docx-cli: AIエージェントによる高精度なWordドキュメント編集の実現

docx-cli: AIエージェントによる高精度なWordドキュメント編集の実現

docx-cli は AIエージェントとWordドキュメントの相互作用を最適化します

docx-cli は、書式を完全に維持しながら .docx ファイルを読み取り、編集し、コメントを追加するために設計された、AIエージェント（Claude や Codex など）向けの特化型 CLI です。エージェントが基盤となる OOXML (Office Open XML) を直接変更しようとして、ファイルが破損したりトークン消費量が増大したりする従来の方法とは異なり、docx-cli はエージェントにプレーンなコマンドと注釈付き Markdown ビューを提供します。このアプローチにより、カスタムスタイル、テーマカラー、埋め込みオブジェクトが編集プロセスを経由しても維持されます。

パフォーマンス・ベンチマーク: docx-cli vs. デフォルトのエージェント機能

NDA の記入、契約書の修正（redlining）、ジャーナルの執筆など、6 つの実世界のドキュメント・タスクを含む制御された A/B テストにおいて、docx-cli は 2 つのモデル層にわたってデフォルトのエージェント機能を有意に上回りました。

  • 成功率: 「弱い」Haiku 層では、デフォルト機能が 0.7/6 タスクを解決したのに対し、docx-cli は 4.3/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 (Abstract Syntax Tree) を解析済み XML ツリーのビューとして扱います。エージェントが edit または comments add コマンドを実行すると、CLI は基盤となる XML ノードを直接変異させ、変更をファイルにシリアル化して書き戻します。これにより、AST に明示的にモデル化されていない要素（独自のスキーマ拡張や複雑なテーマカラーなど）が、そのままの状態で維持されます。

安定したロケーターとアドレッシング

生のテキスト・オフセットの脆弱性を避けるため、docx-cli はドキュメント要素を正確に指定するためのロケーター・システムを使用します。

  • ブロック ID: pN (paragraph), tN (table), および sN (section break) はドキュメントの順序から導出されます。
  • エンティティ ID: cN (comment), imgN (image), linkN (hyperlink), fnN (footnote), および enN (endnote) は list 動詞を通じて公開されます。
  • スパン: 文字オフセットは 0 ベースで、開始位置を含み、終了位置を含みません（例: p3:5-20 は paragraph 3 の 5 文字目から 19 文字目を対象とします）。

リッチ・コンテンツの処理

docx-cli は、複雑な Word 要素を扱うためにいくつかの高度な機能を実装しています。

  • 数式: カスタムの MathML–OMML アダプターを使用して、OOXML <m:oMath> を LaTeX に変換します。
  • 変更履歴 (Tracked Changes): 修正（redlining）のために、ネイティブな <w:ins> および <w:del> タグが使用されます。CLI は 3 つの表示モードを提供します: --accepted (クリーンなテキスト), --current (脚注付きの CriticMarkup), --baseline (変更前のテキスト)。
  • 画像: パス、data: URI、または HTTP(S) URL からの挿入をサポートし、自動的な HEIC–JPEG トランスコーディングを行います。
  • スタイル: styles.xml 内のスタイル定義の編集を許可し、ドキュメント本体のすべてのインスタンスを修正することなく、グローバルな変更（例: 「すべての Heading 1 を緑色にする」）を可能にします。

コマンドとワークフローの参照

読み取りとクエリ

エージェントは docx read を使用してドキュメントの Markdown 表記を取得し、スタイル、配置、間隔に関する構造的なヒントを提供する HTML コメント注釈（例: <!-- docx:p pN style="Caption" -->）が補完されます。

変異 (Mutation)

変異器はファイルをインプレースで変更します。主なコマンドは以下の通りです:

  • docx replace: 実行（run）の書式を維持しながらパターンを置換します。
  • docx edit: 特定のロケーターでコンテンツを修正します。プレーンテキスト、Markdown、または生の run をサポートします。
  • docx insert: ロケーターの前または後にコンテンツを追加します。
  • docx comments add: 特定のスパンまたはフレーズにコメントを付加します。

視覚的検証

docx render を使用すると、エージェントは Microsoft Word (via osascript または PowerShell COM) または LibreOffice を操作して PDF を生成し、それを同梱の PDFium WASM パッケージを使用して PNG または JPG 画像にラスタライズすることで、作業内容を検証できます。

インストールとエージェントの統合

docx-cli は Agent Skill として配布されており、Claude Code、Codex、および Pi に対応しています。npx skills add kklimuk/docx-cli を介してインストールするか、Linux、macOS、および Windows 用のスタンドアロンバイナリとして利用可能です。Claude Code を使用する場合、ユーザーは /plugin marketplace add kklimuk/docx-cli コマンドを使用できます。

Sources