OmX Visual Ralph：基于参考图与实时 URL 的视觉实现闭环技能解析

2026-09-09 22:13:32作者：姚月梅Lane

$visual-ralph 是 OmX（Oh My codeX）中负责“以视觉目标为基准的前端实现”的核心技能：它把一段用户描述、一张已批准的设计参考图或一个实时 URL 基线，转化为可度量的实现循环——描述 / URL → 已批准参考 → $ralph 实现 → Visual Ralph 判定 + 像素对比 → 可复用设计系统。本文基于 visual-ralph/SKILL.md 展开，结合仓库内源码、测试与迁移记录，说明该技能的使用边界、七步工作流、判定阈值、证据要求与交接模板，帮助你把它直接用于“照着图实现前端”或“按线上站点克隆界面”的实战场景。

技能定位：视觉实现循环，而非设计治理

先厘清 OmX 技能家族的分工，避免误用：

$visual-ralph 负责实现匹配：以已批准的视觉参考（生成图、静态图或实时 URL 基线）为准，通过内置 Visual Ralph 判定与像素差异证据，迭代到实现与参考一致，并沉淀可复用的 repo 原生令牌/组件。
$design 负责设计治理：产出并维护仓库根目录的 DESIGN.md 契约（品牌、产品目标、信息架构、视觉语言、组件、可访问性等）。当两者都需要时先运行 $design，DESIGN.md 为视觉判定目标提供支撑，但不替代视觉判定（见 skills/design/SKILL.md）。

因此，下列场景适用 $visual-ralph：

用户希望针对一个视觉目标构建或重构 Web/App UI；
一个实时 URL 或生成的栅格草图（raster mockup）需要可度量的实现与像素级迭代；
结果必须沉淀出可复用的 repo 原生令牌/组件，而不只是一张匹配的截图。

而不应使用它的场景包括：编写持久化的 DESIGN.md 简报（交给 $design）、非视觉的后端工作、可以直接交给 $ralph 的纯对比修复，以及确定性的 SVG/代码原生资产。

历史迁移：它接管了 `$web-clone` 与 `$visual-verdict`

SKILL.md 明确声明：对于 URL 克隆场景，本技能持有迁移自 $web-clone 的用例，须在技能内保留 URL、viewport、保真度与交互记录，不得单独调用 $web-clone。这一点在源码中有硬性佐证：src/hooks/sunset-stub.ts 将 visual-verdict 与 web-clone 统一登记为已移除技能，替换目标均为 $visual-ralph：

"visual-verdict": {
  replacement: "$visual-ralph",
  message: 'Skill "$visual-verdict" has been removed. Use "$visual-ralph" instead.',
},
"web-clone": {
  replacement: "$visual-ralph",
  message: 'Skill "$web-clone" has been removed. Use "$visual-ralph" instead.',
},

对应的测试 src/hooks/tests/visual-verdict-loop.test.ts 验证了移除提示（use.*\$visual-ralph）。同时需要注意：$ralph 技能本身在 OMX 0.21 起已成为 sunset stub（见 skills/ralph/SKILL.md，替换为 $ultragoal），但测试与技能文档共同确认——Visual Ralph 作为视觉 QA 循环独立于 ralph 技能的下线而存在，交接目标是 $ralph 代表的那套“循环直到达标”的执行语义，实际承载者为 $ultragoal。

七步工作流详解

1. 锚定仓库现状（Ground the repository）

开始前先摸底当前项目：包管理器与脚本、前端框架与路由、样式/令牌约定、截图工具链、可复用组件。SKILL.md 特别强调：仅当仓库证据支持时才选择特定技术栈的命令，禁止凭空假设（测试 visual-ralph-skill.test.ts 亦断言了这一约束）。

2. 建立参考（Establish a reference）

参考来源分两类：

实时 URL：捕获或记录一个工件，必须包含以下信息——

源 URL 与权限/范围；
viewport 集合；
路由/状态（route/state）；
种子数据/登录假设（seed/login assumptions）；
基线截图路径或捕获命令；
可见控件对等性记录（visible-control parity notes）；
排除项（后端/API/认证、个性化数据、爬取、第三方组件）。

生成概念图：使用 $imagegen，并附带分类 ui-mockup、viewport/宽高比、表面（surface）、布局层级、排版、色彩基调、精确文案，且要求无 logo/水印/未要求标记、UI 细节可读可行。在 OMX 运行时中，需在内置图片工具之前排队续跑检查点：

omx imagegen continuation <session-id> --artifact <slug-or-filename> --generated-dir "$CODEX_HOME/generated_images/<session>" --work-dir ".omx/artifacts/visual-ralph/<slug>"

这条命令的实现位于 src/imagegen/continuation.ts，其行为可进一步拆解：

参数校验：session id 必须匹配 ^[A-Za-z0-9_-]{1,128}$（L51、L63-L68），--artifact 为必填；--after 接受 ISO 时间戳或 now。
状态落盘：命令在 .omx/state/sessions/<session>/imagegen-pending.json 写入 pending 记录（含 artifact_name、after、generated_images_dir、work_dir 等），并通过 injectExecFollowup 排队受审计的 exec 后续任务，使必须立即结束的内置 image_gen 轮次能在下一个 Stop 检查点恢复 Ralph 视觉 QA/恢复流程（docs/codex-native-hooks.md 的 hooks 表中亦有记载）。
默认恢复指令：生成的 resume_instruction 要求从 generated_dir 中找到 after 时间戳之后最新的生成图、复制到 work_dir 保留原始工件、执行裁剪/后处理，并在任何下一次编辑前通过视觉 QA/visual-verdict 门禁。

