HandbookBrain：让每条公司规则都有据可查的图数据库大脑

当新员工问“为什么七月底试用期MQL下降”，她可能要在四十个聊天线程、会议录音、多次编辑的文档和CRM字段之间翻找，仍说不清“谁决定了什么、为什么”。这正是HandbookBrain要解决的问题：它把公司规则背后的决策路径建成一张可追溯、可版本化的知识图谱。

决策跑得比文档快

商业规则总在变：线索评分阈值调整、Deal Desk新增检查、合作伙伴续约规则反转。决策发生在会议或Slack线程里，文档却可能几周后才更新，甚至永远不更新。依赖旧规则的答案、文档、CRM字段和仪表盘随之悄悄出错。传统搜索只能找到一份文档，而真正需要的是路径：会议 → 决策 → 决策人 → 实施变更的提交 → 变更的章节版本 → 所有依赖它的东西。这是图问题，就该用图来解决。

HandbookBrain在FalkorDB上维护一张版本化知识图谱，容纳公司文档、会议与聊天、实施决策的合并请求，以及文档触及的系统、CRM字段、指标和仪表盘。一个智能体在此之上工作，回答“X如何运作、为什么”，并引用所用章节的精确版本，附带回到会议、决策人和合并请求的线索。

数据模型：三个关键设计

整个设计围绕三个理念展开。

以章节而非文档为版本单位。页面被拆成章节，每次变更创建一个新的Section节点，通过SUPERSEDES指向旧版本，并带有valid_from/valid_to。没有内容被覆盖，因此可以“按任意日期”读取图谱，被删除的规则依然可查。

答案是节点。一个Answer节点CITES它使用的确切章节版本。正是这条边让后续变更能找到它破坏的答案。

决策是一等公民。每个决策从会议、聊天或工单中提取，带发言人和逐字引用，链接到相关章节，并通过读取diff与实施提交对账。核心关系可以简化为：

Conversation <-DECIDED_IN- Decision -DECIDED_BY-> Person
Decision -IMPLEMENTED_BY-> Commit <-MERGED_AS- MergeRequest
Commit -CHANGED-> Section -SUPERSEDES-> older Section
Page -HAS_SECTION-> Section -MENTIONS-> System | Field | Metric | Dashboard
Answer -CITES-> Section     Answer -ANSWERS-> Question
Answer -INVALIDATED_BY / REVALIDATED_BY-> Commit

SUPERSEDES 链与时间点查询：SUPERSEDES 是一条有向边，从新 Section 指向它替换的旧版本，与 valid_from/valid_to 一对时间戳配合，构成一条可回溯的版本链。读取“任意日期”的图谱时，只需筛选 valid_from <= D AND (valid_to IS NULL OR valid_to > D) 的节点，即可还原当时生效的章节；被删除的规则对应一条 valid_to 已闭合、没有后继的 Section，因此仍可被检索和引用。这种“只追加、不覆盖”的存储方式，使每次变更都留下不可变的审计痕迹，也为后文“这次变更破坏了哪些答案”的遍历提供了图结构基础。

用Cypher回答“为什么”和“坏了什么”

“为什么是这样？”是从章节回到会议的一条路径。查询从Section出发，经Commit、Decision找到Conversation，并可选地返回决策人姓名与实施时间。

“这次变更破坏了哪些答案？”从提交出发，回退到每个答案引用的版本，并返回旧文本与新文本供基于diff的裁判使用。关键处理是：如果变更是“removed”，则引用的是当前章节本身；否则引用前一个版本。

“还有什么依赖这次变更？”从变更走到它提到的字段和指标，再走到所有其他当前文档及其负责人。条件是o.valid_to IS NULL且路径不同，从而找出仍在生效但共享相同系统实体的页面。

检索是混合式的，全部在FalkorDB内完成：章节嵌入的向量索引，加上标题与正文的全文本索引，用倒数排名融合，并过滤到当前版本。向量、全文和图遍历在同一个数据库里，意味着没有第二个存储要同步。智能体是一个工具调用循环，封装10个参数化只读Cypher工具；每条断言必须携带工具实际返回的引用，由代码检查。一个运行在不同模型上的审查者只看问题、证据和草稿，可以打回重写。

倒数排名融合（Reciprocal Rank Fusion, RRF）：混合检索会把向量相似度与全文检索的排序结果合并，RRF 是常用的无参数融合方法。它对每个文档在每一路结果中的名次取 1/(k + rank)（k 通常取 60）再求和，按总分重排。相比直接相加不同量纲的分数，RRF 只依赖名次，无需归一化，能稳健地平衡语义召回与关键词精确匹配。在本项目中，章节嵌入的向量索引与标题/正文全文本索引各产生一份排名，RRF 融合后再过滤到 valid_to IS NULL 的当前版本，确保检索结果既语义相关又版本有效。

