agency-orchestrator 0.9.0 → 0.12.0

package/README.en.md

@@ -3,24 +3,25 @@
 **English** | [中文](./README.md)
 
 > **One sentence in, a full plan out — multiple AI roles collaborate automatically.**
+>
+> **It's your one-person company: you're the boss, AI is the team — auto-assembled, asking your sign-off on big calls, delivering against acceptance criteria.**
 
 [![CI](https://github.com/jnMetaCode/agency-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/jnMetaCode/agency-orchestrator/actions)
 [![npm version](https://img.shields.io/npm/v/agency-orchestrator)](https://www.npmjs.com/package/agency-orchestrator)
 [![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 · 216 expert AI roles · Zero-code YAML · 10 LLM providers · key supported (DeepSeek recommended), plus 7 key-free options**
+**One sentence → full plan · 267 expert AI roles · Zero-code YAML · 11 LLM providers · key supported (DeepSeek recommended), plus 7 key-free options**
 
-> **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/`.
+> **Note:** `ao compose --run` auto-detects your language. Both 267 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
+> 📖 [Full Tutorial](https://dev.to/jnmetacode/agency-orchestrator-one-sentence-five-ai-agents-a-complete-plan-in-3-minutes-1ij6) (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 hands-on lessons + AI Coding Trilogy + community, forever free)
 
 > If you find this useful, please **Star** it — helps others discover the project.
 
 <p align="center">
-  <img src="./demo.gif" alt="ao compose --run demo" width="700">
+  <img src="./demo-studio-en.gif" alt="Web Studio: one sentence, AI builds the team" width="820"><br/>
+  <em>Web Studio: type one sentence, AI builds a team from 200+ experts and runs it</em>
 </p>
 
 ---
@@ -30,8 +31,8 @@
 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>
+  <img src="./docs/screenshots/studio-role-lib-ko.png" alt="Studio · Build a Team: role-library dropdown (Korean library shown)" width="800"><br/>
+  <em>Build a Team: ☆ favorites, My Roles, and a role-library dropdown — Chinese / English / Korean / Russian / pt-BR / Indonesian / Arabic</em>
 </p>
 
 <p align="center">
@@ -40,15 +41,23 @@ Prefer not to use the command line? Run `ao web` locally and pick experts, run w
 </p>
 
 > 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.
+>
+> **Docker / NAS** (amd64/arm64): `docker run -d -p 8088:8088 -v ao-data:/data ghcr.io/jnmetacode/agency-orchestrator:latest`, then open `http://<host>:8088` — keys are configured in the Providers tab and persist in the mounted volume. A ready-made [docker-compose.yml](./docker-compose.yml) is in the repo root.
 
 ---
 
 ## One Sentence, Full Result
 
+Prefer the command line? One command, one sentence, full result:
+
 ```bash
 ao compose "I'm a programmer looking to start a side hustle with AI content, target $3K/month, give me a complete plan" --run
 ```
 
+<p align="center">
+  <img src="./demo.gif" alt="ao compose CLI demo" width="700">
+</p>
+
 5 AI roles collaborate automatically:
 
 ```
@@ -68,7 +77,7 @@ ao compose "I'm a programmer looking to start a side hustle with AI content, tar
 ==================================================
 ```
 
-**No code. No config. No role selection.** One sentence → AI auto-decomposes the task → matches roles from 216 experts → executes as DAG → outputs a complete plan.
+**No code. No config. No role selection.** One sentence → AI auto-decomposes the task → matches roles from 267 experts → executes as DAG → outputs a complete plan.
 
 ### What Can You Build
 
@@ -93,7 +102,7 @@ Chatting with one AI gives you one perspective. But any real decision needs prod
 
 | | ChatGPT / Claude | CrewAI / LangGraph | **Agency Orchestrator** |
 |---|--------|-----------|---------------------|
-| Roles | 1 generalist | Write your own | **216 expert roles** |
+| Roles | 1 generalist | Write your own | **267 expert roles** |
 | Usage | Chat | Write Python | **One sentence / YAML** |
 | API key | — | Required | **Key supported; 7 key-free options too** |
 | Dependencies | — | pip + dozens of packages | **npm + 2 deps** |
@@ -191,6 +200,7 @@ steps:
   - id: summary
     role: "product/product-manager"
     task: "Synthesize feedback:\n\n{{tech_report}}\n\n{{design_report}}"
+    acceptance: "1. Clear go/no-go verdict  2. List must-fix issues"  # optional: injected at prompt tail, used as review yardstick
     depends_on: [tech_review, design_review]
 ```
 
@@ -209,7 +219,7 @@ analyze ──→ tech_review  ──→ summary
           (parallel)
 ```
 
-## 10 LLM Providers — 7 Need No API Key
+## 11 LLM Providers — 7 Need No API Key
 
 **Already paying for one of these? You're ready to go:**
 
@@ -230,6 +240,7 @@ analyze ──→ tech_review  ──→ summary
 | Provider | Config | Env Variable |
 |----------|--------|-------------|
 | DeepSeek | `provider: "deepseek"` | `DEEPSEEK_API_KEY` |
+| Volcengine Ark (Doubao / Kimi / GLM · sponsor) | `provider: "volcengine"` | `ARK_API_KEY` |
 | Claude API | `provider: "claude"` | `ANTHROPIC_API_KEY` |
 | OpenAI | `provider: "openai"` | `OPENAI_API_KEY` |
 
@@ -256,7 +267,7 @@ OPENAI_API_KEY=your-key
 
 ```bash
 ao demo                              # Zero-config multi-agent demo
-ao init                              # (Optional) Copy 216 Chinese roles locally for editing
+ao init                              # (Optional) Copy 267 Chinese roles locally for editing
 ao init --lang en                    # (Optional) Copy 184 English roles locally for editing
 ao init --workflow                    # Interactive workflow creator
 ao compose "description"             # AI-powered workflow generation
@@ -294,7 +305,7 @@ ao compose "PR code review covering security and performance"
 ```
 
 The AI will:
-1. Select matching roles from 216 available (e.g., Code Reviewer, Security Engineer, Performance Benchmarker)
+1. Select matching roles from 267 available (e.g., Code Reviewer, Security Engineer, Performance Benchmarker)
 2. Design the DAG (3-way parallel → summary)
 3. Generate complete YAML with variable passing and task descriptions
 4. Save to `workflows/` — ready to `ao run`
@@ -588,7 +599,7 @@ ao-output/product-review-2026-03-22/
 
 ```
 Your AI subscription ──→ agency-orchestrator ──→ 400+ expert roles collaborate ──→ quality output
-                              │                  (216 Chinese + 184 English)
+                              │                  (267 Chinese + 184 English + 5 languages)
              ┌────────────────┼────────────────┐
              ▼                ▼                ▼
       14 AI Coding Tools    CLI Mode        MCP Server
@@ -598,8 +609,9 @@ Your AI subscription ──→ agency-orchestrator ──→ 400+ expert roles c
 
 | Project | Description |
 |---------|-------------|
-| [agency-agents](https://github.com/msitarzewski/agency-agents) | 184 English AI role definitions by [@msitarzewski](https://github.com/msitarzewski) — the English role library for this engine |
-| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) | 216 Chinese AI role definitions (Chinese) — the Chinese role library for this engine |
+| [agency-agents](https://github.com/msitarzewski/agency-agents) | 184 English AI roles by [@msitarzewski](https://github.com/msitarzewski) (MIT) — **bundled in the npm package**, auto-selected for English tasks by `ao compose`, no separate install needed |
+| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) | 267 Chinese AI role definitions (Chinese) — the Chinese role library for this engine |
+| [ko](https://github.com/jnMetaCode/agency-agents-ko) · [ru](https://github.com/jnMetaCode/agency-agents-ru) · [pt-BR](https://github.com/jnMetaCode/agency-agents-pt-BR) · [id](https://github.com/jnMetaCode/agency-agents-id) · [ar](https://github.com/jnMetaCode/agency-agents-ar) | 187 roles each (184 upstream translations + 3 local-market originals) — `npm i agency-agents-<lang>`, then switch via the Studio role-library dropdown |
 | [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 |

package/README.md

@@ -3,17 +3,17 @@
 **中文** | [English](./README.en.md)
 
 > **一句话，让多个 AI 角色自动协作，几分钟出完整方案。**
+>
+> **也是你的「一人公司」：你当老板，AI 当团队——自动组队、重大决策请你签字、按验收标准交付。**
 
 [![CI](https://github.com/jnMetaCode/agency-orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/jnMetaCode/agency-orchestrator/actions)
 [![npm version](https://img.shields.io/npm/v/agency-orchestrator)](https://www.npmjs.com/package/agency-orchestrator)
 [![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)
 
-**一句话出结果 · 216 个专业 AI 角色 · YAML 零代码 · 10 种大模型 · 支持 key（推荐 DeepSeek），也有 7 种免 key 方式**
+**一句话出结果 · 267 个专业 AI 角色 · YAML 零代码 · 11 种大模型 · 支持 key（推荐 DeepSeek），也有 7 种免 key 方式**
 
-> 📖 [完整上手教程](https://mp.weixin.qq.com/s/XcGbkMb6TM6NLQiL7ICwbw) — 从安装到实战，10 分钟上手
->
-> 📖 **免费配套学习** → [从零学会 AI 编程](https://aiolaola.com/?utm_source=github&utm_campaign=orchestrator)：180 节免费实操课 + 《AI 编程实战三卷书》在线阅读 + 实战社区 · 永久免费
+> 📖 [完整上手教程](https://mp.weixin.qq.com/s/XcGbkMb6TM6NLQiL7ICwbw)（从安装到实战，10 分钟上手） ·  🎓 **免费配套学习**：[从零学会 AI 编程](https://aiolaola.com/?utm_source=github&utm_campaign=orchestrator)（180 节实操课 + 三卷书 + 实战社区，永久免费）
 
 > 觉得有用？请点个 **Star** — 帮助更多人发现这个项目。
 
@@ -28,16 +28,24 @@
 
 不想敲命令行？本地跑一条 `ao web`，浏览器里勾选专家、运行工作流、查看产物、实时介入——全程图形界面，全中英双语。
 
+> 🆕 **「一人公司」系列模板**：做产品 / 做内容 / 做投研 + 全员大会，关键步骤带验收标准（`acceptance`），投研含老板签字闸门——交付的是可验收的工作成果，不承诺奇迹。
 > 🆕 **AI 自动组队**：不知道选哪些专家？角色页一句话、不选角色，AI 自动从全部专家里挑人组队并运行。
 > 🆕 **可视化画布**：工作流可在画布上拖拽节点 / 连线（自动防环）/ 改任务·角色 / 保存，运行时节点按状态实时点亮。
 > 🆕 **创意库**：内置图像生成提示词库（Nano Banana / Gemini，可搜索 / 分类 / 一键复制）。
 > 🆕 **零配置首跑**：本机已登录 Claude Code / Gemini CLI 等？AO 自动探测并直接用，连 API key 都不用配。
+> 🆕 **我的角色 + 提示生成**：「提示生成」页产出的 system prompt 一键存为自建角色（`~/.ao/roles`），组队页「我的」分类直接用；角色卡可 ☆ 收藏常用。
+> 🆕 **多语言角色库**：`npm i agency-agents-ko`（ko / ru / pt-br / id / ar）后，Studio「角色库」下拉一键切换，工作流 `agents_dir` 写包名即可跑。
 
 <p align="center">
   <img src="./docs/screenshots/studio-workflows-zh.png" alt="Studio · 工作流模板：内置模板一键运行" width="800"><br/>
   <em>工作流：内置模板一键运行，也能对比多个模板</em>
 </p>
 
+<p align="center">
+  <img src="./docs/screenshots/studio-role-lib-ko.png" alt="Studio · 角色组队：多语言角色库下拉（图为韩语库）" width="800"><br/>
+  <em>角色组队：☆ 收藏常用、「我的」自建角色，一键切换多语言角色库（图为韩语库）</em>
+</p>
+
 > 启动：`ao web`（本地，密钥只存你自己机器、绝不外传）。也有 [桌面客户端下载](https://github.com/jnMetaCode/agency-orchestrator/releases/latest)（Electron · macOS / Windows / Linux）。
 > 英文界面同样完整 → 见 [English README](./README.en.md)。
 
@@ -74,7 +82,7 @@ ao compose "我是一个程序员，想用AI做自媒体副业，目标月入2
 ==================================================
 ```
 
-**不用写代码，不用写配置，不用选角色。** 一句话 → AI 自动拆解任务 → 从 216 个角色中匹配 → 按 DAG 并行执行 → 输出完整方案。
+**不用写代码，不用写配置，不用选角色。** 一句话 → AI 自动拆解任务 → 从 267 个角色中匹配 → 按 DAG 并行执行 → 输出完整方案。
 
 ### 你能用它做什么
 
@@ -99,12 +107,12 @@ ao compose "设计一个 SaaS 产品的定价策略" --run                   #
 
 | | ChatGPT / Claude | CrewAI / LangGraph | **Agency Orchestrator** |
 |---|--------|-----------|---------------------|
-| 角色数 | 1 个通用 | 自己写 | **216 个专业角色** |
+| 角色数 | 1 个通用 | 自己写 | **267 个专业角色** |
 | 使用方式 | 对话 | 写 Python | **一句话 / YAML** |
 | API key | — | 必须 | **支持 key，也有 7 种免 key 方式** |
 | 依赖 | — | pip + 几十个包 | **npm + 2 个依赖** |
 | 并行 | — | 手动建图 | **DAG 自动检测** |
-| 中文角色 | — | 无 | **216 个** |
+| 中文角色 | — | 无 | **267 个** |
 | 价格 | 订阅制 | 开源 + API 费 | **DeepSeek 甜区极低成本，亦可免 key 起步** |
 
 ## 3 步开始
@@ -119,6 +127,7 @@ npm install -g agency-orchestrator
 > - **桌面客户端**（[下载](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`。
+> - **Docker / NAS 部署**（amd64/arm64）：`docker run -d -p 8088:8088 -v ao-data:/data ghcr.io/jnmetacode/agency-orchestrator:latest`，打开 `http://主机IP:8088`，密钥在页面「供应商」里配（存进挂载卷，重启不丢）。也可用仓库根的 [docker-compose.yml](./docker-compose.yml) 一键起。
 
 ### 第 2 步：一句话跑起来
 
@@ -203,6 +212,7 @@ steps:
   - id: summary
     role: "product/product-manager"
     task: "综合反馈输出结论：\n\n{{tech_report}}\n\n{{design_report}}"
+    acceptance: "1. 明确给出通过/不通过结论  2. 列出必须解决的问题"  # 可选：验收标准，注入 prompt 并作评审依据
     depends_on: [tech_review, design_review]
 ```
 
@@ -221,7 +231,7 @@ analyze ──→ tech_review  ──→ summary
           (并行)
 ```
 
-## 10 种 LLM — 7 种不需要 API key
+## 11 种 LLM — 7 种不需要 API key
 
 **你已经有这些会员了吧？直接就能跑：**
 
@@ -242,10 +252,11 @@ analyze ──→ tech_review  ──→ summary
 | 提供商 | 配置 | 环境变量 |
 |--------|------|---------|
 | DeepSeek | `provider: "deepseek"` | `DEEPSEEK_API_KEY` |
+| 火山引擎（豆包 / Kimi / GLM，赞助商） | `provider: "volcengine"` | `ARK_API_KEY` |
 | Claude API | `provider: "claude"` | `ANTHROPIC_API_KEY` |
 | OpenAI | `provider: "openai"` | `OPENAI_API_KEY` |
 
-**自定义 API（火山引擎、智谱、月之暗面、硅基流动等 OpenAI 兼容 API）：**
+**自定义 API（智谱、月之暗面、硅基流动等 OpenAI 兼容 API）：**
 
 ```bash
 ao init --provider openai --model 模型名 \
@@ -279,7 +290,7 @@ OPENAI_API_KEY=你的key
 
 ```bash
 ao demo                              # 零配置体验多智能体协作
-ao init                              # （可选）复制 216 个中文角色到本地以便编辑
+ao init                              # （可选）复制 267 个中文角色到本地以便编辑
 ao init --lang en                    # （可选）复制 184 个英文角色到本地以便编辑
 ao init --workflow                    # 交互式创建工作流
 ao compose "一句话描述"                # AI 智能编排工作流
@@ -311,14 +322,14 @@ ao serve                             # 启动 MCP Server（供 Claude Code / Cur
 
 ### AI 智能编排（Compose）
 
-一句话描述需求，AI 自动从 216 个角色中选角色、设计 DAG、生成完整 workflow YAML：
+一句话描述需求，AI 自动从 267 个角色中选角色、设计 DAG、生成完整 workflow YAML：
 
 ```bash
 ao compose "PR 代码审查，要覆盖安全和性能"
 ```
 
 AI 会自动：
-1. 从 216 角色中匹配出 Code Reviewer、Security Engineer、Performance Benchmarker
+1. 从 267 角色中匹配出 Code Reviewer、Security Engineer、Performance Benchmarker
 2. 设计 DAG（三路并行 → 汇总）
 3. 生成带 `depends_on`、变量串联的完整 YAML
 4. 保存到 `workflows/` — 直接 `ao run` 就能跑
@@ -343,6 +354,8 @@ 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/roles/<id>.md`（与内置库叠加），工作流里用 `my/<id>` 引用；Studio「角色组队 → 我的」可视化增删。
+> 多语言角色库：`npm i agency-agents-ko`（另有 `pt-br` / `ar` / `id` / `ru`），工作流 `agents_dir: "agency-agents-ko"`，Studio 角色页出现「角色库」下拉。
 >
 > 固定全局目录：设 `AO_HOME=~/.ao`（或任意目录），运行产物 `ao-output`、`compose`/`--team` 生成的工作流都落到那里，不再随执行目录散落（#20）。也可用 `AO_OUTPUT_DIR` / `AO_WORKFLOWS_DIR` 单独指定。不设则维持原行为（写到当前目录）。
 
@@ -581,7 +594,7 @@ ao-output/产品需求评审-2026-03-22/
 
 ```
 你的 AI 会员 ──→ agency-orchestrator ──→ 400+ 个 AI 角色协作 ──→ 高质量输出
-                     │                  (216 中文 + 184 英文)
+                     │                  (267 中文 + 184 英文 + 5 语种)
     ┌────────────────┼────────────────┐
     ▼                ▼                ▼
   14 个 AI 编程工具    CLI 模式         MCP Server
@@ -591,9 +604,10 @@ ao-output/产品需求评审-2026-03-22/
 
 | 项目 | 定位 | 一句话 |
 |------|------|-------|
-| **本项目**（agency-orchestrator） | 🚀 编排引擎 | 一句话 → 216 专家协作，**几分钟出方案**（10 家 LLM / 7 免费） |
-| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) ![](https://img.shields.io/github/stars/jnMetaCode/agency-agents-zh?style=flat&label=⭐) | 🎭 中文角色库 | 216 个**即插即用** AI 专家，含 50 中国原创（小红书 / 抖音 / 飞书 / 钉钉） |
-| [agency-agents](https://github.com/msitarzewski/agency-agents) | 🎭 英文角色库 | 184 个英文 AI 角色 by [@msitarzewski](https://github.com/msitarzewski) |
+| **本项目**（agency-orchestrator） | 🚀 编排引擎 | 一句话 → 267 专家协作，**几分钟出方案**（11 家 LLM / 7 免费） |
+| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) ![](https://img.shields.io/github/stars/jnMetaCode/agency-agents-zh?style=flat&label=⭐) | 🎭 中文角色库 | 267 个**即插即用** AI 专家，含 52 中国原创（小红书 / 抖音 / 飞书 / 钉钉） |
+| [agency-agents](https://github.com/msitarzewski/agency-agents) | 🎭 英文角色库 | 184 个英文 AI 角色（by [@msitarzewski](https://github.com/msitarzewski)，MIT）——**已随 npm 包内置**，英文任务 `ao compose` 自动启用，无需单独安装 |
+| [ko](https://github.com/jnMetaCode/agency-agents-ko) · [ru](https://github.com/jnMetaCode/agency-agents-ru) · [pt-BR](https://github.com/jnMetaCode/agency-agents-pt-BR) · [id](https://github.com/jnMetaCode/agency-agents-id) · [ar](https://github.com/jnMetaCode/agency-agents-ar) | 🌍 多语言角色库 | 各 187 个（184 上游翻译 + 3 本地市场原创），`npm i agency-agents-<lang>` 后 Studio「角色库」下拉切换 |
 | [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） |

package/agency-agents/specialized/zk-steward.md

@@ -1,6 +1,6 @@
 ---
 name: ZK Steward
-description: Knowledge-base steward in the spirit of Niklas Luhmann's Zettelkasten. Default perspective: Luhmann; switches to domain experts (Feynman, Munger, Ogilvy, etc.) by task. Enforces atomic notes, connectivity, and validation loops. Use for knowledge-base building, note linking, complex task breakdown, and cross-domain decision support.
+description: "Knowledge-base steward in the spirit of Niklas Luhmann's Zettelkasten. Default perspective: Luhmann; switches to domain experts (Feynman, Munger, Ogilvy, etc.) by task. Enforces atomic notes, connectivity, and validation loops. Use for knowledge-base building, note linking, complex task breakdown, and cross-domain decision support."
 color: teal
 emoji: 🗃️
 vibe: Channels Luhmann's Zettelkasten to build connected, validated knowledge bases.

package/dist/agents/loader.d.ts

@@ -1,14 +1,29 @@
 import type { AgentDefinition } from '../types.js';
+/**
+ * 用户自建角色的固定分类前缀：`my/<id>` 一律解析到用户角色目录。
+ * 与 AO_AGENTS_DIR（整体替换内置库）不同，用户角色目录是「叠加」——
+ * 内置 267 个角色照常可用，自己攒的专家放 ~/.ao/roles，CLI 与 Studio 共用。
+ */
+export declare const USER_ROLE_CATEGORY = "my";
+/** 用户角色目录：AO_USER_ROLES_DIR 可覆盖，默认 ~/.ao/roles（与 ~/.ao/teams、~/.ao/prompts 同体系）。 */
+export declare function userRolesDir(): string;
 /**
  * 加载指定角色的定义
  * @param agentsDir agency-agents 的 agents 目录路径
  * @param rolePath 角色路径，如 "engineering/engineering-sre"
  */
 export declare function loadAgent(agentsDir: string, rolePath: string): AgentDefinition;
+/**
+ * 列出用户角色目录（~/.ao/roles）里的自建角色，rolePath 统一为 "my/<id>"。
+ * 目录不存在返回空数组；只认带 name frontmatter 的 .md（与内置库同规则）。
+ */
+export declare function listUserAgents(): AgentDefinition[];
 /**
  * 列出所有可用角色
+ * @param includeUser true 时叠加用户角色目录（~/.ao/roles）的 my/* 角色；
+ *                    默认 false 保持纯目录语义（安装计数、测试 fixture 等不受用户机器状态影响）
  */
-export declare function listAgents(agentsDir: string): AgentDefinition[];
+export declare function listAgents(agentsDir: string, includeUser?: boolean): AgentDefinition[];
 /**
  * 轻量列出所有角色路径（如 "engineering/engineering-sre"），不解析文件内容。
  * 用于 validate 报错时给"你是不是想用 X"建议，避免 listAgents 全量解析的开销。

package/dist/agents/loader.js

@@ -12,8 +12,21 @@
  */
 import { readFileSync, existsSync, readdirSync } from 'node:fs';
 import { join, resolve, relative, sep } from 'node:path';
+import { homedir } from 'node:os';
 // 枚举角色时跳过的非角色目录
 const SKIP_DIRS = new Set(['node_modules', 'scripts', 'integrations', 'examples']);
+/**
+ * 用户自建角色的固定分类前缀：`my/<id>` 一律解析到用户角色目录。
+ * 与 AO_AGENTS_DIR（整体替换内置库）不同，用户角色目录是「叠加」——
+ * 内置 267 个角色照常可用，自己攒的专家放 ~/.ao/roles，CLI 与 Studio 共用。
+ */
+export const USER_ROLE_CATEGORY = 'my';
+/** 用户角色目录：AO_USER_ROLES_DIR 可覆盖，默认 ~/.ao/roles（与 ~/.ao/teams、~/.ao/prompts 同体系）。 */
+export function userRolesDir() {
+    return process.env.AO_USER_ROLES_DIR
+        ? resolve(process.env.AO_USER_ROLES_DIR)
+        : join(homedir(), '.ao', 'roles');
+}
 /** 一个 .md 是否是「角色」：必须有带 name 的 frontmatter（排除 README / 攻略 / 模板等文档）。 */
 function isAgentFile(fullPath) {
     try {
@@ -63,11 +76,46 @@ export function loadAgent(agentsDir, rolePath) {
         throw new Error(`角色路径越界: ${rolePath}`);
     }
     if (!existsSync(fullPath)) {
+        // `my/<id>` 兜底到用户角色目录（agents_dir 里真有 my/ 子目录时以 agents_dir 优先）
+        if (rolePath.startsWith(`${USER_ROLE_CATEGORY}/`)) {
+            const userDir = userRolesDir();
+            const userPath = resolve(userDir, `${rolePath.slice(USER_ROLE_CATEGORY.length + 1)}.md`);
+            if (userPath.startsWith(userDir + sep) && existsSync(userPath)) {
+                return parseAgentFile(readFileSync(userPath, 'utf-8'), rolePath);
+            }
+        }
         throw new Error(`角色文件不存在: ${fullPath}\n请确认 agents_dir 和 role 路径正确`);
     }
     const content = readFileSync(fullPath, 'utf-8');
     return parseAgentFile(content, rolePath);
 }
+/**
+ * 列出用户角色目录（~/.ao/roles）里的自建角色，rolePath 统一为 "my/<id>"。
+ * 目录不存在返回空数组；只认带 name frontmatter 的 .md（与内置库同规则）。
+ */
+export function listUserAgents() {
+    const dir = userRolesDir();
+    if (!existsSync(dir))
+        return [];
+    const agents = [];
+    for (const f of readdirSync(dir)) {
+        if (!f.endsWith('.md'))
+            continue;
+        const full = join(dir, f);
+        if (!isAgentFile(full))
+            continue;
+        try {
+            const rolePath = `${USER_ROLE_CATEGORY}/${f.replace(/\.md$/, '')}`;
+            const agent = parseAgentFile(readFileSync(full, 'utf-8'), rolePath);
+            agent.rolePath = rolePath;
+            agents.push(agent);
+        }
+        catch {
+            // 跳过无法解析的文件
+        }
+    }
+    return agents;
+}
 /**
  * 解析 agent .md 文件内容
  */
@@ -103,8 +151,10 @@ function parseAgentFile(content, rolePath) {
 }
 /**
  * 列出所有可用角色
+ * @param includeUser true 时叠加用户角色目录（~/.ao/roles）的 my/* 角色；
+ *                    默认 false 保持纯目录语义（安装计数、测试 fixture 等不受用户机器状态影响）
  */
-export function listAgents(agentsDir) {
+export function listAgents(agentsDir, includeUser = false) {
     const dir = resolve(agentsDir);
     if (!existsSync(dir)) {
         throw new Error(`agents 目录不存在: ${dir}`);
@@ -121,6 +171,14 @@ export function listAgents(agentsDir) {
             // 跳过无法解析的文件
         }
     }
+    if (includeUser) {
+        // agents_dir 里真有 my/ 子目录时以 agents_dir 优先（与 loadAgent 解析次序一致）
+        const seen = new Set(agents.map(a => a.rolePath));
+        for (const ua of listUserAgents()) {
+            if (!seen.has(ua.rolePath))
+                agents.push(ua);
+        }
+    }
     return agents;
 }
 /**

package/dist/cli/compose.d.ts

@@ -36,6 +36,7 @@ export declare function buildComposeSystemPrompt(catalog: string, options?: {
     model?: string;
     lang?: 'zh' | 'en';
     timeoutMs?: number;
+    agentsDirName?: string;
 }): string;
 /**
  * 构建 user prompt
@@ -69,6 +70,8 @@ export declare function composeWorkflow(options: {
     saveDir?: string;
     /** R3.2 预算模式：把「轻活」步骤自动降到便宜档，省钱不掉关键质量（默认关，零回归） */
     budget?: boolean;
+    /** 生成 YAML 里 agents_dir 的名字（多语言角色库如 "agency-agents-ko"）；缺省按 lang 用 zh/en 内置库名 */
+    agentsDirName?: string;
 }): Promise<{
     yaml: string;
     savedPath: string;

package/dist/cli/compose.js

@@ -76,7 +76,8 @@ export function applyBudgetTiering(yamlText, provider) {
  * 从 agents 目录构建精简的角色目录
  */
 export function buildRoleCatalog(agentsDir) {
-    const agents = listAgents(agentsDir);
+    // 叠加用户自建角色（~/.ao/roles 的 my/*）：手动组队可锁定自建专家，自动组队也能挑到
+    const agents = listAgents(agentsDir, true);
     return agents
         .filter(a => a.rolePath)
         .map(a => ({
@@ -171,7 +172,7 @@ Output a complete YAML code block in this format:
 name: "Workflow Name"
 description: "One-line description"
 
-agents_dir: "agency-agents"
+agents_dir: "${options?.agentsDirName || 'agency-agents'}"
 
 llm:
   provider: ${provider}
@@ -193,12 +194,20 @@ ${autoRun ? '      Include specific information from the user\'s description' :
       Use {{previous_output}} to reference upstream step outputs
     output: output_variable_name
     depends_on: [upstream_step_id]  # Only add when there's a dependency
+    acceptance: |  # Optional: verifiable conditions the output must satisfy (strongly recommended on the final step)
+      1. First checkable condition...
+      2. Second checkable condition...
 
   # When you need to ask the user something mid-run, use a human_input step (no role, actually pauses for input):
   - id: ask_step_id
     type: human_input
     prompt: "The specific question to ask the user, can reference {{variable_name}} from earlier steps"
     output: user_answer_variable  # the user's answer is injected downstream as this variable
+
+  # For high-stakes decisions (finance/medical/legal/spending real money), insert an approval gate (pauses until the user signs off):
+  - id: approve_step_id
+    type: approval
+    prompt: "State clearly what the user is approving, can reference {{variables}}"
 \`\`\`
 
 ## Design Principles
@@ -210,6 +219,8 @@ ${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}
 - **Use human_input when the user needs to clarify something — don't have a role "ask" in its task**: if the task genuinely can't proceed without more info from the user (personal preference, choosing between options, a specific detail not in inputs — classic case: registration/enrollment-type requests where you must ask the user's specifics partway through), insert a \`type: human_input\` step to ask them, and feed the answer downstream as its output variable. Writing "ask the user X" inside a regular role step's task does NOT work — the engine won't actually pause, the model will just make up an answer
+- **Acceptance criteria**: give key steps — at minimum the FINAL deliverable step — an \`acceptance:\` field with 2-5 verifiable conditions the output must satisfy. Concrete and checkable ("contains X/Y/Z sections", "every recommendation states its risk"), never vague ("high quality"). It is injected into the step's prompt AND actually enforced: after the step runs, the engine checks the output against each item, and any unmet item triggers one automatic rework round — so every item must be objectively machine-checkable from the output text alone
+- **High-risk tasks need an approval gate**: for finance/investment, medical, legal, or anything spending real money / hard to reverse — insert a \`type: approval\` step before the final recommendation/execution step, so the user signs off before proceeding
 - **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." (If you genuinely need to ask the user something, use the human_input step above instead — not in the final step)
 
@@ -275,7 +286,7 @@ ${autoRun ? inputsSection : ''}
 name: "工作流名称"
 description: "一句话描述"
 
-agents_dir: "agency-agents-zh"
+agents_dir: "${options?.agentsDirName || 'agency-agents-zh'}"
 
 llm:
   provider: ${provider}
@@ -297,12 +308,20 @@ ${autoRun ? '      直接包含用户需求中的具体信息' : '      使用 {
       使用 {{previous_output}} 引用上游步骤的输出
     output: output_variable_name
     depends_on: [upstream_step_id]  # 仅在有依赖时添加
+    acceptance: |  # 可选：产出必须满足的可核对验收条件（最终交付步强烈建议写）
+      1. 第一条可核对的条件…
+      2. 第二条可核对的条件…
 
   # 需要向用户询问/确认信息时，用 human_input 类型的步骤（无 role，运行到这一步会真的暂停等用户输入）：
   - id: ask_step_id
     type: human_input
     prompt: "向用户提的具体问题，可用 {{variable_name}} 引用之前的变量"
     output: user_answer_variable  # 用户的回答会作为这个变量注入下游 task
+
+  # 高风险决策（金融/医疗/法律/花真金白银）前插入 approval 闸门（暂停等用户签字放行）：
+  - id: approve_step_id
+    type: approval
+    prompt: "写清楚用户在批准什么，可引用 {{变量}}"
 \`\`\`
 
 ## 设计原则
@@ -314,6 +333,8 @@ ${autoRun ? '      直接包含用户需求中的具体信息' : '      使用 {
 - **任务详细**：task 描述要具体，告诉角色要做什么、输出什么格式
 ${inputsDesignPrinciple}
 - **需要用户澄清时用 human_input，不要指望角色在 task 里"提问"**：如果任务本质上需要用户提供额外信息才能继续（如个人偏好、多个方案里选一个、inputs 里没给的具体细节——典型例子是报名/选课/选方案类需求，中途必须问用户具体情况），插入一个 \`type: human_input\` 的步骤向用户提问，把回答作为 output 变量给下游用。普通 role 步骤的 task 里写"请问用户 XXX"是无效的——引擎不会暂停等回答，模型只会自己编一个答案
+- **验收标准**：给关键步骤——至少是最终交付步——写 \`acceptance:\` 字段，列 2-5 条产出必须满足的可核对条件。要具体可查（"包含 X/Y/Z 三节""每条建议都标注风险"），不要空话（"高质量"）。它不只注入该步 prompt——步骤跑完后引擎会**逐条真核验**，未过自动返工一轮。所以每一条都必须是仅凭产出文本就能客观判定的
+- **高风险任务要加签字闸门**：涉及金融/投资、医疗、法律，或花真金白银、难以撤销的操作——在最终建议/执行步骤之前插入 \`type: approval\` 节点，让用户签字放行后才继续（重大决策必须老板拍板）
 - **最终成品**：最后一个步骤必须输出用户想要的最终成品（如完整文章、完整报告），而不是审查意见或修改建议。如果有审校步骤，审校步骤应该直接输出修改后的定稿，而不是"修改建议列表"
 - **干净的最终产出（重要）**：最后一个步骤的 \`task\` 结尾必须显式要求"只输出成品本身"——不要开场白/寒暄、不要"我改了什么/复盘/修改说明"、不要排版备注小节、不要向用户提问或请其拍板、不要建议运行 \`ao\` 或其它命令、不要"要我继续吗"之类收尾。请在该 step 的 task 末尾追加一行类似：「⚠️ 只输出最终成品本身：不要开场白、不要复盘或说明、不要向用户提问、不要建议任何命令或后续动作。」（需要问用户时用上面的 human_input 步骤，不要在最终步骤里问）
 
@@ -414,6 +435,7 @@ export async function composeWorkflow(options) {
         model: options.llmConfig.model,
         lang,
         timeoutMs: options.timeoutMs,
+        agentsDirName: options.agentsDirName,
     });
     let userPrompt = buildComposeUserPrompt(description, lang);
     if (options.pinnedRoles?.length) {