# cc-connect 管理 API 规范

> **版本：** 1.0-draft  
> **状态：** 草案 — 实现前可能变更  
> **最后更新：** 2026-03-10

---

## 1. 概述

cc-connect 管理 API 是基于 HTTP 的 REST API，供外部应用（Web 控制台、TUI 客户端、GUI 桌面应用、Mac 托盘应用等）管理和监控 cc-connect 实例。它是对现有内部 Unix 套接字 API 的补充，提供可通过网络访问、基于令牌认证的接口，适用于远程和本地管理工具。

### 1.1 架构

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         cc-connect Process                               │
│                                                                          │
│  ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐  │
│  │  Unix Socket API │    │  Management API   │    │  Bridge Server   │  │
│  │  (internal)      │    │  (HTTP :9820)     │    │  (WebSocket)     │  │
│  └────────┬─────────┘    └────────┬─────────┘    └────────┬─────────┘  │
│           │                       │                       │             │
│           └───────────────────────┼───────────────────────┘             │
│                                   │                                      │
│                          ┌────────┴────────┐                            │
│                          │  Core Engine(s)  │                            │
│                          │  Projects       │                            │
│                          │  Sessions      │                            │
│                          │  Cron/Heartbeat │                            │
│                          └─────────────────┘                            │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              │                     │                     │
     ┌────────┴────────┐   ┌───────┴───────┐   ┌─────────┴─────────┐
     │  Web Dashboard  │   │  TUI Client   │   │  Mac Tray App      │
     └─────────────────┘   └───────────────┘   └────────────────────┘
```

### 1.2 设计原则

- **RESTful：** 资源导向的 URL，标准 HTTP 方法
- **JSON：** 所有请求/响应体使用 `application/json`
- **统一封装：** 每个响应均使用 `{"ok": true|false, "data"|"error": ...}`
- **令牌认证：** 所有端点支持 Bearer 令牌或查询参数认证

---

## 2. 配置

### 2.1 管理配置块

在 `config.toml` 中添加以下配置：

```toml
[management]
enabled = true
port = 9820
token = "mgmt-secret"
```

| 字段       | 类型    | 默认值   | 说明                                      |
|------------|---------|----------|-------------------------------------------|
| `enabled`  | boolean | `false`  | 是否启用管理 API 服务                     |
| `port`     | integer | `9820`   | 监听 TCP 端口                             |
| `token`    | string  | (必填)   | 认证用共享密钥                            |

当 `enabled` 为 `false` 时，管理 API 不会启动。令牌应为强随机字符串（建议 32 字符以上）。

### 2.2 基础 URL

所有端点相对于以下基础路径：

```
http://<host>:<port>/api/v1
```

示例：`http://localhost:9820/api/v1/status`

---

## 3. 认证

每个请求必须携带有效令牌。支持两种方式：

### 3.1 Bearer 令牌（推荐）

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

示例：

```bash
curl -H "Authorization: Bearer mgmt-secret" http://localhost:9820/api/v1/status
```

### 3.2 查询参数

```
GET /api/v1/status?token=mgmt-secret
```

> **注意：** 查询参数认证适用于难以设置请求头的环境。出于安全考虑，建议使用 Bearer 令牌（URL 中的令牌可能被记录到日志）。

### 3.3 未授权响应

若令牌缺失或无效：

- **HTTP 状态：** `401 Unauthorized`
- **响应体：**

```json
{
  "ok": false,
  "error": "unauthorized: missing or invalid token"
}
```

---

## 4. 响应格式

### 4.1 成功

```json
{
  "ok": true,
  "data": { ... }
}
```

### 4.2 错误

```json
{
  "ok": false,
  "error": "human-readable error message"
}
```

### 4.3 HTTP 状态码

| 状态码 | 含义                                      |
|--------|-------------------------------------------|
| 200    | 成功                                      |
| 400    | 请求错误（无效请求体、缺少参数）          |
| 401    | 未授权（缺少/无效令牌）                   |
| 404    | 资源未找到（项目、会话等）                |
| 405    | 方法不允许                                |
| 500    | 服务器内部错误                            |

---

## 5. 端点参考