Maya的问题，一次回答

重放演示中，试用阈值的故事这样展开：5月21日，真实MR !19600在Marketo页面添加“Trial Threshold Scoring”，HandbookBrain将其链接到13天前的一场（合成）市场运营会议。6月1日，新分析师问“试用用户多少分成为MQL？”答案是25分，引用该章节版本。7月17日，（合成）市场运营周会决定提高阈值。7月23日，真实MR !20534将25改为31。6月1日的答案被diff判定为过时，CODEOWNERS中的负责人收到通知，答案刷新为31，并附上会议、决策人和MR。Maya问一个问题，得到整条路径。

用独立来源审计图谱

无法验证的答案引擎是负债。作者写了一个审计，用智能体从不读取的来源核对站点展示内容。变更日期、MR编号、版本链对照git log，2562/2562通过；决策人、地点、引用对照会议记录，21/21通过；文档负责人对照CODEOWNERS，122/122通过；决策到实施MR的链接对照隐藏标签，0个错误链接。审计还抓到了真问题：最初的决策到MR裁判过于宽松，把三个决策链接到后来不相关的变更；现在只认diff中实际改变的内容。

诚实地评估智能体

作者最初的头条数字是“89% vs 0%”，针对“为什么”类问题对比普通RAG基线。看起来很棒，但不公平：逐事实检查后发现，普通检索找会议日期和决策人的能力和智能体一样好，它得0%只是因为合并请求根本不在其数据中。

于是按Anthropic的《Demystifying evals for AI agents》重建评估：尽可能用代码评分器，只对开放答案用模型裁判；包含应回答和应拒绝的问题；每题3次试验，关闭LLM缓存。还加入更强的基线“RAG + git log”，获得完整合并日志文本。

29个问题×3次试验的结果：HandbookBrain总体87%，RAG + git log为66%，普通RAG为59%。在“说出实施决策的MR”上，HandbookBrain 18/18，RAG + git log仅4/18，普通RAG为0/18。在“变更规则的旧/新值”上，HandbookBrain 15/15，RAG + git log为9/15，普通RAG为6/15。会议日期三者都是18/18；普通查找三者都是70%。

这些数字说明：找到会议是检索问题，检索能解决。图真正增加的是“决策到实施变更的链接”和“版本历史”，包括被删除的规则。即使把整个合并日志放进上下文，模型也很少能自己把会议匹配到正确的MR。在普通查找上，图没有帮助，智能体更慢也更贵。作者也坦承局限：问题来自单一数据集，且在看过这些问题的失败后修过智能体，新问题上数字会更低。

评估还发现了真实bug：一个名为“Trial Threshold Scoring”的章节被埋在泛泛的“MQL and Lead Scoring”下，导致智能体回答100而不是31，修复方式是搜索中加入标题匹配候选；宽Markdown表格被按列误读，修复方式是行线性化；从页面删除的规则不可见，修复方式是搜索也返回说过更多的旧版本及删除它的MR；只在Slack中商定的规则被当作政策并附上手冊引用，修复方式是标记为“仅在聊天中说过”，智能体必须说明。

模型裁判（LLM-as-judge）与代码评分器：开放式答案难以用精确匹配打分，常用做法是让另一个模型依据评分标准判断答案是否正确、是否引用了足够证据。但模型裁判存在位置偏差、冗长偏好和自洽偏差，因此 Anthropic 的建议是：凡能用确定性代码验证的（如数值、MR 编号、是否包含引用）一律用代码评分器；只有真正开放的表述才交给模型裁判，并固定裁判模型、提供参考证据、必要时多次采样取多数。文中“每题 3 次试验、关闭 LLM 缓存”正是为了降低随机性、让分数可复现，避免缓存命中掩盖智能体的真实波动。

学到的东西

让答案成为节点。一旦答案引用精确版本，“这次变更破坏了什么”就是一次遍历，而不是猜测。在章节级别做版本。整文档版本太粗，无法判断变更影响哪个答案。逐事实衡量，并对公平基线。聚合分数会掩盖图在何处有帮助、何处没有；诚实的表格比好看的表格更有说服力。用独立来源审计LLM构建的边。提取链接的模型不应同时是评分者。

下一步

直接连接器（Slack、Zoom、Drive）替代导出，录音转文字；把CRM和BI元数据（Salesforce字段、Power BI / Tableau仪表盘）作为一等节点；对已批准的更新直接开合并请求，而不只是记录签核。项目使用FalkorDB、Python、FastAPI和LiteLLM构建，大部分代码在作者指导与审查下由AI编程助手Claude编写。

如果你们团队的规则散落在五个工具里，没人记得它们为什么存在，这个思路值得参考：把决策、实现和文档放进同一张图，让“为什么”变成一条可走的路径。