1仕組みと動作原理

.docxを「ZIPコンテナ + OOXML」として扱い、タスク種別に応じて3つの技術ルートに分岐：新規作成はnpm docx-jsによるプログラム生成、既存編集はunzip→XML編集→zipの外科技術、読み取りはpandocを採用。

skills/docx/SKILL.md

A `.docx` is a ZIP archive of XML files. Choose your approach by task:

作成側にはアンチフットガン（危険回避）のgotchaナレッジ一式（A4デフォルトページ、表の二重幅設定、ShadingType.CLEAR、リストnumbering、ImageRun type、PageBreakの位置、PositionalTabのリーダー線など）が組み込まれ、WordとGoogle Docsの描画差異がルール化されている。

skills/docx/SKILL.md

**Table shading:** use `ShadingType.CLEAR`, never `SOLID` (renders black).

これらはdocx-js APIと実際のレンダラー（Word/Google Docs/LibreOffice）間の落とし穴リストです。例：「Column widths must sum to the table width」、「Never use `\n` — use separate `Paragraph` elements」。

編集側ではテキスト変更前にrunの正規化を実施：Wordは1文を大量の`<w:r>` runに分割するため、merge_runs.pyで隣接する同一書式のrunを統合し、XML上での安全な検索・置換を可能にする。

skills/docx/SKILL.md

Word splits text across many `<w:r>` runs (revision ids, spell-check markers), so a phrase you can see in the document often doesn't exist as a contiguous string in the XML. `merge_runs.py` merges adjacent identically-formatted runs in `word/document.xml` without changing content or rendering

merge_runs.pyのdocstringにも同様の仕組みが記載されています：「This coalesces adjacent runs whose formatting (<w:rPr>) is identical, strips rsid attributes and proofErr markers」。

検証ループは「画像レンダリング確認 + XSDバリデーション」の2系統：sofficeでPDF変換→pdftoppmで画像化→モデルによる画像Readで視覚的QAを実施。validate.pyでスキーマ／リレーション／変更履歴の整合性を検査。

skills/docx/SKILL.md

python scripts/office/validate.py out.docx --original doc.docx # XSD checks; --auto-repair fixes common issues

視覚的QAフロー：「python scripts/office/soffice.py --headless --convert-to pdf output.docx」→「pdftoppm -jpeg -r 100 output.pdf page」→「ls page-*.jpg # then Read the images」。soffice.pyはサンドボックス適合用ラッパーです（AF_UNIX無効時はLD_PRELOAD shimにフォールバック）。

変更履歴（redline）専用の検収ツールを配備：validate.pyの--authorモードにより、すべての変更が`<w:ins>`/`<w:del>`で囲まれているかを検証し、「変更したのに履歴に残らない」事故を防止。

skills/docx/SKILL.md

it reports any text you changed without a `<w:ins>`/`<w:del>` around it, which is easy to do by accident and invisible in the accepted view

本文にはセマンティクス詳細も記載：「Inside `<w:del>`, the text element is `<w:delText>`, not `<w:t>`」、段落記号削除＝次段落への結合という挙動、accept_changes.py（LibreOfficeによる変更承諾）とpandocの挙動差分析など。

コメント機能は「6ファイル連動」で構成：comment.pyが4つのcomments XML + relationships + content-type overridesを自動生成し、document.xmlへ挿入すべきアンカーコードを出力。

skills/docx/SKILL.md

The script writes `comments.xml`, `commentsExtended.xml`, `commentsIds.xml`, `commentsExtensible.xml`, the relationships, and the content-type overrides.

テンプレートファイルはscripts/templates/配下に格納（comments*.xml ×4 + people.xml）。comment.pyは展開ディレクトリモードおよび.docx直接変更モード（-o 出力）に対応。

外部からの信頼できない.docxに対する明確な防御策：解凍後にシンボリックリンク項目を削除（Zip Slip脆弱性の攻撃面を排除）。

skills/docx/SKILL.md

find unpacked -type l -delete # strip symlink entries — docx from external parties is untrusted

これはスクリプト強制ではなくプロンプトレベルの指示（解凍後にsymlinkを削除するようホストに促す）であり、XSDバリデーションや「編集時はpretty-printしない」規律と合わせて安全なドキュメント操作作法を形成しています。

2コア機能

01プロフェッショナルなWord文書のプログラミング生成（目次、見出し階層、ページ番号、レターヘッド、表、リーダー付きタブ）

02既存.docx/.dotxの編集・再構成（展開→XML編集→再圧縮）、検索・置換を含む

03コンテンツの読み取りと抽出（pandoc→markdown）、レガシーな.docは事前にsofficeで.docxへ変換

04変更履歴（Tracked changes）：校正マークの作成、--authorによる検収、accept_changes.pyによる一括承諾

05コメントの組み込み（6ファイル連動 + アンカーコード出力）

06XSD検証 + 画像レンダリング視覚的QAのデュアル検証（--originalベースライン比較 / --auto-repair）

3外部依存関係

