知识库

五个知识文件，按「谁能写」分工

KB 的形态是一组 YAML，人可读可改，也是唯一真源。运行时另有一份 SQLite 镜像 （kb.sqlite，带 FTS5 虚拟表）——但镜像只服务检索， 删掉它可以从 YAML 重建，反过来则不行。

service.py:3 human-editable service.py:530 _parse_file merge.py:54 纯人工文件

同目录下的另外两个文件

它们住在同一个目录、同一套 git 版本管理之下，但不属于上面那五个「知识」文件—— 前者是策略不是知识，后者还不是真源。

service.py:1123 save_decisions decisions.py:648 put_decisions manage.py:1129 create_draft

把它们折进「知识」里会糊掉一件事：已确认的事实与待确认的变更 不是同一种东西。判定规则与草案各自有别的消费者，也各有自己的确认门。 判定规则的完整机制见判定规则。

/kb init：能确定性生成的才生成

初始化一个数据源的 KB，走的是一条确定性优先的流水线。 顺序上先做不花钱的部分，再让 LLM 润色：

1. 读活库 schema（表、列、类型）。
2. 没有 LLM 凭证时的降级路径：只写一份 schema_notes.yml 骨架并返回提示，让人补注释后 /kb reload。
3. 枚举采样与列统计画像（这一步会真的查库）。
4. LLM 起草表/列注释。
5. 确定性生成词表与模板——generate_terms / generate_templates。
6. 合成示例，生成语义模型结构。
7. LLM 起草同义词与描述。
8. 原子写盘：三个文件连续写、中间不 await——避免留下写了一半的 KB。

init_pipeline.py:441 init_kb deterministic_gen.py:460 generate_terms deterministic_gen.py:623 generate_templates semantic_gen.py:210 generate_semantic_document

产出的文件是三个：schema_notes.yml、semantics.yml、examples.yml。 rules.yml 与 lessons.yml 不在其中—— 前者的原因是上面说的分工，后者是反馈路径首次写入时才创建。

init_pipeline.py:438 INIT_FILES

/kb learn：把一次好的问答固化下来

交互式的沉淀路径是半自动的：模型从上一轮对话起草一条示例（外加候选术语）， 把草稿展示出来，只有用户明确确认才写盘。

kb_cmds.py:49 _cmd_learn service.py:2487 append_example service.py:2495 append_term

注意这里的确认与后面的「两档门禁」不是同一件事：/kb learn --yes 是当下的人工确认， 写进去就是 confirmed；而自动回写的示例进来时是 pending，需要另一次确认。 区别在来源——人当场看过并点过头的，和系统自己觉得不错的，不该同等对待。

检索：先确定性过滤，再打分

检索的入口在图上（一次问答会并行取示例、教训、术语、指标、实体）， 每条通道内部都遵循同一条原则：先用确定性规则排除不可能的，再排序。

graphs.py:470 search_examples service.py:1537 search_examples service.py:1595 _rank_examples

最重要的那条过滤是表锚定：语义链接阶段已经算出了这个问题涉及哪些表 （matched_tables），那么一条示例如果提到了别的表，它就不该被检索到—— 哪怕文字上再像。这是一个纯确定性的判断，不依赖任何模型。

service.py:1618 keep service.py:411 _lesson_table_ok

排序分由几路信号合成：术语命中、标签命中、词重叠、表锚定加分， 再乘上聚合/日期模板的折扣（模板类示例的泛化性弱一些，不该压过具体示例）。 与检索通道给出的相似度做融合时，权重是 0.5——这个数字是刻意的中庸值， 因为确定性打分和向量相似度各有所长，谁压倒谁都不合适。

service.py:289 _score_example service.py:462 _fuse_extra_sim

教训的排序多两个因子：投票与时效。 一条被反复验证有效的教训应当排前面，一条很久没被触发的教训应当淡出—— 后者用衰减函数实现，而不是靠人工清理。

service.py:1775 _rank_lessons service.py:445 _recency_factor

镜像与 FTS

YAML 是给人读的，逐条扫描它做检索太慢，所以运行时维护一份 SQLite 镜像。 FTS5 虚拟表是 contentless 的——它只存索引，元数据列标为 UNINDEXED， rowid 与镜像表的主键对齐。

service.py:122 _CREATE_FTS service.py:1180 _ensure_mirror_schema service.py:934 _sync_file_fts

在 PostgreSQL 生产环境里，检索不走这条 SQLite 路径，而是切到 pg_hybrid 后端—— 切换逻辑见 混合检索。两者的分界点是配置与能力探测， 不是数据源类型。

取值画像：让「枚举」这件事有依据

很多问数错误来自取值层的误解：「华东区」到底是 '华东' 还是 'east'？ 状态字段有哪些合法值？这些不属于 schema，但决定了 SQL 里的字面量写什么。

画像流程对每个可疑列做一次取值采样，取 Top-K 高频值与频次，连同形状判断 （是枚举？是 ID？是自由文本？）一起合并进 schema_notes.yml 的 stats。

profiling.py:31 TOP_VALUES_LIMIT profiling.py:55 detect_shape profiling.py:195 _probe_top_values profiling.py:253 merge_into_stats

