npxcnency-ux/pi-trace-extension

实验性：pi-agent 的 Langfuse 风格本地 trace 查看器

License: MIT
pi-package
本地优先
无遥测
GitHub stars

* * *

pi-trace-extension 把 pi-agent 的 session 从"对话视角"重组成"执行视角"。 pi 自带的 session.jsonl 是按消息组织的——可回放但扁平。本扩展订阅 pi 的生命周期事件，按 agent 实际怎么一步步推进 重建成一棵树——每次 LLM 调用、每次工具执行、每个子 agent，连同耗时、token 成本、状态——边发生边写到磁盘。

每个 session 输出两份产物：

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

数据全程留在本机。

Pi Trace Dashboard

| pi 自带的 session.jsonl | pi-trace-extension |
| --- | --- |
| 对话视角（按消息顺序） | 执行视角（step + 工具 + 子 agent 组成的树） |
| 一份产物 | 两份产物：events.jsonl（机器）+ trace.html（人） |
| 每条消息的元信息 | 每个 step 的耗时、token、成本、stop reason、完整 LLM payload |
| 工具调用作为 inline 消息 | 工具作为 llm-generation 的兄弟节点挂在 turn 下（Langfuse 风格） |
| 无状态语义 | aborted / error / ok 三态区分并配色 |
| 子 agent 折叠成一个工具结果 | 子 agent 有自己的嵌套 trace（turn / step / tool），父 trace 一键跳转 |

English docs: README.md

* * *

安装

从 npm 装（推荐）
pi install npm:pi-trace-extension

或从 GitHub 装
pi install git:github.com/npxcnency-ux/pi-trace-extension

或不入库试用一次（仅本次 pi 进程）
pi -e npm:pi-trace-extension

不需要你指定安装目录。pi 会自动放到 ~/.pi/agent/npm/pi-trace-extension/，每次启动自动加载。和任何其他 pi 扩展可以共存。

* * *

用法

正常使用 pi 即可——事件会在后台持续写入磁盘：

~/.pi/agent/traces//events.jsonl

随时渲染报告：

/trace

产物：

| 文件 | 说明 |
| --- | --- |
| ~/.pi/agent/traces//trace.html | 单文件查看器，浏览器自动打开 |
| ~/.pi/agent/traces//events.jsonl | 机器可读的事件流（追加写入） |
| ~/.pi/agent/traces//subagents// | 子 agent 独立目录，结构同上，父 trace 节点上有跳转按钮 |

session_shutdown 时也会自动跑一次（不开浏览器），所以正常退出 pi 后随时可以回看。

手动渲染任意历史 session：

python3 ~/.pi/agent/npm/pi-trace-extension/extensions/trace/trace_to_html.py [session-name]
不传参数则渲染最新一个

跨会话 dashboard —— 磁盘上所有 session 的顶层索引。

在 pi 会话里输入：

/trace all

或从 shell：

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

Dashboard 包含：本周 + 全局的 KPI 卡片（sessions / cost / duration）；可搜索/可排序的表格（时间、session id、首个提问、项目、规模、tokens、成本、时长），每行左侧一根状态色条（绿 = ok、黄 = aborted、红 = 有错误）；顶部有项目名 chip 用于快速筛选。点击 session id → 跳到该会话的 trace.html。

* * *

流水线

pi 运行时
│  发出生命周期事件：
│    session_start / interaction_start / turn_start
│    before_provider_request  （完整 payload：model + messages + tools schema）
│    message_end
│    tool_execution_start / tool_execution_end
▼
extensions/trace/index.ts
│  捕获、脱敏（关键字段名打码）、截断（单字符串 8 KB）
└─ JSONL 落盘 → ~/.pi/agent/traces//events.jsonl
│
/trace 命令（或 session_shutdown）       │
────────────────────────────────────────┘
│  spawn python3 extensions/trace/trace_to_html.py
│    读 events.jsonl
│    重建树：
│      session → interaction → turn → llm-generation + tool
│      子 agent 的 result 节点带跳转链接；
│      子 agent 自己的 events.jsonl 也独立渲染出一份 trace.html
│    把 viewer/assets.json（css + js + html）注入到一个文件
└─ 写出 trace.html → 浏览器打开

数据模型刻意做得跟 Langfuse 相近，方便日后升级到托管后端时心智迁移。

* * *

trace.html 里能看到什么

仿 Langfuse 的三栏布局。单 HTML 文件，无 CDN，无外部字体，无 analytics。

