claw-code ACP/Zed 与 JSON-RPC 状态契约解析：以 truthful unsupported 契约服务编辑器生态探测

claw-code ACP/Zed 与 JSON-RPC 状态契约解析以 truthful unsupported 契约服务编辑器生态探测【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code本篇文章基于仓库契约文档 docs/g011-acp-json-rpc-status-contract.md系统讲解 claw-code 2.0 如何将 ACP/Zed 与 JSON-RPC 能力面收敛为稳定的状态查询契约哪些命令被定义为合法状态查询、它们返回什么样的机器可读 JSON 信封、错误调用如何被归类以及真实协议服务为何被推迟deferral gate。读完本文你将掌握如何用claw acp系列命令在编辑器探针editor probes与 CI 检查中正确探测能力状态并理解这套诚实的不支持truthful unsupported设计背后的契约纪律。为什么需要一份状态契约而非隐藏的守护进程在 claw-code 的演进中ACPAgent Client Protocol与 Zed 编辑器集成、JSON-RPC 服务这类能力容易让外部系统误以为存在一个隐藏的守护进程hidden daemon。G011 契约的核心立场是当前公共能力面public surface是一个诚实报告不支持的状态面而不是一个未暴露的常驻服务。也就是说claw acp这一系列命令存在的意义不是假装提供协议服务而是为桌面端、市场marketplace与编辑器集成提供稳定、可探测、不会误导消费者的能力声明。从仓库实现看这一设计贯穿 CLI 解析层rust/crates/rusty-claude-cli/src/main.rs 中parse_acp_args对 ACP 子命令做了白名单式解析只接受空参数与serve其余一律拒绝详见下文不支持的调用一节而状态输出本身则通过CliAction::Acp分发到print_acp_status以纯文本或 JSON 两种格式打印状态。整条路径没有任何 socket 绑定、没有 daemon 进程也没有 JSON-RPC endpoint——这与文档声明的不启动 daemon、不暴露端点完全一致。支持的状态查询命令按照契约文档以下命令是合法的状态查询status queries均以退出码0结束claw acp claw acp serve claw --acp claw -acp claw acp --output-format json claw acp serve --output-format json命令形式说明claw acp基础状态查询纯文本输出claw acp serveserve当前刻意作为 status 的别名不绑定 socket、不启动 daemon、不暴露 JSON-RPC endpointclaw --acp/claw -acp等价的别名形式便于不同习惯的调用方claw acp --output-format json状态查询 机器可读 JSON 信封见下节claw acp serve --output-format jsonserve别名的 JSON 形态源码层面--acp与-acp两个别名在参数归一化阶段被转换为acp子命令见 rust/crates/rusty-claude-cli/src/main.rs 中--acp | -acp的分支处理因此它们与claw acp走完全相同的分发路径保证六种写法的行为一致。帮助文本同样只宣传claw acp [serve]这一种可发现形式并在--help中明确标注currently unsupported见该文件claw acp [serve]的 help 条目避免用户产生能力幻觉。JSON 信封稳定的机器可读状态面claw acp --output-format json返回一个为编辑器探针与 CI 检查设计的稳定信封契约文档给出的完整示例为{ schema_version: 1.0, kind: acp, status: unsupported, phase: discoverability_only, supported: false, exit_code: 0, serve_alias_only: true, protocol: { name: ACP/Zed, json_rpc: false, daemon: false, endpoint: null, serve_starts_daemon: false } }信封字段语义如下字段类型含义schema_versionstring信封自身的模式版本当前为1.0作为向后兼容的判据kindstring固定为acp用于标识该信封属于 ACP 状态面statusstring能力状态文档以unsupported作为契约目标形态phasestringdiscoverability_only说明当前仅处于可发现性阶段supportedbooleanfalse明确声明协议未被支持exit_codenumber0与状态查询退出码一致便于 shell 层直接透传serve_alias_onlybooleantrue声明serve仅是指令别名而非真实服务protocol.namestringACP/Zedprotocol.json_rpcbooleanfalse明确无 JSON-RPC 能力protocol.daemonbooleanfalse明确无守护进程protocol.endpointnull无监听端点protocol.serve_starts_daemonbooleanfalseserve不会拉起 daemon需要指出的是仓库当前源码 rust/crates/rusty-claude-cli/src/main.rs 中acp_status_json()实现的信封在稳定字段上保持一致schema_version: 1.0、kind: acp、supported: false、protocol.json_rpc/daemon/endpoint/serve_starts_daemon等同时额外携带status: not_implemented、action、message、launch_command、contracts、aliases等运行时信息并在contracts.blocking_gates中列出阻塞真实实现的契约门详见推迟门Deferral Gate一节。这意味着契约文档描述的是稳定消费面而源码实现是这一消费面的运行时投影——两者在核心判据字段上保持一致这正是下面要强调的防御性消费原则。消费者应如何校验文档明确要求消费方应检查kind acp、supported false、protocol.json_rpc false而不是根据命令是否存在来推断能力支持。这一原则至关重要命令存在 ≠ 能力可用claw acp存在恰恰是为了诚实地声明暂不支持只检查supported可能遗漏协议细节例如未来supported: true但json_rpc: false的中间态三字段联合判断才能覆盖命令存在但协议未就绪的所有组合。集成方在 CI 或编辑器插件里做能力探测时应解析该 JSON 而非正则抓取帮助文本这正是--output-format json信封存在的意义。仓库测试 rust/crates/rusty-claude-cli/tests/output_format_contract.rs 中acp_guidance_emits_json_when_requested对上述核心字段逐一断言kind、schema_version、supported、protocol.json_rpc、protocol.daemon、endpoint为 null 等并验证内部追踪 ID如discoverability_tracking、tracking、recommended_workflows不会泄漏进公开 JSON——公开面只暴露契约允许的字段。不支持的调用错误信封与退出码 1形如claw acp start的畸形 ACP 调用会被拒绝以退出码1结束。在--output-format json模式下stderr 走 CLI 通用错误信封设置如下判据{ type: error, kind: unsupported_acp_invocation, exit_code: 1 }这一行为在源码中非常清晰parse_acp_argsrust/crates/rusty-claude-cli/src/main.rs只放行[]即claw acp与[serve]即claw acp serve其余参数一律返回Err错误消息以unsupported_acp_invocation前缀开头并附带\n分隔的修复提示提示用户改用claw acp或claw acp serve。该Err最终被顶层错误处理捕获在--output-format json激活时rust/crates/rusty-claude-cli/src/main.rs 的main/run错误路径会调用classify_error_kind将消息归类为unsupported_acp_invocation并组装包含type: error、error_kind、hint、exit_code: 1的 JSON 错误信封输出。同一归类逻辑的单元测试也覆盖了unsupported ACP invocation. Use claw acp.这类消息的分类结果。契约文档强调这种白名单拒绝的价值畸形调用不静默、不假装成功而是给出可机器判别的错误类别与可人类阅读的修复提示。集成方在探测脚本中遇到unsupported_acp_invocation时应当将其视为调用方式错误而非服务故障并可以据hint字段向用户展示修复建议。推迟门Deferral Gate真实协议服务何时落地契约文档明确真实的 ACP/Zed 或 JSON-RPC serve 工作在路线图中 task packets、session control、event/report schemas 等契约稳定之前保持推迟。源码中这一决定被显式编码进 JSON 信封的contracts.blocking_gates字段contracts: { blocking_gates: [ task_packet_schema, session_control_schema, event_report_schema ], stable_status_surface: claw acp [serve] --output-format json, unsupported_invocation_kind: unsupported_acp_invocation }这一设计的动机在文档中表述为防止桌面端、市场与编辑器集成在 CLI/文件/API 契约就绪之前成为另一种事实来源alternate sources of truth。换言之claw-code 不希望编辑器插件先于核心契约锁定行为语义否则后续契约演进会撕裂生态。推迟门的实质是一种契约纪律——能力面的开放顺序必须与数据面契约任务包、会话控制、事件/报告的成熟度对齐。从仓库路线图 ROADMAP.md 的演进记录看这一顺序是有据可循的结构化任务包typed task packet format已由 rust/crates/runtime/src/task_packet.rs 实现TaskPacket结构、校验、序列化与TaskScope解析会话控制session_control在 rust/crates/runtime/src/session_control.rs 中提供SessionStore等实现事件/报告 schema 则由 rust/crates/runtime/src/report_schema.rs 承担。这三者正是blocking_gates列出的三份契约——它们先稳定ACP/Zed 的真实服务才有资格开闸。对读者而言这意味着在blocking_gates对应的契约在路线图中转为稳定之前任何依赖claw acp serve提供真实 JSON-RPC 能力的集成都应当把该命令当作状态探针而非服务入口。实践建议如何正确消费这套契约综合文档、源码与测试面向编辑器插件、CI 或脚本的推荐做法可归纳为探测状态一律用 JSON 形态执行claw acp --output-format json或claw acp serve --output-format json解析 stdout 信封而不是抓取帮助文本或依赖命令存在性。三字段联合判据以kind acp、supported false、protocol.json_rpc false判定当前不支持未来契约演进时再按schema_version做兼容分支。区分两类失败状态查询成功应退出码为0畸形调用如claw acp start退出码为1且kind/error_kind为unsupported_acp_invocation此时应展示hint中的修复建议而非当作系统故障告警。不要把serve当服务serve_alias_only/protocol.serve_starts_daemon为false意味着它永不绑定端口、永不启动 daemon集成方不应尝试连接任何 ACP/Zed 端点。留意契约演进文档信封与源码运行时信封的字段集存在演进差异例如文档的status: unsupported、phase: discoverability_only与源码当前的status: not_implemented消费方应以文档强调的稳定判据字段为准不依赖单字段的精确字符串。这套诚实的不支持契约体现了 claw-code 在能力面管理上的克制与其让编辑器生态误探测出一个不存在的 daemon不如用稳定、可校验、可演进的 JSON 状态面把尚未支持这一事实说得明明白白同时为真实协议服务预留清晰的解锁条件。【免费下载链接】claw-codeAn agent-managed museum exhibit, built in Rust with Gajae-Code / LazyCodex — developed and maintained with no human intervention.项目地址: https://gitcode.com/gh_mirrors/claudeco/claw-code创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考