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.

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:

1. reads the document through ctx.fs (size-checked),
2. writes those bytes to a private temporary directory as document.hwp / .hwpx / .hml,
3. 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,
4. 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