ESA 个人知识库后端实现清单

当前状态（2026-09-08）：清单中的 MVP、Agent 检索和在线预览阶段已实现。本文保留作为实现与验收记录，不再表示仍需从零开发；后续工作以 TODO.md 为准。

本文档把 PERSONAL_KNOWLEDGE_BASE_API.md 转换为可实施、可测试、可验收的任务清单。MVP 的 4 个管理接口、聊天 Agent 个人资料检索闭环，以及后续原文件/在线预览阶段均已进入同一验收记录。

部署事实和路径基线必须由目标机器的只读检查、.env 和作业脚本共同确认。仓库不再包含旧的 SUPERCOMPUTER_ENVIRONMENT.md 快照；每个新 Slurm Job 都不能把历史 PID、 GPU 分配或 /tmp 路径当作当前事实。

1. 范围与结论

1.1 当前必须交付

GET /api/me/knowledge-base
POST /api/me/knowledge-base/files
DELETE /api/me/knowledge-base/files/{file_id}
POST /api/me/knowledge-base/rebuild
原始文件的用户隔离持久化
DocIR 解析、Chunk 构建、Embedding 和 Qdrant 写入的异步流水线
构建任务、进度、统计和错误的持久化
删除和重建的一致性、恢复与清理

1.2 第二阶段交付

给 Agent 增加用户身份绑定的个人知识库检索能力
返回可回查的 Evidence、文档名和定位信息
明确个人库与 ESA 全局教材库的召回、融合和降级策略
验证任何检索路径都不能读取其他用户的 Point

1.3 在线预览阶段（已实现）

GET /api/me/knowledge-base/files/{file_id}/content
PDF、图片、文本和 Office 在线预览
HEAD/Range、流式预览、缩略图和 Office 转 PDF
前端 AttachmentContent.bodyBytes 的大文件内存问题改造

页面只请求受控 preview 派生物，不因点击而全量读取原件。后端不返回伪造文件；未就绪明确返回 409。

前端文件点击调用有界 fetchPersonalKnowledgeBasePreview()，不直接调用原件流。
更新桌面端和移动端 Widget 测试，覆盖正文、PDF/图片视图和切换取消。
content/download API client 返回可取消字节流，不构造整份原件 bodyBytes。

1.4 不在本次范围

课程“知识地图”及其 YAML 数据；它与文档 RAG 是不同系统。
把聊天附件自动永久加入个人知识库。
管理员查看或编辑所有用户的知识库。
文件在线协作编辑、版本对比和共享知识库。
在当前前端之外新增独立搜索调试页面或搜索 HTTP API。

2. 已讨论的推荐架构

2.1 用户与知识库模型

每个用户只有一个个人知识库，学生端和教师端共用。
user_id 只从 Bearer Session 解析，任何请求体、查询参数和路径都不得接受 user_id。
文件元数据、任务状态、活跃索引代次和统计存入现有主 SQLite 数据库；不为个人库另建第二个 SQLite。
原始文件和 DocIR/Chunk 工件写入可配置的个人知识库根目录，不提交 Git。
Qdrant 使用一个共享的个人知识库 collection，不按用户创建 collection。
每个 Qdrant Point 必须携带 user_id、file_id、kb_generation_id 和可见性字段。
所有 count、query、delete 和 payload 更新必须在索引适配器底层强制加入用户过滤条件。

选择共享 collection 的原因：避免用户数增长时产生大量 collection，同时便于统一模型、向量维度、备份和监控。代价是多租户过滤必须成为不可绕过的安全边界。

2.2 构建与切换

