agency-orchestrator 0.3.0 → 0.3.2

package/README.md

@@ -150,6 +150,22 @@ analyze ──→ tech_review  ──→ summary
 
 ## Features
 
+### AI Workflow Composer
+
+Describe your workflow in one sentence — AI selects the right roles, designs the DAG, and generates a ready-to-run YAML:
+
+```bash
+ao compose "PR code review covering security and performance"
+```
+
+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`
+
+Supports `--provider` and `--model` flags (default: DeepSeek).
+
 ### Condition Branching
 
 ```yaml
@@ -160,7 +176,7 @@ analyze ──→ tech_review  ──→ summary
   condition: "{{job_type}} contains technical"
 
 - id: biz_path
-  role: "marketing/marketing-strategist"
+  role: "marketing/marketing-social-media-strategist"
   task: "Business evaluation: {{requirements}}"
   depends_on: [classify]
   condition: "{{job_type}} contains business"
@@ -176,12 +192,12 @@ Supported operators: `contains`, `equals`, `not_contains`, `not_equals`.
 
 ```yaml
 - id: write_draft
-  role: "content/content-creator"
+  role: "marketing/marketing-content-creator"
   task: "Write article: {{topic}}"
   output: draft
 
 - id: brand_review
-  role: "marketing/brand-guardian"
+  role: "design/design-brand-guardian"
   task: "Review brand compliance: {{draft}}"
   output: review_result
   depends_on: [write_draft]
@@ -238,6 +254,7 @@ All providers support custom `base_url` and `api_key`, compatible with any OpenA
 ```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)

package/README.zh-CN.md

