activate-site

插件检查：运行 node "${PLUGIN_ROOT}/scripts/check-version.js" — 如果输出了消息，请先将其展示给用户，然后再继续。

激活 Power Pages 网站

通过 Power Platform REST API，在 Power Platform 环境中预配一个新的 Power Pages 网站。

**前提条件：**此技能需要一个通过 /create-site 创建的现有 Power Pages SPA 网站。如果网站尚不存在，请先运行该技能。

核心原则

• 根据云环境解析 URL — 切勿硬编码 API 基础 URL 或网站 URL 域名。始终根据 pac auth who 返回的 Cloud 值推导这些信息。
• 令牌处理 — Agent 只需验证用户是否已登录 Azure CLI。
• 变更前确认 — 始终向用户展示完整的激活参数，并在向 websites API 发送 POST 请求前获得明确批准。
• 保留调用方的环境 — 如果其他技能传入了 environmentUrl，请在激活前确认 PAC 和 Azure CLI 仍然指向该环境和租户。
• 调用方状态更新 — 如果 /create-site 提供了 statusPath，请在激活确认提示前后更新该文件，以便打开的模板状态页面显示何时需要用户输入。

初始请求： $ARGUMENTS

工作流

1. 阶段 1：验证前提条件 — PAC CLI 身份验证 + Azure CLI 登录 + 激活状态检查
2. 阶段 2：收集参数 — 网站名称、子域名、网站记录 ID
3. 阶段 3：确认 — 向用户展示所有参数以供批准
4. 阶段 4：激活并轮询 — 运行激活脚本（POST + 轮询预配状态）
5. 阶段 5：展示摘要 — 显示网站 URL，并建议后续步骤

---

阶段 1：验证前提条件

**目标：**确保 PAC CLI 已安装并完成身份验证，同时确认用户已登录 Azure CLI。

操作

1.1 验证 PAC CLI

运行 pac help，检查系统 PATH 中是否已安装并可用 PAC CLI。

pac help

如果命令失败（找不到命令 / 无法识别命令）：

1. 告知用户：“尚未安装 PAC CLI。你可以运行以下命令进行安装：”

   dotnet tool install --global Microsoft.PowerApps.CLI.Tool
   

2. 如果 dotnet 也不可用，请引导用户访问 https://aka.ms/PowerPlatformCLI，查看完整安装说明。

3. 安装后，再次运行 pac help 进行验证。

1.2 检查身份验证

运行 pac auth who，检查当前身份验证状态。

pac auth who

如果已完成身份验证：从输出中提取以下值：

• Environment ID — Environment ID: 后面的 GUID
• Organization ID — Organization ID: 后面的 GUID（即 Dataverse 组织 ID）
• Cloud — Cloud: 后面的值（例如 Public、UsGov、UsGovHigh、UsGovDod、China）

如果尚未完成身份验证：按照 deploy-site 的相同身份验证流程，请用户提供其环境 URL，然后运行 pac auth create --environment "<URL>"。

1.3 验证 Azure CLI 登录状态

确认用户已登录 Azure CLI：

az account show

如果未安装 az 或尚未登录：请指导用户安装 Azure CLI，并运行 az login --allow-no-subscriptions（无论用户是否拥有 Azure 订阅，此命令形式都适用 — 激活流程只需要 AAD 令牌）。

1.4 检查是否已激活

首先检查 $ARGUMENTS，确认是否包含来自其他技能的明确导入站点标识：

siteName: <name>
websiteRecordId: <guid>
environmentUrl: <url>
statusPath: <path>

当这两个值都存在时，立即设置 SITE_IDENTITY_SOURCE = "arguments"，并跳过下方的本地项目激活状态检查。该检查会从 powerpages.config.json / .powerpages-site 解析标识；使用 /create-site 激活导入的模板站点时，这些内容可能不存在或与该站点无关。继续进入阶段 2，并使用明确的标识。

当存在 environmentUrl 时，将其存储为 EXPECTED_ENVIRONMENT_URL，并在进入阶段 2 前验证当前 CLI 上下文：

node "${PLUGIN_ROOT}/scripts/validate-cli-tenant-alignment.js" --envUrl "<EXPECTED_ENVIRONMENT_URL>"

只有当 JSON 结果中的 ok: true 时才继续。此检查会将当前 PAC 环境 URL 与调用方提供的 URL 进行比对，并验证 PAC、Azure 帐户和 Dataverse 访问令牌使用的是同一租户。如果检查失败，请停止并要求用户切换 PAC 或 Azure CLI 身份验证。不要在其他环境中激活导入的 Website Record ID。

当 source 为 create-site template path 且存在 statusPath 时，将其存储为 ACTIVATION_STATUS_PATH。这是 /create-site 创建的现有模板状态文件；不要创建单独的状态页面。

