zframes

zframes — 生成你的仪表板

通过运行 zframes CLI 并编写 dashboard.json 规范，为用户设置并运行仪表板。CLI 就是运行时：它会提供一个预构建的仪表板应用，该应用指向这个文件，并可在浏览器中编辑。此任务中你只会编写 JSON。切勿创建或编辑 .tsx 文件。

三项工作，一项技能——提供、更新或创建。 首先（步骤 1）判断请求属于哪一种，然后再做其他事情。“启动 / 打开 / 提供我的仪表板”只是提供用户已有的仪表板——这是仪表板创建后最常见的请求——无需进行访谈，也完全跳过 init。只有创建流程才会执行下面的完整构建流程。

0. CLI

运行时以 npm 上的 zframes CLI 形式提供。始终通过 npx --yes zframes@latest <cmd> 调用它——npx 每次运行都会获取已发布的 CLI（其中包含仪表板运行时），因此无需克隆、安装或保持更新。下面会用到的命令有 init、providers、catalogue、lint 和 serve（为简洁起见写作 zframes <cmd>——始终通过 npx 运行）。

1. 判断请求类型——提供、更新或创建

先对请求进行分类；这会决定下面所有操作，包括要读取哪些参考文件。只有四种工作中的一种需要构建任何内容；除非你确实要为用户创建一个尚不存在的仪表板，否则绝不要进行访谈或运行 init。

• 提供 / 打开 / 启动现有仪表板——“启动我的仪表板”、“打开我的终端”、“提供它”，或用户已有仪表板时直接输入 /zframes。仪表板创建后，这是最常见的情况。不要运行 init，不要进行访谈，也不要读取目录或任何参考文件。 运行 zframes list 查看已有内容，然后直接跳到步骤 6并提供仪表板：直接运行 zframes serve 会打开默认仪表板（列表中标有 *），运行 zframes serve <name> 则会打开指定仪表板。工作就这么简单。
• 更新现有仪表板——“添加 X”、“替换行情代码”、“更改主题”。运行 zframes list（* 标记默认仪表板），或找到用户正在提供的 dashboard.json / 当前目录中的一个文件。先读取文件，然后只更改用户要求的内容。如果要添加、调整大小或重新排列 frame，在编辑 frames 数组之前，请先阅读目录（步骤 2）和 references/design.md（设计方法以及卡片级字段：事件、分组、source、货币）；然后运行 lint 并提供仪表板（步骤 5–6）。不要重新运行 init——否则会清除用户现有的 frame。
• 创建全新仪表板——仅当用户想要一个尚不存在的仪表板（或明确要求在现有仪表板之外再创建一个）时才执行。为其命名并运行 init（如下所示），然后执行完整构建流程：目录概览（步骤 2）、访谈（提问前先阅读 references/interview.md）、设计（编写任何 frame JSON 前先阅读 references/design.md），然后运行 lint 并提供仪表板（步骤 5–6）。
• 复刻共享仪表板——用户提供了 zframes explorer 链接（.../dashboard/<id> 或 .../dashboard/<id>/dashboard.json），或粘贴了“fork”提示词。他们想要将这个共享仪表板放到自己的机器上，以便保留并扩展。不要进行访谈或构建——阅读 references/fork.md 并按其中的说明操作：获取、放入存储、运行 lint 并提供仪表板，然后询问用户是否要个性化调整。

唯一的产物是一个 dashboard.json。无需搭建应用——运行时由 CLI 提供。仪表板存放在全局存储中（$XDG_CONFIG_HOME/zframes/dashboards，默认路径为 ~/.config/zframes/dashboards），因此用户可以从任意位置运行 zframes，并将多个仪表板并列保存，每个仪表板都通过简短的名称（main、crypto 等）来指定。zframes list 会显示所有仪表板，* 标记直接运行 zframes serve 时会打开的仪表板。

要创建仪表板，请为其指定一个名称，并通过 init 将其初始化到存储中——不要手动编写外层结构：

npx --yes zframes@latest init <name> --title "<dashboard title>" --author "<who>"

像 crypto 这样的裸标记会在存储库中生成 <store>/dashboards/crypto/dashboard.json，并在尚无默认仪表盘时将其设为默认仪表盘（因此之后运行裸命令 zframes serve 会打开它；传入 --default 可强制设为默认）。 这会写入一个裸的、已符合规范的仪表盘——固定外层结构参照 package.json 建模：version（semver 字符串）、title、author（如果用户提供了姓名，就传入 --author；否则留空），接着是 12 列的 grid（几何参数——列数/行高/gap）、unicorn background、theme 颜色（强调色使用 accentHue/accentSat，深色卡片表面色调使用 baseHue/baseSat，涨跌颜色使用 upColor/downColor）、typography（字体系列 fontFamily：无衬线/等宽/衬线；数字样式 numericStyle：比例/等宽；全局文本大小 scale）、卡片表面的 appearance（radius/borderStrength/surfaceOpacity/density/elevation），以及显示货币 currency（默认值为 { code: "USD" }）——其中包含一个空的 frames 数组。你无需手动编写这些样板内容或其几何参数；只需填写 frames（第 4 步）。这个文件就是用户拥有的全部内容；它引用的同级文件（本地图像）放在仪表盘自己的 dashboards/<name>/ 文件夹中，因此每个仪表盘的资源彼此隔离。除非传入 --force，否则 init 不会覆盖现有文件。

（更倾向于使用普通文件而非存储库？传入路径——init ./my-dir 或 init ~/dash.json——所有命令也都接受该路径。包含 / 或 .json 后缀的标记始终视为路径；裸标记始终视为存储库名称。）

2. 阅读目录——生成前务必先阅读

目录分为两个阶段读取——完整转储（约 270 个 frame 的 JSON Schema，约 400 KB）过大，无法一次性通读，而且大部分内容并不需要。

阶段 1——浏览。 在做出任何选择之前：

npx --yes zframes@latest catalogue --summary > /tmp/zframes-summary.txt

完整阅读该文件（约 45 KB 纯文本）：按类别分组的每个 frame 的一行 名称 — 描述、类别分类，以及设计词汇表——带有精确规格值的命名主题预设，以及包含其 projectId 的背景场景。这是你在第 4 步挑选 frame 和外观元素的菜单。

阶段 2——获取实际要用的 Schema。 设计阶段确定 frame 集合后，获取这些 frame 的完整条目——配置 Schema，以及每个 frame 的设计尺寸和缩放下限（layout：w/h/minW/minH/…）——仅限这些 frame：

npx --yes zframes@latest catalogue price-liveline price-chart yield-curve ... > /tmp/zframes-frames.json

然后用文件读取器读取该文件——重定向到文件，而不是读取管道的标准输出，以免内容被截断。Frame 名称、配置字段、枚举值和尺寸都以此为准，切勿凭记忆。目录会不断增长，而你的记忆不会。未知的 frame 名称会使命令以状态码 1 退出并列出有效名称——这能帮助你发现拼写错误，和 lint 一样。

3. 采访用户——先阅读 references/interview.md

在创建流程中，构建前先采访用户——但提问前先阅读 references/interview.md。该文件包含完整的引导流程：分三轮逐步缩小范围（资产类别 → 类别 → 3–5 个具体 ticker，可选地附带一个主题预设问题）、每种资产类别的选项菜单，以及将每个类别映射到 dex 实际支持的 ticker 的xyz 符号参考。采访用于确定符号和（可选的）外观，而不是 frame；你要在第 4 步自行组装仪表盘。

4. 设计仪表板 — 先阅读 references/design.md

填充 init 脚手架文件中的 frames 数组（或更新时填充现有文件）。这是一项设计工作，不是简单堆砌，而且**references/design.md 是设计方法——编写任何 frame JSON 之前都要先阅读。**其中介绍了三个步骤（4a 应用一个主题预设；4b 根据必需的骨架精选 frame 集合，卡片数量按主题需求确定，每张卡片都放在一个有标题、表达一个想法的区域中；4c 排布布局——目录中的尺寸、每行占满 12 列、有标题的区域、层级结构，以及作为装饰和行内填充的小型资源图标块），还介绍了编写卡片时需要用到的字段：事件注释、group 集群、通过 source 将 frame 固定到第二个场地，以及每个看板／每张卡片的显示币种。

5. Lint — 反馈循环

npx --yes zframes@latest lint <name>   # the store name (or a path to a dashboard.json)

如果报告了问题，请修复 JSON 并重新运行 lint，直到检查通过。错误消息会指出 frame 实例和确切字段。对于未知的 frame 名称，消息会附上有效名称列表——请使用该列表。Lint 还会检查设计底线：frame 尺寸低于 layout 的最低要求、卡片重叠、group 子项超出其 group 自身的 columns／rows，以及 group 嵌套 group，都会导致检查失败，并指出违规的具体数值。

渲染器级别的故障（没有任何提供方支持某个 frame 的功能）会在运行中的仪表板上显示为错误卡片；请按同样的方式处理。

6. 交接——启动服务，然后打开页面

启动仪表板服务，并在用户的浏览器中打开页面——只打印链接不算交接。serve 会阻塞，因此请在后台运行（后台 shell、复用器窗口——使用你的运行环境所支持的方式），等待端口开始响应，然后打开 URL：

npx --yes zframes@latest serve <name>   # background this; the store name (or a path)
until curl -sf http://localhost:37263 >/dev/null; do sleep 1; done
open http://localhost:37263             # macOS · xdg-open on Linux · start on Windows

始终使用 http://localhost:37263 编写并打开 URL，绝不要使用纯 IP——CLI 打印的就是这个地址，也是用户预期点击的地址。请轮询端口，而不是盲目等待：如果服务器尚未绑定就打开页面，浏览器会显示连接错误。如果传入了 --port <n>，请打开对应端口。

实时数据只需安装一次，不要假定已安装。 仅安装基础包不会附带数据提供方：它会显示模拟演示数据，标题栏会标注“demo data”，并且 serve 会在启动时说明这一点。在某台机器上首次启动服务前（或每当 serve 显示演示数据提示／标题栏显示标记时），安装免费的无密钥数据集：

npx --yes zframes@latest providers add keyless   # one-time; prints what it contacts + where the terms live

这段输出正是关键——它是用户知情同意的界面，因此应让它显示出来，不要抑制。zframes providers 会列出已安装的项目。（较早发布的 CLI 没有此命令，但始终会传输实时数据——如果 providers 报错称命令未知，直接启动服务即可。）

serve 会托管指向该仪表板的预构建运行时，并在安装数据集后传输实时的无密钥数据。不带名称的 zframes serve 会打开默认存储中的仪表板；如果存储中有多个仪表板，标题栏会变成仪表板选择器——用户打开选择器，选择另一个仪表板，页面便会重新加载到该仪表板，无需重启。用户可以在浏览器中拖动、调整大小、添加和配置框架——点击 Save 会将更改直接写回 dashboard.json。文件（无论是你还是用户）中的修改都会在重新加载时显示，因此后续“在我的仪表板中添加 X”的请求只需再次编辑文件并重新加载页面。如果 37263 端口已被占用，请传入 --port <n>。

验证渲染效果是否符合设计，而不只是格式有效。 Lint 能验证 JSON，却无法看到像素。启动新建或重新布局的仪表板后，如果你有浏览器工具，请打开 http://localhost:37263 并快速检查一次：错误卡片（“Invalid configuration”“Unknown frame”、缺少功能）、卡片一直空白、行中有空缺，以及卡片内部内容被裁切——请修正规格并重新加载。标题栏中的 “demo data”标记不是错误：这表示尚未安装数据提供方——运行 zframes providers add keyless 并重启服务。（判断卡片是否为空前，请给实时数据几秒钟加载；图表的绘制动画不是错误。）没有浏览器工具？请明确告诉用户该检查哪些内容，并根据用户反馈进行修复。仅启动普通服务或进行单字段更新时，无需检查——差异本身就是验证。

硬性规则

• 用户只是想看看时，就直接打开。 如果仪表板已存在，且用户说启动 / 打开 / 提供服务（或只发送了 /zframes），就直接提供服务（步骤 1 → 步骤 6）——不要访谈，不要执行 init，也不要重新构建。只有在用户要创建新仪表板或修改现有仪表板时，才进行构建或重新访谈。 提供服务意味着在后台运行 serve，并在浏览器中打开 http://localhost:37263——用户要求“打开我的仪表板”，只打印链接不算完成任务。
• 访谈用于挑选代码，不用于挑选框架。 引导流程——资产类别 → 分类 → 具体代码，再加一个可选的主题预设问题——只用于选择标的和风格。看板由你来组装：不要询问要包含哪些框架或小部件，也不要把框架名称列出来或复述给用户选择。
• 精选并组合——两项设计原则。 卡片数量不限，但每张卡片都必须位于一个有标题、表达单一想法的区域中，且每个区域都能独立阅读；尺寸依据各框架目录中的 layout（不得超出 minW/minH → maxW/maxH 范围），每行必须排满 12 列，并且必须原样应用且只应用一个主题预设。直接倾倒目录内容或做出稀疏空壳，都不合格。
• dashboard.json 是唯一产物。不要用 React，不要写 CSS，不要新增框架。 如果用户想要的框架不存在，就如实说明并列出已有框架。
• 仅使用免费数据：29 个无需密钥的数据源——Hyperliquid（加密货币 + HIP-3 股票永续合约）、Nasdaq、CoinGecko、DeFiLlama、Deribit、Cboe、mempool.space、美国财政部、纽约联储、BLS、SEC EDGAR、FRED、LBMA 贵金属等。整个数据源集合只需执行一次 zframes providers add keyless（步骤 6）；无需配置 API 密钥——绝不要索要密钥。
• 每次会话都重新读取目录；不要依赖记忆中的框架名称。