插圖步驟影片（指南版面）

說明文件的 1 個步驟 = 1 個場景。配合旁白的語句，拿起工具、倒入、打開、輕觸、組裝。繪圖、音訊與輸出完全以 Swift（CoreGraphics・AVFoundation）進行，CLI jgv 統一負責腳本、音訊、字幕、靜態圖片與影片的輸出。

<skill> 是此 SKILL.md 所在的目錄（${CLAUDE_SKILL_DIR}。若無法使用，當透過 plugin 安裝時為 ${CLAUDE_PLUGIN_ROOT}/.claude/skills/j-guide-video，否則為 ~/.claude/skills/j-guide-video 或 .claude/skills/j-guide-video 中存在的目錄）
以下所稱的 jgv 都是指 <skill>/bin/jgv。初次使用或更新 skill 後，會自行編譯自身與 kit（繪圖 DSL 與組件），需要數十秒到數分鐘。編譯快取會放在 ~/Library/Caches/j-guide-video/，而影片專案中只會包含素材相關的檔案（腳本、binding、cue、SVG 素材）（詳細機制請參閱 reference/environment.md）。若使用者要求清除快取，請先用 jgv clean --stale --dry-run 顯示要清除的項目，再執行 jgv clean --stale；若要全部清除，則使用預設位置 rm -rf ~/Library/Caches/j-guide-video（刪除後下次編譯會重新建立）。若已設定 J_GUIDE_VIDEO_CACHE 變更儲存位置，則不要刪除該資料夾本身，僅刪除其中的 build-*、shared-*、projects 和 avtts 目錄（因為該資料夾可能並非專用）
引數與選項可透過 jgv help <子指令> 查看。未知的選項會導致錯誤
<library> 是使用者的函式庫（環境變數 J_GUIDE_VIDEO_LIBRARY，未設定則為 ~/.config/j-guide-video。若有 XDG_CONFIG_HOME 則在其下）。其中包含先前影片建立的工具、動作（parts/）以及偏好設定（defaults.json），即使更新 skill 也不會被刪除（請參閱 reference/library.md）

procedure.md ─(jgv new = init・md2script --stubs・tts・timing)→ script.json・cue 與 binding 的雛形・音訊・timeline・字幕・時間表
visuals/bind.swift (工具・畫面的繪製方式與名稱) + cues/<步驟>.cue (每句的動作) ─(jgv check → jgv dev → jgv render → jgv overview)→ out/video.mp4

開始前確認事項

運作環境

僅支援 macOS（最新版 Xcode 可運行的版本；已在 Apple Silicon 上驗證，Intel Mac 未確認）上的 Claude Code。若為 Linux、Windows（含 WSL2）、Claude Code on the web 或 Claude.ai，請告知無法使用並終止
需要最新版的 Xcode 或 Command Line Tools（swift。可執行 xcode-select --install。舊版本未經驗證）。jgv 會在缺少或版本過舊時停止，請告知使用者安裝方式（需要 sudo 的指令請勿自行執行）。僅在初次編譯 jgv 時需要網路連線
旁白預設使用 macOS 語音（"voice": "auto" 會自動選取腳本語言中品質最高的語音。可使用 jgv voices 查看清單）
可商用 TTS 包括內建的雲端 TTS 以及可透過任意指令連接的 command。雲端 TTS 只需將金鑰設定為環境變數即可使用：google（GOOGLE_TTS_API_KEY；若使用服務帳戶金鑰則為 GOOGLE_APPLICATION_CREDENTIALS）、azure（AZURE_SPEECH_KEY・AZURE_SPEECH_REGION）、amazon（AWS_ACCESS_KEY_ID・AWS_SECRET_ACCESS_KEY・AWS_REGION）、openai（OPENAI_API_KEY。模型預計於 2027-01-06 停止服務，不建議用於長期使用的影片）
金鑰與腳本由使用者自行準備。Claude 不會輸入或顯示 API 金鑰，也不會開啟服務帳戶金鑰檔案（GOOGLE_APPLICATION_CREDENTIALS），更不會擅自呼叫付費 API
處理非使用者原創的影片專案（例如 zip 檔、他人存放庫、傳遞給 --base 的他人腳本）時，在執行 jgv 之前，必須向使用者展示並確認 script.json 與 script.<語言>.json（傳遞給 jgv tts 等的所有腳本）中的 tts（engine 是否為付費雲端 TTS，或 command 中寫了什麼），以及 visuals/、parts/、kit/ 中的 Swift 檔案是否存在。jgv tts / timing / dev / check / snapshots / still / preview / catalog / render / build-langs（所有會產生音訊或編譯視覺並繪製的指令）會直接執行這些指令與程式碼
付費雲端 TTS 在每個專案與引擎中，必須先透過 jgv tts --allow-cloud 明確允許後才會被呼叫（jgv tts 會先顯示行數與字數並停止）。加上 --allow-cloud 前，必須告知使用者該引擎會產生費用並取得許可（使用 jgv new --tts … 建立，或函式庫 defaults.json 中的引擎所產生的腳本會自動被允許。當透過 jgv new --base 繼承他人腳本中的雲端引擎時，jgv new 會在建立任何內容前停止，並要求使用 --tts 選擇引擎）
語音、速度、各 TTS 的設定、磁碟與快取機制請參閱 reference/environment.md

