rhwp-edit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

rhwp-edit

rhwp-edit

What this skill does

本技能的功能

k-skill-rhwp
CLI로
.hwp
문서의 본문 텍스트, 표 구조, 셀 내용을 round-trip 안전하게 수정한다. CLI는
@rhwp/core
(Rust + WebAssembly) 위에 얇은 Node 래퍼를 씌워
insertText
,
deleteText
,
replaceAll
,
createTable
,
setCellText
같은 편집 동작을 서브커맨드로 노출한다. 결과는 항상 새 파일로 저장한다.
이 스킬은 편집 전용이다. 문서를 Markdown/JSON으로 변환하거나 필드만 추출하려면
hwp
스킬을 사용한다. 페이지 렌더링 디버깅이나 IR 비교가 필요하면
rhwp-advanced
스킬을 사용한다.
通过
k-skill-rhwp
CLI可安全地往返编辑
.hwp
文档的正文文本表格结构单元格内容。 CLI在
@rhwp/core
(Rust + WebAssembly)基础上封装了一层轻量Node包装器,将
insertText
deleteText
replaceAll
createTable
setCellText
等编辑操作以子命令形式提供。编辑结果始终保存为新文件。
本技能为编辑专用。若需将文档转换为Markdown/JSON或仅提取字段,请使用
hwp
技能。 若需页面渲染调试或IR对比,请使用
rhwp-advanced
技能。

When to use

使用场景

  • "HWP 본문에 한 줄 추가해줘"
  • "서식은 유지한 채로 2025를 2026으로 일괄 치환해줘"
  • "3행 4열짜리 표를 HWP에 넣어줘"
  • "표의 특정 셀 내용을 바꿔줘"
  • "빈 HWP 새 파일을 만들어줘"
  • "在HWP正文中添加一行"
  • "保留格式的同时将2025批量替换为2026"
  • "在HWP中插入3行4列的表格"
  • "修改表格特定单元格的内容"
  • "创建新的空白HWP文件"

When not to use

不适用场景

  • HWP → Markdown / JSON 변환
    hwp
    스킬(kordoc)을 쓴다. rhwp-edit은 바이너리 편집 전용이다.
  • HWPX 원본을 다시 HWPX로 저장 → rhwp v0.7.3 기준 업스트림이
    #196
    으로 HWPX 저장 경로를 막아둔 상태다. HWPX를 입력으로 주면 내부적으로 HWP IR로 올라온 뒤 HWP 5.x 바이너리로만 저장된다. HWPX 출력이 꼭 필요하면 kordoc
    markdownToHwpx
    를 쓴다.
  • 레이아웃(페이지네이션·SVG 렌더) 디버깅
    rhwp-advanced
    스킬로 업스트림
    rhwp
    CLI(
    export-svg --debug-overlay
    ,
    dump-pages
    ,
    ir-diff
    )를 사용한다.
  • 배포용(읽기전용) 잠금 해제 · IR 구조 덤프 · 썸네일 추출 등 고급 검사 명령
    rhwp-advanced
    스킬 참조.
  • 한컴 오피스 GUI 자동화, 보안모듈 통과, Windows 전용 서식 → 범위 밖이다.
    rhwp
    는 파일 포맷 엔진이지 GUI 제어가 아니다.
  • HWP → Markdown/JSON转换 → 使用
    hwp
    技能(kordoc)。rhwp-edit仅用于二进制编辑。
  • 将HWPX原文件重新保存为HWPX → 截至rhwp v0.7.3,上游通过
    #196
    禁用了HWPX保存路径。 若输入为HWPX,内部会先转换为HWP IR,最终仅保存为HWP 5.x二进制文件。若必须输出HWPX,请使用kordoc的
    markdownToHwpx
  • 布局(分页·SVG渲染)调试 → 使用
    rhwp-advanced
    技能调用上游
    rhwp
    CLI的
    export-svg --debug-overlay
    dump-pages
    ir-diff
    命令。
  • 解除发布用(只读)锁定·导出IR结构·提取缩略图等高级检查命令 → 参考
    rhwp-advanced
    技能。
  • 韩方Office GUI自动化、安全模块认证、Windows专属格式 → 超出本技能范围。
    rhwp
    是文件格式引擎,而非GUI控制工具。

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
    @rhwp/core@^0.7.3
    을 peer 없이 dependency로 끌어온다. 별도 설치 불필요.
  • Rust/Cargo toolchain 불필요. 업스트림
    rhwp
    CLI를 같이 쓰고 싶으면
    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工具链。若需同时使用上游
    rhwp
    CLI,请使用
    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

