autoContents

autoContents

当前版本：v1.1.0

autoContents 是一款专为扫描版 PDF 设计的书签全自动生成工具，能够基于目录页内容创建可跳转书签。上传 PDF 文档后无需进行任何其他操作，等待 1 分钟左右即可获取处理结果。

贡献者致谢

本项目的可用性离不开社区的反馈与代码贡献，感谢以下参与者：

• Daxoel (@4965898) —— 贡献 v1.1.0 的核心功能：任意 OpenAI 兼容 LLM 服务商支持、罗马数字页码识别与前言偏移计算、拖拽上传 PDF、PDF 完整性预检、启动脚本兼容性修复。他另在 issue #16 中提出了「支持其他 MaaS 平台」的需求，直接促成了这项改进。
• @Little-White3110 —— 就导出文件命名规则与自定义导出文件名提出改进建议（#12、#14），并贡献了 3月29日版本的文件重命名功能。

欢迎通过 Issue 反馈问题、通过 Pull Request 贡献代码，贡献内容同样适用本项目许可协议。

下载使用

前往 Releases 下载对应系统的压缩包，解压后双击 启动 autoContents.command（macOS）或 启动 autoContents.bat（Windows）即可，无需安装 Python 或任何依赖。首次使用需在页面中填入自己的 LLM API Key。

若需自行配置环境运行源码，请参考下文「配置环境」章节。

v1.1.0 更新内容

本版本更新内容如下（贡献者见上方致谢）：

• 支持任意 OpenAI 兼容的 LLM 服务商（通义千问、书生·浦语、OpenAI、DeepSeek 等），不再局限于通义千问
• 所有硬编码模型名改为变量/配置读取，可通过 .env 文件或网页 UI 随时切换模型
• 修复了 Windows 下 windows_start.bat 在 PowerShell 中的兼容性问题
• 前端错误信息增强：子进程的 stderr 会直接显示在页面上，便于排查问题
• 增加 PDF 文件完整性预检（页数为 0 时提前报错）
• 支持罗马数字页码（v1.1.0）：自动识别前言/序言的罗马数字页码（如 xv、xviii），计算前言偏移量，排序时副文本正确置于正文之前
• 支持拖拽上传 PDF（v1.1.0）：可直接将 PDF 文件拖入网页，无需点击按钮选择

更新日志

v1.1.0

• 新增罗马数字页码支持：roman_to_int() 转换函数，前言偏移自动计算（calculate_roman_offset），并发采样前言页面
• 修复前言目录排序：罗马数字条目（Foreword、Preface 等）正确排在正文章节之前
• 新增拖拽上传：PDF 文件可直接拖入网页，带蓝色高亮反馈
• 前端错误信息增强：显示子进程 stderr，便于排查

v1.0.0

• 支持任意 OpenAI 兼容 LLM 服务商
• 硬编码模型名改为变量/配置读取（三层配置体系）
• 修复 Windows PowerShell 启动兼容性
• PDF 文件完整性预检

如果想先看看该工具的实际表现情况，请点击这里。

适用文档

适用于全部自带目录页面的中英文文档。

Step 1 下载程序

请点击页面顶部的绿色按钮Code，然后点击Download ZIP以下载程序源码。

Step 2 配置环境

2.1 配置 LLM 服务

本工具需要使用支持视觉/多模态的 LLM 模型来识别 PDF 目录页图片。你可以选择任意 OpenAI 兼容的 LLM 服务商。

方式一：通义千问（阿里云百炼）

1. 注册账号：如果没有阿里云账号，请先注册一个。
2. 实名认证：参考实名认证文档对阿里云账号进行实名认证。
3. 获取 API Key：前往百炼控制台（API-KEY管理）然后创建一个 API-KEY。
4. 如果你有高校学生或教师身份，可前往阿里云高校计划申请一些优惠。具体政策以该网页为准。

方式二：书生·浦语（InternAI）

1. 前往 InternAI 注册并登录。
2. 在个人中心获取 API Key。
3. 可选模型：intern-latest、internvl-latest 等（详见 模型列表）。

方式三：其他 OpenAI 兼容服务商

任意提供 OpenAI 兼容 API 的服务商均可使用，只需提供：

• API Key
• Base URL（服务端点）
• 模型名称（须支持视觉/多模态）

2.2 配置运行环境

Windows

1. 点击这里下载Python安装程序。下载完成后双击打开，然后按照下图依次操作：勾选Add python.exe to PATH -> 点击Install Now -> 安装完成后，点击Close。

2. 双击根目录下的windows_install.bat，直到运行完成（Setup complete.）。

macOS

1. 点击这里下载Python安装程序。下载完成后直接安装即可。
2. 打开"终端"APP，依次输入chmod +x （注意最后面有空格），然后将macos_install.command文件拖入终端窗口，按return。
3. 同样的方法，对macos_start.command执行一次chmod +x （若双击启动无反应，说明该文件缺少执行权限）。

2.3 配置 LLM 凭证（.env 文件）

将 .env.example 复制为 .env，并填写你的 LLM 服务信息：

OPENAI_API_KEY=你的API密钥
OPENAI_BASE_URL=你的服务端点
OPENAI_MODEL=模型名称

也可以跳过此步，直接在启动后的网页 UI 中填写配置（见 Step 3.1）。

Step 3 使用方法

3.1 运行程序

