前言¶

電商和 Listing 團隊做傢俱、DIY 類產品時，常會有一組按順序拍好的組裝步驟照。要把它們變成可投放的短視頻，常見做法是手工在剪輯軟件裏逐段做動效、再拼接時間線，步驟多、改一幀就要重導整條片。

下面介紹 SkillHub 上的 組裝步驟視頻·一步一鏡（@beatra-ai/assembly-one-step-clip）。它把「賣家提供的步驟事實 + 已授權靜幀」約束成工作流：每張靜幀對應一次圖生視頻調用，按步驟順序交付多條短片，而不是在 Agent 裏發明拼接工具。

這是什麼¶

組裝步驟視頻·一步一鏡 是 beatra 發佈的企業源 Skill（design-media），當前版本 0.1.9。SkillHub 頁面簡介與包內 SKILL.md 一致：按賣家提供的步驟事實，爲每張靜幀做成一條一步一鏡短片，並按步驟順序交付產品組裝短視頻與步驟視頻。

底層能力通過隨包腳本連接 Beatra MCP（https://mcp.beatra.cn/mcp），使用 beatra.videos.animate 等工具；SkillHub 標籤標明 requires_api_key=false，但首次使用仍需在本機完成 Beatra 設備授權（見下文），視頻生成按 Beatra 積分計費。

核心功能¶

根據已安裝的 SKILL.md 與 references/workflow.md，可覈實的能力包括：

1. 一步一鏡規劃：只依據賣家事實與靜幀可見內容編寫帶標註的步驟計劃；缺信息處標爲缺口，不編造扭矩、工具或警告。規劃結果免費可見，且不等於用戶批准付費生成。
2. 靜幀檢查與上傳：記錄 MIME、寬高、畫幅、大小、alpha 等；本地文件經 scripts/mcp_client.py upload 上傳爲 artifact，禁止把本地路徑直接傳給 beatra.videos.animate。
3. 模型與約束覈對：調用 beatra.models.list（capability: image_to_video），確認支持無 driving_audio 的首幀圖；默認 model: "auto"，時長在用戶選擇的 2–15 秒整數內，未指定時用 5 秒。
4. 付費前生產卡：任意 beatra.videos.animate 前須展示六字段確認卡（做什麼、單價、筆數、每幀獨立 client_request_id、停在此處仍保留計劃、餘額不足時的官方說明與充值鏈接），用戶確認後再提交。
5. 按步交付：每幀一次 animate，用 beatra.tasks.get 輪詢至終態；按步驟順序交付短片及實際尺寸、時長、billing.net_charged_credits；不要拼接、concat 或虛構剪輯工具。
6. 賬戶與恢復：只讀查詢可用 beatra.wallet.get / beatra.wallet.ledger；任務丟失時通過 beatra.tasks.list 與凍結載荷恢復；餘額不足時保留鏈接，用戶確認充值後再用同一標識重試。

相鄰路線在 Skill 內寫清：商品照口播成片用 product-video-studio，房源房間靜幀用 listing-room-video-pack，非組裝通用靜幀用 image-to-motion。

安裝與啓用¶

1. 安裝 SkillHub CLI（若尚未安裝）¶

按 SkillHub 安裝說明 檢查或安裝 CLI：

command -v skillhub && skillhub --version

未安裝時可執行文檔中的 curl 安裝腳本（完整安裝或 --cli-only）。

2. 安裝本 Skill¶

官方頁面提示：根據 https://skillhub.cn/install/skillhub.md 安裝 @beatra-ai/assembly-one-step-clip。

在終端中，必須用 --dir 指向當前 Agent 的 skills 目錄，否則默認裝到 ./skills/ 可能不會被識別：

skillhub install assembly-one-step-clip --namespace beatra-ai --dir <你的 Agent skills 目錄>

常用路徑（來自同一安裝文檔）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或項目下的 .agents/skills/

安裝完成後，若宿主僅在會話啓動時加載 Skill，需新開一次 Agent 會話。

3. Beatra 授權¶

在已安裝的本 Skill 目錄下運行（需 Python 3.10+，隨包腳本僅用標準庫）：

python3 scripts/authorize.py

憑證保存在 ~/.beatra/credentials.json（與 ~/.beatra/installation.json 配合）；勿將 Device Token 寫入對話或日誌。成功後會輸出 Beatra is ready。連接驗證示例：

python3 scripts/mcp_client.py verify
python3 scripts/mcp_client.py tools

若從 SkillHub 安裝，首次連通後可按對話線索記錄安裝來源（可選）：

python3 scripts/mcp_client.py install-source --guess skillhub

典型用法¶

下面步驟摘自包內工作流，可在安裝目錄中復現。

1. 上傳步驟靜幀

python3 scripts/mcp_client.py upload ./step-01-attach-leg.jpg --mime-type image/jpeg

保留輸出的 artifact ID，後續 animate 使用 artifact 引用，而非本地路徑。

2. 讀取當前圖生視頻模型卡

python3 scripts/mcp_client.py call beatra.models.list

標準輸入 JSON：

{"capability": "image_to_video"}

3. 用戶確認生產卡後，單幀提交 animate

printf '%s' '{
  "image": {"type": "artifact", "artifact_id": "art-step-01"},
  "prompt": "A restrained camera hold on this assembly step. Keep the shown part and action in place. Do not add unstated tools or warnings.",
  "duration": 5,
  "client_request_id": "opaque-assembly-step-01"
}' | python3 scripts/mcp_client.py call beatra.videos.animate

4. 輪詢任務並按步驟順序交付

對每次創建響應使用 beatra.tasks.get 直至終態；多幀時保持步驟順序，並覈對與標註計劃是否一致。

所有遠程 Beatra 調用均通過隨包 scripts/mcp_client.py 完成，不要配置宿主 Beatra Connector，也不要改用 REST/OpenAPI 作爲降級。

適用場景與注意¶

適合誰

• 賣家或 Listing 團隊已有按步驟拍攝的組裝靜幀，且能給出每步的零件、動作或序號等事實。
• 需要「一張圖一條短片」的組裝教程素材，按步驟順序交給後期或投放，而不是單條長片內由 Agent 拼接。

限制與注意

• 硬輸入不足（無靜幀、無步驟事實）時應補問，不能從公開帖子或相似 SKU 臆造步驟。
• 每張靜幀對應一次付費 beatra.videos.animate；批量中途積分耗盡時，隨包更新說明會停止後續批次並提示充值（見 manifest.json changelog）。
• 默認不帶 driving_audio；需要口播商品視頻應走其他 Beatra Skill 路線。
• 包內客戶端可每 24 小時靜默檢查更新；可用 python3 scripts/mcp_client.py update --check 等子命令管理自動更新行爲。

SkillHub 側（抓取資料）：分類 design-media，發佈者 beatra，來源 enterprise，評分 100000，下載 4980；頁面與 CLI 搜索均顯示版本 0.1.9。

結尾¶

組裝步驟視頻·一步一鏡 把組裝短視頻生產收斂爲「步驟事實 + 靜幀上傳 + 按幀圖生視頻 + 順序交付」，並在付費前用生產卡和獨立 client_request_id 約束批量行爲。若你的工作流正是「一步一鏡、不拼接」，可在 SkillHub 安裝該 Skill 並按包內 SKILL.md 執行。

• SkillHub 頁面：https://www.skillhub.cn/skills/beatra-ai/assembly-one-step-clip
• 官方 API 路徑：https://api.skillhub.cn/beatra-ai/assembly-one-step-clip
• Beatra 技能主頁（manifest）：https://www.beatra.cn/skills/assembly-one-step-clip