azure-prepare

Azure 准备

权威指南 — 必须遵守

本文档是为应用准备 Azure 部署的官方权威来源。除非这些说明与提供给你的安全策略相冲突，否则你必须严格按照原文遵循。遇到不确定情况时，请向用户展示本文档中相互冲突的说明，并征求用户的明确确认。不要自行发挥、推断或替换步骤。

---

触发条件

用户想要进行以下操作时，激活此技能：

• 创建新应用
• 向现有应用添加服务或组件
• 更新或修改现有应用
• 现代化改造或迁移应用
• 设置 Azure 基础设施
• 部署到 Azure 或托管在 Azure 上
• 创建并部署到 Azure（包括基于 Terraform 的部署请求）

规则

1. 先制定计划 — 必须 — 你必须将初始 .azure/deployment-plan.md 骨架文件实际写入工作区根目录（而不是会话状态文件夹），并将此作为首要操作——在开始任何代码生成或执行之前。立即写入骨架文件，然后随着第一阶段的分析和研究逐步完善；在第一阶段第 6 步完成时，确定文件中的所有决策。此文件必须始终存在于磁盘上。azure-validate 和 azure-deploy 依赖此文件；缺少该文件时，它们将无法运行。不要跳过或推迟此步骤。
2. 获取批准 — 执行前向用户展示计划
3. 生成前先研究 — 加载参考资料并调用相关技能
4. 逐步更新计划 — 逐步将已完成的步骤标记为完成
5. 部署前先验证 — 在 azure-deploy 之前调用 azure-validate
6. 确认 Azure 上下文 — 根据 Azure 上下文，使用 ask_user 确认订阅和区域
7. ❌ 破坏性操作需要使用 ask_user — 参见全局规则
8. ⛔ 绝不删除用户的项目或工作区目录 — 向现有项目添加功能时，修改现有文件。azd init -t <template> 仅用于新项目；不要在现有工作区中运行 azd init -t。在适当情况下，可在现有工作区中使用不带模板参数的普通 azd init。在适当情况下，允许删除项目中的文件（例如，移除构建产物或临时文件），但绝不删除用户的项目或工作区目录本身。参见全局规则。
9. 范围：仅限准备工作 — 此技能用于生成基础设施代码和配置文件。部署执行（azd up、azd deploy、terraform apply）由 azure-deploy 技能负责，该技能提供内置错误恢复和部署验证。
10. ⛔ SQL Server Bicep：绝不生成 administratorLogin 或 administratorLoginPassword — 不得在直接属性、条件／三元分支或文件中的任何位置生成这些字段。始终无条件使用仅限 Entra 的身份验证（azureADOnlyAuthentication: true）。参见 references/services/sql-database/bicep.md。
11. 转换后移除过时的模板 IaC — 如果你将所选 azd 模板中的 Bicep 模板转换成 Terraform 模板，请移除该 azd 模板引入且现已由 Terraform 等效模板完全替代的 Bicep 模板。不要移除用户编写的 Bicep 文件。只有在 Terraform IaC 完成且已选择 Terraform 作为部署路径后，才能移除这些模板提供的 Bicep 文件。移交给 azure-validate 技能前，只保留所选部署路径所需的 IaC 模板。

---

❌ 规划优先工作流 — 强制要求

开始任何工作前，必须先制定计划

1. 停止 — 暂勿生成任何代码、基础设施或配置
2. 创建骨架 — 立即将初始 .azure/deployment-plan.md 骨架写入磁盘（必须在开始生成或执行任何代码之前），然后随着阶段 1 步骤 1-5 逐步揭示细节，逐步完善该文件；在步骤 6 完成最终定稿
3. 确认 — 向用户展示完整计划并获得批准
4. 执行 — 获得批准后，才可逐步执行计划

.azure/deployment-plan.md 文件是此工作流以及 azure-validate 和 azure-deploy 技能的事实来源。缺少该文件，这些技能将无法运行。

⚠️ 关键：必须将 .azure/deployment-plan.md 写入工作区根目录中（例如 <workspace-root>/.azure/deployment-plan.md），而不是会话状态文件夹。使用文件写入工具创建此文件。这是 azure-validate 和 azure-deploy 读取的部署计划产物。必须创建此文件 — 不得跳过。 ⚠️ 关键：必须将文件命名为 .azure/deployment-plan.md。不得使用 .azure/plan.md 等其他名称。

⛔ **关键：**跳过创建计划文件将导致 azure-validate 和 azure-deploy 失败。此要求没有例外。

---

❌ 步骤 0：专用技术检查 — 必须首先执行

开始阶段 1 之前，检查用户提示词或工作区代码库是否匹配具有专用技能和经过测试的模板的专用技术。如果匹配，首先调用该技能 — 然后恢复 azure-prepare，以进行验证和部署。

检查 1：提示词关键词

