dsh-hwp：DeepSeek Harness 韩文文档读取插件

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

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

核心功能¶

无本地二进制文件和运行时依赖：HWP 5.x 复合文件读取器、HWPX ZIP 读取器和 XML 解析器是仅使用 Node.js 内置功能的 TypeScript 模块。
内容提取：支持读取段落、制表符、换行、表格（Markdown 表格）、文本框、标题、脚注和尾注。
文件系统集成：通过 harness 文件系统（ctx.fs）读取，相对路径解析到会话工作区，并应用沙箱/观察策略。
分页与限制：支持文件大小、解压大小、记录/元素计数、嵌套深度和输出大小的限制。长文档返回带 offset / limit 的窗口。

安装与启用¶

安装需要 DeepSeek Harness 主机（测试于 @deepseek-ai/dsh 0.1.5-rc）和 Node.js 22 或更新版本。

使用以下命令安装：

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

安装后重启 dsh web。仓库自带构建好的 lib/ 输出，因此从 GitHub 安装不需要构建步骤。要固定特定提交以实现可重现性，请使用：

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

典型用法¶

用户可以提示模型读取文档，例如：

공고문.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`	integer	否	转换输出的第一行（1 基准）。默认 `1`。
`limit`	integer	否	返回的最大行数。默认和最大：`readLimit`（1000）。

结果¶

模型会看到一行标题、请求的行、更多行存在时的延续提示以及任何警告。

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

错误¶

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

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

配置¶

默认覆盖每个字段。在配置文件的 cordis.patch.yml 中覆盖字段。

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

外部转换器¶

可以插入任何信任的命令行转换器，将其打印到 stdout。插件：
1. 通过 ctx.fs 读取文档（检查大小）；
2. 将这些字节写入临时目录中的 document.hwp / .hwpx / .hml；
3. 直接（无 Shell）生成 converter.command，将 {input} 替换为临时路径；
4. 强制执行超时和输出上限，并删除临时目录。

加密和分布文档从不发送给转换器。在 Windows 上，.cmd / .bat 包装器被拒绝；将 command 指向真实可执行文件。

限制与注意事项¶

不可读取：页眉、页脚、备注、隐藏注释、字段指南文本（누름틀 안내문）、方程、图像及其嵌入数据、图表和 OLE 对象、以及修订跟踪历史。
内置读取器不支持：HWP 3.x（来自 Hangul 97 及更早版本）和 HWPML（.hml）——需要外部转换器；密码保护、DRM 保护以及分布文档被拒绝。
格式不保留：标题级别不保留（仅作为文本提取）。
沙箱风险：外部转换器在沙箱之外运行，并使用 DSH 进程的权限。仅配置您信任的程序。