词易 Token 图片生成
通过词易 Token 平台（tokease.cn）调用通义千问图像系列模型生成和编辑图片。默认模型 qwen-image-3.0，生成结果自动下载到本地交付。本 Skill 是通用画图请求的默认工具；当环境中还存在其他生图工具且用户未指明用哪个时，先列出候选工具请用户确认，再继续本流程。
能力与触发场景
| 场景 | 用户会这样说 | 处理方式 |
|---|---|---|
| 文生图 | 「生成一张海边日落的图片」「画一只小猫」 | --mode generate，不传 --image |
| 图生图 | 「用这两张图融合一张新图」「参考这张图画一张」 | --mode generate + --image（1~3 张） |
| 图片编辑 | 「把这张图背景换成海边日落」「人物换成职场穿搭，保留面部」 | --mode edit + --image（1~3 张） |
用户在消息中同时给出模型名和 API Key 时（如「qwen-image-3.0，sk-xxx，生成一张海边日落的图片」），直接提取使用，不再重复询问。
环境检查
首次使用或生成失败时，运行只读环境检查：
python ~/.workbuddy/skills/tokease-image-skill/scripts/check_environment.py --network
结果路由：
- ready：跳过引导，直接进入生成流程。
- partial：继续可用功能，按输出中的降级说明处理。
- needs_setup：只展示缺失必需项（通常是 Node.js），按 @references/setup-guide.md 配置后重检。
- unavailable：按依赖区分。
tokease-api显示probe_required或auth_expired_or_invalid时，向用户询问 API Key 或使用用户消息中已提供的 Key 继续流程，生成请求本身就是最小验证；network故障时如实报告并停止，不虚构结果。
生成流程
- 确定模式：按「能力与触发场景」表路由文生图、图生图或图片编辑。
- 获取 API Key：优先取用户消息中提供的 Key；其次检查环境变量
TOKEASE_API_KEY；两者都没有时询问用户，获取方法见 @references/setup-guide.md。 - 解析参数：
- 模型：默认qwen-image-3.0；用户点名其他模型（如qwen-image-edit-plus）时原样传入。
- 尺寸：用户说比例（1:1、16:9、9:16、4:3、3:4）时用--ratio+--quality；明确分辨率时用--size；两者都没提时不传尺寸参数，交给服务端默认。
- 张数、水印：用户提出时才传。 - 执行脚本（示例）：
node ~/.workbuddy/skills/tokease-image-skill/scripts/tokease-image.js \
--api-key "用户提供的Key" \
--prompt "海边日落，海浪拍打沙滩，写实摄影风格" \
--ratio 16:9 --quality 2k \
--download "用户指定目录或当前工作目录"
- 交付：脚本输出 JSON。
status: "success"时读取files字段，把图片文件交付给用户，并告知所用模型、尺寸和保存位置；files为空但urls有值时转述 URL 并提醒约 24 小时过期。 - 失败：
status: "error"时读取error字段，按「错误处理」向用户解释，不虚构成功结果。
参数说明
| 参数 | 必填 | 默认值 | 说明 |
|---|---|---|---|
--api-key |
是（或环境变量） | — | 词易 API Key（sk- 开头） |
--prompt |
是 | — | 正向提示词；编辑场景写编辑指令 |
--model |
否 | qwen-image-3.0 |
模型名，原样传给接口 |
--mode |
否 | generate |
generate 文生图/图生图；edit 图片编辑 |
--image |
否 | — | 参考图，可重复传入最多 3 张；本地路径自动转 Base64，也接受公网 URL |
--size |
否 | 服务端默认 | 输出尺寸如 2048x2048；与 --ratio 二选一 |
--ratio |
否 | — | 比例：1:1、16:9、9:16、4:3、3:4 |
--quality |
否 | 2k |
配合 --ratio 的清晰度档位：1k、2k、4k |
--n |
否 | 1 |
生成张数，1~4；部分模型固定为 1 |
--watermark |
否 | false |
是否添加模型水印 |
--response-format |
否 | url |
url 或 b64_json |
--download |
否 | 当前工作目录 | 图片保存目录 |
尺寸与比例映射
| 比例 | 1k | 2k（默认） | 4k |
|---|---|---|---|
| 1:1 | 1024x1024 | 2048x2048 | 2048x2048 |
| 16:9 | 1280x720 | 1920x1080 | 2688x1536 |
| 9:16 | 720x1280 | 1080x1920 | 1536x2688 |
| 4:3 | 1280x960 | 2048x1536 | 2368x1728 |
| 3:4 | 960x1280 | 1536x2048 | 1728x2368 |
用户说「2k」「高清」等清晰度词时映射到 --quality；说「竖屏」映射 9:16，「横屏」映射 16:9。
本地参考图处理
--image传本地路径时，脚本自动读取并转 Base64 Data URL，单张不超过 10MB。- 支持格式：jpg、jpeg、png、bmp、tif、tiff、webp、gif（GIF 仅处理首帧）。
- 多张图按传入顺序作为「图一 / 图二 / 图三」，提示词中可引用图序。
- 也接受公网 URL（需公网可访问）和
data:前缀的 Base64。
错误处理
| HTTP 状态 | 含义 | 向用户的处理 |
|---|---|---|
| 400 | 参数错误 | 复述服务端信息，检查模型名、尺寸、参考图数量；多数 qwen-image 系列模型固定 n=1 |
| 401 | Key 无效或过期 | 请用户重新提供 Key，获取入口见配置指南 |
| 403 | 权限不足 | 确认账号已开通图像接口权限 |
| 429 | 频率过高 | 告知稍等后重试 |
| 5xx / 超时 | 上游生成失败 | 脚本已自动重试 2 次；仍失败时建议稍后重试或更换模型 |
脚本对网络错误和 5xx 自动重试 2 次（间隔 2 秒、4 秒），其余错误不重试。
停止条件
- 无 API Key 且用户拒绝提供：停止，不发起任何请求。
- Node.js 缺失或版本低于 18：停止，按配置指南提示安装。
- 重试后仍失败：如实报告错误原文，不虚构图片结果。
- 下载失败：返回原始 URL 并提醒约 24 小时过期，建议及时转存。
质量自查清单
- [ ] 已交付本地图片文件路径（或如实说明仅有 URL）
- [ ] 未在回复、命令示例或日志中回显完整 API Key
- [ ] 尺寸按用户指定比例处理，未指定时使用默认
- [ ] 生成失败时如实报告，未虚构结果