### 5.1 系统

#### GET /api/v1/status

返回系统状态与摘要信息。

**响应：**

```json
{
  "ok": true,
  "data": {
    "version": "v1.2.0",
    "uptime_seconds": 3600,
    "connected_platforms": ["feishu", "telegram"],
    "projects_count": 2,
    "bridge_adapters": [
      {
        "platform": "custom",
        "project": "my-backend",
        "capabilities": ["text", "images"]
      }
    ]
  }
}
```

| 字段                   | 类型     | 说明                                      |
|------------------------|----------|-------------------------------------------|
| `version`               | string   | cc-connect 版本（如 `v1.2.0`）            |
| `uptime_seconds`       | number   | 进程运行时长（秒）                        |
| `connected_platforms`  | string[] | 当前已连接的平台类型                      |
| `projects_count`       | number   | 已配置项目数量                            |
| `bridge_adapters`      | array    | 通过 Bridge WebSocket 连接的外部适配器    |

---

#### POST /api/v1/restart

触发优雅重启。进程将正常退出并重新 exec 自身。若适用，可能向发起重启的会话发送「重启成功」消息。

**请求体（可选）：**

```json
{
  "session_key": "telegram:123:456",
  "platform": "telegram"
}
```

若提供，新进程启动后将向指定会话发送重启通知。

**响应：**

```json
{
  "ok": true,
  "data": {
    "message": "restart initiated"
  }
}
```

---

#### POST /api/v1/reload

从磁盘重新加载配置，无需重启进程。可添加新项目；已移除的项目将被停止。项目配置变更将生效。

**响应：**

```json
{
  "ok": true,
  "data": {
    "message": "config reloaded",
    "projects_added": ["new-project"],
    "projects_removed": [],
    "projects_updated": ["my-backend"]
  }
}
```

---

#### GET /api/v1/config

返回当前配置，敏感信息已脱敏。适用于调试和 UI 展示。

**查询参数：** 无

**响应：**

```json
{
  "ok": true,
  "data": {
    "data_dir": "/home/user/.cc-connect",
    "language": "en",
    "projects": [
      {
        "name": "my-backend",
        "agent": {
          "type": "claudecode",
          "providers": [
            {
              "name": "anthropic",
              "api_key": "***",
              "base_url": "",
              "model": "claude-sonnet-4-20250514"
            }
          ]
        },
        "platforms": [
          {
            "type": "feishu",
            "options": {
              "app_id": "***",
              "app_secret": "***"
            }
          }
        ]
      }
    ]
  }
}
```

敏感信息（如 `api_key`、`token`、`app_secret`、`client_secret`）将被替换为 `"***"`。

---

#### GET /api/v1/logs

返回近期日志条目。

**查询参数：**

| 参数     | 类型   | 默认值  | 说明                                          |
|----------|--------|---------|-----------------------------------------------|
| `level`  | string | `info`  | 最低级别：`debug`、`info`、`warn`、`error`    |
| `limit`  | int    | `100`   | 返回条目上限（1–1000）                        |

**响应：**

```json
{
  "ok": true,
  "data": {
    "entries": [
      {
        "time": "2026-03-10T10:30:00Z",
        "level": "info",
        "message": "api server started",
        "attrs": {"socket": "/home/user/.cc-connect/run/api.sock"}
      }
    ]
  }
}
```

---

### 5.2 项目

#### GET /api/v1/projects

列出所有项目及摘要信息。

**响应：**

```json
{
  "ok": true,
  "data": {
    "projects": [
      {
        "name": "my-backend",
        "agent_type": "claudecode",
        "platforms": ["feishu", "telegram"],
        "sessions_count": 3,
        "heartbeat_enabled": true
      }
    ]
  }
}
```

---

#### GET /api/v1/projects/{name}

返回单个项目的详细信息。

**路径参数：**

| 参数   | 类型   | 说明        |
|--------|--------|-------------|
| `name` | string | 项目名称    |

**响应：**

