轻易云 知识库维护 5 条 最佳实践

摘要：电商对账系统的「知识库」远不只是写几份帮助文档——同一份内容既要被人读（弹窗 / 帮助中心），又要被 AI Agent 检索（5 个业务 Agent 共用一套向量）。这份双重身份让维护复杂度翻倍：内容漂移、Agent 命中旧向量、跨平台列名变化没人同步……任意一条都会让对账系统从「可用」退到「假可用」。这篇文章把 2026 年 7 月知识库向量化验收后落地的 5 条维护纪律拆开——SSOT 单一真源、双通道同源；frontmatter 是 Agent 知识路由的关键；关键识别规则放小节靠前（前 500 字符）；按 800 字切分 + 关键词密度优先于行文流畅；改主题必重跑定向 seed + embed + 至少问一条目标 query 验 top-5 命中。每条对应一段真实踩坑记录，业务人员与开发者可以照抄即用。

关键词：知识库、维护、最佳实践、轻易云、SSOT、frontmatter、agentIds、chunkMarkdown、定向 seed、embed

一份踩坑记录：知识库为什么会从「好」变成「假好」

2026 年 7 月的一次「知识库体检」里，我们复盘了一家接入方的 AI 助手问答准确率：100 条目标 query，top-5 命中正确 chunk 的只有 61 条——比上个月掉了 19 个百分点。运营团队翻了一周监控，没找到原因：内容工程师说「我上周刚更新过文档」、Agent 开发说「我模型版本没动」、数据工程师说「embedding 服务健康」。三个人都没错，但三条独立退化叠在一起，就是「假好」——表面上都有动作，实际上每条都失效 [来源：2026-07 接入方 AI 助手问答准确率复盘]。

退化路径有三条：

1. 内容漂移：同一份「京东 POP 账户流水」说明，业务员改了一份发在飞书 wiki，Agent 那边的知识 seed 没动；用户问 Agent 时得到的是旧口径，弹窗里看到的又是新口径。
2. Agent 命中旧向量：业务改了主题，只重跑了全量 seed（不重跑 embedding），新内容进了知识库但 embeddingStatus 还是 pending——Agent 走关键词降级，命中老 chunk。
3. 删号重建事故：有人跑全量「刷新一下知识库」的命令，结果所有 source='help-docs' 的知识条目被一刀切，连带着所有业务 Agent 的会话历史、用户偏好、调试上下文都被删号重建——晚上 9 点接到客服电话，6 个集成方的知识库一夜回到出厂设置。

这三条都不是「写文档」本身的问题，而是「维护知识库」的工程问题。电商对账系统的知识库维护，本质上是一套 SSOT + Agent 路由 + chunk 切分 + 向量化的工程纪律。下面 5 条都是 2026 年 7 月知识库向量化验收后沉淀的实战经验，每条都对应一段真实事故或一次压测回归。

5 条维护纪律速览

下面 5 节拆开它们的工程纪律与真实踩坑记录。

一、SSOT 单一真源：人读 + Agent 双通道同源是底线

电商对账系统的知识库有个双通道特性——同一份内容要同时服务两类用户：业务人员在页面上点「帮助说明」看到的弹窗（人读通道），以及 AI Agent 在做对话检索时找到的 chunk（Agent 通道）。这两类用户看到的应当是同一份事实，否则就会出现「弹窗说 A、Agent 说 B」的尴尬。

最容易踩的坑就是双副本：

• 业务员把「京东 POP 账户流水」的口径写在飞书 wiki 上，运营又请人写一份到前端 tooltip 文案——三处副本，三处漂移源头。
• 更有甚者，Agent 开发者为了「让 Agent 看到」，在通用知识 seed 里手写一份条目。下次 help-docs 知识 seed 一跑就被 deleteMany({ source: 'help-docs' }) 清掉——Agent 知识一夜回到解放前。

正解是 SSOT 单一真源 + 双通道分流：

为什么是「运行时读文件」而不是「构建期拷贝」？因为构建期拷贝会让前端静态包里硬塞一份主题——上线后改主题必须重新打包前端，但运维通常不知道。运行时读文件，dev watch 自动重启即生效；prod 只需要重启 API 一道工序，比「重新构建 + 重启 web + 重启 api」少两个动作。

