versun/claude-code
1
0
Fork 0
mirror of https://github.com/claude-code-best/claude-code.git synced 2026-06-18 14:25:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: 文档大重组，对齐 README 入口

Browse Source 
以 README 为单一事实来源，重构整个 docs/ 目录。

最终结构（3 大组、15 篇文档）：
- 开始: installation / quickstart / model-providers
- 核心功能: pipes-and-lan、acp、channels、chrome-control、computer-use、
  voice-mode、web-browser-tool、auto-dream、remote-control-self-hosting、
  langfuse-monitoring
- 内部机制: growthbook-adapter、sentry-setup

主要变更：
- 删除 56 个 README 未提及的文档（architecture 全部 / guides 全部 /
  features 中未在 README 出现的 20 篇 / internals 中的 5 篇）
- 合并 6 组重复文档（pipes-and-lan、chrome-control、acp、computer-use、
  auto-dream、coordinator-mode 简化为入口）
- features 子组从 5 → 4，ui/ 合并入 tools/
- 所有保留文档加上人性化 frontmatter（title/description/keywords）
- docs.json navigation 简化为 3 大组，redirects 重新过滤为 7 条合并跳转
- 新增 docs.md 工作大纲与验证脚本（verify-docs / check-docs-orphans /
  dump-docs-outline）

总计 130 文件改动，从约 35000 行精简到约 2000 行。

Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
This commit is contained in:
claude-code-best
2026-06-14 20:42:51 +08:00
parent 2714bbf812
commit 37dac682b9
130 changed files with 2074 additions and 33533 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
docs/features/external/channels.md vendored Normal file
View File

