前言¶
在 DSH（DeepSeek Harness）里跑「多路候选、择优上报」的推理模式时，常见的做法是手写 preset，把并行数量和递归层数写死在模板里。问题是：并行开得太多会瞬间占满子代理并发名额，递归层数太深又收不回来，两者互相牵连，调参基本靠试错。
下面介绍的插件把这两个值交给用户设置。仓库 xiong4huo/dsh-recursive-best-of-n（维护者 xiong4huo，分类「工作流」）是一个 DSH bundle，新增 agent preset recursive-best-of-n：代理数量、并行宽度、递归深度全部读取「设置 → Plugins → Subagent」里的两个设置，插件自身不写死任何数字。它属于社区目录 SkillHub 收录的第三方插件，与 DeepSeek / 幻方无官方从属关系。
这是什么¶
一句话定位：一个 DSH 插件（bundle），声明名为 recursive-best-of-n 的 agent preset，主 agent 在每条助手消息里并行派发多个子代理，每个内部节点逐份等待提交、全部到齐后择优上送，最底层叶子真正执行任务。
它解决的是「多路采样 + 递归择优」在 DSH 里的落地问题：树的形状不靠人手写 prompt，而是由两个用户设置自动换算，并且严格不超出子代理的并发容量。
核心功能：两个设置换算出整棵树¶
插件每次请求读取两个值：
- 最大递归深度（
maxDepth） - 子智能体并行数量上限（
maxActiveSubagents）
一棵按层展开的树，若每层并行 f 个、深度 d，同时在线的子代理最多是 f + f² + … + f^d（父级在子级运行期间仍驻留、占名额）。所以插件按三步换算：以最小并行宽度 2 求并行上限内可达的最大有效深度；在该深度下求仍放得下的最大并行宽度 f；把 depth、fanout 以及「设置深度被容量折算」的说明写进每个节点的运行时上下文。
以并行上限 40（当前 Desktop profile 的设置）为例：
| 用户设置的最大深度 | 自动得到：每层并行 f | 有效深度 | 同时在线子代理峰值 | 一次请求代理总数 |
|---|---|---|---|---|
| 1 | 40 | 1 | 40 | 41 |
| 2 | 5 | 2 | 30 | 31 |
| 3 | 3 | 3 | 39 | 40 |
| 4 或更大（当前 10） | 2 | 4 | 30 | 31 |
几个要点：
- 最大深度很大时自动变窄。例如当前的 10，若要每层 2 个、10 层，需要约 2046 个同时在线子代理，超出 40 的上限，所以运行时上下文会注明
configured maximum depth 10 is capacity-limited to 4。 - 想让主 agent 一次开更多，把「最大递归深度」调小。设为 1 就是一次并行开 40 个（一层平铺、主 agent 直接择优）；设为 2 则每层 5 个；设为 3 则每层 3 个。
- 两项设置在每个新请求读取，改完下一轮请求即生效。
- 想真正递归 10 层，需要把并行上限提高到 ≥2046（或接受每层 1 个的退化形态）。
运行协议上，所有内部节点（含主 agent，即 remaining > 0）的主协议是：在同一条助手消息里把本节点该开的 N 个 subagent 调用一起发出，每个 prompt 逐字包含完整任务 + 一句「你的回答会和其他独立答案比较」；随后只回一行状态结束回合等待；子代理提交以 Background subagent ... finished 通知形式到达，逐份计数，未到齐时只回一行状态，不回答、不追加派发、不调用消磨时间的工具；全部到齐后比较、选最好的一个，原样转发。叶子（remaining == 0）才用工具真正执行任务，产出完整自洽的答案。所有深度都不向用户提问、不停留在计划、不越界改文件或提交。
其余实现要点：注册 preset 的模块是 preset-recursive-best-of-n（来自 @deepseek-ai/dsh-agent-preset，id: recursive-best-of-n，order 5）；persona 承载并行多开与择优上报协议；本插件自带的 JS 插件 recursion-context（index.js）负责读设置、算树形、注入运行时上下文；tool-subagent 使用 provider: spawn、toolName: subagent，不配置 maxDepth，因此服务在每次委派时读取用户设置的 subagent.maxDepth 作为硬上限，子代理不指定 agentPreset，自动继承父代理当前 preset 版本。叶子可用的工具包括 tool-bash / tool-pwsh（按平台）、tool-fs / tool-fs-search / tool-jobs / tool-web / tool-skill / tool-todo，另有 agent-instructions / time-context 和 compaction 组处理长任务的上下文压缩。
安装与启用¶
本仓库根目录就是插件包根目录（package.json 的 dsh.bundle.patch 指向 cordis.patch.yml），因此可以直接从 GitHub 安装，不需要 &path: 子目录参数。
从 npm 安装（推荐）：
dsh plugin --profile desktop add dsh-recursive-best-of-n@1.4.0
从 GitHub 安装：
dsh plugin --profile desktop add "git+https://github.com/xiong4huo/dsh-recursive-best-of-n.git#v1.4.0"
也可以克隆仓库后，在 GUI 的插件管理里安装本地 bundle 目录（link: 安装，便于改代码）。
安装后在 Web GUI 里启用：
- 打开 设置 → 通用 → Agent 预设（或新会话的 preset 选择器），选择 Recursive Best-of-N（递归择优树）。
- 新建会话后发任意请求，会话树 / 右侧 subagent 目录可以看到并行开出的子代理。
- 想让主 agent 一次开更多，先按「设置如何换算成树」调整「设置 → Plugins → Subagent」，变化对下一轮请求生效。
两点注意。若 GUI 里暂时看不到该预设，先刷新页面；仍看不到时重启一次 DeepSeek Harness（插件包含 JS 插件模块）。用 Git 地址安装时，plugin_manager 会先用 git ls-remote 检查仓库连通性，本机需要能访问 github.com；直连受限时请给 Git 配置代理。npm 安装没有这个检查。
典型用法：用一次实测验证树的形状¶
GUI 手动验证的做法：在「设置 → Plugins → Subagent」把最大深度设成 2、并行上限设成 14（或任意值），新会话选择 Recursive Best-of-N，发送「37×3 等于几？只回答数字」。预期主 agent 一条消息里同时出现 3 个 subagent 调用；随后 3 个一级子会话各带 3 个二级子会话；主 agent 先显示「已启动 3 个…」，逐份收到提交（1/3、2/3、3/3）后只输出一个答案。
README 记录的最近一次命令行端到端实测（2026-10-24，deepseek-account/deepseek-flash，测试 profile 的 Subagent 设置为最大深度 2 / 并行上限 14）结果如下：
- 插件按设置算出
fanout=3、有效深度2（f + f² = 3 + 9 = 12 ≤ 14）。 - 子代理树：主代理 3 个一级子代理，每个一级再各 3 个叶子，共 12 个子代理。
- 主代理在同一条助手消息里发出 3 个
subagent调用；状态依次为「已启动 3 个…」→「已收到 3 份中的 1 份」→「2 份」→ 3 份到齐后输出111。 - 一级节点同样一条消息并行开 3 个叶子、逐份等待、择优上报；叶子直接输出
111。 - 整轮约 9–11 秒，无报错。
该实测由 verification/ 目录下的端到端验证工具完成：用一次性临时 profile（dsh-base + dsh-web-app + 本插件 + 测试 bundle）启动独立 Web Host，测试插件直接创建绑定 recursive-best-of-n 的会话、提交任务、等待整棵树 settle 并记录子代理树，不经过 GUI。逐层轨迹见 verification/README.md。该目录仅用于验证，不要把 dsh-recursive-e2e 安装到日常 profile。
一次请求的代理总数计算公式为 1 + f + f² + … + f^d，(f, d) 由两个设置自动算出。并行展开的层同时跑，墙钟时间约为「深度次叶子任务 + 各级择优」。当前 Desktop 设置（10 / 40）下的自动解是每层 2 个、4 层，约 31 个代理；把最大深度调到 1 则是一次 40 个平铺候选、41 个代理。这属于「值得多花 token 换更好答案」的模式，闲聊也会完整走树。
适用场景与注意¶
适合的场景：需要在 DSH 里做多路采样择优、又不想自己写分支和计数逻辑的开发者；希望并行数量和递归层数随环境调整、而不是写死在 preset 里的人。只要把两个设置调小，就能在一次请求里得到几十路平铺候选，适合对稳定性要求高的核心任务。
需要留意的限制，均来自 README：
- 两个设置是上限，插件取的是「深度尽量深、容量内最宽」的可行解，不是「每层都开满并行上限」——那会瞬间占满容量，无法继续递归。
- 每层会产生过程消息（「已启动…/已收到 k 份」），这是模式本身的可视化，不是失败。
- 子代理是 in-process 新会话，看不到父会话上下文；父代理必须在 prompt 里逐字带上完整任务（协议已要求）。
- 子代理权限在启动时固定，不能从内部提权；需要审批的操作会在子代理内被拒绝。
- 该 preset 依赖 Web/Desktop profile 的 Host 服务（
subagents+spawnprovider、agentPresets、systemPrompt等），不适用于不组合这些服务的 headless/SDK profile。 - 想自定义形状时只有两个旋钮可调，即那两项设置；若要增删叶子工具，直接编辑
cordis.patch.yml的plugins列表，模型选择可在tool-subagent.config里扩展modelSelectionSettings等字段。
另外需要明确：插件以安装它的 DSH 进程的当前权限运行，安装前建议先检查源码与许可证。仓库使用 MIT 许可证，配置项与安装命令见前文「安装与启用」。
卸载方式是在 GUI 的插件管理里移除 dsh-recursive-best-of-n，或调用 plugin_manager 的 remove_bundle。移除后该预设从列表消失；已存在的会话保留它们启动时的组合。
结尾¶
这个插件的价值在于把「多路采样 + 递归择优」的树形计算从 prompt 里搬出来，交给两个用户设置：容量以内自动求最深可行深度，在该深度下自动求最宽并行宽度，运行时上下文里注明折算结果。对需要在 DSH 里跑 Best-of-N 类推理的开发者，它省掉了自己维护计数与等待逻辑的成本。
目录页：https://www.skillhub.cn/plugins/xiong4huo/dsh-recursive-best-of-n
源码与文档：https://github.com/xiong4huo/dsh-recursive-best-of-n
