SuperAPI AI 工具集

umbraco-review-content-model

编程与开发

查看项目

更新于 10-22 05:17

技能介绍

本技能面向 Umbraco 17+ 内容模型的审查工作,输出一份报告,列出模型对内容建模约定的每一处偏离、为何重要、严重程度以及可由哪个技能修复。审查本身不做任何修改,它是后续经批准的变更的输入,而不是变更本身。

规则来自配套技能 umbraco-content-model-conventions,读取 schema 和 lint 需求文件夹来自 umbraco-content-requirements-documentation。两者必须同时安装;如果无法读取指向任一技能的链接,应停止并说明,不得凭记忆工作。

审查来源

  • 实时站点(通过 Umbraco Developer MCP):使用 inspect-existing-schema.md 中的读取工具读取每个类型、数据类型和模板,可证明站点的实际状态。
  • 需求文件夹:先运行需求 linter,再对页面执行下述判断检查,只能证明需求文档所述内容,不能证明站点与之一致。
  • 用户提供的 schema(导出、回读、描述):仅审查所给内容,并列出未提供的内容。

当 MCP 已连接时使用实时站点,它是唯一能展示真实模型的来源。来源是一种方法的不同输入,而非方法选择。报告顶部须注明来源,不得将需求文档或描述当作实时站点呈现。

检查项

  • 名称、别名、后缀、属性别名:checks-naming.md
  • 树、根、允许子级、模板、列表、设置:checks-structure.md
  • 选项卡、分组和属性排序:checks-sorts.md
  • 数据类型:复用、约束、文件夹、块编辑器:checks-data-types.md
  • 描述和图标:checks-descriptions.md
  • 组合、元素和设置模型:checks-compositions.md

按 review-report.md 编写报告。

步骤

  1. 收集:读取来源提供的一切。使用 MCP 时,用 get-document-type-by-id 读取每个文档类型(了解别名的唯一方式),用 get-data-type 读取每个自定义数据类型。使用需求文件夹时,运行 lint-requirements.mjs 并保留其输出。
  2. 检查:遍历每个 checks 文件,记录每项发现,包含工件、规则、证据和严重程度。
  3. 识别项目自身约定:当整个模型以相同方式持续偏离某条规则时,这属于项目约定而非缺陷列表,在 departures 下报告一次,不参与排名。
  4. 排序:高优先级在前;同一严重程度内,影响类型最多的发现在前。
  5. 写报告:基于模板编写,包含未检查项。保存为 docs/content-model-review-<yyyy-mm-dd>.md,放在需求文件夹旁边而非内部,因为 linter 会把需求文件夹中的每个页面当作需求文档。
  6. 停止:通过指定技能将修复作为下一步提供,每项修复作为独立的需求文档并单独审批。无论修复多小,都不得更改站点或需求文档。

严重程度

  • 高:破坏行为或危及内容。例如:页面类型无模板也无控制器;组合之间别名冲突;块编辑器被共享于无法渲染该块的放置位置。
  • 中:使模型更难使用或扩展。例如:页面或组合别名上的后缀或缩写大小写错误;允许页面位于根;选项卡使用局部排序;约束写在属性验证中。
  • 低:一致性与打磨。例如:缺少描述;默认图标;元素和设置后缀;属性排序未以百位递增。

版本兼容性 面向 Umbraco 17+。MCP 读取工具已按 umbraco-content-requirements-documentation 所述检查;已连接工具列表为准。

最佳实践

  • 只报告,不修复:重命名别名或移动属性可能破坏模板并丢失内容。每项修复都是独立变更,需指定并获批。
  • 每项发现都有证据:引用别名、排序、设置。没有证据的发现只是意见。
  • 说明看不到的内容:没有数据类型配置的回读无法证明约束;需求文件夹无法证明站点。报告应列出这些。
  • 尊重一致的项目约定:一致性优于纯粹性;偏离只报告一次。
  • 代码不在范围内:查询模型不佳的控制器或视图属于 umbraco-common-pitfalls,应作为单独的审查指出。

验证 客观断言位于 evals/evals.json,用 umbraco-skill-evaluator 运行。覆盖层级:Documented。该技能不附带代码,唯一资产是 Markdown 报告模板。评估针对指导内容进行;没有针对实时站点运行任何内容。