mirror of https://github.com/NomaDamas/k-skill.git synced 2026-06-24 02:04:11 +00:00

Jeffrey (Dongkyu) Kim 48b8d8153e Clarify HWP markdown verification in the feature guide

The feature guide already documented `--include-images`, but it did not
spell out the verification rule as clearly as the skill doc. Add a
feature-level verification checklist and tighten the regression test so
repo docs stay aligned with the actual `hwpjs` inline-image behavior.

Constraint: `hwpjs to-markdown --include-images` embeds images as base64 data URIs instead of writing sidecar files
Rejected: Leave verification guidance only in `hwp/SKILL.md` | feature docs could drift without their own regression coverage
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Keep the feature-guide verification text aligned with `npx --yes @ohah/hwpjs to-markdown --help` if the CLI flag behavior changes
Tested: node --test scripts/skill-docs.test.js; npx --yes @ohah/hwpjs to-markdown --help; npm test; npm run ci; npx --yes skills add . --list
Not-tested: End-to-end conversion against a real `.hwp` fixture

2026-03-26 12:34:34 +09:00

3.3 KiB

Raw Permalink Blame History

HWP 문서 처리 가이드

이 기능으로 할 수 있는 일

.hwp 문서를 JSON, Markdown, HTML로 변환
문서 안 이미지를 추출
폴더 단위 배치 처리
Windows + 한글 프로그램 설치 환경에서는 직접 문서 조작까지 확장

먼저 필요한 것

기본 경로: Node.js 18+
기본 패키지: npm install -g @ohah/hwpjs
실행 전: export NODE_PATH="$(npm root -g)"
직접 제어가 필요할 때만: Windows + 한글(HWP) 프로그램 설치 + Python 3.7+

어떤 경로를 선택하나

기본값: `@ohah/hwpjs`

다음 상황에서는 @ohah/hwpjs를 사용한다.

macOS / Linux / CI
읽기, 변환, 이미지 추출, 배치 처리
Windows여도 한글 프로그램 설치/연동을 확신할 수 없음

예외 경로: `hwp-mcp`

다음 조건을 모두 만족할 때만 hwp-mcp를 사용한다.

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

즉, 변환은 @ohah/hwpjs, 직접 조작은 hwp-mcp 가 기본 규칙이다.

기본 흐름

node -p "process.platform" 으로 운영체제를 확인한다.
win32 가 아니면 @ohah/hwpjs를 사용한다.
win32 여도 직접 제어 요건이 분명하지 않으면 @ohah/hwpjs를 사용한다.
직접 조작이 필요하고 한글 설치가 확인되면 hwp-mcp를 선택한다.
결과 파일 생성 여부와 출력 내용을 확인한다.

예시

JSON 변환

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

Markdown 변환 + 이미지 포함

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

--include-images 는 이미지 파일 경로를 따로 만드는 대신 Markdown 안에 base64 data: URI로 포함한다.

HTML 변환

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

이미지 추출

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

배치 처리

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

결과 확인 포인트

JSON 출력: 파일 생성 여부와 최상위 구조를 확인한다.
Markdown 출력: --include-images 를 썼다면 이미지 파일 경로가 따로 생기지 않아도 정상이며, Markdown 안 data: URI / base64 인라인 포함 여부를 확인한다.
HTML 출력: 파일 생성 뒤 브라우저에서 열리는지 확인한다.
이미지 추출: 출력 디렉터리에 실제 이미지 파일이 생겼는지 확인한다.
배치 처리: 입력 개수와 출력 개수가 크게 어긋나지 않는지 확인한다.

이미지를 별도 파일로 떨궈야 한다면 --include-images 대신 --images-dir 경로를 쓴다.

직접 제어가 필요한 경우

hwp-mcp는 Windows + 한글 프로그램 설치 환경에서만 고려한다.

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

그 뒤 MCP 서버로 연결해 새 문서 생성, 텍스트 삽입, 표 작성, 저장 같은 작업을 수행한다.

주의할 점

hwp-mcp를 Linux/macOS에서 우회 실행하려 하지 않는다.
직접 제어 필요성이 약하면 @ohah/hwpjs로 바로 끝내는 편이 더 안정적이다.
배치 작업 후에는 입력 개수와 출력 개수를 같이 확인한다.

3.3 KiB Raw Permalink Blame History