docx-cli: AI エージェントのためのドキュメント編集 CLI ツール

AI エージェント向けに構築された

.docx

特徴と仕組み

• 人間に近い出力: Claude や Codex に

  .docx

  ファイルを渡すと、コメント付きの赤線版コピーを受け取れます。Word で開き、通常通り受け入れるか拒否してください。
• 安定した位置指定: エージェントは**文字オフセット（例：

  p3:5-20

  ）**という安定した位置指定子を用いてテキストにアクセスし、人間はディスク上の通常の Word フォーマットを見ることができます。
• フォーマットの維持: カスタムスタイル、テーマカラー、埋め込みオブジェクト — すべてが維持されます。
• 効率的な変異: CLI は失効するモデルから再エミッションをするのではなく、XML をその場に変異（mutate）させます。

なぜ docx-cli か？

エージェントが Word ドキュメントを編集するデフォルトの方法は、

.docx

• docx-cli の利点: エージェントに単なるコマンドと注釈付きの Markdown リードビューを提供するため、XML に関する推論を行う必要がありません。

実証データ：A/B テストの結果

制御された A/B テスト（6 つの実際のドキュメントタスク）を実施しました。独立した審査員が Word レンダリングページの各結果を評価し、モデル階層ごとの 2 つのレベルで 3 回の実行を行いました。

主要な発見

• 正解のギャップ: 低コストな Haiku レベルで最も広く（約 6 倍）。フロンティアモデルはそれを埋めることができません — デフォルトスキルは最大 4/6 に達し、Sonnet の各実行ごとに契約書の赤線編集とレジュメを失います。
• コストとスピードのペナルティ: モデルに依存しない — 両方の階層で約 2.2〜2.6 倍多くのトークンと約 1.7〜2 倍遅いです。
• Word の信頼性: Word はデフォルトスキルの作業を正常に開けることができませんでした（36 件中 5 件を開けませんでした）。docx-cli のすべての 36 件は 1 回目で開きました。

[完全な方法論、タスク別基準、並置レンダリング：テスタメントの記録] (参照)

インストール

1. npm / Bun

Bun >= 1.3 を必要とします。

bun add -g bun-docx
# またはインストールなしで実行:
bunx bun-docx read doc.docx

2. スタンドアロンバイナリ

Bun は不要です。プリビルトされたバイナリを使用します。

curl -fsSL https://raw.githubusercontent.com/kklimuk/docx-cli/main/install.sh | sh

• PREFIX: デフォルト

  $HOME/.local/bin

• VERSION: デフォルト

  latest

クイック例：NDA の記入

