agency-orchestrator 0.6.6 → 0.6.7

package/README.md

@@ -476,13 +476,14 @@ ao-output/产品需求评审-2026-03-22/
    Code/Copilot...)                   Cursor 直接调用)
 ```
 
-| 项目 | 说明 |
-|------|------|
-| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) | 211 个中文 AI 角色定义 — 本引擎的中文角色库 |
-| [agency-agents](https://github.com/msitarzewski/agency-agents) | 170+ 个英文 AI 角色定义 by [@msitarzewski](https://github.com/msitarzewski) — 本引擎的英文角色库 |
-| [ai-coding-guide](https://github.com/jnMetaCode/ai-coding-guide) | AI 编程工具实战指南 — 66 个 Claude Code 技巧 + 9 款工具最佳实践 + 可复制配置模板 |
-| [superpowers-zh](https://github.com/jnMetaCode/superpowers-zh) | AI 编程超能力 · 中文版 — 20 个 skills，让你的 AI 编程助手真正会干活 |
-| [shellward](https://github.com/jnMetaCode/shellward) | AI 智能体安全中间件 — 注入检测、数据防泄露、命令安全、零依赖、MCP Server |
+| 项目 | 定位 | 一句话 |
+|------|------|-------|
+| **本项目**（agency-orchestrator） | 🚀 编排引擎 | 一句话 → 211 专家协作，**几分钟出方案**（9 家 LLM / 6 免费） |
+| [agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) ![](https://img.shields.io/github/stars/jnMetaCode/agency-agents-zh?style=flat&label=⭐) | 🎭 中文角色库 | 211 个**即插即用** AI 专家，含 46 中国原创（小红书 / 抖音 / 飞书 / 钉钉） |
+| [agency-agents](https://github.com/msitarzewski/agency-agents) | 🎭 英文角色库 | 170+ 个英文 AI 角色 by [@msitarzewski](https://github.com/msitarzewski) |
+| [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） |
 
 ### 交流
 
@@ -490,7 +491,7 @@ ao-output/产品需求评审-2026-03-22/
 
 | 渠道 | 加入方式 |
 |------|---------|
-| QQ 群 | [点击加入](https://qm.qq.com/q/EeNQA9xCxy)（群号 1071280067） |
+| QQ 2群 | [点击加入](https://qm.qq.com/q/EeNQA9xCxy)（群号 1071280067） |
 | 微信群 | 关注公众号后回复「群」获取入群方式 |
 
 ## 路线图

package/dist/cli/compose.d.ts

@@ -30,6 +30,7 @@ export declare function buildComposeSystemPrompt(catalog: string, options?: {
     provider?: string;
     model?: string;
     lang?: 'zh' | 'en';
+    timeoutMs?: number;
 }): string;
 /**
  * 构建 user prompt
@@ -55,6 +56,8 @@ export declare function composeWorkflow(options: {
     autoRun?: boolean;
     /** 语言：自动检测或指定 */
     lang?: 'zh' | 'en';
+    /** 生成的 YAML 中写入的单步超时（ms）；未指定时 API=300s / ollama=600s */
+    timeoutMs?: number;
 }): Promise<{
     yaml: string;
     savedPath: string;

package/dist/cli/compose.js

@@ -5,7 +5,7 @@
  * 支持中文（agency-agents-zh）和英文（agency-agents）角色库。
  */
 import { listAgents } from '../agents/loader.js';
-import { existsSync, writeFileSync, mkdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { resolve, relative } from 'node:path';
 import { createConnector } from '../connectors/factory.js';
 import { t } from '../i18n.js';
@@ -68,7 +68,7 @@ function buildComposeSystemPromptEn(catalog, options) {
     const model = options?.model;
     const isLocal = provider === 'ollama';
     const maxTokens = isLocal ? 8192 : 4096;
-    const timeoutMs = isLocal ? 600000 : 120000;
+    const timeoutMs = options?.timeoutMs ?? (isLocal ? 600000 : 300000);
     const inputsSection = autoRun
         ? `
 ## Important: Direct Run Mode
