AutoCoder CLI SDK for Node.js

一个便于在Node.js/TypeScript代码中调用auto-coder.run功能的SDK，无需直接使用child_process或fork进程。

特性

• 🚀 易于使用: 提供简洁直观的API接口
• 🔄 异步优先: 基于AsyncGenerator的现代异步设计
• 📡 流式处理: 支持实时流式输出和事件处理
• 💬 会话管理: 内置会话管理，支持多轮对话
• ⚡ 并发支持: 支持批量并发查询
• 🛠 完整配置: 支持所有auto-coder.run命令行选项
• 📦 TypeScript优先: 完整的类型定义和类型安全
• 🔧 进程控制: 支持abort操作和进程管理
• 🧪 诊断工具: 内置环境诊断和问题排查

安装

使用 pnpm (推荐)

cd cli-sdks/nodejs
pnpm install

使用 npm

cd cli-sdks/nodejs
npm install

快速开始

基础用法（文本格式 - AsyncGenerator接口）

import { AutoCoderClient } from 'autocoder-cli-sdk';

const client = new AutoCoderClient();

for await (const line of client.query('创建一个TypeScript函数来计算斐波那契数列')) {
  console.log(line); // 逐行输出生成的代码
}

JSON格式输出（类型安全的响应）

import { AutoCoderClient, QueryResponseModel } from 'autocoder-cli-sdk';

const client = new AutoCoderClient();

for await (const response of client.query('创建一个TypeScript类', { outputFormat: 'json' })) {
  if (response instanceof QueryResponseModel) {
    console.log(`事件总数: ${response.summary.totalEvents}`);
    console.log(`最终结果: ${response.finalResult}`);
  }
}

便利方法

import { AutoCoderClient } from 'autocoder-cli-sdk';

const client = new AutoCoderClient();

// 快速查询（返回字符串）
const result = await client.quickQuery('创建一个TypeScript接口');
console.log(result);

// JSON查询（返回类型安全的模型）
const model = await client.jsonQuery('创建一个类');
console.log(`事件数: ${model.summary.totalEvents}`);

中止操作

import { AutoCoderClient } from 'autocoder-cli-sdk';

const client = new AutoCoderClient();

// 启动查询
const queryPromise = (async () => {
  for await (const line of client.query('复杂的查询任务')) {
    console.log(line);
  }
})();

// 5秒后中止
setTimeout(async () => {
  if (client.isRunning()) {
    await client.abort();     // 优雅中止
    // 或 await client.abortForce(); // 强制中止
  }
}, 5000);

API 文档

客户端类

AutoCoderClient

主要的客户端类，提供所有核心功能。

class AutoCoderClient {
  constructor(config?: Partial<SDKConfig>);
  
  // 核心方法
  query(prompt: string, options?: Partial<QueryOptions>): AsyncGenerator<QueryResult>;
  quickQuery(prompt: string, options?: Partial<QuickQueryOptions>): Promise<string>;
  jsonQuery(prompt: string, options?: Partial<JsonQueryOptions>): Promise<QueryResponseModel>;
  queryFromFile(filePath: string, options?: Partial<QueryOptions>): AsyncGenerator<QueryResult>;
  
  // 配置和状态
  configure(configDict: Record<string, string>): Promise<ConfigResultModel>;
  getVersion(): Promise<string>;
  checkAvailability(): { sdkAvailable: boolean; subprocessAvailable: Promise<boolean> };
  
  // 进程控制
  abort(): Promise<boolean>;
  abortForce(): Promise<boolean>;
  isRunning(): boolean;
}

SessionManager

会话管理器，支持多轮对话。

class SessionManager {
  constructor(client: AutoCoderClient, sessionId?: string);
  
  query(prompt: string, options?: Partial<QueryOptions>): AsyncGenerator<QueryResult>;
  quickQuery(prompt: string, options?: Partial<QuickQueryOptions>): Promise<string>;
  jsonQuery(prompt: string, options?: Partial<JsonQueryOptions>): Promise<QueryResponseModel>;
}

BatchQueryManager

批量查询管理器，支持并发查询。

class BatchQueryManager {
  constructor(client: AutoCoderClient);
  
  batchQuery(
    prompts: string[],
    options?: Partial<QueryOptions>,
    maxConcurrency?: number
  ): Promise<Array<string[] | QueryResponseModel>>;
}

配置类型

SDKConfig

interface SDKConfig {
  defaultModel?: string;
  defaultMaxTurns?: number;
  defaultPermissionMode?: 'manual' | 'acceptEdits';
  defaultOutputFormat?: 'text' | 'json' | 'stream-json';
  verbose?: boolean;
  defaultCwd?: string;
  systemPromptPath?: string;
  includeRules?: boolean;
  defaultAllowedTools?: string[];
}

QueryOptions

interface QueryOptions {
  // 基础查询选项
  model?: string;
  maxTurns?: number;
  systemPrompt?: string;
  systemPromptPath?: string;
  outputFormat?: 'text' | 'json' | 'stream-json';
  inputFormat?: 'text' | 'json' | 'stream-json';
  verbose?: boolean;
  cwd?: string;
  
