aspire-init

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Aspire Init

First-run only. This skill owns the skeleton drop and template choice for repositories that do not yet have an Aspire AppHost. Once the skeleton is in place, hand off to
aspireify
for the actual resource wiring.

仅首次运行适用。本技能负责为尚未拥有Aspire AppHost的仓库完成骨架生成和模板选择。骨架生成完成后，将实际的资源连接工作交接给
aspireify
。

Prerequisites

前提条件

Requirement	Install
.NET 10.0 SDK	https://dotnet.microsoft.com/download
Node.js `^20.19.0` , `^22.13.0` , or `>=24` (TypeScript AppHost)	https://nodejs.org
Aspire CLI (curl installer)	`curl -sSL https://aspire.dev/install.sh \| bash`
Aspire CLI (npm)	`npm install -g @microsoft/aspire-cli`
Aspire CLI (NativeAOT global tool)	`dotnet tool install -g Aspire.Cli` (.NET 10 required)
Diagnose missing prerequisites	`aspire doctor`

Aspire also supports Nix, Homebrew, WinGet, mise, and the curl/PowerShell installers. Use the installation method already owned by the user's environment.

要求	安装方式
.NET 10.0 SDK	https://dotnet.microsoft.com/download
Node.js `^20.19.0` 、 `^22.13.0` 或 `>=24` （TypeScript AppHost）	https://nodejs.org
Aspire CLI（curl安装器）	`curl -sSL https://aspire.dev/install.sh \| bash`
Aspire CLI（npm）	`npm install -g @microsoft/aspire-cli`
Aspire CLI（NativeAOT全局工具）	`dotnet tool install -g Aspire.Cli` （需要.NET 10）
诊断缺失的前提条件	`aspire doctor`

Aspire还支持Nix、Homebrew、WinGet、mise以及curl/PowerShell安装器。请使用用户环境中已采用的安装方式。

Detection

检测逻辑

Activate only when adding Aspire to a workspace that does not yet have one. Confirm ALL of the following before running

aspire init

Signal	How to Detect	Meaning
No C# AppHost	No `.csproj` containing `Aspire.AppHost.Sdk`	OK to init
No file-based AppHost	No `apphost.cs` with `#:sdk Aspire.AppHost.Sdk`	OK to init
No TypeScript AppHost	No current `apphost.mts` or legacy `apphost.ts` in the repo	OK to init
No Aspire config	No `aspire.config.json` in repo root	OK to init
User intent	Explicit "add Aspire", "scaffold Aspire", "aspire init"	OK to init

If any AppHost signal is already present, do not run
aspire init
. Route to

aspireify

(re-wire) or

aspire-orchestration

(lifecycle).

仅在向尚未拥有AppHost的工作区添加Aspire时激活。运行

aspire init

前需确认以下所有条件：

信号	检测方式	含义
无C# AppHost	不存在包含 `Aspire.AppHost.Sdk` 的 `.csproj` 文件	可执行init
无文件型AppHost	不存在包含 `#:sdk Aspire.AppHost.Sdk` 的 `apphost.cs` 文件	可执行init
无TypeScript AppHost	仓库中不存在当前版本的 `apphost.mts` 或旧版 `apphost.ts` 文件	可执行init
无Aspire配置	仓库根目录不存在 `aspire.config.json` 文件	可执行init
用户意图	明确提出“添加Aspire”、“搭建Aspire脚手架”、“aspire init”	可执行init

如果任何AppHost信号已存在，请勿运行
aspire init
。请转至

aspireify

（重新连接资源）或

aspire-orchestration

（生命周期管理）。

Decision:

aspire new

aspire init

决策：

aspire new

aspire init

