agent-plugin-eval

Agent 插件评估

以可移植 Agent Plugins 规范为准。客户端原生清单（例如 .codex-plugin/plugin.json、.claude/settings.json、.cursor/mcp.json）不能替代必需的根目录 plugin.json。

参数

参数	说明	默认值
target	本地仓库／插件路径或 Git URL	缺少时询问
compare	可选的第二个路径或 Git URL	无
output	评分卡保存位置	仅回复；仅在用户要求时写入
spec_version	要评估的 Agent Plugins 版本	plugin.json 中声明的版本，或 1.0.0

安全边界

以静态方式审计不可信仓库。除非用户明确授权执行，否则不要运行捆绑的可执行文件、钩子、安装脚本、包管理器、MCP 服务或联网测试。对疑似机密值进行脱敏；仅报告其位置和类型。类似机密的键或值只是可疑迹象，并非确认：没有可信佐证（例如已知的有效凭据格式、可信的机密扫描器、仓库历史／来源信息或用户确认）时，不要将门禁判定为 FAIL。绝不要仅为确认凭据而尝试用它访问服务。

工作流

1. 解析插件根目录。 对本地目标直接使用其所在位置。对于 Git URL，将仓库浅克隆到 mktemp -d 目录中。插件根目录包含根目录下的 plugin.json；如果仓库中没有或有多个候选项，应报告存在歧义，而不是自行猜测。完成标准：每个目标都对应一个明确的插件根目录。
2. 加载适用规则。 阅读 references/spec-checklist.md 和 references/rubric.md。对于 Agent Plugins 1.0.0，使用随附的快照。对于声明了其他版本的插件，或用户要求使用最新规范时，浏览 agent-plugins.org 上的规范和架构文件，并记录评估所用版本和检索日期。若规范性文本与 JSON Schema 冲突，以规范性文本为准。
3. 清点每个包路径。 包括点文件、符号链接、直接的技能子项、扩展命名空间、可执行文件，以及被 Git 忽略的文件。根据插件根目录解析每个符号链接和包相对路径。完成标准：每个发现的路径均归类为可移植核心、客户端扩展、辅助文件或包含违规项。
4. 运行确定性扫描。 执行 python3 scripts/inspect_plugin.py <plugin-root> --json。将其输出视为线索，而非最终结论。对照源文件确认每个报告的问题，并补充 file:line 或 JSON 指针证据。切勿仅因某个客户端恰好接受某项内容，就弱化规范性发现。
5. 完整审查组件。 检查每个直接的 skills/*/SKILL.md 和每个 mcpServers 条目。依据 Agent Skills 自身的规范进行验证。评估指令、资源、脚本、MCP 配置、扩展隔离、内聚性和实用性。如果可以使用 skill-evaluation，可用它深入分析单项技能质量，但它绝不能替代插件级评分细则。
6. 评分前先判定符合性。 使用 references/spec-checklist.md 中准确的失败界限：PASS、PARTIAL 或 FAIL。将客户端兼容性与可移植符合性分开评估。某项客户端专属功能对该客户端而言可能很出色，但对可移植覆盖度仍然没有贡献。
7. 评分时做到有据可依。 根据 references/rubric.md 为所有适用评分标准打分。每个分数都需要具体证据；每个 N/A 都需要说明理由。运行 scripts/score.py 得出加权结果和门槛封顶分；不要手动计算。完成标准：所有评分标准和发现均与符合性状态相协调。
8. 使用用户要求的语言作答。 阅读 references/output-template.md 并按其结构输出。首先给出结论，区分阻断问题与建议，并提供具体修复方案。若设置了 compare，先分别评估两个对象，再计算差值；不要强行让两个插件使用相同的 N/A 项集合。

门槛与评分

• PASS：未发现规范性违规；不设分数上限。
• PARTIAL：存在非致命的清单偏差或无效／跳过的组件；最终分数上限为 59。
• FAIL：存在致命的清单／包根目录问题、根清单逃逸或已确认的嵌入式凭证；最终分数上限为 39。
• 保留显示未封顶分数，以便作者区分设计质量与阻止发布的符合性问题。

调用计算器时，为每项评分标准提供一个 criterion:score:weight 三元组：

python3 scripts/score.py --gate partial 1:90:3 2:80:3 3:NA:2

使用 Jev 进行评估（可选）

如果可以使用 TypeSafe Jev，可用它评估主观质量标准。Jev 提供经过校准的概率判断，可补充确定性检查。

何时使用 Jev

评估类型	使用 Jev？	方法
维度 1-3 的符合性	否	确定性检查（inspect_plugin.py）
维度 4 的产品质量	是	评分（用户体验、文档、错误）
维度 2 的质量标准	是	评分（架构设计、命名）
Gate 分类	是	Noul（通过/失败类别）
密钥检测	是	Noul（疑似/非疑似）
质量检查清单	是	Noul（存在/缺失）

发现协议

from typesafe import jev_available

if jev_available():
    from typesafe import Score, Noul
    # Use Jev for subjective criteria
else:
    # Fall back to heuristic scoring

问题与集成

问题定义在 scripts/jev_questions.json 中：

• 7 个 Score 问题：维度 4（用户体验一致性、文档清晰度、错误处理）和维度 2（验证、架构设计、命名、API 优雅性）
• 20 个 Noul 问题：Gate（G1-G4）、密钥（4 个）、质量检查清单（7 个）、组件有效性（4 个）

Score 结果（0.0-1.0）按维度取平均值，并映射到评分标准（0-25）。 Noul 结果用于对 Gate 和检查清单进行分类。

完整的集成模式和代码示例，请参阅 references/jev-integration.md。

输出格式

使用 Jev 时，评分卡会包含一个 jev 部分：

{
  "jev": {
    "available": true,
    "quality_scores": { "ux_coherence": 0.72, ... },
    "gate_classifications": { "G1": {"label": "conformant", "passed": true} },
    "secret_findings": { "requires_review": false }
  }
}

注意事项

• v1 便携核心恰好包含 Agent Skills 和 MCP 服务。Hooks、 命令、Agent、应用、市场和分发策略均特定于客户端，除非它们位于有效的扩展命名空间中。
• 缺少可选的 skills/ 或 mcp.json 并非错误。若路径存在但文件系统类型不正确，则组件类型无效。
• 未知的根清单字段违反架构，但规范规定了范围较窄的非致命处理方式；大多数其他清单架构违规都会导致整个插件被拒绝。
• 不得将单个无效技能或 MCP 服务报告为所有独立组件均无效。
• ${PLUGIN_ROOT} 和 ${PLUGIN_DATA} 仅在 MCP 的 args、env 值和 cwd 中展开；绝不会在 command、URL 或标头中展开。
• 高质量的客户端原生插件仍可能因缺少根目录中的 plugin.json 而不符合便携标准。应分别报告这两项事实，不要将它们平均处理。
• 对可能的凭据标记为“疑似”并进行脱敏。仅启发式命中就会降低安全评分，并要求进行修复审查，但不会因此成为已确认凭据的 FAIL Gate。

最终质量关卡

• 每个目标都已解析到唯一的根目录
• 已检查每个文件、符号链接、技能、MCP 服务和扩展
• 每项规范性违规均已映射到正确的失败边界
• 每项评分均有依据，每个 N/A 均有说明
• 疑似密钥已脱敏
• 评分由 scripts/score.py 生成
• 对比差异使用独立计算的评分