ss-verify

在此工作流开始前，请先执行每个会话一次的 更新预检。

验证（查看实际效果，不要只读代码）

优先使用注册表的产物边界

当 .styleseed/project.json 和 .styleseed/artifacts/index.json 存在时，先解析请求的产物 ID，然后只读取 .styleseed/bundles/<artifact-id>.md 和 .styleseed/manifests/<artifact-id>.json。对于使用注册表的项目，绝不能回退到全局旧版规则包。只有在不存在注册表时，旧版项目才可以使用 .styleseed/effective-rules.md。

如果任一注册表文件存在，就必须要求注册表完整且有效。读取上述选定产物的规则包和清单，并使用 ss-resolve --artifact <artifact-id> --check 检查。 注册表不完整或无效属于错误，不代表可以读取旧版规则包或重新开始设置。根据每个受影响产物自身所需的渲染结果和验证契约进行验证。

只有在两个注册表文件都不存在时，才使用 .styleseed/effective-rules.md 和 .styleseed/manifest.json，并通过 ss-resolve --from-lock STYLESEED.md --check 检查。 在经过授权的构建或修复过程中，如果所选规则包缺失或已过期，应从对应的项目配置中调用 /ss-resolve 或 $ss-resolve。在仅检查模式下，应报告此情况，不要重写规则包，也不要声称当前符合要求。 如果既没有注册表也没有锁定文件，先明确范围，再作出合规性结论。根据该编译方法评估像素效果。 锁定值不能成为核心缺陷的借口，配方或配置文件也不能取代输出规范。

/ss-score 会读取代码并进行评分。但一些最明显的“AI 制作”痕迹永远不会出现在源代码中——它们只存在于像素里：主视觉实际上并不突出、页面下方三分之一处留白空洞、卡片拥挤、网页字体加载失败却悄然回退到 Times、渲染后两种颜色看起来像是两种强调色、文字在实际背景上难以辨认。人类一眼就能看出这些问题，而只读代码的门禁一个也发现不了。

/ss-verify 可以弥补这一差距：它会渲染 UI、截取屏幕截图，并让你查看图像——然后针对你看到的效果使用同一个 StyleSeed 门禁评分、修复并重新渲染。这个门禁最能预测真实用户是否会觉得“这看起来像经过设计”。

在构建过程中，请在 /ss-score 之后将其作为最后一道门禁运行。直接检查屏幕截图或像素不需要重新进行代码评分；如果无法获得代码证据，应报告为未检查。

检查和修复范围

除非请求同时授权修复，否则检查、验证或报告请求仅限检查。在临时工作区中渲染和截取屏幕截图，不要修改产品源代码、配置或真实用户数据。即使检查未通过，也要报告发现的问题。使用现有测试夹具呈现不同状态；切勿清空线上数据库来生成空状态屏幕截图。

在经过授权的构建或修复过程中，只修复范围内的实现缺陷，并重新渲染。 不要更改已批准的视觉标识，也不要降低核心底线来提高分数。工具缺失或门禁失败时，应如实报告，不要虚构通过结果，也不要进行无关安装。

不适用的情况

• 纯逻辑／配置，没有视觉产物 → 使用相关的功能／配置检查，而不是设计评分。没有宿主的可渲染组件可以使用下方的临时测试框架。
• 完全无法渲染（没有浏览器、没有 Playwright、无头模式受阻）→ 说明这一点，改用 /ss-score，并告知用户跳过了视觉检查。如果没有实际查看截图，绝不要声称已进行视觉验证。
• 快速提交前检查 → 使用 /ss-lint。/ss-verify 更繁重（会启动渲染器）。

对于已编译的空间契约，请遵循 空间角色指南。 对于已配置的空间契约，请运行已安装的 scripts/inspect-spacing.mjs 浏览器函数，并根据指南为每个声明的角色显式绑定。将失败和不支持的测量视为尚未解决，而不是通过了视觉检查；也要检查内容观察结果。在要求的窄／宽视口下，检查实际间距、内边距、令牌解析、分组、重复对齐、溢出，以及加载／错误布局。检查截图和几何尺寸。数值合规无法证明节奏良好或获得用户认可。修复时保留无关的间距。

第 1 步 — 通过当前适配器渲染

对于 social-carousel、slide-deck、document-report 或 single-frame，使用配套渲染器，并以清晰可读的分辨率打开每个必需的导出帧／页面。验证尺寸、裁切／安全区、字体可用性、资源位置和导出清单。不要强行将浏览器工作流用于 PIL、幻灯片、PDF 或图像渲染器。

对于 product-ui，按以下优先顺序获取实际截图：

A. 正在运行的项目（Next / Vite / 等）——常规情况。

