agency-orchestrator 0.6.17 → 0.7.0

package/README.en.md

@@ -9,7 +9,7 @@
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
 
-**One sentence → full plan · 211 expert AI roles · Zero-code YAML · 10 LLM providers · 7 need no API key**
+**One sentence → full plan · 211 expert AI roles · Zero-code YAML · 10 LLM providers · key supported (DeepSeek recommended), plus 7 key-free options**
 
 > **Note:** `ao compose --run` auto-detects your language. Both 211 Chinese roles and 170+ English roles ([agency-agents](https://github.com/msitarzewski/agency-agents), MIT) are **bundled in the npm package — no extra download needed**. **6 English workflow templates** are ready in `workflows/en/` — more coming in v0.6.
 
@@ -23,6 +23,24 @@
 
 ---
 
+## Web Studio (GUI)
+
+Prefer not to use the command line? Run `ao web` locally and pick experts, run workflows, view outputs, and intervene live — all in a GUI, fully bilingual (EN/中文).
+
+<p align="center">
+  <img src="./docs/screenshots/studio-roles-en.png" alt="Studio · Build a Team: pick from 200+ experts, AI composes the team" width="800"><br/>
+  <em>Build a Team: pick from 200+ experts; AI composes and runs the team</em>
+</p>
+
+<p align="center">
+  <img src="./docs/screenshots/studio-workflows-en.png" alt="Studio · Workflows: run built-in templates with one click" width="800"><br/>
+  <em>Workflows: run built-in templates with one click, or compare several</em>
+</p>
+
+> Launch: `ao web` (local — your API key stays on your machine, never uploaded). A [desktop client](./desktop) (Electron) is also available.
+
+---
+
 ## One Sentence, Full Result
 
 ```bash
@@ -75,10 +93,10 @@ Chatting with one AI gives you one perspective. But any real decision needs prod
 |---|--------|-----------|---------------------|
 | Roles | 1 generalist | Write your own | **211 expert roles** |
 | Usage | Chat | Write Python | **One sentence / YAML** |
-| API key | — | Required | **7 providers need none** |
+| API key | — | Required | **Key supported; 7 key-free options too** |
 | Dependencies | — | pip + dozens of packages | **npm + 2 deps** |
 | Parallelism | — | Manual graph | **Auto DAG detection** |
-| Price | Subscription | Open-source + API fees | **Completely free** |
+| Price | Subscription | Open-source + API fees | **DeepSeek sweet spot is dirt cheap; key-free to start** |
 
 ## Get Started in 3 Steps
 
@@ -201,9 +219,11 @@ analyze ──→ tech_review  ──→ summary
 | ChatGPT Plus ($20/mo) | `provider: "codex-cli"` | `npm i -g @openai/codex` | **$0 extra** |
 | OpenClaw account | `provider: "openclaw-cli"` | `npm i -g openclaw` | **$0 extra** |
 | Hermes Agent (NousResearch open-source 🔥) | `provider: "hermes-cli"` | [Install guide](https://github.com/NousResearch/hermes-agent) | **Free** |
-| A computer | `provider: "ollama"` | [ollama.ai](https://ollama.ai) | **Free** (local models) |
+| A computer | `provider: "ollama"` | [ollama.ai](https://ollama.ai) | **Free** (local models, see note below) |
+
+> ⚠️ **Model capability drives the value of multi-agent.** We verified this with a quality eval (see [EVAL_FINDINGS.md](EVAL_FINDINGS.md)): on the **DeepSeek tier (capable yet cheap), multi-agent output clearly beats a single prompt**; but with **weak local models (e.g. llama3 8B), the role hand-offs amplify drift and can do worse than a single call**. For quality, use a capable model (DeepSeek/Claude/Gemini); for local Ollama, prefer 70B+ models.
 
-**Or use traditional API keys:**
+**Or use traditional API keys (DeepSeek recommended for the price/quality sweet spot):**
 
 | Provider | Config | Env Variable |
 |----------|--------|-------------|

package/README.md

@@ -9,7 +9,7 @@
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
 
-**一句话出结果 · 211 个专业 AI 角色 · YAML 零代码 · 10 种大模型 · 7 种免 API key**
+**一句话出结果 · 211 个专业 AI 角色 · YAML 零代码 · 10 种大模型 · 支持 key（推荐 DeepSeek），也有 7 种免 key 方式**
 
 > 📖 [完整上手教程](https://mp.weixin.qq.com/s/XcGbkMb6TM6NLQiL7ICwbw) — 从安装到实战，10 分钟上手
 
@@ -21,6 +21,25 @@
 
 ---
 
+## 网页 Studio（图形界面）
+
+不想敲命令行？本地跑一条 `ao web`，浏览器里勾选专家、运行工作流、查看产物、实时介入——全程图形界面，全中英双语。
+
+<p align="center">
+  <img src="./docs/screenshots/studio-roles-zh.png" alt="Studio · 角色组队：从 200+ 专家里勾选，AI 自动合成团队" width="800"><br/>
+  <em>角色组队：从 200+ 专家里勾选，AI 自动合成团队并运行</em>
+</p>
+
+<p align="center">
+  <img src="./docs/screenshots/studio-workflows-zh.png" alt="Studio · 工作流模板：内置模板一键运行" width="800"><br/>
+  <em>工作流：内置模板一键运行，也能对比多个模板</em>
+</p>
+
+> 启动：`ao web`（本地，密钥只存你自己机器、绝不外传）。也有 [桌面客户端](./desktop)（Electron）。
+> 英文界面同样完整 → 见 [English README](./README.en.md)。
+
+---
+
 ## 一句话出结果
 
 ```bash
@@ -73,11 +92,11 @@ ao compose "设计一个 SaaS 产品的定价策略" --run                   #
 |---|--------|-----------|---------------------|
 | 角色数 | 1 个通用 | 自己写 | **211 个专业角色** |
 | 使用方式 | 对话 | 写 Python | **一句话 / YAML** |
-| API key | — | 必须 | **7 种免 API key** |
+| API key | — | 必须 | **支持 key，也有 7 种免 key 方式** |
 | 依赖 | — | pip + 几十个包 | **npm + 2 个依赖** |
 | 并行 | — | 手动建图 | **DAG 自动检测** |
 | 中文角色 | — | 无 | **211 个** |
-| 价格 | 订阅制 | 开源 + API 费 | **完全免费** |
+| 价格 | 订阅制 | 开源 + API 费 | **DeepSeek 甜区极低成本，亦可免 key 起步** |
 
 ## 3 步开始
 
@@ -200,9 +219,11 @@ analyze ──→ tech_review  ──→ summary
 | ChatGPT Plus/Pro（$20/月） | `provider: "codex-cli"` | `npm i -g @openai/codex` | **不花钱** |
 | OpenClaw 账号 | `provider: "openclaw-cli"` | `npm i -g openclaw` | **不花钱** |
 | Hermes Agent（🔥 NousResearch 热门开源） | `provider: "hermes-cli"` | [安装指南](https://github.com/NousResearch/hermes-agent) | **免费** |
-| 一台电脑 | `provider: "ollama"` | [ollama.ai](https://ollama.ai) | **免费**（本地模型） |
+| 一台电脑 | `provider: "ollama"` | [ollama.ai](https://ollama.ai) | **免费**（本地模型，见下方提示） |
+
+> ⚠️ **模型能力决定多智能体的价值**：我们用质量评测验证过（见 [EVAL_FINDINGS.md](EVAL_FINDINGS.md)）——**DeepSeek 这一档（够强又不贵）上，多智能体产出明显优于单次 prompt**；但**本地小模型（如 llama3 8B 级）能力不足时，多角色交接反而会放大漂移、产出不如单次**。追求质量请用 DeepSeek/Claude/Gemini 等有能力的模型；本地 Ollama 建议用 70B+ 模型。
 
-**也支持传统 API key：**
+**也支持传统 API key（追求质量推荐 DeepSeek，性价比甜区）：**
 
 | 提供商 | 配置 | 环境变量 |
 |--------|------|---------|
@@ -262,6 +283,7 @@ ao serve                             # 启动 MCP Server（供 Claude Code / Cur
 | `--output dir` | 输出目录（默认 `ao-output/`） |
 | `--resume <dir\|last>` | 从上次运行恢复（加载已完成步骤的输出） |
 | `--from <step-id>` | 配合 `--resume`，从指定步骤重新执行 |
+| `--feedback "意见"` | 对话式返工：把修改意见交给 `--from` 指定的专家，让它带着「上一版产出 + 你的意见」在原稿基础上修改（不指定 `--resume` 时默认对上一次运行返工） |
 | `--watch` | 实时终端进度显示 |
 | `--quiet` | 静默模式 |
 
@@ -305,6 +327,22 @@ ao run workflows/一人公司全员大会.yaml --resume last --from launch_decis
 | 只重跑失败的步骤 | `ao run workflow.yaml --resume last` |
 | 基于指定版本重跑 | `ao run workflow.yaml --resume ao-output/具体目录/ --from <步骤ID>` |
 
+### 对话式返工（Feedback）
+
+`--resume --from` 是「让某个专家重做」，但默认是**从零重写**。如果你只是想说一句「这里改一下」，用 `--feedback`——它把你的意见 + 这个专家**上一版的产出**一起交回去，让它在原稿基础上改，而不是推倒重来：
+
+```bash
+# 觉得故事结尾太平淡 —— 直接跟"写故事"那个专家说怎么改
+ao run workflows/story-creation.yaml --from write_story \
+  --feedback "结尾太平淡，加一个反转，并收束前面埋的伏笔"
+
+# 觉得营销方案不接地气
+ao run workflows/一人公司全员大会.yaml --from marketing_plan \
+  --feedback "预算改成 5000 以内，渠道聚焦小红书 + 私域"
+```
+
+不写 `--resume` 时默认对**上一次运行**返工（等价于 `--resume last`）。该专家改完后，它的下游步骤会自动用新产出重跑。
+
 ## 编程 API
 
 ```typescript
@@ -383,8 +421,8 @@ ao serve --verbose    # 带调试日志
 | `depends_on` | string[] | 否 | 依赖的步骤 ID |
 | `depends_on_mode` | string | 否 | `"all"`（默认）或 `"any_completed"`（任一完成即可） |
 | `condition` | string | 否 | 条件表达式，不满足则跳过（如 `"{{var}} contains 技术"`） |
-| `type` | string | 否 | `"approval"` 表示人工审批节点 |
-| `prompt` | string | 否 | 审批节点的提示文本 |
+| `type` | string | 否 | `"approval"` 人工审批节点 / `"human_input"` 人工输入节点（跑到该步暂停，读取你的输入作为该步产出注入下游） |
+| `prompt` | string | 否 | `approval` / `human_input` 节点的提示文本 |
 | `loop` | object | 否 | 循环配置 |
 | `loop.back_to` | string | 否 | 循环回到的步骤 ID |
 | `loop.max_iterations` | number | 否 | 最大循环次数（1-10） |
@@ -484,6 +522,7 @@ ao-output/产品需求评审-2026-03-22/
 | [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) ![](https://img.shields.io/github/stars/jnMetaCode/superpowers-zh?style=flat&label=⭐) | 🧠 工作方法论 | 20 个 skills 教 AI 怎么干活（TDD / 调试 / 代码审查等） |
 | [ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) | 📖 实战教程 | 66 个 Claude Code 技巧 + 9 款工具最佳实践 + 配置模板 |
 | [shellward](https://github.com/jnMetaCode/shellward) | 🛡️ 安全中间件 | 8 层防御 + DLP 数据流 + 注入检测，**零依赖**（含 MCP Server） |
+| 🆕 [ai-shortfilm-prompts](https://github.com/jnMetaCode/ai-shortfilm-prompts) | 🎬 视频提示词 | Mx-Shell《丧尸清道夫》5 段式方法论 + Skill，Seedance / 小云雀 / Sora / 可灵 / 即梦通用 |
 
 ### 交流
 

package/dist/agents/loader.d.ts

@@ -9,3 +9,27 @@ export declare function loadAgent(agentsDir: string, rolePath: string): AgentDef
  * 列出所有可用角色
  */
 export declare function listAgents(agentsDir: string): AgentDefinition[];
+/**
+ * 轻量列出所有角色路径（如 "engineering/engineering-sre"），不解析文件内容。
+ * 用于 validate 报错时给"你是不是想用 X"建议，避免 listAgents 全量解析的开销。
+ */
+export declare function listRolePaths(agentsDir: string): string[];
+/**
+ * 在给定的候选路径集合里，找出最接近 badPath 的若干个（纯函数，不读盘）。
+ * 优先子串包含（按 leaf 名匹配），再按编辑距离兜底；只返回足够接近的。
+ * 供 compose 复用——它要在"实际提供给 LLM 的目录"里建议，而非全盘所有角色。
+ */
+export declare function suggestFromPaths(badPath: string, allPaths: string[], limit?: number): string[];
+/**
+ * 给一个拼错的角色路径，返回最接近的若干真实角色（"你是不是想用…"）。
+ */
+export declare function suggestRoles(badPath: string, agentsDir: string, limit?: number): string[];
+/**
+ * 按关键词过滤角色：匹配 rolePath / name / description（不区分大小写）。
+ * 空关键词返回原列表。供 `ao roles <keyword>` 使用，方便手动找专家。
+ */
+export declare function filterAgentsByKeyword<T extends {
+    name?: string;
+    rolePath?: string;
+    description?: string;
+}>(agents: T[], keyword: string): T[];

package/dist/agents/loader.js

@@ -100,3 +100,89 @@ export function listAgents(agentsDir) {
     }
     return agents;
 }
+/**
+ * 轻量列出所有角色路径（如 "engineering/engineering-sre"），不解析文件内容。
+ * 用于 validate 报错时给"你是不是想用 X"建议，避免 listAgents 全量解析的开销。
+ */
+export function listRolePaths(agentsDir) {
+    const dir = resolve(agentsDir);
+    if (!existsSync(dir))
+        return [];
+    const paths = [];
+    for (const dept of readdirSync(dir, { withFileTypes: true })) {
+        if (!dept.isDirectory())
+            continue;
+        if (dept.name.startsWith('.') || dept.name === 'node_modules' || dept.name === 'scripts' ||
+            dept.name === 'integrations' || dept.name === 'examples')
+            continue;
+        for (const file of readdirSync(join(dir, dept.name), { withFileTypes: true })) {
+            if (!file.isFile() || !file.name.endsWith('.md'))
+                continue;
+            paths.push(`${dept.name}/${file.name.replace('.md', '')}`);
+        }
+    }
+    return paths;
+}
+/** Levenshtein 编辑距离（用于角色名模糊匹配） */
+function editDistance(a, b) {
+    const m = a.length, n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    let prev = Array.from({ length: n + 1 }, (_, i) => i);
+    let cur = new Array(n + 1);
+    for (let i = 1; i <= m; i++) {
+        cur[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + cost);
+        }
+        [prev, cur] = [cur, prev];
+    }
+    return prev[n];
+}
+/**
+ * 在给定的候选路径集合里，找出最接近 badPath 的若干个（纯函数，不读盘）。
+ * 优先子串包含（按 leaf 名匹配），再按编辑距离兜底；只返回足够接近的。
+ * 供 compose 复用——它要在"实际提供给 LLM 的目录"里建议，而非全盘所有角色。
+ */
+export function suggestFromPaths(badPath, allPaths, limit = 3) {
+    if (allPaths.length === 0)
+        return [];
+    const leaf = (badPath.split('/').pop() || badPath).toLowerCase();
+    const target = badPath.toLowerCase();
+    const scored = allPaths.map(p => {
+        const pl = p.toLowerCase();
+        const pleaf = (p.split('/').pop() || p).toLowerCase();
+        // 子串命中给大幅加分（排到前面）
+        const substr = pl.includes(leaf) || pleaf.includes(leaf) || leaf.includes(pleaf);
+        const dist = editDistance(target, pl);
+        return { p, dist, substr };
+    });
+    scored.sort((a, b) => (a.substr === b.substr ? 0 : a.substr ? -1 : 1) || a.dist - b.dist);
+    // 只保留"够接近"的：子串命中，或编辑距离不超过 leaf 长度的一半 + 4
+    const threshold = Math.ceil(leaf.length / 2) + 4;
+    return scored
+        .filter(s => s.substr || s.dist <= threshold)
+        .slice(0, limit)
+        .map(s => s.p);
+}
+/**
+ * 给一个拼错的角色路径，返回最接近的若干真实角色（"你是不是想用…"）。
+ */
+export function suggestRoles(badPath, agentsDir, limit = 3) {
+    return suggestFromPaths(badPath, listRolePaths(agentsDir), limit);
+}
+/**
+ * 按关键词过滤角色：匹配 rolePath / name / description（不区分大小写）。
+ * 空关键词返回原列表。供 `ao roles <keyword>` 使用，方便手动找专家。
+ */
+export function filterAgentsByKeyword(agents, keyword) {
+    const kw = keyword.trim().toLowerCase();
+    if (!kw)
+        return agents;
+    return agents.filter(a => (a.rolePath || '').toLowerCase().includes(kw) ||
+        (a.name || '').toLowerCase().includes(kw) ||
+        (a.description || '').toLowerCase().includes(kw));
+}

package/dist/cli/compose.d.ts

@@ -58,12 +58,29 @@ export declare function composeWorkflow(options: {
     lang?: 'zh' | 'en';
     /** 生成的 YAML 中写入的单步超时（ms）；未指定时 API=300s / ollama=600s */
     timeoutMs?: number;
+    /** 锁定阵容：只用这些角色路径（如 "engineering/xxx"），LLM 仅在其间编排 DAG/task/变量 */
+    pinnedRoles?: string[];
+    /** 保存目录；默认 workflows/。用于把合成结果写到用户目录而非随包模板目录 */
+    saveDir?: string;
 }): Promise<{
     yaml: string;
     savedPath: string;
     relativePath: string;
     warnings: string[];
 }>;
+/**
+ * 确定性修复幻觉角色：对每个不存在的 role，从角色库找到"够接近"的真实路径，直接在 YAML 文本里替换。
+ * 不依赖再调一次 LLM——只要有可信匹配，就保证替换为库里真实存在、可运行的角色。
+ * 仅替换 role 值中的精确路径（双/单引号包裹），避免误伤任务描述等其它文本。
+ * 返回已替换列表与仍无匹配（需 LLM 兜底）的角色。
+ */
+export declare function repairInvalidRolesInYaml(yamlPath: string, invalidRoles: string[], validRolePaths: string[]): {
+    replaced: {
+        from: string;
+        to: string;
+    }[];
+    unresolved: string[];
+};
 /**
  * 自动修复 compose 生成 YAML 中的变量引用错误。
  *

package/dist/cli/compose.js

@@ -4,7 +4,7 @@
  * 用户用一句话描述需求，AI 从角色库中选角色、设计 DAG、生成完整 workflow YAML。
  * 支持中文（agency-agents-zh）和英文（agency-agents）角色库。
  */
-import { listAgents } from '../agents/loader.js';
+import { listAgents, suggestFromPaths } from '../agents/loader.js';
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve, relative } from 'node:path';
 import { createConnector } from '../connectors/factory.js';
@@ -140,6 +140,7 @@ ${autoRun ? '      Include specific information from the user\'s description' :
 - **Detailed tasks**: Task descriptions should be specific — tell the role what to do and what format to output
 ${inputsDesignPrinciple}
 - **Final deliverable**: The last step must output the final deliverable the user wants (e.g., complete article, complete report), not review comments or suggestions. If there's a review step, it should output the revised final version, not a "list of suggestions"
+- **Clean final output (IMPORTANT)**: The LAST step's \`task\` MUST end with an explicit instruction to output ONLY the deliverable itself — no preamble/greeting, no "what I changed"/change-log, no formatting notes, no questions to the user, no suggestions to run \`ao\`/other commands, no "shall I continue?" closers. Append a line like: "⚠️ Output only the final deliverable itself — no preamble, no change-log, no meta-commentary, no questions, no tool/command suggestions."
 
 ## Available Role Catalog
 
@@ -234,6 +235,7 @@ ${autoRun ? '      直接包含用户需求中的具体信息' : '      使用 {
 - **任务详细**：task 描述要具体，告诉角色要做什么、输出什么格式
 ${inputsDesignPrinciple}
 - **最终成品**：最后一个步骤必须输出用户想要的最终成品（如完整文章、完整报告），而不是审查意见或修改建议。如果有审校步骤，审校步骤应该直接输出修改后的定稿，而不是"修改建议列表"
+- **干净的最终产出（重要）**：最后一个步骤的 \`task\` 结尾必须显式要求"只输出成品本身"——不要开场白/寒暄、不要"我改了什么/复盘/修改说明"、不要排版备注小节、不要向用户提问或请其拍板、不要建议运行 \`ao\` 或其它命令、不要"要我继续吗"之类收尾。请在该 step 的 task 末尾追加一行类似：「⚠️ 只输出最终成品本身：不要开场白、不要复盘或说明、不要向用户提问、不要建议任何命令或后续动作。」
 
 ## 可用角色目录
 
@@ -312,10 +314,17 @@ export async function composeWorkflow(options) {
     const { description, agentsDir, llmConfig } = options;
     const lang = options.lang ?? detectLang(description);
     // 1. 构建角色目录
-    const roles = buildRoleCatalog(agentsDir);
+    let roles = buildRoleCatalog(agentsDir);
     if (roles.length === 0) {
         throw new Error(t('compose.empty_catalog', { dir: agentsDir }));
     }
+    // 锁定阵容：把目录收窄到勾选的角色，LLM 既无法幻觉别的角色，也被强制用上这些
+    if (options.pinnedRoles?.length) {
+        const pin = new Set(options.pinnedRoles);
+        const filtered = roles.filter(r => pin.has(r.path));
+        if (filtered.length > 0)
+            roles = filtered;
+    }
     const catalog = formatCatalogForPrompt(roles);
     // 2. 构建 prompt
     const systemPrompt = buildComposeSystemPrompt(catalog, {
@@ -325,7 +334,13 @@ export async function composeWorkflow(options) {
         lang,
         timeoutMs: options.timeoutMs,
     });
-    const userPrompt = buildComposeUserPrompt(description, lang);
+    let userPrompt = buildComposeUserPrompt(description, lang);
+    if (options.pinnedRoles?.length) {
+        const names = roles.map(r => `${r.path}（${r.name}）`).join(lang === 'en' ? ', ' : '、');
+        userPrompt += lang === 'en'
+            ? `\n\nYou MUST build the workflow using EXACTLY these roles, every one of them and no others: ${names}. Design the DAG dependencies, task descriptions and variable chaining among them.`
+            : `\n\n必须且只能使用以下全部角色（每个都要用上，不要引入其他角色）：${names}。在它们之间设计 DAG 依赖、task 描述和变量串联。`;
+    }
     // 3. 调用 LLM
     console.log(`  ${t('compose.generating', { n: roles.length })}\n`);
     const connector = createConnector(llmConfig);
@@ -339,7 +354,7 @@ export async function composeWorkflow(options) {
         throw new Error(t('compose.invalid_yaml'));
     }
     // 5. 保存（避免覆盖）
-    const workflowsDir = resolve('workflows');
+    const workflowsDir = options.saveDir ? resolve(options.saveDir) : resolve('workflows');
     if (!existsSync(workflowsDir)) {
         mkdirSync(workflowsDir, { recursive: true });
     }
@@ -374,13 +389,37 @@ export async function composeWorkflow(options) {
         }
         return { errors, invalidRoles };
     }
-    const first = await validateGenerated(savedPath);
-    // 发现幻觉角色 → 让 LLM 修一次
+    let first = await validateGenerated(savedPath);
+    // 幻觉角色 → 先做确定性替换：有"够接近"的真实角色就直接改 YAML，不花一次 LLM 调用，
+    // 且保证替换结果一定是库里真实存在、可运行的角色。
     if (first.invalidRoles.length > 0) {
-        console.log(`  检测到 ${first.invalidRoles.length} 个不存在的角色，自动重新生成...`);
+        const det = repairInvalidRolesInYaml(savedPath, first.invalidRoles, [...validRolePaths]);
+        if (det.replaced.length > 0) {
+            console.log(`  自动替换 ${det.replaced.length} 个不存在的角色为最接近的真实角色：`);
+            for (const r of det.replaced)
+                console.log(`    ${r.from} → ${r.to}`);
+            first = await validateGenerated(savedPath);
+        }
+    }
+    // 仍有幻觉角色（无可信匹配）→ 让 LLM 修一次
+    if (first.invalidRoles.length > 0) {
+        console.log(`  仍有 ${first.invalidRoles.length} 个角色无法自动匹配，调 LLM 重新生成...`);
+        // 把"你是不是想用 X"喂回 LLM：从实际提供的目录里找最接近的真实角色，
+        // 让模型做定向替换而非盲目重生成，显著提高一次修复成功率
+        const catalogPaths = [...validRolePaths];
+        const corrections = first.invalidRoles.map(bad => {
+            const hit = suggestFromPaths(bad, catalogPaths);
+            return { bad, suggestion: hit[0] };
+        });
+        const mapLine = (sep) => corrections
+            .map(c => c.suggestion ? `${c.bad} → ${c.suggestion}` : c.bad)
+            .join(sep);
         const retryPrompt = lang === 'en'
-            ? `The following role paths in your previous YAML do NOT exist in the catalog: ${first.invalidRoles.join(', ')}.\n\nRegenerate the FULL YAML. Use ONLY role paths from the catalog above. Do not invent new paths.`
-            : `你上次生成的 YAML 里有不存在的 role 路径：${first.invalidRoles.join('、')}。\n\n请重新生成完整 YAML，role 必须严格使用上方角色目录中列出的路径，不要编造。`;
+            ? `The following role paths in your previous YAML do NOT exist in the catalog (→ shows the closest valid path):\n${corrections.map(c => `  - ${c.bad}${c.suggestion ? ` → use "${c.suggestion}" instead` : ''}`).join('\n')}\n\nRegenerate the FULL YAML, replacing each wrong path with the suggested one. Use ONLY role paths from the catalog above. Do not invent new paths.`
+            : `你上次生成的 YAML 里有不存在的 role 路径（→ 后是目录中最接近的正确路径）：\n${corrections.map(c => `  - ${c.bad}${c.suggestion ? ` → 请改用 "${c.suggestion}"` : ''}`).join('\n')}\n\n请重新生成完整 YAML，把每个错误路径替换为建议的正确路径。role 必须严格使用上方角色目录中列出的路径，不要编造。`;
+        if (corrections.some(c => c.suggestion)) {
+            console.log(`  建议替换: ${mapLine('，')}`);
+        }
         try {
             const retryResult = await connector.chat(systemPrompt, `${userPrompt}\n\n${retryPrompt}`, {
                 ...llmConfig,
@@ -389,7 +428,19 @@ export async function composeWorkflow(options) {
             const retryYaml = extractYamlFromResponse(retryResult.content);
             if (retryYaml && retryYaml.includes('steps:')) {
                 writeFileSync(savedPath, retryYaml + '\n', 'utf-8');
-                const second = await validateGenerated(savedPath);
+                let second = await validateGenerated(savedPath);
+                // LLM 重试后若仍残留幻觉角色 → 再用确定性替换兜底，堵住"重试后仍坏、却被当成功"的缺口
+                if (second.invalidRoles.length > 0) {
+                    const det2 = repairInvalidRolesInYaml(savedPath, second.invalidRoles, catalogPaths);
+                    if (det2.replaced.length > 0) {
+                        for (const r of det2.replaced)
+                            console.log(`    ${r.from} → ${r.to}`);
+                        second = await validateGenerated(savedPath);
+                    }
+                    if (second.invalidRoles.length > 0) {
+                        warnings.push(`仍有无法解析的角色: ${second.invalidRoles.join(', ')}`);
+                    }
+                }
                 // 重试后仍有变量引用错误 → 走 fix 链（autoFix → LLM 二次修复）
                 const finalErrors = await runVariableFixChain(savedPath, second.errors, validateGenerated, llmConfig, lang);
                 warnings.push(...finalErrors);
@@ -407,6 +458,33 @@ export async function composeWorkflow(options) {
     const finalYaml = readFileSync(savedPath, 'utf-8').trim();
     return { yaml: finalYaml, savedPath, relativePath, warnings };
 }
+/**
+ * 确定性修复幻觉角色：对每个不存在的 role，从角色库找到"够接近"的真实路径，直接在 YAML 文本里替换。
+ * 不依赖再调一次 LLM——只要有可信匹配，就保证替换为库里真实存在、可运行的角色。
+ * 仅替换 role 值中的精确路径（双/单引号包裹），避免误伤任务描述等其它文本。
+ * 返回已替换列表与仍无匹配（需 LLM 兜底）的角色。
+ */
+export function repairInvalidRolesInYaml(yamlPath, invalidRoles, validRolePaths) {
+    let content = readFileSync(yamlPath, 'utf-8');
+    const replaced = [];
+    const unresolved = [];
+    for (const bad of [...new Set(invalidRoles)]) {
+        const to = suggestFromPaths(bad, validRolePaths)[0];
+        if (!to) {
+            unresolved.push(bad);
+            continue;
+        }
+        const before = content;
+        content = content.split(`"${bad}"`).join(`"${to}"`).split(`'${bad}'`).join(`'${to}'`);
+        if (content !== before)
+            replaced.push({ from: bad, to });
+        else
+            unresolved.push(bad);
+    }
+    if (replaced.length > 0)
+        writeFileSync(yamlPath, content, 'utf-8');
+    return { replaced, unresolved };
+}
 /**
  * 变量引用错误的修复链：autoFix（启发式）→ LLM 二次修复 → 重新校验。
  * 返回最终仍未解决的 errors。

package/dist/cli/demo.d.ts

@@ -5,4 +5,9 @@ export interface DetectedLLM {
     envVar?: string;
 }
 export declare function detectAvailableLLMs(): Promise<DetectedLLM[]>;
+/**
+ * 首跑向导文案：根据检测到的 provider，给出个性化的"下一步"。
+ * 纯函数，便于测试。ao init 在角色库装好后调用。
+ */
+export declare function buildFirstRunGuidance(llms: DetectedLLM[], lang?: 'zh' | 'en'): string;
 export declare function runDemo(): Promise<void>;

package/dist/cli/demo.js

@@ -73,6 +73,50 @@ function resolveWorkflowPath() {
     }
     return p;
 }
+/**
+ * 首跑向导文案：根据检测到的 provider，给出个性化的"下一步"。
+ * 纯函数，便于测试。ao init 在角色库装好后调用。
+ */
+export function buildFirstRunGuidance(llms, lang = 'zh') {
+    const ready = llms.filter(l => l.available);
+    const lines = [];
+    if (ready.length > 0) {
+        const names = ready.map(l => l.name).join(lang === 'en' ? ', ' : '、');
+        if (lang === 'en') {
+            lines.push(`✅ Ready to go — detected: ${names}`);
+            lines.push('');
+            lines.push('Try it now:');
+            lines.push('  ao demo                                  see it run in ~60s');
+            lines.push('  ao compose "your goal in one sentence" --run');
+        }
+        else {
+            lines.push(`✅ 已就绪 —— 检测到可用 provider：${names}`);
+            lines.push('');
+            lines.push('现在就试：');
+            lines.push('  ao demo                                60 秒看效果');
+            lines.push('  ao compose "用一句话描述你的需求" --run');
+        }
+    }
+    else {
+        if (lang === 'en') {
+            lines.push('⚠ No usable LLM detected yet — pick the easiest path:');
+            lines.push('  • Key-free: a CLI you already pay for —');
+            lines.push('      npm i -g @anthropic-ai/claude-code   (Claude Max/Pro)');
+            lines.push('      or run a local model with Ollama (ollama.com)');
+            lines.push('  • API key:  ao init --provider deepseek --api-key sk-...');
+            lines.push('Then run:  ao demo');
+        }
+        else {
+            lines.push('⚠ 还没检测到可用的 LLM，选最省事的一条：');
+            lines.push('  • 免 key：装一个你已付费的 CLI——');
+            lines.push('      npm i -g @anthropic-ai/claude-code   (Claude Max/Pro 会员)');
+            lines.push('      或用 Ollama 跑本地模型 (ollama.com)');
+            lines.push('  • 用 API key：ao init --provider deepseek --api-key sk-...');
+            lines.push('  配好后运行：ao demo');
+        }
+    }
+    return lines.join('\n');
+}
 /** 没检测到 LLM 时：展示 DAG + 行动指引 */
 async function showDagAndGuide() {
     console.log('  ❌ 没检测到可用 LLM。先看一下 ao 工作流的 DAG 结构:\n');

package/dist/cli/validate-report.d.ts

@@ -0,0 +1,33 @@
+/**
+ * validate 报告美化：把 validateWorkflow() 的扁平 string[] 错误，
+ * 分类 + 按 step 分组 + 按修复优先级排序后渲染。
+ *
+ * 重要：本模块只“读” validateWorkflow 的字符串输出，不改动其契约。
+ * compose/mcp 仍消费原始 string[]，分类靠模式识别派生，互不影响。
+ */
+export type FindingCategory = 'cycle' | 'role' | 'dependency' | 'output' | 'loop' | 'variable' | 'other';
+export interface ValidationFinding {
+    scope: 'workflow' | 'step';
+    stepId?: string;
+    category: FindingCategory;
+    /** 首行错误信息 */
+    message: string;
+    /** 后续行（如“你是不是想用…”建议），已去缩进 */
+    hint?: string;
+}
+/** 从一条错误字符串派生结构化分类 */
+export declare function classifyError(raw: string): ValidationFinding;
+export declare function classifyErrors(errors: string[]): ValidationFinding[];
+export interface ValidationReport {
+    valid: boolean;
+    name: string;
+    steps: number;
+    inputs: number;
+    findings: ValidationFinding[];
+}
+/** 构造 --json 输出对象（纯函数，便于测试） */
+export declare function buildValidationReport(name: string, stepCount: number, inputCount: number, errors: string[]): ValidationReport;
+/**
+ * 渲染分组报告。stepOrder 用于让 step 分组按工作流定义顺序出现。
+ */
+export declare function formatValidationReport(workflowName: string, errors: string[], stepOrder?: string[]): string;