```json
{
  "ok": true,
  "data": {
    "name": "my-backend",
    "agent_type": "claudecode",
    "platforms": [
      {
        "type": "feishu",
        "connected": true
      },
      {
        "type": "telegram",
        "connected": true
      }
    ],
    "sessions_count": 3,
    "active_session_keys": ["telegram:123:456", "feishu:ou_xxx:chat_xxx"],
    "heartbeat": {
      "enabled": true,
      "paused": false,
      "interval_mins": 30,
      "session_key": "telegram:123:456"
    },
    "settings": {
      "quiet": false,
      "admin_from": "user1,user2",
      "language": "en",
      "disabled_commands": ["restart", "upgrade"]
    }
  }
}
```

**错误（404）：**

```json
{
  "ok": false,
  "error": "project not found: my-backend"
}
```

---

#### PATCH /api/v1/projects/{name}

更新项目设置。仅更新提供的字段。

**请求体：**

```json
{
  "quiet": true,
  "admin_from": "user1,user2,user3",
  "language": "zh",
  "disabled_commands": ["restart", "upgrade", "cron"]
}
```

| 字段                 | 类型     | 说明                                                      |
|----------------------|----------|-----------------------------------------------------------|
| `quiet`              | boolean  | 是否隐藏思考过程/工具进度消息                             |
| `admin_from`         | string   | 特权命令用户 ID 列表（逗号分隔）；`"*"` 表示全部用户      |
| `language`           | string   | 界面语言：`en`、`zh`、`zh-TW`、`ja`、`es`                 |
| `disabled_commands`  | string[] | 要禁用的命令（如 `restart`、`upgrade`、`cron`）           |

**响应：**

```json
{
  "ok": true,
  "data": {
    "name": "my-backend",
    "settings": {
      "quiet": true,
      "admin_from": "user1,user2,user3",
      "language": "zh",
      "disabled_commands": ["restart", "upgrade", "cron"]
    }
  }
}
```

---

### 5.3 会话

会话是项目内的对话上下文。会话由 `session_key`（格式：`platform:chatId:userId`）标识，命名会话还可通过内部 `id` 标识（例如 `/new work` 会创建命名会话）。

#### GET /api/v1/projects/{name}/sessions

列出项目的会话列表。

**响应：**

```json
{
  "ok": true,
  "data": {
    "sessions": [
      {
        "id": "sess_abc123",
        "session_key": "telegram:123:456",
        "name": "work",
        "platform": "telegram",
        "active": true,
        "created_at": "2026-03-10T09:00:00Z",
        "updated_at": "2026-03-10T10:30:00Z",
        "history_count": 12
      }
    ]
  }
}
```

---

#### POST /api/v1/projects/{name}/sessions

创建新会话。

**请求体：**

```json
{
  "session_key": "telegram:123:456",
  "name": "work"
}
```

| 字段          | 类型   | 必填 | 说明                                      |
|---------------|--------|------|-------------------------------------------|
| `session_key` | string | 是   | 平台路由键（如 `telegram:123:456`）       |
| `name`        | string | 否   | 人类可读的会话名称                        |

**响应：**

```json
{
  "ok": true,
  "data": {
    "id": "sess_xyz789",
    "session_key": "telegram:123:456",
    "name": "work",
    "created_at": "2026-03-10T10:35:00Z"
  }
}
```

---

#### GET /api/v1/projects/{name}/sessions/{id}

返回会话详情，包含消息历史。

**路径参数：**

| 参数   | 类型   | 说明                          |
|--------|--------|-------------------------------|
| `name` | string | 项目名称                      |
| `id`   | string | 会话 ID 或 session_key        |

**查询参数：**

| 参数             | 类型 | 默认值 | 说明                    |
|------------------|------|--------|-------------------------|
| `history_limit`  | int  | 50     | 返回的历史条目上限      |

**响应：**

```json
{
  "ok": true,
  "data": {
    "id": "sess_abc123",
    "session_key": "telegram:123:456",
    "name": "work",
    "platform": "telegram",
    "active": true,
    "agent_session_id": "as_xxx",
    "created_at": "2026-03-10T09:00:00Z",
    "updated_at": "2026-03-10T10:30:00Z",
    "history": [
      {
        "role": "user",
        "content": "Hello",
        "timestamp": "2026-03-10T09:00:05Z"
      },
      {
        "role": "assistant",
        "content": "Hi! How can I help?",
        "timestamp": "2026-03-10T09:00:10Z"
      }
    ]
  }
}
```

