@cluski/pi-session-stats

本地 CLI：扫描 ~/.pi/agent/sessions/ 下的 session 日志（jsonl），启动一个本地 Web 看板，分析 Pi 的 token 用量。subagent / trellis_subagent 派发的子代理用量会自动从主会话的工具结果中提取，无需额外目录。

功能

• 时间范围：近一天（按小时分桶）、近一周（按天）、近一个月（按天）
• 汇总卡片：总 tokens、输入 / 输出、缓存读取 / 写入、缓存命中率、费用、请求数、会话数
• 趋势图：堆叠柱状图（输入 / 输出 / 缓存读取 / 缓存写入），悬停查看明细
• 模型排行：按 provider/model 统计 token 总量、缓存命中率、费用、请求数、会话数，支持点击表头排序
• 文件夹排行：按工作目录（cwd）统计 token 总量、缓存命中率、费用、请求数、会话数，支持点击表头排序
• 增量扫描：按文件 mtime/size 缓存解析结果，"重新扫描" 只读取变更过的文件
• 子代理自动纳入：主会话中 subagent / trellis_subagent 工具结果（toolResult）携带的子代理 token 用量会被一并提取，与主会话用量统一汇总

使用

CLI

# 在本 monorepo 中
node packages/pi-session-stats/src/cli.ts

# 或全局安装后
npm install -g @cluski/pi-session-stats
pi-session-stats

启动后访问终端中打印的地址（默认 http://127.0.0.1:4789）。

作为库引入

// ESM
import {
  parseSessionFile,
  SessionStore,
  aggregate,
  isRangeKey,
  RANGES,
  createStatsServer,
} from "@cluski/pi-session-stats";

// CJS
const {
  parseSessionFile,
  SessionStore,
  aggregate,
  isRangeKey,
  createStatsServer,
} = require("@cluski/pi-session-stats");

主要导出：

| 导出 | 说明 | | --- | --- | | parseSessionFile(content, fallbackSessionId) | 解析单个 session jsonl 文本，返回 UsageRecord[] | | SessionStore | 增量扫描器类，缓存文件 mtime/size，scan() 返回 ScanResult | | aggregate(records, range, now?) | 聚合用量记录，返回 Overview（含 summary、buckets、models、folders） | | isRangeKey(value) | 类型守卫，判断是否为 "day" \| "week" \| "month" | | RANGES | 三个范围对应的 bucket 配置常量 | | createStatsServer(store) | 创建 HTTP 服务（node:http），返回 { server, refresh } |

选项

| 选项 | 说明 | 默认值 | | --- | --- | --- | | -p, --port | 监听端口 | 4789 | | --host | 监听地址 | 127.0.0.1 | | -d, --dir | session 目录 | ~/.pi/agent/sessions | | --open | 启动后自动打开浏览器（支持 WSL 的 wslview） | 关 | | -h, --help | 帮助 | - |

统计口径

• 仅统计 session jsonl 中 role === "assistant" 且带 usage 的消息，逐请求累加，即账单口径（input 为每次请求的完整输入上下文，跨请求会重复计算上下文，属正常现象）。
• 子代理用量取自主会话中的工具结果：subagent 工具读取 details.results[].usage（无 results 时回退 details.totalChildUsage），trellis_subagent 工具读取 details.runs[].usage；两者均为子代理汇报的聚合值，按一次运行记为一条用量记录。
• subagent 运行记录的 sessionId 形如 runId_agent_childIndex（例如 28aac0e3_researcher_0），trellis 运行形如 trellis_<agent>_<runId>；cwd 沿用主会话，因此用量自然汇入对应项目文件夹。provider/model 从子代理汇报的模型字符串解析（剥掉 :thinking 后缀）。
• subagent 工具的子会话 session 文件嵌套存放在 <会话名>/<runId>/run-N/session.jsonl，与主会话格式相同；为避免与工具结果重复计数，扫描时会跳过这些与 <会话名>.jsonl 同名的嵌套目录。
• totalTokens 缺失时按 input + output + cacheRead + cacheWrite 兜底。
• 时间桶按本地时区对齐（近一天按整点、近一周/近一个月按自然日）。
• 费用直接取日志中的 usage.cost.total（美元）；子代理运行记录取工具结果中汇报的 usage.cost 数值。

API

• GET /api/overview?range=day|week|month — 汇总、时间桶、模型排行、文件夹排行
• POST /api/refresh — 增量重扫 session 目录

要求

Node.js >= 22.19。发布前需执行 npm run build（tsup 打包为 CJS + ESM 双格式，含 .d.ts 类型声明）。