  // 会话管理
  sessionId?: string;
  continueSession?: boolean;
  
  // 工具和权限
  allowedTools?: string[];
  permissionMode?: 'manual' | 'acceptEdits';
  
  // 高级选项
  includeRules?: boolean;
  pr?: boolean;
  isSubAgent?: boolean;
  
  // 异步代理运行器选项
  asyncMode?: boolean;
  splitMode?: 'h1' | 'h2' | 'h3' | 'any' | 'delimiter';
  delimiter?: string;
  minLevel?: number;
  maxLevel?: number;
  workdir?: string;
  fromBranch?: string;
  bgMode?: boolean;
  taskPrefix?: string;
  worktreeName?: string;
}

高级用法

会话管理

import { AutoCoderClient, SessionManager } from 'autocoder-cli-sdk';

const client = new AutoCoderClient();
const session = new SessionManager(client);

// 多轮对话
const result1 = await session.quickQuery('创建一个User接口');
const result2 = await session.quickQuery('为User接口添加验证方法'); // 基于上下文
const result3 = await session.quickQuery('添加单元测试'); // 继续上下文

批量并发查询

import { AutoCoderClient, BatchQueryManager } from 'autocoder-cli-sdk';

const client = new AutoCoderClient();
const batchManager = new BatchQueryManager(client);

const prompts = [
  '创建一个用户管理模块',
  '创建一个日志模块',
  '创建一个配置管理模块'
];

// 并发执行，最大并发数为2
const results = await batchManager.batchQuery(prompts, {}, 2);

results.forEach((result, i) => {
  console.log(`查询 ${i+1}: ${Array.isArray(result) ? '文本结果' : 'JSON结果'}`);
});

文件输入

import { AutoCoderClient } from 'autocoder-cli-sdk';

const client = new AutoCoderClient();

// 从文件读取提示内容
for await (const line of client.queryFromFile('./prompt.txt', { outputFormat: 'text' })) {
  console.log(line);
}

配置管理

import { AutoCoderClient } from 'autocoder-cli-sdk';

const client = new AutoCoderClient();

// 设置配置
const result = await client.configure({
  'model': 'gpt-4',
  'max_turns': '25',
  'permission_mode': 'acceptEdits'
});

if (result.success) {
  console.log('配置更新成功');
  console.log('应用的配置:', result.appliedConfigs);
}

开发

设置开发环境

cd cli-sdks/nodejs
pnpm install  # 安装所有依赖

开发任务

# 构建
pnpm run build

# 开发模式（监听文件变化）
pnpm run dev

# 运行测试
pnpm run test
pnpm run test:coverage

# 代码检查和格式化
pnpm run lint
pnpm run lint:fix
pnpm run format
pnpm run typecheck

# 运行示例
pnpm run example:basic
pnpm run example:async
pnpm run example:generator
pnpm run example:diagnostics

示例项目

查看 examples/ 目录中的完整示例：

• basic-usage.ts - 基础用法演示
• async-usage.ts - 异步用法演示
• generator-usage.ts - Generator接口演示

运行示例：

pnpm run example:basic
pnpm run example:async
pnpm run example:generator

错误处理

import { 
  AutoCoderClient, 
  AutoCoderError, 
  ValidationError, 
  ExecutionError 
} from 'autocoder-cli-sdk';

const client = new AutoCoderClient();

try {
  for await (const line of client.query('创建一个函数')) {
    console.log(line);
  }
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('参数验证失败:', error.message);
  } else if (error instanceof ExecutionError) {
    console.error('执行失败:', error.message, '退出码:', error.exitCode);
  } else if (error instanceof AutoCoderError) {
    console.error('SDK错误:', error.message);
  } else {
    console.error('未知错误:', error);
  }
}

诊断工具

import { runDiagnostics } from 'autocoder-cli-sdk';

// 运行完整诊断
const results = await runDiagnostics(true); // verbose=true

// 检查结果
console.log('环境状态:', results.environment);
console.log('依赖状态:', results.dependencies);
console.log('AutoCoder状态:', results.autocoder);

类型安全

SDK 提供完整的 TypeScript 支持：

import { 
  AutoCoderClient, 
  type QueryOptions, 
  type QueryResponseModel 
} from 'autocoder-cli-sdk';

const client: AutoCoderClient = new AutoCoderClient();
const options: QueryOptions = { maxTurns: 10 };

for await (const result of client.query('prompt', options)) {
  // TypeScript 会自动推断 result 的类型
  if (typeof result === 'string') {
    console.log('文本结果:', result);
  } else {
    console.log('JSON结果:', result.summary.totalEvents);
  }
}

版本兼容性

• Node.js 14.0+
• TypeScript 5.0+
• 兼容所有版本的auto-coder.run命令行工具
• 使用 pnpm 作为包管理器

许可证

MIT License - 详见 LICENSE 文件。

贡献

欢迎提交Issue和Pull Request来改进这个SDK。开发流程：

1. Fork 项目
2. 创建功能分支
3. 使用 pnpm install 设置开发环境
4. 运行 pnpm run test 确保测试通过
5. 运行 pnpm run lint:fix 和 pnpm run format 格式化代码
6. 提交 Pull Request