動畫操作手冊

影片操作手冊

將產品畫面轉變為一段附有字幕的短暫導覽影片：動畫游標點擊畫面各處、高亮標示與縮放引導目光，並以動畫文字說明每個步驟。

工作分為四個步驟。使用者決定內容；您負責產出。

步驟	使用者	您
1. 產品專案	說明產品目標對象、設定品牌色、背景模板、標誌、品牌指南	推導語氣規則並調整動態效果
2. 場景	附上螢幕截圖或 Figma 連結	匯入 Figma 畫面
3. 腳本草稿	確定關鍵畫面、順序與文字	擬定草稿供其編輯
4. 影片	觀看、編輯文字與順序、對畫面發表評論	加入動作、檢查每個畫面、根據評論修改、輸出

使用者最在意的是文字與順序，因此這些項目會在步驟 3 中先確定，之後才進行產出工作，並且在步驟 4 中仍可編輯，直到 MP4 輸出為止。

使用使用者的語言與其交談。除非另有指示，否則字幕應使用產品介面的語言撰寫。

兩種工作方式

使用 Studio（預設）。一個本機網頁應用程式會顯示這四個步驟。使用者在該處操作；標示 ✦ 的按鈕會將請求排入佇列，由您接收、處理並回覆。在開始之前，請先閱讀 references/studio.md —— 這是該循環的協定。

僅透過對話進行。當使用者不想開啟瀏覽器，或者您無法執行本機伺服器時，請透過提問並在對話中展示的方式，完成相同的四個步驟。詳見下方的「不使用 Studio」。

無論採用哪種方式，檔案都完全相同，因此專案可以在兩者之間切換。

專案結構

所有內容都放在使用者專案中的 video-manual/ 目錄下，因此一個設定檔即可服務為該產品製作的所有操作手冊：

video-manual/
├── product-profile.json     # 每個產品一份：目標對象、語氣、動態效果、背景
├── brand/                   # guide.md（貼上的品牌指南）、標誌
├── requests.json            # 從 Studio 排入佇列的請求
└── <操作手冊-slug>/           # 每部影片一個資料夾，例如 create-task/
    ├── screens/             # 01-board.png, 02-new-task.png, ...
    ├── storyboard.json      # 先有草稿，之後再補完整腳本
    ├── comments.json        # 來自 Studio 的畫面評論
    └── out/                 # manual.html, manual.mp4, stills/, frames/

設定

腳本位於此技能的 scripts/ 資料夾中。輸出需要先安裝一次相依套件：

cd <技能目錄>/scripts && npm install

然後在背景啟動 Studio，並將位址提供給使用者：

node <技能目錄>/scripts/studio.mjs video-manual --open

用一句話告訴他們接下來會發生什麼事：他們會填寫步驟 1，而您會接收他們透過 ✦ 按鈕發送的內容。然後按照 references/studio.md 的說明等待請求。

步驟 1 — 產品專案

如果 video-manual/product-profile.json 中已經有 voice 區塊，表示產品已設定完成：直接使用即可。同一產品的各影片之間保持一致，比個別調整每個影片更為重要。

否則，使用者填寫表單（名稱、領域、B2C/B2B、目標年齡、裝置、強調色、背景模板、選填的標誌與品牌指南），並發送一個 profile 請求。接著：

1. 讀取 product 區塊與 brand/guide.md。
2. 撰寫 voice 區塊 —— 語氣風格、句尾、最長字幕、應避免的詞彙、產品術語。請閱讀 references/voice-guide.md。使用者的品牌指南優先於其中的一般建議。
3. 針對相同的目標對象調整動態效果。請閱讀 references/motion-profiles.md。使用者已選定預設與背景；您應根據其目標對象的需求，調整節奏、大小與緩動。
4. 加入一兩句的 rationale（理由）。

這三項事實 —— 目標年齡、領域、B2C 或 B2B —— 決定了每一條字幕。如果表單中有一項空白，或畫面與其矛盾，請在撰寫語氣規則之前先提問。

步驟 2 — 場景

每個不同的畫面狀態一張圖片，放在 screens/ 中，並依出現順序編號。一個會明顯改變的狀態（例如彈出視窗開啟、下拉選單展開、表單填寫中）需要自己的圖片：影片會透過切換到下一個螢幕截圖來顯示點擊的結果。

使用者通常會在 Studio 中上傳這些圖片。如果是附有 Figma 連結的 scenes 請求，請將每個畫面匯出為 PNG，並記錄其邏輯寬度作為 coordWidth；同時讀取圖層元資料 —— 確切的元素邊界遠比從像素推估可靠得多。

如果遺漏了導覽所需的狀態，請指出缺少哪一個並要求使用者補上，而不是跳過這個步驟。使用者無法跟上的跳躍畫面會讓操作手冊失去意義。

步驟 3 — 腳本草稿

收到 draft 請求時，讀取所有畫面與設定檔，然後將草稿寫入 storyboard.json：依序排列的場景，每個場景包含 caption 與描述該場景發生事項的 note。此時還沒有動作。請閱讀 references/manual-script.md 了解如何界定影片範圍與撰寫文字，並以設定檔中的語氣撰寫每一行文字。

使用者在 Studio 中編輯草稿，並在文字與順序正確時按下「Request the video」。這個 produce 請求即為核准。在收到該請求之前，請不要加入動作。

步驟 4 — 影片

產出

閱讀 references/storyboard-schema.md，並將核准的草稿轉換為完整的腳本：依照每個場景的 note 加入動作，設定 coordWidth。字幕維持與核准時完全相同。

座標是最容易出錯的部分。當您有確切邊界資訊時（Figma 元資料、DOM 矩形），請使用它們。當您只有圖片時，請仔細觀察並估算；後續的檢查步驟就是為了找出您可能弄錯的地方。

