visualize

name	visualize
description	将前端方案讨论中的 UI、布局和信息层级问题渲染为本地浏览器中的 HTML 页面，辅助用户直观看方案差异。仅在以下场景使用：(1) 用户手动触发 visualize skill，(2) 正在讨论前端界面方案时，先提示用户可使用该 skill 查看示意图，且用户明确同意，(3) 需要并排展示 2-4 个前端视觉方案或带标注的 mockup 以便在终端继续讨论。该 skill 只负责展示；用户始终在终端反馈和做选择。

Visualize

将前端方案讨论中的视觉内容快速整理为本地 HTML 页面并在浏览器打开，帮助用户“先看见，再在终端讨论”。

核心边界

• 只负责浏览器中的视觉呈现，不依赖 event、selection log 或浏览器回传结果。
• 正式反馈渠道始终是终端；用户看完页面后，回到终端给出选择、修改意见或追加约束。
• 不要因为话题与前端相关就自动触发。只有用户手动触发，或在前端方案讨论中先提示、得到用户同意后才使用。

适用场景

• 页面布局、组件结构、信息层级、视觉风格方向对比
• 带标注的页面/组件草图
• 同一问题的 2-4 个可视化方案并排比较

不适用：

• 需求澄清、scope 划分、API 设计、数据建模、tradeoff 讨论
• 流程图、架构图、关系图等非前端视觉方案
• 需要浏览器表单输入、控件调参、状态持久化的 interactive playground
• 需要把浏览器点击作为正式输入的流程

参数

使用本 skill 时，先在内部明确以下参数；若用户未完整给出，根据上下文推断最小必要集：

• topic：当前要可视化的前端问题，例如首页布局、卡片样式、导航结构
• goal：这次展示要帮助用户判断什么，例如选方向、看层级、看流程
• template：使用哪种展示模板，ui-compare 或 annotated-mockup
• variants：需要展示几个方案，通常为 1-4 个
• fidelity：低保真 wireframe 或中保真 mockup
• output_path：HTML 文件保存位置；若用户未指定，默认使用当前项目（cwd）下的 ./.ai_docs/visualize/

执行流程

Step 1: 确定模板与输出目录

根据目标选择最接近的模板：

• ui-compare：并排展示 2-4 个 UI / layout / style 方向
• annotated-mockup：展示单个页面或组件，并用标注解释设计意图

确定输出目录：

• 用户明确指定路径时，使用用户指定路径
• 否则默认写入当前项目（cwd）下的 ./.ai_docs/visualize/
• 如目录不存在，先创建目录再写入 HTML 文件

ui-compare 适用：

• 比较 2-4 个页面布局
• 比较组件风格方向
• 比较信息层级和导航结构

建议结构：

+--------------------------------------------------+
| 标题：这次在比较什么 / 该看什么                  |
+-------------------+------------------------------+
| 方案 A            | 方案 B                       |
| mockup            | mockup                       |
| 1-2 行说明        | 1-2 行说明                   |
+-------------------+------------------------------+
| 方案 C（可选）    | 方案 D（可选）               |
+--------------------------------------------------+
| 回到终端反馈：选 A/B/C，或说明想混合哪些部分     |
+--------------------------------------------------+

annotated-mockup 适用：

• 展示单个页面或组件
• 解释视觉层级、操作区域、信息分组
• 给用户一个“长什么样”的例子

建议结构：

+--------------------------------------------------+
| 标题 + 目标                                      |
+--------------------------------------------------+
| 主 mockup                                        |
|  [1] 顶部导航                                    |
|  [2] 主要操作区                                  |
|  [3] 次级信息区                                  |
+--------------------------------------------------+
| 标注说明列表                                     |
| 1. 为什么这样放                                  |
| 2. 用户先看到什么                                |
| 3. 哪些部分后续可再细化                          |
+--------------------------------------------------+
| 回到终端反馈：指出你想调整的区域或优先级         |
+--------------------------------------------------+

Step 2: 生成 HTML

产出一个单文件 HTML，遵循以下要求：

• 内联 CSS 和必要的 JS；不要依赖外部 CDN
• 内容聚焦当前问题，不做与决策无关的装饰
• 页面顶部明确写出“正在比较什么”
• 方案卡片或图示必须带清晰标签，例如 A / B / C
• 页面底部明确提示：请回到终端反馈，不要把浏览器点击当作正式输入

优先使用低成本、易读的结构：

• wireframe 用简单块状布局即可
• 对比页面控制在 2-4 个方案，避免信息过载

Step 3: 打开浏览器

写入 HTML 后，使用 open <html-file> 在本地浏览器打开该文件或对应本地 URL。

对用户的终端说明应包含三点：

• 浏览器里正在展示什么
• 应该重点比较什么
• 看完后如何在终端反馈

示例：

我已经打开一个本地页面，里面是 3 个 dashboard 布局方向，重点看信息层级和导航密度。看完后直接在终端告诉我你偏向 A/B/C，或者说出你想混合哪些部分。

Step 4: 回到终端继续收敛

浏览器展示完成后，后续决策和修改都在终端完成：

• 记录用户在终端给出的选择和理由
• 如需迭代，生成新的 HTML 版本继续展示
• 如下一步已不需要视觉化，直接回到纯终端讨论

不要读取或依赖浏览器交互日志，不要要求用户必须在浏览器中点击。

产出规范

每次使用本 skill，最终至少应产出以下之一：

• 一个用于比较方案的本地 HTML 页面
• 一个用于解释页面结构或信息层级的本地 HTML 页面
• 一个用于说明视觉层级的带标注 mockup 页面

页面本身不是最终决策记录。最终结论应以终端对话为准。

设计约束

• 优先低保真，除非用户明确要求更高保真
• 优先表达结构、层级和差异，不追求像真实产品截图
• 不把页面做成复杂配置器；这不是 playground builder
• 不引入 selection persistence、copy prompt、preset 控件、状态管理面板
• 只聚焦前端界面方案，不扩展到通用 diagram 或系统结构图
• 如浏览器无法打开，直接在终端输出 HTML 文件地址或本地 URL，并明确告知用户可手动打开

Fidelity 建议

• low：块状 wireframe、占位文本。默认使用。
• medium：更接近真实界面，但仍以结构表达为主。
• high：只有在用户明确要求时才使用；避免为了“好看”牺牲收敛速度。