# Pi Fusion

**经过 DRACO 评分验证的 Pi agents 模型融合。**

Pi Fusion 会把一个 prompt 分发给一组独立模型，让它们并行工作、可选地收集 evidence，再由 judge model 综合、验证并输出最终答案，整个过程发生在 Pi 里。

它的重点不只是“多跑几个模型再合并文本”。Pi Fusion 已经做过 DRACO full10 评分验证：生成阶段只看 prompt-only cases，rubric 只在生成结束后的 scorer 阶段加载，10 个 case 全部完成，并提供 sanitized public benchmark summary。

它受 hosted Fusion-style APIs 启发，但实现为 Pi extension：你选择模型，保留 artifacts，并且可以把 fusion layer 接到现有 Pi 工具和上下文中。

官网：<https://aa2246740.github.io/pi-fusion/>

文档：[English](README.md) | 中文 | [Benchmarks](docs/benchmarks.md) | [中文基准说明](docs/benchmarks.zh-CN.md)

## 这个仓库为什么突出

很多 fusion demo 停在“运行多个模型并合并答案”。Pi Fusion 的定位是有评分验证的 fusion engine：

| 证据点 | 公开 claim | 为什么重要 |
| --- | --- | --- |
| DRACO full10 tested | 完成 10-case benchmark protocol | 这是有评分的项目，不只是 demo |
| Scorer-only rubric access | rubric 只在 generation sealed 后加载 | 生成器看不到 private scoring criteria |
| 对比 Fusion API | 73.80 vs reported Fusion API 69.00 | claim 绑定明确 benchmark result |
| 对比 budget baseline | 73.80 vs reported Fusion API budget 64.70 | 相对 budget baseline 高 +9.10 |
| 最新 validation 稳定性 | 10/10 cases，0 judge failures | 完整 protocol 跑通 |
| 本地 artifact trail | answers、evidence summaries、tokens、costs 留在本地 | 用户可以检查运行过程 |

## 它能做什么

Pi Fusion 为一个模型答案不够用的任务提供通用 fusion layer：

- 多个 participant models 并行独立回答
- judge synthesis 和 contradiction analysis
- 可选 verification/revision loop
- 可选 web/evidence tools
- 用于确定性计算的 sandboxed bash
- 每个 participant 独立的 workspace sandbox 和读写工具
- model fallback 和 retry policy
- artifacts、evidence summaries、token usage 和 cost reporting
- Pi 原生命令和配置

适合研究、规划、架构决策、调试假设、代码/设计评审、产品比较、写作、文档综合，以及其他需要更高可靠性的高风险问题。

## 安装

Pi Fusion 是 Pi package/extension。

```bash
pi install git:https://github.com/aa2246740/pi-fusion@main
```

npm package 名称：

```bash
npm install @aa2246740/pi-fusion
```

本地开发：

```bash
cd pi-fusion
npm install
pi -e ./index.ts
```

Pi package discovery 在 `package.json` 中声明：

```json
{
  "pi": {
    "extensions": ["./index.ts"]
  }
}
```

## 命令

```text
/pi-fusion-config       配置 participants、judge、tools 和 evidence backend
/pi-fusion-doctor       诊断模型和 evidence backend 可用性
/pi-fusion <prompt>     运行 fusion panel
```

示例：

```text
/pi-fusion Should we migrate this module to a plugin architecture?
/pi-fusion --fast Summarize the tradeoffs of these three implementation plans.
/pi-fusion --quality Compare the vendors and cite current sources.
```

## 配置

运行：

```text
/pi-fusion-config
```

你会选择：

1. participant models
2. judge model
3. 从可选模型列表中选择 fallback models
4. web/evidence policy
5. evidence backend mode，通常在运行时 auto-detect
6. sandboxed bash policy
7. monitor 和确认默认值

配置保存在：

```text
~/.pi/agent/pi-fusion/config.json
```

最小配置可以不启用 web retrieval：

```json
{
  "participants": [
    { "model": "openai/gpt-4.1" },
    { "model": "anthropic/claude-sonnet-4-5" }
  ],
  "judge": { "model": "openai/gpt-4.1" },
  "defaultFallbacks": [],
  "webPolicy": "optional",
  "toolPolicy": { "bash": "sandboxed" },
  "monitorDefault": false,
  "confirmBeforeRun": true
}
```

## Evidence layer

Pi Fusion 不是 scraper adapter，但它有一个可选 evidence layer，用于需要现时信息或来源支撑的任务。

如果没有配置或自动发现 evidence backend，Pi Fusion 仍然会作为 model-fusion engine 运行。如果发现兼容的 evidence backend，participant 和 judge models 可以使用 `web_search` 和 `web_fetch` tools。

