Docx Skill
python-docx를 통해 작은 CLI로 Microsoft Word .docx 파일을 생성, 읽기, 편집, 템플릿화합니다. 텍스트, 스타일, 목록, 표, 이미지, 머리글/바닥글, {{token}} 템플릿, 변경 내용(목록/수락/거부), 댓글(목록/추가/삭제), 목차 및 페이지 번호 필드, 패키지 상태 확인을 처리합니다. 문서 자체를 렌더링하지는 않으며(PDF는 LibreOffice 필요 — PDF로 변환 참조), 레거시 .doc는 편집하지 않습니다.
사용 시기
- 사용자가 Word 문서(보고서, 편지, 계약서) 생성을 요청합니다.
.docx파일의 텍스트, 개요, 스타일 또는 포함된 이미지가 필요합니다.- 기존
.docx를 변경해야 합니다: 텍스트 교체, 표 셀 편집, 문단 삽입/삭제, 스타일 적용, 분할된 실행(run) 병합. - 데이터로 채울
{{placeholders}}가 포함된.docx템플릿이 있습니다. - 문서에 검토할 변경 내용이 있습니다.
- 리뷰어의 댓글을 읽거나 댓글을 추가/삭제해야 합니다.
.docx가 열리지 않거나 비정상적으로 작동하여 손상 진단이 필요합니다.- 문서에 목차나 "Page X of Y" 바닥글이 필요합니다.
- 다음에는 사용하지 않음:
.doc(레거시),.odt, 또는 WYSIWYG 레이아웃 작업.
사전 요구 사항
- Python 3.10+ 및
python-docx설치:pip install python-docx(import 이름은docx; lxml은 함께 설치됨). - 댓글
add는 python-docx >= 1.2에서 네이티브 API를 사용하고, 이전 버전에서는 XML 폴백을 사용합니다. 둘 다 자동입니다. - 이미지 블록의 경우: 이미지 파일이 로컬에 존재해야 합니다(PNG/JPEG).
실행 방법
모든 도우미는 이 파일 옆의 scripts/에 있습니다. terminal 도구로 실행하며, 각각 --help를 지원하고 stdout에 JSON을 출력합니다.
python scripts/docx_create.py spec.json out.docx
python scripts/docx_read.py out.docx --text
python scripts/docx_edit.py replace out.docx --find old --replace new
python scripts/docx_template.py tpl.docx values.json filled.docx
python scripts/docx_revisions.py list out.docx
python scripts/docx_comments.py list out.docx
python scripts/docx_validate.py out.docx
빠른 참조
| 작업 | 명령어 |
|---|---|
| JSON 사양에서 생성 | docx_create.py spec.json out.docx |
| 전체 텍스트(본문+표+머리글/바닥글) | docx_read.py f.docx --text |
| 제목 개요 + 표 모양 | docx_read.py f.docx --structure |
| 실제 사용된 스타일 | docx_read.py f.docx --styles |
| 포함된 이미지 추출 | docx_read.py f.docx --images outdir/ |
| 변경 내용/댓글 감지 | docx_read.py f.docx --revisions |
| 찾기/바꾸기(서식 유지) | docx_edit.py replace f.docx --find A --replace B -o out.docx |
| 표 셀 설정 | docx_edit.py set-cell f.docx --table 0 --row 1 --col 2 --text X |
| 인덱스 N 앞에 문단 삽입 | docx_edit.py insert f.docx --index N --text X --style Normal |
| 문단 N 삭제 | docx_edit.py delete f.docx --index N |
| 문단 N에 스타일 적용 | docx_edit.py style f.docx --index N --style "Heading 1" |
| 동일 서식 인접 실행 병합 | docx_edit.py normalize f.docx -o out.docx |
| 문단 N 앞에 TOC 필드 삽입 | docx_edit.py toc f.docx --index N -o out.docx |
| "Page X of Y" 바닥글 필드 | docx_edit.py page-numbers f.docx |
{{tokens}} 채우기 | docx_template.py tpl.docx values.json out.docx --strict |
| 변경 내용 목록(id/작성자/날짜/텍스트) | docx_revisions.py list f.docx |
| 모든 변경 내용 수락/거부 | docx_revisions.py accept-all f.docx -o out.docx (또는 reject-all) |
| 단일 변경 내용 수락/거부 | docx_revisions.py accept f.docx --id 3 -o out.docx |
| 댓글 목록(+앵커 텍스트) | docx_comments.py list f.docx |
| 텍스트에 앵커된 댓글 추가 | docx_comments.py add f.docx --target "phrase" --text "note" --author You |
| ID로 댓글 삭제 | docx_comments.py delete f.docx --id 0 |
| 패키지 상태 확인 | docx_validate.py f.docx (오류 시 exit 1) |
절차
- 생성.
write_file로 JSON 사양을 작성한 후scripts/docx_create.py를 실행합니다. 사양은 다음을 지원합니다:page(크기 + 여백, mm 단위),header/footer문자열,footer_page_numbers("Page X of Y" 필드 바닥글 추가),styles(글꼴, 크기, 굵게/기울임꼴, 16진수color가 있는 사용자 정의 문단 스타일), 그리고blocks—heading(수준 1-9),paragraph(text또는 각 실행이bold/italic/underline을 설정할 수 있는runs목록),bullet_list,numbered_list,table(header행은 굵게 렌더링,rows, 선택적 내장 표style(예:Table Grid)),image(path, 선택적width_mm),toc(목차 필드),page_break. 전체 사양 형식은scripts/docx_create.py상단에 문서화되어 있습니다. - 읽기.
scripts/docx_read.py를 정확히 하나의 모드 플래그와 함께 사용합니다.--text는 본문 문단, 모든 표 셀 텍스트, 머리글/바닥글 텍스트를 JSON으로 반환합니다.--structure는 제목 개요와 문단/표/섹션 개수를 반환합니다.--images DIR은 패키지 내word/media/아래의 모든 파일을 복사합니다. - 편집.
scripts/docx_edit.py를 사용합니다.replace는 본문, 표(중첩 포함), 머리글과 바닥글을 탐색하며 실행 서식을 유지합니다.--body-only를 추가하면 머리글/바닥글을 건너뜁니다.-o out.docx를 전달하여 원본을 유지하고, 생략하면 제자리 편집합니다.insert/delete/style/toc의 문단 인덱스는--structure/--text본문 순서를 참조합니다. Word에서 많이 편집한 문서는 먼저normalize를 실행하세요. 인접한 동일 서식 실행을 병합하여 이후 찾기/바꾸기가 안정적으로 일치합니다. - 변경 내용 검토.
docx_revisions.py list는 본문, 표, 머리글 또는 바닥글의 모든w:ins및w:del(id, 작성자, 날짜, 영향받은 텍스트)을 보고합니다.accept-all/reject-all은 일괄 처리합니다.accept/reject --id N은 단일 변경 내용을 처리합니다. 수락은 삽입을 유지하고 삭제된 텍스트를 제거하며, 거부는 반대입니다. - 댓글.
docx_comments.py list는 각 댓글의 id, 작성자, 날짜, 본문 텍스트 및 앵커된 문서 텍스트를 반환합니다.add --target "some phrase"는 해당 구문의 첫 번째 항목에 새 댓글을 고정합니다(실행은 필요에 따라 분할, 서식 유지).delete --id N은 문서 텍스트를 건드리지 않고 댓글과 해당 마커를 제거합니다. - 템플릿. 문서에
{{name}}스타일 토큰을 넣습니다. 값이 포함된 JSON 객체로scripts/docx_template.py를 실행합니다.--strict를 사용하여 채워지지 않은 토큰이 있으면 실패하게 합니다. JSON 출력은 어느 쪽이든filled개수와unfilled_tokens를 나열합니다. - 확인 (항상):
--text또는--structure로 출력을 다시 읽고, 변경 내용/댓글 작업을 수행한 모든 항목에 대해docx_validate.py를 실행합니다.
PDF로 변환
별도 스크립트가 필요하지 않습니다. LibreOffice가 설치된 경우 헤드리스로 변환합니다:
soffice --headless --convert-to pdf --outdir outdir/ file.docx
먼저 가용성을 확인하십시오(command -v soffice || command -v libreoffice). 둘 다 없으면 PDF 변환이 이 환경에서 불가능하다고 사용자에게 알리십시오. 임시방편으로 하지 마십시오. python-docx는 PDF를 렌더링할 수 없으며 레이아웃 정확성을 위해 실제 렌더러가 필요합니다.
함정
- 토큰이 여러 실행에 분할됨. Word는 종종 텍스트를 여러 실행으로 조각냅니다. 교체 도우미는 일치하는 실행을 병합합니다(대체는 첫 번째 실행의 서식을 상속). 먼저
docx_edit.py normalize를 실행하면 이후 모든 편집에 대해 조각화가 줄어듭니다. - 변경 내용 범위.
docx_revisions.py는 실행 수준의 삽입 및 삭제(압도적 다수)를 해결합니다. 문단 표시 및 표 행 변경 사항, 형식 변경 레코드 및 이동은--revisions에서 감지되지만 자동 해결되지는 않습니다.references/revisions-and-comments.md를 참조하고 Word에 맡기십시오. - 댓글 스레딩. 답글 및 "해결됨" 상태는 이 스킬이 무시하는
commentsExtended.xml에 있습니다. 추가하는 댓글은 일반 최상위 댓글입니다. - 필드 결과는 Word에서 계산됩니다.
toc,page-numbers및toc/footer_page_numbers사양 옵션은 필드 코드를 씁니다. Word/LibreOffice는 파일이 열릴 때 실제 항목과 번호를 채웁니다(Word는 필드 업데이트를 요청할 수 있음). python-docx는 이를 계산하지 않으므로 그때까지 자리 표시자 텍스트가 표시됩니다. - 유효성 검사는 상태 확인이지 스키마 검증이 아닙니다.
docx_validate.py는 zip, 필수 부품, 관계 대상, 이미지 매직 바이트 및 참조된 스타일을 확인합니다. XSD 검증이 아닙니다. 파일이 통과해도 Word가 싫어하는 XML이 포함될 수 있습니다. - 스타일 이름은 존재해야 합니다. 문서에 정의되지 않은 스타일을 적용하면
KeyError가 발생합니다.Heading 1,List Bullet,List Number,Table Grid와 같은 기본 제공 스타일은 기본 템플릿에 있습니다. 사용자 정의 스타일은 먼저 생성 사양에서 선언해야 합니다. - 번호 매기기 목록이 다시 시작됩니다.
List Number는 Word의 기본 번호 매기기에 의존합니다. 하나의 문서에 있는 별도 목록은 다시 시작하는 대신 번호를 계속 매길 수 있습니다. 정확한 여러 목록 번호 매기기가 필요한 사용자에게 경고하십시오. - 셀 쓰기는 서식을 대체합니다.
set-cell은cell.text = ...를 사용하여 해당 셀의 실행을 일반 서식으로 재설정합니다. - 인코딩. 모든 JSON 사양/값 파일은 명시적으로 UTF-8로 읽습니다. 자체 접착 코드를 작성할 때 로케일 기본값에 의존하지 마십시오.
- XML을 unzip-and-sed하지 마십시오. 스크립트(또는 python-docx)를 통해 편집하십시오.
document.xml에서 원시 텍스트 대체는 파일을 쉽게 손상시킵니다. JSON 입력에만patch/write_file을 사용하고.docx자체에는 절대 사용하지 마십시오.
확인
- 생성/편집/템플릿 후
docx_read.py out.docx --text를 실행하고 예상 문자열이 나타나는지(및 이전 문자열이 사라졌는지) 확인합니다. - 수락/거부 후
docx_revisions.py list는[]를 반환해야 합니다(또는 의도적으로 남긴 id만). 댓글 작업 후docx_comments.py list는 변경 사항을 반영해야 하며--text출력은 변경되지 않아야 합니다. docx_validate.py out.docx는 건강한 패키지에서"ok": true와 함께 exit 0을 반환합니다. 변경 내용/댓글/필드 조작 후 항상 실행하십시오.- 템플릿은
--strict로 실행하거나unfilled_tokens == []를 확인합니다. - 구조 확인:
--structure는 예상 제목 개요와 표 모양을 표시해야 합니다.--styles는 사용자 정의 스타일이 적용되었는지 확인합니다.