drupal-theme-review

用途

Drupal Theme Review 用于审查 Drupal 主题代码是否符合 Drupal 11 主题开发标准。主题代码中的缺陷往往很隐蔽，例如误用 |raw、预处理函数缺少缓存上下文、使用 $(document).ready() 而非 Drupal.behaviors、缺少 once() 调用等，这些问题可能导致 XSS 漏洞、内容陈旧或 AJAX 流程中断。该技能帮助在合并前发现并修正这些问题。

主要能力

该技能覆盖以下审查领域，并按需加载对应参考文件：

• Twig 模板（*.html.twig）：参考 references/01-twig.md
• *.theme、预处理函数、模板建议：参考 references/02-preprocess.md
• *.libraries.yml、CSS/JS 资源定义：参考 references/03-libraries.md
• JavaScript 行为、Drupal.behaviors、once()：参考 references/04-javascript.md
• components/、*.component.yml、SDC：参考 references/05-sdc.md
• *.info.yml、theme-settings.php、断点：参考 references/06-theme-config.md
• ARIA 角色、跳转链接、Drupal.announce、颜色对比度：参考 references/07-accessibility.md
• *.breakpoints.yml、响应式图片样式、<picture>：参考 references/08-responsive-images.md

技能会先快速扫描待审查文件，识别文件类型，只加载相关的参考文件，而不是一次性加载全部八个。

使用方式

1. 理解审查对象：如果 $ARGUMENTS 包含文件路径，则读取这些文件；如果用户内联粘贴了代码，则使用该代码；如果两者都没有，则询问：“Which theme file or directory should I review?”
2. 加载相关参考文件，然后进行审查。
3. 按以下结构输出审查结果：

• Drupal Theme Review: [文件名或主题名]
• Critical Issues（关键问题）：例如对用户输入使用 |raw 导致 XSS、使用 $(document).ready() 而非 Drupal.behaviors、缺少 once()（导致 AJAX 后重复事件监听器）、缓存元数据损坏导致内容陈旧。必须在合并前修复。
• Standards Violations（标准违规）：偏离 Drupal 11 主题模式，例如错误的 CSS SMACSS 权重、预处理中的静态调用、缺少库依赖声明、模板命名约定错误。应当修复。
• Recommendations（建议）：最佳实践改进，例如使用 SDC 替代内联组件、响应式图片、针对每用户内容的惰性构建器、无障碍增强。
• Confirmed Good Practices（已确认的良好实践）：简要肯定正确的模式，让开发者知道哪些应保留。

每项发现需包含：引用参考文件及原则（例如“→ 01-twig.md: Never use |raw on user-supplied content”）、展示有问题的代码片段、展示修正后的版本。如果某个部分没有问题，写“None found.”，不要省略该部分。

高价值检查项

每次主题审查都会运行以下常见错误检查：

Twig / 安全

• 不对用户提供的变量使用 |raw——Twig 默认自动转义，|raw 会禁用该保护
• 使用 {{ content|without('field_x') }} 而非手动列出字段——|without 保留缓存元数据，手动列出会静默丢弃
• 不使用 {% set %} 块构建标记字符串后再用 |raw 输出

缓存

• 添加自定义变量的预处理函数同时冒泡正确的 #cache 元数据
• 块预处理：当块内容变化时覆盖 getCacheContexts()、getCacheTags()、getCacheMaxAge()
• 不直接嵌入 max-age: 0 组件——改用惰性构建器

JavaScript

• 使用 Drupal.behaviors 而非 $(document).ready() 或 DOMContentLoaded
• 每个 attach() 处理器都用 once() 包裹——否则 AJAX 请求会重新附加监听器并导致重复
• 声明 core/once 和 core/drupal 为库依赖

库

• 每个使用 $ 的 JS 文件都声明 core/jquery 为依赖——不要假设 jQuery 是全局的
• CSS 文件放在正确的 SMACSS 权重键下（base、layout、component、state、theme）

模板命名

• PHP 钩子名中的下划线在文件名中变为单个连字符；钩子中的 __（双下划线）→ 文件名中的 --（双连字符）
• 模板放在 templates/ 下逻辑组织的子目录中

适用场景

适用于 Drupal 主题开发者在提交或合并代码前进行代码审查，尤其适合检查 Twig 模板安全性、缓存元数据正确性、JavaScript 行为规范、库依赖声明、模板命名约定、无障碍和响应式图片实现。

限制

该技能的具体安装方式、收费模式、价格、平台支持等信息暂未提供。