feat(api): 建立前后端接口契约壳子

2026-08-27 11:37:17 +08:00
parent 08e4aeea0c
commit ce155b27f4
15 changed files with 2005 additions and 38 deletions
@@ -0,0 +1,159 @@
+# 后端接口契约（开发版）
+
+> 本文档记录当前前后端联调使用的接口壳子。业务服务尚未实现，最终字段以 FastAPI 运行时生成的 OpenAPI 为准。
+
+## 契约入口
+
+- Swagger UI：`GET /docs`
+- OpenAPI：`GET /openapi.json`
+- 所有普通接口使用 JSON。
+- Chat 和 Agent 实时事件使用 `text/event-stream`（SSE）。
+- 内部时间统一使用 UTC ISO 8601。
+- ID 使用稳定业务 ID，不使用文件路径代替 ID。
+
+## 接口清单
+
+### System
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| GET | `/health` | Sidecar 健康检查 |
+| GET | `/api/status` | 获取服务名称、版本和环境 |
+
+### Notes 与 Search
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| GET | `/api/notes` | 获取笔记列表 |
+| POST | `/api/notes` | 创建笔记 |
+| GET | `/api/notes/{note_id}` | 获取笔记及 Block |
+| PATCH | `/api/notes/{note_id}` | 更新笔记 |
+| DELETE | `/api/notes/{note_id}` | 删除笔记 |
+| POST | `/api/notes/{note_id}/move` | 移动笔记 |
+| POST | `/api/search` | FTS、Vector 或 Hybrid 检索 |
+
+### Chat、Agent 与 Tool
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| POST | `/api/chat` | 发起聊天并返回 ModelEvent SSE |
+| GET | `/api/agent/runs` | 获取 Agent Run 列表 |
+| POST | `/api/agent/runs` | 创建 Agent Run |
+| GET | `/api/agent/runs/{run_id}` | 获取 Agent Run 状态与 Trace 摘要 |
+| POST | `/api/agent/runs/{run_id}/cancel` | 取消 Agent Run |
+| GET | `/api/agent/runs/{run_id}/events` | 订阅 AgentEvent SSE |
+| POST | `/api/agent/runs/{run_id}/permissions/{request_id}` | 响应 Tool 权限确认 |
+| GET | `/api/tools` | 获取已注册 Tool Definition |
+
+### Skill 与 Plugin
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| GET | `/api/skills` | 获取 Skill 列表及状态 |
+| POST | `/api/skills/install` | 安装 Skill |
+| GET | `/api/skills/{skill_id}` | 获取 Skill Manifest 与状态 |
+| POST | `/api/skills/{skill_id}/enable` | 启用 Skill |
+| POST | `/api/skills/{skill_id}/disable` | 停用 Skill |
+| DELETE | `/api/skills/{skill_id}` | 卸载 Skill |
+| GET | `/api/plugins` | 获取 Plugin 列表及状态 |
+| POST | `/api/plugins/install` | 安装 Plugin |
+| GET | `/api/plugins/{plugin_id}` | 获取 Plugin Manifest 与状态 |
+| POST | `/api/plugins/{plugin_id}/enable` | 启用 Plugin |
+| POST | `/api/plugins/{plugin_id}/disable` | 停用 Plugin |
+| DELETE | `/api/plugins/{plugin_id}` | 卸载 Plugin |
+
+### Provider
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| GET | `/api/providers` | 获取 Provider 配置列表 |
+| POST | `/api/providers` | 新建 Provider 配置 |
+| GET | `/api/providers/{provider_id}` | 获取 Provider 配置 |
+| PATCH | `/api/providers/{provider_id}` | 更新 Provider 配置 |
+| DELETE | `/api/providers/{provider_id}` | 删除 Provider 配置 |
+| GET | `/api/providers/{provider_id}/models` | 获取模型及 Capability 列表 |
+| POST | `/api/providers/test` | 测试 Provider 连接 |
+
+Provider Contract 只传递 `credential_id` 或临时 `credential_context_id`，不通过普通 JSON 接口传递明文 API Key。
+
+### Tasks、Media 与 Index
+
+| 方法 | 路径 | 用途 |
+| --- | --- | --- |
+| GET | `/api/tasks` | 获取任务列表 |
+| POST | `/api/tasks` | 创建任务 |
+| GET | `/api/tasks/{task_id}` | 获取任务 |
+| PATCH | `/api/tasks/{task_id}` | 更新任务 |
+| DELETE | `/api/tasks/{task_id}` | 删除任务 |
+| POST | `/api/media/transcriptions` | 创建音频转写任务 |
+| GET | `/api/media/transcriptions/{job_id}` | 获取转写任务状态 |
+| GET | `/api/index/status` | 获取索引服务状态 |
+| POST | `/api/index/rebuild` | 创建索引重建任务 |
+| GET | `/api/index/jobs/{job_id}` | 获取索引任务状态 |
+
+## 统一错误
+
+所有普通 HTTP 错误统一返回：
+
+```json
+{
+  "error": {
+    "code": "NOT_IMPLEMENTED",
+    "message": "The contract is available, but its business service is not implemented.",
+    "details": {}
+  }
+}
+```
+
+当前接口壳子的写操作主要返回：
+
+- `501 NOT_IMPLEMENTED`：契约已经建立，业务服务尚未接入；
+- `422 VALIDATION_ERROR`：请求字段不符合 Pydantic Contract；
+- `404 RESOURCE_NOT_FOUND`：路由或资源不存在。
+
+前端只根据 `error.code` 判断业务错误，不解析第三方 SDK 的原始异常文本。
+
+## SSE 约定
+
+每条 SSE 包含事件名和对应 JSON Contract：
+
+```text
+event: TextDelta
+data: {"event":"TextDelta","sequence":1,"data":{"text":"..."},"timestamp":"..."}
+```
+
+ModelEvent 类型：
+
+```text
+TextDelta
+ThinkingDelta
+ToolCallStart
+ToolCallDelta
+ToolCallEnd
+Usage
+Error
+Done
+```
+
+AgentEvent 类型：
+
+```text
+RunStarted
+TextDelta
+ThinkingDelta
+ToolCall
+ToolResult
+PermissionRequired
+Usage
+Citation
+RunCompleted
+RunFailed
+RunCancelled
+```
+
+## 当前壳子行为
+
+- 列表、搜索、索引状态等只读接口返回符合 Contract 的空结果或 `idle` 状态。
+- Chat 与 Agent Events 返回符合 SSE 格式的 `NOT_IMPLEMENTED` 事件。
+- 需要数据库、文件、模型或 Runtime 的操作统一返回 `501`。
+- 接入业务模块时保持当前路径和 Contract，不在 Router 中直接实现数据库、Provider 或 Agent 逻辑。