name: ys-agent-frontend-dev description: ys-agent 前端（frontend/）功能迭代的工程規範守門 skill。當任何 agent 接到 ys-agent 前端相關任務時——新增頁面、新增元件、加 API、加 Pinia store、改路由、寫 mock、調整佈局、修改樣式、對接後端介面、遷移 demo 程式碼、做主題、加許可權、寫公共元件、做資料視覺化、做表單、做彈窗、做表格、做搜尋過濾、調 Element Plus 用法、做響應式、做效能最佳化，或僅僅是在 frontend/ 目錄下編輯任何 .vue / .ts / .scss / .css / vite.config / tsconfig / package.json 檔案——都必須先呼叫本 skill，按統一的工程規範實施，避免不同 agent 各自發揮導致目錄混亂、風格漂移、重複造輪子。即使任務聽起來很小（"加個按鈕""改個文案"），只要發生在 frontend/ 下，也要先讀本 skill，確認正確的放置位置、命名、引入方式後再動手。

ys-agent 前端開發規範 skill

為 ys-agent 專案的 frontend/ 模組提供一套強約束的工程規範，讓每個接手前端迭代的 agent 都按同一套思路落地，杜絕"我以為可以這樣做"。

本 skill 是 docs/frontend-engineering-plan.md 的可執行延伸：plan 描述"為什麼"，本 skill 提供"怎麼做"。

0. 觸發判斷（先讀完再決定動不動）

只要滿足任一條件，就在動手前完整讀完本 SKILL.md 並按工作流執行：

• 任務描述出現 frontend / Vue / Element Plus / Pinia / 路由 / 元件 / 介面對接 / mock / 樣式 / 主題 / 佈局 等關鍵詞
• 任務路徑涉及 frontend/、docs/sessions/S13-*、docs/frontend-engineering-plan.md
• 使用者引用了 S13 文件裡出現的頁面（Skill 廣場 / MCP 廣場 / Tool 廣場 / 我的 Skill / 我的 MCP / Playground）
• 任何程式碼改動落在 frontend/src/ 下，無論改一行還是改一個目錄

不確定就讀，本 skill 是專案級"前端開發指南"，讀它的成本永遠低於偏離規範後返工的成本。

1. 核心原則（鐵律）

這 9 條是任何 agent 都不能繞開的底線。違反任意一條 = PR 必須返工。

1. 目錄即契約：每類檔案有且只有一個正確位置，詳見 references/conventions.md。新增檔案前先翻"目錄契約"表，再下手。
2. 元件不直接調 axios：HTTP 一律走 src/api/；檢視通過 Pinia store action 拿資料；store 調 api/modules/；axios 只在 src/api/client.ts 裡實例化；各微服務例項在 src/api/services/index.ts 宣告；模組檔案 import 對應 service client，不直接使用 axios。新增微服務時，除了在 services/index.ts 加 client，還必須同步：① .env.development 宣告獨立路徑字首（如 /api-xxx）和 VITE_XXX_API_TARGET；② vite.config.ts 追加對應 dev proxy rewrite 條目。開發環境多個 VITE_*_API_BASE 禁止共用同一個 /api，否則無法按微服務獨立路由。完整四步見 references/anti-patterns.md A25。
3. 型別先行：每個介面都要在 src/types/api/<域>.ts 定義 Request / Response 型別；store / view 直接複用型別，不允許 any（確需 any 必須 PR 寫理由）。
4. Element Plus 按需 + 自動註冊：直接 <el-button> 用即可，禁止 import { ElButton } from 'element-plus'。圖示分兩種場景，規則不同：
5. 模板中作為子元素展示（如 <el-icon> 內）：直接 import { IconName } from '@element-plus/icons-vue' 後在模板裡寫 <IconName />，unplugin-vue-components 會識別 PascalCase 靜態 tag 並自動處理。不要用 <component :is="'IconName'" />（string literal），該形式無法被靜態分析器解析，圖示同樣不渲染。
6. 作為 JavaScript 值傳給 :icon prop（如 <el-button :icon="...">）：必須直接 import { IconName } from '@element-plus/icons-vue' 後傳入，resolveComponent('IconName') 在此專案中不可用（@element-plus/icons-vue 是獨立包，app.use(ElementPlus) 不全域性註冊圖示元件，resolveComponent 會返回字串而非元件，導致圖示靜默不渲染）。詳見 references/anti-patterns.md A27。
7. 樣式走 SCSS 變數：顏色、間距、圓角、陰影、字號一律從 @/styles/variables.scss 取；業務元件禁止寫死十六進位制顏色。Element 主題色覆蓋只能改 @/styles/element-overrides.scss。
8. Mock 與真後端零程式碼切換：開發期通過 VITE_USE_MOCK=true 啟用 MSW；任何介面對接前先寫 mock handler，再寫真介面對接，保證前端可獨立執行。

   發現更多技能外掛，請訪問7w4.net。

