MCP工具

第 1 步：安装

npm install -g agency-orchestrator

装 CLI 还是桌面端？ - 桌面客户端（下载）自带引擎与 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 一键起。 - 把 Studio 暴露到内网时上把锁：启动前设 AO_WEB_TOKEN=<一串口令>，然后用 http://<地址>:8088/?token=<口令> 打开一次（令牌存进该标签页、随即从地址栏抹掉）。不设 = 现在的行为不变，但监听在非回环地址时启动会提醒你——同一网络内任何人都能用你保存的 key 跑任务。 - 通过域名 / 反向代理访问网页版：本机启动的 Studio 只接受 localhost / 127.0.0.1 的请求（防 DNS 重绑定，别的网页借此偷不到你存的 key）。要用自己的域名访问时，启动前设 AO_ALLOWED_HOSTS=studio.example.com（多个用逗号分隔）。Docker 镜像监听 0.0.0.0、没有登录鉴权——只放在可信内网，别直接暴露到公网。

第 3 步：用内置模板或在 AI 编程工具中使用

```bash

更多真实演示

``` $ ao compose "帮我分析抖音短视频赛道的创业机会" --run

工作流: 抖音短视频赛道创业机会分析与商业方案制定 步骤数: 6 | 并发: 2 | 模型: deepseek-chat 参与者: 👔 老板 | 📊 市场调研员 | 🔍 用户研究员 | 🧭 产品经理 | 📣 营销主管 | 💰 财务总监 ──────────────────────────────────────────────────

✅ 👔 老板 12.7s → 战略方向与目标用户定位 ✅ 📊 市场调研员 45.2s → 7亿日活用户数据、竞争格局分析 ✅ 🔍 用户研究员 38.1s → 用户画像、痛点挖掘、付费意愿 ✅ 🧭 产品经理 41.3s → MVP功能清单、内容矩阵、变现路径 ✅ 📣 营销主管 35.6s → 冷启动方案、投放策略、用户漏斗 ✅ 💰 财务总监 28.4s → 150万启动、首年400万收入、盈亏平衡分析

让整队人接新活（自动用这几个角色重新设计步骤并运行）

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/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 单独指定。不设则维持原行为（写到当前目录）。

第一轮：正常运行

ao run workflows/一人公司全员大会.yaml -i idea="用AI帮小商家做短视频"

按天汇总：运行数、AI 完成步骤、人工节点、手记、人工耗时、token → AI 自主率（markdown，可直接贴进复盘）

