

## 一、背景：为什么需要这次重整


我硬盘上有不同科目类别的书籍,天文地理历史,从孩子教育到大学专业书籍,再到杂志,商业评论,技术文章等等,杂乱无章,且有很多存在书籍重复在分布在不同或者近似的文件夹,自己收集整理起来很费劲. 后来通过wiki和基于 Obsidian 的电子书库来整理,再结合workbuddy的obsidian相关技能,对书籍的分类,去重,以及obsidian的wiki风格整理,改善了书籍资料的存储分布,也去掉没有必要的分类方式,使得书籍更有效的存放在 Mac Studio 本地. 这些书籍上按《中国图书馆分类法》（CLC）组织。书库经历了多次迁移和脚本处理，积累了不少历史债,书籍分类不科学：


- 书是按分类放好了，但****点开就出问题****——有的链接指向已删除的文件，有的直接打开几个 GB 的 PDF 把 Obsidian 卡死

- 之前用脚本批量生成了****2,737 个书评笔记****，但全是"暂无简介"的桩文件，和导航页（MOC）完全脱节

- 装了 Dataview 和 Templater 两个核心插件，但****零配置****——等于没装

- CSS 样式表引用了但文件不存在，元数据 JSON 导出了但从未被使用


一句话概括：****有基础设施但没接线，有数据但没激活。****


---


## 二、现状盘点


| 指标 | 数值 |

|------|------|

| 电子书文件（PDF/EPUB） | 2,165 本 |

| 总大小 | ~65 GB |

| 分类 | 7 大类（O1 数学、O4 物理、O6 化学、O7 晶体学、Q 生物、R 医药、T 工业技术） |

| .md 笔记文件 | 2,745 个（8 个分类导航 + 2,737 个书评桩） |

| 已装插件 | Dataview + Templater（均未配置） |

| 元数据文件 | books_metadata.json（928KB，静态导出，未被使用） |


---


## 三、问题诊断：4 个维度 14 项问题


我让 WorkBuddy 全面扫描了 Vault，它从四个维度给出了诊断：


### 维度一：书目展现（7 项）


- ****书名 = 纯数字文件名****：`1291.pdf`、`7837.pdf`、`06.pdf`——完全看不出是什么书

- ****作者解析错误****："721s"（页数）被当成作者；"3203720"（ISBN 编号）被当成作者；"NOISBN" 被当成作者

- ****2,737 个书评笔记全为"暂无简介"****——有笔记等于没笔记

- ****两套导航共存****：新版 MOC（`O1 数学.md`）vs 旧版 `README.md`（32 个），互相打架

- ****所有表格为静态 Markdown****——增删书后不会自动更新，手动维护到死


### 维度二：链接点击（5 项）


- ****wikilink 直指 PDF 文件****：点击 `[[力学郑永令.pdf]]` 直接打开 2.82GB 的 PDF，Obsidian 直接卡死

- ****没有书详情中间页****：无法在打开 PDF 前查看元数据、阅读笔记

- ****书评笔记中有大量断链****：`[[O 数理科学和化学/README]]` 指向已不存在的文件

- ****2,737 个笔记与导航页完全脱节****：从 MOC 表格点不到书评笔记，从书评笔记也回不到 MOC

- ****无面包屑导航****：在深层子分类页面不知道自己在哪


### 维度三：笔记方式（4 项）


- ****Templater 已启用但无模板目录****：`templates/` 目录不存在

- ****Dataview 已启用但零使用****：frontmatter 里有 status/rating 字段，从未被任何查询使用

- ****书评笔记模板质量低****：大量字段为"未知"或无效值

- ****无阅读进度追踪****：2,207 本书全显示"未读"，没有看板


### 维度四：配置问题（4 项）


- ****CSS snippet 文件缺失****：配置里引用了 `book-styles`，但 `snippets/` 目录不存在

- ****Templater 无配置文件****：`data.json` 不存在

- ****showFrontmatter: false****：YAML 元数据在预览模式不可见

- ****无定制视觉风格****：纯默认主题


---


## 四、改造路线图


我采用了 ****P0 → P1 → P2 → P3 → P4 → P5**** 的分阶段策略，每一阶段都有明确的验收标准：


| 阶段 | 目标 | 方法 | 工作量 |

|------|------|------|--------|

| P0 | 激活基础设施 | 手动创建 CSS/模板/配置 | 小 |

