migrate-bootstrap

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js" — 如果有输出消息，请在继续操作前展示给用户。

将非 SPA Power Pages 网站从 Bootstrap 3 迁移到 Bootstrap 5

指导用户将非 SPA / 原生 Power Pages 网站从 Bootstrap 3 迁移到 Bootstrap 5。采用系统化方法：验证工具链、获取并备份网站、评估范围、运行 pac pages bootstrap-migrate 引擎、检查变更报告、应用引擎只能标记出来的剩余修复、上传（这会自动启用运行时标志）、验证并确认。

核心原则

• 仅适用于非 SPA 网站：此技能适用于非 SPA Power Pages 网站（Liquid Web 模板、*.webtemplate.source.html、*.html/.aspx/.ascx、*.css、sitesetting.yml）。不适用于 SPA 网站（React/Vue/Angular/Astro）——这些网站从来不是基于 Bootstrap 3 构建的。如果目标是 SPA 网站，请停止并告知用户此技能不适用。

• 引擎负责大部分工作；你负责剩余部分：pac pages bootstrap-migrate 会确定性地应用广为人知的类名重命名。此技能的价值在于协助处理引擎只会记录而不会应用的层级 / CSS 变更（参见 references/bootstrap-v5-manual-fixes.md）。

• 非破坏性，并保留还原点：引擎会写入一个新的 <folder>V5 副本，绝不会就地修改源文件。即便如此，在进行任何操作前仍要对源文件夹创建快照（git）。

• 协助并标记——绝不静默重写：剩余修复需要识别 Liquid，可能会破坏布局。逐类别征得同意后再应用；遇到有歧义的情况（例如 Liquid 条件语句）时，应标记出来交由用户处理，而不是自行猜测。

• 通过 pac-log.txt 验证运行时标志切换：pac pages upload 会自动切换服务器端的 Bootstrap 5 标志，但 CLI 会记录并吞掉切换结果。切勿仅凭上传的退出代码判断。权威记录是 PAC 诊断日志（pac telemetry status → pac-log.txt）；请搜索 BootstrapV5UploadPostProcessor。切换操作要求门户处于活动状态——如果网站记录没有已预配的网站，日志会显示 no portal found 并跳过切换。

• 使用 TaskCreate/TaskUpdate：开始工作前，先创建包含全部 8 个阶段的待办事项列表。

初始请求： $ARGUMENTS

---

阶段 1：验证先决条件

目标：确保已安装 PAC CLI、用户已通过身份验证、目标环境已确认，并且所需命令均可用。

操作：

1. 创建包含全部 8 个阶段的待办列表（参见进度跟踪）。

2. 运行 pac help，确认已安装 PAC CLI，且其位于 PATH 中。如果未安装，请告知用户访问 https://aka.ms/PowerPlatformCLI（dotnet tool install --global Microsoft.PowerApps.CLI.Tool） 并重新验证。

3. 运行 pac auth who。如果尚未通过身份验证，请通过 AskUserQuestion 询问环境 URL， 然后运行 pac auth create --environment "<URL>" 并重新验证。记录环境名称、URL 和 ID。

🚦 关卡（同意 · migrate-bootstrap:1.confirm-env）： 在进行任何下载、迁移或上传之前，确认目标环境。对错误的环境运行迁移会造成破坏，因此此确认为必需步骤。

4. 与用户确认目标环境（AskUserQuestion：使用此环境／通过 pac org list + pac org select 选择其他环境）。

5. 探测命令是否可用——以下两个动词都必须可用：

   pac pages help
   

   确认动词列表中包含 bootstrap-migrate 和 upload。如果缺少任一命令（此 CLI 构建版本／租户未启用该功能），请停止并告知用户：这些命令可用之前，无法继续迁移。

6. 定位 PAC 诊断日志——现在记录其路径；在阶段 7 中需要用它验证标志切换：

   pac telemetry status
   

   它会输出 The diagnostic logs can be found at: <…>\logs\pac-log.txt。这是跨所有 pac 运行的滚动日志，也是 Bootstrap V5 标志切换的权威记录。注意：pac pages upload 不会写入单文件夹日志——pac-log.txt 是其后处理程序记录标志切换结果的唯一位置。设置 PAC_LOG = <该路径>。

