feat(usage-detail): 新增本地用量明细插件

[axdlee]

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

• UI Plugin / 是 UI 插件 — provides MCP Apps interactive pages / 提供 MCP Apps interactive pages
• Standard plugin / 普通插件（非 UI）
• Not applicable / 不适用

Affected plugin name(s) / 涉及的插件名称：usage-detail（ui.surfaces 侧栏面板 + 工具 _meta.ui.resourceUri 页面，故声明为 UI Plugin）

What / 改动内容

新增社区插件 usage-detail（v0.13.4）：ZCode 本地逐条用量分析，全部本地计算、零模型开销、数据库只读。

解决的用户问题：官方客户端只提供用量汇总，用户看不到每次请求的 token 构成、输出速率、缓存命中率，也没有预算告警与浪费分析；GLM Coding Plan 订阅用户尤其需要零 token 开销的用量可见性。

功能：

• 逐条请求明细（时间/会话/模型/官方套餐与 BYOK 来源/token 构成/耗时/首字/tok-s 六档变色/状态/折算成本），分页、排序、两级钻取
• 会话侧栏面板（MCP App）：与 /usage-ui 同一完整界面（六个页签、热力图三态、模型效率排行、健康分）；每轮统计经 resources/subscribe → notifications/resources/updated 实时推送到面板顶部横幅——本地计算、不进上下文
• 会话健康分（失败/取消/重试加权）、浪费取证（失败/取消/重试白耗 token + Top 会话/模型）
• 预算与燃烧告警（本地常驻面板每分钟检查，80%/100% 与用量偏高弹 macOS 通知，每档每日一次）；权限等待提醒（async PermissionRequest 钩子，默认关）
• 折算成本：GLM 5.3 系内置智谱官网权威牌价（CNY），其余模型每日从 models.dev 同步并按 USD→CNY 换算（可关）
• /usage /usage-ui /usage-this /usage-today 命令 + 本地面板（仅监听 127.0.0.1）+ JSON/CSV/自包含 HTML 导出

版本与注册：插件清单与 marketplace.json 条目均为 0.13.4；分类 utilities。

测试方式：

• 仓库自带 tests/（44 项，python3 直接运行）：CLI 全子命令、turn-stats 守卫、serve HTTP 全端点、MCP 协议（tools/resources/订阅推送）、三个 hooks 行为
• 在 ZCode Desktop 3.15.3 实测：安装 → 会话右侧「+」选择「用量」面板 → /usage-ui 仪表盘 → 设置弹窗配置价格/预算/通知

依赖、网络、权限与副作用（README 双语均已披露）：

• 零 npm/pip 依赖（仅 Node 内置模块 + bash + sqlite3 CLI）
• 只读打开 ~/.zcode/cli/db/db.sqlite；仅写自身配置/状态文件（~/.zcode/usage-*.json）
• 本地监听 127.0.0.1:7741（面板服务）；macOS osascript 系统通知（其他平台静默）
• 出站网络仅两处：models.dev 价格每日同步（ZCODE_USAGE_NO_AUTOSYNC=1 可关）、open.bigmodel.cn 配额查询（仅在用户自配 API Key 时）；无遥测
• 钩子：UserPromptSubmit（默认静默）/ Stop（async，写本地标记文件）/ PermissionRequest（async，默认关）——均不注入模型上下文

第三方材料：models.dev 价格数据（MIT，本地换算缓存）；其余为原创代码，MIT License（插件目录内附 LICENSE）。

Self-check / 自查清单

• 插件名唯一 kebab-case，位于 external_plugins/usage-detail/
• category: utilities 已填写
• 中英双语 README（README.md / README_CN.md），副作用与网络访问已披露
• 未提交密钥、私有数据或机器专属路径（路径全部经 ZCODE_PLUGIN_ROOT/homedir 动态解析）
• validate.py 通过（46 plugins validated）；本插件 build_zip 通过；git diff --check 通过
• 中英 description / description_i18n 在 plugin.json 与 marketplace.json 保持一致

[panda920]

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

[axdlee]

已推送 0.14.0（fa45cee）：补齐 Windows / Linux 支持。

