---
name: obsidian-kb-builder
description: "构建本地知识库（Obsidian 双链图谱）：按 Karpathy「LLM Wiki」模式，把目录 / 文档 / URL 转化为持久、互链、可复利的 markdown 笔记，保留文本与图片，并产出可导出的图数据。触发场景：建知识库、个人 wiki、Obsidian vault、把这批文章/这个文件夹/这个网页纳入知识库、批量生成互链笔记、导出知识图谱/图数据（Neo4j / Gephi）；scaffold or populate a local personal knowledge base / Obsidian vault from files, folders, or web URLs. This skill should be used when the user wants interlinked [[wikilink]] markdown pages plus exportable graph data."
agent_created: true
---

# Obsidian KB Builder

## Purpose

按 Karpathy「LLM Wiki」模式，把目录 / 文档 / URL 转化为一个**持久、互链、可复利**的本地知识库
（Obsidian vault）。图谱即 Obsidian 双链图谱：节点是笔记，边是页面间的 `[[链接]]`。
脚本负责机械 I/O（建结构、抓取、图片本地化、导出图数据），AI 负责语义抽取与互链。

## When to Use

- 用户说「建一个知识库 / 个人 wiki / Obsidian vault」「把这批文章 / 这个文件夹 / 这个网页纳入知识库」。
- 用户要从 URL、PDF、笔记批量生成互链 markdown 并保留图片。
- 用户要「导出知识图谱 / 图数据」用于可视化或导入 Neo4j / Gephi。
- 触发词：知识库、个人 wiki、Obsidian、双链、互链笔记、知识图谱、图数据、vault。

## When NOT to Use

- 只想要一次性的内容摘要或改写，不建立持久互链库 -> 直接回答或走写作类技能。
- 目标平台是云端协作笔记（Notion / 飞书文档），而非本地 markdown vault -> 本技能只产出
  本地文件，不负责云端导入。
- 只需要转换单个 PDF 为 Markdown -> 用 `pdf2md`。
- 用户未指定 vault 路径且不允许新建 -> 先追问路径，不要擅自选目录。

## Workflow

> **路径约定**：下文 `<skill>` 指本技能安装目录（如 `~/.claude/skills/obsidian-kb-builder`）。

1. **初始化（仅首次）**：若 vault 不存在或缺少 `raw/`、`wiki/`、`.wiki-schema.md`，运行
   `python3 <skill>/scripts/scaffold.py --vault <vault路径> [--topic "知识库主题"]`。
2. **摄入每个输入**：对每个 URL 或本地文件运行
   `python3 <skill>/scripts/fetch_source.py --input <URL或文件路径> --vault <vault路径> [--subdir articles]`；
   目录输入则遍历其中受支持文件逐个调用。
3. **语义抽取与互链（AI 执行）**：读取 `raw/<subdir>/<file>.md` 后依次完成——
   ① 写 source 摘要页 `wiki/sources/<date>-<slug>.md`；② 更新/新建 `wiki/entities/` 与
   `wiki/topics/` 页面（带 YAML frontmatter：`tags/created/updated/sources`）；③ 在相关页面间加
   `[[链接]]`，每页底部维护「相关页面」列表（**这是图数据的边，务必互链**）；④ 更新 `index.md`
   （加一行 `[[页面名]] — 摘要`）；⑤ 向 `log.md` 追加 `## [YYYY-MM-DD] ingest | <源标题>`。
4. **查询与复利**：对 wiki 提问，答案用 `[[链接]]` 引用；有价值的对比 / 分析 / 新关联存回
   `wiki/comparisons/` 或 `wiki/synthesis/`。
5. **导出图数据**：`python3 <skill>/scripts/export_graph.py --vault <vault路径> [--json]`，
   输出 `graph/graph-nodes.csv`、`graph/graph-edges.csv`、`graph/graph.json`，并报告孤儿页与枢纽页。

## Decision Rules

**选 `--subdir`**：文章 -> `articles`；推文 -> `tweets`；微信公众号 -> `wechat`；
小红书 -> `xiaohongshu`；知乎 -> `zhihu`；PDF -> `pdfs`；手写笔记 -> `notes`。

**输入分发**：

