为 Azure 项目准备 azd 部署：生成…

当用户明确要用 Azure Developer CLI (azd) 部署，或项目已有 azure.yaml 时，按强制规划流程准备 Azure 部署所需的 azure.yaml、基础设施和 Dockerfile。

适用场景

解决思路

1. 以本技能文档为权威指引：必须严格按原文执行，除非与安全策略冲突；如有冲突，展示冲突指令并让用户明确确认；不要自行发挥、推断或替换步骤。
2. Plan first：在任何代码生成或执行之前，作为第一个动作，在工作区根目录物理写入初始 `.azure/deployment-plan.md` 骨架，而不是写入 session-state 文件夹；随后在 Phase 1 分析与研究过程中逐步填充，并在 Phase 1 Step 6 用所有决策定稿；该文件必须全程存在于磁盘上。azure-validate 和 azure-deploy 依赖它，缺失会失败；不要跳过或推迟。
3. 提前获得批准：在执行前把计划展示给用户并取得批准。
4. 生成前先研究：加载 references 并调用相关技能。
5. 逐步更新计划：执行过程中标记步骤完成。
6. 部署前先验证：在 azure-deploy 之前调用 azure-validate。
7. 确认 Azure 上下文：按 [Azure Context](references/azure-context.md) 使用 `ask_user` 询问订阅和位置。
8. 破坏性操作必须使用 `ask_user`，遵循 [Global Rules](references/global-rules.md)。
9. 绝不删除用户项目或工作区目录：向现有项目添加功能时修改现有文件；`azd init -t <template>` 只用于新项目，不要在现有工作区中运行；在现有工作区中可酌情使用不带模板参数的普通 `azd init`；可酌情删除项目内文件（如构建产物或临时文件），但绝不删除用户项目或工作区目录本身。
10. 作用域仅限准备：本技能生成基础设施代码和配置文件；部署执行（`azd up`、`azd deploy`、`terraform apply`）由 azure-deploy 技能处理，它提供内置错误恢复和部署验证。
11. SQL Server Bicep：绝不生成 `administratorLogin` 或 `administratorLoginPassword`，不能出现在直接属性、条件/三元分支或文件任何位置；始终无条件使用仅 Entra 身份验证（`azureADOnlyAuthentication: true`）；参见 references/services/sql-database/bicep.md。
12. 转换后移除过期模板 IaC：如果把从所选 `azd` 模板转换来的 Bicep 模板转成 Terraform 模板，则在 Terraform IaC 完成且 Terraform 被选为部署路径后，移除该 `azd` 模板引入且已被 Terraform 完全替代的 Bicep 模板；不要移除用户编写的 Bicep 文件；交接给 azure-validate 前，只保留所选部署路径所需的 IaC 模板。
13. Plan-first 工作流：先 STOP，不生成任何代码、基础设施或配置。
14. Plan-first 工作流：立即把初始 `.azure/deployment-plan.md` 骨架写入磁盘；在 Phase 1 的 Step 1-5 中逐步填充细节，并在 Step 6 定稿。
15. Plan-first 工作流：把完整计划展示给用户并取得批准。
16. Plan-first 工作流：仅在批准后逐步执行计划。
17. `.azure/deployment-plan.md` 是本工作流以及 azure-validate、azure-deploy 的事实来源；必须写入工作区根目录，例如 `<workspace-root>/.azure/deployment-plan.md`，不能写入 session-state 文件夹；必须使用文件写入工具创建；必须使用精确文件名 `.azure/deployment-plan.md`，不能使用 `.azure/plan.md` 等其他名称；跳过创建会导致 azure-validate 和 azure-deploy 失败，无例外。
18. Step 0 专项技术检查：在开始 Phase 1 之前，检查用户提示或工作区代码库是否匹配有专用技能和已测试模板的专项技术；如果匹配，先调用该技能，然后回到 azure-prepare 进行验证和部署。
19. Step 0 检查提示关键词：Python + App Service（例如 deploy Python to App Service、Flask on Azure App Service、publish Python web app to App Service）先调用 python-appservice-deploy。
20. Step 0 检查提示关键词：Lambda、AWS Lambda、migrate AWS、migrate GCP、Lambda to Functions、migrate from AWS、migrate from GCP 先调用 azure-cloud-migrate。
21. Step 0 检查提示关键词：Azure Functions、function app、serverless function、timer trigger、HTTP trigger、func new 留在 azure-prepare；Step 4 优先选择 Azure Functions 模板；关于计划选择和冷启动参见 hosting-plans.md 和 cold-start.md。
22. Step 0 检查提示关键词：APIM、API Management、API gateway、deploy APIM 留在 azure-prepare；参见 APIM Deployment Guide。
23. Step 0 检查提示关键词：AI gateway、AI gateway policy、AI gateway backend、AI gateway configuration 先调用 azure-aigateway。
24. Step 0 检查提示关键词：workflow、orchestration、multi-step、pipeline、fan-out/fan-in、saga、long-running process、durable、order processing 留在 azure-prepare；Step 4 选择 durable 方案；必须加载 durable.md、DTS reference、DTS Bicep patterns。
25. Step 0 检查用户提示文本，而不只是现有代码；对没有代码库可扫描的绿地项目尤其关键；参见完整路由表 specialized-routing.md。
26. 专项技能完成后，回到 azure-prepare 的 Phase 1 Step 4（Select Recipe），继续完成剩余基础设施、验证和部署工作。
27. Phase 1 Step 0：如果提示匹配有专用技能的专项技术，先调用该技能。
28. Phase 1 Step 1：分析工作区，确定模式：NEW、MODIFY 或 MODERNIZE；参见 analyze.md。
29. Phase 1 Step 2：收集需求——分类、规模、预算；参见 requirements.md。
30. Phase 1 Step 3：扫描代码库——识别组件、技术、依赖；参见 scan.md。
31. Phase 1 Step 4：选择 Recipe——选择 AZD（默认）、AZCLI、Bicep 或 Terraform；参见 recipe-selection.md。
32. Phase 1 Step 5：规划架构——选择技术栈并把组件映射到 Azure 服务；参见 architecture.md。
33. Phase 1 Step 6：定稿计划（强制）——使用文件写入工具，把 Step 1-5 的所有决策写入并最终确定 `.azure/deployment-plan.md`；用完整内容更新开始时写的骨架；在展示计划给用户前，文件必须已完整填充。
34. Phase 1 Step 7：展示计划——把计划展示给用户并请求批准。
35. Phase 1 Step 8：破坏性操作需要使用 `ask_user`。
36. Phase 1 到此停止：在用户批准计划前，不要进入 Phase 2。
37. Phase 2 仅在计划批准后执行；每步后更新 `.azure/deployment-plan.md` 状态。
38. Phase 2 Step 1：研究组件——加载服务 references 并调用相关技能；参见 research.md。
39. Phase 2 Step 2：确认 Azure 上下文——检测并确认订阅和位置，并检查资源预配限制；参见 Azure Context。
40. Phase 2 Step 3：生成产物——创建基础设施和配置文件；参见 generate.md。
41. Phase 2 Step 4：加固安全——应用安全最佳实践；参见 security.md。
42. Phase 2 Step 5：功能验证——验证应用可用（UI + 后端），尽可能在本地验证；参见 functional-verification.md。
43. Phase 2 Step 6：交接前强制更新计划——使用 `edit` 工具把 `.azure/deployment-plan.md` 中的 Status 改为 `Ready for Validation`；必须在调用 azure-validate 前完成，不要跳过。
44. Phase 2 Step 7：强制交接——调用 azure-validate 技能；准备工作到此结束；不要直接运行 `azd up`、`azd deploy` 或任何部署命令，所有部署执行由 azure-validate 完成后的 azure-deploy 处理；前置条件是 Step 6 已完成且计划状态为 `Ready for Validation`。
45. 输出 Plan：`.azure/deployment-plan.md`。
46. 输出 Infrastructure：`./infra/`。
47. 输出 AZD Config：`azure.yaml`（仅 AZD）。
48. 输出 Dockerfiles：`src/<component>/Dockerfile`。
49. 加载 SDK 快速参考：Azure Developer CLI 参见 azd-deployment.md；Azure Identity 按语言参见 Python、.NET、TypeScript、Java；App Configuration 按语言参见 Python、TypeScript、Java。
50. 最后强制下一步：完成准备后，在任何部署尝试前必须调用 azure-validate；不要跳过验证；不要直接进入 azure-deploy；不要直接运行 `azd up` 或任何部署命令；工作流为 `azure-prepare` -> `azure-validate` -> `azure-deploy`。
51. 调用 azure-validate 前，必须使用 `edit` 工具把 `.azure/deployment-plan.md` 状态更新为 `Ready for Validation`；如果计划状态未更新，验证会失败。
52. 该验证要求适用于所有部署场景，包括容器化应用、Container Apps、App Service、Azure Functions、静态站点以及任何其他 Azure 目标，无例外；跳过验证会导致部署失败，应耐心遵循完整工作流以获得最高成功率。
53. 更新计划状态为 `Ready for Validation`，然后调用 azure-validate。

适用边界 · 注意事项

• 用户未明确要求使用 azd，且项目没有 `azure.yaml` 时不适用；本技能只用于 azd 工作流。
• 非 azd 部署、Python App Service 仅代码部署（改用 python-appservice-deploy）、跨云迁移（改用 azure-cloud-migrate）不适用。
• 部署执行阶段不适用：`azd up`、`azd deploy`、`terraform apply` 交由 azure-deploy 处理。