respira-builder-edits

Respira Builder の編集

よくある間違い

間違い	正しい方法
見出し、画像、ボタンの変更に respira_update_page を使う	respira_find_element を使ってから respira_update_element を使います。ページツールは本文全体を置き換えるため、ビルダー内のノードがすべて失われます。
respira_get_builder_info を確認せずに respira_update_page を呼び出す	必ず最初にビルダーを特定します。ビルダー管理ページで update_page を使うと、ビルダーの JSON が破損します。
フィールド名を推測してビルダーの生の JSON を編集する	書き込む前に、respira_read_page、respira_find_element、または respira_get_builder_inline_schemas で現在の構造を読み取ります。
スナップショットを作成せずに大幅な変更を行う	複数の要素を編集する前に、必ず respira_create_page_duplicate を呼び出します。
Divi 5 でも Divi 4 と同じフィールドが使われると思い込む	Divi 4 は post_content にショートコードを保存します。Divi 5 はブロックと、complexifier が生成するノードごとの attrs._nodeId を保存します。ID による照合では _nodeId のフォールバックが必要です（v7.0.30 で追加）。
ネストした Divi 5 のペイロードを children だけで渡す	Divi 5 は Divi の語彙に合わせたエイリアス rows / cols / modules も受け付けます（v7.0.32 で取り込み）。v7.0.32 より前は、これらはエラーなく無視されていました。
存在しない Beaver Builder のモジュールタイプを使う	content_field_map は Heading、Text、Button、Image、HTML、Video、Sidebar、Box に対応しています（v7.0.13 で追加）。不明なタイプはエラーなしで処理を迂回します。
{"button_text": "Go"} のようなフラットな updates を渡す	フラット形式、または {settings: {button_text: "Go"}} のどちらかを渡します。v7.0.16 で両方を設定オブジェクトにディープマージするようになりました。v7.0.19 で Divi 4 にも対応しました。v7.0.29 で update_module と apply_builder_patch にも対応しました。
「このページに何があるか」を確認する際に respira_get_page_outline を省略する	アウトラインは extract_builder_content より軽量で、行ごとの子要素数と主見出しも含まれます。編集する要素を決める前に使ってください。

入力

• ページまたは投稿の URL、ID、スラッグ。
• 変更内容の説明（テキスト、画像 URL、色、スタイル、リンク）。
• 使用中のビルダー。不明な場合は respira_get_builder_info で自動検出します。

ワークフロー

1. サイトを把握します。 まだ呼び出していない場合は、respira_get_site_context と respira_get_builder_info を呼び出します。
2. ページを把握します。 構造をすばやく確認するには respira_get_page_outline を、対象がすでに分かっている場合は respira_find_element を呼び出します。
3. 公開済みのページは複製を経由します。 公開済みのページまたは投稿では、サイト所有者が直接編集を有効にしていない限り、Respira は複製した下書きに編集を適用します（未公開の項目はそのまま編集されます）。respira_approve_duplicate で公開する前にユーザーに確認してください。この会話中にユーザーが公開に同意したら、後から依頼された変更も完了後に公開し、公開されたことを伝えてください。ページへの書き込み前には必ずスナップショットも保存されるため、手動で作成する必要はありません。
4. 要素を特定します。 テキスト内容、CSS クラス、ウィジェットタイプ、要素 ID など、利用可能な中で最も具体的なセレクターを指定して respira_find_element を呼び出します。Bricks 2.3.x と Divi 5 では id と attrs._nodeId の両方が表示され、どちらでも使用できます。
5. 編集を適用します。 変更するフィールドだけを指定して respira_update_element を呼び出します。同じページの複数の要素を編集する場合は、respira_batch_update を優先します。
6. 確認します。 要素を再読み込みし、変更が反映されていることを確認します。Divi 5 では、CSS やスタイルによる変更の場合、レンダラーには独自の処理経路があるため、フロントエンドも確認します。
7. 報告します。 何をどこで変更したかをユーザーに伝えます。

ビルダー固有の注意事項

