agency-orchestrator 0.4.2 → 0.5.0

package/README.md

@@ -515,11 +515,14 @@ ao-output/产品需求评审-2026-03-22/
    Code/Copilot...)                   Cursor 直接调用)
 ```
 
-## 社区交流
+## 交流 · Community
 
-| 群名 | 群号 | 加入方式 |
-|------|------|---------|
-| AI 编程 & Agent 中文实践群 | **1071280067** | [点击加入](https://qm.qq.com/q/EeNQA9xCxy) |
+微信公众号 **「AI不止语」**（微信搜索 `AI_BuZhiYu`）— 技术问答 · 项目更新 · 实战文章
+
+| 渠道 | 加入方式 |
+|------|---------|
+| QQ 群 | [点击加入](https://qm.qq.com/q/EeNQA9xCxy)（群号 1071280067） |
+| 微信群 | 关注公众号后回复「群」获取入群方式 |
 
 ## 姊妹项目
 

package/dist/agents/loader.js

@@ -18,7 +18,15 @@ import { join, resolve } from 'node:path';
  * @param rolePath 角色路径，如 "engineering/engineering-sre"
  */
 export function loadAgent(agentsDir, rolePath) {
+    // 防止路径穿越攻击（如 ../../etc/passwd）
+    if (/\.\.[/\\]/.test(rolePath) || /[^a-zA-Z0-9_\-/]/.test(rolePath)) {
+        throw new Error(`非法角色路径: ${rolePath}\n角色路径只能包含字母、数字、下划线、连字符和斜杠`);
+    }
     const fullPath = resolve(agentsDir, `${rolePath}.md`);
+    const resolvedDir = resolve(agentsDir);
+    if (!fullPath.startsWith(resolvedDir)) {
+        throw new Error(`角色路径越界: ${rolePath}`);
+    }
     if (!existsSync(fullPath)) {
         throw new Error(`角色文件不存在: ${fullPath}\n请确认 agents_dir 和 role 路径正确`);
     }

package/dist/cli/compose.d.ts

@@ -3,6 +3,7 @@ import type { LLMConfig } from '../types.js';
 export interface RoleSummary {
     path: string;
     name: string;
+    emoji?: string;
     description: string;
     category: string;
 }
@@ -16,8 +17,14 @@ export declare function buildRoleCatalog(agentsDir: string): RoleSummary[];
 export declare function formatCatalogForPrompt(roles: RoleSummary[]): string;
 /**
  * 构建发给 LLM 的 system prompt
+ * @param catalog 角色目录文本
+ * @param options.autoRun 如果 true，生成的 YAML 不需要 inputs，用户描述直接嵌入 task
  */
-export declare function buildComposeSystemPrompt(catalog: string): string;
+export declare function buildComposeSystemPrompt(catalog: string, options?: {
+    autoRun?: boolean;
+    provider?: string;
+    model?: string;
+}): string;
 /**
  * 构建 user prompt
  */
@@ -37,6 +44,9 @@ export declare function composeWorkflow(options: {
     description: string;
     agentsDir: string;
     llmConfig: LLMConfig;
+    outputName?: string;
+    /** 直接运行模式：生成的 YAML 不需要 inputs */
+    autoRun?: boolean;
 }): Promise<{
     yaml: string;
     savedPath: string;

package/dist/cli/compose.js

@@ -17,6 +17,7 @@ export function buildRoleCatalog(agentsDir) {
         .map(a => ({
         path: a.rolePath,
         name: a.name,
+        emoji: a.emoji,
         description: a.description || '',
         category: a.rolePath.split('/')[0],
     }));
@@ -35,7 +36,7 @@ export function formatCatalogForPrompt(roles) {
     for (const [cat, list] of byCategory) {
         lines.push(`## ${cat}`);
         for (const r of list) {
-            lines.push(`- ${r.path} | ${r.name} | ${r.description}`);
+            lines.push(`- ${r.path} | ${r.emoji || ''} ${r.name} | ${r.description}`);
         }
         lines.push('');
     }
@@ -43,16 +44,43 @@ export function formatCatalogForPrompt(roles) {
 }
 /**
  * 构建发给 LLM 的 system prompt
+ * @param catalog 角色目录文本
+ * @param options.autoRun 如果 true，生成的 YAML 不需要 inputs，用户描述直接嵌入 task
  */
