문서 HWPX 변환

승인된 본문을 발주처가 요구하는 양식의 .hwpx로 정확히 옮긴다. 내용을 새로 쓰거나 요약하지 않는다 — 형식 변환과 양식 준수에만 집중한다.

의존성: 이 스킬의 변환 경로는 kordoc MCP(제3자 오픈소스, npx kordoc@latest mcp)에 의존한다. 미설치 시 마크다운/docx 산출을 대안으로 제시한다(아래 에러 대응).

왜 양식이 중요한가

정부 R&D 제안서·정책보고서는 발주처 지정 양식 준수가 평가 자격 요건인 경우가 많다. 양식을 벗어나면 내용이 좋아도 감점·반려될 수 있다. 따라서 지정 양식이 있으면 반드시 그 양식을 기준으로 채운다.

절차

1. 입력 확인

• 승인된 본문: 오케스트레이터가 지정한 초안 파일 (예: _workspace/04_proposal.md, _workspace/04_report_draft.md)
• 지정 양식 유무: _workspace/00_input/에 발주처 양식(.hwp/.hwpx/.docx)이 있는지 확인
• 양식 제약: RFP/설계 분석 산출물의 글꼴·여백·분량 정보

2. 양식 분기

(A) 지정 양식이 있는 경우 — 폼 채우기 방식

1. mcp__kordoc__detect_format으로 형식 확인
2. mcp__kordoc__parse_form으로 양식의 채울 항목(필드/표/섹션)을 파악
3. 초안 본문을 양식의 각 항목에 매핑 (섹션 제목 기준으로 대응)
4. mcp__kordoc__fill_form으로 양식에 내용을 채워 .hwpx 생성

(B) 지정 양식이 없는 경우 — 표준 생성 방식

1. mcp__kordoc__generate_document로 변환한다 — GFM 표→정부 서식 표, 개조식 부호(□/ㅇ/-)→리스트 깊이 매핑을 지원하므로 표가 있는 원고도 그대로 처리된다.
2. 팀 문서 삽입용 모듈은 표지·목차·쪽번호 off + h2_marker=none(섹션 제목 문자 유지) + 휴먼명조로 생성한다.
3. 기관 고유 스타일이 필요하면 사용자가 제공한 클린 템플릿 또는 직전에 생성한 hwpx를 스타일 공여자로 재사용한다(독점 양식 파일을 저장소에 두지 않는다 — 런타임에 사용자가 제공).
4. RFP/설계 분석의 글꼴·여백 제약을 반영한다.

2.5 변환 전 전처리 + 샘플 선검증

• 원고를 변환용 파일(03b_for_hwpx.md 등)로 전처리한다: 작업 메타·말미 메모 제거, 3레벨 리터럴 "- "를 "·"로 치환(마크다운 리스트 오인 방지), □/○ 글머리·GFM 표는 보존.
• 단독행 날짜(YYYY. M. D.)는 순서목록으로 오파싱(2026. 8. 31. → □ 8. 31.)되므로 변환 전 원고 차원에서 제거·문장 편입한다(이스케이프 우회보다 근본 제거 우선).
• 본 변환 전 소형 샘플로 (1) 도구 작동 (2) 표·부호·제목 렌더링을 선검증한 뒤 전체를 변환한다.

3. 변환 시 보존 원칙

• 본문 텍스트는 작성가/검수관이 확정한 그대로 옮긴다
• 마크다운 표는 hwpx 표로 변환한다 (목표체계도, 일정표, 역할분담표 등)
• 형식상 불가피한 조정(셀 분할, 줄바꿈)은 변환 보고에 명시한다

4. 자체 검증 — 정량 스위트

재파싱 한 번으로 끝내지 않는다. 다음을 기본 스위트로 실행하고 수치로 보고한다:

• mcp__kordoc__parse_document 재파싱 — 본문 누락·기호 오류 확인
• 표 행수 1:1 대조 (원고 표 행수 = hwpx 표 행수, 예: 204/204 EXACT) — 표별 전수
• 본문 왕복 대조 비율 (재파싱 텍스트 ↔ 원고 유사도, 0.999+ 목표)
• 검증기(validateHwpx) 통과·zip 무결성·MIME(application/hwp+zip) 확인, 금지 기호·날짜 오파싱 카운터 0건 문제가 있으면 보완 후 재생성한다. 표 데이터 이상이 의심되면 mcp__kordoc__parse_table로 특정 표를 직접 검사해 손실 지점(생성 vs 이후 단계)을 격리한다.

