aspire

aspire skill 概览

aspire skill 能帮你做什么

aspire skill 适合这样一类用户：你需要创建、运行、调试、配置或发布基于 Aspire 的分布式应用，但不想把零散文档里的流程自己拼起来。它最有价值的场景，不是“系统学习 Aspire 理论”，而是“先把 AppHost 跑起来、把服务依赖接对、定位故障，并准备好可用于部署的产物”。

哪些人适合使用 aspire

最适合的读者包括：

• 正在评估 Aspire 是否适合做多服务应用本地编排的开发者
• 想在现有 API、容器或可执行程序外围补一层 AppHost 的团队
• 希望借助 AI 助手完成 aspire install、初始化、排障和面向部署的发布流程的用户
• 同时使用 .NET AppHost 与 Python、Node.js、Go、Java 或容器化服务的多语言团队

这个 aspire skill 有什么不同

相比泛泛而谈的普通提示词，aspire skill 的优势在于：它会把代理引导到当前任务真正该看的参考路径上：

• CLI 用法和安装细节在 references/cli-reference.md
• AppHost 与运行时概念在 references/architecture.md
• dashboard 与可观测性工作流在 references/dashboard.md
• 面向目标平台的发布说明在 references/deployment.md
• 通过 MCP 发现集成方式在 references/integrations-catalog.md

这点很关键，因为 Aspire 有自己明确的心智模型：由 AppHost 定义资源与依赖关系，再通过运行时和 dashboard 在本地完成运行与观测。

安装 aspire 前的核心判断点

如果你想用一处由代码定义的入口来统一编排服务、依赖、端点、日志、追踪以及面向目标平台的发布产物，就适合选 Aspire。
但如果你期待“一条命令直接部署到生产”，那就不适合：仓库里已经说明得很清楚，Aspire 负责产出 manifests 和 artifacts，真正的部署仍由你的 CI/CD 或目标平台完成。

如何使用 aspire skill

aspire skill 的安装与使用上下文

一个实用的 aspire skill 安装路径，是先把 skill 加进来，再按任务类型只加载对应参考文件：

1. 安装 skill：
   npx skills add github/awesome-copilot --skill aspire
2. 打开 skills/aspire/SKILL.md
3. 不要一口气全读完，只加载与你当前任务匹配的参考文件

建议阅读顺序：

• SKILL.md
• references/cli-reference.md
• references/architecture.md
• references/deployment.md
• references/troubleshooting.md

如何安装 Aspire 本体

如果你的目标是真正开始使用 Aspire，aspire skill 指向的是独立 CLI 安装流程：

# Linux / macOS
curl -sSL https://aspire.dev/install.sh | bash

# Windows PowerShell
irm https://aspire.dev/install.ps1 | iex

aspire --version

这一点很重要，因为 Aspire CLI 是主要操作入口，不只是 dotnet 的一个附属功能。

一开始就把任务描述对

aspire skill 在你的请求明确表达以下意图之一时，效果最好：

• 创建一个新的 Aspire 应用
• 给现有 solution 增加一个 AppHost
• 接入 Redis 或 PostgreSQL 这类依赖
• 运行并调试本地分布式应用
• 为 Docker 或 Kubernetes 发布 Aspire 输出
• 排查启动、健康检查或服务发现问题

像“帮我搞一下 Aspire”这种模糊请求，基本只能靠猜。
而像“帮我的 API、Redis 和一个 Python worker 配好 AppHost，再准备 Docker publish output”这种说法，才足够具体，代理才能准确调用对应参考资料。

aspire skill 需要你提供哪些输入

想得到高质量输出，最好提供：

• 你当前的仓库结构
• 目标语言和运行时
• 是否已经有 AppHost
• 本地运行约束，比如 Docker 或 Podman 是否可用
• 目标发布平台：Docker、Kubernetes，还是面向 Azure 的输出
• 如果是在排障，补充已观察到的失败症状

有用的输入示例：

I have a .NET API, a React frontend, and a Redis dependency. I want Aspire for local orchestration and Docker publish artifacts. I already use Docker Desktop. Show me the AppHost shape, CLI commands, and likely package choices.

