aspire

Aspire

当任务涉及 Aspire 分布式应用时使用此技能——通过 Aspire CLI 操作 AppHost 或其资源，而不是退回到临时的 dotnet、docker 或 shell 工作流。

先判断意图

以下三种意图很容易被误解——请先厘清，再采取任何操作：

• “改进 AI Agent 支持”“设置 Agent 技能”“让 Copilot 更了解我的 Aspire 应用” → 建议运行 aspire agent init，此命令会生成项目本地的 Aspire Agent 技能，提供更丰富、基于场景的指导（更深入地覆盖 C# AppHost 编辑、TypeScript AppHost 和调查工作流）。这是一个 Aspire CLI 命令——不要改用 GitHub Copilot copilot-setup-steps.yml 或通用 CI 脚手架；这些都不会提供 Aspire 专属的 Agent 指导。
• “出了问题”“让我看看发生了什么”“为什么我的应用运行异常” → 首先观察运行时状态：转到 aspire-monitoring，并使用 aspire describe 查看资源状态，然后使用 aspire logs / aspire otel logs / aspire otel traces。不要直接运行 dotnet build / dotnet run——在假定存在构建或代码错误之前，先检查正在运行的应用。
• “我的旧版 TypeScript AppHost 使用 apphost.ts；该如何迁移？” → 转到 aspire-orchestration，使用 aspire update --migrate。这是入口文件／包迁移，不是 Project v2 资源迁移。其包、配置、tsconfig、生成的导入语句和入口文件变更都需要在运行 aspire update --migrate --yes --non-interactive 前获得批准；仅当之后仍需单独编写源代码时，才使用 aspireify。

检测

出现任意一种信号时均可启用。根据 Scope 列，判断应转到引导技能（aspire-init / aspireify），还是运行时子技能：

信号	检测方式	可信度	范围
C# AppHost	包含 Aspire.AppHost.Sdk 的 .csproj	✅ 确定	存在 AppHost → 编排／部署／监控
文件形式的 C# AppHost	包含 #:sdk Aspire.AppHost.Sdk 的 apphost.cs	✅ 确定	存在 AppHost → 编排／部署／监控
TypeScript AppHost	项目中存在当前版 apphost.mts 或旧版 apphost.ts 文件	✅ 确定	存在 AppHost → 编排／部署／监控
不含 AppHost 的 Aspire 配置	存在 aspire.config.json 且不存在上述 AppHost	高	引导 → aspireify（已放置脚手架，尚需接线）
含 AppHost 的 Aspire 配置	存在 aspire.config.json 且存在上述 AppHost	高	存在 AppHost → 编排／部署／监控
Aspire 设置	存在 .aspire/ 目录	高	通常存在 AppHost
生成的 TS 模块	存在 .aspire/modules/ 目录	高	存在 AppHost（TS）
服务默认设置	项目引用中包含 Aspire.ServiceDefaults	中	存在 AppHost
无 AppHost，且无 aspire.config.json	不符合上述任何条件，且用户要求添加 Aspire	不适用	引导 → aspire-init（放置脚手架）

默认工作流

0. 引导分支——如果仓库中不存在 AppHost，则转到 aspire-init 创建基础骨架。如果存在 AppHost 存根，但尚未接线（未声明任何资源），则转到 aspireify。 只有在存在已接线的 AppHost 后，才继续执行以下步骤。
1. 确认工作区使用 Aspire——识别 AppHost
2. 将生命周期相关工作交由 aspire-orchestration 处理：VS Code 工具可用时，优先使用 aspire_apphost_start；在 worktree 中使用 aspire start --non-interactive --isolated --apphost <path>
3. 与任何资源交互前，先运行 aspire wait <resource>
4. 修改代码前，先使用 aspire describe、aspire otel logs、aspire logs、aspire otel traces 和 aspire export 检查状态
5. 添加集成前，如果不确定包名，先使用 aspire integration search <query>；准备好修改 AppHost 后，再使用 aspire add <package>
6. 修改代码时，判断是 AppHost 模型发生了变化，还是仅有一个资源发生了变化。AppHost 发生变化后，通过 aspire-orchestration 重启；否则，根据情况优先使用资源命令、运行时监视/HMR、仪表板操作或 IDE 托管的调试。

