📖 pi-atelier 实战指南 — 从零教会你使用 pi-atelier 扩展生态，包含完整示例和最佳实践。

pi-usage-stats

源码仓库 | npm

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 包装：

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

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

数据模型

{
  "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），避免竞态