dsh-plugin-pdf-text

Readme

# dsh-plugin-pdf-text

Read text out of local PDF files inside [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH).

给 DeepSeek Harness（DSH）用的 PDF 文字读取插件：注册一个 `pdf_extract` 工具，让 agent 自己读 PDF 报告，不必让用户截图或转格式。

纯 Node、无 Python、不联网、文件不离开本机。

## 功能

注册一个工具 `pdf_extract`，它可以：

- 逐页返回 PDF 文字，每页带页眉标记，例如 `===== 第 3 页 =====`；
- 回答开头给出统计：**总页数、已读取页数、其中有文字的页数**；
- 整份 PDF 一页文字都没有时，明确说明「这很可能是纯图片扫描件，需要 OCR」，**绝不编造内容**；
- 返回给模型的内容上限 **32000 字符**，超长时按页边界截断并提示改用 `maxPages` 或 `saveTo`；
- 可选把全文另存为文本文件（`saveTo`），便于之后反复检索；
- 明确报错：文件不存在、目录不存在、无权限、PDF 加密等都会给出可读提示，而不是静默失败。

用法：在 DSH 会话里直接说「读一下这个 PDF」并给出路径，agent 就会调用 `pdf_extract`。

## 安装

前置：已安装 DSH，profile 名称已知（本机为 `desktop`）。

### 从 GitHub 安装（推荐，也是插件市场用的方式）

```bash
dsh plugin --profile desktop add peanutcd2005/dsh-plugin-pdf-text
```

> DSH 兼容 `install` 与 `add` 两种写法；也可在「设置 → DSH 插件市场」里搜 `dsh-plugin-pdf-text` 一键安装。

### 从本地 tarball 安装（离线）

本插件用本地 tarball 安装时，除 `unpdf` 首次下载外不联网；若 profile 里已有 `unpdf` 则完全离线。

```powershell
# 1) 打包（在插件项目目录里）
pnpm pack --pack-destination .pack

# 2) 安装到 profile（用绝对路径，且路径保持纯英文，避免中文路径乱码）
dsh plugin --profile desktop add "C:\Users\csh\dsh-tools\dsh-plugin-pdf-text\.pack\dsh-plugin-pdf-text-0.1.0.tgz"

# 3) 重启 profile 才生效（插件不热加载）
```

安装后可用下面三条命令对账：

```powershell
# a) profile 的 bundles 里应出现 dsh-plugin-pdf-text
Get-Content "$env:USERPROFILE\.dsh\profiles\desktop\package.json"

# b) 组合配置应出现 id: pdf-text 的行，且无重复、无告警
#    注意：桌面版（Electron 托管）会拒绝 dump-config 并返回
#    'profile "desktop" is managed exclusively by the Electron application'，
#    这种情况改用界面「插件」页 /「设置 → 内置插件」确认；
#    在 `dsh web` 等非桌面 profile 上该命令正常可用。
dsh --profile desktop --dump-config

# c) 重启后在会话中调用 pdf_extract 读一份 PDF
```

卸载：

```powershell
dsh plugin --profile desktop remove dsh-plugin-pdf-text
```

## 参数

| 参数 | 必填 | 类型 | 含义 |
| --- | --- | --- | --- |
| `path` | 是 | string | PDF 文件的绝对路径。 |
| `maxPages` | 否 | integer ≥ 1 | 只读取前 N 页；省略则读取全部页面。超过总页数时按总页数处理。 |
| `saveTo` | 否 | string | 把提取到的全文另存为该绝对路径的文本文件（带统计行与页眉）。所在目录必须已存在。 |

返回内容示例：

```text
文件：C:\...\沙文一号加气站可行性研究报告9.9(3)(1).pdf（14.1 MB）
总页数：198；已读取：3 页；其中有文字的页数：2

===== 第 1 页 =====
贵阳市矿能集团石化发展有限公司沙文一号加气站 可行性研究报告
...
```

纯图片扫描件：

```text
文件：C:\Users\csh\Desktop\2026年度学习证明.pdf（1.9 MB）
总页数：1；已读取：1 页；其中有文字的页数：0

该 PDF 共 1 页，但这一批页面没有提取到任何文字层。
它很可能是纯图片扫描件（整页是照片或截图），需要 OCR 才能识别内容。本工具不会编造内容。
如果只想先看一部分，可用 maxPages 指定页数；如果确认是扫描件，请改用 OCR 工具。
```

## 使用限制

- **只处理带文字层的 PDF。** 纯图片扫描件（整页是照片或截图）返回「无文字层 / 需要 OCR」提示，不返回空内容、也不编造内容。本插件不含 OCR。
- **返回给模型的内容上限 32000 字符。** 超长时按页边界截断，并提示改用 `maxPages` 分批读取，或用 `saveTo` 保存全文后再定位段落。`saveTo` 写出的文件是全文，不受该上限影响。
- **判定「这一页有文字」的标准**：去掉空白后不少于 20 个字符；页眉页脚等零星字符的页可能被算作无文字页。
- **只读取，不改动 PDF。** 唯一的写操作是 `saveTo` 指定的文本文件（UTF-8）。
- **纯本地运行。** 不联网、不依赖 Python、不调用外部服务，文件内容不离开本机。
- **`saveTo` 不会自动建目录。** 目标目录不存在时会明确报错。
- 扫描件、加密 PDF、损坏 PDF 都会明确报错或提示，不会返回空内容。

## 实现说明

