| name | clawguard-report |
| description | 基于 ClawGuard 评测产出文件，生成面向插件开发者的评测报告（report.md）。 报告原则：零主观判断，所有扣分项有理有据，修复方法可操作。 输入：certification.json + plugin-data.json + findings.json（必需），probe-report.json + profile.json + eval-report.json（可选）。 触发词：生成评测报告、出报告、generate report。 通常由 clawguard-eval Skill 在 certify 完成后自动调用，也可独立触发。
|
ClawGuard Report — 评测报告生成
报告定位
- 受众：插件开发者
- 目标：看完报告，开发者清楚知道"每一分是怎么扣的、为什么扣、怎么改回来"
- 核心原则：每个扣分项必须有理有据
扣分项说明规范（必须遵守）
报告中每个扣分项必须包含以下 4 个要素：
1. 检测到了什么（事实）
具体描述检测到的问题，引用实际数据：工具名、数量、字符数、文件名等。
示例：检测到 7 个工具的描述超过 100 字符，其中 feishu_calendar_event 为 427 字符
2. 评分规则是什么（依据）
说明对应的评分规则，引用 docs/SCORING.md 中的规则。
示例：根据 COMPLIANCE（规范遵从）评分规则，描述超过 100 字符的工具每个扣 4 分，上限 20 分
3. 实际扣了多少分（计算）
展示具体的扣分计算过程。
示例：7 个工具 × 4 分 = 28，触及上限 → 实际扣 20 分
4. 怎么修（修复方法）
给出具体可操作的修复步骤，包含代码示例或命令。
示例：将 feishu_calendar_event 的描述从 427 字符精简到 100 字符以内，详细说明移至 SKILL.md
禁止出现以下情况：
- ❌ 只说扣了分但不解释为什么
- ❌ 只列分数不给检测数据
- ❌ 说"建议优化"但不给具体步骤
- ❌ 使用主观评价词（好、差、优秀、糟糕）
- ❌ 漏报扣分项：
findings.json 中每一条 deduction > 0 的 finding，以及每个 < 100 的子维度（FUNC/STABLE/VALUE/FOOTPRINT/HOOK_OVERHEAD/E2E_IMPACT/TOKEN_COST），都必须在 section 6 里出现。完整性必须在 6.4 节用数字声明（"26 条 SEC 规则中 X 条命中，其余 {26-X} 条未触发"）
执行方式
由 Agent 读取数据文件后，按模板格式生成 report.md。不调用 CLI 命令。
步骤：
- 读取
certification.json → 三大类分数、子维度分数、tokenSummary、tokenBreakdown
- 读取
findings.json → 每条扣分项（ruleId / category / severity / location / deduction / fix / detail）—— 这是 section 6 的主数据源
- 读取
plugin-data.json → 原始检测数据（securitySignals / apiUsage / codeMetrics / manifest），用于 section 3 检测结果细节
- 可选读取
probe-report.json → 每工具 pass/fail + 错误原因 + P99，用于 section 4
- 可选读取
profile.json → 性能剖析（FOOTPRINT tokens / hook P99），section 5 展示
- 可选读取
eval-report.json → A/B 结果（VALUE / E2E_IMPACT / TOKEN_COST）
- 读取
docs/SCORING.md → 评分规则（作为扣分依据引用）
- 按照
references/report-template.md 的结构生成报告
- 完整性自检：逐一验证 findings.json 中每条 deduction > 0 finding 都出现在 section 6；每个 < 100 的子维度都有单独说明；6.4 节的"未触发"统计数字与 findings.json 吻合
- 将报告写入指定路径
输入文件
| 文件 | 来源步骤 | 必需 | 说明 |
|---|
certification.json | certify | ✅ | 三大类分数、子维度分数、tokenSummary、tokenBreakdown |
findings.json | certify | ✅ | 逐条扣分（section 6 的主数据源） |
plugin-data.json | extract | ✅ | 静态分析原始数据，补充 section 3 的检测结果细节 |
probe-report.json | probe | 可选 | 动态探针每工具 pass/fail + P99 |
profile.json | profile | 可选 | 性能剖析（FOOTPRINT tokens + hook P99） |
eval-report.json | evaluate | 可选 | A/B 结果，VALUE/E2E_IMPACT/TOKEN_COST |
docs/SCORING.md | 仓库 | 参考 | 评分规则手册（作为依据引用） |
certification.json 结构
{
"schemaVersion": "v4",
"pluginId": "my-plugin",
"version": "1.0.0",
"staticOnly": false,
"categories": {
"safetyCompliance": {
"label": "Safety & Compliance（安全合规）",
"score": 63,
"dimensions": {
"SEC": { "score": 100, "weight": 0.4 },
"COMPLIANCE": { "score": 30, "weight": 0.4 },
"QUALITY": { "score": 55, "weight": 0.2 }
}
},
"functionalQuality": { ... },
"performance": { ... }
},
"dimensions": {
"SEC": 100, "COMPLIANCE": 30, "QUALITY": 55,
"FUNC": 100, "STABLE": 100, "VALUE": 60,
"FOOTPRINT": 62, "CONTEXT": "N/A", "HOOK_OVERHEAD": 100,
"E2E_IMPACT": 64, "TOKEN_COST": 57
}
}
关键约束
- 不修改任何输入 JSON 文件
- 所有数字从 JSON 提取，禁止编造
- 不使用评价性词汇（好/差/优秀/糟糕），只用"检测到 X"、"X = Y"等事实陈述
- 每个扣分项必须包含 5 要素：检测事实 + 评分规则依据 + 扣分计算 + 严重度档位标签（🔴/🟠/🟡/🟢） + 修复方法
- 完整性硬要求：
findings.json 中每条 deduction > 0 都必须在 section 6 出现- 每个 < 100 的子维度（FUNC/STABLE/VALUE/FOOTPRINT/HOOK_OVERHEAD/E2E_IMPACT/TOKEN_COST）必须有单独的扣分说明
- 运行时泄漏不作为 Performance 量化维度，由 SEC-22~31 静态规则曝光，走 section 6.1 的 🔴 档
- 6.4 节用数字声明完整性（"X 条命中，Y 条未触发"），数字必须与 findings.json 核对
- 满分项（100 分）在 section 6 不列，但在 6.4 未触发汇总里计数
staticOnly: true 时：Functional Quality / Performance 大类为 N/A，section 4/5 空骨架保留但标注"仅静态分析"- N/A 维度：注明"该维度未检测"及原因（如"channel 插件需要 Gateway runtime" / "未执行 Step 4 evaluate"）
- 探针模式：若 probeMode=mock，section 2 顶部必须醒目标注"FUNC/STABLE 对 native 依赖插件可能失真"
- 不暴露内部字段名：禁止出现 JSON 字段路径，用自然语言描述
- 报告格式遵循
references/report-template.md，不含附录节（旧版 section 7 已删除）
- 严重度分层硬要求：
- Section 2 必须包含"严重度原则"说明（四档：运行时真实影响 > 安全红线 > 规范合规 > 代码卫生）
- Section 6.5 修复优先级不按扣分数排，必须按严重度四档分组，档内再按扣分 + ROI 排
- 不允许说"扣 25 分的 X 比扣 16 分的 Y 更严重" —— 除非两者在同一严重度档，这违反严重度分层原则
- N/A 维度不等于 OK，必须显式标注"未评估"原因
