git:20260830.ad65525 to git:20260925.32ce6c0

80 added, 53 removed. Audit A to A.

---

name: obsidian-kb-builder

- description: 快速构建本地知识库（Obsidian 双链图谱）。当用户输入目录 / 文档 / URL 并希望搭建或填充个人知识库、Obsidian vault、互链 markdown 笔记，或导出知识图谱数据时，使用此 skill。This skill should be used when the user wants to scaffold or populate a local personal knowledge base / Obsidian vault from files, folders, or web URLs — preserving text and images and producing interlinked ([[wikilink]]) markdown pages plus exportable graph data.

+ 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

- ## Overview

+ ## Purpose

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

+ 按 Karpathy「LLM Wiki」模式，把目录 / 文档 / URL 转化为一个**持久、互链、可复利**的本地知识库

+ （Obsidian vault）。图谱即 Obsidian 双链图谱：节点是笔记，边是页面间的 `[[链接]]`。

+ 脚本负责机械 I/O（建结构、抓取、图片本地化、导出图数据），AI 负责语义抽取与互链。

- ## When To Use

+ ## When to Use

- - 用户说「建一个知识库 / 个人 wiki / Obsidian vault」「把这批文章/这个文件夹/这个网页纳入知识库」。

+ - 用户说「建一个知识库 / 个人 wiki / Obsidian vault」「把这批文章 / 这个文件夹 / 这个网页纳入知识库」。

- 用户要从 URL、PDF、笔记批量生成互链 markdown 并保留图片。

- 用户要「导出知识图谱 / 图数据」用于可视化或导入 Neo4j / Gephi。

+ - 触发词：知识库、个人 wiki、Obsidian、双链、互链笔记、知识图谱、图数据、vault。

- ## Prerequisites

+ ## When NOT to Use

- - 确定目标 vault 路径（用户指定；不存在则新建）。

- - 访问外网时确保 `http_proxy` / `https_proxy` 环境变量已设置（fetch_source 走代理）。

- - PDF / DOCX 摄入需要本机 `pandoc`（未装则脚本会提示安装）。

+ - 只想要一次性的内容摘要或改写，不建立持久互链库 -> 直接回答或走写作类技能。

+ - 目标平台是云端协作笔记（Notion / 飞书文档），而非本地 markdown vault -> 本技能只产出

+ 本地文件，不负责云端导入。

+ - 只需要转换单个 PDF 为 Markdown -> 用 `pdf2md`。

+ - 用户未指定 vault 路径且不允许新建 -> 先追问路径，不要擅自选目录。

## Workflow

- > **路径约定**：下文命令中的 `<skill>` 指本技能安装目录（如 `~/.claude/skills/obsidian-kb-builder`）。运行脚本时请将 `<skill>` 替换为实际路径，或在技能目录下执行。

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

- ### 1. 初始化（仅首次）

+ 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`，并报告孤儿页与枢纽页。

- 若 vault 不存在或缺少 `raw/`、`wiki/`、`.wiki-schema.md`，运行：

+ ## Decision Rules

- ```bash

- python3 <skill>/scripts/scaffold.py --vault <vault路径> [--topic "知识库主题"]

- ```

+ **选 `--subdir`**：文章 -> `articles`；推文 -> `tweets`；微信公众号 -> `wechat`；

+ 小红书 -> `xiaohongshu`；知乎 -> `zhihu`；PDF -> `pdfs`；手写笔记 -> `notes`。

- 该脚本创建 `raw/{articles,tweets,wechat,xiaohongshu,zhihu,pdfs,notes,assets}`、`wiki/{entities,topics,sources,comparisons,synthesis}`、`.wiki-schema.md`、`index.md`、`log.md`、`purpose.md`。已存在的文件不覆盖。

+ **输入分发**：

- ### 2. 摄入每个输入（fetch_source.py）

+ - URL -> 经 Jina Reader 取干净 markdown；文中图片下载到 `raw/assets/`，改写为本地相对路径。

+ - 本地 `.md`/`.txt`/`.html` -> 直接处理。

+ - 本地 `.pdf`/`.docx` -> 用本机 `pandoc` 转换；未装 pandoc 时脚本会提示安装。

- 对每个 URL 或本地文件运行：

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

- ```bash

- python3 <skill>/scripts/fetch_source.py --input <URL或文件路径> --vault <vault路径> [--subdir articles]

