AskaEth/Cyrene_v2

0 Fork 0

Files

T

Aska 24d5924cee

CI / Backend (build / vet / test / cross-compile) (push) Has been cancelled

Details

CI / Frontend (tsc + vite build) (push) Has been cancelled

Details

feat(model): Top5#1 结构化流事件 + WS 事件体系（对齐 OpenClaw AssistantMessageEvent）

- 新增 model/stream.go：StreamKind(text/thinking/tool_call 各 start/delta/end + tool_execution)
  + StreamEvent{Kind,Delta,Index,ID}。
- ChatStream 签名 onChunk func(delta string)→onEvent func(StreamEvent)；loop OnStream 同改；
  streamStep 转发结构化事件。
- openai：text_delta + text_start/text_end（正文三段式）；anthropic：文本块 text_*/tool_call_*
  按块 Index（content_block_stop 分支）真分段；fallback：有事件即交付。
- ws_hub：wsEvent 壳补 turnId/seq；新增 broadcastStream；streamChat 每帧打 turnId+seq；
  stream.go 把事件 publish 到 bus ws.stream。
- ws_bridge：streamEventData 映射 text_*→message.start/delta/end、thinking_*→thinking.*、
  tool_call_*→tool_call.*、tool_execution_update→tool_execution.update，未知回退 stream_chunk。
- 前端 ws.ts：解析 message.start/delta/end、thinking.start/delta/end(pendingThinking)、
  tool_call.start/end→addTool、tool_execution.update；保留旧 stream_chunk/thinking/tool_used 兼容；
  types.ts 补 turnId/seq。Docs/api-client.md 增 §3.1 v0.4。

已知限制（注释/文档标注）：turnId 在 OnStream→bus→relay 路径暂为空（StreamEvent 无 turnId 字段，
bus ws.stream 载荷不带 turn）；OpenAI adapter 未解析 tool_call 段；thinking 段两 adapter 暂不发；
tool_execution.update 是保留项（随工具循环钩子后置）。go build/vet/test + 前端 tsc 全绿。

2026-09-06 16:31:28 +08:00

6.3 KiB

Raw Blame History

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,mode?,stream?}` → `{data:{reply}}`；`stream:true` 时经 WS 触发流式
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	🕐	用户/角色/API key（M10）
9	`/api/v1/admin/llm`	GET/PUT	🕐	LLM 模型/路由/降级（M10）
10	`/api/v1/admin/automations`	GET/POST	🕐	自动化与提醒（M10）

M10 前端契约补充（管理面板，均🕐未实现，前端按契约封装、后端 404 时显示"待实现"壳，不报错）： GET /api/v1/admin/users（用户/角色/API key）· 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。写操作（策略/档案/密钥/系统设置）经前端审计登记，待后端 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。

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。
⚠️ 语音/流式完整 schema 随 M9 前端联调补充；会话级定向（当前对所有连接广播）为后续项。

4. 客户端接入指引

认证: 先 POST /api/v1/auth/login 取 JWT → WS 握手（?token=）注入。
版本: 客户端请求头声明 X-API-Version: 1。
离线: PWA / 原生端建议缓存 sessions/personas 列表。

5. 变更记录

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（契约先行）：骨架 + 端点登记表。

6.3 KiB Raw Blame History Unescape Escape