付費生成前的可恢復流程
Rachel Digital Human Production 將數位人口播製作拆成可檢查的工作階段。它不提供第三方帳號、額度或 API 存取權；使用者必須準備自己的 MiniMax、HeyGen 帳號與合法授權素材。
技能以 MiniMax 複製聲音並產生旁白，再把已上傳的音訊資產交給 HeyGen 驅動影像。若目標聲音來自 MiniMax，流程不會自行改用 HeyGen 的 script + voice_id 路徑。
work/job-state.json 保存 voice_id、asset_id、video_id、階段狀態與輸出路徑。來源檔案未變更時，後續工作可重用既有識別碼，避免重複建立付費工作。
素材檢查
MiniMax 旁白
15 秒預覽
使用者核准
完整影片
下載質檢
狀態封存
“Always preserve the production gate.”
技能目錄與明確呼叫
先取得完整專案資料夾，再從其上一層目錄執行 README 提供的複製指令。重新開啟 Codex 工作後，以技能名稱明確呼叫；專案將隱含觸發設為停用，避免付費流程被意外啟動。
cp -R rachel-digital-human-production ~/.codex/skills/預覽任務呼叫
在新的 Codex 工作中貼上 README 的明確呼叫文字。這個請求只建立 15 秒預覽，不會授權完整影片。
Use $rachel-digital-human-production to make a
15-second digital-human preview first.素材、預覽與完整影片
技能把每次外部工作拆成可觀察的輸入、識別碼、狀態與輸出。付費呼叫前先完成本機檢查；收到失敗或逾時狀態時，沿用既有 video_id 恢復，而不是直接建立新工作。
Ingest · 01
inputs/script.md
腳本輸入
檢查長句、品牌名稱、數字與縮寫；把需測試的發音列入預覽審查。
Ingest · 02
inputs/portrait.jpg
肖像輸入
接受 PNG 或 JPEG；畫面需提供清楚正臉、可見嘴部與頭肩構圖。
Ingest · 03
inputs/voice-source.mp3
聲音輸入
接受 MP3、M4A 或 WAV；MiniMax 官方限制為 10 秒至 5 分鐘且不超過 20 MB。
Preflight · 04
preflight_assets.py
素材預檢
檢查檔案存在、類型、大小與可取得的媒體長度；發現問題時回傳非零狀態。
Preflight · 05
authorization
權利確認
在複製聲音或生成影像前，確認聲音、肖像、腳本與最終用途均已獲授權。
State · 06
init_job_state.py
狀態初始化
建立工作骨架；檔案已存在時預設拒絕覆寫，除非明確加入 --force。
MiniMax · 07
source_file_id
聲音上傳
將來源聲音送至 MiniMax 檔案上傳流程，並把回傳識別碼寫入工作狀態。
MiniMax · 08
voice_id
聲音複製
建立或重用穩定的說話者識別碼；來源檔未變更時避免再次複製。
MiniMax · 09
voiceover-full.mp3
完整旁白
以複製聲音產生全長音訊，並保存至 work/voiceover-full.mp3。
MiniMax · 10
preview-15s.mp3
預覽音訊
從完整旁白建立前 15 秒片段，供低成本影像預覽與口型檢查。
HeyGen · 11
image_asset_id
肖像資產
沒有相符資產時上傳肖像；一般 HeyGen 資產上傳依官方文件上限為 32 MB。
HeyGen · 12
preview_audio_asset_id
預覽音訊資產
上傳 MiniMax 產生的預覽音訊；後續影像工作沿用音訊資產識別碼。
HeyGen · 13
preview_video_id
預覽工作
提交 15 秒 Image-to-Video 工作；專案建議先以 720p 測試。
HeyGen · 14
poll status
狀態輪詢
依 video_id 輪詢至完成或失敗；逾時只代表尚未取得終態。
QA · 15
preview-15s.mp4
預覽下載
下載至 outputs/preview-15s.mp4，完成 MP4 解碼檢查後才標記預覽完成。
Gate · 16
approved_by_user
人工核准
檢查聲音相似度、中文口型、五官形變、動作與構圖；未明確核准時停止。
Final · 17
full_audio_asset_id
完整音訊資產
核准後才上傳或重用全長旁白資產，保持 MiniMax 聲音路徑不變。
Final · 18
full_video_id
完整影片工作
提交完整 HeyGen 工作；技能預設以 1080p 作為最終產出目標。
QA · 19
final-1080p.mp4
全片解碼檢查
檢查完整 MP4，不只檢查檔案大小或開頭片段；失敗時先重試下載。
Batch · 20
one state per video
批次隔離
每支影片建立獨立狀態記錄，避免腳本、資產與工作識別碼相互覆蓋。
Batch · 21
outputs/previews/
批次預覽
批次模式預設只產生預覽，並將檔案集中至預覽輸出目錄。
Recovery · 22
resume by video_id
工作恢復
輪詢逾時時沿用既有影片識別碼；不要把逾時判定為生成失敗。
Recovery · 23
refresh signed URL
下載恢復
簽名網址過期時重新取得工作狀態或資產中繼資料，不建立新的付費工作。
任務與停止條件
| 任務 | 預期產物 | 停止條件 |
|---|---|---|
| 素材預檢 | preflight_assets.py JSON 報告 | ok: false 時修正素材 |
| 單支預覽 | outputs/preview-15s.mp4 | 等待使用者明確核准 |
| 完整影片 | outputs/final-1080p.mp4 | 全片解碼檢查通過 |
| 批次製作 | outputs/previews/ 與 review sheet | 指定預覽未核准前不建立完整影片 |
付費工作與個資邊界
以下規則均來自專案的 SKILL.md、references/ 與官方 API 文件。它們用來控制付費呼叫、素材權利、恢復策略與公開分享範圍。
預覽先於完整影片
即使需求直接指定完整影片，仍先建立 15 秒預覽。只有使用者明確豁免或核准預覽後，才可進入完整生成。
來源 · 專案 SKILL.md
外部階段前後寫入狀態
每次外部工作開始與結束時更新 work/job-state.json。狀態檔保存識別碼與進度，不保存完整金鑰或簽名網址。
來源 · 專案 SKILL.md · checklists.md
來源未變時重用識別碼
相對應來源檔未變更時，沿用既有 voice_id、asset_id 與 video_id。先恢復既有工作，再考慮新增付費工作。
來源 · 專案 SKILL.md
MiniMax 旁白路徑固定
MiniMax 音訊已存在時，將上傳後的音訊資產交給 HeyGen。除非使用者指定 HeyGen 聲音，否則不要改用 script + voice_id。
來源 · 專案 SKILL.md · api-facts.md
供應商參數即時重查
精確 request 欄位、價格、模型供應狀態與帳號額度可能變動。編寫生產程式或執行大批次前，重新查閱 MiniMax 與 HeyGen 官方文件。
來源 · api-facts.md · 官方 API 文件
逾時與失敗分流
API 回傳明確 failed 時記錄原因並在付費重試前詢問。輪詢逾時時保留既有 video_id，繼續查詢工作狀態。
來源 · 專案 SKILL.md · Failure Policy
下載問題先重試下載
MP4 損毀或下載中斷時，先重試或恢復下載。簽名網址過期時重新取得狀態或資產資料，不要直接重新生成影片。
來源 · 專案 SKILL.md · Failure Policy
公開套件排除私密素材
公開分享只包含技能文件、agent 設定、參考資料與腳本。排除真實聲音、私密肖像、客戶影片、狀態檔、金鑰與本機私有路徑。
來源 · public-safety.md
批次模式只建立預覽
多腳本任務預設只產生預覽，並建立包含路徑、長度、影片識別碼與審查註記的 review sheet。
來源 · 專案 SKILL.md · Batch Mode
公開使用採明確呼叫
allow_implicit_invocation 設為 false。使用 $rachel-digital-human-production 明確啟動，以降低付費工作被意外觸發的風險。
來源 · agents/openai.yaml · README
從素材預檢到人工核准
以下示例使用專案文件提供的路徑與呼叫格式。任務先完成本機預檢，再取得付費外部工作的明確授權；預覽下載並通過解碼檢查後，流程停在人工核准。
$ You ›
Use $rachel-digital-human-production to make only a 15-second preview.
Script: inputs/script.md
Portrait: inputs/portrait.jpg
Voice sample: inputs/voice-source.mp3
claude: Codex ›
先執行本機素材預檢。此步驟不呼叫外部 API。
> scripts/preflight_assets.py \
> --script inputs/script.md \
> --portrait inputs/portrait.jpg \
> --voice inputs/voice-source.mp3
ok: { "ok": true, "issues": [] }
> scripts/init_job_state.py --project digital-human-demo \
> --out work/job-state.json
ok: work/job-state.json
claude: Codex ›
hl: MiniMax 複製聲音與 HeyGen 預覽屬於付費外部工作。
請確認現在執行預覽生成。
$ You › 核准建立 15 秒預覽；不要建立完整影片。
ok: outputs/preview-15s.mp4 · MP4 decode check passed
ok: work/job-state.json · preview = completed · final = not_started
claude: Codex ›
請檢查聲音相似度、中文口型、五官形變、動作與構圖。
hl: 流程已停止；收到明確核准前不建立完整影片。
“Do not generate the full video until the user clearly approves the preview.”
可觀察的交付狀態
預覽階段完成時，應同時存在 outputs/preview-15s.mp4 與更新後的 work/job-state.json。狀態中的 approved_by_user 仍為 false，final 仍為 not_started。
使用者核准後，後續任務從狀態檔繼續，重用既有聲音與影像資產。完整輸出需完成全片解碼檢查，才可把最終狀態標記為完成。
授權、帳務與恢復邊界
從單支預覽到批次審批
先以一組獲授權素材完成預覽流程，再擴展到批次工作。每支影片使用獨立狀態記錄，並維持「預覽、人工核准、完整生成」的順序。
進階操作地圖
**1. 驗證本機輔助腳本。**先執行 init_job_state.py 與 preflight_assets.py，確認狀態初始化與素材錯誤輸出符合專案需求。
**2. 重查供應商文件。**在實作 API client 前，核對 MiniMax voice clone、T2A 與 HeyGen asset、Image-to-Video 的現行 request 欄位。
**3. 完成單支預覽。**保存每一階段識別碼與輸出，下載預覽後執行 MP4 解碼檢查，並記錄人工審查結果。
**4. 建立批次 review sheet。**列出預覽路徑、長度、video_id 與審查註記；只對指定且核准的預覽建立完整影片。
**5. 檢查公開套件內容。**發布時只保留 SKILL.md、agents/openai.yaml、references/ 與 scripts/；移除所有真實客戶素材與秘密。
延伸閱讀
① SKILL.md：完整操作邊界、階段流程、批次模式與失敗政策。 ② references/api-facts.md：專案依賴的 MiniMax 與 HeyGen API 事實基線。 ③ references/public-safety.md：同意、揭露、公開分享與敏感素材排除規則。
“This skill is intended for legitimate, authorized digital-human production.”