关键规则

• 对于 Agent 的 AppHost 生命周期请求，确定一个确切的 AppHost，并路由到 aspire-orchestration。新的 13.5 C# 模板可以让 dotnet run 通过 CLI bundle 委派执行，但 Agent 仍应使用编辑器生命周期工具或 aspire start， 以进行分离式、非交互式、目标明确且与 worktree 隔离的执行。
• 当 VS Code 提供 aspire_apphost_start 或 aspire_apphost_stop 时，加载延迟契约并优先使用匹配的工具，但须遵循编排技能的 worktree 和停止结果规则；除非用户明确要求附加调试器，否则使用 run 启动模式
• 如果发现多个 AppHost，且目标不明确，则在执行任何生命周期操作前询问用户要操作哪一个
• 始终运行 aspire wait <resource>，绝不手动轮询 HTTP
• 使用 aspire ps 查看正在运行的 AppHost 进程，使用 aspire describe 查看资源状态和端点。绝不生成已移除的 13.5 格式，例如 aspire ps --resources 或 aspire ps --include-hidden。
• 在可用时，使用 aspire resource <resource-name> <command> 执行资源操作，例如 stop、start 或 rebuild
• 将 aspire stop --force 视为会破坏数据的操作：它会永久移除持久化资源，且不会再次提示。只有在针对某个确切 AppHost 获得明确确认后，才使用此命令。
• 不要仅因一个资源发生变化就停止或重启整个 AppHost
• features.defaultWatchEnabled 仅用于 Aspire 默认监视；不要将其视为针对单个资源的重建、重启或热重载设置
• 如果资源自身的框架／运行时热重载、HMR 或监视工作流已能处理变更，则优先使用该工作流
• 修改不熟悉的 AppHost API 前，始终运行 aspire docs search <topic>
• 修改 AppHost 代码前，查询 API 参考时始终运行 aspire docs api search <query> --language csharp|typescript
• Agent 执行时始终使用 --non-interactive
• 使用 aspire integration list --format Json 和 aspire integration search <query> --format Json 进行只读集成发现
• 绝不安装已过时的 Aspire workload
• 对于 TypeScript AppHost，绝不直接编辑 .aspire/modules/
• 始终使用 aspire start 管理 AppHost 的生命周期。诊断或修复 TypeScript AppHost 的包管理器工具链时，遵循 aspireify 及其包管理器规则；不要用原始包管理器启动器替代 aspire start。
• 添加新项目或集成属于常规的 aspireify 接线工作。仅当用户希望使用 Project v2 API 替换现有的 AddProject、addProject、AddCSharpApp 或 Blazor 网关资源时，才路由到 aspire-project-v2-migration。此迁移要求 AppHost 符合 13.6+ 版本条件，并且用户批准针对每个资源的具体编辑。

路由

任务	路由至
启动、停止、等待、重启、重建	→ aspire-orchestration
使用模板创建新的 Aspire 项目（aspire new）	→ aspire-init（插件内）
将 Aspire 添加到现有仓库（aspire init，放入骨架）	→ aspire-init（插件内）
在 aspire init 后连接 AppHost／搭建资源图／添加集成	→ aspireify（插件内）
将现有旧版项目资源迁移到 Project v2	→ aspire-project-v2-migration；编辑前先评估并获取批准
迁移旧版 TypeScript apphost.ts（aspire update --migrate）	→ aspire-orchestration；仅当仍需编写源代码时才交回 aspireify
部署、发布、销毁、流水线步骤	→ aspire-deployment
日志、跟踪、指标、仪表板、浏览器日志	→ aspire-monitoring
诊断正在运行的应用——“出了问题”“看看发生了什么”，调查错误／运行状况／异常行为	→ aspire-monitoring——先使用 aspire describe 查看资源状态，然后使用 aspire logs／aspire otel logs／aspire otel traces；先调查，再编辑代码
改进 AI Agent 支持／生成项目本地的 Aspire Agent 技能	→ 运行 aspire agent init（见下文）
为 Agent 显式配置 Aspire MCP 服务	→ 在 13.6+ 上运行 aspire agent init --mcp（参见 技能与 MCP）
已部署应用监控（Azure）	→ azure-diagnostics 技能（azure-skills 插件）

