ai-pdf-toc-bookmarker

这是什么

帮你生成电子书的目录书签。

通过多模态AI调用工具实现。

常用于解决Z-Library/Anna's Archive 下载的没有目录书签的电子书。

配合智能体软件使用，如OpenClaw类似的。

经测试，在腾讯的WorkBuddy，qclaw和字节的Trae上也可以跑通。

文件结构

 ai-pdf-toc-bookmarker/
 ├── SKILL.md                    # 给 AI 智能体的执行说明（核心）
 ├── images/                     # 示例图
 │   ├── example_1.jpg
 │   ├── example_2.jpg
 │   ├── output_1.jpg
 │   └── output_2.jpg
 ├── requirements.txt            # Python 依赖
 ├── README.md                   # 本文件
 └── scripts/                    # AI需要用到的工具文件夹
     ├── render_toc_pages.py     # 渲染目录页为高清 PNG
     └── write_bookmarks.py      # 读取目录 JSON，写入 PDF 书签

AI模型选择

1. 必须支持视觉模态。 一些 PDF 没有文字层，目录靠 AI「看」图片识别。如果你的智能体后端是纯文本模型，流程会卡在识别那一步。
2. 必须支持工具调用。 本技能通过 python scripts/xxx.py --参数 ... 运行，依赖智能体具备执行命令行的能力。

视觉模型举例

支持的模型	不支持的模型
GLM-5v-Turbo	GLM5.2
Kimi k2.6	Deepseek v4系列
Minimax M3	HY-3
qwen3.7plus	qwen3.7max

快速开始

1. 把 skill 装进你的智能体 部分平台支持拖动文件夹或者zip文件来安装skill，具体看平台。

2. 装依赖 在智能体的工作环境里安装一次即可：

pip install -r requirements.txt

一个很小的库(pymupdf)，用于渲染PDF和往PDF里打书签。一般来说，第一次如果没装直接用，智能体通常会问你要不要安装，只需要点击同意安装即可。

3. 打开 PDF 阅读器，找到三个参数 用阅读器或者浏览器（如Edge / Chrome / Firefox）打开PDF电子书，看上方工具栏显示的页码（电子页码，从 1 开始），记下这三个参数：

参数	是什么
目录起始页	目录第一页的电子页码
目录结束页	目录最后一页的电子页码
偏移量	跳到任意一页「有正文、又印着页码」的地方，用「该页电子页码 − 该页印刷页码」算出差值

4. 告诉智能体书本在哪 + 填入三个参数

• 书本位置：在提示词里给出 PDF 完整路径，或直接把文件导入智能体工作空间。

• 三个参数：用下面两种方法之一告诉智能体即可（自然语言，没有强制语法）：

  • 方法 A（带说明）：目录 15-23，偏移量 11
  • 方法 B（纯数字，从左往右依次是 起始 / 结束 / 偏移量）：15, 23, 11

示例1

示例2

最终效果1

最终效果2

---

常见错误

代码里写的是 import fitz，但 fitz 是 PyMuPDF 库的一部分，请用 pip install pymupdf（或 pip install -r requirements.txt）安装，别去找一个叫 fitz 的包。没装就跑脚本时，脚本会打印友好提示并退出，不会崩溃。

---

许可证

MIT