-export function buildComposeSystemPrompt(catalog) {
+export function buildComposeSystemPrompt(catalog, options) {
+    const autoRun = options?.autoRun ?? false;
+    const provider = options?.provider || 'deepseek';
+    const model = options?.model;
+    const inputsSection = autoRun
+        ? `
+## 重要：直接运行模式
+
+这个工作流生成后会立即执行，所以：
+- **不要**生成 inputs 段
+- 把用户描述中的所有具体信息直接写进每个 step 的 task 里
+- 确保工作流无需任何外部输入就能直接运行`
+        : `
+inputs:
+  - name: variable_name
+    description: "变量描述"
+    required: true`;
+    const inputsYamlExample = autoRun ? '' : `
+inputs:
+  - name: variable_name
+    description: "变量描述"
+    required: true
+`;
+    const inputsDesignPrinciple = autoRun
+        ? '- **自包含**：所有信息直接写在 task 中，不要使用 inputs，工作流必须能直接运行'
+        : '- **合理输入**：提取用户需求中的关键变量作为 inputs';
     return `你是一个 AI 工作流编排专家。用户会用一句话描述他想要的工作流，你需要：
 
 1. 从下方角色目录中选择最合适的角色（通常 2-6 个）
 2. 设计合理的 DAG 依赖关系（哪些步骤可以并行，哪些必须串行）
 3. 为每个步骤编写详细的 task 描述
-4. 设计合理的输入变量
+${autoRun ? '4. 把用户描述中的具体信息直接写进 task，不要生成 inputs' : '4. 设计合理的输入变量'}
 5. 生成完整的 workflow YAML
-
+${autoRun ? inputsSection : ''}
 ## 输出格式
 
 直接输出一个完整的 YAML 代码块，格式如下：
@@ -64,23 +92,20 @@ description: "一句话描述"
 agents_dir: "agency-agents-zh"
 
 llm:
-  provider: deepseek
-  model: deepseek-chat
+  provider: ${provider}
+  ${model ? `model: ${model}` : ''}
   max_tokens: 4096
 
 concurrency: 2
-
-inputs:
-  - name: variable_name
-    description: "变量描述"
-    required: true
-
+${inputsYamlExample}
 steps:
   - id: step_id
     role: "category/role-name"
+    name: "通俗易懂的角色名（如：老板、产品经理、技术总监）"
+    emoji: "👔"
     task: |
       详细的任务描述...
-      使用 {{variable_name}} 引用输入变量
+${autoRun ? '      直接包含用户需求中的具体信息' : '      使用 {{variable_name}} 引用输入变量'}
       使用 {{previous_output}} 引用上游步骤的输出
     output: output_variable_name
     depends_on: [upstream_step_id]  # 仅在有依赖时添加
@@ -91,9 +116,10 @@ steps:
 - **并行优先**：没有数据依赖的步骤应该并行执行（不加 depends_on）
 - **变量串联**：上游步骤的 output 变量名要和下游步骤 task 中的 {{变量}} 对应
 - **角色匹配**：选择最专业的角色，不要用一个角色做所有事
+- **角色命名**：每个步骤必须设置 name（通俗的公司职位名如"老板""产品经理""技术总监"）和 emoji，让小白也能一眼看懂谁在说话
 - **任务详细**：task 描述要具体，告诉角色要做什么、输出什么格式
-- **合理输入**：提取用户需求中的关键变量作为 inputs
-- **最终汇总**：如果有多路并行，最后应该有一个汇总步骤
+${inputsDesignPrinciple}
+- **最终成品**：最后一个步骤必须输出用户想要的最终成品（如完整文章、完整报告），而不是审查意见或修改建议。如果有审校步骤，审校步骤应该直接输出修改后的定稿，而不是"修改建议列表"
 
 ## 可用角色目录
 
@@ -103,7 +129,9 @@ ${catalog}
 
 - role 的值必须严格使用角色目录中的 path（如 "engineering/engineering-code-reviewer"），不要自己编造
 - 只输出 YAML 代码块，不要输出其他内容
-- concurrency 设为并行步骤的最大数量`;
+- concurrency 设为并行步骤的最大数量
+- **重要：拆分大任务**。写长文章时，不要让一个步骤生成超过 800 字的内容。应该按章节拆分成多个并行步骤（如 write_ch1、write_ch2、write_ch3），最后用一个合并步骤重写为连贯的完整文章
+- 每个写作步骤的 task 中要限定输出字数（如"500字以内"），避免单步骤生成时间过长`;
 }
 /**
  * 构建 user prompt
@@ -163,7 +191,11 @@ export async function composeWorkflow(options) {
     }
     const catalog = formatCatalogForPrompt(roles);
     // 2. 构建 prompt
-    const systemPrompt = buildComposeSystemPrompt(catalog);
+    const systemPrompt = buildComposeSystemPrompt(catalog, {
+        autoRun: options.autoRun,
+        provider: options.llmConfig.provider,
+        model: options.llmConfig.model,
+    });
     const userPrompt = buildComposeUserPrompt(description);
     // 3. 调用 LLM
     console.log(`  正在用 AI 编排工作流...（${roles.length} 个角色可选）\n`);
@@ -182,7 +214,9 @@ export async function composeWorkflow(options) {
     if (!existsSync(workflowsDir)) {
         mkdirSync(workflowsDir, { recursive: true });
     }
-    const fileName = generateFileName(description, workflowsDir);
+    const fileName = options.outputName
+        ? (options.outputName.endsWith('.yaml') ? options.outputName : `${options.outputName}.yaml`)
+        : generateFileName(description, workflowsDir);
     const savedPath = resolve(workflowsDir, fileName);
     writeFileSync(savedPath, yaml + '\n', 'utf-8');
     const relativePath = relative(process.cwd(), savedPath);

package/dist/cli.js

@@ -81,6 +81,8 @@ async function handleRun() {
     const watch = args.includes('--watch');
     let resumeDir = getArgValue('--resume');
     const fromStep = getArgValue('--from');
+    const provider = getArgValue('--provider');
+    const model = getArgValue('--model');
     // --resume last: 自动找最近一次的输出目录
     if (resumeDir === 'last') {
         const { findLatestOutput } = await import('./output/reporter.js');
@@ -92,12 +94,21 @@ async function handleRun() {
         resumeDir = latest;
     }
     try {
+        // --provider / --model: 命令行覆盖 YAML 中的 LLM 配置
+        const cliProviders = ['claude-code', 'gemini-cli', 'copilot-cli', 'codex-cli', 'openclaw-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;
         const result = await run(resolve(filePath), inputs, {
             outputDir,
             quiet,
             watch,
             resumeDir: resumeDir ? resolve(resumeDir) : undefined,
             fromStep,
+            llmOverride,
         });
         process.exit(result.success ? 0 : 1);
     }
@@ -176,7 +187,21 @@ async function handleExplain() {
     }
 }
 async function handleCompose() {
-    const description = args[1];
+    const autoRun = args.includes('--run');
+    // 描述是第一个非 flag 的参数（跳过 compose 本身和 --xxx 的值）
+    const flagsWithValue = new Set(['--name', '--provider', '--model', '--agents-dir']);
+    let description;
+    for (let i = 1; i < args.length; i++) {
+        if (args[i] === '--run')
+            continue;
+        if (args[i].startsWith('--')) {
+            if (flagsWithValue.has(args[i]))
+                i++; // 跳过 flag 的值
+            continue;
+        }
+        description = args[i];
+        break;
+    }
     if (!description) {
         console.error('用法: ao compose "用一句话描述你想要的工作流"');
         console.error('');
@@ -186,19 +211,28 @@ async function handleCompose() {
         console.error('  ao compose "用户反馈分析，分类后分别给产品和技术团队"');
         console.error('');
         console.error('选项:');
+        console.error('  --run                生成后立即运行（一句话出结果）');
+        console.error('  --name <filename>   自定义输出文件名 (不含 .yaml 后缀)');
         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 cliProviders = ['claude-code', 'gemini-cli', 'copilot-cli', 'codex-cli', 'openclaw-cli'];
+    const model = getArgValue('--model') || (cliProviders.includes(provider) ? '' :
+        provider === 'deepseek' ? 'deepseek-chat' :
+            provider === 'claude' ? 'claude-sonnet-4-20250514' :
+                'gpt-4o');
     const agentsDir = getArgValue('--agents-dir') || resolveAgentsDir();
+    const outputName = getArgValue('--name');
     try {
         const { composeWorkflow } = await import('./cli/compose.js');
-        const { yaml, relativePath, warnings } = await composeWorkflow({
+        const { yaml, savedPath, relativePath, warnings } = await composeWorkflow({
             description,
             agentsDir: resolve(agentsDir),
             llmConfig: { provider, model },
+            outputName,
+            autoRun,
         });
         console.log(`\n  ✅ 工作流已生成: ${relativePath}\n`);
         // 校验警告
@@ -209,6 +243,33 @@ async function handleCompose() {
             }
             console.log('');
         }
+        if (autoRun) {
+            // --run 模式：校验有严重问题时不执行
+            if (warnings.some(w => w.includes('解析失败'))) {
+                console.error('  生成的 YAML 有解析错误，无法自动运行。请手动修复后执行:');
+                console.error(`    ao run ${relativePath}`);
+                process.exit(1);
+            }
+            console.log('─'.repeat(50));
+            console.log('  开始执行工作流...\n');
+            // 保底：如果 LLM 仍然生成了 required inputs，用用户描述填充
+            const { parseWorkflow } = await import('./core/parser.js');
+            const workflow = parseWorkflow(resolve(savedPath));
+            const inputs = {};
+            for (const def of workflow.inputs || []) {
+                if (def.required && def.default === undefined) {
+                    inputs[def.name] = description;
+                }
+            }
+            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 },
+            });
+            process.exit(result.success ? 0 : 1);
+        }
+        // 非 --run 模式：显示预览和下一步提示
         console.log('  预览:');
         const previewLines = yaml.split('\n').slice(0, 30);
         for (const line of previewLines) {
@@ -271,13 +332,41 @@ async function handleInit() {
     }
     else {
         console.log('  正在下载 agency-agents-zh (186 个 AI 角色定义)...\n');
+        let downloaded = false;
+        // 优先用 npm（国内镜像快）
         try {
-            execSync('git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git', { stdio: 'inherit' });
-            console.log('\n  下载完成!');
+            execSync('npm pack agency-agents-zh --pack-destination .', { stdio: 'pipe' });
+            const { readdirSync } = await import('node:fs');
+            const tgz = readdirSync('.').find(f => f.startsWith('agency-agents-zh-') && f.endsWith('.tgz'));
+            if (tgz) {
+                const { mkdirSync } = await import('node:fs');
+                mkdirSync('agency-agents-zh', { recursive: true });
+                execSync(`tar xzf ${tgz} --strip-components=1 -C agency-agents-zh`, { stdio: 'pipe' });
+                const { unlinkSync } = await import('node:fs');
+                unlinkSync(tgz);
+                downloaded = true;
+                console.log('  通过 npm 下载完成!');
+            }
         }
         catch {
-            console.error('\n  下载失败，请手动克隆:');
-            console.error('  git clone https://github.com/jnMetaCode/agency-agents-zh.git');
+            // npm 失败，回退 git clone
+        }
+        // 回退: git clone
+        if (!downloaded) {
+            try {
+                console.log('  npm 下载失败，尝试 git clone...\n');
+                execSync('git clone --depth 1 https://github.com/jnMetaCode/agency-agents-zh.git', { stdio: 'inherit' });
+                console.log('\n  下载完成!');
+                downloaded = true;
+            }
+            catch {
+                // ignore
+            }
+        }
+        if (!downloaded) {
+            console.error('\n  下载失败，请手动安装:');
+            console.error('  npm pack agency-agents-zh && tar xzf agency-agents-zh-*.tgz && mv package agency-agents-zh');
+            console.error('  或: git clone https://github.com/jnMetaCode/agency-agents-zh.git');
             process.exit(1);
         }
     }
@@ -294,9 +383,25 @@ function handleRoles() {
     try {
         const agents = listAgents(resolve(agentsDir));
         console.log(`\n  共 ${agents.length} 个角色 (${agentsDir}):\n`);
+        // 按分类分组
+        const byCategory = new Map();
         for (const agent of agents) {
-            const emoji = agent.emoji || ' ';
-            console.log(`  ${emoji} ${agent.name} — ${agent.description || '(无描述)'}`);
+            const cat = agent.rolePath?.split('/')[0] || 'other';
+            const list = byCategory.get(cat) || [];
+            list.push(agent);
+            byCategory.set(cat, list);
+        }
+        for (const [category, list] of byCategory) {
+            console.log(`  ── ${category} (${list.length}) ──`);
+            for (const agent of list) {
+                const emoji = agent.emoji || ' ';
+                const path = agent.rolePath || '';
+                console.log(`  ${emoji} ${agent.name}  ${path}`);
+                if (agent.description) {
+                    console.log(`     ${agent.description}`);
+                }
+            }
+            console.log('');
         }
     }
     catch (err) {
@@ -389,6 +494,7 @@ function printHelp() {
     init                              下载/更新 agency-agents-zh
     init --workflow                    交互式创建新工作流
     compose "描述"                     AI 智能编排工作流（一句话生成 YAML）
+    compose "描述" --run               生成并立即运行（一句话出结果）
     serve                             启动 MCP Server（供 Claude Code / Cursor 调用）
     run <workflow.yaml>               执行工作流
     validate <workflow.yaml>          校验工作流定义
@@ -399,6 +505,8 @@ function printHelp() {
   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，从指定步骤重新执行

package/dist/connectors/claude-code.d.ts

@@ -1,11 +1,5 @@
-/**
- * Claude Code CLI Connector
- * 通过本地 `claude` CLI 调用，直接��用 Claude Max/Pro 订阅额度，无需 API key
- *
- * 安装: npm install -g @anthropic-ai/claude-code
- * 认证: claude 登录后自动使用订阅额度
- */
-import { CLIBaseConnector } from './cli-base.js';
-export declare class ClaudeCodeConnector extends CLIBaseConnector {
-    constructor();
+import type { LLMConnector, LLMResult, LLMConfig } from '../types.js';
+export declare class ClaudeCodeConnector implements LLMConnector {
+    chat(systemPrompt: string, userMessage: string, config: LLMConfig): Promise<LLMResult>;
+    private _exec;
 }

package/dist/connectors/claude-code.js

@@ -1,23 +1,145 @@
 /**
  * Claude Code CLI Connector
- * 通过本地 `claude` CLI 调用，直接��用 Claude Max/Pro 订阅额度，无需 API key
+ * 通过本地 `claude` CLI 调用，直接使用 Claude Max/Pro 订阅额度，无需 API key
  *
  * 安装: npm install -g @anthropic-ai/claude-code
  * 认证: claude 登录后自动使用订阅额度
+ *
+ * 关键: 使用 --output-format json 而非 text
+ * text 格式在管道模式下有缓冲问题，长输出（>1000 字）会导致子进程挂起
+ * json 格式一次性输出完整结果，包含 usage 等元数据
  */
-import { CLIBaseConnector } from './cli-base.js';
-export class ClaudeCodeConnector extends CLIBaseConnector {
-    constructor() {
-        super({
-            command: 'claude',
-            displayName: 'Claude Code CLI',
-            buildArgs: (prompt, config) => {
-                const args = ['-p', prompt, '--output-format', 'text'];
-                if (config.model && config.model !== 'claude-code') {
-                    args.push('--model', config.model);
-                }
-                return args;
-            },
+import { spawn } from 'node:child_process';
+import { writeFileSync, unlinkSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export class ClaudeCodeConnector {
+    async chat(systemPrompt, userMessage, config) {
+        const timeout = config.timeout || 600_000; // 默认 10 分钟
+        // 用临时文件传系统 prompt（避免命令行过长）
+        let systemPromptFile;
+        if (systemPrompt) {
+            systemPromptFile = join(tmpdir(), `ao-sysprompt-${Date.now()}-${Math.random().toString(36).slice(2)}.txt`);
+            writeFileSync(systemPromptFile, systemPrompt, 'utf-8');
+        }
+        // 使用 json 格式：text 格式在管道中会缓冲挂起
+        const args = ['-p', '-', '--output-format', 'json', '--tools', '', '--effort', 'low', '--no-session-persistence'];
+        if (systemPromptFile) {
+            args.push('--system-prompt-file', systemPromptFile);
+        }
+        if (config.model && config.model !== 'claude-code') {
+            args.push('--model', config.model);
+        }
+        try {
+            return await this._exec(args, userMessage, timeout);
+        }
+        finally {
+            if (systemPromptFile) {
+                try {
+                    unlinkSync(systemPromptFile);
+                }
+                catch { }
+            }
+        }
+    }
+    _exec(args, stdinData, timeout) {
+        return new Promise((resolve, reject) => {
+            const child = spawn('claude', args, {
+                env: { ...process.env },
+                stdio: ['pipe', 'pipe', 'pipe'],
+                shell: process.platform === 'win32',
+            });
+            let stdout = '';
+            let stderr = '';
+            let killed = false;
+            let receivedBytes = 0;
+            let lastProgressTime = 0;
+            const timer = setTimeout(() => {
+                killed = true;
+                child.kill('SIGTERM');
+                setTimeout(() => { try {
+                    child.kill('SIGKILL');
+                }
+                catch { } }, 5000);
+            }, timeout);
+            child.stdout.on('data', (chunk) => {
+                stdout += chunk.toString();
+                receivedBytes += chunk.length;
+                const now = Date.now();
+                if (now - lastProgressTime > 10_000) {
+                    lastProgressTime = now;
+                    const kb = (receivedBytes / 1024).toFixed(1);
+                    process.stderr.write(`  📡 已接收 ${kb}KB...\n`);
+                }
+            });
+            child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+            child.stdin.on('error', () => { });
+            child.stdin.write(stdinData);
+            child.stdin.end();
+            child.on('error', (err) => {
+                clearTimeout(timer);
+                if (err.code === 'ENOENT') {
+                    reject(new Error('找不到 claude 命令，请先安装 Claude Code CLI\n' +
+                        '安装: npm install -g @anthropic-ai/claude-code\n' +
+                        '参考: https://github.com/jnMetaCode/agency-orchestrator#llm-配置'));
+                }
+                else {
+                    reject(new Error(`Claude Code CLI 调用失败: ${err.message}`));
+                }
+            });
+            child.on('close', (code) => {
+                clearTimeout(timer);
+                if (killed) {
+                    reject(new Error(`Claude Code CLI 超时 (${timeout / 1000}s)，可在 YAML 中设置 timeout 增加等待时间`));
+                    return;
+                }
+                if (code !== 0 && !stdout.trim()) {
+                    reject(new Error(`Claude Code CLI 调用失败 (exit ${code}): ${stderr.slice(0, 500)}`));
+                    return;
+                }
+                // 解析 JSON 响应
+                try {
+                    const json = JSON.parse(stdout);
+                    if (json.is_error) {
+                        reject(new Error(`Claude Code CLI 错误: ${json.result?.slice(0, 300) || 'unknown error'}`));
+                        return;
+                    }
+                    const content = (json.result || '').trim();
+                    if (!content) {
+                        reject(new Error(`Claude Code CLI 返回空内容`));
+                        return;
+                    }
+                    // 从 JSON 中提取真实 usage
+                    const usage = json.usage || json.modelUsage || {};
+                    resolve({
+                        content,
+                        usage: {
+                            input_tokens: usage.input_tokens || usage.inputTokens || 0,
+                            output_tokens: usage.output_tokens || usage.outputTokens || 0,
+                        },
+                    });
+                }
+                catch {
+                    // JSON 解析失败，回退到原始文本
+                    const content = stdout.trim();
+                    if (!content) {
+                        reject(new Error(`Claude Code CLI 返回空内容，stderr: ${stderr.slice(0, 500)}`));
+                        return;
+                    }
+                    // 检测 API 错误
+                    if (content.length < 500) {
+                        const apiErrorPattern = /^API Error:|^ECONNRESET|^ETIMEDOUT|^ECONNREFUSED|^Unable to connect|^socket hang up/im;
+                        if (apiErrorPattern.test(content)) {
+                            reject(new Error(`Claude Code CLI API 错误: ${content.slice(0, 300)}`));
+                            return;
+                        }
+                    }
+                    resolve({
+                        content,
+                        usage: { input_tokens: 0, output_tokens: 0 },
+                    });
+                }
+            });
         });
     }
 }

package/dist/connectors/cli-base.d.ts

@@ -4,8 +4,12 @@ export interface CLIConnectorConfig {
     command: string;
     /** 显示名称（用于错误消息） */
     displayName: string;
+    /** 安装提示（ENOENT 时显示） */
+    installHint?: string;
     /** 构建命令行参数 */
     buildArgs: (fullPrompt: string, config: LLMConfig) => string[];
+    /** 构建 stdin 模式的参数（prompt 过长时使用，默认用 buildArgs 替换 prompt 为 '-'） */
+    buildStdinArgs?: (config: LLMConfig) => string[];
     /** 从 stdout 提取内容（默认 trim） */
     parseOutput?: (stdout: string) => string;
 }