docs: 更新文档

2026-06-23 00:35:51 +00:00 · 2026-04-04 09:57:41 +08:00
parent a67b4a40b0
commit fc9faa2af2
2 changed files with 184 additions and 345 deletions
--- a/docs/features/claude-in-chrome-mcp.md
+++ b/docs/features/claude-in-chrome-mcp.md
@@ -1,243 +1,137 @@
-# Claude in Chrome MCP — 恢复计划
+# Claude in Chrome — 用户操作指南

-更新时间：2026-04-03
-参考项目：`E:\源码\claude-code-source-main\claude-code-source-main`
+## 1. 功能简介

-## 1. 功能概述
+Claude in Chrome 让 Claude Code 直接控制你的 Chrome 浏览器。你可以用自然语言让 Claude 帮你：

-Claude in Chrome 让 Claude Code CLI 通过 MCP 协议控制用户的 Chrome 浏览器：导航网页、填写表单、截图、录制 GIF、读取 DOM、执行 JS、监控网络请求和控制台日志。
+- 打开网页、导航、前进后退
+- 填写表单、上传图片
+- 截图、录制 GIF
+- 读取页面内容（DOM、纯文本）
+- 执行 JavaScript
+- 监控网络请求和控制台日志
+- 管理标签页

-通信方式有两种：
- **本地 Socket**：Chrome 扩展通过 Native Messaging Host 与 CLI 建立 Unix socket 连接
- **Bridge WebSocket**：通过 Anthropic 的 bridge 服务中转，支持远程浏览器
+## 2. 前置条件

-## 2. 完整加载链路
+| 条件 | 说明 |
+|------|------|
+| Claude Code 订阅 | 需要 Claude Pro、Max 或 Team 订阅，浏览器插件功能不向免费用户开放 |
+| Chrome 浏览器 | 需已安装 Google Chrome |
+| Claude in Chrome 扩展 | 从 Chrome Web Store 安装（`claude.ai/chrome`） |
+| Claude Code CLI | 已通过 `bun run dev` 或构建产物运行 |

