系列说明：「Agent Skills 开发实战」专栏已全部完结。全新 Skill 应用 系列，主打开箱即用业务场景落地，不从零造轮子，每篇配套完整 SKILL.md、执行脚本、配置模板，小白复制即可部署。 配套资源包已上传本人主页资源区，本文可直接绑定资源包自助下载。

一、前言：读长文档的痛苦，你是否也遇到过？

做研发、科研、产品、行业研究的同学，经常要面对大量长文档：百页行业 PDF 报告、学术论文、长篇调研报告、网页深度文章。日常会遇到这些痛点：

1、阅读成本极高：一份 80 页行业报告，逐字通读平均耗时 3~5 小时，有效信息不足 30%；用 document‑insight 精读，10 分钟生成结构化报告，所有观点带页码溯源；

2、重点容易遗漏：读完一遍，关键数据、创新点、核心论据容易被淹没在大段文字中；

3、普通 AI 总结容易 “幻觉”：直接丢给大模型做总结，经常编造不存在的数据，没有页码溯源，无法核对原文；

4、格式兼容麻烦：PDF、Word、网页、Markdown 多种格式混杂，需要手动复制粘贴文本；

5、输出无标准化：普通对话输出零散碎片，没有逻辑框架、没有数据表格，不能直接拿来做笔记、写报告素材。

市面上很多 PDF 总结工具，大多只做简单文本摘要，缺少分块抽取、页码溯源、Map‑Reduce 两级精读、多格式兼容完整工程化方案。

本文带来 document‑insight 文档精读 Skill，完整流水线：多格式文档抽取 → 结构化分块批注 → Map 分块精读 → Reduce 全局归纳，输出带页码溯源的标准化精读报告。完美适配 Traework、OpenClaw 双 Agent 平台，小白简单配置即可完成百页文档一键精读，规避 AI 幻觉问题。

✅ 读完本文你能收获

1、完整可落地文档精读 Agent Skill，包含 SKILL.md定义、extract.py抽取脚本；

2、支持 PDF/Word (.docx)/ 网页 URL/TXT/Markdown 多类型输入；

3、Map‑Reduce 两级精读机制，所有观点、数据附带页码溯源，大幅降低 AI 幻觉；

4、标准化精读报告输出：一句话 TL;DR、核心观点、完整逻辑框架、关键数据表、专业术语表；

5、Trae / OpenClaw 双平台完整部署教程，附带全套落地避坑清单；

6、全套资源包可下载，无需逐段复制代码。

二、document‑insight Skill 核心能力一览

2.1 核心功能清单

1、多格式文档解析
PDF、docx、本地文本、Markdown、网页 URL，多兜底解析策略，解析失败给出明确依赖安装提示；扫描版 PDF 会主动提示需要 OCR 处理。

2、结构化分块抽取
自动识别文档标题层级，按标题切分文本块，每块绑定页码信息，控制单块字符上限，避免大模型上下文溢出。

3、Map‑Reduce 两阶段精读

• Map 阶段：分块独立批注，记录要点、论据、存疑内容；

• Reduce 阶段：全局整合生成完整精读报告，并且回查原文校验，杜绝编造事实。

4、强溯源反幻觉机制
报告内每一条观点、每一组数据都附带页码引用，所有输出全部来自原文，禁止 AI 自行编造内容。

5、标准化交付精读报告
包含一句话总结、核心观点摘要、原文逻辑框架、关键证据数据表、学术论文专属术语表与综合评价。

6、完整产物留存：原始抽取文本、分块 JSON 元数据、中间批注文件全部本地落盘，方便二次查阅复盘。

7、完善容错处理：单页抽取失败跳过、网页反爬自动重试、依赖缺失给出 pip 安装指引。

2.2 适合人群

• 科研学生：快速精读学术论文，提炼创新点、实验结论；

• 产品 / 行业研究员：快速消化百页行业 PDF 报告；

• 研发工程师：阅读技术白皮书、长技术文档；

• 使用 Trae / OpenClaw 搭建本地 Agent 工作流的开发者。

三、Skill 完整架构与执行流程

3.1 技能目录结构

Plain Text .trae/skills/document-insight/ ├── SKILL.md               # 技能协议定义 ├── scripts/ │   └── extract.py         # 文本抽取、结构化分块脚本 └── .gitignore             # 忽略临时产物、缓存文件

