TL;DR

OfficeCLI là CLI tool mã nguồn mở (Apache 2.0), single binary, được xây dựng riêng cho AI agent để đọc, tạo và chỉnh sửa file Word, Excel, PowerPoint mà không cần cài Microsoft Office. Điểm đặc biệt: tích hợp rendering engine giúp agent "nhìn thấy" output sau mỗi thao tác, đóng vòng lặp render - xem - fix mà trước đây hầu hết pipeline không giải quyết được. v1.0.132, 11.9k stars, Apache 2.0.

Vấn đề AI agent gặp khi làm việc với file Office

Viết code, agent làm được. Gọi API, không vấn đề. Nhưng khi task là "cập nhật bảng Excel trong báo cáo tuần" hay "sửa slide deck trước khi gửi khách hàng" - đây là nơi hầu hết pipeline thất bại.

Không phải vì agent không thể viết nội dung. Mà vì:

  • Agent mù với layout. Agent có thể thêm text vào slide, nhưng không biết title có bị tràn sang dòng tiếp theo không. Có thể tạo bảng Excel, nhưng không chắc file mở lên có đúng format không.
  • Tool hiện tại thiếu sót. python-docx và openpyxl chỉ là Python library, không có rendering, không có path-based addressing. LibreOffice headless phải cài đầy đủ và dùng UNO API phức tạp, không thiết kế cho AI. Kết quả: team phải duct-tape nhiều library với nhau và vẫn gặp sharp edges ở charts, images, pivot tables.
  • Không có feedback loop. Agent chỉnh sửa file xong không biết kết quả trông như thế nào cho đến khi người dùng mở lên và phát hiện lỗi.

OfficeCLI giải quyết bằng cách nào

OfficeCLI không chỉ là một library khác. Tool này tiếp cận theo hướng agent-native từ đầu.

Rendering engine là điểm cốt lõi. Tool tích hợp engine render từ scratch, xuất ra HTML hoặc PNG. Mỗi lần agent chỉnh sửa xong, có thể gọi officecli view screenshot document.pptx và nhận PNG để kiểm tra layout. Vòng lặp render - xem - fix hoạt động trong CI, trong Docker, trên server không có display - ở bất kỳ đâu binary chạy được.

OfficeCLI three-layer architecture: L1 View, L2 DOM, L3 Raw XML với render loop
Three-layer architecture (L1/L2/L3) và vòng lặp render - xem - fix của OfficeCLI

Three-layer architecture giúp agent escalate complexity khi cần:

  • L1 (View): đọc semantic - text, outline, HTML, screenshot
  • L2 (DOM): thao tác element cụ thể - get/set/add/remove từng paragraph, cell, shape
  • L3 (Raw XML): XPath fallback khi cần truy cập những gì L2 chưa hỗ trợ

Path-based addressing cho phép agent navigate document mà không cần hiểu XML namespaces. /slide[1]/shape[2] là address stable của shape thứ 2 trong slide đầu. Agent dùng selector CSS-like: row[Salary>5000 and Region=EMEA] để query Excel data.

Single binary với .NET runtime nhúng sẵn - không cần Microsoft Office hay bất kỳ dependency nào. Download, chạy, xong. Hỗ trợ macOS (Intel + Apple Silicon), Linux (x64 + ARM64), Windows (x64 + ARM64).

Các tính năng chính

Excel formula engine là điểm đáng chú ý nhất: 350+ Excel functions tự tính ngay khi write. Viết =SUM(A1:A2), đọc cell, giá trị đã có sẵn mà không cần round-trip qua Office để recalculate. Bao gồm dynamic arrays (FILTER, SORT, UNIQUE, SEQUENCE), XLOOKUP, tài chính (XIRR, PRICE, YIELD), thống kê (NORM.DIST, T.TEST, LINEST). Native OOXML pivot tables với 10 aggregation types từ 1 command.

Template merge: thiết kế layout 1 lần, fill {{key}} placeholders N lần bằng JSON data - qua paragraphs, table cells, shapes, headers, footers. Agent không cần tốn token regenerate toàn bộ document mỗi lần.

Round-trip dump: serialize bất kỳ file .docx/.pptx/.xlsx nào thành replayable batch JSON. Agent học từ document mẫu của người dùng bằng cách đọc structured spec thay vì parse raw OOXML XML.

