如何阅读与分析 AI Agent 的执行轨迹
Agent 做完一道题，留下的不只是一个补丁，还有一份完整的执行轨迹——它每次读文件、每轮思考、每条命令的全程记录。 harness 只告诉我们「结果对不对」，而「过程可不可信」只能打开轨迹来读。 本单元已有四讲分别讲深八阶段模型、PRA 评分、问题分类与方法论栈——本页不重复它们， 只补四讲都没覆盖的两件事：怎么读（三遍阅读法 + 3 种轨迹载体的选读指南） 和读完练什么（30 分钟真实轨迹实训 + 一页纸报告模板）。把本页当作单元的「方法与动手」入口。
概览
| 项目 | 说明 |
|---|---|
| 本页定位 | 1.6 单元的方法与动手入口——与四讲零重复：八阶段地图在 第 1 讲、PRA 评分在 第 2 讲、问题 step 分类在 第 3 讲、五层评估栈与 lint/detector/PRA 三件套在 第 4 讲；本页只补「怎么读 + 怎么练」 |
| 前置知识 | 几乎为零——知道 Agent = harness 循环代码 + LLM 即可（Agent 心智 一页，5 分钟）；本页是单元最佳第一站 |
| 读完会什么 | 会按「谁读什么」选对 3 种轨迹载体中的一种打开；会用三遍阅读法（概览 → 定位 → 深读）在 30 分钟内读完一条真实轨迹并产出一页纸报告；知道读完之后去四讲的哪一页继续深入 |
| 真实素材 | 本仓 experiments/ 下 44 条真实实验轨迹（实训用 marshmallow-1359 的 qwen 事件流 10 行 + 任务书 + 结果） |
第一篇 · 打开之前：轨迹存在哪、以什么形态存在
轨迹 = Agent 的「行车记录仪 + 黑匣子」，三种载体各取所需
传统程序出错，我们看日志；Agent 出错，只看最终日志往往不够——因为它的「决策」发生在多轮推理里。 轨迹记录的是全程：每次工具调用的输入输出、每轮 assistant 的思考与行动、每个错误与恢复。 评测分数（%Resolved）只回答「对不对」，轨迹才能回答「它为什么这么走」「这条路可信吗」「下次怎么少走弯路」。
本仓 experiments/marshmallow-code__marshmallow-1359/…/agent/agent/qwen-stream.jsonl 是 brand 原生的 NDJSON 事件流——每行一个 JSON 对象，逐事件记录：
- 第 1 类行 {"type":"system","subtype":"init", …}：会话初始化——工作目录、可用工具清单（60+ 个）、MCP 服务器
- 第 2 类行 {"type":"user", …}：工具执行结果回灌——命令原文、输出、退出码（如 find … -name "ca-issue.json" 返回 empty）
- 后续 assistant 行：模型的思考与下一步动作决定——读轨迹时真正要「读」的部分
| 载体 | 形态与位置 | 适合谁 / 什么场景 |
|---|---|---|
| stream.jsonl 事件流 | brand 原生 NDJSON（qwen-stream.jsonl / opencode-stream.jsonl），在实验目录 agent/agent/ 下 | 做工具开发的人（PRA loader 直接从磁盘解析它）；想逐事件精确还原现场 |
| kimi-run.log 推理日志 | 人可读的文本日志（agent/agent/kimi-run.log），八阶段模型的实证来源（5 任务约 1700 行） | 初学者首选——有思考段/动作段的自然排版，读故事一样读 |
| trajectory_events 表 结构化入库 | S7 阶段入库到 experiments.db 的 v5 二十列结构化事件（本仓已积累 5940 条），轨迹全文在 traj_stream | 做统计分析 / Web 平台的人——SQL 聚合、跨轨迹对比、可视化 |
第二篇 · 三遍阅读法：从「看故事」到「做解剖」
先约定两件随身工具，再开始读
读轨迹时手里要有一张阶段地图（把每个 step 对号入座到 S0–S7）和一个弯路记录格式 （错误信号 → 归因 → 规避 → 验证）。这两件工具的完整定义——八阶段的逐阶段目标与控制源、 S3 环境修复循环、S6→S4 验证回退环、弯路恢复四元组——都在 第 1 讲《读一条 Agent 轨迹：八阶段解题过程模型》， 本页不重复展开，默认你随手可查。这里只给方法：三遍阅读法。
| 遍 | 回答的问题 | 具体动作 | 产出 |
|---|---|---|---|
| ① 概览遍 （5 分钟） | 这条轨迹大体经历了什么、难不难？ | 先看 result.json / manifest.json 的结果与元信息，再扫日志行数、工具调用次数 | 一句话总结 + 难度判断。日志长度 ≈ 任务复杂度代理：本仓实测最简任务 99 行、最难 902 行（量化依据见第 1 讲） |
| ② 定位遍 （10 分钟） | 每个 step 属于哪个阶段、弯路出在哪？ | 拿八阶段地图给轨迹分段贴标签；遇到错误信号就记一条「错误信号 → 归因 → 规避 → 验证」弯路四元组 | 阶段分段表 + 弯路清单（含弯路高发区 S3 的耗时占比） |
| ③ 深读遍 （15 分钟） | 关键决策对不对、可信不可信？ | 精读两处：S4 根因推理（它锁定的缺陷行对吗）与 S6 验证证据链（测试真的跑了吗、全过吗）；核对最终 diff 与修复方案是否一致 | 可信度判断：结果对 ∧ 过程可信 / 可疑成功 / 可信失败（矩阵定义见第 2 讲 PRA） |
第三篇 · 从「读」到「分析」：升级路径一页看清
四讲分工：你的下一步问题对应哪一讲
| 你读完轨迹后的问题 | 去这一讲 |
|---|---|
| 这个阶段划分凭什么？想搞懂 S0–S7 每个阶段的控制源与两个循环 | 第 1 讲 · 八阶段模型 |
| 这条轨迹「结果对但过程可疑」，怎么量化打分？ | 第 2 讲 · PRA 过程评分 |
| 哪个 step 是无用 / 冗余 / 低效 / 错误？怎么判、判得准吗？ | 第 3 讲 · 问题 step 分类学 |
| 五层评估栈怎么搭？lint / detector / PRA 三件套谁干什么？ | 第 4 讲 · 点+线与 Linting |
四讲的工具细节本页不重复。只补一张四讲都没有的图——分析结论最终去了哪里： 读出Insights不是终点，它们要回流到出题（弯路高发区预埋 hint）、Prompt（红线该收该放）与训练（轨迹筛选成燃料）， 新一轮实验再产生新轨迹——这是「轨迹是资产」的完整含义。
难度与结果"] B["定位遍
阶段分段 + 弯路清单"] C["深读遍
根因与证据链"] end subgraph Analyze["分析（四讲工具 · 机械接管）"] D["Lint
形式门票 · 第 4 讲"] E["Detector / PRA
语义诊断 + 综合分 · 第 2-4 讲"] end subgraph Use["用（反哺闭环）"] F["出题：弯路高发区预埋 hint"] G["Prompt：红线约束该收该放"] H["训练：轨迹筛选成燃料"] end Read --> Analyze --> Use Use -.->|新一轮实验产生新轨迹| Read
第四篇 · 课堂实训：30 分钟读完一条真实轨迹
实训对象：marshmallow-1359（qwen 事件流）
- 打开 experiments/marshmallow-code__marshmallow-1359/e2e-smoke-marshmallow-1359-202608050815/marshmallow-code__marshmallow-1359/agent/agent/qwen-stream.jsonl（10 行事件流，规模小、适合首读）
- 对照同目录下的 ca-issue.json（任务书）与 result.json（结果）——读轨迹必须「带着任务书读」，否则无法判断对错
| 任务 | 做什么 | 检验标准 |
|---|---|---|
| T1 概览 | 读 result.json + 统计事件流行数，写一句话总结 | 说清「什么任务、什么 brand、结果如何、用了几步」 |
| T2 定位 | 逐行扫事件流，给每行贴八阶段标签（地图见 第 1 讲）；遇错误信号记弯路四元组 | 产出分段表 + ≥1 条弯路记录；能指出弯路高发区是否在 S3 |
| T3 深读 | 找出 Agent 锁定根因的那一步与验证那一步，对照 ca-issue.json 判断推理是否正确 | 给出三态判断之一：结果对 ∧ 过程可信 / 可疑成功 / 可信失败，并附一句理由 |
- 任务 / brand / 结果 / 规模：四要素一句话
- 阶段分段：S0:行a-b → S1:行c-d → …（贴到八阶段地图上）
- 弯路清单：错误信号 → 归因 → 规避策略 → 验证（各占多少行/步）
- 可信度判断：三态之一 + 证据（根因对吗 / 测试真跑了吗）
- 这条轨迹里，哪些信息是 result.json 给不了、只有读轨迹才能知道的？
- 如果你来给这条轨迹写一条 lint 规则（机械可判），你会选哪个「坏味道」？写出触发条件。
- 三遍阅读法里，哪一遍最可能被工具替代？哪一遍最难被替代？为什么？
- 「日志长度 ≈ 难度」这条代理指标，在什么情况下会失效？（提示：弯路 ≠ 困难，也可能是环境太破）
收口：本页的两件新东西 + 四讲深挖地图
- 怎么读：3 种载体的选读指南（人读 kimi-run.log / 程序读 stream.jsonl / 平台读 trajectory_events 表）+ 三遍阅读法（概览 → 定位 → 深读，O(N) 通读拆成 O(1) 检索）
- 怎么练：30 分钟真实轨迹实训（T1/T2/T3）+ 一页纸阅读报告模板——全单元唯一一页动手