workbuddy_skills/oil-ui-pro/references/style-explorer.md

风格对比页

把几个候选放在同一页里并排比较，由用户挑选。用户可以并排或单张查看、切换桌面和手机、按实际尺寸看、筛选、选定并写备注。对比页的外壳只负责比较和挑选，不带风格倾向，也不作为候选的参考。

先保持核心内容、主要动作和目标用户一致，再改变构图、信息组织、字体气质、色彩关系、密度与图像语言。数量按请求和有效差异决定，不复制整个产品来凑方案，也不把内置外壳的风格套给候选。

对比页是视觉探索工具。HTML 小样默认不执行脚本和提交，标记为可操作的小样和本机地址候选除外（见“准备输入”）；需要真实数据、登录或后端的交互验收，仍在项目里进行。

准备输入

一轮只生成一个对比页，候选能跑就用真实页面：单独写的 HTML 小样直接嵌入，项目里的方案用本地地址。只有拿不到可运行的页面时才用截图。每个方案一个画面：存量项目选入口或差别最大的那一步，整站方案只放代表页，其他页面写进说明。手机版只在手机是主要设备时另出，不手写汇总页。

在任务目录放置 manifest.json 和候选文件。HTML 候选为带 head 的文档，CSS 写在页面里。图片、字体和视频用相对路径引用任务目录里的文件，例如 img/hero.jpg，生成器会把它们内嵌进对比页；不要自己把图片转成 base64 写进候选，文件会变得很大、难以修改。不引用网络资源和任务目录以外的文件，链接只使用本页锚点。可以保留代码供独立打开，但比较页不执行其脚本。

候选必须在不运行脚本时也能显示设计内容。依赖脚本生成界面的页面，先取得静态 HTML 或实际截图；不能把只有空挂载节点的应用入口交给对比页。

候选内部不使用 iframe、object 或 embed 等嵌套文档；先将需要的内容转为静态页面或截图。另存的现有页面常带 srcset 或 <picture><source> 响应式图片，生成器会拒绝：改成一张用相对路径引用的 <img>，或直接用截图作为图片候选。

图片候选支持 PNG、JPEG、WebP。实际查看图片并记录它代表的页面与状态，避免拿不同任务或不同状态的图比较风格。源文件必须位于 manifest 同目录或子目录。

manifest 使用固定字段，结构如下。尖括号内是占位说明，全部换成本轮方向卡里的实际内容；不要沿用占位文字作为风格：

{
  "schemaVersion": 1,
  "project": "<项目名称>",
  "brief": "<所有候选共同表达的内容与主要任务>",
  "round": "<轮次，例如 01>",
  "candidates": [
    {
      "id": "<小写唯一标识>",
      "name": "<方向名称>",
      "concept": "<北极星：一句能指导取舍的体验意图>",
      "typography": "<实际使用的字族、字重与尺度关系>",
      "palette": ["<十六进制色值>", "<十六进制色值>", "<十六进制色值>"],
      "traits": ["<可观察特征>", "<可观察特征>"],
      "kind": "html",
      "source": "<候选文件的相对路径>"
    }
  ]
}

自己写的可运行小样（单个 HTML、脚本内联），在 manifest 里给候选加 "interactive": true。单张查看时就能直接操作，对比页仍是可离线移动的单个文件，不需要服务器；卡片左下角标注“可操作”。这类候选只能运行内联脚本，不能联网或加载外部文件；浏览器存储换成页面关闭即清空的内存版本；alert、confirm 这类系统弹窗不会出现，需要确认时用页面内的对话框。

已有仓库里要运行起来的应用（例如 React、Vue 项目），把 kind 设为 url，用 url 字段代替 source，指向本机开发服务器上的页面，例如 http://localhost:5173/orders?variant=b。这类候选在对比页里实时运行，脚本和表单照常工作，切换手机视口时应用会真实重排；卡片左下角标注“本地运行”。地址只能是 localhost、127.0.0.1 或 ::1；页面空白时，确认开发服务器已启动，且没有用响应头禁止被嵌入。这类候选要靠开发服务器才能看，所以：

• 在 manifest 顶层写下启动方式，就是你刚才自己用过的那条命令："serve": {"command": "pnpm dev", "cwd": "<项目的绝对路径>", "url": "http://localhost:3456"}。
• 交付时让开发服务器开着，用户打开对比页看到的就是真实页面。
• 服务没在运行时，对比页会提示用户在对话里说“打开对比页”，并附上这条命令。

不默认另存截图版。用户要长期留档或发给别人时，再用 工具 里的截图工具另截一份。

给当前版本加 "baseline": true，它会排在第一位，编号显示为“现状”，其余方向从 01 开始编号。每轮最多一个基线。改动存量页面时，都把现状放进来，让每个方向都和它对照。

id 使用唯一的小写字母、数字、连字符或下划线。typography 描述实际使用的文字关系，palette 使用十六进制颜色，traits 简述可观察差异。图片候选将 kind 改为 image、source 指向对应图像。

生成和打开

确认 Python 不低于 3.10，将脚本与输入输出参数解析为绝对路径后运行 生成器：

<python> <skill>/scripts/build_explorer.py <任务目录>/manifest.json --output <任务目录>/style-explorer.html

macOS/Linux 通常使用 python3，Windows 通常使用 py -3；执行前确认实际解释器。没有生成器运行能力时保留输入与候选供直接查看，说明尚未组装对比页，不临时重写另一套工具。

默认拒绝覆盖。确实要更新已有本轮对比页时显式加 --force，或使用新的输出文件名。输入错误时保留旧产物；生成器不覆盖源候选，也不允许把运行产物写入 Skill 目录。

用浏览器打开返回的本地 HTML。HTML 小样和截图已经内嵌，单个文件移到哪里都能看；本地地址候选要开发服务器开着。模板原文件只有空状态，不是用户最终对比页。

用户之后说“打开对比页”时：读对比页旁边的 manifest 里的 serve，在 cwd 里后台运行 command，等 url 能访问了，再用浏览器打开对比页。端口被占用时先确认占着它的是不是同一个项目。

查看与记录选择

默认使用相同逻辑视口展示 HTML 候选：桌面 1280×900，手机 390×844。卡片等比缩放以便同屏比较；判断文字大小与细节时进入单张查看，使用“实际尺寸 100%”检查真实排版；适应窗口仍可能缩小，不能据此宣称可读性通过。切换手机视口后确认真实重排，而非仅看缩小后的桌面。

点“选择”时会复制一句简短的文字，例如“<轮次>：选 03 <方向名>”，有备注时再附一行。用户粘贴复制的结果或直接说出选择后，Agent 按轮次和编号对照当前 manifest，确认对应本轮，再把选择与备注更新到项目设计说明，继续实现。浏览器本地保存不代表已经写回项目文件，也不会自动向 Agent 发送消息。

检查实际结果

核对候选：每张画面和 manifest 里写的页面、状态、视口一致，中文字体真实渲染出来了。对比页本身的并排、单张、筛选、复制和离线打开由 Skill 自带的回归测试保证，任务里不验证、不读模板源码，也不在用户自己的浏览器里清除任何存储。