oma-hwp

HWP 技能 - 将 HWP / HWPX / HWPML 转换为 Markdown

调度

目标

将韩文 HWP 系列文档转换为易读的 Markdown 或结构化 JSON，同时保留文档结构，供大模型上下文、RAG、政府文档审核或企业文档处理使用。

意图特征

• 用户要求转换、解析、读取、提取或处理 .hwp、.hwpx 或 .hwpml。
• 用户提到韩文文字处理文件、韩文文档、政府表格或“한글 파일”。
• 用户需要从 HWP 系列文件中提取标题、表格、嵌套表格、列表、图像、脚注或超链接。

适用场景

• 将韩文 HWP 文档（.hwp、.hwpx、.hwpml）转换为 Markdown
• 为大模型上下文或 RAG 准备韩文政府／企业文档
• 从 HWP 中提取结构化内容（表格、标题、列表、图像）
• 用户说“转换这个 HWP”“解析 hwpx”“HWP 转 markdown”“한글 파일”

不适用场景

• PDF 文件 -> 使用 oma-pdf（OCR + Tagged PDF 专用工具）
• XLSX / DOCX 文件 -> 超出范围；如有需要，直接运行 bunx kordoc（注意：oma-docs 是用于文档漂移的技能，不是转换工具）
• 生成或编辑 HWP 文档 -> 超出范围（kordoc 本身支持 generate / fill / seal / patch / redact / lint / validate / render 子命令；如有需要，直接运行 bunx kordoc@latest <subcommand>）
• 已经是文本的文件 -> 直接使用 Read 工具

预期输入

• input_path：.hwp、.hwpx 或 .hwpml 文件路径
• output_path 或 output_dir：可选的明确输出目标
• format：可选的输出格式 — markdown（默认）、json（结构化 AST）或 chunks（面向 RAG 的结构化分块 JSON，包含标题路径和独立表格块）
• page_range：可选的页面或章节范围
• kordoc_version：可选的固定 kordoc 版本

预期输出

• 与输入文件同目录的 Markdown 输出，或输出到指定目录
• 按需生成 JSON 或 RAG 分块输出
• 默认经过后处理的 Markdown，包含扁平化的 GFM 表格，并剔除私用区字形
• 简短报告，包含输出路径、检测到的源格式和转换问题

依赖项

• bun 和 bunx
• bunx kordoc@latest 或配置的固定 kordoc 版本
• 用于清理 Markdown 的 resources/flatten-tables.ts
• 对输入和输出路径的本地文件系统访问权限

控制流特征

• 根据文件扩展名、输出目标、格式、页面范围、加密／DRM 状态和后处理要求进行分支处理
• 通过 bunx 和 bun run 调用外部 CLI 工具
• 读取本地 HWP 系列文件，并写入本地 Markdown 或 JSON 输出
• 将非 HWP 输入转交给其他技能，而不扩展本技能的适用范围

结构流程

入口

1. 确认输入路径存在。
2. 确认扩展名为 .hwp、.hwpx 或 .hwpml。
3. 确定输出路径或目录以及默认文件名。
4. 检查 bun 是否可用。

阶段

1. 准备：验证路径、扩展名、大小、输出目标和所需格式。
2. 获取：检测源格式和运行时是否可用。
3. 执行：使用明确的输出目标和所需选项运行 kordoc。
4. 验证：后处理 Markdown，并检查标题、表格、列表、图像和脚注等结构。
5. 完成：报告输出路径、源格式和任何转换限制。

转换条件

• 如果输入是 .pdf，停止处理并转交给 oma-pdf。
• 如果输入是 .xlsx 或 .docx，说明本技能不支持这些格式。
• 如果 bun 不可用，停止处理并请用户安装 Bun。
• 如果生成了 Markdown，则运行 resources/flatten-tables.ts，除非调用方明确需要保留 HTML 表格或 PUA 字形。
• 如果输出为空或乱码，请查阅 resources/troubleshooting.md。

失败与恢复

失败	恢复方式
bun 或 bunx 不可用	请用户安装 Bun
格式不受支持或不匹配	检查扩展名和魔数，然后选择相应处理方式或停止
文档已加密或受 DRM 锁定	说明限制，并在需要时请求提供可访问的副本
Markdown 输出为空	将其视为可能包含扫描图像内容，并建议在此技能之外使用 OCR
复杂的合并单元格表格	尽力采用扁平化 Markdown 或 HTML 作为备用格式
kordoc 缓存过期	使用 bunx kordoc@latest 或配置的固定版本
flatten-tables.ts 中出现 Cannot find module "turndown"	在此技能的 resources/ 目录中运行 bun install（该目录的 node_modules 已被 gitignore 忽略，新克隆的仓库中不存在）

