工序交付｜R2 · 流水線 · 鎖臉 · 雜項

【工序｜R2、HTML Gallery、Playwright】

適用工具：Cloudflare R2、HTML Gallery、doubao-html、Playwright

適用場景：成品上傳、手機可預覽交付頁、自動化批次管理

【有效技巧】

1. ★ 手機直開發布平台＝Cloudflare Pages（rh-*.pages.dev）：所有要「手機點開就看」的成品一律用 wrangler pages deploy 發布到 Pages 專案（部署單一目錄，index.html＋各頁用相對連結）。帳號已登入 Es8931407@yahoo.com.tw（npx wrangler whoami 確認，token 存 AppData\Roaming\xdg.config\.wrangler\config\default.toml，有 pages write 權限）。禁止用 workers.dev 的 /api/file?key= 給手機直開——該網域在部分手機/ISP 網路會白屏空白（實測 2026-10-18），且給 R2/Worker 直連 URL 會當下載檔。
2. 交付一律 Gallery HTML（doubao-html 發布連結）＋R2 CDN 內嵌 <video src>，手機直開；不要給 R2 檔案直連 URL。
3. Gallery 產生流程：每張圖 FileBatchUpload（可一次 30 張）→ 記下回傳 https://aka.doubaocdn.com/s/xxx 短碼 → 寫響應式 HTML（grid＋編號）把短碼放進 JS 陣列 → HTML 上傳取連結 → present_files 交付。
4. 大量批次（>100 張）先全部生成完再一起做完整 gallery；中途要先行看就做「生成中版」標註目前張數。
5. html skill 的 _shots/ 輸出目錄嚴禁刪除（會觸發權限確認、打斷交付）。
6. Gallery 更新發布：lark-cli apps +deploy --file-path ./gallery_x.html --app-id <id> → +release-get 到 finished。

【踩坑／避開的錯誤】

1. 交付作品不能給 R2 檔案直連 URL（/api/file?key=...）→ 使用者端顯示空白（被當下載檔）→ 一律 Gallery HTML＋R2 CDN。
2. 發布成功後禁止再訪問連結檢查（會打斷交付流程）。
3. /api/upload 不接受 data URI 前綴（要純 base64）；generate-video-tool 的 image/video 傳 data URL 可以。
4. R2 直連 /api/file 對瀏覽器與無 UA 皆 200 video/mp4；但 Worker 其他 API 需瀏覽器 UA（無則 403 code 1010）。

2026-10-18 交接卡補錄｜交接卡_備份_20261018.md（1210-1460 行）

#### 【有效技巧】

• 交付平台選用原則：手機點開即看的影片 gallery 一律走 Cloudflare Pages（rh-*.pages.dev）；豆包 doubaoapps 在此用戶手機網路全白（curl/bu 正常＝域被擋），僅作備援。
• CF Pages 部署：目錄＝index.html＋videos/＋thumbs/ 整目錄原樣上傳（mp4 由 CDN 串流）；wrangler pages deploy . --project-name <p> --branch main --commit-dirty=true；首次需 pages project create。
• Gallery 手機優先：每支 video 加 poster（ffmpeg -ss 0.3 抽封面）＋preload="none"——17 支同時 preload=metadata 會把手機拖到全白。
• Worker serveFile 必須支援 HTTP Range/206：R2 env.MEDIA.get(key,{range:{offset,length}}) 回 206＋content-range；mp4 moov 在尾部，不支援 Range＝瀏覽器 video 播不出（前幾支沒影片的根因）。
• lark-cli（doubaoapps）用法：cd 到 html 目錄→apps +deploy --file-path ./x.html→+release-get 輪詢 finished→取 online_url；複發布必帶 --app-id 復用。

#### 【踩坑／避開的錯誤】

