hermeslike-moa

Readme

<div align="center">

**中文** · [English](README.en.md)

# hermeslike-MoA

**Hermes 风格的 Mixture-of-Agents(MoA)请求聚合器——为 DSH 的 LLM 调用注入「路由器 → 多路参考顾问 → 聚合器流式输出」流水线,并带双通道故障切换与 V4P 三重闸门费用防护。**

</div>

---

`hermeslike-moa` 是一个 DSH 插件(`dsh.bundle`)。它注册一个 dsh-llm `LlmAdapter`(provider 路由 `deepseek-moa`,配置了 OpenCode Go key 时追加 `go-moa`),所有路由到这些 provider 的模型请求都会经过 MoA 流水线:

```
用户请求
  → V4F 路由器(单次调用 JSON 判定:任务是否值得 V4P 介入)
  → 参考顾问 ×N 并行(V4F;Hermes 风格顾问角色 system prompt;工具调用/结果折叠为纯文本;
     工具结果 head+tail 裁剪;参考输出脱敏;末尾追加合成 user 判断指令)
  → 聚合器(模型选择:用户显式选择优先 → 路由器辅助 → V4P 三重闸门兜底)
  → 流式透传(标准 dsh-llm StreamChunk)
```

## 三个模型选项

模型选择器里本插件提供三个模型:

| 模型 | 含义 |
|---|---|
| **`deepseek-v4-mix`**(MoA Mix · 模型混合) | **完整 MoA 流水线**:路由器 → 参考顾问 ×N(flash,并行)→ 聚合器(pro 或 flash)→ 流式。消耗 1 路由 + N 参考 + 1 聚合共 N+2 次调用;聚合 pro 受 V4P 闸门约束 |
| **`deepseek-v4-pro`** | **直连单一 V4 Pro**(不走 MoA,无路由/参考/聚合开销);**仍受 V4P 闸门约束**(防呆:预算不足时按设置降级 flash 或报错) |
| **`deepseek-v4-flash`** | **直连单一 V4 Flash**(不走 MoA,最便宜最快;**不受闸门约束**) |

> 任何**未知模型 id**(不在上述三个之内)按 **flash 直连**处理,绝不静默触发昂贵的 MoA 路径。

## 核心特性

- **`mix` 模型大类**:模型选择器里新增 **`MoA Mix · 模型混合`**(`deepseek-v4-mix`)——选中它即强制走完整 MoA 流水线(模拟选择入口),聚合模型仍按设置/路由器决定;`flash`/`pro` 保留为显式聚合模型。
- **Hermes 忠实参考语义**:`lib/reference.js` 复刻 Hermes `moa_loop.py` 的顾问视图——丢弃主 system prompt、把 `tool_calls` 渲染为 `[called tool: name(args)]`、把工具结果 head+tail 裁剪(4000 字符预算)折叠进前一条 assistant 消息、**不发出任何 tool-role 消息**(兼容严格 provider)、末尾追加合成 user 判断指令保证 user 结尾。
- **脱敏**:集中式密钥形状(sk-/Bearer/JWT/私钥/数据库连接串)+ 安全的 email/电话正则(带边界条件,不误伤 SHA/ID/日期)。
- **上下文裁剪**:估算 token 预算,从最旧帧丢弃,保持 user-first 不变式,保留尾部合成指令。
- **双通道**:official(DeepSeek 官方按量)+ go(OpenCode Go 订阅额度);**Go 优先整套流水线,连续 3 次失败自动切官方整套**。
- **V4P 三重闸门**:预算倍数(前瞻预算池 = F 已花×ratio − P 已花)+ 窗口内次数上限 + 最小间隔。
- **新契约记账**:dsh-llm 分离式 `TokenUsage`(`inputTokens` 为未缓存输入,cache 读写单独计),滚动窗口成本核算。

## 安装

```bash
# bundle:进入 profile layer stack(重启 web 生效)
dsh plugin --profile web add github:beimianism/Hermeslike-Mixagent-MoA

# 或 本地开发路径(换成你的实际路径)
dsh plugin --profile web add /path/to/hermeslike-moa
```

> 公开 `@deepseek-ai/*` 与 `cordis` 依赖刻意不声明(由 profile 的 pnpm closure 注入)。

## 系统设置(推荐)

插件融合进 DSH **web 系统设置**——设置页(「设置 → Hermeslike MoA」)由插件自带 client 半渲染(官方 Models 页不渲染第三方 provider,其编辑卡被禁用),实时生效、无需重启。**每个字段旁有 ⓘ 悬停提示**,key 字段下方显示实时健康诊断(`keyHealth`):