当 SITE_IDENTITY_SOURCE !== "arguments" 时，运行共享激活状态脚本，检查本地项目站点是否已激活：

node "${PLUGIN_ROOT}/scripts/check-activation-status.js" --projectRoot "<PROJECT_ROOT>"

其中，<PROJECT_ROOT> 是包含 powerpages.config.json 或 .powerpages-site 文件夹的目录。 评估 JSON 结果：

• 如果 activated 为 true：告知用户其站点已在 websiteUrl 激活。建议后续步骤（阶段 5.3），然后停止——不要继续进入阶段 2。
• 如果 activated 为 false：继续进入阶段 2。
• 如果存在 error：继续进入阶段 2（不要阻止激活流程）。

当 SITE_IDENTITY_SOURCE = "arguments" 时，跳过整个本地项目状态检查，并使用提供的站点标识继续进入阶段 2。

输出

• 已安装并通过身份验证的 PAC CLI
• 已提取环境 ID、组织 ID 和 Cloud 值
• 已确认 Azure CLI 登录状态
• 已检查本地项目的激活状态，或因站点标识来自参数而跳过检查

---

阶段 2：收集参数

**目标：**确定站点名称，生成或接受子域名，并查找激活 API 调用所需的网站记录 ID。

操作

2.1 读取站点名称

如果此技能由其他技能调用，且 $ARGUMENTS 中包含明确的导入站点标识，请在发现本地项目之前使用该标识：

siteName: <name>
websiteRecordId: <guid>

当这两个值都存在时：

• 从明确提供的值设置 siteName。
• 从明确提供的值设置 websiteRecordId。
• 设置 SITE_IDENTITY_SOURCE = "arguments"。
• 跳过下方对 powerpages.config.json 的查找，并跳过阶段 2.3（pac pages list），因为调用方已解析出导入的网站记录。

如果缺少任一明确提供的值，则继续现有的本地项目发现流程。

使用 Glob 在当前目录或下一级子目录中查找 powerpages.config.json：

**/powerpages.config.json

读取该文件并提取 siteName 字段。如果未找到，请使用 AskUserQuestion 询问用户站点名称。

2.2 生成子域名建议

重要 — 此步骤为必需步骤。继续操作前，必须询问用户有关子域名的事宜。不得跳过此步骤，也不得在没有用户输入的情况下自动选择子域名。

运行子域名生成脚本，创建一个随机建议：

node "${PLUGIN_ROOT}/skills/activate-site/scripts/generate-subdomain.js"

脚本会输出类似 site-a3f2b1 的字符串。根据第 1.2 阶段获取的 Cloud 值，确定正确的站点 URL 域名：

Cloud	站点 URL 域名
Public	powerappsportals.com
UsGov	powerappsportals.us
UsGovHigh	high.powerappsportals.us
UsGovDod	appsplatform.us
China	powerappsportals.cn

🚦 关卡（plan · activate-site:2.2.subdomain）： 确认或覆盖生成的子域名。子域名是最终站点 URL 的一部分；取消操作会在任何预配调用之前退出。

向用户展示生成的子域名，并通过 AskUserQuestion 询问用户是接受该建议还是输入自己的子域名：

问题	标题	选项
您的站点子域名将为：<suggestion>（完整 URL：https://<suggestion>.<siteUrlDomain>）。您想使用此子域名还是输入自己的子域名？	子域名	使用 <suggestion>（推荐），输入自定义子域名

设置了 ACTIVATION_STATUS_PATH 时，请在调用 AskUserQuestion 前立即使用 Write 原子地覆盖该文件：

{
  "state": "running",
  "phase": "activation",
  "message": "Waiting for subdomain selection",
  "awaitingInput": true,
  "inputPrompt": "Choose the site subdomain in the agent terminal."
}

用户回复后，立即再次覆盖该文件，使 toast 消失：

{
  "state": "running",
  "phase": "activation",
  "message": "Preparing site activation",
  "awaitingInput": false
}

如果用户取消提示，请在停止前清除 awaitingInput。如果子域名冲突并返回此步骤，请应用相同的状态更新。

如果选择自定义：用户通过“Other”自由文本输入提供自己的子域名。验证子域名仅包含小写字母、数字和连字符，且长度为 3-50 个字符。

2.3 获取网站记录 ID

当 SITE_IDENTITY_SOURCE = "arguments" 且 websiteRecordId 已设置时，跳过此步骤。

运行 pac pages list 获取网站记录 ID：

pac pages list

解析输出，查找与站点名称匹配的网站记录。提取 Website Record ID（GUID）。如果 pac pages list 未返回结果或命令不可用，则将 websiteRecordId 设为 $null — API 将创建新的网站记录。

输出

• 已确定站点名称（来自配置文件或用户输入）
• 已选择子域名（生成或自定义）
• 已解析网站记录 ID（GUID 或 null）