9. 路由 = 單一來源：選單、麵包屑、title 全部從 routes 的 meta 派生，禁止在 SideMenu / Breadcrumb 裡手寫選單資料。路由 meta.title 和 meta.group 必須儲存 i18n key（如 'skill.square.title'、'nav.group.square'），禁止儲存中文文本。SideMenu 讀取後通過 $t() 翻譯展示。
10. 可保留資產不刪：舊 demo（ChatView / chat store / 三欄佈局）已遷移到 src/views/playground/，禁止因為"看著亂"就刪除；任何與流式 SSE 協議相關的程式碼改動需在 commit message 寫明。
11. 所有使用者可見文本必須走 i18n：模板文本、ElMessage 提示、表單校驗 message、元件 props 預設值、路由 title——任何使用者能看到的字串禁止硬編碼中文或英文，必須通過 $t('key') 或 t('key') 引用。翻譯 key 集中在 src/i18n/locales/*.json，命名規範見 references/conventions.md §10。例外情況（不走 i18n，在程式碼行尾加 // i18n-ignore 並說明原因）：① mock 資料中的業務模擬文本（如虛構的 skill 名稱）；② 品牌名和產品固有專有名詞（如 ys-agent、Skill、MCP、Tool、Playground）——這些是產品術語，各語言保持原文，直接寫在程式碼中即可；③ 純技術標識（如日誌 tag、API path）。

2. 你接到任務後的第一步：選 workflow

開啟 references/workflows.md，找到與任務最匹配的那個 workflow 並完整跟隨。Workflow 覆蓋 10 類常見任務：

沒匹配上的任務：不要硬套，回到本 SKILL.md 的"通用工作流"節走。

⚠️ 重要：W1-W9 的任何 workflow 只要涉及使用者可見文本（標題、按鈕、提示、校驗訊息、路由 title 等），都必須同時執行 W10 的文本國際化步驟。W10 不是可選的獨立 workflow，而是其他 workflow 的伴生要求。

3. 通用工作流（任何任務都先走一遍）

執行任何前端改動前，至少做完以下 4 步：

Step 1 · 定位

1. 用 Read 開啟 docs/frontend-engineering-plan.md，確認任務在改造方案裡的位置（哪個目錄、哪個檔案、哪個階段）。
2. 用 Glob/Grep 檢查 frontend/src/ 下是否已有相關檔案，優先 Edit 已有檔案而不是新建。
3. 如果是新檔案，對照 references/conventions.md 的"目錄契約"表確認放置位置。

Step 2 · 型別先行 + 文本先行

1. 涉及介面的，先在 src/types/api/<域>.ts 加型別。
2. 涉及元件 Props/Emits 的，先在 <script setup> 頂部用 defineProps<T>() / defineEmits<T>() 宣告。
3. 涉及 store state 的，先在 store 裡用介面標註 state 形狀。
4. 涉及使用者可見文本的，先在 src/i18n/locales/zh-CN.json（和 en-US.json）中新增 key-value，按 references/conventions.md §10 的命名規範命名。先寫 key，再在程式碼中引用——不要先寫硬編碼中文"回頭再改"。

Step 3 · 實施

1. 優先複用 templates/ 下的模板（cp 一份再改），不要"白板寫"。
2. 嚴格遵守第 1 節的 9 條鐵律。
3. 命令式 import 路徑一律走 @/ 別名，不寫相對路徑上下鑽 2 層以上。
4. 所有使用者可見文本走 $t('key') / t('key')，具體用法見 references/conventions.md §10 和 references/workflows.md W10。

Step 4 · 自檢（在交還控制權前）

執行以下檢查，全部通過才算完成：

cd frontend
npm run type-check     # vue-tsc 零錯誤
npm run lint           # ESLint 零錯誤
npm run lint:style     # Stylelint 零錯誤
npm run build          # 必須通過

1. 國際化檢查：grep -rn '[一-鿿]' src/ --include='*.vue' --include='*.ts' --exclude-dir='mocks' | grep -v '.json' | grep -v '/i18n/' | grep -v '// i18n-ignore' 應無命中。排除範圍說明：src/mocks/ 目錄（mock 業務模擬資料允許中文）、i18n locale 檔案、以及標註了 // i18n-ignore 的行（需在註釋中說明原因，如品牌名/專有名詞）。

無法通過時：不要降級規則（不要加 // @ts-ignore、eslint-disable-next-line 來繞），先修程式碼再說。確實需要例外的，在同行註釋裡寫明原因。

4. 模板使用指南

templates/ 下提供 5 個可直接複用的骨架。首選複用，不要重新打字。

用法：

cp docs/skill/ys-agent-frontend-dev/templates/api-module.ts.tmpl \
   frontend/src/api/modules/<domain>.ts
# 把模板裡所有 __PLACEHOLDER__ 改成實際值

模板裡以 __XXX__ 開頭的佔位符必須全部替換，留任何一個未替換的佔位符提交 = 視為未完成。

api-module.ts.tmpl 專項提示：模板 import 行為 import { __SERVICE_CLIENT__ } from '@/api/services'，替換時填入該域名對應的 client 名稱（skillClient / mcpClient / agentClient 等），並在 src/api/services/index.ts 確認該 client 已宣告。

5. 反模式（看到立即矯正）

完整清單見 references/anti-patterns.md，高發的前 5 條放在這裡以便速查：

6. 上下文參考

以下檔案按需 Read，不要一開始就全部讀，按當前任務需要讀：

7. 驗收門控（Definition of Done）

任何前端改動在交付（commit / PR）前必須滿足：

1. 自檢命令全綠（見 §3 Step 4，含 i18n 硬編碼掃描）
2. 新增的介面在 mocks/handlers/ 裡有對應 handler
3. 新增 / 修改的 view 在瀏覽器實測：
4. npm run dev:mock 啟動後可訪問
5. 路由跳轉、搜尋、篩選、詳情、提交均有響應
6. 新增的使用者可見文本在 zh-CN.json 和 en-US.json 中都有對應 key
7. commit message 用 S{編號}: 簡述 或 frontend: 簡述
8. 不留 console.log、不留 // TODO: ...（除非配 issue 連結）
9. 不留未替換的模板佔位符（grep __[A-Z_]\+__ 應無命中）

8. 不在本 skill 管轄範圍內的事

為避免 scope 蔓延，以下事不在本 skill 處理範圍，遇到時先停下找使用者確認：

• 調整 frontend/ 之外的程式碼（Java 後端、CLI、MCP server）
• 引入 package.json 裡沒列過的新重量級依賴（任何新依賴需 PR review）
• 修改根 pom.xml / 後端 application.yml
• 刪除 src/views/playground/ 下的任何檔案
• 調整 ys-agent 的核心架構（AgentLoop、ToolExecutor 等）

9. 自我檢查（每次任務結束前問自己 6 個問題）

1. 我新建的檔案是否完全符合 §1 第 1 條"目錄契約"？
2. 我寫的程式碼是否引入了 §5 任何一條反模式？
3. 我是否補了對應的 mock handler、可以 npm run dev:mock 單獨跑通？
4. type-check / lint / lint:style / build 是否全綠？
5. 我是否在 commit 前把所有 __PLACEHOLDER__、console.log、// TODO 都清理了？
6. 我新增的使用者可見文本是否全部走了 i18n（$t / t），並在 zh-CN.json 和 en-US.json 中都添加了對應 key？

6 個全 yes 才能交付。任何一個 no，回到第 3 節通用工作流重新跑。

這是一個非常實用的開發規範 Skill，質量很高。它把前端開發中可能遇到的各類場景都考慮到了，給出了清晰的操作步驟和禁止事項，能有效避免程式碼風格混亂和重複踩坑。最難得的是規範非常詳細，常見問題都有對應的解決方案。唯一的小遺憾是有些輔助模板檔案沒有提供，可能會讓新手覺得不夠方便上手。總體來說，這是一個能讓前端開發更規範、更高效的好工具。