运行时，Pi Fusion 会从常见 Pi/MCP 配置位置自动检测兼容的本地 MCP search/fetch servers。如果没有发现 backend，而 prompt 看起来需要 sources，Pi Fusion 会询问你是继续不带 web evidence、取消运行，还是为本次运行添加用户提供的上下文/evidence notes。

### MCP evidence backend

MCP 是第一种支持的 connector type。Pi Fusion 不要求也不内置 `unified-search`；任何兼容 MCP search/fetch server 都可以使用。多数用户可以把 evidence backend 留给 auto-detect。高级用户可以固定一个 explicit backend：

```json
{
  "webPolicy": "optional",
  "webBackend": {
    "type": "mcp",
    "serverName": "my-search",
    "searchServerName": "my-search",
    "searchTool": "web_search",
    "fetchServerName": "my-reader",
    "fetchTool": "web_fetch",
    "fetchFallback": "off",
    "maxResults": 5
  }
}
```

Expected search input:

```json
{ "query": "..." }
```

Pi Fusion 可以解析常见 search result shapes，例如带有 `title`、`url`/`link` 和 `snippet` 字段的 `organic[]`、`results[]` 或 `items[]`。

Expected fetch input:

```json
{ "url": "https://example.com" }
```

Pi Fusion 可以解析带有 `content`、`text` 或 `markdown` 的常见 fetch shapes。

### Internal/private backends

你可以在 MCP interface 后面使用 private MCP servers、company search、本地 crawlers 或 hosted search APIs。Provider-specific backend，例如 `unified-search`，应该被看作可选兼容实现，而不是 Pi Fusion 核心依赖。

## Workspace sandboxes

面对大型项目任务时，Pi Fusion 会把当前 Pi working directory 复制成一个 Pi Fusion 管理的 baseline，并为每个 Participant Model 创建一个独立可写 sandbox。Participant 只能通过 scoped `workspace_*` tools 在自己的 sandbox 中 list、search、read、write、edit 文件。

Sandbox 写入不会修改真实用户 workspace。运行结束后，Pi Fusion 会把每个 participant 的 sandbox root、变更文件列表和 ChangeSet artifacts 写到 run directory，方便 judge 和用户审查具体文件级工作，而不是只看纯文字回答。

## DRACO 评分验证结果

Pi Fusion 在 sealed fixed DRACO-10 validation run 上拿到 **73.80**，比 reported Fusion API **69.00** 高 **+4.80**，比 reported Fusion API budget **64.70** 高 **+9.10**。

在这个仓库里，**DRACO verified** 指的是公开 benchmark claim 有完整 DRACO 10-case runs、prompt-only generation、scorer-only rubric access 和 sanitized aggregate results 支撑。它不是 DRACO 官方认证，也不是说 Pi Fusion 在所有评估里超过所有 Fusion API modes。

我们在固定 10-case DRACO validation protocol 上评估了 Pi Fusion。Final answers sealed 之后，scorer 才加载 rubric 和 scoring artifacts。

Public repository 只保留 aggregate scores、methodology notes 和 protocol checks。Raw scorer files、private rubric artifacts、case prompts 和 run internals 不公开发布。

| 验证项 | 状态 |
| --- | --- |
| validation cases | 10/10 |
| generation input | sanitized prompt-only case files |
| rubric access | scorer-only，final answers sealed 后才加载 |
| latest validation judge failures | 0 |
| public artifact policy | 只发布 sanitized aggregate summaries |

| System / run | DRACO score | 相对 reported Fusion API | 相对 reported budget |
| --- | ---: | ---: | ---: |
| Pi Fusion latest sealed DRACO-10 validation | **73.80** | **+4.80** | **+9.10** |
| Reported Fusion API headline result | 69.00 | - | +4.30 |
| Reported Fusion API budget baseline | 64.70 | -4.30 | - |

Latest validation 完成了全部 10 个 cases，judge failures 为 0。

生成阶段使用 sanitized prompt-only case files。Benchmark answer/rubric/scoring artifacts 在生成阶段不提供给 Pi Fusion，只在生成后由 scorer 使用。

更多方法论和 sanitized results 见 [`docs/benchmarks.zh-CN.md`](docs/benchmarks.zh-CN.md)。

## 开发

```bash
npm run check
npm test
```

## 安全

Pi extensions 会以你的本地权限运行。安装第三方 package 前请先审查源码。Pi 本身不提供进程内安全 sandbox。Pi Fusion 因此把 workspace sandbox 当作产品层隔离：文件先复制到 participant 独立目录，participant 写入只留在那里，把 ChangeSet 应用回真实 workspace 是独立于 Fusion Run 的步骤。

Pi Fusion 的 bash tool 是 sandboxed，面向确定性计算，而不是 arbitrary host access。

## License

MIT