1. 双击根目录下的windows_start.bat或macos_start.command来启动程序，浏览器界面会自动打开。
2. 如果浏览器未打开，请在弹出的命令行窗口中找到http://127.0.0.1:5xxx，并复制到浏览器以打开。
3. 在网页的「LLM 配置管理」中填写 API 密钥、Base URL、模型名称，然后点击保存 LLM 配置。可点击「测试 LLM 服务」验证配置是否正常。

配置优先级：网页 UI 实时配置 > static/llm_config.json 配置文件 > .env 环境变量

3.2 上传 PDF 并处理

1. 点击"选择PDF文件"，然后选择需要处理的 PDF 文件。
2. 点击"开始执行"，等待进度条走完，浏览器会自动下载带有书签的 PDF 文件。
3. 关于结果：
   1. 如果效果不错，请前往页面右上方，为这个项目增加一个Star，谢谢！
   2. 如果目录层级有误，请参见下方的编辑书签条目，或者使用自己的PDF编辑器进行相关操作。
   3. 如果运行出现问题，请参见下方的疑难解答以进行问题排查。

编辑书签

该项目提供简易的书签编辑工具，可使用contents_editor中的脚本对 PDF 文件的书签进行编辑，使用方法如下：

1. 将需要编辑的 PDF 文件放入contents_editor文件夹中；
2. 运行windows_extract.bat或macos_extract.command脚本，进行目录提取；
3. 使用Microsoft Excel，VScode或其他任何可编辑csv文件的软件编辑生成的csv文件：如果需要添加条目，那么插入一行；如果需要删除条目，那么删除对应行；如果只需要修改条目，那么修改对应行；
4. 保存并关闭csv文件，然后再运行windows_merge.bat或macos_merge.command脚本，将修改后的目录与 PDF 文件合并；
5. 该目录下的*_edited.pdf文件即为处理后的 PDF 文件。

疑难解答

• ModuleNotFoundError: No module named 'fitz'：虚拟环境中缺少 PyMuPDF 依赖，请运行 pip install -r requirements.txt 重新安装。
• PDF 文件无法解析出任何页面（页数为 0）：PDF 文件可能已损坏（trailer 缺失），请重新获取完好的 PDF 文件。
• LLM 服务测试失败：请检查 API Key、Base URL 和模型名称是否正确，以及模型是否支持视觉/多模态输入。
• 执行失败但看不到具体错误：错误信息会显示在任务日志中，请向上滚动查看 stderr 输出的详细报错。

MCP 服务器（可选，供 AI Agent 调用）

autoContents 也可作为 MCP（Model Context Protocol）服务器运行，让 AI 编程助手（如 Cherry Studio、Claude Desktop）直接调用书签生成能力。

安装 uv

uv 是 Python 的快速包管理器，也是 MCP 服务器的运行环境。

Windows

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

配置 MCP 客户端

将以下 JSON 添加到你的 MCP 客户端配置文件中（路径按实际情况修改）：

{
  "mcpServers": {
    "autoContents": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/autoContents",
        "python",
        "/path/to/autoContents/mcp_server.py"
      ],
      "env": {
        "AUTOCONTENTS_API_KEY": "sk-xxx",
        "AUTOCONTENTS_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "AUTOCONTENTS_MODEL": "qwen3.7-plus"
      }
    }
  }
}

字段	说明
command	固定为 uv，需先完成上一步的安装
args 中的路径	将 /path/to/autoContents 替换为项目实际路径
AUTOCONTENTS_API_KEY	必填，替换为你的百炼 API Key
AUTOCONTENTS_BASE_URL	可选，默认为百炼兼容接口
AUTOCONTENTS_MODEL	可选，默认为 qwen3.5-397b-a17b

配置完成后重启客户端，即可使用 generate_pdf_bookmarks 和 check_llm_config 两个工具。

更新日志

更新提醒：最新版本是v1.1.0，你可以根据获取更新来更新程序。

10月13日的版本对识别逻辑进行了完全重构，可实现任意版面结构的目录数据提取，同时处理速度提升50%，且进一步简化了配置流程；12月2日的版本支持直接在前端进行提示词修改；3月25日发布的版本支持自定义LLM服务；3月29日发布的版本增加了使用LLM对下载文件进行重命名的功能，特别鸣谢@Little-White3110提出的建议；4月4日发布的版本实现的全自动目录提取。4月6日的版本对项目结构再次进行大量重构，解决了很多细节问题。7月26日的版本增加了uv和MCP支持。

v1.1.0 支持任意 OpenAI 兼容的LLM服务商（通义千问、书生·浦语、OpenAI、DeepSeek 等，不再局限于通义千问）、罗马数字页码（前言/序言页码正确排在正文之前）、拖拽上传PDF，以及损坏文件的预检提示。特别鸣谢 @4965898 提交的 PR 思路。

获取更新

1. 点击页面顶部的绿色按钮Code，然后点击Download ZIP以下载程序源码；
2. 将下载的autoContents-main文件夹中的全部内容覆盖到本地autoContents-main文件夹中；
3. 重新运行2.2的安装步骤以更新依赖。

macOS 用户注意：从 GitHub 下载的 ZIP 会丢失 Unix 可执行权限，覆盖后 .command 文件将无法双击运行。请在终端执行一次 chmod +x *.command contents_editor/*.command 后再启动。

许可与贡献

本项目采用专有许可协议（source-available，非开源许可）：个人学习、研究与非商业用途可自由使用与修改；商业使用需另行获得作者书面授权。

欢迎通过 Issue 反馈问题、通过 Pull Request 贡献改进。贡献的代码同样适用本协议条款。

Star History