From a6ce570499d4136a60bcff30ad441345dc6d605b Mon Sep 17 00:00:00 2001 From: Eric Wang Date: Mon, 19 Oct 2026 13:32:31 +0800 Subject: [PATCH] docs: add project README, env guide and assignment baseline notes --- AGENTS.md | 16 +++++ README.md | 85 ++++++++++++++++++++++++ docs/assignment-baseline.md | 71 ++++++++++++++++++++ docs/langgraph-backend-migration-plan.md | 2 +- 4 files changed, 173 insertions(+), 1 deletion(-) create mode 100644 AGENTS.md create mode 100644 README.md create mode 100644 docs/assignment-baseline.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..550652b --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,16 @@ +# 开发环境 + +运行 Python 程序、测试及相关开发命令时，使用 Conda 的 `py3.11` 环境。 + +可以先激活环境： + +```bash +conda activate py3.11 +python -m pytest +``` + +也可以不激活，直接指定环境执行： + +```bash +conda run -n py3.11 python -m pytest +``` diff --git a/README.md b/README.md new file mode 100644 index 0000000..fc0f98c --- /dev/null +++ b/README.md @@ -0,0 +1,85 @@ +# AI 事故信息采集 API（LangGraph 迁移分支） + +本分支是“将对话后端从 FastGPT 工作流迁移到 LangGraph”课程的迁移准备分支。 + +当前状态：对外 API 契约保持不变，`/chat` 的供应商细节已封装到后端适配层（FastGPT 仍 +为唯一实现），迁移计划见 [docs/langgraph-backend-migration-plan.md](docs/langgraph-backend-migration-plan.md)。 +本阶段交付说明与验证证据见 [docs/assignment-baseline.md](docs/assignment-baseline.md)。 + +## 环境要求 + +- Python 3.11（使用 Conda 环境 `py3.11`，见 [AGENTS.md](AGENTS.md)） +- `fastgpt-client` SDK（当前以本地可编辑方式安装，见下文） + +## 安装 + +```bash +conda activate py3.11 + +# 项目依赖 +pip install -r requirements.txt + +# FastGPT SDK（本地可编辑安装；SDK 源码在独立仓库维护） +pip install -e /path/to/fastgpt-python-sdk +``` + +## 配置 + +服务端通过环境变量读取 FastGPT 连接信息。复制示例配置并按环境填写： + +```bash +cp src/.env.example .env +``` + +需要设置的变量： + +| 变量 | 说明 | +|---|---| +| `ANALYSIS_SERVICE_URL` | FastGPT 服务地址 | +| `ANALYSIS_AUTH_TOKEN` | FastGPT API Key | +| `APP_ID` | FastGPT 应用 ID | + +## 运行 + +```bash +python -m uvicorn src.main:app --host 127.0.0.1 --port 8000 +``` + +- `GET /` 存活检查 +- `POST /chat` 对话（`?stream=true` 为 SSE 流式） +- `POST /set_info`、`POST /get_info`、`DELETE /delete_session` 业务数据接口 + +## 测试 + +```bash +conda run -n py3.11 python -m pytest -q +``` + +测试分三层： + +- `test/api/test_public_schema_contract.py`：公共请求/响应 schema 的契约冻结测试 +- `test/api/test_chat_backend_boundary.py`：API 层与后端适配层的边界测试（fake 后端） +- `test/backends/test_fastgpt_backend.py`：FastGPT 适配器的翻译测试（fake SDK） + +## 目录结构 + +```text +src/ + api/endpoints.py # HTTP 协议层：schema、state 前缀解析、SSE 事件 + backends/chat.py # 后端中立契约（ChatBackend Protocol、ChatInput/ChatResult/事件） + backends/fastgpt.py # FastGPT 适配器：SDK 调用与响应翻译 + core/fastgpt_client.py # 客户端生命周期与依赖注入（lifespan） + schemas/models.py # 公共 Pydantic 模型 +docs/langgraph-backend-migration-plan.md # 十阶段迁移作业计划 +evals/ # 调用真实服务的评测用例与 runner +``` + +## 已知限制 + +- LangGraph 脚手架与后端适配层骨架已就位（作业 1—2）：`src/agent/`、 + `src/backends/langgraph.py`、`AGENT_BACKEND` 开关；节点逻辑与适配器实现 + 为待完成的 TODO，对应测试 `test/agent/`、`test/backends/test_langgraph_backend.py` + 在完成前会失败，属预期状态。 +- `set_info` / `get_info` / `delete_session` 仍直接依赖 FastGPT 状态与历史，迁移到共享 + 业务状态属于作业 6。 +- 服务启动需要有效的 FastGPT 配置；仅运行单元测试不需要。 diff --git a/docs/assignment-baseline.md b/docs/assignment-baseline.md new file mode 100644 index 0000000..866e81c --- /dev/null +++ b/docs/assignment-baseline.md @@ -0,0 +1,71 @@ +# 阶段交付说明：后端适配层基线（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() # 协议层：解析请求、解析 前缀、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`。 +- 非流式响应：正文需带 `XXXX` 前缀，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 `）。 diff --git a/docs/langgraph-backend-migration-plan.md b/docs/langgraph-backend-migration-plan.md index 81bd599..eabaf13 100644 --- a/docs/langgraph-backend-migration-plan.md +++ b/docs/langgraph-backend-migration-plan.md @@ -126,7 +126,7 @@ python -m pytest test/agent/test_scaffold.py -q 3. 提供 `AGENT_BACKEND=fastgpt|langgraph` 类型化配置和依赖工厂。LangGraph fake 模式启动不得要求 FastGPT 密钥；仍启用语音 FastGPT 路径时单独校验所需配置。 4. 将资源初始化和关闭纳入 lifespan。两种后端分别执行启动冒烟验证，不仅在测试中覆盖依赖。 5. 在现有 `test/api/` 补充 HTTP 级契约测试；检查 OpenAPI schema、JSON 响应和 SSE 事件。 -6. 先运行已有测试并记录基线。已知需检查的过期预期包括：默认请求缺少 `clientMode`、`ChatInput.client_mode` 仍期望空串、`nextStageCode` 把五字符视为超长。按当前实际契约修正预期，不能为消除红灯收窄合法协议。 +6. 在 Conda 的 `py3.11` 环境先运行已有测试并记录基线。当前测试已覆盖默认 `clientMode=direct`、API 向 `ChatInput` 传递该模式，以及 `nextStageCode` 的 32 字符上限。后续按当前实际契约维护预期，不能为消除红灯收窄合法协议。 7. 保存请求与响应夹具，覆盖两种 clientMode、分句开关、表单开关、state 标签跨 chunk 和错误响应。 **交付物：** 可切换的图后端、HTTP 契约夹具、修正说明、两种后端的启动方法。