Claw Code G011 生态运维/UX 验证地图：跨泳道验收矩阵、ACP/插件 JSON 状态契约与最终验证序列

本文以仓库中的 G011 验证地图 为主体，系统讲解 claw-code 团队运行（team run）的最后一道跨泳道验收门禁：它如何把 ACP/Zed 状态契约、插件/市场路由、剪贴板与桌面 UX 延期项、文档真实源检查以及 Issue/PR 运维门禁组织成一张可复跑的验收矩阵。读完本文后，你可以完整复现 G011 的最终验证序列，理解每一道检查对应的源码实现与测试证据，并掌握“延期功能必须显式声明而非假装已实现”的契约设计方法。

1. G011 的定位：收口前序泳道刻意延期项的跨泳道门禁

G011 关闭的是此前在安全（safety）、会话（session）、MCP、Windows 与文档（docs）等泳道中被刻意延期的横向事项（laterals）。这张验证地图是团队运行的跨泳道门禁（cross-lane gate），它做三件事：

1. 点名哪些本地表面（surface）可以被验证；
2. 给出 worker 集成后必须重新执行的精确检查命令；
3. 明确要求哪些 UX 延期项（UX deferrals）在产品契约稳定之前必须保持显式声明。

根据 Leader audit notes，该地图是仓库本地证据（repo-local evidence），worker 不得修改 .omx/ultragoal；如果某项检查因其他泳道仍在进行中而失败，正确做法是记录失败命令、待该泳道集成后重跑，而不是弱化门禁。

2. 跨泳道验收矩阵（Cross-lane acceptance matrix）

原文档的核心是一张四列矩阵：泳道（Lane）、负责的表面（Owned surface）、回归证据（Regression evidence）、门禁/缺口（Gate / gap）。完整继承如下：

泳道	负责表面	回归证据	门禁 / 缺口
ACP/Zed 状态与 JSON 契约	main.rs 解析 claw acp、claw acp serve、--acp、-acp；README.md 与 rust/README.md 文档化“仅可发现（discoverability-only）”状态	cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli --test output_format_contract acp_guidance_emits_json_when_requested -- --nocapture；cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli local_command_help_flags_stay_on_the_local_parser_path -- --nocapture	真实的 ACP/Zed 守护进程支持仍然延期；状态输出不得暗示存在正在运行的协议端点。
插件/市场本地路由	main.rs 将 claw plugins、claw plugin、claw marketplace 路由到本地插件处理；commands/src/lib.rs 在共享斜杠命令帮助中保留 /plugin 别名	cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli removed_login_and_logout_subcommands_error_helpfully -- --nocapture；cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli direct_slash_commands_surface_shared_validation_errors -- --nocapture；以及 5 个 tests.test_porting_workspace 插件测试（见下文）	市场（marketplace）只是本地插件管理的别名；不宣称存在远程市场浏览/安装契约。
TUI/复制粘贴/可点击路径 UX	commands/src/lib.rs 宣传 /copy、/paste、/desktop 及路径类命令；main.rs 为终端可读性渲染压缩文件/工具路径	cargo test --manifest-path rust/Cargo.toml -p commands renders_help_with_grouped_categories_and_keyboard_shortcuts -- --nocapture；cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli tool_rendering_helpers_compact_output -- --nocapture；cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli tool_rendering_truncates_large_read_output_for_display_only -- --nocapture	剪贴板集成、全屏 TUI 模式、可点击终端超链接还不是稳定产品契约；除非有定向实现落地，否则保持为路线图/UX 跟进项。
桌面集成延期	commands/src/lib.rs 包含 /desktop；main.rs 将其在当前构建中视为未实现	cargo test --manifest-path rust/Cargo.toml -p commands renders_help_from_shared_specs -- --nocapture；cargo test --manifest-path rust/Cargo.toml -p commands renders_per_command_help_detail -- --nocapture	在桌面启动/API 契约存在之前，/desktop 必须保持“可发现但不承诺”。
导航/文件上下文/本地提供商文档	README.md、USAGE.md、rust/README.md、docs/MODEL_COMPATIBILITY.md 及 worker-2 的文档更新	python3 .github/scripts/check_doc_source_of_truth.py；python3 .github/scripts/check_release_readiness.py；git diff --check	文档集成后重跑；除非文档暴露出代码契约缺口，该泳道不得改动 Rust 行为。
Issue/PR 运维门禁	docs/pr-issue-resolution-gate.md、docs/roadmap-pr-goals.md 及（若存在）issue/PR 分诊模板	python3 .github/scripts/check_release_readiness.py；git diff --check；仅当 .omx/cc2/board.md 变更时可选 python3 scripts/validate_cc2_board.py	Worker 泳道不得合并/关闭远程 PR 或 issue；最终对账由 leader 负责。

