TL;DR

OfficeCLI는 AI 에이전트가 Word·Excel·PowerPoint 파일을 단일 바이너리로 생성·읽기·수정하고 고충실 HTML/PNG 렌더링을 통해 시각적 검증을 가능하게 하는 오픈소스 CLI 도구이다. 내부에 Excel 수식 엔진과 OOXML 기반 피벗 생성 로직을 포함해 350개 이상의 함수 평가와 네이티브 피벗 캐시 작성을 지원하며 경로 기반 접근과 --json 출력으로 에이전트 자동화의 신뢰성을 높인다. 템플릿 병합과 덤프→배치 재생으로 대량 문서 생산을 결정적으로 단순화하고 상주 모드로 연속 명령의 지연을 줄여 CI·컨테이너 환경에서 무설치 실행을 가능하게 한다. 빌드 시에는 .NET 10 SDK가 필요하지만 런타임은 바이너리에 내장되어 배포 환경에서 추가 런타임 의존성이 없다. 사용자는 curl 설치, Homebrew 또는 npm 배포 중 선택해 설치한 뒤 create/watch/add/merge 명령으로 바로 자동화 파이프라인을 구성할 수 있다.

주요 기능

• 문서를 브라우저 기반 HTML·PNG로 고충실 렌더링하고 페이지 단위 스크린샷을 제공하여 에이전트가 시각적 레이아웃을 확인하고 레이아웃 문제를 식별할 수 있도록 했다. 이 렌더링 엔진은 도형, 차트, 수식, 3D 모델, 모프 전환 등을 지원하며 헤드리스 환경에서 페이지 PNG 생성이 가능하다. 이러한 시각화는 에이전트 워크플로에서 render→look→fix 루프를 실현하는 핵심 요소이다.
• Excel 수식과 피벗을 바이너리 내부에서 평가하는 350개 이상의 함수와 네이티브 OOXML 피벗 테이블 생성 기능을 제공하여 계산 결과를 외부 Office 재실행 없이 즉시 확인할 수 있게 했다. 동적 배열과 금융·통계 함수군을 포함한 자동 평가를 지원하므로 에이전트가 셀 값을 바로 읽어 후속 처리에 활용할 수 있다. 피벗 캐시와 정의는 OOXML에 기록되어 Microsoft Excel에서 파일을 열었을 때 집계가 유지된다.
• 템플릿 병합과 덤프/배치 재생 기능을 통해 한 번 설계된 레이아웃을 JSON 데이터로 대량 채우고 기존 문서를 구조화된 배치 명세로 직렬화해 재생할 수 있도록 했다. 이 기능은 에이전트가 매번 전체 문서를 재생성하지 않고 deterministic하게 다수의 문서를 생산하게 한다. 결과적으로 토큰 소모와 레이아웃 불일치 위험을 줄인다.
• 경로 기반 요소 주소 지정과 일관된 --json 출력 스키마를 제공하여 에이전트가 XML 네임스페이스를 이해하지 않아도 안정적으로 요소를 탐색하고 수정할 수 있게 했다. 모든 명령은 JSON 출력과 구조화된 오류 객체를 반환하여 에이전트가 오류 코드와 제안을 기반으로 자체 복구할 수 있다. 이 접근은 에이전트 자동화에서 파싱 실패를 줄이고 신뢰성을 높였다.
• 단일 바이너리로 배포되고 런타임 종속성을 포함해 어떤 플랫폼에서든 동작하도록 설계되어 별도 Office 설치나 추가 라이브러리 없이도 헤드리스·컨테이너 환경에서 동작한다. 홈브류·npm·직접 다운로드의 다양한 설치 채널을 제공하며 자동 업데이트와 구성 파일을 통해 운영 편의성을 보장한다. 빌드 시에는 .NET 10 SDK가 필요하지만 런타임은 바이너리에 내장되어 있다.

어떻게 동작하는가

OfficeCLI는 세 계층(L1: 읽기, L2: DOM 조작, L3: Raw XML) 아키텍처를 통해 점진적으로 복잡도를 올리며 문서에 접근한다. 내장 HTML 렌더링 엔진은 OOXML 파트를 해석해 브라우저용 HTML과 PNG 스냅샷을 생성하고 headless 브라우저 파이프라인을 통해 페이지 이미지를 산출한다. Excel 계산 엔진과 피벗 생성 로직이 바이너리 내부에서 수식 평가와 피벗 캐시 생성을 수행해 외부 Office에 의존하지 않고 즉시 계산 결과를 제공한다.

해결 문제

기존에는 에이전트가 문서를 텍스트·DOM 수준으로만 해석해 레이아웃 오류나 오버플로를 파악하기 어려웠으며 Microsoft Office 설치가 필요해 자동화나 CI에서 제약이 있었다. OfficeCLI는 고충실 렌더링과 페이지 스크린샷을 통해 에이전트가 시각적으로 결과를 검증하고 바로 수정할 수 있게 하며 단일 바이너리로 Office 없이도 동일한 작업을 수행하도록 했다. 또한 경로 기반 주소 지정과 일관된 JSON 출력을 제공해 에이전트의 문서 조작 신뢰도를 높였다.

지금 주목받는 이유