- 开关:启用/停用 MoA 聚合
- **API key(直接填写,鲁棒优先)**:表单里 `DeepSeek API key` 与 `OpenCode Go API key` 两个**只写密码框**——直接在设置界面填写即生效(值存本地 `settings.yaml`,不回显,wire 上剥离);留空则回退下方的环境变量引用(`apiKeyEnv`/`goApiKeyEnv`,经 credentials/环境解析)。两者都为空时:官方 key 缺失 → 请求 401;Go key 缺失 → 仅禁用 Go 通道。key 健康状态实时显示"✓ 有效 / ✗ 格式异常原因"。
- **模型混合**:
  - `参考顾问数量`(1–8,默认 3)
  - `参考温度`(按顺序对应各参考)
  - `聚合模型`:auto(路由器判定)/ flash / pro(受 V4P 闸门约束)——对应 Hermes 的 aggregator slot
  - **`参考顾问思考强度`(flash)** 与 **`聚合模型思考强度`**:每槽独立(off / high / max / auto=跟随会话),透传上游 `reasoning_effort`
  - **`参考扇出节奏`**:`user_turn`(默认)=每用户轮只跑一次参考,agent 工具步骤复用轮首指导(Hermes 语义,省成本);`per_iteration`=每步重跑(参考见最新状态,贵)
  - **`显示 MoA 进度`**:在流式输出的思考区显示 "🔄 MoA: 参考 2/3 完成…" / "聚合中…"(可关闭)
  - `优先 Go 通道`:OpenCode Go 订阅额度优先,连续 3 次失败切官方
- **V4P 三重闸门**:预算倍数 / 窗口次数上限 / 最小间隔 / 闸门拦截时降级 Flash
- **隐私**:参考输出脱敏级别(display=聚合输入保持原文;full=进入聚合提示词前先脱敏,适合简单/低频场景)

设置文档存放在 settings 文档的 `hermeslike-moa:` 分节;`cordis.patch.yml` 的插件行 `config:` 作为组合 base 层(用户设置优先)。

## 配置(组合 base 层)

以下字段在 `cordis.patch.yml` 插件行 `config:` 中作为默认值;用户设置覆盖它们:

| 配置 | 默认 | 说明 |
|---|---|---|
| `apiKeyEnv` / `DEEPSEEK_API_KEY` | `DEEPSEEK_API_KEY` | DeepSeek 官方 key 的环境变量引用 |
| `goApiKeyEnv` / `OPENCODE_GO_API_KEY` | `OPENCODE_GO_API_KEY` | OpenCode Go key 引用(留空禁用 Go 通道) |
| `endpoint` | `https://api.deepseek.com/chat/completions` | 官方端点 |
| `goEndpoint` | `https://opencode.ai/zen/go/v1/chat/completions` | Go 端点(pi-ai catalog 的 opencode-go 真实地址) |
| `enabled` | `true` | 总开关 |
| `ratio` | `0.5` | V4P 前瞻预算池比例(F×ratio−P) |
| `windowMs` | `3600000` | 记账滚动窗口 |
| `refCount` | `3` | 参考顾问数量 |
| `refTemps` | `[0.5,0.8,1.1]` | 各参考温度 |
| `aggregatorModel` | `auto` | 聚合模型(auto/flash/pro) |
| `referenceReasoningEffort` | `auto` | 参考顾问思考强度(off/high/max/auto) |
| `aggregatorReasoningEffort` | `auto` | 聚合模型思考强度(off/high/max/auto) |
| `fanout` | `user_turn` | 参考扇出节奏(user_turn/per_iteration) |
| `showProgress` | `true` | 思考区显示 MoA 进度 |
| `preferGo` | `true` | 优先 Go 通道 |
| `fallbackToFlash` | `true` | 闸门拦截 V4P 时降级 V4F |
| `minBudgetMultiple` | `3` | 闸门:预算倍数 |
| `maxProPerWindow` | `3` | 闸门:窗口内 V4P 次数上限 |
| `minProIntervalMs` | `900000` | 闸门:最小间隔 |
| `privacyFilter` | `display` | 参考输出脱敏(display/full) |

示例:

```yaml
- insert:
    - id: hermeslike-moa
      name: 'hermeslike-moa'
      config:
        apiKeyEnv: DEEPSEEK_API_KEY
        goApiKeyEnv: OPENCODE_API_KEY
        ratio: 0.5
        refCount: 3
```

## 布局

```
hermeslike-moa/
├── package.json          # 清单(name, exports["./client"], dsh.bundle.patch, dsh.client)
├── cordis.patch.yml      # bundle 行 insert
├── index.js              # apply():配置解析 + registerAdapter + /hermeslike 设置 RPC
├── client/index.js       # web client 半:设置页(settings.section,含 ⓘ 悬停提示)
├── lib/
│   ├── adapter.js        # MoaAdapter extends LlmAdapter(双通道 + 故障切换)
│   ├── pipeline.js       # MoaPipeline:路由 → 参考×N → 聚合 → 流式
│   ├── router.js         # V4F 路由器 + 关键词兜底
│   ├── reference.js      # Hermes 顾问视图:渲染/裁剪/脱敏/合成指令
│   ├── wire.js           # HTTP 单发/流式 + TokenUsage 归一化 + 错误分类
│   ├── ledger.js         # 花费账本 + V4P 三重闸门
│   ├── prices.js         # 单价表
│   ├── prompts.js        # 路由/参考/聚合 三个 system prompt
│   └── settings.js       # 设置 schema + 配置解析
├── scripts/smoke.mjs     # 冒烟回归(mock 服务器,8 组断言)
└── docs/                 # 学习笔记与差异分析
```

## 许可证

[MIT](./LICENSE)