• Elementor 3. コンテンツは _elementor_data に格納されています。各ウィジェットには id、widgetType、settings があります。基本パスは成熟しています。
• Elementor 4（Atomic Elements）。 v7.1 では、9 つのアトミックウィジェット（e-heading、e-paragraph、e-button、e-image、e-svg、e-divider、e-youtube、e-self-hosted-video、e-component）と 11 個のアトミックレイアウトコンテナー（e-flexbox、e-div-block、e-grid、e-tabs ファミリー、e-form ファミリー）全体で、エンドツーエンドの書き込みをサポートしました。v7.1 より前は、アトミック要素への書き込みはすべて respira_elementor_atomic_write_unsupported を返す 422 エラーになっていました。v4 ノーマライザーは省略形を正規の $$type エンベロープに変換し、v4 バリデーターは不正なノードが DB に到達する前に検出します。サポート対象外のアトミックタイプは引き続き即座に拒否され、エラー本文に supported_widgets が含まれます。
• Divi 4. post_content にショートコードを格納します。v7.0.19 と v7.0.29 で、update_element、batch_update、apply_builder_patch、remove_element、inject_builder_content、update_module の問題を修正しました。kses の回避処理は維持されるため、et_pb_code 内の <script> と <style> は保持されます。カスタム投稿タイプに対応しています。
• Divi 5. ブロックと attrs._nodeId を使用します。v7.0.16 で背景オーバーレイのキーを修正しました（レンダラーが参照するのは overlay.enable です）。v7.0.28 で、数値カウンターの型付きエンベロープとボタンのテキストカラーの二重書き込みを修正しました。v7.0.30 で、ID 照合に _nodeId のフォールバックを追加しました。v7.0.32 で、子要素エイリアスの統合（rows、cols、modules）と、子要素が無言で失われる場合のハードエラーを追加しました。
• Beaver Builder. v7.0.13 で Box モジュールのマッピングを追加しました。v7.0.16 で型付きノードの正規化（{type:'row', columns:[…]}）を修正しました。v7.0.17 で、エージェントが指定しない場合のデフォルト値として、列が全幅で表示されるよう size に "100" を設定しました。v7.0.25 で、トップレベルのフォントフィールドに関する stdClass の致命的エラーを修正しました。v7.0.26 で、修正対象をタイポグラフィコンテナーにも拡張しました。モジュール内のカスタム HTML は kses の回避処理によって保持されます。
• Bricks. v7.0.23 でページ設定のディープマージと CSS 再生成 API を修正しました。v7.0.24 でファイルモードの CSS 再生成に関する不足を解消しました。v7.0.26 でグローバルクラスの ID 解決と、レジストリーを上書きしていた EDITABLE ルートの競合を修正しました。v7.0.27 で設定の正規化を統一しました。null は削除され、_background.color と _color の文字列は {hex, raw} に変換され、タイポグラフィのキーは _typography に移行され、_gap は _columnGap と _rowGap に展開されます。
• Oxygen Classic. v7.0.18 で、ルートでラップされた _ct_builder_json の形式（{id:0, name:"root", depth:0, children:[…]}）を追加しました。従来の配列のみのページは、次回の読み取り時に自動修復されます。v7.0.17 で inject を try/catch \Throwable でラップし、oxy_save_ct_builder_json_meta にフックされたサードパーティープラグインによって REST リクエストが致命的エラーにならないようにしました。
• Oxygen 6. _oxygen_data に格納され、Classic とは異なる形式です。v7.0.7 でディープインテリジェンスの同等性を実現しました。
• Breakdance. v7.0.20 で、エージェントが出力するすべての形式に対応する resolve_breakdance_properties() を追加しました。v7.0.21 で、レンダラーが content.content.* を参照する 15 種類の要素に対応する nest_breakdance_content_section() を追加しました。v7.0.22 で append のラップ解除と置換確認ゲートを修正しました。
• WPBakery + Uncode. v7.0.31 で、Uncode アダプターパック（uncode_* および tdb_* ショートコードを第一級要素として扱う）を追加しました。また、find_builder_targets のページネーション、コンテンツを含む属性をデコードしたラベルの設定、respira_get_page_outline、respira_get_builder_inline_schemas も追加しました。サイト固有の拡張には respira_wpbakery_shortcode_prefixes でフィルタリングできます。

ルール

• コンテンツの編集に respira_update_page を使用しないでください。ページ本文全体が置き換えられ、ビルダーでは結果が単一のテキストブロブとして扱われます。
• ビルダーの JSON フィールド名を推測しないでください。最初に読み取ってから書き込んでください。
• 今回のセッションでまだ編集していないページを初めて編集する前に、必ず respira_get_site_context と respira_get_builder_info を実行してください。
• Divi 5 で ID を使って照合する場合は、id と attrs._nodeId の両方で解決できることを想定してください。
• Bricks のファイルモード CSS（cssLoading=file）では、v7.0.24 がフロントエンドの状態を初期化するため、要素ごとのルールが正しく出力されます。回避策は不要です。
• ビルダーが不明な場合は、respira_get_builder_info を呼び出し、編集前に確認を待ってください。

検証

編集のたびに、次の手順を実行してください。

1. 編集前と同じセレクターを使って respira_find_element を呼び出します。
2. 変更されたフィールドが意図した値と一致することを確認します。
3. 要素が見つからない場合、または変更されていない場合は、respira_update_element がエラーまたは構造化されたソフトフェイルを返したか確認します。

一括編集の場合：

1. respira_diff_snapshots を使って編集前後のスナップショットを比較します。
2. 変更した要素がすべて反映されていることを確認し、反映されていないものがあれば報告します。

エスカレーション

次の場合は作業を中止し、ユーザーに確認してください。

• respira_get_builder_info が不明または非対応のビルダーを返す場合。
• v7.0.x の修正が適用された後も、respira_update_element が Bricks、Oxygen、または Breakdance の要素に対してソフトフェイルを返す場合。
• REST エンドポイントをブロックする WAF またはセキュリティプラグインによってページが保護されている場合。respira_diagnose_connection は Cloudflare エッジによる書き込みブロックを検出します。
• 20 を超える要素を編集する場合。続行する前に対象範囲を確認してください。

例

目的：「Welcome」というヒーロー見出しのテキストを「Get started today.」に変更する。

1. respira_get_builder_info        → Elementor 3.21, supported
2. respira_get_page_outline        → 4 sections, hero is row 0, primary heading "Welcome"
3. respira_create_page_duplicate   → snapshot ID abc123
4. respira_find_element            → selector: text="Welcome", type: heading
   Result: element ID e7a2, widgetType: heading, settings.title: "Welcome"
5. respira_update_element          → element ID e7a2, settings.title: "Get started today."
6. respira_find_element            → element ID e7a2
   Result: settings.title: "Get started today." ✓