培訓影片
語音主導,畫面跟隨:先有腳本與音訊,再有投影片或錄製內容,並根據每句台詞的長度進行同步。
與誰對話。 使用者可能不具備技術背景:請使用繁體中文(或使用者輸入的語言)溝通,用詞簡單,避免使用指令或路徑,除非對方主動詢問。技術步驟由你執行。僅詢問使用者應做的決策:內容、受眾、語言、視覺風格、批准事項。
腳本 位於 ${CLAUDE_SKILL_DIR}/scripts/,並透過 python3 -B ${CLAUDE_SKILL_DIR}/scripts/<腳本>.py … 執行 —— 在 Windows 上請使用 doctor.py 於「Python 指令」行中指定的命令(python 或 py -3);投影片與渲染則使用 node ${CLAUDE_SKILL_DIR}/deck/render.cjs …;應用程式錄製則使用 ${CLAUDE_SKILL_DIR}/screencast/。主題檔案位於 ${CLAUDE_PLUGIN_ROOT}/themes/。適用於 macOS 與 Windows(Bash 與 PowerShell):指令保持簡單 —— 不使用管線、&& 或重新導向。
專案 是你目前工作的目錄(產品的儲存庫或文件目錄)。每個專案都有一個專屬的 Gemini 金鑰,僅儲存在使用者的電腦上(Keychain / Credential Manager);專案的標記是 .training-video/project.json(包含 id 與名稱,不含機密資訊)。
四階段批准 —— 未經批准不花錢與時間
- 腳本(台詞文字與投影片 / 畫面的規劃)。
- 成本 —— 由
cost.py產生的表格。少量試作(最多 3-4 句台詞)無需批准,完整配音則需要。 - 語音樣本 —— 前 3 句台詞(
narrate.py --sample 3);使用者聆聽。 - 視覺 —— 1-2 張完成的投影片或錄製畫面,在完整渲染之前。
執行步驟
- 環境與金鑰 —— 每次啟動時,在任何其他步驟之前執行。
- 執行
doctor.py <專案>。缺少的項目,在使用者許可下,使用doctor.py為該系統提供的命令(brew / winget)進行修正;對於渲染,在${CLAUDE_PLUGIN_ROOT}中執行npm ci(如果 Claude Code 尚未執行),以及npx playwright install chromium。 - 專案金鑰: 執行
key.py check <專案>。OK→ 繼續。沒有專案→ 告知使用者該目錄將建立一個小型檔案.training-video/project.json(包含專案名稱與編號,不含機密資訊 —— 可加入 git),並詢問專案名稱(建議使用目錄名稱)。然後啟動精靈。沒有金鑰→ 如果顯示有舊的通用金鑰,詢問「是否要將您現有的 Gemini 金鑰也用於此專案?」(是 → 執行key.py setup <專案> --use-legacy)。否則啟動精靈。被拒絕→ 使用--replace啟動精靈。
- 精靈: 首先用簡單的詞語說明接下來的步驟:「將會開啟 Google AI Studio 頁面 —— 請在將為此專案支付語音費用的帳戶中建立一個金鑰 (Create API key),然後複製它。接著會出現一個視窗讓您貼上金鑰;金鑰僅保留在此電腦上。」執行
key.py setup <專案> [--name "<名稱>"]—— 它會開啟頁面與視窗,在 Gemini 中驗證金鑰並儲存。切勿在聊天中要求金鑰,也請勿將其寫在任何地方;如果使用者將金鑰貼到聊天中,請告知他們從 Google AI Studio 中刪除該金鑰並建立一個新的。 - 技術人員可使用 Vertex(
gcloud auth application-default login與GOOGLE_CLOUD_PROJECT);環境變數GEMINI_API_KEY適用於所有專案 —— 僅限 CI 使用。
- 執行
- 接收任務 —— 自行判斷,僅詢問不明確的事項。
- 現有資源:聊天中的檔案 / 目錄、磁碟上的檔案、Google Drive 連結(透過已連接的 Google Drive 連接器,如果有的話)、網頁連結、產品的 git 儲存庫(其中的
.training-video/profile.md表示該產品已準備好製作影片)。 - 有 PDF,且
doctor.py顯示「poppler (PDF): 無」 → 用一個問題詢問:「為了從 PDF 中提取文字與圖片,需要一個小型程式 (poppler, 約 35 MB)。是否安裝它?」若回答「是」—— 使用doctor.py給出的命令 (brew / winget);若回答「否」—— 直接讀取 PDF,不從中提取圖片。 - 模式:素材驅動 → 參考
reference/materials.md;程式碼驅動(應用程式錄製) → 參考reference/code.md。如果兩者皆有,詢問影片屬於哪一種。 - 程式碼驅動 —— 針對哪個角色。 影片針對應用程式的一個角色(操作員、經理、管理員……):錄製將以該角色登入,並僅顯示其畫面。角色從產品設定檔或程式碼中取得(
reference/code.md,「角色 — 從程式碼中取得」),並以預設選項提問 —— 使用應用程式使用的標籤。在角色登入檢視 (survey.cjs) 完成之前,不要撰寫腳本。 - 一併提問(使用帶有預設選項的問題):影片的目標受眾是誰,以及他們看完後應能做什麼;語音語言(預設為繁體中文);字幕語言;長度(預設 3-8 分鐘);主題(
themes/,預設為「中性」;如果素材有自己的品牌,建議從中選擇主題);成品存放位置(Drive 目錄或電腦本地)。
- 現有資源:聊天中的檔案 / 目錄、磁碟上的檔案、Google Drive 連結(透過已連接的 Google Drive 連接器,如果有的話)、網頁連結、產品的 git 儲存庫(其中的
- 影片目錄 —— 位於外掛與產品儲存庫之外,預設在使用者的「文件」目錄中:
<文件>/培訓影片/<簡稱>-<日期>/(Mac 上為~/Documents;Windows 上為%USERPROFILE%\Documents,可能位於 OneDrive):video.json——{"name": "<輸出檔案名稱>", "project": "<專案絕對路徑>", "lang": "zh-TW", "voice": "Charon", "subtitles": ["zh-TW", "en"], "theme": "neutral", "mode": "materials|code"}——project指定由哪個金鑰支付語音費用;對於「程式碼驅動」模式,還需包含"product": "<儲存庫>"和"role": "<角色>";script.json—— 腳本(格式參見scripts/lines.py);audio/、timeline.json、final/將由腳本建立;sources/—— 用於撰寫腳本的素材副本或摘錄(由extract.py分解),以及sources/facts.md—— 帶有來源的事實。
- 腳本。 文字規則參見
reference/script.md(語氣、長度、say、事實)。以可讀文字(按章節)呈現給使用者,而非 JSON 格式。根據反饋進行修正,直到使用者表示「可以了」。 → 批准 1。 - 成本。 執行
lines.py <目錄>,然後執行cost.py <目錄>;顯示表格。 → 批准 2。 - 語音樣本。 執行
narrate.py <目錄> --sample 3;提供使用者三個.wav檔案的路徑(或直接播放:Mac 上使用open <檔案>,Windows 上使用start "" "<檔案>")。如果語氣不合適 —— 修改video.json中的voice(語音試聽:tts.py --probe --voice <名稱>),然後重複此步驟。 → 批准 3。 - 視覺。 根據模式:1-2 張投影片(
reference/materials.md)或錄製畫面(reference/code.md)。 → 批准 4。 - 完整配音。 執行
narrate.py <目錄>。最後輸出報告;任何REDO <id>: …行 → 執行narrate.py <目錄> --only <id> …,直到沒有REDO為止(例外情況參見reference/voice.md)。 - 畫面。 根據模式 —— 渲染投影片或錄製螢幕;寫入
timeline.json與final/<名稱>.mp4。 - 字幕。 自行將每句台詞的
text翻譯成subs/<語言>.json({"<id>": "翻譯"})中指定的每種額外語言:使用相同的企業語氣,數字使用阿拉伯數字,名稱保留素材中的原樣。然後執行srt.py <目錄> <名稱>。 - 檢查 —— 參見
reference/voice.md中的「最終檢查」。在所有項目通過之前,不要說「完成」;未通過的項目需直接指出。 - 交付。 如果使用者指定了 Google Drive 中的目錄,並且有已連接的 Drive 連接器 —— 使用其進行上傳;否則 —— 提供
final/的路徑。簡短說明:長度、語言、成本、仍待檢查的項目。
語氣 —— 始終保持一致
專業、企業級、面向成年同事 —— 即使產品是針對兒童。不要幼稚,不要廣告化,不要「給初學者的解釋」。詳細說明:reference/script.md。語音在台詞之間不應改變:整個影片使用同一種 voice、同一種風格、同一溫度設定(reference/voice.md)。