@gajae-code/stats

中文文档
0.21.0发布于 2026/11/16MITTypeScriptES Module构建来源已验证近 30 天下载 6727

Pi AI 使用统计的本地可观察性仪表板

中文使用文档
文档目录17 节
  1. 特征
  2. 跟踪到的量子
  3. 使用量
  4. 通过 CLI
  5. 程序化
  6. API 终点
  7. 本地服务器安全
  8. 数据存储
  9. 盘子
  10. 提示常见模式( C)
  11. 同步并打印摘要
  12. JSON 脚本输出
  13. 在自定义端口上的 Dashboard
  14. 程序: 费用最高的文件夹
  15. 程序:最需要的模型
  16. 解决问题
  17. 许可证

@gajae-code/数据

AI使用统计的本地可观察仪表板.

特征

  • 会话日志解析:从 ~/.gjc/agent/sessions/
  • SQLite 聚合: 使用高效数据存储和查询 bun:sqlite
  • 网络仪表板: 图.js的实时可视化计量
  • 递增同步: 只处理新/已修改的日志条目
  • 角色使用细分数字 : gjc stats --summary 和 JSON 报告默认使用、执行者、规划者、建筑师和评论家;没有身份元数据的自定义角色和遗留会议归为 other 或者说 unknown

跟踪到的量子

度量衡计算
键/秒output_tokens / (duration / 1000)
缓存率cache_read / (input + cache_read) * 100
错误率count(stopReason=error) / total_calls * 100
费用共计总计 usage.cost.total
Avg 纬度平均值 duration
TTFT 电话平均值 ttft (时间到第一令牌)

使用量

通过 CLI

# Start dashboard server (default: http://localhost:3847)
gjc stats

# Custom port
gjc stats --port 8080

# Print summary to console
gjc stats --summary

# Output as JSON (for scripting)
gjc stats --json

程序化

import { getDashboardStats, syncAllSessions } from "@gajae-code/stats";

// Sync session logs to database
const { processed, files } = await syncAllSessions();

// Get aggregated stats
const stats = await getDashboardStats();
console.log(stats.overall.totalCost);
console.log(stats.byModel[0].avgTokensPerSecond);
console.log(stats.byAgent.find(agent => agent.agent === "executor")?.totalCost);

API 终点

标记终点 范围 接受 ?range=1h|24h|7d|30d|90d|all (默认) 24h; 未知值会回到 24h) (中文(简体) ). 时间序列使用小时桶 1h 财务报告和审定财务报表 24h 和长距离的日用桶.

