可视化（profy-visualize）

一句话定义

profy-visualize 让专家把可视化结果直接画在对话里——图表、3D 展品、地理地图、交互式界面——而不是给你一段代码或一张静态图片。产出是可交互的（能悬停、能旋转、能点击），并且平台提供了配套的自检工具让模型在给你看之前先验证渲染有没有出问题。

激活条件

字段	取值
插件 ID	`profy-visualize`
`user_selectable`	`true`——在插件面板里手动勾选
`conditions`	`{ "sandbox_mode": "!none" }`（需要沙箱，非 `none` 模式）
注入工具	`visualize` / `inspect_3d` / `render_ui` / `browser`
注入提示词	`VISUALIZE.md` / `3D.md` / `DATA_VIZ.md` / `A2UI.md`
声明技能	8 篇（目录下另有 14 篇可按需加载，见下）

browser 工具是故意被这个插件一起绑定的：视觉校验流程要调 browser(action='screenshot')，如果你只勾了 Visualize 而没有浏览器能力，提示词里引用的工具就不存在，自检环节会整个失效。这也是为什么单独勾选 Visualize 时你会看到浏览器工具也被激活。

三个渲染工具怎么选

这是使用这个插件时唯一需要理解的判断，其余都是模型的事。

工具	产出	用在什么场合
`visualize`	沙箱 iframe 里的 HTML/CSS/JS	定制视觉：图表、3D、动画、模拟
`render_ui`	原生 React 组件（A2UI）	布局 + 数据 + 操作：卡片、表格、价格对比、状态面板
`inspect_3d`	结构化诊断 JSON	不产出画面，用来检查 Three.js 场景健康度

判断口诀写在提示词里：输出是「布局 + 数据 + 动作」用 render_ui，输出是「自定义画面」用 visualize。两者最实际的差别在于观感一致性：render_ui 渲染出来的东西和 Profy 界面本身是同一套设计系统（因为就是同一批 React 组件），而 visualize 是 iframe 里的独立世界，好看与否完全取决于模型写的 CSS。所以做「一张对比表」用 render_ui 会比让模型手写 HTML 表格稳定得多。

visualize：内联 HTML 可视化

参数

参数	类型	必填	说明
`title`	string	是	可视化的简短标题
`html`	string	是	HTML 片段，可含内联 `<script>` 与 `<style>`
`css`	string	否	额外注入的 CSS

沙箱与网络

渲染发生在 sandboxed iframe 里，默认无网络访问。但 CDN 是放行的——这是唯一的例外，因为几乎所有可视化库都靠 CDN 引入。已验证可用的源：

https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js
https://cdn.jsdelivr.net/npm/d3@7/+esm
https://cdn.jsdelivr.net/npm/vega-lite@5/+esm
https://cdn.jsdelivr.net/npm/vega-embed@6/+esm
https://cdn.jsdelivr.net/npm/@observablehq/plot@0.6/+esm

jsdelivr / unpkg / cdnjs 三个域名放行，其他外部请求会被 iframe 沙箱拦掉。这意味着可视化不能实时拉你的 API 数据——数据必须由模型内联进 HTML。对于几百行的数据集这没问题，几万行就需要先在沙箱里聚合再内联。

设计规范（提示词层强制）

模型被要求遵守六条：

自包含：所有东西在一个 HTML 片段里，不引用外部文件
响应式：width: 100%，高度典型值 400–600px
明暗自适应：用 color-scheme: light dark 或 prefers-color-scheme
可交互：该有悬停提示、点击、缩放平移的地方要有
可访问：关键元素带 ARIA 标签
性能：DOM 元素控制在 1000 以内，大数据集走 canvas/WebGL

第 6 条是实践中最容易撞的：用 <div> 画一万个点的散点图会让页面卡死，必须换 canvas。

视觉自检循环（这个插件最有价值的部分）

提示词里写死了一套「Vision in the Loop」协议——模型在把结果给你看之前必须先自己看一眼：

生成或修改代码

写出 HTML 片段

截图

browser(action="screenshot", html=<your_html>)

读图

image(action="read", image_urls=[...], prompt="检查渲染、构图、标签、可见错误")

自己分析

按症状对照：画布全白 → WebGL 上下文错误或脚本报错；元素缺失 → 几何/材质/光照问题；布局错位 → 相机或位置缩放；坐标轴没了 → scale domain 或 append 顺序；数据没渲染 → 数据绑定或解析错误

有问题就回到第 1 步

修完重新截图，直到看起来对了才呈现给用户

这条协议是这个插件与「让模型直接写个图表」之间的核心差别。没有它，模型交付的是它认为应该长成的样子；有了它，交付的是它确认真的长成的样子。

