# API 参考

所有 REST 端点前缀 `/api/v1/`。所有响应遵循同一个信封格式：

```json
{
  "code": 200,
  "message": "success",
  "data": { }
}
```

除了 `/api/v1/auth/login`，所有端点都需要 `Authorization` header 里带 JWT：

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

深入的行为细节去读对应的功能页——[聊天与消息](./chat)、[Agent 引擎](./agents)、[工具系统](./tools)、[安全与审批](./security)、[LLM Wiki](./wiki)、[多模态创作](./multimodal)、[记忆系统](./memory)、[多渠道接入](./channels)、[模型配置](./models)、[工作空间](./workspaces)、[目标](./goals)、[Doctor](./doctor)。

---

## 认证

```
POST /api/v1/auth/login        # 登录，获取 JWT
GET  /api/v1/users/me          # 获取当前用户
PUT  /api/v1/users/me          # 更新个人资料
PUT  /api/v1/users/me/password # 修改密码
```

**登录示例：**

```bash
curl -X POST http://localhost:18088/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123"}'
```

响应：

```json
{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiJ9...",
    "tokenType": "Bearer",
    "expiresIn": 86400
  }
}
```

---

## 聊天

```
POST /api/v1/chat/{agentId}/message              # 发送消息
GET  /api/v1/chat/{agentId}/stream?conversationId=  # SSE 流式
POST /api/v1/chat/{conversationId}/stop          # 停止进行中的流
GET  /api/v1/chat/{conversationId}/pending-approvals  # 列出等待的审批
```

**发送消息：**

```bash
curl -X POST http://localhost:18088/api/v1/chat/1/message \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"你好，你能做什么？", "conversationId":"conv-abc123"}'
```

**SSE 流式示例：**

```bash
curl -N http://localhost:18088/api/v1/chat/1/stream?conversationId=conv-abc123 \
  -H "Authorization: Bearer YOUR_TOKEN"
```

事件类型和 schema 在 [聊天与消息](./chat) 里。

### 会话

```
GET    /api/v1/conversations                       # 列表（?page&size&agentId）
GET    /api/v1/conversations/page?page=&size=&keyword=  # 分页会话（带关键词搜索）
GET    /api/v1/conversations/{id}/messages         # 取消息
PUT    /api/v1/conversations/{id}/model            # 设置该会话使用的模型
DELETE /api/v1/conversations/{id}                  # 删除
DELETE /api/v1/conversations/{id}/messages         # 清空消息
GET    /api/v1/conversations/{id}/status           # 会话状态
```

---

## Agent

```
GET    /api/v1/agents                # 列表（分页）
GET    /api/v1/agents/{id}            # 获取
POST   /api/v1/agents                 # 创建
PUT    /api/v1/agents/{id}            # 更新（部分）
DELETE /api/v1/agents/{id}            # 软删除

GET    /api/v1/agents/{id}/chat/stream?message=...&conversationId=...  # 流式对话

GET    /api/v1/agents/{id}/workspace/files                    # 列文件
GET    /api/v1/agents/{id}/workspace/files/{filename}         # 取内容
PUT    /api/v1/agents/{id}/workspace/files/{filename}         # 写入
DELETE /api/v1/agents/{id}/workspace/files/{filename}         # 删除
GET    /api/v1/agents/{id}/workspace/prompt-files             # 哪些文件被注入
PUT    /api/v1/agents/{id}/workspace/prompt-files             # 设置注入的文件列表

GET    /api/v1/agents/{agentId}/workspace/memory/export           # 导出记忆快照
POST   /api/v1/agents/{agentId}/workspace/memory/import/preview   # 预览导入（不落库）
POST   /api/v1/agents/{agentId}/workspace/memory/import           # 导入记忆快照

GET    /api/v1/agents/templates        # 列出模板
POST   /api/v1/agents/templates/{id}   # 从模板创建
```

### 字段：`primaryKbId`（1.5.0+）

每个员工可以指定一个**主知识库**作为 wiki 工具的默认目标。字段类型 `string | null`（雪花 ID，前端始终按字符串处理）。

`PUT /api/v1/agents/{id}` 的语义是**三态**的：

