ccapi-server

English

ccapi 的核心服务包。将 Claude Code CLI 封装为 HTTP 和 WebSocket 端点 —— 支持 spawn 和 Docker 执行、单轮和多轮会话。

安装

该包通常作为 ccapi-cli 的依赖使用。也可以直接编程调用：

npm install ccapi-server

编程调用

startServer(options?)

启动一个由 Claude Code 驱动的 HTTP 服务。

import { startServer } from 'ccapi-server';

await startServer({
  workspaceDir: './my-workspace',
  port: 3000,
  maxTurns: 10,
  timeoutMs: 300_000,
  session: true,
  execution: 'spawn',
});

| 选项 | 环境变量 | 默认值 | | -------------- | --------------- | --------------- | | workspaceDir | WORKSPACE_DIR | .（当前目录） | | port | PORT | 3000 | | maxTurns | MAX_TURNS | 10 | | timeoutMs | TIMEOUT_MS | 300000 | | session | SESSION | false | | execution | EXECUTION | spawn | | dockerImage | DOCKER_IMAGE | — |

callClaude(options)

通过 spawn 调用 Claude Code CLI。

import { callClaude } from 'ccapi-server';

const result = await callClaude({
  prompt: 'Hello World',
  cwd: './my-workspace',
  maxTurns: 10,
  timeout: 300_000,
});

console.log(result.result); // Claude 的回复
console.log(result.cost); // 费用（美元）
console.log(result.duration_ms); // 耗时（毫秒）
console.log(result.session_id); // 会话 ID

callClaudeDocker(options)

在 Docker 容器中调用 Claude Code CLI。

import { callClaudeDocker } from 'ccapi-server';

const result = await callClaudeDocker({
  prompt: 'Hello World',
  image: 'cc-image',
  cwd: '/workspace',
  volumes: [{ host: '/path/to/workspace', container: '/workspace' }],
  env: { ANTHROPIC_AUTH_TOKEN: '...' },
  maxTurns: 10,
  timeout: 300_000,
});

SessionManager

基于用户的多轮会话管理。

import { SessionManager } from 'ccapi-server';

const manager = new SessionManager();
const session = manager.getOrCreate('user-123');
// session.sessionId, session.isNew

// 调用成功后：
manager.markUsed(session.sessionId);

// 清理：
manager.cleanup(session.sessionId);

connectRelay(url, handlers, options?)

作为 agent 连接到 WebSocket 中继服务器。内置指数退避自动重连和客户端 ping/pong 死连接检测。

import { connectRelay } from 'ccapi-server';

const relay = connectRelay(
  'wss://relay-server/ws/agent?token=xxx',
  {
    onPrompt: async (userId, sessionId, prompt) => {
      // 处理 prompt，返回结果字符串
      return 'Hello!';
    },
    onSessionEnd: (sessionId) => {
      // 清理会话
    },
  },
  {
    pingIntervalMs: 30_000, // 客户端 ping 间隔（默认 30s）
    reconnectBaseMs: 1_000, // 初始重连延迟（默认 1s）
    reconnectMaxMs: 30_000, // 最大重连延迟（默认 30s）
  },
);

// 优雅关闭：
relay.close();

| 选项 | 默认值 | 说明 | | ----------------- | -------- | ---------------------------------------- | | instanceId | 随机生成 | 注册时发送的唯一 agent 实例 ID | | reconnectBaseMs | 1000 | 初始重连延迟（指数退避 + 30% 随机抖动） | | reconnectMaxMs | 30000 | 最大重连延迟上限 | | pingIntervalMs | 30000 | 客户端 ping 间隔；未收到 pong 则断开重连 |

HTTP API

POST /

请求：

{ "prompt": "Hello World" }

响应：

{
  "result": "Hello!",
  "cost": 0.001,
  "duration_ms": 1234
}

GET /health

返回 { "status": "ok" }。

Workspace 目录

workspaceDir 是 Claude Code 的运行目录。在该目录下放置 CLAUDE.md 来定义 Claude 的行为（系统提示词），可选放置 .claude/settings.json 来限制可用工具。

my-workspace/
├── CLAUDE.md
└── .claude/
    └── settings.json