vault backup: 2026-06-09 23:15:17
This commit is contained in:
@@ -1,12 +1,20 @@
|
||||
---
|
||||
tags: [acp, websocket, proxy, claude-code, remote]
|
||||
create time: 2026-06-09 22:30
|
||||
---
|
||||
|
||||
# acp-link — ACP 代理服务器
|
||||
|
||||
## 概述
|
||||
|
||||
`acp-link` 是一个 ACP 代理服务器，将 WebSocket 客户端桥接到 ACP agent 的 stdio 接口。它让 ACP agent（如 Claude Code）可以通过 WebSocket 远程访问，而不仅限于本地 stdio。
|
||||
|
||||
> [!info]
|
||||
> 源码目录：`packages/acp-link/`
|
||||
> PR: #292
|
||||
> 新增时间：2026-04-18
|
||||
|
||||
## 一、功能概述
|
||||
|
||||
`acp-link` 是一个 ACP (Agent Client Protocol) 代理服务器，将 WebSocket 客户端桥接到 ACP agent 的 stdio 接口。它让 ACP agent（如 Claude Code）可以通过 WebSocket 远程访问，而不仅限于本地 stdio。
|
||||
## 正文
|
||||
|
||||
### 核心特性
|
||||
|
||||
@@ -17,27 +25,25 @@
|
||||
- **HTTPS 支持**：内置自签名证书生成，支持安全连接
|
||||
- **Token 认证**：自动生成或通过环境变量配置认证 token
|
||||
|
||||
## 二、架构
|
||||
### 架构
|
||||
|
||||
### 独立模式
|
||||
#### 独立模式
|
||||
|
||||
```
|
||||
┌──────────────────┐ WebSocket ┌──────────────────┐ stdio/NDJSON ┌──────────────┐
|
||||
│ 浏览器/客户端 │ ◄──────────────►│ acp-link │ ◄────────────────►│ ACP Agent │
|
||||
│ (WS Client) │ ws://host:port │ (Proxy Server) │ spawn subprocess │ (Claude等) │
|
||||
└──────────────────┘ └──────────────────┘ └──────────────┘
|
||||
```mermaid
|
||||
graph LR
|
||||
A["浏览器/客户端 WS Client"] -->|"ws://host:port WebSocket"| B["acp-link Proxy Server"]
|
||||
B -->|"spawn subprocess stdio/NDJSON"| C["ACP Agent Claude等"]
|
||||
```
|
||||
|
||||
### RCS 集成模式
|
||||
#### RCS 集成模式
|
||||
|
||||
```
|
||||
┌──────────────┐ WebSocket ┌──────────────────┐ stdio/NDJSON ┌──────────────┐
|
||||
│ RCS Web UI │ ◄──────────────►│ Remote Control │ ◄─────────────────►│ acp-link │
|
||||
│ (/code/*) │ ACP Relay WS │ Server (RCS) │ ACP events │ + Agent │
|
||||
└──────────────┘ └──────────────────┘ └──────────────┘
|
||||
```mermaid
|
||||
graph LR
|
||||
A["RCS Web UI /code/*"] -->|"ACP Relay WS WebSocket"| B["Remote Control Server RCS"]
|
||||
B -->|"ACP events stdio/NDJSON"| C["acp-link + Agent"]
|
||||
```
|
||||
|
||||
### 文件结构
|
||||
#### 文件结构
|
||||
|
||||
```
|
||||
packages/acp-link/
|
||||
@@ -57,9 +63,9 @@ packages/acp-link/
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
## 三、安装与使用
|
||||
### 安装与使用
|
||||
|
||||
### 基本用法
|
||||
#### 基本用法
|
||||
|
||||
```bash
|
||||
# 直接运行（在 monorepo 中）
|
||||
@@ -76,7 +82,7 @@ acp-link --https ccb-bun -- --acp
|
||||
acp-link --debug ccb-bun -- --acp
|
||||
```
|
||||
|
||||
### CLI 参考
|
||||
#### CLI 参考
|
||||
|
||||
```
|
||||
USAGE
|
||||
@@ -97,7 +103,7 @@ ARGUMENTS
|
||||
command... Agent command followed by its arguments (e.g. "ccb-bun -- --acp")
|
||||
```
|
||||
|
||||
## 四、认证
|
||||
### 认证
|
||||
|
||||
默认启动时自动生成随机 token。客户端连接时不要把 token 放在 URL 中：
|
||||
|
||||
@@ -105,8 +111,8 @@ ARGUMENTS
|
||||
ws://localhost:9315/ws
|
||||
```
|
||||
|
||||
无法发送 `Authorization` header 的 WebSocket 客户端需要使用
|
||||
`rcs.auth.<base64url-token>` 子协议传递 token。
|
||||
> [!warning]
|
||||
> 无法发送 `Authorization` header 的 WebSocket 客户端需要使用 `rcs.auth.<base64url-token>` 子协议传递 token。
|
||||
|
||||
配置固定 token：
|
||||
|
||||
@@ -120,11 +126,11 @@ ACP_AUTH_TOKEN=my-fixed-token acp-link ccb-bun -- --acp
|
||||
acp-link --no-auth ccb-bun -- --acp
|
||||
```
|
||||
|
||||
## 五、RCS 集成
|
||||
### RCS 集成
|
||||
|
||||
acp-link 支持将 ACP agent 注册到 Remote Control Server，通过 Web UI 远程操控。
|
||||
|
||||
### 连接方式
|
||||
#### 连接方式
|
||||
|
||||
```bash
|
||||
# 通过环境变量配置 RCS 连接
|
||||
@@ -133,35 +139,35 @@ ACP_RCS_TOKEN=sk-rcs-your-key \
|
||||
acp-link ccb-bun -- --acp
|
||||
```
|
||||
|
||||
### 注册流程（两步）
|
||||
#### 注册流程（两步）
|
||||
|
||||
1. **REST 注册**：通过 `POST /v1/environments/bridge` 向 RCS 注册环境
|
||||
2. **WS identify**：建立 WebSocket 连接后发送 `identify` 消息（携带 agentId），替代完整 `register`
|
||||
|
||||
RCS 的 ACP WebSocket 连接不接受 URL query token。acp-link 会通过
|
||||
`rcs.auth.<base64url-token>` WebSocket 子协议发送 `ACP_RCS_TOKEN`。
|
||||
> [!warning]
|
||||
> RCS 的 ACP WebSocket 连接不接受 URL query token。acp-link 会通过 `rcs.auth.<base64url-token>` WebSocket 子协议发送 `ACP_RCS_TOKEN`。
|
||||
|
||||
```
|
||||
acp-link RCS
|
||||
│ │
|
||||
│── POST /v1/environments/bridge ──►│ (REST 注册)
|
||||
│◄── { agentId, sessionId } ───────│
|
||||
│ │
|
||||
│── WS connect ─────────────────►│ (WebSocket)
|
||||
│── identify { agentId } ────────►│ (WS 标识)
|
||||
│◄── identified ─────────────────│
|
||||
│ │
|
||||
│── ACP events ─────────────────►│ (双向消息转发)
|
||||
│◄── user prompts/permissions ───│
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant AL as acp-link
|
||||
participant RCS as RCS
|
||||
AL->>RCS: POST /v1/environments/bridge (REST 注册)
|
||||
RCS-->>AL: { agentId, sessionId }
|
||||
AL->>RCS: WS connect (WebSocket)
|
||||
AL->>RCS: identify { agentId } (WS 标识)
|
||||
RCS-->>AL: identified
|
||||
AL->>RCS: ACP events (双向消息转发)
|
||||
RCS-->>AL: user prompts/permissions
|
||||
```
|
||||
|
||||
## 六、权限模式
|
||||
### 权限模式
|
||||
|
||||
### permissionMode 传递链
|
||||
#### permissionMode 传递链
|
||||
|
||||
权限模式通过整条链路传递：Web UI → RCS → acp-link → ACP agent。
|
||||
|
||||
支持的权限模式：
|
||||
|
||||
- `default` — 每次请求权限确认
|
||||
- `auto` — 自动判断
|
||||
- `acceptEdits` — 自动接受编辑
|
||||
@@ -169,13 +175,11 @@ acp-link RCS
|
||||
- `dontAsk` — 不询问
|
||||
- `bypassPermissions` — 绕过权限（需 sandbox 环境）
|
||||
|
||||
### fallback 链
|
||||
#### fallback 链
|
||||
|
||||
当客户端未显式传递 permissionMode 时，使用以下 fallback 链：
|
||||
|
||||
```
|
||||
客户端传值 > config.permissionMode > ACP_PERMISSION_MODE 环境变量
|
||||
```
|
||||
> 客户端传值 > config.permissionMode > ACP_PERMISSION_MODE 环境变量
|
||||
|
||||
示例：
|
||||
|
||||
@@ -183,21 +187,21 @@ acp-link RCS
|
||||
ACP_PERMISSION_MODE=auto acp-link ccb-bun -- --acp
|
||||
```
|
||||
|
||||
## 七、权限管道（2026-04-18 改进）
|
||||
### 权限管道（2026-04-18 改进）
|
||||
|
||||
### 模式同步
|
||||
#### 模式同步
|
||||
|
||||
`applySessionMode` 在 agent 切换权限模式时同步 `appState.toolPermissionContext.mode`，确保内部权限上下文与 ACP 客户端状态一致。
|
||||
|
||||
### 统一权限流水线
|
||||
#### 统一权限流水线
|
||||
|
||||
`createAcpCanUseTool` 接入 `hasPermissionsToUseTool` 统一权限流水线，替代原来分散的处理逻辑。支持 `onModeChange` 回调，模式变更时实时同步。
|
||||
|
||||
### bypass 检测
|
||||
#### bypass 检测
|
||||
|
||||
`bypassPermissions` 模式增加可用性检测 — 仅在非 root 或 sandbox 环境中允许启用，防止权限绕过的安全风险。
|
||||
|
||||
## 八、环境变量
|
||||
### 环境变量
|
||||
|
||||
| 变量 | 说明 |
|
||||
|------|------|
|
||||
@@ -205,3 +209,9 @@ ACP_PERMISSION_MODE=auto acp-link ccb-bun -- --acp
|
||||
| `ACP_PERMISSION_MODE` | 默认权限模式 fallback |
|
||||
| `ACP_RCS_URL` | RCS 服务器地址（启用 RCS 集成） |
|
||||
| `ACP_RCS_TOKEN` | RCS API token |
|
||||
|
||||
## 关联笔记
|
||||
|
||||
- [[acp-zed]]
|
||||
- [[remote-control-self-hosting]]
|
||||
- [[bridge-mode]]
|
||||
|
||||
Reference in New Issue
Block a user