@async23/pi-sessions-studio

Pi 的本地会话可观测与复盘工作台。它通过 /studio 从 Pi 当前会话进入浏览器，将 ~/.pi/agent/sessions 中的分支、工具调用、上下文、Token 与成本还原成可检索、可解释、可导出的工作记录。

Pi TUI ── /studio ──► Pi Package Extension
                           │ 懒启动 / 复用本地服务
                           ▼
                    browser ui (React + Vite + ECharts)
                           │  /api/*
                           ▼
                    backend (Node.js + Express)
                           │  只读扫描 / 增量解析
                           ▼
                    ~/.pi/agent/sessions/**/*.jsonl

功能

• 总览：会话/消息/工具调用/Token/成本 KPI，近 30 天活动趋势，工具 Top 10，项目排行，最近会话
• 会话浏览器：按项目/关键词过滤，按活动时间/成本/Token/时长等排序，无限加载
• 会话详情：
  • 完整对话流：用户 / 助手 / 思考过程（折叠）/ 工具调用与结果自动配对 / 手动 bash / 系统事件
  • 分支可视化：识别重试/回溯产生的树形分支，标出分支点，可切换任意分支路径
  • 上下文规模趋势图（观察 compaction 锯齿）、用户消息大纲导航、逐条原始 JSON
  • 导出 Markdown、fork 父会话跳转、搜索结果锚点定位
• 全局搜索：跨会话全文检索（对话/思考/工具参数与输出/压缩摘要），类型与项目过滤，高亮命中
• 统计洞察：每日 Token/成本、模型成本分布、周×小时活跃热力图、项目成本、模型缓存命中率、模型明细表
• 数据格式：内置 JSONL 格式说明文档，便于学习理解

作为 Pi Package 使用（推荐）

pi install npm:@async23/pi-sessions-studio

安装后重启 Pi 或执行 /reload，然后使用：

| 命令 | 说明 | | --- | --- | | /studio | 懒启动本地服务，并直接打开当前持久化会话与当前分支位置 | | /studio home | 打开 Studio 总览 | | /studio status | 查看当前 Session 数据目录对应的服务状态 | | /studio stop | 停止本地服务 |

Extension 只在用户执行 /studio 时启动服务；同一 Session 数据目录会复用同一个后台进程。服务绑定 127.0.0.1，运行状态和日志保存在 PI_CODING_AGENT_DIR（默认 ~/.pi/agent）下的 pi-sessions-studio/。

开发时也可从 monorepo 源码安装：

cd packages/pi-sessions-studio
npm install
npm run build
pi install "$(pwd)"

独立运行与开发

npm install

# 生产模式（单端口）
npm run build
npm start            # → http://127.0.0.1:5177

# 开发模式（前端热更新）
npm run dev          # 后端 :5177 + 前端 :5173（代理 /api）

配置

| 环境变量 | 默认值 | 说明 | | --- | --- | --- | | PI_SESSIONS_DIR | ~/.pi/agent/sessions | 独立运行时的会话数据目录 | | PI_CODING_AGENT_SESSION_DIR | <PI_CODING_AGENT_DIR>/sessions | 自定义 Pi Session 数据目录；未设置时 Extension 从当前项目目录定位全局 sessions 根目录 | | PI_CODING_AGENT_DIR | ~/.pi/agent | Pi 配置目录，同时作为 Studio 后台进程状态目录的上级目录 | | PI_STUDIO_HOST | 127.0.0.1 | 后端监听地址 | | PORT | 5177 | 独立运行端口；Extension 启动时使用系统分配的空闲端口 |

API

| 路径 | 说明 | | --- | --- | | GET /api/health | 服务身份、PID、监听地址与 Session 数据目录 | | GET /api/overview | 全局总览（KPI、近 30 天、Top 工具/项目、最近会话） | | GET /api/projects | 项目列表及聚合统计 | | GET /api/sessions?project=&q=&sort=&order=&limit=&offset= | 会话列表 | | GET /api/sessions/:id | 会话详情（全部原始条目 + 摘要） | | GET /api/sessions/:id/export.md | 导出主路径为 Markdown | | GET /api/search?q=&kind=&project=&limit= | 全文搜索 | | GET /api/stats?project= | 统计（每日/热力图/模型/工具/项目） |

数据只读，不会修改任何会话文件；文件按 mtime 增量重解析，TUI 里新产生的消息刷新页面即可看到。