企业官网建设流程全解析

claw-code Rust 移植版 Parity 状态与 Mock 对等性验证机制全解析

【免费下载链接】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

本文基于仓库中 rust/PARITY.md 一文展开，系统梳理 claw-code Rust 移植版在“功能对等性（Parity）”上的定义、验证手段与最新进展。你将理解：为什么一个 Agent 自主维护的项目需要一套确定性的 Mock 对等性测试框架，12 个脚本化场景分别验证什么，40/40 工具表面对齐与 67/141 斜杠命令覆盖意味着什么，以及 bash 校验、文件工具、权限执行等关键检查点当前的完成度与剩余缺口。文章所有结论均可回溯到 rust/PARITY.md 及仓库源码、测试、配置文件。

一、背景：什么是 claw-code 的 “Parity”

claw-code 是一个以 Rust 重写、由 Agent 自主开发与维护的编程助手（仓库描述为 "An agent-managed museum exhibit, built in Rust"）。所谓 Parity，指的是Rust 移植版与原参考实现（upstream）在工具表面（tool surface）、斜杠命令、运行时行为上的对齐程度。rust/PARITY.md 就是这份对齐状态的唯一权威台账：它记录每个功能 lane 的完成状态、对应的 feature commit 与 merge commit、diff 统计，以及仍然敞开的运行时行为缺口。

这份文档有两条底层原则，从目录结构即可印证：

• 以“可复现的脚本化场景”为验证单元，而不是依赖人工手工核对；
• 以“诚实”为前提，明确区分"行为对等"与"仅表面对齐（stub）"，不允许用占位实现冒充完整功能。

二、Mock Parity Harness：里程碑 1 与里程碑 2

PARITY.md 用两个里程碑记录了对等性验证基础设施的建设过程，对应的产物在 rust/MOCK_PARITY_HARNESS.md 中有完整说明。

里程碑 1：确定性 Mock 服务 + 干净环境 CLI 测试

这套设计解决了一个现实痛点：真实 LLM 输出具有不确定性，无法用来做回归断言。Mock 服务通过固定脚本返回预定响应，让端到端 CLI 测试变得可重复、可断言。

里程碑 2：行为面扩展

三、Harness v2 行为清单与场景清单

PARITY.md 定义的 Harness v2 行为清单（canonical scenario map）指向 rust/mock_parity_scenarios.json。该清单覆盖五类行为：

• 多工具 assistant 轮次（Multi-tool assistant turns）
• Bash 流程往返（Bash flow roundtrips）
• 跨工具路径的权限执行（Permission enforcement across tool paths）
• 插件工具执行路径（Plugin tool execution path）
• 文件工具——由 harness 验证的流程（File tools — harness-validated flows）

mock_parity_scenarios.json实际登记了12 个场景（比 PARITY.md 列出的 5+4 个核心场景更多），每个场景都带name、category、description和parity_refs（反向引用 PARITY.md 中的承诺条款），形成一个“文档承诺 → 场景清单 → 测试断言”的完整闭环：

运行方式

仓库提供了两条入口，均以rust/为工作目录：

# 1. 运行完整对等性 harness（编译并执行 mock_parity_harness 测试） cd rust/ ./scripts/run_mock_parity_harness.sh

其内容即：

cargo test -p rusty-claude-cli --test mock_parity_harness -- --nocapture

# 2. 行为 checklist / parity diff（运行测试并生成逐场景 PASS/MISSING 报告） cd rust/ python3 scripts/run_mock_parity_diff.py

run_mock_parity_diff.py还有--no-run模式，只做静态映射检查：确认mock_parity_scenarios.json中每个场景的parity_refs都能在PARITY.md正文中找到对应文本，防止“测试跑了但文档承诺没人维护”的漂移。这正是“manifest 与 harness 及 PARITY.md 三向对齐”约束的实现载体（见 rust/MOCK_PARITY_HARNESS.md）。

手动启动 Mock 服务

cd rust/ cargo run -p mock-anthropic-service -- --bind 127.0.0.1:0

服务启动后会打印MOCK_ANTHROPIC_BASE_URL=...，把该 URL 设为ANTHROPIC_BASE_URL，并用任意非空字符串作为ANTHROPIC_API_KEY即可让 CLI 直连 Mock（见 rust/crates/mock-anthropic-service/src/main.rs）。

四、Harness 内部实现：它到底在测什么

