當 AI 走進前端開發：代理插件的全流程開發實踐

1 背景

AI 技術的飛速發展，正在深刻改變前端開發的方式。以 Cursor、Trae 等新一代 AI IDE，正逐步成為工程師的“第二大腦”。它們通過強大的代碼補全、上下文理解、自動重構、文件生成等能力，讓開發者能夠以更高的效率完成項目交付。

在公司日常開發中，我們經常使用 Whistle 作為網路代理工具，不同系統的開發環境與生產環境之間頻繁切換配置，一次其實還好，如果切換次數多了就會導致思維不連貫。為了解決這一痛點，我決定開發一款自動切換代理的瀏覽器插件。

本項目的核心目標是：

在最短時間內驗證插件的可行性與實用性。

為了實現這個目標，我選擇借助 AI 完成從需求分析、技術選型到功能實現的全过程。

2 功能實現

2.1 核心功能

基於需求，項目的核心功能可以拆解為以下三個部分：

• 自動代理切換：在訪問預先配置的域名時，自動匹配並切換到對應的 Whistle 代理規則。
• 手動兜底選擇：在需要手動覆蓋時，允許使用者點擊切換當前代理；同時支持啟用/切換 Default 規則。
• Rules 規則解析：實現對 Rules 進行語法解析，使得使用者可以直接在插件介面中查看和操作各條代理規則。

2.2 技術選型與項目初始化

🔍 1. 借助 AI 自動完成框架調研

在任何工程項目中，技術選型都是最關鍵的第一步。這一環節往往耗時且枯燥：需要人工對比不同框架的特性、深入閱讀 GitHub 倉庫、評估社區活躍度與兼容性問題。整個過程不僅繁瑣，而且容易遺漏關鍵細節。現在，可以使用 AI 的輔助分析能力，讓這個流程變得高效。

💡 2. 推薦理由與分析結果

我將幾個候選框架的 GitHub 倉庫連結 輸入給 AI，讓它自動分析：

• 項目的維護狀態與更新頻率
• Issue 處理活躍度
• 兼容性風險與生態成熟度

AI 馬上就生成了一份詳細的對比報告，列出了各個框架的優劣勢，並給出了明確推薦。

🚀 3. 從選型到腳手架，僅需 5 分鐘

在確認技術選型後，我繼續讓 AI 自動生成項目初始化配置。AI 快速構建了完整的 項目腳手架，包括目錄結構、基礎配置與依賴說明。整個過程從選型到可運行項目耗時 5 分鐘 不到。

2.3 Whistle API 解析

該插件需要與本地運行的 Whistle 服務 交互，例如獲取當前規則、切換規則等。

在傳統開發流程中，我們通常需要 人工查閱源碼或文檔 來了解交互介面的實現細節。然而，這種方式不僅耗時，而且容易遺漏關鍵參數或邏輯。

為了解決這個問題，本項目充分利用了 Cursor 的 AI 能力，讓它自動完成接口分析工作，從而極大地提升了效率。

🧩 1. 自動識別 Whistle 交互介面

首先，我們需要弄清楚 Whistle 提供了哪些可用接口。等待 Cursor 完成代碼解析後，AI 就能自動識別並總結出完整的交互接口列表。

💡 提示：在提問前請確保 Cursor 的 Indexing 已完成，否則 AI 無法準確理解項目結構。

📘 2. 自動生成接口文檔

接下來，我們讓 AI 根據分析結果，進一步提取接口定義、請求參數、響應結構等關鍵信息，並生成一份結構化的內部 API 文檔。

這一步讓我們在無需手動閱讀源碼的情況下，快速了解所有交互細節。有了這份由 AI 自動生成的接口文檔，我們在後續的插件開發中，就可以將其作為交互規範使用。

2.4 頁面設計與文檔撰寫

🧩 1. 用 AI 輔助編寫交互與需求文檔

在開始頁面開發前，建議使用 AI 生成一份詳細的 需求與交互文檔。基本流程如下：

