关键词：Python、Obsidian、双链、AI 摘要、文档转换、自动化、Markdown、Skill

仓库地址：https://github.com/Hbin-difficulty/obsidian-note-pipeline （MIT 协议，纯 Python）

---

一、背景：为什么写这个工具

做技术笔记的人大概率都有过这种体验：读完一篇 14 页的 PDF 教程，想塞进 Obsidian 笔记库，于是开启一段"手动流水线"——

1. 复制粘贴正文

1. 手写 frontmatter（title / tags / 日期）

1. 写一段 AI 摘要

1. 最痛苦的一步：通读全文，把"提示词""回滚""类型安全"这些概念词手动包上 [[ ]] 做成双链

1. 校对标题层级、代码块语言标记……

一篇半小时，几十篇就是几十个小时。这种机械又繁琐的活，正好是脚本 + AI 最擅长的事。

于是我把这套流程做成了一个 通用 Skill：扔进去 PDF / Word / TXT，出来就是带 [[双链]] + AI摘要 的规范 Obsidian 笔记。

---

二、项目简介

核心逻辑只有一句话：

先判断文件类型 → 若是 .md 直接处理；否则先转成 Markdown（图片以 base64 内嵌），再套用笔记库规范处理。

输入格式	处理方式
.md	直接处理，跳过转换
.pdf	PyMuPDF 转换（相对字号分层、Menlo 识别代码块、图片 base64 内嵌）
.docx	纯标准库（zipfile + xml.etree）转换，零第三方依赖
.txt	轻量包裹为 Markdown 后处理
其他	报错并提示不支持

处理阶段对笔记做的机械操作（AGENTS.md / PRD.md 流水线）：

步骤	做什么
格式规范化	setext 标题 → ATX、裸代码块补语言标记、列表统一
frontmatter	写入 title / tags / ai_processed / ai_version
## 📝 AI摘要	AI 生成的核心观点（3~5 句）+ 相关笔记 + 关键标签
[[概念]] 双链	自动识别正文概念词，首次出现处加链接（支持整篇 / #标题 / #^块ID 三粒度）
AI 疑问	文末加 `` 注释，标注矛盾或疑点

注意：摘要文本和概念词表是需要"判断力"的内容，由 AI Agent 生成后传给脚本做机械注入。所以它是"人 + AI 协作"的 Skill，而非纯命令行工具。

---

三、环境准备与安装

3.1 依赖

• Python 3.8+（标准库即可跑 DOCX / TXT / MD 处理）

• PDF 转换需要 PyMuPDF（可选，只处理 PDF 时才装）

3.2 下载

3.3 放到 skills 目录

这个 Skill 是通用的，主流 AI 编程工具都支持 SKILL.md 描述文件，把文件夹拷贝过去即可：

AI 软件	目录
WorkBuddy / CodeBuddy	~/.workbuddy/skills/obsidian-note-pipeline/
Claude Code	~/.claude/skills/obsidian-note-pipeline/
Cursor	<项目>/.cursor/skills/obsidian-note-pipeline/
其他	任何读取 SKILL.md / 自定义指令的目录

同一个文件夹，拷过去就能用，不需要改一行代码。

---

四、快速上手：命令行用法

除了在 AI 对话里说"把 xxx.pdf 转成笔记并处理"，也可以直接跑脚本：

参数说明：

参数	作用
--title	笔记标题（写入 frontmatter）
--tags	白名单标签，逗号分隔
--summary-text	AI 摘要内容（AI 生成后传入）
--concepts	要注入双链的概念词表，逗号分隔
--out	输出路径
--doubts-text	AI 疑问内容（可选）

---

五、核心代码解析

下面拆解四个关键模块的真实实现（已精简注释）。

5.1 入口：类型检测与分流

run_pipeline.py 的 main() 根据扩展名分流，是整套 skill 的"中枢"：

要点：.md 路径不进入临时文件，原地处理；PDF 转换前先 import fitz 探活，缺失就给出明确安装提示而不是崩溃。

5.2 PDF → Markdown：相对字号分层

PDF 没有"标题"语义，只有字体大小。convert_pdf.py 先用一遍扫描统计字号分布，再按相对大小定标题层级——这样换一份字号体系完全不同的 PDF 也不会错：

另一个坑是代码块识别：很多 PDF 用 Menlo 等等宽字体排代码，但有些中文正文行恰好也用了等宽字体。直接全当代码会误判，所以加了 is_real_code() 二次校验——中文整行且无代码符号的，降级回正文：

图片则用 extract_image(xref) 取真实二进制，转成 base64 data URI 内嵌进 MD，保证笔记文件自包含、不依赖外部图片：

5.3 DOCX → Markdown：零依赖

Word 本质是 zip 包，convert_docx.py 用 zipfile + xml.etree 解析 word/document.xml，不依赖 python-docx：

图片通过 document.xml.rels 里的 relId 映射到 word/media/ 下的真实文件，同样 base64 内嵌。

5.4 双链注入：inject_concepts

这是"自动双链"的核心。逐行扫描正文，跳过代码块，每个概念词只在首次出现处链接，且避让已有的 [[...]]：

5.5 frontmatter 与摘要

build_frontmatter() 固定 title / tags / ai_processed / ai_version 四个字段顺序，并保留原 frontmatter 里的其它键：

---

六、效果演示

下面是我用同一份 Skill 处理后的两篇真实笔记截图。

![处理后笔记：项目开发流程（PDF 转换）]

上图：PDF 转换后的笔记——frontmatter 完整、AI 摘要清晰、正文结构化。

![自动双链效果：debug_纠错]

上图：[[提示词]]、[[回滚]]、[[类型安全]] 等概念词被自动识别并链接（蓝色），非手打。

整体处理流程（文档 → Skill → 规范笔记）：

Before / After 对比，直观感受自动化的差距：

---

七、多 AI 工具通用（重点）

最初这个 Skill 路径写死、Python 环境绑死在某个软件上。后来我做了三件事让它通用：

1. 去硬编码：脚本统一用 python3 / python 运行，依赖缺失时明确报错；

1. 支持 SKILL.md 格式：主流 AI 工具都认这个描述文件，拷贝即装；

1. 纯 Python 3 + 可选依赖：核心用标准库，唯一可选依赖 PyMuPDF（pip install pymupdf 一条命令）。

无 Docker、无 Node.js、无配置文件，Windows / macOS / Linux 通吃。

---

八、已知局限（诚实声明）

• PDF 列表序号可能丢失：很多 PDF 把列表数字渲染成图形而非文字，提取时天然丢失，Skill 会如实告知不编造；

• 双链可能指向未创建的笔记：Obsidian 点击未存在的双链会自动新建，若你的 vault 要求只链已有笔记需先确认；

• AI 摘要质量取决于模型：不同 AI 生成质量有差异，建议用你信任的模型。

---

九、开源地址与总结

GitHub：Hbin-difficulty/obsidian-note-pipeline（MIT 协议，欢迎 Star / Issue / PR）

从 PDF 到规范 Obsidian 笔记，真的只需要一句话或一个命令。如果你也厌倦了手动加双链，不妨拉下来试试。

---

如果本文对你有帮助，欢迎点赞收藏；有问题或改进建议，直接在仓库提 Issue。