官方中文正文为项目官方提供的中文文档（原文转载），本站未作翻译、未改动文字，仅剔除图片与无关章节。

基于 pi 的自维护、兼容 Obsidian 的知识库。 遵循 Andrej Karpathy 的 LLM Wiki 模式。

将原始来源（网址、PDF、Markdown、JSON、XML）转化为持久、互联、由 LLM 维护的 Wiki，并随时间不断积累。

原生 Open Knowledge Format (OKF) v0.2 支持

构建可随身携带的知识库——不再是另一个封闭的应用专属导出：

• 创建可移植的 OKF v0.2 文档，具有标准 frontmatter、标准 Markdown 链接和稳定的来源引用。
• 同时读取旧版和 OKF 页面，现有 vault 无需自动迁移或重写即可继续工作。
• 从权威页面生成确定性索引和日志，保持导航和元数据可重现。
• 从 Pi 或 MCP 使用相同的知识模型，支持 Claude Code、Cursor、Windsurf 和其他 MCP 客户端。
• 保持 Obsidian 兼容性，同时让知识准备好供支持 Open Knowledge Format 的工具使用。

从新的 OKF vault 开始，或将 pi-llm-wiki 指向现有 vault，按您的节奏采用该格式。查看 OKF Foundation 规范 了解实现细节。

---

演示

---

快速开始

pi (@mariozechner/pi-coding-agent)：

pi install npm:@zosmaai/pi-llm-wiki

oh-my-pi (omp):

omp install @zosmaai/pi-llm-wiki

两个主机加载相同的扩展、技能和 /wiki-* 命令——有关差异，请参见 双主机支持。

通过MCP的其他线束

Claude Code、Codex、Cursor、Windsurf、Zed、Cline 以及其他支持 MCP 的套件都使用打包的 stdio 服务器。从 Claude 市场开始：

/plugin marketplace add https://github.com/zosmaai/pi-llm-wiki
/plugin install llm-wiki@zosmaai
/reload-plugins

对于其他每个 MCP 客户端，安装该包并将 dist/mcp/index.js 注册为本地 stdio 服务器：

npm install --save-dev @zosmaai/pi-llm-wiki@latest

使用docs/harnesses.md 中的特定客户端 JSON/TOML 示例。它们涵盖了 Codex CLI、Cursor、Windsurf、Zed、Cline 以及通用的 MCP 配置。设置 WIKI_ROOT 来固定存储库；使用绝对服务器路径，因为 MCP 客户端不会展开 ~。

该扩展将在您首次使用时主动建议创建一个维基。或者：

/wiki-init "AI Engineering"
/wiki-ingest
/wiki-query What are the key patterns?

---

为什么选择这个包？

大多数基于文件的 LLM 工作流如同一键式 RAG：每次提问时模型都会搜索原始文档。综合结果转瞬即逝。

pi-llm-wiki 创建了一个中间层：

• 原始来源包 保留真实来源输入
• 来源页面 总结每个来源的内容
• 规范 wiki 页面 追踪 wiki 当前认定的内容
• 生成的元数据 保持所有内容可搜索和可导航

结果是：随着您捕获来源、提出问题并归档持久分析，wiki 会不断 积累。

---

特性

