用途
Aspire Orchestration 是一个工作流技能（WORKFLOW SKILL），用于在 VS Code 或 CLI 中管理 Aspire 应用的生命周期。它的目标是在 AI 代理参与 Aspire 项目时，通过强制的操作规范防止代理「自伤」——即违规操作会导致文件锁、孤儿进程和用户困扰。技能在满足特定检测信号时自动激活。
主要能力
激活检测
当以下任一信号出现时激活：
- C# AppHost：.csproj 中包含 Aspire.AppHost.Sdk（确定性）
- 基于文件的 C# AppHost：apphost.cs 或含
#:sdk Aspire.AppHost.Sdk的 .cs 文件（确定性） - TypeScript AppHost：项目中存在 apphost.mts 或旧版 apphost.ts（确定性）
- Aspire 配置：项目根目录有 aspire.config.json（高）
- Aspire 设置：存在 .aspire/ 目录（高）
- 生成的 TS 模块：.aspire/modules/ 目录（高）
- Service defaults：项目引用中有 Aspire.ServiceDefaults（中）
生命周期管理
- 启动：优先调用 aspire_apphost_start（mode run，传入精确的 appHostPath）；工具不可用或处于 git worktree 时回退到 CLI：
aspire start --non-interactive [--isolated] --apphost <filesystem-path>。 - 等待资源就绪：使用
aspire wait <resource>，禁止使用 curl / HTTP 轮询。 - 检查状态：使用
aspire describe（隐藏资源加--include-hidden），禁止使用已移除的aspire ps --resources。 - 停止：优先调用 aspire_apphost_stop，并严格遵循其结果矩阵回退规则。
停止结果矩阵
stopped/notRunning：报告结果，不再采取停止动作alreadyStopping（controller editor）：报告正在进行，不再采取动作alreadyStarting（controller editor）：重试一次，若重复则报告启动仍在进行notEditorOwned（controller external）：若用户明确要求停止该 AppHost，解析为文件系统路径后运行 CLI 停止命令failed（controller unknown）：重试一次，若重复则使用同目标 CLI 命令ambiguousSession：终止性安全拒绝，不运行也不提供 CLI 回退，用户确认也无法使其安全
Git Worktree 处理
编辑器工具当前无法请求 Aspire 的隔离状态，因此即使在 aspire_apphost_start 可用时，也应使用：aspire start --non-interactive --isolated --apphost <filesystem-path>。
多根工作区
需将选中的 AppHost 解析为实际文件系统路径后再传给 CLI 的 --apphost；不能把多根选择器（如 repo-a~1/MyApp.AppHost/MyApp.AppHost.csproj）原样复制给 CLI。若发现多个 AppHost 且用户目标不清晰，必须提出一个澄清问题并等待用户指定，不得猜测。
安全护栏
- 启动应用：用 aspire_apphost_start，禁止
dotnet run于 AppHost - 等待资源：用
aspire wait，禁止轮询 - 代码变更：优先资源命令、运行时 watch/HMR、仪表板操作或 IDE 调试，禁止对锁定文件执行 dotnet build
- 检查运行中的 AppHost：用
aspire ps，禁止手动检查进程 - 移除持久化资源：确认数据丢失后使用
aspire stop --force --apphost <filesystem-path>，禁止与 --all 组合或用于普通停止 - 安装 Aspire 支持：用
aspire add或aspire init，禁止dotnet workload install aspire（已过时）
使用方式
前置条件
- .NET 10.0 SDK（https://dotnet.microsoft.com/download）
- Aspire CLI，可选安装方式：
- curl/PowerShell：
curl -sSL https://aspire.dev/install.sh | bash - npm：
npm install -g @microsoft/aspire-cli - NativeAOT 全局工具（.NET 10）：
dotnet tool install -g Aspire.Cli
- curl/PowerShell：
应使用用户环境所拥有的安装方式，支持 npm、Nix、Homebrew、WinGet、mise 及安装脚本。
默认工作流
- 确认工作区为 Aspire，识别 AppHost
- git worktree 使用隔离启动命令；否则使用 aspire_apphost_start（mode run）或 CLI 回退
- 交互资源前先
aspire wait <resource> aspire describe检查状态后开始工作- AppHost 代码变更则通过同一生命周期路由重启；仅单个资源变更则优先资源命令/watch/HMR/调试
- 任务完成后停止（编辑器工具优先，CLI 仅在文档化的回退结果下使用）
常用命令
- 人工启动：
aspire run（前台、仪表板） - 列出运行中的 AppHost：
aspire ps - 资源操作：
aspire resource <resource-name> <command> - 创建项目：
aspire new aspire-starter - 添加集成：
aspire add <package> - 升级 CLI：
aspire update --self - 恢复生成文件：
aspire restore - 环境诊断：
aspire doctor - 机器可读输出：
--format Json（支持 ps、describe、start） - API 参考查询：
aspire docs api search <query> --language csharp|typescript
适用场景
- AI 代理在包含 Aspire AppHost 的项目中执行启动、等待、检查、停止等生命周期操作
- 处理因 Aspire 运行导致的构建文件锁错误（MSB3491、CS2012）
- 诊断「端口已占用」「资源未找到」「Docker 守护进程不可用」等环境与运行问题
- git worktree 场景下的隔离启动
- 多 AppHost 场景下的目标消歧
限制
- 仅覆盖生命周期编排，AppHost 接线（资源、ServiceDefaults/OTel）需交接给 aspireify 技能
- 部署、发布、流水线、aspire destroy 交接给 aspire-deployment 技能
- 日志、追踪、指标、仪表板交接给 aspire-monitoring 技能
- 已部署应用的诊断交接给 azure-diagnostics 技能
- TypeScript AppHost 的所有创作均委托给 aspireify；CLI 驱动的旧版迁移由本编排技能负责，且需先获得完整变更批准
- 缺少 SDK 或工具时需通过 aspire doctor 诊断；具体平台差异暂未提供
环境变量
ASPIRE_ENABLE_CONTAINER_TUNNEL：默认 true，容器隧道在 Docker Desktop、Docker Engine 和 Podman 之间提供统一主机连通性，设为 false 可选择退出ASPIRE_ENVIRONMENT：未设置，选择特定环境的配置概要文件ASPIRE_DCP_USE_DEVELOPER_CERTIFICATE：默认 true，Windows 上 DCP 使用 Aspire 受信任开发证书，设为 false 可选择退出features.defaultWatchEnabled：默认未配置时为 false，为支持的 C# 和 TypeScript AppHost 启用 Aspire 默认 watch，不应视为针对资源源码变更的逐资源重建、重启或热重载