@meilulin-1992/dsh-moa

Readme

# dsh-moa

Mixture of Agents（MoA）插件 for DeepSeek Harness：标记一条消息，多个参考模型并行分析，主模型综合总结。

![version](https://img.shields.io/badge/version-0.1.0-blue) ![tests](https://img.shields.io/badge/tests-31%2F31-green) ![license](https://img.shields.io/badge/license-MIT-lightgrey)

## 简介

`/moa` 启用后，下一条消息会先被一组**参考模型**并行分析（每个模型从自己的视角独立作答），再把这些参考结果组装成引导材料注入给主模型，由主模型做综合总结。适合需要多视角交叉验证的问题：架构评审、方案对比、风险分析等。

## 特性

- `/moa` 斜杠命令：默认预设、指定预设、直接提问、列表、取消
- **预设（preset）**：一组参考模型的命名组合，可配置多个
- 参考模型**并行**运行（`concurrency` 控制），单参考超时/失败自动降级（degrade），不阻塞主流程
- 引导消息以 `plugin` 来源注入，携带结构化 section 元数据
- **不写自定义会话事件**：MoA 回合由注入引导消息的 `source.sections` 识别，会话日志只含标准事件类型，任何 harness 版本都能正常加载（历史教训：自定义事件类型会让持久化读取端拒绝整份日志）
- 客户端卡片渲染：参考结果以可折叠卡片展示在引导消息下方（conversationEvents 定义 + 宿主通用渲染，无框架依赖）
- 配置热重载（`applies: live`）

## 安装

已发布到 npm（`@meilulin-1992/dsh-moa`）。推荐使用 dsh 的插件一键安装命令（等价于在 profile 目录执行 `pnpm add`）：

```bash
dsh plugin --profile web add @meilulin-1992/dsh-moa
```

或手动在 profile 目录安装（两者等价）：

```bash
cd ~/.dsh/profiles/web
pnpm add @meilulin-1992/dsh-moa
```

前置依赖（peer）由 pnpm 自动解析：`@deepseek-ai/cordis`、`@deepseek-ai/dsh-agent`、`@deepseek-ai/dsh-commands`、`@deepseek-ai/dsh-llm`、`@deepseek-ai/dsh-session`、`@deepseek-ai/dsh-settings`、`@deepseek-ai/schemastery`（客户端还需 `dsh-client-runtime` / `dsh-client-connection`）。

插件包内自带 `cordis.patch.yml`（经 `dsh.bundle.patch` 声明），会自动插入名为 `moa` 的插件 entry，无需手改 patch 配置。安装后重启 dsh web 即生效。

### 本地开发（link 方式）

```bash
git clone https://github.com/meilulin/dsh-moa.git
cd dsh-moa
pnpm install
pnpm build   # 必须：客户端 bundle（lib/client.js）由 tsdown 构建
```

然后在 `~/.dsh/profiles/web/package.json` 的 dependencies 中加入：

```json
"@meilulin-1992/dsh-moa": "link:/绝对路径/dsh-moa"
```

再在 profile 目录执行 `pnpm install`，重启 dsh web 生效。

## 使用

| 输入 | 行为 |
|---|---|
| `/moa` | 启用 MoA（默认预设），**下一条消息**生效 |
| `/moa deep` | 指定预设 `deep`，下一条消息生效 |
| `/moa 你的问题` | 默认预设 + **直接把问题作为下一条消息提交** |
| `/moa deep 你的问题` | 指定预设 + 直接提交问题 |
| `/moa list` | 列出可用预设 |
| `/moa off` | 取消待生效的 MoA，恢复正常模式 |

直接提问形式会把问题作为唯一用户消息入队并唤醒回合；参考模型在该回合第一步并行运行，随后主模型基于参考结果综合作答。

## 配置

配置位于 settings.yaml 的 `dsh-moa` 命名空间（热重载）：

```yaml
dsh-moa:
  defaultPreset: quick        # 默认预设名；未指定时回退到第一个预设
  concurrency: 3              # 参考模型并行数（1–16）
  referenceTimeoutMs: 60000   # 单个参考模型超时（1000–600000ms）
  presets:
    - name: quick             # 2 个参考
      references:
        - label: 主模型视角
          provider: deepseek-official
          model: deepseek-v4-flash
          temperature: 0.7    # 可选，默认 0.7
          maxChars: 4000      # 可选，参考文本截断上限（≥100），默认 4000
        - label: 独立视角
          provider: agnes-ai
          model: agnes-2.5-flash
    - name: deep              # 3 个参考
      references:
        - label: 严谨分析
          provider: deepseek-official
          model: deepseek-v4-pro
        - label: 综合视角
          provider: deepseek-official
          model: deepseek-v4-flash
        - label: 独立视角
          provider: agnes-ai
          model: agnes-2.5-pro
```

每个预设必须至少配置一个参考模型，否则启动时报错。

## 会话与持久化

插件**不写入任何自定义会话事件**（v1.1 起，`moa/mark` / `moa/reference` 已废弃）。原因：DSH 持久化读取端对未知事件类型采取「宁可拒绝整份日志」的策略——插件事件若未带 `ignorable` 标记（当前 `Session.append` API 也无法写入该标记），会话重启后就会以 `SessionFormatUnsupportedError` 拒绝加载。

MoA 的全部产出都走标准通道：

- 参考模型并行分析 → 组装为引导文本
- 引导文本以**标准 `user/message`** 注入（`source: { kind: 'plugin', plugin: 'dsh-moa', form: 'snapshot', sections: [{ name: 'moa', text }] }`）
- 客户端 `moaDefinition` 匹配该消息的 `source.plugin === 'dsh-moa'` 识别 MoA 回合，渲染 view node 锚定在引导消息下方

## 开发

```bash
pnpm test          # vitest：命令解析、参考运行、配置校验、类型、定义匹配
pnpm typecheck     # tsc --noEmit
pnpm build         # tsdown：lib/index.js（Node 半区，ESM）+ lib/client.js（浏览器半区，CJS）
```

源码结构：

```
src/
├── index.ts       # 宿主入口：settings 注册、/moa 命令、agent/pre-step 拦截
├── command.ts     # /moa 命令解析与处理
├── config.ts      # schemastery 配置 schema + 预设解析
├── mark.ts        # MoA 标记存储（一回合绑定）
├── references.ts  # 参考模型并行运行 + 降级 + 引导组装
├── types.ts       # 共享类型（插件名 + 参考运行元数据）
└── client.ts      # 客户端入口：conversationEvents 定义注册 + 设置面板
    └── client/    # definition.ts（从注入消息识别 MoA 回合）、settings.tsx（配置面板）
```

> ⚠️ 客户端 bundle 必须保持 `window.__ModuleLoader__.load({ id, factory })` 的 CJS 包装（`tsdown.config.ts` 中已配置 banner/footer）——dsh client-modules 的惰性 CJS 模型要求 bundle 执行时注册 factory，裸 ESM 导出会导致 `loaded without registering ... via __ModuleLoader__.load` 启动失败。

## License

MIT