深度解析 stitch-skills 的 upload_to_stitch.py3 步绕过 AI 令牌限制的大文件上传指南【免费下载链接】stitch-skillsA library of Agent Skills designed to work with the Stitch MCP server. Each skill follows the Agent Skills open standard, for compatibility with coding agents such as Antigravity, Gemini CLI, Claude Code, Cursor.项目地址: https://gitcode.com/GitHub_Trending/st/stitch-skillsstitch-skills 是专为 Google Stitch 设计的一套 Agent Skills 技能库其中 upload_to_stitch.py 脚本解决了一个让很多 AI 开发者头疼的问题AI 模型无法直接把大文件上传到 Stitch 项目。本文带你读懂它的令牌限制绕过原理并给出一份可上手的完整使用指南。一、为什么 AI 直接上传文件会失败在 Agent Skills 生态中AI 模型调用 MCP 工具时所有参数都是模型的输出文本。这意味着文件必须先在内存里转成 base64 字符串模型要把这串 base64逐字重新生成出来而模型的输出上限只有约16K tokens结果就是一张仅 53KB 的 PNG 图base64 编码后约 71K 个字符远超输出上限。输出在字符串中间被截断生成损坏的数据API 直接拒绝。这个原理说明就写在脚本文件开头 upload_to_stitch.py#L4-L14作者把脚本为什么存在解释得非常清楚这个脚本完全绕开模型——它在本地进程内读取文件、编码并把完整载荷直接通过 HTTP 发出去没有任何令牌限制。一句话总结原理把让 AI 背出文件内容改成让脚本直接发文件AI 只负责传文件路径不碰文件内容。二、令牌限制绕过的三步核心流程整个脚本只有 268 行核心逻辑可以拆成三步第 1 步进程内 base64 编码encode_fileencode_file 函数 用 Python 原生base64模块一次性读取并编码整个文件。编码发生在本地 Python 进程里不占用模型的任何输出预算——文件多大都无所谓。第 2 步按文件类型构建请求体build_screen_requestbuild_screen_request 函数 根据 MIME 类型自动分流扩展名MIME 类型在 Stitch 中的角色.png.jpg.jpeg.webp图片作为屏幕截图screenshotIMAGE 类型.html.htm文本作为 HTML 代码htmlCodeDOCUMENT 类型.md文本作为设计文档DOCUMENT 类型上传 Markdown 或 HTML 时脚本还会自动标记generatedBy字段如UserUploadedDesignMd方便 Stitch 识别文件来源。第 3 步直接 HTTP 调用 BatchCreateScreens 接口call_batch_create_screens 函数 用标准库urllib向POST /v1/projects/{projectId}/screens:batchCreate发送完整 JSON 载荷通过X-Goog-Api-Key请求头鉴权并设置了 120 秒超时。 注意第 111-112 行还有一个隐藏细节脚本会尝试加载certifi证书包来创建 SSL 上下文这正是为了修复 macOS 上 Python 缺少根证书导致的CERTIFICATE_VERIFY_FAILED报错。三、一键上传upload_to_stitch.py 快速上手1. 准备工作先克隆仓库只需一次git clone https://gitcode.com/GitHub_Trending/st/stitch-skills然后准备好两个参数project-idStitch 项目 ID可用 MCP 的list_projects工具查询api-key从你 Agent 的 MCP 配置文件中提取位置参考 SKILL.mdAntigravity.gemini/antigravity/mcp_config.jsonGemini CLI~/.gemini/settings.jsonClaude Code~/.claude.json2. 执行上传命令python3 plugins/stitch-design/skills/upload-to-stitch/scripts/upload_to_stitch.py \ --project-id PROJECT_ID \ --file-path ./landing_page.html \ --api-key API_KEY \ --title /dashboard常用可选参数参数说明--api-urlAPI 基础地址默认https://stitch.googleapis.com--title屏幕标题上传网页时建议填路由路径如/settings--generated-by标注文件来源如stitch::extract-static-html脚本运行时会打印文件大小、base64 长度、API 地址等中间状态最后输出完整的 JSON 响应方便你排查问题。3. macOS SSL 报错怎么办如果看到ssl.SSLCertVerificationError先尝试pip install certifi脚本会自动识别装不上就用环境变量手动指定证书文件完整写法见 SKILL.md 排错章节。四、它在整个 stitch-skills 生态中的位置upload-to-stitch不是孤立的工具而是多条技能链路的最后一公里code-to-design把现有前端代码React、Vue、Angular 等转成 Stitch 设计的总指挥串联提取 HTML → 提取设计系统 → 上传三步最终都交给本脚本完成上传manage-design-system当 DESIGN.md 较大时超过约 5KB推荐直接用本脚本上传同样是为了绕开输出令牌限制extract-static-html先把运行中的网页快照成自包含的 HTML 文件CSS 内联、图片转 base64 写入文件再由本脚本上传——文件落盘这一步同样规避了上下文截断也就是说写文件到磁盘 脚本直连 HTTP是贯穿整个 stitch-skills 的设计哲学凡是内容可能超过令牌上限的产物一律先落盘再由脚本搬运。五、常见问题 FAQQ1小文件是不是可以直接用 MCP 工具上传可以。像小体积的 DESIGN.md 5KB可以直接调用upload_design_md工具见 tool-schema.md 的说明。大文件则必须走脚本。Q2上传前 AI 会直接执行脚本吗不会。按 SKILL.md 的检查点要求Agent 必须先向你展示要上传的文件路径、大小、类型等你明确同意后才执行——这是一个有意的安全设计。Q3这个脚本只支持 Stitch 吗是的它针对 Stitch 的BatchCreateScreensREST API 设计支持图片、HTML、Markdown 三类文件其他格式如.txt、.pdf会被拒绝并提示支持的类型。六、总结upload_to_stitch.py用不到 300 行代码给出了一个通用解法识别问题MCP 工具参数是模型输出受 16K 令牌上限约束base64 大文件必然被截断绕开模型在本地进程内完成编码让 AI 只传递路径而非内容直连 API标准库 SSL 兜底一条 HTTP 请求搞定上传这套路径代替内容的思路对任何需要 AI Agent 处理大文件的场景都有参考价值。如果你想把它用起来从 upload-to-stitch 技能目录 开始就是最快的路径。【免费下载链接】stitch-skillsA library of Agent Skills designed to work with the Stitch MCP server. Each skill follows the Agent Skills open standard, for compatibility with coding agents such as Antigravity, Gemini CLI, Claude Code, Cursor.项目地址: https://gitcode.com/GitHub_Trending/st/stitch-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
