# 城丰星际 · CFXJ — core-runtime API 规范 v1.5

> core-runtime.exe 通过 HTTP 18989 端口对外提供服务  
> 开源层代码**无任何数据库直连权限**，所有操作必须经过API

---

## 一、公开可免密调用接口（只读查询）

### 系统状态

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/status` | 平台版本、运行时间、端口状态 |
| GET | `/api/agents` | 全部Agent列表与在线状态 |

**示例请求**
```
GET /api/status
```
**示例响应**
```json
{
  "app": {"version": "v1.5.0", "name": "城丰星际 AI 智能助手", "uptime": 3600},
  "services": {"gateway": "online", "task-server": "online"}
}
```

### 任务查询

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/tasks/board` | 任务看板（全部任务状态汇总） |
| GET | `/api/tasks/{task_id}` | 单任务详情 |
| GET | `/api/tasks/{task_id}/timeline` | 任务操作时序流水 |
| GET | `/api/tasks/{task_id}/snapshots` | 任务快照列表 |
| GET | `/api/tasks/preemptable` | 可抢占任务列表 |

**示例响应**
```json
{
  "tasks": [
    {"task_id": "task-abc123", "priority": 2, "assigned_to": "codeman", "status": "in_progress", "effective_hours": 3.5},
    {"task_id": "task-def456", "priority": 1, "assigned_to": "hei", "status": "claimed", "effective_hours": 1.2}
  ]
}
```

**示例请求**
```
GET /api/tasks/board
```
**示例响应**
```json
{
  "summary": {"total": 42, "pending": 3, "in_progress": 8, "completed": 28, "failed": 3},
  "columns": {...}
}
```

### 监控指标

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/metrics/roles` | 分角色CPU/内存资源监控 |
| GET | `/api/alerts` | 系统告警列表 |

### 技能与工具

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/skills` | 技能库列表（公开模板） |
| GET | `/api/logs/recent` | 最近系统日志 |

---

## 二、需授权密钥的写操作接口

以下接口**仅持有官方分发密钥才可调用**，开源代码无内置有效密钥：

| 方法 | 路径 | 密钥要求 | 说明 |
|------|------|---------|------|
| POST | `/api/tasks/create` | X-Core-Key | 创建任务/派发 |
| POST | `/api/tasks/{id}/claim` | X-Core-Key | 认领任务 |
| POST | `/api/tasks/{id}/submit` | X-Core-Key | 提交交付物 |
| POST | `/api/tasks/{id}/accept` | X-Core-Key | 验收通过 |
| POST | `/api/tasks/{id}/reject` | X-Core-Key | 驳回任务 |
| POST | `/api/tasks/{id}/preempt` | X-Core-Key | 抢占调度 |
| POST | `/api/tasks/{id}/escalate` | X-Core-Key | 协助升级 |
| POST | `/api/config` | X-Admin-Key | 修改配置（仅Controller） |

**鉴权方式**：请求头携带 `X-Core-Key: <your_key>`

> **密钥申请**：访问 www.gdcfxj.com 联系商务获取授权密钥。请勿尝试破解或绕过密钥校验，违规行为将被水印溯源并追究法律责任。

---

## 三、角色（role）字段说明

| role值 | 含义 | 权限范围 |
|--------|------|---------|
| core | 主控/调度者 | 全部权限（派发/夺权/验收） |
| exec | 执行者 | 认领/提交/挂起 |
| assist | 协助者 | 只读+建议（不可修改任务状态） |
| monitor | 监控者 | 只读所有监控数据 |
| security | 安全审计 | 权限校验+日志审计 |
| logger | 日志记录 | 仅写入日志，不可读/改任务 |

**注意**：role值由core-runtime内核强制校验，前端传入非法role会被拦截。

---

## 四、错误码

| 状态码 | 含义 |
|--------|------|
| 200 | 成功 |
| 400 | 参数错误 |
| 401 | 未授权（缺少密钥或密钥无效） |
| 403 | 权限不足（role不允许此操作） |
| 404 | 资源不存在 |
| 409 | 冲突（如任务已被认领） |
| 429 | 并发超限 |
| 500 | 内核内部错误 |

---

## 五、重要约束

1. **数据库不可直连**：开源层代码无SQLite/Neo4j连接能力，所有读写必须经过本API
2. **时序防篡改**：`task_timeline` 仅允许INSERT，无法UPDATE/DELETE
3. **角色硬校验**：所有写操作的role字段由内核白名单校验
4. **并发上限**：P0=5, P1=10, P2=20（内核硬编码，不可调整）
5. **密钥管控**：高危接口需`X-Core-Key`，开源层无内置密钥