# 大龙虾 OpenClaw 返回 Markdown 图表规范

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

## 1. 返回总原则

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

## 2. 图表代码块格式

请使用下面格式：

````markdown
```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`。
- 金额、销量等字段不要加千分位逗号。

推荐：

```json
{ "month": "2025-06", "sales": 228.0, "mom": -6.0 }
```

不推荐：

```json
{ "month": "2025-06", "sales": "228.0亿", "mom": "-6.0%" }
```

## 5. 推荐图表类型

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

## 6. 完整回答示例

````markdown
## 结论

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 或脚本，请不要返回这类内容。