sdsrss/moa-skill/moa

MoA：多模型委员会

把多个异构大模型组成"委员会":委员互相隔离、各领角色独立盲审,当前 agent 作为仲裁人按硬规则收敛。原理基于 Mixture-of-Agents——不同模型盲点不同,独立盲审 + 结构化聚合能突破单模型上限。角色契约、收敛硬规则与简报模板见本目录 references/。

实现状态:v1.11.0。已可用:三通道(CH2 CLI:auggie/codex,检测到 auggie 优先 + CH3 API + CH1 子代理)、fallback 降级链、Quorum 宽限窗(可按席覆盖 grace_seconds)、degraded 标记、评审/决策/头脑风暴三场景、精炼轮(匿名互评三态契约 / 决策交叉审查 / 谄媚计数器 / 早停信号)、开会讨论(L3:顺序发言 + 发言序轮转 / 从众计数 / 假讨论检测 / 收尾盲投漂移检测)、主席综合/仲裁/策展、auto 路由 + 开会讨论 L3 选路门(三条硬门:L3 + 根本分歧 + 用户显式要求)、dry-run、按模式统计(含 token 用量)、错误分类、敏感材料外发前告警 + `leak-check` 密钥泄漏静态自查、成本实测(4.79×,见 README)、触发用例集 + auto 路由用例集(五场景×流水线)、.claude-plugin/plugin.json 分发清单。真实端到端验证覆盖:三通道(CH1 子代理 / CH2 codex+auggie(v1.4.0 auggie 双席实跑 2/2,含 auto 检测)/ CH3 API)、评审/决策/头脑风暴、开会讨论(2 轮 + 盲投)、Self-MoA、故障注入(重试/JSON修复/中止)、auto 顶配实跑(4 席三通道;第 4 席因测试 key 无 xAI 供给用了第二个 OpenAI 模型,非完全异构);顶配模型/代理 slug 核对见 assets/config.example.yaml。

v1.11.0 变更(model 预检;纯新增 + 一处报错文字):dry-run 现在会替你核 model slug——它拉 OpenRouter 在线模型列表(GET /api/v1/models,免费,不带 Authorization:该端点不需要 key,就不该把 key 送过去),把每条可比对的 api 链标成 OK / UNKNOWN(已下线或拼错)/ MISSING(没写 model)。README 从一开始就写着「模型 ID 迭代快,正式跑前用 dry-run 核对一次」,而此前 dry-run 对 slug 一个字都不校验——这句话现在才成真。无法诚实比对的链一律标 skip 而不是猜:cli / subagent 席本就不用 slug,自定义 base_url 与非 openrouter 协议有各自的模型名空间,拿 OpenRouter 的列表去判会全是假警报。哪些算 api 链按 `resolve_channel` 的口径判:主链看 member 自己的 channel,fallback 看它自己写的 channel(没写即 api),不是从 member 继承的那个——按继承值判正是 v1.7.0 A1 的错误(当年造成误拒,在这里会造成漏检:cli 席 + 省略 channel 的 fallback 实跑是 api 链,会把 auggie 侧的模型名发给 OpenRouter,恰恰是本功能要抓的那一类)。merge 视图只用来取该链真正会发出去的 model / protocol / base_url。fail-soft:离线 / 出口被拦 / 端点改版只多打一行、退出码不变——判定逻辑也在兜底里(config 字段类型不对不会掀掉 dry-run);取列表的 socket 超时 5s(被拒毫秒级,被黑洞才走满),但 DNS 解析不受它约束,解析器静默丢包时更久;--no-model-check 可关闭;dry_run() 函数本身默认关,发不发那次 GET 是 CLI 边界的决定(否则测试会真连网,违反「测试全离线」不变量)。另修一处报错文字:api 链没写 model 时 call_model 的 cfg["model"] 裸下标抛 KeyError,用户拿到的字面是 'model' [unknown]——既不说明问题也不说明怎么修,unknown 还污染错误分类表;现与 cli 分支「二进制不在 PATH」对称,报 err_class=startup 并给出 hint。不新增拒绝:validate_config 仍放行不写 model 的 api 席(加该门会撞掉 22 条用例/其中 4 条契约用例,且单模型网关省略 model 是合理写法,见 tasks/specs/model-preflight.md),该链仍照旧 continue 到下一条 fallback。tests 372→427。

