vscode-moa

🌐 Languages / 语言: English | 中文（当前 / Current）

面向 VSCode Copilot Chat 的混合专家智能体（MoA） —— 通过原生 vscode.lm API 编排精简的 5 角色流水线（Planner → Recon → Refs → Aggregator → Actor），让多个 LLM 异构协作。

English: Mixture-of-Agents for VSCode Copilot Chat — orchestrates 5-role pipeline through native vscode.lm API. See README.en.md.

⚠️ 默认 Autopilot 模式（v0.21.3+） —— 新安装默认 moa.executionPreset="autopilot" + moa.enableActorInLoop=true。任务收敛后，Actor 角色自动执行 action_items（写文件 / 跑终端命令），由 SafeExecutor 做 .bak.<timestamp> 备份。审计日志：.moa_cache/<task_id>/manifest.json。关闭方式：设 moa.executionPreset="manual"（finalize 仅返回 markdown）或 "supervised"（每轮 Gate-A QuickPick 审批）。

English (summary): v0.21.3+ defaults to autopilot + Actor-in-loop. After convergence, Actor auto-executes action_items with SafeExecutor backup. Opt out via manual or supervised.

它能做什么 / What it does

@moa <your question> 在 Copilot Chat 中运行多模型扇出。三种入口：

流水线总览 / Pipeline overview

每轮迭代按顺序运行 5 个角色。Aggregator 输出 finalize（完整度 ≥ 0.8）或达到 MAX_ITER=12 时收敛。

flowchart TD
    U([👤 User prompt]) --> P
    P["📋 Planner (iter 1 only)<br/>Decompose task + emit hints"]
    P -- "📦 sub_questions + recon_hints" --> RT{recon_required?}

    RT -- yes --> R0["🔀 Recon fan-out (parallel)"]
    R0 --> RA1["🔍 Recon [#1](https://github.com/DDL095/vscode-moa/issues/1)<br/>DeepSeek-V4-Flash"]
    R0 --> RA2["🔍 Recon [#2](https://github.com/DDL095/vscode-moa/issues/2)<br/>MiniMax-M3"]
    RA1 -- "📦 evidence_chunks_1" --> RAGG
    RA2 -- "📦 evidence_chunks_2" --> RAGG
    RAGG["🔀 Recon Aggregator<br/>GLM-5.2 · Merge + dedupe"]

    RAGG == "📦 universal_aggregated_evidence" ==> REF1
    RAGG == "📦 universal_aggregated_evidence" ==> REF2
    RAGG == "📦 universal_aggregated_evidence" ==> REF3
    REF1["💡 Ref advisor_1<br/>DeepSeek-V4-Flash<br/>→ ref_1.json (unique)"]
    REF2["💡 Ref advisor_2<br/>MiniMax-M3<br/>→ ref_2.json (unique)"]
    REF3["💡 Ref advisor_N<br/>GLM-5.2<br/>→ ref_N.json (unique)"]

    REF1 -- "📄 ref_1.json" --> A
    REF2 -- "📄 ref_2.json" --> A
    REF3 -- "📄 ref_N.json" --> A
    A["🔀 Aggregator<br/>GLM-5.2 · 聚合信息并整合判断<br/>completeness + next_action"]

    A -- "next_action: actor_needed" --> AC
    AC["⚙️ Actor<br/>MiniMax-M3 · write_file / execute"]
    AC -. "📦 high-confidence artifacts" .-> RT

    A -. "next_action: recon_needed" .-> RT

    A -- "finalize OR completeness ≥ 0.8 OR iter ≥ 12" --> F([🏁 Finalize])

📦 = 文件/封装内容传递 · 📄 = JSON 文件 📖 详细数据流 + 每个角色的输入/输出 JSON 结构见 docs/ARCHITECTURE.md。

ℹ️ 渲染说明：GitHub、VSCode Marketplace、VSCode 1.58+ 自带 markdown preview 都原生支持 mermaid。

模型选用指南 / Model selection guide

MoA 是 vendor-agnostic 的 —— 代码中没有硬编码任何 model ID。每一层从 moa.* 配置读取。下面是每种角色适合什么类型的模型的推荐：

搭配 GCMP 扩展：仅官方 Copilot 时 MoA 可见模型只有 3-5 个；装上 GCMP 后扩展到 10-30+ 个（DeepSeek-V4-Pro/Flash、GLM-5.2、MiniMax-M3、Qwen3 等），是真正的异构 MoA。

