azure-app-onboard-prereq

Azure App Onboard 前置条件 — 仓库评估

在规划基础设施之前，评估用户仓库的构建健康状况、应用完整性和 Azure 部署可行性。为后续阶段提供各组件的判定结果（PASS/WARN/FAIL）。

**与编排器的关系：**由 azure-app-onboard 在第 3 步调用，也可独立用于代码就绪情况检查。由编排器调用时，写入产物后应将控制权交还给 azure-app-onboard——请勿直接调用后续阶段。

AppOnboard 流水线的第 1 阶段，共 4 个阶段。会话：.copilot-azure/sessions/{session-id}/。读取 context.json。写入 components[]、repo{}、detectedInfra[]。生成 prereq-output.json。架构：prereq-schemas.ts — PrereqOutput、BuildRequirements。支持直接入口。

不适用场景

信号	转至
验证基础设施（Bicep/TF/azure.yaml）	azure-validate
生成 IaC	azure-prepare
从想法到生产环境的端到端流程	azure-app-onboard
运行 azd up 或部署	azure-deploy

规则

⛔ 绝对禁止——绝不可运行 npm install、npm test、npx jest、pytest 以及任何安装/构建/测试命令。 在任何情况下，前置条件阶段都不得运行 npm install、npm test、npx jest、pip install、pytest、dotnet build、dotnet restore、dotnet test、go mod download、cargo build，或任何包管理器安装、构建或测试命令。请勿运行测试套件来验证代码——应通过静态检查测试配置文件。前置条件阶段仅进行只读评估和静态验证。 唯一例外——两种经批准的场景，且均须征得同意：(a) Agent 在迁移/修复过程中修改过的代码（参见 remediation-protocol.md 第 6 步），或 (b) Agent 在零代码路径中从头编写的代码（参见 zero-code-path.md）。在这两种情况下，只能通过用户确认的构建验证关卡（build-check.md 第 3 步）运行安装/构建/测试，并且必须先获得用户针对该具体命令的同意。此前的一般性同意不算数。

1. ⛔ 完整流水线（第 1–8 步），无一例外。 所有提示均直接进入第 1 步。在第 5 步的评估结果中回答具体问题，不要提前回答。
2. ⛔ 评估期间不得使用子 Agent。 三轴评估须在当前流程中完成。例外：零代码路径的脚手架搭建（第 2 步）。
3. 代码修改和破坏性修改必须使用 ask_user。在给出结果前最多提 3 个问题。直接入口：不要重复询问编排器已经提出的意图问题。

MCP 工具

工具	用途
mcp_azure_mcp_get_azure_bestpractices	根据 Azure 最佳实践验证检测到的技术栈模式
mcp_azure_mcp_extension_cli_install	检查/安装所需的 CLI 工具（az、azd、func）

工作流

第 1 步：会话检查

**编排器入口：**会话已存在——读取 context.json，继续第 2 步。

**直接入口：**检查 .copilot-azure/sessions/active-session.json：

• 存在 → ⛔ 阅读 session-protocol.md，了解恢复/新建关卡。用户作出回答前，不得继续。
• 不存在 → 创建会话：生成 UUID，运行 New-Item -ItemType Directory -Path ".copilot-azure/sessions/{uuid}" -Force，使用 create 工具写入 context.json 和 active-session.json。

然后：运行 az account show → 将 {id, name, tenantId} 合并到 context.json.azure。⛔ 在开始任何扫描前，会话必须已写入磁盘。

第 2 步：扫描工作区

扫描项目文件。检测组件、repo{}、detectedInfra[]、detectedServices[]。对 Terraform 提供程序进行分类。检查 CLI 是否可用。技术栈检测冲突时：以用户明确说明为准（写入 context.json，并将扫描标记为覆盖）；仅扫描检测到时 → 向用户确认；存在多个技术栈时 → 显示全部并询问（参见 component-mapping.md）；没有代码时 → zero-code-path.md。

如果没有项目文件、没有 Dockerfile，且没有 index.html → ⛔ 阅读 zero-code-path.md。

⛔ Cloud SDK 提前检查关卡。 搜索 aws-sdk|@aws-sdk|boto3|google-cloud|@google-cloud|firebase。如果发现功能依赖 → 阅读 cloud-sdk-migration.md，然后 ask_user：“重定向到 Azure Cloud Migrate”（设置 routeToSkill: "azure-cloud-migrate"）· “仍继续评估”（完成就绪度评估和 SDK→Azure 映射，然后在第 8 步停止——依赖替换前不要制定计划）· “取消”。