-```
-CLI 启动
-  │
-  ▼
-src/main.tsx:1003
-  .option('--chrome', 'Enable Claude in Chrome integration')
-  │
-  ▼
-src/main.tsx:1522-1527
-  setChromeFlagOverride(chromeOpts.chrome)
-  │
-  ▼
-src/utils/claudeInChrome/setup.ts
-  shouldEnableClaudeInChrome()
-  ├── --chrome flag → true
-  ├── --no-chrome flag → false
-  ├── 非交互模式 → false
-  ├── 环境变量 CLAUDE_CODE_DISABLE_CHROME → false
-  ├── 配置 claudeInChromeDefaultEnabled → true/false
-  └── Chrome 扩展已安装 + GrowthBook tengu_chrome_auto_enable → auto
-  │
-  ▼
-src/utils/claudeInChrome/setup.ts
-  setupClaudeInChrome()
-  ├── 生成 MCP server 配置
-  └── 返回 mcpConfig + allowedTools
-  │
-  ▼
-src/utils/claudeInChrome/mcpServer.ts
-  import { createClaudeForChromeMcpServer } from '@ant/claude-for-chrome-mcp'
-  │
-  ▼
-packages/@ant/claude-for-chrome-mcp/src/index.ts  ← 当前是 STUB
-  export function createClaudeForChromeMcpServer() { return null }
-  export const BROWSER_TOOLS = []
+## 3. 启用方式
+
+### Dev 模式
+
+```bash
+bun run dev -- --chrome
 ```

-## 3. 阻塞点清单
+启动后 Claude 会自动检测 Chrome 扩展是否已安装，并注册浏览器控制工具。

-| # | 阻塞点 | 位置 | 状态 |
-|---|--------|------|------|
-| ① | `@ant/claude-for-chrome-mcp` 是 stub | `packages/@ant/claude-for-chrome-mcp/src/index.ts` | **6 行空壳，返回 null** |
-| ② | 缺少完整实现（7 个文件，3038 行） | `packages/@ant/claude-for-chrome-mcp/src/` | 只有 1 个 stub 文件 |
+### 构建产物

-**不需要任何 feature flag** — `/chrome` 命令无条件注册在 `src/commands.ts:264`。
+```bash
+node dist/cli.js --chrome
+```

-**不需要改 `src/` 下任何文件** — 以下文件全部与参考项目 0 行差异：
- `src/utils/claudeInChrome/setup.ts`
- `src/utils/claudeInChrome/mcpServer.ts`
- `src/utils/claudeInChrome/common.ts`
- `src/utils/claudeInChrome/chromeNativeHost.ts`
- `src/utils/claudeInChrome/prompt.ts`
- `src/utils/claudeInChrome/setupPortable.ts`
- `src/utils/claudeInChrome/toolRendering.tsx`
- `src/commands/chrome/index.ts`
- `src/commands/chrome/chrome.tsx`（仅 sourcemap 差异）
- `src/skills/bundled/claudeInChrome.ts`
+### 禁用

-## 4. 参考项目完整实现清单
+```bash
+bun run dev -- --no-chrome
+```

-参考项目路径：`deps/@ant/claude-for-chrome-mcp/src/`
+或在 REPL 中通过 `/chrome` 命令切换启用/禁用状态。

-| 文件 | 行数 | 职责 |
-|------|------|------|
-| `index.ts` | 15 | 导出入口：`createBridgeClient`、`BROWSER_TOOLS`、`createChromeSocketClient`、`createClaudeForChromeMcpServer`、`localPlatformLabel` + 类型导出 |
-| `types.ts` | 134 | 类型定义：`Logger`、`PermissionMode`、`BridgeConfig`、`ChromeExtensionInfo`、`ClaudeForChromeContext`、`SocketClient`、`BridgePermissionRequest/Response`、`PermissionOverrides` |
-| `browserTools.ts` | 546 | 17 个浏览器工具定义（MCP tool schema） |
-| `mcpServer.ts` | 96 | MCP Server 创建：注册 `ListTools`/`CallTool` handler，选择 socket/bridge 传输 |
-| `mcpSocketClient.ts` | 493 | Unix Socket 客户端：连接 Chrome Native Messaging Host，JSON-RPC 通信 |
-| `mcpSocketPool.ts` | 327 | Socket 连接池：多 Chrome profile 支持，按 tabId 路由 |
-| `bridgeClient.ts` | 1126 | Bridge WebSocket 客户端：连接 Anthropic bridge 服务，扩展发现、设备配对、权限管理 |
-| `toolCalls.ts` | 301 | 工具调用路由：连接状态处理、结果转换、权限模式切换、浏览器切换 |
+### 通过配置默认启用

-### 17 个浏览器工具
+在 Claude Code 设置中将 `claudeInChromeDefaultEnabled` 设为 `true`，以后启动无需加 `--chrome` 参数。

-| 工具名 | 功能 |
-|--------|------|
-| `javascript_tool` | 在页面上下文执行 JavaScript |
-| `read_page` | 获取页面可访问性树（DOM） |
-| `find` | 自然语言搜索页面元素 |
+## 4. 使用流程
+
+1. **启动 CLI** — 加 `--chrome` 参数启动 Claude Code
+2. **确认连接** — REPL 中输入 `/chrome`，查看扩展状态是否显示 "Installed / Connected"
+3. **开始对话** — 正常与 Claude 对话，当需要操作浏览器时直接说，例如：
+   - "打开 https://example.com 并截图"
+   - "在当前页面搜索关键词 xxx"
+   - "填写登录表单，用户名 admin"
+   - "帮我录制当前操作的 GIF"
+4. **权限审批** — 首次执行浏览器操作时，Claude 会请求你的确认
+5. **操作完成** — Claude 完成操作后会返回结果（截图、文本、执行结果等）
+
+## 5. 可用操作
+
+### 页面交互
+
+| 操作 | 说明 |
+|------|------|
+| `navigate` | 导航到指定 URL，或前进/后退 |
+| `computer` | 鼠标点击、移动、拖拽、键盘输入、截图等（13 种 action） |
 | `form_input` | 填写表单字段 |
-| `computer` | 鼠标键盘操作 + 截图（13 种 action） |
-| `navigate` | URL 导航 / 前进后退 |
-| `resize_window` | 调整浏览器窗口尺寸 |
-| `gif_creator` | GIF 录制和导出 |
-| `upload_image` | 图片上传到文件输入框或拖拽区域 |
-| `get_page_text` | 提取页面纯文本 |
+| `upload_image` | 上传图片到文件输入框或拖拽区域 |
+| `javascript_tool` | 在页面上下文执行 JavaScript |
+
+### 页面读取
+
+| 操作 | 说明 |
+|------|------|
+| `read_page` | 获取页面可访问性树（DOM 结构） |
+| `get_page_text` | 提取页面纯文本内容 |
+| `find` | 用自然语言搜索页面元素 |
+
+### 标签页管理
+
+| 操作 | 说明 |
+|------|------|
 | `tabs_context_mcp` | 获取当前标签组信息 |
 | `tabs_create_mcp` | 创建新标签页 |
-| `update_plan` | 向用户提交操作计划供审批 |
+
+### 监控与调试
+
+| 操作 | 说明 |
+|------|------|
 | `read_console_messages` | 读取浏览器控制台日志 |
-| `read_network_requests` | 读取网络请求 |
+| `read_network_requests` | 读取网络请求记录 |
+
+### 其他
+
+| 操作 | 说明 |
+|------|------|
+| `resize_window` | 调整浏览器窗口尺寸 |
+| `gif_creator` | 录制 GIF 并导出 |
 | `shortcuts_list` | 列出可用快捷方式 |
 | `shortcuts_execute` | 执行快捷方式 |
-| `switch_browser` | 切换到其他 Chrome 浏览器（仅 bridge 模式） |
+| `update_plan` | 向你提交操作计划供审批 |
+| `switch_browser` | 切换到其他 Chrome 浏览器（仅 Bridge 模式） |

-### 外部依赖
+## 6. 通信模式

-| 依赖 | 用途 | 我们项目是否已有 |
-|------|------|----------------|
-| `ws` | WebSocket 客户端（bridge 模式） | ✅ 有 |
-| `@modelcontextprotocol/sdk` | MCP Server + 类型 | ✅ 有 |
-| `fs`/`net`/`os`/`path` | Node.js 内置 | ✅ |
+Claude in Chrome 支持两种与浏览器通信的方式：

-## 5. 修复步骤
+### 本地 Socket（默认）

-### 步骤 1：复制完整实现到 stub 包目录
+Chrome 扩展通过 Native Messaging Host 与 CLI 建立 Unix socket 连接。适用于本地开发，无需额外配置。

-```bash
-# 从参考项目复制 7 个文件（覆盖现有的 1 个 stub）
-cp "E:/源码/claude-code-source-main/claude-code-source-main/deps/@ant/claude-for-chrome-mcp/src/"*.ts \
-   "E:/源码/Claude-code-bast/packages/@ant/claude-for-chrome-mcp/src/"
-```
+### Bridge WebSocket

-复制后 `packages/@ant/claude-for-chrome-mcp/src/` 应包含 8 个文件：
+通过 Anthropic 的 bridge 服务中转，支持远程操控浏览器。需要 claude.ai OAuth 登录。

-```
-packages/@ant/claude-for-chrome-mcp/src/
-├── index.ts           ← 覆盖 stub（15 行，导出入口）
-├── types.ts           ← 新增（134 行）
-├── browserTools.ts    ← 新增（546 行）
-├── mcpServer.ts       ← 新增（96 行）
-├── mcpSocketClient.ts ← 新增（493 行）
-├── mcpSocketPool.ts   ← 新增（327 行）
-├── bridgeClient.ts    ← 新增（1126 行）
-└── toolCalls.ts       ← 新增（301 行）
-```
+## 7. 常见问题

-### 步骤 2：验证构建
+### 扩展显示未安装

-```bash
-bun run build
-```
+确认已从 Chrome Web Store 安装 "Claude in Chrome" 扩展，安装后重启浏览器。

-不需要改 `scripts/dev.ts` 或 `build.ts`（无 feature flag）。
+### 工具未出现在工具列表

-### 步骤 3：功能验证
+检查启动时是否加了 `--chrome` 参数，或通过 `/chrome` 命令确认状态。

-```bash
-# 启动（手动启用 chrome）
-bun run dev -- --chrome
+### 连接超时

