Google Chrome 扩展管理手册

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

1. 核心原则

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

2. 主要使用流程

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

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

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

主流程 B：加载本地扩展

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

主流程 C：更新扩展

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

主流程 D：设置快捷键

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

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

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

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

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

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

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

chrome://extensions/ → 开启 Developer mode (1890, 180)
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/ 时有效；窗口尺寸、系统缩放或浏览器缩放改变时会漂移。

元素	坐标 / 位置	说明
Developer mode 开关	`(1890, 180)`	右上角，需先开启才能使用开发者按钮
Load unpacked	`(100, 250)`	左上角，Developer mode 开启后可见
Update	`(450, 250)`	左上角，Developer mode 开启后可见
Pack extension	左上角	Developer mode 开启后可见，点击弹出打包对话框

4.3 反馈映射

动作	预期反馈	含义	下一步
搜索框输入关键词	扩展列表实时过滤	筛选生效	找到目标扩展后操作
点击插件开关	蓝色 ↔ 灰色切换	开启 / 关闭扩展	按需继续
点击 Details	进入详情页	可查版本、权限、无痕模式	查看后返回主页
点击 Remove	弹出确认框	等待确认后卸载	确认弹窗完成卸载
开启 Developer mode	左上角出现三个开发者按钮	开发者功能解锁	可使用 Load unpacked / Update
点击 Load unpacked	弹出文件夹选择器	等待选择本地目录	选中扩展根目录后确认
点击 Update	左下角出现 `Updating...`	正在重新加载所有扩展	等待提示消失
`browser-assist-status` 返回 `connected: true`	附带 `extensionVersion` / `browserName` / `lastSeenAt`	扩展已成功连接 daemon	可发起 locate 请求
`browser-assist-locate` 返回结果	含 `matches` / `mapped.screenCandidates`	元素定位完成	取 `screenPoint` 执行 click

5. 快捷键

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

6. 常见失败与排障

排障优先顺序

.\windows-launcher.ps1 daemon start
.\windows-launcher.ps1 browser-assist-status
确认扩展已加载且开关开启
确认浏览器是前台窗口
确认当前 URL 为目标页
点 Update 刷新扩展
重新执行 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：

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

执行要求：

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

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

chrome-extensions