스위트 통과는 "정상"이 아니다 — 반드시 렌더해서 눈으로 봐라. 스위트는 참조 정합·행렬 수·왕복 자수를 세지 겹침·잘림·빈칸은 세지 않는다. 실측에서 14항목을 전부 통과한 산출물이 화면에서는 한 줄이 다른 줄 위에 겹쳐 찍혀 있었다(조판 캐시가 원본 위치를 물고 있었다). mcp__kordoc__render_document로 렌더해 확인한다.

• 개수로만 확인하지 마라. "표 44개 중 39개 보존(88.6%)"을 적어 놓고 결론을 "누락 없음"으로 쓰는 자기모순이 실측에서 나왔다. 스위트의 각 수치가 1:1인지를 보고, 어긋나면 어긋난 채로 보고한다.
• 이상해 보이면 공여자/양식 원본을 같은 렌더러로 렌더해 대조하라. 렌더러 자체의 한계(쪽나눔 미구현 등)를 우리 결함으로 오인하지 않기 위해서다. 실측에서 '상자 잘림'이 원본에서도 동일하게 나타나 오탐으로 판명됐다.
• 조판 캐시는 지우지 말고 옮겨라. 캐시(linesegarray)는 글자가 아니라 위치·폭을 담는다. 그대로 두고 줄을 복제하면 겹치고, 지우면 캐시를 신뢰하는 렌더러에서 글상자 글자가 통째로 사라진다. 기존 줄 간격을 읽어 복제분에 누적 적용하는 것이 답이다.

5. 분량·양식 점검

RFP/설계 분석의 페이지 한도·분량 제약을 확인한다. 초과 시 리더와 작성가에게 경고한다 (임의로 본문을 잘라내지 않는다).

배포·삽입 (팀 .hwp에 넣을 때)

• hwpx→.hwp 복사·붙여넣기 시 표 본문 행이 소실될 수 있다(헤더만 남는 표 스텁). hwpx 자체는 정상이므로(parse_table로 확인) 손실 지점은 복붙 단계다.
• 표의 이관은 HTML 병행 출력으로 우회한다: 표 전체를 캡션과 함께 HTML(+열람용 MD)로 추출 → 브라우저에서 드래그·복사 → 한글에 붙여넣으면 실제 표로 보존된다. 개조식 텍스트는 복붙 손실이 없다. 마크다운 원문을 한글에 직접 붙이면 텍스트로 들어가므로 HTML 쪽을 안내한다.
• 팀 .hwp 원본은 절대 재생성하지 않는다(이미지·타 모듈 서식 파괴). 스탠드얼론 hwpx + 한글 교체 표준절차(백업→구간 삭제→붙여넣기→그림 재배치→저장) 가이드 md를 동봉한다.
• 산출물+가이드 쌍 원칙: 도구가 못 하는 마지막 수동 구간(한글 삽입·그림 배치)은 절차서 md로 메운다.

출력

• 최종: 사용자 지정 경로의 <과제명>_<문서유형>.hwpx (미지정 시 작업 디렉토리 또는 데스크탑)
• 사본: _workspace/의 오케스트레이터 지정 경로 (예: 06_proposal.hwpx, 06_report.hwpx)
• 팀 삽입 시: 표 HTML(+MD)·교체 가이드 md 동봉
• 변환 보고: 매핑 결과, 자체 검증 결과(정량 스위트 수치), 형식 조정 사항, 분량 점검 결과를 응답에 요약

에러 대응

• 양식 파싱 실패: 1회 재시도 → 실패 시 (B) 표준 생성으로 전환, "지정 양식 적용 실패 — 표준 양식 생성, 수동 확인 권장" 안내
• 본문 누락 발견: 누락 구간 보완 후 재생성
• 의존성 오류(kordoc/lxml 등): 에러를 명확히 보고하고 마크다운 산출물 유지를 대안으로 제시 (docx 변환이 가능하면 docx 폴백도 제시)
• kordoc MCP 호출이 차단된 경우(도구 게이트 장애 등): Bash에서 kordoc 엔진을 스크립트로 직접 구동해 우회 생성한다(npx -y kordoc@latest 계열, 임시 스크립트 방식 — 검증된 우회). 입력 파일을 먼저 완성해 두고 소형 프로브로 복구를 확인한 뒤 일괄 실행한다.

주의

• 미승인 초안은 변환하지 않는다. 검수관(reviewer)의 승인 신호를 받은 뒤 시작한다.
• 내용 품질은 앞 단계가 책임진다. 변환가의 책임은 "제출 가능한 형식"이다.