claw-code 源码详细分析：Parity Audit——如何用工程对比把「像不像」从口水战变成可重复报告？

涉及源码src/parity_audit.py、src/reference_data/archive_surface_snapshot.json、commands_snapshot.json、tools_snapshot.jsonsrc/main.pytests/test_porting_workspace.py。1. 要解决什么问题大型移植里「我们已经很像原版了」最容易变成主观口水战有人看目录像有人看 CLI 像有人坚持行为仍不对。Parity Audit做的是把「像」拆成若干可计数、可写在 CI 里的维度每次跑run_parity_audit()得到同一形状的ParityAuditResult再to_markdown()成人类可贴进 PR 的段落——同一代码树 同一快照数据 ⇒ 同一数字从而把争论从「我觉得」推进到「报告显示」。重要边界与 README 一致这些指标衡量的是表面与清单维度的对齐倾向不是runtime 行为等价或法律意义上的「未侵权证明」。2. 报告长什么样ParityAuditResultto_markdown# 73:110:src/parity_audit.pydataclass(frozenTrue)classParityAuditResult:archive_present:boolroot_file_coverage:tuple[int,int]directory_coverage:tuple[int,int]total_file_ratio:tuple[int,int]command_entry_ratio:tuple[int,int]tool_entry_ratio:tuple[int,int]missing_root_targets:tuple[str,...]missing_directory_targets:tuple[str,...]defto_markdown(self)-str:lines[# Parity Audit]ifnotself.archive_present:lines.append(Local archive unavailable; parity audit cannot compare against the original snapshot.)return\n.join(lines)...五组核心度量归档存在时才会在 Markdown 里展开字段含义分子/分母直觉root_file_coverage归档根级 TS/TSX映射表中当前src/顶层是否出现对应.py文件名directory_coverage归档顶层子目录映射表中当前src/顶层是否出现对应包名/占位total_file_ratio当前src/下.py文件总数vs 参考 JSON 中的total_ts_like_filescommand_entry_ratiocommands_snapshot.json条目数vs 参考command_entry_counttool_entry_ratiotools_snapshot.json条目数vs 参考tool_entry_count另有两份缺失清单missing_root_targets、missing_directory_targets直接给出还没对齐的期望名方便开 issue / 拆任务。3. 「可重复」的数据从哪来3.1 冻结的参考面archive_surface_snapshot.json路径src/reference_data/archive_surface_snapshot.json。其中除列举根文件、根目录名外还提供分母# 60:62:src/reference_data/archive_surface_snapshot.jsontotal_ts_like_files:1902,command_entry_count:207,tool_entry_count:184}学习点分母不依赖你本机是否真有archive/目录——它来自随仓库提交的 JSON。这样 CI 在无归档环境下仍能比较「当前 Python 文件数 vs 某次钉死的 TS-like 文件数」与「当前快照条目数 vs 钉死的条目数」若to_markdown未因archive_present提前返回见下节。3.2 显式映射表ARCHIVE_ROOT_FILES/ARCHIVE_DIR_MAPPINGS根级文件一对一期望TS 名 → 当前src/顶层应存在的 Python 文件名# 13:31:src/parity_audit.pyARCHIVE_ROOT_FILES{QueryEngine.ts:QueryEngine.py,Task.ts:task.py,...main.tsx:main.py,...}子系统目录一对一期望归档目录名 → 当前src/顶层应有commands.py或包名如assistant# 34:69:src/parity_audit.pyARCHIVE_DIR_MAPPINGS{assistant:assistant,...native-ts:native_ts,...}学习点「像不像」里最容易扯皮的一块——根入口与顶层包是否齐——被钉死在两个字典里改期望 改表 改代码审查而不是聊天里重新定义。3.3 本地探测CURRENT_ROOT与ARCHIVE_ROOT# 7:11:src/parity_audit.pyARCHIVE_ROOTPath(__file__).resolve().parent.parent/archive/claw_code_ts_snapshot/srcCURRENT_ROOTPath(__file__).resolve().parentrun_parity_audit用CURRENT_ROOT.iterdir()的顶层名字与映射表比对用CURRENT_ROOT.rglob(*.py)统计全部 Python 文件数。# 121:127:src/parity_audit.pydefrun_parity_audit()-ParityAuditResult:current_entries{path.nameforpathinCURRENT_ROOT.iterdir()}root_hits[targetfortargetinARCHIVE_ROOT_FILES.values()iftargetincurrent_entries]dir_hits[targetfortargetinARCHIVE_DIR_MAPPINGS.values()iftargetincurrent_entries]missing_rootstuple(targetfortargetinARCHIVE_ROOT_FILES.values()iftargetnotincurrent_entries)missing_dirstuple(targetfortargetinARCHIVE_DIR_MAPPINGS.values()iftargetnotincurrent_entries)注意archive_present仅检测ARCHIVE_ROOT.exists()审计逻辑本身不读取归档内文件列表对比的是本仓库的src/树 参考 JSON 映射表。3.4archive_present与 Markdown 输出的关系当本地无归档目录时to_markdown()提前返回上面那些分子分母一行都不会打印# 86:88:src/parity_audit.pyifnotself.archive_present:lines.append(Local archive unavailable; parity audit cannot compare against the original snapshot.)return\n.join(lines)因此有归档适合贴完整Parity Audit段落进 PR。无归档CLI 仍执行run_parity_audit()但对外报告刻意缩短——提醒「无法对照本地快照」避免误以为做过完整对比。若要在无归档 CI 里仍断言数字应直接测ParityAuditResult字段见下不要只解析 Markdown。4. 命令/工具条目清单长度 vs 参考分母# 133:135:src/parity_audit.pytotal_file_ratio(current_python_files,int(reference[total_ts_like_files])),command_entry_ratio(_snapshot_count(COMMAND_SNAPSHOT_PATH),int(reference[command_entry_count])),tool_entry_ratio(_snapshot_count(TOOL_SNAPSHOT_PATH),int(reference[tool_entry_count])),# 117:118:src/parity_audit.pydef_snapshot_count(path:Path)-int:returnlen(json.loads(path.read_text()))学习点命令/工具「像不像」被操作化为JSON 数组长度与钉死分母的比。更新镜像清单时可同时更新archive_surface_snapshot.json里的command_entry_count/tool_entry_count若归档侧枚举变了否则会出现「条目多了但分母旧」的比值大于 1 的语义——维护者需在评审里约定是否允许分子大于分母或同步 bump 参考值。5. 如何变成「可重复」CI 与测试CLI# 104:106:src/main.pyifargs.commandparity-audit:print(run_parity_audit().to_markdown())return0测试test_parity_audit_runs子进程跑parity-audit断言输出含Parity Audit有无归档均过。test_root_file_coverage_is_complete_when_local_archive_exists仅当audit.archive_present时断言根文件全覆盖、目录覆盖 ≥28、命令条目 ≥150、工具条目 ≥100。# 45:51:tests/test_porting_workspace.pydeftest_root_file_coverage_is_complete_when_local_archive_exists(self)-None:auditrun_parity_audit()ifaudit.archive_present:self.assertEqual(audit.root_file_coverage[0],audit.root_file_coverage[1])self.assertGreaterEqual(audit.directory_coverage[0],28)self.assertGreaterEqual(audit.command_entry_ratio[0],150)self.assertGreaterEqual(audit.tool_entry_ratio[0],100)可重复报告在这里体现为开发者机器上有归档时门槛测试必须绿无归档时跳过强断言但test_command_and_tool_snapshots_are_nontrivial仍对PORTED_COMMANDS/PORTED_TOOLS长度保底。6. Parity Audit没有回答什么避免误用行为不跑 TS/Python 双端 E2E不对比 API 响应体。质量不衡量测试覆盖率、类型完整度。安全/合规不是法律或版权结论。归档内容一致性不 diff 归档里每个文件与 Python 实现只认映射表 顶层存在性 文件计数 快照条目数。仓库内PARITY.mdRust 侧另有一套功能差距叙述与 Pythonparity_audit互补而非重复。7. 如何把报告用得「更工程」PR 模板要求贴python3 -m src.main parity-audit输出有归档环境时。趋势把ParityAuditResult五元比例随时间画线CI artifact看移植是否在收敛。扩展维度在不动现有字段的前提下可增加Rust workspace 指标、behavioral parity 用例通过数等仍通过dataclass to_markdown输出保持「一次运行、一份报告」。无归档 CI对run_parity_audit()的数值做结构化导出JSON避免依赖被archive_present截断的 Markdown。8. 小结Parity Audit用冻结参考 JSON 显式 TS→Py 映射 本地src/扫描 快照条目计数把「像不像」压成可重复的ParityAuditResult。to_markdown()提供人类可读、可贴 PR的固定格式archive_present控制是否输出完整指标体现数据治理无归档不强装完整对比。测试把关键门槛编码为断言使「像」在有归档的开发环境下成为门禁而非口头禅。