hwp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HWP

What this skill does

该技能的功能

kordoc

으로

.hwp

.hwpx

.hwpml

문서를 AI가 읽기 좋은 Markdown 또는 JSON으로 바꾸고, 필요하면 문서 비교, 양식 필드 추출, Markdown→HWPX 역변환까지 수행한다.

이 스킬의 기본 엔진은 항상
kordoc
이다. 문서 변환, 비교, 필드 추출, 역변환까지 같은 도구로 일관되게 처리한다.

通过

kordoc

将

.hwp

.hwpx

.hwpml

文档转换为AI易于读取的Markdown或JSON格式，还可按需执行文档对比、表单字段提取、Markdown→HWPX反向转换等操作。

本技能的核心引擎始终为**

kordoc

**，文档转换、对比、字段提取、反向转换等所有操作均通过同一工具统一处理。

When to use

适用场景

"이 HWP 파일을 Markdown으로 바꿔줘"
"공문서를 JSON 구조로 뽑아서 AI가 읽게 해줘"
"두 버전 문서 차이점을 보고 싶어"
"신청서 HWPX 안에 어떤 양식 필드가 있는지 뽑아줘"
"AI가 만든 Markdown을 다시 HWPX로 저장해줘"
"폴더 안 문서를 한 번에 변환해줘"

将此HWP文件转换为Markdown格式
将公文提取为JSON结构，供AI读取
查看两个版本文档的差异
提取申请表HWPX中的表单字段
将AI生成的Markdown重新保存为HWPX格式
批量转换文件夹内的文档

When not to use

不适用场景

OCR이 필수인데 OCR provider 연결이 전혀 없는 이미지 기반 PDF만 있는 경우
```
.docx
```
,
```
.xlsx
```
,
```
.pdf
```
만 다루더라도 문서 파싱 자체가 아니라 편집기 GUI 자동화가 필요한 경우
원본 프로그램의 실시간 UI 제어가 반드시 필요한 경우

仅包含无OCR服务连接的图像型PDF，且必须使用OCR的场景
即使仅处理
```
.docx
```
/
```
.xlsx
```
/
```
.pdf
```
文件，但需要的是编辑器GUI自动化而非文档解析的场景
必须对原程序进行实时UI控制的场景

Prerequisites

前置条件

Node.js 18+
출력 경로 쓰기 권한
```
kordoc
```
과
```
pdfjs-dist
```
를 같은 전역/로컬 환경에 설치했거나, 둘 다 포함된
```
npx --yes --package kordoc --package pdfjs-dist kordoc ...
```
실행 환경
현재 배포된
```
kordoc
```
CLI는 시작 시
```
pdfjs-dist
```
를 바로 로드하므로 PDF를 안 써도 함께 설치해야 한다

Node.js 18及以上版本
输出路径的写入权限
在同一全局/本地环境中安装了
```
kordoc
```
和
```
pdfjs-dist
```
，或使用包含两者的
```
npx --yes --package kordoc --package pdfjs-dist kordoc ...
```
执行环境
当前发布的
```
kordoc
```
CLI启动时会直接加载
```
pdfjs-dist
```
，因此即使不处理PDF也需一并安装

Inputs

输入参数

원본
```
.hwp
```
,
```
.hwpx
```
,
```
.hwpml
```
파일 경로 또는 폴더/글롭 경로
원하는 결과 형태:
```
markdown
```
,
```
json
```
,
```
hwpx
```
출력 파일/디렉터리 경로
페이지 범위 지정 여부
비교 / 양식 필드 추출 / 역변환 여부

源
```
.hwp
```
/
```
.hwpx
```
/
```
.hwpml
```
文件路径或文件夹/通配符路径
期望的输出格式：
```
markdown
```
、
```
json
```
、
```
hwpx
```
输出文件/目录路径
是否指定页面范围
是否执行对比、表单字段提取、反向转换操作

Routing policy

