Communitygithub.com

simpletibr/simplicio-loop-marketing

一次性引導技能,將 HyperFrames (https://github.com/wesleysimplicio/hyperframes) 作為一流的影片提供者,接入行銷引擎的複製品——包括三個執行時期技能、提供者類別與模擬物件、路由矩陣列、環境變數以及 CLAUDE.md 更新。具備冪等性。當全新的複製品需要加入 HyperFrames,或在 rebase 遺漏了整合的任何部分後重新套用整合時,即可呼叫此技能。

simplicio-loop-marketing 是什麼?

此技能旨在將 HyperFrames 無縫整合至行銷引擎的複製品中,使其成為一個完整的影片提供者。它提供一個具冪等性的一次性引導流程,按照專案 CLAUDE.md 中定義的「新增提供者」三步驟合約執行。這項整合支援多種平台,包括 CLI 工具(透過 Claude Code 或類似代理框架呼叫)。技能的核心功能是自動化建立必要的執行時期技能 (hyperframes、hyperframes-cli、hyperframes-prompt-builder)、擴充提供者層(類型、路由矩陣、真實與模擬提供者類別)、更新環境變數檔案 (.env.example),以及修改 CLAUDE.md 以反映整合狀態。透過依序執行每個步驟並驗證每個成品,該技能確保整合的可靠性與冪等性。當需要將 HyperFrames 加入全新的複製品,或在 rebase 或合併後遺漏了部分成品時,應優先使用此技能,而非手動重做整合。其產出包括一個包含所有變更的功能分支、一個草稿拉取請求,以及一份詳細的報告,說明哪些檔案已被修改、跳過或驗證失敗。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/simpletibr/simplicio-loop-marketing/tree/HEAD/.skills/install-hyperframes

在你喜歡的 AI 中提問

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

說明文件

安裝 HyperFrames

一次性重現將 HyperFrames 作為影片提供者的整合,遵循 CLAUDE.md 中定義的三步驟新增提供者合約。這是一份自包含的檢查清單,列出所有必須存在的成品;會驗證每個成品,並僅建立缺少的部分。

請執行此技能,而不是從頭開始重新推導整合。它是此儲存庫中「HyperFrames 已啟用」的權威記錄。

何時呼叫

  • 全新的行銷引擎複製品尚未包含 HyperFrames 支援時。
  • 因 rebase 或合併遺漏了下列任何成品(router:check 報錯、影片路由因排版任務回退至 higgsfield,或 .skills/hyperframes*/ 目錄遺失)時。
  • 新客戶需要程式化短片 / 動態排版 / 資料視覺化輪播,且路由矩陣需要為這三種任務類型建立連線時。
  • 在培訓新操作員時,需要一個可透過單一指令執行的操作手冊,而不是閱讀三個提交記錄時。

輸入

  • repo_root:字串。行銷引擎複製品的絕對路徑。預設為 process.cwd()。
  • branch:字串,可選。要提交的分支名稱。預設為 claude/install-hyperframes。若分支不存在則建立;絕不在 main 分支上提交。
  • dry_run:布林值,可選。若為 true,則僅列印計劃的變更並退出,不實際寫入任何內容。

流程

依序執行每個步驟。每個步驟都具備冪等性——在已整合的儲存庫上重新執行時,該步驟不會產生任何效果。

步驟 1 — 前置檢查

  1. 確認 repo_root 包含 CLAUDE.md,且其中含有 ## How to Add a New Provider 這一行。若缺少則拒絕執行——這不是行銷引擎儲存庫。
  2. 確認 lib/providers/video.ts、lib/providers/matrix.ts、lib/providers/types.ts 和 lib/providers/__mocks__/video.ts 都存在。若缺少任何一個則拒絕執行。
  3. 確認目前分支不是 main。如果在 main 上,則先建立並切換到 branch。

步驟 2 — 新增三個執行時期技能

建立這三個目錄及其中的 SKILL.md 檔案。每個檔案都已存在於樹狀結構中的標準版本中——請直接從下方的參考成品集一節複製。如果某個檔案已存在且其 frontmatter 中的 name 相符,則跳過該檔案。

  • .skills/hyperframes/SKILL.md — 合成編寫規則(佈局優先於動畫、時間軸暫停並註冊在 window.__timelines 上、不使用 Math.random() 或時間相關邏輯、變數透過 data-composition-variables 宣告)。
  • .skills/hyperframes-cli/SKILL.md — npx hyperframes lint → inspect → render 開發循環。一律使用 --strict --strict-variables 進行渲染。
  • .skills/hyperframes-prompt-builder/SKILL.md — 專用提示建構器,當路由矩陣解析為 hyperframes 時,由 video-prompt-builder 呼叫;從 clients/<slug>/design.md 載入品牌代碼,根據 task_kind 選擇範本,傳回合成規格與渲染參數。

步驟 3 — 更新調度器技能

在 .skills/video-prompt-builder/SKILL.md 中:

  1. 在開頭段落和相關技能區域中,將 hyperframes-prompt-builder 加入專用技能清單。
  2. 將 task_kind 輸入列舉擴充為包含 motion_typography、data_viz_reel、programmatic_short。
  3. 在驗證環境變數的流程步驟中,將 HYPERFRAMES_ACTIVE 加入清單。
  4. 在提供者→專用技能的對應表中,加入 Hyperframes -> hyperframes-prompt-builder 這一行。
  5. 新增一個範例:一個路由到 HyperFrames、task_kind 為 programmatic_short 的每週 KPI 輪播。

跳過任何目標字串已存在的子步驟。

步驟 4 — 擴充提供者層

在 lib/providers/types.ts 中,將三個成員加入 VideoTask 聯合型別:

| "motion-typography"
| "data-viz-reel"
| "programmatic-short"

在 lib/providers/matrix.ts 中:

  • 在 EMBEDDED_DEFAULTS.video 中加入三行:motion-typography、data-viz-reel、programmatic-short —— 每個預設值均為 hyperframes。
  • 在 TASK_LABEL_MAP 中加入標籤別名:"motion typography"、"kinetic typography"、"data viz reel"、"data-viz reel"、"programmatic short"、"parametrized short"。

在 lib/providers/video.ts 中:

  • 新增一個 HyperframesVideoProvider 類別,繼承 RealVideoBase,並以 process.env.HYPERFRAMES_ACTIVE === "true" 作為守衛條件,在 realGenerate 中拋出一個「需要呼叫端環境中的本機 CLI 渲染;此為暫存」的錯誤(比照現有的 higgsfield/topview 暫存模式)。
  • 在 REAL_VIDEO_REGISTRY 中註冊 hyperframes: () => new HyperframesVideoProvider()。

在 lib/providers/__mocks__/video.ts 中:

  • 新增一個 MockHyperframesVideoProvider 類別,繼承 BaseMockVideo,name 設定為 "hyperframes"。
  • 在 MOCK_VIDEO_REGISTRY 中註冊 hyperframes: () => new MockHyperframesVideoProvider()。

步驟 5 — 更新路由矩陣檔案

在 .specs/architecture/PROVIDERS.md 中,將三行附加到影片路由表格:

| 動態排版 (Motion typography) | hyperframes | HTML/GSAP 動態文字,忠於品牌,具確定性 |
| 資料視覺化輪播 (Data viz reel) | hyperframes | 宣告式變數 → 可重新渲染的圖表(紐約時報風格) |
| 程式化短片 (Programmatic short) | hyperframes | 參數化的 HTML 合成;位元組完全相同的重新渲染 |

步驟 6 — 更新 .env.example

在 WAVESPEED_API_KEY= 之後附加:

# HyperFrames 是一個本機 HTML→MP4 渲染器;不需要 API 金鑰。
# 當 `npx hyperframes doctor` 在本機通過後,將 HYPERFRAMES_ACTIVE 設定為 true
# (需要 Node >= 22 且 FFmpeg 在 PATH 中)。詳見 https://github.com/wesleysimplicio/hyperframes
HYPERFRAMES_ACTIVE=false

步驟 7 — 更新 CLAUDE.md

  1. 在技術棧表格中,將 Video 列的提供者儲存格變更為包含 hyperframes (local HTML→MP4)。
  2. 在可用技能中,在 wavespeed-batch 之後插入三行:
    • hyperframes — 以 HTML 為真相來源的動態合成編寫。
    • hyperframes-cli — 執行 npx hyperframes lint/inspect/preview/render。
    • hyperframes-prompt-builder — 當路由矩陣解析為 hyperframes 時,由 video-prompt-builder 選用。

步驟 8 — 驗證

  1. 透過下列測試解析 .specs/architecture/PROVIDERS.md,並斷言 motion-typography、data-viz-reel、programmatic-short 都解析為 hyperframes。
  2. 執行 npm run typecheck —— 接受任何與變更無關的既有失敗(例如缺少 @types/node);若有新的 TypeScript 錯誤涉及提供者層,則判定失敗。
  3. 如果儲存庫中存在 .env,則執行 npm run router:check;否則跳過(該指令碼需要 .env,且與整合形狀無關)。
  4. 確認 git status 僅顯示預期的檔案。
node --input-type=module -e "
import { readFileSync } from 'node:fs';
const text = readFileSync('.specs/architecture/PROVIDERS.md', 'utf8');
const expected = ['motion-typography', 'data-viz-reel', 'programmatic-short'];
for (const key of expected) {
  if (!text.toLowerCase().includes(key.replace(/-/g, ' '))) {
    console.error('MISSING:', key); process.exit(1);
  }
}
console.log('PROVIDERS.md OK');
"

步驟 9 — 提交並推送

  1. 僅暫存此技能觸及的檔案。絕對不要使用 git add -A。
  2. 使用標準提交訊息進行提交:
    feat(skills): 將 HyperFrames 作為影片提供者啟用
    
    並附上描述三步驟合約執行的內文(請參考已合併的參考提交記錄中的措辭)。
  3. 推送至 origin <branch>。若該分支尚無草稿拉取請求,則建立一個。

輸出

  • branch:字串。保存提交的分支名稱。
  • pr_url:字串。草稿拉取請求的 URL(如果已建立或已存在)。
  • files_written:陣列,包含實際建立或修改的相對路徑。
  • files_skipped_idempotent:陣列,包含因已正確而跳過的相對路徑。
  • verification:{ providers_md_pass: boolean, typecheck_pass: boolean, router_check: "pass" | "skipped" | "fail" }。

不可協商的規則

  • 冪等性。 在已整合的儲存庫上重新執行時,不會觸及任何檔案。
  • 絕不在 main 上提交。 先建立功能分支;引擎的分支政策在上游強制執行。
  • 技能本體中,除了合約條款外,不得提及 hyperframes。 提供者選擇仍透過 PROVIDERS.md + lib/router.ts 進行。此技能是引導程式;執行時期的選擇仍與提供者無關。
  • 請勿編輯任何已渲染的 MP4 或 outputs/ 目錄下的任何檔案。 此技能僅變更引擎的內部機制。
  • 絕不刪除現有的 compliance-<客戶名稱> 技能或任何客戶專用的成品。 此整合僅為附加性質。

失敗模式

  • 步驟 1 前置檢查失敗(非行銷引擎儲存庫):顯示缺少的檔案並停止。不要嘗試「修復」它。
  • 某個檔案已存在但內容衝突(例如 .skills/hyperframes/SKILL.md 曾被手動編輯):與標準內容進行比對;顯示差異;在覆寫前詢問操作員。
  • npm run typecheck 報告 lib/providers/ 中有新的 TypeScript 錯誤:停止,顯示錯誤,不進行提交。
  • git push 因非網路原因失敗:停止。網路失敗則依專案的 git 政策重試(2 秒、4 秒、8 秒、16 秒的退避間隔,最多重試 4 次)。

相關技能

  • hyperframes:執行時期編寫(此技能在步驟 2 中安裝)。
  • hyperframes-cli:執行時期 lint/inspect/render(此技能在步驟 2 中安裝)。
  • hyperframes-prompt-builder:執行時期專用提示建構器(此技能在步驟 2 中安裝)。
  • video-prompt-builder:此技能在步驟 3 中更新的調度器。
  • llm-router:無關;LLM 提供者路由是另一個並行的調度器。

參考成品集

此技能所寫入的每個檔案的標準內容,都存在於 main 分支的已合併提交中:

  • 技能:.skills/hyperframes/SKILL.md、.skills/hyperframes-cli/SKILL.md、.skills/hyperframes-prompt-builder/SKILL.md
  • 提供者層:lib/providers/types.ts、lib/providers/matrix.ts、lib/providers/video.ts、lib/providers/__mocks__/video.ts
  • 路由矩陣:.specs/architecture/PROVIDERS.md
  • 環境變數:.env.example
  • 專案章程:CLAUDE.md

如有疑問,請與 origin/main 比對到已合併的參考提交,並逐字複製標準版本。請勿憑記憶重新輸入。

上游參考

Individual skills in this repo

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

相關技能