v1.10.0 变更(options 默认层 + --models 具名报错 + 一次性 [options] 信号;关闭 v1.8.0 记的两条 Known issue):validate_config 的两个校验器都写着「未设(None)= 用默认,合法」,四个 accept 用例也把「options 键可选」钉成契约——但消费侧从来没有默认源,而且两半键的崩法与代价并不相同:timeout_seconds / max_tokens_member 走裸下标,键缺失时在首次派发处 KeyError(响亮、即时、一次请求都没发出),键写了留空则更安静——下标取到 None,一路进 socket timeout、max_tokens 载荷与截断重试算术;grace_seconds / min_successful_members 走 .get(k, 字面量),只在键缺失时回落,写了留空是显式 None、直接漏过去,其中 min_successful_members: 崩在 cmd_generate 的 min(None, …)、在派发之前、不花钱,而 grace_seconds: 是最贵的一条:它喂的 deadline 只在「已达法定数且仍有落伍席」时才计算,所以同一份 config 可能今天跑通、慢一天才崩在 now + None——此时已有数席应答并计费、产物已落了一部分盘。现收口到单一默认源 DEFAULT_OPTIONS + _opt()(六个调用点),键缺失与键留空一视同仁;判据用 is None 而非 or——这不是回归修复(旧写法对显式 0 也是放行的),是防止以后顺手写错:grace_seconds: 0(不等落伍席)与 min_successful_members: 0(不设下限)都是校验器明确放行的合法值。默认值取自 config.example.yaml 出厂值,只有 `grace_seconds` 例外:脚本 fallback 仍是 30、不是示例里的 90(v1.6.0 起的既有约定),现有一条读出厂示例的漂移门钉住两侧,任何一边被「对齐」都会红。新增一次性信号:用到默认值时 main() 在校验之后、派发之前往 stderr 打一行 [options],点名哪几个键被代入了什么值、各自管的是计费上限还是挂钟、怎么固定住,以及「v1.9.0 及以前这种配置会崩、不会发起调用」——四个键写齐的 config 永远看不到这行。另:--models 配上顶层不是映射的 config(如空 YAML)会在 apply_custom_committee 的 dict(cfg) 上裸 TypeError——它在 main() 里跑在 validate_config 之前,绕开了那句早就写好的具名报错;现原样交还、由校验层出具同一句(用例断言两条路径给的是同一句)。tests 355→372。

v1.9.0 变更(ISSUE-012 逐席 usage 累加器;主要是新增 stats 字段,另有两处既有读数收紧):补上 v1.7.0 曾加又撤回的「白花的计费」。当年撤回是因为它两个方向同时错——最大的单个消耗点(推理模型截断重试,max_tokens 3000→6000→12000 合计 21300 token)在 call_model 的重试循环里就把 usage 丢了、报 0;而 provider 省略 usage 时全零 dict 却为真,把没花钱的席计成花了。根因不是那两个字段,是 usage 靠局部变量沿正常返回路径传递,于是每条异常路径都是丢弃点,逐点补丁修不完。现改为逐席账本:每收到一个计费响应当场记账,栈怎么展开都不影响已记的数。stats.json 与 stats.r<N>.json 的 token_usage 新增 wasted_tokens/wasted_members(不并入 total_tokens,后者仍是"换回了意见的成本";逐席算差、逐席夹 0),逐席产物新增 usage_total。仍按下界报:被宽限窗弃置的席还在后台继续计费,账只记到被弃那一刻。另:billed_members 与 discuss_stats.json 的 billed_calls 判据都从 dict 真值收紧为"实际计费的 token 数为正"(本版改动的两处既有读数,方向一致);捎带修 4 处 except 内 raise 未接 from。tests 305→355。

