| name | paper-summarize-pdf-to-feishu |
| version | 1.0.1 |
| author | yy-fan |
| license | MIT |
| homepage | https://github.com/openclaw/openclaw |
| description | 总结论文 PDF 为飞书文档（含图表）。当用户发送 PDF 文件并要求总结、阅读、提取内容，
或要求将 PDF 内容写入飞书文档时激活。支持学术论文、技术报告、一般 PDF 文档。
自动检测扫描版 PDF 并回退 OCR，支持提取并上传论文图片到飞书文档。
含多模型自审核机制：生成 → 配图 → 审核 → 人工确认 → 完善。
**支持去重系统**：自动识别重复 PDF、同文章不同版本、补充材料，智能合并处理。
触发场景：发送 PDF 附件、"总结这个 PDF"、"帮我读一下这个论文"、"把 PDF 写成飞书文档"、
"论文总结"、"PDF 摘要"、"阅读 PDF 并输出到飞书"。
|
| metadata | {"openclaw":{"requires":{"bins":["pdftotext","pdfinfo","pdfimages","pdftoppm","tesseract","jq"],"env":["OPENCLAW_WORKSPACE"],"config":["~/.openclaw/openclaw.json"]},"primaryEnv":"OPENCLAW_WORKSPACE"}} |
paper-summarize-pdf-to-feishu
将 PDF 文件完整阅读后生成结构化总结，写入飞书文档，并将论文 Figure 精确插入对应章节。
含多模型审核 + 配置确认 + 人工确认机制，确保最终输出质量。
前置依赖
系统工具
| 工具 | 用途 | 版本要求 |
|---|
pdftotext | PDF 文本提取 | poppler-utils ≥ 0.86 |
pdfinfo | PDF 元信息查看 | poppler-utils ≥ 0.86 |
pdfimages | PDF 图片提取 | poppler-utils ≥ 0.86 |
pdftoppm | PDF 转图片（截图/OCR） | poppler-utils ≥ 0.86 |
tesseract | OCR 识别 | ≥ 4.1 |
jq | JSON 处理 | ≥ 1.6 |
OpenClaw 插件
| 插件 | 用途 | 版本 |
|---|
feishu | 飞书文档操作 | 2026.3.13¹ |
feishu_doc | 文档读写/图片上传 | 内置 |
¹ OpenClaw 官方插件与主程序同步发布，版本号一致
检查依赖：
which pdftotext pdfinfo pdfimages pdftoppm tesseract jq || \
sudo apt-get install -y poppler-utils tesseract-ocr tesseract-ocr-eng tesseract-ocr-chi-sim jq
pdftotext -v
tesseract --version
jq --version
完整工作流程（六阶段）
阶段零：去重检查
目标：避免重复处理，智能识别补充材料并合并
0.1 提取元数据
scripts/extract_metadata.sh <input.pdf> "$TEMP_DIR/metadata.json"
提取内容：
- DOI（优先，用于唯一标识）
- 标题、作者、发表年份
- PDF 文件哈希（用于精确去重）
- 生成
paper_id：<DOI> 或 hash_<指纹>
0.2 检查是否已处理
scripts/check_duplicate.sh "$TEMP_DIR/metadata.json" "$PAPERS_DIR"
判断逻辑：
收到 PDF → 计算 paper_id → 查询 papers/ 目录
├─ 不存在 → 新论文，创建文件夹，进入阶段一
├─ 存在 + PDF 哈希相同 → 完全重复，跳过并告知用户
├─ 存在 + DOI 相同但哈希不同 → 同文章不同版本，询问是否更新
└─ 存在 + 判断为补充材料 → 合并到 supplements/，追加到飞书文档
0.3 补充材料识别规则
文件名包含以下关键词视为补充材料：
supplement, suppl, _si_, supporting, appendix
DOI 包含 .supp 或 supplementary 也视为补充材料。
0.4 文件夹结构
papers/
├── 10.xxxx-xxxxxx/ # DOI 作为 ID（优先）
│ ├── metadata.json # 元数据（DOI、标题、作者等）
│ ├── paper.pdf # 主文章
│ ├── paper.txt # 提取的全文文本
│ ├── feishu_doc_token.txt # 飞书文档 token
│ ├── summary.md # 总结文档
│ ├── versions.json # 版本历史（如有更新）
│ ├── images/ # 提取的 Figure/Table
│ └── supplements/ # 补充材料
│ ├── 20260326_120000_suppl1.pdf
│ ├── 20260326_120000_suppl1_meta.json
│ └── 20260326_120000_suppl1.txt
│
└── hash_xxxxxxxxxxxx/ # 无 DOI 时用指纹哈希
└── ...
阶段一：生成
1. 创建论文专属文件夹
PAPER_DIR=<OpenClaw 工作目录>/papers/<paper_id>
mkdir -p "$PAPER_DIR"/{images,supplements}
cp <input.pdf> "$PAPER_DIR/paper.pdf"
cp "$TEMP_DIR/metadata.json" "$PAPER_DIR/metadata.json"
2. 智能提取 PDF 文本
scripts/extract_pdf_text.sh "$PAPER_DIR/paper.pdf" "$PAPER_DIR/paper.txt"
策略：pdftotext → 检测字符密度（≥50 字符/页正常，<50 走 OCR 回退）
3. 分段完整阅读
用 read 工具每次 500 行，直到读完全文。
关键要求：必须读完全文再总结，不要只读摘要或部分内容。
4. 生成结构化总结
学术论文结构：
# 总结：<论文标题>
> 原文标题 / 发表日期 / 机构
---
## 📊 论文统计
- 总字数 / 总页数
- Figure（正文）：X 张
- Figure（附录）：X 张
- Table（正文）：X 张
- Table（附录）：X 张
---
## 一、研究背景与动机
## 二、研究设计
## 三、方法/系统架构
## 四、核心结果
### 4.1 结果 A
### 4.2 结果 B
## 五、讨论与局限性
## 六、结论
## 七、关键数据速览
5. 创建飞书文档并写入
{
"action": "create",
"title": "总结：<文档标题>",
"owner_open_id": "<用户的 open_id>"
}
{
"action": "write",
"doc_token": "<doc_token>",
"content": "<Markdown 格式总结>"
}
保存 feishu_doc_token.txt 以便后续补充材料合并时使用。
阶段一（补充）：补充材料合并
如果阶段零判断为补充材料，执行以下流程：
DOC_TOKEN=$(cat "$PAPER_DIR/feishu_doc_token.txt")
scripts/merge_supplement.sh "$PAPER_DIR" "<supplement.pdf>" "$DOC_TOKEN"
feishu_doc action=append doc_token="$DOC_TOKEN" content="
## 📎 补充材料：$(basename $SUPPLEMENT_PDF)
- 添加时间：$(date +%Y-%m-%d %H:%M)
- 摘要：$(cat $SUPP_TXT | head -20)
"
合并逻辑：
merge_supplement.sh 负责文件层面操作：
- 复制补充材料到
supplements/ 目录（带时间戳命名）
- 提取补充材料的元数据（
_meta.json）
- 提取简要摘要（
.txt）
- Agent 调用
feishu_doc 工具追加内容到飞书文档
- 更新
versions.json 记录（待实现）
注意：merge_supplement.sh 不直接操作飞书文档，仅准备文件和数据。飞书文档更新由上层 Agent 调用 feishu_doc 工具完成。
阶段二：配图（Figure/Table 提取与验证）
6. 定位 Figure/Table 页码
scripts/locate_figures.sh "$PAPER_DIR/paper.pdf" "$PAPER_DIR/paper.txt" "$PAPER_DIR/images"
脚本会：
- 用
grep 找到所有 Figure/Table 标题行
- 根据行号估算页码
- 对估算页码 ±2 页范围截图（候选页面）
⚠️ 注意：行号→页码是粗略估算，必须经过审核验证！
7. 验证截图（关键步骤）
对每个 Figure 的候选截图逐张审核：
for each Figure:
1. read 候选截图
2. 判断：图中是否包含目标 Figure？
- ✅ 包含 → 记录正确页码，复制为 Figure_XX_full.png
- ❌ 不包含 → 检查相邻页面
3. 如果所有候选页面都不对 → 扩大搜索范围
验证标准：
- ✅ 截图中必须可见 "Figure X" 或 "Table X" 标题文字
- ✅ 截图中必须包含图表内容（非纯文字页面）
- ✅ 复合图（多子图拼合）应作为完整页面保留
如果截图是纯文字：
- ❌ 不要使用该截图
- 检查相邻页面（±3 页范围）
- 检查文本提取是否有误（Figure 标题可能在图片中无法提取）
- 手动浏览 PDF 定位：
pdftoppm -f X -l X paper.pdf output
8. 插入图片到对应章节
精确定位：
{
"action": "upload_image",
"doc_token": "<doc_token>",
"file_path": "<图片路径>",
"parent_block_id": "<doc_token>",
"index": <目标索引>
}
技巧：从文档末尾往前插（倒序），避免索引偏移。
阶段三：审核（多模型审核）
核心思想：直接使用 fallback 模型审核 → 告知用户 → 主模型审查 → 人工确认
9. 读取模型配置并启动审核
CONFIG_FILE=<OpenClaw 配置文件路径>
FALLBACK_MODEL=$(jq -r '.agents.defaults.model.fallbacks[0]' "$CONFIG_FILE")
if [ -z "$FALLBACK_MODEL" ] || [ "$FALLBACK_MODEL" = "null" ]; then
echo "⚠️ 未配置 fallback 模型，将使用主模型自审"
sessions_spawn task="请审核这份飞书文档与原始 PDF 的一致性..."
else
echo "✅ 使用 fallback 模型进行审核：$FALLBACK_MODEL"
echo "📋 已启动审核流程，使用模型：$FALLBACK_MODEL"
sessions_spawn task="请审核这份飞书文档与原始 PDF 的一致性..." \
model="$FALLBACK_MODEL"
fi
注意：
- 优先使用配置中的 fallback 模型
- 不需要用户确认，直接启动审核
- 审核前告知用户使用的模型即可
审核内容：
- 文档章节完整性
- Figure 是否正确显示（非纯文字）
- 关键数据准确性（百分比、p 值、置信区间）
- 格式和错别字检查
10. 生成审核报告
审核报告包含：
- 字数对比（原始 PDF vs 飞书文档）
- 章节完整性检查
- Figure/Table 清单核对
- 关键数据提取（百分比、p 值、样本量等）
- 修改建议清单（逐条列出）
11. 主模型审查审核意见
主模型审查流程：
1. 阅读审核报告
2. 逐条审查修改建议：
- ✅ 合理建议 → 标记为"采纳"
- ❌ 错误建议 → 标记为"拒绝"并说明原因
- ⚠️ 需确认 → 标记为"待用户确认"
3. 生成最终修改方案
注意：
- 不照单全收审核意见
- 主模型对最终质量负责
- 有争议的建议提交用户确认
阶段四：人工确认
12. 提交用户确认
向用户发送：
- 飞书文档链接（初版）
- 审核报告摘要
- 修改建议清单（标注采纳/拒绝/待确认）
- 确认提示：
📋 文档已完成初稿和审核
✅ 已完成的修改：X 处
⚠️ 待您确认的修改：Y 处
❌ 拒绝的修改：Z 处（原因：...）
请查看文档后回复：
- "确认" → 应用所有修改，输出最终版
- "修改 XXX" → 指定需要调整的内容
- "跳过" → 直接输出当前版本
13. 等待用户确认
用户回复处理：
- ✅ "确认" / "没问题" / "可以" → 进入阶段五（完善）
- ✏️ "修改 XXX" → 根据用户要求修改后重新提交确认
- ⚠️ "跳过" / "直接输出" → 跳过修改，进入阶段五
阶段五：完善
14. 应用最终修改
根据用户确认的修改方案：
- 补充遗漏的章节
- 修正错误的数据
- 添加缺失的 Figure/Table
- 优化格式和表述
格式标准化检查清单（必须逐项核对）：
15. 最终检查
- 通读飞书文档，检查格式、错别字
- 确认所有链接可点击
- 确认图片显示正常
- 核对格式检查清单（见步骤 15）
16. 添加署名信息（强制）
在文档末尾添加署名块（必须包含）：
---
## 📝 文档信息
| 项目 | 信息 |
|------|------|
| 撰写人 | <Agent 名字>（<主模型名称>） |
| 审核模型 | <审核模型名称> |
| 审核状态 | ✅ 已通过 |
| 生成时间 | YYYY-MM-DD HH:MM |
| 文档版本 | v1.0 |
---
*本总结由 AI 助手自动生成，如有问题请指出。*
示例：
撰写人：Lux（qwen3.5-plus）
审核模型：kimi-k2.5
审核状态：✅ 已通过
生成时间：2026-03-26 17:13
文档版本：v1.0
注意：
- 撰写人 = 当前 Agent 的名字（从 IDENTITY.md 或会话上下文获取）
- 主模型 = 生成文档使用的模型（如
qwencode/qwen3.5-plus）
- 审核模型 = fallback 模型（如
qwencode/kimi-k2.5）
- 如果跳过审核，标注"审核状态：⏭️ 已跳过"
17. 返回最终文档
向用户发送：
- 飞书文档链接（最终版）
- 修改摘要（可选）
- 使用说明："如有问题请随时指出，我可以进一步修改"
脚本说明
去重系统
| 脚本 | 功能 | 输出 |
|---|
extract_metadata.sh | 提取 PDF 元数据（DOI、标题、作者、页数），生成 paper_id | JSON：paper_id, doi, title, pdf_hash |
check_duplicate.sh | 检查是否已处理，判断重复/版本更新/补充材料 | JSON：action, file_type, message |
merge_supplement.sh | 复制补充材料到 supplements/，提取元数据和摘要 | JSON：文件路径 + 摘要，不操作飞书文档 |
原有脚本
| 脚本 | 功能 |
|---|
extract_pdf_text.sh | 智能文本提取（pdftotext + OCR 回退） |
extract_pdf_images.sh | 提取嵌入图片 + 生成清单 |
locate_figures.sh | 定位 Figure/Table 页码 + 截取候选页面 |
review_document.sh | 生成审核报告（对比 PDF 与飞书文档） |
注意事项
去重系统
- DOI 优先：有 DOI 的论文用 DOI 作为唯一标识（
/ 替换为 _），无 DOI 时用指纹哈希
- 版本管理：同 DOI 不同版本会提示用户确认是否更新，不会自动覆盖
- 补充材料识别：文件名含
supplement/suppl/_si_/supporting/appendix/moesm/_esm 自动识别
- 支持 Nature 系列期刊标准命名（MOESM = Materials Online Electronic Supplementary Material）
- 精确去重：PDF 哈希完全相同则跳过，避免重复处理
- 文件夹命名：
papers/<paper_id>/，其中 paper_id 为 DOI（/→_）或 hash_<指纹>
补充材料合并
- 文件层面：
merge_supplement.sh 复制到 supplements/ + 提取元数据和摘要
- 飞书文档：Agent 调用
feishu_doc action=append 追加"补充材料"章节
- 命名规则：
YYYYMMDD_HHMMSS_<原文件名>（带时间戳避免冲突）
配图验证
- 页码估算不可靠：每张截图都要
read 验证
- 优先页面截图：
pdftoppm 整页截图 > pdfimages 嵌入图片
多模型审核
- 配置确认：执行前读取 OpenClaw 配置文件中的
agents.defaults.model.fallbacks 配置
- Fallback 模型审核：使用配置中的第一个 fallback 模型进行审核（避免自己审核自己）
- 降级方案：如未配置 fallback 模型，使用主模型重新阅读 PDF + 文档进行自审
- 主模型审查：逐条审查审核建议，不照单全收
- 人工确认：有争议的建议提交用户确认
流程自动化
- 六阶段流程：去重检查 → 生成 → 配图 → 审核 → 人工确认 → 完善
- 补充材料自动合并：识别后追加到主文档的"补充材料"章节
- 审核告知：审核前告知用户使用的 fallback 模型（无需确认）
- 人工确认环节：审核完成后需用户确认再输出最终版
- 格式标准化：使用检查清单确保每次输出格式一致
- 强制署名：文档末尾必须包含撰写人、审核模型、生成时间
输出格式稳定性
为确保每次生成的文档格式一致，必须遵守：
-
文档结构模板化：
- 严格按照"一、二、三..."章节编号
- 每个章节使用 H2 标题（
##）
- 子章节使用 H3 标题（
###）
-
表格样式统一：
- 所有统计数据使用 Markdown 表格
- 表格第一行为表头
- 重要数据加粗（如
**55.0%**）
-
强制署名：
- 文档末尾必须包含署名块（见步骤 17）
- 使用表格格式展示撰写人、审核模型等信息
- 不得省略或修改署名格式
-
质量检查：
已知限制（待实现）
飞书文档图片插入方法
正确用法（已验证）：
feishu_doc action=upload_image \
doc_token="<doc_token>" \
file_path="<image_path>" \
parent_block_id="<文档根 block ID>" \
index=20
feishu_doc action=upload_image \
doc_token="<doc_token>" \
file_path="<image_path>" \
parent_block_id="<章节 block ID>"
注意事项：
parent_block_id 为文档根 ID 时，index 表示在 children 数组中的位置parent_block_id 为章节 ID 时，图片会追加到该章节下insert + after_block_id 方式会报错，不推荐使用
注意事项
Token 消耗提醒
请注意 Token 消耗，建议使用包月套餐。
安全说明
环境变量：
OPENCLAW_WORKSPACE：OpenClaw 工作目录（用于存储论文和临时文件）
配置文件读取：
- 技能会读取
~/.openclaw/openclaw.json 获取 fallback 模型配置（用于多模型审核）
- 如未配置 fallback 模型，将使用主模型自审
本地存储：
- 论文文本：
<OPENCLAW_WORKSPACE>/papers/<paper_id>/paper.txt
- 飞书文档 Token：
<OPENCLAW_WORKSPACE>/papers/<paper_id>/feishu_doc_token.txt
- 提取的图片：
<OPENCLAW_WORKSPACE>/papers/<paper_id>/images/
系统依赖：
- 脚本可能运行
sudo apt-get install 安装 poppler-utils、tesseract-ocr 等工具（用于 PDF 处理和 OCR）
- 需要 root 权限，请确保在受信任的环境中使用
权限说明：
- 技能需要访问 OpenClaw 配置文件（读取 fallback 模型）
- 技能会调用
sessions_spawn 启动子代理审核（使用 fallback 模型）
- 技能会创建和修改本地文件（论文存储、Token 保存）
版本: 1.0.0
许可证: MIT
作者: yy-fan
最后更新: 2026-03-26
