可视化表达：从图到证据
本章要解决的问题
怎样让可视化成为可审计证据，而不是装饰性图表？
读者读完应获得什么
- 能定义“证据型可视化”的标准。
- 能把图、路径、表格、报告组合成证据包。
- 能说明 AI 输出为何必须可回跳事实层。
本章不讲什么
- 不教授设计美学教程。
- 不比较所有前端可视化库。
代码可视化的失败模式很常见：图很漂亮，但无法回答“所以呢”。证据型可视化要求每个视觉元素都能追溯到数据，并能支持决策。
证据标准
一条可视化结论应可检查：
- 来源：来自静态/动态/变更哪一层
- 定位：对应哪个文件/符号/行号
- 路径：如何从问题走到该节点
- 置信度：确定还是候选
- 动作：建议测试、Review 关注点或回滚条件
表达组合
| 表达 | 适合 |
|---|---|
| 子图 | 局部关系探索 |
| 路径列表 | 影响链解释 |
| 表格 | 测试、风险、规则 |
| 报告 | PR/Agent 交付物 |
| 查询轨迹 | AI 审计 |
PR-42 的证据包不应只有一张调用图，而应包含：
- 变更实体表
- 影响路径
- 相关测试表
- 风险说明
- 查询轨迹
见 examples/mini-shop/artifacts/verification-report-pr-42.md。
从“看见”到“证明”
对 AI 输出的要求
模型可以说“可能影响订单总价”，但系统应附上：
path: apply -> calculateTotal -> createOrder -> create
tests: PricingServiceTest, OrderServiceTest
rule_check: pricing-no-payment = pass
否则 Reviewer 只能选择相信或放弃，无法审计。
设计原则
- 默认展示任务相关子图，不丢全库大图
- 节点可点击回源码
- 边显示来源与置信度
- 先摘要后下钻
- 报告与图共享同一查询结果
图可以是插图，也可以是证据。差别在于：读者能否从一张图回到实体 ID、源码位置、置信度与查询轨迹，并据此做合并决策。没有这些，颜色再醒目也只是装饰；有了这些，哪怕只是路径列表加测试表，也比全仓力导向大图更像 Review 材料。
本章的七步法是为了对抗“先画图再找故事”的习惯。正确顺序永远是：先有主张，再绑实体，再选最小表达。PR-42 的三件套（路径、测试、规则）就是这个顺序的最小完备例。
局限
- 证据链过长会淹没重点
- 低置信度边展示不当会造成误导
- 需要产品化的信息层级，而不是一次画完
小结
- 可视化的目标是证据，不是装饰。
- 图、路径、表、报告应组成可审计证据包。
- AI 结论必须回跳到图谱事实。
- 好的表达服务于决策动作。
证据包模板（可直接复用）
# Evidence Pack
Claim: ...
Entities: ...
Paths: ...
Tests: ...
Rules: ...
Confidence: ...
Query Trace: ...
Suggested Action: ...
AI 生成的自然语言说明只能作为 Claim 的草稿，不能替换后六项。
工作示例：同一结论的两种呈现
弱呈现：
这张图显示订单和定价有关系，所以可能有风险。
强呈现：
变更实体
DiscountPolicy.apply；影响路径apply -> calculateTotal -> createOrder -> create；相关测试 2 个将失败；架构规则通过；查询轨迹 4 步可回放。
出版级终稿要求全书默认使用强呈现：每个重要视觉结论都能改写成强呈现段落。
常见问题：证据可视化
为什么不直接给最大图？
全图不可决策，证据需要裁剪与解释。
颜色编码可以使用吗？
可以，但必须有图例，并服务信息而非装饰。
AI 插画能当证据吗？
不能。证据必须可回跳数据。
本章检查清单
- 结论能否改写成强呈现
- 是否有来源与置信度
- 是否可回源码
- 是否服务明确动作
关键要点复盘
围绕「可视化表达：从图到证据」，读者离开本章前应能做到：
- 陈述证据七步法
- 用 PR-42 组装路径+测试+规则三件套
- 拒绝无 ID/无轨迹的插图
- 说明颜色与 AI 插画的边界
- 衔接到工程场景篇
若任一做不到，请先复习本章例子与练习，再继续向后读。
证据图判定标准
一张图要成为证据，必须同时满足：
- 可追溯：节点/边能回到源码或产物 ID
- 可复现：给定同一输入可再生成
- 有任务边界：说明查询条件/过滤
- 有置信度：低置信不可画成实线“事实”
反例：无过滤的全仓力导向图、无来源标签的调用箭头、与报告数字不一致的截图。
PR-42 证据三件套
- 影响路径图：
apply -> calculateTotal -> createOrder -> create - 测试表：两测需更新断言
- 规则结果：
pricing-no-payment = pass
三者缺一，就从“证据”退回“插图”。
如何把结论做成证据（操作步骤）
- 锁定主张：先写一句话结论（例如：
PR-42会改变 VIP 订单总价并影响支付入参）。 - 绑定实体 ID：把结论落到
method:DiscountPolicy#apply等稳定 ID，而不是“某个折扣文件”。 - 选择最少表达：路径图 + 测试表 + 规则结果；默认不渲染全仓大图。
- 标注来源与置信度：边/结论标明 static/dynamic 与 high/medium/low。
- 提供回跳：每个关键节点可定位文件与行号，或指向 artifacts。
- 保留查询轨迹：记录
find_symbol/find_callers/related_tests等步骤，使结论可复现。 - 分级展示：阻断/重要/提示分层，避免证据过载。
claim
-> entities
-> minimal views (path/table/rule)
-> confidence + source
-> source jump
-> query_trace
-> reviewer decision
这套步骤是方法，不只是版式建议。缺步骤 2/4/6 的图，通常只能算插图。
练习
- 把
verification-report-pr-42.md拆成“图/路径/表/轨迹”四类证据。 - 指出一张“很好看但不可审计”的图可能缺少哪些字段。
- 为 AI 结论设计必须附带的最小证据包字段。
本章导航
- 上一章：代码图谱：节点、边与属性
- 下一章：代码库理解与上下文构建
- 相关章：变更影响分析与验证；构建代码图谱
延伸阅读与参考资料
- Nielsen Norman Group: Minimize Cognitive Load：信息呈现与认知负荷。
- OpenTelemetry visualization of traces：路径可视化直觉。
- SARIF：机器可读分析结果交换。资料卡：
../docs/research-cards/rc-sarif.md - GitHub PR checks：证据进入工作流的位置。
- D3 graph interaction patterns：交互探索参考（实现可选）。
- 本书样例：
examples/mini-shop/artifacts/verification-report-pr-42.md。