11 KiB
ACP Remote / Agent adapter 技术说明
本文记录 Remote 内通用 Agent ACP gateway(#65)与 Cursor backend adapter 的边界。 线协议以 Remote Protocol v1 为准。
定位
Host Plugin 提供 backend-neutral 的 Agent ACP gateway:
ACP Client
-> 已认证 Remote channel(agent.acp.*)
-> Host ACP gateway
-> Cursor `agent acp` adapter(本阶段)
- 公共 capability / RPC:
agent.acp.v1、agent.acp.* - Host 配置键
cursor.enabled/cursor.binary只控制 Cursor adapter,不是线协议名 - 按 Remote connection 隔离;编译期固定 allowlist;未授权 method fail closed
- 现有
codex.app.*保持不变;暂不把 Codex 迁到 ACP adapter
启动与后端配置
acp.enabled 控制 gateway;acp.backends 内各后端独立使用 enabled、command、args、
可选 cwd。当前支持 cursor / antigravity / pi / opencode / claude,不按 binary 名称推测 adapter,也不把不可用后端的
请求转发到其他后端。仅配置旧 cursor 字段时,只启用 Cursor。
对于 opencode,Host 运行 opencode acp 子进程接入标准 ACP 协议,采用标准 initialize 握手(避免发送 Cursor 私有 cursor_login 鉴权方法)。默认优先探测官方安装位置的 ~/.opencode/bin/opencode、~/.local/bin/opencode 及系统 PATH。独立 capability 声明为 agent.acp.opencode.v1。工作区目录来自标准 session/list 返回的 cwd,历史通过独立临时进程的 session/load 回放生成,不写入 Harness SessionStore。
启动前通过同一命令的 --help 检测参数能力,不硬编码主版本号。仅当 CLI 同时声明
--hostname、--port、--mdns 时追加私有 loopback 参数并启用原生归档;三者均不支持时
移除这些旧网络参数,仅通过 stdio ACP 工作。检测失败、输出超限或仅支持部分参数时显式
返回 OPENCODE_CLI_PROBE_FAILED,不猜测监听地址或盲目重试另一套参数;关闭后端会取消检测。
官方 v1 使用 npm opencode-ai,v2 使用 @opencode/cli。已分别以真实 1.19.3 / 2.0.32
验证 Host 本地 ACP 主流程;v2 的内部私有服务不开放网络端口,详见
官方 ACP 文档。这不等同于跨设备或 Prompt 验收。
Cursor/Claude 的 Desktop/Android 模型选择读取真实会话 catalog,并等待上游确认。Cursor 为避免进程级模型设置串会话,每个活动会话使用独立进程。Claude 显示名统一为 Claude,工作区与历史投影见 接入说明。
ACP 在后台启动,各后端独立初始化,不阻塞 Harness Remote 注册和 Client 初始化。
能力声明表示已启用的协议支持,workspaceTypes.available 表示实际就绪;关闭期间会清理
正在启动的 CLI,迟到的初始化结果不得重新注册实例。后端配置保存后立即生效,仅更新发生变化的后端。
设置页根据 Host 上配置的命令及运行时支持的候选位置检测后端是否可发现。
检测不可用时工作区开关显示关闭并禁用;手动检测失败会保存该后端的关闭状态,
并立即更新 Host 运行时,适用于 Cursor、AGY、CodeX 和自定义 ACP 条目。
重新检测通过后可以手动开启,不自动恢复为开启。命令可发现不代表已登录或协议就绪,
真实 Remote 可用性仍以 workspaceTypes.available 为准。
AGY 会话发现按数据库中的 file URI 解码后与项目目录完整匹配,支持编码目录名和 原生路径分隔符。指定目录缺少数据库归属信息时返回空列表,不把所有 transcript 推测为该目录的会话。历史读取限制在 AGY brain 内的真实 transcript,拒绝越界 ID 和符号链接。切换会话后,客户端丢弃迟到的历史与订阅结果。
公共方法(allowlist)
| 方法 | 用途 |
|---|---|
initialize |
Gateway 返回能力描述(不转发 Cursor 私有 initialize) |
session/new |
在 Host 上已存在的绝对目录创建会话(强制 mcpServers: []) |
session/load |
恢复会话 |
session/prompt |
Cursor 文本 Prompt;AGY 文本/受限图片 Prompt |
session/cancel |
中断 |
dsh/directoryList |
Host 只读单层目录浏览(选 cwd;Remote 扩展) |
dsh/workspaceList |
指定后端的 Host 工作区发现 |
dsh/sessionList |
AGY 持久化会话发现 |
dsh/sessionHistory |
历史读取(有界 ACP transfer) |
dsh/sessionArchive |
OpenCode 原生归档;要求独立 capability |
线 RPC:agent.acp.call|respond|stream.*|transfer.*
事件:agent.acp.frame / agent.acp.stream.closed / agent.acp.catalog.changed
OpenCode 原生归档
Desktop/Android 的 OpenCode 归档经 dsh/sessionArchive 直接调用同一个 Host
opencode acp 进程的原生 HTTP API,设置 time.archived,原生确认后才移除默认目录成员。
Host 声明 agent.acp.opencode.archive.v1,成功后以 agent.acp.catalog.changed 同步其他连接。
归档状态由 OpenCode 持久保存,Host 重启后仍隐藏;历史保留可读。活动回复、加载、模型写入和
待审批时拒绝归档,不隐式停止或删除会话。其他 ACP 后端尚无原生归档,不返回本地伪成功。
纯 stdio ACP 构建没有可用的私有 HTTP API 时返回 OPENCODE_ARCHIVE_UNAVAILABLE,
会话列表与历史直接使用标准 ACP,不尝试访问未启动的 HTTP 端口。
当前不提供恢复或已归档列表;实现和上游版本边界见原生归档设计。
Web 兼容边界
共享浏览器投影接收标准 session_info_update.title。OpenCode 的标题生成独立于回复,
V2 ACP 未必转发原生 rename,因此回复后以有界重试在二十秒内恢复列表标题;关闭投影
取消重读。New session - <ISO 时间> / Child session - <ISO 时间> 视为占位,
原生标题缺失时仅在内存中使用首条提问前 60 个字符,打开历史时同样恢复;后续正式标题
可替换临时标题,但占位、迟到读取不能覆盖较新的投影,手动改名优先。不写 OpenCode
或 Harness 数据库。独立 Remote Web 需同步该投影后部署,不能视为线上已生效。
Web、Desktop 和 Android 共用独立 agent.acp.* RPC / stream / transfer / event。
dsh/ 扩展只存在于 ACP call 内,不注册到 Harness 或 Codex 业务 API。
virtual-harness.ts 是可在浏览器使用的内存 UI 投影,不读取本机 AGY 文件;工作区和历史
由 Host ACP 返回。AGY 工作区仅接受 antigravity:cwd: ID,不兼容旧 cursor:cwd: ID
或无前缀路径。Cursor / AGY 分别需 agent.acp.cursor.v1 / agent.acp.antigravity.v1;
agent.acp.v1 仅表示公共数据面,不据此推断后端。不提供早期 ACP 配置或工作区 ID 的迁移;该限制不表示 ACP 尚未实现或发布。
独立 Remote Web runtime 的接入和跨设备 E2E 仍待在独立 Server 仓库验证。
配置
Cursor adapter 默认关闭。开启前请在 Host 本机完成 agent login,或配置
CURSOR_API_KEY。也可在 Desktop 插件设置中切换开关(立即生效)。
ds-harness-remote:
cursor:
enabled: true
binary: agent # 或 ~/.local/bin/agent 的绝对路径
实现入口
| 路径 | 作用 |
|---|---|
packages/plugin/src/acp/gateway.ts |
ACP gateway / 会话归属 / 审批 |
packages/plugin/src/acp/method-policy.ts |
公共 allowlist |
packages/plugin/src/acp/peer-bridge.ts |
每连接 stream / transfer |
packages/plugin/src/acp/adapter.ts |
backend adapter 契约 |
packages/plugin/src/acp/adapters/cursor-process.ts |
Cursor agent acp stdio |
packages/plugin/src/acp/adapters/cursor.ts |
Cursor adapter 工厂 |
packages/plugin/src/acp/adapters/opencode-process.ts |
OpenCode opencode acp stdio |
packages/plugin/src/acp/adapters/opencode.ts |
OpenCode adapter 工厂 |
packages/plugin/src/acp/virtual-harness.ts |
Desktop Virtual Harness(cwd → Workspace / Session / Composer) |
packages/client-core/src/acp-client.ts |
共享 Client(AgentAcpClient) |
packages/plugin/src/client-runtime.ts |
探测独立后端 capability 和就绪状态、打开 Virtual Harness |
packages/plugin/src/client.ts |
Remote 模态框列出 / 添加 Cursor 工作区 |
Desktop 使用
- Host:设置中开启 Agent 后端 → Cursor(
acp.backends的cursor.enabled),完成本机agent login,保存后立即生效。 - Client:侧栏 Remote → 选择在线 Host → 在 Cursor virtual workspace 分组点
+,浏览并确认 Host 上已有绝对目录。 - 打开后复用原生 Workspace / Session / Composer;会话 id 形如
cursor:<acpSessionId>,不写入 DSH SessionStore。
Android Client
内存投影(不写入 SessionStore):
- 探测 Host capability
agent.acp.cursor.v1并确认工作区类型就绪后启用 Cursor 工作区分组。 - 新建 Cursor workspace = 选择 Host 上已有绝对目录;会话经
AgentAcpClient(agent.acp.*)创建与流式更新。 - 文本 Prompt / cancel / approval(
allow-once|reject-once);暂不支持图片。 - Workspace backend id 仍为
'cursor'(仅 UI);线协议为agent.acp.*。
验证状态
- Host gateway、capability、RPC 路由(
agent.acp.v1) - Cursor adapter initialize + authenticate(Host 本地)
- Client
initialize公共面(gateway 短路) - 方法策略单测
- Desktop 设置开关
settings.cursor.set(adapter) - Desktop Virtual Harness(cwd workspace + session/prompt/stream/approval)
- Android Client 投影(
AgentAcpClient/ 内存 Cursor workspace) - Android 真机:文本 Prompt、思考/正文流式帧、
prompt_completedcatch-up、多轮气泡分离 - Desktop ↔ 异机 Client 完整 E2E(审批 / cancel / 长工具轮次)
- 断线重连后 stream 重建与会话内 History 恢复
- Android:重连保留 Cursor 会话并自动重建 ACP stream
session/load与跨设备会话列表体验
近期后续(不含 Codex→ACP)
- Android / Desktop:transport 抖动后自动
stream.open+claimSession - Host 侧按 session 保留可分页的展示用 History(不写 DSH SessionStore)
- 审批 / 提问 UI 与
agent.acp.respond真机矩阵 - 跨机长时间稳定性与 WebRTC/Relay 丢帧回归
Android AGY (2026-10-07)
Android 的 antigravity 工作区独立使用 AGY catalog/history/prompt 与 ACP stream。首次连接
和刷新均发现 Host 既有目录与会话;新建会话保持空白,回复后更新标题,重连重新加载历史并
订阅 stream。图片通过私有 tmp 缓存与有界 ACP transfer;不调用 Harness Prompt 或写入
SessionStore。批量读取列表不触发预热,选中目录才预热。Hermes 打包及真实 AGY 的
in-process 数据链路已验证;Android 真机与加密跨设备验收尚未完成。