上传请求只保存文件、写元数据并创建任务，返回 202，不等待 DocIR/RAG 完成。
前端文件/知识库状态使用 idle|queued|building|ready|failed；内部 Job 状态独立使用 queued|running|succeeded|failed|cancel_requested|cancelled。
同一用户的上传、删除和重建按 target_revision 严格顺序提交；同一用户已有上传或重建任务时，再次上传或重建统一返回 409。删除仍可同步写 tombstone，并由有序 cleanup job 接在当前 revision 之后执行。
不同用户可以并发执行解析、Chunk 和 Embedding；写入共享 Qdrant collection 的短提交阶段按用户有序，并与全局 snapshot/collection 维护锁协调。
普通新增文件可以增量处理，但新 Point 在文件完整写入并校验前不可检索。
generation_id 表示一次全量 rebuild 代次，不是不可变的完整文件集合指纹；普通增量上传写入当前 active generation，并记录独立的 ingestion_revision。
重建使用新的 staging generation；完整校验后原子更新 SQLite 中的 active_generation_id。
重建失败时继续使用旧的活跃 generation，不把整个知识库切到失败状态。
新 generation 激活后，再异步回收旧 generation，不能先删旧索引。

2.3 任务执行方式

MVP 固定使用“SQLite 持久任务 + 进程内 asyncio.Queue 唤醒器”，不接入外部任务系统。
任务本身必须持久化，进程重启后将内部 running 恢复为 queued 并重新领取。
claim_job 必须使用条件更新，保证多个进程不会同时执行同一任务。
生产启动固定为一个 Uvicorn worker 且关闭 reload；否则每个进程都会启动自己的个人库 worker。
MinerU、Chunk、Embedding、Qdrant 等阶段边界必须检查 cancel_requested，不能把取消 asyncio.to_thread() 误认为底层同步工作已经停止。
在线检索和后台建库共享一个进程级 Embedding provider 及全局并发上限，不能每个任务加载一份模型。
当前拓扑固定为“每个 Slurm Job 只有一个活动 ESA 后端实例”，不设计多后端节点同时读写。
“单机”只描述活动服务实例数量，不表示可以把持久数据放到节点 /tmp；Job 结束后节点临时目录会消失。
原文件、SQLite、DocIR/Chunk 工件和 Qdrant 备份必须放持久挂载；节点本地 ext4 只用于临时工作目录和 Qdrant 活动目录。

2.4 Agent 检索建议

第一阶段不修改冻结的全局 retrieve_knowledge B2 契约。第二阶段优先新增上下文感知的 retrieve_personal_knowledge：

工具参数只包含 query、top_k 等检索参数，不包含 user_id。
执行器从 ToolExecutionContext.user_id 获取用户身份。
个人库为空、未就绪或暂时不可用时返回明确空结果/降级信息，不能退化成无用户过滤的查询。
全局库和个人库先保持两个工具，待有检索评测后再决定是否做自动联邦融合。

这样可以保持现有全局知识库契约、训练数据和行为稳定，也能让个人资料的授权边界更清晰。

2.5 超算目录与进程布局

当前按“一次 Slurm Job 运行一个 ESA 后端、一个 Qdrant 进程”实施，不引入多后端写入协调。推荐目录布局如下；其中持久根目录只是候选值，正式配置前必须在当次 Job 的宿主机环境重新检查容量、挂载和写权限：

/persist_data/home/chenxuzhao/esa-personal-knowledge-base/
  files/                 # 原始文件，权威数据
  artifacts/             # DocIR、Chunk、manifest，权威或可重建工件
  qdrant-snapshots/      # 个人 collection 的持久快照

${SLURM_TMPDIR:-/tmp}/esa-${SLURM_JOB_ID}/personal-kb/
  work/                  # 上传、解析和构建临时目录
  qdrant-storage/        # 当前 Job 的 Qdrant 活动 storage
  qdrant-snapshots/      # Qdrant 创建/恢复快照时的本地工作目录
  qdrant-temp/