v1.8.0 变更(七轮实跑自测循环,11 个缺陷;含三处新增的硬拒绝):两处读数错误——① 宽限窗竞态把【已跑完】的落伍席结果当成"主动放弃"丢掉:真 401 被洗成 skipped_grace,使 SKILL.md 教的「真故障席 = members_failed − members_skipped」算成 0,且丢掉已计费 usage;成功席变体更糟,丢的是唯一投 fail 带 blocker 的意见,stats 报出全票通过的假共识。② stats 的 --mode 与产物不符时静默给出全零共识读数(--mode 默认 review,产物不记 mode),而 synthesis.md 要求你照抄 stats 的数字——错读数直达报告;现按产物的 schema 键形反推 mode 并拒绝错配(判据保守:全部成功席须一致指向同一 mode,歧义则沉默)。其余:dry-run 在「主通道 codex 席按示例注释写成 model: null」上崩、单席畸形 verdict 打崩整个精炼轮聚合、落伍席的 worker 抛异常被记成"主动放弃"而非故障(与上面①同一种把故障洗成非故障)、非字符串 seat:/role:(如 seat: 1)在角色解析处裸崩、[budget] 横幅承诺不存在的 fallback、以及坏 YAML 的 --config/不可写的 --collect-dir/手写 CH1 产物/非 UTF-8 文件一律改为具名报错(对齐 ISSUE-005)。另:--config 与 --input 口径一致,接受非常规文件(<(…) 进程替换、/dev/stdin)。三处新增硬拒绝:stats --mode 与产物不符 · --round 为 0 或负数 · member 的 seat: 写空【且未显式设 role:;discuss 三命令则一律要求非空 seat,它在那里兼任发言者身份与 blindvote 文件名】。当时已知未修:options: {} 过得了校验却在派发时 KeyError: 'timeout_seconds'(既存,v1.7.1 同样如此)——已由 v1.10.0 的 options 默认层修掉,见上。tests 231→305。

v1.7.1 变更(v1.7.0 自身修复引入的三处回归,同日补丁;config.yaml 里有 cli 席的建议升级):① fallback 省略 `channel:` 的 cli 席不再被误拒启动——省略即 api(resolve_channel 就是这么分发的),而 v1.7.0 的新门按 {**member, **fb} 判、把 member 的 channel 继承了进来,报错还称它 channel=cli;② --retry-timeout 恢复整数——v1.7.0 起 cli 修复轮拿到的是浮点剩余预算,拼出 73.0,若 auggie 参数解析严格,出厂 A/C/D 三席的 JSON 自修复会静默失效;③ 有 CLI 调用在飞时不再快速退出——os._exit 会一并杀掉 subprocess.run 的超时看门狗,被弃的 auggie/codex 子进程变成无人收割的孤儿并持续计费,该情况退回 v1.7.0 之前的常规退出。tests 228→231。

v1.7.0 变更(降级韧性;含两处默认行为变更):① 修 api 席在"输出不可解析"上不降级的真 bug——cli 分支 raise→降级、api 分支 return→占席,配了 fallback 的 api 席等于没配(ISSUE-006);② `timeout_seconds` 语义改为「每条 fallback 链」的挂钟预算(含该链的重试与修复轮),单席最坏耗时从 链长 × (1+retries) × timeout(实测 3 链 240s = 36 分钟)收敛到 展开后链数 × timeout;被预算切断时 err_class=budget 并印一次性 stderr 说明(ISSUE-007);③ `channel: cli` 未写 `cli_kind` 又只有 `model` 的席改为拒绝启动——它会静默跑 auggie 默认模型、model_used 记 None,使 synthesis.md 的家族构成披露不可执行(出厂 config 全部显式写了 cli_kind,不受影响)(ISSUE-008);④ 弃席后进程快速退出,不再等 atexit join 落伍线程(实测 0.55s 返回 / 6.1s 才退出)(ISSUE-009);⑤ stats 新增 members_skipped(主动放弃≠故障)与 roster[].model_known(家族是否可知)。dry-run 明示其调用数为下界。失败席白花的计费仍未汇总:本轮曾加 wasted_*,预审评审证明它两个方向同时错(截断重试在 call_model 循环内就丢了 usage;provider 省略 usage 时全零 dict 却为真)而撤回,待后续版本用逐席累加器重做。tests 209→231。

v1.6.2 变更(自测循环健壮性加固,向后兼容):合法配置/正常委员输出行为不变。修 5 个问题——① parse_json 收紧为 dict-or-None,聚合层独立 isinstance(dict) 门:委员输出为非对象 JSON(数组/标量)不再崩 stats;② 嵌套字段类型守卫(issues/ideas/confidence 等写成字符串/异型不再崩聚合);③ 数值 config 选项(min_successful_members/timeout_seconds/max_tokens_member)补类型校验(对齐 v1.6.1 的 grace);④ discuss 强制 seat 唯一(seat 是讨论里的匿名发言者身份;重复 seat 会静默丢席/歧义。generate/refine 仍允许重复 seat);⑤ 缺 --input/--inject 文件给具名报错而非 traceback。tests 177→209。

