这份文档面向需要自定义安装、远程查询或彻底清理的用户。日常使用通常不需要改配置文件。
当前正式版：
#plugin-releases正式渠道（核对 2026-10-31：v1.5.7）自动安装/修复状态条，始终开启、不再提供配置开关（旧配置里的plugin_auto_install_overlay与环境变量ZUSAGE_PLUGIN_AUTO_INSTALL已不被读取）；只需要查询工具与回答速率时运行/uninstall-overlay移除并保留卸载豁免。安装/修复会修改客户端app.asar，请确认信任此项目；成功后需完全退出并重开。
- 桌面客户端：推荐通过 ZCode 插件安装，可选择远程市场或本地目录。插件管理查询、回答速率与更新，自动安装/修复状态条（始终开启，没有配置开关），成功后需完全退出并重开。也可以使用下方的一键安装器；两者共用运行目录与注入行，无需重复安装。
- 自托管网页：按 Web 版文档 部署，不能用桌面安装器给浏览器页面添加状态条。
- 官方云端网页：本仓库的 Web 方案需要你控制服务器与 nginx，不适用于官方托管页面。
桌面版需要 Python 3.8+，不需要额外 Python 包。支持 Windows、macOS；Linux 系统级路径可能需要管理员权限，界面与发行版兼容性需自行验证。
通过客户端界面操作，无需系统 PATH 中有 zcode：
- 打开 设置 → 插件 → 添加插件市场；某些版本入口在「发现」页的 +。
- 输入
https://github.com/ByteRax/zcode-token-usage-statusbar#plugin-releases，添加市场。 - 找到 ZCode Token Usage Statusbar，安装到用户范围并启用。
GitHub 访问受限时，第 2 步改用 GitCode 渠道地址（结尾 .git 不能省，本机需装有 Git）：
https://gitcode.com/tanranran/zcode-token-usage-statusbar.git#plugin-releases-gitcode
两条渠道提供同一份经过校验的正式 Release；注册哪个地址，之后的版本检查和下载就在哪个渠道进行，⚙ 面板的「更新来源」会显示当前渠道。
此渠道从经过校验的正式 Release ZIP 安装插件，不跟随开发分支，也不需要自己下载源码。当前正式版自动安装/修复状态条（始终开启，旧自动安装开关配置只保留不再读取）；成功后完全退出并重开；不需要状态条时用 /uninstall-overlay 移除并阻止自动重注入。
从 ByteRax 仓库 下载或克隆源码后：
- 打开 设置 → 插件 → 添加插件市场，点击 选择目录。
- 选择包含
marketplace.json的仓库根目录（不是plugins/子目录），添加市场。 - 找到 ZCode Token Usage Statusbar，安装到用户范围并启用。
「按 README 的方式 A（远程市场）装完却什么都没有」先分清是插件没装上，还是状态条没注入：注册市场和安装插件这两步失败时可能不留任何痕迹。市场注册要从注册地址克隆仓库，国内直连 GitHub 超时就会卡在这一步，失败提示也未必醒目——没看到报错不等于成功了。逐项核对：
- 市场注册：默认位置
~/.zcode/cli/plugins/known_marketplaces.json含zusage-marketplace，设置 → 插件里能看到该市场（宿主使用自定义插件存储时以实际位置为准）。 - 插件安装：默认位置
~/.zcode/cli/plugins/installed_plugins.json含zcode-token-usage-statusbar@zusage-marketplace，插件页显示已安装并启用。 - 状态条注入：新建或恢复会话触发自动安装，成功后完全退出并重开 ZCode；有仓库克隆的话可用
overlay_install.py check确认注入状态（见排查）。
前两项任一缺失，重启和 /install-overlay 都救不了——那是「零痕迹 + 状态条不出现」的形态，先重新走方式一：GitHub 直连超时的机器注册 GitCode 镜像渠道，两条渠道装的是同一份经过校验的正式 Release。
安装插件后，按宿主提示加载插件，新建或恢复会话；装插件时已开着的会话不会补触发启动钩子。插件自动安装/修复状态条（始终开启，没有配置开关），会修改客户端的 app.asar，请确认信任此项目。成功后必须完全退出并重新打开 ZCode；只关闭窗口不一定退出主进程。
自动安装失败时，再手动执行以下兜底命令，按实际输出排查；成功后仍需完全退出并重开：
/install-overlay
自动安装始终开启：新建或恢复会话时只要状态条未注入就会自动安装/修复，不再提供开关（旧配置里的 plugin_auto_install_overlay 与环境变量 ZUSAGE_PLUGIN_AUTO_INSTALL 已不被读取）。只需要查询工具与回答速率时，运行 /uninstall-overlay 移除状态条并保留卸载豁免，阻止自动重注入与提示。
Windows 找不到 python3 时插件 hook 会自动回退：hook 命令按 python3 → python → py -3 依次尝试，无需改文件。stdio MCP 同样自动适配：.mcp.json 以 node 启动包内 mcp-launch.cjs（桌面 ZCode 3.17.1 起给 stdio MCP 子进程的 PATH 末尾追加 Electron Node 的回退 shim，未装 Node 的机器也能解析 node；更旧的桌面版或其它无此机制的宿主需要本机装有 Node），由它按同一顺序 python3 → python → py -3 实测探测解释器后拉起 usage_mcp.py 并透传 stdio——macOS 无 python、Windows 无 python3、Microsoft Store 的 python 占位桩（只有执行才能与真实安装区分）都由探测排除，任何平台都无需手工改文件。三个候选全部不可用时 MCP 连接失败并在错误详情里提示安装 Python 3.8+；只用状态条与 /usage 时不受影响。
plugin-releases 分支 的市场清单指向当前正式 Release。新用户请在添加市场界面使用 https://github.com/ByteRax/zcode-token-usage-statusbar#plugin-releases，具体版本以该清单为准。
GitHub 访问受限时可注册 GitCode 镜像渠道 https://gitcode.com/tanranran/zcode-token-usage-statusbar.git#plugin-releases-gitcode：清单由同一份发布产物生成，ZIP 与 SHA256 和 GitHub Release 完全一致，版本检查、下载与安装全部在 GitCode 完成。该渠道要求本机装有 Git（宿主通过 git 拉取渠道清单）。
清单指向正式 ZIP，包含 SHA256 与插件子目录；下载时核对 Release manifest、版本与包内容，安装后再复核宿主安装记录与所选 Release 一致。后续正式版本仍需维护者同步发布渠道清单：Release 已发布而渠道清单尚未更新的几分钟内，宿主按旧清单安装不会前进到新版本，更新会报「插件管理器未提交新版安装记录」，稍后再点即可。
默认 main 的市场清单仍用于源码安装，本地目录也保持原用法；不要把正式渠道清单复制到自己的源码根目录。私有仓库认证下载和 GitHub/GitCode 之外的远端自动更新不支持。发布操作见 维护文档。
市场名仍是 zusage-marketplace，但来源从默认分支/本地目录变为 #plugin-releases。已安装用户不会自动切换，也不必为了添加分支卸载浮层。 想迁移时：
- 先关闭插件自动更新，等待正在进行的更新结束，记下现有市场来源。
- 打开 设置 → 插件 → 发现 → +（添加插件市场），填写
https://github.com/ByteRax/zcode-token-usage-statusbar#plugin-releases。通过市场管理确认并切换同名市场来源；不支持同名来源替换时，先移除旧市场注册再添加正式地址，无需卸载插件或浮层。 - 在市场管理中确认
zusage-marketplace指向新地址，来源的ref为plugin-releases，再刷新市场并在插件页按需更新。不要只看到插件已安装就假定来源已切换。 - 确认正式包可读取后，按自己的偏好开启自动更新。更新涉及主进程文件时，完全退出并重开 ZCode。
如果客户端版本不支持同名来源替换，可先移除旧市场注册再添加正式地址；移除市场与卸载插件是不同操作。不要执行卸载命令来替代来源迁移。
要从 GitHub 渠道迁到 GitCode 镜像渠道（或反向），用同样步骤把来源地址换成目标渠道即可；迁移前后插件版本相同，无需重装，迁移后 ⚙ 的「更新来源」显示新渠道即成功。
迁移操作须由你明确选择；本项目不会静默修改个人市场注册、删除设置或移动本地源码。
不通过插件时，先安装 Python 和 Git，在系统终端执行：
git clone https://github.com/ByteRax/zcode-token-usage-statusbar.git
cd zcode-token-usage-statusbar
python install.pymacOS 可改用 python3。成功后完全退出并重开 ZCode；只关闭窗口不一定退出主进程。
安装器会定位客户端、复制运行文件、保留或生成设置、安装状态条、注册查询工具和 /usage。安装监控会提示重启并确认是否加载；Windows 文件被占用时，可能要退出后才完成替换。
推荐指定安装目录：
# Windows 示例
python install.py --root "D:\Apps\ZCode"
# macOS 示例
python3 install.py --root /Applications/ZCode.app也可传 --asar <app.asar 完整路径> 或设置环境变量 ZCODE_ASAR。自动探测只采用确认属于 ZCode 的目标，首次安装后会保存位置；Windows 会依次探测用户目录、%ProgramFiles% 与各本地固定盘的 Program Files\ZCode、<盘>:\ZCode 等常见布局（如 D:\Program Files\ZCode 也能自动找到；网络盘和可移动盘不扫描，装在那里请用 ZCODE_ASAR）。
| 选项 | 用途 |
|---|---|
--lang en |
安装器、CLI 和查询报表使用英文 |
--no-mcp |
只安装状态条，不再注册查询工具和 /usage；适合查询已由插件提供的情况 |
--dry-run |
预览安装动作，不实际安装 |
--dev |
开发模式，直接引用仓库文件；此时不能删除或移动仓库 |
--remove |
移除注入、独立注册的查询工具、/usage 和运行目录；不等于卸载 ZCode 插件 |
正式渠道可在 ⚙ 检查或安装更新，也可以按以下步骤手动更新：
- 远程安装无需更新本地源码；本地目录安装需先自行获取最新源码。
- 打开 设置 → 插件，在市场管理中刷新
zusage-marketplace。 - 到 已安装 更新 ZCode Token Usage Statusbar。
- 新建或恢复会话；若提示主进程文件变化，再完全退出并重开 ZCode。
本地目录市场不会执行 git pull。ZCode 使用的是独立安装副本，修改仓库不等于完成插件更新。
状态条 ⚙ → 插件更新 还提供「检查更新」「立即更新」和「自动更新」：
- 检查更新不会安装；发现新版后可点「立即更新」。
- 自动更新默认开启，客户端运行时按上次尝试时间间隔 1 小时检查，有新版才安装；首次运行或距上次尝试已满 1 小时，在下一次调度时检查。你显式关闭的设置会保留，手动检查不受此间隔限制。
- 更新器属于主进程代码，检查间隔变更需加载新版更新器后生效：更新安装副本和运行文件后，完全退出并重开 ZCode。关闭或休眠期间不保证检查，恢复运行后到期补查，不保证整点执行。旧版本首次发现此更新仍按原检查间隔；运行文件因本地热修被保留时，重启也不会自动替换它。
- GitHub/GitCode 来源按市场清单分两条链：清单指向正式 Release ZIP（
#plugin-releases/#plugin-releases-gitcode）时走 Release 校验链；清单指向仓库源码（默认分支）或本地目录时没有可校验的 Release，更新交给宿主插件管理器按市场清单直接完成（marketplace update→ 插件更新），不经过发布包 SHA256 校验，⚙ 的「更新来源」会写明「仓库源码」或「本地目录市场」。新远程安装仍建议使用#plugin-releases。 - GitCode 渠道的版本检查读宿主从注册 ref 拉取的渠道清单，ZIP 从 GitCode Release 资产下载并按 Release manifest 核对 SHA256，安装后复核安装记录与所选 Release 一致。
- 更新代码会访问已注册来源，不上传用量数据；来源错误或网络失败会显示原因。
- 更新日志：更新卡片下方新增「更新日志」卡片，显示与当前更新状态对应版本的 Release 说明（待重启=实际安装的版本；有新版=目标版本；已是最新=当前版本；更新失败=失败目标并标注未安装成功）。GitHub/GitCode 正式 Release 渠道与源码渠道均在线获取：源码渠道取注册仓库的同号 Release 正文作参考（明确标注「未核实与本渠道一致」），历史版本按钮可按需查看最近 20 个正式版本；本地目录渠道无仓库身份，不联网显示。正文为受限渲染（脚本与图片禁用，链接仅 https），按来源仓库缓存 1 小时；拉取失败不影响检查更新、立即更新或重启操作。
- 只支持本插件的用户级安装；不会替你启用已禁用的插件。
自动或手动更新成功后，都需按提示重开会话或重启客户端。
客户端升级可能覆盖 app.asar。插件默认在新建或恢复会话时自动修复，成功后仍需完全退出并重开 ZCode；自动修复失败时，再运行 install-overlay 或 python install.py 兜底。
macOS 上若 ZCode 自更新已把新版本安装包下载到本地待装缓存，主进程会抢先给更新包内的 app.asar 补上注入行（pending_zip_patch，默认开；客户端版本在渲染桥指纹表内时一并补桥）——「重启以更新」后状态条一次生效，省掉自动修复后的第二次重启；Windows 的更新安装包带签名校验，不适用此机制，仍走会话启动自动修复。
自动修复始终开启（旧配置里的 plugin_auto_install_overlay 键与 ZUSAGE_PLUGIN_AUTO_INSTALL 环境变量已不被读取）。只想查询、不希望自动修改客户端时，运行 /uninstall-overlay 写入卸载豁免。它独立于 plugin_auto_update：关闭插件更新并不会关闭客户端自动安装/修复。
自动修复不会直接调用斜杠命令，而是在启动钩子中执行同一个安装器；SessionStart 覆盖新建和恢复会话（startup|resume），清空后新会话走 startup，不依赖独立 clear 事件。宿主 schema 接受 clear，但当前没有独立事件派发。
自动修复后仍需完全退出并再次启动 ZCode。更新包含需重启的文件时，状态条 ⚙ 齿轮与 ⚙ 面板「插件更新」项会显示红点，点进「插件更新」分区后消失（更新成功且无需重启——浮层已自动热重载——不显示红点；带红点点击 ⚙ 会直接打开「插件更新」分区）；该分区显示「已更新成功，点击重启 ZCode 即可生效」提示条，也可以直接点「重启 ZCode」按钮（需再次点击确认）。点击确认后按钮立即显示「正在重启…」并禁用，状态区提示已发出重启请求（等待会话与扩展子进程退出，通常几秒到几十秒）；重启回执送达后全部窗口隐藏作为退出反馈（渲染端无响应时由 800ms 兜底同样隐藏）；若 4 秒无回执、请求失败或 90 秒后仍未退出，按钮自动恢复并可再次点击或按提示手动完全退出；隐藏的窗口由主进程在退出失败或超时后自动恢复显示。浮层脚本可热更新而主进程代码只在启动时加载一次：更新落盘后、完全重启前的窗口期里，正在运行的主进程还是旧版本，「重启 ZCode」按钮不可用（主进程不支持重启指令时按钮隐藏），更新状态区改为手动退出指引；点击后若收到「主进程是旧版本」的回执也是同一含义。插件不会自行重启，也不再在会话中注入文字提醒（自动安装失败的故障提示除外）；不想看到红点可在 ⚙ 面板或配置中设置 restart_notice: false。插件未启用、启动钩子没触发、无写入权限或客户端结构不兼容时，自动修复不能保证成功。
卸载产生的 .plugin-overlay-optout 会阻止重注入；删除它表示恢复参与自动安装/提示，而不是立即执行安装。
git pull
python install.py状态条脚本和查询库通常可热更新；主进程文件、首次注入或安装目录改变时需重启。已安装文件的本地手改会受到插件同步保护，未覆盖内容会提示，不应为了升级直接删除个人配置。
优先用状态条的 ⚙ 调整。需要直接编辑时，默认位置是：
~/.zcode/zcode-token-usage-statusbar/config.json
Windows 对应用户目录下的 .zcode\zcode-token-usage-statusbar\config.json。下面是常用设置示例，只修改需要的字段，保留现有配置：
{
"lang": "zh",
"answer_rate_line": true,
"restart_notice": true,
"quota_enabled": true,
"reset_badge_enabled": true,
"plugin_auto_update": true,
"context_window": 1000000
}| 字段 | 说明 |
|---|---|
lang |
zh / en，查询报表语言 |
python_path |
Python 可执行文件；安装器会设置，无法启动 Python 时检查 |
hot_reload |
状态条脚本热更新：缺省开（约 5 秒检查一次）；显式 true 加速到 2 秒（开发改脚本时用），false 完全关闭（改文件需重启 ZCode 才生效）；检查间隔在启动时读取，改动需重启 |
diag |
定位诊断文件（运行目录 diag-<n>.json，约每 15 次拉取落盘），默认开；显式 false 关闭常驻诊断写入，需要排查问题时设回 true 或删掉该键 |
answer_rate_line |
插件回答末尾的统计行，默认开。面板切换会立即重扫：关闭撤下插件生成的行，开启补回可用记录；下一问沿用该设置，历史正文和缓存数字不重算 |
restart_notice |
待重启的红点提醒，默认开：更新包含需重启的文件时，状态条 ⚙ 齿轮与 ⚙ 面板「插件更新」项显示红点，点进「插件更新」分区后消失；更新成功且无需重启（自动热重载）不显示红点（⚙ 面板「更新后在状态条显示红点提醒」同一开关）。显式 false 关闭红点；/install-overlay 的命令行输出、自动安装失败的故障提示不受它控制，异常值视为开启 |
quota_enabled |
套餐额度 chip（BigModel / Z.ai 个人编码套餐、ZCode Start Plan 免费档），默认开（显式 false 关闭）。建议用 ⚙ 面板开关而不是手改：主进程读取凭据查询套餐/余额接口（仅内存使用、不落盘、不进日志与诊断）：内置套餐走 ZCode 登录凭据（bigmodel.cn / api.z.ai，Start Plan 走 zcode.z.ai）；自定义供应商余额用其自己的 key，只发官方域（api.deepseek.com、openrouter.ai、api.siliconflow.cn、api.minimaxi.com、api.kimi.com、api.commandcode.ai、api.cline.bot、api.anthropic.com、platform.xiaomimimo.com、open.volcengineapi.com、opencode.ai 等）或你配置的中转站本域；⚙ 面板可为各数据源（MiniMax/Kimi/Cline/Anthropic/MiMo/火山/SCNet/OpenCode 等）单独配置凭据与开关（保存在运行目录 quota-secrets.json，0600）。套餐额度是账号级套餐池口径，不是单模型额度；BigModel 悬停还显示套餐名/版本与周期（自动续费显示"下次续费"，非自动续费显示"有效期至"；无法确认当前周期时不显示日期）；Start Plan 悬停显示套餐名、套餐池已用百分比与到期时间（选中 Start Plan 档位时 chip 显示该池，不与编码套餐池混用）；团队套餐暂不支持，未配置凭据/形状不支持的源 chip 显示中性「额度 未配置／额度 暂不支持」提示。chip 默认显示各窗口的已用比例；⚙ 面板「显示剩余额度」开关（默认关，纯渲染端偏好存 zusage3.quotaRemain，不写配置文件）切换为剩余口径：剩余% = 100 − 已用%（同一额度窗口的补数），chip 面分段、悬停明细与读屏文案跟随，段位颜色仍按已用量判定（剩得越少越红）；账户余额与 Key 剩余额度本身是剩余口径，不受该开关影响 |
reset_badge_enabled |
重置卡徽标（v135：额度 chip 左侧「重置 · N」，多账号张数 + 连接），默认开（显式 false 关闭）。独立于 quota_enabled：关闭额度 chip 后本开关开启时主进程仍解密登录凭据、仅查询官方 reset/status 只读接口（zcode.z.ai，与登录凭据同域）维护徽标。悬停徽标显示每账号 5 小时卡/周卡的张数与到期时间（yyyy-MM-dd HH:mm），并列出服务端返回的近 7 天已过期记录与上次重置时间（BigModel 账号；数据由网页控制台同款列表接口提供，接口未返回时不显示）；剩余 >3 小时绿、3 小时–30 分钟黄、<30 分钟红并呼吸闪烁；剩余时间短于阈值（⚙ 面板可配，默认 24 小时）时在徽标上显示倒计时。需要 ZCode 登录态；仅 API Key 用户与团队套餐无重置卡。每 5 分钟查询一次（BigModel 账号开启列表补充后每周期并行查 status 与列表两个接口），倒计时为本地推算 |
auto_compact_patch |
自动压缩上下文阈值注入（v179；v188 起默认开，显式 false 关闭）。开启后主进程给客户端引擎 glm/zcode.cjs 打阈值改道补丁：按引擎构建 SHA256 白名单，不支持的版本拒绝注入并在 ⚙ 明示（v225 起区分「引擎文件被单独热更」：客户端 build 仍在白名单而引擎 sha 脱钩时，明示热更事实与漂移 sha 前 12 位，便于反馈维护者加快登记；fail-closed 拒注入判定不变）；关闭开关按当前内容反向还原引擎。补丁把「到达阈值自动压缩上下文」的触发点变为可配置（引擎内置 ≈ 窗口 − 21K 输出预留 − 13K 缓冲，200K 窗口约 83%）。阈值百分比存运行目录 autocompact.json（v188 起 ⚙ 只暴露百分比，留空=跟随引擎默认；enabled:false/thresholdTokens/bufferTokens 引擎层协议保留，配置文件手写仍生效），引擎每轮决策读取（mtime 缓存）——数值改完下一轮即生效；补丁本身冷生效（已运行 agent 子进程保持旧阈值，新会话/重启客户端后生效）。百分比 v194 起以总窗口为基准（30-99）：设置 91 即原生上下文按钮走到 91% 时触发（旧口径按扣除输出预留后的有效窗口计算，与显示差约 2 个点）；引擎按有效窗口 +21K 近似还原标称窗口，任何形式都会被钳到不早于有效窗口的 1%、且不晚于有效窗口，避免连环压缩触发熔断中断回合。改百分比的 ⚙ 数值行只接受 30-99。只影响桌面客户端内置引擎，终端 CLI 不受影响 |
pending_zip_patch |
macOS 更新包预注入（默认开，显式 false 关闭）。ZCode 桌面自更新把完整安装 zip 下载到本地缓存（sha512 只在下载完成时校验一次，安装前不再复验），主进程监测到待装包且版本高于当前客户端时，抢在安装前给包内 app.asar 补上注入行（版本在渲染桥指纹表内时一并打桥），「重启以更新」后状态条即生效，省掉会话自动修复后的第二次重启。只改更新包文件本身、绝不改写其元数据（那是宿主缓存有效性的判据，改了会触发反复重新下载）；改动先写临时文件、提交前核对锚点，任何失败保留原包，由会话启动自动修复兜底。Windows 安装包带 Authenticode 验签，不适用；本机制不联网，只处理已下载到本机的缓存 |
plugin_auto_update |
插件自动更新，默认开；损坏或非布尔配置不会启动更新 |
pricing |
预估费用（v202）数据链配置，整块可省略：fetch（默认 true）设 false 彻底关闭价表/汇率联网同步（已落盘的缓存仍参与显示）；url 覆盖价表源（默认 https://models.dev/api.json）；fx.url 覆盖汇率源（默认 https://open.er-api.com/v6/latest/USD，响应须含 rates.CNY 数值；仅使用默认主源时，失败会按序兜底到公益源 https://api.exchangerate.fun/latest?base=USD，显式配置的源失败即失败、不擅自换源）。同步在常驻查询进程内每 12 小时一次（启动时缓存超期才拉，超时 10 秒、失败静默保留旧值），结果落运行目录 pricing-cache.json；一次性 CLI（json 子命令）只读不联网。费用在悬停本轮/会话累计/项目累计/今日合计的 tooltip 里按 models.dev 官方模型价格估算（内置 326 条随插件发版），USD 计算、按拉取汇率折 ¥ 显示，无有效汇率显示 $ 原值；匹配不到模型价格的模型按默认均价（$1/$5 每百万）估算，⚙ 通用区「预估费用」开关只门控显示 |
context_window |
自动识别失败时的上下文窗口大小兜底 |
resident |
使用常驻 Python 查询进程，默认开 |
activity_min_ms |
活跃期最小查询间隔，默认 1500ms |
heartbeat_ms |
文件事件丢失时的兜底检查间隔，默认 30000ms |
配置是 JSON，不能直接粘贴带注释的示例。
ZCode 引擎会在上下文接近窗口上限时自动把会话历史总结压缩（auto-compact），内置触发点不可配置。本插件的 ⚙ 面板提供「自动压缩上下文阈值注入」开关（默认开启，显式关闭需在 ⚙ 关掉）：
- 开启：主进程按引擎构建白名单给客户端引擎打补丁，状态行显示注入结果（已注入 / 版本不支持 / 文件被占用等）。补丁对新会话生效，已运行的会话保持旧阈值。
- 阈值百分比：压缩触发点占总窗口的比例（30-99，与原生按钮/hover 阈值行同口径）；留空 = 跟随引擎默认。v188 起 ⚙ 只暴露百分比；
enabled:false（禁用自动压缩，超窗兜底仍在）、thresholdTokens、bufferTokens引擎层协议保留，需要时可直接编辑运行目录autocompact.json。 - 即时生效：数值由引擎每轮决策时读取，改完下一轮就生效，无需重启；⚙ 里目标低于当前用量会给出警告。
- 上下文按钮悬停面板：补丁生效时显示「自动压缩 ~X%」当前生效线。
- 还原：关闭开关即按当前内容反向还原引擎字节（开关默认开启；显式关闭后不再打补丁）。
仅影响桌面客户端内置引擎；终端 CLI 不受影响。客户端升级后若新引擎版本尚未登记支持，注入自动停用并在 ⚙ 明示，等待插件更新。
在桌面状态条的 ⚙ → 状态条显示 → 状态条样式 中选择「默认」「药丸」或「精简」；默认使用原有样式。切换在同一窗口的各分栏即时生效，不承诺跨窗口即时同步。
样式为「默认」时，样式选择下方会显示 水平对齐 三选一（均分对齐 / 居左对齐 / 居右对齐，默认均分）：均分把各格铺满整条，居左/居右把各格靠一侧聚拢，⚙ 齿轮始终在最右。该设置仅对默认样式生效，药丸与精简不受影响；条面内容超宽时三种对齐都按原有策略分级收缩、右缘渐隐。
「状态条显示」中的六个格开关（本轮 / 会话累计 / 项目累计 / 工具调用 / 今日合计 / 子代理）全部关闭时，样式自动转为「精简」（当前为默认或药丸时都触发）；重新打开其中任一格，自动恢复进入精简前的样式。在面板手动改过样式即解除自动切换，此后不再自动干预。
本地辅助对话（划词侧栏会话）有自己的独立状态条，与主窗口分栏互不挤占（最多 4 个主分栏 + 当前可见的 1 个辅助对话）；会话数据按该辅助会话自身口径计算，项目累计和今日合计仍分别使用项目及全局口径。回答末尾统计行与主会话同一链路（仅统计当前活跃轮）。面板收起或切换标签时对应状态条随之隐藏或切换；远端或身份不明时不展示辅助会话数据。
「药丸」位于所属输入框下方居中，宽度随内容变化、窄窗受约束。圆角、边框与背景随所属输入框的实际界面主题及悬停、聚焦、Highspeed 状态变化，不复制粒子动画。药丸条面会精简，次要信息保留在提示中；token 数量单位沿用现有设置。额度的已用口径不变；额度、Git、重置卡、原生上下文界面和设置面板不因样式切换而改变。
「精简」隐藏整个悬浮状态条，信息直接展示在输入框工具行：生成速度变为工具行前导区的速率图标（Git 状态 chip 左侧；工作区不是 Git 仓库时位于「电脑操作」按钮旁），悬停可查看速度读数、状态条各格摘要（本轮/会话累计/今日合计/项目累计/工具调用/子代理，受 ⚙ 显示项开关控制，子代理行可点击打开明细）并打开设置；重置卡、套餐额度、剩余额度与 Git 状态照常显示在工具行（Git 仍在前导区，需工作区是 Git 仓库）。会话没有有效速度样本时（如新会话未发消息）速率图标不显示，此时也没有设置入口——发一条消息即出现。Web 版在 ⚙ → 通用 中选择「默认样式/精简模式」：速率与上下文容量图标挂在发送按钮左侧。
token 数量单位默认跟随 ⚙ → 通用 →「中文单位（万/亿）」 开关（仅中文界面生效）。⚙ → 通用 →「强制 K/M/B 单位」（默认关闭）开启后，状态条、tooltip 与回答末尾统计行的 token 数量按 K/M/B 格式显示，不受界面语言与该开关影响；已缓存的历史统计行保持旧格式。请求数、工具数和 Git 状态 chip 的变更计数不属 token 数量，仍跟随「中文单位」开关。该设置即时应用于当前窗口的分栏；其他已打开窗口需重新加载后读取。更新本功能涉及主进程，安装后需完全退出并重启 ZCode，回答末尾富文本才使用新格式。
状态条的统计卡（本轮 / 会话累计 / 项目累计 / 工具调用 / 今日合计 / 生成速度）与子代理面板默认鼠标悬停立即显示。若常被鼠标滑过误触遮挡，可在 ⚙ → 通用 →「点击激活悬浮窗口」（默认关闭、纯渲染端偏好存 zusage3.tipClick）打开：统计卡与子代理面板改为点击格子才打开，再点同一格（首击后稍候）或按 Escape、移出条面即收起；点开后需点击另一格切换内容，悬停不再自动切换。两种模式下键盘 Tab 聚焦格子都即时打开，不改变无障碍行为。
工具栏上的额度 / Git / 速率 / 重置卡等 chip 的提示，以及宿主原生的「上下文容量」面板不在此开关范围内（前者是独立的小提示，后者延迟由宿主控制）。Web 版为独立实现，桌面设置不作用于 Web。
本节远端适配与恢复功能已随正式 Release 发布。本机必须加载当前安装副本与运行文件，完成状态条安装或修复后完全退出并重启 ZCode；只修改仓库不会更新已安装副本，只关闭窗口不算退出。
桌面连接 SSH、WSL 或 Docker 远端 ZCode 时，数据在远端。支持的是桌面状态条的 JSON 查询链，不是把所有命令都变成远端命令：MCP、/usage 和回答末尾速率不自动跨机，纯 CLI 没有状态条 UI，自托管 Web 仍按独立文档部署。
- 自动连接适配：读取客户端保存的远端工作区连接设置（默认
~/.zcode/v2/setting.json的lastWorkspaceSession），按条目里的target.kind生成可用通道：SSH 生成ssh -o BatchMode=yes …，WSL 生成wsl.exe -d 发行版 [-u 用户] --exec …（发行版缺省时不带-d、走 WSL 默认发行版），Docker 生成docker exec -i 容器 …（后两类无需凭据即可免交互）；结合宿主合法工作区 IPC 与本窗口会话证据取得workspaceIdentity。客户端 3.15.x 的 WSL 工作区身份是remote:wsl:发行版[:用户]:/路径；3.16 起所有传输连接握手后统一升级为remote:server:<serverId>:/路径，该身份记在sourceServerWorkspaceHistory，而lastWorkspaceSession持久化的仍是传输级 legacy 身份与{kind, distro, user}——插件按归一路径把 server 身份并进对应传输通道（同路径命中多个服务器或多条通道视为歧义，不并），两种客户端形态都覆盖。 - 多服务器路由：以会话 ID 和工作区身份共同选目标，不仅凭 ID、主机标签或远端最近活跃会话猜测。自动模式只查询已确认远端 scope，不对历史服务器试探本地未知会话 ID。手动目标用
identity或identities绑定工作区，可覆盖同身份的自动目标。 - 独立 today/error：各目标独立返回今日总量与错误，不能把某服务器的今日量混入本地或另一服务器；一台不可达不应中断其它来源查询。相同会话 ID 仍需按工作区/目标隔离。
- 失败与未知持续重试：查询失败、远端暂未找到会话或尚无可信身份时不会永久放弃；已知远端 scope 保持退避重试，身份未知则等待合法身份重新出现，不盲发到其它服务器。
- 恢复与重连：恢复历史会话、切换工作区或宿主 SSH 重连后，取得可靠身份才继续远端查询。这里的自恢复是统计查询链恢复，不是插件替宿主自动重连 SSH。身份广播依赖宿主功能与事件；晚加载且没有可信工作区证据时默认不猜测；归属歧义（如同 SID 多归属）时也不猜测。
主面板归属：主标签页（workspace-main）与各分栏按本窗口实际会话节点的 SID 和工作区身份路由，不从共享的 last-session、pane-layout 或工作台分组历史推断归属，因此其它窗口切换会话或清除记录不会改变本窗绑定。身份由版本、资产 SHA256 和唯一节点锚点校验的 renderer 补丁随宿主渲染更新；本窗可信 workspace IPC 与任务列表继续校验身份。节点身份缺失、协议不匹配或 SID 不一致时不借其它分栏或历史远端数据：无桥且本窗没有任何远端证据时按同 SID 的本地记录显示，否则显示零值。已登记的客户端版本以插件 renderer_bridge.py 的 HOST_TARGETS 登记表为准（不在文档维护版本清单）；表外版本先经严格结构校验（唯一锚点、混淆名绑定与 store 形状）自动推导后补丁，校验不过则跳过并降级为数据库轮询。升级安装后需完全退出并重启客户端，旧补丁或未知构建不会启用共享记录回退。
明确分栏的工作区身份与 SID 组合仍可生成远端 scope；空 scope 则 fail-closed，不借同 SID 的远端快照。配置 targets.identity 只绑定查询目标，并不凭空证明主 pane 属于该工作区。
每台远端需部署与本机匹配的 zusage.py，默认路径 ~/.zcode/zcode-token-usage-statusbar/zusage.py。远端需要 Python 3.8+（含标准库 sqlite3），并让执行脚本的用户能读取其 ZCode 数据库。SSH 示例在本机仓库目录执行；请替换连接地址：
ssh user@server 'mkdir -p ~/.zcode/zcode-token-usage-statusbar'
scp zusage.py user@server:.zcode/zcode-token-usage-statusbar/zusage.py
ssh -o BatchMode=yes user@server 'python3 ~/.zcode/zcode-token-usage-statusbar/zusage.py today'WSL 远端的脚本与数据都在发行版内部（Windows 侧 %USERPROFILE%\.zcode 没有远程会话数据），从 Windows 拷入发行版并验证：
wsl.exe -d Ubuntu --exec mkdir -p ~/.zcode/zcode-token-usage-statusbar
copy zusage.py \\wsl.localhost\Ubuntu\home\<user>\.zcode\zcode-token-usage-statusbar\zusage.py
wsl.exe -d Ubuntu --exec python3 ~/.zcode/zcode-token-usage-statusbar/zusage.py today最后一条只验证远端脚本/数据库可读，不证明桌面身份路由或所有服务器已实机验收。自定义远端安装位置时设置 remote.script。远端查询带递归防护，无需在远端安装桌面状态条或再次启用远端转发。
本机查询通道必须免交互可用。插件不能解密复用宿主保存的密码、加密私钥或口令，不会自动登录或应答认证提示；请自行配置 SSH key/agent。自动生成的 SSH 通道使用 BatchMode=yes，不支持的凭据不会变成可用登录；WSL/Docker 通道本身免凭据，但发行版/容器内仍需有可用的 Python 与脚本。自动适配不等于自动部署，不能承诺完全零配置。
将需要的字段合并到运行配置，保留其它设置：
{
"remote": {
"auto": true,
"enabled": false,
"script": "~/.zcode/zcode-token-usage-statusbar/zusage.py",
"python": "python3",
"timeout_s": 6,
"poll_ms": 3000
}
}remote.auto缺省为true，独立控制自动发现/身份路由。remote.enabled: false保留为旧单通道/无身份 fallback 的手动关闭，不关闭已确认身份的自动路由。remote.auto: false关闭自动发现；手动使用带身份的targets时需显式enabled: true。- 不再查询任何远端时，设置
auto: false、enabled: false；已有targets可保留而不会执行：
{
"remote": {
"auto": false,
"enabled": false
}
}下面示例中的身份字符串仅是格式示例。请从客户端连接工作区记录的 workspaceIdentity 复制实际值，必须与当前工作区完全匹配；不要只依据标签、主机名或目录自行猜值。
{
"remote": {
"auto": true,
"enabled": false,
"script": "~/.zcode/zcode-token-usage-statusbar/zusage.py",
"python": "python3",
"timeout_s": 6,
"poll_ms": 3000,
"targets": [
{
"identity": "remote:ssh:build.example.com:22:alice:/srv/build",
"ssh": "ssh alice@build.example.com",
"host_label": "构建机"
},
{
"identities": ["remote:ssh:gpu.example.com:2222:bob:/srv/gpu"],
"ssh": ["ssh", "-i", "~/.ssh/id_ed25519", "-p", "2222", "bob@gpu.example.com"],
"host_label": "GPU 机",
"timeout_s": 6
},
{
"identities": ["remote:wsl:Ubuntu:dev:/home/dev/project", "remote:server:srv1:/home/dev/project"],
"ssh": ["wsl.exe", "-d", "Ubuntu", "-u", "dev", "--exec"],
"host_label": "WSL Ubuntu"
}
]
}
}WSL 目标示例同时绑定两种客户端形态的身份：3.15.x 的 remote:wsl:发行版:用户:/路径 和 3.16 握手升级后的 remote:server:<serverId>:/路径（serverId 以客户端实际持久化值为准）。自动模式下这两类条目无需手配，这里示例用于手动覆盖。
targets 在自动模式或显式 enabled: true 时接收；auto: false 且 enabled 非 true 为总关闭。用 identity 绑定一个工作区，或用 identities 绑定同一目标的多个工作区。目标的 script、python、timeout_s 未设置时继承 remote 顶层值。多个目标不应争抢同一身份；不带身份的多机配置不能实现精准 route。
{
"remote": {
"auto": false,
"enabled": true,
"ssh": "ssh user@server",
"script": "~/.zcode/zcode-token-usage-statusbar/zusage.py",
"python": "python3",
"timeout_s": 6,
"poll_ms": 3000,
"host_label": "我的服务器"
}
}仅旧 CLI python3 zusage.py json <SID> 的 SID/逗号列表协议，在 enabled: true 时可使用 remote.ssh 或首个手动目标作为默认单通道 fallback。桌面始终发送 JSON 请求；显式 scopes: [] 禁止 legacy fallback，即使 enabled: true 也不会把未知 main 借通道查成远端。桌面远端仍必须有可靠 scope，不猜历史身份。多服务器推荐上方带身份的配置。ssh 也可用 argv 数组指定其它免交互通道，例如 Docker ["docker", "exec", "-i", "容器名"]、WSL ["wsl.exe", "-d", "发行版", "--exec"] 或 Kubernetes ["kubectl", "exec", "-i", "pod名", "--"]；WSL 通道建议带 --exec（与客户端 3.16.1 起的调用方式一致，绕开发行版默认 shell 的变量展开），不带时会经默认 shell 执行。
远端按 poll_ms 刷新，默认 3000ms、最少 1000ms，首次查询即建立续查定时器；本地仍以数据库写入事件触发。单目标 timeout_s 限制 1–6 秒，最多 4 个并行查询、整轮总预算 6 秒；配置更大值不能突破预算。失败或暂未找到会话持续退避重试，包括已确认远端 scope 尚未配置目标的情况；总关闭则停止远端轮询。
有效失败条目保留最近成功的同工作区快照并标为 stale/error；首次无缓存显示零值，不借本地今日量。null/error 响应不清空最近成功的显示，不代表取得成功新数据。不需要为了短暂断线反复安装状态条；宿主自身断线需先由宿主/用户恢复连接。配置或客户端连接设置变化、关闭后重新开启由心跳检测（默认 30000ms、最少 10000ms），不是修改文件后立即生效。
- 确认本机确实加载新版安装副本且完全重启过。
- 确认远端脚本、Python、数据库读取权限和免交互 SSH 命令可用；认证失败先修认证，不是重装插件。
- 确认客户端当前会话
workspaceIdentity与目标identity/identities匹配，并安装当前节点身份补丁后完全重启。主标签页与分栏按本窗实际会话节点绑定；未知版本/节点字段、SID 不一致、身份不可信或与任务列表矛盾时不借其它来源。partial 远端 IPC、共享 last-session 或历史分组不证明当前主 pane 归属，默认不猜测服务器。 - 恢复连接后等待轮询与退避重试，再查看各目标独立的今日量和错误；暂未找到会话时先确认远端请求已入库。
协议使用 JSON 请求 {sids, scopes: [{sid, workspaceIdentity}]}，响应 recent 携带 workspace_identity；本机与远端脚本应同步更新，不能把旧版的无身份结果当作多服务器验证。自动化回归说明见 测试文档。
一键安装和插件都使用裸名 /usage（不加插件名前缀）：
/usage
/usage today
/usage week
/usage sessions
/usage workspace:项目目录关键词
MCP 工具 token_usage(scope) 还支持 days:N、sessions:N、models:days 和 session:会话ID前缀。
在仓库根目录运行：
python zusage.py today
python zusage.py days 7
python zusage.py sessions 10
python zusage.py models 7
python zusage.py workspace 项目目录关键词
python zusage.py session 会话ID前缀
python zusage.py watchjson 子命令供自动化工具使用。
- 数据来自 ZCode 本地 SQLite，主要随请求完成入库刷新，不是逐字速度或账单。
- 总用量为输入 + 输出；缓存读取已在输入内，不再重复相加。思考明细取决于供应商是否上报。
- 当前实现将思考视为已包含在输出中；有思考的请求默认从请求开始计算生成耗时，其它请求从首字开始计算，段间工具等待不计入。Claude 系列不单独上报思考 token，但思考同样在首字之前完成，因此也从请求开始计算；这样 Claude 的速度会包含首字前的等待，略低于纯生成速度，属于正常现象。少数供应商的思考 token 是在首字之后随输出流出的（按各供应商的历史数据自动识别：首字等待时间基本不随思考量增长即属此类），这类请求按首字窗口计时已包含思考，不再把发出请求到首字之间的输入预处理（大上下文可达数秒）摊进生成耗时，速度读数更贴近纯生成。
- 状态条完成后的主读数是本会话平均速度（全会话已完成请求的加权平均：Σ输出 ÷ Σ生成时长，工具等待不计、不含子智能体；最近一段/最近一轮读数移入悬停提示）。悬停速度提示还包含「最近 10 轮」柱状图：每轮合并一次提问的全部模型请求（轮速度 = Σ有效输出 ÷ Σ生成耗时，工具等待不计），按完成顺序排列，柱顶标注该轮速度（一位小数），X 轴为各轮完成时间（月日 + 时:分）；悬停或用键盘聚焦柱体可查看单轮详情——完成时间精确到秒，附模型、Token 用量（含输入/输出拆分）、请求次数与预估费用（费用跟随 ⚙ 预估费用开关，旧数据缺字段的行自动省略），不足 10 轮时显示实际数量，旧版数据没有分段列表时保持原「最近一段」读数。左侧读数按运行状态分层展示（工具执行中/工具组执行中/Skill 执行中/子代理运行中/思考中/生成中（估算）/生成完成；会话均态主读数带小号「均」前缀、子代理带「估」前缀，下方为该组分段的速度概览），状态、计时与速度数值各自独立，长技能名悬停可见完整名称；回答速率行看当前提问已入库请求的加权速度，尚未入库的最终正文不在此次采样内，两处另各自标注全会话「会话均」。
- 上下文占比是最近请求输入量 ÷ 窗口容量，不是会话累计量 ÷ 容量。上下文按钮的显示优先镜像客户端实时已用占比（与悬停面板同源，压缩后立即回落，不必等下一条请求完成入库）；客户端未提供该数据时回退最近请求输入量口径。
- 子智能体单独展示；工作区查询按父子关系合并，避免重复计算。会话移动到另一个工作区后，历史消耗归属可能随之变化。
- 「项目累计」格（⚙ 可关，默认开）聚合当前会话所属项目的全部会话消耗：按宿主的 project_id 归属（由启动目录派生，与宿主
--continue找回会话同一身份），含子智能体（会话累计格不含）；会话数/轮数只数有已完成请求的会话。worktree 等不同启动目录各算独立项目；远端会话不在本地库，不显示该格。「会话累计」与「项目累计」悬停明细的标题旁分别拼接当前会话名与项目目录名（与标题垂直居中，超长省略；旧数据缺名称时不显示），都列出按模型分组的消耗（按总量降序全量展示，列对齐不折行），时间范围精确到秒。 - 状态条跟随各窗口的焦点会话；CLI/MCP 的
current是查询库识别的近期活跃会话，不保证等同屏幕上当前窗口。 - 输入框工具行的 Git 状态 chip（⚙「Git 状态」开关，默认开）优先挂在「电脑操作」右侧；该按钮缺失或隐藏时，仍留在同一输入卡片的左侧操作区末尾，不迁到右侧上下文或思考控件旁；无法确认左侧位置时隐藏。它是独立数据链：主进程每 10 秒、每轮回答后及点击时对本窗各 pane 的本地工作区目录运行
git status --porcelain --branch与git diff HEAD --shortstat（无提交仓库退回diff+diff --cached求和），+N/-N 为工作区相对 HEAD 的插入/删除行数合计（非净差异），?N 为未跟踪条目数；计数满 1 万缩写（中文跟随 ⚙「中文单位」开关显示「万/亿」，关闭或英文为 k/M；9999 内原值），chip 与 tooltip 同口径。只读不写 index、不联网、不自动 fetch；远端 SSH 会话、非 git 目录、找不到git时不显示；查询失败保留最近成功结果并以「过期」文字徽章标注。与本地 token 统计互不推导。窄窗时 Git chip 会收起分支名等次要信息；恢复展开前会确认完整内容与安全余量都能放下，避免与原生按钮折叠反复互相触发。 - 工作区目录自身不是仓库（
git status判定非仓库，即祖先链上也无仓库）时，枚举直接子目录中的独立仓库（.git目录或 worktree 链接文件均认，只扫一层、不递归）：0 个维持 chip 不显示；恰好 1 个对该子仓走完整单仓管线，tooltip「目录」行显示真实仓库路径；≥2 个进入多仓聚合，每仓只并行跑一条git status --porcelain --branch（有界并发 6），不查行数。聚合 chip 形如▣ 24仓 · 6改：「改」= 有未提交改动的仓库数（确认冲突的仓库包含在内）；确认冲突追加· !2冲突（冲突仓库数）；部分仓库查询失败追加· 2失败且「改」带「已知」前缀；整体过期显示· 上次6改 · 过期；全部干净只显示份数；窄屏紧凑模式隐藏份数、保留语义段。多仓 tooltip 分三段：概览（有改动仓库数、非零冲突/操作中/查询失败、条目汇总「已跟踪变更 X 项 · 未跟踪 Y 项」、数据不完整时的「已确认 22/24 个仓库」覆盖率行）；逐仓全量列表（行=仓库名+分支+状态标签：!N 冲突、操作名（变基/合并/拣选/还原/二分/补丁）、过期、改 X 项、新 Y 项、↑领先 ↓落后，按冲突 → 失败/过期 → 操作中 → 有改动 → 上游差异 → 干净排序，干净组前插「其余 N 个仓库，无本地改动」分隔行，悬停仓库名可见完整路径，超出屏幕滚动）；元信息（工作目录、更新时间 yyyy-MM-dd HH:mm:ss、口径）。失败仓保留最近成功快照并标「过期」，其冲突不汇总为已确认；刷新失败的时间不算更新时间。「改」的口径=已跟踪变更条目（新增/修改/删除/改名/冲突各算 1，部分暂存计 1 条），「新」=未跟踪条目（目录折叠计 1，文件与目录混合计数），与单仓+N/-N行数口径不同；单仓 tooltip 的已暂存/未暂存/未跟踪同为条目数。子仓库超过 32 个按仓库名排序（码点序、大小写敏感）只统计前 32 个，tooltip 注明「另有 N 个未统计」；远端 SSH 会话不显示与 ⚙ 开关同时管单仓/多仓两种形态的规则与原单仓一致。
更深入的数据库和性能说明见 设计笔记。
| 现象 | 先做什么 |
|---|---|
| 装插件后没有状态条 | 先按安装结果自查确认市场与插件确实装上；再新建或恢复会话触发自动安装，成功后完全退出并重开；失败时用 /install-overlay 兜底 |
| ZCode 升级后消失 | 新建或恢复会话触发自动修复（始终开启，没有配置开关），成功后完全退出并重开；检查卸载豁免，失败时手动安装 |
| 新会话都是零 | 完成一次模型请求后再查看 |
| 远端会话没有数据 | 确认远程配置、远端脚本和非交互通道可用 |
| Python 启动失败 | 检查 Python 命令与 python_path；Windows 的命令可能叫 python |
| 说已更新但没有变化 | 确认安装的是缓存副本而非仅改了仓库；按提示重开会话或重启 |
| 卸载后又有目录 | 确认插件、自动更新和旧主进程已停止，再删除目录 |
在仓库目录可运行状态检查（不修改注入；已注入时可能生成临时语法检查文件并调用客户端可执行文件）。Windows 上 python3 可能是 Microsoft Store 存根会静默失败，依次改用 python、py -3；macOS/Linux 用 python3。「彻底卸载」一节的手动命令同理：
python3 plugins/zcode-token-usage-statusbar/overlay_install.py check
python3 patch_install.py checkpatch_install.py standalone 运行（不经 install.py/overlay_install.py 拉起）不会自动探测安装位置；非默认位置须传 --asar <app.asar 完整路径> 或设置环境变量 ZCODE_ASAR（命令行参数优先），否则会按平台默认位置猜测，猜错时报 FileNotFoundError。install --finalize 还须额外传 --runtime <运行时目录> 或设 ZCODE_RUNTIME：pending TMP 的 sidecar 记录了生成时的运行时目录，standalone 默认用脚本自身所在目录，插件安装的运行时数据目录通常不是同一个，不传会被来源授权校验拒绝；remove/check 不需要这个参数。收尾/卸载失败后的提示会给出带正确路径的完整命令，照着复制执行即可；独立安装的运行目录同样携带 patch_install.py/install_monitor.py，源码 clone 已删除时直接用其中的副本执行提示命令。安装监控窗口若被提前关闭，下次会话启动（插件链为 SessionStart hook 自检、独立链为 MCP 进程拉起）会检测到未收尾的待替换包并静默重新拉起监控；也可随时按提示手动收尾。
运行目录中的 plugin-session-start.json 是启动钩子诊断，plugin-update.json 是更新状态，diag-*.json 是窗口诊断。没有自然启动事件记录时，手动脚本成功不能证明钩子自动执行过；空闲时窗口诊断不持续更新并不等于故障。
先停用，再清理文件。不要只删除运行目录。 自动更新或仍在运行的主进程可能重建文件。
- 如果使用插件，在 ⚙ 关闭自动更新；没有状态条时在现有配置中设置
plugin_auto_update: false。等待已经开始的更新结束。 - 在插件仍启用时执行
/uninstall-overlay，确认成功。这会移除注入并留下阻止重注入的标记。 - 在 设置 → 插件 → 已安装 → ZCode Token Usage Statusbar → ⋯ → 卸载。这是卸载插件组件，不负责移除外部状态条与个人配置。
- 完全退出并重开 ZCode，确认状态条消失。若此前也用一键安装器注册过
/usage，在插件卸载后运行python install.py --remove清理独立注册与运行目录，再重启确认。 - 不再需要插件市场时，在设置里移除
zusage-marketplace。保留供其它插件使用的市场和目录，不要删除整个.zcode。 - 备份想保留的
config.json，检查并删除本项目残留。
插件已卸载才想起移除状态条？从仍保留的仓库执行：
python3 plugins/zcode-token-usage-statusbar/overlay_install.py remove仅一键安装的用户直接执行 python install.py --remove，无需操作插件页。
以下为默认位置。ZCode 支持自定义 storage.dir / ZCODE_STORAGE_DIR，不要把默认路径当作全部安装的固定位置；按自己的设置查找。
- 客户端
app.asar：用patch_install.py check确认未注入，而不是删除该文件。 - 运行目录
~/.zcode/zcode-token-usage-statusbar/：脚本、个人设置、诊断与卸载标记。 - 插件缓存
~/.zcode/cli/plugins/cache/zusage-marketplace/zcode-token-usage-statusbar/：GUI 操作后检查是否残留，不要假定所有宿主版本都会清理同样的目录层级。 - 市场缓存
~/.zcode/cli/plugins/marketplaces/zusage-marketplace/：与市场注册分开检查，本地目录市场可能保留源码副本。 - 插件数据目录：按宿主显示的
dataPath检查，不猜测固定子路径。 - 回答速率状态
~/.zcode/zusage-rate.last-session.json及其.lock：不在运行目录中，若保留过其它安装或多个会话，先确认没有继续使用它。 - 一键安装器的配置备份
~/.zcode/cli/config.json.zusage.bak：可能含完整客户端设置。只处理备份，不要删除原config.json。 app.asar同目录的app.asar.zusage.tmp、.tmp.json、.lock和异常遗留的暂存文件：注入移除、所有相关进程退出后检查。成功卸载会清掉历史.bak，但未知 TMP 可能保留用于排查；不要手动把 TMP 覆盖回 app.asar。- 自行创建的卸载备份：保留与否由你决定。
文件清理请通过文件管理器逐项检查后删除。删除个人配置前先备份；运行目录只能在注入已移除、插件已卸载、旧进程已退出后删除。installed_plugins.json、known_marketplaces.json 是多插件共享库存，不应整文件删除。
在仍保留的仓库运行：
python3 patch_install.py check应显示未注入；然后确认：
- 插件页没有本插件的已安装条目。
- 状态条在完全重启后不再出现。
- 插件缓存和运行目录没有本项目残留（其它插件的市场父目录可能正常保留）。
- 不再使用该市场时，市场页已移除它，对应缓存也已清理。
不必为了卸载删除 db.sqlite；它是 ZCode 自己的用量与会话数据。
自定义供应商使用 sub2api 时，插件使用该配置的 key 在同源 /v1/usage 查询，无需后台管理密钥。订阅型数据展示日／周／月的用量、限额、剩余与已用比例；remaining 可能等于每日剩余，不能当充值余额。仅余额型响应才显示余额；重置时间只展示接口明确返回的字段。
OpenRouter 账户余额需设置 Management Key 或 OPENROUTER_MANAGEMENT_KEY；普通推理 key 不代表管理权限。SiliconFlow 返回 410 时表示接口已停用，不代表余额为零。其他厂商的发现条件、凭据依赖与实测程度见额度支持审计矩阵。
额度查询跟随宿主数据目录（桌面端优先读 <home>/.zcode/v2/setting.json 的 dataBaseDir，ZCODE_DATA_BASE_DIR 环境变量仅作回落），优先采用 ZCODE_PERSONAL_PROVIDER_CONFIG_FILE 与 ZCODE_BUILTIN_PROVIDER_CONFIG_FILE 指向的实际配置；凭据读取与文件监听使用同一实际目录。迁移数据后无需复制 key 回旧 HOME。个人配置只保存 key 而继承内置 baseUrl 的 MiniMax 规则同样可识别；不会按任意模型名称猜测查询地域。运行期改 dataBaseDir 与主进程文件改动一样需完全退出并重启客户端才生效。