force-link-environment

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

force-link-environment

将开发或目标环境与 Power Platform Pipelines 主机的关联从一个主机迁移到另一个主机。当 deploymentenvironments 创建失败并提示 "this environment is already associated with another pipelines host" 时，这是有文档记录的补救方法；有意在主机之间迁移环境时，这也是合适的工具。

Microsoft Learn（权威依据）： 使用 Force Link 将环境关联到新主机

此技能会进行哪些更改

在目标主机（用户想要使用的新主机）中：

• 将现有的 deploymentenvironments 记录标记为 BAP 环境的活动戳记。
• 重新运行验证；验证成功后，validationstatus 将变为 Succeeded（200000001）。

在先前的主机（环境之前关联的主机）中：

• 对应的 deploymentenvironments 行将被解除关联。其 validationstatus 将保持过时状态，直到在先前主机的 UI 中刷新。
• 之前可通过该环境运行管道的制作者将无法再通过此环境访问先前主机中的这些管道。

再次从先前主机运行 Force Link 即可撤销此操作。

阶段 1.5 — Microsoft Learn 依据核实（必需）

在进行任何 Dataverse 调用之前，通过 mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch 获取上述文档，刷新 Agent 的依据。如果文档说明了行为变更（例如新增权限要求或新的警告文本），请在继续前告知用户。通用模式请参阅 ${PLUGIN_ROOT}/references/alm-docs-grounding.md。

阶段

#	阶段	输出
1	前提条件	主机环境的 Azure CLI 令牌；已通过身份验证的 PAC CLI
1.5	MCP Learn 依据核实	确认 Force Link / ManageEnvironmentStamp 的当前行为
2	确定主机 + 开发环境	hostEnvUrl、目标主机的 deploymentEnvironmentId、源 BAP 环境 GUID
3	解析 deploymentenvironments 记录	新主机上已有的记录，或新创建的记录
4	确认破坏性操作	通过 AskUserQuestion 明确征得用户同意
5	执行 Force Link	ManageEnvironmentStamp 返回 204 + 验证后状态为 Succeeded
6	写入标记 + 摘要	docs/alm/last-force-link.json + 人类可读的摘要

在阶段 1 开始时，使用 TaskCreate 创建所有任务。开始执行时将每项标记为 in_progress，完成后标记为 completed。

---

阶段 1 — 前提条件

使用共享验证器：

node "${PLUGIN_ROOT}/scripts/lib/verify-alm-prerequisites.js"

具体要求：

• PAC CLI 身份验证 — pac env who 必须报告已通过身份验证的环境（用于 --dev-env 自动发现）。
• Azure CLI 身份验证 — az account show 执行成功。
• 主机范围的令牌 — 调用方必须在目标主机（环境将要关联到的主机）上拥有 Deployment Pipeline Administrator 角色。否则，ManageEnvironmentStamp 将返回 403。

使用主机的 Dataverse URL 作为资源，通过 Azure CLI 获取主机令牌。复用 scripts/lib/validation-helpers.js 中的 getAuthToken。

阶段 1.5 — MCP Learn 依据核实

调用：

mcp__plugin_power-pages_microsoft-learn__microsoft_docs_fetch(url=
  "https://learn.microsoft.com/en-us/power-platform/alm/custom-host-pipelines")

继续前，确认 "Using Force Link…" 部分当前列出的警告。如果该部分现在提到了此技能未涵盖的新前提条件或回滚限制，请告知用户。

Phase 2 — 确定主机和开发环境

🚦 Gate（plan · force-link-environment:2.host-url）： 当参数／标记解析路径均未找到结果时，选择目标主机环境 URL。仅在“没有 --host 参数、没有 last-host-check.json、没有 last-pipeline.json”的分支中触发（下方步骤 4）。

触发条件： Phase 2 解析顺序中的步骤 1–3 均未返回值。 询问原因： 自动选择错误的主机，会针对错误的租户运行 ManageEnvironmentStamp，并在未经同意的情况下不可逆地移动印章。 取消后： 无任何影响——尚未调用 API。

🚦 Gate（plan · force-link-environment:2.dev-env）： 当缺少 --dev-env 参数且 pac env who 未能确认时，选择（或粘贴）源开发环境的 BAP 环境 GUID。仅在“没有参数且未确认”的分支中触发（下方步骤 3）。

触发条件： Phase 2 中 BAP-GUID 解析步骤 1–2 均未返回值。 询问原因： 自动选择错误的开发环境，会将其他环境重新链接到新主机——错误环境的创建者将失去管道访问权限。 取消后： 无任何影响——尚未调用 API。

hostEnvUrl 的解析顺序：

