hwp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HWP

What this skill does

功能说明

.hwp

문서를 읽어 JSON / Markdown / HTML로 변환하고, 이미지 추출이나 배치 처리를 수행한다.
환경이 Windows + 한글(HWP) 프로그램 설치 + 직접 제어가 필요한 작업이면

hwp-mcp

를 선택하고, 그 외에는 기본값으로

@ohah/hwpjs

를 사용한다.

读取

.hwp

文档并转换为JSON/Markdown/HTML格式，支持图片提取、批量处理操作。
如果运行环境满足Windows系统 + 已安装Hangul（HWP）办公软件 + 需要直接操控软件执行任务，则选择

hwp-mcp

，其余场景默认使用

@ohah/hwpjs

。

When to use

适用场景

"이 HWP 파일을 Markdown으로 바꿔줘"
"한글 문서에서 이미지만 뽑아줘"
"폴더 안 HWP를 한 번에 JSON으로 변환해줘"
"윈도우에서 한글 프로그램을 직접 조작해서 표 채워줘"

"请帮我把这个HWP文件转为Markdown"
"请帮我提取这个HWP文档里的所有图片"
"请把文件夹里所有HWP文件批量转为JSON"
"在Windows环境下直接操控Hangul软件填充表格"

When not to use

不适用场景

원본이
```
.hwpx
```
,
```
.docx
```
,
```
.pdf
```
인 경우
Windows가 아니거나 한글 프로그램이 없는데 직접 편집 자동화를 요구하는 경우
OCR이나 스캔 PDF 복구가 필요한 경우

源文件为
```
.hwpx
```
、
```
.docx
```
、
```
.pdf
```
格式的情况
非Windows系统，或未安装Hangul软件，但要求实现直接编辑自动化的情况
需要OCR识别或扫描件PDF恢复的情况

Prerequisites

前置依赖

공통 변환 경로: Node.js 18+
직접 제어 경로: Windows + 한글(HWP) 프로그램 설치 + Python 3.7+
출력 경로 쓰기 권한

通用转换路径：Node.js 18+
直接操控路径：Windows + 已安装Hangul（HWP）办公软件 + Python 3.7+
输出路径写入权限

Inputs

输入参数

원본
```
.hwp
```
파일 경로 또는 폴더 경로
원하는 출력 형식:
```
json
```
,
```
markdown
```
,
```
html
```
출력 파일/디렉터리 경로
이미지 포함/추출 여부
배치 처리 여부
직접 제어가 필요한지 여부

源
```
.hwp
```
文件路径或文件夹路径
期望的输出格式：
```
json
```
、
```
markdown
```
、
```
html
```
输出文件/目录路径
是否包含/提取图片
是否开启批量处理
是否需要直接操控Hangul软件

Routing policy

路由策略

Default:

@ohah/hwpjs

默认选项：

@ohah/hwpjs

다음 조건 중 하나라도 맞으면

@ohah/hwpjs

를 기본값으로 사용한다.

macOS / Linux / CI 환경
Windows여도 한글 프로그램 설치 여부를 확신할 수 없음
읽기 / 변환 / 이미지 추출 / 배치 처리 중심 작업

满足以下任一条件时默认使用

@ohah/hwpjs

：

macOS / Linux / CI 环境
即使是Windows系统，也无法确认是否已安装Hangul软件
核心需求为读取/转换/图片提取/批量处理类操作

Windows direct-control path:

hwp-mcp

Windows直接操控路径：

hwp-mcp

다음 조건을 모두 만족할 때만

hwp-mcp

를 선택한다.

운영체제가 Windows
한글(HWP) 프로그램이 실제로 설치되어 있음
문서 생성, 텍스트 삽입, 표 채우기, 저장 같은 실행 중인 한글 프로그램 직접 제어가 필요함

직접 제어 조건이 불분명하면 추측하지 말고

@ohah/hwpjs

로 처리 가능한 범위부터 진행한다.

仅当同时满足以下所有条件时选择

hwp-mcp

：

操作系统为Windows
已实际安装Hangul（HWP）办公软件
需要直接操控运行中的Hangul软件完成文档创建、文本插入、表格填充、保存等直接操控类操作

若直接操控条件不明确，不要猜测，优先在

@ohah/hwpjs

可处理的范围内推进。

Workflow

工作流程

0. Detect the environment first

0. 优先检测环境

bash

node -p "process.platform"