v1.6.0 变更:Quorum 宽限窗支持按席覆盖——member 上可设 grace_seconds,给"高价值但慢"的重推理旗舰席(Fable 5 / Gemini Pro 类)单独放宽,避免它在精炼互评轮被全局小窗系统性牺牲(只丢那一票、不丢结论,但缺最强席的共识计量);未设则继承全局、行为不变。config 示例全局默认 grace_seconds 30→90;脚本 fallback 保持 30(向后兼容)。tests 169→170。

v1.5.0 变更:默认阵容改为真·四家族(D 席从第二个 Anthropic Self-MoA 子代理换为 Moonshot/kimi-k2.7 走 auggie,修审核 §7 的 B/D+仲裁人 3/5 同家族相关性;D 席 kimi 已实测 generate 落盘 64.7s OK)——默认计费席 2→3,回退法见 config.example.yaml 注释;新增 GitHub Actions CI(测试 + leak-check + 版本/徽章一致性,.github/workflows/ci.yml);修 v1.4.0 审核 P3(refine 全败止损 / early_stop 失败席抑制 / 多数派平票 / auto cli_kind 顶替 model 告警 / dry-run fallback 计费提示);补披露跨席注入传播、仲裁人同家族、置信度序数化。tests 162→169。

三种调用模式

• 顶配 `full`(手动默认) = /moa <材料>:固定 4 名顶配委员（默认四家族:OpenAI/Anthropic/Google/Moonshot）+ 当前 agent 仲裁。
• 智能 `auto`(关键词/自调默认):按 场景×难度×阶段 智能选人数/模型/流水线(M2)。
• 自定义 `custom` = --members N --models "id1,id2":指定人数与模型;重复同一模型 = 主动 Self-MoA。

第 0 步:判断是否该启动 + 选模式

• 简单问答、答案基本唯一 → 不启动,直接回答。
• 可机械验证的客观问题(算术/事实检索)→ 不启动,直接跑验证(MoA 对此类任务实测收益为负)。
• 高价值判断类(评审/决策/推荐/头脑风暴/二次确认)→ 启动。

手动 `/moa <材料>` → full(4 席顶配);关键词/自调触发 → auto:按 references/routing.md 三步(场景×难度×阶段)决定人数/模型/流水线,并把结论一句话公示给用户后再召集。

第 1 步:写自包含简报(最重要)

委员是无状态盲审者,只看到你写的简报——简报质量直接决定评审质量。按 references/briefing.md 写 moa-reports/<run>/brief.md,含:背景(3–8句)、待评对象本体(完整,不要只给摘要)、已知约束、明确的委员会问题、范围与工作量夹层(out_of_scope + 勘探预算)。简报不得引用"上文/刚才"等对话内指称;缺关键信息先问用户。

第 2 步:配置与预演

# 依赖: pip install pyyaml (HTTP 层纯标准库)。key 走环境变量,不落盘。
cp skills/moa/assets/config.example.yaml config.yaml   # 首次;按需改模型/通道
# CH2 auggie 席(默认委员会 A/C 席): 走 auggie 自身 OAuth(auggie login),不需 key;
#   模型 ID 用 auggie 侧命名(auggie models list),一个账号覆盖 GPT/Gemini/Claude/Kimi/GLM。
export OPENROUTER_API_KEY=...                            # api 席/fallback 用;或 OPENAI_API_KEY
 
# 预演: 看委员构成、通道、代理状态、成本量级,给用户过目。
# 它还会拉 OpenRouter 在线模型列表(免费、不需 key)逐条核 api 链的 slug:
#   OK / UNKNOWN(已下线或拼错)/ MISSING(没写 model)/ skip(cli·subagent·自定义 base_url·非 openrouter 协议)。
# 出现 UNKNOWN 或 MISSING 就先改 config 再正式跑 —— 正式跑时这些链会在【烧掉其余席位的钱之后】才暴露。
# 离线/出口被拦时该步自动跳过(只多一行说明;socket 超时 5s,DNS 挂住会更久);--no-model-check 可关闭。
python skills/moa/scripts/moa.py dry-run --input moa-reports/run/brief.md --refine-rounds 0
 
# custom 模式(无需改 config): --models 逗号分隔模型 ID,直接组临时委员会(全 CH3)
python skills/moa/scripts/moa.py dry-run --input moa-reports/run/brief.md \
  --models "openai/gpt-5.6-sol,anthropic/claude-opus-4.8,google/gemini-3.1-pro-preview"
