企业官网建设流程全解析

screenshot-to-code 图像资产管线 QA 实践指南：如何验证资产提取、自渲染预览与图像编辑工具链

【免费下载链接】screenshot-to-codeDrop in a screenshot and convert it to clean code (HTML/Tailwind/React/Vue)项目地址: https://gitcode.com/GitHub_Trending/sc/screenshot-to-code

本文基于仓库根目录的 QA.md 展开，系统讲解 screenshot-to-code 在image-tools分支上针对图像资产处理能力（资产提取、上传资产直用、screenshot_preview自渲染检查、edit_image/remove_background工具）的 QA 检查清单，并结合后端源码说明每一项验证结论背后的实现依据，以及一套"以 prompt reports 为核心"的高效 QA 执行方法。读完本文，你可以独立搭建该项目的资产管线回归测试流程，并能在模型输出层面（而非 UI 层面）证明"截图中的 logo 被精确提取并在生成页面中被真正使用"。

1. QA 范围：image-tools分支要验证什么

QA.md 是针对image-tools分支的回归验证清单，核心是新增的资产处理能力（Asset handling），同时要求既有功能不回归、且行为在 Gemini / OpenAI / Claude 三家模型上保持一致。原文档分四块：新增资产处理、既有功能、跨模型一致性、高效执行 QA 的方法。下面逐一展开，并在每块给出仓库源码级的佐证。

2. 新增资产处理能力（Asset handling）的 QA 要点

2.1 提取"对"的资产，而不是"多"的资产

QA 清单第一条要求：从截图中提取正确的资产——logo、hero 图、feature 图标，而不是按钮、文本或整页。这一条隐含了两个维度的验证：

• 选择正确性：模型要挑出语义上"可复用为图片资源"的元素；
• 边界正确性：裁剪框要紧贴目标，不吞掉周边内容。

从源码结构看，资产提取由 backend/asset_extraction.py 实现：它以 schema 约束的AssetDetection模型（request_id+ 1-based 的image_index+ 归一化到 0–1000 的box_2d边框 +label）让视觉模型对每个资产请求给出结构化答案，找不到时显式返回null。这意味着 QA 时"没提取到"和"提取错了"在数据层面是可区分的——配合后文第 5 节的 prompt reports，你可以直接 grep 检测框坐标来判断裁剪是否贴合。对应的实现测试见 backend/tests/test_asset_extraction.py。

2.2 裁剪结果要"像素级精确"并且真的被用进页面

清单第二条："Extracted crops are pixel-accurate and actually used in the generated page"。这条检查点强调的不是"页面里有张图"，而是：

1. 裁剪坐标精确（无偏移、无多余留白）；
2. 生成的 HTML 中引用的确实是该裁剪产物（而不是模型手绘/重新描述出来的相似图）。

验证手段见 5.5 小节的内容寻址（content-addressed）方法：通过文件名哈希即可机械地确认"生成页面引用的就是这个裁剪文件"。

2.3 上传的精确 logo 必须"原文照用"（verbatim）

清单第三条："Uploaded an exact logo → used verbatim in the output, not redrawn"。这是该分支最容易被模型行为破坏的场景：agent 拿到用户上传的 logo 后，正确行为是直接引用该文件 URL，而不是"我画一个类似的 logo"。QA 时若生成页面里的 logo 与原文件有任何差异（重绘、改色、换字体），即判定失败。

2.4screenshot_preview：agent 渲染自己的 HTML 并自查

清单第四条对应screenshot_preview工具。该工具让 agent 把当前生成的 HTML 送进无头浏览器渲染、截图，并把截图作为多模态图片返回给模型"自查"。backend/agent/tools/screenshot_preview.py 中可以看到其实现要点：

• 分别在desktop和mobile两个视口下做full_page截图（PREVIEW_VIEWPORTS = ("desktop", "mobile")）；
• 截图仅用于模型"看"，不作为资产持久化（注释明确：预览是为 seeing 而非 keeping）；
• 前置校验：还没有文件内容时会报错要求先create_file。

QA 验证点：agent 是否调用了该工具、返回的两张视口截图是否作为图像 part 进入了后续模型请求（prompt reports 中可直接看到）。该依赖 Playwright Chromium，README 中说明安装playwright install chromium后自动启用。

2.5edit_image/remove_background接受本地资产 URL

清单第五条要求图像编辑类工具能接收本地资产 URL。这里的实现细节值得展开：后端把资产发布在本机回环地址的/local-assets/路径下，而 Replicate 等云端模型 API无法访问 localhost URL，因此所有传给 Replicate 的图像输入都必须先内联为 base64data:URL。

backend/agent/tools/local_assets.py 完整实现了这一路由逻辑，QA 时可对照验证：

• is_local_host_url：判定 URL 是否指向回环地址（127.0.0.1/localhost/::1），这类 URL 绝不能直接递给云端模型；
• local_asset_url_to_bytes：把http://localhost:PORT/local-assets/xxx读成(bytes, mime_type)，并做了路径穿越防护（解析后的绝对路径必须位于LOCAL_ASSET_DIR之下，否则返回None）；
• local_asset_url_to_data_url：转换为data:image/png;base64,...形式；外部 URL 与已有的 data URL 原样透传。