| 区域 | 内容 |
| --- | --- |
| 顶栏 | session ID（点击复制）、interactions / generations / tool calls 计数、总成本与总耗时 |
| 左栏树 | 层级：session → interaction → turn → llm-generation + tool（一个 turn 内 step 和 tool 同级）。点任意节点查看详情。搜索框按节点名 / 工具名 / prompt 过滤。 |
| 右栏详情 | 选中节点的：徽章（耗时 / token in→out / 成本 / 模型 / stop reason），分节内容 — Input（完整 LLM 请求 payload，带行号 JSON 折叠树）、Output、Tool Calls、Error/Aborted（区分配色）、Metadata。 |
| 左下 DAG 统计 | 按工具/节点类型分组：bash 76/80 · 3 ⏹（成功/总数 · 中断数）。有错误时红色边框，有中断时黄色边框。 |

具体能力：

- aborted / error / ok 三态 — 用户取消（⏹ 黄）vs 真错误（❌ 红）vs 正常。pi 撞 429 自动 retry 后最终成功的，整体仍计为 ok，不会被中间失败误判。
- 「只看错误」过滤 — 树工具栏一个 toggle，勾选后只保留 error / aborted 节点及其从根到叶的完整祖先路径，长 session 一次点击聚焦失败分支。与文本搜索框叠加（AND）。无错误 session 里按钮禁用。
- 子 agent 有独立 trace — 派生子 agent（single / parallel / chain）时，子进程把自己的 events.jsonl 写到 subagents//，并独立生成一份 trace.html。父 trace 的子 agent 节点会内联展示子 agent 的 turn / step / tool（从 messages 重建），并提供「Open child trace」跳转按钮。parallel 模式下尽量按 sessionId 匹配父子关系。
- Retry 检测 — 同一个 turnIndex 在一个 interaction 内出现第二次（比如 429 后框架重试），节点名会标记成 turn N (retry #1)，不会被折叠成同一个 turn。
- 完整 LLM input payload — model、所有 messages[] 条目（含 reasoning_content、tool_calls、tool_result）、注册过的 tools[] schema、请求级参数（max_tokens、temperature 等）。超长字符串截断到 8 KB，截断长度会显示出来。
- 跨进程容错 — 重启 pi 或 fork session 时，重复的 stepIndex / turnIndex 通过内部 epoch 计数器正确区分，不会渲染出"两个 turn 0"。

* * *

适合谁用

适合：

- 经常用 pi-agent，想看清 LLM 实际收到了什么、做了什么——一步一步还原
- 在调 prompt、工具定义、子 agent 协作、长会话上下文压缩
- 工作环境要求 trace 数据不出本机（个人电脑、不能上 SaaS 的合规场景）
- 不想为了看每轮 token 用量 / 成本 / 缓存命中率付钱给托管方

不适合：

- 想做生产监控：告警、多租户聚合、长期保留 — 选 Langfuse / LangSmith / Phoenix 自建版
- 想做团队共享 dashboard — 本扩展是单人单机用的
- 想 trace 不跑在 pi-agent 上的链路 — 本扩展只消费 pi 的事件流

* * *

不做的事情

分三类——分别意味着不同的应对。

故意不做（明确选择，不是欠缺）

- 没有网络代码。 不上传匿名使用数据，不上传崩溃报告，没有"为了改进产品"的 telemetry。需要这些的话请 fork。
- 不自动脱敏 prompt。 写盘前只对字段名做正则脱敏（password / token / secret / api_key / authorization / bearer → REDACTED）。你的原始 prompt、工具参数、工具输出、模型回复都是原文存储的。
- 没有团队共享 UI。 单人单机。需要团队共享时，自建 Langfuse 是天然下一步——本扩展的数据模型刻意跟 Langfuse 对齐了。
- 没有内置归档/轮转。 单 session 的 events.jsonl 只增不减。深度长会话可能涨到几十 MB；生成的 trace.html 超过 5 MB 时浏览器打开会慢。

结构性的（写代码也修不了）

- /trace 需要 Python 3.8+。 渲染器是 Python 标准库脚本——故意的：没有 Node 端构建步骤，没有 bundler。如果你的环境里没法装 Python，这个扩展不适合你。
- 绑定 pi 事件流。 别的 agent 框架要用，得自己写一份采集层。

隐私上限

- trace 数据默认就是敏感的。 prompt、工具参数、模型输出都可能含没匹配上正则的 PII / 密钥。要分享 trace.html 之前，先人工过一遍。

* * *

对比托管方案

本扩展刻意覆盖比成熟厂商小得多的范围。如实对比：

| | pi-trace-extension | Langfuse Cloud | LangSmith | Arize Phoenix |
| --- | --- | --- | --- | --- |
| 部署方式 | 本地文件 | SaaS 或自建 | SaaS only | SaaS 或本地 notebook |
| 数据是否离开本机 | 否 | 是 | 是 | 可配 |
| 需要账号 | 否 | 是 | 是 | 云端版需要 |
| 成本 | 免费、MIT | 免费档 + 付费 | 付费 | 免费 OSS |
| 多人 dashboard | 否 | 是 | 是 | 是 |
| 告警 / SLO | 否 | 是（付费） | 是 | 是 |
| 跨 session 聚合 | 本地 dashboard（--dashboard） | 是 | 是 | 是 |
| pi-agent 原生支持 | 是 | 可适配 | 否 | 可适配 |
| 看到第一张图的时间 | 几秒 | 几分钟（注册） | 几分钟 | 几分钟 |

它们不是竞争关系——解决的是不同问题。

* * *

运行依赖

- pi-agent ≥ 0.79.x
- Node ≥ 18（扩展运行时）
- Python ≥ 3.8（渲染器；如 python3 不在标准路径，可 PI_TRACE_PYTHON=/path/to/python3 覆盖）

无其他依赖。渲染器只用 Python 标准库；viewer 不引任何 JS 框架。

* * *

文件结构

pi-trace-extension/
├── README.md / README.zh.md / LICENSE / package.json
├── examples/
│   └── dashboard.png
└── extensions/
└── trace/
├── index.ts            # pi 扩展入口（事件采集、/trace 命令）
├── trace_to_html.py    # 渲染器（events.jsonl → trace.html）
└── viewer/
├── assets.json     # 打包后的 css + js + html（运行时加载，仓库提交）
├── viewer.css      # 源（单会话查看器）
├── viewer.html
├── viewer.js
├── dashboard.css   # 源（跨会话 dashboard）
├── dashboard.html
├── dashboard.js
└── build.py        # 修改源后重新打包 assets.json

* * *

FAQ 与常见问题排查

启动时看到两条 [pi-trace] extension loaded。 另一份扩展也被加载了（比如之前手动拷贝过到 ~/.pi/agent/extensions/trace/）。把旧的从 ~/.pi/agent/extensions/ 移走——pi 会自动加载该目录下任何 /index.ts。

/trace 报 python3: command not found。 装 Python 3.8+，或用环境变量指向解释器：
export PI_TRACE_PYTHON=/opt/homebrew/bin/python3

浏览器没自动打开。 路径会显示在通知里，手动打开即可。底层用的命令：macOS open、Linux xdg-open、Windows start。

events.jsonl 太大 / trace.html 加载慢。 单字符串截断到 8 KB，但跨多天的深度 session 仍可能涨。目前还没自动归档——需要时新开一个 session。

想分享 trace 但里面有敏感内容。 内置脱敏只覆盖了"敏感字段名"。需要打开 trace.html，搜索敏感子串，手动改 HTML 后再分享。CLI 脱敏工具在路线图上。

* *

开发

改 UI 前先读 docs/design-language.md——里面沉淀了视觉语法、信息密度取舍、明确不做的方向。PR 评审可按 §N.M 引用具体条款。

git clone https://github.com/npxcnency-ux/pi-trace-extension
cd pi-trace-extension
pi -e .   # 本地试装

修改视图样式/行为：

- extensions/trace/viewer/viewer.css — 样式
- extensions/trace/viewer/viewer.js — 视图逻辑
- extensions/trace/viewer/viewer.html — HTML 外壳

然后重新打包（最终用户加载的是打包产物）：

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 门槛：

- 新事件类型对老 viewer 必须降级友好（只能加，不能改语义）
- 不引入新的运行时依赖（Python 标准库 + Node 内置）
- 隐私回退会被拒：任何新增网络调用必须默认关 + 文档明确说明

* * *

路线图

- [ ] CLI 脱敏工具：python3 trace_to_html.py  --redact-prompts
- [x] 多 session 索引页（~/.pi/agent/traces/index.html）—— v0.1.7
- [ ] 可选 OTLP exporter（opt-in 环境变量），转发到 Langfuse / Phoenix 自建
- [ ] events.jsonl 超过 N MB 自动归档

* * *

License

MIT

* * *

致谢

Viewer 的三栏布局、配色、节点详情结构大量借鉴 Langfuse 的 trace explorer。本项目与 Langfuse 无任何关联——它们是另一个值得付费的优秀产品，本扩展不够用了应该升过去。

pi-agent 由 pi.dev 团队开发。