技能 Core

阶段快照写入器

按任务生成阶段快照的生产者契约——将最终面向操作者的 /dr-* 响应以覆盖语义持久化到 datarim/snapshots/{TASK-ID}.snapshot.md。通过 cta-format.md 提供单一生产者触点。

概述

阶段快照写入器是按任务生成阶段快照的生产者契约——于 v2.13.0(<TASK-ID>)引入。每个 /dr-* 命令在其最终步骤中,将最终面向操作者的响应(摘要 + 门禁结果 + CTA 块)以覆盖语义持久化到 datarim/snapshots/{TASK-ID}.snapshot.md,并带有 8 KB 硬上限和基于 mkdir 的原子锁。

存在原因

在 v2.13.0 之前,/clear 之后的 /dr-next {TASK-ID} 必须从冷工件——PRD、计划、任务描述、activeContext——重新推导下一阶段。对于拥有 700 行计划的 L3+ 任务,这会消耗约 30% 的上下文窗口,并丢失关于智能体刚刚做了什么以及发出了哪些 CTA 选项的关键信息。修复方案:一个小的、重试时覆盖的快照文件,消费者可以优先读取。

单一生产者触点

写入器仅从一个位置调用——skills/cta-format/SKILL.md § 快照发出。由于 cta-format.md 在每个 /dr-* 命令响应末尾已是强制性的,将快照步骤添加到一个技能中即可覆盖所有 15+ 个生产者命令,无需 N 个触点补丁。

快照文件结构

---
task_id: <TASK-ID>
artifact: stage-snapshot
schema_version: 1
stage: plan
command: /dr-plan
captured_at: 2026-05-21T13:45:00Z
captured_by: agent
recommended_next: /dr-do
options:
  - "/dr-do <TASK-ID> | implementation"
  - "/dr-status | escape hatch"
size_bytes: 6432
truncated: false
---

<rendered Summary + Gate Results + CTA block; total file ≤ 8192 bytes>

安全控制

  • TASK-ID 正则——^[A-Z][A-Z0-9]{1,9}-[0-9]{4}(-[A-Za-z0-9]+)*$;在任何文件 IO 之前拒绝路径遍历尝试。
  • 基于 mkdir 的原子锁——复用 scripts/lib/plugin-system.sh::acquire_plugin_lock()(macOS 可移植,不依赖 flock);默认 60 秒超时,通过 DR_SNAPSHOT_LOCK_TIMEOUT 配置。
  • 写临时文件后重命名——正文写入 .tmp 文件后通过 mv 重命名;在 POSIX 上为原子操作。
  • chmod 600——快照文件仅运行用户可读;锁目录 chmod 700。
  • 硬性大小上限——每个文件总计 8192 字节;溢出正文被截断并标记 <!-- snapshot-truncated, full response in session jsonl -->。
  • 符号链接防护——目标位置已存在的符号链接在重命名前被解除链接。
  • 终止开关——DATARIM_DISABLE_SNAPSHOT=1 使写入器成为空操作。
  • 入口点——智能体调用 bash "${DATARIM_RUNTIME:?}/dev-tools/snapshot-writer-wrapper.sh" 并传入命名标志,绝不直接调用裸库函数(在 zsh 父 shell 下会静默失败)。缺少必需标志时会在 stderr 中指明并以退出码 2 退出;退出码 3 表示锁超时。如果包装器不可达,命令会警告一次并继续——快照文件绝不手工编写。

消费者侧

快照由 /dr-next(步骤 2.5「快照优先读取」)和 /dr-orchestrate(快照优先恢复)通过同级技能 dr-next-snapshot-replay.md 消费。清理在 /dr-archive 步骤 0.95 中将最终快照移动到 documentation/archive/<subdir>/snapshots/{TASK-ID}-final-stage.md——移动,而非删除。

来源

<TASK-ID>,v2.13.0,2026-05-21。PRD:datarim/prd/PRD-<TASK-ID>-stage-snapshot.md。实现:scripts/lib/snapshot-writer.sh。测试:跨 10 个套件的 44 个 bats 用例(写入器覆盖、frontmatter 模式、大小上限、flock 竞争、cta-format 集成、归档时清理、dr-archive 子目录解析)。