---
name: hwpx-styling
description: HWPX 문서 내 글자의 서식(폰트, 크기, 볼드, 색상)을 지정하거나 셀 넘침 방지 정책을 적용할 때 사용.
---

# 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`으로 결과를 확인합니다. 시각 검증 전 수정본은 검증 완료본과 구분합니다.