# 공문서 다루기 — hwp·hwpx

> **이 장에서 배우는 것**
> `.hwp`·`.hwpx`를 읽어 자료로 쓰는 법, 마크다운에서 공문서를 만드는 법,
> 그리고 **빈 서식을 자동으로 채우는** 법.

## 앞 장에 없던 확장자

[문서를 자료로 바꾸기](/guide/ht-documents)에서 다룬 것은 네 가지였습니다 —
`pdf` · `docx` · `xlsx` · `pptx`. 국내 실무에서 **가장 자주 마주치는 확장자가
거기 없습니다.**

관공서 공고문, 지원사업 신청서, 사내 기안문, 회의록 서식. 이것들이 `.hwp`나
`.hwpx`로 옵니다. 그리고 대부분의 자동화가 여기서 멈춥니다 — **한컴오피스가
깔린 윈도우 PC가 있어야 한다**고 알려져 있기 때문입니다.

그렇지 않습니다.

## 먼저 — 두 확장자는 다른 포맷입니다

**이 장에서 가장 자주 사고가 나는 지점입니다.**

| | `.hwp` | `.hwpx` |
|---|---|---|
| 정체 | 바이너리 (HWP 5.x) | ZIP + XML |
| 읽기 | 됩니다 | 됩니다 |
| **쓰기·수정** | **안 됩니다** | 됩니다 |

읽는 것은 양쪽 다 되지만, **만들고 고치는 것은 `.hwpx`뿐입니다.** 아래 나오는
생성·채우기·편집의 산출물은 전부 `.hwpx`입니다. 한글에서 `.hwp`로 다시 저장하는
것은 사람이 마지막에 하면 됩니다.

## 도구 — kordoc

npm 패키지 하나입니다. **설치하지 않고** 부릅니다.

```bash
npx -y kordoc@^4 <명령> ...
```

- **Node.js 18+ 만 있으면 됩니다.** 한컴오피스도, 윈도우도, COM 자동화도
  필요 없습니다. macOS·리눅스 서버에서 그대로 돕니다.
- 첫 호출만 내려받느라 느리고 이후는 캐시됩니다.
- `@^4`로 메이저 버전을 고정합니다. [앞 장의
  yt-dlp](/guide/ht-video-collect)와 반대 방향인데, 상대가 플랫폼이 아니라
  **문서 포맷 규격**이라 자주 바뀌지 않기 때문입니다.

## 1. 읽기 — 무엇이든 마크다운으로

```bash
npx -y kordoc@^4 사업계획서.hwp -o 사업계획서.md
```

[문서를 자료로 바꾸기](/guide/ht-documents)의 **텍스트 사본**이 여기서도 그대로
성립합니다. 원본 옆에 마크다운을 나란히 두면 검색이 걸립니다.

| 하고 싶은 것 | 붙일 것 |
|---|---|
| 폴더 통째로 | `-d ./변환결과/` |
| 특정 쪽만 | `-p 1-3` 또는 `-p 1,3,5` |
| 구조화된 JSON | `--format json` |

hwp 계열뿐 아니라 **PDF·DOCX·XLS/XLSX도 같은 명령으로** 읽힙니다. 관공서에서
받은 파일 묶음이 확장자별로 섞여 있을 때 유용합니다.

> **표는 GFM이 아니라 HTML `<table>`로 나옵니다.** 공문서의 병합·중첩 표는
> 파이프표로 표현이 안 되기 때문입니다. 셀 병합이 살아 있다는 뜻이니 그대로
> 쓰면 됩니다. 수식은 LaTeX(`$...$`)로 나옵니다.

### 스캔본 구분

PDF는 텍스트층 품질을 함께 계산해 알려줍니다. **`needsOcr` 신호가 뜨면 스캔본**
이라 글자가 아니라 그림입니다. kordoc은 OCR을 내장하지 않으므로 여기서
멈추고 다른 경로를 찾아야 합니다. 표가 깨져 보이는 PDF는 대개 이 경우입니다.

## 2. 만들기 — 마크다운에서 공문서로

```bash
npx -y kordoc@^4 초안.md -o 보고서.hwpx --preset 보고서
```

프리셋이 일곱 개 있습니다 — `기안문` · `보고서` · `계획서` · `통지` · `회의록` ·
`개조식` · `보도자료`.

