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 批量提問或自然追問；已詳細時輕量確認即可）：
1. 主體內容 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

skill-image-qwen 技能