执行轨迹查看器 npxcnency-ux/pi-trace-extension

实验性功能：为 pi-agent 打造的 Langfuse 风格本地追踪查看器

pi-trace-extension 把 pi-agent 会话从对话视图重组为执行视图。 pi 自带的 session.jsonl 面向消息——可以回放，但结构扁平。这个扩展订阅 pi 的生命周期事件，把它们重建为一棵树，呈现智能体实际推进的过程——每次 LLM 调用、每次工具执行、每个子代理，连同耗时、token 开销和结果——边发生边写入磁盘。

每个会话产出两个产物：

- events.jsonl —— 机器可读、只追加的事件流
- trace.html —— 自包含的单文件 Langfuse 风格查看器（零外部资源，任何浏览器都能打开）

所有数据都留在你的机器上。

Pi Trace Dashboard

| pi 自带的 session.jsonl | pi-trace-extension |
| 对话视图（消息按顺序排列） | 执行视图（步骤 + 工具 + 子代理组成一棵树） |
| 一个产物（session.jsonl） | 两个产物：events.jsonl（给机器）+ trace.html（给人看） |
| 每条消息的元数据 | 每个步骤的延迟、token、开销、停止原因、完整 LLM 载荷 |
| 工具调用内联为消息 | 工具与 llm-generation 平级，同处一个 turn 内（Langfuse 风格） |
| 没有状态语义 | 区分 aborted / error / ok，并用颜色标注 |
| 子代理运行被折叠进工具结果 | 子代理拥有自己的嵌套追踪（turns / steps / tools），父级还有可点击跳转的链接 |

中文文档见 README.zh.md

安装

from npm (recommended)
pi install npm:pi-trace-extension

or from GitHub
pi install git:github.com/npxcnency-ux/pi-trace-extension

or try without installing (current pi run only)
pi -e npm:pi-trace-extension

安装路径不用你选。pi 会把它放到 ~/.pi/agent/npm/pi-trace-extension/，每次启动自动加载。可与任何其他 pi 扩展共存。

用法

照常使用 pi —— 事件会在后台流式写入磁盘。

~/.pi/agent/traces/<session-id>/events.jsonl

随时渲染 HTML 报告：

/trace

输出：

| 文件 | 说明 |
| ~/.pi/agent/traces/<session-id>/trace.html | 单文件查看器，用默认浏览器打开 |
| ~/.pi/agent/traces/<session-id>/events.jsonl | 机器可读的事件流（只追加） |
| ~/.pi/agent/traces/<session-id>/subagents/<child-id>/ | 每个子代理一个嵌套目录，布局同样是 events.jsonl + trace.html，从父级的子代理节点链接过去 |

session_shutdown 时也会自动生成 trace.html（不打开浏览器），所以正常关闭 pi 后，总能留下一份可查看的报告。

手动重新渲染任意历史会话：

python3 ~/.pi/agent/npm/pi-trace-extension/extensions/trace/trace_to_html.py [session-name]
Omit the argument to pick the most recent session

跨会话仪表盘 —— 磁盘上所有会话的顶层索引。

在 pi 会话里运行：

/trace all

或者从 shell 运行：

python3 ~/.pi/agent/npm/pi-trace-extension/extensions/trace/trace_to_html.py --dashboard
Writes ~/.pi/agent/traces/index.html

仪表盘展示：本周 + 全时段 KPI 卡片（会话数 / 成本 / 时长）；一张可排序、可搜索的表格（时间、会话 id、首条提示词、项目、规模、token、成本、时长），每行左侧带颜色条（绿色 = 正常，黄色 = 中止，红色 = 有错误）；还有项目名标签，方便快速筛选。点击会话 id → 跳到该会话的 trace.html。

流水线

pi runtime
│ emits lifecycle events:
│ session_start / interaction_start / turn_start
│ before_provider_request (full payload: model + messages + tools schema)
│ message_end
│ tool_execution_start / tool_execution_end
▼
extensions/trace/index.ts
│ capture, sanitize (mask secret-like keys), truncate (8 KB/string)
└─ writes JSONL → ~/.pi/agent/traces/<session-id>/events.jsonl
│
/trace command (or session_shutdown) │
────────────────────────────────────────┘
│ spawn python3 extensions/trace/trace_to_html.py
│ reads events.jsonl
│ rebuilds the tree:
│ session → interaction → turn → llm-generation + tool
│ sub-agent results carry a child-trace link;
│ a sub-agent's own events.jsonl is rendered into its own trace.html
│ bundles viewer/assets.json (css + js + html) into one file
└─ writes trace.html → opens in browser

数据模型刻意做得和 Langfuse 相似，这样以后升级到托管后端时，思路可以直接沿用。

trace.html 里能看到什么

