dsh-hwp

A DeepSeek Harness plugin that lets agents read Korean Hangul word processor documents — .hwp (HWP 5.x) and .hwpx — as Markdown or plain text.

HWP files are everywhere in Korean government, public institutions, schools, and companies, but they are binary (or zipped XML), so the built-in read tool rejects them. dsh-hwp registers one tool, read_hwp, that converts a document into text the model can use: paragraphs, tabs and line breaks, tables (as Markdown tables), text boxes, captions, and footnotes/endnotes.

No native binaries and no runtime dependencies. The HWP 5.x compound-file reader, the HWPX ZIP reader, and the XML parser are small TypeScript modules that use only Node.js built-ins.
Reads through the harness filesystem seam (ctx.fs), so relative paths resolve against the session workspace and sandbox / observation policy apply exactly as they do for the built-in read tool.
Bounded and pageable. File size, decompressed size, record/element counts, nesting depth, and output size are all capped; long documents are returned in windows with offset / limit.
Optional external converter for formats the built-in reader does not handle (for example HWP 3.x), run without a shell.

Install

Requires a DeepSeek Harness host (tested with @deepseek-ai/dsh 0.1.5 release candidates) and Node.js 22 or newer.

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

Restart dsh web afterwards. The repository ships the built lib/ output, so installing from GitHub needs no build step and no allowBuilds approval. You can pin a commit for reproducibility:

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

To install from a local checkout instead:

git clone https://github.com/kevin9327/dsh-hwp.git
dsh plugin --profile web add ./dsh-hwp

The package declares a dsh.bundle manifest; its cordis.patch.yml inserts one plugin row (id: dsh-hwp). Remove it with dsh plugin --profile web remove dsh-hwp.

Usage

Ask the agent to read a document, for example:

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

The model calls read_hwp:

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

and receives something like:

공고문.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 the `.hwp` / `.hwpx` file. Relative paths resolve against the session workspace.
`format`	`"markdown"` \| `"text"`	no	`markdown` (default): tables become Markdown tables. `text`: table rows become tab-separated lines.
`offset`	integer	no	1-based first line of the converted output. Default `1`.
`limit`	integer	no	Maximum number of lines to return. Default and maximum: `readLimit` (1000).

The format is detected from the file content, never from the extension.

Result

The model sees a header line, the requested lines, a continuation hint when more lines remain, and any warnings. Programmatic callers (for example PTC mode) receive this canonical value:

Field	Type	Description
`path`	string	Display path of the file that was read.
`sourceFormat`	`hwp5` \| `hwpx` \| `hwp3` \| `hwpml` \| `unknown`	Detected container format.
`engine`	`builtin` \| `converter`	Which reader produced the text.
`version`	string?	Format version declared by the file, e.g. `5.1.0.1`.
`sections`	integer?	Number of body sections (built-in reader only).
`format`	`markdown` \| `text`	Output format used.
`offset`	integer	First line requested.
`lines`	`{ number, text }[]`	The returned window.
`totalLines`	integer	Total lines of the converted document.
`nextOffset`	integer?	Present when more lines remain; pass it as `offset` to continue.
`warnings`	string[]	Non-fatal problems, e.g. a truncated trailing record.

Errors

Failures are returned as tool errors whose message starts with a stable code:

Code	Meaning
`HWP_UNSUPPORTED_FORMAT`	Not an HWP 5.x or HWPX document (HWP 3.x and HWPML need the external converter).
`HWP_ENCRYPTED`	Password-protected or DRM-protected document.
`HWP_DISTRIBUTION`	Read-only "distribution" document (배포용 문서) whose body text is encrypted.
`HWP_MALFORMED`	The container or record structure is damaged.
`HWP_TOO_LARGE`	A size, count, or nesting limit was exceeded.
`HWP_CONVERTER_FAILED`	The external converter is misconfigured, failed, timed out, or produced too much output.