---

#### DELETE /api/v1/projects/{name}/sessions/{id}

删除会话及其历史记录。

**响应：**

```json
{
  "ok": true,
  "data": {
    "message": "session deleted"
  }
}
```

---

#### POST /api/v1/projects/{name}/sessions/switch

切换指定 session_key 的活跃会话（例如用户有多个命名会话时）。

**请求体：**

```json
{
  "session_key": "telegram:123:456",
  "session_id": "sess_xyz789"
}
```

| 字段          | 类型   | 必填 | 说明                    |
|---------------|--------|------|-------------------------|
| `session_key` | string | 是   | 平台路由键              |
| `session_id`  | string | 是   | 要设为活跃的会话 ID     |

**响应：**

```json
{
  "ok": true,
  "data": {
    "message": "active session switched",
    "active_session_id": "sess_xyz789"
  }
}
```

---

#### POST /api/v1/projects/{name}/send

向会话发送消息。消息会像用户通过平台发送一样传递给 Agent。

**请求体：**

```json
{
  "session_key": "telegram:123:456",
  "message": "Review the latest commit"
}
```

| 字段          | 类型   | 必填 | 说明                    |
|---------------|--------|------|-------------------------|
| `session_key` | string | 是   | 平台路由键              |
| `message`     | string | 是   | 发送给 Agent 的文本     |

**响应：**

```json
{
  "ok": true,
  "data": {
    "message": "message sent"
  }
}
```

---

### 5.4 提供商

提供商是 API 后端（如 Anthropic、OpenAI、自定义端点），为项目的 Agent 提供 AI 模型。

#### GET /api/v1/projects/{name}/providers

列出提供商及其活跃状态。

**响应：**

```json
{
  "ok": true,
  "data": {
    "providers": [
      {
        "name": "anthropic",
        "active": true,
        "model": "claude-sonnet-4-20250514",
        "base_url": ""
      },
      {
        "name": "relay",
        "active": false,
        "model": "claude-sonnet-4-20250514",
        "base_url": "https://api.relay.example.com"
      }
    ],
    "active_provider": "anthropic"
  }
}
```

---

#### POST /api/v1/projects/{name}/providers

添加新提供商。

**请求体：**

```json
{
  "name": "relay",
  "api_key": "sk-xxx",
  "base_url": "https://api.relay.example.com",
  "model": "claude-sonnet-4-20250514",
  "thinking": "disabled",
  "env": {
    "CLAUDE_CODE_USE_BEDROCK": "1",
    "AWS_PROFILE": "bedrock"
  }
}
```

| 字段        | 类型           | 必填 | 说明                                          |
|-------------|----------------|------|-----------------------------------------------|
| `name`      | string         | 是   | 提供商标识符                                  |
| `api_key`   | string         | 否*  | API 密钥（*未提供 `env` 时为必填）            |
| `base_url`  | string         | 否   | 自定义 API 端点                               |
| `model`     | string         | 否   | 模型覆盖                                      |
| `thinking`  | string         | 否   | `"disabled"` 表示提供商不支持自适应思考      |
| `env`       | object (k/v)   | 否   | 额外环境变量                                  |

**响应：**

```json
{
  "ok": true,
  "data": {
    "name": "relay",
    "message": "provider added"
  }
}
```

---

#### DELETE /api/v1/projects/{name}/providers/{provider}

移除提供商。无法移除当前活跃的提供商，需先切换。

**响应：**

```json
{
  "ok": true,
  "data": {
    "message": "provider removed"
  }
}
```

**错误（400）：**

```json
{
  "ok": false,
  "error": "cannot remove active provider; switch to another first"
}
```

---

#### POST /api/v1/projects/{name}/providers/{provider}/activate

切换活跃提供商。

**响应：**

```json
{
  "ok": true,
  "data": {
    "active_provider": "relay",
    "message": "provider activated"
  }
}
```

---

#### GET /api/v1/projects/{name}/models

