livewiki

代码锚定文档，且能感知自身何时过期。

livewiki 将一个仓库变成 Markdown wiki，其中每个代码引用都锚定到真实的索引符号。LLM 负责撰写散文；livewiki 负责确定性工作——规划页面、对模型写出的内容运行结构性反幻觉检查、追踪哪些锚定符号发生了变化，并保留你的编辑。

任何编码代理都可以通过 @livewiki/mcp 使用该 wiki——这是一个 MCP（Model Context Protocol）服务器，提供八个工具，用于阅读、搜索和安全写入 wiki。

livewiki view 会从 wiki 构建一个自包含的离线站点——分组侧边栏、离线搜索、图表和深色模式：

这是 livewiki 为 MoneyPrinterTurbo-Plus（一个外部 Python 仓库）生成的示例 wiki。

为什么

代码一变，技术文档立刻就过期了。livewiki 让这种过期变得可见且易于修复，而不是悄悄发生：

• 确定性反幻觉检查。 每个代码引用都必须指向真实的索引符号。livewiki verify 直接从磁盘读取 wiki，并对虚构的符号、失效的锚点以及不再匹配的签名报错——包括 LLM 几秒前刚刚写下的引用，无需先运行 index，也不消耗任何 token。这是结构性的，而非语义性的；下面这一节会划清界限。

• 你的编辑永远优先。 标记为 owner: human 的页面永远不会被重写，lw:manual 块会被逐字节保留。

• 文档债是被追踪的，而非事后发现。 livewiki status 对漂移程度进行排序；GitHub Action 可以用零文档债来把关每一次合并，无需消耗 token。

• 在你已经工作的地方工作。 通过你正在使用的编码代理来引导和维护，或者运行全自动批处理。

verify 检查什么——以及不检查什么

反幻觉层是确定性的、结构性的。livewiki verify 直接从磁盘读取 wiki——因此 LLM 几秒前刚写的页面也会在未先运行 index 的情况下被检查——并在以下情况报错：

• 引用的符号在代码中不存在；

• 锚点因符号被移动、重命名或删除而失效；

• 引用的签名与索引中的签名不再匹配；

• 内部链接无法解析；

• 引用的产物在磁盘上缺失；

• frontmatter 或页面结构违反格式契约。

这就在读者看到之前，以零 token 成本移除了整类虚构内容——被虚构的函数、从未存在过的 API、悄然腐化的引用。任何失败的内容都会被拒绝并回滚，而不是被合并。

但它不能证明某个句子是真实的。一个貌似合理但对真实存在的代码的错误解释，能通过上述所有检查，因为上述所有检查关注的是结构和身份，而非含义。请将这里的“反幻觉”理解为一个机械地消除一大类虚构内容、并在代码从散文下移动时立刻告诉你的层——而不是事实准确性的保证。审查解释本身仍然是你的工作。

Related MCP server: wiki-helper

快速开始

需要 Node.js 24 或更高版本。

1. 安装

npm install -g @livewiki/cli

（npx @livewiki/cli 也可以，无需全局安装。）

2. 初始化

在你想记录的仓库根目录下运行：

livewiki init

对代码建立索引，并在 livewiki/ 下创建 wiki 骨架，同时在 .livewiki/ 下创建派生缓存（已加入 .gitignore）。这是确定性的——不调用 LLM，不消耗 token。

3. 一次性引导 wiki

有两条路线——任选其一。

路线 A — 通过你的编码代理（无需 API 密钥）：

livewiki install

安装程序会检测你的代理，接入 MCP 服务器、随写随文档化技能和 git 钩子。然后让代理引导 wiki；它会从 livewiki_next_task 拉取任务，并使用它已有的模型通过 livewiki_write_doc 提交页面。

路线 B — 已配置的 LLM API（无人值守）：

livewiki config

向导会列出提供商，要求你输入 API 密钥（输入时不回显），然后保存。在未配置的仓库中直接运行 livewiki 会启动同样的向导。然后：

livewiki init --batch

可恢复的流水线会规划真实的页面单元，并为每个源文件和文件夹各写一页，外加流程、概念主题、图表和一份 understanding.md 综合总结。可以中断它，并用 livewiki batch resume <runId> 恢复。

4. 验证与浏览

livewiki verify   # validate code references, internal links, and artifacts
livewiki view     # build an offline site with search, Mermaid, and dark mode

与你的编码代理协作

livewiki install 会自动检测并接入 13 个代理（通过 MCP），在代理支持的情况下附带技能和钩子：

Claude Code · Codex · Cursor · Kimi · Gemini CLI · OpenCode · OpenClaw · Cline · Kiro · Qwen · Warp · Zed · Hermes

更喜欢手动接入？任何支持 stdio 的 MCP 客户端都可以：

{
  "mcpServers": {
    "livewiki": {
      "command": "npx",
      "args": ["-y", "@livewiki/mcp", "--repo", "/path/to/repo"]
    }
  }
}

语言

锚定页面引用真实符号；散文兜底仍然让每个文件在 wiki 中占有一席之地。一级语言支持会随着模式的验证而扩展（Go、Rust 和 Java 都是这样加入的）。

提供商

livewiki config 列出这 17 个预设。每个预设读取各自的 API 密钥环境变量；livewiki config show 会打印你的预设所期望的环境变量名，但绝不会显示其值。

ollama 和 lmstudio 在本地服务器上无需密钥。对于 CI 和无人值守自动化，直接设置环境变量即可——它优先于已保存的密钥。

生成页面的示例

摘自本仓库自身的 livewiki/core-src/verify.md：

## Discovery: walking the wiki from disk

The verifier never trusts the index for which pages exist — a doc freshly written by an LLM must be caught without first running `index`. Two walkers enumerate the `livewiki/` directory from disk; both skip hidden directories but keep dot-prefixed files.

<!-- lw:anchors packages/core/src/verify.ts#collectWikiPages packages/core/src/verify.ts#collectWikiArtifactPaths -->

```ts
async function collectWikiPages(absRoot: string): Promise<{ relPath: string }[]>
```

散文部分解释实现；lw:anchors 标记将该段落与真实索引符号绑定，因此过期和无效引用会被机械地检测出来。

工作原理

• 确定性层 —— CLI 对源码建立索引、提取符号、计算过期程度、规划工作、追踪文档债并进行验证——全程无需模型。

• 写作层 —— 已连接的代理（或由 API 驱动的批处理）从允许的符号密钥封闭列表中撰写散文。

• 反幻觉层 —— 确定且结构性：代码锚点、引用的签名、内部链接、产物和页面结构都会与磁盘对照检查；无效写入会被回滚。它消除的是虚构和腐化的引用，而非语义错误。

• 人工所有权 —— 标记为 owner: human 的页面永远不会被重写；lw:manual 块会被逐字节保留。

• 可移植基线 —— 每项文档义务的已接受状态都保存在版本化的 livewiki/.baseline.json 中，因此文档债会对照真实基线执行，并且即使本地缓存被删除，wiki 依然存在。

文档债可以在 CI 中把关每一次合并，无需 LLM 调用或 token——参见 GitHub Actions 模板。

历史对比方法和带日期结果存档于 基准测试。

包

文档

• SPEC.md — 行为与格式契约

• VISION.md — 产品原理与非目标

• docs/ROADMAP.md — 已批准的产品待办与执行顺序

许可证

MIT — 参见 LICENSE。