agency-orchestrator 0.11.0 → 0.12.0

package/README.en.md

@@ -11,13 +11,11 @@
 [![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 · 11 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.
 
@@ -32,12 +30,19 @@
 
 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-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">
   <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 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.
 
 ---
 
@@ -72,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
 
@@ -97,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** |
@@ -262,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
@@ -300,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`
@@ -594,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
@@ -604,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

@@ -11,11 +11,9 @@
 [![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 零代码 · 11 种大模型 · 支持 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** — 帮助更多人发现这个项目。
 
@@ -35,12 +33,19 @@
 > 🆕 **可视化画布**：工作流可在画布上拖拽节点 / 连线（自动防环）/ 改任务·角色 / 保存，运行时节点按状态实时点亮。
 > 🆕 **创意库**：内置图像生成提示词库（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)。
 
@@ -77,7 +82,7 @@ ao compose "我是一个程序员，想用AI做自媒体副业，目标月入2
 ==================================================
 ```
 
-**不用写代码，不用写配置，不用选角色。** 一句话 → AI 自动拆解任务 → 从 216 个角色中匹配 → 按 DAG 并行执行 → 输出完整方案。
+**不用写代码，不用写配置，不用选角色。** 一句话 → AI 自动拆解任务 → 从 267 个角色中匹配 → 按 DAG 并行执行 → 输出完整方案。
 
 ### 你能用它做什么
 
@@ -102,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 步开始
@@ -122,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 步：一句话跑起来
 
@@ -284,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 智能编排工作流
@@ -316,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` 就能跑
@@ -348,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` 单独指定。不设则维持原行为（写到当前目录）。
 
@@ -586,7 +594,7 @@ ao-output/产品需求评审-2026-03-22/
 
 ```
 你的 AI 会员 ──→ agency-orchestrator ──→ 400+ 个 AI 角色协作 ──→ 高质量输出
-                     │                  (216 中文 + 184 英文)
+                     │                  (267 中文 + 184 英文 + 5 语种)
     ┌────────────────┼────────────────┐
     ▼                ▼                ▼
   14 个 AI 编程工具    CLI 模式         MCP Server
@@ -596,9 +604,10 @@ ao-output/产品需求评审-2026-03-22/
 
 | 项目 | 定位 | 一句话 |
 |------|------|-------|
-| **本项目**（agency-orchestrator） | 🚀 编排引擎 | 一句话 → 216 专家协作，**几分钟出方案**（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=⭐) | 🎭 中文角色库 | 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}
@@ -285,7 +286,7 @@ ${autoRun ? inputsSection : ''}
 name: "工作流名称"
 description: "一句话描述"
 
-agents_dir: "agency-agents-zh"
+agents_dir: "${options?.agentsDirName || 'agency-agents-zh'}"
 
 llm:
   provider: ${provider}
@@ -434,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) {

package/dist/cli.js

@@ -1328,7 +1328,7 @@ function handleRoles() {
     const keyword = getArgValue('--search')
         || (args[1] && !args[1].startsWith('-') ? args[1] : '');
     try {
-        const all = listAgents(resolve(agentsDir));
+        const all = listAgents(resolve(agentsDir), true);
         const agents = keyword ? filterAgentsByKeyword(all, keyword) : all;
         if (keyword) {
             console.log(`\n  搜索 "${keyword}"：匹配 ${agents.length} / ${all.length} 个角色 (${agentsDir})\n`);

package/dist/connectors/claude.js

@@ -22,6 +22,8 @@ export class ClaudeConnector {
         // 这里把它作为单请求 timeout 传给 SDK。timeout=0/未设（不限时）→ 不传，退回 SDK 默认。
         const requestTimeout = config.timeout && config.timeout > 0 ? config.timeout : undefined;
         const response = await this.client.messages.create({
+            // 供应商专有参数（如 thinking 预算）铺底，核心字段随后覆盖
+            ...(config.params ?? {}),
             model: config.model,
             max_tokens: config.max_tokens || 4096,
             ...(config.temperature !== undefined ? { temperature: config.temperature } : {}),

package/dist/connectors/ollama.js

@@ -22,6 +22,8 @@ export class OllamaConnector {
                     options: {
                         num_predict: numPredict,
                         num_ctx: numCtx,
+                        // 供应商专有参数并入 ollama options（top_k/repeat_penalty 等）
+                        ...(config.params ?? {}),
                         ...(config.temperature !== undefined ? { temperature: config.temperature } : {}),
                     },
                 }),

package/dist/connectors/openai-compatible.js

@@ -88,6 +88,9 @@ export class OpenAICompatibleConnector {
                         },
                         signal: controller.signal,
                         body: JSON.stringify({
+                            // 供应商专有参数（thinking/reasoning 档位等）先铺底，核心字段随后覆盖——
+                            // params 永远不能改掉 model/stream/messages，避免把流式解析搞挂
+                            ...(config.params ?? {}),
                             model: config.model,
                             [this.tokenParam]: config.max_tokens || 4096,
                             ...(config.temperature !== undefined ? { temperature: config.temperature } : {}),

package/dist/i18n.js

@@ -205,6 +205,8 @@ const dict = {
     upgrade [--check]                 自我升级到最新版（--check 只检查不安装）
 
   自带私有角色：设 AO_AGENTS_DIR=/你的角色目录，run/compose/roles/web 全局生效。
+  自建角色（叠加）：放 ~/.ao/roles/<id>.md（或设 AO_USER_ROLES_DIR），工作流里用 my/<id> 引用，
+              与内置角色库共存；Studio「角色组队 → 我的」可视化增删。
   固定全局目录：设 AO_HOME=~/.ao（或任意目录），产物 ao-output / 生成的工作流都落到那里，
               不再散在执行目录；也可单独用 AO_OUTPUT_DIR / AO_WORKFLOWS_DIR 指定。
 
@@ -272,6 +274,8 @@ const dict = {
     upgrade [--check]                 Self-update to the latest version (--check: check only)
 
   Bring your own roles: set AO_AGENTS_DIR=/your/roles/dir — applies to run/compose/roles/web.
+  Your own roles (additive): drop ~/.ao/roles/<id>.md (or set AO_USER_ROLES_DIR) and reference
+              them as my/<id> — they coexist with the built-in library; manage visually in Studio.
   Fixed global dir: set AO_HOME=~/.ao (or any dir) so outputs / generated workflows land there
               instead of scattering across CWD; or set AO_OUTPUT_DIR / AO_WORKFLOWS_DIR individually.
 

package/dist/index.d.ts

@@ -9,7 +9,7 @@ export { buildDAG, formatDAG } from './core/dag.js';
 export { executeDAG } from './core/executor.js';
 export { evaluateCondition } from './core/condition.js';
 export { renderTemplate, extractVariables } from './core/template.js';
-export { loadAgent, listAgents } from './agents/loader.js';
+export { loadAgent, listAgents, listUserAgents, userRolesDir, USER_ROLE_CATEGORY } from './agents/loader.js';
 export { ClaudeConnector } from './connectors/claude.js';
 export { OllamaConnector } from './connectors/ollama.js';
 export { OpenAICompatibleConnector } from './connectors/openai-compatible.js';

package/dist/index.js

@@ -9,7 +9,7 @@ export { buildDAG, formatDAG } from './core/dag.js';
 export { executeDAG } from './core/executor.js';
 export { evaluateCondition } from './core/condition.js';
 export { renderTemplate, extractVariables } from './core/template.js';
-export { loadAgent, listAgents } from './agents/loader.js';
+export { loadAgent, listAgents, listUserAgents, userRolesDir, USER_ROLE_CATEGORY } from './agents/loader.js';
 export { ClaudeConnector } from './connectors/claude.js';
 export { OllamaConnector } from './connectors/ollama.js';
 export { OpenAICompatibleConnector } from './connectors/openai-compatible.js';

package/dist/mcp/server.js

@@ -266,7 +266,7 @@ export async function startServer(verbose = false) {
     }, async ({ agents_dir }) => {
         try {
             const agentsDir = findAgentsDir(agents_dir);
-            const agents = listAgents(agentsDir);
+            const agents = listAgents(agentsDir, true);
             const lines = agents.map(a => {
                 const emoji = a.emoji || ' ';
                 return `${emoji} ${a.name} — ${a.description || '(无描述)'}`;

package/dist/types.d.ts

@@ -17,6 +17,7 @@ export interface LLMConfig {
     agent?: string;
     max_tokens?: number;
     temperature?: number;
+    params?: Record<string, unknown>;
     timeout?: number;
     retry?: number;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agency-orchestrator",
-  "version": "0.11.0",
-  "description": "Multi-agent YAML workflow engine — 216 AI roles, auto DAG parallelism, zero code. One sentence → multiple AI roles collaborate → complete plan in minutes. 11 LLM providers, 7 need no API key.",
+  "version": "0.12.0",
+  "description": "Multi-agent YAML workflow engine — 267 CN + 184 EN + 5 more language libraries of AI roles, auto DAG parallelism, zero code. One sentence → multiple AI roles collaborate → complete plan in minutes. 11 LLM providers, 7 need no API key.",
   "keywords": [
     "multi-agent",
     "ai-agents",
@@ -90,7 +90,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.52.0",
     "@modelcontextprotocol/sdk": "^1.28.0",
-    "agency-agents-zh": "^1.2.2",
+    "agency-agents-zh": "^1.2.7",
     "html-to-docx": "^1.8.0",
     "js-yaml": "^4.1.0",
     "marked": "^18.0.5",
@@ -101,6 +101,11 @@
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.0.0",
+    "agency-agents-ar": "^1.0.1",
+    "agency-agents-id": "^1.0.1",
+    "agency-agents-ko": "^1.0.1",
+    "agency-agents-pt-br": "^1.0.1",
+    "agency-agents-ru": "^1.0.1",
     "typescript": "^5.7.0"
   },
   "optionalDependencies": {