@@ -200,6 +200,7 @@ analyze ──→ tech_review  ──→ summary
 ```bash
 ao init                              # 下载 186 个 AI 角色
 ao init --workflow                    # 交互式创建工作流
+ao compose "一句话描述"                # AI 智能编排工作流
 ao run <workflow.yaml> [选项]          # 执行工作流
 ao validate <workflow.yaml>           # 校验（不执行）
 ao plan <workflow.yaml>               # 查看执行计划（DAG）
@@ -217,6 +218,22 @@ ao roles                             # 列出所有角色
 | `--watch` | 实时终端进度显示 |
 | `--quiet` | 静默模式 |
 
+### AI 智能编排（Compose）
+
+一句话描述需求，AI 自动从 186 个角色中选角色、设计 DAG、生成完整 workflow YAML：
+
+```bash
+ao compose "PR 代码审查，要覆盖安全和性能"
+```
+
+AI 会自动：
+1. 从 186 角色中匹配出 Code Reviewer、Security Engineer、Performance Benchmarker
+2. 设计 DAG（三路并行 → 汇总）
+3. 生成带 `depends_on`、变量串联的完整 YAML
+4. 保存到 `workflows/` — 直接 `ao run` 就能跑
+
+支持 `--provider` 和 `--model` 参数（默认使用 DeepSeek）。
+
 ### 迭代优化（Resume）
 
 **问题**：`ao run` 跑完一轮后，所有步骤的输出都丢了。想基于叙事学家的结构重写小说，只能整个工作流从头跑。

package/dist/agents/loader.js

@@ -82,6 +82,7 @@ export function listAgents(agentsDir) {
             const rolePath = `${dept.name}/${file.name.replace('.md', '')}`;
             try {
                 const agent = loadAgent(agentsDir, rolePath);
+                agent.rolePath = rolePath;
                 agents.push(agent);
             }
             catch {

package/dist/cli/compose.d.ts

@@ -0,0 +1,43 @@
+import type { LLMConfig } from '../types.js';
+/** 精简的角色摘要，供 LLM 选角色用 */
+export interface RoleSummary {
+    path: string;
+    name: string;
+    description: string;
+    category: string;
+}
+/**
+ * 从 agents 目录构建精简的角色目录
+ */
+export declare function buildRoleCatalog(agentsDir: string): RoleSummary[];
+/**
+ * 格式化角色目录为紧凑文本（给 LLM 看）
+ */
+export declare function formatCatalogForPrompt(roles: RoleSummary[]): string;
+/**
+ * 构建发给 LLM 的 system prompt
+ */
+export declare function buildComposeSystemPrompt(catalog: string): string;
+/**
+ * 构建 user prompt
+ */
+export declare function buildComposeUserPrompt(description: string): string;
+/**
+ * 从 LLM 回复中提取 YAML 内容
+ */
+export declare function extractYamlFromResponse(response: string): string;
+/**
+ * 根据描述生成文件名
+ */
+export declare function generateFileName(description: string): string;
+/**
+ * 执行 compose 流程
+ */
+export declare function composeWorkflow(options: {
+    description: string;
+    agentsDir: string;
+    llmConfig: LLMConfig;
+}): Promise<{
+    yaml: string;
+    savedPath: string;
+}>;

package/dist/cli/compose.js

@@ -0,0 +1,210 @@
+/**
+ * ao compose — AI 智能编排工作流
+ *
+ * 用户用一句话描述需求，AI 从 186 个角色中选角色、设计 DAG、生成完整 workflow YAML。
+ */
+import { listAgents } from '../agents/loader.js';
+import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+/**
+ * 从 agents 目录构建精简的角色目录
+ */
+export function buildRoleCatalog(agentsDir) {
+    const agents = listAgents(agentsDir);
+    return agents
+        .filter(a => a.rolePath) // 只保留有路径的
+        .map(a => ({
+        path: a.rolePath,
+        name: a.name,
+        description: a.description || '',
+        category: a.rolePath.split('/')[0],
+    }));
+}
+/**
+ * 格式化角色目录为紧凑文本（给 LLM 看）
+ */
+export function formatCatalogForPrompt(roles) {
+    const byCategory = new Map();
+    for (const r of roles) {
+        const list = byCategory.get(r.category) || [];
+        list.push(r);
+        byCategory.set(r.category, list);
+    }
+    const lines = [];
+    for (const [cat, list] of byCategory) {
+        lines.push(`## ${cat}`);
+        for (const r of list) {
+            lines.push(`- ${r.path} | ${r.name} | ${r.description}`);
+        }
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+/**
+ * 构建发给 LLM 的 system prompt
+ */
+export function buildComposeSystemPrompt(catalog) {
+    return `你是一个 AI 工作流编排专家。用户会用一句话描述他想要的工作流，你需要：
+
+1. 从下方角色目录中选择最合适的角色（通常 2-6 个）
+2. 设计合理的 DAG 依赖关系（哪些步骤可以并行，哪些必须串行）
+3. 为每个步骤编写详细的 task 描述
+4. 设计合理的输入变量
+5. 生成完整的 workflow YAML
+
+## 输出格式
+
+直接输出一个完整的 YAML 代码块，格式如下：
+
+\`\`\`yaml
+name: "工作流名称"
+description: "一句话描述"
+
+agents_dir: "agency-agents-zh"
+
+llm:
+  provider: deepseek
+  model: deepseek-chat
+  max_tokens: 4096
+
+concurrency: 2
+
+inputs:
+  - name: variable_name
+    description: "变量描述"
+    required: true
+
+steps:
+  - id: step_id
+    role: "category/role-name"
+    task: |
+      详细的任务描述...
+      使用 {{variable_name}} 引用输入变量
+      使用 {{previous_output}} 引用上游步骤的输出
+    output: output_variable_name
+    depends_on: [upstream_step_id]  # 仅在有依赖时添加
+\`\`\`
+
+## 设计原则
+
+- **并行优先**：没有数据依赖的步骤应该并行执行（不加 depends_on）
+- **变量串联**：上游步骤的 output 变量名要和下游步骤 task 中的 {{变量}} 对应
+- **角色匹配**：选择最专业的角色，不要用一个角色做所有事
+- **任务详细**：task 描述要具体，告诉角色要做什么、输出什么格式
+- **合理输入**：提取用户需求中的关键变量作为 inputs
+- **最终汇总**：如果有多路并行，最后应该有一个汇总步骤
+
+## 可用角色目录
+
+${catalog}
+
+## 注意
+
+- role 的值必须严格使用角色目录中的 path（如 "engineering/engineering-code-reviewer"），不要自己编造
+- 只输出 YAML 代码块，不要输出其他内容
+- concurrency 设为并行步骤的最大数量`;
+}
+/**
+ * 构建 user prompt
+ */
+export function buildComposeUserPrompt(description) {
+    return `请为以下需求设计一个多智能体协作工作流：
+
+${description}`;
+}
+/**
+ * 从 LLM 回复中提取 YAML 内容
+ */
+export function extractYamlFromResponse(response) {
+    // 尝试从 ```yaml ... ``` 代码块中提取
+    const yamlBlock = response.match(/```ya?ml\s*\n([\s\S]*?)```/);
+    if (yamlBlock)
+        return yamlBlock[1].trim();
+    // 尝试从 ``` ... ``` 代码块中提取
+    const codeBlock = response.match(/```\s*\n([\s\S]*?)```/);
+    if (codeBlock)
+        return codeBlock[1].trim();
+    // 没有代码块，整个回复当 YAML
+    return response.trim();
+}
+/**
+ * 根据描述生成文件名
+ */
+export function generateFileName(description) {
+    const cleaned = description
+        .replace(/[^\u4e00-\u9fffa-zA-Z0-9\s-]/g, '')
+        .trim()
+        .slice(0, 40)
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/^-|-$/g, '');
+    return (cleaned || 'composed-workflow') + '.yaml';
+}
+/**
+ * 创建 LLM connector（动态导入）
+ */
+async function createConnector(config) {
+    switch (config.provider) {
+        case 'deepseek': {
+            const { OpenAICompatibleConnector } = await import('../connectors/openai-compatible.js');
+            return new OpenAICompatibleConnector({
+                apiKey: config.api_key || process.env.DEEPSEEK_API_KEY,
+                baseUrl: config.base_url || 'https://api.deepseek.com/v1',
+            });
+        }
+        case 'openai': {
+            const { OpenAICompatibleConnector } = await import('../connectors/openai-compatible.js');
+            return new OpenAICompatibleConnector({
+                apiKey: config.api_key || process.env.OPENAI_API_KEY,
+                baseUrl: config.base_url || 'https://api.openai.com/v1',
+            });
+        }
+        case 'claude': {
+            const { ClaudeConnector } = await import('../connectors/claude.js');
+            return new ClaudeConnector(config.api_key);
+        }
+        case 'ollama': {
+            const { OllamaConnector } = await import('../connectors/ollama.js');
+            return new OllamaConnector(config.base_url);
+        }
+        default:
+            throw new Error(`不支持的 provider: ${config.provider}`);
+    }
+}
+/**
+ * 执行 compose 流程
+ */
+export async function composeWorkflow(options) {
+    const { description, agentsDir, llmConfig } = options;
+    // 1. 构建角色目录
+    const roles = buildRoleCatalog(agentsDir);
+    if (roles.length === 0) {
+        throw new Error(`角色目录为空: ${agentsDir}\n请先运行 ao init 下载角色定义`);
+    }
+    const catalog = formatCatalogForPrompt(roles);
+    // 2. 构建 prompt
+    const systemPrompt = buildComposeSystemPrompt(catalog);
+    const userPrompt = buildComposeUserPrompt(description);
+    // 3. 调用 LLM
+    console.log(`  正在用 AI 编排工作流...（${roles.length} 个角色可选）\n`);
+    const connector = await createConnector(llmConfig);
+    const result = await connector.chat(systemPrompt, userPrompt, {
+        ...llmConfig,
+        max_tokens: llmConfig.max_tokens || 4096,
+    });
+    // 4. 提取 YAML
+    const yaml = extractYamlFromResponse(result.content);
+    if (!yaml || !yaml.includes('steps:')) {
+        throw new Error('AI 生成的内容不是有效的 workflow YAML，请重试或调整描述');
+    }
+    // 5. 保存
+    const fileName = generateFileName(description);
+    const workflowsDir = resolve('workflows');
+    if (!existsSync(workflowsDir)) {
+        mkdirSync(workflowsDir, { recursive: true });
+    }
+    const savedPath = resolve(workflowsDir, fileName);
+    writeFileSync(savedPath, yaml + '\n', 'utf-8');
+    console.log(`  Token 用量: 输入 ${result.usage.input_tokens}, 输出 ${result.usage.output_tokens}`);
+    return { yaml, savedPath };
+}

