从 DXPR Builder 1.x 或 2.x 迁移.
DXPR Builder 3.x 从任何 1.x 或 2.x 版本就地更新。Composer 替换代码，drush updatedb 运行 dxpr_builder.install 中转换配置和内容的更新钩子。本页列出这些钩子做什么、自定义代码有何变化，以及如何验证结果。发布日期来自 git 标签；请参阅旧版本。
版本简史
| 系列 | Drupal | 说明 |
|---|---|---|
| 7.x-1.x | Drupal 7 | 曾以 Glazed Builder 销售，后改名。 |
| 1.x (8.x-1.x) | Drupal 8 和 9 | 模块机器名 dxpr_builder 自 2020 年 5 月首个 1.x 起。最后版本 1.8.8。 |
| 2.x | Drupal 9.3 到 11 | CKEditor 5、Key 模块支持、首批 AI 功能。最后版本 2.8.1。 |
| 3.x | Drupal 10.2 和 11 | 仅 Bootstrap 5、Key 模块必需、内容迁移、AI 页面和图像生成。 |
1.x 到 3.x 机器名未变。仍带 Glazed 时代标记的内容必须先在 1.x 或 2.x 上迁移再升级；3.x 不再改写 Glazed 名称（见下文）。
开始前要求
- Drupal 10.2 及以上，或 Drupal 11（
dxpr_builder.info.yml中的core_version_requirement）。 - Key 模块。3.x 硬依赖；
drush updatedb发现缺失时dxpr_builder_update_9020()安装它。 - DXPR Builder 2.0.0 及以上签发的产品密钥。没有
dxpr_tier声明的密钥被设置表单拒绝。 - 提供 Bootstrap 5 的主题，或 Bootstrap 5 sideload 选项。Bootstrap 3 和 4 的 sideload 已取消。
迁移步骤
-
备份数据库和文件：
drush sql:dump --result-file=backup.sql -
用 Composer 更新代码。3.x 目前以预发布发布，请允许：
composer require 'drupal/dxpr_builder:^3.0@beta' --with-all-dependencies -
运行更新钩子并重建缓存：
drush updatedb drush cache:rebuild多个 3.x 钩子分批处理每个 DXPR Builder 字段值（见下文）。大站点上耗时按分钟计，而非秒。
-
打开
/admin/dxpr_studio/dxpr_builder/settings并检查 License 分区。更新 9020 后 Storage method 为 Key module，Key 为DXPR Builder JWT（dxpr_builder_jwt）。 -
在同一页面检查 Sideload Bootstrap files。之前选 Bootstrap 3 或 4 的站点现在是 Bootstrap 5。
-
打开
/admin/dxpr_studio/dxpr_builder/ai_settings，决定默认开启的三个 AI 开关是否保持开启。 -
访问使用 DXPR Builder 的页面，确认渲染和编辑正常。
更新钩子做什么
编号 8005 到 8025 的钩子随 1.x 发布。1.x 站点运行 8026 起的全部；2.8.0 或 2.8.1 站点运行 8040 和 9014 起的。函数名为 dxpr_builder_update_NNNN()。
2.x 新增（从 1.x 来时运行）
| 钩子 | What it does |
|---|---|
| 8026 | 更新 DXPR Builder 中央用户存储。 |
| 8027 | 添加许可证信息区块，并在 People 视图加 "DXPR Builder User" 列。 |
| 8028 | 创建内容锁定的 dxpr_lock 表。 |
| 8029 | 在用户许可证仪表盘添加许可证区块。 |
| 8030 | "Bootstrap 3 Light" 选项移除后切换 Bootstrap 设置。 |
| 8031 | 在禁用安装处启用许可证信息区块。 |
| 8032 | 从许可证存储移除被封禁用户。 |
| 8033 | 初始化 drm_last_contact。 |
| 8034 | 安装 dxpr_user_is_disavowed 用户字段和 avow/disavow 用户操作。 |
| 8035 | 初始化 hide_reminders 设置。 |
| 8036 | 把档案中 CKEditor 4 工具栏按钮名迁移到 CKEditor 5。 |
| 8037 | 添加快速加载图片的默认图片样式。 |
| 8038 | 清缓存以注册 Key 模块集成服务。 |
| 8039 | 修复 image_scale_and_crop 设置不完整的图片样式。 |
| 9007 | 创建带默认术语的 ai_tone_of_voice 和 ai_agent_commands 词汇表。 |
| 9008 | 将 ai_enabled 设为 true 并移除旧 ai_page_enabled 键。 |
| 9009 | 将 drm_last_contact 从配置移到状态。 |
| 9010 | 清缓存。 |
| 9011 | 在每个档案启用 AI Assistant 和 AI Tone of Voice 按钮。 |
| 9012 | 恢复 ai_page_enabled，默认 true。 |
| 9013 | 设置 AI 输出过滤默认值（ai_output_allowed_domains）。 |
| 9015 | 添加 ai_image_enabled，默认 true。 |
3.x 新增（从 1.x 或 2.x 来时运行）
| 钩子 | What it does |
|---|---|
| 8040 | 将 bootstrap 规范为 bs5；1（Bootstrap 3）和 bs4 值被改写。 |
| 9014 | 分批：把内容中的 Owl Carousel 标记转为 Bootstrap 轮播（src/Migration/OwlCarouselMigration.php）。 |
| 9016 | 添加 ai_user_model_selection，默认 true。 |
| 9017 | 分批：把 circliful 环形计数器转为 Bootstrap 进度标记（CircleCounterMigration.php）。 |
| 9018 | 分批：把旧版进度条标记转为 Bootstrap 进度结构（ProgressBarMigration.php）。 |
| 9020 | 安装 Key 模块，把 json_web_token 移入 Key 实体 dxpr_builder_jwt，将 api_key_storage 设为 key 并清除明文值。 |
| 9021 | 从标记回填用户模板的 type 属性。 |
| 9022 | 分批：给内部 /node/N 链接加 data-entity-type 和 data-entity-uuid（EntityLinkMigration.php）。 |
| 9023 | 分批：修复更新 9022 在 text_with_summary 字段丢失的文本格式、摘要和已删除增量。 |
| 9024 | 分批：以 9022 同样方式丰富别名内部链接（AliasLinkMigration.php）。 |
| 9025 | 当 tone_of_voice_vocabulary 指向不存在的词汇表时清空它。 |
| 9026 | 密钥在 Key 实体中时，清除设置中遗留的明文 json_web_token。 |
没有更新 9019。
内容迁移
3.x 只分批运行内容迁移，不再有渲染时转换。迁移状态页（/admin/dxpr_studio/dxpr_builder/migration-status）和状态报告列出待迁移内容。上面的更新钩子迁移它，该页的 Run now 和 Run all pending migrations 操作也迁移。迁移是带 dxpr_builder.content_migration 标签的服务（dxpr_builder.services.yml）。记录失败的批次不标记完成；失败项记入日志并保持待迁移。
1.x 和 2.x 在渲染时应用的 glazed_to_dxpr 字符串改写已移除。Glazed 名称随 2020 年 5 月的 1.0.0 弃用，假设所有 Glazed 和 Carbide 时代内容已由那些版本迁移。该改写是纯字符串替换。在内容仅提及 Glazed 的站点（支持文章、文档链接），它会改写正文并破坏链接，而不是迁移标记。存储内容仍带 Glazed 类名的站点应先运行 2.x 版本。
自定义代码的变更
字段格式
字段格式 id 为 dxpr_builder_text（标签 "DXPR Builder"，src/Plugin/Field/FieldFormatter/DxprBuilderFormatter.php），自 1.x 未变。它有一个设置 profile，按角色默认则为空，或为档案 id。请检查每个构建器字段在其视图显示仍用该格式；更新 9023 的修复仅限用该格式的字段。
钩子
dxpr_builder.api.php 记录 3.x 钩子。Glazed Builder 钩子改名如下：
| Glazed Builder 钩子 | DXPR Builder 3.x 钩子 |
|---|---|
hook_glazed_builder_classes() |
hook_dxpr_builder_classes_alter(array &$dxpr_builder_classes) |
hook_glazed_builder_buttons_folders() |
hook_dxpr_builder_element_buttons_folders_alter(array &$dxpr_element_buttons_folders) |
hook_glazed_builder_elements_folders() |
已移除；无替代钩子。 |
| 无 | hook_dxpr_builder_icon_sets_alter(array &$icon_sets)，新增。图标集在 MODULE.dxpr_icon_sets.yml 文件中声明。 |
CSS 与实用类
定位 Glazed 类名的自定义 CSS 必须改用 DXPR 名称，如 dxpr-theme-util、panel-dxpr 和 dxpr-builder。编辑器暴露的实用类通过 hook_dxpr_builder_classes_alter() 提供。
配置与部署
- 从任何已提交配置中移除
json_web_token；更新 9020 后密钥在dxpr_builder_jwtKey 实体中。该 Key 使用 Configuration 提供者，因此密钥仍导出为key.key.dxpr_builder_jwt。请将它切换为 File 或 Environment 提供者（/admin/config/system/keys），让它不进入导出。 - 配置导出现在包含两个 AI 词汇表及其术语。
- 档案在
inline_buttons和modal_buttons导出 CKEditor 5 按钮名。
故障排查
更新后内容显示不正确：
- 运行
drush cache:rebuild。 - 到
/admin/reports/dblog查看dxpr_builder通道的消息；分批迁移记录跳过的项。 - 确认每个构建器字段的视图显示仍用 DXPR Builder 格式。
- 确认主题加载 Bootstrap 5，或到
/admin/dxpr_studio/dxpr_builder/settings启用 sideload。
