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.23.4）：ZCode 本地逐条用量分析。全部本地计算、零模型开销、数据库只读。

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

功能（v0.16.0 → v0.23.4 重点）：

• 完整仪表盘六页签（总览/每日趋势/会话排行/模型效率/请求明细/失败请求），两级钻取、排序、分页、GitHub 式热力图（日/周/月历三态）
• 界面 i18n 中英双语：跟随 ZCode 语言偏好（localePreference）或浏览器语言，可手动指定；数字单位 K/M/B（中文 万/亿）
• 多厂商配额聚合（可选）：DeepSeek / Kimi / OpenRouter / MiniMax——Key 仅存本地（权限 0600）、仅发送到对应厂商官方域名做只读查询；GLM 零密钥（客户端日志源）
• 会话健康分、浪费取证（失败/取消/重试白耗 token + Top 会话/模型）
• 预算与燃烧告警（本地常驻面板每分钟检查，80%/100% 与用量偏高系统通知，每档每日一次）；权限等待提醒（async 钩子，默认关）
• 项目用量按 git 仓库根归并（子/孙目录会话并入真实项目）；BYOK 显示用户自定义来源名（provider_config.json 只读取名称映射）
• 折算成本：GLM 5.3 系内置智谱官网权威牌价（CNY），其余模型每日从 models.dev 同步、支持峰谷分时计价（可关）
• 「本轮」实时统计横幅（MCP resources/subscribe 推送，本地计算不进上下文）；5h 计费窗口近似（ccusage blocks 同口径）；昨日筛选/文本搜索/今日预算进度卡/自动刷新；自包含 HTML 报告导出
• /usage /usage-ui /usage-this 等命令 + 本地面板（127.0.0.1，端口被占自动顺延 7742-7749）+ JSON/CSV 导出
• Windows / Linux 兼容：node:sqlite 替身（readfile + CSV）、bash 探测（Git for Windows 常见安装位置 / ZCODE_BASH）、BOM 免疫、原子写兜底

安全与隐私（相对 v0.16.0 的加固）：

• GLM 配额查询不再读取任何宿主凭据文件（provider_config.json 的 apiKey、credentials.json 的 OAuth token 均不接触）——仅使用用户显式提供给插件的凭据或零密钥日志源
• 面板 HTTP 服务增加 Host/Origin 校验（防 DNS rebinding 与跨站写）；仅监听 127.0.0.1
• CLI 参数白名单校验；价格路径 SQL 转义统一
• 无遥测；出站网络仅：models.dev 价格每日同步（可关）与用户显式配置的配额查询

测试方式：

• 仓库自带 tests/（80 项，python3 运行）：CLI 全子命令、成本公式数值断言（缓存命中不重复计费）、峰谷分时价、serve HTTP 全端点（含 Host/Origin 矩阵）、MCP 协议（tools/resources/订阅推送）、三个 hooks 行为、node:sqlite 替身与 CLI 双实现字节级一致、老 schema（无 turn_id）兼容、XSS 恶意数据实测
• 官方 scripts/validate.py 通过（47 plugins validated）

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

• 零 npm/pip 依赖（Node 内置模块 + bash + sqlite3 CLI，无 sqlite3 时自动走 node 替身）
• 只读打开 ~/.zcode/cli/db/db.sqlite；仅写自身配置/状态文件（~/.zcode/usage-*.json）
• 钩子：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 通过（47 plugins validated）；git diff --check 通过
• 中英 description / description_i18n 在 plugin.json 与 marketplace.json 保持一致
• commands/hooks 为单层目录（与 plugin.json 的 ./commands ./hooks 声明一致，旧版误为双层已修正）

[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.

[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]

更新至 v0.23.4（release candidate，自上次推送的 0.16.0 以来的主要变化）：

功能

• 界面 i18n 中英双语：跟随 ZCode 语言偏好（localePreference）/ 浏览器语言，手动可覆盖；英文数字单位 K/M/B
• 多厂商配额聚合（可选）：DeepSeek / Kimi / OpenRouter / MiniMax——Key 仅存本地（0600）、仅发对应厂商官方域名只读查询；GLM 零密钥日志源
• 项目用量按 git 仓库根归并（子/孙目录会话并入真实项目）；BYOK 自定义来源名显示（只取名映射）
• 5h 计费窗口近似（ccusage blocks 同口径）、峰谷分时计价、昨日筛选、会话/模型/来源文本搜索、今日预算进度卡、自动刷新、自包含 HTML 报告导出
• 本地面板端口顺延（7741 被占自动 7742-7749）；Windows/Linux 兼容层（node:sqlite 替身、bash 探测、BOM 免疫、原子写兜底）

安全与隐私加固

• GLM 配额查询不再读取任何宿主凭据文件（provider_config.json 的 apiKey、credentials.json 的 OAuth token 均不接触），仅用显式配置凭据或零密钥日志源
• 面板服务加 Host/Origin 校验（防 DNS rebinding 与跨站写）；CLI 参数白名单；价格路径统一 sql_quote

质量

• 测试 44 → 80 项全绿（成本公式数值断言、HTTP 端点矩阵、MCP 协议、钩子行为、替身与 CLI 双实现字节级一致、老 schema 兼容、XSS 恶意数据实测）
• scripts/validate.py 通过（47 plugins validated）
• 修正 commands/hooks 双层目录为单层（与 plugin.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.

[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]

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

[axdlee]

已将 usage-detail 更新到 0.30.3（0.23.5 → 0.30.3，十个版本累计）。

主线更新——上下文洞察（对齐社区标杆 dsh-context 的观测+下钻能力）：

• 会话下钻：上下文构成环（对话/推理/工具/骨架/附件按本地字节近似）、当前上下文 hero 卡、耗时构成环、Agent 团队行（子代理按 parent_id 归属主会话）
• 上下文浏览器：五类内容（对话/推理/工具调用/压缩/附件）类别行展开逐条摘要，按字节排序定位上下文大头；近 1h 增量绿标；条目点击展开全文（工具调用渲染为参数 KV 表，容错解析截断 JSON）
• Fleet 子代理并行时间轴：泳道 Gantt，条可点击跳转该子代理请求明细
• 水位曲线：压缩事件 trigger 标注、超窗请求红点、Level/Delta 切换

稳定性（三轮十五遍复审）：

• 全新环境冷启动（无库/0 字节库）直接出空数据页，不再报错
• 协议对抗/竞态/边界库矩阵（含 XSS 探针）/静态检查/三端语言 e2e 全过

安全边界不变：SQLite 全程只读、本地面板仅监听 127.0.0.1、无遥测、绝不读取凭据文件。

[panda920]

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