Situation	Command	Why
Empty directory or brand-new project	`aspire new <template>`	Generates a full starter solution
Existing repo with services to model	`aspire init`	Drops minimal skeleton + `aspire.config.json` next to existing code
User wants a sample to learn from	`aspire new aspire-starter`	Includes ApiService + Web + ServiceDefaults
User wants the smallest possible scaffold	`aspire new aspire-empty` (C#) or `aspire new aspire-ts-empty` (TS)	No resources pre-wired
User wants Python services	`aspire new aspire-py-starter` (TypeScript AppHost drives Python)	Not `dotnet new` — that template was removed in 13.3

See references/templates.md for the complete template list and options.

场景	命令	原因
空目录或全新项目	`aspire new <template>`	生成完整的入门解决方案
包含待建模服务的现有仓库	`aspire init`	在现有代码旁生成最小化骨架 + `aspire.config.json`
用户需要学习用的示例	`aspire new aspire-starter`	包含ApiService + Web + ServiceDefaults
用户需要最小化脚手架	`aspire new aspire-empty` （C#）或 `aspire new aspire-ts-empty` （TS）	无预连接资源
用户需要Python服务	`aspire new aspire-py-starter` （TypeScript AppHost驱动Python）	请勿使用 `dotnet new` ——该模板在13.3版本中已移除

完整模板列表和选项请参考references/templates.md。

Workflow A —

aspire new <template>

(new project)

工作流A —

aspire new <template>

（新项目）

For brand-new projects in an empty or non-existent directory:

Confirm prerequisites with
```
aspire doctor
```
if the CLI install is uncertain.
Pick a template from references/templates.md.

Run the template, append

--non-interactive

for agent flows:

bash

aspire new aspire-starter --name MyApp --output ./MyApp --non-interactive

The new directory is fully wired by the template — no aspireify handoff needed.
Route to
```
aspire-orchestration
```
for first run (
```
aspire start
```
).

若CLI安装情况不确定，使用
```
aspire doctor
```
确认前提条件。
从references/templates.md中选择模板。

运行模板，在Agent流程中添加

--non-interactive

参数：

bash

aspire new aspire-starter --name MyApp --output ./MyApp --non-interactive

新目录已由模板完成完整配置——无需交接给aspireify。
转至
```
aspire-orchestration
```
进行首次运行（
```
aspire start
```
）。

Workflow B —

aspire init

(existing repo)

工作流B —

aspire init

（现有仓库）

For repositories that already contain services (Express API, .NET API, Python service, etc.) and need an AppHost added alongside them:

Verify the Detection table — confirm no AppHost is present.

Run

aspire init

, choosing language explicitly for non-interactive flows:

bash

aspire init --language csharp --non-interactive
# or
aspire init --language typescript --non-interactive

```
aspire init
```
drops:
- The AppHost skeleton (
```
apphost.cs
```
  with
```
#:sdk
```
  directives, or
```
apphost.mts
```
  with the generated
```
.aspire/modules/
```
  folder)
- AppHost configuration describing language + AppHost path
- The aspireify
  agent skill into the project's skill directory (same one
```
aspire agent init
```
  uses)
Hand off to
aspireify
—
```
aspire init
```
does not wire resources, projects, or integrations on its own.

After

aspireify

finishes wiring, validate via

aspire start

