형식 정리 에이전트
형식이 엉망인 Word 문서(.docx)를 주어진 규격에 따라 자동으로 재정렬합니다. 이해는 AI가, 실행은 코드가, 중간은 JSON으로 연결합니다.
기능 범위
- 두 가지 형식 출처 지원: 자연어 규격 텍스트(.txt), 올바르게 정렬된 Word 템플릿(.docx)
- 이미 정렬된 모든 문서를 템플릿으로 사용 가능: 당위원회/주주총회/이사회 자료, 계약서, 법률 의견서, 컨설팅 보고서, 논문, 보도자료 등. 에이전트가 글꼴/크기/줄 간격/들여쓰기/번호 매기기 스타일을 읽어 대상 문서에 적용합니다.
- 비구조적 문서(모델의 의미 판단에 의존)와 번호가 있는 문서(一, (一), 1. 수동 번호 매기기, 제1장/제1조 조항 번호 또는 Word 자동 번호 매기기)를 확실하게 식별합니다.
- 페이지 수준: 여백, 줄 격자, 머리글/바닥글(페이지 번호 필드 포함)
- 단락 수준: 글꼴/크기/굵게/정렬/줄 간격/첫 줄 들여쓰기/번호 매기기 스타일
- 표 수준: 첫 행 머리글(굵게/가운데 정렬), 셀 글꼴 크기 정렬, 테두리 선
- 템플릿에 지정되지 않은 역할은 자동으로 본문과 일치합니다.
- 본문 텍스트 내용은 전혀 수정하지 않음: 정렬 후 항상 텍스트 일관성 검증(원본과 최종본을 단락별로 비교), 텍스트 추가/삭제가 있으면 명확히 보고합니다.
- 목차: 템플릿에 목차 필드가 있으면 자동 생성(Word에서 열면 필드 업데이트로 목차 생성); 다단 정렬: 지원(대학원 이단 논문에 적합)
- 현재 버전에서는 재정렬하지 않음: 표지 디자인; 병합된 셀의 복잡한 표 구조는 그대로 유지
환경 요구 사항
- Python 3.10+, 종속성:
pip install -r requirements.txt(python-docx, requests, PyMuPDF; Windows 렌더링에는 pywin32 추가 필요) - 에이전트 환경에서는 모델을 설정할 필요 없음: 이해 작업은 호스트 에이전트가 수행합니다("사용 방법 1" 참조).
- 독립 API 모드(에이전트가 없는 환경)에서만 모델 설정 필요:
환경 변수 /
.env파일:LLM_BASE_URL,LLM_API_KEY,LLM_MODEL(선택 사항:LLM_VISION_MODEL,LLM_TIMEOUT,LLM_TEMPERATURE)
모델 선택 (중요: 다중 모달 권장)
이 스킬은 특정 모델에 종속되지 않으며 모든 OpenAI 호환 엔드포인트에서 사용 가능합니다. 하지만 다중 모달 모델을 권장합니다 (텍스트와 이미지 입력을 모두 지원하는 모델, 예: GPT-4o, Kimi K3, Qwen-VL, GLM-4V 등):
- 형식 정리 주요 프로세스(규칙 추출, 역할 레이블링)에는 텍스트 기능만 필요합니다.
- 시각적 자체 검사(--verify)는 렌더링된 이미지를 모델에 전달하여 품질을 검사해야 하므로 순수 텍스트 모델은 이 단계를 사용할 수 없습니다.
호출 에이전트를 위한 지침: 실행을 시작하기 전에 현재 사용 중인 모델이 무엇인지, 다중 모달(이미지 입력) 기능이 있는지 확인하십시오. 현재 모델에 다중 모달 기능이 없으면 사용자에게 적극적으로 알리십시오: "현재 모델은 이미지 입력을 지원하지 않으므로 시각적 자체 검사를 사용할 수 없습니다. 다중 모달 모델(예: XXX)로 전환하면 정렬 후 자동 품질 검사를 받을 수 있어 더 나은 결과를 얻을 수 있습니다." 사용자가 확인한 후 계속 진행하십시오.
사용 방법
이 스킬에는 두 가지 사용 방법이 있습니다. 에이전트 환경에서는 '내장 지능형 모드'를 우선 사용하십시오 – 구성이 필요 없으며, API 키가 필요 없으며, 이해 작업은 호스트 에이전트가 수행합니다.
사용 방법 1: 에이전트 내장 지능형 모드 (기본 권장, 구성 불필요)
호스트 에이전트로서의 실행 흐름:
-
대상 문서 구조 추출:
python main.py --extract-only --target 대상.docx --out 출력디렉터리/정렬후.docx출력디렉터리/정렬후_paragraphs.json파일이 생성되며, 각 단락에는idx/text/size_pt/bold/alignment/style_name/in_table및 번호 메타데이터가 포함됩니다. -
직접 FormatSpec 생성 (형식 규칙 JSON):
- 사용자가 규격 텍스트를 제공한 경우: 이를 읽고 아래 스키마에 따라 JSON을 작성하여
출력디렉터리/정렬후_formatspec.json으로 저장합니다; - 사용자가 템플릿 docx를 제공한 경우: 먼저 템플릿에 대해
--extract-only를 실행하고, 각 단락의 역할 (제목/본문/서명 등)을 읽어템플릿_rolemap.json에 기록합니다(형식:{"0": "title", "1": "body", ...}). 그런 다음--template 템플릿.docx --template-rolemap-json 템플릿_rolemap.json을 사용하여 코드가 템플릿 형식을 확실하게 읽도록 합니다.
FormatSpec 스키마:
{ "page": {"margin": {"top_mm": 37, "bottom_mm": 35, "left_mm": 28, "right_mm": 26}, "line_grid": {"line_pt": 28}}, "roles": { "body": {"font_eastasia": "FangSong_GB2312", "font_ascii": "Times New Roman", "size_pt": 16, "bold": false, "alignment": "justify", "first_line_indent_chars": 2, "line_spacing": {"type": "exact", "pt": 28}} } }역할 열거:
title/subtitle/heading_1/heading_2/heading_3/body/signature/date/ attachment_label/attachment/other.body는 필수입니다; 정렬 값은left/center/right/justify;size_pt872, 여백 550mm. 규격에 언급되지 않은 역할은 작성하지 말고, 언급되지 않은 필드는 만들지 마십시오. - 사용자가 규격 텍스트를 제공한 경우: 이를 읽고 아래 스키마에 따라 JSON을 작성하여
-
직접 RoleMap 생성 (단락 역할 JSON): 1단계의 단락 목록을 읽고,
in_table=false인 각 단락에 대해 열거형에서 역할을 선택하여출력디렉터리/정렬후_rolemap.json에 저장합니다. 형식은{"0": "title", "1": "body", ...}이며, 모든 비표 단락을 포함해야 합니다. 판단 기준: 텍스트 내용, 위치 순서, 현재 형식 힌트; 서명은 끝부분에 서명 느낌이 강함; 날짜는 "년/월/일" 포함; 제목은 맨 앞에 있고 독립행입니다. -
형식 정리 실행 (결정적 코드가 처리):
# 규격 텍스트 출처 (FormatSpec은 2단계에서 직접 생성) python main.py --spec-json 출력디렉터리/정렬후_formatspec.json \ --rolemap-json 출력디렉터리/정렬후_rolemap.json \ --target 대상.docx --out 출력디렉터리/정렬후.docx # 템플릿 출처 python main.py --template 템플릿.docx --template-rolemap-json 템플릿_rolemap.json \ --rolemap-json 출력디렉터리/정렬후_rolemap.json \ --target 대상.docx --out 출력디렉터리/정렬후.docx직접 생성한 JSON은 코드에서 다시 검증됩니다(역할 유효성, 단락 전체 포함, 값 범위 확인). 검증 실패 시 오류와 이유가 보고되며, 수정 후 다시 실행하면 됩니다.
사용 방법 2: 독립 API 모드 (선택 사항)
에이전트가 없는 환경(서버, 예약 작업, 로컬 독립 실행)에서만 모델을 구성해야 합니다.
.env.example을 .env로 복사하고 LLM_BASE_URL / LLM_API_KEY / LLM_MODEL을 입력합니다
(다중 모달 모델 권장, 위 섹션 참조). 그런 다음:
# 규격 텍스트를 형식 출처로 사용 (LLM이 자동으로 규칙 추출)
python main.py --spec 규격텍스트.txt --target 대상.docx --out 출력디렉터리/정렬후.docx
# Word 템플릿을 형식 출처로 사용
python main.py --template 템플릿.docx --target 대상.docx --out 출력디렉터리/정렬후.docx
템플릿은 규격에 따라 이미 정렬된 모든 문서(당위원회 회의 자료, 계약서 견본, 법률 의견서, 컨설팅 보고서, 논문 샘플 등)가 될 수 있으며, 템플릿을 수정하거나 레이블을 지정할 필요가 없습니다.
시각적 자체 검사 (선택 사항, 사용 방법 2 + 다중 모달 모델만 해당)
--verify 추가: 정렬 후 이미지로 렌더링하고, 시각적 모델이 규격과 대조하여 품질을 검사하며,
편차를 발견하면 정확하게 수정하고 한 번 재정렬합니다(단일 라운드, 열린 루프 없음).
사용 방법 1에서 호스트 에이전트가 이미지 이해 능력을 갖춘 경우 직접 렌더링하여 확인할 수 있습니다:
출력 디렉터리의 *_verify_render/ 아래에 페이지별 PNG 파일이 있습니다.
출력 산출물
실행할 때마다 생성되는 파일들(동일한 디렉터리, 동일한 이름 접두사 사용):
정렬후.docx— 명명된 스타일이 작성된 깔끔한 문서정렬후_tracked.docx— 변경 추적 모드: Word 검토 보기에서 각 형식 변경 사항을 볼 수 있으며, 하나씩 수락/거부 가능정렬후_report.docx/.md— 변경 대조 보고서(페이지 설정, 규칙, 단락 세부 정보)정렬후_formatspec.json/_rolemap.json/_stylemap.json— 중간 산출물(검토를 위한 "이해 증거")
문제 해결 빠른 참조
LLM 구성 누락→ .env 또는 환경 변수 확인- 역할 레이블링 반복 실패 → 모델 JSON 출력이 불안정함,
--rolemap-json으로 수동 레이블링 사용 - 시각적 검토 400 temperature → 해당 모델은 temperature = 1만 허용함, .env에서
LLM_TEMPERATURE= 1설정 - 시각적 검토 이미지 오류 → 엔드포인트가 data:base64 인라인 이미지를 지원하지 않거나 현재 모델에 이미지 입력 기능이 없음; 다중 모달 모델로 전환
- 렌더링 실패 → Windows는 Word 설치 필요(COM 사용), macOS/Linux는 LibreOffice 필요
examples/ 디렉터리
messy.docx: 형식이 완전히 엉망인 예시 공문(통지)spec.txt: 공문 정리 규격 텍스트 예시spec_std.json/rolemap_std.json: 위 예시의 정답(수락 기준 + 폴백 입력)template-committee_meeting_agenda_sample.docx: 템플릿 모드의 형식 출처 예시