| P1 | 体验质变 | Python 脚本重写 MOC + 修复链接 | 中 |

| P2 | 数据清洗 | Python 脚本从 metadata 补全数据 | 大 |

| P3 | 补全缺失 | Python 脚本为遗漏 PDF 创建笔记 | 中 |

| P4 | 目录重整 | Python 脚本清理孤儿 + 重生成导航 | 中 |

| P5 | 扩展分类 | 手动创建新分类结构 | 小 |


---


## 五、逐步操作过程


### P0：激活基础设施（配置层修复）


****目标****：让已安装但未配置的插件和样式生效。


#### 操作 1：创建 CSS snippet


在 `.obsidian/snippets/book-styles.css` 创建样式文件，包含：

- 书籍表格斑马纹

- MOC 卡片样式

- 面包屑导航样式

- PDF 嵌入容器

- 阅读状态标签


#### 操作 2：创建书评模板


在 `Templates/书评模板.md` 创建标准模板：


```yaml

---

isbn: ""

title: "{{title}}"

author: ""

publisher: ""

clc_category: ""

sub_category: ""

tags:

  - 书籍

status: "未读"

rating:

date_added: "{{date}}"

file: ""

---

```


模板结构：基本信息表 → 内容简介 → 读书笔记（摘录/感悟/待探索）→ 原书嵌入 → 相关书目


#### 操作 3：配置 Templater


创建 `.obsidian/plugins/templater-obsidian/data.json`：


```json

{

  "templates_folder": "Templates",

  "trigger_on_file_creation": **true**

}

```


#### 操作 4：修复 showFrontmatter


`app.json` 中 `"showFrontmatter": false` → `"showFrontmatter": true`


改造后安装的插件状态（Dataview + Templater + PDF++）：


