Pi Agent 101｜12｜Observability and Sharing

先说人话：Agent 最值得复盘的，往往不是最后一句回答，而是中间到底发生了什么。

它读了哪些文件？运行了什么命令？为什么改这个地方？测试失败在哪里？上下文什么时候压缩？这些过程如果没有记录，agent 就会变成一个很会说话但很难追责的黑盒。

Agent 的结果不只是最后一段回答。真正有价值的是中间过程：读了什么文件、运行了什么命令、工具失败在哪里、上下文什么时候压缩、token 和成本如何变化、用户从哪里分支、最终如何收束。Pi 把这些信息放进 session、footer、HTML export 和 observability 设计里。

这张图的重点是证据链。Agent 的最终答案不够，用户还需要知道过程：模型看到了什么，执行了哪些工具，哪里失败，哪里重试，是否压缩过上下文，最后为什么得出这个结果。

Observability 不是给运维看的附属功能，而是 agent 产品能不能被信任、复盘和改进的基础。

给基础读者的慢速版地图

Agent 的最终答案只是结果，过程才是证据。可观测性让用户知道 Agent 做了什么、为什么卡住、哪里失败、是否调用了工具、是否压缩了上下文。分享则把这些过程变成可以复盘的文档，但也必须注意隐私边界。

读图说明：这张图把“观测出口”拆成五个连续位置。先不要记术语，先看每一格负责什么，以及上一格的结果怎样交给下一格。

读图说明：这张图把“事件类型”拆成五个连续位置。先不要记术语，先看每一格负责什么，以及上一格的结果怎样交给下一格。

读图说明：这张图把“调试层次”拆成五个连续位置。先不要记术语，先看每一格负责什么，以及上一格的结果怎样交给下一格。

读图说明：这张图把“分享流程”拆成五个连续位置。先不要记术语，先看每一格负责什么，以及上一格的结果怎样交给下一格。

读图说明：这张图把“隐私边界”拆成五个连续位置。先不要记术语，先看每一格负责什么，以及上一格的结果怎样交给下一格。

这组图的目的不是替代正文，而是给读者一个低门槛入口：先形成整体画面，再回到正文理解为什么这些边界必须存在。

读完这一篇，你应该能看懂什么

• 理解 agent observability 为什么不等于普通日志
• 看清 session export 如何复用 runtime 的消息和工具渲染
• 学会默认安全地记录结构化事件，而不是记录敏感内容

和主流产品怎么对应

Claude Code、Codex CLI 和 Cursor 都会把 agent 过程展示给用户，但“看见过程”和“能复盘过程”不是一回事。你看到模型跑过命令，不代表事后还能还原：它为什么跑这条命令，工具结果有没有进入下一轮上下文，哪一步开始偏了。

OpenClaw 这类系统更需要这层能力。一次回复可能来自 channel 事件、plugin hook、provider stream 和工具调用的组合。没有 session export、trajectory 或安全观测事件，出了问题只能猜。

Session 是可观测底座

Pi 的 JSONL session tree 记录了消息、工具结果、custom entry、compaction、branch summary、model change 等事实。它既服务继续对话，也服务 debug、导出和分享。

README 里提到公开 OSS coding agent sessions 的价值：真实任务、工具使用、失败和修复过程，比 toy benchmark 更能反映 agent 能力。

HTML export 的意义

Pi 的 HTML export 把 session data base64 注入自包含 HTML，同时内联 markdown、highlight、CSS 和 JS。更具体地说，导出文件里会有一个 script 标签保存 base64 编码后的 session JSON；浏览器端 JS 读取这段数据、解码、再用同一套 message/tool renderer 渲染成可浏览页面。

内置工具和扩展工具可以通过 renderer 输出可读展示。这样分享出去的是一个单文件证据包，而不是一堆依赖本地环境的 JSONL 和资源路径。

这个设计让一次 agent session 可以被 review，而不要求接入服务端。对 OSS 协作、issue 复盘、教学文章都很有用。

安全默认的 observability

Agent observability 最危险的是把 prompt、completion、tool args、tool results、headers、API keys 全部打出去。Pi 的 observability 设计倾向 runtime-agnostic、safe-by-default：记录 trace/span、生命周期、时延、错误和状态，但不默认记录敏感内容。

这和 footer 的思路一致：给用户实时看到成本、上下文压力、模型和扩展状态，但不把私密内容暴露给外部系统。

放到修测试这个例子里

一次失败测试修复过程，如果最后失败，用户真正需要的是完整证据链：模型为何选择这个文件，工具输出是什么，编辑是否成功，测试失败信息是什么，是否发生 compaction，是否从某个分支继续。Session export 和 observability 的目标，就是让这些问题可以回答。

工具失败时怎么定位

还是“修复失败测试”。假设 agent 运行到一半，bash 工具失败了，最后模型给出的总结也不对。一个可观测的 agent 至少应该让你三步定位问题。

