From 4ccca345d4eeed9b98cc908f97d4d35c431dc57e Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 15:32:35 +0800 Subject: [PATCH 01/15] =?UTF-8?q?=E6=96=B0=E5=A2=9E=20Claude=20Code=20Remo?= =?UTF-8?q?te=20Control=20=E4=B8=93=E9=A2=98=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增 08-remote-control.md：完整介绍 Remote Control 功能 - 三种启动方式（Server 模式 / 交互式 / 会话内启用） - 连接与安全架构（出站 HTTPS polling + Anthropic 中继） - 与 Claude Code on the Web 的区别对比 - 跨设备工作流全景（Dispatch / Remote Control / Channels / Slack / Schedule） - 前置条件、环境变量、限制与故障排查 - 行业对比（18 款 Agent 中 Claude Code 独有） - 更新索引：Claude Code 文档目录和 README 导航 Co-authored-by: Qwen-Coder --- README.md | 2 +- docs/tools/claude-code/08-remote-control.md | 203 ++++++++++++++++++++ docs/tools/claude-code/README.md | 1 + 3 files changed, 205 insertions(+), 1 deletion(-) create mode 100644 docs/tools/claude-code/08-remote-control.md diff --git a/README.md b/README.md index 214649ea..8d42445a 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@
Agent 详情（源码级）— 8 个专题 - **[Agent 索引](./docs/tools/)** — 18 个 Agent 的详细分析 -- **[Claude Code](./docs/tools/claude-code/)** — 7 篇（79 命令/架构/Skill+13 插件/24 Hook/会话） +- **[Claude Code](./docs/tools/claude-code/)** — 8 篇（79 命令/架构/Skill+13 插件/24 Hook/会话/Remote Control） - **[Copilot CLI](./docs/tools/copilot-cli/)** — 3 篇（34 命令 + 67 工具 + 3 代理） - **[Codex CLI](./docs/tools/codex-cli/)** — 3 篇（28 命令 + 三平台沙箱） - **[Gemini CLI](./docs/tools/gemini-cli/)** — 5 篇（39 命令/8 策略路由/策略引擎） diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md new file mode 100644 index 00000000..74728fb9 --- /dev/null +++ b/docs/tools/claude-code/08-remote-control.md @@ -0,0 +1,203 @@ +# 8. Claude Code Remote Control（远程控制） + +> Remote Control 允许从手机、平板或任意浏览器远程操控本地运行的 Claude Code 终端会话。会话**始终在本地执行**，远程端仅作为交互窗口。基于 Anthropic 官方文档（2026-03）和 v2.1.81 二进制反编译分析。 + +## 概述 + +Remote Control 是 Claude Code 的跨设备会话桥接功能，在 18 款主流 AI 编程 Agent 中**为 Claude Code 独有**（源码: `docs/comparison/features.md`）。它解决了开发者的一个核心痛点：启动了一个长时间的终端代理任务后，需要离开工位继续监控或干预。 + +核心特性： + +- **本地执行，远程操控**：会话运行在本地机器上，完整的文件系统、MCP 服务器、工具链、项目配置均可使用 +- **实时双向同步**：所有连接设备的对话保持同步，可在任意设备上发送消息 +- **自动重连**：笔记本电脑睡眠或网络短暂中断后自动恢复连接 +- **零入站端口**：所有通信通过出站 HTTPS 完成，无需开放防火墙端口 + +## 前置条件 + +| 要求 | 详情 | +|------|------| +| **版本** | Claude Code v2.1.51+（`claude --version` 检查） | +| **订阅** | Pro / Max / Team / Enterprise 计划。**API Key 不支持** | +| **认证方式** | 必须通过 claude.ai OAuth 登录（`/login`），不支持 API Key 或 `claude setup-token` | +| **工作区信任** | 需在项目目录中至少运行一次 `claude` 以接受工作区信任对话框 | +| **Team/Enterprise** | 管理员需在 `claude.ai/admin-settings/claude-code` 中启用 Remote Control 开关 | + +## 三种启动方式 + +### 方式一：Server 模式（专用服务） + +```bash +claude remote-control +claude remote-control --name "My Project" +``` + +运行一个专用的 Remote Control 服务器，等待远程连接。终端显示会话 URL，按 **空格键** 可显示 QR 码。 + +**可用参数：** + +| 参数 | 说明 | +|------|------| +| `--name <名称>` | 自定义会话标题，在会话列表中可见 | +| `--spawn <模式>` | `same-dir`（默认）：所有会话共享 CWD；`worktree`：每个会话获得独立 Git worktree | +| `--capacity ` | 最大并发会话数（默认：32） | +| `--verbose` | 详细连接/会话日志 | +| `--sandbox` / `--no-sandbox` | 启用/禁用文件系统和网络沙箱（默认关闭） | + +### 方式二：交互式会话 + Remote Control + +```bash +claude --remote-control # 或 --rc +claude --remote-control "My Project" # 带名称 +``` + +在终端中启动一个完整的交互式会话，同时可通过远程设备操控。可以本地输入，远程客户端也可以同时连接。 + +### 方式三：从已有会话启用 + +``` +/remote-control # 或 /rc +/remote-control My Project +``` + +在当前对话中启用 Remote Control。此方式不支持 `--verbose`、`--sandbox`、`--no-sandbox` 参数。 + +> **源码位置**：`/remote-control` 命令类型为 `local-jsx`（反编译提取，`源码: docs/tools/claude-code/02-commands.md`），渲染远程控制配置 UI 并启动到 claude.ai/code 的连接。 + +## 从其他设备连接 + +三种连接方式： + +| 方式 | 操作 | +|------|------| +| **会话 URL** | 在任意浏览器中打开，跳转到 `claude.ai/code` | +| **QR 码** | 用 Claude App 扫描（Server 模式下按空格键切换显示） | +| **会话列表** | 在 `claude.ai/code` 或 Claude App 中按名称查找；在线的 Remote Control 会话显示**带绿点的电脑图标** | + +**会话标题优先级**（依次递减）： +1. `--name` / `--remote-control` / `/remote-control` 参数指定的名称 +2. 通过 `/rename` 设置的标题 +3. 对话历史中最后一条有意义消息的内容 +4. 用户发送的第一条 prompt + +## 全局默认启用 + +在 Claude Code 中运行 `/config` → 将 **"Enable Remote Control for all sessions"** 设为 `true`。此后每个交互式进程自动注册一个远程会话。如需一个进程中多个并发会话，使用 **Server 模式** 加 `--spawn`。 + +## 连接与安全架构 + +### 网络拓扑 + +``` +┌─────────────┐ 出站 HTTPS ┌──────────────────┐ +│ 本地终端 │ ──────────────────────────→ │ Anthropic API │ +│ (Claude Code)│ ←────────────────────────── │ (消息中继) │ +└─────────────┘ 流式响应 └───────┬──────────┘ + │ + 出站 HTTPS │ + │ + ┌───────▼──────────┐ + │ 浏览器/手机 App │ + │ (claude.ai/code) │ + └──────────────────┘ +``` + +| 方面 | 细节 | +|------|------| +| **网络方向** | 仅出站 HTTPS——**本地不开放入站端口** | +| **通信机制** | 本地进程向 Anthropic API 注册并**轮询获取工作**（polling） | +| **消息路由** | Anthropic 服务器在 Web/Mobile 客户端和本地会话之间通过**流式连接**中继消息 | +| **传输安全** | 所有流量经 Anthropic API 传输，全程 **TLS** 加密（与普通 Claude Code 会话相同） | +| **凭证** | 使用**多个短期凭证**，每个凭证限定单一用途且独立过期 | + +> **注意**：并非直接向本地机器建立 WebSocket 连接。本地进程通过 polling Anthropic API 获取消息，消息经由 Anthropic 基础设施中继。 + +### 相关环境变量（反编译提取） + +| 变量 | 影响 | +|------|------| +| `ANTHROPIC_API_KEY` | 阻止 Remote Control；需清除并使用 OAuth 登录 | +| `CLAUDE_CODE_OAUTH_TOKEN` | 提供有限范围 token；与 Remote Control 不兼容 | +| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 可能破坏资格检查 | +| `DISABLE_TELEMETRY` | 可能破坏资格检查 | +| `CLAUDE_CODE_USE_BEDROCK` | 不兼容——Remote Control 要求 claude.ai 认证 | +| `CLAUDE_CODE_USE_VERTEX` | 不兼容——Remote Control 要求 claude.ai 认证 | +| `CLAUDE_CODE_USE_FOUNDRY` | 不兼容——Remote Control 要求 claude.ai 认证 | +| `SESSION_ACCESS_TOKEN` | 会话访问凭证（反编译提取，`源码: EVIDENCE.md`） | +| `WEBSOCKET_AUTH_*` | WebSocket 认证相关凭证（反编译提取） | + +## Remote Control vs Claude Code on the Web + +两者经常混淆，但本质不同： + +| | Remote Control | Claude Code on the Web | +|---|---|---| +| **执行位置** | 你的本地机器 | Anthropic 云端基础设施 | +| **本地工具/MCP** | ✅ 可用（文件系统、MCP 服务器等） | ❌ 不可用 | +| **安装要求** | 需要本地运行 Claude Code 进程 | 无需本地安装 | +| **适合场景** | 在其他设备上继续进行中的工作 | 无本地环境时启动新任务，并行任务 | +| **启动方式** | `claude remote-control` / `--rc` / `/rc` | `claude --remote "任务描述"` | +| **反向操作** | — | `claude --teleport`（拉回 Web 会话到终端） | + +### 跨设备工作流全景 + +Claude Code 提供了多种跨设备工作方式，各有侧重： + +| 方式 | 触发方式 | 运行位置 | 适用场景 | +|------|----------|----------|----------| +| **Dispatch** | 从 Claude Mobile App 发送消息 | 本地机器（Desktop） | 离开工位时委派任务 | +| **Remote Control** | 从浏览器/Mobile 操控运行中的会话 | 本地机器（CLI/VS Code） | 远程操控进行中的工作 | +| **Channels** | 从 Telegram/Discord 推送事件 | 本地机器（CLI） | 响应外部事件 | +| **Slack** | 团队频道中 `@Claude` 提及 | Anthropic 云端 | 从团队聊天处理 PR/审查 | +| **Scheduled Tasks** | 设置定时计划 | CLI / Desktop / 云端 | 周期性自动化 | +| **`--remote`** | CLI 推送任务到 Web | Anthropic 云端 | 启动 Web 会话 | +| **`--teleport`** | CLI 拉回 Web 会话 | 本地机器 | 将云端会话拉到本地继续 | + +## 限制 + +| 限制 | 说明 | +|------|------| +| **单远程会话/进程** | 交互模式（非 Server 模式）下每个进程仅一个远程会话。需多会话时用 `--spawn` | +| **终端必须保持打开** | 关闭终端或终止进程会结束会话 | +| **网络超时** | 若机器在线但网络不可达持续约 10 分钟，会话超时并退出进程 | +| **不支持 API Key** | 必须使用 claude.ai OAuth 认证 | +| **不支持第三方提供商** | Bedrock / Vertex / Foundry 用户无法使用 | + +## 故障排查 + +| 错误信息 | 原因与解决 | +|----------|-----------| +| *"Requires a claude.ai subscription"* | 未通过 claude.ai 认证。运行 `claude auth login`，选择 claude.ai。如设置了 `ANTHROPIC_API_KEY` 需先清除 | +| *"Requires a full-scope login token"* | 使用了 `claude setup-token` 或 `CLAUDE_CODE_OAUTH_TOKEN` 产生的有限 token。运行 `claude auth login` 获取完整 session token | +| *"Unable to determine your organization"* | 缓存的账户信息过期。运行 `claude auth login` 刷新 | +| *"Not yet enabled for your account"* | 检查是否设置了 `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`、`DISABLE_TELEMETRY`、`CLAUDE_CODE_USE_BEDROCK` 等——清除它们。否则 `/logout` 后重新 `/login` | +| *"Disabled by your organization's policy"* | 三种原因：(1) 使用 API Key → 切换为 claude.ai OAuth；(2) Team/Enterprise 管理员未启用 `claude.ai/admin-settings/claude-code` 的开关；(3) 管理员开关灰色 → 数据保留/合规配置阻止，联系 Anthropic 支持 | +| *"Remote credentials fetch failed"* | 使用 `--verbose` 查看详情。常见：未登录、防火墙/代理阻止出站 HTTPS 443 端口、订阅不活跃 | + +## 与 `/session` 命令的关系 + +`/session`（别名 `/remote`）是另一个与远程相关的命令，但功能不同于 Remote Control： + +| 命令 | 功能 | +|------|------| +| `/remote-control` `/rc` | 启用双向远程控制——从浏览器/Mobile 实时操控终端会话 | +| `/session` `/remote` | 显示远程会话 URL 和 QR 码——用于在其他设备上查看/连接会话 | +| `/remote-env` | 配置远程环境设置（远程服务器上的 Claude Code 实例） | +| `/desktop` `/app` | 将当前会话转交到 Claude Desktop 应用继续 | +| `/mobile` `/ios` `/android` | 显示下载 Claude Mobile 应用的 QR 码 | + +## 行业对比 + +在 18 款对比的 AI 编程 Agent 中，Remote Control 为 **Claude Code 独有**功能： + +| Agent | 远程控制能力 | +|-------|-------------| +| **Claude Code** | ✅ `/remote-control` + Server 模式 + `--spawn` 多会话 | +| **Copilot CLI** | ❌ 无（有 VS Code 集成但无终端远程操控） | +| **Codex CLI** | ❌ 无 | +| **Gemini CLI** | ❌ 无 | +| **Qwen Code** | ❌ 无（`源码: docs/comparison/qwen-code-feature-gaps.md`，需从零构建） | +| **Kimi CLI** | ❌ 无（有 Wire 协议但未实现远程控制） | +| **其他 Agent** | ❌ 无 | + +> **免责声明**：以上数据基于 2026 年 Q1 源码分析和官方文档，可能已过时。Qwen Code 的 Remote Control 功能缺口已被标记为 P2 优先级。 diff --git a/docs/tools/claude-code/README.md b/docs/tools/claude-code/README.md index 919f31ef..54958005 100644 --- a/docs/tools/claude-code/README.md +++ b/docs/tools/claude-code/README.md @@ -11,3 +11,4 @@ | [05-Skill 系统](./05-skills.md) | Skill 定义、加载、内置 Skill | | [06-设置与安全](./06-settings.md) | 5 层设置、权限、沙箱、24 种 Hook 事件 | | [07-会话与记忆](./07-session.md) | 会话管理、记忆系统、MCP | +| [08-Remote Control](./08-remote-control.md) | 远程控制架构、使用方式、安全模型、跨设备对比 | From ed9cb87619e042652ab4f66b9590860148ad1a7b Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 15:50:09 +0800 Subject: [PATCH 02/15] =?UTF-8?q?=E5=AE=A1=E8=AE=A1=E4=BF=AE=E6=AD=A3?= =?UTF-8?q?=EF=BC=9ARemote=20Control=20=E6=96=87=E6=A1=A3=E6=9D=A5?= =?UTF-8?q?=E6=BA=90=E5=BD=92=E5=B1=9E=E4=B8=8E=20WebSocket=20=E6=8F=8F?= =?UTF-8?q?=E8=BF=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 明确区分官方文档来源 vs 二进制反编译来源（数据来源 blockquote） - 修正 02-commands.md：WebSocket→outbound HTTPS polling（与官方文档一致） - 修正 源码: 前缀误用：改为 Markdown 链接引用（符合 AGENTS.md 约定） - 环境变量表新增 来源 列，区分官方文档 vs EVIDENCE.md 反编译 - /teleport 补充 CLI 等价方式说明 Co-authored-by: Qwen-Coder --- docs/tools/claude-code/02-commands.md | 2 +- docs/tools/claude-code/08-remote-control.md | 38 ++++++++++++--------- 2 files changed, 22 insertions(+), 18 deletions(-) diff --git a/docs/tools/claude-code/02-commands.md b/docs/tools/claude-code/02-commands.md index e00783d9..a475cec4 100644 --- a/docs/tools/claude-code/02-commands.md +++ b/docs/tools/claude-code/02-commands.md @@ -924,7 +924,7 @@ Found 3 issues: **实现细节：** - 渲染远程控制配置 UI -- 启动 WebSocket 连接到 claude.ai/code +- 向 Anthropic API 注册并轮询获取工作（outbound HTTPS polling） - 允许在浏览器中操作终端会话 - 支持跨设备远程操作 diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index 74728fb9..f594111b 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -1,10 +1,12 @@ # 8. Claude Code Remote Control（远程控制） -> Remote Control 允许从手机、平板或任意浏览器远程操控本地运行的 Claude Code 终端会话。会话**始终在本地执行**，远程端仅作为交互窗口。基于 Anthropic 官方文档（2026-03）和 v2.1.81 二进制反编译分析。 +> Remote Control 允许从手机、平板或任意浏览器远程操控本地运行的 Claude Code 终端会话。会话**始终在本地执行**，远程端仅作为交互窗口。 +> +> **数据来源**：CLI 子命令/参数（`claude remote-control`、`--remote-control`/`--rc`、`--spawn`、`--capacity`）和故障排查指南来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)（2026-03）；`/remote-control` 斜杠命令类型来自 v2.1.81 二进制反编译；环境变量名来自 [EVIDENCE.md](./EVIDENCE.md) 反编译提取。 ## 概述 -Remote Control 是 Claude Code 的跨设备会话桥接功能，在 18 款主流 AI 编程 Agent 中**为 Claude Code 独有**（源码: `docs/comparison/features.md`）。它解决了开发者的一个核心痛点：启动了一个长时间的终端代理任务后，需要离开工位继续监控或干预。 +Remote Control 是 Claude Code 的跨设备会话桥接功能，在 18 款主流 AI 编程 Agent 中**为 Claude Code 独有**（[功能矩阵](../../comparison/features.md)）。它解决了开发者的一个核心痛点：启动了一个长时间的终端代理任务后，需要离开工位继续监控或干预。 核心特性： @@ -62,7 +64,7 @@ claude --remote-control "My Project" # 带名称 在当前对话中启用 Remote Control。此方式不支持 `--verbose`、`--sandbox`、`--no-sandbox` 参数。 -> **源码位置**：`/remote-control` 命令类型为 `local-jsx`（反编译提取，`源码: docs/tools/claude-code/02-commands.md`），渲染远程控制配置 UI 并启动到 claude.ai/code 的连接。 +> **命令类型**：`/remote-control` 斜杠命令类型为 `local-jsx`（[命令详解](./02-commands.md)），渲染远程控制配置 UI 并启动到 claude.ai/code 的连接。 ## 从其他设备连接 @@ -112,19 +114,21 @@ claude --remote-control "My Project" # 带名称 > **注意**：并非直接向本地机器建立 WebSocket 连接。本地进程通过 polling Anthropic API 获取消息，消息经由 Anthropic 基础设施中继。 -### 相关环境变量（反编译提取） +### 相关环境变量 -| 变量 | 影响 | -|------|------| -| `ANTHROPIC_API_KEY` | 阻止 Remote Control；需清除并使用 OAuth 登录 | -| `CLAUDE_CODE_OAUTH_TOKEN` | 提供有限范围 token；与 Remote Control 不兼容 | -| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 可能破坏资格检查 | -| `DISABLE_TELEMETRY` | 可能破坏资格检查 | -| `CLAUDE_CODE_USE_BEDROCK` | 不兼容——Remote Control 要求 claude.ai 认证 | -| `CLAUDE_CODE_USE_VERTEX` | 不兼容——Remote Control 要求 claude.ai 认证 | -| `CLAUDE_CODE_USE_FOUNDRY` | 不兼容——Remote Control 要求 claude.ai 认证 | -| `SESSION_ACCESS_TOKEN` | 会话访问凭证（反编译提取，`源码: EVIDENCE.md`） | -| `WEBSOCKET_AUTH_*` | WebSocket 认证相关凭证（反编译提取） | +前 6 项来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)；后 2 项为反编译提取的变量名（[EVIDENCE.md](./EVIDENCE.md)），具体用途为推断。 + +| 变量 | 影响 | 来源 | +|------|------|------| +| `ANTHROPIC_API_KEY` | 阻止 Remote Control；需清除并使用 OAuth 登录 | 官方文档 | +| `CLAUDE_CODE_OAUTH_TOKEN` | 提供有限范围 token；与 Remote Control 不兼容 | 官方文档 | +| `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 可能破坏资格检查 | 官方文档 | +| `DISABLE_TELEMETRY` | 可能破坏资格检查 | 官方文档 | +| `CLAUDE_CODE_USE_BEDROCK` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | +| `CLAUDE_CODE_USE_VERTEX` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | +| `CLAUDE_CODE_USE_FOUNDRY` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | +| `SESSION_ACCESS_TOKEN` | 认证相关凭证（反编译提取） | EVIDENCE.md | +| `WEBSOCKET_AUTH_*` | 认证相关凭证（反编译提取） | EVIDENCE.md | ## Remote Control vs Claude Code on the Web @@ -151,7 +155,7 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | **Slack** | 团队频道中 `@Claude` 提及 | Anthropic 云端 | 从团队聊天处理 PR/审查 | | **Scheduled Tasks** | 设置定时计划 | CLI / Desktop / 云端 | 周期性自动化 | | **`--remote`** | CLI 推送任务到 Web | Anthropic 云端 | 启动 Web 会话 | -| **`--teleport`** | CLI 拉回 Web 会话 | 本地机器 | 将云端会话拉到本地继续 | +| **`/teleport`** | 在 Web 端启动长任务后拉入终端 | 本地机器 | 将云端会话拉到本地继续（CLI 等价：`claude --teleport`） | ## 限制 @@ -196,7 +200,7 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | **Copilot CLI** | ❌ 无（有 VS Code 集成但无终端远程操控） | | **Codex CLI** | ❌ 无 | | **Gemini CLI** | ❌ 无 | -| **Qwen Code** | ❌ 无（`源码: docs/comparison/qwen-code-feature-gaps.md`，需从零构建） | +| **Qwen Code** | ❌ 无（[功能缺口分析](../../comparison/qwen-code-feature-gaps.md)，需从零构建） | | **Kimi CLI** | ❌ 无（有 Wire 协议但未实现远程控制） | | **其他 Agent** | ❌ 无 | From 878c00a5c94a32e4a821a59b6319353e885be302 Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 16:18:33 +0800 Subject: [PATCH 03/15] =?UTF-8?q?=E6=B7=B1=E5=BA=A6=E8=A1=A5=E5=85=A8?= =?UTF-8?q?=EF=BC=9ARemote=20Control=20=E6=8A=80=E6=9C=AF=E6=9E=B6?= =?UTF-8?q?=E6=9E=84=E3=80=81=E4=BC=9A=E8=AF=9D=E7=94=9F=E5=91=BD=E5=91=A8?= =?UTF-8?q?=E6=9C=9F=E3=80=81=E5=AE=89=E5=85=A8=E7=BA=B5=E6=B7=B1=E3=80=81?= =?UTF-8?q?=E5=B7=B2=E7=9F=A5=E9=97=AE=E9=A2=98?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增内容： - 三方中继架构图（本地 polling + Anthropic 中继 + 远程 WebSocket） - 会话生命周期状态机（注册→等待→活跃→空闲→过期） - 会话文件与本地存储（sessions/{pid}.json、Unix socket、jsonl 历史） - --spawn 多会话架构（same-dir vs worktree，与 CCR 云端会话的区别） - 安全模型 7 层纵深（认证→管理→凭证→网络→传输→沙箱→分类器） - 相关 API 端点（反编译提取的 5 个基础设施端点） - 已知架构问题 8 项（GitHub Issues 社区反馈：pidfile 竞态、遥测耦合、 僵尸进程、连接循环、stale WebSocket、VS Code 配置缺口等） - 新增 SSE_PORT 环境变量 数据来源：官方文档 + EVIDENCE.md 反编译 + GitHub Issues + Anthropic 工程博客 Co-authored-by: Qwen-Coder --- docs/tools/claude-code/08-remote-control.md | 146 +++++++++++++++++--- docs/tools/claude-code/README.md | 2 +- 2 files changed, 124 insertions(+), 24 deletions(-) diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index f594111b..7dc798f9 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -86,49 +86,134 @@ claude --remote-control "My Project" # 带名称 在 Claude Code 中运行 `/config` → 将 **"Enable Remote Control for all sessions"** 设为 `true`。此后每个交互式进程自动注册一个远程会话。如需一个进程中多个并发会话，使用 **Server 模式** 加 `--spawn`。 -## 连接与安全架构 +## 技术架构 -### 网络拓扑 +> 以下综合 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)、v2.1.81 二进制反编译（[EVIDENCE.md](./EVIDENCE.md)）、GitHub Issues 社区反馈和 Anthropic 工程博客分析。 + +### 三方中继架构 + +Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic API 充当消息代理： ``` -┌─────────────┐ 出站 HTTPS ┌──────────────────┐ -│ 本地终端 │ ──────────────────────────→ │ Anthropic API │ -│ (Claude Code)│ ←────────────────────────── │ (消息中继) │ -└─────────────┘ 流式响应 └───────┬──────────┘ - │ - 出站 HTTPS │ - │ - ┌───────▼──────────┐ - │ 浏览器/手机 App │ - │ (claude.ai/code) │ - └──────────────────┘ +┌──────────────┐ ① 出站 HTTPS (polling) ┌───────────────────────┐ +│ 本地终端 │ ────────────────────────────→ │ Anthropic API │ +│ (Claude Code)│ ←──────────────────────────── │ (消息中继/代理) │ +│ │ ② 流式响应 (streaming) │ │ +└──────────────┘ │ claude.ai/code │ + │ 会话注册 + 消息路由 │ + └───────────┬───────────┘ + │ + ③ WebSocket/HTTPS │ + │ + ┌───────────▼───────────┐ + │ 浏览器 / 手机 App │ + │ (claude.ai/code) │ + └───────────────────────┘ ``` +**数据流**： +1. **本地 → Anthropic API**：本地进程启动时用 full-scope OAuth token 注册会话，随后以 polling 方式持续获取待处理消息 +2. **Anthropic API → 本地**：服务器有消息时通过 streaming connection 下发（长轮询或 SSE over HTTPS） +3. **Anthropic API ↔ 浏览器/手机**：远程客户端通过 WebSocket 连接到 Anthropic 基础设施（GitHub Issues 中观察到 stale WebSocket 连接行为） + | 方面 | 细节 | |------|------| -| **网络方向** | 仅出站 HTTPS——**本地不开放入站端口** | -| **通信机制** | 本地进程向 Anthropic API 注册并**轮询获取工作**（polling） | -| **消息路由** | Anthropic 服务器在 Web/Mobile 客户端和本地会话之间通过**流式连接**中继消息 | -| **传输安全** | 所有流量经 Anthropic API 传输，全程 **TLS** 加密（与普通 Claude Code 会话相同） | -| **凭证** | 使用**多个短期凭证**，每个凭证限定单一用途且独立过期 | +| **本地→服务器** | 出站 HTTPS polling（非 WebSocket）。本地不开放入站端口 | +| **远程客户端→服务器** | WebSocket 连接到 Anthropic 基础设施（`WEBSOCKET_AUTH_*` 凭证认证） | +| **消息路由** | Anthropic 服务器在远程客户端和本地会话之间双向中继 | +| **传输安全** | 全程 TLS 加密，与普通 Claude Code 会话相同 | +| **凭证体系** | 多个短期凭证，每个限定单一用途，独立过期 | + +### 会话生命周期 + +``` +┌─────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ +│ 注册 │ ──→ │ 等待连接 │ ──→ │ 活跃 │ ──→ │ 空闲/断连 │ ──→ │ 过期/退出 │ +│Register │ │ Waiting │ │ Active │ │ Idle │ │ Expired │ +└─────────┘ └───────────┘ └──────────┘ └───────────┘ └──────────┘ + - OAuth认证 - 显示URL/QR - 双向消息同步 - 自动重连尝试 - 进程退出 + - API注册 - 轮询等待客户端 - 工具调用可远程审批 - ~10min网络断连 - 清理会话文件 + - Server模式可 后超时 + 接受多个客户端 +``` + +**各阶段详情**： + +| 阶段 | 触发 | 行为 | +|------|------|------| +| **注册** | 启动 `claude remote-control` 或 `/rc` | 使用 full-scope OAuth token 向 Anthropic API 注册会话，获取 `SESSION_ACCESS_TOKEN` | +| **等待连接** | 注册成功后 | 终端显示会话 URL 和 QR 码。本地进程持续 polling 等待远程客户端 | +| **活跃** | 远程客户端连接 | 双向消息同步：远程发送的指令路由到本地执行，本地输出实时推送到远程 | +| **空闲/断连** | 网络中断、笔记本睡眠 | 自动尝试重连。若网络断连超过 ~10 分钟，会话超时 | +| **过期/退出** | 超时或进程终止 | 清理会话文件。Server 端约 20+ 分钟无活动后关闭连接（观察到 `CLOSE_WAIT` TCP 状态） | + +### 会话文件与本地存储 + +| 路径 | 内容 | 来源 | +|------|------|------| +| `~/.claude/sessions/{pid}.json` | 会话元数据：`name`、`status`、`updatedAt`、`bridgeSessionId`、`messagingSocketPath` | GitHub Issues | +| `/tmp/cc-socks/*.sock` | 本地进程间通信的 Unix domain socket | GitHub Issues | +| `~/.claude/projects//` | 会话对话历史（`.jsonl` 格式），`cleanupPeriodDays`（默认 30 天）后自动清理 | [EVIDENCE.md](./EVIDENCE.md) | + +### `--spawn` 多会话架构 + +Server 模式支持通过 `--spawn` 参数管理多个并发远程会话： -> **注意**：并非直接向本地机器建立 WebSocket 连接。本地进程通过 polling Anthropic API 获取消息，消息经由 Anthropic 基础设施中继。 +| 模式 | 行为 | 适用场景 | +|------|------|----------| +| `same-dir`（默认） | 所有会话共享当前工作目录 | 多人远程操控同一项目不同任务 | +| `worktree` | 每个按需会话获得独立 Git worktree | 需要文件隔离的并行开发任务 | + +**运行时切换**：在 Server 模式中按 `w` 键可动态切换 spawn 模式。 + +**容量控制**：`--capacity ` 限制最大并发会话数（默认 32），防止资源耗尽。 + +> **与 CCR（Claude Code Remote）的区别**：`--spawn` 创建的是**本地多会话**（通过 worktree 隔离），而 `/schedule` 使用的 `RemoteTrigger` 工具创建的是**云端隔离会话**（CCR），在 Anthropic 基础设施上独立运行（[命令详解](./02-commands.md)）。 + +### 安全模型纵深 + +Remote Control 的安全架构采用多层防护： + +| 层级 | 机制 | 说明 | +|------|------|------| +| **1. 认证门槛** | claude.ai OAuth full-scope token | API Key、`setup-token`、Bedrock/Vertex/Foundry 均被拒绝 | +| **2. 管理员门控** | `claude.ai/admin-settings/claude-code` 开关 | Team/Enterprise 默认关闭；合规配置可阻止启用 | +| **3. 凭证隔离** | 多短期凭证、单用途作用域、独立过期 | 防止凭证泄露后横向移动 | +| **4. 网络隔离** | 仅出站 HTTPS，零入站端口 | 本地机器不暴露任何攻击面 | +| **5. 传输加密** | 全程 TLS | 与普通 Claude Code 会话相同 | +| **6. 可选沙箱** | `--sandbox` 启用文件系统+网络隔离 | 默认关闭，Server 模式可启用 | +| **7. 安全分类器** | auto mode 双层防御（服务端 probe + 客户端分类器） | [工程博客](https://anthropic.com/engineering/claude-code-auto-mode)，Sonnet 4.6 驱动 | + +**遥测耦合问题**：`DISABLE_TELEMETRY=1` 会阻止 Remote Control 注册（[GitHub #41189](https://github.com/anthropics/claude-code/issues/41189)），因为资格检查依赖遥测通道。这是一个已知的架构耦合问题。 + +### 相关 API 端点（反编译提取） + +| 端点 | 用途 | 来源 | +|------|------|------| +| `claude.ai/api/claude_code/settings` | 远程设置获取 | [EVIDENCE.md](./EVIDENCE.md) | +| `claude.ai/api/claude_code/policy_limits` | 策略限制查询 | [EVIDENCE.md](./EVIDENCE.md) | +| `claude.ai/api/oauth/authorize` | OAuth 认证 | [EVIDENCE.md](./EVIDENCE.md) | +| `api.anthropic.com/api/claude_code/metrics` | 遥测上报（资格检查依赖此通道） | [EVIDENCE.md](./EVIDENCE.md) | +| `claude.ai/api/ws/speech_to_text/voice_stream` | 语音转文字（非 Remote Control，但共用 WebSocket 基础设施） | [EVIDENCE.md](./EVIDENCE.md) | + +> **注意**：Remote Control 专用的会话注册和消息中继端点 URL 未在 v2.1.81 二进制的 `--help` 输出或 rodata 段中明文暴露。上述端点为反编译中确认的基础设施端点，可能被 Remote Control 复用。 ### 相关环境变量 -前 6 项来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)；后 2 项为反编译提取的变量名（[EVIDENCE.md](./EVIDENCE.md)），具体用途为推断。 +前 6 项来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)；后 4 项为反编译提取的变量名（[EVIDENCE.md](./EVIDENCE.md)），具体用途为推断。 | 变量 | 影响 | 来源 | |------|------|------| | `ANTHROPIC_API_KEY` | 阻止 Remote Control；需清除并使用 OAuth 登录 | 官方文档 | | `CLAUDE_CODE_OAUTH_TOKEN` | 提供有限范围 token；与 Remote Control 不兼容 | 官方文档 | | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 可能破坏资格检查 | 官方文档 | -| `DISABLE_TELEMETRY` | 可能破坏资格检查 | 官方文档 | +| `DISABLE_TELEMETRY` | 阻止 Remote Control 注册（架构耦合 bug） | 官方文档 + GitHub #41189 | | `CLAUDE_CODE_USE_BEDROCK` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | | `CLAUDE_CODE_USE_VERTEX` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | | `CLAUDE_CODE_USE_FOUNDRY` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | -| `SESSION_ACCESS_TOKEN` | 认证相关凭证（反编译提取） | EVIDENCE.md | -| `WEBSOCKET_AUTH_*` | 认证相关凭证（反编译提取） | EVIDENCE.md | +| `SESSION_ACCESS_TOKEN` | 会话访问凭证（反编译提取） | EVIDENCE.md | +| `WEBSOCKET_AUTH_*` | WebSocket 认证凭证（反编译提取） | EVIDENCE.md | +| `SSE_PORT` | SSE 本地端口（反编译提取，可能用于 Remote Control 或 MCP SSE 传输） | EVIDENCE.md | ## Remote Control vs Claude Code on the Web @@ -167,6 +252,21 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | **不支持 API Key** | 必须使用 claude.ai OAuth 认证 | | **不支持第三方提供商** | Bedrock / Vertex / Foundry 用户无法使用 | +## 已知架构问题（社区反馈） + +以下问题来自 GitHub Issues，反映了 Remote Control 当前实现的架构缺陷： + +| 问题 | 根因 | 影响 | 来源 | +|------|------|------|------| +| **Pidfile 竞态** | `concurrentSessions.ts` 中 `updatePidFile()` 非原子 read-modify-write（缺少 tmp+rename） | 并发会话时 JSON 文件损坏，Bun `fallocate` 可产生 null 字节截断 | [#41195](https://github.com/anthropics/claude-code/issues/41195) | +| **遥测耦合** | `DISABLE_TELEMETRY=1` 阻止 RC 注册（资格检查走遥测通道） | RC 失败但报错信息误导为"未启用" | [#41189](https://github.com/anthropics/claude-code/issues/41189) | +| **僵尸进程** | 无 TCP read timeout、无 `CLOSE_WAIT` 检测、无空闲看门狗 | 服务端关闭连接后客户端进程不退出，占用 1+ GB 内存无限期 | [#41024](https://github.com/anthropics/claude-code/issues/41024) | +| **连接循环** | Connecting/Disconnected 循环，可能与凭证刷新或网络代理有关 | 远程客户端无法稳定连接 | [#41324](https://github.com/anthropics/claude-code/issues/41324) | +| **移动端 stale 连接** | Mobile App 复用过期的 WebSocket/session token | 空闲会话在移动端不可恢复，但 CLI 端正常 | [#41128](https://github.com/anthropics/claude-code/issues/41128) | +| **VS Code 配置缺口** | 扩展未读取 `remoteControlAtStartup` 设置 | `/config` 全局启用在 VS Code 扩展中不生效 | [#41036](https://github.com/anthropics/claude-code/issues/41036) | +| **Windows MCP 兼容** | Cloud MCP + RC 在 Windows 上加载失败 | Windows 用户无法同时使用 MCP 和 Remote Control | [#41044](https://github.com/anthropics/claude-code/issues/41044) | +| **活跃 turn 丢消息** | Agent 正在执行 turn 时，stdin 消息可能丢失 | 远程发送的指令在 agent 忙碌时可能不被处理 | [#41230](https://github.com/anthropics/claude-code/issues/41230) | + ## 故障排查 | 错误信息 | 原因与解决 | diff --git a/docs/tools/claude-code/README.md b/docs/tools/claude-code/README.md index 54958005..60caf7c9 100644 --- a/docs/tools/claude-code/README.md +++ b/docs/tools/claude-code/README.md @@ -11,4 +11,4 @@ | [05-Skill 系统](./05-skills.md) | Skill 定义、加载、内置 Skill | | [06-设置与安全](./06-settings.md) | 5 层设置、权限、沙箱、24 种 Hook 事件 | | [07-会话与记忆](./07-session.md) | 会话管理、记忆系统、MCP | -| [08-Remote Control](./08-remote-control.md) | 远程控制架构、使用方式、安全模型、跨设备对比 | +| [08-Remote Control](./08-remote-control.md) | 远程控制架构、三方中继、会话生命周期、安全纵深、已知问题 | From 842962da11c27d512771bf3ac9b2e9f0c6171100 Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 17:18:07 +0800 Subject: [PATCH 04/15] =?UTF-8?q?=E5=9B=9E=E5=BA=94=20gpt-5.4=20review?= =?UTF-8?q?=EF=BC=9A=E8=AF=81=E6=8D=AE=E7=AD=89=E7=BA=A7=E5=88=86=E5=B1=82?= =?UTF-8?q?=EF=BC=8C=E6=8E=A8=E6=96=AD=E9=99=8D=E7=BA=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 根据 gpt-5.4 的 4 条 inline review 意见，逐项修正： 1. 数据流/传输协议：拆分「官方确认」与「推断」两层表述 - 数据流列表新增 ✅/⚠️ 标记 - 传输协议表格新增「确认度」列 - streaming connection 不再具体化为 long-poll/SSE 2. 安全表述：「不暴露任何攻击面」→「显著降低网络暴露面」 - 明确承认本地 IPC、会话文件、OAuth flow 仍属攻击面 3. 遥测耦合因果降级：「架构耦合问题」→「疑似实现耦合」 - 明确标注「当前证据不足以确认根因」 - 环境变量表和已知问题表统一调整 4. 僵尸进程根因降级：列标题从「根因」改为「观察到的现象/推测原因」 - 节标题从「已知架构问题」改为「已知问题（社区反馈）」 - 标注「根因未经官方确认」 Co-authored-by: Qwen-Coder --- docs/tools/claude-code/08-remote-control.md | 40 ++++++++++----------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index 7dc798f9..392a3f71 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -111,18 +111,18 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic └───────────────────────┘ ``` -**数据流**： -1. **本地 → Anthropic API**：本地进程启动时用 full-scope OAuth token 注册会话，随后以 polling 方式持续获取待处理消息 -2. **Anthropic API → 本地**：服务器有消息时通过 streaming connection 下发（长轮询或 SSE over HTTPS） -3. **Anthropic API ↔ 浏览器/手机**：远程客户端通过 WebSocket 连接到 Anthropic 基础设施（GitHub Issues 中观察到 stale WebSocket 连接行为） - -| 方面 | 细节 | -|------|------| -| **本地→服务器** | 出站 HTTPS polling（非 WebSocket）。本地不开放入站端口 | -| **远程客户端→服务器** | WebSocket 连接到 Anthropic 基础设施（`WEBSOCKET_AUTH_*` 凭证认证） | -| **消息路由** | Anthropic 服务器在远程客户端和本地会话之间双向中继 | -| **传输安全** | 全程 TLS 加密，与普通 Claude Code 会话相同 | -| **凭证体系** | 多个短期凭证，每个限定单一用途，独立过期 | +**数据流**（官方确认部分）： +1. **本地 → Anthropic API**：本地进程启动时用 full-scope OAuth token 注册会话，随后以 polling 方式持续获取待处理消息 ✅ 官方确认 +2. **Anthropic API → 本地**：服务器有消息时通过 streaming connection 下发 ✅ 官方确认 +3. **Anthropic API ↔ 浏览器/手机**：远程客户端连接到 Anthropic 基础设施（具体传输协议未公开确认） ⚠️ 社区观察到 stale WebSocket 连接行为 + +| 方面 | 细节 | 确认度 | +|------|------|--------| +| **本地→服务器** | 出站 HTTPS polling。本地不开放入站端口 | ✅ 官方确认 | +| **远程客户端→服务器** | 推测为 WebSocket 或 HTTPS 长连接（`WEBSOCKET_AUTH_*` 变量名暗示 WebSocket 使用） | ⚠️ 推断 | +| **消息路由** | Anthropic 服务器在远程客户端和本地会话之间双向中继 | ✅ 官方确认 | +| **传输安全** | 全程 TLS 加密，与普通 Claude Code 会话相同 | ✅ 官方确认 | +| **凭证体系** | 多个短期凭证，每个限定单一用途，独立过期 | ✅ 官方确认 | ### 会话生命周期 @@ -179,12 +179,12 @@ Remote Control 的安全架构采用多层防护： | **1. 认证门槛** | claude.ai OAuth full-scope token | API Key、`setup-token`、Bedrock/Vertex/Foundry 均被拒绝 | | **2. 管理员门控** | `claude.ai/admin-settings/claude-code` 开关 | Team/Enterprise 默认关闭；合规配置可阻止启用 | | **3. 凭证隔离** | 多短期凭证、单用途作用域、独立过期 | 防止凭证泄露后横向移动 | -| **4. 网络隔离** | 仅出站 HTTPS，零入站端口 | 本地机器不暴露任何攻击面 | +| **4. 网络隔离** | 仅出站 HTTPS，零入站端口 | 显著降低网络暴露面（本地 IPC、会话文件、OAuth flow 仍属攻击面） | | **5. 传输加密** | 全程 TLS | 与普通 Claude Code 会话相同 | | **6. 可选沙箱** | `--sandbox` 启用文件系统+网络隔离 | 默认关闭，Server 模式可启用 | | **7. 安全分类器** | auto mode 双层防御（服务端 probe + 客户端分类器） | [工程博客](https://anthropic.com/engineering/claude-code-auto-mode)，Sonnet 4.6 驱动 | -**遥测耦合问题**：`DISABLE_TELEMETRY=1` 会阻止 Remote Control 注册（[GitHub #41189](https://github.com/anthropics/claude-code/issues/41189)），因为资格检查依赖遥测通道。这是一个已知的架构耦合问题。 +**遥测耦合现象**：设置 `DISABLE_TELEMETRY=1` 后 Remote Control 注册失败（[GitHub #41189](https://github.com/anthropics/claude-code/issues/41189)），表现为 eligibility check 不通过。当前证据不足以确认根因是"资格检查走遥测通道"，标记为**疑似实现耦合**。 ### 相关 API 端点（反编译提取） @@ -207,7 +207,7 @@ Remote Control 的安全架构采用多层防护： | `ANTHROPIC_API_KEY` | 阻止 Remote Control；需清除并使用 OAuth 登录 | 官方文档 | | `CLAUDE_CODE_OAUTH_TOKEN` | 提供有限范围 token；与 Remote Control 不兼容 | 官方文档 | | `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` | 可能破坏资格检查 | 官方文档 | -| `DISABLE_TELEMETRY` | 阻止 Remote Control 注册（架构耦合 bug） | 官方文档 + GitHub #41189 | +| `DISABLE_TELEMETRY` | 阻止 Remote Control 注册（疑似实现耦合，[GitHub #41189](https://github.com/anthropics/claude-code/issues/41189)） | 官方文档 + 社区观察 | | `CLAUDE_CODE_USE_BEDROCK` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | | `CLAUDE_CODE_USE_VERTEX` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | | `CLAUDE_CODE_USE_FOUNDRY` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | @@ -252,15 +252,15 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | **不支持 API Key** | 必须使用 claude.ai OAuth 认证 | | **不支持第三方提供商** | Bedrock / Vertex / Foundry 用户无法使用 | -## 已知架构问题（社区反馈） +## 已知问题（社区反馈） -以下问题来自 GitHub Issues，反映了 Remote Control 当前实现的架构缺陷： +以下问题来自 GitHub Issues，为社区观察到的现象，**根因未经官方确认**： -| 问题 | 根因 | 影响 | 来源 | +| 问题 | 观察到的现象 / 推测原因 | 影响 | 来源 | |------|------|------|------| | **Pidfile 竞态** | `concurrentSessions.ts` 中 `updatePidFile()` 非原子 read-modify-write（缺少 tmp+rename） | 并发会话时 JSON 文件损坏，Bun `fallocate` 可产生 null 字节截断 | [#41195](https://github.com/anthropics/claude-code/issues/41195) | -| **遥测耦合** | `DISABLE_TELEMETRY=1` 阻止 RC 注册（资格检查走遥测通道） | RC 失败但报错信息误导为"未启用" | [#41189](https://github.com/anthropics/claude-code/issues/41189) | -| **僵尸进程** | 无 TCP read timeout、无 `CLOSE_WAIT` 检测、无空闲看门狗 | 服务端关闭连接后客户端进程不退出，占用 1+ GB 内存无限期 | [#41024](https://github.com/anthropics/claude-code/issues/41024) | +| **遥测耦合** | 设置 `DISABLE_TELEMETRY=1` 后 RC 注册失败（疑似 eligibility check 与遥测共享代码路径） | RC 失败但报错信息误导为"未启用" | [#41189](https://github.com/anthropics/claude-code/issues/41189) | +| **僵尸进程** | 服务端关闭连接后客户端进程不退出（观察到 `CLOSE_WAIT` TCP 状态，推测可能缺少 TCP read timeout 或 `CLOSE_WAIT` 检测） | 服务端关闭后客户端仍占用 1+ GB 内存，无自动退出 | [#41024](https://github.com/anthropics/claude-code/issues/41024) | | **连接循环** | Connecting/Disconnected 循环，可能与凭证刷新或网络代理有关 | 远程客户端无法稳定连接 | [#41324](https://github.com/anthropics/claude-code/issues/41324) | | **移动端 stale 连接** | Mobile App 复用过期的 WebSocket/session token | 空闲会话在移动端不可恢复，但 CLI 端正常 | [#41128](https://github.com/anthropics/claude-code/issues/41128) | | **VS Code 配置缺口** | 扩展未读取 `remoteControlAtStartup` 设置 | `/config` 全局启用在 VS Code 扩展中不生效 | [#41036](https://github.com/anthropics/claude-code/issues/41036) | From ece18f5819a729d3bbc7040c69a2bda3007aa10e Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 17:34:44 +0800 Subject: [PATCH 05/15] =?UTF-8?q?=E6=96=B0=E5=A2=9E=E8=AF=84=E4=BB=B7?= =?UTF-8?q?=E4=BC=98=E7=BC=BA=E7=82=B9=E5=88=86=E6=9E=90=20+=207=20?= =?UTF-8?q?=E6=AC=BE=E7=AB=9E=E5=93=81=E8=BF=9C=E7=A8=8B=E8=83=BD=E5=8A=9B?= =?UTF-8?q?=E5=AF=B9=E6=AF=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增内容： - 评价与优缺点分析（4 个核心优势 + 4 个核心短板 + 设计权衡表） - 竞品对比：远程访问能力全景矩阵（7 款 Agent × 8 个维度） - 竞品关键差异分析（Kimi CLI / OpenCode / Goose / Codex CLI） - 为什么没有其他 Agent 复制 Remote Control（4 个壁垒分析） 竞品数据来源：项目内各 Agent 的 EVIDENCE.md 和架构文档 Co-authored-by: Qwen-Coder --- docs/tools/claude-code/08-remote-control.md | 109 ++++++++++++++++++++ docs/tools/claude-code/README.md | 2 +- 2 files changed, 110 insertions(+), 1 deletion(-) diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index 392a3f71..b60e0f13 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -304,4 +304,113 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | **Kimi CLI** | ❌ 无（有 Wire 协议但未实现远程控制） | | **其他 Agent** | ❌ 无 | +## 评价与优缺点分析 + +### 核心优势 + +**1. 唯一实现"终端会话远程操控"的 Agent** + +Claude Code 的 Remote Control 在所有 18 款 Agent 中独树一帜——它不是简单的 Web UI 或 API 暴露，而是将一个**正在运行的终端交互会话**双向桥接到浏览器/手机。这意味着远程端可以完整使用本地文件系统、MCP 服务器、项目配置，实现真正的"离开工位不中断工作"。 + +**2. 安全架构设计审慎** + +- 仅出站 HTTPS，零入站端口——企业防火墙友好 +- 强制 claude.ai OAuth full-scope token——排除 API Key / 第三方提供商 +- Team/Enterprise 管理员门控——组织级管控 +- 多短期凭证隔离——防止凭证泄露横向移动 + +**3. 多模式灵活适配** + +三种启动方式（Server 模式 / 交互式 / 会话内）覆盖不同场景：长时间无人值守用 Server 模式，日常开发用交互式，临时需要用会话内。`--spawn worktree` 支持多会话文件隔离，`--capacity` 防止资源耗尽。 + +**4. 跨设备生态完整** + +Remote Control 不是孤立功能，而是 Claude Code 跨设备矩阵的一部分——配合 `--remote`（推到 Web）、`/teleport`（拉回终端）、Dispatch（手机委派）、Channels（Telegram/Discord 推送）、`/schedule`（定时任务），形成从"实时远程操控"到"异步事件驱动"的完整工作流覆盖。 + +### 核心短板 + +**1. 强绑定 claude.ai 生态** + +- 不支持 API Key、Bedrock、Vertex、Foundry——企业私有化部署场景被排除 +- `DISABLE_TELEMETRY` 会意外阻止注册——隐私敏感用户被迫在遥测和远程控制之间二选一 +- Team/Enterprise 默认关闭，部分合规配置不可覆盖 + +**2. 稳定性问题** + +截至 v2.1.81，社区反馈了 8 个已知问题（见上文），其中几个影响实际使用： +- 僵尸进程：服务端关闭后客户端不退出，内存不释放 +- 连接循环：Connecting/Disconnected 反复，无法稳定工作 +- 移动端 stale 连接：WebSocket/session token 过期后不可恢复 +- VS Code 扩展忽略 `remoteControlAtStartup` 配置 + +**3. 本地进程强依赖** + +- 终端必须保持打开，关闭即断 +- 网络断连 ~10 分钟后超时退出 +- 不如 `/schedule`（CCR 云端执行）那样能"关机后继续跑" + +**4. 闭源且证据有限** + +通信协议细节（polling 间隔、消息格式、端点 URL）未公开，二进制反编译也未完整暴露 Remote Control 专用端点。安全审计只能基于官方文档描述，无法独立验证实现。 + +### 设计权衡总结 + +| 设计决策 | 收益 | 代价 | +|----------|------|------| +| 本地执行 + 远程操控 | 完整本地环境可用 | 终端必须在线 | +| HTTPS polling 中继 | 零入站端口，企业友好 | 延迟高于直连 WebSocket | +| claude.ai OAuth 强绑定 | 统一认证、管理员管控 | 排除 API Key / 第三方用户 | +| 多短期凭证 | 凭证泄露影响面小 | 增加注册失败点 | +| 遥测与资格检查耦合 | 可能简化实现 | 隐私用户被意外阻断 | + +## 竞品对比：远程访问能力全景 + +Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有，但"远程访问"本身在其他 Agent 中有不同形态的实现： + +### 功能对比矩阵 + +| 能力 | Claude Code | Kimi CLI | OpenCode | Goose | Codex CLI | Copilot CLI | Aider | +|------|:-:|:-:|:-:|:-:|:-:|:-:|:-:| +| **终端会话远程操控** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | +| **Web UI** | ❌ | ✅ FastAPI+React | ✅ SolidJS（实验） | ✅ via Axum HTTP | ❌ | ❌ | ❌ | +| **多客户端（TUI+Web+Desktop）** | ❌ | ✅ Wire 四客户端 | ✅ TUI+Web+Desktop | ✅ CLI+Desktop | ❌ | ❌ | ❌ | +| **移动端 App** | ✅ iOS/Android | ❌（Web 可访问） | ❌ | ❌ | ❌ | ❌ | ❌ | +| **LAN/公网暴露** | ❌（仅通过 Anthropic 中继） | ✅ `--public` | ✅ MDNS | ✅ Axum HTTP | ❌ | ❌ | ❌ | +| **远程 IDE 集成** | ✅ VS Code | ✅ ACP | ❌ | ❌ | ✅ app-server | ✅ 原生 | ❌ | +| **零入站端口** | ✅ | ❌（开端口） | ❌（开端口） | ❌（开端口） | ❌ | N/A | N/A | +| **协议** | HTTPS polling + 中继 | Wire v1.6 (WS) | Hono HTTP+WS+SSE | REST (Axum) | JSON-RPC (WS) | CLI only | CLI only | + +### 竞品关键差异 + +**Kimi CLI**（最完整的 Web UI）： +- `kimi web` 启动 FastAPI + React Web UI（默认 `localhost:5494`），支持多会话管理、实时 diff 预览、审批对话框、数学公式渲染 +- Wire v1.6 协议统一 TUI / Web / IDE / 自定义 UI 四种客户端，所有事件广播到所有连接 +- 支持 `--network`、`--lan-only`、`--public` 三种网络模式，token 认证 +- **劣势**：需要在本地开放端口（不像 Claude Code 的 outbound-only），无原生移动 App + +**OpenCode**（最雄心勃勃的多客户端）： +- TUI + Web Console（SolidJS）+ Desktop（Tauri v2 / Electron）三客户端共享 Hono HTTP 后端 +- MDNS 本地网络设备发现 +- 社区项目 Remote-OpenCode 支持 Discord 控制 +- **劣势**：远程 workspace 仍为实验性功能，稳定性待验证 + +**Goose**（REST API 驱动）： +- `goose-server`（Axum HTTP）提供 REST API，Electron Desktop App 作为 GUI 客户端 +- `ComputerController` 扩展提供 `web_scrape`、`computer_control` 浏览器自动化 +- **劣势**：无 Web UI、无移动端、REST API 不如 WebSocket 实时 + +**Codex CLI**（IDE 集成导向）： +- `codex app-server` 提供 JSON-RPC 2.0 over stdio/WebSocket（90+ 方法） +- `--remote` 连接远程 app-server 实例 +- **劣势**：面向 IDE 插件设计，非通用远程访问 + +### 为什么没有其他 Agent 复制 Remote Control？ + +| 壁垒 | 说明 | +|------|------| +| **需要云基础设施** | Anthropic 的中继服务器和 claude.ai/code 平台是 Remote Control 的必要前提。开源 Agent 缺乏同等规模的云中继设施 | +| **认证体系强绑定** | 强制 OAuth + 短期凭证 + 管理员门控依赖中心化身份系统，自托管 Agent 难以复制 | +| **产品定位差异** | Claude Code 定位"企业级 AI 编程平台"（含 Web/Desktop/Mobile 多端），大多数 Agent 定位"开发者本地工具" | +| **替代方案更简单** | Kimi CLI/OpenCode 用本地 Web UI + 开端口的方式实现了 80% 的远程需求，开发成本低得多 | + > **免责声明**：以上数据基于 2026 年 Q1 源码分析和官方文档，可能已过时。Qwen Code 的 Remote Control 功能缺口已被标记为 P2 优先级。 diff --git a/docs/tools/claude-code/README.md b/docs/tools/claude-code/README.md index 60caf7c9..54f65979 100644 --- a/docs/tools/claude-code/README.md +++ b/docs/tools/claude-code/README.md @@ -11,4 +11,4 @@ | [05-Skill 系统](./05-skills.md) | Skill 定义、加载、内置 Skill | | [06-设置与安全](./06-settings.md) | 5 层设置、权限、沙箱、24 种 Hook 事件 | | [07-会话与记忆](./07-session.md) | 会话管理、记忆系统、MCP | -| [08-Remote Control](./08-remote-control.md) | 远程控制架构、三方中继、会话生命周期、安全纵深、已知问题 | +| [08-Remote Control](./08-remote-control.md) | 远程控制架构、会话生命周期、安全纵深、评价优缺点、7 款竞品对比 | From 8bee55cd7b7f576be8f7c344a369e3db4579684a Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 17:49:13 +0800 Subject: [PATCH 06/15] =?UTF-8?q?gpt-5.4=20=E7=AC=AC=E4=BA=8C=E8=BD=AE=20r?= =?UTF-8?q?eview=20=E4=BF=AE=E5=A4=8D=EF=BC=9A=E7=9F=A9=E9=98=B5=E5=8F=A3?= =?UTF-8?q?=E5=BE=84=E7=BB=9F=E4=B8=80=20+=20=E5=BB=B6=E8=BF=9F=E9=99=8D?= =?UTF-8?q?=E7=BA=A7=20+=20=E5=A3=81=E5=9E=92=E5=88=86=E6=9E=90=E6=A0=87?= =?UTF-8?q?=E6=B3=A8=E6=8E=A8=E6=B5=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 竞品矩阵：Goose Web UI 改为 ❌（仅 Desktop App），Claude Code 多客户端改为 ✅， 删除口径不可比的 LAN/公网暴露行，新增维度说明 blockquote 2. 设计权衡表：延迟表述从「高于直连 WebSocket」降级为「可能带来更高交互延迟 ⚠️ 推断」 3. 壁垒分析：标题加注「作者分析，非源码验证结论」，新增推测声明 blockquote， 列标题改为「可能原因」，每行加 ⚠️ 推断，删除无数据支撑的 80% 数字 Co-authored-by: Qwen-Coder --- docs/tools/claude-code/08-remote-control.md | 34 +++++++++++++-------- 1 file changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index b60e0f13..c0c9a359 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -358,7 +358,7 @@ Remote Control 不是孤立功能，而是 Claude Code 跨设备矩阵的一部 | 设计决策 | 收益 | 代价 | |----------|------|------| | 本地执行 + 远程操控 | 完整本地环境可用 | 终端必须在线 | -| HTTPS polling 中继 | 零入站端口，企业友好 | 延迟高于直连 WebSocket | +| HTTPS polling 中继 | 零入站端口，企业友好 | 可能带来更高交互延迟 ⚠️ 推断 | | claude.ai OAuth 强绑定 | 统一认证、管理员管控 | 排除 API Key / 第三方用户 | | 多短期凭证 | 凭证泄露影响面小 | 增加注册失败点 | | 遥测与资格检查耦合 | 可能简化实现 | 隐私用户被意外阻断 | @@ -369,15 +369,21 @@ Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有 ### 功能对比矩阵 +> **维度说明**：本表统一按「是否具备该能力」横向对比。各能力定义如下—— +> - **终端会话远程操控**：从其他设备实时操控一个正在运行的 CLI 会话 +> - **Web/浏览器 UI**：提供可通过浏览器访问的图形界面 +> - **多客户端同时连接**：同一会话可被多种客户端（TUI/Web/Desktop/Mobile）同时连接 +> - **原生移动端 App**：iOS/Android 原生应用（非移动浏览器访问 Web UI） +> - **零入站端口**：无需在本地开放任何监听端口 + | 能力 | Claude Code | Kimi CLI | OpenCode | Goose | Codex CLI | Copilot CLI | Aider | |------|:-:|:-:|:-:|:-:|:-:|:-:|:-:| | **终端会话远程操控** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | -| **Web UI** | ❌ | ✅ FastAPI+React | ✅ SolidJS（实验） | ✅ via Axum HTTP | ❌ | ❌ | ❌ | -| **多客户端（TUI+Web+Desktop）** | ❌ | ✅ Wire 四客户端 | ✅ TUI+Web+Desktop | ✅ CLI+Desktop | ❌ | ❌ | ❌ | -| **移动端 App** | ✅ iOS/Android | ❌（Web 可访问） | ❌ | ❌ | ❌ | ❌ | ❌ | -| **LAN/公网暴露** | ❌（仅通过 Anthropic 中继） | ✅ `--public` | ✅ MDNS | ✅ Axum HTTP | ❌ | ❌ | ❌ | +| **Web/浏览器 UI** | ❌ | ✅ FastAPI+React | ✅ SolidJS（实验） | ❌（仅 Desktop App） | ❌ | ❌ | ❌ | +| **多客户端同时连接** | ✅ TUI+浏览器+Mobile | ✅ Wire 四客户端 | ✅ TUI+Web+Desktop | ✅ CLI+Desktop | ❌ | ❌ | ❌ | +| **原生移动端 App** | ✅ iOS/Android | ❌（移动浏览器可访问 Web UI） | ❌ | ❌ | ❌ | ❌ | ❌ | +| **零入站端口** | ✅（outbound-only 中继） | ❌（开端口） | ❌（开端口） | ❌（开端口） | ❌ | N/A | N/A | | **远程 IDE 集成** | ✅ VS Code | ✅ ACP | ❌ | ❌ | ✅ app-server | ✅ 原生 | ❌ | -| **零入站端口** | ✅ | ❌（开端口） | ❌（开端口） | ❌（开端口） | ❌ | N/A | N/A | | **协议** | HTTPS polling + 中继 | Wire v1.6 (WS) | Hono HTTP+WS+SSE | REST (Axum) | JSON-RPC (WS) | CLI only | CLI only | ### 竞品关键差异 @@ -404,13 +410,15 @@ Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有 - `--remote` 连接远程 app-server 实例 - **劣势**：面向 IDE 插件设计，非通用远程访问 -### 为什么没有其他 Agent 复制 Remote Control？ +### 为什么没有其他 Agent 复制 Remote Control？（作者分析，非源码验证结论） -| 壁垒 | 说明 | -|------|------| -| **需要云基础设施** | Anthropic 的中继服务器和 claude.ai/code 平台是 Remote Control 的必要前提。开源 Agent 缺乏同等规模的云中继设施 | -| **认证体系强绑定** | 强制 OAuth + 短期凭证 + 管理员门控依赖中心化身份系统，自托管 Agent 难以复制 | -| **产品定位差异** | Claude Code 定位"企业级 AI 编程平台"（含 Web/Desktop/Mobile 多端），大多数 Agent 定位"开发者本地工具" | -| **替代方案更简单** | Kimi CLI/OpenCode 用本地 Web UI + 开端口的方式实现了 80% 的远程需求，开发成本低得多 | +> ⚠️ 以下为基于公开信息的分析推测，未经源码或官方声明验证。 + +| 可能原因 | 说明 | +|----------|------| +| **需要云基础设施** ⚠️ 推断 | Anthropic 的中继服务器和 claude.ai/code 平台是 Remote Control 的必要前提。开源 Agent 缺乏同等规模的云中继设施 | +| **认证体系强绑定** ⚠️ 推断 | 强制 OAuth + 短期凭证 + 管理员门控依赖中心化身份系统，自托管 Agent 难以复制 | +| **产品定位差异** ⚠️ 推断 | Claude Code 定位"企业级 AI 编程平台"（含 Web/Desktop/Mobile 多端），大多数 Agent 定位"开发者本地工具" | +| **替代方案成本更低** ⚠️ 推断 | Kimi CLI/OpenCode 等通过本地 Web UI + 开端口的方式提供了基本的远程访问能力，对多数场景已够用 | > **免责声明**：以上数据基于 2026 年 Q1 源码分析和官方文档，可能已过时。Qwen Code 的 Remote Control 功能缺口已被标记为 P2 优先级。 From fbd0c9f6dd16960af96cbdc11f1c456b34c76582 Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 18:02:38 +0800 Subject: [PATCH 07/15] =?UTF-8?q?gpt-5.4=20=E7=AC=AC=E4=B8=89=E8=BD=AE=20r?= =?UTF-8?q?eview=20=E4=BF=AE=E5=A4=8D=EF=BC=9A=E4=B8=AD=E6=80=A7=E8=A1=A8?= =?UTF-8?q?=E8=BF=B0=20+=20=E6=9D=A5=E6=BA=90=E8=A1=A5=E9=93=BE=20+=20?= =?UTF-8?q?=E5=88=A0=E9=99=A4=E6=97=A0=E5=87=BA=E5=A4=84=E5=A3=B0=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 1. 遥测耦合行收益列从「可能简化实现」改为「—」，避免推测性归因 2. 竞品关键差异：每个 Agent 新增来源链接（指向仓库内架构/EVIDENCE 文档）， 删除无来源的细粒度描述（数学公式渲染、90+方法、ComputerController、Discord 项目） 3. 免责声明删除「P2 优先级」句（仓库内无定义该优先级的文档） Co-authored-by: Qwen-Coder --- docs/tools/claude-code/08-remote-control.md | 22 +++++++++++---------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index c0c9a359..2d3630dd 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -361,7 +361,7 @@ Remote Control 不是孤立功能，而是 Claude Code 跨设备矩阵的一部 | HTTPS polling 中继 | 零入站端口，企业友好 | 可能带来更高交互延迟 ⚠️ 推断 | | claude.ai OAuth 强绑定 | 统一认证、管理员管控 | 排除 API Key / 第三方用户 | | 多短期凭证 | 凭证泄露影响面小 | 增加注册失败点 | -| 遥测与资格检查耦合 | 可能简化实现 | 隐私用户被意外阻断 | +| 遥测与资格检查耦合 | — | 会导致隐私用户被意外阻断 | ## 竞品对比：远程访问能力全景 @@ -389,25 +389,27 @@ Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有 ### 竞品关键差异 **Kimi CLI**（最完整的 Web UI）： -- `kimi web` 启动 FastAPI + React Web UI（默认 `localhost:5494`），支持多会话管理、实时 diff 预览、审批对话框、数学公式渲染 -- Wire v1.6 协议统一 TUI / Web / IDE / 自定义 UI 四种客户端，所有事件广播到所有连接 +- `kimi web` 启动 FastAPI + React Web UI（默认 `localhost:5494`），支持多会话管理、实时 diff 预览、审批对话框 + （来源：[Kimi CLI 架构文档](../kimi-cli/03-architecture.md)） +- Wire v1.6 协议统一 TUI / Web / IDE / 自定义 UI 四种客户端 + （来源：[Kimi CLI 架构文档](../kimi-cli/03-architecture.md)） - 支持 `--network`、`--lan-only`、`--public` 三种网络模式，token 认证 - **劣势**：需要在本地开放端口（不像 Claude Code 的 outbound-only），无原生移动 App -**OpenCode**（最雄心勃勃的多客户端）： +**OpenCode**（多客户端架构）： - TUI + Web Console（SolidJS）+ Desktop（Tauri v2 / Electron）三客户端共享 Hono HTTP 后端 + （来源：[OpenCode 架构文档](../opencode/03-architecture.md)） - MDNS 本地网络设备发现 -- 社区项目 Remote-OpenCode 支持 Discord 控制 - **劣势**：远程 workspace 仍为实验性功能，稳定性待验证 **Goose**（REST API 驱动）： - `goose-server`（Axum HTTP）提供 REST API，Electron Desktop App 作为 GUI 客户端 -- `ComputerController` 扩展提供 `web_scrape`、`computer_control` 浏览器自动化 -- **劣势**：无 Web UI、无移动端、REST API 不如 WebSocket 实时 + （来源：[Goose 架构文档](../goose/03-architecture.md)、[EVIDENCE](../goose/EVIDENCE.md)） +- **劣势**：无浏览器 Web UI、无移动端 **Codex CLI**（IDE 集成导向）： -- `codex app-server` 提供 JSON-RPC 2.0 over stdio/WebSocket（90+ 方法） -- `--remote` 连接远程 app-server 实例 +- `codex app-server` 提供 JSON-RPC 2.0 over stdio/WebSocket，`--remote` 连接远程实例 + （来源：[Codex CLI 命令文档](../codex-cli/02-commands.md)、[EVIDENCE](../codex-cli/EVIDENCE.md)） - **劣势**：面向 IDE 插件设计，非通用远程访问 ### 为什么没有其他 Agent 复制 Remote Control？（作者分析，非源码验证结论） @@ -421,4 +423,4 @@ Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有 | **产品定位差异** ⚠️ 推断 | Claude Code 定位"企业级 AI 编程平台"（含 Web/Desktop/Mobile 多端），大多数 Agent 定位"开发者本地工具" | | **替代方案成本更低** ⚠️ 推断 | Kimi CLI/OpenCode 等通过本地 Web UI + 开端口的方式提供了基本的远程访问能力，对多数场景已够用 | -> **免责声明**：以上数据基于 2026 年 Q1 源码分析和官方文档，可能已过时。Qwen Code 的 Remote Control 功能缺口已被标记为 P2 优先级。 +> **免责声明**：以上数据基于 2026 年 Q1 源码分析和官方文档，可能已过时。 From ceb5793c18b32f9d6df18ec1e64a0def344cffcf Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 18:27:53 +0800 Subject: [PATCH 08/15] feat: add implementation reference section from v2.1.87 binary analysis Deep decompilation of Claude Code v2.1.87 SEA binary reveals: - Redux state machine: 13 bridge state fields (replBridge*) - Polling config: server-tunable with Zod validation schema - Message protocol: 8+ JSON-lines message types (wire format) - Token refresh system: JWT expiry-based with 5min buffer - initReplBridge callback interface and return values - Bridge child process environment variables - Concurrent session PID file format and race condition - 5 undocumented CLI parameters (--spawn session, --session-timeout-ms, etc.) - Client type detection logic via environment variables - 5 additional API endpoints and 7 new environment variables Section targets Code Agent developers as implementation reference. Co-authored-by: Qwen-Coder --- docs/tools/claude-code/08-remote-control.md | 405 +++++++++++++++++++- 1 file changed, 398 insertions(+), 7 deletions(-) diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index 2d3630dd..c9a635d4 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -191,16 +191,21 @@ Remote Control 的安全架构采用多层防护： | 端点 | 用途 | 来源 | |------|------|------| | `claude.ai/api/claude_code/settings` | 远程设置获取 | [EVIDENCE.md](./EVIDENCE.md) | -| `claude.ai/api/claude_code/policy_limits` | 策略限制查询 | [EVIDENCE.md](./EVIDENCE.md) | -| `claude.ai/api/oauth/authorize` | OAuth 认证 | [EVIDENCE.md](./EVIDENCE.md) | +| `claude.ai/api/claude_code/policy_limits` | 策略限制查询（RC 管理员门控检查） | [EVIDENCE.md](./EVIDENCE.md) | +| `claude.ai/api/oauth/authorize` | OAuth 认证（RC 注册需 full-scope token） | [EVIDENCE.md](./EVIDENCE.md) | | `api.anthropic.com/api/claude_code/metrics` | 遥测上报（资格检查依赖此通道） | [EVIDENCE.md](./EVIDENCE.md) | -| `claude.ai/api/ws/speech_to_text/voice_stream` | 语音转文字（非 Remote Control，但共用 WebSocket 基础设施） | [EVIDENCE.md](./EVIDENCE.md) | +| `claude.ai/api/ws/speech_to_text/voice_stream` | 语音转文字（共用 WebSocket 基础设施） | [EVIDENCE.md](./EVIDENCE.md) | +| `api.anthropic.com/admin_requests/eligibility` | 资格检查端点（RC 启用前的资格判定） | v2.1.87 反编译 | +| `api.anthropic.com/api/claude_code_grove` | Grove 端点（用途待确认） | v2.1.87 反编译 | +| `api.anthropic.com/api/claude_code_penguin_mode` | 快速模式端点 | v2.1.87 反编译 | +| `api.anthropic.com/api/claude_code_shared_session_transcripts` | 共享会话转录 | v2.1.87 反编译 | +| `api.anthropic.com/api/claude_code/team_memory` | 团队记忆 | v2.1.87 反编译 | -> **注意**：Remote Control 专用的会话注册和消息中继端点 URL 未在 v2.1.81 二进制的 `--help` 输出或 rodata 段中明文暴露。上述端点为反编译中确认的基础设施端点，可能被 Remote Control 复用。 +> **注意**：Remote Control 专用的会话注册和消息中继端点 URL 未在 v2.1.87 二进制中明文暴露（可能通过拼接构造或从服务端动态获取）。上述端点为反编译中确认的基础设施端点。 ### 相关环境变量 -前 6 项来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)；后 4 项为反编译提取的变量名（[EVIDENCE.md](./EVIDENCE.md)），具体用途为推断。 +前 7 项来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)；其余为 v2.1.87 反编译提取。 | 变量 | 影响 | 来源 | |------|------|------| @@ -211,8 +216,12 @@ Remote Control 的安全架构采用多层防护： | `CLAUDE_CODE_USE_BEDROCK` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | | `CLAUDE_CODE_USE_VERTEX` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | | `CLAUDE_CODE_USE_FOUNDRY` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | -| `SESSION_ACCESS_TOKEN` | 会话访问凭证（反编译提取） | EVIDENCE.md | -| `WEBSOCKET_AUTH_*` | WebSocket 认证凭证（反编译提取） | EVIDENCE.md | +| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 会话访问凭证；存在时客户端类型被判定为 "remote" | v2.1.87 反编译 | +| `CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR` | WebSocket 认证（文件描述符传递）；存在时客户端类型被判定为 "remote" | v2.1.87 反编译 | +| `CLAUDE_CODE_ENTRYPOINT` | 值为 `"remote"` 时标记为远程入口，改变客户端类型行为 | v2.1.87 反编译 | +| `CLAUDE_CODE_REMOTE` | 存在时影响 auto-memory 行为；传递给 teammate spawn 环境 | v2.1.87 反编译 | +| `CLAUDE_CODE_ENVIRONMENT_KIND` | 值为 `"bridge"` 时标识为桥接子进程 | v2.1.87 反编译 | +| `CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2` | 值为 `"1"` 时启用 V2 会话入口协议 | v2.1.87 反编译 | | `SSE_PORT` | SSE 本地端口（反编译提取，可能用于 Remote Control 或 MCP SSE 传输） | EVIDENCE.md | ## Remote Control vs Claude Code on the Web @@ -304,6 +313,388 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | **Kimi CLI** | ❌ 无（有 Wire 协议但未实现远程控制） | | **其他 Agent** | ❌ 无 | +## 实现参考：面向 Code Agent 开发者 + +> 以下数据来自 v2.1.87 ELF 二进制（SEA，228MB，2026-03-29 构建）中嵌入的 JavaScript 代码反编译提取。变量名经过 minification 处理（如 `Z6H`、`Cl7`、`Ra`），但字符串常量、对象键名、Zod schema 定义保持可读。 +> +> **适用场景**：其他 Code Agent 开发者实现类似"远程控制"功能时，可将本节作为架构参考。Claude Code 的实现是经过生产验证的方案，但并非唯一可行路径。 + +### 内部状态机（Redux Store） + +Remote Control 在 Redux AppState 中维护 13 个桥接状态字段（反编译提取自 `Z6H` 初始状态对象）： + +```javascript +// v2.1.87 二进制反编译：AppState 初始状态 +replBridgeEnabled: false, // 是否启用桥接（旧字段，已迁移至 remoteControlAtStartup） +replBridgeExplicit: false, // 用户是否主动启用（vs 自动启用） +replBridgeOutboundOnly: false, // 仅出站模式：可推送消息但不接受远程控制指令 +replBridgeConnected: false, // 与中继服务器的连接状态 +replBridgeSessionActive: false, // 是否有活跃的远程客户端会话 +replBridgeReconnecting: false, // 是否正在重连中 +replBridgeConnectUrl: undefined, // 远程客户端连接 URL（供 QR 码/链接使用） +replBridgeSessionUrl: undefined, // 会话管理 URL +replBridgeEnvironmentId: undefined,// 运行环境标识（用于 spawn 多会话路由） +replBridgeSessionId: undefined, // 当前桥接会话 ID +replBridgeError: undefined, // 最近错误信息 +replBridgeInitialName: undefined, // 初始会话名称（--name 参数值） +showRemoteCallout: false // UI 标志：是否显示远程控制提示 +``` + +**状态迁移逻辑**（反编译 `Cl7` 函数）： + +```javascript +// 旧版迁移：replBridgeEnabled → remoteControlAtStartup +function migrateBridgeConfig(state) { + if (state.replBridgeEnabled === undefined) return state; + if (state.remoteControlAtStartup !== undefined) return state; + let next = {...state, remoteControlAtStartup: Boolean(state.replBridgeEnabled)}; + delete next.replBridgeEnabled; + return next; +} +``` + +**实现要点**： +- `replBridgeEnabled` 是旧字段名，当前版本使用 `remoteControlAtStartup`（选项：`"true"` / `"false"` / `"default"`） +- `replBridgeOutboundOnly` 为 `true` 时，用户界面显示 "This session is outbound-only. Enable Remote Control locally to allow inbound control." +- `replBridgeReconnecting` 用于 UI 展示重连状态（Connecting/Disconnected 循环问题与此状态相关） + +### Polling 配置参数（服务端可调） + +服务端下发 polling 配置，客户端通过 Zod schema 校验后使用。以下为反编译提取的默认值和校验规则： + +```javascript +// v2.1.87 二进制反编译：默认 polling 配置 +const DEFAULT_POLL_CONFIG = { + poll_interval_ms_not_at_capacity: 2000, // 未满容量时：2 秒轮询 + poll_interval_ms_at_capacity: 600000, // 满容量时：10 分钟心跳（或 0=禁用） + non_exclusive_heartbeat_interval_ms: 0, // 非独占心跳：默认关闭 + multisession_poll_interval_ms_not_at_capacity: 2000, // 多会话未满：2 秒 + multisession_poll_interval_ms_partial_capacity: 2000, // 多会话部分满：2 秒 + multisession_poll_interval_ms_at_capacity: 600000, // 多会话满：10 分钟 + reclaim_older_than_ms: 5000, // 回收阈值：5 秒后回收废弃会话 + session_keepalive_interval_v2_ms: 120000 // WebSocket ping/pong：2 分钟 +}; +``` + +**Zod 校验 schema**（`hM9`）： + +| 参数 | 类型 | 约束 | 默认值 | +|------|------|------|--------| +| `poll_interval_ms_not_at_capacity` | `int` | `≥ 100` | `2000` | +| `poll_interval_ms_at_capacity` | `int` | `= 0 或 ≥ 100` | `600000` | +| `non_exclusive_heartbeat_interval_ms` | `int` | `≥ 0` | `0` | +| `reclaim_older_than_ms` | `int` | `≥ 1` | `5000` | +| `session_keepalive_interval_v2_ms` | `int` | `≥ 0` | `120000` | + +**配置加载机制**： + +```javascript +// 通过远程配置服务加载，TTL 5 分钟 +loadConfig("tengu_bridge_poll_interval_config", DEFAULT_POLL_CONFIG, 300000); +``` + +**实现要点**： +- Poll 间隔是**服务端可调**的，客户端不应硬编码——通过远程配置服务动态下发 +- 满容量时（`at_capacity`）poll 间隔从 2s 切换到 10min，实质进入"心跳保活"模式 +- `reclaim_older_than_ms: 5000` 意味着服务器 5 秒无响应即可判定会话废弃——实现者需注意网络抖动场景 +- `session_keepalive_interval_v2_ms` 是 WebSocket 层的 ping/pong，与 HTTP 层的 poll 互补 + +### 消息协议（Wire Format） + +Remote Control 使用 JSON-lines 格式进行消息传输。以下消息类型来自反编译提取： + +| 消息类型 | 方向 | 用途 | Zod Schema | +|----------|------|------|------------| +| `user` | 远程→本地 | 用户输入消息 | `y.object({type: "user", content: [...]})` | +| `assistant` | 本地→远程 | Agent 响应 | — | +| `system` | 本地→远程 | 系统消息 | — | +| `control_request` | 远程→本地 | 权限/模式/模型变更请求 | — | +| `control_response` | 本地→远程 | 对 control_request 的响应 | — | +| `control_cancel_request` | 本地→远程 | 取消未决的 control_request | — | +| `keep_alive` | 双向 | 心跳保活（收到时跳过处理） | `y.object({type: y.literal("keep_alive")})` | +| `update_environment_variables` | 本地→本地 | 运行时环境变量更新（如 token 刷新） | — | +| `bridge_state` | 双向 | 桥接状态变更通知 | — | + +**keep_alive 处理逻辑**： + +```javascript +// 收到 keep_alive 消息时直接跳过，不做任何处理 +if (message.type === "keep_alive") continue; +``` + +**token 动态更新机制**： + +```javascript +// 通过 stdin 注入更新后的 access token +function updateAccessToken(newToken) { + this.accessToken = newToken; + this.writeStdin(JSON.stringify({ + type: "update_environment_variables", + variables: { CLAUDE_CODE_SESSION_ACCESS_TOKEN: newToken } + }) + "\n"); +} +``` + +### Token 刷新系统 + +反编译提取的 token 刷新参数（`dn$` 函数）： + +| 参数 | 值 | 说明 | +|------|-----|------| +| `refreshBufferMs` | `300000`（5 分钟） | Token 过期前提前刷新的缓冲时间 | +| `followUpRefreshMs` | `1800000`（30 分钟） | 刷新后的 follow-up 刷新间隔 | +| `maxFailures` | `3` | 最大刷新失败次数 | +| `retryDelayMs` | `60000`（1 分钟） | 刷新失败后的重试延迟 | + +**刷新策略**：基于 JWT expiry 的定时调度——在 token 过期前 5 分钟触发刷新，最多失败 3 次后放弃。 + +### Bridge 初始化接口（initReplBridge） + +反编译提取的 `initReplBridge` 回调接口，这是 Remote Control 的核心桥接层： + +```javascript +// initReplBridge 调用签名 +const bridge = await initReplBridge({ + // 远程端发来的用户消息 + onInboundMessage(message) { /* 注入到本地对话流 */ }, + + // 远程端的权限审批响应 + onPermissionResponse(response) { /* 注入 control_response */ }, + + // 远程端请求中断当前操作 + onInterrupt() { abortController?.abort() }, + + // 远程端切换模型 + onSetModel(model) { /* 更新当前模型 */ }, + + // 远程端调整 thinking token 预算 + onSetMaxThinkingTokens(tokens) { /* 更新配置 */ }, + + // 桥接状态变更通知 + onStateChange(state, metadata) { /* 更新 Redux store */ }, + + // 初始消息（用于恢复断连前的上下文） + initialMessages: previousMessages.length > 0 ? previousMessages : undefined +}); +``` + +**返回值**： + +| 字段 | 类型 | 说明 | +|------|------|------| +| `bridgeSessionId` | `string` | 桥接会话唯一标识 | +| `sessionIngressUrl` | `string` | 会话入口 URL | +| `environmentId` | `string` | 运行环境标识 | +| `sendControlRequest()` | `function` | 向远程端发送控制请求 | +| `sendControlCancelRequest()` | `function` | 取消未决的控制请求 | +| `writeMessages()` | `function` | 向远程端写入消息流 | +| `teardown()` | `function` | 关闭桥接、清理资源 | + +**会话注册响应格式**（反编译 `ZH` 函数）： + +```javascript +// initReplBridge 成功后，构造响应数据 +{ + session_url: buildSessionUrl(bridgeSessionId, sessionIngressUrl), + connect_url: buildConnectUrl(environmentId, sessionIngressUrl), + environment_id: environmentId +} +``` + +### Bridge 子进程环境变量 + +Server 模式下 `--spawn` 创建的子进程继承以下环境变量（反编译提取）： + +```javascript +// spawn 子进程的环境变量设置 +{ + CLAUDE_CODE_OAUTH_TOKEN: undefined, // 显式清除，防止子进程用 OAuth token 重新注册 + CLAUDE_CODE_ENVIRONMENT_KIND: "bridge", // 标识为桥接子进程 + CLAUDE_CODE_SESSION_ACCESS_TOKEN: accessToken, // 传递会话访问凭证 + CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2: "1", // 启用 V2 会话入口协议 + CLAUDE_CODE_USE_CCR_V2: "1", // 使用 CCR V2（如果 useCcrV2=true） + CLAUDE_CODE_WORKER_EPOCH: String(workerEpoch), // Worker epoch（如果 useCcrV2=true） + CLAUDE_CODE_FORCE_SANDBOX: "1" // 强制沙箱（如果 --sandbox） +} +``` + +**实现要点**： +- `CLAUDE_CODE_OAUTH_TOKEN` 被显式设为 `undefined`——子进程不应使用父进程的 OAuth 凭证重新注册，而应通过 `SESSION_ACCESS_TOKEN` 接管会话 +- `CLAUDE_CODE_ENVIRONMENT_KIND: "bridge"` 让子进程知道自己在桥接模式下运行，调整行为（如不启动自己的 polling） +- `CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2: "1"` 启用更新的会话入口协议 + +### 并发会话管理（PID File） + +反编译提取的会话注册文件格式和更新逻辑： + +**PID 文件路径**：`$CONFIG_DIR/sessions/{process.pid}.json` + +**注册时写入**： + +```javascript +// 会话注册：写入 PID 文件 +await fs.writeFile(pidFilePath, JSON.stringify({ + pid: process.pid, + sessionId: getSessionId(), + cwd: getCurrentWorkingDir(), + startedAt: Date.now(), + kind: sessionKind, // "interactive" | "server" | ... + entrypoint: process.env.CLAUDE_CODE_ENTRYPOINT, // "cli" | "remote" | ... + name: sessionName // 可选 +})); +``` + +**更新逻辑**（`gv7` 函数）： + +```javascript +// 非原子更新：read → merge → write（存在竞态条件） +async function updatePidFile(updates) { + const path = join(configDir(), `${process.pid}.json`); + try { + const existing = JSON.parse(await fs.readFile(path, "utf8")); + await fs.writeFile(path, JSON.stringify({...existing, ...updates})); + } catch (err) { + log(`[concurrentSessions] updatePidFile failed: ${formatError(err)}`); + } +} +``` + +**已知问题**：此 read-modify-write 操作**非原子**（缺少 tmp+rename），在并发场景下可能导致 JSON 文件损坏（[GitHub #41195](https://github.com/anthropics/claude-code/issues/41195)）。实现者应使用 `writeFileSync(tmp, data)` + `renameSync(tmp, path)` 的原子写入模式。 + +### Bridge 会话注册 Schema + +反编译提取的 Zod schema（`pN9`），用于注册桥接会话： + +```javascript +// 会话注册请求体 schema +const bridgeSessionSchema = z.object({ + session_id: z.string(), // 会话唯一标识 + ws_url: z.string(), // WebSocket 连接 URL + work_dir: z.string().optional() // 工作目录（可选） +}); +``` + +### CLI 完整参数（remote-control 子命令） + +反编译提取的 `claude remote-control` 完整参数列表： + +``` +claude remote-control [options] + --spawn Spawn 模式：same-dir | worktree | session + --capacity 最大并发会话数 + --create-session-in-dir 在指定目录创建会话 + --session-id 恢复指定会话 ID + --continue 继续上次会话 + --permission-mode 权限模式 + --name 会话名称 + --verbose 详细日志 + --sandbox 启用沙箱 + --debug-file 调试输出文件 + --session-timeout-ms 会话超时（毫秒） +``` + +**新增发现**（相比官方文档）： + +| 参数 | 官方文档 | 反编译发现 | +|------|----------|-----------| +| `--spawn session` | 未提及 | 第三种 spawn 模式 | +| `--create-session-in-dir` | 未提及 | 在指定目录创建会话 | +| `--session-id` | 未提及 | 恢复特定会话 ID | +| `--session-timeout-ms` | 未提及 | 精确控制会话超时时间 | +| `--debug-file` | 未提及 | 调试输出到文件 | + +### 遥测事件 + +Remote Control 相关的遥测事件前缀为 `tengu_bridge_*`，反编译提取到以下事件名： + +| 事件名 | 用途 | +|--------|------| +| `tengu_bridge_token_refreshed` | Token 刷新成功/失败追踪 | +| `tengu_bridge_multi_session_denied` | 多会话访问被拒绝（capacity 已满） | +| `tengu_bridge_poll_interval_config` | Polling 配置加载追踪 | +| `tengu_concurrent_sessions` | 并发会话状态追踪 | + +### 客户端类型检测 + +反编译提取的客户端类型判定逻辑： + +```javascript +// 客户端类型检测 +function detectClientType() { + const hasSessionToken = process.env.CLAUDE_CODE_SESSION_ACCESS_TOKEN + || process.env.CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR; + if (process.env.CLAUDE_CODE_ENTRYPOINT === "remote" || hasSessionToken) { + return "remote"; // Remote Control 桥接客户端 + } + // ... 其他类型判断 +} +``` + +**关键环境变量**： + +| 变量 | 说明 | 来源 | +|------|------|------| +| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 存在时标记为 "remote" 客户端类型 | 反编译 | +| `CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR` | 存在时标记为 "remote" 客户端类型（文件描述符方式传递 WebSocket 认证） | 反编译 | +| `CLAUDE_CODE_ENTRYPOINT` | 值为 `"remote"` 时标记为远程入口 | 反编译 | +| `CLAUDE_CODE_REMOTE` | 存在时影响 auto-memory 行为；传递给 teammate spawn 环境 | 反编译 | + +### 实现建议：架构模式总结 + +基于以上反编译分析，实现类似 Remote Control 功能的推荐架构模式： + +``` +┌──────────────────────────────────────────────────────────────────┐ +│ 推荐架构模式 │ +├──────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────┐ ① Register ┌──────────────┐ │ +│ │ Local │ ──────────────────→ │ │ │ +│ │ Agent │ ←────────────────── │ Relay │ │ +│ │ Process │ ② Token + URL │ Server │ │ +│ │ │ │ │ │ +│ │ │ ③ HTTPS Poll │ - 消息路由 │ │ +│ │ │ ──────────────────→ │ - 凭证管理 │ │ +│ │ │ ←────────────────── │ - 会话追踪 │ │ +│ │ │ ④ Stream Msgs │ - 配置下发 │ │ +│ └─────────┘ └──────┬───────┘ │ +│ │ │ +│ ⑤ WebSocket/HTTPS │ +│ │ │ +│ ┌──────▼───────┐ │ +│ │ Remote │ │ +│ │ Client │ │ +│ │ (Web/Mobile) │ │ +│ └──────────────┘ │ +│ │ +│ 关键设计决策： │ +│ 1. 本地仅出站 HTTPS → 企业防火墙穿透 │ +│ 2. 服务端下发 poll 配置 → 运行时可调 │ +│ 3. JWT + 短期凭证 → 定时刷新 (过期前 5min) │ +│ 4. JSON-lines 消息协议 → 简单可扩展 │ +│ 5. PID file 并发注册 → 需原子写入（tmp+rename） │ +│ 6. 子进程显式清除 OAuth token → 防止重复注册 │ +│ 7. keep_alive 空操作 → 降低无用处理开销 │ +│ 8. 客户端类型检测 → 区分 local/remote/bridge 行为 │ +└──────────────────────────────────────────────────────────────────┘ +``` + +### 与 Gemini CLI 的对比参考 + +Qwen Code 基于 Gemini CLI 分叉（[Qwen Code EVIDENCE](../qwen-code/EVIDENCE.md)），Gemini CLI 使用 Google Cloud relay 实现 `--remote` 功能。两者实现路径对比： + +| 维度 | Claude Code | Gemini CLI / Qwen Code | +|------|-------------|----------------------| +| **中继架构** | Anthropic API 中继 | Google Cloud relay | +| **本地传输** | HTTPS polling（服务端可调） | SSE (Server-Sent Events) | +| **认证** | claude.ai OAuth full-scope | Google OAuth | +| **消息格式** | JSON-lines（8+ 消息类型） | SSE stream | +| **状态管理** | Redux 13 字段状态机 | — | +| **Token 刷新** | JWT expiry - 5min 提前刷新 | — | +| **多会话** | `--spawn` + `--capacity` + PID file | — | + +> **注意**：Gemini CLI 的 `--remote` 实现细节未公开源码，对比数据来自 CLI help 输出和行为观察，标注 `⚠️` 的条目为推断。 + ## 评价与优缺点分析 ### 核心优势 From 307991abb5b2b926d54697250055a3b08415f767 Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 18:58:25 +0800 Subject: [PATCH 09/15] feat: three-plane architecture split, local state IPC checklist, implementer decision table Address GPT-5.4 round 4 review (4 comments): 1. Fix Goose Web UI inconsistency: matrix now links to goose.md, bullet clarifies that 'Web' label = HTTP API (no standalone browser frontend) 2. Split architecture into Control/Data/Local State planes with component tables per plane, showing evidence source for each component 3. Expand local state & IPC section: add plane attribution, lifecycle, recoverability columns + implementer notes (PID naming semantics, bridgeSessionId vs sessionId distinction) 4. Add Implementer Checklist: 8-item design decision table covering source of truth, eligibility/telemetry coupling, token scoping, poll config strategy, proxy support, crash recovery, session isolation, and diagnostic logging Co-authored-by: Qwen-Coder --- docs/tools/claude-code/08-remote-control.md | 72 +++++++++++++++++++-- 1 file changed, 65 insertions(+), 7 deletions(-) diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index c9a635d4..6a953956 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -124,6 +124,43 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic | **传输安全** | 全程 TLS 加密，与普通 Claude Code 会话相同 | ✅ 官方确认 | | **凭证体系** | 多个短期凭证，每个限定单一用途，独立过期 | ✅ 官方确认 | +#### 三层架构拆分：控制面 / 数据面 / 本地状态面 + +从实现者视角，Remote Control 可拆分为三个职责清晰的子系统： + +**控制面（Control Plane）**——会话注册、资格检查、凭证管理、策略执行： + +| 组件 | 职责 | 证据来源 | +|------|------|----------| +| 会话注册 | 用 full-scope OAuth token 向中继服务器注册会话，获取 `SESSION_ACCESS_TOKEN` | 官方文档 + 反编译 | +| 资格检查 | `admin_requests/eligibility` 端点判定用户是否可使用 RC（受订阅类型、管理员策略、组织策略影响） | v2.1.87 反编译 | +| 凭证刷新 | JWT expiry 驱动的定时刷新（过期前 5 分钟触发，最多失败 3 次） | v2.1.87 反编译 | +| 策略执行 | `policy_limits` 端点查询组织级 RC 开关；Team/Enterprise 管理员门控 | EVIDENCE.md | +| 配置下发 | `tengu_bridge_poll_interval_config` 动态下发 polling 参数（TTL 5 分钟） | v2.1.87 反编译 | +| PID 文件管理 | `~/.claude/sessions/{pid}.json` 跟踪并发会话 | v2.1.87 反编译 | + +**数据面（Data Plane）**——消息传输、双向同步、流式响应： + +| 组件 | 职责 | 证据来源 | +|------|------|----------| +| 出站轮询 | 2s（未满容量）或 10min（满容量）HTTPS poll 获取待处理消息 | 官方文档 + 反编译 | +| 流式响应 | 服务端通过 streaming connection 下发 agent 输出到远程客户端 | 官方文档 | +| 消息协议 | JSON-lines 格式，8+ 消息类型（`user`/`assistant`/`control_request`/`keep_alive` 等） | v2.1.87 反编译 | +| 本地 IPC | Unix domain socket (`/tmp/cc-socks/*.sock`) 用于进程内消息传递 | GitHub Issues | +| 对话持久化 | `~/.claude/projects//*.jsonl` 存储完整对话流 | EVIDENCE.md | +| WebSocket ping/pong | `session_keepalive_interval_v2_ms: 120000`（2 分钟）维持连接活性 | v2.1.87 反编译 | + +**本地状态面（Local State Plane）**——Redux 状态机、环境变量、运行时状态： + +| 组件 | 职责 | 证据来源 | +|------|------|----------| +| Redux 状态机 | 13 个 `replBridge*` 字段管理桥接生命周期（enabled/connected/active/reconnecting 等） | v2.1.87 反编译 | +| 客户端类型检测 | `CLAUDE_CODE_SESSION_ACCESS_TOKEN` / `WEBSOCKET_AUTH_FILE_DESCRIPTOR` / `ENTRYPOINT` 判定客户端类型 | v2.1.87 反编译 | +| 环境变量配置 | 14+ 环境变量控制 RC 行为（认证模式、网络代理、沙箱、远程环境等） | 官方文档 + 反编译 | +| initReplBridge | 核心桥接层，通过 7 个回调函数连接远程端和本地会话 | v2.1.87 反编译 | + +> **设计启示**：三层分离使得**控制面变更不影响消息传输**（如修改 polling 策略无需改消息格式），**本地状态面独立于网络**（进程崩溃后可从 PID 文件和对话历史重建部分状态）。实现者可参考此拆分设计自己的子系统边界。 + ### 会话生命周期 ``` @@ -149,11 +186,16 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic ### 会话文件与本地存储 -| 路径 | 内容 | 来源 | -|------|------|------| -| `~/.claude/sessions/{pid}.json` | 会话元数据：`name`、`status`、`updatedAt`、`bridgeSessionId`、`messagingSocketPath` | GitHub Issues | -| `/tmp/cc-socks/*.sock` | 本地进程间通信的 Unix domain socket | GitHub Issues | -| `~/.claude/projects//` | 会话对话历史（`.jsonl` 格式），`cleanupPeriodDays`（默认 30 天）后自动清理 | [EVIDENCE.md](./EVIDENCE.md) | +| 路径 | 内容 | 所属面 | 生命周期 | 可恢复性 | 来源 | +|------|------|--------|----------|----------|------| +| `~/.claude/sessions/{pid}.json` | 会话元数据：`pid`、`sessionId`、`cwd`、`startedAt`、`kind`、`entrypoint`、`name`、`status`、`updatedAt`、`bridgeSessionId`、`messagingSocketPath` | 控制面 + 本地状态面 | 每个 interactive process 一个文件；进程退出后残留但无意义 | ⚠️ 推断：进程退出后文件残留，但 `reclaim_older_than_ms: 5000` 意味着服务端 5 秒后即视为废弃。**进程重启不会自动恢复** | GitHub Issues + v2.1.87 反编译 | +| `/tmp/cc-socks/*.sock` | Unix domain socket，用于本地进程间消息传递（如 UI bridge、多客户端复用） | 数据面（本地 IPC） | 随进程创建/销毁；进程退出即失效 | ❌ 不可恢复：Unix socket 文件随进程退出失效，重新连接需建立新 socket | GitHub Issues | +| `~/.claude/projects//` | 会话对话历史（`.jsonl` 格式），包含完整对话流；`cleanupPeriodDays`（默认 30 天）后自动清理 | 数据面（持久化） | 独立于 Remote Control 生命周期；与普通会话共享存储 | ✅ 可恢复：对话历史在磁盘上持久化，可用于 `/continue` 或 `/teleport` 恢复上下文 | [EVIDENCE.md](./EVIDENCE.md) | + +> **实现者注意事项**： +> - PID 文件命名（`{pid}.json`）意味着**每个 OS 进程一个远程会话**，而非每个 bridge session 一个 state file。Server 模式 `--spawn` 创建的子进程各自有独立的 PID 文件 +> - `messagingSocketPath` 字段存储在 PID 文件中，表明 Unix socket 路径是**服务端/客户端协商结果**，而非硬编码 +> - `bridgeSessionId` 与 `sessionId` 是不同概念：`sessionId` 是本地会话 ID，`bridgeSessionId` 是中继服务器分配的桥接 ID ### `--spawn` 多会话架构 @@ -224,6 +266,21 @@ Remote Control 的安全架构采用多层防护： | `CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2` | 值为 `"1"` 时启用 V2 会话入口协议 | v2.1.87 反编译 | | `SSE_PORT` | SSE 本地端口（反编译提取，可能用于 Remote Control 或 MCP SSE 传输） | EVIDENCE.md | +### 实现者 Checklist：设计决策表 + +> 以下清单提炼自反编译分析和官方文档。每个条目对应实现一个 Remote Control 类功能时**必须做出的设计决策**，Claude Code 的选择作为参考标注。 + +| # | 设计决策 | Claude Code 的选择 | 实现考量 | +|---|----------|-------------------|----------| +| **1** | **本地与云端谁持有会话状态（source of truth）？** | **云端是控制面 source of truth**（资格检查、策略执行、配置下发均在服务端）；本地持有数据面状态（对话历史 `.jsonl`、PID 文件） | 云端控制面允许运行时调整（如 poll 间隔）无需客户端升级；但需要网络可用才能启动 | +| **2** | **资格检查是否复用遥测通道？** | **疑似耦合**：`DISABLE_TELEMETRY=1` 阻止 RC 注册（[#41189](https://github.com/anthropics/claude-code/issues/41189)），根因未确认 | 解耦更安全——遥测开关不应影响功能可用性；但共享通道可简化实现 | +| **3** | **多客户端鉴权是共享 token 还是分 scope token？** | **分 scope token**：`SESSION_ACCESS_TOKEN`（会话访问）、`WEBSOCKET_AUTH_FILE_DESCRIPTOR`（WebSocket 认证），各独立过期 | 多 token 增加管理复杂度，但降低凭证泄露影响面 | +| **4** | **Poll 间隔是硬编码还是服务端可调？** | **服务端下发，Zod schema 校验**，TTL 5 分钟缓存 | 服务端可调允许根据负载动态调整（满容量时从 2s 切到 10min），但需考虑配置服务可用性 | +| **5** | **网络/代理环境是否一等公民支持？** | **部分支持**：`HOST_HTTP_PROXY_PORT`、`HOST_SOCKS_PROXY_PORT` 存在于二进制中，但 RC 在代理环境下的连接问题仍被报告（[#41324](https://github.com/anthropics/claude-code/issues/41324)） | 企业代理是常见障碍；出站 HTTPS 需正确处理 CONNECT 方法、证书链、认证代理 | +| **6** | **进程崩溃后状态可恢复吗？** | **部分可恢复**：对话历史 `.jsonl` 可通过 `/continue` 恢复；但桥接状态（`replBridge*`）纯内存，进程退出即丢失；PID 文件残留但服务端 5s 后视为废弃 | 需区分「对话上下文恢复」（容易）和「桥接会话恢复」（需要云端配合） | +| **7** | **并发会话如何隔离？** | `--spawn same-dir`（共享 CWD）或 `--spawn worktree`（独立 Git worktree），`--capacity` 上限 32 | 文件隔离是基本需求；worktree 方案允许并行修改不同分支但增加磁盘占用 | +| **8** | **诊断日志写到哪里？** | `--debug-file ` 参数指定调试输出文件；`--verbose` 控制连接/会话日志详细度 | 生产环境中需要可开关的详细日志，用于排查连接循环、凭证刷新失败等问题 | + ## Remote Control vs Claude Code on the Web 两者经常混淆，但本质不同： @@ -770,7 +827,7 @@ Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有 | 能力 | Claude Code | Kimi CLI | OpenCode | Goose | Codex CLI | Copilot CLI | Aider | |------|:-:|:-:|:-:|:-:|:-:|:-:|:-:| | **终端会话远程操控** | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | -| **Web/浏览器 UI** | ❌ | ✅ FastAPI+React | ✅ SolidJS（实验） | ❌（仅 Desktop App） | ❌ | ❌ | ❌ | +| **Web/浏览器 UI** | ❌ | ✅ FastAPI+React | ✅ SolidJS（实验） | ❌（仅 Desktop App，见 [说明](../goose.md)） | ❌ | ❌ | ❌ | | **多客户端同时连接** | ✅ TUI+浏览器+Mobile | ✅ Wire 四客户端 | ✅ TUI+Web+Desktop | ✅ CLI+Desktop | ❌ | ❌ | ❌ | | **原生移动端 App** | ✅ iOS/Android | ❌（移动浏览器可访问 Web UI） | ❌ | ❌ | ❌ | ❌ | ❌ | | **零入站端口** | ✅（outbound-only 中继） | ❌（开端口） | ❌（开端口） | ❌（开端口） | ❌ | N/A | N/A | @@ -796,7 +853,8 @@ Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有 **Goose**（REST API 驱动）： - `goose-server`（Axum HTTP）提供 REST API，Electron Desktop App 作为 GUI 客户端 （来源：[Goose 架构文档](../goose/03-architecture.md)、[EVIDENCE](../goose/EVIDENCE.md)） -- **劣势**：无浏览器 Web UI、无移动端 +- 仓库文档宣称支持 CLI/Web/Desktop 三种客户端（[Goose 概述](../goose.md)），但实际源码中仅有 CLI (`goose-cli`) 和 Desktop (`ui/desktop/`) 两个具体客户端实现；"Web" 标签指 `goose-server` 的 HTTP API 可供 Web 客户端连接，但无独立浏览器前端 +- **劣势**：无独立浏览器 Web UI（仅有 HTTP API）、无移动端 **Codex CLI**（IDE 集成导向）： - `codex app-server` 提供 JSON-RPC 2.0 over stdio/WebSocket，`--remote` 连接远程实例 From c00b04f15ea90057ad6523b860b6a98f6786f5e9 Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 19:17:14 +0800 Subject: [PATCH 10/15] docs: add section numbers to all headings Numbering scheme: 8.1-8.15 (H2), 8.x.1-8.x.n (H3), 8.x.y.1 (H4) Co-authored-by: Qwen-Coder --- docs/tools/claude-code/08-remote-control.md | 94 ++++++++++----------- 1 file changed, 47 insertions(+), 47 deletions(-) diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index 6a953956..bb1d4062 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -4,7 +4,7 @@ > > **数据来源**：CLI 子命令/参数（`claude remote-control`、`--remote-control`/`--rc`、`--spawn`、`--capacity`）和故障排查指南来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)（2026-03）；`/remote-control` 斜杠命令类型来自 v2.1.81 二进制反编译；环境变量名来自 [EVIDENCE.md](./EVIDENCE.md) 反编译提取。 -## 概述 +## 8.1 概述 Remote Control 是 Claude Code 的跨设备会话桥接功能，在 18 款主流 AI 编程 Agent 中**为 Claude Code 独有**（[功能矩阵](../../comparison/features.md)）。它解决了开发者的一个核心痛点：启动了一个长时间的终端代理任务后，需要离开工位继续监控或干预。 @@ -15,7 +15,7 @@ Remote Control 是 Claude Code 的跨设备会话桥接功能，在 18 款主流 - **自动重连**：笔记本电脑睡眠或网络短暂中断后自动恢复连接 - **零入站端口**：所有通信通过出站 HTTPS 完成，无需开放防火墙端口 -## 前置条件 +## 8.2 前置条件 | 要求 | 详情 | |------|------| @@ -25,9 +25,9 @@ Remote Control 是 Claude Code 的跨设备会话桥接功能，在 18 款主流 | **工作区信任** | 需在项目目录中至少运行一次 `claude` 以接受工作区信任对话框 | | **Team/Enterprise** | 管理员需在 `claude.ai/admin-settings/claude-code` 中启用 Remote Control 开关 | -## 三种启动方式 +## 8.3 三种启动方式 -### 方式一：Server 模式（专用服务） +### 8.3.1 方式一：Server 模式（专用服务） ```bash claude remote-control @@ -46,7 +46,7 @@ claude remote-control --name "My Project" | `--verbose` | 详细连接/会话日志 | | `--sandbox` / `--no-sandbox` | 启用/禁用文件系统和网络沙箱（默认关闭） | -### 方式二：交互式会话 + Remote Control +### 8.3.2 方式二：交互式会话 + Remote Control ```bash claude --remote-control # 或 --rc @@ -55,7 +55,7 @@ claude --remote-control "My Project" # 带名称 在终端中启动一个完整的交互式会话，同时可通过远程设备操控。可以本地输入，远程客户端也可以同时连接。 -### 方式三：从已有会话启用 +### 8.3.3 方式三：从已有会话启用 ``` /remote-control # 或 /rc @@ -66,7 +66,7 @@ claude --remote-control "My Project" # 带名称 > **命令类型**：`/remote-control` 斜杠命令类型为 `local-jsx`（[命令详解](./02-commands.md)），渲染远程控制配置 UI 并启动到 claude.ai/code 的连接。 -## 从其他设备连接 +## 8.4 从其他设备连接 三种连接方式： @@ -82,15 +82,15 @@ claude --remote-control "My Project" # 带名称 3. 对话历史中最后一条有意义消息的内容 4. 用户发送的第一条 prompt -## 全局默认启用 +## 8.5 全局默认启用 在 Claude Code 中运行 `/config` → 将 **"Enable Remote Control for all sessions"** 设为 `true`。此后每个交互式进程自动注册一个远程会话。如需一个进程中多个并发会话，使用 **Server 模式** 加 `--spawn`。 -## 技术架构 +## 8.6 技术架构 > 以下综合 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)、v2.1.81 二进制反编译（[EVIDENCE.md](./EVIDENCE.md)）、GitHub Issues 社区反馈和 Anthropic 工程博客分析。 -### 三方中继架构 +### 8.6.1 三方中继架构 Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic API 充当消息代理： @@ -124,7 +124,7 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic | **传输安全** | 全程 TLS 加密，与普通 Claude Code 会话相同 | ✅ 官方确认 | | **凭证体系** | 多个短期凭证，每个限定单一用途，独立过期 | ✅ 官方确认 | -#### 三层架构拆分：控制面 / 数据面 / 本地状态面 +#### 8.6.1.1 三层架构拆分：控制面 / 数据面 / 本地状态面 从实现者视角，Remote Control 可拆分为三个职责清晰的子系统： @@ -161,7 +161,7 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic > **设计启示**：三层分离使得**控制面变更不影响消息传输**（如修改 polling 策略无需改消息格式），**本地状态面独立于网络**（进程崩溃后可从 PID 文件和对话历史重建部分状态）。实现者可参考此拆分设计自己的子系统边界。 -### 会话生命周期 +### 8.6.2 会话生命周期 ``` ┌─────────┐ ┌───────────┐ ┌──────────┐ ┌───────────┐ ┌──────────┐ @@ -184,7 +184,7 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic | **空闲/断连** | 网络中断、笔记本睡眠 | 自动尝试重连。若网络断连超过 ~10 分钟，会话超时 | | **过期/退出** | 超时或进程终止 | 清理会话文件。Server 端约 20+ 分钟无活动后关闭连接（观察到 `CLOSE_WAIT` TCP 状态） | -### 会话文件与本地存储 +### 8.6.3 会话文件与本地存储 | 路径 | 内容 | 所属面 | 生命周期 | 可恢复性 | 来源 | |------|------|--------|----------|----------|------| @@ -197,7 +197,7 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic > - `messagingSocketPath` 字段存储在 PID 文件中，表明 Unix socket 路径是**服务端/客户端协商结果**，而非硬编码 > - `bridgeSessionId` 与 `sessionId` 是不同概念：`sessionId` 是本地会话 ID，`bridgeSessionId` 是中继服务器分配的桥接 ID -### `--spawn` 多会话架构 +### 8.6.4 `--spawn` 多会话架构 Server 模式支持通过 `--spawn` 参数管理多个并发远程会话： @@ -212,7 +212,7 @@ Server 模式支持通过 `--spawn` 参数管理多个并发远程会话： > **与 CCR（Claude Code Remote）的区别**：`--spawn` 创建的是**本地多会话**（通过 worktree 隔离），而 `/schedule` 使用的 `RemoteTrigger` 工具创建的是**云端隔离会话**（CCR），在 Anthropic 基础设施上独立运行（[命令详解](./02-commands.md)）。 -### 安全模型纵深 +### 8.6.5 安全模型纵深 Remote Control 的安全架构采用多层防护： @@ -228,7 +228,7 @@ Remote Control 的安全架构采用多层防护： **遥测耦合现象**：设置 `DISABLE_TELEMETRY=1` 后 Remote Control 注册失败（[GitHub #41189](https://github.com/anthropics/claude-code/issues/41189)），表现为 eligibility check 不通过。当前证据不足以确认根因是"资格检查走遥测通道"，标记为**疑似实现耦合**。 -### 相关 API 端点（反编译提取） +### 8.6.6 相关 API 端点（反编译提取） | 端点 | 用途 | 来源 | |------|------|------| @@ -245,7 +245,7 @@ Remote Control 的安全架构采用多层防护： > **注意**：Remote Control 专用的会话注册和消息中继端点 URL 未在 v2.1.87 二进制中明文暴露（可能通过拼接构造或从服务端动态获取）。上述端点为反编译中确认的基础设施端点。 -### 相关环境变量 +### 8.6.7 相关环境变量 前 7 项来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)；其余为 v2.1.87 反编译提取。 @@ -266,7 +266,7 @@ Remote Control 的安全架构采用多层防护： | `CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2` | 值为 `"1"` 时启用 V2 会话入口协议 | v2.1.87 反编译 | | `SSE_PORT` | SSE 本地端口（反编译提取，可能用于 Remote Control 或 MCP SSE 传输） | EVIDENCE.md | -### 实现者 Checklist：设计决策表 +### 8.6.8 实现者 Checklist：设计决策表 > 以下清单提炼自反编译分析和官方文档。每个条目对应实现一个 Remote Control 类功能时**必须做出的设计决策**，Claude Code 的选择作为参考标注。 @@ -281,7 +281,7 @@ Remote Control 的安全架构采用多层防护： | **7** | **并发会话如何隔离？** | `--spawn same-dir`（共享 CWD）或 `--spawn worktree`（独立 Git worktree），`--capacity` 上限 32 | 文件隔离是基本需求；worktree 方案允许并行修改不同分支但增加磁盘占用 | | **8** | **诊断日志写到哪里？** | `--debug-file ` 参数指定调试输出文件；`--verbose` 控制连接/会话日志详细度 | 生产环境中需要可开关的详细日志，用于排查连接循环、凭证刷新失败等问题 | -## Remote Control vs Claude Code on the Web +## 8.7 Remote Control vs Claude Code on the Web 两者经常混淆，但本质不同： @@ -294,7 +294,7 @@ Remote Control 的安全架构采用多层防护： | **启动方式** | `claude remote-control` / `--rc` / `/rc` | `claude --remote "任务描述"` | | **反向操作** | — | `claude --teleport`（拉回 Web 会话到终端） | -### 跨设备工作流全景 +### 8.7.1 跨设备工作流全景 Claude Code 提供了多种跨设备工作方式，各有侧重： @@ -308,7 +308,7 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | **`--remote`** | CLI 推送任务到 Web | Anthropic 云端 | 启动 Web 会话 | | **`/teleport`** | 在 Web 端启动长任务后拉入终端 | 本地机器 | 将云端会话拉到本地继续（CLI 等价：`claude --teleport`） | -## 限制 +## 8.8 限制 | 限制 | 说明 | |------|------| @@ -318,7 +318,7 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | **不支持 API Key** | 必须使用 claude.ai OAuth 认证 | | **不支持第三方提供商** | Bedrock / Vertex / Foundry 用户无法使用 | -## 已知问题（社区反馈） +## 8.9 已知问题（社区反馈） 以下问题来自 GitHub Issues，为社区观察到的现象，**根因未经官方确认**： @@ -333,7 +333,7 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | **Windows MCP 兼容** | Cloud MCP + RC 在 Windows 上加载失败 | Windows 用户无法同时使用 MCP 和 Remote Control | [#41044](https://github.com/anthropics/claude-code/issues/41044) | | **活跃 turn 丢消息** | Agent 正在执行 turn 时，stdin 消息可能丢失 | 远程发送的指令在 agent 忙碌时可能不被处理 | [#41230](https://github.com/anthropics/claude-code/issues/41230) | -## 故障排查 +## 8.10 故障排查 | 错误信息 | 原因与解决 | |----------|-----------| @@ -344,7 +344,7 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | *"Disabled by your organization's policy"* | 三种原因：(1) 使用 API Key → 切换为 claude.ai OAuth；(2) Team/Enterprise 管理员未启用 `claude.ai/admin-settings/claude-code` 的开关；(3) 管理员开关灰色 → 数据保留/合规配置阻止，联系 Anthropic 支持 | | *"Remote credentials fetch failed"* | 使用 `--verbose` 查看详情。常见：未登录、防火墙/代理阻止出站 HTTPS 443 端口、订阅不活跃 | -## 与 `/session` 命令的关系 +## 8.11 与 `/session` 命令的关系 `/session`（别名 `/remote`）是另一个与远程相关的命令，但功能不同于 Remote Control： @@ -356,7 +356,7 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | `/desktop` `/app` | 将当前会话转交到 Claude Desktop 应用继续 | | `/mobile` `/ios` `/android` | 显示下载 Claude Mobile 应用的 QR 码 | -## 行业对比 +## 8.12 行业对比 在 18 款对比的 AI 编程 Agent 中，Remote Control 为 **Claude Code 独有**功能： @@ -370,13 +370,13 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： | **Kimi CLI** | ❌ 无（有 Wire 协议但未实现远程控制） | | **其他 Agent** | ❌ 无 | -## 实现参考：面向 Code Agent 开发者 +## 8.13 实现参考：面向 Code Agent 开发者 > 以下数据来自 v2.1.87 ELF 二进制（SEA，228MB，2026-03-29 构建）中嵌入的 JavaScript 代码反编译提取。变量名经过 minification 处理（如 `Z6H`、`Cl7`、`Ra`），但字符串常量、对象键名、Zod schema 定义保持可读。 > > **适用场景**：其他 Code Agent 开发者实现类似"远程控制"功能时，可将本节作为架构参考。Claude Code 的实现是经过生产验证的方案，但并非唯一可行路径。 -### 内部状态机（Redux Store） +### 8.13.1 内部状态机（Redux Store） Remote Control 在 Redux AppState 中维护 13 个桥接状态字段（反编译提取自 `Z6H` 初始状态对象）： @@ -415,7 +415,7 @@ function migrateBridgeConfig(state) { - `replBridgeOutboundOnly` 为 `true` 时，用户界面显示 "This session is outbound-only. Enable Remote Control locally to allow inbound control." - `replBridgeReconnecting` 用于 UI 展示重连状态（Connecting/Disconnected 循环问题与此状态相关） -### Polling 配置参数（服务端可调） +### 8.13.2 Polling 配置参数（服务端可调） 服务端下发 polling 配置，客户端通过 Zod schema 校验后使用。以下为反编译提取的默认值和校验规则： @@ -456,7 +456,7 @@ loadConfig("tengu_bridge_poll_interval_config", DEFAULT_POLL_CONFIG, 300000); - `reclaim_older_than_ms: 5000` 意味着服务器 5 秒无响应即可判定会话废弃——实现者需注意网络抖动场景 - `session_keepalive_interval_v2_ms` 是 WebSocket 层的 ping/pong，与 HTTP 层的 poll 互补 -### 消息协议（Wire Format） +### 8.13.3 消息协议（Wire Format） Remote Control 使用 JSON-lines 格式进行消息传输。以下消息类型来自反编译提取： @@ -492,7 +492,7 @@ function updateAccessToken(newToken) { } ``` -### Token 刷新系统 +### 8.13.4 Token 刷新系统 反编译提取的 token 刷新参数（`dn$` 函数）： @@ -505,7 +505,7 @@ function updateAccessToken(newToken) { **刷新策略**：基于 JWT expiry 的定时调度——在 token 过期前 5 分钟触发刷新，最多失败 3 次后放弃。 -### Bridge 初始化接口（initReplBridge） +### 8.13.5 Bridge 初始化接口（initReplBridge） 反编译提取的 `initReplBridge` 回调接口，这是 Remote Control 的核心桥接层： @@ -558,7 +558,7 @@ const bridge = await initReplBridge({ } ``` -### Bridge 子进程环境变量 +### 8.13.6 Bridge 子进程环境变量 Server 模式下 `--spawn` 创建的子进程继承以下环境变量（反编译提取）： @@ -580,7 +580,7 @@ Server 模式下 `--spawn` 创建的子进程继承以下环境变量（反编 - `CLAUDE_CODE_ENVIRONMENT_KIND: "bridge"` 让子进程知道自己在桥接模式下运行，调整行为（如不启动自己的 polling） - `CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2: "1"` 启用更新的会话入口协议 -### 并发会话管理（PID File） +### 8.13.7 并发会话管理（PID File） 反编译提取的会话注册文件格式和更新逻辑： @@ -618,7 +618,7 @@ async function updatePidFile(updates) { **已知问题**：此 read-modify-write 操作**非原子**（缺少 tmp+rename），在并发场景下可能导致 JSON 文件损坏（[GitHub #41195](https://github.com/anthropics/claude-code/issues/41195)）。实现者应使用 `writeFileSync(tmp, data)` + `renameSync(tmp, path)` 的原子写入模式。 -### Bridge 会话注册 Schema +### 8.13.8 Bridge 会话注册 Schema 反编译提取的 Zod schema（`pN9`），用于注册桥接会话： @@ -631,7 +631,7 @@ const bridgeSessionSchema = z.object({ }); ``` -### CLI 完整参数（remote-control 子命令） +### 8.13.9 CLI 完整参数（remote-control 子命令） 反编译提取的 `claude remote-control` 完整参数列表： @@ -660,7 +660,7 @@ claude remote-control [options] | `--session-timeout-ms` | 未提及 | 精确控制会话超时时间 | | `--debug-file` | 未提及 | 调试输出到文件 | -### 遥测事件 +### 8.13.10 遥测事件 Remote Control 相关的遥测事件前缀为 `tengu_bridge_*`，反编译提取到以下事件名： @@ -671,7 +671,7 @@ Remote Control 相关的遥测事件前缀为 `tengu_bridge_*`，反编译提取 | `tengu_bridge_poll_interval_config` | Polling 配置加载追踪 | | `tengu_concurrent_sessions` | 并发会话状态追踪 | -### 客户端类型检测 +### 8.13.11 客户端类型检测 反编译提取的客户端类型判定逻辑： @@ -696,7 +696,7 @@ function detectClientType() { | `CLAUDE_CODE_ENTRYPOINT` | 值为 `"remote"` 时标记为远程入口 | 反编译 | | `CLAUDE_CODE_REMOTE` | 存在时影响 auto-memory 行为；传递给 teammate spawn 环境 | 反编译 | -### 实现建议：架构模式总结 +### 8.13.12 实现建议：架构模式总结 基于以上反编译分析，实现类似 Remote Control 功能的推荐架构模式： @@ -736,7 +736,7 @@ function detectClientType() { └──────────────────────────────────────────────────────────────────┘ ``` -### 与 Gemini CLI 的对比参考 +### 8.13.13 与 Gemini CLI 的对比参考 Qwen Code 基于 Gemini CLI 分叉（[Qwen Code EVIDENCE](../qwen-code/EVIDENCE.md)），Gemini CLI 使用 Google Cloud relay 实现 `--remote` 功能。两者实现路径对比： @@ -752,9 +752,9 @@ Qwen Code 基于 Gemini CLI 分叉（[Qwen Code EVIDENCE](../qwen-code/EVIDENCE. > **注意**：Gemini CLI 的 `--remote` 实现细节未公开源码，对比数据来自 CLI help 输出和行为观察，标注 `⚠️` 的条目为推断。 -## 评价与优缺点分析 +## 8.14 评价与优缺点分析 -### 核心优势 +### 8.14.1 核心优势 **1. 唯一实现"终端会话远程操控"的 Agent** @@ -775,7 +775,7 @@ Claude Code 的 Remote Control 在所有 18 款 Agent 中独树一帜——它 Remote Control 不是孤立功能，而是 Claude Code 跨设备矩阵的一部分——配合 `--remote`（推到 Web）、`/teleport`（拉回终端）、Dispatch（手机委派）、Channels（Telegram/Discord 推送）、`/schedule`（定时任务），形成从"实时远程操控"到"异步事件驱动"的完整工作流覆盖。 -### 核心短板 +### 8.14.2 核心短板 **1. 强绑定 claude.ai 生态** @@ -801,7 +801,7 @@ Remote Control 不是孤立功能，而是 Claude Code 跨设备矩阵的一部 通信协议细节（polling 间隔、消息格式、端点 URL）未公开，二进制反编译也未完整暴露 Remote Control 专用端点。安全审计只能基于官方文档描述，无法独立验证实现。 -### 设计权衡总结 +### 8.14.3 设计权衡总结 | 设计决策 | 收益 | 代价 | |----------|------|------| @@ -811,11 +811,11 @@ Remote Control 不是孤立功能，而是 Claude Code 跨设备矩阵的一部 | 多短期凭证 | 凭证泄露影响面小 | 增加注册失败点 | | 遥测与资格检查耦合 | — | 会导致隐私用户被意外阻断 | -## 竞品对比：远程访问能力全景 +## 8.15 竞品对比：远程访问能力全景 Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有，但"远程访问"本身在其他 Agent 中有不同形态的实现： -### 功能对比矩阵 +### 8.15.1 功能对比矩阵 > **维度说明**：本表统一按「是否具备该能力」横向对比。各能力定义如下—— > - **终端会话远程操控**：从其他设备实时操控一个正在运行的 CLI 会话 @@ -834,7 +834,7 @@ Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有 | **远程 IDE 集成** | ✅ VS Code | ✅ ACP | ❌ | ❌ | ✅ app-server | ✅ 原生 | ❌ | | **协议** | HTTPS polling + 中继 | Wire v1.6 (WS) | Hono HTTP+WS+SSE | REST (Axum) | JSON-RPC (WS) | CLI only | CLI only | -### 竞品关键差异 +### 8.15.2 竞品关键差异 **Kimi CLI**（最完整的 Web UI）： - `kimi web` 启动 FastAPI + React Web UI（默认 `localhost:5494`），支持多会话管理、实时 diff 预览、审批对话框 @@ -861,7 +861,7 @@ Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有 （来源：[Codex CLI 命令文档](../codex-cli/02-commands.md)、[EVIDENCE](../codex-cli/EVIDENCE.md)） - **劣势**：面向 IDE 插件设计，非通用远程访问 -### 为什么没有其他 Agent 复制 Remote Control？（作者分析，非源码验证结论） +### 8.15.3 为什么没有其他 Agent 复制 Remote Control？（作者分析，非源码验证结论） > ⚠️ 以下为基于公开信息的分析推测，未经源码或官方声明验证。 From 0d9d5d63ab35f467c245786c7abcc0f41c919dc9 Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 19:48:48 +0800 Subject: [PATCH 11/15] docs: rewrite Remote Control architecture with source code evidence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Major corrections from source code analysis (bridge/ 12,613 LOC): - Fix: transport is WebSocket (v1) / SSE+POST (v2), NOT 'HTTPS polling' - Add: dual-generation transport architecture (HybridTransport vs SSETransport+CCRClient) - Add: 21 control_request subtypes from entrypoints/sdk/controlSchemas.ts - Add: 3-tier session ingress auth chain (env var -> FD -> well-known file) - Add: bridge pointer crash recovery, sleep detection, echo dedup - Add: session tracking (9 Map/Set data structures in bridgeMain.ts) - Add: optimistic concurrency for session ingress (Last-Uuid + 409 recovery) - Add: iOS camelCase compatibility shim (normalizeControlMessageKeys) - Update: evidence sources from 'v2.1.87 反编译' to '源码: ' - Fix: 02-commands.md remote-control description Co-authored-by: Qwen-Coder --- docs/tools/claude-code/02-commands.md | 2 +- docs/tools/claude-code/08-remote-control.md | 322 +++++++++++--------- 2 files changed, 181 insertions(+), 143 deletions(-) diff --git a/docs/tools/claude-code/02-commands.md b/docs/tools/claude-code/02-commands.md index a475cec4..2bf34996 100644 --- a/docs/tools/claude-code/02-commands.md +++ b/docs/tools/claude-code/02-commands.md @@ -924,7 +924,7 @@ Found 3 issues: **实现细节：** - 渲染远程控制配置 UI -- 向 Anthropic API 注册并轮询获取工作（outbound HTTPS polling） +- 向 Anthropic API 注册会话（WebSocket/SSE 双向通信） - 允许在浏览器中操作终端会话 - 支持跨设备远程操作 diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index bb1d4062..1d0a045d 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -2,7 +2,7 @@ > Remote Control 允许从手机、平板或任意浏览器远程操控本地运行的 Claude Code 终端会话。会话**始终在本地执行**，远程端仅作为交互窗口。 > -> **数据来源**：CLI 子命令/参数（`claude remote-control`、`--remote-control`/`--rc`、`--spawn`、`--capacity`）和故障排查指南来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)（2026-03）；`/remote-control` 斜杠命令类型来自 v2.1.81 二进制反编译；环境变量名来自 [EVIDENCE.md](./EVIDENCE.md) 反编译提取。 +> **数据来源**：CLI 子命令/参数和故障排查指南来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)（2026-03）；`/remote-control` 斜杠命令类型来自 v2.1.81 二进制反编译；环境变量名来自 [EVIDENCE.md](./EVIDENCE.md) 反编译提取；**技术架构细节来自源码分析**（`bridge/`、`remote/`、`utils/`、`entrypoints/` 等目录，约 35,000 行 TypeScript）。 ## 8.1 概述 @@ -88,20 +88,22 @@ claude --remote-control "My Project" # 带名称 ## 8.6 技术架构 -> 以下综合 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)、v2.1.81 二进制反编译（[EVIDENCE.md](./EVIDENCE.md)）、GitHub Issues 社区反馈和 Anthropic 工程博客分析。 +> 以下综合 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)、源码分析（`bridge/` 目录 12,613 行 + `remote/` 目录 1,127 行 + `utils/` 和 `entrypoints/` 相关约 21,000 行）、GitHub Issues 社区反馈和 Anthropic 工程博客。 ### 8.6.1 三方中继架构 Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic API 充当消息代理： ``` -┌──────────────┐ ① 出站 HTTPS (polling) ┌───────────────────────┐ -│ 本地终端 │ ────────────────────────────→ │ Anthropic API │ -│ (Claude Code)│ ←──────────────────────────── │ (消息中继/代理) │ -│ │ ② 流式响应 (streaming) │ │ -└──────────────┘ │ claude.ai/code │ - │ 会话注册 + 消息路由 │ - └───────────┬───────────┘ +┌──────────────┐ ┌───────────────────────┐ +│ 本地终端 │ ① 注册会话 (POST /v1/...) │ Anthropic API │ +│ (Claude Code)│ ──────────────────────────→ │ (消息中继/代理) │ +│ │ 获取 JWT + 会话凭证 │ │ +│ │ │ claude.ai/code │ +│ │ ② WebSocket (v1) / SSE (v2) │ 会话注册 + 消息路由 │ +│ │ ←────────────────────────────→ │ │ +│ │ 双向消息传输 │ │ +└──────────────┘ └───────────┬───────────┘ │ ③ WebSocket/HTTPS │ │ @@ -111,55 +113,76 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic └───────────────────────┘ ``` -**数据流**（官方确认部分）： -1. **本地 → Anthropic API**：本地进程启动时用 full-scope OAuth token 注册会话，随后以 polling 方式持续获取待处理消息 ✅ 官方确认 -2. **Anthropic API → 本地**：服务器有消息时通过 streaming connection 下发 ✅ 官方确认 -3. **Anthropic API ↔ 浏览器/手机**：远程客户端连接到 Anthropic 基础设施（具体传输协议未公开确认） ⚠️ 社区观察到 stale WebSocket 连接行为 +**双代传输架构**（源码确认）： + +源码揭示 Claude Code 内部实现了两代传输协议，服务端按会话动态选择： + +| 维度 | v1（HybridTransport） | v2（SSETransport + CCRClient） | +|------|----------------------|-------------------------------| +| **读取通道** | WebSocket 接收消息 | SSE（Server-Sent Events）接收消息 | +| **写入通道** | POST 到 Session-Ingress 端点 | POST 到 CCR `/worker/*` 端点 | +| **认证方式** | OAuth token | JWT（含 `session_id` + `worker` role） | +| **选择条件** | 默认 | 服务端通过 `secret.use_code_sessions` 标志切换；`CLAUDE_BRIDGE_USE_CCR_V2` 环境变量可强制启用 | +| **来源** | `bridge/replBridge.ts` | `bridge/remoteBridgeCore.ts` | + +**数据流**： + +| 阶段 | v1 流程 | v2 流程 | 确认度 | +|------|---------|---------|--------| +| **注册** | `registerBridgeEnvironment()` → `environment_id` + `environment_secret` | `createCodeSession()` → `sessionId` → `fetchRemoteCredentials()` → JWT | ✅ 源码确认 | +| **连接** | WebSocket 长连接 + POST 写入 | SSE 长连接 + POST 写入 | ✅ 源码确认 | +| **认证刷新** | OAuth token 刷新后通过 `refreshHeaders` 回调注入 | JWT 过期前 5 分钟通过 `/bridge` 端点刷新，bump epoch | ✅ 源码确认 | +| **断线重连** | 指数退避（2s → 60s，15 分钟放弃），重连-in-place 或新建会话 | SSE 401 触发 OAuth 刷新 + 凭证重取 | ✅ 源码确认 | +| **心跳** | `keep_alive` 消息（默认 120 秒间隔） | `heartbeatIntervalMs` + `heartbeatJitterFraction` | ✅ 源码确认 | | 方面 | 细节 | 确认度 | |------|------|--------| -| **本地→服务器** | 出站 HTTPS polling。本地不开放入站端口 | ✅ 官方确认 | -| **远程客户端→服务器** | 推测为 WebSocket 或 HTTPS 长连接（`WEBSOCKET_AUTH_*` 变量名暗示 WebSocket 使用） | ⚠️ 推断 | +| **本地→服务器** | 出站 WebSocket/SSE，本地不开放入站端口 | ✅ 源码确认 | +| **远程客户端→服务器** | 浏览器/App 连接到 claude.ai 基础设施（WebSocket） | ✅ 源码确认 | | **消息路由** | Anthropic 服务器在远程客户端和本地会话之间双向中继 | ✅ 官方确认 | | **传输安全** | 全程 TLS 加密，与普通 Claude Code 会话相同 | ✅ 官方确认 | -| **凭证体系** | 多个短期凭证，每个限定单一用途，独立过期 | ✅ 官方确认 | +| **凭证体系** | 多个短期凭证（JWT + OAuth），每个限定单一用途，独立过期 | ✅ 源码确认 | #### 8.6.1.1 三层架构拆分：控制面 / 数据面 / 本地状态面 -从实现者视角，Remote Control 可拆分为三个职责清晰的子系统： +从实现者视角，Remote Control 可拆分为三个职责清晰的子系统（源码中对应 `ReplBridgeHandle` 统一接口，`BridgeCoreParams` 依赖注入）： **控制面（Control Plane）**——会话注册、资格检查、凭证管理、策略执行： | 组件 | 职责 | 证据来源 | |------|------|----------| -| 会话注册 | 用 full-scope OAuth token 向中继服务器注册会话，获取 `SESSION_ACCESS_TOKEN` | 官方文档 + 反编译 | +| 会话注册 | v1: `registerBridgeEnvironment()` → `environment_id` + `environment_secret`；v2: `createCodeSession()` → JWT | 源码: `bridge/replBridge.ts` | | 资格检查 | `admin_requests/eligibility` 端点判定用户是否可使用 RC（受订阅类型、管理员策略、组织策略影响） | v2.1.87 反编译 | -| 凭证刷新 | JWT expiry 驱动的定时刷新（过期前 5 分钟触发，最多失败 3 次） | v2.1.87 反编译 | +| 凭证刷新 | v1: OAuth 刷新 → `refreshHeaders` 回调；v2: JWT 过期前 5 分钟调用 `/bridge` 端点，bump epoch 防双刷 | 源码: `bridge/remoteBridgeCore.ts` | | 策略执行 | `policy_limits` 端点查询组织级 RC 开关；Team/Enterprise 管理员门控 | EVIDENCE.md | -| 配置下发 | `tengu_bridge_poll_interval_config` 动态下发 polling 参数（TTL 5 分钟） | v2.1.87 反编译 | -| PID 文件管理 | `~/.claude/sessions/{pid}.json` 跟踪并发会话 | v2.1.87 反编译 | +| 配置下发 | GrowthBook 特性门控（`tengu_bridge_poll_interval_config`、`tengu_bridge_initial_history_cap` 等）动态调整运行参数 | 源码: `bridge/bridgeMain.ts` | +| PID 文件管理 | `~/.claude/sessions/{pid}.json` 跟踪并发会话，含 `kind`（interactive/bg/daemon/daemon-worker）和 `status`（busy/idle/waiting） | 源码: `utils/concurrentSessions.ts` | **数据面（Data Plane）**——消息传输、双向同步、流式响应： | 组件 | 职责 | 证据来源 | |------|------|----------| -| 出站轮询 | 2s（未满容量）或 10min（满容量）HTTPS poll 获取待处理消息 | 官方文档 + 反编译 | -| 流式响应 | 服务端通过 streaming connection 下发 agent 输出到远程客户端 | 官方文档 | -| 消息协议 | JSON-lines 格式，8+ 消息类型（`user`/`assistant`/`control_request`/`keep_alive` 等） | v2.1.87 反编译 | -| 本地 IPC | Unix domain socket (`/tmp/cc-socks/*.sock`) 用于进程内消息传递 | GitHub Issues | -| 对话持久化 | `~/.claude/projects//*.jsonl` 存储完整对话流 | EVIDENCE.md | -| WebSocket ping/pong | `session_keepalive_interval_v2_ms: 120000`（2 分钟）维持连接活性 | v2.1.87 反编译 | +| v1 传输 | WebSocket 读取 + POST 写入 Session-Ingress；指数退避重连（2s→60s，15 分钟放弃） | 源码: `bridge/replBridge.ts` | +| v2 传输 | SSE 读取 + POST 写入 CCR `/worker/*`；JWT 认证 + 自动刷新 | 源码: `bridge/remoteBridgeCore.ts` | +| 消息协议 | JSON-lines 格式，21 种 `control_request` 子类型 + 标准 SDK 消息 | 源码: `entrypoints/sdk/controlSchemas.ts` | +| 历史刷新 | `initialHistoryCap`（默认 200 条，GrowthBook 可调）限制初始历史推送；FlushGate 防止历史消息与实时消息交错 | 源码: `bridge/replBridge.ts` | +| Echo 去重 | 双层 UUID 保护：`initialMessageUUIDs` + `recentPostedUUIDs`（2000 条环形缓冲），防止消息回声 | 源码: `bridge/replBridge.ts` | +| 对话持久化 | Session-Ingress API + 乐观并发写入（`Last-Uuid` header + 409 Conflict 自动恢复） | 源码: `services/api/sessionIngress.ts` | +| WebSocket 心跳 | `keep_alive` 消息，默认 120 秒间隔（`session_keepalive_interval_v2_ms`） | 源码: `bridge/replBridge.ts` | **本地状态面（Local State Plane）**——Redux 状态机、环境变量、运行时状态： | 组件 | 职责 | 证据来源 | |------|------|----------| -| Redux 状态机 | 13 个 `replBridge*` 字段管理桥接生命周期（enabled/connected/active/reconnecting 等） | v2.1.87 反编译 | -| 客户端类型检测 | `CLAUDE_CODE_SESSION_ACCESS_TOKEN` / `WEBSOCKET_AUTH_FILE_DESCRIPTOR` / `ENTRYPOINT` 判定客户端类型 | v2.1.87 反编译 | -| 环境变量配置 | 14+ 环境变量控制 RC 行为（认证模式、网络代理、沙箱、远程环境等） | 官方文档 + 反编译 | -| initReplBridge | 核心桥接层，通过 7 个回调函数连接远程端和本地会话 | v2.1.87 反编译 | +| Redux 状态机 | 13 个 `replBridge*` 字段管理桥接生命周期（enabled/connected/active/reconnecting 等） | 源码: `bridge/replBridge.ts` | +| 客户端类型检测 | 3 层 token 优先级链：env var → FD → well-known file | 源码: `utils/sessionIngressAuth.ts` | +| 环境变量配置 | 14+ 环境变量控制 RC 行为（认证模式、网络代理、沙箱、远程环境等） | 官方文档 + 源码 | +| initReplBridge | 核心桥接层，通过 `BridgeCoreParams` 依赖注入 7 个回调函数 | 源码: `bridge/initReplBridge.ts` | +| 崩溃恢复 | Bridge pointer 文件（`{sessionId, environmentId, source}`），进程 crash 后下次启动可恢复 | 源码: `bridge/replBridge.ts` | +| 睡眠检测 | `setTimeout` 超时阈值 60+ 秒 → 判定系统睡眠 → 重置错误预算 | 源码: `bridge/replBridge.ts` | +| 会话活动追踪 | refcount 心跳计时器（30 秒间隔），区分 `api_call` / `tool_exec` 活动 | 源码: `utils/sessionActivity.ts` | -> **设计启示**：三层分离使得**控制面变更不影响消息传输**（如修改 polling 策略无需改消息格式），**本地状态面独立于网络**（进程崩溃后可从 PID 文件和对话历史重建部分状态）。实现者可参考此拆分设计自己的子系统边界。 +> **设计启示**：三层分离使得**控制面变更不影响消息传输**（如修改传输策略无需改消息格式），**本地状态面独立于网络**（进程崩溃后可从 pointer 文件和对话历史重建部分状态）。源码中 `BridgeCoreParams` 使用依赖注入，所有核心逻辑不直接 import `bootstrap/state` 或 `sessionStorage`，实现了模块间零耦合。 ### 8.6.2 会话生命周期 @@ -169,26 +192,29 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic │Register │ │ Waiting │ │ Active │ │ Idle │ │ Expired │ └─────────┘ └───────────┘ └──────────┘ └───────────┘ └──────────┘ - OAuth认证 - 显示URL/QR - 双向消息同步 - 自动重连尝试 - 进程退出 - - API注册 - 轮询等待客户端 - 工具调用可远程审批 - ~10min网络断连 - 清理会话文件 - - Server模式可 后超时 - 接受多个客户端 + - API注册 - 等待客户端 - 工具调用可远程审批 - WS/SSE 断连 - 清理会话文件 + - Server模式可 - keep_alive心跳 - 睡眠检测恢复 - 归档会话 + 接受多个客户端 - 重连-in-place或 + 新建会话 ``` +**源码中的会话状态**（`server/types.ts`）：`'starting' | 'running' | 'detached' | 'stopping' | 'stopped'` + **各阶段详情**： | 阶段 | 触发 | 行为 | |------|------|------| | **注册** | 启动 `claude remote-control` 或 `/rc` | 使用 full-scope OAuth token 向 Anthropic API 注册会话，获取 `SESSION_ACCESS_TOKEN` | -| **等待连接** | 注册成功后 | 终端显示会话 URL 和 QR 码。本地进程持续 polling 等待远程客户端 | -| **活跃** | 远程客户端连接 | 双向消息同步：远程发送的指令路由到本地执行，本地输出实时推送到远程 | -| **空闲/断连** | 网络中断、笔记本睡眠 | 自动尝试重连。若网络断连超过 ~10 分钟，会话超时 | -| **过期/退出** | 超时或进程终止 | 清理会话文件。Server 端约 20+ 分钟无活动后关闭连接（观察到 `CLOSE_WAIT` TCP 状态） | +| **等待连接** | 注册成功后 | 终端显示会话 URL 和 QR 码。本地进程等待远程客户端连接（v1 通过 polling 等待工作分配；v2 通过 SSE 等待） | +| **活跃** | 远程客户端连接 | 双向消息同步：远程发送的指令路由到本地执行，本地输出实时推送到远程。权限请求通过 `control_request`（`can_use_tool` 子类型）桥接到远程审批 | 源码确认 | +| **空闲/断连** | 网络中断、笔记本睡眠 | 自动尝试重连（指数退避，2s→60s）。**睡眠检测**：`setTimeout` 超时 60+ 秒判定系统睡眠，重置错误预算。v1 策略：重连-in-place（`reuseEnvironmentId`）或新建会话；v2 策略：SSE 401 触发 OAuth 刷新 + 凭证重取 | 源码确认 | +| **过期/退出** | 超时或进程终止 | v1: `stopWork()` + `archiveSession()` + 清理 PID 文件；v2: transport 关闭 + archive。Perpetual 模式下不发送 result，让后端 TTL（300s）到期后重新排队 | 源码确认 | ### 8.6.3 会话文件与本地存储 | 路径 | 内容 | 所属面 | 生命周期 | 可恢复性 | 来源 | |------|------|--------|----------|----------|------| -| `~/.claude/sessions/{pid}.json` | 会话元数据：`pid`、`sessionId`、`cwd`、`startedAt`、`kind`、`entrypoint`、`name`、`status`、`updatedAt`、`bridgeSessionId`、`messagingSocketPath` | 控制面 + 本地状态面 | 每个 interactive process 一个文件；进程退出后残留但无意义 | ⚠️ 推断：进程退出后文件残留，但 `reclaim_older_than_ms: 5000` 意味着服务端 5 秒后即视为废弃。**进程重启不会自动恢复** | GitHub Issues + v2.1.87 反编译 | +| `~/.claude/sessions/{pid}.json` | 会话元数据：`pid`、`sessionId`、`cwd`、`startedAt`、`kind`（interactive/bg/daemon/daemon-worker）、`entrypoint`、`name`、`status`（busy/idle/waiting）、`logPath`、`agent`、`messagingSocketPath`、`bridgeSessionId` | 控制面 + 本地状态面 | 每个 interactive process 一个文件；进程退出后残留但无意义 | 进程退出后文件残留。`countConcurrentSessions()` 会清理 stale PID 文件（WSL 除外）。**进程重启不会自动恢复** | 源码: `utils/concurrentSessions.ts` | | `/tmp/cc-socks/*.sock` | Unix domain socket，用于本地进程间消息传递（如 UI bridge、多客户端复用） | 数据面（本地 IPC） | 随进程创建/销毁；进程退出即失效 | ❌ 不可恢复：Unix socket 文件随进程退出失效，重新连接需建立新 socket | GitHub Issues | | `~/.claude/projects//` | 会话对话历史（`.jsonl` 格式），包含完整对话流；`cleanupPeriodDays`（默认 30 天）后自动清理 | 数据面（持久化） | 独立于 Remote Control 生命周期；与普通会话共享存储 | ✅ 可恢复：对话历史在磁盘上持久化，可用于 `/continue` 或 `/teleport` 恢复上下文 | [EVIDENCE.md](./EVIDENCE.md) | @@ -196,6 +222,8 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic > - PID 文件命名（`{pid}.json`）意味着**每个 OS 进程一个远程会话**，而非每个 bridge session 一个 state file。Server 模式 `--spawn` 创建的子进程各自有独立的 PID 文件 > - `messagingSocketPath` 字段存储在 PID 文件中，表明 Unix socket 路径是**服务端/客户端协商结果**，而非硬编码 > - `bridgeSessionId` 与 `sessionId` 是不同概念：`sessionId` 是本地会话 ID，`bridgeSessionId` 是中继服务器分配的桥接 ID +> - 源码中 `registerCleanup` 确保进程退出时 unlink PID 文件；文件名严格校验 `/^\d+\.json$/` 防止误删非 PID 文件 +> - **Bridge pointer 文件**（`bridge/bridgeMain.ts`）独立于 PID 文件，用于崩溃恢复：包含 `{sessionId, environmentId, source}`，mtime 每小时刷新 ### 8.6.4 `--spawn` 多会话架构 @@ -208,7 +236,21 @@ Server 模式支持通过 `--spawn` 参数管理多个并发远程会话： **运行时切换**：在 Server 模式中按 `w` 键可动态切换 spawn 模式。 -**容量控制**：`--capacity ` 限制最大并发会话数（默认 32），防止资源耗尽。 +**容量控制**：`--capacity ` 限制最大并发会话数（默认 32），防止资源耗尽。`capacityWake` 信号在会话完成时中断 at-capacity 睡眠，立即接受新工作。 + +**会话跟踪**（源码: `bridge/bridgeMain.ts`）：运行时维护 9 个 Map/Set 数据结构： + +| 数据结构 | 用途 | +|----------|------| +| `activeSessions: Map` | 活跃会话句柄 | +| `sessionStartTimes: Map` | 会话启动时间 | +| `sessionWorkIds: Map` | 会话→工作项映射 | +| `sessionIngressTokens: Map` | 会话→Ingress token | +| `sessionTimers: Map` | 会话超时定时器 | +| `completedWorkIds: Set` | 已完成工作项（防重复） | +| `sessionWorktrees: Map` | worktree 隔离信息 | +| `timedOutSessions: Set` | 超时会话 | +| `v2Sessions: Set` | v2 传输会话 | > **与 CCR（Claude Code Remote）的区别**：`--spawn` 创建的是**本地多会话**（通过 worktree 隔离），而 `/schedule` 使用的 `RemoteTrigger` 工具创建的是**云端隔离会话**（CCR），在 Anthropic 基础设施上独立运行（[命令详解](./02-commands.md)）。 @@ -220,15 +262,18 @@ Remote Control 的安全架构采用多层防护： |------|------|------| | **1. 认证门槛** | claude.ai OAuth full-scope token | API Key、`setup-token`、Bedrock/Vertex/Foundry 均被拒绝 | | **2. 管理员门控** | `claude.ai/admin-settings/claude-code` 开关 | Team/Enterprise 默认关闭；合规配置可阻止启用 | -| **3. 凭证隔离** | 多短期凭证、单用途作用域、独立过期 | 防止凭证泄露后横向移动 | -| **4. 网络隔离** | 仅出站 HTTPS，零入站端口 | 显著降低网络暴露面（本地 IPC、会话文件、OAuth flow 仍属攻击面） | +| **3. 凭证隔离** | v1: OAuth + environment_secret；v2: JWT（`session_id` + `worker` role），多短期凭证、单用途作用域 | 源码: `bridge/replBridge.ts`、`bridge/remoteBridgeCore.ts` | +| **4. 网络隔离** | 仅出站 WebSocket/SSE + POST，零入站端口 | 显著降低网络暴露面 | | **5. 传输加密** | 全程 TLS | 与普通 Claude Code 会话相同 | | **6. 可选沙箱** | `--sandbox` 启用文件系统+网络隔离 | 默认关闭，Server 模式可启用 | -| **7. 安全分类器** | auto mode 双层防御（服务端 probe + 客户端分类器） | [工程博客](https://anthropic.com/engineering/claude-code-auto-mode)，Sonnet 4.6 驱动 | +| **7. 权限桥接** | `can_use_tool` control_request 通过中继转发到远程客户端审批，响应经 `control_response` 返回 | 源码: `bridge/bridgeMessaging.ts` | +| **8. 会话 Ingress 认证** | 3 层 token 优先级链：env var → FD → well-known file；session key 用 Cookie，JWT 用 Bearer | 源码: `utils/sessionIngressAuth.ts` | +| **9. Echo 去重** | 双层 UUID 保护（`initialMessageUUIDs` + 2000 条环形缓冲），防止消息回声 | 源码: `bridge/replBridge.ts` | +| **10. 安全分类器** | auto mode 双层防御（服务端 probe + 客户端分类器） | [工程博客](https://anthropic.com/engineering/claude-code-auto-mode)，Sonnet 4.6 驱动 | **遥测耦合现象**：设置 `DISABLE_TELEMETRY=1` 后 Remote Control 注册失败（[GitHub #41189](https://github.com/anthropics/claude-code/issues/41189)），表现为 eligibility check 不通过。当前证据不足以确认根因是"资格检查走遥测通道"，标记为**疑似实现耦合**。 -### 8.6.6 相关 API 端点（反编译提取） +### 8.6.6 相关 API 端点 | 端点 | 用途 | 来源 | |------|------|------| @@ -237,6 +282,12 @@ Remote Control 的安全架构采用多层防护： | `claude.ai/api/oauth/authorize` | OAuth 认证（RC 注册需 full-scope token） | [EVIDENCE.md](./EVIDENCE.md) | | `api.anthropic.com/api/claude_code/metrics` | 遥测上报（资格检查依赖此通道） | [EVIDENCE.md](./EVIDENCE.md) | | `claude.ai/api/ws/speech_to_text/voice_stream` | 语音转文字（共用 WebSocket 基础设施） | [EVIDENCE.md](./EVIDENCE.md) | +| `POST /v1/sessions` | CCR v2 会话创建（含 `anthropic-beta: ccr-byoc-2025-07-29` header） | 源码: `utils/teleport.tsx` | +| `POST /v1/session_ingress/session/{id}` | 对话日志追加写入（`Last-Uuid` 乐观并发控制） | 源码: `services/api/sessionIngress.ts` | +| `GET /v1/session_ingress/session/{id}` | 对话日志读取 | 源码: `services/api/sessionIngress.ts` | +| `GET /v1/sessions/{id}/events` | CCR v2 事件流（游标分页，1000 条/页，最多 100 页） | 源码: `utils/teleport.tsx` | +| `POST /v1/sessions/{id}/archive` | 归档远程会话（409 = 已归档，视为成功） | 源码: `utils/teleport.tsx` | +| `GET /v1/sessions/{id}/teleport-events` | Teleport 事件流（Spanner v2 / threadstore 回退） | 源码: `services/api/sessionIngress.ts` | | `api.anthropic.com/admin_requests/eligibility` | 资格检查端点（RC 启用前的资格判定） | v2.1.87 反编译 | | `api.anthropic.com/api/claude_code_grove` | Grove 端点（用途待确认） | v2.1.87 反编译 | | `api.anthropic.com/api/claude_code_penguin_mode` | 快速模式端点 | v2.1.87 反编译 | @@ -372,13 +423,13 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： ## 8.13 实现参考：面向 Code Agent 开发者 -> 以下数据来自 v2.1.87 ELF 二进制（SEA，228MB，2026-03-29 构建）中嵌入的 JavaScript 代码反编译提取。变量名经过 minification 处理（如 `Z6H`、`Cl7`、`Ra`），但字符串常量、对象键名、Zod schema 定义保持可读。 +> 以下数据来自源码分析（`bridge/`、`remote/`、`utils/`、`entrypoints/` 等目录，约 35,000 行 TypeScript）及 v2.1.87 ELF 二进制反编译交叉验证。源码文件名和行号可直接追溯。 > > **适用场景**：其他 Code Agent 开发者实现类似"远程控制"功能时，可将本节作为架构参考。Claude Code 的实现是经过生产验证的方案，但并非唯一可行路径。 ### 8.13.1 内部状态机（Redux Store） -Remote Control 在 Redux AppState 中维护 13 个桥接状态字段（反编译提取自 `Z6H` 初始状态对象）： +Remote Control 在 Redux AppState 中维护 13 个桥接状态字段（源码: `bridge/replBridge.ts`）： ```javascript // v2.1.87 二进制反编译：AppState 初始状态 @@ -415,7 +466,7 @@ function migrateBridgeConfig(state) { - `replBridgeOutboundOnly` 为 `true` 时，用户界面显示 "This session is outbound-only. Enable Remote Control locally to allow inbound control." - `replBridgeReconnecting` 用于 UI 展示重连状态（Connecting/Disconnected 循环问题与此状态相关） -### 8.13.2 Polling 配置参数（服务端可调） +### 8.13.2 Polling 配置参数（服务端可调 / GrowthBook 动态下发） 服务端下发 polling 配置，客户端通过 Zod schema 校验后使用。以下为反编译提取的默认值和校验规则： @@ -458,109 +509,96 @@ loadConfig("tengu_bridge_poll_interval_config", DEFAULT_POLL_CONFIG, 300000); ### 8.13.3 消息协议（Wire Format） -Remote Control 使用 JSON-lines 格式进行消息传输。以下消息类型来自反编译提取： - -| 消息类型 | 方向 | 用途 | Zod Schema | -|----------|------|------|------------| -| `user` | 远程→本地 | 用户输入消息 | `y.object({type: "user", content: [...]})` | -| `assistant` | 本地→远程 | Agent 响应 | — | -| `system` | 本地→远程 | 系统消息 | — | -| `control_request` | 远程→本地 | 权限/模式/模型变更请求 | — | -| `control_response` | 本地→远程 | 对 control_request 的响应 | — | -| `control_cancel_request` | 本地→远程 | 取消未决的 control_request | — | -| `keep_alive` | 双向 | 心跳保活（收到时跳过处理） | `y.object({type: y.literal("keep_alive")})` | -| `update_environment_variables` | 本地→本地 | 运行时环境变量更新（如 token 刷新） | — | -| `bridge_state` | 双向 | 桥接状态变更通知 | — | +Remote Control 使用 JSON-lines 格式进行消息传输。以下消息类型来自源码（`entrypoints/sdk/controlSchemas.ts`，约 510 行 Zod v4 schema 定义）： + +**消息信封**（Envelope）： + +| Schema | `type` 字段 | 用途 | +|--------|------------|------| +| `SDKControlRequestSchema` | `control_request` | 从远程端发来的控制请求，含 `request_id` + `request` 内含 `subtype` | +| `SDKControlResponseSchema` | `control_response` | 控制请求的响应，含 `subtype`（`success`/`error`）+ 对应数据 | +| `SDKControlCancelRequestSchema` | `control_cancel_request` | 取消待处理的控制请求 | +| `SDKKeepAliveMessageSchema` | `keep_alive` | 心跳保活 | +| `SDKUpdateEnvironmentVariablesMessageSchema` | `update_environment_variables` | 父进程向子进程注入环境变量更新 | + +**Control Request 子类型**（21 种，源码完整列表）： + +| 子类型 | 用途 | 源码 | +|--------|------|------| +| `initialize` | 会话初始化（hooks、MCP 服务器、agents、system prompt） | `SDKControlInitializeRequestSchema` | +| `interrupt` | 中断当前 turn | `SDKControlInterruptRequestSchema` | +| `can_use_tool` | 工具权限审批请求（含 `tool_name`、`input`、`tool_use_id`） | `SDKControlPermissionRequestSchema` | +| `set_permission_mode` | 设置权限模式 | `SDKControlSetPermissionModeRequestSchema` | +| `set_model` | 切换模型 | `SDKControlSetModelRequestSchema` | +| `set_max_thinking_tokens` | 设置 thinking token 上限 | `SDKControlSetMaxThinkingTokensRequestSchema` | +| `mcp_status` | 查询 MCP 服务器状态 | `SDKControlMcpStatusRequestSchema` | +| `get_context_usage` | 获取上下文窗口分析（含分类、总量、百分比、网格可视化数据） | `SDKControlGetContextUsageRequestSchema` | +| `rewind_files` | 回退文件变更到指定用户消息 | `SDKControlRewindFilesRequestSchema` | +| `cancel_async_message` | 丢弃待处理的异步用户消息 | `SDKControlCancelAsyncMessageRequestSchema` | +| `seed_read_state` | 预填充 readFileState 缓存 | `SDKControlSeedReadStateRequestSchema` | +| `hook_callback` | 投递 hook 回调 | `SDKHookCallbackRequestSchema` | +| `mcp_message` | 发送 JSON-RPC 到 MCP 服务器 | `SDKControlMcpMessageRequestSchema` | +| `mcp_set_servers` | 替换动态 MCP 服务器 | `SDKControlMcpSetServersRequestSchema` | +| `reload_plugins` | 从磁盘重新加载插件 | `SDKControlReloadPluginsRequestSchema` | +| `mcp_reconnect` | 重连失败的 MCP 服务器 | `SDKControlMcpReconnectRequestSchema` | +| `mcp_toggle` | 启用/禁用 MCP 服务器 | `SDKControlMcpToggleRequestSchema` | +| `stop_task` | 停止运行中的任务 | `SDKControlStopTaskRequestSchema` | +| `apply_flag_settings` | 合并 flag settings | `SDKControlApplyFlagSettingsRequestSchema` | +| `get_settings` | 获取有效设置（含 per-source 分层：user/project/local/flag/policy） | `SDKControlGetSettingsRequestSchema` | +| `elicitation` | MCP elicitation（用户输入请求） | `SDKControlElicitationRequestSchema` | + +> **iOS 兼容层**：旧版 iOS App 发送 camelCase `requestId`（因 Swift CodingKeys 缺失），源码通过 `normalizeControlMessageKeys()` 将 `requestId` → `request_id` 进行兼容。snake_case 优先级高于 camelCase。 -**keep_alive 处理逻辑**： - -```javascript -// 收到 keep_alive 消息时直接跳过，不做任何处理 -if (message.type === "keep_alive") continue; -``` - -**token 动态更新机制**： +### 8.13.4 Token 刷新系统 -```javascript -// 通过 stdin 注入更新后的 access token -function updateAccessToken(newToken) { - this.accessToken = newToken; - this.writeStdin(JSON.stringify({ - type: "update_environment_variables", - variables: { CLAUDE_CODE_SESSION_ACCESS_TOKEN: newToken } - }) + "\n"); -} -``` +源码揭示了两代独立的 token 刷新策略： -### 8.13.4 Token 刷新系统 +**v1（OAuth 刷新）**——`bridge/replBridge.ts`： +- `clearOAuthTokenCache()` + `checkAndRefreshOAuthTokenIfNeeded()` 刷新 OAuth token +- 通过 `refreshHeaders` 回调将新 token 注入 WebSocket 连接 +- 子进程通过 `update_environment_variables` stdin 消息更新 `CLAUDE_CODE_SESSION_ACCESS_TOKEN` -反编译提取的 token 刷新参数（`dn$` 函数）： +**v2（JWT 刷新）**——`bridge/remoteBridgeCore.ts`： +- `createTokenRefreshScheduler` 在 JWT 过期前 5 分钟触发 +- 调用 `/bridge` 端点刷新凭证，每次调用 bump epoch（防双刷：`authRecoveryInFlight` 标志序列化并发请求） +- SSE 401 触发应急刷新：`onAuth401` → 重新获取 OAuth → 重取凭证 → 重建 transport +- `initialFlushDone` 重置为 false，确保历史消息重传 -| 参数 | 值 | 说明 | -|------|-----|------| -| `refreshBufferMs` | `300000`（5 分钟） | Token 过期前提前刷新的缓冲时间 | -| `followUpRefreshMs` | `1800000`（30 分钟） | 刷新后的 follow-up 刷新间隔 | -| `maxFailures` | `3` | 最大刷新失败次数 | -| `retryDelayMs` | `60000`（1 分钟） | 刷新失败后的重试延迟 | +| 参数 | v1 值 | v2 值 | 说明 | +|------|-------|-------|------| +| 刷新提前量 | — | 过期前 5 分钟 | JWT expiry 驱动 | +| 最大重试 | 3 次 | — | 刷新失败后放弃 | +| 重试延迟 | 60 秒 | 指数退避 | — | +| 睡眠恢复 | 预算重置 | epoch bump | 笔记本睡眠唤醒后 | **刷新策略**：基于 JWT expiry 的定时调度——在 token 过期前 5 分钟触发刷新，最多失败 3 次后放弃。 ### 8.13.5 Bridge 初始化接口（initReplBridge） -反编译提取的 `initReplBridge` 回调接口，这是 Remote Control 的核心桥接层： - -```javascript -// initReplBridge 调用签名 -const bridge = await initReplBridge({ - // 远程端发来的用户消息 - onInboundMessage(message) { /* 注入到本地对话流 */ }, - - // 远程端的权限审批响应 - onPermissionResponse(response) { /* 注入 control_response */ }, - - // 远程端请求中断当前操作 - onInterrupt() { abortController?.abort() }, +源码提取的 `initReplBridge` 回调接口（`bridge/initReplBridge.ts`，569 行）。这是 Remote Control 的核心桥接层，通过 `BridgeCoreParams` 依赖注入所有外部依赖： - // 远程端切换模型 - onSetModel(model) { /* 更新当前模型 */ }, +**`BridgeCoreParams`（注入参数）**： +- `createSession` — 创建新会话 +- `archiveSession` — 归档会话 +- `toSDKMessages` — 内部消息→SDK 消息转换 +- `onAuth401` — 401 认证失败回调 +- `getPollIntervalConfig` — 获取 GrowthBook 下发的 polling 参数 +- `onSetPermissionMode` — 权限模式变更回调 +- `onEnvironmentLost` — 环境丢失回调 - // 远程端调整 thinking token 预算 - onSetMaxThinkingTokens(tokens) { /* 更新配置 */ }, - - // 桥接状态变更通知 - onStateChange(state, metadata) { /* 更新 Redux store */ }, - - // 初始消息（用于恢复断连前的上下文） - initialMessages: previousMessages.length > 0 ? previousMessages : undefined -}); -``` +**`ReplBridgeHandle`（返回的统一句柄）**： +- 只读属性：`bridgeSessionId`、`environmentId`、`sessionIngressUrl` +- `writeMessages(Message[])` — 写入原始消息 +- `writeSdkMessages(SDKMessage[])` — 写入 SDK 格式消息 +- `sendControlRequest` / `sendControlResponse` / `sendControlCancelRequest` — 权限桥接 +- `sendResult` — 发送会话结束信号 +- `teardown()` — 清理资源 -**返回值**： - -| 字段 | 类型 | 说明 | -|------|------|------| -| `bridgeSessionId` | `string` | 桥接会话唯一标识 | -| `sessionIngressUrl` | `string` | 会话入口 URL | -| `environmentId` | `string` | 运行环境标识 | -| `sendControlRequest()` | `function` | 向远程端发送控制请求 | -| `sendControlCancelRequest()` | `function` | 取消未决的控制请求 | -| `writeMessages()` | `function` | 向远程端写入消息流 | -| `teardown()` | `function` | 关闭桥接、清理资源 | - -**会话注册响应格式**（反编译 `ZH` 函数）： - -```javascript -// initReplBridge 成功后，构造响应数据 -{ - session_url: buildSessionUrl(bridgeSessionId, sessionIngressUrl), - connect_url: buildConnectUrl(environmentId, sessionIngressUrl), - environment_id: environmentId -} -``` +**关键设计**：源码中 `BridgeCoreParams` 不直接 import `bootstrap/state` 或 `sessionStorage`，所有外部依赖通过注入传入，实现了核心桥接逻辑与 UI/存储层的零耦合。 ### 8.13.6 Bridge 子进程环境变量 -Server 模式下 `--spawn` 创建的子进程继承以下环境变量（反编译提取）： +Server 模式下 `--spawn` 创建的子进程继承以下环境变量（源码: `bridge/replBridge.ts`）： ```javascript // spawn 子进程的环境变量设置 @@ -577,12 +615,12 @@ Server 模式下 `--spawn` 创建的子进程继承以下环境变量（反编 **实现要点**： - `CLAUDE_CODE_OAUTH_TOKEN` 被显式设为 `undefined`——子进程不应使用父进程的 OAuth 凭证重新注册，而应通过 `SESSION_ACCESS_TOKEN` 接管会话 -- `CLAUDE_CODE_ENVIRONMENT_KIND: "bridge"` 让子进程知道自己在桥接模式下运行，调整行为（如不启动自己的 polling） +- `CLAUDE_CODE_ENVIRONMENT_KIND: "bridge"` 让子进程知道自己在桥接模式下运行，调整行为（如不启动自己的 WebSocket/SSE 连接） - `CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2: "1"` 启用更新的会话入口协议 ### 8.13.7 并发会话管理（PID File） -反编译提取的会话注册文件格式和更新逻辑： +源码提取的会话注册文件格式和更新逻辑（`utils/concurrentSessions.ts`，205 行）： **PID 文件路径**：`$CONFIG_DIR/sessions/{process.pid}.json` @@ -698,7 +736,7 @@ function detectClientType() { ### 8.13.12 实现建议：架构模式总结 -基于以上反编译分析，实现类似 Remote Control 功能的推荐架构模式： +基于源码分析（`bridge/` 目录 12,613 行 + `remote/` 目录 1,127 行），实现类似 Remote Control 功能的推荐架构模式： ``` ┌──────────────────────────────────────────────────────────────────┐ @@ -743,7 +781,7 @@ Qwen Code 基于 Gemini CLI 分叉（[Qwen Code EVIDENCE](../qwen-code/EVIDENCE. | 维度 | Claude Code | Gemini CLI / Qwen Code | |------|-------------|----------------------| | **中继架构** | Anthropic API 中继 | Google Cloud relay | -| **本地传输** | HTTPS polling（服务端可调） | SSE (Server-Sent Events) | +| **本地传输** | WebSocket (v1) / SSE (v2)，服务端可调 | SSE (Server-Sent Events) | | **认证** | claude.ai OAuth full-scope | Google OAuth | | **消息格式** | JSON-lines（8+ 消息类型） | SSE stream | | **状态管理** | Redux 13 字段状态机 | — | @@ -799,14 +837,14 @@ Remote Control 不是孤立功能，而是 Claude Code 跨设备矩阵的一部 **4. 闭源且证据有限** -通信协议细节（polling 间隔、消息格式、端点 URL）未公开，二进制反编译也未完整暴露 Remote Control 专用端点。安全审计只能基于官方文档描述，无法独立验证实现。 +通信协议细节（WebSocket/SSE 双代传输、消息格式、端点 URL）未公开文档化，但已通过源码分析完整揭示。安全审计已可基于源码进行独立验证。 ### 8.14.3 设计权衡总结 | 设计决策 | 收益 | 代价 | |----------|------|------| | 本地执行 + 远程操控 | 完整本地环境可用 | 终端必须在线 | -| HTTPS polling 中继 | 零入站端口，企业友好 | 可能带来更高交互延迟 ⚠️ 推断 | +| WebSocket/SSE 中继 | 零入站端口，企业友好 | 双代传输增加维护复杂度 | | claude.ai OAuth 强绑定 | 统一认证、管理员管控 | 排除 API Key / 第三方用户 | | 多短期凭证 | 凭证泄露影响面小 | 增加注册失败点 | | 遥测与资格检查耦合 | — | 会导致隐私用户被意外阻断 | @@ -832,7 +870,7 @@ Claude Code Remote Control 在"跨设备远程操控终端会话"维度上独有 | **原生移动端 App** | ✅ iOS/Android | ❌（移动浏览器可访问 Web UI） | ❌ | ❌ | ❌ | ❌ | ❌ | | **零入站端口** | ✅（outbound-only 中继） | ❌（开端口） | ❌（开端口） | ❌（开端口） | ❌ | N/A | N/A | | **远程 IDE 集成** | ✅ VS Code | ✅ ACP | ❌ | ❌ | ✅ app-server | ✅ 原生 | ❌ | -| **协议** | HTTPS polling + 中继 | Wire v1.6 (WS) | Hono HTTP+WS+SSE | REST (Axum) | JSON-RPC (WS) | CLI only | CLI only | +| **协议** | WebSocket/SSE + 中继 | Wire v1.6 (WS) | Hono HTTP+WS+SSE | REST (Axum) | JSON-RPC (WS) | CLI only | CLI only | ### 8.15.2 竞品关键差异 From 38026e7adabf21ae41a7c33594acfa41c3ec9735 Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 19:56:48 +0800 Subject: [PATCH 12/15] docs: add Remote Control source code evidence to EVIDENCE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Addresses GPT-5.4 review concern: '正文深度超过证据页可审计深度' New section: SOURCE CODE ANALYSIS: Remote Control / Bridge (~275 lines) - Source code file map (30 files, ~35,000 LOC) - Dual-generation transport architecture (HybridTransport vs SSETransport+CCRClient) - Session states, PID file schema, Redux state machine (13 fields) - BridgeCoreParams dependency injection interface - 21 control_request subtypes with Zod v4 schema names - 3-tier session ingress auth chain - Token refresh (v1 OAuth + v2 JWT) - Connection backoff constants, reconnection strategies, sleep detection - Echo dedup, session activity tracking, iOS compatibility shim - Session-Ingress optimistic concurrency (Last-Uuid + 409 recovery) - Multi-session tracking (9 Map/Set data structures) - Bridge pointer crash recovery, GrowthBook feature flags - Teleport source selection ladder Co-authored-by: Qwen-Coder --- docs/tools/claude-code/EVIDENCE.md | 273 +++++++++++++++++++++++++++++ 1 file changed, 273 insertions(+) diff --git a/docs/tools/claude-code/EVIDENCE.md b/docs/tools/claude-code/EVIDENCE.md index a458fbfa..70c7a5bd 100644 --- a/docs/tools/claude-code/EVIDENCE.md +++ b/docs/tools/claude-code/EVIDENCE.md @@ -398,3 +398,276 @@ From binary analysis of telemetry event construction: - macOS: plist-based managed settings - Windows: Registry policies at HKLM/HKCU\SOFTWARE\Policies\ClaudeCode - Settings key: "Settings" under policy path + +########## SOURCE CODE ANALYSIS: Remote Control / Bridge ########## + +> 以下数据来自 Claude Code 源码分析（`bridge/`、`remote/`、`utils/`、`entrypoints/` 等目录，约 35,000 行 TypeScript），与 v2.1.87 ELF 二进制反编译交叉验证。文件名和行号可直接追溯。 + +### Source Code File Map + +| 文件路径 | 行数 | 职责 | +|----------|------|------| +| `bridge/bridgeMain.ts` | 2,999 | 主桥接编排器（standalone daemon/server 模式） | +| `bridge/replBridge.ts` | 2,406 | REPL 会话内桥接核心 | +| `bridge/remoteBridgeCore.ts` | 1,008 | Env-less v2 桥接核心 | +| `bridge/initReplBridge.ts` | 569 | 桥接初始化 | +| `bridge/sessionRunner.ts` | 550 | 会话执行器 | +| `bridge/bridgeApi.ts` | 539 | Bridge API 层 | +| `bridge/bridgeUI.ts` | 530 | Bridge UI 层 | +| `bridge/bridgeMessaging.ts` | 461 | 消息协议处理 | +| `bridge/createSession.ts` | 384 | 会话创建 | +| `bridge/replBridgeTransport.ts` | 370 | 传输层抽象 | +| `bridge/types.ts` | 262 | 类型定义 | +| `bridge/jwtUtils.ts` | 256 | JWT 认证工具 | +| `bridge/trustedDevice.ts` | 210 | 设备信任管理 | +| `bridge/bridgeEnabled.ts` | 202 | 启用/禁用逻辑 | +| `bridge/pollConfig.ts` | 110 | Polling 配置 | +| `bridge/pollConfigDefaults.ts` | 82 | 默认 polling 参数 | +| `bridge/flushGate.ts` | 71 | 历史消息刷新门控 | +| `bridge/capacityWake.ts` | 56 | 容量唤醒信号 | +| `remote/SessionsWebSocket.ts` | 404 | Sessions WebSocket 客户端 | +| `remote/RemoteSessionManager.ts` | 343 | 远程会话管理 | +| `remote/sdkMessageAdapter.ts` | 302 | SDK 消息适配器 | +| `entrypoints/sdk/controlSchemas.ts` | ~510 | Zod v4 控制消息 schema（21 种子类型） | +| `utils/concurrentSessions.ts` | 205 | PID 文件并发会话管理 | +| `utils/sessionIngressAuth.ts` | 131 | 3 层 token 优先级链 | +| `utils/sessionActivity.ts` | 123 | refcount 心跳计时器 | +| `utils/controlMessageCompat.ts` | 35 | iOS camelCase 兼容层 | +| `services/api/sessionIngress.ts` | 464 | Session-Ingress API（乐观并发写入） | +| `utils/teleport.tsx` | 1,226 | Teleport 远程会话创建/恢复 | +| `server/directConnectManager.ts` | 213 | DirectConnect WebSocket 客户端 | + +### Dual-Generation Transport Architecture + +**v1 (HybridTransport)** — `bridge/replBridge.ts`: +- 读取：WebSocket 长连接 +- 写入：POST 到 Session-Ingress 端点 +- 认证：OAuth token（通过 `refreshHeaders` 回调注入刷新后的 token） +- 重连：指数退避（2s → 60s，15 分钟放弃） +- 选择条件：默认 + +**v2 (SSETransport + CCRClient)** — `bridge/remoteBridgeCore.ts`: +- 读取：SSE（Server-Sent Events） +- 写入：POST 到 CCR `/worker/*` 端点 +- 认证：JWT（含 `session_id` claim + `worker` role） +- 重连：SSE 401 触发 OAuth 刷新 + 凭证重取 +- 选择条件：服务端通过 `secret.use_code_sessions` 标志切换；`CLAUDE_BRIDGE_USE_CCR_V2` env var 强制 + +### Session States (from `server/types.ts`) + +```typescript +type SessionState = 'starting' | 'running' | 'detached' | 'stopping' | 'stopped' +``` + +### Session Registration (from `utils/concurrentSessions.ts`) + +PID file at `$CONFIG_DIR/sessions/{process.pid}.json`: +```json +{ + "pid": "", + "sessionId": "", + "cwd": "", + "startedAt": "", + "kind": "", + "entrypoint": "", + "messagingSocketPath": "", + "name": "", + "logPath": "", + "agent": "", + "status": "" +} +``` + +Session kinds: `'interactive' | 'bg' | 'daemon' | 'daemon-worker'` +Filename validation: `/^\d+\.json$/` prevents accidental deletion of non-PID files. + +### Redux State Machine (13 fields, from `bridge/replBridge.ts`) + +```javascript +replBridgeEnabled: false, +replBridgeExplicit: false, +replBridgeOutboundOnly: false, +replBridgeConnected: false, +replBridgeSessionActive: false, +replBridgeReconnecting: false, +replBridgeConnectUrl: undefined, +replBridgeSessionUrl: undefined, +replBridgeEnvironmentId: undefined, +replBridgeSessionId: undefined, +replBridgeError: undefined, +replBridgeInitialName: undefined, +showRemoteCallout: false +``` + +### Dependency Injection: BridgeCoreParams (from `bridge/initReplBridge.ts`) + +Injected params (no direct imports from bootstrap/state or sessionStorage): +- `createSession` — 创建新会话 +- `archiveSession` — 归档会话 +- `toSDKMessages` — 内部消息→SDK 消息转换 +- `onAuth401` — 401 认证失败回调 +- `getPollIntervalConfig` — 获取 GrowthBook 下发的 polling 参数 +- `onSetPermissionMode` — 权限模式变更回调（含 auto gate check + bypassPermissions availability check） +- `onEnvironmentLost` — 环境丢失回调 + +Returned handle (ReplBridgeHandle): +- Read-only: `bridgeSessionId`, `environmentId`, `sessionIngressUrl` +- Methods: `writeMessages()`, `writeSdkMessages()`, `sendControlRequest()`, `sendControlResponse()`, `sendControlCancelRequest()`, `sendResult()`, `teardown()` + +### Control Request Subtypes (21 types, from `entrypoints/sdk/controlSchemas.ts`) + +Zod v4 schemas using `lazySchema()` wrappers: + +| subtype | Schema Name | +|---------|-------------| +| `initialize` | `SDKControlInitializeRequestSchema` | +| `interrupt` | `SDKControlInterruptRequestSchema` | +| `can_use_tool` | `SDKControlPermissionRequestSchema` | +| `set_permission_mode` | `SDKControlSetPermissionModeRequestSchema` | +| `set_model` | `SDKControlSetModelRequestSchema` | +| `set_max_thinking_tokens` | `SDKControlSetMaxThinkingTokensRequestSchema` | +| `mcp_status` | `SDKControlMcpStatusRequestSchema` | +| `get_context_usage` | `SDKControlGetContextUsageRequestSchema` | +| `rewind_files` | `SDKControlRewindFilesRequestSchema` | +| `cancel_async_message` | `SDKControlCancelAsyncMessageRequestSchema` | +| `seed_read_state` | `SDKControlSeedReadStateRequestSchema` | +| `hook_callback` | `SDKHookCallbackRequestSchema` | +| `mcp_message` | `SDKControlMcpMessageRequestSchema` | +| `mcp_set_servers` | `SDKControlMcpSetServersRequestSchema` | +| `reload_plugins` | `SDKControlReloadPluginsRequestSchema` | +| `mcp_reconnect` | `SDKControlMcpReconnectRequestSchema` | +| `mcp_toggle` | `SDKControlMcpToggleRequestSchema` | +| `stop_task` | `SDKControlStopTaskRequestSchema` | +| `apply_flag_settings` | `SDKControlApplyFlagSettingsRequestSchema` | +| `get_settings` | `SDKControlGetSettingsRequestSchema` | +| `elicitation` | `SDKControlElicitationRequestSchema` | + +Message envelopes: +- `SDKControlRequestSchema`: `{ type: 'control_request', request_id: string, request: }` +- `SDKControlResponseSchema`: `{ type: 'control_response', response: { subtype: 'success'|'error', ... } }` +- `SDKControlCancelRequestSchema`: `{ type: 'control_cancel_request', request_id: string }` +- `SDKKeepAliveMessageSchema`: `{ type: 'keep_alive' }` +- `SDKUpdateEnvironmentVariablesMessageSchema`: `{ type: 'update_environment_variables', variables: Record }` + +### Session Ingress Auth (3-tier, from `utils/sessionIngressAuth.ts`) + +Priority chain: +1. `CLAUDE_CODE_SESSION_ACCESS_TOKEN` env var +2. `CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR` → read from `/dev/fd/{fd}` (macOS) or `/proc/self/fd/{fd}` (Linux) +3. `CLAUDE_SESSION_INGRESS_TOKEN_FILE` or default `/home/claude/.claude/remote/.session_ingress_token` + +Auth header construction: +- Session keys (`sk-ant-sid` prefix): `Cookie: sessionKey={token}` + optional `X-Organization-Uuid` +- JWTs: `Authorization: Bearer {token}` + +### Token Refresh + +**v1 (OAuth)** — `bridge/replBridge.ts`: +- `clearOAuthTokenCache()` + `checkAndRefreshOAuthTokenIfNeeded()` +- `refreshHeaders` callback injects fresh OAuth into WebSocket +- Child process: `update_environment_variables` stdin message updates `CLAUDE_CODE_SESSION_ACCESS_TOKEN` + +**v2 (JWT)** — `bridge/remoteBridgeCore.ts`: +- `createTokenRefreshScheduler`: fires 5 minutes before JWT expiry +- Calls `/bridge` endpoint to refresh, each call bumps epoch +- `authRecoveryInFlight` flag serializes concurrent refresh requests +- SSE 401 → `onAuth401` → re-fetch OAuth → re-fetch credentials → rebuild transport +- `initialFlushDone` reset to false for history re-flush + +### Connection Backoff Constants (from `bridge/replBridge.ts`) + +``` +POLL_ERROR_INITIAL_DELAY_MS = 2_000 +POLL_ERROR_MAX_DELAY_MS = 60_000 +POLL_ERROR_GIVE_UP_MS = 15 * 60 * 1000 (15 minutes) +MAX_ENVIRONMENT_RECREATIONS = 3 +``` + +Standalone daemon (from `bridge/bridgeMain.ts`): +``` +connInitialMs: 2_000 +connCapMs: 120_000 (2 min) +connGiveUpMs: 600_000 (10 min) +generalInitialMs: 500 +generalCapMs: 30_000 +generalGiveUpMs: 600_000 +``` + +### Reconnection Strategies (from `bridge/replBridge.ts`) + +1. **Reconnect-in-place**: `reuseEnvironmentId` → if backend returns same env ID, `reconnectSession()` re-queues. `currentSessionId` stays same, URL valid, `previouslyFlushedUUIDs` preserved. +2. **Fresh session fallback**: If env differs (TTL-expired) or `reconnectSession` throws, archive old + create new. + +### Sleep Detection (from `bridge/replBridge.ts`) + +If `setTimeout` overshoots deadline by 60+ seconds → process was suspended → reset error budget + force fast-poll cycle. + +### Echo Dedup (from `bridge/replBridge.ts`) + +Two-layer UUID protection: +1. `initialMessageUUIDs` — messages sent during session creation +2. `recentPostedUUIDs` — `BoundedUUIDSet(2000)` ring buffer for live writes +Both mirrored in `recentInboundUUIDs` for re-delivered inbound prompts. + +### Session Activity Tracking (from `utils/sessionActivity.ts`) + +- `SESSION_ACTIVITY_INTERVAL_MS = 30_000` (30 seconds) +- `SessionActivityReason = 'api_call' | 'tool_exec'` +- Refcount-based: `startSessionActivity(reason)` / `stopSessionActivity(reason)` +- Gate: `CLAUDE_CODE_REMOTE_SEND_KEEPALIVES` env var + +### iOS Compatibility (from `utils/controlMessageCompat.ts`) + +`normalizeControlMessageKeys(obj)`: converts camelCase `requestId` → snake_case `request_id`. Reason: older iOS app builds missing Swift CodingKeys mapping. Snake_case wins when both present. + +### Session-Ingress Optimistic Concurrency (from `services/api/sessionIngress.ts`) + +- `PUT /v1/session_ingress/session/{sessionId}` with `Last-Uuid` header +- 409 Conflict: adopts server's `x-last-uuid` and retries. If entry already stored (`x-last-uuid === entry.uuid`), recovers silently. +- 10 retries max, exponential backoff (500ms base, 8s cap) +- Per-session `sequential()` wrapper prevents concurrent writes + +### Multi-Session Tracking (from `bridge/bridgeMain.ts`) + +Runtime data structures: +``` +activeSessions: Map +sessionStartTimes: Map +sessionWorkIds: Map +sessionIngressTokens: Map +sessionTimers: Map +completedWorkIds: Set +sessionWorktrees: Map +timedOutSessions: Set +v2Sessions: Set +``` + +Spawn modes: `'single-session' | 'same-dir' | 'worktree'` +GrowthBook gate: `tengu_ccr_bridge_multi_session` +Interactive toggle: 'w' key switches spawn mode at runtime + +### Bridge Pointer (Crash Recovery, from `bridge/replBridge.ts`) + +Written after session creation. Contains `{sessionId, environmentId, source: 'standalone' | 'repl'}`. +Hourly mtime refresh prevents staleness. +On `--continue`, reads pointer across worktree siblings. +Perpetual mode: does NOT send result or stopWork on teardown; backend TTL (300s) expires and re-queues. + +### GrowthBook Feature Flags (from source) + +- `tengu_bridge_poll_interval_config` — dynamic polling parameter tuning +- `tengu_bridge_initial_history_cap` — initial history flush cap (default 200) +- `tengu_ccr_bridge_multi_session` — multi-session per environment gate +- `tengu_ccr_bundle_seed_enabled` — git bundle fallback for Teleport + +### Teleport (from `utils/teleport.tsx`) + +Source selection ladder: +1. **GitHub clone** (default): CCR clones from repo's origin URL. Requires GitHub remote + CCR GitHub App. +2. **Git bundle** (fallback): `git bundle --all`, uploaded via Files API. Triggered when GitHub preflight fails and `tengu_ccr_bundle_seed_enabled` gate is on. `CCR_FORCE_BUNDLE=1` forces this path. +3. **Empty sandbox**: when no repo detected. + +Session creation: `POST /v1/sessions` with `anthropic-beta: ccr-byoc-2025-07-29` header. +Title/branch generation: Claude Haiku generates `{title, branch}`, branch prefix `claude/`. +Polling: `GET /v1/sessions/{id}/events` cursor-based, max 50 pages. +Archive: `POST /v1/sessions/{id}/archive`, 409 = already archived (success). From a24d04b0627e422fc0d4fb3d3b0c123f06dbddac Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 20:08:39 +0800 Subject: [PATCH 13/15] docs: add eligibility check and polling config schema to EVIDENCE.md Addresses GPT-5.4 round 7 feedback: two named anchors missing from evidence page. Added: - Eligibility Check section: admin_requests/eligibility endpoint, org UUID check, and related eligibility functions across subsystems - Polling Config Schema section: complete Zod schema with 8 fields, constraints, defaults, object-level refinements, and usage code from bridge/replBridge.ts Co-authored-by: Qwen-Coder --- docs/tools/claude-code/EVIDENCE.md | 48 +++++++++++++++++++++++++++++- 1 file changed, 47 insertions(+), 1 deletion(-) diff --git a/docs/tools/claude-code/EVIDENCE.md b/docs/tools/claude-code/EVIDENCE.md index 70c7a5bd..00ef4338 100644 --- a/docs/tools/claude-code/EVIDENCE.md +++ b/docs/tools/claude-code/EVIDENCE.md @@ -655,11 +655,57 @@ Perpetual mode: does NOT send result or stopWork on teardown; backend TTL (300s) ### GrowthBook Feature Flags (from source) -- `tengu_bridge_poll_interval_config` — dynamic polling parameter tuning +- `tengu_bridge_poll_interval_config` — dynamic polling parameter tuning (5-minute refresh, Zod validation, falls back to defaults on malformed config) - `tengu_bridge_initial_history_cap` — initial history flush cap (default 200) - `tengu_ccr_bridge_multi_session` — multi-session per environment gate - `tengu_ccr_bundle_seed_enabled` — git bundle fallback for Teleport +### Eligibility Check (from `services/api/adminRequests.ts` + `bridge/bridgeEnabled.ts`) + +Remote Control eligibility is checked via: +``` +GET /api/oauth/organizations/${orgUUID}/admin_requests/eligibility?request_type=${requestType} +``` +Uses OAuth headers with `x-organization-uuid`. + +`bridge/bridgeEnabled.ts:79`: org UUID check — "Unable to determine your organization for Remote Control eligibility. Run `claude auth login` to refresh your account information." + +Related eligibility functions in other subsystems: +- `checkRemoteAgentEligibility()` — before remote agent/ultraplan/review sessions (`tasks/RemoteAgentTask/RemoteAgentTask.tsx`) +- `checkBackgroundRemoteSessionEligibility()` — before background remote sessions (`utils/background/remote/remoteSession.ts`) +- `isRemoteManagedSettingsEligible()` — for remote managed settings sync (`services/remoteManagedSettings/index.ts`) + +### Polling Config Schema (from `bridge/pollConfig.ts` + `bridge/pollConfigDefaults.ts`) + +Complete Zod schema for `tengu_bridge_poll_interval_config`: + +| Field | Type | Default | Constraint | Purpose | +|-------|------|---------|------------|---------| +| `poll_interval_ms_not_at_capacity` | `int` | 2,000 | min 100 | Idle polling interval | +| `poll_interval_ms_at_capacity` | `int` | 0 | 0 or ≥100 | At-capacity polling (0 = disabled) | +| `non_exclusive_heartbeat_interval_ms` | `int` | 0 | min 0 | Heartbeat alongside at-capacity poll | +| `multisession_poll_interval_ms_not_at_capacity` | `int` | 2,000 | min 100 | Multi-session idle | +| `multisession_poll_interval_ms_partial_capacity` | `int` | 2,000 | min 100 | Multi-session partial | +| `multisession_poll_interval_ms_at_capacity` | `int` | 0 | 0 or ≥100 | Multi-session at-capacity | +| `reclaim_older_than_ms` | `int` | 5,000 | min 1 | Server-side work item reclaim threshold | +| `session_keepalive_interval_v2_ms` | `int` | **120,000** | min 0 | **WebSocket keep-alive interval (0 = disabled). Pushes silent `{type:'keep_alive'}` to session-ingress. Fixes Envoy idle timeout on bridge-topology sessions (#21931).** | + +Object-level refinements: +1. At-capacity liveness requires `non_exclusive_heartbeat_interval_ms > 0` OR `poll_interval_ms_at_capacity > 0` +2. Multi-session at-capacity liveness requires `non_exclusive_heartbeat_interval_ms > 0` OR `multisession_poll_interval_ms_at_capacity > 0` + +Usage (from `bridge/replBridge.ts:1533-1546`): +```typescript +const keepAliveIntervalMs = getPollIntervalConfig().session_keepalive_interval_v2_ms +const keepAliveTimer = keepAliveIntervalMs > 0 + ? setInterval(() => { + void transport.write({ type: 'keep_alive' }) + }, keepAliveIntervalMs) + : null +``` + +Same pattern in `cli/remoteIO.ts:180-194` with `this.isBridge` guard. + ### Teleport (from `utils/teleport.tsx`) Source selection ladder: From 2fabdd54d6c2a36c81212b816ad2589c739c10b7 Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 20:16:51 +0800 Subject: [PATCH 14/15] docs: complete EVIDENCE.md update for source code evidence anchor Co-authored-by: Qwen-Coder --- docs/tools/claude-code/EVIDENCE.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/docs/tools/claude-code/EVIDENCE.md b/docs/tools/claude-code/EVIDENCE.md index 00ef4338..ed40477e 100644 --- a/docs/tools/claude-code/EVIDENCE.md +++ b/docs/tools/claude-code/EVIDENCE.md @@ -717,3 +717,30 @@ Session creation: `POST /v1/sessions` with `anthropic-beta: ccr-byoc-2025-07-29` Title/branch generation: Claude Haiku generates `{title, branch}`, branch prefix `claude/`. Polling: `GET /v1/sessions/{id}/events` cursor-based, max 50 pages. Archive: `POST /v1/sessions/{id}/archive`, 409 = already archived (success). + +### Admin Requests Eligibility (from `services/api/adminRequests.ts`) + +API endpoints: +- `POST /api/oauth/organizations/${orgUUID}/admin_requests` — creates admin request +- `GET /api/oauth/organizations/${orgUUID}/admin_requests/me?request_type=${requestType}` — gets user's existing admin requests +- `GET /api/oauth/organizations/${orgUUID}/admin_requests/eligibility?request_type=${requestType}` — checks eligibility + +Error message from `bridge/bridgeEnabled.ts`: +> `Unable to determine your organization for Remote Control eligibility. Run \`claude auth login\` to refresh your account information.` + +### session_keepalive_interval_v2_ms (from `bridge/pollConfig.ts`) + +Zod schema definition: +```typescript +session_keepalive_interval_v2_ms: z.number().int().min(0).default(120_000), +``` + +Default: `120_000` (2 minutes). Comment from `pollConfigDefaults.ts`: +> "0 = disabled. When > 0, push a silent {type:'keep_alive'} frame to session-ingress at this interval so upstream proxies don't GC an idle remote-control session. 2 min is the default. _v2: bridge-only gate (pre-v2 clients read the old key, new clients ignore it)." + +Used in `bridge/replBridge.ts` and `cli/remoteIO.ts`: +```typescript +const keepAliveIntervalMs = getPollIntervalConfig().session_keepalive_interval_v2_ms +``` + +GrowthBook flag: `tengu_bridge_poll_interval_config` controls the entire config object with 5-minute refresh. From 9c0ee4aba41746030cfd2e4d673362f52ae526cd Mon Sep 17 00:00:00 2001 From: wenshao Date: Tue, 31 Mar 2026 20:28:57 +0800 Subject: [PATCH 15/15] =?UTF-8?q?docs:=20unify=20evidence=20source=20label?= =?UTF-8?q?s=20from=20'=E5=8F=8D=E7=BC=96=E8=AF=91'=20to=20source=20code?= =?UTF-8?q?=20references?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GPT-5.4 round 8 feedback: article still had residual 'v2.1.87 反编译' labels when EVIDENCE.md now has stronger source-code-level evidence. Changes: - Blockquote data source: removed 'v2.1.81 二进制反编译' reference - Evidence source table: 6 env vars upgraded to '源码: ' paths - API endpoint table: admin_requests/eligibility → source code reference - Section 8.13 intro: removed 'v2.1.87 ELF 二进制反编译交叉验证' - Code block comments: '反编译' → '源码: ' - Bridge schema, CLI params, telemetry, client detection: all upgraded - Implementation checklist intro: '反编译分析' → '源码分析' Total: 32 '反编译/v2.1.8x' references → 1 remaining (version number, correct) Co-authored-by: Qwen-Coder --- docs/tools/claude-code/08-remote-control.md | 64 ++++++++++----------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/docs/tools/claude-code/08-remote-control.md b/docs/tools/claude-code/08-remote-control.md index 1d0a045d..f8344eb0 100644 --- a/docs/tools/claude-code/08-remote-control.md +++ b/docs/tools/claude-code/08-remote-control.md @@ -2,7 +2,7 @@ > Remote Control 允许从手机、平板或任意浏览器远程操控本地运行的 Claude Code 终端会话。会话**始终在本地执行**，远程端仅作为交互窗口。 > -> **数据来源**：CLI 子命令/参数和故障排查指南来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)（2026-03）；`/remote-control` 斜杠命令类型来自 v2.1.81 二进制反编译；环境变量名来自 [EVIDENCE.md](./EVIDENCE.md) 反编译提取；**技术架构细节来自源码分析**（`bridge/`、`remote/`、`utils/`、`entrypoints/` 等目录，约 35,000 行 TypeScript）。 +> **数据来源**：CLI 子命令/参数和故障排查指南来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)（2026-03）；环境变量名来自 [EVIDENCE.md](./EVIDENCE.md) 源码提取；**技术架构细节来自源码分析**（`bridge/`、`remote/`、`utils/`、`entrypoints/` 等目录，约 35,000 行 TypeScript）。 ## 8.1 概述 @@ -152,7 +152,7 @@ Remote Control 采用 **三方中继**（Three-Party Relay）架构，Anthropic | 组件 | 职责 | 证据来源 | |------|------|----------| | 会话注册 | v1: `registerBridgeEnvironment()` → `environment_id` + `environment_secret`；v2: `createCodeSession()` → JWT | 源码: `bridge/replBridge.ts` | -| 资格检查 | `admin_requests/eligibility` 端点判定用户是否可使用 RC（受订阅类型、管理员策略、组织策略影响） | v2.1.87 反编译 | +| 资格检查 | `admin_requests/eligibility` 端点判定用户是否可使用 RC（受订阅类型、管理员策略、组织策略影响） | 源码: `services/api/adminRequests.ts` + `bridge/bridgeEnabled.ts` | | 凭证刷新 | v1: OAuth 刷新 → `refreshHeaders` 回调；v2: JWT 过期前 5 分钟调用 `/bridge` 端点，bump epoch 防双刷 | 源码: `bridge/remoteBridgeCore.ts` | | 策略执行 | `policy_limits` 端点查询组织级 RC 开关；Team/Enterprise 管理员门控 | EVIDENCE.md | | 配置下发 | GrowthBook 特性门控（`tengu_bridge_poll_interval_config`、`tengu_bridge_initial_history_cap` 等）动态调整运行参数 | 源码: `bridge/bridgeMain.ts` | @@ -288,17 +288,17 @@ Remote Control 的安全架构采用多层防护： | `GET /v1/sessions/{id}/events` | CCR v2 事件流（游标分页，1000 条/页，最多 100 页） | 源码: `utils/teleport.tsx` | | `POST /v1/sessions/{id}/archive` | 归档远程会话（409 = 已归档，视为成功） | 源码: `utils/teleport.tsx` | | `GET /v1/sessions/{id}/teleport-events` | Teleport 事件流（Spanner v2 / threadstore 回退） | 源码: `services/api/sessionIngress.ts` | -| `api.anthropic.com/admin_requests/eligibility` | 资格检查端点（RC 启用前的资格判定） | v2.1.87 反编译 | -| `api.anthropic.com/api/claude_code_grove` | Grove 端点（用途待确认） | v2.1.87 反编译 | -| `api.anthropic.com/api/claude_code_penguin_mode` | 快速模式端点 | v2.1.87 反编译 | -| `api.anthropic.com/api/claude_code_shared_session_transcripts` | 共享会话转录 | v2.1.87 反编译 | -| `api.anthropic.com/api/claude_code/team_memory` | 团队记忆 | v2.1.87 反编译 | +| `api.anthropic.com/admin_requests/eligibility` | 资格检查端点（RC 启用前的资格判定） | 源码: `services/api/adminRequests.ts` | +| `api.anthropic.com/api/claude_code_grove` | Grove 端点（用途待确认） | EVIDENCE.md | +| `api.anthropic.com/api/claude_code_penguin_mode` | 快速模式端点 | EVIDENCE.md | +| `api.anthropic.com/api/claude_code_shared_session_transcripts` | 共享会话转录 | EVIDENCE.md | +| `api.anthropic.com/api/claude_code/team_memory` | 团队记忆 | EVIDENCE.md | -> **注意**：Remote Control 专用的会话注册和消息中继端点 URL 未在 v2.1.87 二进制中明文暴露（可能通过拼接构造或从服务端动态获取）。上述端点为反编译中确认的基础设施端点。 +> **注意**：Remote Control 专用的会话注册和消息中继端点 URL 未在源码中明文暴露（可能通过拼接构造或从服务端动态获取）。上述端点为源码和 EVIDENCE.md 中确认的基础设施端点。 ### 8.6.7 相关环境变量 -前 7 项来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)；其余为 v2.1.87 反编译提取。 +前 7 项来自 [Anthropic 官方文档](https://docs.anthropic.com/en/docs/claude-code/remote-control)；其余来自源码分析（`bridge/`、`utils/` 等目录）。 | 变量 | 影响 | 来源 | |------|------|------| @@ -309,17 +309,17 @@ Remote Control 的安全架构采用多层防护： | `CLAUDE_CODE_USE_BEDROCK` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | | `CLAUDE_CODE_USE_VERTEX` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | | `CLAUDE_CODE_USE_FOUNDRY` | 不兼容——Remote Control 要求 claude.ai 认证 | 官方文档 | -| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 会话访问凭证；存在时客户端类型被判定为 "remote" | v2.1.87 反编译 | -| `CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR` | WebSocket 认证（文件描述符传递）；存在时客户端类型被判定为 "remote" | v2.1.87 反编译 | -| `CLAUDE_CODE_ENTRYPOINT` | 值为 `"remote"` 时标记为远程入口，改变客户端类型行为 | v2.1.87 反编译 | -| `CLAUDE_CODE_REMOTE` | 存在时影响 auto-memory 行为；传递给 teammate spawn 环境 | v2.1.87 反编译 | -| `CLAUDE_CODE_ENVIRONMENT_KIND` | 值为 `"bridge"` 时标识为桥接子进程 | v2.1.87 反编译 | -| `CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2` | 值为 `"1"` 时启用 V2 会话入口协议 | v2.1.87 反编译 | -| `SSE_PORT` | SSE 本地端口（反编译提取，可能用于 Remote Control 或 MCP SSE 传输） | EVIDENCE.md | +| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 会话访问凭证；存在时客户端类型被判定为 "remote" | 源码: `utils/sessionIngressAuth.ts` | +| `CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR` | WebSocket 认证（文件描述符传递）；存在时客户端类型被判定为 "remote" | 源码: `utils/sessionIngressAuth.ts` | +| `CLAUDE_CODE_ENTRYPOINT` | 值为 `"remote"` 时标记为远程入口，改变客户端类型行为 | 源码: `utils/concurrentSessions.ts` | +| `CLAUDE_CODE_REMOTE` | 存在时影响 auto-memory 行为；传递给 teammate spawn 环境 | 源码: `bridge/replBridge.ts` | +| `CLAUDE_CODE_ENVIRONMENT_KIND` | 值为 `"bridge"` 时标识为桥接子进程 | 源码: `bridge/replBridge.ts` | +| `CLAUDE_CODE_POST_FOR_SESSION_INGRESS_V2` | 值为 `"1"` 时启用 V2 会话入口协议 | 源码: `bridge/remoteBridgeCore.ts` | +| `SSE_PORT` | SSE 本地端口（源码提取，可能用于 Remote Control 或 MCP SSE 传输） | EVIDENCE.md | ### 8.6.8 实现者 Checklist：设计决策表 -> 以下清单提炼自反编译分析和官方文档。每个条目对应实现一个 Remote Control 类功能时**必须做出的设计决策**，Claude Code 的选择作为参考标注。 +> 以下清单提炼自源码分析和官方文档。每个条目对应实现一个 Remote Control 类功能时**必须做出的设计决策**，Claude Code 的选择作为参考标注。 | # | 设计决策 | Claude Code 的选择 | 实现考量 | |---|----------|-------------------|----------| @@ -423,7 +423,7 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： ## 8.13 实现参考：面向 Code Agent 开发者 -> 以下数据来自源码分析（`bridge/`、`remote/`、`utils/`、`entrypoints/` 等目录，约 35,000 行 TypeScript）及 v2.1.87 ELF 二进制反编译交叉验证。源码文件名和行号可直接追溯。 +> 以下数据来自源码分析（`bridge/`、`remote/`、`utils/`、`entrypoints/` 等目录，约 35,000 行 TypeScript）。源码文件名和行号可直接追溯。 > > **适用场景**：其他 Code Agent 开发者实现类似"远程控制"功能时，可将本节作为架构参考。Claude Code 的实现是经过生产验证的方案，但并非唯一可行路径。 @@ -432,7 +432,7 @@ Claude Code 提供了多种跨设备工作方式，各有侧重： Remote Control 在 Redux AppState 中维护 13 个桥接状态字段（源码: `bridge/replBridge.ts`）： ```javascript -// v2.1.87 二进制反编译：AppState 初始状态 +// 源码: bridge/replBridge.ts — AppState 初始状态 replBridgeEnabled: false, // 是否启用桥接（旧字段，已迁移至 remoteControlAtStartup） replBridgeExplicit: false, // 用户是否主动启用（vs 自动启用） replBridgeOutboundOnly: false, // 仅出站模式：可推送消息但不接受远程控制指令 @@ -448,10 +448,10 @@ replBridgeInitialName: undefined, // 初始会话名称（--name 参数值） showRemoteCallout: false // UI 标志：是否显示远程控制提示 ``` -**状态迁移逻辑**（反编译 `Cl7` 函数）： +**状态迁移逻辑**（源码: `migrations/migrateReplBridgeEnabledToRemoteControlAtStartup.ts`）： ```javascript -// 旧版迁移：replBridgeEnabled → remoteControlAtStartup +// 源码: migrations/migrateReplBridgeEnabledToRemoteControlAtStartup.ts function migrateBridgeConfig(state) { if (state.replBridgeEnabled === undefined) return state; if (state.remoteControlAtStartup !== undefined) return state; @@ -468,10 +468,10 @@ function migrateBridgeConfig(state) { ### 8.13.2 Polling 配置参数（服务端可调 / GrowthBook 动态下发） -服务端下发 polling 配置，客户端通过 Zod schema 校验后使用。以下为反编译提取的默认值和校验规则： +服务端下发 polling 配置，客户端通过 Zod schema 校验后使用。以下为源码中的默认值和校验规则（源码: `bridge/pollConfigDefaults.ts` + `bridge/pollConfig.ts`）： ```javascript -// v2.1.87 二进制反编译：默认 polling 配置 +// 源码: bridge/pollConfigDefaults.ts — 默认 polling 配置 const DEFAULT_POLL_CONFIG = { poll_interval_ms_not_at_capacity: 2000, // 未满容量时：2 秒轮询 poll_interval_ms_at_capacity: 600000, // 满容量时：10 分钟心跳（或 0=禁用） @@ -658,7 +658,7 @@ async function updatePidFile(updates) { ### 8.13.8 Bridge 会话注册 Schema -反编译提取的 Zod schema（`pN9`），用于注册桥接会话： +源码提取的 Zod schema（源码: `bridge/createSession.ts`），用于注册桥接会话： ```javascript // 会话注册请求体 schema @@ -671,7 +671,7 @@ const bridgeSessionSchema = z.object({ ### 8.13.9 CLI 完整参数（remote-control 子命令） -反编译提取的 `claude remote-control` 完整参数列表： +源码提取的 `claude remote-control` 完整参数列表（源码: `bridge/bridgeMain.ts`）： ``` claude remote-control [options] @@ -690,7 +690,7 @@ claude remote-control [options] **新增发现**（相比官方文档）： -| 参数 | 官方文档 | 反编译发现 | +| 参数 | 官方文档 | 源码发现 | |------|----------|-----------| | `--spawn session` | 未提及 | 第三种 spawn 模式 | | `--create-session-in-dir` | 未提及 | 在指定目录创建会话 | @@ -700,7 +700,7 @@ claude remote-control [options] ### 8.13.10 遥测事件 -Remote Control 相关的遥测事件前缀为 `tengu_bridge_*`，反编译提取到以下事件名： +Remote Control 相关的遥测事件前缀为 `tengu_bridge_*`，源码提取到以下事件名（源码: `bridge/bridgeMain.ts`）： | 事件名 | 用途 | |--------|------| @@ -711,7 +711,7 @@ Remote Control 相关的遥测事件前缀为 `tengu_bridge_*`，反编译提取 ### 8.13.11 客户端类型检测 -反编译提取的客户端类型判定逻辑： +源码提取的客户端类型判定逻辑（源码: `utils/sessionIngressAuth.ts` + `bridge/replBridge.ts`）： ```javascript // 客户端类型检测 @@ -729,10 +729,10 @@ function detectClientType() { | 变量 | 说明 | 来源 | |------|------|------| -| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 存在时标记为 "remote" 客户端类型 | 反编译 | -| `CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR` | 存在时标记为 "remote" 客户端类型（文件描述符方式传递 WebSocket 认证） | 反编译 | -| `CLAUDE_CODE_ENTRYPOINT` | 值为 `"remote"` 时标记为远程入口 | 反编译 | -| `CLAUDE_CODE_REMOTE` | 存在时影响 auto-memory 行为；传递给 teammate spawn 环境 | 反编译 | +| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | 存在时标记为 "remote" 客户端类型 | 源码: `utils/sessionIngressAuth.ts` | +| `CLAUDE_CODE_WEBSOCKET_AUTH_FILE_DESCRIPTOR` | 存在时标记为 "remote" 客户端类型（文件描述符方式传递 WebSocket 认证） | 源码: `utils/sessionIngressAuth.ts` | +| `CLAUDE_CODE_ENTRYPOINT` | 值为 `"remote"` 时标记为远程入口 | 源码: `utils/concurrentSessions.ts` | +| `CLAUDE_CODE_REMOTE` | 存在时影响 auto-memory 行为；传递给 teammate spawn 环境 | 源码: `bridge/replBridge.ts` | ### 8.13.12 实现建议：架构模式总结