Scholar LLM Wiki

文献进，知识出。 面向科研与文献整理的知识库工具包：AI agent 把论文、书籍、课件、网页长文编译成结构化、高度互链的 Obsidian 知识库。

Sources in, knowledge out. A knowledge base toolkit for research and literature review. AI agents compile papers, books, course notes and articles into a structured, densely interlinked Obsidian wiki — not a one-off summary, but a persistent artifact that compounds with every source you add. Built on Andrej Karpathy's llm-wiki.md pattern, plus a controlled tag vocabulary, concept hierarchy with generated Canvas maps, an arXiv→LaTeX formula pipeline, and audits that speak through exit codes. Zero hardcoding. Docs are in Chinese.

📖 新手请直接看 用户手册 docs/MANUAL.md —— 从「这东西是干什么的」讲到「出问题怎么修」。

🧠 方法论出处：本工具包的基础方法论来自 Andrej Karpathy 的 llm-wiki.md—— 「让 LLM 增量维护一个持久 wiki」这个想法是他的；本仓库做的是把它工程化、脚本化、做成可安装的工具。详见下文。

它不是「笔记模板」，而是一套可执行的知识库契约：

• AGENTS.md —— 给 AI 的架构规范：目录权限边界、页面分类、命名规则、双链、tag 受控词表、概念分层、Canvas 同步；
• 三个技能（ingest / query / lint）—— 把「摄入资料 → 生成页面 → 维护索引 → 健康巡检」固化成流水线；
• 一沓脚本 —— 路径自省、骨架初始化、tag 审计、概念地图生成、PDF 公式提取、环境自检；
• 一份配置 —— 所有目录名、领域、词表都在 JSON 里，仓库内零硬编码、零绝对路径。

它面向什么：科研与文献整理

这不是通用笔记应用——没有待办、日记、看板、周计划。它是文献进、知识出的编译器， 按「一位研究者在几个月里持续读论文」这个场景设计的。具体对应关系：

为什么专门标注这一点：Karpathy 的原始 pattern 是通用知识管理（也能用来记健康、 读小说、做竞品分析）。本仓库把它实例化成了科研文献整理这一个具体形状—— 论文讲解模板、公式流水线、概念分层、受控词表，都是为这个场景加的。 如果你要做的是别的领域，这套代码照样能用，但可能要换掉论文模板和那套 tag 词表 （见 docs/CUSTOMIZE.md）。

运行环境（装之前先看这一段）

最佳体验 = Obsidian + DSH（DeepSeek Harness）。 这两者不是可选项，而是这套工具「能跑」和「好用」的分界线：

一句话：DSH 负责「怎么干」，Obsidian 负责「看得见」。

想换个 harness（Claude Code / Cursor 等）？脚本层完全可移植，只需把 .dsh/skills/ 搬到该 harness 的技能目录、把 AGENTS.md 复制成它认识的指令文件。技能正文引用了 DSH 的工具名 （skill / grep / glob / read / read_image）与 office-docx 技能，换宿主时需要 相应替换——这一步是机械劳动，但必须做，否则技能会「找工具失败」而退化成凭记忆回答。

🚀 一句话安装

把下面这一整句发给你的 DSH，它会自己完成全部安装：

请安装 Scholar LLM Wiki：把 https://github.com/lkhfrgc/scholar-llm-wiki 克隆到临时目录（没有 git 就下载 zip 解压），将仓库里的 .dsh/、AGENTS.md、templates/ 复制到当前工作区（.dsh/ 按目录合并，任何已存在的同名文件都不要覆盖，冲突项另存为 <原文件名>.kit-new），然后依次运行 python .dsh/scripts/setup_wiki.py 与 python .dsh/scripts/selfcheck.py，把体检报告原样贴给我，并提醒我把待摄入资料放进 raw/research/；全程不要修改 raw/ 下的任何文件。

git clone https://github.com/lkhfrgc/scholar-llm-wiki /tmp/scholar-llm-wiki
cp -r /tmp/scholar-llm-wiki/.dsh /tmp/scholar-llm-wiki/AGENTS.md /tmp/scholar-llm-wiki/templates .   # 合并式复制
python .dsh/scripts/setup_wiki.py
python .dsh/scripts/selfcheck.py

git clone https://github.com/lkhfrgc/scholar-llm-wiki $env:TEMP\scholar-llm-wiki
Copy-Item $env:TEMP\scholar-llm-wiki\.dsh, $env:TEMP\scholar-llm-wiki\AGENTS.md, $env:TEMP\scholar-llm-wiki\templates . -Recurse
python .dsh/scripts/setup_wiki.py
python .dsh/scripts/selfcheck.py