Kind	Dependency / Endpoint
package	docx（npm，docx-js）
cli	pandoc（读取 .docx → markdown）
cli	LibreOffice soffice（渲染 QA/接受修订/.doc 转换；经 soffice.py 包装）
cli	pdftoppm（Poppler，PDF 渲染成图）
cli	unzip / zip（解包与回封 OOXML 容器）

4推奨統制措置と判定根拠

安全運用のための推奨統制措置

Agent 向け

段階的・都度認可、サンドボックス推奨

管理者向け

承認フロー、ロールバック可能、全履歴監査

判定根拠（ファイルパスと抜粋）

scripts/: ローカルスクリプトおよびコマンドの実行: merge_runs.py / comment.py / accept_changes.py / validate.py / soffice.py
本地工作目录: ファイルの読み書きと成果物出力: 出力/中間 .docx（unzip解凍ディレクトリ、zip再圧縮、out.docx）

監査ノート： 同梱のPythonスクリプトおよびローカルCLI（pandoc/soffice/pdftoppm/unzip/zip）を実行し、ローカルワークスペース内のファイルを読み書きします。外部ネットワーク通信（require/import失敗時の公式レジストリへのnpm/pipフォールバックを除く）や認証情報の読み取りは行いません。留意事項：① 制限されたサンドボックス内において、soffice.pyがローカルAF_UNIXフォールバック用の同梱socket shimをgccでその場でコンパイルしますが、完結した非悪意の処理です。② 外部の.docx編集は信頼できない入力を扱うため、プロンプト指示による防御（symlink削除 + XSD検証）に依存します。③ XML直接編集モードで不適切なエスケープを行うと文書が破損するリスクがあります。いずれもネットワークやクレデンシャルに関するセキュリティリスクには該当しません。

5二重目の独立検証

[ok] 『创建走 docx-js』路线与依赖声明 — approach 表与 Dependencies 节一致；npm 包不在仓库内（外部依赖，条件安装）。
[ok] merge_runs 机制（runs 拆分问题） — SKILL.md 描述与 merge_runs.py docstring 相互印证，均原文在。
[ok] redline --author 验收与 accept_changes — 两工具及用法命令行均存在于 SKILL.md，accept_changes.py 存在且 docstring 相符。
[ok] 批注六文件机制与 templates — comment.py 写 4 个 comments xml + rels + content-type（代码 rels/ct 常量可查）；templates/ 5 个 xml 模板（含 people.xml）与脚本引用一致。
[ok] soffice.py 沙箱 shim 无外联 — C shim 仅拦 AF_UNIX socket/listen/accept 做 socketpair 回退；编译产物在 tempdir；无任何网络地址。
[ok] 网络/凭证零命中 — 脚本层无网络调用无 env/token 读取（get_soffice_env 仅拷贝环境变量+设 SAL_USE_VCLPLUGIN/LD_PRELOAD）。
[ok] 功能声明 vs 实现（夸大检查） — description 声称的能力均有对应命令/脚本；'Do NOT use for PDFs, spreadsheets…' 负面边界清晰。唯一无法源码证实的是环境预装假设。
[ok] 元数据 — 本地 HEAD==pin 41bbe19；LICENSE.txt 为 Anthropic 专有条款（© 2025 Anthropic, PBC.），与 SKILL.md frontmatter 'Proprietary' 一致。

6結論

Wordの「隠れた複雑さ」を可視化：runの細切れ化、6ファイルのコメント構造、変更履歴のセマンティクス、レンダリングの癖を実行可能なナレッジとして形式知化。

編集→検証→画像レンダリングReadの閉ループにより、モデル自身がドキュメントの正確性を自己証明可能。

XSDスキーマ検証と自動修復機能を標準装備し、直接XMLを編集するよりもはるかに安全。

信頼できない入力に対する高いセキュリティ意識（symlink削除 + 'external parties is untrusted'の明記）。

docx/pptx/xlsxで共有されるoffice/ツールツリーを再利用し、単一の情報源と集中保守を実現。

最適な用途： 管理されたサンドボックス（Claude Code等、docx-js/pandoc/soffice/popplerが事前導入済み）環境において、Word文書の頻繁な生成・添削、テンプレート流し込み、変更履歴やコメントのレビューを自動化する用途に最適。validate+レンダリングQAのループは「即時納品可能な信頼性」が求められる現場に合致。

不向きな用途： WYSIWYGなビジュアルエディタが必要なケースや、複雑なレイアウトデザインの試行錯誤（表組みの試行コストが高い）には不向き。LibreOffice/popplerが存在しないプレーンな環境（検証や.doc変換が動作不可）には不向き。独自のライセンス条項を許容できない厳格なコンプライアンス環境には不向き。単純なテキスト読み取りのみの用途（オーバースペックであり、pandocやmarkitdownで十分）には不向き。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload docx.tar.gz

sha256: 054b66c290295197…

Option B · Copy Guide for Agent

install.json

Agent はこの JSON ガイドから自動的にダウンロードして検証します。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 41bbe19d1a.