首选 PERSONAL_KB_ROOT=/persist_data/home/chenxuzhao/esa-personal-knowledge-base；如当次宿主机检查不满足容量或写权限，再改用 /remote_dir 下经确认的持久目录。
启动前在宿主机只读核对 findmnt -T /persist_data/home/chenxuzhao、df -hT /persist_data/home/chenxuzhao 和 test -d/-r/-w；历史记录的约 515 GB 可用空间不能当作当前保证。
个人库沿用现有主 user.db；确认其当前路径跨 Job 持久，并把主数据库备份纳入部署要求。若以后迁往 /persist_data，迁移整个主数据库而不是拆出个人库数据库。
不把原文件、主 SQLite、DocIR/Chunk manifest 或唯一一份 Qdrant 快照放在 $SLURM_TMPDIR//tmp。
Qdrant 活动 storage 继续放节点本地 ext4，避免把 Qdrant 活动数据库直接放 NFS；持久层只保存可恢复的 snapshot。
主 SQLite 位于 NFS 时默认使用 rollback journal（如 DELETE/TRUNCATE），不要未经宿主机锁与故障测试直接启用 WAL；保持单一活动写入实例。
持久根目录和用户目录权限设为 0700，文件、SQLite 备份和 snapshot 设为 0600，启动时检查实际权限与 owner。
从本地 ext4 向 NFS 提交文件或工件时，先复制到目标持久目录内的 .partial，完成校验和 fsync 后再在同一文件系统内原子 rename；不能跨文件系统直接 os.replace()。
文件、数据库事务和索引快照的提交顺序要有恢复记录；Job 被抢占后能判断应该恢复快照、补做快照，还是从权威工件重建。

3. 需要新增或扩展的模块

建议文件位置如下，实际命名可以按实现调整：

backend/core/stores/personal_knowledge_base_store.py
backend/core/services/personal_knowledge_base_service.py
backend/core/web/routers/personal_knowledge_base.py
backend/agent/rag/indexes/personal_qdrant.py
backend/agent/rag/personal/ingestion.py
backend/agent/rag/personal/retrieval.py
backend/tests/test_personal_knowledge_base_api.py
backend/agent/rag/tests/test_personal_knowledge_base_index.py

复用边界：

复用 UserAttachmentStore 的流式写入、SHA-256、临时文件和原子 rename 思路，但不要复用它的 conversation_id 目录模型。
复用 MultimodalIngestionService 下层的 MinerU/DocIR、视觉补全、Chunk 和 Embedding 组件。
不直接复用 MultimodalSessionService；它是会话级、进程内状态，生命周期和个人知识库不一致。
不直接复用当前 QdrantIndex 的代次校验；它假设 collection 只含一个 generation，会拒绝多用户混合 Point。
复用 ResearchDataService/ResearchWritingService 的持久队列、领取任务、失败记录和重启恢复模式。

4. 配置清单

推荐共享全局 RAG 的 Embedding 模型配置与维度，但个人库使用独立 Qdrant collection，避免改变冻结的全局部署身份。

2026-08-16 至 2026-08-17 的历史超算快照使用 Qdrant 1.18.3、 127.0.0.1:6333、Embedding 模型 /remote_dir/home/chenxuzhao/models/Qwen3-Embedding-4B 和维度 2560。这些值只可作为参考，不能视为当前机器事实或写死在代码中；每次启动仍要校验版本、模型路径、向量维度和服务可达性。

5. 数据库与状态模型

5.1 数据表

增加版本化 migration，禁止只在 Store 初始化时静默建表。
personal_knowledge_bases
- user_id 主键及用户外键
- status、progress、error
- active_generation_id、building_generation_id
- desired_revision、indexed_revision
- file_count、chunk_count、index_count
- created_at、updated_at
personal_knowledge_base_files
- file_id 主键、user_id 外键
- 原始文件名、规范化后缀、MIME、字节数、SHA-256
- 原始文件路径、DocIR/Chunk manifest 路径
- ingestion_revision、indexed_revision
- status、progress、chunk_count、index_count、error
- uploaded_at、updated_at
- 删除/取消状态或 tombstone 字段
personal_knowledge_base_jobs
- job_id、user_id、job_type
- 内部 status、progress、generation_id、target_revision
- 目标文件 ID 列表或稳定 JSON payload
- 尝试次数、错误、创建/开始/完成/更新时间
personal_knowledge_base_generations
- generation_id、user_id、状态
- rebuild 时的输入清单快照及 collection/embedding/chunk 配置指纹
- chunk/index 数量
- 创建、激活和回收时间
personal_knowledge_base_collection_state（单例行或等价全局状态）
- 个人共享 collection 名称
- qdrant_mutation_seq：已验证提交的最新全局变更高水位，只增不减
- snapshot_mutation_seq：最新有效 snapshot 已覆盖的全局变更序号
- snapshot dirty 标记、更新时间和最近错误
personal_knowledge_base_mutations（也可由具备同等字段和保留规则的 durable outbox 实现）
- mutation ID、user_id、target_revision、操作类型和幂等 payload
- 成功提交后分配的全局 qdrant_mutation_seq，并以唯一约束防止重复分配
- 状态、尝试次数、错误和创建/应用时间
- 至少保留到所有仍允许使用的有效 snapshot 都不再需要该记录；恢复旧 snapshot 时用它重放所有更大的 sequence
personal_knowledge_base_snapshots 或等价 manifest 记录：snapshot 文件、SHA-256、collection、Point 数、qdrant_mutation_seq、模型/索引指纹、locator schema 版本和创建时间。