终点说明
GET /api/stats全数 DashboardStats 对象:总体情况、失败情况、每个模型/文件夹/代理件的分解情况、时间、模型、模型性能和成本序列,以及缓存缺失的归属(范围(中文(简体) )
GET /api/stats/overviewoverall 财务报告和审定财务报表 timeSeries 仅限(范围(中文(简体) )
GET /api/stats/models按要求统计的每个模型统计(范围(中文(简体) )
GET /api/stats/model-dashboardbyModel, (中文(简体) ), modelSeries,以及 modelPerformanceSeries (单位:千美元)范围(中文(简体) )
GET /api/stats/folders每个文件夹/项目统计(范围(中文(简体) )
GET /api/stats/timeseries请求、错误、符号和每桶时间成本(范围(中文(简体) )
GET /api/stats/costs每个模型和供应商的每日费用,分为投入/产出/包范围(中文(简体) )
GET /api/stats/behavior用户信息行为信号(大叫、放屁、重复等):整体而言,每个模型,并随着时间推移(范围(中文(简体) )
GET /api/stats/recent最近的请求,最先?limit=,默认 100)
GET /api/stats/errors最近以出错停止的请求( E)?limit=,默认 100)
GET /api/request/:id一份请求及其存储的信息和输出; 404 如果未知,则
POST /api/sync同步会话文件并返回 { processed, files, totalMessages }· ; 409 当同步已经运行时

本地服务器安全

仪表盘只绑住 127.0.0.1; CLI 打开默认浏览器 URL localhost。API 请求必须使用 HTTP, 服务器的实际端口, 并且准确无误 localhost 或者说 127.0.0.1。浏览器请求必须保持同一来源,会话同步需要同一来源 POST 请求。 服务器无法启用跨源访问或信任转发主机头 .

反向代用和不回放部署是不支持的. 它们需要单独的经过认证的部署边界,而不是放松这些仅在当地进行的检查.

数据存储

  • 会话日志数字 : ~/.gjc/agent/sessions/ (JSONL档案)
  • 数据库数字 : ~/.gjc/stats.db (SQLite) (英语)

盘子

网络仪表板提供:

  • 总的衡量卡(要求、成本、缓存率、出错率、持续时间、信使)
  • 显示请求和长期错误的时间序列图表
  • 按模型分列的表格
  • 每个文件夹的细分表
  • 每30秒自动刷新一次

提示常见模式( C)

同步并打印摘要

每个 gjc stats 引用同步会话文件后再做其他任何事情,所以没有单独的同步旗.

gjc stats --summary

JSON 脚本输出

与 --json,stdout只载有 JSON 文件;同步进度和 Synced N new entries ... 摘要转到 stderr .

gjc stats --json | jq '.overall.totalCost'

在自定义端口上的 Dashboard

gjc stats --port 3000

--summary 财务报告和审定财务报表 --json 打印并退出而不启动服务器, 因此 --port 与它们结合时没有效果.

程序: 费用最高的文件夹

import { getDashboardStats, syncAllSessions } from "@gajae-code/stats";

await syncAllSessions();
const stats = await getDashboardStats();

const [first, ...rest] = stats.byFolder;
if (first) {
  const topFolder = rest.reduce((a, b) => (b.totalCost > a.totalCost ? b : a), first);
  console.log(`Highest cost folder: ${topFolder.folder} ($${topFolder.totalCost.toFixed(2)})`);
} else {
  console.log("No folder data available");
}

程序:最需要的模型

import { getDashboardStats, syncAllSessions } from "@gajae-code/stats";

await syncAllSessions();
const stats = await getDashboardStats();

// byModel is ordered by request count, highest first.
const topModel = stats.byModel[0];
if (topModel) {
  console.log(`Most requested model: ${topModel.model} (${topModel.totalRequests} requests)`);
}

解决问题

  • 没有显示数据吗? 检查此会话日志是否存在于 ~/.gjc/agent/sessions/ (单位:千美元)~/<GJC_CONFIG_DIR>/agent/sessions/ 如果设置了变量). 有习惯 GJC_CODING_AGENT_DIR,会话在 $GJC_CODING_AGENT_DIR/sessions/否则,在Linux和macOS上,如果 XDG_DATA_HOME 设置和 $XDG_DATA_HOME/gjc 存在( 创建于 gjc config init-xdg页:1 $XDG_DATA_HOME/gjc/sessions/。这些变量必须来自您的外壳环境。 一个项目 .env 无法设置,如果 .env 条目用途 $ 扩展它也会阻断 shell 值;在两种情况下都适用默认路径.
  • 达克板没有开始吗? 请检查access-date=中的日期值 (帮助) 端口 3847(或通过端口 --port)是免费的.

许可证

麻省理工学院

版本与发布记录

@gajae-code/stats 共发布 158 个版本,首次发布于 2026/05/28;过去 12 个月发布了 158 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.21.0latest2026/11/16今天
0.20.1-nightly.20261108030927.43711868338.gb4127889c4a8nightly2026/11/15今天
0.20.1-nightly.20261108030927.43590872198.gb4127889c4a82026/11/141 天前
0.20.1-nightly.20261108030927.43424588966.gb4127889c4a82026/11/132 天前
0.20.1-nightly.20261108030927.43222623203.gb4127889c4a82026/11/123 天前
0.20.1-nightly.20261108030927.43016219422.gb4127889c4a82026/11/114 天前

关于 @gajae-code/stats 的常见问题

@gajae-code/stats 是什么?

Pi AI 使用统计的本地可观察性仪表板

如何安装 @gajae-code/stats?

在项目目录运行 npm install @gajae-code/stats,或使用 pnpm add / yarn add / bun add。它还提供命令行工具 gjc-stats,可以用 npx gjc-stats 直接运行。

@gajae-code/stats 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gajae-code/stats 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gajae-code/stats 可以商用吗?

@gajae-code/stats 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gajae-code/stats 的下载量有多少?

根据 npm 官方下载统计,@gajae-code/stats 在 2026/10/16 – 2026/11/14 这 30 天内被下载 6,727 次,日均约 224 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gajae-code/stats 还在维护吗?

最新版本 0.21.0 发布于 2026/11/16(今天);至今共发布 158 个版本,其中过去 12 个月发布了 158 个;首次发布于 2026/05/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。