uploads.sh

---

拉取请求开启时，产物已就绪

uploads 会托管编码 Agent 生成的产物，并为它们提供稳定的公开 URL，供 Agent 在拉取请求和 issue 中使用：屏幕截图和屏幕录制， 以及测试报告、日志、JSON、CSV、Markdown、PDF 和压缩包 （完整列表见方案与限制）。在 分支上，uploads put 会在每个文件准备就绪后立即暂存该文件。拉取请求开启时，uploads.sh 会将暂存的文件整合到一条托管评论中。

GitHub 自带的附件功能可在浏览器中使用；自 GitHub CLI 2.99 （2026 年 9 月）起，也可通过 gh … --attach 使用，但必须先有拉取请求或 issue，而且文件仍由 GitHub 自己托管，无法在其他地方嵌入或获取。uploads.sh 让 Agent 能在构建和测试变更的同一终端中获取稳定的 公开 URL，即使分支上的工作尚未完成；GitHub（目前）尚无实现这一功能的公开 API。 托管的 MCP 服务也能为无法运行命令的 Agent 提供同样的功能，可接收文件字节或 URL。

键名不含哈希，因此重新上传同名文件会直接覆盖原文件，URL 始终不变——所有引用它的嵌入内容都会立即更新。工作区会隔离不同租户（以及各自的预算和键策略）。

此仓库是 uploads.sh 上正式部署版本的源代码： API worker、auth worker、MCP 服务、Astro Web 应用，以及 @buildinternet/uploads CLI（从 packages/uploads 发布到 npm）。

效果展示

每个 PR 仅有一条评论，并在每次同步时原地重写。标记为 --state before 和 --state after 的文件会配对并排显示在表格中；其他 图片和视频显示在表格下方，非媒体文件（报告、日志、归档文件） 则会列在文件表格中，并注明类型和大小。