第一，看 footer。先确认当前模型、上下文占用、token/cost、是否触发过 compaction。如果上下文已经接近上限，问题可能不是工具本身，而是模型这一轮看到的信息不完整。

第二，看 session export。顺着事件找到失败的 tool call，看它的参数、开始时间、结束状态、截断后的输出，以及失败后模型是否真的读到了 tool result。

第三，看安全观测事件。你应该能看到 tool_start、tool_end、error、compaction、agent_end 这些结构化事件，但不应该默认把完整 prompt、API key、请求 header、长工具输出全打到外部 telemetry 里。

这就是 safe-by-default 的具体含义：本地 session 可以保留足够复盘的信息；发到外部日志系统的内容要默认脱敏、限量、结构化。

可迁移的边界

如果自己做 harness，trace event 要默认结构化、可脱敏、可采样。内部 session 可以保存足够完整的复盘事实；外部分享或日志系统只应该拿到必要字段，避免把 prompt、文件内容、密钥或本地路径直接暴露出去。

Agent 的可观测性和普通应用不一样

普通应用的 trace 关注请求路径、延迟和错误。Agent 的 trace 还要关注推理过程的外部证据：prompt 片段、工具调用、文件变化、用户确认、模型 stop reason、上下文压缩、分支路径。

但这些信息里也可能包含敏感内容。代码、密钥、路径、客户数据、内部 prompt，都不能随便发到外部日志系统。所以 observability 需要 safe-by-default：本地 session 可以完整些，外部分享要脱敏、限量、结构化。

Sharing 不是炫耀运行过程

Trajectory export、HTML export 或分享链接的价值，是让失败可复盘，让团队能讨论 agent 为什么这样行动。一个好的分享结果应该回答：任务目标是什么，关键步骤是什么，工具结果是什么，在哪里失败或成功，用户有没有介入。

如果分享只是一段聊天截图，调试价值很低；如果分享泄漏了全部上下文，安全风险又太高。Pi 这层机制要说明的就是这条边界。

这里的取舍

• 取舍：记录底座
  • Pi 的倾向：JSONL session tree
  • 可迁移原则：可恢复和可审计用同一事实源
• 取舍：实时观测
  • Pi 的倾向：Footer dashboard
  • 可迁移原则：成本、上下文、模型状态要低干扰可见
• 取舍：导出
  • Pi 的倾向：自包含 HTML
  • 可迁移原则：分享不一定需要服务端
• 取舍：工具渲染
  • Pi 的倾向：TUI renderer 复用到 HTML
  • 可迁移原则：不要为每个界面写一套工具展示
• 取舍：Telemetry
  • Pi 的倾向：safe-by-default
  • 可迁移原则：默认不记录敏感内容

如果你在读 OpenClaw

如果你在读 OpenClaw，这一篇对应 trajectory、session export、debug evidence 和运行过程复盘。OpenClaw 的价值不只是把消息发出去，还要让一次 agent 行动能被回看：它为什么这么做，哪一步失败，哪些内容应该脱敏。

源码里真正能看到的可观测出口

Pi 的可观测性不是一个单独 dashboard，而是分布在多个出口：AgentSession 事件流、print JSON 输出、RPC 事件、TUI debug log、启动 timing、扩展 diagnostics、HTML export、session share。它们面对不同用户，但源头都是运行过程中的结构化事件。

Interactive 模式用事件更新界面；print JSON 把事件逐行输出，方便脚本记录；RPC 把事件作为协议消息发给宿主；HTML export 则把 session 变成可以阅读和分享的文档。

这说明 Pi 的 observability 不是事后补日志，而是从 agent 运行时就把过程事件设计成一等对象。

分享为什么要有安全边界

Agent 的运行轨迹很有价值，因为它能解释为什么成功或失败。但它也很敏感：里面可能有 prompt、文件内容、路径、命令输出、客户数据或内部策略。

Pi 的分享流程更像“把当前 session 导出成文档，再交给外部存储和 viewer 展示”。它让过程可传播，但也提醒我们：分享不是天然安全。产品要明确告诉用户分享了什么、存到哪里、是否可以取消、失败时如何恢复。

这篇文章要强调的是：Agent 的最终答案只是结果，运行轨迹才是调试、信任和改进的证据链。

阅读时可以用的三问

第一，出了问题后能不能复盘。只有最终答案，无法解释 agent 为什么失败；只有原始日志，又难以阅读。

第二，哪些信息应该本地保留，哪些可以外部分享。Agent trace 常常包含敏感上下文，默认策略必须保守。

第三，observability 是否能反过来改进产品。好的轨迹记录能帮助你发现工具失败、上下文压缩失败、模型选择错误和 UI 误导。

如果只记住一句话

没有过程记录，agent 的成功和失败都很难学习。

小结

Pi 的 Observability and Sharing 机制把 agent 的中间过程当成一等产物。一个可学习、可调试、可协作的 coding agent，不应该只留下最终回答；它应该留下结构化、可恢复、可审阅、默认安全的运行记录。