验证进度账本 lion231226/dsh-verified-progress

dsh-verified-progress

为 DSH 的长任务提供「已验证进度账本」——一个裁决只有在产出它的那一方被证明全程只读时才作数。

长任务有一种特定的失败方式：agent 报告了它证明不了的进度，这份报告进了对话记录，下一轮就在一个从未被核实的 claim 上继续往下建。下游没有任何东西能区分「已核实的步骤」和「乐观的步骤」，于是错误不断累积，直到最后给出一个自信但错误的答案。

本插件补上缺失的那道核对。当 agent 声称某步做完时，一个带全新上下文的独立验证者去检查真实工作区，返回结构化裁决。只有 clean、aligned、complete 的裁决才会进入账本。被否的步骤留在账本里作为证据——它永远不会被提升为进度。

声明 ──▶ 独立验证 ──▶ 裁决 │ complete + clean + aligned ──▶ 账本（进度） │ 其它任何结果 ──▶ 账本（仅证据）

不靠提示词的那一半

「只读验证者」通常靠两件事保证：要求验证者守规矩，以及把写类工具从它的工具集里拿掉。两者都是预防，而任何没被工具白名单点名的路径都能绕过去。

本插件改为检测。每次验证回合前后各对工作区做一次指纹——所有文件记 size+mtime，限额内的文件另记 SHA-256。只要有东西变了，就说明这个「只读审计」期间验证者动了工作区，于是它自己的结论由构造即作废：该轮记为 blocked / violation，无论它的报告写得多干净，都不可能被提升为进度。

这一点很重要，因为会写文件的验证者不是中立的证人：它可以先造出自己随后要报告的证据，而再多的提示词纪律或工具白名单都无法证明它没这么做。指纹比对完全不需要信任验证者——也正因如此，账本的准入规则才可以写成绝对的：

integrity === "violation" || contract !== "aligned" ⟹ status !== "complete"

这条不变量是代码强制的，不是在提示词里请求的。少写一行控制行的验证者会向保守方向降级——未声明的 integrity 读作 suspect，绝不读作 clean——因为占位值绝不能成为背书工作的那一环。

它做什么

1. 用独立验证替代自述。 验证者是一个不继承任何对话上下文的独立子代理。它读文件、跑能跑检查、然后用三行控制行作答：

Status: complete | incomplete | blocked
Integrity: clean | suspect | violation
Contract audit: aligned | unknown | needs_revision | invalid

2. 持久化已验证进度账本。 通过的步骤追加写入 ledger.jsonl（一行一个 JSON 对象，每次追加都 fsync），并在 state.json 里维护 last-wins 投影。崩过的进程、被压缩过的上下文、或一个全新会话，都能重新打开这次运行并回答：什么已被验证、什么被否以及为什么、还剩什么。被否的轮次作为证据保留而不是丢弃，所以后续回合能看到哪些声明已经试过并失败了。

3. 变异检测。 见上；它是账本的准入规则，不是一个附属功能。

工具

| 工具 | 用途 |
| verified_progress_verify | 用一个声明的步骤去核对工作区，并把裁决写入账本。 |
| verified_progress_ledger | 读回已验证进度、被否的声明、以及剩余项。 |
| verified_progress_state | 当前状态：已验证轮次、待证声明、未完成项。 |

必须声明护栏的判定范围

verified_progress_verify 接受 guard_scope：一个工作区相对路径或 glob，其非 glob 前缀成为指纹根。

verified_progress_verify claim="解析器能处理 CRLF 输入"
guard_scope="src/parser/**"

这不是可选的装饰。护栏最初对整个工作区根做指纹，而在桌面端那个根就是 harness home 本身——sessions/、storages/ 与插件状态正被「插件所运行的这个会话」持续写入。最初两次验证都返回 workspace mutated (+3 ~5 -3)，而每一个变化路径都属于 harness，验证者什么都没写。把宿主自己的写入算到验证者头上的护栏，会每轮都失败，却看起来像个保守的裁决。 所以范围改为由调用方声明，而不是被假定的：

- 范围必须落在工作区内；绝对路径与 .. 一律拒绝，而不是悄悄放宽；
- 当工作区就是 harness home 时，必须给出范围，且 harness 自有目录（sessions、storages、logs、telemetry、cache、profiles 等）仅在根层被排除——所以真实项目里嵌套的同名 sessions/ 目录仍受护栏保护；
- 结果里会打印 Fingerprinted: <路径>，裁决的覆盖范围不留含糊。

安装

dsh plugin --profile web add dsh-verified-progress

或直接装已发布的 tarball（不需要 registry）：

dsh plugin --profile web add \
https://github.com/lion231226/dsh-verified-progress/releases/download/v0.3.1/dsh-verified-progress.tgz

然后重启 harness：激活失败的插件不会被重试，且模块缓存会一直持有旧版本直到进程重启。无需构建：包内直接是 ESM 源码，且没有运行时依赖。

存储位置

一切都在 harness 的状态目录下，不在你的项目里：

<state>/verified-progress/runs/<runId>/ledger.jsonl
<state>/verified-progress/runs/<runId>/state.json

<runId> 优先由会话 id 派生，没有会话 id 时用工目录的哈希，所以重开同一个会话就是重开同一次运行。

设计边界——请读这几条

- 验证者是独立 agent，不是独立进程。 它看不到执行者的对话，这是它「独立」的来源，并且它跑在只读工具集下。它与宿主同权限约束；指纹检测的作用是让违规可被发现，而不是让违规不可能发生。
- 变异护栏是正确性工具，不是安全边界。 它比对文件指纹，不防御本地攻击者，不是沙箱，也不覆盖被排除在快照之外的路径。
- 超出哈希上限的大文件会被如实报为「证据缺口」。 这类文件只比 size+mtime，快照会明确说出来，而不是假装做过它没做的比对。
- 验证是有成本的。 每个被验证的步骤都会多一次验证者回合。你换来的是账本；如果任务只是一轮短对话，你不需要这个插件。

为什么会有这个项目

循环设计移植自 LongHorizon-Harness（AMAP-ML，MIT）——manager/executor/auditor 轮次、持久轮账本、以及一个无法为脏结果背书的 auditor。

那个项目是一个包裹 agent CLI 的 Python 编排器，在 Windows 上跑不起来：它的持久化层要求 os.O_NOFOLLOW、os.O_DIRECTORY 与 supports_dir_fd（win32 上全部缺失），并且用 POSIX 的 VAR=value cmd 模板起子进程。它还按设计为每个角色回合驱动一次 agent CLI——所以接 DeepSeek Harness 时它只能读到每次 dsh --profile headless 的最终答复，拿不到中间的工具事件。

本插件把真正承载价值的部分——独立验证、降级不变量、已验证状态账本、变异护栏——拿出来，在 harness 内部原生实现：那里事件可得，也不需要任何 POSIX-only 原语。其中工作区变异检测是本插件自己的贡献：上游项目对「验证者写入」的防护同样只停留在上文那种「提示词 + 白名单」的预防层面。

许可证

MIT