知识库版本管理
为什么需要版本
外卖知识经常变化：价格调整、活动过期、配送范围扩缩、菜品上下架、售后政策更新、过敏标注修订。如果没有版本管理：
- 模型某次回答出错时，无法追溯当时引用的是哪一版知识
- 商家不知道是模型问题还是知识过期问题
- 改写后效果不好无法回滚
- 跨周对比改写有效性缺乏证据
版本管理把知识库从"一份当前文档"变成"一条带时间轴的演进记录"，让运营改进可解释、可复盘、可回滚。
版本字段
kb_articles 表保留以下字段支持版本：
| 字段 | 用途 |
|---|---|
version | 自增整数，每次发布性修改 +1 |
status | draft / active / archived |
created_at | 首次创建时间 |
updated_at | 最近修改时间 |
change_log | 修改原因（自由文本） |
synonyms[] | 同义词数组（独立维护历史） |
hit_count / helpful_count / unhelpful_count | 累积命中与反馈 |
active 版本参与 RAG 检索；archived 版本保留审计、不参与检索；draft 版本仅商家可见、用于灰度测试。
版本切换规则
| 操作 | 数据库变化 | 何时使用 |
|---|---|---|
| 新建 | 新增一行 status='draft' | 候选条目入库 |
| 发布 | 草稿 status='active'，旧版本 status='archived' | 审核通过 |
| 回滚 | 旧版本 status='active'，新版本 status='archived' | 改写后效果不好 |
| 归档 | status='archived' | 失效或不再使用 |
| 重新激活 | status='archived' → 'active' | 节假日规则重新生效 |
发布操作在数据库 transaction 内完成：先把旧版本归档，再激活新版本，确保任意时刻只有一个 active 版本存在，避免检索召回多版本。
与 Prompt 的关系
知识库版本和 Prompt 版本要分开管理。两者关注不同问题：
| 维度 | 知识库版本 | Prompt 版本 |
|---|---|---|
| 回答的问题 | 事实是什么 | 如何使用事实 |
| 修改频率 | 高（每周） | 低（每月或每季度） |
| 修改责任人 | 商家 + 运营 | 产品 + AI 训练师 |
| 影响范围 | 单条召回 | 全部会话 |
当知识内容变化时（例如价格更新），不一定要改 Prompt；当同一知识被模型反复误用时（例如总把"咨询"当成"承诺"），才需要同步调整 Prompt 规则。
两者的协同点：知识库的"边界声明"（参见 03-quality）和 Prompt 的"禁止承诺清单"必须保持一致。例如知识库写"金额需老板确认"，Prompt 也必须有"不承诺具体退款金额"。
灰度发布
涉及高风险或大幅改写的知识，建议灰度发布：
- 修改后先以
status='draft'保存 - 在
/widget/demo用 3-5 种问法测试，包括边界情况 - 测试通过后再发布
- 发布后 48 小时内重点观察
hit_count、unhelpful_count、相关会话质检分
如果观察到异常（如有用率突然下降、相关 fallback 增加），立即回滚到上一版本。回滚操作只是把 archived 版本重新设为 active，不会丢失数据。
回滚案例
一个典型的回滚场景：
周一 14:00：商家把"配送范围 5 公里"改写成"配送范围 3-5 公里（高峰可能延长）"
周一 18:00：客户开始反馈"3 公里还是 5 公里到底是多少"
周一 19:30：fallback 数据显示同一问题被追问 7 次
周一 20:00：商家在后台点击"回滚到上一版"，恢复"配送范围 5 公里"
周一 20:01：旧版本重新 active，新版本归档保留
周二 上午：商家重新设计文案，分开做成两条知识：
- "配送范围多远"（5 公里）
- "高峰期会延长配送时间吗"（晚 21-23 点常延长 10-15 分钟）
整个回滚 + 重做的过程不到 24 小时，且没有任何技术介入。这正是版本管理的核心价值。
复盘价值
版本管理可以解释数据变化：
- 某周退款 FAQ 改写后，无用反馈下降 → 知识改写有效
- 某次活动更新后 fallback 上升 → 同义问法不足，需要补充
- 某条食品安全条目长期零修改但季度复核显示仍然准确 → 内容稳定，可降低复核频率
版本是运营实验的证据。配合每日聚合指标（参见 06-data/01-metrics-system），可以把"我觉得这次改写有效"变成"上周改写后有用率从 47% 提升到 71%"。
数据保留策略
归档版本保留多久？建议规则：
| 类别 | 保留期 |
|---|---|
| 食品安全 / 过敏类 | 永久 |
| 退款 / 售后类 | 3 年 |
| 价格 / 活动类 | 1 年 |
| 营业 / 配送类 | 2 年 |
| 其他 | 1 年 |
保留期满后才允许物理删除，删除需要单独审计日志。这样在出现客户投诉"两年前你们的退款规则不是这样"时，仍能追溯当时的有效规则。