plugin-review

插件评审

概述

根据依赖关系确定范围，对插件进行分级质量评审。

不适用场景

• 评审单个技能而非插件（使用 abstract:skills-eval）
• 评审钩子（使用 abstract:hooks-eval）
• 跨插件追踪 Skill() 引用（使用 abstract:skill-graph-audit）

分级

级别	触发条件	范围	深度	时长
branch	默认	受影响及相关插件	快速检查	~2 分钟
pr	合并前	受影响及相关插件	标准	~5 分钟
release	版本号更新前	每个插件	完整	~15 分钟

编排

1. 检测范围：解析 --tier 标志，根据 git diff 查找受影响的 插件，从 docs/plugin-dependencies.json 解析相关插件
2. 规划：构建检查矩阵（级别 x 插件 x 角色）
3. 执行：按级别定义运行检查
4. 报告：输出每个插件的表格和汇总判定结果

范围检测

受影响的插件：通过 git diff main --name-only 筛选 plugins/*/。

相关插件：加载 docs/plugin-dependencies.json， 查询每个受影响插件的反向索引，查找依赖该插件的项目。将这些插件标记为“相关”（执行较轻量的检查）。

如果使用 --tier release，或无法获取 git diff，则将范围设为 所有插件。

模块加载

• 始终：此 SKILL.md（编排逻辑）
• branch 级别：加载 modules/tier-branch.md
• pr 级别：先加载 modules/tier-branch.md，再加载 modules/tier-pr.md
• release 级别：加载所有级别模块以及 modules/tier-release.md
• 解析依赖时：加载 modules/dependency-detection.md

判定结果

结果	含义
PASS	所有检查均通过
PASS-WITH-WARNINGS	存在非阻塞问题
FAIL	发现阻塞问题

输出格式

Plugin Review (<tier> tier)
Affected: <list>
Related:  <list> (<reason>)

Plugin          test  lint  type  reg   verdict
<name>          PASS  PASS  PASS  PASS  PASS
...

Verdict: <PASS|PASS-WITH-WARNINGS|FAIL> (N/N plugins healthy)

PR 和 release 级别还会添加评分卡部分。

质量门禁模式

--quality-gate 标志可启用 CI/CD 集成，并通过退出代码区分警告和失败：

• 0：所有质量门禁均通过
• 1：存在警告，但门禁已通过（非阻塞）
• 2：质量门禁失败（阻塞）
• 3：发现严重问题（阻塞）

使用 --fail-on warning 将警告视为阻塞问题。

配置

在插件根目录中放置 .plugin-review.yaml 文件， 以自定义阈值和关注区域：

plugin_review:
  quality_gates:
    structure_min: 80
    skills_min: 75
    hooks_min: 70
    tokens_max_total: 50000
    bloat_max_percentage: 15
  focus_areas:
    - skills
    - hooks
    - tokens
  exclude_patterns:
    - "*/legacy/*"
    - "*/deprecated/*"
  severity_overrides:
    missing_description: warning
    large_file: info

有关完整用法示例，请参阅 /plugin-review 命令参考。

退出条件

• 输出包含每个插件的表格，列包括：test、lint、type、reg、verdict，以及汇总的 PASS / PASS-WITH-WARNINGS / FAIL 判定结果。
• 范围检测通过 git diff main --name-only 筛选 plugins/*/，识别受影响的插件；如果无法获取 git diff，该技能会回退到所有插件范围，并明确说明这一点。
• 任何评分低于 structure_min（默认值为 80）或 skills_min（默认值为 75）阈值的插件都列为 FAIL，而非警告。
• --quality-gate 模式在出现阻塞失败时返回退出代码 2，在出现非阻塞警告时返回退出代码 1，以便调用它的 CI 步骤区分二者。