一个 Tauri 2 + Rust 的桌面常驻小工具（Windows / macOS 双平台）：实时展示 ZCode CLI 的模型输出速度与今日 Token 用量，并监控 ZCode 的网络上传/下载（区分会话流量与快照上传——ZCode 会在后台把整个工作区打包加密上传云端，这里能看见它传了多少），支持桌宠、迷你仪表盘与速度胶囊三种悬浮窗形态，可最小化到系统托盘（mac 上为菜单栏）。
手动安装：⬇ 下载最新版 Release
让 ZCode 自动安装：
请自行阅读https://github.com/Masterchiefm/zcode-speed-panel ，为用户安装。如果网络不好，善用代理或者ghproxy镜像。
复制以上内容让 ZCode 帮你直接安装。
完整面板：当前速度 / 今日平均 / 今日总量三块仪表 + 网速监控（整机速度、会话上传估算）+ 近 15 分钟速度曲线 + 状态栏（当前速度弧线随速度分档变色：0–40 绿 / 40–80 黄绿 / 80–160 黄 / 160–240 橙 / 240–320 红 / 320+ 品红；当前速度卡右上角另有"上轮"小圆环，显示最近一次已完成调用的速度）；快照防护与上传记录卡默认隐藏，可在顶栏 ⚙ 设置中开启
两种悬浮窗形态（整块可拖动、右键菜单恢复/退出）：
| 桌宠（悬停气泡：实时速度 / 上轮均速） | 迷你仪表（弧线随速度分档变色） |
|---|---|
 |
 |