功能	描述
🏠 个人回退	始终开启的 ~/.llm-wiki/ vault——即使没有项目 wiki，知识也能跨项目积累
🔗 不可变的来源捕获	URL、本地文件（PDF/md/txt/html/XML/JSON）或粘贴文本 → 结构化来源包
🧠 自动化摄取	wiki_ingest 批量处理来源到概念、实体、综合和分析页面
🔍 全文搜索	生成的注册表，跨所有页面和来源的关键字查找
🩺 机械式 linting	孤儿页面、断链、重复别名、覆盖缺口、过时捕获
📊 仪表板	wiki_status——计数、来源状态、最近活动
🤖 自动更新监控	wiki_watch——打印按计划运行完整周期的 crontab 行
🧠 分层召回	同时搜索个人（~/.llm-wiki/）和项目（.llm-wiki/）vault——个人知识随您到处
📝 自动引导	当前目录不存在 wiki 时扩展建议创建
💾 轻量级捕获	wiki_retro——将原子洞察保存为单个 markdown 文件；通过 wiki_capture_source 也可用完整 4 层管道
🧭 代理工作记忆 （可选）	wiki_capture_trajectory 记录任务如何解决的（工具调用轨迹）→ 提炼为可重用的 skill/case 页面 → wiki_recall_skill 下次展示。默认关闭；用 /wiki-trajectories on 启用
🌐 OKF v0.2 原生	可移植 Open Knowledge Format 文档、双读旧版兼容、确定性投影
🌐 MCP 服务器	通过 stdio MCP 传输从 Claude Code、Cursor、Windsurf 使用相同的 OKF 感知 wiki
📝 Obsidian 友好	文件夹限定 wikilinks、稳定来源 ID 引用、兼容 vault
🛡️ 护栏	阻止直接编辑原始来源和生成的元数据
🔧 可配置的 PDF 提取	通过 WIKI_MARKITDOWN_TIMEOUT_MS 环境变量设置 MarkItDown 超时
🧪 质量检查	TypeScript、Vitest、Biome、Codecov、CodeQL

---

工具

工具	描述
wiki_bootstrap	用配置、模板、模式和元数据初始化新的 wiki vault
wiki_capture_source	将 URL、本地文件或粘贴文本捕获到不可变的来源包中
wiki_recall	搜索 wiki 中与任务相关的页面——搜索个人和项目 vault，去重
wiki_retro	将已完成任务的原子洞察保存到 wiki
wiki_ingest	处理未摄取的来源包到 wiki 页面（批量）
wiki_ensure_page	解析或安全创建实体/概念/综合/分析页面
wiki_search	搜索生成的 wiki 注册表
wiki_lint	确定性健康检查（孤儿、缺口、矛盾、自动修复）
wiki_status	显示计数、来源状态和最近活动
wiki_observe	记录当前会话的带时间戳、可搜索观察
wiki_rebuild_meta	强制完整元数据重建（注册表、反向链接、索引、日志）
wiki_reindex_embeddings	为新增或过期的页面刷新语义嵌入（未配置 embedding 提供方时为空操作）
wiki_log_event	将结构化事件追加到 wiki 活动日志
wiki_watch	打印自动 wiki 更新的 crontab 行（每日/每周/每小时）——不安装它
wiki_capture_trajectory （可选）	捕获已完成任务的工具调用轨迹（代理工作记忆）
wiki_distill_skills （可选）	批量未提炼的轨迹以合成为可重用的技能页面
wiki_recall_skill （可选）	召回提炼的技能+类似过去案例——"我以前做过这个吗？"

三个代理轨迹工具 默认关闭（issue #80）。用 /wiki-trajectories on 启用（设置 llm-wiki.trajectories）；关闭时完全不注册。

斜杠命令

命令	描述
/wiki-init <topic>	初始化新的 LLM Wiki vault
/wiki-ingest [path]	处理新来源文件并更新 wiki
/wiki-query <question>	带引用向 wiki 提问
/wiki-discover [--topic <topic>]	从网络自动发现新来源
/wiki-run [--schedule daily\|weekly]	完整周期：发现 → 摄取 → lint
/wiki-lint [--fix]	健康检查（孤儿、矛盾、缺口）
/wiki-status	显示简洁的操作摘要
/wiki-digest [--period daily\|weekly]	生成最近活动的摘要
/wiki-retro	保存已完成任务的原子洞察
/wiki-model [provider/id | session]	设置后台任务模型（无参数时为交互式选择器）
/wiki-req <concept>	将概念分解为原子、可追踪的需求页面
/wiki-trajectories <on\|off>	启用/禁用代理工作记忆（可选，默认关闭）
/wiki-record <title>	捕获已完成任务的轨迹（需要启用轨迹）
/wiki-skills [query]	搜索提炼的技能+过去案例（需要启用轨迹）
/wiki-settings	交互式设置屏幕 — 在 project/global 作用域下查看/修改全部 llm-wiki 设置
/wiki-dashboard	只读知识库仪表盘 — 页面数量/类型、新鲜度、7 日活动、入库队列、零反链页面、embedding 覆盖率

---

分层存储架构

知识无处不在。pi-llm-wiki 使用分层存储系统：

