ai-cut/doc/CUT_AI_FRONTEND_SPEC.md

Cursor 開發最高準則（Nuxt 4 · Gemini Direct）

1. 前提

• 專案已存在
• 使用 Nuxt 4
• 使用真實 Gemini API
• Token 由使用者於設定頁輸入

---

2. Dependency 規則

規劃階段

• 允許討論是否需要新增 dependency
• 需說明必要性與替代方案

實作階段（預設）

• ❌ 不新增任何 dependency
• ❌ 不安裝任何套件
• ❌ 不隱性引入 library

---

3. Component 拆解原則（Token 最小化）

只允許三層：

Base

• BaseButton
• BaseInput
• BaseTextarea
• BaseCard

Feature

• ToolCard
• SceneCard
• CameraShotCard

Page

• pages/*.vue
• 僅組合元件與呼叫 composable

---

4. 拆 component 的唯一判斷

是否會被兩個以上頁面重用：

• 是 → 拆
• 否 → 留在頁面

---

5. AI 呼叫規則

• UI 不得直接呼叫 Gemini
• UI 只呼叫 composable
• Prompt 組裝只存在於 utils/ai

---

6. AI Provider 架構

Interface（/types/ai.ts）

export interface AIProvider {
  generateStoryboard(input: unknown): Promise<string>
  analyzeCamera(input: unknown): Promise<string>
  generateVideoPlan(input: unknown): Promise<string>
}

Gemini Client

• 從 localStorage 讀取 token
• 單一責任：呼叫 API

Grok Client

• 與 Gemini 相同介面
• 預設不啟用

Provider Selector

• 依設定頁選擇 provider
• 預設 Gemini

---

7. 鏡頭語言處理規則

• 不 hardcode 鏡頭語言
• 不寫 enum
• 不驗證 AI 選擇是否合理
• UI 僅顯示結構化結果

建議結構：

{
  shot: string
  movement: string
  composition: string
  lighting: string
  description: string
}

---

8. Cursor 輸出限制

• 一次只產生一個檔案
• 不跨檔案修改
• 不自動優化
• 不補未使用功能

---

9. 開發順序（不可跳）

1. Settings Page
2. Gemini Client
3. Provider Selector
4. AI 分鏡表
5. 其他工具頁