前言¶
在 DeepSeek Harness（DSH）里处理韩文行政、技术类文档时，常见痛点是：源文件是 한글（HWP/HWPX），模型能翻译正文，却难以在不破坏表格、项目符号和缩进的前提下写回。手工复制粘贴或整页导出再贴回，既慢又容易丢结构。
下面介绍的 dsh-hwp-translate 把「抽取段落 → 由当前会话模型翻译 → 写回文件」收成一组本地工具；默认路径不需要 API Key，翻译由会话模型完成，插件负责与 Yeobaek HWP Translator 配套的抽取与回写。
这是什么¶
dsh-hwp-translate 是社区维护的 DSH 插件（维护者 Sanshui258，GitHub：Sanshui258/dsh-hwp-translate）。在 SkillHub 目录中归类为「联网工具」；README 中同时保留了需自备 Key 的旧式联网接口，推荐流程以本地三工具为主。
插件版本在 package.json 中为 0.3.0，要求 DSH >=0.1.0-rc.6，运行环境限定 Windows（win32）。插件本体采用 MIT 许可证；随包分发的 HWP_Translator.exe 适用作者声明的个人非商业使用许可，安装前宜阅读仓库中的 PROVENANCE.md 与许可证说明。
核心功能¶
插件向 DSH 暴露三个工具，职责如下。
| 工具 | 作用 | 是否联网 |
|---|---|---|
hwp_extract(path, offset?, limit?) |
从文档抽取待翻段落（id + 原文） | 否 |
hwp_apply(path, translations, out_dir?) |
将 {id: 译文} 写回文档 |
否 |
hwp_translate(path, target?, out_dir?) |
旧接口：由 exe 自行调 API（需自带 Key） | 是 |
设计要点：
- 版式保留：目标是在中文版中保留表格、项目符号与缩进等结构（README 表述）。
- 模型侧翻译：
hwp_extract/hwp_apply路径下不调用外部翻译 API；模型根据抽取的韩文逐段产出中文，再以 id 映射写回。 - 分页抽取：长文档需分页；
hwp_extract返回next_offset用于取下一页（默认每页 50 段）。hwp_apply返回中的missing表示未交回的 id。 - 格式差异：
.hwpx走纯 Python 链路；旧版.hwp写回依赖本机安装的 한글(HWP)（COM）。随包提供bin/HWP_Translator.exe（README 约 16.8 MB），无需单独安装 Yeobaek。
安装与启用¶
在 DSH 插件安装界面添加，或在终端执行（命令来自仓库 README）：
dsh plugin --profile web add github:Sanshui258/dsh-hwp-translate
安装后插件以当前 dsh 进程的用户权限访问本机路径与（.hwp 场景下）한글 COM。安装前应浏览仓库源码与许可条款，确认符合你的环境与合规要求。
典型用法¶
README 给出的模型自动完成流程如下。
用户示例意图：把 D:\资料\행정절차.hwpx 翻成中文。
- 调用
hwp_extract→ 得到若干段韩文（含 id）。 - 会话模型将各段译为中文。
- 调用
hwp_apply，例如传入{"1": "专业体验活动照片", ...}→ 输出D:\资料\행정절차_zh.hwpx。
若段落较多，用 next_offset 继续 hwp_extract，凑齐全部 id 后再一次性或分批 hwp_apply，并核对返回的 missing。
不经过 DSH 时，也可直接使用随包可执行文件（README 离线命令行）：
HWP_Translator.exe --file 文档.hwpx --extract-json segments.json
HWP_Translator.exe --file 文档.hwpx --apply-json translations.json --output-dir out
适用场景与注意¶
适合谁
- 在 Windows 上、用 DSH 智能体处理韩文 HWP/HWPX，且希望翻译结果仍按原结构落盘。
- 愿意让当前会话模型承担翻译质量，而不是依赖插件内置的付费 API 路径。
限制与注意
- 仅 Windows；Linux/macOS 不在
package.json的os支持范围内。 .hwp需要本机 한글；.hwpx 不需要。hwp_translate仍为兼容旧用法保留，需要用户自己的 API Key，与推荐的无 Key 流程无关。- 长文档务必按 offset 分页抽取，避免一次加载过多段落。
- 插件与翻译器许可不同：插件 MIT，翻译器非商业个人使用——商业场景需自行确认授权。
DSH 生态遵循「一切皆插件」：社区目录（如 SkillHub）是独立站点，与 DeepSeek / 幻方无官方从属关系；本文事实以 GitHub README 与仓库 package.json 为准。
结尾¶
dsh-hwp-translate 把 HWP/HWPX 的结构化抽取与写回接到 DSH 工具链上，让「模型翻译 + 本地回写」成为默认路径，免去为版式付出的代价。进一步说明与源码见：
- 目录页：https://www.skillhub.cn/plugins/Sanshui258/dsh-hwp-translate
- GitHub：https://github.com/Sanshui258/dsh-hwp-translate