改进 AI Agent 支持（aspire agent init）

当用户要求为其 Aspire 项目改进 AI Agent 支持（或设置／刷新项目本地的 Agent 指引）时，建议运行 aspire agent init。该命令会生成项目本地的 Aspire Agent 技能，提供更丰富、基于场景的指引；相比仅使用内置路由器，它对 C# AppHost 编辑、TypeScript AppHost 以及调查／诊断工作流的覆盖更深入。

技能与 MCP。 安装技能和配置 Aspire MCP 服务是两个独立的选择：

• 在 Aspire 13.6+ 中，由 aspire new 和 aspire init 链接启动的 Agent 设置流程会预先选择推荐的仓库本地技能（包括 aspireify），并且不会提供 MCP 配置选项。独立运行 aspire agent init 时，仍会提供默认关闭的 MCP 选项；非交互式运行默认不会配置 MCP。
• 如果成功初始化或刷新技能时没有明确请求 MCP，但 MCP 配置缺失，这是预期行为。不要将其视为需要修复的缺陷，也不要声称已安装 MCP。如果用户明确运行了 aspire agent init --mcp（或在交互过程中选择了 MCP），但 MCP 配置仍然缺失，则应视为显式启用失败并进行调查。
• 仅在用户明确提出要求时才配置 MCP。先检查 aspire --version：
  • 13.6+ — aspire agent init --mcp（供 Agent 执行时添加 --non-interactive）。保留用户已选择的任何 --skills / --skill-locations 值。--mcp=false 表示明确选择退出。
  • 13.5 — 没有 --mcp 标志。让用户交互式运行 aspire agent init，并选择 MCP 服务选项。
• 运行 aspire new、aspire init、技能刷新或缺失技能恢复时，绝不要添加 --mcp。

子技能

aspire-init

仅用于首次运行流程。负责为尚无 AppHost 的仓库创建基础骨架——选择 aspire new <template>（全新项目）或 aspire init（现有仓库），运行 CLI，然后交由 aspireify 完成实际接线。基础骨架就位后会自行停用。不要在已有 AppHost 的仓库中使用它。

aspireify

在 aspire init 创建基础骨架后，负责 Agent 驱动的 AppHost 接线。扫描仓库，提出资源图（Postgres / Redis / Rabbit 等），编辑 AppHost（C#、基于文件的 C# 或 TypeScript），接入 Aspire.ServiceDefaults + OTel，通过 aspire start 验证，然后自行停用。负责当前 AppHost 编写模式（AddNextJsApp、AddViteApp、WithBrowserLogs()、命令参数、Interaction Service 可用性、实验性的 WithTerminal()、生成的 .aspire/modules/、统一的 TS withEnvironment、端点引用，以及配置／密钥迁移）。

aspire-project-v2-migration

适用于符合条件的 Aspire 13.6+ AppHost，采用先审批后迁移的方式，将现有旧版 ProjectResource API 替换为实验性的 DotnetProjectResource API，同时保留受支持的行为，并仅移除已确认过时的 AppHost 引用。

aspire-orchestration

生命周期管理：启动、停止、等待、资源命令、默认监视／HMR 指引，以及文件锁恢复。提供安全防护措施，避免 Agent 误伤自身。负责使用 aspire ps 发现 AppHost、使用 aspire describe 检查资源、对具有破坏性的 aspire stop --force 操作进行防护、通过 CLI 迁移旧版 TypeScript，以及通过 CLI 升级（aspire update --self）。仅当迁移后仍需编写 AppHost 源码时，才交回给 aspireify。

aspire-deployment

