用三层 Markdown…

当 agent 从原始资料编译出 wiki 页面、需要每条数字/引用可回溯到不可变来源，并能用一次 git diff 廉价检测页面是否过时时使用。

适用场景

解决思路

1. 采用三层目录结构：raw/ 存放源材料（笔记、论文、转录、日志、导出数据），只由人或摄取流程写入，加入后不可变，agent 永不编辑 raw 文件；wiki/ 存放从 raw/ 和代码编译出的页面，由 agent 和人写入，每个数字、日期、引用都必须链接到来源；archive/ 存放已漂移或被取代的页面，由 agent 在垃圾回收时移入，只移动不删除，并在头部说明原因。
2. 在库根放置两个文件：index.md 作为所有当前页面的地图，log.md 作为只追加的变更与原因记录；两者必须与其描述的页面在同一次提交中一起变更。
3. 每个 wiki/ 页面开头写头部块，包含：Raw: 列出编译该页面的所有来源；Fingerprint: 编译时对应的短提交哈希；Monitored: 该页面描述的代码路径列表；Status: Current、Outdated（被监控代码已变化）或 Disputed（有更新的来源与页面矛盾）。
4. 在正文内联声明处也链接到具体来源，例如：Tokens expire after 15 minutes ([raw/adr/0007-jwt.md](../raw/adr/0007-jwt.md))。
5. 遵守 grounding 规则：编译页面只陈述来源支持的内容，每个数字、日期或引文必须逐字出现在所链接的来源中；综合内容要声明自己是综合并链接其输入；来源中的空白要写成空白，不能靠猜测填补。
6. 机械校验 grounding：对每条带链接的声明，在链接的 raw 文件中搜索完全一致的数字或引文短语；未命中即为 grounding 错误，阻止提交；references/details.md 中的脚本可对整个库执行此检查。
7. 用指纹与当前代码树比较来检测漂移，而不是重读被监控代码：运行 git diff --stat 5b237fa..HEAD -- src/auth/jwt.ts src/auth/session.ts package.json；输出为空表示页面仍描述其编译时的代码，有任何输出则表示需要重新编译：只重读变更的文件、更新页面并打上新指纹；该检查只需毫秒且不消耗模型 token。
8. 按工作流执行：1) 摄取——把新材料放入 raw/，使用带日期或来源的文件名，绝不重写已有 raw 文件，而是在旁边新增一个；2) 编译——写入或更新 wiki/ 页面，包含头部块、每条声明上的来源链接，以及读取代码时所在提交的指纹；3) 检查——提交前运行 grounding 检查和漂移检查，在来源处修复未命中，不要为了通过检查而弱化声明；4) 垃圾回收——当出现漂移或矛盾来源且当前不重新编译时，修改状态、移入 archive/ 并记录原因，例如：> Status: Outdated > Reason: src/auth/session.ts changed after git:5b237fa; see log.md 2026-09-01；5) 更新地图——每次新增、移动或归档都在同一次提交中更新 index.md 并向 log.md 追加一行。
9. 在 pre-commit hook 或 CI 步骤中运行两项检查，防止带有不可验证数字或过时指纹的页面进入仓库：python3 scripts/check_vault.py --strict（任何 grounding 未命中或漂移页面都会以 1 退出）。
10. 需要更深入时查阅 references/details.md，其中涵盖：vault 检查脚本、跨页面批量漂移检查、index.md 与 log.md 模板、被监控文件被重命名或删除的情况、二进制或位于外部 URL 的来源，以及参考实现。

适用边界 · 注意事项

• 会话状态、任务队列和对话连续性属于不同问题，应使用 context-management 或 conductor 插件，而不是本技能。
• 本技能关注持久知识库的来源可追溯与漂移，不适用于不需要来源验证或漂移检测的临时笔记。