> 📖 **[pi-atelier 实战指南](https://catlain.github.io/pi-atelier/)** — 从零教会你使用 pi-atelier 扩展生态，包含完整示例和最佳实践。

# pi-usage-stats

[源码仓库](https://github.com/catlain/pi-usage-stats) | [npm](https://www.npmjs.com/package/pi-usage-stats)

pi-coding-agent 扩展包工具使用次数统计。

## 功能

- **AI 工具调用统计**：监听 `tool_call` / `tool_result` 事件，自动记录每次 AI 调用的工具名和错误次数
- **用户命令统计**：双轨机制
  - 已注册命令：通过 `wrapCommand()` 包装（需扩展主动接入）
  - 未注册命令：监听 `input` 事件自动识别（零配置）
- **持久化存储**：`~/.pi/agent/data/usage-stats.json`，session_shutdown 时自动写入
- **查询报告**：`/usage` 命令或 `usage_stats` 工具，支持 today / week / all 时间范围

## 使用

### 查看统计

```
/usage                     # 今天的统计
/usage week                # 近 7 天
/usage all                 # 全部历史
/usage today --tool bash   # 过滤工具名
```

AI 也可以调用 `usage_stats` 工具查询。

### 接入用户命令统计（扩展开发者）

pi 的已注册命令（`/journal`、`/usage` 等）执行时 **不触发 `input` 事件**（pi 会直接执行命令 handler）。因此需要扩展主动用 `wrapCommand` 包装：

```typescript
import { wrapCommand } from "@pi-atelier/usage-stats/lib/wrap-command";

// 替代 pi.registerCommand("journal", def)
wrapCommand(pi, "journal", {
  description: "生成日报",
  handler: async (ctx, args) => { ... },
});
```

## 数据模型

```json
{
  "version": 1,
  "daily": {
    "2026-05-29": {
      "bash": { "ai": 42, "user": 0, "errors": 2 },
      "journal": { "ai": 3, "user": 1, "errors": 0 }
    }
  },
  "tools": {
    "bash": { "firstUsed": "...", "lastUsed": "...", "totalAi": 42, "totalUser": 0 }
  }
}
```

- 按**天聚合**，避免 history 无限增长
- 超过 180 天的数据自动清理
- 写入使用文件锁（`proper-lockfile`），避免竞态