1. 如果提供了 --host <url> 参数，则使用该参数。
2. docs/alm/last-host-check.json（由 ensure-pipelines-host 写入）——读取 finalHostEnvUrl。
3. docs/alm/last-pipeline.json——读取 hostEnvUrl。
4. 通过 AskUserQuestion 提示用户。

源开发环境 BAP 环境 GUID 的解析顺序：

1. 如果提供了 --dev-env <guid> 参数，则使用该参数。
2. pac env who（当前 PAC CLI 环境）——但只有在用户确认这是要重新链接的环境时才使用。
3. 通过 AskUserQuestion 提示用户。

Phase 3 — 在新主机上解析 deploymentenvironments 记录

此阶段的目标： 获取 deploymentEnvironmentId（新主机的记录 ID），无论该记录已存在、刚刚创建，还是在 Failed 状态下创建。没有该 GUID，Phase 5 就无法运行 Force Link。

Step 3.1 — 按 BAP 环境 GUID 查找

GET {hostEnvUrl}/api/data/v9.1/deploymentenvironments?$filter=environmentid eq '{bapEnvId}'&$select=deploymentenvironmentid,name,environmenttype,validationstatus,errormessage

结果	操作
命中一条记录，validationstatus = 200000001（Succeeded）	已链接到此主机。跳转至 Phase 6，显示无操作摘要；无需 Force Link。
命中一条记录，validationstatus = 200000002（Failed）	这是“已关联到另一个管道主机”的状态。记录 deploymentenvironmentid 和 errormessage。带着这些值跳转至 Phase 4。
命中一条记录，validationstatus = 200000000（Pending）	短暂等待（3–5 秒）后重新查询。如果约 20 秒后仍为 Pending，则中止并提示“验证仍在进行中；请稍后重试”。
未命中任何记录	继续执行步骤 3.2——需要先创建记录。

步骤 3.2 — 在新主机上创建记录（当步骤 3.1 返回 0 条结果时）

node "${PLUGIN_ROOT}/scripts/lib/create-deployment-environment.js" \
  --hostEnvUrl <hostEnvUrl> \
  --token <hostToken> \
  --name "<display name>" \
  --bapEnvId <bapEnvId> \
  --environmentType <200000000|200000001>

该辅助程序会轮询 validationstatus，并在状态为 Failed 时 抛出错误，且不会在错误载荷中返回新记录的 GUID。需要处理以下三种结果：

辅助程序结果	操作
成功返回，且 validationStatus = Succeeded	记录已完全关联。跳到阶段 6 — 无需 Force Link。
抛出的错误消息包含 "already associated with another pipelines host"（或类似的主机关联措辞）	记录已在 Failed 状态下创建，但辅助程序的错误没有显示新 GUID。重新执行步骤 3.1 的 GET，以恢复刚创建记录的 deploymentenvironmentid，然后使用该 ID 和捕获的 errormessage 继续阶段 4。不要重试创建 — 否则会记录重复的 name。
抛出其他任何错误消息	原样显示错误并中止。Force Link 不是正确的工具 — 这是另一种故障（例如，创建时出现 403 = 调用方在主机上缺少角色；400 = bapEnvId 无效）。

为什么需要重新查询： create-deployment-environment.js 在后续调用时具有幂等性（会通过 findExistingByBapId 提前结束），但在首次调用遇到 Failed 验证时，它会在执行返回路径之前抛出错误。按 environmentid eq '{bapEnvId}' 重新查询是标准的恢复方式 — 步骤 3.1 使用的也是同一查询。

此阶段结束后，必须获得非空的 deploymentEnvironmentId。如果没有，请中止阶段 4，并清楚说明“无法解析新主机上的记录”。

阶段 4 — 确认破坏性操作

🚦 关卡（同意 · force-link-environment:4.destructive）： 在跨主机移动 stamp 时，必须先取得同意，然后才能调用 ManageEnvironmentStamp。之前的主机将失去对此环境的管道访问权限。只能通过从之前的主机重新运行 Force Link 来撤销。每次调用技能时都会重新触发。 每次调用恰好将一个环境强制关联到一台主机。如果制作者需要跨主机迁移多个环境，则需针对每个环境分别调用此技能 — 每次调用都必须单独征求同意，并明确回显相应环境的身份信息。不得使用 --yes 标志，不得批量处理，也不得沿用之前的同意。

这是强制性关卡。使用 AskUserQuestion 提供两个选项，并在问题文本中清楚警告这是破坏性操作。提问前必须显示以下信息：

• 目标主机（新主机）
• 源环境名称 + BAP 环境 GUID
• 来自之前主机的 stamp 错误消息（阶段 3 中的错误消息，如有）
• 已记录的副作用：
  • “之前主机上的制作者将失去对此环境的管道访问权限”
  • “之前主机上的环境记录将保留过时的验证状态”
  • “可以通过从之前的主机运行 Force Link 来撤销”