• 用簡潔的語言描述功能點：例如“設定頁用於配置代理規則與默認選項”。
• 讓 AI 扮演產品經理或設計師：根據描述自動擴展成結構化的 Markdown 文檔。
• 人工復核與補充示例：對 AI 輸出的內容進行細化、補充狀態變化與異常場景。

🧱 2. 頁面文檔的結構建議

每個頁面（如 “設定頁”、“規則管理頁” 等）應包含以下核心內容：

• 功能說明：頁面的主要目標與核心作用。
• 交互流程：使用者在頁面中的操作路徑與反饋邏輯。
• 數據流說明：前端、插件背景腳本及存儲之間的數據交互關係。
• 測試與驗收要點：用於驗證頁面功能正確性的關鍵點。

這樣設計的好處是：每個頁面在開發完成後都可以獨立驗收，減少迭代風險。

🤖 3. AI Prompt 模板

本次為了讓 AI 輸出更高質量的文檔，使用了如下的 Prompt 模板，這種預定好的模版其實很多，在開發的時候可以收藏一些自己常用的模版

你現在是一名資深產品經理，請基於以下輸入信息，生成一份詳細的頁面功能文檔（Markdown 格式）。

【輸入信息】
- 項目背景：基於 Chrome Manifest V3 的瀏覽器插件，用於控制本地 Whistle 服務，实现自動切換代理、手動兜底代理、Rules 規則解析。
- 當前目標頁面：{{頁面名稱，例如“設定頁”或“規則管理頁”}}
- 頁面定位：{{頁面的主要作用，例如“用戶配置代理規則與默認選項”}}
- 功能範圍：{{頁需實現的核心功能點簡要列出}}

【文檔要求】
請輸出為 Markdown 格式，包含以下內容：
1. 頁面概述（描述該頁面的功能目標與使用場景）
2. 功能結構（用列表形式拆解成獨立子功能，每個功能用一句話概述）
3. 頁面交互流程（可用文字 + 流程描述，若有狀態變化請說明）
4. 數據流說明（說明該頁面涉及的輸入/輸出、存儲方式、事件觸發邏輯）
5. 測試要點（列出驗證功能正確性與邊界情況的測試點）
6. 驗收標準（說明頁面完成後可被視為“驗收通過”的條件）

請輸出完整文檔，不要包含提示語或額外解釋。

你是一位專業的UI/UX設計師，專門研究現代瀏覽器插件界面。你在為使用Antd、React構建的瀏覽器插件創建直觀、可訪問且視覺吸引力強的用戶體驗方面擁有深厚的專業知識。

你的核心職責：
- 分析現有UI組件和頁面，理解當前的設計系統
- 提供符合Antd標準的具體設計建議
- 創建開發者可以輕鬆實現的詳細UI/UX規範
- 確保設計在不同屏幕尺寸環境中無縫工作
- 優先考慮用戶工作流程效率和可訪問性

在提供設計指導時，你將：
1. 首先分析當前UI狀態，識別具體的改進機會
2. 引用適用於具體情況的Antd組件、設計令牌和模式
3. 提供清晰、可執行的設計規範，包括：
   - 組件層次結構和佈局結構
   - 使用Antd設計的間距、排版和顏色建議
   - 交互狀態和適當的微動畫
   - 可訪問性考慮（對比度比率、焦點指示器等）
4. 創建足夠詳細的視覺描述，讓開發者可以無歧義地實現
5. 考慮React + Antd技術棧的技術約束
6. 在適用時建議具體的Antd組件和屬性
7. **創建ASCII佈局草圖或詳細的佈局描述圖**，直觀展示設計方案

你的設計建議應始終：
- 遵循Antd原則（動態顏色、改進的可訪問性、表現力主題）
- 與現有應用程序模式保持一致性
- 針對瀏覽器交互模式（鼠標、鍵盤導航）進行優化
- 可使用當前技術棧實現
- 包含設計決策的合理性說明

**輸出格式要求：**
你的響應必須包含以下結構：

## 設計分析
[分析當前狀態和改進機會]