Missing files, directories, and invalid arguments produce the usual harness tool errors.

Configuration

Every field has a default. Override fields in your profile's cordis.patch.yml; remember that a patch replaces a row's whole config, so restate every field you want to keep non-default.

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

Field	Default	Description
`maxFileBytes`	`52428800` (50 MiB)	Largest file read by one call.
`maxDecompressedBytes`	`268435456` (256 MiB)	Largest total decompressed size of one document (decompression-bomb guard).
`readLimit`	`1000`	Default and maximum number of lines per call.
`maxOutputChars`	`40000`	Character budget of one returned window.
`maxLineChars`	`4000`	Longer lines are cut and marked. Must not exceed `maxOutputChars`.
`timeoutMs`	`120000`	Cooperative timeout of one call.
`converter.command`	`""`	Absolute path of an external converter executable. Empty disables it.
`converter.args`	`["{input}"]`	Converter arguments; `{input}` is replaced by the path of 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 every file.
`converter.timeoutMs`	`60000`	Converter timeout.
`converter.maxOutputBytes`	`33554432` (32 MiB)	Largest converter output accepted.

External converter

You can plug in any command-line converter you trust that prints Markdown or text to stdout. The plugin:

reads the document through ctx.fs (size-checked),
writes those bytes to a private temporary directory as document.hwp / .hwpx / .hml,
spawns converter.command directly, without a shell, with {input} in converter.args replaced by that temporary path — nothing from the model's arguments or the document ends up on the command line,
enforces the timeout and output cap, and deletes the temporary directory.

Encrypted and distribution documents are never sent to the converter. On Windows, .cmd / .bat wrappers are rejected because they would need a shell; point command at the real executable (for a Node.js converter, use node.exe and put the script path first in args). The converter runs with the harness process's permissions, outside any sandbox — configure only programs you trust.

Limitations

Not read: page headers and footers, memos/comments, hidden comments, field guide text (누름틀 안내문), equations, images and their embedded data, charts and OLE objects, and change-tracking history.
Not supported by the built-in reader: HWP 3.x (.hwp from Hangul 97 and earlier) and HWPML (.hml) — use an external converter; password-protected, DRM-protected, and distribution documents are refused.
Formatting is not preserved: heading levels, fonts, colors, and alignment are dropped. Merged table cells keep their text in the top-left cell and leave the covered cells empty; nested tables are flattened into their parent cell; a 1×1 table (a boxed paragraph) is rendered as plain paragraphs.
HWPX ZIP64 packages (over 4 GiB) are not supported.
Parsing is synchronous; a very large document can block the harness event loop for a moment.

How it was tested

76 unit and integration tests (Vitest), run in CI on Linux and Windows. Fixtures are synthetic documents generated by the tests themselves: HWP 5.x records inside compound files written by the independent cfb library, and HWPX packages zipped by fflate.
Seeded fuzz tests mutate compound files, ZIP archives, and record streams and assert that only typed HwpReadErrors escape — no RangeErrors, hangs, or unbounded allocations.
The plugin is composed with the real @deepseek-ai/dsh-tools, @deepseek-ai/dsh-system-prompt, and @deepseek-ai/dsh-fs-local services in a Cordis context and called through the harness tool pipeline.
The packed plugin was installed with dsh plugin add into a @deepseek-ai/dsh 0.1.5-rc profile and driven through the real headless agent loop by a local stand-in model provider (no API key): the agent called read_hwp with a workspace-relative path and received the converted .hwp and .hwpx content, and a missing file came back as a tool error.
During development the reader was also cross-checked against an independent open-source HWP parser on a local corpus of about 1,000 real-world public documents (not included in this repository).

Development

npm ci
npm run typecheck
npm test
npm run build   # regenerates lib/, which is committed so GitHub installs need no build step

License