• 统一通知通道 scripts/notify.mjs：macOS = osascript；Windows = PowerShell 5.1 自带 WinRT toast（零模块依赖）；Linux = notify-send；不可用时静默。Stop 钩子、PermissionRequest 钩子、预算告警 watchdog 三处全部改走该通道——此前仅 macOS。
• 摆脱 sqlite3 CLI 依赖：scripts/sqlite.mjs（node:sqlite）完整复刻 sqlite3 list / -header 输出，usage.sh 在 sqlite3 缺失时自动切换（Windows Git Bash 常见）；新增 test_sqlite_shim.py 逐条对比两实现输出一致性。
• serve 面板在 Windows 用 cmd /c start 打开浏览器。
• 双语 README 新增 Platform support 小节：三平台全量核心能力（侧栏面板 / MCP / 钩子 / 仪表盘 / CLI），CLI 需 bash（Windows 用 Git Bash）与 Node ≥ 22.13（ZCode 自带）。

说明：跨平台路径在代码层完成（所有路径经 ${ZCODE_PLUGIN_ROOT} / os.homedir() 动态解析、通知与 SQLite 双实现有自动化测试），本机为 macOS，Windows 实机的 toast 展示未能实测——已尽自动化对比与 PowerShell 语法静态检查，如需实机回归我可以配合。

[panda920]

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

[axdlee]

补交插件图标：assets/usage-detail/icon.png（512×512，蓝紫渐变柱状图 + 绿色趋势线，风格对齐市场现有图标），marketplace.json 条目已加 icon 字段指向 CDN 规范路径，validate.py 通过（5d4fdd2）。

[panda920]

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

[axdlee]

已推送 0.15.0：侧栏面板设置可直接编辑 + 热力图小时粒度。

• 侧栏面板内直接编辑设置：panel-server 新增 App-only 工具 usage_settings_get/set（visibility: ['app']，不经模型），面板页面经 window.zcode.callTool 直调——价格、预算、通知开关在侧栏内即可修改，无需本地面板；旧版桥兜底为「打开本地面板」按钮（调 open_full_panel）替代原先的死提示。
• 配置面补全：新增「通用」区（USD→CNY 汇率 prices.usdCny、每日自动同步开关 prices.autoSync）——此前只能环境变量；null 清空汇率还原默认。配置项全景：价格/新增/删除、汇率、自动同步、日月预算、三类通知开关（权限提醒/预算告警/每轮统计三态）、userConfig（dbPath/panelLimit/quotaToken）均有 UI 入口。
• 热力图新增「小时」模式：近 7 天 × 24 小时矩阵（行=日期、列=0–23 时），四分位着色、悬停看该小时请求/token。
• 可靠性：修复 panel-server process.exit 可能在管道刷完前截断大响应（如全量价格表）的问题；测试夹具补 ZCODE_USAGE_NO_AUTOSYNC=1（原套件会真实请求 models.dev），新增 settings 往返协议用例（共 48 项测试全绿）。

[panda920]

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

[panda920]

Thanks for the contribution! This PR no longer applies cleanly on top of the latest main (conflicts in: marketplace.json). Please rebase onto main and push again; it will be picked up automatically.

🤖 Copy this prompt into Claude Code / Codex to fix it

You are updating my pull request #104 to github.com/zai-org/zcode-plugins (the ZCode plugin marketplace).
The maintainers' automated intake reported: the PR conflicts with the latest main

Conflicting files: marketplace.json

Fix it in this repository:
- New external plugins belong under external_plugins/<my-plugin>/; keep existing plugins in their current directory;
  never modify .github/, scripts/, tests/, .gitignore, .gitattributes or AGENTS.md.
- Follow CONTRIBUTING.md and AGENTS.md: the manifest lives at <plugin-directory>/.zcode-plugin/plugin.json,
  its name/version must match marketplace.json, names are kebab-case, keep the required i18n fields.
- Fetch the latest main of zai-org/zcode-plugins and rebase onto it; if marketplace.json conflicts,
  keep every existing entry and re-add mine.
- Run `python scripts/validate.py` until it passes, then force-push my PR branch.

[axdlee]

Rebased onto latest main and force-pushed — the branch is now a single clean commit on top of current main (marketplace.json conflict resolved; validate.py passes: 47 plugins OK).

Also updated to 0.15.2 with a few fixes found during real-world use:

• Side-panel settings save no longer triggers MCP App page stopped: the sandboxed iframe must not navigate (location.reload / location.href); saves now soft-refresh from the tool response. Full reload remains for the local serve dashboard (a plain browser page).
• usage_settings_get slims the price table to models seen in local usage (the synced catalog is 3400+ models / ~210 KiB, which exceeds the host's 64 KiB structuredContent cap); a query argument searches the full catalog on demand.
• The export button now works in the side panel (hands the report URL to the system browser via openExternal after ensuring the local server runs), and a new app-only usage_prices_sync tool runs the models.dev sync directly instead of asking the model to run a slash command.
• Hourly heatmap is now the default view, and its window is fixed to the last 7 natural days.

[panda920]

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