@haowei0520/acp-connector
v0.17.1
Published
Single-WebSocket ACP connector: connects local ACP stdio agents (opencode, claude code) to AgentNexus over /ws/acp.
Maintainers
Readme
@haowei0520/acp-connector
语言: English | 中文
在本地运行 ACP stdio Agent(OpenCode、Claude Code 或任意 Agent Client Protocol
Agent),通过单一 /ws/acp WebSocket 接入 AgentNexus 服务端。控制帧与更新
流共用一条连接,不再有独立的 control/data 通道。
适用于 AgentNexus 部署在服务器上、而 ACP Agent 必须运行在开发者工作站、私有 机器或其他能访问本地凭据与项目文件的环境中的场景。
核心能力:
| 领域 | 行为 |
| --- | --- |
| 传输 | 每账号一条经认证的 /ws/acp WebSocket(?token=…&boot=…),自动重连(抖动退避),断线期间帧按序排队、重连后补发。服务端连续拒绝握手(HTTP 4xx,如 bot token 失效)达到预算(默认 10 次)后停止重连,状态页显示 handshake_rejected;网络故障与 5xx 响应不计入,会一直重试。 |
| 会话 | 后端用进程级 boot id 协商续聊:本进程无法应答的会话轮换为 session/new,绝不加载过期会话。 |
| MCP 工具 | 本地反向代理为每个回合提供独立端点(/mcp/{turnToken});身份来自 URL 而非猜测——无法确定归属的工具调用会被拒绝。 |
| 入站文件 | 后端下发附件引用,由经授权的 Core MCP 工具读取内容;Connector 不再暂存下载。 |
| 委托 | 回合的 delegate token 作为尽力而为的旁路激活/释放;失败只推迟 MCP 可用性,绝不阻塞 ACP 帧。 |
| 运维 | 支持前台运行与命名守护进程模式(本地日志与状态命令)。 |
大模型 Token 计量
配置 llmUpstreamBaseUrl,并将 Agent 的模型请求路由到 Connector 的 /llm
入口后,0.12.4 会随 usage 上报可选的 cache_read_input_tokens(缓存读取)和
cache_creation_input_tokens(缓存写入)。Backend schema revision 81 将其保存到
每次调用的 usage_events,并汇总到用户回合的 usage_ledger;个人及管理员账单
API 都返回这两个字段。以上是本次源码版本,不代表已经发布或部署。
OpenAI Chat Completions 的 prompt_tokens 已包含缓存输入,其
prompt_tokens_details.cached_tokens 是缓存读取细分;Anthropic Messages 的
input_tokens 不包含缓存读写,因此 Connector 将三项相加一次,统一为总输入。
支持 JSON 和 SSE;Anthropic 初始 usage 与后续累计输出合并,不逐帧累加。
历史数据、旧 Connector 或上游未返回的维度保留未知(数据库 NULL),明确返回
的 0 保存为 0。只有回合中每条已收到的调用都报告该维度,回合汇总才给出数值。
缓存属于总输入的细分,不再重复叠加。积分仍按配置的输入/输出单价计算;缓存
独立定价及计量通知丢失后的可靠补账不在本次修改范围内。
配置
{
"accounts": {
"opencode-main": {
"botToken": "agb_xxx",
"acpUrl": "wss://agentnexus.example.com/ws/acp",
"agent": {
"transport": "stdio",
"command": "opencode",
"args": ["acp", "--cwd", "/Users/me/project"],
"cwd": "/Users/me/project",
"clickTheRequest": { "mode": "ask", "responder": "owner_or_requester" },
"env": {
"OPENCODE_CONFIG_CONTENT": "$OPENCODE_CONFIG_CONTENT"
}
}
}
}
}| 字段 | 默认值 | 说明 |
| --- | --- | --- |
| botToken | 必填 | Bot 凭据;用于 WS query token 与 API 调用。 |
| acpUrl | 必填 | ws(s)://host/ws/acp。0.1.x 的 controlUrl/dataUrl 会被拒绝——这些端点在服务端从未存在。 |
| httpBaseUrl | 由 acpUrl 推导 | MCP/委托/文件调用的 HTTP base。 |
| mcpUrl | ${httpBaseUrl}/api/v1/mcp | 本地代理的上游 MCP 端点。 |
| localMcpPort | 28888 | 本地 MCP 反向代理端口(只绑 127.0.0.1)。 |
| maxSessionProcesses | capacity,否则 10 | 常驻 Session 子进程上限,并作为连接并发容量通告;另有一个控制进程。满载时拒绝新建,不杀活动任务。 |
| sessionIdleTimeoutMs | 300000 | 空闲回收时间;通过 resume/load 恢复原会话,长时间无输出的活动 prompt 不回收。 |
| agent.requestTimeoutMs | 120000 | 本地准备超时回退值,范围 1–3,600,000ms;Backend 随请求下发的预算优先。覆盖资源分配、初始化、恢复和配置;prompt 转发后解除。 |
| perSessionMcp | true | 在 session/new/session/load 中通告每回合独立 MCP 端点。 |
| promptKeepaliveMs | 2000 | 回合流式期间的 agent 思考保活(解除后端流空闲看门狗)。0 关闭。 |
| pingIntervalMs | 15000 | WS ping 心跳。 |
| handshakeFailureMaxAttempts | 10 | 连续 HTTP 4xx 握手被拒的容忍次数,超过后 connector 停止重连(状态页显示 handshake_rejected)。0 表示永不放弃。修好 token 后用状态页「立即重连」或重启守护进程恢复。 |
agentnexus-acp-connector --config ./agentnexus-acp.jsonConnector 0.15.1 通告 setupTimeoutV1。配套 Core/Bot 将 Bot 页面保存的
Request timeout(5–3,600 秒)传到执行请求;未配置时使用
ACP_SESSION_SETUP_TIMEOUT_SECONDS(默认 120 秒)。每条准备 RPC 的预算包含
内部冷恢复,不在初始化、恢复、配置之间重新计时。无 Backend 预算的发现/准备请求
使用上述本地回退值。过期或取消会移除排队请求并忽略迟到响应;已发出的配置不能据此
宣称撤销,取消也不证明远端执行已停止。消除旧的两层限制需要配套升级 Core/Bot 和
Connector。旧 promptTimeoutMs 字段不在当前承载运行时启用总执行期限;执行限时仍需显式配置。
Pi 默认预设
connect --agent pi 使用 @openma/pi-acp(命令 openma-pi-acp),交互安装固定为
0.1.8。需要 Node.js 22.19 或更高版本:
npm install -g @openma/[email protected]此适配器按会话接收 ACP 注入的 HTTP / stdio MCP。Connector 自动提供 AgentNexus
端点和凭据,无需修改共享 mcp.json。此预设不支持旧式 SSE。
已有账号保留原来的启动命令。迁移时先备份配置,把对应账号的 agent.command
改为 openma-pi-acp、agent.args 改为 [],保留其他设置,再重启对应 Connector
并新建会话。自定义适配器仍可通过 --agent-cmd <command> 接入。
安装固定版本适配器后,可在此包目录运行 npm run test:pi,或通过
PI_ACP_BIN=/path/to/openma-pi-acp 指向临时安装。此可选本地合同测试使用真实适配器、
Connector relay、会话进程池和 MCP 代理,模型与上游 MCP 为确定性的回环服务。
覆盖双会话并发、工具发现/调用/结果返回、下一任务凭据和无共享 mcp.json 写入。
测试使用临时 Pi 配置,无需外部模型账号,不代表 Kubernetes 或生产环境验收。
本地接入流程
- 在 AgentNexus 中创建 Agent Bridge Bot(系统管理 → Agent 桥接,或用个人令牌
调
POST /api/v1/bots),复制页面给出的配置片段;它已指向/ws/acp。 - 保存为本地 JSON 文件,按需调整
agent部分(命令、工作区、环境变量)。 - 在运行 Agent 的机器上启动 connector:
agentnexus-acp-connector start --config ./agentnexus-acp.json --name opencode-main- 在 AgentNexus 中把 Bot 拉入频道或私聊,发送
@opencode-main hello。
npm CLI 与守护进程
npm install -g @haowei0520/acp-connector
agentnexus-acp-connector start --config ./agentnexus-acp.json --name opencode-main
agentnexus-acp-connector status --name opencode-main
agentnexus-acp-connector logs --name opencode-main --lines 200
agentnexus-acp-connector restart --name opencode-main
agentnexus-acp-connector stop --name opencode-main守护进程元数据与日志位于 ~/.agentnexus/acp-connector/<name>/(可用 --home
或 AGENTNEXUS_ACP_HOME 覆盖)。
一个回合的完整流程
- 后端发送
session/new/session/load,_meta.agentnexus携带调度上下文 (频道、任务、turn token、delegate token)。 - relay 剥离
_meta,通告本回合的本地 MCP 端点 (http://127.0.0.1:{port}/mcp/{turnToken}),并登记身份。 session/prompt到达:文本(当回合已委托授权且 Agent 声明了对应 prompt 能力时,还带附件引用列表)。relay 预置[Context: channel_id=…, task_id=…]指令,把拉取到的附件落盘为resource_link块,再转发给 Agent。- Agent 的
session/update流按 chunk 透传;终结agent_message会被改写为agent_message_chunk(后端把终结 ACP 响应分类为回合结果)。 ping探测在本地应答。Agent 发起的session/request_permission使用 worker 隔离的 ID 转发到后端;WebSocket 离线时在本地取消。Session 错误结束 当前 Task,不自动重放 prompt 或工具副作用。- 取消全走标准 ACP:后端自行将消息解析为
session/cancel,连接器仅做 session id 双向映射后转发,不再有自定义取消帧。
从 0.1.x 迁移
- 把
controlUrl/dataUrl换成单一acpUrl(wss://host/ws/acp)。携带旧键 的配置会立即报错并指明改法,而不是对着 404 永久重连。 - 本地会话状态文件(
statePath)已移除;WS query 中的 boot id 取代之。 @haowei0520/bridge-client已退役,不再是依赖。
发布
发布从 develop 最终提交手工执行:包版本随代码同一变更集内升级,合并到
develop 后在该提交上打注解 tag,再基于同一棵树发布产物:
git tag -a agentnexus-acp-connector-v0.2.0 -m "agentnexus-acp-connector v0.2.0"
git push origin agentnexus-acp-connector-v0.2.0
npm publish --access public
# 构建并推送容器化 runtime:
# harbor.epichust.com/ai/agentnexus-opencode-bot:<version>tag 必须与 package.json 完全一致(agentnexus-acp-connector-v<version>)。
升级至 0.12.0
升级前先等待当前任务结束。每个常驻 ACP Session 使用独立 Agent 进程,
保留原业务 cwd;MCP 注册名固定为 agentnexus,地址在 Session 生命周期内固定。存活 Session 每轮直接 prompt,不再 resume/load;
Shadow 在收到 HTTP 请求时固定当前 Task 凭据,私有元数据在转给 Agent 前删除。
平台 Token 保存在 Connector,不放入模型提示词。已进入 Shadow 的请求固定旧身份;用户已接受尚未抵达的旧调用按抵达时当前轮次授权。
跨 Session 独立入口与上下文,空闲时拒绝工具调用。
每次模型请求只有一份 MCP 工具定义与说明,不随历史 Task 或其他 Session 累积。 模型 API 仍可能要求每次携带 schema 并计费;不承诺整个会话只计一次 token。 容量默认 10 个 Session 子进程,另有控制进程,需评估内存。空闲进程回收后仅通过 resume/load 恢复会话,不重跑失败任务;Agent 不支持恢复时会明确失败。 初始化 401/403 返回明确鉴权错误,不包装为可重试的普通代理故障。
npm run test:opencode 使用真实 OpenCode 和本地模型/Core 替身验证线协议,
不调用外部模型,不代表已通过 Kubernetes/UAT 端到端验收。
OpenCode 的控制进程与各 Session 使用独立 OPENCODE_DB 文件,避免首次 WAL 初始化锁竞争;
原业务 cwd、配置及账户凭据目录保留。此运行期覆盖也适用于包装命令,优先于用户提供的
共享 OPENCODE_DB。数据库位于账户私有临时目录,空闲恢复保留,正常停止 Connector 后删除。
Session 元数据上限 4,096;工具目录变更需新建 Session,每次调用仍由 Core 检查实时权限。
clickTheRequest 以 Core 中由 Bot Owner 管理的设置为准。本地配置与旧标量别名仅兼容读取,不会授予审批权限或覆盖平台策略;需要无人值守时,请在 Bot 设置中明确选择自动策略。默认询问当前有频道访问权的 Owner 或原始任务发起人。