-# 在 REPL 中：
-# 1. /chrome 命令应显示 Chrome 设置菜单
-# 2. 如果 Chrome 扩展已安装 → 状态显示 "Enabled"
-# 3. 如果未安装 → 提示安装扩展链接
-```
+确保 Chrome 浏览器正在运行且扩展已启用。Native Messaging Host 在扩展安装时自动注册，如果重装过扩展需要重启浏览器。

-## 6. 验证测试项
+### 不使用 Chrome 功能时

-### 6.1 构建验证
-
-| 测试项 | 预期结果 | 验证命令 |
-|--------|---------|---------|
-| build 成功 | 无报错 | `bun run build` |
-| BROWSER_TOOLS 非空 | 产物中包含 17 个工具定义 | `grep "javascript_tool" dist/*.js` |
-| createClaudeForChromeMcpServer 非 null | 产物中包含 MCP Server 创建逻辑 | `grep "ListToolsRequestSchema" dist/*.js` |
-| Bridge WebSocket 逻辑在产物中 | 包含 bridge 连接代码 | `grep "bridge.claudeusercontent.com" dist/*.js` |
-
-### 6.2 命令注册验证
-
-| 测试项 | 预期结果 |
-|--------|---------|
-| `/chrome` 命令可见 | REPL 中输入 `/chrome` 显示设置菜单 |
-| `--chrome` 参数可用 | `bun run dev -- --chrome` 不报错 |
-| `--no-chrome` 参数可用 | `bun run dev -- --no-chrome` 不报错 |
-
-### 6.3 MCP Server 验证（需要 Chrome 扩展）
-
-| 测试项 | 预期结果 |
-|--------|---------|
-| Chrome 扩展检测 | 已安装扩展时 `/chrome` 显示 "Extension: Installed" |
-| Socket 连接 | 扩展连接后 MCP tools 可用 |
-| BROWSER_TOOLS 注册 | `tabs_context_mcp` 等 17 个工具在 MCP 工具列表中可见 |
-
-### 6.4 工具功能验证（需要 Chrome 扩展 + 连接）
-
-| 测试项 | 预期结果 |
-|--------|---------|
-| `tabs_context_mcp` | 返回当前标签组信息 |
-| `navigate` | 能导航到指定 URL |
-| `computer` + `screenshot` | 返回页面截图 |
-| `read_page` | 返回 DOM 可访问性树 |
-| `javascript_tool` | 执行 JS 并返回结果 |
-
-### 6.5 不影响现有功能
-
-| 测试项 | 预期结果 |
-|--------|---------|
-| 不带 `--chrome` 启动 | 正常运行，无 chrome 相关报错 |
-| `/voice` 命令 | 不受影响 |
-| `/schedule` 命令 | 不受影响 |
-| `bun test` | 现有测试全部通过 |
-
-## 7. 改动总结
-
-| 操作 | 文件 | 说明 |
-|------|------|------|
-| 覆盖 stub | `packages/@ant/claude-for-chrome-mcp/src/index.ts` | 6 行 stub → 15 行完整导出 |
-| 新增 | `packages/@ant/claude-for-chrome-mcp/src/types.ts` | 134 行类型定义 |
-| 新增 | `packages/@ant/claude-for-chrome-mcp/src/browserTools.ts` | 546 行，17 个工具定义 |
-| 新增 | `packages/@ant/claude-for-chrome-mcp/src/mcpServer.ts` | 96 行 MCP Server |
-| 新增 | `packages/@ant/claude-for-chrome-mcp/src/mcpSocketClient.ts` | 493 行 Socket 客户端 |
-| 新增 | `packages/@ant/claude-for-chrome-mcp/src/mcpSocketPool.ts` | 327 行连接池 |
-| 新增 | `packages/@ant/claude-for-chrome-mcp/src/bridgeClient.ts` | 1126 行 Bridge 客户端 |
-| 新增 | `packages/@ant/claude-for-chrome-mcp/src/toolCalls.ts` | 301 行工具调用路由 |
-
-**不改动**：`src/` 下所有文件（已与参考项目一致）、`scripts/dev.ts`、`build.ts`。
-
-## 8. 运行时依赖
-
-| 依赖 | 必需？ | 说明 |
-|------|--------|------|
-| Chrome 浏览器 | 是 | 需安装 Chrome |
-| Claude in Chrome 扩展 | 是 | 从 https://claude.ai/chrome 安装 |
-| claude.ai OAuth 登录 | Bridge 模式需要 | 本地 Socket 模式不需要 |
-| Native Messaging Host | 本地 Socket 需要 | 扩展安装时自动注册 |
-
-## 9. 与 /voice、/schedule 恢复方式对比
-
-| 项 | `/schedule` | `/voice` | Claude in Chrome |
-|---|---|---|---|
-| 编译开关 | `AGENT_TRIGGERS_REMOTE` | `VOICE_MODE` | **无需** |
-| 改 dev.ts/build.ts | ✅ | ✅ | **不需要** |
-| 缺失的 vendor 二进制 | 无 | `.node` 文件 | 无 |
-| 需要替换的 stub | 无 | `audio-capture-napi` | `@ant/claude-for-chrome-mcp`（7 个文件） |
-| 改动 src/ 源码 | 无 | 无 | 无 |
-| 平台限制 | 无 | 需原生 `.node` | 需 Chrome 浏览器 |
+不带 `--chrome` 参数正常启动即可，不会加载任何浏览器相关模块，不影响其他功能。