原文内容

从实验日志到可读报告：AI 辅助整理 API 测试结果

面向 USTC Token Plan / 词元计划成长营的实践案例。
关键词：JSONL、指标摘要、Markdown 报告、事实复核、行动建议。

这个案例解决什么问题

做 API 测试的时候，最真实的产物往往不是一份漂亮报告。

而是一堆 JSONL、终端输出、错误码、延迟统计和 token 用量表。

这些东西对复现实验很重要。

但说真的，不太适合直接拿给团队成员、项目负责人或后续参与者看。

懂脚本的人还能慢慢翻。不懂的人看到一屏 JSON，大概率只会问一句：

所以结论是什么？

这个案例想分享的是一个很实用的整理流程：实验仍然由人设计和执行，AI 不替代压测、调用验证或人工判断；AI 主要负责把原始实验记录整理成 结构化 Markdown 报告，让复核、沟通和下一步行动都更清楚。

为什么日志不能直接等于报告

一次 API 测试很少只产生一个结论。

它更像是产生一堆碎片。

这些信息如果只停留在日志里，会有几个麻烦。

开发者复核成本高。
每次都要重新打开日志、筛字段、算指标。

非开发者难以理解。
错误码和 JSON 字段不能直接说明风险，也不能直接说明下一步该干什么。

结论容易失真。
只截几行报错，可能忽略整体成功率；只看成功率，又可能忽略延迟和 429 分布。

后续对比困难。
下一轮测试如果换了口径，就很难判断到底有没有变好。

所以中间需要一层东西。

它既保留实验依据，又把信息组织成可以讨论、可以复核、可以行动的报告。

我推荐的流程

我比较推荐 「脚本统计 + AI 整理 + 人工复核」 这三段式流程。

1. 脚本负责采集事实

测试脚本只做确定性工作：

• 发起请求；
• 记录状态码；
• 记录耗时；
• 记录 token 用量；
• 写入 JSONL 或 CSV。

脚本不急着写最终结论。

原因很简单，脚本适合记录事实，不适合把临时观察包装成判断。

2. 统计脚本负责生成指标摘要

在日志基础上，生成一份适合分享和复核的指标摘要。

比如：

• 总请求数；
• 成功率；
• 错误码分布；
• 延迟分位数；
• token 汇总；
• 典型错误样例。

这里尽量用可重复运行的脚本，而不是手工复制粘贴。

手工整理不是不能做，但一旦要对比多轮结果，口径很容易飘。

3. AI 负责组织报告语言

把指标摘要和必要背景交给 AI，让它按固定模板生成 Markdown 草稿。

AI 的任务不是编造结论，而是把证据组织得更清楚。

它可以同时照顾几类读者：

• 给开发者，说明复现条件、错误类型和排查方向；
• 给管理者，说明总体风险、资源占用和下一步建议；
• 给后续测试者，留下同一套指标口径，方便下一轮对比。

这一步的价值很实际。

很多时候我们不是没有数据，而是数据太散，没人愿意读。

4. 人负责最终复核

这一步不能省。

AI 写得再顺，也不能替实验执行者承担事实准确性。

发布报告前，至少要看四件事：

• 指标是否真的来自日志统计；
• 结论有没有过度外推；
• 是否混入和报告无关的字段；
• 建议是否符合实际约束。

目录内容

这个案例里，我放了几个可以直接参考的示例文件。

logs-to-report/
├── README.md
├── examples/
│   └── metrics-summary.sample.json
├── reports/
│   └── sample-readable-report.md
├── scripts/
│   └── metrics_to_report_prompt.example.py
└── templates/
    └── api-test-report-template.md

一个最小可复用流程

先准备一份指标摘要。

示例文件是：

examples/metrics-summary.sample.json

然后生成给 AI 使用的报告提示词：

python .\scripts\metrics_to_report_prompt.example.py `
  --metrics .\examples\metrics-summary.sample.json

脚本不会调用任何模型。

它只做一件事，把已经整理好的指标变成一段更明确的提示词。

我比较喜欢这种分层方式。统计归统计，写作归写作，复核归复核。

这三个环节分开以后，报告就不容易变成一团玄学。

报告里最重要的三件事

1. 事实要清楚

比如：

本轮测试在 2026-05-XX 10:00-10:30 内完成，共发起 1000 次请求，成功率为 96.0%，P95 延迟为 4.9s。

这类内容必须来自统计结果。

没有统计出来，就不要写。

2. 判断要克制

不推荐这样写：

本接口已经完全稳定，可以放心大规模使用。

我更推荐这样写：

在本轮 30 分钟、并发 5 的测试窗口内，接口成功率为 96.0%，P95 延迟为 4.9s。当前结果说明该配置下具备继续试用价值，但还不能代表高并发或长时间运行场景。下一轮建议扩大测试窗口，并单独验证 429 错误下的退避策略。

后面这种写法没那么爽，但更靠谱。

它把 观察到的事实、暂时的判断、下一步行动 分开了。

3. 建议要能执行

报告最后不要只写「建议继续优化」。

这句话太空了。

更好的建议应该像这样：

• 参数侧，把 max_qps 下调一档，观察 429 是否下降；
• 日志侧，继续保留 error_type、retry_count、latency_ms；
• 测试侧，把长输出任务拆成独立阶段，不和短任务混用同一组 timeout；
• 报告侧，下一轮继续使用同一套指标口径，方便对比。

读者看完以后，应该知道下一步该做什么。

AI 在这里帮了什么

AI 在这个案例里最有价值的地方，不是替我做实验。

实验必须由脚本和人来完成。

AI 更适合做的是：

• 把零散指标组织成一份可读报告；
• 把开发者语言翻译成团队能讨论的语言；
• 提醒哪些结论可能过度外推；
• 帮忙生成不同读者版本，比如开发者版、管理者版、后续测试者版；
• 把下一步建议写得更明确。

但有一点很重要。

AI 不能凭空补数据。

报告里所有数字，都应该来自前面的指标摘要。

这个案例对我的启发

我以前会觉得，测试跑完以后，报告只是收尾工作。

后来发现不是。

报告其实是实验的一部分。

如果报告写不清楚，那这轮实验的价值就会打折。别人不知道你怎么测的，不知道异常怎么来的，也不知道下一轮该怎么改。

所以我现在更倾向于把 API 测试看成一个闭环：

脚本采集事实 → 统计生成指标 → AI 整理表达 → 人工复核结论 → 下一轮调整参数。

这个闭环跑起来以后，API 测试就不再是一次性尝试，而是变成了可记录、可复核、可沟通的工程资产。

我觉得这件事很适合放在词元计划成长营里分享。

因为它展示的不是炫技，而是一个更朴素的能力：

怎么把 AI API 的使用经验，沉淀成别人也能看懂、也能复用的东西。