datarim-doctor 技能 — 让运维文件保持诚实
datarim-doctor 技能如何为 Datarim 的运维索引定义一套精简的单行契约,并运行 8 遍迁移来强制执行它,同时不丢失任何一条任务记录。
随着项目增长,tasks.md 和 backlog.md 会积累遗留的块状条目、过时的章节,以及不断膨胀的完成日志,这些内容会撑大 agent 在每条命令开始时读取的上下文。datarim-doctor 技能定义了这些文件必须遵循的规范精简契约,以及让它们达到该状态的迁移算法。
精简索引契约
tasks.md 和 backlog.md 中的每一行回答四个问题——哪个任务、什么状态、什么复杂度,以及描述文件位于何处——除此之外别无其他。规范格式是一个匹配严格正则表达式的单条项目符号:任务 ID、状态、优先级、级别、标题,以及指向描述文件的箭头指针。没有散文,没有子项目符号,没有内联需求。
所有任务内容都存放在单独的文件中:datarim/tasks/{TASK-ID}-task-description.md。该文件包含一个 12 键的 YAML frontmatter 块,以及最多 250 行的正文内容,分布在五个固定章节中:Overview、Acceptance Criteria、Constraints、Out of Scope 和 Related。doctor 同时强制执行索引行格式和描述文件 schema。
8 遍迁移
迁移脚本按固定顺序应用各个遍次。第 0 遍拒绝 tasks.md 内的 ## Backlog 章节——doctor 不会自动迁移它,因为每个项目符号的语义意图未知。第 1 遍遍历遗留的块状标题,从正文文本中提取 frontmatter 字段,并将每个字段写入新的描述文件。第 2 遍将索引文件重写为精简的单行条目。第 3 遍从 activeContext.md 中剥离已废除的滚动日志章节,并删除 progress.md。第 4 遍将遗留的 backlog-archive.md 迁移为按任务划分的归档文档。第 6 遍从运维文件中剥离归档章节。第 7 遍移除指向现有归档文档的已验证 HTML 注释标记。第 5 遍在变更遍次之后重新扫描整棵树,以断言结果符合规范。
数据丢失安全契约
每次 --fix 调用在触碰任何文件之前都会运行四道安全护栏。整个 datarim/ 目录的 tarball 会在任何变更之前落到 /tmp 中。第 4 遍迁移的每个遗留文件旁边都会放置一份 .pre-v2.bak 副本。计数不变量要求输出的任务条目数量至少与解析的数量一样多——如果计数下降,脚本会从 tarball 恢复并以代码 2 退出。文件锁防止并发调用相互竞争。
幂等性守卫意味着对已符合规范的树再次执行 --fix 会立即以 0 退出。--quiet 标志由 /dr-init 自愈使用,以在没有任何输出的情况下检查合规性——只返回退出代码。
为什么精简索引很重要
agent 读取一个 100 KB 的单体 tasks.md 会消耗上下文预算在它并不需要的内容上。精简索引将该读取量削减到 1 KB 以下。任务描述在具体任务被处理时按需加载。完成历史永远不会被镜像回运维文件——它只存在于 documentation/archive/ 和 git log 中,那才是它该待的地方。
关于 doctor 强制执行的完整运维文件 schema,请参阅 datarim-system 技能文章。/dr-doctor 命令封装了迁移脚本以供交互式使用。