render_ui：声明式原生界面（A2UI）

参数

参数	类型	必填	说明
`components`	array	是	A2UI 组件定义数组，每个必须有 `type`
`surface_id`	string	否	稳定的界面标识，省略则自动生成 uuid4

协议版本固定为 0.9.1。

组件类型

Card / Row / Column / Text / Button / Image / Table / PricingTable，可通过 children 数组嵌套。

校验会先于渲染

每个组件（含所有层级的 children）都会被递归校验必须带 type 字段。校验不通过时返回的是错误详情而不是界面：

{
  "error": "Invalid component structure",
  "details": ["components[0].children[2]: missing required `type` field"]
}

错误信息带完整路径（components[0].children[2]），所以模型能精确定位问题。children 不是数组时也会被指出（.children: must be an array）。

render_ui 渲染的是原生 React 组件，不走 iframe。所以它没有 visualize 的网络限制问题，但也不能跑任意 JS——你只能用平台提供的组件类型。这是安全性与灵活性的取舍：能力上限低，但产出必然和产品设计系统一致。

inspect_3d：Three.js 场景诊断

这个工具不产出画面，它回答「我刚渲染的 3D 场景到底健不健康」。

参数

参数	默认	说明
`url`	无	检查前先导航到的 URL；省略则检查当前页（配合 `browser(set_html)` 用）
`max_depth`	5	场景树遍历最大深度
`include_materials`	true	是否输出材质清单
`include_animations`	true	是否输出动画片段列表
`performance_audit`	true	是否输出性能报告与告警

前提：场景必须被暴露出来

工具通过 CDP 注入 JS 遍历场景图，页面必须把场景挂在 window.__THREE_SCENE__ 或 window.scene 上。没挂就会拿到：

Three.js scene not found. Expose via window.__THREE_SCENE__ or window.scene

这不是 bug 而是契约——写 Three.js 代码时顺手加一行 window.__THREE_SCENE__ = scene; 就能让整个诊断链路可用。

它会告诉你什么

告警	触发条件	含义
`WebGL not available`	拿不到 WebGL 上下文	环境问题，画面必然全白
`WebGL error on active canvas: <err>`	canvas 上有 WebGL 错误	着色器/纹理/缓冲区出错
`Three.js scene not found...`	场景未暴露	加一行全局赋值
`High triangle count: <n>`	三角面 > 1,000,000	需要减面或用 LOD
`High draw calls: <n>`	draw call > 100	需要合并几何体或用 instancing

「画面全白」这个症状在 3D 里非常常见且难以从截图判断原因——可能是 WebGL 挂了、可能是相机看错方向、可能是场景根本没物体。inspect_3d 的价值就是把这三种情况区分开。

双模式支持

沙箱模式走 CDP，桌面模式走 browser 工具路由，两边行为一致。解析失败时会返回 {"raw_output": ..., "warnings": ["Could not parse inspection result as JSON"]} 而不是抛错，所以拿到 raw_output 说明注入执行了但输出格式异常。

技能层

