k-skill 项目 rhwp-edit 技能实战基于 k-skill-rhwp CLI 的 HWP 文档安全编辑指南【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill本指南以 k-skill 仓库中rhwp-edit技能的核心说明文档为主干系统讲解如何借助k-skill-rhwpCLI基于 Rust WebAssembly 的rhwp/core引擎的薄 Node 封装对韩文办公文档 HWPHangul Word Processor进行 round-trip 安全的正文文本、表格结构、单元格内容编辑。读完本文你将掌握从安装、坐标定位、文本插入/删除/全文替换、建表与填单元格到输出验证与异常规避的完整实战闭环并理解其底层 WASM 初始化与 Unicode 安全机制。rhwp-edit 技能定位编辑专用不做转换k-skill-rhwp是一个 Node CLI对.hwp文档执行本内容编辑insertText、deleteText、replaceAll、createTable、setCellText 等每次编辑结果总是写入一个新文件绝不覆盖原文件。该技能是编辑专用的与仓库中其他技能形成明确分工HWP → Markdown / JSON 转换、字段提取使用 hwp 技能基于 kordoc页面渲染调试、IR 结构比较使用 rhwp-advanced 技能调用上游 rhwp CLI 的export-svg --debug-overlay、dump-pages、ir-diff等高级命令部署用只读文档解锁、IR 结构 dump、缩略图提取也归属rhwp-advanced技能한컴 오피스 GUI 自动化、安全模块、Windows 专用格式明确不在范围内——rhwp 是文件格式引擎不是 GUI 控制器。典型适用场景When to use向 HWP 正文追加一行、在保留原有格式的前提下把 2025 批量替换为 2026、向 HWP 插入 3×4 表格、修改表格特定单元格内容、生成一份空白 HWP 新文件。一个关键的边界约束以 HWPX 为输入时内部会上行到 HWP IR但输出只保存为 HWP 5.x 二进制——上游 rhwp 在#196中禁用了 HWPX → HWPX 的保存路径因此输出文件名应始终使用.hwp扩展名不要依赖源文件扩展名。环境准备与安装根据 rhwp-edit 技能目录 及 packages/k-skill-rhwp 的说明前置条件如下Node.js 18packages/k-skill-rhwp/package.json中engines.node: 18明确声明具有写入权限的输出目录无需 Rust/Cargo 工具链WASM 已随包分发如需使用上游 rhwp Rust CLI请走rhwp-advanced技能。k-skill-rhwp的安装方式三选一# 一次性使用 npx --yes k-skill-rhwp --help # 全局安装 npm install -g k-skill-rhwp # 本地安装 npm install k-skill-rhwp依赖关系上k-skill-rhwp以普通 dependency而非 peerDependency引入rhwp/core^0.7.3见 package.json因此无需单独安装rhwp/core。上游 rhwp 仍处于活跃开发中v0.7.32026-04-19 时点为容纳可能的 breaking change依赖使用 semver caret^锁定。命令总览与输入参数CLI 的帮助文本见 cli.js 中的USAGE列出全部子命令命令功能info input以 JSON 输出文档结构信息list-paragraphs input [--section N]列出指定区段内各文段的长度search input --query TEXT [--from-section N] [--from-paragraph N] [--from-char N]向前查找首个匹配位置仅正文文段insert-text input output --section N --paragraph N --offset N --text TEXT在正文文段插入文本delete-text input output --section N --paragraph N --offset N --count N从正文文段删除指定数量字符replace-all input output --query TEXT --replacement TEXT [--case-sensitive]全文替换仅正文文段拒绝含换行的替换串create-table input output --section N --paragraph N --offset N --rows N --cols N插入空表set-cell-text input output --section N --parent-paragraph N --control N --cell N --text TEXT [--cell-paragraph N] [--no-replace]写入/替换单元格文本create-blank output生成空白 HWP 文档render input [--page N] [--format svg\|html]将指定页渲染为 SVG/HTML 输出到 stdout核心输入参数归纳输入输出路径input可为绝对或相对路径output必须是不同于原文件的路径正文编辑坐标--section N --paragraph N --offset N区段、文段、字符偏移均从 0 开始表格坐标--section N --parent-paragraph N --control N --cell N [--cell-paragraph N]文本/查询--text ...、--query ...、--replacement ...create-table尺寸--rows N --cols N选择开关--case-sensitive大小写敏感匹配、--no-replaceset-cell-text保留已有单元格内容、仅在末尾追加、--format svg|htmlrender输出格式。全局选项--json机器可读 JSONinfo/list/search默认即 JSON、--help, -h、--version, -v。路由策略什么任务走哪个命令技能说明中给出了一张任务 → 默认命令的速查表是 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。这一约定贯穿所有编辑命令是后续自动化脚本依赖的稳定契约。端到端工作流附完整命令示例技能说明给出五步工作流逐条展开如下。第 1 步输入检查。先运行k-skill-rhwp info input确认sourceFormathwp/hwpx、sectionCount、各区段paragraphCount及每文段的length。所有编辑坐标都应从该输出中提取。从源码看index.js 中的getDocumentInfo会逐区段逐文段调用getParagraphCount/getParagraphLength并把文档自带元数据getDocumentInfoJSON一并返回。第 2 步按需搜索。需要定位替换目标时用k-skill-rhwp search input --query 2025拿到区段/文段/字符偏移再原样填入编辑命令。第 3 步执行编辑。根据任务选一个子命令--output始终指向与原件不同的路径# 生成空白文档 npx k-skill-rhwp create-blank ./out/blank.hwp # 在正文首个文段开头插入标题 npx k-skill-rhwp insert-text ./in.hwp ./out/with-title.hwp \ --section 0 --paragraph 0 --offset 0 \ --text 2026년 오픈소스 AI·SW 지원사업 신청서 # 2025 → 2026 全文替换 npx k-skill-rhwp replace-all ./in.hwp ./out/2026.hwp \ --query 2025 --replacement 2026 # 在正文第 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 # 向刚建表格的 (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 합계这里特别值得强调表插入 → 填单元格的链路create-table的结果 JSON 中带paraIdx与controlIdx必须原样作为set-cell-text的--parent-paragraph与--control传入。测试 index.test.js 中的setCellText fills a cell after creating a table正是这一链路的端到端验证。第 4 步round-trip 校验。编辑完成后再次调用k-skill-rhwp info output人工核对期望的paragraphs[].length或paragraphCount变化必要时用k-skill-rhwp render output --page 0 --format html确认第一页能正常生成渲染字符串sanity check。第 5 步敏感原件保护。若编辑对象涉及个人信息、事业申请书等非公开文档不要把生成文件提交到仓库写入日志时也要对正文做摘要与掩码处理。从源码理解参数解析与校验k-skill-rhwp的命令行由 cli.js 中的parseArgs自行实现不依赖 commander/yargs。它支持三种取值形式--flag value、--flagvalue、纯布尔--flag并支持--终止符把剩余 token 视为位置参数——这一行为由测试parseArgs handles positional args, --flag value, --flagvalue, and boolean flags覆盖。值得注意的校验逻辑requireFlag强制必填项insert-text/delete-text/create-table/set-cell-text的--section、--paragraph、--offset等必须是非负整数否则报错--X must be a non-negative integerdeleteText要求count为正整数Number.isInteger(count) count 0insertText要求text为非空字符串createTable要求rows/cols为正整数index.js——校验失败时不会写出任何输出文件测试明确断言fs.existsSync(dst) false参数解析失败或子命令执行抛错时main捕获异常、向 stderr 打印k-skill-rhwp: message并以 exit code 1 退出unknown command场景由测试覆盖。底层引擎WASM 懒初始化与 measureTextWidth shimrhwp/core是面向浏览器的 ESM 包Rust 编译为 WASM在 Node 中直接使用会遇到两个障碍均由 wasm-init.js 解决WASM 二进制加载默认init()路径依赖import.meta.url与fetch()在 Node 中无法定位本地文件。该模块改用require.resolve(rhwp/core/rhwp_bg.wasm)解析随包分发的 WASM测试断言该路径存在且大于 1 MB把字节数组显式交给core.default({ module_or_path: wasmBytes })完全绕开网络 I/O文本度量回调WASM 进行换行/两端对齐排版时需要globalThis.measureTextWidth(font, text)浏览器用 Canvas 2D 实现无头 Node 没有 Canvas。该模块在首次调用时自动安装一个确定性近似 shimCJK/全角码点U1100–UFFDC按约一字宽 字号计拉丁字母按约 0.55 倍字号计测试installMeasureTextWidthShim installs a deterministic shim only once验证了 CJK 宽度 Latin 宽度。这个近似值对 round-trip 编辑与冒烟测试足够但不要依赖它做像素级精确渲染需要精确排版时应在首次调用前自行注入基于 node-canvas 的 shimshim 存在时不会被覆盖用户注入者优先。懒初始化通过模块级initPromise缓存保证 WASM每个进程只初始化一次测试getRhwpCore returns a cached module...验证了缓存语义。首次调用会解析约 4 MB 的 WASM 包可能带来数十至数百毫秒的启动延迟。Node API把编辑嵌入代码而非命令行如果不想走 CLI同一个包可以作为库直接调用。技能文档给出如下示例const { 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));index.js 导出的完整 API 集合为getDocumentInfo、insertText、deleteText、replaceAll、searchText、createTable、setCellText、createBlank、listParagraphs、renderPage、parseJsonResult以及底层loadDocument/writeHwp。每个编辑函数都遵循同一模式加载 HWP → 调用 WASM 方法 →parseJsonResult校验ok true→writeHwp导出为新文件 →finally中doc.free()释放 WASM 内存。其中replaceAll是纯 JS 层实现逐区段逐文段读取getTextRange用findAllMatchOffsets计算匹配偏移见下文匹配语义再倒序调用replaceText回写。Node 侧同样要求 Node 18WASM 首次调用时初始化一次无需额外配置。每次运行后的输出验证Verify outputs技能文档列出的验收清单与源码契约一一对应ok true且bytesWritten至少数 KB空白文档测试断言bytesWritten 1024重新运行info后区段/文段数量与长度变化符合预期如insertText测试断言文段长度等于插入文本长度建表后paraIdx/controlIdx能直接用于下一次set-cell-text调用见 index.test.js 的建表→填单元格用例输出文件与原文件路径不同且原件未被改动replaceAll测试用 SHA-1 断言mid与dst字节不同。完成标准Done when用户请求的编辑已落到 HWP 二进制并保存为新文件k-skill-rhwp info output返回相同或增大的sectionCount/paragraphCount以及期望的length原文件完好无损。故障模式与边界条件技能文档详细列出十余种故障模式是实操中最重要的避坑清单HWPX 无法保存为 HWPX上游 #196HWPX 输入会被内部转成 HWP IR 后仅保存为 HWP 5.x 二进制。不要依赖源文件扩展名输出始终用.hwp。确实需要 HWPX 输出时改用 kordoc 的markdownToHwpx属hwp技能范畴。坐标越界section/paragraph/offset超出实际文档范围时WASM 抛出类似렌더링 오류: 구역 인덱스 0 범위 초과的错误CLI 以 exit code 1 stderr 消息退出。因此编辑前务必先用info确认坐标。复杂内容 round-trip 有损rhwp v0.7.x 仍是 beta包含复杂表格、图片、图表、表单字段的真实事业申请书在 round-trip 时可能偶发格式损失。建议编辑后执行k-skill-rhwp render output加肉眼复核。部署用只读文档rhwp 本身通过convertToEditable支持解锁但k-skill-rhwpCLI 尚未暴露该子命令需要时走rhwp-advanced技能的上游rhwp convert路径。WASM 首次初始化延迟约 4 MB 的 WASM 首次调用才解析头一次调用可能有数十至数百毫秒延迟。文件编码韩文文本直接以 UTF-8 传给 CLI 即可若 shell 中引号被破坏用--text$...这类形式。search/replace-all只扫正文文段上游searchText作用域限定在正文bodyk-skill-rhwp replace-all遵循相同范围。表格单元格内文本、页眉/页脚、脚注正文中search返回found:falsereplace-all也不会触碰。单元格内容为目标时用list-paragraphs或info定位表坐标后以set-cell-text直接写。CLI 帮助文本也明确注明了这一范围Scope noteREADME.md 有同样说明。段落边界/换行替换被禁止replace-all只保证单文段内的替换--replacement含换行\n、\r、U2028、U2029时 CLI 返回 exit code 1 与replacement must not contain newline or paragraph-break characters。需要跨段生成多段文本时多次调用insert-text。对应校验见 index.js 中的正则/[\n\r\u2028\u2029]/并有专门测试replaceAll rejects replacement containing newlines。替换基于原始匹配、non-overlapping匹配先对原文整体计算替换引入的新字符串不再参与匹配。例query a / replacement aa / 原文 aaa会把每个原始a各替换一次得到aaaaaa不会死循环。测试replaceAll handles replacement containing the query without infinite loop覆盖此语义断言 count3、长度6。大小写不敏感匹配的 UTF-16 长度安全护栏默认不加--case-sensitive模式基于String.prototype.toLowerCase()保持 UTF-16 长度不变的假设来计算偏移。土耳其语İU0130小写化为i 组合附点U0307长度会增长当正文或查询含此类字符时为避免偏移漂移导致的静默文档损坏replace-all直接拒绝执行exit code 1 case-insensitive matching is unsafe because case folding changes the UTF-16 length。对策改用--case-sensitive重跑或先对输入做归一化。韩文/ASCII 正文不受影响2025 → 2026这类事业申请书工作流完全安全。测试对该护栏做了专门回归验证拒绝时不写出任何输出文件且--case-sensitive路径可正常完成count2X字符不被破坏。技能生态与结论在 k-skill 仓库中文档处理能力由三兄弟分工rhwp-edit二进制编辑、hwpkordoc 转换/字段提取、rhwp-advanced上游 rhwp CLI 高级调试。k-skill-rhwp是三者中编辑能力的承载者其实现位于 packages/k-skill-rhwp通过 index.test.js 与 cli.test.js 提供覆盖插入、删除、替换等长/变长/删空/大小写/Unicode 安全、建表、填单元格、渲染的全链路测试保障。实际使用时的核心心法是先info后编辑、坐标取自info/search、输出永远新文件、编辑后inforender双验证。这套方法论把 WASM 引擎的编辑能力封装成了稳定、可审计、可脚本化的命令行契约让 Agent 可以在不接触 Rust 工具链的前提下安全地完成 HWP 文档的批量自动化编辑。【免费下载链接】k-skill한국인을 위한 스킬 모음집 - 에이전트를 한국인으로项目地址: https://gitcode.com/GitHub_Trending/ks/k-skill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考