visualize

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>。