用途:Umbraco 后台 API 在不同主版本间会变化(树数据源、认证、OpenAPI 注册等),该技能用于避免把针对某一主版本的技能应用到其他主版本站点上,从而产生看似正确实则错误的代码。它是预检步骤,应在任何 Umbraco 后台任务开始、编写代码之前先运行;入口技能(umbraco-quickstart、umbraco-backoffice、umbraco-extension-template)会将其作为第一步引用。仅在工作区发生变化时才需重跑。
主要能力与用法:
- 确定目标主版本:读取已安装插件的版本(为主要来源),取其首位数字作为 TARGET_MAJOR。命令:cat "${CLAUDE_PLUGIN_ROOT}/.claude-plugin/plugin.json" 2>/dev/null || cat ../../.claude-plugin/plugin.json 2>/dev/null | grep -m1 '"version"' | grep -oE '[0-9]+' | head -1。若路径无法解析,回退到市场版本,再回退到同级技能声明的值;无法确定时应说明并跳过,不得凭空猜测。
- 检测站点主版本:按顺序尝试并在首个得到数字的信号处停止。A. Umbraco.Cms 包引用(准据,覆盖 .csproj 的 PackageReference 与集中包管理的 .props):grep -rhoE 'Umbraco\.Cms"[^0-9][0-9]+' --include='.csproj' --include='.props' . 2>/dev/null | grep -oE '[0-9]+$' | sort -u。B. 回退到后台客户端依赖主版本(处理 ^18.0.0、~18.0.0、18.0.0):grep -rhoE '"@umbraco-cms/backoffice":[^0-9][0-9]+' --include='package.json' . 2>/dev/null | grep -oE '[0-9]+$' | sort -u。C. 最后手段为运行中实例的 Server Information API(需站点在线,优先用 A/B):GET {baseUrl}/umbraco/management/api/v1/server/information。结果为 SITE_MAJOR。若 A/B/C 均无结果,说明工作区尚无 Umbraco 站点,无需守卫,继续即可;若发现多个不同主版本(混合解决方案),应列出并询问目标项目。
- 比较与处理:SITE_MAJOR == TARGET_MAJOR 时静默通过,用一行确认匹配并继续。SITE_MAJOR != TARGET_MAJOR 时停止,不生成版本相关代码,并给出警告,仅在用户明确确认后才继续。推荐命令遵循仓库分支约定:最新主版本在 main,旧主版本 N 在 vN/main。站点更旧时:/plugin marketplace add https://github.com/umbraco/Umbraco-CMS-Backoffice-Skills.git#v{SITE_MAJOR}/main。站点更新时:/plugin marketplace add umbraco/Umbraco-CMS-Backoffice-Skills。若某主版本尚无已发布分支,应说明技能可能尚未跟进。对 Vercel Skills CLI(Cursor/Copilot/Windsurf),将仓库 URL 指向对应分支。
限制:技能自身不硬编码具体主版本号,两端均为计算得出;需站点或项目文件可访问才能检测版本;未提供的其他细节暂未提供。