chore: 完成知识库迁移与检索验证收口

ai_knowledge_base_v2/development_records/2026-07-11-知识库与Agent检索重构实施记录.md

@@ -0,0 +1,82 @@
+# 知识库与 Agent 检索重构实施记录
+
+日期：2026-07-11
+
+## 一、实施结论
+
+本次已将旧的“遍历所有开放知识库、现场读取飞书全文、简单词法排序”链路，替换为“飞书源快照、版本审核发布、动态知识目录、Agent 按需选库、词法召回、模型重排、父章节回读、完整检索审计”链路。
+
+系统仍不使用向量数据库。飞书是唯一可编辑内容源，管理后台只展示和审核系统生成的章节、切片、知识卡和说明卡。
+
+## 二、完成内容
+
+### 2.1 知识库生命周期
+
+- 保留每个知识库的飞书 `space_id` 和 `node_id`。
+- 新增手动同步、不可变源快照、内容变化检测和同步任务记录。
+- 生成父级语义章节、搜索切片、知识卡和 Knowledge Manifest。
+- 新增自动质检、说明卡确认、版本审核、发布、回滚、开放、关闭和归档。
+- 正式检索只允许使用已开放、已发布、说明卡已确认且源状态正常的版本。
+- 知识库开放后对全体合法学员生效，不再按人分配知识库。
+
+### 2.2 Agent 检索
+
+- 每轮问题固化当时可用知识目录和版本。
+- 普通常识问题可以不调用知识工具。
+- 课程、老师、功课和学员业务问题先根据说明卡选库，不再无条件全库搜索。
+- 使用中文词法切分、同义词扩展和等效 BM25 评分，召回上限为 12 个候选。
+- 有可用大模型时执行重排，模型不可用时自动回退到词法评分。
+- 最终最多回读 4 个完整父章节，不直接把搜索短切片作为回答上下文。
+- 知识缺失、高风险或用户明确要求人工时生成人工关注记录。
+
+### 2.3 管理后台
+
+- 知识库管理已提供类型、审核模式、源状态、版本状态、同步和迁移结果。
+- 详情抽屉已提供说明卡、只读内容、版本、回滚和同步任务。
+- Agent 预览采用“配置、对话、检索轨迹”三列布局，可选知识库及版本。
+- 新增检索日志列表和详情，可查看目录快照、候选切片、评分、重排、采用或舍弃原因及最终回答。
+- 新增人工关注列表、状态处理、原会话查看和删除。
+- 新增迁移中心，支持批量迁移和单项重试。
+
+## 三、存量数据迁移结果
+
+迁移前已生成 MySQL 备份：`.uploads/db-backups/ai_kb_before_0007_20260711.sql`。
+
+6 个现有知识库已全部完成首次同步、质检、说明卡确认、审核和发布：
+
+| 知识库 | 章节 | 搜索切片 | 知识卡 | 正式版本 |
+| --- | ---: | ---: | ---: | ---: |
+| 01_七天训练营基础与大本营衔接 | 10 | 10 | 10 | V1 |
+| 02_大本营学员直接答疑表达原则 | 8 | 8 | 8 | V1 |
+| 03_大本营学员常见问题答疑素材 | 12 | 12 | 12 | V1 |
+| 04_大本营功课与练习答疑边界 | 12 | 12 | 12 | V1 |
+| 05_大本营学员安全边界与现实风险 | 12 | 12 | 12 | V1 |
+| 06_七天训练营基础术语词典_大本营学员版 | 22 | 22 | 22 | V1 |
+
+高风险主题作为质检警告保留，不屏蔽知识；实际回答仍受后端最低安全规则和人工关注机制约束。
+
+## 四、验证结果
+
+- Alembic `0007_knowledge_agent_rebuild` 完成“升级、回退到 0006、再升级”验证。
+- 后端单元测试：13 项全部通过。
+- 管理端 `vue-tsc` 和 Vite 生产构建通过。
+- 普通问题“今天北京天气怎么样？”：目录中有 6 个知识库，Agent 正确选择不调用知识库。
+- 课程问题“大本营学员做万能释放法时没有感觉，应该怎么办？”：选择 4 个相关知识库，召回 12 个候选，模型重排后回读 4 个父章节。
+- 容器已重建，后端健康检查和统一网关访问正常。
+- 管理端登录页可正常打开，账号和密码未默认回填。
+
+## 五、部署与回退
+
+1. 正式环境先备份 MySQL。
+2. 发布新后端镜像并执行 `alembic upgrade head`。
+3. 发布管理端和网关配置。
+4. 在迁移中心逐个同步、审核并发布正式版本。
+5. 检查正式知识目录数量与开放知识库数量一致后再放量。
+6. 如需回退，优先回滚应用镜像；若涉及数据结构，执行 Alembic 回退并恢复迁移前备份。
+
+## 六、已知边界
+
+- 首次迁移已在当前开发数据库执行；其他环境仍需按同样流程单独迁移，不能只升级表结构。
+- 飞书源文章变更不会自动进入正式问答，必须由超级管理员手动同步并完成审核发布。
+- 模型重排依赖当前启用的大模型；模型异常时会自动使用词法排序，不阻断回答。
+- 管理端业务页的完整浏览器操作验收需使用有效管理员会话；本次已完成类型检查、生产构建和后端真实数据链路验证。