# Visualize Output > Create clear, restrained visual presentations for answers and results by choosing among Markdown, tables, Mermaid, images, and self-contained inline HTML. Use when the user asks for a visualization, chart, diagram, comparison, timeline, status/result view, or when spatial layout would materially improve understanding in the current conversation; read this skill before any other visualization tool call or inline display of an existing app. Use nextclaw-app-creator instead for reusable apps, editors, or sustained workflows. - Skill: `peiiii/visualize-output` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add peiiii/visualize-output` - Raw SKILL.md: https://api.skillmd.com/api/skills/peiiii/visualize-output/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: peiiii (https://skillmd.com/u/peiiii) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/peiiii/visualize-output --- # Visualize Output 让可视化服务于理解，而不是只增加装饰。始终选择能够清楚表达结果的最小展示方式；如果普通文字已经足够，就不要为了“好看”强行可视化。 ## 选择展示方式 - 简单事实、结论或短步骤：使用自然的 Markdown 段落或短列表。 - 多组精确映射、字段比较或数值对照：使用紧凑表格。 - 流程、时序、层级、依赖或状态迁移：优先使用聚焦的 Mermaid 图。 - 需要真实视觉形象、空间构图或插画表达：在具备图片生成/处理能力时使用图片。 - 布局、排版、图形编码或轻量交互能显著提升理解：使用自包含的内联 HTML。 - 可复用应用、编辑器、管理台、大表格、多页界面或持续工作流：不要塞进当前回答；读取 `nextclaw-app-creator`，改用 Panel App / side panel。 同一关系默认只选一种主要可视化，不要把表格、Mermaid 和 HTML 重复堆叠。必要的文字说明保持简短，并让可视化本身承担主要信息表达。 ## 单一焦点 - 一个可视化只回答一个主要问题，突出一个核心结论或一组紧密相关的数据。 - 默认不要制作带导航、侧栏、标签页、工具栏和多块 KPI 的“大而全 dashboard”。 - 使用留白、对齐、字号和必要的细分隔线建立层级；不要靠页标题、总背景板或把每一组内容包成卡片来制造结构。 - 如果内容无法在一个聚焦表面里讲清，先删减、分层摘要，或改用 side panel；不要缩小到难以阅读。 ## 内联 HTML 合同 仅当 HTML 比 Markdown / Mermaid 明显更清楚时使用： 1. 先创建目标文件的父目录，再创建一个真实存在、可独立打开的 `.html` 文件；写入后确认文件存在。只为当前会话展示而生成的可视化属于 NextClaw 持久资产，必须放到系统上下文给出的 `NEXTCLAW_HOME/assets/visualizations//` 绝对目录，并在声明中使用绝对路径。不得放到 `/tmp`、其他临时目录、当前项目或工作目录根部；只有用户明确要求项目交付文件时，才写入用户项目。 2. 默认把 CSS、JavaScript 和 SVG 内联在文件中，不依赖 CDN、远程字体、远程脚本或不可验证的网络资源。 3. 在最终回复中输出 inert 的 `nextclaw-inline` 声明，让宿主把文件直接渲染在消息内。当前任务生成的本地 HTML 必须使用 `file` target；禁止改成 `url` target，也不要把本地路径伪造成 `/somewhere/file.html`： ```nextclaw-inline {"target":{"type":"file","payload":{"path":"/Users/example/.nextclaw/assets/visualizations/session-123/result.html","viewer":"rendered"}},"title":"Result"} ``` 4. 一旦选择用内联 HTML 交付当前回答，无论用户是否说出“内联”，整个回合都不得调用 `show_file`、`show_url`、系统浏览器或其他外部展示动作。`show_file(path, viewer="rendered")` 会打开 side panel，不能用来预览、验证或展示内联结果；用 `read_file` / `exec` 检查文件和内容，最终只输出上面的 Markdown 声明。只有明确决定不做内联、需要长时间阅读或操作时才改用 side panel。 5. 最终回复仍要自包含，但不要用表格、列表、数据速览或第二种图表重复内联视觉已经表达的数据。最终一次验证工具返回后，静默完成判断，不得输出核对表、计算过程、“检查通过”、引导语或数据复述；最终可见内容必须只有 `nextclaw-inline` 声明，声明的关闭围栏就是回复最后内容。不要描述它位于“右侧”“侧栏”或其他未经执行的 UI 位置。 ````markdown ```nextclaw-inline {"target":{"type":"file","payload":{"path":"/Users/example/.nextclaw/assets/visualizations/session-123/result.html","viewer":"rendered"}},"title":"Result"} ``` ```` ## HTML 画布合同 - 把整个 HTML 文档当成唯一展示表面。`html` / `body` 默认保持透明、无边框、无阴影，只有承载内容所需的内边距；不要再放带背景、外边框、圆角或阴影的根容器。 - 默认不放可见的页面标题、眉题、报告名或说明横幅，直接从核心图形与数据开始。只有标题本身是用户要求展示的信息时才保留；`nextclaw-inline.title` 只是宿主元数据，不得在 HTML 中重复渲染。 - 不要在 HTML 内重复文件名、预览标题栏、打开按钮或工具栏；宿主会在外部提供这些操作，并负责圆角裁切。 - 使用响应式宽度、`box-sizing: border-box` 和自然文档高度；禁止固定桌面宽度、横向滚动和依赖超宽画布。 - 宿主从约 `240px` 高度开始按内容增长，可见上限为 `min(90vh, 1440px)`。优先把完整核心信息控制在一屏内，并确保不超过 `1440px` 仍能理解。 - 不依赖 document 级内部滚动。若内容超过可见上限，先删减、改成摘要或换 side panel；只有短列表、下拉菜单等局部控件可以有限滚动。 - 页面本身就是视觉容器。内部需要分组时优先用间距、对齐、排版或细分隔线。默认不使用 KPI 卡片、洞察框、章节卡片或其他带独立背景/边框/阴影的矩形容器；只有某个形状本身承担数据编码或交互含义时才使用色块。 ## 视觉质量 - 先建立信息层级，再添加装饰。突出主要结论，弱化辅助信息，并让阅读顺序一眼可见。 - 使用系统字体、克制的色板和最多一个主要强调色；避免无意义渐变、玻璃拟态、厚重阴影、霓虹效果和持续动画。 - 让布局在窄宽度和宽屏下都能成立。长标签换行或缩短，图表与 SVG 使用响应式尺寸。 - 对数据可视化标明必要的标题、单位、时间范围、坐标或图例；不补造缺失数据，不用面积或透视效果夸大差异。 - 保持用户提供的时间粒度、口径和语义限定不变；季度数据不能擅自改成月度数据，累计值、时点值、比率和预测值也不能互相替换。 - 默认只陈述用户输入直接支持的事实与数学关系。除非用户明确提供依据并要求分析，否则不补造因果假设、行业正常区间、目标值、优化幅度、未来影响或行动收益。 - 衍生值必须能由已给数据完整推导，并在需要时标注公式与假设；不能完整推导的行业基准、增长幅度、收益预测或因果结论必须删除，而不是用“可能”“通常”等措辞弱化后保留。 - 任何合计、差值、占比、增长率或完成率都必须先用计算工具或 `exec` 得到结果，不得心算后直接写入。写完后重新读取最终 HTML，把每个展示的数字与用户输入和工具计算结果逐项对照；无法完成逐项核对的衍生值直接删除。 - 只计算表达用户问题所必需的衍生值。用户未要求时，默认不额外增加环比、同比、复合增长或“累计增长”等指标；确需展示时必须使用与公式严格一致的名称，区间首尾增幅不能写成累计增长。 - 写 HTML 前先形成“用户可见数据白名单”：只包含用户原始值和表达当前问题所必需、已经由工具计算的衍生值。HTML 中每个用户可见的数据值都必须来自这份白名单；验证过程中的中间值、几何参数或顺手算出的指标不得进入画布。 - 总体目标只能与同口径的总体实际值比较。不得把类别值除以总体目标后称为该类别的“目标占比”“目标完成率”或类别目标；没有用户提供的类别目标，就不展示任何类别目标语义。 - 没有用户提供的阈值或比较基准时，不使用“健康、正常、不错、偏高、偏低”等定性判断，只陈述增减、排序、占比和可验证差值。 - 建议、诊断方向和优先动作也属于分析，不能因为看似常识就自动成立。用户只要求呈现或摘要已给数据时，到“发生了什么”为止，不延伸“为什么”或“怎么办”。 - 保证文字与背景对比度、可辨识的非颜色编码、语义化结构和键盘可达性；动画必须有信息价值并遵守 `prefers-reduced-motion`。 - 使用用户当前语言，避免在可视化里混入内部实现说明、文件路径或无关品牌文案。 - 可按 `prefers-color-scheme` 提供明暗配色，但两种模式都必须保持清晰、克制和可读。 ## 发送前检查 - 这个可视化是否真的比短 Markdown 更容易理解？ - 是否只有一个主要焦点，没有重复媒介和 dashboard 式堆叠？ - HTML 是否把页面本身当作表面，没有额外总卡片、文件名或内部工具栏？ - HTML 是否直接从核心内容开始，没有重复页标题、眉题、报告名、根背景板、KPI 卡片或洞察框？ - 核心内容是否能在 `min(90vh, 1440px)` 内完整理解，且没有 document 级滚动？ - 数据、单位、标签、对比度和交互是否真实、清楚、可访问？ - 是否已逐项对照用户输入核对时间粒度、单位、标签和衍生值？所有未被输入直接支持的定性评价、因果解释、诊断建议、行业区间、目标值和预测是否已经删除？ - 是否用工具计算了每个衍生值，并重新读取最终 HTML 逐项核对了其中展示的所有数字？ - HTML 的用户可见数值是否全部来自展示白名单，且没有把总体目标错误拆成类别目标？ - 内联 HTML 文件是否真实存在，路径是否正确，声明是否使用 `viewer: "rendered"`？ - 会话生成的可视化是否位于系统指定的 NextClaw 持久资产目录，而不是 `/tmp`、临时目录、用户项目或工作目录根部？ - 最终回复是否只有内联声明，并在声明关闭围栏处立即结束，没有验证叙述、引导语或数据复述？ ## 专项展示协议 Mermaid: use a focused fenced `mermaid` block and quote punctuated labels; ASCII/code-fence substitutes do not count. Prefer it for 3+ ordered, dependent, owned, or feedback-linked nodes unless prose is unambiguous. A table already counts as visualization; escalate only when requested or a graphic reveals a material pattern. 仅当将输出 inline HTML、inline JSON 或展示已有 Panel App 时，继续读取 [inline 展示协议](references/inline-display.md)，再生成声明或执行展示操作。普通文本、表格和 Mermaid 不读取该 reference。展示已有应用不要求创建、修改或安装应用。完整规则若被压缩移出上下文，执行前重新读取。