docx-cli: AI 에이전트가 고품질로 Word 문서를 편집하도록 지원

docx-cli: AI 에이전트가 고품질로 Word 문서를 편집하도록 지원

docx-cli는 AI 에이전트와 Word 문서 간의 상호작용을 최적화합니다

docx-cli는 AI 에이전트(예: Claude와 Codex)가 .docx 파일을 읽고, 편집하고, 주석을 달 수 있도록 설계된 특수 CLI이며, 전체 형식 충실도를 유지합니다. 에이전트가 기본 OOXML(Office Open XML)을 직접 수정하려고 시도하는 전통적인 방법과 달리—이는 종종 파일 손상 및 높은 토큰 소비를 초래합니다—docx-cli는 에이전트에게 간단한 명령과 주석이 달린 Markdown 읽기 뷰를 제공합니다. 이 접근 방식은 사용자 정의 스타일, 테마 색상 및 삽입된 객체가 편집 과정에서 그대로 유지되도록 보장합니다.

성능 벤치마크: docx-cli vs. 기본 에이전트 스킬

여섯 개의 실제 문서 작업(예: NDA 작성, 계약서 빨간줄 표시, 저널 작성)을 포함한 통제된 A/B 베이크오프에서 docx-cli는 두 모델 티어 전반에 걸쳐 기본 에이전트 스킬을 크게 앞섰습니다:

  • 성공률: "약한" Haiku 티어에서는 docx-cli가 4.3/6 작업을 해결한 반면 기본 스킬은 0.7/6에 그쳤습니다. "강한" Sonnet 티어에서는 완벽한 6/6을 달성했으며, 기본 스킬은 4/6에 머물렀습니다.
  • 토큰 효율성: docx-cli는 입력 토큰을 약 2.2·2.6· 감소시켜 비용을 낮추고 속도를 높였습니다.
  • 지연 시간: 전체 실행 시간은 두 티어 모두에서 1.7·2.0· 감소했습니다.
  • 신뢰성: docx-cli 출력물 100%가 첫 시도에 Microsoft Word에서 열렸으며, 기본 스킬은 Word에서 열 수 없는 파일을 여러 개 생성했습니다.

핵심 기술 아키텍처

제자리 XML 변형

손실이 있는 모델에서 문서를 다시 내보내는 대신, docx-cli는 AST(추상 구문 트리)를 파싱된 XML 트리에 대한 뷰로 취급합니다. 에이전트가 edit 또는 comments add 명령을 실행하면 CLI는 기본 XML 노드를 직접 변형하고 변경 사항을 파일에 다시 직렬화합니다. 이를 통해 AST에 명시적으로 모델링되지 않은 요소(예: 독점 스키마 확장이나 복잡한 테마 색상)가 손상되지 않고 그대로 유지됩니다.

안정적인 로케이터와 주소 지정

원시 텍스트 오프셋의 취약성을 피하기 위해 docx-cli는 문서 요소를 정확히 지정하는 로케이터 시스템을 사용합니다:

  • 블록 ID: pN(단락), tN(표), sN(섹션 구분)은 문서 순서에서 파생됩니다.
  • 엔터티 ID: cN(주석), imgN(이미지), linkN(하이퍼링크), fnN(각주), enN(미주)는 list 동사를 통해 표시됩니다.
  • 스팬: 문자 오프셋은 0부터 시작하며, 시작은 포함, 끝은 제외합니다(예: p3:5-20은 단락 3의 문자 5~19를 대상으로 함).

풍부한 콘텐츠 처리

docx-cli는 복잡한 Word 요소를 다루기 위해 여러 고급 기능을 구현합니다:

  • 수식: 맞춤형 MathML–OMML 어댑터를 사용해 OOXML <m:oMath>를 LaTeX로 라운드트립합니다.
  • 변경 추적: 빨간줄 표시를 위해 기본 <w:ins> 및 <w:del> 태그를 사용합니다. CLI는 세 가지 읽기 뷰를 지원합니다: --accepted(정리된 텍스트), --current(각주가 포함된 CriticMarkup), --baseline(변경 전 텍스트).
  • 이미지: 경로, data: URI 또는 HTTP(S) URL에서 삽입을 지원하며, 자동 HEIC–JPEG 변환을 수행합니다.
  • 스타일: styles.xml의 스타일 정의를 편집할 수 있어 문서 본문 내 모든 인스턴스를 개별 수정 없이 전역 변경이 가능합니다(예: "모든 Heading 1을 초록색으로 만들기").

명령 및 워크플로우 참고

읽기 및 질의

에이전트는 docx read를 사용해 문서의 Markdown 표현을 얻으며, HTML 주석(<!-- docx:p pN style="Caption" -->)을 통해 스타일, 정렬, 간격 등에 대한 구조적 힌트를 제공합니다.

변형

변형 명령은 파일을 제자리에서 수정합니다. 주요 명령은 다음과 같습니다:

  • docx replace: 서식(run) 보존하면서 패턴을 교체합니다.
  • docx edit: 특정 로케이터에서 콘텐츠를 수정하며, 일반 텍스트, Markdown 또는 원시 run을 지원합니다.
  • docx insert: 로케이터 앞이나 뒤에 콘텐츠를 추가합니다.
  • docx comments add: 특정 스팬이나 구문에 주석을 붙입니다.

시각적 검증

docx render는 에이전트가 Microsoft Word(osascript 또는 PowerShell COM 사용) 또는 LibreOffice를 구동해 PDF를 생성하고, 이를 번들된 PDFium WASM 패키지를 이용해 PNG 또는 JPG 이미지로 래스터화함으로써 작업을 검증할 수 있게 합니다.

설치 및 에이전트 통합

docx-cli는 Claude Code, Codex, Pi와 호환되는 Agent Skill로 배포됩니다. npx skills add kklimuk/docx-cli 명령으로 설치하거나 Linux, macOS, Windows용 독립 실행 파일로 설치할 수 있습니다. Claude Code 전용으로는 /plugin marketplace add kklimuk/docx-cli 명령을 사용할 수 있습니다.

요약:

docx-cli는 AI 에이전트가 안정적인 로케이터와 제자리 XML 변형을 사용해 .docx 파일을 읽고, 편집하고, 주석을 달 수 있게 해 주는 명령줄 인터페이스이며, 형식 보존과 토큰 사용량 감소를 실현합니다.

제목:

docx-cli: AI 에이전트가 고품질로 Word 문서를 편집하도록 지원

Sources