关于 grounded-vault
用于在基于 Git 的三层 Markdown 知识库中维护持久资料，编译出的内容可追溯至不可变源文件。适合整理笔记或代码文档的 Agent 与人员，并提供来源依据和内容漂移检查。
主要功能
- 01raw、wiki、archive 三层结构
- 02编译内容附来源链接
- 03提交指纹与监控路径
- 04来源依据与漂移检查
- 05追加式变更日志
适用场景
- 01根据笔记或论文构建可追溯的 Wiki
- 02核对数字和引文是否对应源文件
- 03发现因代码变化而过时的文档
- 04归档已被取代的页面并保留历史
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/grounded-vault确认已加载。
附带文件references/details.md
详细介绍
Grounded Vault
Grounded Vault 是一个三层 Markdown 存储，其中每一条编译后的论断都能追溯到不可变的来源，每个页面都能用一次 git diff 检查是否过时。它只需要一个 git 仓库，别无其他。这一约定来自 llm-wiki-loop 项目，该项目是参考实现而非依赖；本技能教授的是这一模式，因此它能与普通文件以及会话中的任何 Agent 配合使用。
何时使用
- Agent 将笔记、论文、转录稿、日志或代码编译成后续会话依赖的 wiki 页面。
- 页面引用了数字、日期或引文，读者必须能够对照来源逐一核实。
- 页面描述代码，而每次会话都重读代码库来检查它们是否仍然成立，代价太高。
- 知识必须在不丢失历史的情况下得到更正：被取代的页面会被归档，绝不删除。
会话状态、任务队列和对话连续性是另一个问题；这些请使用 context-management 或 conductor 插件。本技能关注的是持久知识存储上的来源追溯与漂移。
三个层
| 层 | 内容 | 由谁写入 | 规则 |
|---|---|---|---|
raw/ | 来源材料：笔记、论文、转录稿、日志、导出的数据 | 仅由人员和摄取流程写入 | 加入后即不可变；Agent 绝不编辑 raw 文件 |
wiki/ | 由 raw/ 和代码编译而成的页面 | Agent 和人员 | 每个数字、日期和引文都链接到其来源 |
archive/ | 已漂移或被取代的页面 | Agent，在垃圾回收期间 | 移动，绝不删除；头部说明原因 |
两个文件位于 vault 根目录。index.md 是所有当前页面的地图。log.md 是记录变更内容及原因的仅追加日志。二者都与它们所描述的页面在同一次提交中变更。
页面头部约定
每个 wiki/ 页面都以一个头部块开头：
# Authentication architecture
> Raw: [raw/notes/auth-v1.md](../raw/notes/auth-v1.md), [raw/adr/0007-jwt.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](../raw/adr/0007-jwt.md)).Fingerprint:是页面编译时所对应的短提交哈希。Monitored:列出页面所描述的代码路径。在 fingerprint 之后其中任何路径发生变更，都意味着页面可能已过时。Status:为Current、Outdated（受监控的代码已向前演进）或Disputed（更新的来源与页面相矛盾）。
有据可依规则
编译后的页面只陈述来源支持的内容，且每个数字、日期或引文都逐字出现在所链接的来源中。综述会说明自己是综述，并链接其输入。来源中的缺口会作为缺口写入页面，而不是靠猜测填补。
机械地检查它：对每一条带链接的论断，在所链接的 raw 文件中搜索确切的数字或引文短语。找不到即为有据可依错误，会阻止提交。references/details.md 中的脚本可对整个 vault 执行此检查。
漂移检测
将 fingerprint 与当前目录树比较，而不是重读受监控的代码：
git diff --stat 5b237fa..HEAD -- src/auth/jwt.ts src/auth/session.ts package.json
输出为空意味着页面仍然描述着它所编译所依据的代码。有任何输出就意味着需要重新编译：只重读已变更的文件，更新页面，并盖上新的 fingerprint。该检查在毫秒内运行，且不消耗任何模型 token。
工作流
-
收录。 将新素材放入
raw/，文件名带日期或来源。绝不重写已有的 raw 文件；在其旁边新增一个。 -
编译。 编写或更新
wiki/页面，包含头部信息块、每条论断的来源链接，以及读取代码时所处提交的指纹。 -
检查。 在提交前运行 grounding check 和 drift check。在源头修复遗漏；不要为了让检查通过而弱化论断。
-
垃圾回收。 当出现 drift 或相互矛盾的来源，且该页面当前不重新编译时，更改其状态，将其移入
archive/，并记录原因：> Status: Outdated > Reason: src/auth/session.ts changed after git:5b237fa; see log.md 2026-09-01 -
更新地图。 每一次新增、移动或归档，都要在同一次提交中更新
index.md，并向log.md追加一行。
提交门禁
从 pre-commit hook 或 CI 步骤中运行这两项检查，这样页面就不会带着无法核实的数字或过期的指纹落地：
python3 scripts/check_vault.py --strict # exits 1 on any grounding miss or drifted page
深入阅读
references/details.md 涵盖：vault check 脚本、跨页面批量运行 drift check、index.md 和 log.md 的模板、被监控文件的重命名或删除、二进制来源或位于外部 URL 的来源，以及参考实现。