package/dist/cli/explain.js

@@ -34,7 +34,7 @@ function buildLayers(steps) {
             remaining.delete(s.id);
             for (const [id, depList] of deps) {
                 if (depList.includes(s.id)) {
-                    inDegree.set(id, (inDegree.get(id) || 1) - 1);
+                    inDegree.set(id, (inDegree.get(id) ?? 0) - 1);
                 }
             }
         }
@@ -77,10 +77,12 @@ export function explainWorkflow(workflow) {
         for (const step of layer.steps) {
             const role = formatRole(step.role);
             // 取 task 的第一行作为摘要
-            const taskSummary = (step.task || '').split('\n')[0].trim().slice(0, 60);
+            const firstLine = (step.task || '').split('\n')[0].trim();
+            const taskSummary = firstLine.slice(0, 60);
+            const truncated = firstLine.length > 60 || (step.task || '').includes('\n');
             lines.push(`  • ${step.id} (${role})`);
             if (taskSummary) {
-                lines.push(`    ${taskSummary}${(step.task || '').length > 60 ? '...' : ''}`);
+                lines.push(`    ${taskSummary}${truncated ? '...' : ''}`);
             }
             // 标注条件
             if (step.condition) {
@@ -96,7 +98,7 @@ export function explainWorkflow(workflow) {
     }
     // 汇总
     const totalSteps = workflow.steps.length;
-    const maxParallel = Math.max(...layers.map(l => l.steps.length));
+    const maxParallel = layers.length > 0 ? Math.max(...layers.map(l => l.steps.length)) : 0;
     const hasLoop = workflow.steps.some(s => s.loop);
     const hasCondition = workflow.steps.some(s => s.condition);
     lines.push(`总计 ${totalSteps} 个步骤，${layers.length} 层执行，最大并行度 ${maxParallel}。`);

package/dist/cli/init-workflow.js

@@ -4,10 +4,14 @@
 import { createInterface } from 'readline';
 import { writeFileSync, mkdirSync, existsSync } from 'fs';
 import { resolve } from 'path';
+/** Escape double quotes for YAML string values */
+function yamlEscape(s) {
+    return s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
 export function generateWorkflowYaml(opts) {
     const lines = [
-        `name: "${opts.name}"`,
-        `description: "${opts.description}"`,
+        `name: "${yamlEscape(opts.name)}"`,
+        `description: "${yamlEscape(opts.description)}"`,
         '',
         'agents_dir: "agency-agents-zh"',
         '',
@@ -21,22 +25,27 @@ export function generateWorkflowYaml(opts) {
     if (opts.hasInputs && opts.inputs.length > 0) {
         lines.push('', 'inputs:');
         for (const input of opts.inputs) {
-            lines.push(`  - name: ${input.name}`);
-            lines.push(`    description: "${input.description}"`);
+            lines.push(`  - name: "${yamlEscape(input.name)}"`);
+            lines.push(`    description: "${yamlEscape(input.description)}"`);
             lines.push(`    required: ${input.required}`);
         }
     }
     lines.push('', 'steps:');
     for (let i = 0; i < opts.roles.length; i++) {
         const step = opts.roles[i];
-        lines.push(`  - id: ${step.id}`);
-        lines.push(`    role: "${step.role}"`);
-        lines.push(`    task: |`);
-        // Indent task lines for YAML block scalar
-        for (const taskLine of step.task.split('\n')) {
-            lines.push(`      ${taskLine}`);
+        lines.push(`  - id: "${yamlEscape(step.id)}"`);
+        lines.push(`    role: "${yamlEscape(step.role)}"`);
+        // 单行 task 用引号，多行用 block scalar
+        if (step.task.includes('\n')) {
+            lines.push(`    task: |`);
+            for (const taskLine of step.task.split('\n')) {
+                lines.push(`      ${taskLine}`);
+            }
+        }
+        else {
+            lines.push(`    task: "${yamlEscape(step.task)}"`);
         }
-        lines.push(`    output: ${step.output}`);
+        lines.push(`    output: "${yamlEscape(step.output)}"`);
         if (i > 0) {
             lines.push(`    depends_on: [${opts.roles[i - 1].id}]`);
         }

package/dist/cli/watch.js

@@ -6,7 +6,7 @@ const ICONS = {
     running: '🔄',
     done: '✅',
     error: '❌',
-    skipped: '⏭️',
+    skipped: '⏩',
 };
 /**
  * 创建 watch 渲染器，返回 ProgressCallback
@@ -50,7 +50,9 @@ export function createWatchRenderer(workflowName, stepIds, roles) {
             lines.push(line);
         }
         lines.push(`│${''.padEnd(boxWidth - 2)}│`);
-        lines.push(`│ Progress: ${bar} ${completed}/${total}  ${elapsed}s${''.padEnd(Math.max(0, boxWidth - 38 - elapsed.length))}│`);
+        const progressContent = `Progress: ${bar} ${completed}/${total}  ${elapsed}s`;
+        const progressPad = Math.max(0, boxWidth - 4 - progressContent.length);
+        lines.push(`│ ${progressContent}${''.padEnd(progressPad)} │`);
         lines.push(`└${'─'.repeat(boxWidth - 2)}┘`);
         // 写到 stderr 避免与正常输出混合
         for (const line of lines) {

package/dist/cli.js

@@ -41,13 +41,16 @@ async function main() {
         case 'explain':
             await handleExplain();
             break;
+        case 'compose':
+            await handleCompose();
+            break;
         case '--version':
         case '-v':
             console.log(getVersion());
             break;
         default: {
             // 容错：用户可能漏了空格，如 "planworkflows/x.yaml"
-            const knownCmds = ['run', 'validate', 'plan', 'explain', 'roles'];
+            const knownCmds = ['run', 'validate', 'plan', 'explain', 'compose', 'roles', 'init'];
             const match = knownCmds.find(c => command.startsWith(c) && command.length > c.length);
             if (match) {
                 console.error(`看起来少了个空格？试试:\n  ao ${match} ${command.slice(match.length)}\n`);
@@ -166,6 +169,53 @@ async function handleExplain() {
         process.exit(1);
     }
 }
+async function handleCompose() {
+    const description = args[1];
+    if (!description) {
+        console.error('用法: ao compose "用一句话描述你想要的工作流"');
+        console.error('');
+        console.error('示例:');
+        console.error('  ao compose "PR 代码审查，要覆盖安全和性能"');
+        console.error('  ao compose "写一篇技术博客，需要调研、写稿、审校"');
+        console.error('  ao compose "用户反馈分析，分类后分别给产品和技术团队"');
+        console.error('');
+        console.error('选项:');
+        console.error('  --provider <name>   LLM 提供商 (默认 deepseek)');
+        console.error('  --model <name>      模型名 (默认 deepseek-chat)');
+        process.exit(1);
+    }
+    const provider = (getArgValue('--provider') || 'deepseek');
+    const model = getArgValue('--model') || (provider === 'deepseek' ? 'deepseek-chat' : provider === 'claude' ? 'claude-sonnet-4-20250514' : 'gpt-4o');
+    const agentsDir = getArgValue('--agents-dir') || resolveAgentsDir();
+    try {
+        const { composeWorkflow } = await import('./cli/compose.js');
+        const { yaml, savedPath } = await composeWorkflow({
+            description,
+            agentsDir: resolve(agentsDir),
+            llmConfig: { provider, model },
+        });
+        console.log(`\n  ✅ 工作流已生成: ${savedPath}\n`);
+        console.log('  预览:');
+        // 显示前 30 行
+        const previewLines = yaml.split('\n').slice(0, 30);
+        for (const line of previewLines) {
+            console.log(`    ${line}`);
+        }
+        if (yaml.split('\n').length > 30) {
+            console.log('    ...');
+        }
+        console.log('');
+        console.log('  接下来可以:');
+        console.log(`    ao plan ${savedPath}       查看执行计划`);
+        console.log(`    ao validate ${savedPath}   校验工作流`);
+        console.log(`    ao run ${savedPath}        运行工作流`);
+        console.log('');
+    }
+    catch (err) {
+        console.error(`\n错误: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+}
 async function handleInit() {
     // ao init --workflow: 交互式创建工作流
     if (args.includes('--workflow')) {
@@ -302,6 +352,7 @@ function printHelp() {
   Commands:
     init                              下载/更新 agency-agents-zh
     init --workflow                    交互式创建新工作流
+    compose "描述"                     AI 智能编排工作流（一句话生成 YAML）
     run <workflow.yaml>               执行工作流
     validate <workflow.yaml>          校验工作流定义
     plan <workflow.yaml>              查看执行计划
@@ -320,6 +371,7 @@ function printHelp() {
 
   Examples:
     ao init
+    ao compose "PR 代码审查，覆盖安全和性能"
     ao run workflows/story-creation.yaml -i premise='一个时间旅行的故事' -i style='悬疑'
     ao run workflows/product-review.yaml -i prd_content=@prd.md
     ao plan workflows/content-pipeline.yaml

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { ClaudeConnector } from './connectors/claude.js';
 export { OllamaConnector } from './connectors/ollama.js';
 export { OpenAICompatibleConnector } from './connectors/openai-compatible.js';
 export { saveResults, loadPreviousContext, findLatestOutput } from './output/reporter.js';
+export { composeWorkflow, buildRoleCatalog, extractYamlFromResponse } from './cli/compose.js';
 export type { WorkflowDefinition, StepDefinition, LLMConfig, LLMConnector, LLMResult, AgentDefinition, WorkflowResult, StepResult, DAGNode, } from './types.js';
 /**
  * 一行运行工作流（高级 API）

package/dist/index.js

@@ -14,6 +14,7 @@ export { ClaudeConnector } from './connectors/claude.js';
 export { OllamaConnector } from './connectors/ollama.js';
 export { OpenAICompatibleConnector } from './connectors/openai-compatible.js';
 export { saveResults, loadPreviousContext, findLatestOutput } from './output/reporter.js';
+export { composeWorkflow, buildRoleCatalog, extractYamlFromResponse } from './cli/compose.js';
 import { parseWorkflow, validateWorkflow } from './core/parser.js';
 import { buildDAG } from './core/dag.js';
 import { executeDAG } from './core/executor.js';

package/dist/types.d.ts

@@ -71,6 +71,7 @@ export interface AgentDefinition {
     description: string;
     emoji?: string;
     tools?: string;
+    rolePath?: string;
     systemPrompt: string;
 }
 /** 执行结果 */

package/integrations/antigravity/README.md

@@ -5,18 +5,25 @@
 ## 安装
 
 ```bash
-# 1. 安装角色定义
+# 1. 下载 186 个 AI 角色
 cd your-project
 git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
 
-# 2. 将 AGENTS.md 复制到项目根目录
-cp integrations/antigravity/AGENTS.md AGENTS.md
+# 2. 下载工作流模板和技能文件
+git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp
+cp -r .ao-tmp/workflows ./workflows
+cp .ao-tmp/integrations/antigravity/AGENTS.md ./AGENTS.md
+rm -rf .ao-tmp
+
+# 3. 开始使用
+# 在 Antigravity 中直接说：运行 workflows/story-creation.yaml
 ```
 
-如果项目根目录已有 `AGENTS.md`，将内容追加：
+如果项目根目录已有 `AGENTS.md`，可将内容追加而非覆盖：
 
 ```bash
-cat integrations/antigravity/AGENTS.md >> AGENTS.md
+# 替换上面第 2 步中的 cp 命令为：
+cat .ao-tmp/integrations/antigravity/AGENTS.md >> ./AGENTS.md
 ```
 
 ## 使用方式

package/integrations/codex/README.md

@@ -5,19 +5,26 @@
 ## 安装
 
 ```bash
-# 1. 安装角色定义
+# 1. 下载 186 个 AI 角色
 cd your-project
 git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
 
-# 2. 复制 workflow-runner 指令到 .codex 目录
+# 2. 下载工作流模板和技能文件
+git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp
+cp -r .ao-tmp/workflows ./workflows
 mkdir -p .codex
-cp integrations/codex/instructions.md .codex/instructions.md
+cp .ao-tmp/integrations/codex/instructions.md .codex/instructions.md
+rm -rf .ao-tmp
+
+# 3. 开始使用
+# 在 Codex CLI 中直接说：运行 workflows/story-creation.yaml
 ```
 
-如果 `.codex/instructions.md` 已存在，将内容追加：
+如果 `.codex/instructions.md` 已存在，可将内容追加而非覆盖：
 
 ```bash
-cat integrations/codex/instructions.md >> .codex/instructions.md
+# 替换上面第 2 步中的 cp 命令为：
+cat .ao-tmp/integrations/codex/instructions.md >> .codex/instructions.md
 ```
 
 ## 使用方式

package/integrations/cursor/README.md

@@ -5,16 +5,19 @@
 ## 安装
 
 ```bash
-# 1. 安装角色定义到项目
+# 1. 下载 186 个 AI 角色
 cd your-project
 git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
 
-# 2. 复制工作流模板
-git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp && cp -r .ao-tmp/workflows ./workflows && rm -rf .ao-tmp
-
-# 3. 添加工作流执行规则
+# 2. 下载工作流模板和技能文件
+git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp
+cp -r .ao-tmp/workflows ./workflows
 mkdir -p .cursor/rules
-cp agency-orchestrator/integrations/cursor/workflow-runner.mdc .cursor/rules/
+cp .ao-tmp/integrations/cursor/workflow-runner.mdc .cursor/rules/
+rm -rf .ao-tmp
+
+# 3. 开始使用
+# 在 Cursor 中直接说：运行 workflows/story-creation.yaml
 ```
 
 ## 使用方式
@@ -87,11 +90,11 @@ ao run workflows/story-creation.yaml -i 'premise=时间旅行'
 
 ## 可用工作流
 
-| 工作流 | 说明 | 角色 |
+| 工作流 | 文件 | 说明 |
 |--------|------|------|
-| `story-creation.yaml` | 短篇小说创作 | 叙事学家 → 心理学家 + 叙事设计师 → 内容创作者 |
-| `product-review.yaml` | 产品需求评审 | 产品经理 → 架构师 + UX 研究员 → 产品经理 |
-| `content-pipeline.yaml` | 内容创作流水线 | 策略师 → 创作者 + SEO → 编辑 |
+| 短篇小说创作 | `story-creation.yaml` | 叙事学家 → 心理学家 + 叙事设计师 → 内容创作者 |
+| 产品需求评审 | `product-review.yaml` | 产品经理 → 架构师 + UX 研究员 → 产品经理 |
+| 内容流水线 | `content-pipeline.yaml` | 策略师 → 创作者 + SEO → 编辑 |
 
 ## 自定义
 

package/integrations/deerflow/README.md

@@ -5,13 +5,19 @@
 ## 安装
 
 ```bash
-# 1. 安装角色定义
+# 1. 下载 186 个 AI 角色
 cd your-project
 git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
 
-# 2. 将 SKILL.md 复制到 DeerFlow 的自定义技能目录
+# 2. 下载工作流模板和技能文件
+git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp
+cp -r .ao-tmp/workflows ./workflows
 mkdir -p skills/custom/ao-workflow-runner
-cp integrations/deerflow/SKILL.md skills/custom/ao-workflow-runner/SKILL.md
+cp .ao-tmp/integrations/deerflow/SKILL.md skills/custom/ao-workflow-runner/SKILL.md
+rm -rf .ao-tmp
+
+# 3. 开始使用
+# 在 DeerFlow 中直接说：运行 workflows/story-creation.yaml
 ```
 
 ## 使用方式

package/integrations/gemini-cli/README.md

@@ -5,18 +5,25 @@
 ## 安装
 
 ```bash
-# 1. 安装角色定义
+# 1. 下载 186 个 AI 角色
 cd your-project
 git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
 
-# 2. 将 workflow-runner 指令追加到项目根目录的 GEMINI.md
-cat integrations/gemini-cli/GEMINI.md >> GEMINI.md
+# 2. 下载工作流模板和技能文件
+git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp
+cp -r .ao-tmp/workflows ./workflows
+cp .ao-tmp/integrations/gemini-cli/GEMINI.md ./GEMINI.md
+rm -rf .ao-tmp
+
+# 3. 开始使用
+# 在 Gemini CLI 中直接说：运行 workflows/story-creation.yaml
 ```
 
-如果项目根目录还没有 `GEMINI.md`，直接复制即可：
+如果项目根目录已有 `GEMINI.md`，可将内容追加而非覆盖：
 
 ```bash
-cp integrations/gemini-cli/GEMINI.md GEMINI.md
+# 替换上面第 2 步中的 cp 命令为：
+cat .ao-tmp/integrations/gemini-cli/GEMINI.md >> ./GEMINI.md
 ```
 
 ## 使用方式

package/integrations/kiro/README.md

@@ -5,16 +5,19 @@
 ## 安装
 
 ```bash
-# 1. 安装角色定义到项目
+# 1. 下载 186 个 AI 角色
 cd your-project
 git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
 
-# 2. 复制工作流模板
-git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp && cp -r .ao-tmp/workflows ./workflows && rm -rf .ao-tmp
-
-# 3. 添加工作流执行规则
+# 2. 下载工作流模板和技能文件
+git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp
+cp -r .ao-tmp/workflows ./workflows
 mkdir -p .kiro/steering
-cp agency-orchestrator/integrations/kiro/ao-workflow-runner.md .kiro/steering/
+cp .ao-tmp/integrations/kiro/ao-workflow-runner.md .kiro/steering/
+rm -rf .ao-tmp
+
+# 3. 开始使用
+# 在 Kiro 中直接说：运行 workflows/story-creation.yaml
 ```
 
 ## 使用方式

package/integrations/trae/README.md

@@ -5,16 +5,19 @@
 ## 安装
 
 ```bash
-# 1. 安装角色定义到项目
+# 1. 下载 186 个 AI 角色
 cd your-project
 git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git
 
-# 2. 复制工作流模板
-git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp && cp -r .ao-tmp/workflows ./workflows && rm -rf .ao-tmp
-
-# 3. 添加工作流执行规则
+# 2. 下载工作流模板和技能文件
+git clone --depth 1 https://github.com/jnMetaCode/agency-orchestrator.git .ao-tmp
+cp -r .ao-tmp/workflows ./workflows
 mkdir -p .trae/rules
-cp agency-orchestrator/integrations/trae/ao-workflow-runner.md .trae/rules/
+cp .ao-tmp/integrations/trae/ao-workflow-runner.md .trae/rules/
+rm -rf .ao-tmp
+
+# 3. 开始使用
+# 在 Trae 中直接说：运行 workflows/story-creation.yaml
 ```
 
 ## 使用方式

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agency-orchestrator",
-  "version": "0.3.0",
-  "description": "Multi-agent workflow orchestrator — 186 ready-to-use AI roles, YAML-defined pipelines, auto DAG parallelism, zero code required",
+  "version": "0.3.2",
+  "description": "Multi-agent workflow orchestrator — 186 AI roles, YAML pipelines, auto DAG parallelism, AI-powered workflow composer",
   "keywords": [
     "multi-agent",
     "ai-agents",
@@ -44,7 +44,7 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "test": "npx tsx test/run.ts && npx tsx test/condition.ts && npx tsx test/cli.ts && npx tsx test/e2e.ts && npx tsx test/e2e-condition.ts && npx tsx test/e2e-loop.ts",
+    "test": "npx tsx test/run.ts && npx tsx test/condition.ts && npx tsx test/cli.ts && npx tsx test/compose.ts && npx tsx test/e2e.ts && npx tsx test/e2e-condition.ts && npx tsx test/e2e-loop.ts",
     "prepublishOnly": "npm run build"
   },
   "files": [