- ```

+ - Obsidian 原生：`[[链接]]` 即图，Graph View 直接看，无需导出。

+ - 结构化导出：`export_graph.py` 产出节点/边 CSV+JSON，用于程序化图分析或导入图数据库。

- - URL：经 Jina Reader 取干净 markdown；文中图片下载到 `raw/assets/`，改写为本地相对路径 `../assets/xxx`。

- - 本地 .md/.txt/.html 直接处理；.pdf/.docx 用 pandoc 转换。

- - 目录：遍历受支持文件，按类型选 `--subdir`（文章→articles，推文→tweets，小红书→xiaohongshu，知乎→zhihu，PDF→pdfs，笔记→notes）。

- - 脚本打印写出的 `raw/.../*.md` 路径与图片统计，AI 据此继续抽取。

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

+ `references/workflow.md`。

- ### 3. 语义抽取与互链（AI 执行，详见 references/workflow.md）

+ ## Constraints

- 读取 `raw/<subdir>/<file>.md` 后：

+ - **`raw/` 是不可变源**：AI 只读不改；所有产物写在 `wiki/`。

+ - **隐私边界**：仅在用户明确指定的 vault 路径下读写；不递归删除、不改动用户原始内容。

+ - **必须互链**：图谱质量取决于 `[[链接]]` 的密度与正确性，而非页面数量——摄入时务必互链。

+ - **不静默覆盖**：新数据反驳旧主张时显式标注矛盾。

+ - **代理**：`fetch_source.py` 走 `http_proxy` / `https_proxy` 环境变量；访问外网前确保已设置。

+ - `.wiki-schema.md` 是运行时配置，可随使用与用户共同演进，不要把它当成一次性生成物。

+ - 图片下载是 best-effort：失败时保留原 URL 并记录 warning，不中断摄入。

- 1. 写 source 摘要页 `wiki/sources/<date>-<slug>.md`；

- 2. 更新 / 新建 `wiki/entities/` 与 `wiki/topics/` 页面，带 YAML frontmatter（`tags/created/updated/sources`）；

- 3. 在相关页面间加 `[[链接]]`，每页底部维护「相关页面」列表（**这是图数据的边，务必互链**）；

- 4. 更新 `index.md`（加一行 `[[页面名]] — 摘要`）；

- 5. 向 `log.md` 追加 `## [YYYY-MM-DD] ingest | <源标题>`。

+ ## Verification

- 新数据反驳旧主张时显式标注矛盾，不静默覆盖。`raw/` 只读不改，所有产物在 `wiki/`。

+ 交付前逐项确认：

- ### 4. 查询与复利

+ - [ ] 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/` 下三个文件已生成，孤儿页/枢纽页报告已给出。

- 对 wiki 提问，答案用 `[[链接]]` 引用；有价值的对比 / 分析 / 新关联存回 `wiki/comparisons/` 或 `wiki/synthesis/`，让探索也复利累积。

+ ## Output

- ### 5. 导出图数据（export_graph.py）

+ - **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。

- ```bash

- python3 <skill>/scripts/export_graph.py --vault <vault路径> [--json]

- ```

+ ## References

- 输出 `graph/graph-nodes.csv`、`graph/graph-edges.csv`、`graph/graph.json`，并报告**孤儿页**（无入链）与**枢纽页**（最多入链）。CSV/JSON 可导入 Neo4j / Gephi。Obsidian 打开 vault → Graph View 即可直接可视化双链图谱。

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

- ## Graph Data

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

- 本知识库的「图数据」有两层含义，按需取用：

+ ## Scripts

- - **Obsidian 原生**：`[[链接]]` 即图，Graph View 直接看，无需额外导出。

- - **结构化导出**：`export_graph.py` 产出节点 / 边 CSV+JSON，用于程序化图分析或导入图数据库。

+ - `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 并报告孤儿页与枢纽页。

- ## Resources

+ ## Troubleshooting

- - `scripts/scaffold.py` — 初始化 vault 结构与配置文件。

- - `scripts/fetch_source.py` — URL / 文档 → 规范化 markdown，图片本地化。

- - `scripts/export_graph.py` — 解析全库 `[[链接]]` 导出图数据。

- - `references/workflow.md` — Ingest / Query / Lint 详细流程、页面格式与命名规范。

+ - `pandoc` 缺失导致 PDF/DOCX 无法摄入 -> 按脚本提示安装 pandoc，或先用 `pdf2md` 转成 markdown 再摄入。

+ - 外网抓取失败 / 超时 -> 检查 `http_proxy` / `https_proxy` 是否设置；脚本网络层统一走 curl。

+ - 图片没落地 -> 查看脚本输出的 warning；失败的图片会保留原始 URL，不影响正文摄入。

+ - 图谱稀疏 / 有孤儿页 -> 是互链不足，回 Workflow 第 3 步补「相关页面」链接后重跑 `export_graph.py`。

- ## Notes

+ ## Related Skills

- - 私人文件安全：仅在用户明确指定的 vault 路径下读写；不递归删除、不改动 `raw/` 原始内容。

- - 图谱质量取决于 `[[链接]]` 的密度与正确性，而非页面数量——摄入时务必互链。

- - `.wiki-schema.md` 是运行时配置，可随使用与用户共同演进。

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