| name | audit-reporter |
| description | Use as the FINAL stage of the code-audit pipeline. Reads confirmed.json (output of audit-verifier) and renders a self-contained single-file HTML report (always) and optionally an Excel workbook. The HTML contains summary stats by severity/category/module, filterable finding cards with code snippets and audit trails (reviewer + verifier). Not for emitting findings (use audit-reviewer) or verifying findings (use audit-verifier). |
Audit Reporter
汇总确认后的 finding，渲染 HTML（必需）+ Excel（可选）报告。
When to Use
适用：
audit-verifier 已写出 confirmed.json- 在
code-audit-verifier-agent 主流程的收尾被调用
不适用：
- 还没有
confirmed.json → 回到 audit-verifier
- 想要重新渲染上一次 run 的报告 → 也用本 skill，传
--run-id
Hard Gates
- 不修改
confirmed.json、findings/、verifications/
- 报告必须是单文件 HTML，CSS / JS 全部 inline，可离线打开
- Excel 渲染失败（如缺 openpyxl）不阻断 HTML 渲染
- 报告内不暴露源代码全文，只展示 finding
evidence.code_snippet 字段
Workflow
1. 读取输入
.garage/code-audit/runs/<run_id>/plan.json：拿 run meta + module 清单.garage/code-audit/runs/<run_id>/confirmed.json：拿确认后的 finding 数组- 可选
.garage/code-audit/runs/<run_id>/findings/<module>.json：用于在报告"被驳回 finding"区展示 rejected / needs_more_evidence 的 finding 摘要（保持审计完整性）
2. 数据校验
- 每条 finding 字段完整性（按
finding-schema.md）
- enum 字段值合法（
severity / category / confidence / verifier.status）
- 行号合理（
line_start <= line_end）
- 拒绝 enum 拼写错误（防止报告里出现 "HIGH" 与 "high" 同时存在）
校验失败 → 不渲染报告，把错误写到 stderr 并返回错误码。
3. 渲染 HTML
调用 scripts/render_html.py（Slice B 引入），输出 .garage/code-audit/runs/<run_id>/reports/report.html。
HTML 内容契约（详见 references/report-schema.md）：
- 顶部 banner：run_id / 时间 / target / pack version
- Summary 区：总 finding 数 / 按 severity 分布饼图（SVG） / 按 category 柱图 / 按 module 表
- Filter 区：severity / category / confidence / module / verifier_status 多选筛选（纯 JS）
- Finding 卡片列表：每条卡片
- 标题 + severity badge + category badge + confidence badge
<file>:<line_start>-<line_end> + 复制按钮- 代码片段（pre + code，简单高亮）
- description / evidence / suggested_fix
- audit trail：reviewer agent + ts → verifier agent + ts + status + reason + evidence_check
- 文件漂移告警：若 finding 的
file_sha256 与渲染时 file 当前 sha 不一致，卡片顶部加 ⚠ banner
- 底部："被驳回 finding" 折叠区：列出
rejected / needs_more_evidence 的 id + 模块 + 理由摘要
4. 渲染 Excel（可选）
若调用方传 --formats html,xlsx 或 --xlsx，调用 scripts/render_xlsx.py（Slice C 引入），输出 report.xlsx：
- Sheet 1 - Findings：每行一条 finding
- Sheet 2 - Summary：透视（severity × module）
- Sheet 3 - RunMeta：run_id / 起止时间 / 模块清单 / pack 版本 / agent 版本
- Sheet 4 - Rejected：被驳回与待补证据的 finding 概览
若 openpyxl 未安装：
- HTML 仍正常生成
- Excel 渲染跳过，stderr 写 "openpyxl not available, skipping xlsx output"
- 返回值不视为错误
5. 返回结构化摘要
run_id: <run_id>
report_paths:
html: .garage/code-audit/runs/<run_id>/reports/report.html
xlsx: .garage/code-audit/runs/<run_id>/reports/report.xlsx (or "skipped" / "n/a")
finding_total: <int>
by_severity: {critical: N, high: N, medium: N, low: N, info: N}
by_module: {runtime: N, knowledge: N, ...}
next_action: done
Output Contract
- 写盘：
reports/report.html（必需）+ reports/report.xlsx（可选）
- 不修改：confirmed.json / findings / verifications
- 唯一下一步：
done（pipeline 结束）
Red Flags
- HTML 引用外部 CDN（必须 inline）
- 把源代码全文嵌入 HTML（只能用 finding 内已记录的 code_snippet）
- 渲染 Excel 失败导致 HTML 也未生成（应隔离失败）
- 报告里隐藏被驳回 finding（必须保留可见审计区，哪怕折叠）
- 拼错 severity / category 但报告"渲染成功"
Verification
Reference Guide
| 文件 | 用途 |
|---|
references/report-schema.md | HTML / Excel 输出格式契约（Slice B/C 之前确定） |
Scripts（后续 Slice 引入）
| 文件 | Slice | 用途 |
|---|
scripts/render_html.py | B | confirmed.json → report.html 渲染脚本 |
scripts/render_xlsx.py | C | confirmed.json → report.xlsx 渲染脚本 |
assets/report-template.html | B | HTML 模板骨架（含 inline CSS 占位） |
assets/report-style.css.txt | B | inline 到 HTML 的 CSS |
