agency-orchestrator 0.1.0

package/dist/core/executor.js

@@ -0,0 +1,174 @@
+import { renderTemplate } from './template.js';
+import { loadAgent } from '../agents/loader.js';
+import { createInterface } from 'node:readline';
+export async function executeDAG(dag, options) {
+    const { connector, agentsDir, llmConfig, concurrency, inputs, onStepComplete, onStepStart, } = options;
+    // 变量上下文：inputs + 每步的 output
+    const context = new Map(inputs);
+    const startTime = Date.now();
+    const stepResults = [];
+    const timeout = llmConfig.timeout || 120_000;
+    const maxRetry = llmConfig.retry ?? 3;
+    for (const level of dag.levels) {
+        // 同层节点可并行，但受 concurrency 限制
+        const { onBatchStart, onBatchComplete } = options;
+        const allTasks = level.map(id => dag.nodes.get(id));
+        // 过滤掉已被标记为 skipped 的节点
+        const tasks = allTasks.filter(node => {
+            if (node.status === 'skipped') {
+                node.endTime = Date.now();
+                node.startTime = node.endTime;
+                stepResults.push({
+                    id: node.step.id,
+                    role: node.step.role,
+                    status: 'skipped',
+                    duration: 0,
+                    tokens: { input: 0, output: 0 },
+                });
+                onStepComplete?.(node);
+                return false;
+            }
+            return true;
+        });
+        // 按 concurrency 分批执行
+        for (let i = 0; i < tasks.length; i += concurrency) {
+            const batch = tasks.slice(i, i + concurrency);
+            onBatchStart?.(batch);
+            const results = await Promise.allSettled(batch.map(node => executeStep(node, {
+                connector,
+                agentsDir,
+                llmConfig,
+                context,
+                timeout,
+                maxRetry,
+                onStepStart,
+            })));
+            // 处理结果
+            for (let j = 0; j < batch.length; j++) {
+                const node = batch[j];
+                const result = results[j];
+                if (result.status === 'fulfilled') {
+                    node.status = 'completed';
+                    node.result = result.value;
+                    if (node.step.output) {
+                        context.set(node.step.output, result.value);
+                    }
+                }
+                else {
+                    node.status = 'failed';
+                    node.error = result.reason instanceof Error
+                        ? result.reason.message
+                        : String(result.reason);
+                    // 标记所有下游为 skipped
+                    markDownstreamSkipped(dag, node.step.id);
+                }
+                node.endTime = Date.now();
+                stepResults.push({
+                    id: node.step.id,
+                    role: node.step.role,
+                    status: node.status,
+                    output: node.result,
+                    error: node.error,
+                    duration: (node.endTime || 0) - (node.startTime || 0),
+                    tokens: node.tokenUsage || { input: 0, output: 0 },
+                });
+                onStepComplete?.(node);
+            }
+            onBatchComplete?.(batch);
+        }
+    }
+    const totalDuration = Date.now() - startTime;
+    const totalTokens = stepResults.reduce((acc, s) => ({
+        input: acc.input + s.tokens.input,
+        output: acc.output + s.tokens.output,
+    }), { input: 0, output: 0 });
+    return {
+        name: '', // 由调用方填充
+        success: stepResults.every(s => s.status !== 'failed'),
+        steps: stepResults,
+        totalDuration,
+        totalTokens,
+    };
+}
+async function executeStep(node, opts) {
+    node.status = 'running';
+    node.startTime = Date.now();
+    opts.onStepStart?.(node);
+    // 人工审批节点
+    if (node.step.type === 'approval') {
+        return await handleApproval(node, opts.context);
+    }
+    // 加载角色定义
+    const agent = loadAgent(opts.agentsDir, node.step.role);
+    const systemPrompt = agent.systemPrompt;
+    // 渲染任务模板
+    const userMessage = renderTemplate(node.step.task, opts.context);
+    // 带重试的 LLM 调用
+    let lastError = null;
+    for (let attempt = 0; attempt <= opts.maxRetry; attempt++) {
+        try {
+            const result = await withTimeout(opts.connector.chat(systemPrompt, userMessage, opts.llmConfig), opts.timeout);
+            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)) {
+                // 指数退避: 1s, 2s, 4s
+                await sleep(1000 * Math.pow(2, attempt));
+                continue;
+            }
+        }
+    }
+    throw lastError || new Error(`step "${node.step.id}" 执行失败`);
+}
+async function handleApproval(node, context) {
+    const prompt = node.step.prompt
+        ? renderTemplate(node.step.prompt, context)
+        : '请确认是否继续 (yes/no):';
+    // 如果有 input 引用，先显示内容
+    if (node.step.task) {
+        const content = renderTemplate(node.step.task, context);
+        console.log('\n' + content);
+    }
+    const rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(`\n⏸️  ${prompt} `, (answer) => {
+            rl.close();
+            resolve(answer.trim());
+        });
+    });
+}
+function markDownstreamSkipped(dag, failedId) {
+    const node = dag.nodes.get(failedId);
+    if (!node)
+        return;
+    for (const depId of node.dependents) {
+        const depNode = dag.nodes.get(depId);
+        if (depNode && depNode.status === 'pending') {
+            depNode.status = 'skipped';
+            markDownstreamSkipped(dag, depId);
+        }
+    }
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`超时 (${ms}ms)`)), ms);
+        promise
+            .then(val => { clearTimeout(timer); resolve(val); })
+            .catch(err => { clearTimeout(timer); reject(err); });
+    });
+}
+function isRetryable(error) {
+    const msg = error.message.toLowerCase();
+    return msg.includes('429') || msg.includes('rate') ||
+        msg.includes('500') || msg.includes('502') ||
+        msg.includes('503') || msg.includes('timeout') ||
+        msg.includes('econnreset');
+}
+function sleep(ms) {
+    return new Promise(r => setTimeout(r, ms));
+}