路由策略

Default:

kordoc

默认：

kordoc

다음 작업은 모두 기본적으로

kordoc

으로 처리한다.

HWP/HWPX/HWPML → Markdown
HWP/HWPX/HWPML → JSON (
```
blocks
```
,
```
metadata
```
)
배치 변환
페이지 범위 파싱
이미지/표/양식이 포함된 공문서 구조 추출
디렉터리 감시 변환 (
```
watch
```
)
Markdown→HWPX 역변환
HWPX 양식 필드 추출

以下操作默认均通过

kordoc

处理：

HWP/HWPX/HWPML → Markdown
HWP/HWPX/HWPML → JSON（包含
```
blocks
```
、
```
metadata
```
）
批量转换
指定页面范围解析
提取包含图片、表格、表单的公文结构
目录监控转换（
```
watch
```
命令）
Markdown→HWPX反向转换
HWPX表单字段提取

Optional library path

可选库路径

CLI만으로 부족하면 Node API를 사용한다.

```
parse()
```
— Markdown + 구조화 블록
```
compare()
```
— 신구 문서 비교
```
extractFormFields()
```
— 파싱된 블록에서 양식 필드 추출
```
markdownToHwpx()
```
— Markdown→HWPX 역변환

若CLI功能不足，可使用Node API：

```
parse()
```
— 生成Markdown及结构化块
```
compare()
```
— 新旧文档对比
```
extractFormFields()
```
— 从解析后的块中提取表单字段
```
markdownToHwpx()
```
— Markdown转HWPX反向转换

Workflow

操作流程

1. Prepare the CLI runtime

1. 准备CLI运行环境

일회성 변환이면 둘 다 포함한

npx

형태를 바로 쓴다.

bash

npx --yes --package kordoc --package pdfjs-dist kordoc --help

반복 실행용 전역 설치가 필요하면:

bash

npm install -g kordoc pdfjs-dist

현재 배포된

kordoc

CLI는

pdfjs-dist

가 없으면

kordoc --help

단계부터 실패하므로 깨끗한 환경에서는 두 패키지를 같이 설치한 뒤 실행한다.

若为一次性转换，可直接使用包含两者的

npx

命令：

bash

npx --yes --package kordoc --package pdfjs-dist kordoc --help

若需重复执行，可进行全局安装：

bash

npm install -g kordoc pdfjs-dist

当前发布的

kordoc

CLI若缺少

pdfjs-dist

，会在执行

kordoc --help

时失败，因此在干净环境中需同时安装两个包后再执行。

2. Prepare a local project for Node API examples

2. 为Node API示例准备本地项目

parse()

compare()

extractFormFields()

markdownToHwpx()

같은 ESM 예시는 전역

NODE_PATH

가 아니라 로컬 프로젝트 설치 기준으로 실행한다.

bash

mkdir -p ./kordoc-local && cd ./kordoc-local
npm init -y
npm install kordoc pdfjs-dist

이미

package.json

이 있는 작업 디렉터리라면

npm install kordoc pdfjs-dist

만 추가로 실행하면 된다.

parse()

、

compare()

、

extractFormFields()

、

markdownToHwpx()

等ESM示例需基于本地项目安装而非全局

NODE_PATH

执行：

bash

mkdir -p ./kordoc-local && cd ./kordoc-local
npm init -y
npm install kordoc pdfjs-dist

若工作目录已存在

package.json

，只需额外执行

npm install kordoc pdfjs-dist

即可。

3. Convert a document to Markdown

3. 将文档转换为Markdown

bash

npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp -o 보고서.md

여러 문서를 한 번에 처리하려면:

bash

