# 手动 Chrome 扩展场景 {/* #manual-chrome-extension-scenarios */}

手动录制作为管理采集任务运行：**Desktop → Web Extension**（桌面 → Web 扩展）。其内部环境为 `WebExtension`；采集元数据和公共 MCP 使用 `web-extension`。代理下载选定的 Chrome 网上应用店扩展，并使用该扩展和 Reconstruct 采集扩展打开一次性 Chromium 配置档。操作员导航；Reconstruct 将屏幕和观察到的转换保存为 [`reconstruct.scene.v1`](/docs/zh/data-format)。

## 创建并运行任务 {/* #create-and-run-a-job */}

1. 在 Admin → Jobs → Create（管理 → 任务 → 创建）中选择 **Desktop → Web Extension**（桌面 → Web 扩展）。如果只需扩展，请取消选择 Web。移动环境仍为 Web、iOS 和 Android。
2. 在 Environment Settings → Web Extension（环境设置 → Web 扩展）中粘贴所选 Chrome 网上应用店链接。不能输入本地扩展目录或个人浏览器配置档。
3. 将任务加入队列。已启用且分配至 **Desktop / Web Extension**（桌面 / Web 扩展）的 Capture Agent 会领取任务。Web 和 Web 扩展工作进程无法领取彼此的任务。
4. 代理通过 Google 更新服务下载签名 CRX3，并在解压至私密任务目录前验证所选扩展 ID 和发布者签名。软件包以解压方式加载时仍保留商店 ID。采集版本元数据中的 `browserExtension` 包含已验证 ID、本地化名称、包版本和 SHA-256；目录显示名称来自该包。使用前会检查归档路径、文件数和展开大小。
5. Chromium 会打开扩展自己的引导选项卡；否则使用其声明的选项页或操作弹窗。没有 UI 入口的扩展会失败。
6. 从浏览器扩展菜单打开 **Reconstruct Agent Browser Bridge**。其弹窗显示当前任务 ID 和已保存屏幕数。每个屏幕后使用 **Capture screen**（采集屏幕）。在此使用 **Pause**（暂停）、**Resume**（继续）和 **Finish recording**（结束录制）。

无需启动独立录制器 CLI 或额外录制 MCP。控制项绑定当前任务和私密本地会话令牌，不接受字段值、任意标签或来源 URL。管理员也可通过 Admin → Jobs → job → **Live browser**（管理 → 任务 → 具体任务 → 实时浏览器）观察和控制任务浏览器；仅在任务等待操作员时接受输入。其他扩展或其他任务会被拒绝。扩展若打开另一选项卡，请先激活再采集；切换目标前会检查其身份。密码、创建钱包、协议和注册仍需手动操作。

## 登录任务和自动探索 {/* #sign-in-jobs-and-automatic-exploration */}

需要引导设置的扩展（例如 MetaMask 创建钱包）可半自动录制。在 Environment Settings → Web Extension（环境设置 → Web 扩展）中，将 **Sign-in**（登录）设为 **Operator registers**（操作员注册）或 **Operator signs in**（操作员登录）。

1. 任务等待操作员。在 Admin → Jobs → job → **Live browser**（管理 → 任务 → 具体任务 → 实时浏览器）或任务浏览器本身完成引导。使用 **Capture screen**（采集屏幕）保存屏幕；密码和恢复助记词屏幕绝不会保存。
2. 选择 **Finish sign-in**（完成登录，控制台）、**Continue**（继续，管理界面）或 **Finish sign-in and explore**（完成登录并探索，Reconstruct 弹窗）。
3. Reconstruct 随后访问扩展的弹窗、选项页、侧面板页面及导航控件所指向的路由，每条路由保存一个屏幕。它绝不会点击可能执行发送、签名、确认、显示秘密、导出、锁定、删除或创建的控件。
4. 如果扩展自行锁定，任务会以 **Signed out**（已退出）状态等待，直至操作员解锁并再次选择 **Finish sign-in**（完成登录）。没有剩余路由或达到页面限制后，录制结束并上传审核。

Web 任务具有相同的 **Sign-in**（登录）设置：登录屏幕保存为阶段，抓取跳过退出链接，并在会话结束时暂停。验证码、短信代码和接受条款始终由操作员处理。详情参阅 `backend/docs/operator-sign-in.md`。

## 代理设置 {/* #agent-setup */}

