使用看板

概述

在 Metrix.Bar 中，所有监控与指标均以看板（Dashboard）为单位进行组织。一个看板封装了数据查询、业务逻辑、菜单栏指标与弹出面板。无需手动拼装界面画布，开箱即用。

挑选看板

打开 Metrix.Bar，应用展示当前已添加的看板以及官方看板源目录（按分类分组）。App 仅内置 GitHub 仓库看板，其余 13 个官方看板按需从官方看板源安装。

• AI：Claude Code 用量、Codex 用量。
• 统计与图表：Umami、Plausible、PostHog、Rybbit、Dub 短链分析、Sink。
• 开发：GitHub 仓库指标。
• 天气：天气。
• 金融：加密货币行情、加密钱包、股指。

完整索引发布在 metrix.bar/dashboards/index.json，也可在看板库中浏览。你也可以导入由同事分享或 AI Agent 编写的任何 .bar 格式看板文件。

配置输入项

每个看板都会声明运行所需的配置项。当打开需要初始配置的看板时，应用会自动生成参数表单：

如果存在未填写的必填项（required），看板会处于等待配置状态，不会发起无效的网络请求。

GitHub 仓库看板直接读取 GitHub REST API。公开仓库无需 Token，使用每小时 60 次的匿名额度，足够每 10 分钟刷新一个仓库；配置 Token 后额度更高，并可读取私有仓库。刷新失败时保留最近成功的数据并提供 Retry。

Umami 看板需填写 API 地址，以及 API 密钥或自托管 Umami 2 的用户名和密码。API 密钥优先；Umami Cloud 必须使用 API 密钥。

Rybbit 填写 https://app.rybbit.io 或自托管域名，以及具有 analytics:read 权限的个人 API key，即可自动加载各组织中有权访问的站点，并从列表切换查看站点详情。

Umami 和 Rybbit 可在当前显示网站的实时访客总数超过阈值时发送系统通知。在 Settings → Notifications 中开启通知，输入非负整数（默认 100），按 Enter 或点击 Save 生效。通知默认关闭；完整的新采样超过阈值后，持续超限只通知一次，完整采样的合计人数回落到阈值或以下后，再次超限可重新通知。无效或失败的实时人数不会触发通知或恢复通知资格。即使面板关闭，实时人数仍每分钟刷新。重新启动看板会重置通知去重状态。

凭据安全管理

在 secret 字段输入密钥时：

• 密钥将以该看板专属 ID 为标识写入系统安全凭据库中。
• 应用配置文件与导出的 .bar 单文件中绝不记录任何密钥明文。
• 你可以随时在参数设置页面更新或清除已保存的密钥。

预览看板

选择看板入口前，可先预览：

• 实时数据：Metrix.Bar 自动运行看板 Worker，并将界面渲染为原生组件。
• 错误诊断：若某个接口请求失败或数据异常，错误状态直接呈现在面板中，不会影响其他看板的运行。

看板入口与打开方式

在看板设置中，可独立配置视觉入口、键盘快捷键与打开方式：

• 五种来源独立开关与打开方式：菜单栏（Menu Bar）、左侧 Sidebar（Left Sidebar）、右侧 Sidebar（Right Sidebar）、底部 Sidebar（Bottom Sidebar）与键盘快捷键（Keyboard Shortcut）五个触发来源均有独立的启用开关与打开方式选择（Flyout 或 Dialog）。同一个看板可设置菜单栏以 Flyout 打开，而快捷键与右侧 Sidebar 以 Dialog 打开。关闭某个视觉入口或禁用快捷键会保留其已配置的打开方式。
• 快捷键独立开关与录制：在看板设置中，Keyboard Shortcut 行提供独立的启用开关与打开方式选择；其下方的独立 Shortcut 行承载按键绑定与录制（Record）/ 取消流程。即使菜单栏与三侧 Sidebar 全部关闭，快捷键仍可独立唤出面板，且在错误态下仍可编辑。

屏幕 Sidebar 独立于主窗口的导航侧栏：

