本篇重点 ：不是讲"如何写更像"，而是讲"如何在公开仓库里把再实现做成可学习、可验证、可持续协作 ，同时尽量避免把不可授权材料变成可分发产物"。
涉及仓库证据 ：README 的 clean-room 叙事与免责声明、reference_data快照与parity-audit、Python/Rust 双轨结构。
1. 什么是「学得会、抄不得」
在工程语境里，"学得会"不等于"拿到源码照着敲"。更健康的目标是：
- 学得会：理解架构模式、运行时切分、协议边界、可观测性与测试策略，并能在自己的实现里复现这些模式；
- 抄不得 ：不以逐行/逐模块的复制为路径，不把原始受限材料（源码、资源、机密配置）纳入公开仓库的可分发树；对照只发生在受控环境 与结构化提取物上。
claw-code 的仓库叙事明确把自己定位为 clean-room rewrite / implementation，并在 README 声明：不主张原始材料所有权、且不与原作者关联：
225:229:README.md
## 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/copy：
1:4:rust/README.md
Claw 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_data + parity-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/O
Python 侧的 execute_command / execute_tool 返回的是"would handle ..."的镜像消息；bootstrap_session 输出 Runtime Session Markdown，包含路由、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 的实践可以概括为一句话：对齐靠"数据化的表面事实"和"可验证的运行报告"，而不是靠"共享受限源码树"。