@@ -0,0 +1,95 @@
---
title: "频道消息推送（Channels）"
description: "MCP 服务器把飞书 / Slack / Discord / 微信等外部消息推到会话，`--channels plugin:name@marketplace` 启用。"
keywords: ["Channels", "频道消息", "微信 channel", "飞书 channel", "MCP 事件推送"]
---
# Channels — 外部频道消息接入
> 启动参数：`--channels` / `--dangerously-load-development-channels`
> 状态：已解除 feature flag 和 OAuth 限制，可直接使用
## 概述
Channel 是一个 MCP 服务器，它将外部事件推送到你运行中的 Claude Code 会话中，以便 Claude 可以在你不在终端时做出反应。详细使用说明请参考以下文档：
- **官方文档**：[使用 channels 将事件推送到运行中的会话](https://code.claude.com/docs/zh-CN/channels)
- **飞书插件**：[claude-code-feishu-channel](https://github.com/whobot-ai/claude-code-feishu-channel) — 社区首个飞书 Channel 插件，支持双向消息、配对认证、群组聊天、文件附件
本仓库现在内置了 **微信 WeChat channel**，不需要单独安装外部 marketplace 插件。
## 快速开始
```bash
# 启用频道监听（plugin 格式）
ccb --channels plugin:feishu@claude-code-feishu-channel
# 启用内置微信 channel
ccb weixin login
ccb --channels plugin:weixin@builtin
# 启用频道监听（server 格式）
ccb --channels server:my-slack-bridge
# 同时启用多个频道
ccb --channels plugin:feishu@claude-code-feishu-channel --channels server:discord-bot
# 开发模式（跳过 allowlist 检查，用于测试自定义 channel）
ccb --dangerously-load-development-channels server:my-custom-channel
```
## 支持的 Channel
| Channel | 说明 | 来源 |
|---------|------|------|
| **Telegram** | 官方 Telegram Bot 集成 | `/plugin install telegram@claude-plugins-official` |
| **Discord** | 官方 Discord Bot 集成 | `/plugin install discord@claude-plugins-official` |
| **iMessage** | macOS 原生消息 | `/plugin install imessage@claude-plugins-official` |
| **飞书 (Feishu/Lark)** | 双向消息、群组聊天、文件附件 | `/plugin install feishu@claude-code-feishu-channel` |
| **微信 (WeChat)** | 内置 channel，支持扫码登录、双向消息、附件透传 | `ccb weixin login` + `ccb --channels plugin:weixin@builtin` |
## 微信内置 Channel
### 登录
```bash
ccb weixin login
```
已登录状态可清除：
```bash
ccb weixin login clear
```
### 会话启用
```bash
ccb --channels plugin:weixin@builtin
```
### 配对授权
首次收到未授权微信用户消息时，weixin channel 会回一条 6 位 pairing code。运营侧可在终端执行：
```bash
ccb weixin access pair <code>
```
确认后，该微信用户后续消息才会进入 Claude Code 会话。
## 相关文件
| 文件 | 职责 |
|------|------|
| `src/services/mcp/channelNotification.ts` | 频道 gate 逻辑、消息包装 |
| `src/services/mcp/channelAllowlist.ts` | 频道开关（已默认开启） |
| `src/services/mcp/useManageMCPConnections.ts` | MCP 连接管理中的频道注册 |
| `src/components/LogoV2/ChannelsNotice.tsx` | 启动时频道状态提示 |
| `src/main.tsx` | `--channels` 参数解析 |
| `src/interactiveHelpers.tsx` | Dev channels 确认对话框 |
## 参考链接
- [官方 Channels 文档](https://code.claude.com/docs/zh-CN/channels) — 完整使用说明、安全性、Enterprise 控制
- [飞书 Channel 插件](https://github.com/whobot-ai/claude-code-feishu-channel) — 安装配置教程、MCP 工具、Skill 命令参考

189
docs/features/external/chrome-control.md vendored Normal file
View File

@@ -0,0 +1,189 @@
---
title: "Chrome 浏览器控制"
description: "让 AI 用自然语言操作 Chrome 浏览器：导航、表单、数据抓取。两种实现方案对比：自托管 MCP（chrome-use-mcp）与 Chrome 原生集成（claude-in-chrome-mcp）。"
keywords: ["Chrome 浏览器控制", "MCP", "浏览器自动化", "Claude in Chrome", "网页抓取"]
---
# Chrome 浏览器控制
让 Claude Code 用自然语言直接操作 Chrome 浏览器，完成网页导航、表单填写、数据抓取、截图录制等任务。
Claude Code 提供两种浏览器控制方案：
| 方案 | 简介 | 适用场景 |
|------|------|---------|
| **Chrome Use MCP**（自托管 MCP） | 通过社区开源 MCP 扩展（`mcp-chrome`）接入，Claude Code 以 MCP 客户端方式调用 | 想自托管、可定制、不依赖 Anthropic 订阅 |
| **Claude in Chrome**（Chrome 原生集成） | Anthropic 官方扩展 + 内建工具集，通过 `--chrome` 启动参数加载 | 需要完整能力（截图/GIF/网络监控/JS 执行等），有 Claude Pro/Max/Team 订阅 |
两种方案可以独立使用，也可按需切换。下面先讲快速上手，再分别给出详细说明。
## 快速上手
### 方案一：Chrome Use MCP（3 分钟）
**第一步：安装 Chrome 扩展**
1. 下载扩展：https://github.com/hangwin/mcp-chrome/releases
2. 解压 zip 文件
3. 打开 Chrome 访问 `chrome://extensions/`
4. 开启右上角「开发者模式」
5. 点击「加载已解压的扩展程序」，选择解压后的文件夹
**第二步：启动 Claude Code**
```bash
bun run dev
ccb # 或者 ccb 安装版也行
```
**第三步：启用 Chrome MCP**
1. 在 REPL 中输入 `/mcp` 打开 MCP 面板
2. 找到 `mcp-chrome`，按空格键启用
3. 按 Enter 确认
### 方案二：Claude in Chrome
**前置条件**
| 条件 | 说明 |
|------|------|
| 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**
```bash
# Dev 模式
bun run dev -- --chrome
# 构建产物
node dist/cli.js --chrome
```
启动后 Claude 会自动检测 Chrome 扩展是否已安装，并注册浏览器控制工具。
**确认连接**：REPL 中输入 `/chrome`，查看扩展状态是否显示 "Installed / Connected"。
**开始对话**：正常与 Claude 对话，当需要操作浏览器时直接说，例如：
- "打开 https://example.com 并截图"
- "在当前页面搜索关键词 xxx"
- "填写登录表单，用户名 admin"
- "帮我录制当前操作的 GIF"
**权限审批**：首次执行浏览器操作时，Claude 会请求你的确认；操作完成后返回结果（截图、文本、执行结果等）。
## 详细说明：Chrome Use MCP
Chrome Use MCP 是基于社区开源项目 [`mcp-chrome`](https://github.com/hangwin/mcp-chrome) 的自托管方案。Claude Code 以标准 MCP 客户端身份接入，由扩展提供浏览器侧能力。
特点：
- 完全开源、可自托管，不依赖 Anthropic 账户体系
- 在 MCP 面板里启用/禁用，不占用启动参数
- 能力由扩展决定，适合做定制化浏览器自动化
相关文档：
- GitHub 仓库：https://github.com/hangwin/mcp-chrome
## 详细说明：Claude in Chrome
Claude in Chrome 是 Anthropic 官方扩展 + 内建工具集，提供更完整的浏览器操控能力。
### 可用操作
#### 页面交互
| 操作 | 说明 |
|------|------|
| `navigate` | 导航到指定 URL，或前进/后退 |
| `computer` | 鼠标点击、移动、拖拽、键盘输入、截图等（13 种 action） |
| `form_input` | 填写表单字段 |
| `upload_image` | 上传图片到文件输入框或拖拽区域 |
| `javascript_tool` | 在页面上下文执行 JavaScript |
#### 页面读取
| 操作 | 说明 |
|------|------|
| `read_page` | 获取页面可访问性树（DOM 结构） |
| `get_page_text` | 提取页面纯文本内容 |
| `find` | 用自然语言搜索页面元素 |
#### 标签页管理
| 操作 | 说明 |
|------|------|
| `tabs_context_mcp` | 获取当前标签组信息 |
| `tabs_create_mcp` | 创建新标签页 |
#### 监控与调试
| 操作 | 说明 |
|------|------|
| `read_console_messages` | 读取浏览器控制台日志 |
| `read_network_requests` | 读取网络请求记录 |
#### 其他
| 操作 | 说明 |
|------|------|
| `resize_window` | 调整浏览器窗口尺寸 |
| `gif_creator` | 录制 GIF 并导出 |
| `shortcuts_list` | 列出可用快捷方式 |
| `shortcuts_execute` | 执行快捷方式 |
| `update_plan` | 向你提交操作计划供审批 |
| `switch_browser` | 切换到其他 Chrome 浏览器（仅 Bridge 模式） |
### 通信模式
Claude in Chrome 支持两种与浏览器通信的方式：
**本地 Socket（默认）**：Chrome 扩展通过 Native Messaging Host 与 CLI 建立 Unix socket 连接。适用于本地开发，无需额外配置。
**Bridge WebSocket**：通过 Anthropic 的 bridge 服务中转，支持远程操控浏览器。需要 claude.ai OAuth 登录。
## 进阶与参考
### 配置
#### 启用 / 禁用（Claude in Chrome）
```bash
# 显式禁用
bun run dev -- --no-chrome
```
或在 REPL 中通过 `/chrome` 命令切换启用/禁用状态。
#### 通过配置默认启用
在 Claude Code 设置中将 `claudeInChromeDefaultEnabled` 设为 `true`，以后启动无需加 `--chrome` 参数。
#### Feature Flag 提示
- Chrome Use MCP：依赖标准 MCP 加载机制，通过 `/mcp` 面板启用。
- Claude in Chrome：构建/运行时通过 `--chrome` 参数（对应内部 feature 开关）加载浏览器相关模块；不带该参数启动时不会加载任何浏览器相关模块，不影响其他功能。
### 常见问题
**扩展显示未安装**
确认已从 Chrome Web Store 安装 "Claude in Chrome" 扩展，安装后重启浏览器。Chrome Use MCP 用户则需确认已按上面"加载已解压的扩展程序"步骤加载本地扩展。
**工具未出现在工具列表**
- Claude in Chrome：检查启动时是否加了 `--chrome` 参数，或通过 `/chrome` 命令确认状态。
- Chrome Use MCP：在 `/mcp` 面板里确认 `mcp-chrome` 已启用。
**连接超时**
确保 Chrome 浏览器正在运行且扩展已启用。Native Messaging Host 在扩展安装时自动注册，如果重装过扩展需要重启浏览器。
**不使用 Chrome 功能时**
不带 `--chrome` 参数正常启动即可，不会加载任何浏览器相关模块，不影响其他功能。

621
docs/features/external/computer-use.md vendored Normal file
View File

@@ -0,0 +1,621 @@
---
title: "屏幕控制（Computer Use）"
description: "截屏、键鼠控制，跨 macOS / Windows / Linux。本文包含快速上手、平台差异说明和工具参考。"
keywords: [屏幕控制, 截屏, 键鼠模拟, 跨平台自动化, Computer Use]
---
# 屏幕控制（Computer Use）
Computer Use 提供截屏、键鼠控制和应用管理能力，支持 macOS / Windows / Linux 三大桌面平台。Windows 平台额外提供窗口绑定模式（不干扰真实键鼠），全平台共 38 个工具。
本文包含三部分：
- **快速上手** — 启用方式与典型操作流程
- **平台差异说明** — 三平台的实现、依赖与能力差异
- **工具参考** — 全部工具的参数、用法和进阶场景
## 概述
Computer Use 由三个 workspace 包组成：
| 包 | 职责 |
|----|------|
| `@ant/computer-use-mcp` | MCP server 入口与工具注册（12 文件） |
| `@ant/computer-use-input` | 键鼠模拟（dispatcher + 各平台 backend） |
| `@ant/computer-use-swift` | 截图与应用管理（dispatcher + 各平台 backend） |
工具共 38 个，分三类：
| 分类 | 平台 | 工具数 | 说明 |
|------|------|--------|------|
| 通用工具 | 全平台 | 24 | 官方 Computer Use 标准能力 |
| Windows 专属工具 | Win32 | 11 | 绑定窗口模式下的增强能力 |
| 教学工具 | 全平台 | 3 | 分步引导模式（需 `teachMode` 开启） |
## 快速上手
### 启用方式
在启动 Claude Code 时附加 `--computer-use-mcp`，或在运行时通过 `feature("CHICAGO_MCP")` 控制入口初始化。
```bash
claude --computer-use-mcp
```
Linux 平台需要先安装依赖工具（详见下文「Linux 依赖工具」）。macOS / Windows 通常无需额外安装。
### 典型操作流程
#### 流程 1：全屏操作（未绑定窗口）
```
request_access(apps=["Notepad"])
open_application(app="Notepad") ← 自动绑定窗口
screenshot ← PrintWindow 截图 + GUI 元素列表
left_click(coordinate=[500, 300]) ← 全局 SendInput
type(text="hello world") ← 全局 SendInput
key(text="ctrl+s") ← 全局 SendInput
```
#### 流程 2：绑定窗口操作（Windows 推荐，不干扰用户）
```
request_access(apps=["Notepad"])
bind_window(action="list") ← 列出所有窗口
bind_window(action="bind", title="记事本") ← 绑定 + 绿色边框 + 虚拟光标
screenshot ← PrintWindow 截取绑定窗口
virtual_mouse(action="click", coordinate=[500, 300]) ← SendMessageW，不动真实鼠标
virtual_keyboard(action="type", text="hello world") ← SendMessageW，不动物理键盘
virtual_keyboard(action="combo", text="ctrl+s") ← 保存
mouse_wheel(coordinate=[500, 400], delta=-5) ← 向下滚动
bind_window(action="unbind") ← 解除绑定
```
#### 流程 3：按元素名称操作
```
bind_window(action="bind", title="记事本")
screenshot ← 返回截图 + GUI elements 列表
click_element(name="保存", role="Button") ← UI Automation 查找并点击
type_into_element(role="Edit", text="new content")
```
#### 流程 4：终端交互
```
bind_window(action="bind", title="PowerShell")
screenshot
prompt_respond(response_type="yes") ← 回答 y + Enter
prompt_respond(response_type="select", arrow_direction="down", arrow_count=2) ← 选第3项
```
#### 流程 5：Excel/浏览器滚动
```
bind_window(action="bind", title="Excel")
screenshot
mouse_wheel(coordinate=[600, 400], delta=-10) ← 向下滚动 10 格
mouse_wheel(coordinate=[600, 400], delta=5, direction="horizontal") ← 向右滚动
```
## 平台差异说明
### 各平台能力依赖
#### computer-use-input（键鼠）
| 功能 | macOS | Windows | Linux |
|------|-------|---------|-------|
| 鼠标移动 | CGEvent JXA | SetCursorPos P/Invoke | xdotool mousemove |
| 鼠标点击 | CGEvent JXA | SendInput P/Invoke | xdotool click |
| 鼠标滚轮 | CGEvent JXA | SendInput MOUSEEVENTF_WHEEL | xdotool scroll |
| 键盘按键 | System Events osascript | keybd_event P/Invoke | xdotool key |
| 组合键 | System Events osascript | keybd_event 组合 | xdotool key combo |
| 文本输入 | System Events keystroke | SendKeys.SendWait | xdotool type |
| 前台应用 | System Events osascript | GetForegroundWindow P/Invoke | xdotool getactivewindow + /proc |
| 工具依赖 | osascript（内置） | powershell（内置） | xdotool（需安装） |
#### computer-use-swift（截图 + 应用管理）
| 功能 | macOS | Windows | Linux |
|------|-------|---------|-------|
| 全屏截图 | screencapture | CopyFromScreen | gnome-screenshot / scrot / grim |
| 区域截图 | screencapture -R | CopyFromScreen(rect) | gnome-screenshot -a / scrot -a / grim -g |
| 显示器列表 | CGGetActiveDisplayList JXA | Screen.AllScreens | xrandr --query |
| 运行中应用 | System Events JXA | Get-Process | wmctrl -l / ps |
| 打开应用 | osascript activate | Start-Process | xdg-open / gtk-launch |
| 隐藏/显示 | System Events visibility | ShowWindow/SetForegroundWindow | wmctrl -c / xdotool |
| 工具依赖 | screencapture + osascript | powershell | xdotool + scrot/grim + wmctrl |
#### executor 层
| 功能 | macOS | Windows | Linux |
|------|-------|---------|-------|
| drainRunLoop | CFRunLoop pump | 不需要 | 不需要 |
| ESC 热键 | CGEventTap | 跳过（Ctrl+C fallback） | 跳过（Ctrl+C fallback） |
| 剪贴板读 | pbpaste | `powershell Get-Clipboard` | xclip -o / wl-paste |
| 剪贴板写 | pbcopy | `powershell Set-Clipboard` | xclip / wl-copy |
| 粘贴快捷键 | command+v | ctrl+v | ctrl+v |
| 终端检测 | __CFBundleIdentifier | WT_SESSION / TERM_PROGRAM | TERM_PROGRAM |
| 系统权限 | TCC check | 直接 granted | 检查 xdotool 安装 |
### Linux 依赖工具
| 工具 | 用途 | 安装命令（Ubuntu） |
|------|------|-------------------|
| `xdotool` | 键鼠模拟 + 窗口管理 | `sudo apt install xdotool` |
| `scrot` 或 `gnome-screenshot` | 截图 | `sudo apt install scrot` |
| `xrandr` | 显示器信息 | 通常已预装 |
| `xclip` | 剪贴板 | `sudo apt install xclip` |
| `wmctrl` | 窗口列表/切换 | `sudo apt install wmctrl` |
Wayland 环境需要替代工具：`ydotool`（替代 xdotool）、`grim`（替代 scrot）、`wl-clipboard`（替代 xclip）。初期可先只支持 X11，Wayland 标记为 todo。
## 工具参考
### 通用工具（24 个）
全平台可用。未绑定窗口时，操作对象是整个屏幕。
#### 权限与会话
| 工具 | 参数 | 说明 |
|------|------|------|
| `request_access` | `apps[]`, `reason`, `clipboardRead?`, `clipboardWrite?`, `systemKeyCombos?` | 请求操作应用的权限。所有其他工具的前置条件 |
| `list_granted_applications` | — | 列出当前会话已授权的应用 |
#### 截图与显示
| 工具 | 参数 | 说明 |
|------|------|------|
| `screenshot` | `save_to_disk?` | 截取当前屏幕。绑定窗口时截取绑定窗口（PrintWindow）。返回图片 + GUI 元素列表（Windows） |
| `zoom` | `region: [x1,y1,x2,y2]` | 截取指定区域的高分辨率图片。坐标基于最近一次全屏截图 |
| `switch_display` | `display` | 切换截图的目标显示器 |
#### 鼠标操作
| 工具 | 参数 | 说明 |
|------|------|------|
| `left_click` | `coordinate: [x,y]`, `text?` (修饰键) | 左键点击。`text` 可传 "shift"/"ctrl"/"alt" 实现组合点击 |
| `double_click` | `coordinate`, `text?` | 双击 |
| `triple_click` | `coordinate`, `text?` | 三击（选整行） |
| `right_click` | `coordinate`, `text?` | 右键点击 |
| `middle_click` | `coordinate`, `text?` | 中键点击 |
| `mouse_move` | `coordinate` | 移动鼠标（不点击） |
| `left_click_drag` | `coordinate` (终点), `start_coordinate?` (起点) | 拖拽 |
| `left_mouse_down` | — | 按下左键不松 |
| `left_mouse_up` | — | 松开左键 |
| `cursor_position` | — | 获取当前鼠标位置 |
#### 键盘操作
| 工具 | 参数 | 说明 |
|------|------|------|
| `type` | `text` | 输入文字 |
| `key` | `text` (如 "ctrl+s"), `repeat?` | 按键/组合键 |
| `hold_key` | `text`, `duration` (秒) | 按住键指定时长 |
#### 滚动
| 工具 | 参数 | 说明 |
|------|------|------|
| `scroll` | `coordinate`, `scroll_direction`, `scroll_amount` | 滚动。方向: up/down/left/right |
#### 应用管理
| 工具 | 参数 | 说明 |
|------|------|------|
| `open_application` | `app` | 打开应用。Windows 上自动绑定窗口 |
#### 剪贴板
| 工具 | 参数 | 说明 |
|------|------|------|
| `read_clipboard` | — | 读取剪贴板文字 |
| `write_clipboard` | `text` | 写入剪贴板 |
#### 其他
| 工具 | 参数 | 说明 |
|------|------|------|
| `wait` | `duration` (秒) | 等待 |
| `computer_batch` | `actions[]` | 批量执行多个动作（减少 API 往返） |
### Windows 专属工具（12 个）
仅 Windows 平台可见。核心能力：**绑定窗口后的独立操作——不抢占用户鼠标键盘**。
#### 工作模式
```
┌──────────────────────────────────────────────────┐
│ 未绑定模式 │
│ 使用通用工具 (left_click/type/key/scroll) │
│ 操作对象：整个屏幕 │
│ 输入方式：全局 SendInput（会移动真实鼠标） │
└──────────────────────────────────────────────────┘
│
bind_window / open_application
▼
┌──────────────────────────────────────────────────┐
│ 绑定窗口模式 │
│ 使用 Win32 工具 (virtual_mouse/virtual_keyboard) │
│ 操作对象：绑定的窗口 │
│ 输入方式：SendMessageW（不动真实鼠标/键盘） │
│ 可视化：DWM 绿色边框 + 虚拟光标 + 状态指示器 │
└──────────────────────────────────────────────────┘
```
#### 窗口绑定
| 工具 | 参数 | 说明 |
|------|------|------|
| `bind_window` | `action`: list/bind/unbind/status | 窗口绑定管理 |
**动作详情：**
| action | 参数 | 说明 |
|--------|------|------|
| `list` | — | 列出所有可见窗口（hwnd、pid、title） |
| `bind` | `title?`, `hwnd?`, `pid?` | 绑定到指定窗口。设置 DWM 绿色边框 + 启动虚拟光标 + 启动状态指示器 + 短暂激活窗口确保可接收输入 |
| `unbind` | — | 解除绑定，恢复全屏模式 |
| `status` | — | 查看当前绑定状态（hwnd、title、pid、窗口矩形） |
#### 窗口管理
| 工具 | 参数 | 说明 |
|------|------|------|
| `window_management` | `action`, `x?`, `y?`, `width?`, `height?` | 窗口操作（Win32 API，不走全局快捷键） |
**动作详情：**
| action | 说明 |
|--------|------|
| `minimize` | ShowWindow(SW_MINIMIZE) |
| `maximize` | ShowWindow(SW_MAXIMIZE) |
| `restore` | ShowWindow(SW_RESTORE) — 恢复最小化/最大化 |
| `close` | SendMessage(WM_CLOSE) — 优雅关闭 |
| `focus` | SetForegroundWindow + BringWindowToTop — 激活窗口 |
| `move_offscreen` | SetWindowPos(-32000,-32000) — 移到屏幕外（仍可 SendMessage/PrintWindow） |
| `move_resize` | SetWindowPos — 移动/缩放到指定位置和大小 |
| `get_rect` | GetWindowRect — 获取当前位置和大小 |
#### 虚拟鼠标
| 工具 | 参数 | 说明 |
|------|------|------|
| `virtual_mouse` | `action`, `coordinate: [x,y]`, `start_coordinate?` | 在绑定窗口内操作虚拟鼠标 |
**动作详情：**
| action | 说明 |
|--------|------|
| `click` | 左键点击。虚拟光标移动到坐标 + 闪烁动画 |
| `double_click` | 双击 |
| `right_click` | 右键点击 |
| `move` | 移动虚拟光标（不点击） |
| `drag` | 按住 → 移动 → 松开。需 `start_coordinate` 指定起点 |
| `down` | 按下左键不松 |
| `up` | 松开左键 |
**与通用鼠标工具的区别：**
| | 通用 (`left_click` 等) | `virtual_mouse` |
|---|---|---|
| 输入方式 | SendInput（全局） | SendMessageW（窗口级） |
| 真实鼠标 | 会移动 | **不动** |
| 用户干扰 | 有 | **无** |
| 适用场景 | 未绑定时 | **绑定后** |
#### 虚拟键盘
| 工具 | 参数 | 说明 |
|------|------|------|
| `virtual_keyboard` | `action`, `text`, `duration?`, `repeat?` | 在绑定窗口内操作虚拟键盘 |
**动作详情：**
| action | text 含义 | 说明 |
|--------|----------|------|
| `type` | 要输入的文字 | SendMessageW(WM_CHAR)，支持 Unicode 中文/emoji |
| `combo` | 组合键 (如 "ctrl+s") | WM_KEYDOWN/UP 序列 |
| `press` | 单个键名 | 按下不松（配合 release 使用） |
| `release` | 单个键名 | 松开按键 |
| `hold` | 键名或组合 | 按住指定秒数后松开 |
**与通用键盘工具的区别：**
| | 通用 (`type`/`key`) | `virtual_keyboard` |
|---|---|---|
| 输入方式 | SendInput（全局） | SendMessageW（窗口级） |
| 物理键盘 | 会冲突 | **不冲突** |
| 适用场景 | 未绑定时 | **绑定后** |
**注意：** SendMessageW 对 Windows Terminal (ConPTY) 等现代应用无效。这些应用需要使用通用工具 + 窗口激活方式操作。
#### 鼠标滚轮
| 工具 | 参数 | 说明 |
|------|------|------|
| `mouse_wheel` | `coordinate: [x,y]`, `delta`, `direction?` | WM_MOUSEWHEEL 鼠标中键滚轮 |
**参数说明：**
- `delta`: 正值=向上，负值=向下。每 1 单位 ≈ 3 行
- `direction`: "vertical"（默认）或 "horizontal"
- `coordinate`: 滚轮作用点——决定哪个面板/区域接收滚动
**与通用 `scroll` 的区别：**
| | `scroll` | `mouse_wheel` |
|---|---|---|
| 原理 | WM_VSCROLL/WM_HSCROLL | **WM_MOUSEWHEEL** |
| Excel | 否 | 是 |
| 浏览器 | 否 | 是 |
| 代码编辑器 | 否 | 是 |
#### 元素级操作
| 工具 | 参数 | 说明 |
|------|------|------|
| `click_element` | `name?`, `role?`, `automationId?` | 按无障碍名称/角色点击 GUI 元素 |
| `type_into_element` | `name?`, `role?`, `automationId?`, `text` | 按名称向元素输入文字 |
**工作原理：**
1. 通过 UI Automation 在绑定窗口中查找匹配元素
2. `click_element`: 先尝试 InvokePattern（按钮/菜单），失败则 SendMessage 点击 BoundingRect 中心
3. `type_into_element`: 先尝试 ValuePattern 直接设值，失败则点击聚焦 + WM_CHAR 输入
**适用场景：**
- 截图中看到元素名称但坐标不精确时
- Accessibility Snapshot 列出了元素的 name/automationId 时
- 比坐标点击更可靠（不受窗口缩放/DPI 影响）
#### 终端交互
| 工具 | 参数 | 说明 |
|------|------|------|
| `open_terminal` | `agent`, `command?` | 打开新终端窗口并启动 AI agent（claude/codex/gemini/custom）。自动绑定窗口并截图验证 |
| `activate_window` | `click_x?`, `click_y?` | 激活绑定窗口：SetForegroundWindow + BringWindowToTop + 点击确保焦点 |
| `prompt_respond` | `response_type`, `arrow_direction?`, `arrow_count?`, `text?` | 处理终端 Yes/No/选择提示 |
**open_terminal agent 类型：**
| agent | 命令 | 说明 |
|-------|------|------|
| `claude` | `claude` | 启动 Claude Code |
| `codex` | `codex` | 启动 Codex |
| `gemini` | `gemini` | 启动 Gemini |
| `custom` | 用户指定 | 自定义命令 |
**response_type 详情：**
| response_type | 操作 | 场景 |
|---------------|------|------|
| `yes` | 发送 'y' + Enter | npm "Continue? (y/n)" |
| `no` | 发送 'n' + Enter | 拒绝确认 |
| `enter` | 发送 Enter | 接受默认选项 |
| `escape` | 发送 Escape | 取消操作 |
| `select` | ↑/↓ 箭头 × N + Enter | inquirer 选择菜单 |
| `type` | 输入文字 + Enter | 文本输入提示 |
#### 状态指示器
| 工具 | 参数 | 说明 |
|------|------|------|
| `status_indicator` | `action`: show/hide/status, `message?` | 控制绑定窗口底部的浮动状态标签 |
### 教学工具（3 个）
需要 `teachMode` 开启。
| 工具 | 说明 |
|------|------|
| `request_teach_access` | 请求教学引导模式权限 |
| `teach_step` | 显示一步引导提示，等用户点 Next |
| `teach_batch` | 批量排队多步引导 |
## 进阶
### 应用兼容性
| 应用类型 | SendMessageW (virtual_*) | 元素操作 (click_element) | 注意 |
|---------|--------------------------|------------------------|------|
| 传统 Win32 (记事本/写字板) | 完美支持 | 完美支持 | 完美支持 |
| Office (Excel/Word) | 支持（COM 自动化） | 支持 | 通过 COM API |
| WPF 应用 | 支持 | 支持 | 标准 UIA 支持 |
| Electron/Chrome | 部分支持 | 部分支持 | 内部渲染不走 Win32 消息 |
| UWP/WinUI (Windows Terminal) | 不支持 | 不支持 | ConPTY 不接受 SendMessageW |
| 浏览器网页内容 | 不支持 | 不支持 | 需要全局 SendInput |
**对于不支持 SendMessageW 的应用**，使用通用工具 (`left_click`/`type`/`key`) + `window_management(action="focus")` 先激活窗口。
### 绑定窗口时的可视化
绑定窗口后自动启动三层可视化：
1. **DWM 绿色边框** — 窗口自身的边框颜色变绿，零偏移
2. **虚拟鼠标光标** — 红色箭头图标，跟随 virtual_mouse 操作移动，点击时闪烁
3. **状态指示器** — 窗口底部浮动标签，显示当前操作（通过 status_indicator 控制）
### Accessibility Snapshot
每次 `screenshot` 时，如果窗口已绑定，会自动附带 GUI 元素列表：
```
GUI elements in this window:
[Button] "Save" (120,50 80x30) enabled
[Edit] "" (200,80 400x25) enabled value="hello" id=textBox1
[MenuItem] "File" (10,0 40x25) enabled
[MenuItem] "Edit" (50,0 40x25) enabled
[CheckBox] "Auto-save" (300,50 100x20) enabled id=chkAutoSave
```
模型同时收到 **截图图片 + 结构化元素列表**，可以选择：
- 用坐标操作：`virtual_mouse(action="click", coordinate=[120, 50])`
- 用名称操作：`click_element(name="Save")`
### UI Automation Control Patterns 参考
`click_element` / `type_into_element` 底层使用 UI Automation Control Patterns。当前已实现的和可扩展的：
| Pattern | 用途 | 当前状态 | 可用于 |
|---------|------|---------|--------|
| `InvokePattern` | 触发点击 | 已实现 (`click_element`) | 按钮、菜单项、链接 |
| `ValuePattern` | 读写文本值 | 已实现 (`type_into_element`) | 文本框、组合框 |
| `TogglePattern` | 切换状态 | 未实现 | 复选框、开关 |
| `SelectionPattern` | 选择项目 | 未实现 | 下拉菜单、列表 |
| `ScrollPattern` | 编程滚动 | 未实现（用 `mouse_wheel` 替代） | 列表、树、面板 |
| `ExpandCollapsePattern` | 展开/折叠 | 未实现 | 树节点、折叠面板 |
| `WindowPattern` | 窗口操作 | 未实现（用 `window_management` 替代） | 窗口最大化/关闭 |
| `TextPattern` | 读取文档文本 | 未实现 | 文档、富文本 |
| `GridPattern` | 表格操作 | 未实现 | Excel 单元格、数据网格 |
| `TablePattern` | 表格结构 | 未实现 | 表头、行列关系 |
| `RangeValuePattern` | 范围值操作 | 未实现 | 滑块、进度条 |
| `TransformPattern` | 移动/缩放 | 未实现 | 可拖拽元素 |
**扩展路线：** 优先实现 `TogglePattern`（复选框）和 `SelectionPattern`（下拉菜单），这两个在表单自动化中最常用。
### 输入方式技术矩阵
不同应用类型需要不同的输入方式：
| 输入方式 | API | 优势 | 限制 | 适用应用 |
|---------|-----|------|------|---------|
| **SendMessageW** | `WM_CHAR` / `WM_KEYDOWN` | 不抢焦点，不动真实键鼠 | 现代应用不支持 | Win32 传统应用 (记事本/Office/WPF) |
| **SendInput** | `INPUT` 结构体 | 所有应用都支持 | **必须前台焦点**，会干扰用户 | 所有应用（通用后备） |
| **WriteConsoleInput** | 控制台 API | 直接写入控制台缓冲区 | 需要 AttachConsole（可能被拒绝） | cmd/PowerShell（非 Windows Terminal） |
| **UI Automation** | `InvokePattern` / `ValuePattern` | 语义级操作，最可靠 | 部分应用不暴露 UIA 接口 | 支持 UIA 的应用 |
| **COM Automation** | Excel/Word COM | 完全编程控制 | 仅 Office 应用 | Excel / Word |
| **剪贴板 + 粘贴** | `SetClipboardData` + `Ctrl+V` | 绕过输入限制 | 会覆盖用户剪贴板 | 通用后备 |
**按应用类型的推荐输入策略：**
| 应用类型 | 首选 | 后备 | 说明 |
|---------|------|------|------|
| 传统 Win32 (记事本/写字板) | SendMessageW | UIA ValuePattern | 虚拟输入完美工作 |
| Office (Excel/Word) | COM Automation | SendMessageW | COM 提供结构化操作 |
| WPF 应用 | SendMessageW | UIA | 标准 Win32 消息循环 |
| Electron/Chrome 应用 | UIA | 剪贴板粘贴 | 内部渲染不走 Win32 |
| Windows Terminal (ConPTY) | SendInput (需前台) | 剪贴板粘贴 | ConPTY 不接受外部消息 |
| UWP/WinUI 应用 | SendInput (需前台) | UIA | XAML 渲染不走 Win32 消息 |
### 屏幕截取技术方案对比
当前使用 Python Bridge (mss) 进行截图，底层是 GDI BitBlt。三种方案对比：
| 方案 | API | 当前状态 | 性能 | 优势 | 限制 |
|------|-----|---------|------|------|------|
| **GDI BitBlt** | `BitBlt` / `PrintWindow` | 当前使用 (mss/bridge.py) | ~300ms | 简单稳定，支持后台窗口 (PrintWindow) | 不支持硬件加速内容、DPI 处理复杂 |
| **DXGI Desktop Duplication** | `IDXGIOutputDuplication` | 未实现 | ~16ms (60fps) | 硬件加速，支持 HDR，GPU 直接读取 | 不支持单窗口截取，需 D3D11 |
| **Windows.Graphics.Capture** | `GraphicsCaptureItem` | 未实现 | ~16ms | 最新 API，支持单窗口/单显示器，系统级权限管理 | Win10 1903+，首次需用户确认 |
**推荐升级路径：**
```
当前: GDI BitBlt (mss) ─── 全屏 ~300ms, 窗口 ~300ms (PrintWindow)
│
├─ 近期: DXGI Desktop Duplication ─── 全屏 ~16ms, 但不支持单窗口
│
└─ 远期: Windows.Graphics.Capture ─── 全屏 + 单窗口都 ~16ms
```
**DXGI Desktop Duplication 实现要点：**
```python
# bridge.py 中可添加 DXGI 截图（通过 d3dshot 或 dxcam 库）
import dxcam # pip install dxcam
camera = dxcam.create()
frame = camera.grab() # numpy array, ~5ms
# 转为 JPEG base64 发送
```
**Windows.Graphics.Capture 实现要点：**
```python
# 需要 WinRT Python 绑定
# pip install winrt-Windows.Graphics.Capture winrt-Windows.Graphics.DirectX
# 限制：首次调用需要用户在系统弹窗中确认权限
```
### 已知限制与待解决
| 限制 | 影响 | 计划 |
|------|------|------|
| Windows Terminal 不接受 SendMessageW | 虚拟键盘/鼠标对终端无效 | 自动检测应用类型，终端类切换到 SendInput + 短暂激活 |
| PrintWindow 截不到 alternate screen buffer | Ink REPL 画面截不到 | 切换到 Windows.Graphics.Capture |
| Accessibility Snapshot 对大应用慢 (>30s) | Excel 等复杂应用超时 | 限制遍历深度 + 超时保护 |
| DWM 边框对自定义标题栏应用可能无效 | 某些 Electron 应用看不到边框 | 检测并回退到叠加窗口方案 |
| 虚拟光标是 PowerShell WinForms 进程 | 启动慢 (~1s)，资源占用 | 考虑用 Win32 原生窗口替代 |
### 技术路线图
#### Phase 1（当前）— 基础功能
- SendMessageW 虚拟输入
- PrintWindow/mss 截图
- UI Automation (InvokePattern + ValuePattern)
- Accessibility Snapshot
- DWM 边框指示
- Python Bridge
#### Phase 2（近期）— 兼容性增强
- 应用类型自动检测（Win32 vs Terminal vs UWP）
- 终端类应用自动切换 SendInput + 短暂激活
- TogglePattern / SelectionPattern 支持
- DXGI Desktop Duplication 高速截图
- Accessibility Snapshot 超时保护
#### Phase 3（远期）— 高级能力
- Windows.Graphics.Capture（单窗口实时截图）
- 截图元素标注（在截图上标记 ID 数字）
- 浏览器 DOM 提取（绑定浏览器时提取网页结构）
- GridPattern / TablePattern（Excel 单元格级操作）
- TextPattern（文档内容读取）
- 多窗口协同操作
## 配置
### Feature Flag
Computer Use 入口由 `CHICAGO_MCP` feature flag 控制。
- **Dev mode**：默认启用（`scripts/dev.ts` 全部启用）
- **Build mode**：默认启用（在 `DEFAULT_BUILD_FEATURES` 列表中）
- **运行时**：通过环境变量 `FEATURE_CHICAGO_MCP=1` 启用
入口位置：`src/main.tsx` 中 `feature("CHICAGO_MCP")` 门控，初始化 Computer Use MCP server。
### 跨平台架构要点
各平台由 dispatcher + backend 模式分发：
| 层 | macOS | Windows | Linux |
|----|-------|---------|-------|
| `computer-use-input/backends/` | darwin.ts | win32.ts | linux.ts |
| `computer-use-swift/backends/` | darwin.ts | win32.ts | linux.ts |
| `src/utils/computerUse/executor.ts` | darwin 路径 | 跨平台 executor | 跨平台 executor |
| `src/utils/computerUse/swiftLoader.ts` | darwin 加载 | platforms/ | platforms/ |
非 darwin 平台的关键差异：
- `drainRunLoop.ts` — 非 darwin 无需 CFRunLoop pump（直接执行 fn）
- `escHotkey.ts` — 非 darwin 返回 false（已有 Ctrl+C fallback）
- `hostAdapter.ts` — 非 darwin 权限检查逻辑：Windows 直接 granted，Linux 检查 xdotool 安装
- `common.ts` — 平台标识按 `process.platform` 动态分发：darwin→'native'，其他→'none'
- `gates.ts` — `hasRequiredSubscription()` 已按平台更新默认值
### 新增 Linux 后端的要点
| 步骤 | 文件 | 内容 |
|------|------|------|
| 1 | `packages/@ant/computer-use-input/src/backends/linux.ts` | xdotool 键鼠（mousemove/click/key/type/getactivewindow） |
| 2 | `packages/@ant/computer-use-swift/src/backends/linux.ts` | scrot/grim 截图 + xrandr 显示器 + wmctrl 窗口管理 |
| 3 | `packages/@ant/computer-use-input/src/index.ts` | dispatcher 加 `case 'linux'` |
| 4 | `packages/@ant/computer-use-swift/src/index.ts` | dispatcher 加 `case 'linux'` |

269
docs/features/external/voice-mode.md vendored Normal file
View File

@@ -0,0 +1,269 @@
---
title: "语音输入（Voice Mode）"
description: "Push-to-talk 语音输入，支持豆包语言模型。需 Anthropic OAuth 或本地语音后端。"
keywords: ["语音输入", "Push-to-Talk", "豆包 ASR", "STT", "语音转录"]
---
# VOICE_MODE — 语音输入
> Feature Flag: `FEATURE_VOICE_MODE=1`
> 实现状态：完整可用（双后端：Anthropic OAuth / 豆包 ASR）
> 引用数：46
## 一、功能概述
VOICE_MODE 实现"按键说话"（Push-to-Talk）语音输入。用户按住空格键录音，音频流式传输到 STT 后端，实时转录显示在终端中。支持两个后端：
- **Anthropic STT（默认）**：通过 WebSocket 流式传输到 Nova 3 端点，需要 Anthropic OAuth
- **豆包 ASR（Doubao）**：通过 `doubaoime-asr` 包的 AsyncGenerator 协议流式识别，使用独立凭证文件，无需 Anthropic OAuth
### 核心特性
- **Push-to-Talk**：长按空格键录音，释放后自动发送
- **流式转录**：录音过程中实时显示中间转录结果
- **无缝集成**：转录文本直接作为用户消息提交到对话
- **双后端切换**：通过 `/voice` 命令参数选择 STT 后端，持久化到 settings.json
## 二、用户交互
| 操作 | 行为 |
|------|------|
| 长按空格 | 开始录音，显示录音状态 |
| 释放空格 | 停止录音，转录结果自动提交 |
| `/voice` | 切换语音模式开关（默认使用 Anthropic 后端） |
| `/voice doubao` | 启用语音模式并使用豆包 ASR 后端 |
| `/voice anthropic` | 切换回 Anthropic STT 后端 |
### UI 反馈
- **录音指示器**：录音时显示红色/脉冲动画
- **中间转录**：录音过程中显示 STT 实时识别文本
- **最终转录**：完成后替换中间结果
## 三、实现架构
### 3.1 门控逻辑
文件：`src/voice/voiceModeEnabled.ts`
两层检查函数：
```ts
// Anthropic 后端（需要 OAuth）
isVoiceModeEnabled() = hasVoiceAuth() && isVoiceGrowthBookEnabled()
// 豆包后端 / 通用可用性检查（不需要 OAuth）
isVoiceAvailable() = isVoiceGrowthBookEnabled()
```
1. **Feature Flag**：`feature('VOICE_MODE')` — 编译时/运行时开关
2. **GrowthBook Kill-Switch**：`!getFeatureValue_CACHED_MAY_BE_STALE('tengu_amber_quartz_disabled', false)` — 紧急关闭开关（默认 false = 未禁用）
3. **Auth 检查（仅 Anthropic）**：`hasVoiceAuth()` — 需要 Anthropic OAuth token（非 API key）
4. **Provider 检查**：`voiceProvider` 设置决定使用哪个后端，豆包后端跳过 OAuth 检查
### 3.2 核心模块
| 模块 | 职责 |
|------|------|
| `src/voice/voiceModeEnabled.ts` | Feature flag + GrowthBook + Auth 三层门控 |
| `src/hooks/useVoice.ts` | React hook 管理录音状态和后端连接 |
| `src/services/voiceStreamSTT.ts` | Anthropic WebSocket 流式 STT |
| `src/services/doubaoSTT.ts` | 豆包 ASR 适配器（AsyncGenerator → VoiceStreamConnection） |
| `src/commands/voice/voice.ts` | `/voice` 命令实现，处理后端选择和持久化 |
| `src/hooks/useVoiceEnabled.ts` | 语音启用状态 hook，根据 provider 决定是否跳过 OAuth |
| `src/utils/settings/types.ts` | `voiceProvider: 'anthropic' | 'doubao'` 设置类型定义 |
### 3.3 数据流
#### Anthropic 后端
```
用户按下空格键
│
▼
useVoice hook 激活
│
▼
macOS 原生音频 / SoX 开始录音
│
▼
WebSocket 连接到 Anthropic STT 端点
│
├──→ 中间转录结果 → 实时显示
│
▼
用户释放空格键
│
▼
停止录音，等待最终转录
│
▼
转录文本 → 插入输入框 → 自动提交
```
#### 豆包 ASR 后端
```
用户按下空格键
│
▼
useVoice hook 激活（检测到 voiceProvider === 'doubao'）
│
▼
macOS 原生音频 / SoX 开始录音
│
▼
connectDoubaoStream() 创建 AudioChunkQueue + VoiceStreamConnection
│
├──→ onReady 立即触发（无需等待握手）
│
▼
音频数据通过 AudioChunkQueue 传入 transcribeRealtime()
│
├──→ INTERIM_RESULT → 实时显示中间转录
├──→ FINAL_RESULT → 显示最终转录
│
▼
用户释放空格键
│
▼
finalize() 立即返回（豆包在录音过程中已返回结果，无需等待）
│
▼
转录文本 → 插入输入框 → 自动提交
```
### 3.4 音频录制
支持两种音频后端（两个 STT 后端共享）：
- **macOS 原生音频**：优先使用，低延迟
- **SoX（Sound eXchange）**：回退方案，跨平台
### 3.5 豆包 ASR 适配器设计
文件：`src/services/doubaoSTT.ts`
豆包后端使用适配器模式，将 `doubaoime-asr` 的 AsyncGenerator 协议桥接到 `VoiceStreamConnection` 接口：
**AudioChunkQueue** — push 式异步队列：
- 实现 `AsyncIterable<Uint8Array>` 接口
- `push(chunk)` 将音频数据入队，`push(null)` 发送结束信号
- 内部维护等待者（waiting）和缓冲队列（chunks）两个状态
**connectDoubaoStream()** — 连接入口：
- 动态导入 `doubaoime-asr`（optionalDependencies）
- 从 `~/.claude/tts/doubao/credentials.json` 加载凭证
- 创建 AudioChunkQueue 和 VoiceStreamConnection
- 立即触发 `onReady`（避免与 useVoice 的音频缓冲死锁）
- `finalize()` 立即返回（豆包在录音过程中已返回结果）
- 后台 async IIFE 消费 `transcribeRealtime` generator，映射响应类型到回调
**响应类型映射**：
| doubaoime-asr ResponseType | 回调映射 |
|----------------------------|----------|
| SESSION_STARTED | 日志记录 |
| VAD_START | 日志记录 |
| INTERIM_RESULT | `onTranscript(text, false)` |
| FINAL_RESULT | `onTranscript(text, true)` |
| ERROR | `onError(errorMsg)` |
| SESSION_FINISHED | 日志记录 |
### 3.6 后端选择逻辑
文件：`src/hooks/useVoice.ts`
```ts
// 判断当前 provider
isDoubaoProvider() → 读取 settings.voiceProvider
// handleKeyEvent 中的可用性检查
const sttAvailable = isDoubaoProvider()
? isDoubaoAvailableSync() // 乐观检查（首次返回 true）
: isVoiceStreamAvailable() // Anthropic WebSocket 检查
// attemptConnect 中的连接函数选择
const connectFn = isDoubaoProvider()
? connectDoubaoStream
: connectVoiceStream
```
豆包后端的特殊处理：
- 跳过 `getVoiceKeyterms()` 调用（豆包无需关键词提示）
- 跳过 Focus Mode（`if (!enabled || !focusMode || isDoubaoProvider())`）
## 四、关键设计决策
1. **双后端共存**：豆包后端作为独立适配器与 Anthropic 后端并存，不替换原有流程，通过 `voiceProvider` 设置切换
2. **设置持久化**：`voiceProvider` 存储在 `settings.json`，通过 `/voice` 命令修改，跨会话生效
3. **OAuth 独占（Anthropic）**：Anthropic 后端使用 `voice_stream` 端点（claude.ai），仅 OAuth 用户可用
4. **豆包无需 OAuth**：豆包后端使用独立凭证文件，不依赖 Anthropic 认证，通过 `isVoiceAvailable()` 放宽门控
5. **GrowthBook 负向门控**：`tengu_amber_quartz_disabled` 默认 `false`，新安装自动可用
6. **onReady 立即触发**：豆包后端在连接建立后立即触发 `onReady`，避免与 useVoice 音频缓冲的时序死锁（Anthropic 需要等待 WebSocket 握手）
7. **finalize() 立即返回**：豆包在录音过程中已返回所有结果，用户抬手时无需等待处理
8. **乐观可用性检查**：`isDoubaoAvailableSync()` 在首次调用时返回 `true`，实际导入错误在 `connectDoubaoStream` 中处理
9. **optionalDependencies**：`doubaoime-asr` 作为可选依赖，安装失败不影响 Anthropic 后端
## 五、使用方式
```bash
# 启用 feature
FEATURE_VOICE_MODE=1 bun run dev
# 在 REPL 中使用 Anthropic 后端
# 1. 确保已通过 OAuth 登录（claude.ai 订阅）
# 2. 输入 /voice 启用
# 3. 按住空格键说话
# 4. 释放空格键等待转录
# 在 REPL 中使用豆包 ASR 后端
# 1. 确保 doubaoime-asr 已安装（bun add doubaoime-asr）
# 2. 配置凭证文件：~/.claude/tts/doubao/credentials.json
# 3. 输入 /voice doubao 启用
# 4. 按住空格键说话
# 5. 释放空格键，转录结果即刻显示
# 切换后端
/voice doubao # 切换到豆包 ASR
/voice anthropic # 切换回 Anthropic STT
/voice # 关闭语音模式
```
### 豆包凭证配置
凭证文件路径：`~/.claude/tts/doubao/credentials.json`
```json
{
"deviceId": "...",
"installId": "...",
"cdid": "...",
"openudid": "...",
"clientudid": "...",
"token": "..."
}
```
## 六、外部依赖
| 依赖 | 说明 | 适用后端 |
|------|------|----------|
| Anthropic OAuth | claude.ai 订阅登录，非 API key | Anthropic |
| GrowthBook | `tengu_amber_quartz_disabled` 紧急关闭 | 通用 |
| macOS 原生音频 或 SoX | 音频录制 | 通用 |
| Nova 3 STT | Anthropic 语音转文本模型 | Anthropic |
| doubaoime-asr | 豆包 ASR SDK（optionalDependencies） | 豆包 |
| 凭证文件 | `~/.claude/tts/doubao/credentials.json` | 豆包 |
## 七、文件索引
| 文件 | 职责 |
|------|------|
| `src/voice/voiceModeEnabled.ts` | 三层门控逻辑 + `isVoiceAvailable()` |
| `src/hooks/useVoice.ts` | React hook（录音状态 + 后端选择 + 连接管理） |
| `src/hooks/useVoiceEnabled.ts` | 语音启用状态 hook（按 provider 决定 OAuth 检查） |
| `src/services/voiceStreamSTT.ts` | Anthropic STT WebSocket 流式传输 |
| `src/services/doubaoSTT.ts` | 豆包 ASR 适配器（AudioChunkQueue + connectDoubaoStream） |
| `src/commands/voice/voice.ts` | `/voice` 命令（开关 + 后端选择） |
| `src/commands/voice/index.ts` | 命令注册（去除 availability 限制） |
| `src/utils/settings/types.ts` | `voiceProvider` 类型定义 |

75
docs/features/external/web-browser-tool.md vendored Normal file
View File

@@ -0,0 +1,75 @@
---
title: "浏览器操作工具"
description: "让 AI 控制 Chrome 完成网页操作：导航、点击、输入、抓取。"
keywords: ["浏览器工具", "Chrome 控制", "网页操作", "Bun WebView", "WEB_BROWSER_TOOL"]
---
# WEB_BROWSER_TOOL — 浏览器工具
> Feature Flag: `FEATURE_WEB_BROWSER_TOOL=1`
> 实现状态：核心工具已实现，面板为 Stub，布线完整
> 引用数：4
## 一、功能概述
WEB_BROWSER_TOOL 让模型可以启动浏览器实例、导航网页、与页面元素交互。使用 Bun 的内置 WebView API 提供无头/有头浏览器能力。
## 二、实现架构
### 2.1 模块状态
| 模块 | 文件 | 状态 |
|------|------|------|
| 浏览器面板 | `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserPanel.ts` | **Stub** — 返回 null |
| 浏览器工具 | `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserTool.ts` | **已实现** |
| REPL 集成 | `src/screens/REPL.tsx` | **布线** — 渲染 WebBrowserPanel |
| 工具注册 | `src/tools.ts` | **布线** — 动态加载 |
| WebView 检测 | `src/main.tsx` | **布线** — `'WebView' in Bun` 检测 |
### 2.2 预期数据流
```
模型调用 WebBrowserTool
│
▼
Bun WebView 创建浏览器实例
│
├── navigate(url) — 导航到 URL
├── click(selector) — 点击元素
├── screenshot() — 截取页面截图
└── extract(selector) — 提取页面内容
│
▼
结果返回给模型
│
▼
WebBrowserPanel 在 REPL 侧边显示浏览器状态
```
## 三、需要补全的内容
| 模块 | 工作量 | 说明 |
|------|--------|------|
| `WebBrowserTool.ts` | ✅ 已实现 | 工具 schema + Bun WebView API 执行 |
| `WebBrowserPanel.tsx` | 中 | REPL 侧边栏浏览器状态面板（仍为 Stub） |
## 四、关键设计决策
1. **Bun WebView API**：使用 Bun 内置的 WebView 而非外部浏览器驱动（Puppeteer/Playwright）
2. **REPL 侧边面板**：浏览器状态在 REPL 布局中独立渲染
3. **Bun 特性检测**：`'WebView' in Bun` 检查运行时是否支持
## 五、使用方式
```bash
FEATURE_WEB_BROWSER_TOOL=1 bun run dev
```
## 六、文件索引
| 文件 | 职责 |
|------|------|
| `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserPanel.ts` | 面板组件（stub） |
| `packages/builtin-tools/src/tools/WebBrowserTool/WebBrowserTool.ts` | 工具实现（已实现） |
| `src/screens/REPL.tsx:471,5676` | 面板渲染 |
| `src/tools.ts:115-116` | 工具注册 |