KB-METABOLISM · 机制图解

hooks 是怎么生效的：门的第二形态

MCP 工具靠 agent 自觉调用——它有时不会去搜。hooks 把"走门"从选择变成管道的必然：每条提问自动检索、相关就注入、不相关就沉默。本页拆解从 kb hook install 到摘要出现在模型上下文里的每一步。

为什么需要第二形态

形态一 · MCP 工具（自觉） agent 觉得需要才调 kb_search。它经常不觉得需要——直接凭训练知识回答，你的积累被绕过，笔记拿不到续命信号。

形态二 · hooks（管道） Claude Code 在每条提问进入模型之前强制运行一段外部命令。检索不再依赖 agent 的判断——它发生在 agent 思考之前。

安装那一刻发生了什么

kb hook install 只做一件事：往 Claude Code 的 ~/.claude/settings.json 写两条挂点注册（先备份 .bak；加 --project 则写当前项目的 .claude/settings.json）：

{
  "hooks": {
    "UserPromptSubmit": [{ "hooks": [{ "type": "command",
      "command": "\"/path/to/node\" \"/path/to/cli.js\" hook prompt --vault \"/你的/vault\"" }] }],
    "SessionStart":     [{ "hooks": [{ "type": "command",
      "command": "\"/path/to/node\" \"/path/to/cli.js\" hook session --vault \"/你的/vault\"" }] }]
  }
}

幂等：命令串里带 kb-metabolism 标记，重装时先移除旧条目再写新的，不会越装越多；你自己的其他 hooks 原样保留。
可逆：kb hook uninstall 按标记精确移除；kb hook show 打印配置片段供手动粘贴。
三个绝对路径被固化：node 可执行文件、cli.js、vault 目录——见下文"坑"。

每条提问的完整时序（UserPromptSubmit）

从你按下回车到模型开始思考之间，发生了这 8 步——全程毫秒级：

CLAUDE CODE你提交一条消息。在把它交给模型之前，Claude Code 发现 UserPromptSubmit 挂点上注册了命令，同步执行它，把 {"prompt": "你输入的内容", …} 以 JSON 写进该进程的 stdin。

KB 进程kb hook prompt 启动，读 stdin 拿到提问原文。

守门 · 提前退出提问不足 4 个字符 → 直接退出，零输出。（另有总闸：任何异常都被吞掉静默退出——hook 永不打断你的提问。）

KB 进程只读打开派生索引 .kb/kb.db（SQLite），跑 纯字面检索 hookSearch——刻意不走 embedding：hook 阻塞提问，不能付网络延迟。

判准（三层降级）① 整串精确命中（FTS5 trigram）→ 强相关；② 空格分词全命中（LIKE AND）；③ 自动分词评分兜底，须同时满足 idf 加权覆盖 ≥ 50%（常用字权重趋零）且至少 1 个词命中笔记标题（正文碰瓷拦截）。取 top 3。

纪律 · 宁沉默没有一篇过线 → 零输出退出。Claude Code 收到空 stdout = 什么都不注入。沉默是合格行为，不是故障。

信号记账每篇被注入的笔记追加一行 kb_inject 到 .kb/access.log.jsonl（含 query 前 80 字、路径、kb_id）——这是第三档存活证据，免死 30 天。

注入stdout 输出 <kb-context> 块（每篇一行：路径 — 标题：摘要片段，外加一句"如需全文用 kb_read"）。Claude Code 把这段文本放进本轮模型上下文——模型"未卜先知"地知道了你的相关积累。

会话开始时（SessionStart）

新会话（含 resume）第一时间注入一次 <kb-status>，内容三样：库概况（总数、L0 容量）、最近经门读过的 3 篇（按 kb_id 解析成当前路径——笔记移动过也指得到新家，给会话连续性），以及距上次消化超一周时的提醒（"请转告用户"）。库为空则沉默。

注入在信号经济里的位置

hooks 不只是便利功能——它是信号经济的一环。协议 v2 起，注入是第三档存活证据：

kb_cite

被引用进产出 · 免死 180 天

kb_read

被读取全文 · 免死 90 天

kb_inject

被注入且真相关 · 免死 30 天

search / ui

不续命

为什么注入配续命：摘要一眼够用的短笔记最有用，却恰恰因此永远不会被点开全文——v1 时代它们会被法医冤杀。为什么只有 30 天：注入是机器行为，效力必须低于人/agent 亲手读取与引用。为什么先收紧判准再给续命：判准不准，注入续命就是滥发免死金牌——顺序不能反。

三条纪律与三个坑

纪律（刻在代码里）

永不打断：任何异常静默退出——知识库坏了也不能影响你提问。
宁沉默勿碰瓷：不够相关就零输出，不制造上下文噪音。
只走字面：毫秒级零费用，绝不为注入付 embedding 延迟。

坑（使用前想清楚）

① 绝对路径固化settings.json 里的命令写死了安装时的 node、cli.js 与 vault 路径。升级 node 大版本、重装 kb、移动 vault 之后，重跑一次 kb hook install，否则 hook 静默失效（它连报错都不会——纪律①）。

② user 级 = 全局生效默认装在 ~/.claude/settings.json——你在任何项目的每条提问都会检索这个 vault 并可能注入个人笔记摘要。在意隔离就用 --project 只装到特定项目。

③ 静默失效怎么察觉正因 hook 从不报错，判断它活着的办法是看信号：kb stats／管理台信号页里有没有新的 kb_inject；或新开会话看有没有 <kb-status>。

命令速查

命令	作用
`kb hook install [--project]`	写入两条挂点（备份 .bak，幂等），新会话生效
`kb hook uninstall [--project]`	按标记精确移除
`kb hook show`	打印配置片段，手动粘贴用
`kb hook prompt / session`	挂点本体（Claude Code 调用，不需要手动跑）

源码：packages/cli/src/hooks.ts（挂点与安装）· packages/core/src/search.ts 的 hookSearch（判准）· 协议 v2 信号规则见协议规范 · 全系统一张图见设计全景