# 知识库与 Agent 检索重构实施设计

日期：2026-07-11

## 一、目标架构

```text
飞书源文章
→ 手动同步任务
→ 不可变源快照
→ 章节/搜索切片/知识卡/说明卡
→ 自动质检与定向审核
→ 不可变正式版本
→ 回答级知识目录快照
→ Agent 判断是否调用知识工具
→ 词法召回与模型重排
→ 父章节回读
→ 回答与完整检索轨迹
```

## 二、数据结构

### 2.1 扩展现有 `sys_knowledge`

新增：飞书源标题、知识库类型、审核模式、生命周期状态、源状态、说明卡确认状态、当前正式版本、待发布版本、最近同步/发布时间、迁移状态和源错误。

### 2.2 新增正式数据表

- `sys_knowledge_source_snapshot`：不可变飞书源快照。
- `sys_knowledge_version`：待审核、已发布和历史版本。
- `sys_knowledge_manifest`：知识库说明卡。
- `sys_knowledge_section`：父级完整语义章节。
- `sys_knowledge_chunk`：用于词法召回的子级切片。
- `sys_knowledge_card`：标题、摘要、适用范围、关键词、同义词、风险和来源定位。
- `sys_knowledge_review_record`：审核通过、拒绝和继承记录。
- `sys_knowledge_sync_job`：同步阶段、进度、模式、结果和异常。
- `sys_knowledge_publish_log`：发布、部分发布、回滚和开放状态影响。
- `sys_knowledge_retrieval_log`：回答级目录快照、工具轨迹、耗时和结果。
- `sys_knowledge_retrieval_candidate`：候选切片、评分、重排、采用和舍弃原因。
- `sys_human_attention_record`、`sys_human_attention_history`：人工关注及处理历史。

## 三、同步与发布

1. 仅超级管理员可以手动发起同步。
2. 同步首先读取飞书标题和全文，保存内容哈希及不可变源快照。
3. 新快照与当前正式版本源快照比较；内容未变化时生成“无变化”任务结果。
4. 程序按标题、空行、列表和长度边界形成父章节，并生成较短搜索切片。
5. 生成知识卡和说明卡；模型能力不可用时采用确定性摘要与关键词规则，任务仍可审核。
6. 自动质检检查空内容、遗漏、重复、无法追溯、异常变化、生成失败和高风险关键词。
7. 必须人工审核模式进入待审核；自动模式只有质检无阻断项且说明卡无需重新确认时才允许发布。
8. 发布在数据库事务内切换正式版本，旧正式版本保留。
9. 源文章异常时记录异常并继续保留旧正式版本。

## 四、Agent 知识工具

内部业务工具统一为：

- `get_knowledge_catalog`：返回本次回答快照中的可用说明卡。
- `search_knowledge`：执行规范化、中文词法切分、同义词扩展、多字段召回和等效 BM25 评分。
- `read_knowledge_sections`：回读候选切片所属父章节。
- `read_knowledge_document`：受限读取整篇源快照，仅供结构理解。

Agent 先根据问题和目录判断是否需要知识。课程、老师观点和公司业务问题优先使用知识；普通常识问题可以不调用知识工具。涉及知识时先搜索候选，再重排并回读完整章节，禁止直接使用短切片作为最终回答依据。

## 五、回答级快照

用户每次发送消息时固化：

- 当时开放且可用的知识库；
- 每个知识库的正式版本；
- KnowledgeList 内容哈希和版本；
- 最低安全规则版本。

本轮生成始终使用该快照。发布、开放、关闭或回滚从用户下一条消息生效。

## 六、安全与内容保护

- 最低安全规则直接由后端常量和版本号注入，优先级高于知识库和可编辑 Prompt。
- 最终用户不显示知识库名称、版本、章节、飞书链接和工具轨迹。
- 上下文限制连续原文长度，Prompt 明确禁止整篇输出和多轮拼接还原课程。
- 高风险、自伤伤人、复杂卡住、知识明显缺失或主动请求老师时创建人工关注记录。

## 七、后台改造

- 知识库管理：列表筛选、类型/审核模式、同步、开放关闭、详情、版本、发布、回滚、归档和删除。
- 版本审核：变更统计、质检项、章节/知识卡只读对比、审核通过/拒绝、部分发布。
- Agent 预览：选择任意知识库和版本，连续对话，中间聊天，右侧独立检索轨迹。
- 检索日志：按会话、知识库、版本、是否调用知识、异常筛选并查看完整轨迹。
- 人工关注：优先级、状态、关联会话、处理人、备注和历史。
- 迁移中心：6 个现有知识库的迁移统计、批量迁移、单项重试和失败原因。

## 八、切换与回退

1. 迁移前备份数据库。
2. 新表和新接口先上线，旧正式问答链路继续可用。
3. 全部现有开放知识库完成同步、审核和首次说明卡确认后，设置新检索运行时开关。
4. 切换后正式回答只走新 Agent 工具链。
5. 回退只需要关闭运行时开关并恢复数据库备份或继续读取旧服务，不删除新系统数据。

## 九、实施阶段

1. 数据库迁移与模型。
2. 飞书同步、解析、质检和版本服务。
3. 审核、发布、回滚、开放关闭和迁移接口。
4. 动态目录、Agent 工具、重排、章节回读和检索日志。
5. 正式问答链路切换和人工关注。
6. 管理后台页面升级。
7. 现有知识库迁移、联调、测试和部署。

## 十、验收门槛

- 关闭知识库无法进入正式目录和检索。
- 普通常识问题能够不调用知识工具。
- 课程问题能选中正确知识库、回读父章节并记录完整轨迹。
- 新版本、回滚和关闭从下一条消息生效。
- 飞书异常不影响旧正式版本继续服务。
- 没有正式版本或未确认首次说明卡的知识库不能开放。
- 不使用向量数据库，MySQL 可独立重建全部缓存。
- 后端测试、前端构建、数据库迁移和浏览器主流程全部通过。
