/dr-doctor
诊断并将运维文件迁移至薄索引模式
概述
/dr-doctor 将旧版 Datarim 运维文件迁移至薄索引模式。它把任务描述从 tasks.md、backlog.md 和 activeContext.md 外置到 datarim/tasks/{TASK-ID}-task-description.md 的每任务文件中,使运维文件仅保留单行指针。
该命令还会淘汰旧版 progress.md 和 backlog-archive.md 文件(两者均在 v1.19 系列中废除)。已取消的任务归入 documentation/archive/cancelled/;已完成的任务归入 documentation/archive/{area}/。
用法
# 试运行(默认)——报告发现项,不做变更
/dr-doctor
# 应用迁移
/dr-doctor --fix
# 在非交互环境中应用迁移(CI / AI 会话)
# —— 跳过冲突(保留条目)而非提示
/dr-doctor --fix --no-prompt
# 静默探测(仅退出码——适用于脚本和自愈场景)
/dr-doctor --quiet
功能说明
- 探测
datarim/中的不合规条目(旧版### TASK-ID:块、粗体 ID 的- **TASK-ID** ...行、非规范项目符号、残留的backlog-archive.md、残留的progress.md)。 - 按类别报告发现项计数表。
- 在
--fix时,执行 6 轮迁移:- 第 1 轮 —— 描述缓存(将任务正文提取到每任务描述文件)。
- 第 2 轮 —— 运维文件重写(
tasks.md、backlog.md→ 单行薄索引)。 - 第 3 轮 ——
activeContext.md富块迁移器(旧版段落形式 → 严格镜像tasks.md§ Active)。 - 第 4 轮 ——
backlog-archive.md迁移。按## Cancelled/## Completed拆分;对每个条目:已取消 → 合成documentation/archive/cancelled/archive-{ID}.md;已完成 → 验证现有documentation/archive/{area}/archive-{ID}.md或合成到general/。冲突解决遵循--conflict-policy=prompt|keep|overwrite|skip|abort(默认prompt,非 TTY 下自动skip);--no-prompt是skip的 CI 别名。 - 第 5 轮 —— 修复后重新扫描。对迁移后的树执行完整试运行必须报告零发现项;按 ID 断言检查修复前
backlog-archive.md.pre-v2.bak中存在的每个任务 ID 现在都已体现在documentation/archive/中。不匹配会触发从写入前 tarball 备份自动恢复。 - 第 6 轮(<TASK-ID> v1.21.5,加固于 <TASK-ID> v1.21.6)—— 运维文件归档区段迁移。从
tasks.md/backlog.md中剥离## Archived,从activeContext.md中剥离### Archived/### Recently Archived/## Последние завершённые—— 这些区段违反规范薄索引契约(«仅一个区段»,v1.19.1)。自动检测四种项目符号形态(S1 箭头链接、S2 状态括号、S4 中置粗体上下文、S3 纯粗体);支持复合任务 ID(例如<TASK-ID>-S8)。显式→ documentation/archive/{path}.md指针优先于prefix_to_area映射。对每个项目符号:用{ID}字面量验证规范性 → 剥离;缺失 → 在各区域子目录中防御性find(深度 ≤ 3);若未找到,合成存根;冲突 → 遵循--conflict-policy。无标题回退:没有归档标题的运维文件逐行处理;状态非终态(in_progress、not_started等)的项目符号作为活动内容原样通过。
- 生成带有封闭 12 键 YAML frontmatter 的描述文件(id、title、status、priority、complexity、type、project、started、parent、related、prd、plan)。
- 迁移后运行两个正交轮次:backlog 终态条目清理(
prune-backlog-terminal.sh—— 移除已有归档文档的已完成条目,暴露没有归档文档的条目)以及建议性 init 任务存在性检查(check-init-task-presence.sh --all,从不阻塞)。 - 幂等 —— 在合规的树上重新运行是静默无操作(退出码 0)。
数据丢失安全契约
每次 --fix 调用都会在任何写入之前于 ${DATARIM_DOCTOR_BACKUP_DIR:-/tmp}/datarim-backup-{TS}.tgz 创建 tarball 备份(模式 0600)。成功时的摘要行会打印备份路径。第 4 轮还会写入每文件 backlog-archive.md.pre-v2.bak 附属文件,迁移后保留。修复后不变量 emitted_count >= parsed_count 防止静默数据丢失;违反时 doctor 会恢复 tarball 并以退出码 2 退出。
退出码
0—— 合规(或--fix成功)1—— 存在不合规发现项(试运行)2—— 迁移错误(--fix中止;状态按原子文件重命名保留)3—— 并发调用(锁被持有)4—— 运维文件中的路径遍历 / 安全违规64—— 用法错误
自愈集成
当 datarim/ 已存在时,/dr-init 第 2.4 步在每次初始化时运行 datarim-doctor.sh --quiet。在 TTY 下退出码为 1 时,提示 «运行 /dr-doctor --fix?[Y/n]»(默认 Y)。非 TTY 会话打印警告并继续。
pre-archive-check.sh 在 /dr-archive 可以继续之前,根据规范正则验证 tasks.md / backlog.md 中的每个项目符号行。逃生通道:--no-schema-check 用于进行中的迁移。
文档迁移自愈(2.49.0+)
自 2.49.0 起,规范文档根目录为 documentation/(旧版 docs/ 名称已退役),且 /dr-optimize 漂移检测器会硬性翻转:仍使用 docs/ 的消费方仓库会被标记为漂移。因此仓库不仅被告知存在漂移 —— /dr-doctor 还提供可选的迁移轮次来修复它。
该轮次检测布局(旧版 docs/ → 提供迁移;docs/ 和 documentation/ 同时存在 → 人工审查,不自动修复;已迁移 → 干净无操作),然后执行 git mv + 四类 Diátaxis 拆分(已知文件映射到其类别;未知文件归入 how-to/ 并带审查标记)+ 锚定引用重写。它根据引用 linter 验证结果,若任何检查失败则回滚到迁移前的树 —— 幂等且回滚安全。
按设计,这是一个独立的同级执行器,而非运维文件 doctor 的 --scope:产品文档物理上位于框架状态目录之外,因此将内容迁移混入模式迁移会模糊框架有意保持的边界(§ 验证纪律)。
模式参考
规范正则(单行,锚定):
^- ([A-Z][A-Z0-9]{1,9}-[0-9]{4}) · (status) · P[0-3] · L[1-4] · (.{1,80}) → tasks/\1-task-description\.md$
状态集:tasks.md 使用 in_progress|blocked|not_started;backlog.md 使用 pending|blocked-pending|cancelled。
流水线位置
维护命令,按需运行,或在结构不合规时由 /dr-init 自动建议。
相关
- /dr-init —— 在第 2.4 步自动触发 /dr-doctor 探测
- datarim-doctor 技能 —— 模式规范与迁移语义
- datarim-system 技能 —— 运维文件模式规范契约
报告结果
在面向人员的更新或结果之前,应用 Human Outcome Reporting。说明用户可见的结果、原始条件、检查与证据,以及未决限制。阶段结果并不意味着整个任务已完成。保持精确协议和技术记录完整。若要在不继续工作的情况下再次解释,请使用 /dr-explain。