visualize git:20261020.fcf8b55A

Immutable. This exact content never changes and is served at /api/v1/blob/87955d054f0816dc.

---
name: visualize
description: 回答里有数字比较、趋势、构成、流程、结构、机制或"参数变了会怎样"，一张图比一段话更快让人看懂时，用 render_visual 画可交互的图表、示意图、讲解或对比卡片。用户说画一下、可视化、做个图、对比一下、演示原理、讲讲怎么运作时使用。
---

# Visualize

`render_visual` 把一段 HTML 渲染成回复里的交互图。它不在常驻工具里：先用 `load_tools` 传入插件工具目录中
visuals 的准确 ID（形如 `visuals@release`）取得 schema，再用 `tool_call` 传入 `name: "render_visual"` 和参数调用。

## 什么时候画

图要替用户省力：扫一眼就能得到读一段话才能得到的东西，才值得画。

适合画：两个以上的数要比大小、看排名或占比；一组数随时间变化；流程、步骤、因果链；
东西里面套着东西的结构；靠空间位置才讲得清的原理；"如果把 X 调大会怎样"。

不要画：答案是一个数、一句话或几条短列表；用户要代码、原文、清单或纯文字；
没有真实数据（不为数据图编数）；话题沉重（疾病、死亡、灾难、冲突、个人困境）时只在确实帮助理解时画，
样式平实，不玩修辞。拿不准就先用文字回答，再问要不要画。

## 按意图选形式

先问用户想**查阅**还是想**理解**：查阅要一张准确的地图，理解要一个对的心智模型。
同一个主题，问法不同，图就不同——看动词，不看名词：

| 用户在问 | 形式 | 画什么 |
|---|---|---|
| 一两个关键数 | 指标 | hero 数字或指标卡，不画图 |
| 比较、排名、趋势、构成、两量关系 | 数据图 | `ak` 图表，见 `charts.md` |
| "流程是怎样的""经过哪些步骤" | 流程图 | 方框加箭头，见 `diagrams.md` |
| "由哪些部分组成""架构是什么" | 结构图 | 容器套区域，见 `diagrams.md` |
| "它是怎么运作的""为什么会这样" | 机制示意 | 画机制本身，能操作就加控件，见 `diagrams.md` |
| "调大会怎样""帮我算算" | 交互讲解 | 滑块加实时读数和图，见 `interactive.md` |
| "这几个选哪个" | 对比卡片 | 每个选项一张卡，见 `interactive.md` |

内容是解释性的就用编辑式版式（无外框，留白即容器）；内容是一个有边界的对象（一张名片、一张收据）就用一张卡片包住。

## 复杂度预算

- 一张图只讲一件事。方框里只写名称，最多八九个字，解释写在正文。
- 一行最多四个方框；用户一口气列了六个以上组件，先画只有方框的总览，再每个子流程单独一张图。
- 颜色最多两种强调色加中性色；颜色表达含义时加一行图例。数据图最多四个系列，再多就并入"其他"。
- 正文里写了"点开看细节"，图本身就必须真的精简。

## 调用顺序

1. 按形式读对应写法（路径相对本技能目录），只读用得上的：`charts.md`、`diagrams.md`、`interactive.md`；
2. 先用文字讲直觉或结论，再调用 `render_visual`。解释、标题和总结都写在正文里，图里只放图；
   示意图、多元素布局这类坐标容易出错的图，先加 `draft: true` 打草稿（见下节），简单的数据图直接发布；
3. 主题复杂就拆成几张图，按顺序讲；两张图之间写一两句话衔接，说了几张就真的画几张；
4. 成功后接着说图里该看什么，不复述图里已有的数字和标签；
5. 每一步最多并行两次调用。

## 先打草稿，再发布

正式调用一次，用户就看到一张图；发布之后再为外观重画，用户会看到两张。所以外观问题在发布之前解决：

1. 带 `draft: true` 调用：照常渲染并回传 720px 宽的截图，但不展示给用户；
2. 能看图时逐项检查：文字和文字、文字和线条有没有重叠；标签有没有被截断或超出边界；
   箭头有没有穿过不相干的方框；留白是否失衡；颜色和图例是否对得上；
3. 有问题就改完整 HTML 再打一次草稿，草稿最多三次；没问题就省略 `draft`，用同样的参数正式发布；
4. 正式发布的结果也带截图，这时只为脚本报错这类真正坏掉的情况重画；
   只是"可以更好看"不算问题。

结果里写着当前模型不接收图片时，草稿看不到效果，以后直接发布。

渲染报错、空白、横向溢出、出现 NaN 时，草稿和正式调用都会直接失败并返回原因，图不会展示，按原因改完再调用即可。

## 通用规则

- `html` 是 body 片段，可含内联 style、script、SVG、Canvas；不依赖网络、外部库、宿主 API、iframe、
  表单提交或导航，也不放外链。最多 200,000 个字符。
- **无缝**：背景透明，不加外框和底色，不重复正文标题，看起来像聊天的一部分。
- **扁平**：不用渐变、阴影、模糊、发光和装饰纹理；不用 emoji，图标用简单的 SVG 形状。
- **宽度**：适应 280px 与 720px，不横向溢出；网格列写 `minmax(0, 1fr)`，宽表格用 `table-layout: fixed`。
- **颜色只用主题 token**，深浅色自动适配，不写死 #333 这类颜色：文字 `--ak-color-text-primary/secondary/muted`，
  线条 `--ak-color-border-default/strong`，底面 `--ak-color-bg-canvas/surface`，强调 `--ak-color-action-primary`，
  系列 `--k1`…`--k6`、`--k-gray`、`--k-hot`。想象背景变成近黑色，每段文字是否还读得清。
  只有描绘真实物体颜色（天空、水、皮肤）时才写死颜色，并整组写死。
- **字体**：图里的文字用 `--ak-type-ui`，最小 12px；只用常规和加粗两种字重；不用全大写，不在句中加粗。
- **圆角**：控件 8px，卡片 12px；只有单侧边框时不加圆角。
- 不用 `position: fixed`、全屏 API 和内部滚动区；高度由内容撑开。
- 显示出来的每个数都要取整（`toFixed`、`Math.round` 或 `Intl.NumberFormat`），滑块设好 `step`。
- **无障碍**：HTML 图以 `<h2 class="sr-only">` 开头写一句话概括；独立 SVG 加 `role="img"`，第一个子元素是
  `<title>` 和 `<desc>`。