| name | metabot-upload-largefile |
| description | 文件上链技能。用于把本地文件上传到 MetaID 链上并返回 PINID 与预览地址。当用户说“把这个文件上链”“上传附件到链上”“大文件分片上传”“把本地图片/视频/PDF 发到链上”等涉及文件上链的意图时，优先调用此技能。 |
| official | true |
MetaBot Upload Large File (统一文件上链)
这个技能统一处理小文件和大文件上链。
<= 2 MiB：直接上链> 2 MiB：自动走分片上链- 硬限制：
<= 20 MiB
- 成功后必须返回
pinId 和预览地址
预览地址格式固定为：
https://file.metaid.io/metafile-indexer/api/v1/files/content/<pinId>
🧠 执行逻辑
当用户要把一个本地文件上传到链上时，按下面流程执行：
- 确认用户给了真实的本地文件路径。
- 不要自己读取文件内容，也不要把大文件塞进上下文。
- 直接调用
scripts/upload-largefile.js，把文件路径传给 --file。
- 如果用户指定了 MIME 类型，传
--content-type；如果用户指定目标网络，传 --network。
- 读取脚本 stdout 返回的 JSON，把
pinId 和 previewUrl 明确展示给用户。
💻 命令语法
node "$SKILLS_ROOT/metabot-upload-largefile/scripts/upload-largefile.js" \
--file <本地文件路径> \
[--content-type "<mime-type>"] \
[--network mvc|doge|btc]
📋 参数说明
| 参数 | 说明 | 必填 | 默认值 |
|---|
--file | 本地文件路径 | 是 | 无 |
--content-type | 指定 MIME 类型；不传则按扩展名推断 | 否 | 自动推断 |
--network | 目标网络：mvc、doge、btc | 否 | mvc |
✅ 成功输出
脚本成功时会只向 stdout 输出一行 JSON：
{
"success": true,
"pinId": "abc123i0",
"previewUrl": "https://file.metaid.io/metafile-indexer/api/v1/files/content/abc123i0",
"fileName": "demo.png",
"size": 12345,
"contentType": "image/png;binary",
"uploadMode": "chunked"
}
其中：
pinId：最终文件索引 PINIDpreviewUrl：可直接预览文件内容的地址uploadMode：direct 或 chunked
⚠️ 严格约束
- 不要用
cat、Read 工具或其它方式主动读取用户的大文件内容。只传文件路径给脚本。
- 文件超过
20 MiB 必须直接报错，不要尝试上传。
- 文件大于
2 MiB 时必须走分片上传，不能继续走 direct upload。
- 当前 IDBots 内置实现里，大文件分片上传只支持
mvc。如果用户指定 doge 或 btc 且文件大于 2 MiB，要明确报错，不要假装支持。
- 如果用户没有提供真实文件路径，必须先追问路径，不能捏造。
- 始终使用
$SKILLS_ROOT/metabot-upload-largefile/scripts/upload-largefile.js，不要调用 .ts。
✅ 示例
1. 上传一个 PNG：
node "$SKILLS_ROOT/metabot-upload-largefile/scripts/upload-largefile.js" \
--file /path/to/logo.png
2. 上传一个 PDF：
node "$SKILLS_ROOT/metabot-upload-largefile/scripts/upload-largefile.js" \
--file /path/to/report.pdf \
--content-type application/pdf
3. 上传一个大于 2 MiB 的视频到 MVC：
node "$SKILLS_ROOT/metabot-upload-largefile/scripts/upload-largefile.js" \
--file /path/to/demo.mp4 \
--network mvc
