LLM-Wiki-Pi

把 Pi 深度定制成擅长搭建与维护 Karpathy LLM Wiki 的 agent。

Karpathy 的 LLM Wiki 主张让 LLM 增量地把 raw/ 里的原始资料编译成结构化、互链的 markdown wiki， 而不是每次提问都重新检索、重新推导——知识因而随每次摄入而复利。 他的比喻是——Obsidian 是 IDE，LLM 是程序员，wiki 是代码库。

本包就是把这个比喻落成工程：给"程序员"配上趁手的工具。

---

里面有什么

组成	内容
扩展	extensions/llm-wiki.ts —— 6 个确定性工具 + raw/ 写保护守卫
技能	skills/ —— wiki-init / wiki-ingest / wiki-query / wiki-lint 四套工作流
命令	prompts/ —— /wiki-init、/wiki-ingest、/wiki-query、/wiki-lint 快捷入口
模板	templates/wiki-AGENTS.md —— 新 wiki 的规约文件模板
示例	example-wiki/ —— 可重复运行的验证夹具

六个确定性工具

机械检查交给代码，比每次让模型通读全库更可靠，也更省 token：

工具	作用
wiki_init	建立骨架（raw/、wiki/、AGENTS.md、CLAUDE.md、index.md、log.md）。幂等，不覆盖已有文件，不建 stub 页
wiki_lint	体检：frontmatter 合规、幽灵链接、孤儿页、index.md 不一致、log.md 格式违规
wiki_index	汇总页面生成 index.md（check 只报告差异，write 落盘）。保留已有行的手写描述，只增删不重写
wiki_backlinks	给定页面，列出所有引用它的页面
wiki_stats	页面数、类型分布、链接数、孤儿数
wiki_selfcheck	自检探针：报告工具参数实际形状、当前目录是否被识别为 wiki 根、注册期有无错误。装好后或升级 Pi 后跑一次，可快速定位「工具没反应」

raw/ 写保护

Karpathy 的规约要求 raw/ 不可变（LLM 只读）。本包把这条从提示词约定升级为代码强制： 扩展通过 tool_call 钩子拦截对 raw/ 的写操作。

诚实标注：这是强护栏，不是沙箱。write / edit 能精确判定路径并拦截； 但 bash 能做任何事（>、rm、mv、sed -i、tee……），无法可靠解析， 只能按"命令串中出现 raw 路径 + 写操作特征"做启发式拦截。 守卫也只对本 wiki 的 raw/ 生效——会先向上确认目录里存在 wiki/index.md，避免误伤其它项目里同名的 raw/ 目录。

---

安装

从 npm 安装（推荐）

pi install npm:llm-wiki-pi

不写版本号时跟随 latest，pi update --extensions 可以把它升到新版：

pi install npm:llm-wiki-pi@0.1.0   # 锁定版本（此后更新时会被跳过）

从 GitHub 安装（tag 锁定）

如果不想依赖 npm，可以直接从仓库装：

pi install git:github.com/helix-byte/llm-wiki-pi@v0.1.0

@v0.1.0 是 Git tag，属于锁定版本：Pi 把它克隆到 ~/.pi/agent/git/github.com/helix-byte/llm-wiki-pi， pi update --extensions 不会把它挪到更新的 tag，行为可预期。

想换到新版本，用 pi install 指定新 tag 即可（会同步更新配置里的 ref）：

pi install git:github.com/helix-byte/llm-wiki-pi@v0.2.0

装到某个 wiki 项目里（可随仓库共享给团队）

加 -l 会写进项目级配置 .pi/settings.json 而不是全局配置：

cd my-wiki
pi install -l npm:llm-wiki-pi

把 .pi/settings.json 提交进仓库后，团队成员的项目被 Pi 信任时会自动安装缺失的包，无需各自手动执行。

临时试用（不写进任何配置）

pi -e npm:llm-wiki-pi

从本地路径安装（开发本包时）

pi install "C:\Users\Skyline\Local Doc\Projects\LLM-Wiki-Pi"

本地路径不复制、只挂载，所以改完源码在 Pi 里 /reload 即生效。

---

移除

pi remove npm:llm-wiki-pi

或本地路径（与之对应）：

pi remove "C:\Users\Skyline\Local Doc\Projects\LLM-Wiki-Pi"

查看与升级

pi list                  # 列出已安装的包
pi update --extensions   # 更新包，并校准锁定的 git ref

两种源的更新行为不同：npm 源不带版本号时会跟随 latest 升级；git tag 源属于锁定版本，不会被自动挪到更新的 tag。

安装后先跑一次 wiki_selfcheck：它会报告工具参数的实际形状、当前目录是否被识别为 wiki 根， 以及注册期是否有错误。遇到「工具没反应」时，这是最快的定位手段。

---

使用

1. 建一个新的 wiki

mkdir my-wiki && cd my-wiki

在 Pi 里：

/wiki-init

它会生成 raw/、wiki/、AGENTS.md、wiki/index.md、wiki/log.md—— 不会预先创建空白 stub 页（本项目的约定；见下方「哪些是原文、哪些是我们定的」）。

