kordoc — 한국 공문서 툴킷
kordoc(npm)은 관공서 문서 파이프라인 도구다. HWP 3.x/5.x·HWPX·HWPML·PDF·DOCX·XLS/XLSX → Markdown
파싱, Markdown → 공문서 HWPX 생성, 서식 빈칸 채우기(원본 스타일 보존), 서식 보존 라운드트립 패치,
문서 비교, HWPX 구조 검증, 조판 SVG 렌더를 제공한다. 한컴오피스·Windows COM 불필요, Node.js 18+만
있으면 된다.
실행 방법
설치 없이 npx 로 실행한다 (메이저 버전 고정):
npx -y kordoc@^4 <command> ...
첫 호출만 패키지 다운로드로 느리고 이후는 캐시. 상시 사용 환경이면 MCP 서버로 붙일 수도 있다
(npx -y kordoc@^4 setup — 대화형 마법사가 Claude Code/Desktop·Cursor 등에 자동 등록).
MCP 도구 11종: parse_document, parse_table, parse_pages, parse_metadata, parse_form,
fill_form, place_seal, patch_document, generate_document, compare_documents, detect_format.
명령 요약
| 작업 |
명령 |
| 문서 → Markdown |
npx -y kordoc@^4 문서.hwpx -o 문서.md |
| 일괄 변환 |
npx -y kordoc@^4 *.pdf -d ./변환결과/ |
| 페이지/섹션 범위 |
-p 1-3 또는 -p 1,3,5 |
| 구조화 JSON (blocks+metadata) |
--format json |
| 서식 필드 목록만 보기 |
npx -y kordoc@^4 fill 서식.hwpx --dry-run |
| 서식 채우기 |
npx -y kordoc@^4 fill 서식.hwpx -j 값.json -o 결과.hwpx |
| 공문서 생성 |
npx -y kordoc@^4 generate 초안.md -o 결과.hwpx --preset 보고서 |
| 편집 왕복 패치 |
npx -y kordoc@^4 patch 원본.hwpx 편집.md -o 결과.hwpx |
| HWPX 구조 검증 |
npx -y kordoc@^4 validate 결과.hwpx |
| 조판 SVG 렌더 |
npx -y kordoc@^4 render 문서.hwpx -o 미리보기.svg |
| 도장/서명 배치 |
npx -y kordoc@^4 seal 문서.hwpx --image 도장.png --anchor "(인)" -o 결과.hwpx |
도장 위치 한계: 중첩표·글상자·탭/줄바꿈 문단·복잡 rowSpan 그리드는 근사 배치이며 결과 warnings 에 고지된다 — 한컴에서 확인 후 --dx/--dy(MCP dx_mm/dy_mm)로 보정한다.
워크플로
1) 읽기 — 어떤 문서든 Markdown 으로
npx -y kordoc@^4 사업계획서.hwp -o 사업계획서.md
- 병합·중첩 표는 GFM 으로 표현이 안 되므로 HTML
<table>(colspan/rowspan)로 나온다 — 그대로 다루면 된다.
- 수식은
$...$ / $$...$$ LaTeX 로 나온다.
- PDF 는 텍스트층 품질 신호를 같이 계산한다 — 추출 텍스트가 깨져 보이면(
needsOcr) 스캔/손상
PDF 라는 뜻이니 --ocr(CLI) / ocr: true(MCP)로 재시도한다 — 내장 OCR(PP-OCRv5 korean,
로컬 추론·API 키 불필요, 첫 사용 시 모델 ~18MB 자동 다운로드)이 깨진 페이지만 다시 읽는다.
이미지 파일(PNG/JPG/WebP)은 플래그 없이 자동 OCR.
- 대용량·다수 파일은
-d 디렉토리 모드로 한 번에.
2) 공문서 생성 — Markdown 규약
npx -y kordoc@^4 generate 보고서.md -o 보고서.hwpx --preset 보고서
프리셋: 기안문(official) · 보고서(report) · 계획서(plan) · 통지(notice) · 회의록(minutes) ·
개조식(gaejosik, 표지·목차·장 헤더) · 보도자료(press).
위계는 서울 실결재 629건 실측값으로 고정된다(v4.13). #=제목, ##=장(보고서 Ⅰ. Ⅱ. / 기안문·통지는 법정 1.),
###=□(또는 가.), 그 아래 리스트는 ㅇ → - → ㆍ(법정형 가. → 1) → 가)). 본문에 □/ㅇ/-/1./가. 를 직접 써도
같은 depth 로 정규화된다. □·제목은 한 줄에 맞춰 자동 축소된다(넘치면 경고 — 문장을 줄일 것).
기안문은 --doc-head "org=기관명,slogan=원훈,to=수신,title=제목" --doc-foot "sender=발신명의,drafter=주무관 홍길동, reviewer=과장 김철수,approver=국장 박영희,docNum=과-번호 (날짜),zip=…,address=…,phone=…,email=…,disclosure=공개"
로 실결재 두문표·결문표가 붙는다. 보고서는 --report-info "(날짜, 부서 담당자, ☎)"(담당자 행)·--summary(요약박스)·
--cover --dept 부서 --doc-info "docNum=…"(표지).
보고서는 제목 직후 인용문(>)에 보고 목적을 반드시 쓴다 — 부호 없이 한 문장(쉼표 허용), 15pt 기준 3줄 이내(약 90~100자), "…을 검토하고자 함" 꼴(실물 요약박스 "…검토 결과를 보고드림"). 요약박스가 된다. 없거나 3줄을 넘으면 경고.
출처·자료는 출처: … 로 시작하는 줄로 쓰면 ※ 참고(작은 글씨)로 간다. 법령명 뒤 법제처 코드 (282791), KOSIS 표 ID DT_…, (법정동코드 …), "통계 MCP 조회" 같은 도구 언급은 공문에 남기지 않는다(써도 자동 제거) — 출처는 기관·자료명만.
표는 GFM 파이프표로 쓰면 된다. display 수식 $$...$$ 은 HWPX 네이티브 수식(<hp:equation>)으로
생성된다 (\frac·\sqrt·첨자·그리스 문자·적분/극한·행렬 등 제한된 LaTeX 부분셋).
본문 옵션: --font gothic(맑은 고딕) · --pt <크기> · --line-spacing <퍼센트> ·
--plain(공문서 모드 끄고 범용 변환).
stdin 입력은 파일 인자에 -.
차트: ```chart 펜스가 한컴 네이티브 차트로 생성된다 (막대·선·원·도넛·영역·분산·방사형 20종):
```chart
type: column
cat: 1분기, 2분기, 3분기
size: 120x70
colors: #304D68, accent2
예산: 100, 120, 110
집행: 80, 95, 105
```
type: column|bar|line|area|pie|doughnut|scatter|radar (+_stacked) — 미지정 시 column.cat: 카테고리(x축) 라벨 · size: 너비x높이(mm, 선택) · colors: 계열 색(파이는 조각 색, 선택).이름: 숫자들 형식의 각 라인이 데이터 계열. 위 펜스는 그대로 복사해도 되는 유효 입력이다(주석 금지 — 주석 텍스트가 값으로 들어가 계열이 탈락한다).- 차트 제목은 펜스가 아니라 본문 문단으로 쓴다. 계열이 없으면 일반 코드블록으로 폴백된다.
생성 후 validate 로 구조를 확인하고 나서 사용자에게 전달한다.
3) 서식 채우기 (fill)
- 먼저 필드를 파악한다:
fill 서식.hwpx --dry-run → 라벨 목록.
- 값은
-j 값.json(JSON 파일)으로 넘기는 것을 권장 — -f 'k=v,...' 는 셸 히스토리·프로세스
목록에 값이 노출된다.
- 다중줄 값은 JSON 문자열 안의
\n — 표 셀/문단 안에서 실제 강제 줄바꿈으로 채워진다.
- 같은 라벨이 문서에 2곳 이상이면 기본 동작은 모든 칸에 채운다(반복 양식 지원). 남의 칸 오염이
우려되면 MCP
fill_form 에 require_unique: true 를 줘라 — 2곳+ 매칭되는 스칼라 라벨은 채우지
않고 rejected 로 보고한다(배열 값은 예외). CLI fill 엔 이 가드가 없으니 반복 라벨 서식은
값을 배열로 주거나 어느 칸인지 확인 후 채운다.
- 날짜·전화·주민등록번호 등 칸 모양 변환(
yyyy.mm.dd, ###-####-#### 숫자 마스크 등)은 MCP
fill_form 의 formats 파라미터가 지원한다.
- 기본 출력 포맷은
hwpx-preserve(원본 글꼴·크기·정렬 100% 유지). 원본 파일은 덮어쓰지 말고
항상 -o 로 새 파일에 쓴다.
개인정보 주의: 주민등록번호·계좌·연락처 같은 값은 응답에 그대로 되풀이하지 않는다. 채움 결과
확인이 필요하면 MCP fill_form 의 mask_values 마스킹 verify 를 쓰고, 사용자가 원문 확인을 명시
요청할 때만 보여준다. 채운 결과 파일 자체가 개인정보 문서임을 고지한다.
4) 기존 문서 편집 (patch)
npx -y kordoc@^4 원본.hwpx -o 편집.md # ① 파싱
# ② 편집.md 를 수정 (내용만 — 구조 이동/삭제 최소화)
npx -y kordoc@^4 patch 원본.hwpx 편집.md -o 수정본.hwpx # ③ 서식 보존 반영
- 원본의 글꼴·표·개체·조판을 보존한 채 텍스트 변경만 in-place 반영한다.
- 본문 문단에 줄을 나누고 싶으면 편집 md 에 명시적
<br> 을 쓴다 — 에디터의 soft-wrap 접힘은
수정으로 취급되지 않는다.
- 원본은 절대 덮어쓰지 않는다 (
-o 필수 습관).
5) 도장/서명 배치 (seal)
npx -y kordoc@^4 seal 신청서.hwpx --image 도장.png --anchor "(인)" -o 신청서_날인.hwpx
- 앵커 문구("(인)"·"서명 또는 인" 등) 위/옆에 이미지를 글 앞 부유로 얹는다 — 표·페이지가
절대 커지지 않는다 (날인 후 서식이 밀리는 사고 방지).
- 같은 앵커가 여럿이면
-n <0-based> 로 선택. 못 찾으면 등장 횟수를 에러로 안내한다.
--mode: auto(기본 — 오른쪽 공간 있으면 옆에, 없으면 문구 위에 겹침) · overlap · right.- 크기 기본값은 줄높이×1.6 (7~18mm 클램프),
--size-mm 로 고정 가능. 위치 미세조정은
--dx/--dy (mm).
- 이미지는 투명 배경 PNG 권장 (macOS 미리보기 > 마크업 > 서명 내보내기, 또는 도장 스캔).
- HWPX 전용. 배치 후
render --reflow 로 위치를 확인하고 사용자에게 전달한다.
6) 비교·검증·미리보기
- 비교(신구대조표): MCP
compare_documents — 두 문서의 조문/문단 단위 diff.
- 검증:
validate 파일.hwpx — ZIP 구조·mimetype·필수 파트·XML 웰폼드·secCnt·manifest 참조를
검사한다 (한컴독스 업로드 거부 요인 사전 차단). 생성·패치 산출물은 전달 전에 반드시 통과 확인.
- 미리보기:
render 문서.hwpx -o 문서.svg
- 한컴에서 저장한 파일: 조판 캐시를 그대로 그려 원본 충실 미리보기.
- kordoc 이 생성/패치한 파일(조판 캐시 없음):
--reflow 를 붙여 순수 TS 조판으로 렌더.
--highlight 검색어 로 형광펜 표시 가능.
함정
- 암호로 보호된 HWP/HWPX·DRM 배포본은 파싱할 수 없다 — 에러 메시지를 그대로 사용자에게 전달한다.
.hwp(바이너리 HWP 5.x)와 .hwpx(ZIP/XML)는 다른 포맷이다. fill/patch/generate 산출물은 HWPX 다.- 생성 HWPX 를 한컴에서 열면 편집 후 저장 시 조판 캐시가 생겨 render 기본 모드도 동작하게 된다.
- 표가 깨져 보이는 PDF 는 원본이 스캔본이거나 텍스트층이 손상된 경우가 대부분이다 — 품질 신호를
근거로 설명한다.
1---2name: kordoc3description: Use this skill whenever the user wants to read, create, fill, edit, compare, validate, or preview Korean Hangul/official documents — .hwp (HWP 3.x/5.x), .hwpx, .hml (HWPML) — or convert Korean-office PDF/DOCX/XLS/XLSX to Markdown. Triggers include any mention of 'hwp', 'hwpx', 'hml', '한글 문서', '아래한글', '한컴', '공문서', '기안문', '보고서를 hwpx로', '서식 채우기', '양식 자동 작성', '신청서 채워줘', '신구대조표', '문서 비교', or uploading/attaching .hwp/.hwpx/.hml files. Also use when generating official Korean documents from Markdown (기안문·보고서·계획서·통지·회의록 presets) or when a HWPX layout preview/verification is needed. Do NOT use for authoring plain Word .docx files (kordoc reads DOCX but generates only HWPX) or for general Korean text with no document file involved.4license: MIT5---67# kordoc — 한국 공문서 툴킷89kordoc(npm)은 관공서 문서 파이프라인 도구다. HWP 3.x/5.x·HWPX·HWPML·PDF·DOCX·XLS/XLSX → Markdown10파싱, Markdown → 공문서 HWPX 생성, 서식 빈칸 채우기(원본 스타일 보존), 서식 보존 라운드트립 패치,11문서 비교, HWPX 구조 검증, 조판 SVG 렌더를 제공한다. 한컴오피스·Windows COM 불필요, Node.js 18+만12있으면 된다.1314## 실행 방법1516설치 없이 npx 로 실행한다 (메이저 버전 고정):1718```bash19npx -y kordoc@^4 <command> ...20```2122첫 호출만 패키지 다운로드로 느리고 이후는 캐시. 상시 사용 환경이면 MCP 서버로 붙일 수도 있다23(`npx -y kordoc@^4 setup` — 대화형 마법사가 Claude Code/Desktop·Cursor 등에 자동 등록).24MCP 도구 11종: `parse_document`, `parse_table`, `parse_pages`, `parse_metadata`, `parse_form`,25`fill_form`, `place_seal`, `patch_document`, `generate_document`, `compare_documents`, `detect_format`.2627## 명령 요약2829| 작업 | 명령 |30|---|---|31| 문서 → Markdown | `npx -y kordoc@^4 문서.hwpx -o 문서.md` |32| 일괄 변환 | `npx -y kordoc@^4 *.pdf -d ./변환결과/` |33| 페이지/섹션 범위 | `-p 1-3` 또는 `-p 1,3,5` |34| 구조화 JSON (blocks+metadata) | `--format json` |35| 서식 필드 목록만 보기 | `npx -y kordoc@^4 fill 서식.hwpx --dry-run` |36| 서식 채우기 | `npx -y kordoc@^4 fill 서식.hwpx -j 값.json -o 결과.hwpx` |37| 공문서 생성 | `npx -y kordoc@^4 generate 초안.md -o 결과.hwpx --preset 보고서` |38| 편집 왕복 패치 | `npx -y kordoc@^4 patch 원본.hwpx 편집.md -o 결과.hwpx` |39| HWPX 구조 검증 | `npx -y kordoc@^4 validate 결과.hwpx` |40| 조판 SVG 렌더 | `npx -y kordoc@^4 render 문서.hwpx -o 미리보기.svg` |41| 도장/서명 배치 | `npx -y kordoc@^4 seal 문서.hwpx --image 도장.png --anchor "(인)" -o 결과.hwpx` |4243> **도장 위치 한계**: 중첩표·글상자·탭/줄바꿈 문단·복잡 rowSpan 그리드는 근사 배치이며 결과 `warnings` 에 고지된다 — 한컴에서 확인 후 `--dx`/`--dy`(MCP `dx_mm`/`dy_mm`)로 보정한다.4445## 워크플로4647### 1) 읽기 — 어떤 문서든 Markdown 으로4849```bash50npx -y kordoc@^4 사업계획서.hwp -o 사업계획서.md51```5253- 병합·중첩 표는 GFM 으로 표현이 안 되므로 HTML `<table>`(colspan/rowspan)로 나온다 — 그대로 다루면 된다.54- 수식은 `$...$` / `$$...$$` LaTeX 로 나온다.55- PDF 는 텍스트층 품질 신호를 같이 계산한다 — 추출 텍스트가 깨져 보이면(`needsOcr`) 스캔/손상56 PDF 라는 뜻이니 `--ocr`(CLI) / `ocr: true`(MCP)로 재시도한다 — 내장 OCR(PP-OCRv5 korean,57 로컬 추론·API 키 불필요, 첫 사용 시 모델 ~18MB 자동 다운로드)이 깨진 페이지만 다시 읽는다.58 이미지 파일(PNG/JPG/WebP)은 플래그 없이 자동 OCR.59- 대용량·다수 파일은 `-d 디렉토리` 모드로 한 번에.6061### 2) 공문서 생성 — Markdown 규약6263```bash64npx -y kordoc@^4 generate 보고서.md -o 보고서.hwpx --preset 보고서65```6667- 프리셋: `기안문`(official) · `보고서`(report) · `계획서`(plan) · `통지`(notice) · `회의록`(minutes) ·68 `개조식`(gaejosik, 표지·목차·장 헤더) · `보도자료`(press).69- 위계는 서울 실결재 629건 실측값으로 고정된다(v4.13). `#`=제목, `##`=장(보고서 Ⅰ. Ⅱ. / 기안문·통지는 법정 `1.`),70 `###`=□(또는 `가.`), 그 아래 리스트는 ㅇ → - → ㆍ(법정형 가. → 1) → 가)). 본문에 □/ㅇ/-/1./가. 를 직접 써도71 같은 depth 로 정규화된다. □·제목은 한 줄에 맞춰 자동 축소된다(넘치면 경고 — 문장을 줄일 것).72- 기안문은 `--doc-head "org=기관명,slogan=원훈,to=수신,title=제목"` `--doc-foot "sender=발신명의,drafter=주무관 홍길동,73 reviewer=과장 김철수,approver=국장 박영희,docNum=과-번호 (날짜),zip=…,address=…,phone=…,email=…,disclosure=공개"`74 로 실결재 두문표·결문표가 붙는다. 보고서는 `--report-info "(날짜, 부서 담당자, ☎)"`(담당자 행)·`--summary`(요약박스)·75 `--cover --dept 부서 --doc-info "docNum=…"`(표지).76- **보고서는 제목 직후 인용문(`>`)에 보고 목적을 반드시 쓴다** — 부호 없이 **한 문장**(쉼표 허용), 15pt 기준 **3줄 이내**(약 90~100자), "…을 검토하고자 함" 꼴(실물 요약박스 "…검토 결과를 보고드림"). 요약박스가 된다. 없거나 3줄을 넘으면 경고.77- 출처·자료는 `출처: …` 로 시작하는 줄로 쓰면 ※ 참고(작은 글씨)로 간다. 법령명 뒤 법제처 코드 `(282791)`, KOSIS 표 ID `DT_…`, `(법정동코드 …)`, "통계 MCP 조회" 같은 도구 언급은 공문에 남기지 않는다(써도 자동 제거) — 출처는 기관·자료명만.78- 표는 GFM 파이프표로 쓰면 된다. display 수식 `$$...$$` 은 HWPX 네이티브 수식(`<hp:equation>`)으로79 생성된다 (`\frac`·`\sqrt`·첨자·그리스 문자·적분/극한·행렬 등 제한된 LaTeX 부분셋).80- 본문 옵션: `--font gothic`(맑은 고딕) · `--pt <크기>` · `--line-spacing <퍼센트>` ·81 `--plain`(공문서 모드 끄고 범용 변환).82- stdin 입력은 파일 인자에 `-`.83- **차트**: ` ```chart ` 펜스가 한컴 네이티브 차트로 생성된다 (막대·선·원·도넛·영역·분산·방사형 20종):8485 ~~~86 ```chart87 type: column88 cat: 1분기, 2분기, 3분기89 size: 120x7090 colors: #304D68, accent291 예산: 100, 120, 11092 집행: 80, 95, 10593 ```94 ~~~9596 - `type`: `column|bar|line|area|pie|doughnut|scatter|radar` (+`_stacked`) — 미지정 시 column.97 - `cat`: 카테고리(x축) 라벨 · `size: 너비x높이`(mm, 선택) · `colors`: 계열 색(파이는 조각 색, 선택).98 - `이름: 숫자들` 형식의 각 라인이 데이터 계열. 위 펜스는 그대로 복사해도 되는 유효 입력이다(주석 금지 — 주석 텍스트가 값으로 들어가 계열이 탈락한다).99 - 차트 제목은 펜스가 아니라 본문 문단으로 쓴다. 계열이 없으면 일반 코드블록으로 폴백된다.100- 생성 후 `validate` 로 구조를 확인하고 나서 사용자에게 전달한다.101102### 3) 서식 채우기 (fill)1031041. **먼저 필드를 파악한다**: `fill 서식.hwpx --dry-run` → 라벨 목록.1052. 값은 `-j 값.json`(JSON 파일)으로 넘기는 것을 권장 — `-f 'k=v,...'` 는 셸 히스토리·프로세스106 목록에 값이 노출된다.1073. 다중줄 값은 JSON 문자열 안의 `\n` — 표 셀/문단 안에서 실제 강제 줄바꿈으로 채워진다.1084. 같은 라벨이 문서에 2곳 이상이면 기본 동작은 **모든 칸에 채운다**(반복 양식 지원). 남의 칸 오염이109 우려되면 MCP `fill_form` 에 `require_unique: true` 를 줘라 — 2곳+ 매칭되는 스칼라 라벨은 채우지110 않고 `rejected` 로 보고한다(배열 값은 예외). CLI `fill` 엔 이 가드가 없으니 반복 라벨 서식은111 값을 배열로 주거나 어느 칸인지 확인 후 채운다.1125. 날짜·전화·주민등록번호 등 칸 모양 변환(`yyyy.mm.dd`, `###-####-####` 숫자 마스크 등)은 MCP113 `fill_form` 의 `formats` 파라미터가 지원한다.1146. 기본 출력 포맷은 `hwpx-preserve`(원본 글꼴·크기·정렬 100% 유지). 원본 파일은 덮어쓰지 말고115 항상 `-o` 로 새 파일에 쓴다.116117**개인정보 주의**: 주민등록번호·계좌·연락처 같은 값은 응답에 그대로 되풀이하지 않는다. 채움 결과118확인이 필요하면 MCP `fill_form` 의 `mask_values` 마스킹 verify 를 쓰고, 사용자가 원문 확인을 명시119요청할 때만 보여준다. 채운 결과 파일 자체가 개인정보 문서임을 고지한다.120121### 4) 기존 문서 편집 (patch)122123```bash124npx -y kordoc@^4 원본.hwpx -o 편집.md # ① 파싱125# ② 편집.md 를 수정 (내용만 — 구조 이동/삭제 최소화)126npx -y kordoc@^4 patch 원본.hwpx 편집.md -o 수정본.hwpx # ③ 서식 보존 반영127```128129- 원본의 글꼴·표·개체·조판을 보존한 채 텍스트 변경만 in-place 반영한다.130- 본문 문단에 줄을 나누고 싶으면 편집 md 에 **명시적 `<br>`** 을 쓴다 — 에디터의 soft-wrap 접힘은131 수정으로 취급되지 않는다.132- 원본은 절대 덮어쓰지 않는다 (`-o` 필수 습관).133134### 5) 도장/서명 배치 (seal)135136```bash137npx -y kordoc@^4 seal 신청서.hwpx --image 도장.png --anchor "(인)" -o 신청서_날인.hwpx138```139140- 앵커 문구("(인)"·"서명 또는 인" 등) 위/옆에 이미지를 **글 앞 부유**로 얹는다 — 표·페이지가141 절대 커지지 않는다 (날인 후 서식이 밀리는 사고 방지).142- 같은 앵커가 여럿이면 `-n <0-based>` 로 선택. 못 찾으면 등장 횟수를 에러로 안내한다.143- `--mode`: `auto`(기본 — 오른쪽 공간 있으면 옆에, 없으면 문구 위에 겹침) · `overlap` · `right`.144- 크기 기본값은 줄높이×1.6 (7~18mm 클램프), `--size-mm` 로 고정 가능. 위치 미세조정은145 `--dx`/`--dy` (mm).146- 이미지는 **투명 배경 PNG** 권장 (macOS 미리보기 > 마크업 > 서명 내보내기, 또는 도장 스캔).147- HWPX 전용. 배치 후 `render --reflow` 로 위치를 확인하고 사용자에게 전달한다.148149### 6) 비교·검증·미리보기150151- **비교(신구대조표)**: MCP `compare_documents` — 두 문서의 조문/문단 단위 diff.152- **검증**: `validate 파일.hwpx` — ZIP 구조·mimetype·필수 파트·XML 웰폼드·secCnt·manifest 참조를153 검사한다 (한컴독스 업로드 거부 요인 사전 차단). 생성·패치 산출물은 전달 전에 반드시 통과 확인.154- **미리보기**: `render 문서.hwpx -o 문서.svg`155 - 한컴에서 저장한 파일: 조판 캐시를 그대로 그려 원본 충실 미리보기.156 - kordoc 이 생성/패치한 파일(조판 캐시 없음): `--reflow` 를 붙여 순수 TS 조판으로 렌더.157 - `--highlight 검색어` 로 형광펜 표시 가능.158159## 함정160161- 암호로 보호된 HWP/HWPX·DRM 배포본은 파싱할 수 없다 — 에러 메시지를 그대로 사용자에게 전달한다.162- `.hwp`(바이너리 HWP 5.x)와 `.hwpx`(ZIP/XML)는 다른 포맷이다. fill/patch/generate 산출물은 HWPX 다.163- 생성 HWPX 를 한컴에서 열면 편집 후 저장 시 조판 캐시가 생겨 render 기본 모드도 동작하게 된다.164- 표가 깨져 보이는 PDF 는 원본이 스캔본이거나 텍스트층이 손상된 경우가 대부분이다 — 품질 신호를165 근거로 설명한다.
chrisryugj