# 13. API 设计

> **更新日期**: 2026-03-26
> **状态**: ✅ 反映实际已实现的 API 端点

---

## 13.1 Agent 管理 (`/api/agent`)

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/agent/list` | 列出所有 Agent |
| `GET` | `/api/agent/:agentId/info` | 获取 Agent 详情 |
| `POST` | `/api/agent/scaffold` | 创建 Agent 骨架 (AgentScaffold) |
| `POST` | `/api/agent/:agentId/chat` | 与 Agent 对话 (SSE 流式) |
| `POST` | `/api/agent/:agentId/chat/:convId/stop` | 停止正在进行的对话 |

## 13.2 Agent Bootstrap 文件

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/agent/:agentId/bootstrap/:filename` | 获取 Agent Bootstrap 文件 |
| `GET` | `/api/agent/:agentId/files` | 获取 Agent 文件树 |
| `GET` | `/api/agent/:agentId/file/*` | 读取 Agent 任意文件 |

## 13.3 Agent 待办与计划

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/agent/:agentId/todo` | 获取待办清单 |
| `PUT` | `/api/agent/:agentId/todo` | 更新待办清单 |
| `GET` | `/api/agent/:agentId/plan` | 获取任务计划 |
| `PUT` | `/api/agent/:agentId/plan` | 更新任务计划 |
| `GET` | `/api/agent/:agentId/cron` | 获取定时任务 |
| `PUT` | `/api/agent/:agentId/cron` | 更新定时任务 |

## 13.4 任务分发与汇报

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/agent/task/dispatch` | 向目标 Agent 分发任务 (写入 todo.md + plan.md，支持 autoExecute) |
| `POST` | `/api/agent/task/report` | Agent 汇报任务完成 (更新 todo.md + plan.md + 可选 Goal 节点) |
| `POST` | `/api/agent/task/reject` | 拒绝/驳回任务 |
| `POST` | `/api/agent/human-request` | Agent 向人类发起待办请求 |

## 13.5 Agent 对话历史

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/agent/:agentId/conversations` | 列出对话历史 |
| `GET` | `/api/agent/:agentId/conversations/:convId` | 获取对话详情 |
| `GET` | `/api/agent/:agentId/conversations/:convId/sub-logs` | 获取子 Agent 日志 |
| `GET` | `/api/agent/:agentId/conversations/:convId/sub-logs/:logFile` | 读取子日志文件 |
| `DELETE` | `/api/agent/:agentId/conversations/:convId` | 删除对话记录 |

## 13.6 Agent 记忆系统

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/agent/:agentId/memory/cerebellum` | 写入小脑 (固化方案) |
| `POST` | `/api/agent/:agentId/memory/consolidate` | 触发记忆整合 |
| `POST` | `/api/agent/:agentId/memory/daily-report` | 生成日报 |

---

## 13.7 Company 管理 (`/api/company`)

### CRUD

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/company/create` | 创建新公司 (自动初始化目录 + company.json) |
| `GET` | `/api/company/list` | 列出所有公司 |
| `GET` | `/api/company/templates` | 列出所有模板 (读取 _registry.json) |
| `GET` | `/api/company/:companyId` | 获取公司详情 |
| `PUT` | `/api/company/:companyId` | 更新公司信息 |
| `POST` | `/api/company/:companyId/shutdown` | 关停公司 |
| `POST` | `/api/company/:companyId/start` | 启动公司 |
| `GET` | `/api/company/:companyId/status` | 获取公司运行状态 |

### 招聘与 Agent 管理

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/company/:companyId/hire` | 招聘 Agent (模板优先 → Creator+FDE 兜底) |
| `POST` | `/api/company/:companyId/fire` | 解雇 Agent |
| `POST` | `/api/company/:companyId/deposit-template` | 沉淀 Agent 为模板 |
| `GET` | `/api/company/:companyId/agents` | 列出公司所有 Agent |
| `GET` | `/api/company/:companyId/agents/:agentId/skills` | 查看 Agent 技能 |

### 心跳控制

| 方法 | 路径 | 说明 |
|------|------|------|
| `PUT` | `/api/company/:companyId/agents/:agentId/heartbeat` | 更新 Agent 心跳配置 |
| `POST` | `/api/company/:companyId/agents/:agentId/heartbeat/start` | 启动 Agent 心跳 |
| `POST` | `/api/company/:companyId/agents/:agentId/heartbeat/stop` | 停止 Agent 心跳 |