package/dist/core/parser.d.ts

@@ -0,0 +1,6 @@
+import type { WorkflowDefinition } from '../types.js';
+export declare function parseWorkflow(filePath: string): WorkflowDefinition;
+/**
+ * 验证工作流定义（不执行），返回错误列表
+ */
+export declare function validateWorkflow(workflow: WorkflowDefinition): string[];

package/dist/core/parser.js

@@ -0,0 +1,118 @@
+/**
+ * YAML → WorkflowDefinition 解析器
+ */
+import { readFileSync } from 'node:fs';
+import yaml from 'js-yaml';
+export function parseWorkflow(filePath) {
+    const raw = readFileSync(filePath, 'utf-8');
+    const doc = yaml.load(raw);
+    // 基本校验
+    if (!doc || typeof doc !== 'object') {
+        throw new Error(`工作流文件格式错误: ${filePath}`);
+    }
+    if (!doc.name || typeof doc.name !== 'string') {
+        throw new Error('工作流缺少 name 字段');
+    }
+    if (!doc.steps || !Array.isArray(doc.steps) || doc.steps.length === 0) {
+        throw new Error('工作流缺少 steps 或 steps 为空');
+    }
+    if (!doc.llm || typeof doc.llm !== 'object') {
+        throw new Error('工作流缺少 llm 配置');
+    }
+    const llm = doc.llm;
+    if (!llm.provider || !llm.model) {
+        throw new Error('llm 配置缺少 provider 或 model');
+    }
+    // 校验每个 step
+    const stepIds = new Set();
+    const steps = doc.steps;
+    for (const step of steps) {
+        if (!step.id)
+            throw new Error('step 缺少 id');
+        if (stepIds.has(step.id))
+            throw new Error(`step id 重复: ${step.id}`);
+        stepIds.add(step.id);
+        if (step.type !== 'approval' && !step.role) {
+            throw new Error(`step "${step.id}" 缺少 role`);
+        }
+        if (!step.task && step.type !== 'approval') {
+            throw new Error(`step "${step.id}" 缺少 task`);
+        }
+        // depends_on 的引用校验在 validateWorkflow() 中处理
+    }
+    return {
+        name: doc.name,
+        description: doc.description,
+        agents_dir: doc.agents_dir || './agents',
+        llm: doc.llm,
+        concurrency: doc.concurrency || 2,
+        inputs: doc.inputs,
+        steps,
+    };
+}
+/**
+ * 验证工作流定义（不执行），返回错误列表
+ */
+export function validateWorkflow(workflow) {
+    const errors = [];
+    const stepIds = new Set(workflow.steps.map(s => s.id));
+    for (const step of workflow.steps) {
+        // 检查 depends_on 引用
+        if (step.depends_on) {
+            for (const dep of step.depends_on) {
+                if (!stepIds.has(dep)) {
+                    errors.push(`step "${step.id}" 依赖不存在的 step: "${dep}"`);
+                }
+                if (dep === step.id) {
+                    errors.push(`step "${step.id}" 不能依赖自己`);
+                }
+            }
+        }
+        // 检查 {{变量}} 引用
+        const varRefs = step.task?.match(/\{\{(\w+)\}\}/g) || [];
+        for (const ref of varRefs) {
+            const varName = ref.slice(2, -2);
+            // 变量要么来自 inputs，要么来自某个 step 的 output
+            const inputDef = workflow.inputs?.find(i => i.name === varName);
+            const isOutput = workflow.steps.some(s => s.output === varName);
+            if (!inputDef && !isOutput) {
+                errors.push(`step "${step.id}" 引用了未定义的变量: {{${varName}}}`);
+            }
+            // 可选输入无默认值用在模板中 → 警告
+            if (inputDef && !inputDef.required && inputDef.default === undefined) {
+                errors.push(`step "${step.id}" 使用了可选输入 {{${varName}}}，但未设置默认值（未提供时为空字符串）`);
+            }
+        }
+    }
+    // 检查循环依赖
+    const cycleError = detectCycle(workflow.steps);
+    if (cycleError)
+        errors.push(cycleError);
+    return errors;
+}
+function detectCycle(steps) {
+    const visited = new Set();
+    const inStack = new Set();
+    const adj = new Map();
+    for (const step of steps) {
+        adj.set(step.id, step.depends_on || []);
+    }
+    function dfs(id) {
+        visited.add(id);
+        inStack.add(id);
+        for (const dep of adj.get(id) || []) {
+            if (inStack.has(dep))
+                return true;
+            if (!visited.has(dep) && dfs(dep))
+                return true;
+        }
+        inStack.delete(id);
+        return false;
+    }
+    for (const step of steps) {
+        if (!visited.has(step.id) && dfs(step.id)) {
+            return '工作流存在循环依赖';
+        }
+    }
+    return null;
+}

