commit 81e156703a6a31f4f2fbf798938537d5ddeb464b
Author: gqt <3217233537@qq.com>
Date:   Mon Jul 13 10:14:09 2026 +0800

    docs: add kbqa system design

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..49b0112
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,28 @@
+# Secrets and local configuration
+.env
+.env.*
+!.env.example
+1.md
+
+# Local runtime data
+data/
+
+# Superpowers visual brainstorming artifacts
+.superpowers/
+
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+
+# Node.js
+node_modules/
+dist/
+coverage/
+
+# Editors and operating systems
+.DS_Store
+.idea/
+.vscode/
diff --git a/docs/superpowers/specs/2026-07-13-kbqa-system-design.md b/docs/superpowers/specs/2026-07-13-kbqa-system-design.md
new file mode 100644
index 0000000..8df0df3
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-13-kbqa-system-design.md
@@ -0,0 +1,550 @@
+# 双 Agent 个人知识库问答系统设计
+
+**状态：** 已确认  
+**日期：** 2026-07-13  
+**设计范围：** 首个可运行、可持久化、可真实模型验收的本地单用户版本
+
+## 1. 目标
+
+构建一个本地单用户知识库问答系统。用户可以上传可提取文本的 PDF、Markdown 和 TXT 文件；系统在后台调用真实 Embedding 模型完成分块和向量索引；用户通过双 Agent 对知识库进行严格、有引用、可多轮追问的问答，并通过 SSE 接收流式回答。
+
+首版完成标准是打通并验证以下完整链路：
+
+> 上传真实文档 → 后台真实 Embedding 索引 → 发起问题 → 双 Agent 真实检索和生成 → SSE 流式回答 → 右栏展示可点击引用 → 多轮追问 → 重启后文档与会话仍存在 → 删除文档/会话后相关数据完整清理
+
+## 2. 已确认约束
+
+- 产品形态是本机运行的单用户个人知识库，不实现登录、权限和用户隔离。
+- 关系数据库固定使用 SQLite，不使用 PostgreSQL、psycopg 或 JSONB。
+- 向量数据库固定使用 Milvus Lite。
+- Agent 框架固定使用 LangChain 1.x API。
+- Agent 必须是双 Agent：主 Agent 负责组织回答，研究 Agent 负责规划并执行一次或多次检索。
+- Agent 创建使用 `langchain.agents.create_agent`，不使用旧的 `langgraph.prebuilt.create_react_agent`。
+- 主 Agent 与研究 Agent 均使用 `qwen3.5-flash`。
+- Embedding 使用 `text-embedding-v4`，向量维度固定为 `1024`。
+- Chat 与 Embedding 均通过 `.env` 中配置的 DashScope OpenAI 兼容地址和密钥真实调用。
+- 系统采用严格知识库模式：没有足够证据时明确回答资料不足，不使用模型自身知识补全事实。
+- PDF 只支持可提取文本的文件，不实现扫描件 OCR。
+- 文档上传后后台异步索引，接口不等待 Embedding 完成。
+- 应用重启后必须恢复未完成的索引任务。
+- SQLite 保存历史会话、用户消息、最终回答和引用；Agent 内部消息不写入业务数据库。
+- LangSmith 必须接入，用于记录主 Agent、研究 Agent、工具调用和耗时。
+- LangSmith 使用官方 `LANGSMITH_` 环境变量；其余应用配置使用 `KBQA_` 前缀。
+- 首版本机直接运行，不提供 Docker 或 Docker Compose。
+- Python 项目使用 `uv`，提交 `.python-version` 固定 Python 3.12。
+- Node.js 项目使用 `npm`。
+- 不采用 TDD。测试在功能实现后编写和执行。
+- 模型和 Embedding 测试不得使用 Mock；`live` 测试直接调用真实服务。
+- 前端必须使用 `agent-browser` 操作真实页面完成端到端验收。
+
+## 3. 范围
+
+### 3.1 首版功能
+
+- 上传、列出、查看、重试和删除 PDF、Markdown、TXT 文档。
+- 查看文档索引状态、失败原因和分块原文。
+- 创建、列出和删除会话。
+- 查看持久化的历史消息与仍然有效的引用。
+- 通过 POST SSE 接口提交问题并接收研究状态、引用、回答 token 和结束/错误事件。
+- 支持依赖历史语境的多轮追问。
+- 显示本轮引用来源、相关度和完整 chunk 原文。
+- 提供 SQLite 与 Milvus Lite 健康检查。
+- 通过 LangSmith 查看双 Agent 的完整运行轨迹。
+
+### 3.2 明确不做
+
+- 用户账号、鉴权、角色权限或租户隔离。
+- 扫描 PDF OCR。
+- WebSocket。
+- Docker 化和远程生产部署。
+- 多进程 Uvicorn worker。
+- 混合检索、关键词检索、重排模型或知识图谱。
+- 会话自动摘要和无限上下文记忆。
+- 主 Agent 使用模型自身知识回答资料外问题。
+- 保存子 Agent 工具消息或内部执行状态到 SQLite。
+- 模型、Embedding 或向量数据库的测试替身。
+
+## 4. 总体架构
+
+项目采用单仓库：
+
+```text
+浏览器中的 React 三栏工作台
+  ├─ REST：文档、会话、历史和健康检查
+  └─ POST + ReadableStream：SSE 流式问答
+                   │
+                   ▼
+单进程 FastAPI 应用
+  ├─ API 路由与统一错误处理
+  ├─ 文档、会话和问答应用服务
+  ├─ SQLite 持久任务 + asyncio 单消费者索引 Worker
+  └─ LangChain 1.x 双 Agent
+       ├─ 主 Agent：research 工具
+       └─ 研究 Agent：search_knowledge_base 工具
+                   │
+        ┌──────────┼──────────┐
+        ▼          ▼          ▼
+     SQLite    Milvus Lite   data/raw
+        │
+        ├─ DashScope：真实 Chat 与 Embedding
+        └─ LangSmith：Agent 与工具追踪
+```
+
+SQLite 是业务事实源。Milvus Lite 只负责向量检索。两者无法组成跨库事务，因此通过文档状态、持久索引任务、确定性 chunk ID、幂等 upsert、按文档清理和启动恢复实现最终一致。
+
+FastAPI 只能以一个 Uvicorn worker 运行。多进程会重复启动本地索引消费者，也会增加 SQLite 与 Milvus Lite 文件竞争。
+
+## 5. 组件边界
+
+### 5.1 后端
+
+后端位于 `backend/`，Python 包位于 `backend/src/kbqa/`。
+
+- `main.py`：创建 FastAPI 应用，注册中间件、路由、异常处理与生命周期。
+- `config.py`：使用 `pydantic-settings` 读取 `KBQA_` 配置并校验必填项。
+- `database.py`：创建 SQLAlchemy 2.x async engine、session factory，并设置 SQLite PRAGMA。
+- `api/`：请求 ID、中间件、错误响应和路由汇总。
+- `documents/`：文档 ORM、DTO、repository、上传/删除服务和 HTTP 路由。
+- `indexing/`：文件加载、文本分割、持久任务队列、单消费者 worker 和恢复逻辑。
+- `rag/`：真实 Embedding 工厂、MilvusClient 封装和检索器。
+- `chat/`：会话/消息 ORM、DTO、repository、SSE 编码和问答应用服务。
+- `agents/`：LLM 工厂、提示词、检索工具、研究 Agent、主 Agent 和 middleware。
+- `health/`：SQLite 与 Milvus Lite 探测。
+
+每个模块只通过公开 service/repository 接口协作。HTTP 路由不直接操作 ORM、Milvus 或 Agent；Agent 工具不直接管理 HTTP 响应或业务事务。
+
+### 5.2 前端
+
+前端位于 `web/`，采用 React + TypeScript + Vite、React Router、zustand、Tailwind CSS 与 shadcn/ui。
+
+- `app/`：路由、全局布局和 provider。
+- `features/chat/`：会话列表、消息列表、输入框、SSE client、证据栏和会话 store。
+- `features/documents/`：上传、列表、状态轮询、重试、删除、分块详情。
+- `components/`：只存放跨功能复用的展示组件。
+- `lib/api/`：普通 JSON client、统一错误解析和请求类型。
+- `lib/sse/`：可处理跨 chunk 边界的 SSE 增量解析器。
+
+服务端数据由 API 获取；zustand 只保存当前会话、流式临时状态和界面状态，不作为持久化事实源。
+
+## 6. SQLite 数据模型
+
+数据库 URL 使用 `sqlite+aiosqlite:///...`。连接时启用：
+
+- `PRAGMA foreign_keys=ON`
+- `PRAGMA journal_mode=WAL`
+- `PRAGMA busy_timeout=5000`
+
+所有 ID 使用 UUID 字符串，时间统一保存为 UTC。表结构通过 Alembic 管理。
+
+### 6.1 `documents`
+
+| 字段 | 类型 | 约束/用途 |
+|---|---|---|
+| `id` | TEXT | 主键，UUID |
+| `filename` | TEXT | 用户原始文件名 |
+| `stored_path` | TEXT | `data/raw/{document_id}.{ext}` |
+| `file_type` | TEXT | `pdf/md/txt` |
+| `mime_type` | TEXT | 检测后的 MIME |
+| `file_size` | INTEGER | 字节数 |
+| `sha256` | TEXT | 内容完整性标识，不设置唯一约束 |
+| `status` | TEXT | `pending/indexing/indexed/failed/deleting` |
+| `chunk_count` | INTEGER | 默认 0 |
+| `error_code` | TEXT NULL | 安全错误码 |
+| `error_message` | TEXT NULL | 可展示错误摘要 |
+| `created_at` | DATETIME | UTC |
+| `updated_at` | DATETIME | UTC |
+
+按 `status` 和 `updated_at` 建索引。
+
+### 6.2 `index_jobs`
+
+| 字段 | 类型 | 约束/用途 |
+|---|---|---|
+| `id` | TEXT | 主键，UUID |
+| `document_id` | TEXT | 外键，删除文档时级联；唯一 |
+| `status` | TEXT | `queued/running/succeeded/failed` |
+| `attempt_count` | INTEGER | 实际执行次数 |
+| `last_error` | TEXT NULL | 内部错误摘要，不包含密钥 |
+| `created_at` | DATETIME | UTC |
+| `started_at` | DATETIME NULL | UTC |
+| `finished_at` | DATETIME NULL | UTC |
+
+启动时将 `queued/running` 任务统一恢复为 `queued` 并重新入队。失败文档通过重试接口复用同一任务记录、增加 `attempt_count`。
+
+### 6.3 `chunks`
+
+| 字段 | 类型 | 约束/用途 |
+|---|---|---|
+| `id` | TEXT | 主键，UUID，也是 Milvus 主键 |
+| `document_id` | TEXT | 外键，删除文档时级联 |
+| `order_index` | INTEGER | 文档内顺序，从 0 开始 |
+| `content` | TEXT | 分块原文 |
+| `page_number` | INTEGER NULL | PDF 页码，从 1 开始 |
+| `char_count` | INTEGER | 字符数 |
+| `created_at` | DATETIME | UTC |
+
+`(document_id, order_index)` 唯一，并为 `document_id` 建索引。
+
+### 6.4 `chat_sessions`
+
+| 字段 | 类型 | 约束/用途 |
+|---|---|---|
+| `id` | TEXT | 主键，UUID |
+| `title` | TEXT NULL | 手动标题；未提供时由首次问题前 30 个字符填充 |
+| `created_at` | DATETIME | UTC |
+| `updated_at` | DATETIME | UTC，按此字段倒序列出 |
+
+### 6.5 `messages`
+
+| 字段 | 类型 | 约束/用途 |
+|---|---|---|
+| `id` | TEXT | 主键，UUID |
+| `session_id` | TEXT | 外键，删除会话时级联 |
+| `role` | TEXT | 只允许 `user/assistant` |
+| `content` | TEXT | 用户问题或最终回答 |
+| `status` | TEXT | `generating/completed/failed` |
+| `error_code` | TEXT NULL | assistant 失败原因 |
+| `order_index` | INTEGER | 会话内顺序 |
+| `created_at` | DATETIME | UTC |
+
+`(session_id, order_index)` 唯一，并为 `(session_id, created_at)` 建索引。用户消息直接为 `completed`；assistant 在运行前创建空内容的 `generating` 占位记录，完成后一次更新内容。
+
+### 6.6 `message_sources`
+
+| 字段 | 类型 | 约束/用途 |
+|---|---|---|
+| `id` | TEXT | 主键，UUID |
+| `message_id` | TEXT | assistant 消息外键，删除消息时级联 |
+| `document_id` | TEXT | 文档外键，删除文档时级联 |
+| `chunk_id` | TEXT | chunk 外键，删除 chunk 时级联 |
+| `citation_label` | TEXT | `S1` 至 `S8` |
+| `score` | REAL | COSINE 检索分数 |
+| `created_at` | DATETIME | UTC |
+
+`(message_id, chunk_id)` 唯一。来源正文和文件名实时关联 `chunks/documents`，不在该表保留正文副本。删除文档后历史回答文本仍保留，但对应来源卡片和来源正文会彻底删除。
+
+## 7. Milvus Lite 设计
+
+数据库文件默认位于 `data/milvus/kbqa.db`，collection 名为 `kbqa_chunks`。
+
+| 字段 | Milvus 类型 | 用途 |
+|---|---|---|
+| `chunk_id` | VARCHAR | 主键，使用 SQLite chunk UUID |
+| `document_id` | VARCHAR | 按文档过滤和删除 |
+| `order_index` | INT64 | 原文顺序 |
+| `vector` | FLOAT_VECTOR | `dim=1024` |
+
+向量索引使用 `AUTOINDEX`，距离指标使用 `COSINE`。Milvus 不重复保存 chunk 正文。检索得到 chunk ID 和分数后，应用一次批量查询 SQLite，并丢弃所属文档不是 `indexed` 状态的结果。
+
+索引和重试使用确定性 `chunk_id` 执行 upsert。清理使用 `document_id` filter 删除整篇文档的向量。
+
+## 8. 文档索引流程
+
+1. API 校验文件大小、扩展名、MIME 与内容。
+2. 文件以 UUID 文件名写入 `data/raw`，避免路径穿越和同名覆盖。
+3. 在一个 SQLite 事务内创建 `documents(status=pending)` 与 `index_jobs(status=queued)`。
+4. 任务提交给进程内 `asyncio.Queue`，API 返回 `202`。
+5. 单消费者将任务和文档改为 `running/indexing`。
+6. 重试前按 `document_id` 清理旧 Milvus 向量和旧 SQLite chunk。
+7. PDF 使用可提取文本加载器；Markdown/TXT 使用文本加载器。无文本 PDF 失败为 `PDF_TEXT_NOT_EXTRACTABLE`。
+8. 使用 `RecursiveCharacterTextSplitter`，默认 `chunk_size=500`、`chunk_overlap=50`。
+9. 在内存中形成 chunk 与确定性 ID，批量调用真实 `text-embedding-v4`。
+10. SQLite 写入 chunk，文档仍保持 `indexing`。
+11. Milvus 按 chunk ID upsert 向量。
+12. SQLite 将文档改为 `indexed`、记录 `chunk_count`，任务改为 `succeeded`。
+13. 任一步骤失败时文档和任务改为 `failed`，保存安全错误信息；残留向量在下一次重试或删除时清理。
+
+索引同一时间只处理一篇文档，避免本地数据库竞争和模型并发额度失控。
+
+## 9. 双 Agent 设计
+
+### 9.1 模型工厂
+
+`ChatOpenAI` 使用 DashScope OpenAI 兼容 `base_url`、API key 和 `qwen3.5-flash`。主 Agent 与研究 Agent使用相同模型配置，但分别添加 LangSmith tag：`main-agent` 和 `research-agent`。
+
+Embedding 工厂使用 `OpenAIEmbeddings`、`text-embedding-v4` 和固定 1024 维输出。应用启动不调用模型；真实连通性由 live 测试验证。
+
+### 9.2 研究 Agent
+
+研究 Agent 使用 `langchain.agents.create_agent` 创建，只注册 `search_knowledge_base` 工具。它接收主 Agent 整理后的独立问题，而不是整个会话历史。
+
+研究 Agent 每轮最多调用检索工具 3 次。每次检索：
+
+- 对查询调用真实 Embedding。
+- 从 Milvus 请求候选结果。
+- 批量回查 SQLite，只接受 `indexed` 文档的 chunk。
+- 返回最多 5 条结果。
+- 文本内容供研究 Agent 阅读，完整来源元数据作为 Tool artifact 保存在本次运行消息中。
+
+研究完成后，外层 `research` 工具从 ToolMessage artifact 收集全部结果，按 chunk ID 去重并保留最高分，最多形成 8 条来源，编号为 `S1` 至 `S8`。
+
+### 9.3 主 Agent
+
+主 Agent 使用 `langchain.agents.create_agent` 创建，只注册 `research` 工具，并读取当前会话最近 20 条用户可见消息。
+
+自定义 LangChain 1.x middleware 强制当前知识问答在生成最终答案前完成一次成功的 `research` 调用，并限制模型/工具调用次数。主 Agent不能访问 Milvus，也不能直接调用底层检索工具。
+
+`research` 工具向主 Agent 返回：
+
+- 研究 Agent 基于工具结果生成的摘要。
+- 编号后的原始证据片段。
+- 可使用的引用标签集合。
+
+主 Agent提示词要求所有知识性事实基于证据并使用 `[S1]` 形式引用。若研究结果为空，Chat Service 不再让主 Agent自由生成，而是发送固定的资料不足回答。最终答案中不存在的来源标签视为运行错误，不写入成功历史。
+
+严格知识库模式通过“强制研究、空证据短路、引用标签校验”实现。它不能从数学上证明每句话的事实正确性，但会阻断无检索回答和伪造来源。
+
+## 10. 会话与 SSE 流程
+
+1. 校验会话存在且当前没有进行中的生成。
+2. 保存 `user/completed` 消息和 `assistant/generating` 占位消息。
+3. 读取最近 20 条用户可见历史消息。
+4. 调用主 Agent 的 async stream，启用 `messages/custom/updates` 流模式。
+5. 研究开始时发送 `status(researching)`。
+6. `research` 完成后发送去重后的 `sources`。
+7. 主 Agent开始最终回答时发送 `status(answering)`。
+8. 只将主 Agent最终回答的 token 映射为 `token` 事件；不暴露研究 Agent草稿或内部工具消息。
+9. 累积完整回答，校验引用标签，在一个 SQLite 事务内更新 assistant 消息并写入 `message_sources`。
+10. 数据持久化完成后发送 `done`。
+
+研究期间每 15 秒发送 SSE 注释 `: ping`。前端不展示 heartbeat。
+
+浏览器使用 `AbortController` 取消请求。客户端断开、模型超时或服务异常时取消下游任务并将 assistant 占位消息标记为 `failed`；残缺 token 不保存为成功回答。
+
+## 11. SSE 事件契约
+
+`POST /api/v1/chat/stream` 的 `Content-Type` 为 `text/event-stream`。
+
+```text
+event: status
+data: {"phase":"researching"}
+
+event: sources
+data: {"sources":[{"label":"S1","document_id":"...","chunk_id":"...","filename":"rag.pdf","order_index":2,"page_number":3,"content":"...","score":0.92}]}
+
+event: status
+data: {"phase":"answering"}
+
+event: token
+data: {"content":"RAG"}
+
+event: done
+data: {"message_id":"..."}
+
+event: error
+data: {"code":"MODEL_TIMEOUT","message":"模型响应超时，请重试","retryable":true}
+```
+
+事件 data 必须是单行 JSON。前端 SSE parser 必须正确处理 TCP chunk 在任意字符或行位置切分的情况。
+
+## 12. HTTP API
+
+所有业务 API 使用 `/api/v1` 前缀。
+
+### 12.1 文档
+
+| 方法 | 路径 | 成功响应 | 说明 |
+|---|---|---|---|
+| POST | `/api/v1/documents` | `202 Document` | 上传、落盘并创建后台任务 |
+| GET | `/api/v1/documents` | `200 Page[Document]` | 分页，支持 status 过滤 |
+| GET | `/api/v1/documents/{id}` | `200 Document` | 文档详情 |
+| GET | `/api/v1/documents/{id}/chunks` | `200 Page[Chunk]` | 分页分块预览 |
+| POST | `/api/v1/documents/{id}/retry` | `202 Document` | 只允许 failed 状态 |
+| DELETE | `/api/v1/documents/{id}` | `204` | 清理向量、文件和 SQLite 关联数据 |
+
+删除时先把文档标记为 `deleting`，再按顺序删除 Milvus 向量、原文件和 SQLite 关联数据。只有全部成功才返回 204；失败时保留 `deleting` 记录。应用启动时查询所有 `deleting` 文档并继续清理，向量或文件已经不存在时按删除成功处理，保证恢复流程幂等。
+
+### 12.2 会话与问答
+
+| 方法 | 路径 | 成功响应 | 说明 |
+|---|---|---|---|
+| POST | `/api/v1/sessions` | `201 Session` | 可提供标题 |
+| GET | `/api/v1/sessions` | `200 Page[Session]` | 按 updated_at 倒序 |
+| GET | `/api/v1/sessions/{id}/messages` | `200 Page[Message]` | 返回用户可见消息和有效来源 |
+| DELETE | `/api/v1/sessions/{id}` | `204` | 级联删除消息和引用 |
+| POST | `/api/v1/chat/stream` | `200 text/event-stream` | `{session_id, query}` |
+
+同一会话同时只允许一个生成任务；冲突返回 409。未提供标题的会话使用 NULL 保存，界面显示“新会话”；首次问题将标题更新为问题前 30 个字符，不额外调用模型生成标题。
+
+### 12.3 健康检查
+
+`GET /health` 检查应用、SQLite 与 Milvus Lite，返回各组件状态，但不调用付费 Chat 或 Embedding 服务。
+
+## 13. 文件校验与限制
+
+- 默认最大上传大小为 20 MiB，可通过配置修改。
+- 只允许 `.pdf`、`.md`、`.markdown` 和 `.txt`。
+- 同时校验扩展名、MIME 与内容签名，不只信任浏览器提供的 MIME。
+- 原始文件名只用于展示；落盘文件名使用 document UUID。
+- Markdown 和 TXT 必须能按 UTF-8 解码。
+- PDF 必须至少提取到一段非空文本，否则异步任务失败并提示不支持扫描件。
+- 同内容文件允许重复上传；SHA-256 用于诊断和完整性，不用于拒绝重复。
+
+## 14. 错误处理
+
+普通 JSON API 的错误格式：
+
+```json
+{
+  "error": {
+    "code": "UNSUPPORTED_FILE_TYPE",
+    "message": "仅支持 PDF、Markdown 和 TXT 文件",
+    "request_id": "..."
+  }
+}
+```
+
+状态码约定：
+
+- 413：文件过大。
+- 415：文件类型不支持。
+- 404：文档或会话不存在。
+- 409：资源状态冲突或会话正在生成。
+- 422：参数校验失败。
+- 502：模型上游返回错误。
+- 504：模型调用超时。
+- 503：SQLite 或 Milvus Lite 暂不可用。
+
+SSE 建立后发生的错误使用 `event: error`，不能再尝试改变 HTTP 状态码。服务端日志记录 request ID 和异常堆栈，但不记录密钥、完整提示词或文档正文；前端只显示安全错误摘要和是否可重试。
+
+## 15. 前端交互
+
+### 15.1 桌面三栏
+
+- 左栏固定约 220–260 px：产品标识、对话/文档导航、新建会话和历史会话。
+- 中栏自适应：对话消息、研究/回答状态和固定底部输入框。
+- 右栏固定约 300–340 px：当前回答的来源列表和来源详情。
+
+来源以 `S1`、`S2` 展示。点击来源卡片后直接在右栏原位展开完整 chunk，不使用遮挡对话的 modal。用户切换某条历史 assistant 消息时，右栏同步切换到该消息的有效来源。
+
+文档被删除后，历史回答中的引用标签仍可见，但不存在对应 `message_sources` 记录；前端将其渲染为不可点击的“来源已删除”，不显示原文件名或正文。
+
+### 15.2 文档页面
+
+文档页沿用同一工作台框架：
+
+- 左栏显示主导航、状态筛选和计数。
+- 中栏显示上传入口、文档列表、类型、分块数和索引状态。
+- 右栏显示选中文档信息和分页 chunk 预览。
+- failed 文档显示安全失败原因和重试按钮。
+
+### 15.3 响应式
+
+- `>= 1100 px`：完整三栏。
+- `768–1099 px`：右侧来源变为可打开的抽屉。
+- `< 768 px`：左侧导航与来源均为抽屉，聊天区单栏显示。
+
+首版以桌面浏览器为主要验收目标，同时保证窄屏关键操作可用。
+
+### 15.4 路由
+
+- `/chat`：无会话时显示空状态或新建会话入口。
+- `/chat/:sessionId`：指定会话的多轮问答。
+- `/documents`：文档列表与上传入口。
+- `/documents/:documentId`：指定文档及其分块详情。
+
+### 15.5 客户端状态
+
+- 索引页面每 2 秒轮询 pending/indexing 文档，进入 indexed/failed 后停止。
+- SSE 临时 token 只保存在当前页面状态；收到 done 后重新读取持久化消息。
+- 研究中展示阶段提示，但 heartbeat 不产生视觉提示。
+- failed assistant 消息显示可重新发送原问题的操作。
+- 没有 indexed 文档时，聊天空状态引导用户先上传文档。
+
+## 16. 配置与密钥
+
+应用配置使用 `KBQA_` 前缀；LangSmith SDK 使用其官方 `LANGSMITH_` 环境变量。`.env.example` 只包含占位符，至少包括：
+
+```dotenv
+KBQA_DASHSCOPE_API_KEY=
+KBQA_DASHSCOPE_BASE_URL=
+KBQA_CHAT_MODEL=qwen3.5-flash
+KBQA_EMBEDDING_MODEL=text-embedding-v4
+KBQA_EMBEDDING_DIM=1024
+KBQA_DATABASE_URL=sqlite+aiosqlite:///./data/kbqa.sqlite3
+KBQA_MILVUS_URI=./data/milvus/kbqa.db
+KBQA_CHUNK_SIZE=500
+KBQA_CHUNK_OVERLAP=50
+KBQA_RETRIEVAL_TOP_K=5
+KBQA_MAX_RESEARCH_SEARCHES=3
+KBQA_MAX_SOURCES=8
+KBQA_HISTORY_MESSAGE_LIMIT=20
+KBQA_MAX_UPLOAD_MIB=20
+KBQA_RUN_LIVE_TESTS=0
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY=
+LANGSMITH_PROJECT=kbqa-local
+```
+
+现有明文密钥必须在开发前轮换。真实密钥只存在于被 Git 忽略的 `.env`。LangSmith 会接收 Agent 输入、工具结果和运行轨迹，这是产品已确认的外部数据传输。
+
+开发环境 CORS 默认只允许 `http://localhost:5173` 与 `http://127.0.0.1:5173`，可通过显式配置增加本地来源，不允许通配符来源。
+
+## 17. 测试与验收
+
+### 17.1 开发方式
+
+本项目不使用 TDD。每个功能先按已批准设计实现，再补充并执行相应验证。测试不得使用 Chat 或 Embedding Mock。
+
+### 17.2 普通验证
+
+普通验证不进入真实模型路径：
+
+- Python 格式、lint 和类型/导入检查。
+- SQLite migration、repository、状态机和级联删除验证。
+- 文件类型、大小和路径安全验证。
+- 文本加载与分块验证。
+- SSE 编码和前端增量解析验证。
+- TypeScript、ESLint 和生产构建验证。
+
+普通测试使用独立临时 SQLite 和 Milvus Lite 文件，不接触开发数据。
+
+### 17.3 Live API 集成测试
+
+只有显式设置 `KBQA_RUN_LIVE_TESTS=1` 才运行 live 测试。测试启动真实 Uvicorn 进程，通过 localhost HTTP 请求真实 API，并使用真实 DashScope 与 LangSmith 配置。
+
+必须覆盖：
+
+1. 上传真实 PDF、Markdown 和 TXT fixture。
+2. 轮询直到后台真实 Embedding 完成，验证文档 indexed 且 chunk_count 大于 0。
+3. 创建会话并调用真实 `/chat/stream`。
+4. 验证 status、sources、token、done 事件顺序和来源关联。
+5. 发送依赖上一轮语境的追问，验证历史会话和新引用。
+6. 询问 fixture 中不存在的事实，验证资料不足响应。
+7. 重启 Uvicorn，验证文档、会话、消息和来源仍存在。
+8. 删除文档和会话，验证原文件、SQLite 关联记录和 Milvus 向量均被清理。
+
+模型输出测试只断言语义边界、引用存在性和结构，不断言固定措辞。
+
+### 17.4 Agent-browser 端到端测试
+
+使用 `agent-browser` 操作真实 Vite 页面和真实 FastAPI：
+
+- 上传文档并观察 pending/indexing/indexed 状态。
+- 新建会话并发送真实问题。
+- 验证研究阶段、流式文本增长和右栏来源。
+- 点击来源并验证完整 chunk 详情。
+- 发送多轮追问并刷新页面验证历史恢复。
+- 验证索引失败重试、删除确认、空状态和错误提示。
+- 在桌面三栏与窄屏抽屉视口各执行关键流程。
+- 保存关键状态截图作为验收证据。
+
+## 18. 参考资料
+
+- [LangChain v1](https://docs.langchain.com/oss/python/releases/langchain-v1)
+- [LangChain subagents](https://docs.langchain.com/oss/python/langchain/multi-agent/subagents)
+- [LangChain streaming](https://docs.langchain.com/oss/python/langchain/streaming)
+- [LangChain middleware](https://docs.langchain.com/oss/python/langchain/middleware/overview)
+- [Milvus schema design](https://github.com/milvus-io/milvus-docs/blob/v3.0.x/site/en/aiTools/schema_design.md)
+- [Milvus Lite](https://github.com/milvus-io/milvus-docs/blob/v3.0.x/site/en/getstarted/milvus_lite.md)
+
+## 19. 验收判定
+
+只有同时满足以下条件才认为首版完成：
+
+- 已在干净环境中通过 `uv` 与 `npm` 安装并启动。
+- 所有普通验证通过。
+- live API 测试真实调用 Chat 与 Embedding 并通过。
+- agent-browser 端到端流程通过并留存关键截图。
+- 上传、索引、双 Agent、SSE、引用、多轮历史、重启恢复和完整删除链路全部通过。
+- 代码中不存在 PostgreSQL/psycopg、LangChain 0.3.x Agent API、模型 Mock 或明文密钥。