协议客户端如何测试acpx ACP 一致性测试套件与 Mock 适配器全解【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpxacpx是一个面向 Agent Client ProtocolACP的无头 CLI 客户端支持有状态的 Agent 会话。它内置了一套ACP 一致性测试套件Conformance Suite和本地 Mock 适配器让你可以脱离真实 Agent 环境用确定性用例验证协议握手、会话生命周期、取消与权限语义——这正是协议客户端测试的核心难题的解法。一、为什么协议客户端必须有一致性测试ACP 基于JSON-RPC 2.0 over stdio传输客户端acpx与适配器Agent双向通信。测试这类客户端时有三个天然难点难点说明acpx 的对策依赖真实 Agent真实适配器行为不确定、响应缓慢捆绑 Mock 适配器提供确定性命令语义双向通信Agent 会反向调用fs/read_text_file、terminal/create等客户端方法Mock 覆盖双向流量验证时序敏感流式session/update、取消、后台完成都涉及时序每个用例定义独立超时预算测试资产集中在 conformance/ 目录设计文档见 conformance/README.md 与 docs/2026-02-19-mock-agent-testing.md。二、套件结构规范、用例、档案、运行器四件套一致性套件采用数据驱动模型由四类文件组成规范契约conformance/spec/v1.md 以 RFC 2119 的 MUST/MAY 措辞定义 v1 画像的规范性要求用例定义conformance/cases/ 下的 21 个 JSON 文件按数字前缀保持稳定执行顺序画像Profileconformance/profiles/ 声明某套必选用例集合运行器conformance/runner/run.ts 解析并执行steps与checks输出通过/失败矩阵。两个内置画像画像用例数适用对象acp-core-v114 个任意 ACP 适配器适配器无关的核心互操作acpx-mock-v121 个捆绑 Mock 适配器额外覆盖权限、活跃取消等确定性回归核心画像锁定五个高价值方法initialize、session/new、session/prompt、session/update、session/cancel外加基线错误语义Invalid params、未知会话。三、用例长什么样以取消为例每个用例 JSON 由有序步骤steps和事后断言checks构成。看一个经典场景——取消进行中的提示取自 conformance/cases/005-cancel-in-flight.jsonnew_session创建会话并保存为session_idprompt_background在后台发送一条会让 Mock 适配器休眠 5 秒的提示sleep100 毫秒确保请求已在飞行中cancel发送session/cancel通知await_background等待后台请求结束断言最终stopReason必须为cancelled。这就是数据驱动的价值没有case id - 硬编码逻辑的映射运行器只认 JSON 中的结构化指令新增用例零代码改动。支持的步骤包括new_session、prompt、prompt_background、await_background、cancel、sleep断言包括协议版本检查、非空字符串校验、停止原因匹配、更新流计数与文本匹配、文件系统操作完成校验等完整清单见 conformance/README.md 的 Data-Driven Model 一节。四、Mock 适配器确定性行为的来源Mock 适配器是 test/mock-agent.ts 中的一个独立 ACP Agent 实现仅用于测试。它基于 ACP SDK 的AgentSideConnectionndJsonStream工作流程是acpx --agent node mock-agent.js ├──→ initialize / session/new / session/prompt └──← fs/read_text_file / terminal/create / session/update双向验证Mock 不仅回应客户端请求还会反向调用fs/read_text_file、terminal/create、terminal/kill等 ACP 客户端方法验证 acpx 的输出格式化器与权限门控确定性提示场景echo text、read path、write path content、terminal command、kill-terminal command、sleep ms让权限批准/拒绝、可取消延迟、迟到更新都可以被稳定观测。端到端集成测试在 test/integration.test.ts把acpx作为子进程用--agent指向 Mock 运行断言进程退出码、stdout/stderr 与文件/进程副作用。五、快速上手四条命令跑完全部测试克隆仓库后git clone https://gitcode.com/gh_mirrors/ac/acpx常用入口如下# 核心画像 默认 Mock 适配器 pnpm run conformance:run # 全量确定性回归Mock 画像21 用例 pnpm run conformance:run -- --profile conformance/profiles/acpx-mock-v1.json # 只跑单个用例 pnpm run conformance:run -- --case acp.v1.initialize.handshake # 指向真实适配器例如 Codex ACP pnpm run conformance:run -- --agent-command npx -y agentclientprotocol/codex-acp加上--format json --report ./report.json可导出机器可读报告。运行器在执行前会校验画像与所有用例 JSON 的合法性未知字段、重复 ID 都属启动错误在拉起任何适配器之前就拦截配置问题。六、工程细节清理、超时与信号处理一致性测试不仅要跑起来还要干净地结束acpx 在这方面的设计值得借鉴逐用例回收每个用例报告结果前回收适配器进程、被观察的后代进程与传输层8 秒预算内从 stdin EOF 升级至 TERM/KILL回收失败则用例判败并停止后续用例超时即失败每个用例自带request_timeout_ms/update_timeout_ms/settle_timeout_ms预算超时按失败处理并保留现场信号安全SIGINT/SIGTERM/SIGHUP 会停止新任务、中断在途请求与等待先完成已拥有的清理再写出部分报告重复信号不会跳过清理每晚工作流Mock 全量画像在 CI 中每晚运行并归档 JSON 报告真实适配器冒烟检查可通过变量或手动触发开启。七、这套方法对其他协议客户端的启示先锁规范再写用例用 MUST/SHOULD 措辞的规范文档v1.md划定范围明确非目标如 v1 不含session/fork、性能基准避免范围蔓延数据驱动分离意图与执行用例是纯数据运行器是纯引擎两者都可独立演进与静态校验Mock 承担不确定性把时序、权限、副作用等依赖真实 Agent 的行为收敛到 Mock 的确定性命令语义中核心画像保持适配器无关对外互操作只要求最低稳定契约厂商特定行为放到独立画像才能跨实现比较。ACP 方法的完整支持矩阵可查阅 docs/2026-02-19-acp-coverage-roadmap.md用例规范细节见 conformance/spec/v1.md。【免费下载链接】acpxHeadless CLI client for stateful Agent Client Protocol (ACP) sessions项目地址: https://gitcode.com/gh_mirrors/ac/acpx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考