| 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. |
| agent_created | true |
Obsidian KB Builder
Overview
按 Karpathy「LLM Wiki」模式，把目录 / 文档 / URL 转化为一个持久、互链、可复利的本地知识库（Obsidian vault）。图谱即 Obsidian 双链图谱：节点是笔记，边是页面间的 [[链接]]。脚本负责机械的 I/O（建结构、抓取法、图片本地化、导出图数据），AI 负责语义抽取与互链。
When To Use
- 用户说「建一个知识库 / 个人 wiki / Obsidian vault」「把这批文章/这个文件夹/这个网页纳入知识库」。
- 用户要从 URL、PDF、笔记批量生成互链 markdown 并保留图片。
- 用户要「导出知识图谱 / 图数据」用于可视化或导入 Neo4j / Gephi。
Prerequisites
- 确定目标 vault 路径（用户指定；不存在则新建）。
- 访问外网时确保
http_proxy / https_proxy 环境变量已设置（fetch_source 走代理）。
- PDF / DOCX 摄入需要本机
pandoc（未装则脚本会提示安装）。
Workflow
路径约定：下文命令中的 <skill> 指本技能安装目录（如 ~/.claude/skills/obsidian-kb-builder）。运行脚本时请将 <skill> 替换为实际路径，或在技能目录下执行。
1. 初始化（仅首次）
若 vault 不存在或缺少 raw/、wiki/、.wiki-schema.md，运行：
python3 <skill>/scripts/scaffold.py --vault <vault路径> [--topic "知识库主题"]
该脚本创建 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 或本地文件运行：
python3 <skill>/scripts/fetch_source.py --input <URL或文件路径> --vault <vault路径> [--subdir articles]
- 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 据此继续抽取。
3. 语义抽取与互链（AI 执行，详见 references/workflow.md）
读取 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 | <源标题>。
新数据反驳旧主张时显式标注矛盾，不静默覆盖。raw/ 只读不改，所有产物在 wiki/。
4. 查询与复利
对 wiki 提问，答案用 [[链接]] 引用；有价值的对比 / 分析 / 新关联存回 wiki/comparisons/ 或 wiki/synthesis/，让探索也复利累积。
5. 导出图数据（export_graph.py）
python3 <skill>/scripts/export_graph.py --vault <vault路径> [--json]
输出 graph/graph-nodes.csv、graph/graph-edges.csv、graph/graph.json，并报告孤儿页（无入链）与枢纽页（最多入链）。CSV/JSON 可导入 Neo4j / Gephi。Obsidian 打开 vault → Graph View 即可直接可视化双链图谱。
Graph Data
本知识库的「图数据」有两层含义，按需取用：
- Obsidian 原生：
[[链接]] 即图，Graph View 直接看，无需额外导出。
- 结构化导出：
export_graph.py 产出节点 / 边 CSV+JSON，用于程序化图分析或导入图数据库。
Resources
scripts/scaffold.py — 初始化 vault 结构与配置文件。scripts/fetch_source.py — URL / 文档 → 规范化 markdown，图片本地化。scripts/export_graph.py — 解析全库 [[链接]] 导出图数据。references/workflow.md — Ingest / Query / Lint 详细流程、页面格式与命名规范。
Notes
- 私人文件安全：仅在用户明确指定的 vault 路径下读写；不递归删除、不改动
raw/ 原始内容。
- 图谱质量取决于
[[链接]] 的密度与正确性，而非页面数量——摄入时务必互链。
.wiki-schema.md 是运行时配置，可随使用与用户共同演进。
