docx-processing-superdoc

SuperDoc CLI（v1）

DOCX 作業には SuperDoc CLI を使用します。v1 コマンド（標準操作とそのヘルパーラッパー）を使用してください。 v0 形式の一括ワークフローが明示的に必要な場合を除き、レガシーコマンドをデフォルトで使用しないでください。

superdoc がインストールされている場合はそれを使用し、そうでない場合は代替として npx @superdoc-dev/cli@latest を使用してください。

最初のステップ：正確なパラメーターを確認する

不明なコマンドやフラグについては、まず実行時メタデータを確認してください。

superdoc describe
superdoc describe command find
superdoc describe command "comments add"

コマンドごとの引数と制約を確認するには、describe command を使用してください。

推奨ワークフロー

1）状態を保持する複数ステップの編集（推奨）

superdoc open ./contract.docx
superdoc query match --select-json '{"type":"text","pattern":"termination"}' --require exactlyOne
superdoc replace --target-json '{"kind":"text","blockId":"p1","range":{"start":0,"end":11}}' --text "expiration"
superdoc save --in-place
superdoc close

• 変更対象を特定するには、常に find ではなく query match を使用してください。query match は、多重度の保証付きで正確なアドレスを返します。
• open の後は、<doc> を省略したコマンドはアクティブ／デフォルトのセッションに対して実行されます。
• 明示的にセッションを管理するには、superdoc session list|set-default|save|close を使用してください。
• 変更が未保存の状態で close するには、--discard を指定するか、事前に save する必要があります。

2）ステートレスな単発の読み取り

superdoc get-text ./proposal.docx
superdoc get-markdown ./proposal.docx
superdoc info ./proposal.docx

3）ステートレスな単発の変更

superdoc replace ./proposal.docx \
  --target-json '{"kind":"text","blockId":"p1","range":{"start":0,"end":5}}' \
  --text "Updated" \
  --out ./proposal.updated.docx

• ステートレスモード（<doc> を指定）では、--dry-run を使用しない限り、変更コマンドに --out が必要です。

安全性：適用前にプレビューする

• 変更を適用せずにプレビューするには、--dry-run を使用してください。
• ステートフルな変更で楽観的同時実行制御を行うには、--expected-revision <n> を使用してください。

よく使う v1 コマンド

クエリと確認

• コンテンツを検索／閲覧：find --type text --pattern "..." または find --query-json '{...}'
• 変更対象を特定：query match --select-json '{...}' --require exactlyOne
• ブロックを確認：blocks list、get-node、get-node-by-id
• コンテンツを抽出：get-text、get-markdown、get-html

変更

• テキストを置換：replace --target-json '{...}' --text "..."
• インラインテキストを挿入：insert --block-id <id> --offset <n> --value "..."
• テキスト／ノードを削除：delete --target-json '{...}'
• ブロックを削除：blocks delete、blocks delete-range
• 変更をまとめて適用：mutations apply --steps-json '[...]' --atomic true --change-mode direct
• 段落を作成：create paragraph --text "..."（任意の --at-json を指定可能）
• 見出しを作成：create heading --input-json '{"level":<n>,"text":"..."}'

書式

• 書式を適用：format apply --block-id <id> --start <n> --end <n> --inline-json '{"bold":true}'
• ショートカット：format bold、format italic、format underline、format strikethrough

リスト

• リスト項目を確認：lists list、lists get
• リスト項目を挿入：lists insert --node-id <id> --position after --text "..."
• 変更：lists indent、lists outdent、lists set-level、lists set-type、lists convert-to-text

コメント

• 追加／返信：comments add、comments reply
• 読み取り：comments get、comments list
• 編集／解決／移動：comments edit、comments resolve、comments move、comments set-internal
• 削除：comments delete（標準）または comments remove（エイリアス）

変更履歴

• 一覧表示：track-changes list、track-changes get
• 決定：track-changes accept、track-changes reject、track-changes accept-all、track-changes reject-all

履歴

• history get、history undo、history redo

低レベル操作

• 直接呼び出し：call <operationId> --input-json '{...}'（JSON 出力のみ。--pretty はサポートされていません）

JSON／ファイルのペイロードフラグ

すべてのコマンドで --*-file 形式を使用できるわけではありません。確認するには、describe command <name> を使用してください。

対応する -json 形式と併用できます（どちらか一方を使用し、両方は使用しないでください）。

フラグの組み合わせ	使用可能なコマンド
--query-json / --query-file	find、lists list
--address-json / --address-file	get-node、lists get
--input-json / --input-file	call、create paragraph
--at-json / --at-file	create paragraph

--target-json は多くの変更コマンドで使用できますが、対応する --target-file はありません。--target-json の代わりに、フラットなフラグ（--block-id、--start、--end）を使用できます。

出力とグローバルフラグ

• デフォルトの出力は JSON エンベロープです。
• 人間が読みやすい出力にするには --pretty を使用します（call ではサポートされていません）。
• グローバルフラグ：--output <json|pretty>、--session <id>、--timeout-ms <n>。
• <doc> に - を指定すると、標準入力から DOCX バイトを読み込みます。

レガシー互換性（必要な場合のみ使用）

レガシー v0.x ブリッジコマンドも引き続き利用できます：

superdoc search <pattern> <files...>
superdoc replace-legacy <find> <to> <files...>
superdoc read <file>

v0 形式の動作が特に必要な場合（特に複数ファイルのグロブ検索・置換）にのみ使用してください。 新しい自動化では、v1 の操作を優先してください。