• serveFile 第一參數是 URL 物件非 Request，無 .headers；讀 Range 要另傳 request（url.headers.get 會 TypeError→全 500）。
• wrangler 對「同名但內容改變」的檔案會誤判 already uploaded 不重傳→改新檔名＋index.html 引用同步更新強制當新檔上傳。
• 部署後等 ~20s CDN 生效；主域名可能暫存舊版，用 hash URL 或 ?v=<ts> 驗證/交付。
• 前端改 JS 必 node --check（V0 3 塊、V1 2 塊 script）；JS 字串內嵌 HTML 屬性含單引號（onclick="fn('login')"）會中斷外層字串→整個 script 區塊崩潰→三條線選單全無反應；一律 backtick 模板字串。
• Edit replace_all 陷阱：短字串（如 applyEngineUI();）在頁內出現多次，replace_all 會把大段 JS 塞進行內 if 造成語法損壞；先 Grep 確認次數與上下文。
• 純 Python mp4 parser 交付前必測：實測時長/解析度/Range 播放，不能只看「下載成功」。

【工序｜批量流水線、Worker、中央佇列】

適用：多 Worker 任務調度、無人值守批次生成

【有效技巧】

1. 所有影片生成提交至中央外部排程佇列；中央排程器僅在 Comfy 空閒時取下一筆送入。
2. 長任務交本機腳本＋Windows 開機自啟／計畫任務無人值守，避免 Agent 反覆輪詢耗平台額度。
3. 本機 watcher 輪詢＋Windows toast 通知（每 30 秒檢查，下完彈通知），不燒平台額度；長任務監控都這樣做。
4. 斷點續傳下載：curl.exe -L -C - --retry 10 --retry-delay 5 --retry-all-errors -o <檔> <URL>。
5. 大檔下載首選 HuggingFace 直連（GitHub 多數大檔被擋）；台灣直連 HF 速度浮動（0.5–4 MB/s），必要時換 hf-mirror.com 或 aria2 多線程。

【踩坑／避開的錯誤】

1. curl 下載會無聲死掉（跑到 1.39GB 進程直接沒、沒報錯）→ 必須用上面斷點續傳 curl，不能用裸 curl。
2. 平台 cron 最小間隔 3600 秒（1 小時）：做不到每 7 分鐘；長任務輪詢交本機 PowerShell 腳本。
3. 平台 at 任務不能帶 deadline；正在執行定時任務時不能同時 create 新任務。
4. PowerShell 5.1 背景跑 python 用管道會被截斷（BrokenPipe 殺進程），輸出要 *> log 2>&1 重導向。
5. 高峰時段（7:30-10:00、15:30-17:00、19:30-20:00）定時任務會延遲觸發，勿排敏感任務。

2026-10-18 交接卡補錄｜長任務監控、平台 cron 限制

#### 【有效技巧】

• 本機 watcher 輪詢＋Windows toast 通知（每 30 秒檢查檔案大小，下完彈通知），不燒平台額度；長任務監控都這樣做（D:\短劇流水線\tools\watch_fasth3_download.ps1）。

#### 【踩坑／避開的錯誤】

• 平台 cron 最小間隔 3600 秒（1 小時），做不到每 7 分鐘；長任務輪詢交本機 PowerShell 腳本。
• 平台 at 任務不能帶 deadline；正在執行定時任務時不能同時 create 新任務。
• PowerShell 5.1 背景跑 python 用管道會被 BrokenPipe 截斷殺進程 → 輸出一律 *> log 2>&1 重導向。

2026-10-18 交接卡補錄｜交接卡_HANDOFF_備份_20261018.md

#### 【有效技巧】

• 長任務無人值守＝本機腳本＋Windows 開機自啟/排程；開機自啟 HKCU Run\OHIYOYO_MimicWorker，但建議 python.exe＋Start-Process＋RedirectStandardOutput（pythonw 啟動可能不存活、log 只有一行）。
• 監督機制現況：watchdog.py 只監督 course_h3_batch（v6），不涵蓋 mimic_worker／8189——別假設它會自動拉起動作模仿產線；目前 cron 定時任務 0 個（舊 AI MV 監控 task id 已不存在），需監控就建本機 watchdog。

#### 【踩坑／避開的錯誤】

