Communitygithub.com

Devin-AXIS/iPolloWork

開發或更新 iPolloWork Video 的可重用視覺元件,包括地圖、圖表、排行榜、圖解、開場與結尾。遵循元件撰寫規則、清單、可編輯變數、共用資料表單、繼承設計主題、AI 編輯槽與可搜尋 HyperFrames 時間軸。不用於產出完整影片、製作完整專案範本或封裝 DeepSeek 主機外掛。

iPolloWork 是什麼?

此技能旨在引導 AI 代理(如 Claude Code、Cursor)在 iPolloWork 專案中開發或更新可重用視覺元件。它強調整合至 HyperFrames 生態系,確保元件能透過共用表單調整、自動繼承主題,並提供 AI 編輯槽以利後續加工。技能支援地圖、圖表等多種元件類型,並提供清晰的規範,包括變數宣告、資料結構、動畫時間線與 AI 加工空間。開發者需遵循最小化交付結構,僅在必要時新增檔案,並善用既有主題變數與 GSAP 動畫庫。最終交付需通過多項驗收測試,包含畫面一致性、時間軸操作及多實例隔離。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Devin-AXIS/iPolloWork/tree/HEAD/.codex/skills/ipollowork-video-component-authoring

在你喜歡的 AI 中提問

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

說明文件

iPolloWork 視頻元件開發規範

交付的是能放進影片、透過共用表單調整、跟隨專案主題、可由 AI 加工的元件。不要為一個元件另做編輯器、參數面板、渲染器或主機外掛。

1. 開始前:以當前程式碼契約為準

在 iPolloWork 倉庫根目錄閱讀 AGENTS.md 和維護性規範。先找同類元件,再選擇擴充還是新增。以下路徑均相對倉庫根目錄:

  • vendor/hyperframes/registry/blocks/world-map/:地圖、主題繼承、結構化資料的參考。
  • vendor/hyperframes/registry/blocks/metric-signal/:資料展示及可選動畫配方的參考。
  • vendor/hyperframes/packages/core/src/registry/types.ts:元件分類及 manifest 契約。
  • vendor/hyperframes/packages/core/src/registry/componentData.ts:共用資料結構及解析規則。
  • vendor/hyperframes/packages/core/schemas/registry-item.json、packages/types/src/hyperframes.ts:註冊項和主機校驗契約。
  • vendor/hyperframes/packages/studio/src/utils/blockInstaller.ts:真實安裝、主題與變數接入方式。

不要複製這些 schema 或建立另一套資料協議。規範與程式碼不一致時,先核對當前消費者,不用舊範例猜測介面。

2. 最小交付結構

通常只需在 vendor/hyperframes/registry/blocks/<slug>/ 放置:

registry-item.json       # 元資訊、變數、分類、檔案和能力聲明
<slug>.html              # 畫面與動畫

確有需要再加本地圖片、字型、資料或預覽檔案;安裝所需檔案必須在 files 中聲明,路徑保持包內相對路徑。註冊到現有 vendor/hyperframes/registry/registry.json,不另建元件目錄服務。

產品裡統稱「元件」,但底層類型要準確:有獨立畫布和時長的地圖、排行榜等通常是 hyperframes:block;注入已有畫面的片段才是 hyperframes:component。完整專案範本屬於另一種交付,不混用。

3. 變數:少而有用,表單共用

  • 在 manifest 的 variables 聲明穩定的 id、可理解的 label、類型及預設值,與 HTML 的 data-composition-variables 保持一致。
  • 沿用現有 string / number / color / boolean / enum 類型;數字給合理範圍,列舉給選項,長文字給長度約束。不要擅自增加物件類型。
  • 只暴露內容、資料、高亮、必要的佈局等使用者決策;不要把每個 CSS 數值都變成參數。顏色預設來自主題,不能靠使用者逐項配色才能使用。
  • update: live 僅用於能即時更新的參數;改變結構或動畫時按現有機制使用 rebuild / reload,聲明必須與實際行為一致。
  • 接入現有變數更新機制,更新後 DOM 和動畫都應反映新值,並保持主機當前播放位置。不得只更改文字而讓時間線仍指向舊元素。
  • 使用共用變數表單和資料表格,不給單個元件新寫一套面板。motionCueTimes、motionStyle 等系統控制欄位不當作普通使用者參數。

