前言¶
在 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