如何把模糊目标变成高质量的 aspire 提示词

一条好的 aspire 指导型提示，通常包含五部分：

1. 当前应用结构
2. 期望的资源
3. 本地运行预期
4. 部署目标
5. 你希望返回结果的形式

示例：

Use the aspire skill to propose an AppHost for:
- .NET API in src/Api
- Node frontend in src/Web
- PostgreSQL for local dev
Need:
- service startup order
- endpoint wiring
- environment variable strategy
- Aspire CLI commands
- publish path for Kubernetes
Return code snippets plus a short explanation of tradeoffs.

真正使用 aspire skill 时，优先读哪些仓库文件

如果你是在评估是否采用 aspire skill，这些文件最值得先看：

• SKILL.md：看范围和路由方式
• references/cli-reference.md：看安装、aspire new、aspire run、aspire publish 以及带版本差异的命令
• references/deployment.md：看 publish 与 deploy 之间那条关键边界
• references/polyglot-apis.md：如果你的服务不全是 .NET，优先看这里
• references/mcp-server.md：如果你想让助手主动检查环境并查文档
• references/troubleshooting.md：本地编排失败时优先看这里

这套结构非常实用：aspire skill 是“参考资料驱动型”设计，效果好不好，取决于你是否加载了正确文件，而不是把所有文件都塞进去。

aspire 的实际使用流程是什么样

典型的 aspire 使用顺序通常是：

1. 创建或打开 AppHost
2. 定义资源和引用关系
3. 用 aspire run 在本地运行
4. 在 dashboard 中查看资源状态、日志、端点和 traces
5. 迭代调整配置
6. 为目标部署平台发布 artifacts

相比一上来就冲着部署去，这个流程更合理，因为 Aspire 的设计重点本来就是先做好本地编排和可观测性。

正确理解用于 Deployment 的 aspire

对于 aspire for Deployment，最关键的一点是：aspire publish 生成的是部署产物，不会直接帮你完成部署。

参考资料中的示例：

aspire publish -p docker -o ./docker-output
aspire publish -p kubernetes -o ./k8s-output

决策建议：

• 如果你希望部署产物来自与你本地运行相同的 AppHost 模型，可以选 Aspire
• 如果你期待一个工具同时完成应用定义和生产发布全流程，就不该选它

什么时候该走 MCP 路径

当你希望助手直接检查正在运行的应用，或者无需手动搜索就能抓取集成文档时，aspire skill 配合 MCP 会特别有用。

references/mcp-server.md 里展示了 aspire mcp init，它可以为受支持的 AI 环境生成配置，并创建 .vscode/mcp.json 以及 AGENTS.md。这对采用落地很重要，因为它显著缩短了“助手只懂 Aspire 概念”和“助手真的能看到我当前资源、日志和 traces”之间的距离。

能显著提升输出质量的实用建议

• 明确说明你的工作负载是 .NET project、container 还是 executable；Aspire 对它们的建模方式不同。
• 尽早说明本地运行时是否可用。多语言应用即使 AppHost 是 .NET，也可能需要目标语言运行时先装好。
• 明确要求输出启动顺序和依赖接线；这正是 AppHost 价值最容易体现的地方。
• 如果最终目标是部署，要求代理把“本地编排选择”和“面向发布目标的选择”分开说明。
• 如果命令执行失败，贴出完整命令，以及 dashboard 或日志里看到的实际状态，而不只是说一句“没跑起来”。

aspire skill 常见问题

aspire skill 适合新手吗

适合，前提是你已经对多服务应用有基本认识。aspire skill 能明显降低新手最常见的阻力：哪些 CLI 命令最关键、AppHost 到底负责什么、dashboard 行为该去哪里看，以及为什么 publish 不等于 deploy。

aspire skill 的边界在哪里

aspire skill 覆盖的是本地编排、AppHost 概念、集成发现、MCP 配置、dashboard 工作流、故障排查，以及面向发布的部署准备。它不能完整替代你平台专属的 CI/CD、集群运维或云安全设计。

为什么 aspire skill 比普通提示词更好