安装 / Install

方式 A — Marketplace（推荐）：扩展面板搜 "MoA Bridge"，或命令行 code --install-extension dudali095.moa-bridge。

方式 B — GitHub Release：releases 页面下载 .vsix，code --install-extension moa-bridge-X.Y.Z.vsix。

方式 C — 源码构建：

git clone https://github.com/DDL095/vscode-moa.git
cd vscode-moa && npm install
npm run package && code --extensionDevelopmentPath .

首次配置 / First-run config

最简方式 —— 命令面板运行 Moa: Configure Models：8 步引导式流程，除 refs（Step 1）和 recon（Step 3）外每步都提供 "Use aggregator" / "Disable" 哨兵选项作为推荐默认。

手动编辑 settings.json —— 以下是作者本人的工作配置（日常代码 + 深度研究兼顾）：

{
  "moa.activePreset": "default",
  "moa.presets": {
    "default": {
      "name": "Daily coding + research",
      // 4 个 ref advisor —— 来自不同实验室，异构视角
      "refModels": [
        { "role": "advisor_1", "model": "DeepSeek-V4-Flash" },
        { "role": "advisor_2", "model": "MiniMax-M3" },
        { "role": "advisor_3", "model": "GLM-5.2" },
        { "role": "advisor_4", "model": "Qwen3" }
      ],
      "aggregator":     { "model": "GLM-5.2" },        // 逻辑强，决定收敛
      "reconModels": [                                 // 便宜+快，工具偏好不同
        { "model": "DeepSeek-V4-Flash" },
        { "model": "MiniMax-M3" }
      ],
      "reconAggregator": { "model": "GLM-5.2" },       // 默认 = aggregator
      "planner":         { "model": "GLM-5.2" },       // 默认 = aggregator
      "actor":           { "model": "MiniMax-M3" },    // 依从度高
      "l3Summarizer":    { "model": "MiniMax-M3" }     // 大文件压缩
    }
  }
}

model 字段作为子串匹配 LanguageModelChat.id（如 "GLM-5.2" 匹配 gcmp.zhipu:::GLM-5.2-CodingPlan）。配置持久化到 User + Workspace 两级，跨窗口无需手动同步。

💡 Preset 切换：保存多个 preset（如 code / research / quick），通过 Moa: Switch Preset 一键切换。

用法 / Usage

作为 chat 参与者（最简单）：

@moa refactor src/moaRunner.ts to extract the sufficiency loop into its own module
@moa 多视角分析这个 PR 的设计权衡
@moa review the auth flow in src/services/auth/

作为 VSCode LM 工具（可组合，从其他 agent 调用）：

流水线可视化 / Pipeline visibility

5 个独立 OutputChannel（View → Output 下拉）：MoA Planner / MoA Recon / MoA Refs / MoA Aggregator / MoA Actor。每个 channel 含迭代边界 header（═══════ iter N ═══════），方便多迭代时滚动查看。

Actor 执行控制 / Actor execution (v0.20.0+)

Actor 会真正执行 Aggregator 给出的 action_items（写文件 / 跑命令 / 副作用）。4+1 个 executionPreset 模式：

每个副作用操作记到 .moa_cache/<task_id>/manifest.json；safeExecutionMode: true 时备份到 <target>.bak.<timestamp>。回滚 = 删新文件 + 把 .bak.<ts> 改回原名。

v0.22：角色注入系统大改造 + 用户主权

主题（用户原话）："VSCode 内长出来的个人 MOA 檞寄生" —— 让用户对 LLM 角色身份有完全主权，同时升级 Planner 为可迭代智能路由。完整设计见 docs/roadmap/v0.22.0-role-injection-overhaul.md v3。

4 大改动

1. Planner mini-loop + role_setup 设计师

Planner 从"单次调用"升级为"可迭代 mini-loop"（默认最多 5 次，绝对上限 20），自评 plan_coverage ≥ 0.9 收敛。iter 2+ 可调 read-only 工具（read_file/list_dir/grep_search/get_errors，每轮 ≤3 次）。plan_coverage < 0.5 时弹 vscode_askQuestions 询问用户。

Planner 新增身份：通过 role_setup 字段设计下游 3 角色（recon / recon_aggregator / actor）的 tone / perspective / tool_priority / cautions / focus。Refs 与 Aggregator 保留多模型可比性，不接受 role_setup（架构红线）。

2. 基础设施层注入（所有调工具的角色）