| 请求体里 | 行为 |
|---------|------|
| 不带 `primaryKbId` 这个字段 | 保留原值，不动 |
| `"primaryKbId": "<kbId>"` | 设为指定 KB |
| `"primaryKbId": null` | 清空（之后 wiki 工具按 workspace 默认 KB 回退） |

服务端用 `body.containsKey("primaryKbId")` 区分"字段缺失"和"显式 null"，entity 上配 `@TableField(updateStrategy = FieldStrategy.ALWAYS)` 保证 null 真的写到数据库（不会被 MyBatis-Plus 默认 `NOT_NULL` 策略静默跳过）。

设计语义：**KB 是工作空间共享的，`primaryKbId` 只决定该员工 wiki 工具的默认目标，不改变 KB 的归属或可见性。** 多个员工可以选同一个 KB 作主库，互不影响。

请求示例：

```bash
# 设为某个 KB
curl -X PUT http://localhost:18088/api/v1/agents/2055639185675730946 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: 1" \
  -H "Content-Type: application/json" \
  -d '{"primaryKbId": "2054907618529591298", ...其余字段}'

# 清空绑定
curl -X PUT http://localhost:18088/api/v1/agents/2055639185675730946 \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Workspace-Id: 1" \
  -H "Content-Type: application/json" \
  -d '{"primaryKbId": null, ...其余字段}'
```

---

## 工具

```
GET    /api/v1/tools                               # 列表
PUT    /api/v1/tools/{id}                          # 更新
PUT    /api/v1/tools/{id}/toggle?enabled={bool}    # 开关
PUT    /api/v1/tools/{id}/disclosure-tier          # 设置披露层级（core / extension）
POST   /api/v1/tools/{name}/test                   # 直接测试
```

---

## 技能

```
GET    /api/v1/skills                                 # 列表（?type=builtin|custom|mcp&tag=...）
GET    /api/v1/skills/{id}                            # 获取
POST   /api/v1/skills                                 # 创建
PUT    /api/v1/skills/{id}                            # 更新
DELETE /api/v1/skills/{id}                            # 删除
PUT    /api/v1/skills/{id}/toggle?enabled={bool}      # 开关
GET    /api/v1/skills/runtime/active                  # 当前活跃的技能
GET    /api/v1/skills/runtime/status                  # 运行时状态
POST   /api/v1/skills/runtime/refresh                 # 重载运行时
```

---

## MCP 服务

```
GET    /api/v1/mcp/servers                             # 列表
GET    /api/v1/mcp/servers/{id}                         # 获取
POST   /api/v1/mcp/servers                              # 创建
PUT    /api/v1/mcp/servers/{id}                         # 更新（PATCH 语义）
DELETE /api/v1/mcp/servers/{id}                         # 删除
PUT    /api/v1/mcp/servers/{id}/toggle?enabled={bool}   # 开关
POST   /api/v1/mcp/servers/{id}/test                    # 测试连接
POST   /api/v1/mcp/servers/refresh                      # 刷新所有
```

请求体 schema 见 [MCP 协议](./mcp)。

---

## LLM Wiki

```
GET    /api/v1/wiki/kbs                                  # 列知识库
POST   /api/v1/wiki/kbs                                  # 创建 KB
GET    /api/v1/wiki/kbs/{id}                             # 获取 KB 详情
PUT    /api/v1/wiki/kbs/{id}                             # 更新 KB
DELETE /api/v1/wiki/kbs/{id}                             # 删除 KB

POST   /api/v1/wiki/kbs/{kbId}/raw                       # 上传原始材料
GET    /api/v1/wiki/kbs/{kbId}/raw                       # 列原始材料
DELETE /api/v1/wiki/raw/{id}                             # 删除原始材料
POST   /api/v1/wiki/raw/{id}/reprocess                   # 重新消化

GET    /api/v1/wiki/kbs/{kbId}/pages                     # 列页面
GET    /api/v1/wiki/pages/{id}                           # 获取页面
PUT    /api/v1/wiki/pages/{id}                           # 编辑页面
DELETE /api/v1/wiki/pages/{id}                           # 删除页面
POST   /api/v1/wiki/pages/{id}/lock                      # 锁定页面
POST   /api/v1/wiki/pages/{id}/unlock                    # 解锁

GET    /api/v1/wiki/kbs/{kbId}/search?q=...              # 全文搜索
GET    /api/v1/wiki/pages/{id}/backlinks                 # 反向链接
```

