umbraco-version-guard

Umbraco 版本守卫

此技能的作用

Umbraco backoffice API 会随主版本变化（树数据源、身份验证、OpenAPI 注册等）。这些技能针对某个特定主版本。 将它们用于主版本不同的网站，会生成看似正确、实则错误的代码。

此技能是一项预检：它会从插件本身推导目标主版本（因此发布新主版本后不会过时），确定性地检测目标网站的主版本，将两者进行比较，并在不匹配时停止操作，同时提供正确的安装命令。这里没有硬编码特定主版本号——两边的版本号都会动态计算。

第 1 步——确定这些技能所针对的主版本

插件自身的版本是唯一可信来源，且每次发布主版本时都会递增。读取该版本并取开头的数字：

# Primary: the installed plugin's version. First path is the Claude Code plugin layout;
# the greps are fallbacks for when the skill was copied flat into an editor's skills dir.
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

称其为 TARGET_MAJOR。如果这些路径都无法解析（例如文件被平铺复制，旁边没有 plugin.json），则回退到市场版本；只有在此之后，才读取同级技能声明的值——绝不要凭空编造版本号。如果确实无法确定，就说明这一点并跳过检查，不要猜测。

第 2 步——检测 Umbraco 网站的主版本（确定性检测，无需运行实例）

按以下顺序尝试这些信号，并在第一个得出数字的信号处停止。每种方法都只提取主版本，因此适用于 18.0.0、18.*、[18.0.0,) 或纯数字 18。

A. Umbraco.Cms 包引用（权威依据——实际安装的版本）。 覆盖 *.csproj 中的 PackageReference 和集中式包管理的 *.props（PackageVersion）；Cms 后面的 " 会排除 Umbraco.Cms.DevelopmentMode 等内容。

grep -rhoE 'Umbraco\.Cms"[^0-9]*[0-9]+' --include='*.csproj' --include='*.props' . 2>/dev/null \
  | grep -oE '[0-9]+$' | sort -u

B. 回退方案——backoffice 客户端依赖项的主版本（支持 ^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 网站——说明这一点并继续（无需检查）。如果发现多个不同的主版本（混合解决方案），请列出所有版本并询问目标项目是哪一个。

第 3 步——比较并采取行动

• SITE_MAJOR == TARGET_MAJOR → ✅ 静默通过。用一句话确认版本匹配（例如：“网站使用 Umbraco {SITE_MAJOR}.x，与这些技能匹配。”），然后继续。
• SITE_MAJOR != TARGET_MAJOR → ⛔ 停止。不要生成特定于版本的代码。按下文警告，然后只有在用户明确确认后才能继续。

建议使用哪条技能分支取决于仓库的分支约定——最新主版本位于 main；每个较旧的主版本 N 位于 vN/main 分支：

• SITE_MAJOR < TARGET_MAJOR（网站版本低于这些技能）→ 指向适用于网站主版本的较旧分支：

  /plugin marketplace add https://github.com/umbraco/Umbraco-CMS-Backoffice-Skills.git#v{SITE_MAJOR}/main
  

• SITE_MAJOR > TARGET_MAJOR（这些技能的版本低于网站）→ 最新主版本位于默认的 main 分支，因此请重新添加并更新默认市场版本：

  /plugin marketplace add umbraco/Umbraco-CMS-Backoffice-Skills
  

  如果 SITE_MAJOR 尚无已发布的分支，请说明这一点——这些技能可能尚未跟上该主版本。

在呈现这些内容时，替换为实际版本号。消息模板：

⚠️ 版本不匹配。 此网站使用 Umbraco {SITE_MAJOR}，但已加载的技能针对 Umbraco {TARGET_MAJOR}。不同主版本的 backoffice API 存在差异，因此这组技能会为你的网站生成错误代码。请安装匹配的分支： <computed command above>

对于 Vercel Skills CLI（Cursor/Copilot/Windsurf），请将仓库 URL 指向匹配的分支（最新主版本使用 main，较旧主版本使用 v{N}/main）。

何时运行

在开始任何 Umbraco backoffice 任务时，先运行一次，然后再编写代码。入口技能（umbraco-quickstart、umbraco-backoffice、umbraco-extension-template）会将此检查列为第一步。只有在工作区发生变化时才重新运行。