160 lines
5.5 KiB
Markdown
160 lines
5.5 KiB
Markdown
# 大龙虾 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 或脚本，请不要返回这类内容。
|