livewiki

livewiki

与代码锚定的文档，能及时发现内容何时过时。

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

通过 @livewiki/mcp，任何编码 Agent 都可以访问该知识库；它是一个带有八种工具的 MCP（Model Context Protocol）服务，用于读取、搜索和安全写入知识库。

livewiki view 会根据知识库构建一个自包含的离线网站，包含分组侧边栏、离线搜索、图表和深色模式：

livewiki 为 MoneyPrinterTurbo-Plus（一个外部 Python 代码仓库）生成的知识库示例。

---

为什么选择 livewiki

代码一变，技术文档就会过时。livewiki 会让这一点清晰可见，并降低修复成本，而不是让问题悄无声息地累积：

• 确定性反幻觉检查。 每个代码引用都必须指向一个真实的已索引符号。livewiki verify 会直接从磁盘读取最新知识库；如果发现虚构符号、失效锚点或不再匹配的签名，就会报错——即便这些引用是 LLM 几秒前写下的，也无需先运行 index，更不会消耗 token。它检查的是结构，而非语义；下文会说明界限。
• 你的编辑优先。 标记为 owner: human 的页面绝不会被重写，lw:manual 区块会逐字节保留。
• 跟踪技术债，而不是等它暴露。 livewiki status 会按优先级列出发生偏移的内容；GitHub Action 可以在每次合并时检查文档债务是否为零，且不消耗 token。
• 融入你现有的工作方式。 通过你使用的编码 Agent 初始化并维护知识库，也可以运行完全自动化的批处理。

verify 检查什么——不检查什么

反幻觉层采用确定性的结构检查。livewiki verify 会直接从磁盘读取最新知识库——因此，LLM 几秒前写下的页面无需先运行 index 也会受到检查——并会对以下问题报错：

• 引用的符号在代码中不存在；
• 符号移动、重命名或删除后导致锚点失效；
• 引用的签名与已索引签名不再匹配；
• 内部链接无法解析；
• 磁盘上缺少被引用的文件；
• frontmatter 或页面结构违反格式约定。

这样一来，读者看到内容之前，就能以零 token 成本消除一整类编造内容——虚构的函数、从未存在过的 API、悄然失效的引用。任何未通过检查的内容都会被拒绝并回滚，而不会合并。

它不能证明某句话是真的。对确实存在的代码作出看似合理但错误的解释，仍能通过上述所有检查，因为这些检查针对的是结构和标识，而非含义。这里的“反幻觉”指的是：通过机械检查消除大量编造内容，并在代码发生变化时立即告知你——而非保证事实准确性。解释本身仍需由你审阅。

快速开始

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

1. 安装

npm install -g @livewiki/cli

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

2. 初始化

在你要生成文档的仓库根目录中：

livewiki init

此命令会为代码建立索引，并在 livewiki/ 下创建 Wiki 框架，同时在 .livewiki/ 下创建派生缓存（已添加到 .gitignore）。结果具有确定性——不会调用 LLM，也不消耗令牌。

3. 首次初始化 Wiki

有两种方式，任选其一。

方式 A——通过你的编码 Agent（无需 API 密钥）：

livewiki install

安装程序会检测你的 Agent，并配置 MCP 服务、边编写文档边记录的技能，以及 Git 钩子。然后让 Agent 初始化 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

兼容你的编码 Agent

livewiki install 会通过 MCP 自动检测并配置 13 种 Agent（对于支持的 Agent，还会配置技能和钩子）：

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"]
    }
  }
}

此服务也已发布到官方 MCP Registry，名称为 io.github.eduardoabreu81/livewiki。因此，能够从 Registry 解析服务的客户端可以按名称找到它，无需使用上面的配置片段。

语言

语言	带锚点的文档（已提取符号）
TypeScript	✅ .ts
JavaScript	✅ .js .mjs .cjs
TSX / JSX	✅ .tsx .jsx
Python	✅ .py
Go	✅ .go
Rust	✅ .rs
Java	✅ .java
其他所有语言	基础文本支持——遍历每个文本文件，并将其作为文本记录到文档中，不提取符号

带锚点的页面会引用实际符号；基础文本支持仍会确保每个文件在 Wiki 中都有位置。随着模式得到验证，一级语言支持会逐步扩展（Go、Rust 和 Java 均以这种方式加入）。

提供商

livewiki config 会列出以下 17 个预设。每个预设都会读取自己的 API 密钥环境变量；livewiki config show 会显示该预设所需的环境变量，但绝不会显示其值。

提供商	预设	环境变量
Anthropic	anthropic	ANTHROPIC_API_KEY
OpenAI	openai	OPENAI_API_KEY
OpenRouter	openrouter	OPENROUTER_API_KEY
DeepSeek	deepseek	DEEPSEEK_API_KEY
Kimi (Moonshot)	kimi	MOONSHOT_API_KEY
MiniMax	minimax	MiniMax_API_KEY
Google Gemini	gemini	GEMINI_API_KEY
NVIDIA	nvidia	NVIDIA_API_KEY
Ollama （本地）	ollama	OLLAMA_API_KEY （可选）
LM Studio （本地）	lmstudio	LMSTUDIO_API_KEY （可选）
Fireworks	fireworks	FIREWORKS_API_KEY
Novita	novita	NOVITA_API_KEY
GMI	gmi	GMI_API_KEY
StepFun	stepfun	STEPFUN_API_KEY
Hugging Face	huggingface	HF_TOKEN
xAI	xai	XAI_API_KEY
Alibaba (DashScope)	alibaba	DASHSCOPE_API_KEY

本地服务上的 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.



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

正文解释了实现方式；lw:anchors 标记将此部分关联到实际的索引符号，因此可以通过机制检测过时内容和无效引用。

工作原理

• 确定性层 — CLI 为源代码建立索引、提取符号、计算陈旧度、规划工作、跟踪债务并进行验证，全程无需模型。
• 编写层 — 已连接的 Agent（或由 API 支持的批处理）根据允许使用的符号键列表编写文案。
• 防幻觉层 — 采用确定性和结构化方式：代码锚点、引用的签名、内部链接、产物和页面结构都会与磁盘上的内容核对；无效写入会回滚。它能消除伪造和过时的引用，但无法避免语义错误。
• 人工所有权 — owner: human 页面绝不会被重写；lw:manual 块会按字节原样保留。
• 可移植基线 — 每项文档义务的已接受状态都保存在版本化的 livewiki/.baseline.json 中，因此债务会依据真实基线强制执行，即使本地缓存被删除，Wiki 也能保留。

文档债务可以在 CI 中阻止每次合并，无需调用大模型或消耗令牌 — 请参阅 GitHub Actions 模板。

历史对比方法和带日期的结果已归档在 基准测试 中。

软件包

软件包	用途
@livewiki/cli	livewiki 命令
@livewiki/mcp	面向支持 stdio 的 MCP 客户端的 MCP 服务
@livewiki/core	库：索引器、锚点、台账、流水线

文档

• SPEC.md — 行为和格式契约
• VISION.md — 产品理念和非目标
• docs/ROADMAP.md — 已批准的待办事项和执行顺序

许可证

MIT — 请参阅 LICENSE。

---