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"}

1. 一旦选择用内联 HTML 交付当前回答，无论用户是否说出“内联”，整个回合都不得调用 show_file、show_url、系统浏览器或其他外部展示动作。show_file(path, viewer="rendered") 会打开 side panel，不能用来预览、验证或展示内联结果；用 read_file / exec 检查文件和内容，最终只输出上面的 Markdown 声明。只有明确决定不做内联、需要长时间阅读或操作时才改用 side panel。
2. 最终回复仍要自包含，但不要用表格、列表、数据速览或第二种图表重复内联视觉已经表达的数据。最终一次验证工具返回后，静默完成判断，不得输出核对表、计算过程、“检查通过”、引导语或数据复述；最终可见内容必须只有 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 卡片、洞察框、章节卡片或其他带独立背景/边框/阴影的矩形容器；只有某个形状本身承担数据编码或交互含义时才使用色块。