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。这条检查点强调的不是页面里有张图而是裁剪坐标精确无偏移、无多余留白生成的 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_previewagent 渲染自己的 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 ChromiumREADME 中说明安装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之下否则返回Nonelocal_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 中说明该模式依赖 GeminiEdit / 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_ENABLED1LOGS_PATH…下每一次 LLM 请求都会落盘包含工具调用、返回结果和最终 HTML——grep 报告远比抓页面文本可靠。在浏览页/evals/prompt-reports查看。实现佐证backend/routes/prompt_reports.py 的模块注释说明报告是 JSON 文件由fs_logging.prompt_reportsbackend/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 使用独特且确定性的测试夹具fixturesQA 应使用一眼可辨、结构清晰的截图与 logo 作为 fixture比如一个轮廓鲜明的 logo 布局规整的页面截图这样只需肉眼核对就能判断是否挑对了资产。fixture 必须确定性保证多次运行可对比。仓库前端测试自带这类夹具的思路可参考 frontend/src/tests/fixtures/含 UI 截图与简单页面 HTML。5.5 资产是内容寻址的用哈希证明就是这个文件原文给出了关键机制资产文件名形如asset_sha256[:24].png取文件内容 SHA-256 的前 24 位十六进制。这带来一个可机械执行的验证流程对上传的原始 logo 文件计算 SHA-256取前 24 位拼出期望文件名在服务出来的资产目录即/local-assets/对应的后端目录见 backend/agent/tools/local_assets.py 中LOCAL_ASSET_DIR的引用查找该文件在生成的 HTML中查找该文件名。两步都命中即可严格证明上传的精确 logo 被原文照用、未重绘。内容寻址还顺带解决了去重与缓存一致性同一内容永远映射到同一文件名。5.6 场景之间清空报告每个场景跑完清空报告目录保证下一次运行的报告归属干净——与 5.2 配合形成单场景 独立报告集的 QA 节奏。6. 完整 QA 检查清单可直接照做类别检查点验证方法资产选择提取的是 logo / hero / feature icons而非按钮、文本、整页肉眼对比 fixturegrep prompt report 中的检测框裁剪精度crop 像素级贴合且被生成页面引用HTML 中引用的资产文件名 ↔ 裁剪产物一致上传直用上传的精确 logo 原样使用、不重绘SHA-256 前 24 位 →asset_hash.png出现在服务资产与 HTML 中自渲染预览screenshot_preview被调用并返回 desktop mobile 截图prompt report 中的工具调用与图像 part图像编辑edit_image/remove_background接受本地资产 URL工具执行成功local_assets.py的 data URL 内联路径生效回归Text→code / Video→code / 增量更新 / 多 variant 并行既有功能逐项冒烟跨模型工具图像送达 Gemini、OpenAI、ClaudeFast/Max 标签正确三家 provider 各跑一遍核对报告执行纪律单场景串行、输入框判定完成、确定性 fixture、场景间清报告5.1–5.6 的流程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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/5 22:36:03 · 阅读 1.2k screenshot-to-code 图像资产管线 QA 实践指南：如何验证资产提取、自渲染预览与图像编辑工具链
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。这条检查点强调的不是页面里有张图而是裁剪坐标精确无偏移、无多余留白生成的 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_previewagent 渲染自己的 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 ChromiumREADME 中说明安装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之下否则返回Nonelocal_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 中说明该模式依赖 GeminiEdit / 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_ENABLED1LOGS_PATH…下每一次 LLM 请求都会落盘包含工具调用、返回结果和最终 HTML——grep 报告远比抓页面文本可靠。在浏览页/evals/prompt-reports查看。实现佐证backend/routes/prompt_reports.py 的模块注释说明报告是 JSON 文件由fs_logging.prompt_reportsbackend/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 使用独特且确定性的测试夹具fixturesQA 应使用一眼可辨、结构清晰的截图与 logo 作为 fixture比如一个轮廓鲜明的 logo 布局规整的页面截图这样只需肉眼核对就能判断是否挑对了资产。fixture 必须确定性保证多次运行可对比。仓库前端测试自带这类夹具的思路可参考 frontend/src/tests/fixtures/含 UI 截图与简单页面 HTML。5.5 资产是内容寻址的用哈希证明就是这个文件原文给出了关键机制资产文件名形如asset_sha256[:24].png取文件内容 SHA-256 的前 24 位十六进制。这带来一个可机械执行的验证流程对上传的原始 logo 文件计算 SHA-256取前 24 位拼出期望文件名在服务出来的资产目录即/local-assets/对应的后端目录见 backend/agent/tools/local_assets.py 中LOCAL_ASSET_DIR的引用查找该文件在生成的 HTML中查找该文件名。两步都命中即可严格证明上传的精确 logo 被原文照用、未重绘。内容寻址还顺带解决了去重与缓存一致性同一内容永远映射到同一文件名。5.6 场景之间清空报告每个场景跑完清空报告目录保证下一次运行的报告归属干净——与 5.2 配合形成单场景 独立报告集的 QA 节奏。6. 完整 QA 检查清单可直接照做类别检查点验证方法资产选择提取的是 logo / hero / feature icons而非按钮、文本、整页肉眼对比 fixturegrep prompt report 中的检测框裁剪精度crop 像素级贴合且被生成页面引用HTML 中引用的资产文件名 ↔ 裁剪产物一致上传直用上传的精确 logo 原样使用、不重绘SHA-256 前 24 位 →asset_hash.png出现在服务资产与 HTML 中自渲染预览screenshot_preview被调用并返回 desktop mobile 截图prompt report 中的工具调用与图像 part图像编辑edit_image/remove_background接受本地资产 URL工具执行成功local_assets.py的 data URL 内联路径生效回归Text→code / Video→code / 增量更新 / 多 variant 并行既有功能逐项冒烟跨模型工具图像送达 Gemini、OpenAI、ClaudeFast/Max 标签正确三家 provider 各跑一遍核对报告执行纪律单场景串行、输入框判定完成、确定性 fixture、场景间清报告5.1–5.6 的流程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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考