aspire

aspire skill 概覽

aspire skill 能幫你完成什麼

aspire skill 適合需要建立、執行、除錯、設定或發佈 Aspire 型分散式應用程式的使用者，不必再把零散文件東拼西湊成工作流程。當你的實際目標不是「從理論上學會 Aspire」，而是「把 AppHost 跑起來、正確串接各項服務、檢查失敗原因，並準備好可部署的產出」時，這個 aspire skill 特別有用。

誰適合使用 aspire

最適合的讀者包括：

• 正在評估 Aspire 是否適合作為多服務應用本機協調工具的開發者
• 想在既有 API、容器或可執行程式外層加入 AppHost 的團隊
• 希望 AI 助理協助處理 aspire install、初始化、疑難排解與部署導向發佈流程的使用者
• 同時混用 .NET AppHost 與 Python、Node.js、Go、Java 或容器化服務的多語言技術團隊

這個 aspire skill 有什麼不同

這個 aspire skill 比一般泛用 prompt 更強的地方，在於它會依任務把代理導向正確的參考路徑：

• CLI 用法與安裝細節在 references/cli-reference.md
• AppHost 與執行期概念在 references/architecture.md
• dashboard 與可觀測性工作流程在 references/dashboard.md
• 依目標平台發佈的指引在 references/deployment.md
• 透過 MCP 進行整合項目探索在 references/integrations-catalog.md

這點很重要，因為 Aspire 有一套明確的心智模型：AppHost 用來定義資源與相依關係，而 runtime 與 dashboard 則協助你在本機操作與觀察它們。

安裝 aspire 前的核心判斷點

如果你想用一個以程式碼定義的集中位置，統籌服務、相依套件、端點、日誌、追蹤，以及針對目標平台產生發佈產物，那就適合用 Aspire。
但如果你期待一條指令就能直接完成正式環境部署，就不該選它：repo 已明確說明，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. 只載入與你目前任務相符的 reference 檔案，不必全部一起讀

建議閱讀順序：

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

如何安裝 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 app
• 在既有 solution 中加入 AppHost
• 串接像 Redis 或 PostgreSQL 這類相依服務
• 執行並除錯本機分散式應用
• 為 Docker 或 Kubernetes 發佈 Aspire 輸出
• 排查啟動、健康檢查或服務探索問題

像「help with Aspire」這種過於籠統的請求，會迫使代理猜測你的需求。
相對地，像「幫我為 API、Redis 和 Python worker 建好 AppHost，並準備 Docker publish output」這樣的描述，就足以讓代理使用正確的參考資料。

aspire skill 需要哪些輸入資訊

如果你希望輸出品質高，請提供：

• 目前 repo 的結構
• 目標使用的語言與 runtime
• 是否已經有 AppHost
• 本機 runtime 限制，例如是否可用 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 prompt

一個好的 aspire guide prompt，通常會包含五個部分：

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.

真正要用時，應先讀哪些 repository 檔案

如果你正在評估是否採用 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：如果本機協調流程出了問題

這樣的結構很實用：這個 skill 是以 reference 為核心，所以品質取決於你是否載入正確檔案，而不是把所有檔案一次塞進去。

aspire 實際使用流程

典型的 aspire 使用流程通常如下：

1. 建立或開啟 AppHost
2. 定義資源與 references
3. 用 aspire run 在本機執行
4. 在 dashboard 檢查資源狀態、logs、endpoints 與 traces
5. 反覆調整設定
6. 針對部署目標發佈 artifacts

這樣的流程比一開始就直接跳到部署更合理，因為 Aspire 的設計取向本來就優先強調本機協調與可觀測性。

正確理解 aspire for Deployment 的用法

對 aspire for Deployment 來說，最關鍵的事實是：aspire publish 會產生部署產物，但不會直接替你部署。

參考資料中的範例如下：

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

選型建議：

• 如果你想讓部署產物直接從本機使用的同一套 AppHost 模型推導出來，就適合選 Aspire
• 如果你期待單一工具同時負責定義應用與完整管理正式環境 rollout，就不適合選它

什麼情況下該走 MCP 路徑

當你希望助理能檢查正在執行的應用，或不用手動搜尋就能抓到整合文件時，aspire skill 搭配 MCP 特別有價值。

references/mcp-server.md 說明了 aspire mcp init，它會設定支援的 AI 環境，並可建立 .vscode/mcp.json 與 AGENTS.md。這對導入很重要，因為它能縮小「助理知道 Aspire 概念」與「助理真的看得到我的資源、logs 與 traces」之間的落差。

能明顯提升輸出品質的實務建議

