feat: ACP 协议版本 remote control #293
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,78 @@ | ||
| # Impeccable Design Context | ||
|
|
||
| ## Users | ||
|
|
||
| **Primary**: Technical teams and enterprises using AI-assisted coding in production workflows. | ||
| - DevOps engineers managing remote agents via RCS dashboard | ||
| - Development teams collaborating through shared sessions | ||
| - Individual developers using terminal CLI daily | ||
|
|
||
| **Context**: Used during focused work sessions — debugging, code review, agent orchestration. Users are in "get things done" mode, not browsing. They value efficiency but also appreciate warmth and personality. | ||
|
|
||
| **Job to be done**: Make advanced AI coding tools accessible and controllable, especially features that normally require enterprise accounts or Anthropic OAuth. | ||
|
|
||
| ## Brand Personality | ||
|
|
||
| **3 words**: Warm, Considered, Human | ||
|
|
||
| **Voice**: Like a knowledgeable colleague who's genuinely enthusiastic about the craft — not a corporate product manager. Community-first, open, slightly playful. Chinese developer community culture (贴吧/discord 温暖氛围). | ||
|
|
||
| **Emotional goals**: Confidence (this tool is solid), Warmth (this community is welcoming), Delight (small moments of personality make the difference). | ||
|
|
||
| **References**: | ||
| - **Anthropic's own design language** — their clean, considered aesthetic with warm undertones. The terra cotta/burnt orange as a human accent. Lots of breathing room. Typography-forward. | ||
| - **NOT**: Generic AI product (no ChatGPT blue, no gradient text, no "AI slop"). NOT corporate SaaS (no Salesforce-blue dashboards, no enterprise sterility). | ||
|
|
||
| **Anti-references**: Corporate enterprise dashboards, generic AI product pages, anything that looks like it was "designed by committee." | ||
|
|
||
| ## Aesthetic Direction | ||
|
|
||
| **Theme**: Light + Dark dual mode (user/system preference switch) | ||
|
|
||
| **Tone**: Anthropomorphic warmth meets terminal precision. The brand orange (Claude's terra cotta) is the thread that ties everything together — it's the human element in a technical world. | ||
|
|
||
| **Typography**: Clean, considered, with good hierarchy. Terminal-native for CLI; modern web fonts for Web UI (RCS dashboard, docs). Favor readability and personality. | ||
|
|
||
| **Color**: | ||
| - Primary: Claude orange family (`#D77757` / terra cotta) | ||
| - Accent: Warm neutrals tinted toward orange | ||
| - Semantic: Success/Error/Warning following Anthropic's established palette | ||
| - Dark mode: Warm dark surfaces (not cold blue-black) | ||
|
|
||
| **Differentiation**: The CCB brand sits at the intersection of "serious tool" and "community project." It should feel like Anthropic's design principles applied to an open-source context — less corporate polish, more human craft. The mascot "Clawd" and the playful "踩踩背" naming hint at personality that the design should honor. | ||
|
|
||
| **Scope**: All Web UI — RCS control panel, documentation site, landing pages. | ||
|
|
||
| ## Design Principles | ||
|
|
||
| 1. **Considered over clever** — Every design choice should feel intentional, not trendy. If it doesn't serve the user, it doesn't ship. | ||
| 2. **Warmth through subtlety** — Orange tints on neutrals, breathing room in layouts, personality in copy. Not giant emoji or aggressive color. | ||
| 3. **Density with clarity** — Technical users need information density, but not chaos. Every pixel earns its place. | ||
| 4. **Community voice** — The design should feel like it was made by people who use it, not by a distant design team. Slightly rough edges are fine if they're honest. | ||
| 5. **Anthropic's shadow** — When in doubt, follow Anthropic's design instincts — the clean layouts, the generous spacing, the warm color temperature. Then add the community touch. | ||
|
|
||
| ## Existing Design Assets | ||
|
|
||
| ### Brand Colors (from theme system) | ||
| - Claude Orange: `rgb(215,119,87)` / `#D77757` | ||
| - Claude Blue: `rgb(87,105,247)` / `#5769F7` | ||
| - Permission Blue: `rgb(87,105,247)` | ||
| - Auto Accept Violet: `rgb(135,0,255)` | ||
| - Plan Mode Teal: `rgb(0,102,102)` | ||
| - Success: `rgb(78,186,101)` | ||
| - Error: `rgb(255,107,128)` | ||
| - Warning: `rgb(255,193,7)` | ||
|
|
||
| ### Logo | ||
| - CCB text + orange play button icon | ||
| - Dark/Light SVG variants in `docs/logo/` | ||
| - Favicon: Orange circle `#D97706` with white play triangle | ||
|
|
||
| ### Mascot | ||
| - "Clawd" — terminal-art character with multiple poses | ||
| - Theme-aware coloring | ||
|
|
||
| ### Theme System | ||
| - 7 variants: dark, light, dark-ansi, light-ansi, dark-daltonized, light-daltonized, auto | ||
| - 89+ semantic color tokens | ||
| - Full documentation in `packages/@ant/ink/docs/04-theme-system.md` |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,205 @@ | ||
| # acp-link — ACP 代理服务器 | ||
|
|
||
| > 源码目录：`packages/acp-link/` | ||
| > PR: #292 | ||
| > 新增时间：2026-04-18 | ||
|
|
||
| ## 一、功能概述 | ||
|
|
||
| `acp-link` 是一个 ACP (Agent Client Protocol) 代理服务器，将 WebSocket 客户端桥接到 ACP agent 的 stdio 接口。它让 ACP agent（如 Claude Code）可以通过 WebSocket 远程访问，而不仅限于本地 stdio。 | ||
|
|
||
| ### 核心特性 | ||
|
|
||
| - **WebSocket → stdio 桥接**：将浏览器/远程客户端的 WebSocket 连接转换为 ACP agent 的 stdin/stdout NDJSON 流 | ||
| - **会话管理**：创建、加载、恢复、列出、关闭会话 | ||
| - **权限审批流程**：客户端可远程审批 agent 的工具权限请求 | ||
| - **RCS 集成**：可与 Remote Control Server (RCS) 连接，将 ACP agent 注册到 RCS 并通过 Web UI 交互 | ||
| - **HTTPS 支持**：内置自签名证书生成，支持安全连接 | ||
| - **Token 认证**：自动生成或通过环境变量配置认证 token | ||
|
|
||
| ## 二、架构 | ||
|
|
||
| ### 独立模式 | ||
|
|
||
| ``` | ||
| ┌──────────────────┐ WebSocket ┌──────────────────┐ stdio/NDJSON ┌──────────────┐ | ||
| │ 浏览器/客户端 │ ◄──────────────►│ acp-link │ ◄────────────────►│ ACP Agent │ | ||
| │ (WS Client) │ ws://host:port │ (Proxy Server) │ spawn subprocess │ (Claude等) │ | ||
| └──────────────────┘ └──────────────────┘ └──────────────┘ | ||
| ``` | ||
|
|
||
| ### RCS 集成模式 | ||
|
|
||
| ``` | ||
| ┌──────────────┐ WebSocket ┌──────────────────┐ stdio/NDJSON ┌──────────────┐ | ||
| │ RCS Web UI │ ◄──────────────►│ Remote Control │ ◄─────────────────►│ acp-link │ | ||
| │ (/code/*) │ ACP Relay WS │ Server (RCS) │ ACP events │ + Agent │ | ||
| └──────────────┘ └──────────────────┘ └──────────────┘ | ||
| ``` | ||
|
|
||
| ### 文件结构 | ||
|
|
||
| ``` | ||
| packages/acp-link/ | ||
| ├── src/ | ||
| │ ├── server.ts # 主服务器：WS 连接管理、会话管理、权限处理、消息桥接 | ||
| │ ├── rcs-upstream.ts # RCS 上游客户端：REST 注册 + WS identify 两步流程 | ||
| │ ├── cert.ts # TLS 证书生成（自签名） | ||
| │ ├── logger.ts # 日志模块 | ||
| │ ├── types.ts # JSON-RPC 和 ACP 协议类型定义 | ||
| │ ├── cli/ | ||
| │ │ ├── bin.ts # CLI 入口 | ||
| │ │ ├── command.ts # 命令行参数解析 | ||
| │ │ ├── app.ts # 应用启动 | ||
| │ │ └── context.ts # 上下文配置 | ||
| │ └── __tests__/ # 测试（cert, server, types） | ||
| ├── package.json | ||
| └── tsconfig.json | ||
| ``` | ||
|
|
||
| ## 三、安装与使用 | ||
|
|
||
| ### 基本用法 | ||
|
|
||
| ```bash | ||
| # 直接运行（在 monorepo 中） | ||
| # 注意：claude 本身不支持 ACP，需要用 ccb-bun --acp 启动 ACP agent | ||
| bun packages/acp-link/src/cli/bin.ts ccb-bun -- --acp | ||
|
|
||
| # 指定端口和主机 | ||
| acp-link --port 9000 --host 0.0.0.0 ccb-bun -- --acp | ||
|
|
||
| # 启用 HTTPS（自签名证书） | ||
| acp-link --https ccb-bun -- --acp | ||
|
|
||
| # 调试模式 | ||
| acp-link --debug ccb-bun -- --acp | ||
| ``` | ||
|
|
||
| ### CLI 参考 | ||
|
|
||
| ``` | ||
| USAGE | ||
| acp-link [--port value] [--host value] [--debug] [--no-auth] [--https] <command>... | ||
| acp-link --help | ||
| acp-link --version | ||
|
|
||
| FLAGS | ||
| [--port] Port to listen on [default = 9315] | ||
| [--host] Host to bind to [default = localhost] | ||
| [--debug] Enable debug logging to file | ||
| [--no-auth] Disable authentication (dangerous) | ||
| [--https] Enable HTTPS with self-signed cert | ||
| -h --help Print help information and exit | ||
| -v --version Print version information and exit | ||
|
|
||
| ARGUMENTS | ||
| command... Agent command followed by its arguments (e.g. "ccb-bun -- --acp") | ||
| ``` | ||
|
|
||
| ## 四、认证 | ||
|
|
||
| 默认启动时自动生成随机 token。客户端连接时需通过 query 参数传递： | ||
|
|
||
| ``` | ||
| ws://localhost:9315/ws?token=<your-token> | ||
| ``` | ||
|
|
||
| 配置固定 token： | ||
|
|
||
| ```bash | ||
| ACP_AUTH_TOKEN=my-fixed-token acp-link ccb-bun -- --acp | ||
| ``` | ||
|
|
||
| 禁用认证（不推荐，仅用于开发）： | ||
|
|
||
| ```bash | ||
| acp-link --no-auth ccb-bun -- --acp | ||
| ``` | ||
|
|
||
| ## 五、RCS 集成 | ||
|
|
||
| acp-link 支持将 ACP agent 注册到 Remote Control Server，通过 Web UI 远程操控。 | ||
|
|
||
| ### 连接方式 | ||
|
|
||
| ```bash | ||
| # 通过环境变量配置 RCS 连接 | ||
| ACP_RCS_URL=http://localhost:3000 \ | ||
| ACP_RCS_TOKEN=sk-rcs-your-key \ | ||
| ACP_RCS_NAME=my-agent \ | ||
| acp-link ccb-bun -- --acp | ||
| ``` | ||
|
|
||
| ### 注册流程（两步） | ||
|
|
||
| 1. **REST 注册**：通过 `POST /v1/environments/bridge` 向 RCS 注册环境 | ||
| 2. **WS identify**：建立 WebSocket 连接后发送 `identify` 消息（携带 agentId），替代完整 `register` | ||
|
|
||
| ``` | ||
| acp-link RCS | ||
| │ │ | ||
| │── POST /v1/environments/bridge ──►│ (REST 注册) | ||
| │◄── { agentId, sessionId } ───────│ | ||
| │ │ | ||
| │── WS connect ─────────────────►│ (WebSocket) | ||
| │── identify { agentId } ────────►│ (WS 标识) | ||
| │◄── registered ─────────────────│ | ||
| │ │ | ||
| │── ACP events ─────────────────►│ (双向消息转发) | ||
| │◄── user prompts/permissions ───│ | ||
| ``` | ||
|
|
||
| ## 六、权限模式 | ||
|
|
||
| ### permissionMode 传递链 | ||
|
|
||
| 权限模式通过整条链路传递：Web UI → RCS → acp-link → ACP agent。 | ||
|
|
||
| 支持的权限模式： | ||
| - `default` — 每次请求权限确认 | ||
| - `auto` — 自动判断 | ||
| - `acceptEdits` — 自动接受编辑 | ||
| - `plan` — 规划模式 | ||
| - `dontAsk` — 不询问 | ||
| - `bypassPermissions` — 绕过权限（需 sandbox 环境） | ||
|
|
||
| ### fallback 链 | ||
|
|
||
| 当客户端未显式传递 permissionMode 时，使用以下 fallback 链： | ||
|
|
||
| ``` | ||
| 客户端传值 > config.permissionMode > ACP_PERMISSION_MODE 环境变量 | ||
| ``` | ||
|
|
||
| 示例： | ||
|
|
||
| ```bash | ||
| ACP_PERMISSION_MODE=auto acp-link ccb-bun -- --acp | ||
| ``` | ||
|
|
||
| ## 七、权限管道（2026-04-18 改进） | ||
|
|
||
| ### 模式同步 | ||
|
|
||
| `applySessionMode` 在 agent 切换权限模式时同步 `appState.toolPermissionContext.mode`，确保内部权限上下文与 ACP 客户端状态一致。 | ||
|
|
||
| ### 统一权限流水线 | ||
|
|
||
| `createAcpCanUseTool` 接入 `hasPermissionsToUseTool` 统一权限流水线，替代原来分散的处理逻辑。支持 `onModeChange` 回调，模式变更时实时同步。 | ||
|
|
||
| ### bypass 检测 | ||
|
|
||
| `bypassPermissions` 模式增加可用性检测 — 仅在非 root 或 sandbox 环境中允许启用，防止权限绕过的安全风险。 | ||
|
|
||
| ## 八、环境变量 | ||
|
|
||
| | 变量 | 说明 | | ||
| |------|------| | ||
| | `ACP_AUTH_TOKEN` | 固定认证 token（默认自动生成） | | ||
| | `ACP_PERMISSION_MODE` | 默认权限模式 fallback | | ||
| | `ACP_RCS_URL` | RCS 服务器地址（启用 RCS 集成） | | ||
| | `ACP_RCS_TOKEN` | RCS API token | | ||
| | `ACP_RCS_NAME` | Agent 名称（在 RCS 中显示） | | ||
| | `ACP_RCS_CHANNEL_GROUP` | Channel group ID | | ||
| | `ACP_MAX_SESSIONS` | 最大会话数 | | ||
|
Comment on lines
+24
to
+205
Contributor
There was a problem hiding this comment. 为 fenced code block 补充语言标识 文档里多处代码块未声明语言（如 Line 24、Line 33、Line 42、Line 81、Line 104、Line 139、Line 171），会持续触发 MD040。建议统一补上（ 📝 示例修复（节选）-```
+```text
┌──────────────────┐ WebSocket ┌──────────────────┐ stdio/NDJSON ┌──────────────┐
│ 浏览器/客户端 │ ◄──────────────►│ acp-link │ ◄────────────────►│ ACP Agent │
│ (WS Client) │ ws://host:port │ (Proxy Server) │ spawn subprocess │ (Claude等) │
└──────────────────┘ └──────────────────┘ └──────────────┘- Verify each finding against the current code and only fix it if needed. In |
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
PR 引用号与当前 PR 不一致
Line 4 写的是
PR:#292``，但当前变更来自 PR#293。建议修正，避免后续追溯混淆。🤖 Prompt for AI Agents