docs: add project README, env guide and assignment baseline notes

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
+```

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 配置；仅运行单元测试不需要。

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()                      # 协议层：解析请求、解析 <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 路径>`）。

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 契约夹具、修正说明、两种后端的启动方法。