3. ACP/Zed 泳道：可发现但不运行的状态契约

3.1 命令面与别名

从 main.rs 的参数解析可以看到，CLI 顶层接受 claw acp、claw acp serve 两种调用形式，以及 --acp、-acp 两个短别名（第 305–306 行将 "--acp"、"-acp" 列入本地解析路径）。帮助主题表将其映射到 LocalHelpTopic::Acp（main.rs）。

参数解析器 parse_acp_args 对不支持的调用形态返回带类型的错误（main.rs）：

unsupported_acp_invocation: unsupported ACP invocation. Use `claw acp` or `claw acp serve`.
ACP/Zed editor integration is not implemented yet; `claw acp serve` reports status only.

注意这里的错误分类名 unsupported_acp_invocation 是公共契约的一部分——它出现在 JSON 输出的 contracts 字段中（见 3.2），因此解析器、状态 JSON、错误分类三者必须一致，这正是该泳道回归测试要锁住的东西。

3.2 JSON 状态契约：如何“不暗示存在运行中的协议端点”

claw acp 在 --output-format json 下输出 acp_status_json() 构建的 JSON（main.rs）。文本模式的状态文案明确写出：

ACP/Zed editor integration is not implemented in claw-code yet. `claw acp serve` reports
status only and does not launch a daemon or JSON-RPC endpoint. Use the normal terminal
surfaces for now.

契约测试 output_format_contract.rs 的 acp_guidance_emits_json_when_requested 逐字段锁定该 JSON 的形状：

字段	期望值	含义
进程退出码	2	“未实现”必须以非零码暴露，而非返回 0 假装成功（issue #443）
kind / schema_version	"acp" / "1.0"	状态文档的类型与版本
status	"not_implemented"	状态语义
supported	false	顶层支持性声明
protocol.json_rpc / protocol.daemon	false / false	明确否认存在 JSON-RPC 或守护进程
protocol.endpoint	null	端点必须为空，不得暗示可连接地址
contracts.unsupported_invocation_kind	"unsupported_acp_invocation"	错误分类名契约
message	包含 "not implemented"	人类可读提示必须与状态一致

测试还断言 discoverability_tracking、tracking、recommended_workflows 三个内部跟踪字段不得出现在公共 JSON 中（#443 移除内部跟踪 ID）。这条设计对 Agent 消费者很关键：机器读取状态 JSON 时，supported=false + endpoint=null 就足以做出正确决策，不会被过期文案误导。

配套的 local_command_help_flags_stay_on_the_local_parser_path 测试则验证 --acp/-acp 等本地帮助标志始终留在本地解析器路径上，不会被误送进提示词（prompt）流程。

4. 插件/市场泳道：marketplace 是别名，不是远程商店

4.1 本地路由实现

在共享斜杠命令规格中，插件命令被声明为（commands/src/lib.rs）：

SlashCommandSpec {
    name: "plugin",
    aliases: &["plugins", "marketplace"],
    summary: "Manage Claw Code plugins",
    ...
}

