kevin9327/dsh-hwp

dsh-hwp

CI
license: MIT

一个 DeepSeek Harness 插件，让智能体能够读取韩文
Hangul 文字处理文档——.hwp（HWP 5.x）和 .hwpx——并将其转换为 Markdown 或纯文本。

HWP 文件在韩国政府、公共机构、学校和企业中无处不在，但它们是二进制文件（或压缩的 XML），因此内置的
read 工具会拒绝它们。dsh-hwp 注册了一个工具 read_hwp，可将文档转换为模型可用的文本：段落、
制表符和换行符、表格（以 Markdown 表格形式）、文本框、题注以及脚注/尾注。

- 无原生二进制文件，无运行时依赖。 HWP 5.x 复合文件读取器、HWPX ZIP 读取器和 XML 解析器都是
小型 TypeScript 模块，仅使用 Node.js 内置功能。
- 通过 harness 文件系统接缝（ctx.fs）读取，因此相对路径会相对于会话工作区解析，沙箱 / 观察策略
的应用方式与内置 read 工具完全一致。
- 有界且可分页。 文件大小、解压后大小、记录/元素数量、嵌套深度和输出大小均设有上限；长文档以
窗口形式返回，并支持 offset / limit。
- 可选的外部转换器，用于处理内置读取器不支持的格式（例如 HWP 3.x），无需 shell 即可运行。

安装

需要 DeepSeek Harness 宿主（已使用 @deepseek-ai/dsh 0.1.5 候选发布版测试）以及 Node.js 22 或更高版本。

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

之后重启 dsh web。该仓库已附带构建好的 lib/ 输出，因此从 GitHub 安装无需构建步骤，也无需
allowBuilds 审批。你可以固定某个提交以保证可复现性：

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

若要从本地检出安装：

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

该包声明了 dsh.bundle 清单；其 cordis.patch.yml 会插入一行插件（id: dsh-hwp）。
可使用 dsh plugin --profile web remove dsh-hwp 将其移除。

用法

让智能体读取文档，例如：

공고문.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 | 整数 | 否 | 转换后输出的起始行（从 1 开始计数）。默认 1。 |
| limit | 整数 | 否 | 返回的最大行数。默认值和最大值：readLimit（1000）。 |

格式从文件内容中检测，绝不从扩展名检测。

结果

模型会看到一行表头、请求的行、当还有更多行时给出的续读提示，以及任何
警告。程序化调用方（例如 PTC 模式）会收到以下规范值：

| 字段 | 类型 | 描述 |
|---|---|---|
| path | 字符串 | 所读取文件的显示路径。 |
| sourceFormat | hwp5 \| hwpx \| hwp3 \| hwpml \| unknown | 检测到的容器格式。 |
| engine | builtin \| converter | 由哪个读取器生成文本。 |
| version | 字符串? | 文件声明的格式版本，例如 5.1.0.1。 |
| sections | 整数? | 正文节的数量（仅内置读取器）。 |
| format | markdown \| text | 使用的输出格式。 |
| offset | 整数 | 请求的起始行。 |
| lines | { number, text }[] | 返回的窗口。 |
| totalLines | 整数 | 转换后文档的总行数。 |
| nextOffset | 整数? | 当还有更多行时出现；将其作为 offset 传入以继续。 |
| warnings | 字符串[] | 非致命问题，例如被截断的尾部记录。 |

错误

失败会作为工具错误返回，其消息以稳定的代码开头：

| 代码 | 含义 |
|---|---|
| HWP_UNSUPPORTED_FORMAT | 不是 HWP 5.x 或 HWPX 文档（HWP 3.x 和 HWPML 需要外部转换器）。 |
| HWP_ENCRYPTED | 受密码保护或受 DRM 保护的文档。 |
| HWP_DISTRIBUTION | 只读的“分发”文档（배포용 문서），其正文文本已加密。 |
| HWP_MALFORMED | 容器或记录结构已损坏。 |
| HWP_TOO_LARGE | 超出了大小、数量或嵌套限制。 |
| HWP_CONVERTER_FAILED | 外部转换器配置错误、失败、超时，或产生了过多输出。 |