输出：已验证 PAC CLI、已通过身份验证的会话、已确认的环境、已确认 bootstrap-migrate 和 upload 可用，并已记录 PAC_LOG 路径。

---

阶段 2：获取网站并备份

目标：获取待迁移的非 SPA 网站的本地副本，并建立还原点。

操作：

2.1 定位或下载网站

• 如果用户提供了本地网站文件夹路径（或 $ARGUMENTS 中指定了路径）：验证该路径存在， 且看起来是已下载的非 SPA 网站（包含 website.yml 和 sitesetting.yml）。将其用作 SITE_FOLDER。

• 否则：列出可用网站并下载选定的网站。

  pac pages list
  

  🚦 关卡（计划 · migrate-bootstrap:2.1.select-site）： 如果存在多个网站，请选择要下载的网站。取消不会更改任何内容。

  通过 AskUserQuestion 列出网站，然后下载选定的网站：

  pac pages download --path "<SITE_FOLDER>" --webSiteId "<WEBSITE_ID>"
  

  将下载的目录用作 SITE_FOLDER。

确认这是一个非 SPA 网站，而不是 SPA 网站。SPA 项目包含 powerpages.config.json 和框架的 package.json；非 SPA 网站包含 website.yml、sitesetting.yml 和 *.webtemplate.source.html 文件。如果这是 SPA 网站，请停止——此技能不适用。

2.2 确认站点已激活（而不只是存在网站记录）

pac pages list 显示的是网站记录（adx_website）。网站记录可能存在，但背后没有已预配／已激活的 Power Pages 站点（门户）——例如由数据导入／克隆创建、已停用或成为孤立记录。第 7 阶段的标志切换（SetPortalBootstrapV5Enabled）针对的是门户，而不是网站记录，因此，如果没有已激活的门户，切换操作会静默跳过，线上站点也无法呈现——如果现在不检查，等到上传后才会发现这一点。

从 websitebinding.yml（adx_sitename）解析站点 URL，并检查最终状态码（-L 会跟随重定向，因此登录／规范主机重定向会解析为其实际状态码）：

curl -sL -o /dev/null -w "%{http_code}" "https://<adx_sitename>/"

• 2xx，或最终解析为 2xx／3xx 的重定向 → 门户已激活；继续操作。私有或受保护的站点会正常重定向到登录页或规范主机，因此，解析后的 3xx 表示站点已激活，并非失败。

• 4xx／5xx → 仅凭状态码无法确定。私有站点可能返回非 200 状态码，但并不代表未激活，因此不要仅凭状态码断定“未激活”——请获取错误正文（或在浏览器中打开 URL），查看是否包含未激活特征：

  curl -sL "https://<adx_sitename>/" | head -c 4000
  

如果正文显示 Dataverse 连接空引用错误（Object reference not set …／CrmOnlineOrganizationService.ToOrganizationService），或者 URL 在浏览器中无法呈现门户页面，则站点很可能尚未激活。这也正是第 7 阶段的标志切换记录 no portal found for website <id> via Power Pages API 的原因。如果 4xx／5xx 不包含此特征，则更可能是已激活站点上的身份验证拦截或暂时性错误——请按已激活处理，并告知用户，而不要因此阻止操作。

如果确认站点未激活，请停止操作，并告知用户先激活／预配站点（通过 Power Pages 管理中心，或使用 /power-pages:activate-site 技能）。将内容迁移到尚未激活的网站仍会上传，但运行时标志无法切换，也无法验证站点。

2.3 创建源站点快照

在迁移前创建还原点：

cd "<SITE_FOLDER>"
git init -q && git add -A && git commit -q -m "Pre-migration snapshot (Bootstrap 3)"

如果该文件夹已经是 git 仓库，只需提交所有待处理的更改，以保存迁移前的状态。

输出：已解析 SITE_FOLDER，确认不是 SPA，且已提交源站点快照。

---

第 3 阶段：迁移前评估

目标：通过清点 Bootstrap 3 的使用情况并标记风险区域，在运行引擎前明确预期。