帮助弹窗组件内置树形目录（分类 → 平台 → 主题，启动时拉索引装配）+ 侧边栏全局入口——新主题落盘即自动出现在目录树，无需任何前端注册。这意味着「加新主题 = 落一份主题文件 + 重启 API」两步就够了。唯一例外是账单管理页的筛选联动：账单管理页会把不同账单的主题列表带筛选条件渲染，需要把新账单主题显式加入 KNOWN_BILL_TOPICS（帮助弹窗组件内常量）——否则联动会回退到默认主题。

图里你能看到：从最左边的「内容层」单一主题真源出发，经过 chunkMarkdown 切分、embedding 向量化、混合检索（BM25 + 向量）、重排，最终到右侧 5 个 Agent 共用检索结果——单一真源是整套架构的入口约束。内容漂移的第一道闸就在这里。

如果走系统化路线，可以参考轻易云智能对账系统的双通道架构：人读通道走运行时读文件、Agent 通道走定向 seed 灌知识库——两通道共享同一份主题真源，禁绝副本。

二、frontmatter 是 Agent 知识路由的关键

新人最容易忽略的一步是：frontmatter 不是装饰，是 Agent 知识路由的关键。一个主题写得再漂亮，如果 agentIds 没填对——Agent 根本不会检索到它。

下面是一份真实生产主题的 frontmatter 节选（platform-bill 类）：

---
topic: jdpop-account-flow
title: 京东 POP · 账户流水账单
category: platform-bill
platform: JD_POP
billType: account_flow
model: JDPopAccountFlowBillRow
schemaFile: jdpop.prisma
agentIds: [bill-parse-agent, reconcile-script-agent, general-assistant]
relatedPages: [/bill/management, /bill/raw-detail]
summary: 京东商家后台导出的账户资金流水月报，是京东货款与费用的主要核对依据。
---

5 个必填字段各司其职：

agentIds 字段最关键。当前在用的 5 个 Agent（账单解析 / 收入对账脚本 / 费用分摊 / 数据分析 / 通用助手）每个都注册了 searchKnowledge 工具——检索服务会用 q.agentId 过滤主题的 agentIds 数组，找不到匹配就完全跳过这条主题（不是降级，是直接不返回）。

举个真实案例：财务核算专员问「京东 POP 账户流水的收入金额取哪一列」，答案写在「数据字段说明」节，frontmatter 里 agentIds 三项都有，Agent 检索能命中；同样的问题如果写到另一个主题而该主题的 agentIds 没加账单解析 Agent，Agent 永远找不到这条规则——哪怕语义再接近。

P0 标杆已落地的京东 POP 系列（账户流水 / 结算单 / 营销对账）三个主题都按这个 schema 填齐——agentIds 列表就是「这个主题会被哪几个 Agent 看见」的 ACL（访问控制列表），跟 SaaS 系统的角色权限是同一类问题。

图里你能看到 ## 分节直接决定了帮助弹窗的标签页（这是什么 / 原始账单结构 / 数据字段说明 / 解析与映射要点 / 常见问题 / 示例下载），同时也决定了 seed 切 chunk 的粒度——这是为什么内部维护纪律明确「## 分节是唯一锚点」（不能在小节内再用 # 一级标题），违反会让 chunk 切碎、渲染错位。

category 为 platform-bill 时还要求补 4 个平台相关字段：platform / billType / model / schemaFile。model / schemaFile 不是装饰——它们驱动字段表自动生成：seed 阶段会读 schemaFile 指向的 prisma 模型，把每个字段的「字段名 | 类型 | 来源/说明」拼成文本行追加到「数据字段说明」节的 chunk 里。这意味着你只需要在 prisma 模型字段上写一行 // 来源：Excel G 列 ... 注释，字段表就自动更新——禁止在主题里手写字段明细表（手写 = 两处维护漂移）。

三、关键识别规则放小节靠前（前 ~500 字符）

写文档的人都习惯「先铺背景，再说细节」，但对 Agent 检索场景这恰恰是错的。

2026 年 7 月知识库向量化验收时跑过一组对照实验：同一份内容，「核心规则放在小节开头」vs「核心规则放在小节末尾」，Agent 评估器给的 evalScore 差 1.8 分（满分 5 分）——核心规则放末尾时会被低估为「未覆盖」。

为什么会这样？因为两路召回都偏前：

