[AwenJackson]

插件类型（必填）

• 普通插件（非 UI） —— 本插件不提供 MCP Apps 交互页面（无 ui.surfaces / _meta.ui.resourceUri），组件包括 command（/remove-sidebar-widget）、SessionStart hook、以及由主进程注入器驱动的前端脚本
• UI Plugin
• 不适用

涉及插件：balance-dashboard（普通插件，非 UI）

改动解决的问题

ZCode Desktop 没有任何余额/用量视图：DeepSeek 余额、火山引擎（账户 + Coding Plan）额度、ZCode 套餐占用与本地 token 消耗分散在各家控制台。本插件在左侧边栏提供一个紧凑的余额组件，并附带多维度消耗分析。

用户可见行为与测试方式

• 侧边栏头像行上方出现余额卡片：每行显示余额/套餐 + 今日消耗（费用 + token），可在设置弹框中开关每行、未接入的供应商自动隐藏；
• 点击任意余额行打开消耗分析弹框：今天/昨天/本周/本月/自定义日期，项目/任务/供应商过滤，堆叠柱状图（Token/费用切换）、供应商占比、Top 模型、项目/任务排行；
• 点击齿轮打开设置弹框，可直接填写 DeepSeek API Key、火山 AK/SK、ZCode JWT 等，保存后立即刷新；
• 复现步骤：安装 → 完全退出并重开 ZCode → 查看侧边栏 → 点击余额行/齿轮；
• 已在 ZCode Desktop 3.18.2（Windows）实际运行并截图验证（组件位置、两行布局、弹框、深浅色主题、popover 期间不消失）；仓库内 python scripts/validate.py 通过（OK: 55 plugin(s)），build_zip 对本插件单独构建 zip 成功（17 个文件，完整性校验通过）。

版本与市场注册

• external_plugins/balance-dashboard/.zcode-plugin/plugin.json：version 0.3.0；
• 根 marketplace.json 新增条目：name/version/描述与 manifest 一致，category utilities；
• 首次提交，无历史版本复用。

依赖、网络请求、权限和副作用（全部披露）

• Hook（SessionStart）：同步运行时文件到 ~/.zcode/balance-dashboard/runtime/，检查 resources/app.asar；
• 修改 app.asar：ZCode 插件系统没有左侧边栏挂载点，插件在 out/main/index.js 末尾追加一行本插件专属的动态 import()。安全性措施：重打包前保存原始 offset；替换后对全部条目逐文件重算 SHA-256 + 4MB block hash 并与 header 比对，全部通过才替换；替换前自动备份 app.asar.balance-dashboard.bak，替换后再次校验失败自动回滚；每条替换路径（session-start / finalize / post-patch）都先校验 stage；/remove-sidebar-widget 命令或 scripts/unpatch.mjs 可完整还原，且保留其他插件（如 token 用量悬浮条）的注入行。此能力与已收录的 zcode-token-usage-statusbar 社区插件采用相同机制；
• 本地文件写入：仅 ~/.zcode/balance-dashboard/runtime/；
• 网络请求（仅官方域名，无遥测）：api.deepseek.com；billing.volces.com / ark.cn-beijing.volces.com 签名接口；zcode.z.ai、api.z.ai / bigmodel.cn；
• 命令执行：hook 与注入器以子进程调用 node 执行插件自带脚本；
• 凭据：存于 ZCode 插件配置或本机 options.json（明文，与 ZCode 自身 plugin-secrets.json 同级），仅本机读取，不写日志、不上传；README 与 PR 均已说明；
• MCP server：无。

第三方材料来源与许可证

• 全部代码为本插件原创，MIT License（插件目录 LICENSE）；
• 无第三方代码、素材或服务依赖；运行时依赖为 Node.js 内置模块（node:sqlite、node:crypto 等）与 ZCode 本体；
• 未提交任何密钥、私有地址、客户数据或机器专属路径。

自查清单

• 已勾选插件类型并列出插件名称
• 插件名唯一且为 kebab-case
• 必需文件与中英文 README 均已提供
• 分类填写正确（utilities）
• 未提交密钥、私有数据或机器专属路径
• validate.py 通过；build_zip 对本插件单独构建通过（完整 build_dist.py 在本地浅克隆上因 excalidraw 缺少 pnpm 构建产物无法整体运行，与本 PR 无关）
• 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.