📖 dsh-plugin-text-translation

DeepSeek Harness (DSH) 文本与文档翻译插件：为 DSH Agent 提供标签防爆遮罩、
多格式文本提取/切片与无损回填组装能力，覆盖游戏脚本与长文档两类场景。
翻译本身由 DSH Agent 编排完成——可借助 DSH 内置的 subagent / subagent_fork /
workflow 工具并行翻译各批次，本插件只负责"提取"与"装配"这两个原子环节。

• 📦 GitHub: https://github.com/1738348785/dsh-plugin-text-translation
• ✅ 实测环境：DSH 0.1.0-rc.6（headless 与 web profile 均已验证）

---

🌟 核心特性

• 🛡️ 标签防爆遮罩 (Tag Protector)：自动识别并保护 RPG Maker (\c[1], \v[1], \n)、
  Unity/RichText (<color>, <b>)、变量占位符 ({player}, {0}, %s) 与 Ren'Py 标签，
  翻译后 100% 精确无损还原。
• 📑 全格式支持：
  • 游戏脚本：Mtool JSON (ManualTransFile.json)、Translator++ 表格 (XLSX/CSV)、
    Ren'Py (.rpy)、字幕 (SRT/ASS/VTT)、Gettext (.po)。
  • 长文档：PDF、Word (.docx)、Markdown、HTML、TXT。
• 🧩 原生集成 DSH：
  • 导出标准的 dsh.bundle Manifest（dsh.bundle.patch），随 dsh plugin 安装后自动加入
    profile 的 bundle 层。
  • 注册 extract_text、assemble_text、inspect_text_file 三个工具供 DSH Agent 调度。
  • Python 引擎（python/ 目录）随插件一起分发，安装即用，无外部路径依赖。

---

📦 安装与使用

方式一：从 GitHub 安装（推荐）

dsh plugin --profile demo add github:1738348785/dsh-plugin-text-translation

dsh 会拉取仓库、自动把插件的 cordis.patch.yml 追加进 profile 的 bundle 层。
（GitHub 安装实测通过：依赖走 pnpm store，无符号链接解析问题。）

方式二：安装到 web profile（让 GUI 插件页可见）

DSH Web 的「设置 → 插件」清单显示的是当前运行的 profile 实际加载的插件。
要让 GUI 里看到并管理本插件，需要装进 web profile 并重启：

dsh plugin --profile web add github:1738348785/dsh-plugin-text-translation
# 重启 web（Ctrl+C 后重新 dsh web），刷新页面即可在插件清单中看到 text-translation

方式三：本地源码安装（开发调试）

dsh plugin --profile demo add ./dsh-plugin-text-translation

⚠️ 注意：pnpm 对本地路径包使用符号链接（junction），而 Node ESM 会按符号链接的
真实路径解析依赖——插件代码 import '@deepseek-ai/dsh-tools' 时会从插件源码目录
向上查找，找不到 profile 里的依赖包并报 ERR_MODULE_NOT_FOUND。解决办法（Windows）：
把依赖树以 junction 暴露给插件目录（一次即可）：

# demo profile 有自己的依赖树时：
New-Item -ItemType Junction -Path ".\dsh-plugin-text-translation\node_modules" `
         -Target "$env:USERPROFILE\.dsh\profiles\demo\node_modules"

# web profile 的依赖树在 DSH 安装锚点（npx 缓存）时，按包名逐项链接：
New-Item -ItemType Junction -Path ".\dsh-plugin-text-translation\node_modules\@deepseek-ai" -Force
New-Item -ItemType Junction -Path ".\dsh-plugin-text-translation\node_modules\@deepseek-ai\dsh-tools" `
         -Target "$env:LOCALAPPDATA\npm-cache\_npx\<hash>\node_modules\@deepseek-ai\dsh-tools"
# 同理链接 cordis、schemastery

方式四：--patch 覆盖层快速调试（不安装）

dsh --profile demo --patch ./dsh-plugin-text-translation/cordis.patch.yml

---

⚠️ 新 profile 初始化注意事项

以下两条是 DSH 环境在创建新 profile 时的已知问题（与本插件无关），首次把插件装进新 profile 时可能遇到：