• 明確說明你的 workload 是 .NET project、container 還是 executable；Aspire 對它們的建模方式不同。
• 盡早提到本機 runtime 是否可用。多語言應用即使由 .NET AppHost 協調，仍可能需要先安裝對應語言的 runtime。
• 直接要求 startup order 與 dependency wiring；這正是 AppHost 的價值所在。
• 如果最終目標是部署，請要求代理把本機協調選擇與 publish target 的選擇分開說明。
• 如果某個指令失敗，請附上完整指令，以及從 dashboard 或 logs 觀察到的狀態，而不只是說「it didn’t work」。

aspire skill 常見問題

aspire skill 適合新手嗎

適合，但前提是你對多服務應用已經有基本概念。aspire skill 能降低新手最常遇到的幾個阻力點：哪些 CLI 指令最重要、AppHost 到底負責什麼、dashboard 行為要去哪裡看，以及為什麼 publish 不等於 deploy。

aspire skill 的適用邊界是什麼

aspire skill 涵蓋本機協調、AppHost 概念、整合項目探索、MCP 設定、dashboard 工作流程、疑難排解，以及以 publish 為導向的部署前準備。它不能完整取代平台專屬的 CI/CD、叢集營運，或雲端安全設計。

aspire skill 為什麼比一般 prompt 更好

一般 prompt 可能會產生看似合理、實際卻不正確的設定建議。當你需要下列內容時，aspire skill 會更可靠：

• 依版本調整的 CLI 指引
• 正確區分 publish 與 deploy
• 多語言 hosting 模式
• dashboard 與 troubleshooting 路徑
• 透過 MCP 工具進行 integration discovery

aspire 只適合 .NET 團隊嗎

不是。參考資料已明確涵蓋多語言 workload。雖然 AppHost 本身仍以 .NET 為基礎，但被協調的服務可以是其他語言的容器或可執行程式。因此 Aspire 適合混合技術棧，不只限於純 .NET solution。

什麼情況下不該使用 aspire

以下情況建議跳過 Aspire：

• 你只需要單一程序應用
• 團隊已經有很適合的本機協調標準流程
• 你需要的是直接管理正式環境部署，而不是產生 artifacts
• 你的環境無法支援所需的本機 runtime 或容器工具

安裝 aspire 一定需要 Docker 嗎

不一定，但很多實際的 Aspire 工作流程都會受益於容器支援。architecture reference 提到，容器可以透過 Docker 或 Podman 這類本機 runtime 執行，而 executable 則會以原生程序方式執行。實際需求仍取決於你打算協調哪些資源。

如何提升 aspire skill 的效果

給 aspire skill 具體的架構輸入

想最快提升 aspire skill 的輸出品質，最有效的方法就是不要再問抽象範例，而是直接提供你的真實拓樸：

• 服務名稱
• port 或 endpoint 期待
• 相依關係圖
• 本機 runtime 限制
• 目標 publish 平台

這樣能得到更好的 AppHost 建議、更乾淨的 endpoint wiring，也能減少空泛的 placeholder。

要求輸出拆成可部署的區塊

不要只說「build me an Aspire setup」，改成要求：

• AppHost code
• 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」

這樣可以避免把架構、runtime 行為與部署概念混在一起，導致回答失焦。

常見失誤：把本機協調和正式環境部署混為一談

導入 Aspire 最常見的錯誤之一，就是誤以為 Aspire 本身會直接部署到正式環境。如果第一版回答往這個方向偏掉，應立刻修正：要求它先產出 publish artifacts，再另外規劃一份 CI/CD 交接方案。這樣才能讓 aspire guide 保持實用且正確。

常見失誤：忽略相依與健康狀態假設

如果服務啟動順序不對或 discovery 失敗，請要求代理明確建模：

• 資源之間的 references
• wait/health 行為
• 由相依項目推導出的 environment variables
• 對外 endpoint 曝露需求

這正是模糊的 aspire usage 請求最容易表現不佳的地方。

透過可觀測證據提升疑難排解品質

如果你希望 aspire skill 幫你除錯，請提供：

• 使用的 aspire run 指令
• dashboard 中各資源的狀態
• 出錯資源的 logs
• 問題屬於啟動、連線，還是 publish 相關失敗

可觀測的證據，比一大段程式碼傾倒上來更重要。

在 aspire for Deployment 中加入目標限制條件

針對 aspire for Deployment，請直接說明你的平台需求：

• Docker Compose artifacts
• Kubernetes manifests
• Helm-friendly output
• 不同環境的設定邊界
• replica 或 ingress 期待

deployment reference 已清楚指出，publish output 會因目標而異，所以你的需求也應該具體到目標層級。

第一輪回答後要迭代，不要重來

一個有力的第二輪 prompt 通常像這樣：

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 更能提升貼合度。