## 佈局草圖
┌─────────────────────────────────────────────────┐
│                 [組件描述]                       │
├─────────────────────────────────────────────────┤
│  [詳細的ASCII佈局圖，展示各組件位置和層次關係]     │
│                                                 │
└─────────────────────────────────────────────────┘

## 設計規範
### 組件層次結構
[詳細描述組件的嵌套關係和層次]

### Antd 規範
- **顏色方案**：[具體的顏色令牌和應用]
- **排版系統**：[字體大小、行高、字重規範]
- **間距系統**：[具體的間距值和應用規則]
- **組件規範**：[Material-UI組件選擇和配置]

### 交互設計
[描述交互狀態、動畫效果和用戶反饋]

### 可訪問性考慮
[對比度、焦點管理、鍵盤導航等]

### 響應式設計
[不同窗口尺寸下的佈局適配]

在描述UI佈局時，使用清晰的結構化語言並引用具體的Antd組件。始終考慮明暗主題的實現。

⚙️ 4. 審閱與擴展：讓 AI 文檔真正可用

AI 生成的文檔往往已經覆蓋了 70% 的基礎需求，但在投入開發前，仍需人工審閱與細化：

• 檢查是否符合產品目標與業務邏輯。
• 補充操作示例與狀態圖。
• 對關鍵數據結構、存儲邏輯等內容，進一步讓 AI 生成對應的 技術文檔（例如 Rules 解析邏輯、消息通信機制等）。

這樣，文檔既具備產品層面的完整性，又能直接指導開發與測試。

3 功能效果

🧠 1. 問題發現與分析

在初版插件生成後，很快發現了一些 細節性問題。這些問題大多源於以下幾個方面：

• 需求文檔未明確的邊界條件：例如：部分輸入值或異常狀態未定義、文字溢出等
• 交互邏輯描述不完整
• 上下文遺忘問題

在調試階段，如果發現 AI 生成的代碼出現了邏輯混亂或交互異常的情況，建議不要盲目讓 AI 一直修改同一段代碼，可以開啟一個新的對話輪次，重新提供上下文和問題描述。

或者使用 Cursor 命令 /Reset Context 來將上下文重置為默認。

⚙️ 2. 多輪 AI 優化與人工校對

經過多輪 AI 優化 與 人工復核，插件中的大部分問題都能被快速修復。

4 使用建議

4.1 Rules 提升開發效率

在實際工程中，僅靠自然語言對話很難讓 AI 始終遵守項目約定。為了讓 AI 理解團隊的技術棧、編碼風格與約束條件，將項目規範以 Rules（規則）的形式注入提示鏈 是最有效的方式之一，能顯著減少重複溝通與低級錯誤，讓 AI 始終在一致的上下文中工作。

在轉轉的實踐中，我們通過 IDE 插件機制 來分發統一維護的 Rules 文件，支持版本化管理，使團隊成員都能保持相同的 AI 行為標準。

📘 1. Cursor 的四類 Rules（及其最佳實踐）

目前，Cursor 支持四種類型的規則文件，每種都有不同的作用範圍與應用場景。

在理解類型的同時，我們也可以針對每類規則配置相應的內容結構，從而發揮最大效用。

參考文檔：cursor.com/cn/docs/context/rules

User Rules

• 作用範圍：個人全局規則，在 Cursor 設定中定義並始終生效。
• 典型內容：
  • 個人開發習慣（縮進風格、命名規則、註釋偏好）
  • 語言約定（TypeScript、React Hook 編碼風格）
  • 禁止項（如禁止自動生成 README 或無意義測試代碼）
• 使用建議：可將你的編碼偏好寫入 User Rules，確保無論在哪個項目中，AI 都能保持一致的輸出風格。

Project Rules

• 作用範圍：項目級規則，存放於 .cursor/rules 文件夾中，納入版本控制。
• 典型內容：
  • 技術棧說明（當前項目為瀏覽器插件，而非普通 Web 頁面）
  • 業務模組說明與接口定義
  • 異常與安全處理規範
  • 團隊特定約定（命名空間、API 返回結構、日誌策略）
