Edge Extension 集成指南

01 · Principles

权威在 Host，体验在边缘

传统营销内容审核分散在表格、聊天和邮件中：编辑不知道遵循哪一版规则， 审核意见与实际修改分离，批准后缺少不可变快照。Edge Content 的回答不是再造一个巨型系统，而是明确分工——Host 继续作为记录事实与流程状态的权威系统，受信 Extension 作为面向具体审校任务的边缘工作台，二者只通过受保护 API 和受约束的消息协议协作。

以下六条产品原则是所有接入决策的出发点。它们同时约束 Host 开发者、Extension 开发者和部署方，任何实现细节与原则冲突时，以原则为准。

02 · Architecture

三个 Origin，一条信任链

系统由 Host、静态 Extension 与 Python API Server 三个独立 Origin 构成。浏览器会话由 Host 登录建立，API 设置 HttpOnly、SameSite 会话 Cookie 并签发会话绑定的 CSRF token；Extension 无论以外链还是 iframe 打开，都携带同一 Cookie 调用受保护 API。业务数据从不经过 postMessage——消息只做协调，权威读取永远回到 API。

权威数据归属

所有业务数据只有一个权威来源。Extension 持有的只是按当前身份获取的视图；未保存输入只存在于 Extension 内存中，不写入 Web Storage。

03 · Host Loader

一脚本接入老旧系统

Host Loader 面向难以修改源代码的老旧系统。Host 不需要为每个 Extension 编写 iframe、外链或消息处理代码，只需在公共 layout 或部署响应层注入一个版本固定的脚本。Loader 读取声明式 Host Manifest，只有当前 pathname 命中 placement 时才继续加载同版本的 Bridge 与样式，解析业务 Context，等待目标 DOM，并创建受控的 Extension UI。

注入方式

<script
  defer
  src="https://edge.example.com/sdk/edge-host-loader.v1.js"
  data-manifest="https://edge.example.com/config/legacy-host.json"
></script>

按推荐顺序选择注入位置：公共 layout、应用服务器的模板/响应过滤、 或反向代理对明确 HTML 响应的注入。响应级注入必须限制 Content-Type、路径和上游应用；生产环境同步配置 CSP script-src、style-src、frame-src 与 Extension 的 frame-ancestors。不要使用自动跟随 latest 的远程脚本，也不要通过标签管理器赋予可变第三方代码完整的 Host DOM 权限。

声明式 Manifest

一个 placement 声明页面匹配、Context 定位与解析、DOM 挂载位置、Extension 地址和通用 UI 文本。Manifest 只包含数据，不允许脚本、HTML 或任意事件 callback。

{
  "id": "claims-checklist-workspace",
  "when": { "paths": ["/release.html"] },
  "context": {
    "source": { "kind": "query", "name": "id" },
    "resolve": {
      "pathTemplate": "/api/releases/{value}",
      "responsePath": "context_id"
    }
  },
  "mount": {
    "selector": "#release-content",
    "position": "append",
    "match": "first",
    "waitForMs": 10000
  },
  "extension": {
    "id": "marketing-claims-checklist",
    "url": "https://claims.extensions.example.com/index.html",
    "title": "营销主张检查清单 Extension"
  },
  "display": "standalone",
  "ui": {
    "kind": "确定性规则检查",
    "title": "营销主张检查清单",
    "badge": "No AI",
    "standaloneLabel": "打开检查清单"
  }
}

DOM placement

mount.selector 必须指向真实 DOM 元素；CSS 伪元素不能承载 iframe，会被部署校验拒绝。Loader 使用 MutationObserver 等待延迟出现的 selector，并在 waitForMs 超时后安全失败，不阻塞原 Host。

Context 定位与解析

URL、DOM 和全局变量提供的值都只是 locator，不代表权限。推荐通过 context.resolve 调用受保护 API，把 hostId + legacy locator 映射为不透明 Edge Context ID；解析请求始终使用 credentials: include，API 仍需校验用户、对象权限和 CORS。Manifest 不支持 eval、任意 resolver function 或从 DOM 抓取完整业务正文。