在使用者看到之前先檢查

建置，然後輸出靜止畫面 —— 在每次點擊、文字與字幕變更時，以及每個場景結束時，各輸出一張：

node <技能目錄>/scripts/build.mjs video-manual/<slug>/storyboard.json
node <技能目錄>/scripts/render.mjs video-manual/<slug>/out/manual.html --stills video-manual/<slug>/out/stills

build.mjs 會驗證腳本，檢查每條字幕是否符合設定檔的語氣規則，並印出每個場景的時間點。修正錯誤。對於使用者編寫的文字，如果觸發了語氣警告，請保留他們的措辭，並在回覆中提及該警告。

檢視靜止畫面並檢查每一張：

• 游標尖端是否在字幕所指的元素上？
• 高亮環是否完整包圍該元素，且沒有包到其他東西？
• 縮放後，目標是否完全在畫面中且清晰可讀？
• 輸入的文字是否位於欄位內並覆蓋了預留文字？
• 每條字幕是否完整可見，且最多兩行？
• 每個提示框是否指向正確的元素，且沒有遮擋到該元素或游標？

修正腳本，重新建置並重新輸出靜止畫面，直到每一幀都通過檢查，然後回覆請求。一個點擊在按鈕旁邊的游標會讓整本操作手冊看起來有問題，因此使用者絕不應該成為發現這種錯誤的人。

審閱循環

在 Studio 的步驟 4 中，使用者可以：

• 編輯任何字幕、標題或螢幕上的文字，並重新排序場景 —— 直接儲存到 storyboard.json，無需請求；
• 暫停在某一幀，標記位置並撰寫評論，然後將評論作為 revise 請求發送。

按照 references/studio.md 的描述處理 revise 請求：輸出被評論的那一幀，看看他們看到了什麼；只修改評論所指的內容，不要動其他東西；用一張新的靜止畫面確認問題已修正；然後回覆每一條評論。在他們重新排序場景後，檢查每個點擊是否仍能正確導向後續的畫面；中斷的連結是應該告知他們的問題，而不是默默地修復。

這個循環會持續進行，直到使用者滿意為止。

輸出

使用者可以在 Studio 中一鍵將 MP4 匯出。若要自行輸出：

node <技能目錄>/scripts/render.mjs video-manual/<slug>/out/manual.html --out video-manual/<slug>/out/manual.mp4

輸出所需的時間大約與影片本身等長，在較慢的機器上可能需要兩到三倍時間；對於超過一分鐘的操作手冊，請在背景執行。回報輸出路徑、長度與檔案大小。

不使用 Studio

在對話中完成相同的四個步驟：

1. 專案 —— 根據畫面與 UI 文字推斷目標年齡、領域與 B2C/B2B，說明您的判斷並用一個問題請使用者確認。然後自行撰寫完整的設定檔，包括預設、強調色與背景。
2. 場景 —— 將使用者提供的圖片複製到 screens/ 中，或者如果您有瀏覽器或 Figma 工具，則自行擷取。
3. 草稿 —— 撰寫腳本草稿，以表格形式呈現（步驟、畫面、發生什麼事、字幕、螢幕文字）並附上預估長度，然後等待核准。如果他們一開始就說要直接進行，則繼續進行並告知草稿所在位置。
4. 影片 —— 按照上述方式產出並檢查，然後告知他們 out/manual.html 的位置。該獨立頁面會播放影片，並附有編輯文字與順序的面板；「Download edits」會產生一個 storyboard.edited.json 檔案，他們可以交回給您。當他們這樣做時，列出哪些部分已更改，以便他們確認您正確理解了他們的意圖，然後將其儲存為 storyboard.json，重新建置並重新檢查靜止畫面。最後輸出。

後續修改

• 文字或順序：使用者在 Studio 中編輯，或直接告訴您。
• 語氣（「太生硬了」、「我們的用戶年齡比那更大」）：修改設定檔中的 voice 區塊，然後重新撰寫相符的字幕。
• 感覺（「太慢了」、「太彈跳了」）：修改設定檔中的動態效果參數，而不是個別場景 —— 請參閱 references/motion-profiles.md 中的調整表格。
• 某個步驟看起來不對：修正該場景的動作，並重新檢查其靜止畫面。

在每次修改後、重新輸出新版本之前，都要重新建置並檢查靜止畫面。

限制

當請求觸及以下任一項時，請明確告知：

• 畫面是靜態圖片。不會重現滾動、懸停狀態與應用程式內的動畫；請以獨立螢幕截圖呈現。
• 沒有旁白或音樂。字幕與螢幕文字負責解說。
• Studio 可以編輯文字與場景順序。某個步驟點擊或高亮的內容，需要透過對您的評論來更改。
• 預設輸出為 16:9。若需要其他比例，請在腳本中設定 meta.width 和 meta.height。

疑難排解

• playwright-core is not installed：在 scripts 資料夾中執行 npm install。
• no browser found：安裝 Google Chrome，或在 scripts 資料夾中執行 npx playwright install chromium。
• ffmpeg not found：安裝 ffmpeg 或設定 FFMPEG_PATH。npm install 通常會透過 ffmpeg-static 提供一個。
• 請求在 Studio 中一直顯示「等待中」：沒有人正在執行 studio.mjs wait。請執行它，或執行 studio.mjs pending。
• 步驟 4 顯示錯誤而非影片：某個場景指向了不存在的圖片，或座標超出畫面範圍。build.mjs 會指出是哪個場景。
• 字型看起來不對：影片使用機器上安裝的字型。請在設定檔中將 font.family 設定為已安裝的字型。