Back to Details

azure-app-onboard-prereq

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Azure App Onboard Prereq — Repository Evaluation

Azure App Onboard 前置检查 — 代码库评估

Evaluate a user's repository for build health, app completeness, and Azure deployment feasibility — before infrastructure planning. Produces per-component verdicts (PASS/WARN/FAIL) consumed by downstream phases.
Orchestrator relationship: Called by 
azure-app-onboard
at Step 3, or standalone for code readiness checks. When called by orchestrator, return control to 
azure-app-onboard
after writing artifacts — do NOT invoke downstream phases directly.
Phase 1 of 4 in AppOnboard pipeline. Session: 
.copilot-azure/sessions/{session-id}/
. Reads 
context.json
. Writes 
components[]
, 
repo{}
, 
detectedInfra[]
. Produces 
prereq-output.json
. Schema: 
prereq-schemas.ts
 — 
PrereqOutput
, 
BuildRequirements
. Direct entry supported.
评估用户代码库的构建健康度、应用完整性以及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
。Schema参考：
prereq-schemas.ts
 ——对应
PrereqOutput
、
BuildRequirements
。支持直接启动。

When NOT to Use

不适用于以下场景

SignalRedirect
Validate infrastructure (Bicep/TF/azure.yaml)azure-validate
Generate IaCazure-prepare
End-to-end idea-to-productionazure-app-onboard
Run 
azd up
or deploy		azure-deploy
信号重定向目标
验证基础设施（Bicep/TF/azure.yaml）azure-validate
生成基础设施即代码（IaC）azure-prepare
从想法到生产的端到端流程azure-app-onboard
运行
azd up
或执行部署		azure-deploy

Rules

规则

⛔ ABSOLUTE PROHIBITION — 
npm install
, 
npm test
, 
npx jest
, 
pytest
, and ALL install/build/test commands are NEVER allowed. Under NO circumstances may you run 
npm install
, 
npm test
, 
npx jest
, 
pip install
, 
pytest
, 
dotnet build
, 
dotnet restore
, 
dotnet test
, 
go mod download
, 
cargo build
, or ANY package-manager install, build, or test command during the prereq phase. Do NOT run test suites to verify code — check for test config files statically instead. The prereq phase is read-only evaluation + static-only verification. ONLY exception — two sanctioned contexts, both consent-gated: (a) code the agent modified during migration/remediation (see remediation-protocol.md step 6), or (b) code the agent wrote from scratch on the zero-code path (see zero-code-path.md). In either case, install/build/test runs ONLY via the user-confirmed build-validation gate (build-check.md Step 3), after the user answers that specific per-command consent prompt. General prior consent never counts.
  1. ⛔ Full pipeline (Steps 1–8), no exceptions. All prompts → Step 1 directly. Answer specific questions AS PART OF findings (Step 5), not before.
  2. ⛔ No sub-agents for evaluation. 3-axis evaluation is inline. Exception: zero-code-path scaffolding (Step 2).
  3. Code/destructive modifications require 
    ask_user
    . Max 3 questions before results. Direct entry: don't repeat orchestrator's intent questions.
⛔ 绝对禁止——绝不允许执行
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) 代理在迁移/修复过程中修改的代码（参考remediation-protocol.md步骤6），或(b) 代理在零代码路径中从头编写的代码（参考zero-code-path.md）。无论哪种情况，仅能在用户确认的构建验证关卡（build-check.md步骤3）后运行安装/构建/测试，且需用户针对特定命令确认授权。通用的预先授权无效。
  1. ⛔ 完整流水线（步骤1–8），无例外。 所有提示直接进入步骤1。特定问题需作为检查结果的一部分（步骤5）回答，而非提前回答。
  2. ⛔ 评估环节不得使用子代理。 三维评估需内联执行。例外情况：零代码路径的脚手架搭建（步骤2）。
  3. 代码修改或破坏性操作需调用
    ask_user
    。返回结果前最多可提问3次。直接启动场景：请勿重复编排器已问过的意图问题。

MCP Tools

MCP工具

ToolPurpose
mcp_azure_mcp_get_azure_bestpractices
Validate detected stack patterns against Azure best practices
mcp_azure_mcp_extension_cli_install
Check/install required CLI tools (az, azd, func)
工具用途
mcp_azure_mcp_get_azure_bestpractices
验证检测到的技术栈模式是否符合Azure最佳实践
mcp_azure_mcp_extension_cli_install
检查/安装所需的CLI工具（az、azd、func）

Workflow

工作流程

Step 1: Session Check

步骤1：会话检查

Orchestrator entry: Session exists — read 
context.json
, proceed to Step 2.
Direct entry: Check 
.copilot-azure/sessions/active-session.json
:
  • Exists → ⛔ read session-protocol.md for resume/fresh gate. Do NOT proceed until user answers.
  • Missing → create session: generate UUID, 
    New-Item -ItemType Directory -Path ".copilot-azure/sessions/{uuid}" -Force
    , write 
    context.json
    + 
    active-session.json
    via 
    create
    tool.