文件缺失、目录以及无效参数会产生通常的 harness 工具错误。

配置

每个字段都有默认值。在你的 profile 的 cordis.patch.yml 中覆盖字段；请记住，补丁会替换
某一行的整个 config，因此请重新声明你希望保持非默认值的每个字段。

- 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） | 可接受的最大转换器输出。 |

外部转换器

你可以接入任何你信任的、能将 Markdown 或文本打印到 stdout 的命令行转换器。该插件会：

1. 通过 ctx.fs 读取文档（已做大小检查），
2. 将这些字节写入一个私有临时目录，文件名为 document.hwp / .hwpx / .hml，
3. 直接启动 converter.command，不经过 shell，并将 converter.args 中的 {input} 替换为该临时路径——模型参数或文档中的任何内容都不会出现在命令行上，
4. 强制执行超时和输出上限，并删除临时目录。

加密文档和分发文档绝不会发送给转换器。在 Windows 上，.cmd / .bat 包装脚本会被拒绝，因为它们需要 shell；请将 command 指向真正的可执行文件（对于 Node.js 转换器，请使用 node.exe，并将脚本路径放在 args 的首位）。转换器以 harness 进程的权限运行，且在任何沙箱之外——请只配置你信任的程序。

限制

- 不读取： 页眉和页脚、备忘录/批注、隐藏批注、字段引导文本（누름틀 안내문）、公式、图像及其嵌入数据、图表和 OLE 对象，以及修订跟踪历史。
- 内置读取器不支持： HWP 3.x（来自 Hangul 97 及更早版本的 .hwp）和 HWPML（.hml）——请使用外部转换器；受密码保护、受 DRM 保护和分发文档会被拒绝。
- 格式不会保留： 标题级别、字体、颜色和对齐方式都会被丢弃。合并的表格单元格会将其文本保留在左上角单元格中，并让被覆盖的单元格留空；嵌套表格会被展平到其父单元格中；1×1 表格（带边框的段落）会渲染为普通段落。
- 不支持 HWPX ZIP64 包（超过 4 GiB）。
- 解析是同步的；非常大的文档可能会短暂阻塞 harness 事件循环。

测试方式

- 76 个单元测试和集成测试（Vitest），在 CI 中于 Linux 和 Windows 上运行。测试夹具是由测试自身生成的合成文档：复合文件中的 HWP 5.x 记录由独立的 cfb 库写入，HWPX 包由 fflate 压缩。
- 种子模糊测试会变异复合文件、ZIP 归档和记录流，并断言只有带类型的
HwpReadError 会逃逸——不会有 RangeError、挂起或无界分配。
- 该插件在 Cordis 上下文中与真实的 @deepseek-ai/dsh-tools、@deepseek-ai/dsh-system-prompt 和
@deepseek-ai/dsh-fs-local 服务组合，并通过 harness 工具管道调用。
- 打包后的插件通过 dsh plugin add 安装到 @deepseek-ai/dsh 0.1.5-rc 配置文件中，并由本地替代模型提供方
（无需 API 密钥）通过真实的无头 agent 循环驱动：agent 使用工作区相对路径调用
read_hwp，并收到转换后的 .hwp 和 .hwpx 内容，而缺失的文件则作为工具错误返回。
- 在开发过程中，读取器还在约 1,000 份真实世界公开文档的本地语料库（未包含在本仓库中）上与一个独立的
开源 HWP 解析器进行了交叉校验。

开发

npm ci
npm run typecheck
npm test
npm run build   # 重新生成 lib/，该目录已提交，因此 GitHub 安装无需构建步骤

许可证

MIT。dsh-hwp 没有运行时依赖；它使用的 @deepseek-ai/* 包是由 harness 提供的
对等依赖。仅开发用的依赖采用 MIT、ISC、BSD 或 Apache-2.0 许可。

本插件是根据公开可用的 HWP 5.0 和 OWPML（HWPX）格式文档编写的。
“Hangul”、“HWP”和“Hancom”是 Hancom Inc. 的商标；本项目与
Hancom Inc. 或 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