Resident mode: giữ document trong memory qua named pipes, không phải reopen file mỗi lần thao tác. Auto-start với 60s idle timeout, auto-flush sau 2-10s khi idle. Batch mode cho phép apply nhiều thao tác trong 1 pass.

MCP server tích hợp: register bằng 1 command, expose toàn bộ document operations qua JSON-RPC - không cần shell access.

Auto-install: tự detect Claude Code, Cursor, GitHub Copilot và inject skill file. Không cần cấu hình thủ công.

So sánh với các giải pháp khác

OfficeCLIpython-docx/openpyxlLibreOfficeM365 Copilot
Mã nguồn mở & miễn phí✓ (Apache 2.0)✓✓✗
AI-native CLI + JSON✓✗✗✗
Zero install (single binary)✓✗ (Python + pip)✗ (full install)✗
Rendering engine✓✗Partial✗
Word + Excel + PowerPoint✓Tách biệt✓✓
Headless CI/Docker✓✓Partial✗

Python library phù hợp cho use case đơn giản và team chấp nhận không có visual feedback loop. LibreOffice headless vẫn là lựa chọn khi cần độ tương thích cao với format cũ. M365 Copilot phục vụ end-user làm việc trong GUI - khác hẳn với automation pipeline.

Hạn chế cần biết trước khi dùng

Trước khi đưa vào pipeline production, có một số điểm cần test kỹ:

Chưa có benchmark độc lập. Repo self-claim rằng rendering engine đạt "high fidelity" nhưng chưa có test bên thứ ba trên file phức tạp thực tế - file nhiều chart, template, font, tiếng Việt, macro. Nên test với bộ file thật của team trước.

Resident mode cần flush đúng lúc. Khi document đang trong resident mode, disk write bị defer. Trước khi file được đọc bởi tool khác (python-docx, Word, upload script) - phải flush trước bằng lệnh save hoặc close. Bỏ qua bước này, tool kia sẽ đọc version cũ.

Một số v1 limitations: Excel watch mode không emit data-path (v2 candidate). PowerPoint group shapes chỉ select as whole, không drill vào child. Word textbox/shape add-mostly - get trả raw XML, không structured readback.

Shell escaping: Path có brackets phải quote ("/slide[1]"), $ trong text phải single-quote. Nhỏ nhưng hay gây bug trong automation script.

iOfficeAI chưa rõ team. Không có thông tin về team đằng sau project và sustainability plan. Đây là yếu tố cần cân nhắc khi phụ thuộc vào tool trong pipeline dài hạn.

Ai nên thử ngay

OfficeCLI phù hợp khi pipeline của bạn có một hoặc nhiều trong các case sau:

  • Báo cáo định kỳ từ data: weekly report, KPI dashboard, financial summary được generate từ database/API thay vì viết tay
  • Proposal/deck sales: agent tạo proposal từ metadata sản phẩm, changelog, pricing - thay vì người tự làm mỗi lần
  • Validate trước khi giao khách hàng: kiểm tra text overflow, formula error, heading thiếu, placeholder chưa fill
  • Template variation: thiết kế layout 1 lần, generate 50-100 phiên bản với data khác nhau qua template merge

Nếu team đang dùng python-docx + openpyxl + headless LibreOffice và gặp sharp edges ở charts, pivot, images - OfficeCLI là alternative đáng test.

Kết

OfficeCLI không hào nhoáng. Không phải chatbot, không phải AI assistant. Là CLI tool chuyên biệt giải quyết đúng một vấn đề: cho AI agent bề mặt thao tác có cấu trúc với file Office.

Điểm mấu chốt là rendering engine. Không có nó, agent chỉnh sửa file xong vẫn bay mù - về kỹ thuật file hợp lệ nhưng về mặt visual có thể hoàn toàn sai. Có nó, agent có thể sửa - nhìn - sửa lại theo vòng lặp giống cách người làm thực tế.

Caveat quan trọng: chưa có benchmark độc lập. Đừng đưa vào production pipeline chỉ vì demo clean. Test với file thật của team - đặc biệt file có chart, template phức tạp, font tiếng Việt - trước khi quyết định.

Nếu chạy ổn, đây là mảnh ghép quan trọng cho AI agent làm việc văn phòng tử tế hơn - thứ mà hiện tại hầu hết pipeline đang thiếu.

via iOfficeAI/OfficeCLI