独立脚本 scripts/probe_enums.py 做同一件事，但带两道护栏： 行数上限与超时。因为「对一亿行的大表做全表 GROUP BY」是一个很容易写出来、 又很容易把生产库拖垮的操作。

enum_probe.py:37 DEFAULT_MAX_ROWS enum_probe.py:48 probe_enums

lint：把 KB 的问题在提问之前发现

scripts/lint_kb.py 是专门挑 KB 毛病的静态检查工具 （另有一把专查「抄 gold」的尺子，见本节末尾）。 它检查的都是「不报错但会一直悄悄降低准确率」的问题：

live_lint.py:19 check_enums live_lint.py:47 check_undocumented_columns

最后一条尤其值得注意：漏掉一个枚举值不会让任何查询报错， 它只会让「状态 = C 的那批」这类问题永远算错——因为编译器认为 'C' 不是一个合法取值。 这类错误没有报错信号，只能靠主动比对发现。

同一套检查还有个写盘前的门禁版本：语义模型的写入路径在落盘之前先跑一遍 lint_semantics，只要有 issue 就 raise——不落盘、不刷新检索镜像， 坏语义根本进不了 KB。命令行上的 lint_kb.py 是给整套 KB 做体检， 这里挡的是「这一次写入」。

两档门禁：pending 不进检索

所有自动写入的内容默认是 pending。读侧的过滤器是硬的： 待确认的示例直接跳过，教训列表默认只返回 confirmed。

flowchart TB
    Q["提问 → 回答"]:::entry --> D{"这条内容从哪来"}:::entry
    D -- "人当场点头（/kb learn --yes）" --> K
    D -- "自动回写 / 蒸馏" --> P["pending 草稿
示例 · 教训"]:::entry
    P --> G{"管理端确认"}:::gate
    G -- "确认" --> K[("KB YAML
examples / lessons")]:::entry
    G -- "拒绝" --> X["丢弃"]:::entry
    K --> R["检索：先表锚定过滤，再打分"]:::exec
    R --> Q
    classDef entry fill:#71717a14,stroke:#71717a59,stroke-width:1px;
    classDef exec fill:#14b8a614,stroke:#14b8a699,stroke-width:1.5px;
    classDef gate fill:#f59e0b14,stroke:#f59e0b99,stroke-width:1.5px;
    linkStyle 7 stroke:#8b5cf6,stroke-width:1.5px

service.py:617 pending 草稿不参与检索 service.py:1725 confirmed_only service.py:1823 setdefault

service.py:1900 confirm_pending_lessons service.py:2003 confirm_pending_examples service.py:2221 reject_lesson

1 2 3 4

1. 1待审批 KPI——数字即缺口：6 条待审，拆开是教训 2 · 示例 4。待审的不是「脏数据」，是还没人背书的内容。
2. 2tab 行的数字是过滤器——待审批 / 资产 / 术语与指标 / 示例 / 教训 / 规则，每一类各自计数；点哪个数字就按哪一类过滤。
3. 3每条待审项带着它是怎么来的——来源（用户投票 / 自动捕获）、时间、票数 ▲1 · ▼0 与置信度（这条 0% 照实显示，不粉饰），下面一行是它的说明；这条教训卡还写明确认后的去向：进 Hint Bank 检索、注入后续生成的上下文。
4. 4逐条处置：确认 / 编辑后确认 / 拒绝——确认写入认证块（批准人 / 时间）并进入检索；「编辑后确认」是让确认人先改再背书，而不是先背书再指望有人回来修。

资产治理：这条 SQL 是谁确认的

确认不只是一个布尔开关。示例条目带五个治理维度， 在确认的那一刻逐条写进 examples.yml——与 SQL 同一份文件，随 git 一起回滚：

governance.py:36 GOVERNANCE_FIELDS service.py:2003 confirm_pending_examples

• 存量条目不迁移：库里已有的几百条示例都在加载期推断成 draft，而不是一次性往盘上写几百行 status: draft——那既是没有信息量的写盘，也会让「这条资产被谁验过」的第一次记录变成机器批量盖的章。推断出来的 draft 与写在盘上的 draft 对检索含义完全相同。
• 认证门在写盘之前：确认走一批之前先校验，坏 SQL 会让整批被拒（ExampleCertificationError），不做「跳过坏的、确认其余的」——部分确认会让 confirmed 这个词本身失去意义。配套的一条纪律（I5）：certified 必须有人，机器不能自己给自己背书。
• _meta 来源块：每份生成物落盘时写 format / generator / generated_at / digest，回答「我是哪一版生成的」和「生成之后有人动过我吗」。读侧有个版本门：比自己新的格式直接拒绝——按旧解释读一份新格式的文件，产出的不是一个「少读几个字段」的模型，而是一个错的语义模型，它会进编译器、进权威 SQL、进答案。没有 _meta 的存量文件按 format 0 处理（按当前解释读），所以升级不会一次停摆。

一条会咬人的约束：KB 语言要跟着问题语言走

这是一个实测过一次的定性结论，值得写在这里而不是埋在文档角落： KB 内容的语言应当与提问语言一致。用中文 KB 去回答英文问题时， 准确率会明显下降，而且主要缺口不在生成、在少样本检索的命中—— 检索不到对的示例，后面再强也没用。

继续读