Word 문서
.docx 생성, 편집, 읽기 및 시각적 검증
기본 활성화: 예 —
docx 스킬은 기본적으로 사용 가능하며, Word 문서, .docx 파일, 보고서, 메모, 편지 또는 템플릿을 언급하면 자동으로 트리거됩니다. 수동 로딩이 필요 없습니다.개요
docx 스킬은 Word 문서의 전체 라이프사이클을 처리합니다: 처음부터 생성, 기존 파일 편집, 읽기 및 분석, 템플릿 기반 생성, 변경 내용 추적 관리, 그리고 필수 시각적 QA 검증. 이 스킬은 .docx 파일에만 적용되며 — PDF, 스프레드시트, HWPX 또는 Google Docs에는 적용되지 않습니다.
주요 도구는 PATH에 있는 CLI인 officecli로, 작업의 약 80%를 처리합니다 (add, set, remove, validate, query, track-change accept/reject). officecli가 처리할 수 없는 작업 — 변경 내용 추적 생성, OMML 수식, 대량 패턴 매칭 — 의 경우 scripts/에 있는 Python OOXML 스크립트로 대체합니다.
트리거
| 패턴 | 예시 |
|---|---|
| 파일 확장자 | .docx, Word 문서 |
| 문서 유형 | 보고서, 메모, 편지, 제안서, 계약서 |
| 키워드 | "Word doc", "template", "tracked changes", "table of contents" |
| 한국어 트리거 | "워드 문서", "보고서 만들어줘", "문서 작성해줘" |
빠른 참조
| 작업 | 도구 | 명령 패턴 | 비고 |
|---|---|---|---|
| 기존 문서와 동일한 서식 적용 | shell + officecli | cp source.docx target.docx && officecli open target.docx | 스타일/머리글/바닥글 상속 |
| 빈 DOCX 생성 | officecli | officecli create report.docx | 실제 Office 파일에서 시작 |
| 단락 추가 | officecli | officecli add FILE /body --type paragraph --prop text="..." | 기본 쓰기 경로 |
| 단락/런 편집 | officecli | officecli set FILE /body/p[N] --prop ... | 정확한 경로 지정 |
| 텍스트/개요/통계 읽기 | officecli | officecli view FILE text | 모드: text, annotated, outline, stats, issues, html |
| 문서 쿼리 | officecli | officecli query FILE "p[style=Heading1]" | CSS 유사 셀렉터 |
| 템플릿 치환 | officecli | officecli set FILE / --prop find="{{X}}" --prop replace="Y" | 템플릿 구조 보존 |
| 유효성 검사 / 이슈 스캔 | officecli | officecli validate FILE | view FILE issues와 함께 사용 |
| 변경 내용 추적 수락/거부 | officecli | officecli set FILE / --prop accept-changes=all | reject-changes=all도 가능 |
| 변경 내용 추적 생성 | Python (L3/L4) | scripts/docx_cli.py + ooxml/redline_diff.py | officecli는 생성 불가 — 수락/거부만 가능 |
| OMML 수식 | Python (L4) | 압축 해제 → <m:oMath> 삽입 → 재압축 | officecli는 OMML 생성 불가 |
| 복잡한 앵커 주석 | Python (L3) | python3 scripts/comment.py IN OUT --text "..." --anchor "..." | officecli 범위를 넘어서는 주석용 |
| PDF 변환 / 시각적 QA | soffice | soffice --headless --convert-to pdf FILE | 스크린샷 기반 QA |
"~해줘" 사용 예시
"분기 보고서 만들어줘"
적절한 제목 계층 구조, 목차, 표, 전문적인 서식을 갖춘 분기 보고서 문서를 처음부터 생성합니다.
적절한 제목 계층 구조, 목차, 표, 전문적인 서식을 갖춘 분기 보고서 문서를 처음부터 생성합니다.
officecli create → 구조 추가 → 유효성 검사 → PDF 검증 순서로 진행합니다.
"이 문서 형식에 맞춰서 새로 작성해줘"
참조 기반 편집: 소스 파일을 복사하여 모든 스타일, 머리글, 바닥글을 상속한 다음, 문서의 시각적 정체성을 유지하면서 본문 내용을 교체합니다. 아래의 참조 기반 편집 워크플로우를 참고하세요.
참조 기반 편집: 소스 파일을 복사하여 모든 스타일, 머리글, 바닥글을 상속한 다음, 문서의 시각적 정체성을 유지하면서 본문 내용을 교체합니다. 아래의 참조 기반 편집 워크플로우를 참고하세요.
"이 워드 문서 내용 요약해줘"
officecli view FILE text와 view FILE outline을 사용하여 문서를 읽고 분석한 다음, 제목, 주요 내용, 문서 통계에 대한 구조화된 요약을 제공합니다.
"변경사항 추적해서 수정해줘"
officecli는 변경 내용 추적을 수락/거부만 할 수 있고 생성은 할 수 없으므로, Python OOXML 스크립트를 통해 변경 내용 추적(레드라인)을 생성합니다. 자동으로 L3/L4로 에스컬레이션됩니다.
officecli는 변경 내용 추적을 수락/거부만 할 수 있고 생성은 할 수 없으므로, Python OOXML 스크립트를 통해 변경 내용 추적(레드라인)을 생성합니다. 자동으로 L3/L4로 에스컬레이션됩니다.
"문서 템플릿에 데이터 채워줘"
officecli set FILE / --prop find="{{X}}" --prop replace="Y"를 사용한 템플릿 안전 치환으로, 템플릿의 서식과 구조를 보존하면서 플레이스홀더를 채웁니다.
참조 기반 편집
사용자가 "X.docx처럼 서식 맞춰줘", "기존 스타일에 맞춰줘", "템플릿 기반으로"라고 하거나 소스 파일을 제공하면 — 항상 소스 파일에서 시작하세요. 절대 처음부터 다시 만들지 마세요.
워크플로우
- 소스 복사:
cp source.docx target.docx— 모든 스타일, 여백, 번호 매기기, 머리글, 바닥글을 상속합니다 - 열기:
officecli open target.docx— 데몬이 시작되고, 명령이 즉시 반환됩니다 - 본문 내용만 제거 —
/styles,/numbering,/header,/footer는 유지합니다 - 기존 스타일 이름을 사용하여 새 단락 추가 (예:
--prop style=Heading1) — 자동으로 적용됩니다
이것이 중요한 이유
Pandoc으로 생성된 문서와 Word로 생성된 문서에는 해당 문서에 고유한 특정 스타일 ID(예: Heading1, BodyText, FirstParagraph)가 있습니다. 같은 이름으로 새 스타일을 추가하면 다음과 같은 문제가 발생합니다:
officecli validate에서 중복 스타일 ID 오류 발생- Word/LibreOffice 렌더링이 기본값으로 대체됨
- 작업 시간이 필요 이상으로 10배 길어짐
템플릿 우선순위
- 사용자 제공 소스 파일 — 최우선 템플릿
tests/fixtures/*.docx— 스킬과 함께 제공되는 사전 빌드된 작동 예제officecli create빈 문서 — 다른 것이 적용되지 않을 때만 사용
# 올바른 방법: Pandoc 스타일 상속
cp Assignment1.docx Assignment2.docx
officecli open Assignment2.docx
officecli remove Assignment2.docx "/body/p[1]" # 기존 본문 제거 (스타일/머리글/바닥글은 유지)
# ... 나머지 단락도 제거 ...
officecli add Assignment2.docx /body --type paragraph --prop text="New title" --prop style=Heading1
officecli close Assignment2.docx
# 잘못된 방법: 이미 존재하는 스타일을 재생성 -- validate 실패
officecli add doc.docx /styles --type style --prop name=Heading1 --prop size=20pt ...에스컬레이션 단계
officecli로 작업을 수행할 수 없을 때, 다음 순서로 에스컬레이션합니다:
| 단계 | 상황 | 도구 |
|---|---|---|
| L1 officecli 고수준 | 일반적인 add/set/remove 작업 | officecli add/set/remove/query/view |
| L2 officecli raw-set | XML 삽입 — PAGE 필드, fldChar, 하이퍼링크 앵커, 사용자 지정 속성 | officecli raw-set FILE PATH --xpath X --action A --xml ... |
| L3 Python 스크립트 | 대량 변경 내용 추적 작업, 주석 추가, 런 병합, 레드라인 검증 | python3 scripts/*.py |
| L4 압축 해제 → XML 편집 → 재압축 | OMML 수식, 사용자 지정 스타일 삽입, 패턴 매칭 편집 | scripts/docx_cli.py open FILE work/ → XML 편집 → scripts/docx_cli.py save work/ OUT.docx |
에스컬레이션 신호
- officecli가 "silently ignored"를 표시하면 → L2 (raw-set)
- OMML/MathML 수식이 필요하면 → L4 (
<m:oMath>XML 삽입) - 변경 내용 추적을 생성해야 하면 (officecli는 수락/거부만 가능) → L3 또는 L4
- 100개 이상의 대상에 대해 대량 찾기/바꾸기 → L3 (
docx_cli.py search/replace) - 사용자 지정 스타일 ID가 있는 Pandoc 생성 문서 → 먼저 참조 기반 편집 수행
- L1+L2 이후에도 작업 실패 → 포기하기 전에 관련
references/*.md읽기
핵심 워크플로우
실행 모델
명령을 한 번에 하나씩 실행하세요. 모든 명령을 쉘 스크립트에 작성하여 한 블록으로 실행하지 마세요. OfficeCLI는 증분식입니다: 모든 add, set, remove가 즉시 파일을 수정하고 출력을 반환합니다.
- 한 번에 하나의 명령을 실행하고 출력을 확인하세요. 다음 단계로 진행하기 전에 종료 코드를 확인합니다.
- 0이 아닌 종료 코드 = 즉시 중지하고 수정하세요. 깨진 상태 위에 계속 빌드하지 마세요.
- 구조적 작업 후에 검증하세요. 스타일, 표, 차트 또는 섹션을 추가한 후, 그 위에 빌드하기 전에
get또는validate를 실행하세요.
읽기 및 분석
officecli view doc.docx text # 전체 텍스트 추출
officecli view doc.docx text --max-lines 200 # 잘린 추출
officecli view doc.docx text --start 1 --end 50 # 범위 추출
officecli view doc.docx outline # 구조: 통계, 제목, 머리글/바닥글
officecli view doc.docx annotated # 런별 스타일/글꼴/크기, 수식은 LaTeX로 표시
officecli view doc.docx stats # 단락 수, 스타일/글꼴 분포요소 검사
officecli get doc.docx / # 문서 루트 (메타데이터, 페이지 설정)
officecli get doc.docx /body --depth 1 # 본문 하위 요소 목록
officecli get doc.docx "/body/p[1]" # 특정 단락
officecli get doc.docx "/body/p[1]/r[1]" # 특정 런
officecli get doc.docx "/body/tbl[1]" --depth 3 # 표 구조
officecli get doc.docx /styles # 스타일 정의
officecli get doc.docx "/styles/Heading1" # 특정 스타일
officecli get doc.docx "/header[1]" # 머리글/바닥글
officecli get doc.docx /numbering # 번호 매기기 정의
officecli get doc.docx "/body/p[1]" --json # 스크립팅용 JSON 출력CSS 유사 쿼리
officecli query doc.docx 'paragraph[style=Heading1]' # 스타일별
officecli query doc.docx 'p:contains("quarterly")' # 텍스트 내용별
officecli query doc.docx 'p:empty' # 빈 단락
officecli query doc.docx 'image:no-alt' # 대체 텍스트 없는 이미지
officecli query doc.docx 'p[align=center] > r[bold=true]' # 복합 셀렉터
officecli query doc.docx 'paragraph[size>=24pt]' # 크기별
officecli query doc.docx 'field[fieldType!=page]' # 유형별 필드머리글 및 바닥글
알려진 CLI 버그:
add --type footer 명령에서 --prop field=page가 조용히 무시됩니다. 바닥글은 정적 텍스트만으로 생성됩니다. 바닥글을 생성한 후 PAGE 필드를 삽입하려면 반드시 raw-set을 사용해야 합니다.# 1단계. 표지 페이지용 빈 바닥글 (differentFirstPage 자동 활성화)
officecli add doc.docx / --type footer --prop type=first --prop text=""
# 2단계. 정적 "Page " 텍스트가 있는 기본 바닥글
officecli add doc.docx / --type footer --prop text="Page " \
--prop type=default --prop align=center --prop size=9pt --prop font=Calibri
# 3단계. raw-set으로 PAGE 필드 삽입
# (첫 페이지 바닥글이 있을 때 footer[2] = 기본 바닥글)
officecli raw-set doc.docx "/footer[2]" \
--xpath "//w:p" \
--action append \
--xml '<w:r ...><w:fldChar w:fldCharType="begin"/></w:r>
<w:r ...><w:instrText xml:space="preserve"> PAGE </w:instrText></w:r>
<w:r ...><w:fldChar w:fldCharType="end"/></w:r>'바닥글 인덱스 규칙: 첫 페이지 바닥글과 기본 바닥글이 모두 추가된 경우, 기본 바닥글은 /footer[2]입니다. 첫 페이지 바닥글이 없으면 기본 바닥글은 /footer[1]입니다. 항상 officecli get doc.docx "/footer[2]"로 확인하세요.
상주 모드 (성능)
항상 open/close를 사용하세요 — 이것이 스마트 기본값입니다. 모든 명령이 반복적인 파일 I/O 없이 이점을 얻습니다.
officecli open doc.docx # 메모리에 한 번 로드 (즉시 반환)
officecli add doc.docx ... # 모든 명령이 메모리에서 실행 -- 빠름
officecli set doc.docx ...
officecli close doc.docx # 디스크에 한 번 기록경고:
officecli open을 백그라운드 쉘 작업으로 실행하지 마세요 (예: run_in_background를 통해). 이 명령은 즉시 반환되고 데몬은 자동으로 백그라운드에서 실행됩니다. 모니터링되는 쉘로 실행하면 좀비 프로세스와 파일 잠금이 발생합니다.배치 모드
단일 open/save 사이클에서 여러 작업을 실행합니다:
cat <<'EOF' | officecli batch doc.docx
[
{"command":"add","parent":"/body","type":"paragraph",
"props":{"text":"Introduction","style":"Heading1"}},
{"command":"add","parent":"/body","type":"paragraph",
"props":{"text":"This report covers Q4 results.","font":"Calibri","size":"11pt"}}
]
EOF배치가 지원하는 명령: add, set, get, query, remove, move, swap, view, raw, raw-set, validate.
하위 스킬 참조
추가 세부 사항은 필요 시 로드되는 동반 파일에 있습니다:
| 하위 스킬 | 사용 시점 |
|---|---|
| officecli-academic-paper | 학술 논문, 인용, 참고 문헌, 논문용 목차 |
| creating.md | 상세 생성 레시피 (처음부터 새 문서 생성) |
| editing.md | 상세 편집 가이드 (기존 문서 수정) |
결정 흐름
문서가 학술 논문인가 (학위 논문, 저널, 학회)?
예 --> officecli-academic-paper/SKILL.md 읽기
아니오 --> 메인 스킬로 계속
사용자가 매칭할 소스 파일을 제공했는가?
예 --> 참조 기반 편집 + editing.md
아니오 --> creating.mdPython OOXML 스크립트
officecli가 한계에 도달하면, 스킬은 다음 Python 스크립트로 대체합니다:
| 스크립트 | 용도 | 명령 |
|---|---|---|
scripts/docx_cli.py | 통합 Python CLI — 압축 해제, 저장, 유효성 검사, 복구, 검색, 목차, 청크, 주석, 변경 내용 수락, 런 병합 | python3 scripts/docx_cli.py {open|save|validate|repair|text|search|...} |
scripts/accept_changes.py | 모든 변경 내용 추적 수락 | python3 scripts/accept_changes.py IN.docx OUT.docx |
scripts/comment.py | 텍스트에 앵커된 W3C 호환 OOXML 주석 추가 | python3 scripts/comment.py IN.docx OUT.docx --text "..." --anchor "..." |
scripts/ooxml/merge_runs.py | 동일한 서식을 가진 인접 런 병합 | python3 scripts/ooxml/merge_runs.py unpacked/ |
scripts/ooxml/redline_diff.py | 원본 대비 변경 내용 추적 정확성 검증 | python3 scripts/ooxml/redline_diff.py unpacked/ original.docx |
scripts/ooxml/simplify_tracked.py | 동일 작성자의 인접 변경 내용 추적 간소화 | python3 scripts/ooxml/simplify_tracked.py unpacked/ |
참조 자료
| 파일 | 읽을 시점 | 내용 |
|---|---|---|
references/cjk-handling.md | 한국어 텍스트 / 동아시아 글꼴 / 줄바꿈 이슈 | rFonts 동아시아 글꼴, lang 태그, 접근성 |
references/tracked-changes.md | 변경 내용 추적 / 주석 / 레드라인 작업 | w:ins, w:del, 주석 XML, 스크립트 사용 예시 |
비즈니스 문서 디자인 원칙
제목 계층 구조
- H1: 문서 제목 (문서당 하나)
- H2: 주요 섹션
- H3: H2 아래의 하위 섹션
- 단계를 건너뛰지 마세요 (H1 → H3은 유효하지 않음). 목차는 올바른 제목 구조에 의존합니다.
# 제목 계층 구조 확인
officecli view report.docx outline색상 팔레트
| 용도 | 허용 색상 | 16진수 예시 |
|---|---|---|
| 제목, 강조 | 네이비 | #003366, #1B2A4A |
| 본문 포인트, 테두리 | 차콜 | #333333, #4A4A4A |
| 하이라이트, 콜아웃 | 포레스트 그린 | #2E5E3F, #1A4731 |
단일 문서에서 무지개색, 밝은 원색, 또는 3개 이상의 강조 색상을 절대 사용하지 마세요.
글꼴 선택
| 문자 체계 | 기본 글꼴 | 대체 글꼴 |
|---|---|---|
| 한국어 | Malgun Gothic | Pretendard |
| 영어 / 라틴 | Calibri | Aptos |
타이포그래피
본문 텍스트: 11-12pt. 제목은 단계적으로 증가: H1 = 최소 18pt (긴 문서의 경우 20pt 권장), H2 = 14pt 볼드, H3 = 12pt 볼드. 본문 텍스트의 줄 간격은 1.15x-1.5x입니다.
콘텐츠-요소 매핑
| 콘텐츠 유형 | 권장 요소 | 이유 |
|---|---|---|
| 순차적 항목 | 글머리 기호 목록 (listStyle=bullet) | 인라인 쉼표보다 스캔이 빠름 |
| 단계별 프로세스 | 번호 매기기 목록 (listStyle=numbered) | 숫자가 순서를 전달함 |
| 비교 데이터 | 헤더 행이 있는 표 | 열로 나란히 비교 가능 |
| 추세 데이터 | 내장 차트 (chartType=line/column) | 시각적 패턴 인식 |
| 핵심 정의 | 내어쓰기 단락 | 용어와 정의를 구분 |
| 법적/계약 조항 | 북마크가 있는 번호 매기기 목록 | 북마크를 통한 상호 참조 |
| 수학적 내용 | 수식 요소 (formula=LaTeX) | 적절한 OMML 렌더링 |
| 인용/참조 | 각주 또는 미주 | 본문 텍스트를 깔끔하게 유지 |
| 인용문 / 콜아웃 | 테두리 + 음영이 있는 단락 | 본문과의 시각적 구분 |
| 다중 섹션 레이아웃 | 열이 있는 섹션 나누기 | 섹션별 열 제어 |
필수 검증
검증을 절대 건너뛰지 마세요. DOCX 생성 또는 편집 후, 아래 두 단계 모두 필수입니다.
# 1단계: 구조적 유효성 검사
officecli validate output.docx
# 2단계: 시각적 PDF 검증
soffice --headless --convert-to pdf --outdir /tmp output.docx
# PDF를 열어 확인: 서식, 표, 이미지, 머리글/바닥글- PDF 검증을 건너뛰면 = 검증되지 않은 출력
validate에서 오류가 보고되면, 파일을 전달하기 전에 수정하세요
QA 체크리스트
문제가 있다고 가정하세요. 여러분의 임무는 그것을 찾는 것입니다.
이슈 감지
officecli view doc.docx issues
officecli view doc.docx issues --type format
officecli view doc.docx issues --type content
officecli view doc.docx issues --type structure콘텐츠 QA
officecli view doc.docx text
officecli view doc.docx outline
officecli query doc.docx 'p:empty'
officecli query doc.docx 'image:no-alt'
# 남은 플레이스홀더 확인
officecli query doc.docx 'p:contains("lorem")'
officecli query doc.docx 'p:contains("placeholder")'전달 전 체크리스트
- 메타데이터 설정 (제목, 작성자)
raw-set으로 바닥글에 PAGE 필드 삽입됨 —officecli get doc.docx "/footer[2]" --depth 3으로 확인- 문서에 표지 페이지가 있으면 첫 페이지 바닥글 추가됨
- 표지 페이지 내용이 페이지의 최소 60% 이상 채워짐
- 문서에 3개 이상의 제목이 있으면 목차 포함
- 마지막 페이지 내용이 페이지의 최소 40% 이상 채워짐
- 제목 계층 구조가 올바름 (건너뛴 단계 없음)
- 간격용으로 빈 단락을 사용하지 않음
- 모든 이미지에 대체 텍스트 있음
- 표에 헤더 행 있음
officecli validate로 문서 유효성 검사 통과- 남은 플레이스홀더 텍스트 없음
검증 루프
- 문서 생성
view issues+view outline+view text+validate실행- 발견된 이슈 목록 작성 (없으면 더 비판적으로 다시 확인)
- 이슈 수정
- 재검증 — 하나의 수정이 다른 문제를 만드는 경우가 많음
- 전체 패스에서 새로운 이슈가 발견되지 않을 때까지 반복
최소 한 번의 수정-검증 사이클을 완료할 때까지 성공을 선언하지 마세요.
일반적인 함정
| 함정 | 올바른 접근법 |
|---|---|
--name "foo" | --prop name="foo"를 사용 — 모든 속성은 --prop을 통해 전달 |
| 속성 이름 추측 | 정확한 이름을 확인하려면 officecli help docx set paragraph --json 실행 |
쉘 문자열의 \n | --prop text="line1\\nline2"에서 줄바꿈은 \\n 사용 |
#이 있는 16진수 색상 | #FF0000이 아닌 FF0000 사용 — 해시 접두사 없음 |
| 경로는 1부터 시작 | /body/p[1], /body/tbl[1] — XPath 규약 |
--index는 0부터 시작 | --index 0 = 첫 번째 위치 — 배열 규약 |
zsh/bash에서 따옴표 없는 [N] | 쉘이 /body/p[1]을 글로브 확장함 — 항상 경로를 따옴표로 감싸기: "/body/p[1]" |
| 빈 단락으로 간격 조절 | 단락의 spaceBefore/spaceAfter 속성 사용 |
--prop text=의 $ | 작은따옴표 사용: --prop text='$50M' |
바닥글의 --prop field=page | 조용히 무시됨. <w:fldChar>를 삽입하려면 raw-set을 사용해야 함 |
| 템플릿의 스타일 재생성 | 먼저 cp source.docx target.docx — 기존 ID로 스타일을 추가하지 마세요 |
officecli open을 백그라운드 쉘로 실행 | 포그라운드에서 실행 — open은 즉시 반환되고, 데몬은 자동으로 백그라운드에서 실행 |
| 배치 JSON 파싱 오류 | heredoc 사용: cat <<'EOF' | officecli batch FILE.docx |
| OMML 수식 생성 | officecli는 OMML을 생성할 수 없음 — L4로 에스컬레이션 |
listStyle을 런에 적용 | listStyle은 단락 속성이며, 런 속성이 아님 |
| 행 수준의 볼드/색상/음영 | 행의 set은 height, header, c1/c2/c3 텍스트 단축키만 지원 — 셀 수준의 set 사용 |
| 섹션 vs 루트 속성 이름 | 섹션은 pagewidth/pageheight (소문자) 사용. 문서 루트는 pageWidth/pageHeight (카멜케이스) 사용 |
| 잘못된 테두리 형식 | style;size;color;space 형식 사용: single;4;FF0000;1 |
| 공백으로 코드 블록 들여쓰기 | ind.left 단락 속성 사용 (예: --prop ind.left=720) |
LibreOffice에서 chartType=pie/doughnut | PDF에서 슬라이스가 보이지 않음 — 대신 column 또는 bar 사용 |
알려진 이슈
| 이슈 | 해결 방법 |
|---|---|
| 시각적 미리보기 없음 | pptx (SVG/HTML)와 달리, docx에는 내장 렌더링이 없습니다. 검증에는 view text/outline/annotated/issues를 사용하세요. 시각적 확인은 Word에서 열어 수행하세요. |
| 변경 내용 추적 생성에 원시 XML 필요 | OfficeCLI는 수락/거부만 가능하고 변경 내용 추적을 생성할 수 없습니다. raw-set 또는 Python 스크립트 (L3)를 사용하세요. |
| 탭 정지에 원시 XML이 필요할 수 있음 | 탭 정지 생성은 고수준 명령에 노출되지 않습니다. raw-set을 사용하세요. |
| 생성 후 차트 시리즈 추가 불가 | set --prop data=는 기존 시리즈만 업데이트할 수 있습니다. 차트를 삭제하고 다시 생성하세요. |
| 복잡한 번호 매기기 정의 | listStyle=bullet/numbered는 간단한 경우를 다룹니다. 다단계 목록의 경우 numId/numLevel을 사용하세요. |
| 배치 간헐적 실패 | 약 15번 중 1번의 배치 작업이 실패할 수 있습니다. 재시도하거나 파일을 close/reopen하세요. 대량 배치는 10-15개 청크로 분할하세요. |
| 테이블 수준 패딩이 유효하지 않은 XML 생성 | set tbl[N] --prop padding=N을 사용하지 마세요. 셀 수준의 padding.top/padding.bottom을 사용하세요. |
| 내부 하이퍼링크 미지원 | hyperlink는 절대 URI만 허용합니다. <w:hyperlink w:anchor="...">와 함께 raw-set을 사용하세요. |
테이블 --index 위치 지정 불안정 | add /body --type table의 --index N이 무시될 수 있습니다. 원하는 순서대로 콘텐츠를 추가하세요. |
view text에서 모든 번호 매기기 항목이 "1."으로 표시 | 표시 전용 제한 사항입니다. Word/LibreOffice의 렌더링 결과에서는 올바른 번호가 표시됩니다. |
안티 패턴 (반드시 피해야 할 것)
- 플레이스홀더 데이터: 출력에 "Acme Corp", "Alice Chen", "Lorem ipsum"을 절대 남기지 마세요. 사용자가 데이터를 제공하지 않았다면 물어보세요.
- 바닥글 PAGE 필드:
raw-set으로 페이지 번호를 설정할 때, XML 구조가 정확해야 합니다 (fldChar/instrText/fldChar 순서). - 간격용 빈 단락:
spacing-after속성을 사용하세요. - 수동 글머리 기호 문자 (-, *):
listStyle=bullet또는listStyle=number를 사용하세요. - 수동 글꼴 XML 삽입: 충분한 경우
--prop font=...을 사용하세요. - 참조 자료 무시: 복잡한 작업이 officecli로 실패하면, 포기하기 전에
references/*.md를 읽고scripts/*.py를 확인하세요. - 기존 스타일 재생성: 사용자가 소스 파일을 제공하면, 복사하고 수정하세요 — 스타일을 처음부터 다시 만들지 마세요.
도구 검색
추측하기 전에 항상 도움말에서 구문을 확인하세요:
officecli --help
officecli help docx
officecli help docx add
officecli help docx set
officecli help docx query
officecli help docx add paragraph --json
officecli help docx set run --json의존성
| 도구 | 용도 | 상태 |
|---|---|---|
officecli (PATH) | 주요 DOCX CLI — 글로벌 설치에 CJK 포크 포함 | 필수 |
dotnet | officecli의 런타임/빌드 | 포크 빌드 시 필수 |
python3 | 대체 스크립트 (scripts/*.py) | L3/L4 시 필수 |
lxml | scripts/ooxml/*용 Python XML 처리 | L3/L4 시 필수 |
soffice | PDF 변환 / .doc 마이그레이션 / 매크로 워크플로우 | 선택적 대체 |
pdftoppm | PDF 렌더링 후 이미지 기반 QA | 선택적 대체 |
사전 요구 사항 확인
# 필수
python3 -c "import docx, lxml" || echo "MISSING: pip install python-docx lxml"
# 필요 시: LibreOffice
which soffice >/dev/null 2>&1 || echo "INFO: LibreOffice not installed"
# 필요 시: OfficeCLI
which officecli >/dev/null 2>&1 || echo "INFO: OfficeCLI not installed"