实机场景：ZCode 桌面端工作中，桌宠悬浮在窗口旁，气泡实时显示当前速度与上轮均速（t/s 按六档变色）：
推荐：直接使用 Release 里打包好的文件（Windows 每个版本两个文件按需下载其一；macOS 按机型二选一 dmg）
-
打开 最新 Release，按系统在 Assets 里选择：
Windows 10/11 x64（需 WebView2 运行时，Win11 自带）：
zcode-speed-panel_x.y.z_x64-setup.exe—— 安装版（推荐）：双击按向导安装，开始菜单启动，旧版本覆盖升级；zcode-speed-panel_x.y.z_x64-portable.exe—— 免安装版：下载后放到任意目录直接双击运行，不写注册表、不建开始菜单，删掉文件即卸载。
macOS 10.15+（双架构独立包，不做 universal）：
zcode-speed-panel_x.y.z_x64.dmg—— Intel 芯片的 Mac；zcode-speed-panel_x.y.z_aarch64.dmg—— Apple Silicon（M 系列，需 macOS 11+）。- 安装：打开 dmg，把
zcode-speed-panel.app拖入「应用程序」。
⚠️ macOS 首次打开会被 Gatekeeper 拦住：本项目的 mac 包没有签名和公证（签名公证需要付费的 Apple 开发者账号），拖进「应用程序」直接双击会提示"无法打开，因为 Apple 无法检查其是否包含恶意软件"（有些系统版本显示"已损坏，无法打开"）。两条路任选一条：- 去掉管控（最快，不重新下载）：在「应用程序」里对
zcode-speed-panel.app右键 → 打开 → 再点一次"打开"，授权一次之后就能正常双击；或者终端执行xattr -cr /Applications/zcode-speed-panel.app清掉这个 app 的隔离标记（只对这一个应用生效，不动系统的安全设置）。 - 自行编译（不碰 Gatekeeper 管控）：按开发与构建在本机跑
npm run tauri build，自己编出来的包没有隔离标记，装好直接双击即可运行——若不想为下载的包放宽任何安全设置，走这条。
-
同一系统的各版本功能完全一致，数据都存放在
~/.zcode/下，可共存。
macOS 退出方式说明：悬浮窗/桌宠形态菜单栏常驻（无 Dock 图标）；完整面板形态会亮出 Dock 图标（Regular 应用身份，绿色交通灯可原生全屏），收起为悬浮窗后 Dock 自动隐藏、应用不退出。点窗口 ✕ 或按 Cmd+Q 都是折叠为悬浮窗而不是退出——真退出只有两条路：菜单栏图标右键 → 退出，或悬浮窗右键 → 退出程序。找不到窗口时，点屏幕右上角菜单栏的应用图标即可唤起面板。
其他方式：
- 下载某次提交的构建产物：到 Actions 页选一次成功的 Build 运行，在 Artifacts 下载
windows（含安装版与免安装版两个 exe）、macos-x86_64-apple-darwin/macos-aarch64-apple-darwin（各含一个 dmg，适用于体验尚未发版的最新改动）； - 从源码构建：见下方开发与构建。
运行环境：Windows 10/11 x64（WebView2，Win11 自带）或 macOS 10.15+（Intel）/ 11+（Apple Silicon）。所有数据仅从本地文件与进程读取，不上传任何内容。
现在的桌宠阵容太单薄了——特别想看 质谱娘 登场！如果你手上有质谱娘的桌宠素材（或愿意画一套），恳请投稿：到征集 issue 留言，或直接提 PR。格式很简单，一个 pet.json + 一张 spritesheet.webp（参考 public/pets/ 里现有宠物包），不会写代码也没关系，素材收到后由我们来集成，收录后会在 README 与 Release note 致谢。
- 悬浮窗模式（点右上角高亮的"⧉ 收起为悬浮窗"，或直接点窗口关闭按钮）
- 三种样式可选（完整面板右上角下拉框）：桌宠（默认鲸鱼女仆，精灵区 200×200、头顶另有气泡预留带；滚轮上下滚动缩放 100~480；双击或 🔄 换宠物；待机站立；生成中按实时速度分档换动作：0–40 t/s 小跑、40–80 t/s 迈步、80–240 t/s 跳跃、240+ t/s 极速左右来回跑；生成/估算时头顶气泡显示实时速度，鼠标悬停变多行：实时速度 / 上轮均速——气泡向头顶上方生长，宠物不缩小不遮挡；多任务并发时气泡自动展开分任务行（每个 CLI 进程一行、分档着色，窗口自动向上加高给行让位），待机时不显示气泡；右键菜单或完整面板顶栏的**"常显上轮均速"开关**（桌宠样式时出现）勾选后生成中气泡恒以多行出现（实时速度 + 上轮均速一起显示，无需悬停），待机时气泡仍隐藏）/ 迷你仪表盘（148×148 正方形，主环旁带"上轮"小环，弧线读数口径与完整面板当前速度表一致）/ 速度胶囊（172×72，实时速度下方一行"上轮均速"）
- 按住任意位置拖动；点 ⤢、双击悬浮窗（桌宠除外——双击已用于换宠物）或右键菜单 → 恢复窗体展开回完整面板；右键菜单还可退出程序（桌宠样式下菜单首项为"常显上轮均速"勾选）
- 桌宠位置与完整面板位置各自独立记忆：收起时桌宠回到自己上次的位置（首次锚定窗体中心），展开时窗体回到自己的老位置，互不拉扯
- 模式、样式、两种位置与桌宠尺寸都会记住，下次启动直接恢复
- 近 15 分钟速度曲线（10 秒一档；横轴标注真实墙钟时刻，每 5 分钟一条刻度，整条曲线随时间连续左移，可直接对表验证）
- 模型速度趋势详情：点图表卡片右上角"模型详情"打开弹窗，按模型分类展示最近 10 分钟 / 1 小时 / 6 小时（60 桶，5s 自动刷新）的速度折线与统计（均速 / 峰值 / 调用次数 / token 占比）；图例可点击多选——隐藏干扰模型（折线与统计行同步过滤，至少保留一个），行尾「全选 / 仅 Top3」（token 用量前三）快捷操作，选择跨刷新持久记忆；直接只读查询 ZCode usage 数据库现算，不落任何本地数据
- 速度分档配色：当前速度表的弧线与读数随速度整体变色——0–40 t/s 绿、40–80 黄绿、80–160 黄、160–240 橙、240–320 红、320+ 品红，一瞥即知快慢（部分极速模型远超 100 t/s，六档全覆盖）；背景轨道恒为灰色，悬浮窗迷你仪表与"上轮"小环同规则
- 实时读数重新校准：当前速度卡左上角 ⟳ 按钮随时手动触发——丢弃已学习的字节→token 系数样本、回到默认先验重新收敛（更换模型后实时读数明显偏离"上轮"真值时用，按钮闪 ✓ 表示已生效）。也会自动触发：每轮调用取显示速度均值，上轮均值与之前连续 5 轮均值差异 ≥3 倍（升/降双向）即判定速度量级突变（换了模型/分词器，旧系数已过期），自动重新校准
- "上轮"小表（完整面板当前速度卡右上角、迷你仪表悬浮窗主环旁）：显示最近一次已完成调用的速度（落盘口径：输出+思考 ÷ 纯生成时长），与实时读数互为参照——实时测速受管道静默影响时，可对照上一轮实际速率判断当前读数是否可信；胶囊悬浮窗与桌宠悬停气泡同样给出该值；均按同一六档变色，鼠标悬停有口径说明
- 无边框窗口 + 自绘顶栏：顶栏与应用同风格，按住拖动移动、双击安全最大化/还原（mac 绿色交通灯为原生全屏，符合 mac 语言）；平台原生化控制按钮（macOS 位于顶栏最左侧，为原生红黄绿交通灯圆点，悬停微显符号；Windows 保持右侧
— ▢ ✕自绘控制）；支持多屏安全最大化，副屏最大化铺满不跳屏、还原记忆副屏原位；窗口标题实时显示当前速度（任务栏/Alt+Tab 可见）；托盘（mac 为菜单栏）左键单击显示/隐藏，右键菜单顶部有实时状态行（生成中 x.x t/s / 估算中 / 待机），菜单项（显示面板 / 隐藏到托盘 / 悬浮窗切换 / 退出）；重复启动自动唤起已有窗口。mac：原生 Overlay 标题栏 + 真·系统交通灯（绿点原生全屏、红折叠、黄最小化）；完整面板亮 Dock 图标、悬浮窗自动隐藏（菜单栏常驻），Cmd+Q与点 ✕ 均折叠为悬浮窗，窗口每次显示时会提示"应用常驻菜单栏"（6 秒自动消失）；WebView 的 Cmd+C/V/X/A 由自定义"编辑"菜单保留 - 应用内更新：状态栏右下角显示版本号，点击即手动检查更新；程序每次启动与每天还会自动静默检查一次（无更新或网络异常完全不打扰）。发现新版本时自动在后台下载（右下角卡片显示进度与更新说明），点"立即更新"即安装——Windows 自动调起安装向导（应用自动退出交接），macOS 打开 dmg 拖入「应用程序」即可；卡片另有**"手动下载"按钮**直达浏览器中的 Release 页自行下载；✕ 关闭提示后该版本不再自动弹（版本号旁留小圆点提醒）。
- 网速监控（完整面板"网速监控"卡）：实时显示整机上传/下载速度与当日总量（接口计数器实测，整机 = 本机全部应用流量而非仅 ZCode，卡上有显式标注；约 1 秒滑窗、字节单位——任务管理器显示比特且仅统计所选网卡，读数对不上是口径差异，悬停数值可看完整说明）；当日上传/下载中的会话流量（≈ 估算，按 token×系数）单独列出与整机值对照；另有 ZCode 连接归属（悬停看每条连接的远端与归属进程）：ZCode 会话进程（CLI，对话流量）与 ZCode 桌面端（ZCode 的 Electron 壳——快照上传等非对话流量的承载者）各持有几条外连——两组都是 ZCode 自身进程，不含其他应用。整机上传飙升 + 桌面端新连接 + 快照防护卡的"快照上传进行中"同时出现，就是又一次快照上传的现场证据（口径细节见
docs/features.md；按进程直测网络字节在 Windows/macOS 非管理员下无公开原语，故采用此分层设计）。当日网络累计跨重启续算。 - 快照防护与上传记录（完整面板"快照防护与上传记录"卡——快照相关的一切都在这张卡）：上方为防护开关与状态（见下条）；下方今日快照上传（监控
~/.zcode/v2/checkpoints/的上传接受事件，ZCode 把整个工作区打包加密上传到云端时如实累计快照大小——今日 N 个，下方逐行列出工作区名单，悬停看逐条明细，上传进行中脉冲提示）与快照上传记录列表：逐工作区列出已上传快照（时间/工作区/加密后大小/状态——上传中、待传、已接受；固定显示 5 行、其余列表内滚动查看，可选中复制或一键导出为文本文件留存取证，行尾 📂 可在文件管理器中打开快照目录）；checkpoints 目录被 ACL 封锁时如实显示"不可读"。 - 快照防护（阻断工作区快照静默上传，macOS / Windows）：ZCode 登录后会把整个工作区（含
.git历史）加密上传到云端，设置开关无效（机制分析文章）。在"快照防护与上传记录"卡开启防护时二选一：保留并锁定（推荐）——现有快照原地只读保留（mac 递归不可变锁 / Windows 目录 ACL 拒绝写入），上传记录照常显示、行尾 📂 可在文件管理器中打开快照目录；删除并锁定——先留档记录清单再清空全部快照（原始记录随之消失，仅清单可回看，确认弹窗逐条明示）。锁定后 ZCode 写不进去，快照上传链路彻底死亡；不碰网络，模型对话 / 代码补全 / 工具调用完全不受影响，唯一损失是 ZCode 的「检查点回滚 / 时间线」功能（随时可解除：保留的快照原地恢复，空目录自动重建）。防护中卡片区分"快照已保留 / 已删除"两态并累计"开启后 N 轮对话 · 新快照落盘 0 个"；卡片标题悬停可看防护原理与监控边界说明（不承诺 100% 拦截，直传机制靠流量层发现）。 - 设置：模块显隐与排序（顶栏 ⚙ 齿轮按钮）：勾选要在完整面板显示的模块并用 ↑↓ 调整上下顺序（列表从上到下 = 面板从上到下，即时生效并跨重启记住）。默认显示 仪表盘 / 网速监控 / 近 15 分钟输出速度，快照防护与上传记录默认隐藏——需要时再勾选开启；「恢复默认」一键还原。并发任务卡跟仪表盘走（不单列）；模块开关不影响悬浮窗与状态栏。
- 状态栏：数据源（usage 数据库）、今日调用次数、会话数、最近活动时间
- 今日用量与平均速度：只读轮询 ZCode usage 数据库（
~/.zcode/cli/db/db.sqlite的model_usage表，WAL 模式不影响运行中的客户端）。速率定义采用纯生成时长：分母 =completed_at - first_token_at（排除首 token 等待与排队），分子 =output_tokens + reasoning_tokens（思考内容同样是流式输出）。一张表覆盖全部会话（含子 agent）。 - 实时速度（30s 滑窗实测，秒级启停）：不依赖落盘数据，直接实测 CLI 进程的写字节流折算而成，原理见下方《实时速度实测原理》。调用开始当拍即亮"生成中"（新开对话同样即时），首字节到达前表盘/桌宠显示 "…"（统计中） 提示而不是估算值；结束、取消、出错都在 1~2 拍内归零。多任务并发（多窗口/子代理并行）时读数为聚合总吞吐，完整面板同时显示分任务明细（按 CLI 进程逐个实测，各行合计 = 主表读数），桌宠气泡也会展开分任务行、窗口自动向上加高。同一 ZCode 窗口内新开的任务会复用同一服务进程（跨项目才各起进程），字节层无法拆分——此类任务计为一行合计（标注会话数），速度为该进程合计。
- 网速监控：整机速度/当日总量来自操作系统接口计数器（实测）；会话流量按当日 token 数×字节系数估算（≈ 标注）；快照上传来自
~/.zcode/v2/checkpoints/*/state.json的接受事件（真实工件大小）；ZCode 连接归属来自 TCP 连接表的进程归属（仅 Windows）。当日网络累计跨重启持久化续算（~/.zcode/speed-panel-net.json）。详见docs/features.md的"网速监控"节。 - 部分调用期间 UI 管道无增量字节（实测约半数调用是"完成时一次性刷出"），此时回退为：门控判定生成中 → 显示近期已完成调用的真实速度 ≈（与速度曲线同口径，两者不再打架）；完全无调用 → 归零待机。
要解决的问题：ZCode 只在调用完成时才把 token 数落盘（model_usage 表），流式过程中数据库里没有任何增量数据——这是所有"完成后统计"类工具的共同盲区：长回答生成期间，速度只能显示 0 或上一次的旧值。
关键观测：CLI 进程在模型流式输出时，会持续把渲染增量写入通往桌面 UI 的管道。对进程写字节速率的实测显示（Windows）：
| 状态 | 写速率（每 ~700ms 拍） |
|---|---|
| 流式输出中 | 6 ~ 25 KB，随生成节奏波动 |
| 待机 | 仅 1 ~ 2 KB 心跳 |
| 调用完成瞬间 | 数百 KB 尖峰（落盘写入） |
这个计数器由 Windows 内核维护（GetProcessIoCounters 的 WriteTransferCount），权威、实时、读取零开销。
macOS 口径差异（同一条清洗/校准管道，平台参数不同）：进程发现用 proc_listallpids + KERN_PROCARGS2 识别（CLI 由 Electron Helper fork 而来，须按命令行参数 zcode-cli 精确匹配）；写字节计数器换成 proc_pid_rusage 的 ri_diskio_byteswritten（内核维护的进程累计磁盘写字节）。mac 上流式字节是单拍突发形态（0,0,0,+225KB~1.5MB，≈3900 B/token），与 Windows 的连续细流不同，因此禁用突发剔除、不设静态底噪（idle 实测严格 0 字节）、初始系数与校准区间按实测放宽；rollout 目录的落盘扣除在 mac 上关闭（目录净变化常为负——清理轮转会反噬清洗流，见 docs/features.md 的 CleanParams 平台表）。
测量循环（随主轮询 ~700ms 一拍）：
- 发现进程：Toolhelp32 枚举全部进程 → 过滤
ZCode.exe→ 读每个进程的完整命令行（ProcessBasicInformation → PEB → ProcessParameters → CommandLine），只保留含zcode.cjs的 CLI 子进程（每 30s 刷新，排除桌面壳/渲染进程；一个进程都没发现时缩短到 2s——新开的 CLI 最长 2s 即可被观测到） - 采样：对每个 CLI 进程读取
WriteTransferCount（进程启动以来累计写字节），存入每进程约 3 分钟的环形缓冲 - 启停判定（调用门控）：看 usage 库 message 表的 assistant 消息行——它在调用开始瞬间即提交（实测 ≤200ms 可读），行内
time.completed字段在调用结束（含取消/出错）瞬间补写。扫描最近活跃会话的最新 assistant 行：未带completed的全部会话都算调用进行中（不限会话：新开对话的首个调用当拍即亮，无需等它的首个完成行落盘；多任务并发各自计入）；带completed→ 当拍归零。usage 库的model_usage行只记status='completed'，取消/出错的调用永远没有完成行——早期以完成行判定启停时，这类调用会卡"生成中"最长 10 分钟。工具执行/待机期间管道同样有 UI 状态突发，字节上无法与模型流式区分，门控将其可靠排除；进行中会话的归属进程全部退出（崩溃/关终端，completed无人补写）时强制判停，不留僵尸"生成中" - 速度读数（30s 滑窗 ∩ 活跃段）：对 30s 窗口内的清洗字节取均值，但左边界不早于本段流式起点——起步时只有几拍也立即有读数（状态栏显示"统计中…"），随后窗口逐渐填满变得平滑；流内停顿与完成瞬间的落盘尖峰不会混入
- 扣心跳噪声：每进程取自身历史最小增量的 2 倍作为底噪扣除（自适应，各进程底噪不同），单拍封顶 ~2KB——不封顶时持续流式期间分位数会被流式增量本身抬高，把自己的输出当噪声扣掉（实测读数塌缩到真值 1/5 的元凶之一）
- 扣落盘尖峰（允许负拍）：同步监测 rollout/日志/WAL 文件大小增量并从写字节中减去。落盘 flush 与 IO 计数存在错位：单拍可能"文件涨了 60KB 但只写了 20KB"，该拍记为负值，由前后正拍在区间总和中对消；若逐拍钳 0，错位增量会被永久吞掉（实测另一半损失来源）。单拍原始增量超过 100KB（请求体上传 ~190KB/拍）整拍剔除，字节与时长都不进积分
- 字节 → token（一致性校准）：除以自校准系数。每次调用完成后，用与显示路径完全相同的清洗流在
[first_token, completed]区间的按时间比例积分字节 ÷ 真实output+reasoning tokens得到一次校准样本，取最近 5 个（含初始 600 先验）的中位数作为当前系数。分子与显示分子同源：任何系统性扣除（噪声底/落盘镜像/突发剔除）都被系数自动抵消，显示值收敛到真实 t/s。输出 <300 token 的调用不入样本——小调用的 UI 固定帧开销会把系数抬高数倍。先验样本保证冷启动时单个异常样本无法独占系数；已学习的样本队列持久化在本地（~/.zcode/speed-panel-cal.json，超 14 天自动过期回先验），重启后直接沿用，不再每次从先验重新收敛（系数偏离先验的会话冷启动读数可偏差 2~3 倍）。系数可随时重置为先验重新收敛：当前速度卡 ⟳ 按钮手动触发，或轮均速漂移（上轮均值 vs 之前连续 5 轮均值 ≥3 倍，双向）自动触发——换模型后旧系数过期时读数能自动回到正轨
启动提示（统计中…）：门控开启但首字节尚未到达（TTFT/排队）时，表盘数字与桌宠气泡显示 "…"（青色呼吸脉冲弧提示"已连接、等待输出"），不显示误导性的估算值；超过 20s 仍无字节的调用视为管道静默，回退到下面的 ≈ 估算。
管道静默回退：实测相当一部分调用（多为 first_token_at 为空者）生成期间不往 UI 管道写增量、全部字节在完成瞬间一次性刷出。对这类调用，门控（生成中）与字节（静默）组合判定后，面板回退显示"近期 10 分钟已完成调用的真实速度"（≈ 标记，与速度曲线完全同源），避免出现"图表 50、仪表盘 0"的矛盾。
多任务并发：按进程归属聚合：每次调用完成时，取流式区间内写字节最多的进程，标记为该会话所属的 CLI 进程（带迟滞：已有归属时仅当候选进程字节 ≥ 现归属 2 倍才切换，并发窗口间不逐调用翻转）。实时速度统计全部进行中会话的归属进程并集——多窗口/子代理并行时当前读数是真实的总吞吐，完整面板同时在仪表行下方显示"并发任务"卡（一个 CLI 进程一行：归属会话 + 各自速度，合计 = 主表读数；同一窗口内并行的多个子代理在字节层不可拆分，显示为该进程合计）。尚无归属记录的进行中会话（新会话/子代理的首个调用未完成过）触发全进程求和兜底，不会显示成别的窗口的速度。CLI 全部退出后即使门控信号残留也立即归零待机，不再按调用间隔盲估。判停兜底：停止生成后 CLI 补写"完成"标记可延迟数秒~分钟，若期间门控信号残留而字节流已断绝超过 15 秒，面板同样判定已停、读数归零——不会一直挂着"生成中"或 ≈ 估算。
实测效果（标题栏轨迹）：
19:56:52 ⏸ 0.0 t/s ← 无任务
19:56:53 ▶ … t/s ← 调用已开始（TTFT），表盘/桌宠显示"…"等待首字节
19:56:55 ▶ 18.2 t/s 统计中 ← 首字节出现，当拍响应、立即有读数（30s 滑窗建立中）
19:56:58 ▶ 37.5 t/s ← 滑窗填满，读数趋于平滑
19:57:21 ▶ 9.5 t/s ← 末段节奏放缓（真实反映）
19:57:22 ⏸ 0.0 t/s ← 停止后 1~2 拍内判定停止，立即归零（取消/出错同样即时）
精度说明与对账：字节 → token 的换算是统计近似的（清洗流实测约 200~900 B/token，随 UI 帧内容波动；一致性校准使其长期积分收敛到真值）。精确 token 计数仍由每次调用完成时的落盘记录提供，用于今日总量与均值——两者互为补充。每次调用完成后，调试日志写入一条对账事件：pred_tps = 清洗流区间积分 ÷ 生成时长 ÷ 当前系数，与落盘真值 true_tps 对比即可量化实时准确性：
python scripts/live_vs_true.py # 实时 vs 真值 对账（旧格式日志自动退化 tick 回放）- 今日 Token 总量与 ZCode 官方统计同口径 =
input + output + reasoning + cache_creation；缓存命中（cache_read）是提示复用、不计入总量，明细中以缓存命中率展示（cache_read ÷ input——usage 库的 input 是全部提示 token，缓存命中的部分已计入其中）。按事件完成时间归属"今日"，跨天自动重置。
隐私：所有数据仅从本地文件与进程读取，不上传任何内容。
环境要求：Node.js ≥ 20、Rust stable（Windows 下需 MSVC 工具链；macOS 下需 Xcode Command Line Tools）、WebView2 运行时（Win11 自带）。
npm install
npm run tauri dev # 开发调试（debug 版连接 vite dev server）
npm run tauri build # 正式版（内嵌前端 + 安装包：Windows NSIS / macOS dmg）mac 本地构建如需精确声明最低系统版本（CI 的做法，与本节命令一致）：Intel 包加
--config '{"bundle":{"macOS":{"minimumSystemVersion":"10.15"}}}'并前缀环境变量MACOSX_DEPLOYMENT_TARGET=10.15（前者写 Info.plist 的 LSMinimumSystemVersion，后者决定二进制的最低版本；不指定时 tauri 默认 plist 写 10.13）。
macOS 交叉构建 Apple Silicon 包（在 Intel Mac 上即可）：
rustup target add aarch64-apple-darwin
MACOSX_DEPLOYMENT_TARGET=11.0 npm run tauri build -- --target aarch64-apple-darwin --bundles dmg --config '{"bundle":{"macOS":{"minimumSystemVersion":"11.0"}}}'产物位置：
- Windows：可执行文件
src-tauri/target/release/zcode-speed-panel.exe，安装包src-tauri/target/release/bundle/nsis/*.exe - macOS：
src-tauri/target/release/bundle/macos/zcode-speed-panel.app与src-tauri/target/release/bundle/dmg/*.dmg（交叉构建时在src-tauri/target/aarch64-apple-darwin/release/bundle/下）
调试工具（不走 UI，直接打印引擎对真实数据的计算结果，含 IO 实测可用性）：
cd src-tauri && cargo run --example dump调试日志：面板运行时持续把数据追加到 ~/.zcode/speed-panel-debug.jsonl（8MB 自动轮转保留一代，轮转出的旧文件超过 7 天在启动时自动清理）：tick（实时显示值/清洗管道字节率 pipe/生效系数/统计图尾桶，活跃期逐拍+待机心跳 30s 一条）、call（每轮调用完成后的真实 token 与真实速度）、cal（每次校准与对账：真值 true_tps、原始/清洗积分字节 raw_kb/clean_kb、样本系数 bpt_sample、显示口径预测 pred_tps）、cal_reset（手动/漂移自动重新校准：系数前后值与触发均值）。离线验证工具同样记录前三类事件：
cd src-tauri && cargo run --example verify -- 300 target/verify-log.jsonl # 采样 5 分钟
python scripts/compare3.py src-tauri/target/verify-log.jsonl # 仪表盘 vs 统计图 vs 真值 三源对比单元测试：
cd src-tauri && cargo test普通推送不会触发构建。两种出包方式：打 v* 标签（如 git tag v0.2.0 && git push --tags）会自动创建 Release，Assets 附 Windows 安装版（_x64-setup.exe）、免安装版（_x64-portable.exe）与 macOS 双架构 dmg（_x64.dmg = Intel、_aarch64.dmg = Apple Silicon，未签名公证，首次打开见上方绕过指引）；或在 Actions 页选择 Build → Run workflow（选 main 分支）手动触发，产物在本次运行的 Artifacts（windows 含两个 exe；macos-x86_64-apple-darwin / macos-aarch64-apple-darwin 各含一个 dmg）。mac 包最低系统版本：x64 = 10.15、aarch64 = 11.0。配置见 .github/workflows/build.yml。
发版前把版本号三处一起 bump：src-tauri/tauri.conf.json（运行时权威）、src-tauri/Cargo.toml、package.json——应用内更新按 Release 资产名后缀匹配安装包，产物命名与版本号是它赖以工作的协议，不可只改一处（详见 docs/key-rules.md #12）。
npm run dev 后直接在浏览器打开 http://localhost:1420，页面会以模拟数据运行（检测到非 Tauri 环境自动进入 mock 模式），便于调样式。
Tauri 2（Rust 后端：usage 数据库轮询 + 进程 IO 实测 + 网络接口计数与 TCP 连接归属 + 托盘）、原生 Canvas 绘制仪表盘与桌宠（无图表库依赖）、Vite + TypeScript。
- zcode-tps-monitor（MIT）：本项目速率定义借鉴其纯生成时长口径（first_token_at 起点、思考 token 计入分子）
- dsh-desk（MIT）：桌宠采用其内置的 Codex Pet 宠物包（月薪喵、Maid-DeepSeek-Whale）