Skill 应用 02：百页报告 3 分钟精读？文档精读 Skill 一键提炼核心+页码溯源

1. 百页 PDF 精读的真实困境：为什么普通总结总在编数据

一份 86 页的行业报告，逐字读完大概要三到五小时，而真正能进笔记的有效信息可能不到三成。更麻烦的是，你读完之后想回头找某个数据出自哪一页，往往要重新翻一遍。很多人第一反应是把 PDF 丢给大模型让它总结，结果拿到一段读起来很顺、但数据对不上原文的文字——这就是典型的幻觉。

我试过把一份 60 页的技术白皮书直接塞进对话窗口，模型给出的「市场规模 320 亿」在原文里根本不存在，它只是根据上下文「合理推测」了一个数字。对于做研报、写论文、做竞品分析的人来说，这种没有出处的总结比不总结还危险，因为你无法核对。

document-insight 这个 Skill 要解决的就是这件事：它不追求「一句话概括全文」这种爽感，而是把长文档拆成可控的块，逐块精读并记录页码，最后再全局归纳。所有观点和数据都带[p.xx]溯源标记，你随时能翻回原文验证。适合科研学生读论文、产品经理消化行业报告、研发看技术白皮书这几类场景。

整条链路分三步：先用 extract.py 把 PDF/Word/网页抽成带页码的结构化分块，再由 Agent 做 Map 阶段的分块批注，最后 Reduce 阶段整合成一份标准化精读报告。下面我把每一步的配置、脚本和验证方式都写清楚，你可以直接复制跑通。

2. TaoToken 前置准备：统一 Key 与 API 通道

在跑通 document-insight 之前，需要先解决模型调用的问题。Skill 本身只负责抽取、分块和编排，真正做批注和归纳的是背后的大模型。如果你在 Map 阶段要处理几十个文本块，每个块都发一次请求，用零散的 Key 管理会非常乱，额度、限流、模型切换都容易出问题。

TaoToken 在这里的作用是提供一个统一的 API 通道：一个 Key 覆盖多种模型，Base URL 固定，Map 和 Reduce 两个阶段可以按需切换模型——比如 Map 阶段用便宜快速的模型做批注，Reduce 阶段用更强的模型做归纳。这样既控制了成本，又不用在代码里维护多套鉴权逻辑。

你需要准备三样东西，我把它叫做「三件套」，后面所有配置都围绕它展开：

获取 Key 的入口在控制台的 API Keys 页面，创建后复制保存。如果你还不确定该选哪个模型，可以先到模型对话页面手动试几条 prompt，感受一下不同模型在长文本批注上的表现，再决定 Map 和 Reduce 分别用哪个。

需要提醒的是，Skill 的脚本和 Agent 配置里，Base URL 一定要写成https://taotoken.net/api这个形式，不要自己拼/v1/chat/completions之类的后缀，通道内部会处理路由。Key 建议放在环境变量里，不要硬编码进 extract.py 或 SKILL.md，避免提交到仓库泄露。

对于长期要跑文档精读、批量处理报告的场景，可以考虑 Coding Plan，它在高频调用下比按次计费更划算，尤其是你打算把 Map 阶段拆得很细的时候。接入文档里有各语言 SDK 的示例，Python 环境下用 OpenAI 兼容写法即可，改一下 base_url 和 api_key 就能通。

3. 可复制配置：extract.py 分块脚本与 Skill 配置片段

这一节是全文的核心，我把 extract.py 的关键逻辑和 Skill 的配置片段都写成可直接复制的形式。先看目录结构，Skill 放在项目的.trae/skills/document-insight/下：

.trae/skills/document-insight/ ├── SKILL.md ├── scripts/ │ └── extract.py └── .gitignore

SKILL.md 的 frontmatter 定义触发条件，Agent 靠这段描述判断什么时候调用它：

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

extract.py 负责把文档抽成raw.txt、chunks.json、meta.json三个产物。核心是分块函数，它按标题层级切分，每块绑定页码，并限制单块字符数避免上下文溢出：