• 含中文路徑的排程啟動檔用 .bat（UTF-8 無 BOM）會被 cmd 以 ANSI(cp950) 讀成亂碼→cd 失敗 python 沒啟動；一律 .ps1（UTF-8 BOM）或 8.3 短名。
• Start-Process -ArgumentList 含空格路徑會被拆成兩參數（can't open file）；路徑參數內嵌雙引號；傳中文路徑給 python 會 Big5 亂碼→wrapper 腳本內寫死 UTF-8 路徑或參考圖放 ASCII 路徑。
• cap_tmp 會被 worker 清空，長任務參考圖勿放 cap_tmp，下載後立即複製到固定位置。

【通用｜參考圖、鎖臉、LoRA 素材】

適用：全部人像影片模型

【有效技巧】

1. 角色鎖臉用 FLUX.2＋ReferenceLatent 鎖錨點臉：LoadImage→scale 1MP(lanczos)→VAEEncode→ReferenceLatent 注入正負提示，可鏈式多張。
2. 鎖臉精修可用 InstantID→Flux（兩段式：先鎖臉後精修）。
3. 人群處理：淺景深＋多樣化，背景人群虛化（cream bokeh）、不同年齡/性別/朝向/遮擋；負向排除克隆臉、冷凍假人。
4. 角色 LoRA（如 xiaoqing/xiaocha/tingting）：多版本時用最終版，step-0xxxx 中間版留 D 不進產線。
5. 人像風格：清純自然；避免「cinematic 濃豔／glossy 紅唇／高對比」提示（會帶成 AI 網紅臉）。

【踩坑／避開的錯誤】

1. seed 一經收斂勿隨意更換：換 seed 重生成表演略優但色彩大幅偏離，需整組（seed+色彩）重新收斂，成本 2–3 輪。
2. 角色跨鏡頭長得不一樣 → 生成時務必用角色卡錨點；換裝／受傷等造型變化先更新角色卡再生成。
3. 素材命名與內容需核對（曾誤用別鏡素材）。
4. FLUX.1「低解析度生成再放大」必現皮膚橫紋；硬拉會重複主體 → 統一用 FLUX.2。

2026-10-18 交接卡補錄｜START_HERE_備份_20261018.md（十三、仿即夢鎖臉產線 / 換臉技術）

#### 【有效技巧】

• 本機鎖臉「三路線＋InstantID」按需求選：要最像且大量換裝走①貼臉（Qwen-Edit 25 步＋inswapper，sim 0.87–0.89 現役最強）；貼臉後要洗貼圖感走②局部重繪（face bbox mask denoise 0.35，sim 同）；要即夢式無貼片縫才走③PhotoMaker V2，但參考圖必須是高清正臉大頭照。
• 新角色 5 步 SOP：摳圖（多人圖先裁角色區域）→ insightface 找最大臉緊裁（外擴 0.25）存 <角色>_face.jpg→拷進 ComfyUI input\（英文檔名）→改腳本 REF_IMG/ANCHOR/OUTFITS→exp_sim.py 驗證（sim≥0.85 超像、0.7–0.85 可接受、<0.7 換路線）。
• inswapper 換臉單張參考會不像本人（0.72–0.74）；解法＝從目標角色圖庫挑 12 張最大臉 embedding 取平均當參考，sim 拉到 0.90/0.82。
• PuLID Flux img2img 保留場景穿搭：底圖 VAEEncode 當 init latent、denoise 0.65、PuLID weight 0.75＋LoRA 0.85，比 inswapper 更自然。
• InstantID＝IdentityNet＋FaceID 雙路鎖身份，四角色實測 sim 0.88–0.92（SDXL only）；v2 量產用 Arienmix 底模＋BASE_FACE 完整模板＋cfg 4.0。
• InstantID→Flux 精修兩段式可追平 LoRA+Flux：Step1 InstantID 出圖→Step2 Flux Dev+PuLID（無 LoRA）img2img denoise 0.35（是「又像又有 Flux 質感」平衡點，d0.45 起 sim 掉）。
• 角色錨點圖挑選：insightface 從 1000 張圖庫掃最大臉緊裁；anchor 用最大臉 face 物件，只改 anchor.embedding（normed_embedding 是唯讀不可設）。

#### 【踩坑／避開的錯誤】

