aspire

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Aspire

Use this skill when the task involves an Aspire distributed application — operating the AppHost or its resources through the Aspire CLI rather than falling back to ad-hoc

dotnet

docker

, or shell workflows.

当任务涉及Aspire分布式应用时使用此技能——通过Aspire CLI操作AppHost或其资源，而非使用临时的

dotnet

、

docker

或Shell工作流。

Triage first

先进行分类排查

Two intents are commonly misread — resolve them before doing anything else:

"Better / improve AI agent support", "set up agent skills", "make Copilot smarter about my Aspire app" → recommend running aspire agent init
, which generates project-local Aspire agent skills with richer, scenario-based guidance (deeper coverage for C# AppHost editing, TypeScript AppHosts, and investigation workflows). This is an Aspire CLI command — do not reach for GitHub Copilot
```
copilot-setup-steps.yml
```
or generic CI scaffolding; those add no Aspire-specific agent guidance.
"Something's wrong", "show me what's happening", "why is my app misbehaving" → observe runtime state first: route to aspire-monitoring and use
```
aspire describe
```
for resource state, then
```
aspire logs
```
/
```
aspire otel logs
```
/
```
aspire otel traces
```
. Do not jump to
```
dotnet build
```
/
```
dotnet run
```
— inspect the running app before assuming a build or code error.

有两种意图常被误判——在执行其他操作前需先解决：

“优化/改进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
```
——在假设是构建或代码错误前，先检查运行中的应用。

Detection

触发条件

Activate when ANY signal is present. Use the Scope column to decide whether to route to the bootstrap skills (

aspire-init

aspireify

) or to a runtime sub-skill:

Signal	How to Detect	Confidence	Scope
C# AppHost	`.csproj` containing `Aspire.AppHost.Sdk`	✅ Definitive	AppHost present → orchestration / deployment / monitoring
File-based C# AppHost	`apphost.cs` with `#:sdk Aspire.AppHost.Sdk`	✅ Definitive	AppHost present → orchestration / deployment / monitoring
TypeScript AppHost	`apphost.ts` file in project	✅ Definitive	AppHost present → orchestration / deployment / monitoring
Aspire config without AppHost	`aspire.config.json` present and no AppHost above	High	Bootstrap → `aspireify` (skeleton dropped, needs wiring)
Aspire config with AppHost	`aspire.config.json` present and AppHost above	High	AppHost present → orchestration / deployment / monitoring
Aspire settings	`.aspire/` directory present	High	AppHost present (usually)
Generated TS modules	`.aspire/modules/` directory present	High	AppHost present (TS)
Service defaults	`Aspire.ServiceDefaults` in project references	Medium	AppHost present
No AppHost, no `aspire.config.json`	None of the above and user asks to add Aspire	n/a	Bootstrap → `aspire-init` (skeleton drop)

只要存在任一信号即可激活。使用**Scope（范围）**列决定路由至引导技能（

aspire-init

aspireify

）还是运行时子技能：

信号	检测方式	置信度	范围
C# AppHost	包含 `Aspire.AppHost.Sdk` 的 `.csproj` 文件	✅ 确定	存在AppHost → 编排/部署/监控
基于文件的C# AppHost	包含 `#:sdk Aspire.AppHost.Sdk` 的 `apphost.cs` 文件	✅ 确定	存在AppHost → 编排/部署/监控
TypeScript AppHost	项目中的 `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` （生成骨架）

Default Workflow

默认工作流

Bootstrap branch — if no AppHost exists in the repo, route to
```
aspire-init
```
for the skeleton drop. If an AppHost stub exists but is unwired (no resources declared), route to
```
aspireify
```
. Only continue with the steps below once a wired AppHost is present.
Confirm workspace is Aspire — identify the AppHost
```
aspire start
```
(or
```
aspire start --isolated
```
in worktrees or whenever shared local state is risky)
```
aspire wait <resource>
```
before interacting with any resource

Inspect state with

aspire describe

aspire otel logs

aspire logs

aspire otel traces

, and

aspire export

before making code changes

Before adding integrations, use
```
aspire integration search <query>
```
when the package is unknown, then
```
aspire add <package>
```
when ready to mutate the AppHost
When code changes, decide whether the AppHost model changed or only one resource changed. Re-run
```
aspire start
```
after AppHost changes; otherwise prefer resource commands, runtime watch/HMR, dashboard actions, or IDE-managed debugging as appropriate.

引导分支 — 如果仓库中无AppHost，路由至
```
aspire-init
```
生成骨架。如果存在AppHost stub但未配置（未声明资源），路由至
```
aspireify
```
。仅当配置好的AppHost存在时，才继续执行以下步骤。
确认工作区为Aspire环境——识别AppHost
执行
```
aspire start
```
（在工作树或共享本地状态存在风险时，使用
```
aspire start --isolated
```
）
在与任何资源交互前执行
```
aspire wait <resource>
```

在修改代码前，使用

aspire describe

、

aspire otel logs

、

aspire logs

、

aspire otel traces

和

aspire export

检查状态

添加集成前，若不了解包信息，使用
```
aspire integration search <query>
```
；准备修改AppHost时，使用
```
aspire add <package>
```
代码变更后，判断是AppHost模型变更还是仅单个资源变更。AppHost变更后需重新执行
```
aspire start
```
；否则优先使用资源命令、运行时热重载/HMR、仪表盘操作或IDE管理的调试功能。

Key Rules

核心规则

Always
```
aspire start
```
, never
```
dotnet run
```
on AppHosts
Always
```
aspire wait <resource>
```
, never manual HTTP polling

Use

aspire resource <resource-name> <command>

for resource operations such as

stop

start

, or

rebuild

when available

Do not stop or restart the whole AppHost just because one resource changed
Use
```
features.defaultWatchEnabled
```
only for Aspire default watch; do not treat it as per-resource rebuild, restart, or hot reload
Prefer a resource's own framework/runtime hot reload, HMR, or watch workflow when it already handles the change
Always
```
aspire docs search <topic>
```
before editing unfamiliar AppHost APIs

Always

aspire docs api search <query> --language csharp|typescript

for API reference before editing AppHost code

Always
```
--non-interactive
```
for agent execution

Use

aspire integration list --format Json

and

aspire integration search <query> --format Json

for read-only integration discovery

Never install the obsolete Aspire workload
Never edit
```
.aspire/modules/
```
directly in TypeScript AppHosts

始终执行
```
aspire start
```
，绝不在AppHost上执行
```
dotnet run
```
始终执行
```
aspire wait <resource>
```
，绝不手动进行HTTP轮询

若可用，使用

aspire resource <resource-name> <command>

执行资源操作，如

stop

、

start

或

rebuild

不要仅因单个资源变更就停止或重启整个AppHost
仅将
```
features.defaultWatchEnabled
```
用于Aspire默认监听；不要将其视为针对单个资源的重建、重启或热重载
若资源自身框架/运行时已支持热重载、HMR或监听工作流，优先使用该资源自带的功能
在编辑不熟悉的AppHost API前，始终执行
```
aspire docs search <topic>
```

在编辑AppHost代码前，始终执行

aspire docs api search <query> --language csharp|typescript

查看API参考

Agent执行时始终使用
```
--non-interactive
```
参数

使用

aspire integration list --format Json

和

aspire integration search <query> --format Json

进行只读集成发现

绝不安装已废弃的Aspire工作负载
在TypeScript AppHost中绝不直接编辑
```
.aspire/modules/
```

Routing

路由规则

Task	Route To
Start, stop, wait, restart, rebuild	→ aspire-orchestration
Create a new Aspire project from a template ( `aspire new` )	→ aspire-init (in-plugin)
Add Aspire to an existing repo ( `aspire init` , drop skeleton)	→ aspire-init (in-plugin)
Wire AppHost / scaffold resource graph / add integrations after `aspire init`	→ aspireify (in-plugin)
Deploy, publish, destroy, pipeline steps	→ aspire-deployment
Logs, traces, metrics, dashboard, browser logs	→ aspire-monitoring
Diagnose a running app — "something's wrong", "show me what's happening", investigate errors / health / unexpected behavior	→ aspire-monitoring — start with `aspire describe` for resource state, then `aspire logs` / `aspire otel logs` / `aspire otel traces` ; investigate before editing code
Improve AI agent support / generate project-local Aspire agent skills	→ run `aspire agent init` (see below)
Deployed app monitoring (Azure)	→ `azure-diagnostics` skill (azure-skills plugin)

任务	路由至
启动、停止、等待、重启、重建	→ aspire-orchestration
从模板创建新Aspire项目（ `aspire new` ）	→ aspire-init（插件内）
向现有仓库添加Aspire（ `aspire init` ，生成骨架）	→ aspire-init（插件内）
在 `aspire init` 生成骨架后配置AppHost/搭建资源图/添加集成	→ aspireify（插件内）
部署、发布、销毁、流水线步骤	→ aspire-deployment
日志、追踪、指标、仪表盘、浏览器日志	→ aspire-monitoring
诊断运行中的应用——“出问题了”、“看看发生了什么”、排查错误/健康状态/异常行为	→ aspire-monitoring — 先使用 `aspire describe` 查看资源状态，再使用 `aspire logs` / `aspire otel logs` / `aspire otel traces` ；排查后再编辑代码
优化AI Agent支持/生成项目本地Aspire Agent技能	→ 执行 `aspire agent init` （见下文）
已部署应用的监控（Azure）	→ `azure-diagnostics` 技能（azure-skills插件）

Improving AI agent support (

aspire agent init

)

优化AI Agent支持（

aspire agent init

）

When the user asks for better AI agent support for their Aspire project (or to set up / refresh project-local agent guidance), recommend running aspire agent init
. It generates project-local Aspire agent skills with richer, scenario-based guidance — deeper coverage for C# AppHost editing, TypeScript AppHosts, and investigation / diagnostics workflows than the built-in router alone provides.

当用户要求为其Aspire项目优化AI Agent支持（或设置/刷新项目本地Agent指导）时，建议运行**

aspire agent init

。该命令会生成项目本地的Aspire Agent技能，提供比内置路由更丰富的场景化指导——针对C# AppHost编辑**、TypeScript AppHost以及排查/诊断工作流的覆盖更深入。

Sub-Skills

子技能

aspire-init

First-run flow only. Owns the skeleton drop for repos that do not yet have an AppHost — picks

aspire new <template>

(greenfield) or

aspire init

(existing repo), runs the CLI, and hands off to

aspireify

for the actual wiring. Self-deactivates once the skeleton is in place. Do not use it on a repo that already contains an AppHost.

仅用于首次运行流程。负责为尚未拥有AppHost的仓库生成骨架——选择

aspire new <template>

（全新项目）或

aspire init

（现有仓库），执行CLI命令，然后将后续配置工作移交至

aspireify

。骨架生成后自动停用。请勿在已包含AppHost的仓库中使用。

aspireify

Agentic AppHost wiring after

aspire init

lands the skeleton. Scans the repo, proposes a resource graph (Postgres / Redis / Rabbit / etc.), edits the AppHost (C#, file-based C#, or TypeScript), wires

Aspire.ServiceDefaults

+ OTel, validates with

aspire start

, then self-deactivates. Owns current AppHost authoring patterns (

AddNextJsApp

AddViteApp

WithBrowserLogs()

, generated

.aspire/modules/

, unified TS

withEnvironment

, endpoint references, and config/secret migration).

在

aspire init

生成骨架后，负责Agent化的AppHost配置。扫描仓库，生成资源图建议（Postgres/Redis/Rabbit等），编辑AppHost（C#、基于文件的C#或TypeScript），配置

Aspire.ServiceDefaults

+ OTel，通过

aspire start

验证，然后自动停用。负责当前AppHost的编写模式（

AddNextJsApp

、

AddViteApp

、

WithBrowserLogs()

、生成的

.aspire/modules/

、统一TS

withEnvironment

、端点引用以及配置/密钥迁移）。

aspire-orchestration

Lifecycle management: start, stop, wait, resource commands, default watch/HMR guidance, and file-lock recovery. Safety guardrails that prevent agent self-harm. Owns

aspire ps

aspire describe

--include-hidden

inspection and CLI upgrades (

aspire update --self

). Does not edit AppHost code — defers to

aspireify

for wiring.

生命周期管理：启动、停止、等待、资源命令、默认监听/HMR指导以及文件锁恢复。防止Agent误操作的安全防护规则。负责

aspire ps

aspire describe

--include-hidden

检查以及CLI升级（

aspire update --self

）。不编辑AppHost代码——将配置工作移交至

aspireify

。

aspire-deployment

Multi-target deployment and tear-down:

aspire deploy

aspire publish

aspire destroy

aspire do <step>

. Targets: Azure Container Apps, App Service, AKS, Kubernetes (Helm), Docker Compose. Owns current deployment surfaces (Front Door, NSP, AKS hosting, Foundry

AddPromptAgent

, JS

PublishAs*

--pipeline-log-level

) and 13.4 API naming.

多目标部署与销毁：

aspire deploy

、

aspire publish

、

aspire destroy

、

aspire do <step>

。支持的目标：Azure容器应用、App Service、AKS、Kubernetes（Helm）、Docker Compose。负责当前部署功能（Front Door、NSP、AKS托管、Foundry

AddPromptAgent

、JS

PublishAs*

、

--pipeline-log-level

）以及13.4版本的API命名。

aspire-monitoring

Observability:

aspire logs

aspire otel

aspire describe

aspire export

aspire dashboard run

. Routes between local Aspire CLI diagnostics, AKS workload tooling, and deployed-Azure platform tools. Surfaces dashboard features (notification center, Rebuild command, browser-logs telemetry).

可观测性：

aspire logs

、

aspire otel

、

aspire describe

、

aspire export

、

aspire dashboard run

。在本地Aspire CLI诊断、AKS工作负载工具和已部署Azure平台工具之间进行路由。展示仪表盘功能（通知中心、重建命令、浏览器日志遥测）。

Project-Local Skill Override

项目本地技能覆盖

If any of the following exist project-locally (from

aspire agent init

or Aspire

aspire init

), warn the user and defer to the project-local copy — repo-specific guidance there should not be overridden by the in-plugin sibling:

Project-local file	Precedence
`.agents/skills/aspire/SKILL.md`	This file (top-level router) defers to it for deeper C# / TS AppHost editing, Playwright handoff, investigation workflows.
`.agents/skills/aspireify/SKILL.md`	The in-plugin `aspireify` sibling defers to it for AppHost wiring.
`.agents/skills/aspire-init/SKILL.md`	The in-plugin `aspire-init` sibling defers to it for the skeleton/first-run flow.

Safety guardrails from this plugin always apply even when project-local skills are active.

如果项目本地存在以下任一文件（来自

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` 会优先使用它进行骨架/首次运行流程。

即使项目本地技能处于激活状态，本插件的安全防护规则仍始终适用。

Prerequisites

前置要求

Requirement	Install
.NET 10.0 SDK	https://dotnet.microsoft.com/download
Aspire CLI (curl/PowerShell)	`curl -sSL https://aspire.dev/install.sh \| bash`
Aspire CLI (NativeAOT global tool, .NET 10)	`dotnet tool install -g Aspire.Cli`

Either install method works. The

dotnet tool install

path produces a NativeAOT binary (instant startup, no JIT warmup) and is recommended when .NET 10 is already present.

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

两种安装方式均有效。若已安装.NET 10，推荐使用

dotnet tool install

方式，该方式会生成NativeAOT二进制文件（启动速度快，无需JIT预热）。

References

参考资料

aspire-13-3-breaking-changes.md — Every 13.3 breaking change to scrub from agent-generated code, scripts, and CI snippets (rename of
```
--log-level
```
, dashboard MCP removal,
```
NameOutput
```
→
```
NameOutputReference
```
,
```
AddAndPublishPromptAgent
```
removal, TS
```
withEnvironment*
```
deprecation, and the full 13.2 → 13.3 migration checklist).
aspire-orchestration/references/agent-workflows.md — Common agent workflows: worktrees, code changes, investigation, integrations, TypeScript generated APIs, secrets, deployment, and Playwright handoff.
aspire-orchestration/references/app-commands.md — App lifecycle, bootstrap, update, restore, docs, and integration discovery commands.
aspire-orchestration/references/resource-management.md — Resource wait and resource-command guidance.
aspire-monitoring/references/monitoring.md — App state, logs, traces, search filtering, dashboard links, and export workflows.
aspire-monitoring/references/playwright-handoff.md — Playwright handoff after Aspire endpoint discovery.
aspire-deployment/SKILL.md — Deployment and pipeline-step workflows.
aspireify/references/apphost-wiring.md — C# and TypeScript AppHost API lookup and wiring patterns.

aspire-13-3-breaking-changes.md — 13.3版本的所有破坏性变更，需从Agent生成的代码、脚本和CI片段中移除（包括
```
--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查找与配置模式。

aspire

Original

Translation

Aspire

Aspire

Triage first

先进行分类排查

Detection

触发条件

Default Workflow

默认工作流

Key Rules

核心规则

Routing

路由规则

Improving AI agent support (
`aspire agent init`
)

优化AI Agent支持（
`aspire agent init`
）

Sub-Skills

子技能

aspire-init

aspire-init

aspireify

aspireify

aspire-orchestration

aspire-orchestration

aspire-deployment

aspire-deployment

aspire-monitoring

aspire-monitoring

Project-Local Skill Override

项目本地技能覆盖

Prerequisites

前置要求

References

参考资料

aspire

Original

Translation

Aspire

Aspire

Triage first

先进行分类排查

Detection

触发条件

Default Workflow

默认工作流

Key Rules

核心规则

Routing

路由规则

Improving AI agent support (aspire agent init)

优化AI Agent支持（aspire agent init）

Sub-Skills

子技能

aspire-init

aspire-init

aspireify

aspireify

aspire-orchestration

aspire-orchestration

aspire-deployment

aspire-deployment

aspire-monitoring

aspire-monitoring

Project-Local Skill Override

项目本地技能覆盖

Prerequisites

前置要求

References

参考资料

Improving AI agent support (
`aspire agent init`
)

优化AI Agent支持（
`aspire agent init`
）