# -*- coding: utf-8 -*- """文档精读 - 文本抽取与结构化分块脚本""" import argparse import json import re from pathlib import Path def normalize(text: str) -> str: """文本清洗，去除零宽字符、多余空白""" text = re.sub(r"[\u200b-\u200f\ufeff]", "", text) text = re.sub(r"[ \t]+", " ", text) return re.sub(r"\n{3,}", "\n\n", text).strip() def chunk_blocks(blocks: list, max_chars: int = 3000): """按标题层级做结构化分块，携带标题路径、页码""" chunks, buf, buf_len = [], [], 0 for blk in blocks: if buf_len + len(blk["text"]) > max_chars and buf: chunks.append({ "id": len(chunks), "title_path": buf[0]["title_path"], "page": buf[0]["page"], "text": "\n".join(b["text"] for b in buf), }) buf, buf_len = [], 0 buf.append(blk) buf_len += len(blk["text"]) if buf: chunks.append({ "id": len(chunks), "title_path": buf[0]["title_path"], "page": buf[0]["page"], "text": "\n".join(b["text"] for b in buf), }) return chunks 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()

运行抽取脚本，把 PDF 转成分块：

python scripts/extract.py report.pdf -o ./output

跑完之后，output/report_work/下会出现raw.txt、chunks.json、meta.json。chunks.json里每个块都带id、title_path、page，这就是后面页码溯源的依据。

接下来是模型通道的配置。如果你用 Cline 或类似的 Agent 工具，MCP 配置里要写全三件套：

{ "mcpServers": { "taotoken": { "command": "npx", "args": ["-y", "@taotoken/mcp-server"], "env": { "TAOTOKEN_BASE_URL": "https://taotoken.net/api", "TAOTOKEN_API_KEY": "sk-你的Key", "TAOTOKEN_MODEL": "claude-sonnet-4-5" } } } }

如果你用的是 Codex 这类工具，鉴权信息写在auth.json里，同样三件套齐全：

{ "base_url": "https://taotoken.net/api", "api_key": "sk-你的Key", "model": "claude-sonnet-4-5" }

Claude Code 场景下，环境变量方式最省事：

export ANTHROPIC_BASE_URL="https://taotoken.net/api" export ANTHROPIC_API_KEY="sk-你的Key" export ANTHROPIC_MODEL="claude-sonnet-4-5"

配置完成后，Map 阶段和 Reduce 阶段可以指向不同模型。Map 阶段处理几十个块，用响应快的模型；Reduce 阶段只跑一次，用归纳能力强的模型。切换时只改 Model ID，Base URL 和 Key 不动。

4. 验证请求：从分块到精读报告的端到端跑通

配置写完之后，必须验证整条链路真的通了，而不是「看起来配好了」。验证分三层：先确认模型通道能通，再确认抽取分块正确，最后确认 Map-Reduce 产出了带页码的报告。

第一层，验证 API 通道。用 curl 发一条最小请求，确认 Base URL 和 Key 有效：

curl https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的Key" \ -H "Content-Type: application/json" \ -d '{ "model": "claude-sonnet-4-5", "messages": [{"role": "user", "content": "回复 OK"}] }'

返回里能看到choices字段和内容，说明通道正常。如果这里就报 401，先别往下走，去检查 Key 是否复制完整、有没有多余空格。

第二层，验证抽取分块。跑完 extract.py 后，打开chunks.json检查三件事：块数量是否合理、每块是否带page、title_path是否反映了标题层级。可以用一段小脚本快速统计：

import json data = json.load(open("output/report_work/chunks.json", encoding="utf-8")) print("块数:", len(data)) print("首页块:", data[0]["page"], data[0]["title_path"]) print("末页块:", data[-1]["page"], data[-1]["title_path"])

如果page全是 0 或者title_path为空，说明解析阶段没拿到页码或标题，需要检查 PDF 是否带文本层。

第三层，验证 Map-Reduce。向 Agent 发送指令：

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

Agent 会先调 extract.py，再读chunks.json逐块批注，写入batch_*.md，最后整合成精读报告_xxx.md。打开报告，重点看两处：核心观点后面是否带[p.xx]，关键数据表的「页码」列是否填了真实页码。如果页码是空的或者明显对不上，说明 Reduce 阶段没有回查chunks.json，需要检查 Skill 的提示词里是否强制了溯源校验。

一个正常的报告片段长这样：