manifest 显式声明 8 篇技能，这 8 篇的正文会被注入进提示词： visualize / threejs-showcase / molecular-visualization / data-visualization / d3-data-visualization / geospatial-visualization / statistical-visualization / a2ui-patterns 但插件目录下实际有 22 个技能目录。平台的技能注册表会递归扫描 plugins/builtin/*/skills/ 下所有 SKILL.md，所以另外 14 篇同样能通过 skill 工具按名加载，只是不会默认占用上下文： 3d-data-visualization / accessibility-visualization / canvas2d-data-visualization / dashboards-realtime / gantt-chart / grammar-of-graphics / interactive-3d-atlas / node-link-diagram / react-nextjs-visualization / reports-pdf-slides / scrollytelling / threejs-data-visualization / uml-architecture / visualization-strategy

这是一条通用规律，不止 visualize：manifest 的 skills 列表 = 默认注入的，目录里的 SKILL.md = 可按需加载的。前者花上下文买确定性，后者省上下文但需要模型主动去取。所以你说「用甘特图展示排期」时模型会先去加载 gantt-chart 再动手，中间那一步不是它在磨蹭。

可执行示例

数据图表

这是我们过去 12 个月的营收和成本数据（贴表格），
画一张双轴图，营收用柱状、成本用折线，悬停显示具体数值和当月利润率。

模型会选 visualize + D3 或 Vega-Lite，画完截图自检，确认坐标轴和悬停都正常后再给你。

3D 产品展示

做一个可以拖拽旋转的产品展台，展示一个圆角立方体，
带环境光和一盏主光，底部有阴影。要能看清材质质感。

这类需求会触发 3D.md 提示词与 threejs-showcase 技能，并在渲染后调 inspect_3d 确认 draw call 和三角面在合理范围。

结构化对比界面

把这三个方案做成一张对比卡片，每个方案列出价格、适用规模、三条核心能力，
最下面各放一个「选择这个」按钮。

这是 render_ui 的典型场景——布局 + 数据 + 动作，不需要自定义画面。

地理数据

用这份省份销售数据画一张中国地图分级填色图，
颜色按销售额分五档，鼠标悬停显示省份名和金额。

会加载 geospatial-visualization 技能。

边界与失败态

症状	原因	处理
可视化区域一片空白	iframe 里脚本报错，或 CDN 被拦	让模型截图自检；确认用的是放行的三个 CDN 域名
3D 场景全黑	WebGL 上下文失败或相机方向错	让模型跑 `inspect_3d` 区分这两种情况
`Three.js scene not found`	页面没暴露 `window.__THREE_SCENE__`	让模型加一行全局赋值后重新检查
`Invalid component structure`	`render_ui` 的组件缺 `type`	错误详情里有精确路径，让模型按路径修
图表卡顿、浏览器发烫	DOM 元素超过 1000，用 div 画了大数据	明确要求「用 canvas 渲染」
可视化里的数据是编的	你没提供数据，模型只能造示例	把真实数据贴进对话，或让它先从文件读
插件面板里勾了但没生效	`sandbox_mode` 为 `none`	这个插件需要沙箱，检查对话是否在无沙箱模式

可视化不能实时连你的数据源。 iframe 无网络（CDN 除外），所以图里的数据是生成那一刻内联进去的快照。要”活”的看板需要走 Sites 发布一个真站点，而不是内联可视化。

验证

确认插件已激活

问「你现在能在对话里直接画图吗？」。激活时专家会区分 visualize 与 render_ui 两种产出；未激活时它会说”我可以给你代码”。

最小图表

「用 [1,3,2,5,4] 画一个柱状图」。应该直接看到可交互图表，不是代码块。

验证自检生效

提一个稍复杂的 3D 需求，观察模型是否在给你结果前调用了截图与 inspect_3d。跳过自检直接交付的，多半是浏览器工具没绑上。

渲染表面

对话里各类渲染表面的总览与区别

A2UI

声明式界面协议的组件与模式

3D 开发

Blender / Godot 桥接与 3D 资产管线

画布

自由创作画布（与内联可视化正交）

核对日期 2026-08-11。来源：services/agent-runtime/src/plugins/builtin/visualize/plugin.json、tools/{visualize,render_ui,inspect_3d,_inspect_runner}.py、prompts/VISUALIZE.md、services/agent-runtime/src/skills/registry.py。

开始使用

核心概念

使用指南

平台与账户

深入了解

可视化

可视化（profy-visualize）

一句话定义

激活条件

三个渲染工具怎么选

visualize：内联 HTML 可视化

参数

沙箱与网络

设计规范（提示词层强制）

视觉自检循环（这个插件最有价值的部分）

render_ui：声明式原生界面（A2UI）

参数

组件类型

校验会先于渲染

inspect_3d：Three.js 场景诊断

参数

前提：场景必须被暴露出来

它会告诉你什么

双模式支持

技能层

可执行示例

边界与失败态

验证

相关页面

渲染表面

A2UI

3D 开发

画布

​可视化（profy-visualize）

​一句话定义

​激活条件

​三个渲染工具怎么选

​visualize：内联 HTML 可视化

​参数

​沙箱与网络

​设计规范（提示词层强制）

​视觉自检循环（这个插件最有价值的部分）

​render_ui：声明式原生界面（A2UI）

​参数

​组件类型

​校验会先于渲染

​inspect_3d：Three.js 场景诊断

​参数

​前提：场景必须被暴露出来

​它会告诉你什么

​双模式支持

​技能层

​可执行示例

​边界与失败态

​验证

​相关页面

渲染表面

A2UI

3D 开发

画布

可视化（profy-visualize）

一句话定义

激活条件

三个渲染工具怎么选

visualize：内联 HTML 可视化

参数

沙箱与网络

设计规范（提示词层强制）

视觉自检循环（这个插件最有价值的部分）

render_ui：声明式原生界面（A2UI）

参数

组件类型

校验会先于渲染

inspect_3d：Three.js 场景诊断

参数

前提：场景必须被暴露出来

它会告诉你什么

双模式支持

技能层

可执行示例

边界与失败态

验证

相关页面