# 知识库与 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 回退并恢复迁移前备份。

## 六、已知边界

- 首次迁移已在当前开发数据库执行；其他环境仍需按同样流程单独迁移，不能只升级表结构。
- 飞书源文章变更不会自动进入正式问答，必须由超级管理员手动同步并完成审核发布。
- 模型重排依赖当前启用的大模型；模型异常时会自动使用词法排序，不阻断回答。
- 管理端业务页的完整浏览器操作验收需使用有效管理员会话；本次已完成类型检查、生产构建和后端真实数据链路验证。
