[forachange]

Plugin type (required) / 插件类型（必填）

• UI Plugin / 是 UI 插件 — provides MCP Apps interactive pages / 提供 MCP Apps 交互页面
• Standard plugin / 普通插件（非 UI） — does not provide MCP Apps interactive pages / 不提供 MCP Apps 交互页面
• Not applicable / 不适用 — repository-only changes; no plugin content changed / 仅仓库级改动，不涉及插件内容

Affected plugin name(s) / 涉及的插件名称：usage-report

What / 改动内容

新增社区插件 usage-report（external_plugins/usage-report/），分类 utilities。

解决的问题：用户想了解每轮对话消耗了多少 token、会话累计用了多少、模型跑了多久，但 ZCode 客户端没有逐轮的用量报告；平台侧又没有本地可查询的 credits API。

用户可见行为：安装后，每次模型回复的末尾自动附上一行真实测量的统计：

📊 用量统计｜上轮 ↑1.2k ↓100 ⏱2s/2m01s｜累计 ↑3.6k ↓300 ⏱6s/5m01s

↑ 输入 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 / 自查清单

• Plugin name is unique kebab-case; new external plugin directory is external_plugins/<name>/ / 插件名唯一且 kebab-case，位于 external_plugins/usage-report/
• Usage category is set（utilities）
• Plugin type declared above（普通插件（非 UI）），涉及插件 usage-report
• version 同步：plugin.json 与 marketplace.json 均为 0.4.0
• README.md（EN）与 README_CN.md（中文）均已提供且语义一致
• description_i18n 包含 en 与 zh-CN，清单与市场条目完全一致
• 不含密钥、机器专属路径、缓存、构建产物
• 模型/API/网络依赖已写明（无网络、仅本地文件读写、需 python3）
• 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 通过

[panda920]

✅ Internal validation passed. A ZCode maintainer will review the change next; after acceptance, release checks run separately and this PR is closed automatically.