大龙虾 OpenClaw 返回 Markdown 图表规范

本文档用于规范大龙虾 / OpenClaw 助手在第三方聊天窗口中返回可视化图表数据。第三方前端会继续渲染普通 Markdown 文本和 Markdown 表格；如果回答中包含标准 openclaw-chart 代码块，前端会自动渲染为图表卡片。

1. 返回总原则

answer 字段仍然返回一段 Markdown 字符串。
普通解释、结论、列表、标题继续使用 GitHub Flavored Markdown。
表格继续使用标准 Markdown 表格。
需要展示趋势、增长率、销售额、占比、排名等指标时，在 Markdown 中追加一个或多个 openclaw-chart 代码块。
图表数据必须使用合法 JSON，不要包含注释、尾逗号、中文引号或非 JSON 内容。
图表代码块只放结构化数据，不要把说明文案写进 JSON 外的代码块内。

2. 图表代码块格式

请使用下面格式：

```openclaw-chart
{
  "openclaw_chart": true,
  "type": "combo",
  "title": "月销售额与环比走势",
  "subtitle": "2025-05 至 2026-05",
  "xKey": "month",
  "yAxisLabel": "销售额（亿）",
  "rightYAxisLabel": "环比（%）",
  "series": [
    {
      "key": "sales",
      "name": "销售额",
      "type": "bar",
      "unit": "亿",
      "yAxis": "left"
    },
    {
      "key": "mom",
      "name": "环比",
      "type": "line",
      "unit": "%",
      "yAxis": "right"
    }
  ],
  "data": [
    { "month": "2025-05", "sales": 242.48, "mom": null },
    { "month": "2025-06", "sales": 228.00, "mom": -6.0 },
    { "month": "2025-07", "sales": 208.39, "mom": -8.6 }
  ],
  "note": "sales 为销售额，mom 为月环比。"
}
```

3. 字段说明

字段	类型	必填	说明
`openclaw_chart`	boolean	建议	固定写 `true`，方便识别
`type`	string	是	图表类型：`line`、`bar`、`combo`
`title`	string	是	图表标题
`subtitle`	string	否	副标题，例如时间范围或口径
`xKey`	string	是	X 轴字段名，必须对应 `data` 中的字段
`yAxisLabel`	string	否	左侧 Y 轴说明
`rightYAxisLabel`	string	否	右侧 Y 轴说明
`series`	array	是	指标系列配置，最多建议 6 个
`series[].key`	string	是	指标字段名，必须对应 `data` 中的字段
`series[].name`	string	是	前端展示名称
`series[].type`	string	否	单个指标展示类型：`line` 或 `bar`
`series[].unit`	string	否	单位，例如 `亿`、`%`、`件`
`series[].yAxis`	string	否	`left` 或 `right`，不同量纲建议拆左右轴
`series[].color`	string	否	可选十六进制颜色，例如 `#4f8cff`
`data`	array	是	图表数据，最多建议 80 行
`note`	string	否	图表底部备注

4. 数值要求

data 中用于画图的指标值必须尽量返回数字，不要返回 "242.48亿" 或 "6.0%"。
单位放在 series[].unit 中。
没有值时使用 null，不要使用 -、无、N/A。
百分比按展示数值返回，例如 -6.0 表示 -6.0%，不要返回 -0.06。
金额、销量等字段不要加千分位逗号。

5. 推荐图表类型

场景	推荐 type	series 配置
单个指标趋势	`line`	指标 `type: "line"`
多个月销售额/销量对比	`bar`	指标 `type: "bar"`
销售额 + 环比/同比	`combo`	销售额 `bar` 左轴，环比/同比 `line` 右轴
关键词排名/品类排名	`bar`	排名值或销售额 `bar`
多指标同量纲趋势	`line`	多条 `line`

6. 完整回答示例

## 结论

2025-05 至 2026-05 期间，整体销售额先下滑后回升，10 月出现明显反弹。

## 关键数据

| 月份 | 销售额 | 环比 |
| --- | ---: | ---: |
| 2025-05 | 242.48亿 | - |
| 2025-06 | 228.00亿 | -6.0% |
| 2025-07 | 208.39亿 | -8.6% |

```openclaw-chart
{
  "openclaw_chart": true,
  "type": "combo",
  "title": "月销售额与环比走势",
  "subtitle": "单位：销售额=亿，环比=%",
  "xKey": "month",
  "yAxisLabel": "销售额（亿）",
  "rightYAxisLabel": "环比（%）",
  "series": [
    { "key": "sales", "name": "销售额", "type": "bar", "unit": "亿", "yAxis": "left" },
    { "key": "mom", "name": "环比", "type": "line", "unit": "%", "yAxis": "right" }
  ],
  "data": [
    { "month": "2025-05", "sales": 242.48, "mom": null },
    { "month": "2025-06", "sales": 228.00, "mom": -6.0 },
    { "month": "2025-07", "sales": 208.39, "mom": -8.6 },
    { "month": "2025-08", "sales": 207.82, "mom": -0.3 },
    { "month": "2025-09", "sales": 209.88, "mom": 1.0 },
    { "month": "2025-10", "sales": 249.90, "mom": 19.1 }
  ],
  "note": "环比为空的月份用 null。"
}
```

## 建议

重点关注 10 月反弹原因，并拆解品类、关键词和渠道贡献。

7. 多图表返回

同一个 answer 中可以返回多个 openclaw-chart 代码块。建议每个图表前先用 Markdown 写一句说明，避免用户不知道图表含义。

8. 兼容说明

如果前端识别不到合法图表 JSON，会按普通代码块显示。
图表卡片支持下载图表数据 CSV。
Markdown 表格仍支持横向滚动和下载表格 CSV。
前端不支持 HTML、自定义 CSS 或脚本，请不要返回这类内容。

5.5 KiB Raw Permalink Blame History Unescape Escape