运行后自动生成输出产物（<文件名>_work/）

Plain Text <文件名>_work/ ├── raw.txt                # 抽取完整原始文本 ├── chunks.json            # 结构化分块结果（id、标题路径、页码、字符） ├── meta.json              # 文档元信息：标题、页数、字数、语言 ├── batch_*.md             # Map阶段分块批注中间产物 └── 精读报告_<标题>.md      # Reduce阶段最终交付精读报告

3.2 完整三步工作链路

1、第一步：抽取与结构化分块（extract.py 脚本）
读取本地文件或者网页链接，自动解析文本，识别标题层级，切割为可控大小文本块，记录页码、标题路径，输出 raw.txt、chunks.json、meta.json。

命令示例： bash python scripts/extract.py report.pdf -o ./output

2、第二步：Map 分块精读（Agent 执行）
读取 chunks.json，分批处理每一个文本块；输出每一块的要点、支撑论据、逻辑定位、存疑项，写入batch_*.md中间批注文件。严格只记录原文存在内容，禁止脑补编造信息。

3、第三步：Reduce 全局归纳生成精读报告（Agent 执行）
读取全部 batch 批注文件与 meta 元信息，生成完整 Markdown 精读报告；生成完成后回查 chunks.json 校验页码引用，修正偏差，输出最终交付文档。

3.3 精读报告输出样例（片段）

markdown # 《大模型行业发展2026报告》精读报告 > 元信息：发布机构XXX | 来源类型PDF | 页数 86 · 字数42000 | 语言 zh | 精读日期：2026‑08‑20 ## 一句话结论（TL;DR） 国内大模型产业落地加速，端侧模型成为重点方向，但行业仍面临应用商业化落地难题。 ## 一、核心观点摘要 1. **端侧大模型硬件门槛持续下降**，主流手机已经具备本地运行条件 `[p.12]` 2. **行业大模型商业化落地进度慢于技术迭代速度**，企业付费意愿仍待提升 `[p.27]` ## 二、完整逻辑框架 第一章 行业总览 [p.1~p.10]   1.1 全球大模型产业现状：市场规模统计   1.2 国内政策环境与产业导向 第二章 技术发展趋势 [p.11~p.35]   2.1 端侧轻量化模型演进路径   …… ## 三、关键数据与证据 | 数据/证据 | 数值或内容 | 出处 | 页码 | |---|---|---|---| | 国内大模型厂商数量 | 合计72家备案模型 | 报告统计 | p.9 | ## 四、术语表 **RAG**：检索增强生成，将外部知识库和大模型结合的技术方案。 ## 五、综合评价 - 创新点：系统梳理端侧模型硬件适配现状 - 局限性：缺少中小企业真实落地案例样本 > 全部观点均溯源至原文，无自创内容。

四、SKILL.md 核心定义

4.1 Frontmatter 基础定义

yaml --- name: "document-insight" description: "文档精读：一键提炼百页报告、学术论文、长网页的核心观点与完整逻辑框架，输出结构化精读报告。当用户需要对长篇PDF/Word/网页文档进行快速阅读理解、核心内容提炼、总结要点时触发使用。" ---

4.2 Agent 自动触发指令

向 Agent 发送如下指令，即可调用本 Skill：

1、精读这份 PDF 论文，输出结构化精读报告；

2、提炼这份行业报告核心观点，带上页码来源；

3、对该网页链接做文档精读；

4、traework 任务指令示例：使用document‑insight精读xxx.pdf，输出精读报告到指定目录

五、双平台小白部署实操教程

方案 1：Trae平台部署

1、将完整document‑insight文件夹放置项目路径 .trae/skills/；

2、可以手动对话触发，也可以新建一次性任务；

3、任务描述示例：

Plain Text 使用 document‑insight 精读 D:/docs/2026行业报告.pdf，输出精读报告到D:/out目录

4、执行完成后，在输出目录获取xxx_work/精读报告_xxx.md。

方案 2：OpenClaw 平台部署

1、将技能文件夹复制到 ~/.openclaw/skills/document‑insight/；

2、终端先执行抽取脚本：

bash python .trae/skills/document-insight/scripts/extract.py input.pdf -o work

3、在对话发送指令：执行document‑insight完整精读流程；

