dsh-deliberation

English | 简体中文

一个非官方 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 [email protected]
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 没有从属或背书关系。