# 主动 Self-MoA: 单模型复制成 N 席(座位自动分化角色)
python skills/moa/scripts/moa.py generate --input moa-reports/run/brief.md \
  --collect-dir moa-reports/run --members 3 --models "openai/gpt-5.6-sol"

第 3 步:生成 + 统计

python skills/moa/scripts/moa.py generate --mode review \
  --input moa-reports/run/brief.md --collect-dir moa-reports/run
python skills/moa/scripts/moa.py stats --mode review --collect-dir moa-reports/run

moa.py 只跑 channel: api(CH3)与 channel: cli(CH2:cli_kind: auggie/codex,省略 = auto 检测到 auggie 优先;auggie 计费 = 上游价 +40%,codex 走订阅)席位;纯 channel: subagent(CH1、无 api/cli fallback)席位它会跳过并提示。注意:若某 subagent 席挂了 api/cli fallback,moa.py 会判它可派发并实走那条 fallback(api=计费),而非留给你免费派发——订阅席不要挂 api fallback(dry-run 会对此打 ⚠)。

CH1 子代理席位由你(仲裁人)脚本外派发,与 moa.py 并行:

1. 先后台启动 moa.py generate(CH2/CH3 席位);弃置落伍席后进程会快速退出、不等后台线程收尾,但中止路径(顾问不足 abort)仍走常规退出,最多再等一个 member timeout_seconds;
2. 同时用 Task/Agent 工具派发 CH1 子代理(可指定非会话默认模型,如主模型是 Fable 5 时派 Opus 4.8 子代理),提示词 = 角色契约 + 简报,明令子代理不得调用工具/读写文件,仅基于简报作答,只输出 JSON;
3. 把子代理返回的 JSON 按 member_<name>.json 格式写入同一 --collect-dir;
4. 两边都落盘后,再跑 moa.py stats——统计块即覆盖全部席位(含 CH1)。

产物:moa-reports/run/member_<name>.json(逐委员结构化意见)、stats.json(机械统计,含 degraded 标记与每席实际 model/channel)。脚本可派发席(CH2/CH3)的成功数 < min(options.min_successful_members, 可派发席数)(默认 2)时中止——纯 subagent(CH1)席由你另行派发、不计入此门,合流后含 CH1 的整体法定数由你判定;全 CH1 配置时脚本无席可跑,干净退出不报错。达法定数后落伍席位有 grace_seconds(config 示例默认 90s,脚本 fallback 30s;可在 member 上按席覆盖——给重推理旗舰慢席单独放宽,不被全局窗牺牲)宽限窗,超时标 skipped_grace——它不计入上面那道止损门,但在 stats.json 里仍算在 members_failed 内,另有 members_skipped 单列其数,真故障席数 = `members_failed - members_skipped`。

timeout_seconds 是每条 fallback 链的挂钟预算(含该链自己的重试与 JSON 修复轮),不是每次 HTTP 尝试,故单席最坏耗时 = 展开后的链数 × 该值(未写 cli_kind 的 cli 席在 auggie/codex 二进制都在时会展开成两条,按展开后的尝试数算);超预算的链以 err_class=budget 让位给下一条。stats.json 的 token_usage 里,total_tokens/billed_members 仍只汇总换回了意见的花销(README 的成本倍数按这个口径读);白花的计费自 v1.9.0 起单列为 wasted_tokens/wasted_members,涵盖全败席的整笔、以及降级成功席在失败链上烧掉的部分,不并入 total_tokens。向用户报成本时请两个数都报,并按下界表述:真实支出 ≥ total_tokens + wasted_tokens。为何仍是下界:被 grace_seconds 弃置的落伍席仍在后台继续跑、继续计费,它的账只记到被弃那一刻为止。逐席产物另有 usage_total(该席全部计费,含重试与失败链)。roster 里 model_known: false 的席跑的是通道默认模型、家族不可知(收敛时按 references/synthesis.md 处理)。

mode 与场景:--mode review(评审/审查/二次确认/总结评审)、--mode decide(多选项决策,委员按 roles-decide.md 认领选项对抗论证)、--mode brainstorm(头脑风暴,发散人格,无精炼轮)。决策的认领角色由你在 config custom_roles 里按选项注入(见 references/roles-decide.md)。