• 使用建議：在團隊開發中，Project Rules 是 AI 理解項目上下文的“核心指南”。建議在其中寫明：

針對 Rules 也可以去編寫 description、globs、alwaysApply 等內容。

Team Rules

• 作用範圍：團隊級別，由管理控制台統一配置。
• 典型內容：團隊通用編碼規範

AGENTS.md

• 作用範圍：輕量化規則文件，以 Markdown 格式定義。
• 典型內容：
  • 簡化版 Agent 指令（如角色設定、任務範圍、語氣要求）
  • 適用於小型項目或臨時實驗
• 使用建議：若項目規模較小，可以使用 AGENTS.md 快速定義開發約束。

⚙️ 2、Cursor 直接生成 Rules 文件

🧹 3、補充：維護與優化 .cursorignore

別忘了創建並配置 .cursorignore 文件，它的作用類似 .gitignore，在大型代碼庫中，排除無關部分，以加快索引並更準確地定位文件。

並且排除文件也可以提高安全性，限制敏感信息的訪問，Cursor 會屏蔽被忽略的文件，但由於 LLM 的不可預測性，無法保證絕對防護。

4.2 高質量 Prompt

💡 1、清晰意圖優於“聰明代碼”

在 AI輔助編程中，提示詞（Prompt）的質量往往決定了生成結果的質量。

這樣的 Prompt 明確了上下文、依賴關係、架構規範與測試方式 —— AI 就能在一次生成中完成高質量實現，而無需反覆修正。

// ❌ 錯誤示例
幫我寫 content.js，把彈窗注入到頁面。

// ✅ 正確示例
你是一個資深前端工程師，目標是為 Chrome 插件的 content script (content.js) 生成高質量、可維護、符合 Manifest V3 的注入彈窗實現。請嚴格按下面要求輸出代碼/說明。

1) 環境與約束
- Chrome 插件，Manifest V3。
- 不使用第三方庫（純原生 DOM / JS）。
- 使用 Shadow DOM 來隔絕樣式、JS的影響。
- 異步配置來自 `chrome.storage.local` 的 key: `pluginConfig`，其結構為 `{ message?: string, duration?: number }`。
- 異常處理：閱讀 storage 失敗或未定義字段時使用默認值 `{ message: "插件已啟用", duration: 3000 }`。
- 要支持頁面可能已存在同類彈窗（避免重複注入）。

2) 角色與職責分離（要求）
- 提供 `getPluginConfig()`（Promise 返回 config）
- 提供 `createPopup(message, duration)`（只操作 DOM）
- 提供 `mountPopup()`（主流程：獲取配置並調用 createPopup）
- 將所有 DOM 類名以 `popup-` 前綴命名以避免衝突
- 提供 `content.css` 的完整樣式塊

3) 驗證點（測試要點）
- 當 storage 返回自定義 message/duration 時，彈窗按自定義值顯示並在 duration 後移除
- 當 storage 返回空或閱讀失敗時，使用默認值
- 多次加載 content script 時，不會創建重複彈窗

4) 若在開始編寫代碼前有任何不明確之處，請先列出最多 3 個澄清問題；等待我答覆後再開始生成代碼。

現在開始：先給出（若有）澄清問題；如無問題，請直接按格式輸出代碼與樣式。

✍️ 2、高質量 Prompt 的特徵

• 指明上下文範圍，不要全量貼代碼：如果只是用到頁面或接口定義，就精準引用那一小段，而不是把整個文件丟給 AI，太多上下文不僅浪費 Token，還容易讓模型“跑題”。
• 先寫在文檔裡，再丟給 AI：在調用 AI 生成前，可以先在一個文檔中寫好完整 Prompt 都說明白。這樣邏輯更清晰，也方便團隊成員複用與協作。
• 遇到不確定時，讓 AI 主動澄清：如果你擔心需求描述有歧義，可以讓 AI 在生成前提問。

一個好的 Prompt 應該具備以下特徵：

• 簡潔明確：用最少的字，描述最關鍵的信息。
• 聚焦單一任務：把複雜任務拆分為多個原子操作，例如「分析 → 生成 → 測試 → 重構」。
• 角色清晰：讓 AI 扮演具體角色（例如產品經理、架構師、測試工程師），輸出會更專業、更貼合目標。

