dsh-pdf-edit

English | 中文

版本：v0.3.1（当前） | 需要 dsh >= 0.1.1-rc.2 / Node >= 22

DeepSeek Harness 插件 —— AI 修改 PDF 文字，自动保持原版式不变。

这是什么

一个面向 PDF 文档的 AI 编辑插件。你用自然语言告诉它要改什么，它就会：

• 只改文字，不动排版 —— 字体、字号、颜色、位置全部锁定，改完和原文看起来一模一样
• 自动处理溢出 —— 新文字比原来长时，自动缩小字号或截断，不会撑破版面
• 支持中文 —— 自动识别并嵌入系统中文字体（SimHei / 微软雅黑 / Noto Sans CJK）

适合什么场景

安装

# 通过 Harness 插件 CLI（与官方插件一致）
dsh plugin --profile web add dsh-pdf-edit@latest

# 或直接通过 npm
npm install dsh-pdf-edit

当前版本：v0.3.1（2026-08-23 发布）。主要更新：工具层路径白名单体验修复（报错带出允许根目录、按调用传 allowedRoots）、pdf-edit-insert 支持 markdown 文本；v0.3.0 新增插入内容能力与字体回退链。

遇到 "Cannot read properties of undefined (reading 'prepare')"？

这是 dsh 宿主 rc 阶段的已知问题：当 @deepseek-ai/dsh-tools 在进程内被加载多份时，工具调度器 Symbol 失配。本插件从 v0.1.7 起通过 peerDependencies（精确版本钉死 0.1.1-rc.2）从源头规避；但若曾在 profile 目录下手动执行过 pnpm install，残留副本仍可能触发。

按以下顺序排查：

# 1. 检查是否真的有本地副本（实体目录而非 symlink）
ls -l ~/.dsh/profiles/web/node_modules/@deepseek-ai/

# 2. 若有，移除核心包的本地副本
cd ~/.dsh/profiles/web
pnpm remove @deepseek-ai/dsh-tools @deepseek-ai/cordis

# 3. 重启 dsh，并【新建会话】验证（崩溃过的旧会话日志已损坏，无法恢复）

插件装载时也会主动探测该问题：若命中会直接抛出带上述修复命令的明确报错，而不是静默崩溃。

AI Agent 操作手册（隐藏规则）

在使用本插件前，请先确认以下三个“隐藏规则”——它们在源码中存在，但不在工具接口文档中直接说明：

编程接口简要示例

const { StyleLockedEditor, applyPatches, removeSubheadings } = require('dsh-pdf-edit');

// 1. 打开文档（需 Uint8Array）
const original = new Uint8Array(require('fs').readFileSync('doc.pdf'));
const editor = await StyleLockedEditor.open(original, chatFn, { allowedRoots: ['/workspace'] });

// 2. 预览某页可编辑单元（获取 tid 列表）
const units = await editor.previewPage(1);
console.log(units);  // [{ tid: 'p1-0', text: '...' }, ...]

// 3. 全文 AI 修改（标准流程，受 sanitizeText 限制）
const result = await editor.editDocument('修正错别字并统一术语');
require('fs').writeFileSync('doc.edited.pdf', result);

// 4. 手动删除文字（绕过 sanitizeText 空文本限制）—— 完整可运行示例
const fs = require('fs');

// 4a. 提取页面并找到要删除的 tid（getExtract 已开放为公共方法）
const ex = await editor.getExtract(1);
const targetText = '小标题文字';  // 替换为实际要删除的文字
const deleteTid = ex.units.find(u => u.text.includes(targetText))?.tid;

if (deleteTid) {
  // 4b. 直接修改 Unit 文本为空（绕过 sanitizeText）
  const unit = ex.units.find(u => u.tid === deleteTid);
  unit.text = '';

  // 4c. 打开原生文档、渲染修改
  const { doc, resolver } = await editor.openNativeDoc();
  await editor.drawPatchedPages(doc, resolver, [
    { ex, changedTids: new Set([deleteTid]) }
  ]);
  const result = await doc.save();
  fs.writeFileSync('deleted.pdf', result);
}