第 3 步：逐个组件评估

子步骤	操作	参考
3.1	构建检查	⛔ 必须阅读 build-check.md
3.2	完整性检查	⛔ 必须阅读 completeness-check.md
3.3	可部署性检查	⛔ 必须阅读 deployability-check.md
3.3a	组件映射（有条件）	仅当找到 >1 个项目清单（monorepo）时，阅读 component-mapping.md

评估后，按组件填写 buildRequirements。判定结果传递、层级规则和 f1Viable 汇总见 readiness-gate.md 和各项检查的参考文档。

第 4 步：编写产物 + 就绪度关卡

⛔ 确认磁盘上存在 context.json。阅读 readiness-gate.md（判定结果、层级、先批量后批准、快速通道），然后阅读 prereq-artifacts.md（编写流程、架构）。

第 5 步：展示发现

根据 readiness-gate.md § Present Findings — 继续之前，按严重程度分组展示判定结果。

第 6 步：修复（有条件）

⛔ 如果存在任何 ❌ FAIL 判定、🔧 建议修复，或带有 fixPhase: "prereq" 的 ⚠️ WARN，必须阅读 remediation-protocol.md。其中包含修复循环、静态验证、重新评估要求、修复后的产物更新，以及构建验证同意关卡。如果所有判定均为 ✅ PASS，或为不带 fixPhase: "prereq" 的 ⚠️ WARN，则跳至第 7 步。

第 7 步：写入最终状态

completedPhases 已包含 "prereq"，且 currentPhase: null（来自第 4 步）。然后：

⛔ 写入 lastScanCommit。 运行 git rev-parse HEAD，并将完整的 40 位 SHA 存储为 context.json.repo.lastScanCommit。这是必需步骤——第 1 步中的过期检查会在恢复时与 HEAD 比较，以检测变更。

步骤 8：路由

⛔ 必须执行 — 不得跳过此步骤。

路由字段： 所有路由操作都会将 routeToSkill 和 routeReason 写入 context.json。

修复后的上下文： 如果执行了步骤 6，请在路由提示词开头写上：“修复已完成 — 已修复 {N} 个问题，你的应用现在处于 {overallHealth} 状态。”

⛔ 按从上到下的顺序评估各行 — 首次匹配即生效。

#	条件	操作
1	routeToSkill 已设置（任意条目）	ask_user：“重定向到 {routeToSkill}” / “暂不”。⛔ 流程停止 — 不得继续进行架构规划。
2	cloudSdkFindings[] 非空（用户选择了“仍然继续评估”）	将 cloud-SDK → Azure 替换映射作为 🔶 阻碍项呈现，然后使用以下确切提示词调用 ask_user：“🔶 必须迁移 Cloud SDK — 部署此应用到 Azure 之前，必须替换这些依赖项。（重定向到 azure-cloud-migrate / 停止 — 手动替换并重新运行）” — 重定向会设置 routeToSkill: "azure-cloud-migrate"；停止则会中止。⛔ 流程停止 — 不得继续进行架构规划，也不得提供“继续准备”选项；替换依赖项之前无法部署此应用。
3	编排器 + 未设置 routeToSkill	告知用户：“✅ 已完成对应用的评估，应用已准备就绪 — 现在来规划 Azure 部署。”然后调用 azure-app-onboard。⛔ 不得停止，不得等待用户输入，不得叙述内部交接过程。用户已在范围分类阶段同意执行完整流程。
4	直接 + ready/readyWithCaveats + 无 Azure 基础设施	ask_user：“部署到 Azure（完整流程）” → 调用 azure-app-onboard / “暂不”
5	直接 + ready/readyWithCaveats + 已有 Azure 基础设施	ask_user：“从头开始” → 调用 azure-app-onboard / “使用现有基础设施” → 调用 azure-prepare / “暂不”
6	直接 + blocked	报告阻碍项摘要 + “修复并重新运行。”

严重性等级（🛑🔶❌🔧⚠️✅）定义于 readiness-gate.md。

输出

工件	位置	使用者
会话上下文	context.json → components[]、repo{}、detectedInfra[]、detectedServices[]	所有下游阶段
先决条件输出	prereq-output.json	准备阶段（通过 azure-app-onboard）
就绪情况报告	.copilot-azure/sessions/{uuid}/readiness-report.md	用户（离线参考）