将批准的参考复制到 .omx/artifacts/visual-ralph/<slug>/reference.png，不要只留在 $CODEX_HOME/generated_images 下。

3. 批准门禁（Approval gate）

生成或 URL 捕获完成后必须停下来，获得一张参考图/状态（或一次定向的重新生成/捕获调整）的用户批准。批准之前：不得开始实现，不得调用 $ralph。批准之后，该图/基线即为视觉事实源（visual source of truth）；任何重大转向（major pivot）都需要用户显式请求。测试断言了 Before approval, do not implement or invoke '$ralph' 与 Major design pivots...explicit user request 两条契约（visual-ralph-skill.test.ts）。

4. 交接给 `$ralph`（Hand off to `$ralph`）

向 $ralph 传递：已批准参考/基线、URL 与权限说明（如适用）、viewport/内容状态、交互对等与排除项、用户描述、检测到的前端上下文、截图命令/viewport、完成检查清单。Ralph 在批准之后编辑、运行、截图并迭代，直到匹配或被阻塞。技能还提供了一份可直接复制的交接模板（见下文），保证每次交接字段完整。

5. 每次编辑前先判定（Verdict before every edit）

每个迭代周期：以当前 viewport/状态截图 → 运行 Visual Ralph 判定（必要时借助 vision）→ 将返回的 JSON 视为权威依据：

若 score < 90，把 differences[] 与 suggestions[] 转化为下一轮编辑计划，先重跑判定再编辑；
判定的必含键：score、verdict、category_match、differences[]、suggestions[]、reasoning。

测试 visual-ralph-skill.test.ts 显式断言了 score < 90 阈值与这组必含键，说明它们是可机器校验的技能契约，而非建议性措辞。

6. 次级差异证据（Secondary diff evidence）

像素对比（pixel diff / pixelmatch 叠加图）只用于定位热点并转化为编辑动作，永远不替代判定。最终需记录参考图、截图与 diff 工件以便审计。也就是说，判定负责“是否达标”，diff 负责“改哪里”。

7. 沉淀可复用设计系统（Reusable design system）

把匹配结果编码进仓库原生资产：CSS 变量、主题令牌（theme tokens）、配置、组件变体、story 或 DESIGN.md 更新。需要捕获：适用颜色、间距、排版/字重、圆角、阴影/层级，以及重要变体/状态。优先扩展现有模式，而不是新增一套平行体系（测试要求令牌维度至少覆盖 colors、spacing、typography、radii、shadows）。

完成证据与停止条件

SKILL.md 给出的“完成”定义是一组可验证证据的合取，缺一不可：

已保存批准的参考/基线，以及可复现命令（viewport、路由、状态、输出路径）；
最终判定 >= 90；
已记录次级 diff 证据；
已存在可复用令牌/组件；
等价的 build/lint/test 验证通过；
无未批准的转向（unapproved pivot）；
剩余差异已文档化。

当证据无法满足这些条件时，在批准门禁处停止，或报告具体的阻塞点（concrete blocker）。这与 skills/ultragoal/SKILL.md 的“不得仅凭 OMX 状态声称完成”精神一致：判定与证据优先于状态字段。

标准交接模板（可直接使用）

技能内嵌的 $ralph 交接模板如下，每次视觉实现任务都应以它为骨架填充：

$ralph "Implement the approved frontend reference.
Reference: <workspace reference or URL-derived artifact>
Source URL and permission/scope: <when applicable>
Viewport/content state: <viewport, route/state, seed/login assumptions>
Interaction parity and exclusions: <visible controls and known limits>
Route/surface: <route or component>
Screenshot command: <command and viewport>
Run Visual Ralph verdict before every next edit; pass threshold >= 90.
Use pixel diff only as secondary evidence.
Extract reusable tokens/components for colors, spacing, typography, radii, shadows, and variants.
Run the repository's equivalent verification before completion.
Do not make major design pivots unless explicitly requested."
Task: {{ARGUMENTS}}

契约如何被测试守护

技能不是一份“仅供参考”的文档——src/hooks/tests/visual-ralph-skill.test.ts 逐条校验了它（读取的即仓库根目录镜像 skills/visual-ralph/SKILL.md）：

定义“已批准参考交接给 Ralph”的描述与 $imagegen 引用；
持有迁移自 $web-clone 的 URL 克隆用例（URL、viewport、保真度、交互记录）；
内置视觉判定权威、像素 diff 次级；
要求可复现性与 repo 原生设计系统工件；
禁止未批准转向、要求仓库证据支撑技术栈选择。

重要运行前提

本文所述 $visual-ralph 的技能定义以仓库内两份互为镜像的文档为准：plugins/oh-my-codex/skills/visual-ralph/SKILL.md（插件分发副本）与 skills/visual-ralph/SKILL.md（源码副本，测试直接读取）；技能目录清单见 src/catalog/manifest.json。
共享的操作、委派、状态、hook、团队、取消与验证不变量统一收敛在 templates/AGENTS.md，技能不再重复这些规则——接入完整运行时前应遵循该 SSOT。
omx imagegen continuation 依赖 OMX 运行时与 CODEX_HOME 环境（默认生成目录位于 $CODEX_HOME/generated_images/<session>），请在确认环境变量与运行时版本后使用。
$ralph 技能在 OMX 0.21 已下线并由 $ultragoal 承接其“循环至达标”的语义；$visual-ralph 作为视觉 QA 技能不受此影响，但交接目标应理解为 $ultragoal 承载的已验证完成循环。