agency-orchestrator 0.3.2 → 0.4.2

package/README.md

@@ -1,107 +1,144 @@
 # Agency Orchestrator
 
-**English** | [中文](./README.zh-CN.md)
+**中文** | [English](./README.en.md)
 
-> **Multi-agent workflows in YAML — 186 ready-to-use AI roles, zero code required**
+> **你已经为 AI 付了月费。为什么跑个工作流还要再掏 API key 的钱？**
 
 [![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)
 
+**186 个专业 AI 角色 · YAML 零代码编排 · 有会员就能跑 · 免 API key**
+
+```
+Claude Max ✓  ChatGPT Plus ✓  GitHub Copilot ✓  Google 账号（免费）✓  Ollama ✓
+```
+
+> 觉得有用？请点个 **Star** — 帮助更多人发现这个项目。
+
 ---
 
-## What Is This?
+## 为什么需要 Agency Orchestrator
 
-A lightweight engine that orchestrates multiple AI agents to collaborate on complex tasks. You define the workflow in YAML — which roles, what tasks, what order — and the engine handles parallel execution, variable passing, retries, and output management.
+**你遇到过这些问题吗？**
 
-**No Python. No framework boilerplate. Just YAML.**
+- 想让多个 AI 角色协作，但 CrewAI/LangGraph 要写 Python，还要花时间定义每个角色
+- 装好了框架，发现**还要去申请 API key、充值、管额度**
+- 你明明已经有 Claude Max / ChatGPT Plus / Copilot 会员了，却用不上
+
+**Agency Orchestrator 的答案：**
+
+写一个 YAML 文件 → 186 个专业角色自动协作 → 用你**已有的会员**直接跑。
+
+> **行业首创：全球所有多智能体框架（CrewAI / LangGraph / AutoGen / Dify / n8n / Agency Swarm / MetaGPT / Google ADK / OpenAI Agents SDK）都要求 API key。只有 Agency Orchestrator 让你带着订阅来用。**
+
+### 30 秒对比
+
+```python
+# CrewAI: ~50 行 Python，角色从零写，必须有 API key
+researcher = Agent(role="PM", goal="...", backstory="...(你自己写)...")
+task = Task(description="...", agent=researcher)
+crew = Crew(agents=[researcher], tasks=[task])
+crew.kickoff()
+```
 
 ```yaml
+# Agency Orchestrator: 10 行 YAML，186 个角色开箱即用，无需 API key
 steps:
   - id: analyze
-    role: "product/product-manager"          # 186 built-in roles
-    task: "Analyze this PRD:\n\n{{prd_content}}"
-    output: requirements
-
-  - id: tech_review
-    role: "engineering/engineering-software-architect"
-    task: "Evaluate feasibility:\n\n{{requirements}}"
-    depends_on: [analyze]                    # auto DAG detection
+    role: "product/product-manager"   # 现成角色，专业 prompt 已写好
+    task: "分析这个 PRD：{{prd_content}}"
 ```
 
-### vs CrewAI / LangGraph
+| | CrewAI | LangGraph | AutoGen | **Agency Orchestrator** |
+|---|--------|-----------|---------|---------------------|
+| 语言 | Python | Python | Python | **YAML（零代码）** |
+| 角色 | 自己写 | 自己写 | 自己写 | **186 个现成** |
+| API key | 必须 | 必须 | 必须 | **6 种免 API key** |
+| 依赖 | pip + LiteLLM + 几十个包 | pip + LangChain | pip + AutoGen | **npm + 2 个依赖** |
+| 中文角色 | 无 | 无 | 无 | **186 个（44 个中国原创）** |
+| 并行 | Manager 模式 | 手动建图 | 手动 | **DAG 自动检测** |
+| 价格 | 开源 + $25-99/月云版 | 开源 | 开源 | **完全免费** |
 
-| | CrewAI | LangGraph | **Agency Orchestrator** |
-|---|--------|-----------|---------------------|
-| Language | Python | Python | **YAML (zero code)** |
-| Roles | Write your own | Write your own | **186 ready-to-use** |
-| Dependencies | pip + LiteLLM + dozens | pip + LangChain | **npm + 2 deps** |
-| Models | LiteLLM | LangChain | **Native: DeepSeek, Claude, OpenAI, Ollama** |
-| Parallelism | Manager mode | Manual graph | **Auto DAG detection** |
-| Branching | None | Manual | **Condition expressions** |
-| Loops | None | Manual | **Declarative loop/exit** |
-| Resume | None | Checkpointers | **Built-in `--resume` + `--from`** |
-| Price | Open-source + $25-99/mo cloud | Open-source | **Completely free** |
+## 3 步开始
 
-## Quick Start
+### 第 1 步：5 秒体验
 
-### Option A: Inside Claude Code / Cursor (No API key needed)
+```bash
+npx agency-orchestrator demo
+```
 
-Your AI coding tool's built-in LLM serves as the execution engine:
+4 个 AI 角色协作写小说。无需安装、无需配置、无需 API key。
+
+### 第 2 步：用你的会员跑真实工作流
 
 ```bash
-git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
-npx superpowers-zh
+npm install agency-orchestrator
+npx ao init                    # 下载 186 个 AI 角色
+
+# 用你已有的 Claude Max 会员（无需 API key！）
+npx ao run workflows/story-creation.yaml --input premise='一个时间旅行的故事'
 ```
 
-Then tell your AI: `Run workflows/story-creation.yaml with premise="A time travel story"`
+只需在 YAML 中写 `provider: "claude-code"`。没有 Claude？用 `gemini-cli`（Google 账号免费）、`copilot-cli`、`codex-cli` 都行。
 
-### Option B: CLI Mode (API key required)
+### 第 3 步：在 AI 编程工具中直接说
 
 ```bash
-npm install agency-orchestrator
-npx ao init                    # download 186 AI roles
-export DEEPSEEK_API_KEY=your-key
-npx ao run workflows/story-creation.yaml --input premise="A time travel story"
+./scripts/install.sh           # 一键安装到你的 AI 编程工具
+```
+
+然后在 Cursor / Claude Code / Copilot 中直接说：
+
 ```
+运行 workflows/story-creation.yaml，创意是"一个程序员在凌晨发现AI回复不该知道的事"
+```
+
+AI 会自动解析 YAML → 加载角色 → 按 DAG 顺序执行 → 保存结果。
+
+**支持 14 个 AI 编程工具**（[集成指南](./integrations/)）：Claude Code · GitHub Copilot · Cursor · Windsurf · Kiro · Trae · Aider · Gemini CLI · Codex CLI · OpenCode · Qwen Code · DeerFlow 2.0 · Antigravity · OpenClaw
 
-## Demo: 4 AI Roles Write a Complete Story in 2 Minutes
+## 真实演示：4 个 AI 角色 2 分钟写出完整小说
 
 ```
-$ ao run workflows/story-creation.yaml -i "premise=A programmer discovers AI replies with things it shouldn't know"
+$ ao run workflows/story-creation.yaml -i "premise=一个程序员在凌晨三点发现AI开始回复不该知道的事情"
 
-  Workflow: Short Story Creation
-  Steps: 4 | Concurrency: 2 | Model: deepseek-chat
+  工作流: 短篇小说创作
+  步骤数: 4 | 并发: 2 | 模型: deepseek-chat
 ──────────────────────────────────────────────────
 
-  ── [1/4] story_structure (Narratologist) ──
-  Done | 14.9s | 1,919 tokens
+  ── [1/4] story_structure (叙事学家) ──
+  完成 | 14.9s | 1,919 tokens
+    核心冲突：程序员与一个似乎拥有超越其代码权限的自主意识之间的认知对抗...
 
-  ── [2/4] character_design (Psychologist) ──            ← parallel
-  Done | 65.5s | 4,016 tokens
+  ── [2/4] character_design (心理学家) ──           ← 并行执行
+  完成 | 65.5s | 4,016 tokens
+    人物心理档案：林深——一个信奉逻辑与控制的资深AI工程师...
 
-  ── [3/4] conflict_design (Narrative Designer) ──       ← parallel
-  Done | 65.5s | 3,607 tokens
+  ── [3/4] conflict_design (叙事设计师) ──          ← 并行执行
+  完成 | 65.5s | 3,607 tokens
+    凌晨三点，屏幕的冷光映着陈默疲惫的脸...
 
-  ── [4/4] write_story (Content Creator) ──
-  Done | 33.9s | 5,330 tokens
+  ── [4/4] write_story (内容创作者) ──
+  完成 | 33.9s | 5,330 tokens
+    凌晨三点，调试日志的蓝色荧光是房间里唯一的光源。陈默灌下今晚第三杯黑咖啡...
 
 ==================================================
-  Completed: 4/4 steps | 114.3s | 14,872 tokens
+  完成: 4/4 步 | 114.3s | 14,872 tokens
 ==================================================
 ```
 
-Steps 2 and 3 run **in parallel** (auto-detected from DAG dependencies). Four specialized AI roles collaborate to produce a complete suspense short story.
+第 2、3 步**自动并行执行**（从 DAG 依赖关系检测）。4 个专业 AI 角色协作，产出一篇完整的悬疑短篇小说。
 
-## How It Works
+## 工作原理
 
 ```yaml
-name: "Product Requirements Review"
+name: "产品需求评审"
 agents_dir: "agency-agents-zh"
 
 llm:
-  provider: "deepseek"       # or: claude, openai, ollama
+  provider: "deepseek"          # 免 API key: claude-code / gemini-cli / copilot-cli / codex-cli / ollama
   model: "deepseek-chat"
 
 concurrency: 2
@@ -113,300 +150,398 @@ inputs:
 steps:
   - id: analyze
     role: "product/product-manager"
-    task: "Analyze this PRD and extract core requirements:\n\n{{prd_content}}"
+    task: "分析以下 PRD，提取核心需求：\n\n{{prd_content}}"
     output: requirements
 
   - id: tech_review
     role: "engineering/engineering-software-architect"
-    task: "Evaluate technical feasibility:\n\n{{requirements}}"
+    task: "评估技术可行性：\n\n{{requirements}}"
     output: tech_report
     depends_on: [analyze]
 
   - id: design_review
     role: "design/design-ux-researcher"
-    task: "Evaluate UX risks:\n\n{{requirements}}"
+    task: "评估用户体验风险：\n\n{{requirements}}"
     output: design_report
     depends_on: [analyze]
 
   - id: summary
     role: "product/product-manager"
-    task: "Synthesize feedback:\n\n{{tech_report}}\n\n{{design_report}}"
+    task: "综合反馈输出结论：\n\n{{tech_report}}\n\n{{design_report}}"
     depends_on: [tech_review, design_review]
 ```
 
-The engine automatically:
-1. Parses YAML → builds a **DAG** (directed acyclic graph)
-2. Detects parallelism — `tech_review` and `design_review` run concurrently
-3. Passes outputs between steps via `{{variables}}`
-4. Loads role definitions from [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) as system prompts
-5. Retries on failure (exponential backoff)
-6. Saves all outputs to `.ao-output/`
+引擎自动：
+
+1. 解析 YAML → 构建 **DAG**（有向无环图）
+2. 检测并行 — `tech_review` 和 `design_review` 并发执行
+3. 通过 `{{变量}}` 在步骤间传递输出
+4. 从 [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) 加载角色定义作为 system prompt
+5. 失败自动重试（指数退避）
+6. 保存所有输出到 `ao-output/`
 
 ```
 analyze ──→ tech_review  ──→ summary
          └→ design_review ──┘
-          (parallel)
+          (并行)
 ```
 
-## Features
+## 9 种 LLM — 6 种不需要 API key
+
+**你已经有这些会员了吧？直接就能跑：**
 
-### AI Workflow Composer
+| 你有... | YAML 配置 | 安装 CLI | 额外费用 |
+|---------|----------|---------|---------|
+| Claude Max/Pro（$20/月） | `provider: "claude-code"` | `npm i -g @anthropic-ai/claude-code` | **不花钱** |
+| Google 账号 | `provider: "gemini-cli"` | `npm i -g @google/gemini-cli` | **免费**（1000 次/天，Gemini 2.5 Pro） |
+| GitHub Copilot（$10/月） | `provider: "copilot-cli"` | `npm i -g @github/copilot` | **不花钱** |
+| ChatGPT Plus/Pro（$20/月） | `provider: "codex-cli"` | `npm i -g @openai/codex` | **不花钱** |
+| OpenClaw 账号 | `provider: "openclaw-cli"` | `npm i -g openclaw` | **不花钱** |
+| 一台电脑 | `provider: "ollama"` | [ollama.ai](https://ollama.ai) | **免费**（本地模型） |
 
-Describe your workflow in one sentence — AI selects the right roles, designs the DAG, and generates a ready-to-run YAML:
+**也支持传统 API key：**
+
+| 提供商 | 配置 | 环境变量 |
+|--------|------|---------|
+| DeepSeek | `provider: "deepseek"` | `DEEPSEEK_API_KEY` |
+| Claude API | `provider: "claude"` | `ANTHROPIC_API_KEY` |
+| OpenAI | `provider: "openai"` | `OPENAI_API_KEY` |
+
+所有 API 提供商支持自定义 `base_url` 和 `api_key`，兼容智谱、月之暗面等 OpenAI 兼容 API。
+
+## CLI 命令
 
 ```bash
-ao compose "PR code review covering security and performance"
+ao demo                              # 零配置体验多智能体协作
+ao init                              # 下载 186 个 AI 角色
+ao init --workflow                    # 交互式创建工作流
+ao compose "一句话描述"                # AI 智能编排工作流
+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 调用）
 ```
 
-The AI will:
-1. Select matching roles from 186 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`
+| 参数 | 说明 |
+|------|------|
+| `--input key=value` | 传入输入变量 |
+| `--input key=@file` | 从文件读取变量值 |
+| `--output dir` | 输出目录（默认 `ao-output/`） |
+| `--resume <dir\|last>` | 从上次运行恢复（加载已完成步骤的输出） |
+| `--from <step-id>` | 配合 `--resume`，从指定步骤重新执行 |
+| `--watch` | 实时终端进度显示 |
+| `--quiet` | 静默模式 |
 
-Supports `--provider` and `--model` flags (default: DeepSeek).
+### AI 智能编排（Compose）
 
-### Condition Branching
+一句话描述需求，AI 自动从 186 个角色中选角色、设计 DAG、生成完整 workflow YAML：
 
-```yaml
-- id: tech_path
-  role: "engineering/engineering-sre"
-  task: "Technical evaluation: {{requirements}}"
-  depends_on: [classify]
-  condition: "{{job_type}} contains technical"
+```bash
+ao compose "PR 代码审查，要覆盖安全和性能"
+```
 
-- id: biz_path
-  role: "marketing/marketing-social-media-strategist"
-  task: "Business evaluation: {{requirements}}"
-  depends_on: [classify]
-  condition: "{{job_type}} contains business"
+AI 会自动：
+1. 从 186 角色中匹配出 Code Reviewer、Security Engineer、Performance Benchmarker
+2. 设计 DAG（三路并行 → 汇总）
+3. 生成带 `depends_on`、变量串联的完整 YAML
+4. 保存到 `workflows/` — 直接 `ao run` 就能跑
 
-- id: summary
-  depends_on: [tech_path, biz_path]
-  depends_on_mode: "any_completed"  # proceeds when ANY upstream completes
-```
+支持 `--provider` 和 `--model` 参数（默认使用 DeepSeek）。
 
-Supported operators: `contains`, `equals`, `not_contains`, `not_equals`.
+### 迭代优化（Resume）
 
-### Loop Iteration
+**问题**：`ao run` 跑完一轮后，所有步骤的输出都丢了。想基于叙事学家的结构重写小说，只能整个工作流从头跑。
 
-```yaml
-- id: write_draft
-  role: "marketing/marketing-content-creator"
-  task: "Write article: {{topic}}"
-  output: draft
+**解决**：`--resume` 会自动加载上一轮所有步骤的输出，`--from` 指定从哪步开始重跑。之前的步骤直接用缓存结果，不会重新执行。
+
+#### 完整示例：小说创作 4 轮迭代
 
-- id: brand_review
-  role: "design/design-brand-guardian"
-  task: "Review brand compliance: {{draft}}"
-  output: review_result
-  depends_on: [write_draft]
-  loop:
-    back_to: write_draft
-    max_iterations: 3
-    exit_condition: "{{review_result}} contains approved"
+以 `story-creation.yaml` 为例，DAG 结构如下：
+
+```
+story_structure ──→ character_design ──→ write_story
+                └→ conflict_design  ──┘
+                    (并行)
+```
+
+**第一轮：正常运行**
+
+```bash
+ao run workflows/story-creation.yaml \
+  -i premise='一个程序员在凌晨三点发现AI开始回复不该知道的事情'
 ```
 
-When the exit condition is not met, execution loops back to `back_to`. The `{{_loop_iteration}}` variable tracks the current round.
+运行完后，每步输出保存在 `ao-output/` 下：
 
-### Resume & Iterate
+```
+ao-output/短篇小说创作-2026-03-24T14-30-00/
+├── summary.md                    ← 最终小说
+├── metadata.json                 ← 每步状态 + 变量映射
+├── steps/
+│   ├── 1-story_structure.md      ← 叙事学家的结构设计
+│   ├── 2-character_design.md     ← 心理学家的人物设定
+│   ├── 3-conflict_design.md      ← 叙事设计师的冲突场景
+│   └── 4-write_story.md          ← 最终小说
+```
 
-**Problem**: After `ao run` completes, all step outputs are lost. To tweak the final story, you'd have to re-run everything from scratch.
+打开这些文件看每步输出，觉得哪里不满意就重跑那步。
 
-**Solution**: `--resume` reloads previous outputs. `--from` specifies where to restart.
+**第二轮：人物太单薄，从人物设计开始重跑**
 
 ```bash
-# Round 1: Normal run
-ao run workflows/story-creation.yaml -i premise="A time travel story"
-
-# Round 2: Characters feel flat — re-run from character_design
 ao run workflows/story-creation.yaml --resume last --from character_design
+```
+
+- `--resume last`：自动找到最近一次输出
+- `--from character_design`：从人物设计开始重跑
+- `story_structure` 的输出（叙事结构）直接复用，不重新执行
+- `character_design` → `conflict_design` → `write_story` 重新执行
+- 新的输出保存到新的时间戳目录
+
+**第三轮：结构和人物都好，只改最终写作**
 
-# Round 3: Only rewrite the final prose
+```bash
 ao run workflows/story-creation.yaml --resume last --from write_story
+```
 
-# Round 4: Go back to a specific version
-ao run workflows/story-creation.yaml --resume .ao-output/<dir>/ --from write_story
+只重跑最后一步。叙事结构、人物设定、冲突设计全部复用，只让内容创作者重写。
+
+**第四轮：想回到第二轮的版本继续改**
+
+```bash
+ao run workflows/story-creation.yaml \
+  --resume ao-output/短篇小说创作-2026-03-24T14-35-00/ \
+  --from write_story
 ```
 
-Each round creates a new timestamped output directory. All versions are preserved.
+指定具体目录，基于那个版本继续迭代。
 
-| Scenario | Command |
-|----------|---------|
-| First run | `ao run workflow.yaml -i key=value` |
-| Re-run from a step | `ao run workflow.yaml --resume last --from <step-id>` |
-| Re-run only failed steps | `ao run workflow.yaml --resume last` |
-| Resume specific version | `ao run workflow.yaml --resume .ao-output/<dir>/ --from <step-id>` |
+#### 所有历史版本都保留
 
-## Supported LLMs
+```bash
+ls ao-output/
+# 短篇小说创作-2026-03-24T14-30-00/   ← 第一轮
+# 短篇小说创作-2026-03-24T14-35-00/   ← 第二轮
+# 短篇小说创作-2026-03-24T14-38-00/   ← 第三轮
+# 短篇小说创作-2026-03-24T14-40-00/   ← 第四轮
+```
 
-| Provider | Config | Env Variable |
-|----------|--------|-------------|
-| **DeepSeek** | `provider: "deepseek"` | `DEEPSEEK_API_KEY` |
-| **Claude** | `provider: "claude"` | `ANTHROPIC_API_KEY` |
-| **OpenAI** | `provider: "openai"` | `OPENAI_API_KEY` |
-| **Ollama** (local) | `provider: "ollama"` | None needed |
+#### 用法速查
 
-All providers support custom `base_url` and `api_key`, compatible with any OpenAI-compatible API (Zhipu, Moonshot, etc.).
+| 场景 | 命令 |
+|------|------|
+| 第一次运行 | `ao run workflow.yaml -i key=value` |
+| 从某步重跑（基于上次结果） | `ao run workflow.yaml --resume last --from <步骤ID>` |
+| 只重跑失败的步骤 | `ao run workflow.yaml --resume last` |
+| 基于指定版本重跑 | `ao run workflow.yaml --resume ao-output/具体目录/ --from <步骤ID>` |
 
-## CLI Reference
+#### 原理
 
-```bash
-ao init                              # Download 186 AI roles
-ao init --workflow                    # Interactive workflow creator
-ao compose "description"             # AI-powered workflow generation
-ao run <workflow.yaml> [options]      # Execute workflow
-ao validate <workflow.yaml>           # Validate without running
-ao plan <workflow.yaml>               # Show execution plan (DAG)
-ao explain <workflow.yaml>            # Explain execution plan in natural language
-ao roles                             # List all available roles
-```
-
-| Option | Description |
-|--------|-------------|
-| `--input key=value` | Pass input variables |
-| `--input key=@file` | Read variable value from file |
-| `--output dir` | Output directory (default `.ao-output/`) |
-| `--resume <dir\|last>` | Resume from previous run |
-| `--from <step-id>` | With `--resume`, restart from a specific step |
-| `--watch` | Real-time terminal progress display |
-| `--quiet` | Quiet mode |
+`--resume` 做了三件事：
+1. 读取指定目录的 `metadata.json`，获取每步的状态和输出变量名
+2. 从 `steps/` 目录读取已完成步骤的输出内容，注入回 `{{变量}}` 上下文
+3. 标记 `--from` 之前的步骤为"已完成"，跳过执行
 
-## YAML Schema
+智能体结构（角色分工、DAG 依赖、变量传递）不会丢失 — 它定义在 YAML 里，每次都会重新加载。丢失的只是上一轮的**输出内容**，`--resume` 就是把这些内容恢复回来。
 
-### Workflow
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Workflow name |
-| `agents_dir` | string | Yes | Path to role definitions directory |
-| `llm.provider` | string | Yes | `claude` / `deepseek` / `openai` / `ollama` |
-| `llm.model` | string | Yes | Model name |
-| `llm.max_tokens` | number | No | Default 4096 |
-| `llm.timeout` | number | No | Step timeout in ms (default 120000) |
-| `llm.retry` | number | No | Retry count (default 3) |
-| `concurrency` | number | No | Max parallel steps (default 2) |
-| `inputs` | array | No | Input variable definitions |
-| `steps` | array | Yes | Workflow steps |
-
-### Step
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `id` | string | Yes | Unique step identifier |
-| `role` | string | Yes | Role path (e.g. `"engineering/engineering-sre"`) |
-| `task` | string | Yes | Task description, supports `{{variables}}` |
-| `output` | string | No | Output variable name |
-| `depends_on` | string[] | No | Dependent step IDs |
-| `depends_on_mode` | string | No | `"all"` (default) or `"any_completed"` |
-| `condition` | string | No | Condition expression; step skipped if not met |
-| `type` | string | No | `"approval"` for human approval gate |
-| `prompt` | string | No | Prompt text for approval nodes |
-| `loop` | object | No | Loop config |
-| `loop.back_to` | string | No | Step ID to loop back to |
-| `loop.max_iterations` | number | No | Max loop rounds (1-10) |
-| `loop.exit_condition` | string | No | Exit condition expression |
-
-## Programmatic API
+## 编程 API
 
 ```typescript
 import { run } from 'agency-orchestrator';
 
 const result = await run('workflow.yaml', {
-  prd_content: 'Your PRD here...',
+  prd_content: '你的 PRD 内容...',
 });
 
 console.log(result.success);     // true/false
 console.log(result.totalTokens); // { input: 1234, output: 5678 }
 ```
 
-## Integrations
-
-Works with **9 AI coding tools** — each tool gets a workflow-runner skill file:
-
-| Tool | Integration | Docs |
-|------|------------|------|
-| **Claude Code** | Skill mode / CLI | [Guide](./integrations/claude-code/) |
-| **Cursor** | `.cursor/rules` | [Guide](./integrations/cursor/) |
-| **Kiro** | `.kiro/steering` | [Guide](./integrations/kiro/) |
-| **Trae** | `.trae/rules` | [Guide](./integrations/trae/) |
-| **Gemini CLI** | `GEMINI.md` | [Guide](./integrations/gemini-cli/) |
-| **Codex CLI** | `.codex/instructions` | [Guide](./integrations/codex/) |
-| **DeerFlow 2.0** | `skills/custom` | [Guide](./integrations/deerflow/) |
-| **Antigravity** | `AGENTS.md` | [Guide](./integrations/antigravity/) |
-| **OpenClaw** | Skill mode / CLI | [Guide](./integrations/openclaw/) |
+## MCP Server 模式
 
-## Workflow Templates (20+)
+AI 编程工具（Claude Code、Cursor 等）可通过 MCP 协议直接调用工作流操作，无需手动集成：
 
-### Dev Workflows
-
-| Template | Roles | Description |
-|----------|-------|-------------|
-| `dev/pr-review.yaml` | Code Reviewer, Security Engineer, Performance Benchmarker | PR review (3-way parallel → summary) |
-| `dev/tech-debt-audit.yaml` | Architect, Code Reviewer, Test Analyst, Sprint Prioritizer | Tech debt audit (parallel → prioritize) |
-| `dev/api-doc-gen.yaml` | Tech Writer, API Tester | API doc generation (analyze → validate → finalize) |
-| `dev/readme-i18n.yaml` | Content Creator, Tech Writer | README internationalization |
-| `dev/security-audit.yaml` | Security Engineer, Threat Detection Engineer | Security audit (parallel → report) |
-| `dev/release-checklist.yaml` | SRE, Performance Benchmarker, Security Engineer, PM | Release Go/No-Go decision |
-
-### Data / Design / Ops Workflows
+```bash
+ao serve              # 启动 MCP stdio 服务器
+ao serve --verbose    # 带调试日志
+```
 
-| Template | Roles | Description |
-|----------|-------|-------------|
-| `data/data-pipeline-review.yaml` | Data Engineer, DB Optimizer, Data Analyst | Data pipeline review |
-| `data/dashboard-design.yaml` | Data Analyst, UX Researcher, UI Designer | Dashboard design |
-| `design/requirement-to-plan.yaml` | PM, Architect, Project Manager | Requirements → tech design → task breakdown |
-| `design/ux-review.yaml` | UX Researcher, Accessibility Auditor, UX Architect | UX review |
-| `ops/incident-postmortem.yaml` | Incident Commander, SRE, PM | Incident postmortem |
-| `ops/sre-health-check.yaml` | SRE, Performance Benchmarker, Infra Ops | SRE health check (3-way parallel) |
+配置 Claude Code（`settings.json`）：
+
+```json
+{
+  "mcpServers": {
+    "agency-orchestrator": {
+      "command": "npx",
+      "args": ["agency-orchestrator", "serve"]
+    }
+  }
+}
+```
 
-### General Workflows
+配置 Cursor（`.cursor/mcp.json`）：
+
+```json
+{
+  "mcpServers": {
+    "agency-orchestrator": {
+      "command": "npx",
+      "args": ["agency-orchestrator", "serve"]
+    }
+  }
+}
+```
 
-| Template | Roles | Description |
-|----------|-------|-------------|
-| `product-review.yaml` | PM, Architect, UX Researcher | Product requirements review |
-| `content-pipeline.yaml` | Strategist, Creator, Growth Hacker | Content creation pipeline |
-| `story-creation.yaml` | Narratologist, Psychologist, Narrative Designer, Creator | Collaborative fiction (4 roles) |
-| `department-collab/code-review.yaml` | Code Reviewer, Security Engineer | Code review (review loop) |
-| `department-collab/hiring-pipeline.yaml` | HR, Tech Interviewer, Biz Interviewer | Hiring pipeline |
-| `department-collab/content-publish.yaml` | Content Creator, Brand Guardian | Content publishing (review loop) |
-| `department-collab/incident-response.yaml` | SRE, Security Engineer, Backend Architect | Incident response |
-| `department-collab/marketing-campaign.yaml` | Strategist, Creator, Approver | Marketing campaign (human approval) |
+提供 6 个工具：`run_workflow`、`validate_workflow`、`list_workflows`、`plan_workflow`、`compose_workflow`、`list_roles`。
 
-## Output Structure
+## YAML Schema
 
-Each run saves to `.ao-output/<name>-<timestamp>/`:
+### 工作流
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `name` | string | 是 | 工作流名称 |
+| `agents_dir` | string | 是 | 角色目录路径 |
+| `llm.provider` | string | 是 | `claude-code` / `gemini-cli` / `copilot-cli` / `codex-cli` / `openclaw-cli` / `ollama` / `claude` / `deepseek` / `openai` |
+| `llm.model` | string | 是 | 模型名称 |
+| `llm.max_tokens` | number | 否 | 默认 4096 |
+| `llm.timeout` | number | 否 | 步骤超时毫秒数（默认 120000） |
+| `llm.retry` | number | 否 | 重试次数（默认 3） |
+| `concurrency` | number | 否 | 最大并行步骤数（默认 2） |
+| `inputs` | array | 否 | 输入变量定义 |
+| `steps` | array | 是 | 工作流步骤 |
+
+### 步骤
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | string | 是 | 步骤唯一标识 |
+| `role` | string | 是 | 角色路径（如 `"engineering/engineering-sre"`） |
+| `task` | string | 是 | 任务描述，支持 `{{变量}}` |
+| `output` | string | 否 | 输出变量名 |
+| `depends_on` | string[] | 否 | 依赖的步骤 ID |
+| `depends_on_mode` | string | 否 | `"all"`（默认）或 `"any_completed"`（任一完成即可） |
+| `condition` | string | 否 | 条件表达式，不满足则跳过（如 `"{{var}} contains 技术"`） |
+| `type` | string | 否 | `"approval"` 表示人工审批节点 |
+| `prompt` | string | 否 | 审批节点的提示文本 |
+| `loop` | object | 否 | 循环配置 |
+| `loop.back_to` | string | 否 | 循环回到的步骤 ID |
+| `loop.max_iterations` | number | 否 | 最大循环次数（1-10） |
+| `loop.exit_condition` | string | 否 | 退出条件表达式 |
+
+## 输出
+
+每次运行保存到 `ao-output/<名称>-<时间戳>/`：
 
 ```
-.ao-output/product-review-2026-03-22/
-├── summary.md          # Final step output
+ao-output/产品需求评审-2026-03-22/
+├── summary.md          # 最终步骤输出
 ├── steps/
 │   ├── 1-analyze.md
 │   ├── 2-tech_review.md
 │   ├── 3-design_review.md
 │   └── 4-summary.md
-└── metadata.json       # Timing, token usage, step states
+└── metadata.json       # 耗时、token 用量、步骤状态
 ```
 
-## Ecosystem
+## 内置工作流模板（30 个）
+
+### 开发类（7 个）
+
+| 模板 | 角色 | 说明 |
+|------|------|------|
+| `dev/tech-design-review.yaml` | 架构师、后端架构师、安全工程师、代码审查员 | **技术方案评审**（设计→并行评审→结论） |
+| `dev/pr-review.yaml` | 代码审查员、安全工程师、性能基准师 | PR 评审（3 路并行→汇总） |
+| `dev/tech-debt-audit.yaml` | 架构师、代码审查员、测试分析师、Sprint 排序师 | 技术债务审计（并行→优先级排序） |
+| `dev/api-doc-gen.yaml` | 技术文档工程师、API 测试员 | API 文档生成（分析→验证→定稿） |
+| `dev/readme-i18n.yaml` | 内容创作者、技术文档工程师 | README 国际化 |
+| `dev/security-audit.yaml` | 安全工程师、威胁检测工程师 | 安全审计（并行→报告） |
+| `dev/release-checklist.yaml` | SRE、性能基准师、安全工程师、产品经理 | 发布 Go/No-Go 决策 |
+
+### 营销类（3 个）
+
+| 模板 | 角色 | 说明 |
+|------|------|------|
+| `marketing/competitor-analysis.yaml` | 趋势研究员、数据分析师、SEO 专家、高管摘要师 | **竞品分析报告**（研究→并行分析→摘要） |
+| `marketing/xiaohongshu-content.yaml` | 小红书专家、内容创作者、视觉叙事师、小红书运营 | **小红书种草笔记**（选题→并行创作→优化） |
+| `marketing/seo-content-matrix.yaml` | SEO 专家、策略师、内容创作者 | **SEO 内容矩阵**（关键词→策略→批量生成→审核） |
+
+### 数据 / 设计 / 运维类（7 个）
+
+| 模板 | 角色 | 说明 |
+|------|------|------|
+| `data/data-pipeline-review.yaml` | 数据工程师、数据库优化师、数据分析师 | 数据管道评审 |
+| `data/dashboard-design.yaml` | 数据分析师、UX 研究员、UI 设计师 | 仪表盘设计 |
+| `design/requirement-to-plan.yaml` | 产品经理、架构师、项目经理 | 需求→技术设计→任务拆分 |
+| `design/ux-review.yaml` | UX 研究员、无障碍审核员、UX 架构师 | UX 评审 |
+| `ops/incident-postmortem.yaml` | 事故指挥官、SRE、产品经理 | 事故复盘 |
+| `ops/sre-health-check.yaml` | SRE、性能基准师、基础设施运维师 | SRE 健康检查（3 路并行） |
+| `ops/weekly-report.yaml` | 会议助手、内容创作者、高管摘要师 | **周报/月报生成**（整理→亮点→定稿） |
+
+### 战略 / 法务 / HR 类（3 个）
+
+| 模板 | 角色 | 说明 |
+|------|------|------|
+| `strategy/business-plan.yaml` | 趋势研究员、财务预测师、产品经理、高管摘要师 | **商业计划书**（市场→并行分析→整合） |
+| `legal/contract-review.yaml` | 合同审查专家、法务合规员 | **合同审查**（逐条分析→合规检查→意见书） |
+| `hr/interview-questions.yaml` | 招聘专家、心理学家、后端架构师 | **面试题设计**（维度→并行出题→评分表） |
+
+### 通用类（10 个）
+
+| 模板 | 角色 | 说明 |
+|------|------|------|
+| `product-review.yaml` | 产品经理、架构师、UX 研究员 | 产品需求评审 |
+| `content-pipeline.yaml` | 策略师、创作者、增长黑客 | 内容创作流水线 |
+| `story-creation.yaml` | 叙事学家、心理学家、叙事设计师、创作者 | 协作小说创作（4 角色） |
+| `ai-opinion-article.yaml` | 趋势研究员、叙事设计师、心理学家、创作者 | AI 观点长文 |
+| `department-collab/code-review.yaml` | 代码审查员、安全工程师 | 代码评审（循环） |
+| `department-collab/hiring-pipeline.yaml` | HR、技术面试官、业务面试官 | 招聘流程 |
+| `department-collab/content-publish.yaml` | 内容创作者、品牌守护者 | 内容发布（循环） |
+| `department-collab/incident-response.yaml` | SRE、安全工程师、后端架构师 | 事故响应 |
+| `department-collab/marketing-campaign.yaml` | 策略师、创作者、审批人 | 营销活动（人工审批） |
+| `department-collab/ceo-org-delegation.yaml` | CEO、工程/市场/产品/HR 部门负责人 | **CEO 组织架构协作**（决策→部门并行→汇总） |
+
+## 项目生态
+
+```
+你的 AI 会员 ──→ agency-orchestrator ──→ 186 个专业角色协作 ──→ 高质量输出
+                     │
+    ┌────────────────┼────────────────┐
+    ▼                ▼                ▼
+  14 个 AI 编程工具    CLI 模式         MCP Server
+  (Cursor/Claude     (自动化/CI/CD)   (Claude Code/
+   Code/Copilot...)                   Cursor 直接调用)
+```
+
+## 社区交流
+
+| 群名 | 群号 | 加入方式 |
+|------|------|---------|
+| AI 编程 & Agent 中文实践群 | **1071280067** | [点击加入](https://qm.qq.com/q/EeNQA9xCxy) |
+
+## 姊妹项目
 
-| Project | Description |
-|---------|-------------|
-| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) | 186 AI role definitions — the role library for this engine |
-| [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) | AI coding superpowers — 20 skills for Claude Code / Cursor |
-| [shellward](https://github.com/jnMetaCode/shellward) | AI agent security middleware — prompt injection detection, DLP, command safety |
+| 项目 | 说明 |
+|------|------|
+| [ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) | AI 编程工具实战指南 — 66 个 Claude Code 技巧 + 9 款工具最佳实践 + 可复制配置模板 |
+| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) | 187 个专业角色，让 AI 变成安全工程师、DBA、产品经理等 |
+| [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) | AI 编程超能力 · 中文版 — 20 个 skills，让你的 AI 编程助手真正会干活 |
+| [shellward](https://github.com/jnMetaCode/shellward) | AI 智能体安全中间件 — 注入检测、数据防泄露、命令安全、零依赖、MCP Server |
 
-## Roadmap
+## 路线图
 
-- [x] **v0.1** — YAML workflows, DAG engine, 4 LLM connectors, CLI, streaming output
-- [x] **v0.2** — Condition branching, loop iteration, human approval, Resume, 5 department-collab templates
-- [x] **v0.3** — 9 AI tool integrations, 20+ workflow templates, `ao explain`, `ao init --workflow`, `--watch` mode
-- [ ] **v0.4** — MCP Server mode, Web UI, visual DAG editor, English role support, workflow marketplace
+- [x] **v0.1** — YAML 工作流、DAG 引擎、4 个 LLM 连接器、CLI、实时输出
+- [x] **v0.2** — 条件分支、循环迭代、人工审批、Resume 断点续跑、5 个部门协作模板
+- [x] **v0.3** — 9 个 AI 工具集成、20+ 工作流模板、`ao explain`、`ao init --workflow`、`--watch` 模式
+- [x] **v0.4** — MCP Server 模式（`ao serve`）、14 个 AI 工具集成、一键安装脚本、30 个工作流模板、**9 种 LLM（6 种免 API key：Claude Code / Gemini / Copilot / Codex / OpenClaw / Ollama）**
+- [ ] **v0.5** — Web UI、可视化 DAG 编辑器、英文角色支持、工作流市场
 
-## Contributing
+## 贡献
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md). PRs welcome!
+参见 [CONTRIBUTING.md](./CONTRIBUTING.md)，欢迎 PR！
 
-## License
+## 许可证
 
 [Apache-2.0](./LICENSE)