Grounded Vault 是一种三层 Markdown 知识库约定，其核心目标是让编译出的每一条陈述都能追溯回不可变的原始来源，并让每一页都能用一次 git diff 检查是否过时。它只需要一个 git 仓库。该约定来自 llm-wiki-loop 项目，后者是参考实现而非依赖；本技能教授这套模式，使其适用于普通文件和当前会话中的任意智能体。
用途与适用场景
当智能体把笔记、论文、转录、日志或代码编译成后续会话依赖的 wiki 页面时使用。当页面引用数字、日期或引文，且读者需要能对每一条对照来源进行验证时使用。当页面描述代码，而每次会话都重读代码库来检查是否仍然成立过于昂贵时使用。当知识需要在不丢失历史的前提下被修正——被取代的页面要归档而不是删除——时使用。
需要注意，会话状态、任务队列与对话连续性属于另一个不同的问题；这类需求应使用 context-management 或 conductor 插件。本技能关注的是持久知识库上的来源可追溯性与漂移。
三层结构
raw/：原始素材，包括笔记、论文、转录、日志、导出的数据。由人和摄取流程写入。规则是：一经加入即不可变，智能体绝不编辑 raw 文件。
wiki/：由 raw/ 和代码编译而成的页面。由智能体和人类写入。规则是：每一个数字、日期和引文都链接到其来源。
archive/：发生漂移或被取代的页面。由智能体在垃圾回收时移动进入。规则是：只移动，绝不删除；页头注明原因。
仓库根目录下有两个文件。index.md 是所有当前页面的地图。log.md 是只追加的记录，说明改了什么以及为什么。两者与其所描述的页面在同一提交中变更。
页面头部契约
每个 wiki/ 页面以一个头部块开头，示例如下：
Authentication architecture
Raw: raw/notes/auth-v1.md, raw/adr/0007-jwt.md Fingerprint: git:5b237fa Monitored: src/auth/jwt.ts, src/auth/session.ts, package.json Status: Current
Raw 字段列出页面编译所依据的每一个来源。行内陈述也链接到其具体来源，例如：Tokens expire after 15 minutes (raw/adr/0007-jwt.md)。
Fingerprint 字段是页面编译时所依据的短提交哈希。
Monitored 字段列出页面所描述的代码路径。在指纹之后这些路径中的任何一个发生变化，都意味着页面可能已过时。
Status 字段的取值有 Current（当前）、Outdated（被监控的代码已变化）、Disputed（有更新的来源与页面矛盾）。
接地规则
编译出的页面只陈述有来源支撑的内容，并且每一个数字、日期或引文都逐字出现在所链接的来源中。综合性的表述要声明它是综合，并链接其输入。来源中的空白要作为空白写进页面，而不是靠猜测填补。
可以机械地检查：对每一条带链接的陈述，在所链接的 raw 文件中搜索确切的数字或引用的短语。找不到即为接地错误，会阻断提交。references/details.md 中的脚本可对整个知识库执行此检查。
漂移检测
通过与当前代码树比较指纹，而不是重读被监控的代码：
git diff --stat 5b237fa..HEAD -- src/auth/jwt.ts src/auth/session.ts package.json
输出为空表示页面仍然描述其编译时所依据的代码。有任何输出则表示需要重新编译：只重读发生变化的文件，更新页面，并打上新的指纹。该检查在毫秒级完成，且不消耗模型 token。
工作流
摄取。把新材料放入 raw/，使用带日期或带来源的文件名。绝不重写已有的 raw 文件；在其旁边新增一个。
编译。编写或更新 wiki/ 页面，包含头部块、每条陈述上的来源链接，以及读取代码时所处提交的指纹。
检查。提交前运行接地检查和漂移检查。在来源处修复未命中项；不要为了让检查通过而弱化陈述。
垃圾回收。当出现漂移或相矛盾的来源，且页面不能立即重新编译时，更改其状态，把它移入 archive/，并记录原因：
Status: Outdated Reason: src/auth/session.ts changed after git:5b237fa; see log.md 2026-09-01
更新地图。每一次新增、移动或归档，都在同一提交中更新 index.md 并向 log.md 追加一行。
提交关卡
在 pre-commit 钩子或 CI 步骤中运行两项检查，使页面无法带着无法验证的数字或过时的指纹落地：
python3 scripts/check_vault.py --strict # exits 1 on any grounding miss or drifted page
深入阅读
references/details.md 涵盖：知识库检查脚本、跨页面批量执行漂移检查、index.md 与 log.md 的模板、被监控文件的重命名或删除、二进制来源或托管在外部 URL 的来源，以及参考实现。