await editor.close();

简化删除包装（v0.2.2 新增）

const { removeSubheadings } = require('dsh-pdf-edit');
// 直接删除匹配的小标题文本（精确匹配或包含匹配）
const { outputPath, deletedTids } = await removeSubheadings(
  'doc.pdf', 'doc-deleted.pdf',
  ['第一章 小标题', '附录 A'],
  chatFn  // 可选：自定义 LLM 调用函数
);

插入内容（v0.3.0 新增：pdf-edit-insert / insertPages）

原四个工具只支持“原位改字”，无法在文档里加内容。v0.3.0 补齐这条链路：把结构化内容（标题 + 文本块）作为新页插到原 PDF 指定页之后，自动排版（灰底横幅标题 / 正文 / 公式灰底框 / 跨页断页 / 页脚），原页零改动，且无需 LLM（不依赖 chatFn / API Key）。

工具调用：

pdf-edit-insert
  pdfPath: "doc.pdf"
  insertions: [
    { afterPage: 14, title: "补充一：电解质判别", caption: "模块二｜插入位置：第 14 页后",
      blocks: [
        { t: "p",  s: "判断电解质只看自身能否电离……" },
        { t: "b",  s: "CO₂ 自身不能电离，是非电解质" },
        { t: "eq", s: "2HCO₃⁻ + Ca²⁺ + 2OH⁻ = CaCO₃↓ + CO₃²⁻ + 2H₂O" },
        { t: "h2", s: "小节标题" },
      ] }
  ]

块类型 t：p 段落 / b 要点（悬挂缩进）/ b2 子要点 / h2 小节标题（加粗）/ eq 公式（灰底框）/ gap 间距。同 afterPage 的插入自动合并为一组；内容超长自动跨页（续页带“（续）”标记）。

编程接口（src/inserter.ts）：

const { insertPages, parseMarkdownBlocks } = require('dsh-pdf-edit');
const { bytes, insertedPages, totalPages } = await insertPages(
  new Uint8Array(require('fs').readFileSync('doc.pdf')),
  [{ afterPage: 14, title: '补充一', caption: '插入位置', blocks: parseMarkdownBlocks(mdText) }],
  {
    family: 'regular', titleFamily: 'bold',
    fonts: {
      customs: [{ family: 'regular', path: '/fonts/NotoSansCJKsc-Regular.otf' },
                { family: 'bold',    path: '/fonts/NotoSansCJKsc-Bold.otf' }],
      cjk: { path: '/fonts/NotoSansCJKsc-Regular.otf' },
      fallbacks: [{ family: 'freesans', path: '/usr/share/fonts/gnu-free/FreeSans.otf' }],
      fakeBold: false,
    },
    footerText: (n) => `补充页 · 插于原第 ${n} 页之后`,
  },
);

化学式上下标缺字回退：Noto/思源等常见 CJK 字体 cmap 里没有 ₂₃⁺⁻（U+2080-209F）等字形——这就是很多 PDF 里 Na₂O₂ 显示为空白的根源。配置 fonts.fallbacks（如 FreeSans，含完整上下标）后，FontResolver 会自动把缺字字符拆到回退字体混排渲染（resolveRuns / hasGlyph）。回退字体不做子集化（pdf-lib 对部分 CFF 如 FreeSans 子集化后字形整段空白，已实测修复）。

依赖说明

• 核心：pdf-lib（PDF 操作）+ pdfjs-dist（文本提取）
• 原生绘制：fontkit（字体嵌入与测量）
• 浏览器模式：puppeteer-core（需 browserExecutablePath 指向系统 Chrome/Edge）
• 中文字体：自动探测 simhei.ttf / msyh.ttc / wqy-microhei.ttc / wqy-zenhei.ttc / NotoSansCJK-Regular.ttc，或通过 fonts.cjk 配置

