docs: 完成知识库与Agent重构设计

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

@@ -0,0 +1,119 @@
+# 知识库与 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 可独立重建全部缓存。
+- 后端测试、前端构建、数据库迁移和浏览器主流程全部通过。

ai_knowledge_base_v2/development_records/2026-07-11-知识库与Agent检索重构现状评估.md

@@ -0,0 +1,84 @@
+# 知识库与 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 知识工具编排。