/dr-doctor 命令 — Datarim 文件的结构健康检查
/dr-doctor 如何诊断并修复 Datarim 运维文件:将旧式块状任务迁移为精简的单行 schema、外置描述内容,并移除已废弃的 progress.md。
Datarim 运维文件具有规范结构。当任务经过数月累积后,该结构会发生偏移:块状标题与单行条目混杂,描述性文字在 tasks.md 内肆意蔓延,而一个已废弃的 progress.md 从更早的 schema 版本残留下来。/dr-doctor 可以修复所有这些情况。
该命令是幂等的。在完全合规的项目上运行它不会产生任何输出,并会干净退出。在旧式目录树上运行它,会迁移每一个不合规文件,然后验证结果——第二次运行始终返回零发现。
何时运行
有三种触发场景会让 /dr-doctor 登场。最常见的是手动触发:tasks.md 或 backlog.md 已变得很大,或包含混合格式的条目。第二种是自动触发:/dr-init 的 Step 0.6 会运行结构合规性探测,并在其返回非零退出码时重定向到这里。第三种是在升级到 Datarim v1.19.0 或更高版本之后——首次运行会执行 schema 迁移。
/dr-archive 处的归档前检查也会以合规性作为门槛,因此未清理的目录树会在任何任务被关闭之前在这里暴露出来。
先试运行,再应用
默认模式是试运行。该命令会报告一个四行计数表:旧式块状标题、旧式粗体 ID 条目、不合规的项目符号行,以及 progress.md 是否仍然存在。如果所有计数均为零,运行会静默退出。如果存在发现,命令会在改动任何内容之前进行提示。
传入 --fix 以应用迁移。在底层,scripts/datarim-doctor.sh 会获取文件锁,按文件原子写入,并在任何错误时中止且保留状态。迁移后,第二次试运行会确认零发现。
磁盘上会发生哪些变化
tasks.md 或 backlog.md 中的每个旧式块状任务条目都会变成单行条目。原本位于块内的文字会移动到新文件:datarim/tasks/{TASK-ID}-task-description.md,其中包含 YAML frontmatter 和正文分节。如果 progress.md 存在,其最近完成条目会被提升到 activeContext.md,然后该文件被删除。datarim/ 之外的任何内容都不会被触碰。
迁移后,会运行一次 Init-Task Presence 校验器作为建议性检查——它会列出任何没有关联 init-task 文件的任务,并按存在时长标记,但绝不会阻止迁移本身。
退出码与恢复
退出码 0 表示合规或迁移成功。退出码 1 表示试运行模式下存在发现。退出码 2 表示迁移已中止——状态被保留,单个文件可以用 git restore 回滚。退出码 3 表示锁被并发运行持有;请等待后重试。退出码 4 表示路径遍历防护被触发——在继续之前检查有问题的条目。
在 Datarim 是什么 中了解更多关于整体框架的信息,或查看框架组件如何通过 /dr-optimize 保持整洁。