pdf-ai-explorer 0.1.1

PDF-AI Explorer - AI-oriented PDF document reading tool

PDF-AI Explorer

面向 AI 的 PDF 文档阅读工具，将 PDF 视为带索引的拓扑图，帮助 AI 高效导航和理解长文档。

为什么需要这个工具？

当 AI 阅读长 PDF 文档（如年报、合同、技术手册）时，面临几个挑战：

• 迷失位置 - 不知道当前内容在文档中的位置
• 缺乏上下文 - 看不到相邻章节和层级关系
• 难以定位 - 无法快速跳转到相关内容
• 表格断裂 - 跨页表格被拆分，难以理解完整数据

PDF-AI Explorer 通过将 PDF 转换为带索引的拓扑图来解决这些问题：

AI: "我在看第 196 页的表格，这是什么章节？"
→ inspect_node(2000) 
→ 路径: 根 > 财务报告 > 合并报表项目注释 > 长期股权投资
   兄弟: 对子公司投资、对联营企业投资、...
   
AI: "文档里哪里提到了营业收入？"
→ search_nodes("营业收入")
→ 15 个结果，包含 ID、类型、页码、预览

AI: "这个表格跨了 3 页，怎么看完整数据？"
→ get_content(52)  # 完整合并表格
→ get_content("52:p9")  # 只看第 9 页部分

核心特性

• 拓扑感知 - 祖先路径、兄弟节点、子节点导航
• 物理感知 - 页码定位、页面层级骨架
• 语义感知 - 正则/模糊搜索、HTML 表格
• 引用感知 - ^id 锚点标记
• 跨页表格 - 自动拆分为分页虚拟节点 (52:p9)

安装

uv sync

快速开始

Python SDK

from pdf_ai_explorer import PDFAITool, PDFReader

# 文本接口（适合 AI）
tool = PDFAITool("document.json")
print(tool.get_outline(depth=2))
print(tool.inspect_node(id=1))
print(tool.search_nodes("关键词"))
print(tool.read_page(12))
print(tool.read_page("12-15"))  # 页码范围
print(tool.get_content(id=52))
print(tool.get_content(id="52:p9"))  # 跨页表格分页

# 结构化接口（适合程序）
reader = PDFReader("document.json")
node = reader.get_node(1)
for n in reader.iter_nodes(type_filter="table"):
    print(n.id, n.page_number)

CLI

uv run pdf-ai-explorer outline doc.json --depth 2
uv run pdf-ai-explorer inspect doc.json 1 --siblings 5
uv run pdf-ai-explorer search doc.json "关键词"
uv run pdf-ai-explorer read doc.json 12-15
uv run pdf-ai-explorer content doc.json 52

AI Agent Skill

生成 Claude Code skill 文件，让 AI agent 快速掌握 CLI 用法：

# 输出到 stdout
uv run pdf-ai-explorer skill

# 写入 Claude Code skills 目录（自动创建 SKILL.md）
uv run pdf-ai-explorer skill --output .claude/skills/pdf-ai-explorer

Python API：

from pdf_ai_explorer import generate_skill
content = generate_skill()  # 返回 skill markdown 文本

MCP Server

# 启动 MCP Server（stdio 模式，用于 IDE 集成）
uv run pdf-ai-explorer mcp

# 或指定传输协议
uv run pdf-ai-explorer mcp --transport sse

工具: get_outline, inspect_node, search_nodes, read_page, get_content

接口说明

接口	功能	主要参数
get_outline	文档大纲	id, depth
inspect_node	节点透视	id, sibling_count
search_nodes	搜索	query, mode
read_page	读取页面	page_num, end_page
get_content	节点内容	id

输出格式

段落文本 ^1234

<table id="52">
  <tr><th>项目</th><th>金额</th></tr>
  <tr><td>营业收入</td><td>20,594,892</td></tr>
</table>

[跨页表格第 9 页部分，完整表格 ID: 52，页码范围: 8-10]

项目结构

src/pdf_ai_explorer/
├── api.py          # PDFAITool, PDFReader
├── cli.py          # CLI 命令
├── skill.py        # Skill 生成
├── parser.py       # 文档加载
├── renderer.py     # 渲染输出
├── search.py       # 搜索逻辑
├── cache.py        # diskcache 缓存
├── config.py       # 配置管理
├── exceptions.py   # 异常类
├── models/         # 数据模型
├── templates/      # Skill 模板
└── mcp/server.py   # MCP Server

开发

make test   # 运行测试
make demo   # 运行演示
make help   # 查看帮助

配置

优先级：代码参数 > 环境变量 > 配置文件 > 默认值

环境变量

export MEMECT_API_URL="http://api.example.com/api"

配置文件

# ~/.config/pdf-ai-explorer/config.toml
api_url = "http://api.example.com/api"

MCP 配置示例

在 IDE 的 MCP 配置中（如 mcp.json）：

{
  "mcpServers": {
    "pdf-ai-explorer": {
      "command": "uvx",
      "args": ["--index", "http://192.168.41.95:8141/memect/dev/+simple/", "pdf-ai-explorer", "mcp"],
      "env": {
        "MEMECT_API_URL": "http://api.example.com/api"
      }
    }
  }
}

uvx 会自动从指定索引安装并运行，无需本地克隆项目。

缓存目录：~/.cache/pdf-ai-explorer/（基于文件 MD5）

License

MIT