4、Agent 读取 chunks.json 执行 Map‑Reduce 两阶段精读，输出最终精读报告。

依赖安装提示：

bash # 基础必装 pip install requests # PDF解析 pip install pdfplumber pypdf # Word解析 pip install python‑docx # 网页解析 pip install trafilatura readability‑lxml

六、extract.py 脚本核心骨架

python # -*- coding: utf-8 -*- """文档精读 - 文本抽取与结构化分块脚本 输入：本地文件（.pdf / .docx / .txt / .md）或 http(s) 网页 URL 输出：raw.txt、chunks.json、meta.json """ import argparse import json import logging import os import re import sys from pathlib import Path def setup_logging():     ... def normalize(text: str) -> str:     """文本清洗，去除零宽字符、多余空白"""     ... def extract_pdf(path: Path, timeout:int):     """PDF多库降级抽取"""     ... def extract_docx(path: Path):     """docx文档解析，识别标题层级"""     ... def extract_url(url: str, timeout:int):     """网页正文抽取，trafilatura优先，兜底正则"""     ... def chunk_blocks(blocks: list, max_chars:int):     """按标题层级做结构化分块，携带标题路径、页码"""     ... def main():     parser = argparse.ArgumentParser(description="文档精读抽取脚本")     parser.add_argument("input", help="本地文件路径或者网页url")     parser.add_argument("-o","--outdir",default=None)     parser.add_argument("--max-chars",type=int,default=3000)     args = parser.parse_args()     # 完整执行逻辑：文件判断、解析、分块、写出产物     ... if __name__ == "__main__":     main()

七、落地避坑 8 条指南

⚠️坑 1：扫描版 PDF 直接执行，抽不到文本
解决方案：本 Skill 只支持带文本层 PDF；扫描版 PDF 会提示报错，需要先使用 PaddleOCR/Tesseract 做 OCR 文字识别。

⚠️坑 2：大模型输出内容出现幻觉，编造数据
解决方案：本 Skill 强制启用溯源机制，精读报告所有关键信息必须绑定页码；生成报告后 Agent 会回查 chunks.json 校验，禁止 AI 凭空生成内容。

⚠️坑 3：网页链接抓取返回空内容、403 反爬
解决方案：脚本内置一次重试，退避 3 秒；仍然失败建议复制网页正文保存为 txt 文件再进行精读。

⚠️坑 4：文档过长，大模型上下文溢出
解决方案：脚本自动按标题切分文本块，Map 阶段分批处理，单批控制 8000 字符以内，规避上下文超限。

⚠️坑 5：Python 依赖缺失，脚本直接退出
解决方案：脚本会明确打印缺失包名与 pip install 命令，按提示安装对应库即可。

⚠️坑 6：输出精读报告找不到原文出处
解决方案：不要删除xxx_work整个工作目录，chunks.json、batch_*.md是完整溯源依据。

⚠️坑 7：中文 / 英文混合文档输出混乱
解决方案：自动识别文档主要语言，批注跟随段落语言，报告主体使用文档主要语言。

⚠️坑 8：直接复制粘贴大段文本丢给 Agent，不使用脚本抽取
解决方案：优先运行 extract.py脚本做结构化分块；直接丢原始长文本会丢失页码、标题层级信息，溯源失效。

八、配套资源领取

全套落地资源包已上传本人主页资源区，可直接自助下载，包含：

1、document‑insight 完整 SKILL.md技能定义；

2、完整可运行 extract.py抽取脚本；

3、技能目录模板.gitignore 配置。

领取方式：前往本人主页资源区自助下载；部署调试遇到问题，欢迎评论区留言交流。

九、系列回顾与下期预告

往期完结系列

「Agent Skills 开发实战」完整 12 篇专栏，覆盖 Skill 底层开发、编排、项目落地手册。

Skill 应用系列往期回顾

Skill 应用 01：资讯聚合 Skill｜过滤广告标题党，只看你关心的新闻资讯

十、文末互动

你平时阅读论文、行业报告时最大痛点是什么？是读文档耗时太久，还是 AI 总结经常乱编内容？
如果你希望增加新功能，例如支持 PPT 解析、输出 markdown 笔记，欢迎评论区留言。

觉得本文文档精读 Skill 对你有帮助，欢迎点赞👍 + 收藏⭐ + 关注，持续更新开箱即用 Agent 实战技能！