mcpField
A
aspire-init

aspire-init

github.com/microsoft开发93751 次安装2 周前更新
代码仓库

关于 aspire-init

aspire-init 是用于在仓库中引入 Aspire 或创建新 Aspire 项目的 Agent 技能。它选择合适的模板，或添加最小 AppHost 骨架；对于现有仓库，则将资源接线交给 aspireify。

主要功能

  1. 01检查现有 AppHost 文件
  2. 02选择 aspire new 或 aspire init
  3. 03通过模板创建项目
  4. 04为现有仓库添加骨架
  5. 05将资源接线交给 aspireify

适用场景

  1. 01从模板启动新的 Aspire 项目
  2. 02在现有服务旁添加 AppHost 骨架
  3. 03判断现有工作区是否可初始化

MCP 相关

该技能说明，MCP 服务配置需单独选择；Aspire 13.6 及更高版本的串联 Agent 设置不会创建此配置。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/microsoft/aspire-skills --skill aspire-init

安装后在 Claude Code 中输入/aspire-init确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

evals/
eval.yaml
references/
init-workflow.md
templates.md

详细介绍

Aspire Init

仅用于首次运行。 此技能负责为尚无 Aspire AppHost 的代码仓库添加基础骨架并选择模板。骨架就位后，移交给 aspireify 来实际连接资源。

先决条件

要求安装
.NET 10.0 SDKhttps://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 安装程序。 使用用户环境现有的安装方式。

检测

仅当为尚未包含 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可以初始化
用户意图明确提出“添加 Aspire”“搭建 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。

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

适用于空目录或尚不存在的目录中的全新项目：

  1. 如果不确定 CLI 是否已安装，请运行 aspire doctor 确认先决条件。
  2. 从 references/templates.md 中选择模板。
  3. 运行模板；在 Agent 流程中追加 --non-interactive： 
    aspire new aspire-starter --name MyApp --output ./MyApp --non-interactive
  4. 模板会为新目录完成全部连接——无需移交给 aspireify。
  5. 首次运行时（aspire start），转交给 aspire-orchestration。

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

对于已有服务（Express API、.NET API、Python 服务等）的仓库，需要在旁边添加 AppHost：

  1. 查看 检测 表 — 确认没有 AppHost。
  2. 运行 aspire init，在非交互式流程中明确选择语言： 
    aspire init --language csharp --non-interactive
# or
aspire init --language typescript --non-interactive
  3. aspire init 会生成：
    • AppHost 骨架（包含 #:sdk 指令的 apphost.cs，或包含生成的 .aspire/modules/ 文件夹的 apphost.mts）
    • 描述语言和 AppHost 路径的 AppHost 配置
    • 放入项目技能目录的 aspireify Agent 技能（与 aspire agent init 使用的目录相同）。在 13.6+ 中，串联的 Agent 设置会预选推荐技能，包括 aspireify，且不会提供 Aspire MCP 服务配置选项。如果成功初始化后缺少 MCP 配置，这是预期行为，并非缺陷。MCP 是单独选择启用的选项；请参阅 aspire 路由器的 Skills vs. MCP 指南。
  4. 移交给 aspireify — aspire init 不会自行连接资源、项目或集成。
  5. aspireify 完成连接后，通过 aspire start 验证 (aspire-orchestration)。

在 13.5 中，如果 TypeScript 初始化是在已有根目录 package.json 的仓库中进行，会创建嵌套的 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
用户在初始化后要求部署→ aspire-deployment
用户在初始化后要求查看日志/跟踪记录→ aspire-monitoring
检测到现有 AppHost — 不要运行 init→ aspireify（重新连接）或 aspire-orchestration（生命周期管理）

项目本地技能覆盖

如果项目本地存在 .agents/skills/aspire-init/SKILL.md（由较早版本的 aspire init 安装），请提醒用户并遵循该文件。旧版项目本地技能可能包含特定于仓库的指南，不应被此插件内技能覆盖。

出于相同原因，项目本地的 aspireify 技能（由 aspire init 安装）优先于此插件内的 aspireify；请遵循项目本地副本并提醒用户。

错误处理

症状原因操作
aspire init 报告 AppHost 已存在仓库中已有 AppHost停止。转交给 aspireify（重新接线）或 aspire-orchestration（生命周期管理）
在非交互模式下，aspire init 未提供 --language 时失败有多种语言路径可用使用 --language csharp 或 --language typescript 重新运行
aspire new 拒绝 --output 路径路径已存在且非空使用其他 --output，或清空该目录
找不到 aspire 命令未安装 CLI安装 .NET 10 时运行 dotnet tool install -g Aspire.Cli，或运行 curl -sSL https://aspire.dev/install.sh | bash
aspire doctor 报告缺少 .NET 10缺少 SDK重试前安装 .NET 10 SDK
aspire init 已成功，但未安装 aspireify 技能未检测到 Agent 技能目录，或未选择 aspireify（13.5 不会预选该技能）运行 aspire agent init --non-interactive --skills aspireify（将 aspireify 附加到任何显式的 --skills 列表中，保留所有 --skill-locations，且不要添加 --mcp），然后继续接线
aspire init 已成功，但未写入 MCP 配置13.6+ 中的预期行为——串联的 Agent 设置不会提供 MCP不要修复。仅在用户明确提出要求时配置 MCP（13.6+ 上运行 aspire agent init --mcp）
已生成骨架，但资源未接线这是预期行为——aspire init 不负责接线转交给 aspireify
现有 TypeScript AppHost 仍使用 apphost.ts旧版入口点和包依赖图转交给负责审批和 aspire update --migrate --yes --non-interactive 的 aspire-orchestration；仅在后续源代码编写时再交回 aspireify

参考资料

评论

支持 Markdown