插件审计

plugin-audit
分类编程
作者Alireza Rezvani
许可MIT
评分4.30/5
使用5.8K

/plugin-audit

针对本仓库中任何技能、插件、智能体或命令的完整审计流水线。运行 8 个验证阶段，尽可能自动修复问题，仅在关键决策（破坏性变更、新依赖项）时停止并请求用户输入。

用法

bash
/plugin-audit product-team/code-to-prd
/plugin-audit engineering/agenthub
/plugin-audit engineering-team/playwright-pro

功能概述

按顺序执行所有 8 个阶段。在出现关键故障时停止。自动修复非关键问题。最后报告结果。

---

阶段 1：探索 (Discovery)

识别技能包含的内容并进行分类。

1. 验证 {skill_path} 是否存在且包含 SKILL.md
2. 读取 SKILL.md 的 frontmatter —— 提取 name、description、Category、Tier
3. 检测技能类型：
- 包含 scripts/ $\rightarrow$ 拥有 Python 工具
- 包含 references/ $\rightarrow$ 拥有参考文档
- 包含 assets/ $\rightarrow$ 拥有模板/示例
- 包含 expected_outputs/ $\rightarrow$ 拥有测试固件 (test fixtures)
- 包含 agents/ $\rightarrow$ 拥有嵌入式智能体
- 包含 skills/ $\rightarrow$ 拥有子技能（复合技能）
- 包含 .claude-plugin/plugin.json $\rightarrow$ 是独立插件
- 包含 settings.json $\rightarrow$ 拥有命令注册
4. 从路径检测领域：engineering/、product-team/、marketing-skill/ 等。
5. 检查关联命令：在 commands/ 中搜索与技能名称匹配的 .md 文件

在继续之前显示探索摘要：

code
Auditing: code-to-prd
  Domain: product-team
  Type: STANDARD skill with standalone plugin
  Scripts: 2 | References: 2 | Assets: 1 | Expected outputs: 3
  Command: /code-to-prd (found)
  Plugin: .claude-plugin/plugin.json (found)

---

阶段 2：结构验证 (Structure Validation)

运行 skill-tester 验证器。

bash
python3 engineering/skills/skill-tester/scripts/skill_validator.py {skill_path} --tier {detected_tier} --json

解析 JSON 输出。提取：

  • 总体得分和合规级别

  • 未通过的检查项（逐一列出）

  • 错误和警告

门禁规则： 分数必须 $\ge 75$ (GOOD)。如果低于 75：

  • 读取错误列表

  • 尽可能自动修复：

- 缺失 frontmatter 字段 $\rightarrow$ 从 SKILL.md 内容中添加
- 缺失章节 $\rightarrow$ 添加占位标题
- 缺失目录 $\rightarrow$ 创建空目录并附带说明
  • 修复后重新运行。如果仍低于 75，报告为 FAIL 并继续收集剩余结果。

---

阶段 3：质量评分 (Quality Scoring)

运行质量评分器。

bash
python3 engineering/skills/skill-tester/scripts/quality_scorer.py {skill_path} --detailed --json

解析 JSON 输出。提取：

  • 总体得分和等级

  • 各维度得分（文档、代码质量、完整性、可用性）

  • 改进路线图项

门禁规则： 分数必须 $\ge 60$ (C)。如果低于 60，将改进路线图项作为待办事项报告。

---

阶段 4：脚本测试 (Script Testing)

如果技能包含带有 .py 文件的 scripts/ 目录，则运行脚本测试器。

bash
python3 engineering/skills/skill-tester/scripts/script_tester.py {skill_path} --json --verbose

解析 JSON 输出。针对每个脚本，提取：

  • 通过/部分通过/失败 状态

  • 单项测试结果

门禁规则：
所有脚本必须通过 (PASS)。任何失败 (FAIL) 均为阻塞项。部分通过 (PARTIAL) 将触发警告。

