dsh-pdf-edit

English | 中文

版本：v0.2.2（当前） | 需要 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.2.2（2026-08-23 发布）。主要更新：README 增加 AI Agent 操作手册、removeSubheadings() 完整实现、关键编程方法（getExtract / drawPatchedPages / openNativeDoc）公开为公共接口。

遇到 "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 调用函数
);

依赖说明

• 核心：pdf-lib（PDF 操作）+ pdfjs-dist（文本提取）
• 原生绘制：fontkit（字体嵌入与测量）
• 浏览器模式：puppeteer-core（需 browserExecutablePath 指向系统 Chrome/Edge）
• 中文字体：自动探测 simhei.ttf / msyh.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 流程。

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

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

更新记录

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