• Qwen-Edit 換衣必須用 EmptyLatent＋TextEncodeQwenImageEditPlus(image1 槽)；傳統 VAEEncode img2img（denoise 0.65/0.8）衣服卡死換不了。
• qwen_image_edit_2511_fp8 本機出純雜訊（需 nightly ComfyUI，不升級）；4 步 Lightning 鎖臉保真差，25 步才是鎖臉最佳。
• SetLatentNoiseMask 的 mask 要接 LoadImage 的 MASK 輸出 ["12",1]，接錯全 400。
• PhotoMakerEncodePlus 漏接 insightface_opt ["3",0] → 報「InsightFace is required」；photomaker-v2.bin 要從 TencentARC/PhotoMaker-V2 倉庫抓（V1 倉庫 404）。
• 中文路徑 cv2/Comfy 不吃 → 參考圖與中間檔一律英文檔名、放 input 目錄；中文角色名 prefix 曾導致 SaveImage 異常＋被判 execution_cached 不存圖。
• 摳圖：短邊>4320 先縮（否則 human 上限/Gateway Timeout）；多人圖 human 會保留全部人物，需先裁出目標角色再摳。
• 無 LoRA 的 FLUX 文生圖＝臉隨機、保證不了同一角色；img2img denoise ≤0.55 只能微調不能換場景 → 鎖角色唯一可靠路＝標準訓練集（多角度白底大頭+正/側/背全身）＋LoRA。

【雜項｜下載、版本、工具除錯】

適用：版本管理、下載、檔案處理

【有效技巧】

1. 版本命名 軟體_特色_4位全局連續流水號，流水號唯一來源 VERSIONS.md；成片與工作流共用同號同名。
2. 成片已生成但存檔中斷 → 用 save_wf_archive.py 補存，勿重跑融合（否則流水號跳號）。
3. 免登入扒 RunningHub 工作流 JSON：貼文頁面免登入就能下載 JSON，不用開號。
4. BFL 官方 FLUX.2 repo gated（匿名 401）→ 用 unsloth 非 gated GGUF。

【踩坑／避開的錯誤】

1. PowerShell 行覆蓋改腳本易括號數錯/丟 append/尾行缺閉 → 改完必 py_compile；Replace 尾括號數不符靜默不生效。
2. & $py -c "多行" 的 -c 被當 lex token → 用 .py 檔；ffmpeg 單幀輸出需 -update 1（否則 image2 warning 但 exit 1）。
3. mk/腳本替換字串一律用 raw 字串：\workspace 的 \v 被 Python 解析成垂直製表符 → replace 靜默失效；改完必回查。
4. 成品量測用 -ss 放 -i 後（output seek）：input seek 對 setpts 後成品取到 keyframe 假幀。

2026-10-18 交接卡補錄｜curl、RunningHub、LoRA 訓練

#### 【有效技巧】

• 斷點續傳 curl：curl.exe -L -C - --retry 10 --retry-delay 5 --retry-all-errors -o <檔> <URL>；台灣直連 HF 速度浮動 0.5–4MB/s，必要換 hf-mirror.com 或 aria2。
• 免登入扒 RunningHub 工作流 JSON：貼文頁面（如 runninghub.ai/zh-tw/post/2100850479709675521）免登入可下載 JSON，不用開號。
• PuLID 鎖臉必須與 LoRA 疊用：純 PuLID（一張參考圖）sim 僅 0.17–0.29，PuLID w1.0＋角色 LoRA 0.9 才到 0.7+。

#### 【踩坑／避開的錯誤】

• curl 裸下載會無聲死掉（跑到 1.39GB 進程直接沒、沒報錯）→ 必須用上面斷點續傳。
• 小晴 v2b–v2j 共 8 次全彩噪點根因＝當前 sd-scripts＋--cache_text_encoder_outputs 使 T5 embeddings 快取錯誤 → 換 AI Toolkit／新版 kohya，勿再用當前 sd-scripts 配 cache 訓練。
• LoRA 訓練勿加 --fp8_base_unet（5090＋PyTorch 2.12 meta tensor 錯誤）；勿用 kontext fp8 版主模型（loss 爆炸 1e+26），必須 flux1-dev-bf16。
• RunningHub H3 Lightning 多卡加速工程（8×RTX 6000D）對單卡 5090 無用，別浪費時間研究。

