# csc serve — HTTP API 接口规范

> `csc serve` 启动一个 HTTP 服务器，为 IDE 插件和 Web 客户端提供 REST API。
> 内部架构为 **子进程模式**：每个会话 spawn 一个 `csc --print --input-format stream-json --output-format stream-json` 子进程，HTTP 层作为 NDJSON 协议的桥梁。

## 设计原则

1. **API 路径兼容 opencode serve**：cs-cloud 通过路由表映射，客户端无需感知后端差异
2. **子进程隔离**：1 session = 1 子进程，无进程内多会话
3. **子进程复用**：同一 session 的多次 prompt 复用同一子进程（bridge 模式已验证）
4. **JSONL 持久化**：会话数据沿用 csc 现有的 transcript JSONL 文件
5. **文件系统操作由 cs-cloud 自有接口处理**：`/api/v1/runtime/files` 等不经过 csc serve

## CLI 入口

```bash
csc serve [options]

Options:
  --port <port>        监听端口（默认 0 = 自动分配）
  --host <host>        监听地址（默认 127.0.0.1）
  --auth-token <token>  Bearer token 认证
  --workspace <dir>     默认工作目录
  --max-sessions <n>    最大并发会话数（默认 32）
  --idle-timeout <ms>   空闲会话超时（默认 1800000 = 30 分钟，0 = 永不超时）
```

stdout 输出端口信息（供 cs-cloud 解析）：

```
csc server listening on http://127.0.0.1:{port}
```

---

## API 端点总览

| 分类 | 端点数 | 说明 |
|---|---|---|
| Server | 1 | 健康检查 |
| Info | 5 | 路径、VCS、命令、agent 模式、MCP 状态 |
| Session | 11 | 会话 CRUD、prompt、abort |
| Event | 1 | SSE 事件流 |
| Permission | 2 | 权限请求列表、回复 |
| Question | 3 | 问题请求列表、回复、拒绝 |
| Message | 3 | 消息历史、todo、diff |
| Provider | 2 | 模型/Provider 信息 |
| **合计** | **28** | |

---

## 1. Server

### `GET /health`

服务健康检查。

**Response 200:**

```json
{
  "status": "ok",
  "version": "4.0.1",
  "uptime_ms": 12345,
  "active_sessions": 3
}
```

---

## 2. Info

### `GET /path`

获取路径信息。

**Response 200:**

```json
{
  "home": "/Users/user",
  "state": "/Users/user/.claude",
  "config": "/Users/user/.claude",
  "directory": "/path/to/workspace"
}
```

### `GET /vcs`

获取 VCS 信息。

**Response 200:**

```json
{
  "branch": "main"
}
```

### `GET /command`

列出可用 slash 命令。

**Response 200:**

```json
[
  { "name": "compact", "description": "Compact conversation" },
  { "name": "clear", "description": "Clear conversation" },
  { "name": "help", "description": "Show help" }
]
```

数据来源：子进程 `initialize` response 中的 `commands` 字段。

### `GET /agent`

列出可用的 agent 模式。

**Response 200:**

```json
[
  { "id": "main", "name": "Main Agent" },
  { "id": "plan", "name": "Plan Mode" }
]
```

数据来源：子进程 `initialize` response 中的 `agents` 字段。

### `GET /mcp`

获取 MCP 服务器状态。通过子进程 `mcp_status` control-request 获取。

**Response 200:**

```json
{
  "servers": [
    { "name": "filesystem", "status": "connected", "tools": 5 },
    { "name": "github", "status": "disconnected", "error": "Connection refused" }
  ]
}
```

---

## 3. Session

### `POST /session`

创建新会话。spawn 一个 `csc --print` 子进程。

**Request Body:**