普通提示词也许能生成“看起来像对的”配置建议，但实际可能有偏差。aspire skill 更适合以下需求：

• 带版本意识的 CLI 指导
• 正确区分 publish 与 deploy
• 多语言托管模式
• dashboard 与故障排查路径
• 通过 MCP 工具发现集成方式

aspire 只适合 .NET 团队吗

不是。参考资料里明确覆盖了多语言工作负载。虽然 AppHost 本身仍然基于 .NET，但被编排的服务可以是其他语言的容器或可执行程序。因此 Aspire 不只适用于纯 .NET 方案，也适合混合技术栈。

什么情况下不该用 aspire

以下场景可以直接跳过 Aspire：

• 你只需要运行单一进程应用
• 团队已经有一套很合适的本地编排标准
• 你需要的是直接管理生产部署，而不是生成部署产物
• 你的环境无法满足所需的本地运行时或容器工具条件

安装 aspire 一定需要 Docker 吗

不一定，但很多实际的 Aspire 工作流都会明显受益于容器支持。架构参考里提到，容器可以通过 Docker 或 Podman 这类本地运行时运行，而可执行程序则直接作为本机进程运行。你是否真的需要 Docker，取决于你打算编排哪些资源。

如何提升 aspire skill 的使用效果

给 aspire skill 提供具体的架构输入

想让 aspire skill 更快给出靠谱结果，最有效的方法就是不要再让它举抽象例子，而是直接提供你的真实拓扑：

• 服务名称
• 端口或端点预期
• 依赖图
• 本地运行约束
• 目标发布平台

这样更容易得到更准确的 AppHost 建议、更清晰的端点接线，以及更少的通用占位内容。

要求输出按可落地的块来组织

与其说“帮我搭一套 Aspire”，不如直接要求输出：

• AppHost 代码
• package 和 template 命令
• 本地运行步骤
• dashboard 验证步骤
• 面向目标平台的 publish 命令

这种结构更贴近 Aspire 的真实使用方式，也更容易逐项验证。

有意识地使用 references 文件夹

想提升质量，就明确告诉代理应基于哪个来源展开：

• “use references/deployment.md for publish choices”
• “use references/polyglot-apis.md for Node and Python hosting options”
• “use references/troubleshooting.md to diagnose failed startup”

这样能避免把架构、运行时行为和部署逻辑混在一起，导致回答越说越乱。

常见失败模式：把本地编排和生产部署混为一谈

采用 Aspire 时，最常见的误区之一，就是误以为 Aspire 自己会直接部署到生产。如果第一轮输出开始往这个方向偏，立刻纠正：要求它先给 publish artifacts，再单独补一份 CI/CD 交接方案。这样才能让 aspire guide 保持实用且准确。

常见失败模式：遗漏依赖和健康检查前提

如果服务启动顺序不对，或者服务发现失败，就要求代理明确建模以下内容：

• 资源之间的 references
• wait/health 行为
• 从依赖派生出的环境变量
• 外部端点暴露需求

这正是模糊的 aspire usage 请求最容易表现不佳的地方。

通过共享可观测证据提升排障效果

当你希望 aspire skill 帮你定位问题时，尽量提供：

• 使用过的 aspire run 命令
• dashboard 中每个资源的状态
• 失败资源的日志
• 故障属于启动、连通性还是 publish 相关问题

可观测证据的价值，往往比贴一大段代码更高。

针对目标约束优化用于 Deployment 的 aspire 输出

对于 aspire for Deployment，要明确说明你的平台预期是什么：

• Docker Compose artifacts
• Kubernetes manifests
• Helm-friendly output
• environment-specific configuration boundaries
• replica 或 ingress 预期

部署参考已经说明，publish 输出是强目标导向的，所以你的请求也应该同样具体。

第一轮回答之后继续迭代，不要重来

一个高质量的第二轮提示通常像这样：

Revise the Aspire plan using these constraints:
- frontend must stay outside Aspire
- API and worker should run under AppHost
- use PostgreSQL container locally
- produce Kubernetes publish output
- explain what must still be handled by CI/CD

这种迭代方式，通常比重新要一份全新的通用版 aspire guide 更能快速贴合你的真实需求。