前言¶
在 DeepSeek Harness（DSH）里跑长链路任务时，常见失败模式是：执行智能体宣称某步已完成，该说法进入对话 transcript，下一轮在未经核对的前提上继续推进。下游无法区分「已验证步骤」与「乐观自报」，错误会层层叠加，最终答案可能看起来很有把握却早已偏离事实。
社区插件 dsh-verified-progress（维护者 lion231226，目录分类 admin-security）针对的是这一类问题：为长时 DSH 工作维护一份 verified-progress ledger——独立校验方对每一步声称给出结构化裁决，只有满足准入规则的回合才记为进度；若校验过程中工作区被改动，指纹对比会使该裁决作废，且永远不能升格为进度。
这是什么¶
dsh-verified-progress 是 DSH 生态中的插件包（npm 名 dsh-verified-progress，当前资料中版本 0.3.1，MIT 许可证）。它不把「请校验方只读」当作唯一保障，而是在每次校验 episode 前后对工作区做指纹快照（文件 size、mtime，以及在 hash 上限内的 SHA-256），用 检测 替代单纯依赖工具过滤或提示词约束。
流程可概括为：
claim ──▶ independent verification ──▶ verdict
│
complete + clean + aligned ──▶ ledger (progress)
│
anything else ──▶ ledger (evidence only)
准入规则在代码中强制执行，而非仅写在 prompt 里：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
仅当裁决 complete、clean、aligned 时，该步才会进入账本意义上的「进度」；被拒绝的回合仍留在账本中作为 evidence，不会被提升为进度。
2. 持久化 verified-progress 账本¶
接受的步骤追加写入 ledger.jsonl（每行一个 JSON 对象，每次 append 后 fsync）；state.json 提供 last-wins 投影。进程崩溃、上下文压缩或新会话重新打开同一 run 时，仍可查询：哪些已验证、哪些因何被拒、还剩什么。被拒回合保留为证据，便于后续轮次看到已失败过的声称。
3. 工作区突变检测（指纹守卫）¶
校验前后对声明范围内的文件做指纹对比。若校验 episode 期间工作区发生变化，该轮记为 blocked / violation，无论校验报告读起来多干净，都不能升格为进度——因为会写文件的校验方不是中立见证，可能「先改再报」；指纹对比不依赖对校验方的信任。
4. 插件暴露的工具¶
| 工具 | 用途 |
|---|---|
verified_progress_verify |
针对工作区校验一步声称，并将裁决写入账本 |
verified_progress_ledger |
读回已验证进度、被拒声称与剩余项 |
verified_progress_state |
当前 run 状态：已验证轮次、待处理声称、开放项 |
guard_scope：声明指纹根目录¶
verified_progress_verify 必须配合 guard_scope：工作区相对路径或 glob，非 glob 前缀成为指纹根。示例：
verified_progress_verify claim="the parser handles CRLF input"
guard_scope="src/parser/**"
这不是可选装饰。若对整个工作区根做指纹，在 desktop profile 下根目录可能是 harness 主目录，sessions/**、storages/** 等会被会话本身持续写入，会导致每轮都像「工作区被 mutate」而误杀。因此：
- 路径须解析在 工作区内；绝对路径与
..会被拒绝； - 当工作区即为 harness 主目录时，必须 提供 scope；仅在根级排除
sessions、storages、logs、telemetry、cache、profiles等 harness 自有目录（嵌套项目内的sessions/仍可被守卫）； - 输出会打印
Fingerprinted: <path>，避免裁决范围含糊。
安装与启用¶
按环境选择 README 中的安装方式之一。无 registry、无 git 时，tarball 为通用默认：
dsh plugin --profile web add \
https://github.com/lion231226/dsh-verified-progress/releases/latest/download/dsh-verified-progress.tgz
包发布后也可从 registry 安装：
dsh plugin --profile web add dsh-verified-progress
本机已安装 git 时，可从仓库地址安装：
dsh plugin --profile web add github:lion231226/dsh-verified-progress
未安装 git 时使用 github: 形式可能因 git ls-remote 失败而报错，易被误判为插件损坏；tarball 走 HTTPS，不依赖 git。
安装后 需重启 harness：激活失败的插件不会自动重试，模块缓存也会保留旧版本直至进程重启。包为纯 ESM，无运行时依赖，无需额外 build。
环境要求（来自 package.json）：Node >= 22，DSH >= 0.2.0-rc.2；peer 依赖含 @deepseek-ai/cordis 等 DSH 相关包。
典型用法¶
- 安装插件并重启 harness。
- 对某步完成声称调用
verified_progress_verify，传入自然语言claim与guard_scope（指向你真正要守卫的项目路径，而非整个 harness 状态树）。 - 根据返回的三行控制字段与指纹结果判断该步是否进入进度；需要汇总时用
verified_progress_ledger或verified_progress_state。
账本文件不在项目目录，而在 harness 状态目录下：
<state>/verified-progress/runs/<runId>/ledger.jsonl
<state>/verified-progress/runs/<runId>/state.json
<runId> 有 session id 时取自 session id，否则取自工作目录哈希，同一 session 重开会对应同一 run。
适用场景与注意¶
适合：多轮、长 horizon 的 DSH 任务，需要在 crash、compaction 或新会话后仍能回答「什么被独立验证过、什么被拒、还差什么」；愿意用额外 token 换每步一次校验 episode 的团队。
不必上插件：单轮、极短任务——校验成本可能高于收益。
设计边界（README 明确说明）：
- 校验方是 独立上下文子智能体，不是独立 OS 进程；仍与执行方同属 harness 权限域，指纹检测使违规 可发现，而非从物理上不可能写盘。
- 突变守卫是 正确性工具，不是安全边界：不防本地攻击者，不是沙箱，未纳入快照的路径不在对比范围内。
- 超过 hash 上限的大文件仅比 size/mtime，快照会标明 evidence gap，不会假装做了内容哈希。
- 每次验证消耗 token。
插件以 当前 dsh 进程的权限 运行；安装前请自行查阅 GitHub 仓库 源码与 MIT 许可证，确认符合你的合规与信任要求。DSH 社区插件目录（如 SkillHub）为独立站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-verified-progress 把 LongHorizon 类循环里的「独立校验 + 账本」落到 DSH 插件形态：声称经独立校验方裁决，指纹守卫否决校验期间改动了工作区的回合，账本让进度与证据在会话中断后仍可追溯。
- 目录页：https://www.skillhub.cn/plugins/lion231226/dsh-verified-progress
- GitHub：https://github.com/lion231226/dsh-verified-progress
