Aska
518bd0a230
批次A admin 端点（原本 404 变 200 真实数据）：
- GET /admin/llm：读 s.cfg.LLM 组 openai+anthropic 两 provider（enabled=当前 Provider、multimodal=配 VisionModel），APIKey 不进 wire 零泄露。
- GET /admin/automations：*automations.Service.List()（reminders+event rules+cron schedules，cron 加只读登记）。
- GET /admin/users：cfg.AdminUser + *auth.APIKey.List()（密钥掩码）；无用户存储，恒先返回当前 admin 账号。
- GET /admin/backthink：*backthink.Backthink.List(ctx,50)。均只读、owner/admin RBAC、{data} 信封。
批次B 视觉真推理 + 语音：
- rest.go chatRequest 加 Image?；流式 publishChatStream 带 image；userChatMessages 构造 ImageMessage(model.go:71)。
- loop/vision.go：ImageResolver 可注入（MVP 先看图再对话）；run.go Run 开头 resolveImages，无 resolver 透传直交主模型。
- vision/resolver.go：MessageResolver 调 vision.Router.Route——KindMain 保留图片交主模型多模态、KindVisionTool/OCRTool 经 dispatcher.Invoke 折叠成 [图片内容] 文本、KindUnsupported 记日志保留原图不崩。
- gateway/voice.go：VoiceService 接口 + SetVoice 注入点 + handleVoiceInput（未注入回 error 不崩）+ runVoiceTurn 异步 STT→loop chat→TTS→定向 voice_output 帧。
- ws_hub/ws_route：voice_input 接 handleVoiceInput；前端 ws.ts decodeBase64/playVoiceAudio/case voice_output。
第3步 wire.go 收口（唯一碰 wire.go 的一步）：
- Deps 补传 Automations:a.automation / Backthink:a.backthink / Users:auth.NewAPIKey(a.cfg.Auth)（*auth.APIKey 原生满足 UserStore，避免 admin 重复的复合类型）。
- gw.SetVoice(a.voice)；loop.Options.Vision = vision.NewMessageResolver(router, info, dispatcher.Invoke)（router=NewRouter(WithVisionTool/WithOCRTool)、info=cfg.LLM.VisionModel）。
实机验证：四 admin 端点 200 真实数据（llm 双 provider 脱敏、users=admin,yeij0942,owner）；WS 握手正常。go build/vet/test 全绿 + 前端 tsc。wire.go 557 行。
78 lines
7.6 KiB
Markdown
78 lines
7.6 KiB
Markdown
# Cyrene v2 客户端 API 文档（用户侧）
|
||
|
||
> **面向**: Web 前端 / 移动端原生客户端 / IM 桥接等**跨平台客户端开发者**。
|
||
> **维护铁律**: 每实现/变更一个 API（REST 端点、WS 事件、admin API）**立即更新本文件**；契约变更必须版本化，不破坏既有客户端。
|
||
> **状态**: gateway 已在 M8 落地核心端点；M9 前端按此开发。**`✅` = 已实现**，`🕐` = 规划。
|
||
|
||
---
|
||
|
||
## 0. 基础约定
|
||
- **Base URL**: `http://<host>:8080`（网关唯一对外端口；生产一般经反代/HTTPS）。
|
||
- **版本**: REST 全部挂在 `/api/v1/{resource}`；未来破坏性变更升 v2。
|
||
- **认证**: `Authorization: Bearer <JWT>`（RBAC：`owner`/`admin`/`viewer`）；管理端另支持 `X-API-Key`。
|
||
- **响应统一**: `{"data": ...}` / `{"error": {"code": <string>, "message": <string>}}`；状态码 200/201/204/400/401/403/404/429/500。
|
||
- **错误码**：业务错误带 `code` 字符串（如 `unauthorized` / `not_found`），便于客户端分支。
|
||
|
||
---
|
||
|
||
## 1. REST 端点（公开）
|
||
|
||
| # | 端点 | 方法 | 认证 | 状态 | 说明 |
|
||
|---|------|------|------|:---:|------|
|
||
| 1 | `/api/v1/auth/login` | POST | 否 | ✅ | `{username,password}` → `{data:{token,jwt}}`（24h，owner） |
|
||
| 2 | `/api/v1/health` | GET | 否 | ✅ | 健康检查 `{data:{status:"ok"}}` |
|
||
| 3 | `/api/v1/chat` | POST | JWT | ✅ | `{text,image?,stream?}` → `{data:{reply}}`；`stream:true` 时经 WS 触发流式。`image` 为 base64 data: URI 或 http(s) URL，入视觉真推理（design/06） |
|
||
| 4 | `/api/v1/sessions` | GET | JWT | ✅ | `{data:[session...]}` |
|
||
| 5 | `/api/v1/personas` | GET | JWT | ✅ | `{data:[persona...]}` |
|
||
|
||
## 2. REST 端点（管理，`/api/v1/admin/*`）
|
||
|
||
> 仅供管理面板与授权客户端；RBAC：`owner`/`admin`/`viewer`（viewer 只读、写 403）；**写操作全程审计**。
|
||
|
||
| # | 端点 | 方法 | 状态 | 说明 |
|
||
|---|------|------|:---:|------|
|
||
| 1 | `/api/v1/admin/personas` | GET | ✅ | 人格列表 |
|
||
| 2 | `/api/v1/admin/sessions` | GET | ✅ | 会话列表 |
|
||
| 3 | `/api/v1/admin/memories` | GET | ✅ | 记忆列表（检索/编辑随 M10 扩展） |
|
||
| 4 | `/api/v1/admin/plugins` | GET | ✅ | 插件/能力列表（含 MCP/渠道） |
|
||
| 5 | `/api/v1/admin/plugins/policy` | POST | ✅ | 写工具策略（owner-only，审计） |
|
||
| 6 | `/api/v1/admin/channels` | GET | ✅ | 渠道列表/健康 |
|
||
| 7 | `/api/v1/admin/iot` | GET | ✅ | IoT 设备列表 |
|
||
| 8 | `/api/v1/admin/users` | GET/POST | ✅(GET) | 用户/角色/API key（GET 已实现；POST 创建用户/签发 key 随 M10 落地） |
|
||
| 9 | `/api/v1/admin/llm` | GET/PUT | ✅(GET) | LLM 模型/路由/降级（GET 已实现，APIKey 脱敏；PUT 热重载 M10） |
|
||
| 10 | `/api/v1/admin/automations` | GET/POST | ✅(GET) | 自动化与提醒（GET 已实现；POST 创建 M10） |
|
||
| 11 | `/api/v1/admin/backthink` | GET | ✅ | 后台思考记录 |
|
||
|
||
> **M10 前端契约补充（管理面板）**：`GET /api/v1/admin/users` · `GET /api/v1/admin/llm` · `GET /api/v1/admin/automations` · `GET /api/v1/admin/backthink` 已实现，返回真实数据；`GET /api/v1/admin/logs` · `GET /api/v1/admin/trace` · `GET /api/v1/admin/audit` · `GET /api/v1/admin/system` 仍🕐未实现（前端按契约封装、后端 404 时显示"待实现"壳，不报错）。写操作（策略/档案/密钥/系统设置/用户与自动化创建）经前端审计登记，待后端 M10+ 落地真实持久化与热重载。
|
||
|
||
## 3. WebSocket `/ws/chat`（实时）
|
||
|
||
- **握手**: `ws://<host>:8080/ws/chat?token=<JWT>` 或 `Authorization: Bearer`；未认证在握手前回 `401` JSON。
|
||
- **下行（服务端→客户端）**: 经 bus 广播 `{type:"<event>", data:..., turnId?, seq?}`（`turnId`/`seq` 为流式关联字段，见 §3.1）——`message.start/delta/end` / `thinking.start/delta/end` / `tool_call.start/delta/end` / `tool_execution.update`（结构化流，design/04 §1.1），以及向后兼容的 `stream_chunk` / `stream_end` / `thinking`(思维链) / `mood` / `reminder` / `device_update` / `tool_used`(工具回显) / `subagent_event` / `graph_update`。语音回复走 `voice_output`（定向回请求连接，非广播）。
|
||
|
||
### 3.1 结构化流事件（`message.*` / `thinking.*` / `tool_call.*` / `tool_execution.*`）
|
||
- **事件壳**：`{type, turnId?, seq?, data}`, `data` 为**类型化结构**（非 `any`）。`seq` 为 hub 级单调递增序号，供客户端将一次突发的流式事件排序关联。
|
||
- **`message.start`**(`{index}`) / **`message.delta`**(`{delta, index}`) / **`message.end`**(`{index}`)：正文段。`delta` 为正文 token 增量；客户端对 `message.delta` 累加到当前消息正文；`message.start/end` 划定正文段边界，**不**结束整轮（结束由 `stream_end` 负责）。
|
||
- **`thinking.start`**(`{index}`) / **`thinking.delta`**(`{delta, index}`) / **`thinking.end`**(`{index}`)：思维链段（前端折叠块）。`thinking.delta` 累加增量。
|
||
- **`tool_call.start`**(`{id, index}`) / **`tool_call.delta`**(`{id, index, delta}`) / **`tool_call.end`**(`{id, index}`)：工具调用中间态；`tool_call.delta` 携带参数增量（如 Anthropic `input_json_delta`）。
|
||
- **`tool_execution.update`**(`{id, index, delta}`)：工具执行进度/局部输出（保留，工具循环 §1.2 后置实现）。
|
||
- **向后兼容**：未映射/无法确定的事件仍走 `stream_chunk` + `stream_end`（非流式回退路径）。
|
||
- **上行（客户端→服务端）**: `mode_switch` / `chat`（跑 loop 并广播流式） / `voice_input` / `subagent_ask` / `task_output_query`。
|
||
- **`voice_input`**（上行，客户端→服务端）：`_{audio?, format?, text?, sessionId?}`。`audio` 为 base64（或 data: URI）音频，`format` 为其编码（`wav`/`mp3`/`ogg`）；`text` 为已转写文本时跳过 STT。服务端走 STT→agent 聊天→TTS（design/06 §1），回复经 `voice_output` 定向回该连接。无注入语音服务时回 `error` 帧（`voice unavailable`）。
|
||
- **`voice_output`**（下行，服务端→客户端）：`{audio, format, text, reply}`。`audio` 为 base64 合成音频，`format` 为其编码，`text` 为识别文本，`reply` 为助手回复文本。
|
||
- **向后兼容**：未映射/无法确定的事件仍走 `stream_chunk` + `stream_end`（非流式回退路径）。
|
||
|
||
---
|
||
|
||
## 4. 客户端接入指引
|
||
- **认证**: 先 `POST /api/v1/auth/login` 取 JWT → WS 握手（`?token=`）注入。
|
||
- **版本**: 客户端请求头声明 `X-API-Version: 1`。
|
||
- **离线**: PWA / 原生端建议缓存 `sessions`/`personas` 列表。
|
||
|
||
## 5. 变更记录
|
||
- `v0.5`（批次B·视觉真推理 + 语音端）：`POST /api/v1/chat` 增 `image` 字段（base64 data: URI 或 URL），入 loop 视觉路由（vision/OCR 工具或主模型多模态，design/06 §0「先看图再对话」）；WS 上行 `voice_input` 接 STT→聊天→TTS 管道，下行新增 `voice_output`（定向回请求连接，含合成音频 + 识别文本 + 回复文本）。
|
||
- `v0.4`（结构化流）：WS 下行新增 `message.*` / `thinking.*` / `tool_call.*` / `tool_execution.update` 结构化流事件（event shell 补 `turnId`/`seq`，`data` 类型化），对齐 OpenClaw AssistantMessageEvent；保留 `stream_chunk`/`stream_end` 向后兼容。
|
||
- `v0.3`（M10）：管理面板 `/admin` 落地——按 §2 契约封装 admin 只读端点（personas/sessions/memories/plugins/channels/iot）+ owner-only `plugins/policy` 写；其余 M10 端点以契约路径封装、后端未实现时前端显式"待实现"壳。
|
||
- `v0.2`（M8）：gateway 落地——登录/health/chat/sessions/personas + admin 只读端点 + `plugins/policy` 写 + WS `/ws/chat`（JWT + bus 广播）。
|
||
- `v0.1`（契约先行）：骨架 + 端点登记表。
|