レポジトリには Common Paper Mutual NDA テンプレート (

tests/fixtures/mnda.docx

# まずコピーを作成します — やり直しはありません (git が履歴であり、CLI はその場を上書き)
cp tests/fixtures/mnda.docx mnda-filled.docx

# エージェントがプレースホルダーを知るためにカバーページのテーブルを読み取る
docx read mnda-filled.docx --from t1 --to t1

# 黄色でハイライトされたかっこ内のプレースホルダーを記入する
docx replace mnda-filled.docx "Fill in: today's date" "May 6, 2026"
docx replace mnda-filled.docx "fill in state and/or county" "California"

# リッド変更のためにオンに切り替える
docx track-changes mnda-filled.docx on

# 「Use & Protection」節内のフレーズを縮める
docx replace mnda-filled.docx \
    "having a reasonable need to know" \
    "with a documented need to know"

# 人間審査員向けのコメントを残す — --at で既存のスパンにアドレスする
docx comments add mnda-filled.docx --at p7:0-30 \
    --text "Should we narrow 'representatives' to a named list?"

# Word で mnda-filled.docx を開く：
# リッド変更とコメントはレビューウィンドウに表示され、受け入れるか拒否するか返信する準備ができている。

エージェントスキルとして使用

docx-cli はエージェントスキルとして出荷されています。SKILL.md ファイルを読み取るハーネス（Claude Code, Codex, Pi など）で機能します。

インストール方法

• あらゆるエージェント (skills.sh):

  npx skills add kklimuk/docx-cli
  

• Claude Code:

  /plugin marketplace add kklimuk/docx-cli
  /plugin install docx-cli@docx-cli
  

• Codex:

  codex plugin marketplace add kklimuk/docx-cli
  

• Pi:

  pi install git:github.com/kklimuk/docx-cli     # グローバル
  

最新の状態に保つ

バイナリが真のソースです。コミットされたコピーがドリフトした場合 CI テストは失敗します。

docx info skill > skills/docx-cli/SKILL.md

重要:

docx <command> --help

は権威ある契約です。エージェントはコールを構成する前にこれを必ず実行してください。各コマンドの

--help

がフラグ、ローケーター形式、正確な出力形状の真のソースです。

コマンド参照

基本構文

docx <verb>

docx <noun> <verb>

--help

• リード＆クエリー: データを stdout に印刷します（ファイル書き換えなし）。
• 変異コマンド: ファイルを変更します（

  --dry-run

  、

  -o/--output PATH

  を支持）。

リード＆クエリー (stdout 出力)

docx read FILE [--from LOC] [--to LOC] [--accepted | --baseline | --current] [--comments]
docx read FILE --ast                                  # JSON-AST 代わりに Markdown（Markdown のみフラグを無効化）
docx find FILE QUERY [--regex] [--ignore-case] [--all]
docx find FILE (--highlight COLOR) [--all]             # フォーマットによる検索（QUERY なし）
docx wc FILE [LOCATOR] [--json]
docx outline FILE [--style-prefix S] [--json]          # インデントツリー
docx styles FILE [--used] [--at STYLEID]
docx styles --catalog                                  # 組み込みスタイル一覧 (Title, Heading1–9...)
docx images list FILE
docx hyperlinks list FILE

変異 (FILE をその場で変更)

• Core:

  docx create

  ,

  docx insert

  ,

  docx edit

  ,

  docx delete

• Replace & Batch:

  docx replace FILE PATTERN REPLACEMENT [--regex] [--all] [--limit N]
  # バッチ処理 (JSONL) の例:
  docx edit FILE --batch fills.jsonl
  docx insert FILE --batch additions.jsonl
  docx replace FILE --batch script.jsonl
  

コメント・脚注・ヘッダー操作

コメント

docx comments add FILE --at LOCATOR --text "..." [--author NAME]
docx comments reply FILE --at cN --text "..."
docx comments resolve FILE --at cN
docx comments delete FILE --at cN
docx comments add FILE --batch reviews.jsonl           # JSONL: { at | anchor, text, author? }

脚注・末尾脚注

docx footnotes add FILE --at pN[:offset] (--text "..." | --markdown TEXT)
docx footnotes edit FILE --at fnN (--text "..." | --markdown TEXT)
docx endnotes add FILE --at pN[:offset] (...), delete, edit

ヘッダー・フッター (marginals)

# セクション sN に設定します (--type default|first|even/odd / --first-page etc.)
docx headers set FILE [--at sN] [--text "..."] [--align left] [--page-number] [--style-ref STYLE] [--field filename|title]
docx footers set FILE …                                # 同一フラグ（kind=footer）
# クリア
docx headers clear FILE [--at sN]

画像・ハイパーリンク・リスト・テーブル

• 画像:

  extract

  ,

  replace

  ,

  delete

  を使用。

  --caption

  で Word のキャプションスタイルを追加可能。
• ハイパーリンク:

  add

  ,

  replace

  (

  --with URL

  ),

  delete

  。
• リスト:

  docx lists set FILE --at pN [--start N] [--format FMT]

  （FMT: decimal, lower-alpha, upper-roman など）。
• テーブル:

  • insert-row

    ,

    insert-column

  • merge

    ,

    unmerge

  • set-widths

  • borders

    (style: single|double|none)

  • format

    (valign, halign, style ID など)

リッド変更管理

docx track-changes on|off FILE
docx track-changes list FILE [--json]
docx track-changes accept FILE (--at tcN | --all)       # ファイルを finaliza せずに一括適用
docx track-changes reject FILE
docx track-changes apply FILE                           # 元の id に対して決断リストを一呼いで適用（再番号化せず）

ローケーター (Locator) と ID の発見

位置指定の形式

• ブロック:

  pN

  (段落),

  tN

  (テーブル),

  sN

  (セクション)。
• スパン:

  pN:S-E

  (文字範囲),

  pN-pM

  (全パラグラフ範囲)。
• セル:

  tN:rRcC:pK

  (row R, col C のセル内の段落 K)。

Offset セマンティクス: Character オフセットは 0-based、start-inclusive、end-exclusive です（例：

p3:5-20

ID の発見

各リスト動詞 (

list

--at

pN

tN

read

outline

render page images

cN

comments list FILE

fnN

enN

footnotes list

endnotes list

imgN

images list FILE

linkN

hyperlinks list FILE

tcN

track-changes list FILE

jq を通じたフィルタ例:

docx comments list doc.docx \| jq '.[] \| select(.author=="Jane")'

出力契約 (Output Contract)

CLI は非インタラクティブエージェントのために構築されています。Exit コード 0 は成功シグナルです。

USAGE

INVALID_LOCATOR

FILE_NOT_FOUND

COMMENT_NOT_FOUND

NOT_A_ZIP

RENDER_FAILED

TABLE_STRUCTURE

• エラーは

  {code, error, hint?}

  JSON を stdout に印刷し、非ゼロ exit を持ちます。

• ok

  フィールドは成功時 (

  --verbose

  含む) に

  {ok:true, ...}

  と表示されます。

デフォルト出力形状

{ok:true,…}

<operation> <target>

edit t1:r0c1:p0

replace 3 occurrences

{ok:true,…}

--json

--json

{ words, scope, ... }

--ast

メモ:

find

,

replace

,

wc

などは同じ

--accepted/--baseline/--current

flags を尊重し、オフセットがコマンド間で一貫性を保ちます。

仕組み (Under the Hood)

• その場 XML 変異:

  read

  が返す AST は別モデルではなく、パースされた XML ツリー上のビューです。編集は基盤の XML ノードを直接変異させ、再シリアライズします。カスタムスタイルやテーマカラーなどの未記述領域は失われません。
• JSX for エミッター: OOXML フラグメントを imperatively 構築する代わりに、新鮮な XML は JSX で作成されます（

  <w.rPr><w.b/></w.rPr>

  のような構文）。
• リッド変更:

  <w:trackChanges/>

  が設定されている場合、

  insert/edit/delete/replace

  はネイティブ

  <w:ins>/<w:del>

  を出力します。

  images replace

  や

  hyperlinks

  については

  [docx-cli]

  オーディットコメントを出力します。
• Rich コンテンツ:
  • 画像: Path、Data URI、URL を受け付けます。HEIC → JPEG transcode。非公開リダイレクトは拒否。
  • 方程式: OOXML

    <m:oMath>

    ↔ LaTeX round-trip（temml 経由）。
  • コードブロック: GFM 囲みブロックで折り返します。
• Literal テキスト - パーサーフリーチャネル:

  create --text-file PATH

  /

  insert --text-file PATH

  を使用すると、改行ごとに新しい段落が作られ、Markdown の解釈（リンク作成、強調など）は適用されません。プロースの正確なままを挿入したい場合に最適です。
• ドキュメントワイドフォント:

  docx styles set-default-font FILE "Times New Roman"

  は、

  <w:docDefaults>

  とテーマフォントスキームの両方に設定し、実 Word が解決します。
• Visual 検証:

  docx render

  は唯一外部 runtime (Word/LibreOffice) や bundled WASM (

  pdfium

  ) を必要とするコマンドです。

スタックとコントリビュート

技術スタック

• Runtime: Bun (node:util parseArgs, JSX, native zlib)
• Parser: jszip + fast-xml-parser / builder
• Markdown: unified + remark-parse/gfm/math
• Math: temml (MIT) LaTeX → MathML ↔ OMML アダプター
• Render: @hyzyla/pdfium (WASM) for PDF rasterization
• Quality: Biome + Knip + tsc；LibreOffice headless for CI

コンタクト

詳細なアーキテクチャ概要や開発セットアップについては、

CONTRIBUTING.md