72 lines
3.9 KiB
Markdown
72 lines
3.9 KiB
Markdown
# 阶段交付说明：后端适配层基线（LangGraph 迁移准备）
|
||
|
||
> 对应迁移计划 [langgraph-backend-migration-plan.md](langgraph-backend-migration-plan.md)
|
||
> 的“开工前准备”。本阶段不改变任何对外 API 行为，只把供应商细节收敛到适配层，
|
||
> 为作业 1—2 引入 LangGraph 后端提供可测试的接缝。
|
||
|
||
## 1. 交付内容
|
||
|
||
| 文件 | 职责 |
|
||
|---|---|
|
||
| `src/backends/chat.py` | 后端中立契约：`ChatBackend` Protocol、`ChatInput`、`ChatResult`、流式事件 `TextDelta` / `FormUpdate`、统一异常 `ChatBackend*Error` |
|
||
| `src/backends/fastgpt.py` | FastGPT 适配器：调用 SDK，把响应正文、表单更新节点（`更新表单`）和 SDK 异常翻译为中立契约 |
|
||
| `src/core/fastgpt_client.py` | `AsyncChatClient` 的初始化/关闭（lifespan）与依赖注入，新增 `get_chat_backend()` |
|
||
| `src/api/endpoints.py` | HTTP 协议层：`/chat` 只面向中立契约；保留 state 前缀解析、状态映射（`3001/3002→1002` 等）、SSE 事件序列 |
|
||
| `test/api/test_public_schema_contract.py` | 公共 schema 契约冻结测试（默认值、必填、长度上限、JSON 编码字符串） |
|
||
| `test/api/test_chat_backend_boundary.py` | 用 fake 后端验证 API 层不依赖 FastGPT：非流式结果映射、流式 state 前缀跨 chunk 缓冲 |
|
||
| `test/backends/test_fastgpt_backend.py` | FastGPT 适配器翻译测试：响应 → `ChatResult`、SSE 事件 → 中立事件、异常映射、SDK 调用参数 |
|
||
|
||
## 2. 调用链路
|
||
|
||
```text
|
||
POST /chat
|
||
└─ endpoints.chat() # 协议层：解析请求、解析 <state> 前缀、SSE
|
||
└─ ChatBackend.complete() / .stream() # 中立契约
|
||
└─ FastGPTBackend # 本阶段唯一实现
|
||
└─ AsyncChatClient (fastgpt-client SDK)
|
||
```
|
||
|
||
迁移时只需新增 `src/backends/langgraph.py` 实现同一 Protocol，并在依赖工厂中按配置
|
||
选择，协议层与公共契约保持不变（作业 2）。
|
||
|
||
## 3. 契约要点（冻结项）
|
||
|
||
- 请求：`sessionId`/`timeStamp`/`text` 必填；`clientMode` 缺省、空串、空白、null 均归一为
|
||
`direct`，允许 `browser_addon`；`needFormUpdate`/`useTextChunk` 默认 `false`。
|
||
- 非流式响应：正文需带 `<state>XXXX</state>` 前缀，API 解析后映射内部状态码
|
||
（`3001/3002/1002→1002`，`2006→2004`，`2017→2016`，`2020→0002`），
|
||
`browser_addon` 模式外部码加 `browser_addon.` 命名空间。
|
||
- SSE 事件名：`stage_code`、`formUpdate`、`text_delta`、`done`、`error`；
|
||
保证 `stage_code` 先于正文、成功只有一个 `done`、失败以 `error` 终止。
|
||
- `get_info` 的 `value` 始终是 JSON 编码字符串；分组读取时布尔值映射为 `"1"/"0"`。
|
||
|
||
## 4. 验证证据
|
||
|
||
Conda `py3.11` 环境执行（2026-02 验证，42 通过、0 失败）：
|
||
|
||
```bash
|
||
conda run -n py3.11 python -m pytest -q
|
||
# 42 passed
|
||
```
|
||
|
||
不需要 FastGPT 密钥即可运行全部单元测试（适配器测试使用 fake SDK）。
|
||
|
||
## 5. 已知限制与后续作业的对应关系
|
||
|
||
| 限制 | 处理计划 |
|
||
|---|---|
|
||
| 仅 FastGPT 一个后端实现 | 骨架已就位（作业 1—2），LangGraph 节点与适配器实现为 TODO |
|
||
| `set_info`/`get_info`/`delete_session` 仍直接读写 FastGPT 状态与历史 | 作业 6：应用服务 + repository，四接口共享业务状态 |
|
||
| 流式“先攒完整答案再切片”不是真实增量输出 | 作业 8：基于 LangGraph 流式 API 的真实增量 SSE |
|
||
| 缺少健康检查与运行指标 | 作业 9 |
|
||
| 服务启动强依赖 FastGPT 配置，无法无密钥启动文本模式 | 作业 2：按后端开关分别校验配置 |
|
||
|
||
## 6. 提交说明
|
||
|
||
按作业规则，每次提交应附运行命令、预期结果、实际结果。本阶段：
|
||
|
||
- 运行命令：见第 4 节。
|
||
- 预期结果：全部测试通过。
|
||
- 实际结果：42 passed。
|
||
- 环境说明：`fastgpt-client` 以本地 editable 方式安装（`pip install -e <sdk 路径>`）。
|