clawguard-report

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 命令。

步骤：

1. 读取 certification.json → 三大类分数、子维度分数、tokenSummary、tokenBreakdown
2. 读取 findings.json → 每条扣分项（ruleId / category / severity / location / deduction / fix / detail）—— 这是 section 6 的主数据源
3. 读取 plugin-data.json → 原始检测数据（securitySignals / apiUsage / codeMetrics / manifest），用于 section 3 检测结果细节
4. 可选读取 probe-report.json → 每工具 pass/fail + 错误原因 + P99，用于 section 4
5. 可选读取 profile.json → 性能剖析（FOOTPRINT tokens / hook P99），section 5 展示
6. 可选读取 eval-report.json → A/B 结果（VALUE / E2E_IMPACT / TOKEN_COST）
7. 读取 docs/SCORING.md → 评分规则（作为扣分依据引用）
8. 按照 references/report-template.md 的结构生成报告
9. 完整性自检：逐一验证 findings.json 中每条 deduction > 0 finding 都出现在 section 6；每个 < 100 的子维度都有单独说明；6.4 节的"未触发"统计数字与 findings.json 吻合
10. 将报告写入指定路径

输入文件

文件	来源步骤	必需	说明
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 },
              
      
    
      ... 
      ... 
  
   
         
         
         
       
    
    
  

关键约束

1. 不修改任何输入 JSON 文件
2. 所有数字从 JSON 提取，禁止编造
3. 不使用评价性词汇（好/差/优秀/糟糕），只用"检测到 X"、"X = Y"等事实陈述
4. 每个扣分项必须包含 5 要素：检测事实 + 评分规则依据 + 扣分计算 + 严重度档位标签（🔴/🟠/🟡/🟢） + 修复方法
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 核对
6. 满分项（100 分）在 section 6 不列，但在 6.4 未触发汇总里计数
7. staticOnly: true 时：Functional Quality / Performance 大类为 N/A，section 4/5 空骨架保留但标注"仅静态分析"
8. N/A 维度：注明"该维度未检测"及原因（如"channel 插件需要 Gateway runtime" / "未执行 Step 4 evaluate"）
9. 探针模式：若 probeMode=mock，section 2 顶部必须醒目标注"FUNC/STABLE 对 native 依赖插件可能失真"
10. 不暴露内部字段名：禁止出现 JSON 字段路径，用自然语言描述
11. 报告格式遵循 references/report-template.md，不含附录节（旧版 section 7 已删除）
12. 严重度分层硬要求：
    • Section 2 必须包含"严重度原则"说明（四档：运行时真实影响 > 安全红线 > 规范合规 > 代码卫生）
    • Section 6.5 修复优先级不按扣分数排，必须按严重度四档分组，档内再按扣分 + ROI 排
    • 不允许说"扣 25 分的 X 比扣 16 分的 Y 更严重" —— 除非两者在同一严重度档，这违反严重度分层原则
    • N/A 维度不等于 OK，必须显式标注"未评估"原因