slug: poeusage
version: 0.5.0

一个 ClawHub 技能，用于通过 poeusage CLI 监控 Poe API 积分余额及使用历史。

安装

brew tap rgstephens/tap
brew install poeusage

说明

poeusage 是一款终端工具，用于监控您的 Poe API 配额、使用历史和消费汇总。支持 JSON / CSV / 表格输出模式、分页、过滤以及 Shell 补全脚本生成。

CLI 命令

全局标志

• --api-key 字符串（默认从 $POE_API_KEY 环境变量读取）
• --json 布尔值
• --plain 布尔值
• --no-color 布尔值
• --quiet / -q 布尔值
• --verbose / -v 布尔值
• --timeout 整数（默认为 30）
• --help / -h 布尔值
• --version 布尔值

子命令

poeusage balance

获取并显示当前积分余额。

用法：

poeusage balance [--json] [--plain]

• TTY 示例：Current balance: 1,500 pts
• --plain 示例：1500
• --json 示例：{"current_point_balance":1500}

poeusage history

获取使用历史记录。默认自动分页，直至获取全部记录（或达到 --limit 指定数量）。

用法：

poeusage history [flags]

标志：

• --limit / -n 整数（0 表示全部）
• --page-size 整数（默认为 100，最大值为 100）
• --no-paginate 布尔值
• --cursor 字符串
• --bot / -b 字符串
• --type / -t 字符串（可选值：chat、api、canvas）
• --since 字符串（格式：YYYY-MM-DD 或 Unix 时间戳）
• --until 字符串（格式：YYYY-MM-DD 或 Unix 时间戳）
• --output / -o 字符串
• --format / -f 字符串（可选值：table、csv、json）

注意事项：

• --json 是 --format json 的别名
• --plain 是 --format csv 的别名
• 日期筛选在客户端执行
• 启用 --no-paginate 时，若仍有更多页，则向 stderr 输出 next-cursor:

默认表格输出列：TIME、BOT、TYPE、POINTS、COST (USD)

CSV 输出列：time,bot_name,usage_type,cost_points,cost_usd,query_id,chat_name,input_pts,output_pts,cache_write_pts,cache_discount_pts

JSON 输出示例：

[
  {
    "bot_name": "Claude-3.5-Sonnet",
    "time": "2024-01-09T14:00:00Z",
    "query_id": "2Nhd9xBFbLcXEwmNj",
    "cost_usd": "0.00075",
    "cost_points": 339,
    "usage_type": "API",
    "chat_name": null,
    "cost_breakdown": {
      "input": 120,
      "output": 219,
      "cache_write": 0,
      "cache_discount": 0,
      "total": 339
    }
  }
]

poeusage summary

聚合使用数据并展示费用明细。支持与 history 相同的筛选条件，并额外支持按维度分组。

用法：

poeusage summary [flags]

标志：

• --bot / -b 字符串
• --type / -t 字符串
• --since 字符串
• --until 字符串
• --group-by / -g 字符串（可选值：bot、type、day、bot,type）
• --format / -f 字符串（可选值：table、csv、json）

默认表格输出列（按 bot 分组）：BOT、QUERIES、POINTS、COST (USD)

poeusage completion

生成 Shell 补全脚本。

用法：

poeusage completion 

示例：

poeusage completion zsh > ~/.zsh/completions/_poeusage

I/O 协议

• stdout：主命令输出
• stderr：诊断信息、进度提示、警告、下一页游标提示
• TTY 检测控制颜色与格式化行为

退出码

• 0：成功
• 1：运行时错误（网络/API 错误）
• 2：参数使用错误
• 3：认证错误（HTTP 401）

配置

优先级顺序：命令行标志 > 环境变量 > 配置文件 > 默认值

环境变量：

• POE_API_KEY
• NO_COLOR
• POEUSAGE_TIMEOUT
• POEUSAGE_PAGE_SIZE

配置文件路径：~/.config/poeusage/config.toml

# api_key = "..." # 不推荐在此处设置
timeout = 30
page_size = 100

发布

• make release TAG=v1.0.0