architext 0.0.2

package/dist/templates/zh-Hant/skills/archi-plan-options/SKILL.md

@@ -0,0 +1,364 @@
+---
+name: archi-plan-options
+description: Architext 架構決策選項庫。定義五個核心維度（Core Structure / Interaction Pattern / Data Flow / Error Handling / Access & Scope）的候選方案及 AI+/AI- 分析，覆蓋 Web/CLI/API/Lib/Mobile/MiniApp/Extension/Desktop/AI Agent 等專案類型。含慣例繼承規則、專案標籤路由邏輯、推薦 vs 展開判斷準則，供 /archi.plan step_2 Part 2（架構建議階段）引用。
+---
+
+# 架構決策選項庫
+
+## 系統流程定位
+
+```
+/archi.plan step_2 Part 2
+    ↓
+[本 Skill] 三步選用邏輯
+    ↓
+直接推薦行（多數維度）或 Q-table（需使用者裁決時）
+    ↓
+寫入 Task Proposal 架構建議表
+```
+
+> **Skill 的職責邊界**：
+> - 負責：各維度的候選方案內容、慣例繼承規則、推薦 vs 展開判斷
+> - 不負責：Q-table 格式規範（見 `archi-interview-protocol` Skill）、Unified Proposal 輸出格式（見 plan.md step_2）
+
+---
+
+## 選用邏輯（三步，按序執行）
+
+### Step 1 · 慣例繼承檢查
+
+讀取 `02_tech_stack.md` Section 9（專案約定）。
+
+| 情形 | 處理 |
+|:---|:---|
+| 該維度有專案慣例 | 直接繼承為推薦，來源標註 `專案慣例`，**禁展開選項表**（除非此功能有明確特殊需求須偏離慣例） |
+| 該維度無專案慣例 | 進入 Step 2 |
+
+### Step 2 · 專案標籤路由
+
+根據 step_1_load 已啟用的專案標籤（`[?UI]` / `[?Data]` / `[?CLI]` / `[?Lib]` / `[?API]` / `[?Mobile]` / `[?MiniApp]` / `[?Extension]` / `[?Desktop]` / `[?AI]`）選擇適用維度，略過不適用的維度。路由規則見各維度標題。
+
+### Step 3 · 推薦 vs 展開
+
+| 判斷條件 | 處理 |
+|:---|:---|
+| 有明顯最優方案（上下文已足夠） | 直接推薦，寫出 1-2 句理由，不展開選項表 |
+| 存在 2+ 合理選項且選擇顯著影響實現 | 展開 Q-table（格式見 `archi-interview-protocol` Skill） |
+
+**功能上下文化（Critical）**：無論推薦還是展開，須用功能設計中確認的實體名、操作名、業務流程描述，禁照搬泛化描述。
+
+---
+
+## 維度 1 · Core Structure（必用）
+
+根據專案標籤路由到對應選項庫：
+
+### [?Data] 資料模型與關係策略
+
+> 決定此功能的資料如何儲存和組織。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Flat / Single Entity | 所有資料存在單張表/單個文件中，無外鍵關聯。適合實體獨立、欄位固定、不涉及跨表關聯的場景 | 上下文集中在單檔案，AI 生成 CRUD 不需跨檔案追蹤關係，錯誤率最低 | 資料天然有從屬關係時強行平鋪會導致欄位冗餘，後續拆分重構成本高 |
+| B | 1:N Relation | 一個父實體擁有多個子實體，透過外鍵關聯。適合主從關係明確、子實體依附父實體存在的場景 | 最常見的關係模式，AI 訓練資料充足，生成 JOIN 查詢和級聯操作的準確率高 | 須同時維護兩個 Model 及關聯邏輯，AI 可能遺漏級聯刪除/更新或巢狀序列化 |
+| C | M:N Relation | 兩個實體間多對多關係，需中間表。適合兩個實體互不從屬但需要關聯的場景 | 中間表結構標準化，關係語義清晰 | 極易遺漏中間表建立和事務邏輯；中間表常需額外欄位，AI 經常忘記處理 |
+| D | Recursive / Tree | 實體自引用形成樹狀結構，適合層級深度不確定的分類、目錄、評論樹 | 單表即可表達任意深度，Schema 簡潔 | 遞迴查詢/渲染易產生無限迴圈或堆疊溢出，AI 生成的遞迴終止條件常不完整 |
+| E | JSON / EAV | 用 JSON 欄或 EAV 模式儲存動態欄位，適合 Schema 不確定、欄位因使用者/場景而異的需求 | Schema 彈性，新增欄位無需資料庫遷移 | 喪失資料庫級型別校驗和索引能力，AI 無法從 Schema 推斷欄位結構，易產生執行階段型別錯誤 |
+| F | Virtual / Computed | 資料不直接儲存，從其他欄位即時計算，適合衍生資料、統計聚合、格式化展示 | 無需資料遷移，資料始終與來源保持一致 | 計算邏輯分散在查詢層，AI 易寫出 N+1 查詢或低效聚合語句 |
+| Z | 自訂 | (請描述你的資料結構方案) | - | - |
+
+### [?CLI] 輸入/輸出與設定設計
+
+> 決定此功能如何接收輸入、以什麼形式輸出結果。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Pure Args/Flags | 所有輸入透過命令列參數傳入。適合自動化腳本呼叫、CI/CD 管道 | 輸入結構明確，AI 可直接從參數定義推導解析程式碼和說明文件 | 參數過多時使用者記憶成本高，複雜巢狀設定難以透過命令列表達 |
+| B | Interactive Prompts | 執行後透過互動式問答引導輸入。適合初始化精靈、設定產生器等需要引導的場景 | 每個 prompt 步驟獨立，AI 可按順序逐一生成處理邏輯 | 須處理 Ctrl+C 取消、回退、預設值等邊界情況，測試需 Mock stdin |
+| C | Hybrid (Args + Prompts) | 優先讀取命令列參數，缺失項才彈互動提示。適合同時服務腳本呼叫和手動操作 | 兼顧自動化與互動，是現代 CLI 的最佳實踐 | 須維護參數解析和互動提示兩套邏輯，AI 須確保兩條路徑行為一致 |
+| D | Config File | 從設定檔讀取輸入。適合參數數量多、需要版本化管理設定的場景 | 設定可用 JSON Schema 嚴格校驗，AI 可基於 Schema 生成解析程式碼 | 須處理檔案不存在、格式錯誤、Schema 版本遷移等邊界情況 |
+| E | Stdin / Pipe | 從標準輸入或管道接收資料。適合資料處理管道、與 Unix 命令組合使用 | 輸入格式可定義清晰的 Parser 契約 | 串流讀取和編碼處理易出錯，須處理空輸入和超大檔案 |
+| Z | 自訂 | (請描述你的輸入/輸出方案) | - | - |
+
+### [?Lib] 公開 API 與型別設計
+
+> 決定此功能暴露給消費者的介面形態。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Single Function | 匯出一個或少數獨立函式。適合功能單一、無狀態的工具函式 | 介面最簡，AI 生成使用範例和單元測試的準確率最高 | 功能擴展時可能導致函式簽名膨脹 |
+| B | Class / Instance | 匯出類別，消費者建立實例後呼叫方法。適合需維護內部狀態、提供多個關聯操作的模組 | 類別的 constructor + methods 結構清晰，AI 易理解物件生命週期 | 繼承層級過深增加上下文複雜度，AI 追蹤 this 繫結易出錯 |
+| C | Builder / Fluent | 透過鏈式呼叫建構設定。適合可選設定項多、需要漸進式建構的場景 | TypeScript 下鏈式呼叫可逐步收窄型別，型別安全好 | 鏈式方法的呼叫順序約束和泛型體操複雜，AI 生成型別定義易出錯 |
+| D | Config Object | 接受一個設定物件作主要輸入。適合初始化參數多且需統一管理的場景 | 設定物件可用 interface/Zod 嚴格定義，AI 從型別推斷行為非常準確 | 設定項過多時文件和校驗邏輯繁重，可選欄位的預設值合併易出錯 |
+| E | Plugin / Middleware | 核心精簡，功能透過外掛/中介軟體擴展。適合需要高度可擴展的框架級函式庫 | 核心程式碼簡單，AI 可獨立生成每個外掛 | 外掛間互動、執行順序和型別安全難以保證，AI 易生成相互衝突的外掛 |
+| Z | 自訂 | (請描述你的 API 設計方案) | - | - |
+
+### [?API] 介面契約與路由設計
+
+> 決定此功能的 API 端點結構和呼叫方式。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | RESTful CRUD | 標準 REST 資源路由。適合實體明確、操作可標準化的增刪改查場景 | REST 是最普及的 API 模式，AI 訓練資料極充足，生成路由+控制器準確率最高 | 複雜查詢和跨資源操作用純 REST 表達力有限，容易產生非標準端點 |
+| B | RPC-Style Actions | 面向操作的端點，如 `POST /send-invite`。適合業務動作不能簡單對應到 CRUD 動詞的場景 | 端點語義明確，AI 可從動作名直接推斷實現邏輯 | 缺乏統一範式，端點命名易不一致，數量膨脹後難以維護 |
+| C | GraphQL | 單端點 + Schema 查詢語言。適合前端資料需求多變、需要減少多次請求的場景 | Schema 即文件，強型別定義，前端自由組合查詢 | Resolver 的 N+1 問題和細粒度權限校驗複雜，AI 生成 DataLoader 常有快取 Bug |
+| D | Nested Sub-resource | 巢狀路由表達從屬關係，如 `GET /users/:id/posts`。適合資源間有明確父子關係的場景 | 路由結構反映資料關係，AI 可從路由推斷查詢邏輯 | 巢狀超 2 層路由冗長，權限檢查須逐級驗證父資源所有權 |
+| Z | 自訂 | (請描述你的 API 設計方案) | - | - |
+
+### [?Mobile] 導航架構策略
+
+> 決定此功能在行動端導航體系中的位置與流轉方式。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Stack Navigator | 層級式頁面堆疊，使用者進入詳情後可返回。適合操作流程有明確層級深度的場景 | 最常見的行動端導航模式，AI 生成 push/pop 準確率高 | 深層巢狀時需維護複雜的路由參數傳遞，參數型別安全易丟失 |
+| B | Tab Navigator | 底部/頂部固定標籤列，切換各功能入口。適合功能並列、使用者需頻繁切換的應用主框架 | Tab 結構固定明確，AI 可逐 Tab 獨立生成，互不干擾 | 不同 Tab 的狀態隔離與共享資料同步需額外處理，AI 易遺漏 Tab 切換時的資料刷新 |
+| C | Drawer Navigator | 側邊抽屜式導航選單。適合功能較多、不適合 Tab 展示的後台類應用 | 抽屜選單結構清晰，AI 生成列表項和路由對應準確 | 抽屜手勢與內部列表捲動手勢衝突較難處理，跨平台行為差異 AI 常忽略 |
+| D | Modal / Bottom Sheet | 強制回應頁面或底部彈出面板，不脫離當前上下文。適合快速操作、篩選、確認等次級流程 | 上下文局部化，不跳轉根頁面，AI 生成條件渲染邏輯準確 | Focus Trap、手勢關閉、鍵盤彈起適配 AI 常處理不完整；iOS/Android 行為差異多 |
+| Z | 自訂 | (請描述你的行動端導航方案) | - | - |
+
+### [?MiniApp] 頁面架構與請求策略
+
+> 決定此功能在小程式頁面體系中的組織形式和網路請求封裝方式。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Single Page | 功能集中在單個小程式頁面內完成，無跨頁跳轉。適合功能聚焦、操作步驟少的場景 | 頁面上下文集中，AI 可在單檔案內完整生成邏輯，錯誤率低 | 功能擴展時單頁邏輯膨脹，可維護性下降 |
+| B | Page + Sub-page Flow | 主頁面 + 跳轉詳情/編輯子頁面，透過 `navigateTo` 傳參。適合有明確主從關係的場景 | 頁面間職責清晰，AI 可按頁面獨立生成，上下文互不干擾 | 頁面間參數傳遞須序列化，資料量大時需用 EventBus 或全域 store，AI 易遺漏 |
+| C | Tabbar + Module | 底部 Tabbar 框架 + 各模組獨立頁面，適合功能並列的主應用框架 | Tabbar 結構穩定，AI 可模組化生成各 Tab 內容 | 跨 Tab 資料共享須全域狀態管理，小程式 store 生態較碎片，AI 方案選型易混淆 |
+| D | WebView Hybrid | 部分功能透過 WebView 內嵌 H5 頁面實作，適合複雜富文字編輯或已有 Web 資產複用 | 可複用 Web 技術堆疊，功能完整性高 | WebView 與原生通訊透過 bridge，AI 生成訊息協議易有相容性問題；受平台沙盒限制 |
+| Z | 自訂 | (請描述你的小程式頁面方案) | - | - |
+
+### [?Extension] 架構層分配策略
+
+> 決定此功能的核心邏輯部署在 Background Service Worker、Content Script 還是 Popup 層。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Background-Centric | 核心邏輯在 Background Service Worker，其他層僅做 UI 展示和訊息轉發。適合需持續執行、跨分頁共享狀態的場景 | 邏輯集中，訊息協議單向清晰，AI 可在單檔案生成主要邏輯 | Service Worker 生命週期短暫（MV3），須處理喚醒和狀態持久化 |
+| B | Content-Centric | 主要邏輯注入目標頁面的 Content Script，與頁面 DOM 深度互動。適合頁面增強、劃詞翻譯、內容修改類功能 | 可直接操作頁面 DOM，不需要訊息中轉 | 與頁面 JS 環境隔離（isolated world），須透過 window.postMessage 通訊，AI 常混淆隔離邊界 |
+| C | Popup-Centric | 主要互動和邏輯在 Popup 頁面，Background 僅做最小權限代理。適合功能簡單、點擊即用的工具型擴充 | Popup 本質是普通網頁，AI 生成 UI 程式碼與 Web 無異 | Popup 關閉時狀態丟失，須持久化到 chrome.storage；Popup 與 Background 生命週期獨立 |
+| D | Full Architecture | Background + Content + Popup 各承擔特定職責，透過訊息總線協調。適合功能複雜的綜合型擴充 | 職責分層明確，各層可獨立開發和測試 | 三層訊息協議複雜，AI 容易遺漏訊息路由或混淆發送方/接收方 |
+| Z | 自訂 | (請描述你的擴充架構方案) | - | - |
+
+### [?Desktop] 程序模型與 IPC 策略
+
+> 決定此功能的業務邏輯如何在主程序（Main）與渲染程序（Renderer）之間分配。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Main-Centric | 核心業務邏輯在主程序，渲染程序僅負責展示和使用者輸入。適合需頻繁呼叫系統 API（檔案系統、原生選單、系統通知）的場景 | 主程序邏輯集中，AI 在單處生成業務邏輯；型別透過 IPC 契約約束 | 主程序阻塞會導致整個 App 無回應；渲染程序須等待 IPC 回應，AI 易忘記非同步處理 |
+| B | Renderer-Centric | 業務邏輯主要在渲染程序，主程序僅暴露最小系統 API 代理。適合以 UI 為核心、系統呼叫較少的應用 | 渲染程序可使用瀏覽器標準 API，AI 生成程式碼與 Web 開發一致 | 系統級呼叫須透過 contextBridge 預載，AI 常忘記宣告 preload 白名單導致安全問題 |
+| C | Worker Thread | 計算密集型邏輯遷移至 Worker Thread，避免阻塞 UI 執行緒。適合檔案處理、資料轉換等重型任務 | 將重型任務與 UI 解耦，回應性好 | Worker Thread 無法直接存取 DOM 和 IPC，須透過 MessageChannel 通訊，AI 容易遺漏序列化約束 |
+| Z | 自訂 | (請描述你的桌面端程序分配方案) | - | - |
+
+### [?AI] LLM 整合與 Agent 架構策略
+
+> 決定此功能如何整合 LLM 能力、組織 Prompt 和管理 Agent 執行流程。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Direct API Call | 直接呼叫 LLM Provider API（OpenAI/Claude/Gemini 等）。適合功能簡單、無需切換 Provider 的場景 | 實作最簡，AI 生成 SDK 呼叫程式碼準確率高 | 與 Provider 強耦合；切換模型須改程式碼；串流輸出處理在各 Provider 間不統一 |
+| B | Provider Abstraction | 封裝統一 LLM 客戶端介面，底層可切換 Provider。適合需支援多模型或本地模型的場景 | 介面穩定，AI 可針對抽象層生成呼叫程式碼而無需關心底層 Provider | 抽象層設計複雜，不同 Provider 的能力差異（context window、tool calling 格式）難以完全統一 |
+| C | Tool / Function Calling | 為 LLM 定義 Tool Schema，由 LLM 決策何時呼叫。適合需 AI 主動呼叫外部能力（搜尋、程式碼執行、資料庫查詢）的場景 | Tool Schema 結構化，AI 可從型別定義生成呼叫適配程式碼 | Tool 執行錯誤的重試策略、多 Tool 並行呼叫的狀態管理，AI 容易遺漏冪等性處理 |
+| D | Multi-Agent Orchestration | 多個專職 Agent 協作完成複雜任務，含路由器/協調者角色。適合任務複雜度高、單次對話無法完成的工作流 | 各 Agent 職責單一，AI 可獨立生成每個 Agent 的 Prompt 和工具集 | Agent 間狀態傳遞、迴圈偵測、成本控制極難設計正確，AI 生成的協調邏輯容易產生無限迴圈 |
+| Z | 自訂 | (請描述你的 AI 整合方案) | - | - |
+
+---
+
+## 維度 2 · Interaction Pattern（必用）
+
+### [?UI] 展示與互動模式
+
+> 決定使用者看到什麼介面、如何操作。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | CRUD Table/List | 資料以表格或列表展示，支援篩選/排序/翻頁，點擊進入詳情。適合後台管理、資源列表 | 表格元件是 AI 訓練資料最充足的 UI 模式，生成程式碼的準確率最高 | 大資料量下需分頁+排序+多條件篩選的組合邏輯，互動狀態管理較多 |
+| B | Wizard / Stepper | 將複雜操作拆為多步頁面，帶進度條和步驟指示器。適合註冊流程、設定精靈、多步表單 | 每步狀態獨立明確，AI 可逐個生成 Step 元件 | 跨步驟資料共享/校驗複雜，AI 易遺漏步驟間狀態傳遞 |
+| C | Dashboard / Kanban | 以卡片/欄形式展示資料，可拖曳移動。適合任務管理、狀態工作流、專案看板 | 視覺直觀，每張卡片是獨立上下文單元 | 拖曳排序依賴第三方函式庫，AI 生成拖曳邏輯幻覺風險高，跨瀏覽器相容問題多 |
+| D | Modal / Drawer | 點擊列表項後彈出浮層或側邊滑出面板展示詳情/編輯。適合快速編輯不需要獨立頁面的場景 | 上下文局部化，不需要路由跳轉 | Z-index 層疊、Focus Trap、Escape 關閉、背景滾動鎖定等互動細節常出 Bug |
+| E | Infinite Scroll / Feed | 滾動到底部自動載入更多，形成無限資訊流。適合內容消費型場景 | 基本的「載入更多」邏輯簡單 | 虛擬滾動極難寫對，滾動位置恢復和快速滾動白屏 AI 很難處理好 |
+| F | Editor / Canvas | 富文字編輯區或畫布式自由操作區域。適合內容創作/視覺化編輯 | 功能上限高，使用者自由度大 | Canvas 是指令式 API，比宣告式 DOM 難生成得多；Selection API 極為複雜 |
+| Z | 自訂 | (請描述你的互動方案) | - | - |
+
+### [?CLI] 使用者互動模式
+
+> 決定使用者如何與此 CLI 功能互動、看到什麼回饋。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Silent / Batch | 無互動，純靜默執行，成功到 stdout，失敗到 stderr。適合作為腳本/管道中一環 | 實作最簡，無 I/O 副作用，測試只需斷言 stdout 輸出 | 使用者在執行過程中無法獲得進度回饋 |
+| B | Progress / Spinner | 執行期間顯示進度條或旋轉動畫，完成後輸出結果摘要。適合耗時操作 | 標準模式，clack/ora 等函式庫支援完善，幾行程式碼即可接入 | 須處理非 TTY 環境降級、終端寬度變化等邊界情況 |
+| C | Interactive Menu | 展示選單讓使用者選擇操作。適合功能入口多、使用者需瀏覽和選擇的場景 | 選單結構明確，AI 可逐個生成選項處理邏輯 | 選單層級過深體驗差，須處理不支援互動的終端回退方案 |
+| D | REPL / Shell | 進入持續互動迴圈。適合探索式工具、除錯器 | 每輪互動獨立，AI 可逐條命令處理 | 須維護會話狀態、命令歷史、Tab 補全，實作複雜度高 |
+| E | Watch / Daemon | 持續執行並監聽變化，自動觸發操作。適合開發工具、檔案同步、自動建置 | 事件驅動模型清晰，每次觸發獨立處理 | 跨平台檔案監聽相容性、防抖邏輯、優雅退出處理難點多 |
+| Z | 自訂 | (請描述你的互動方案) | - | - |
+
+### [?API] 客戶端整合模式
+
+> 決定調用方如何接入和使用此 API。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Direct HTTP Call | 客戶端直接發 HTTP 請求呼叫。最簡單直接的整合方式 | 無額外抽象層，AI 生成請求程式碼最簡單直接 | 型別安全需手動維護，介面變更時客戶端容易失同步 |
+| B | SDK / Client Lib | 提供封裝好的客戶端 SDK，調用方使用型別化方法呼叫 | 強型別安全，介面變更在編譯期發現 | 須額外維護 SDK 程式碼和版本發布，增加開發負擔 |
+| C | Code Generation | 從 OpenAPI/GraphQL Schema 自動生成客戶端程式碼和型別定義 | Schema 即契約，型別自動生成零手動維護 | 生成程式碼定制性有限，Schema 變更需重新生成並檢查相容性 |
+| D | Webhook / Event | API 透過 Webhook 回呼主動通知客戶端。適合非同步事件驅動場景 | 解耦，非同步通知無需輪詢 | Webhook 的簽名驗證、重試冪等、逾時處理 AI 容易遺漏 |
+| Z | 自訂 | (請描述你的整合方案) | - | - |
+
+### [?Lib] 消費者使用模式
+
+> 決定消費者如何使用此函式庫的功能。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Import & Call | 直接匯入函式/類別並呼叫。最直接的使用方式，零設定即可上手 | 使用方式最簡，AI 生成範例程式碼和測試準確率最高 | 功能擴展時可能需頻繁修改公開簽名，影響下游消費者 |
+| B | Register & Use | 先註冊設定再使用，適合需要初始化和生命週期管理的函式庫 | 初始化與使用階段分離，AI 可分階段生成邏輯 | 註冊時序和生命週期約束需清晰文件，AI 可能生成錯誤呼叫順序 |
+| C | Decorator / Annotation | 透過裝飾器宣告行為。適合框架級函式庫，宣告式設定減少樣板程式碼 | 宣告式程式碼簡潔，意圖清晰 | TS 裝飾器提案仍在演進，AI 可能混淆舊版和新版語法 |
+| Z | 自訂 | (請描述消費者的使用方式) | - | - |
+
+### [?Mobile] 行動端互動模式
+
+> 決定使用者在行動裝置上如何操作此功能、看到何種回饋。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Standard List / Card | 資料以列表或卡片展示，點擊進入詳情。適合內容瀏覽和管理類功能 | 與 Web 端 CRUD Table 類似，AI 生成 FlatList/ScrollView 準確率高 | 大列表須 FlatList 虛擬化；下拉刷新、上拉載入 AI 常遺漏邊界處理 |
+| B | Form / Wizard | 多步表單或引導式輸入。適合註冊、建立流程 | 每步表單獨立，AI 可逐步生成欄位和校驗 | 鍵盤彈起導致視圖遮擋須處理 KeyboardAvoidingView；步驟間資料共享需狀態提升 |
+| C | Gesture-Driven | 依賴滑動、長按等手勢操作，如左划刪除、拖曳排序。適合高頻操作的輕量互動 | 手勢語義直觀，使用者操作流暢 | 手勢衝突（內部捲動 vs 外部手勢）極難除錯；跨平台手勢函式庫 API 差異大，AI 易混淆 |
+| D | Bottom Sheet / Action Sheet | 點擊觸發底部滑出面板或操作選單。適合次級操作、篩選、快速選擇 | 無需路由跳轉，上下文局部化 | 手勢關閉、鍵盤配合、巢狀捲動須精細處理；iOS/Android 行為差異 AI 常忽略 |
+| Z | 自訂 | (請描述你的行動端互動方案) | - | - |
+
+### [?MiniApp] 小程式互動模式
+
+> 決定使用者在小程式內如何與此功能互動。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Native Components | 使用平台原生元件（button、input、scroll-view），遵循平台 UI 規範。適合大部分標準功能 | 原生元件有平台保障，AI 生成標準小程式程式碼準確率高 | 原生元件樣式定制受限，CSS 支援不如 Web 完整 |
+| B | Custom Component | 封裝自訂元件，提取可複用 UI 單元。適合樣式定制要求高或多處複用的場景 | 元件化提高上下文局部性，AI 可獨立生成每個元件 | 小程式自訂元件的 slot、properties、triggerEvent 與 Web 元件有細節差異，AI 易混淆 |
+| C | Half-Screen / Full-Screen Popup | 半屏彈窗或全屏覆蓋層。適合詳情查看、確認操作、篩選面板 | 彈窗結構明確，AI 生成條件渲染邏輯準確 | z-index 層級管理和動畫過渡須注意微信小程式的渲染層特殊性 |
+| Z | 自訂 | (請描述你的小程式互動方案) | - | - |
+
+### [?Extension] 擴充互動入口模式
+
+> 決定使用者透過何種入口與擴充功能互動。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Browser Action Popup | 點擊擴充圖示彈出小型 Popup 視窗。適合設定面板、快速操作、狀態展示 | Popup 是獨立 HTML 頁面，AI 生成程式碼與普通 Web 無異 | Popup 寬高有限（約 600×600px），關閉即銷毀，須將資料持久化到 chrome.storage |
+| B | Context Menu | 右鍵選單注入選項。適合對選取文字/連結/圖片的快速處理 | 選單項目註冊邏輯簡單，AI 一次生成即可 | 選單顯示條件須精確宣告；操作結果須透過訊息通知使用者 |
+| C | Content Injection | 在目標頁面注入按鈕、浮標、工具列等 UI 元素。適合頁面增強類功能 | 注入 UI 的 HTML/CSS 自成體系，AI 可獨立生成 | 須處理頁面樣式污染（使用 Shadow DOM 隔離）；目標頁面 DOM 變化時注入點可能失效 |
+| D | Side Panel | 瀏覽器側邊欄（Chrome sidePanel API），常駐於瀏覽器右側。適合持續使用的工具面板 | 有完整頁面空間，與瀏覽器原生整合，UX 自然 | sidePanel API 較新，跨瀏覽器相容性有限；須使用者主動開啟 |
+| Z | 自訂 | (請描述你的擴充互動方案) | - | - |
+
+### [?Desktop] 桌面端互動模式
+
+> 決定使用者如何與此桌面應用功能互動，以及使用哪種系統級 UI 範式。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Window-Based UI | 標準應用視窗，UI 與 Web App 相近。適合功能複雜、需要較大操作空間的應用 | AI 生成的 Web UI 程式碼可直接複用；桌面端增量僅在於 IPC 呼叫 | 須處理多視窗管理、視窗尺寸記憶等桌面特有細節 |
+| B | Tray / Menu Bar App | 常駐系統托盤或 macOS 選單列，點擊彈出小型懸浮視窗。適合後台服務、快速查看類工具 | 互動面小且固定，AI 可在極小上下文內完成 | 托盤圖示隨系統主題切換須維護兩套圖示；懸浮視窗尺寸和定位須精確計算 |
+| C | Global Hotkey Trigger | 全域快速鍵喚起，跨應用使用。適合 Spotlight 類快速啟動工具、剪貼簿管理器 | 使用者無需切換焦點，體驗流暢 | 註冊全域快速鍵須系統權限；快速鍵衝突難以預測；macOS/Windows 註冊 API 不同 |
+| D | Native Dialogs | 使用系統原生檔案選擇器、對話方塊、通知。適合檔案操作、系統級提醒場景 | 原生對話方塊零樣式維護成本，使用者熟悉 | 原生對話方塊 API 在 Electron/Tauri 中呼叫方式不同，須查閱文件確認 |
+| Z | 自訂 | (請描述你的桌面端互動方案) | - | - |
+
+### [?AI] Agent 互動輸出模式
+
+> 決定使用者如何觸發 AI 能力，以及如何接收 AI 的輸出結果。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Chat Interface | 對話式輸入/輸出，支援多輪上下文。適合開放式問答、輔助創作類功能 | 對話結構線性，AI 可按訊息對生成處理邏輯 | 多輪上下文的 Token 管理（裁剪/摘要）易被忽略，超出上下文視窗時回應品質驟降 |
+| B | Command-Driven | 使用者發出結構化指令，AI 執行並返回結果。適合 AI 輔助完成特定任務（程式碼生成、文件整理）的場景 | 指令格式可 Schema 化，AI 生成解析和執行邏輯準確 | 須處理指令解析失敗、參數缺失的降級策略；使用者須學習指令語法 |
+| C | Streaming Output | AI 輸出以串流形式逐步渲染，使用者即時看到生成過程。適合生成內容較長的場景 | 串流 API 模式標準（SSE/Stream），主流 SDK 均支援 | 串流中斷的重試和已渲染內容的回滾較複雜；Markdown 串流渲染的跳脫 Bug AI 常處理不好 |
+| D | Autonomous Agent | AI 自主規劃並執行多步任務，最終返回完整結果。適合複雜工作流自動化 | 無需使用者逐步介入，端到端完成任務 | 中間步驟的可觀測性（進度展示）、任務失敗的部分回滾、成本控制極難正確實作 |
+| Z | 自訂 | (請描述你的 AI 互動輸出方案) | - | - |
+
+---
+
+## 維度 3 · Data Flow
+
+**適用條件**: 專案含 `[?UI+Data]` 或 `[?UI+API]` 標籤時適用；純 `[?CLI]`/`[?Lib]` 略過。
+**慣例繼承**: `02_tech_stack.md` §9 Data Flow 有值 → 自動繼承，不展開選項表。僅當此功能需偏離專案預設時才展開。
+
+### [?UI] 狀態同步與資料流
+
+> 資料如何在前端介面和後端之間流轉和同步。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Standard Request | 使用者操作→發請求→等回應→更新介面。適合大多數標準 CRUD 操作 | 原子操作，無狀態，AI 生成 fetch + loading/error 狀態處理最可靠 | 每次操作須等網路往返，操作頻繁時體感較慢 |
+| B | Optimistic UI | 使用者操作後立即更新介面（假設成功），後台同步發請求。適合操作頻繁且大概率成功的場景 | 使用者體感極快，互動無卡頓 | 回滾邏輯（伺服端返回失敗時恢復原狀態）常被遺忘，AI 容易只寫樂觀更新不寫回滾 |
+| C | Polling / SWR | 定期自動重新獲取資料，或視窗聚焦時刷新。適合資料需要準即時但不必毫秒級更新的場景 | React Query/SWR 等函式庫封裝完善，AI 只需設定 staleTime/refetchInterval | 輪詢間隔和快取失效策略需平衡，不當設定會造成無意義的請求風暴 |
+| D | Realtime (Socket/SSE) | 伺服端主動推送資料到客戶端。適合線上聊天、即時協作、股票行情 | 延遲最低，資料即時同步，使用者體驗最好 | 斷線重連、心跳保活、訊息順序保證極難正確實作，AI 生成的 WebSocket 程式碼常有連線洩漏 |
+| E | Local-First / Offline | 資料優先存本地，連網時與伺服端同步。適合弱網/離線必須可用的場景 | 離線可用，不受網路影響 | 衝突解決演算法（CRDT/OT）是高階問題，AI 難以正確實作多端並行衝突合併 |
+| F | Background Job | 使用者觸發後立即返回，後台非同步完成。適合耗時操作（批次處理、檔案生成） | 主執行緒解耦，API 回應快 | 須額外實作任務佇列、狀態查詢和完成通知機制 |
+| Z | 自訂 | (請描述你的資料流方案) | - | - |
+
+---
+
+## 維度 4 · Error Handling（慣例繼承）
+
+**慣例繼承**: `02_tech_stack.md` §9 Error Handling 已確立專案級策略 → 自動繼承，不展開選項表。
+僅當此功能有**專案慣例未覆蓋的特殊異常場景**時，才額外補充（如此功能需 Undo/Redo 但專案慣例只有 Fail Fast）。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Fail Fast / Notify | 遇到錯誤立即中止並通知使用者，不嘗試恢復。適合大多數非關鍵操作的預設策略 | 實作最簡單（一行 throw + 全域錯誤處理），AI 幾乎不會寫錯 | 使用者體驗偏生硬，頻繁操作失敗時通知轟炸 |
+| B | Form Validation | 使用者提交前進行欄位級/表單級校驗，阻止非法輸入到達後端 | Zod/Yup Schema 可同時用於校驗和型別推斷，AI 從 Schema 生成 UI 回饋準確 | 複雜校驗規則（非同步唯一性、跨欄位依賴）的正規表示式和時序 AI 容易寫錯 |
+| C | Retry / Recovery | 操作失敗後自動重試或提供手動重試按鈕。適合網路不穩定或外部服務間歇性故障的場景 | 重試邏輯可封裝為通用工具函式，複用度高 | 須確保操作冪等（重複執行不產生副作用），AI 難以驗證冪等性 |
+| D | Fallback / Skeleton | 載入失敗或資料為空時顯示降級 UI（骨架屏、空狀態提示）而非白屏 | 骨架屏是標準 UI 模式，AI 生成準確率高 | 須為每個狀態（loading/empty/error）維護並行 UI 結構，元件數量翻倍 |
+| E | Draft / Auto-save | 使用者編輯過程中自動定期儲存草稿，防止意外遺失資料 | 儲存邏輯可抽象為通用 Hook/工具函式 | 儲存節流（debounce/throttle）、衝突偵測須仔細處理 |
+| F | Undo / Redo | 操作後支援撤銷/重做。適合使用者可能誤操作且後果較嚴重的場景 | 提升使用者信心，降低操作焦慮 | 狀態快照和歷史堆疊管理邏輯複雜，AI 生成 undo 堆疊經常有記憶體洩漏或狀態不一致 |
+| Z | 自訂 | (請描述你的錯誤處理方案) | - | - |
+
+---
+
+## 維度 5 · Access & Scope
+
+**適用條件**: 專案含 `[?Web/API]` 標籤時提問權限控制；含 `[?MiniApp]` 標籤時提問小程式授權模式；含 `[?Lib]` 標籤時提問封裝策略；純 `[?CLI]` 通常略過。
+**慣例繼承**: `02_tech_stack.md` §9 Auth & Access 有值 → 認證**機制**繼承（如 JWT/RBAC），但**權限級別**仍為功能級決策（如某功能 Public vs Owner Only）。
+
+### [?Web/API] 權限控制
+
+> 誰能執行此功能的操作、看到什麼資料。認證機制繼承專案慣例，此處僅決定此功能的權限級別。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Public | 完全公開，無需登入即可存取。適合面向匿名使用者的公開內容 | 無需鑑權中介軟體，API 層最簡 | 須額外考慮限流防濫用，公開介面易被爬蟲和惡意呼叫 |
+| B | Authenticated | 僅登入使用者可存取。適合個人首頁、訂單列表等需身份驗證的場景 | 標準 JWT/Session 中介軟體即可實作，AI 生成成熟度高 | 須處理 token 過期刷新、多端登入踢出等會話管理邏輯 |
+| C | Owner Only | 僅資源建立者可操作。適合「只有自己能編輯自己的內容」的場景 | 簡單的所有權檢查，一行程式碼即可實作 | 如果資源可轉讓或有代理操作場景，簡單 owner 檢查不夠用 |
+| D | Role Based (RBAC) | 按角色劃分權限，如 admin/editor/viewer。適合後台管理、多角色協作系統 | 權限規則明確可列舉，AI 可基於角色矩陣生成守衛邏輯 | 守衛邏輯分散在每個端點，上下文負載高；角色巢狀時權限繼承複雜 |
+| E | Team / Shared | 團隊/組織成員可存取。適合協作場景、多租戶系統 | 權限邊界以團隊為單位，粒度適中 | 須查詢團隊成員關係表，涉及複雜 JOIN；跨團隊共享進一步複雜化 |
+| F | Tier / Subscription | 按付費等級限制功能。適合 SaaS 產品的分級功能 | 規則可設定化，與業務邏輯解耦 | Mock 支付狀態和計費邏輯困難，測試需要大量 fixture 資料 |
+| Z | 自訂 | (請描述你的權限方案) | - | - |
+
+### [?MiniApp] 小程式授權模式
+
+> 決定此功能需要哪種平台授權級別。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Anonymous | 無需授權，匿名存取。適合瀏覽型功能 | 無授權流程，AI 生成最簡 | 須額外考慮限流防刷，無使用者身份時無法關聯歷史資料 |
+| B | Platform Auth (openid) | 靜默授權獲取 openid，不彈授權對話方塊。適合大多數需要區分使用者但不需要完整資料的場景 | 無需使用者操作，code2session 流程標準，AI 生成準確率高 | openid 僅在同一小程式/同一平台下唯一，跨平台或跨小程式須用 unionid |
+| C | Phone Binding | 對話方塊授權獲取手機號，綁定到業務帳號。適合需要真實身份關聯或與已有帳號系統對接的場景 | 平台處理真實性驗證，業務側僅需儲存關聯關係 | 手機號授權按鈕有嚴格 UI 限制（須為 button 元件，禁 JS 觸發），AI 容易生成不符合規範的觸發方式 |
+| D | Full Profile Auth | 請求完整使用者資料授權（暱稱/頭像）。適合社交類功能或需要展示使用者資訊的場景 | 一次授權獲取完整使用者資訊 | 微信已於 2022 年收緊此授權，須用新版 getUserProfile API，舊版 getUserInfo 已廢棄，AI 訓練資料中舊版程式碼較多易混淆 |
+| Z | 自訂 | (請描述你的小程式授權方案) | - | - |
+
+### [?Lib] 封裝與可見性
+
+> 此功能的程式碼如何組織封裝，對消費者暴露什麼。
+
+| ID | 選項 | 說明 | AI+ | AI- |
+|:---|:---|:---|:---|:---|
+| A | Full Public | 所有功能和型別全部公開匯出。適合透明度高的小型工具函式庫 | AI 無需猜測哪些是公開 API，所有型別都可追溯 | 公開面過大，任何內部重構都可能是 breaking change |
+| B | Facade / Entry Point | 透過單一入口檔案（index.ts）精選匯出公共 API，內部實作不直接暴露 | 公共面小且明確，AI 從 index.ts 即可理解全部可用 API | 須持續維護匯出列表，新功能須顯式加入到 facade |
+| C | Internal / Private | 僅暴露最小公共介面，大量實作標記為 internal。適合核心函式庫、安全敏感模組 | 最小公開面，breaking change 風險最低 | AI 需要修改 internal 程式碼時缺乏上下文，須頻繁閱讀原始碼 |
+| Z | 自訂 | (請描述你的封裝策略) | - | - |
+
+---
+
+> **中間產物**：此 Skill 為子程序，產出推薦行或 Q-table 後控制權交還 `/archi.plan` step_2，由調用方組裝進 Task Proposal 的架構建議表。