# pdf-bookmark

**Repository Path**: bitpg/pdf-bookmark

## Basic Information

- **Project Name**: pdf-bookmark
- **Description**: 这是一个给pdf文件加书签的skill
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-08-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PDF Bookmark

自动从 PDF 内容中提取标题层级，生成可点击跳转的书签。点击书签后，目标标题会显示在 PDF 窗口的第 2 行。

## 功能

- 支持多层级标题，L1 之后采用通用编号检测（默认支持 L1 ~ L6，可调高），自动识别 `第X章/讲`、`X. xxx`、`X.X xxx`、`X.X.X xxx`、`X.X.X.X xxx` 等编号模式
- 支持 `加餐-xxx` 格式的特殊标题
- 通过字体大小 + 父编号匹配区分真标题和正文中的编号条目
- 如果没有找到 L1 标题，自动用首页最大字体的文字创建根书签
- 书签目标位置自动上移，点击后标题显示在窗口第 2 行

## 安装

以下两种方式任选其一。

### 方式一：手动安装

1. 将 `pdf-bookmark` 文件夹放到 skills 目录下，确保 `SKILL.md` 位于该文件夹根目录：
   - Windows：`C:\Users\<用户名>\.config\opencode\skills\pdf-bookmark`
   - macOS/Linux：`~/.config/opencode/skills/pdf-bookmark`

   有仓库时也可直接克隆：

   ```bash
   git clone https://gitee.com/bitpg/pdf-bookmark <skills目录>/pdf-bookmark
   ```

2. 安装 Python 依赖：

   ```bash
   pip install pymupdf
   ```

### 方式二：提示词让 AI 自动安装

将下面这段提示词发给任意 AI 助手，它会自己拉取仓库并安装到正确位置：

```text
请帮我安装 pdf-bookmark 这个 OpenCode skill：

1. 将仓库 https://gitee.com/bitpg/pdf-bookmark 克隆到 skills 目录
   - Windows: 克隆到 C:\Users\<用户名>\.config\opencode\skills\pdf-bookmark
   - macOS/Linux: 克隆到 ~/.config/opencode/skills/pdf-bookmark
2. 确认 SKILL.md 位于该文件夹根目录
3. 安装 Python 依赖：pip install pymupdf
4. 完成后告诉我"安装成功"
```

> 提示：把 `<用户名>` 换成你实际的值。若无法克隆，请改用"方式一"手动复制。

## 图形界面版（exe，适合非技术用户）

除了命令行工具外，还提供图形界面版，无需安装 Python、无需使用智能体，双击即可用：

- 使用方式：打开窗口 → 选择 PDF 文件或整个文件夹 → 点「开始生成」→ 完成
- 成品程序 `dist\PDF书签生成工具.exe`（单文件，约 30MB，双击运行）
- 通过构建脚本 `build_exe.ps1` 重新打包（依赖 PyInstaller + pymupdf）
- 入口源码：`pdf_bookmark_gui.py`，处理逻辑复用 `generate_bookmarks.py`

## 在 OpenCode 中使用

安装完成后，在 OpenCode 对话中输入以下任一方式即可自动触发：

- "帮我给这个 PDF 加上书签"
- "给当前文件夹中的 PDF 文件加上书签"
- "帮我生成 PDF 书签"

OpenCode 会自动加载该 skill，检测 Python 环境、安装依赖并运行脚本。

## 手动运行

也可以直接运行脚本：

```bash
python generate_bookmarks.py <PDF目录路径>
```

脚本会自动扫描目录下所有 `.pdf` 文件，提取标题并设置书签。

## 自定义偏移量

如果希望调整点击后标题在窗口中的位置，修改 `generate_bookmarks.py` 顶部的 `OFFSET_Y` 变量（默认 14 点）。

## 标题检测规则

| 层级 | 编号模式 | 字体阈值 | 示例 |
|------|---------|---------|------|
| L1 | `第\d+[讲章]` / `\d+. ` / `加餐-` | ≥ 20pt | `第1讲：初识C语言`、`6. Vibe Coding的好与坏` |
| L1(无编号) | 不以数字/第/加开头 | ≥ 18pt | `版权声明`、`代码与板书链接` |
| L2 | `\d+. ` 开头 | ≥ 13.5pt | `1. C语言是什么？` |
| L3 | `\d+.\d+ ` 开头且父编号匹配 L2 | ≥ 13pt | `2.1 历史` |
| L4 | `\d+.\d+.\d+ ` 开头且父编号匹配 L3 | ≥ 12pt | `2.2.1 字符串和字符数组` |
| L5 | `\d+.\d+.\d+.\d+ ` 开头且父编号匹配 L4 | ≥ 11.5pt | `2.2.1.1 小节标题` |
| L6+ | `\d+(.\d+){4,}` 开头且父编号匹配上一级 | ≥ 11pt | `2.2.1.1.1 更深层标题` |

> L3 起逐级要求"父编号匹配当前上级编号"；超过默认层级的标题会继续递归识别，直到不再出现更深的编号层级或达到 `MAX_LEVEL` 上限。

> **跳级编号（方案B）**：若父编号缺失（如 `3. 数据检索` 后直接出现 `3.1.1 用户查询`，没有 `3.1`），会自动就近归入已存在的最近祖先之下（该例归为 `3. 数据检索` 的 L3 子书签）。

> **无编号标题字号分层（方案C）**：对"纯字号分层、无编号"的 PDF（如 `Git 原理与使用`），先做编号检测，编号标题 ≥ `MIN_NUMBERED_HEADINGS`(默认3) 时不启用该功能；否则按字号档位把无编号大字映射为 L2~L6（如 16.5pt→L2、15pt→L3、13.5pt→L4）。`◦`/`•` 开头的列表项与句末标点结尾的句子不会被当作标题。

> **水印过滤**：同一行文本出现在 ≥30% 页面上（且至少 3 页）时视为水印/页眉页脚/页码，不会作为书签（如整页重复的 `比特就业课` 水印）。比例和最少页数由脚本顶部的 `REPEAT_RATIO`、`REPEAT_MIN_PAGES` 控制。

## 调整最大层级与字体阈值

脚本顶部定义了相关常量，可按需修改：

- `MAX_LEVEL`：最大书签层级，默认 6，可调高（如 8、10）。PDF 书签树本身不限制深度，超出该值的更深编号将被忽略。
- `LEVEL_THRESHOLDS`：各层级的字体阈值字典；未在字典中的更深层级统一使用 `DEFAULT_THRESHOLD`（默认 11pt）兜底。
- `MIN_NUMBERED_HEADINGS`：编号风格判定阈值（默认 3），编号标题达到该数量即不启用无编号字号分层。
- `REPEAT_RATIO` / `REPEAT_MIN_PAGES`：重复文本过滤（水印/页眉页脚）比例与最少页数。
- `OFFSET_Y`：书签目标上移点数，默认 14。