```json
{
  "cwd": "/path/to/project",
  "permission_mode": "default",
  "model": "claude-sonnet-4-20250514",
  "system_prompt": "optional system prompt",
  "resume_session_id": "optional-uuid-to-resume"
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `cwd` | string | 否 | 工作目录，默认为 serve 的 `--workspace` |
| `permission_mode` | string | 否 | 权限模式：`default` / `bypassPermissions` / `plan` |
| `model` | string | 否 | 初始模型 |
| `system_prompt` | string | 否 | 自定义 system prompt |
| `resume_session_id` | string | 否 | 恢复已有会话的 ID |

**Response 201:**

```json
{
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "starting",
  "cwd": "/path/to/project",
  "created_at": 1713001234567
}
```

子进程启动完成后通过 SSE 推送 `session.ready` 事件。

### `GET /session`

列出所有会话。

**Query Parameters:**

| 参数 | 类型 | 说明 |
|---|---|---|
| `limit` | number | 分页大小（默认 50） |
| `offset` | number | 分页偏移 |
| `search` | string | 搜索会话标题 |

**Response 200:**

```json
{
  "sessions": [
    {
      "session_id": "uuid-1",
      "status": "running",
      "cwd": "/path/to/project",
      "title": "Fix authentication bug",
      "model": "claude-sonnet-4-20250514",
      "permission_mode": "default",
      "created_at": 1713001234567,
      "last_active_at": 1713001299999,
      "cost_usd": 0.0523,
      "api_duration_ms": 12345
    }
  ]
}
```

数据来源：内存中的活跃会话 + `~/.claude/server-sessions.json` 持久化索引 + 各 session 的 transcript JSONL 头部。

### `GET /session/:sessionID`

获取单个会话详情。

**Response 200:**

```json
{
  "session_id": "uuid-1",
  "status": "running",
  "cwd": "/path/to/project",
  "title": "Fix authentication bug",
  "model": "claude-sonnet-4-20250514",
  "permission_mode": "default",
  "created_at": 1713001234567,
  "last_active_at": 1713001299999,
  "cost_usd": 0.0523,
  "api_duration_ms": 12345,
  "message_count": 12,
  "usage": {
    "input_tokens": 15000,
    "output_tokens": 5000,
    "cache_read_input_tokens": 10000,
    "cache_creation_input_tokens": 2000
  }
}
```

**Response 404:**

```json
{ "error": "session not found" }
```

### `PATCH /session/:sessionID`

更新会话属性。

**Request Body:**

```json
{
  "title": "New title",
  "model": "claude-sonnet-4-20250514",
  "permission_mode": "bypassPermissions"
}
```

`model` 和 `permission_mode` 的变更通过子进程的 control_request 实现（`set_model` / `set_permission_mode`）。

**Response 200:**

```json
{
  "session_id": "uuid-1",
  "title": "New title",
  "model": "claude-sonnet-4-20250514",
  "permission_mode": "bypassPermissions"
}
```

### `DELETE /session/:sessionID`

删除会话。kill 子进程 + 清理持久化索引。

**Response 200:**

```json
{ "deleted": true }
```

### `GET /session/status`

批量获取所有会话的状态。

**Response 200:**

```json
{
  "sessions": {
    "uuid-1": { "status": "running", "has_pending_permission": false },
    "uuid-2": { "status": "idle", "has_pending_permission": true }
  }
}
```

### `POST /session/:sessionID/prompt`

发送 prompt 并流式返回响应。对应子进程 stdin 写入 `SDKUserMessage`。

**Request Body:**

```json
{
  "content": "Fix the authentication bug in login.ts",
  "files": ["src/login.ts"],
  "images": []
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `content` | string | 是 | 用户输入内容 |
| `files` | string[] | 否 | 附带的文件路径（作为 context） |
| `images` | object[] | 否 | 图片附件（base64 或 URL） |

**Response 200 (streaming):**

Content-Type: `text/event-stream`

```
event: message
data: {"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"I'll fix the"}]}}

event: message
data: {"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":" authentication bug."}]}}

event: message
data: {"type":"tool_progress","tool_name":"Edit","elapsed_time_seconds":1}

event: message
data: {"type":"assistant","message":{"role":"assistant","content":[{"type":"tool_use","id":"toolu_xxx","name":"Edit","input":{...}}]}}

event: result
data: {"type":"result","subtype":"success","cost_usd":0.0123,"duration_ms":5432,"usage":{"input_tokens":5000,"output_tokens":2000}}
```

事件类型直接映射子进程 stdout NDJSON 的 `SDKMessage.type`：

| NDJSON type | SSE event | 说明 |
|---|---|---|
| `assistant` | `message` | assistant 流式内容 |
| `partial_assistant` | `message` | 原始 API 流式事件 |
| `tool_progress` | `message` | 工具执行进度 |
| `result` | `result` | 最终结果（含 cost/usage） |
| `result_success` | `result` | 成功结果 |
| `system` | `system` | 系统消息（init、compact_boundary 等） |
| `status` | `system` | 状态变更 |
| `control_request` | `control_request` | 权限/交互请求 |
| `permission_denial` | `system` | 权限被拒绝 |

### `POST /session/:sessionID/prompt_async`

异步 prompt。立即返回，后台执行。通过 SSE 推送事件。

**Request Body:** 同 `prompt`。

**Response 204:** No Content

### `POST /session/:sessionID/abort`

中止当前正在执行的 prompt。向子进程发送 `control_request { subtype: "interrupt" }`，如果无响应则 SIGTERM。

**Response 200:**

```json
{ "aborted": true }
```

### `POST /session/:sessionID/shell`

在会话上下文中执行 shell 命令。转换为 prompt 发送到子进程。

**Request Body:**

```json
{
  "command": "npm test"
}
```

**Response 200 (streaming):** 同 `prompt` 的 SSE 流。

### `POST /session/:sessionID/command`

执行 slash 命令。转换为对应 prompt 发送到子进程。

**Request Body:**

```json
{
  "command": "/compact"
}
```

**Response 200 (streaming):** 同 `prompt` 的 SSE 流。

---

## 4. Event

### `GET /event`

全局 SSE 事件流。聚合所有会话的事件。

**Query Parameters:**

| 参数 | 类型 | 说明 |
|---|---|---|
| `session_id` | string | 可选，只订阅特定会话的事件 |

**Response 200 (SSE):**

```
event: connected
data: {"type":"server.connected"}

event: session.created
data: {"session_id":"uuid-1","status":"starting"}

event: session.ready
data: {"session_id":"uuid-1","status":"running","model":"claude-sonnet-4-20250514"}

event: session.message
data: {"session_id":"uuid-1","type":"assistant","message":{...}}

event: session.result
data: {"session_id":"uuid-1","type":"result","cost_usd":0.0123,"duration_ms":5432}

event: session.control_request
data: {"session_id":"uuid-1","request_id":"req-1","request":{"subtype":"can_use_tool","tool_name":"Bash","input":{...}}}

event: session.status_changed
data: {"session_id":"uuid-1","status":"idle"}

event: session.deleted
data: {"session_id":"uuid-1"}

event: heartbeat
data: {"type":"server.heartbeat","ts":1713001234567}
```

所有 session 相关事件都带 `session_id` 字段。心跳间隔 10 秒。

---

## 5. Permission

### `GET /permission`

列出所有待处理的权限请求。

**Response 200:**

```json
{
  "permissions": [
    {
      "request_id": "req-1",
      "session_id": "uuid-1",
      "tool_name": "Bash",
      "tool_use_id": "toolu_xxx",
      "input": { "command": "rm -rf node_modules" },
      "title": "Bash: rm -rf node_modules",
      "description": "Execute bash command"
    }
  ]
}
```

数据来源：拦截子进程 stdout 的 `control_request { subtype: "can_use_tool" }` 消息，缓存在内存。

### `POST /permission/:requestID/reply`

回复权限请求。向对应子进程 stdin 写入 `control_response`。

**Request Body (allow):**

```json
{
  "behavior": "allow",
  "updated_input": { "command": "rm -rf node_modules" }
}
```

**Request Body (deny):**

```json
{
  "behavior": "deny",
  "message": "Command not allowed"
}
```

**Response 200:**

```json
{ "resolved": true }
```

---

## 6. Question

csc 通过 `control_request { subtype: "elicitation" }` 实现 MCP elicitation 交互，映射为 question 端点。

### `GET /question`

列出所有待处理的问题请求。

**Response 200:**

```json
{
  "questions": [
    {
      "request_id": "req-2",
      "session_id": "uuid-1",
      "mcp_server_name": "my-server",
      "message": "Please provide your API key",
      "mode": "form",
      "requested_schema": { "type": "object", "properties": { "key": { "type": "string" } } }
    }
  ]
}
```

### `POST /question/:requestID/reply`

回复问题请求。

**Request Body:**

```json
{
  "action": "accept",
  "content": { "key": "sk-xxx" }
}
```

**Response 200:**

```json
{ "resolved": true }
```

### `POST /question/:requestID/reject`

拒绝问题请求。

**Request Body:**

```json
{
  "action": "decline"
}
```

**Response 200:**

```json
{ "resolved": true }
```

---

## 7. Message

### `GET /session/:sessionID/message`

获取会话消息历史。读取 transcript JSONL 文件。

**Query Parameters:**

| 参数 | 类型 | 说明 |
|---|---|---|
| `limit` | number | 返回条数（默认 50） |
| `before` | string | 游标：返回此 UUID 之前的消息 |
| `include_system` | boolean | 是否包含 system 消息（默认 false） |

**Response 200:**

```json
{
  "messages": [
    {
      "uuid": "msg-uuid-1",
      "type": "user",
      "role": "user",
      "content": "Fix the auth bug",
      "timestamp": 1713001234567,
      "parent_uuid": null
    },
    {
      "uuid": "msg-uuid-2",
      "type": "assistant",
      "role": "assistant",
      "content": [
        { "type": "text", "text": "I'll fix the authentication bug." },
        { "type": "tool_use", "id": "toolu_xxx", "name": "Edit", "input": { "file_path": "src/login.ts", "old_string": "...", "new_string": "..." } }
      ],
      "timestamp": 1713001234999,
      "parent_uuid": "msg-uuid-1",
      "usage": { "input_tokens": 5000, "output_tokens": 2000 }
    }
  ]
}
```

Headers:

```
Link: </session/uuid-1/message?before=msg-uuid-first>; rel="prev"
X-Next-Cursor: msg-uuid-first
```

实现方式：解析 `~/.claude/projects/<project>/sessions/<sessionID>.jsonl`，按 `parentUuid` 构建消息链。

### `GET /session/:sessionID/todo`

获取会话中的 todo/plan 列表。从 transcript 中提取 `tool_use[name=TodoWrite/TodoRead]` 消息。

**Response 200:**

```json
{
  "todos": [
    {
      "id": "todo-1",
      "content": "Fix authentication bug",
      "status": "in_progress",
      "priority": "high"
    },
    {
      "id": "todo-2",
      "content": "Add unit tests",
      "status": "pending",
      "priority": "medium"
    }
  ]
}
```

### `GET /session/:sessionID/diff`

获取会话中的文件变更。读取 csc 的 file-history 快照目录。

**Query Parameters:**

| 参数 | 类型 | 说明 |
|---|---|---|
| `messageID` | string | 可选，指定消息 ID 的变更 |

**Response 200:**

```json
{
  "diffs": [
    {
      "file": "src/login.ts",
      "status": "modified",
      "additions": 5,
      "deletions": 2,
      "patch": "--- a/src/login.ts\n+++ b/src/login.ts\n@@ -10,3 +10,6 @@..."
    }
  ]
}
```

注意：csc 的 file-history 没有索引，需要按 messageID 关联快照目录，实现复杂度中等。如果 messageID 未指定则返回全部变更。

---

## 8. Provider

### `GET /provider`

列出所有可用的 AI providers 和模型。

**Response 200:**

```json
{
  "connected": ["anthropic"],
  "default_model": "claude-sonnet-4-20250514",
  "providers": [
    {
      "id": "anthropic",
      "name": "Anthropic",
      "connected": true,
      "models": [
        {
          "id": "claude-sonnet-4-20250514",
          "name": "Claude Sonnet 4",
          "context_window": 200000,
          "max_output_tokens": 64000,
          "supports_images": true,
          "supports_streaming": true
        }
      ]
    }
  ]
}
```

数据来源：
- 读取 `~/.claude/settings.json` 中的 API key 配置
- 通过子进程的 `initialize` response 中的 `models` 字段获取模型列表

### `GET /provider/capabilities`

精简的模型能力列表（供模型选择 UI 使用）。

**Response 200:**

```json
{
  "connected": [
    {
      "provider_id": "anthropic",
      "provider_name": "Anthropic",
      "models": [
        {
          "model_id": "claude-sonnet-4-20250514",
          "model_name": "Claude Sonnet 4",
          "context_window": 200000,
          "max_output_tokens": 64000,
          "supports_images": true,
          "input_cost_per_million": 3.0,
          "output_cost_per_million": 15.0
        }
      ]
    }
  ]
}
```

---

## 9. Find

### `GET /find/file`

按文件名搜索文件。

**Query Parameters:**

| 参数 | 类型 | 说明 |
|---|---|---|
| `query` | string | 搜索模式（必填） |
| `dirs` | string | 是否包含目录（"true" / "false"） |
| `limit` | number | 结果数量限制 |

**Response 200:**

```json
["src/login.ts", "src/logout.ts", "tests/login.test.ts"]
```

---

## 错误格式

所有错误响应使用统一格式：

```json
{
  "error": "ERROR_CODE",
  "message": "Human readable error message"
}
```

| HTTP Status | Code | 说明 |
|---|---|---|
| 400 | `BAD_REQUEST` | 请求参数错误 |
| 401 | `UNAUTHORIZED` | 认证失败（需要 auth-token） |
| 404 | `NOT_FOUND` | 会话/资源不存在 |
| 409 | `CONFLICT` | 会话已在执行中（重复 prompt） |
| 429 | `TOO_MANY_SESSIONS` | 超过 max-sessions 限制 |
| 500 | `INTERNAL` | 内部错误 |
| 503 | `SESSION_ERROR` | 子进程崩溃或无响应 |

---

## 认证

如果启动时指定了 `--auth-token`，所有请求需要携带：

```
Authorization: Bearer <token>
```

未携带或 token 不匹配返回 401。

---

## 子进程生命周期

```
POST /session
  → spawn: csc --print --input-format stream-json --output-format stream-json
           [--session-id <id>] [--resume <id>] [--permission-mode <mode>]
           [--model <model>]
  → 状态: starting

子进程输出 system.init
  → 状态: running

POST /session/:id/prompt
  → stdin: SDKUserMessage
  → stdout → SSE: assistant/result/control_request
  → 状态: running → active → idle

POST /session/:id/abort
  → stdin: control_request { subtype: "interrupt" }
  → 如果无响应: SIGTERM

idle-timeout 到期
  → SIGTERM 子进程
  → 状态: stopped

DELETE /session/:id
  → SIGKILL 子进程
  → 清理 SessionIndex
```

---

## cs-cloud 路由映射

cs-cloud 作为反向代理，将客户端 API 映射到 csc serve：

| cs-cloud 路由 | → csc serve 路由 | 客户端调用 |
|---|---|---|
| `POST /api/v1/conversations` | `POST /session` | `conversation.create` |
| `GET /api/v1/conversations` | `GET /session` | `conversation.list` |
| `GET /api/v1/conversations/{id}` | `GET /session/{id}` | `conversation.get` |
| `PATCH /api/v1/conversations/{id}` | `PATCH /session/{id}` | `conversation.update` |
| `DELETE /api/v1/conversations/{id}` | `DELETE /session/{id}` | `conversation.delete` |
| `POST /api/v1/conversations/{id}/prompt` | `POST /session/{id}/prompt` | `conversation.prompt` |
| `POST /api/v1/conversations/{id}/prompt/async` | `POST /session/{id}/prompt_async` | `conversation.promptAsync` |
| `POST /api/v1/conversations/{id}/abort` | `POST /session/{id}/abort` | `conversation.abort` |
| `GET /api/v1/conversations/{id}/messages` | `GET /session/{id}/message` | `conversation.messages` |
| `GET /api/v1/conversations/{id}/todo` | `GET /session/{id}/todo` | `conversation.todo` |
| `GET /api/v1/conversations/{id}/diff` | `GET /session/{id}/diff` | `conversation.diff` |
| `POST /api/v1/conversations/{id}/shell` | `POST /session/{id}/shell` | `conversation.shell` |
| `POST /api/v1/conversations/{id}/command` | `POST /session/{id}/command` | `conversation.command` |
| `GET /api/v1/conversations/status` | `GET /session/status` | `conversation.status` |
| `GET /api/v1/events` | `GET /event` | `event.stream` |
| `GET /api/v1/permissions` | `GET /permission` | `interaction.permissions` |
| `POST /api/v1/permissions/{id}/reply` | `POST /permission/{id}/reply` | `interaction.permissionRespond` |
| `GET /api/v1/questions` | `GET /question` | `interaction.questions` |
| `POST /api/v1/questions/{id}/reply` | `POST /question/{id}/reply` | `interaction.questionReply` |
| `POST /api/v1/questions/{id}/reject` | `POST /question/{id}/reject` | `interaction.questionReject` |
| `GET /api/v1/agents/models` | `GET /provider/capabilities` | `runtime.modelCapabilities` |
| `GET /api/v1/agents/session-modes` | `GET /agent` | `runtime.sessionModes` |
| `GET /api/v1/agents` | `GET /provider` | `runtime.agentRuntimes` |

以下 cs-cloud 路由不代理到 csc serve，由 cs-cloud 自有接口处理：

| cs-cloud 自有路由 | 客户端调用 | 说明 |
|---|---|---|
| `GET /api/v1/runtime/health` | `runtime.health` | cs-cloud 进程自身健康检查 |
| `GET /api/v1/runtime/files` | `runtime.fileList` | cs-cloud 直接读文件系统 |
| `GET /api/v1/runtime/files/content` | `runtime.fileRead` | cs-cloud 直接读文件内容 |

以下透传路由不经过 `/api/v1` 前缀，cs-cloud 直接代理：

| cs-cloud 透传路由 | → csc serve 路由 | 客户端调用 |
|---|---|---|
| `GET /path` | `GET /path` | `runtime.targetContext` |
| `GET /vcs` | `GET /vcs` | `runtime.vcs` |
| `GET /command` | `GET /command` | `runtime.commands` |
| `GET /mcp` | `GET /mcp` | `runtime.mcpStatus` |
| `GET /find/file` | `GET /find/file` | `runtime.findFiles` |
| `POST /instance/dispose` | `GET /health`（带 shutdown 标记） | `runtime.instanceDispose` |

---

## 与 opencode serve 的差异

| 能力 | opencode serve | csc serve | 说明 |
|---|---|---|---|
| 进程模型 | 1 进程多会话 | 1 进程 = 1 子进程 | csc 单例架构限制 |
| 会话存储 | SQLite 数据库 | JSONL 文件 + 内存索引 | csc 沿用现有 transcript |
| `POST /session/:id/revert` | ✅ | ❌ | csc 有 `rewind_files` control-request 可部分替代，但无完整 revert |
| `POST /session/:id/unrevert` | ✅ | ❌ | 同上 |
| `POST /session/:id/summarize` | ✅ | ❌ | csc 有 compact 但无独立 summarize |
| `POST /session/:id/fork` | ✅ | ❌ | 需 JSONL 文件复制 + UUID 重映射 |
| `POST /session/:id/share` | ✅ | ❌ | csc 无 share 功能 |
| `DELETE /session/:id/share` | ✅ | ❌ | 同上 |
| `GET /session/:id/diff` | ✅（DB 索引） | ⚠️（读 file-history） | 无索引，性能较差 |
| `GET /project` | ✅ | ❌ | csc 无项目数据库 |
| `GET /pty` | ✅ | ❌ | PTY 在子进程内部，无法外部操作 |
| `GET /tui/*` | ✅（14 个端点） | ❌ | 仅 TUI 模式有意义 |
| `GET /experimental/*` | ✅（11 个端点） | ❌ | 高级功能，暂不支持 |
| 文件操作 | csc serve 处理 | cs-cloud 自有接口 | `/api/v1/runtime/files` 不经过 csc |