4. 資料:給 AI 結構,給使用者表格

地圖、路線、圖表、排行榜等資料元件使用 visualComponent.data,宣告列、語義、行標識、行數限制和綁定。沿用已有 category-value / region-value / point-value / route-value / series-value,選擇真正匹配資料的類型。

AI 面對的標準資料是:

{
  "version": 1,
  "kind": "region-value",
  "rows": [
    { "region": "China", "value": 96 },
    { "region": "Japan", "value": 77 }
  ]
}

列名由該元件的 columns 決定,不是所有元件固定使用 region。rowId 穩定且唯一,數字保持數字類型;單位、精度、高亮和替換/覆蓋語義按現有契約聲明。

binding.variable 必須對應真實變數。底層可以使用已有 json / key-value-list / route-value-list / label-detail-list 編碼,但由共用適配層轉換;不要求使用者手寫逗號、冒號等字串。不要另設一份互不同步的 JSON 狀態。非法資料給明確提示,不靜默丟行或生成虛構數值。

5. 主題與分類

  • 聲明 visualComponent.version: 1、themeMode: inherit,按能力填寫 surfaces;首選 video,未驗證前不要聲稱支援 PPT 或網頁。
  • 分類沿用當前 VISUAL_COMPONENT_CATEGORIES,例如地圖 maps、資料 data、架構/金字塔 diagrams。開頭、結尾還可用已有 librarySection 定位;不要另造一套分類樹。
  • 使用現有主題變數,例如 --ipw-color-bg、--ipw-color-surface、--ipw-color-text、--ipw-color-primary、--ipw-color-border、--ipw-font-display、--ipw-font-body、--ipw-card-radius。
  • 允許獨立預覽的預設回退值,但不能覆蓋主機傳入的主題。主題切換後背景、文字、圖形、邊框和字型應協調變化;資料的語義色例外需有明確理由。
  • 保持層級清楚、留白合理、中文可讀。必要時用剋制的漸變或玻璃質感,不以特效代替資訊表達。

6. 動畫與時間線

  • 預設 HTML + CSS + GSAP;優先複用現有圖形及本地 SVG。只有明確需要真實 3D 時才考慮 Three.js,不為簡單地圖增加重型依賴。
  • 沿用現有 composition 根節點、尺寸、時長和安裝機制,註冊到 window.__timelines[compositionId] 的暫停 GSAP 時間線,由 HyperFrames 控制播放、暫停與 seek。
  • 每個實例的選擇器、狀態和時間線只影響自己。重建時清理舊動畫,不覆蓋其他實例。
  • 同一時刻必須得到同一畫面:不要用獨立計時器、自動播放迴圈、未固定的隨機數或 CSS 自執行動畫驅動關鍵內容。真實圖片、音影片遵循現有媒體時間同步方式。
  • 動畫服務於講解順序:明確出現、強調、停留、退出;文字和資料留足閱讀時間。避免所有元件同一種入場,也避免為了炫技持續運動。
  • 普通元件不強制增加 motionRecipe。需要讓 AI 依照旁白呼叫動畫配方時,才沿用已支援的配方契約;事件、cue 綁定和實際元素一致,容量與文字限制有真實依據,不偽造配音時間。

7. AI 加工空間

用 visualComponent.ai.slots 宣告穩定的可編輯區域,並在 HTML 對應位置添加 data-ipw-ai-slot。instructions 簡要說明用途、輸入規則和需要保留的結構。

支援 AI 取代內容、調整佈局、縮小地圖並在旁邊加說明等局部加工;保持變數 ID、資料綁定、主題繼承及時間線接入不變。不強制所有加工都變成表單參數,也不為 AI 再維護一份畫面。

