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，可作为本技能的素材预处理步骤。