產生影片的使用條件

macOS 語音（預設的 apple）：根據 Apple 的 macOS 使用許諾（「語音」條款），系統語音僅能用於製作個人、非商業用途的原創作品。輸出影片僅限個人、非商業使用，不得公開張貼於社群媒體或影音平台，亦不得用於工作或公司用途（包含內部教育訓練手冊）（摘要。原文請參閱 macOS 使用許諾的「語音」條款）
google / azure / amazon / openai / 透過 command 連接的 TTS：請遵守該 TTS 的使用條款。若為可商用 TTS，則可用於公開或商業用途。若 TTS 要求標註出處或標示為 AI 語音，請在 script.json 的 credit 中註明
若使用者要求看起來是為了公開張貼於社群媒體、影音平台，或工作、公司用途時，請在開始作業前告知使用者此限制，並說明可以切換為可商用 TTS。請勿提供法律判斷（應建議使用者參閱 Apple 使用許諾或所選 TTS 的使用條款）

0. 選擇版面類型

根據素材決定版面類型並簡短告知使用者（僅在不確定時才確認）。同時在此告知專案建立位置（2 的 <dir>）。

類型	`--layout`	外觀	適合的素材	完成範例（examples/）
房間	`guide`（預設）	房間內有同一人物站立，手持工具作業。細部手部動作用放大卡片顯示	飲料、家事、家電保養等「人操作工具」的內容	`room-microwave-rice`, `room-mug-wash`
螢幕操作	`guide-screen`	無人物。以輕觸、點擊、輸入操作手機/瀏覽器畫面。右側顯示重點備註，非重點區域變暗	應用程式、Web 服務的操作步驟	`screen-alarm`（手機）
俯視雙手	`guide-topdown`	從正上方俯瞰工作台，雙手從畫面下方伸出	料理、手工藝、包裝等以手部動作為主的內容	`topdown-cucumber`
組裝說明	`guide-manual`	白色方格紙上繪製等角線圖、虛線箭頭、螺絲鎖緊、零件清單	家具組裝、設備安裝、零件更換	`manual-smallbox`
直式	以上任一 + `--vertical`	1080×1920。房間類型時，人物在上方，櫃檯下方常駐放大卡片（僅房間類型已驗證）	手機直畫面觀看的簡短生活技巧、食譜	`vertical-coffee`

即使需要多語言版本，請先以一種語言完成後，再透過「6. 建立多語言版本」來新增。

1. 準備說明文件

將使用者的文字整理成以下 Markdown 格式，並儲存為 <dir>/procedure.md（若已是此格式則直接使用）。

# How to Brew Drip Bag Coffee
## Get ready [prepare]
Prepare a mug, a drip coffee bag and a kettle. Boil the water and let it cool to about ninety degrees Celsius.
## Open the bag [open]
Hold the bag with both hands, tear off the top strip along the marked line. Open it gently to avoid spilling the coffee.

