多份技术文档间缺乏一致性检查，易产生内容冲突

[V1ki]

背景

ZeRo OS 的核心文档包括 Architecture.md、TechStack.md、ContextEngineering.md、UI-UX.md、Milestones.md 等。这些文档相互关联，共同定义系统的架构、技术实现和设计规范。由于缺乏自动化的一致性检查机制，文档间容易出现术语定义不一致、路径描述冲突、配置示例矛盾等问题。这些冲突会降低文档可信度，导致开发者和 AI 基于错误信息做出决策。

借鉴 Hamel 的评估方法论，文档质量应作为系统可观测、可评估的一部分。文档间的冲突应被量化、跟踪，并作为系统健康度的指标之一。

问题描述

• 不同文档对同一概念（如“Session”、“Tool”）的定义可能存在差异。
• 文档中引用的文件路径、配置字段、命令示例等，在不同文档中可能不一致。
• 文档间的依赖关系（如 TechStack 中提到的“包间依赖关系”需与 Architecture 中的模块划分吻合）未得到验证。
• 没有自动化工具定期扫描文档并报告冲突，冲突往往在人工阅读时才发现，修复成本高。
• 没有历史记录追踪文档冲突的出现和解决情况，无法评估文档维护质量。

影响

• 开发误导：开发者和 AI 依据过时或冲突的文档做出错误实现。
• 维护成本：人工排查文档冲突耗时且容易遗漏。
• 评估失真：若文档作为 evaluator 的输入，冲突的文档会导致评估结果偏差。
• 团队协作效率：多人修改时，缺乏冲突预警机制，容易产生合并冲突。

建议解决方案

阶段一：定义文档一致性规则

• 创建 DOCS_RULES.md，明确文档间应遵守的约束，例如：
  • 术语表：核心概念（Session、Tool、Skill 等）应保持统一定义。
  • 路径一致性：如 .zero/logs/sessions/ 在所有文档中描述一致。
  • 配置字段：如 config.yaml 中的字段名和格式应一致。
  • 依赖关系：TechStack 中的“包间依赖关系”需与 Architecture 中的模块划分吻合。
• 规则应结构化，便于自动化检测（如正则、YAML 提取）。

阶段二：开发文档一致性检查技能

• 开发 docs-consistency 技能，输入文档路径集合，输出冲突报告。
• 技能包含：
  • 解析器：用 gray-matter 提取 frontmatter，用正则或 LLM 提取关键定义。
  • 对比器：对不同文档中的同名/关联字段进行比对（字符串比对或语义相似度）。
  • 报告生成器：输出 Markdown 格式的冲突列表，包含冲突位置、原文及建议统一值。
• 技能可作为独立工具运行，也可集成到 CI 流程。

阶段三：集成到工作流

• CI 流程：在 PR 中自动运行 docs-consistency，将报告作为评论，提醒作者处理冲突。
• Scheduler 定期任务：每周自动扫描全量文档，生成冲突报告存入 .zero/logs/，并在 Dashboard 中展示摘要。
• Web UI 集成：在 Metrics 页面增加“文档一致性”面板，展示冲突数量、趋势、历史记录。

阶段四：记录与评估

• 将检测到的冲突事件写入 incidents/（类型 docs-conflict），包含冲突文档、冲突类型、解决状态。
• 统计冲突解决率、平均解决时间等指标，纳入系统健康度评估。
• 借鉴 Hamel 的评估框架，将文档冲突作为一个 failure mode，设计 evaluator 自动检测并校准。

验收标准

• 存在 DOCS_RULES.md 并至少覆盖 5 条核心一致性规则。
• docs-consistency 技能可独立运行，输出结构化的冲突报告。
• 在 PR 中，技能能自动评论冲突（可配置为可选触发）。
• Scheduler 每周自动扫描并生成报告，报告存入指定路径。
• 冲突事件被记录到 incidents/，并包含冲突详情。
• Metrics 页面显示“文档冲突数”趋势图。
• 至少在一个真实场景中验证过（例如：修改 Architecture.md 中 Session 定义，技能检测到与 TechStack.md 不一致）。

优先级

P3（中等影响，中等复杂度）——建议纳入 M9 或后续迭代。