列出项目 Agent 类型可用的模型。

**响应：**

```json
{
  "ok": true,
  "data": {
    "models": [
      "claude-sonnet-4-20250514",
      "claude-3-5-sonnet-20241022",
      "claude-3-opus-20240229"
    ],
    "current": "claude-sonnet-4-20250514"
  }
}
```

---

#### POST /api/v1/projects/{name}/model

设置项目使用的模型。

**请求体：**

```json
{
  "model": "claude-3-5-sonnet-20241022"
}
```

**响应：**

```json
{
  "ok": true,
  "data": {
    "model": "claude-3-5-sonnet-20241022",
    "message": "model updated"
  }
}
```

---

### 5.5 定时任务

#### GET /api/v1/cron

列出所有定时任务，可按项目筛选。

**查询参数：**

| 参数      | 类型   | 说明        |
|-----------|--------|-------------|
| `project` | string | 按项目筛选  |

**响应：**

```json
{
  "ok": true,
  "data": {
    "jobs": [
      {
        "id": "cron_abc123",
        "project": "my-backend",
        "session_key": "telegram:123:456",
        "cron_expr": "0 6 * * *",
        "prompt": "Summarize GitHub trending",
        "exec": "",
        "work_dir": "",
        "description": "Daily GitHub Trending",
        "enabled": true,
        "silent": true,
        "created_at": "2026-03-10T08:00:00Z",
        "last_run": "2026-03-10T06:00:00Z",
        "last_error": ""
      }
    ]
  }
}
```

---

#### POST /api/v1/cron

添加定时任务。必须提供 `prompt` 或 `exec` 之一，不可同时提供。

**请求体（prompt 任务）：**

```json
{
  "project": "my-backend",
  "session_key": "telegram:123:456",
  "cron_expr": "0 6 * * *",
  "prompt": "Summarize GitHub trending",
  "description": "Daily GitHub Trending",
  "silent": true
}
```

**请求体（exec 任务）：**

```json
{
  "project": "my-backend",
  "session_key": "telegram:123:456",
  "cron_expr": "0 9 * * 1",
  "exec": "npm run weekly-report",
  "work_dir": "/path/to/project",
  "description": "Weekly Report",
  "silent": false
}
```

| 字段          | 类型    | 必填 | 说明                                        |
|---------------|---------|------|---------------------------------------------|
| `project`     | string  | 否*  | 项目名称（*多项目时为必填）                 |
| `session_key` | string  | 是   | prompt 任务的目标会话                       |
| `cron_expr`   | string  | 是   | Cron 表达式（5 或 6 个字段）                |
| `prompt`      | string  | 否*  | 要发送的 prompt（*未提供 `exec` 时为必填）  |
| `exec`        | string  | 否*  | Shell 命令（*未提供 `prompt` 时为必填）     |
| `work_dir`    | string  | 否   | exec 的工作目录                             |
| `description` | string  | 否   | 人类可读的标签                              |
| `silent`      | boolean | 否   | 是否隐藏启动通知                            |
| `session_mode` | string | 否   | `reuse`（默认）或 `new_per_run`：每次运行新建 agent 会话 |
| `timeout_mins` | int    | 否   | 单次调度最长等待：省略=30 分钟，`0`=不限制 |

**响应：**

```json
{
  "ok": true,
  "data": {
    "id": "cron_xyz789",
    "project": "my-backend",
    "session_key": "telegram:123:456",
    "cron_expr": "0 6 * * *",
    "prompt": "Summarize GitHub trending",
    "description": "Daily GitHub Trending",
    "enabled": true,
    "created_at": "2026-03-10T10:40:00Z"
  }
}
```

---

#### DELETE /api/v1/cron/{id}

删除定时任务。

**响应：**

```json
{
  "ok": true,
  "data": {
    "message": "cron job deleted"
  }
}
```

---

### 5.6 心跳

心跳在会话中定期执行 prompt（如「检查收件箱」），使 Agent 持续感知环境状态。

#### GET /api/v1/projects/{name}/heartbeat

返回心跳状态。

**响应：**