• 单次只展开触发方向：触发左、右或底部外缘热区时，任意时刻最多在当前屏幕展开对应的那一侧 rail（最多一个屏幕、一个方向 rail），不同时展开多侧；指针切换到另一侧时先移除旧栏再创建目标栏。
• 贴边触发与驻留保持：屏幕 Sidebar 为贴屏边的深色胶囊（固定深色背景，不随系统浅色模式改变）。平时完全隐藏；贴死右侧或底侧边缘即可触发（左右触发区位于高度 25%～75% 的区域，底部触发区位于底边宽度 25%～75% 的区域，厚度均为 2 DIP），指针停留约 100 ms 展开，多屏相接的内缝不会触发。展开时从屏幕边缘滑入，收起时滑出；在系统 Reduce Motion（减少动态效果）偏好下无动画，即时显隐。指针在当前侧有效触发热区内驻留时持续保持展开，即使落在短 rail 外侧也不会闪烁或收起；离开有效保持区（当前侧有效热区、rail、tooltip、面板、连接通道与菜单）300 ms 后收起。App 处于非前台状态时，Sidebar 贴边展开与图标悬停同样可以正常响应。
• 外观与排布：Sidebar 只显示图标。底栏横向排列图标，溢出时横向滚动，tooltip 显示在图标上方。悬停提示只显示单行核心数值，优先显示托盘标题（tray.title），缺省时依次使用托盘提示（tray.tooltip）、看板名称，不显示标题行；图标依次使用托盘图标、看板图标、通用看板 glyph。指标数值由看板格式化。Sidebar 窗口请求显示在系统栏上方，底栏可能与 Dock 或任务栏位于同一区域。
• 图标拖动排序与菜单栏联动：在屏幕 Sidebar 内按住平台主修饰键（macOS Cmd，Windows/Linux Ctrl）拖动图标可直接重排顺序，并写入全局看板顺序，首页、其他 Sidebar 和主窗口左栏各分组内同步跟随；拖动仅调整当前栏可见看板之间的相对位置，松手前先松开修饰键或拖回原位即可取消。在 macOS 上按住 Cmd 拖动菜单栏中的 Metrix.Bar 图标后，看板顺序会在下次展开 Sidebar 或刷新主窗口时单向跟随（Windows 与 Linux 托盘顺序由系统决定，不同步）。

Dialog 与 Flyout 呈现：

• Flyout：从所点入口向屏幕内侧展开，底栏 Flyout 向上展开。点击 Sidebar 图标打开 Flyout 时，macOS 使用系统 Popover，箭头指向被点击图标（左栏向右、右栏向左、底栏向上），Flyout 打开期间侧栏保持展开；Windows 与 Linux 使用无箭头的 Flyout。
• 高透明遮罩与居中呈现：Dialog 在当前显示器完整 Bounds 上展示遮罩并居中展示看板内容，不进入系统全屏 Space。遮罩采用约 12% 黑色的高透明遮罩（系统高对比度模式下为约 40% 黑色）；内容卡片带圆角与阴影。
• 无关闭按钮与四侧 10% 间隙：界面无“X”关闭按钮。内容请求尺寸由看板决定，默认 320×480 DIP。左右边距各至少为屏幕宽度的 10%，上下边距各至少为屏幕高度的 10%，内容区域宽高最多为屏幕宽高的 80%，超大内容内部滚动；内容尺寸动态变化不会缩小遮罩外壳。
• 交互与关闭：点击内容外或按 Esc 可关闭，内容内点击不关闭；有内部浮层时 Esc 优先关闭该浮层。Dialog 打开时 Sidebar 收起，关闭后需先离开边缘触发区再进入，才能重新唤出 Sidebar。

多个入口共享同一份数据与面板状态。已配置且可用的 Sidebar 即使收起仍保持刷新；没有可用入口、预览或打开的面板时，看板闲置，直到再次需要。你仍可通过主窗口或快捷键打开看板。右键入口可执行刷新、打开设置等操作；移除菜单栏入口不会关闭已启用的 Sidebar 入口。

平台可用性

Linux 支持目标为 X11 及具备可用 gtk-layer-shell 库和协议的 Wayland。GNOME 原生 Wayland，或因缺库、缺协议而无法原生定位屏幕的会话，会禁用 Sidebar 并说明原因。Dialog 同样需要原生屏幕定位能力，不可用时明确提示，不以普通浮窗替代。注意：Windows 与 Linux 桌面 GUI 实机验收仍待完成。

本地 API 自动化

Metrix.Bar 在 6387 端口提供本地回环 HTTP API，供命令行与 AI 代理自动化调用：

• 立即刷新：POST /v0/dashboards/:id/refresh 触发数据刷新。
• 发送事件：POST /v0/dashboards/:id/events/:name 向看板 Worker 发送自定义事件。
• 读取快照：GET /v0/dashboards/:id 获取看板当前状态与 UI 视图树。

导入与导出 .bar 文件

所有看板均基于 .bar 单文件格式进行分发：

• 导入：将 .bar 文件置入 Dashboards 目录，或通过本地 HTTP API 直接创建。
• 导出：导出的文件完整包含所有权限声明（网络源与本地文件路径）、输入参数定义与 Worker 脚本，但不包含任何敏感密钥，确保分享安全。