llm-wiki-compiler新鲜度机制：检测过期页面并用refresh --stale自动修复知识（完整教程）

llm-wiki-compiler新鲜度机制：检测过期页面并用refresh --stale自动修复知识（完整教程）

【免费下载链接】llm-wiki-compilerThe knowledge compiler. Raw sources in, interlinked wiki out. Inspired by Karpathy's LLM Wiki pattern.项目地址: https://gitcode.com/gh_mirrors/ll/llm-wiki-compiler

llm-wiki-compiler 是一款"知识编译器"：把原始文档（Markdown、PDF、网页等）编译成相互链接的 Wiki。它内置的**新鲜度机制（source freshness）**通过内容哈希自动检测过期页面（stale pages）和孤儿页面（orphaned pages），并可用一条llmwiki refresh --stale命令自动修复，无需全量重编译。本文带你从零理解这套机制，并手把手完成检测与修复 🛠️。

环境准备：如何快速安装并运行 llmwiki

开始之前，先花 1 分钟把环境搭好：

下图是 llmwiki 从原始资料到可浏览 Wiki 的完整演示 🎬：

新鲜度机制原理：llmwiki 如何追踪知识是否过期？

核心思路非常轻巧，只有两句话：

1. 编译时记账：每次llmwiki compile都会把每个来源文件的内容哈希和"归属关系"（哪个来源生成了哪些页面）写入.llmwiki/state.json。
2. 使用时对账：之后任何需要检查新鲜度的命令，都会重新读取磁盘上的sources/目录，把当前哈希与记录逐一对比——不一致就说明页面"过期"了。

整个过程按需计算、无后台守护进程：没有常驻 watcher，每次命令只对哈希计算一遍，结果被 lint、status、查看器、MCP 工具等所有出口共享，绝不重复计算。

状态判定规则（定义见 src/freshness/types.ts）：

💡 小知识：由llmwiki query --save保存的问答页面永远标记为unverified——它们是生成的答案，不是来源的投影，不参与新鲜度判定。

如何快速定位过期页面：5 个检测入口

llmwiki 的新鲜度信号会自动扩散到所有输出面，你不需要专门跑一个"新鲜度检查"命令：

1️⃣llmwiki lint——列出每一条stale-page/orphaned-page结果，指明受影响页面和具体来源文件，并计入llmwiki eval的健康分。

2️⃣llmwiki status——最直观的"体检报告"，示例输出：

! Stale: 3 page(s): transformer, self-attention, positional-encoding — run `llmwiki refresh --stale` ~ Pending changes: 2 source(s) awaiting compile — run `llmwiki compile` ! State: missing — no compile has run yet — run `llmwiki compile`

3️⃣ 本地查看器（llmwiki view）——页面元数据栏显示 STALE / ORPHANED 徽章，Concepts 列表用新鲜度圆点标记并支持按状态筛选，顶部横幅报告全库结论（见下方 Scientific Clay 主题效果）：

4️⃣ MCP / JSON 导出——get_context_pack证据包和export --target json的每条页面记录都带freshnessStatus字段，下游 Agent 知道哪些页面可能过期。

5️⃣llmwiki next——当存在过期页面时，它会主动推荐你运行llmwiki refresh --stale，把修复动作"推"到你面前。

refresh --stale 自动修复教程：4 步把过期页面修回新鲜状态

这是本文的重点。llmwiki refresh --stale是定向修复命令，只做三件事：

• 只重编译"变了的"来源——只有拥有过期页面的变更来源会走两阶段 LLM 流水线；新加入、从未编译的来源会被刻意跳过（那种情况请运行llmwiki compile）；
• 清理孤儿页面——所有来源都被删的页面直接从wiki/移除，此过程零 LLM 调用、无需 API key；
• 不碰无关页面——来源没变的页面保持原样，省钱省时间。

第 1 步：先看看哪些页面过期了

llmwiki lint

关注stale-page和orphaned-page两条规则的结果。

第 2 步：用 --dry-run 预览修复计划（强烈推荐）

llmwiki refresh --stale --dry-run

dry-run 会打印完整计划——哪些来源将被重编译、哪些孤儿页面将被删除——不发起任何 LLM 调用、不写任何文件。确认范围无误再动真格。

第 3 步：执行真正的修复

llmwiki refresh --stale

如果你的项目配置了审核策略（.llmwiki/config.json中的review.hold），refresh 会像 compile 一样遵守它：触发拦截条件的页面会进入.llmwiki/candidates/候选队列，而不是直接写入wiki/——配置解析失败时直接中止，绝不悄悄关闭策略（fail-closed）。

第 4 步：再次 lint 验证

llmwiki lint

确认没有 stale / orphaned 结果即修复完成。如果仍有残留，检查是否混入了"从未编译的新来源"，如有则运行一次llmwiki compile。

常见问题：状态文件损坏怎么办？

如果.llmwiki/state.json丢失或 JSON 无效，llmwiki不会悄悄创建备份或回退到空状态，而是明确报错：

• lint和status报告stateStatus: "missing"或"corrupt"，所有页面标记为unverified；
• 查看器顶部显示状态损坏横幅；
• refresh --stale会报告损坏并拒绝继续。

修复方式只有一条：重新全量编译重建状态文件 🔄：

llmwiki compile

完成后新鲜度追踪自动恢复正常。

⏱️防过期小贴士：日常编辑时挂一个llmwiki watch即可——它监视sources/目录，文件一保存就自动触发增量重编译，让页面边写边新，从源头避免过期积累。

延伸阅读

• 过期页面官方排障文档：docs/troubleshooting/stale-pages.mdx
• compile 与 refresh 完整 CLI 参考：docs/cli/compile.mdx
• status 命令参考：docs/cli/status.mdx
• 新鲜度核心类型定义：src/freshness/types.ts、src/freshness/index.ts
• 工作原理详解：docs/concepts/how-it-works.mdx

【免费下载链接】llm-wiki-compilerThe knowledge compiler. Raw sources in, interlinked wiki out. Inspired by Karpathy's LLM Wiki pattern.项目地址: https://gitcode.com/gh_mirrors/ll/llm-wiki-compiler