| name | visual-ralph |
| description | Visual Ralph 编排：用 $ralph 加上内置的 visual verdict 与像素 diff 证据，从生成参考、静态参考或在线 URL 目标出发实现前端 UI，直到实现匹配，并沉淀出可复用的设计系统。 |
Visual Ralph Skill
当用户希望 Codex 通过 Visual Ralph 循环来构建或重做前端 UI 时使用本 skill：已批准的生成参考、静态参考，或来自在线 URL 的基线作为目标，Ralph 负责实现，Visual Verdict 用可测量的判定驱动迭代，而不是仅靠主观描述。
目的
从生成参考、静态参考或在线 URL 出发，构建可测量的前端交付循环：
用户描述 / 在线 URL -> 已批准的视觉参考 -> $ralph 实现 -> Visual Ralph verdict + 像素 diff -> 可复用的设计系统。
对于在线 URL 克隆请求，Visual Ralph 接管已迁移的 $web-clone 用例。不要把新的 URL 驱动的网站克隆工作路由到 $web-clone；把 URL、视口、保真度要求与交互说明都保留在 Visual Ralph 循环里。
这是一个编排 skill。它组合已有的 skills，自身不应当引入运行时命令、依赖或应用级假设。
何时使用
- 用户描述了想要的 web/app UI，要的是实现，不只是设计建议。
- 用户提供了在线 URL，希望通过可测量的 Visual Verdict 迭代得到视觉实现或克隆。
- 生成一张栅格化的 mockup / 参考图能让目标更清楚。
- 任务需要带 pass/fail 阈值的像素级视觉迭代。
- 最终结果应当留下可复用的设计 token / 组件，而不仅仅是一次性的截图匹配。
何时不要用
- 用户只想要设计批评或一般前端建议；用
$frontend-ui-ux 或 designer 通道。
- 任务是没有 UI 参考目标的纯后端 / API 实现。
- 用户已经给了最终静态参考图，只需要对比/修复；直接交给
$ralph 并附 Visual Ralph verdict 指引。
- 请求的产物是确定性的 SVG / 矢量 / 代码原生资源，而不是栅格参考。
工作流
1. 落地目标仓库
在做任何技术栈相关选择之前，先检查本地证据：
- 包管理器与脚本，
- 前端框架与路由结构，
- 样式系统与设计 token 约定，
- 截图 / 测试工具链，
- 应当复用的已有组件。
不要在没有仓库证据支持的情况下硬编码 React、Vue、Tailwind、Playwright 或任何其他技术栈。
2. 建立视觉参考
对于在线 URL 请求，在 Visual Ralph 工件里捕获或记录 URL 派生的参考，并把视口、内容状态、交互约束保留下来。不要调用 $web-clone；该独立 skill 已硬弃用。
在线 URL 参考工件必须包含：
- 来源 URL 与权限/范围说明，
- 视口、路由/状态、任何种子/登录假设，
- 捕获的基线截图路径，或记录在案的截取命令/工具，
- 可见控件的交互对齐说明，
- 已知的排除项，例如后端 / API / 鉴权、个性化数据、多页爬取、第三方组件对齐。
对于生成式的 UI 概念，用 $imagegen 从用户的 UI 描述产出参考。
Prompt 要求：
- 分类为
ui-mockup，除非另一种 imagegen 分类明显更合适，
- 包含视口 / 长宽比与目标承载面，
- 指定布局、层次、排版方向、配色情绪与任何精确文本，
- 禁止 logo / 水印 / 未请求的品牌标记，
- 要求 imagegen 避免不可能存在的 UI 细节或不可读的文本。
在 oh-my-kimi CLI / runtime 下运行、且生成参考是某个活跃的 Ralph 风格循环的一部分时，在调用内置图像工具之前先排入一个 continuation checkpoint：
kimi-omk imagegen continuation <session-id> --artifact <slug-or-filename> --generated-dir "$CODEX_HOME/generated_images/<session>" --work-dir ".omk/artifacts/visual-ralph/<slug>"
这个 helper 会记录 .omk/state/sessions/<session>/imagegen-pending.json，并复用已有的 Stop-hook 后续队列。它的存在是因为内置图像生成可能必须立刻结束 assistant 的本轮回合；下一次 Stop checkpoint 应当恢复工件回收，把生成的图像拷贝进工作区，并跑必要的视觉 QA / verdict 门，而不是依赖手动 $ralph 再次提示。
对于绑定到项目的实现，把已批准的参考拷贝到工作区，例如 .omk/artifacts/visual-ralph/<slug>/reference.png。永远不要让实现参考只留在 $CODEX_HOME/generated_images/... 里。
3. 要求显式的用户批准
在参考生成或 URL 派生参考捕获完成后停下，并请用户批准一张参考图 / 状态，或请求定向的重新生成 / 捕获调整。
批准之前：
- 不要开始前端实现，
- 不要调用
$ralph，
- 不要把一张草稿图当作最终。
批准之后，被确认的图像或 URL 派生基线成为视觉真理来源。任何重大设计转向、替换参考或改变设计方向都需要用户显式请求。
4. 移交给 $ralph 实现
调用 $ralph 时附上：
- 已批准的参考图路径或 URL 派生的基线工件，
- 在线 URL 任务的源 URL、视口、内容状态与交互对齐说明，
- 用户描述，
- 检测到的仓库 / 前端上下文，
- 截图命令 / 视口的精确要求，
- 下面的完成清单。
批准后 Ralph 可以自主迭代。它应当编辑代码、跑应用、截图，并持续改进直到匹配已批准的参考，或出现真正的阻塞。
5. 每次下一笔编辑之前都用 Visual Ralph verdict
每一次视觉迭代：
- 按记录的视口 / 状态截取当前生成的截图。
- 跑 Visual Ralph verdict 步骤，对已批准的参考与生成截图做对比。需要时用
vision agent 做图像理解。
- 把 JSON 判定作为权威。
- 如果
score < 90，把 differences[] 与 suggestions[] 转成下一次编辑计划。
- 下一笔编辑前再跑一次。
必需的 verdict 形状：score、verdict、category_match、differences[]、suggestions[]、reasoning。
6. 像素 diff 仅作为次级调试证据
当不匹配的诊断很难时，生成像素 diff 或 pixelmatch overlay 来定位热点。像素 diff 不替代 Visual Ralph verdict；它只帮你把视觉热点翻译成具体编辑。
把最终 diff 证据与参考 / 截图工件一并记录，让结果可被审计。
7. 沉淀出可复用的设计系统
如果视觉匹配没有被编码成仓库原生的可复用工件，实现就不算完成。视项目情况，这可能意味着 CSS 变量、theme token、Tailwind 配置、组件 variant、Storybook story、设计文档，或已有的等价物。
至少捕获相关的：
- 配色，
- 间距系统，
- 排版尺度 / 字重，
- 圆角，
- 阴影 / elevation，
- 重要的组件 variant 与状态。
优先复用已有的 token / 组件模式。如果仓库已经有可扩展的设计系统层，不要再引入一个新的。
完成清单
下面全部为真之前不要宣告完成：
- 已批准的参考图或 URL 派生的参考工件保存在工作区。
- 截图复现命令、视口、路由、种子 / 状态与输出路径都已记录。
- Visual Ralph verdict 对已批准参考的最终分数
>= 90。
- 像素 diff 或 overlay 证据作为次级调试证据已记录。
- 设计系统 token / 组件是仓库原生、可复用的。
- 构建 / lint / 测试或仓库的等价验证通过。
- 参考批准后没有未经授权的重大设计转向。
- 残留的视觉差异（若有）显式记录，并附理由。
移交模板
$ralph "Implement the approved frontend reference.
Reference: <workspace-reference-image-or-url-derived-artifact>
Source URL (if URL-derived): <url and permission/scope note>
Viewport/content state: <viewport, route/state, seed/login assumptions>
Interaction parity notes: <visible controls and known exclusions>
Route/surface: <route or component>
Screenshot command: <command and viewport>
Use the Visual Ralph verdict step before every next edit; pass threshold score >= 90.
Use pixel diff only as secondary debug evidence.
Extract reusable design tokens/components for colors, spacing, typography, radii, shadows, and key variants.
Run build/lint/test before completion.
Do not make major design pivots unless explicitly requested."
Task: {{ARGUMENTS}}
