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

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