跳到主要内容

图表样式手册

这是一份关于"优秀的" Blocklens 图表应如何呈现的规范参考。它提炼了贯穿约 70 个内置模板（chart-templates）、数据库种子模板（template-seeds）以及 the chart renderer 渲染行为所体现的各项规则。

两类受众：

  1. 前端 / 模板作者——在设计新模板或种子数据时应用这些规则。
  2. Buddy 的 lab-author 技能——加载这些规则的精简副本，使 AI 生成的图表配置符合精选目录的视觉语言。

如果下文某条规则与某个模板当前的做法相矛盾，出于历史遗留原因以模板为准，但新工作应遵循本指南。

1. 坐标轴​

1.1 价格始终位于右侧 Y 轴，采用对数刻度​

每个叠加 BTC 价格的模板都将价格放在单独的右轴上，并设置 scale: "log"。主要指标放在左轴。将价格在视觉上关联、却在数值上分离，可以让快速增长的指标（持仓量、AUM、供应量）和价格都保持可读性。

例外：价格模型模板（realized_price、transferred_price）将价格与模型放在同一轴上，以便用户在同一刻度上比较两个价格。该轴为对数刻度。

1.2 共享单位的指标共享同一坐标轴​

  • lth_supply + sth_supply → 同一左轴（均为 BTC）。
  • lth_mvrv + sth_mvrv → 同一左轴（均为比率）。
  • 资金费率（%）在左轴，价格（USD）在右轴——单位不同，坐标轴不同。

不要将两个范围差异极大的指标堆叠在同一线性轴上。较小的序列在视觉上会被挤压。

1.3 周期对比：allLeftAxis: true + 对数刻度​

周期表现模板（如 cycle-perf-low、cycle-perf-ath、cycle-perf-halving）强制使用 allLeftAxis: true 并配合 yAxes: [{ side: "left", scale: "log" }]。多个周期叠加在同一对数轴上，从而可以跨周期比较指数式增长。

1.4 坐标轴标签颜色​

  • 多个不同颜色的序列共享一个坐标轴 → 轴标签使用中性深灰色 #6b7280。
  • 单一指标独占一个坐标轴 → 标签可以继承该指标的颜色（很少使用；灰色是稳妥的默认值）。

2. 刻度选择​

使用线性使用对数
供应量、流量、计数、USD 数值、市值BTC 价格（始终）
比率（MVRV、SOPR）、百分比、资金费率单独显示的股票指数（SPY/QQQ/IWM）
每日增量、净变化价格模型（realized_price、transferred_price）
任何在有界范围内波动的指标周期表现叠加

如果某个指标在可见窗口内跨越超过约 2 个数量级，优先使用对数。

3. 各指标的图表类型​

样式适用场景fillOpacity
area持仓量、供应量、累计流量、AUM、堆叠队列0.3
line比率（MVRV、SOPR）、费率（资金费率）、价格叠加0.1
bar每日 / 30 日增量（净流量、供应量 30D Δ）0.5
candlestick仅 OHLC—

对数轴上的柱状图渲染后无法辨读——柱状图请保持线性。

4. 配色方案​

4.1 按领域​

领域元素十六进制
价格叠加BTC 价格（中性）#6b7280
供应LTH#2563eb
供应STH#dc2626
供应第三队列#fbbf24 / #FFBB28
ETF持仓量#f59e0b
ETFAUM#3b82f6
ETF净流量#10b981
ETF累计流量#059669
ETF主导度#8b5cf6
ETF美国持仓量#3b82f6
ETF实现价格#dc2626 / #ea580c
DAT总持仓量#F7931A（Bitcoin 品牌色）
DAT上市公司#0088FE
DAT政府#FF4444
DAT私有公司#FFBB28
DAT净变化#82ca9d
DAT主导度#ff7300
资金费率费率#3b82f6
资金费率价差#f97316
资金费率过热区间rgba(239,68,68,0.1)
资金费率投降区间rgba(34,197,94,0.1)
宏观收益率（中性）#6b7280
宏观通胀#f59e0b
宏观VIX / 风险#ef4444
周期 1→4紫罗兰 → 蓝 → 绿 → 橙#8b5cf6 → #3b82f6 → #22c55e → #f97316

4.2 多指标着色​

当两个相关队列一同出现时（LTH/STH、美国/非美国、上市/私有），使用既定配对（LTH/STH 用蓝 + 红），以便用户学习一套统一的心智模型。不要为每张图表重新发明配色。

