skill-image-qwen 技能
用千问 Qwen-Image-3.0 生成或编辑图片。模型同时支持文生图（T2I）和图生图/图像编辑（I2I），可根据文本提示词直接生成，也可基于 1-3 张参考图结合编辑指令精确编辑。核心追求从「好看」转向「好用」--生成的图要能成为可直接交付的成品。核心原则：靠提示词把模型能力发挥到最大；把「需求澄清」「提示词审核优化」与「生成前确认」放在最重要位置。
V3 核心升级：三段式令牌链条（代码兜底，唯一 100% 有效）
V2 是两阶段（prepare/generate），理论上模型可不经审核优化直接 prepare。V3 新增「提示词优化审核环节」作为代码级门禁，形成三段式令牌链条：
- 阶段一
optimize：模型按官方范本（6 步范式）完成审核与优化，提交登记--强制含「优化前后对比 + 改动说明」（防敷衍作业）。代码生成令牌A（绑定优化后提示词内容指纹sha256），落盘记录。绝不调用真实 API。 - 阶段二
prepare：代码检查令牌A（无令牌A -> 拒绝，提示「必须先完成审核优化环节」）；通过后向用户原样呈现「原始需求 -> 优化后提示词 -> 改动说明」供确认；生成令牌B，销毁令牌A（用完即焚）。绝不调用真实 API。 - 阶段三
generate：代码检查令牌B（无令牌B / 不匹配 / 内容被篡改 -> 拒绝）；通过后执行 API 调用，成功后销毁令牌B（用完即焚）。
令牌接力：optimize ->(令牌A)-> prepare ->(令牌B)-> generate，少一张门票门就不开；模型想从原始需求直接跳到生成，会在 prepare 或 generate 被拦下。
令牌是流程副产品，非写死密码：由代码动态生成内容指纹（
sha256(提示词)），模型读源码也无法伪造，只有老老实实走完该环节才有资格拿到钥匙。令牌与内容绑定：每次需求不同令牌不同，提交内容与登记/确认版本不一致即拒绝，防「展示一套、生成另一套」。
令牌范围：指纹只覆盖提示词内容，尺寸/格式等技术参数从登记记录回取不纳入指纹--门禁锁的核心事实是「用户确认了内容」，技术参数灵活处理，避免改个尺寸就重走全流程。
用完即焚：prepare 消费令牌A即销毁，generate 成功即销毁令牌B，防拿旧令牌跳步重复执行。
拒绝信息反向教学：报错文案即流程指南，被拦下后能自我纠正走回正确流程。
防敷衍机制：optimize 登记强制含「优化前后对比 + 改动说明」，prepare 原样呈现给用户确认；想走过场就得现场编造改动理由，敷衍成本上升；用户确认时能看到优化依据，可发现方向跑偏（如「写实风」被改成「卡通风」）。一份输出同时扮演「防敷衍作业」和「用户确认依据」两个角色，不增加额外环节。
模型与版本
| 版本 | 模型 ID | 定位 | 生成单价 |
|---|---|---|---|
| 标准版（默认） | qwen-image-3.0 | 质量-速度平衡，日常创作顺手省心 | 1K/2K 均 0.18 元/张 |
| Pro 版（可选） | qwen-image-3.0-pro | 密集排版、极致细节、知识厚实 | 1K 0.25 元/张，2K 0.50 元/张 |
模型核心能力（官方「三实」）：
| 能力 | 说明 | 关键指标 |
|---|---|---|
| 内容丰实 | 装得下一整页：试卷、报纸、图鉴、信息图一次生成 | 指令长度提升至 4.5K token |
| 细节真实 | 经得起放大：纹理质感逼近真实材质 | 10px 小字清晰可辨，毛孔发丝纤毫毕现 |
| 知识厚实 | 什么都懂：跨语言、跨领域 | 覆盖 12 国语言、100+ 艺术风格与多种 UI 界面 |
- 默认使用标准版。仅当用户明确需要 Pro 版能力（图中图密集排版、微表情/毛孔/发丝真实细节）或主动要求 Pro 时才切换。
- 输入价格两版一致（0.02 元/张）。详见
references/pricing_and_models.md。 - 模型能力边界与选型建议见
references/pricing_and_models.md。
工作流（必须遵守）
①意图识别与澄清 -> ②选版本 -> ③构建提示词并 optimize 审核优化 -> ④回显确认 -> ⑤prepare 确认 -> ⑥generate 生成与迭代 -> ⑦反馈消耗。
第一步：意图识别与需求澄清（重中之重，不得跳过）
作为 AI 图片生成专家，判断用户需求是否足够明确和详细。用户初始需求通常模糊，这一步是出图质量的关键，必须与用户反复确认。
- 解析意图：结合用户的文字问题 + 输入附件（参考图/草图/截图），初步判断：
- 任务类型：凭空创作（T2I）？基于已有图编辑（I2I）？
- 是否涉及特定真人/品牌/物件须保真？
- 参考图数量与每张角色（编辑目标 / 风格参考 / 主体来源）。
- 多维度细化（模糊时逐项确认，可用
request_user_input批量提问或自然追问；已详细时轻量确认即可）：- 主体内容 2. 风格 3. 构图视角 4. 氛围光影 5. 尺寸比例 6. 数量 7. 用途 8. 参考图 9. 保真度要求
- 涉及真人：追问并记录每人辨识特征（发型/发色/眼镜/肤色/脸型/服装/体型/年龄），作为提示词锚点。
- 汇总成「图片规格」回显用户确认。
效率原则：请求已明确时只做轻量确认（复述 + 问"对吗，还要调整吗"），不机械走全量清单；只在模糊或高风险维度（保真度、参考图角色）深挖。
第二步：选择版本
根据第一步明确后的需求，按选型建议选版本（详见 references/pricing_and_models.md）：
| 场景 | 推荐版本 |
|---|---|
| 日常海报、插画、社交媒体配图、UI 原型、批量生成 | 标准版（默认） |
| 高分辨率 2K 输出且不要求极致细节 | 标准版（2K 同价更省） |
| 电商商品图合成家装场景（I2I 多图） | 标准版即可；追求极致材质可选 Pro |
| 报纸版面、试卷、分镜、菜单、信息图表（密集排版） | Pro 版 |
| 人像摄影、产品特写（微表情/毛孔/发丝真实细节） | Pro 版 |
| 知识图鉴、历史教学信息图（多模块+跨语言） | Pro 版 |
- 默认标准版；需 Pro 时明确告知用户成本差异（2K 下 Pro 贵 178%）。
- 若用户未指定版本，默认标准版并在生成方案中说明。
第三步：构建提示词并调用 optimize（审核优化登记，绝不调 API）
根据第一步意图与规格，结合最佳实践与案例库审核优化提示词并选定模式，然后调用 optimize（而非直接生成）。optimize 是把模型能力发挥到最大的核心环节：原始需求通常简短模糊，须按官方 6 步范式扩写为画面感充足的提示词，并登记「优化前后对比 + 改动说明」。
3.1 查最佳实践与案例库
先看 references/best_practices.md 和 references/case_library.md 有无同类场景的官方案例，学习其提示词结构模式与关键技巧，识别易踩的坑并提前规避。
场景到案例速查：
| 用户场景 | 参考案例 | 提示词重心 |
|---|---|---|
| 考试卷/文档/报告排版 | 案例 1（语文试卷） | 逐区域扫描式描写+文字逐字写入 |
| 微距摄影/产品特写 | 案例 2（刺绣微距） | 材质纤维+操作瞬间+浅景深 |
| 手写笔记/数学公式 | 案例 3（数学笔记） | 三色批注+公式逐字+几何图 |
| 电商商品图合成场景 | 案例 4（商品图合成 I2I） | 编辑规则（提取/忽略/保留/生成） |
| 角色设定/多视角一致性 | 案例 5（角色设定稿） | 单人极详细描写+多视角分区 |
| 手绘地图/信息图 | 案例 6（美食地图） | 逐区描写+编号点位+图例系统 |
| 菜单/价目表 | 案例 7（潮汕菜单） | 栏目分区+菜品列表+照片嵌入 |
| 知识图鉴/科普海报 | 案例 8（襦裙图鉴） | 模块化描写+主视觉人物+辅助模块 |
| 矢量运动/导览信息图 | 案例 9（徒步导览图） | 英文矢量风格+配色体系+路线途经点 |
| 历史教学/跨语言信息图 | 案例 10（安史之乱） | 双语模式+超宽横版+负面约束 |
| 商业人像摄影 | 案例 11（意式街头人像） | 多层背景叙事+人物极详细+胶片感 |
| 光影人像摄影 | 案例 12（草帽光影人像） | 光影成因与落点+摄影参数+负面约束 |
完整 12 个官方案例的提示词结构解析与关键技巧见
references/case_library.md；完整原文提示词见Qwen-Image-3.0官方最佳实践案例与完整提示词手册.md。
3.2 选方式（按目标）
| 目标 | 方式 | 调用 |
|---|---|---|
| 凭空创作，无参考图 | 文生图 T2I | 仅提示词，不传 --image |
| 保留/扩展已有图的人物或内容 | 图生图 I2I | 提示词 + 1~3 --image |
3.3 写提示词（官方 6 步范式）
按官方从 12 个案例归纳的提示词结构骨架组织内容（详见 references/best_practices.md 第三章）：
- 开篇定调：一句话说明画面类型、画幅方向、整体风格与氛围。例：「这是一张竖版……海报，整体背景为……」
- 空间动线：严格按空间顺序（从上到下、从左到右、从主体到背景）逐区域描述，写明各元素的相对位置关系。
- 文字逐字写入：所有需要渲染的文字（标题/正文/标注/价格/页脚）用引号逐字写进提示词，指定字体/字号/颜色/位置。
- 细节五要素：色彩给具体色名、材质给质感词、光影给方向与软硬、字体给风格、构图给层次。
- 收尾约束：以「避免……」列出负面约束（乱码/错位/畸变/过曝/水印等），也可用
--negative-prompt参数。 - 画幅与摄影参数：写实/人像类可附画幅比例、镜头焦段、光圈等参数（如「竖版 3:4，85mm，f/2」）。
官方 3 条使用技巧：
- 指令可以「长」：4.5K token 留给复杂版面，把每个区域、每段文字、每个相对位置都描述清楚。
- 小字要「点名」：精确文字直接写进指令，用引号标出并指定字体/字号/颜色/位置。
- 风格要「说全」：摄影风写光线镜头氛围（焦段/光圈/曝光/胶片颗粒），插画风写材质配色笔触。
编辑/参考类（I2I）特殊要点：写清「保留 X，只改 Y」，迭代时重申不变量防漂移。多图合成重心在编辑规则（提取什么/忽略什么/保留什么/生成什么），用「必须」「不得」等强约束词确保完整使用参考图。
3.4 调用 optimize（登记对比+改动说明，返回令牌A，绝不调 API）
提示词审核优化完成后，调用 optimize 阶段（而非直接生成）。optimize 会校验防敷衍（原始/优化/改动说明齐备且改动说明有实质内容）、校验参数、计算优化后提示词指纹、落地审核记录并返回令牌A，绝不调用真实 API、不耗费用：
optimize 文生图：python scripts/generate_image.py optimize --original-prompt "原始需求" --optimized-prompt "优化后提示词" --change-explanation "改动说明" --size 1024*1024
optimize 图生图：python scripts/generate_image.py optimize --original-prompt "原始需求" --optimized-prompt "优化后提示词" --change-explanation "改动说明" --image ref.png --model qwen-image-3.0-pro
optimize 多图： python scripts/generate_image.py optimize --original-prompt "..." --optimized-prompt "..." --change-explanation "..." --n 4
optimize 必需参数：--original-prompt（原始需求）、--optimized-prompt（优化后提示词）、--change-explanation（改动说明：优化了什么、为什么--防敷衍作业，也是用户确认依据）。常用参数：--model（默认 qwen-image-3.0）、--image（1-3 张参考图）、--size 宽*高、--n（1-6）、--negative-prompt、--seed、--watermark、--no-prompt-extend、--prompt-extend-mode direct|agent、-o 输出路径。所有参数在 optimize 时锁定进记录，后续阶段不可篡改（仅 generate 的 -o 可覆盖输出路径）。
提示词类参数支持
@文件语法：值以@开头时从其后路径读取文件内容（应对超长提示词，规避命令行长度限制），如--optimized-prompt @optimized.txt。
optimize 输出：原始需求、优化后提示词、改动说明、生成方案（模式/模型/尺寸/数量/改写模式/预估费用）、审核令牌(Token A)。把这些完整带入第四步。
第四步：回显确认（强制等待用户确认）
把 optimize 返回的**「原始需求 -> 优化后提示词 -> 改动说明」+ 生成方案 + 令牌A完整回显给用户，并等待用户明确确认**：
- 用户确认 -> 进入第五步，用令牌A 调用
prepare。 - 用户要求修改 -> 回第三步重新审核优化后重新
optimize（产生新令牌A，旧令牌自然失效/过期清理），再次回显确认。 - ⚠️ 不得在用户确认前调用
prepare/generate。代码兜底虽不验证"用户是否真的看过"，但 prepare 必须依赖有效的 optimize 令牌A；规范的回显确认是质量与成本的关键闸门。用户确认时可对照改动说明发现优化方向是否跑偏（如「写实风」被改成「卡通风」）。
第五步：prepare 确认（消费令牌A、返回令牌B、不调 API）
用户确认后，用令牌A + 与 optimize 登记完全一致的优化后提示词调用 prepare：
prepare：python scripts/generate_image.py prepare --token <令牌A> --optimized-prompt "<optimize 登记的优化后提示词>"
- 脚本过三道检查（审核记录存在 / 令牌A 匹配 / 优化后提示词与登记版本一致）通过后，原样呈现「原始需求 -> 优化后提示词（确认版本） -> 改动说明」+ 生成方案，返回确认令牌(Token B)，并销毁令牌A（用完即焚）。
- 技术参数（图片/尺寸/数量等）从 optimize 记录回取并锁定，不可在 prepare 阶段篡改。
- 无令牌A 或内容不一致 -> 拒绝（报错文案即流程指南）。
第六步：generate 生成与单点迭代
用令牌B + 与 prepare 确认版本完全一致的提示词调用 generate：
generate：python scripts/generate_image.py generate --token <令牌B> --prompt "<确认版提示词>" [-o 输出路径]
- 脚本过三道检查（确认记录存在 / 令牌B 匹配 / 提示词与确认版本一致）后才调 API；其余参数从记录回取并锁定，不可在 generate 阶段篡改。
- 成功后自动输出实际尺寸、用量、费用，并销毁令牌B（一次性，不可复用）。
- 用绝对路径展示图片。
- 迭代：每次只改一处 -> 重新
optimize（新令牌A）-> 回显确认 ->prepare（新令牌B）->generate。效果不理想优先调"风格氛围/构图"，或回第三步换策略。
第七步：反馈消耗情况
生成后脚本自动输出本次用量与费用（版本、输入/输出档位、图片数、单价、合计）。在回复中向用户汇总：
- 使用的版本与方式（T2I/I2I）、模型 ID。
- 输出尺寸、生成数量、计费档位（1K/2K）。
- 输入费用、输出费用、合计费用（元）。
- 请求 ID（便于溯源）。
费用计算规则与示例见 references/pricing_and_models.md。
令牌与记录机制（三段式链条，代码兜底细节）
- 令牌格式：
sha256(提示词)-nonce8（指纹绑定提示词内容，nonce 保证同提示词多次登记不互相覆盖）。令牌A、令牌B 同内容同指纹但 nonce 不同，是两个不同令牌。 - 令牌接力：optimize 产出令牌A -> prepare 消费令牌A 产出令牌B（销毁A）-> generate 消费令牌B（成功后销毁B）。少一环即被拒。
- 记录存储：系统临时目录下两个目录--
skill_image_qwen_optimize/<tokenA>.json（令牌A，含 original_prompt/optimized_prompt/change_explanation/params）、skill_image_qwen_pending/<tokenB>.json（令牌B，含确认版本与回取参数）。optimize只存图片路径/URL，不读图片内容，记录保持轻量。 - 令牌范围：指纹只覆盖提示词内容（
sha256(提示词)），尺寸/格式等技术参数从记录回取不纳入指纹--改尺寸不必重走全流程（除非尺寸/水印本身是用户须确认的合规要素）。 - 防敷衍：optimize 登记强制含「优化前后对比 + 改动说明」，改动说明须达最低字数；prepare 原样呈现给用户确认。
- 生命周期：prepare 成功后立即销毁令牌A；generate 成功后立即销毁令牌B（一次性，防复用）；API 调用失败则保留令牌B允许同令牌重试（无需重新确认）；记录超过 2 小时自动失效并清理。
- 参数锁定：图片/尺寸/数量/改写模式等在
optimize时锁定进记录，后续阶段从记录回取使用，不可篡改；generate仅可用-o覆盖输出路径。 - 图片文件须在 generate 时仍存在：
optimize只校验存在并记路径，generate时才读盘转 data URI。
提示词构建规范
- 6 步范式：开篇定调 -> 空间动线 -> 文字逐字写入 -> 细节五要素 -> 收尾约束 -> 画幅与摄影参数（详见
references/best_practices.md）。 - Qwen 特性：偏好详细、有画面感的长描述（上限 4.5K token）；
prompt_extend默认开启可增强简短提示词。 - 图中文字：引号标出内容，指定字体/字号/颜色/位置，要求逐字渲染。
- 编辑/参考：写清「保留 X，只改 Y」，迭代时重申不变量防漂移。
- 尺寸：用
宽*高（星号分隔，如1920*1080）；不指定则模型自动推荐。 - 完整最佳实践与常见问题库见
references/best_practices.md；12 个官方案例结构解析见references/case_library.md；API 参数见references/api_reference.md。
参考文件索引
| 文件 | 内容 |
|---|---|
references/best_practices.md | 三实能力概览、3 条官方技巧、6 步提示词范式、常见问题对策、尺寸档位、迭代建议 |
references/case_library.md | 12 个官方案例的分类索引、提示词结构解析、关键技巧、场景到模式速查 |
references/api_reference.md | API 端点、请求体结构、参数说明、响应体、usage 字段、错误码 |
references/pricing_and_models.md | 模型对比、价格表、费用计算、选型建议 |
Qwen-Image-3.0官方最佳实践案例与完整提示词手册.md | 官方原文：12 个案例的完整提示词、使用技巧、API 价格 |
scripts/generate_image.py | 三阶段生成脚本（optimize/prepare/generate，T2I/I2I，纯标准库，三段式令牌链条强制审核优化+确认，防敷衍，自动计费） |
重要约束
- 密钥安全：只从环境变量
DASHSCOPE_API_KEY读取，绝不写入技能文件，绝不在聊天中向用户索要明文密钥。若未设置，给出设置指引并等待。 - 三阶段不可绕过：无
optimize令牌A 则prepare被拒；无prepare令牌B 则generate被拒；optimize/prepare不调 API、不耗费用。模型无法从原始需求直接跳到生成。 - 防敷衍强制：
optimize必须登记「优化前后对比 + 改动说明」，改动说明须有实质内容；prepare原样呈现给用户确认。 - 回显确认强制：
optimize后必须将「原始需求 -> 优化后提示词 -> 改动说明」+ 方案回显用户确认，确认前不得prepare/generate。 - 先澄清后生成：未完成第一步（意图识别与澄清）不得调用脚本。
- 输出位置：默认存到当前工作目录的
output/下；若图片用于当前项目，生成后移入项目合适位置。 - 不覆盖：除非用户明确要求替换，否则用带版本号的文件名。
- 图片时效：API 返回的图片 URL 有效期 24 小时，脚本已自动下载到本地。
环境准备
- 必须设置环境变量
DASHSCOPE_API_KEY（阿里云百炼 API Key）。 - PowerShell 临时设置（按提示输入，密钥不进入命令历史）：
$env:DASHSCOPE_API_KEY = Read-Host -Prompt 'DASHSCOPE_API_KEY' - 持久设置：通过系统环境变量界面写入
DASHSCOPE_API_KEY，或使用setx后重开终端。不要把真实值写入仓库文件。 - 可选
DASHSCOPE_BASE_URL：覆盖默认端点https://dashscope.aliyuncs.com（如用业务空间专属域名）。 - API Key 获取：https://help.aliyun.com/zh/model-studio/get-api-key