pi-session-insights

pi-session-insights 是一个 Pi extension（扩展）包，做只读的 Pi 会话信息拓展：从本地 session JSONL 聚合会话消耗与活动，提供多维分析 + 项目化日报。

当前进度：已实现 K0 量纲 + 多维分析（K1/K2/K3/K5）+ 按天摘要缓存 + 项目化日报（复用 pi-daily 日报链）+ 配置化自动归档 + L2 交互面板。详见 doc/10-需求规格/PRD-pi-session-insights.md。

定位

• 只读不拦截：只读 ~/.pi/agent/sessions/**/*.jsonl 及本机扩展产生的脱敏数字账本，不拦截工具调用、不做 sandbox。对照 context-mode 的分析层心智模型，但靠读取既有记录达到深度，不付拦截税。
• 调研与设计依据见 doc/20-能力参考/01-context-mode会话信息分析参考.md 和 doc/10-需求规格/PRD-pi-session-insights.md。

当前功能（量纲 + 多维分析 + 项目化日报）

注册两个独立的 slash command（斜杠命令）：

/insights [自然语言时间范围]   # token/cost/工具/项目/健康数字面板
/daily [日期|范围] [--day-start HH:mm] [--project current]   # 项目化日报

/insights 默认无参数显示今天的数据：

/insights
/insights 最近5小时
/insights 本周
/insights 最近一周
/insights 昨天
/insights 昨天到今天
/insights 2026-06-17
/insights 2026-06-10 到 2026-06-17
/insights 当前会话

/daily 生成按真实项目分组的项目化日报并归档：

/daily                       # 今天日报
/daily 昨天
/daily 2026-06-17
/daily 0718 和 0719           # MMDD 范围按当前年份解析
/daily 2026-06-10 到 2026-06-17
/daily 本周
/daily --project current     # 限定当前项目
/daily --day-start 03:00     # 自定义日界

/insights daily 已废弃；pi-daily 卸载后由本项目 /daily 接管每日日报。

日报自动归档到 ~/.pi/agent/pi-session-insights.json 的 reportOutputDir；未配置时写 ~/Documents/pi-daily-reports/YYYY-MM-DD.md。多日范围会逐日写入独立文件，命令或 tool 结果只显示生成数量与归档路径，不展开各日报正文。归档覆盖策略：无已有文件直接写入；有已有文件时，TUI 模式一次确认是否覆盖（多天合并确认），非交互模式（-p/JSON/RPC）默认跳过已有文件并在结果提示。dailyModel 可选用 provider/model-id:thinking 指定日报模型；不可用时会提示并回退当前会话模型，当前模型也不可用时使用本地 Markdown fallback。

同时注册两个 tool（工具），agent 可在自然语言对话中调用：insights（读 token/cost 消耗，优先传结构化 since/until）与 daily（生成项目化日报，传 date/range/projectCurrent）。例如你问"最近 5 小时 token 花了多少？"时 agent 调 insights；问"生成今天的日报"或"总结今天的工作"时 agent 调 daily。

UI 行为

• TUI 模式：/insights 无参数会立即打开带加载状态的 L2 overlay 交互面板（第 1 页今天消耗 / 第 2 页昨天日报预览，见 ADR 0003），再异步读取数据。数字页只保留今天范围内的 session 事件；日报页只读缓存并限制行数。完整日报请运行 /daily。带参数（如 /insights 最近5小时）走原生 select/input 提问式对话框。
• 非 TUI 模式（pi -p / JSON / RPC）：输出纯文本，方便脚本和测试验证。
• 日报标签与 AI 输出跟随 pi-di18n 的当前 locale（语言环境）；支持简体中文、繁体中文、日语、韩语、德语、法语、西班牙语、葡萄牙语、俄语、阿拉伯语和英语。
• 时间范围解析：先用当前模型理解，失败后回退本地规则解析。

统计口径

• 默认 /insights = 今天本机所有 session 的统计。
• 时间范围统计逐行读取 session JSONL，只保留范围内事件与必要元数据；扫描保持异步、容错，并串行化多个外部扫描请求以控制内存峰值。
• 时间窗口按 assistant message（模型回复）的实际 timestamp（时间戳）聚合 token 与 cost；同时只读合并 ~/.pi/agent/audit-usage.jsonl 中 pi-dgoal 的脱敏审核用量，以及 ~/.pi/agent/dteam-usage.jsonl 中 dteam in-memory worker 的脱敏用量（都按 dedupKey 去重）。
• 模型维度按 provider/model（供应商/模型）聚合；即使 model 同名，只要 provider 不同也会分开统计。
• /insights 当前会话 使用 ctx.sessionManager.getBranch() 统计 active branch，并按 parentSessionId 合并该主会话所属的 dteam worker 用量。

