# dsh-hwp

[![CI](https://github.com/kevin9327/dsh-hwp/actions/workflows/ci.yml/badge.svg)](https://github.com/kevin9327/dsh-hwp/actions/workflows/ci.yml)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

English | [한국어](#한국어)

A [DeepSeek Harness](https://github.com/deepseek-ai/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.

```sh
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:

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

To install from a local checkout instead:

```sh
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`:

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

and receives something like:

```text
공고문.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.

```yaml
- 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`](https://github.com/SheetJS/js-cfb) library, and HWPX packages zipped by
  [`fflate`](https://github.com/101arrowz/fflate).
- Seeded fuzz tests mutate compound files, ZIP archives, and record streams and assert that only typed
  `HwpReadError`s escape — no `RangeError`s, 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

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

## License

[MIT](LICENSE). `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](https://github.com/deepseek-ai/deepseek-harness)용 플러그인으로, 에이전트가
한글 문서(`.hwp` HWP 5.x, `.hwpx`)를 Markdown 또는 일반 텍스트로 읽을 수 있게 해 주는 `read_hwp` 도구를 등록합니다.

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

### 설치

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

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

### 사용 예

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

### 제한 사항

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

라이선스: MIT