diagnose-deployment

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

diagnose-deployment

显示部署错误，并与已知故障目录中的模式进行匹配。对于每个已识别且有可用自动修复方案的错误，应用任何更改前都会明确征求用户许可。未经确认绝不自动应用修复。

前提条件

• 项目根目录中包含 powerpages.config.json
• 已安装 PAC CLI（如果缺失，会报告）

阶段

阶段 1 — 验证前提条件并定位项目

在本阶段开始时一次性创建所有任务。

要创建的任务：

1. “验证前提条件并定位项目”
2. “收集部署构件”
3. “显示上传错误”
4. “查询解决方案导入状态”
5. “诊断并分类发现的问题”
6. “提供自动修复”
7. “呈现发现的问题摘要”

步骤：

1. 定位项目根目录：在当前工作目录和父目录中搜索 powerpages.config.json
2. 检查 PAC CLI：pac --version（报告版本或“未安装”）
3. 检查 PAC CLI 身份验证：pac env who（报告环境 URL 或“未通过身份验证”）
4. 检查 Azure CLI：az account show（报告订阅或“未登录”）

身份验证失败不会阻止后续操作 — 将其报告为发现的问题，并继续收集其他构件。

阶段 1.5 — 参考当前 ALM 文档

参考：${PLUGIN_ROOT}/references/alm-docs-grounding.md

此步骤最多用时约 30 秒。如果 MCP 搜索 / 获取出错，记录一行说明并继续 — 此技能必须能够离线运行。

1. 使用查询 Power Pages deployment errors solution import troubleshooting 运行 microsoft_docs_search。
2. 通过 microsoft_docs_fetch 并行获取 https://learn.microsoft.com/en-us/power-platform/alm/solution-concepts-alm（以及至多一个关于故障排查或已知导入错误的相关页面）。
3. 提取一段摘要，说明 Microsoft Learn 当前对常见部署失败及其解决方法的描述。与 ${PLUGIN_ROOT}/references/deployment-error-catalog.md 对比，并标记目录中尚未收录的错误模式。
4. 使用该摘要为阶段 5 的模式匹配提供参考。如果 Learn 中记录了目录尚未收录的新模式，请将其作为候选新增项呈现给用户，而不是悄悄扩充目录。

阶段 2 — 收集部署构件

收集所有可用的上下文：

