HTPD

将长篇 PDF 转换为 AI 能正确读取的文档——文本准确，每个答案都标明页码。

简单来说  ·  看看它如何工作  ·  安装  ·  与你的 AI 一起使用  ·  面向开发者  ·  质量  

通俗来说

你有一份很长的 PDF——300 页的数据手册、5000 页的参考手册、一份政策文件或报告——以及一个关于它的问题。如果把整份 PDF 都交给 AI，它通常回答得很慢、会漏掉细节、混淆表格，也无法说明答案的出处。

**HTPD 为 AI 准备文档。**转换器会将 PDF 转换为一个 .htpd 文件：保留原文，一字不差，并按文档自身的章节和小节切分；标注每个段落所在的页码；将表格按行保存，并将插图保存为图片。随后，AI 只需读取回答问题所需的少数几个小节，就能根据原文作答，并提供页码，方便你核查。

在浏览器中试用：HTPD Studio。

看看它如何工作

以下是针对一份公开的 109 页数据手册（NXP i.MX 93）的实际命令及其输出，较长内容已缩短。

1. 转换一次 PDF——100 页约需一秒：

2. 用自己的话提问——获取文档中的原文，并附上页码和章节：

3. 插图保留为图片——能识别图像的 AI 可以直接查看示意图：

日常使用时，你无需输入这些命令：把 .htpd 文件交给 AI 即可，也可以让插件、技能或 MCP 服务代为处理。

一分钟内完成安装

转换器和读取器都在你的电脑上运行。传给 AI 的只有你提供给它的文本。

与你的 AI 搭配使用

/plugin marketplace add narendrachampaneri/htpd
/plugin install htpd@htpd

pip install htpd-reader                                   # htpd-read and htpd-mcp, nothing else needed
claude mcp add htpd -- htpd-mcp --bundles ~/manuals       # Claude Code

面向开发者

工作原理

flowchart LR
    PDF["📄 PDF<br/>scanned or digital"] -->|htpd convert| H["HTPD<br/>sections · pages · tables · figures"]
    H -->|upload| CHAT["AI chat<br/>(file + reading rules)"]
    H -->|skill · plugin · MCP| AGENT["AI agent<br/>(Claude, Antigravity, Codex)"]
    CHAT --> ANS["Answer from the exact text<br/>with page numbers"]
    AGENT --> ANS

下载（无需构建），请前往发布页面：

tar xzf htpd-0.1.2-linux-x64.tar.gz
cd htpd-0.1.2-linux-x64
./htpd convert manual.pdf --single           # writes manual.htpd
sudo apt install tesseract-ocr               # optional: read scanned pages too

从源代码构建——Linux（Ubuntu 24.04，也支持 WSL）、g++ 13+、make 或 CMake、Python 3.10+：

git clone https://github.com/narendrachampaneri/htpd.git && cd htpd
./scripts/get_pdfium.sh        # the PDF engine, once (about 4 MB)
make                           # builds build/htpd
make test                      # the C++ tests

转换并提问：

./build/htpd convert manual.pdf --single     # one file: manual.htpd  (for AI chats)
./build/htpd convert manual.pdf              # a folder: manual.htpd/ (for tools and agents)

pip install htpd-reader                      # or: python3 -m pip install -e .
htpd-read ask examples/single-file/sample.htpd "What is the maximum bus voltage?"

[page 2, 2.1.1 Limits]
  Parameter | Min | Typ | Max | Unit
  Bus voltage | 200 | 400 | 480 | V

每行答案都从文件中逐字复制；--context 会为 AI 添加完整章节。更多命令：contents、section、 search、figure、check——详见 reader/README.md。

格式

HTPD 文档是纯 UTF-8 文本：采用 Markdown 格式，并包含少量字段。任何模型、 编辑器或 grep 都能读取。

## [S14] 4.1.5 Maximum frequency of main modules

Path: 4 Electrical characteristics > 4.1 Chip-level conditions > 4.1.5 Maximum frequency of main modules - page 18



```text
Cortex®-A55 cores | 0.9 GHz | 1.4 GHz | 1.7 GHz
DRAM | 933 MHz | 1400 MHz | 1866 MHz
NPU | 500 MHz | 800 MHz | 1000 MHz
```

• 章节遵循文档自身的标题并构成树形结构：父级、子级、上一章、下一章。
• 页码标记 `` 位于每一页文本的上方。
• 表格以 | 分隔各单元格；代码和清单保留其间距。
• 图示为 PNG 图片，附带标题和页码，并存储在文件内。
• **两种形式，内容相同：**单个 .htpd 文件（用于聊天）和每个章节一个文件的文件夹（用于工具）；后者也是有效的 Open Knowledge Format 数据包。

完整规范见 docs/FORMAT.md。 示例：examples/single-file/sample.htpd 和 examples/sample.htpd/。

质量

速度和体积——单个文件，启用图示和 OCR，在 2 核云机器上：

包含图示的文件中，大部分内容是位于文件末尾的图片；文本在前。--figures off 会将图片排除。

查找答案——针对两本公开手册的 133 个测试问题（eval/report.md，由评估工具编写）：

交给 AI 的文本约占整个文档的 6%；对于手册中没有答案的 95% 问题，reader 都能正确指出“此文件中没有”。

适用于多种 PDF——45 份包含已知文本的 PDF，由 Word、LaTeX、Chrome、wkhtmltopdf 和幻灯片软件生成，也包括扫描件和将字母绘制为形状的文件 （tests/zoo）： 99% 的文本顺序正确，96% 的标题正确，89% 的表格行完全准确。

健壮性——对 34 份难处理的 PDF 进行压力测试（双栏、横向表格、旋转页面、1500 页、加密、截断和损坏文件）：没有崩溃或卡住，所有文件均有效，没有丢失任何单词。每次变更都会运行 102 个 C++ 测试和 155 个 Python 测试。

项目结构

include/ src/ cli/      the converter (C++23, PDFium is used in one file only)
reader/htpd_reader/     the reader: bundle, check, search, retriever, re-ranker, packer, answer, MCP server
skills/htpd/            the skill for AI apps (scripts/build_skill.py packs it)
skills/convert/         the plugin's skill that converts PDFs
.claude-plugin/         the Claude Code plugin and its marketplace (this repository is both)
eval/                   evaluation harness, baselines, report
model/                  the training of the re-ranker
tests/                  C++ tests, test PDFs, the stress test, the document zoo
docs/                   FORMAT.md · CONVERTER.md · READER.md · AI-APPS.md · BACKGROUND.md
examples/               a converted document in both forms

参与贡献

欢迎提交问题和拉取请求。修改任何内容之前，请先阅读 AGENTS.md；简要规则如下：

• 合并变更前，所有测试都必须通过：make test 和 python3 -m pytest。
• 代码中的每条新规则都必须配有测试，且没有该规则时测试应失败。
• 绝不丢失文本，也绝不编造文本。
• 对写入 HTPD 文件的内容所做的变更，必须在同一提交中更新 docs/FORMAT.md。

许可证

HTPD 采用 Apache License 2.0 开源：只要保留版权和许可证声明（NOTICE），并标明你做出的修改，即可使用、修改和分享，也可用于商业产品。 许可证还包含每位贡献者授予的专利许可。

转换器使用的 PDFium 不属于此仓库，并采用其自己的许可证（BSD 风格，含有 Apache-2.0 部分）；运行 scripts/get_pdfium.sh 后，其许可证文本位于 third_party/pdfium/licenses/。如果你将程序与 libpdfium.so 一起提供给他人，也必须将这些文件一并提供。