결과가
```
win32
```
가 아니면
```
@ohah/hwpjs
```
결과가
```
win32
```
여도 한글 프로그램 직접 제어가 확인되지 않으면
```
@ohah/hwpjs
```
```
win32
```
이고 한글 프로그램이 실제로 설치되어 있으며 직접 조작이 필요하면
```
hwp-mcp
```

bash

node -p "process.platform"

运行结果不是
```
win32
```
则使用
```
@ohah/hwpjs
```
即使结果为
```
win32
```
，若无法确认需要直接操控Hangul软件，也使用
```
@ohah/hwpjs
```
结果为
```
win32
```
、已安装Hangul软件且需要直接操控时，使用
```
hwp-mcp
```

1. Install the chosen backend when missing

1. 缺少选中的后端时先完成安装

@ohah/hwpjs

@ohah/hwpjs

bash

npm install -g @ohah/hwpjs
export NODE_PATH="$(npm root -g)"

bash

npm install -g @ohah/hwpjs
export NODE_PATH="$(npm root -g)"

hwp-mcp

hwp-mcp

bash

git clone https://github.com/jkf87/hwp-mcp.git
cd hwp-mcp
pip install -r requirements.txt

hwp-mcp

는 Windows와 한글 프로그램 설치가 전제다. 이 전제가 깨지면 억지로 진행하지 말고

@ohah/hwpjs

로 되돌린다.

bash

git clone https://github.com/jkf87/hwp-mcp.git
cd hwp-mcp
pip install -r requirements.txt

hwp-mcp

的使用前提是Windows系统且已安装Hangul软件，若前提不满足不要强行使用，切回

@ohah/hwpjs

即可。

2. Prefer

@ohah/hwpjs

for conversions and extraction

2. 转换、提取类操作优先使用

@ohah/hwpjs

JSON 변환

转换为JSON

bash

hwpjs to-json document.hwp -o output.json --pretty

bash

hwpjs to-json document.hwp -o output.json --pretty

Markdown 변환

转换为Markdown

bash

hwpjs to-markdown document.hwp -o output.md --include-images

--include-images

는 이미지를 별도 파일로 떨구지 않고 Markdown 안에 base64

data:

URI로 인라인한다. 이미지를 파일로 따로 저장해야 하면 다음처럼

--images-dir

를 사용한다.

bash

hwpjs to-markdown document.hwp -o output.md --images-dir ./images

bash

hwpjs to-markdown document.hwp -o output.md --include-images

--include-images

参数不会将图片导出为单独文件，而是以base64

data:

URI的形式内联到Markdown中。如果需要将图片单独保存为文件，可使用如下

--images-dir

参数：

bash

hwpjs to-markdown document.hwp -o output.md --images-dir ./images

HTML 변환

转换为HTML

bash

hwpjs to-html document.hwp -o output.html

bash

hwpjs to-html document.hwp -o output.html

이미지 추출

提取图片

bash

hwpjs extract-images document.hwp -o ./images

bash

hwpjs extract-images document.hwp -o ./images

배치 처리

批量处理

bash

hwpjs batch ./documents -o ./output --format json --recursive

배치 출력 형식은 로컬 설치 버전의

hwpjs batch --help

를 확인해 맞춘다.

bash

hwpjs batch ./documents -o ./output --format json --recursive

批量输出格式可参考本地安装版本的

hwpjs batch --help

命令输出进行适配。

3. Use

hwp-mcp

only for live HWP control on Windows

3. 仅Windows环境下的Hangul实时操控场景使用

hwp-mcp

Claude/Codex MCP 설정에

hwp_mcp_stdio_server.py

를 등록한 뒤 다음 종류의 작업에 사용한다.

새 문서 생성
텍스트 삽입
표 생성 / 채우기
저장
여러 편집 명령을 묶은 배치 작업

직접 제어 예시는 다음 범주에 한정한다.

보고서 템플릿 채우기
표 데이터 입력
정해진 서식 문서 생성

在Claude/Codex MCP配置中注册

hwp_mcp_stdio_server.py

后，可用于以下类型的任务：

新建文档
插入文本
创建/填充表格
保存文件
包含多个编辑指令的批量任务

直接操控的适用场景限定为以下类别：

填充报告模板
表格数据录入
生成固定格式的文档

4. Verify outputs after every run

4. 每次运行后校验输出结果

