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

范围 ：src/reference_data/ 下 archive_surface_snapshot.json、commands_snapshot.json、tools_snapshot.json、subsystems/*.json ，及 Python 侧消费方式；衔接 result/10.md（Parity Audit）。

---

1. 「对照底稿」在仓库里扮演什么角色

在 claw-code 这类 大型、对照式移植 中，reference_data 不是业务配置，而是 从归档源树抽取、可随 Git 追踪的「事实快照」：

• 不 把完整 TypeScript 归档塞进主分支时，仍需要 可 diff、可计数、可测试 的「当时表面长什么样」。
• 运行时/CLI 的 清单、路由、审计、占位包元数据 都从这里读，避免「口头对齐」。

模块说明写得很直白：

# 1:1:src/reference_data/__init__.py
"""Tracked 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(maxsize=1) 缓存在进程内；子系统包在 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.py
    def test_subsystem_packages_expose_archive_metadata(self) -> None:
        from src import assistant, 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 变更评审清单（建议）

1. 是否必须进主仓库：是否含许可证/隐私风险路径字符串（一般仅相对路径，风险低）。
2. 是否与生成脚本一致 ：若团队有 extract-snapshots-from-archive.py，PR 应附 命令 + 输入版本说明。
3. 是否同步更新 ：archive_surface 分母、parity 映射表、相关测试阈值。
4. 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 强调归档可 gitignore ；reference_data 是允许跟踪的提取物。治理上应坚持：

• 底稿 = 结构化元数据 + 清单，不 用快照替代 完整专有源码 的分发。
• 更新底稿时 记录来源 （commit、日期、工具版本），便于审计「这条 source_hint 从哪棵树来」。

---

5. 演进策略（如何长大而不乱）

5.1 增量镜像

• 新增命令/工具 ：往 commands_snapshot / tools_snapshot 追加 条目；若归档枚举变了，** bump** archive_surface 中对应 *_entry_count（或重跑生成器一次更新全文件）。
• 新增子系统 ：新增 subsystems/foo.json + src/foo/__init__.py 模板 + parity_audit 映射（若该包须在顶层出现）。

5.2 破坏性变更

• 重命名字段 （如 source_hint → path）：需 版本号 + 兼容读取 或 单原子 PR 改全仓库 loader。
• 删减大量条目 ：可能影响 路由与 golden CLI 测试 ；应同时更新 tests/test_porting_workspace.py 中 route/show-tool 等用例。

5.3 自动化优先

成熟团队通常会：

1. 在 有归档的受控环境 跑 提取脚本 → 覆盖 reference_data。
2. CI 跑 parity-audit + 单元测试 +（可选）快照条数 == archive_surface 分母。
3. 人工只审 生成 diff 摘要，不手改千行 JSON。

5.4 sample_files 膨胀

utils.json 等可能含 很长 sample_files 列表。治理上可设 上限 （只保留 N 个代表性路径）或改为 sample_files_hash + 外部 manifest ，避免 PR noise；需与 测试 （SAMPLE_FILES 非空）协调。

---

6. 与 Parity Audit、路由、占位包的关系（一张图）

archive_surface_snapshot.json
commands_snapshot.json
tools_snapshot.json
subsystems/*.json
parity_audit
commands.py / tools.py
src/*/ init.py

• Parity ：AS + CS/TS 长度 + src/ 树 + .py 内映射表。
• 运行清单 ：CS/TS → PORTED_*。
• 子系统故事 ：SS → 各包常量。

---

7. 小结

• reference_data 是大型移植的 对照底稿 ：全局表面统计 、命令/工具全清单 、子系统轻量元数据 三层分工明确。
• 治理 核心是：与 Parity 映射、分母字段、测试阈值共演进 ；优先机器生成 + CI 校验 ；schema/版本 为长期必备。
• 演进 时把 JSON 当 受版本控制的 API：_additive 容易，_breaking 要原子迁移与兼容策略。

---