npx --yes --package kordoc --package pdfjs-dist kordoc ./문서함/* -d ./변환결과

특정 페이지 범위만 읽고 싶으면:

bash

npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp --pages 1-3

bash

npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp -o 보고서.md

如需批量处理多个文档：

bash

npx --yes --package kordoc --package pdfjs-dist kordoc ./문서함/* -d ./변환결과

如需仅读取指定页面范围：

bash

npx --yes --package kordoc --package pdfjs-dist kordoc 보고서.hwp --pages 1-3

4. Extract structured JSON for AI/automation

4. 提取结构化JSON供AI/自动化使用

bash

npx --yes --package kordoc --package pdfjs-dist kordoc 검토서.hwpx --format json > 검토서.json

JSON 결과에서는

success

markdown

blocks

metadata

를 우선 확인한다. 표나 이미지가 중요하면

blocks

안의

table

image

타입을 확인한다.

bash

npx --yes --package kordoc --package pdfjs-dist kordoc 검토서.hwpx --format json > 검토서.json

JSON结果中需优先检查

success

、

markdown

、

blocks

、

metadata

字段。若表格或图片重要，需检查

blocks

中的

table

、

image

类型。

5. Inspect HWPX form fields from parsed blocks

5. 从解析后的块中查看HWPX表单字段

bash

node --input-type=module - <<'EOF'
import { parse, extractFormFields } from "kordoc";

const result = await parse("신청서.hwpx");
if (!result.success) {
  console.error(result.error);
  process.exit(1);
}

const fields = extractFormFields(result.blocks);
console.log(JSON.stringify(fields, null, 2));
EOF

자동 변환이 계속 들어오는 폴더면 CLI의

watch

명령을 쓴다.

bash

npx --yes --package kordoc --package pdfjs-dist kordoc watch ./문서함

bash

node --input-type=module - <<'EOF'
import { parse, extractFormFields } from "kordoc";

const result = await parse("신청서.hwpx");
if (!result.success) {
  console.error(result.error);
  process.exit(1);
}

const fields = extractFormFields(result.blocks);
console.log(JSON.stringify(fields, null, 2));
EOF

若需监控持续有文档传入的文件夹，可使用CLI的

watch

命令：

bash

npx --yes --package kordoc --package pdfjs-dist kordoc watch ./문서함

6. Reverse-convert Markdown back to HWPX

6. 将Markdown反向转换为HWPX

bash

node --input-type=module - <<'EOF'
import { markdownToHwpx } from "kordoc";
import { writeFileSync } from "node:fs";

const hwpx = await markdownToHwpx("# 제목\n\n본문\n\n| 항목 | 값 |\n| --- | --- |\n| 성명 | 홍길동 |");
writeFileSync("출력.hwpx", Buffer.from(hwpx));
EOF

bash

node --input-type=module - <<'EOF'
import { markdownToHwpx } from "kordoc";
import { writeFileSync } from "node:fs";

const hwpx = await markdownToHwpx("# 제목\n\n본문\n\n| 항목 | 값 |\n| --- | --- |\n| 성명 | 홍길동 |");
writeFileSync("출력.hwpx", Buffer.from(hwpx));
EOF

7. Compare two document versions when diff matters

7. 对比两个版本的文档差异

bash

node --input-type=module - <<'EOF'
import { compare } from "kordoc";
import { readFileSync } from "node:fs";

const before = readFileSync("이전버전.hwp");
const after = readFileSync("최신버전.hwpx");
const diff = await compare(before, after);
console.log(diff.stats);
EOF

bash

node --input-type=module - <<'EOF'
import { compare } from "kordoc";
import { readFileSync } from "node:fs";

const before = readFileSync("이전버전.hwp");
const after = readFileSync("최신버전.hwpx");
const diff = await compare(before, after);
console.log(diff.stats);
EOF

Verify outputs after every run

每次运行后验证输出

Markdown: 파일이 생성되었고 제목/본문/표 구조가 깨지지 않았는지 확인
JSON:
```
success: true
```
와
```
blocks
```
/
```
metadata
```
존재 여부 확인
배치 처리: 입력 수와 출력 수가 크게 어긋나지 않는지 확인
양식 필드 추출:
```
extractFormFields(result.blocks)
```
결과가 비어 있지 않은지 확인
역변환: 생성된
```
.hwpx
```
파일이 열리고 기본 서식/테이블 구조가 유지되는지 확인
비교:
```
diff.stats
```
에 added / removed / modified 값이 합리적인지 확인

Markdown：确认文件已生成且标题、正文、表格结构未损坏
JSON：确认
```
success: true
```
及
```
blocks
```
/
```
metadata
```
字段存在
批量处理：确认输入与输出文件数量无显著差异
表单字段提取：确认
```
extractFormFields(result.blocks)
```
结果非空
反向转换：确认生成的
```
.hwpx
```
文件可正常打开且基本格式、表格结构得以保留
文档对比：确认
```
diff.stats
```
中的added/removed/modified数值合理

Done when

完成标准

요청한 Markdown / JSON / HWPX 결과물이 생성되어 있다
공문서 표·이미지·메타데이터가 필요한 수준으로 확인되어 있다
양식 필드 추출이나 역변환 요청이 있었다면 결과/출력 구조까지 검증되어 있다
배치 요청이면 처리 범위와 실패 건수가 정리되어 있다

已生成请求的Markdown/JSON/HWPX结果文件
公文的表格、图片、元数据已达到所需的验证标准
若存在表单字段提取或反向转换请求，其结果/输出结构已完成验证
若为批量请求，已整理好处理范围及失败数量

Failure modes

失败场景

손상된 HWP/HWPX/HWPML 파일
암호화/배포 제한 문서에서 일부 파싱 한계 발생
이미지 기반 PDF인데 OCR provider가 없음
출력 디렉터리 권한 부족
양식 라벨이 템플릿 안에서 예상과 다르게 배치되어 일부 필드가 인식되지 않음

HWP/HWPX/HWPML文件损坏
加密或受分发限制的文档存在部分解析限制
图像型PDF无对应的OCR服务
输出目录权限不足
表单标签在模板中的布局与预期不符，导致部分字段无法识别

Notes

注意事项

```
kordoc
```
은 HWP/HWPX뿐 아니라 HWPML, PDF, XLSX, DOCX도 함께 다룬다.
기본 목적은 AI가 읽을 수 있는 Markdown/JSON 변환 이다.
현재 배포본 기준으로 문서화된 CLI 명령은 기본 변환과
```
watch
```
이며, 양식 처리는
```
extractFormFields()
```
같은 Node API로 연결한다.

```
kordoc
```
不仅支持HWP/HWPX，还可处理HWPML、PDF、XLSX、DOCX格式
核心目标是实现AI可读取的Markdown/JSON转换
基于当前发布版本，已文档化的CLI命令包括基础转换和
```
watch
```
，表单处理需通过
```
extractFormFields()
```
等Node API实现

hwp

Original

Translation

HWP

HWP

What this skill does

该技能的功能

When to use

适用场景

When not to use

不适用场景

Prerequisites

前置条件

Inputs

输入参数

Routing policy

路由策略

Default: kordoc

默认：kordoc

Optional library path

可选库路径

Workflow

操作流程

1. Prepare the CLI runtime

1. 准备CLI运行环境

2. Prepare a local project for Node API examples

2. 为Node API示例准备本地项目

3. Convert a document to Markdown

3. 将文档转换为Markdown

4. Extract structured JSON for AI/automation

4. 提取结构化JSON供AI/自动化使用

5. Inspect HWPX form fields from parsed blocks

5. 从解析后的块中查看HWPX表单字段

6. Reverse-convert Markdown back to HWPX

6. 将Markdown反向转换为HWPX

7. Compare two document versions when diff matters

7. 对比两个版本的文档差异

Verify outputs after every run

每次运行后验证输出

Done when

完成标准

Failure modes

失败场景

Notes

注意事项

Default:
`kordoc`

默认：
`kordoc`