OfficeCLI는 에이전트 친화적 기능 군(내장 렌더링, 바이너리 내부 수식 평가, 경로 기반 JSON API)과 단일 바이너리 배포 모델로 에이전트 자동화의 실무적 제약을 직접 해소한다. README가 강조하듯 에이전트가 시각적으로 결과를 확인할 수 있는 render→look→fix 루프를 헤드리스 환경까지 확장한 점이 주목을 받고 있다. 또한 자동 스킬 설치와 MCP 서버 통합으로 다수의 AI 툴에 빠르게 연결할 수 있어 통합 비용과 초기 진입 장벽을 낮췄다.

차별점

• 내장 고충실 HTML 렌더링 엔진을 포함해 도형·차트·수식·3D 모델·모프 전환을 브라우저 친화적 출력(HTML/PNG)으로 생성함으로써 에이전트가 시각적 문제를 직접 확인하고 수정할 수 있게 했다. 이 렌더링은 헤드리스 환경과 CI에서 작동하도록 설계되어 추가 GUI나 Office 설치가 필요 없다. 결과적으로 에이전트 기반 슬라이드 생성의 검증 피드백 루프가 실무에서 실현 가능하다.
• Excel 수식과 피벗을 바이너리 내부에서 직접 평가해 파일을 쓰지 않고도 셀 값을 즉시 획득하게 함으로써 Office 재실행이나 외부 계산 엔진에 의존하지 않게 했다. 피벗은 OOXML에 캐시와 정의를 저장하므로 Microsoft Excel에서 파일을 열었을 때도 동일한 집계가 유지된다. 이로 인해 에이전트가 계산된 결과를 기반으로 후속 작업을 안정적으로 수행할 수 있다.
• 템플릿 병합(`{{key}}`)과 덤프→배치 재생 워크플로를 결합해 한 번 만든 레이아웃을 데이터로 대량 생산하도록 설계되어 에이전트가 매번 레이아웃을 재생성하는 실패 모드를 피하도록 했다. 덤프로 문서 하위트리를 JSON으로 직렬화하고 batch로 재생하면 인간이 만든 샘플을 구조화된 스펙으로 학습 가능한 입력으로 전환할 수 있다. 이 패턴은 대규모 보고서 생산과 CI 파이프라인 통합에 유리하다.
• 단일 바이너리·무설치·무종속성 배포로 다양한 플랫폼과 컨테이너 환경에서 동일한 동작을 보장하며 자동 설치 스킬과 MCP 통합으로 여러 에이전트에 무중단 배포가 가능하다. 설치 옵션으로 curl 스크립트, Homebrew, npm 배포를 제공해 배포 편의성을 높였다. 이로 인해 에이전트 생태계와의 통합 비용이 낮아진다.

사용 사례

• 데이터베이스나 API에서 보고서를 자동으로 생성해 PowerPoint·Word 문서를 일괄 생산하고 템플릿 병합으로 여러 고객용 문서를 일관되게 채우는 용도로 활용할 수 있다. 이 흐름은 템플릿 설계 후 JSON 데이터로 대량 생성하는 파이프라인에 적합하다. 에이전트가 생성 결과를 즉시 렌더링으로 확인하고 레이아웃 문제를 자동으로 수정할 수 있다.
• AI 에이전트가 사용자 프롬프트로부터 프레젠테이션을 생성하고 라이브 프리뷰와 스크린샷을 통해 시각적 정합성을 검증하는 워크플로에 적합하다. 에이전트는 path-based 접근과 --json 응답을 이용해 슬라이드 요소를 점진적으로 구성하고 validate·view issues로 자율 복구를 수행할 수 있다.
• CI/CD 파이프라인에서 문서 품질 검증과 일괄 수정 작업을 자동화하는 데 사용될 수 있다. 예컨대 테스트 리포트로부터 PowerPoint를 생성하고 view issues/validate로 품질 검사를 수행한 뒤 batch 명령으로 스타일 교정이나 텍스트 교체를 자동 실행할 수 있다.
• 팀 단위 템플릿 복제와 표준화 작업에서 템플릿 병합과 dump→batch 재생을 결합해 규격화된 문서 산출물을 대량으로 생성하고 버전 관리 파이프라인에 통합할 수 있다. 이 방식은 사람에 의한 수동 편집을 줄이고 문서 일관성을 확보한다.

시작하기

설치는 curl 스크립트를 통해 한 줄로 수행하거나 Homebrew·npm 등으로 플랫폼별 바이너리를 설치할 수 있다. 설치 후 `officecli install` 또는 단순 `officecli` 실행으로 바이너리와 스킬이 자동으로 프로비저닝되며 `officecli create deck.pptx`와 `officecli watch deck.pptx`로 즉시 라이브 프리뷰와 편집 플로우를 확인할 수 있다. 개발자용 예시는 README의 빠른 시작 블록을 복사해 터미널에서 실행하면 30초 내에 동작을 확인할 수 있다.

요구사항

• .NET 10 SDK는 소스에서 빌드할 때만 필요하며 빌드 후 생성된 네이티브 바이너리는 런타임에 .NET을 포함하므로 배포 환경에서는 별도 런타임이 필요 없다. README에는 빌드를 위한 최소 요구로 .NET 10 SDK를 명시하고 있다.
• 실행 환경은 macOS Apple Silicon/Intel, Linux x64/ARM64, Windows x64/ARM64용 네이티브 바이너리를 제공하므로 해당 플랫폼에 맞는 바이너리를 선택해야 한다. 컨테이너·헤드리스 환경에서 작동하도록 설계되어 추가 GUI나 Office 설치가 필요하지 않다.

이미지 분석