package/dist/core/template.d.ts

@@ -0,0 +1,12 @@
+/**
+ * {{变量}} 模板引擎
+ * 简单的字符串替换，不需要复杂的模板语法
+ */
+/**
+ * 替换字符串中的 {{变量名}} 为上下文中的值
+ */
+export declare function renderTemplate(template: string, context: Map<string, string>): string;
+/**
+ * 提取模板中引用的所有变量名
+ */
+export declare function extractVariables(template: string): string[];

package/dist/core/template.js

@@ -0,0 +1,30 @@
+/**
+ * {{变量}} 模板引擎
+ * 简单的字符串替换，不需要复杂的模板语法
+ */
+/**
+ * 替换字符串中的 {{变量名}} 为上下文中的值
+ */
+export function renderTemplate(template, context) {
+    return template.replace(/\{\{(\w+)\}\}/g, (_match, varName) => {
+        const value = context.get(varName);
+        if (value === undefined) {
+            throw new Error(`模板变量未定义: {{${varName}}}`);
+        }
+        return value;
+    });
+}
+/**
+ * 提取模板中引用的所有变量名
+ */
+export function extractVariables(template) {
+    const vars = [];
+    const regex = /\{\{(\w+)\}\}/g;
+    let match;
+    while ((match = regex.exec(template)) !== null) {
+        if (!vars.includes(match[1])) {
+            vars.push(match[1]);
+        }
+    }
+    return vars;
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * agency-orchestrator — 公开 API
+ *
+ * 使用方式:
+ *   import { run, validate, plan } from 'agency-orchestrator';
+ */
+export { parseWorkflow, validateWorkflow } from './core/parser.js';
+export { buildDAG, formatDAG } from './core/dag.js';
+export { executeDAG } from './core/executor.js';
+export { renderTemplate, extractVariables } from './core/template.js';
+export { loadAgent, listAgents } from './agents/loader.js';
+export { ClaudeConnector } from './connectors/claude.js';
+export { OllamaConnector } from './connectors/ollama.js';
+export { OpenAICompatibleConnector } from './connectors/openai-compatible.js';
+export { saveResults } from './output/reporter.js';
+export type { WorkflowDefinition, StepDefinition, LLMConfig, LLMConnector, LLMResult, AgentDefinition, WorkflowResult, StepResult, DAGNode, } from './types.js';
+/**
+ * 一行运行工作流（高级 API）
+ */
+export declare function run(workflowPath: string, inputs: Record<string, string>, options?: {
+    outputDir?: string;
+    quiet?: boolean;
+}): Promise<import('./types.js').WorkflowResult>;

package/dist/index.js

@@ -0,0 +1,139 @@
+/**
+ * agency-orchestrator — 公开 API
+ *
+ * 使用方式:
+ *   import { run, validate, plan } from 'agency-orchestrator';
+ */
+export { parseWorkflow, validateWorkflow } from './core/parser.js';
+export { buildDAG, formatDAG } from './core/dag.js';
+export { executeDAG } from './core/executor.js';
+export { renderTemplate, extractVariables } from './core/template.js';
+export { loadAgent, listAgents } from './agents/loader.js';
+export { ClaudeConnector } from './connectors/claude.js';
+export { OllamaConnector } from './connectors/ollama.js';
+export { OpenAICompatibleConnector } from './connectors/openai-compatible.js';
+export { saveResults } from './output/reporter.js';
+import { parseWorkflow, validateWorkflow } from './core/parser.js';
+import { buildDAG } from './core/dag.js';
+import { executeDAG } from './core/executor.js';
+import { ClaudeConnector } from './connectors/claude.js';
+import { OllamaConnector } from './connectors/ollama.js';
+import { OpenAICompatibleConnector } from './connectors/openai-compatible.js';
+import { saveResults, printStepResult, printStepRunning, clearRunningLine, printSummary } from './output/reporter.js';
+import { existsSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+/**
+ * 一行运行工作流（高级 API）
+ */
+export async function run(workflowPath, inputs, options) {
+    const workflow = parseWorkflow(workflowPath);
+    // 自动解析 agents_dir
+    workflow.agents_dir = resolveAgentsDir(workflow.agents_dir, workflowPath);
+    // 校验
+    const errors = validateWorkflow(workflow);
+    if (errors.length > 0) {
+        throw new Error(`工作流校验失败:\n${errors.map(e => `  - ${e}`).join('\n')}`);
+    }
+    // 构建 DAG
+    const dag = buildDAG(workflow);
+    // 创建 connector
+    let connector;
+    switch (workflow.llm.provider) {
+        case 'claude':
+            connector = new ClaudeConnector(workflow.llm.api_key);
+            break;
+        case 'ollama':
+            connector = new OllamaConnector(workflow.llm.base_url);
+            break;
+        case 'deepseek':
+            connector = new OpenAICompatibleConnector({
+                apiKey: workflow.llm.api_key || process.env.DEEPSEEK_API_KEY,
+                baseUrl: workflow.llm.base_url || 'https://api.deepseek.com/v1',
+            });
+            break;
+        case 'openai':
+            connector = new OpenAICompatibleConnector({
+                apiKey: workflow.llm.api_key || process.env.OPENAI_API_KEY,
+                baseUrl: workflow.llm.base_url || 'https://api.openai.com/v1',
+            });
+            break;
+        default:
+            throw new Error(`暂不支持 provider: ${workflow.llm.provider}（支持 claude / deepseek / openai / ollama）`);
+    }
+    // 构建输入
+    const inputMap = new Map(Object.entries(inputs));
+    // 检查必填输入 + 注入默认值
+    for (const def of workflow.inputs || []) {
+        if (def.required && !inputMap.has(def.name)) {
+            throw new Error(`缺少必填输入: ${def.name}`);
+        }
+        // 可选输入未提供时使用默认值
+        if (!inputMap.has(def.name) && def.default !== undefined) {
+            inputMap.set(def.name, def.default);
+        }
+        // 可选输入无默认值且未提供 → 设为空字符串（避免模板引擎崩溃）
+        if (!inputMap.has(def.name)) {
+            inputMap.set(def.name, '');
+        }
+    }
+    // 执行
+    let stepCounter = 0;
+    const totalSteps = workflow.steps.length;
+    const quiet = options?.quiet ?? false;
+    if (!quiet) {
+        console.log(`\n  工作流: ${workflow.name}`);
+        console.log(`  步骤数: ${totalSteps} | 并发: ${workflow.concurrency} | 模型: ${workflow.llm.model}`);
+        console.log('─'.repeat(50));
+    }
+    const result = await executeDAG(dag, {
+        connector,
+        agentsDir: workflow.agents_dir,
+        llmConfig: workflow.llm,
+        concurrency: workflow.concurrency || 2,
+        inputs: inputMap,
+        onBatchStart: quiet ? undefined : (nodes) => {
+            printStepRunning(nodes);
+        },
+        onBatchComplete: quiet ? undefined : (nodes) => {
+            clearRunningLine();
+            for (const node of nodes) {
+                stepCounter++;
+                printStepResult(node, stepCounter, totalSteps);
+            }
+        },
+    });
+    result.name = workflow.name;
+    // 保存结果
+    const outputDir = options?.outputDir || '.ao-output';
+    const outputPath = saveResults(result, outputDir);
+    if (!quiet) {
+        printSummary(result, outputPath);
+    }
+    return result;
+}
+/**
+ * 自动查找 agents 目录
+ * 优先级：YAML 中指定的路径 → 相对于 workflow 文件 → 常见位置
+ */
+function resolveAgentsDir(agentsDir, workflowPath) {
+    // 1. 如果 YAML 中指定的路径存在，直接用
+    const absolute = resolve(agentsDir);
+    if (existsSync(absolute))
+        return absolute;
+    // 2. 相对于 workflow 文件所在目录
+    const relToWorkflow = resolve(dirname(workflowPath), agentsDir);
+    if (existsSync(relToWorkflow))
+        return relToWorkflow;
+    // 3. 常见位置
+    const candidates = [
+        resolve('agency-agents-zh'),
+        resolve('../agency-agents-zh'),
+        resolve('node_modules/agency-agents-zh'),
+    ];
+    for (const dir of candidates) {
+        if (existsSync(dir))
+            return dir;
+    }
+    // 找不到就返回原值，让后续报错
+    return agentsDir;
+}

package/dist/output/reporter.d.ts

@@ -0,0 +1,19 @@
+import type { WorkflowResult } from '../types.js';
+import type { DAGNode } from '../types.js';
+/**
+ * 保存工作流执行结果到文件
+ */
+export declare function saveResults(result: WorkflowResult, outputDir: string): string;
+/**
+ * 打印一个步骤的完整结果（标题 + 内容），不拆成 start/complete
+ */
+export declare function printStepResult(node: DAGNode, stepIndex: number, totalSteps: number): void;
+/**
+ * 打印正在运行的步骤提示（简短一行）
+ */
+export declare function printStepRunning(nodes: DAGNode[]): void;
+/**
+ * 清除"执行中"提示行
+ */
+export declare function clearRunningLine(): void;
+export declare function printSummary(result: WorkflowResult, outputPath: string): void;

package/dist/output/reporter.js

@@ -0,0 +1,96 @@
+/**
+ * 执行结果输出和保存
+ */
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * 保存工作流执行结果到文件
+ */
+export function saveResults(result, outputDir) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+    const dirName = `${result.name}-${timestamp}`;
+    const dir = join(outputDir, dirName);
+    const stepsDir = join(dir, 'steps');
+    mkdirSync(stepsDir, { recursive: true });
+    // 保存每步的输出
+    for (let i = 0; i < result.steps.length; i++) {
+        const step = result.steps[i];
+        const filename = `${i + 1}-${step.id}.md`;
+        const content = step.output || step.error || '(无输出)';
+        writeFileSync(join(stepsDir, filename), content, 'utf-8');
+    }
+    // 保存最终输出（最后一个成功步骤的结果）
+    const lastCompleted = [...result.steps].reverse().find(s => s.status === 'completed');
+    if (lastCompleted?.output) {
+        writeFileSync(join(dir, 'summary.md'), lastCompleted.output, 'utf-8');
+    }
+    // 保存元数据
+    const metadata = {
+        name: result.name,
+        success: result.success,
+        totalDuration: `${(result.totalDuration / 1000).toFixed(1)}s`,
+        totalTokens: result.totalTokens,
+        steps: result.steps.map(s => ({
+            id: s.id,
+            role: s.role,
+            status: s.status,
+            duration: `${(s.duration / 1000).toFixed(1)}s`,
+            tokens: s.tokens,
+        })),
+    };
+    writeFileSync(join(dir, 'metadata.json'), JSON.stringify(metadata, null, 2), 'utf-8');
+    return dir;
+}
+/**
+ * 打印一个步骤的完整结果（标题 + 内容），不拆成 start/complete
+ */
+export function printStepResult(node, stepIndex, totalSteps) {
+    const role = node.step.role || node.step.type || '?';
+    const duration = ((node.endTime || 0) - (node.startTime || 0)) / 1000;
+    const tokens = node.tokenUsage
+        ? `${node.tokenUsage.input + node.tokenUsage.output} tokens`
+        : '';
+    console.log(`\n  ── [${stepIndex}/${totalSteps}] ${node.step.id} (${role}) ──`);
+    if (node.status === 'completed') {
+        console.log(`  完成 | ${duration.toFixed(1)}s | ${tokens}`);
+        if (node.result) {
+            console.log('');
+            for (const line of node.result.split('\n')) {
+                console.log(`    ${line}`);
+            }
+        }
+    }
+    else if (node.status === 'failed') {
+        console.log(`  失败: ${node.error}`);
+    }
+    else if (node.status === 'skipped') {
+        console.log(`  跳过 (上游失败)`);
+    }
+}
+/**
+ * 打印正在运行的步骤提示（简短一行）
+ */
+export function printStepRunning(nodes) {
+    if (nodes.length === 1) {
+        process.stdout.write(`\n  ... ${nodes[0].step.id} 执行中`);
+    }
+    else {
+        const ids = nodes.map(n => n.step.id).join(' + ');
+        process.stdout.write(`\n  ... ${ids} 并行执行中`);
+    }
+}
+/**
+ * 清除"执行中"提示行
+ */
+export function clearRunningLine() {
+    process.stdout.write('\r\x1b[K');
+}
+export function printSummary(result, outputPath) {
+    const totalTokens = result.totalTokens.input + result.totalTokens.output;
+    const duration = (result.totalDuration / 1000).toFixed(1);
+    const completedSteps = result.steps.filter(s => s.status === 'completed').length;
+    console.log('\n\n' + '='.repeat(50));
+    console.log(`  ${result.success ? '完成' : '部分失败'}: ${completedSteps}/${result.steps.length} 步 | ${duration}s | ${totalTokens} tokens`);
+    console.log(`  详细输出: ${outputPath}`);
+    console.log('='.repeat(50));
+}