---

第 3 阶段：确认

目标： 向用户展示所有激活参数，并在调用 API 前获得明确批准。

操作

🚦 关卡（final · activate-site:3.confirm）： 调用激活 API 前的最后确认。回显所有激活参数；取消操作会在预配前正常退出。每次调用技能时都会重新触发。 当 plan-alm 编排多阶段激活（Staging + Production）时，它会在每个阶段调用一次 activate-site — 每次调用都会重新触发此关卡，并使用各自的 siteName、subdomain 和目标环境。对 Staging 激活的同意不涵盖 Production。每个阶段的站点 URL 都是单独的上线决定（面向不同受众，时间也不同）。

使用 AskUserQuestion 向用户展示所有激活参数：

问题	标题	选项
已准备好使用以下设置激活您的 Power Pages 站点：\n\n- 站点名称：<siteName>\n- 子域名：<subdomain>.powerappsportals.com\n- 环境 ID：<environmentId>\n\n继续激活吗？	激活	是，激活站点（推荐），否，取消

如果选择“否”：停止技能，并告知用户之后可以重新运行。

如果选择“是”：继续第 4 阶段。

输出

• 用户已明确批准激活参数

---

第 4 阶段：激活并轮询

目标： 向 Power Platform 网站 API 发送 POST 请求以开始预配，轮询直至完成，并报告结果。

操作

4.1 运行激活脚本

运行共享激活脚本，并传入在阶段 1–2 中收集的所有参数：

node "${PLUGIN_ROOT}/skills/activate-site/scripts/activate-site.js" --siteName "<siteName>" --subdomain "<subdomain>" --organizationId "<organizationId>" --environmentId "<environmentId>" --cloud "<cloud>" --websiteRecordId "<websiteRecordId>"

如果 --websiteRecordId 为 null 或空值，请省略该参数。

将脚本的 JSON 结果视为权威激活结果。在前台运行脚本，并为 Bash 设置至少 360 秒的超时时间；在脚本退出前，不要继续阶段 5。不要启动单独的就绪状态轮询。

4.2 处理结果

评估 JSON 输出：

status 值	statusCode / errorCode	操作
Succeeded	—	配置完成。结果包含 siteUrl。继续阶段 5。
Failed	400 + SubdomainConflict（或错误消息提及子域名）	子域名已被占用。返回阶段 2 的操作 2.2，使用新的子域名，然后重新运行脚本。
Failed	401	令牌已过期。请用户运行 az login --allow-no-subscriptions 并重试。
Failed	403	权限不足。告知用户需要“Power Pages site creator”或“System Administrator”角色。
Failed	409	网站已存在。告知用户，并建议改用 /deploy-site。
Failed	429 或 5xx	请求过多或服务器错误。等待 5 秒，然后重新运行脚本一次。
Failed	其他	向用户展示错误，并协助排查。
Running	—	5 分钟后配置仍在进行。告知用户这可能需要最多 15 分钟，并建议检查 Power Platform 管理中心。
error 字段	—	前置条件失败（缺少参数、没有令牌）。向用户展示错误，并协助排查。

激活脚本返回 Succeeded 后，不要针对 siteUrl 启动第二个后台轮询。HTTP 和 DNS 传播可能会落后于配置完成；请在阶段 5 中说明这一点，而不是留下可能触发新一轮助手对话的命令。如果意外启动了额外的可访问性轮询，请在展示激活摘要前将其停止。

输出

• 已确认配置状态（Succeeded，包含 siteUrl；Failed，包含错误详情；或 Running，包含超时提示）

---

阶段 5：展示摘要

目标： 向用户显示最终网站 URL，并建议后续步骤。

操作

5.1 显示结果

使用脚本输出中的 siteUrl 展示激活摘要：

Power Pages site activated successfully!

  Site Name:  <siteName>
  Site URL:   <siteUrl>
  Environment: <environmentName> (<environmentId>)
  Status:     Provisioned

脚本已解析出适用于相应云环境的网站 URL 域名，因此请直接使用 siteUrl 值。

5.1b 写入 docs/alm/last-activate.json 标记

对于渲染后的 ALM 计划等使用方（Manual 路径中每个目标的 Activate 步骤），请写入结构化标记以记录激活后的状态。请先确保 docs/alm/ 目录存在：

node -e "require('fs').mkdirSync('docs/alm',{recursive:true})"
# Determine the stage label this activation was for. The upstream ALM context
# (e.g. the user running this after import-solution) supplies it as "Staging"/
# "Production"; standalone invocations may leave it null — refreshActivateSite
# falls back to env-URL matching against planData.stages[].envUrl.
node -e "require('fs').writeFileSync('docs/alm/last-activate.json', JSON.stringify({
  stageName: <stageNameOrNull>,
  siteName: '<siteName>',
  siteUrl: '<siteUrl>',
  websiteRecordId: '<websiteRecordId>',
  environmentUrl: '<envUrl>',
  environmentId: '<environmentId>',
  activatedAt: new Date().toISOString(),
  status: 'Activated',
  cloud: '<cloud>',
}, null, 2))"