2026-10-18 交接卡補錄｜交接卡_備份_20261018.md

#### 【有效技巧】

• R2 批量上傳走 wrangler r2 object put --remote 直傳（不經 Worker /api/upload，後者大批量 503 限流）；PowerShell 中文 key 會被 ConvertTo-Json 變問號→改用 Python requests UTF-8。
• 本機備份機制：worker 完成時同時存 bridge\result\<user_id>（<email>）\cap_<task>.<ext>；sync_backup.py 掃本機比對 KV 補上傳。

#### 【踩坑／避開的錯誤】

• 舊任務 dataURL 一次性遷移：暫存路徑需 ASCII（中文路徑 cmd 吃字）；works API 內跑遷移會 CPU 超時（1102）→改本機一次性腳本。

2026-10-18 交接卡補錄｜START_HERE／VERSIONS_備份（ffmpeg 組裝鐵律）

#### 【有效技巧】

• zoompan（Ken Burns 推/拉）必須加 -loop 1 且 d=總幀數；表達式變數是 on（frame number）不是 n。
• Ken Burns 無抖動公式：scale=1920:1080:force_original_aspect_ratio=increase,crop=1920:1080,zoompan=...:d=125:s=1920x1080:fps=25，交替 zoom in/out，不要加手持抖動。
• concat 清單路徑用正斜線；ffmpeg 單幀輸出需 -update 1。

#### 【踩坑／避開的錯誤】

• zoompan 不加 -loop 1 或誤用 n 變數 → 推動作異常/靜幀。

2026-10-18 交接卡補錄｜百度網盤清理_交接卡_備份_20261018.md

#### 【有效技巧】

• 百度網盤客戶端盤點大型 AI 安裝包 SOP：頂部搜尋 .7z→Enter→切「文件」標籤→切「其他·N」分類→點「大小」標題排序從最大往下看，30 秒看清全貌（FaceFusion 21GB→sd-webui 6GB→数字人 5GB→ComfyUI 3GB）。
• 批量勾選刪除：先滾到第一個勾 checkbox→續滾續勾→頂部工具列垃圾桶一次刪；勿逐個右鍵刪（慢且易誤觸）。
• 百度網盤刪除預設進回收站、30 天內可救回，誤刪風險低；但要立即釋放容量須手動清空回收站。
• 大動作刪除先列清單（容量/名稱/位置/建議）給使用者拍板；使用者常一句話定奪（如「留第四個其他全刪」），自己對照表格解讀，勿反覆追問。
• 換臉工具識別關鍵字：FaceFusion、roop、deepfacelab、CodeFormer、Wav2Lip（唇形同步配套）；原則＝這些全版本保留，不管新舊、不管硬體版本。
• cu 座標分工：列表 checkbox 整齊對齊可用座標點；彈窗對話框按鈕一律鍵盤 Tab 切焦點＋Enter。

#### 【踩坑／避開的錯誤】

• 百度網盤客戶端首啟必彈「開啟兼容模式更穩定」Dialog：cu.click() 座標對 Dialog 按鈕偏移嚴重、一直點不到取消/刪除→勿跟滑鼠座標搏鬥，直接 Tab 切焦點＋Enter；兼容模式開了無妨（只影響 UI 渲染，不動本機 GPU）。
• 搜尋框輸入關鍵字後不會自動搜，下拉選單只是建議，務必再按一次 Enter 才執行。
• 手機 App 掃碼登入成功後客戶端常縮到系統列、視窗看似消失→從工作列叫出，別誤判登入失敗。
• 搜尋預設「綜合」混大量無關圖片/文件/影片→要切「文件」標籤→「其他·N」分類→按大小排序才看得到大型 7z 安裝包。
• 客戶端視窗常被 opencaw-gateway 終端機視窗遮住→Alt+Tab 切換或從工作列叫出；使用者有時直接關掉整個視窗，要重新 Start-Process 捷徑開啟。