自动修复： 如果脚本未通过 --help 测试，请检查其是否使用了 argparse —— 如果没有，则这是一个真实问题。如果未通过仅限标准库 (stdlib-only) 测试，请标记该导入并询问用户该依赖是否可接受（这是一个关键决策）。

---

第 5 阶段：安全审计

运行技能安全审计工具。

bash
python3 engineering/skills/skill-security-auditor/scripts/skill_security_auditor.py {skill_path} --strict --json

解析 JSON 输出。提取：

  • 结论 (Verdict)：PASS/WARN/FAIL

  • 严重缺陷 (Critical findings)：必须为零

  • 高危缺陷 (High findings)：在严格模式下必须为零

  • 信息提示 (Info findings)：仅作为建议

准入规则： 严重缺陷为零，高危缺陷为零。任何严重或高危缺陷均为阻塞项 —— 请报告具体的文件、行号、模式及建议的修复方案。

不要自动修复安全问题。 请报告问题并由用户决定。

---

第 6 阶段：市场与插件合规性

6a. plugin.json 验证

如果 {skill_path}/.claude-plugin/plugin.json 存在：

1. 解析为 JSON —— 必须有效
2. 验证仅包含允许的字段：name, description, version, author, homepage, repository, license, skills
3. 版本必须与仓库版本 (2.1.2) 一致
4. skills 必须为 "./"
5. name 必须与技能目录名一致

自动修复： 如果版本错误，请更新；如果存在多余字段，请删除。

6b. settings.json 验证

如果 {skill_path}/settings.json 存在：

1. 解析为 JSON —— 必须有效
2. 版本必须与仓库版本一致
3. 如果存在 commands 字段，验证每个命令在 commands/ 目录下都有对应的文件

6c. 市场条目

检查该技能在 .claude-plugin/marketplace.json 中是否有条目：

1. 在 plugins 数组中搜索 source 与 ./ + 技能路径匹配的条目
2. 如果找到：验证 version、name 以及 source 路径是否存在
3. 如果未找到：检查该技能的领域包（例如 product-skills）是否通过其 source 路径将其包含在内

6d. 领域 plugin.json

检查父级领域的 .claude-plugin/plugin.json：

  • 验证描述中的技能数量是否与实际相符

  • 验证版本是否与仓库版本一致

自动修复： 更新过时的数量，修复版本不一致。

---

第 7 阶段：生态集成

7a. 跨平台同步

验证该技能是否出现在平台索引中：

bash
grep -l "{skill_name}" .codex/skills-index.json .gemini/skills-index.json

如果任一索引中缺失：

bash
python3 scripts/sync-codex-skills.py --verbose
python3 scripts/sync-gemini-skills.py --verbose

7b. 命令集成

如果该技能有关联命令（来自 settings.json 的 commands 字段或 commands/ 中名称匹配的文件）：

  • 验证命令 .md 文件具有有效的 YAML frontmatter (name, description)

  • 验证命令引用了正确的技能路径

  • 验证该命令已包含在 mkdocs.yml 的导航栏中

自动修复： 添加缺失的 mkdocs.yml 导航条目。

7c. Agent 集成

