Agent Document Skills

🇺🇸 English · 🇨🇳 简体中文

把 PDF 变成干净的 Markdown，再把长文稳定翻译成中文。

一组用于 PDF OCR 与长文档翻译的可移植 Agent Skills。
默认使用宿主 Agent，也可通过三种通用大模型 API 协议自动处理。

---

包含内容 · 工作流程 · 快速开始 · 运行模式 · 依赖 · 兼容平台

包含内容

Skill	功能
pdf-ocr	使用 MinerU 完成 PDF OCR、图片提取、确定性质量检查和可选的大模型复核。
md-translate	基于术语表、支持分块与断点续传的 Markdown 简体中文翻译。

两个 Skill 既可以独立使用，也可以组成完整流水线。翻译和大模型复核默认直接使用当前宿主 Agent；如需无人值守自动处理，也可以使用 OpenAI Chat Completions、OpenAI Responses 或 Anthropic Messages 协议，不需要维护厂商专属模型列表。

工作流程

flowchart LR
    PDF["PDF"] --> OCR["pdf-ocr"]
    OCR --> MINERU["MinerU API"]
    MINERU --> MD["Markdown + 图片 + 质量检查"]
    MD --> TRANS["md-translate"]
    TRANS --> HOST["宿主 Agent（默认）"]
    TRANS --> API["可选外部 LLM API"]
    HOST --> ZH["可续传的中文 Markdown"]
    API --> ZH

Loading

快速开始

使用标准 Agent Skills CLI 安装两个 Skill：

npx skills add SuperJJ007/agent-document-skills

无交互地全局安装到指定 Agent：

npx skills add SuperJJ007/agent-document-skills \
  --skill '*' -g -y \
  -a codex -a claude-code -a cursor -a opencode -a openclaw -a hermes-agent

安装完成后重新启动 Agent 会话，然后直接用自然语言提出请求：

用 MinerU 把这个 PDF 转成干净的 Markdown。
把这份 OCR Markdown 翻译成简体中文。
先 OCR 这个 PDF，检查输出质量，然后翻译。

运行模式

host 是默认的大模型运行模式。当前 Codex、Claude Code、Cursor 或其他宿主 Agent 会直接翻译准备好的分块，不需要额外配置大模型 API Key。脚本负责保存分块元数据、跳过已完成内容并合并最终文档。

如需通过外部 API 自动处理，可选择一种协议：

LLM_PROTOCOL	HTTP API 协议
openai-chat	OpenAI Chat Completions
openai-responses	OpenAI Responses
anthropic-messages	Anthropic Messages

export LLM_PROTOCOL="openai-responses"
export LLM_API_KEY="..."
export LLM_MODEL="provider-model-name"
export LLM_BASE_URL="https://provider.example/v1" # 官方端点可省略

这里刻意只提供协议适配，而不维护大模型服务商目录。模型名称、可用性、价格及兼容程度由端点运营方决定。其他可选配置包括 LLM_MAX_OUTPUT_TOKENS、LLM_TIMEOUT_SECONDS、OCR_LLM_MODEL 和 ANTHROPIC_VERSION。

依赖

安装 Skill 本身不会静默修改 Python 环境。只有实际运行需要依赖的脚本时，才解析相应依赖。

工作流	运行要求
md-translate host 模式	Python 3.9+；仅使用标准库
md-translate 外部 API	Python 3.9+、httpx
pdf-ocr MinerU 云端模式	Python 3.9+、requests、pypdf
OCR 的 host 复核	无额外 Python 包
OCR 的外部 LLM 复核	Python 3.9+、httpx
MinerU 本地模式	用户单独安装的 mineru 命令及其模型

Python 入口脚本带有 PEP 723 元数据。使用 uv 执行时，uv run 会自动创建隔离环境，只下载当前脚本声明的包，并在后续运行中复用缓存：

cd skills/pdf-ocr
uv run scripts/ocr.py --input <pdf> --output <directory>

Host 翻译模式不需要 uv，也不需要第三方 Python 包：

cd skills/md-translate
python3 scripts/translate.py --input <source.md> --prompt <prompt.md>

外部 API 翻译会通过内联声明自动解析 httpx：

uv run scripts/translate.py --input <source.md> --prompt <prompt.md> \
  --protocol openai-responses

如果没有 uv，每个 Skill 都提供备用 requirements.txt。可以只安装准备使用的 Skill 依赖，也可以安装仓库汇总依赖：

python3 -m pip install -r skills/pdf-ocr/requirements.txt
python3 -m pip install -r skills/md-translate/requirements.txt
# 或：python3 -m pip install -r requirements.txt

MinerU OCR

使用云端 OCR 时需要配置 MinerU API Token：

export MINERU_API_TOKEN="..."

pdf-ocr Skill 会把用户选定的 PDF 页面上传至 MinerU，并生成 full.md、提取出的图片和质量检查报告。如果系统已经安装了可用的 mineru 命令，也可以选择本地 MinerU 后端。

MinerU 云端请求默认使用直连 HTTP 会话，不读取代理环境变量。翻译管线可识别 1–6 级 References 标题，保留原有标题层级，并让所有参考文献条目保持原始语言。

兼容平台

本仓库使用可移植的 SKILL.md 目录，并为支持 Plugin 的平台提供轻量 manifest。

Agent 平台	安装方式
Codex	Plugin manifest 或复制 Skill 目录
Claude Code	Plugin manifest 或复制 Skill 目录
Cursor	复制 Skill 目录
OpenCode	复制 Skill 目录
OpenClaw	复制 Skill 目录
Hermes	复制 Skill 目录
兼容 Agent Skills 的工具	~/.agents/skills

数据与凭据

• 使用云端 OCR 时，选定的 PDF 页面会上传至 MinerU。
• Host 翻译模式不需要单独的大模型 API 凭据。
• 外部 LLM 模式会把选定的 Markdown 分块发送至配置的端点。
• 凭据只从运行环境读取，不会打包进项目。
• 不要把 API Key 粘贴到 Agent 对话中，也不要提交到代码仓库。

处理敏感材料前，请查看相关服务商当前的隐私、数据保留、额度和价格条款。

验证

诊断脚本不会调用网络，也不会打印凭据内容：

python3 scripts/doctor.py
python3 tests/test_offline.py

许可证

MIT