兼容 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 迁移目标固定为：

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。

当前实现：

通过一次 FastGPT 对话读取 newVariables.state；
删除辅助对话记录；
直接执行 state[key] = value；
再通过 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

4.1 KiB Raw Blame History Unescape Escape

兼容 API 契约基线

通用约定

POST /chat

请求