docs(api): 规划第二阶段统一接口契约

2026-08-31 20:26:53 +08:00
parent 0b20bad0a8
commit bb8091f2e6
4 changed files with 1432 additions and 3 deletions
@@ -1,6 +1,6 @@
 # 后端接口契约（开发版）

-> 更新日期：2026-08-30。本文档记录当前前后端联调使用的已实现接口；机器可读字段、校验规则和响应模型以 FastAPI 运行时生成的 OpenAPI 为准。
+> 更新日期：2026-08-31。本文档记录当前前后端联调使用的已实现接口；机器可读字段、校验规则和响应模型以 FastAPI 运行时生成的 OpenAPI 为准。第二阶段尚未实现的规划接口见 `第二阶段接口契约-开发版.md`，不要将规划路径视为当前服务能力。

 ## 契约入口

@@ -159,7 +159,7 @@ RunCancelled

 ## 当前实现状态

-更新至 2026-08-30：后端 71 项回归测试通过。
+更新至 2026-08-31：后端 71 项回归测试通过。

 - Chat、Agent Run、Agent Events、Tool 列表、Provider 配置生命周期、模型列表和连接测试已经接入 AI Core。
 - Provider Adapter 当前包含 Mock、真正增量 SSE 的 OpenAI-Compatible Chat Completions，以及 Ollama JSONL Streaming。
@@ -168,3 +168,5 @@ RunCancelled
 - Plugin 启用前必须通过权限接口记录授权，未知权限默认拒绝。
 - Attachment Tool 读取 Host 管理的 `attachments` 目录；音频接口读取 Host 生成的转写文本，真实本地语音模型在第二阶段接入。
 - 接入业务模块时保持当前路径和 Contract，不在 Router 中直接实现数据库、Provider 或 Agent 逻辑。
+
+第二阶段开发保持本文件中已有路径兼容，并按 `第二阶段接口契约-开发版.md` 增加子资源、可选字段和事件。接口完成后先更新 OpenAPI 与本文件，再将第二阶段文档中的状态改为已实现。