@zosmaai/pi-llm-wiki

v0.11.4

Published

10 days ago

Self-maintaining LLM Wiki for Pi — Karpathy-pattern knowledge base with immutable source capture, automated ingestion, search, linting, and Obsidian-compatible vault. auto-updating personal & company wiki.

Downloads

10,478

@zosmaai/pi-llm-wiki

基于 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 install npm:@zosmaai/pi-llm-wiki

扩展将在首次会话时主动建议创建 wiki。或者：

/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 超时 | | 🧪 562 测试、85.09% 覆盖率 | 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_rebuild_meta | 强制完整元数据重建（注册表、反向链接、索引、日志） | | 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-req <concept> | 将概念分解为原子、可追踪的需求页面 | | /wiki-trajectories <on\|off> | 启用/禁用代理工作记忆（可选，默认关闭） | | /wiki-record <title> | 捕获已完成任务的轨迹（需要启用轨迹） | | /wiki-skills [query] | 搜索提炼的技能+过去案例（需要启用轨迹） |

分层 Vault 架构

知识随您到处。pi-llm-wiki 使用分层 vault 系统：

| 层 | 位置 | 用途 | |----|------|------| | 🏠 个人 | ~/.llm-wiki/ | 始终激活。零设置。知识跨所有会话积累——无论您在哪个项目中。 | | 📁 项目 | {project}/.llm-wiki/ | 明确选择加入。每个项目专用 wiki，相关时共享个人知识。 | | 🏢 公司（未来） | git 跟踪 | 团队共享 wiki。wiki_publish 将个人/项目页面提升到公司 wiki。 |

工作原理：

resolveVaultRoot() 检查：cwd → 向上查找 .llm-wiki/ → ~/.llm-wiki/
wiki_recall（分层）搜索两个个人和项目 vault，合并结果带 vault 标签
个人结果在召回输出中首先显示，标记为 "📓 personal"
wiki_retro 写入当前激活的 vault（项目优先）
设置 WIKI_HOME 环境变量覆盖个人 wiki 位置

这意味着：您可以有用于团队文档的项目 wiki 和用于个人笔记的个人 wiki，recall 同时搜索两者。

快速开始（详细）

1) 创建新的 wiki

mkdir my-wiki
cd my-wiki
pi

询问 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) 集成来源

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

4) 查询 wiki

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.

Vault 布局

my-wiki/
└─ .llm-wiki/
   ├─ config.json               # Vault 配置
   ├─ templates/                 # 页面模板
   ├─ raw/
   │  └─ sources/
   │     └─ SRC-2026-05-11-001/
   │        ├─ manifest.json
   │        ├─ original/           # 原始工件
   │        ├─ extracted.md        # 规范化文本
   │        └─ attachments/
   ├─ wiki/
   │  ├─ sources/                  # 来源页面（每个来源说什么）
   │  ├─ concepts/                 # 概念和重复出现的想法
   │  ├─ entities/                 # 人物、组织、产品、论文、系统
   │  ├─ syntheses/                # 跨来源论点和张力
   │  └─ analyses/                 # 来自查询的持久归档答案
   ├─ meta/
   │  ├─ registry.json             # 自动生成搜索索引
   │  ├─ backlinks.json
   │  ├─ index.md
   │  ├─ events.jsonl              # 仅追加事件日志
   │  ├─ log.md
   │  └─ lint-report.md
   └─ WIKI_SCHEMA.md               # 操作手册

所有权模型

| 路径 | 所有者 | 规则 | |------|--------|------| | .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 | 人工 + 明确请求 | 操作手册 |

链接和引用风格

内部导航

[[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     # 捕获元数据（标题、URL、格式、时间戳）
├─ original/         # 原始工件（原样保留）
├─ extracted.md      # 规范化文本（PDF→md、XML→md、JSON→md 等）
└─ attachments/      # 未来附件下载

这同时保留 原始工件 和 规范化提取视图 供阅读。

MCP 服务器

从 任何 MCP 兼容工具 使用 wiki——Claude Code、Cursor、Windsurf 等。

包附带独立 MCP 服务器，通过 stdio 暴露 6 个 wiki 工具：

| 工具 | 描述 | |------|------| | wiki_bootstrap | 用配置、模板、模式和元数据初始化新的 wiki vault | | wiki_recall | 搜索 wiki 中与任务相关的页面 | | wiki_search | 完整注册表搜索 | | wiki_status | Wiki 统计（页面计数、类型分解） | | wiki_retro | 保存原子洞察 | | wiki_capture_source | 捕获文本为来源包 |

用法

# pi 自动发现：
pi install npm:@zosmaai/pi-llm-wiki

# 独立使用任何 MCP 客户端：
WIKI_ROOT=~/my-wiki node node_modules/@zosmaai/pi-llm-wiki/dist/mcp/index.js

设置 WIKI_ROOT 为您的 wiki vault 目录。如果未设置，服务器从当前工作目录自动检测。

客户端配置

在 .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 收到之前展开。

技能行为

捆绑的 llm-wiki 技能教导模型：

❌ 从不直接编辑原始来源
❌ 从不编辑生成的元数据文件
✅ 先捕获，后集成
✅ 创建新规范页面前先搜索
✅ 使用来源页面 ID 引用事实
✅ 默认保持查询模式只读
✅ 证据混合时使用 "张力/注意事项" 和 "开放问题"

架构

Vault 层

参见上方分层 Vault 架构部分了解个人/项目/公司分层。

四层页面模型

每个 wiki vault 有四个层，所有权清晰：

.llm-wiki/raw/sources/SRC-*/     # 不可变来源包（扩展所有）
.llm-wiki/wiki/                   # 可编辑知识页面（您 + LLM）
.llm-wiki/meta/                   # 自动生成注册表、反向链接、索引、日志
.llm-wiki/                        # 配置和模板

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

文档

| 文档 | 涵盖内容 | |------|----------| | 架构 | 四层如何工作、所有权模型 | | 命令 | 所有斜杠命令和工具参考 | | Obsidian 集成 | Vault 设置和推荐插件 | | 配置 | Wiki 模式、主题、环境变量 | | API | 扩展工具参数参考 |

贡献

查看 CONTRIBUTING.md 了解开发设置、测试模式和 PR 工作流。

贡献者

感谢所有贡献者！此列表由 .github/workflows/contributors.yml 自动生成——查看 #60 了解原因。

Full history: contributors graph.

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@zosmaai/pi-llm-wiki

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

演示

快速开始

为什么选择这个包？

特性

工具

斜杠命令

分层 Vault 架构

快速开始（详细）

1) 创建新的 wiki

2) 捕获来源

3) 集成来源

4) 查询 wiki

Vault 布局

所有权模型

链接和引用风格

内部导航

事实引用

护栏

来源包格式

MCP 服务器

用法

客户端配置

技能行为

架构

Vault 层

四层页面模型

文档

贡献

贡献者

License