Cyrene_v2/Docs/api-client.md

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	✅	后台思考记录
12	/api/v1/admin/rag	GET	✅	知识库文档列表（分块/嵌入状态）；带 ?query= 时并入检索结果
13	/api/v1/admin/rag/query	POST	✅	知识库检索（真实检索；配置向量增强走语义路径）
14	/api/v1/admin/rag/delete	POST	🕐(写)	删除知识库文档；写操作 M10，当前返回 501 not_implemented
15	/api/v1/admin/observability/metrics	GET	✅	网关请求指标（总数/QPS/延迟/方法·路径·状态计数/LLM·子代理计数）
16	/api/v1/admin/observability/trace	GET	✅	最近 trace span（环形缓冲，默认 512 条）
17	/api/v1/admin/observability/audit	GET	✅	审计记录（who/what/when/result，SQLite 持久化）

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/rag · POST /api/v1/admin/rag/query · GET /api/v1/admin/observability/metrics · GET /api/v1/admin/observability/trace · GET /api/v1/admin/observability/audit 已实现，返回真实数据；GET /api/v1/admin/logs · GET /api/v1/admin/system 仍🕐未实现（前端按契约封装、后端 404 时显示"待实现"壳，不报错）。写操作（策略/档案/密钥/系统设置/用户与自动化创建、知识库上传/删除）经前端审计登记，待后端 M10+ 落地真实持久化与热重载。

知识库 RAG 契约：

• GET /admin/rag → {"data":{"documents":[{id,name,desc?,chunks,embedded}],"hits"?:[{docId,docName,chapter?,text,score,semantic}]}}。hits 仅在携带 ?query= 时出现；embedded 反映部署是否配置向量增强（未配置为待嵌入）。
• POST /admin/rag/query body {"query":"..."} → {"data":{"query":"...","hits":[{docId,docName,chapter?,text,score,semantic}]}}。检索走项目索引关键词+行上下文；配置 pgvector/向量增强时并入语义/向量命中（semantic:true）。
• POST /admin/rag/delete body {"id":"..."} → 写操作 M10，返回 501 {"error":{"code":"not_implemented",...}}。

可观测性契约（GET /api/v1/admin/observability/*，均需 owner/admin，?limit=N 缺省 50、上限 500）：

• GET /metrics → {"data":{"totalRequests","qps","avgLatencyMs","maxLatencyMs","perMethod{}","perPath{}","statusCounts{}","llmCalls","subagentEvents"}}。qps 为近 1 秒窗口计数；llmCalls/subagentEvents 由实际观测到的 trace span 按 kind 累计（Tracer 未注入时为 0）。Token/成本后端不统计、不返回（不伪造指标）。
• GET /trace?limit=100 → {"data":[{id,parentId?,name,kind,status,startedAt,endedAt?,durationNs,props?,events?]}。kind ∈ llm_call|tool_call|orchestration|state_transition|subagent|memory|guardrail；durationNs 为纳秒；events 为 [{time,type,props?}]。
• GET /audit?limit=100 → {"data":[{id,who,what,when,result}]}。id 为整数自增；when 为 RFC3339；来源为 SQLite audit_logs 表（未注入 AuditStore 时退化为进程内存）。

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.6（可观测性）：新增 GET /api/v1/admin/observability/{metrics,trace,audit}（owner/admin）——metrics 返回网关实时请求计数/QPS/延迟/方法·路径·状态分布 + LLM/子代理 span 计数；trace 返回 gateway 环形缓冲里的最近 span（经 TraceSink 对接 runtime tracer，映射为 AdminTraceSpan）；audit 返回持久化审计（SQLite audit_logs，未注入时退化为内存）。llmCalls/subagentEvents 由实际观测 span 累计；Token/成本后端不统计、不返回（不伪造指标）。
• 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（契约先行）：骨架 + 端点登记表。