Agent 可调的 wiki 工具（`wiki_search`、`wiki_read`、`wiki_backlinks`）自动解析 `kbId`。

### 员工绑定主知识库（1.5.0+）

PR #237 / V130 迁移引入了员工的"主知识库"机制。新的端点：

```
GET /api/v1/wiki/knowledge-bases/bindable      # 列当前 workspace 可绑定为主库的 KB
```

返回的是当前 workspace 的**全部** KB（包含已被其他员工选作主库的），因为绑定语义是"我默认查哪一个"——不是独占。返回 shape 跟 `GET /api/v1/wiki/knowledge-bases`（按 workspace 列出）一致，单独命名只是为了在 UI 语义上更清晰。

绑定动作本身**不走** wiki 接口，而是写在员工实体上：

```
PUT /api/v1/agents/{id}    # body 里带 primaryKbId 字段
```

字段语义、三态行为见上面 [Agent 段的 `primaryKbId` 说明](#字段-primarykbid150)。

::: warning 旧字段 `kb.agentId` 的去留
1.5.0 之前的版本曾把绑定关系写在 `mate_wiki_knowledge_base.agent_id` 上（一对一独占）。V130 迁移把旧值回填到了 `agent.primary_kb_id`，老字段保留作 fallback 读取——**`PUT /api/v1/wiki/knowledge-bases/{id}` 不再处理 `agentId` 字段**，传上去会被忽略。新代码请只通过 `agent.primaryKbId` 控制绑定。
:::

---

## 多模态

```
POST /api/v1/image/generate              # 生成图像
POST /api/v1/image/edit                  # 编辑图像
POST /api/v1/video/generate              # 生成视频
POST /api/v1/video/from-image            # 图生视频
POST /api/v1/music/generate              # 生成音乐
POST /api/v1/tts/synthesize              # 文本转语音
POST /api/v1/stt/transcribe              # 语音转文本

GET  /api/v1/image/jobs/{id}             # 查异步图像任务状态
GET  /api/v1/video/jobs/{id}             # 查异步视频任务状态
```

见 [多模态创作](./multimodal)。

---

## 记忆

```
POST /api/v1/memory/{agentId}/emergence                        # 手动触发整合
POST /api/v1/memory/{agentId}/summarize/{conversationId}       # 手动触发提取
GET  /api/v1/memory/{agentId}/dreaming/status                  # 上次/下次运行 + 最新 DREAMS.md 条目
```

---

## 安全与审批

### Tool Guard 规则

```
GET    /api/v1/security/guard/config                               # 全局配置
PUT    /api/v1/security/guard/config                               # 更新全局配置
GET    /api/v1/security/guard/rules                                # 列自定义规则
GET    /api/v1/security/guard/rules/builtin                        # 列内置规则
POST   /api/v1/security/guard/rules                                # 创建规则
PUT    /api/v1/security/guard/rules/{id}                           # 更新规则
DELETE /api/v1/security/guard/rules/{id}                           # 删除规则
PUT    /api/v1/security/guard/rules/{id}/toggle?enabled={bool}     # 开关规则
```

### File Guard

```
GET /api/v1/security/guard/config/file-guard   # 获取配置
PUT /api/v1/security/guard/config/file-guard   # 更新配置
```

### 审批

```
GET  /api/v1/approvals?status=pending          # 列 pending 审批
POST /api/v1/approvals/{id}/resolve            # 批准或拒绝
```

请求体：

```json
{ "decision": "approved" }
```

或

```json
{ "decision": "rejected", "notes": "原因" }
```

### 审计日志

```
GET /api/v1/security/audit/logs   # 查询（?toolName, ?decision, ?from, ?to）
GET /api/v1/security/audit/stats  # 统计
GET /api/v1/audit/events          # 完整审计事件查询
```

---

## 模型

```
GET    /api/v1/models                                              # 列出模型
GET    /api/v1/models/enabled                                      # 仅列已启用
GET    /api/v1/models/default                                      # 默认模型
GET    /api/v1/models/active                                       # 活跃模型
PUT    /api/v1/models/active                                       # 设置活跃
POST   /api/v1/models                                              # 创建模型配置
PUT    /api/v1/models/{id}                                         # 更新
DELETE /api/v1/models/{id}                                         # 删除
POST   /api/v1/models/{id}/default                                 # 设为默认

PUT    /api/v1/models/{providerId}/config                          # 更新供应商配置
POST   /api/v1/models/custom-providers                             # 创建自定义供应商
DELETE /api/v1/models/custom-providers/{providerId}                # 删除自定义供应商

POST   /api/v1/models/{providerId}/models                          # 往供应商加模型
DELETE /api/v1/models/{providerId}/models/{modelId}                # 移除模型

POST   /api/v1/models/{providerId}/discover                        # 发现模型
POST   /api/v1/models/{providerId}/discover/apply                  # 应用已发现
POST   /api/v1/models/{providerId}/test-connection                 # 测试供应商连接
POST   /api/v1/models/{providerId}/models/{modelId}/test           # 测试单个模型
```

### 遗留端点

```
GET    /api/v1/model-providers           # 遗留——优先用 /api/v1/models
POST   /api/v1/model-providers
PUT    /api/v1/model-providers/{id}
DELETE /api/v1/model-providers/{id}

GET    /api/v1/model-configs             # 遗留——优先用 /api/v1/models
POST   /api/v1/model-configs
PUT    /api/v1/model-configs/{id}
DELETE /api/v1/model-configs/{id}
```

---

## 渠道

```
GET    /api/v1/channels                                          # 列表
POST   /api/v1/channels                                          # 创建
PUT    /api/v1/channels/{id}                                     # 更新
DELETE /api/v1/channels/{id}                                     # 删除
PUT    /api/v1/channels/{id}/toggle?enabled={bool}               # 开关
GET    /api/v1/channels/status                                   # 每个渠道的连接状态
GET    /api/v1/channels/health                                   # 聚合健康视图

GET    /api/v1/channels/webhook/weixin/qrcode                    # 微信 iLink 二维码
GET    /api/v1/channels/webhook/weixin/qrcode/status             # 扫码状态

POST   /api/v1/channels/qrcode/qq/begin                          # 发起 QQ 扫码绑定
GET    /api/v1/channels/qrcode/qq/status                         # QQ 扫码绑定状态
```

### 渠道 webhook 回调

| 渠道 | 回调 URL |
|------|----------|
| 钉钉 | `POST /api/v1/channels/webhook/dingtalk` |
| 飞书 | `POST /api/v1/channels/webhook/feishu` |
| 企业微信 | `POST /api/v1/channels/webhook/wecom` |
| Telegram | `POST /api/v1/channels/webhook/telegram` |
| Discord | *（Gateway——无 webhook）* |
| QQ | `POST /api/v1/channels/webhook/qq` |
| Slack | `POST /api/v1/channels/webhook/slack` |
| 微信 | `POST /api/v1/channels/webhook/weixin` |

---

## 定时任务

```
GET    /api/v1/cron-jobs                                # 列表
POST   /api/v1/cron-jobs                                # 创建
PUT    /api/v1/cron-jobs/{id}                           # 更新
DELETE /api/v1/cron-jobs/{id}                           # 删除
PUT    /api/v1/cron-jobs/{id}/toggle?enabled={bool}     # 开关
POST   /api/v1/cron-jobs/{id}/run                       # 立即执行
```

---

## 工作流（1.3.0+）

完整字段、step mode、Pebble 语法见 [工作流](./workflow)。

```
GET    /api/v1/workflows                                # 列表
GET    /api/v1/workflows/{id}                           # 获取（含已发布 revision + 草稿）
POST   /api/v1/workflows                                # 新建
PUT    /api/v1/workflows/{id}/draft                     # 保存草稿（graph_json）
POST   /api/v1/workflows/{id}/publish                   # 发布草稿为新 revision
DELETE /api/v1/workflows/{id}                           # 删除

POST   /api/v1/workflows/draft/generate                 # 自然语言生成 graph_json 草稿
POST   /api/v1/workflows/{id}/preview-compile           # 静态检查 + Pebble 校验，不发布

POST   /api/v1/workflows/{id}/runs                      # 起一个 run（异步）
GET    /api/v1/workflows/{id}/runs                      # run 列表
GET    /api/v1/workflows/runs/{runId}                   # run 详情 + 每步 input/output/token/duration
POST   /api/v1/workflows/runs/{runId}/resume            # await_approval 后恢复
POST   /api/v1/workflows/runs/{runId}/cancel            # 取消运行中
```

---

## 触发器（1.3.0+）

6 种 pattern type、事件治理、跨实例一致性见 [触发器](./triggers)。

```
GET    /api/v1/triggers                                 # 列表
GET    /api/v1/triggers/{id}                            # 获取
POST   /api/v1/triggers                                 # 新建
PUT    /api/v1/triggers/{id}                            # 更新
DELETE /api/v1/triggers/{id}                            # 删除
PUT    /api/v1/triggers/{id}/toggle?enabled={bool}      # 开关

POST   /api/v1/triggers/events                          # 通用事件入口（webhook / 桥接外部系统）
                                                         # 立即 ACK 200，异步派发
GET    /api/v1/triggers/{id}/events                     # 该 trigger 的事件历史
```

---

## 目标（1.4.0+）

目标完成评分、自动跟进的行为细节见 [目标](./goals)。

```
POST   /api/v1/goals                                   # 新建目标
GET    /api/v1/goals/{id}                               # 获取目标
PATCH  /api/v1/goals/{id}                               # 更新目标（部分）
GET    /api/v1/goals/{id}/events                        # 该目标的评估事件历史
```

---

## Token 用量

```
GET /api/v1/token-usage?startDate=&endDate=&modelName=&providerId=
```

---

## 系统设置

```
GET /api/v1/settings              # 所有设置
PUT /api/v1/settings              # 更新多个
GET /api/v1/settings/language     # 当前语言
PUT /api/v1/settings/language     # 更新语言
PUT /api/v1/settings/{key}        # 更新单个 key
```

---

## 仪表盘

```
GET /api/v1/dashboard/summary             # 用量汇总卡片
GET /api/v1/dashboard/trends              # 趋势图（?range=7d|30d|90d）
GET /api/v1/dashboard/top-agents          # 最常用 Agent
GET /api/v1/dashboard/top-tools           # 最常用工具
```

---

## 工作空间

```
GET    /api/v1/workspaces                             # 列表
GET    /api/v1/workspaces/{id}                        # 获取
POST   /api/v1/workspaces                             # 创建
PUT    /api/v1/workspaces/{id}                        # 更新
DELETE /api/v1/workspaces/{id}                        # 删除（仅 owner）
GET    /api/v1/workspaces/{id}/access                 # 当前用户访问信息（见下）
```

### 成员与 RBAC（1.4.0+）

`/access` 返回调用者在该工作空间内的有效权限，前端据此渲染路由和菜单：

```json
{
  "memberRole": "editor",
  "isGlobalAdmin": false,
  "effectiveRole": "editor",
  "capabilities": ["workspace.read", "conversation.write", "..."]
}
```

```
GET    /api/v1/workspaces/{id}/members                  # 列成员
POST   /api/v1/workspaces/{id}/members                  # 添加成员
PUT    /api/v1/workspaces/{id}/members/{memberId}       # 更新成员（角色等）
DELETE /api/v1/workspaces/{id}/members/{memberId}       # 移除成员
```

---

## Doctor（健康检查）

```
GET /api/v1/doctor/run          # 运行所有检查
GET /api/v1/doctor/checks       # 缓存的检查结果
```

---

## 错误响应

```json
{
  "code": 400,
  "message": "Validation failed: name is required"
}
```

### 常见状态码

| 状态码 | 含义 |
|--------|------|
| 200 | 成功 |
| 400 | 错误请求 |
| 401 | 未授权 |
| 403 | 禁止 |
| 404 | 未找到 |
| 500 | 服务端错误 |

---

## 分页

列表端点按一致的 shape 返回分页结果：

```json
{
  "code": 200,
  "data": {
    "records": [ ],
    "total": 42,
    "current": 1,
    "size": 20,
    "pages": 3
  }
}
```

| 字段 | 用途 |
|------|------|
| `records` | 当前页的条目数组 |
| `total` | 总条数 |
| `current` | 当前页（从 1 开始） |
| `size` | 每页条数 |
| `pages` | 总页数 |

---

## 下一步

- [快速开始](./quickstart)——让服务器跑起来
- [安全与审批](./security)——JWT + 审批流程
- [聊天与消息](./chat)——SSE 事件格式
- [LLM Wiki](./wiki)——Wiki 端点行为