企业官网建设流程全解析

llm-wiki-compiler 常见问题与故障排查指南：过期页面修复、状态恢复、Embedding 失败与性能调优完整清单

【免费下载链接】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（llmwiki）是一个「知识编译器」：输入原始资料（URL、文档、笔记、PDF），输出可交叉引用、可语义检索的 Markdown Wiki。本文面向新手，汇总了一份llm-wiki-compiler 常见问题与故障排查清单，覆盖四大高频场景：过期页面（Stale Pages）的检测与修复、state.json状态损坏或版本过新的恢复、Embedding 嵌入失败的排查与恢复，以及编译慢、检索退化时的性能调优参数。照着清单自查，基本能解决 90% 的日常故障 🔧

一、排障第一步：用 status 与 lint 摸清项目状态

遇到任何异常，先别急着重新编译。llmwiki 提供了三个只读的诊断入口，它们不调用 LLM、不需要 API Key，全部基于磁盘状态实时计算：

一个健康项目的status输出形如：

llmwiki status # ✓ Fresh: no stale or orphaned pages # ✓ State: ok

若出现State: missing — run llmwiki compile或State: corrupt，说明状态文件有问题，直接跳到第三节处理。更多细节见 docs/cli/status.mdx 与 docs/troubleshooting/faq.mdx。

二、过期页面（Stale Pages）与孤儿页面：检测与一键修复

💡核心机制：每个 wiki 页面在编译时都会记录「由哪些源文件生成 + 内容哈希」。之后每次执行命令，llmwiki 都会把记录的哈希与sources/磁盘现状对比——这就是源新鲜度追踪。

两种新鲜度状态怎么区分

• Stale（过期）：源文件还在，但内容改了；或多源页面中部分源被删除。页面还能读，但可能已不代表最新资料。
• Orphaned（孤儿）：生成该页面的所有源文件都被删除了，页面已无法再生，是清理候选。

⚠️ 注意：llmwiki query --save保存的问答页是生成答案，永远不会被标记为过期。

三步修复流程（推荐顺序）

第 1 步：查看哪些页面过期

llmwiki lint # 关注规则名 stale-page 与 orphaned-page 的结果

第 2 步：预览修复计划（零成本）

llmwiki refresh --stale --dry-run

--dry-run只打印计划——哪些源会重编译、哪些孤儿页会被删除——不发生任何 LLM 调用，不写盘。

第 3 步：执行修复

llmwiki refresh --stale

它只做三件事：重编译「变更且拥有过期页」的源、清理孤儿页面（纯文件操作、免 API Key）、不碰无关页面。若所有过期页都是孤儿（只是删源文件），整个修复甚至不需要配置任何凭证。

防止问题积累：编辑期间保持llmwiki watch运行，文件一保存就自动增量重编译，过期页几乎不会堆积。完整的生命周期说明见 docs/troubleshooting/stale-pages.mdx。

📌 小提示：llmwiki view打开的 Viewer 会在页面元数据栏显示STALE / ORPHANED徽标，顶部横幅显示整库新鲜度判定——不敲命令也能肉眼发现过期页。

三、state.json 损坏或被新版本写入：两种恢复路径

.llmwiki/state.json是增量编译的账本，带有 schemaversion字段。当它由更新版本的 llmwiki 写入（比如同事用了新版本编译过），当前构建会故意失败关闭并报错：

.llmwiki/state.json (version 3) was written by a newer llmwiki version (this build understands up to version 2). Upgrade llmwiki to read this project.

这是设计好的安全行为：宁可不读，也不冒险误读或覆盖。你有两条路可走：

路线 A：升级 llmwiki（推荐）

npm install -g llm-wiki-compiler@latest

升级后直接读取现有状态，增量编译记录完整保留。

路线 B：重置状态文件（保留备份）

llmwiki state reset # 先预览，不做任何修改 llmwiki state reset --yes # 确认执行：备份为 state.json.bak 后移除原文件 llmwiki compile # 从当前 sources/ 重建状态

state reset --yes直接操作原始字节、从不解析状态文件，因此即使文件「太新或损坏」也能可靠执行。原内容原子备份在.llmwiki/state.json.bak，以后升级了版本还可以改回去。

状态缺失或 JSON 损坏时：lint和status会报告stateStatus: missing / corrupt并把所有页面标为unverified，Viewer 顶部出现损坏横幅。恢复方法统一是重新完整编译：

llmwiki compile

官方恢复手册见 docs/troubleshooting/state-recovery.mdx，新鲜度判定算法的源码位于 src/freshness/。