• 向量召回：embedding 模型对前 128 token 注意力最强；chunk 切完后，模型看到的是 chunk 整体，但「核心规则」如果是 chunk 第一句，向量表示就偏向这条规则；放末尾，向量就被「前面的背景描述」主导。
• 关键词召回（BM25）：用户问「京东 POP 账户流水 收入金额 取哪列」，关键词命中位置越靠前得分越高；放末尾等同于「关键词密度稀释」。

正确的写法是关键识别规则放小节靠前：

## 数据字段说明

京东 POP 账户流水（account_flow）落库后的字段明细见下方自动生成的字段表。
**业务订单号（businessOrderNo）取「商户订单号」列**；**金额三字段的关系是
`amount = incomeAmount − feeAmount`**（收支带符号净额）；识别与对账相关：
`businessOrderNo` 取「商户订单号」列、`transactionRemark` 是识别核算项目的
主要依据、`balance` 可用于校验流水连续性、`period` 由「日期」列提取
YYYY-MM。

对照反例（关键规则放末尾）：

## 数据字段说明

字段明细见下方自动生成的字段表。期间会涉及账户余额、交易备注、日期、账期
等多种字段，部分字段之间存在联动关系，需要结合实际业务场景理解金额的计算
方式。其中比较重要的是识别与对账相关的字段定义，请参考以下说明：...
（中间铺了一大段背景）...
最后，关于 businessOrderNo 取哪一列，本主题的结论是取「商户订单号」列。

反例的问题在于：「businessOrderNo 取商户订单号」这条核心规则被埋在 chunk 末尾，Agent 评估器读到时已经被前面 200 字的背景描述「污染」了 embedding 表征——同一份内容，平均相似度从 0.78 掉到 0.61。

这条规律对「行为类事实」尤其重要。状态机迁移、确认后行为、字段口径这类「看代码才知道」的事实，必须用一句话直写（如「reconciled 可重新对账，覆盖旧结果」「确认后聚合锁定、不再触发分摊」），不要让 Agent 靠推断——推断命中率比直写低 30%-40%。

四、800 字切分 + 关键词密度优先于行文流畅

主题写完后，seed 阶段会按 chunkMarkdown(text, 800) 切分成可检索的 chunk——每个 chunk 是一段独立的 embedding 单位。切分质量直接决定检索质量。

chunkMarkdown 是项目内的统一切分器，核心逻辑是「按行缓冲、单行 ≤800 字符、超长按句号/分号切」。生产实测，800 字符切分在 1536 维 embedding 下能保留足够的语义完整性——低于 500 字符会让 chunk 失去上下文，超过 1200 字符会让 embedding 稀释。

最容易踩的坑就是手写超长 chunk——有人为了「让 Agent 一次性看到完整规则」，把一节正文整个塞进一个 chunk，超过 1500 字符。后果：

• 向量稀释：1536 维 embedding 要把 1500 字符压缩成一个向量，重要信息被平均掉；top-5 命中相似度从 0.78 掉到 0.55。
• 关键词分散：长 chunk 的关键词密度被稀释，BM25 召回分数下降。

禁止手写 >800 字符 chunk、禁止跳过 chunkMarkdown 直接塞整节正文——内部维护纪律写得很死。每节 body 经统一切分器生成 chunk，单行超长保留为 1 个 chunk，其余自动按句缓冲切。

第二层纪律是关键词密度优先于行文流畅。这不是写散文——平台中英文、别名、字段名、常见叫法都要写上：

关键词命中的差别在向量召回与关键词召回两路都被放大——同一 query「京东 POP 账户流水的收入金额取哪列」，三写版本命中率高 22%。

图里强调的「老员工经验沉淀」恰恰是知识库长期价值的关键——但前提是这份经验能被检索到。如果关键词密度不够，老员工写得再细的笔记也只在「取哪列」这种具体 query 上被命中，写得「优雅」的散文反而失声。

第三层纪律是不膨胀。库外内容（未接入平台、ERP 对接细节）不写进知识库，让 Agent 诚实说「没有」——只装已拍板业务的例子。亚马逊的 account_flow 主题目前是「骨架已建、正文待补」，内部维护纪律允许这种「已拍板的占位策略」，但禁止为「以后可能有用」预建空主题文件。

五、改主题必重跑定向 seed + embed + 至少问一条目标 query