- 解析依赖 [unpdf](https://www.npmjs.com/package/unpdf)（零运行时依赖、服务端取向的 pdf.js 封装），加载参数为
  `{ verbosity: 0, useSystemFonts: true, isEvalSupported: false }`，用于压掉 pdf.js 的字体告警；
  文本按页提取（`extractText(proxy, { mergePages: false })`）。
- 插件**不 import 任何 `@deepseek-ai/*` 包**：profile 的插件目录里解析不到这些包，导入会导致插件加载失败。
  工具定义直接按 `ctx.tools.register()` 的契约手写（`{ name, description, parameters, output: { schema, render }, execute }`）。
- 项目文件：`lib/index.js` 全部实现、`cordis.patch.yml` bundle 补丁、`scripts/verify.mjs` 验收脚本。

## 自检

```powershell
# 在插件项目目录，把 profile 的 unpdf 借来当依赖即可运行（脚本只读 PDF）
node scripts/verify.mjs "C:\path\to\report.pdf"
node scripts/verify.mjs "C:\path\to\scanned.pdf" --expect-scan
```

脚本会打印总页数、已读取页数、有文字的页数、耗时，并对扫描件断言「无文字层」提示。

## 发布到 DSH 插件市场

市场（`dsh-plugin-marketplace`）**没有申请入口**：给 GitHub 仓库打上 topic `dsh-plugin`，CI 最迟 2 小时扫描收录。

1. **建仓库并推代码**（仓库名建议与包名一致：`dsh-plugin-pdf-text`）：

   ```bash
   cd dsh-plugin-pdf-text
   git init
   git add -A
   git commit -m "feat: pdf_extract tool for DSH (0.1.0)"
   git remote add origin https://github.com/peanutcd2005/dsh-plugin-pdf-text.git
   git push -u origin main
   ```

2. **打 topic**：仓库页 → ⚙ Settings → **Topics** → 添加 `dsh-plugin`。
   建议再加：`dsh`、`deepseek-harness`、`cordis-plugin`、`pdf`。

3. **等 CI 收录**：最迟 2 小时出现在市场列表（设置 →「DSH 插件市场」）。

4. **改名提醒**：如果你的 GitHub 用户名以后变了，记得同步更新 `package.json` 的
   `repository` / `homepage` / `bugs` 与本文档里的仓库地址。

收录自检（对照市场 [STANDARD.md](https://github.com/bradeGithub/DSH-Plugins-Marketplace/blob/main/STANDARD.md)）：

| 检查项 | 本仓库状态 |
| --- | --- |
| 根目录 `package.json` 有 `dsh` 声明 | ✅ `dsh.plugin` + `dsh.bundle.patch` → 判为 cordis 插件（bundle 型） |
| `main` 指向仓库里真实存在的文件（产物型，无需构建） | ✅ `lib/index.js` 已提交，无 `scripts.build` |
| 根目录无 `install.ps1` / `install.sh` | ✅ 不会误判成脚本型 |
| 宿主接口包只进 `peerDependencies` | ✅ 更彻底：**不依赖任何 `@deepseek-ai/*` 包**（见「实现说明」） |
| `version` 每次发版必须 bump | ✅ 当前 0.1.0；改代码务必改版本，否则「更新」按钮不会出现 |
| 包名唯一 | ✅ 已核对市场索引：无 `dsh-plugin-pdf-text` 占用 |
| 分类敏感词自查 | ✅ 简介未含微信/通知/商店/榜单等词 |
| 披露字段（`disclosure`） | ✅ `cloud:false`、`network:[]`、`apiKeys:[]`、`retention:none` |

两个容易踩的坑（本仓库已避开）：

- **不要**在运行时或安装脚本里自己写 `cordis.patch.yml` 注册条目 —— 市场安装时会自动注册，双注册会导致 Web 服务路由重复、启动崩溃（市场 issue #39）。
- **不要**把 `@deepseek-ai/dsh-tools` 等宿主包写进普通 `dependencies` —— 旧版副本会遮蔽宿主（STANDARD §6.6）。本插件干脆不 import 任何 `@deepseek-ai/*`。同时市场在注册 bundle 时会校验 `dependencies`+`peerDependencies` **全部可解析**，声明解析不到的宿主 peer 会直接让安装失败。

## 验收记录（本机实测）

验收对象：`沙文一号加气站可行性研究报告9.9(3)(1).pdf`（14.1 MB）。

| 检查项 | 期望 | 实测 |
| --- | --- | --- |
| 总页数 | 198 | 198 |
| 有文字的页数 | 169–170 | 169 |
| 第 123 页财务指标 | 含「财务内部收益率」「1107.25 万元」「19.06」 | 全部命中（`财务内部收益率`、`1107.25`、`19.06`） |
| 纯图片扫描件 | 返回「无文字层 / 需要 OCR」，不编造内容 | `2026年度学习证明.pdf`（1 页）、`关于贵阳矿能集团风电投资项目之投资合作协议.pdf`（62 页）均正确返回 OCR 提示 |
| 超长截断 | 32000 字符上限 + 按页截断提示 | 130 页调用返回 32079 字符，末页为第 49 页并附提示 |
| 耗时 | — | 整份 198 页约 0.8–1.4 s |
| 进程退出码 | 0 | 0（无 pdf.js 字体告警） |

安装验证三连：

1. profile `dsh.profile.bundles` 含 `dsh-plugin-pdf-text`，且无重复项；
2. `dsh --profile desktop --dump-config` 在本机被 Electron 拒绝（`profile "desktop" is managed exclusively by the Electron application`），
   因此改用「已安装文件与源码逐字节一致 + 工具在活动会话中真实可用」作为等价证据；
3. 重启后 agent 在本会话直接调用 `pdf_extract` 读通了上述报告。

## License

MIT