Loader 自动提供的 UI 与协调

• 通用 UI。标题、说明、可选 badge、只携带 Context ID 与 mode 的外链、连接与 dirty 状态、save/refresh 操作，以及由 Bridge 管理的 sandboxed iframe。
• 多 Extension 协调。一个 Extension 保存或评论后，Loader 自动刷新同页其他 Extension，并向 Host 发出 metadata-only CustomEvent。
• 作用域样式。全部 Loader DOM 使用 edge-loader- class 与 data-edge-* 属性，不依赖也不修改 Host 业务样式。

// 请求所有已连接 Extension 从 API 刷新
document.dispatchEvent(
  new CustomEvent("edgehost:refresh-extensions")
);

// Extension 保存或评论后，Loader 发出：
// edgehost:content-changed
// detail 只包含 hostId、placementId、extensionId 和事件类型

04 · Host Bridge

可选的 Bridge 深度集成

能够修改 Host 应用代码时，可以跳过 Loader，直接部署 Host Bridge 获得完整控制能力。Bridge 与 Loader 遵循同一份消息协议和版本契约， 二者可共存：Loader 是默认接入层，Bridge 是深度集成选项。

嵌入 Extension

Host 页面只需一个容器；EdgeHost.mount() 接受 CSS selector、普通容器元素或既有 iframe。

const controller = EdgeHost.mount("#content-review-extension", {
  extensionId: "product-content-review",
  extensionUrl:
    "https://extensions.example.com/product-content-review/index.html",
  contextId: release.extensionContextId,
  title: "商品内容审校",
  minHeight: 480,
  maxHeight: 960,
  onEvent(event) {
    switch (event.type) {
      case "extension.saved":
      case "extension.comment-added":
        refreshReleaseFromApi();
        break;
      case "extension.auth-required":
        redirectToLogin();
        break;
    }
  }
});

Bridge 自动完成：生成只含 Context ID 与 mode 的 iframe URL、设置 sandbox 与 referrer policy、固定精确 Extension Origin、集中校验和分发消息、响应 extension.ready、 限制并应用建议高度、生成 Event ID，并在页面销毁时清理监听器。

独立窗口外链

const standaloneUrl = EdgeHost.createExtensionUrl({
  extensionUrl:
    "https://extensions.example.com/product-content-review/index.html",
  contextId: release.extensionContextId,
  mode: "standalone"
});

// 推荐使用普通链接，隔离 opener：
// <a target="_blank" rel="noopener noreferrer">
// 或由 Bridge 安全打开：
controller.openStandalone();

Host 可接收事件

注意：事件不包含正文、评论内容、Cookie 或 CSRF token。收到 extension.saved 后的正确动作是回到 API 重新读取权威快照，而不是信任消息中的任何业务数据。

05 · Extension Contract

Extension 开发契约

Extension 是一个无构建的静态 HTML/CSS/JavaScript 应用，必须同时支持 standalone 与 embedded 两种模式。URL 输入仅限于不透明 UUID Context ID 和 mode；业务数据一律通过 Extension Runtime 从受保护 API 获取。Manifest 声明请求的 capabilities，但声明从不授予权限——API 仍按当前用户和 Context 校验。

最小接入

页面按 config → Runtime → 业务代码的固定顺序加载：

<script src="./config.js" defer></script>
<script src="/sdk/edge-extension-runtime.v1.js" defer></script>
<script src="./app.js" defer></script>

// config.js
window.MY_EXTENSION_CONFIG = Object.freeze({
  API_BASE: "https://api.example.com",
  HOST_BASE: "https://host.example.com"
});

// app.js — 创建 Runtime；非法 context/mode 抛出带 code 的 RuntimeError
const runtime = EdgeExtension.create({
  extensionId: "product-content-review",
  apiBase: MY_EXTENSION_CONFIG.API_BASE,
  hostBase: MY_EXTENSION_CONFIG.HOST_BASE
});