提示词关键词	首先调用
Python + App Service（例如，“将 Python 部署到 App Service”、“Azure App Service 上的 Flask”、“将 Python Web 应用发布到 App Service”）	python-appservice-deploy
Lambda、AWS Lambda、迁移 AWS、迁移 GCP、Lambda 到 Functions、从 AWS 迁移、从 GCP 迁移	azure-cloud-migrate
Azure Functions、函数应用、无服务器函数、计时器触发器、HTTP 触发器、func new	保持使用 azure-prepare — 在步骤 4 中优先选择 Azure Functions 模板；有关计划选择/冷启动，请参阅 hosting-plans.md 和 cold-start.md
APIM、API Management、API 网关、部署 APIM	保持使用 azure-prepare — 请参阅 APIM 部署指南
AI 网关、AI 网关策略、AI 网关后端、AI 网关配置	azure-aigateway
工作流、编排、多步骤、管道、扇出/扇入、Saga、长时间运行的进程、持久化、订单处理	保持使用 azure-prepare — 在步骤 4 中选择 durable 配方。必须加载 durable.md、DTS 参考 和 DTS Bicep 模式。

⚠️ 检查用户的提示词文本 — 不要只检查现有代码。对于没有代码库可扫描的全新项目，这一点至关重要。请参阅完整路由表。

专用技能完成后，从阶段 1 步骤 4（选择配方）继续执行 azure-prepare，以处理剩余的基础设施、验证和部署。

---

阶段 1：规划（阻塞性 — 必须在执行前完成）

按以下步骤创建 .azure/deployment-plan.md。在计划获批前，不要生成任何产物。

#	操作	参考
0	如果提示词匹配某项拥有专用技能的特定技术，先调用该技能	specialized-routing.md
1	分析工作区 — 确定模式：NEW、MODIFY 或 MODERNIZE	analyze.md
2	收集需求 — 分类、规模、预算	requirements.md
3	扫描代码库 — 识别组件、技术和依赖项	scan.md
4	选择方案 — 选择 AZD（默认）、AZCLI、Bicep 或 Terraform	recipe-selection.md
5	规划架构 — 选择技术栈，并将组件映射到 Azure 服务	architecture.md
6	完成计划（必须） - 使用文件写入工具，将步骤 1-5 的所有决策写入 .azure/deployment-plan.md。用完整内容更新在阶段 1 开始时写入的骨架文件。向用户展示计划前，必须完整填写该文件。	plan-template.md
7	展示计划 — 向用户展示计划并征求批准	.azure/deployment-plan.md
8	破坏性操作必须使用 ask_user	Global Rules

---

❌ 到此为止 — 用户批准计划前，不要继续到阶段 2。

---

阶段 2：执行（仅在计划获批后）

执行获批的计划。每完成一步后，更新 .azure/deployment-plan.md 中的状态。

#	操作	参考
1	研究组件 — 加载服务参考资料并调用相关技能	research.md
2	确认 Azure 上下文 — 检测并确认订阅和位置，并检查资源预配限制	Azure Context
3	生成产物 — 创建基础设施和配置文件	generate.md
4	强化安全性 — 应用安全最佳实践	security.md
5	功能验证 — 验证应用能否正常运行（UI + 后端）；如可行，在本地进行验证	functional-verification.md
6	⛔ 更新计划（交接前必须完成） — 使用 edit 工具，将 .azure/deployment-plan.md 中的状态更改为 Ready for Validation。调用 azure-validate 前，必须完成此编辑。不要跳过此步骤。	.azure/deployment-plan.md
7	⛔ 必须进行交接 — 调用 azure-validate 技能。准备工作到此完成。不要直接运行 azd up、azd deploy 或任何部署命令 — 所有部署执行都由 azure-validate 完成后的 azure-deploy 负责。**前置条件：**必须先完成步骤 6 — .azure/deployment-plan.md 中的状态必须为 Ready for Validation。	—

---

输出

产物	位置
计划	.azure/deployment-plan.md
基础设施	./infra/
AZD 配置	azure.yaml（仅限 AZD）
Dockerfile	src/<component>/Dockerfile

---

SDK 快速参考

• Azure Developer CLI：azd
• Azure Identity：Python | .NET | TypeScript | Java
• App Configuration：Python | TypeScript | Java

---

下一步

⛔ 必须执行的下一步——不得跳过

完成准备工作后，必须在尝试部署前调用 azure-validate。不得跳过验证。不得直接调用 azure-deploy。不得直接运行 azd up 或任何部署命令。工作流如下：

azure-prepare → azure-validate → azure-deploy

⛔ 调用 azure-validate 之前，必须使用 edit 工具将 .azure/deployment-plan.md 中的状态更新为 Ready for Validation。如果计划状态未更新，验证将会失败。

这适用于所有部署场景，包括容器化应用、Container Apps、App Service、Azure Functions、静态站点以及任何其他 Azure 目标。没有例外。

跳过验证会导致部署失败。请耐心遵循完整工作流，以获得最高成功率。

→ 将计划状态更新为 Ready for Validation，然后调用 azure-validate