核心用法
Golden Master 是一款文件血缘追踪工具，专注于建立"单一数据源"与派生文件之间的可验证关系。其核心 workflow 包含四个操作：
1. Analyze（分析关系）：扫描目录内容，基于文本相似度智能推荐潜在的主从文件关系，输出置信度评分
2. Establish（建立追踪）：为确认的关系生成标准化元数据注释，插入到源文件和派生文件的头部
3. Validate（验证新鲜度）：比对当前校验和与存储值，输出"新鲜/过期"状态报告，精确显示源文件的变更差异
4. Refresh（刷新校验）：人工同步内容后更新元数据，建立新的基准线
技术实现上采用 SHA256 校验和，配合内容标准化（统一换行符、去除尾随空格、过滤自身元数据），确保哈希的稳定性。
显著优点
- 精准定位过期内容：传统文档维护依赖人工记忆，此工具通过机器可验证的校验和实现自动化 staleness 检测
- 非侵入式设计：仅添加注释性元数据，不改变原有文件结构和渲染输出
- 可追溯审计：记录派生时间戳和源文件变更详情，支持 12 天过期等量化评估
- 灵活部署：支持文件内嵌注释（推荐）和独立 manifest 两种模式
局限与风险
- 仅追踪结构，不验证语义：工具检测"源文件是否变更"，但不保证"派生内容是否正确同步"——仍需人工审查变更 diff
- 单仓库限制：v1.0 不支持跨仓库追踪，monorepo 场景下需配合路径约定
- 关系发现依赖确认：AI 推荐的相似文件需要人工审核，避免误将巧合相似建立为正式关系
- 校验和碰撞：8 字符截断显示虽为可读性妥协，理论上存在极低概率的碰撞风险
适合人群
- 维护复杂文档体系的开发者（README、架构文档、API 指南多层派生场景）
- 需要确保代码示例与源码同步的技术写作者
- 追求文档即代码（Docs as Code）实践的工程团队
常规风险
| 风险场景 | 缓解措施 |
|---------|---------|
忘记运行 refresh 导致持续误报过期 | 集成 CI 流程，提交前强制校验 |
| 手动编辑元数据破坏格式 | 使用 establish/refresh 命令，禁止直接修改注释 |
| 敏感文件意外纳入追踪 | 配置 .golden-master-ignore 排除机密路径 |