@aprilwizard/dsh-multi-cot

English | 中文

Multi-CoT 通过重复生成并采样思维链，为 dsh 提供近似“并行测试时计算”的能力：同一输入 并行跑 samples 条推理链，由内部投票选出最佳结果，再用它驱动“先计划后执行”或完整的 “计划 → 执行 → 复检”三阶段工作流。插件只包含纯函数选择核心和稳定的协议提示词，接在 agent/pre-step、llm/stream、agent/turn-stopping 三个扩展点上，不需要修改 dsh 源码。

近期通过修改 codex 源码，用 deepseek-v4-flash 在隔离环境下用 Terminal-Bench 2.1 做了开/关对比（baseline = 普通模式，workflow = 多采样三阶段）：

题目	baseline	workflow
write-compressor (hard)	✅ 685.6s / 2475B / 1.83M in	✅ 643.5s / 2231B / 1.17M in
cancel-async-tasks (hard)	❌ 219.8s（5/6 测试过）	✅ 647.3s
polyglot-rust-c (hard)	✅ 522.0s	✅ 1,097.9s
regex-chess (hard)	✅ 1,075.0s / 6.93M in	✅ 产物合格，进程 1800s 超时被杀
sqlite-db-truncate (medium)	✅ 129.2s	✅ 598.5s

单题 GSM8K 对比：正确率不变（26/26），耗时约 29×（4.4s → 126.8s），输入 token 11.1k → ~219k——多采样主要用成本换稳定性。

注：以上为近期 codex 实验的参考数据；本 dsh 插件尚未在同条件下跑过这套对比。

设计思路

采样与投票

普通回合只问模型一次，返回什么就是什么。这个插件用相同输入问 samples 次，再让 samples 个内部投票者给候选打分。输入相同让成本可控：provider 会缓存共享前缀，并行 采样不会真的付出 samples 倍的输入成本。结果全部相同就跳过投票。

三阶段工作流

workflow 模式把任务分成三个阶段：信息收集、具体实现、编写报告。每阶段三步：计划 （离线采样 + 投票）、执行（普通工具循环）、复检（再一轮离线采样 + 投票）。复检失败就 重新计划，最多 reviewMaxRetries 次，再失败则强制推进并标记“存疑”。阶段状态由插件 管理，不靠模型打印标记。

离线工作放在哪里

计划必须在模型请求构建前选好。llm/stream 要求同步返回流，计划步也不能声明空批 （空批会让 loop 关回合）。所以：

• 首个计划在 agent/pre-step 选择；
• 后续计划在 agent/turn-stopping 选择；
• 选中的计划存进进程内表，llm/stream 只做同步短接，返回存好的计划流。

因此后续阶段的计划之前会多一行 user 角色“为阶段 N 制定计划”。

缓存

协议文本是系统提示词里稳定的 section（order 50）。采样请求字节完全相同；投票共享 一个前缀（所有候选的压缩链），只追加自己的完整链和打分指令。opencode-go 与官方 DeepSeek 都实测过：

实验	opencode-go	官方 DeepSeek
相同请求重复	0 命中	0 命中
共享前缀 voter 1+	~90%	~90%
真机工作流缓存命中	83.1%（40 次）	62.7%（32 次）

相同请求重复不命中（推理模型把 reasoning tokens 算进输出端缓存单元），所以设计 依赖的是共享前缀复用。

推理链

投票用的是模型真实推理的压缩版。chat completions wire 上 reasoning_content 经 pi-ai 变成 thinking 事件，dsh adapter 再映射成 reasoning 块。有个坑： opencode-go 内置 provider 默认走 DeepSeek thinking 方言，未指定 effort 时会发 thinking: {type: "disabled"}；设 compat.thinkingFormat: openai 即可保持推理开启。

日志与降级

每次离线请求、usage、决策和阶段切换都作为会话事件落盘，选中的计划由 loop 写成普通 assistant 消息，会话日志是唯一事实来源。失败一律降级而不是卡死：选择为空 → 普通模型 调用；结果相同 → 跳过投票；票无效 → 多数优先/第一条；复检解析失败 → PASS；流异常 → 普通循环。

配置

键	默认	含义
mode	off	off 关闭；first-plan 先离线计划再执行；workflow 对三个阶段分别运行计划 → 执行 → 复检。
samples	3	每次离线选择的并行采样数（也是内部投票者数）；启用模式下为 2–16。
votePoints	100	每张内部票分配给各采样的整数总分。
compressedChainMaxTokens	300	压缩思考链的绝对 token 上限。
compressedChainRatio	0.2	压缩链相对完整链长度的比例上限。
nearTopDistance	0.05	低于最高分该比例内的候选仍参与加权随机。
reviewMaxRetries	2	阶段被强制推进前允许的复检失败次数。

所有值在插件加载时校验；非法范围响亮失败，不静默回退默认值。

事件

本包声明四个 log-only SessionEventMap 成员：

事件	用途
multi-cot/phase	按轮次保存的阶段状态（最后一条生效）；resume/fork 通过 fold 恢复。
multi-cot/request	一次离线采样/投票/复检请求的完整 system 与 messages，保证可重建。
multi-cot/usage	一次离线请求的 provider usage。
multi-cot/decision	一次离线选择的选中下标、归一化分数与复检结论。

Model Experience

协议 section

模型看到什么

启用模式时，每个请求在 prompt order 50 处携带稳定的 multi-cot:protocol section。

工作流模式

