Communitygithub.com

ChatCut-Inc/agent-plugin

當 Codex 使用 ChatCut 插件(chatcut MCP 伺服器)來新增、建立、手寫、修補或放置動態圖形 JSX 素材時使用。涵蓋參考瀏覽、直接內嵌 JSX 編寫、可編輯屬性、素材綁定、時間軸放置以及合成驗證。

agent-plugin 是什麼?

此技能專門用於透過 Codex 等 AI 代理程式,在 ChatCut 網頁編輯器中建立和編輯動態圖形(Motion Graphics, MG)素材。它要求代理程式使用 `chatcut` MCP 伺服器,並遵循嚴格的流程:先瀏覽視覺參考資料以確認設計方向,然後套用選定的設計樣式,再比對實例以滿足具體的 MG 形式需求。在編寫 JSX 程式碼之前,代理程式必須先檢查專案狀態、放置位置、時間點和內容等關鍵資訊,並確保使用 ChatCut 渲染器中可用的字型。最終,代理程式需將 JSX 程式碼直接內嵌傳入 MCP 工具,以建立或更新素材,而非透過產出檔案或傳統提示詞來完成。此設計確保了高品質、一致且可直接進行後續編輯的動態圖形產出。

相容平台~Claude Code✓Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/ChatCut-Inc/agent-plugin/tree/HEAD/claude/skills/create-motion-graphics

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

建立動態圖形

插件主機與專案

使用 chatcut MCP 伺服器以及來自使用者編輯器網址或插件專案結果的專案 ID。此插件適用於網頁編輯器,包含本地開發網址。請勿為網頁專案開啟 ChatCut Desktop 或使用 chatcut_desktop。如果 chatcut 工具無法使用,請回報連線失敗;不要將任務提交給編輯器的原生代理程式作為替代方案。

在設計前先找到 MG 參考資料

瀏覽並確認視覺方向

為求生產效率,請重複使用已核准的專案樣式或使用者提供的品牌/參考資料。當尚未完全了解其完整規格時,請使用 manage_design_style get。常規的文字/位置編輯不需要重新選擇樣式或重新掃描目錄。

當需要新的方向或使用者要求瀏覽替代方案時,請從 browse_library references: {view: "style-overview"} 開始。閱讀所有編號的聯絡表,並依 nextOffset 直到 complete。它們包含了已發布的、啟用代理程式的樣式代表,其中包含連結的現有設計樣式。list_presets 僅為舊版目錄子集;它無法取代此視覺總覽。重試失敗的頁面;回報不完整的總覽,而不是直接略過。

對於以語音為主的影片,請先理解口語內容並檢查代表性的影片影格,然後再篩選樣式。重複使用已在上下文中提供的逐字稿和影格證據。考慮主題、傳遞語氣、螢幕上使用的語言,以及影片的顏色、主體構圖和背景,並同時參考樣式預覽。

當視覺方向尚未達成一致時,請針對當前內容和影片篩選最多 6 個合適的樣式,並閱讀它們的 hero 部分。載入主機的 widget-forms 技能,並顯示實際的 heroPreview.url 圖片與簡短名稱。工具回傳的圖片是給代理程式的證據,而非使用者直接選擇的工具;純文字選項無法顯示視覺差異。保持每個選項與其參考 ID 的對應關係;使用表單的「其他」分支來表達偏好或進行另一輪選擇,不要重複選項或增加單獨的「顯示更多」選項。等待使用者做出選擇後再套用新樣式並產出 MG,除非使用者已選定方向或明確委託代理程式選擇樣式。「其他」回答不代表接受。

套用所選樣式

閱讀所選代表的 summary、hero 和 members。依照其 designStyleAction 搭配 manage_design_style 操作:

  • apply_preset:直接使用回傳的 presetId;不要為了儲存參考元資料而複製或更新預設。
  • apply:對已存在的已儲存使用者樣式,重複使用回傳的 designStyleId。
  • create:僅當獨立的參考需要一個新的使用者自訂樣式時才執行。根據所選參考定義並儲存其調色盤、字型和可重複使用的視覺規則。重複使用參考文件中記錄的調色盤;如果沒有,則從其代表性圖片中推導出連貫的調色盤。在 designSpec.referenceSources: [{id: "<reference ID>"}] 以及 thumbnailUrl 和 designSpec.images: [{role: "style reference", url: "<heroPreview.url>"}] 中都儲存個別的 heroPreview.url。使用 applyToProject: true;在修補陣列時保留現有圖片。

套用後,呼叫 get 以取得最新的完整規格和來源 ID;不要沿用先前樣式快取的規則。對於新樣式,請驗證其調色盤、字型、來源、封面和參考圖片是否已儲存。僅有來源 ID 並不能儲存圖片。 參考圖片是視覺證據,並非要嵌入的影片/背景或要複製的範例文案。

