respira-builder-edits

Respira 构建器编辑

常见错误

错误	正确做法
使用 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 存储区块，以及由复杂化器生成的每节点 attrs._nodeId。按 ID 匹配需要 _nodeId 回退机制（在 v7.0.30 中添加）。
只通过 children 传递嵌套的 Divi 5 负载	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 中添加）。未知类型会直接略过，不会报错。
传入扁平的 updates，例如 {"button_text": "Go"}	传入扁平格式，或 {settings: {button_text: "Go"}}。v7.0.16 会将两种格式深度合并到 settings 对象中。v7.0.19 将此功能扩展到 Divi 4。v7.0.29 将其扩展到 update_module 和 apply_builder_patch。
查看“此页面上有什么”时跳过 respira_get_page_outline	大纲比 extract_builder_content 更轻量，并提供每行的子项数量和主标题。请先使用它，再决定要编辑哪个元素。

输入

• 页面或文章的 URL、ID 或 slug。
• 修改内容的描述（文本、图片 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. 查找元素。 使用可用的最具体选择器调用 respira_find_element：文本内容、CSS 类、组件类型或元素 ID。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 之前，所有原子写入都会返回 422 respira_elementor_atomic_write_unsupported。v4 规范化器会将简写转换为规范的 $$type 信封；v4 验证器会在节点写入数据库前捕获格式错误的节点。对于不支持的原子类型，系统仍会快速拒绝，并在错误正文中提供 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。ksес 绕过机制仍然有效，因此 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"，这样即使 Agent 未提供该值，列也会以全宽显示。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 使用 try/catch \Throwable 包装了 inject，因此挂接到 oxy_save_ct_builder_json_meta 的第三方插件不再导致 REST 请求发生致命错误。
• Oxygen 6。 数据存储于 _oxygen_data，格式与 Classic 不同。v7.0.7 补齐了深度智能支持。
• Breakdance。 v7.0.20 为 Agent 生成的所有结构新增了 resolve_breakdance_properties()。v7.0.21 为 15 种渲染器读取 content.content.* 的元素类型新增了 nest_breakdance_content_section()。v7.0.22 修复了解包追加和替换确认门控。
• 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 元素返回软失败。
• 页面受到 WAF 或安全插件保护，导致 REST 端点遭到拦截。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." ✓