5.2 约束与查询

5.3 去重决策

MVP 固定按用户内 SHA-256 去重：

同一用户重复上传相同内容时返回已有文件，不重复解析和写向量。
不跨用户复用逻辑文件记录或暴露命中信息。
即使底层以后做内容寻址去重，授权、元数据和删除引用计数仍按用户隔离。
相同内容即使文件名不同，也只保留首次上传的逻辑条目和文件名。
在数据库中使用用户范围的唯一约束或条件唯一索引消除并发重复上传；批次内部重复文件采用同一语义。

6. 文件持久化与校验

前端当前 _mimeFor 不会为 doc、ppt、xls、csv、txt、md、json 生成精确 MIME，这些文件可能以 application/octet-stream 上传。后端不能仅因该 MIME 就拒绝合法文件，应结合后缀、魔数和受限文本探测；同时补齐前端 MIME 映射。

7. DocIR、Chunk 与索引流水线

7.1 摄取

现有 SUPPORTED_SOURCE_SUFFIXES 只覆盖 PDF、DOCX、PPTX、XLSX 和常见图片。实现时把 doc、ppt、xls 接入 MinerU，并给 csv、txt、md、json 增加受限原生解析器。每种格式都必须从真实源文件跑通 MinerU/原生解析、DocIR、Chunk 和索引，不能只扩大后缀 allowlist。

7.2 Qdrant 多租户适配器

新建租户感知适配器，不改变冻结全局库的 QdrantIndex 行为。
Point ID 至少绑定 user_id + generation_id + chunk_id，防止相同 Chunk 在不同用户间覆盖。
payload 至少包含：
- scope = personal
- user_id
- file_id
- kb_generation_id
- ingestion_revision
- chunk_id
- visible
- 原 Chunk/Evidence payload
为 user_id、file_id、kb_generation_id、visible 创建 payload index。
Dense、BM25 Body、BM25 Heading 查询统一合并以下过滤：
- 当前 user_id
- 当前活跃 generation
- visible = true
- 可选 content role
count、删除、清理和 verify 使用同一租户过滤构造器。
禁止提供无 user_id 的个人库 query/delete 公共方法。
文件写入完成并验证数量前保持 visible = false，提交后再切换可见性。
删除时先令 Point 不可见，再异步删除，避免删除窗口继续被检索。

7.3 代次、revision 与原子性

7.4 Qdrant 持久化与跨 Job 恢复

8. 异步任务与并发

9. 四个管理接口与预览/下载接口

9.1 `GET /me/knowledge-base`

使用 CurrentSession，不存在文件也返回 200 空快照。
返回完整 PersonalKnowledgeBase，字段名与契约完全一致。
files 始终为完整列表，不能只返回正在构建或最近上传文件。
file_count == len(files)。
queued/building 状态支持前端每 2 秒轮询。
不在请求内扫描文件系统、计算 Embedding 或执行 Qdrant count。

9.2 `POST /me/knowledge-base/files`

