Skip to content

[Docs] docs index 无内容变化时保持工作树稳定 #99

Description

@liuli195

关联规范

背景

docs index 每次运行都会更新多个 catalog 的 generated_at,即使内容本身没有实质变化,也会造成工作树 churn。PR Flow / governance 改动中这会放大 diff、增加 pathref/governance 验证噪音,并让 review 更难聚焦真正变化。

产品解决方案

让 docs index 生成保持稳定:无内容变化时不改文件;只有 catalog 内容 hash 变化时才更新对应文件。时间戳不应成为每次运行都改动的主内容。

用户视角:运行 docs index 后,如果没有实际文档索引变化,工作树保持干净。

技术实现方案

  1. 为 docs catalog 生成增加内容规范化步骤,生成前剔除或稳定化 generated_at
  2. 写文件前比较规范化内容 hash;无变化则不写文件。
  3. 如果必须保留生成时间,移到单独 metadata 文件,或只在内容 hash 变化时更新。
  4. 增加测试:连续运行 docs index 两次,第二次 git diff 为空。
  5. 确保 pathref/full governance 仍读取同一 catalog schema。

Acceptance criteria

  • 连续两次运行 docs index,第二次不产生工作树改动。
  • 内容变化时对应 catalog 正常更新。
  • pathref.full 和 governance.full 仍通过。
  • 生成时间不会单独造成 diff churn。

Blocked by

None - can start immediately

Metadata

Metadata

Assignees

No one assigned

    Labels

    priority:P2Medium priority: efficiency or operator-experience improvementready-for-agent

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions