看板源 Registries

概览

看板源（Registry）是一个静态 JSON 索引，列出可安装的 .bar 看板。Metrix.Bar 读取看板源、展示目录，并通过 HTTPS 下载每个看板——不需要包管理服务器或账号。

每个看板源在固定 URL 发布一个 index.json。条目指向同源的 .bar 文件，带完整性哈希，并使用短 ID——安装时在设备上组合成全局唯一的安装 ID。

index.json 结构

{
  "$schema": "https://metrix.bar/dashboards/schema.json",
  "schema_version": 1,
  "id": "official",
  "name": "Official",
  "dashboards": [
    {
      "id": "github-repo",
      "name": "GitHub Repository",
      "file": "github-repo.bar",
      "protocol_version": "0",
      "version": "1.0.0",
      "category": "development",
      "description": "Track GitHub repository stars, forks, and activity.",
      "icon": "star",
      "license": "AGPL-3.0-only",
      "homepage": "https://agili.app",
      "sha256": "7c9bbe54c15a8b940486b167094a18f7f9f6f3eccad4d5c63a17e070eebacc72"
    }
  ]
}

完整源码见官方 GitHub 看板，摘要必须匹配实际发布文件的字节。

结构契约发布在 /dashboards/schema.json，仓库内位于 schemas/dashboard-registry.schema.json。

安装 ID

安装看板时，看板源 ID 与看板 ID 以双连字符组合：

{registryID}--{dashboardID}
official--github-repo
awesome--crypto-ticker

安装 ID 只存在于设备上，不会写回看板源。安装时 Metrix.Bar：

1. 通过 HTTPS 获取 .bar。
2. 用条目中的 sha256 校验原始字节，在来源记录 Source 中记为 sha256。
3. 只把根 <bar id="…"> 改写为复合安装 ID，再重新解析文档。
4. 计算改写后的文件摘要，记为 installed_sha256（磁盘上的文件与 index.json 的 sha256 不再一致，因根 ID 被改写，这是预期行为）。

来源记录同时绑定 registry_id、registry_url（规范化 Canonical URL）与 dashboard_id。绑定严格遵循 registryID + dashboardID + Canonical registry URL。若缺少来源记录或源 URL 变更，Metrix.Bar 不会接管已安装看板；本地未绑定的看板绝不猜测远端来源。

因根 ID 改写，installed_sha256 与原始分发摘要 sha256 通常本来就不同。应用据此进行两处不同的哈希比对：

• 本地修改检测：比对当前磁盘文件的实际 SHA-256 与记录的 installed_sha256。
• 上游更新检测：比对远端条目的 sha256 与记录的原始 sha256。

官方与 Awesome

• Official —— https://metrix.bar/dashboards/index.json。固定且始终启用，不能移除或停用。分发全部 16 个官方 .bar 看板——其中仅 GitHub 仓库看板同时随 App 内置，其余按需从该看板源安装。
• Awesome —— https://awesome.metrix.bar/dashboards/index.json。预置的社区索引地址，默认关闭；启用后是否可用取决于 awesome.metrix.bar 是否提供有效索引。

两者都是普通看板源，只是默认值不同。

自托管看板源

任何能在 HTTPS 上提供合法 index.json 的 URL 都可以作为看板源。要求：

• HTTPS，局域网可用 HTTP——看板源与 .bar 文件下载使用 HTTPS（任意主机与端口）；局域网主机（私网 IP、.local 等）也可用 HTTP，方便自托管。禁止凭据与 fragment，重定向必须同源。请求遵循应用的代理设置，fake-ip / TUN 代理下同样可用。metrixbar:// 链接中的地址仍只接受公网 HTTPS。
• 同源文件——每个 file 相对 index.json URL 解析且必须严格同源；重定向也必须维持原始协议与主机端口同源。
• 合法结构——文档必须符合 dashboard-registry.schema.json（schema_version: 1、slug ID、必填字段、64 位小写十六进制 SHA-256 哈希）。
• 异步校验与容错——保存看板源配置时立即持久化配置列表，网络请求与索引校验在后台异步进行。若网络请求失败或验证未通过，Metrix.Bar 保留错误状态并维持已有缓存，不会拒绝保存配置。
• ID 唯一——看板 ID 在源内唯一且符合 slug 规则（不能含 --，该符号为安装 ID 保留）。

最小自托管索引就是一个放在任意 HTTPS 主机上的静态文件（以下 SHA-256 对应原始字节 <bar protocol-version="0" version="1.0.0" id="example" category="development"><docs>Example setup instructions</docs><script><![CDATA[const id = "example";]]></script></bar>，末尾无换行）：

{
  "$schema": "https://metrix.bar/dashboards/schema.json",
  "schema_version": 1,
  "id": "my-team",
  "name": "My Team",
  "dashboards": [
    {
      "id": "example",
      "name": "Example",
      "file": "example.bar",
      "protocol_version": "0",
      "version": "1.0.0",
      "docs": "Example setup instructions",
      "sha256": "85d4f03b07795353f523e35227c575af674c6910e00e0f833bf6ed54ee6bac94"
    }
  ]
}

使用 build.js 构建看板源

为方便打包与发布自定义看板源，官网托管了独立的构建脚本，可直接下载运行：

curl -fsS https://metrix.bar/dashboards/build.js -o build.js
node build.js --input ./dashboards --output ./dist/dashboards --id my-team --name "My Team"

构建脚本特点：

• 无外部依赖：已内置 XML 解析依赖（saxes 与 xmlchars），可在普通目录、CommonJS 和 ESM 项目中运行，只需 Node 22+ 运行环境，无需 npm install。
• 不发布 npm、不设 MCP：脚本仅随官网托管供直接下载使用，不发布到 npm 仓库，也不作为 MCP 工具提供。
• 保真与摘要计算：按相对目录结构保真复制 .bar 文件，并自动计算原始字节的 SHA-256 摘要与 $schema 提示生成 index.json。
• 静态校验与运行时校验区别：build.js 仅校验 XML 语法、根属性、SemVer 规范、分类 slug 与 URL 格式等静态内容。它不会执行 Worker 脚本，也不会校验运行时环境；完整的运行时行为与渲染校验请使用本地 API 的 POST /v0/check、POST /v0/validate 或命令行 metrixbar check。

更新

Metrix.Bar 每 24 小时自动检查已启用的看板源，也可手动触发。自动流程仅查询更新，绝不静默应用更新。

• 严格 SemVer 与人工确认：更新要求 SemVer 版本严格更高且必须由用户明确确认。相同版本下远端 hash 变化视为异常并拒绝。
• 本地修改保护：比对当前磁盘文件的 SHA-256 与保存的 installed_sha256。若本地源码被修改过，更新前必须经用户明确确认；在应用更新前，Metrix.Bar 会自动在数据目录保存备份副本（<runtimeID>-local-*.bar），绝不静默覆盖本地改动。
• 并发保护：更新确认流程严格绑定目标文件的 ETag。若在确认与应用之间文件被并发修改导致 ETag 不一致，中止更新。
• 配置与 secret 兼容保留：兼容的输入项与系统凭据库中的密钥在更新后完整保留。若新版本存在移除输入项或字段类型变更等不兼容情况，更新会被拒绝，需先处理不兼容项。

安全说明

• 看板源请求走 HTTPS，带 Metrix.Bar 标准头（User-Agent: Metrix.Bar/<version>、X-Requested-With: bar.metrix）。
• 安装或更新前都会校验 sha256；不一致则中止安装。
• 看板源元数据不会授予额外权限——.bar 文件自己的 <permissions> 仍然控制网络源与文件访问，secret 仍保存在系统凭据库中。

安装链接

metrixbar://open 可唤起主窗口，metrixbar://open/<实例ID> 可选择看板，metrixbar://refresh[/<实例ID>] 可刷新一个或全部实例。实例 ID 保留解码后的值与大小写，支持点号和 Unicode。ID 须编码为单个路径段；拒绝 .、..、路径分隔符与 NUL。

metrixbar://install/github-repo 可从官方目录安装；附加 ?registry=awesome 或其他已配置来源 ID 可选择来源。禁用的来源会先请求启用确认。metrixbar://install/<id>?registry_url=<编码后的 HTTPS 索引 URL> 可从其他索引安装，确认窗口会展示来源、权限与 inputs；新来源仅在确认安装时与看板一起保存，取消不会添加来源。metrixbar://registry/add?url=<编码后的 HTTPS 索引 URL> 仅请求添加来源。

重复点击同来源、同版本、同原始 SHA-256 的 registry 安装链接会打开已有看板。应用会重新校验当前索引，不写检查时间或缓存；同版本摘要变化视为异常，更高版本仍须确认更新。

metrixbar://install?url=<编码后的 HTTPS .bar URL> 可直接导入，附加 &sha256=<64 位十六进制摘要> 可验证内容。确认窗口展示下载域名、权限与 inputs，确认后才安装运行。直链导入保留原始看板 ID 和下载来源，不提供后台更新。再次点击同 URL 时，若下载摘要与记录的原始摘要相同，即使本地文件已编辑，也会打开已有看板；摘要变化则请求再次导入确认，允许版本不变。显式摘要须先校验通过。更新保留兼容配置与 secret，本地修改需要明确允许替换并备份，准备后文件或来源变化会中止，保存失败会回滚。其他来源不能覆盖相同 ID 的已安装看板。

嵌套 URL 须编码为查询参数值。重复或冲突参数、凭据、fragment 与非法摘要会被拒绝。下载使用有大小限制的公网 HTTPS，仅允许同源重定向。多个链接会等主窗口就绪后依次处理，重复等待中的点击只处理一次；取消或关闭错误确认后可继续下一条。