harmonize-docs

统一文档

让文档连贯地说明实现、意图和剩余工作。为每项长期有效的事实和可变状态指定唯一的权威来源；其他阅读路径应链接到该来源。优先删减过时或重复的材料，同时保留理解、理由、运维或决策所需的细节。

范围

未指定范围时，覆盖仓库中所有仍在使用的文档。若明确指定了变更、路径、主题、计划、子系统或对比对象，则以该对象为起点，并将范围限定为它及其必要的文档影响：权威文档、受影响的计划和状态记录、导航及交叉引用。针对限定范围的任务，不要盘点整个仓库。

对于 changes，使用已有的变更集；若未指定，则使用当前暂存、未暂存和未跟踪的变更。如果不存在有意义的变更集，应先确定边界，而不是用无关的历史记录替代。

纳入文档专属的导航和配置。源代码可作为证据，但不属于编辑范围。排除归档、生成文件、供应商文件和依赖项；保留不可变的历史记录，同时修正当前状态的表述或指向历史记录的路径。记录可信的无关冲突以便后续跟进，但不要因此扩大范围。

分开陈述各类信息

清晰区分以下状态：

• **实现现状：**通过代码、配置、测试、命令或发布版本核实的行为和运维边界。
• **目标设计：**依据最新确认的方向，已选定、已提议或尚未解决的未来行为。
• **交付状态：**根据仓库现有的规划惯例标明已完成、进行中、受阻、已延期和后续工作。

已接受的设计不等于已实现的行为。仅有源代码实现，并不能证明已完成验证、发布、支持、授权或具备生产就绪条件。应通过清晰的文档定位、时态或简洁的状态表来区分这些内容；避免在每句话中重复限定说明。

协调文档

阅读范围内的每份文档，并根据相应证据核实其中的重要声明。梳理决策和有用的理由；揭示尚未解决的冲突，不要臆造意图。可将不同领域的工作委派给其他人，但协调者负责确保覆盖完整并整合结果。

为每份文档确定其用途、受众、范围和生命周期。保留已经简洁且有效的文档。根据内容归属或读者路径的需要，重写、合并、拆分、移动或删除材料；只有当某项职责具有独立且长期的意义时，才创建新文档。修改这些文件时，保留工具可识别的指令发现机制和优先级规则。

创建、重写、拆分、合并或移动 ARCHITECTURE.md 时，请阅读架构文档指南。明确标示目标架构；让计划负责记录交付顺序和剩余工作，避免架构文档变成第二份路线图。

直接落实协调后的结果。在恰当的位置整合更新，删减已被取代的说法和类似对话记录的历史内容，并修复受影响的链接、命令、术语和导航。即使原有措辞或位置不再合适，也要保留有用的意图。除非另有明确要求，否则不要暂存、提交或推送。

完成

通读最终文档。检查受影响的链接、路径、示例和命令；搜索过时术语和相互矛盾的说法。如果易变的计数没有持久用途，则用稳定事实或源文档链接替代。

双向检查文档衔接：已完成的工作应体现在当前状态文档和进度记录中，尚未完成的设计则应明确标示为未实现。直接入口概览应指向与详细计划相同的权威状态。核查所有范围内的文档和冲突，运行相关的可用检查，并修复重写导致的问题。

报告有意义的修正、所有权或拓扑变更、验证结果及未解决的限制。确保范围内的文档彼此一致，且读者能够找到已有内容、计划内容和未完成事项。