# pi-moa

> [English](./README.md) · [Gitee 仓库](https://gitee.com/zhuli2/pi-moa) · [npm](https://www.npmjs.com/package/pi-moa)

面向 [pi](https://pi.dev) 的 Mixture of Agents（MOA）扩展，以斜杠命令的形式复刻
Nous Research Hermes Agent 的 MOA 工作流。

- **1–3 个高智能参考模型**并行运行，每个模型只看到单轮上下文（无工具、无 system prompt）。
- **1 个主模型**接收带标签的参考意见 + 完整对话历史，正常作答并可使用工具。
  默认就是**当前界面选择的模型**；也可以选择固定一个聚合器。
- 模型与鉴权**复用 pi 已有配置**——配置文件只存 `provider/model` 标识，绝不存 API 密钥。
- **可选自动模式**（`/moa-auto`）：开启后，你输入的**每一条**消息都会自动走
  MOA 流程，无需再每次打 `/moa`。

## MOA 做了什么

一次 `/moa <prompt>` 分两个阶段：

1. **参考 fan-out。** 每个参考模型（1–3 个）拿到单轮上下文——仅当前这条
   用户消息（多轮会话时附带一段简短的对话总结）。无工具、无 system prompt、
   无历史。它们各自独立、并行作答。
2. **聚合。** 主模型收到所有参考回答（按来源标注）+ 完整对话历史，产出
   最终回复——与普通轮次一样，可正常使用工具。

主模型默认跟随你当前界面选择的模型；配置 `aggregator` 可固定一个。

### 能带来什么

- **交叉校验单一模型的盲区。** 相互独立的模型给出互补或冲突的第一轮意见，
  这比单个模型单独推理提供了更强的信号。
- **难题或模棱两可的问题更稳健。** 多角度交叉可降低单个模型「自信但错误」
  的概率。
- **无需手动获取第二意见。** 不必把同一个 prompt 复制到多个对话里——一条
  命令自动 fan-out 并收敛。
- **零额外配置。** 参考模型复用 pi 里已配置的模型；配置文件只存
  `provider`/`model` 标识，绝不存密钥。

## 安装

```bash
pi install npm:pi-moa
# 或开发期从本地路径安装
pi install ./moa
# 或手动复制到 ~/.pi/agent/extensions/ + ~/.pi/agent/skills/
```

首次在交互终端运行 `/moa` 会进入引导向导（选 1–3 个参考模型；主模型默认
跟随当前界面模型，除非你选择固定一个）。配置写入 `~/.pi/agent/moa.json`。

## 用法

```
/moa <prompt>             用默认预设运行一次 MOA
/moa                      显示用法 + 配置摘要（未配置时进入向导）
/moa list                 列出所有预设
/moa configure [名称]     交互式创建/编辑（默认 "default"）
/moa delete <名称>        删除一个预设
/moa status               显示配置与当前模型
/moa set-main <p>/<m>     设置固定主输出模型（默认跟随界面模型）
/moa-auto                 切换自动模式（每条消息都走 MOA）
```

## 配置

```json
{
  "default_preset": "default",
  "presets": {
    "default": {
      "reference_models": [
        { "provider": "anthropic", "model": "claude-sonnet-4-5", "reasoning_effort": "low" },
        { "provider": "openrouter", "model": "deepseek/deepseek-v3.1" }
      ],
      "aggregator": { "provider": "anthropic", "model": "claude-opus-4-5" },
      "reference_max_tokens": 4000,
      "max_tokens": 4096
    }
  }
}
```

`aggregator` 字段是**可选的**。省略时，MOA 直接把当前界面模型作为主输出模型
（不切换、不恢复）；只有想固定一个主模型（不随界面变化）时才需要设置它。

其余每个预设的可选字段：`reference_temperature`、
`reasoning_effort`（每个参考槽位）、`max_tokens`（v1 保留未启用——主模型的
token 预算由 pi 管理）。

## 行为说明与限制（v0.3.2）

- **主模型跟随界面。** 默认情况下主输出模型就是当前界面模型（`ctx.model`），
  不切换、不恢复。只有配置了固定 `aggregator` 时，MOA 才会临时切换并在
  结束后恢复。
- **自动模式。** `/moa-auto` 切换一个持久的「每条消息都走 MOA」状态。它通过
  pi 的 `input` 事件，同时拦截 TUI（`source === "interactive"`）与 pi-web 等
  web/RPC 界面（`source === "rpc"`）的输入，在 agent 循环前把普通输入改写
  成 MOA 消息。斜杠命令与 `/moa` 内部 `sendUserMessage`
  （`source === "extension"`）不受影响，因此不会双重 fan-out。开启时状态栏
  显示 `MOA 自动：开`。
- **可滚动选择器。** 配置向导使用可滚动的 `SelectList`（最多显示 10 项 +
  `(n/总数)` 指示器）而非 `ctx.ui.select`，模型列表再长也不会撑爆窗口。
- **对话总结（多轮）。** 会话已有历史时，`/moa` 会先让主模型总结
  「我们在做什么」（100–200 字），再把总结提供给参考模型，而非只给用户
  当前一句话。总结失败则降级为仅用用户 prompt。
- **一次性语义**（`fanout: user_turn`）。参考模型每次 `/moa` 只跑一次，
  不会在工具循环中反复调用。
- **模型恢复。** 配置了固定 `aggregator` 时，`/moa` 前的模型会在
  `agent_settled` 时恢复；MOA 期间排队的后续步骤仍会在聚合器上跑完再恢复。
- **失败处理。** 单个参考模型失败会内联标注并继续；若全部失败，`/moa`
  会在运行主模型前中止。
- **无隐私过滤。** 参考输出原样注入主模型（未实现 Hermes 的
  `privacy_filter`）。
- **无界面/print 模式。** 无法运行向导；请先在交互模式跑一次 `/moa`，或
  手动编辑 `~/.pi/agent/moa.json`。
- **prompt-cache 交互**（U8）与并发写 `moa.json` 时的**文件锁**在 v1 中
  未处理。