frontend-code-review

前端程式碼審查

使用時機

當使用者要求審查、稽核、分析或檢查 web/、packages/dify-ui/ 或前端相關 TypeScript 檔案時，使用此技能。

支援的模式：

• 待變更審查：檢查暫存區與工作目錄的變更。
• 檔案審查：檢查明確指定的檔案或路徑。
• 差異/片段審查：審查貼上的差異或程式碼片段，盡力參考相關內容。

請勿將此技能用於 api/ 下的後端程式碼；請改用 backend-code-review。

必要背景

審查前，請先閱讀相關的本地合約：

• web/AGENTS.md：了解 Dify 前端工作流程、覆蓋層、設計代碼、狀態與測試。
• packages/dify-ui/README.md 與 packages/dify-ui/AGENTS.md：當程式碼使用或修改 @langgenius/dify-ui/* 時。
• web/docs/overlay.md：審查對話框、抽屜、彈出視窗、工具提示、選單、選擇器、下拉選單或其他浮動 UI 時。
• web/docs/test.md 與 frontend-testing 技能：審查測試或可測試性時。
• karpathy-guidelines：控制範圍與聚焦可驗證的變更。
• how-to-write-component：審查 React 元件結構、所有權、副作用、查詢/變更合約或記憶化時。

對於任何 UI、UX 或無障礙審查，請在最終確定發現前，先取得最新的 Web 介面指南。將其視為必要基準，而非無障礙真理的完整來源：

https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md

如果審查依賴於當前的框架、SDK、瀏覽器 API 或無障礙行為，且本地程式碼無法解決，請先查閱官方文件。對於瀏覽器相容性、棄用或行為敏感的前端 API，請驗證 MDN 或相關標準。

規則包

套用所有相關的規則包：

• references/accessibility-ui.md — 無障礙、語意 HTML、焦點、表單、鍵盤、禁用狀態、文案與長內容行為。結合 Web 介面指南與 Dify UI、Base UI、MDN 及本地基本元件合約。
• references/dify-ui.md — Dify UI 基本元件使用、Base UI 語意、覆蓋層、表單、代碼、圓角對應與基本元件邊界。
• references/component-architecture.md — 元件所有權、props、狀態、副作用、匯出、包裝器與功能組織。
• references/data-query-contracts.md — 生成的合約、TanStack Query、變更、工作區/認證/SSR 邊界、URL/本地儲存狀態。
• references/performance.md — 來自 Vercel 指南的 React/Next 效能審查規則，僅限於實際風險。
• references/testing.md — 前端測試審查規則。
• references/dify-invariants.md — 穩定的 Dify 特定執行期不變量，一般 React/a11y 規則無法捕捉。
• references/code-quality.md — 一般 TypeScript、樣式、命名與可維護性規則。

審查流程

1. 確定審查範圍。對於待變更，檢查 git diff --stat、git diff 及相關的暫存區差異。對於檔案審查，僅限於指定的檔案，除非必須讀取相關的所有者或合約。
2. 閱讀變更行附近的程式碼及其所屬模組。不要僅根據隔離的片段進行審查，當附近的所有權、標籤、查詢輸入或覆蓋層結構決定正確性時。
3. 首先檢查使用者可見的回歸：無障礙、互動中斷、認證/權限洩漏、查詢/水合錯誤、資料遺失、導航錯誤與不可能狀態。
4. 然後檢查可維護性與效能：所有權、副作用、包裝器、記憶化、套件/瀑布風險、測試與設計系統偏移。
5. 僅報告可操作的發現。不要列出推測性風險、風格偏好或廣泛的重構，除非它們直接與範圍內的可重現問題相關。

嚴重程度

• P0：安全性/隱私/認證洩漏、資料遺失、生產環境當機、無法存取的關鍵流程或主要工作流程中斷。
• P1：使用者可見的回歸、水合/SSR 失敗、無效的 API/查詢合約、鍵盤/焦點行為中斷或嚴重的設計系統/a11y 違規。
• P2：可能導致錯誤的可維護性或效能問題、重複狀態、不正確的所有權、缺少對風險行為的測試或非關鍵的 a11y 問題。
• P3：具有明確價值的次要清理。除非使用者要求徹底稽核，否則省略。

輸出格式

以發現為主，按嚴重程度排序。使用以下結構：

## 發現

- [P1] 簡短問題標題
  檔案：`path/to/file.tsx:123`
  為何重要以及如何重現或推理。
  建議修正：具體的修正方向。

## 開放問題

- 問題或假設（如有）。

## 總結

簡短的次要背景。提及未執行的測試或殘餘風險。

規則：

• 如果沒有發現，請說 No issues found. 並提及任何測試缺口或殘餘風險。
• 始終包含檔案與行號（若可用）。
• 保持發現具體且可重現。
• 預設不包含讚美部分。
• 除非使用者明確要求審查加上實作，否則不要要求套用修正。