_{真实评论见 #436。}

当多组配对共用一条评论时，会通过 --meta path=… 配对（每个路径对应一个 before 和一个 after）；如果没有此标记，则会根据文件名配对，文件名仅在 before/after 标记上有所不同，例如 hero-before.webp 和 hero-after.webp。

你上传的所有内容也会按来源归类到工作区中——页面按 path 分组， 项目按 repo 或 app 分组——并可在一个地方浏览。

_{截图视图按项目和路径对上传内容进行分组。}

打开任意文件即可进入分享页面：其中包含可直接复制的嵌入代码（Markdown、HTML 等）、 原始 URL 和删除按钮。

_{每个文件的分享页面都包含可直接复制的嵌入代码、详情和删除操作。}

快速开始

安装 CLI 并登录一次：

npm install --global @buildinternet/uploads
uploads login

上传文件并标记其所展示的页面：

uploads put ./settings.png --meta path=/settings

在分支上，put 会自动暂存文件。像平常一样创建拉取请求。 GitHub App 会将暂存文件整理到一条托管附件评论中。

更多上传方式

使用相同的命令上传前后对比证据、开放的拉取请求、浏览器截图或带注释的图片：

# Pair two states from the same page in the pull request comment.
uploads put ./before.png --meta path=/settings --state before
uploads put ./after.png --meta path=/settings --state after

# See what this branch will attach when the pull request opens.
uploads staged

# Attach files directly when a pull request or issue is already open.
uploads attach ./before.png ./after.png

# Capture, annotate, and upload a page in one command.
uploads screenshot http://localhost:4321/settings --via local --annotate ./callouts.json

attach 会通过 gh 检测代码仓库和当前 PR，上传所有文件，并创建或更新同一条评论。 如果没有 GitHub App，请在创建拉取请求后运行 uploads attach --promote，以整理之前暂存的文件。无需全局安装，即可通过 npx @buildinternet/uploads … 运行所有命令。

使用 GitHub 或魔法链接登录，然后创建自己的工作区，或接受邀请加入现有工作区—— 详见加入工作区。托管文件是公开 URL——私有仓库的附件会使用 不可猜测的链接 （了解其工作原理），但任何持有 URL 的人都能查看文件。 如果文件看起来包含凭据、ID 或卡号，我们会在公开前将其暂存，等待你审核，但不要依赖这一机制： 请勿上传密钥或敏感界面内容。

在 CI 中要求提供截图

对于更改 UI 文件的拉取请求，GitHub App 会在测试和构建旁添加一项 uploads.sh 检查。无需工作流或 Actions 步骤。默认情况下，它只报告结果，不会阻止任何人。 在工作区的 Settings → GitHub 中启用 Require screenshots on UI changes，或在某个代码仓库的 .uploads.yml 中设置此项， 检查就会在收到截图之前失败：

comment:
  check:
    require: [before-after, desktop, mobile] # or just [uploads]

PR 评论会显示一份清单，并在文件到达时自动勾选。直接拖到 GitHub PR 中的图片也会计入， 因此没有使用 uploads.sh 的贡献者不会因此受阻；而 skip-uploads 标签可以跳过无需截图的 PR。 在分支保护中将 uploads.sh 添加为必需状态检查，即可阻止合并。 有关设置、哪些文件会被视为 UI 文件以及跳过标签，请参阅 要求拉取请求提供截图。

连接你的 Agent

托管的 MCP 服务运行在 https://agents.uploads.sh/mcp，并以 sh.uploads/mcp 的名称列于 MCP Registry。 本地 stdio 命令是同一 npm 包中的 uploads mcp。

# Claude Code
claude mcp add --transport http uploads https://agents.uploads.sh/mcp

# Codex
codex mcp add uploads --url https://agents.uploads.sh/mcp

# OpenCode
opencode mcp add uploads --url https://agents.uploads.sh/mcp

uploads install 会添加 Agent 技能和 MCP 服务，因此后续会话无需提示即可捕获每个视觉里程碑。这些技能也可以单独安装到任何 Agent 运行时中：

npx skills add buildinternet/uploads

这会安装三项技能：github-screenshots（视觉内容 → PR/议题）、uploads-cli（完整的 CLI 参考）和 annotate-screenshots（为截图添加标注和涂抹）。

在 Claude Code 或 Codex 中，插件会打包这些技能、MCP 服务和 PR 提交前的截图提醒。在 Claude Code 中，它还会在提示词上方显示已暂存的截图，并在 PR 打开时附上这些截图。在 claude.ai 和 Cowork 中，可从 Claude 目录添加 uploads。相同的文件夹 （plugins/claude/uploads）是通用的 Agent 插件布局，并以 uploads 的名称提交至 xAI 插件市场。

包括标注、托管评论、公开图库和变更源（涵盖整个仓库或单个拉取请求）在内的完整 CLI 用法，参见 docs/cli.md。

uploads feed create 会打印仓库截图的实时页面：

_{uploads feed create --repo buildinternet/uploads。}

REST 路由见 docs/api.md。

此仓库包含什么

路径	内容
apps/	可部署组件：REST API worker（api.uploads.sh）、可选的公共查看器、认证 worker、远程 MCP 服务、Slack 应用（链接预览和暂存上传消息），以及 uploads.sh 上的 Astro 网站
packages/	共享代码——最值得注意的是 @buildinternet/uploads（CLI，发布于 npm）、@uploads/storage（所有存储操作都经过的 files-sdk 适配器工厂）和 @uploads/plugin（Claude/Codex 插件版本，不对外发布）
skills/	提供给用户的三项 Agent 技能
hooks/、plugins/、.mcp.json	Agent 运行时配置：共享的 PR 提交前截图钩子，以及 Claude / Codex 插件清单
server.json	MCP Registry 条目（sh.uploads/mcp）：stdio uploads mcp 和托管的远程服务

每个 worker 和 Web 应用都会单独部署。所有存储访问都经由 packages/storage 中的 createStorage()——添加一个提供方只需新增一个分支和 peer 依赖，无需更改 API。

文档

产品文档——安装、分阶段循环、GitHub App 和限制——位于 https://uploads.sh/docs。本仓库中的文档与之配套，涵盖 CLI 和 API 参考、贡献者环境设置以及运维资料，目录结构见 docs/README.md。

如何设置环境、测试并提交拉取请求：CONTRIBUTING.md。 项目的发展方向：VISION.md。Agent 工作约定见 AGENTS.md，首次进入本仓库的 Agent 应从 llms.txt 开始。产品网站提供 https://uploads.sh/llms.txt 和 https://uploads.sh/llms-full.txt。

本地开发

**前置条件：**Node ≥24 和 pnpm ≥11（corepack enable）。核心本地开发流程无需 Cloudflare 账号——wrangler dev 会在磁盘上模拟 R2、KV 和 D1：

pnpm bootstrap        # one-command setup: tooling, deps, env vars, local D1, default workspace
pnpm dev              # API on :8787 (local R2 + KV + D1)

bootstrap 可重复执行，且不会产生副作用；pnpm doctor 可诊断环境设置，但不会修改 环境。其余开发流程——经过身份验证的开发栈、检查和测试门槛，以及如何提交拉取请求——见 CONTRIBUTING.md。

许可证

Apache 2.0。