审议式复核插件fly1989/dsh-deliberation

dsh-deliberation

一个非官方 DeepSeek Harness 插件：提供有界、由 Primary 控制的 deliberation，以及可选的 reasoning-masked review。

状态：实验预览版。 Runtime、失败隔离和协议边界已有测试；目前没有配对 benchmark 能证明它提高正确率或推理成本回报，因此自动审查默认关闭。

插件提供两条相关能力：

| 能力 | 触发方式 | 实际作用 |
| --- | --- | --- |
| deliberate 工具 | Primary 主动调用 | 并行运行 1–3 个有界 alternative、audit 或 masked-review child，返回紧凑 JSON packet |
| 自动 masked review | 可选的 agent/turn-stopping hook | 不带当前工具 Turn 已记录的 reasoning 重新复审，只向 Primary 发布决策相关增量 |

child 只提供证据、不确定项、可能错误与下一步检查，不投票、不选择 winner，也不替代 Primary。

五分钟启动

环境要求

- Node.js 22.19+ 或 24+
- pnpm 已加入 PATH（dsh plugin 底层把安装参数转发给 pnpm）
- 已能正常使用 DeepSeek Harness Web profile，并已配置模型凭据

先检查：

node --version
pnpm --version
npx @deepseek-ai/dsh --version

安装正式发布包

npx @deepseek-ai/dsh plugin --profile web add dsh-deliberation@0.1.0
npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh web

添加、移除或更新 Bundle 后，必须重启正在运行的 Web。配置 dump 应同时出现：

subagent-mid-fork-step-family-in-process
subagent-mid-fork-current-turn-in-process
tool-deliberation

请从希望作为 Agent workspace 的目录启动 Web。

发布前测试本地 checkout

git clone https://github.com/fly1989/dsh-deliberation.git
cd dsh-deliberation
npm ci
npm run release:check

最新 DSH 会先把 . 锚定到当前 checkout，再进入 profile 目录。
npx @deepseek-ai/dsh plugin --profile web add .
npx @deepseek-ai/dsh --profile web --dump-config
npx @deepseek-ai/dsh web

本地安装是 link。修改 TypeScript 后要重新 build；修改 Bundle 成员或编译代码后要重启 runtime：

npm run build

第一次手动测试

插件注册的模型工具名是 deliberate。工具可用不等于模型必然调用，第一次 smoke 请用明确任务：

检查当前 workspace 并诊断失败的校验，暂时不要修改文件。
先用只读工具得到一条具体观察，然后调用 deliberate：
一个 trajectory-audit 分支和一个 masked-review 分支，后者复审最近一个
已完成 Step。route 使用 same；audit 使用 read-only；masked review 使用
reason-only。拿到 packet 后，选择成本最低的鉴别性检查并正常继续。

预期流程：

1. Primary 至少完成一个含工具的 Step。
2. Web 出现通用 deliberate tool card。
3. 每个分支创建独立 child Session；child transcript 不进入 Primary context。
4. 工具结果为每个成功分支返回一份紧凑 packet。
5. Primary 自己判断是否采用。

开启自动 masked review

自动审查必须显式启用。仓库提供了一份完整的 DSH config-row replacement：

$reviewPatch = (Resolve-Path .\examples\auto-review.patch.yml).Path
npx @deepseek-ai/dsh --profile web --patch $reviewPatch --dump-config
npx @deepseek-ai/dsh --profile web --patch $reviewPatch

该示例启用：

autoReview:
enabled: true
scope: tool-bearing-turns
provider: mid-fork-current-turn
route: same
capability: read-only
publish: updates-only
timeoutMs: 300000

若要永久启用，把 examples/auto-review.patch.yml 中完整的 tool-deliberation 配置行复制到该 Web profile 的 cordis.patch.yml。DSH patch 会替换目标行的整个 config，不会深度合并嵌套字段，所以不要只写半段 autoReview。普通 profile patch 修改支持热重载；安装或移除插件 Bundle 仍需重启。

收集 shadow eval 时建议先用 publish: observe-only：child 会运行并持久化，但绝不写入 Primary inbox。

三种角色

| 角色 | 历史 | 是否看 incumbent | 适合做什么 |
| --- | --- | --- | --- |
| independent-alternative | fresh / spawn | 否 | 寻找一个实质不同的机制或策略 |
| trajectory-audit | completed prefix / fork | 是 | 证伪当前轨迹，并定位最早可疑决策 |
| masked-review | 更老的 native prefix + recent-Step snapshot | 否 | 不看选中 Step 的 recorded reasoning，重新审视可观察行动与结果 |

手动 masked-review 必须填写 recentSteps，范围为 1..maxRecentSteps（默认上限 8）。一个 Step 是“一次已完成模型决策 + 该 response 引起的全部 tool call/result”；并行工具仍属于同一个 Step。正在执行 deliberate 的 active Step 不在窗口内。

自动路径使用 window: current-turn：更早完整 Turn 保持 native history，正在 stopping 的 Turn 内所有完整 Step 被投影成 reasoning-masked snapshot。

返回 packet

child 只返回结构化决策信息，不返回 hidden reasoning 或完整 transcript：

{
"role": "masked-review",
"status": "update",
"items": [
{ "kind": "possible_error", "certainty": "likely", "content": "..." },
{ "kind": "unknown", "certainty": "uncertain", "content": "..." },
{ "kind": "suggestion", "certainty": "likely", "content": "..." }
]
}