改造后已安装的 Obsidian 插件
![screenshot-plugins.png](https://developer.qcloudimg.com/http-save/yehe-3797819/93d97dcfcacba3c81ad56a0b287c6d62.png)


****给 WorkBuddy 的提示词****：


> 帮我看 /Users/tony/BooksLib 目录的 obsidian vault 有无改进效果的地方，包括书目展现、链接点击、笔记方式，等等


WorkBuddy 自动扫描了 vault 结构、配置文件、插件状态、笔记内容，输出了 4 维度 14 项问题的诊断报告，然后我指示：


> 全部都做


它创建了任务清单，按 P0→P1→P2 顺序执行。


---


### P1：Dataview 驱动 + 链接修复


****目标****：把静态表格改为 Dataview 动态查询，修复所有断链。


#### 步骤 1：备份


先备份所有现有 .md 文件到 `.backup_md_20260707_215502/`，确保可回滚。


#### 步骤 2：重写首页和 MOC


写 Python 脚本（`p1_rewrite_mocs.py`），将所有 MOC 页面改为 Dataview 查询：


****改前****（静态 Markdown 表格）：

```markdown

| 1 | [[O1 数学/金融数学/The Model Thinker.pdf|The Model Thinker]] | 未知 | PDF | 11.3 MB |

```


****改后****（Dataview 动态查询）：

```sql

-- Dataview 查询（Obsidian Dataview 插件语法，类 SQL）

**TABLE** **WITHOUT** ID

  file.link **AS** 书名,

  author **AS** 作者,

  status **AS** 状态,

  rating **AS** 评分

**FROM** "O1 数学/金融数学"

**WHERE** contains(tags, "书籍")

SORT file.name **ASC**

```


关键改进：

- 表格从****指向 PDF**** 改为****指向 .md 笔记****（避免直接打开大文件）

- 顶部添加****面包屑导航****：`[[首页|首页]] › [[O1 数学|O1 数学]] › 金融数学`

- 首页改为****仪表盘****：自动统计、最近添加、高分推荐、正在阅读


#### 步骤 3：修复断链


写脚本（`p2_fix_broken_links.py`）批量替换：

- `[[O 数理科学和化学/README]]` → `[[O4 物理学]]`

- 修复 213 个文件中的 426 个断链

- 修复 6 个括号截断的 wikilink


****执行结果****：

- 重写 1 个首页 + 7 个分类 MOC + 34 个子分类 MOC

- 全部改为 Dataview TABLE + 面包屑导航


---


### P2：数据清洗


****目标****：从 books_metadata.json 补全真实元数据，修复无效作者。


写脚本（`p3_data_cleanup.py`）：

1. 加载 `books_metadata.json`（2,207 本书的元数据）

2. 遍历所有 .md 笔记，用正则匹配清洗作者字段：

   - 纯数字（"3203720"）→ 清空

   - 页数标记（"721s"）→ 清空

   - "NOISBN" → 清空

   - "未知" → 清空

3. 补全标题、文件大小、格式等字段

4. 为无笔记的书创建新笔记


****执行结果****：

- 更新 933 个现有笔记的 frontmatter

- 新建 985 个书评笔记

- 作者字段清洗完成


---


### P3：补全缺失笔记


****问题发现****：P2 只覆盖了 `books_metadata.json` 中的 2,207 本，但实际有 2,165 个 PDF——部分 PDF 不在元数据中，没有笔记。


****用户反馈****：

> 有些书有名字，但是点击打不开，有些打得开


WorkBuddy 诊断后发现 ****527 个 PDF 缺少对应 .md 笔记****，Dataview 表格里显示了书名但点击无效。


写脚本（`p4_missing_notes.py`）：

- 扫描所有 PDF

- 从文件名提取书名（处理"系列名 - 书名 - 作者"、"书名-未知-页数"等模式）

- 为 527 个缺失 PDF 创建标准格式笔记


****标题提取规则****（核心逻辑）：

```text

模式1: "系列名 - 书名 - 作者" → 取中间

模式2: "书名 - 作者" → 取书名

模式3: "[系列] 书名" → 取书名

模式4: "书名-未知-页数" → 取书名

模式5: "书名_1" → 去掉后缀

```


****执行结果****：527 个笔记创建完成，剩余缺失 = 0。


---


### P4：目录重整——清理幽灵数据


****问题发现****：经过前几轮脚本处理，累积了大量****孤儿笔记****——.md 文件指向已不存在的 PDF。


写脚本（`p5_reorganize_catalog.py`）：

1. 扫描所有 PDF 和 .md，交叉比对

2. 备份 2,036 个孤儿笔记到 `__backup_orphans_20260707_221053/`

3. 删除全部孤儿 + 清理 48 个空目录

4. 重新生成首页和所有 MOC（基于实际 PDF 分布）


****执行结果****：


| 指标 | 整理前 | 整理后 |

|------|--------|--------|

| PDF | 2,165 | 2,165 |

| 书评 .md | 4,250 | ****2,165****（1:1 精准匹配） |

| 孤儿笔记 | 2,085 | ****0**** |

| MOC 页面 | 8 | 33（首页 + 7 分类 + 25 子分类） |

| 空目录碎片 | 48 个 | 全部清理 |


---


### P5：扩展分类


用户后续请求添加语言学习分类，WorkBuddy 快速创建了 `H 语言、文字` 分类：

- 9 个子分类目录（综合、英语、日语、韩语、法语、德语、泰语、马来语、其他语言）

- 每个子分类创建 MOC 页面（面包屑 + Dataview 查询）

- 更新首页仪表盘（分类数 7→8，Dataview 查询范围扩展）


---


## 六、关键提示词记录


以下是整个过程中给 WorkBuddy 的核心提示词，按阶段排列：


### 诊断阶段


```text

帮我看 /Users/tony/BooksLib 目录的 obsidian vault 有无改进效果的地方，

包括书目展现，链接点击，笔记方式，等等

```


→ WorkBuddy 扫描了 vault 结构、.obsidian 配置、插件状态、笔记内容，输出 4 维度 14 项问题诊断。


### 执行阶段


```text

全部都做

```


→ WorkBuddy 创建 7 个任务（P0-1 到 P2），按优先级顺序执行。


### 问题排查阶段


```text

有些书有名字，但是点击打不开，有些打得开

```


→ WorkBuddy 诊断出 527 个 PDF 缺少 .md 笔记，写脚本补全。


```text

帮我重新整理下有效的书目录，同步到 vault 里面

```


→ WorkBuddy 发现 2,036 个孤儿笔记，备份后清理，重生成导航。


```text

帮我修改 obsidian 的 vault，添加一个语言学习的分类进去

```


→ WorkBuddy 创建 H 语言、文字分类，9 个子分类 + MOC 页面 + 首页更新。


---


## 七、经验总结


### 1. 诊断先行，不要急着动手


先用 AI Agent 做一次全面扫描，拿到问题清单后再制定优先级。我们的案例中，14 项问题分了 3 个优先级，P0 可以立即执行，P2 需要写脚本——如果一开始就盲目写脚本，很容易遗漏配置层的问题。


### 2. 每一步都要备份


每次批量修改 .md 文件前，先备份。我们创建了两个备份目录：

- `.backup_md_20260707_215502/`（P1 重写前的原始版本）

- `__backup_orphans_20260707_221053/`（P4 清理的孤儿笔记）


万一脚本出了问题，可以直接恢复。


### 3. PDF 和 .md 必须保持 1:1


这是整个治理的核心原则：

- ****每个 PDF 对应一个 .md 笔记****（书详情页）

- ****MOC 表格的链接指向 .md 而非 PDF****（避免直接打开大文件）

- ****.md 笔记里嵌入原书 PDF****（用户选择何时打开）


1:1 匹配消除了"有名字打不开"和"幽灵笔记"两类问题。


### 4. Dataview 是 Obsidian 知识库的灵魂


静态表格的最大问题是****维护成本****——每次增删书都要手动更新。Dataview 查询是动态的：

- 新增一个 PDF + .md 笔记 → MOC 表格自动出现

- 删除一个 .md → MOC 表格自动消失

- 修改 status 字段 → 首页仪表盘自动更新


一次配置，永久受益。


### 5. 文件名提取是脏活


从杂乱文件名提取书名，准确率约 90%。常见模式：

- `系列名 - 书名 - 作者.pdf`（三段式，取中间）

- `书名-未知-页数.pdf`（带页数后缀，去尾）

- `书名_1.pdf`（分册后缀，去后缀）


剩余 10% 需要手动微调，但 90% 的自动化已经省了大量时间。


### 6. AI Agent 的价值在于"诊断 + 执行"一体


传统方式需要：人工排查问题 → 写脚本 → 执行 → 验证 → 发现新问题 → 再写脚本。


用 WorkBuddy 的方式：一句话描述现象 → AI 诊断根因 → 自动写脚本 → 执行 → 验证 → 反馈。整个循环在几分钟内完成。


---


## 八、最终架构


改造后的 Obsidian 首页仪表盘（Dataview 驱动，自动统计/最近添加/阅读进度）：

知识库目录结构（CLC 分类 + 子分类 + 1:1 PDF/MD 匹配）：


知识库目录结构
![screenshot-folders.png](https://developer.qcloudimg.com/http-save/yehe-3797819/f0b4250f1d119ac882aa5cd77a1c54a9.png)


```text

BooksLib/

├── 首页.md                    ← 仪表盘（Dataview 驱动）

├── H 语言、文字.md             ← 分类 MOC

├── H 语言、文字/

│   ├── 综合.md                ← 子分类 MOC

│   ├── 英语.md

│   ├── 英语/

│   │   ├── 新概念英语.pdf      ← 原书文件

│   │   └── 新概念英语.md       ← 书评笔记（1:1 匹配）

│   └── ...

├── O1 数学.md

├── O1 数学/

│   ├── 几何与拓扑.md

│   ├── 几何与拓扑/

│   │   ├── 微分几何.pdf

│   │   └── 微分几何.md

│   └── ...

├── .obsidian/

│   ├── app.json               ← showFrontmatter: true

│   ├── community-plugins.json ← Dataview + Templater + CSS

│   ├── snippets/

│   │   └── book-styles.css    ← 定制样式

│   └── plugins/

│       ├── dataview/

│       └── templater-obsidian/

│           └── data.json      ← templates_folder: "Templates"

└── Templates/

    └── 书评模板.md             ← Templater 模板

```


---


## 九、数据对比


| 维度 | 改造前 | 改造后 |

|------|--------|--------|

| MOC 表格 | 静态 Markdown，手动维护 | Dataview 动态查询，自动更新 |

| 书目链接 | 直指 PDF（点击卡死） | 指向 .md 笔记（先看详情再开 PDF） |

| 断链 | 426 个 | 0 |

| 面包屑导航 | 无 | 顶部 `首页 › 分类 › 子分类` |

| CSS 样式 | 引用了但文件不存在 | 已创建并启用 |

| Templater | 已装但无配置 | 已配置模板目录 |

| 书评笔记 | 2,737 个桩（全"暂无简介"） | 2,165 个（1:1 匹配，含真实元数据） |

| 孤儿笔记 | 2,085 个 | 0 |

| 阅读追踪 | 不可见 | showFrontmatter: true + Dataview 看板 |

| 分类数 | 7 | 8（新增 H 语言、文字） |


---


## 十、后续维护指南


### 添加新书


1. 把 PDF 放到对应子分类目录（如 `H 语言、文字/英语/`）

2. 在 Obsidian 中用 Templater 新建同名 .md 笔记

3. Dataview 自动在 MOC 表格中显示

Obsidian的插件启用
![screenshot-plugins.png](https://developer.qcloudimg.com/http-save/yehe-3797819/b795823ffcca1ba578bcabae7662d6f5.png)


### 修改阅读状态


在书评笔记的 frontmatter 中修改：

```yaml

status: "在读"    # 未读 / 在读 / 已读

rating: 4         # 1-5

date_read: "2026-07-08"

```


首页仪表盘的"正在阅读"和"高分推荐"会自动更新。


### 定期检查


运行以下命令检查 PDF 与 .md 的匹配情况：

```bash

python3 scripts/p5_reorganize_catalog.py  # 会输出缺失/孤儿统计

```


---


## 写在最后


这次重整的核心不是"建了多少新东西"，而是"****把现有零件接上线****"。2,165 本书、4,258 个 .md 文件、65GB 数据——靠手动整理不现实，但用 AI Agent + 脚本化的方式，从诊断到完成只用了几个小时。


关键在于：****让 AI 做诊断和脚本编写，让人做决策和验收。**** AI Agent 不是替代你整理书库，而是把整理书库这件事从"不可能"变成"一个下午就能搞定"。

Obsidian的页面优化,阅读体验改进,在日常读的时候根据自己的要求,可以在第三方插件找工具,也可以让workbuddy通过技能来帮忙优化改进.


---


**本文基于 2026 年 7 月 7-8 日的实际操作记录整理。*

我硬盘上有不同科目类别的书籍,天文地理历史,从孩子教育到大学专业书籍,再到杂志,商业评论,技术文章等等,杂乱无章,且有很多存在书籍重复在分布在不同或者近似的文件夹,自己收集整理起来很费劲. 后来通过wiki和基于 Obsidian 的电子书库来整理,再结合workbuddy的obsidian相关技能,对书籍的分类,去重,以及obsidian的wiki风格整理,改善了书籍资料的存储分布,也去掉没有必要的分类方式,使得书籍更有效的存放在 Mac Studio 本地. 这些书籍上按《中国图书馆分类法》（CLC）组织。书库经历了多次迁移和脚本处理，积累了不少历史债,书籍分类不科学：

从混乱到秩序：用 AI Agent 重整万册电子书库的 Obsidian 知识库实践

本文记录了使用 WorkBuddy（AI Agent）对一个包含 2,165 本电子书的 Obsidian Vault 进行全面诊断、重构和治理的真实操作过程。从发现 2,085 个孤儿笔记到最终 1:1 精准匹配，全程脚本化、可复现。

人工智能

开发工具

职业发展

本文详细记录了如何利用Obsidian和Python脚本高效整理杂乱电子书库的完整过程。通过Dataview插件动态管理、1:1匹配PDF与笔记、自动化数据清洗等技巧，将65GB的2165本电子书从混乱无序转变为分类清晰、链接精准的知识库。重点解决了静态表格维护难、断链多、笔记与导航脱节等痛点，大幅提升了电子书管理效率。

数据清洗

代码解释

WorkBuddy 

容器

Python

JSON

2026上云采购 | AI焕新·智启新局

workbuddy

lexiang

腾讯云BI特惠9.9元起！


文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

本文详细记录了如何利用Obsidian和Python脚本高效整理杂乱电子书库的完整过程。通过Dataview插件动态管理、1:1匹配PDF与笔记、自动化数据清洗等技巧，将65GB的2165本电子书从混乱无序转变为分类清晰、链接精准的知识库。重点解决了静态表格维护难、断链多、笔记与导航脱节等痛点，大幅提升了电子书管理效率...

从混乱到秩序：用 AI Agent 重整万册电子书库的 Obsidian 知识库实践-腾讯云开发者社区-腾讯云

从混乱到秩序：用 AI Agent 重整万册电子书库的 Obsidian 知识库实践

从混乱到秩序：用 AI Agent 重整万册电子书库的 Obsidian 知识库实践

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