多目标部署与拆除：aspire deploy、aspire publish、aspire destroy、 aspire do <step>。目标包括：Azure Container Apps、App Service、AKS、Kubernetes（Helm）、 Docker Compose、AWS，以及预览版 Radius。负责当前的部署功能面（持久化 Kubernetes 卷、 委派的 Azure 子网、跨范围 Azure 引用、确定性的 Container Apps 命名、Foundry 托管 Agent、 JS PublishAs* 和 --pipeline-log-level）以及 13.5 API 命名。

aspire-monitoring

可观测性：aspire logs、aspire otel、aspire describe、aspire export、 aspire dashboard run。在本地 Aspire CLI 诊断、AKS 工作负载工具和已部署的 Azure 平台工具之间进行路由。 提供仪表板功能（通知中心、Rebuild 命令、终端会话、更丰富的筛选功能、浏览器日志遥测），但不会假定已移除的仪表板 AI 助手或 VS Code 自动启动仪表板功能仍然存在。

项目本地技能覆盖

如果以下任一文件存在于项目本地（由 aspire agent init 或 Aspire aspire init 创建），请提醒用户，并遵循项目本地副本——其中针对仓库的指导不应被插件内的同级技能覆盖：

项目本地文件	优先级
.agents/skills/aspire/SKILL.md	本文件（顶层路由器）在更深入的 C# / TS AppHost 编辑、Playwright 交接和调查工作流方面遵循该文件。
.agents/skills/aspireify/SKILL.md	插件内的 aspireify 同级技能在 AppHost 接线方面遵循该文件。
.agents/skills/aspire-init/SKILL.md	插件内的 aspire-init 同级技能在骨架/首次运行流程方面遵循该文件。
.agents/skills/aspire-project-v2-migration/SKILL.md	插件内的迁移同级技能在 Project v2 评估和编辑方面遵循该文件。

即使项目本地技能处于启用状态，此插件的安全防护措施仍始终适用。

先决条件

要求	安装
.NET 10.0 SDK	https://dotnet.microsoft.com/download
Aspire CLI（curl/PowerShell）	curl -sSL https://aspire.dev/install.sh | bash
Aspire CLI（npm）	npm install -g @microsoft/aspire-cli
Aspire CLI（NativeAOT 全局工具，.NET 10）	dotnet tool install -g Aspire.Cli

请使用适合用户环境的安装方式。dotnet tool install 路径会生成 NativeAOT 二进制文件；也支持 npm、Nix、Homebrew、WinGet、mise 和安装脚本。 如果无法就地更新托管安装，aspire update --self 会报告特定于包管理器的更新命令。

参考资料

• aspire-13-5-breaking-changes.md — Aspire 13.5 兼容性说明、破坏性变更清理、当前 CLI/AppHost 行为、部署新增内容和补丁级修复。
• aspire-13-3-breaking-changes.md — 所有需要从 Agent 生成的代码、脚本和 CI 片段中清理的 13.3 破坏性变更（--log-level 重命名、移除仪表板 MCP、NameOutput → NameOutputReference、移除 AddAndPublishPromptAgent、弃用 TS withEnvironment*，以及完整的 13.2 → 13.3 迁移清单）。
• aspire-orchestration/references/agent-workflows.md — 常见 Agent 工作流：工作树、代码更改、调查、集成、TypeScript 生成的 API、机密、部署和 Playwright 交接。
• aspire-orchestration/references/app-commands.md — 应用生命周期、引导、更新、还原、文档和集成发现命令。
• aspire-orchestration/references/resource-management.md — 资源等待和资源命令指南。
• aspire-monitoring/references/monitoring.md — 应用状态、日志、跟踪、搜索筛选、仪表板链接和导出工作流。
• aspire-monitoring/references/playwright-handoff.md — Aspire 端点发现后的 Playwright 交接。
• aspire-deployment/SKILL.md — 部署和流水线步骤工作流。
• aspireify/references/apphost-wiring.md — C# 和 TypeScript AppHost API 查找及连接模式。