agency-orchestrator 0.5.1 → 0.5.3

package/README.en.md

@@ -11,7 +11,7 @@
 
 **One sentence → full plan · 211 expert AI roles · Zero-code YAML · 10 LLM providers · 7 need no API key**
 
-> **Note:** `ao compose --run` auto-detects your language. For English input, it uses [agency-agents](https://github.com/msitarzewski/agency-agents) (170+ English roles). Use `ao init --lang en` to download the English role library. **6 English workflow templates** are ready in `workflows/en/` — more coming in v0.6.
+> **Note:** `ao compose --run` auto-detects your language. Both 211 Chinese roles and 170+ English roles ([agency-agents](https://github.com/msitarzewski/agency-agents), MIT) are **bundled in the npm package — no extra download needed**. **6 English workflow templates** are ready in `workflows/en/` — more coming in v0.6.
 
 > 📖 [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
 
@@ -217,8 +217,8 @@ All API providers support custom `base_url` and `api_key`, compatible with any O
 
 ```bash
 ao demo                              # Zero-config multi-agent demo
-ao init                              # Download 211 Chinese AI roles
-ao init --lang en                    # Download 170+ English AI roles
+ao init                              # (Optional) Copy 211 Chinese roles locally for editing
+ao init --lang en                    # (Optional) Copy 170+ English roles locally for editing
 ao init --workflow                    # Interactive workflow creator
 ao compose "description"             # AI-powered workflow generation
 ao compose "description" --run       # Generate AND execute in one command

package/README.md

@@ -216,8 +216,8 @@ analyze ──→ tech_review  ──→ summary
 
 ```bash
 ao demo                              # 零配置体验多智能体协作
-ao init                              # 下载 211 个中文 AI 角色
-ao init --lang en                    # 下载 170+ 个英文 AI 角色
+ao init                              # （可选）复制 211 个中文角色到本地以便编辑
+ao init --lang en                    # （可选）复制 170+ 个英文角色到本地以便编辑
 ao init --workflow                    # 交互式创建工作流
 ao compose "一句话描述"                # AI 智能编排工作流
 ao compose "一句话描述" --run          # 编排并立即执行

package/dist/cli/compose.js

@@ -8,6 +8,7 @@ import { listAgents } from '../agents/loader.js';
 import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve, relative } from 'node:path';
 import { createConnector } from '../connectors/factory.js';
+import { t } from '../i18n.js';
 /**
  * 从 agents 目录构建精简的角色目录
  */
@@ -299,7 +300,7 @@ export async function composeWorkflow(options) {
     // 1. 构建角色目录
     const roles = buildRoleCatalog(agentsDir);
     if (roles.length === 0) {
-        throw new Error(`角色目录为空: ${agentsDir}\n请先运行 ao init 下载角色定义`);
+        throw new Error(t('compose.empty_catalog', { dir: agentsDir }));
     }
     const catalog = formatCatalogForPrompt(roles);
     // 2. 构建 prompt
@@ -311,7 +312,7 @@ export async function composeWorkflow(options) {
     });
     const userPrompt = buildComposeUserPrompt(description, lang);
     // 3. 调用 LLM
-    console.log(`  正在用 AI 编排工作流...（${roles.length} 个角色可选）\n`);
+    console.log(`  ${t('compose.generating', { n: roles.length })}\n`);
     const connector = createConnector(llmConfig);
     const result = await connector.chat(systemPrompt, userPrompt, {
         ...llmConfig,
@@ -320,7 +321,7 @@ export async function composeWorkflow(options) {
     // 4. 提取 YAML
     const yaml = extractYamlFromResponse(result.content);
     if (!yaml || !yaml.includes('steps:')) {
-        throw new Error('AI 生成的内容不是有效的 workflow YAML，请重试或调整描述');
+        throw new Error(t('compose.invalid_yaml'));
     }
     // 5. 保存（避免覆盖）
     const workflowsDir = resolve('workflows');
@@ -333,21 +334,55 @@ export async function composeWorkflow(options) {
     const savedPath = resolve(workflowsDir, fileName);
     writeFileSync(savedPath, yaml + '\n', 'utf-8');
     const relativePath = relative(process.cwd(), savedPath);
-    console.log(`  Token 用量: 输入 ${result.usage.input_tokens}, 输出 ${result.usage.output_tokens}`);
-    // 6. 校验生成的 YAML
+    if (process.env.AO_VERBOSE) {
+        console.log(`  ${t('compose.tokens', { in: result.usage.input_tokens, out: result.usage.output_tokens })}`);
+    }
+    // 6. 校验生成的 YAML（含角色路径真实性校验，防 LLM 幻觉）
     const warnings = [];
-    try {
+    const validRolePaths = new Set(roles.map(r => r.path));
+    async function validateGenerated(path) {
         const { parseWorkflow, validateWorkflow } = await import('../core/parser.js');
-        const workflow = parseWorkflow(savedPath);
-        const errors = validateWorkflow(workflow);
-        if (errors.length > 0) {
-            for (const e of errors) {
-                warnings.push(e);
+        const errors = [];
+        const invalidRoles = [];
+        try {
+            const workflow = parseWorkflow(path);
+            errors.push(...validateWorkflow(workflow));
+            for (const step of workflow.steps) {
+                if (step.role && !validRolePaths.has(step.role)) {
+                    invalidRoles.push(step.role);
+                    errors.push(`step "${step.id}" 的 role "${step.role}" 不存在于角色库中`);
+                }
             }
         }
+        catch (err) {
+            errors.push(`YAML 解析失败: ${err instanceof Error ? err.message : err}`);
+        }
+        return { errors, invalidRoles };
     }
-    catch (err) {
-        warnings.push(`YAML 解析失败: ${err instanceof Error ? err.message : err}`);
+    const first = await validateGenerated(savedPath);
+    // 发现幻觉角色 → 让 LLM 修一次
+    if (first.invalidRoles.length > 0) {
+        console.log(`  检测到 ${first.invalidRoles.length} 个不存在的角色，自动重新生成...`);
+        const retryPrompt = lang === 'en'
+            ? `The following role paths in your previous YAML do NOT exist in the catalog: ${first.invalidRoles.join(', ')}.\n\nRegenerate the FULL YAML. Use ONLY role paths from the catalog above. Do not invent new paths.`
+            : `你上次生成的 YAML 里有不存在的 role 路径：${first.invalidRoles.join('、')}。\n\n请重新生成完整 YAML，role 必须严格使用上方角色目录中列出的路径，不要编造。`;
+        try {
+            const retryResult = await connector.chat(systemPrompt, `${userPrompt}\n\n${retryPrompt}`, {
+                ...llmConfig,
+                max_tokens: llmConfig.max_tokens || 4096,
+            });
+            const retryYaml = extractYamlFromResponse(retryResult.content);
+            if (retryYaml && retryYaml.includes('steps:')) {
+                writeFileSync(savedPath, retryYaml + '\n', 'utf-8');
+                const second = await validateGenerated(savedPath);
+                warnings.push(...second.errors);
+                return { yaml: retryYaml, savedPath, relativePath, warnings };
+            }
+        }
+        catch (err) {
+            warnings.push(`自动修正失败（保留原始输出）: ${err instanceof Error ? err.message : err}`);
+        }
     }
+    warnings.push(...first.errors);
     return { yaml, savedPath, relativePath, warnings };
 }

package/dist/cli.js

@@ -16,8 +16,17 @@ import { buildDAG, formatDAG } from './core/dag.js';
 import { listAgents } from './agents/loader.js';
 import { run } from './index.js';
 import { scheduleUpdateCheck } from './utils/version-check.js';
+import { t, detectLang } from './i18n.js';
+// Suppress Node's DEP0190 warning from legitimate shell:true on Windows (.cmd shims).
+const origEmit = process.emit.bind(process);
+process.emit = function (name, data, ...rest) {
+    if (name === 'warning' && data && data.code === 'DEP0190')
+        return false;
+    return origEmit(name, data, ...rest);
+};
 const args = process.argv.slice(2);
 const command = args[0];
+detectLang(process.argv);
 async function main() {
     // 启动时提示新版本（仅 TTY，24h 缓存，失败静默）
     scheduleUpdateCheck(getVersion());
@@ -123,18 +132,18 @@ async function handleRun() {
 function handleValidate() {
     const filePath = args[1];
     if (!filePath) {
-        console.error('用法: ao validate <workflow.yaml>');
+        console.error(t('validate.usage'));
         process.exit(1);
     }
     try {
         const workflow = parseWorkflow(resolve(filePath));
         const errors = validateWorkflow(workflow);
         if (errors.length === 0) {
-            console.log(`  ${workflow.name} — 校验通过`);
-            console.log(`  ${workflow.steps.length} 个步骤, ${(workflow.inputs || []).length} 个输入`);
+            console.log(`  ${t('validate.ok', { name: workflow.name })}`);
+            console.log(`  ${t('validate.stats', { steps: workflow.steps.length, inputs: (workflow.inputs || []).length })}`);
         }
         else {
-            console.error(`  ${workflow.name} — 校验失败:\n`);
+            console.error(`  ${t('validate.failed', { name: workflow.name })}\n`);
             for (const err of errors) {
                 console.error(`  - ${err}`);
             }
@@ -142,21 +151,21 @@ function handleValidate() {
         }
     }
     catch (err) {
-        console.error(`错误: ${err instanceof Error ? err.message : err}`);
+        console.error(`${t('error.prefix')}: ${err instanceof Error ? err.message : err}`);
         process.exit(1);
     }
 }
 function handlePlan() {
     const filePath = args[1];
     if (!filePath) {
-        console.error('用法: ao plan <workflow.yaml>');
+        console.error(t('plan.usage'));
         process.exit(1);
     }
     try {
         const workflow = parseWorkflow(resolve(filePath));
         const errors = validateWorkflow(workflow);
         if (errors.length > 0) {
-            console.error(`校验失败:\n${errors.map(e => `  - ${e}`).join('\n')}`);
+            console.error(`${t('plan.validate_failed')}\n${errors.map(e => `  - ${e}`).join('\n')}`);
             process.exit(1);
         }
         const dag = buildDAG(workflow);
@@ -164,7 +173,7 @@ function handlePlan() {
         console.log(formatDAG(dag));
     }
     catch (err) {
-        console.error(`错误: ${err instanceof Error ? err.message : err}`);
+        console.error(`${t('error.prefix')}: ${err instanceof Error ? err.message : err}`);
         process.exit(1);
     }
 }
@@ -242,10 +251,10 @@ async function handleCompose() {
             autoRun,
             lang: composeLang,
         });
-        console.log(`\n  ✅ 工作流已生成: ${relativePath}\n`);
+        console.log(`\n  ${t('compose.generated', { path: relativePath })}\n`);
         // 校验警告
         if (warnings.length > 0) {
-            console.log('  ⚠️  校验发现问题（AI 生成的 YAML 可能需要手动调整）:');
+            console.log(`  ${t('compose.warnings_header')}`);
             for (const w of warnings) {
                 console.log(`    - ${w}`);
             }
@@ -253,13 +262,13 @@ async function handleCompose() {
         }
         if (autoRun) {
             // --run 模式：校验有严重问题时不执行
-            if (warnings.some(w => w.includes('解析失败'))) {
-                console.error('  生成的 YAML 有解析错误，无法自动运行。请手动修复后执行:');
+            if (warnings.some(w => w.includes('解析失败') || w.toLowerCase().includes('parse failed'))) {
+                console.error(`  ${t('compose.retry_yaml_bad')}`);
                 console.error(`    ao run ${relativePath}`);
                 process.exit(1);
             }
             console.log('─'.repeat(50));
-            console.log('  开始执行工作流...\n');
+            console.log(`  ${t('compose.auto_running')}\n`);
             // 保底：如果 LLM 仍然生成了 required inputs，用用户描述填充
             const { parseWorkflow } = await import('./core/parser.js');
             const workflow = parseWorkflow(resolve(savedPath));
@@ -278,7 +287,7 @@ async function handleCompose() {
             process.exit(result.success ? 0 : 1);
         }
         // 非 --run 模式：显示预览和下一步提示
-        console.log('  预览:');
+        console.log(`  ${t('compose.preview')}`);
         const previewLines = yaml.split('\n').slice(0, 30);
         for (const line of previewLines) {
             console.log(`    ${line}`);
@@ -287,14 +296,14 @@ async function handleCompose() {
             console.log('    ...');
         }
         console.log('');
-        console.log('  接下来可以:');
-        console.log(`    ao validate ${relativePath}   校验工作流`);
-        console.log(`    ao plan ${relativePath}       查看执行计划`);
-        console.log(`    ao run ${relativePath}        运行工作流`);
+        console.log(`  ${t('compose.next_steps')}`);
+        console.log(`    ao validate ${relativePath}   ${t('compose.next.validate')}`);
+        console.log(`    ao plan ${relativePath}       ${t('compose.next.plan')}`);
+        console.log(`    ao run ${relativePath}        ${t('compose.next.run')}`);
         console.log('');
     }
     catch (err) {
-        console.error(`\n错误: ${err instanceof Error ? err.message : err}`);
+        console.error(`\n${t('error.prefix')}: ${err instanceof Error ? err.message : err}`);
         process.exit(1);
     }
 }
@@ -512,57 +521,6 @@ function getVersion() {
     }
 }
 function printHelp() {
-    console.log(`
-  agency-orchestrator — Multi-Agent Workflow Engine
-  基于 agency-agents-zh 的多智能体编排引擎
-
-  Quick Start:
-    ao demo                           零配置体验多智能体协作
-    ao init                           下载 AI 角色定义（中文）
-    ao init --lang en                 Download English AI roles
-    ao roles                          查看所有可用角色
-    ao plan <workflow.yaml>           查看执行计划 (DAG)
-    ao run <workflow.yaml> [options]   执行工作流
-
-  Commands:
-    demo                              零配置体验多智能体协作（mock + 真实 AI）
-    init                              下载/更新角色库 (--lang en 下载英文版)
-    init --workflow                    交互式创建新工作流
-    compose "描述"                     AI 智能编排工作流（一句话生成 YAML）
-    compose "描述" --run               生成并立即运行（一句话出结果）
-    serve                             启动 MCP Server（供 Claude Code / Cursor 调用）
-    run <workflow.yaml>               执行工作流
-    validate <workflow.yaml>          校验工作流定义
-    plan <workflow.yaml>              查看执行计划
-    explain <workflow.yaml>           用自然语言解释执行计划
-    roles [--agents-dir path]         列出可用角色
-
-  Options:
-    --input, -i key=value    传入输入变量
-    --input, -i key=@file    从文件读取变量值
-    --provider <name>        覆盖 YAML 中的 LLM provider (如 claude-code, deepseek)
-    --model <name>           覆盖 YAML 中的模型名
-    --output dir             输出目录 (默认 ao-output/)
-    --resume <dir|last>      从上次运行恢复（加载已完成步骤的输出）
-    --from <step-id>         配合 --resume，从指定步骤重新执行
-    --watch                  实时进度显示（终端 UI）
-    --quiet, -q              静默模式
-    --version, -v            版本号
-
-  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
-
-  Resume (基于上次结果迭代):
-    ao run workflow.yaml --resume last                    # 跳过上次已完成的步骤
-    ao run workflow.yaml --resume last --from summary     # 从 summary 步骤重新执行
-    ao run workflow.yaml --resume ao-output/xxx/         # 指定具体输出目录
-
-  Agents (中文): https://github.com/jnMetaCode/agency-agents-zh
-  Agents (English): https://github.com/msitarzewski/agency-agents
-  `);
+    console.log(t('help.text'));
 }
 main();

package/dist/connectors/claude-code.js

@@ -13,6 +13,7 @@ import { spawn } from 'node:child_process';
 import { writeFileSync, unlinkSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { t } from '../i18n.js';
 export class ClaudeCodeConnector {
     async chat(systemPrompt, userMessage, config) {
         const timeout = config.timeout || 600_000; // 默认 10 分钟
@@ -69,7 +70,7 @@ export class ClaudeCodeConnector {
                 if (now - lastProgressTime > 10_000) {
                     lastProgressTime = now;
                     const kb = (receivedBytes / 1024).toFixed(1);
-                    process.stderr.write(`  📡 已接收 ${kb}KB...\n`);
+                    process.stderr.write(`  ${t('stream.received', { size: kb })}\n`);
                 }
             });
             child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });

package/dist/connectors/cli-base.js

@@ -8,6 +8,7 @@
  * 避免 ENAMETOOLONG 错误（GitHub issue #1）
  */
 import { spawn } from 'node:child_process';
+import { t } from '../i18n.js';
 /**
  * 命令行参数安全长度上限
  * claude -p 等 CLI 工具通过命令行参数传大 prompt 会严重变慢
@@ -29,7 +30,7 @@ export class CLIBaseConnector {
         const args = useStdin
             ? (this.cfg.buildStdinArgs?.(config) ?? this.cfg.buildArgs('-', config))
             : this.cfg.buildArgs(fullPrompt, config);
-        const timeout = config.timeout || 300_000; // 默认 5 分钟，effort=low 正常 1-3 分钟内响应
+        const timeout = config.timeout || 600_000; // 默认 10 分钟（gateway/MiniMax 等 CLI provider 可能单步 5+ 分钟）
         return new Promise((resolve, reject) => {
             const child = spawn(this.cfg.command, args, {
                 env: { ...process.env },
@@ -60,7 +61,7 @@ export class CLIBaseConnector {
                 if (now - lastProgressTime > 10_000) {
                     lastProgressTime = now;
                     const kb = (receivedBytes / 1024).toFixed(1);
-                    process.stderr.write(`  📡 已接收 ${kb}KB...\n`);
+                    process.stderr.write(`  ${t('stream.received', { size: kb })}\n`);
                 }
             });
             child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });

package/dist/core/dag.js

@@ -1,3 +1,4 @@
+import { t } from '../i18n.js';
 /**
  * 从 WorkflowDefinition 构建 DAG
  */
@@ -82,7 +83,7 @@ function topologicalLevels(nodes) {
  * 格式化 DAG 为可读文本（用于 `ao plan` 命令）
  */
 export function formatDAG(dag) {
-    const lines = ['执行计划:\n'];
+    const lines = [`${t('dag.title')}\n`];
     for (let i = 0; i < dag.levels.length; i++) {
         const level = dag.levels[i];
         const parallel = level.length > 1;
@@ -90,16 +91,16 @@ export function formatDAG(dag) {
             const node = dag.nodes.get(level[j]);
             const step = node.step;
             const prefix = parallel ? (j === 0 ? '┌' : j === level.length - 1 ? '└' : '├') : '→';
-            const tag = parallel ? ' (并行)' : '';
-            lines.push(`  第${i + 1}层 ${prefix} [${step.id}] ${step.role || step.type}${tag}`);
+            const tag = parallel ? t('dag.parallel') : '';
+            lines.push(`  ${t('dag.layer', { n: i + 1 })} ${prefix} [${step.id}] ${step.role || step.type}${tag}`);
             if (node.dependencies.length > 0) {
-                lines.push(`         依赖: ${node.dependencies.join(', ')}`);
+                lines.push(`         ${t('dag.deps')}: ${node.dependencies.join(', ')}`);
             }
             if (step.condition) {
-                lines.push(`         条件: ${step.condition}`);
+                lines.push(`         ${t('dag.condition')}: ${step.condition}`);
             }
             if (step.loop) {
-                lines.push(`         循环: → ${step.loop.back_to} (最多 ${step.loop.max_iterations} 次)`);
+                lines.push(`         ${t('dag.loop', { to: step.loop.back_to, n: step.loop.max_iterations })}`);
             }
         }
         if (i < dag.levels.length - 1)

package/dist/core/executor.js

@@ -10,7 +10,7 @@ export async function executeDAG(dag, options) {
     const startTime = Date.now();
     const stepResults = [];
     const isCLI = llmConfig.provider.endsWith('-cli') || llmConfig.provider === 'claude-code';
-    const timeout = llmConfig.timeout || (isCLI ? 300_000 : 120_000); // CLI 5分钟，API 2分钟
+    const timeout = llmConfig.timeout || (isCLI ? 600_000 : 120_000); // CLI 10分钟（gateway/MiniMax 等可能单步 5+ 分钟），API 2分钟
     const maxRetry = llmConfig.retry ?? 5;
     // CLI provider 强制串行：共享同一账户额度，并发会触发限速反而更慢
     const effectiveConcurrency = isCLI ? 1 : concurrency;

package/dist/core/parser.js

@@ -3,37 +3,38 @@
  */
 import { readFileSync } from 'node:fs';
 import yaml from 'js-yaml';
+import { t } from '../i18n.js';
 export function parseWorkflow(filePath) {
     const raw = readFileSync(filePath, 'utf-8');
     const doc = yaml.load(raw);
     // 基本校验
     if (!doc || typeof doc !== 'object') {
-        throw new Error(`工作流文件格式错误: ${filePath}`);
+        throw new Error(t('parse.bad_yaml', { path: filePath }));
     }
     if (!doc.name || typeof doc.name !== 'string') {
-        throw new Error('工作流缺少 name 字段');
+        throw new Error(t('parse.missing_name'));
     }
     if (!doc.steps || !Array.isArray(doc.steps) || doc.steps.length === 0) {
-        throw new Error('工作流缺少 steps 或 steps 为空');
+        throw new Error(t('parse.missing_steps'));
     }
     if (!doc.llm || typeof doc.llm !== 'object') {
-        throw new Error('工作流缺少 llm 配置');
+        throw new Error(t('parse.missing_llm'));
     }
     const llm = doc.llm;
     if (!llm.provider) {
-        throw new Error('llm 配置缺少 provider');
+        throw new Error(t('parse.missing_provider'));
     }
     // CLI providers (claude-code, gemini-cli, copilot-cli, codex-cli, openclaw-cli, hermes-cli) 和 ollama 不需要 model
     const cliProviders = ['claude-code', 'gemini-cli', 'copilot-cli', 'codex-cli', 'openclaw-cli', 'hermes-cli', 'ollama'];
     if (!llm.model && !cliProviders.includes(llm.provider)) {
-        throw new Error('llm 配置缺少 model（CLI provider 可省略）');
+        throw new Error(t('parse.missing_model'));
     }
     // 校验每个 step
     const stepIds = new Set();
     const steps = doc.steps;
     for (const step of steps) {
         if (!step.id)
-            throw new Error('step 缺少 id');
+            throw new Error(t('parse.missing_step_id'));
         if (stepIds.has(step.id))
             throw new Error(`step id 重复: ${step.id}`);
         stepIds.add(step.id);
@@ -101,10 +102,7 @@ export function validateWorkflow(workflow) {
             if (!inputDef && !isOutput && varName !== '_loop_iteration') {
                 errors.push(`step "${step.id}" 引用了未定义的变量: {{${varName}}}`);
             }
-            // 可选输入无默认值用在模板中 → 警告
-            if (inputDef && !inputDef.required && inputDef.default === undefined) {
-                errors.push(`step "${step.id}" 使用了可选输入 {{${varName}}}，但未设置默认值（未提供时为空字符串）`);
-            }
+            // 可选输入无默认值时，运行时自动填空字符串 — 非错误，不再警告
         }
     }
     // 检查循环依赖

package/dist/i18n.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Minimal i18n for CLI user-facing strings.
+ *
+ * Language detection priority:
+ *   1. --lang=en CLI flag
+ *   2. AO_LANG env var
+ *   3. LANG env var (en_US.UTF-8 → en)
+ *   4. Default: zh
+ */
+type Lang = 'zh' | 'en';
+export declare function detectLang(argv?: string[]): Lang;
+export declare function setLang(lang: Lang): void;
+type Dict = Record<string, {
+    zh: string;
+    en: string;
+}>;
+declare const dict: Dict;
+export declare function t(key: keyof typeof dict, params?: Record<string, string | number>): string;
+export {};