dsh-pdf-edit

English | 中文

🧩 已接入 dsh-std 生态（Community v0.15）：本插件随包提供 dsh-plugin.json 静态清单与标准 FacetModule 入口（dist/std/host.js），可被 @dsh-std/adapter-dsh 等 dsh-std 标准宿主直接装载，不依赖任何 @deepseek-ai/* 官方包；同时保留 cordis 直连入口。两条入口共用同一套工具实现，编辑行为完全一致。

版本：v0.4.5（当前） | 需要 Node >= 22；兼容 dsh >= 0.1.1-rc.2（cordis 直连）与 dsh-std Community v0.15 宿主

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.4.5（2026-08-25 发布）。主要更新：彩色背景不再留白块（native 直绘按内容流采样实际背景色作补丁底色）、tid 合并阈值自适应排版密度、大文档内存 LRU 淘汰、字体解析结果缓存提速批量编辑。v0.4.3：parsePatchObject 按 JSON 解析错误位置截断，彻底处理模型尾部任意说明文字。

dsh-std 标准生态适配（v0.4.0 新增）

本插件同时是 dsh-std Community v0.15 标准插件（dsh-std / dsh-ecosystem-spec）：宿主通过静态 dsh-plugin.json 在不执行插件代码的前提下完成兼容性判定，运行期经 adapter 层与 dsh 本体通信——上游接口变更被 adapter 单点吸收，插件免维护。

两种装载方式

# 标准生态宿主内安装（adapter 会扫描 profile 依赖中的 dsh-plugin.json）
dsh plugin --profile web add @dsh-std/adapter-dsh
dsh plugin --profile web add dsh-pdf-edit

std 宿主下的配置（环境变量）

std 协议没有 cordis config 注入，配置改从环境变量读取：

说明：dsh-std tool/model 协议 v1alpha1 尚未向插件开放宿主 LLM 推理通道，因此 std 宿主下 AI 精修暂走 DeepSeek API 直连（Key 必填）；工具注册、生命周期、清理语义全部走标准协议。

清单要点

• $schema: urn:dsh-std:community-draft:dsh-plugin:0.15，manifestVersion: 0.15
• 组件 ID：io.github.whatsmore-nf.dsh-pdf-edit
• 5 个工具以 contributes["x-tools"] 声明为 tools.dsh/v1alpha1 Tool 扩展，activation 时逐一发布本地 ToolHandler
• 不声明任何 required 契约与权限 → 与任意 std 宿主协商即兼容

遇到 "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.4.5

依据 v0.4.3 全面审查报告完成的四项 P0 + 两项 P1 改造（准确性 / 稳定性 / 性能）：

• 背景色采样替代白补丁（P0，视觉保真）：native 直绘新增内容流背景采样——扫描页面填充矩形（含 pdf.js 分解的 re 路径与 CMYK/灰度填充），按画家算法取补丁位置最上层背景色作为遮盖底色。彩色背景合同、带底纹证书上不再出现"白块"；图片等无法采样的区域自动回退 patchColor。新配置项 autoPatchColor（默认开启，设 false 强制用 patchColor）。纯 JS 实现，零浏览器依赖
• tid 合并阈值自适应（P0，准确性）：mergeRuns 不再硬编码 0.45/0.18 系数——按同页相邻文本项间隙中位数动态计算（合并上限 clamp [0.3, 0.8]、空格下限 clamp [0.1, 0.4]），学术双栏紧凑排版不再跨栏误合并，宽字距标题不再被拆散；显式传入 maxGapFactor/spaceGapFactor 时仍优先显式值（向后兼容）
• 提取缓存 LRU 淘汰（P0，稳定性）：extractCache 加 20 页容量上限（LRU），500+ 页大文档编辑不再全量驻留内存导致 OOM 风险；新增通用 LRUCache 工具类
• 字体解析结果 LRU 缓存（P1，性能）：FontResolver.resolveA 结果按「族|字重变体|CJK/标准」缓存（128 条），批量 applyPatches 高频调用免重复解析，批量编辑耗时降低
• CID 字体乱码检测降级（P1，可用性）：提取阶段检测私用区/U+FFFD 占比超 50% 的页面（Type0/CID 字体缺 ToUnicode CMap 的典型症状），记入 warnings 提示该页 AI 编辑结果可能不可靠，不中断其余页面
• 测试 +14（背景采样单测、彩色背景端到端补丁色断言、自适应阈值行为、LRU、乱码检测），全套 164 例通过

v0.4.3

• parsePatchObject 解析再加固：新增「按 JSON 解析错误位置截断」（tryParseJsonLenient）——模型在 JSON 值后附带任意说明文字（包括含 {}/[] 的尾注）都能正确解析出 items
• 新增 2 条回归测试（尾注含花括号/方括号、任意垃圾尾随），全套 150 例通过

v0.4.2

• 修复 AI 精修（pdf-edit-page / pdf-edit-document）在 LLM 返回「顶层 JSON 数组 + 尾部说明文字」时的解析失败（Unexpected non-whitespace character after JSON）：parsePatchObject 改为候选式容错解析——原样 / 花括号截取 / 方括号截取依次尝试，且只接受带 items 的候选（避免误吞数组内单对象）
• 新增 2 条回归测试（数组+尾注、对象+尾注含花括号），全套 148 例通过

v0.4.1

• 修复 std 生态下 insert 的标准字体 WinAnsi 崩溃：inserter.drawLine 对标准字体（WinAnsi）run 绘制前先过 toWinAnsiSafe——−/—/“” 等字符不再抛 WinAnsi cannot encode（v0.3.0 潜在 bug，std 默认字体路径触发）
• pdf-edit-insert 自动派生字体族：从 fonts.customs 自动取第 1 项为正文 family、第 2 项为 titleFamily；配置了独立加粗字体时自动 fakeBold: false，消除标题双绘导致的文本提取重复
• preview 免 LLM：只读预览不再强制要求 LLM Key（传 no-op chat）
• std 宿主新增 DSH_PDF_EDIT_FAKE_BOLD 环境变量；DSH_PDF_EDIT_FONTS_CJK/_CUSTOMS/_FALLBACKS 补齐（化学式上下标回退在 std 宿主可用）

v0.4.0

• 适配 dsh-std Community v0.15 生态：包根新增静态清单 dsh-plugin.json（manifestVersion: 0.15），新增标准 FacetModule 入口 src/std/host.ts（编译为 dist/std/host.js）——经 @dsh-std/adapter-dsh 等标准宿主装载时把 5 个工具发布为 tools.dsh/v1alpha1 Tool 扩展 + 本地 ToolHandler，生命周期/清理走标准 activation scope
• 解除官方包硬依赖：@deepseek-ai/dsh-tools peerDependency 改为 optional——标准宿主下插件零 @deepseek-ai/* 依赖，未来 dsh 上游破坏性变更由 adapter 层单点吸收；cordis 直连入口原样保留并在缺包时报错带指引
• std 宿主配置改用环境变量（DSH_PDF_EDIT_* / DEEPSEEK_API_KEY），见 README「dsh-std 标准生态适配」章节
• 工具参数 schema 升级为标准 JSON Schema（顶层 required 数组）；工具实现函数（pdfEditPreview 等）公开导出供两种入口复用
• 新增集成测试 test/integration/std-facet.test.ts（9 例：manifest 一致性、handler 发布契约、端到端执行、越界拦截、重复激活恢复），全套 146 例通过

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 等，插件都会自动跟随，零配置即可使用

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