116 lines
4.1 KiB
Markdown
116 lines
4.1 KiB
Markdown
# 兼容 API 契约基线
|
||
|
||
## 通用约定
|
||
|
||
- 路径保持 `/chat`、`/set_info`、`/get_info`。
|
||
- 请求和响应字段保持 camelCase。
|
||
- 业务成功/失败主要通过响应体字符串 `code` 表达；现有 endpoint 通常仍返回 HTTP 200。
|
||
- `sessionId` 最大 64 字符，`timeStamp` 最大 32 字符。
|
||
- Pydantic 校验失败由 FastAPI 返回 HTTP 422。
|
||
- 本文冻结的是当前可观察行为；“目标行为”标记为后续迁移必须修复的已批准偏差。
|
||
|
||
## `POST /chat`
|
||
|
||
### 请求
|
||
|
||
| 字段 | 类型 | 必填 | 默认值 |
|
||
|---|---|---:|---|
|
||
| `sessionId` | string | 是 | - |
|
||
| `timeStamp` | string | 是 | - |
|
||
| `text` | string | 是 | - |
|
||
| `needFormUpdate` | boolean | 否 | `false` |
|
||
| `useTextChunk` | boolean | 否 | `false` |
|
||
|
||
### 非流式响应
|
||
|
||
字段为 `sessionId`、`timeStamp`、`outputText`、`formUpdate`、`nextStage`、`nextStageCode`、`code`、`msg`。
|
||
|
||
- 成功时 `code="200"`。
|
||
- `<state>XXXX</state>` 从正文中移除。
|
||
- `3001/3002/1002 → 1002`，`2006 → 2004`，`2017 → 2016`，`2020 → 0002`。
|
||
- Prefix 缺失或正文不可解析时当前返回 `code="500"` 和“消息不完整”。
|
||
- FastGPT 认证、限流和 API 异常分别映射为响应体 `401`、`429`、`500`。
|
||
- `formUpdate` 保持无固定 schema 的 JSON 值，以兼容现有调用方。
|
||
|
||
### SSE 响应
|
||
|
||
事件名和数据：
|
||
|
||
| 事件 | 数据 | 基数 |
|
||
|---|---|---|
|
||
| `stage_code` | `{"nextStageCode":"1002","nextStage":"通话中"}` | 成功轮最多一次 |
|
||
| `formUpdate` | 表单 patch 对象 | 有更新时最多一次 |
|
||
| `text_delta` | `{"text":"..."}` | 零到多次 |
|
||
| `done` | `{"status":"completed"}` | 成功恰好一次 |
|
||
| `error` | `{"msg":"...","code":"500"}` | 失败恰好一次且终止 |
|
||
|
||
V1.0.9 文档要求 `stage_code` 先于 `text_delta`；`formUpdate` 的位置由 FastGPT `flowResponses` 到达时间决定，文档示例允许它出现在两个 `text_delta` 之间。LangGraph 迁移目标固定为：
|
||
|
||
```text
|
||
stage_code -> formUpdate(可选) -> text_delta* -> done
|
||
```
|
||
|
||
迁移后的错误路径不得同时产生 `done` 和 `error`。`useTextChunk=true` 只改变 `text_delta` 切分，不改变拼接后的文本。
|
||
|
||
### 已知偏差
|
||
|
||
- 当前流式 parser 会在整段文本中搜索标签，而不是强制标签位于开头。
|
||
- 当前流式未知状态码仍可能发送空 `nextStage`。
|
||
- 当前流式缺少 prefix 时仍可能输出正文和 `done`。
|
||
- 当前流式内部事件处理异常会记录后继续，可能掩盖部分失败。
|
||
- 当前实现记录完整输入、输出和 `formUpdate`，不符合数据保护目标。
|
||
|
||
以上偏差被字符化测试记录，但不作为 LangGraph 新实现的目标行为；Phase 5–8 必须按迁移计划修正。
|
||
|
||
## `POST /set_info`
|
||
|
||
### 请求
|
||
|
||
字段为 `sessionId`、`timeStamp`、`key`、`value`、`includeInputInfo`；其中 `includeInputInfo` 默认 `false`。
|
||
|
||
当前实现：
|
||
|
||
1. 通过一次 FastGPT 对话读取 `newVariables.state`；
|
||
2. 删除辅助对话记录；
|
||
3. 直接执行 `state[key] = value`；
|
||
4. 再通过 FastGPT 对话写回并删除辅助记录。
|
||
|
||
成功返回 `code="200"`；任一步失败返回响应体 `code="500"`。
|
||
|
||
目标行为：
|
||
|
||
- 仅接受 `field-registry.json` 中 `external_write=true` 的 key。
|
||
- 进行类型转换和领域校验。
|
||
- 禁止写内部状态字段。
|
||
- 直接事务化写业务状态，不调用 LLM，不创建/删除辅助聊天记录。
|
||
|
||
## `POST /get_info`
|
||
|
||
请求字段为 `sessionId`、`timeStamp`、`key`、`includeInputInfo`；`includeInputInfo` 默认 `false`。
|
||
|
||
支持：
|
||
|
||
- `all`
|
||
- `acdinfo`
|
||
- `acdhuman1`
|
||
- `acdhuman2`
|
||
- 单个字段 key
|
||
|
||
兼容序列化：
|
||
|
||
- `value` 始终是 JSON 编码后的字符串。
|
||
- boolean 转为字符串 `"1"` 或 `"0"`。
|
||
- 缺失字段转为空字符串。
|
||
- 未知单字段 key 当前返回 JSON 字符串 `""`，而不是报错。
|
||
|
||
目标实现仍保留上述响应编码，但直接读取业务投影，不调用 FastGPT。
|
||
|
||
## 契约来源
|
||
|
||
- `src/schemas/models.py`
|
||
- `src/api/endpoints.py`
|
||
- `docs/视频快处智能信息采集机器人交互接口文档V1.0.9.docx`
|
||
- `docs/chat-stream-mode.md`
|
||
- `test/api/test_public_schema_contract.py`
|
||
- `test/api/test_chat_backend_boundary.py`
|