---
name: read-document
description: 读 PDF、Word、PPT、Excel 这类不是纯文本的文件时使用：用户要你看、总结、摘录、查找、核对或比较这些文件里的内容（本机对话的工作文件夹里的、云端对话沙箱里生成或下载的）。纯文本文件（.md、.txt、.csv、.json、代码）直接用 read 读，不用它；云端对话里上传的附件已经给了解析好的文字，按给的路径读；要生成或修改 Office 文件用对应的 office 技能；知识库里的文档用知识库工具。
---

# 读文档：先转成文字再读

`read` 只读得了纯文本。PDF、Word、PPT、Excel 先用辅助脚本转成文字，再按下面的办法读。

> 命令里的 `office/…` 是本技能资源目录（加载技能时给出的 Base directory）下的辅助脚本，运行时按资源目录写成完整路径；其余相对路径都相对当前工作目录。
> **解释器：** 工具列表里有 `load_workspace_dependencies`（本机对话）就先调一次，下面命令里的 `python3` 换成它返回的 `python`。没有这个工具（云端对话的沙箱）就直接用 `python3`。用到的库都已带好，不要 `pip install`，也不要另找系统里的解释器。
> **中间文件：** 转出来的文字放进这次新建的隐藏临时目录：`mktemp -d ./.dsh-read.XXXXXXXX` 会打印出目录名（下文写作 `<临时目录>`），之后的命令都直接写这个名字（每条命令是新的 shell，变量留不下来）。回答完——失败了也一样——只删这个目录（`rm -rf <临时目录>`）。原文件只读、不要改；转出来的文字是给你读的，不交付、不在回答里链接。

## 转成文字

```bash
python3 office/extract_text.py 文件.pdf <临时目录>
```

脚本打印结果文件的路径、字数、页数（PDF 才有）和目录（标题，标题太少时是每页开头，都带行号）。几个文件就各跑一次，结果放同一个临时目录。

- PDF：每页前面有一行 `[第 n 页]`；
- Word、PPT 转成 Markdown，标题是 `#`，PPT 每张幻灯片前面有 `<!-- Slide number: n -->`；Excel 每个工作表一个 `## 表名`，下面是表格；
- `.doc`、`.ppt`、`.xls`、`.wps` 这类旧格式脚本会先转成新格式，不用另外处理。

脚本没成功时看退出码：

- `3`：提取不出文字（扫描的 PDF、图片）。不要猜内容：是图片、工具列表里又有 `read_image` 的，用它直接看图；其余的如实告诉用户这份是扫描件或图片、这里读不出文字，要用里面的内容就把它作为附件发到云端对话里（云端对话的附件会自动识别文字）；
- `4`：转换失败（文件损坏、加了密码）。把脚本给的原因告诉用户。

## 读

- **不长的（两三万字以内）**：用 `read` 读结果文件全文。
- **长的**：先看脚本打印的目录，用 `read` 的 `offset`、`limit` 按行号读用得上的那几段；找具体的词、数字、条款用 `grep -n` 在结果文件里搜，再读前后几十行。不要从头一段段往下读完整份。
- **Excel 要算数**（汇总、筛选、排序、比对）：不要拿转出来的表格自己算，用 pandas 读原文件算（`pandas.read_excel("文件.xlsx", sheet_name=None)` 拿到所有工作表）。

## 回答

- 引用原文时说出处：PDF 写第几页，Word 写哪一节，PPT 写第几张幻灯片，Excel 写哪张表。
- 文件里没有的内容不要补；读到的和用户的说法对不上时直说。
