轮末回执 zhangyy0423/dsh-veripipe

dsh-veripipe

一个 DeepSeek Harness（dsh）插件，为每一轮生成轮末回执，并在该轮结束后仍保持可读——另附一个只读工具，用来读回执。它不增加模型调用，不访问网络，也不写入你的会话。

它解决的问题

dsh 自带一个 todos 会话投影，智能体用 todo_write 更新它。这个投影在每次 turn/start 时被清空：下一轮一开始，读 todos 投影就返回 null。外部校验器如果在轮次之间检查会话，就无法区分一个已完成的计划（所有 todo 都是 completed）和一个被放弃的计划——两者读出来都是「没有列表」。

dsh-veripipe 把同一份事件日志折叠成一份平行投影，其中的条目不会被后续轮次清空。每次 turn/end 时它记录一条回执，捕获该轮的终态，于是每一轮的完成状态在整个会话生命周期内都保持可读。

它注册了什么

- veripipeReceipts 会话投影——对会话事件日志（turn/start、todo/write、goal/change、turn/end）做纯函数式、确定性的折叠。每次 turn/end 生成一条回执，保留最新 50 条。它像其他投影一样从日志重放；除事件流之外不保存任何自身状态。
- veripipe_receipt 工具——只读。返回当前会话最近的若干条回执（默认 1 条）。它不发起模型调用，不发起网络请求，也不写入。

安装

dsh plugin --profile <your-profile> add github:zhangyy0423/dsh-veripipe

仓库自带预构建产物（lib/），且没有 prepare 脚本，所以安装时不会构建任何东西。它没有发布到 npm。本地检出或打包的 tarball 也可以：

dsh plugin --profile <your-profile> add ./dsh-veripipe # local checkout
dsh plugin --profile <your-profile> add ./dsh-veripipe-0.1.0.tgz # from npm pack

所有 @deepseek-ai/ 包都是对等依赖，由宿主 dsh 安装提供；插件故意把它们声明为对等依赖（而非普通依赖）。声明为依赖会加载第二份 @deepseek-ai/dsh-tools，导致每次工具调用都失败。zod 是唯一的直接运行时依赖。

回执字段

每条回执都是一条小巧的、JSON 纯量记录：

| 字段 | 类型 | 含义 |
| turn | integer | 这条回执认证的轮次编号（事件里省略时为 -1）。 |
| endReason | string | turn/end 的原因类型（如 completed、aborted、error）；读不出来时为 unknown。 |
| todos | object \| null | 该轮最后写入的 todo 列表计数：{ total, completed, inProgress, pending }；没写过则为 null。 |
| goal | object \| null | 轮末的目标标识：{ id, phase, revision }；没有活跃目标则为 null。 |
| verdict.planComplete | pass \| fail \| inconclusive | 失败关闭的完成判定（见下文）。 |

判定语义（失败关闭）

判定刻意保守 —— 不确定的情况绝不报成 pass：

- pass —— 本轮写入了非空 todo 列表，且每一项都是 completed。
- fail —— 写入了非空 todo 列表，且至少有一项不是 completed。
- inconclusive —— 本轮没有写入 todo 列表、列表为空，或者 todo/write 载荷读不出来。

工具用法

// veripipe_receipt (no required arguments)
{ "limit": 3 } // optional; how many of the most recent receipts to return, newest last.
// Defaults to 1; clamped to 1..50.

返回：

{
"available": 7, // total receipts kept for this session
"returned": 3, // how many this call returned
"receipts": [ // oldest first
{
"turn": 5,
"endReason": "completed",
"todos": { "total": 3, "completed": 3, "inProgress": 0, "pending": 0 },
"goal": { "id": "g_abc", "phase": "active", "revision": 2 },
"verdict": { "planComplete": "pass" }
}
// ...
]
}

第一轮结束之前，工具返回 { "available": 0, "returned": 0, "receipts": [] }。

隐私

回执只存计数和标识符。折叠过程从不记录提示词、todo 文本、工具参数、工具结果，也不记录目标的目标文本 —— 只记录按状态分类的 todo 计数、目标的 id/phase/revision、轮次编号，以及结束原因的种类。veripipe_receipt 工具返回的正是这些字段，不多不少。

与 veripipe 的关系

veripipe 是外部验证流水线，用来判断智能体是否真的完成了交给它的任务。它的 dsh 适配器在运行结束后读取会话状态。由于原生的 todos 投影会在下一次 turn/start 时被清空，跨轮读取无法区分已完成的计划和被放弃的计划。本插件在 dsh 这一侧补上这个缺口：它按轮暴露持久、失败关闭、只含计数的完成信号，这类验证器可以直接读取，无需重新推导历史，也无需触碰私密内容。即使不用 veripipe，本插件也独立可用 —— 它是一份通用的轮次完成台账 —— 并且与 harness 分开维护。

开发

DSH_HARNESS=/path/to/deepseek-harness bash scripts/link-harness.sh # dev links for type-checking
npm run build # tsc -p tsconfig.json -> lib/
npm test # node --test over the pure fold (tests/.test.mjs)

lib/ 已提交，所以安装时无需构建；改动 src/ 之后请重新构建并提交。

全部计算都在 src/receipt.ts 里，它不从 harness 导入任何东西，并针对编译产物 lib/receipt.js 单独做单元测试。

License

MIT © zhangyuyu03