1. 在后台启动开发服务器（npm run dev / pnpm dev / 框架命令）；等待就绪提示行并记录端口。
2. 使用 Playwright 通过无头 Chromium 截取该路由的屏幕截图。如果项目的 node_modules 中有 playwright，就使用它；否则使用全局缓存的 Chromium。最简脚本：

   import { chromium } from "playwright";           // or an absolute path into node_modules
   const b = await chromium.launch();
   const c = await b.newContext({ viewport: SURFACE, deviceScaleFactor: 2 });
   const p = await c.newPage();
   await p.goto(URL, { waitUntil: "networkidle" });
   await p.evaluate(() => document.fonts.ready);      // don't shoot before fonts load
   await p.waitForTimeout(400);
   await p.screenshot({ path: OUT, fullPage: true });
   await b.close();
   

   **表面视口：**移动端 {width:390,height:844} · 桌面端 {width:1440,height:900}。从锁定项的 Surface 中选择，或使用 --surface。
3. 如果有可用的浏览器 MCP（claude-in-chrome），则改用它导航并截图。

B. 静态 HTML 文件 → 直接通过 file://… 打开并截图（使用相同脚本）。

C. 独立组件（没有宿主页面）→ 创建一个最简临时页面，引入该组件并传入真实的 props，然后截图。

之后务必读回截图（读取 PNG）。必须亲眼查看。使用 deviceScaleFactor: 2 截图，确保文字足够清晰，以便进行评判。

第 2 步 — 为你看到的内容评分（视觉检查关卡）

查看图像，并通过感知评估运行 StyleSeed 检查关卡。以下检查需要目视，而不能只看源代码：

□ Squint test    — blur your focus / imagine it at 50%. Does it still read "AI-generated"?
                   (bland gradient, pill button + generic sans, icon-chip row, even flat grid) → FAIL
□ Focal          — does ONE element actually dominate at a glance? If your eye lands nowhere,
                   or on an all-even grid, the focal point failed regardless of what code intended
□ Balance        — dead whitespace (a lower third of empty), or cramped/colliding elements?
                   Is the visual weight distributed, or all top-left / all-centered?
□ Fonts loaded   — is the intended typeface actually rendering, or a Times/Arial fallback?
                   (a silent font-load fail is a top "looks cheap" tell — invisible in code)
□ One accent (seen) — count the hues you actually SEE. Two things competing for "the color" = FAIL,
                   even if the code named one token
□ Contrast (seen) — any text you have to strain to read on its real rendered background?
                   Light-grey-on-white labels, low-contrast on a colored/照片 panel
□ Rhythm/optics  — are edges aligned, gaps consistent, cards optically even? Off-by-a-few-px
                   misalignments that read as "sloppy" but pass a code check
□ Type scale fit — on desktop, does the body text look too small for the canvas? does the hero
                   feel undersized? (the surface-scale tell, judged by eye)
□ Grammar fit   — does the screen visually serve the selected grammar's user job, attention
                   model, composition, density, action hierarchy, and characteristic tells?
□ Recipe fit    — do geometry, containment, controls, collections, navigation, density, and
                   motion visibly match the selected recipe rather than the old universal soft-card look?
                   Would the same layout still appear if the product changed? If yes, FAIL
□ Motion (if any) — capture before/after or a mid-transition frame; is it purposeful, or the
                   "cheap fade/bounce on everything" tell? does it block the first read?

第 3 步 — 同时渲染各种状态或序列变体

正常流程的截图会掩盖最常见的真实问题：**没有空状态／加载状态／错误状态。**如果表面包含数据视图，请使用测试数据、现有的预览查询参数，或临时测试框架中的 props 渲染这些变体，并分别截图。“无数据”时一片空白是失败，只有查看空状态才能发现。（不含数据视图的静态营销页面 → 不适用，并注明。）

对于序列型产物，请将封面／首帧、每个内容帧以及结尾／CTA 作为整体进行检查：连贯性、进展、每帧传达一条信息、重复模板造成的疲劳、来源标签、页码，以及安全区是否保持完整。对于文档／演示文稿，请检查每一页／每张幻灯片，以及具有代表性的缩略图或总览视图。

步骤 4 — 修复、重新渲染、重复

在仅检查模式下，返回发现的问题和证据，不做任何修改。在获准修复时， 修复代码，然后重新渲染并再次检查。通过后停止；修复并渲染最多三轮后停止； 遇到权限或工具阻碍时也停止。切换技能不得重置次数限制。 始终报告最新的图像（如有）、生效的规则集、所做的更改、门禁状态以及未解决的问题。 可以展示失败结果供审查，但绝不能将其标记为已接受。

规则

• 必须实际查看渲染后的产物。 未渲染就不能给出视觉判断——改用 /ss-score，并说明跳过了视觉门禁。绝不能捏造“看起来不错”。
• 每次修复后都要重新渲染。 这项技能存在的原因是源码与像素会出现偏差；通过阅读差异来验证视觉修复，有违初衷。
• **按顺序执行构建门禁：**先运行 /ss-score（代码），以低成本发现结构问题；然后运行 /ss-verify（像素），作为最终标准。/ss-build 会在其循环中运行代码门禁；最后使用 /ss-verify 完成可渲染的屏幕。
• **清理：**只停止由你启动的开发服务器；只移除你自己的临时测试文件。
• 以 2× 分辨率截图，并使用锁定界面的视口——用 390px 的截图评判桌面应用（或反过来）会使字号比例和视觉平衡检查失效。