# 標題、## 步驟名稱 [tag]，內文會直接朗讀。tag 為選用，會成為 visual 的名稱（open → Open）。只能使用英文字母開頭的英數字、-、_，否則會被忽略而變成 Step01 等
項目符號與編號清單的每個項目視為一句話。移除強調、連結、行內程式碼等標記後朗讀（不朗讀 HTML 標籤、註解、程式碼區塊。保留 <Enter> <URL> 這類按鍵名稱或需替換處的尖括號）。中文、日文以換行為句子的邊界（以句號結束的行會連接到下一行），英文等語言則以空行為段落邊界。若句末缺少句點則自動補上。表格（| … | 的行）與程式碼區塊不朗讀（移除表格時會出現警告）
步驟約 4 到 8 個，每個步驟 1 到 3 句話。一句話 = 動畫的一個區段，逗號（, 、）= 更細微的區段，請撰寫成「做什麼 → 怎麼做」以句號分隔的句式（例如：「Spread the paper hooks, attach them to the rim of your mug.」）
實際等待時間（如悶蒸、乾燥等）在影片中假設會縮短
若使用者的文字為說明書、筆記等自由格式，請依照 reference/rewriting.md 的標準改寫為說明文件格式

2. 建立專案並轉換為腳本

jgv new <dir> --kicker "DAILY RITUAL / COFFEE GUIDE" --layout guide

jgv new 會一次完成：建立專案（jgv init）、從說明文件建立腳本與 cue 的雛形（jgv md2script procedure.md -o script.json --stubs visuals）、產生音訊與 timeline（jgv tts）、以及輸出 cue 的時間表（jgv timing，包含每個步驟的 行.句 與從步驟開始起的秒數）。說明文件會使用 <dir>/procedure.md（若在其他位置，可使用 jgv new <dir> <說明文件> 複製過去）。選項與 jgv md2script 相同。後續指令需先 cd <dir> 再執行

<dir> 若使用者已指定位置則使用該處。若未指定，則不詢問，直接建立在 skill 及其存放庫之外（例如 ~/Movies/jgv/<素材>）。無論哪種情況，在建立前（於步驟 0 告知類型時）應以完整路徑告知使用者（例如：「將建立在 ~/Movies/jgv/shoulder-massage。若希望放在其他位置請告知」）。若建立在目前目錄下，可能會在存放庫中產生 out/、.jgv/ 等產出物
--layout 為步驟 0 選擇的類型。直式需加上 --vertical。--kicker 為左上角的系列名稱
人物外觀（--presenter）、與函式庫 defaults.json 的關係、雲端 TTS（--tts）、不顯示文字（--no-text 等）、舊版專案（jgv migrate）請參閱 reference/options.md 的「jgv new 的選項」。若 defaults.json 中已有 kicker / layout，則僅在使用者指定或步驟 0 選擇的類型不同時才加上 --kicker / --layout
若 jgv new 因錯誤而停止，jgv new 會自行清除已建立的內容（原有檔案則保留）。修正原因後，重新執行相同的 jgv new（若中斷，請參閱 reference/tips.md 的疑難排解）

產出的內容（此時已可完整執行至輸出）：script.json、每個步驟的 cues/<Visual>.cue（開頭有 行.句 編號與句子註解）、visuals/<Visual>.swift（一行呼叫 cue，請勿修改）、visuals/bind.swift（binding 的雛形）、.jgv/timeline.json、out/subtitles.srt。

修正日文讀音

日文部分，可在 script.json 中各行的 speak 中調整數字、英字、難讀詞語的讀音。修正讀音時請使用片假名（平假名容易與前後文混淆而造成斷詞錯誤，例如「食欲やはいせつぶつ」→「や／は／いせつ…」。使用 ハイセツブツ 則不會出錯）
使用 jgv yomi 查看每個詞語的讀音與警告，修正不正確的讀音。jgv yomi 不論引擎為何，都使用 macOS 的分析結果，僅供雲端 TTS 參考（修正為片假名對所有引擎都有效）（警告類型與修正方式請參閱 reference/tips.md 的「日文讀音」）
修正 speak 後，執行 jgv tts（僅重新朗讀被修正的行）→ jgv timing（重新輸出時間表）
若使用者指出讀音問題，修正後請在步驟 7 詢問是否要加入函式庫的 defaults.json 的 readings 中

3. 決定工具與畫面（binding）

