From 01a4e29f845b560fb22f027d9fe8adff48d353b2 Mon Sep 17 00:00:00 2001 From: Aska Date: Sun, 6 Sep 2026 05:32:57 +0800 Subject: [PATCH] =?UTF-8?q?docs(api):=20=E6=96=B0=E5=A2=9E=E7=94=A8?= =?UTF-8?q?=E6=88=B7=E4=BE=A7=E8=B7=A8=E5=B9=B3=E5=8F=B0=E5=AE=A2=E6=88=B7?= =?UTF-8?q?=E7=AB=AF=20API=20=E6=96=87=E6=A1=A3=EF=BC=88=E5=A5=91=E7=BA=A6?= =?UTF-8?q?+=E7=AB=AF=E7=82=B9=E7=99=BB=E8=AE=B0=E8=A1=A8=EF=BC=89?= =?UTF-8?q?=EF=BC=9BAGENTS=20=E7=AB=8B=E3=80=8C=E9=9A=8F=E5=AE=9E=E7=8E=B0?= =?UTF-8?q?=E6=9B=B4=E6=96=B0=20API=20=E6=96=87=E6=A1=A3=E3=80=8D=E9=93=81?= =?UTF-8?q?=E5=BE=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 1 + Docs/api-client.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 59 insertions(+) create mode 100644 Docs/api-client.md diff --git a/AGENTS.md b/AGENTS.md index 3e3d457..9807a6a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,6 +52,7 @@ - 🔴 禁 `interface{}`（用 `any`）、禁包级全局变量（除 `var ErrXxx`）、禁裸 `return err`、禁魔法数字；错误一律 `%w` wrap；SQL 全参数化、表名单数、主键 `id`、时间戳 `created_at/updated_at`、索引 `idx_{table}_{col}`；敏感信息打日志。 - 🔴 **日志必须标来源**：模块/子功能用 `internal/logger.WithSource`/`Scoped`（`source=module/subfeature`）标注，跨模块可追溯定位；**禁止无来源裸日志**。 - 🔴 **客户端 API 契约先行**：REST `/api/v1` + WS `/ws` + admin `/api/v1/admin/*` 统一**版本化契约**，供跨平台客户端（Web/移动/IM bridge）接入与治理；JSON 响应 `{data}` / `{error:{code,message}}`。 +- 🔴 **用户侧 API 文档随实现更新**：每实现/变更一个 REST 端点、WS 事件、admin API，**立即同步更新 `Docs/api-client.md`**（用户侧跨平台客户端 API 文档），供后期原生客户端开发；契约变更版本化。 - 🔴 每阶段完成（或里程碑归档）后：**`git push origin dev`** 同步远端。 - 🔴 **遇到开发文档冲突 / 意义不明 / 规格矛盾时**：**阻塞会话**，用 `AskUserQuestion` 询问主人，**不得自行猜测**；文档清、不冲突则自主推进。 - 🔴 阶段验证：后端 `go build ./...` + `go vet ./...` + `go test ./...` 全绿 + windows/darwin 交叉编译；前端（M9+）`tsc --noEmit` + `vite build` 通过。 diff --git a/Docs/api-client.md b/Docs/api-client.md new file mode 100644 index 0000000..0edd721 --- /dev/null +++ b/Docs/api-client.md @@ -0,0 +1,58 @@ +# Cyrene v2 客户端 API 文档（用户侧） + +> **面向**: Web 前端 / 移动端原生客户端 / IM 桥接等**跨平台客户端开发者**。 +> **维护铁律**: 每实现/变更一个 API（REST 端点、WS 事件、admin API）**立即更新本文件**；契约变更必须版本化，不破坏既有客户端。 +> **状态**: 契约先行（gateway 在 M8 实现，M9 前端按此开发）。当前多数端点为「规划中」，随实现逐条补全请求/响应。 + +--- + +## 0. 基础约定 +- **Base URL**: `http://:8080`（网关唯一对外端口；生产一般经反代/HTTPS）。 +- **版本**: REST 全部挂在 `/api/v1/{resource}`；未来破坏性变更升 v2。 +- **认证**: `Authorization: Bearer `；管理端另支持 `X-API-Key`。 +- **响应统一**: `{"data": ...}` / `{"error": {"code": , "message": }}`；状态码 200/201/204/400/401/403/404/429/500。 +- **错误码**：业务错误带 `code` 字符串（如 `unauthorized` / `not_found`），便于客户端分支。 + +--- + +## 1. REST 端点（公开） + +> 下表为登记表：状态 `✅ 已实现` / `🕐 规划`。实现时补上 URL、方法、请求/响应示例。 + +| # | 端点 | 方法 | 认证 | 状态 | 说明 | +|---|------|------|------|:---:|------| +| — | `/api/v1/auth/login` | POST | 否 | 🕐 | 用户登录 → 返回 JWT | +| — | `/api/v1/sessions` | GET/POST | JWT | 🕐 | 会话列表/创建 | +| — | `/api/v1/chat` | POST | JWT | 🕐 | 发送 chat 消息（返回流或即时回复） | +| — | `/api/v1/personas` | GET | JWT | 🕐 | 人格列表/当前角色 | + +## 2. REST 端点（管理，`/api/v1/admin/*`） + +> 仅供管理面板与授权客户端；RBAC：`owner`/`admin`/`viewer`；全程审计。 + +| # | 端点 | 方法 | 状态 | 说明 | +|---|------|------|:---:|------| +| — | `/api/v1/admin/users` | GET/POST | 🕐 | 用户/角色/API key 管理 | +| — | `/api/v1/admin/personas` | GET/POST/PUT/DELETE | 🕐 | 人格 CRUD | +| — | `/api/v1/admin/channels` | GET/POST | 🕐 | 渠道管理（含身份识别测试） | +| — | `/api/v1/admin/memories` | GET/PUT/DELETE | 🕐 | 记忆管理（检索/编辑/删除） | +| — | `/api/v1/admin/plugins` | GET/POST | 🕐 | 插件/能力/MCP | +| — | `/api/v1/admin/llm` | GET/PUT | 🕐 | LLM 模型/路由/降级配置 | +| — | `/api/v1/admin/automations` | GET/POST | 🕐 | 自动化与提醒 | + +## 3. WebSocket `/ws`（实时） + +**下行（服务端→客户端）**: `stream_chunk` / `stream_end` / `thinking`(思维链) / `mood` / `reminder` / `device_update` / `tool_used`(工具回显) / `subagent_event` / `graph_update`(流程图) / `auth`。 +**上行（客户端→服务端）**: `mode_switch` / `chat` / `voice_input` / `subagent_ask`(子代理上下文查询) / `task_output_query`(后台任务输出查询)。 + +> 完整事件负载 schema 随 M8 实现补充到本文件。 + +--- + +## 4. 客户端接入指引 +- **认证**: 先 `POST /api/v1/auth/login` 取 JWT → WS 握手（子协议/`auth` 消息）注入 token。 +- **版本**: 客户端在 `Accept`/`User-Agent` 或请求头声明 `X-API-Version: 1`。 +- **离线**: PWA / 原生端建议缓存 `sessions`/`personas` 等列表。 + +## 5. 变更记录 +- `v0.1`（契约先行）：建骨架 + 端点登记表；gateway 未实现，随 M8 逐条补全并更新本表。