claw-code 源码详细分析：`reference_data` JSON 快照——大型移植里「对照底稿」该怎么治理与演进？

范围src/reference_data/下archive_surface_snapshot.json、commands_snapshot.json、tools_snapshot.json、subsystems/*.json及 Python 侧消费方式衔接result/10.mdParity Audit。1. 「对照底稿」在仓库里扮演什么角色在 claw-code 这类大型、对照式移植中reference_data不是业务配置而是从归档源树抽取、可随 Git 追踪的「事实快照」不把完整 TypeScript 归档塞进主分支时仍需要可 diff、可计数、可测试的「当时表面长什么样」。运行时/CLI 的清单、路由、审计、占位包元数据都从这里读避免「口头对齐」。模块说明写得很直白# 1:1:src/reference_data/__init__.pyTracked snapshot metadata extracted from the local TypeScript archive.下文按文件族说明职责再谈治理与演进。2. 快照分层三类数据2.1 全局表面archive_surface_snapshot.json内容要点归档根文件列表、根目录列表、以及用于 Parity 分母的total_ts_like_files、command_entry_count、tool_entry_count见result/10.md。消费者parity_audit.py的_reference_surface()与条目计数对比。性质描述「某次钉死的归档统计」与parity_audit里ARCHIVE_ROOT_FILES/ARCHIVE_DIR_MAPPINGS互补映射表在.py里统计在 JSON 里。2.2 命令/工具镜像清单commands_snapshot.json、tools_snapshot.json每条记录典型字段name、source_hint、responsibility。消费者commands.py/tools.py在 import 时lru_cache加载为PORTED_COMMANDS/PORTED_TOOLS驱动路由、shim、QueryEngine 摘要、command-graph、tool-pool经get_*等整条链见result/08.md、result/09.md。性质可执行面与审计面的主清单体积大、变更频率可能高于archive_surface。2.3 子系统元数据subsystems/name.json典型结构示例assistant#1:8:src/reference_data/subsystems/assistant.json{archive_name:assistant,package_name:assistant,module_count:1,sample_files:[assistant/sessionHistory.ts]}消费者对应包src/name/__init__.py统一模式读 JSON → 暴露ARCHIVE_NAME、MODULE_COUNT、SAMPLE_FILES、PORTING_NOTE。性质占位包与文档/测试的锚点——证明「这个 Python 包对应归档里的哪棵子树、规模量级、样例路径」不要求列出全部文件。3. 消费模式与工程后果3.1 Import 时加载 缓存命令/工具快照经lru_cache(maxsize1)缓存在进程内子系统包在import 时read_text()。后果本地改 JSON 后长跑进程需重启才能看到新清单测试子进程通常无此问题。3.2 单一文件路径、硬编码相对路径各模块用Path(__file__).resolve().parent...定位reference_data。后果禁止随意移动reference_data目录而不全库替换路径若未来要拆包应集中一个SNAPSHOT_ROOT常量或资源发现层避免 20 处重复相对路径当前为移植期可接受重复。3.3 测试对快照的隐式契约例如# 73:79:tests/test_porting_workspace.pydeftest_subsystem_packages_expose_archive_metadata(self)-None:fromsrcimportassistant,bridge,utils self.assertGreater(assistant.MODULE_COUNT,0)self.assertGreater(bridge.MODULE_COUNT,0)self.assertGreater(utils.MODULE_COUNT,100)self.assertTrue(utils.SAMPLE_FILES)治理含义改utils.json的module_count若低于 100 会红 CI——这是故意的防回归锚点演进时需同步调整测试阈值或改为更稳的断言例如与生成脚本校验一致。4. 治理原则把底稿当「受控数据产品」4.1 单一事实来源与字段一致性commands_snapshot.json条目数与archive_surface_snapshot.json中command_entry_count理想上应同源生成或在 PR 说明里解释为何分子分母刻意不同例如故意多镜像辅助文件。同理tool 条目数与tool_entry_count。archive_surface里的root_dirs与parity_audit.ARCHIVE_DIR_MAPPINGS新增子系统时往往要两处都改或将来收敛为从 JSON 生成映射否则会出现Parity 报缺失而子系统 JSON 已存在等分裂。4.2 变更评审清单建议是否必须进主仓库是否含许可证/隐私风险路径字符串一般仅相对路径风险低。是否与生成脚本一致若团队有extract-snapshots-from-archive.pyPR 应附命令 输入版本说明。是否同步更新archive_surface分母、parity映射表、相关测试阈值。Diff 可读性大 JSON 单行 vs 格式化GitHub 对巨大 diff 不友好时可分 PR先工具后命令等。4.3 版本与 schema当前缺口与建议当前 JSON无schema_version字段。演进建议在顶层增加schema_version: 1或按文件族分版本loader 用宽容解析缺省版本走旧逻辑。对commands_snapshot/tools_snapshot可维护JSON Schema文件可选CI 用jsonschema校验避免手改 typo 导致 import 崩。4.4 与「不可分发归档」的边界README 强调归档可gitignorereference_data是允许跟踪的提取物。治理上应坚持底稿 结构化元数据 清单不用快照替代完整专有源码的分发。更新底稿时记录来源commit、日期、工具版本便于审计「这条source_hint从哪棵树来」。5. 演进策略如何长大而不乱5.1 增量镜像新增命令/工具往commands_snapshot/tools_snapshot追加条目若归档枚举变了** bump**archive_surface中对应*_entry_count或重跑生成器一次更新全文件。新增子系统新增subsystems/foo.jsonsrc/foo/__init__.py模板 parity_audit映射若该包须在顶层出现。5.2 破坏性变更重命名字段如source_hint→path需版本号 兼容读取或单原子 PR改全仓库 loader。删减大量条目可能影响路由与 golden CLI 测试应同时更新tests/test_porting_workspace.py中route/show-tool等用例。5.3 自动化优先成熟团队通常会在有归档的受控环境跑提取脚本→ 覆盖reference_data。CI 跑parity-audit 单元测试 可选快照条数 archive_surface 分母。人工只审生成 diff 摘要不手改千行 JSON。5.4sample_files膨胀utils.json等可能含很长sample_files列表。治理上可设上限只保留 N 个代表性路径或改为sample_files_hash 外部 manifest避免 PR noise需与测试SAMPLE_FILES非空协调。6. 与 Parity Audit、路由、占位包的关系一张图archive_surface_snapshot.jsoncommands_snapshot.jsontools_snapshot.jsonsubsystems/*.jsonparity_auditcommands.py / tools.pysrc/*/ __init__.pyParityASCS/TS长度 src/树 .py内映射表。运行清单CS/TS→PORTED_*。子系统故事SS→ 各包常量。7. 小结reference_data是大型移植的对照底稿全局表面统计、命令/工具全清单、子系统轻量元数据三层分工明确。治理核心是与 Parity 映射、分母字段、测试阈值共演进优先机器生成 CI 校验schema/版本为长期必备。演进时把 JSON 当受版本控制的 API_additive 容易_breaking 要原子迁移与兼容策略。