根據實際螢幕上的文字(包括雙語文字和拉丁數字),使用 fontRecommendations["zh-Hans"] 或 .en。重複使用已核准的字型方案;空的語言群組表示未解決。比對參考資料的排版特性和標題/內文層級,並檢查字符涵蓋範圍和執行階段可用性。在 designSpec.fonts 中儲存所選的字型系列/角色,並在 styleGuide 中儲存語言、粗細、斜體和所需的字軸。跨樣式的表單範例無法取代此計畫。僅在缺少字型或明確調整排版時,才閱讀字型比對;中文比對從產生的中文效果圖片開始,而非英文字母形狀。

將實例與所需的 MG 形式進行比對

使用口語內容和目標影格來決定哪些 MG 形式有用;讓參考預覽來優化這些選擇。在整個影片中保持已確認的視覺語言,併為每個所需形式找到合適的實例。除非使用者要求比較,否則自行選擇實例。不同的形式可以使用不同的實例;重複出現的元件可以重複使用已檢查過的實例。當回傳 nextReferenceSearch 時,請遵循:

  • 對於相關成員,瀏覽 kind: "instance", styleId: "<representative UUID>" 或閱讀相關的成員 ID。
  • 如果所需的形式沒有合適的成員,請透過內容/形式 query 或 facets.form 搜尋整個實例庫,省略 styleId、facets.style 和樣式名稱詞彙,即使其他形式已有相同樣式的匹配。
  • 比較封面拼貼,然後使用 parts: ["summary", "hero"] 閱讀所選 ID。為動畫加上 motion,為實作加上 code。如果程式碼支援的參考回傳了 templateInspection,請使用其唯讀呼叫來取得已儲存的屬性綱要/預設值;JSX 可以讀取 props 而不宣告其值。legacyTemplateRefs 是模板 ID:manage_template get 讀取元資料,list_assets 讀取 MG 屬性。兩者都不會套用或複製模板。inspect_asset 用於當前專案中的媒體/MG,而非目錄來源 ID。

根據固定的專案子型、調色盤、材質和實際鏡頭,調整實例的構圖、層級、間距和顯露結構。如果更廣泛的形式搜尋也沒有合適的結果,則擴充風格板塊並說明此限制。批次處理相關的詳細資訊讀取;找到一個實例並不涵蓋不相關的形式。對於分割的回應,請遵循 pendingIds;known 可能僅包含仍在上下文中的已回傳版本和部分。每個動作表是一個在真實時間戳記上的設計;蒙太奇不是一個版面,靜態圖片也無法建立動畫。

對於新的/大幅重新設計的人物談話頭頂覆蓋層,請閱讀覆蓋層構圖。僅從 materials 中匯入會出現在結果中的生產檔案;使用它們的專案素材 ID。檢視 MG 與目標影片合成的結果。

在編寫時使用參考資料

當借用其實作時,閱讀所選實例的 code,或使用 manage_template list_assets 閱讀連結的模板屬性。在下面的程式碼工作流程中將其用作參考,同時保留專案樣式。

同時檢視所選的圖片:僅有 URL、ID 或搜尋結果並不等於已檢視過的參考。保留 STYLE 證據以供外觀參考,以及跨樣式的 FORM 證據以供結構參考。如果所選的參考失敗,請重試或回報缺少證據,而不是聲稱它已被檢查。

當 ChatCut 插件任務需要以內嵌 JSX 的形式建立或修補動態圖形素材時,使用此技能。內建的 ChatCut 代理程式有自己的 motion-graphic-gen 工作流程;請勿從此插件任務切換到它。

Codex 插件動態圖形是直接編寫的。使用 create_motion_graphic_from_code 建立新的 JSX 素材,並使用 edit_asset 編輯現有的 MG JSX。此介面不提供 submit_motion_graphic;請勿將請求轉換為 Gemini 提示詞或生成簡報。如果缺少直接編寫工具,請停止並回報不可用的 ChatCut 插件工具。

透過 chatcut MCP 工具內嵌傳遞動態圖形原始碼。不要將程式碼暫存在 ChatCut 儲存庫、ai-working/、/tmp、本地 HTTP 伺服器、產生的程式碼檔案或猜測的應用程式路徑中,因為工具直接接受內嵌 JSX。

核心原則

  • 當畫布大小、fps、現有視覺語言、放置位置或時間軸衝突尚未知道時,請檢查專案狀態。
  • 在編寫 JSX 之前,在編寫程式碼之前識別所需的輸入。
  • 透過可用的內嵌程式碼素材工作流程建立或更新動態圖形素材;使用當前工具綱要來取得確切的承載形狀。
  • 當編輯需要時間軸放置時,透過時間軸編輯工作流程放置或移動素材。
  • 在結構性或視覺性變更後,重新讀取專案狀態並驗證可見影格。

編寫程式碼之前