ao ledger report --since 2026-09-22 --out 复盘-账本.md ```

工作流里的 approval / human_input 节点自动计为人工，不用手记；--resume / --feedback 复用的旧步骤不重复计入。账本默认读命令行的运行目录（ao-output）；网页 Studio 的运行记录在 Studio 数据目录下的 ao-output，用 ao ledger report --output <该目录> 指过去。AI 自主率 = AI 完成步骤 ÷（AI 完成步骤 + 人工节点 + 手记介入），按次数算、不按工作量，不折算金额——口径随报告一起输出，不藏。

环境变量

只列用户会用到的；测试 / 内部用的（AO_WEB_INPUT、AO_NODE、AO_SSY_CATALOG_HOST …）不在此列。

用你已有的 Claude 会员（无需 API key）

ao compose "帮我分析做一个AI记账工具的可行性" --run --provider claude-code

20+ 家 API — 10 种不需要 API key

统计口径（以源码为准）：免 key = 复用已登录订阅的 9 个编码 CLI（Claude Code / Antigravity / Copilot / Codex / OpenClaw / Hermes / CodeBuddy / Cline / OpenCode）+ 本地 Ollama；不含已停服的 Gemini CLI；DeepSeek Harness 需要 DEEPSEEK_API_KEY，不计入免 key。API = 下方官方直连 + 赞助商 / 聚合中转平台（见 src/connectors/api-providers.ts），另支持任意 OpenAI 兼容接口。

你已经有这些会员了吧？直接就能跑：

💡 用 AWS Bedrock / Google Vertex 跑 Claude Code 的（没有 API key，走云凭证）：照样用 provider: "claude-code"， 不用额外配置 —— AO 调的就是你本机的 claude 命令，CLAUDE_CODE_USE_BEDROCK / AWS_* 等环境变量会原样传给它。 只要 claude -p "你好" 能跑通就行。两个注意点： ① AO 默认在空临时目录里启动 claude（避免你项目的 CLAUDE.md、记忆混进角色输出），所以这些配置要放在全局 —— shell 环境变量或 ~/.claude/settings.json，别只放在某个项目的 .claude/settings.json 里； ② model 留空或写 claude-code 即可沿用你在 Claude Code 里配的模型；要指定就填 Bedrock/Vertex 的模型 ID。

⚠️ 模型能力决定多智能体的价值：我们用质量评测验证过（见 EVAL_FINDINGS.md，网页版：中文 / English）——DeepSeek 这一档（够强又不贵）上，多智能体产出明显优于单次 prompt；但本地小模型（如 llama3 8B 级）能力不足时，多角色交接反而会放大漂移、产出不如单次。追求质量请用 DeepSeek/Claude/Gemini 等有能力的模型；本地 Ollama 建议用 70B+ 模型。

也支持传统 API key（追求质量推荐 DeepSeek，性价比甜区）：

需要代理才能访问的官方 API（OpenAI / Gemini / xAI / Claude 等）：AO 会读 HTTPS_PROXY / HTTP_PROXY / ALL_PROXY 自动走代理—— Node 的 fetch 默认不读这些变量，这正是"curl 能通、AO 连不上"的头号原因，AO 替你接上了。 本机地址（localhost / 127.0.0.1 等）永远直连，不会被绕进代理，所以 Ollama、Studio 自身不受影响； 你自己写的 NO_PROXY 会被保留。想彻底关掉这层接管：AO_NO_PROXY=1。

这几家都不预设默认模型（各家模型编码互不通用，写死一个就是给你埋一个"跑起来才发现模型不存在"）： 在 YAML 里写 model:，或在 Studio 供应商页配好 key 后点「获取模型列表」拉真实全量。 Gemini 的 key 变量名特意不叫 GEMINI_API_KEY——那个名字被 gemini-cli 占着，共用会把你本机的 CLI 一起改道。

自定义 API（智谱、月之暗面、硅基流动等 OpenAI 兼容 API）：

ao init --provider openai --model 模型名 \
  --base-url https://你的API地址/v1 \
  --api-key 你的key

或手动编辑 .env：

AO_PROVIDER=openai
AO_MODEL=模型名
OPENAI_BASE_URL=https://你的API地址/v1
OPENAI_API_KEY=你的key

.env 读两处，优先级：shell 环境变量 > 当前目录 ./.env（项目级） > ~/.ao/.env（用户级）。 配一次就想在任何目录下都生效，写 ~/.ao/.env（和 ~/.ao/teams、~/.ao/prompts 同一个地方）。

常见示例：

⚠️ 注意：这些平台请使用 provider: "openai"，不要用 provider: "ollama"。Ollama 仅用于本地模型，不发送 API Key。

💡 网页 Studio 里更简单：「供应商」面板支持直接添加自定义供应商（任意 OpenAI 兼容 endpoint，带 SiliconFlow / OpenRouter / 火山方舟 / 智谱 / Kimi 等常见预设，点一下自动填 base_url），加完即可在顶部下拉切换使用。Claude Code / Gemini CLI / Codex 卡片还支持配置第三方中转（填中转商的 base_url + token，跳过官方账号登录）。

CLI 命令

ao demo                              # 零配置体验多智能体协作
ao init                              # （可选）复制 276 个中文角色到本地以便编辑
ao init --lang en                    # （可选）复制 191 个英文角色到本地以便编辑
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）
ao explain <workflow.yaml>            # 用自然语言解释执行计划
ao roles                             # 列出所有角色
ao serve                             # 启动 MCP Server（供 Claude Code / Cursor 调用）

Skills（给步骤挂方法论）

角色决定「谁来做」，skill 决定「怎么做」。给工作流某一步挂一个 skill（流程剧本），它的方法论会注入该步——比如让代码审查步骤遵循结构化审查法、让实现步骤走 TDD：

steps:
  - id: review
    role: "engineering/engineering-code-reviewer"
    skill: "chinese-code-review"     # 单个；或 skills: ["test-driven-development", ...]
    task: "审查这段代码 {{code}}"

ao skills                      # 列出全部可用 skill
ao skills test-driven-development   # 看某个 skill 的方法论

skill 内容直接用开源的 superpowers-zh（MIT，20 个,已作为依赖,零配置）；也可设 AO_SKILLS_DIR=/你的skill目录 挂自己的。

编程 API

import { run } from 'agency-orchestrator';

const result = await run('workflow.yaml', {
  prd_content: '你的 PRD 内容...',
});

console.log(result.success);     // true/false
console.log(result.totalTokens); // { input: 1234, output: 5678 }

从一个跑得好的工作流抽出阵容，存成团队

ao team save workflows/tech-blog.yaml --name 技术博客组

工作流之外的人工操作，手记一条（原因四选一：unsupported / quality / judgment / external）

ao ledger add "人工部署到服务器" --reason unsupported --minutes 20 --run last

工作流

内置工作流模板（精选；全部 57 个中文模板见 `workflows/`，Studio「工作流模板」按类目列出）