pi-web-token-usage

PI WEB 上的 Token 用量分析插件。在侧边面板里展示尽可能详细的 token 明细——输入 / 输出 / 缓存读 / 缓存写 / 推理 token、分项成本、缓存命中率与节省、上下文占用、按模型拆分、最贵轮次，并提供实时动态图表（堆叠柱状、累计成本曲线、构成环形图、实时增长 sparkline）。

⚠️ 说明：PI WEB 官方插件 API（apiVersion 2）不暴露任何 token / 成本数据。本插件通过浏览器与 pi-web 同源（same-origin）的优势，直接读取 pi-web 内部的 REST / WebSocket 端点（api/machines/.../sessions/.../status、/messages、/events）来获取数据。这些端点是根据 @jmfederico/pi-web 源码逆向得到的，不属于公开插件契约，未来 pi-web 升级可能会变动。仅适用于本地运行的 pi-web（sessiond），且插件以同源页面身份访问，不会把数据发往任何外部服务器。

---

功能

• 明细面板（Tokens 工作区面板）
  • 顶部 KPI：总 token、总成本、$/1K token、缓存命中率、上下文占用（已用 / 上限 / 百分比）
  • 分项表格：Cache read / Input / Cache write / Output / Reasoning 各自的 token 数、占比、成本
  • 缓存收益：估算的缓存节省金额（含「无缓存时」对比成本）
  • 按模型拆分（含 Tools/summaries 这类工具 / 摘要用量桶）
  • 最贵轮次排行（按单轮成本降序）
  • 实时图表：
    • 逐轮堆叠柱状图（cacheRead / input / cacheWrite / output 四色，hover 看明细，patch 动画）
    • 累计成本面积曲线
    • 构成环形图
    • 实时增长 sparkline（随 WebSocket 推送平滑延伸）
• 紧凑标签：在工作区标签栏显示当前会话 xxx tok · $y.yy，并带「上下文已用 N%」提示，不额外拉取 transcript（省钱）。
• 动作面板命令（命令面板输入 Token Usage）：
  • Open Token Usage — 打开面板
  • Copy Token Usage Report — 复制 Markdown 汇总到剪贴板
  • Copy Token Usage JSON — 复制逐轮原始 JSON
  • Refresh Token Usage — 立即重新拉取

---

安装

推荐（发布版）：在 PI WEB 的 Settings → Pi packages 填入 github:samecorner/pi-web-token-usage，或命令行 pi install github:samecorner/pi-web-token-usage。

也可以整目录手动放到插件根下（插件 id 必须为 token-usage，已在 package.json 中声明）：

~/.pi-web/plugins/token-usage/

其中 ~ 即用户主目录：

• Windows：C:\Users\<你的用户名>\.pi-web\plugins\token-usage
• macOS / Linux：~/.pi-web/plugins/token-usage

方式 A：复制文件夹（稳定，推荐首次安装）

把本目录整个复制过去：

# Windows (PowerShell)
$src = "C:\Users\yangj\WorkBuddy\2026-08-13-10-48-04\pi-web-token-usage"
$dst = "$env:USERPROFILE\.pi-web\plugins\token-usage"
New-Item -ItemType Directory -Force -Path $dst | Out-Null
Copy-Item -Recurse -Force "$src\*" $dst

# macOS / Linux
cp -R ./pi-web-token-usage ~/.pi-web/plugins/token-usage

方式 B：软链接（开发期热改，Windows 需开发者模式或管理员）

# Windows (PowerShell, 需开发者模式或管理员权限)
New-Item -ItemType SymbolicLink -Force `
  -Path "$env:USERPROFILE\.pi-web\plugins\token-usage" `
  -Target "C:\Users\yangj\WorkBuddy\2026-08-13-10-48-04\pi-web-token-usage"

# macOS / Linux
ln -s "$(pwd)/pi-web-token-usage" ~/.pi-web/plugins/token-usage

启用并验证