如果该技能包含嵌入式 Agent ({skill_path}/agents/*.md)：

  • 验证每个 Agent 具有有效的 YAML frontmatter

  • 验证 Agent 引用可解析（指向技能的相对路径）

在 agents/ 中搜索任何引用此技能的 cs-* Agent：

bash
grep -rl "{skill_name}\|{skill_path}" agents/

如果找到，验证该 Agent 的技能引用是否正确。

7d. 跨技能依赖

阅读 SKILL.md 以查找对其他技能的引用（查找 ../ 路径或“相关技能”部分中的技能名称）：

  • V

  • 验证每个引用的技能均存在

  • 验证引用技能的 SKILL.md 文件存在

---

第 8 阶段：领域相关的代码审查

根据技能所属领域，调用相应 Agent 的审查视角：

| 领域 | Agent | 审查重点 |
|--------|-------|-------------|
| engineering/ 或 engineering-team/ | cs-senior-engineer | 架构、代码质量、CI/CD 集成 |
| product-team/ | cs-product-manager | PRD 质量、用户故事覆盖率、RICE 匹配度 |
| marketing-skill/ | cs-content-creator | 内容质量、SEO 优化、品牌语调 |
| ra-qm-team/ | cs-quality-regulatory | 合规检查清单、审计追踪、监管一致性 |
| business-growth/ | cs-growth-strategist | 增长指标、营收影响、客户成功 |
| finance/ | cs-financial-analyst | 财务模型准确性、指标定义 |
| 其他 | cs-senior-engineer | 通用代码与架构审查 |

调用方式： 阅读 Agent 的 .md 文件以了解其审查标准。将这些标准应用于审查技能的 SKILL.md、脚本和引用。这不是创建子 Agent，而是利用 Agent 文档中定义的视角来构建你的审查。

审查清单（应用相应的领域视角）：

  • [ ] SKILL.md 的工作流可执行且完整

  • [ ] 脚本正确解决了所述问题

  • [ ] 引用包含准确的领域知识

  • [ ] 模板/资产已达到生产就绪状态

  • [ ] 无失效的内部链接

  • [ ] 必要处已标注归属/来源

---

最终报告

以结构化表格形式呈现结果：

code
╔══════════════════════════════════════════════════════════════╗
║  插件审计报告: {skill_name}                                 ║
╠══════════════════════════════════════════════════════════════╣
║                                                              ║
║  阶段 1 — 探索                ✅ {type}, {domain}            ║
║  阶段 2 — 结构                ✅ {score}/100 ({level})       ║
║  阶段 3 — 质量                ✅ {score}/100 ({grade})       ║
║  阶段 4 — 脚本                ✅ {n}/{n} 通过                ║
║  阶段 5 — 安全                ✅ 通过 (0 严重, 0 高危)        ║
║  阶段 6 — 市场                ✅ plugin.json 有效            ║
║  阶段 7 — 生态                ✅ Codex + Gemini 已同步        ║
║  阶段 8 — 代码审查            ✅ {domain} 审查通过            ║
║                                                              ║
║  结论: ✅ 通过 — 准备合并/发布                                ║
║                                                              ║
║  已应用自动修复: {n}                                          ║
║  警告: {n}                                                   ║
║  待办事项: {n}                                               ║
║                                                              ║
╚══════════════════════════════════════════════════════════════╝

结论逻辑

| 条件 | 结论 |
|-----------|---------|
| 所有阶段均通过 | PASS — 准备合并/发布 |
| 仅有警告（无阻塞项） | PASS WITH WARNINGS — 合并前请查看警告 |
| 任何阶段存在阻塞项 | FAIL — 列出阻塞项及修复指令 |

阻塞项（满足任意一项 = FAIL）

  • 结构分 < 75
  • 质量分 < 60（在记录路线图之后）
  • 任何脚本 FAIL
  • 任何 CRITICAL（严重）或 HIGH（高危）安全漏洞
  • plugin.json 无效或包含禁用字段
  • 与仓库版本不匹配

非阻塞项（仅为警告）

  • 质量分在 60-75 之间
  • 脚本结果为 PARTIAL（部分通过）
  • M
  • 缺失平台索引（已自动修复）
  • 缺失 mkdocs.yml 导航条目（已自动修复）
  • 安全性 INFO 级别发现项

---

技能参考

| 工具 | 路径 |
|------|------|
| Skill Validator | engineering/skills/skill-tester/scripts/skill_validator.py |
| Quality Scorer | engineering/skills/skill-tester/scripts/quality_scorer.py |
| Script Tester | engineering/skills/skill-tester/scripts/script_tester.py |
| Security Auditor | engineering/skills/skill-security-auditor/scripts/skill_security_auditor.py |
| Quality Standards | standards/quality/quality-standards.md |
| Security Standards | standards/security/security-standards.md |
| Git Standards | standards/git/git-workflow-standards.md |