@@ -160,7 +160,7 @@ function buildComposeSystemPromptZh(catalog, options) {
     const model = options?.model;
     const isLocal = provider === 'ollama';
     const maxTokens = isLocal ? 8192 : 4096;
-    const timeoutMs = isLocal ? 600000 : 120000;
+    const timeoutMs = options?.timeoutMs ?? (isLocal ? 600000 : 300000);
     const inputsSection = autoRun
         ? `
 ## 重要：直接运行模式
@@ -319,6 +319,7 @@ export async function composeWorkflow(options) {
         provider: options.llmConfig.provider,
         model: options.llmConfig.model,
         lang,
+        timeoutMs: options.timeoutMs,
     });
     const userPrompt = buildComposeUserPrompt(description, lang);
     // 3. 调用 LLM
@@ -385,6 +386,20 @@ export async function composeWorkflow(options) {
             if (retryYaml && retryYaml.includes('steps:')) {
                 writeFileSync(savedPath, retryYaml + '\n', 'utf-8');
                 const second = await validateGenerated(savedPath);
+                // 重试后仍有变量引用错误 → 自动修复
+                const retryVarErrors = second.errors.filter(e => e.includes('未定义的变量'));
+                if (retryVarErrors.length > 0) {
+                    const fixResult = await autoFixVariableRefs(savedPath);
+                    if (fixResult.fixed > 0) {
+                        console.log(`  自动修复了 ${fixResult.fixed} 个变量引用：`);
+                        for (const f of fixResult.details)
+                            console.log(`    {{${f.from}}} → {{${f.to}}}`);
+                        const afterFix = await validateGenerated(savedPath);
+                        warnings.push(...afterFix.errors);
+                        const fixedYaml = readFileSync(savedPath, 'utf-8').trim();
+                        return { yaml: fixedYaml, savedPath, relativePath, warnings };
+                    }
+                }
                 warnings.push(...second.errors);
                 return { yaml: retryYaml, savedPath, relativePath, warnings };
             }
@@ -393,6 +408,137 @@ export async function composeWorkflow(options) {
             warnings.push(`自动修正失败（保留原始输出）: ${err instanceof Error ? err.message : err}`);
         }
     }
+    // 自动修复未定义的变量引用（LLM 常见错误：变量名与 output 名不一致）
+    const varErrors = first.errors.filter(e => e.includes('未定义的变量'));
+    if (varErrors.length > 0) {
+        const fixResult = await autoFixVariableRefs(savedPath);
+        if (fixResult.fixed > 0) {
+            console.log(`  自动修复了 ${fixResult.fixed} 个变量引用：`);
+            for (const f of fixResult.details) {
+                console.log(`    {{${f.from}}} → {{${f.to}}}`);
+            }
+            // 重新校验
+            const afterFix = await validateGenerated(savedPath);
+            warnings.push(...afterFix.errors);
+            const fixedYaml = readFileSync(savedPath, 'utf-8').trim();
+            return { yaml: fixedYaml, savedPath, relativePath, warnings };
+        }
+    }
     warnings.push(...first.errors);
     return { yaml, savedPath, relativePath, warnings };
 }
+/**
+ * 自动修复 compose 生成 YAML 中的变量引用错误。
+ * 常见情况：LLM 用 step id 或 role 名代替 output 变量名。
+ */
+async function autoFixVariableRefs(yamlPath) {
+    const { parseWorkflow } = await import('../core/parser.js');
+    const content = readFileSync(yamlPath, 'utf-8');
+    let workflow;
+    try {
+        workflow = parseWorkflow(yamlPath);
+    }
+    catch {
+        return { fixed: 0, details: [] };
+    }
+    const inputNames = new Set((workflow.inputs || []).map((i) => i.name));
+    const outputNames = new Set();
+    const stepIdToOutput = new Map();
+    for (const step of workflow.steps) {
+        if (step.output) {
+            outputNames.add(step.output);
+            stepIdToOutput.set(step.id, step.output);
+        }
+    }
+    const allDefined = new Set([...inputNames, ...outputNames, '_loop_iteration']);
+    const replacements = [];
+    let fixedContent = content;
+    // 找出所有未定义的变量引用
+    const undefinedVars = new Set();
+    for (const step of workflow.steps) {
+        const refs = step.task?.match(/\{\{(\w+)\}\}/g) || [];
+        for (const ref of refs) {
+            const varName = ref.slice(2, -2);
+            if (!allDefined.has(varName)) {
+                undefinedVars.add(varName);
+            }
+        }
+    }
+    for (const badVar of undefinedVars) {
+        // 策略1：badVar 是某个 step id，该 step 有 output → 替换为 output
+        if (stepIdToOutput.has(badVar)) {
+            const goodVar = stepIdToOutput.get(badVar);
+            fixedContent = fixedContent.replace(new RegExp(`\\{\\{${badVar}\\}\\}`, 'g'), `{{${goodVar}}}`);
+            replacements.push({ from: badVar, to: goodVar });
+            continue;
+        }
+        // 策略2：模糊匹配 — 找子串包含关系最强的 output 变量
+        const best = findBestMatch(badVar, [...outputNames]);
+        if (best) {
+            fixedContent = fixedContent.replace(new RegExp(`\\{\\{${badVar}\\}\\}`, 'g'), `{{${best}}}`);
+            replacements.push({ from: badVar, to: best });
+            continue;
+        }
+        // 策略3：按 depends_on 找上游有 output 且尚未被引用的步骤
+        const alreadyUsed = new Set(replacements.map(r => r.to));
+        for (const step of workflow.steps) {
+            const refs = step.task?.match(/\{\{(\w+)\}\}/g) || [];
+            const hasBadRef = refs.some((r) => r.slice(2, -2) === badVar);
+            if (hasBadRef && step.depends_on?.length) {
+                // 优先选还没被占用的上游 output
+                const deps = step.depends_on.filter(d => stepIdToOutput.has(d));
+                const unusedDep = deps.find(d => !alreadyUsed.has(stepIdToOutput.get(d)));
+                const depId = unusedDep || deps[0];
+                if (depId) {
+                    const goodVar = stepIdToOutput.get(depId);
+                    fixedContent = fixedContent.replace(new RegExp(`\\{\\{${badVar}\\}\\}`, 'g'), `{{${goodVar}}}`);
+                    replacements.push({ from: badVar, to: goodVar });
+                }
+                break;
+            }
+        }
+    }
+    if (replacements.length > 0) {
+        writeFileSync(yamlPath, fixedContent, 'utf-8');
+    }
+    return { fixed: replacements.length, details: replacements };
+}
+/**
+ * 模糊匹配：找子串包含、前缀/后缀重叠最多的候选
+ */
+function findBestMatch(target, candidates) {
+    if (candidates.length === 0)
+        return null;
+    const t = target.toLowerCase();
+    // 完全包含关系
+    for (const c of candidates) {
+        const cl = c.toLowerCase();
+        if (t.includes(cl) || cl.includes(t))
+            return c;
+    }
+    // 按公共子串长度打分
+    let best = '';
+    let bestScore = 0;
+    for (const c of candidates) {
+        const cl = c.toLowerCase();
+        const score = longestCommonSubstring(t, cl);
+        if (score > bestScore && score >= 3) {
+            bestScore = score;
+            best = c;
+        }
+    }
+    return best || null;
+}
+function longestCommonSubstring(a, b) {
+    let max = 0;
+    for (let i = 0; i < a.length; i++) {
+        for (let j = 0; j < b.length; j++) {
+            let k = 0;
+            while (i + k < a.length && j + k < b.length && a[i + k] === b[j + k])
+                k++;
+            if (k > max)
+                max = k;
+        }
+    }
+    return max;
+}

package/dist/cli/provider-guides.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 各 provider 首次使用指南 —— 在 `ao init --provider X` 完成 .env 写入后打印，
+ * 告诉用户 provider 自身还需要做什么（OAuth 登录 / 拿 API key / 启本地服务 等）。
+ */
+export interface GuideContext {
+    /** 本次 init 是否提供了 --api-key */
+    hasApiKey: boolean;
+    /** 本次 init 是否提供了 --base-url，或环境已存在 OPENAI_BASE_URL */
+    hasBaseUrl: boolean;
+    /** 本次 init 指定的 model（用于 ollama pull 提示） */
+    model?: string;
+}
+export declare function getProviderGuide(provider: string, ctx: GuideContext): string;

package/dist/cli/provider-guides.js

@@ -0,0 +1,97 @@
+/**
+ * 各 provider 首次使用指南 —— 在 `ao init --provider X` 完成 .env 写入后打印，
+ * 告诉用户 provider 自身还需要做什么（OAuth 登录 / 拿 API key / 启本地服务 等）。
+ */
+export function getProviderGuide(provider, ctx) {
+    const p = provider.toLowerCase();
+    switch (p) {
+        case 'gemini-cli':
+            return [
+                `📋 首次使用 gemini-cli，二选一:`,
+                `   A. Google 账号登录（免费 1000 次/天，推荐）`,
+                `      → 终端跑一次: gemini -p "hi"，首次会弹出浏览器登录`,
+                `   B. API Key`,
+                `      → 从 https://aistudio.google.com/app/apikey 申请（不是 Cloud Console）`,
+                `      → export GEMINI_API_KEY=xxx  或加到 .env`,
+            ].join('\n');
+        case 'claude-code':
+            return [
+                `📋 首次使用 Claude Code:`,
+                `   → 终端跑一次: claude，首次会弹出浏览器完成 Anthropic 账号登录`,
+                `   → 或设 API Key: export ANTHROPIC_API_KEY=sk-ant-xxx`,
+            ].join('\n');
+        case 'copilot-cli':
+            return [
+                `📋 首次使用 GitHub Copilot CLI:`,
+                `   → 需要 GitHub Copilot 付费订阅`,
+                `   → 终端跑 copilot 命令，按提示完成 GitHub 账号登录`,
+            ].join('\n');
+        case 'codex-cli':
+            return [
+                `📋 首次使用 OpenAI Codex CLI:`,
+                `   → 需要 ChatGPT Plus/Pro 订阅`,
+                `   → 终端跑 codex 命令，按提示完成 OpenAI 账号登录`,
+            ].join('\n');
+        case 'openclaw-cli':
+            return [
+                `📋 首次使用 OpenClaw CLI:`,
+                `   → 终端跑 openclaw 命令，按提示完成登录或配置 token`,
+                `   → 也可用 OPENCLAW_AGENT 环境变量指定 agent`,
+            ].join('\n');
+        case 'hermes-cli':
+            return [
+                `📋 首次使用 Hermes CLI:`,
+                `   → 参考 Hermes 官方文档完成 token 配置`,
+                `   → 支持多模型，在 YAML 里用 model 字段指定 (如 anthropic/claude-sonnet-4、openai/gpt-4o)`,
+            ].join('\n');
+        case 'ollama': {
+            const model = ctx.model || '<model>';
+            return [
+                `📋 Ollama 本地推理:`,
+                `   → 启动服务: ollama serve`,
+                `   → 拉取模型: ollama pull ${model}`,
+                `   → 默认地址 http://localhost:11434，可用 OLLAMA_BASE_URL 覆盖`,
+            ].join('\n');
+        }
+        case 'deepseek':
+            return ctx.hasApiKey
+                ? `✅ DeepSeek 已配置，可以跑: ao run workflows/story-creation.yaml -i premise="测试"`
+                : [
+                    `📋 DeepSeek 还缺 API key:`,
+                    `   → 从 https://platform.deepseek.com/ 申请`,
+                    `   → 再跑: ao init --provider deepseek --api-key sk-xxx`,
+                ].join('\n');
+        case 'openai':
+            return ctx.hasApiKey
+                ? `✅ OpenAI 已配置。`
+                : [
+                    `📋 OpenAI 还缺 API key:`,
+                    `   → 从 https://platform.openai.com/api-keys 申请`,
+                    `   → 再跑: ao init --provider openai --api-key sk-xxx`,
+                ].join('\n');
+        case 'anthropic':
+        case 'claude':
+            return ctx.hasApiKey
+                ? `✅ Anthropic Claude 已配置。`
+                : [
+                    `📋 Anthropic Claude 还缺 API key:`,
+                    `   → 从 https://console.anthropic.com/settings/keys 申请`,
+                    `   → 再跑: ao init --provider claude --api-key sk-ant-xxx`,
+                ].join('\n');
+        default: {
+            const lines = [];
+            lines.push(`📋 "${provider}" 按自定义 OpenAI 兼容端点处理:`);
+            if (!ctx.hasBaseUrl)
+                lines.push(`   ⚠️  还缺 --base-url（/v1 兼容接口地址）`);
+            if (!ctx.hasApiKey)
+                lines.push(`   ⚠️  还缺 --api-key`);
+            lines.push(``);
+            lines.push(`   常见国内端点可参考:`);
+            lines.push(`     智谱 GLM:   https://open.bigmodel.cn/api/paas/v4`);
+            lines.push(`     Moonshot:   https://api.moonshot.cn/v1`);
+            lines.push(`     通义:       https://dashscope.aliyuncs.com/compatible-mode/v1`);
+            lines.push(`     硅基流动:   https://api.siliconflow.cn/v1`);
+            return lines.join('\n');
+        }
+    }
+}