装完以后你会得到：

你的知识库/
├── AGENTS.md          # AI 的架构规范（每次对话自动生效）
├── TAGS.md            # tag 受控词表（脚本生成，勿手改）
├── index.md           # 总目录
├── log.md             # 操作日志（append-only）
├── .dsh/
│   ├── wiki.config.json    # 唯一配置源
│   ├── tag-vocab.json      # 词表数据
│   ├── skills/{ingest,query,lint}/SKILL.md
│   └── scripts/*.py
├── raw/research/      # ← 把待摄入的资料丢这里
└── wiki/{papers,concepts,connections,questions,syntheses}/

30 秒上手

1. 把一篇论文 PDF（或 markdown、网页剪藏）丢进 raw/research/；
2. 对 agent 说 /ingest（或「把 raw/research 里的资料摄入知识库」）；
3. 摄入完成后到 Obsidian 里看：wiki/papers/ 有论文讲解页，wiki/concepts/ 有概念页，index.md 已更新，log.md 有记录，概念地图 .canvas 已重新生成；
4. 之后随时 /query 某个问题 检索，或 /lint 做一次全库体检。

三个技能

三个技能都建立在同一份 AGENTS.md 契约上，因此输出结构长期稳定。

工具链

python .dsh/scripts/wiki_env.py --paths        # 自省：工作区根 / 库根前缀 / 所有路径
python .dsh/scripts/setup_wiki.py              # 初始化骨架（幂等，绝不覆盖已有内容）
python .dsh/scripts/setup_wiki.py --venv       # 顺带建 venv 装 PyMuPDF
python .dsh/scripts/selfcheck.py               # 体检：环境 / 依赖 / 骨架 / 子脚本

python .dsh/scripts/tag_vocab.py --check       # 词表自洽性
python .dsh/scripts/tag_vocab.py --emit-doc    # 刷新 TAGS.md
python .dsh/scripts/tag_audit.py               # 全库 tag 审计（非 0 = 有未登记 tag）
python .dsh/scripts/tag_apply.py [--apply]     # 按 map 批量迁移历史 tag
python .dsh/scripts/tag_apply.py --rollback <备份.json>          # 精确回滚
python .dsh/scripts/tag_verify_migration.py    # 独立复核迁移结果

python .dsh/scripts/gen_canvas.py [--check]    # 生成 / 校验概念地图画布
python .dsh/scripts/check_paper_template.py    # 论文页模板合规校验（--links 顺带查死链）

python .dsh/scripts/repo_lint.py               # 提交前扫描：绝对路径 / 用户名 / 凭据 / BOM / 失效链接

python .dsh/scripts/fetch_source.py --arxiv 1706.03762v7   # arXiv/DOI → LaTeX 公式真值（仅标准库）
python .dsh/scripts/extract_pdf.py paper.pdf --math -o out.txt     # PDF 正文抽取（需 PyMuPDF）
python .dsh/scripts/crop_equations.py --manifest m.json --equations e.json --out-dir crops/  # 裁剪公式小图（需 Pillow）

审计类脚本的退出码是有意义的：0 = 通过，非 0 = 有问题，可以直接接进 CI 或 pre-commit。 本仓库自己就接了（见 .github/workflows/ci.yml）：在 Linux 上 用 Python 3.9 与 3.12 各跑一遍「泄露扫描 → 词表自洽 → 模拟安装 → 全量体检」。

配置与自定义

唯一配置源：.dsh/wiki.config.json（改完保存即生效，没有第二步）

Tag 词表：.dsh/tag-vocab.json —— 词表是数据，不是代码。七个分面（domain / task / modality / method / challenge / data / meta）的叶节点与中文释义都在这里；map 用来登记历史别名与近义词的归一化映射。改完按「--check → --emit-doc → tag_apply.py → tag_audit.py」四步走。

库根自动探测：如果你把知识库放在一个更大的 Obsidian 库里（比如 my-vault/notes/），vault_prefix 保持 "auto" 即可 —— 脚本会向上找 .obsidian/ 并自动算出 notes/ 这个前缀，写进 .canvas 的路径永远是对的。也可以显式写死。

Python 依赖（可选）

上面「运行环境」表里的必装项只有 Python 本身。这三个是可选的，只有用到 PDF 公式提取才需要：

把可变依赖关在项目 venv 里，不污染系统 Python：

python -m venv .dsh/venv
# Windows:      .dsh\venv\Scripts\python.exe -m pip install -r .dsh/requirements.txt
# macOS/Linux:  .dsh/venv/bin/python       -m pip install -r .dsh/requirements.txt

或者一步到位：python .dsh/scripts/setup_wiki.py --venv。

缺依赖时脚本不会崩：会打印精确的安装指引并以退出码 1 退出。

设计原则

1. 配置优先于代码：仓库里没有一处绝对路径、盘符或用户名。所有位置由 .dsh/scripts/wiki_env.py 从脚本自身位置推导，配置只描述「相对结构」。
2. 词表是数据：tag 词表放在 JSON 里，才能被审计、被迁移、被 diff。放在 Python 常量里就只能靠人肉守规矩。
3. 不可变层是底线：raw/ 只读只归档。事实来源不被「顺便优化」污染，是知识库能长期可信的前提。
4. 收尾动作必须显式：更新 index.md、追加 log.md、重生成 Canvas 是写页面的一部分，不是可选礼貌。
5. 缺依赖要优雅退化：能降级就降级，不能降级就给出可复制的修复命令 —— 而不是 traceback。
6. 审计用退出码说话：0 / 非 0 比「看起来没问题」可靠。

方法论出处

本工具包的基础方法论来自 Andrej Karpathy 的 llm-wiki.md。

那是一份 "idea file"——刻意写得抽象，只讲 pattern、不讲实现，作者本人的用法是 「直接把它丢给你的 LLM agent，让 agent 和你一起把细节长出来」。本仓库就是它的一个具体实例化： 把抽象 pattern 落成目录契约、技能、脚本和一份开箱即用的安装流程。

📛 三个名字别混（它们会同时出现在文档里）：

名字	指什么	在哪
Scholar LLM Wiki	本工具包 / 这个仓库	README、文档、LICENSE
LLM Wiki	Karpathy 的方法论名	llm-wiki.md、AGENTS.md 的角色定义、本节的对照表
wiki_name	你自己知识库的名字，显示在概念地图画布标题里	.dsh/wiki.config.json，默认 科研 Wiki

项目名里带 LLM Wiki 是故意的——它的意思就是「面向学术的 LLM Wiki」， 名字本身就说明了血统：这不是另起炉灶，是把那份方法论落到科研文献这个场景上。

原方法论 → 本工具包的对应关系

原方法论之上，本仓库补的工程约束

原文档明确说「具体实现取决于你的领域、偏好和 LLM 选择，上面提到的一切都是可选、可拆的」。 以下是这个实例化自己加的：

• Tag 受控词表：七分面 + 封闭词表 + 审计与迁移脚本（原文档没有标签体系）；
• 概念分层与概念地图：母页/子页两级结构，配 gen_canvas.py 生成带结构指纹的 Canvas；
• 可执行的校验：论文页模板、索引一致性、死链与孤儿页、Canvas 同步、词表合规—— 全部用退出码说话，可以接进 CI；
• PDF 公式流水线：arXiv/DOI 取 LaTeX 真值 → 抽取正文 → 按 bbox 裁公式小图核对， 让「摄入一篇论文」在公式上不打折；
• 零硬编码：目录名、词表、领域全部配置化，装到任何机器、任何库上都能跑。

原文档是想法，本仓库是其中一个实现——两者不冲突。如果你想要另一种形状， 最该读的其实是原文档本身；把它丢给你的 agent，让它按你的领域长出一套。

文档

• docs/MANUAL.md —— 用户手册（新手从这里开始，从零讲到进阶）
• AGENTS.md —— 完整架构契约（也是安装后给 AI 读的那份）
• docs/INSTALL.md —— 安装细节、目录布局、故障排查
• docs/CUSTOMIZE.md —— 改目录名 / 换词表 / 换领域 / 加技能
• docs/ARCHITECTURE.md —— 数据流与脚本地图
• TAGS.md —— 内置 tag 受控词表（随包附带的种子词表）

许可

MIT —— 代码、文档、技能文本、tag 词表，整仓同一个许可。

你可以随便用、改、商用、闭源分发，也可以把它装进自己的知识库、把知识库推到自己的仓库。 唯一的义务是保留版权声明与许可证文本——LICENSE 在仓库根有一份， .dsh/LICENSE 还有一份副本，安装时会跟着 .dsh/ 一起进到你的知识库里，不用额外做什么 （安装脚本只复制 .dsh/、AGENTS.md、templates/，许可证已经包含在内）。

为什么两个地方放同一份：知识库通常是一个独立仓库，用户装完之后手上只有 .dsh/， 拿不到仓库根的 LICENSE——那就不满足「随副本保留声明」了。两份文件由 repo_lint.py 强制逐字节一致，不会漂。

改了什么也不用告诉我 —— 但如果你把它用出花来了，欢迎开 issue 说说。