一个三栏的 Langfuse 风格查看器。单个 HTML 文件，不用 CDN，不从网络加载字体，没有分析脚本。

| 栏位 | 内容 |
| 顶栏 | 会话 id（点击复制）、计数（交互 / 生成 / 工具调用）、总成本与总时长 |
| 左侧树 | 层级结构：session → interaction → turn → llm-generation + tool（同一 turn 内为兄弟节点）。点击任意节点即可查看。搜索框按名称 / 工具 / 提示词过滤。 |
| 右侧详情 | 针对选中的节点：徽章（延迟 / token 输入→输出 / 成本 / 模型 / 停止原因），然后是各个分区 —— Input（完整 LLM 载荷，可折叠的 JSON 树，带行号）、Output、Tool Calls、Error / Aborted（按颜色区分）、Metadata。 |
| 左下角 DAG 统计 | 按工具统计次数，格式为 ok/total · N ⏹（bash 76/80 · 3 ⏹）。出错时边框变红，中止时变黄。 |

具体功能：

- aborted 与 error 与 ok —— 区分用户取消（⏹ 黄色）和真正的错误（❌ 红色）。429 重试最终成功的，正确归类为 ok。
- 「Only errors」过滤器 —— 树形工具栏里的开关，只保留 error / aborted 节点及其祖先路径，长会话因此收缩到只剩出错的分支。可与文本搜索框组合使用（AND）。无错误的会话中该开关禁用。
- 子代理有自己的 trace —— 智能体派生子代理时（single / parallel / chain），子代理在 subagents/<child-id>/ 下写入自己的 events.jsonl，并生成自己渲染的 trace.html。父级的 sub-agent-result 节点内联显示子代理的 turns / steps / tools（从消息重建），并提供「Open child trace」按钮，跳转到子代理的完整报告。并行子代理在可用时按 sessionId 匹配到磁盘上的 trace。
- 自动重试检测 —— 当某一轮以相同的 turnIndex 重新进入时（例如框架在 429 后重试），第二次出现会标记为 turn N (retry #1)，而不是把两次合并成一个节点。
- 完整 LLM 输入载荷 —— model、每个 messages[] 条目（包括 reasoning_content、tool_calls、tool_result）、注册的 tools[] schema，以及请求级参数（max_tokens、temperature 等）。长字符串截断到 8 KB；截断后的长度会显示出来。
- 跨进程韧性 —— 如果你重新加载 pi 或 fork 会话，重复的 stepIndex / turnIndex 值会通过内部 epoch 计数器正确区分。

什么时候用它

适合：

- 常规 pi-agent 用户，想看清 LLM 实际看到了什么、实际做了什么 —— 一步步看
- 调试提示词、工具定义、子代理编排，或长会话的上下文压缩
- trace 数据必须留在本地的环境（个人机器，不允许用 SaaS）
- 想查看每轮 token 用量 / 成本 / 缓存命中率，又不想为托管仪表盘付费

不适合：

- 带告警、多租户聚合或长期留存的生产监控 —— 请选 Langfuse / LangSmith / Phoenix 自托管
- 团队共享仪表盘 —— 这是单用户、单机
- 不在 pi-agent 上运行的流水线追踪 —— 这里只消费 pi 的事件流

它不做什么

分三类 —— 分开讲，因为它们对应不同的应对方式。

设计使然（明确的选择，不是缺陷）
- 没有网络代码。 不做匿名使用统计，不上报崩溃报告，也没有「为改进产品」的遥测。想要这些功能，请自行 fork。
- 不自动清洗提示词。 写入时只做键名脱敏（password、token、secret、api_key、authorization、bearer → REDACTED）。你的原始提示词、工具参数、工具输出、模型响应都按原样存储。
- 没有团队共享界面。 这是单用户、单机工具。如果你觉得不够用，自托管 Langfuse 是自然的下一步——数据模型刻意做得相似。
- 没有内置保留/轮转机制。 events.jsonl 每个会话单调增长。长会话可能达到几十 MB；渲染出的 trace.html 超过 5 MB 后可能变慢。

结构性问题（不是靠更好的代码能解决的）

- /trace 需要 Python 3.8+。 渲染器是 Python 标准库脚本，这是有意为之——不需要 Node 侧重构建，不需要打包器。如果你用不了 Python，这个工具不适合你。
- 绑定 pi 的事件流。 换一个智能体框架，就得自己写采集层。

隐私上限

- 追踪数据默认就是敏感的。 提示词、工具参数、模型输出都可能包含 PII / 密钥，而它们不一定匹配脱敏正则。如果你打算分享 trace.html，先手动审一遍。

与托管方案的对比

这个扩展覆盖的范围比成熟产品小。说实话：

| | pi-trace-extension | Langfuse Cloud | LangSmith | Arize Phoenix |
| 托管方式 | 本地文件 | SaaS 或自托管 | 仅 SaaS | SaaS 或本地 notebook |
| 数据离开你的机器 | 否 | 是 | 是 | 可配置 |
| 需要账号 | 否 | 是 | 是 | 可选（云端） |
| 费用 | 免费，MIT | 免费额度 + 付费 | 付费 | 免费开源 |
| 多用户仪表盘 | 否 | 是 | 是 | 是 |
| 告警 / SLO | 否 | 是（付费） | 是 | 是 |
| 跨会话聚合 | 本地仪表盘（--dashboard） | 是 | 是 | 是 |
| pi-agent 原生 | 是 | 可做适配 | 否 | 可做适配 |
| 出第一张图的时间 | 秒级 | 分钟级（注册） | 分钟级 | 分钟级 |

它们不是竞品——解决的是不同问题。

环境要求

- pi-agent ≥ 0.79.x
- Node ≥ 18（扩展运行时）
- Python ≥ 3.8（渲染器；需要时用 PI_TRACE_PYTHON=/path/to/python3 覆盖）

没有其他依赖。渲染器只用 Python 标准库；查看器不用任何 JS 框架。

文件结构

pi-trace-extension/
├── README.md / README.zh.md / LICENSE / package.json
├── examples/
│ └── dashboard.png
└── extensions/
└── trace/
├── index.ts # pi extension entry (event capture, /trace command)
├── trace_to_html.py # renderer (events.jsonl → trace.html)
└── viewer/
├── assets.json # bundled css + js + html (runtime-loaded, committed)
├── viewer.css # source (single-session viewer)
├── viewer.html
├── viewer.js
├── dashboard.css # source (cross-session dashboard)
├── dashboard.html
├── dashboard.js
└── build.py # rebuild assets.json after editing the sources

常见问题与排查

启动时出现两行 [pi-trace] extension loaded。 说明还有另一个版本的扩展也被加载了（比如你之前把它复制到了 ~/.pi/agent/extensions/trace/）。把旧的那份移出 ~/.pi/agent/extensions/ —— pi 会自动加载该目录下所有 /index.ts。

/trace 报 python3: command not found。 要么装 Python 3.8+，要么把 PI_TRACE_PYTHON 指向你的解释器：bash
export PI_TRACE_PYTHON=/opt/homebrew/bin/python3

浏览器没有自动打开。 通知里会显示路径，手动打开即可。底层依次尝试的命令：open（macOS）、xdg-open（Linux）、start（Windows）。

events.jsonl 太大 / trace.html 很慢。 长字符串每个字段会截断到 8 KB，但跨多天的深度会话仍可能撑大。目前还没有自动轮转 —— 需要的话就开新会话。

想分享 trace，但里面有敏感内容。 除了键名正则之外没有内置的清洗器。打开 trace.html，搜索敏感子串，手动改完再分享。命令行清洗器已列入路线图。

开发

动 UI 代码之前，先读 docs/design-language.md —— 里面记录了视觉语法、信息密度的取舍原则，以及明确「不做」的边界。评审 PR 时可以引用具体的 §N.M 小节。
bash
git clone https://github.com/npxcnency-ux/pi-trace-extension
cd pi-trace-extension
pi -e . # try locally

改查看器的样式与行为：

- extensions/trace/viewer/viewer.css —— 样式
- extensions/trace/viewer/viewer.js —— 查看器逻辑
- extensions/trace/viewer/viewer.html —— HTML 外壳

然后重新构建打包的 JSON（终端用户加载的就是它）： bash
python3 extensions/trace/viewer/build.py

改数据管道：extensions/trace/index.ts（事件采集）或 extensions/trace/trace_to_html.py（事件 → 树 → HTML）。两者都方便重载：pi 的 /reload 会重新运行扩展；python3 trace_to_html.py 是一次性执行。

PR 门槛：

- 新事件类型必须在现有渲染器上优雅降级（只做加法）
- 不引入新的运行时依赖（Python 标准库 + Node 内置模块）
- 隐私方面的倒退一律拒绝 —— 任何新的网络调用都必须默认关闭，并且有文档说明

路线图

- [ ] 命令行清洗器：python3 trace_to_html.py <session> --redact-prompts
- [x] 多会话索引页（~/.pi/agent/traces/index.html）—— v0.1.7
- [ ] 可选的 OTLP 导出器（通过环境变量开启），用于转发到自建的 Langfuse / Phoenix
- [ ] events.jsonl 超过 N MB 时自动轮转

许可证

MIT

致谢查看器的三栏布局、配色方案和节点详情结构，大量借鉴了 Langfuse 的 trace explorer。本项目与 Langfuse 没有隶属关系——他们是一款出色的产品，当你觉得本项目不够用时，他们就是顺理成章的下一步。

pi-agent 由 pi.dev 团队打造。