package/dist/cli.js

@@ -18,6 +18,7 @@ import { run } from './index.js';
 import { scheduleUpdateCheck } from './utils/version-check.js';
 import { t, detectLang } from './i18n.js';
 import { loadEnvFile, writeEnvFile, ensureEnvGitignored } from './utils/env-loader.js';
+import { parseDuration } from './utils/duration.js';
 // Auto-load ./.env (shell env wins; no overwrite)
 loadEnvFile();
 // Suppress Node's DEP0190 warning from legitimate shell:true on Windows (.cmd shims).
@@ -99,6 +100,18 @@ async function handleRun() {
     // Precedence: CLI flag > .env (AO_PROVIDER/AO_MODEL) > YAML
     const provider = (getArgValue('--provider') || process.env.AO_PROVIDER);
     const model = getArgValue('--model') || process.env.AO_MODEL;
+    const baseUrl = getArgValue('--base-url') || getArgValue('--baseurl');
+    const apiKey = getArgValue('--api-key') || getArgValue('--apikey');
+    const timeoutRaw = getArgValue('--timeout');
+    let timeoutMs;
+    if (timeoutRaw !== undefined) {
+        const parsed = parseDuration(timeoutRaw);
+        if (parsed === null) {
+            console.error(`--timeout 值无效: "${timeoutRaw}"（支持 300000 / 300s / 5m / 0）`);
+            process.exit(1);
+        }
+        timeoutMs = parsed;
+    }
     // --resume last: 自动找最近一次的输出目录
     if (resumeDir === 'last') {
         const { findLatestOutput } = await import('./output/reporter.js');
@@ -110,14 +123,29 @@ async function handleRun() {
         resumeDir = latest;
     }
     try {
-        // --provider / --model: 命令行覆盖 YAML 中的 LLM 配置
+        // --provider / --model / --base-url / --api-key / --timeout: 命令行覆盖 YAML 中的 LLM 配置
         const cliProviders = ['claude-code', 'gemini-cli', 'copilot-cli', 'codex-cli', 'openclaw-cli', 'hermes-cli'];
-        const llmOverride = provider ? {
-            provider,
-            // CLI provider 不指定 model 时清空（避免 YAML 里的 deepseek-chat 传给 claude CLI）
-            model: model || (cliProviders.includes(provider) ? '' : undefined),
-            ...(cliProviders.includes(provider) ? { timeout: 600_000 } : {}),
-        } : undefined;
+        let llmOverride;
+        if (provider || model || baseUrl || apiKey || timeoutMs !== undefined) {
+            llmOverride = {};
+            if (provider) {
+                llmOverride.provider = provider;
+                // CLI provider 不指定 model 时清空（避免 YAML 里的 deepseek-chat 传给 claude CLI）
+                llmOverride.model = model || (cliProviders.includes(provider) ? '' : undefined);
+                if (cliProviders.includes(provider))
+                    llmOverride.timeout = 600_000;
+            }
+            else if (model) {
+                llmOverride.model = model;
+            }
+            if (baseUrl)
+                llmOverride.base_url = baseUrl;
+            if (apiKey)
+                llmOverride.api_key = apiKey;
+            // --timeout 最后赋值，优先级高于 CLI provider 自动 600s
+            if (timeoutMs !== undefined)
+                llmOverride.timeout = timeoutMs;
+        }
         const result = await run(resolve(filePath), inputs, {
             outputDir,
             quiet,
@@ -205,7 +233,7 @@ async function handleExplain() {
 async function handleCompose() {
     const autoRun = args.includes('--run');
     // 描述是第一个非 flag 的参数（跳过 compose 本身和 --xxx 的值）
-    const flagsWithValue = new Set(['--name', '--provider', '--model', '--agents-dir', '--lang']);
+    const flagsWithValue = new Set(['--name', '--provider', '--model', '--agents-dir', '--lang', '--base-url', '--baseurl', '--api-key', '--apikey', '--timeout']);
     let description;
     for (let i = 1; i < args.length; i++) {
         if (args[i] === '--run')
@@ -232,14 +260,36 @@ async function handleCompose() {
         console.error('  --provider <name>   LLM 提供商 (默认 deepseek)');
         console.error('  --model <name>      模型名 (默认 deepseek-chat)');
         console.error('  --lang <zh|en>      语言 (默认自动检测 / auto-detect)');
+        console.error('  --timeout <值>       单步超时，支持 300000/300s/5m (默认 API 300s, 本地/CLI 600s)');
         process.exit(1);
     }
     const provider = (getArgValue('--provider') || process.env.AO_PROVIDER || 'deepseek');
     const cliProviders = ['claude-code', 'gemini-cli', 'copilot-cli', 'codex-cli', 'openclaw-cli', 'hermes-cli'];
-    const model = getArgValue('--model') || process.env.AO_MODEL || (cliProviders.includes(provider) ? '' :
+    const knownApiProviders = ['deepseek', 'claude', 'openai', 'ollama'];
+    const isUnknownProvider = !cliProviders.includes(provider) && !knownApiProviders.includes(provider);
+    const cliModel = getArgValue('--model') || process.env.AO_MODEL;
+    // 未知 provider（如 zhipu/qwen/moonshot 走 openai-compatible）必须显式指定 model，
+    // 否则会用下面的 'gpt-4o' 默认值去调自定义端点，必然 404。
+    if (isUnknownProvider && !cliModel) {
+        console.error(`\n错误: provider "${provider}" 是自定义 OpenAI 兼容端点，必须用 --model 显式指定模型名（例如 --model glm-4-plus）。`);
+        process.exit(1);
+    }
+    const model = cliModel || (cliProviders.includes(provider) ? '' :
         provider === 'deepseek' ? 'deepseek-chat' :
             provider === 'claude' ? 'claude-sonnet-4-20250514' :
                 'gpt-4o');
+    const baseUrl = getArgValue('--base-url') || getArgValue('--baseurl');
+    const apiKey = getArgValue('--api-key') || getArgValue('--apikey');
+    const composeTimeoutRaw = getArgValue('--timeout');
+    let composeTimeoutMs;
+    if (composeTimeoutRaw !== undefined) {
+        const parsed = parseDuration(composeTimeoutRaw);
+        if (parsed === null) {
+            console.error(`--timeout 值无效: "${composeTimeoutRaw}"（支持 300000 / 300s / 5m / 0）`);
+            process.exit(1);
+        }
+        composeTimeoutMs = parsed;
+    }
     // 自动检测语言：英文输入 → 优先英文角色库
     const { detectLang } = await import('./cli/compose.js');
     const composeLang = getArgValue('--lang') ?? detectLang(description);
@@ -250,10 +300,16 @@ async function handleCompose() {
         const { yaml, savedPath, relativePath, warnings } = await composeWorkflow({
             description,
             agentsDir: resolve(agentsDir),
-            llmConfig: { provider, model },
+            llmConfig: {
+                provider,
+                model,
+                ...(baseUrl ? { base_url: baseUrl } : {}),
+                ...(apiKey ? { api_key: apiKey } : {}),
+            },
             outputName,
             autoRun,
             lang: composeLang,
+            timeoutMs: composeTimeoutMs,
         });
         console.log(`\n  ${t('compose.generated', { path: relativePath })}\n`);
         // 校验警告
@@ -285,8 +341,16 @@ async function handleCompose() {
             const result = await run(resolve(savedPath), inputs, {
                 quiet: false,
                 // 用 compose 时同样的 provider 执行，避免 YAML 里写的 provider 和用户实际可用的不一致
-                // CLI provider 单步调用可能很慢（1-20 分钟），给足超时
-                llmOverride: { provider, model: model || undefined, timeout: cliProviders.includes(provider) ? 600_000 : 300_000 },
+                // CLI provider 单步调用可能很慢（1-20 分钟），给足超时；用户显式 --timeout 优先
+                llmOverride: {
+                    provider,
+                    model: model || undefined,
+                    timeout: composeTimeoutMs !== undefined
+                        ? composeTimeoutMs
+                        : (cliProviders.includes(provider) ? 600_000 : 300_000),
+                    ...(baseUrl ? { base_url: baseUrl } : {}),
+                    ...(apiKey ? { api_key: apiKey } : {}),
+                },
             });
             process.exit(result.success ? 0 : 1);
         }
@@ -358,17 +422,17 @@ async function handleInit() {
             updates[urlVar] = cfgBaseUrl;
         }
         if (cfgApiKey) {
-            // Route api key to the provider-specific var the connectors already read
+            // 路由到 factory 里 connector 实际会读的 env 变量。
+            // factory.ts 只对 deepseek / claude / openai 有专属分支；其他 provider
+            // （zhipu/glm/qwen/moonshot 等）都走 default → openai-compatible，读 OPENAI_API_KEY。
+            // 所以未知 provider 的 key 也写到 OPENAI_API_KEY，不再写死代码的 AO_API_KEY / ZHIPU_API_KEY。
             const p = (cfgProvider || process.env.AO_PROVIDER || '').toLowerCase();
             const keyVar = p === 'deepseek' ? 'DEEPSEEK_API_KEY' :
-                p === 'openai' ? 'OPENAI_API_KEY' :
-                    p === 'anthropic' || p === 'claude' ? 'ANTHROPIC_API_KEY' :
-                        p === 'zhipu' || p === 'glm' ? 'ZHIPU_API_KEY' :
-                            p === 'qwen' || p === 'dashscope' ? 'DASHSCOPE_API_KEY' :
-                                p === 'moonshot' || p === 'kimi' ? 'MOONSHOT_API_KEY' :
-                                    'AO_API_KEY';
+                p === 'anthropic' || p === 'claude' ? 'ANTHROPIC_API_KEY' :
+                    'OPENAI_API_KEY';
             updates[keyVar] = cfgApiKey;
         }
+        const hasBaseUrl = !!cfgBaseUrl || !!process.env.OPENAI_BASE_URL;
         const envPath = resolve(process.cwd(), '.env');
         writeEnvFile(updates);
         const gitignoreUpdated = ensureEnvGitignored();
@@ -379,6 +443,20 @@ async function handleInit() {
         }
         if (gitignoreUpdated)
             console.log(`  🔒 已将 .env 加入 .gitignore`);
+        // 打印 provider 专属的首次使用指南
+        if (cfgProvider) {
+            const { getProviderGuide } = await import('./cli/provider-guides.js');
+            const guide = getProviderGuide(cfgProvider, {
+                hasApiKey: !!cfgApiKey,
+                hasBaseUrl,
+                model: cfgModel,
+            });
+            if (guide) {
+                console.log('');
+                for (const line of guide.split('\n'))
+                    console.log(`  ${line}`);
+            }
+        }
         console.log(`\n  下次运行 ao 时会自动加载这些配置。`);
         console.log(`  也可手动编辑 .env 或复制到其他项目复用。`);
         return;

package/dist/connectors/cli-base.js

@@ -90,7 +90,13 @@ export class CLIBaseConnector {
                     return;
                 }
                 if (code !== 0 && !stdout.trim()) {
-                    reject(new Error(`${this.cfg.displayName} 调用失败 (exit ${code}): ${stderr.slice(0, 500)}`));
+                    // 启发式识别"首次未认证"类错误（各 CLI 工具首次运行时都要求登录），给中文引导
+                    const authPattern = /auth method|not authenticated|not logged in|please (login|sign[\s-]*in)|unauthorized|credentials|_API_KEY/i;
+                    const looksLikeAuth = authPattern.test(stderr);
+                    const hint = looksLikeAuth
+                        ? `\n  提示: 首次使用 ${this.cfg.displayName} 需要先在终端跑一次 \`${this.cfg.command}\` 完成账号登录，或设置对应的 API KEY 环境变量`
+                        : '';
+                    reject(new Error(`${this.cfg.displayName} 调用失败 (exit ${code}): ${stderr.slice(0, 500)}${hint}`));
                     return;
                 }
                 const content = this.cfg.parseOutput

package/dist/connectors/codex-cli.js

@@ -11,11 +11,19 @@ export class CodexCLIConnector extends CLIBaseConnector {
         super({
             command: 'codex',
             displayName: 'OpenAI Codex CLI',
-            buildArgs: (prompt, _config) => {
-                return ['exec', '--skip-git-repo-check', '--sandbox', 'read-only', prompt];
+            buildArgs: (prompt, config) => {
+                const args = ['exec', '--skip-git-repo-check', '--sandbox', 'read-only'];
+                if (config.model)
+                    args.push('--model', config.model);
+                args.push(prompt);
+                return args;
             },
-            buildStdinArgs: (_config) => {
-                return ['exec', '--skip-git-repo-check', '--sandbox', 'read-only', '-'];
+            buildStdinArgs: (config) => {
+                const args = ['exec', '--skip-git-repo-check', '--sandbox', 'read-only'];
+                if (config.model)
+                    args.push('--model', config.model);
+                args.push('-');
+                return args;
             },
         });
     }

package/dist/connectors/copilot-cli.js

@@ -11,8 +11,12 @@ export class CopilotCLIConnector extends CLIBaseConnector {
         super({
             command: 'copilot',
             displayName: 'GitHub Copilot CLI',
-            buildArgs: (prompt, _config) => {
-                return ['-p', prompt];
+            buildArgs: (prompt, config) => {
+                const args = [];
+                if (config.model)
+                    args.push('--model', config.model);
+                args.push('-p', prompt);
+                return args;
             },
         });
     }

package/dist/connectors/factory.js

@@ -30,12 +30,12 @@ export function createConnector(config) {
         case 'deepseek':
             return new OpenAICompatibleConnector({
                 apiKey: config.api_key || process.env.DEEPSEEK_API_KEY,
-                baseUrl: config.base_url || 'https://api.deepseek.com/v1',
+                baseUrl: config.base_url || process.env.OPENAI_BASE_URL || 'https://api.deepseek.com/v1',
             });
         case 'openai':
             return new OpenAICompatibleConnector({
                 apiKey: config.api_key || process.env.OPENAI_API_KEY,
-                baseUrl: config.base_url || 'https://api.openai.com/v1',
+                baseUrl: config.base_url || process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
             });
         default:
             // 未知 provider：如果提供了 base_url，当作 OpenAI 兼容 API 处理

package/dist/connectors/gemini-cli.js

@@ -11,8 +11,12 @@ export class GeminiCLIConnector extends CLIBaseConnector {
         super({
             command: 'gemini',
             displayName: 'Gemini CLI',
-            buildArgs: (prompt, _config) => {
-                return ['-p', prompt];
+            buildArgs: (prompt, config) => {
+                const args = [];
+                if (config.model)
+                    args.push('-m', config.model);
+                args.push('-p', prompt);
+                return args;
             },
         });
     }

package/dist/connectors/openai-compatible.js

@@ -55,7 +55,11 @@ export class OpenAICompatibleConnector {
             }
             catch (err) {
                 clearTimeout(timer);
-                throw err;
+                const url = `${this.baseUrl}/chat/completions`;
+                const hint = !this.apiKey
+                    ? '\n  可能原因: 未设置 API Key，请检查环境变量（DEEPSEEK_API_KEY 或 OPENAI_API_KEY）或 .env 配置'
+                    : `\n  可能原因: 无法连接 ${this.baseUrl}，请检查 base_url 是否正确、网络是否可达`;
+                throw new Error(`请求失败: ${url}\n  ${err instanceof Error ? err.message : err}${hint}`);
             }
             if (!response.ok) {
                 clearTimeout(timer);

package/dist/core/executor.js

@@ -221,30 +221,58 @@ async function executeStep(node, opts) {
     const effectiveConfig = stepLlm
         ? { ...opts.llmConfig, ...stepLlm }
         : opts.llmConfig;
-    const effectiveConnector = (stepLlm?.provider && stepLlm.provider !== opts.llmConfig.provider)
-        ? createConnector(effectiveConfig)
-        : opts.connector;
-    // 带重试的 LLM 调用
+    // connector 把 api_key / base_url 存在构造时的私有字段，chat(config) 不会再读
+    // 所以 step 级覆盖任一凭证字段时必须重建 connector
+    const needsNewConnector = !!(stepLlm && ((stepLlm.provider && stepLlm.provider !== opts.llmConfig.provider) ||
+        stepLlm.base_url !== undefined ||
+        stepLlm.api_key !== undefined));
+    const effectiveConnector = needsNewConnector ? createConnector(effectiveConfig) : opts.connector;
+    // timeout / retry / CLI 判定必须基于 effectiveConfig，否则 step 级覆盖这几个字段时会被全局值吃掉
+    const effectiveIsCLI = effectiveConfig.provider.endsWith('-cli') || effectiveConfig.provider === 'claude-code';
+    const effectiveIsLocal = effectiveConfig.provider === 'ollama';
+    // timeout 策略：
+    // - 用户显式设置（含 timeout: 0 表示不限时）→ 第一次按此值
+    // - 未设置 → provider 默认（API 120s / CLI/ollama 600s）
+    // - 因超时触发 retry 时，下一轮 timeout x1.5（上限 900s）
+    //   非超时类错误（429/500/ECONNRESET 等）保持原 timeout，避免无谓放大
+    const defaultTimeout = effectiveIsCLI ? 600_000 : effectiveIsLocal ? 600_000 : 120_000;
+    const baseTimeout = effectiveConfig.timeout !== undefined ? effectiveConfig.timeout : defaultTimeout;
+    const effectiveMaxRetry = effectiveConfig.retry ?? opts.maxRetry;
+    const TIMEOUT_CAP = 900_000;
+    // 带重试的 LLM 调用（timeout 在网络超时类错误重试时自动延长）
     let lastError = null;
-    for (let attempt = 0; attempt <= opts.maxRetry; attempt++) {
+    let attemptTimeout = baseTimeout;
+    for (let attempt = 0; attempt <= effectiveMaxRetry; attempt++) {
         try {
-            const result = await withTimeout(effectiveConnector.chat(systemPrompt, userMessage, effectiveConfig), opts.timeout);
+            // attemptTimeout 同时传给 connector（控制内层 fetch/CLI timeout）和 withTimeout（外层兜底），
+            // 否则 connector 内部还按旧 timeout 硬断，递增就白加了
+            const attemptConfig = { ...effectiveConfig, timeout: attemptTimeout };
+            const result = await withTimeout(effectiveConnector.chat(systemPrompt, userMessage, attemptConfig), attemptTimeout);
             node.tokenUsage = { input: result.usage.input_tokens, output: result.usage.output_tokens };
             return result.content;
         }
         catch (err) {
             lastError = err instanceof Error ? err : new Error(String(err));
-            if (attempt < opts.maxRetry && isRetryable(lastError)) {
-                const isCLI = opts.llmConfig.provider.endsWith('-cli') || opts.llmConfig.provider === 'claude-code';
+            if (attempt < effectiveMaxRetry && isRetryable(lastError)) {
                 const errorClass = classifyError(lastError);
+                // connection 类错误（超时/ECONNRESET/aborted/socket hang up 等）→ 下一次 timeout x1.5
+                // 上限 900s，0=不限时保持不变，rate_limit / server_error 保持原值避免无谓放大
+                let nextTimeout = attemptTimeout;
+                if (errorClass === 'connection' && attemptTimeout > 0 && attemptTimeout < TIMEOUT_CAP) {
+                    nextTimeout = Math.min(Math.round(attemptTimeout * 1.5), TIMEOUT_CAP);
+                }
                 // 分级退避：rate_limit 最长，connection 中等，server_error 最短
-                const baseByClass = isCLI
+                const baseByClass = effectiveIsCLI
                     ? { rate_limit: 15_000, connection: 10_000, server_error: 5_000 }
                     : { rate_limit: 5_000, connection: 2_000, server_error: 1_000 };
                 const base = baseByClass[errorClass] || 1_000;
                 const jitter = Math.random() * 0.3; // 0-30% 抖动，防止并发步骤同时重试
                 const delay = Math.round(base * Math.pow(2, attempt) * (1 + jitter));
-                process.stderr.write(`\n  ⚠️  ${node.step.id} 失败 (${lastError.message.slice(0, 80)})，${Math.round(delay / 1000)}s 后重试 (${attempt + 1}/${opts.maxRetry})...\n`);
+                const extendHint = nextTimeout !== attemptTimeout
+                    ? `（timeout 延长至 ${Math.round(nextTimeout / 1000)}s）`
+                    : '';
+                process.stderr.write(`\n  ⚠️  ${node.step.id} 失败 (${lastError.message.slice(0, 80)})，${Math.round(delay / 1000)}s 后重试${extendHint} (${attempt + 1}/${effectiveMaxRetry})...\n`);
+                attemptTimeout = nextTimeout;
                 await sleep(delay);
                 continue;
             }
@@ -304,7 +332,7 @@ function withTimeout(promise, ms) {
     if (!ms)
         return promise; // 0 = 不限时（CLI provider 写完自动停）
     return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error(`超时 (${ms}ms)`)), ms);
+        const timer = setTimeout(() => reject(new Error(`超时 (${ms}ms)，可用 --timeout 或 YAML llm.timeout 延长`)), ms);
         promise
             .then(val => { clearTimeout(timer); resolve(val); })
             .catch(err => { clearTimeout(timer); reject(err); });
@@ -313,16 +341,17 @@ function withTimeout(promise, ms) {
 /** 错误分级：不同错误类型使用不同退避策略（借鉴 Claude Code 架构） */
 function classifyError(error) {
     const msg = error.message.toLowerCase();
-    // 限速：需要更长退避
-    if (msg.includes('429') || msg.includes('rate'))
+    // 限速：需要更长退避。用 \b 边界匹配，避免 "1429ms" / "429 ids" 等子串误判
+    if (/\b429\b/.test(msg) || msg.includes('rate'))
         return 'rate_limit';
-    // 服务端错误：短退避即可
-    if (msg.includes('500') || msg.includes('502') || msg.includes('503') || msg.includes('api 错误'))
+    // 服务端错误：短退避即可。5xx 状态码用 \b 边界匹配，避免 "500ms" / "450000ms" 等误判
+    if (/\b5\d\d\b/.test(msg) || msg.includes('api 错误'))
         return 'server_error';
-    // 连接断开/超时：中等退避
+    // 连接断开/超时：中等退避（"超时"识别中文 withTimeout 抛出的消息）
     if (msg.includes('econnreset') || msg.includes('econnrefused') ||
         msg.includes('etimedout') || msg.includes('socket hang up') ||
-        msg.includes('terminated') || msg.includes('aborted') || msg.includes('timeout'))
+        msg.includes('terminated') || msg.includes('aborted') ||
+        msg.includes('timeout') || msg.includes('超时'))
         return 'connection';
     return 'non_retryable';
 }

package/dist/i18n.js

@@ -167,6 +167,7 @@ const dict = {
     --input, -i key=@file    从文件读取变量值
     --provider <name>        覆盖 YAML 中的 LLM provider (如 claude-code, deepseek)
     --model <name>           覆盖 YAML 中的模型名
+    --timeout <值>            单步超时，支持 300000/300s/5m/0 (0=不限时)
     --output dir             输出目录 (默认 ao-output/)
     --resume <dir|last>      从上次运行恢复（加载已完成步骤的输出）
     --from <step-id>         配合 --resume，从指定步骤重新执行
@@ -220,6 +221,7 @@ const dict = {
     --input, -i key=@file    Read variable value from a file
     --provider <name>        Override LLM provider (e.g. claude-code, deepseek)
     --model <name>           Override model name from YAML
+    --timeout <value>        Per-step timeout, accepts 300000/300s/5m/0 (0=no limit)
     --output dir             Output directory (default: ao-output/)
     --resume <dir|last>      Resume from previous run (reuse completed step outputs)
     --from <step-id>         With --resume, re-run starting from this step

package/dist/utils/duration.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 解析时长字符串 → 毫秒。
+ *   "300000" / "300000ms" → 300000
+ *   "300s" → 300000
+ *   "5m"   → 300000
+ *   "0"    → 0  （调用方可用来表示"不限时"）
+ * 非法输入返回 null，由调用方报错。
+ */
+export declare function parseDuration(input: string): number | null;

package/dist/utils/duration.js

@@ -0,0 +1,24 @@
+/**
+ * 解析时长字符串 → 毫秒。
+ *   "300000" / "300000ms" → 300000
+ *   "300s" → 300000
+ *   "5m"   → 300000
+ *   "0"    → 0  （调用方可用来表示"不限时"）
+ * 非法输入返回 null，由调用方报错。
+ */
+export function parseDuration(input) {
+    const m = /^(\d+)\s*(ms|s|m)?$/i.exec(input.trim());
+    if (!m)
+        return null;
+    const n = parseInt(m[1], 10);
+    if (!Number.isFinite(n) || n < 0)
+        return null;
+    const unit = (m[2] || 'ms').toLowerCase();
+    if (unit === 'ms')
+        return n;
+    if (unit === 's')
+        return n * 1000;
+    if (unit === 'm')
+        return n * 60_000;
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agency-orchestrator",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "Multi-agent YAML workflow engine — 211 AI roles, auto DAG parallelism, zero code. One sentence → multiple AI roles collaborate → complete plan in minutes. 10 LLM providers, 7 need no API key.",
   "keywords": [
     "multi-agent",