独立 AstrBot 插件，记录模型返回的 Token 用量，支持 QQ 统计卡片与文本查询。统计从安装启用后开始，不自动导入历史，也不查询账户余额。
在 AstrBot 插件页从文件安装本插件 ZIP，重载后开始记录。Pillow 已是 AstrBot 的依赖；无安装脚本、外部渲染服务或字体下载。
默认仅机器人管理员可查询：
/token
/token 近7天
/token 累计
/token 当前会话
/token 今日 全部
/token 累计 模型 实际模型名称
/token 今日 文本
默认只查当前会话来源（群或私聊）；“全部”仅管理员可查，包含未归属到会话的模型调用。“当前会话”使用 AstrBot 会话ID，重置会话后区分旧会话。未取得会话ID时不回退为查询所有会话。
允许成员查询时，将“谁能查询”改为“成员可查当前会话”。群成员看到的是本群来源的合计，不是个人账单；不能查看其他群或全局统计。缺少中文字体时返回文本，也可追加“文本”。
默认启用已核对的 DeepSeek 官方 Flash/Pro 人民币价格。建议在“使用官方价格的提供商ID”里填写直连官方的 AstrBot 提供商ID；留空按内置模型名匹配。第三方代理价格不同，请关闭官方预设或填写模型单价。旧名 deepseek-chat / deepseek-reasoner 没有在本次官方价格表中明确列价，因此不会猜测映射。
每条调用分开记录缓存未命中输入、缓存命中输入、缓存写入（如有）、输出费用，不重复计算总输入。DeepSeek 总价 = 未命中输入 × 对应单价 + 命中输入 × 对应单价 + 输出 × 对应单价。单价单位均为每百万 Token。缓存字段缺失或冲突时费用保持未知。
普通模型响应在返回时固定时间；流式响应使用最后一份汇总用量的接收时刻，不用生成器关闭时间或数据库落盘时间。不逐块累加。仅有汇总用量时，整次调用按最后一份用量接收时段估算，不能精确拆分跨时段流中每个Token。OAuth桥接在收到上报时固定时间，仍只记录订阅用量。
“本地统计时区”默认 local，即运行 AstrBot 的服务器系统时区，和查看QQ的手机时区无关；可设 Asia/Shanghai。今日、近7天与每条本地时间按该设置计算。DeepSeek 官方时段始终按北京时间转换，避免服务器在海外时误计价。数据库保存带UTC偏移的接收时间、计价时段、完整单价快照、规则来源及拆分费用。改价、延迟落盘、重新启动不会重算历史。升级自动增加数据库列，旧费用保留，旧记录标为“历史记录（未保存时段）”。
“模型单价”可为相同模型添加多个条目，每项设置名称、适用时段（全天/自定义/DeepSeek官方高峰/官方空闲）、币种和三项单价。自定义条目支持每周日期和跨午夜时段；起点包含、终点不包含，开始等于结束代表全天。例：周一22:00–02:00包含周二01:00。规则时间使用条目时区，留空使用本地统计时区。
选择顺序：先匹配模型与提供商，再筛选时间；精确提供商优先，同一层级的时段条目优先于全天条目。相同优先级的匹配项重叠时，费用标为条目冲突，不随意取第一项。该模型只要存在用户规则，就不再回退官方预设；没有覆盖的时段保持未知。价格空白为未知，明确填0才为零费用。不同币种不换汇；缺少缓存写入价格时不估算该调用。
统计卡片和文本显示时段分组、最近一条的当地接收时间；文本额外显示分项费用。可以用 /token 今日 文本 查看。详细单价快照存于本插件 usage.sqlite3 的 calls.price_snapshot，原始接收时间存于 ts，本地时间存于 local_time，时段存于 price_period。数据库不包含聊天正文、图片或令牌。
四个可直接参考的官方高峰/空闲价格条目见 分时价格配置示例。其中__template_key是AstrBot模板条目标识；示例不是完整插件配置，请只将需要的字段填入现有设置，保留其他权限配置。
官方规则、当前单价、已支持模型与日历维护说明见 DeepSeek官方价格说明。API费用只是估算，不能视为供应商实际扣费；Search/Fetch等独立工具费用未计入。
同时安装 ChatGPT OAuth 识图 v0.1.5 或更新版，即可接收其QQ识图调用的数字用量。旧版需升级；不重新登录。该插件的独立HTTP请求不能通过普通Provider观察自动捕获。
OAuth记录始终标为订阅调用，不套用API单价、不推算余额、剩余百分比或重置时间。管理脚本中的登录、模型目录、自检不属于QQ会话，不计入这条上报链路。
- 通过可恢复的实例方法包装观察 AstrBot 聊天提供商的
text_chat/text_chat_stream返回值，不改HTTP库、认证或请求参数；卸载时恢复原方法。 - 普通回复、工具循环中的提供商调用、直接使用这些提供商接口的第三方插件均可记录。流式取最后一份汇总用量，不逐块累加；同一提供商调用内部嵌套的接口不重复统计。私自直连HTTP、外部执行器和不经过这两个方法的模型调用不自动覆盖；代理内部的重试、路由和隐藏请求无法逐次核对。
- 对常见 OpenAI Chat/Responses、DeepSeek缓存字段、Anthropic分列缓存、Gemini用量及AstrBot标准用量做保守解析。未知格式显示未知；AstrBot标准对象默认的0缓存不能证明接口报告过缓存。
- 数据保存在本插件专属
usage.sqlite3。只保存时间、匿名化会话键、提供商/模型名称、数字用量、状态和价格快照。不写入聊天正文、图片、模型答案、请求参数、密钥或OAuth令牌。 - 记录失败或队列满会标记统计不完整，不能作为精确账单。正常停用会尝试排空队列；突然断电、强制结束或尚未完成的调用可能未落盘。
- 默认保留90天、至多10万条；达到上限会分批删除最旧记录。因此“累计”是当前保留数据累计，不是账号终身用量。查询不额外调用模型。
OAuth插件通过 context.get_registered_star('astrbot_plugin_token_usage') 获取已启用插件实例，再调用 ingest_external(event, request_id=唯一ID, model=模型名, usage=仅数字usage, status=状态)。该接口将来源固定为ChatGPT订阅，不接受计费类型覆盖。相同request_id只写入一次。
在本目录使用已有Pillow运行 python -m unittest discover -s tests -v。测试只用模拟提供商、合成数字和临时数据库，无真实账户或模型请求。真实QQ与用户服务器联调仍需反馈。
采用 MIT License。
使用 StarTools.get_data_dir("astrbot_plugin_token_usage")。SQLite仅保存在 data/plugin_data/astrbot_plugin_token_usage/，不写入共享根目录、不改变共享根目录权限。本仓库不包含GPT价格估算，ChatGPT OAuth只统计数字用量。旧版若误写共享根目录，先停用插件并备份，再由管理员确认文件归属后迁移；不要在SQLite仍打开时搬动文件。