5. 参考线与参考区域​

仅在阈值具有清晰解释意义时使用：

  • 资金费率 > 20% → 红色阴影区域，标签"过热"。
  • 资金费率 < -10% → 绿色阴影区域，标签"投降"。
  • SOPR = 1.0 → 在盈亏平衡处的参考线（机会点——尚未纳入模板）。
  • MVRV = 1.0 → 在公允价值平价处的参考线。

避免使用没有数值含义的装饰性线条。每张图表最多一到两个标注。

"referenceAreas": [
  { "y1": 20, "y2": 100, "yAxisId": "axis-left", "fill": "rgba(239,68,68,0.1)", "label": "Overheated" },
  { "y1": -100, "y2": -10, "yAxisId": "axis-left", "fill": "rgba(34,197,94,0.1)", "label": "Capitulation" }
]

6. 日期范围默认值​

预设适用场景
ALL长期趋势指标——供应量、估值、周期叠加，以及任何用户希望完整查看其长历史的指标。
1Y多年视图会掩盖信号的噪声型指标——每日净流量、DAT 净变化、资金费率价差。
1W / 1M绝不作为默认值——这些是由用户驱动的缩放级别。

7. 样式常量​

除非有图表特定的理由，否则请在各处统一使用：

  • 所有线条使用 strokeWidth: 2。
  • 区域使用 fillOpacity: 0.3，线条叠加使用 0.1，柱状图使用 0.5。
  • instanceId 格式：{metricId}-{seq}（如 price-1、lth_supply-1）。在编辑过程中保持稳定。

8. 命名约定​

  • 图表名称——名词短语，像列标题一样采用首字母大写。≤60 个字符。不使用表情符号。
    • 良好：BTC LTH Supply with 30D Change、ETF Net Flow vs. Price
    • 不良：📈 Bitcoin Long-Term Holders!!! (2024)
  • 描述——一句话描述图表展示的内容以及它揭示的洞察。
    • 良好：Long-term holder supply with 30-day delta bars to surface accumulation and distribution waves.

9. 反模式​

在审查模板或 AI 生成的配置时，拒绝以下做法：

  • 在双轴布局上只放单一指标——空置的坐标轴是浪费的空间。
  • 在一个坐标轴上放超过 4 条序列且未堆叠——视觉上无法辨读。
  • 在单一线性轴上混合范围差异极大的指标（例如计数 1-2M 与价格 20k-100k）——较小的序列会不可见。
  • 将 BTC 价格放在线性轴上且与高增长指标配对——价格会在视觉上占据主导。
  • 没有数值含义的装饰性参考线——增加噪声而非信号。
  • 对数刻度上的柱状图——渲染后无法辨读。
  • 逐图定制的配色——破坏用户已习得的颜色关联。

10. lab-author 技能快速参考​

当 Buddy 从自然语言构建图表配置时：

  1. 通过 search_metrics / get_metric 解析指标 ID。确认每个指标的 grade 在用户的订阅层级范围内。
  2. 决定坐标轴布局：
    • BTC 价格是序列之一吗？→ 价格放右轴并设置 scale: "log"，主要指标放左轴。
    • 其余指标共享单位吗？→ 同一坐标轴。单位不同？→ 不同坐标轴。
  3. 按 §3 选择图表样式。
  4. 按 §4.1 选择颜色——使用该领域的既定配色。
  5. 按 §2 选择刻度。
  6. 按 §6 选择日期范围。
  7. 仅在阈值具有清晰含义时添加参考线/参考区域（§5）。
  8. 应用样式常量（§7）和命名约定（§8）。
  9. 在保存前运行反模式检查清单（§9）。

11. 模板存放位置​

  • 静态（前端）——chart-templates。约 70 个模板在应用启动时加载。
  • 数据库（templates 表）——由 template-seeds 种子化的精选模板，并通过 the templates API 对外提供。
  • 用户创建（user-charts 表）——本指南其余部分所讨论的内容。通过 Lab UI、派生模板，或 Buddy 的 save_chart MCP 工具保存。

配置 JSON 的结构（metrics、formulas、yAxes、dateRange、referenceLines、referenceAreas 等）在全部三种来源中完全一致——TypeScript 定义参见 the Lab API client 中的 the chart config，Pydantic schema 参见 the API schema。