1仕組みと動作原理

最大の強みは「変更履歴認識（revision-aware）」：素の python-docx では変更履歴の挿入（`w:ins` でラップされた子 run）の脱落や段落全体の削除（段落記号を包む `w:del`）の誤認が発生するため、python-docx を使わず公式 OpenXML SDK の csx スクリプトで ins/del/move を第一級オブジェクトとして読み取ります。

daymade-docs/read-docx-review/SKILL.md

python-docx 的 `paragraph.text` 走 `paragraph.runs`，runs 只取直接子 `<w:r>`、不递归 `<w:ins>` 包装——**对方用修订模式插入的所有内容都会被漏读**

素の lxml による `.//w:t` では `ins` は拾えるものの `w:del` で囲まれた段落全体を認識できず（校正を承認すると消滅する段落にも `w:t` が残るため）、実際の出版査読原稿で両方の取りこぼしが発生した経緯から SKILL 内に選定理由が記録されています。

アーキテクチャ = Python オーケストレーション層＋ C# dotnet-script エンジン：`docx_bridge_client.py` がステートレスに docx を直接読み込み、subprocess 経由で `csharp/tasks/*.csx`（`list_comments`/`list_revisions`/`extract_views`）を呼び出し、結果を (パス + mtime) キーでメモリ内 LRU キャッシュに保持します。

daymade-docs/read-docx-review/scripts/bridge_lib/docx_bridge_client.py

cmd = ["dotnet-script", str(script), "--", str(docx), *extra_args] proc = subprocess.run(cmd, capture_output=True, text=True, env=env)

クライアントは `~/.dotnet/tools` を自動的に PATH へ追加し、新しい .NET に対応する `DOTNET_ROLL_FORWARD=Major` を内蔵。Python 側は標準ライブラリのみで構成され外部依存関係はゼロです。

3つの csx はすべて `DocumentFormat.OpenXml` 3.2.0（`#r nuget` 宣言）に基づいており、Python の描画向けに JSON/NDJSON を出力します。パース処理はすべて C# 側で完結し、Python はオーケストレーションのみを担当します。

daymade-docs/read-docx-review/scripts/csharp/tasks/list_comments.csx

#r "nuget: DocumentFormat.OpenXml, 3.2.0" using System.Text.Json; using DocumentFormat.OpenXml.Packaging;

`list_comments` は `WordprocessingCommentsPart`（comments.xml）＋ `CommentsExPart`（paraId → done）＋ `document.xml` の `CommentRangeStart`/`CommentReference` によるデュアルアンカーを読み込みます（WPS エクスポート品の一部コメントが reference のみを持つ仕様に対応。実測で 96 件中 6 件）。

出力は空の「処置」列を備えた突合表（markdown または `--json`）：コメント記入者／対象段落／内容／ステータス＋段落ごとの変更履歴の修正内容。アンカー段落は 60 文字で切り詰められ、`--json` では全文が出力されます。

daymade-docs/read-docx-review/SKILL.md

产出表格自带空白「处置」列——它的用途就是拿去逐条裁决。引擎提炼自作者一个真实图书出版项目的审阅工具链（2026-02 起生产验证：单文件 96 条编辑批注、整书修订处理、输入含 WPS 云文档导出件）

出力規約：コメントはドキュメント順に並び、返信（`replyToCommentId`）は親コメントの下にインデント表示。変更履歴やコメントが存在しない場合は、空の表ではなく明確な通知を出力します。

結果ゼロ時はサイレントな空テーブルではなく「明確な通知」として設計：コメントも変更履歴もない場合は「この docx には校正の痕跡が含まれていません」というメッセージと2つの主な原因（エクスポート時のコメント脱落／オンライン版でエクスポート未完了）を出力し、「コメントが消えたファイルを見て、相手の意見がないと誤認する」事故を防ぎます。

daymade-docs/read-docx-review/SKILL.md

无批注无修订时输出一段明确提示（「这份 docx 没有携带任何审阅痕迹」＋两个常见原因），不会静默输出空表——拿到丢了批注的副本还以为对方没意见，比读错内容更危险。

トラブルシューティング表に調査手順も記載（相手に docx の再ダウンロード／別名保存を依頼。WPS の「docx としてダウンロード」はコメントと resolved 状態を保持することを検証済み）。

読み取り専用ポリシーの徹底：変更履歴の承認／却下、コメントへの返信、修正原稿の再エクスポート機能は提供しません。突合後の修正はユーザー自身のマスター原稿に反映し、再生成することを前提としています。

daymade-docs/read-docx-review/SKILL.md

本 skill 只读。它不提供「接受/拒绝修订」「回复批注」「改正文再导出」——对账后的改动应落在你自己的正稿源（合同草案 SSOT、书稿源文件）再重新生成

二次開発向けに段落インデックスの意味論（body の直下段落を対象とし、表内の段落は再帰探索しない、`python-docx` と準拠）を `reference csharp-tasks-spec.md` に記録しています。

2コア機能

01docx コメント全量抽出（作成者／日時／内容／resolved 状態／返信スレッド／段落アンカー、WPS エクスポート品互換のデュアルアンカー）

02変更履歴を認識した3種ビューテキスト：段落ごとの accepted/rejected/display ＋インライン ins/del および段落単位の ins/del 判定