CLI 侧的路由同样把三个名字收敛到同一处理入口，并在 main.rs 中给出统一用法：

claw plugins [list|show <id>|install <id>|enable <id>|disable <id>|uninstall <id>|update <id>|help]

源码注释记录了历史缺陷（#145）：plugins 曾经因为没有本地路由而被错误地送进 prompt 回退路径，现在 claw plugins、claw plugins --help、claw plugins list 等都走本地命令路径；plugin（单数）与 marketplace 是 plugins 的别名（main.rs）。

4.2 参数校验：共享的 usage_error 契约

parse_plugin_command（commands/src/lib.rs）对每个动作执行严格的用法校验，缺少参数时返回带精确用法提示的错误：

动作	期望形式	缺参时的错误用法提示
list	/plugin list	plugin list
install	/plugin install <path>	plugin install <path>
enable	/plugin enable <name>	plugin enable <name>
disable	/plugin disable <name>	plugin disable <name>
uninstall	/plugin uninstall <id>	plugin uninstall <id>
update	/plugin update <id>	plugin update <id>

未知动作会提示 Unknown /plugin action '{action}'。这套共享校验错误正是 direct_slash_commands_surface_shared_validation_errors 测试锁定的对象——斜杠命令（REPL 内）与直接 CLI 命令必须报同样的错误形状。运行期入口是 handle_plugins_slash_command（commands/src/lib.rs），它通过 PluginManager 完成 list/install/enable/disable/uninstall/update，并在 JSON 模式下由 plugin_command_json（main.rs）输出 kind: "plugin" 的报告，其中每个插件条目携带 lifecycle_state 等生命周期字段。

4.3 移植工作区（porting workspace）侧的回归证据

验收矩阵引用的 5 个 Python 单元测试位于 tests/test_porting_workspace.py，从 Python 镜像层独立验证插件命令行为：

• test_plugin_command_filter_excludes_plugin_sources：get_commands(include_plugin_commands=False) 必须过滤掉所有 source_hint 含 "plugin" 的命令，保证共享命令表不被插件源污染；
• test_plugin_command_aliases_execute_as_local_commands：plugin、plugins、marketplace 三个别名经 exec-command 执行时都必须输出 Mirrored command 'plugin'，且不得出现 Unknown mirrored command；
• test_route_plugin_slash_commands_match_commands：/plugin list、/plugins list、/marketplace browse、/reload-plugins 经 route 命令路由时，首行必须是 command\t... 且匹配到 plugin 或 reload-plugins；
• test_plugin_command_stream_emits_command_match：PortRuntime().bootstrap_session(...) 流式事件中必须出现 command_match 事件；
• test_turn_loop_plugin_commands_are_not_prompt_only：turn-loop 结构化输出必须包含 "Matched commands:，证明这些斜杠命令不是仅作为纯提示词透传。

这条证据链同时覆盖 Rust 实现与 Python 镜像，确保两个实现面在插件命令语义上保持一致。

5. TUI/剪贴板/路径可读性泳道：已实现什么、明确没实现什么

5.1 命令规格：可发现但显式延期

三个 UX 命令在共享规格中都有完整声明（commands/src/lib.rs）：

命令	参数提示	规格摘要
/copy	[last|all]	Copy conversation or output to clipboard（lib.rs）
/paste	无	Paste clipboard content as input（lib.rs）
/desktop	无	Open or manage the desktop app integration（lib.rs）

解析层行为："desktop" 走 validate_no_args 后进入 SlashCommand::Desktop（lib.rs），"copy" 进入 SlashCommand::Copy { target }（lib.rs）。关键设计点：这些都是可解析的斜杠命令名，但当前运行期处理仍会报告“未实现的命令”，而不是执行剪贴板或桌面副作用——G011 地图明确指出“这比假装支持存在更安全”（safer than pretending support exists）。/desktop 的具体门禁是：保持可发现、但不承诺（discoverable but non-committal），直到桌面启动/API 契约存在。