接收重复字段名 files 的 multipart 批量文件。
缺少 multipart files 字段返回框架级 422；字段存在但没有可用文件或包含零字节文件返回 400。
限制单文件 200 MB、单批 20 个、单批 1 GB、单用户 10 GB/1000 个文件，并在超限时使用契约状态码。
只接受 MVP 完整格式列表；列表外格式在可靠保存前返回 415。
全批验证、保存和建任务成功后返回 202 完整快照。
新文件状态为 queued，知识库状态为 queued/building。
发生互斥任务冲突时不留下孤立文件或半条数据库记录。

9.3 `GET /me/knowledge-base/files/{file_id}/content`

该接口返回经过租户授权和路径完整性校验的原文件；页面使用独立的有界 preview 派生接口，下载使用独立 download 路径。

PersonalKnowledgeBasePage 文件点击发起有界 preview 请求，不直接读取原文件 content。
桌面端和移动端显示真实派生预览，并覆盖 loading、失败、重试和取消。

预览阶段完成以下事项：

用 user_id + file_id 校验所有权；跨用户访问与不存在统一返回 404。
使用已授权文件描述符安全流式响应，并支持 HEAD/Range 和独立下载。
设置准确的 Content-Type、长度、文件名及安全响应头。
PDF、图片、文本与 Office 分格式选择预览器，必要时生成受控的派生文件或缩略图。
前端不再用 bodyBytes 一次性加载大文件，并为本地缓存设置大小和清理策略。

9.4 `DELETE /me/knowledge-base/files/{file_id}`

删除当前用户存在的文件返回 204；再次删除当前用户尚保留的 tombstone 仍返回 204；从未存在、tombstone 已清理或属于其他用户统一返回 404。
同步写 tombstone 并从 GET 快照隐藏，再异步处理 Qdrant 和文件工件。
cleanup job 完成前保留文件 tombstone、目标 revision 和错误记录，不能因级联删除把尚未执行的清理任务删掉。
cleanup 成功后按审计保留策略清理原文件、DocIR、Chunk、Point、旧任务和错误记录。
cleanup 只有在生成不含该文件 Point 的干净 snapshot，并清除所有可能含该数据的旧 snapshot 后才算完成；这一规则覆盖常规保留 3 份策略。
清理失败进入可重试任务，不重新暴露已删除文件。
更新汇总统计和知识库状态。
删除最后一个文件后返回/保持 idle、零统计和空列表。

9.5 `POST /me/knowledge-base/rebuild`

空请求体，成功返回 202 完整快照。
没有文件时固定返回 400。
不改动原始文件。
创建新的 staging generation 并全量重建解析产物、Chunk 和索引。
旧 generation 在新 generation 完整就绪前继续服务。
失败时快照保留可展示错误，同时记录旧索引是否仍可查询。

10. FastAPI 与生命周期接线

新 router 使用 /me/knowledge-base prefix，并加入 business_router。
router 只做认证、输入校验、状态码转换和响应，不承载构建逻辑。
lifespan 初始化 Store、文件存储、Qdrant 适配器和 Service。
lifespan 启动 worker、把内部 running 重排为 queued、执行 revision reconcile 后再报告个人库 ready。
生产命令验证 Uvicorn worker 数量为 1 且 reload 关闭。
shutdown 停止接单、推进/重排活动任务并尝试最后一次 snapshot，再释放模型/HTTP 资源；Job 启动脚本保证此时 Qdrant 尚未停止。
PERSONAL_KB_ENABLED=false 时 4 个管理接口固定返回 503。
健康检查保持轻量，不触发模型和 Qdrant 查询。
增加 readiness/内部指标：队列长度、活动任务、成功/失败数、阶段耗时、待清理代次。

11. Agent 检索闭环（第二阶段）

新增 PersonalKnowledgeRetrievalService.search(user_id, query, ...)。
user_id 由执行上下文注入，模型参数不可覆盖。
新增 retrieve_personal_knowledge 工具 schema 和能力声明。
在 AgentRuntimeDependencies 中注入个人库检索服务。
在 BoundToolExecutor 中处理个人库工具并传入 context.user_id。
学习、科研、教学 workspace 是否都暴露该工具，需要按产品策略明确；当前页面三者共用同一用户库，推荐全部可读。
输出包含文件名、Evidence、结构化 locator、Chunk ID 和检索降级信息；locator 严格使用第 7.1 节的格式专用 schema。
保持全局 retrieve_knowledge 与 get_knowledge_base_stats 冻结契约不变。
用真实问题集评估“个人库单独检索”和“全局 + 个人联邦检索”后，再决定是否合并工具。