- status：update 或 no_update
- kind：observation、conclusion、assumption、unknown、possible_error、suggestion
- certainty：certain、likely、uncertain

certainty 是 child 自报，不是事实认证。真实 timeout、abort、child error、非法 packet 或 role 不匹配都不会发布 packet。只有 child Session 能证明 Turn 正常结束时，才允许使用严格的 final-text JSON fallback。

配置参考

手动工具配置

| 字段 | Bundle 值 | 含义 |
| --- | ---: | --- |
| freshProvider | spawn | independent-alternative 使用的 provider |
| forkProvider | fork | trajectory-audit 使用的 provider |
| midForkProvider | mid-fork-step | recent-Step provider family 前缀 |
| maxRecentSteps | 8 | Primary 可选的最大 K |
| maxBranches | 3 | 一次调用最多几个分支 |
| maxDepth | 1 | child delegation 的绝对深度上限 |
| branchTimeoutMs | 600000 | 每个手动分支独立的墙钟超时 |
| routes | same | 暴露给 Primary 的部署许可模型路线 |
| capabilityProfiles | reason-only、read-only | 暴露给 Primary 的 child 工具边界 |
| debug | false | 只记录安全生命周期 breadcrumb，不记录 prompt 或 child 内容 |

自动审查配置

| 字段 | 可选值 | 含义 |
| --- | --- | --- |
| enabled | false / true | 是否挂载 stopping-boundary policy |
| scope | tool-bearing-turns / all-primary-turns | 哪些顶层 Primary Turn 可以触发 |
| provider | 默认 mid-fork-current-turn | 部署者控制的 history projection |
| route | 默认 same | child provider/model 路线 |
| capability | Bundle 默认 read-only | child 工具上限 |
| publish | updates-only / all / observe-only | 哪些 packet 可以进入 Primary inbox |
| timeoutMs | 300000 | 自动 child 墙钟超时 |

History projection provider

| 字段 | Bundle 值 | 含义 |
| --- | ---: | --- |
| window | recent-steps 或 current-turn | snapshot 选择方式 |
| mask | reasoning-only | 删除 reasoning/replay state；action-only 仅作评测对照 |
| maxSnapshotChars | 65536 | 整体 snapshot 文本预算；超限完整 skip，不截断 |
| maxSnapshotImages | 20 | projected suffix 图片上限 |

route 和 capability 是 allowlist，不负责注册缺失能力。可移植的 same 继承 Primary 模型，不代表模型族独立；read-only 请求 read/grep/glob，但 profile 没有暴露这些工具时会安全退化到接近 reason-only。

安全与 runtime 边界

- child 永远看不到 deliberate；maxDepth 防止递归分叉。
- 手动 sibling 并行执行、独立失败。
- reasoning masking 从不修改 append-only Parent Session。
- in-process child 共享 workspace；tool filter 不等于文件系统、进程或凭据隔离。
- Bundle 不提供 mutation-capable child，也不能回滚文件、命令、数据库或网络副作用。
- 含图审查只在最终 child route 明确支持 image input 时启动，否则创建 child 前直接 skip。
- turn-stopping 是稳定 checkpoint，不是 token entropy detector。
- 同模型一致只是弱证据；child 是提案生成器，不是外部事实核查器。
- 每次自动尝试都会增加一次 child LLM call；发布 update 还会增加一个 Primary assimilation Step。

常见问题

Web 找不到 deliberate

安装 Bundle 后重启 Web，再检查：

npx @deepseek-ai/dsh plugin --profile web why dsh-deliberation
npx @deepseek-ai/dsh --profile web --dump-config

模型没有调用 deliberate

安装只让工具可用，不会强制模型调用。请先用上面的明确 smoke prompt。自动审查是另一条 runtime 路径，除非配置启用，否则不会运行。

自动 child 跑了，但 Primary 没显示更新

updates-only 下，合法的 no_update 本来就不会生成 parent notice 或 assimilation Step。协议调试可临时用 publish: all；shadow eval 用 observe-only。

从 Git 安装时 pnpm 拒绝运行 build

Git 源码依赖会执行 prepare，pnpm 10 可能要求 profile 的 pnpm-workspace.yaml 先声明构建许可。优先安装正式 npm 包；若必须装 Git，请复制 pnpm 错误中给出的精确 allowBuilds key，加入 profile 后重新安装。

pnpm 提示缺少 DSH peer dependencies

DSH profile 有意设置 autoInstallPeers: false。树外插件把 Host API 声明为 peer，而 DSH launcher 会通过 profile fallback 提供同一套 Cordis/DSH 实例。因此 plugin add 时出现 peer warning 属于预期行为；不要在插件里再安装第二份 Cordis。请用 --dump-config 和一次真实 Web boot 验证兼容性。

开发与发布检查

npm ci
npm run release:check

release check 会依次完成类型检查、全部测试、production build 和 npm tarball dry run。当前目标版本线是 DSH 0.1.1-rc.2；Harness 仍处于 developer preview，每次升级后都应重跑 smoke。

深入文档

- Runtime 完整流程
- Cordis / Harness / 源码映射
- 研究假设、论文、本地实验与评测计划
- Reasoning-masked fork 实现说明
- 术语表
- 待定与明确不支持内容

MIT。本项目与 DeepSeek 没有从属或背书关系。