⚠️ 注意：工具接口（pdf-edit-document、pdf-edit-preview、pdf-edit-page、pdf-edit-relayout）封装了完整流程，但受限于 allowedRoots、sanitizeText、chatFn 依赖；编程接口更灵活但需要自己处理 openNativeDoc、drawPatchedPages、doc.save()。如果你的目标包含“删除文字”，请直接走编程接口操作 Unit 对象，而非依赖标准 editDocument 流程。pdf-edit-insert 无 LLM / sanitizeText 限制，可直接在工具层使用。

AI 选哪个接口？（快速决策表）

💡 路径解析提示：若 pdfPath 解析到 /home/wang/Desktop 而非预期目录，说明 process.cwd() 与实际文件位置不匹配。编程调用时显式传入绝对路径：const pdfPath = require('path').resolve('Document.pdf');，并在 allowedRoots 中包含该路径的真实父目录（如 ['/workspace'] 或 ['/home/wang/dsh-pdf-edit']）。

更新记录

v0.3.1

• 工具层路径白名单体验修复：越界报错现在会带出「当前允许的根目录」；5 个工具（page/document/relayout/preview/insert）都支持按调用传 allowedRoots，与插件配置合并后放行——GUI 工作目录与 dsh 服务 cwd 不一致时不再需要改服务配置
• pdf-edit-insert 支持 markdown 文本：insertions[].markdown 直接传 md（#标题 / -要点 / 缩进子要点 / eq:公式 / ---分隔），内部经 parseMarkdownBlocks 解析，与 blocks 合并
• 路径守卫新增 withExtraRoots() / rootsText() 辅助；测试 +4（全套 137 例通过）

v0.3.0

• 新增「插入内容」能力：工具 pdf-edit-insert + 编程接口 insertPages() / parseMarkdownBlocks()（src/inserter.ts）——把结构化内容作为新页插到指定页之后，自动排版（横幅/正文/公式框/跨页断页/页脚），原页零改动，无需 LLM
• FontResolver 字形覆盖与回退链：新增 resolveRuns() / hasGlyph() 与 fonts.fallbacks 配置——化学式上下标（₂₃⁺⁻ 等，Noto CJK cmap 缺失）自动拆到回退字体混排渲染
• 修复：回退字体不做 pdf-lib 子集化（实测 FreeSans 等 CFF 字体子集化后字形整段空白）
• 系统 CJK 字体自动探测补充 wqy-zenhei.ttc、noto-cjk 等 Linux 路径
• 测试新增 8 例（inserter 集成 + fonts-fallback 单测），全套 133 例通过

v0.2.2

• README 重构：人类内容（这是什么 / 安装 / 版本号）前置，AI Agent 操作手册后置
• removeSubheadings() 完整实现（不再抛错误，支持精确/包含匹配、多页累积渲染）
• 关键编程方法公开：getExtract、openNativeDoc、drawPatchedPages、mergeChanged

v0.2.1

• 动态读取 DSH 默认模型：通过 ctx.agentDefaultModel.currentSelection() 获取用户当前配置的 provider/model，替换硬编码的 agnes
• 优先级链：用户配置 (config.provider/config.model) > DSH 默认模型 > agnes 兜底
• 无论用户在 DSH 里用的是 deepseek、kimi、glm、minimax、openpangu、mino、claude、grok、gpt 等，插件都会自动跟随，零配置即可使用

v0.1.8

• 复用 DSH 已有 LLM 服务（ctx.llm），无需用户手动配置 API Key
• inject 增加 "llm" 依赖，插件通过 ctx.llm.stream() 调用 DSH 内置 LLM
• 保留 DeepSeek API 直连作为 fallback（当 ctx.llm 不可用时）

v0.1.7

• 依赖声明重构：@deepseek-ai/dsh-tools 从 dependencies 移入 peerDependencies 并精确钉死 0.1.1-rc.2， 从源头避免 pnpm 在 profile 内物化第二份副本（双副本会使工具调度器 Symbol 失配，导致所有工具崩溃）
• 新增装载守卫：apply() 首行探测工具运行时调度器是否可用，失联时抛出带修复命令的明确报错而非静默崩溃
• README 安装章节新增 "Cannot read properties of undefined (reading 'prepare')" 故障排查指引； engines 声明 Node >= 22

