autocoder-cli-sdk/README.md

Node.js SDK for AutoCoder CLI - 便于在Node.js代码中调用auto-coder.run功能

# AutoCoder CLI SDK for Node.js

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

## 特性

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

## 安装

### 使用 pnpm (推荐)

```bash
cd cli-sdks/nodejs
pnpm install
```

### 使用 npm

```bash
cd cli-sdks/nodejs
npm install
```

## 快速开始

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

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

const client = new AutoCoderClient();

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

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

```typescript
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}`);
  }
}
```

### 便利方法

```typescript
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}`);
```

### 中止操作

```typescript
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`

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

```typescript
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`

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

```typescript
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`

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

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

### 配置类型

#### `SDKConfig`

```typescript
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`

```typescript
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;
}
```

## 高级用法

### 会话管理

```typescript
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('添加单元测试'); // 继续上下文
```

### 批量并发查询

```typescript
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结果'}`);
});
```

### 文件输入

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

const client = new AutoCoderClient();

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

### 配置管理

```typescript
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);
}
```

## 开发

### 设置开发环境

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

### 开发任务

```bash
# 构建
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接口演示

运行示例：

```bash
pnpm run example:basic
pnpm run example:async
pnpm run example:generator
```

## 错误处理

```typescript
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);
  }
}
```

## 诊断工具

```typescript
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 支持：

```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