# @gajae-code/stats 中文文档

规范地址：https://npmcn.com/package/%40gajae-code/stats/

版本：0\.21\.0
npm 元数据更新时间：2026-11-16T05:12:24.848Z
中文译文更新时间：2026-11-16T05:13:59.746Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40gajae-code/stats
原文对照：https://npmcn.com/package/%40gajae-code/stats/?lang=original
项目主页：https://gajae-code.com/
源码仓库：https://github.com/Yeachan-Heo/gajae-code

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1 MB，69 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：10 个
- 首次发布：2026-05-27T18:46:36.080Z
- 最新版本发布：2026-11-16T05:12:24.517Z
- 近 30 天下载量：6727（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：158（近 12 个月 158 个）

## 中文简介

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

## 安装

```sh
npm install @gajae-code/stats
```

也可以使用：`pnpm add @gajae-code/stats`、`yarn add @gajae-code/stats`、`bun add @gajae-code/stats`

## README

# @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

```bash
# 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
```

### 程序化

```typescript
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/overview` | `overall` 财务报告和审定财务报表 `timeSeries` 仅限(_范围_(中文(简体) ) |
| `GET /api/stats/models` | 按要求统计的每个模型统计(_范围_(中文(简体) ) |
| `GET /api/stats/model-dashboard` | `byModel`, (中文(简体) ), `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` 引用同步会话文件后再做其他任何事情,所以没有单独的同步旗.

```bash
gjc stats --summary
```

### JSON 脚本输出

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

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

### 在自定义端口上的 Dashboard

```bash
gjc stats --port 3000
```

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

### 程序: 费用最高的文件夹

```typescript
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");
}
```

### 程序:最需要的模型

```typescript
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 是什么？

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 和提交记录判断。

