企业官网建设流程全解析

k-skill 的 rhwp-advanced 技能实战：用 rhwp Rust CLI 对 HWP 做布局调试、IR 结构审计、版本比对与只读文档解锁

【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill

rhwp-advanced是 k-skill 仓库中面向「HWP 文档结构级调试」的指引型技能：它不负责编辑，而是调用上游rhwp（Rust 原生 CLI）完成布局调试、文档 IR 结构转储、两个 HWP 文件的版本差异比对、PrvImage 缩略图提取，以及解锁「只读/禁编辑」的发行版 HWP。读完本文，你将掌握rhwp info / export-svg / dump / dump-pages / dump-records / diag / ir-diff / thumbnail / convert / gen-table这 10 个核心子命令的完整用法、验证方法与失败边界，并能根据 k-skill 中rhwp-edit（Node 编辑 CLI）与hwp（kordoc 转换）的技能分工，正确地把「调试」路由到本技能、把「编辑」路由到编辑技能。

一、技能定位：结构分析与渲染诊断专用，绝不越权编辑

k-skill 围绕 HWP/HWPX 形成了明确的三技能分工，rhwp-advanced只负责其中「分析、调试、一次性转换」这一层：

技能自身声明非常明确：「这个技能不做编辑（이 스킬은 편집을 하지 않는다）」。在仓库中，该技能的实际指令（rhwp-advanced/instruction.md）与自动生成的 CLI 存根（rhwp-advanced/SKILL.md、rhwp-advanced/skill.json）一一对应，skill.json的 description 即完整概括了本技能能力域：Debug HWP layout, dump document IR, compare versions, extract thumbnails, and unlock read-only HWPs。

典型使用场景（原文档 When to use）：

• 「表格/单元格被奇怪地截断了，想通过 IR 转储定位是在哪里坏的」；
• 「想逐行查看两个 HWP 文件的结构差异」；
• 「SVG 渲染异常，想可视化地检查段落/表格边界线」；
• 「想确认文档共有几页、某个段落横跨到哪一页」；
• 「想解除发行版（只读）HWP 文件的锁定」；
• 「想从 HWP 中取出 PrvImage 缩略图」。

明确不适用（When not to use）：

• 文本/表格编辑 → 走rhwp-edit（k-skill-rhwpCLI）；
• HWP → Markdown/JSON/表单字段转换 → 走hwp（kordoc）；
• GUI 自动化、绕过韩文 Office（한컴）安全模块、Windows 注册表控制 → 完全超出本技能范围，rhwp是文件格式引擎而非 GUI 控制器；
• 在 Node 代码中以库 API 形式编辑 → 直接使用k-skill-rhwp的 Node API。

硬性规则（Hard rules）：本技能（以及仓库内所有技能）在未获得用户明确事前批准时，绝不执行支付、消息/邮件发送、最终提交、取消或公开发布；绝不在聊天、文件或 shell 参数中请求/打印/存储明文凭据；绝不绕过法律、到场验证、CAPTCHA、身份核验或电子签名边界。

二、环境准备：安装并验证 rhwp 原生 CLI

本技能的前置条件只有一个硬性依赖——rhwpCLI 二进制存在于PATH。两条安装路径：

# 路径一：Rust 工具链源码构建（Rust 1.75+，原生构建） # 原生构建的完整子命令集可用，包括 PDF export cargo install rhwp # 路径二：上游发布页的预构建平台二进制（按平台是否提供而定） # 从上游 rhwp 发布页下载对应平台二进制，加入 PATH

安装后先做一次性验证，确认子命令列表能正常打印：

command -v rhwp || cargo install rhwp rhwp --help | head

其余前置：输出目录/文件需有写权限；若要用export-pdf，需对照上游文档确认该子命令的附加要求（见后文「失败模式」中 PDF 仅限原生构建的说明）。

输入要素（Inputs）：

• 输入 HWP/HWPX 文件路径；
• 子命令所需的坐标（section/段落 index）或页码；
• 部分子命令需要的输出路径。

三、子命令路由总览（v0.7.3 基准）

原文档给出了一张完整的「目的 → 子命令 → 示例」路由表，这是本技能最核心的速查内容，完整继承如下：

需要特别强调的一点：v0.7.3 的rhwpCLI 没有编辑（edit/insert-text/save）子命令。凡是"改文档"的需求都不要在本技能内寻找命令，编辑统一走 rhwp-edit/SKILL.md（k-skill-rhwpCLI）。这正是 k-skill 把「编辑」与「调试」拆成两个技能的根本原因：上游rhwp仓库的定位是文件格式引擎，其 packages/k-skill-rhwp/README.md 也明确写到——本 Node 包不包装export-svg --debug-overlay、dump、ir-diff、thumbnail、convert这些调试命令，调试请用rhwp-advanced技能。

四、标准工作流与六大实操流程

原文档给出了标准工作流骨架，前两步是固定动作，第三步按目的分流。

第 1 步：安装确认（见上文验证命令）。

第 2 步：先用info摸清坐标范围——任何 dump/渲染类子命令都需要页码或 section/paragraph 坐标，info能一次性给出页数、section 数、所用字体以及表格/图片统计，坐标越界问题大多可以在此步避免：

rhwp info sample.hwp

第 3 步：按目的执行对应流程。

4.1 SVG 渲染异常时：带调试叠加层的导出

当页面渲染（SVG）看起来不对时，用--debug-overlay把段落/表格边界线和坐标标签可视化，快速定位问题区域：

