claw-code 源码分析：洁净室重写——在公开仓库里如何做「学得会、抄不得」的架构迁移？

本篇重点不是讲“如何写更像”而是讲“如何在公开仓库里把再实现做成可学习、可验证、可持续协作同时尽量避免把不可授权材料变成可分发产物”。涉及仓库证据README 的 clean-room 叙事与免责声明、reference_data快照与parity-audit、Python/Rust 双轨结构。1. 什么是「学得会、抄不得」在工程语境里“学得会”不等于“拿到源码照着敲”。更健康的目标是学得会理解架构模式、运行时切分、协议边界、可观测性与测试策略并能在自己的实现里复现这些模式抄不得不以逐行/逐模块的复制为路径不把原始受限材料源码、资源、机密配置纳入公开仓库的可分发树对照只发生在受控环境与结构化提取物上。claw-code 的仓库叙事明确把自己定位为clean-room rewrite / implementation并在 README 声明不主张原始材料所有权、且不与原作者关联## Ownership / Affiliation Disclaimer - This repository does **not** claim ownership of the original Claw Code source material. - This repository is **not affiliated with, endorsed by, or maintained by the original authors**.在 Rust README 中同样强调clean-room、inspired、不是 direct port/copyClaw Code is a local coding-agent CLI implemented in safe Rust. It is **Claude Code inspired** and developed as a **clean-room implementation**: it aims for a strong local agent experience, but it is **not** a direct port or copy of Claude Code.这些不是“装饰性声明”而是对协作方式的约束你贡献的东西必须能在公开仓库中自洽。2. 洁净室重写的工程分层推荐做法“洁净室”最容易失败在两个极端极端 A只做口头宣称不提供任何可验证的迁移依据 → 贡献者无法对齐目标极端 B把受限材料直接复制进仓库哪怕只是“临时对照” → 分发风险爆炸。比较稳的工程化分层是行为/接口层可公开对外 CLI、协议事件、数据结构、错误语义、权限与审计模型。结构/清单层可公开命令/工具/子系统的“表面枚举”用 JSON 快照承载。受控对照层不可公开如果确有对照需求应在本地 ignore 的归档中完成不进入 Git。claw-code 的reference_dataparity-audit组合正是在公开仓库里做了第 2 层并把第 3 层限定为“本地可选”。3. 仓库里具体是怎么做的可复用的模式3.1 把“对照目标”降维成可分发的 JSON 快照src/reference_data/存放commands_snapshot.json/tools_snapshot.json命令/工具镜像清单名称、来源提示、职责描述。archive_surface_snapshot.json归档表面统计根文件、根目录、TS-like 文件数、条目分母。subsystems/*.json各子系统的规模元数据与 sample_files。这些快照让对照从“我电脑里那坨源码长啥样”变成“Git 里有一份可审阅、可 diff 的底稿”。这正是「学得会」的一部分让新人不必访问受限材料也能理解目标轮廓。这部分的治理细节见result/11.md。3.2 把“像不像”量化为可重复报告而不是贴截图争论parity_audit.py计算根文件覆盖、目录覆盖、Python 文件数比、command/tool 条目数比、缺失清单并输出 Markdown。 \n重要的是它会在本地归档缺失时提示无法对照避免伪装完整对比。详见result/10.md。3.3 让移植期实现以“shim 报告”为主而不是立刻接真 I/OPython 侧的execute_command/execute_tool返回的是“would handle …”的镜像消息bootstrap_session输出Runtime SessionMarkdown包含路由、shim、流式事件、turn result、落盘路径。 \n这是一种洁净室友好的节奏先把调用契约与可观测面稳定下来再逐步替换为真实实现。参见result/02.md、result/08.md、result/09.md。3.4 用“阶段图 探针 CLI”让复杂启动可拆分验证bootstrap-graph、setup-report、bootstrap、*-mode这些子命令把运行时拆成可验证的切片让贡献者不需要“拥有原版”也能对齐工程节奏先能跑、能报告、能测再谈功能深度。参见result/14.md、result/13.md。3.5 Rust 侧用强类型把“策略与扩展接口”固化更像长期主线Rust workspace 把 clean-room 目标写得更产品化会话、compaction、commands、plugins 等都有明确 crate 边界。尤其是插件/钩子部分manifest、权限枚举、HookRunner 的 allow/deny/warn 语义都是“公开可学、不可照抄受限源代码”的典型实现形态。参见result/17.md、result/07.md。4. 公开仓库里怎么避免“无意复制”实操清单下面是一份偏工程流程的“护栏清单”适用于类似 claw-code 的再实现项目。4.1 仓库层护栏禁止提交受限归档把对照源保持在.gitignore的本地目录公开仓库只存结构化快照与自研实现。在 README 显式声明边界像 claw-code 这样写清“not affiliated / no ownership / clean-room”。把对照材料降维用快照 JSON 替代源码分发快照尽量只含name/path hint/count避免包含大量可重建实现细节。4.2 开发层护栏双人/双路径对照写实现的人尽量只看“接口/行为规范”由另一方在受控环境里做对照验收经典洁净室流程。避免逐行映射可以对齐“模块边界、状态机、协议事件形状”但不要对齐“函数名、内部变量、注释语句结构”。记录来源与理由PR 里写“改动目的/行为变化”而非“从某文件复制”。4.3 测试与审计护栏用可重复报告替代口头对齐parity-audit、setup-report、bootstrap等输出可贴 PR。把关键指标写进 CI像test_porting_workspace.py对快照条目数、CLI 输出关键字做断言。运行史可回放会话落盘、transcript、usage 对账并注意 PII 风险见result/06.md。5. 常见误区以及 claw-code 如何避免“没有源码就无法对齐”对齐的是架构模式与可观测行为不必对齐实现细节。claw-code 用快照清单与 parity 报告解决“目标不清”的问题。 \n2.“先实现功能再补文档/测试”洁净室项目最怕不可解释。claw-code 先把 CLI 报告与测试门禁立起来bootstrap、parity-audit、command-graph、tool-pool。 \n3.“把对照源当作主仓库的一部分”README 明确外泄快照不再是被跟踪源树公开仓库聚焦重写工作区。 \n4.“把相似度当成合法性结论”README 与文档都强调免责声明parity-audit的设计也避免在无归档时输出误导性比例。6. 小结在公开仓库里做洁净室重写要同时满足两件事让贡献者学得会通过可分发的对照底稿reference_data、可重复的对齐报告parity-audit、可观察的运行切片bootstrap/setup-report。让仓库抄不得不分发受限源码把对齐目标限制在架构/接口/清单用强类型与独立实现替代复制。claw-code 的实践可以概括为一句话对齐靠“数据化的表面事实”和“可验证的运行报告”而不是靠“共享受限源码树”。