1. 确认 pi-web（sessiond）正在运行。
2. 重启 sessiond 或在插件目录变动后刷新页面，让宿主重新读取 manifest。
3. 验证插件 manifest 已被宿主托管（端口以你本机实际为准，常见为 8504）：

curl http://127.0.0.1:8504/pi-web-plugins/manifest.json

返回里应包含 "id":"token-usage" 及 browserRoot / module。

4. 打开 PI WEB 网页，侧边栏应出现 Tokens 面板；命令面板输入 Token Usage 应出现 4 个动作。

---

调试

• 面板空白 / 看不到数据：先确认当前已选中一个会话（动作在「无会话」时会置灰）。打开浏览器 DevTools 控制台：
  • 搜索 token-usage 相关日志（数据层 usage-data.js 在加载 / 连接失败时会 console.warn）。
  • 手动确认端点可达：fetch("/api/machines/local/sessions/<sessionId>/status?cwd=<cwd>") 是否返回含 tokens / cost / contextUsage 的对象。
• 端口 / 路径不对：插件通过 <script> 自身 URL 中的 /pi-web-plugins/ 片段反推 appBase（即 http://<host>:<port>/），无需手工配置端口。
• 图表不渲染：图表为手写 SVG 注入 Shadow DOM。检查是否被宿主 CSP 拦截（一般同源不受影响）。
• 样式错位：所有颜色走 --pi-* CSS 变量；若该 pi-web 版本未定义某个变量，插件有 --tu-* 兜底色。
• WebSocket 不推送：数据层会自动退化为「防抖轮询重取」；如面板长时间不动，可点动作 Refresh Token Usage 或重开面板。

---

文件结构

pi-web-token-usage/
├── package.json          # 插件清单（piWeb.plugins[].id = "token-usage"）
├── pi-web-plugin.js      # 入口：activate() 返回 actions / workspaceLabels / workspacePanels
├── usage-data.js         # 数据层：读取 session 引用、聚合、UsageStore（REST + WS 实时 + 防竞态）
├── usage-format.js       # 格式化：token / 成本 / 百分比 / 时长 / 时钟（对齐 pi 的 format.ts）
├── usage-charts.js       # 手写 SVG 图表：堆叠柱 / 成本曲线 / 环形 / sparkline（patch 动画）
├── usage-panel.js        # <pi-web-token-usage-panel> 自定义元素 + Shadow DOM + 渲染 / tooltip
├── usage-report.js       # Markdown / JSON 报告生成 + 剪贴板复制
└── usage-styles.js       # 全部 --pi-* 主题变量 + tu-* 语义色 + 布局

---

数据来源与关键接口

用途	端点
会话状态（token / cost / 上下文）	GET {base}api/machines/{machineId}/sessions/{sessionId}/status?cwd=...
逐轮消息（含每轮 Usage）	GET {base}api/machines/{machineId}/sessions/{sessionId}/messages?cwd=...
实时事件推送	WS {base}api/machines/{machineId}/sessions/{sessionId}/events?cwd=...

• state.selectedSession 运行时是 SessionInfo（含 id / cwd），插件再用 id + cwd 换取完整 SessionStatus。
• 每条 assistant 消息自带 pi 的 Usage（input / output / cacheRead / cacheWrite / reasoning / totalTokens / cost），因此可画真实历史堆叠图。
• 缓存节省无官方单价表：用各消息自报的 cost / tokens 反推有效单价估算（computeSavings）。

---

已知限制

• 依赖 pi-web 内部（未公开）端点，升级可能失效。
• 仅适用于本地 / 同源的 pi-web 部署，无法跨域取数。
• 未读 / 已折叠的工具消息若不含 Usage，不计入明细（归入 Tools/summaries 的仅限带用量的那部分）。
• 单位换算采用 pi-web 通用计价量级；若你的账号计费口径不同，面板数字为「同源端点返回值」，以 pi-web 账单为准。

License

MIT