别只看 AI Agent 的最终回答：rungraph 如何把重试、子代理与人工介入还原成可追溯执行图
一次 AI 编程任务结束后，终端里通常只剩一段总结：“修复完成，测试已通过”。可一旦结果不对、费用异常或改动碰到不该碰的文件，真正需要回答的问题会立刻变多：谁启动了子代理？哪个工具调用先失败？失败后是否真的被修复？人类拒绝某次权限请求后，任务又沿什么路径继续？
把完整 JSONL 会话逐行打开当然能找到答案，但长任务很快变成几千行文本。更麻烦的是，编排器、子代理和工具调用往往分散在不同记录中；时间顺序仍在，因果关系却不容易一眼看出。rungraph 是一个 MIT 许可的本地工具，目标正是把这类记录转换为有向执行图：编排器、子代理和工具成为节点，启动与返回关系成为边；重试、失败和人工干预则被标注为会改变任务走向的信号。
它适合用于复盘和调试，而不是替代 Agent 本身。项目明确强调不需要 hook、wrapper 或遥测：对于已存在的会话，它可以回溯读取本地记录；正在运行的任务则通过文件监听让图持续增长。这一点决定了它的边界：它看到的是适配器支持的本地 transcript，而不是操作系统中所有进程、更不是远端服务的完整审计日志。
从“聊天记录”改用“执行路径”理解失败
对单轮问答来说，文本顺序足够。但编码 Agent 的一次运行往往包含并行分支：主 Agent 分派调查任务，子代理修改代码，另一个分支跑测试；随后某个编辑失败，主流程读取文件再重试。若只看最后一条消息，很容易把“尝试过”误认为“完成了”。
rungraph 的图模型把三个关系放在一起：谁派生了谁、哪个工具在何时调用、路径为什么改变。工具节点不只显示工具类型，也可以保留调用输入、输出、错误和耗时；连续的相同调用会合并，避免测试—修复循环在画布上变成难以浏览的节点墙。点击某个节点可追溯它的上下文，而不是只得到一个成功或失败的颜色。
项目还从执行记录推导信号。例如，同一位置反复失败会形成 retry storm；错误出现后没有后续修复则成为 unresolved error；拒绝权限、回答问题或中断会作为 intervention 保留；耗时或 token 显著偏离其他步骤可被标记为 outlier。它们都不是模型对代码质量的裁决，而是帮助人先缩小调查范围的启发式提示。看到“未解决错误”后，仍要打开节点检查具体命令、退出码与后续路径，不能把一个图标当成事故结论。
先在本机建立最小可复现视图
README 给出的最短启动方式只有一条命令。它会扫描本地会话目录、启动本地服务并打开浏览器：
npx rungraph
rungraph 要求 Node.js 20 或更高版本。首次使用时，先在一个非敏感测试项目中运行，确认浏览器打开的是本机地址，并核对它识别出的运行记录是否符合预期。其服务默认绑定在 127.0.0.1；项目也说明会检查 HTTP Host header，以减少恶意网页借 DNS rebinding 访问本地 transcript 的风险。即便如此，浏览器本地服务不等于“内容天然可公开”：会话中仍可能有业务路径、命令输出和提示词，应按真实敏感度控制屏幕共享与文件权限。
命令行模式更适合把一次复盘纳入脚本或让另一个 Agent 先筛选范围。先列出记录，再只获取一个 run 的图结构：
npx rungraph list --json npx rungraph graph '' --json npx rungraph find ' ' 'src/auth.js' --json
这里最重要的是先用 find 缩小范围。大型图的完整 JSON 可能很长；如果目标只是确认 src/auth.js 被谁修改过，先按文件名查节点，再针对命中的节点取详情，比把整段会话一股脑塞进新的模型上下文更节省 token，也降低了无关内容扩散到后续提示词的风险。
把“失败”拆成可核验的问题
假设 Agent 报告测试通过，但线上问题仍在。不要先要求它“再检查一遍”。可以按图的因果路径拆成四个问题：第一，测试命令是否真实执行，还是只出现在计划里；第二，失败的调用是否有随后成功的调用，还是被新的任务分支遮住；第三，最终改动来自主 Agent 还是子代理；第四，人类是否曾拒绝某项操作，从而让后续方案偏离原计划。
这种拆法比逐字阅读 transcript 更可靠，因为每个问题都能落到节点、边和原始工具记录。复盘笔记应同时写下 run ID、查询词、检查时间与最终验证命令，避免图形结论脱离其可复查的原始上下文。比如“测试执行了吗”应查看测试工具节点的命令和退出状态；“错误是否解决”则检查失败节点之后是否存在与该错误相关的修复和验证，而不是只看最后的自然语言结论。对 token 或耗时异常，也应先确认它属于长上下文、重试循环、等待外部服务，还是确实发生了无效规划，再决定优化提示词、工具接口还是任务拆分。
rungraph 支持将图作为 .rungraph 文件显式导出。导出前会输出库存信息，并检测高置信度的密钥模式；发现疑似密钥时，用户可选择删改、只导出结构，或明确承担风险后继续。一个更稳妥的团队流程是：默认导出 --structure-only 用于讨论执行形状；只有确实需要排查提示词或工具输出时，才在受控渠道分享完整 bundle。任何自动检测都不是数据脱敏保证，导出前仍应人工检查文件路径、命令输出和客户数据。
npx rungraph export --last 2 --structure-only npx rungraph open team-review.rungraph
导出的文件是传递载体而非云端同步机制：接收者用 open 在自己的机器上临时查看。这个设计把传输通道和访问控制留给团队既有的机制，也意味着发送者应像处理日志制品一样审查收件人和保留期限。
MCP 能帮忙问问题，不能替代证据判断
rungraph 还提供 MCP 接口。一次性安装后，兼容客户端可以通过 list_runs、get_graph、find_nodes、get_detail 等只读工具查询运行记录，并用 focus_nodes 在已打开的图中高亮相关节点：
npx rungraph mcp --install npx rungraph mcp --check
这很适合把问题问得具体，例如“上次运行中哪些编辑失败后没有恢复”“哪些步骤触碰了这个文件”。但必须把 MCP 返回内容视为待核验的本地证据，而不是让 Agent 根据摘要直接断言根因。尤其是分享 bundle 时，运行记录本身可能含有不可信文本；不要因为它出现在图里，就让另一个 Agent 把其中的命令或指令当作应执行的操作。
何时值得引入，何时要补别的控制
如果团队已经使用 Claude Code 或 Codex CLI，并且痛点是难以复盘多代理任务、难以确认重试是否真正结束，rungraph 提供了一个低接入成本的观察层：不改执行链路，先把已有记录变成可查询的结构。它尤其适合代码审查前核对“做过什么”、故障后定位“从哪里偏航”、以及在不直接暴露全部 transcript 的情况下共享执行轮廓，也适合为一次人工介入保留可解释的上下文。
但它不替代权限控制、分支保护、日志留存或生产审计。图能说明某份本地记录显示了什么，不能阻止危险命令，也不能证明记录之外的外部系统没有变化。把它放在“可观测与复盘”这一层，并结合最小权限、测试、独立日志和人工审批，才能让 AI Agent 的执行过程既更透明，也不被误当作已经受控。