dsh-hwp: DeepSeek Harness Korean Document Reader Plugin

在 DeepSeek Harness (DSH) 中，内置的 read 工具通常能处理纯文本文件。但在处理韩文办公文档时，特别是 HWP（韩文 Word）格式，这些二进制或压缩的文件往往被直接拒绝。dsh-hwp 插件解决了这个问题，它将 .hwp (HWP 5.x) 和 .hwpx 文档转换为 Markdown 或纯文本。

这是一个 DeepSeek Harness 插件，由 kevin9327 维护。它将韩文 Hangul 文档转换为可读文本，供智能体处理。

Wait, that was still Chinese. Need final only English. I’ll output translated. Ensure no Chinese.

Final:
In DeepSeek Harness (DSH), the built-in read tool can usually handle plain text files. But when processing Korean office documents, especially HWP (Hangul Word) format, these binary or compressed files are often rejected outright. The dsh-hwp plugin solves this problem by converting .hwp (HWP 5.x) and .hwpx documents to Markdown or plain text.

This is a DeepSeek Harness plugin maintained by kevin9327. It converts Korean Hangul documents into readable text for agent processing.

Core Features¶

No local binaries or runtime dependencies: The HWP 5.x compound-file reader, HWPX ZIP reader, and XML parser are TypeScript modules that use only Node.js built-in features.
Content extraction: Supports paragraphs, tabs, line breaks, tables (Markdown tables), text boxes, headings, footnotes, and endnotes.
Filesystem integration: Reads through the harness filesystem (ctx.fs); relative paths resolve to the session workspace, and sandbox/observation policies are applied.
Pagination and limits: Supports limits for file size, decompressed size, record/element count, nesting depth, and output size. Long documents return a window using offset / limit.

Installation and Enablement¶

Installation requires a DeepSeek Harness host (tested with @deepseek-ai/dsh 0.1.5-rc) and Node.js 22 or newer.

Use the following command to install:

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

After installation, restart dsh web. The repository includes prebuilt lib/ output, so installation from GitHub does not require a build step. To pin a specific commit for reproducibility, use:

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

Typical Usage¶

Users can prompt the model to read a document, for example:

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

The model then calls the read_hwp tool:

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

Sample output:

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

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

Tool Reference: `read_hwp`¶

Parameters¶

Name	Type	Required	Description
`file_path`	string	Yes	Path to a `.hwp` / `.hwpx` file. Relative paths resolve to the session workspace.
`format`	`"markdown"` \| `"text"`	No	`markdown` (default): tables are converted to Markdown tables. `text`: table rows are converted to tab-separated lines.
`offset`	integer	No	First line of the converted output (1-based). Default `1`.
`limit`	integer	No	Maximum number of lines to return. Default and maximum: `readLimit` (1000).

Result¶

The model sees a header line, the requested lines, a continuation hint if more lines exist, and any warnings.

Field	Type	Description
`path`	string	Display path of the file read.
`sourceFormat`	`hwp5` \| `hwpx` \| `hwp3` \| `hwpml` \| `unknown`	Detected container format.
`engine`	`builtin` \| `converter`	Reader that generated the text.
`version`	string?	Format version declared by the file, for example `5.1.0.1`.
`sections`	integer?	Number of body sections (built-in reader only).
`format`	`markdown` \| `text`	Output format used.
`offset`	integer	First requested line.
`lines`	`{ number, text }[]`	Returned window.
`totalLines`	integer	Total lines in the converted document.
`nextOffset`	integer?	Present when more lines exist; pass it as `offset` to continue.
`warnings`	string[]	Non-fatal issues, such as truncated trailing records.

Errors¶

Failures are returned as tool errors, with messages beginning with stable codes:

Code	Meaning
`HWP_UNSUPPORTED_FORMAT`	Not an HWP 5.x or HWPX document (HWP 3.x and HWPML require an external converter).
`HWP_ENCRYPTED`	Password-protected or DRM-protected document.
`HWP_DISTRIBUTION`	Read-only “distribution” document (배포용 문서), whose body text is encrypted.
`HWP_MALFORMED`	Corrupted container or record structure.
`HWP_TOO_LARGE`	Size, count, or nesting limits exceeded.
`HWP_CONVERTER_FAILED`	External converter misconfiguration, failure, timeout, or excessive output.

Configuration¶

Override fields in cordis.patch.yml in the configuration file.

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

Field	Default	Description
`maxFileBytes`	`52428800` (50 MiB)	Maximum file size read in a single invocation.
`maxDecompressedBytes`	`268435456` (256 MiB)	Total decompressed size for a single document (decompression-bomb protection).
`readLimit`	`1000`	Maximum lines returned per invocation.
`maxOutputChars`	`40000`	Character budget for a single returned window.
`maxLineChars`	`4000`	Longer lines are truncated and marked. Must not exceed `maxOutputChars`.
`timeoutMs`	`120000`	Cooperative timeout for a single invocation.
`converter.command`	`""`	Absolute path to an external converter executable. Empty disables it.
`converter.args`	`["{input}"]`	Converter arguments; `{input}` is replaced with the path to a temporary copy of the document.
`converter.mode`	`fallback`	`fallback`: use the converter only when the built-in reader reports `HWP_UNSUPPORTED_FORMAT` or `HWP_MALFORMED`. `always`: use it for all files.
`converter.timeoutMs`	`60000`	Converter timeout.
`converter.maxOutputBytes`	`33554432` (32 MiB)	Maximum accepted converter output.

External Converter¶

Any trusted command-line converter that prints to stdout can be used. The plugin:

reads the document through ctx.fs (checking size);
writes those bytes to document.hwp / .hwpx / .hml in a temporary directory;
spawns converter.command directly (without a shell), replacing {input} with the temporary path;
enforces timeouts and output limits, then removes the temporary directory.

Encrypted and distribution documents are never sent to the converter. On Windows, .cmd / .bat wrappers are rejected; point command at a real executable file.

Limitations and Notes¶

Not readable: headers, footers, remarks, hidden comments, field guideline text (누름틀 안내문), equations, images and their embedded data, charts and OLE objects, and revision tracking history.
Not supported by the built-in reader: HWP 3.x (from Hangul 97 and earlier) and HWPML (.hml)—an external converter is required; password-protected, DRM-protected, and distribution documents are rejected.
Formatting is not preserved: heading levels are not preserved (extracted only as text).
Sandbox risk: The external converter runs outside the sandbox and uses the permissions of the DSH process. Configure only programs you trust.