在 `backend/agent-browser-extensions` 中运行 `yarn nx run chrome:build`，构建匹配的浏览器适配器。主机需要 Node.js 24+、Python 3 和支持扩展的 Chromium 构建。通过已忽略的本地设置或环境变量配置现有 Capture Agent：

```json
{
  "Agent": {
    "Id": "extension-worker",
    "ApiUrl": "https://internal-admin-api.example",
    "ChromiumPath": "/Applications/Chromium.app/Contents/MacOS/Chromium",
    "ExtensionDir": "/checkout/backend/agent-browser-extensions/chrome"
  },
  "WebExtension": {
    "RecorderDirectory": "/checkout/backend/tools/manual-recorder",
    "NodePath": "node",
    "PythonPath": "python3"
  }
}
```

通过秘密配置提供现有 `ApiTokens:Agent` 凭据。现有 Kestrel Web 监听器必须绑定环回地址。使用 `extension serve` 启动 Capture Agent 二进制文件，然后在管理界面将其代理记录分配至 **Desktop / Web Extension**（桌面 / Web 扩展）。每种主机模式拥有自己的监听器和工作锁；不要在同一端点启动两个工作进程。远程工作进程需要受管理的隔离浏览器主机，并明确声明 `WebExtension:ManagedBrowserIsolated`，因为扩展会执行自己的网络和后台代码。该标记本身不会创建隔离。现有的显式 `Agent:AllowHttpApi` 设置适用于环回开发 API。

工作进程负责领取、心跳、取消和上传重试。其内部 Node 子进程使用私密进程管道，不使用调试 TCP 端口。完成时关闭任务浏览器并删除临时配置档。请使用空测试钱包：场景不会保存凭据或可使用的钱包。

## 秘密和图像审核 {/* #secrets-and-image-review */}

输入密码、恢复助记词、密钥或代码前先暂停。离开敏感屏幕后恢复。受保护文本屏幕会安全拒绝采集，并形成观察缺口。截图前会遮罩可编辑控件及其后代；字段值不会读入 Scene。若受保护状态、遮罩、导航或文档内容在采集期间变化，前后检查会拒绝采集。

Canvas 和其他不透明像素在**私密审核媒体**中仍然可见。DOM 检查不能证明其中没有秘密。检查和遮罩在一次隔离世界求值中同步执行；截图时保留 JavaScript 启用，以便渲染原生 canvas 内容。

**Finish recording**（结束录制）会自动打包并上传为未发布采集。每个检查点拥有页面、Scene 和截图。场景索引引用页面，不复制页面文字。在管理界面的 **Hide personal data**（隐藏个人数据）中检查每张截图，模糊敏感区域或删除不安全媒体，并在审核后发布。遮盖还会清除覆盖的 Scene 文本、无障碍名称、重复值和媒体引用。单独存储的原始媒体需要单独审核。录制控制不能发布或返回原始图像。

## 通过 MCP 重建 {/* #reconstruction-through-mcp */}

审核发布后，代理通过普通 Capture MCP 目录发现该版本。使用 `get_scenario_scene` 加载帧、配置和转换；它们由当前归属于页面的数据组装，包括管理员遮盖。使用普通的已发布页面工具获取已批准图像。对照每个必需的已采集屏幕和配置验证重建；仅工具调用成功不能证明视觉还原度。

## 证据和限制 {/* #evidence-and-limits */}

检查点是静态观察。在导航、菜单、模态和其他展开操作之后，以及每个必需视口下采集。相邻观察衡量变化/未变化结果，不证明自动执行了点击。暂停和阻止期间形成明确缺口。此模式不会悄悄采集每次点击、重放注册、采集原生操作系统权限对话框或从静态图像推断动画。秘密步骤仍由人工执行，且不会出现在已发布场景中。任务页面限制约束检查点（自动选择默认为 200）；Scene 节点预算为每任务 100,000。任务时限和元素限制也适用。

## 请求可用性 {/* #request-availability */}

在 **Admin → Requests → Job defaults → Request submissions**（管理 → 请求 → 任务默认值 → 请求提交）中配置允许的产品类型/环境组合。默认值为 Desktop/Web、Desktop/Web Extension 和 Mobile/Web。**Allow new requests**（允许新请求）关闭或重新开放所有新提交；关闭提交时保存仍保留所选组合。现有请求和已发布采集继续可用。相同持久化策略适用于平台 API 和经过身份验证的 MCP，包括表单选项过期的客户端。关闭提交时，请求选项端点不返回平台。目录产品类型/环境选择器仅显示该产品已采集环境；请求可用性不会隐藏已发布的目录证据。