azure-architecture-autopilot

Azure 架构构建器

一个使用自然语言设计 Azure 基础设施，或分析现有资源以可视化架构并完成修改和部署的流水线。

图表引擎内嵌在技能中（scripts/ 文件夹）。 无需 pip install —— 它直接使用捆绑的 Python 脚本 生成带有 605+ 个官方 Azure 图标的交互式 HTML 图表。 无需网络访问或安装包即可立即使用。

自动检测用户语言

🚨 检测用户第一条消息的语言，并使用该语言提供后续所有回复。这是最高优先级原则。

• 如果用户使用韩语书写 → 使用韩语回复
• 如果用户使用英语书写 → 使用英语回复（ask_user、进度更新、报告、Bicep 注释 —— 全部使用英语）
• 本文档中的说明和示例均使用英语书写，所有面向用户的输出都必须与用户的语言一致

⚠️ 不要将本文档中的示例逐字复制给用户。 仅将结构作为参考，并根据用户的语言调整文本。

工具使用指南（GHCP 环境）

功能	工具名称	备注
获取 URL 内容	web_fetch	用于 MS Docs 查询等
网页搜索	web_search	URL 发现
询问用户	ask_user	choices 必须是字符串数组
子 Agent	task	explore/task/general-purpose
Shell 命令执行	powershell	Windows PowerShell

所有子 Agent（explore/task/general-purpose）都无法使用 web_fetch 或 web_search。 需要查询 MS Docs 的事实核查必须由主 Agent 直接执行。

外部工具路径发现

az、python、bicep 等通常不在 PATH 中。 在开始某个 Phase 之前发现一次并缓存结果。不要每次都重新发现。

⚠️ 不要使用 Get-Command python —— 存在 Windows Store 别名的风险。 直接文件系统发现（$env:LOCALAPPDATA\Programs\Python）优先。

az CLI 路径：

$azCmd = $null
if (Get-Command az -ErrorAction SilentlyContinue) { $azCmd = 'az' }
if (-not $azCmd) {
  $azExe = Get-ChildItem -Path "$env:ProgramFiles\Microsoft SDKs\Azure\CLI2\wbin", "$env:LOCALAPPDATA\Programs\Azure CLI\wbin" -Filter "az.cmd" -ErrorAction SilentlyContinue | Select-Object -First 1 -ExpandProperty FullName
  if ($azExe) { $azCmd = $azExe }
}

Python 路径 + 内嵌图表引擎：参阅 references/phase1-advisor.md 中的图表生成部分。

必须提供进度更新

使用块引用 + emoji + 粗体格式：

> **⏳ [Action]** — [Reason]
> **✅ [Complete]** — [Result]
> **⚠️ [Warning]** — [Details]
> **❌ [Failed]** — [Cause]

并行预加载原则

在通过 ask_user 等待用户输入时，并行预加载下一步所需的信息。

ask_user 问题	同时预加载
项目名称 / 扫描范围	参考文件、MS Docs、Python 路径发现、图表模块路径验证
模型/SKU 选择	用于下一个问题选项的 MS Docs
架构确认	az account show/list、az group list
订阅选择	az group list

---

路径分支 —— 由用户请求自动确定

路径 A：新设计（New Build）

触发条件：“create”、“set up”、“deploy”、“build”等。

Phase 1 (references/phase1-advisor.md) — Interactive architecture design + diagram
    ↓
Phase 2 (references/bicep-generator.md) — Bicep code generation
    ↓
Phase 3 (references/bicep-reviewer.md) — Code review + compilation verification
    ↓
Phase 4 (references/phase4-deployer.md) — validate → what-if → deploy

路径 B：现有分析 + 修改（Analyze & Modify）

触发条件：“analyze”、“current resources”、“scan”、“draw a diagram”、“show my infrastructure”等。

Phase 0 (references/phase0-scanner.md) — Existing resource scan + diagram
    ↓
Modification conversation — "What would you like to change here?" (natural language modification request → follow-up questions)
    ↓
Phase 1 (references/phase1-advisor.md) — Confirm modifications + update diagram
    ↓
Phase 2~4 — Same as above

当路径判断不明确时

直接询问用户：

ask_user({
  question: "What would you like to do?",
  choices: [
    "Design a new Azure architecture (Recommended)",
    "Analyze + modify existing Azure resources"
  ]
})

---

Phase 转换规则

• 每个 Phase 读取并遵循其对应 references/*.md 文件中的说明
• 在 Phase 之间转换时，始终告知用户下一步
• 不要跳过 Phase（尤其是 Phase 3 → Phase 4 之间的 what-if）
• 🚨 Phase 1 → Phase 2 转换的必要条件：01_arch_diagram_draft.html 必须已使用内嵌图表引擎生成并向用户展示。没有图表就不要继续生成 Bicep。 仅完成规范收集并不意味着 Phase 1 已完成 —— Phase 1 包含图表生成 + 用户确认。
• 部署后的修改请求 → 返回 Phase 1，而不是 Phase 0（Delta Confirmation Rule）

服务覆盖与回退

优先支持的服务

Microsoft Foundry、Azure OpenAI、AI Search、ADLS Gen2、Key Vault、Microsoft Fabric、Azure Data Factory、VNet/Private Endpoint、AML/AI Hub

其他 Azure 服务

全部支持——会自动查阅 MS Docs，以同等质量标准生成。 不要发送诸如“超出范围”或“尽力而为”之类会引起用户焦虑的消息。

稳定信息与动态信息的处理

类别	处理方式	示例
稳定	优先参考文件	isHnsEnabled: true、PE 三件套
动态	始终获取 MS Docs	API 版本、模型可用性、SKU、区域

快速参考

文件	作用
references/phase0-scanner.md	现有资源扫描 + 关系推断 + 架构图
references/phase1-advisor.md	交互式架构设计 + 事实核查
references/bicep-generator.md	Bicep 代码生成规则
references/bicep-reviewer.md	代码审查清单
references/phase4-deployer.md	validate → what-if → deploy
references/service-gotchas.md	必需属性、PE 映射
references/azure-dynamic-sources.md	MS Docs URL 注册表
references/azure-common-patterns.md	PE/安全/命名模式
references/ai-data.md	AI/数据服务指南
assets/06-architecture-diagram.png	生成的架构图示例
assets/07-azure-portal-resources.png	Azure 门户资源视图示例
assets/08-deployment-succeeded.png	部署成功结果示例