12. 安全与隐私验收

13. 测试清单

13.1 Store 与 Service 单元测试

13.2 RAG 与 Qdrant 适配器测试

13.3 API 契约测试

13.4 端到端测试

上传一个小型真实 fixture，等待 ready，断言 Chunk 和 Point 数大于零。
查询只能命中该用户上传内容。
另一用户相同查询无命中。
删除后查询无命中，管理快照中不再出现该文件。
重建后 generation 改变、内容仍可命中、旧 generation 最终被回收。
后端在构建中重启后任务恢复并最终完成。
恢复落后 snapshot 后自动补齐最近上传和删除，最终 indexed_revision == desired_revision。

13.5 预览测试

文件 content 接口的认证、跨用户 404、响应头和二进制内容。
HEAD/Range、流式读取、取消请求和缓存清理。
接近 200 MB 文件不会被客户端一次性读入内存。
PDF、图片、文本和 Office 的支持矩阵与受控失败行为。

建议验证命令：

python -m pytest backend/tests backend/agent/DocIR/tests backend/agent/rag/tests
cd frontend && flutter test test/personal_knowledge_base_page_test.dart

外部模型、MinerU 和 Qdrant 不可用时，集成测试必须明确 skip，不能用伪造 manifest 冒充成功。

14. 文档与运维清单

15. 推荐实施顺序与完成标准

阶段 A：管理接口骨架

Migration、Store、配额、文件存储、空快照、上传/删除/rebuild 路由。
使用假构建器验证 4 个 MVP 接口和状态轮询；前端补齐全部格式 MIME。后续阶段已让预览入口调用独立的有界 preview API。

完成标准：前端能完成文件管理和状态展示，4 个 MVP 接口不再出现 404；预览不属于本阶段完成标准。

阶段 B：真实异步建库

强制 Chunk 的个人摄取、可降级视觉补全、共享 Embedding、租户感知 Qdrant、revision reconcile、周期 snapshot、跨 Job 恢复、任务恢复和 generation 切换。

完成标准：真实 fixture 从上传到 ready，统计可核对，删除和重建无孤立可见 Point；新 Job 能从 snapshot 恢复并通过 revision 补齐最近变更。没有这条，不得宣称个人库已持久化交付。

阶段 C：Agent 检索

用户上下文检索工具、引用输出、权限和评测。

完成标准：当前用户聊天能引用个人文档，其他用户无法通过任何工具或查询路径读取该内容。

阶段 D：生产加固

单 Job 单后端/单 worker 拓扑下的限流、权限、监控、snapshot 保留清理、运维工具、容量与故障演练。

完成标准：重启、Qdrant 短暂不可用、部分写入、超限上传和删除竞态均有可重复验证结果。

阶段 E：在线预览（已完成）

content 接口、流式/Range、分格式预览器、下载和前端内存治理。

完成标准：受支持的大文件无需 bodyBytes 全量载入即可预览，权限、缓存和失败路径通过独立验收。

16. 开工前需要最终确认的决策

实现选择固定为独立 retrieve_personal_knowledge，并按 common 只读能力在学习、科研、教学三个 workspace 中开放；工具 schema 不含 user_id，执行时只使用受信任的 ToolExecutionContext.user_id。

MVP 已无待选的产品语义；部署前只需按环境完成 /persist_data 的宿主机核验，检查失败时不得静默回退临时目录。Agent 工具和 workspace 选择可以在 4 个管理接口和真实建库完成后再定；在线预览留到独立阶段讨论。

FilesExpand file tree

PERSONAL_KNOWLEDGE_BASE_IMPLEMENTATION_CHECKLIST.md

Latest commit

History