Karpathy LLM Wiki

本地优先的 LLM Wiki CLI——把原始资料「编译」成结构化的个人知识库。
Local-first LLM Wiki CLI — compile raw sources into a structured personal knowledge base.

English →

这是什么 / What is this

基于 Andrej Karpathy 的 LLM Wiki 范式，让 LLM 把知识「编译」成持久的 Wiki，而非每次临时检索（RAG）。

核心模型

raw/    原始资料，你放进去，可写
wiki/   编译后的知识，LLM 维护，你阅读
git     状态机，每次操作可追溯

快速开始 / Quick Start

一行命令安装（推荐）

npm install -g cask-wiki

装完直接使用：

cask init ./my-wiki
cask ingest
cask query "RAG"

从源码安装

git clone https://github.com/LosFurina/cask-wiki.git
cd cask-wiki
npm install
npm run build
npm link

放一篇原始资料

echo "# RAG 笔记" > my-wiki/raw/general/articles/rag.md

摄入

cd my-wiki cask ingest

搜索

cask query RAG

诊断

cask doctor

---

## 功能 / Features

| 命令 | 说明 |
|------|------|
| `init` | 初始化 vault：目录结构 + AGENT 规则文件 + 管理页面 |
| `ingest` | 摄入 raw 文件 → Agent 写 wiki 页面 → lint → commit |
| `lint` | 检查 vault 完整性（schema/来源/引用），输出 Markdown 报告 |
| `query` | 本地搜索引擎，TF-IDF 打分，支持中英文混合搜索 |
| `publish` | 导出 public wiki 页面到 Astro 站点 |
| `doctor` | 诊断 vault 环境（git/config/agent/索引） |

### 核心特性

- **中英文搜索引擎** — 倒排索引 + TF-IDF，中文 unigram+bigram，零外部依赖
- **多域支持** — `--domains "tech:技术,work:工作"`，按域隔离知识
- **Agent 集成** — 支持 pi、Claude Code、Codex 等任意 Agent 执行 ingest
- **自动审计** — 每次 ingest 记录 prompt/stdout/stderr 到 `.cask/runs/`
- **Git 驱动** — 自动 commit，每次操作可回滚

---

## 日常工作流 / Daily Workflow

1. 收集 → 把文章放到 raw//articles/
2. 摄入 → cask ingest → Agent 自动写 wiki 页面
3. 阅读 → 在 vault 下跑 pi，直接问问题
4. 搜索 → cask query <关键词>
5. 体检 → cask doctor + cask lint
6. 发布 → cask publish

---

## 命令参考 / Command Reference

| 命令 | 常见用法 |
|------|---------|
| `init` | `cask init ./vault` / `--domains "tech:技术,work:工作"` |
| `ingest` | `cask ingest` / `cask ingest raw/ai/articles/foo.md` |
| `lint` | `cask lint` / `--full` / `--json` |
| `query` | `cask query "RAG"` / `cask query "tmux vs nohup" --answer` |
| `publish` | `cask publish` / `--out ../site/src/content` / `--dry-run` |
| `doctor` | `cask doctor` / `--json` |

详细说明 → [docs/reference/commands.md](docs/reference/commands.md)

---

## 目录结构 / Vault Layout

my-wiki/ ├── raw/ ← 原始资料（你放，LLM 只读） │ └── general/ │ ├── articles/ │ ├── papers/ │ └── assets/ ├── wiki/ ← 知识层（LLM 维护，你阅读） │ ├── general/ │ │ ├── sources/ ← 来源摘要页 │ │ ├── concepts/ ← 概念定义页 │ │ ├── entities/ ← 实体/人物/工具页 │ │ ├── comparisons/ ← 对比分析页（查询反哺） │ │ └── maps/ ← 主题导航页（查询反哺） │ ├── index.md ← 总索引 │ ├── log.md ← 操作日志 │ ├── hot.md ← 会话热缓存 │ └── maps/dashboard.md ← Dataview 仪表盘 ├── AGENT.md ← LLM 主规则 ├── AGENT-schema.md ← 页面格式规范 ├── AGENT-workflows.md ← 工作流（ingest/query/lint） ├── AGENT-writing.md ← 写作规范 + 标签体系 ├── templates/ │ └── web-clipper.md ← Obsidian Web Clipper 模板 └── .cask/ ├── config.json ← CLI 配置 ├── search-index.json ← 搜索引擎缓存 └── runs/ ← ingest 审计日志

---

## 配置 / Configuration

编辑 `.cask/config.json`：

```json
{
  "vault": ".",
  "domain": "general",
  "domains": [{ "id": "general", "name": "通用", "description": "通用知识库" }],
  "agent": { "command": "pi -p" },
  "publish": { "out": "../site/src/content" }
}

详细说明 → docs/reference/configuration.md

Agent 集成 / Agent Integration

cask ingest 支持通过 stdin 传递 prompt 给外部 Agent：

| Agent | 配置值 | 说明 | |-------|--------|------| | pi | "pi -p" | 本机，无需额外配置 | | Claude Code | "claude" | 内置 shorthand | | Codex | "codex" | 内置 shorthand（sandbox 模式） | | 自定义 | "my-agent --flag" | 走 shell 模式 |

详细说明 → docs/guide/agent-config.md

开发 / Development

npm test          # 运行全部测试（124+ tests）
npm run build     # TypeScript 编译
npm run typecheck # 类型检查

架构说明 → docs/development/architecture.md 搜索引擎设计 → docs/development/search-engine.md

致谢 / Credits

• Andrej Karpathy — LLM Wiki 范式提出者
• cask-init — 参考实现
• Superpowers — 驱动本项目的技能系统

License

MIT