문서 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 변환 전 전처리 + 샘플 선검증

• 원고를 변환용 파일(04b_for_hwpx.md 등)로 전처리한다: 작업 메타·말미 메모 제거, 3레벨 리터럴 "- "를 "·"로 치환(마크다운 리스트 오인 방지), □/○ 글머리·GFM 표는 보존. 전처리본은 지우지 않고 _workspace/에 남긴다 — 변환 검증의 기준이 승인 초안이 아니라 이 파일이기 때문이다. 전처리에서 걷어내는 것은 작업 메타(안내 인용문·추적 태그·자기점검 메모)뿐이며 본문 문장·수치·[보강 필요] 표시는 건드리지 않는다. 걷어낸 항목은 변환 보고에 적는다.
• 단독행 날짜(YYYY. M. D.)는 순서목록으로 오파싱(2026. 8. 31. → □ 8. 31.)되므로 변환 전 원고 차원에서 제거·문장 편입한다(이스케이프 우회보다 근본 제거 우선).
• 본 변환 전 소형 샘플로 (1) 도구 작동 (2) 표·부호·제목 렌더링을 선검증한 뒤 전체를 변환한다.

3. 변환 시 보존 원칙

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

4. 검증 — 스크립트로 판정한다

"검증했다"는 말이 아니라 종료 코드로 통과를 정한다. 이 스킬에 동봉된 검증기를 변환에 넣은 원고와 결과 파일에 돌린다:

python3 <이 스킬 디렉토리>/scripts/verify_hwpx.py _workspace/04b_for_hwpx.md _workspace/06_proposal.hwpx

검증기가 보는 것: ①패키지 무결성(zip·mimetype·필수 엔트리·XML 정형성) ②표 대조(원고의 표마다 행·열 수가 같은 표가 같은 순서로 있는가) ③본문 대조율(기준 99.5%, 통째로 사라진 대목은 1건이어도 불합격) ④수치 보존(원고의 숫자가 같은 횟수 이상 있는가) ⑤마크다운 잔재(**·|---). 남아 있는 [보강 필요] 표시도 세어 준다.

• 변환가의 실행과 별개로 리더가 같은 명령을 한 번 더 돌린다. 변환가의 보고가 아니라 리더가 본 종료 코드가 통과 판정이다.
• 기준은 변환에 실제로 넣은 파일(전처리본)이다. 승인 초안(04_proposal.md)을 기준으로 주면 전처리에서 걷어낸 작업 메타 때문에 불합격이 난다.
• 지정 양식 채우기 경로(A)는 양식 자체의 표가 섞이므로 --no-tables로 돌리고, 표는 mcp__kordoc__parse_table로 따로 확인한다.
• 검증기가 못 보는 것: 쪽수·글꼴·여백. mcp__kordoc__parse_document 재파싱과 한글에서의 육안 확인으로 보완한다.
• python3가 없는 환경이면 같은 항목(표 행수 1:1, 본문 왕복 대조, zip·mimetype)을 parse_document 재파싱으로 직접 세어 수치로 보고하고, "스크립트 미실행"이라고 적는다.

문제가 있으면 보완 후 재생성한다. 표 데이터 이상이 의심되면 mcp__kordoc__parse_table로 특정 표를 직접 검사해 손실 지점(생성 vs 이후 단계)을 격리한다.

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 동봉
• 변환 보고: 매핑 결과, 전처리에서 걷어낸 항목, verify_hwpx.py 출력 전문(종료 코드 포함), 형식 조정 사항, 분량 점검 결과를 응답에 요약

에러 대응

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

주의

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