(

aspire-orchestration

In 13.5, a TypeScript init inside a repo that already has a root

package.json

creates a nested

aspire-apphost/

package and points the root

aspire.config.json

aspire-apphost/apphost.mts

. A solution-backed C# repo can receive a project-based AppHost; new C# AppHosts enable

AspireUseCliBundle=true

by default. Preserve these generated choices.

See references/init-workflow.md for the full sequence including what

aspire.config.json

contains and what to do if

aspire init

fails partway.

针对已包含服务（Express API、.NET API、Python服务等）且需在旁添加AppHost的仓库：

验证检测逻辑表——确认无AppHost存在。

运行

aspire init

，在非交互式流程中明确指定语言：

bash

aspire init --language csharp --non-interactive
# 或
aspire init --language typescript --non-interactive

```
aspire init
```
会生成：
- AppHost骨架（包含
```
#:sdk
```
  指令的
```
apphost.cs
```
  ，或生成了
```
.aspire/modules/
```
  文件夹的
```
apphost.mts
```
  ）
- 描述语言 + AppHost路径的AppHost配置
- 项目技能目录中的**
```
aspireify
```
  **Agent技能（与
```
aspire agent init
```
  使用的目录相同）
交接给
aspireify
——
```
aspire init
```
本身不会连接资源、项目或集成。
```
aspireify
```
完成资源连接后，通过
```
aspire start
```
验证（
```
aspire-orchestration
```
）。

在13.5版本中，若仓库根目录已存在

package.json

，在其中执行TypeScript init会创建嵌套的

aspire-apphost/

包，并将根目录的

aspire.config.json

指向

aspire-apphost/apphost.mts

。基于解决方案的C#仓库可接收基于项目的AppHost；新的C# AppHost默认启用

AspireUseCliBundle=true

。请保留这些生成的设置。

完整流程（包括

aspire.config.json

的内容以及

aspire init

中途失败的处理方式）请参考references/init-workflow.md。

Handoff Rules

交接规则

After `aspire init` / `aspire new` finishes...	Route To
Skeleton dropped, resources need wiring	→ `aspireify` skill (in-plugin or project-local)
Skeleton dropped, validate it starts	→ `aspire-orchestration` (run `aspire start` )
New project from template, ready to run	→ `aspire-orchestration`
User asks to deploy after init	→ `aspire-deployment`
User asks for logs/traces after init	→ `aspire-monitoring`
Existing AppHost detected — do NOT run init	→ `aspireify` (re-wire) or `aspire-orchestration` (lifecycle)

`aspire init` / `aspire new` 完成后...	转至
骨架已生成，资源需要连接	→ `aspireify` 技能（插件内或项目本地）
骨架已生成，验证是否能启动	→ `aspire-orchestration` （运行 `aspire start` ）
从模板生成新项目，可直接运行	→ `aspire-orchestration`
用户要求在init后部署	→ `aspire-deployment`
用户要求在init后查看日志/追踪	→ `aspire-monitoring`
检测到已有AppHost — 请勿运行init	→ `aspireify` （重新连接）或 `aspire-orchestration` （生命周期管理）

Project-Local Skill Override

项目本地技能覆盖

.agents/skills/aspire-init/SKILL.md

exists project-locally (legacy install from an older

aspire init

run), warn the user and defer to it. The legacy project-local skill may carry repo-specific guidance that should not be overridden by this in-plugin skill.

The project-local

aspireify

skill (installed by

aspire init

) takes precedence over this plugin's in-plugin

aspireify

for the same reason — defer to the project-local copy and warn.

如果项目本地存在

.agents/skills/aspire-init/SKILL.md

（由旧版

aspire init

运行安装的遗留版本），请向用户发出警告并优先使用该版本。遗留的项目本地技能可能包含仓库特定的指导，不应被插件内的技能覆盖。

出于相同原因，

aspire init

安装的项目本地

aspireify

技能优先于插件内的

aspireify

——请优先使用项目本地副本并发出警告。

Error Handling

错误处理

Symptom	Cause	Action
`aspire init` reports AppHost already exists	Repo already has an AppHost	Stop. Route to `aspireify` (re-wire) or `aspire-orchestration` (lifecycle)
`aspire init` fails in non-interactive mode without `--language`	Multiple language paths available	Re-run with `--language csharp` or `--language typescript`
`aspire new` rejects `--output` path	Path exists and is non-empty	Use a different `--output` or empty the directory
`aspire` command not found	CLI not installed	`dotnet tool install -g Aspire.Cli` (.NET 10) or `curl -sSL https://aspire.dev/install.sh \| bash`
`aspire doctor` reports missing .NET 10	SDK missing	Install .NET 10 SDK before retrying
`aspire init` succeeded but no `aspireify` skill installed	Agent skill directory not detected	Run `aspire agent init` to install `aspireify` , then continue wiring
Skeleton dropped but resources not wired	Expected — `aspire init` does not wire	Hand off to `aspireify`
Existing TypeScript AppHost still uses `apphost.ts`	Legacy entry point and package graph	Hand off to `aspire-orchestration` , which owns approval and `aspire update --migrate --yes --non-interactive` ; return to aspireify only for later source authoring

症状	原因	操作
`aspire init` 报告AppHost已存在	仓库已包含AppHost	停止操作。转至 `aspireify` （重新连接资源）或 `aspire-orchestration` （生命周期管理）
`aspire init` 在非交互式模式下未指定 `--language` 时失败	存在多种语言路径可选	使用 `--language csharp` 或 `--language typescript` 重新运行
`aspire new` 拒绝 `--output` 路径	路径已存在且非空	使用其他 `--output` 路径或清空目录
找不到 `aspire` 命令	CLI未安装	执行 `dotnet tool install -g Aspire.Cli` （.NET 10）或 `curl -sSL https://aspire.dev/install.sh \| bash`
`aspire doctor` 报告缺少.NET 10	SDK缺失	先安装.NET 10 SDK再重试
`aspire init` 成功但未安装 `aspireify` 技能	未检测到Agent技能目录	运行 `aspire agent init` 安装 `aspireify` ，然后继续资源连接
骨架已生成但资源未连接	此为预期行为 — `aspire init` 不负责资源连接	交接给 `aspireify`
现有TypeScript AppHost仍使用 `apphost.ts`	遗留入口点和包依赖图	转至 `aspire-orchestration` ，由其负责确认并执行 `aspire update --migrate --yes --non-interactive` ；仅在后续源代码编写时返回aspireify

References

参考资料

templates.md —
```
aspire new
```
templates and options
init-workflow.md —
```
aspire init
```
flow,
```
aspire.config.json
```
layout, and
```
aspireify
```
handoff
aspire-13-5-breaking-changes.md — 13.5.3 versions, migrations, and CLI-bundle behavior

templates.md —
```
aspire new
```
模板及选项
init-workflow.md —
```
aspire init
```
流程、
```
aspire.config.json
```
结构及
```
aspireify
```
交接说明
aspire-13-5-breaking-changes.md — 13.5.3版本、迁移及CLI捆绑包行为

aspire-init

Original

Translation

Aspire Init

Aspire Init

Prerequisites

前提条件

Detection

检测逻辑

Decision:
`aspire new`
vs
`aspire init`

决策：
`aspire new`
vs
`aspire init`

Workflow A —
`aspire new <template>`
(new project)

工作流A —
`aspire new <template>`
（新项目）

Workflow B —
`aspire init`
(existing repo)

工作流B —
`aspire init`
（现有仓库）

Handoff Rules

交接规则

Project-Local Skill Override

项目本地技能覆盖

Error Handling

错误处理

References

参考资料

aspire-init

Original

Translation

Aspire Init

Aspire Init

Prerequisites

前提条件

Detection

检测逻辑

Decision: aspire new vs aspire init

决策：aspire new vs aspire init

Workflow A — aspire new <template> (new project)

工作流A — aspire new <template>（新项目）

Workflow B — aspire init (existing repo)

工作流B — aspire init（现有仓库）

Handoff Rules

交接规则

Project-Local Skill Override

项目本地技能覆盖

Error Handling

错误处理

References

参考资料

Decision:
`aspire new`
vs
`aspire init`

决策：
`aspire new`
vs
`aspire init`

Workflow A —
`aspire new <template>`
(new project)

工作流A —
`aspire new <template>`
（新项目）

Workflow B —
`aspire init`
(existing repo)

工作流B —
`aspire init`
（现有仓库）