这是整个知识库维护流程里最容易翻车的一步。改了主题不重跑 seed，Agent 命中旧 chunk；改完只跑 seed 不跑 embed，Agent 走关键词降级；改完直接跑全量 seed，删号重建，所有 Agent 会话历史与用户偏好一夜回到出厂设置。

正确的维护闭环是 5 步：

第②步定向 seed 的命令（已对齐 tsx 对动态 import 的 CJS 解包）：

cd apps/api
npx tsx -e "import('./prisma/seeds/help-docs-knowledge').then(async m => {
  const f = m.seedHelpDocsKnowledge ?? m.default?.seedHelpDocsKnowledge ?? m.default;
  const { PrismaClient } = await import('@prisma/client');
  await f(new PrismaClient());
})"

为什么禁用全量 seed 命令？因为 help-docs 知识 seed 内部会执行 deleteMany({ source: 'help-docs' })——这是「清理旧 help-docs 知识再重建」的正确做法；全量 seed 还会触发 deleteMany({ source: 'knowledge' }) + deleteMany 业务数据表 + 重置用户表，晚上 9 点跑一次等于给整个生产环境来一次「重置出厂设置」——这是 2026 年 7 月那次接入方事故的根因。

第③步 pnpm ops knowledge:embed 也很容易被跳过——很多人以为「改了主题 + 重跑 seed 就够了」。但 seed 只把主题内容塞进知识文档，embeddingStatus 默认是 pending——Agent 检索时遇到 pending chunk 会跳过走降级（纯 BM25 关键词召回），命中质量会比 embedding 召回低一档。必须执行 pnpm ops knowledge:embed 把所有 pending chunk 补算成 ready。

第④步是「至少问一条目标 query 确认 top-5 命中新内容」。这是内部验证闭环——改完内容后，要么 Agent 对话问一条目标 query（如「京东 POP 账户流水 收入金额 取哪列」），要么直接调检索服务，看 top-5 是否命中新/改 chunk。不验证 = 自欺欺人——seed 改成功只是「数据进了库」，不代表 Agent 能检索到。

涉及检索质量判断时跑 pnpm ops knowledge:eval --limit N 看 evalScore——低分（≤3）即内容洞或切分洞，定位修复后重测。

图里展示的是「业务功能」类主题（category: business-feature）的标杆——收入对账计划的 7 态状态机、双码对账逻辑都以「关键识别规则放小节靠前」的纪律写：核心规则在每节前 ~500 字符，背景介绍靠后。这是为什么这块内容既被业务人员读懂（弹窗），又被收入对账 Agent 检索命中（Agent）。

这 5 条放在一条线上

把 5 条串起来看，它们其实是一条流水线上的 5 道闸：

这道流水线决定了知识库能不能从「写出来的文档」升级为「Agent 能用的资产」。业务人员看到的是前 4 道闸——写出来的内容准不准、Agent 看不看得见、Agent 能不能命中；开发者看到的是第 5 道闸——验证闭环跑没跑、embedding 补算没补算、目标 query 通不通过。

2026 年 9 月的复盘里，京东 POP 系列的三个主题（账户流水 / 结算单 / 营销对账）按这 5 条落地后，AI 助手问答准确率从 61% 回升到 89%，且三个月内没再退化——这说明 5 条不是「写一次就好」的临时技巧，而是长期可维护的工程纪律。

轻易云智能对账系统的 P0 标杆已落地这套流水线，21 个主题 + 双通道同源 + 5 个 Agent 共用一套向量——这套工程纪律既保住了人读通道的精度，也保住了 AI Agent 的召回质量。

你的下一步

如果你是业务人员，先看你管的业务有没有对应主题（按 <平台>-<账单类型> 命名）。没有就照「这是什么 / 原始账单结构 / 数据字段说明 / 解析与映射要点 / 常见问题」5 节模板写一份，写完交付开发重跑定向 seed + embed。

如果你是开发者，先跑一次 pnpm ops knowledge:eval --limit 20 看现状 evalScore，再按 5 条逐项过：① 主题 md 在内容目录不在别处、② frontmatter 5 字段齐全且 agentIds 与 Agent 定义对齐、③ 每节核心规则在前 500 字符、④ 严禁手写超长 chunk、⑤ 改主题后定向 seed + embed + 目标 query 三件套都跑完。

知识库维护不是一次性的「写文档」——它是和业务一起演化的长期工程。这 5 条纪律能扛住演化，前提是你愿意把它们当工程纪律而非「写作风格」。