umbraco-quickstart

Umbraco 快速入门

通过一条命令完成 Umbraco 扩展开发所需的所有设置。

用法

# Full setup with custom credentials
/umbraco-quickstart MyUmbracoSite MyExtension --email [email protected] --password Admin123456

# With default credentials ([email protected] / SecurePass1234)
/umbraco-quickstart MyUmbracoSite MyExtension

# Just Umbraco instance name (will prompt for extension name)
/umbraco-quickstart MyUmbracoSite

# No arguments (will detect existing or prompt for names)
/umbraco-quickstart

工作流

1. 解析参数

• 第一个参数：Umbraco 项目名称（例如，“MyUmbracoSite”）
• 第二个参数：扩展名称（例如，“MyExtension”）
• --email（可选）：管理员邮箱（默认值：[email protected]）
• --password（可选）：管理员密码（默认值：SecurePass1234）

如果未提供参数，请检查现有内容，并提示用户提供缺少的名称。

2. 检查现有内容

版本检查（首先运行）： 在构建任何内容之前，调用 umbraco-version-guard， 确认站点的 Umbraco 主版本与这些技能所针对的主版本一致。如果不一致， 请停止并引导用户使用匹配的技能系列——不要生成代码。

检查 Umbraco 实例：

find . -name "*.csproj" -exec grep -l "Umbraco.Cms" {} \; 2>/dev/null | head -5

检查扩展项目：

find . -name "umbraco-package.json" 2>/dev/null | head -10

3. 执行操作

如果没有 Umbraco 实例：

• 使用提供的名称（第一个参数），或提示用户提供名称
• 使用 /package-script-writer [ProjectName] 创建

如果没有扩展：

• 使用提供的名称（第二个参数），或提示用户提供名称
• 使用 /umbraco-extension-template [ExtensionName] 创建

如果扩展尚未注册：

• 使用 /umbraco-add-extension-reference [ExtensionName] 注册

4. 提醒用户缺少的可选资源

检查扩展工作区（包括 /add-dir 目录），如果缺少以下资源则提醒用户：

如果未找到 CMS 源码：

⚠ Umbraco CMS source not found in extended workspace.
  For better code generation, add it:
  git clone https://github.com/umbraco/Umbraco-CMS
  /add-dir /path/to/Umbraco-CMS/src/Umbraco.Web.UI.Client

如果未找到 UUI 源码：

⚠ UUI library source not found in extended workspace.
  For UI component reference, add it:
  git clone https://github.com/umbraco/Umbraco.UI
  /add-dir /path/to/Umbraco.UI/packages/uui

如果未安装测试技能：

⚠ Testing skills not installed.
  To add testing capabilities:
  /plugin install umbraco-cms-backoffice-testing-skills@umbraco-backoffice-marketplace

5. 必须：进入计划模式

完成此步骤之前，不得开始构建。

1. 告知用户设置已完成，并显示登录凭据
2. 阅读 umbraco-backoffice 技能中的 PRE-BUILD-PLANNING.md
3. 询问用户想要构建什么

✅ Setup complete! Your extension is ready.

Login: [email protected] / SecurePass1234

What would you like to build? Describe your idea and I'll help you plan the implementation.

Examples:
- "A dashboard that shows recent content changes"
- "A property editor for picking colours"
- "A tree in Settings for managing custom data"

用户描述需求后：

1. 使用 /plan 进入计划模式
2. 按照 PRE-BUILD-PLANNING.md 工作流执行：
   • 绘制 UI 的 ASCII 线框图
   • 标注所需的扩展类型（section、dashboard、workspace 等）
   • 识别 UUI 组件
   • 梳理数据流（上下文、API）
3. 确定要调用哪些子技能
4. 在计划文档中加入以下必需部分（计划获批后将执行这些内容）：

## Pre-Build Setup
- [ ] Load `/umbraco-backoffice` skill for best practices and examples

## Implementation
[Your implementation steps here - skills to invoke, files to create]

## Post-Build Validation (REQUIRED - DO NOT SKIP)

### Step 1: Initial Build
- [ ] Run `npm run build` in extension directory
- [ ] Verify build completes without errors

### Step 2: Code Review
- [ ] Spawn `umbraco-extension-reviewer` agent
- [ ] Fix all Critical/High severity issues

### Step 3: Rebuild (if fixes were made)
- [ ] Run `npm run build` again
- [ ] Verify build still succeeds

### Step 4: Restart Umbraco
- [ ] Stop the running Umbraco instance
- [ ] Run `dotnet run` to restart
- [ ] Wait for startup to complete

### Step 5: Browser Validation
Check if browser automation is available (any of: `dev-browser` skill, Playwright MCP, Claude computer use).

If validating with **Claude-in-Chrome** (`mcp__claude-in-chrome` tools): load the
`umbraco-chrome-navigation` skill first — the backoffice is Lit/shadow-DOM, so the built-in
find/read_page tools and raw screenshots are unreliable; that skill provides the
shadow-DOM-piercing helpers and navigation playbook needed to validate it.

If browser automation IS available:
- [ ] Navigate to backoffice login (http://localhost:5000/umbraco)
- [ ] Login with credentials
- [ ] Navigate to extension location
- [ ] Verify: no console errors, UI renders, interactions work
- [ ] Take screenshot of working extension

If NO browser automation available, output manual testing steps for user.

5. 只有在线框图和所有验证部分都纳入计划后，才能退出计划模式

⚠️ 计划完成并获得用户批准之前，不得生成代码。

目标

帮助用户获得可正常运行且通过验证的扩展。遵循工作流：PLAN → BUILD → VALIDATE。不要只做报告——要采取行动。

默认凭据

创建 Umbraco 实例时，将使用以下默认值：

• 邮箱： [email protected]
• 密码： SecurePass1234

这些值适用于本地开发，且不包含可能导致转义问题的特殊字符。

示例

/umbraco-quickstart MyUmbracoSite MyDashboard

此操作将：

1. 如果 Umbraco 实例不存在，则创建一个（例如，“MyUmbracoSite”）
2. 创建扩展（例如，“MyDashboard”）
3. 在 Umbraco 项目中注册该扩展
4. 在适用时提醒用户缺少 CMS/UUI 源码
5. 进入计划模式，设计扩展（线框图、扩展类型、验证步骤）
6. 使用确定的子技能进行构建
7. 运行 npm run build
8. 运行 umbraco-extension-reviewer 并修复问题
9. 如果进行了修复，则重新构建
10. 重启 Umbraco
11. 在浏览器中验证（如果可以进行浏览器自动化则自动验证，否则提供手动步骤）

登录凭据： [email protected] / SecurePass1234