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/<session-id>/ 绝对目录，并在声明中使用绝对路径。不得放到 /tmp、其他临时目录、当前项目或工作目录根部；只有用户明确要求项目交付文件时，才写入用户项目。
2. 默认把 CSS、JavaScript 和 SVG 内联在文件中，不依赖 CDN、远程字体、远程脚本或不可验证的网络资源。
3. 在最终回复中输出 inert 的 nextclaw-inline 声明，让宿主把文件直接渲染在消息内。当前任务生成的本地 HTML 必须使用 file target；禁止改成 url target，也不要把本地路径伪造成 /somewhere/file.html：

{"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 位置。

```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 展示协议，再生成声明或执行展示操作。普通文本、表格和 Mermaid 不读取该 reference。展示已有应用不要求创建、修改或安装应用。完整规则若被压缩移出上下文，执行前重新读取。