dsh-checkpoint

English | 中文

一个包、一个入口插件。挂载 @dpskh/tool-checkpoint 提供 ctx.checkpoint（把 checkpoint 标记持久记录到插件自有存储域、按 session id 关联的服务）和基于它的模型侧 checkpoint 工具。标记记录探索起点所在的会话位置；兄弟插件 @dpskh/tool-rewind 会把标记之后的一切折叠成一份自动生成的报告，让探索中嘈杂的中间过程（读文件、搜索、试验）不再占用模型可见上下文，而持久日志完整保留探索过程供审计。本插件自身从不折叠任何东西 —— 标记在 rewind 之前保持惰性。

标记不是会话事件：它存放在 checkpoint 存储域（~/.dsh/storages/checkpoint.json），因此持久会话日志保持纯核心词汇、任何 harness 都可读 —— 仓库外的插件事件会被词汇表缺失的 harness 拒绝。rewind 仅通过本服务消费标记。

配置

- id: tool-checkpoint
  name: '@dpskh/tool-checkpoint'
  config:
    toolName: checkpoint   # model-facing tool name (default checkpoint)

配合使用

标记只有配合折叠才有意义：两个插件一起挂载，rewind 才能折叠标记锚定的探索。单独挂 checkpoint 只会记录惰性标记；单独挂 rewind 则没有可折叠的内容，会以 no-checkpoint 错误失败。

- id: tool-checkpoint
  name: '@dpskh/tool-checkpoint'
- id: tool-rewind
  name: '@dpskh/tool-rewind'        # https://github.com/dpskh/dsh-rewind
  config:
    reportLanguage: en              # en | zh report instruction language

契约

• ctx.checkpoint.mark(session, objective?) —— 在插件自有存储域中为会话记录一条持久标记（按 session id 关联），返回 { id, logLength }。id 是插件自有的单调标记标识；logLength 是标记时的会话日志长度（折叠锚点：标记之后第一个事件的 seq）。编号 turn 记录标记时所在的开放回合；null 表示空闲会话。标记存放在会话日志之外，因此压缩或后续折叠都不会遮蔽它，无论标记与 rewind 之间发生什么，标记始终可定位。
• ctx.checkpoint.latestMark(sessionId) / ctx.checkpoint.hasActive(sessionId) / ctx.checkpoint.completeFold(sessionId, id) —— rewind 使用的消费面：读取最近标记、询问是否仍欠一次折叠、折叠成功后把标记标记为已折叠。
• checkpoint 工具 —— { objective?: string } → { id, logLength }。模型在开始一段中间过程会污染上下文的探索之前调用它，之后由 rewind 把标记之后的一切折叠成自动生成的报告。渲染意图：generic 卡片。

模型体验

直接可见：checkpoint 工具调用及其 { id, logLength } 结果。工具描述教会"先标记、后 rewind"的工作流；tool:checkpoint 系统提示 section 将其变为常驻指令（任何需要多次工具调用的调查前标记、回合结束前 rewind）。标记本身从不进入模型可见历史，也从不进入会话日志。

KV 缓存影响

前缀稳定：工具 schema 固定；标记是存储记录而非会话事件，绝不改变请求前缀。

已知限制与待办

• 无 rewind 的标记是惰性的 —— 从未被折叠的 checkpoint 不产生额外开销，但探索仍留在上下文中；工作流依赖模型成对使用标记与 rewind。
• 每个标记只能折叠一次 —— rewind 折叠最近的标记；对同一标记二次折叠会因区域为空而被拒绝。