对应测试在 backend/tests/test_local_assets.py。QA 检查点：agent 把本地资产 URL 传给edit_image/remove_background时工具执行成功（没有把 localhost URL 直接发给云端导致 404），且编辑结果在 prompt reports 中可见。

3. 既有功能回归清单

QA.md 明确列出必须回归的既有能力，QA 时不能因为加了图像工具就只测图像链路：

• Text → code：纯文本描述生成页面；
• Video → code：屏幕录像转功能原型（README 中说明该模式依赖 Gemini）；
• Edit / update an existing generation：对已有生成结果做增量修改；
• Multiple variants generate in parallel：多 variant 并行生成（见 design-docs/variant-system.md）。

4. 跨模型一致性检查

清单"All models"部分要求：

• Tool images reach Gemini, OpenAI, and Claude——工具返回的图片（资产裁剪、预览截图、编辑结果）作为图像 part 送达三家 provider，不能只测单一模型。可从 backend/agent/providers/ 下各 provider 的实现确认图像 part 的编码路径，test_tool_image_outputs相关测试（backend/tests/test_tool_image_outputs.py）覆盖工具图像输出的行为；
• Variant labels (Fast / Max) show correctly——variant 前端的档位标签展示正确，属于 UI 层验证项。

5. 高效执行 QA 的六条实战方法

这是 QA.md 最有操作价值的一节，逐条结合仓库实现说明：

5.1 相信 prompt reports，而不是 UI

原文：PROMPT_REPORTS_ENABLED=1+LOGS_PATH=…下，每一次 LLM 请求都会落盘，包含工具调用、返回结果和最终 HTML——grep 报告远比抓页面文本可靠。在浏览页/evals/prompt-reports查看。

实现佐证：backend/routes/prompt_reports.py 的模块注释说明，报告是 JSON 文件，由fs_logging.prompt_reports（backend/fs_logging/prompt_reports.py）写入{LOGS_PATH}/run_logs/prompt_reports；路由还提供列表（provider、model、session、turn、size、cost_usd）与按天数剪枝的能力。由于报告包含完整的工具调用与最终 HTML，验证"裁剪是否被用进页面""预览截图是否送达模型"这类问题都可以直接 grep 完成，不需要任何 DOM 断言。

5.2 一次只跑一个场景——为了报告归属清晰

并发跑多个场景会把多个 run 的 prompt reports 交织写进同一目录，归因很痛苦；串行跑还有附带好处：避免每个场景 ~4 个 variant 叠加打到 provider（作者注明当时并未实际触发限流，但串行仍是推荐做法）。

5.3 用"聊天输入框回归"判定完成

检测生成完成的信号是页面出现"Tell the AI what to change…"聊天输入框，而不是扫描页面文字——因为该输入框的 placeholder 文案不在innerText里，文本扫描会漏判。这是对 UI 自动化断言的精确提醒：断言应针对"元素存在"而非"文本出现"。

5.4 使用独特且确定性的测试夹具（fixtures）

QA 应使用一眼可辨、结构清晰的截图与 logo 作为 fixture（比如一个轮廓鲜明的 logo + 布局规整的页面截图），这样只需肉眼核对就能判断"是否挑对了资产"。fixture 必须确定性，保证多次运行可对比。仓库前端测试自带这类夹具的思路可参考 frontend/src/tests/fixtures/（含 UI 截图与简单页面 HTML）。

5.5 资产是内容寻址的：用哈希证明"就是这个文件"

原文给出了关键机制：资产文件名形如asset_<sha256[:24]>.png（取文件内容 SHA-256 的前 24 位十六进制）。这带来一个可机械执行的验证流程：

1. 对上传的原始 logo 文件计算 SHA-256，取前 24 位拼出期望文件名；
2. 在服务出来的资产目录（即/local-assets/对应的后端目录，见 backend/agent/tools/local_assets.py 中LOCAL_ASSET_DIR的引用）查找该文件；
3. 在生成的 HTML中查找该文件名。

两步都命中，即可严格证明"上传的精确 logo 被原文照用、未重绘"。内容寻址还顺带解决了去重与缓存一致性：同一内容永远映射到同一文件名。

5.6 场景之间清空报告

每个场景跑完清空报告目录，保证下一次运行的报告归属干净——与 5.2 配合，形成"单场景 + 独立报告集"的 QA 节奏。

6. 完整 QA 检查清单（可直接照做）

7. 延伸阅读

• QA.md：本文章的原始清单；
• backend/asset_extraction.py：资产检测的 schema 约束与 Gemini 批处理（每批至多MAX_ASSETS_PER_GEMINI_REQUEST个请求）；
• backend/agent/tools/extract_assets.py 与 backend/agent/tools/definitions.py：资产提取工具的定义与执行入口；
• backend/agent/tools/runtime.py：工具运行时；
• backend/preview_screenshot/playwright_backend.py：预览截图的 Playwright 后端实现；
• backend/tests/test_asset_extraction.py、backend/tests/test_local_assets.py、backend/tests/test_tool_image_outputs.py：对应功能的自动化测试；
• Evaluation.md 与 backend/evals/：批量评测体系，可与 QA 流程互补使用。

【免费下载链接】screenshot-to-codeDrop in a screenshot and convert it to clean code (HTML/Tailwind/React/Vue)项目地址: https://gitcode.com/GitHub_Trending/sc/screenshot-to-code