跳到主要内容

手动 Chrome 扩展场景

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

创建并运行任务​

  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（管理 → 任务 → 具体任务 → 实时浏览器）观察和控制任务浏览器；仅在任务等待操作员时接受输入。其他扩展或其他任务会被拒绝。扩展若打开另一选项卡，请先激活再采集；切换目标前会检查其身份。密码、创建钱包、协议和注册仍需手动操作。

登录任务和自动探索​

需要引导设置的扩展（例如 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。

代理设置​

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

{
  "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 端口。完成时关闭任务浏览器并删除临时配置档。请使用空测试钱包：场景不会保存凭据或可使用的钱包。

秘密和图像审核​

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

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

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

通过 MCP 重建​

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

证据和限制​

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

请求可用性​

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