@dpskh/tool-checkpoint —— DeepSeek Harness 的 checkpoint 标记插件

[English](README.md) | 中文 [![dshfind](https://dshfind.com/api/card/dpskh/dsh-checkpoint?lang=zh)](https://dshfind.com/zh/plugins/dpskh/dsh-checkpoint?ref=badge) 一个包、一个入口插件。挂载 `@dpskh/tool-checkpoint` 提供 `ctx.checkpoint`（把 checkpoint 标记持久记录到插件自有存储域、按 session id 关联的服务）和基于它的模型侧 `checkpoint` 工具。标记记录探索起点所在的会话位置；兄弟插件 [`@dpskh/tool-rewind`](https://github.com/dpskh/dsh-rewind) 会把标记之后的一切折叠成一份自动生成的报告，让探索中嘈杂的中间过程（读文件、搜索、试验）不再占用模型可见上下文，而持久日志完整保留探索过程供审计。本插件自身从不折叠任何东西 —— 标记在 rewind 之前保持惰性。标记**不是会话事件**：它存放在 `checkpoint` 存储域（`~/.dsh/storages/checkpoint.json`），因此持久会话日志保持纯核心词汇、任何 harness 都可读 —— 仓库外的插件事件会被词汇表缺失的 harness 拒绝。`rewind` 仅通过本服务消费标记。 ## 配置 ```yaml - id: tool-checkpoint name: '@dpskh/tool-checkpoint' config: toolName: checkpoint # model-facing tool name (default checkpoint) ``` ## 配合使用标记只有配合折叠才有意义：两个插件一起挂载，`rewind` 才能折叠标记锚定的探索。单独挂 `checkpoint` 只会记录惰性标记；单独挂 `rewind` 则没有可折叠的内容，会以 no-checkpoint 错误失败。 ```yaml - 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` 折叠最近的标记；对同一标记二次折叠会因区域为空而被拒绝。