加载身份与 Context

try {
  const session = await runtime.authenticate();
  const context = await runtime.getContext();
  render(context, session.user);
  runtime.ready();
} catch (error) {
  if (error instanceof EdgeExtension.ApiError && error.status === 401) {
    handleLoggedOut(runtime.loginUrl());
  }
}

Runtime 自动完成：所有请求使用 credentials: "include"； CSRF token 只保存在 Runtime 内存；修改请求自动携带 X-CSRF-Token；禁止请求配置 API Origin 以外的地址；非 2xx 响应统一转换为带 status 与 payload 的 ApiError。未 authenticate() 就发起的修改请求会被直接拒绝。

调用业务 API

const draft = await runtime.request(
  `/api/extension-contexts/${runtime.contextId}/draft`,
  {
    method: "PATCH",
    json: {
      text: editor.value,
      expected_version: currentVersion
    }
  }
);

与 Host 协作

// 接收 Host 操作（消息已经过 Runtime 集中校验）
runtime.on("host.init", () => runtime.requestResize());
runtime.on("host.refresh", refreshFromApi);
runtime.on("host.save-request", saveDraft);

// 上报协调状态；独立窗口模式下安全返回 false
runtime.setDirty(true);
runtime.requestResize();
runtime.notifySaved(draft.version);
runtime.notifyCommentAdded(comment.id);
runtime.notifyAuthRequired();
runtime.reportError("version-conflict", 409);

在 pagehide 时调用 runtime.destroy() 清理消息监听与内存中的 session。可恢复错误（401、403、409、网络失败） 必须保留用户输入；viewer 等只读身份在 UI 与 API 两层同时被拒绝。

06 · Protocol

metadata-only 消息协议

Host 与 Extension 之间只交换协调信号，不交换业务数据。所有消息使用统一信封， 由 Host Bridge 与 Extension Runtime 在两端集中校验——业务代码从不直接处理原始 postMessage。

{
  "channel": "edge-extension",
  "protocolVersion": "1.0",
  "type": "extension.saved",
  "contextId": "opaque-context-id",
  "eventId": "unique-event-id",
  "payload": {}
}

双方必须校验：

• 精确 event.origin 与精确 event.source；
• channel 与 protocolVersion 完全匹配；
• 当前 Context ID 与非空 Event ID；
• 已知消息类型及其 payload 结构。

07 · Security & Versioning

安全要求与版本策略

Integration Kit 是内部、受信 Extension 的稳定接入层，而不是绕过后端集成的注入工具。 以下要求对 Host、Extension 与部署方同时生效：

• 固定版本自托管。Loader、Bridge 与 Runtime 必须自托管或使用固定、可审计、带完整性校验的版本；不发布会被原地替换的 latest URL。
• Manifest 只含数据。Host Manifest 是受信部署配置，只允许 Schema 内的声明数据，不允许脚本、HTML 或 callback。
• 精确 Origin。不允许 postMessage(..., "*")；Host 与 Extension 各自从配置计算对方的精确 Origin；CORS 使用精确 Origin 且只允许需要的方法与请求头。
• 定位不等于授权。Context ID 仅用于定位，每次 API 请求仍做角色与对象级权限校验。
• 敏感数据不出边界。不在 URL 或消息中放正文、身份、权限、Cookie、CSRF 或 AI 结果；Extension 不使用 Web Storage 或 document.cookie 保存敏感信息，业务代码不访问父页面 DOM。
• 生产环境基线。HTTPS、HSTS、CSP、frame-src/frame-ancestors、Secure Cookie 与最小 sandbox 权限缺一不可；AI Provider 密钥只存在于服务端。

版本策略

Bridge 在 extension.ready 握手时校验 Extension ID、Runtime 版本存在、protocolVersion 完全匹配，以及 Context ID 与当前挂载一致。