路由策略

작업기본 경로
본문 문단에 텍스트 삽입
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
+ 셀 좌표 확인 후
k-skill-rhwp set-cell-text
로 직접 쓰기
빈 표 삽입
k-skill-rhwp create-table --rows N --cols N
표 셀 내용 교체/채우기
k-skill-rhwp set-cell-text --control N --cell N --text "..."
빈 HWP 생성
k-skill-rhwp create-blank <output.hwp>
구조 파악(섹션/문단 수·길이)
k-skill-rhwp info <file>
/
list-paragraphs
페이지 SVG/HTML 미리보기
k-skill-rhwp render <file> --page N --format svg
모든 편집 서브커맨드는 결과를 JSON 한 줄(CLI에서는 pretty-print)로 돌려준다.
ok: true
, 새 커서 위치(
charOffset
,
paraIdx
,
controlIdx
), 저장된 바이트 수(
bytesWritten
), 출력 경로(
outputPath
) 를 포함한다.
操作默认命令路径
在正文段落插入文本
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
确认单元格坐标,再使用
k-skill-rhwp set-cell-text
直接编辑
插入空白表格
k-skill-rhwp create-table --rows N --cols N
替换/填充表格单元格内容
k-skill-rhwp set-cell-text --control N --cell N --text "..."
创建空白HWP
k-skill-rhwp create-blank <output.hwp>
查看文档结构(章节/段落数量·长度)
k-skill-rhwp info <file>
/
list-paragraphs
预览页面SVG/HTML
k-skill-rhwp render <file> --page N --format svg
所有编辑子命令都会返回一行JSON(CLI端会进行格式化输出),包含
ok: true
、新光标位置(
charOffset
paraIdx
controlIdx
)、写入字节数(
bytesWritten
)、输出路径(
outputPath
)。

Workflow

工作流程

  1. 입력 점검:
    k-skill-rhwp info <input>
    sourceFormat
    (hwp/hwpx),
    sectionCount
    , 섹션별
    paragraphCount
    , 문단별
    length
    를 먼저 확인한다. 편집 좌표는 이 결과에서 뽑는다.
  2. 검색이 필요한 경우:
    k-skill-rhwp search <input> --query "2025"
    로 섹션/문단/문자 오프셋을 먼저 얻고, 편집 명령에 그대로 넣는다.
  3. 편집: 아래 예시 중 해당하는 서브커맨드 하나로 실행한다.
    --output
    은 항상 원본과 다른 경로를 지정한다.
    bash
    # 빈 문서 만들기
    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 "합계"
  4. round-trip 검증: 편집 직후
    k-skill-rhwp info <output>
    를 다시 호출하고, 기대한
    paragraphs[].length
    또는
    paragraphCount
    변화를 직접 눈으로 확인한다. 필요하면
    k-skill-rhwp render <output> --page 0 --format html
    로 첫 페이지 렌더 문자열이 생성되는지 sanity check 한다.
  5. 민감 원본 보호: 편집 대상이 개인정보/사업 신청서 등 비공개 문서라면 생성 파일을 레포에 커밋하지 않고, 로그에 남길 때도 본문을 요약·마스킹한다.
  1. 输入检查:先执行
    k-skill-rhwp info <input>
    查看
    sourceFormat
    (hwp/hwpx)、
    sectionCount
    、各章节的
    paragraphCount
    、各段落的
    length
    ,编辑坐标需基于此结果确定。
  2. 需搜索的场景:执行
    k-skill-rhwp search <input> --query "2025"
    获取章节/段落/字符偏移量,直接用于编辑命令。
  3. 执行编辑:选择以下对应子命令执行。
    --output
    需指定与原文件不同的路径。
    bash
    # 创建空白文档
    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 "合计"
  4. 往返验证:编辑完成后再次执行
    k-skill-rhwp info <output>
    ,手动确认
    paragraphs[].length
    paragraphCount
    是否符合预期变化。 必要时可执行
    k-skill-rhwp render <output> --page 0 --format html
    ,检查首页渲染字符串是否正常生成。
  5. 敏感原文件保护:若编辑对象为含个人信息/项目申请书等非公开文档,请勿将生成文件提交至仓库,记录日志时需对正文进行摘要或掩码处理。

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+,
@rhwp/core
WASM 은 첫 호출 시 한 번만 초기화된다. WASM 이 요구하는
globalThis.measureTextWidth
콜백은 자동 shim 되므로 별도 설정 없이 돌아간다(정밀 레이아웃이 필요하면
node-canvas
기반 shim을 먼저 주입한다).
若无需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+,
@rhwp/core
WASM仅在首次调用时初始化一次。WASM所需的
globalThis.measureTextWidth
回调会自动填充,无需额外配置(若需高精度布局,可先注入基于
node-canvas
的填充逻辑)。

