@sky_sun/dsh-debate

Readme

# 多 agent 隔离辩论插件（@sky_sun/dsh-debate）

给 DeepSeek Harness 增加一个面向模型的 `debate` 工具：提出一个议题，多个不同"底色"（怀疑论者 / 乐观派 / 务实派 / 创意派）的子 agent 会：

1. **隔离发散** —— 各自独立联网取证、独立论证，互不可见（防人云亦云 / 羊群效应）
2. **交叉辩论** —— 汇总各方论点，互相反驳、修正、补充（纠错 + 激发新观点）
3. **评审收敛** —— 多个评审各自独立评审，再交叉辩论，产出最终结论 + 分歧点

**特性**：辩论作为**后台 job** 运行，立即返回 job id；用 `job_output` 查看每个 agent 的实时进度（Web UI 的 jobs 列表也会显示）。同一波次内的 agent **并行**执行（隔离发散的 4 个辩手同时跑），总耗时约为串行的 1/3。中途断网后**再次调用会自动断点续跑**——已完成的 agent 直接复用，只补跑剩下的。

## 技术要点

- **编排复用 `ctx.subagents` seam**：每个子 agent 是独立 session，天然严格隔离（spawn provider 不共享对话历史）。
- **后台 job（`ctx.jobs`）**：辩论注册为 `debate` kind 的后台任务，`readOutput` 增量输出每个 agent 的进度。
- **波次并行**：隔离发散、每轮交叉辩论、评审各自为一个波次，波内 `Promise.allSettled` 并行、波间串行（后一波依赖前一波产出）。
- **断点续传（session 引用）**：存档只存每个已完成步骤的**子 agent session id**（内容权威来源是子 agent 自己的持久化会话，DSH 原生），不复制文本；中断后重调时从 `sessionPersistence.load(sessionId)` 读回正文，已完成的 agent 直接复用。每个 agent 完成后立即存档（串行化写避免并发竞态），所以 kill/断网都能保留进度。
- **底色差异靠 `persona`**：子 agent 的 `deployment:persona` section 被遮蔽为各自的立场人设。
- **抗幻觉靠"强制取证"**：每个子 agent 的 prompt 都要求联网搜索、附来源、区分"查证事实"与"推理"。
- **能力继承**：子 agent 通过 `composeFrom` 继承父 agent 的 preset，所以能调用 `web_search` 等工具。

> ⚠️ 关于 `temperature`：当前 DSH 版本的请求路径尚未消费 `temperature`（`LlmCallConfig.temperature` 字段存在，但源码中没有消费方）。本插件的 `DebateAgent.temperature` 字段已**预留**，底色差异目前实际由 persona 与 prompt 承担。待 DSH 实现采样参数消费后，该字段即可直接生效。

## 安装

```powershell
# 安装到你的 profile（本插件声明了 dsh.bundle.patch，安装后自动挂载）
dsh plugin --profile web add @sky_sun/dsh-debate

# 或者直接 npm install 到 profile 目录
cd $env:USERPROFILE\.dsh\profiles\web
npm install @sky_sun/dsh-debate
```

安装后重启 `dsh web`，`debate` 工具即可用。

## 配置

| 字段 | 默认 | 说明 |
|---|---|---|
| `provider` | `spawn` | `ctx.subagents` 的 provider 名（须支持 `persona` capability） |
| `roster` | 内置 4 底色 | 自定义辩论方阵容：`{ id, name, persona, temperature? }` |
| `defaultRounds` | `1` | 交叉辩论轮数（工具参数 `rounds` 可覆盖） |
| `defaultJudges` | `2` | 评审数量（工具参数 `judges` 可覆盖） |
| `storageBackend` | `json` | storage backend 名，用于断点续传存档 |
| `debaterModel` | 父默认 | 辩手（隔离发散 + 交叉辩论）使用的模型，如 `deepseek-v4-flash` |
| `judgeModel` | 父默认 | 评审 + 主席评审使用的模型，如 `deepseek-v4-pro` |

**模型分配**：辩手阶段（发散 + 交叉辩论）以联网取证、组织论点为主，事实检索占主导，用快模型（flash）即可；评审阶段（评审 + 主席）需要比较各方论点、挑漏洞、综合权衡，用强模型（pro）保证判断深度。默认 `debaterModel: flash`、`judgeModel: pro`。

**token 统计**：每个 agent 完成后会输出其 token 用量，辩论结束汇总总消耗。token 计量依赖 `token-meter`（base bundle 已挂载），拿不到时优雅跳过统计。

## 使用

在聊天里说：

> 辩论一下「远程办公是否应该成为默认工作模式」

模型会调用 `debate` 工具（参数 `topic`），返回一个 **job id**。用 `job_output <id>` 查看每个 agent 的实时进度，最终会输出完整结论。你也可以要求更多轮次或评审：

> 用 3 轮辩论、3 个评审，辩论「通用人工智能是否会在 10 年内实现」

**断点续传**：若辩论中途失败（如网络断开），直接再说一次同样的话（或重新触发 `debate`），插件会检测到未完成的存档并**从断点续跑**——已完成的 agent 不会重跑。

## 自定义底色示例

```yaml
- insert:
    - id: tool-debate
      name: '@sky_sun/dsh-debate'
      config:
        provider: spawn
        roster:
          - id: data-scientist
            name: 数据科学家
            persona: 你只信数据和统计，任何结论都要有数字支撑。
          - id: historian
            name: 历史学者
            persona: 你习惯从历史长周期看问题，警惕短期叙事。
          - id: engineer
            name: 工程师
            persona: 你关心这东西能不能造出来、成本多少、怎么运维。
```

## 测试

仓库附带一个**独立逻辑测试**，用 Node 原生类型剥离直接加载真实源码，仅 mock 运行时 seam（`defineTool` / `ctx.subagents` / `ctx.jobs` / `ctx.storage`），验证：后台 job 注册与进度输出、三阶段编排顺序、开局隔离性、交叉辩论携带前文、以及**断点续传**（中断后 resume 跳过已完成 agent）：

```powershell
node --experimental-strip-types test\debate.test.mts
```

> 注意：`node_modules\@deepseek-ai\dsh-tools` 是测试用的 mock 包，仅为让类型剥离后的源码能独立运行；真机挂载时使用 DSH 提供的真实包，不要覆盖它。

## 已知限制

- 子 agent 的 `temperature` 目前不生效（见上文说明），底色差异靠 persona。
- 辩论质量与子 agent 数量、轮数成正比，但 token 成本与耗时也线性增长。
- 本插件依赖 `ctx.subagents`（spawn provider）、`ctx.tools`、`ctx.jobs`、`ctx.storage`，须在 web profile 组合下使用。
- 断点续传按 topic 字符串区分：同一 topic 的多次调用视为同一次辩论（配置不符时会丢弃旧存档重来）。