层	位置	目的
🏠 个人	~/.llm-wiki/	始终激活。零设置。无论你在哪个项目中，知识都会在所有会话中累积。
📁 项目	{project}/.llm-wiki/	明确选择加入。每个项目的专用维基，在相关情况下共享个人知识。
🏢 公司（未来）	git跟踪	团队共享的维基。wiki_publish 可以将个人/项目页面推广到公司维基。

它是如何运作的：

1. resolveVaultRoot() 检查：当前工作目录 → 向上查找 .llm-wiki/ → ~/.llm-wiki/
2. wiki_recall（分层）搜索个人和项目保险库，并将结果与保险库标签合并
3. 个人结果首先显示在回忆输出中，标记为“📓 个人”
4. wiki_retro 写入当前活动的任何金库（项目优先）
5. 设置 WIKI_HOME 环境变量以覆盖个人维基位置

这意味着：你可以拥有一个用于团队文档的项目维基 以及 一个用于个人笔记的个人维基，并且可以同时搜索两者。

---

快速开始（详细）

1）创建一个新的维基

mkdir my-wiki
cd my-wiki
pi

问 π：

Initialize an llm wiki here for AI research.

这会调用 wiki_bootstrap 并创建：

.llm-wiki/
├── config.json
├── templates/
├── raw/
├── wiki/
├── meta/
└── WIKI_SCHEMA.md

2) 捕获一个来源

Capture this article into the wiki: https://example.com/some-article

Capture this PDF into the wiki: ./papers/context-windows.pdf

Capture these notes into the wiki: ...pasted text...

3）整合来源

1. 捕获源
2. 阅读 .llm-wiki/wiki/sources/SRC-*.md
3. 更新该来源页面
4. 使用 wiki_search 搜索受影响的规范页面
5. 使用 wiki_ensure_page 创建缺失的页面
6. 使用引用更新概念/实体/综合页面
7. 使用 wiki_log_event kind=integrate 标记集成

4) 查询维基

Based on the wiki, what are the main tradeoffs between long-context models and RAG?

默认情况下，查询模式是只读。要提交持久答案：

Answer the question and file the result as an analysis page.

---

金库布局

my-wiki/
└─ .llm-wiki/
   ├─ config.json               # Vault config
   ├─ templates/                 # Page templates
   ├─ raw/
   │  └─ sources/
   │     └─ SRC-2026-05-11-001/
   │        ├─ manifest.json
   │        ├─ original/           # Original artifact
   │        ├─ extracted.md        # Normalized text
   │        └─ attachments/
   ├─ wiki/
   │  ├─ sources/                  # Source pages (what each source says)
   │  ├─ concepts/                 # Concepts and recurring ideas
   │  ├─ entities/                 # People, orgs, products, papers, systems
   │  ├─ syntheses/                # Cross-source theses and tensions
   │  └─ analyses/                 # Durable filed answers from queries
   ├─ meta/
   │  ├─ registry.json             # Auto-generated search index
   │  ├─ backlinks.json
   │  ├─ index.md
   │  ├─ events.jsonl              # Append-only event log
   │  ├─ log.md
   │  └─ lint-report.md
   └─ WIKI_SCHEMA.md               # Operating manual

所有权模型