深入 rust/crates/rusty-claude-cli/tests/mock_parity_harness.rs 可以看到这套测试的几个关键设计，它们是 PARITY.md 各条"✅"的直接证据来源：

4.1 干净环境隔离

每个场景在独立临时目录中运行，通过env_clear()清空环境变量，再显式注入：

• ANTHROPIC_API_KEY=test-parity-key（任意值即可）
• ANTHROPIC_BASE_URL=<mock base url>（指向本测试进程内 spawn 的 Mock 服务）
• CLAW_CONFIG_HOME/HOME指向独立的临时目录
• NO_COLOR=1、PATH=/usr/bin:/bin
• CLI 参数：--model sonnet --permission-mode <mode> --output-format=json [--allowedTools <tools>]

每个场景通过--permission-mode指定不同权限模式，从而在同一套框架下覆盖 read-only、workspace-write、danger-full-access 三种权限上下文。

4.2 场景驱动的 Mock 响应

Mock 服务（rust/crates/mock-anthropic-service/src/lib.rs）通过在用户 prompt 中寻找PARITY_SCENARIO:前缀识别场景，然后：

• 对无工具调用场景返回text/event-stream的 SSE 流（message_start→content_block_delta→message_stop）；
• 对工具调用场景，第一轮返回tool_use类型的 content block，并故意把工具入参拆成多个input_json_delta分块——例如 grep 场景把{"pattern":"par"、ity","path":"fixture.txt"、,"output_mode":"count"}三段发送，专门考验客户端对部分 JSON 分块的重组能力；
• 第二轮根据上一次tool_result的内容（从file.content、numMatches、filePath、stdout等字段中提取）生成最终文本回复。

测试最后还会断言：12 个场景累计产生21 次/v1/messages请求，且每次请求都带stream: true——这验证了客户端始终以流式方式消费响应。

4.3 断言矩阵（部分关键断言）

4.4 插件场景的工作区构造

prepare_plugin_fixture展示了外部插件的标准布局：在external-plugins/parity-plugin/下创建tools/echo-json.sh（通过CLAWD_PLUGIN_ID、CLAWD_TOOL_NAME环境变量回显 JSON，并声明requiredPermission: workspace-write）与.claude-plugin/plugin.json清单，然后在CLAW_CONFIG_HOME/settings.json中通过enabledPlugins与plugins.externalDirectories启用它。这说明插件的发现、加载与执行路径已经可被端到端验证。

五、工具表面：40/40 规格对等

PARITY.md 声明Tool Surface 达到 40/40（spec parity）——即 40 个工具在规格层面全部有 Rust 实现或占位。这一数字必须拆开看：表面对齐 ≠ 行为对等。

5.1 真实实现（行为对等，深度不一）

下表完整继承自 rust/PARITY.md：

实现分布的规律很清晰：文件类、任务类、团队/cron 类、MCP 桥、LSP 客户端已经达到"良好对等"——这些恰好都落在 PARITY.md 的 "Completed Behavioral Parity Work" 表格中，每条 lane 都有对应的 feature commit 和 merge commit（详见下一节）。而 WebFetch/WebSearch/NotebookEdit/REPL/PowerShell 等仍标记"中等对等"，需要进一步核对细节。

5.2 仅占位（表面对齐，无行为）

这 4 个 stub 是"诚实台账"的最佳例证：它们计入 40/40 的表面数字，但 PARITY.md 明确标注"surface parity, no behavior"，避免误导。

六、斜杠命令：67/141 上游条目

PARITY.md 对斜杠命令的统计口径非常细致，值得单独说明：

• 27 个原始 spec（此前已存在）——全部有真实 handler；
• 40 个新 spec——目前是 parse + stub handler（返回 "not yet implemented"）；
• 其余约 74 个上游条目是内部模块/对话框/步骤，不属于用户/commands。

也就是说，67 这个数字并不是"67 个能用"，而是"67 个在规格上登记在册"；其中 27 个有真实行为、40 个仅解析后返回占位提示。不要用 67/141 宣传斜杠命令完成度，这是规格登记数而非可用数——这正符合文档一贯的诚实原则。

七、行为功能检查点：已完成工作与剩余缺口

7.1 Bash 工具：9/9 校验子模块全部完成

PARITY.md 列出 bash 工具的 9 个请求级校验子模块，全部标记 ✅，落地于 commit36dac6c（1005 insertions）：

• sedValidation—— 执行前校验 sed 命令
• pathValidation—— 校验命令中的文件路径
• readOnlyValidation—— read-only 模式禁止写入
• destructiveCommandWarning—— 对rm -rf等破坏性命令告警
• commandSemantics—— 命令意图分类
• bashPermissions—— 按命令类型做权限门控
• bashSecurity—— 安全检查
• modeValidation—— 依据当前权限模式校验
• shouldUseSandbox—— sandbox 决策逻辑

从源码看，这 9 个子模块的名称在 rust/crates/runtime/src/bash_validation.rs 中均有对应定义；权限模式本身（ReadOnly/WorkspaceWrite/DangerFullAccess/Prompt）与按工具设定所需权限的策略 API（with_tool_requirement）实现在 rust/crates/runtime/src/permissions.rs，实际门控逻辑（含check_file_write工作区边界判定）在 rust/crates/runtime/src/permission_enforcer.rs。

Harness 注记：里程碑 2 验证了 bash 成功执行，以及 workspace-write 升级的 approve/deny 两条路径；主分支运行时同时携带 sandbox 与权限执行能力。

7.2 文件工具：已完成检查点

• 路径穿越防护（symlink 跟随、../逃逸）
• 读写大小限制
• 二进制文件检测
• 权限模式执行（read-only vs workspace-write）

Harness 注记：read_file、grep_search、write_file允许/拒绝、以及同轮多工具组装均已纳入 mock parity harness；文件边界用例与权限执行分别落地于a98f2b6与336f820。

7.3 Config / Plugin / MCP 流程

• 完整 MCP 服务器生命周期（连接 → 列出工具 → 调用工具 → 断开）
• 插件 install/enable/disable/uninstall 全流程 ——仍开放
• 配置合并优先级（user > project > local）——仍开放

Harness 注记：外部插件的发现与执行已由plugin_tool_roundtrip覆盖；MCP 生命周期落地于cc0f92e（491 insertions, 24 deletions），插件生命周期与配置合并优先级仍是待办。

八、运行时行为缺口（Runtime Behavioral Gaps）

PARITY.md 诚实记录了尚未对齐的运行时行为：

Harness 注记：当前覆盖已包含写文件拒绝、bash 升级 approve/deny、以及插件 workspace-write 执行路径。值得注意：auto_compact_triggered场景在 JSON 层面验证了auto_compaction字段的格式对等性与大 token 数回显（input_tokens >= 50_000），但触发行为本身由 rust/crates/runtime/src/conversation.rs 中的auto_compacts_when_cumulative_input_threshold_is_crossed单元测试负责——这是"格式对等"与"行为对等"分层验证的又一实例。

九、迁移就绪度（Migration Readiness）

PARITY.md 最后给出迁移就绪清单，多数条目仍未勾选，说明项目处于"诚实披露、持续收敛"阶段：

• PARITY.md得到维护且诚实
• 无#[ignore]测试掩盖失败（仅允许 1 个：live_stream_smoke_test）
• 每个 commit 上 CI 全绿
• 代码库形态为交接准备就绪

十、总结：这份台账如何阅读

要正确使用 rust/PARITY.md，建议按三层去读：

1. 验证层：先看Completed Behavioral Parity Work表格中的 commit 与 diff 统计，确认"谁、在什么时候、以多少代码量"完成了哪条 lane；
2. 场景层：对照 rust/mock_parity_scenarios.json 与 rust/crates/rusty-claude-cli/tests/mock_parity_harness.rs，理解每个 ✅ 背后对应的可重复执行断言；
3. 差距层：把"工具表面 40/40"、"斜杠命令 67/141"、"4 个 stub"、"运行时 3 个缺口"、"迁移 3 个未勾选项"放在一起看，得出真实完成度，而不是只看某个数字。

如果想亲手复现验证结果，最低成本的做法是：

cd rust/ python3 scripts/run_mock_parity_diff.py --no-run # 静态检查文档↔场景映射 ./scripts/run_mock_parity_harness.sh # 跑完整 12 场景端到端测试

这套"文档承诺 ↔ 场景清单 ↔ 测试断言 ↔ commit 溯源"四位一体的对等性管理机制，正是 Agent 自主开发项目能够长期自我约束、避免功能悄悄漂移的关键工程实践。

【免费下载链接】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