### 公司级 OKR

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/company/:companyId/goals` | 列出公司 OKR |
| `POST` | `/api/company/:companyId/goals` | 创建公司 OKR |
| `GET` | `/api/company/:companyId/goals/:goalId` | 获取 OKR 详情 |
| `PUT` | `/api/company/:companyId/goals/:goalId` | 更新 OKR |
| `POST` | `/api/company/:companyId/goals/:goalId/nodes` | 添加 OKR 节点 |
| `PUT` | `/api/company/:companyId/goals/:goalId/nodes/:nodeId` | 更新 OKR 节点 |
| `GET` | `/api/company/:companyId/goals/:goalId/progress` | 获取 OKR 进度 |

### SOP 流水线

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/company/:companyId/pipelines` | 创建流水线 |
| `GET` | `/api/company/:companyId/pipelines` | 列出流水线 |
| `GET` | `/api/company/:companyId/pipelines/:pipelineId` | 获取流水线详情 |
| `PUT` | `/api/company/:companyId/pipelines/:pipelineId` | 更新流水线 |
| `POST` | `/api/company/:companyId/pipelines/:pipelineId/run` | 运行流水线 |
| `GET` | `/api/company/:companyId/pipelines/runs/list` | 列出流水线运行记录 |
| `GET` | `/api/company/:companyId/pipelines/runs/:runId` | 获取运行详情 |
| `POST` | `/api/company/:companyId/pipelines/runs/:runId/advance` | 推进流水线下一步 |
| `GET` | `/api/company/:companyId/pipelines/runs/:runId/current` | 获取当前步骤 |
| `POST` | `/api/company/:companyId/pipelines/runs/:runId/reject` | 驳回当前步骤 |

### 工作日历

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/company/:companyId/schedule` | 获取日程表 |
| `POST` | `/api/company/:companyId/schedule/slots` | 创建日程槽 |
| `PUT` | `/api/company/:companyId/schedule/slots/:slotId` | 更新日程槽 |
| `DELETE` | `/api/company/:companyId/schedule/slots/:slotId` | 删除日程槽 |

### 运营数据

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/company/:companyId/data/metrics` | 获取运营指标 |
| `GET` | `/api/company/:companyId/data/trending` | 获取趋势数据 |
| `GET` | `/api/company/:companyId/data/attribution` | 获取归因分析 |

---

## 13.8 全局 OKR (`/api/goals`)

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/goals` | 列出所有目标 (返回 _index.json) |
| `POST` | `/api/goals` | 创建新目标 |
| `GET` | `/api/goals/:goalId` | 获取完整 OKR 树 |
| `PUT` | `/api/goals/:goalId` | 更新目标元数据 |
| `POST` | `/api/goals/:goalId/nodes` | 添加节点 |
| `GET` | `/api/goals/:goalId/nodes/:nodeId` | 获取节点详情 |
| `PUT` | `/api/goals/:goalId/nodes/:nodeId` | 更新节点状态 |
| `GET` | `/api/goals/:goalId/progress` | 返回进度统计 |

---

## 13.9 Master Agent 对话 (`/api/master`)

| 方法 | 路径 | 说明 |
|------|------|------|
| `POST` | `/api/master/chat` | 与 Master Agent 对话 (SSE 流式) |
| `POST` | `/api/master/upload` | 上传文件给 Master |
| `GET` | `/api/master/sessions` | 列出 Master 对话会话 |
| `DELETE` | `/api/master/sessions/:id` | 删除 Master 会话 |

---

## 13.10 Innovator 技能管理 (`/api/innovator`)

| 方法 | 路径 | 说明 |
|------|------|------|
| `GET` | `/api/innovator/skills` | 列出所有技能 |
| `GET` | `/api/innovator/skills/:name` | 获取技能详情 |
| `DELETE` | `/api/innovator/skills/:name` | 删除技能 |
| `PATCH` | `/api/innovator/skills/:name` | 更新技能元数据 |
| `POST` | `/api/innovator/skills/:name/rename` | 重命名技能 |
| `GET` | `/api/innovator/skills/:name/evolve-log` | 获取进化日志 |
| `POST` | `/api/innovator/skills/scan` | 扫描技能目录 |
| `POST` | `/api/innovator/skills/:name/retrain` | 触发重训 |
| `GET` | `/api/innovator/skills/:name/artifacts` | 获取技能产物 |
| `GET` | `/api/innovator/jobs/:jobId` | 查询异步任务状态 |
| `GET` | `/api/innovator/conversations` | 列出 Innovator 对话 |

---

## 13.11 实时流

| 端点 | 协议 | 说明 |
|------|------|------|
| `/api/agent/:agentId/chat` | SSE | Agent 对话实时输出流 |
| `/api/master/chat` | SSE | Master Agent 对话实时输出流 |
| WebSocket (claude-chat-ws.js) | WS | Claude Chat 双向实时通道 |