The agent completes a task in three phases: information gathering, implementation, and report writing. Each phase runs a plan step, an execution step, and a review step. During execution you may gather missing information directly, but you must not change the plan; when the plan must change, return through review and re-plan. A phase review may fail at most twice before the phase advances anyway; when that happens, mark anything uncertain as doubtful in the final report.

先计划模式

Before executing a task, produce one concrete plan, then follow it during execution.

Token 影响

插件组合且模式启用时为固定按请求成本；off 不贡献任何文本。

KV Cache 影响

section 文本与顺序不变时前缀稳定；启用、停用或切换模式会使 order 50 起的复用失效。

计划、执行与复检步骤

模型看到什么

计划步呈现为离线选出的 assistant 计划；后续阶段的计划步与执行步携带稳定的 user 角色请求/指令行。

后续阶段计划请求与执行指令

Produce a plan for phase 2 (implementation). Do not execute it yet; it will be selected and reviewed before execution.

Execute the plan above for phase 2 (implementation). Gather missing information directly during execution, but do not change the plan unless a review requires it.

Token 影响

每个后续阶段计划前多一条 user 行、每阶段一条执行指令；离线采样与投票的 token 只计入 multi-cot/usage 事件，不计入循环的 assistant usage。

KV Cache 影响

同一轮内的离线采样共享字节相同的前缀；执行指令追加在可复用的计划前缀之后。

已知限制与后续工作

• 离线请求不参与上下文压缩 —— 长会话中采样输入可能膨胀；离线输入压缩边界待定。
• 阶段状态不做中断恢复 —— multi-cot/phase 可折叠出持久状态，但进行中的计划/复检 步骤本身无检查点；中断的轮次从下一个新轮次重新开始。
• 投票注入无完整链上限 —— 压缩链有界，但投票者自己的完整链按原样注入；该上限待定。
• 后续阶段计划请求多一条 user 行 —— 计划请求消息会留在转录中，位于离线选出的计划 之前；无历史痕迹的内部唤醒方案待定。

安装

先安装包，再在 cordis.yml 中组合：

npm install @aprilwizard/dsh-multi-cot

- id: multi-cot
  name: '@aprilwizard/dsh-multi-cot'
  config:
    mode: workflow   # off | first-plan | workflow
    samples: 3

peer 依赖为 @deepseek-ai/cordis、@deepseek-ai/dsh-agent、 @deepseek-ai/dsh-invariants、@deepseek-ai/dsh-llm、 @deepseek-ai/dsh-session 与 @deepseek-ai/dsh-system-prompt。

安装注意事项：已发布的 dsh rc.1 包 peer 依赖未发布的纯类型包 @deepseek-ai/dsh-type-meta，npm 自动安装 peer 会失败。在上游发布它之前，请用 pnpm 安装（pnpm-workspace.yaml 里设 autoInstallPeers: false），或等待新版 dsh 包发布。

开发

插件已在 npm 发布的 @deepseek-ai/dsh-*（0.0.1-rc.1 + @deepseek-ai/cordis 4.0.1）上验证通过，不需要 dsh checkout 或 link：

pnpm install
pnpm build         # 生成 lib/types 供发布
pnpm test          # 单测 + 集成 + baseline/workflow 对比
pnpm typecheck
pnpm cache-check   # opencode-go 端点的真实缓存实验
pnpm live-run      # opencode-go 端点的真实端到端工作流

一个安装注意事项：已发布的 rc.1 dsh 包 peer 依赖纯类型包 @deepseek-ai/dsh-type-meta，而它从未发布。pnpm-workspace.yaml 因此设置了 autoInstallPeers: false，所有运行时 peer 都在 devDependencies 中显式列出。 等更新的 dsh 包发布后，升级这些 devDependency 版本即可。

cache-check 与 live-run 读取 OPENCODE_GO_API_KEY（回退 OPENCODE_API_KEY），两者都不会打印凭证。

Provider 说明（推理捕获）

DeepSeek 系模型在 chat completions wire 上返回 reasoning_content。pi-ai 内置的 opencode-go 与 deepseek catalog provider 默认走 DeepSeek thinking 方言，未指定 reasoning effort 时会发送 thinking: {type: "disabled"}，导致 reasoning 内容到不了 harness。将 route 配置为 compat.thinkingFormat: openai 可保持 provider 默认思考 开启：

- id: llm
  name: '@deepseek-ai/dsh-llm-pi-ai'
  config:
    providers:
      opencode-go:
        apiKeyEnv: OPENCODE_GO_API_KEY
        api: openai-completions
        baseURL: https://opencode.ai/zen/go/v1
        compat:
          thinkingFormat: openai
        models:
          - id: deepseek-v4-flash
            contextWindow: 1000000
          - id: deepseek-v4-pro
            contextWindow: 1000000
      deepseek:
        apiKeyEnv: DEEPSEEK_API_KEY
        api: openai-completions
        baseURL: https://api.deepseek.com
        compat:
          thinkingFormat: openai
        models:
          - id: deepseek-v4-flash
            contextWindow: 1000000
          - id: deepseek-v4-pro
            contextWindow: 1000000

两个 route 都用该配置验证过（官方 DeepSeek 还提供 deepseek-chat，它不返回 reasoning）。推理捕获不需要任何 dsh 源码改动：thinkingFormat: openai 下 pi-ai 会发出 thinking 事件，dsh 自带的 adapter 会映射成 reasoning 块。自带 adapter 的 usage 映射不转发 reasoning token 计数，因此 multi-cot/usage 事件会省略 reasoningTokens；链捕获与压缩不受影响。