03突合表（markdown）と機械可読な全量データ（`--json`）のデュアル出力（アンカー段落の省略／全文表示の切り替え可能）

04コメントのコンテキスト抽出：`extract_views(docx, paragraph_range=(40,55))` によるアンカー段落の前後 N 段落の取得

05python-docx を代替する段落レベルのユーティリティ関数：`paragraph_text`/`paragraphs_text`/`iter_paragraphs`（変更履歴認識対応）

06校正痕跡なし時の明確な警告＋原因調査ガイダンス（意見なしとの誤認を防止）

3外部依存関係

Kind	Dependency / Endpoint
cli	dotnet-script（csx 运行时，dotnet tool install -g）
package	DocumentFormat.OpenXml 3.2.0（NuGet，csx 首跑自动 restore 需网络 10-30s）
cli	dotnet SDK（brew install dotnet，宿主需装）

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

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

Agent 向け

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

管理者向け

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

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

scripts/: ローカルスクリプトまたはコマンドの実行: `python extract_review.py` / bridge client（ローカルオーケストレーション）
网络端点: 外部ネットワークアクセスの宣言: 実行時のネットワークアクセスは、初回の csx 実行時に `DocumentFormat.OpenXml` を NuGet から復元する際のみ発生（SKILL にて 10〜30 秒の通信が必要と明記、以降はローカルキャッシュを使用）；d
本地工作目录: ファイル読み書きおよび成果物出力: なし（docx は読み取り専用、出力は stdout/ターミナルテーブルまたは `--json` stdout のみ）

監査ノート： 読み取り専用 skill：ユーザーの docx ファイルに対して読み取りのみを行い書き込みは行いません。同梱のローカル python/csx で動作し、認証情報の読み込み、ファイルの削除、データの外部送信は一切行いません。唯一のネットワーク通信は初回 csx 実行時に nuget.org から公式 `DocumentFormat.OpenXml` を復元する処理のみであり（初回 10〜30 秒、以降はオフライン実行可能と明記）、通信先は公式かつ予期されたものです。

5二重目の独立検証

[ok] 修订感知引擎（csx + OpenXML SDK） — 三个 csx 均 #r 'nuget: DocumentFormat.OpenXml, 3.2.0' 并引用 WordprocessingPackage API；list_revisions/list_comments 输出 JSON。
[ok] Python 编排壳零第三方依赖 — docx_bridge_client.py import 仅 stdlib（subprocess/json/pathlib/functools 等）；SKILL 'Python 侧纯 stdlib' 属实。
[ok] dotnet-script 调用链 + ROLL_FORWARD/PATH 处理 — _ensure_dotnet_script_on_path 追加 ~/.dotnet/tools、env.setdefault('DOTNET_ROLL_FORWARD','Major') 均在源码。
[ok] 无状态只读 + (路径,mtime) 缓存 — _cache_key 返回 (str(p), st_mtime)；lru_cache 装饰器在三个读取函数上；无写 docx 代码路径。
[ok] python-docx 漏读叙事（w:ins/w:del） — SKILL 对 python-docx runs 直子与 w:del 段落的描述与 OpenXML 结构一致（技术事实，非夸大）；reference csharp-tasks-spec 补充语义。
[ok] 批注双锚定（WPS 兼容） — list_comments.csx 头注释记录 CommentRangeStart 首选 + CommentReference 回退及 WPS 96 条中 6 条实测。
[ok] 空结果提示防假阴性 — SKILL 声明 + extract_review.py 输出契约（无批注无修订时输出提示段）。
[ok] 无网络外发（除 NuGet 首跑） — 脚本全量扫描无 requests/urllib/http/curl；SKILL 明示 NuGet restore 需网络且仅首次。

6結論

変更履歴認識による明確な差別化：`python-docx` の ins/del に対する盲点を回避し、公式 OpenXML SDK で3種ビューを読み取ることで、同種のコメント一括読み取りツールでは稀な高いセマンティック精度を実現。

読み取り専用＋ステートレス＋キャッシュ：相手方のファイルに副作用を一切与えず、返却された校正稿に対して安全に繰り返し実行可能。

本番環境での検証実績（96 件のコメント、書籍全体の変更履歴、WPS エクスポート品）と決定ログ（コミュニティライブラリを採用しなかった理由）による検証可能な信頼性。

結果ゼロ時の明確な通知設計により、「実際にはコメントがあるのに見落とす」という最も危険な偽陰性を未然に防止。

最適な用途： 契約書、協定書、書籍原稿、レポートなど、相手方のコメントが入って返却された Word/WPS のコメントおよび変更履歴モードのフィードバック確認に最適。特に法務や出版編集者向け。突合表と処置列により1件ずつの裁定ワークフローへスムーズに接続可能。.NET 環境と初回実行時のインターネット接続が必要です。

不向きな用途： 直接原稿を修正したり変更履歴を承認／却下したりするワークフローには不向き（読み取り専用）；PDF、Feishu/Lark、Tencent Docs のコメントには非対応（対象外）；.NET がない完全オフライン環境には非対応；表内の詳細なコメントアンカーは body 直下段落のインデックス仕様を超えるため対象外。

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload read-docx-review.tar.gz

sha256: 5d26333cd2cde9a9…

Option B · Copy Guide for Agent

install.json

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

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.