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）
适合什么场景
| 场景 | 举例 |
|---|
| 术语统一 | 全文把「帐号」改成「账号」、「数据中台」改成「数据平台」 |
| 错别字修正 | 让 AI 扫一遍，自动修正拼写和语法错误 |
| 合同/报告批量修改 | 多页文档统一替换人名、金额、日期等 |
| 格式转换 | 把散乱的 PDF 重新排版成学术论文双栏、手机阅读单栏、商务简报等版式 |
| 往 PDF 里补内容 | 把 md/笔记作为新页插到指定页之后（pdf-edit-insert，无需 LLM）：自动排版横幅标题/正文/公式框、跨页断页、化学式上下标缺字自动回退 |
安装
# 通过 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 单点吸收，插件免维护。
两种装载方式
| 方式 | 宿主 | 入口 | 依赖 |
|---|
| 标准生态（推荐） | 支持 dsh-std 的宿主（如经 @dsh-std/adapter-dsh / dsh-TUI） | 包根 dsh-plugin.json → facets.host.entry（dist/std/host.js） | 无需任何 @deepseek-ai/* 包 |
| cordis 直连（旧） | DeepSeek Harness 原生 profile | cordis.patch.yml + apply(ctx, config) | @deepseek-ai/dsh-tools（peerDep，现为 optional） |
# 标准生态宿主内安装（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 注入，配置改从环境变量读取：
| 环境变量 | 说明 |
|---|
DEEPSEEK_API_KEY | LLM Key；AI 精修必需（预览/插入不需要）。也可用 DSH_PDF_EDIT_API_KEY 覆盖 |
DSH_PDF_EDIT_ALLOWED_ROOTS | 路径白名单，按平台路径分隔符拼接（默认当前工作目录） |
DSH_PDF_EDIT_PROVIDER / _MODEL / _BASE_URL | 模型路由（直连 API 时使用） |
DSH_PDF_EDIT_RENDER_MODE | native（默认）或 browser |
DSH_PDF_EDIT_BROWSER_EXECUTABLE / _BROWSER_CONCURRENCY | 浏览器模式选项 |
DSH_PDF_EDIT_PATCH_COLOR / _STRICT_TIDS / _MISSING_TIDS_USE_ORIGINAL / _RECOVER_COLOR / _STRICT_COLOR / _OVERFLOW_MODE / _MIN_FONT_SIZE_PT | 其余编辑行为开关 |
说明：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 操作手册（隐藏规则）
在使用本插件前，请先确认以下三个“隐藏规则”——它们在源码中存在，但不在工具接口文档中直接说明：
| 规则 | 位置 | 影响 | 绕过方式 |
|---|
路径白名单 allowedRoots | src/path-guard.ts | 工具调用 (pdf-edit-preview / pdf-edit-document) 直接失败（文件不存在或不在允许目录） | 编程接口 StyleLockedEditor.open() 仍需配置 allowedRoots；或直接 node -e 调用内部模块绕开工具守卫 |
sanitizeText 拒收空字符串 | src/validator.ts:26 (t.length === 0 → {ok:false}) | editDocument('去掉所有小标题...') 若 AI 返回 "" 会被拒收，missingTidsUseOriginal: true 回填原文 | 直接操作 unit.text = ''，再手动调用 drawPatchedPages()（见示例） |
依赖 ctx.llm / DEEPSEEK_API_KEY | src/index.ts:96-121 | 工具接口依赖 DSH LLM 服务或环境变量；无配置时抛错 | 编程接口可传入自定义 chatFn（如 setChatFn），完全脱离工具调度 |
编程接口简要示例
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 选哪个接口？（快速决策表）
| 任务类型 | 推荐接口 | 关键方法 | 需要避开的限制 |
|---|
| 修正错别字 / 统一术语 | 工具 pdf-edit-document 或编程 editDocument() | editDocument('指令') | 无（标准流程） |
| 预览可编辑单元 | 工具 pdf-edit-preview 或编程 previewPage() | previewPage(n) | 无 |
| 删除文字（设空） | 编程接口 removeSubheadings() 或手动操作 | getExtract → unit.text='' → drawPatchedPages | sanitizeText 拒收空字符串；editDocument 会回填 |
| 版式重排 | 工具 pdf-edit-relayout 或编程 relayout() | relayout('academic'|'mobile'|'briefing') | 无 |
| 往 PDF 里补内容 | 工具 pdf-edit-insert 或编程 insertPages() | insertPages(bytes, insertions, opts) / parseMarkdownBlocks() | 无 LLM 依赖；回退字体不做子集化 |
| 化学式上下标混排 | 编程接口 | resolver.resolveRuns(text, family, bold, italic) / resolver.hasGlyph(...) | 需配置 fonts.fallbacks |
| 自定义字体 / 颜色修复 | 编程接口 + 配置 fonts | StyleLockedEditor.open(pdf, chat, { fonts }) | 工具接口不暴露字体配置细节 |
💡 路径解析提示：若 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 等，插件都会自动跟随，零配置即可使用
历史版本
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