**여기서 자동으로 되는 것이 공문서 작성의 실제 번거로움 대부분입니다.**

| 마크다운에 쓴 것 | 문서에서 |
|---|---|
| `1.` / 들여쓴 `-` | 공문서 항목부호 8단계 (1. → 가. → 1) → 가) → …) |
| — | 함초롬바탕·공식 여백 등 표준 서식 |
| GFM 파이프표 | 표 |
| `$$...$$` | 한글 네이티브 수식 |
| ` ```chart ` 펜스 | 한글 네이티브 차트 (막대·선·원·도넛 등) |

항목부호 단계와 내어쓰기는 손으로 맞추면 오래 걸리고 자주 틀리는 부분입니다.
**마크다운으로 내용만 쓰고 서식은 맡기는** 것이 이 명령의 요점입니다.

본문 옵션은 `--font gothic`(맑은 고딕) · `--pt <크기>` ·
`--line-spacing <퍼센트>`가 있고, 공문서 서식을 끄고 범용 변환만 하려면
`--plain`입니다.

## 3. 서식 채우기 — 빈칸이 있는 신청서

가장 반복이 심한 일입니다. 같은 신청서를 스무 번 채우는 자리입니다.

**순서가 중요합니다. 무엇을 채울 수 있는지부터 봅니다.**

```bash
npx -y kordoc@^4 fill 신청서.hwpx --dry-run
```

라벨 목록이 나옵니다. 그걸 보고 값을 JSON으로 만들어 넣습니다.

```bash
npx -y kordoc@^4 fill 신청서.hwpx -j 값.json -o 결과.hwpx
```

- **값은 반드시 `-j` 파일로 넘기세요.** `-f 'k=v,...'`도 되지만 값이 셸
  히스토리와 프로세스 목록에 남습니다. 신청서에 들어가는 값이 무엇인지 생각하면
  이유가 분명합니다.
- 원본 글꼴·크기·정렬은 **100% 유지**됩니다. 채운 티가 나지 않습니다.
- 여러 줄은 JSON 문자열 안의 `\n`으로 씁니다.

> **같은 라벨이 여러 곳에 있으면 기본 동작은 "전부 채우기"입니다.** 반복
> 양식을 위한 동작인데, 서식에 따라 엉뚱한 칸까지 채워질 수 있습니다. 처음 쓰는
> 서식은 `--dry-run`으로 라벨이 몇 번 나오는지 먼저 확인하세요.

### 도장

```bash
npx -y kordoc@^4 seal 신청서.hwpx --image 도장.png --anchor "(인)" -o 날인본.hwpx
```

"(인)" 같은 앵커 문구를 찾아 이미지를 **글 앞 부유**로 얹습니다. 표나 페이지가
커지지 않는다는 뜻입니다 — 날인하고 나서 서식이 한 장 밀리는 사고를 막습니다.
투명 배경 PNG를 쓰세요.

## 4. 고치기 — 원본 서식을 유지한 채

받은 문서의 내용만 바꿔야 할 때입니다.

```bash
npx -y kordoc@^4 원본.hwpx -o 편집.md          # ① 마크다운으로
# ② 편집.md 에서 내용을 고칩니다
npx -y kordoc@^4 patch 원본.hwpx 편집.md -o 수정본.hwpx   # ③ 되돌려 넣기
```

②에서 **내용만 고치세요.** 문단을 옮기거나 지우는 구조 변경은 최소로 합니다.
글꼴·표·개체·조판은 원본 것이 그대로 유지되고 텍스트만 제자리에 반영됩니다.

## 전달 전에 — 검증과 미리보기

**생성하거나 고친 파일은 확인하고 넘깁니다.**

```bash
npx -y kordoc@^4 validate 결과.hwpx                    # 구조 검사
npx -y kordoc@^4 render 결과.hwpx --reflow -o 미리보기.svg   # 눈으로 확인
```

`validate`는 ZIP 구조·필수 파트·XML 형식을 봅니다. **한컴독스 업로드가 거부되는
사유를 미리 걸러내는 자리**입니다. `render`는 조판을 SVG로 그립니다 — kordoc이
만든 파일은 조판 캐시가 없으므로 `--reflow`를 붙여야 합니다.

두 문서를 비교해 **신구대조표**를 만드는 것도 됩니다. 조문·문단 단위 diff를
돌려줍니다.

## HyperTeams에서 돌리기

정해진 변환이면 판단이 없으니 **`terminal`**입니다.
[사례 — 콘텐츠 공장](/guide/ht-case-factory)의 수집 칸과 같은 자리입니다.

```
매주 월 08:00  ·  kind: terminal
npx -y kordoc@^4 ./공고/*.hwp -d ./공고-md/
```

반대로 **무엇을 채울지 판단해야 하면 `task`**입니다.

```
1. terminal — 받은 서식을 --dry-run 으로 라벨 추출
2. task     — 사내 자료에서 값을 찾아 값.json 작성
3. terminal — fill 로 채우고 validate
4. 사람     — 확인하고 제출
```

**4번이 사람인 이유**는 [가드레일](/guide/ha-guardrails)과 같습니다. 제출은
되돌릴 수 없습니다.

### Connect에서 쓸 때

kordoc은 MCP 서버로도 붙습니다. 워크스페이스 멤버가 대화 중에 hwp를 다루게
하려면 이쪽입니다.

```bash
npx -y kordoc@^4 setup
```

대화형 마법사가 클라이언트에 등록해 줍니다. 워크스페이스 쪽 연결은
[MCP 서버 연결하기](/guide/cn-mcp)와 [도구 설정](/guide/cn-tool-settings)을
보세요. 도구가 열한 개 늘어나므로 [도구가 많아질
때](/guide/mcp-too-many-tools)의 주의가 그대로 적용됩니다.

## 조심할 것

### 개인정보가 담긴 서식입니다

신청서·인사 서식에는 주민등록번호·계좌·연락처가 들어갑니다.

```
□ 값 파일(값.json)을 저장소에 커밋하고 있지 않나
□ 채운 결과 파일이 공유 폴더에 남아 있지 않나
□ 대화 기록에 값이 그대로 남지 않았나
```

[문서를 자료로 바꾸기](/guide/ht-documents)의 마지막 경고가 여기서 더
강해집니다. **작업 폴더가 곧 활동 범위**이고, 시스템을
[Connect에 등록](/guide/cn-systems)했다면 멤버도 닿습니다.

### 원본을 덮어쓰지 마세요

`-o`로 **항상 새 파일에 씁니다.** 채우기·패치·날인 모두 마찬가지입니다. 원본
서식은 다시 받기 번거로운 경우가 많습니다.

### 암호·DRM 문서는 열리지 않습니다

기관에서 배포한 DRM 문서나 암호가 걸린 파일은 파싱되지 않습니다. 우회 대상이
아니라 **다른 경로를 찾아야 하는 신호**입니다.

### 숫자와 표는 확인하세요

앞 장과 같습니다. 금액·날짜·수량이 걸린 판단이라면 **원본을 확인**하세요.
[조심할 것](/guide/ai-cautions)의 "숫자는 반드시 확인"이 공문서에서 특히
그렇습니다.

---

## 확인

**1. `.hwp` 파일의 내용을 고쳐서 다시 내보낼 수 있습니까?**

<details>
<summary>답</summary>

**읽을 수는 있지만 그 포맷으로 다시 쓸 수는 없습니다.** 생성·채우기·편집의
산출물은 전부 `.hwpx`입니다. `.hwp`로 필요하면 마지막에 한글에서 다시 저장합니다.
</details>

**2. 서식을 채울 때 값을 `-f`가 아니라 `-j` 파일로 넘기는 이유는?**

<details>
<summary>답</summary>

**셸 히스토리와 프로세스 목록에 값이 남기 때문**입니다. 신청서에 들어가는 값은
주민등록번호·계좌 같은 개인정보인 경우가 많습니다.
</details>

**3. 만든 hwpx를 사람에게 넘기기 전에 무엇을 합니까?**

<details>
<summary>답</summary>

**`validate`로 구조를 검사**합니다. ZIP 구조·필수 파트·XML 형식을 미리 봐서
한컴독스 업로드가 거부되는 사유를 걸러냅니다. 조판이 걱정되면
`render --reflow`로 눈으로도 확인합니다.
</details>

---

**확장하기 파트가 끝났습니다.** 막히는 것이 있으면 →
[문제 해결](/guide/ht-troubleshooting) · [가이드 목차](/guide)