hwpx-styling

Imported from taejung3852/hwpx-document-plugin (skills/hwpx-styling/SKILL.md). Install upstream with npx skills add taejung3852/hwpx-document-plugin --skill hwpx-styling. Copyright stays with the author.

HWPX 글자 서식 및 맞춤 정책 스킬

이 스킬은 HWPX 문서 내 텍스트의 글자 서식(폰트, 크기, 볼드, 색상)을 지정하고, 표 셀 내 글자 넘침을 방지하기 위한 맞춤 정책을 정의하고 적용하는 전용 도메인 스킬입니다. 최상위 메타 라우터(hwpx-document)로부터 글자 서식 및 셀 맞춤 제어 작업을 위임받아 실행합니다.

1. 도구 선택

문서 변경에는 HWPX 편집 도구를 사용합니다. 지침 읽기·파일 확인 등 읽기 전용 작업까지 막지 않습니다. 도구 오류를 우회하려고 직접 XML 편집이나 별도 MCP 클라이언트로 전환하지 않습니다.

2. 글자 서식 규격 (CharacterStyleInput)

CellEditInput의 style 속성에 전달되는 객체로, 사용자가 지정하거나 기본 서식 상속을 변경할 때 사용합니다:

• bold: 볼드체 적용 여부 (true / false / null)
• italic: 이탤릭체 적용 여부 (true / false / null)
• underline: 밑줄 적용 여부 (true / false / null)
• font_size: 글자 크기 (포인트 pt 단위, 양수 실수, gt=0, le=100)
• font_family: 글꼴 명칭 (예: "맑은 고딕", "한컴바탕", "나눔고딕", 최대 100자)
• text_color: 글자 색상 (HEX 색상 코드, 정규식 ^#[0-9a-fA-F]{6}$, 예: "#000000", "#003399")

설정하지 않은 필드는 기존 문서 셀의 기본 서식을 그대로 상속합니다.

3. 텍스트 맞춤 정책 규격 (TextFitPolicyInput)

CellEditInput의 fit_policy 속성에 전달되는 객체로, 텍스트가 셀 경계를 벗어나는 것을 방지하기 위한 정책을 정의합니다:

• policy: 맞춤 정책 모드 (기본값: "reject")
  • "reject": 텍스트가 셀의 가용 폭을 초과할 경우 계획 생성 단계에서 즉시 거부하고 에러를 반환합니다.
  • "wrap": 셀 너비를 초과할 때 자동 줄바꿈을 적용하여 여러 행으로 분할 배치합니다.
  • "shrink_to_fit": 셀 너비를 초과할 때 폰트 크기를 단계적으로 축소하여 셀 안에 맞춥니다.
• min_font_size: 축소 가능한 최소 폰트 크기 하한선 (포인트 pt 단위, 기본값: 7.0, gt=0, le=100)
• shrink_step: 단계적 폰트 축소 단위 (포인트 pt 단위, 기본값: 0.5, gt=0, le=5.0)
• max_lines: 줄바꿈 또는 축소 맞춤 시 허용되는 최대 줄 수 (기본값: 2, ge=1, le=10)

4. 3중 안전 게이트 (Triple-Safety Gate)

텍스트 넘침과 레이아웃 붕괴를 원천 방지하기 위해 3단계 안전 게이트를 순차적으로 통과해야 합니다:

1. 1차 게이트: Fit Estimator (Unicode 사전 평가)
   • create_edit_plan 실행 시 서버 내부의 Unicode 너비 계산기(Fit Estimator)가 글자 수, 폰트 크기, 여백, 셀 너비를 사전에 계산합니다.
   • 설정된 정책(reject, wrap, shrink_to_fit)에 따라 축소 또는 줄바꿈 적합성을 평가합니다. 설정한 하한선이나 최대 줄 수를 벗어나면 사용자에게 다른 방법을 묻습니다.
2. 2차 게이트: Rust layoutOverflowDiagnostics (렌더링 진단)
   • apply_edit_plan 실행 시 Rust 인프로세스 렌더러가 실제 HWPX 조판 엔진 수준의 레이아웃을 계산하고 layoutOverflowDiagnostics를 수행합니다.
   • 원본 대비 새로 발생하거나 악화된 넘침을 검사합니다. 원본부터 동일하게 존재하던 경고는 알리고 작업을 계속할 수 있습니다.
3. 3차 게이트: Vision AI 검토 (시각 검증)
   • review_document_vision 실행 시 고해상도 렌더링 이미지를 대조하여 줄바꿈 이상, 글자 겹침, 클리핑 현상을 최종 시각 확인합니다.

넘침 발생 시 사용자에게 질문

계획 생성, 적용 또는 시각 검증에서 넘침이 감지되면 작업 전체를 포기하지 말고 다음 조정 방법을 사용자에게 묻습니다.

• 확인된 항목명과 문제를 짧게 설명합니다. 오류가 원본 레이아웃인지 새 입력 때문인지 불명확하면 원인을 단정하지 않습니다. 모르는 셀을 지목하지 말고 위치 확인을 제안합니다.
• 해당 대상에 도구가 지원하는 선택지만 제시합니다: 내용을 유지한 줄바꿈(wrap), 최소 크기를 명시한 축소(shrink_to_fit, 기본 하한 7pt), 사용자가 정한 짧은 문구로 변경, 해당 항목을 변경하지 않고 나머지만 진행. 줄바꿈·축소로 해결된다고 보장하지 않습니다.
• 예: “주소 칸에서 글자 넘침이 감지됐어요. 내용을 유지해 두 줄로 배치할까요, 글자를 최소 7pt까지 줄여볼까요, 아니면 이 항목은 그대로 두고 나머지만 진행할까요?”
• 답을 받기 전에는 내용 축약, 전체 필드 축소, 항목 누락, 새 가져오기 반복으로 우회하지 않습니다. 기존의 ‘양식을 채워줘’ 승인은 이런 추가 변경의 승인이 아닙니다. 이미 같은 대상·방법·한도를 명시적으로 승인했다면 중복 질문하지 않습니다.
• 답을 받으면 같은 local_path에서 선택한 대상·방법을 반영해 create_edit_plan을 다시 호출합니다. 나머지 요청 값은 edits에 유지하고 새 plan_id로 승인·적용·재검증합니다. 실패한 적용은 저장 성공으로 보고하지 않습니다. 실행 중·취소 등 다른 제약이 있으면 해당 상태를 확인하며, 이전 입력을 버리고 인터뷰부터 다시 요구하지 않습니다.
• 선택한 방법으로도 실패하면 결과를 알리고 다른 방법을 묻습니다. 임의로 축소 한도를 낮추거나 내용을 바꾸며 계속 재시도하지 않습니다.

5. 사용자 선택과 지원 범위

• 셀 규격 임의 확대 금지: 텍스트 길이가 길다는 이유로 표의 셀 너비나 행 높이를 임의로 확장할 수 없습니다. 이는 전체 문서 레이아웃과 페이지 구조를 파괴하므로 엄격히 금지됩니다.
• 축소 하한: 기본 제안은 7pt입니다. 사용자가 다른 하한을 명시하면 가독성 저하를 설명하고 도구가 지원하는 범위에서 적용합니다. 에이전트가 임의로 하한을 계속 낮추지는 않습니다.
• 임의 장평/자간 압축 금지: 텍스트를 강제로 구겨 넣기 위해 장평(가로세로 비율)이나 자간을 비정상적으로 왜곡하는 조작을 금지합니다.

6. 작업 파이프라인 연계 요령

1. 요청한 대상과 서식만 확인합니다. 서식 변경에 전체 양식 인터뷰는 필요하지 않습니다.
2. 각 필드의 텍스트 길이와 셀 특성에 맞춰 CharacterStyleInput 및 TextFitPolicyInput을 구성합니다.
3. 스타일과 맞춤 정책을 포함한 CellEditInput 목록으로 create_edit_plan을 호출합니다 (1차 Fit Estimator 통과 확인).
4. 사용자가 해당 변경을 명확히 요청했다면 approve_edit_plan(user_confirmed=True) 후 apply_edit_plan을 실행합니다. 그렇지 않으면 변경 범위를 먼저 확인합니다.
5. 수정본을 제공하고 hwpx-verification으로 결과를 확인합니다. 시각 검증 전 수정본은 검증 완료본과 구분합니다.