mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-18 14:25:51 +00:00
docs: 文档大重组，对齐 README 入口
以 README 为单一事实来源，重构整个 docs/ 目录。 最终结构（3 大组、15 篇文档）： - 开始: installation / quickstart / model-providers - 核心功能: pipes-and-lan、acp、channels、chrome-control、computer-use、 voice-mode、web-browser-tool、auto-dream、remote-control-self-hosting、 langfuse-monitoring - 内部机制: growthbook-adapter、sentry-setup 主要变更： - 删除 56 个 README 未提及的文档（architecture 全部 / guides 全部 / features 中未在 README 出现的 20 篇 / internals 中的 5 篇） - 合并 6 组重复文档（pipes-and-lan、chrome-control、acp、computer-use、 auto-dream、coordinator-mode 简化为入口） - features 子组从 5 → 4，ui/ 合并入 tools/ - 所有保留文档加上人性化 frontmatter（title/description/keywords） - docs.json navigation 简化为 3 大组，redirects 重新过滤为 7 条合并跳转 - 新增 docs.md 工作大纲与验证脚本（verify-docs / check-docs-orphans / dump-docs-outline） 总计 130 文件改动，从约 35000 行精简到约 2000 行。 Co-Authored-By: glm-5.2 <zai-org@claude-code-best.win>
This commit is contained in:
claude-code-best
188
docs/features/modes/auto-dream.md
Normal file
188
docs/features/modes/auto-dream.md
Normal file
@@ -0,0 +1,188 @@
|
||||
---
|
||||
title: "后台记忆整理（Auto Dream）"
|
||||
description: "会话间自动审查、组织和修剪持久化记忆，确保未来会话快速获得准确上下文。"
|
||||
keywords: ["Auto Dream", "记忆整合", "后台任务", "MEMORY.md", "/dream 命令"]
|
||||
---
|
||||
|
||||
# Auto Dream — 自动记忆整理
|
||||
|
||||
## 概述
|
||||
|
||||
Auto Dream 是 Claude Code 的后台记忆整合机制。它在会话间自动审查、组织和修剪持久化记忆文件，确保未来会话能快速获得准确的上下文。
|
||||
|
||||
记忆系统存储在文件系统中（默认 `~/.claude/projects/<project-slug>/memory/`），由 `MEMORY.md` 索引文件和若干主题文件（如 `user_language.md`、`project_overview.md`）组成。随着会话积累，记忆会变得过时、冗余或矛盾——Dream 负责清理这些堆积。
|
||||
|
||||
## 架构
|
||||
|
||||
### 核心模块
|
||||
|
||||
| 模块 | 路径 | 职责 |
|
||||
|------|------|------|
|
||||
| 调度器 | `src/services/autoDream/autoDream.ts` | 时间/会话/锁三重门控，触发 forked agent |
|
||||
| 配置 | `src/services/autoDream/config.ts` | 读取 `isAutoDreamEnabled()` 开关 |
|
||||
| 提示词 | `src/services/autoDream/consolidationPrompt.ts` | 构建 4 阶段整理提示词 |
|
||||
| 锁文件 | `src/services/autoDream/consolidationLock.ts` | PID 锁 + mtime 作为 `lastConsolidatedAt` |
|
||||
| 任务 UI | `src/tasks/DreamTask/DreamTask.ts` | 后台任务注册，footer pill + Shift+Down 可见 |
|
||||
| 手动入口 | `src/skills/bundled/dream.ts` | `/dream` 命令，无条件可用 |
|
||||
|
||||
### 记忆路径解析
|
||||
|
||||
优先级（`src/memdir/paths.ts`）：
|
||||
|
||||
1. `CLAUDE_COWORK_MEMORY_PATH_OVERRIDE` 环境变量（完整路径覆盖）
|
||||
2. `autoMemoryDirectory` 设置项（`settings.json`，支持 `~/` 展开）
|
||||
3. 默认：`<memoryBase>/projects/<sanitized-git-root>/memory/`
|
||||
|
||||
其中 `memoryBase` = `CLAUDE_CODE_REMOTE_MEMORY_DIR` 或 `~/.claude`。
|
||||
|
||||
## 触发机制
|
||||
|
||||
### 自动触发（Auto Dream）
|
||||
|
||||
每个对话轮次结束后，`executeAutoDream()` 按顺序检查三重门控：
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ Gate 1: 全局开关 │
|
||||
│ isAutoMemoryEnabled() && isAutoDreamEnabled() │
|
||||
│ 排除: KAIROS 模式 / Remote 模式 │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ Gate 2: 时间门控 │
|
||||
│ hoursSince(lastConsolidatedAt) >= minHours │
|
||||
│ 默认: 24 小时 │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ Gate 3: 会话门控 │
|
||||
│ sessionsTouchedSince(lastConsolidatedAt) >= minSessions │
|
||||
│ 默认: 5 个会话（排除当前会话） │
|
||||
├─────────────────────────────────────────────────────┤
|
||||
│ Lock: PID 锁文件 │
|
||||
│ .consolidate-lock (mtime = lastConsolidatedAt) │
|
||||
│ 死进程检测 + 1 小时过期 │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
全部通过后，以 **forked agent**（受限子代理）方式运行整理任务：
|
||||
|
||||
- Bash 工具限制为只读命令（`ls`、`grep`、`cat` 等）
|
||||
- 只能读写记忆目录内的文件
|
||||
- 用户可在 Shift+Down 后台任务面板中查看进度或终止
|
||||
|
||||
### 手动触发（`/dream` 命令）
|
||||
|
||||
通过 `/dream` 命令随时触发，无门控限制：
|
||||
|
||||
- 在主循环中运行（非 forked agent），拥有完整工具权限
|
||||
- 用户可实时观察操作过程
|
||||
- 执行前自动更新锁文件 mtime
|
||||
|
||||
### 配置开关
|
||||
|
||||
| 开关 | 位置 | 作用 |
|
||||
|------|------|------|
|
||||
| `autoDreamEnabled` | `settings.json` | `true`/`false` 显式开关 |
|
||||
| `autoMemoryEnabled` | `settings.json` | 总开关，关闭后所有记忆功能禁用 |
|
||||
| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 环境变量 | `1`/`true` 关闭所有记忆功能 |
|
||||
| `tengu_onyx_plover` | GrowthBook | 官方远程配置，控制 `enabled`/`minHours`/`minSessions` |
|
||||
|
||||
默认值（无 GrowthBook 连接时）：
|
||||
|
||||
```typescript
|
||||
minHours: 24 // 距上次整理至少 24 小时
|
||||
minSessions: 5 // 至少有 5 个新会话
|
||||
```
|
||||
|
||||
## 整理流程（4 阶段）
|
||||
|
||||
Dream agent 执行的提示词包含 4 个阶段：
|
||||
|
||||
### Phase 1 — 定位（Orient）
|
||||
|
||||
- `ls` 记忆目录，查看现有文件
|
||||
- 读取 `MEMORY.md` 索引
|
||||
- 浏览现有主题文件，避免重复创建
|
||||
|
||||
### Phase 2 — 采集信号（Gather）
|
||||
|
||||
按优先级收集新信息：
|
||||
|
||||
1. **日志文件**（`logs/YYYY/MM/YYYY-MM-DD.md`，KAIROS 模式下的追加式日志）
|
||||
2. **过时记忆** — 与当前代码库状态矛盾的事实
|
||||
3. **会话记录** — 窄关键词 grep JSONL 文件（不全文读取）
|
||||
|
||||
### Phase 3 — 整合（Consolidate）
|
||||
|
||||
- 合并新信号到现有主题文件，而非创建近似重复
|
||||
- 将相对日期（"昨天"、"上周"）转为绝对日期
|
||||
- 删除被推翻的事实
|
||||
|
||||
### Phase 4 — 修剪与索引（Prune）
|
||||
|
||||
- `MEMORY.md` 保持在 200 行以内、25KB 以内
|
||||
- 每条索引项一行，不超过 150 字符
|
||||
- 移除过时/错误/被取代的指针
|
||||
|
||||
## 记忆类型
|
||||
|
||||
记忆系统使用 4 种类型（`src/memdir/memoryTypes.ts`）：
|
||||
|
||||
| 类型 | 用途 | 示例 |
|
||||
|------|------|------|
|
||||
| `user` | 用户角色、偏好、知识 | 用户是高级后端工程师，偏好中文交流 |
|
||||
| `feedback` | 工作方式指导 | 不要 mock 数据库测试；代码审查用 bundled PR |
|
||||
| `project` | 项目上下文（非代码可推导的） | 合并冻结从 3 月 5 日开始；认证重写是合规需求 |
|
||||
| `reference` | 外部系统指针 | Linear INGEST 项目跟踪 pipeline bugs |
|
||||
|
||||
**不保存的内容**：代码模式、架构、文件路径（可从代码推导）；Git 历史（`git log` 权威）；调试方案（代码中已有）。
|
||||
|
||||
## 锁文件机制
|
||||
|
||||
`.consolidate-lock` 文件位于记忆目录内：
|
||||
|
||||
- **文件内容**：持有者 PID
|
||||
- **mtime**：即 `lastConsolidatedAt` 时间戳
|
||||
- **过期**：1 小时（防 PID 复用）
|
||||
- **竞态处理**：双进程同时写入时，后读验证 PID，失败者退出
|
||||
- **回滚**：forked agent 失败或被用户终止时，mtime 回退到获取前的值
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景 1：日常开发中的自动整理
|
||||
|
||||
开发者连续多天使用 Claude Code 处理不同任务。Auto Dream 在积累 5+ 个会话且距上次整理 24 小时后自动触发，整合分散在多次会话中的用户偏好和项目决策。
|
||||
|
||||
### 场景 2：手动整理记忆
|
||||
|
||||
用户发现 Claude 重复犯相同错误或遗忘之前的决策。输入 `/dream` 立即触发整理，无需等待自动触发周期。
|
||||
|
||||
### 场景 3：新会话快速上下文
|
||||
|
||||
新会话启动时，`MEMORY.md` 被加载到上下文中。经过 Dream 整理的记忆文件结构清晰、信息准确，让 Claude 快速了解用户和项目。
|
||||
|
||||
### 场景 4：KAIROS 模式下的日志蒸馏
|
||||
|
||||
KAIROS（长驻助手模式）中，agent 以追加方式写入日期日志文件。Dream 负责将这些日志蒸馏为主题文件和 `MEMORY.md` 索引。
|
||||
|
||||
## 与其他系统的关系
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌──────────────┐ ┌───────────────┐
|
||||
│ 会话交互 │────▶│ 记忆写入 │────▶│ MEMORY.md │
|
||||
│ (主 agent) │ │ (即时保存) │ │ + 主题文件 │
|
||||
└─────────────┘ └──────────────┘ └───────┬───────┘
|
||||
│
|
||||
┌───────────────────────────────────────┘
|
||||
▼
|
||||
┌──────────────┐ ┌──────────────┐
|
||||
│ Auto Dream │────▶│ 整理/修剪 │
|
||||
│ (后台触发) │ │ 去重/纠错 │
|
||||
└──────────────┘ └──────────────┘
|
||||
▲
|
||||
┌──────────────┐
|
||||
│ /dream 命令 │
|
||||
│ (手动触发) │
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
- **extractMemories**（`src/services/extractMemories/`）：每轮次结束时从对话中提取新记忆并写入。Dream 不负责提取，只负责整理。
|
||||
- **CLAUDE.md**：项目级指令文件，加载到上下文中但不属于记忆系统。
|
||||
- **Team Memory**（`TEAMMEM` feature）：团队共享记忆目录，与个人记忆使用相同的 Dream 机制。
|
||||
363
docs/features/modes/remote-control-self-hosting.md
Normal file
363
docs/features/modes/remote-control-self-hosting.md
Normal file
@@ -0,0 +1,363 @@
|
||||
---
|
||||
title: "Remote Control 私有化部署"
|
||||
description: "Docker 自托管 RCS，含 Web UI 控制面板、ACP agent 接入、JWT 认证。"
|
||||
keywords: ["Remote Control Server", "Docker 部署", "ACP agent", "JWT 认证", "Web UI 控制面板"]
|
||||
---
|
||||
|
||||
# Remote Control Server 私有化部署指南
|
||||
|
||||
本指南说明如何将 Remote Control Server (RCS) 部署到私有环境，并通过 Claude Code CLI 连接使用。
|
||||
|
||||
## 架构概览
|
||||
|
||||
```
|
||||
┌──────────────────┐ ┌──────────────────────┐
|
||||
│ Claude Code CLI │ ◄── HTTP/SSE/WS ─►│ Remote Control │
|
||||
│ (Bridge Worker) │ 长轮询 + 心跳 │ Server (RCS) │
|
||||
└──────────────────┘ │ │
|
||||
│ ┌──────────────┐ │
|
||||
┌──────────────────┐ HTTP/SSE │ │ In-Memory │ │
|
||||
│ Web UI 控制面板 │ ◄─────────────── │ │ Store │ │
|
||||
│ (/code/*) │ │ └──────────────┘ │
|
||||
│ (React + Vite) │ │ ┌──────────────┐ │
|
||||
└──────────────────┘ │ │ JWT Auth │ │
|
||||
│ └──────────────┘ │
|
||||
┌──────────────────┐ │ ┌──────────────┐ │
|
||||
│ acp-link │ ◄── ACP Relay ─── │ │ ACP Handler │ │
|
||||
│ + ACP Agent │ WebSocket │ └──────────────┘ │
|
||||
└──────────────────┘ └──────────────────────┘
|
||||
```
|
||||
|
||||
**RCS 是一个纯内存的中间服务**，它的职责是：
|
||||
- 接收 Claude Code CLI 的环境注册和工作轮询
|
||||
- 接收 acp-link 的 ACP agent 注册，支持 WebSocket relay 桥接
|
||||
- 提供 Web UI 供操作者远程监控和审批
|
||||
- 通过 WebSocket/SSE 双向传输消息
|
||||
- 管理会话、环境、权限请求
|
||||
- 提供 ACP SSE event stream 供外部消费者订阅 channel group 事件
|
||||
|
||||
## 前置条件
|
||||
|
||||
- 一台可被 Claude Code CLI 和 Web 浏览器同时访问的服务器（物理机、VM、容器均可）
|
||||
- [Docker](https://www.docker.com/)
|
||||
- 启用 `BRIDGE_MODE` feature flag 的 Claude Code 构建
|
||||
|
||||
## 部署
|
||||
|
||||
### 构建 Docker 镜像
|
||||
|
||||
在项目根目录执行：
|
||||
|
||||
```bash
|
||||
docker build -t rcs:latest -f packages/remote-control-server/Dockerfile .
|
||||
```
|
||||
|
||||
### 启动容器
|
||||
|
||||
```bash
|
||||
docker run -d \
|
||||
--name rcs \
|
||||
-p 3000:3000 \
|
||||
-e RCS_API_KEYS=sk-rcs-your-secret-key-here \
|
||||
-e RCS_BASE_URL=https://rcs.example.com \
|
||||
-v rcs-data:/app/data \
|
||||
--restart unless-stopped \
|
||||
rcs:latest
|
||||
```
|
||||
|
||||
### Docker Compose
|
||||
|
||||
```yaml
|
||||
version: "3.8"
|
||||
services:
|
||||
rcs:
|
||||
build:
|
||||
context: .
|
||||
dockerfile: packages/remote-control-server/Dockerfile
|
||||
args:
|
||||
VERSION: "0.1.0"
|
||||
ports:
|
||||
- "3000:3000"
|
||||
environment:
|
||||
- RCS_API_KEYS=sk-rcs-your-secret-key-here
|
||||
- RCS_BASE_URL=https://rcs.example.com
|
||||
volumes:
|
||||
- rcs-data:/app/data
|
||||
restart: unless-stopped
|
||||
|
||||
volumes:
|
||||
rcs-data:
|
||||
```
|
||||
|
||||
启动：
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
## 环境变量参考
|
||||
|
||||
### 服务器端
|
||||
|
||||
| 变量 | 必填 | 默认值 | 说明 |
|
||||
|------|------|--------|------|
|
||||
| `RCS_API_KEYS` | **是** | _(空)_ | API 密钥列表，逗号分隔。用于客户端认证和 JWT 签名。**务必设置强密钥** |
|
||||
| `RCS_PORT` | 否 | `3000` | 服务监听端口 |
|
||||
| `RCS_HOST` | 否 | `0.0.0.0` | 服务监听地址 |
|
||||
| `RCS_BASE_URL` | 否 | `http://localhost:3000` | 外部访问 URL。用于生成 WebSocket 连接地址，必须与客户端实际访问的地址一致 |
|
||||
| `RCS_VERSION` | 否 | `0.1.0` | 版本号，显示在 `/health` 响应中 |
|
||||
| `RCS_POLL_TIMEOUT` | 否 | `8` | V1 工作轮询超时（秒） |
|
||||
| `RCS_HEARTBEAT_INTERVAL` | 否 | `20` | 心跳间隔（秒） |
|
||||
| `RCS_JWT_EXPIRES_IN` | 否 | `3600` | JWT 令牌有效期（秒） |
|
||||
| `RCS_DISCONNECT_TIMEOUT` | 否 | `300` | 断线判定超时（秒） |
|
||||
| `RCS_WS_IDLE_TIMEOUT` | 否 | `30` | WebSocket 空闲超时（秒），Bun 发送协议级 ping |
|
||||
| `RCS_WS_KEEPALIVE_INTERVAL` | 否 | `20` | 服务端→客户端 keep_alive 帧间隔（秒），防止反向代理关闭空闲连接 |
|
||||
|
||||
### 客户端（Claude Code CLI）
|
||||
|
||||
| 变量 | 必填 | 说明 |
|
||||
|------|------|------|
|
||||
| `CLAUDE_BRIDGE_BASE_URL` | **是** | RCS 服务器地址，例如 `https://rcs.example.com`。设置此变量即启用自托管模式，跳过 GrowthBook 门控 |
|
||||
| `CLAUDE_BRIDGE_OAUTH_TOKEN` | **是** | 认证令牌，必须与服务器端 `RCS_API_KEYS` 中的某个值匹配 |
|
||||
| `CLAUDE_BRIDGE_SESSION_INGRESS_URL` | 否 | WebSocket 入口地址（默认与 `CLAUDE_BRIDGE_BASE_URL` 相同） |
|
||||
| `CLAUDE_CODE_REMOTE` | 否 | 设为 `1` 时标记为远程执行模式 |
|
||||
|
||||
## Claude Code 客户端连接
|
||||
|
||||
### 1. 设置环境变量
|
||||
|
||||
在运行 Claude Code 的机器上设置：
|
||||
|
||||
```bash
|
||||
export CLAUDE_BRIDGE_BASE_URL="https://rcs.example.com"
|
||||
export CLAUDE_BRIDGE_OAUTH_TOKEN="sk-rcs-your-secret-key-here"
|
||||
```
|
||||
|
||||
### 2. 启动 Claude Code
|
||||
|
||||
```bash
|
||||
# 使用 dev 模式（BRIDGE_MODE 默认启用）
|
||||
bun run dev
|
||||
|
||||
# 或使用构建产物
|
||||
bun run dist/cli.js
|
||||
```
|
||||
|
||||
### 3. 执行 /remote-control 命令
|
||||
|
||||
在 Claude Code 的 REPL 中输入：
|
||||
|
||||
```
|
||||
/remote-control
|
||||
```
|
||||
|
||||
环境型 Remote Control（例如 `claude remote-control` 子命令）会向 RCS 注册环境，注册成功后在终端显示连接 URL：
|
||||
|
||||
```
|
||||
https://rcs.example.com/code?bridge=<environmentId>
|
||||
```
|
||||
|
||||
交互式 REPL 方式（`--remote-control` 或 `/remote-control`）在某些桥接模式下也可能直接给出会话 URL：
|
||||
|
||||
```
|
||||
https://rcs.example.com/code/session_<id>
|
||||
```
|
||||
|
||||
两种 URL 都可以直接在浏览器打开并远程操控当前会话；只有 environment 模式才会出现在 Web UI 的环境列表中。
|
||||
|
||||
若已连接，再次执行 `/remote-control` 会显示对话框，包含以下选项：
|
||||
- **Disconnect this session** — 断开远程连接
|
||||
- **Show QR code** — 显示/隐藏二维码
|
||||
- **Continue** — 保持连接，继续使用
|
||||
|
||||
也可通过 CLI 参数直接启动：
|
||||
|
||||
```bash
|
||||
claude remote-control
|
||||
# 或简写
|
||||
claude rc
|
||||
# 或
|
||||
claude bridge
|
||||
```
|
||||
|
||||
## Web UI 控制面板
|
||||
|
||||
通过 `/remote-control` 命令获取 URL 后，在浏览器打开即可使用。
|
||||
|
||||
### 技术栈（v2，2026-04-18 重构）
|
||||
|
||||
Web UI 已从原生 JS 重构为 **React + Vite + Radix UI**：
|
||||
|
||||
- **框架**: React 19 + Vite 构建，TypeScript
|
||||
- **UI 组件**: Radix UI primitives（Dialog、Tabs、Select、Popover 等）
|
||||
- **聊天组件**: 完整的 ACP 聊天界面，支持 Plan 可视化、工具调用展示、权限审批
|
||||
- **AI Elements**: 独立的 AI 交互组件库（message、reasoning、tool、code-block、prompt-input 等）
|
||||
- **ACP 直连**: 支持 QR 码扫描自动跳转 ACP 直连视图（`ACPDirectView`）
|
||||
- **主题系统**: 暗色/亮色主题切换，遵循 Impeccable 设计系统
|
||||
|
||||
### 功能
|
||||
|
||||
- 查看已注册的运行环境（environment 模式），区分 ACP Agent 和 Claude Code 类型
|
||||
- 创建和管理会话
|
||||
- 实时查看对话消息和工具调用
|
||||
- 查看 Autopilot 状态（`standby` / `sleeping`）和自动运行指示
|
||||
- 查看 authoritative task snapshots 驱动的 Tasks 面板
|
||||
- 审批 Claude Code 的工具权限请求
|
||||
- 权限模式选择器（6 种模式：默认/自动接受编辑/跳过权限/规划/不询问/自动判断）
|
||||
- 模型选择器（可选可用模型）
|
||||
- Plan 可视化（进度条、状态图标、优先级标签）
|
||||
- ACP QR 扫描自动跳转到 ACP 聊天界面
|
||||
|
||||
Web UI 使用 UUID 认证（无需用户账户），适合受信任网络环境。
|
||||
|
||||
## ACP 支持
|
||||
|
||||
RCS 支持 ACP (Agent Client Protocol) agent 通过 `acp-link` 包接入。
|
||||
|
||||
### 架构
|
||||
|
||||
```
|
||||
acp-link ──REST注册──► RCS POST /v1/environments/bridge
|
||||
acp-link ──WS identify──► RCS WebSocket (携带 agentId)
|
||||
acp-link ◄──ACP relay──► RCS ◄──Web UI WS──► 浏览器
|
||||
```
|
||||
|
||||
### 后端组件
|
||||
|
||||
| 文件 | 职责 |
|
||||
|------|------|
|
||||
| `src/routes/acp/index.ts` | ACP REST 路由：agents 列表、channel groups、relay |
|
||||
| `src/transport/acp-ws-handler.ts` | ACP WebSocket 处理：agent 注册、心跳、消息转发 |
|
||||
| `src/transport/acp-relay-handler.ts` | 前端 WS → acp-link 透传 + EventBus inbound 转发 |
|
||||
| `src/transport/acp-sse-writer.ts` | SSE event stream 供外部消费者订阅 |
|
||||
|
||||
ACP 的 agents、channel groups、relay 和 channel-group SSE 端点都要求有效
|
||||
API key。浏览器 `EventSource` 不能发送 `Authorization` header，外部订阅
|
||||
`/acp/channel-groups/:id/events` 时需要使用 `fetch` + `ReadableStream` 并带
|
||||
`Authorization: Bearer <api-key>`。
|
||||
|
||||
### acp-link 连接
|
||||
|
||||
详见 [acp-link 文档](../agents/acp-link.md)。
|
||||
|
||||
```bash
|
||||
# 在 RCS 环境中启动 acp-link
|
||||
# 注意：claude 本身不支持 ACP，需要用 ccb-bun --acp
|
||||
ACP_RCS_URL=http://localhost:3000 \
|
||||
ACP_RCS_TOKEN=sk-rcs-your-key \
|
||||
acp-link ccb-bun -- --acp
|
||||
```
|
||||
|
||||
ACP session 在 Web UI 中显示品牌色标签，与普通 Claude Code session 区分。
|
||||
|
||||
## 工作流程详解
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────────────────────┐
|
||||
│ 完整工作流程 │
|
||||
└──────────────────────────────────────────────────────────┘
|
||||
|
||||
1. Claude Code CLI 启动，设置环境变量指向自托管 RCS
|
||||
|
||||
2. 用户执行 /remote-control 命令
|
||||
|
||||
3. 注册环境
|
||||
CLI ──POST /v1/environments/bridge──► RCS
|
||||
CLI ◄── { environment_id, environment_secret } ── RCS
|
||||
|
||||
4. 终端显示连接 URL
|
||||
https://rcs.example.com/code?bridge=<environmentId>
|
||||
|
||||
5. 开始工作轮询（循环）
|
||||
CLI ──GET /v1/environments/:id/work/poll──► RCS
|
||||
（长轮询，等待任务分配，超时 8 秒后重试）
|
||||
|
||||
6. 浏览器打开 URL → Web UI 创建任务
|
||||
Browser ──POST /web/sessions──► RCS
|
||||
RCS 分配 work 给正在轮询的 CLI
|
||||
|
||||
7. CLI 收到任务并确认
|
||||
CLI ◄── { id, data: { type, sessionId } } ── RCS
|
||||
CLI ──POST /v1/environments/:id/work/:workId/ack──► RCS
|
||||
|
||||
8. 建立会话连接
|
||||
CLI ──WebSocket /v1/session_ingress──► RCS
|
||||
（或使用 V2 的 SSE + HTTP POST）
|
||||
|
||||
9. 双向通信
|
||||
CLI ──消息/工具调用结果──► RCS ──► Browser
|
||||
CLI ◄──权限审批/指令───── RCS ◄──── Browser
|
||||
CLI ──automation_state / task_state──► RCS ──► Browser
|
||||
|
||||
10. 心跳保活（每 20 秒）
|
||||
CLI ──POST /v1/environments/:id/work/:workId/heartbeat──► RCS
|
||||
|
||||
11. 任务完成 → 归档会话 → 注销环境
|
||||
```
|
||||
|
||||
## 故障排查
|
||||
|
||||
### Web UI 看不到当前 Autopilot 状态
|
||||
|
||||
- `standby`：proactive 已开启，正在等待下一个 tick
|
||||
- `sleeping`：模型正在 `SleepTool` 等待窗口中
|
||||
|
||||
这两个状态通过 worker `external_metadata.automation_state` 上报。如果页面只显示普通 working spinner，优先检查 CLI 和 RCS 之间的 worker metadata PUT 是否成功。
|
||||
|
||||
### CLI 无法连接
|
||||
|
||||
```
|
||||
Error: Remote Control is not available in this build.
|
||||
```
|
||||
|
||||
**原因**：`BRIDGE_MODE` feature flag 未启用。
|
||||
|
||||
**解决**：使用 dev 模式（默认启用）或确保构建时包含 `BRIDGE_MODE` flag。
|
||||
|
||||
### 认证失败 (401)
|
||||
|
||||
```
|
||||
Error: Unauthorized
|
||||
```
|
||||
|
||||
**检查项**：
|
||||
1. `CLAUDE_BRIDGE_OAUTH_TOKEN` 是否与 `RCS_API_KEYS` 中的值匹配
|
||||
2. API Key 是否包含多余的空格或换行
|
||||
3. 两个环境变量是否都已正确设置
|
||||
|
||||
### WebSocket 连接中断
|
||||
|
||||
**检查项**：
|
||||
1. 如果使用反向代理，确认已正确配置 WebSocket 升级（`Upgrade` / `Connection` 头）
|
||||
2. 代理的 `proxy_read_timeout` 是否足够大（建议 86400 秒）
|
||||
3. 网络防火墙是否允许 WebSocket 流量
|
||||
|
||||
### 健康检查
|
||||
|
||||
```bash
|
||||
curl https://rcs.example.com/health
|
||||
# 预期: {"status":"ok","version":"0.1.0"}
|
||||
```
|
||||
|
||||
## 限制与注意事项
|
||||
|
||||
| 项目 | 说明 |
|
||||
|------|------|
|
||||
| 存储 | 纯内存存储（Map），服务器重启后所有会话和环境数据丢失 |
|
||||
| 扩展 | 不支持水平扩展（无共享状态），单实例部署 |
|
||||
| 并发 | 适合中小规模使用，大量并发会话可能需要性能调优 |
|
||||
| 数据持久化 | `/app/data` 卷已预留但当前未使用，未来可能用于持久化 |
|
||||
| Web UI 认证 | 基于 UUID，无用户账户系统，适合受信任网络环境 |
|
||||
|
||||
## 与云端模式对比
|
||||
|
||||
| 特性 | 云端 (Anthropic CCR) | 自托管 (RCS) |
|
||||
|------|---------------------|--------------|
|
||||
| 认证方式 | claude.ai OAuth 订阅 | API Key |
|
||||
| GrowthBook 门控 | 需要 `tengu_ccr_bridge` 通过 | 自动跳过 |
|
||||
| 功能标志 | 需要 `BRIDGE_MODE=1` | 同样需要 |
|
||||
| 部署位置 | Anthropic 云端 | 用户自有服务器 |
|
||||
| 数据流经 | Anthropic 基础设施 | 用户私有网络 |
|
||||
| 依赖 | claude.ai 订阅 + OAuth | 仅需 API Key |
|
||||
|
||||
自托管模式的核心优势是：设置 `CLAUDE_BRIDGE_BASE_URL` 后，代码自动调用 `isSelfHostedBridge()` 返回 `true`，跳过所有 GrowthBook 和订阅检查，无需 claude.ai 账户即可使用。
|
||||
Reference in New Issue
Block a user