Chrome Extensions

Google Chrome 扩展管理手册

适用：Windows 桌面端 Chrome | 更新：2026-03-14

1. 核心原则

1. 页面必须是 chrome://extensions/，浏览器保持最大化
2. Browser Assist Locator 只负责定位，不执行点击 / 输入 / 滚动
3. 最终坐标映射由 daemon 完成，真实动作由 agent-computer 执行
4. 扩展代码更新后表现异常，优先点 Update
5. 排障顺序：daemon → status → 扩展加载 → 前台浏览器 → locate

2. 主要使用流程

以下流程覆盖该应用的大部分实际使用场景。

主流程 A：管理已安装扩展

1. 访问 chrome://extensions/
2. 搜索框输入关键词，实时过滤扩展列表
3. 点击插件开关启停（蓝色=开启，灰色=关闭）
4. 需查详情时点击 Details（版本、权限、无痕模式）
5. 需卸载时点击 Remove → 确认弹窗

主流程 B：加载本地扩展

1. 访问 chrome://extensions/
2. 开启右上角 Developer mode (1890, 180)
3. 点击 Load unpacked (100, 250) → 弹出文件夹选择器
4. 选中扩展根目录 → 点击"选择文件夹"

主流程 C：更新扩展

1. 确认 chrome://extensions/ 已开启 Developer mode
2. 点击 Update (450, 250)
3. 等待左下角 Updating... 消失，更新完成

主流程 D：设置快捷键

1. 访问 chrome://extensions/
2. 点击左侧导航 Keyboard shortcuts
3. 找到目标扩展，点击 Not set
4. 按下目标组合键完成绑定

主流程 E：Browser Assist Locator 完整使用流程

第 1 步：启动 daemon 并确认状态

.\windows-launcher.ps1 daemon start
.\windows-launcher.ps1 browser-assist-status

daemon 正常但扩展未连接时返回 "connected": false，属于正常，继续加载扩展即可。

第 2 步：加载扩展（二选一）

方法 A — 直接加载源码目录：

1. chrome://extensions/ → 开启 Developer mode (1890, 180)
2. Load unpacked (100, 250) → 选择 extensions/browser-assist-locator → 选择文件夹

方法 B — 先打包再加载：

.\scripts\package_browser_assist_extension.ps1

产物位于 artifacts/browser-assist-locator-package/browser-assist-locator，再按方法 A 流程加载该目录。

第 3 步：确认连接成功

.\windows-launcher.ps1 browser-assist-status

成功时返回 connected: true + extensionVersion / browserName / lastSeenAt。

第 4 步：打开目标页并保持前台

.\windows-launcher.ps1 browser-open-url --url "<目标 URL>"

Browser Assist v1 会校验前台窗口是否为浏览器，以及 URL / 标题是否一致，执行 locate 前浏览器需保持前台。

第 5 步：发起 locate 请求

.\windows-launcher.ps1 browser-assist-locate --input-file .\docs\examples\browser-assist-request.json

请求体示例：

{
  "query": {
    "text": "收藏",
    "role": "button",
    "hint": "当前职位详情区域里的收藏按钮",
    "selectorHint": null,
    "index": 0
  },
  "options": {
    "visibleOnly": true,
    "interactiveOnly": true,
    "maxCandidates": 5
  }
}

第 6 步：读取返回结果并执行点击

返回结构关键字段：

• matches[].rect — 网页视口内 DOM 几何框
• matches[].clickablePoint — 网页内部点击点
• browser.contentLeftOnScreen / contentTopOnScreen — 内容区锚点
• mapped.screenCandidates[].screenPoint — daemon 映射后的桌面绝对坐标（用这个）

.\windows-launcher.ps1 click --x <screen_x> --y <screen_y>

第 7 步：截图校验

.\windows-launcher.ps1 capture-grid --grid-size 50

主流程 F：结束 Browser Assist Locator 使用

• 保留扩展：回到扩展页关闭开关即可
• 彻底卸载：扩展页点 Remove
• 停止后端：.\windows-launcher.ps1 daemon stop（daemon 停止后扩展仍存在但处于未连接状态）

3. 稳定规则

3.1 路由 / 页面 / 模块

• 扩展管理主页：chrome://extensions/
• 快捷键配置页：chrome://extensions/shortcuts（或从主页左侧导航 Keyboard shortcuts 进入）
• Chrome 网上应用店：主页左下角 Chrome Web Store 链接

3.2 参数 / 状态 / 业务语义

