context — 看清 Session 到底吃了多少 Token

简介

coding agent 用久了，上下文窗口是最大的隐形成本。你感觉「越聊越慢」「回答变浅」，但很难定位根源——是 tool results 膨胀？某次 read 拉了冗余内容？还是对话历史本身过长？pi 内置的 /session 只展示 session 列表，缺少单 session 内容分布分析。@piex-dev/context 填补这个缺口：一次性输出结构化条目分析、角色占比和 token 估算。

技术原理

Token 估算：不做精确 token counting（精确计数需调模型 tokenizer，成本太高），用业界通用的「字符数 / 3.5」经验公式。对中英混合偏保守但不失为有用的相对比较。分析维度：按 role（user/assistant/system）+ type（message/tool_call/tool_result/custom）分类统计字符数，三个角色为分析主轴——Assistant（模型回答，通常大头）、User（你的指令）、Tool Results（最容易意外膨胀，如 read 大文件、grep 结果过多）。

session entries → 按 role 分类 → 按 type 分类
→ 按角色统计字符数 → ASCII bar chart + 结构化表格

使用说明

安装

pi install npm:@piex-dev/context

仓库源码：extensions/context

用法

/context

输出 Overview 表格 + Distribution ASCII 柱状图 + token 估算。

配置

无配置项，开箱即用。token 估算固定用 chars / 3.5 系数。

验证

pi -e ./extensions/context/src/context.ts -p "what is 1+1" --no-session

实现方案

约 160 行单文件。核心函数：analyzeEntries()（遍历 entries 按 role/type 统计）、countChars()（适配 string 与 content block 数组）、buildReport()（Markdown 表格 + ASCII 柱状图）、estimateTokens()（chars/3.5）、buildBar()（█/░ 柱状图）。

## Context Usage Report

### Overview
| Metric            | Value |
| Total entries     | 42    |
| Estimated tokens  | ~3.2k |

### Distribution
████████████░░░░░░░░ Assistant     62%
██████░░░░░░░░░░░░░░ User          28%
██░░░░░░░░░░░░░░░░░░ Tool Results  10%

设计参考

核心取舍：相对比较优先于精确计数（零成本、定位问题够用），静态快照优先于时序分析（先解决「现在谁占得多」）。

迭代记录

路线图

版本记录