退出

• 成功：输出文件存在，且后处理后的结构可读。
• 部分成功：输出文件存在，并明确报告表格、字形、加密或保真度方面的限制。
• 失败：未生成可靠输出，并报告阻碍原因。

逻辑操作

操作

操作	SSL 原语	依据
验证文件路径和扩展名	VALIDATE	执行协议中的输入预检
检查运行时是否可用	VALIDATE	bun --version
选择输出目标和格式	SELECT	输出行为和配置
运行转换器	CALL_TOOL	bunx kordoc@latest
写入输出产物	WRITE	Markdown 或 JSON 输出
扁平化表格并剥除 PUA 字形	CALL_TOOL	resources/flatten-tables.ts
检查提取质量	VALIDATE	验证步骤
报告结果	NOTIFY	面向用户的最终摘要

工具和工具链

• kordoc：HWP 系列格式转换的主要 CLI
• flatten-tables.ts：用于处理 GFM 表格和清理 Hancom PUA 的后处理脚本
• bun / bunx：运行时和 CLI 执行器

标准命令路径

bunx kordoc@latest "{input_path}" -o "{output_path}"
# fresh clone: run `bun install` in {skill_dir}/resources/ first (node_modules is gitignored)
bun "{skill_dir}/resources/flatten-tables.ts" "{output_path}"
# {skill_dir} = this skill's directory: .agents/skills/oma-hwp (project mode) or ~/.agents/skills/oma-hwp (global mode)

批量转换时，请使用明确的输出目录：

bunx kordoc@latest "{input_pattern}" -d "{output_dir}"

资源范围

范围	资源目标
LOCAL_FS	输入的 HWP 系列文件和生成的输出
PROCESS	bunx kordoc 和 bun run 子进程
MEMORY	格式决策、验证备注和最终报告

前置条件

• 输入文件存在且可读。
• 输出位置可写，或可以创建。
• 已安装 bun。
• kordoc 可以解析文档，或在失败时提供可报告的错误。

效果和副作用

• 创建 Markdown 或 JSON 输出文件。
• 可能会扁平化合并单元格表格，以牺牲单元格保真度换取 Markdown 兼容性。
• 默认剥除私用区字符，因为没有 Hancom 字体时这些字符会显示为空白。
• 不会有意修改源 HWP 系列文档。

防护措施

1. 始终传入 @latest 或明确指定的固定版本，以避免使用过期的 bunx 缓存。
2. 用户需要文件时，始终传入明确的输出目标。
3. 不要围绕 kordoc 的 ZIP、XML、SSRF 或 XSS 防护措施添加自定义安全防护。
4. 报告表格缺失、文本乱码、输出为空、加密片段，以及尽力提取 DRM 内容的情况。
5. 将完整的 CLI 详情保留在 resources/execution-protocol.md 中，并将故障排查分支保留在 resources/troubleshooting.md 中。

支持的格式

格式	扩展名	备注
HWP 5.x 二进制格式	.hwp	完全支持（包括通过 kordoc 的 rhwp-algorithm 移植版处理受 DRM 锁定的文件）
HWPX	.hwpx	完全支持，包括嵌套表格和合并单元格
HWPML	.hwp（XML 变体）	根据签名自动检测

kordoc 还可以解析 PDF / XLSX / DOCX，并提供文档创作子命令（generate、fill、seal、patch、redact、lint、validate、render）。这些功能均不属于本技能的范围；请参阅“何时不应使用”。转换质量标志（--dedupe-headers、--keep-empty-cols、--inline-images）和 chunks 格式详见 resources/execution-protocol.md。

参考资料

• 执行协议：resources/execution-protocol.md
• 故障排查：resources/troubleshooting.md
• 配置：先读取 .agents/oma-config.yaml 的 hwp: 部分，然后对其中未设置的键回退至 config/hwp-config.yaml（supported_formats 仅存在于技能配置中）。用户覆盖项应放在 .agents/oma-config.yaml 中，因为 oma update 会覆盖技能配置。
• 上游：https://github.com/chrisryugj/kordoc
• 相关：../oma-pdf/SKILL.md（用于 .pdf 输入）