```json
{
  "ok": true,
  "data": {
    "enabled": true,
    "paused": false,
    "interval_mins": 30,
    "only_when_idle": true,
    "session_key": "telegram:123:456",
    "silent": true,
    "run_count": 42,
    "error_count": 0,
    "skipped_busy": 5,
    "last_run": "2026-03-10T10:00:00Z",
    "last_error": ""
  }
}
```

---

#### POST /api/v1/projects/{name}/heartbeat/pause

暂停心跳。

**响应：**

```json
{
  "ok": true,
  "data": {
    "message": "heartbeat paused"
  }
}
```

---

#### POST /api/v1/projects/{name}/heartbeat/resume

恢复心跳。

**响应：**

```json
{
  "ok": true,
  "data": {
    "message": "heartbeat resumed"
  }
}
```

---

#### POST /api/v1/projects/{name}/heartbeat/run

立即触发一次心跳（单次执行）。

**响应：**

```json
{
  "ok": true,
  "data": {
    "message": "heartbeat triggered"
  }
}
```

---

#### POST /api/v1/projects/{name}/heartbeat/interval

设置心跳间隔。

**请求体：**

```json
{
  "minutes": 15
}
```

**响应：**

```json
{
  "ok": true,
  "data": {
    "interval_mins": 15,
    "message": "interval updated"
  }
}
```

---

### 5.7 Bridge

#### GET /api/v1/bridge/adapters

列出已连接的 Bridge 适配器（通过 WebSocket 连接的外部平台）。

**响应：**

```json
{
  "ok": true,
  "data": {
    "adapters": [
      {
        "platform": "custom",
        "project": "my-backend",
        "capabilities": ["text", "images", "files"],
        "connected_at": "2026-03-10T09:00:00Z"
      }
    ]
  }
}
```

---

## 6. 错误处理约定

### 6.1 标准错误响应

所有错误使用相同封装格式：

```json
{
  "ok": false,
  "error": "human-readable message"
}
```

### 6.2 常见错误

| HTTP | 错误消息示例                                  | 原因                          |
|------|-----------------------------------------------|-------------------------------|
| 400  | `"project is required (multiple projects)"`   | 缺少必填参数                  |
| 400  | `"either prompt or exec is required"`         | 定时任务请求体无效            |
| 401  | `"unauthorized: missing or invalid token"`    | 认证失败                      |
| 404  | `"project not found: xyz"`                    | 未知项目/会话/定时任务       |
| 404  | `"session not found"`                         | 未知会话 ID                   |
| 405  | `"method not allowed"`                       | HTTP 方法错误                 |
| 500  | `"internal error"`                           | 服务器意外错误                |

### 6.3 校验错误

当请求体验证失败时：

```json
{
  "ok": false,
  "error": "invalid request: session_key is required"
}
```

---

## 7. Session Key 格式

`session_key` 是用于将消息路由到正确平台和会话的复合标识符：

```
<platform>:<chat_id>:<user_id>
```

示例：

- `telegram:123456789:123456789` — Telegram 用户 123456789，会话 123456789
- `feishu:ou_xxx:chat_yyy` — 飞书用户与会话
- `slack:C01234:U05678` — Slack 频道与用户
- `discord:123456789:987654321` — Discord 服务器与用户

多工作区模式下，格式可能包含工作区前缀：

```
<workspace>:<platform>:<chat_id>:<user_id>
```

---

## 8. CORS

当管理 API 被 Web 控制台调用时，CORS 头应可配置。建议的配置扩展：

```toml
[management]
enabled = true
port = 9820
token = "mgmt-secret"
cors_origins = ["http://localhost:3000", "https://dashboard.example.com"]
```

若未配置，CORS 可能被禁用或使用默认值（例如仅同源时为 `*`）。

---

## 9. 更新日志

| 版本       | 日期       | 变更                    |
|------------|------------|-------------------------|
| 1.0-draft  | 2026-03-10 | 初始规范                |

---

## 10. 参考

- [Bridge 协议](bridge-protocol.md) — 外部平台适配器的 WebSocket 协议
- [使用指南](usage.md) — 终端用户功能与斜杠命令
- [config.example.toml](../config.example.toml) — 配置模板