代码变更后文档更新缺乏检测与提醒机制 #2
Description
背景
ZeRo OS 支持 AI 自主修改代码。当 Agent 通过 Write/Edit 工具修改代码文件后，对应的技术文档（如 Architecture.md、TechStack.md、API.md 等）往往需要同步更新，以反映最新的实现。目前系统没有任何机制检测这种不一致，也没有提醒用户或 AI 更新文档。这导致文档逐渐与代码脱节，影响后续开发和 AI 的自我进化。
借鉴 Codex 的最佳实践，可重复的工作应技能化，可预测的流程应自动化。文档同步正是一个可重复且可预测的任务，应纳入系统自动管理。
问题描述
- 当 Agent 修改代码时，没有自动分析哪些文档可能受影响。
- 代码提交（git commit / push）时，没有检查文档是否需要更新。
- 没有集中记录“代码-文档不一致”的事件，无法追踪陈旧文档的历史。
- 系统健康度指标中缺少文档陈旧度相关数据，无法量化评估。
影响
- 维护困难：后续开发者（包括人类和 AI）基于过时文档做出错误决策。
- 质量下降：文档可信度降低，逐渐被废弃。
- 评估失真：若文档作为 evaluator 的输入，过时文档会导致评估结果偏差。
- AI 自我进化受阻：AI 依赖文档学习规则，若文档与代码不符，会学到错误知识。
建议解决方案
阶段一：建立文档-代码映射
- 创建
docs-map.json（或 YAML），记录代码文件与文档章节的对应关系。例如：
{
"src/core/session.ts": ["docs/architecture.md#session", "docs/api/session.md"],
"packages/model/src/adapters/anthropic.ts": ["docs/techstack.md#anthropic-adapter"]
}- 初始映射由人工维护，后续可由 AI 辅助更新（当新建文件时，AI 可询问是否需要关联文档）。
阶段二：开发文档影响分析技能
- 开发
docs-impact技能，输入代码文件 diff，输出受影响的文档列表及更新建议。 - 技能调用流程：
- 根据映射找到可能受影响的文档。
- 读取文档对应章节内容。
- 调用 LLM 分析 diff 与文档内容，判断是否需要更新，并生成更新草案。
- 技能输出结构化报告，包含：受影响文档、更新必要性（必须/建议/无需）、更新建议文本、置信度。
阶段三：集成到工作流
- Agent 开发中：代码修改后，Agent 主动调用
docs-impact，将报告追加到当前 Session 的system_notice中，提醒用户（或自身）更新文档。可配置为自动应用更新草案（需用户授权）。 - Git pre-commit 钩子：检测本次变更涉及的文件，若有文档需要更新但未更新，则警告并可选择阻止提交。
- Git pre-push / PR 检查：运行全面分析，将报告作为 PR 评论，要求人工确认。
- 发布前检查：在 CI 中运行文档一致性检查，若有不一致则阻断发布。
阶段四：记录与评估
- 将文档不一致事件写入
incidents/（类型docs-out-of-sync），并关联对应的代码变更哈希和文档建议。 - 定期统计文档陈旧度（例如：代码变更次数与文档最后更新时间之差），作为 metrics 存入
metrics.db，并在 Web UI 的 Metrics 页面增加“文档健康度”面板。 - 借鉴 Hamel 的评估框架，将文档不一致作为一个 failure mode，设计 evaluator 自动检测并校准。
阶段五：长期优化
- 根据历史数据，优化
docs-map.json的覆盖率和准确性。 - 将常见的文档更新模式固化到
AGENTS.md或DOCS_RULES.md中，作为 Agent 的行为约束。
验收标准
- 存在
docs-map.json并至少覆盖核心代码与文档的映射。 -
docs-impact技能可独立运行，输出结构化的文档更新建议。 - Agent 修改代码后能主动调用
docs-impact并展示提醒（通过system_notice）。 - Git pre-commit 钩子在检测到文档未同步时发出警告。
- 文档不一致事件被记录到
incidents/，并包含代码变更哈希和文档建议。 - Metrics 页面显示“文档陈旧度”趋势图。
- 至少在一个真实场景中验证过（例如：修改
session.ts后，docs-impact正确指出需要更新architecture.md#session）。
优先级
P2（高影响，中复杂度）——建议纳入 M8 或 M9 里程碑。