- URL -> 经 Jina Reader 取干净 markdown；文中图片下载到 `raw/assets/`，改写为本地相对路径。
- 本地 `.md`/`.txt`/`.html` -> 直接处理。
- 本地 `.pdf`/`.docx` -> 用本机 `pandoc` 转换；未装 pandoc 时脚本会提示安装。

**图数据取用两条路**：

- Obsidian 原生：`[[链接]]` 即图，Graph View 直接看，无需导出。
- 结构化导出：`export_graph.py` 产出节点/边 CSV+JSON，用于程序化图分析或导入图数据库。

**下钻详细流程**：需要 Ingest / Query / Lint 完整流程、页面格式示例与命名规范时，读
`references/workflow.md`。

## Constraints

- **`raw/` 是不可变源**：AI 只读不改；所有产物写在 `wiki/`。
- **隐私边界**：仅在用户明确指定的 vault 路径下读写；不递归删除、不改动用户原始内容。
- **必须互链**：图谱质量取决于 `[[链接]]` 的密度与正确性，而非页面数量——摄入时务必互链。
- **不静默覆盖**：新数据反驳旧主张时显式标注矛盾。
- **代理**：`fetch_source.py` 走 `http_proxy` / `https_proxy` 环境变量；访问外网前确保已设置。
- `.wiki-schema.md` 是运行时配置，可随使用与用户共同演进，不要把它当成一次性生成物。
- 图片下载是 best-effort：失败时保留原 URL 并记录 warning，不中断摄入。

## Verification

交付前逐项确认：

- [ ] vault 内存在 `raw/`、`wiki/`、`.wiki-schema.md`、`index.md`、`log.md`、`purpose.md`。
- [ ] 每个输入都产出了 `raw/<subdir>/<date>-<slug>.md`，图片已本地化到 `raw/assets/`。
- [ ] 新建/更新的 wiki 页面带 YAML frontmatter，且底部有「相关页面」`[[链接]]`。
- [ ] `index.md` 已加对应行，`log.md` 已追加 ingest 记录。
- [ ] 需要图数据时 `graph/` 下三个文件已生成，孤儿页/枢纽页报告已给出。

## Output

- **Outcome**：一个结构化的本地 vault——`raw/`（不可变素材）+ `wiki/`（互链知识页）+
  `index.md` / `log.md` / `purpose.md` / `.wiki-schema.md`；按需附 `graph/` 图数据。
- **Done when**：`## Verification` 全部勾选，且用户可在 Obsidian 中打开 vault 看到双链图谱。
- **Evidence**：脚本打印的写入路径与图片统计；wiki 页之间的 `[[链接]]`；`graph/graph.json`
  中的 nodes / edges / orphans / hubs。

## References

按需加载，不要预先全读：

- `references/workflow.md` — 需要 Ingest / Query / Lint 详细流程、页面格式示例或命名规范时读。

## Scripts

- `scripts/scaffold.py` — 初始化 vault 结构（`raw/` 与 `wiki/` 子目录）与配置文件；幂等，
  已存在的文件不覆盖。用法 `--vault <路径> [--topic "主题"]`，打印新建项清单。
- `scripts/fetch_source.py` — 把 URL 或本地文档规范化为 markdown 并把图片落到 `raw/assets/`。
  用法 `--input <URL|文件> --vault <路径> [--subdir articles] [--date YYYY-MM-DD]`，
  打印写出的 `raw/.../*.md` 路径与图片统计。
- `scripts/export_graph.py` — 解析全库 `[[链接]]` 导出图数据。用法 `--vault <路径> [--out <目录>] [--json]`，
  输出节点/边 CSV+JSON 并报告孤儿页与枢纽页。

## Troubleshooting

- `pandoc` 缺失导致 PDF/DOCX 无法摄入 -> 按脚本提示安装 pandoc，或先用 `pdf2md` 转成 markdown 再摄入。
- 外网抓取失败 / 超时 -> 检查 `http_proxy` / `https_proxy` 是否设置；脚本网络层统一走 curl。
- 图片没落地 -> 查看脚本输出的 warning；失败的图片会保留原始 URL，不影响正文摄入。
- 图谱稀疏 / 有孤儿页 -> 是互链不足，回 Workflow 第 3 步补「相关页面」链接后重跑 `export_graph.py`。

## Related Skills

- `pdf2md` — 把 PDF 转为高保真 Markdown，可作为本技能的素材预处理步骤。