工作區設定
支援 macOS(Apple Silicon)、Linux(透過 apt,Ubuntu 22.04+、Debian 12+)以及 Windows(透過 WSL 2)。此儲存庫包含規則、技能、工具、共享的 CC0 音效、Previs Studio 及一個示範影片,但沒有任何與機器或個人相關的內容:沒有 API 金鑰、沒有 .venv、沒有 node_modules、沒有使用者層級的技能或外掛、沒有 OWNER.md。這個技能會幫助擁有者建立一個可用的工作室。SETUP.md 是為人類撰寫的相同程序。
請用簡單明瞭的語言與擁有者溝通。他們可能不具備技術背景,也可能對動態設計一無所知。一次只進行一個步驟,說明每個步驟的內容、原因以及預計花費的時間。
嚴格規則
- 絕對不要在對話中詢問 API 金鑰,也絕對不要輸入、顯示、記錄或寫下任何金鑰。 金鑰必須透過
scripts/setup/keys.sh輸入,該腳本由擁有者在其自己的終端機中執行,並使用隱藏輸入方式(macOS 使用鑰匙圈;Linux/WSL 2 使用密碼儲存區或~/.config/motion-studio/keys.env)。如果使用者仍然在對話中貼上金鑰:請勿使用或儲存它。告知他們該金鑰現在已留在對話記錄中,請他們在提供者的網站上刪除該金鑰並產生新的,然後使用keys.sh儲存新的金鑰。 - 安裝動作必須獲得他們的同意(參見 AGENTS.md 中的「先詢問」)。在執行任何
install.sh步驟之前,請使用 AskUserQuestion 詢問,並告知下載大小。 - 請勿自行執行
sudo。在 macOS 上,Homebrew 的安裝程式需要他們的密碼;在 Linux/WSL 2 上,bash scripts/setup/install.sh system(apt)也需要。他們在自己的終端機中執行這一個指令。(在 Claude Code 雲端工作階段中,你具有 root 權限,因此可以執行它。)
步驟
- 尚未進入儲存庫? 如果當前資料夾不是 motion-studio 的副本(沒有包含「motion-studio」的
AGENTS.md檔案,也沒有scripts/setup/資料夾),請先複製它:git clone https://github.com/jayfirke/motion-studio.git motion-studio(詢問存放位置,預設為其家目錄或當前資料夾中的motion-studio資料夾),然後在該資料夾內工作。告知他們最後需要在那個資料夾中開啟一個新的工作階段。 - 打招呼並設定預期,用三行說明:設定的內容(檢查工具、安裝遺漏的項目、寫入他們的偏好設定、儲存他們的金鑰),大約需要 15–30 分鐘,大約需要 3 GB 的下載量(系統套件、Chromium、1.6 GB 的 Whisper 模型)。說明系統醫生偵測到的系統(macOS、Linux 或 WSL 2)。
- 檢查: 執行
bash scripts/setup/doctor.sh。用簡單的語言摘要 NEED 行的內容(每個項目是做什麼用的),然後用一句話說明 OPT 行的內容。 - 系統工具。
- macOS 且未安裝 Homebrew: 請他們自己在終端機中執行 https://brew.sh 的官方安裝程式(會要求輸入密碼),然後依照其輸出的「Next steps」指示操作。
- Linux / WSL 2: 請他們在自己的終端機中執行
bash scripts/setup/install.sh system(apt 需要他們的密碼;它也會建置whisper-cli並安裝 Node 22 和 uv)。在 ARM Linux 上,它會輸出一行export HYPERFRAMES_BROWSER_PATH=…,需要加入到他們的 shell 設定檔中。 等待「done」訊息,然後再次執行醫生腳本。
- 選擇安裝項目,使用一次 AskUserQuestion(多選)。僅提供醫生標記為遺漏的項目:
- 「核心工作室」= 在 macOS 上執行
install.sh core(Homebrew 工具、Python 虛擬環境、Claude 技能、Claude 外掛);在 Linux/WSL 2 上,在他們的system步驟之後,執行install.sh venv skills plugins。建議安裝。 - 「Whisper 模型,1.6 GB」= 執行
install.sh whisper-model(用於字幕和語音檢查的文字時間戳)。建議安裝。 - 「Previs Studio 套件」= 執行
install.sh app(用於重建 Previs Studio 並執行其檢查)。 - 「onetake」= 執行
install.sh onetake:僅限個人、非商業實驗用途(PolyForm Noncommercial 授權)。 - 「Motion Reel Kit」= 執行
install.sh motion-reel <kit folder>:僅在他們從其創作者處購買或下載了該套件時使用(請參見CREDITS.md);此套件不在此儲存庫中。 在工作區根目錄執行已獲准的步驟。長時間的步驟(brew、whisper-model)請在背景執行;告知他們正在執行什麼。如果某個步驟印出FAIL …並附帶修復方式:嘗試修復一次,然後解釋並詢問。
- 「核心工作室」= 在 macOS 上執行
- 他們的偏好設定。 將
OWNER.example.md複製為OWNER.md,然後透過一至兩輪 AskUserQuestion 詢問問題(姓名、他們的工作內容、個人或商業用途、動態設計經驗、預設語音、品質標準、預算與審核流程)。將答案以他們自己的話語寫入OWNER.md。此檔案已加入 git 忽略清單,絕不會被分享。 - API 金鑰。 使用 AskUserQuestion 詢問他們現在想要設定哪些金鑰:
- Fish Audio(每個旁白都需要;免費帳戶;免費模型
s2.1-pro-free免費使用至 2026-11-30):金鑰請至 https://fish.audio/app/api-keys/ 取得。 - Freesound(選用;僅用於搜尋和下載新的音效;免費帳戶):請至 https://freesound.org/apiv2/apply/ 申請,並複製「Client secret/Api key」和「Client id」。
然後請他們在自己的終端機中執行
bash scripts/setup/keys.sh: - 在 Claude 桌面應用程式中,如果你有終端機工具(
run_in_terminal),請在他們的終端機面板中啟動cd "<workspace>" && bash scripts/setup/keys.sh,並告訴他們在該處輸入。在他們輸入時請勿閱讀該面板。 - 否則請他們開啟一個終端機(macOS 的終端機,他們的 Linux 或 WSL 終端機)並貼上:
cd <workspace> && bash scripts/setup/keys.sh。 當他們告知完成時,執行bash scripts/setup/doctor.sh --online。它會確認金鑰正常運作,但不會顯示金鑰內容。
- Fish Audio(每個旁白都需要;免費帳戶;免費模型
- 選用擴充功能(一個簡短清單,讓他們選擇):
- Diffusion Studio(剪輯真實影片、物體遮罩):在 macOS 上,他們從 https://diffusion.studio 下載應用程式,開啟一次,然後你執行
install.sh diffusion-mcp。在 Linux 上,它以網頁應用程式(https://app.diffusion.studio)的形式執行,沒有 MCP。 - claude.ai 中的 Fish Audio 連接器(設定 → 連接器)。非必要;腳本會直接使用金鑰。
- Remotion 對個人與不超過 3 人的公司免費;較大的公司需要 Remotion 授權。
- Diffusion Studio(剪輯真實影片、物體遮罩):在 macOS 上,他們從 https://diffusion.studio 下載應用程式,開啟一次,然後你執行
- 完成。 寫入
.local/setup.json(建立.local/資料夾;它已加入 git 忽略清單):執行{"owner": "<名字>", "setup_at": "<來自 date -u +%Y-%m-%dT%H:%M:%SZ 的 UTC 時間>", "by": "workspace-setup", "doctor": "<DOCTOR 行的內容>"}bash scripts/setup/session-check.sh(現在應該不會印出任何內容)並再次執行醫生腳本。回報哪些項目已就緒,哪些被跳過。 - 告訴他們接下來要做什麼:
- 在此資料夾中啟動一個新的 Claude Code 工作階段。技能、外掛和 Diffusion MCP 只會在工作階段啟動時載入。
- 開啟示範:
python3 -m http.server 8790 --directory _shared/previs/studio,然後開啟 http://localhost:8790(包含 Crumb 示範影片的 Previs Studio)。 - 一個可以嘗試的初始提示:「為 <你的產品> 製作一個 15 秒的啟動預告片。先製作 Previs。」
重新執行
隨時可執行 bash scripts/setup/doctor.sh。bash scripts/setup/install.sh <step> 可以安全地重複執行某個步驟。刪除 .local/setup.json 即可重新執行整個設定程序。