## 一句话结论（TL;DR） 国内大模型产业落地加速，端侧模型成为重点方向，但商业化落地仍待验证。 ## 核心观点摘要 1. 端侧大模型硬件门槛持续下降，主流手机已具备本地运行条件 `[p.12]` 2. 行业大模型商业化进度慢于技术迭代，企业付费意愿待提升 `[p.27]` ## 关键数据与证据 | 数据/证据 | 数值或内容 | 出处 | 页码 | |---|---|---|---| | 国内大模型厂商数量 | 合计72家备案模型 | 报告统计 | p.9 |

看到[p.12]、[p.27]这种标记，并且你能翻回原文对应位置找到那句话，才算真正跑通。这一步别偷懒，它是判断 Skill 有没有幻觉的唯一标准。

5. 常见报错排查：401、local proxy failed 与页码丢失

跑不通的时候，报错信息往往很具体，但容易看错方向。我把几个高频错误和对应处理列出来，你对照着查。

401 Unauthorized：最常见。先确认 Key 有没有复制完整，再确认请求头格式是Authorization: Bearer sk-xxx，注意 Bearer 后面有一个空格。如果 Key 是从控制台复制的，检查有没有把首尾的引号也带进去。还有一种情况是 Key 被禁用或额度耗尽，去控制台看一眼状态。

local proxy failed / connection refused：这类错误通常出现在 Agent 工具的网络配置层。检查 Base URL 是否写成了https://taotoken.net/api，有没有多写或少写路径。如果你在本地配了额外的网络层，先确认它没有拦截对taotoken.net的请求。MCP 配置里TAOTOKEN_BASE_URL的值要和 curl 验证时用的一致。

reading 'choices' of undefined：说明请求发出去了，但返回体里没有choices字段。多半是模型 ID 写错了，或者请求体格式不对。用 curl 那条命令先验证，确认返回结构正常，再回头检查 Agent 配置里的 Model ID 拼写。

OAuth 相关报错：如果你用的是 Claude Code 或 Codex 这类带 OAuth 流程的工具，报错提示 token 过期或授权失败，说明它没走 API Key 模式。检查环境变量ANTHROPIC_API_KEY是否设置，以及ANTHROPIC_BASE_URL是否指向https://taotoken.net/api。有些工具会优先读 OAuth 凭证，需要显式指定用 API Key。

页码丢失或全是 0：报告里观点没有[p.xx]，或者页码明显不对。先查chunks.json里page字段是否有值。如果抽取阶段就没拿到页码，说明 PDF 是扫描版或者解析库没识别到页面边界。扫描版 PDF 需要先做 OCR，本 Skill 只处理带文本层的文档。如果chunks.json有页码但报告里没有，说明 Reduce 阶段的提示词没强制溯源，检查 SKILL.md 里是否写明了「所有观点必须绑定页码」。

上下文溢出：Map 阶段报 token 超限。检查--max-chars参数，默认 3000 字符，如果文档段落特别长，可以调到 2000 甚至 1500。单块越小，Map 阶段请求次数越多，但每次更安全。配合 Coding Plan 的高频调用额度，拆细一点反而更稳。

网页抓取返回空：URL 抽取失败，可能是反爬。脚本内置一次重试，退避 3 秒。如果还是空，把网页正文复制保存成 txt，再用 extract.py 处理本地文件，这样最稳。

排查的顺序建议是：先 curl 验证通道，再检查 chunks.json，最后看报告输出。大部分问题在前两步就能定位，不用反复重跑整个流程。

6. 把文档精读接进你的日常工作流

跑通一次之后，真正有价值的是把它变成习惯。我的做法是：所有超过 30 页的 PDF 先进docs/目录，跑一遍 extract.py，再让 Agent 出报告。报告和chunks.json一起归档，以后要引用某个数据，直接搜报告里的[p.xx]，翻回原文核对，比重新读一遍快得多。

如果你要批量处理多份报告，可以把 extract.py 包一层循环，Map 阶段并发跑，Reduce 阶段串行归纳。模型通道统一走 TaoToken，Key 和 Base URL 只配一次，换模型只改 Model ID。需要更高频的调用额度，可以看 Coding Plan；想先手动感受模型在长文本上的表现，去模型对话页面试几条；接入细节和 SDK 示例在接入文档里；Key 的创建和管理在 API Keys 页面。