问题结构：

question: "Force-link this environment to <host name>? This will remove its association with the previous host."
options:
  - "Yes — force link" (Recommended only if user is intentionally migrating)
  - "Cancel"

如果用户选择取消，则正常退出（不写入标记文件），并建议运行 /power-pages:ensure-pipelines-host detect-only 以进行进一步诊断。

阶段 5 — 执行 Force Link

node "${PLUGIN_ROOT}/scripts/lib/force-link-environment.js" \
  --hostEnvUrl <hostEnvUrl> \
  --token <hostToken> \
  --deploymentEnvironmentId <guid>

该辅助程序：

1. 调用 ManageEnvironmentStamp（成功时返回 204 No Content）。
2. 每隔 3 秒轮询同一记录的 validationstatus，最多 20 次。
3. 状态为 Succeeded（200000001）时成功返回；状态为 Failed（200000002）时抛出错误，并包含捕获的 errormessage。

如果辅助程序抛出的错误状态为 403，则调用方在目标主机上缺少 Deployment Pipeline Administrator 角色 — 将其作为解决方法消息显示。

如果辅助程序抛出的错误状态为 404，则目标主机上不存在 deploymentenvironments 记录 — 阶段 3 必定静默失败；请返回并重新处理。

阶段 6 — 写入标记并生成摘要

确保 docs/alm/ 目录存在（node -e "require('fs').mkdirSync('docs/alm',{recursive:true})"），然后写入 docs/alm/last-force-link.json：

{
  "schemaVersion": 1,
  "hostEnvUrl": "https://...",
  "deploymentEnvironmentId": "...",
  "bapEnvId": "...",
  "previousHostEnvUrl": "https://...",
  "validationStatus": 200000001,
  "forcedAt": "2026-05-11T..."
}

previousHostEnvUrl 为尽力获取的值。按以下顺序推导；如果均未得到值，则设为 null：

1. 从 docs/alm/last-host-check.json 获取（由 ensure-pipelines-host 写入）：如果已设置 finalHostEnvUrl 且与当前的 hostEnvUrl 不同，则发现流程已将此环境绑定到之前的主机 — 记录该值。
2. 从阶段 3 的 errormessage 获取：扫描捕获的 errormessage，查找符合模式 https?://[^\s'"]+\.(crm\d*\.dynamics\.com|dynamics-int\.com|crm\.microsoftdynamics\.us) 的内容，并选择第一个不是当前 hostEnvUrl 的匹配项。Microsoft 的错误消息在“已关联”场景中有时会包含之前主机的 URL，有时只包含其显示名称；将此正则表达式视为尽力匹配，而非权威依据。
3. 否则：设为 null。标记架构允许此值 — 验证器不要求必须提供该字段。

不要提示用户填写 previousHostEnvUrl；该信息仅用于运行后的摘要。

显示摘要表，包含：

• 已强制关联的环境
• 旧主机 → 新主机
• 验证状态
• 提醒：“你可以在之前的主机上运行 /power-pages:force-link-environment 撤销此操作。”

根据 ${PLUGIN_ROOT}/references/skill-tracking-reference.md 记录技能使用情况。

---

失败情形与补救措施

失败	向用户显示	下一步
ManageEnvironmentStamp 返回 403 Forbidden	“你需要具备 上的 Deployment Pipeline Administrator 角色。”	请主机管理员授予该角色；详见与管道管理员共享。
部署环境记录返回 404 Not Found	“此主机上尚不存在 deploymentenvironments 记录。”	重新执行阶段 3 的创建步骤。
关联后验证状态变为 Failed	原样显示 errormessage。	如果消息提到该环境仍与某个主机关联，则之前的主机可能启用了立即重新应用策略 — 请咨询之前主机的管理员。
用户在阶段 4 取消	“未执行 Force Link；之前的关联保持不变。”	建议运行 /power-pages:ensure-pipelines-host detect-only 进行更全面的诊断。

此技能不会执行的操作

• 它不会在新主机上安装 Pipelines 应用 — 请为此使用 /power-pages:ensure-pipelines-host。
• 它不会自行创建新的主机环境。
• 它不会重新关联管道定义；仅移动环境↔主机戳记。之前主机中引用此环境的管道仍会保留，但会失去此环境作为参与者。
• 它不会修改用户的解决方案。不更新 .solution-manifest.json；不调用 AddSolutionComponent。

进度跟踪

阶段	状态
1 — 前提条件	⏳
1.5 — MCP Learn 知识确认	⏳
2 — 识别主机和开发环境	⏳
3 — 解析 deploymentenvironments 记录	⏳
4 — 确认破坏性操作	⏳
5 — 执行 Force Link	⏳
6 — 写入标记并生成摘要	⏳

阶段完成后更新此表。