> For the complete documentation index, see [llms.txt](https://code-visualization.shawnxie.top/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://code-visualization.shawnxie.top/di-liu-pian-shi-jian-xiang-mu/ai-change-verification-report.md).

# AI 修改后的验证报告

AI 修改后的验证报告用于帮助 Reviewer 判断改动是否可合并。它应基于代码图谱、影响面分析、测试结果、架构规则和 Agent 查询轨迹生成。

这份报告不是 AI 的自我解释，而是系统根据代码事实生成的证据包。它应该能够被人类独立检查。

## 报告目标

验证报告需要回答：

* AI 修改了什么。
* 为什么这些修改与任务相关。
* 可能影响哪些入口、模块和测试。
* 哪些测试建议运行或已经运行。
* 是否存在未覆盖风险。
* 是否触碰安全或架构边界。
* Agent 是否查询过必要上下文。

如果报告无法回答这些问题，Reviewer 就只能回到手工排查。

## 改动摘要

改动摘要应该区分不同类型：

* 功能代码改动。
* 测试代码改动。
* 配置改动。
* 文档改动。
* 重构或格式化改动。

每个改动项最好映射到代码实体，而不仅是文件名。例如：

```
修改方法：OrderService.cancel(Long)
新增测试：OrderServiceTest.cancel_shouldReleaseStock
修改配置：order.cancel.timeout
```

这样报告才能进一步连接影响面和测试证据。

## 影响面摘要

影响面摘要展示从变更实体到业务入口、调用方和相关测试的路径。

报告可以按风险排序：

1. 核心业务入口。
2. 高频运行路径。
3. 跨模块影响。
4. 缺少测试覆盖路径。
5. 低置信度推断路径。

影响面摘要不需要展示完整图谱，但需要提供证据链接，让 Reviewer 能追溯到源码和图谱路径。

## 测试建议

测试建议应该包含：

* 建议运行的测试。
* 推荐依据。
* 是否已经运行。
* 运行结果。
* 覆盖缺口。

示例：

```
建议测试：OrderControllerTest.cancel_shouldReturnSuccess
依据：覆盖入口 DELETE /orders/{id}
状态：未运行
风险：入口路径受影响但缺少本次验证
```

如果没有 Coverage 数据，报告应明确说明“测试推荐基于命名和调用关系推断”，避免把候选关系当成确定覆盖。

## 风险节点

风险节点可以来自：

* 高复杂度。
* 低覆盖率。
* 高频变更。
* 生产高频路径。
* 安全敏感路径。
* 核心业务模块。
* 架构边界变化。
* 低置信度调用边。

报告不需要把所有风险都阻断，但要让 Reviewer 知道应该重点看哪里。

## 架构和安全检查

报告应包含架构规则检查结果：

* 是否新增跨层依赖。
* 是否修改公共接口。
* 是否绕过统一访问层。
* 是否触碰特定 owner 模块。

安全检查可以包含：

* 是否新增用户输入路径。
* 是否修改权限判断。
* 是否新增敏感日志。
* 是否让数据流向危险 Sink。

最小系统可以先做规则提示，后续再接入更强的数据流分析。

## Agent 查询轨迹

查询轨迹是 AI 时代验证报告的新内容。它记录 Agent 是否做了必要上下文查询。

例如：

```
Agent 查询记录：
- find_symbol(OrderService.cancel)
- find_callers(OrderService.cancel)
- related_tests(OrderService.cancel)
- architecture_rules(order)
```

如果 Agent 没有查询调用方或测试，报告可以提示“上下文检查不足”。这能帮助团队逐步规范 Agent 工作流。

## 报告格式

建议同时输出两种格式：

* Markdown：给人类 Reviewer 阅读。
* JSON：给 CI、平台和 Agent 继续消费。

Markdown 报告可以放进 PR 描述或评论。JSON 报告可以用于自动规则判断，例如高风险路径未运行测试时阻断合并。

## 示例报告结构

```markdown
# AI 修改验证报告

## 改动摘要

## 影响面

## 建议测试

## 已运行验证

## 风险节点

## 架构和安全检查

## Agent 查询轨迹

## Reviewer 检查清单
```

## Reviewer 检查清单

最终报告应该转化为动作：

* 是否确认改动范围符合任务。
* 是否查看高风险影响路径。
* 是否运行建议测试。
* 是否检查未覆盖路径。
* 是否检查权限和数据流。
* 是否确认架构规则没有违规。
* 是否需要 owner 追加审核。

## 小结

AI 修改后的验证报告是本书实践闭环的终点。它把源码结构、代码图谱、影响面分析、测试建议、架构规则和 Agent 查询轨迹汇总为可审查证据。

完成这份报告后，一个最小代码理解系统就具备了基本价值：它不仅能帮助人理解代码，也能帮助 AI 在工程约束下修改代码，并帮助 Reviewer 判断修改是否可信。