workrally-ref-image-cos-upload
把本机文件变成 WorkRally 生成工具可用的公网参考图 URL。
When to use
触发条件(满足其一即用):
- 调用
mcp__workrally*__upload_file返回❌ 文件不存在: /...(哪怕文件确实存在、ls能看到、md5 能算) - 需要用本机已有图片做
canvas_generate_image的input_images(角色基准图、风格参考、构图参考) - 需要用本机已有图片做
canvas_generate_video/ 图生视频的首帧 - 已知 WorkRally 的 MCP server 与本地文件系统隔离,无法读取本地路径
不适用:文件已经在公网 URL 上(直接用该 URL 即可,无需本技能)。
根因(先确认,别瞎试)
upload_file 失败不是路径写错,而是 MCP server 与本机沙箱隔离:
- 中文路径 → 文件不存在
- 纯 ASCII 路径(
/Users/.../ref_tmp/a.jpg)→ 文件不存在 /tmp、/private/tmp→ 文件不存在
所以不要反复换本地路径重试,直接走下面的 COS 直传。
Steps
1. 取 COS 临时凭证
调 MCP 工具 get_upload_token,参数:
file_ext: "jpg" # 或 png / mp4 / mp3
upload_type: 200 # 200=普通(公网可读,图片用);210=私有读(音视频用)
返回:tmp_secret_id / tmp_secret_key / tmp_token / bucket / region / key / cdn_path。
每个文件单独取一次(每次调用返回一个专属 key)。
2. 本地 COS 签名直传
用 scripts/cos_put.py(本技能自带,已封装签名 + curl PUT):
python3 scripts/cos_put.py \
--secret-id "<tmp_secret_id>" \
--secret-key "<tmp_secret_key>" \
--token "<tmp_token>" \
--bucket "<bucket>" \
--region "<region>" \
--key "<key>" \
--file "/绝对路径/本地图.jpg" \
--content-type "image/jpeg"
成功输出 HTTP 200。
3. 拼出公网 URL
https://<cdn 域名>/<key>
cdn_path 返回形如 //zenvideo-pro.gtimg.com,取域名部分拼 https:// + 域名 + / + key。
务必校验(图片是公网可读,视频/音频必须用带签名的 url):
curl -s -o /dev/null -w "%{http_code} %{content_type} %{size_download}\n" "<URL>"
# 期望:200 image/jpeg <本地字节数>
4. 作为参考图传入
canvas_generate_image(或 video 工具):
input_images: ["<URL1>", "<URL2>"]
prompt: "...角色外形严格参照第一张图片..."
prompt 用「第一张图片」「第二张图片」引用,与 input_images 数组下标一一对应。
参考图数量上限看 canvas_image_model_list 返回的 kontext_config.max_input_images。
参考图选择纪律(实测:哪个锚会泄漏什么)
传上去只是第一步;选错锚会稳定污染输出。以下 5 条为 2026-09-19 在真实项目(《呼噜噜的夏日》补齐 11 项角色 + 5 项场景)上逐张目检得出的结论:
| 现象 | 结论 |
|---|---|
| 把含人物的场景图当结构参考 | 原图人物会被抄进画面(实测:中景凭空出现 8–10 个红色小人剪影)→ 场景结构参考只能传干净无人的图 |
| 同时传两张参考图 | 第一张主导。第一张的色调会压过第二张的风格锚(实测:想用 B 定调色,结果整幅被 A 的冷绿带跑) |
| 把持道具的角色当三视图结构锚 | 道具会抄给其他角色(实测:用持竹杖的猫师傅当锚,熊爸与猫妈都长出了竹杖) |
| 把同科属角色当锚 | 物种会被抄(实测:换成狐狸当锚后,三花猫被画成狐狸脸) |
| 换锚之后 | 泄漏类型会变(道具泄漏 → 物种泄漏),每次换锚都必须重新目检,不能假设「换了就好了」 |
选锚优先级:① 干净、无道具、物种差异大的同体系三视图 > ② 只有设计没有版式的半身/立绘(必须配一张①当版式锚) > ③ 纯文字。
沿用旧参考的正面经验:用户给出的原角色三视图(如「呼噜噜」)本身无道具、版式标准,是最安全的结构锚,优先复用。
风格锚要单独挑干净的:风格统一时不要拿「有建筑/有人/有动物的场景图」当风格锚——结构会一起抄。优先用空镜场景或裁切出的纯风格区块。
Pitfalls
- 签名串漏段:COS 的
StringToSign必须是三段"sha1\n" + KeyTime + "\n" + sha1(HttpString) + "\n"只传HttpString会稳定报SignatureDoesNotMatch(服务端回包里会带StringToSign/FormatString,可对照排查)。 - Python urllib 直传会 write timeout:沙箱下用 urllib 发 PUT 常超时;改用 curl
--data-binary @文件即可通。 - 别用
requests/urllib:走subprocess调 curl 最稳。 - 凭证时效:STS 临时凭证有效期短(约 1 小时级),取到后尽快传完;
get_upload_token返回的key已带日期目录与 uuid,不要自己拼。 - 音视频是私有读:
upload_file返回的url(带签名)才能访问,original_url不行。图片是公网读,无此限制。 - 不要拿风格/氛围图当 input_images:会污染画面(把参考图里的人、道具一起抄进去)。参考图只传结构/身份参考;风格走文字描述。
- 组合图(多视图并置的资产图)不能直接当 input_images:道具/角色资产常做成「一张图里并排多个视图」(如同时有封面+内页、全杖+杖头特写)。直接整张传入,模型会把多个视图一起画进同一画面(同框出现两份物料)。传入前先按视图裁成单件。
- 含大量汉字的资产图慎传:视频模型复现汉字会写成乱码或伪字形。关键文字(书名/表格/题词)走后期叠印(Pillow 渲染+overlay),生成时不要求模型写字。
- 否定式约束不可靠:写「画面里不要出现 X」常被忽略;改肯定式描述(「这是已清场的空镜,台面上除了雨水什么都没有」)更有效。
- 一张图只有一个主导者:传两张参考图时第一张主导,其色调与内容会压过第二张——把「要什么」放第一张,「风格/结构」放第二张。
Verification
curl -o /dev/null -w "%{http_code}"返回 200,且%{size_download}与本地文件字节数一致。%{content_type}是image/jpeg/image/png等预期类型。- 把 URL 填进
input_images后,生成结果确实复现了参考图中的目标特征(造型/配色/结构),且背景没有被参考图污染。