v0.1.6

• 适配 dsh v0.1.1-rc.2 插件契约：导出 name / inject / apply(ctx, config)，四个工具改经 ctx.tools.register(defineTool(...)) 注册，配置经 cordis 行 config: 字段传入
• 新增路径白名单守卫：pdfPath/outputPath 经 allowedRoots 校验、符号链接解析与扩展名/大小检查，防止注入导致的任意文件读写
• Prompt injection 防御：PDF 文本放入数据容器并加固系统提示词，AI 输出做注入特征二次检测，命中回退原文
• 浏览器渲染加固：禁用 JS、拦截出站请求、CSP 与 CSS 清洗、背景 dataUrl 与字体名白名单
• 工程健壮性：API Key 环境变量优先、请求超时、分块并发限流、429 感知退避、AI 输出限长校验
• 新增测试体系（120 用例）与编辑能力基准（10 用例，npm run bench）

v0.1.5

• 包名从 @whatsmore-nf/dsh-plugin-pdf-edit 改为 dsh-pdf-edit，在插件市场直接显示为插件名

v0.1.4

• 修复 embedCustom 传 fontkit 对象给 doc.embedFont 的错误，改为直接传 Uint8Array
• 修复 loadBytes 不支持字符串路径（如 fonts.cjk: '/path/to/font.ttf'）
• 修复 CFF 格式 TTC 字体兼容性，自动检测并跳过不支持的 CFF 字体
• 添加 Android 系统字体路径（MiSansRoundedSC、NotoSansSC 等）
• 简化 cordis.patch.yml 为社区插件标准格式

v0.1.3

• 修复 ctx.tools.register() 缺少必需的 output: { schema, render } 字段导致注册失败
• 修复 execute 签名不匹配（应为 (args, exec) 双参数）

v0.1.2

• 添加 cordis 插件格式的 name/inject/apply 导出，修复 "invalid plugin" 错误

v0.1.1

• 修复 cordis.patch.yml 中插件名与 package.json 不一致导致加载失败的问题

v0.1.0

• 初始发布
• 样式锁定编辑：AI 修改文字，自动保持原排版
• native 渲染模式：pdf-lib 直绘，零浏览器依赖
• CJK 字体自动探测与嵌入
• 溢出处理：shrink / clip / wrap / reject
• 术语表全局替换
• 三种重排版模板：academic / mobile / briefing

</

工作原理

整个编辑流程由 StyleLockedEditor（src/pipeline.ts）统一调度，分为四个阶段：提取 → AI 修改 → 溢出控制 → 叠加绘制。下面结合源码逐步说明。

1. 提取：pdfjs + 样式锁定（src/extractor.ts）

• 用 pdfjs-dist（src/pdfjs-lazy.ts 延迟加载）打开 PDF，逐页调用 getTextContent() 读取每个文本项（str、transform、width、fontName、height）。
• 通过 page.getViewport({ scale: 1 }) 把页面坐标系转换为 PDF 点（pt）坐标。
• 对每个 str 构造 RawRun：记录 text、x、baselineTop、width、fontSize（由 transform 矩阵计算）、颜色（从 OPS.setFillRGBColor / OPS.setFillGray / OPS.setFillCMYKColor 运算符列表恢复，recoverColors），以及样式签名 sig（fontFamily、fontSizePt、color、bold、italic）。
• mergeRuns() 把同一行、同一样式、间距小于 fontSize * maxGapFactor 的 RawRun 合并为一个 Unit（文本单元），每个 Unit 获得唯一 tid（如 p3-0），并计算 top（baselineTop - ascent * fontSize）。
• freezeStyles() 把所有 Unit 按样式签名分组，生成 CSS 类名（如 .s1）和 css 字符串，供后续浏览器渲染或原生绘制使用。

输出 PageExtract 包含：pageNumber、widthPt、heightPt、units[]、css、html（由 buildPageHtml 构造的绝对定位 HTML）。

2. AI 修改：分块调用 DeepSeek（src/ai-editor.ts、src/prompts.ts）