支持的时间表达

• 今天 / day / today
• 昨天 / yesterday
• 本周 / week
• 最近一周 / 过去一周 / last week
• 最近 N 小时 / 最近 N 天 / 最近 N 周
• 裸时间：5小时、1天、2周
• 单日：YYYY-MM-DD、YYYY/MM/DD
• 日期范围：YYYY-MM-DD 到 YYYY-MM-DD、YYYY/MM/DD 到 YYYY/MM/DD
• 命名范围：昨天到今天（结束边界为当前时刻）、昨天到现在
• 中文月日范围：7月18日到7月19日（按当前年份解析）
• /daily 紧凑月日范围：0718 和 0719（按当前年份解析）
• 当前会话 / session

当模型与本地规则都无法识别时，会回退到今天，并在标题里保留原始输入提示。

项目结构

pi-session-insights/
├── index.ts                # Pi extension 入口，注册 /insights + /daily 命令与 insights/daily tool
├── src/
│   ├── types.ts            # 类型层：Session JSONL 解析类型 + 量纲/范围类型
│   ├── session-scan.ts     # 扫描层：异步扫描 ~/.pi/agent/sessions，容错解析（复用自 pi-daily）
│   ├── locale.ts           # 多语言文案 + locale 解析（pi-di18n 事件 API）
│   ├── usage-rollup.ts     # K0 量纲聚合（rollupEntries/rollupSessions，纯函数）
│   ├── dimensions.ts      # 多维聚合（K1 项目/K2 工具/K3 错误/K5 健康，纯算法）
│   ├── time-range.ts       # 时间范围解析（parseRange + LLM 解析）
│   ├── format.ts           # 格式化与渲染（print 模式纯文本）
│   ├── insights.ts         # 命令主逻辑（组装扫描 → 聚合 → 渲染）
│   ├── daily-command.ts    # /daily 命令参数解析、日期展开与 tool 参数合并
│   ├── daily-options.ts    # 默认/显式日界
│   ├── daily-config.ts     # 日报配置与模型选择器
│   ├── daily-archive.ts    # 配置目录稳定归档
│   ├── daily-orchestrator.ts # /daily 编排：覆盖确认、扫描、生成、归档、错误隔离
│   ├── day-cache.ts        # 按天摘要缓存（day-*.json 读写幂等 + 增量补跑）
│   ├── day-report.ts       # 日报组装：接日报生成链 + 缓存
│   ├── date-utils.ts       # 本地日期字符串与自然日 TimeRange
│   ├── report-session-extract.ts # 从 session 提取日报事实（任务/完成/阻塞/工具/文件）
│   ├── report-model.ts     # 按项目聚合日报模型
│   ├── report-ai-summary.ts # 配置模型→当前会话模型→本地 Markdown fallback
│   ├── report-markdown.ts  # AI 失败时的本地 Markdown fallback
│   ├── report-labels.ts    # 日报正文多语言文案字典
│   ├── daily-ui-labels.ts  # 日报命令 UI 多语言文案字典
│   ├── audit-usage.ts      # pi-dgoal audit-usage.jsonl 扫描、时间过滤与数字聚合
│   ├── dteam-usage.ts      # dteam-usage.jsonl 扫描、去重及 worker/model/tier 聚合
│   ├── panel-data.ts       # L2 overlay 面板数据加载
│   ├── report-redact.ts    # 日报链脱敏与截断
│   ├── obsidian-sync.ts    # 遗留 Obsidian 落点工具，不参与默认日报归档
│   └── panel.ts            # L2 overlay 交互面板（今天消耗/昨天日报切换）
├── tests/                  # Node 内置 test（TS 直接 import .ts）
├── doc/                    # 需求规格、调研参考、决策档案
└── package.json            # Pi package 清单

安装

把本仓库路径加入 ~/.pi/agent/settings.json 的 packages：

"/Users/diwu/Workspace/Codes/Githubs/pi-session-insights"

然后在 Pi 中执行：

/reload

开发验证

npm run check          # typecheck + 单元测试
PI_SKIP_VERSION_CHECK=1 pi --no-extensions --extension ./index.ts --no-session -p "/insights"
PI_SKIP_VERSION_CHECK=1 pi --no-extensions --extension ./index.ts --no-session -p "/insights 最近5小时"
PI_SKIP_VERSION_CHECK=1 pi --no-extensions --extension ./index.ts --no-session -p "/insights 当前会话"
PI_SKIP_VERSION_CHECK=1 pi --no-extensions --extension ./index.ts --no-session -p "/daily 2020-01-02"