• Developer mode 开启后，左上角才出现 Load unpacked / Pack extension / Update 三个按钮
• 插件开关：蓝色 = 开启；灰色 = 关闭
• browser-assist-status 返回 "connected": false 不代表异常，仅表示扩展尚未加载
• browser-assist-status 返回 connected: true 时，同步返回 extensionVersion / browserName / lastSeenAt
• daemon 停止后，扩展仍然存在但处于未连接状态

3.3 Browser Assist Locator 职责边界

• 负责：查找网页元素，返回 page / viewport / browser / matches，返回元素 rect 和 clickablePoint
• 不负责：点击、输入、滚动、浏览器自动化执行

链路总结：

扩展页加载 → 扩展连接 daemon → status 显示 connected:true
→ locate 返回 raw+mapped → agent-computer click 执行真实动作

扩展负责定位，daemon 负责映射，computer 负责执行。

3.4 判断标准

• 直接通过：browser-assist-status 返回 connected: true → 可直接发起 locate
• 条件通过：返回 connected: false → 先完成扩展加载流程再重新确认状态
• 直接跳过：不需要元素定位时，无需启动 daemon 或加载扩展

4. UI / 坐标 / 页面映射

4.1 页面区域

• 顶部搜索框：实时过滤已安装扩展列表
• 右上角 Developer mode 开关：开启后解锁 Load unpacked / Pack extension / Update
• 左上角开发者按钮区：Load unpacked · Pack extension · Update（仅 Developer mode 开启后可见）
• 扩展卡片区：每张卡片含插件开关、Details、Remove
• 左侧导航：Keyboard shortcuts 入口
• 左下角：Chrome Web Store 链接

4.2 关键控件 / 坐标

坐标在浏览器最大化 + chrome://extensions/ 时有效；窗口尺寸、系统缩放或浏览器缩放改变时会漂移。

4.3 反馈映射

5. 快捷键

暂无（Chrome 扩展管理页本身无专属快捷键；扩展的快捷键在 Keyboard shortcuts 页配置）

6. 常见失败与排障

排障优先顺序

1. .\windows-launcher.ps1 daemon start
2. .\windows-launcher.ps1 browser-assist-status
3. 确认扩展已加载且开关开启
4. 确认浏览器是前台窗口
5. 确认当前 URL 为目标页
6. 点 Update 刷新扩展
7. 重新执行 browser-assist-locate

现象：browser-assist-status 返回 connected: false

• 可能原因：
  • 扩展尚未加载到 Chrome
  • 扩展已加载但开关处于关闭状态
• 优先检查：
  1. chrome://extensions/ 中是否存在 Browser Assist Locator 且开关为蓝色
  2. daemon 是否已正常启动
• 处理方式：
  • 按主流程 E 第 2 步加载扩展，或打开扩展开关；daemon 未启动则先执行 daemon start

现象：扩展加载后行为异常 / 功能不符预期

• 可能原因：
  • 本地扩展代码已更新，但 Chrome 仍加载旧版本
• 优先检查：
  1. 是否刚修改过扩展源码
• 处理方式：
  • chrome://extensions/ → 确认 Developer mode 开启 → 点 Update (450, 250) → 等待 Updating... 消失

现象：locate 请求报错 / 无匹配结果

• 可能原因：
  • 浏览器不在前台，或当前页 URL / 标题与目标不一致
  • 目标元素不可见或不可交互
• 优先检查：
  1. 浏览器窗口是否为当前前台窗口
  2. 当前页 URL 是否为目标页
  3. 请求体中 visibleOnly / interactiveOnly 是否过滤掉了目标元素
• 处理方式：
  • 执行 browser-open-url 将浏览器置于前台；检查请求体中的筛选条件是否过严

现象：坐标点击偏移 / 未命中目标控件

• 可能原因：
  • 浏览器未最大化，或系统缩放 / 浏览器缩放发生变化
• 优先检查：
  1. 浏览器是否处于最大化状态
  2. 系统缩放比例是否变化
• 处理方式：
  • 重新最大化浏览器；若仍偏移，以 locate 返回的 mapped.screenCandidates[].screenPoint 为准，不使用硬编码坐标

7. Self-Improving

当执行过程中出现以下情况时，需要追加记录到 references/self-improving.md：

• 原有流程无法覆盖实际高频使用路径
• 排障过程中确认了新的失败模式
• 发现更稳定、更高效的执行方法
• 发现了值得沉淀的新事实

执行要求：

1. 禁止直接修改本 SKILL.md 的正文内容
2. 只允许把新增内容追加写入 references/self-improving.md
3. 只追加，不覆盖、不删除历史记录
4. 这里只记录观察到的事实，不记录推断，不记录猜测

写法请严格使用 references/self-improving-template.md 中提供的模板。