screenshot-to-code 的 Agent 指令实践Poetry 环境、测试校验与本地服务启动规范【免费下载链接】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本文以截图转代码项目 screenshot-to-code 中的 CLAUDE.md与 AGENTS.md 内容一致的 AI Agent 项目指令文档为核心逐条解读其定义的 Python 虚拟环境约定、后端测试与类型检查策略、前端 lint 规则、Prompt 代码风格约定以及 Cursor Cloud 云环境下的依赖安装与服务启动方式。读完本文你既能按文档完整跑通该项目的本地开发与验证闭环也能理解每条指令背后对应的 pyproject.toml、pytest.ini 等真实配置并把这套给 Agent 写开发规约的思路复用到自己的仓库中。文档定位CLAUDE.md 在仓库中是什么CLAUDE.md 是一份面向 AI 编码助手Claude Code 等 Agent的项目级操作手册仓库根目录下的 AGENTS.md 与其内容完全一致供不同 Agent 框架读取。它回答的不是这个仓库做什么那是 README.md 的职责而是三个更工程化的问题环境怎么用——Python 命令必须走哪个虚拟环境、依赖如何安装改动后如何验证——每次代码变更必须跑哪些测试、类型检查、lint通过标准是什么哪些坑要绕开——端口、环境变量、工具链的隐含行为。这种文档的价值在于把原本只存在于维护者脑子里的隐性约定显性化让 Agent或新加入的开发者无需试错即可正确操作仓库。下文按原文档章节顺序逐条展开并给出每条指令在仓库源码中的落点。Python 环境一律使用 backend 的 Poetry 虚拟环境原文档的 Python 环境约定是所有 Python 命令必须使用 backend 的 Poetry 虚拟环境backend-py3.10首选调用方式为cd backend poetry run command若需要手动激活用cd backend backend/poetry env activate实际写法为cd backend poetry env activate查看当前环境对应的虚拟环境路径再执行它打印出的source .../bin/activate命令。这三条规则背后的依据可以直接在仓库中核对后端是一个非可打包的 Poetry 项目。backend/pyproject.toml 中声明package-mode false依赖 Python 版本约束为python ^3.10核心运行时依赖包括fastapi、uvicorn、websockets、openai、anthropic、google-genai、playwright等开发依赖dev group则固定为pytest、pyright、pytest-asyncio三个工具。由于依赖只安装在该虚拟环境里poetry run是保证命令与项目锁文件backend/poetry.lock所解析版本一致的最安全方式——它自动进入正确环境避免了系统 Python 缺包或版本漂移。poetry env activate的作用是查询当前项目虚拟环境的激活命令。在 Cursor Cloud 这类非交互环境中shell 不一定加载了.bashrc手动source一个记错的固定路径很容易失败而通过poetry env activate让 Poetry 自己输出当前解析出的路径是更健壮的做法。这里有一个文档专门点出的反直觉细节值得单独说明虚拟环境目录名虽然是backend-...-py3.10但实际解析到的 Python 是 3.12而不是 3.10。因为 pyproject.toml 中^3.10表示3.10,4.03.12 完全满足该约束。日常操作无需关心具体小版本统一poetry run即可。这条说明提醒我们Poetry 的 caret 约束是向后兼容到主版本的语义环境名中带的小版本号只是创建环境时的快照不代表版本上限。测试与类型检查策略每次变更后的强制验证闭环原文档的 Testing policy 给出了两条每次代码变更后必须执行的规则和一条通过标准# 变更后运行后端测试 cd backend poetry run pytest # 变更后运行类型检查 cd backend poetry run pyright通过标准Type checking policy是被修改的文件中不允许出现新的 pyright 警告。也就是说仓库允许存量警告存在但禁止带伤通过——你动过的文件必须不引入新告警。这条策略在仓库配置中有两处直接印证backend/pytest.ini 定义了测试发现规则与默认参数testpaths tests、文件模式test_*.py、函数模式test_*addopts -v --tbshort详细输出 短 traceback并且asyncio_mode auto让pytest-asyncio自动处理异步测试用例。因此poetry run pytest无需任何额外参数就能在 backend/tests/ 下发现全部 30 余个测试文件。backend/pyrightconfig.json 将检查模式设为basicreportMissingTypeStubs降为none不强制第三方库类型桩并排除image_generation.py这正是存量告警可控、增量零告警策略能够成立的前提——配置已经把噪声压到了合理水平。从 backend/tests/ 的测试文件命名如test_agent_engine.py、test_openai_provider_session.py、test_asset_extraction.py可以看出测试覆盖 Agent 引擎、各模型 Provider 会话、资产抽取、评估系统等核心链路这也解释了为什么文档把改完必跑全量 pytest定为硬性规则。前端校验pnpm lint 与基线告警的边界原文档对前端只有一条命令cd frontend pnpm lint并补充了一句关键说明如果改动同时涉及前后端两套校验都要跑If changes touch both, run both sets。结合 frontend/package.json 可以看到lint脚本的完整定义lint: eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0--max-warnings 0意味着任何一条 lint 告警都会让命令以失败退出码结束。这也引出了原文档最后一条非显然注意事项当前pnpm lint会报出存量错误例如generateCode.ts中的typescript-eslint/no-explicit-any这些是基线问题baseline issues属于代码历史遗留而不是环境装坏了。理解这条边界的意义在于Agent 在云环境里跑 lint 失败时应当把它归类为已知基线而不是反复重装依赖试图修复环境。另外frontend/package.json 通过packageManager字段锁定了pnpm10.32.1、engines要求node 14.18.0依赖侧还包含puppeteer用于 QA 测试test:qa脚本——这就解释了下一条注意事项中pnpm install提示忽略 esbuild/puppeteer 构建脚本的现象该提示无害Vite 的 dev/build 与 Jest 测试都不依赖这些 native 构建脚本。Prompt 代码风格约定多行提示词一律三引号原文档的 Prompt formatting 一节规定多行 prompt 文本优先使用三引号字符串...需要插值的多行 prompt优先用单个三引号 f-string而不是把字符串片段拼接起来。这条约定针对的是后端提示词工程的典型痛点。本仓库的提示词构建集中在 backend/prompts/ 目录pipeline.py、system_prompt.py、message_builder.py以及create/、update/子模块其中存在大量需要插入变量用户请求、文件快照、设计系统等的长文本模板。字符串拼接a b var c在换行、缩进、引号转义上都极易出错而单个三引号 f-string 保持了模板的整体性与可读性也便于 Agent 在批量改写提示词时做结构化 diff。对维护者来说这是一条低成本、高收益的风格护栏。Hosted 分支连接独立 SaaS 后端的发布形态原文档用一节简短说明了hosted分支的存在hosted 版本位于hosted分支。该分支连接一个 SaaS 后端位于另一个代码库../screenshot-to-code-saas。从源码结构看这一说法有两处印证frontend/package.json 中除常规dev/build外还定义了dev-hostedvite --mode prod与build-hostedtsc vite build --mode prod即前端本身预留了托管模式的构建入口scripts/cursor-cloud-install.sh 末尾会检测同级目录../screenshot-to-code-saas下的backend/与admin/是否存在若存在则分别为其执行poetry install --no-root与pnpm install。这说明 hosted 分支与自托管分支共享同一份前端代码差异主要体现在后端连接目标与构建模式上。文档把这节放在 Agent 指令中是为了防止 Agent 误改 hosted 相关逻辑时去错误的代码库里找实现。Cursor Cloud 云环境依赖自动刷新与安装脚本原文档的 Cursor Cloud specific instructions 一节给出了云沙箱场景的完整操作约定依赖在启动时自动刷新backend/跑poetry install、frontend/跑pnpm install因此 Agent 无需手动安装依赖环境初始化脚本为bash /agent/repos/screenshot-to-code/scripts/cursor-cloud-install.sh对应仓库内的真实脚本是 scripts/cursor-cloud-install.sh其执行逻辑值得完整过一遍REPO_ROOT$(cd $(dirname ${BASH_SOURCE[0]})/.. pwd) cd $REPO_ROOT # 先切到仓库根目录保证与启动时的工作目录无关 curl -sSL https://install.python-poetry.org | python3 - # 安装/更新 poetry ~/.local/bin/poetry -C backend install # 后端依赖 ~/.local/bin/poetry -C backend run playwright install chromium || true # Chromium失败不阻断 pnpm -C frontend install # 前端依赖 # 若存在 ../screenshot-to-code-saas则顺带安装其 backend 与 admin脚本有三个可取的设计点与文档中的注意事项一一对应先cd到仓库根目录再安装这正是文档所说脚本会先切到仓库根目录因此无论启动时工作目录在哪都能正常工作poetry 使用全路径~/.local/bin/poetry而非裸命令——因为 poetry 装在~/.local/bin交互式 shell 通过.bashrc把它放进了 PATH但非交互脚本如云沙箱的执行器不一定加载.bashrc裸poetry可能报 command not foundplaywright install chromium || true允许失败——Chromium 下载失败不阻断整体安装因为截图预览只是可选能力。本地服务启动端口、WebSocket 与同源代码文档指出服务的规范命令以 README.md 为准seeREADME.mdfor the canonical commands并给出了两条核心服务的启动方式# 后端FastAPI WebSocket在 backend/ 下执行 poetry run uvicorn main:app --reload --port 7001 # 前端Vite/React在 frontend/ 下执行 pnpm dev # 然后打开 http://localhost:5173文档特别强调了三个容易踩坑的细节均可在源码中找到对应实现1. Vite 只绑定localhost必须用http://localhost:5173访问。用http://127.0.0.1:5173会直接拒绝连接。这是 Vite dev server 的默认 host 行为对 Agent 来说是一条高频卡点自动化脚本里写127.0.0.1就能复现服务明明在跑却连不上的假故障。2. 前端与后端走 WebSocket 通信环境变量为VITE_WS_BACKEND_URL。文档表述其默认值为ws://127.0.0.1:7001生成过程generation的流式输出经由该 WebSocket 推送其余路由为普通 HTTP。从 frontend/src/config.ts 的实现可以看到更细的降级逻辑export const WS_BACKEND_URL import.meta.env.VITE_WS_BACKEND_URL || SAME_ORIGIN_WS;即未显式设置VITE_WS_BACKEND_URL时前端会退回同源WebSocket 地址HTTP 协议头替换为ws。frontend/src/config.ts 中的注释解释了这一设计的动机配合 Vite dev server 的代理让应用在隧道/预览 URL 下也能工作——此时localhost指向的是查看者自己的机器而不是沙箱。因此在本地标准开发中按文档配置指向ws://127.0.0.1:7001即可而在云端隧道场景下则依赖同源代码自动适配。docker-compose.yml 也再次提示改后端端口时要同步修改frontend/.env.local中的VITE_WS_BACKEND_URL。3. 后端端口 7001 有自动避让机制。虽然文档给出的规范命令显式指定--port 7001但 backend/start.py 实现了更宽松的策略从--port默认 7001开始最多探测--max-port-attempts默认 20个端口遇到占用自动顺延并打印提示Port 7001 is in use. Starting backend on port 7002.。在云沙箱多实例并存时这一机制能显著减少端口冲突导致的启动失败。环境变量与 API Key核心能力的启动前提原文档的 Non-obvious caveats 中API Key 一节信息密度最高完整内容为截图转代码这一核心功能至少需要一个 LLM KeyOPENAI_API_KEY、ANTHROPIC_API_KEY或GEMINI_API_KEY三选一设置位置二选一写入backend/.env改完必须重启后端或通过应用内 Settings 对话框填写一个 Key 都没有时生成会快速失败并提示 No OpenAI, Anthropic, or Gemini API keyREPLICATE_API_KEY图像生成/编辑能力只能通过backend/.env配置UI 不支持。这条消息字符串在源码中可以直接定位backend/routes/generate_code.py 中的throw_error提示与文档描述逐字对应并额外给出了补救指引If you add it to .env, make sure to restart the backend server。从源码结构看_get_variant_models接收openai_api_key、anthropic_api_key、gemini_api_key三个可选参数来装配变体模型也就是说三个 Key 全部缺失才会触发该失败路径——这与三选一即可的文档表述一致。对 Agent 的实际意义是云沙箱首次跑生成任务前应先确认 Key 来源.env还是 Settings并记住.env路径不热加载这一约束避免改了 .env 却以为没生效的误判。其他环境注意事项的逐条印证文档末尾还列了三条云环境专属的非显然注意事项逐条说明如下Playwright Chromium 已预装供可选的 Screenshot preview 工具使用Settings 页面中显示为 Available。这与 scripts/cursor-cloud-install.sh 中playwright install chromium的安装步骤、pyproject.toml 中playwright ^1.61.0的依赖声明相互印证后端对应实现位于 backend/preview_screenshot/playwright_backend.py。pnpm install会打印 Ignored build scripts (esbuild, puppeteer) 警告这是 pnpm 出于安全默认忽略依赖包安装脚本的行为无害Vite 构建、dev server 和 Jest 测试都不需要批准这些构建。poetry在非交互 shell 中可能不在 PATH前文已述解决方案就是统一用~/.local/bin/poetry全路径或poetry run。结语一份 Agent 指令文档应有的形态CLAUDE.md 展示了 AI Agent 协作场景下项目文档的完整写法环境约束Poetry venv poetry run保证依赖一致性并用源码级解释^3.10语义消除命名带来的误导验证闭环pytest pyright pnpm lint 三条命令、改动文件零新告警的通过标准让 Agent 可以自主判断改动是否合格且通过标准与 pytest.ini、pyrightconfig.json 的实际配置严格对齐风格约定三引号 f-string针对本仓库提示词工程的真实痛点陷阱清单Vite 只绑 localhost、WebSocket 环境变量、Key 不热加载、lint 基线告警、pnpm 构建脚本警告把维护者的踩坑经验显性化避免 Agent 在同样的坑上反复试错。这套命令可复制、标准可验证、陷阱有出处的写法可以作为为任何多端前端 后端项目编写 Agent 指令文档的参考模板。【免费下载链接】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），仅供参考 screenshot-to-code 的 Agent 指令实践：Poetry 环境、测试校验与本地服务启动规范
screenshot-to-code 的 Agent 指令实践Poetry 环境、测试校验与本地服务启动规范【免费下载链接】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本文以截图转代码项目 screenshot-to-code 中的 CLAUDE.md与 AGENTS.md 内容一致的 AI Agent 项目指令文档为核心逐条解读其定义的 Python 虚拟环境约定、后端测试与类型检查策略、前端 lint 规则、Prompt 代码风格约定以及 Cursor Cloud 云环境下的依赖安装与服务启动方式。读完本文你既能按文档完整跑通该项目的本地开发与验证闭环也能理解每条指令背后对应的 pyproject.toml、pytest.ini 等真实配置并把这套给 Agent 写开发规约的思路复用到自己的仓库中。文档定位CLAUDE.md 在仓库中是什么CLAUDE.md 是一份面向 AI 编码助手Claude Code 等 Agent的项目级操作手册仓库根目录下的 AGENTS.md 与其内容完全一致供不同 Agent 框架读取。它回答的不是这个仓库做什么那是 README.md 的职责而是三个更工程化的问题环境怎么用——Python 命令必须走哪个虚拟环境、依赖如何安装改动后如何验证——每次代码变更必须跑哪些测试、类型检查、lint通过标准是什么哪些坑要绕开——端口、环境变量、工具链的隐含行为。这种文档的价值在于把原本只存在于维护者脑子里的隐性约定显性化让 Agent或新加入的开发者无需试错即可正确操作仓库。下文按原文档章节顺序逐条展开并给出每条指令在仓库源码中的落点。Python 环境一律使用 backend 的 Poetry 虚拟环境原文档的 Python 环境约定是所有 Python 命令必须使用 backend 的 Poetry 虚拟环境backend-py3.10首选调用方式为cd backend poetry run command若需要手动激活用cd backend backend/poetry env activate实际写法为cd backend poetry env activate查看当前环境对应的虚拟环境路径再执行它打印出的source .../bin/activate命令。这三条规则背后的依据可以直接在仓库中核对后端是一个非可打包的 Poetry 项目。backend/pyproject.toml 中声明package-mode false依赖 Python 版本约束为python ^3.10核心运行时依赖包括fastapi、uvicorn、websockets、openai、anthropic、google-genai、playwright等开发依赖dev group则固定为pytest、pyright、pytest-asyncio三个工具。由于依赖只安装在该虚拟环境里poetry run是保证命令与项目锁文件backend/poetry.lock所解析版本一致的最安全方式——它自动进入正确环境避免了系统 Python 缺包或版本漂移。poetry env activate的作用是查询当前项目虚拟环境的激活命令。在 Cursor Cloud 这类非交互环境中shell 不一定加载了.bashrc手动source一个记错的固定路径很容易失败而通过poetry env activate让 Poetry 自己输出当前解析出的路径是更健壮的做法。这里有一个文档专门点出的反直觉细节值得单独说明虚拟环境目录名虽然是backend-...-py3.10但实际解析到的 Python 是 3.12而不是 3.10。因为 pyproject.toml 中^3.10表示3.10,4.03.12 完全满足该约束。日常操作无需关心具体小版本统一poetry run即可。这条说明提醒我们Poetry 的 caret 约束是向后兼容到主版本的语义环境名中带的小版本号只是创建环境时的快照不代表版本上限。测试与类型检查策略每次变更后的强制验证闭环原文档的 Testing policy 给出了两条每次代码变更后必须执行的规则和一条通过标准# 变更后运行后端测试 cd backend poetry run pytest # 变更后运行类型检查 cd backend poetry run pyright通过标准Type checking policy是被修改的文件中不允许出现新的 pyright 警告。也就是说仓库允许存量警告存在但禁止带伤通过——你动过的文件必须不引入新告警。这条策略在仓库配置中有两处直接印证backend/pytest.ini 定义了测试发现规则与默认参数testpaths tests、文件模式test_*.py、函数模式test_*addopts -v --tbshort详细输出 短 traceback并且asyncio_mode auto让pytest-asyncio自动处理异步测试用例。因此poetry run pytest无需任何额外参数就能在 backend/tests/ 下发现全部 30 余个测试文件。backend/pyrightconfig.json 将检查模式设为basicreportMissingTypeStubs降为none不强制第三方库类型桩并排除image_generation.py这正是存量告警可控、增量零告警策略能够成立的前提——配置已经把噪声压到了合理水平。从 backend/tests/ 的测试文件命名如test_agent_engine.py、test_openai_provider_session.py、test_asset_extraction.py可以看出测试覆盖 Agent 引擎、各模型 Provider 会话、资产抽取、评估系统等核心链路这也解释了为什么文档把改完必跑全量 pytest定为硬性规则。前端校验pnpm lint 与基线告警的边界原文档对前端只有一条命令cd frontend pnpm lint并补充了一句关键说明如果改动同时涉及前后端两套校验都要跑If changes touch both, run both sets。结合 frontend/package.json 可以看到lint脚本的完整定义lint: eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0--max-warnings 0意味着任何一条 lint 告警都会让命令以失败退出码结束。这也引出了原文档最后一条非显然注意事项当前pnpm lint会报出存量错误例如generateCode.ts中的typescript-eslint/no-explicit-any这些是基线问题baseline issues属于代码历史遗留而不是环境装坏了。理解这条边界的意义在于Agent 在云环境里跑 lint 失败时应当把它归类为已知基线而不是反复重装依赖试图修复环境。另外frontend/package.json 通过packageManager字段锁定了pnpm10.32.1、engines要求node 14.18.0依赖侧还包含puppeteer用于 QA 测试test:qa脚本——这就解释了下一条注意事项中pnpm install提示忽略 esbuild/puppeteer 构建脚本的现象该提示无害Vite 的 dev/build 与 Jest 测试都不依赖这些 native 构建脚本。Prompt 代码风格约定多行提示词一律三引号原文档的 Prompt formatting 一节规定多行 prompt 文本优先使用三引号字符串...需要插值的多行 prompt优先用单个三引号 f-string而不是把字符串片段拼接起来。这条约定针对的是后端提示词工程的典型痛点。本仓库的提示词构建集中在 backend/prompts/ 目录pipeline.py、system_prompt.py、message_builder.py以及create/、update/子模块其中存在大量需要插入变量用户请求、文件快照、设计系统等的长文本模板。字符串拼接a b var c在换行、缩进、引号转义上都极易出错而单个三引号 f-string 保持了模板的整体性与可读性也便于 Agent 在批量改写提示词时做结构化 diff。对维护者来说这是一条低成本、高收益的风格护栏。Hosted 分支连接独立 SaaS 后端的发布形态原文档用一节简短说明了hosted分支的存在hosted 版本位于hosted分支。该分支连接一个 SaaS 后端位于另一个代码库../screenshot-to-code-saas。从源码结构看这一说法有两处印证frontend/package.json 中除常规dev/build外还定义了dev-hostedvite --mode prod与build-hostedtsc vite build --mode prod即前端本身预留了托管模式的构建入口scripts/cursor-cloud-install.sh 末尾会检测同级目录../screenshot-to-code-saas下的backend/与admin/是否存在若存在则分别为其执行poetry install --no-root与pnpm install。这说明 hosted 分支与自托管分支共享同一份前端代码差异主要体现在后端连接目标与构建模式上。文档把这节放在 Agent 指令中是为了防止 Agent 误改 hosted 相关逻辑时去错误的代码库里找实现。Cursor Cloud 云环境依赖自动刷新与安装脚本原文档的 Cursor Cloud specific instructions 一节给出了云沙箱场景的完整操作约定依赖在启动时自动刷新backend/跑poetry install、frontend/跑pnpm install因此 Agent 无需手动安装依赖环境初始化脚本为bash /agent/repos/screenshot-to-code/scripts/cursor-cloud-install.sh对应仓库内的真实脚本是 scripts/cursor-cloud-install.sh其执行逻辑值得完整过一遍REPO_ROOT$(cd $(dirname ${BASH_SOURCE[0]})/.. pwd) cd $REPO_ROOT # 先切到仓库根目录保证与启动时的工作目录无关 curl -sSL https://install.python-poetry.org | python3 - # 安装/更新 poetry ~/.local/bin/poetry -C backend install # 后端依赖 ~/.local/bin/poetry -C backend run playwright install chromium || true # Chromium失败不阻断 pnpm -C frontend install # 前端依赖 # 若存在 ../screenshot-to-code-saas则顺带安装其 backend 与 admin脚本有三个可取的设计点与文档中的注意事项一一对应先cd到仓库根目录再安装这正是文档所说脚本会先切到仓库根目录因此无论启动时工作目录在哪都能正常工作poetry 使用全路径~/.local/bin/poetry而非裸命令——因为 poetry 装在~/.local/bin交互式 shell 通过.bashrc把它放进了 PATH但非交互脚本如云沙箱的执行器不一定加载.bashrc裸poetry可能报 command not foundplaywright install chromium || true允许失败——Chromium 下载失败不阻断整体安装因为截图预览只是可选能力。本地服务启动端口、WebSocket 与同源代码文档指出服务的规范命令以 README.md 为准seeREADME.mdfor the canonical commands并给出了两条核心服务的启动方式# 后端FastAPI WebSocket在 backend/ 下执行 poetry run uvicorn main:app --reload --port 7001 # 前端Vite/React在 frontend/ 下执行 pnpm dev # 然后打开 http://localhost:5173文档特别强调了三个容易踩坑的细节均可在源码中找到对应实现1. Vite 只绑定localhost必须用http://localhost:5173访问。用http://127.0.0.1:5173会直接拒绝连接。这是 Vite dev server 的默认 host 行为对 Agent 来说是一条高频卡点自动化脚本里写127.0.0.1就能复现服务明明在跑却连不上的假故障。2. 前端与后端走 WebSocket 通信环境变量为VITE_WS_BACKEND_URL。文档表述其默认值为ws://127.0.0.1:7001生成过程generation的流式输出经由该 WebSocket 推送其余路由为普通 HTTP。从 frontend/src/config.ts 的实现可以看到更细的降级逻辑export const WS_BACKEND_URL import.meta.env.VITE_WS_BACKEND_URL || SAME_ORIGIN_WS;即未显式设置VITE_WS_BACKEND_URL时前端会退回同源WebSocket 地址HTTP 协议头替换为ws。frontend/src/config.ts 中的注释解释了这一设计的动机配合 Vite dev server 的代理让应用在隧道/预览 URL 下也能工作——此时localhost指向的是查看者自己的机器而不是沙箱。因此在本地标准开发中按文档配置指向ws://127.0.0.1:7001即可而在云端隧道场景下则依赖同源代码自动适配。docker-compose.yml 也再次提示改后端端口时要同步修改frontend/.env.local中的VITE_WS_BACKEND_URL。3. 后端端口 7001 有自动避让机制。虽然文档给出的规范命令显式指定--port 7001但 backend/start.py 实现了更宽松的策略从--port默认 7001开始最多探测--max-port-attempts默认 20个端口遇到占用自动顺延并打印提示Port 7001 is in use. Starting backend on port 7002.。在云沙箱多实例并存时这一机制能显著减少端口冲突导致的启动失败。环境变量与 API Key核心能力的启动前提原文档的 Non-obvious caveats 中API Key 一节信息密度最高完整内容为截图转代码这一核心功能至少需要一个 LLM KeyOPENAI_API_KEY、ANTHROPIC_API_KEY或GEMINI_API_KEY三选一设置位置二选一写入backend/.env改完必须重启后端或通过应用内 Settings 对话框填写一个 Key 都没有时生成会快速失败并提示 No OpenAI, Anthropic, or Gemini API keyREPLICATE_API_KEY图像生成/编辑能力只能通过backend/.env配置UI 不支持。这条消息字符串在源码中可以直接定位backend/routes/generate_code.py 中的throw_error提示与文档描述逐字对应并额外给出了补救指引If you add it to .env, make sure to restart the backend server。从源码结构看_get_variant_models接收openai_api_key、anthropic_api_key、gemini_api_key三个可选参数来装配变体模型也就是说三个 Key 全部缺失才会触发该失败路径——这与三选一即可的文档表述一致。对 Agent 的实际意义是云沙箱首次跑生成任务前应先确认 Key 来源.env还是 Settings并记住.env路径不热加载这一约束避免改了 .env 却以为没生效的误判。其他环境注意事项的逐条印证文档末尾还列了三条云环境专属的非显然注意事项逐条说明如下Playwright Chromium 已预装供可选的 Screenshot preview 工具使用Settings 页面中显示为 Available。这与 scripts/cursor-cloud-install.sh 中playwright install chromium的安装步骤、pyproject.toml 中playwright ^1.61.0的依赖声明相互印证后端对应实现位于 backend/preview_screenshot/playwright_backend.py。pnpm install会打印 Ignored build scripts (esbuild, puppeteer) 警告这是 pnpm 出于安全默认忽略依赖包安装脚本的行为无害Vite 构建、dev server 和 Jest 测试都不需要批准这些构建。poetry在非交互 shell 中可能不在 PATH前文已述解决方案就是统一用~/.local/bin/poetry全路径或poetry run。结语一份 Agent 指令文档应有的形态CLAUDE.md 展示了 AI Agent 协作场景下项目文档的完整写法环境约束Poetry venv poetry run保证依赖一致性并用源码级解释^3.10语义消除命名带来的误导验证闭环pytest pyright pnpm lint 三条命令、改动文件零新告警的通过标准让 Agent 可以自主判断改动是否合格且通过标准与 pytest.ini、pyrightconfig.json 的实际配置严格对齐风格约定三引号 f-string针对本仓库提示词工程的真实痛点陷阱清单Vite 只绑 localhost、WebSocket 环境变量、Key 不热加载、lint 基线告警、pnpm 构建脚本警告把维护者的踩坑经验显性化避免 Agent 在同样的坑上反复试错。这套命令可复制、标准可验证、陷阱有出处的写法可以作为为任何多端前端 后端项目编写 Agent 指令文档的参考模板。【免费下载链接】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），仅供参考