新建 systemContext.ts + instructionScanner.ts，给 Planner / Recon / Actor 统一注入 4 段动态上下文：

3. Recon Aggregator 始终运行 + 自迭代

v0.18 起 parallel 模式下运行；v0.22 起无论 single 还是 parallel 都运行（统一证据清洁度）。支持自迭代（默认 1 次，最大 10），maxIterations > 1 时启用启发式评分（aggregation + fidelity，零额外 LLM 成本）。

4. Role Setup Preset 用户主权系统

类似 moa 模型预设，新增 Role Setup Preset 系统。预设持久化到 ~/.moa/role-setup-presets.json（全局，跨任务/会话）。内置仅 1 个 default 预设（不可删除），用户基于 default 自行修改。

v0.22 命令（11 个）

Role Setup Preset CRUD + 分享：

• Moa: Create Role Preset / Switch Role Preset / Edit Role Preset / Delete Role Preset
• Moa: Export Role Preset / Import Role Preset（社区分享）

用户主权 + 报告：

• Moa: Toggle AI Generation（开/关 AI 自生成预设建议的采纳）
• Moa: Toggle Plan Mode Report / Moa: Show Last Plan Mode Report（借鉴 Copilot Plan Agent，但 MoA 为主干）
• Moa: Toggle final.md Inline Display（task complete 时把 final.md 关键内容内嵌主会话）

环境诊断：

• Moa: Diagnose Environment (v0.22)（12 项信息源可获取性检查）

v0.22 配置项（12 个新增）

完整说明详见 docs/CONFIGURATION.md。最关键 4 项：

其余 8 项：moa.plannerAllowTools / moa.reconAggregatorMaxIterations / moa.reconAggregatorScoreThreshold / moa.planModeReport.enabled / moa.finalMdInlineDisplay / moa.finalMdInlineThresholds / moa.roleSetup.activePreset / moa.roleSetup.aiGeneration。

升级路径（v0.21.x 用户）

• 不强制使用 role_setup（Planner 可选输出，缺失时下游用 v0.21.x 静态 prompt fallback）
• enablePlannerIteration=false 或 plannerMaxIterations=1 → 回退到 v0.21.x 单次 Planner 模式
• 首次启动自动创建 ~/.moa/role-setup-presets.json 含 default 预设

本地缓存 / Local cache

所有任务状态持久化到 <workspace>/.moa_cache/<task_id>/：

.moa_cache/<task_id>/
├── state.json              # 实时状态（每轮更新）
├── meta.json               # 元数据（模型 / 耗时 / 角色分布）
├── timeline.md             # 人类可读每轮表格
├── final.md / final.json   # Aggregator 综合 / 结构化 action_items
├── manifest.json           # SafeExecutor 审计日志（v0.19.1+）
├── autopilot.log           # v0.20.0+ 自动执行摘要
└── iteration_001/
    ├── planner.json
    ├── recon/advisor_1__<model>.json
    ├── recon_aggregator.json
    ├── refs/advisor_N__<model>.json
    ├── aggregator.json
    └── actor.json (if Actor ran)

生命周期：moa.cacheTtlDays（默认 30 天，0 = 永不自动清理）；moa.cacheRootDir 可设绝对路径跨工作区共享。

配置参考 / Configuration reference

📖 VSCode 设置 UI 描述在 v0.20.2+ 全部双语化（中文 + 英文）。完整配置项详见 docs/CONFIGURATION.md。本节只列最常用的。

调试 / Debugging

• Moa: Probe Available Tools —— 列出 vscode.lm.tools 中所有已注册工具。
• 5 个 OutputChannel（View → Output）—— 按角色查看每轮输出。
• 端到端审计：@moa 的完整 trace 在 .moa_cache/<task_id>/iteration_NNN/；autopilot.log 是人类可读摘要。
• 设 "moa.refDisplayMode": "verbose" 调试 aggregator 融合问题（⚠️ 上下文污染风险）。

与 GCMP 的关系 / Relationship with GCMP

MoA 是 vendor-agnostic 的，不 import、不配置、不依赖 GCMP。但 MoA 装了 GCMP 会更有用 —— 多模型扇出的全部意义就是异构视角，仅官方 Copilot 时多样性有限。

构建与发布 / Build & release

npm install
npm run compile      # 开发 bundle
npm run package      # 生产 bundle
npx vsce package     # 构建 .vsix

发布到 GitHub Releases，每个 release 附带对应 .vsix。

许可证 / License

MIT © DDL095