Then: 
az account show
→ merge 
{id, name, tenantId}
into 
context.json.azure
. ⛔ Session MUST exist on disk before any scanning.
编排器启动： 会话已存在——读取
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
中。 ⛔ 开始扫描前，磁盘上必须存在会话。

Step 2: Scan Workspace

步骤2：扫描工作区

Scan for project files. Detect components, 
repo{}
, 
detectedInfra[]
, 
detectedServices[]
. Classify Terraform providers. Check CLI availability. Stack detection conflicts: user explicit statement wins (write to 
context.json
, mark scan as override); scan-only → confirm with user; multiple stacks → show all and ask (see component-mapping.md); no code → zero-code-path.md.
If no project files, no Dockerfile, AND no index.html → ⛔ read zero-code-path.md.
⛔ Cloud SDK early gate. Grep for 
aws-sdk|@aws-sdk|boto3|google-cloud|@google-cloud|firebase
. If functional deps found → read cloud-sdk-migration.md, then 
ask_user
: "Redirect to Azure Cloud Migrate" (set 
routeToSkill: "azure-cloud-migrate"
) · "Continue evaluation anyway" (finish readiness eval + SDK→Azure mapping, then STOP at Step 8 — no plan until the deps are swapped) · "Cancel".
扫描项目文件，检测组件、
repo{}
、
detectedInfra[]
、
detectedServices[]
。对Terraform提供商进行分类。检查CLI工具是否可用。技术栈检测冲突处理：用户明确说明优先（写入
context.json
，标记扫描为覆盖）；仅扫描结果→需与用户确认；多个技术栈→全部展示并询问（参考component-mapping.md）；无代码→参考zero-code-path.md。
如果无项目文件、无Dockerfile且无index.html → ⛔ 阅读zero-code-path.md。
⛔ 云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停止——依赖替换前不生成部署计划）· "取消"。

Step 3: Per-Component Evaluation

步骤3：组件级评估

Sub-stepActionReference
3.1Build check⛔ You MUST read build-check.md
3.2Completeness check⛔ You MUST read completeness-check.md
3.3Deployability check⛔ You MUST read deployability-check.md
3.3aComponent mapping (conditional)Read component-mapping.md ONLY IF >1 project manifest found (monorepo)
Populate 
buildRequirements
per component after evaluation. Verdict propagation, tier rules, and f1Viable aggregation are in readiness-gate.md and the individual check references.
子步骤操作参考文档
3.1构建检查⛔ 必须阅读build-check.md
3.2完整性检查⛔ 必须阅读completeness-check.md
3.3部署可行性检查⛔ 必须阅读deployability-check.md
3.3a组件映射（条件触发）仅当检测到多个项目清单（单体仓库）时，阅读component-mapping.md
评估完成后为每个组件填充
buildRequirements
。判定结果传播、层级规则以及f1Viable聚合逻辑在readiness-gate.md和各检查环节的参考文档中定义。

Step 4: Write Artifacts + Readiness Gate

步骤4：写入工件 + 就绪性关卡

⛔ Verify 
context.json
exists on disk. Read readiness-gate.md (verdicts, tiers, batch-then-approve, fast-track) then prereq-artifacts.md (write procedures, schemas).
⛔ 验证磁盘上存在
context.json
。阅读readiness-gate.md（判定结果、层级、批量审批、快速通道），然后阅读prereq-artifacts.md（写入流程、Schema）。

Step 5: Present Findings

步骤5：展示检查结果

Per readiness-gate.md § Present Findings — show verdicts grouped by severity before proceeding.
按照readiness-gate.md § Present Findings的要求——先按严重程度分组展示判定结果，再继续后续操作。

Step 6: Remediation (conditional)

步骤6：修复（条件触发）

⛔ You MUST read remediation-protocol.md IF any ❌ FAIL verdict, 🔧 Recommended Fix, or ⚠️ WARN with 
fixPhase: "prereq"
exists. Contains remediation loop, static verification, re-eval mandate, post-remediation artifact updates, and the build-validation consent gate. If all verdicts are ✅ PASS or ⚠️ WARN without 
fixPhase: "prereq"
, skip to Step 7.
⛔ 如果存在任何❌ FAIL判定、🔧 推荐修复或⚠️ WARN且
fixPhase: "prereq"
，必须阅读remediation-protocol.md。文档包含修复循环、静态验证、重新评估要求、修复后工件更新以及构建验证授权关卡。如果所有判定结果均为✅ PASS或⚠️ WARN且无
fixPhase: "prereq"
，则跳过此步骤进入步骤7。

Step 7: Write Final State

步骤7：写入最终状态

completedPhases
already has 
"prereq"
+ 
currentPhase: null
(from Step 4). Then:
⛔ Write 
lastScanCommit
. Run 
git rev-parse HEAD
and store the full 40-character SHA as 
context.json.repo.lastScanCommit
. Required — staleness guard in Step 1 compares to HEAD on resume to detect changes.
completedPhases
已包含
"prereq"
+ 
currentPhase: null
（来自步骤4）。随后：
⛔ 写入
lastScanCommit
。 执行
git rev-parse HEAD
，将完整的40位SHA值存储为
context.json.repo.lastScanCommit
。此为必填项——步骤1恢复会话时会将其与HEAD对比，以检测代码是否变更。

