agency-orchestrator 0.7.5 → 0.8.0

package/README.en.md

@@ -14,6 +14,8 @@
 > **Note:** `ao compose --run` auto-detects your language. Both 216 Chinese roles and 184 English roles ([agency-agents](https://github.com/msitarzewski/agency-agents), MIT) are **bundled in the npm package — no extra download needed**. **10 English workflow templates** are ready in `workflows/en/`.
 
 > 📖 [Full Tutorial](https://dev.to/jnmetacode/agency-orchestrator-one-sentence-five-ai-agents-a-complete-plan-in-3-minutes-1ij6) — from install to real-world use in 10 minutes
+>
+> 📖 **Free companion learning** → [Learn AI coding from zero](https://aiolaola.com/?utm_source=github&utm_campaign=orchestrator): 180 free hands-on lessons + AI Coding Trilogy online + community · forever free
 
 > If you find this useful, please **Star** it — helps others discover the project.
 
@@ -37,7 +39,7 @@ Prefer not to use the command line? Run `ao web` locally and pick experts, run w
   <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.
+> Launch: `ao web` (local — your API key stays on your machine, never uploaded). A [desktop client download](https://github.com/jnMetaCode/agency-orchestrator/releases/latest) (Electron · macOS / Windows / Linux) is also available.
 
 ---
 
@@ -259,6 +261,12 @@ ao init --lang en                    # (Optional) Copy 184 English roles locally
 ao init --workflow                    # Interactive workflow creator
 ao compose "description"             # AI-powered workflow generation
 ao compose "description" --run       # Generate AND execute in one command
+ao team save <workflow.yaml>         # Save a role line-up as a reusable team (Loadout)
+ao team list / show / rm             # Manage saved teams
+ao run --team <name> "new task"      # Run a new task with a saved team (locked line-up)
+ao prompt optimize "<prompt>"        # AI-optimize a prompt (--save to keep it reusable)
+ao prompt test / list / garden       # Test / manage / starter templates (prompt library)
+ao skills [name]                     # List / view methodology skills to attach to steps
 ao run <workflow.yaml> [options]      # Execute workflow
 ao validate <workflow.yaml>          # Validate without running
 ao plan <workflow.yaml>              # Show execution plan (DAG)
@@ -293,6 +301,59 @@ The AI will:
 
 Add `--run` to generate and execute in one command. Supports `--provider` and `--model` flags (default: DeepSeek).
 
+### Teams / Loadouts (save a winning line-up and reuse it)
+
+Every `compose` builds an ad-hoc team. When a line-up works well, **save it as a team** and apply it to any new task — a team stores only the *roles*, decoupled from any specific task:
+
+```bash
+# Extract the line-up from a workflow that worked well, save it as a team
+ao team save workflows/tech-blog.yaml --name blog-crew
+
+# Put the whole crew on a new task (re-designs the steps for those roles and runs)
+ao run --team blog-crew "Write an explainer on the RISC-V architecture"
+
+ao team list           # List saved teams
+ao team show blog-crew # Inspect the line-up
+```
+
+`ao run --team` simply **locks** the compose role catalog down to the team's roles — so nobody is dropped and no role is hallucinated. Teams live in `~/.ao/teams/*.team.yaml` (plain YAML, copy-to-share) and are **shared between the CLI and the web Studio** — pick roles in Studio, hit "Save as team", and `ao run --team` can use it immediately, and vice versa.
+
+> Bring your own experts: set `AO_AGENTS_DIR=/your/roles/dir` and `run / compose / roles / web` all switch to your own role library.
+>
+> Fixed global dir: set `AO_HOME=~/.ao` (or any dir) so run outputs (`ao-output`) and generated workflows (`compose` / `--team`) land there instead of scattering across the CWD (#20). Or set `AO_OUTPUT_DIR` / `AO_WORKFLOWS_DIR` individually. Unset = unchanged (writes to current dir).
+
+### Prompt Lab
+
+Turn gut-feel prompts into assets you can optimize, test, compare, and save:
+
+```bash
+ao prompt optimize "write a tweet selling coffee" --save coffee-copy   # AI rewrites it into a sharper prompt
+ao prompt test "You are a translator, output only the translation" --mode system --input "good morning"
+ao prompt list / show coffee-copy   # saved prompts + version history
+ao prompt garden                    # built-in starter templates
+```
+
+`--mode system|user` distinguishes role/system prompts from task prompts. Optimize only ever produces a **better prompt** (it never executes the prompt). The Studio "Prompts" tab adds side-by-side original-vs-optimized comparison **with AI scoring**. Stored in `~/.ao/prompts/` (`AO_PROMPTS_DIR` to override), shared between CLI and Studio.
+
+### Skills (attach a methodology to a step)
+
+Roles decide *who* does it; skills decide *how*. Attach a **skill** (a methodology playbook) to a workflow step and its method is injected into that step — e.g. make the review step follow a structured review method, or the implementation step do TDD:
+
+```yaml
+steps:
+  - id: review
+    role: "engineering/engineering-code-reviewer"
+    skill: "chinese-code-review"     # single; or skills: ["test-driven-development", ...]
+    task: "Review this code {{code}}"
+```
+
+```bash
+ao skills                            # list all available skills
+ao skills test-driven-development    # view a skill's methodology
+```
+
+Skill content comes straight from the open-source [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) (MIT, 20 skills, bundled as a dependency — zero config). Or set `AO_SKILLS_DIR=/your/skills/dir` for your own.
+
 ### Resume & Iterate
 
 Not happy with a step? No need to start over. `--resume` reloads previous outputs, `--from` specifies where to restart:
@@ -542,6 +603,7 @@ Your AI subscription ──→ agency-orchestrator ──→ 400+ expert roles c
 | [ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) | AI coding tools field guide (Chinese) — 66 Claude Code tips + 9 tools best practices |
 | [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) | AI coding superpowers (Chinese) — 20 skills for Claude Code / Cursor |
 | [shellward](https://github.com/jnMetaCode/shellward) | AI agent security middleware — prompt injection detection, DLP, command safety |
+| [codepet](https://github.com/jnMetaCode/codepet) | Desktop pet that levels up as you code / use Claude Code — Electron, reads metadata only, local-first |
 
 ## Roadmap
 

package/README.md

@@ -12,6 +12,8 @@
 **一句话出结果 · 216 个专业 AI 角色 · YAML 零代码 · 10 种大模型 · 支持 key（推荐 DeepSeek），也有 7 种免 key 方式**
 
 > 📖 [完整上手教程](https://mp.weixin.qq.com/s/XcGbkMb6TM6NLQiL7ICwbw) — 从安装到实战，10 分钟上手
+>
+> 📖 **免费配套学习** → [从零学会 AI 编程](https://aiolaola.com/?utm_source=github&utm_campaign=orchestrator)：180 节免费实操课 + 《AI 编程实战三卷书》在线阅读 + 实战社区 · 永久免费
 
 > 觉得有用？请点个 **Star** — 帮助更多人发现这个项目。
 
@@ -25,6 +27,11 @@
 
 不想敲命令行？本地跑一条 `ao web`，浏览器里勾选专家、运行工作流、查看产物、实时介入——全程图形界面，全中英双语。
 
+> 🆕 **AI 自动组队**：不知道选哪些专家？角色页一句话、不选角色，AI 自动从全部专家里挑人组队并运行。
+> 🆕 **可视化画布**：工作流可在画布上拖拽节点 / 连线（自动防环）/ 改任务·角色 / 保存，运行时节点按状态实时点亮。
+> 🆕 **创意库**：内置图像生成提示词库（Nano Banana / Gemini，可搜索 / 分类 / 一键复制）。
+> 🆕 **零配置首跑**：本机已登录 Claude Code / Gemini CLI 等？AO 自动探测并直接用，连 API key 都不用配。
+
 <p align="center">
   <img src="./docs/screenshots/studio-roles-zh.png" alt="Studio · 角色组队：从 200+ 专家里勾选，AI 自动合成团队" width="800"><br/>
   <em>角色组队：从 200+ 专家里勾选，AI 自动合成团队并运行</em>
@@ -35,7 +42,7 @@
   <em>工作流：内置模板一键运行，也能对比多个模板</em>
 </p>
 
-> 启动：`ao web`（本地，密钥只存你自己机器、绝不外传）。也有 [桌面客户端](./desktop)（Electron）。
+> 启动：`ao web`（本地，密钥只存你自己机器、绝不外传）。也有 [桌面客户端下载](https://github.com/jnMetaCode/agency-orchestrator/releases/latest)（Electron · macOS / Windows / Linux）。
 > 英文界面同样完整 → 见 [English README](./README.en.md)。
 
 ---
@@ -106,6 +113,11 @@ ao compose "设计一个 SaaS 产品的定价策略" --run                   #
 npm install -g agency-orchestrator
 ```
 
+> **装 CLI 还是桌面端？**
+> - **桌面客户端**（[下载](https://github.com/jnMetaCode/agency-orchestrator/releases/latest)）**自带引擎与 Node，双击即用，无需** `npm i -g agency-orchestrator`。只有想在终端用 `ao` 命令、或接进脚本 / CI 时才需要装 CLI。
+> - 用 `--provider claude-code`（或 `gemini-cli` / `codex-cli` 等）时，需要**本机已安装并登录对应 CLI**；AO 会自动探测已装的，零配置直接用。用 API key 类（deepseek/openai…）则配好 key 即可，无需装任何 CLI。
+> - **自定义目录**：产物 / 数据目录用 `AO_DATA_DIR`（桌面端默认指向 userData），角色库用 `AO_AGENTS_DIR`，统一工作区用 `AO_HOME`。
+
 ### 第 2 步：一句话跑起来
 
 ```bash
@@ -268,6 +280,12 @@ ao init --lang en                    # （可选）复制 184 个英文角色到
 ao init --workflow                    # 交互式创建工作流
 ao compose "一句话描述"                # AI 智能编排工作流
 ao compose "一句话描述" --run          # 编排并立即执行
+ao team save <workflow.yaml>          # 把角色阵容存成可复用团队 (Loadout)
+ao team list / show / rm              # 管理已保存的团队
+ao run --team <名字> "新任务"          # 用已保存的团队跑新任务（锁定阵容）
+ao prompt optimize "提示词"           # AI 优化提示词（--save 存为可复用资产）
+ao prompt test / list / garden        # 测试 / 管理 / 起手模板（提示词沉淀）
+ao skills [名字]                       # 列出/查看可挂到步骤的方法论 skill
 ao run <workflow.yaml> [选项]          # 执行工作流
 ao validate <workflow.yaml>           # 校验（不执行）
 ao plan <workflow.yaml>               # 查看执行计划（DAG）
@@ -303,6 +321,59 @@ AI 会自动：
 
 支持 `--provider` 和 `--model` 参数（默认使用 DeepSeek）。
 
+### 团队 / Loadout（把跑得好的阵容存下来复用）
+
+`compose` 每次都是临时组队。如果某个角色阵容效果好，把它**存成团队**，套到任意新任务上——团队只保存「角色阵容」，与具体任务解耦：
+
+```bash
+# 从一个跑得好的工作流抽出阵容，存成团队
+ao team save workflows/tech-blog.yaml --name 技术博客组
+
+# 让整队人接新活（自动用这几个角色重新设计步骤并运行）
+ao run --team 技术博客组 "写一篇关于 RISC-V 架构的科普"
+
+ao team list           # 查看已保存的团队
+ao team show 技术博客组  # 查看阵容构成
+```
+
+`ao run --team` 的本质 = compose 时把可选角色**锁定**为团队那几个，所以既不会漏人、也不会幻觉出别的角色。团队存在 `~/.ao/teams/*.team.yaml`（纯 YAML，可直接拷贝分享），**命令行和网页 Studio 共用同一份**——Studio 里勾选角色后点「存为团队」，命令行立刻 `ao run --team` 可用，反之亦然。
+
+> 自带私有专家：设环境变量 `AO_AGENTS_DIR=/你的角色目录`，`run / compose / roles / web` 全部改用你自己的角色库。
+>
+> 固定全局目录：设 `AO_HOME=~/.ao`（或任意目录），运行产物 `ao-output`、`compose`/`--team` 生成的工作流都落到那里，不再随执行目录散落（#20）。也可用 `AO_OUTPUT_DIR` / `AO_WORKFLOWS_DIR` 单独指定。不设则维持原行为（写到当前目录）。
+
+### 提示词优化（Prompt Lab）
+
+把「靠感觉」的提示词，变成可优化、可测试、可对比、可沉淀的资产：
+
+```bash
+ao prompt optimize "帮我写个朋友圈文案卖咖啡" --save 咖啡文案   # AI 把它改写成更有效的提示词
+ao prompt test "你是专业翻译，只输出译文" --mode system --input "good morning"  # 用样例实跑看输出
+ao prompt list / show 咖啡文案     # 已保存的提示词 + 版本历史
+ao prompt garden                  # 内置起手模板
+```
+
+`--mode system|user` 区分「角色/系统提示词」和「任务提示词」。优化只产出**更好的提示词**（不会直接去执行它）。网页 Studio 的「提示词」页还能原版 vs 优化版**并排对比 + AI 评分**。存在 `~/.ao/prompts/`（`AO_PROMPTS_DIR` 可改），命令行与 Studio 共用。
+
+### Skills（给步骤挂方法论）
+
+角色决定「谁来做」，skill 决定「怎么做」。给工作流某一步挂一个 **skill**（流程剧本），它的方法论会注入该步——比如让代码审查步骤遵循结构化审查法、让实现步骤走 TDD：
+
+```yaml
+steps:
+  - id: review
+    role: "engineering/engineering-code-reviewer"
+    skill: "chinese-code-review"     # 单个；或 skills: ["test-driven-development", ...]
+    task: "审查这段代码 {{code}}"
+```
+
+```bash
+ao skills                      # 列出全部可用 skill
+ao skills test-driven-development   # 看某个 skill 的方法论
+```
+
+skill 内容直接用开源的 [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh)（MIT，20 个,已作为依赖,零配置）；也可设 `AO_SKILLS_DIR=/你的skill目录` 挂自己的。
+
 ### 迭代优化（Resume）
 
 跑完一轮觉得某步不满意？不用从头来。`--resume` 加载上一轮输出，`--from` 指定从哪步重跑：
@@ -523,9 +594,18 @@ ao-output/产品需求评审-2026-03-22/
 | [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 / 可灵 / 即梦通用 |
+| 🆕 [codepet](https://github.com/jnMetaCode/codepet) ![](https://img.shields.io/github/stars/jnMetaCode/codepet?style=flat&label=⭐) | 🐾 桌面宠物 | 挂在桌面的桌宠，你写代码 / 用 Claude Code 它就涨经验、升级、换状态、冒话（Electron · 仅读元数据，本地优先） |
 
 ### 交流
 
+<table>
+<tr>
+<td width="170" align="center">
+<img src="assets/qr-wechat.jpg" width="150" alt="微信公众号 AI不止语 二维码"><br>
+<sub>微信扫码关注</sub>
+</td>
+<td>
+
 微信公众号 **「AI不止语」**（微信搜索 `AI_BuZhiYu`）— 技术问答 · 项目更新 · 实战文章
 
 | 渠道 | 加入方式 |
@@ -533,6 +613,10 @@ ao-output/产品需求评审-2026-03-22/
 | QQ 2群 | [点击加入](https://qm.qq.com/q/EeNQA9xCxy)（群号 1071280067） |
 | 微信群 | 关注公众号后回复「群」获取入群方式 |
 
+</td>
+</tr>
+</table>
+
 ## 路线图
 
 - [x] **v0.1** — YAML 工作流、DAG 引擎、4 个 LLM 连接器、CLI、实时输出

package/dist/canvas/graph.d.ts

@@ -0,0 +1,27 @@
+export interface CanvasPosition {
+    x: number;
+    y: number;
+}
+export interface CanvasGraphNode {
+    id: string;
+    position: CanvasPosition;
+    /** 该步骤的完整 YAML 定义（保真往返的关键：原样保留所有字段）。 */
+    data: Record<string, unknown>;
+}
+export interface CanvasGraphEdge {
+    id: string;
+    source: string;
+    target: string;
+}
+export interface CanvasGraph {
+    name: string;
+    nodes: CanvasGraphNode[];
+    edges: CanvasGraphEdge[];
+}
+/** YAML 文本 → 画布 graph。坐标取 meta.layout，没有则给 {0,0}（前端用 dagre 自动布局）。 */
+export declare function workflowToGraph(yamlText: string): CanvasGraph;
+/**
+ * 画布 graph → YAML 文本。以 baseYamlText 为底保留顶层字段（name/agents_dir/llm/inputs…）；
+ * steps 由 graph 节点重建（保留每步全部字段），depends_on 由连线重算，坐标写进 meta.layout。
+ */
+export declare function graphToWorkflow(graph: CanvasGraph, baseYamlText: string): string;

package/dist/canvas/graph.js

@@ -0,0 +1,71 @@
+// 工作流 YAML ↔ 画布 graph 的双向转换（可编辑画布的核心契约）。
+//
+// 设计原则（防 AI 开发头号风险「往返丢字段」）：
+//   - graph 节点携带**完整的 step 原始对象**（node.data）；
+//   - graphToWorkflow 只重算 depends_on（来自连线）和坐标（meta.layout），其余字段原样 dump；
+//   - 转换基于原始 YAML doc（不走会丢未知字段的 parseWorkflow），保留 name/agents_dir/llm/inputs 等。
+//   - 坐标存进 doc.meta.layout（引擎忽略，不影响可运行性 / 校验）。
+//
+// 这两个函数是纯函数（string in / string out + 朴素对象），便于单测往返。
+import yaml from 'js-yaml';
+/** YAML 文本 → 画布 graph。坐标取 meta.layout，没有则给 {0,0}（前端用 dagre 自动布局）。 */
+export function workflowToGraph(yamlText) {
+    const doc = (yaml.load(yamlText) || {});
+    const steps = Array.isArray(doc.steps) ? doc.steps : [];
+    const meta = (doc.meta || {});
+    const layout = (meta.layout || {});
+    const nodes = steps.map((step) => {
+        const id = String(step.id);
+        const pos = layout[id];
+        return {
+            id,
+            position: pos && typeof pos.x === 'number' && typeof pos.y === 'number' ? { x: pos.x, y: pos.y } : { x: 0, y: 0 },
+            data: step,
+        };
+    });
+    const edges = [];
+    for (const step of steps) {
+        const target = String(step.id);
+        const deps = Array.isArray(step.depends_on) ? step.depends_on : [];
+        for (const dep of deps) {
+            const source = String(dep);
+            edges.push({ id: `${source}->${target}`, source, target });
+        }
+    }
+    return { name: String(doc.name ?? 'workflow'), nodes, edges };
+}
+/**
+ * 画布 graph → YAML 文本。以 baseYamlText 为底保留顶层字段（name/agents_dir/llm/inputs…）；
+ * steps 由 graph 节点重建（保留每步全部字段），depends_on 由连线重算，坐标写进 meta.layout。
+ */
+export function graphToWorkflow(graph, baseYamlText) {
+    const doc = (yaml.load(baseYamlText) || {});
+    // 入边表：target ← [sources]，保持稳定顺序（按节点出现顺序）。
+    const incoming = new Map();
+    for (const node of graph.nodes)
+        incoming.set(node.id, []);
+    for (const edge of graph.edges) {
+        if (!incoming.has(edge.target))
+            incoming.set(edge.target, []);
+        incoming.get(edge.target).push(edge.source);
+    }
+    doc.steps = graph.nodes.map((node) => {
+        const step = { ...node.data, id: node.id };
+        const deps = incoming.get(node.id) ?? [];
+        if (deps.length > 0)
+            step.depends_on = deps;
+        else
+            delete step.depends_on; // 没有入边就不写空数组
+        return step;
+    });
+    // 坐标存进 meta.layout（引擎忽略）。
+    const meta = (doc.meta || {});
+    const layout = {};
+    for (const node of graph.nodes)
+        layout[node.id] = { x: Math.round(node.position.x), y: Math.round(node.position.y) };
+    meta.layout = layout;
+    doc.meta = meta;
+    if (graph.name)
+        doc.name = graph.name;
+    return yaml.dump(doc, { lineWidth: -1, noRefs: true });
+}

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

@@ -0,0 +1,9 @@
+/** `ao run --compare` 的终端报告格式化（纯函数，便于单测）。 */
+import type { CompareVerdict } from '../core/compare.js';
+export interface CompareReportInput {
+    multiOutput: string;
+    baselineOutput: string;
+    verdict: CompareVerdict | null;
+}
+/** 把对比结果格式化成终端可读的报告块。 */
+export declare function formatCompareReport(r: CompareReportInput): string;

package/dist/cli/compare-report.js

@@ -0,0 +1,25 @@
+const PREVIEW = 800;
+const preview = (s) => (s.length > PREVIEW ? s.slice(0, PREVIEW) + '\n…[省略，完整产出见 ao-output]' : s);
+/** 把对比结果格式化成终端可读的报告块。 */
+export function formatCompareReport(r) {
+    const L = ['', '═'.repeat(50), '  多智能体 vs 单次基线'];
+    if (!r.verdict) {
+        L.push('  ⚠️ 评审解析失败，无法给出可信评分（judge 未返回有效 JSON）。');
+        L.push('  两份产出仍可人工对比：多智能体见上方 / ao-output，单次基线见下。');
+    }
+    else {
+        const v = r.verdict;
+        const mark = v.winner === 'multi-agent' ? '✅ 多智能体胜' : v.winner === 'baseline' ? '❌ 单次基线胜' : '➖ 打平';
+        const conf = v.consistent ? '高可信' : '低可信(疑位置偏置)';
+        L.push(`  评审: 多智能体 ${v.multiScore.toFixed(1)} | 单次基线 ${v.baseScore.toFixed(1)} → ${mark}（${conf}）`);
+        for (const reason of v.reasons)
+            if (reason)
+                L.push(`    · ${reason}`);
+    }
+    L.push(`  产出长度: 多智能体 ${r.multiOutput.length} 字 / 单次基线 ${r.baselineOutput.length} 字`);
+    L.push('─'.repeat(50));
+    L.push('  单次基线产出（多智能体产出见上方 / ao-output）:');
+    L.push(preview(r.baselineOutput) || '  (空)');
+    L.push('═'.repeat(50), '');
+    return L.join('\n');
+}

package/dist/cli/install.d.ts

@@ -0,0 +1,33 @@
+export interface ToolTarget {
+    id: string;
+    label: string;
+    /** 安装目标目录：user 级用 home，project 级用 cwd */
+    dest: (home: string, cwd: string) => string;
+    ext: string;
+    scope: 'user' | 'project';
+}
+/** 各编码工具的安装目标（参考 agency-agents-app 的 destination 表）。 */
+export declare const INSTALL_TARGETS: Record<string, ToolTarget>;
+export interface RoleFile {
+    rolePath: string;
+    category: string;
+    id: string;
+    absPath: string;
+}
+/** 递归收集角色 .md（只取带 `name:` frontmatter 的真角色，跳过 README/示例等）。 */
+export declare function collectRoleFiles(agentsDir: string): RoleFile[];
+export interface InstallResult {
+    installed: number;
+    destDir: string;
+    files: string[];
+}
+/**
+ * 把角色装进目标工具目录。文件名用 `<category>-<id><ext>` 防跨分类重名。
+ * 内容逐字复制（角色 .md 的 frontmatter 即各工具通用格式）。
+ */
+export declare function installRoles(agentsDir: string, target: ToolTarget, opts?: {
+    home: string;
+    cwd: string;
+    category?: string;
+    dryRun?: boolean;
+}): InstallResult;

package/dist/cli/install.js

@@ -0,0 +1,64 @@
+/**
+ * `ao install --tool <tool>` —— 把内置 AI 角色装进各编码工具（Claude Code / Cursor 等）。
+ *
+ * 借鉴 agency-agents-app 的核心能力，但聚焦 AO 生态：中文角色库(agency-agents-zh)是空位，
+ * 让"只在编码工具里用角色、不跑工作流"的用户也能一键装入。角色 .md 的 frontmatter
+ * (name/description) 本就是 Claude Code agent 格式，多数工具可直接复制。
+ */
+import { readdirSync, statSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/** 各编码工具的安装目标（参考 agency-agents-app 的 destination 表）。 */
+export const INSTALL_TARGETS = {
+    'claude-code': { id: 'claude-code', label: 'Claude Code', dest: (h) => join(h, '.claude', 'agents'), ext: '.md', scope: 'user' },
+    'copilot': { id: 'copilot', label: 'GitHub Copilot', dest: (h) => join(h, '.github', 'agents'), ext: '.md', scope: 'user' },
+    'gemini-cli': { id: 'gemini-cli', label: 'Gemini CLI', dest: (h) => join(h, '.gemini', 'agents'), ext: '.md', scope: 'user' },
+    'qwen': { id: 'qwen', label: 'Qwen Code', dest: (h) => join(h, '.qwen', 'agents'), ext: '.md', scope: 'user' },
+    'cursor': { id: 'cursor', label: 'Cursor', dest: (_h, cwd) => join(cwd, '.cursor', 'rules'), ext: '.mdc', scope: 'project' },
+    'opencode': { id: 'opencode', label: 'opencode', dest: (_h, cwd) => join(cwd, '.opencode', 'agents'), ext: '.md', scope: 'project' },
+};
+const SKIP_DIRS = new Set(['node_modules', 'scripts', 'integrations', 'examples', '.git']);
+/** 递归收集角色 .md（只取带 `name:` frontmatter 的真角色，跳过 README/示例等）。 */
+export function collectRoleFiles(agentsDir) {
+    const root = resolve(agentsDir);
+    const out = [];
+    const walk = (dir, category) => {
+        for (const entry of readdirSync(dir)) {
+            if (SKIP_DIRS.has(entry))
+                continue;
+            const full = join(dir, entry);
+            const st = statSync(full);
+            if (st.isDirectory()) {
+                walk(full, category ? `${category}/${entry}` : entry); // 用完整相对目录作 category，避免嵌套分类重名
+            }
+            else if (entry.endsWith('.md') && !/^(README|CONTRIBUTING|LICENSE|SECURITY)/i.test(entry)) {
+                const head = readFileSync(full, 'utf-8').slice(0, 400);
+                if (!/^---[\s\S]*?\bname\s*:/.test(head))
+                    continue; // 必须有 name frontmatter
+                const id = entry.replace(/\.md$/, '');
+                out.push({ rolePath: `${category}/${id}`, category: category || 'other', id, absPath: full });
+            }
+        }
+    };
+    walk(root, '');
+    return out;
+}
+/**
+ * 把角色装进目标工具目录。文件名用 `<category>-<id><ext>` 防跨分类重名。
+ * 内容逐字复制（角色 .md 的 frontmatter 即各工具通用格式）。
+ */
+export function installRoles(agentsDir, target, opts = { home: '', cwd: '' }) {
+    const roles = collectRoleFiles(agentsDir).filter((r) => !opts.category || r.category === opts.category);
+    const destDir = target.dest(opts.home, opts.cwd);
+    const files = [];
+    if (!opts.dryRun && roles.length)
+        mkdirSync(destDir, { recursive: true });
+    for (const r of roles) {
+        // 文件名用完整分类路径拍平(a/b → a-b)，避免嵌套分类下同名角色互相覆盖
+        const outName = `${r.category.replace(/\//g, '-')}-${r.id}${target.ext}`;
+        const outPath = join(destDir, outName);
+        if (!opts.dryRun)
+            writeFileSync(outPath, readFileSync(r.absPath, 'utf-8'), 'utf-8');
+        files.push(outName);
+    }
+    return { installed: files.length, destDir, files };
+}

package/dist/cli/materialize.d.ts

@@ -0,0 +1,24 @@
+import type { WorkflowResult } from '../types.js';
+export interface FileBlock {
+    path: string;
+    content: string;
+}
+/**
+ * 解析文本里的"文件块"。返回 [{path, content}]，按出现顺序；同路径后者覆盖前者。
+ */
+export declare function parseFileBlocks(text: string): FileBlock[];
+/**
+ * 把候选路径规整成相对目标目录的安全路径；非法（绝对路径 / .. 逃逸 / 越界）返回 null。
+ */
+export declare function safeRelPath(candidate: string, destDir: string): string | null;
+export interface MaterializeResult {
+    destDir: string;
+    stepId: string | null;
+    files: string[];
+    skipped: string[];
+}
+/**
+ * 从工作流结果落盘：从后往前扫已完成步的产出，取第一个含文件块的步，把其文件写到 destDir。
+ * 这样 verify 等收尾步在最后也没事——会自动回退到真正出代码的 build 步。
+ */
+export declare function materializeFromResult(result: WorkflowResult, destDir: string): MaterializeResult;

package/dist/cli/materialize.js

@@ -0,0 +1,131 @@
+/**
+ * `ao run --materialize <dir>` 核心：把工作流（开发步）产出里的"文件块"落盘成真实项目脚手架。
+ *
+ * 约定格式（喂给开发角色，解析器主认这个 + 容错）：
+ *   ### path/to/file.ext        ← 标题行给出文件路径（# / ** / `` 包裹均可）
+ *   ```lang
+ *   <文件内容>
+ *   ```
+ * 也兼容围栏信息串带路径：```ts path=src/x.ts
+ *
+ * 安全：拒绝绝对路径、`..` 逃逸、越出目标目录的路径（由 safeRelPath 把关）。
+ */
+import { resolve, sep, normalize, join, dirname } from 'node:path';
+import { mkdirSync, writeFileSync } from 'node:fs';
+/** 一行去掉 markdown 标记后，是否本身就是一个"看起来像路径"的 token。 */
+function pathFromHeadingLine(line) {
+    // 去掉标题 #、加粗 **、行内代码 `、列表符号、首尾空白与结尾冒号
+    const stripped = line
+        .replace(/^[\s>]*#{1,6}\s*/, '')
+        .replace(/\*\*/g, '')
+        .replace(/`/g, '')
+        .replace(/^[-*]\s+/, '')
+        .replace(/[:：]\s*$/, '')
+        .trim();
+    // 必须整行就是一个路径：含 . 扩展名或 /，且只由路径合法字符组成
+    if (/^[\w.\-]+(\/[\w.\-]+)*$/.test(stripped) && (stripped.includes('.') || stripped.includes('/'))) {
+        return stripped;
+    }
+    return null;
+}
+/** 从围栏信息串里取路径：```ts path=src/x.ts 或 ```ts file=src/x.ts 或 ```src/x.ts */
+function pathFromFenceInfo(info) {
+    const m = info.match(/(?:path|file)\s*=\s*([\w.\-/]+)/i);
+    if (m)
+        return m[1];
+    const tok = info.trim().split(/\s+/)[0] || '';
+    // 信息串第一个 token 本身是路径（含 . 或 /），而非单纯语言名
+    if ((tok.includes('/') || /\.[a-zA-Z0-9]+$/.test(tok)) && /^[\w.\-/]+$/.test(tok))
+        return tok;
+    return null;
+}
+/**
+ * 解析文本里的"文件块"。返回 [{path, content}]，按出现顺序；同路径后者覆盖前者。
+ */
+export function parseFileBlocks(text) {
+    const lines = text.split(/\r?\n/); // 容忍 CRLF：否则尾随 \r 会让围栏正则匹配不上、整体失效
+    const blocks = [];
+    let lastNonBlank = ''; // 紧邻围栏的上一非空行（用于取标题路径）
+    for (let i = 0; i < lines.length; i++) {
+        const fence = lines[i].match(/^(\s*)(`{3,}|~{3,})(.*)$/);
+        if (!fence) {
+            if (lines[i].trim())
+                lastNonBlank = lines[i];
+            continue;
+        }
+        // 进入围栏：闭合围栏的长度必须 ≥ 开围栏（这样 ```` 外层可包裹含 ``` 的文件，如 README）
+        const marker = fence[2][0];
+        const openLen = fence[2].length;
+        const closeRe = new RegExp(`^\\s*[${marker}]{${openLen},}\\s*$`);
+        const info = fence[3] || '';
+        const body = [];
+        let closed = false;
+        let j = i + 1;
+        for (; j < lines.length; j++) {
+            if (closeRe.test(lines[j])) {
+                closed = true;
+                break;
+            }
+            body.push(lines[j]);
+        }
+        const path = pathFromFenceInfo(info) || pathFromHeadingLine(lastNonBlank);
+        if (path)
+            blocks.push({ path, content: body.join('\n') });
+        // 跳到闭合围栏之后；围栏块不更新 lastNonBlank
+        i = closed ? j : lines.length;
+        lastNonBlank = '';
+    }
+    // 同路径去重：保留最后一次
+    const byPath = new Map();
+    for (const b of blocks)
+        byPath.set(b.path, b.content);
+    return Array.from(byPath, ([path, content]) => ({ path, content }));
+}
+/**
+ * 把候选路径规整成相对目标目录的安全路径；非法（绝对路径 / .. 逃逸 / 越界）返回 null。
+ */
+export function safeRelPath(candidate, destDir) {
+    let p = candidate.trim().replace(/^\.\//, '');
+    if (!p || p.startsWith('/') || p.startsWith('~') || p.startsWith('\\') || /^[a-zA-Z]:/.test(p))
+        return null;
+    const rel = normalize(p);
+    if (rel.startsWith('..' + sep) || rel === '..' || rel.includes(sep + '..' + sep))
+        return null;
+    if (rel === '.' || rel === '')
+        return null; // 规整后指向目标根本身（如 "foo/.."）→ 拒绝，避免写到目录上 EISDIR
+    const full = resolve(destDir, rel);
+    const base = resolve(destDir);
+    if (full !== base && !full.startsWith(base + sep))
+        return null;
+    return rel;
+}
+/**
+ * 从工作流结果落盘：从后往前扫已完成步的产出，取第一个含文件块的步，把其文件写到 destDir。
+ * 这样 verify 等收尾步在最后也没事——会自动回退到真正出代码的 build 步。
+ */
+export function materializeFromResult(result, destDir) {
+    const out = { destDir, stepId: null, files: [], skipped: [] };
+    const steps = result.steps.filter((s) => s.status === 'completed' && s.output);
+    // 取"文件块最多"的步：build 出整个项目(多文件)，verify 顶多顺带 1 个测试，不会盖过 build。
+    // 并列时保留靠前的步（build 通常在 verify 之前）。
+    let bestBlocks = [];
+    for (const s of steps) {
+        const blocks = parseFileBlocks(String(s.output));
+        if (blocks.length > bestBlocks.length) {
+            bestBlocks = blocks;
+            out.stepId = s.id;
+        }
+    }
+    for (const b of bestBlocks) {
+        const rel = safeRelPath(b.path, destDir);
+        if (!rel) {
+            out.skipped.push(b.path);
+            continue;
+        }
+        const full = join(destDir, rel);
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, b.content.endsWith('\n') ? b.content : b.content + '\n', 'utf-8');
+        out.files.push(rel);
+    }
+    return out;
+}

package/dist/cli/parse-inputs.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 解析 `--input key=value` / `-i key=@file` 参数。
+ * argv 形如 process.argv.slice(2)（即包含命令与工作流文件，故从下标 2 起扫描）。
+ *
+ * 安全：`@file` 会读取本机文件作为输入值。网页 Studio 把请求里的 input 原样拼成 `-i k=v`，
+ * 若放行 @file，任意 CSRF/同机来源即可用 `@/path` 读取本机文件（如保存的 API key）经 LLM
+ * 输出回传。故网页入口设置 `AO_NO_AT_FILE=1` 关闭展开，此时 `@` 值按字面字符串处理。
+ *
+ * onError 由调用方提供（CLI 走 console.error + process.exit；测试可抛异常）。
+ */
+export declare function parseInputPairs(argv: string[], onError: (msg: string) => never): Record<string, string>;