路径	所有者	规则
路径	所有者	规则
------	-------	------
.llm-wiki/raw/**	扩展工具	捕获后不可变
.llm-wiki/wiki/**	模型 用户	可编辑的知识页面
.llm-wiki/meta/registry.json	扩展	已生成
.llm-wiki/meta/backlinks.json	扩展名	已生成
.llm-wiki/meta/index.md	扩展	生成
.llm-wiki/meta/events.jsonl	扩展 / 工具	权威的追加式状态；用于活动连续性的备份
.llm-wiki/meta/log.md	扩展	从事件生成
.llm-wiki/meta/lint-report.md	扩展名	已生成
.llm-wiki/WIKI_SCHEMA.md	人类明确请求	操作手册

活动历史、备份和可移植性

meta/events.jsonl 是已记录扩展活动的权威来源。与注册表、反向链接、索引、日志和嵌入不同，它不能从 wiki 页面或原始数据包重建。在备份或 Git 同步完整的 pi-llm-wiki 存储库时，请保留它。

meta/log.md 和 OKF 模式的 wiki/log.md 是生成的视图。wiki/log.md 可以随 OKF 包一起作为可读快照传播，但它无法重建或恢复原始的 JSONL 流。手动页面编辑故意缺失，因此这是选择的扩展活动，而不是完整的修订审计。

文件捕获事件会从公共日志投影中省略机器本地路径。wiki_log_event 的调用者仍然可以控制任意详细字段，但不得记录机密或私人主机路径。

---

链接与引用格式

内部导航

[[concepts/retrieval-augmented-generation]]
[[entities/openai|OpenAI]]
[[syntheses/long-context-vs-rag]]

事实引用

[[sources/SRC-2026-04-04-001|SRC-2026-04-04-001]]

稳定的源页面 ID 即使标题发生变化，也能保持来源稳定。

---

护栏

该扩展阻止对以下内容的直接工具调用编辑：

• .llm-wiki/raw/** — 不可变的源文档
• .llm-wiki/meta/registry.json
• .llm-wiki/meta/backlinks.json
• .llm-wiki/meta/events.jsonl
• .llm-wiki/meta/index.md
• .llm-wiki/meta/log.md
• .llm-wiki/meta/lint-report.md

如果模型直接使用 Pi 内置的 write 或 edit 工具编辑 .llm-wiki/wiki/**，扩展会在代理回合结束时 自动重建 生成的元数据。

---

源数据包格式

每个捕获的来源都被存储为一个结构化的数据包：

.llm-wiki/raw/sources/SRC-YYYY-MM-DD-NNN/
├─ manifest.json     # Capture metadata (title, URL, format, timestamp)
├─ original/         # Original artifact (preserved as-is)
├─ extracted.md      # Normalized text (PDF→md, XML→md, JSON→md, etc.)
└─ attachments/      # Future attachment downloads

这既保留了原始文档，也保留了标准化提取视图以供阅读。

---

MCP 服务器

使用来自任何兼容 MCP 的工具的维基——Claude Code、Cursor、Windsurf 等。

该软件包提供一个独立的 MCP 服务器，通过 stdio 暴露 15 个维基工具：

工具	描述
wiki_bootstrap	初始化一个保险库
wiki_recall	搜索相关维基页面
wiki_search	搜索注册表
wiki_status	显示维基健康状况和数量
wiki_retro	保存一次原子级洞察
wiki_capture_source	捕获源数据包
wiki_ingest	在配置的任务模型上同步地综合捕获的来源
wiki_reindex	重建/修复 QMD 索引
wiki_ensure_page	安全地创建规范页面
wiki_lint	运行确定性健康检查
wiki_log_event	添加一个活动事件
wiki_observe	保存带时间戳的观察
wiki_rebuild_meta	重建元数据投影
wiki_reindex_embeddings	刷新语义嵌入
wiki_watch	打印更新 cron 行

使用

# Auto-discovered by pi:
pi install npm:@zosmaai/pi-llm-wiki

# Standalone with any MCP client:
WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js

将 WIKI_ROOT 设置为你的 Wiki 库目录。如果未设置，服务器将从当前工作目录自动检测。

Claude 市场安装

/plugin marketplace add https://github.com/zosmaai/pi-llm-wiki
/plugin install llm-wiki@zosmaai
/reload-plugins

客户端配置

与 .mcp.json（Claude Code）或 claude_desktop_config.json 中的条目相同的服务器：

{
  "mcpServers": {
    "llm-wiki": {
      "command": "node",
      "args": ["/absolute/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
      "env": { "WIKI_ROOT": "/absolute/path/to/my-wiki" }
    }
  }
}

MCP 客户端在 没有 shell 的情况下 启动命令，因此 ~ 永远不会被展开。args 或 env 中的 ~/my-wiki 会被按字面传递，服务器启动失败，客户端只会报告为通用连接错误 —— 在这里使用绝对路径。上面的 shell 代码片段是可以的：你的 shell 会在 node 看到它之前展开 ~。

---

双主机支持（pi oh-my-pi）

该软件包从单一代码库针对两个主机：

	pi (@mariozechner/pi-coding-agent)	oh-my-pi (omp)
扩展条目	package.json#pi.extensions	package.json#omp.extensions（回退到 #pi）
技能	skills/llm-wiki/SKILL.md 通过 pi.skills	相同文件，通过目录约定找到
斜杠命令	通过 pi.prompts 使用 prompts/*.md	commands/*.md（prompts/ 的生成镜像）
项目配置	<cwd>/.pi/settings.json	<cwd>/.omp/settings.json，然后 .omp/config.yml
用户配置	~/.pi/agent/settings.json	~/.omp/agent/settings.json，然后 config.yml
MCP 服务器	通过 pi.mcpservers 自动注册	手动注册（见下文）
没有项目维基的环境表面	在（个人保险库）上	关闭 — 见下文

导入不需要任何源代码更改：oh-my-pi 在加载旧版扩展时，会将 @mariozechner/pi-* 和裸 typebox 指定符重写到其自身捆绑的包中。

设置从两个布局中读取。 llm-wiki 配置从上述每个文件合并，host-native 目录最后。配置在 pi 下的保险库在 omp 接管同一存储库后继续工作，并且写入会落在已存在的配置目录中（因此只有 .pi 的存储库不会生成第二个设置文件）。写入始终为 JSON — 手动创建的 config.yml 会被读取，但从不被重写。

设置 LLM_WIKI_HOST=pi|omp 来覆盖主机检测；默认情况下，它是从解析的代理目录中获取的。

在 oh-my-pi 下，环境表面是受控的。 会话通知、定期观察/回顾提醒以及 before_agent_start 回调都会自动触发，而保险库解析会回退到个人保险库——所以一旦存在 ~/.llm-wiki/，它们会在每个目录中提示。在 pi 下，这是历史行为并得以保留；在 omp 下，插件只安装一次并会加载到每个项目中，因此从未运行过 /wiki-init 的仓库保持静默。可以通过 llm-wiki.ambientPersonalVault 覆盖任一默认设置。Wiki 工具和斜杠命令无论如何都会注册，所以 /wiki-init 总是可用——而拥有自己 .llm-wiki/ 的项目会恢复所有表面功能。

MCP 在 oh-my-pi 下。 pi.mcpservers 是一个仅适用于 pi 的清单键，服务器的保险库自动检测依赖于客户端的工作目录，所以不能用相对路径声明。请改为显式注册它：

// <cwd>/.omp/.mcp.json
{
  "mcpServers": {
    "llm-wiki": {
      "command": "node",
      "args": ["/abs/path/to/node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js"],
      "env": { "WIKI_ROOT": "/abs/path/to/your/wiki" }
    }
  }
}

你很少需要它：在任一主机下，该扩展已经注册了与本地工具相同的功能。

---

技能行为

捆绑的 llm-wiki 技能教模型如下内容：

• ❌ 永远不要直接编辑原始来源
• ❌ 永远不要编辑生成的元数据文件
• ✅ 先捕获，再整合
• ✅ 在创建新的规范页面之前进行搜索
• ✅ 使用来源页ID引用事实
• ✅ 默认保持查询模式为只读
• ✅ 当证据混合时使用“紧张/警告”和“开放性问题”

---

建筑学

金库层

请参见上文的分层保险库架构部分，以了解个人/项目/公司分层。

四层页面模型

每个维基库都有四层明确的所有权：

.llm-wiki/raw/sources/SRC-*/     # Immutable source packets (extension-owned)
.llm-wiki/wiki/                   # Editable knowledge pages (you + LLM)
.llm-wiki/meta/                   # Durable event source + generated internal projections
.llm-wiki/                        # Config and templates

阅读 docs/architecture.md 获取完整的设计文档。

---

文档

文件	它涵盖的内容
架构	四层的工作原理，所有权模型
命令	所有斜杠命令和工具参考
Obsidian 集成	保险库设置和推荐插件
配置	Wiki 模式、主题、环境变量
API	扩展工具参数参考

---

贡献

有关开发设置、测试模式和 PR 工作流程，请参见 CONTRIBUTING.md。

---

许可证

麻省理工学院

安全带支撑

可以在 Pi 上本地运行，也可以作为 MCP 服务器在 Claude Code（插件）、Codex、Cursor、Windsurf、Zed 和 opencode 中运行。请参阅 docs/harnesses.md。