mkdir -p out rhwp export-svg sample.hwp -o out/ -p 0 --debug-overlay open out/page-0.svg

叠加层会绘制段落/表格边界线，并标注形如s{sec}:pi={idx} y={y}的坐标标签（section 编号、paragraph 索引、y 坐标），让「SVG 在哪一行、哪个段落开始走样」一目了然。

4.2 需要细看某页布局时：分页转储

rhwp dump-pages sample.hwp -p 2

输出该页的页面化结果，用于确认段落分布、分页断点是否符合预期。

4.3 表格看起来损坏时：IR 结构转储

通过 IR dump 检查单元格结构、ParaShape（段落形状）与LINE_SEG（行分割）等内部结构，定位表格截断的根因：

rhwp dump sample.hwp -s 0 -p 3

其中-s为 section 索引、-p为段落索引——这两个坐标就来自第 2 步的rhwp info。

4.4 两个版本结构比对：ir-diff

只想看结构层面的变更，不关心正文逐字差异时：

rhwp ir-diff draft-v1.hwp draft-v2.hwp > ir-diff.txt

输出是逐行的 delta：结构完全一致时输出几乎为空，有差异时呈现行级 diff。仓库文档 docs/features/rhwp-advanced.md 中还有一个补充操作——用wc -l ir-diff.txt快速量化差异规模。

4.5 提取封面缩略图：thumbnail

rhwp thumbnail sample.hwp -o cover.png # 需要 data URI 直接内嵌时追加 --data-uri rhwp thumbnail sample.hwp --data-uri

默认输出 PNG 文件；--data-uri模式直接把图片以 data URI 字符串输出，适合即时内嵌到 HTML/报告。

4.6 解锁发行版（只读）文档：convert

rhwp convert locked.hwp unlocked.hwp

转换后得到可编辑副本，后续编辑操作交由rhwp-edit技能的k-skill-rhwpCLI 执行。注意这是"解锁只读发行版文档"的唯一入口——k-skill-rhwp的 CLI 目前并不暴露 convertToEditable 类子命令（见 packages/k-skill-rhwp/README.md 的 Known limitations），所以这条路径只有本技能能覆盖。

五、输出验证清单与完成标准

每种子命令执行后都要按下列标准验证产出，这是把"跑过命令"升级为"拿到可信结果"的关键：

「完成标准（Done when）」分两种：

• 调试/检查目的：用户所需的结构/渲染信息已经打印出来，且明确记录是哪个子命令、带哪些 flag 生成的；
• 一次性转换目的（如convert）：产出文件已生成，且可用rhwp info重新确认。

六、失败模式与边界（排障手册）

原文档列出了 6 类典型失败，是实际使用中最容易踩的坑，完整继承并补充如下：

1. rhwp: command not found→ 尚未安装或未加入 PATH，先执行cargo install rhwp或安装发布二进制。
2. export-pdf失败→ PDF 导出只在原生构建下保证可用；@rhwp/core的 WASM 路径不支持。请确认当前运行的是cargo install安装的原生二进制，而非 WASM 封装。
3. HWPX 保存路径被上游禁用（rhwp #196）→rhwpCLI 自身被上游禁止把 HWPX 再导出为 HWPX（HWPX → HWP round-trip 允许，HWPX → HWPX 不允许）。需要保存的场景一律走 HWP 5.x 二进制格式。这一点与k-skill-rhwp的已知限制完全一致：packages/k-skill-rhwp/README.md 明确写到「HWPX input is accepted, but output is always written as HWP 5.x binary」。
4. 编辑子命令缺失→ v0.7.3 基准下rhwpCLI 不提供编辑命令，编辑请用 rhwp-edit/SKILL.md。
5. Windows 安全模块/한컴 GUI 自动化→ 超出本技能范围。rhwp是文件格式引擎，不是 GUI 控制器，不承担绕过安全模块的职责。
6. 版本漂移→ rhwp 开发活跃，子命令 flag 可能变更或新增。使用任何子命令前先执行rhwp <subcommand> --help确认当前版本的参数。仓库文档 docs/features/rhwp-advanced.md 记录了版本上下文：v0.7.3（2026-04-19 前后）。

七、结果汇报、隐私与技能协同

汇报规范：把结果附到 PR/报告时——SVG/PDF/缩略图直接附文件本身；dump 输出若过长，只引用前 200～500 行，全文作为附件提交；包含个人信息文档的正文文本必须脱敏（마스킹）。dump*与ir-diff的输出中可能混入原文文本，引用前务必检查。

隐私与敏感源文件保护：调试/转换对象若是个人资料、申报书等非公开文档，产出文件不要提交进仓库；写日志时也应对正文做摘要或脱敏（与 rhwp-edit/instruction.md 的敏感源保护规范一致）。

技能协同总结：本技能本质上是「安装指引 + 执行配方」型技能，面向快速调试；需要程序化（Node API）控制时改用k-skill-rhwp（编辑），需要 Markdown/JSON/表单字段转换时改用hwp（kordoc）。三者在 k-skill 仓库中边界清晰、互不重叠：调试查证 → rhwp-advanced/SKILL.md；二进制编辑 → rhwp-edit/SKILL.md；解析转换 → hwp/SKILL.md。技能发布说明与特性总览可进一步参考仓库 docs/features/rhwp-advanced.md，其与当前指令文档 rhwp-advanced/instruction.md 内容互相对应、互为镜像。

【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill