用途
Aspire Init 是一个“仅首次运行”的工作流技能，用于把 Aspire 添加到一个尚无 Aspire AppHost 的仓库。它只负责生成 AppHost 骨架和选择模板；一旦骨架就位，后续实际的资源接线交由 aspireify 处理。
检测与触发条件
只有在为一个尚无 Aspire 的工作区添加 Aspire 时才会激活。运行 aspire init 前需确认以下全部信号：
- 无 C# AppHost：不存在包含 Aspire.AppHost.Sdk 的 .csproj。
- 无基于文件的 AppHost：不存在带
#:sdk Aspire.AppHost.Sdk的 apphost.cs。 - 无 TypeScript AppHost：仓库中不存在当前的 apphost.mts 或旧的 apphost.ts。
- 无 Aspire 配置：仓库根目录不存在 aspire.config.json。
- 用户意图明确：显式要求“add Aspire”“scaffold Aspire”“aspire init”。
如果任一 AppHost 信号已存在，则不要运行 aspire init，应转交 aspireify（重新接线）或 aspire-orchestration（生命周期）。
aspire new 与 aspire init 的选择
- 空目录或全新项目：使用
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。
前置条件
| 要求 | 安装方式 |
|---|---|
| .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 安装器。请使用用户环境已采用的安装方式。
使用方式
工作流 A —— aspire new <template>（新项目）
针对空目录或不存在的目录中的全新项目：
- 若 CLI 安装状态不确定，用
aspire doctor确认前置条件。 - 从 references/templates.md 选择模板。
- 运行模板，代理流程请追加
--non-interactive：
aspire new aspire-starter --name MyApp --output ./MyApp --non-interactive
新目录已由模板完整接线，无需 aspireify 移交。随后转交 aspire-orchestration 进行首次运行（aspire start）。
工作流 B —— aspire init（已有仓库）
针对已包含服务（Express API、.NET API、Python 服务等）并需要在其旁添加 AppHost 的仓库：
- 核对检测表——确认不存在 AppHost。
- 运行 aspire init，非交互流程需显式选择语言：
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 代理技能写入项目的技能目录（与
aspire agent init使用的是同一个）。在 13.6+ 中，链式代理设置会预选推荐技能（包括 aspireify），并且不提供 Aspire MCP 服务器配置。若成功 init 后缺少 MCP 配置，这是预期行为而非缺陷。MCP 是独立的可选项，参见 aspire 路由器的 Skills vs. MCP 指南。
- 移交给 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。
移交规则
| aspire init / aspire new 完成后…… | 移交至 |
|---|---|
| 骨架已生成，资源需接线 | aspireify 技能（插件内或项目本地） |
| 骨架已生成，需验证可启动 | aspire-orchestration（运行 aspire start） |
| 由模板创建的新项目，已可运行 | aspire-orchestration |
| 用户 init 后询问部署 | aspire-deployment |
| 用户 init 后询问日志/追踪 | aspire-monitoring |
| 检测到已有 AppHost——不要运行 init | aspireify（重新接线）或 aspire-orchestration（生命周期） |
项目本地技能覆盖
如果项目本地存在 .agents/skills/aspire-init/SKILL.md（来自较早 aspire init 运行的旧安装），应警告用户并让位于它。旧的项目本地技能可能带有不应被本插件内技能覆盖的仓库特定指引。
项目本地的 aspireify 技能（由 aspire init 安装）优先于本插件的插件内 aspireify，原因相同——让位于项目本地副本并发出警告。
适用场景
- 首次向仓库引入 Aspire，且尚无 AppHost。
- 需要根据仓库状态（全新项目 vs 已有服务）选择合适模板。
限制与错误处理
| 症状 | 原因 | 处理 |
|---|---|---|
| aspire init 报告 AppHost 已存在 | 仓库已有 AppHost | 停止。转交 aspireify（重新接线）或 aspire-orchestration（生命周期） |
| 非交互模式下缺少 --language 导致 aspire init 失败 | 存在多条语言路径 | 使用 --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 技能 | 未检测到代理技能目录，或未选择 aspireify（13.5 不预选它） | 运行 aspire agent init --non-interactive --skills aspireify（把 aspireify 追加到任何显式 --skills 列表，保留任何 --skill-locations，且不要添加 --mcp），然后继续接线 |
| aspire init 成功但未写入 MCP 配置 | 13.6+ 中的预期行为——链式代理设置不提供 MCP | 不要修复它。仅在用户明确要求时配置 MCP（13.6+ 上 aspire agent init --mcp） |
| 骨架已生成但资源未接线 | 预期——aspire init 不接线 | 移交给 aspireify |
| 已有 TypeScript AppHost 仍使用 apphost.ts | 旧入口点与包图 | 移交 aspire-orchestration，由其负责批准与 aspire update --migrate --yes --non-interactive；稍后仅在源代码编写时回到 aspireify |
参考资料
- templates.md——aspire new 模板与选项
- init-workflow.md——aspire init 流程、aspire.config.json 布局与 aspireify 移交
- aspire-13-5-breaking-changes.md——13.5 迁移、CLI-bundle 行为以及对受影响版本的修复