🧩 3、通用的 AI 編程 Prompt 模板
以下是一份通用的 Prompt 模板，根據自己的項目做出修改，可直接在 Cursor、Claude Code、Trae 等 IDE 中使用。

你是Cursor IDE的AI編程助手，遵循核心工作流（研究->構思->計劃->執行->評審）用中文協助用戶，面向專業程序員，交互應簡潔專業，避免不必要解釋。

[溝通守則]

1. 響應以模式標籤 `[模式：X]` 開始，初始為 `[模式：研究]`。
2. 核心工作流嚴格按 `研究->構思->計劃->執行->評審` 順序流轉，用戶可指令跳轉。

[核心工作流詳解]

1. `[模式：研究]`：理解需求。
2. `[模式：構思]`：提供至少兩種可行方案及評估（例如：`方案1：描述`）。
3. `[模式：計劃]`：將選定方案細化為詳盡、有序、可執行的步驟清單（含原子操作：文件、函數/類、邏輯概要；預期結果；新庫用`Context7`查詢）。不寫完整代碼。完成後用`interactive-feedback`請求用戶批准。
4. `[模式：執行]`：必須用戶批准方可執行。嚴格按計劃編碼執行。計劃簡要（含上下文和計劃）存入`./issues/任務名.md`。關鍵步驟後及完成時用`interactive-feedback`反饋。
5. `[模式：評審]`：對照計劃評估執行結果，報告問題與建議。完成後用`interactive-feedback`請求用戶確認。

[快速模式]
`[模式：快速]`：跳過核心工作流，快速響應。完成後用`interactive-feedback`請求用戶確認。

[主動反饋與MCP服務]

* **通用反饋**：研究/構思遇疑問時，使用 `interactive_feedback` 徵詢意見。任務完成（對話結束）前也需徵詢。
* **MCP服務**：
  * `Context7`: 查詢最新庫文檔/示例。
  * 優先使用MCP服務。

4.3 模組化開發

在實際開發中，“一次生成一個大文件”幾乎是 AI 開發中最常見、也最致命的陷阱之一。很多人喜歡一句話讓 AI 生成完整模組，但結果往往是上下文超限、邏輯混亂、邊緣情況丟失，最後調試時間反而更久。

正確的做法是：將複雜系統拆分為若干個獨立的小模組，每個模組具備清晰的輸入、輸出與測試目標。這樣不僅方便 AI 理解，也讓你能快速驗證中間產物，及時發現問題。

🎯 1、拆分策略，讓開發有節奏地前進

• 從“70% 可用”開始：不必一開始就追求完美。先讓 AI 生成核心邏輯（約 70% 可用的版本），驗證運行流程後，再逐步補齊異常處理、UI 優化、性能調整等邊緣部分。這種“漸進式完善”的方式，可以顯著降低 AI 誤解需求的概率。
• 按功能片段分批生成與合併：儘量避免一次性讓 AI 生成過長的文件或多個模組。長上下文不僅容易觸發 token 限制，也容易導致 AI 遺漏或自相矛盾。可以讓 AI 先完成單個功能（例如事件綁定邏輯、API 調用封裝、彈窗渲染函數等），在確認正確後再整合。

🧠 2、限定上下文，讓 AI 更“專注”
在多輪迭代中，可以利用標識來限定上下文範圍，告訴 AI 你希望修改哪個文件或目錄，在迭代的時候使用 @file、@folder、@git 等標識，明確把上下文限定到目標文件或目錄。通過這些顯式標識，AI 能準確聚焦到目標區域，而不會誤改無關部分。

4.4 迭代化學習

在 AI輔助開發的過程中，最關鍵的能力不是“讓 AI 寫代碼”，而是“讓 AI 學會改進自己”。要讓 AI 輸出真正穩定、可控，就必須建立一套持續的 審查與反饋機制，讓

原文出處：https://juejin.cn/post/7561730978814656575