Modern Vue 3 & Pinia 開發專家 (neo-vue)

本技能為 Agent 提供 Vue 3 (Composition API) 與 Pinia 狀態管理的開發與審查指南。它協助產出符合 Vue Style Guide 優先級 A/B 規則的程式碼，避開常見響應式陷阱，並生成一致、強型別的單一檔案元件（SFC）。

Gotchas

• 解構 reactive 物件導致響應性丟失：禁止直接解構 props 或由 reactive() 定義的物件（例如：const { name } = props 或 const { x } = state），這會徹底失去 Vue 響應式追蹤！
• 防錯機制：必須使用 toRefs(props) 或 toRef(props, 'name') 來保持其響應性。
• 解構 Pinia Store 導致狀態響應性丟失：直接解構 Pinia store 的 state（如 const { user } = useAuthStore()）會使 state 失去雙向響應！
• 防錯機制：必須使用 storeToRefs(store) 來解構 state；而 action 則可以直接正常解構。
• v-model 手動繁瑣綁定：在 Vue 3.4 之前，自定義雙向綁定需要手動宣告 modelValue 屬性並觸發 update:modelValue 事件，容易寫錯。
• 防錯機制：在 Vue 3.4+ 專案中，優先使用 defineModel() 巨集宣告雙向綁定，降低屬性與事件不一致的風險。
• v-if 與 v-for 在同一節點混用：在 Vue 3 中，v-if 的優先級高於 v-for，這意味著 v-if 的條件判斷無法存取到 v-for 迴圈中的變數，會直接導致編譯或執行期報錯！
• 防錯機制：永遠使用 <template> 標籤包裹 v-for，再於內部子節點使用 v-if，或者預先使用 computed 計算屬性對陣列進行過濾。

Workflow Checklist

Progress:

• [ ] 步驟 1：感知專案環境與依賴 (Perceive Setup & Tooling)
• [ ] 步驟 2：載入編碼規範與踩坑指南 (Load Guides & Best Practices)
• [ ] 步驟 3：架構推理與響應式規劃 (Reasoning & Architecture)
• [ ] 步驟 4：套用範本生成一致的程式碼 (Generate SFC & Stores)
• [ ] 步驟 5：程式碼健檢與自我校對 (Code Quality Review)

Detailed Guidelines

步驟 1 — 感知專案環境與依賴 (Perceive)

1. 檢查依賴配置：讀取 package.json，確定 Vue 版本（確認為 Vue 3.x）以及是否安裝了 pinia、vue-router。
2. 識別建置工具與語言：確認是否為 Vite 專案，以及是否啟用了 TypeScript（lang="ts"）與 Scoped CSS。

步驟 2 — 載入編碼規範與踩坑指南 (Reason)

在進行 Vue 3 開發或審查前，必須動態載入深度知識庫：

1. 讀取 references/coding-style.md 以確認組件命名（必須為多字詞 PascalCase）、屬性定義等官方優先級規範。
2. 讀取 references/anti-patterns.md 以避開 props mutation、computed 副作用等反模式。
3. 讀取 references/patterns.md 以獲得 Composables 的合理拆分與 Pinia Setup Stores 的架構設計。

步驟 3 — 架構推理與響應式規劃 (Reason)

在編寫程式碼前，先思考以下設計：

1. Reactivity 選擇：除非是多個屬性需要高度關聯的複雜物件，否則優先使用 `ref()` 而不是 reactive()，以確保存取 .value 的一致性並避免解構失活。
2. 狀態下沉：評估狀態是屬於組件局部狀態（用 ref）還是全局狀態（用 Pinia Setup Store）。

步驟 4 — 套用範本生成一致的程式碼 (Act)

1. SFC 結構：新建立的元件必須使用 <script setup> 語法，並依專案設定優先加入 lang="ts"。
2. 套用範本：讀取並參考 assets/Vue3SFCComponentTemplate.vue 作為標準 Vue 3 元件的排版範例。
3. 強制語言與風格：所有程式碼註解、說明必須使用 Traditional Chinese (Taiwan)。專用術語需對齊（例如：元件、屬性、狀態管理、響應式、雙向綁定、計算屬性）。

步驟 5 — 程式碼健檢與自我校對 (Act)

1. 確認沒有在 computed 中做任何 state 修改或 API 調用等 Side Effects。
2. 確認沒有直接對 props 進行賦值與修改。
3. 確認 v-for 的 key 綁定使用了穩定的唯一 ID，而不是陣列索引 index。

Output Templates

生成新元件時，依照以下一致結構輸出；更多實作細節請參閱 assets/Vue3SFCComponentTemplate.vue：

<template>
  <div class="vue-expert-component">
    <!-- 模板內容 -->
  </div>
</template>

<script setup lang="ts">
import { ref, computed } from 'vue';

// 1. 定義屬性與事件 (Props, Emits, Models)
const props = defineProps<{
  title: string;
}>();

const emit = defineEmits<{
  (e: 'change', value: string): void;
}>();

// Vue 3.4+ 雙向綁定巨集
const modelValue = defineModel<string>();

// 2. 狀態定義 (State)
const count = ref(0);

// 3. 計算屬性 (Computed)
const doubleCount = computed(() => count.value * 2);

// 4. 方法定義 (Methods)
function handleAction() {
  emit('change', 'action-triggered');
}
</script>

<style scoped>
/* 必須使用 scoped 以免全域樣式污染，並優先選用 class 選擇器 */
.vue-expert-component {
  display: flex;
  flex-direction: column;
}
</style>