dsh-pdf-translate
DSH 插件：通过 DeepSeek 或任何兼容 OpenAI 的 API 翻译文本型 PDF，同时保留布局、字体、图像和链接（输出可编辑 PDF，每项任务最多 50 页）。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:l2685209197/dsh-pdf-translate#31d6cc0dd0207fd6d6c86ac69605a9d8e95376b2Pdf Translate 以 dsh-pdf-translate 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
DSH（DeepSeek Harness）插件：用用户自有的 DeepSeek（或任意 OpenAI 兼容 API）对文本型 PDF 进行全文翻译，输出保留版式、字体样式、图片与链接的可编辑 PDF（文本可选中、可复制）。
当前仅支持文本型 PDF（有文本层）。扫描版（需 OCR）不在 v1 范围。
role('secret') 保护，绝不写入会话日志。# 1. 安装 Python worker 依赖（pymupdf + pytest；-ExecutionPolicy Bypass 因 Windows PowerShell 5.1 默认拦截脚本）
powershell -ExecutionPolicy Bypass -File scripts/install-worker.ps1
# 2. 安装 TS 依赖并构建
pnpm install
pnpm run build
# 3. 挂载到 DSH 桌面 profile
# 发布后：dsh plugin --profile desktop add dsh-pdf-translate
# 开发期：dsh plugin --profile desktop add <本地仓库路径>
# 4. 重启 DSH Desktop → 设置 → 插件区 →「PDF 翻译」卡片填入 API Key → 保存
# 5. 让 agent 翻译，或直连 CLI：
node scripts/translate-cli.mjs <input.pdf> <outputDir> 1 20 en→zh
| 组件 | 版本 |
|---|---|
| Node.js | ^22.19 || >=24 |
| pnpm | 11.x |
| Python | 3.14（PyMuPDF 1.28.2 已验证） |
| DSH | 桌面版（Harness home %USERPROFILE%\.dsh） |
translate_pdf 工具（agent 可调用）：
| 参数 | 必填 | 说明 |
|---|---|---|
input | ✅ | 输入 PDF 绝对路径 |
outputDir | ✅ | 输出目录 |
pageStart / pageEnd | 可选 | 页面范围（1-based），默认全文；单次任务范围 ≤ 50 页（大书可分页段多次翻译） |
langPair | 可选 | 语言对，如 en→zh；默认取配置 |
termbase | 可选 | 术语表文件路径（JSON/TXT） |
| 配置项 | 默认 | 说明 |
|---|---|---|
apiKey | 空 | DeepSeek API Key（secret，不入日志） |
baseUrl | https://api.deepseek.com | OpenAI 兼容端点 |
model | deepseek-chat | 模型名 |
langPair | en→zh | 默认语言对 |
concurrency | 6 | 并发请求数（1-16） |
maxRetries | 3 | 每请求最大重试（429/5xx/超时，指数退避 + Retry-After） |
timeoutMs | 60000 | 单请求超时 |
termbasePath | 空 | 默认术语表路径 |
pythonBin | python | Python 解释器 |
设置卡片（DSH 桌面设置页 → 插件区）以 zh/en 双语渲染：文案经 ctx.locale 注册 settings.pdfTranslate 命名空间词典，跟随应用全局 Language 切换即时中英互换；视觉使用 --dsw-* 主题 token（明暗自动适配）。API Key 为 secret 角色：保存后不再回显值，显示为「已配置」。输入框带可编辑视觉标识（浅灰底色 + 可见边框 + 聚焦蓝环 + 每字段示例占位符）。
仓库内置两个脚本直接复用生产流水线（与 translate_pdf 工具完全同路径）：
# 干跑：只提取段落统计，不调用 API（预估段数/成本）
node scripts/extract-dryrun.mjs <input.pdf> [start0Based] [end0Based]
# 真实翻译（需要 DEEPSEEK_API_KEY 环境变量；与设置卡片同一字段）
node scripts/translate-cli.mjs <input.pdf> <outputDir> [pageStart1Based] [pageEnd1Based] [langPair]
产物：<outputDir>/<书名>.<langPair>.pdf + <outputDir>/.translate-cache.json（断点续传缓存，重跑同段落直接命中）。
JSON：
[
{ "src": "API", "dst": "应用程序接口", "locked": false },
{ "src": "GPT", "dst": "GPT", "locked": true }
]
TXT（每行 原文,译文；locked 不支持）：
API,应用程序接口
locked: true 表示专名/标识符保留原文不翻译。
┌──────────────────────────────────────────────────────────────┐
│ DSH Cordis 插件（TypeScript） │
│ translate_pdf 工具 → runPipeline（校验/编排/缓存/报告） │
│ ├─ DeepSeek 客户端（并发池 × 批处理 × 重试/退避/取消） │
│ └─ PdfWorker（spawn `python -m worker.main`，stdio 逐行 JSON）│
├──────────────────────────────────────────────────────────────┤
│ Python worker（仅依赖 PyMuPDF） │
│ textlayer → 文本层检测（无文本层报错） │
│ extract → 段落提取（列检测→聚类→分类→置信度降级） │
│ rebuild → 两阶段重建：redaction 删原文 → insert_textbox 写译文 │
└──────────────────────────────────────────────────────────────┘
worker 协议（stdio 逐行 JSON）：请求 {"id","cmd","payload"}；响应 {"id","ok","result"|"error"}；启动首行 {"ready":true}。
关键设计：
images/graphics=NONE, text=REMOVE）删除本页全部原文，再统一 insert_textbox 按段落锚点写回（逐段「删→写」会让后段 redaction 误删前段已写译文）；几何由重建时重提取原文档按 id 匹配（载荷只传 {id, text}）。src/ TS 插件
types.ts 协议类型（与 worker JSON 镜像）
translate/ 分块器/提示词/DeepSeek 客户端/并发池/缓存
worker.ts Python worker 进程管理
pipeline.ts 流水线编排
tool.ts translate_pdf 工具
index.ts apply 入口
client/ 设置卡片
worker/ Python worker
main.py stdio 协议分发
model.py 数据模型（协议唯一来源）
extract.py 文本提取 + 段落识别
rebuild.py redaction + 写入
tests/ pytest（41 个用例）
tools/pdf-render/ PDFium 渲染对比 QA 工具（C++，链接现有 pdfium.lib）
# Python worker（41 个用例：协议/提取/聚类/分类/置信度/黄金版式/重建）
python -m pytest worker/tests -q
# TS 模块（73 个用例：分块/提示词/客户端/并发池/缓存/流水线/工具/入口/设置卡片/jsdom 渲染/E2E）
pnpm exec vitest run
# 类型检查
pnpm exec tsc -p tsconfig.json --noEmit
DSH Desktop 内置社区市场（目录源：DSH 1024Store / DSH Marketplace(qilewl.net) / dshfind）。目录条目 = GitHub 仓库元数据 + dsh plugin --profile <name> add <npm包> 部署命令；可安装前提：npm 官方 latest 稳定版本 + 有效的 dsh.bundle.patch。本仓库已做好发布前置：
package.json：已声明 dsh.bundle.patch: "cordis.patch.yml"（插件进入 profile bundle 层）、license: MIT、description/keywords，无 private；prepublishOnly 自动构建。npm login → pnpm publish --access public；随后把仓库推送到 GitHub（公开，补 topics 分类），再到市场站点（qilewl.net 等）按其收录流程提交。insert 行（loader 树重复 id 会启动失败）。table:{row,col} 元数据字段已声明但未填充（v2）。import pymupdf as fitz 是强制约定：1.28.2 的 fitz shim 会在 import 时向 stdout 打印弃用警告，污染 stdio 行协议。@deepseek-ai/dsh-tools/dsh-settings 的 0.1.2-alpha.1 仅在桌面应用安装（私有来源，无 .d.ts）；运行时经 $DSH_HOME/profiles/node_modules 回退解析到应用实例；开发期类型用注册表 0.1.1-rc.2（类型漂移已接受）。python -m worker.main（cwd = 仓库根）启动——脚本形式 python worker/main.py 无法 from worker import ...。python -m pytest worker/tests -q 与 pnpm exec vitest run 两套测试。tools/pdf-render）：原文/译文第 1 页渲染成功，墨水 bbox 左缘一致（x=145px=72pt），无重叠、无错位。page_index * 1_000_000 偏移，E2E 逐页断言守卫。maxPages 作用于翻译范围长度而非全书页数。