• AiTextEditor 接收提取的 EditableUnit[]（只保留 tid 和 text），按字符数分块（packChunks，默认每块不超过 18,000 字符）。
• 每块构造提示：系统提示（TEXT_EDIT_SYSTEM_PROMPT）要求只输出 {"items":[{"tid":"...","text":"..."}]}，条目数与输入完全一致，不能新增/删除 tid，未改条目原样返回。
• 调用 createDeepSeekChatFn（src/index.ts）：向 https://api.deepseek.com/chat/completions 发送 POST，设置 temperature=0.1、response_format: {type: "json_object"}。
• AI 返回的原始字符串经 parsePatchObject() 解析：先去除代码围栏（代码围栏 ```），再提取 JSON 对象，修复常见的尾部逗号错误。如果解析失败或缺少 items 数组则抛出错误。
• 每块并行处理（Promise.all），结果合并到 merged Map。完成后执行 reconcilePatches()（src/validator.ts）：
  • 严格模式（strictTids=true）下，若 AI 返回未知 tid 或缺失 tid 直接抛错；
  • 非严格模式下，未知 tid 被丢弃，缺失 tid 用原文补回（missingTidsUseOriginal 默认 true）。
• 最后应用术语表（Glossary，由 normalizeGlossary 处理为 from→to 数组），对每条修改后的文本执行 applyGlossary()（字符串替换）。

3. 溢出控制与文本校验（src/validator.ts、src/util.ts）

在将 AI 修改应用到 Unit 前，执行以下安全校验：

1. sanitizeText()：
   • 移除 HTML 标签（...>）；
   • 移除控制字符（\u0000-\u0008、\u000b、\u000c、\u000e-\u001f）；
   • 拒绝空文本；
   • 拒绝长度膨胀超过原长 3 倍 + 16 字符（防止 AI 跑飞）。
2. overflowAction()（根据配置 OverflowPolicy）：
   • clip：若新文本宽度超过 unit.width * 1.06 + 2，设置 unit.clip = true（绘制时截断）；
   • wrap：设置 unit.wrap = true（绘制时换行）；
   • reject：若溢出直接拒绝，记录到 rejected 列表，不修改该条；
   • shrink（默认）：计算缩放比例 unit.fontSize * (unit.width / estWidth)，若缩放后字号 ≥ minFontSizePt（默认 6pt）则设置 fontSizeOverride；否则设置为最小字号并同时启用 clip。
3. measure()（fonts-resolver.ts）：通过 font.widthOfTextAtSize()（pdf-lib + fontkit）计算新文本在当前字号下的实际宽度（pt）；若字体未嵌入则回退到 text.length * size * 0.6 估算。

4. 叠加绘制：两种渲染模式（src/native-renderer.ts、src/browser-renderer.ts）

插件支持两种渲染模式，由 renderMode（默认 "native"）控制：

Native（原生 pdf-lib 直绘，零浏览器依赖）：

• NativePageRenderer.renderPatches() 对每个被修改的 Unit 执行：
  1. 用 FontResolver.resolveA() 解析字体（标准字体映射到 Helvetica/Times/Courier，中文自动探测系统字体如 simhei.ttf / msyh.ttc / NotoSansCJK-Regular.ttc，或从配置 fonts.cjk 加载）；
  2. 测量新文本宽度，计算遮盖矩形（白色 patchColor，默认 #ffffff），在原位置画白色矩形遮住旧文字；
  3. 画新文字：若 wrap 启用则分行绘制（wrapByMeasure），若 clip 启用则截断（ellipsizeByMeasure）；若 fontSizeOverride 有值则使用缩小后的字号；
  4. 对粗体字体启用 fakeBold 时，在原位置偏移 0.02 * size 再画一次（模拟加粗）。
• 绘制在加载的原始 PDFDocument（PDFDocument.load）上，通过 doc.getPage() 获取页面对象，修改后 doc.save() 输出新 PDF 字节流。
• pdf-ops.ts 提供 replacePages()：当仅部分页修改时，把修改页的 Uint8Array 与未修改页的原页合并到新文档，保留原文档元数据（标题、作者、创建日期等）。

Browser（浏览器渲染，通过 Puppeteer）：

• BrowserRenderer 启动无头 Chrome（puppeteer-core，需配置 browserExecutablePath），并发限制由 browserConcurrency 控制（默认 2）。
• 对修改页构造 HTML：buildPageHtml() 生成绝对定位的 .txt span（样式从 freezeStyles 提取），若有背景图则插入 .bg 图片。被修改的单元在原位置上方叠加 .mask（白色矩形）遮盖旧字，再在同位置放新 .txt。
• renderPage() 用 page.setContent() 加载 HTML，等待字体就绪（document.fonts.ready），然后 page.pdf() 打印为 PDF（margin: 0、printBackground: true），返回 Uint8Array。
• relayout（重排版）模式下：先提取全文构建 FlowBlock（按字号中位数分类：heading、subheading、body、caption），再用 buildFlowBlocks() 生成流式 HTML，填充到 templates.ts 定义的三种模板（academic 双栏、mobile 手机单栏、briefing 商务简报），同样通过浏览器打印为 PDF，并通过 replaceEntireDocument() 替换原文档内容（保留元数据）。

5. 整体流程控制（src/pipeline.ts、src/index.ts）

• StyleLockedEditor.open() 初始化：加载 PDF、创建 StyleLockedExtractor、创建 AiTextEditor、设置默认配置（batchSize=10、overflow={mode:"shrink",minFontSizePt:6}、patchColor="#ffffff"、renderMode="native"）。
• editPage()：提取单页 → AI 修改 → 应用溢出控制 → 原生/浏览器渲染 → 返回新 PDF 字节。
• editDocument()：批量逐页处理：先预取第一批（并发 extractConcurrency，默认 4），每批调用 AI（分块并行），每页应用溢出控制后收集修改页；原生模式下把所有修改页的工作推迟到最后统一绘制（drawPatchedPages），浏览器模式下每页独立渲染后合并（replacePages）。过程中通过 onProgress 回调报告阶段（extract → ai → render → skip → merge / error）。
• previewPage()：仅提取并返回可编辑单元列表，不执行修改，用于预览。
• relayout()：提取全部页 → 构建流式块 → 按模板渲染新文档 → 替换原文档内容。

6. 字体与中文支持（src/fonts-resolver.ts）

• 标准字体：helvetica（无衬线）、times（衬线）、courier（等宽），按 bold / italic 组合映射到 pdf-lib 的 StandardFonts（如 HelveticaBold、TimesRomanItalic）。
• 中文（CJK）：检测文本中是否含 \u2E80-\u9FFF 等字符。若含 CJK 且无嵌入字体，则自动从系统路径探测（Windows simhei.ttf / msyh.ttc、macOS Songti.ttc / PingFang.ttc、Linux wqy-microhei.ttc / NotoSansCJK-Regular.ttc），通过 fontkit 嵌入到 PDF。若自动探测失败且未配置 fonts.cjk，则抛出错误。
• 自定义字体：支持 fonts.customs（按字体族名匹配）和 fonts.cjk（专门用于中文）。
• 字体缓存：FontResolver 对每个解析后的字体对象 (PDFFont) 做缓存（fontCache），避免重复嵌入。

整个过程纯 JavaScript 完成：提取和原生绘制依赖 pdf-lib + pdfjs-dist，浏览器模式额外依赖 puppeteer-core（系统 Chrome/Edge 可执行文件）。不需要打开真实浏览器窗口，原生模式完全无浏览器依赖。

测试与基准

npm test              # 98 个测试：单元 + 集成（vitest）
npm run bench         # 编辑能力基准：准确性 / 版式保持 / 完整性 / 性能
npm run fetch:samples # 下载公开样例 PDF（可选）

基准支持两种模式：oracle（脚本化理想 AI，度量管线保真上限）与 DEEPSEEK_API_KEY=… npm run bench -- --llm（真实 LLM 端到端打分）。报告输出至 test/benchmark/results/report.md。详见 test/README.md。

许可证

MIT