5.2 路径可读性：压缩渲染的真实实现

该泳道中“已落地”的部分是终端渲染辅助。main.rs 中的 truncate_output_for_display（main.rs）按 max_lines/max_chars 双重上限截断工具输出，读取（read）工具输出走 READ_DISPLAY_MAX_LINES/READ_DISPLAY_MAX_CHARS 常量（main.rs），截断时保留完整路径信息并追加提示：

… output truncated for display; full result preserved in session.

也就是说截断只发生在显示层，会话中保存的是完整结果——这正是 tool_rendering_truncates_large_read_output_for_display_only 测试名的语义。两个验收测试分别锁定：tool_rendering_helpers_compact_output（压缩输出辅助）与显示层截断不丢失数据。

5.3 明确的“未做”清单

• 可点击 OSC-8 超链接：若未来添加，需要独立测试，因为终端支持不一致；
• 全屏 TUI 模式：仍是愿景项，见 rust/TUI-ENHANCEMENT-PLAN.md；当前验证聚焦于行内 REPL/help/status 表面。

6. 文档泳道：两个可执行检查脚本的机制

文档/导航/本地提供商这一泳道的回归证据是两个依赖为零的 Python 脚本，可以直接在仓库根目录复跑。

6.1 check_doc_source_of_truth.py

.github/scripts/check_doc_source_of_truth.py 扫描 README.md、USAGE.md、PARITY.md、PHILOSOPHY.md、ROADMAP.md、.github/FUNDING.yml 以及 docs/ 下全部 Markdown（脚本），用 FORBIDDEN 正则表（脚本）阻止陈旧链接与资产引用回归，包括旧 GitHub 仓库链接、过期 Discord 邀请、过时的 star-history 嵌入、以及 assets/clawd-hero.jpeg 等失效资产名。任何命中都会输出 文件:行号: 原因 并退出码 1；全部通过则打印 doc source-of-truth check passed。

6.2 check_release_readiness.py

.github/scripts/check_release_readiness.py 做三项发布就绪校验（脚本）：

1. 必备策略文件存在：LICENSE、CONTRIBUTING.md、SECURITY.md、SUPPORT.md、CODE_OF_CONDUCT.md；
2. 本地链接与锚点可解析：遍历 README.md、USAGE.md、PARITY.md、PHILOSOPHY.md、ROADMAP.md、各策略文件、整个 docs/ 目录及 rust/README.md 等，校验 Markdown 链接/HTML 链接目标不逃出仓库根、目标文件存在、Markdown 锚点在目标文件中真实存在（锚点生成规则模拟 GitHub 风格，见 github_anchor 函数）；
3. 命令示例守门：bash/sh/shell/zsh/powershell 代码块中出现已弃用的 cargo install claw-code 安装方式会被判为错误，要求改用源码构建文档（脚本）。

再配合 git diff --check（空白错误检查），文档泳道即完成一轮回归。G011 地图对该泳道的约束是：文档集成后重跑这些检查；除非文档暴露出代码契约缺口，否则不得因此改动 Rust 行为。

7. Issue/PR 运维门禁

运维泳道由 docs/pr-issue-resolution-gate.md 与 docs/roadmap-pr-goals.md 定义，门禁规则只有两条但非常硬：

• Worker 泳道不得合并/关闭远程 PR 或 issue，最终对账（final reconciliation）始终由 leader 负责；
• 检查命令为 check_release_readiness.py + git diff --check；scripts/validate_cc2_board.py 是条件性检查——仅当 .omx/cc2/board.md 发生变更时才需要运行，避免对未变更的看板做无意义校验。

8. Task 5 UX/延期支持说明（原文完整继承）

