merge: integrate dev into main

2026-10-16 20:33:13 +08:00
parent 460f120364 7ccb1f7fcb
commit 0f36f7403b
110 changed files with 10707 additions and 142 deletions
@@ -14,7 +14,50 @@ FastAPI + Pydantic
          |-- 来源获取 -> 人工核验 -> 文本切分 -> 生成向量 -> 发布版本
 ```

-当前工程仅实现健康检查、知识条目新增/列表及问答占位接口；pgvector 扩展已在启动时启用，但未实现向量字段、索引和 RAG。前端来源管理与实验页为静态原型。
+当前后端实现健康/数据库就绪检查、来源与文档管理、知识增删改查、分页筛选、人工审核、历史快照、认证会话/角色权限、文本/向量快照及独立关键词/向量/RRF 检索；问答仍为占位接口。数据库由 Alembic 显式迁移并启用 pgvector，DeepSeek RAG 待明确恢复后实现。前端已接入登录/注册、个人中心、账户设置、会话恢复、路由守卫和角色菜单；实验页不伪造数据，文档、审核、完整分页、浏览器 Cookie 与 PostgreSQL 联调仍需验收。
+
+## 阶段 2 数据边界
+
+- `sources` 登记来源名称、HTTP(S) 网址和备注；`documents` 登记所属来源、正文、分类与采集时间。
+- `knowledge_items` 保留基础版本全部字段，新增可选来源/文档引用、采集时间、人工审核字段、版本和软删除状态。历史条目不强行补造来源或时间。
+- `audit_events` 在同一事务中保存创建、修改、审核、失效、删除和迁移导入事件；知识快照包含当时关联的来源与文档。
+- `version` 用于内容并发控制，PATCH/审核/DELETE 必须匹配读取版本；ORM 版本检查处理并发写入冲突，引用操作对来源/文档加行锁，避免与修改和删除交错。
+- 修改知识或关联依据会撤销当前审核结论。未来正式检索必须同时限定 `verification_status = 'verified'` 和 `is_deleted = false`；当前管理列表不承担检索或索引发布功能。
+- 文档版本通过递增版本号及完整历史快照留存；`chunks`、Embedding 模型版本与索引发布版本在检索阶段单独实现，不能把记录版本当作已实现索引切换。
+- 旧库首次升级自动接管基础表，保留条目与导入快照。没有完整审核记录的旧 `verified` 状态回到待审核。启动不自动迁移，缺失或不匹配的版本会明确报错。

 ## 安全边界
-当前无认证与权限控制，仅供本机开发；正式部署前须补充登录鉴权、接口限流、数据库迁移、密钥管理、日志脱敏、CORS 收敛和 HTTPS。
+新增 `users`、`auth_sessions` 与 `auth_rate_limits`。Argon2id 保存密码哈希，随机 Cookie 会话只保存摘要，角色逐次由数据库校验。来源白名单与会话 CSRF 保护写入；改密撤销所有会话。管理资源和检索历史均限管理员，公开检索只返回已核验资料。具体字段、来源、Cookie、预算和迁移见 [认证接口契约](AUTH_API.md)。
+
+当前仍供本机开发与联调；完整生产部署、网关限流、访问审计、邮箱验证、账号恢复以及浏览器端权限流程验收仍待后续工程验收。
+
+## 关键词检索基线（T06）
+
+`POST /api/retrieval` 在同一 SQL 语料快照中筛选有效的已审核知识，读取出处和记录版本，再进行固定中文分词、标题加权 BM25 排序和原文片段截取。语料指纹覆盖本次实际参与排序的内容与出处版本；算法标识和参数独立记录。管理页的字面子串筛选继续用于管理，正式关键词基线使用专用检索接口。
+
+新增 `retrieval_runs` 保存查询、模式、语料指纹和完整结果快照，支持分页读取及按 UUID 复核。零命中如实记录；当前依据修改后失效不会改写历史，但后续检索必须重新检查审核与父记录状态。响应耗时是本次真实读取、分词、排序及片段生成耗时，不含写日志或模型调用。
+
+关键词基线仍按知识条目检索，显示片段最长 240 字符；独立的持久化 chunks 和文本索引版本见下方。该接口不读取 chunks；chunk 与向量/RRF 的独立接口见后文。全语料计算明确限制条目数及总字符数，超限报错，适用于首批小规模资料与后续对照实验准备，不能当作生产检索性能结论。
+
+
+## 切分与索引版本（T05）
+
+`index_versions/chunks` 保存已审核语料的原文切分、出处与版本、参数、内容哈希及语料指纹。构建先保存 ready 快照，不切换当前发布；`index_state` 管理发布指针、代数与目录修订号，发布同一事务更新前后状态并追加 `index_publications`。
+
+目录写入、构建与发布共用状态行锁，目录写入先于父记录锁获取该锁并递增修订号。发布核对代数、修订号和当前语料指纹；失败回滚，保留旧版本。目录变化后旧指针仍可追溯，但 is_current=false，不可据此绕过正式审核。历史快照不会被改写。接口均限管理员并沿用 Cookie/CSRF，完整边界见 [INDEX_API.md](INDEX_API.md)。
+
+这只是后续索引的文本版本基础，关键词基线行为不变；没有生成向量或宣称已实现 ANN/混合检索。同步构建和全局写锁面向当前有限语料，后续异步/增量发布须重新设计并验证并发协议。
+
+
+## 向量与 RRF 检索（T07）
+
+文本发布之后，固定 Embedding 空间的完整向量快照通过独立代数发布，精确余弦检索只使用当前审核与发布版本。编码在发布锁外进行，完成后重新核对语料、空间及发布状态，失败保留旧版本。运行与空间身份见 [VECTOR_API.md](VECTOR_API.md)。
+
+新增 chunk 正文 BM25 与等权 RRF；两路限定同一文本/向量快照和分类，固定 k=60，先各取 candidate_k 再融合。保存完整候选排名、原始分数、贡献、切分/分词/BM25/模型配置及出处。旧条目关键词模式保留，评测不能混同两种证据单元。两路排序至检索记录写入共用当前性锁，面向最多 2000 chunks 的同步精确计算。字段、失败及回滚边界见 [HYBRID_API.md](HYBRID_API.md)。RAG、ANN 与真实领域质量验收仍待后续阶段。
+
+
+## RAG 上下文与兼容请求准备（T08）
+
+`rag_contexts` 通过检索记录外键保存证据、出处/版本、选段/排除原因、提示词版本和 OpenAI 兼容 Chat Completions 请求体。准备时在发布锁内复核审核资料及文本/向量快照；已过期检索必须重查。输入与证据作为 JSON 数据放在 user message，固定规则独立保存，不允许客户端提交任意上下文或凭据。字符预算不是模型 token 校验。
+
+准备/历史接口限管理员，写入要求会话 CSRF；历史保持当时快照。当前提供纯响应格式/引用解析，不调用生成模型；`prepared_request/model_called=false` 不能视为实际回答或领域实验。真实服务接入及模型 token 预算验证等待后续阶段。字段、权限、迁移和回滚见 [RAG_CONTEXT_API.md](RAG_CONTEXT_API.md)。
@@ -0,0 +1,67 @@
+# 认证与角色权限接口（Issue #5）
+
+本分支实现 [Issue #5](https://gitea.kronecker.cc/saint/border-red-post-nalati/issues/5) 的七个接口。认证分支 `feat/backend-auth-sessions` 基于 PR #6 的已验证后端提交，迁移依次为 `0002_catalog → 0003_retrieval_runs → 0004_auth_sessions`；PR #6 仍须独立审阅，本分支没有自行合并它。
+
+## 启动与管理员初始化
+
+在 `backend/` 安装更新依赖并执行 `alembic upgrade head`，再运行：
+
+```bash
+python -m app.manage create-admin --username local_admin
+```
+
+命令通过终端隐藏输入和确认密码，不接受密码参数，不创建默认账号；已有用户名不会被升级为管理员或覆盖密码。生产密码请使用独立长口令，不把账号、密码、Cookie 或响应保存到仓库。迁移只新增表，不预置任何用户。
+
+默认 `AUTH_COOKIE_SECURE=true`，必须通过 HTTPS 使用会话。本机 HTTP 联调时可在未入库的 `backend/.env` 显式设置 `APP_ENV=development` 和 `AUTH_COOKIE_SECURE=false`，保持服务只绑定回环地址。其他环境拒绝关闭 Secure；非开发/测试环境的认证与 CORS Origin 必须均为 HTTPS。不要把本机例外带到部署环境。
+
+`AUTH_ALLOWED_ORIGINS` 独立控制写请求的来源，默认允许 `localhost/127.0.0.1` 的 5173、8000 端口；`CORS_ORIGINS` 控制前端跨域读取。两者均须填写完整 `scheme://host:port`，不含路径/尾斜杠/通配符。部署时按实际地址同时收敛这两项。代理层仅信任受控代理，不能任意接受外部转发 IP 头。
+
+## 接口契约
+
+| 接口 | 请求 | 成功响应与权限 |
+|---|---|---|
+| POST `/api/auth/register` | `username/password`，可选 `nickname/email` | 201 用户资料；仅创建 `user`，不自动登录 |
+| POST `/api/auth/login` | `username/password` | 200 用户资料及 `csrf_token`；设置会话 Cookie |
+| POST `/api/auth/logout` | 无正文 | 204；要求当前会话和 CSRF，作废该会话并清除 Cookie |
+| GET `/api/auth/me` | 无 | 200 用户资料及当前 `csrf_token`；要求有效会话 |
+| PATCH `/api/users/me` | `nickname` 和/或 `email` | 200 当前用户资料；会话与 CSRF 必需 |
+| POST `/api/auth/change-password` | `current_password/new_password` | 204；验证当前密码后撤销该用户全部会话并清除 Cookie，须重新登录 |
+| GET `/api/admin/users` | `limit` 默认/最大 100，`offset` 默认 0 | 200 用户数组，按 ID 升序；仅 `admin` |
+
+所有输入拒绝未知字段。注册和资料修改均不接受 `role/id/password_hash`，不能修改他人资料或用户名。用户名去首尾空白并转小写，须为字母开头的 3–32 位 ASCII 字母、数字或下划线。新密码为 15–128 字符，不修剪、不截断；旧密码只作校验。昵称最长 80 字符且不能含控制字符；邮箱须为合法地址，最长 254 字符。昵称/邮箱的空字符串或 `null` 用于清空；邮箱尚未验证，不能用于登录、找回密码或唯一身份判定。
+
+用户资料为 `{id, username, nickname, email, role, created_at}`；登录和 `/me` 额外返回 `csrf_token`。响应不包含密码哈希、会话 Cookie 值或内部凭据版本。示例中的 ID、时间和名字均为占位：
+
+```json
+{
+  "id": 1,
+  "username": "example_user",
+  "nickname": null,
+  "email": null,
+  "role": "user",
+  "created_at": "2026-10-16T00:00:00Z",
+  "csrf_token": "<由服务端返回的当前会话 CSRF 值>"
+}
+```
+
+错误使用 `detail`：参数 422、用户名冲突 409、登录错误/会话失效 401、权限/来源/CSRF 错误 403、当前密码错误 400、认证请求过多 429（`Retry-After: 300`）。参数错误不回显输入值，避免原样返回密码。认证及其他 `/api/` 响应均使用 `Cache-Control: no-store`。
+
+## Cookie、CSRF 与授权
+
+- Cookie 名 `nalati_session`，HttpOnly、Secure（默认）、SameSite=Lax、Path=/、不设置 Domain。服务端生成 256 位随机会话标识；数据库仅保存其 SHA-256 摘要、用户、凭据版本及到期时间。固定有效期 `AUTH_SESSION_SECONDS` 默认 28800 秒，可配置 300–604800 秒，不自动续期。
+- 登录轮换本浏览器旧会话；退出仅撤销当前会话；改密通过用户行锁、凭据版本递增与删除全部会话使旧凭据立即失效。授权每次从数据库读取当前角色，不信任前端角色或 Cookie 内的角色声明。
+- 登录/注册即检查精确匹配的 `Origin`，缺失或不可信均拒绝，避免登录 CSRF。已认证的 POST/PATCH/DELETE 等写请求还须带 `X-CSRF-Token`，值来自登录或 `/me`。该值由当前随机 Cookie 经独立 HMAC 派生，不能跨会话复用。后端不从请求正文、URL 或客户端角色获取权限。
+- `knowledge`、`sources`、`documents` 的全部读写及历史、管理员用户列表、检索历史列表/详情均要求 `admin`。因此旧匿名知识管理调用现在返回 401，普通用户返回 403。健康检查、公开的已核验关键词检索和当前占位问答保持公开；正式问答、实验接口接入时须重新明确各自授权。
+- 登录及注册共用每客户端地址 30 次/5 分钟预算；登录另有规范用户名 10 次/5 分钟预算，成功/失败都计数。计数通过 PostgreSQL 原子更新，跨进程/重启有效；仅保存带类型前缀的摘要，旧预算在下一次认证请求时清理。此处为基础防暴力尝试，不代替部署网关限流与监控。
+
+前端 `src/services/auth.ts` 和 `src/services/session.ts` 提供真实 Cookie 请求封装：CSRF 只存内存，刷新后通过 `/me` 恢复；知识写入也使用同一封装。`dev` 已提供登录、注册、个人中心、账户设置、管理员用户列表与路由守卫；导航菜单按当前角色隐藏管理员入口。账户资料更新与改密均调用真实接口，前端的新密码规则与后端一致为至少 15 个字符。浏览器端 Cookie、CORS 和 PostgreSQL 联调仍须在目标部署环境验收，不能由静态构建替代。
+
+## 验证与回滚
+
+在 `backend/` 执行 `ruff check .`、`ruff format --check .`、`pytest -q`；在 `frontend/` 执行 `npm run build`。测试使用隔离 PostgreSQL 和占位账号，覆盖权限拒绝、CSRF、输入越权、哈希、轮换/撤销/过期、改密、重启后会话恢复与退出持久化、预算、迁移及既有检索回归。测试库不代表 Docker 或浏览器验收。
+
+备份后可配合旧后端执行 `alembic downgrade 0003_retrieval_runs`，删除用户、会话与认证预算表，保留知识和检索历史；账号与哈希恢复依赖备份。降级会撤除授权边界，旧服务只能按其原开发范围使用，不应用于公开部署。继续降至 `0002_catalog` 还会删除检索历史。
+
+尚未实现邮箱验证、找回密码、MFA、角色管理 API、会话管理页面、访问审计和完整生产部署；没有把这些功能标记为完成。
+
+实现依据：[argon2-cffi API](https://argon2-cffi.readthedocs.io/en/stable/api.html)、[OWASP 密码存储](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)、[OWASP 认证](https://cheatsheetseries.owasp.org/cheatsheets/Authentication_Cheat_Sheet.html)、[OWASP CSRF 防护](https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html)。本项目使用 Argon2id（19 MiB、2 次迭代、并行度 1）；会话与来源策略以本接口契约及代码为准。
@@ -14,3 +14,45 @@

 ## ADR-005 更新策略
 状态：设计确定、尚未实现。新文档版本后台生成向量，完成后原子发布；失败保留旧索引。
+
+## ADR-006 阶段 2 知识管理
+
+状态：已通过 PR #4 合入 `dev`。采用来源、文档、知识条目和追加式事件日志；记录版本用于并发控制，快照用于追溯。所有删除均为软删除，被有效记录引用的父记录禁止删除。依据或正文修改即回待审核；核验通过必须有来源链接、采集时间、核验人和说明。保留旧版知识创建请求及列表数组结构，新页面使用独立分页接口。当前为本机人工审核流程，认证身份、向量切分和索引发布仍属后续阶段。
+
+## ADR-007 显式迁移与旧数据保留
+
+状态：已通过 PR #4 合入 `dev`。以 Alembic 取代应用启动时的 `create_all`。基础迁移接管旧知识表，新增字段和表通过增量迁移完成；不推测旧数据采集时间。旧审核结论缺少完整记录时保留原快照并转待审核。迁移回滚需先备份，新增历史与审核元数据无法通过降级完整保留。
+
+## ADR-008 可复核的中文关键词基线
+
+状态：分支实现，待审阅。采用固定 Jieba 搜索分词及关闭 HMM 的词典模式，加入项目名称词，并使用固定停用词表。选择标题重复权重 2、正文权重 1 的 BM25 正值平滑 IDF 变体，不称为 BM25F；查询词去重，同分按知识 ID 排序。参数、分词标识、实际语料指纹及出处版本随每次结果保存，方便冻结后续实验配置。分词接口参考 [Jieba 官方说明](https://github.com/fxsjy/jieba)，BM25 基础参考 [Stanford IR 教材](https://nlp.stanford.edu/IR-book/html/htmledition/okapi-bm25-a-non-binary-model-1.html)；具体平滑公式与权重以本仓库实现和手算测试为准。
+
+当前检索单元为已审核知识条目，在设置的容量内按请求计算，不提前实现向量切分/索引更新；超过容量明确失败。`retrieval_runs` 仅记录当时结果，不代表该条目之后仍然获得审核批准。网络搜索、模型选择和真实论文实验保持原阶段边界。
+
+
+## ADR-009 服务端会话与最小角色边界
+
+状态：Issue #5 分支实现，待审阅。使用 Argon2id 密码哈希、数据库保存摘要的随机 Cookie 会话，以及独立 CSRF 请求头与显式 Origin 白名单；不把角色或会话凭据放入浏览器持久存储。普通注册只能创建 user，管理员仅由本机隐藏密码输入命令创建。知识/来源/文档管理及检索历史限 admin，公开检索继续只使用已核验依据。完整契约与实现依据见 [AUTH_API.md](AUTH_API.md)。
+
+为改密和会话撤销使用用户行锁与凭据版本，认证预算使用数据库原子计数；不依赖单进程内存限流。现有前端写请求同步 Cookie/CSRF 封装，页面和路由联调仍待前端完成。本分支叠加 PR #6，后续审阅需关注迁移顺序及匿名管理调用变为 401 的行为变化。
+
+
+## ADR-010 切分快照与显式发布
+
+状态：T05 分支实现，待审阅。先对当前有效审核语料构建带原文偏移/哈希/出处的 chunks，再以独立的发布请求切换指针。固定 Unicode 字符窗口配置留存在版本中，关键词接口继续按条目运行，防止未经评估就改变实验口径。
+
+为当前小规模语料选择统一数据库行锁：应用目录写入、构建、发布串行，发布同时校验代数、目录修订和语料指纹；失败回滚全部更新，旧版本保留为历史。任何成功目录写入保守地使旧索引过期，历史不能视作当前有效依据。实现、容量与后续并发扩展边界见 [INDEX_API.md](INDEX_API.md)。
+
+
+## ADR-011 同粒度 chunk 排序与等权 RRF
+
+状态：后端分支实现，待审阅。基于已合入的向量快照，新增正文 BM25 的 chunk 基线，与向量模式使用同一文本发布及分类范围；保留条目关键词接口作为独立口径。两路候选各限 candidate_k，使用从 1 起的排名、固定 k=60、等权倒数排名融合，缺席一路贡献为零。保存候选全排名、原始分数、两路贡献和配置，确保实验准备可复核；不把 BM25 与余弦原始分数直接相加。
+
+公式与常数参考 [RRF 原论文](https://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf)，本项目尚未依据核验领域问题集调优。同步精确计算限制 2000 chunks，固定配置、版本一致性、历史兼容与回滚见 [HYBRID_API.md](HYBRID_API.md)。
+
+
+## ADR-012 先固定证据与 Chat Completions 契约
+
+状态：T08 分支实现，待审阅。用户要求模型选择暂缓，先按 OpenAI 通用格式开发。选择纯 `model/messages` 请求构造及非流式单候选响应解析，不配置服务、凭据或默认生成模型；参数兼容通过显式 role/token 字段选项表达，不暗中降级。供应商可替换，真实调用验证另行开展。
+
+上下文只接受服务端 chunk 检索记录，在当前性锁内复核证据，完整保留原文和出处；重叠和超预算片段明确排除，不截断正文。引用校验只能确认编号存在，不能证明事实受到支持。准备快照通过独立表持久化，不把协议 fixture 或准备结果标记为真实模型回答。完整边界见 [RAG_CONTEXT_API.md](RAG_CONTEXT_API.md)。
@@ -0,0 +1,36 @@
+# 前端页面与功能设计（阶段一）
+
+## 设计目标
+
+前端不是展示虚构文旅结论的门户，而是让团队能看清资料从来源登记、文档采集到知识审核的状态。所有列表均以接口返回为准；接口不可用时展示明确的连接状态，不使用模拟数据兜底。
+
+## 页面结构
+
+| 页面 | 已实现 | 下一步功能 | 验收标准 |
+|---|---|---|---|
+| 智能问答 | 输入、会话、来源链接、请求中与不可用提示 | 检索命中片段、追问、会话清空 | 每条回答显示后端状态和可打开来源 |
+| 知识库管理 | 新建条目、搜索、状态统计、来源跳转 | 审核抽屉、编辑、版本冲突提示、历史记录 | 通过审核前必须有来源网址与采集时间 |
+| 来源与更新 | 登记来源、检索来源、来源状态说明 | 文档列表、关联创建、编辑/软删除、历史记录 | 不自动抓取；来源登记不等同于事实核验 |
+| 实验评估 | 指标边界与对照方案说明 | 问题集、人工评分、结果导出 | 不展示未经真实实验产生的数值 |
+
+## 核心操作链路
+
+1. 资料负责人登记来源：填写名称、网址和可靠性备注。
+2. 采集文档：必须选定一个来源，记录正文、分类和真实采集时间。
+3. 前端创建知识条目：关联文档或填写可访问的来源网址，默认状态为 `pending`。
+4. 审核人核验：填写审核说明；仅在来源网址和采集时间齐全时可标为 `verified`。
+5. 检索阶段只使用已核验内容；问答页展示来源链接与“原型阶段”提示。
+
+## 交互与状态规范
+
+- 提交按钮在请求期间禁用，完成后刷新对应列表。
+- 接口错误显示后端返回的业务信息；网络错误提示检查 FastAPI 和 PostgreSQL。
+- 删除采用后端软删除；前端须在删除前显示关联文档/知识条目可能阻止删除的说明。
+- 并发修改以接口 `version` 为准；返回 409 时提示刷新列表后重试，禁止静默覆盖。
+- 移动端优先展示表格的标题、状态和主要动作，其他字段通过横向滚动查看。
+
+## 前端与后端边界
+
+- 前端不决定资料真实性、不生成审核结论，也不伪造统计结果。
+- 前端仅调用 `/api/health`、`/api/chat`、`/api/knowledge`、`/api/sources` 和后续 `/api/documents`；鉴权接入后统一由 API 层处理。
+- 网页抓取、Embedding、向量检索与定时更新属于后端后续阶段，当前页面只说明其规划状态。
@@ -0,0 +1,67 @@
+# Chunk 关键词与 RRF 混合检索
+
+本阶段基于已合入 `dev` 的文本/向量发布，增加可独立调用的 chunk BM25 和 RRF。既有条目关键词接口继续保留。三个 chunk 模式使用相同的当前文本版本、原文 chunk 与分类范围；比较时应固定发布版本、分类和 `top_k`，同时记录混合检索的 `candidate_k`。
+
+| 接口 | 请求 mode | 排序/证据单元 | 前置条件 |
+|---|---|---|---|
+| `POST /api/retrieval` | `keyword` | 知识条目，标题权重 2、正文权重 1 | 当前有效审核语料 |
+| `POST /api/retrieval/chunks` | `keyword_chunks` | chunk 正文 BM25，标题不参与打分 | 当前有效文本发布；无需模型或向量发布 |
+| `POST /api/retrieval/vector` | `vector` | chunk 精确余弦 | 当前有效文本/向量发布，运行模型空间匹配 |
+| `POST /api/retrieval/hybrid` | `hybrid` | 同一批 chunk 的两路 RRF | 与向量模式相同 |
+
+`mode` 可省略，由接口固定；传入其他模式或未知字段返回 422。公开检索无需登录；历史分页及详情继续限管理员。问答接口仍为占位，当前响应不生成 LLM 答案。
+
+## 请求与排名
+
+```json
+{"query":"合成资料中的交通查询入口","mode":"hybrid","top_k":5,"candidate_k":50,"category":"交通"}
+```
+
+- `query` 去除首尾空白后 1–500 字符，`top_k` 默认 5、范围 1–20，`category` 可省略。chunk 关键词请求不接收 `candidate_k`。
+- 混合检索每路最多取 `candidate_k` 条候选，默认 50、范围 1–200，并须不小于 `top_k`。这是固定排名后的候选截断，不会改变文本或输入 token。最终从候选并集返回最多 `top_k` 条。
+- chunk BM25 只对正文分词。沿用固定 Jieba 0.42.1 搜索分词、NFKC/casefold、HMM 关闭、项目词与 `zh-small-v1` 停用词表；查询词去重，`k1=1.2`、`b=0.75`，正值平滑 IDF。语料长度和词频在分类过滤后的全部 chunks 上计算，只将正分候选纳入关键词一路。标题仅作为出处字段。
+- 向量一路复用精确余弦排序，同样先按分类筛选，不设置相似度阈值。负分和零分仍可能进入候选，分数不是事实置信度，`status=ok` 只表示存在排序结果。
+- 两路先按各自原始分数排序；同分按 `knowledge_id, chunk_ordinal, chunk_id` 升序，排名从 1 开始。RRF 使用等权、固定 `k=60`：`score(c) = sum(1 / (60 + rank_leg(c)))`。不在某路候选列表中的 chunk，该路贡献为 0。原始 BM25 和余弦分数不直接相加；融合分数同分沿用相同 ID 次序。排序与日志使用未预先四舍五入的分数。
+- 融合以 chunk ID 去重。同一知识的不同片段（含重叠片段）保留各自排名和原文偏移，不做条目折叠或多样性重排。条目基线与 chunk 模式的分数、命中数、语料数及评测单元不同，不能直接混算指标。
+
+RRF 方法与常数参考 [Cormack、Clarke、Büttcher，SIGIR 2009 原论文](https://cormack.uwaterloo.ca/cormacksigir09-rrf.pdf)。这里把 `k=60` 作为首版可复现配置，并未通过本项目领域问题集调优。
+
+## 响应与复核
+
+全部模式保留原文、字符偏移（左闭右开）、知识/文档/来源 ID 及版本、URL、排名与耗时。chunk 关键词和混合响应另含：
+
+| 字段 | 含义 |
+|---|---|
+| `mode` | `keyword_chunks` 或 `hybrid`，可用于历史类型判别 |
+| `text_index_version_id`, `text_generation`, `catalog_revision` | 本次文本发布和目录修订 |
+| `corpus_fingerprint` | 整份已审核语料的指纹，分类筛选不改变它 |
+| `corpus_size` | 分类范围内参与两路打分的 chunk 数 |
+| `total_hits` | 关键词模式为全部正分 chunk 数；混合模式为两路截断后的候选并集大小，可能大于返回条数 |
+| `query_terms`, `config.lexical`, `config.chunking`, `config.tie_break` | 实际分词、BM25 参数、切分配置、稳定排序规则 |
+| `elapsed_ms` | 语料检查、模型编码（混合模式）、排序及响应组装耗时；不含记录写入及网络时间 |
+
+混合模式还保存：
+
+- `vector_version_id`、`generation`：向量发布版本与代数；`config.space` 包含完整模型 revision、维度、token 预算、指令、实现/池化/归一化与权重格式身份；与向量契约一致。
+- `config.rrf_k/weights/candidate_k/vector_scorer`：融合与候选预算，不允许请求覆盖固定算法参数。
+- `lexical_candidates/vector_candidates`：两路完整的截断候选列表，每条为 `chunk_id/rank/score`，即使未进最终前 `top_k` 也保留。
+- `lexical_total_hits/vector_total_hits`：截断前正分关键词候选数、分类范围内向量候选总数。
+- 命中的 `lexical_rank/lexical_score/vector_rank/vector_score` 和两路 `*_contribution`：缺席的排名/原始分数为 `null`、贡献为 0。`score` 等于两路贡献之和。
+
+结果完整写入现有 `retrieval_runs`，历史接口联合类型支持四种 mode，不需要新增迁移，当前 Schema 仍为 `0006_vectors`。修改依据后历史保持原样，只代表当时快照；重查须通过当前性验证。原始查询和运行记录属于数据库数据，不应提交到仓库。
+
+## 一致性、失败与容量
+
+混合检索先检查发布版本与模型空间，然后提交只读事务释放发布锁，再真实编码查询；编码后重新获取目录/向量状态锁，复核目录修订、文本/向量代数、审核指纹、实际 chunks、完整向量集及空间身份。变化时 409，且不保存部分结果。两路排名及写入检索历史在同一个受锁保护的事务内完成。
+
+关键词一路没有命中或没有分词时，混合模式明确保留空候选列表，可仅有向量一路；纯关键词模式没有可检索词则 422。分类无资料或空的有效发布返回 `no_evidence`。模型 token 超限/输出校验失败返回 422，运行环境不可用或编码忙返回 503；模型失败不降级成一份声称成功的混合结果。
+
+两种新接口均沿用向量阶段最多 2000 chunks、5000 条知识/200 万字符的整体核验预算，超限明确 503。只在分类范围内打分，但当前性及容量检查针对整份发布。文本快照允许的 20000 chunks 不等同于本接口容量。同步精确排序及 BM25 在锁内运行，会短暂串行化目录写入；当前没有 ANN、后台队列或生产吞吐量结论。
+
+运行依赖、固定缓存、默认关闭的本地模型、构建/发布步骤见 [VECTOR_API.md](VECTOR_API.md)。前端新增 `services/hybrid.ts` 两个调用及历史类型；模式切换页面、Docker/浏览器端和真实领域验收仍待交接。
+
+## 验证与回滚
+
+轻量测试使用明确的合成正文及坐标 fixture，覆盖手算 BM25/RRF、原始分数与融合的独立性、候选边界、两路缺席、稳定排序、chunk 偏移、分类、权限、历史、失效/破坏快照、编码期间版本竞争、无部分日志及容量拒绝。真实模型专项沿用 `test_vector_runtime.py` 的显式 opt-in，增加固定 BGE small 的 HTTP 混合检索和进程重启后的两路排名/历史复核。运行命令见 [VECTOR_API.md](VECTOR_API.md)。这些用例验证实际模型/数据库/API 贯通，合成问题不代表领域质量或论文实验结论。
+
+撤回本功能代码即可撤回两个新增接口；数据库无需降级。旧后端历史响应模型不认识 `keyword_chunks/hybrid`，回滚时应限制旧历史端点或先以备份保留新模式记录，避免把新记录交给旧模型解析；不要为回滚而无备份删除检索历史。
@@ -0,0 +1,81 @@
+# 文本切分与索引版本接口（T05）
+
+本阶段保存可复核的已审核语料切分及发布指针，为后续检索索引提供版本边界。这里的“索引版本”是文本语料快照，不包含 Embedding、pgvector 向量字段/ANN 索引或 RRF。现有 `POST /api/retrieval` 仍运行原关键词基线，不读取这些 chunks；不能把本阶段称为向量检索已完成。
+
+## 依赖、迁移与权限
+
+分支 `feat/backend-chunk-index-versions` 叠加待审 PR #7（认证），并继承 PR #6（关键词）。三项须分别跟踪审阅；本分支不自行合并其他请求。升级时停止旧后端实例，安装依赖、备份并执行 `alembic upgrade head`，再启动新实例。所有实例必须使用当前版本，才能让目录写入遵守同一发布锁。
+
+新增迁移 `0005_chunk_indexes`，依赖 `0004_auth_sessions`，创建：
+
+- `index_versions`：切分配置、语料指纹、目录修订号、条目/chunk 数、构建人、构建时间及发布状态。
+- `chunks`：所属版本、知识 ID、从 0 开始的片序、原文起止偏移、正文、UTF-8 内容 SHA-256 与出处快照。
+- `index_state`：单例发布指针、发布代数 `generation`、目录修订号 `catalog_revision`。
+- `index_publications`：每次发布的前后版本、代数、操作人和时间；重复发布当前版本不会新增记录。
+
+迁移不改写既有知识、审核、用户、会话或检索记录，不创建初始发布版本。所有 `/api/indexes` 接口均要求 `admin`；POST 还必须携带有效 Cookie、明确 Origin 与 `X-CSRF-Token`，与 [认证契约](AUTH_API.md) 相同。
+
+## 构建与原文切分
+
+`POST /api/indexes` 创建一个 `ready` 版本，返回 201，不切换当前发布指针。请求可用默认值 `{}` 或：
+
+```json
+{"chunk_size": 500, "overlap": 80}
+```
+
+`chunk_size` 为 100–2000 个 Python Unicode 字符，默认 500；`overlap` 默认 80，非负且不得超过切分长度一半。自定义较短长度时也须指定兼容的重叠，例如 `{"chunk_size":100,"overlap":20}`。未知字段拒绝，不支持按类别单独发布。
+
+固定算法 `unicode-window-v1` 从知识条目原正文位置 0 开始（不是关联文档或原网页的偏移），以 `chunk_size-overlap` 前进，末片到正文结束即停止。保留空白、全半角、组合字符和 Emoji，不标准化或截断原文。`start_offset` 包含起点，`end_offset` 不包含终点；每片 `text == 原文[start_offset:end_offset]`。标题放在出处信息中，不拼进正文偏移。客户端若使用 JavaScript 字符串偏移，须注意其 UTF-16 索引与 Python Unicode 字符偏移的区别。
+
+- 语料条件与关键词基线共用：只读取未删除、审核及采集信息完整的 `verified` 知识，关联来源/文档须有效、归属及来源网址一致；pending/rejected 不进入构建。
+- 语料指纹与关键词基线使用同一规范 JSON/算法，涵盖实际正文、标题、类别、出处及知识/父记录版本；切分参数独立保存在 `config`。
+- 出处快照包含 `knowledge_id/knowledge_version`、可空 `document_id/document_version`、可空 `source_id/source_version/source_name`、`source_url/title/category`。以后原资料修改或失效，不改写旧 chunk 内容及出处。
+- chunk ID 在一个版本内由版本 UUID、知识 ID 与顺序确定；新构建使用新版本 ID。相同资料及参数可重现偏移/正文/内容哈希，但新旧版本的 chunk ID 不相同。
+- 本阶段同步构建，沿用最多 5000 条及标题/正文总计 200 万字符的语料限制，每版本另限 20000 个 chunks。超限返回 503；事务写入失败也完整回滚，不保留半个版本，不改变旧发布指针。
+- 可以构建空语料版本，以便所有依据撤回后发布空快照；这不表示存在可用知识。
+
+## 发布、过期与并发
+
+先通过 `GET /api/indexes/active` 读取当前代数，再提交：
+
+```text
+POST /api/indexes/{version_id}/publish
+```
+
+```json
+{"expected_generation": 0}
+```
+
+发布时锁定 `index_state`，检查代数、目录修订号及当前有效语料指纹；资料或审核已变化、代数过期均返回 409，要求重新构建或刷新。成功后同一事务把旧版本设为 `superseded`、新版本设为 `published`、切换指针、增加代数并追加发布记录。校验失败或写入失败保留此前全部发布状态。持有当前代数重复发布当前版本是无变化的 200；仍有效的历史版本可用最新代数重新发布，发布记录保留每次转换。
+
+知识、来源、文档的应用写入在修改父记录前持有同一状态锁，事务内将 `catalog_revision` 增加一次；失败写入一起回滚修订号。构建、发布和这些写入串行，避免校验到提交之间发生目录修改。为首批小规模资料选择此保守策略，长构建会暂时阻塞管理写入；尚无后台任务或大规模增量索引。
+
+任一成功目录写入都会使旧快照过期，包括尚未核验的新条目；此规则比只比较有效语料更保守。`GET /active` 同时核对修订号与实际语料指纹，返回：
+
+```json
+{"generation": 1, "catalog_revision": 2, "is_current": true, "active_version": {"id": "<版本 UUID>", "status": "published", "config": {"splitter":"unicode-window-v1","chunk_size":500,"overlap":80}, "...":"其余版本字段见 OpenAPI"}}
+```
+
+初始无发布时 `active_version=null/is_current=false`。资料变化后指针及历史保留，但 `is_current=false`；`published` 只表示仍是发布指针，不表示资料仍有效。历史 chunks 是当时的依据快照，不能绕过 `is_current` 直接用于后续正式检索。任何结果只描述该事务快照，之后的目录写入仍可让它过期。直接改库不属于支持的维护流程；额外指纹检查可发现绕过修订号的正文/出处变化，不能替代应用写锁。
+
+## 查询与交接
+
+| 接口 | 响应 |
+|---|---|
+| GET `/api/indexes` | 版本分页，构建时间降序，同时间按 ID |
+| GET `/api/indexes/active` | 发布代数、目录修订号、当前性与当前版本 |
+| GET `/api/indexes/publications` | 发布记录分页，代数降序 |
+| GET `/api/indexes/{version_id}` | 版本元数据 |
+| GET `/api/indexes/{version_id}/chunks` | chunk 分页；可按 `knowledge_id` 筛选，按知识 ID/片序排列 |
+
+分页沿用 `{items,total,page,page_size}`，默认 20、最大 100。版本元数据完整字段为 `id/status/config/corpus_fingerprint/catalog_revision/item_count/chunk_count/created_by/created_at/published_at`；`published_at` 是最近一次发布的时间，逐次时间保存在发布记录。版本及发布记录时间统一输出 UTC ISO 8601，避免数据库时区让重读结果出现不同表示。chunk 字段为 `id/index_version_id/knowledge_id/ordinal/start_offset/end_offset/text/text_sha256/provenance`。
+
+前端 `src/services/indexes.ts` 提供类型和调用封装，写入共用 Cookie/CSRF；未增加页面或假数据。接口新增需由前端按该契约接入、审阅并验收。独立 T05 Issue 因当前缺少 Gitea 写入认证仍待补建，本 PR 和任务板先保留实现与验证记录。
+
+## 验证及回滚
+
+验证包含真实 PostgreSQL 的原文重建与哈希、审核筛选、重复构建、过期拒绝、来源/文档更新、失败写入、发布历史、数据库锁竞争、失败构建/发布的真实约束回滚、迁移兼容及真实 HTTP 重启后指针/chunks 持久化。这里只使用占位资料，不是论文实验结果。Docker 和浏览器端验收保持待办。
+
+备份后配合旧后端执行 `alembic downgrade 0004_auth_sessions`，只撤回这四张表，保留用户、会话、知识及检索记录；索引历史与 chunks 恢复依赖备份。旧应用不可使用新版本数据库混跑。
+
+并发实现参考 [PostgreSQL 16 行锁说明](https://www.postgresql.org/docs/16/explicit-locking.html) 与 [SQLAlchemy FOR UPDATE](https://docs.sqlalchemy.org/en/20/core/selectable.html#sqlalchemy.sql.expression.Select.with_for_update)。
@@ -0,0 +1,79 @@
+# T07：本地 Embedding 与 CPU 资源评估
+
+本阶段从 `dev` 独立开发，交付可替换 Provider 和可复现的本地 CPU 评估工具。它不依赖待审 PR #6/#7/#8 的接口或数据库迁移；后续向量检索集成再组合这些基础。普通后端启动及普通自动化测试均不导入 PyTorch、不加载模型，也不要求模型下载。
+
+## 固定配置与边界
+
+| CLI 名称 | 官方模型 | 固定 revision | 维度 | Token 上限 | 权重格式 |
+|---|---|---|---:|---:|---|
+| small | BAAI/bge-small-zh-v1.5 | `7999e1d3359715c523056ef9478215996d62a620` | 512 | 512 | Safetensors |
+| base | BAAI/bge-base-zh-v1.5 | `f03589ceff5aac7111bd60cfc7d497ca17ecac65` | 768 | 512 | PyTorch，仅权重读取 |
+
+两者使用 CLS 输出、L2 归一化、CPU FP32；查询添加官方检索指令，正文不添加该指令。`EmbeddingSpec` 冻结模型/revision/维度/token 上限/查询指令/实现版本/权重格式，由规范 JSON 生成 `space_id`。不同空间必须分开保存和查询；目前只提供身份契约，数据库隔离约束尚待向量阶段实现。
+
+模型仓库均标注 MIT。基础版该修订只提供 `pytorch_model.bin`，显式使用 Transformers 的 `weights_only=True` 读取；不会自动回退未知格式或开启远程模型代码。公开模型下载使用 `token=False`，不要求或读取用户保存的 Hugging Face 凭据。默认只用本机缓存，CLI `--download` 才允许下载固定修订。
+
+`LocalEmbeddingProvider` 按批处理，默认 batch=8、CPU 线程=2；显式限制 batch 1–32、线程 1–4。输入先按真实 tokenizer 计数，包含查询指令和特殊 token；超过模型上限明确报错，不静默截断。输出检查数量、维度、有限数值和 L2 范数。字符切分长度不等于 token 数，后续接入 chunks 时须据此重新检查。
+
+## 输入与指标
+
+项目当前资料台账只有未核验的占位行，没有可用于正式选型的领域数据。本阶段自带 `backend/evaluation/synthetic_zh.json`，含 12 条明确标注“合成测试”的示例文本及 10 个问题，ID/相关文档标注在运行前固定。这些句子不描述那拉提真实事实，不写入应用数据库。
+
+评估保存输入文件 SHA-256、模型完整配置与空间 ID、运行库版本、实际命中 ID/分数、命中率、Recall@3 和 MRR@3。排序采用归一化向量内积，同分按文档 ID；数值不是正确率或置信度。命中率检查首位相关文档；Recall@k 为前 k 命中相关文档数/标注相关文档总数；MRR@k 为首个相关命中的倒数，未命中为 0。
+
+每项计时先按同一输入形状预热一次，然后记录 5 次及中位数：12 条语料编码、10 个查询批量编码、单个查询、8 条长文本批量编码。长文本均为相同的合成句子重复形成，360 字符/362 token，仅测试资源。包含分词、补齐、前向、归一化和结果转换；不包含网络、数据库、HTTP 或整个 RAG 延迟。初始化时间单独记录，可能包含缓存检查/下载与首次加载，不用于模型推理速度比较。Linux 峰值 RSS 是整个独立进程高水位，包含解释器、运行库和模型，不能当作仅权重大小。
+
+## 本机实测
+
+运行环境：Linux、Python 3.11.17、4 个逻辑 CPU、内存总计约 9.7 GiB，检查时可用约 5.0 GiB；GPU 驱动不可用，本轮仅用 CPU。PyTorch `2.14.1+cpu`、Transformers `5.20.0`、huggingface-hub `2.2.0`、NumPy `2.4.6`；每个模型用独立进程测量，线程 2、batch 8、每项 5 次。未记录用户名、主机名或本机个人路径。
+
+输入文件 SHA-256：`9f4762a10dc1502b871c84ccedf9fbbdbd93067b8318476a77c78aa14789b243`。
+
+| 模型 | 12 条正文批编码中位数 | 10 个查询批编码中位数 | 单查询中位数 | 8 条长文批编码中位数 | 峰值进程 RSS | 合成 Hit@1 / Recall@3 / MRR@3 |
+|---|---:|---:|---:|---:|---:|---|
+| small | 98.708 ms | 72.877 ms | 8.927 ms | 457.944 ms | 531.2 MiB | 0.90 / 0.90 / 0.90 |
+| base | 582.315 ms | 416.287 ms | 52.912 ms | 3016.157 ms | 865.5 MiB | 1.00 / 1.00 / 1.00 |
+
+两个模型在该负载下都能使用本机 CPU。small 在合成问题 q05（出处可靠性）把住宿条目 d07 排在首位，目标资料审核条目 d06 未进入前三；base 将 d06 排首位。这里保留失败结果，不修改数据以提高分数。两个模型的相似度分布不同，不能共用固定分数阈值。
+
+建议：资源优先的后端开发验证可先使用 small，保留 base 作对照。正式默认模型暂不冻结，先在已核验语料与独立问题集上比较相关性、无依据情形和实际端到端延迟。当前未测 GPU、并发服务、最大 token 负载或完整索引构建。
+
+这些是合成小样本的功能与资源结果，不是项目正式实验分数。不能据此断言真实文旅问答质量或生产尾延迟。应先用资料负责人核验后的语料及独立问题集复测，再固定默认模型；不能通过修改测试题迎合已观察的排名。
+
+## 复现（Linux，仓库根目录）
+
+可使用 `uv` 创建独立 Python 3.11 环境；或以等价 venv/pip 命令安装。依赖独立于 `requirements.txt`，不把 GPU 依赖或模型加入默认 API 启动流程。
+
+```bash
+task_eval_root=$(git rev-parse --absolute-git-dir)
+test -x "$task_eval_root/embedding-eval-venv/bin/python" || \
+  uv venv --python 3.11 "$task_eval_root/embedding-eval-venv"
+uv pip install --python "$task_eval_root/embedding-eval-venv/bin/python" \
+  --index-url https://download.pytorch.org/whl/cpu torch==2.14.1+cpu
+uv pip install --python "$task_eval_root/embedding-eval-venv/bin/python" \
+  -r backend/requirements-embedding-cpu.txt
+export HF_HUB_DISABLE_TELEMETRY=1 HF_HUB_DISABLE_IMPLICIT_TOKEN=1
+export HF_HUB_DISABLE_PROGRESS_BARS=1 TOKENIZERS_PARALLELISM=false
+export HF_HUB_DISABLE_XET=1
+(
+  cd backend
+  "$task_eval_root/embedding-eval-venv/bin/python" -m evaluation.local_embeddings \
+    --model small --download --cache-dir "$task_eval_root/embedding-model-cache" \
+    --output "$task_eval_root/embedding-evaluation/small.json"
+  "$task_eval_root/embedding-eval-venv/bin/python" -m evaluation.local_embeddings \
+    --model base --download --cache-dir "$task_eval_root/embedding-model-cache" \
+    --output "$task_eval_root/embedding-evaluation/base.json"
+)
+```
+
+后续离线复跑去掉 `--download`。可用 `--dataset` 指定同结构数据，文档/问题各最多 1000 条、文件最多 2MB；拒绝重复 ID、未知或重复的相关文档标注。报告不含输入文本，但实际问题/标签可能仍敏感，原始报告、运行输出、环境及模型缓存都应只留在本机 Git 元数据目录，不提交。参数错误或模型失败不会生成伪造的成功结果。
+
+普通后端验证仍是在 `backend/` 执行 `ruff check .`、`ruff format --check .`、`pytest -q`。轻量测试验证模型身份、非法输出、资源参数、token 拒绝、输入标注及手算排序指标，不需要模型包或联网；真实模型执行由上述独立 CLI 验证。
+
+## 下一步
+
+将 Provider 接入已发布的文本版本，完成 pgvector 存储与严格空间隔离、向量检索及 RRF，再使用真实审核语料评测。模型编码耗时应在发布锁外运行，发布前重新核对目录/语料版本；过期或失败时保留旧版本。当前没有新增向量数据库字段、检索 API 或论文结论。
+
+以上描述 PR #9 独立评估阶段的范围；后续向量存储与精确检索集成另见 [VECTOR_API.md](VECTOR_API.md)，不改变本页已记录的合成评估结果。
+
+依据：[BGE small 官方模型说明](https://huggingface.co/BAAI/bge-small-zh-v1.5)、[BGE base 官方文件](https://huggingface.co/BAAI/bge-base-zh-v1.5/tree/f03589ceff5aac7111bd60cfc7d497ca17ecac65)、[Transformers 模型加载参数](https://huggingface.co/docs/transformers/main_classes/model#transformers.PreTrainedModel.from_pretrained)、[PyTorch CPU 安装](https://pytorch.org/get-started/locally/)、[Hugging Face 固定修订下载](https://huggingface.co/docs/huggingface_hub/guides/download)。
@@ -0,0 +1,83 @@
+# RAG 证据与 OpenAI 兼容请求准备
+
+本阶段按用户要求先实现通用请求格式，生成模型选择和真实调用延期。协议采用非流式 Chat Completions：`model/messages`、单条 assistant 响应、可选用量；不绑定供应商、服务地址、密钥或具体模型。字段依据 [OpenAI 官方 Chat Completions 文档](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)。
+
+本阶段提供管理员上下文准备与历史接口、完整证据快照、固定提示词及纯响应解析器。`POST /api/chat` 仍保留原占位状态，尚未成为生成式问答接口；准备记录固定为 `kind=prepared_request, model_called=false`，不能作为实际模型回答、耗时、费用或领域实验结果。
+
+## 准备与读取
+
+| 接口 | 用途 | 权限 |
+|---|---|---|
+| `POST /api/rag/contexts` | 从服务端检索记录准备并持久化请求 | admin、明确 Origin、会话 CSRF |
+| `GET /api/rag/contexts?page=1&page_size=20` | 分页读取当时准备快照 | admin |
+| `GET /api/rag/contexts/{id}` | 按 UUID 读取单份快照 | admin |
+
+请求示例（ID、模型标识仅作格式示例，不表示已选择或调用模型）：
+
+```json
+{
+  "retrieval_run_id": "00000000-0000-0000-0000-000000000001",
+  "completion": {
+    "model": "deployment-model-id",
+    "output_tokens": 512,
+    "token_parameter": "max_completion_tokens",
+    "instruction_role": "system"
+  },
+  "max_input_characters": 10000,
+  "max_evidence": 5
+}
+```
+
+请求只接收服务端检索记录 UUID、组包配置和预算，不接收任意正文、提示词、URL、请求头或 API Key。来源必须是 `keyword_chunks/vector/hybrid` 的完整结果；条目级 `keyword` 返回 422，避免把条目与 chunk 的证据粒度混用。记录不存在返回 404，格式/预算越界返回 422。
+
+| 字段 | 约束 |
+|---|---|
+| `completion.model` | 必填，1–128 个字母/数字及 `._:/-`；只保存标识，不验证模型存在或服务可用 |
+| `output_tokens` | 默认 512，1–4096，写入所选输出预算字段 |
+| `token_parameter` | 默认 `max_completion_tokens`；显式选择 `max_tokens` 才生成旧兼容字段，两者不同时发送 |
+| `instruction_role` | 默认 `system`，也可显式使用 `developer`；须由后续实际服务兼容性测试确认 |
+| `temperature` | 可选 0–2；省略时请求体不发送，不预设所有模型都支持该参数 |
+| `max_input_characters` | 默认 10000，1024–24000；两个 message 的 content 字符数之和 |
+| `max_evidence` | 默认 5，1–10；保持检索排名顺序挑选证据 |
+
+组装的请求体为 `model`、两个文本 `messages`、`stream=false`、`n=1`、`store=false`、所选输出预算字段，及显式提供的 temperature。第一条消息只有固定规则，第二条是规范 JSON 的 `question/evidence` 数据。请求不包含鉴权或服务地址。这是明确的协议子集，不保证每个“OpenAI 兼容”服务都支持所有字段；后续接入须核对服务的角色、参数及模型限制，不做静默重试或字段回退。
+
+字符预算用于有限体积的准备工作，**不是模型 token 数或上下文窗口校验**。输出 token 上限同样不表示输入能被某个尚未选定的模型接受。真实发送前须按所选模型验证完整输入与输出预算，超限明确失败，不静默截断原文。
+
+## 证据、引用与不足规则
+
+准备时只从数据库读取检索结果，并重新核对当前有效审核语料、原文 chunks、文本发布 ID/代数、目录修订和语料指纹。vector/hybrid 还须匹配当前向量发布 ID/代数、完整向量集及空间身份。整个检查至保存过程沿用目录/发布锁，不重新编码、不加载 Embedding，也不调用生成模型。知识变化、文本或向量重新发布、缺失向量/原文、出处或检索记录不一致均返回 409，要求重新检索。
+
+按检索排名逐条处理完整 chunk，给被纳入的证据分配连续 `E1/E2/...`。保存知识/文档/来源 ID 与版本、来源 URL、标题/分类、chunk ID/序号、原文、字符偏移和 SHA-256、检索排名。对同一知识已选择片段的重叠区间排除后续片段；达到证据数上限或整体 message 字符预算时，排除相应片段并继续检查后续可容纳候选，不切割原文。
+
+每个排除项记录 chunk ID 及 `overlap/budget/evidence_limit` 原因。没有候选时返回 `insufficient_evidence/no_candidates`；全部候选超出预算时为 `insufficient_evidence/context_budget`。这两种情况均不生成 request_body，不能把空证据包交给后续模型。
+
+固定 `nalati-evidence-v1` 提示词要求：依据提供的证据回答，事实标注 `[E1]` 形式引用，不编造出处；不把问题、正文、标题或 URL 中的命令作为系统规则；资料不足或冲突时说明局限，无法可靠回答时使用固定不足说明。JSON 数据与固定指令分离只是结构约束，尚未通过真实模型的注入抵抗/领域质量实验。`prepared/candidates_available` 只表示有可组装片段，不表示这些片段在语义上足够支持答案。
+
+## 快照与复核
+
+响应保存为独立 `rag_contexts` 记录，引用原 `retrieval_runs`，不改写已有检索历史。响应包含：
+
+- `id/retrieval_run_id/retrieval_mode/query`、文本/向量发布 ID 和代数、目录修订、语料指纹。
+- `prompt_version`、实际 completion 配置、字符/证据预算、完整已选 evidence 和 excluded 列表。
+- `request_body` 及其规范 UTF-8 JSON 的 `request_sha256`；无证据时两者均为 null，input_characters 为 0。
+- `kind=prepared_request`、`model_called=false`、状态/原因和创建时间，不包含任何模型答案或调用成本。
+
+历史查询返回当时的完整快照，资料后续撤回也不会改写它。历史请求体不是当前发送授权；未来实际模型调用必须重新检查当前依据和发布状态，不能从历史端点取出旧包后直接认定仍有效。
+
+## 兼容响应解析
+
+`services/completions.py` 提供纯解析函数，当前不暴露可向数据库写入“模型回答”的导入接口，也没有 HTTP 模型客户端。它只接受 `object=chat.completion` 的单一 index=0 assistant 文本候选，拒绝流式 chunk、工具/函数调用、未知结束原因或畸形结构。
+
+- `finish_reason=length` 标记 incomplete 并丢弃部分答案；content_filter 或 refusal 标记 refused。
+- 正常 stop 响应必须有非空文本、至少一个已提供的 `[E#]` 引用；缺失、越界或错误编号拒绝。固定不足说明单独标记 insufficient_evidence。
+- 返回实际 response ID/model、引用列表和可选非负整数 token 用量；用量合计不一致时拒绝，不自行估算费用。
+- 即使引用结构通过，也只标记 `answer_candidate`。引用存在不能证明原文支持每个事实，事实支持度、冲突、时效及人工验收仍需后续阶段验证。
+
+测试使用明确的合成响应/坐标与 PostgreSQL，不冒充真实模型推理。供应商兼容、生成质量、真实 token 预算、超时/重试/限流和费用记录须在模型选择后另行验收。
+
+## 迁移、回滚与交接
+
+新增 `0007_rag_contexts`，启动前备份并执行 `alembic upgrade head`。表通过外键保留检索记录和创建账号关系，只有追加与查询 API，没有修改/删除 API。撤回本阶段时可备份后配合旧后端执行 `alembic downgrade 0006_vectors`；仅删除准备快照表，保留知识、账号、文本/向量发布与检索历史。恢复准备快照须使用备份。
+
+前端新增 `services/rag.ts` 调用与类型，不修改现有问答页面。实际部署环境、运行日志、凭据和真实请求数据不得提交仓库。生成模型接入按用户后续选择推进，当前没有待创建的密钥，也不因延期而反复询问。
@@ -4,13 +4,89 @@

 | 编号 | 模块 | 任务 | 负责人 | 状态 |
 |---|---|---|---|---|
-| T01 | 前端 | 验证 Vue 页面启动、补充截图 | 吉海燕 | 待办 |
-| T02 | 后端 | 验证 FastAPI `/docs`、`/api/health` | 范涵宇 | 待办 |
-| T03 | 数据库 | 启动 PostgreSQL 并验证知识入库 | 范涵宇 | 待办 |
+| T01 | 前端 | 验证 Vue 页面启动、补充截图 | 吉海燕 | 进行中（生产构建已通过；登录、账户设置与角色导航已合入，待浏览器 Cookie 联调） |
+| T02 | 后端 | 验证 FastAPI `/docs`、`/api/health` | 范涵宇 | 已完成自动化/真实 HTTP 验证；待目标 Docker 环境复核 |
+| T03 | 数据库 | 启动 PostgreSQL 并验证知识入库 | 范涵宇 | 已用隔离 PostgreSQL 完成迁移与回归；本机 Docker Compose 验收受阻 |
 | T04 | 文档 | 明确接口字段、知识来源审核规则 | 杨星萱 | 待办 |
-| T05 | 知识库 | 设计 sources/documents/chunks/version 表 | 范涵宇 | 待办 |
-| T06 | 检索 | 实现关键词检索基线 | 范涵宇 | 待办 |
-| T07 | 向量 | 评估 Embedding 并实现 pgvector | 范涵宇 | 待办 |
-| T08 | RAG | 集成 LLM 与来源展示 | 范涵宇 | 待办 |
+| T05 | 知识库 | 设计 sources/documents/chunks/version 表 | 范涵宇 | 已完成（迁移、发布快照和接口已合入；待 Docker 联调） |
+| T06 | 检索 | 实现关键词检索基线 | 范涵宇 | 已完成（已核验知识 BM25 与检索历史已合入） |
+| T07 | 向量 | 评估 Embedding 并实现 pgvector | 范涵宇 | 已完成（本地模型、精确向量和 RRF 已合入；待真实领域评测） |
+| T08 | RAG | 集成 LLM 与来源展示 | 范涵宇 | 暂缓（已确定 DeepSeek，待明确恢复外部模型调用授权） |
 | T09 | 实验 | 构建可核验问题集及评分规范 | 杨星萱 | 待办 |
-| T10 | 工程 | 补充测试、Alembic、鉴权与部署 | 范涵宇（主）、全员 | 待办 |
+| T10 | 工程 | 补充测试、Alembic、鉴权与部署 | 范涵宇（主）、全员 | 进行中（迁移、认证、CSRF 与自动化回归已完成；本机 pytest/Docker/部署验收待补） |
+
+## 2026-10-15 首次联调记录
+
+- 已创建本机 `backend/.venv`（Python 3.12）并安装后端依赖；该目录由 Git 忽略。
+- 已安装前端依赖，`npm run build` 通过。构建中发现并修复了问答来源 URL 可为 `null` 时的 TypeScript 类型不一致。
+- 已使用临时 Uvicorn 服务（关闭数据库生命周期初始化）验证 `GET /api/health` 返回 `200` 和预期状态数据，验证后服务已关闭。
+- 本机 Docker CLI 已安装，但 Docker Desktop 引擎无法启动，且 WSL 尚未处于可用状态。因此尚未执行 PostgreSQL 容器启动、知识条目新增/读取、默认生命周期启动和浏览器端联调。
+- 后续操作：重启 Windows 后启动 Docker Desktop；确认 `docker version` 能显示 Server 信息，再在项目根目录运行 `docker compose up -d db`，随后继续 T02、T03 和 T01 的剩余验收。
+
+## 2026-10-15 后端阶段 1–2 分支验收
+
+分支：`feat/backend-knowledge-management`。以下为分支验收结果，须经既定审阅流程合入后再关闭任务；不覆盖前述其他环境的历史记录。
+
+| 范围 | 已完成的验证 | 剩余事项 |
+|---|---|---|
+| T02 | 默认生命周期真实启动 Uvicorn；HTTP `/docs`、健康检查、数据库就绪检查通过 | 合并请求审阅、团队环境复核 |
+| T03 | 真实 PostgreSQL 16 测试实例完成迁移、知识录入和读取；后端进程重启后数据仍可读取 | 当前主机 Docker 守护进程未运行，启动需管理员权限；Compose 容器与浏览器端联调待复核 |
+| T05（阶段 2 范围） | 来源、文档、知识关联、版本、人工审核、软删除和历史快照；验证旧基础表迁移保留数据 | `chunks` 和索引版本留到检索阶段；字段与前端、资料负责人共同确认 |
+| T10（部分） | Alembic 迁移、并发版本检查、PostgreSQL 自动化测试、启动说明 | 登录鉴权、限流、生产部署留到后续工程阶段 |
+
+验证环境：Python 3.11；使用可选 `pgserver` 启动独立 PostgreSQL 16.2 测试实例并启用 pgvector。该方式用于验证 SQL 和接口，不等同于 Docker 容器验收。
+
+实际命令与结果（在 `backend/` 执行）：
+
+- `ruff check .`：通过。
+- `ruff format --check .`：通过。
+- `pytest -q`：22 passed；依赖库产生一条 TestClient 弃用提示，不影响本轮用例。
+- 覆盖：新库迁移、已有基础表接管、重复升级、阶段 2 降级后基础正文保留、ORM 与迁移结构一致、审核前置条件、正文/来源/文档变更后重新审核、历史快照、软删除引用保护、筛选与分页、并发写入冲突、跨域预检、真实 HTTP 与服务重启持久化。
+
+所有测试正文、来源和审核人均为占位数据，临时数据库不入库。当前问答仍是占位接口，未开展论文对照实验。Issue、合并请求和最终批准结论须补入 Gitea 后按团队规则归档。
+
+## 2026-10-15 合并后续开发：关键词检索基线
+
+- 阶段 2 后端功能已通过普通功能分支的 [PR #4](https://gitea.kronecker.cc/saint/border-red-post-nalati/pulls/4) 合入 `dev`（合并提交 `4d437ca`），包含测试客户端依赖修正。旧 AGit PR #2 仍打开，不作为该批功能是否已合入的唯一判据。
+- 从最新 `dev` 创建 `feat/backend-keyword-retrieval`，推进 T06 的独立关键词接口与检索记录。T05 的持久化切分/索引版本、T07 的模型评估和向量检索仍待后续实现。
+- 当前主机 Docker 服务仍未运行；本轮继续使用隔离 PostgreSQL 做接口与迁移测试，不把容器或浏览器端联调标记为完成。独立任务 Issue 仍须补齐。
+- 新增检索接口、中文分词和 BM25 基线、有效审核筛选、原文片段、来源与版本、语料指纹及检索历史；前端调用层同步类型与接口，页面接入由前端继续联调。
+- 分支验证：`ruff check .`、`ruff format --check .`、`pytest -q`；本轮 42 项 PostgreSQL/单元/真实 HTTP 测试通过，覆盖手算分数、标题权重、排序复现、审核边界、来源失效、容量拒绝、迁移兼容和服务重启后的检索历史。前端 `npm run build` 通过，包含新增检索调用类型的检查。全部使用占位资料，不是论文实验结果。
+
+## 2026-10-16 Issue #5：认证与角色权限
+
+- 按继续开发的授权，在 `feat/backend-auth-sessions` 推进 T10 的认证部分；叠加 PR #6（`8ac9dca`），不等待其合并，不自行批准或合并。PR #6 与本分支分别保持可追踪记录。
+- 实现注册、登录、退出、当前会话、本人资料修改、改密及管理员用户列表；注册拒绝角色字段，知识/来源/文档管理及检索历史均由服务端要求 admin。
+- 新增 `0004_auth_sessions`，保存 Argon2id 密码哈希、会话摘要与到期/凭据版本、共享认证请求预算；不预置用户，提供本机隐藏密码输入的管理员初始化命令。迁移和回滚保留知识及检索记录。
+- 默认 Secure/HttpOnly/SameSite Cookie；写操作校验明确 Origin 及当前会话 CSRF。改密使所有旧会话失效，退出持久化撤销；参数错误不回显密码。字段、来源、CSRF 和前端交接见 [认证接口契约](AUTH_API.md)。
+- 实际验证：`ruff check .`、`ruff format --check .` 通过；`pytest -q` **70 passed**，包含认证、授权、CSRF、输入越权、过期/轮换/撤销、限额、迁移及既有知识/检索回归；真实 HTTP 服务重启验证会话恢复和退出后不再有效。前端 `npm run build` 通过。
+- 当前仍使用隔离 PostgreSQL 做自动化验证；Docker 容器、前端登录/角色页面及真实浏览器端流程仍待验收。远程 main 的注册原型最低密码提示需要按本契约同步到 15 字符，并接入带 Cookie/CSRF 的调用层。没有宣称已完成前端集成或生产部署。
+
+## 2026-10-16 T05：持久化 chunks 与索引版本
+
+- 分支 `feat/backend-chunk-index-versions` 叠加待审 PR #7（`f9827fe`），继承 #6；不等待合并继续后端阶段，同时保留各 PR 的审阅记录。
+- 新增 `0005_chunk_indexes`：版本、原文切分及出处、发布状态单例、逐次发布记录。构建 ready 快照与发布分开，保留字符偏移、内容哈希、知识/来源/文档版本和语料指纹。
+- 知识、来源、文档写入与构建/发布共用数据库行锁；目录修订与实际语料指纹一起决定当前性，旧构建/旧代数拒绝发布。构建或发布失败完整回滚，旧发布指针及历史不丢失。
+- 管理接口统一要求 admin 与写入 CSRF；前端只同步类型和调用层，页面仍待联调。现有关键词基线行为不变，向量、ANN、RRF 与 RAG 未在本阶段实现。
+- 实际验证：`ruff check .`、`ruff format --check .` 通过；`pytest -q` **91 passed**（隔离 PostgreSQL 16 + pgvector），包含真实锁竞争、失败构建/发布的数据库约束回滚、迁移保留账号/知识/检索记录、原文重建与来源快照、真实 HTTP 重启后的发布指针和 chunks 持久化。修正了发布时间在 UTC 与数据库时区之间表示不一致的问题，索引接口统一 UTC 输出。前端 `npm run build` 通过。
+- 完整请求/响应、切分/容量、失效策略及回滚说明见 [INDEX_API.md](INDEX_API.md)。本阶段仍是有限语料的同步文本快照；Docker/浏览器验收、独立 T05 Issue 补建及后续 Embedding 方案选择仍有待完成。
+
+
+## 2026-10-16 T07：合并后的 RRF 混合检索
+
+- 本地模型评估和向量持久化/精确检索分别经 PR #11/#13 合入 `dev`；#9/#10 是被替代的旧 AGit 入口。读取已确认合并结果后，从最新 `dev` 创建 `feat/backend-rrf-retrieval`，遵循每阶段 PR 合并后才开发下一阶段。
+- 新增公开 chunk 正文 BM25 与 RRF 接口，三种 chunk 模式限定同一文本快照及分类；原条目关键词接口保留独立口径。固定 k=60、等权、每路候选预算，记录两路完整候选排名/原始分数、贡献、模型空间、切分/BM25/分词参数与出处。前端仅同步调用与历史类型。
+- 模型编码在发布锁外，完成后重新检查审核语料、文本/向量代数与空间；两路排序和记录保存受同一事务保护。竞争、模型或写入失败不保存部分混合结果；2000 chunks 容量与原向量阶段一致。没有新增数据库迁移。完整字段、比较口径及回滚见 [HYBRID_API.md](HYBRID_API.md)。
+- 常规测试 `pytest -q` **180 passed, 1 skipped**（真实模型专项须显式启用）；新增 27 项覆盖手算排序/融合、候选截断/缺席/同分、相同粒度及分类、原文、历史、权限、编码期间锁释放和版本竞争、损坏/失效快照、失败回滚与容量。`ruff check`、`ruff format --check` 和前端 `npm run build` 通过。真实模型专项在独立 CPU 环境另执行 **1 passed**：固定 BGE small 经真实 HTTP 完成向量/混合/关键词 chunk 查询，进程重启后两路候选排名、结果和历史保持一致。首次专项请求因 candidate_k 小于默认 top_k 被按契约拒绝，修正测试请求后通过；未改变该输入约束。
+- Issue #5 本轮复查无新评论，后端实现已合入，前端登录/CSRF/角色页面及浏览器流程仍待交接；Docker 容器、核验领域语料/问题集、正式模型冻结与领域评测同样未验收。所有新增自动化资料均为合成测试，不作为文旅事实或论文分数。下一阶段须等待本轮 PR 真正合入 `dev`。
+
+
+## 2026-10-16 T08：证据与 OpenAI 兼容请求契约
+
+- RRF 经 PR #14 真正合入 `dev` 并核对 head/merge 祖先关系后，从最新 `dev` 创建唯一阶段分支 `feat/backend-rag-context`。用户明确“模型先不急”，随后要求“先以OpenAI通用请求格式进行开发”；本轮完成协议和证据准备，不选择生成模型或发起真实调用。
+- 新增管理员 `POST/GET /api/rag/contexts` 及详情接口，写操作沿用 Cookie/Origin/CSRF；只接受服务端 chunk 检索记录，复核当前审核语料、文本/向量发布、空间、原文及出处，持久化完整证据、排除原因、提示词版本、请求体与哈希。
+- OpenAI 兼容 Chat Completions 请求构造支持明确的 model/messages、角色及输出预算字段；纯响应解析校验单候选、结束原因、引用编号和可选 token 用量。截断/拒绝/无引用等不作为有效答案；引用通过只表示结构候选，不表示事实已核验。
+- 新增迁移 `0007_rag_contexts`，失败写入完整回滚，历史保留当时快照；回滚保留知识、账号、文本/向量发布和检索记录。当前 `/api/chat` 仍为原占位，准备结果固定 `prepared_request/model_called=false`。完整协议、字符预算与后续 token/模型边界见 [RAG_CONTEXT_API.md](RAG_CONTEXT_API.md)。
+- 实际验证：`pytest -q` **224 passed, 1 skipped**；较上一阶段新增 43 项上下文/协议/权限/失效/预算/原文/失败回滚/真实 HTTP 重启用例，另新增 1 项上下文迁移降级保留数据验证。skip 为既有须显式启用的真实 Embedding 用例，本轮未重跑真实模型专项，不沿用旧结果冒充生成模型验证。`ruff check`、`ruff format --check` 通过。前端调用层同步，构建在补齐依赖后通过。
+- PR #16 已合入的认证路由引用了 `vue-router`，原 package.json/锁文件未声明；本轮补充匹配现有 Vue 3 的 vue-router 4 依赖及锁记录，保留其他依赖原版本和平台元数据。前端 `npm run build` 通过；浏览器实际 Cookie/CSRF/角色及容器验收仍待完成。
+- 本轮所有测试为协议/合成资料或坐标 fixture，没有真实生成模型请求、质量分数或费用。生成模型选择和服务凭据保持延期，不重复索要；本阶段提交 PR 后等待实际合入，再继续下一项可独立验收的后端任务。
@@ -0,0 +1,116 @@
+# T07 向量快照、发布与精确检索
+
+本分支 `feat/backend-vector-retrieval` 组合待审 #8 的文本版本与 #9 的固定版本 CPU Provider，继承 #7/#6。合并到 `dev` 前须按依赖审阅；不自行批准或合并。双方阶段文档均保留，独立阶段差异从组合基线 `bd0b738` 起查看。
+
+交付 pgvector 存储、空间约束、独立发布、精确余弦检索与历史。关键词 `POST /api/retrieval` 保持原请求/分数/条目粒度；向量使用新的 `POST /api/retrieval/vector`，粒度为 chunk。本阶段尚未实现 RRF、ANN、RAG、持久化后台任务或正式领域评测。
+
+## 配置与迁移
+
+执行 `alembic upgrade head` 到 `0006_vectors`。迁移增加 `embedding_spaces`、`vector_versions`、`chunk_vectors`、`vector_state` 和 `vector_publications`，以及 chunks 的复合唯一约束。保留账号、目录、原文版本及既有检索日志，不预置模型或向量。
+
+扩展类型/函数/距离算子显式引用 `public.vector`，业务表仍放在连接的当前 Schema，不把 public 加入测试搜索路径。已有 vector 扩展须位于 public；其他安装位置会明确报错，迁移不会移动共享扩展。新数据库可先由有权限的数据库管理员执行 `CREATE EXTENSION IF NOT EXISTS vector WITH SCHEMA public`。
+
+默认 `EMBEDDING_ENABLED=false`，普通 API 启动不导入 PyTorch 或加载权重。模型相关请求返回 503，不回退占位向量或伪造空结果；关键词和管理元数据接口可继续使用。启用前按 [本地评估说明](LOCAL_EMBEDDING_EVALUATION.md) 安装独立 CPU 环境、缓存固定修订；该运行环境还需安装 `backend/requirements.txt` 的 API 依赖。
+
+| 变量 | 默认值 | 作用 |
+|---|---|---|
+| `EMBEDDING_ENABLED` | false | 显式启用本地编码 |
+| `EMBEDDING_MODEL` | small | 仅 small/base；完整修订、维度等由固定 Spec 决定 |
+| `EMBEDDING_CACHE_DIR` | 未设置 | 固定模型缓存目录；空值使用库默认缓存 |
+| `EMBEDDING_BATCH_SIZE` | 8 | 1–32 |
+| `EMBEDDING_THREADS` | 2 | 1–4 个 CPU 线程 |
+
+开发资源优先暂用 small，正式模型仍待已核验领域资料/问题集评测。API 始终只从本机固定修订缓存读取，禁止在请求中下载权重，不接收模型路径、任意仓库名或用户向量。CPU Provider 首次使用才加载，单进程同时只允许一个编码调用，繁忙立即返回 503；当前建议单 worker 本机运行，不能据此宣称已实现跨进程队列或生产并发容量。
+
+Linux 仓库根目录示例（先完成模型准备及数据库迁移；本机 Cookie/Origin 配置仍按认证说明设置）：
+
+```bash
+task_vector_root=$(git rev-parse --absolute-git-dir)
+uv pip install --python "$task_vector_root/embedding-eval-venv/bin/python" \
+  -r backend/requirements.txt
+export EMBEDDING_ENABLED=true EMBEDDING_MODEL=small
+export EMBEDDING_CACHE_DIR="$task_vector_root/embedding-model-cache"
+export HF_HUB_OFFLINE=1 HF_HUB_DISABLE_TELEMETRY=1 HF_HUB_DISABLE_IMPLICIT_TOKEN=1
+export TOKENIZERS_PARALLELISM=false
+cd backend
+"$task_vector_root/embedding-eval-venv/bin/python" -m uvicorn app.main:app --host 127.0.0.1
+```
+
+环境、模型权重和实际日志只留本机，不提交。普通 API 环境不自动增加 PyTorch 依赖。
+
+## 构建与发布协议
+
+1. 通过 `/api/indexes` 构建并发布当前有效审核语料的文本版本。建议开发先用 `chunk_size=200, overlap=20`；实际 tokenizer 仍须检查，字符数不保证 token 数。
+2. 管理员向 `POST /api/vector-indexes` 提交 `{"text_index_version_id":"<已发布文本版本 UUID>"}`。服务仅接受当前有效的文本发布版本；整份快照最多 2000 chunks，超限返回 503，不截断语料。
+3. 服务短暂锁住目录/文本状态，复核实际审核语料指纹、原文窗口、偏移、哈希、出处和完整数量；复制输入后提交并释放事务。模型加载与正文编码全部在锁外运行。
+4. 编码成功且向量数量/维度/有限数/L2 范数通过后，再取得同一状态锁，重新校验文本代数、目录修订、当前指针、语料指纹及实际 chunks。变化则 409，整批不入库。成功只保存 ready 向量版本，不自动发布。
+5. 管理员向 `POST /api/vector-indexes/{id}/publish` 提交 `{"expected_generation":0}`。向量代数独立于文本代数；原子切换当前指针、前后版本状态和发布历史。旧代数、过期文本或不完整向量集均拒绝。相同当前版本和当前代数为幂等读取。
+
+上述构建同步执行，没有后台任务 ID 或自动重试。超过模型 token 上限返回 422，应重新切分并发布文本，再重建；不会静默截断。编码不可用/繁忙为 503；数据库约束或版本竞争为 409。失败不会改写旧指针或留下部分向量版本。空的有效审核语料允许生成/发布 0 chunks 的版本；随后检索如实返回 `no_evidence`。
+
+目录变化会使既有文本和向量版本过期；文本切换即使内容相同也要求对应新文本版本的向量。旧指针和日志保留为历史，公开检索对过期状态返回 409，不继续使用旧审核依据。切换模型配置后，若当前空间不一致，也须重新构建/发布相应空间或恢复匹配的运行配置。
+
+## 数据库空间隔离
+
+`space_id` 为固定 Spec 的 SHA-256，包含模型名、完整 revision、维度、token 上限、查询指令、编码实现（CLS/L2/CPU FP32）及权重格式。同维度的不同修订/指令/配置仍是不同空间。
+
+数据库同时约束：
+
+- 版本的 `(space_id, dimension)` 必须引用同一 EmbeddingSpace。
+- 每条向量的 `(version_id, text_index_version_id, space_id, dimension)` 必须引用同一向量版本。
+- `(chunk_id, text_index_version_id)` 必须引用对应文本版本中的 chunk。
+- `public.vector_dims` 必须等于声明维度；`public.vector_norm` 须在 `0.9999–1.0001`，pgvector 拒绝非有限元素。
+
+使用无固定维度的 vector 列容纳独立空间，查询显式限定版本、空间、文本版本和维度，然后使用余弦距离。当前为有限语料精确扫描，没有 HNSW/IVFFlat；模型空间和向量发布均不由客户端参数任意指定。
+
+## 接口与字段交接
+
+`/api/vector-indexes` 下所有读写要求 admin；写入沿用当前 Cookie、CSRF 和明确 Origin。元数据不要求加载模型。分页使用 `{items,total,page,page_size}`，`page_size` 最大 100。
+
+| 方法与路径 | 请求/用途 | 响应 |
+|---|---|---|
+| POST `/api/vector-indexes` | `text_index_version_id` | 201，VectorVersion |
+| GET `/api/vector-indexes` | page/page_size | 版本分页 |
+| GET `/api/vector-indexes/{id}` | UUID | VectorVersion，缺失 404 |
+| GET `/api/vector-indexes/active` | 当前元数据 | generation/text_generation/catalog_revision/is_current/active_version |
+| GET `/api/vector-indexes/spaces` | page/page_size | 空间 id/dimension/spec |
+| POST `/api/vector-indexes/{id}/publish` | expected_generation | 当前向量元数据 |
+| GET `/api/vector-indexes/publications` | page/page_size | 代数、前后向量版本、actor_id、UTC 时间 |
+| POST `/api/retrieval/vector` | 下方请求 | VectorRetrievalResponse |
+
+VectorVersion 字段：`id/text_index_version_id/space_id/dimension/chunk_count/status/created_by/created_at/published_at`，状态为 ready/published/superseded；时间统一 UTC ISO 8601。发布历史的 `version_id` 是向量版本，不能与文本发布历史混用。
+
+公开检索请求示例：
+
+```json
+{"query":"待检索问题","mode":"vector","top_k":5,"category":"交通"}
+```
+
+`mode` 可省略，固定为 vector；query 1–500 字符，top_k 1–20，category 可省略。未知字段拒绝。流程在查询编码前后均复核当前发布/审核状态和完整向量集；编码时不持有目录发布锁，期间任何发布代数变化都会返回 409，重试使用新快照。
+
+响应记录：`run_id/query/mode/status/top_k/category/vector_version_id/text_index_version_id/generation/text_generation/corpus_fingerprint/corpus_size/total_hits/results/elapsed_ms/created_at/config`。`config` 固定 scorer=`pgvector-cosine-exact-v1`、ranking_unit=`chunk`，并保存完整空间 Spec。
+
+每个 result 沿用关键词出处字段，再加 `chunk_id/chunk_ordinal`；snippet 为完整原文 chunk，snippet_start/end 是原正文的 Unicode 字符偏移（左闭右开），matched_terms 为空数组。score 为 `1 - cosine_distance`，不是正确率或置信度，也未设领域无依据阈值。按实际距离、knowledge_id、chunk_ordinal、chunk_id 排序；同一知识可出现多个 chunks，不能把结果数量当作命中的知识数。
+
+`corpus_size/total_hits` 为分类筛选后的候选 chunk 数，不是超过置信阈值的数量；corpus_fingerprint 是整个已发布文本语料指纹，分类另行保存。耗时包括两次审核/快照检查、查询编码（首次可含模型加载）、SQL 距离排序与片段生成，不含最终日志提交及网络。不同于关键词基线的条目粒度，正式对照前必须统一评测单位。
+
+成功和零候选均保存 `retrieval_runs` 不可变快照。既有历史接口现在返回 keyword/vector 判别联合，仍限 admin；不改写过去结果，也不因历史可读取就代表资料仍有效。前端调用层已同步 `services/vectors.ts` 与历史联合类型，页面和浏览器仍待接入验收。
+
+## 回滚与验证
+
+备份后 `alembic downgrade 0005_chunk_indexes` 删除本阶段空间、向量、向量状态和发布历史，保留文本 chunks/发布、账号、知识及所有检索结果快照。切回对应旧版后端前须处理其历史接口只认识 keyword 响应的兼容性；重升后向量指针为空，需要重新构建，不会复原被删权重结果。当前 API 启动会拒绝旧 Schema。
+
+默认测试用明确的三维坐标 fixture 验证 SQL 数学、空间隔离、并发与回滚，绝不代表实际模型质量。真实模型贯通用例显式启用，在独立模型环境运行：
+
+```bash
+task_vector_root=$(git rev-parse --absolute-git-dir)
+uv pip install --python "$task_vector_root/embedding-eval-venv/bin/python" \
+  -r backend/requirements-dev.txt pgserver
+RUN_LOCAL_EMBEDDING_TEST=1 EMBEDDING_CACHE_DIR="$task_vector_root/embedding-model-cache" \
+  "$task_vector_root/embedding-eval-venv/bin/python" -m pytest -q \
+  backend/tests/test_vector_runtime.py
+```
+
+该用例用合成测试文字，验证真实 small 的 512 维编码、HTTP 构建/发布/查询、pgvector 持久化及新进程重启后的空间、发布、命中和历史一致；不是领域分数或生产性能实验。Docker 容器、前端浏览器、RRF 和领域验收保持待办。
+
+实现依据：[pgvector 精确查询与余弦算子](https://github.com/pgvector/pgvector#querying)、[混合维度存储约束](https://github.com/pgvector/pgvector#can-i-store-vectors-with-different-dimensions-in-the-same-column)、[SQLAlchemy 集成](https://github.com/pgvector/pgvector-python#sqlalchemy)。
@@ -0,0 +1,25 @@
+# 联调验收记录
+
+> 用途：记录每次联调/验收的日期、人员、环境、操作与结果，保证测试过程可追溯。
+> 维护人：杨星萱
+
+## 字段说明
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| 日期 | 是 | 联调/验收日期 `YYYY-MM-DD` |
+| 人员 | 是 | 参与本次联调/验收的成员 |
+| 环境 | 是 | 如「本机 Windows + Docker PostgreSQL + FastAPI + Vite」及版本号 |
+| 操作 | 是 | 具体操作步骤，如「POST /api/knowledge 新增一条资料」 |
+| 预期结果 | 是 | 操作前预期的结果 |
+| 实际结果 | 是 | 实际观察到的结果（成功/失败/异常） |
+| 截图/日志位置 | 否 | 相关截图或日志的存放路径 |
+| 结论 | 是 | 通过 / 不通过 / 阻塞，及原因与下一步 |
+
+## 登记表
+
+| 日期 | 人员 | 环境 | 操作 | 预期结果 | 实际结果 | 截图/日志位置 | 结论 |
+|---|---|---|---|---|---|---|---|
+| 【示例】2026-10-15 | 【示例】杨星萱 | 【示例】本机浏览器 | 【示例】打开知识管理页 | 【示例】页面正常展示 | 【示例】此处为占位，非真实结果 | 【示例】docs/screenshots/ | 【示例】待执行 |
+
+> 上表仅含一条**示例占位行**，用于演示填写格式，不含任何真实测试结果。
@@ -0,0 +1,39 @@
+# 资料台账
+
+> 用途：登记候选资料及其核验状态，是资料进入正式检索库前的唯一登记入口。未核验（`pending`）资料不得进入正式检索。
+> 维护人：杨星萱（知识库、实验与文档负责人）
+
+## 状态约定
+
+| 状态 | 含义 |
+|---|---|
+| `pending` | 待核验：已登记，尚未完成真实性/时效性核验 |
+| `verified` | 可正式使用：来源可靠、交叉印证通过、可进入正式检索 |
+| `rejected` | 不采用：来源不可靠、信息过时或被证伪 |
+
+> 详细判定标准见 [审核规则](review-rules.md)。
+
+## 字段说明
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| 编号 | 是 | 唯一序号，格式 `K-0001`，按登记顺序递增 |
+| 标题 | 是 | 资料的简短标题，便于检索和引用 |
+| 类别 | 是 | 四选一：红色文化 / 旅游资源 / 民宿服务 / 交通出行 |
+| 来源名称 | 是 | 发布方，如机构/媒体/网站名称 |
+| URL | 是 | 来源链接；无法溯源时填「无链接」并在真实性判断中说明 |
+| 获取日期 | 是 | 采集日期，格式 `YYYY-MM-DD` |
+| 正文摘要 | 是 | 资料关键内容的一两句话摘要，不改变原意 |
+| 真实性判断 | 是 | 核验结论依据，如「与官方公告一致」「与另一独立来源交叉印证」「无法核实」 |
+| 核验日期 | 否 | 完成核验的日期 `YYYY-MM-DD`；`pending` 时可为空 |
+| 核验人 | 否 | 完成核验的人；`pending` 时可为空 |
+| 状态 | 是 | `pending` / `verified` / `rejected` |
+| 备注 | 否 | 补充说明，如过期时间、需二次确认的事项 |
+
+## 登记表
+
+| 编号 | 标题 | 类别 | 来源名称 | URL | 获取日期 | 正文摘要 | 真实性判断 | 核验日期 | 核验人 | 状态 | 备注 |
+|---|---|---|---|---|---|---|---|---|---|---|---|
+| K-0001 | 【示例·占位】某景区简介 | 旅游资源 | 【示例来源，非真实】示例站点 | https://example.com/ | 2026-10-15 | 【示例】此处为占位摘要，非真实资料 | 待核验 |  |  | pending | 示例行，仅演示填写格式，不构成真实资料 |
+
+> 上表仅含一条**示例占位行**，用于演示填写格式，不包含任何真实文旅信息。正式收集的资料按此格式逐行追加。
@@ -0,0 +1,53 @@
+# 审核规则
+
+> 用途：规定资料的核验状态、判定标准与核验流程，是资料能否进入正式检索库的统一依据。
+> 状态：本规则为**草案**，由杨星萱起草，需经确认后定稿。
+> 维护人：杨星萱
+
+## 一、状态定义
+
+| 状态 | 含义 | 能否进入正式检索库 |
+|---|---|---|
+| `pending` | 待核验：已登记，但来源可靠性、时效性或关键信息完整性尚未确认 | 否 |
+| `verified` | 可正式使用：来源可靠、关键事实交叉印证、时效性满足需求、信息完整 | 是 |
+| `rejected` | 不采用：来源不可靠、信息被证伪/与权威来源冲突、严重过时、或无法核验且影响关键事实 | 否 |
+
+## 二、判定标准（草案）
+
+### 标记为 `verified` 需同时满足
+
+1. 来源可靠（官方文旅/景区/政府公告，或可溯源的权威媒体）。
+2. 关键事实与至少一个独立来源交叉印证一致。
+3. 信息时效性满足当前使用需求（未过期、未失效）。
+4. 关键信息完整，无影响结论的缺失。
+
+### 标记为 `pending` 的情形
+
+- 来源可靠性存疑，尚待核实。
+- 关键事实暂无法交叉印证。
+- 信息可能过期，但尚未确认。
+- 关键信息缺失，需要补充后再判。
+
+### 标记为 `rejected` 的情形
+
+- 来源不可靠（无法溯源的个人自媒体、无依据转载等）。
+- 信息已被证伪，或与权威来源冲突。
+- 信息严重过时，不再适用。
+- 无法核验，且该事实对结论有实质影响。
+
+## 三、核验流程
+
+1. 采集登记：在 [资料台账](material-ledger.md) 登记基础字段，状态先置 `pending`。
+2. 来源可靠性判断：确认发布方可溯源、权威性可接受。
+3. 真实性判断：关键事实与独立来源交叉印证。
+4. 时效性判断：确认信息当前仍适用。
+5. 定状态：根据判定标准置 `verified` / `rejected`，并填写核验日期、核验人、真实性判断说明。
+
+## 四、核验要点
+
+- 来源权威性排序（参考）：官方文旅局/景区官网/政府公告 > 权威媒体 > 一般网站/个人自媒体。
+- 多源交叉：单一来源不足以定为 `verified`，关键事实需至少一个独立来源印证。
+- 时效性：注明信息发布时间，避免使用明显过时内容。
+- 边界一致：首版不承诺实时房态、实时价格、自动联网核验等，此类信息不按可靠事实收录。
+
+> 本规则为草案，判定标准与流程以负责人确认为准。