Verify outputs after every run

每次运行后验证输出

  • ok === true
    ,
    bytesWritten
    가 수 KB 이상.
  • info
    재호출 결과에서 섹션/문단 수·길이 변화가 의도와 일치.
  • 표 삽입의 경우
    paraIdx
    /
    controlIdx
    가 다음
    set-cell-text
    호출에 그대로 들어간다.
  • 출력 파일이 원본과 다른 경로이며 원본은 그대로다.
  • ok === true
    ,且
    bytesWritten
    为几KB以上。
  • 再次调用
    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
    로 저장한다.
  • 좌표 범위 초과:
    section/paragraph/offset
    이 실제 문서 범위를 벗어나면 WASM에서
    렌더링 오류: 구역 인덱스 0 범위 초과
    같은 에러를 던지고 CLI는 exit code 1 + stderr 에 메시지를 찍는다. 편집 전에
    info
    로 좌표를 확인한다.
  • 복잡한 표·이미지·양식 필드 round-trip: 현재 업스트림 rhwp v0.7.x 는 베타다. 복잡한 표·이미지·차트·양식필드가 많은 실제 사업 신청서를 HWP round-trip 할 경우 드물게 형식 손실이 발생할 수 있다. round-trip 이 끝나면
    k-skill-rhwp render <output>
    + 육안 확인을 권장한다.
  • 배포용(읽기전용) 문서: rhwp 자체는
    convertToEditable
    로 잠금 해제를 지원하지만
    k-skill-rhwp
    CLI 서브커맨드는 아직 노출하지 않는다. 필요하면
    rhwp-advanced
    스킬의 업스트림
    rhwp convert
    경로를 쓴다.
  • WASM 초기화:
    @rhwp/core
    번들 WASM(4 MB) 은 최초 호출 시 한 번 파싱한다. 첫 호출은 수십 ms수백 ms 지연될 수 있다.
  • 파일 인코딩: 한국어 텍스트는 UTF-8 로 그대로 CLI 에 넘기면 된다. 셸에서 인용부호가 깨질 경우
    --text=$'...'
    같은 형식을 쓴다.
  • search
    /
    replace-all
    은 본문 문단만 스캔한다
    : 업스트림
    searchText
    가 본문(body) 범위로 제한되어 있고,
    k-skill-rhwp replace-all
    도 같은 스코프를 그대로 따른다. 표(cell) 안의 텍스트, 머리말/꼬리말, 각주 본문에서는
    search
    found:false
    를 돌려주고
    replace-all
    도 해당 위치를 건드리지 않는다. 셀 내용이 대상이라면
    list-paragraphs
    또는
    info
    로 표 좌표를 잡고
    set-cell-text
    로 직접 쓴다.
  • 문단 경계 / 개행 치환 금지:
    replace-all
    은 한 문단 안에서의 치환만 보장한다.
    --replacement
    에 개행(
    \n
    ,
    \r
    , U+2028, U+2029) 이 들어오면 CLI 는 exit code 1 과 "replacement must not contain newline or paragraph-break characters" 메시지를 돌려준다. 여러 문단을 만들고 싶으면
    insert-text
    를 여러 번 호출한다.
  • 치환은 원본 매칭 기준 non-overlapping: 예를 들어 query
    a
    / replacement
    aa
    / 원본
    aaa
    는 원본의 각
    a
    를 한 번씩 교체해
    aaaaaa
    가 된다. 치환으로 새로 들어온 문자열은 다시 매칭하지 않는다.
  • 대소문자 무시 매칭은 UTF-16 길이가 보존되는 문자에만 안전하다: 기본값인 대소문자 무시(
    --case-sensitive
    없이) 모드는
    String.prototype.toLowerCase()
    가 UTF-16 길이를 그대로 유지한다는 전제 위에서 오프셋을 계산한다. 터키어
    İ
    (U+0130) 처럼 소문자화 시
    i
    + 결합 점(U+0307) 로 길이가 늘어나는 문자가 본문 또는 쿼리에 포함되면, 조용한 문서 손상을 방지하기 위해
    replace-all
    이 exit code 1 과 함께
    case-insensitive matching is unsafe because case folding changes the UTF-16 length
    메시지를 돌려준다. 이런 문서에는
    --case-sensitive
    로 다시 실행하거나, 입력을 미리 정규화한다. 한글·ASCII 본문에는 해당하지 않으며,
    2025 → 2026
    같은 실제 사업 신청서 워크플로우는 아무 영향을 받지 않는다.
  • 无法保存HWPX原文件(rhwp #196):HWPX→HWPX往返编辑已被上游禁用。即使输入为HWPX,输出也仅保存为HWP格式。请勿依赖原文件扩展名,始终以
    .hwp
    格式保存。
  • 坐标超出范围:若
    section/paragraph/offset
    超出实际文档范围,WASM会抛出类似“渲染错误:区域索引0超出范围”的错误,CLI会返回退出码1并在stderr输出错误信息。编辑前需通过
    info
    确认坐标。
  • 复杂表格·图片·表单字段往返编辑问题:当前上游rhwp v0.7.x处于测试阶段。编辑包含复杂表格、图片、图表、表单字段的实际项目申请书时,可能偶尔出现格式丢失。建议往返编辑完成后执行
    k-skill-rhwp render <output>
    并手动检查。
  • 发布用(只读)文档:rhwp本身支持通过
    convertToEditable
    解除锁定,但
    k-skill-rhwp
    CLI子命令暂未提供该功能。若需使用,请通过
    rhwp-advanced
    技能调用上游
    rhwp convert
    命令。
  • WASM初始化延迟
    @rhwp/core
    打包后的WASM约4MB,首次调用时需解析一次,可能会有几十毫秒到几百毫秒的延迟。
  • 文件编码:韩文文本直接以UTF-8格式传入CLI即可。若在终端中引号出现乱码,可使用
    --text=$'...'
    格式。
  • search
    /
    replace-all
    仅扫描正文段落
    :上游
    searchText
    仅限定在正文(body)范围,
    k-skill-rhwp replace-all
    也沿用同一范围。表格单元格内的文本、页眉/页脚、脚注正文不会被
    search
    检索到(返回
    found:false
    ),
    replace-all
    也不会修改这些位置。若需编辑单元格内容,请通过
    list-paragraphs
    info
    确定表格坐标后,使用
    set-cell-text
    直接编辑。
  • 禁止替换段落边界/换行符
    replace-all
    仅保证单段落内的替换。若
    --replacement
    包含换行符(
    \n
    \r
    、U+2028、U+2029),CLI会返回退出码1并提示“replacement must not contain newline or paragraph-break characters”。若需创建多个段落,请多次调用
    insert-text
  • 替换为非重叠匹配:例如,查询内容为
    a
    、替换内容为
    aa
    、原文本为
    aaa
    时,会将原文本中的每个
    a
    替换一次,最终得到
    aaaaaa
    。替换后新增的字符串不会再次被匹配。
  • 大小写不敏感匹配仅对UTF-16长度不变的字符安全:默认的大小写不敏感模式(未添加
    --case-sensitive
    )基于
    String.prototype.toLowerCase()
    保持UTF-16长度不变的前提计算偏移量。若正文或查询内容包含如土耳其语
    İ
    (U+0130)这类转换为小写后会变为
    i
    +结合点(U+0307)导致长度增加的字符,
    replace-all
    会返回退出码1并提示“case-insensitive matching is unsafe because case folding changes the UTF-16 length”,以避免隐性文档损坏。此类文档需添加
    --case-sensitive
    重新执行,或预先规范化输入。韩文·ASCII正文不受此影响,类似
    2025→2026
    的实际项目申请工作流完全不受影响。

Notes

备注

  • 업스트림 rhwp: https://github.com/edwardkim/rhwp
  • 업스트림
    @rhwp/core
    npm: https://www.npmjs.com/package/@rhwp/core
  • 업스트림은 활발히 개발 중이다(v0.7.3 2026-04-19 기준). breaking change 가능성을 고려해
    k-skill-rhwp
    dependency 는 semver caret 으로 고정한다.
  • 이 스킬은 편집 전용 스킬이다. 조회/변환은
    hwp
    , 고급 디버깅은
    rhwp-advanced
    가 담당한다.
  • 上游rhwp项目:https://github.com/edwardkim/rhwp
  • 上游
    @rhwp/core
    npm包:https://www.npmjs.com/package/@rhwp/core
  • 上游项目正处于活跃开发阶段(截至2026-04-19版本为v0.7.3)。
    k-skill-rhwp
    的依赖已通过semver caret固定,以应对潜在的破坏性变更。
  • 本技能为编辑专用技能。查询/转换功能由
    hwp
    技能负责,高级调试功能由
    rhwp-advanced
    技能负责。