即使激活属于“已激活”检测（阶段 1.4），仍需写入标记——无论是在本次运行中执行了激活，还是激活状态已存在，渲染后的计划都应反映“此阶段已在 https://... 上线”。设置 status: 'AlreadyActivated'，并使用阶段 1.4 检查中已有的 siteUrl。

5.2 记录技能使用情况

参考：${PLUGIN_ROOT}/references/skill-tracking-reference.md

按照参考文档中的技能跟踪说明，记录此技能的使用情况。使用 --skillName "ActivateSite"。

5.2b 刷新 ALM 计划（如果存在）

node "${PLUGIN_ROOT}/scripts/lib/refresh-alm-plan-data.js" \
  --projectRoot "." \
  --phase activate-site \
  --stageName "{stageNameOrEmpty}" \
  --render

{stageNameOrEmpty} 是 Agent 正在激活的 Manual 路径目标阶段标签（例如 Staging、Production），由用户说明或根据目标环境推断得出。如果未知，则传入空字符串；refreshActivateSite 会回退到将 docs/alm/last-activate.json 中的 environmentUrl 与 planData.stages[].envUrl 进行 URL 匹配，因此单独调用时也能记录激活信息。

该辅助程序会读取 docs/alm/last-activate.json，在 planData.activations[stageName] 中写入一条针对目标的记录（siteUrl、status、activatedAt），并重新生成 docs/alm-plan.html，使匹配的 Activate site in {stageName} 清单步骤显示带有实时站点 URL 的 ACTIVATED 徽章。当 docs/.alm-plan-data.json 不存在时（独立运行，不属于 ALM 计划），该辅助程序会返回 ok:false，作为软性空操作。

引导用户进入下一步（由用户驱动流程）。 辅助程序的 stdout JSON 包含 nextStep: { name, skill: string | null } | null。当该值非 null 时，根据 skill 进行分支处理：当 skill 非 null 时，告诉用户 “计划已更新。计划中的下一步：{nextStep.name} → 准备就绪时运行 {nextStep.skill}。”；当 skill 为 null（例如 Finalize 这样的内部步骤，没有用户命令）时，只说出步骤名称 — “计划已更新。计划中的下一步：{nextStep.name}。” — 绝不要输出 run null。当该值为 null 或辅助程序返回 ok:false 时，不要提及下一步。绝不要自动调用下一项技能 — 执行流程由用户驱动。

5.3 建议后续步骤

总结后，建议：

• 测试站点：/test-site — 验证站点是否正常加载，以及 API 调用是否正常工作
• 设置 ALM：/power-pages:plan-alm — 设置 ALM，将此站点发布到预发布或生产环境（创建解决方案，配置部署管道或导出/导入策略）
• 设置数据模型：/setup-datamodel
• 添加示例数据：/add-sample-data
• 在浏览器中通过预配的 URL 查看站点（注意：DNS 传播可能需要几分钟）

输出

• 呈现包含站点 URL 的激活摘要
• 向用户建议后续步骤

---

重要说明

进度跟踪

开始时使用 TaskCreate 跟踪各阶段的进度：

任务	说明
Phase 1	验证先决条件 — PAC CLI 身份验证、云环境检测、Azure CLI 登录、激活状态检查
Phase 2	收集参数 — 站点名称、子域名、website 记录 ID
Phase 3	确认 — 用户批准激活参数
Phase 4	激活并轮询 — 运行激活脚本，处理结果
Phase 5	呈现摘要 — 显示站点 URL 和后续步骤

每完成一个阶段，都使用 TaskUpdate 将相应任务标记为已完成。

关键决策点

• Phase 1.2：如果尚未通过身份验证，必须先完成身份验证才能继续 — 不可跳过。
• Phase 1.4：如果站点已激活，则提前停止 — 不要继续进入 Phase 2。
• Phase 2.2：用户可以接受生成的子域名，也可以提供自定义子域名 — 验证自定义输入。
• Phase 3：用户必须明确批准激活。如果用户拒绝，则彻底停止该技能。
• Phase 4.2：如果返回 400（子域名已被占用），则返回 Phase 2 的操作 2.2 并重新运行脚本 — 不要中止。
• Phase 4.2：如果返回 409（站点已存在），则改为引导用户使用 /deploy-site。
• Phase 4.2：如果超时（运行 5 分钟后仍处于 Running 状态），不要视为失败 — 建议用户检查管理中心。

从 Phase 1：验证先决条件开始