DOCX 스킬
사용 시기
- 레이아웃(표, 다이어그램, 페이지 나눔)이 중요한 DOCX 콘텐츠를 읽거나 검토할 때
- 전문적인 서식을 갖춘 DOCX 파일을 만들거나 편집할 때
- 전달 전 시각적 레이아웃을 검증할 때
워크플로우
- 시각적 검토(레이아웃, 표, 다이어그램)를 우선시합니다.
soffice와pdftoppm을 사용할 수 있으면 DOCX -> PDF -> PNG로 변환합니다.- 또는
scripts/render_docx.py를 사용합니다(pdf2image와 Poppler 필요). - 이러한 도구가 없으면 설치하거나 사용자에게 로컬에서 렌더링된 페이지를 검토하도록 요청합니다.
- 편집 및 구조화된 생성(제목, 스타일, 표, 목록)에는
python-docx를 사용합니다. - 의미 있는 변경 후에는 다시 렌더링하여 페이지를 검사합니다.
- 시각적 검토가 불가능하면 대안으로
python-docx로 텍스트를 추출하고 레이아웃 위험을 알립니다. - 중간 출력물을 정리하고 최종 승인 후 정리합니다.
임시 파일 및 출력 규칙
- 중간 파일에는
tmp/docs/를 사용하고, 작업이 끝나면 삭제합니다. - 이 저장소에서 작업할 때는 최종 결과물을
output/doc/아래에 작성합니다. - 파일 이름은 안정적이고 설명적으로 유지합니다.
종속성 (없으면 설치)
종속성 관리는 uv를 선호합니다.
Python 패키지:
uv pip install python-docx pdf2image
uv를 사용할 수 없는 경우:
python3 -m pip install python-docx pdf2image
시스템 도구(렌더링용):
# macOS (Homebrew)
brew install libreoffice poppler
# Ubuntu/Debian
sudo apt-get install -y libreoffice poppler-utils
이 환경에서 설치할 수 없으면 누락된 종속성과 로컬 설치 방법을 사용자에게 알려줍니다.
환경
필요한 환경 변수가 없습니다.
렌더링 명령어
DOCX -> PDF:
soffice -env:UserInstallation=file:///tmp/lo_profile_$$ --headless --convert-to pdf --outdir $OUTDIR $INPUT_DOCX
PDF -> PNG:
pdftoppm -png $OUTDIR/$BASENAME.pdf $OUTDIR/$BASENAME
번들 도우미:
python3 scripts/render_docx.py /path/to/file.docx --output_dir /tmp/docx_pages
품질 기준
- 고객에게 제출할 수 있는 문서를 제공합니다. 일관된 타이포그래피, 간격, 여백, 명확한 계층 구조를 갖추어야 합니다.
- 포맷 결함(글자 잘림/겹침, 표 깨짐, 읽을 수 없는 문자, 기본 템플릿 스타일)을 피합니다.
- 차트, 표, 시각 자료는 렌더링된 페이지에서 읽을 수 있어야 하며 정렬이 정확해야 합니다.
- ASCII 하이픈만 사용합니다. U+2011(줄 바꿈 없는 하이픈) 및 기타 유니코드 대시는 피합니다.
- 인용 및 참조는 사람이 읽을 수 있어야 하며, 도구 토큰이나 플레이스홀더 문자열을 남기지 않습니다.
최종 점검
- 최종 전달 전에 100% 확대로 모든 페이지를 다시 렌더링하고 검사합니다.
- 간격, 정렬 또는 페이지 나눔 문제를 수정하고 렌더링 루프를 반복합니다.
- 사용자가 유지하도록 요청하지 않는 한 남은 파일(임시 파일, 중복 렌더링)이 없는지 확인합니다.