--- name: docx description: "변경 내용 추적, 주석, 서식 보존, 텍스트 추출을 지원하는 포괄적인 문서 생성, 편집, 분석. Claude가 전문 문서(.docx 파일)를 다음과 같은 작업에 사용해야 할 때: (1) 새 문서 생성, (2) 내용 수정 또는 편집, (3) 변경 내용 추적 작업, (4) 주석 추가, 또는 기타 문서 작업" license: 독점 라이선스. 전체 약관은 LICENSE.txt 참조 --- # DOCX 생성, 편집, 분석 ## 개요 사용자가 .docx 파일을 생성, 편집, 분석하도록 요청할 수 있습니다. .docx 파일은 본질적으로 읽거나 편집할 수 있는 XML 파일과 기타 리소스가 포함된 ZIP 아카이브입니다. 작업에 따라 다양한 도구와 워크플로우를 사용할 수 있습니다. ## 워크플로우 의사 결정 트리 ### 내용 읽기\/분석 아래 "텍스트 추출" 또는 "원시 XML 접근" 섹션 사용 ### 새 문서 생성 "새 Word 문서 생성" 워크플로우 사용 ### 기존 문서 편집 - **본인의 문서 + 간단한 변경** "기본 OOXML 편집" 워크플로우 사용 - **타인의 문서** **"레드라인 워크플로우"** 사용 (권장 기본값) - **법률, 학술, 비즈니스 또는 정부 문서** **"레드라인 워크플로우"** 사용 (필수) ## 내용 읽기 및 분석 ### 텍스트 추출 문서의 텍스트 내용만 읽어야 한다면 pandoc을 사용하여 문서를 마크다운으로 변환하세요. Pandoc은 문서 구조 보존에 우수한 지원을 제공하며 변경 내용 추적을 표시할 수 있습니다: ```bash # 변경 내용 추적과 함께 문서를 마크다운으로 변환 pandoc --track-changes=all path-to-file.docx -o output.md # 옵션: --track-changes=accept\/reject\/all ``` ### 원시 XML 접근 다음을 위해 원시 XML 접근이 필요합니다: 주석, 복잡한 서식, 문서 구조, 포함된 미디어, 메타데이터. 이러한 기능 중 하나라도 필요하면 문서를 풀고 원시 XML 내용을 읽어야 합니다. #### 파일 풀기 `python ooxml\/scripts\/unpack.py ` #### 주요 파일 구조 * `word\/document.xml` - 주요 문서 내용 * `word\/comments.xml` - document.xml에 참조된 주석 * `word\/media\/` - 포함된 이미지 및 미디어 파일 * 변경 내용 추적은 `` (삽입) 및 `` (삭제) 태그 사용 ## 새 Word 문서 생성 새 Word 문서를 처음부터 생성할 때는 JavaScript\/TypeScript로 Word 문서를 생성할 수 있는 **docx-js**를 사용하세요. ### 워크플로우 1. **필수 - 전체 파일 읽기**: [`docx-js.md`](docx-js.md) (~500줄)를 처음부터 끝까지 완전히 읽으세요. **이 파일을 읽을 때 범위 제한을 설정하지 마세요.** 문서 생성을 진행하기 전에 상세한 구문, 중요한 서식 규칙, 모범 사례를 위해 전체 파일 내용을 읽으세요. 2. Document, Paragraph, TextRun 컴포넌트를 사용하여 JavaScript\/TypeScript 파일 생성 (모든 의존성이 설치되어 있다고 가정하지만, 그렇지 않은 경우 아래 의존성 섹션 참조) 3. Packer.toBuffer()를 사용하여 .docx로 내보내기 ## 기존 Word 문서 편집 기존 Word 문서를 편집할 때는 **Document 라이브러리** (OOXML 조작을 위한 Python 라이브러리)를 사용하세요. 이 라이브러리는 인프라 설정을 자동으로 처리하고 문서 조작을 위한 메서드를 제공합니다. 복잡한 시나리오의 경우 라이브러리를 통해 기본 DOM에 직접 접근할 수 있습니다. ### 워크플로우 1. **필수 - 전체 파일 읽기**: [`ooxml.md`](ooxml.md) (~600줄)를 처음부터 끝까지 완전히 읽으세요. **이 파일을 읽을 때 범위 제한을 설정하지 마세요.** Document 라이브러리 API와 문서 파일 직접 편집을 위한 XML 패턴을 위해 전체 파일 내용을 읽으세요. 2. 문서 풀기: `python ooxml\/scripts\/unpack.py ` 3. Document 라이브러리를 사용하여 Python 스크립트 생성 및 실행 (ooxml.md의 "Document Library" 섹션 참조) 4. 최종 문서 패킹: `python ooxml\/scripts\/pack.py ` Document 라이브러리는 일반적인 작업을 위한 고수준 메서드와 복잡한 시나리오를 위한 직접 DOM 접근을 모두 제공합니다. ## 문서 검토를 위한 레드라인 워크플로우 이 워크플로우를 사용하면 OOXML에서 구현하기 전에 마크다운을 사용하여 포괄적인 변경 내용 추적을 계획할 수 있습니다. **중요**: 완전한 변경 내용 추적을 위해 모든 변경 사항을 체계적으로 구현해야 합니다. **배치 전략**: 관련 변경 사항을 3-10개의 변경으로 그룹화하세요. 이렇게 하면 효율성을 유지하면서 디버깅을 관리할 수 있습니다. 다음으로 이동하기 전에 각 배치를 테스트하세요. **원칙: 최소한의 정확한 편집** 변경 내용 추적을 구현할 때 실제로 변경된 텍스트만 표시하세요. 변경되지 않은 텍스트를 반복하면 편집 검토가 어려워지고 전문적이지 않게 보입니다. 대체를 다음으로 분해하세요: [변경되지 않은 텍스트] + [삭제] + [삽입] + [변경되지 않은 텍스트]. 원본의 `` 요소를 추출하고 재사용하여 변경되지 않은 텍스트의 원래 run의 RSID를 보존하세요. 예시 - 문장에서 "30일"을 "60일"로 변경: ```python # 나쁨 - 전체 문장 대체 '기간은 30일입니다.<\/w:delText><\/w:r><\/w:del>기간은 60일입니다.<\/w:t><\/w:r><\/w:ins>' # 좋음 - 변경된 부분만 표시, 변경되지 않은 텍스트는 원래 보존 '기간은 <\/w:t><\/w:r>30<\/w:delText><\/w:r><\/w:del>60<\/w:t><\/w:r><\/w:ins>일입니다.<\/w:t><\/w:r>' ``` ### 변경 내용 추적 워크플로우 1. **마크다운 표현 가져오기**: 변경 내용 추적이 보존된 상태로 문서를 마크다운으로 변환: ```bash pandoc --track-changes=all path-to-file.docx -o current.md ``` 2. **변경 사항 식별 및 그룹화**: 문서를 검토하고 필요한 모든 변경 사항을 식별하여 논리적 배치로 구성: **위치 찾기 방법** (XML에서 변경 사항 찾기용): - 섹션\/제목 번호 (예: "섹션 3.2", "제4조") - 번호가 매겨진 경우 단락 식별자 - 고유한 주변 텍스트가 있는 grep 패턴 - 문서 구조 (예: "첫 번째 단락", "서명 블록") - **마크다운 줄 번호를 사용하지 마세요** - XML 구조에 매핑되지 않음 **배치 구성** (배치당 3-10개의 관련 변경 그룹화): - 섹션별: "배치 1: 섹션 2 수정", "배치 2: 섹션 5 업데이트" - 유형별: "배치 1: 날짜 수정", "배치 2: 당사자 이름 변경" - 복잡도별: 간단한 텍스트 대체로 시작한 다음 복잡한 구조 변경 처리 - 순차적: "배치 1: 1-3페이지", "배치 2: 4-6페이지" 3. **문서 읽기 및 풀기**: - **필수 - 전체 파일 읽기**: [`ooxml.md`](ooxml.md) (~600줄)를 처음부터 끝까지 완전히 읽으세요. **이 파일을 읽을 때 범위 제한을 설정하지 마세요.** "Document Library" 및 "Tracked Change Patterns" 섹션에 특히 주의하세요. - **문서 풀기**: `python ooxml\/scripts\/unpack.py ` - **제안된 RSID 참고**: unpack 스크립트는 변경 내용 추적에 사용할 RSID를 제안합니다. 4b 단계에서 사용할 이 RSID를 복사하세요. 4. **배치로 변경 사항 구현**: 변경 사항을 논리적으로 그룹화하고(섹션별, 유형별 또는 근접성별) 단일 스크립트에서 함께 구현하세요. 이 접근 방식은: - 디버깅 용이 (더 작은 배치 = 오류 격리 용이) - 점진적 진행 가능 - 효율성 유지 (3-10개 변경의 배치 크기가 적합) **권장 배치 그룹**: - 문서 섹션별 (예: "섹션 3 변경", "정의", "해지 조항") - 변경 유형별 (예: "날짜 변경", "당사자 이름 업데이트", "법률 용어 대체") - 근접성별 (예: "1-3페이지 변경", "문서 전반부 변경") 각 관련 변경 배치에 대해: **a. 텍스트를 XML에 매핑**: `word\/document.xml`에서 텍스트를 grep하여 텍스트가 `` 요소에 어떻게 분할되어 있는지 확인. **b. 스크립트 생성 및 실행**: `get_node`를 사용하여 노드를 찾고, 변경 사항을 구현한 다음 `doc.save()`. ooxml.md의 **"Document Library"** 섹션에서 패턴 참조. **참고**: 스크립트를 작성하기 직전에 항상 `word\/document.xml`을 grep하여 현재 줄 번호를 가져오고 텍스트 내용을 확인하세요. 각 스크립트 실행 후 줄 번호가 변경됩니다. 5. **문서 패킹**: 모든 배치가 완료되면 풀린 디렉토리를 다시 .docx로 변환: ```bash python ooxml\/scripts\/pack.py unpacked reviewed-document.docx ``` 6. **최종 검증**: 전체 문서에 대한 포괄적인 검사 수행: - 최종 문서를 마크다운으로 변환: ```bash pandoc --track-changes=all reviewed-document.docx -o verification.md ``` - 모든 변경 사항이 올바르게 적용되었는지 확인: ```bash grep "원래 문구" verification.md # 찾으면 안 됨 grep "대체 문구" verification.md # 찾아야 함 ``` - 의도하지 않은 변경 사항이 도입되지 않았는지 확인 ## 문서를 이미지로 변환 Word 문서를 시각적으로 분석하려면 두 단계 프로세스를 사용하여 이미지로 변환하세요: 1. **DOCX를 PDF로 변환**: ```bash soffice --headless --convert-to pdf document.docx ``` 2. **PDF 페이지를 JPEG 이미지로 변환**: ```bash pdftoppm -jpeg -r 150 document.pdf page ``` 이렇게 하면 `page-1.jpg`, `page-2.jpg` 등의 파일이 생성됩니다. 옵션: - `-r 150`: 해상도를 150 DPI로 설정 (품질\/크기 균형 조정) - `-jpeg`: JPEG 형식 출력 (선호하는 경우 PNG는 `-png` 사용) - `-f N`: 변환할 첫 번째 페이지 (예: `-f 2`는 2페이지부터 시작) - `-l N`: 변환할 마지막 페이지 (예: `-l 5`는 5페이지에서 중지) - `page`: 출력 파일의 접두사 특정 범위 예시: ```bash pdftoppm -jpeg -r 150 -f 2 -l 5 document.pdf page # 2-5페이지만 변환 ``` ## 코드 스타일 가이드라인 **중요**: DOCX 작업을 위한 코드 생성 시: - 간결한 코드 작성 - 장황한 변수명과 중복 작업 피하기 - 불필요한 print 문 피하기 ## 의존성 필수 의존성 (사용 불가능한 경우 설치): - **pandoc**: `sudo apt-get install pandoc` (텍스트 추출용) - **docx**: `npm install -g docx` (새 문서 생성용) - **LibreOffice**: `sudo apt-get install libreoffice` (PDF 변환용) - **Poppler**: `sudo apt-get install poppler-utils` (PDF를 이미지로 변환하는 pdftoppm용) - **defusedxml**: `pip install defusedxml` (보안 XML 파싱용)