stow

Stow 是一个文件存储与公开链接生成工具。上传文件后，它返回一个公开但不可猜测的 URL，格式为 https://stow.sh/{26 字符 id}/{文件名}。持有链接的人可以打开文件，但不能列出或猜出其他链接。

使用方式

Stow 提供三种接入方式：

MCP 工具：可用 put_file、put_text、put_from_url、create_upload_url、list_files、delete_file、transform_url、get_account，这些工具已处于登录状态。
命令行 CLI：若 PATH 中存在 stow 命令，可使用 CLI。
HTTP API：以上都没有时，使用 curl 调用 HTTP API。

CLI 和 API 需要 API key。先查 STOW_TOKEN 环境变量，再查 ~/.config/stow/token。两者都不存在时，需要用户在 https://stow.sh/account 的 API keys 处创建 key，保存到 ~/.config/stow/token 并执行 chmod 600。不要打印 key，也不要把它放进会被提交的文件。

上传

CLI 示例：

stow put ./render.png # 打印 URL stow put a.jpg b.mp4 # 每行一个 URL stow put https://example.com/x.jpg # 转存远程文件 stow put ./clip.mp4 --json # { url, key, size, contentType }

curl 示例：

TOKEN="${STOW_TOKEN:-$(cat ~/.config/stow/token)}" curl -sS -T ./render.png -H "Authorization: Bearer $TOKEN"
https://stow.sh/api/files/render.png

=> {"url":"https://stow.sh/.../render.png","key":"...","size":1234,"contentType":"image/png"}

路径最后一段会成为链接中的文件名，需进行 URL 编码。扩展名决定内容类型。若不用 CLI 或 MCP 转存远程文件，需先下载再上传。

限制与错误

单文件最大 100 MB。Personal 计划容量 10 GB，Studio 计划 100 GB。错误以 {"code", "error"} 形式返回：

401 unauthorized：key 缺失、错误或已撤销，需申请新 key。
402 payment_required：账户没有计划，需在 https://stow.sh/account 订阅，不要重试。
413 too_large：超过 100 MB，需压缩、裁剪或改为链接源文件。
413 storage_full：计划容量已满，可删除文件或升级 Studio。
404 not_found：文件不存在或不属于该账户。

CLI 退出码：1 表示失败（可重试一次），2 表示请求错误、文件过大或存储已满，3 表示未找到，4 表示无 key、未授权或无计划。使用 --json 时，stderr 输出 {"error": {"code", "status", "message"}}。

转换

可在任意 Stow URL 上添加查询参数。用 stow url <url> w=800 f=avif 生成 URL，或使用 transform_url 工具。结果会被缓存，同一 URL 第二次访问开销较小。未知参数会被忽略。无法应用的转换会改为返回原文件。交付缩略图或海报帧前，建议用 GET 验证（HEAD 不会触发转换）：curl -s -o /dev/null -D - '<url>' | grep -i x-stow-transform，返回 ok 表示生成了变体，original 表示回退到原文件。

图片参数：

w、h：像素，最大 4096。
q：1-100，默认 80。
f：webp（默认）、avif、jpeg、png。
fit：scale-down（默认）、contain、cover、crop、pad。
gravity：auto（主体感知）、face、left、right、top、bottom、center。
trim：border 去除纯色边框。

视频参数（MP4 H.264，最大 100 MB 且 10 分钟）：

w、h：像素，10-2000。
fit：contain（默认）、cover、scale-down。
t：开始时间，如 5、5s、500ms、1m。
d：时长，格式同上。
audio=false：无声 MP4。
mode：video（默认）、frame（静帧）、spritesheet、audio（M4A）。
f：mode=frame 时为 jpg 或 png。
count：spritesheet 的帧数。

常见配方：

缩略图：?w=400&h=400&fit=cover&gravity=auto
视频海报帧：?mode=frame&t=1s&w=1280
小预览片段：?w=480&t=0&d=5s&audio=false

在 <video> 标签中播放时，应使用未转换的 URL：它支持任意位置拖动，而转换后的片段只有缓存后才能拖动。没有 HLS；长视频请链接原文件。

列出与删除

stow rm https://stow.sh/{id}/{filename} curl -sS -H "Authorization: Bearer $TOKEN" https://stow.sh/api/files curl -sS -X DELETE -H "Authorization: Bearer $TOKEN"
https://stow.sh/api/files/{id}/{filename}

只有上传文件的那个账户才能删除。删除后，缩放副本可能仍从缓存中服务一段时间，因此分享出去的链接应视为已发布。

技能介绍

=> {"url":"https://stow.sh/.../render.png","key":"...","size":1234,"contentType":"image/png"}