rhwp-edit 实战指南用 k-skill-rhwp CLI 对 HWP/HWPX 文档做 round-trip 安全的编辑【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本指南围绕 k-skill 仓库中的rhwp-edit技能展开它通过k-skill-rhwpCLI一个包装rhwp/coreRustWebAssembly 引擎的薄 Node 层实现对韩文 HWP 5.x 二进制文档的本体文本、表格结构与单元格内容的编辑。读完本文你将掌握从文档结构探查、坐标定位、文本插入/删除/全局替换、建表与写单元格到编辑后 round-trip 校验的完整实操链路并理解其底层 WASM 初始化、非重叠替换与大小写安全校验的实现原理。一、技能定位k-skill-rhwp是什么rhwp-edit是 k-skill 技能集中负责二进制编辑的文档类技能rhwp-edit/skill.json中category: documents、locale: ko-KR、phase: v1.5。它不直接处理 HWP 文件格式而是调用k-skill-rhwp包——一个把上游rhwp/coreRust WebAssemblyMIT 许可作者 Edward Kim封装为 Node 子命令的 CLI 包对应仓库目录为 packages/k-skill-rhwp包版本0.2.0见 package.json。核心编辑能力被暴露为如下子命令子命令功能insert-text在指定段落偏移处插入文本delete-text从指定段落偏移处删除 N 个字符replace-all全文档仅本文章段保持格式地替换字符串create-table在指定位置插入空表set-cell-text覆写或填充表格单元格内容create-blank生成全新的空 HWP 文件info/list-paragraphs探查文档结构区段/段落数、长度search定位查询串在正文中的坐标render将页面渲染为 SVG 或 HTML 用于预览所有编辑类子命令永远写入一个新文件绝不覆盖原文档——这是该技能 round-trip 安全设计的第一原则。与同仓库其他 HWP 技能的分工k-skill 将 HWP 能力拆成了三个互补技能rhwp-edit只做编辑转换/解析HWP → Markdown / JSON、表单字段提取、Markdown → HWPX使用hwp技能基于 kordoc见 hwp/SKILL.md。rhwp-edit是二进制编辑专用不负责格式转换。高级调试SVG 渲染叠加层、IR 结构 dump、版本对比、缩略图、只读文档解锁使用rhwp-advanced技能调用上游rhwpRust CLI见 rhwp-advanced/SKILL.md。编辑本文主角rhwp-edit即k-skill-rhwpCLI。二、适用场景与回避边界何时使用rhwp-edit“给 HWP 正文加一行文字”“保持格式不变把 2025 全部替换成 2026”“在 HWP 里插入一个 3 行 4 列的表格”“改写表格里某个单元格的内容”“生成一个空的 HWP 新文件”何时不应使用应转向其他技能或明确拒绝HWP → Markdown / JSON 转换走hwp技能kordoc。rhwp-edit只做二进制编辑。HWPX 原样输出 HWPX上游 rhwp 目前以#196关闭了 HWPX 保存路径以rhwp-edit/instruction.md记载为准rhwp v0.7.3。HWPX 输入会被内部提升为 HWP IR 后只能保存为 HWP 5.x 二进制确实需要 HWPX 输出时应使用 kordoc 的markdownToHwpx。排版/渲染调试分页、SVG 渲染叠加层走rhwp-advanced使用上游rhwpCLI 的export-svg --debug-overlay、dump-pages、ir-diff。高级检查命令只读发行文档解锁、IR 结构 dump、缩略图提取参考rhwp-advanced。Hancom Office GUI 自动化、安全模块绕过、Windows 专有格式明确超出范围。rhwp是文件格式引擎不是 GUI 控制器。三、前置条件与安装Node.js 18k-skill-rhwp在package.json中声明engines: { node: 18 }。具有写权限的输出路径编辑结果总是写到新路径。安装k-skill-rhwp三选一# 一次性运行无需全局安装 npx --yes k-skill-rhwp --help # 全局安装 npm install -g k-skill-rhwp # 项目内局部安装 npm install k-skill-rhwpk-skill-rhwp把rhwp/core^0.7.3作为直接依赖非 peer dependency引入安装时自动带上无需另行安装。不需要 Rust/Cargo 工具链——WASM 二进制随 npm 包分发Node 端直接加载执行。想使用上游rhwpRust CLI 时另行参考rhwp-advanced。四、核心输入参数详解k-skill-rhwp的输入可以分为四类完整参数与默认值在 cli.js 的 USAGE 中有权威定义1. 文件路径输入 HWP / HWPX 路径绝对或相对CLI 内部会path.resolve。输出 HWP 路径必须与输入不同原文件永不被覆盖。2. 文本编辑坐标作用于本文章段--section N区段索引从 0 开始。--paragraph N段落索引从 0 开始。--offset N段落内的字符偏移从 0 开始。--count N仅delete-text要删除的字符数。3. 表格坐标--parent-paragraph N包含表格的段落索引表格在 HWP 中作为段落内控制符存在。--control N控制符索引段落内第 N 个控制对象。--cell N单元格索引。--cell-paragraph N可选默认 0单元格内的段落索引。create-table另需--rows N --cols N。4. 文本与查询参数--text ...要插入/写入的文本。--query ...搜索/替换目标串。--replacement ...替换结果串。--case-sensitive开启大小写敏感匹配默认大小写不敏感。--no-replaceset-cell-text专用保留单元格已有内容、改为追加而非覆写。--format svg|htmlrender专用默认 svg、--page N默认 0。CLI 对数值参数有严格校验requireFlag要求必须是非负整数否则报错--section must be a non-negative integer见 cli.js。参数支持--name value与--namevalue两种写法。五、操作路由策略任务到命令的映射rhwp-edit/instruction.md给出的路由策略是 Agent 使用该技能时的决策表按“用户意图 → 首选命令”组织任务首选命令向本文章段插入文本k-skill-rhwp insert-text从本文章段删除文本k-skill-rhwp delete-text简单全局替换保持格式仅本文章段k-skill-rhwp replace-all --query ... --replacement ...替换前先定位命中位置仅本文章段k-skill-rhwp search --query ... --from-section N --from-paragraph N查看表格单元格内的文本k-skill-rhwp list-paragraphs定位表格坐标后用set-cell-text直接写入插入空表k-skill-rhwp create-table --rows N --cols N替换/填充单元格内容k-skill-rhwp set-cell-text --control N --cell N --text ...创建空 HWPk-skill-rhwp create-blank output.hwp结构探查区段/段落数与长度k-skill-rhwp info file/list-paragraphs页面 SVG/HTML 预览k-skill-rhwp render file --page N --format svg结果契约所有编辑子命令都会返回一行 JSONCLI 下 pretty-print包含ok: true、编辑后的新光标位置charOffset、paraIdx、controlIdx、实际写入的字节数bytesWritten、以及输出路径outputPath。后续调用如set-cell-text复用create-table返回的坐标应直接消费这些字段。六、标准工作流从探查到 round-trip 校验rhwp-edit/instruction.md定义了五步标准流程任何编辑任务都应遵循第 1 步输入检查。先运行k-skill-rhwp info input拿到sourceFormathwp/hwpx、sectionCount、各区段的paragraphCount与每个段落的length。编辑坐标全部以这份结构数据为来源避免盲猜越界。info的实现见 index.js它通过 WASM 的getSectionCount/getParagraphCount/getParagraphLength逐区段、逐段落枚举出{paragraphIndex, length}数组。第 2 步需要定位时先搜索。运行k-skill-rhwp search input --query 2025拿到区段/段落/字符偏移再把坐标原样填进编辑命令。第 3 步执行编辑。按任务匹配第五节的命令。下面是一组可复制的完整示例# 1) 创建空白文档 npx k-skill-rhwp create-blank ./out/blank.hwp # 2) 在正文第一段开头插入标题 npx k-skill-rhwp insert-text ./in.hwp ./out/with-title.hwp \ --section 0 --paragraph 0 --offset 0 \ --text 2026년 오픈소스 AI·SW 지원사업 신청서 # 3) 全文档 2025 → 2026 批量替换 npx k-skill-rhwp replace-all ./in.hwp ./out/2026.hwp \ --query 2025 --replacement 2026 # 4) 在正文第 2 段末尾插入 3 行 4 列表格 npx k-skill-rhwp create-table ./in.hwp ./out/with-table.hwp \ --section 0 --paragraph 1 --offset 0 --rows 3 --cols 4 # 5) 向刚创建的表格 (0,0) 单元格写入 합계 # —— 直接复用 create-table 结果中的 paraIdx / controlIdx npx k-skill-rhwp set-cell-text ./out/with-table.hwp ./out/with-cell.hwp \ --section 0 --parent-paragraph paraIdx --control controlIdx \ --cell 0 --text 합계第 4 步round-trip 校验。编辑完成后立即再次运行k-skill-rhwp info output肉眼核对paragraphs[].length或paragraphCount是否符合预期必要时k-skill-rhwp render output --page 0 --format html做一次 sanity check确认首页能正常渲染出字符串。第 5 步敏感原稿保护。如果编辑对象是个人隐私信息、事业申请书等非公开文档生成文件不要提交进仓库写日志时对正文做摘要或打码masking。七、源码级原理k-skill-rhwp 是如何做到的1. WASM 惰性初始化与 measureTextWidth shimrhwp/core是为浏览器设计的 ESM WASM 包Node 环境有两个痛点都由 wasm-init.js 解决文本度量回调缺失WASM 排版换行、两端对齐需要globalThis.measureTextWidth(font, text)浏览器用canvas2D context 实现而 headless Node 没有 Canvas。该模块在首次使用时自动注入确定性近似 shimCJK 全角码点按字号计宽、拉丁/数字按0.55 × 字号计宽见 wasm-init.js。这对 round-trip 编辑和冒烟测试足够精确但不应用于像素级渲染。WASM 二进制定位默认init(undefined)依赖import.meta.url与fetch()Node 下无法指向本地文件。k-skill-rhwp改用require.resolve(rhwp/core/rhwp_bg.wasm)拿到随包分发的 WASM 字节流再显式传给core.default({ module_or_path: wasmBytes })全程无网络 I/Owasm-init.js。getRhwpCore()是惰性单例首次调用缓存 Promise后续调用复用同一实例WASM 每个进程只初始化一次。测试用例也验证了 shim 幂等安装与 WASM 路径可解析见 test/index.test.js。2. round-trip 安全与 JSON 结果契约每个编辑动作都遵循“加载 → 操作 →exportHwp()导出 → 写新文件”的管线见 index.js。parseJsonResult会检查 WASM 返回的 JSON 中ok必须为true否则抛出该操作被 rhwp 拒绝的异常index.js把引擎层的失败显式暴露给调用方而不是静默产出损坏文件。3. replace-all 的非重叠替换与安全校验replaceAll的实现index.js有三处值得注意的语义非重叠匹配findAllMatchOffsets在原始文本上按indexOf顺序收集命中偏移i idx needle.length前进替换时从后往前逐次执行replaceText保证新增替换文本不会被再次匹配例如a → aa处理aaa得到aaaaaa不会死循环。换行/分段拒绝--replacement若包含\n、\r、U2028、U2029CLI 直接 exit code 1 并报replacement must not contain newline or paragraph-break characters。需要生成多段落时应拆成多次insert-text调用。大小写折叠安全护栏默认大小写不敏感模式依赖String.prototype.toLowerCase()保持 UTF-16 长度不变这样在折叠后文本上收集的偏移才能安全映射回原文。土耳其语İ(U0130) 小写化后会变成i 组合点(U0307)、长度1会漂移后续所有偏移。当 query 或任意段落命中这类字符时replace-all拒绝执行exit code 1消息case-insensitive matching is unsafe because case folding changes the UTF-16 length而不是静默损坏文档。此时应改用--case-sensitive重跑或预先归一化输入。韩文与 ASCII 文本不受影响2025 → 2026这类典型申请书流程完全无碍。4. search / replace-all 的作用域边界上游searchText被限定在正文body范围因此search与replace-all只扫描本文章段。表格单元格内文本、页眉/页脚、脚注正文都不会被命中search返回found:falsereplace-all不触碰。处理单元格内容时必须先靠info/list-paragraphs定位表格坐标再用set-cell-text直接写入README 对此有同样的 Scope 说明见 README.md。5. set-cell-text 的替换语义setCellTextindex.js默认replace: true先查询单元格段落长度若大于 0 则deleteTextInCell清空再insertTextInCell写入新文本传入--no-replace时跳过删除步骤实现追加语义。因此“覆写”与“追加”两种需求都能覆盖。八、Node API在代码中直接编辑不想走 CLI 时同一个包可作库使用导出的函数与子命令一一对应完整导出清单见 index.jsconst { insertText, getDocumentInfo } require(k-skill-rhwp); await insertText({ input: ./in.hwp, output: ./out.hwp, section: 0, paragraph: 0, offset: 0, text: 안녕하세요 }); console.log(await getDocumentInfo(./out.hwp));使用前提Node 18rhwp/coreWASM 首次调用时初始化一次globalThis.measureTextWidth回调由包自动 shim开箱即用——需要像素级精确排版时在首次调用前自行注入 node-canvas 版 shim 覆盖即可。九、每次运行后的验证清单与完成标准rhwp-edit/instruction.md要求每次编辑后核验返回的ok true且bytesWritten至少为 KB 级数 KB 以上排除空导出。重新调用info区段/段落数量与长度变化符合预期。表格场景下create-table返回的paraIdx/controlIdx原样传入下一次set-cell-text。输出文件路径与原文件不同原文件保持不动。Done when完成标准用户请求的编辑已反映到 HWP 二进制并以新文件保存k-skill-rhwp info output返回相同或增加的sectionCount/paragraphCount以及预期的段落length原文件未被触碰。十、失败模式与边界条件rhwp-edit明确列出的失败场景接入前应心中有数HWPX 无法保存回 HWPXrhwp #196HWPX → HWPX 的 round-trip 被上游禁用HWPX 输入最终只会保存为 HWP。不要依赖源文件扩展名始终以.hwp输出。坐标越界section/paragraph/offset超出文档范围时WASM 抛出类似렌더링 오류: 구역 인덱스 0 범위 초과渲染错误区段索引 0 越界的错误CLI exit code 1 并在 stderr 打印消息。编辑前务必用info确认坐标。复杂对象 round-trip 偶发失真是 beta 风险上游 rhwp v0.7.x 处于 beta复杂表格、图片、图表、表单字段较多的真实申请书在 HWP round-trip 时可能罕见地出现格式损失。复杂编辑结束后建议render输出并肉眼复核。只读分发用文档rhwp 自身通过convertToEditable支持解锁但k-skill-rhwp的子命令尚未暴露该能力需要时走rhwp-advanced的上游rhwp convert路径。WASM 初始化延迟rhwp/core的 WASM约 4 MB在首次调用时解析一次第一次调用可能有数十到数百毫秒延迟。文件编码韩文文本直接按 UTF-8 传给 CLI 即可shell 引号异常时可改用--text$...形式。search / replace-all 的作用域限制不覆盖表格单元格、页眉页脚、脚注已在第七节详述。大小写不敏感匹配的 Unicode 长度约束命中如İ这类折叠改变 UTF-16 长度的字符时命令被拒绝详见第七节。十一、技能生态与维护提示用hwp技能做格式转换与字段提取用rhwp-advanced做高级调试与解锁用rhwp-edit做日常编辑三者按需路由。上游 rhwp 仍在活跃开发k-skill-rhwp以 semver caret 固定rhwp/core^0.7.3依赖包自身版本0.2.0存在 breaking change 可能安装后建议关注CHANGELOG.md见 packages/k-skill-rhwp/CHANGELOG.md。技能完整指令始终以仓库内的 rhwp-edit/instruction.md 与 packages/k-skill-rhwp/README.md 为权威来源rhwp-edit/SKILL.md为生成的 CLI stub 入口实际内容以instruction.md为准。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考