操作：

1. 使用 Grep 扫描站点中的 Bootstrap 3 标记，范围为 *.html、*.aspx、*.ascx、*.css：

   • 组件类：panel、navbar-header、img-responsive、btn-block、pull-left|pull-right、 col-(xs|sm|md|lg)-、glyphicon、label-、page-header、pager、data-toggle|data-dismiss。
   • 统计受影响的文件数，并粗略计算各类别的出现次数。

2. 标记风险区域：

   • 大量自定义 CSS（包含非 Bootstrap 选择器的大型 .css 文件）——不会自动转换。
   • 与 Liquid 交织的标记（类名周围有 {% ... %}、条件下拉菜单）——需要审查。

3. 提供简洁的范围摘要并明确预期：

   “这是一次辅助式迁移。引擎会自动应用常见的 Bootstrap 3 → 5 类名替换。有些更改（网格层级、导航栏结构、面板／页面标题／分页器样式）只能标记出来——我会在第 6 阶段协助处理。视觉效果不保证完全一致，你需要对结果进行 QA。”

输出：已提供范围摘要；用户了解这是辅助式迁移，而非一键完成。

---

阶段 4：运行迁移引擎

目标：生成迁移后的 <folder>V5 副本。

操作：

🚦 关卡（同意 · migrate-bootstrap:4.run-engine）： 运行 pac pages bootstrap-migrate 前必须获得明确同意。引擎会写入一个新的 <SITE_FOLDER>V5 副本，绝不会编辑源文件，因此取消操作不会造成任何更改。

1. 获得运行引擎的明确同意（AskUserQuestion："Run the Bootstrap 5 migration on <SITE_FOLDER>? This creates a new <SITE_FOLDER>V5 copy and does not modify the original."）。

2. 运行：

   pac pages bootstrap-migrate --path "<SITE_FOLDER>"
   

3. 确认引擎已生成 <SITE_FOLDER>V5，其中包含：

   • 已重写的 *.html / *.js / *.aspx / *.ascx / *.css 文件
   • 已替换的 bootstrap.min.css（Bootstrap 5）
   • 已更新并包含 Site/BootstrapV5Enabled 记录的 sitesetting.yml
   • logs.txt 和各文件对应的 *-diff.json

   完整的输出约定请参阅 references/migration-engine-reference.md。设置 MIGRATED_FOLDER = <SITE_FOLDER>V5。

输出：已生成 MIGRATED_FOLDER，其中包含已重写的文件、已替换的 CSS、logs.txt 和差异文件。

---

阶段 5：审查变更报告

目标：将 logs.txt 转换为结构化的分组摘要，突出显示需要手动处理的工作。

操作：

1. 阅读 <MIGRATED_FOLDER>/logs.txt，并按照引擎参考文档中的格式进行分类。报告开头包含三个文件列表——无变更、自动应用（替换/添加/删除）和层级变更（仅记录）——后面接着是逐文件的详细信息块（Total Number of Changes:<n> + 变更行）。使用 Grep 统计并定位相关工作：

   • 对 Need hierarchy change 使用 Grep → 获取需要手动处理的层级项目（通常为 零项）。
   • 最可靠的残留项信号来自 V5 输出本身：对迁移后的 *.html 使用 Grep 查找残留的 Bootstrap 3 标记（page-header、glyphicon、label-(info|danger|primary)、panel-(primary|success|info|warning|danger)、btn-block、navbar-header）。引擎留下的任何内容，都是阶段 6 中需要处理的工作。

2. 提交摘要：

   • 各类别的数量。
   • 包含层级变更和依赖 CSS 的上下文类（例如 panel-primary）的文件列表——这些都是阶段 6 的工作项。

输出：分组变更摘要；明确列出残留的手动处理项。

---

阶段 6：AI 辅助处理残留项

目标：在 MIGRATED_FOLDER 文件中，应用引擎标记但无法安全自动应用的结构/CSS 修复。

参考方案：references/bootstrap-v5-manual-fixes.md

操作：

1. 按类别对残留项分组（网格层级、导航栏结构、面板/卡片样式、page-header、pager、btn-block、Liquid 边缘情况、局部路径）。

