stage-snapshot-writer 技能——在终端关闭后依然存活
Datarim 的 stage-snapshot-writer 技能如何在每个流水线步骤之后将最后一次操作员可见的响应持久化到磁盘,使下一条命令能够从精确的检查点恢复,而无需重新读取会话历史。
一个漫长的流水线步骤结束了,操作员运行 /clear 来释放上下文,而下一条命令需要知道当前进展到哪一步。如果没有书面记录,agent 就必须从头重建状态。stage-snapshot-writer 技能通过为每个任务维护一个文件来解决这个问题,该文件在每个流水线阶段结束时被覆盖写入。
每条会输出 CTA 块的 /dr-* 命令,都会将其最终的操作员可见响应作为终端步骤写入 datarim/snapshots/{TASK-ID}.snapshot.md。在会话重置后,该文件是 /dr-next 的主要上下文来源。覆盖语义意味着对同一阶段的第二次调用总会生成一个全新的文件——不会累积过时的状态。
快照包含的内容
该文件包含一个 YAML frontmatter 块,随后是渲染后的摘要和 CTA 部分。frontmatter 记录了任务 ID、阶段名称、生成该快照的命令、时间戳、由哪个实体捕获(agent 或操作员)、推荐的下一命令,以及备选后续步骤的选项列表。另外两个字段记录文件自身的字节大小以及正文是否被截断。
8,192 字节的硬性上限是关键约束。如果渲染后的摘要和 CTA 合计超过该限制,正文将在上限处被截断,并追加一个标记:<!-- snapshot-truncated, full response in session jsonl -->。完整响应仍可在会话 JSONL 日志中获取;快照并非唯一记录,只是快速路径的那一份。
并发与安全控制
写入器在写入前会获取一个基于 mkdir 的锁。锁超时可通过 DR_SNAPSHOT_LOCK_TIMEOUT 配置(默认 60 秒)。之所以使用 mkdir 原语而不是 flock,是因为在 macOS 上通过 NFS 和 SMB 挂载时 POSIX flock 不可靠。
另外三项控制针对最常见的文件操作失败模式。路径遍历通过在构造路径之前用模式 ^[A-Z][A-Z0-9-]+-[0-9]{4,5}$ 校验任务 ID 来阻止。Shell 注入通过从文件参数读取正文而不是内联展开来防止。符号链接攻击通过在原子重命名之前解除目标路径上任何已存在的符号链接来阻止。完成的快照文件会被设置为 chmod 600,锁目录会被设置为 chmod 700。
终止开关与实现位置
设置 DATARIM_DISABLE_SNAPSHOT=1 可将写入器变为空操作,而无需修改任何源文件。当在快照目录位于只读挂载上的环境中运行,或在不产生副作用的情况下测试流水线时,这很有用。
实现位于 scripts/lib/snapshot-writer.sh,具体在 write_stage_snapshot 函数中。唯一的生产者接触点是 cta-format 技能的 Snapshot Emission 部分——写入器不会被各个命令直接调用,只能通过那一个入口点调用。消费者一侧是 dr-next-snapshot-replay 技能,它读取该文件并为恢复执行的命令重建上下文。
退出码
写入器在成功时退出码为 0,在 IO 错误或参数校验失败时为 1,在缺少必需标志时为 2,在锁超时时为 3。锁超时(退出码 3)通常意味着另一个写入器正在为同一任务运行——正确的响应是等待并重试,而不是覆盖锁。
阅读什么是 Datarim以了解快照如何融入流水线的背景,或查看subagent-driven-development 技能以了解隔离的 agent 在计划执行期间如何使用检查点。