決定每個步驟中要顯示的物品（工具、設備、畫面）、擺放位置、以及手部接觸點，並在 visuals/bind.swift（jgv new 會產生雛形）中以 binding 方式撰寫。所有步驟共用一個 binding。寫法請參閱 reference/cue.md 的「binding」。

開始撰寫前，請先閱讀一個相同類型的完成範例（從 examples/README.md 的清單中選擇，並閱讀其 visuals/bind.swift 與 cues/*.cue。相似的動作與工具擺放方式可從中複製）
工具優先使用 kit 中的零件與專案的 parts/（函式庫中的零件）。外觀可參考 reference/props-catalog.png 中的圖片，清單請參閱 reference/visual-kit.md 的「工具」。引數、握持位置（例如 KETTLE_PARTS）可使用 jgv api 水壺（可依名稱、日文名稱、說明文字搜尋。純 jgv api 則顯示名稱清單，也會顯示專案的 parts/）查詢，請勿 grep kit 的原始碼
若無對應工具，請依照 reference/prop-style.md 的規則在 visuals/props.swift 中繪製，並使用 jgv preview 確認範例（PROPS_PREVIEW）。使用者提供的 SVG 可放在 assets/ 中，使用 Svg("名稱") 繪製（請參閱 visual-kit.md 的「SVG 素材（assets）」）
工具的原點位置與縮放比例請使用具名常數（例如 let MW = Pt(1080, GUIDE.counterY)；直式則為 LAYOUT_PORTRAIT.counterY），以便後續修正時只需修改一處
人物用手接觸的工具或設備，應放置於人物附近（橫向畫面時約 x 1150 以內）（jgv check 會在手部距離過遠時發出警告）
「準備物品」「注意事項」「Before/After」「總結」等步驟，可使用 kit 中的場景類型（PrepareItems NoteCards BeforeAfter SummaryList）作為 binding 的繪製方式
各類型的視覺要點請參閱 reference/implementation.md 的「各類型要點」

4. 以 cue 撰寫步驟的動作

為每個步驟撰寫 cues/<Visual>.cue。時間 行.句 的編號來自雛形開頭的註解（# 0.0 冷凍ごはんを、 0.1 ラップのまま、…）以及 jgv new / jgv timing 的時間表。語法請參閱 reference/cue.md。相似的動作可從相同類型的完成範例（examples/）的 cue 中複製。每個 cue 僅數行到十數行，因此請在主流程中直接撰寫所有步驟，無需使用子代理。

init <Load
0.0+.3 H>mw.handle~.45
0.0+.35 mw.open=0~.6
0.2+.45 P mw.start;mw.on=1~.2;mw.disp=cd 2:00 0:[email protected];timer timer 2分@1.0
1.1+.7 H>dish.gripL~.4;dish.in=0
1.1+.77 dish@PLATE~.5;steam dish.top

每個語句撰寫一行「什麼 → 怎麼做」（在名詞、動詞被朗讀的時刻觸發動畫）。等待時間使用圓弧計時器（timer）與註解「等待時間已縮短」
手部動作（H> C> P）的時刻為「到達時刻」，其他動作的時刻為「開始時刻」。若要將值與手部動作對齊，請將值的時刻提前手部動作的持續時間
從第二個步驟開始，以 init <前一 step 開頭（繼承結束時的狀態）。若要持續保持放大卡片開啟，請在前一步驟設 card.exit=0，下一步驟設 card.enter=0
細微的手部動作（打開、舀取、摩擦、扭轉）使用放大卡片（card・C>）顯示。人物在卡片左側指示（H>gesture）。最後一個步驟顯示完成品加上勾選記號（check）以及蒸氣、閃爍的餘韻
避免靜止畫面：在旁白進行期間，應確保有蒸氣、搖曳（wave）、漣漪等持續動態

cd <dir> && jgv check

修正 cue 與 binding，直到不再出現 ! 開頭的行（名稱錯誤、手部距離過遠、在移動中放開夾取的物品、結束前 0.5 秒之後的動作、文字或框線重疊等）。H / C 行顯示手部的時間表（從幾秒到幾秒，從何處到何處）。S1→S2 行顯示步驟邊界處不同的值（僅顯示刻意變更的項目即為正常）。僅修改 cue 時不需重新編譯，可立即再次確認。行的解讀方式與修正方法請參閱 cue.md 的「jgv check」。

若 cue 無法描述的特殊動作，可在 binding 的繪製方式中以 Swift 撰寫，並透過 cue 以數值控制（請參閱 cue.md 的「以 Swift 撰寫時」）。也可以使用先撰寫分鏡稿，再交由步驟子代理平行實作的完整 Swift visual 方式（請參閱 reference/implementation.md）。

5. 整體確認 → 輸出

cd <dir> && jgv dev

jgv dev 會一次性完成所有確認：jgv tts（僅重新朗讀變更的行）→ 編譯 → jgv check（若有 ! 則在此停止）→ 僅對自上次 jgv dev 以來有變更的步驟執行 jgv snapshots。

binding 等處的編譯錯誤會以檔案名稱與行號顯示（例如 visuals/bind.swift:12:5: error: …）
最後一行「確認用圖片:」會顯示需閱讀的清單。初次執行，或 Swift 檔案、assets/、配色等有變更，或所有步驟都有變更時，會顯示整體的 out/snapshots/sheet.png。僅變更 cue 時，則顯示有變更的步驟的 out/snapshots/scene-N/sheet.png（包含以 init <前一 step 繼承的步驟）。變更腳本時，影片長度會改變，進度條也會移動，因此通常會顯示整體。若需重新拍攝所有步驟，可使用 jgv dev --all
務必以 Read 開啟「確認用圖片:」清單中的圖片進行確認，修正後重新執行 jgv dev（僅重新拍攝變更的步驟時，整體的 out/snapshots/sheet.png 會保留先前版本，請勿混淆）。手部時間的偏移，透過 jgv check 的手部時間表查看比圖片更快速
清單中過小無法辨識的部分（虛線、註解文字、手部與握把位置），請以同一資料夾中的逐格靜態圖片（影片一半大小，檔名為輸出時顯示的各行開頭編號，例如 03.png。若使用 jgv snapshots --scene=N --phrases 逐句拍攝，則為 02-04.png。jgv dev 無 --phrases 選項）進行確認

圖片需檢查的重點：

手部是否正確接觸工具握把，工具是否有懸空或重疊
語句內容與畫面動作是否一致（例如「tear off」這行是否確實呈現撕開的動作）
放大卡片中的小步驟標籤與註解是否可讀。文字、註解、框線的重疊或超出畫面邊界，jgv check 會以 ! 秒-秒s: 行顯示；圖片則需檢查物體之間的重疊、重複繪製的物體，以及 binding 的圖形是否與標題、字幕列重疊（check 不會顯示此類問題）。若使用 --no-text / --no-notes，則需確認說明文字是否確實未顯示

若無問題，則進行輸出，並接著建立概覽頁面：

cd <dir> && jgv render && jgv overview

out/overview.html 將每個步驟的旁白、visual 檔案、靜態圖片與 SVG 素材排列在單一頁面中（可用瀏覽器開啟）。告知使用者 out/video.mp4、out/subtitles.srt、out/overview.html 的位置，若可傳送則傳送影片檔案。接著進行「7. 儲存至函式庫」。

色調、語音等調整方式、錯誤處理方式、以及以 Swift 撰寫的實例（存放庫中的 demo/）請參閱 reference/tips.md。

6. 建立多語言版本

先以一種語言完成後，再依照 reference/multilang.md 的步驟新增 script.<語言>.json，並使用 jgv build-langs 一次性輸出（影像共用，僅更換腳本與畫面上的文字）。

7. 儲存至函式庫

輸出完成後，針對此影片中建立且可能用於其他素材的工具與動作（visuals/props.swift、shared.swift、binding 中撰寫的工具繪製方式），以及使用者選擇的偏好設定（配色、語音、速度等，不包含各素材的 kicker），還有使用者指出後修正的讀音（readings），列出候選項目，詢問使用者是否要儲存至函式庫（若無候選項目或所有項目已與函式庫相同則不詢問）。儲存時，請依照 reference/library.md 的「影片完成後儲存」步驟，放入 <library>/parts/ 與 <library>/defaults.json。如此一來，在下一部影片中就能減少繪製工具與告知設定的工作量。

j-guide-video 插圖步驟影片