Repository navigation
feat(usage-report): 新增用量统计插件(UserPromptSubmit 钩子注入 token 用量与耗时) - #189
forachange wants to merge 5 commits into
Conversation
|
✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically. |
|
✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically. |
|
✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically. |
|
✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically. |
|
✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically. |
Plugin type (required) / 插件类型(必填)
Affected plugin name(s) / 涉及的插件名称:
usage-reportWhat / 改动内容
新增社区插件
usage-report(external_plugins/usage-report/),分类utilities。解决的问题:用户想了解每轮对话消耗了多少 token、会话累计用了多少、模型跑了多久,但 ZCode 客户端没有逐轮的用量报告;平台侧又没有本地可查询的 credits API。
用户可见行为:安装后,每次模型回复的末尾自动附上一行真实测量的统计:
↑输入 tokens(含缓存读)、↓输出 tokens、⏱纯算耗时/墙钟跨度;上轮 = 上一轮,累计 = 本会话至今。零额外回合(不用 Stop 延续),数据截至上一轮。实现:
UserPromptSubmit钩子运行scripts/report_usage.py(纯标准库 Python),解析本会话本地 rollout 日志~/.zcode/cli/rollout/model-io-*.jsonl中每条请求的response.usage(inputTokens/outputTokens/cacheReadTokens)、durationMs、completedAt,仅读取用量字段、不读对话内容;统计结果以additionalContext注入,状态记账存于~/.zcode/usage-report-plugin/state/。测试方式:安装后在 ZCode 新开会话,发送任意两条消息,第二条回复末尾出现统计行且数值与 ZCode 会话日志一致;会话首条消息不附加。
依赖、网络、权限与副作用:无网络访问;不访问凭据;无第三方代码/素材/服务(仅 Python 标准库);本地文件读取(rollout 日志的用量字段)与写入(状态目录);本地执行
python3钩子脚本;运行时需python3(macOS/Linux 自带)。均已在双语 README 中说明。第三方材料来源与许可证:无第三方材料;插件代码以 MIT 许可证发布(manifest
license: MIT)。版本与市场注册:
0.4.0(首次提交),plugin.json与根marketplace.json条目一致,description_i18n含en与zh-CN。Self-check / 自查清单
external_plugins/<name>// 插件名唯一且 kebab-case,位于external_plugins/usage-report/categoryis set(utilities)usage-reportversion同步:plugin.json与marketplace.json均为0.4.0README.md(EN)与README_CN.md(中文)均已提供且语义一致description_i18n包含en与zh-CN,清单与市场条目完全一致python3 scripts/validate.py通过(OK: 55 plugin(s) validated)python3 scripts/build_dist.py全量通过 —— 本地预置环境限制:部分既有 UI 插件(如excalidraw)需要node >= 24与pnpm build产物,本机 node 为 v23.11.0,全量构建无法完成;与本次新增插件无关。已单独验证external_plugins/usage-report可正常打出确定性 zip(build_zip通过)。git diff --check通过