🚦 关卡（进度 · migrate-bootstrap:6.residual-fixes）： 应用每项残留修复前，须按类别获得同意。更改仅作用于 V5 副本，并按类别提交；取消操作不会造成任何对外可见的更改。

2. 对于每个类别，按类别获得同意（AskUserQuestion："Apply the <category> fixes to <N> file(s)?"）。获得同意后：
   • 使用 Edit 应用手动修复参考文档中的方案。
   • 根据文件的 *-diff.json 重新检查受影响的行，确认没有影响已自动应用的变更。
   • 按类别提交：git -C "<MIGRATED_FOLDER>" add -A && git -C "<MIGRATED_FOLDER>" commit -m "v5 fixes: <category>" （如有需要，先将 V5 文件夹初始化为仓库）。在 add 和 commit 两者中使用 -C "<MIGRATED_FOLDER>"，确保命令针对 V5 副本运行，而不是当前工作目录。
3. 对于含义不明确或与 Liquid 纠缠的情况，不要重写——列出文件及行号，并向用户建议手动更改方式。

输出：按类别应用（或标记）残留修复，并分别提交；列出含义不明确的项目。

---

阶段 7：上传、自动启用运行时标志并验证

目标：上传迁移后的网站（这会自动切换服务器端的 Bootstrap 5 标志），并 验证该标志确实已生效。

操作：

7.1 上传前检查清单

自动切换标志的操作取决于 MIGRATED_FOLDER 中的两个文件：

• website.yml 必须包含有效的 adx_websiteid。
• sitesetting.yml 必须包含值为 true 的 Site/BootstrapV5Enabled。

验证两项（Grep/Read）。如果缺少任何一项，切换标志的操作会静默跳过——请在上传前修复。

7.2 最终确认关卡，然后上传

🚦 关卡（最终 · migrate-bootstrap:7.2.upload）： 首次对外变更前的最终确认。pac pages upload 会发布 Bootstrap 5 网站并自动启用运行时标志。在上传前取消，不会影响线上网站。

这是首次对外变更。请明确征得同意（AskUserQuestion：“将 <MIGRATED_FOLDER> 上传到环境 <ENV_NAME>？这会发布 Bootstrap 5 网站并启用 Bootstrap 5 运行时。”）。获得同意后：

pac pages upload --path "<MIGRATED_FOLDER>"

对于非 SPA 网站，请将 --modelVersion 保持为默认值（Standard）。pac pages upload 会上传内容，并且通过其后处理器自动切换服务器端的 Bootstrap 5 标志（由 Site/BootstrapV5Enabled=true 设置触发）。

请使用 pac pages upload，不要使用 upload-code-site（这是 SPA 路径，会损坏非 SPA 网站）。

7.3 验证标志切换（必做）

CLI 会记录并吞掉标志切换结果，因此上传成功并不能证明运行时已启用 Bootstrap 5。权威记录是 pac-log.txt（阶段 1 中记录的 PAC_LOG 路径），而不是线上网站。请先检查日志——几秒内即可得出明确结论；线上网站可能会造成误导（未激活的网站会返回 500，这与 Bootstrap 无关）：

# grep the PAC diagnostic log for the post-processor's result (most recent run is last)
grep -iE "BootstrapV5UploadPostProcessor|SetPortalBootstrapV5Enabled" "<PAC_LOG>"

可能出现以下三种结果：

日志行	含义	操作
Set … BootstrapV5Enabled / success（INF）	已应用切换	✅ 继续；可选择在线上网站确认。
Skipping SetPortalBootstrapV5Enabled: no portal found for website <id> via Power Pages API（WRN）	没有活动门户——未尝试切换	❌ 网站尚未激活。请激活网站（参见阶段 2.2 / /power-pages:activate-site），然后重新运行 pac pages upload。
后处理器返回 ERR/异常	已尝试但失败（身份验证/HTTP）	❌ 重新确认 7.1 中的清单和权限，然后重新运行上传。

