用途:让项目文档随时间与代码保持一致。适用于文档过时、发布前核对、代码完成后同步文档、新建文档、术语争议等场景。
主要能力:按流程分派任务,包括全量审计、增量复查、写路径更新、词典维护、新建文档。维护两个产物:docs/DICTIONARY.md 术语词典,以及 docs/README.md 或 docs/INDEX.md 中的文档索引表(含 Doc、What、Class、Owns 列)。常青文档末尾带 <!-- doc-audit:last-reviewed --> 标记块,记录复核日期、commit 与延迟项。提供脚本 docmaint(scan | stamp | stale),只做机械扫描,不编辑文档,需用绝对路径调用并传 --root。
使用方式:先分类再编辑。常青文档(README、教程、现行 API 参考)须反映当前现实,漂移即缺陷;时点文档(设计规格、计划、脑暴笔记)只在其日期成立,不得改写以匹配代码,最多加取代横幅或日期。分类须在组级别完成并经人工确认,这是不可跳过的一步。仅当文档为常青、声明为机械性(标识符、路径、CLI 标志、配置名与默认值、API 路由字段、token 级示例)、代码中存在唯一非测试对应物、替换后句子仍成立、且经 git 历史确认对应物是删除而非改名时,才可自动修复。计数与清单、裸行号引用、否定性声明、交叉引用修复、示例结构改写、行为语义声明、真值在外部仓库的声明,一律转人工。验证要查动词而非名词,即找到实际执行该行为的代码路径。
限制:不编辑被 git 忽略、生成或标注“请勿编辑”的文件;不自动提交审计结果;无独立验证不得打标记;每个项目只维护两个元数据产物,不加第三个;无读者的文档不写。