外部文字按文字處理,不拼入可執行 HTML;不執行輸入資料中的腳本,不嵌入金鑰。引用地圖、字型、圖片等資源保留來源和授權,缺少素材時明確說明,不暗中聯網替換。

8. 驗收與交付

  1. manifest、HTML 變數、AI slots、資料綁定及安裝路徑一致,通過當前倉庫對應校驗和受影響的測試。
  2. 在現有 Studio 安裝元件;共用表單能修改實際畫面,資料表格能增刪和編輯合法行。
  3. 檢查預設、邊界、空值、長中文、錯誤資料和兩種主題;多實例互不影響。
  4. 檢查從頭播放、中間 seek、拖回起點、參數更新後的 seek;畫面與時間線一致。
  5. 用真實素材導出一段短影片,確認瀏覽器預覽與輸出一致;不能僅憑截圖聲稱通過。
  6. 交付元件檔案、必要資源與來源、參數/資料範例、實際測試結果和未驗證項。不複製 Studio,不改現有範本行為,不殘留替代實作。

本規範只指導元件開發。發佈 npm、修改主機外掛、提交 PR 或上傳元件市集需依使用者授權及現有發佈流程另行處理。

Individual skills in this repo

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

Devin-AXIS/iPolloWork

Create deterministic animation and transitions for the active iPollo Video project.

Devin-AXIS/iPolloWork

Inspect, validate, preview, and render the active iPollo Video project with its bundled HyperFrames CLI.

Devin-AXIS/iPolloWork

Apply the core composition, timing, media, and determinism contract used by iPollo Video.

Devin-AXIS/iPolloWork

Plan visual direction, typography, pacing, audio, and composition for iPollo Video projects.

Devin-AXIS/iPolloWork

Build seek-safe keyframe animation for the active iPollo Video timeline.

Devin-AXIS/iPolloWork

Reuse approved HyperFrames blocks and components inside the active iPollo Video project.

Devin-AXIS/iPolloWork

Route video creation and editing through the active iPollo Video project and its built-in HyperFrames runtime.

Devin-AXIS/iPolloWork

Create or edit the active iPolloWork video's visual assets, installed recipes, editable composition and seek-safe motion; use for assembly or local picture/text/theme changes.

Devin-AXIS/iPolloWork

Add or revise music, sound effects and their mix in the active iPolloWork video, using authorized sources, real editable tracks and measured event cues.

Devin-AXIS/iPolloWork

Write or revise the active iPolloWork video's native STORYBOARD.md, with source coverage, content-led sequence and provisional timing; use for script-only work.

Devin-AXIS/iPolloWork

Route the active iPolloWork video request to its current storyboard, compose, voiceover or soundtrack work, preserving the client-owned delivery flow.

Devin-AXIS/iPolloWork

Add or revise scene-bound narration or speech-linked captions in the active iPolloWork video using actual voice settings, measured audio and alignment.

Devin-AXIS/iPolloWork

Create product launch and promotional videos through the active iPollo Video workflow.

Devin-AXIS/iPolloWork

Translates Figma motion and animations into production-ready application code. Use when implementing animation/motion from a Figma design — user mentions "implement this motion", "add animation from Figma", "animate this component", provides a Figma URL whose node is animated, or when `get_design_context` returns motion data or instructs you to call `get_motion_context`.

Devin-AXIS/iPolloWork

Motion / animation context for the `use_figma` MCP tool — animating Figma nodes via manual keyframes, animation styles, easing, and timeline duration. Load alongside figma-use whenever a task involves adding, editing, or inspecting animation on a node.

Devin-AXIS/iPolloWork

Plan and create short videos using the installed short-video-studio workspace app. Manage its creative canvas, scripts, storyboards, characters and local assets, generate images or video through connected Work channels, and hand off editable tracks to Work Video Studio.

Devin-AXIS/iPolloWork

Find, generate, process, and reuse media through the active iPollo Video session's media services.

相關技能