docs: 添加文档大纲及 superpowers/outline 目录

Co-Authored-By: deepseek-v4-pro <deepseek-ai@claude-code-best.win>
2026-06-23 16:55:51 +00:00 · 2026-06-15 16:17:03 +08:00
parent 37dac682b9
commit 178868175e
39 changed files with 9972 additions and 0 deletions
--- a/docs/outline-output/user/08-bridge-rcs-acp.md
+++ b/docs/outline-output/user/08-bridge-rcs-acp.md
@@ -0,0 +1,271 @@
+# 第八章：跨机器与跨团队协作 -- Bridge、Remote Control、ACP
+
+> 让 Claude 从另一台机器、浏览器或 IDE 里被操控。
+
+## Bridge 模式与 Remote Control -- 在浏览器里用 Claude
+
+Bridge 模式是 Claude Code 的远程控制核心。启用后，你的本地 Claude Code 会话可以被远程客户端（浏览器、Web UI、其他工具）访问和操控。这在你想从另一台机器控制本地的 Claude，或者让团队成员在浏览器里审批权限请求时特别有用。
+
+Bridge 由 `BRIDGE_MODE` feature flag 控制，dev 模式和默认构建都已启用。你不需要额外做任何事来开启它，只需要使用对应命令即可。
+
+有两种常见的启动方式。第一种是从 REPL 内部启动：在 Claude Code 的对话中输入 `/remote-control`，它会将当前会话桥接到远程控制服务，并在终端显示一个 URL。
+
+```
+> /remote-control
+Remote Control connecting...
+This session is available via Remote Control at https://rcs.example.com/code?bridge=abc123
+```
+
+再次输入 `/remote-control` 会弹出对话框，提供三个选项：断开连接、显示二维码（方便手机扫码）、或继续当前连接。
+
+第二种方式是通过命令行直接启动，这会进入"环境型"Remote Control 模式，注册一个可被分配工作的环境：
+
+```bash
+# 以下五个命令完全等价
+claude remote-control
+claude rc
+claude remote
+claude sync
+claude bridge
+```
+
+启动后，终端会持续轮询任务，等待远程客户端分配工作。浏览器打开终端显示的 URL 后即可创建会话、发送消息、审批权限请求。
+
+### 自托管 Remote Control Server (RCS)
+
+RCS 是 Bridge 模式的服务端，负责接收 CLI 的注册、分发任务、转发消息。它可以部署在你自己的服务器上，所有数据流经你控制的网络，不经过任何第三方基础设施。
+
+RCS 是一个纯内存的 HTTP + WebSocket 服务，基于 Hono 框架构建。它支持两套传输协议：V1 的 WebSocket 长连接和 V2 的 SSE + HTTP POST。
+
+部署 RCS 最简单的方式是 Docker。在项目根目录执行：
+
+```bash
+docker build -t rcs:latest -f packages/remote-control-server/Dockerfile .
+```
+
+然后启动容器：
+
+```bash
+docker run -d \
+  --name rcs \
+  -p 3000:3000 \
+  -e RCS_API_KEYS=sk-rcs-your-secret-key-here \
+  -e RCS_BASE_URL=https://rcs.example.com \
+  --restart unless-stopped \
+  rcs:latest
+```
+
+也可以用 Docker Compose：
+
+```yaml
+version: "3.8"
+services:
+  rcs:
+    build:
+      context: .
+      dockerfile: packages/remote-control-server/Dockerfile
+    ports:
+      - "3000:3000"
+    environment:
+      - RCS_API_KEYS=sk-rcs-your-secret-key-here
+      - RCS_BASE_URL=https://rcs.example.com
+    restart: unless-stopped
+```
+
+RCS 的核心配置通过环境变量控制。`RCS_API_KEYS` 是唯一的必填项，它既是客户端认证的 API Key，也用于 JWT 令牌签名，务必设置一个足够强的密钥。
+
+在 Claude Code 这边，连接到自托管 RCS 只需要设置两个环境变量：
+
+```bash
+export CLAUDE_BRIDGE_BASE_URL="https://rcs.example.com"
+export CLAUDE_BRIDGE_OAUTH_TOKEN="sk-rcs-your-secret-key-here"
+```
+
+设置 `CLAUDE_BRIDGE_BASE_URL` 后，代码会自动识别为自托管模式，跳过所有云端门控检查，不需要 claude.ai 账户。之后正常启动 Claude Code 并执行 `/remote-control` 即可。
+
+如果你使用反向代理（Nginx 或 Caddy），需要确保代理支持 WebSocket 升级：
+
+```nginx
+server {
+    listen 443 ssl;
+    server_name rcs.example.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_read_timeout 86400s;
+    }
+}
+```
+
+Caddy 会自动处理 WebSocket 升级，配置更简单：
+
+```
+rcs.example.com {
+    reverse_proxy localhost:3000
+}
+```
+
+### RCS Web UI
+
+RCS 自带一个 Web 控制面板，通过 `/code/*` 路径访问。它是一个 React 19 + Vite + Radix UI 构建的单页应用，支持暗色和亮色主题切换。
+
+Web UI 提供的核心功能包括：
+
+- 查看所有已注册的运行环境，区分 Claude Code 和 ACP Agent 类型
+- 创建和管理远程会话，实时查看对话消息和工具调用
+- 审批 Claude Code 的工具权限请求，支持六种权限模式切换
+- 查看 Plan 可视化，包含进度条、状态图标和优先级标签
+- 查看 Autopilot 状态（`standby` 等待下一轮、`sleeping` 模型休眠中）
+- 通过 QR 码扫码快速连接
+
+Web UI 使用 UUID 认证，无需用户账户系统，适合部署在受信任的内网环境中。
+
+## ACP 协议 -- 把 Claude Code 接入 IDE
+
+ACP（Agent Client Protocol）是一种标准化的 stdio 协议，允许 IDE 和编辑器通过 stdin/stdout 的 NDJSON 流驱动 AI Agent。Claude Code 实现了完整的 ACP agent 端，可以被 Zed、Cursor 等支持 ACP 的客户端直接调用。
+
+启用 ACP 模式只需要 `--acp` 参数。它是一个 CLI 快速路径（位于 `src/entrypoints/cli.tsx` 中），由 `FEATURE_ACP` feature flag 控制。
+
+```bash
+claude --acp
+```
+
+启动后，Claude Code 不再进入 REPL，而是通过 stdin/stdout 与 ACP 客户端通信。所有 console 输出都被重定向到 stderr，避免干扰 ACP 的 NDJSON 协议流。
+
+### 在 Zed 中接入 Claude Code
+
+Zed 是最典型的 ACP 客户端。打开 Zed 的设置（`Cmd+,`），在 `settings.json` 中添加：
+
+```json
+{
+  "agent_servers": {
+    "claude-code": {
+      "type": "custom",
+      "command": "claude",
+      "args": ["--acp"]
+    }
+  }
+}
+```
+
+如果你需要显式传入 API 凭证（而不是依赖 `settings.json` 中的配置），可以在 `env` 字段中指定：
+
+```json
+{
+  "agent_servers": {
+    "claude-code": {
+      "command": "claude",
+      "args": ["--acp"],
+      "env": {
+        "ANTHROPIC_BASE_URL": "https://api.example.com/v1",
+        "ANTHROPIC_AUTH_TOKEN": "sk-xxx"
+      }
+    }
+  }
+}
+```
+
+重启 Zed 后，按 `Cmd+'` 打开 Agent Panel，在顶部下拉菜单中选择 "claude-code" 即可开始对话。
+
+在 ACP 模式下，Claude Code 支持完整的会话管理（新建、恢复、加载、分叉、关闭）、斜杠命令和 Skills（输入 `/` 查看列表，如 `/commit`、`/review`）、权限审批、模型切换和模式切换。当 Zed 重启时，之前的会话可以自动恢复并回放历史消息。
+
+### 权限模式与 ACP 权限管道
+
+ACP 模式下的权限系统与 REPL 模式略有不同。当 Claude 需要使用某个工具时，权限请求会被转发到 ACP 客户端（如 Zed），由用户在 IDE 中选择 Allow、Reject 或 Always Allow。
+
+支持六种权限模式：`default`（每次确认）、`auto`（自动判断）、`acceptEdits`（自动接受文件编辑）、`plan`（规划模式）、`dontAsk`（不询问，未预批准则拒绝）、`bypassPermissions`（绕过所有权限检查，仅在非 root 或 sandbox 环境下可用）。
+
+权限模式可以通过环境变量设置默认值：
+
+```bash
+ACP_PERMISSION_MODE=auto claude --acp
+```
+
+也可以在 ACP 客户端中动态切换。当 Claude 处于 Plan 模式并执行退出计划时，ACP 会显示一个特殊的选项面板，让你选择退出后进入哪种模式（auto、acceptEdits、default、plan、bypassPermissions）。
+
+## acp-link -- 通过网络暴露 ACP Agent
+
+ACP 协议本身基于 stdio，意味着 ACP agent 只能在本机使用。`acp-link` 是一个 WebSocket 代理服务器，将远程 WebSocket 客户端桥接到本地 ACP agent 的 stdio 接口，让 ACP agent 可以通过网络访问。
+
+### 独立使用
+
+最基本的用法：启动 acp-link，让它管理一个 ACP agent 子进程：
+
+```bash
+acp-link claude --acp
+```
+
+默认监听 `localhost:9315`。你也可以指定端口和主机：
+
+```bash
+acp-link --port 9000 --host 0.0.0.0 claude --acp
+```
+
+启用 HTTPS（自动生成自签名证书）：
+
+```bash
+acp-link --https claude --acp
+```
+
+acp-link 启动后会自动生成一个随机认证 token。WebSocket 客户端通过 `rcs.auth.<base64url-token>` 子协议传递 token。如果需要固定 token：
+
+```bash
+ACP_AUTH_TOKEN=my-fixed-token acp-link claude --acp
+```
+
+开发环境下可以禁用认证（不推荐在生产环境使用）：
+
+```bash
+acp-link --no-auth claude --acp
+```
+
+### 与 RCS 集成
+
+acp-link 可以将 ACP agent 注册到 RCS，通过 RCS 的 Web UI 进行交互。设置两个环境变量即可：
+
+```bash
+ACP_RCS_URL=http://localhost:3000 \
+ACP_RCS_TOKEN=sk-rcs-your-key \
+acp-link claude --acp
+```
+
+注册流程分两步：首先通过 REST API 向 RCS 注册环境，然后建立 WebSocket 连接并发送 identify 消息。之后 ACP agent 会出现在 RCS Web UI 的环境列表中，与普通 Claude Code 会话一起管理和监控。
+
+## IDE 集成 -- 在编辑器里使用 Claude Code
+
+除了通过 ACP 协议接入 Zed 等原生 ACP 客户端，Claude Code 还提供 `/ide` 命令，帮助检测和连接正在运行的 IDE。这个命令会自动扫描本地已安装的 IDE（包括 JetBrains 系列和各种终端），并提供选择界面。
+
+在 REPL 中输入：
+
+```
+/ide
+```
+
+Claude Code 会检测本地运行的 IDE 和支持的终端，让你选择要连接的目标。连接后，Claude Code 可以通过 IDE 的 Language Server Protocol 获取代码上下文，提供更精准的编辑建议。
+
+## SSH 远程模式
+
+`SSH_REMOTE` feature 允许 Claude Code 通过 SSH 在远程机器上工作。在 main.tsx 中通过 `feature('SSH_REMOTE')` 控制，当启用时会接管 `--ssh` 参数和相关的 SSH 连接逻辑。
+
+启用 SSH 远程模式后，Claude Code 可以在远程机器上启动会话，通过 SSH 隧道保持通信。这对于在服务器或 CI 环境中使用 Claude Code 特别有用。`/remote-setup` 命令提供辅助设置流程，`/remote-env` 命令提供远程环境管理界面。
+
+## 常见问题
+
+**Remote Control is not available in this build** -- `BRIDGE_MODE` feature flag 未启用。使用 dev 模式（`bun run dev`）默认启用，或确保构建时包含该 flag。
+
+**认证失败 (401 Unauthorized)** -- 检查 `CLAUDE_BRIDGE_OAUTH_TOKEN` 是否与 RCS 的 `RCS_API_KEYS` 中的值完全匹配，注意排除多余空格或换行。
+
+**WebSocket 连接中断** -- 如果使用反向代理，确认已配置 WebSocket 升级（`Upgrade` / `Connection` 头），`proxy_read_timeout` 建议设为 86400 秒。
+
+**RCS 重启后数据丢失** -- RCS 使用纯内存存储，重启后所有会话和环境数据都会清除。`/app/data` 卷已预留但当前未使用。
+
+## 下一步
+
+- 想配置 Provider 和模型，看 [第二章](./02-providers.md)
+- 想了解权限模式和安全配置，看 [第九章](./09-budget-caching-hooks.md)
+- 想在 CI 流水线中使用 Claude Code，看 [第十一章](./11-ci-integration.md)
+- 想处理连接问题和其他报错，看 [第十章](./10-troubleshooting.md)