然后在线上网站进行佐证（仅当日志显示已应用时才有意义）：重新渲染已知页面，确认 Bootstrap 5 bundle 已提供；或通过 Power Pages 管理界面再次确认门户的 Bootstrap V5 已启用状态。如果线上 URL 返回带有 Dataverse 连接空引用（CrmOnlineOrganizationService.ToOrganizationService）的 5xx，这就是**“网站尚未激活”**的特征——请将其与日志中的 no portal found 行对应起来，而不要将其视为暂时性重启问题。

输出：已上传迁移后的网站；已从 pac-log.txt 读取标志切换结果（已应用 / 因没有门户而跳过 / 出错），并在已应用时在线上网站确认。

---

阶段 8：验证并总结

目标：确认线上网站在 Bootstrap 5 上正常运行，并记录结果。

操作：

1. 运行时冒烟测试 — 使用 /test-site 对网站 URL 执行测试，爬取关键页面、验证页面是否正常呈现，并捕获控制台／网络错误。
2. 迁移前后视觉检查 — 抽查流量最高的页面（首页、导航栏、任何面板／卡片、表单、分页），检查迁移是否引入布局回归。
3. 记录技能使用情况 — 按照 ${PLUGIN_ROOT}/references/skill-tracking-reference.md 操作，并传入 --projectRoot "<MIGRATED_FOLDER>"（包含 powerpages.config.json 的文件夹）和 --skillName "MigrateBootstrap"。只有当项目是 SPA 网站（存在 .powerpages-site/site-settings/）时才会写入跟踪记录；对于非 SPA／原生下载，脚本会静默退出且不执行任何操作——这是预期行为，因此应无条件调用，不要将不执行操作视为错误。如果写入了跟踪文件，请将其纳入最终提交。
4. 总结 — 展示：
   • 按类别列出变更的文件（自动应用、辅助处理、标记为需手动处理）。
   • 仍需人工关注的遗留事项。
   • 确认已启用 Bootstrap 5 运行时标志。
   • 源快照（用于回滚）和 MIGRATED_FOLDER 的位置。
5. 建议后续步骤 — 手动 QA 检查、重新运行 /test-site，以及（如果要推广到多个环境）使用 ALM 技能（/plan-alm）。

输出：网站已通过 Bootstrap 5 验证，使用情况已记录，并已提供总结和遗留事项列表。

---

重要说明

所有阶段均须遵守

• 使用 TaskCreate/TaskUpdate 跟踪每个阶段的进度。
• 在关键决策点征求用户确认（见下文）。
• 清楚呈现错误 — 展示相关命令输出，并在建议修复方案前加以说明。
• 上传后不自动回滚 — 依靠阶段 2 中的源快照；报告失败并继续处理／分类，而不是自动还原。

关键决策点（等待用户确认）

1. 阶段 1：如果尚未通过身份验证，获取环境 URL；确认／切换目标环境。
2. 阶段 2：如果有多个网站，确认要下载哪个网站；确认这是非 SPA（非代码）网站。
3. 阶段 4：征得同意后运行迁移引擎。
4. 阶段 6：应用遗留修复前，按类别征得同意。
5. 阶段 7：上传前（对外可见操作）征求最终同意。

进度跟踪

开始阶段 1 前，使用 TaskCreate 创建包含所有阶段的任务列表：

任务主题	activeForm	描述
验证先决条件	正在验证先决条件	PAC CLI、身份验证、环境和命令可用性（bootstrap-migrate、upload）
获取网站并备份	正在获取网站	下载／定位非 SPA 网站；创建源快照
迁移前评估	正在评估范围	清点 Bootstrap-3 用法；标记自定义 CSS／Liquid 风险
运行迁移引擎	正在运行迁移	pac pages bootstrap-migrate → <folder>V5
检查变更报告	正在检查报告	解析 logs.txt；按自动应用与层级／手动处理分类
应用遗留修复	正在应用修复	针对标记出的层级／CSS 项，按类别进行辅助修复
上传并验证标志	正在上传并验证	pac pages upload；验证 Bootstrap 5 运行时标志已切换
验证并总结	正在验证	/test-site、视觉检查、记录使用情况、总结

开始每项任务时，通过 TaskUpdate 将状态标记为 in_progress；完成时标记为 completed。

---

从阶段 1 开始：验证先决条件