rhwp-edit
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chineserhwp-edit
rhwp-edit
What this skill does
本技能的功能
k-skill-rhwp.hwp@rhwp/coreinsertTextdeleteTextreplaceAllcreateTablesetCellText이 스킬은 편집 전용이다. 문서를 Markdown/JSON으로 변환하거나 필드만 추출하려면 스킬을 사용한다.
페이지 렌더링 디버깅이나 IR 비교가 필요하면 스킬을 사용한다.
hwprhwp-advanced通过 CLI可安全地往返编辑文档的正文文本、表格结构、单元格内容。
CLI在(Rust + WebAssembly)基础上封装了一层轻量Node包装器,将、、、、等编辑操作以子命令形式提供。编辑结果始终保存为新文件。
k-skill-rhwp.hwp@rhwp/coreinsertTextdeleteTextreplaceAllcreateTablesetCellText本技能为编辑专用。若需将文档转换为Markdown/JSON或仅提取字段,请使用技能。
若需页面渲染调试或IR对比,请使用技能。
hwprhwp-advancedWhen to use
使用场景
- "HWP 본문에 한 줄 추가해줘"
- "서식은 유지한 채로 2025를 2026으로 일괄 치환해줘"
- "3행 4열짜리 표를 HWP에 넣어줘"
- "표의 특정 셀 내용을 바꿔줘"
- "빈 HWP 새 파일을 만들어줘"
- "在HWP正文中添加一行"
- "保留格式的同时将2025批量替换为2026"
- "在HWP中插入3行4列的表格"
- "修改表格特定单元格的内容"
- "创建新的空白HWP文件"
When not to use
不适用场景
- HWP → Markdown / JSON 변환 → 스킬(kordoc)을 쓴다. rhwp-edit은 바이너리 편집 전용이다.
hwp - HWPX 원본을 다시 HWPX로 저장 → rhwp v0.7.3 기준 업스트림이 으로 HWPX 저장 경로를 막아둔 상태다. HWPX를 입력으로 주면 내부적으로 HWP IR로 올라온 뒤 HWP 5.x 바이너리로만 저장된다. HWPX 출력이 꼭 필요하면 kordoc
#196를 쓴다.markdownToHwpx - 레이아웃(페이지네이션·SVG 렌더) 디버깅 → 스킬로 업스트림
rhwp-advancedCLI(rhwp,export-svg --debug-overlay,dump-pages)를 사용한다.ir-diff - 배포용(읽기전용) 잠금 해제 · IR 구조 덤프 · 썸네일 추출 등 고급 검사 명령 → 스킬 참조.
rhwp-advanced - 한컴 오피스 GUI 자동화, 보안모듈 통과, Windows 전용 서식 → 범위 밖이다. 는 파일 포맷 엔진이지 GUI 제어가 아니다.
rhwp
- HWP → Markdown/JSON转换 → 使用技能(kordoc)。rhwp-edit仅用于二进制编辑。
hwp - 将HWPX原文件重新保存为HWPX → 截至rhwp v0.7.3,上游通过禁用了HWPX保存路径。 若输入为HWPX,内部会先转换为HWP IR,最终仅保存为HWP 5.x二进制文件。若必须输出HWPX,请使用kordoc的
#196。markdownToHwpx - 布局(分页·SVG渲染)调试 → 使用技能调用上游
rhwp-advancedCLI的rhwp、export-svg --debug-overlay、dump-pages命令。ir-diff - 解除发布用(只读)锁定·导出IR结构·提取缩略图等高级检查命令 → 参考技能。
rhwp-advanced - 韩方Office GUI自动化、安全模块认证、Windows专属格式 → 超出本技能范围。是文件格式引擎,而非GUI控制工具。
rhwp
Prerequisites
前置条件
- Node.js 18+
- 쓰기 권한이 있는 출력 경로
- 설치(셋 중 하나):
k-skill-rhwp- 일회성:
npx --yes k-skill-rhwp --help - 전역:
npm install -g k-skill-rhwp - 로컬:
npm install k-skill-rhwp
- 일회성:
- 는
k-skill-rhwp을 peer 없이 dependency로 끌어온다. 별도 설치 불필요.@rhwp/core@^0.7.3 - Rust/Cargo toolchain 불필요. 업스트림 CLI를 같이 쓰고 싶으면
rhwp스킬로.rhwp-advanced
- Node.js 18+ -具备写入权限的输出路径
- 安装(三种方式任选其一):
k-skill-rhwp- 一次性使用:
npx --yes k-skill-rhwp --help - 全局安装:
npm install -g k-skill-rhwp - 本地安装:
npm install k-skill-rhwp
- 一次性使用:
- 已将
k-skill-rhwp作为依赖引入,无需单独安装。@rhwp/core@^0.7.3 - 无需Rust/Cargo工具链。若需同时使用上游CLI,请使用
rhwp技能。rhwp-advanced
Inputs
输入参数
- 입력 HWP / HWPX 경로 (절대 또는 상대)
- 출력 HWP 경로 (항상 별도 파일. 원본을 덮어쓰지 않는다.)
- 편집 좌표:
--section N --paragraph N --offset N - 표 좌표:
--section N --parent-paragraph N --control N --cell N [--cell-paragraph N] - 텍스트/쿼리: ,
--text "...",--query "..."--replacement "..." - :
create-table--rows N --cols N - 선택 플래그: ,
--case-sensitive(--no-replace에서 기존 셀 내용 보존),set-cell-text(--format svg|html)render
- 输入HWP/HWPX路径(绝对或相对路径)
- 输出HWP路径(始终为独立文件,不会覆盖原文件)
- 编辑坐标:
--section N --paragraph N --offset N - 表格坐标:
--section N --parent-paragraph N --control N --cell N [--cell-paragraph N] - 文本/查询内容:、
--text "..."、--query "..."--replacement "..." - 参数:
create-table--rows N --cols N - 可选标志:、
--case-sensitive(--no-replace中保留原有单元格内容)、set-cell-text(--format svg|html命令)render
Routing policy
路由策略
| 작업 | 기본 경로 |
|---|---|
| 본문 문단에 텍스트 삽입 | |
| 본문 문단에서 텍스트 삭제 | |
| 단순 전체 치환(같은 서식 유지, 본문 문단만) | |
| 치환 대상 위치 사전 조회(본문 문단만) | |
| 표 셀 안의 텍스트 확인 | |
| 빈 표 삽입 | |
| 표 셀 내용 교체/채우기 | |
| 빈 HWP 생성 | |
| 구조 파악(섹션/문단 수·길이) | |
| 페이지 SVG/HTML 미리보기 | |
모든 편집 서브커맨드는 결과를 JSON 한 줄(CLI에서는 pretty-print)로 돌려준다. , 새 커서 위치(, , ),
저장된 바이트 수(), 출력 경로() 를 포함한다.
ok: truecharOffsetparaIdxcontrolIdxbytesWrittenoutputPath| 操作 | 默认命令路径 |
|---|---|
| 在正文段落插入文本 | |
| 删除正文段落中的文本 | |
| 简单全局替换(保留相同格式,仅针对正文段落) | |
| 预查询替换目标位置(仅针对正文段落) | |
| 查看表格单元格内的文本 | 先通过 |
| 插入空白表格 | |
| 替换/填充表格单元格内容 | |
| 创建空白HWP | |
| 查看文档结构(章节/段落数量·长度) | |
| 预览页面SVG/HTML | |
所有编辑子命令都会返回一行JSON(CLI端会进行格式化输出),包含、新光标位置(、、)、写入字节数()、输出路径()。
ok: truecharOffsetparaIdxcontrolIdxbytesWrittenoutputPathWorkflow
工作流程
-
입력 점검:로
k-skill-rhwp info <input>(hwp/hwpx),sourceFormat, 섹션별sectionCount, 문단별paragraphCount를 먼저 확인한다. 편집 좌표는 이 결과에서 뽑는다.length -
검색이 필요한 경우:로 섹션/문단/문자 오프셋을 먼저 얻고, 편집 명령에 그대로 넣는다.
k-skill-rhwp search <input> --query "2025" -
편집: 아래 예시 중 해당하는 서브커맨드 하나로 실행한다.은 항상 원본과 다른 경로를 지정한다.
--outputbash# 빈 문서 만들기 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 # 3행 4열 표 삽입(본문 2번째 문단 끝) 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 "합계" -
round-trip 검증: 편집 직후를 다시 호출하고, 기대한
k-skill-rhwp info <output>또는paragraphs[].length변화를 직접 눈으로 확인한다. 필요하면paragraphCount로 첫 페이지 렌더 문자열이 생성되는지 sanity check 한다.k-skill-rhwp render <output> --page 0 --format html -
민감 원본 보호: 편집 대상이 개인정보/사업 신청서 등 비공개 문서라면 생성 파일을 레포에 커밋하지 않고, 로그에 남길 때도 본문을 요약·마스킹한다.
-
输入检查:先执行查看
k-skill-rhwp info <input>(hwp/hwpx)、sourceFormat、各章节的sectionCount、各段落的paragraphCount,编辑坐标需基于此结果确定。length -
需搜索的场景:执行获取章节/段落/字符偏移量,直接用于编辑命令。
k-skill-rhwp search <input> --query "2025" -
执行编辑:选择以下对应子命令执行。需指定与原文件不同的路径。
--outputbash# 创建空白文档 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 # 插入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 "合计" -
往返验证:编辑完成后再次执行,手动确认
k-skill-rhwp info <output>或paragraphs[].length是否符合预期变化。 必要时可执行paragraphCount,检查首页渲染字符串是否正常生成。k-skill-rhwp render <output> --page 0 --format html -
敏感原文件保护:若编辑对象为含个人信息/项目申请书等非公开文档,请勿将生成文件提交至仓库,记录日志时需对正文进行摘要或掩码处理。
Node API (선택)
Node API(可选)
CLI가 아니라 Node 코드에서 직접 편집하고 싶으면 같은 패키지를 라이브러리로 쓴다.
js
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"));Node 18+, WASM 은 첫 호출 시 한 번만 초기화된다. WASM 이 요구하는 콜백은 자동 shim 되므로 별도 설정 없이 돌아간다(정밀 레이아웃이 필요하면 기반 shim을 먼저 주입한다).
@rhwp/coreglobalThis.measureTextWidthnode-canvas若无需CLI,直接通过Node代码编辑,可将同一包作为库使用。
js
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"));需Node 18+, WASM仅在首次调用时初始化一次。WASM所需的回调会自动填充,无需额外配置(若需高精度布局,可先注入基于的填充逻辑)。
@rhwp/coreglobalThis.measureTextWidthnode-canvasVerify outputs after every run
每次运行后验证输出
- ,
ok === true가 수 KB 이상.bytesWritten - 재호출 결과에서 섹션/문단 수·길이 변화가 의도와 일치.
info - 표 삽입의 경우 /
paraIdx가 다음controlIdx호출에 그대로 들어간다.set-cell-text - 출력 파일이 원본과 다른 경로이며 원본은 그대로다.
- ,且
ok === true为几KB以上。bytesWritten - 再次调用返回的章节/段落数量·长度变化与预期一致。
info - 插入表格时返回的/
paraIdx可直接用于后续controlIdx调用。set-cell-text - 输出文件路径与原文件不同,原文件未被修改。
Done when
完成标准
- 사용자가 요청한 편집이 HWP 바이너리에 반영되어 새 파일로 저장됐다.
- 가 같은 혹은 늘어난
k-skill-rhwp info <output>/sectionCount와 기대paragraphCount를 돌려준다.length - 원본 파일은 건드리지 않았다.
- 用户要求的编辑操作已应用到HWP二进制文件,并保存为新文件。
- 返回的
k-skill-rhwp info <output>/sectionCount与预期一致或有所增加,且paragraphCount符合预期。length - 原文件未被修改。
Failure modes
失败场景
- HWPX 원본 저장 불가(rhwp #196): HWPX → HWPX round-trip 은 upstream에서 비활성화 상태다. HWPX 입력이라도 출력은 HWP로만 저장된다. 원본 확장자에 의존하지 말고 항상 로 저장한다.
.hwp - 좌표 범위 초과: 이 실제 문서 범위를 벗어나면 WASM에서
section/paragraph/offset같은 에러를 던지고 CLI는 exit code 1 + stderr 에 메시지를 찍는다. 편집 전에렌더링 오류: 구역 인덱스 0 범위 초과로 좌표를 확인한다.info - 복잡한 표·이미지·양식 필드 round-trip: 현재 업스트림 rhwp v0.7.x 는 베타다. 복잡한 표·이미지·차트·양식필드가 많은 실제 사업 신청서를 HWP round-trip 할 경우 드물게 형식 손실이 발생할 수 있다. round-trip 이 끝나면 + 육안 확인을 권장한다.
k-skill-rhwp render <output> - 배포용(읽기전용) 문서: rhwp 자체는 로 잠금 해제를 지원하지만
convertToEditableCLI 서브커맨드는 아직 노출하지 않는다. 필요하면k-skill-rhwp스킬의 업스트림rhwp-advanced경로를 쓴다.rhwp convert - WASM 초기화: 번들 WASM(
@rhwp/core4 MB) 은 최초 호출 시 한 번 파싱한다. 첫 호출은 수십 ms수백 ms 지연될 수 있다. - 파일 인코딩: 한국어 텍스트는 UTF-8 로 그대로 CLI 에 넘기면 된다. 셸에서 인용부호가 깨질 경우 같은 형식을 쓴다.
--text=$'...' - /
search은 본문 문단만 스캔한다: 업스트림replace-all가 본문(body) 범위로 제한되어 있고,searchText도 같은 스코프를 그대로 따른다. 표(cell) 안의 텍스트, 머리말/꼬리말, 각주 본문에서는k-skill-rhwp replace-all가search를 돌려주고found:false도 해당 위치를 건드리지 않는다. 셀 내용이 대상이라면replace-all또는list-paragraphs로 표 좌표를 잡고info로 직접 쓴다.set-cell-text - 문단 경계 / 개행 치환 금지: 은 한 문단 안에서의 치환만 보장한다.
replace-all에 개행(--replacement,\n, U+2028, U+2029) 이 들어오면 CLI 는 exit code 1 과 "replacement must not contain newline or paragraph-break characters" 메시지를 돌려준다. 여러 문단을 만들고 싶으면\r를 여러 번 호출한다.insert-text - 치환은 원본 매칭 기준 non-overlapping: 예를 들어 query / replacement
a/ 원본aa는 원본의 각aaa를 한 번씩 교체해a가 된다. 치환으로 새로 들어온 문자열은 다시 매칭하지 않는다.aaaaaa - 대소문자 무시 매칭은 UTF-16 길이가 보존되는 문자에만 안전하다: 기본값인 대소문자 무시(없이) 모드는
--case-sensitive가 UTF-16 길이를 그대로 유지한다는 전제 위에서 오프셋을 계산한다. 터키어String.prototype.toLowerCase()(U+0130) 처럼 소문자화 시İ+ 결합 점(U+0307) 로 길이가 늘어나는 문자가 본문 또는 쿼리에 포함되면, 조용한 문서 손상을 방지하기 위해i이 exit code 1 과 함께replace-all메시지를 돌려준다. 이런 문서에는case-insensitive matching is unsafe because case folding changes the UTF-16 length로 다시 실행하거나, 입력을 미리 정규화한다. 한글·ASCII 본문에는 해당하지 않으며,--case-sensitive같은 실제 사업 신청서 워크플로우는 아무 영향을 받지 않는다.2025 → 2026
- 无法保存HWPX原文件(rhwp #196):HWPX→HWPX往返编辑已被上游禁用。即使输入为HWPX,输出也仅保存为HWP格式。请勿依赖原文件扩展名,始终以格式保存。
.hwp - 坐标超出范围:若超出实际文档范围,WASM会抛出类似“渲染错误:区域索引0超出范围”的错误,CLI会返回退出码1并在stderr输出错误信息。编辑前需通过
section/paragraph/offset确认坐标。info - 复杂表格·图片·表单字段往返编辑问题:当前上游rhwp v0.7.x处于测试阶段。编辑包含复杂表格、图片、图表、表单字段的实际项目申请书时,可能偶尔出现格式丢失。建议往返编辑完成后执行并手动检查。
k-skill-rhwp render <output> - 发布用(只读)文档:rhwp本身支持通过解除锁定,但
convertToEditableCLI子命令暂未提供该功能。若需使用,请通过k-skill-rhwp技能调用上游rhwp-advanced命令。rhwp convert - WASM初始化延迟:打包后的WASM约4MB,首次调用时需解析一次,可能会有几十毫秒到几百毫秒的延迟。
@rhwp/core - 文件编码:韩文文本直接以UTF-8格式传入CLI即可。若在终端中引号出现乱码,可使用格式。
--text=$'...' - /
search仅扫描正文段落:上游replace-all仅限定在正文(body)范围,searchText也沿用同一范围。表格单元格内的文本、页眉/页脚、脚注正文不会被k-skill-rhwp replace-all检索到(返回search),found:false也不会修改这些位置。若需编辑单元格内容,请通过replace-all或list-paragraphs确定表格坐标后,使用info直接编辑。set-cell-text - 禁止替换段落边界/换行符:仅保证单段落内的替换。若
replace-all包含换行符(--replacement、\n、U+2028、U+2029),CLI会返回退出码1并提示“replacement must not contain newline or paragraph-break characters”。若需创建多个段落,请多次调用\r。insert-text - 替换为非重叠匹配:例如,查询内容为、替换内容为
a、原文本为aa时,会将原文本中的每个aaa替换一次,最终得到a。替换后新增的字符串不会再次被匹配。aaaaaa - 大小写不敏感匹配仅对UTF-16长度不变的字符安全:默认的大小写不敏感模式(未添加)基于
--case-sensitive保持UTF-16长度不变的前提计算偏移量。若正文或查询内容包含如土耳其语String.prototype.toLowerCase()(U+0130)这类转换为小写后会变为İ+结合点(U+0307)导致长度增加的字符,i会返回退出码1并提示“case-insensitive matching is unsafe because case folding changes the UTF-16 length”,以避免隐性文档损坏。此类文档需添加replace-all重新执行,或预先规范化输入。韩文·ASCII正文不受此影响,类似--case-sensitive的实际项目申请工作流完全不受影响。2025→2026
Notes
备注
- 업스트림 rhwp: https://github.com/edwardkim/rhwp
- 업스트림 npm: https://www.npmjs.com/package/@rhwp/core
@rhwp/core - 업스트림은 활발히 개발 중이다(v0.7.3 2026-04-19 기준). breaking change 가능성을 고려해 dependency 는 semver caret 으로 고정한다.
k-skill-rhwp - 이 스킬은 편집 전용 스킬이다. 조회/변환은 , 고급 디버깅은
hwp가 담당한다.rhwp-advanced
- 上游rhwp项目:https://github.com/edwardkim/rhwp
- 上游npm包:https://www.npmjs.com/package/@rhwp/core
@rhwp/core - 上游项目正处于活跃开发阶段(截至2026-04-19版本为v0.7.3)。的依赖已通过semver caret固定,以应对潜在的破坏性变更。
k-skill-rhwp - 本技能为编辑专用技能。查询/转换功能由技能负责,高级调试功能由
hwp技能负责。rhwp-advanced