2. 摄入一份资料

把文章/论文放进 raw/，然后：

/wiki-ingest raw/某篇文章.md

流程是：读源 → 写 source-summary 页 → 更新 index.md → 更新相关的 entity/concept 页（一个源常常牵动 10–15 页）→ 追加 log.md。

3. 提问

/wiki-query 增量编译和 RAG 的本质区别是什么？

先读 index.md 定位相关页，再带引用作答。有价值的回答会被回写成新页面，于是探索本身也在复利。

4. 体检

/wiki-lint

查出矛盾、被新源取代的过期声明、无入链的孤儿页、被提及却缺页的概念、缺失的交叉引用。

---

双端兼容

同一套 wiki 在 Pi 和 Claude Code 下都能维护：

• AGENTS.md 是单一事实源（Pi 原生读取）
• 同目录的 CLAUDE.md 只有一行 @AGENTS.md（Claude Code 的导入语法，已验证确实加载； 而"见 AGENTS.md"这类文字重定向不生效）
• Windows 上导入优于 symlink（symlink 需管理员权限）

规约只写一份，两端行为一致。

能力层（skills / 斜杠命令）的差别：Pi 侧由本 package 全局提供，装一次到处可用； Claude Code 读的是 .claude/skills/，需要在 wiki 项目里复制一份（wiki_init 不代建这个目录）：

mkdir .claude 2>nul && xcopy /E /I /Y "C:\Users\Skyline\Local Doc\Projects\LLM-Wiki-Pi\skills" ".claude\skills"

注意：Claude Code 的项目级 hooks/设置需要你信任该目录后才生效，且 hooks 在会话启动时快照—— 改完要重启 Claude Code。

---

哪些是 Karpathy 原文，哪些是我们定的

这点必须说清楚：Karpathy 的 gist 自称 "idea file"，刻意保持抽象—— 它明确说目录结构、schema、页面格式应由你与 LLM 按具体领域共同决定。 所以社区里每个实现都在自己拍板这些细节。本包的选择如下：

来自原文（较硬的约束）

约定	说明
三层结构	raw/ 不可变 · wiki/ 归 LLM · schema 文件与 LLM 共同演进
index.md	内容目录，每页一行带一句话摘要；每次查询先读它
log.md	仅追加；条目以 ## [ 开头——原文给的 grep "^## \[" log.md | tail -5 技巧依赖这个前缀
三个操作	ingest / query / lint
数字约定	一份源可能触及 10–15 页；好答案回写成新页面
lint 的 6 类检查	矛盾、过期声明、孤儿页、被提及却缺页的概念、缺失的交叉引用、数据缺口

本项目自定（你可以自由改）

• 五种 type 枚举：entity / concept / source-summary / comparison / synthesis
• frontmatter 字段：title / type / summary / sources / created / updated
• 把 updated 与 sources 定为必填——不这样定，"过期声明"检查就无从谈起
• "不创建 stub 页"
• log 的 operation 限定为 init / ingest / query / lint / update（原文只给了示例格式）

为什么 title ↔ wikilink 契约必须显式钉死：社区里有实现因为"生成端写 [[标题]]、 解析端按 slug 建索引且不切分 | 别名"，导致解析出的边为零、所有页面被判为孤岛。 这是被实证过的系统性故障，所以本项目把契约写死：

wikilink 的目标就是页面 frontmatter 里的 title 原文；title 全库唯一， wiki_lint 会检查重复与不一致。

---

目录结构

LLM-Wiki-Pi/
├── package.json            # Pi 包清单（pi 字段声明各资源路径）
├── README.md
├── extensions/
│   └── llm-wiki.ts         # 确定性工具 + raw/ 守卫
├── skills/
│   ├── wiki-init/SKILL.md
│   ├── wiki-ingest/SKILL.md
│   ├── wiki-query/SKILL.md
│   └── wiki-lint/SKILL.md
├── prompts/
│   ├── wiki-init.md
│   ├── wiki-ingest.md
│   ├── wiki-query.md
│   └── wiki-lint.md
├── templates/
│   └── wiki-AGENTS.md      # 新 wiki 的规约模板
├── example-wiki/           # 演示用 wiki（干净的初始状态）
└── fixtures/
    └── lint-cases/         # 故意做坏的 wiki，用于验证 wiki_lint 的检出能力

---

说明

• 扩展用 TypeScript 编写，靠 Pi 内置的 jiti 直接加载，无需编译。
• 零依赖：工具参数用内联 JSON Schema，不加载 Pi 运行时的 typebox。 这样既避免了"运行时包半兼容导致整个扩展加载失败"，行为也完全可预测。
• 若扩展 API 在你的 Pi 版本上有出入，见 extensions/llm-wiki.ts 顶部的兼容说明。
• 装好后怎么确认它真的生效：照 VERIFY.md 走一遍， 每项都给了操作与预期，第 5 项（raw/ 拦截）是核心验收点。