JSON: 파일 생성 여부와 최상위 구조 확인
Markdown: 본문 생성 여부와
```
data:
```
URI / base64 이미지 인라인 포함 여부 확인 (
```
--include-images
```
사용 시)
Markdown: 이미지 파일 분리가 목적이면
```
--images-dir
```
출력 디렉터리에 실제 파일이 생겼는지 확인
HTML: 파일 생성 후 브라우저 렌더링 가능 여부 확인
이미지 추출: 출력 디렉터리에 파일이 실제로 생겼는지 확인
배치 처리: 입력 개수와 출력 개수가 대략 맞는지 확인

JSON：确认文件已生成，且顶层结构正确
Markdown：确认正文已生成，若使用
```
--include-images
```
参数需校验
```
data:
```
URI/base64图片是否正确内联
Markdown：若目标是导出单独图片文件，需校验
```
--images-dir
```
指定的输出目录下已生成对应图片文件
HTML：确认文件已生成，且可在浏览器正常渲染
图片提取：校验输出目录下已生成对应图片文件
批量处理：确认输入文件数量和输出文件数量大致匹配

Done when

完成判定标准

요청한 형식의 결과물이 생성되어 있다
이미지 요청이 있으면 추출 파일 또는 Markdown 안
```
data:
```
URI 인라인 결과가 확인되어 있다
배치 요청이면 처리 범위와 실패 건수가 정리되어 있다
Windows 직접 제어 작업이면 어떤 조작을 수행했는지 남아 있다

已生成用户要求格式的结果文件
若有图片提取需求，已确认提取出的图片文件或Markdown中内联的
```
data:
```
URI结果正常
若是批量处理需求，已统计清楚处理范围和失败数量
若是Windows直接操控任务，已留存执行的操作记录

Failure modes

失败场景

손상된
```
.hwp
```
파일
전역
```
hwpjs
```
미설치
Windows가 아니어서
```
hwp-mcp
```
를 사용할 수 없음
한글 프로그램 미설치 또는 자동화 연결 실패
출력 디렉터리 권한 부족

```
.hwp
```
文件已损坏
未全局安装
```
hwpjs
```
非Windows系统无法使用
```
hwp-mcp
```
未安装Hangul软件或自动化连接失败
输出目录权限不足

Notes

注意事项

기본 선택지는 언제나
```
@ohah/hwpjs
```
다.
```
hwp-mcp
```
는 Windows + 한글 설치 환경에서만 직접 제어용으로 사용한다.
직접 제어가 실패해도 읽기/변환 작업으로 충분하면
```
@ohah/hwpjs
```
경로로 축소해 완료한다.

无论何时默认选项都是
```
@ohah/hwpjs
```
```
hwp-mcp
```
仅在Windows+已安装Hangul的环境下用于直接操控场景
若直接操控失败，且读取/转换类操作就能满足需求时，可降级使用
```
@ohah/hwpjs
```
路径完成任务

hwp

Original

Translation

HWP

HWP

What this skill does

功能说明

When to use

适用场景

When not to use

不适用场景

Prerequisites

前置依赖

Inputs

输入参数

Routing policy

路由策略

Default: @ohah/hwpjs

默认选项：@ohah/hwpjs

Windows direct-control path: hwp-mcp

Windows直接操控路径：hwp-mcp

Workflow

工作流程

0. Detect the environment first

0. 优先检测环境

1. Install the chosen backend when missing

1. 缺少选中的后端时先完成安装

@ohah/hwpjs

@ohah/hwpjs

hwp-mcp

hwp-mcp

2. Prefer @ohah/hwpjs for conversions and extraction

2. 转换、提取类操作优先使用@ohah/hwpjs

JSON 변환

转换为JSON

Markdown 변환

转换为Markdown

HTML 변환

转换为HTML

이미지 추출

提取图片

배치 처리

批量处理

3. Use hwp-mcp only for live HWP control on Windows

3. 仅Windows环境下的Hangul实时操控场景使用hwp-mcp

4. Verify outputs after every run

4. 每次运行后校验输出结果

Done when

完成判定标准

Failure modes

失败场景

Notes

注意事项

Default:
`@ohah/hwpjs`

默认选项：
`@ohah/hwpjs`

Windows direct-control path:
`hwp-mcp`

Windows直接操控路径：
`hwp-mcp`

`@ohah/hwpjs`

`@ohah/hwpjs`

`hwp-mcp`

`hwp-mcp`

2. Prefer
`@ohah/hwpjs`
for conversions and extraction

2. 转换、提取类操作优先使用
`@ohah/hwpjs`

3. Use
`hwp-mcp`
only for live HWP control on Windows

3. 仅Windows环境下的Hangul实时操控场景使用
`hwp-mcp`