@kongfu/api-client

官方 Kongfu API 客户端 SDK，提供类型安全的 API 访问接口。

安装

npm install @kongfu/api-client
# 或
yarn add @kongfu/api-client
# 或
pnpm add @kongfu/api-client

快速开始

import { createClient } from '@kongfu/api-client';

// 创建客户端实例
const client = createClient({
  baseUrl: 'http://localhost:3210',
  apiKey: 'your-api-key', // 可选
  timeout: 30000, // 可选，默认 30 秒
});

// 使用客户端
async function example() {
  // 获取任务列表
  const tasks = await client.tasks.list({
    status: 'todo',
    limit: 10,
  });

  // 创建新任务
  const newTask = await client.tasks.create({
    name: '实现用户认证',
    type: 'feature',
    priority: 'high',
  });

  // 更新任务状态
  await client.tasks.update(newTask.id, {
    status: 'doing',
    progress: 50,
  });
}

主要功能

任务管理

// 获取任务列表
const tasks = await client.tasks.list({
  status: ['todo', 'doing'],
  owner: '@alice',
  sortBy: 'priority',
  sortOrder: 'desc',
});

// 获取单个任务
const task = await client.tasks.get('task-id');

// 创建任务
const newTask = await client.tasks.create({
  name: '修复登录问题',
  type: 'bug',
  priority: 'urgent',
  description: '用户无法使用邮箱登录',
});

// 更新任务
await client.tasks.update('task-id', {
  status: 'done',
  progress: 100,
});

// 删除任务
await client.tasks.delete('task-id');

// 批量操作
await client.tasks.batchCreate([task1, task2, task3]);
await client.tasks.batchUpdate([
  { id: 'task1', data: { status: 'done' } },
  { id: 'task2', data: { status: 'review' } },
]);

// 任务统计
const stats = await client.tasks.getStats();

Agent 管理

// 获取 Agent 列表
const agents = await client.agents.list({
  category: 'development',
  status: 'active',
});

// 执行任务
const result = await client.agents.execute('agent-id', {
  task: {
    type: 'code-review',
    name: '代码审查',
    parameters: {
      files: ['src/auth.ts', 'src/user.ts'],
    },
  },
  context: {
    projectId: 'project-123',
  },
});

// 获取协作建议
const suggestions = await client.agents.getCollaborationSuggestions(
  'agent-id',
  'feature'
);

Flow 管理

// 获取流程列表
const flows = await client.flows.list({
  status: 'published',
});

// 创建流程
const flow = await client.flows.create({
  name: '代码发布流程',
  description: '自动化代码发布流程',
  nodes: [...],
  edges: [...],
});

// 执行流程
const execution = await client.flows.execute('flow-id', {
  variables: {
    branch: 'main',
    environment: 'production',
  },
});

// 获取执行状态
const status = await client.flows.getExecutionStatus(
  'flow-id',
  execution.id
);

实时更新 (SSE)

// 订阅任务更新
const unsubscribeTask = client.subscribeToTaskUpdates((task) => {
  console.log('任务更新:', task);
});

// 订阅 Agent 执行状态
const unsubscribeAgent = client.subscribeToAgentExecution(
  'agent-id',
  (status) => {
    console.log('执行状态:', status);
  }
);

// 订阅系统通知
const unsubscribeNotifications = client.subscribeToNotifications(
  (notification) => {
    console.log('系统通知:', notification);
  }
);

// 取消订阅
unsubscribeTask();
unsubscribeAgent();
unsubscribeNotifications();

// 或者直接管理 SSE 连接
const sseClient = client.createSSEConnection('/api/custom/stream');
sseClient.connect();

sseClient.on('custom-event', (data) => {
  console.log('自定义事件:', data);
});

// 关闭连接
sseClient.disconnect();

错误处理

try {
  const task = await client.tasks.get('non-existent-id');
} catch (error) {
  if (error.statusCode === 404) {
    console.error('任务不存在');
  } else if (error.statusCode === 401) {
    console.error('认证失败');
  } else {
    console.error('请求失败:', error.message);
  }
}

TypeScript 支持

SDK 提供完整的 TypeScript 类型定义：

import type {
  Task,
  TaskStatus,
  Agent,
  AgentCategory,
  Flow,
  FlowExecutionStatus,
} from '@kongfu/api-client';

// 使用类型
function processTask(task: Task): void {
  if (task.status === 'done') {
    console.log(`任务 ${task.name} 已完成`);
  }
}

// 自定义扩展
interface CustomTask extends Task {
  customField: string;
}

高级配置

自定义请求头

const client = createClient({
  baseUrl: 'http://localhost:3210',
  apiKey: 'your-api-key',
});

// 为单个请求添加自定义头
await client.tasks.list({}, {
  headers: {
    'X-Custom-Header': 'value',
  },
});

请求超时

// 全局超时设置
const client = createClient({
  baseUrl: 'http://localhost:3210',
  timeout: 60000, // 60 秒
});

// 单个请求超时
await client.tasks.create(taskData, {
  timeout: 5000, // 5 秒
});

请求取消

const controller = new AbortController();

// 发起请求
const promise = client.tasks.list({}, {
  signal: controller.signal,
});

// 取消请求
controller.abort();

API 参考

完整的 API 文档请参考 Kongfu API 文档。

许可证

MIT