从 initialize 到 session/cancelacpx 如何在 stdio 上实现 ACP 协议通信协议实现深度解析【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpxacpx是一个面向Agent Client ProtocolACP的无头 CLI 客户端它把 Claude Code、Codex、Gemini 等编码智能体装进标准输入输出stdio管道用JSON-RPC 2.0完成从initialize握手、session/new建会话、session/prompt对话到session/cancel取消的全流程通信。本文从新手视角拆解这套协议在 stdio 上的实现机制带你读懂它的消息帧、握手协商、流式更新与错误语义。一、acpx 是什么把编码智能体接进命令行ACP 是客户端 ↔ 智能体之间的会话协议。acpx 站在客户端一侧它负责拉起智能体子进程在其stdin/stdout上读写 JSON-RPC 消息并把权限确认、文件读写、终端等回调能力暴露给智能体。一句话概括acpx 不关心模型本身只关心如何在 stdio 上稳定地收发 ACP 消息。核心协议实现集中在 src/acp/ 目录客户端主体逻辑见 src/acp/client.ts。二、消息帧一行一条 JSON 的 NDJSON 约定stdio 是字节流没有天然的消息边界。acpx 采用NDJSON每行一条 JSON来切分消息每收到一个字节块按换行符\n切分未完成的行被暂存拼到下一个块再解析。每条合法消息必须满足jsonrpc: 2.0并被识别为请求、通知或响应三种之一。单条消息默认有64 MB上限可用环境变量ACPX_MAX_ACP_MESSAGE_BYTES调整设为0表示不限制。这套切分与校验逻辑位于 src/acp/ndjson-stream.ts消息类型判定与字段合法性检查见 src/acp/jsonrpc.ts。{jsonrpc:2.0,id:1,method:initialize,params:{...}} {jsonrpc:2.0,id:1,result:{protocolVersion:1,...}}三、握手第一步initialize 协商协议版本连接建立后的第一件事是initialize 握手acpx 声明自己支持的protocolVersion与客户端能力智能体返回其能力集合agentCapabilities随后按需进行鉴权。关键流程见 src/acp/client.tsinitializeAgentConnection负责整条启动链路的编排initializeProtocolConnection发出methods.agent.initialize请求并等待响应握手完成后调用authenticateIfRequired处理鉴权方法。响应里若携带authMethodsacpx 会继续发起authenticate请求完成登录态。四、建会话session/new 与上下文绑定握手通过后acpx 请求一个会话并把工作目录cwd、模型等上下文绑定进去。相关请求见 src/acp/client.tssession.new创建新会话返回会话 ID 与会话能力session.load/session.resume加载或恢复已有会话实现跨命令的有状态体验。会话 ID 是后续所有请求/通知的定位键acpx 会用它维护哪个会话正在跑哪一轮 prompt的内部状态。五、对话轮session/prompt 与流式 session/update一次提问prompt是 ACP 的核心交互。acpx 发出session/prompt请求后智能体在执行过程中会持续推送session/update通知文本块、思考块、计划等最终由原始 prompt 的响应携带stopReason表示结束。发出请求src/acp/client.ts接收session/update通知src/acp/client.ts从响应中解析stopReasonsrc/acp/jsonrpc.ts这种通知流 最终响应收尾的模式让用户在终端里能实时看到智能体的输出而不是等全部算完才一次性返回。六、打断对话session/cancel 的通知式设计session/cancel是一个通知notification而非请求——它没有id也不期望收到独立的 JSON-RPC 响应。真正的取消确认体现在仍在进行的session/prompt最终返回stopReason: cancelled。实现要点见 src/acp/client.ts通过connection.agent.notify(methods.agent.session.cancel, { sessionId })发送用cancellingSessionIds集合做幂等保护避免同一会话被并发重复取消若会话处于空闲状态取消通知发出即可无需等待远端确认。这套语义在一致性规范中被明确约定见 conformance/spec/v1.md。七、错误语义与能力协商acpx 对能力和错误都有严格约定能力协商initialize 阶段声明clientCapabilities如fs、terminal。例如--no-fs、--no-terminal会把对应能力设为false见 docs/CLI.md。错误归一化无效参数应返回 JSON-RPC 错误通常为-32602未知会话 ID 必须显式报错而非静默成功。错误形状与解析见 src/acp/jsonrpc-error.ts 与 src/acp/error-shapes.ts。八、用一致性测试验证协议行为acpx 内置一套Conformance一致性测试用 JSON 描述的用例驱动真实或模拟智能体逐条断言协议行为。规范定义见 conformance/spec/v1.md典型用例包括001-initialize-handshake.json握手与版本协商002-session-new.json会话创建003-prompt-single-turn.json单轮对话005-cancel-in-flight.json飞行中取消模拟智能体与运行器分别位于 test/mock-agent.ts 与 conformance/runner/协议骨架示例可参考 references/acp-sdk-example-client.ts。九、快速上手三条命令感受完整协议流程想亲手体验一遍从 initialize 到 cancel 的过程git clone https://gitcode.com/gh_mirrors/ac/acpx cd acpx pnpm install pnpm run dev -- --help随后对任意受支持的智能体发起一轮 prompt即可在终端看到session/update的流式输出再发一次session/cancel观察响应如何以stopReason: cancelled收尾。更多用法见 docs/quickstart.md 与 docs/CLI.md。小结acpx 用最朴素的 stdio NDJSON JSON-RPC 2.0组合把 ACP 的会话生命周期拆成了清晰可验证的几步握手 → 建会话 → 对话流式更新→ 取消 → 收尾。每一步都有明确的源码位置与一致性用例兜底这正是它能在多种编码智能体之间稳定互通的关键。 延伸阅读会话身份模型见 docs/session-management.md权限交互见 docs/permissions.md。【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
从 initialize 到 session/cancel：acpx 如何在 stdio 上实现 ACP 协议通信（协议实现深度解析）
从 initialize 到 session/cancelacpx 如何在 stdio 上实现 ACP 协议通信协议实现深度解析【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpxacpx是一个面向Agent Client ProtocolACP的无头 CLI 客户端它把 Claude Code、Codex、Gemini 等编码智能体装进标准输入输出stdio管道用JSON-RPC 2.0完成从initialize握手、session/new建会话、session/prompt对话到session/cancel取消的全流程通信。本文从新手视角拆解这套协议在 stdio 上的实现机制带你读懂它的消息帧、握手协商、流式更新与错误语义。一、acpx 是什么把编码智能体接进命令行ACP 是客户端 ↔ 智能体之间的会话协议。acpx 站在客户端一侧它负责拉起智能体子进程在其stdin/stdout上读写 JSON-RPC 消息并把权限确认、文件读写、终端等回调能力暴露给智能体。一句话概括acpx 不关心模型本身只关心如何在 stdio 上稳定地收发 ACP 消息。核心协议实现集中在 src/acp/ 目录客户端主体逻辑见 src/acp/client.ts。二、消息帧一行一条 JSON 的 NDJSON 约定stdio 是字节流没有天然的消息边界。acpx 采用NDJSON每行一条 JSON来切分消息每收到一个字节块按换行符\n切分未完成的行被暂存拼到下一个块再解析。每条合法消息必须满足jsonrpc: 2.0并被识别为请求、通知或响应三种之一。单条消息默认有64 MB上限可用环境变量ACPX_MAX_ACP_MESSAGE_BYTES调整设为0表示不限制。这套切分与校验逻辑位于 src/acp/ndjson-stream.ts消息类型判定与字段合法性检查见 src/acp/jsonrpc.ts。{jsonrpc:2.0,id:1,method:initialize,params:{...}} {jsonrpc:2.0,id:1,result:{protocolVersion:1,...}}三、握手第一步initialize 协商协议版本连接建立后的第一件事是initialize 握手acpx 声明自己支持的protocolVersion与客户端能力智能体返回其能力集合agentCapabilities随后按需进行鉴权。关键流程见 src/acp/client.tsinitializeAgentConnection负责整条启动链路的编排initializeProtocolConnection发出methods.agent.initialize请求并等待响应握手完成后调用authenticateIfRequired处理鉴权方法。响应里若携带authMethodsacpx 会继续发起authenticate请求完成登录态。四、建会话session/new 与上下文绑定握手通过后acpx 请求一个会话并把工作目录cwd、模型等上下文绑定进去。相关请求见 src/acp/client.tssession.new创建新会话返回会话 ID 与会话能力session.load/session.resume加载或恢复已有会话实现跨命令的有状态体验。会话 ID 是后续所有请求/通知的定位键acpx 会用它维护哪个会话正在跑哪一轮 prompt的内部状态。五、对话轮session/prompt 与流式 session/update一次提问prompt是 ACP 的核心交互。acpx 发出session/prompt请求后智能体在执行过程中会持续推送session/update通知文本块、思考块、计划等最终由原始 prompt 的响应携带stopReason表示结束。发出请求src/acp/client.ts接收session/update通知src/acp/client.ts从响应中解析stopReasonsrc/acp/jsonrpc.ts这种通知流 最终响应收尾的模式让用户在终端里能实时看到智能体的输出而不是等全部算完才一次性返回。六、打断对话session/cancel 的通知式设计session/cancel是一个通知notification而非请求——它没有id也不期望收到独立的 JSON-RPC 响应。真正的取消确认体现在仍在进行的session/prompt最终返回stopReason: cancelled。实现要点见 src/acp/client.ts通过connection.agent.notify(methods.agent.session.cancel, { sessionId })发送用cancellingSessionIds集合做幂等保护避免同一会话被并发重复取消若会话处于空闲状态取消通知发出即可无需等待远端确认。这套语义在一致性规范中被明确约定见 conformance/spec/v1.md。七、错误语义与能力协商acpx 对能力和错误都有严格约定能力协商initialize 阶段声明clientCapabilities如fs、terminal。例如--no-fs、--no-terminal会把对应能力设为false见 docs/CLI.md。错误归一化无效参数应返回 JSON-RPC 错误通常为-32602未知会话 ID 必须显式报错而非静默成功。错误形状与解析见 src/acp/jsonrpc-error.ts 与 src/acp/error-shapes.ts。八、用一致性测试验证协议行为acpx 内置一套Conformance一致性测试用 JSON 描述的用例驱动真实或模拟智能体逐条断言协议行为。规范定义见 conformance/spec/v1.md典型用例包括001-initialize-handshake.json握手与版本协商002-session-new.json会话创建003-prompt-single-turn.json单轮对话005-cancel-in-flight.json飞行中取消模拟智能体与运行器分别位于 test/mock-agent.ts 与 conformance/runner/协议骨架示例可参考 references/acp-sdk-example-client.ts。九、快速上手三条命令感受完整协议流程想亲手体验一遍从 initialize 到 cancel 的过程git clone https://gitcode.com/gh_mirrors/ac/acpx cd acpx pnpm install pnpm run dev -- --help随后对任意受支持的智能体发起一轮 prompt即可在终端看到session/update的流式输出再发一次session/cancel观察响应如何以stopReason: cancelled收尾。更多用法见 docs/quickstart.md 与 docs/CLI.md。小结acpx 用最朴素的 stdio NDJSON JSON-RPC 2.0组合把 ACP 的会话生命周期拆成了清晰可验证的几步握手 → 建会话 → 对话流式更新→ 取消 → 收尾。每一步都有明确的源码位置与一致性用例兜底这正是它能在多种编码智能体之间稳定互通的关键。 延伸阅读会话身份模型见 docs/session-management.md权限交互见 docs/permissions.md。【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