• /copy、/paste、/desktop 是可解析的斜杠命令名，但当前运行期处理仍报告未实现的命令，而不是执行剪贴板或桌面副作用。这比假装支持存在更安全。
• /marketplace 被有意设计为插件别名；在 install/search/update 语义与信任策略（trust policy）被明确定义之前，不应把它描述为远程市场。
• 路径可读性由终端渲染辅助覆盖：压缩冗长工具输出，并在 read/write/edit 摘要中保留路径。若之后添加可点击 OSC-8 链接，需要单独测试，因为终端支持不一致。
• 全屏 TUI 模式仍是愿景（rust/TUI-ENHANCEMENT-PLAN.md）；当前验证应聚焦行内 REPL/help/status 表面。

9. 最终验证序列（Final verification sequence）

以下命令在所有 G011 worker 提交集成进 leader 分支之后按序执行（完整继承自原文档，未做任何增删）：

git diff --check
python3 .github/scripts/check_doc_source_of_truth.py
python3 .github/scripts/check_release_readiness.py
cargo check --manifest-path rust/Cargo.toml -p commands -p rusty-claude-cli
cargo test --manifest-path rust/Cargo.toml -p commands renders_help_from_shared_specs -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p commands renders_help_with_grouped_categories_and_keyboard_shortcuts -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p commands renders_per_command_help_detail -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli removed_login_and_logout_subcommands_error_helpfully -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli direct_slash_commands_surface_shared_validation_errors -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli local_command_help_flags_stay_on_the_local_parser_path -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli tool_rendering_helpers_compact_output -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli tool_rendering_truncates_large_read_output_for_display_only -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli --test output_format_contract acp_guidance_emits_json_when_requested -- --nocapture
cargo test --manifest-path rust/Cargo.toml -p rusty-claude-cli --test output_format_contract plugins_json_surfaces_lifecycle_contract_when_plugin_is_installed -- --nocapture
python3 -m unittest tests.test_porting_workspace.PortingWorkspaceTests.test_plugin_command_filter_excludes_plugin_sources tests.test_porting_workspace.PortingWorkspaceTests.test_plugin_command_aliases_execute_as_local_commands tests.test_porting_workspace.PortingWorkspaceTests.test_route_plugin_slash_commands_match_commands tests.test_porting_workspace.PortingWorkspaceTests.test_plugin_command_stream_emits_command_match tests.test_porting_workspace.PortingWorkspaceTests.test_turn_loop_plugin_commands_are_not_prompt_only

序列的组织逻辑可以分成四段理解：

1. 文档与卫生检查（git diff --check + 两个 Python 检查脚本）——最快失败、成本最低，先跑；
2. 编译门禁（cargo check -p commands -p rusty-claude-cli）——确认两个核心 crate 编译通过后再跑测试；
3. 命令面契约测试（commands crate 的 help 渲染测试 + rusty-claude-cli 的解析/渲染/JSON 契约测试）——对应矩阵前四条泳道的回归证据；
4. 跨语言镜像测试（Python unittest）——确认 Python 移植工作区与 Rust 实现在插件命令语义上一致。

10. Leader 审计规则与最小终态条件

G011 地图对 leader 的约束（Leader audit notes）：

• 该地图只是仓库本地证据；worker 不得修改 .omx/ultragoal；
• 若某项检查因另一泳道仍在进行中而失败，记录失败命令、待该泳道集成后重跑，而不是弱化门禁（weakening the gate）；
• 最小终态条件（minimum terminal condition）：文档检查通过、Rust 定向测试通过、且所有仍延期的 UX 表面都在地图中被显式点名。

这套规则的工程价值在于：延期不是“悄悄不做”，而是把“未实现”本身变成一份可测试的契约——claw acp 的 supported=false + 退出码 2、/copy 的“未实现”报错、/marketplace 的别名语义——每一项延期都有对应的回归测试防止它被无意“实现”或被文档误描述，这正是 G011 作为团队运行最后一道跨泳道门禁的核心机制。