fusion-symphony

Readme

# Fusion Symphony

> 多模型融合编排引擎（Multi-Model Fusion Orchestrator）—— 一个 DSH（DeepSeek Harness）插件包，基于 DSH 自身注册的 LLM Provider 做 MoA 式融合，**零训练**。
>
> `pluginId = fusion-symphony` · 注册工具 `fusion_symphony_orchestrate`
>
> [English README](./README.en.md)

## 它是什么

把 OpenRouter Fusion（静态面板 + 合成）、Sakana Fugu Ultra（动态编排 + 多轮校验）、Hermes MoA（顾问式并行 + 主 Agent 持工具）三种范式的优点，归约为 **一台引擎的三个可配置轴**（拓扑 × 工具权限 × 校验循环），并用纯 prompt 编排替代训练式协调器。所有模型调用走 DSH 已注册的 `ctx.llm` Provider（如 deepseek / pi-ai / OpenRouter 网关等），不需要外接网关。

## 实现形态（与文档的差异说明）

- 真实 DSH 插件是 **bundle 包**：`package.json` 声明 `dsh.bundle.patch` → `cordis.patch.yml`，把插件 entry 插入 Cordis 组合；插件模块导出 `{ name, inject, Config, apply(ctx, config) }`。
- 工具通过 `ctx.tools.register(defineTool({ ... }))` 注册（来自 `@deepseek-ai/dsh-tools`）。
- 模型调用通过 `ctx.llm`（`@deepseek-ai/dsh-llm`），证据通过 `ctx.web.search`。
- 文档目录 `Doc/fusion-symphony` 中的 `code.host` 骨架是**动态插件**视角的示意；本包是 DSH 真正加载的**静态 bundle 包**形式，功能等价、更贴近实际架构。

## 目录结构

```
Plugins/fusion-symphony/
├── package.json          # bundle 声明 + 入口
├── cordis.patch.yml      # 把插件 entry 插入 profile 组合
└── lib/
    ├── index.js          # 插件 + orchestrate 工具注册 + 编排引擎
    ├── llm.js            # ctx.llm 模型调用 + ctx.web 检索封装
    ├── prompts.js        # Gate/Conductor/Worker/Verifier/Aggregator 提示 + JSON 提取
    └── types/index.d.ts  # 公开类型
```

## 安装（把插件装进一个 profile）

```bash
# 从 DSH 安装目录/任意 cwd，用相对路径锚到插件目录
dsh plugin --profile default add file:D:\work\DeepSeekHarness\Plugins\fusion-symphony
```

`dsh plugin add` 会用 pnpm 安装到 profile，并因为本包声明了 `dsh.bundle` 而把它加入 `dsh.profile.bundles`；下次启动 profile 时 `cordis.patch.yml` 会插入 `fusion-symphony` entry。

> 注：`dsh --profile <name>` 的 profile 才走 bundle/patch 机制。若用 `default` profile，请按实际 profile 名替换。

## 配置（`cordis.patch.yml` 的 `config`，可在安装后修改，或运行期用工具参数覆盖）

| 字段 | 默认 | 说明 |
|---|---|---|
| `enabled` | `true` | 是否注册工具 |
| `provider` | `deepseek-official` | 默认 Provider 路由（已按本机运行环境核对：`settings.yaml` + `@deepseek-ai/dsh-llm-deepseek` 适配器） |
| `model` | `deepseek-v4-flash` | 默认模型 id |
| `conductorModel` | `""` | 门控/Conductor 用模型 id（留空则用 `model`） |
| `aggregatorModel` | `""` | Verifier/Aggregator 用模型 id（留空则用 `model`） |
| `workerModels` | `["deepseek-v4-flash", "deepseek-v4-pro"]` | worker 模型 id 列表（同一 provider 下的多模型 = 真实融合；auto/fugu 下前一半 advisor、后一半 agent） |
| `advisors` / `agents` | `2` / `2` | 默认顾问/调研员数量 |
| `search` | `true` | 是否允许 agent 角色使用 `web_search` 取证据 |
| `useConductor` | `false` | 预留：是否用 Conductor 动态生成 Plan（当前为静态多 worker） |
| `processBriefing` | `true` | 每次调用后注入一条"执行过程简报"上下文（各 worker 论断+证据来源+裁决），对话与会话日志可见；设 `false` 关闭 |
| `maxRounds` | `2` | 校验/重派轮次上限 |
| `maxWorkers` | `4` | 并发 worker 上限 |
| `maxTotalToolCalls` | `8` | 工具调用预算（保留） |
| `maxTokensPerWorker` | `4000` | 单次 worker 模型调用 maxTokens（实际按 ≥16000 兜底） |
| `maxTokensAggregator` | `16000` | 聚合器（最终报告组装）输出上限 |
| `maxSections` | `8` | 章节数上限（安全阀）；实际章节数由 Conductor 按任务决定（综述类 6+ 章、简单任务 1~2 章） |