1. npm registry 的 latest tag 指错版本：@deepseek-ai/dsh-base 的 latest 是旧版
   0.0.1-rc.1（其依赖 dsh-fs-policy 不存在于 registry），安装会失败。必须显式指定版本：

   dsh plugin --profile demo add @deepseek-ai/[email protected] @deepseek-ai/[email protected]
   

2. pnpm 11 默认阻止依赖的 build scripts：首次安装报 ERR_PNPM_IGNORED_BUILDS 时，
   把 profile 下 pnpm-workspace.yaml 中 allowBuilds: 段的 set this to true or false
   改为 true，再 dsh plugin --profile demo install。

---

🛠️ 注册的 DSH 工具 (Tools)

工具名称	说明	入参
extract_text	提取文件中的可翻译文本，应用标签遮罩并按行数切片；建议传 output_json 落盘避免大文本进入对话	input_file (必需), output_json, batch_size
assemble_text	将翻译结果还原标签后无损重组回原始格式文件	original_file (必需), translations_json (必需), output_file (必需)
inspect_text_file	轻量检查：格式、条目数、说话人、标签分布（不输出全文）	file_path (必需)

---

⚙️ 插件配置项 (Config Schema)

在 profile 的 cordis.patch.yml（或 --patch 覆盖层）中可自定义：

- insert:
    - id: text-translation
      name: dsh-plugin-text-translation
      config:
        pythonPath: python     # Python 解释器路径 (默认: python)
        batchSize: 25          # 单批次切片行数大小 (默认: 25)

---

🤖 推荐的翻译工作流（利用 DSH 子代理）

DSH 提供完整的子代理能力（ctx.subagents 服务 + 模型侧 subagent / subagent_fork
工具 + workflow 批量编排），Agent 可以这样编排一次翻译任务：

1. 摸底：调用 inspect_text_file 了解格式、条目数与标签分布；
2. 提取：调用 extract_text（传 output_json 保存分块 JSON）；
3. 并行翻译：对每个批次分别启动一个子代理（subagent），或用一个
   workflow 脚本对全部批次做 fan-out 翻译，结果合并为一个 translations JSON；

   💡 子代理结果去重：实测中子代理完成通知可能重复投递，主 Agent 可能把
   "重复通知"误当作新结果处理。建议在任务提示词中明确："子代理结果按 id 合并，
   已合并的 id 直接忽略重复通知"。

4. 回填：调用 assemble_text 无损写回本地化文件。

---

🐍 Python 依赖

依赖清单见 python/requirements.txt，分三层：

• 必需（提取/遮罩/切片/组装全链路）：typer、pydantic

  pip install -r python/requirements.txt
  

• 可选 · 格式解析（按需格式启用）：
  • XLSX → openpyxl
  • PDF → PyMuPDF
  • DOCX → python-docx
  • HTML → beautifulsoup4
  • （Markdown / TXT / 字幕 / Ren'Py / JSON 等为纯文本解析，零额外依赖）
• 可选 · 独立 LLM 流水线（仅当绕过 DSH Agent、直接调用
  UniversalLLMClient / MultiAgentTranslatorPipeline 时）：openai、httpx

插件运行本身只依赖第一层；未装可选依赖时，仅对应功能报错，其余不受影响。

---

🛠️ 开发

dist/ 已提交到仓库（插件运行时加载 dist/index.js，clone 即用）。修改源码后重新构建：

npm install     # 安装 typescript 等开发依赖
npm run build   # tsc 编译到 dist/

测试

# Python 引擎冒烟测试（extract / inspect / assemble 无损断言）
pip install -r python/requirements.txt
python -m unittest discover -s test -v

# TypeScript 类型检查（需先 npm install）
npx tsc --noEmit

CI（GitHub Actions）会自动跑以上两项：tsc --noEmit 类型检查 + Python 3.11/3.13
矩阵冒烟测试。

同步上游引擎

python/core/ 是 multi_agent_translator 引擎的随包快照（LLM 相关模块为可选导入）。
上游改动后运行：

# 默认：只同步 core/（local_helper.py 保留插件定制：UTF-8 输出修复 + inspect 命令）
powershell -File scripts/sync-python-engine.ps1

# 同时覆盖 local_helper.py（CLI 层有冲突时需手动合并）
powershell -File scripts/sync-python-engine.ps1 -IncludeHelper

# 上游不在默认位置时指定路径
powershell -File scripts/sync-python-engine.ps1 -Source C:\path\to\multi_agent_translator

---

📄 License

MIT