# 知识库与 Agent 检索重构现状评估

日期：2026-07-11

## 一、现有系统数据流

当前正式问答链路为：

```text
用户发送问题
→ 查询所有 status=1 的 sys_knowledge
→ 并发读取所有知识库对应的飞书文章
→ 对文章内容进行简单词法打分
→ 取前 5 个短内容
→ 机械拼接进 Prompt
→ 调用已启用模型生成回答
→ 将命中的内容写入 AI 请求日志
```

当前 `KnowledgeAccessService.get_allowed_knowledge()` 仅判断 `sys_knowledge.status=1`，没有正式版本、说明卡确认、源异常或发布状态校验。

## 二、现有数据与功能

### 2.1 可复用部分

- `sys_knowledge.id`：可以继续作为稳定知识库 ID。
- `name`：继续作为后台显示名称。
- `feishu_space_id`、`feishu_node_id`：业务含义保持不变，一篇飞书文章对应一个知识库。
- `status`：兼容为知识库开放状态。
- 飞书 AppID、AppSecret、异步 HTTP、Redis 缓存能力可以复用。
- 现有模型配置、Prompt、用户会话、流式回答、排队、审计日志和管理后台框架可以复用。
- 现有 Agent 预览入口可以保留并升级。

### 2.2 当前运行数据

- 当前知识库数量：6。
- 当前开放知识库数量：6。
- 当前 Alembic 版本：`0006_expand_ai_request_log_text`。
- 所有现有知识库均已保存 `space_id/node_id`，可直接进入迁移流水线。

## 三、主要问题

1. 每次问题都无条件读取全部开放知识库，Agent 没有自主判断过程。
2. 飞书文章是运行时直接读取，没有不可变源快照，无法稳定回滚或复现。
3. 没有知识版本、审核、发布、部分发布和回滚能力。
4. 搜索单元和回答依据没有分层，短切片可能直接成为最终上下文。
5. 没有 Knowledge Manifest，Agent 不知道各知识库用途、适用范围和边界。
6. 当前简单打分缺少中文分词、同义词扩展、多字段权重和模型重排。
7. AI 请求日志只能看到最终注入片段，无法还原目录、检索词、候选、舍弃原因、章节回读和冲突处理。
8. 关闭知识库只依赖单字段，没有“必须已发布、说明卡已确认、源数据正常”的组合约束。
9. 飞书源异常会直接影响当前请求，没有“继续使用上一正式版本”的稳定机制。
10. 后台知识库管理仍是简单 CRUD，缺少同步进度、版本审核、发布、迁移和检索追踪。

## 四、兼容原则

- 不使用向量数据库。
- 不更换 Vue 3、FastAPI、SQLAlchemy、MySQL、Redis 和现有模型调用技术栈。
- 不改变一篇飞书文章对应一个知识库的业务结构。
- 不改变 `space_id/node_id` 的业务含义。
- 不删除或重建现有知识库 ID。
- 不影响现有用户会话、用户登录、模型配置和流式接口协议。
- Redis 只保存可重建缓存，正式知识、版本和检索轨迹全部保存在 MySQL。
- 重构完成前保留旧检索服务作为受控回退，迁移完成并切换后正式链路不再调用旧机械注入逻辑。

## 五、风险判断

### 必须当前处理

- 版本和源快照不可变性。
- 发布原子性和回答级知识快照。
- 关闭知识库不进入正式目录和检索。
- 检索日志可追溯。
- 迁移未完成时不得切换新链路。
- 最低安全规则必须独立且不可关闭。

### 可采用稳健一期实现

- 中文词法检索先采用可维护的分词、同义词和 BM25 等效评分，不引入外部检索集群。
- 模型重排采用现有已启用 LLM 的结构化判断；失败时回退词法排序并明确记录。
- 语义章节先按文档标题、段落、列表结构切分，再由模型边界能力增强；模型失败时保留程序切分结果。

## 六、结论

现有项目可以原位升级，不需要新建项目或替换技术栈。重构应围绕 `sys_knowledge` 增量扩展正式版本体系，并将正式回答入口从 `AsyncRagService` 的“全库读取后注入”切换为回答快照驱动的 Agent 知识工具编排。