**多模型融合的关键**：`workerModels`（或调用参数 `worker_models`）里填多个不同模型 id（可跨 Provider），是让"不同模型盲区互相抵消"的前提。只有单一模型时，插件退化为"同模型多角色"的 MoA，效果打折但仍可用。

## 调用

```
fusion_symphony_orchestrate
  query: "2026 年 X 行业市场规模官方最新数据是多少？"
  preset: "auto"            # auto|fusion|hermes|fugu
  return_mode: "synthesized" # 或 materials（Hermes 式：返回意见给宿主 Agent 合成）
  worker_models: [{provider:"openrouter",model:"anthropic/claude-...",role:"agent"},
                  {provider:"openrouter",model:"openai/gpt-...",role:"agent"},
                  {provider:"openrouter",model:"google/gemini-...",role:"advisor"}]
```

返回：`{ status, final_answer, divergence_report, summary, materials?, error? }`。

## 预设语义

| preset | 拓扑 | 工具 | 校验 | 返回 |
|---|---|---|---|---|
| `fusion` | 全 agent | 有 | 单轮合成 | synthesized |
| `hermes` | 全 advisor | 无 | 单轮顾问 | materials |
| `fugu` / `auto` | 混合 | 按角色 | 多轮校验+重派 | synthesized |

## 设计要点

- **零训练**：Conductor/Worker/Verifier/Aggregator 全是 prompt 角色，无任何权重更新。
- **任务分解（Conductor）**：章节数由 Conductor 按任务决定（`maxSections` 只是安全上限）；worker 分批写章（每批并发 = worker 数），章节篇幅不限、讲透为止（目标 3000 字以上/章）。
- **证据账本**：agent 角色的每条论断携带 `evidence`（原始检索结果），聚合器只引用账本。
- **深度校验**：verifier 除矛盾/缺口外还检查"覆盖度与深度"（子任务是否都有实质内容）；深度不足 → 定向重派到被标记的子任务深化。
- **范围收缩重派**：`allow_redispatch` 开启时，重派只针对 verifier 标记的**子任务**并携带明确要求，防成本爆炸。
- **零压缩组装（报告长度无单次调用上限）**：聚合器只生成框架层（标题/摘要/目录/概述/结语，一次轻量调用）；各章草稿由插件**逐字拼接**进 `final_answer`（`## 章节标题` 分节）。报告长度 = Σ章节长度，不再受"最后一次生成调用的输出上限"约束；完整章节草稿同时随 `materials` 返回。
- **降级链**：全 worker 失败 → 单模型直答（L2）；校验/聚合失败 → 标 `unverified`（L3）。
- **无训练 Conductor 的可靠性**：结构化 JSON 提取 + 失败回退（整题作答），不依赖模型输出格式稳定。

## 可观测性

- **过程上下文注入**：每次调用后，工具通过 `exec.deferContext` 注入一条"执行过程简报"（`processBriefing` 控制）——列出每个 worker 的论断摘要、证据来源、verifier 裁决与轮次统计，直接出现在对话中并写入会话日志；
- **定制卡片**：`presentCall`（运行中显示 `fusion-symphony · <preset>` + query）与 `presentResult`（完成后显示状态与统计：轮次/workers/models/分歧数），数据经 `output.presentationMeta` 投影、随会话日志可回放；
- 工具返回的 `summary`（rounds/workersUsed/models/fallbackLevel）即执行过程的统计视图。

## 已验证的接口（来自本机 DSH checkout 源码）

- `defineTool({ name, description, parameters, output:{schema,render}, timeoutMs, isConcurrencySafe, execute(args, exec) })`（`@deepseek-ai/dsh-tools`）
- `ctx.tools.register(definition)`、`ctx.systemPrompt.section({name,order,text})`
- `ctx.llm.stream({ provider, model, messages, system, temperature, maxTokens, signal })` + `BlockAssembler.blocks()`（`@deepseek-ai/dsh-llm`）
- `ctx.web.search({ query, maxResults }, signal)`（`@deepseek-ai/dsh-web`）
- Cordis bundle：`dsh.bundle.patch` → `cordis.patch.yml`（`insert` 列表，`@deepseek-ai/cordis-plugin-include`）

## 已知限制

- 已通过离线端到端冒烟测试（`npm test`，脚本化 mock LLM 驱动真实 `execute` 全链路）+ 安装态校验（`npm run test:install`，用 DSH 自身 `loadProfile` 校验 bundle 组合）。**真机对话级验证仍需重启 Web GUI（web profile）后，在会话中实际调用一次该工具**（会真实消耗 `deepseek-official` 的 API 配额）。
- `maxTotalToolCalls`/`est_cost_usd` 当前为近似/未计费（不读价格表）。
- `useConductor` 为预留开关：真正的"Conductor 动态 Plan"（文档中的完整 Conductor 提示）暂未接入，当前用静态多 worker + 校验/重派实现同等骨架。
- 单一模型时融合度下降（需多模型路由才见差异）；当前默认池 flash + pro 两个真实模型。

## 相关文档

- 设计：`D:\work\DeepSeekHarness\Doc\fusion-symphony\`（PRD / 架构 / 技术）