Step 8: Route

步骤8：路由

⛔ Mandatory — do NOT skip this step.
Routing fields: All routing writes 
routeToSkill
and 
routeReason
to 
context.json
.
Post-remediation context: If Step 6 ran, lead the routing prompt with: "Remediation complete — {N} issues fixed, your app is now {overallHealth}."
⛔ Evaluate rows top to bottom — first match wins.
#ConditionAction
1
routeToSkill
set (any entry)
ask_user
: "Redirect to {routeToSkill}" / "Not now". ⛔ Pipeline stops — do NOT proceed to architecture planning.
2
cloudSdkFindings[]
non-empty (user chose "Continue evaluation anyway")		Present the cloud-SDK → Azure swap mapping as 🔶 blockers, then 
ask_user
with this exact prompt: "🔶 Cloud SDK migration required — these dependencies must be swapped before this app can deploy to Azure. (Redirect to azure-cloud-migrate / Stop — swap manually and re-run)" — Redirect sets 
routeToSkill: "azure-cloud-migrate"
, Stop halts. ⛔ Pipeline stops — do NOT proceed to architecture planning, and do NOT offer a "continue to prepare" option; the app can't deploy until the deps are swapped.
3Orchestrator + no 
routeToSkill
Tell the user: "✅ Your app has been evaluated and is ready — let's plan your Azure deployment." Then invoke 
azure-app-onboard
. ⛔ Do NOT stop, do NOT wait for user input, do NOT narrate internal handoffs. The user already consented to the full pipeline at scope triage.
4Direct + ready/readyWithCaveats + no Azure infra
ask_user
: "Deploy to Azure (full pipeline)" → invoke 
azure-app-onboard
/ "Not now"
5Direct + ready/readyWithCaveats + existing Azure infra
ask_user
: "Start fresh" → invoke 
azure-app-onboard
/ "Use existing infra" → invoke 
azure-prepare
/ "Not now"
6Direct + blockedReport blocker summary + "Fix and re-run."
Severity tiers (🛑🔶❌🔧⚠️✅) are defined in readiness-gate.md.
⛔ 此步骤为必填项——请勿跳过。
路由字段： 所有路由操作需将
routeToSkill
和
routeReason
写入
context.json
。
修复后上下文： 如果执行了步骤6，路由提示需以以下内容开头："修复完成——已修复{N}个问题，您的应用当前状态为{overallHealth}。"
⛔ 从上到下评估条件——首个匹配项生效。
#条件操作
1已设置
routeToSkill
（任何场景）		调用
ask_user
："重定向至{routeToSkill}" / "暂不重定向"。 ⛔ 流水线停止——请勿进入架构规划阶段。
2
cloudSdkFindings[]
非空（用户选择"继续评估"）		将云SDK到Azure的替换映射作为🔶障碍展示，然后调用
ask_user
并使用以下精确提示："🔶 需迁移云SDK——这些依赖项必须替换后，应用才能部署至Azure。（重定向至azure-cloud-migrate / 停止——手动替换后重新运行）" ——重定向会设置
routeToSkill: "azure-cloud-migrate"
，停止则终止流程。 ⛔ 流水线停止——请勿进入架构规划阶段，也不得提供"继续准备"选项；依赖替换完成前应用无法部署。
3编排器启动 + 未设置
routeToSkill
告知用户："✅ 您的应用已完成评估，准备就绪——接下来我们规划Azure部署方案。" 然后调用
azure-app-onboard
。 ⛔ 请勿停止流程，请勿等待用户输入，请勿描述内部交接过程。用户已在范围分类阶段同意执行完整流水线。
4直接启动 + 就绪/附带条件就绪 + 无Azure基础设施调用
ask_user
："部署至Azure（完整流水线）" → 调用
azure-app-onboard
/ "暂不部署"
5直接启动 + 就绪/附带条件就绪 + 已有Azure基础设施调用
ask_user
："重新开始" → 调用
azure-app-onboard
/ "使用现有基础设施" → 调用
azure-prepare
/ "暂不操作"
6直接启动 + 部署受阻报告障碍摘要 + "修复后重新运行。"
严重程度层级（🛑🔶❌🔧⚠️✅）在readiness-gate.md中定义。

Outputs

输出产物

ArtifactLocationConsumer
Session context
context.json
→ 
components[]
, 
repo{}
, 
detectedInfra[]
, 
detectedServices[]
All downstream phases
Prereq output
prereq-output.json
prepare phase (via 
azure-app-onboard
)
Readiness report
.copilot-azure/sessions/{uuid}/readiness-report.md
User (offline reference)
工件位置使用者
会话上下文
context.json
→ 
components[]
, 
repo{}
, 
detectedInfra[]
, 
detectedServices[]
所有下游阶段
前置检查输出
prereq-output.json
准备阶段（通过
azure-app-onboard
调用）
就绪性报告
.copilot-azure/sessions/{uuid}/readiness-report.md
用户（离线参考）