1. 读取 powerpages.config.json — 提取 siteName、websiteRecordId、compiledPath
2. 检查 .powerpages-site/ 文件夹是否存在
3. 使用 glob 查找清单文件：.powerpages-site/*-manifest.yml — 列出所有找到的文件，并记录其环境主机名
4. 检查 .solution-manifest.json 是否存在（用于解决方案相关诊断）
5. 检查 docs/alm/last-import.json 是否存在（用于近期导入失败）
6. 检查构建输出：确认 {compiledPath}/ 存在且非空

报告：“找到项目：{siteName}。已收集构件。”

阶段 3 — 显示上传错误

以捕获模式重新运行 pac pages upload-code-site，以获取最新错误输出：

pac pages upload-code-site --rootPath "." 2>&1

注意：此操作会有意触发上传，以捕获可能出现的错误。如果上传顺利成功，这也是有效的诊断结果（“未发现错误”）。

将 stdout+stderr 捕获为单个字符串。传递给 scripts/parse-deployment-errors.js：

echo "{escaped-output}" | node "${PLUGIN_ROOT}/scripts/parse-deployment-errors.js"

解析 JSON 发现结果数组。如果上传成功且没有错误，记录这一情况，并跳至阶段 5，使用空的发现结果列表。

阶段 4 — 查询解决方案导入状态

仅当 .solution-manifest.json 存在时运行。

1. 获取用于环境 URL 的 Azure CLI 令牌
2. 检查最近 24 小时内的异步操作：

   GET {envUrl}/api/data/v9.2/asyncoperations?$filter=statecode eq 3 and statuscode eq 31 and createdon gt {yesterday}&$select=asyncoperationid,name,message,friendlymessage,statuscode,completedon&$orderby=completedon desc&$top=5
   

3. 检查最近的导入作业：

   GET {envUrl}/api/data/v9.2/importjobs?$select=solutionname,completedon,progress&$orderby=completedon desc&$top=3
   

4. 如果发现失败操作，将每个 message 字段传递给 parse-deployment-errors.js

如果无法进行身份验证（阶段 1 中身份验证失败），则正常跳过。

Phase 5 — 自动诊断已知问题

汇总第 3 和第 4 阶段的所有发现。为每项发现分类：

• Error：阻止部署
• Warning：可能导致问题
• Info：仅供参考

同时添加第 2 阶段发现的缺失构件：

• 缺少 websiteRecordId → Error（patternId：missing-website-record-id）
• 构建输出为空 → Error（patternId：empty-build）
• 存在多个环境清单 → Warning（可能表示环境混淆）

以表格形式呈现所有发现：

#	Severity	Type	Issue	Auto-fix?
1	Error	upload	JavaScript 上传受阻	Yes
2	Warning	config	找到多个清单文件	No

Phase 6 — 提供自动修复

按顺序处理每项 autoFixAvailable: true 的 Error 发现：

🚦 关卡（同意 · diagnose-deployment:6.auto-fix）： 应用任何自动修复前，必须针对每项发现征求同意。对每项 autoFixAvailable: true 的 Error 发现循环一次——每项发现都要单独使用 AskUserQuestion 询问 Yes / No / Skip-all。提示中会显示 pattern ID。绝不批量修复——三项发现就要发出三次单独的同意提示（除非用户在第一次选择“Skip all”，此时会提前结束循环）。对第 1 项发现选择 Yes 并不代表同意修复第 2 项；每项修复的影响范围各不相同（涉及不同文件、不同设置和不同的可逆性）。

1. 说明问题和建议的修复方案

2. 通过 AskUserQuestion 明确征求许可：

   “问题：{message} 建议的修复方案：{suggestedFix} 应用此修复？Yes / No / Skip all auto-fixes”

3. 如果获得批准，执行修复：

   stale-manifest：删除 .powerpages-site/ 中的 *-manifest.yml 文件

   # Ask which manifest to delete if multiple found, then:
   rm ".powerpages-site/{manifestFile}"
   

   blocked-js：更新 blockedattachments 设置

   # Get current setting first
   pac env list-settings | grep -i blocked
   # Remove .js from the blocked list (preserve other blocked types)
   pac env update-settings --name blockedattachments --value "{updated-value}"
   

   missing-website-record-id：检索并更新记录 ID

   pac pages list
   # Parse output, find matching site by name, then update powerpages.config.json
   

   auth-expired：指导用户重新进行身份验证

   pac auth create --environment "{envUrl}"
   az login
   

   empty-build：运行构建

   npm run build
   

4. 每次修复后，重新运行相关检查，确认问题已解决。将发现的状态更新为“Fixed”或“Manual required”。

关键限制：未经用户明确许可，绝不应用任何修复。每项修复都需要单独确认。

Phase 7 — 呈现发现摘要

显示包含所有发现的最终摘要表：

#	Severity	Type	Issue	Status
1	Error	upload	JS 上传受阻	Fixed
2	Error	config	缺少 websiteRecordId	Manual required
3	Warning	config	存在多个清单文件	Informational

状态值：

• Fixed：已应用并验证自动修复
• Manual required：没有可用的自动修复——显示手动操作步骤
• Skipped：用户拒绝修复
• Informational：Warning/Info，无需操作

如果所有 Error 均已解决：建议使用 /power-pages:deploy-site 重试部署。

如果仍有手动操作步骤：明确列出这些步骤及相关命令或链接。

记录技能使用情况

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

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

关键决策点（等待用户）

1. Phase 6：应用每项自动修复前，都必须获得明确确认
2. Phase 6：如果用户说“Skip all auto-fixes”，停止提供修复并转到摘要

错误处理

• 如果 pac pages upload-code-site 没有输出：报告“当前状态下未检测到上传错误”
• 如果 Azure CLI 令牌不可用：跳过 Phase 4，并在摘要中注明
• 如果 parse-deployment-errors.js 未返回任何发现：报告“未检测到已知错误模式”，并显示原始输出供人工审查

进度跟踪表

任务主题	当前状态	描述
验证先决条件并定位项目	正在验证先决条件	检查 PAC CLI、Azure CLI，定位项目根目录和 powerpages.config.json
收集部署构件	正在收集部署构件	读取配置，列出清单，检查构建输出，检查解决方案清单
显示上传错误	正在显示上传错误	在捕获模式下重新运行 pac pages upload-code-site，解析 stdout/stderr
查询解决方案导入状态	正在查询解决方案导入状态	在 Dataverse 中检查近期失败的异步操作和导入作业
诊断并分类发现的问题	正在诊断发现的问题	将所有错误与 deployment-error-catalog 中的模式匹配，并指定严重性
提供自动修复	正在应用自动修复	对于每个可修复的错误，征求许可并执行修复，验证结果
呈现发现问题的摘要	正在呈现摘要	显示包含严重性和修复状态的所有发现问题表格，并列出手动步骤