四、Embedding 失败：从报错到恢复的完整排查

4.1 最常见：ProviderUnavailableError

跑compile时若报ProviderUnavailableError，含义是找不到有效的 LLM 凭证——此时没有任何 LLM 调用发生、没有写入任何内容，可安全重试。排查顺序：

1. 默认 Anthropic 供应商：确认ANTHROPIC_API_KEY或ANTHROPIC_AUTH_TOKEN已设置（二选一即可）。
2. 若已配置本地 Claude Code（~/.claude/settings.json的env块），裸跑llmwiki compile应自动兜底读取。
3. 不想用 API Key？可切换到免 Key 方案：LLMWIKI_PROVIDER=claude-agent（用本地 Claude Code 登录）、ollama（本地模型）或copilot。

4.2 query 检索不到相关内容

llmwiki query的语义检索依赖嵌入索引（.llmwiki/embeddings.bin或embeddings.json）。索引缺失时会自动降级为纯词法（BM25）检索——能用，但排序质量下降。常见原因：

• 当前供应商不支持嵌入：copilot与claude-agent不暴露嵌入端点。claude-agent可设VOYAGE_API_KEY开启；或显式指定LLMWIKI_EMBEDDING_PROVIDER（如ollama，免 Key）。
• 全新项目：先跑一次llmwiki compile，页面与嵌入会一起构建。

⚠️ 若报embedding-store-unavailable，说明索引文件存在但无法加载（损坏）。不要删除二进制索引去回退旧 JSON 快照——正确做法是执行llmwiki compile，它会自动发现缺失向量并重建（注意：重建会消耗嵌入 API 额度，隔离页除外）。

4.3 嵌入重试与隔离（Quarantine）机制

嵌入生成失败时，llmwiki 在.llmwiki/pending-embeddings.json中记录持久化重试预算：同内容连续 5 次失败后，页面被移入.llmwiki/quarantined-embeddings.json，后续刷新跳过它，让其他页面正常嵌入。内容一旦变化，会以全新预算自动重试。

排查信号看status输出的告警码：

• embeddings-refresh-pending：等待再次嵌入的页面
• embeddings-refresh-quarantined：已耗尽重试、被隔离的页面

修复供应商后的正确重置姿势：① 确认没有 compile/refresh 在运行；② 从两个标记文件中移除该页面条目（重置全部则删除两个文件）；③ 重新llmwiki compile。注意：只改嵌入配置不会清除隔离状态。

4.4 切换嵌入后端会重建整个索引

索引会记录生产它的供应商、模型与端点。修改LLMWIKI_EMBEDDING_PROVIDER/LLMWIKI_EMBEDDING_MODEL/ 端点后，即使没有任何源变更，下次 compile 也会重新嵌入全部合格页面（有 API 成本）。不同后端产出的向量不可比较，重建前 query 会报告索引过时并退回词法排序。例外：anthropic与claude-agent之间切换不重建（二者走同一 Voyage 模型）。

五、性能调优清单：让 compile 更快、检索更稳

✅ 首次编译慢是正常现象（所有源要走「概念提取 → 页面生成」两阶段流水线）；之后的编译是增量的，未变更语料通常几秒完成。想进一步优化，按此清单逐项检查：

四条实用策略：

1. 小步快跑：大语料先用llmwiki quickstart <单个源>跑通，再增量加入其余源。
2. 换更快的模型：设LLMWIKI_MODEL为供应商的轻量模型变体。
3. 大索引自动走二进制存储：超过 64 MiB 的 JSON 上限后自动切换embeddings.bin，无需手动干预（上限：512 MiB 文件 / 10 万条记录）。
4. 编辑期开 watch：llmwiki watch实时增量重编译，避免积压。

完整变量参考（含调试开关LLMWIKI_DEBUG）见 docs/configuration/environment-variables.mdx。

六、症状速查表

七、相关文档与源码路径

• 故障排查 FAQ：docs/troubleshooting/faq.mdx
• 过期页面检测与修复：docs/troubleshooting/stale-pages.mdx
• 状态版本恢复手册：docs/troubleshooting/state-recovery.mdx
• 环境变量全参考（嵌入重试与隔离、存储上限）：docs/configuration/environment-variables.mdx
• status 命令输出字段：docs/cli/status.mdx
• 新鲜度追踪实现：src/freshness/
• lint 规则实现：src/linter/

🧭 记住排障口诀：先看status定方向，再用lint定页面，dry-run预览后才动手，compile兜底一切状态问题。

【免费下载链接】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