MIT. dsh-hwp has no runtime dependencies; the @deepseek-ai/* packages it uses are peer dependencies provided by the harness. Development-only dependencies are MIT, ISC, BSD, or Apache-2.0 licensed.

This plugin was written from the publicly available HWP 5.0 and OWPML (HWPX) format documentation. "Hangul", "HWP", and "Hancom" are trademarks of Hancom Inc.; this project is not affiliated with or endorsed by Hancom Inc. or DeepSeek.

한국어

dsh-hwp는 DeepSeek Harness용 플러그인으로, 에이전트가 한글 문서(.hwp HWP 5.x, .hwpx)를 Markdown 또는 일반 텍스트로 읽을 수 있게 해 주는 read_hwp 도구를 등록합니다.

네이티브 바이너리·런타임 의존성 없음: HWP 5.x 복합 파일, HWPX(ZIP+XML) 파서를 Node.js 내장 기능만으로 구현했습니다.
읽는 내용: 문단, 탭·줄바꿈, 표(Markdown 표), 글상자, 캡션, 각주·미주.
안전장치: 파일 크기·압축 해제 크기·레코드 수·중첩 깊이·출력 길이를 모두 제한하고, 긴 문서는 offset/limit로 나눠 읽습니다.
외부 변환기(선택): HWP 3.x처럼 내장 파서가 읽지 못하는 형식은 사용자가 지정한 변환 프로그램으로 읽을 수 있습니다. 셸을 거치지 않고 실행하며, 임시 사본 경로만 인자로 넘깁니다.

설치

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

설치 후 dsh web을 다시 시작하세요.

사용 예

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

제한 사항

머리말·꼬리말, 메모, 숨은 설명, 누름틀 안내문, 수식, 그림·차트·OLE 개체, 변경 추적 기록은 읽지 않습니다.
HWP 3.x, HWPML(.hml)은 외부 변환기가 필요합니다. 암호·DRM이 걸린 문서와 배포용 문서는 읽지 않습니다.
글꼴·제목 수준·정렬 같은 서식은 보존하지 않습니다. 병합된 셀은 왼쪽 위 칸에 내용을 두고 나머지는 비웁니다.

라이선스: MIT

dsh-hwp

English | 한국어

A DeepSeek Harness plugin that lets agents read Korean Hangul word processor documents — .hwp (HWP 5.x) and .hwpx — as Markdown or plain text.

No native binaries and no runtime dependencies. The HWP 5.x compound-file reader, the HWPX ZIP reader, and the XML parser are small TypeScript modules that use only Node.js built-ins.
Reads through the harness filesystem seam (ctx.fs), so relative paths resolve against the session workspace and sandbox / observation policy apply exactly as they do for the built-in read tool.
Bounded and pageable. File size, decompressed size, record/element counts, nesting depth, and output size are all capped; long documents are returned in windows with offset / limit.
Optional external converter for formats the built-in reader does not handle (for example HWP 3.x), run without a shell.

Install

Requires a DeepSeek Harness host (tested with @deepseek-ai/dsh 0.1.5 release candidates) and Node.js 22 or newer.

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

Restart dsh web afterwards. The repository ships the built lib/ output, so installing from GitHub needs no build step and no allowBuilds approval. You can pin a commit for reproducibility:

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

To install from a local checkout instead:

git clone https://github.com/kevin9327/dsh-hwp.git
dsh plugin --profile web add ./dsh-hwp

The package declares a dsh.bundle manifest; its cordis.patch.yml inserts one plugin row (id: dsh-hwp). Remove it with dsh plugin --profile web remove dsh-hwp.

Usage

Ask the agent to read a document, for example:

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

The model calls read_hwp:

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

and receives something like:

공고문.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 the `.hwp` / `.hwpx` file. Relative paths resolve against the session workspace.
`format`	`"markdown"` \| `"text"`	no	`markdown` (default): tables become Markdown tables. `text`: table rows become tab-separated lines.
`offset`	integer	no	1-based first line of the converted output. Default `1`.
`limit`	integer	no	Maximum number of lines to return. Default and maximum: `readLimit` (1000).

The format is detected from the file content, never from the extension.

Result

The model sees a header line, the requested lines, a continuation hint when more lines remain, and any warnings. Programmatic callers (for example PTC mode) receive this canonical value:

Field	Type	Description
`path`	string	Display path of the file that was read.
`sourceFormat`	`hwp5` \| `hwpx` \| `hwp3` \| `hwpml` \| `unknown`	Detected container format.
`engine`	`builtin` \| `converter`	Which reader produced the text.
`version`	string?	Format version declared by the file, e.g. `5.1.0.1`.
`sections`	integer?	Number of body sections (built-in reader only).
`format`	`markdown` \| `text`	Output format used.
`offset`	integer	First line requested.
`lines`	`{ number, text }[]`	The returned window.
`totalLines`	integer	Total lines of the converted document.
`nextOffset`	integer?	Present when more lines remain; pass it as `offset` to continue.
`warnings`	string[]	Non-fatal problems, e.g. a truncated trailing record.

Errors

Failures are returned as tool errors whose message starts with a stable code:

Code	Meaning
`HWP_UNSUPPORTED_FORMAT`	Not an HWP 5.x or HWPX document (HWP 3.x and HWPML need the external converter).
`HWP_ENCRYPTED`	Password-protected or DRM-protected document.
`HWP_DISTRIBUTION`	Read-only "distribution" document (배포용 문서) whose body text is encrypted.
`HWP_MALFORMED`	The container or record structure is damaged.
`HWP_TOO_LARGE`	A size, count, or nesting limit was exceeded.
`HWP_CONVERTER_FAILED`	The external converter is misconfigured, failed, timed out, or produced too much output.

Missing files, directories, and invalid arguments produce the usual harness tool errors.

Configuration

Every field has a default. Override fields in your profile's cordis.patch.yml; remember that a patch replaces a row's whole config, so restate every field you want to keep non-default.

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

Field	Default	Description
`maxFileBytes`	`52428800` (50 MiB)	Largest file read by one call.
`maxDecompressedBytes`	`268435456` (256 MiB)	Largest total decompressed size of one document (decompression-bomb guard).
`readLimit`	`1000`	Default and maximum number of lines per call.
`maxOutputChars`	`40000`	Character budget of one returned window.
`maxLineChars`	`4000`	Longer lines are cut and marked. Must not exceed `maxOutputChars`.
`timeoutMs`	`120000`	Cooperative timeout of one call.
`converter.command`	`""`	Absolute path of an external converter executable. Empty disables it.
`converter.args`	`["{input}"]`	Converter arguments; `{input}` is replaced by the path of 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 every file.
`converter.timeoutMs`	`60000`	Converter timeout.
`converter.maxOutputBytes`	`33554432` (32 MiB)	Largest converter output accepted.

External converter

You can plug in any command-line converter you trust that prints Markdown or text to stdout. The plugin:

reads the document through ctx.fs (size-checked),
writes those bytes to a private temporary directory as document.hwp / .hwpx / .hml,
spawns converter.command directly, without a shell, with {input} in converter.args replaced by that temporary path — nothing from the model's arguments or the document ends up on the command line,
enforces the timeout and output cap, and deletes the temporary directory.

Limitations

Not read: page headers and footers, memos/comments, hidden comments, field guide text (누름틀 안내문), equations, images and their embedded data, charts and OLE objects, and change-tracking history.
Not supported by the built-in reader: HWP 3.x (.hwp from Hangul 97 and earlier) and HWPML (.hml) — use an external converter; password-protected, DRM-protected, and distribution documents are refused.
Formatting is not preserved: heading levels, fonts, colors, and alignment are dropped. Merged table cells keep their text in the top-left cell and leave the covered cells empty; nested tables are flattened into their parent cell; a 1×1 table (a boxed paragraph) is rendered as plain paragraphs.
HWPX ZIP64 packages (over 4 GiB) are not supported.
Parsing is synchronous; a very large document can block the harness event loop for a moment.

How it was tested

76 unit and integration tests (Vitest), run in CI on Linux and Windows. Fixtures are synthetic documents generated by the tests themselves: HWP 5.x records inside compound files written by the independent cfb library, and HWPX packages zipped by fflate.
Seeded fuzz tests mutate compound files, ZIP archives, and record streams and assert that only typed HwpReadErrors escape — no RangeErrors, hangs, or unbounded allocations.
The plugin is composed with the real @deepseek-ai/dsh-tools, @deepseek-ai/dsh-system-prompt, and @deepseek-ai/dsh-fs-local services in a Cordis context and called through the harness tool pipeline.
The packed plugin was installed with dsh plugin add into a @deepseek-ai/dsh 0.1.5-rc profile and driven through the real headless agent loop by a local stand-in model provider (no API key): the agent called read_hwp with a workspace-relative path and received the converted .hwp and .hwpx content, and a missing file came back as a tool error.
During development the reader was also cross-checked against an independent open-source HWP parser on a local corpus of about 1,000 real-world public documents (not included in this repository).

Development

npm ci
npm run typecheck
npm test
npm run build   # regenerates lib/, which is committed so GitHub installs need no build step

License

한국어

네이티브 바이너리·런타임 의존성 없음: HWP 5.x 복합 파일, HWPX(ZIP+XML) 파서를 Node.js 내장 기능만으로 구현했습니다.
읽는 내용: 문단, 탭·줄바꿈, 표(Markdown 표), 글상자, 캡션, 각주·미주.
안전장치: 파일 크기·압축 해제 크기·레코드 수·중첩 깊이·출력 길이를 모두 제한하고, 긴 문서는 offset/limit로 나눠 읽습니다.
외부 변환기(선택): HWP 3.x처럼 내장 파서가 읽지 못하는 형식은 사용자가 지정한 변환 프로그램으로 읽을 수 있습니다. 셸을 거치지 않고 실행하며, 임시 사본 경로만 인자로 넘깁니다.

설치

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

설치 후 dsh web을 다시 시작하세요.

사용 예

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

제한 사항

머리말·꼬리말, 메모, 숨은 설명, 누름틀 안내문, 수식, 그림·차트·OLE 개체, 변경 추적 기록은 읽지 않습니다.
HWP 3.x, HWPML(.hml)은 외부 변환기가 필요합니다. 암호·DRM이 걸린 문서와 배포용 문서는 읽지 않습니다.
글꼴·제목 수준·정렬 같은 서식은 보존하지 않습니다. 병합된 셀은 왼쪽 위 칸에 내용을 두고 나머지는 비웁니다.

라이선스: MIT

kevin9327/dsh-hwp

dsh-hwp

Install

Usage

Tool reference: `read_hwp`

Parameters

Result

Errors

Configuration

External converter

Limitations

How it was tested

Development

License

한국어

설치

사용 예

제한 사항

Community comments

kevin9327/dsh-hwp

dsh-hwp

Install

Usage

Tool reference: `read_hwp`

Parameters

Result

Errors

Configuration

External converter

Limitations

How it was tested

Development

License

한국어

설치

사용 예

제한 사항

Community comments

kevin9327/dsh-hwp

dsh-hwp

Install

Usage

Tool reference: read_hwp

Parameters

Result

Errors

Configuration

External converter

Limitations

How it was tested

Development

License

한국어

설치

사용 예

제한 사항

Community comments

kevin9327/dsh-hwp

dsh-hwp

Install

Usage

Tool reference: read_hwp

Parameters

Result

Errors

Configuration

External converter

Limitations

How it was tested

Development

License

한국어

설치

사용 예

제한 사항

Community comments

Tool reference: `read_hwp`

Tool reference: `read_hwp`