在編寫 JSX 之前,僅識別此次編輯所需的資訊:

  • 放置位置:開始時間、持續時間、目標圖層(如果已知),以及圖形必須與之合成的目標影格。
  • 在編輯中的角色:此動態圖形在影片中執行的任務。
  • 內容:必須出現的確切文字、數字、媒體或視覺事實。
  • 時間點:內部動畫是否應與語音、音樂或視覺事件同步。
  • 視覺來源:使用者提供的樣式、專案設計樣式、品牌顏色/字型,或已核准的現有動態圖形。
  • 可編輯欄位:哪些文字、顏色、數字、布林值、圖片或影片值應成為屬性。

僅詢問那些會實質性改變結果的、缺失的高槓桿輸入。

視覺系統與放置

使用已確認的完整設計樣式和上述檢查過的參考資料。對於新的自訂方向,在批次處理前先建立一個合成的結果;已核准的方向和常規修復不需要重新確認樣式。

根據實際鏡頭和語音跨度選擇每個構圖、位置、大小和閱讀時間。保持共用的排版、調色盤、材質和動畫,同時根據內容調整參考資料的形式。僅當構圖需要時,才使用固定的左/右錨點或卡片容器。

對於有意重複出現且具有相同資訊結構的元件,請重複使用具有逐項屬性的素材。新的結構需要自己的實例參考和構圖。覆蓋層邊界應緊密包含圖形;僅對設計上明顯跨越影格的設計使用時間軸尺寸。

比對素材持續時間和內部節奏與放置的時間軸跨度。如果時間點發生重大變化,請更新 MG,而不是截斷未完成的動畫。批次處理時,並排檢閱已合成的靜止影格,在報告完成前修正碰撞、可讀性和無意的重複。

可編輯屬性

將使用者可見且可能變更的值暴露為可編輯屬性。

  • 可見文字、主色、強調色和關鍵數值都應為屬性。
  • 當使用者合理地可能變更字型時,字型選擇應為 font 屬性。
  • 圖片和影片來源必須是 image / video 屬性。
  • 程式碼鍵必須與屬性綱要鍵完全匹配。
  • 從 item.props 讀取值;不要將使用者日後合理地想要變更的可見內容硬編碼。
  • 僅對具有相同檢視者任務、資訊結構和視覺形式的有意重複元件使用項目層級屬性覆蓋。如果其中任何一項不同,請建立另一個 MG 素材,並改為共享調色盤、類型和動畫邏輯。

屬性條目應宣告穩定的鍵、使用者可見的標籤、類型和預設值。支援的屬性類型包括文字、數字、顏色、布林值、選項、字型、圖片和影片。

字型

動態圖形必須使用 ChatCut 渲染器可用的字型,以確保預覽和本地匯出保持一致。請勿依賴機器特定的系統字型,例如 STKaiti、PingFang SC、Microsoft YaHei、Arial、Helvetica、Comic Sans MS、system-ui、-apple-system 或通用 CSS 系列作為主要渲染字型;不同機器之間的可用性不同,可能導致字型回退。

在選擇或取代字型時,請呼叫 search_fonts 並逐字使用回傳的規範系列名稱作為 fontFamily 值以及匹配的 font 屬性 defaultValue。使用目錄回傳的 Google Fonts 或專案自訂字型。如果請求的機器特定字型不在目錄中,請解釋無法保證一致的本地渲染,搜尋具有類似感覺的支援替代方案,並使用它,除非使用者明確接受字型回退。

素材與構圖

一個參考實例可能描述一個由數個時間軸項目組成的完整構圖。這並不意味著一個自包含的 MG 素材。保持參考螢幕截圖、生產素材和當前專案影片的區分。

當設計將普通媒體與圖形結合時,預設使用獨立的項目:

  • 可重複使用的紙張/紋理/背景:放在構圖後方的圖片或影片項目。
  • 當前專案的照片、產品圖片或影片:其自己的媒體項目。代理程式選擇/取代、裁切、定位並對其套用支援的效果;使用者不需要手動組合圖層。
  • 排版、形狀和動畫裝飾:透明的 MG 項目。當媒體必須位於兩者之間時,將背景裝飾與前景文字分開。

在編寫之前規劃圖層順序、目標媒體矩形、開始時間/持續時間和進場時間點。在 MG 簡報/程式碼範圍中說明哪些圖層存在於 MG 之外,這樣參考資料的照片或紙張就不會再次產生。對目標媒體項目套用黑白/彩色/顆粒效果,而不是意外影響前景文字。在實際播放/匯出表面上驗證效果支援;分離圖層本身並不能證明網頁/桌面對等性。

  1. 從當前專案中的 browse_assets 重複使用素材。僅將輸出所需的生產檔案匯入「我的素材」。載入 asset-import 並使用其 import_media 工作階段/上傳輔助工具。註冊專案媒體不會將其發佈到公共資源庫。
  2. 透過 edit_item 放置正常的生產媒體,使用回傳的當前專案素材 ID。代理程式負責將參考資料中的人物、文案和資料替換為當前任務的內容。請勿使用參考資料的完成...

[此處省略]

Individual skills in this repo

This repo contains 4 individual skills — each has its own dedicated page.

相關技能