dsh-hwp：DeepSeek Harness 韓文文檔讀取插件

在 DeepSeek Harness (DSH) 中，內置的 read 工具通常能處理純文本文件。但在處理韓文辦公文檔時，特別是 HWP（韓文 Word）格式，這些二進制或壓縮的文件往往被直接拒絕。dsh-hwp 插件解決了這個問題，它將 .hwp (HWP 5.x) 和 .hwpx 文檔轉換爲 Markdown 或純文本。

這是一個 DeepSeek Harness 插件，由 kevin9327 維護。它將韓文 Hangul 文檔轉換爲可讀文本，供智能體處理。

核心功能¶

無本地二進制文件和運行時依賴：HWP 5.x 複合文件讀取器、HWPX ZIP 讀取器和 XML 解析器是僅使用 Node.js 內置功能的 TypeScript 模塊。
內容提取：支持讀取段落、製表符、換行、表格（Markdown 表格）、文本框、標題、腳註和尾註。
文件系統集成：通過 harness 文件系統（ctx.fs）讀取，相對路徑解析到會話工作區，並應用沙箱/觀察策略。
分頁與限制：支持文件大小、解壓大小、記錄/元素計數、嵌套深度和輸出大小的限制。長文檔返回帶 offset / limit 的窗口。

安裝與啓用¶

安裝需要 DeepSeek Harness 主機（測試於 @deepseek-ai/dsh 0.1.5-rc）和 Node.js 22 或更新版本。

使用以下命令安裝：

dsh plugin --profile web add github:kevin9327/dsh-hwp

安裝後重啓 dsh web。倉庫自帶構建好的 lib/ 輸出，因此從 GitHub 安裝不需要構建步驟。要固定特定提交以實現可重現性，請使用：

dsh plugin --profile web add github:kevin9327/dsh-hwp#<commit-sha>

典型用法¶

用戶可以提示模型讀取文檔，例如：

공고문.hwpx 파일을 읽고 신청 자격과 마감일을 정리해 줘.

模型隨後調用 read_hwp 工具：

{ "file_path": "공고문.hwpx" }

輸出示例如下：

공고문.hwpx (hwpx 5.1.1.0, builtin reader, markdown) — lines 1-42 of 42

2026년 지원사업 모집 공고
...
| 구분 | 신청 기간 | 비고 |
| --- | --- | --- |
| 1차 | 3.2.~3.20. | 온라인 접수 |

工具參考：`read_hwp`¶

參數¶

名稱	類型	必需	描述
`file_path`	string	是	`.hwp` / `.hwpx` 文件的路徑。相對路徑解析到會話工作區。
`format`	`"markdown"` \| `"text"`	否	`markdown`（默認）：表格轉換爲 Markdown 表格。`text`：表格行轉換爲製表符分隔的行。
`offset`	integer	否	轉換輸出的第一行（1 基準）。默認 `1`。
`limit`	integer	否	返回的最大行數。默認和最大：`readLimit`（1000）。

結果¶

模型會看到一行標題、請求的行、更多行存在時的延續提示以及任何警告。

字段	類型	描述
`path`	string	讀取文件的顯示路徑。
`sourceFormat`	`hwp5` \| `hwpx` \| `hwp3` \| `hwpml` \| `unknown`	檢測到的容器格式。
`engine`	`builtin` \| `converter`	生成文本的讀取器。
`version`	string?	文件聲明的格式版本，例如 `5.1.0.1`。
`sections`	integer?	主體節數（僅內置讀取器）。
`format`	`markdown` \| `text`	使用的輸出格式。
`offset`	integer	請求的第一行。
`lines`	`{ number, text }[]`	返回的窗口。
`totalLines`	integer	轉換後文檔的總行數。
`nextOffset`	integer?	更多行存在時出現；將其作爲 `offset` 傳遞以繼續。
`warnings`	string[]	非致命問題，例如截斷的尾部記錄。

錯誤¶

失敗作爲工具錯誤返回，其消息以穩定的代碼開頭：

代碼	含義
`HWP_UNSUPPORTED_FORMAT`	不是 HWP 5.x 或 HWPX 文檔（HWP 3.x 和 HWPML 需要外部轉換器）。
`HWP_ENCRYPTED`	受密碼保護或受 DRM 保護的文檔。
`HWP_DISTRIBUTION`	只讀“分佈”文檔（배포용 문檔），其正文文本已加密。
`HWP_MALFORMED`	容器或記錄結構損壞。
`HWP_TOO_LARGE`	超過了大小、計數或嵌套限制。
`HWP_CONVERTER_FAILED`	外部轉換器配置錯誤、失敗、超時或產生過多輸出。

配置¶

默認覆蓋每個字段。在配置文件的 cordis.patch.yml 中覆蓋字段。

- id: dsh-hwp
  name: dsh-hwp
  config:
    readLimit: 500
    maxOutputChars: 30000

字段	默認值	描述
`maxFileBytes`	`52428800` (50 MiB)	單次調用讀取的最大文件。
`maxDecompressedBytes`	`268435456` (256 MiB)	單個文檔的總解壓大小（反解壓炸彈保護）。
`readLimit`	`1000`	每次調用返回的最大行數。
`maxOutputChars`	`40000`	單個返回窗口的字符預算。
`maxLineChars`	`4000`	較長的行被截斷並標記。必須不超過 `maxOutputChars`。
`timeoutMs`	`120000`	單次調用的協同超時。
`converter.command`	`""`	外部轉換器可執行文件的絕對路徑。空則禁用。
`converter.args`	`["{input}"]`	轉換器參數；`{input}` 被文檔臨時副本的路徑替換。
`converter.mode`	`fallback`	`fallback`：僅當內置讀取器報告 `HWP_UNSUPPORTED_FORMAT` 或 `HWP_MALFORMED` 時使用轉換器。`always`：用於所有文件。
`converter.timeoutMs`	`60000`	轉換器超時。
`converter.maxOutputBytes`	`33554432` (32 MiB)	接受的最大轉換器輸出。

外部轉換器¶

可以插入任何信任的命令行轉換器，將其打印到 stdout。插件：
1. 通過 ctx.fs 讀取文檔（檢查大小）；
2. 將這些字節寫入臨時目錄中的 document.hwp / .hwpx / .hml；
3. 直接（無 Shell）生成 converter.command，將 {input} 替換爲臨時路徑；
4. 強制執行超時和輸出上限，並刪除臨時目錄。

加密和分佈文檔從不發送給轉換器。在 Windows 上，.cmd / .bat 包裝器被拒絕；將 command 指向真實可執行文件。

限制與注意事項¶

不可讀取：頁眉、頁腳、備註、隱藏註釋、字段指南文本（누름틀 안내문）、方程、圖像及其嵌入數據、圖表和 OLE 對象、以及修訂跟蹤歷史。
內置讀取器不支持：HWP 3.x（來自 Hangul 97 及更早版本）和 HWPML（.hml）——需要外部轉換器；密碼保護、DRM 保護以及分佈文檔被拒絕。
格式不保留：標題級別不保留（僅作爲文本提取）。
沙箱風險：外部轉換器在沙箱之外運行，並使用 DSH 進程的權限。僅配置您信任的程序。