feat: add full stage-2 multilingual support for 8 locales
Translate all 24 stage-2 chapters (frontend, backend, AI capabilities, assignments) to ja-jp, ko-kr, zh-tw, es-es, fr-fr, de-de, ar-sa, vi-vn. Update VitePress config with sidebar labels, nav links, and sidebar entries for each locale. Images reference zh-cn originals via absolute paths. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
sanbuphy
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,346 @@
|
||||
# AI 營銷文案 SaaS 開發實戰
|
||||
|
||||
## 概述
|
||||
|
||||
本實戰項目要求你圍繞一份真實的 PRD，從零完成一個面向獨立開發者和內容團隊的 AI 營銷文案 SaaS 產品。你將使用 Supabase 作為後端服務、Stripe 作為支付系統，完成從需求分析到部署上線的全過程。
|
||||
|
||||
這是 Stage 2 的綜合實戰環節。在前面幾章中，你已經分別學習了前端頁面搭建、後端接口開發、資料庫操作、支付集成等單項技能——這個項目要求你把它們全部串起來，交付一個可運行的產品原型。
|
||||
|
||||
## 前置知識
|
||||
|
||||
在開始本項目之前，你應該已經掌握以下內容：
|
||||
|
||||
- 前端頁面設計與組件庫使用（[UI 設計](../../frontend/ui-design/)、[現代組件庫](../../frontend/modern-component-library/)）
|
||||
- 後端接口設計與開發（[接口程式碼編寫](../../backend/ai-interface-code/)）
|
||||
- 資料庫基礎與 Supabase（[從資料庫到 Supabase](../../backend/database-supabase/)）
|
||||
- 支付集成（[Stripe 收費系統](../../backend/stripe-payment/)）
|
||||
- Git 工作流與部署（[Git 和 GitHub](../../backend/git-workflow/)、[部署 Web 應用](../../backend/zeabur-deployment/)）
|
||||
|
||||
## 學習目標
|
||||
|
||||
完成本實戰後，你將能夠：
|
||||
|
||||
1. 閱讀並理解一份真實的 PRD，從中提取開發任務清單
|
||||
2. 使用 AI 輔助分步生成前端頁面和後端接口
|
||||
3. 使用 Supabase 實現用戶鑑權、資料庫操作
|
||||
4. 集成 Stripe 實現付費訂閱功能
|
||||
5. 搭建管理後臺並完成端到端聯調
|
||||
|
||||
## 項目簡介
|
||||
|
||||
你要構建的產品是一個 AI 營銷文案 SaaS，包含三個子系統：
|
||||
|
||||
| 子系統 | 職責 |
|
||||
|--------|------|
|
||||
| **官網前臺** | 產品介紹、定價、FAQ、註冊轉化 |
|
||||
| **用戶工作臺** | 輸入產品資訊、生成文案、查看歷史、升級套餐 |
|
||||
| **後臺管理臺** | 用戶管理、生成記錄、支付資料、運營概覽 |
|
||||
|
||||
後端使用 Supabase 提供資料庫和鑑權能力，使用 Stripe 處理支付，使用 AI 模型生成營銷文案。
|
||||
|
||||
::: tip PRD 入口
|
||||
本項目的需求文檔在 GitHub： [查看 PRD](https://github.com/datawhalechina/easy-vibe/blob/main/docs/zh-tw/stage-2/assignments/copywriting-platform-supabase/PRD.md)
|
||||
:::
|
||||
|
||||
<div style="margin: 32px 0;">
|
||||
<ClientOnly>
|
||||
<StepBar :active="0" :items="[
|
||||
{ title: '需求分析', description: '閱讀 PRD，明確頁面、功能、鑑權、支付範圍' },
|
||||
{ title: '搭建骨架', description: '用 AI 生成三套前端骨架（www / app / admin）' },
|
||||
{ title: '後端集成', description: 'Supabase 鑑權、生成接口、Stripe 支付' },
|
||||
{ title: '聯調上線', description: '端到端跑通，部署並準備演示' }
|
||||
]" />
|
||||
</ClientOnly>
|
||||
</div>
|
||||
|
||||
## 第一部分：需求分析
|
||||
|
||||
### 1.1 閱讀 PRD
|
||||
|
||||
打開 PRD 文檔，重點回答以下問題：
|
||||
|
||||
- 系統有幾個入口？各自覆蓋哪些頁面？
|
||||
- 每個頁面的核心功能是什麼？
|
||||
- 後端包含哪些模塊和資料表？
|
||||
- 套餐定價、支付流程、免費額度如何設計？
|
||||
- MVP 範圍是什麼？第一版哪些做，哪些不做？
|
||||
|
||||
::: warning
|
||||
如果以上問題沒有明確答案，不要開始寫程式碼。需求理解不清楚是導致返工的最常見原因。
|
||||
:::
|
||||
|
||||
### 1.2 確認系統架構
|
||||
|
||||
根據 PRD 梳理出系統的整體架構：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
prd["PRD"] --> web["官網前臺"]
|
||||
prd --> app["用戶工作臺"]
|
||||
prd --> admin["後臺管理臺"]
|
||||
app --> auth["鑑權"]
|
||||
app --> gen["文案生成任務"]
|
||||
gen --> db["資料庫"]
|
||||
billing["支付與套餐"] --> db
|
||||
admin --> analytics["用戶 / 生成 / 支付看板"]
|
||||
```
|
||||
|
||||
## 第二部分：搭建項目骨架
|
||||
|
||||
### 2.1 生成前端頁面
|
||||
|
||||
使用 AI 先生成所有頁面的基本結構和假資料。
|
||||
|
||||
提示詞參考：
|
||||
|
||||
```text
|
||||
請基於當前 PRD，幫我生成一個 AI 營銷文案 SaaS 的前端骨架。
|
||||
|
||||
要求：
|
||||
1. 分成三個入口：www、app、admin
|
||||
2. 官網包括：首頁、定價、FAQ
|
||||
3. app 包括：登錄、註冊、生成工作臺、歷史記錄、套餐頁
|
||||
4. admin 包括：後臺首頁、用戶管理、生成記錄、支付訂單
|
||||
5. 先只生成頁面結構和假資料，不接真實接口
|
||||
6. 風格要像現代 SaaS，不像課堂 demo
|
||||
```
|
||||
|
||||
### 2.2 完善核心頁面
|
||||
|
||||
骨架搭好後，重點完善文案生成工作臺（Dashboard）頁面：
|
||||
|
||||
```text
|
||||
請繼續完善 /dashboard 頁面。
|
||||
|
||||
這是一個 AI 營銷文案工作臺。
|
||||
|
||||
左側表單字段：
|
||||
- 產品名
|
||||
- 一句話介紹
|
||||
- 目標用戶
|
||||
- 3 個賣點
|
||||
- 投放渠道（官網、朋友圈、小紅書、抖音、郵件）
|
||||
|
||||
右側結果區域預留：
|
||||
- 主標題
|
||||
- 副標題
|
||||
- CTA
|
||||
- 3 版短文案
|
||||
- 長文案
|
||||
|
||||
先用 mock 資料跑通交互。
|
||||
|
||||
要求：
|
||||
- 點擊"生成文案"後有 loading 狀態
|
||||
- 結果區域設計空狀態
|
||||
- 響應式佈局，寬屏窄屏都能正常顯示
|
||||
```
|
||||
|
||||
### 2.3 驗證頁面結構
|
||||
|
||||
逐項檢查：
|
||||
|
||||
- [ ] 三個入口的路由是否獨立
|
||||
- [ ] 頁面數量是否與 PRD 一致
|
||||
- [ ] Dashboard 的表單和結果區域佈局合理
|
||||
- [ ] 假資料展示了基本的 UI 狀態
|
||||
|
||||
### 遇到阻礙？
|
||||
|
||||
如果你在前端搭建階段卡住，可以回顧這些章節：
|
||||
|
||||
- [UI 設計](../../frontend/ui-design/)
|
||||
- [參考 UI 設計規範設計頁面和按鈕](../../frontend/multi-product-ui/)
|
||||
- [用 LLM 和 Skills 讓界面變好看](../../frontend/llm-skills-beautiful/)
|
||||
- [從設計原型到項目程式碼](../../frontend/design-to-code/)
|
||||
- [使用現代組件庫更新你的界面](../../frontend/modern-component-library/)
|
||||
|
||||
## 第三部分：後端集成
|
||||
|
||||
### 3.1 接入 Supabase 登錄
|
||||
|
||||
```text
|
||||
請把我當成 0 基礎，一步一步帶我完成 Supabase 登錄接入。
|
||||
|
||||
需要你幫我完成：
|
||||
1. 項目接入 Supabase
|
||||
2. 實現註冊、登錄、退出功能
|
||||
3. 登錄成功後跳轉到 /dashboard
|
||||
4. 未登錄用戶訪問 /dashboard、/billing、/admin 時自動跳轉 /login
|
||||
5. 創建 profiles 表
|
||||
6. 用戶註冊成功後自動在 profiles 表創建記錄
|
||||
7. profiles 表包含 email、role、plan 字段
|
||||
|
||||
實現要求：
|
||||
- 每步都說明在修改哪些文件
|
||||
- 密鑰不要硬編碼
|
||||
- 需要在 Supabase 後臺手動操作的地方請明確標註
|
||||
- 完成後說明如何驗證註冊和登錄
|
||||
```
|
||||
|
||||
### 3.2 接入生成接口和資料庫
|
||||
|
||||
```text
|
||||
請把我當成 0 基礎，幫我完成網站的核心功能：生成營銷文案並保存。
|
||||
|
||||
目標效果：
|
||||
1. 用戶在 /dashboard 填寫表單，點擊"生成文案"
|
||||
2. 後端接收：產品名、介紹、目標用戶、賣點、投放渠道
|
||||
3. 後端調用模型生成結果
|
||||
4. 頁面展示生成結果
|
||||
5. 輸入和輸出都保存到資料庫
|
||||
6. 用戶下次進入可查看歷史記錄
|
||||
|
||||
需要你完成：
|
||||
- 創建生成接口 /api/generate
|
||||
- 創建 generations 表
|
||||
- 設計輸入和輸出字段
|
||||
- Dashboard 頁面讀取當前用戶的歷史記錄
|
||||
|
||||
用戶體驗：
|
||||
- 按鈕 loading 狀態
|
||||
- 生成失敗時的錯誤提示
|
||||
- 無歷史記錄時的空狀態
|
||||
|
||||
完成後請說明：
|
||||
- 前端頁面文件位置
|
||||
- 後端接口文件位置
|
||||
- 資料寫入資料庫的邏輯位置
|
||||
- 如何測試完整生成鏈路
|
||||
```
|
||||
|
||||
### 3.3 接入 Stripe 付費
|
||||
|
||||
```text
|
||||
請把我當成 0 基礎，幫我給 LaunchKit 加上最簡可用的 Stripe 付費。
|
||||
|
||||
不需要複雜系統，先跑通最基本的付費鏈路。
|
||||
|
||||
需要你完成：
|
||||
1. /billing 頁面展示 free 和 pro 兩個套餐
|
||||
2. 用戶點擊升級後跳轉 Stripe Checkout
|
||||
3. 支付成功後返回網站
|
||||
4. 支付結果保存到 subscriptions 表
|
||||
5. 同步更新 profile.plan 字段
|
||||
6. free 用戶每日限 3 次生成，pro 用戶不限
|
||||
|
||||
實現原則：
|
||||
- 先跑通主流程，暫不考慮複雜邊界
|
||||
- 需要在 Stripe 後臺配置的地方請寫清楚
|
||||
- 完成後說明如何測試完整支付流程
|
||||
```
|
||||
|
||||
### 3.4 搭建管理後臺
|
||||
|
||||
```text
|
||||
請把我當成 0 基礎，幫我做一個簡潔可用的管理後臺。
|
||||
|
||||
僅限管理員訪問。
|
||||
|
||||
需要你完成：
|
||||
1. 僅 role = admin 的用戶可訪問 /admin
|
||||
2. 後臺包含 3 個 Tab：用戶列表、生成記錄、訂閱狀態
|
||||
3. 用戶列表顯示：email、plan、創建時間
|
||||
4. 生成記錄顯示：用戶、產品名、渠道、創建時間
|
||||
5. 訂閱狀態顯示：用戶、套餐、支付狀態
|
||||
|
||||
要求：
|
||||
- 界面簡潔清晰
|
||||
- 使用現有組件庫的表格、Tab、Badge
|
||||
- 完成後說明如何將賬號設為 admin
|
||||
```
|
||||
|
||||
### 遇到阻礙？
|
||||
|
||||
如果你在後端開發階段卡住，可以回顧這些章節：
|
||||
|
||||
- [從資料庫到 Supabase](../../backend/database-supabase/)
|
||||
- [大模型輔助編寫接口程式碼與接口文檔](../../backend/ai-interface-code/)
|
||||
- [如何集成 Stripe 等收費系統](../../backend/stripe-payment/)
|
||||
|
||||
## 第四部分：聯調與上線
|
||||
|
||||
### 4.1 端到端測試
|
||||
|
||||
至少驗證以下場景：
|
||||
|
||||
- 註冊 → 登錄 → 生成文案 → 查看歷史 → 升級套餐
|
||||
- 管理員登錄 → 查看用戶資料 → 查看生成記錄 → 查看支付狀態
|
||||
|
||||
部署前檢查：
|
||||
|
||||
```text
|
||||
請把我當成 0 基礎，幫我檢查項目是否具備部署條件。
|
||||
|
||||
檢查重點：
|
||||
- 環境變量是否完整
|
||||
- 登錄回調地址是否正確
|
||||
- Stripe 支付回調地址是否正確
|
||||
- 頁面是否缺少 loading、空狀態、錯誤提示
|
||||
- README 是否包含啟動說明和部署說明
|
||||
|
||||
需要你：
|
||||
1. 按優先級列出待修復事項
|
||||
2. 標註哪些必須先修
|
||||
3. 說明修復後的部署步驟
|
||||
```
|
||||
|
||||
### 4.2 部署
|
||||
|
||||
將項目部署到公網環境。部署教程參考：[Git 和 GitHub 工作流](../../backend/git-workflow/)、[如何部署 Web 應用](../../backend/zeabur-deployment/)。
|
||||
|
||||
## 交付物
|
||||
|
||||
完成本項目後，你需要提交以下內容：
|
||||
|
||||
- [ ] 可訪問的線上演示鏈接
|
||||
- [ ] 源碼倉庫鏈接（含 README）
|
||||
- [ ] PRD 文檔
|
||||
- [ ] 核心頁面截圖（首頁、Dashboard、Billing、Admin）
|
||||
- [ ] 60 秒演示影片（覆蓋註冊 → 生成 → 支付 → 後臺）
|
||||
|
||||
README 至少包含：項目簡介、核心頁面說明、技術棧、本地啟動步驟、環境變量清單。
|
||||
|
||||
## 評分標準
|
||||
|
||||
| 維度 | 基本要求 | 進階要求 |
|
||||
|------|---------|---------|
|
||||
| 產品完整度 | 首頁、登錄、Dashboard、Billing、Admin 都能訪問 | 首頁文案和視覺風格像真實 SaaS |
|
||||
| 業務閉環 | 註冊 → 登錄 → 生成 → 查看歷史可以跑通 | 免費/Pro 權限差異清晰可見 |
|
||||
| 資料正確性 | 生成結果和支付狀態都寫入資料庫 | 有明確的錯誤提示、空狀態和 loading |
|
||||
| 權限與安全 | 未登錄不能訪問受保護頁面，普通用戶不能進 Admin | 有基本的輸入校驗和服務端鑑權 |
|
||||
| 工程交付 | 項目可本地啟動，也可部署到公網 | README 清楚，演示影片結構完整 |
|
||||
|
||||
::: tip
|
||||
如果你覺得任務太大，記住一個原則：**先保證"能跑通"，再去追求"做漂亮"。**
|
||||
:::
|
||||
|
||||
## 提交前檢查
|
||||
|
||||
<el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
|
||||
<template #header>
|
||||
<div style="font-weight: bold; font-size: 16px;">提交前最後看一眼</div>
|
||||
</template>
|
||||
|
||||
<ul style="list-style-type: none; padding-left: 0;">
|
||||
<li><label><input type="checkbox" disabled /> 首頁、登錄頁、Dashboard、Billing、Admin 均已完成</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 用戶可以註冊、登錄、退出</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 生成結果真實寫入資料庫</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 支付主流程已跑通</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 管理員可查看用戶、生成記錄和支付狀態</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 項目已部署到公網</label></li>
|
||||
</ul>
|
||||
</el-card>
|
||||
|
||||
## 參考資料
|
||||
|
||||
- [UI 設計](../../frontend/ui-design/)
|
||||
- [參考 UI 設計規範設計頁面和按鈕](../../frontend/multi-product-ui/)
|
||||
- [用 LLM 和 Skills 讓界面變好看](../../frontend/llm-skills-beautiful/)
|
||||
- [從設計原型到項目程式碼](../../frontend/design-to-code/)
|
||||
- [使用現代組件庫更新你的界面](../../frontend/modern-component-library/)
|
||||
- [從資料庫到 Supabase](../../backend/database-supabase/)
|
||||
- [大模型輔助編寫接口程式碼與接口文檔](../../backend/ai-interface-code/)
|
||||
- [Git 和 GitHub 工作流](../../backend/git-workflow/)
|
||||
- [如何部署 Web 應用](../../backend/zeabur-deployment/)
|
||||
- [如何集成 Stripe 等收費系統](../../backend/stripe-payment/)
|
||||
@@ -0,0 +1,210 @@
|
||||
# 類 Dify 智能體平臺開發實戰
|
||||
|
||||
## 概述
|
||||
|
||||
本實戰項目要求你圍繞一份真實的 PRD，從零完成一個模仿 Dify 核心體驗的智能體平臺。你將構建用戶控制檯、管理後臺和平臺後端，實現智能體管理、對話、日誌和知識庫等核心功能。
|
||||
|
||||
這是 Stage 2 的綜合實戰環節。與前面的單頁面或單功能項目不同，這個項目要求你構建一個有"平臺感"的 AI 產品——包含多角色、多模塊、資料持久化和模型調用鏈路。
|
||||
|
||||
## 前置知識
|
||||
|
||||
在開始本項目之前，你應該已經掌握以下內容：
|
||||
|
||||
- 前端頁面設計與組件庫使用（[UI 設計](../../frontend/ui-design/)、[現代組件庫](../../frontend/modern-component-library/)）
|
||||
- 後端接口設計與開發（[接口程式碼編寫](../../backend/ai-interface-code/)）
|
||||
- 資料庫基礎與 Supabase（[從資料庫到 Supabase](../../backend/database-supabase/)）
|
||||
- Git 工作流與部署（[Git 和 GitHub](../../backend/git-workflow/)、[部署 Web 應用](../../backend/zeabur-deployment/)）
|
||||
|
||||
## 學習目標
|
||||
|
||||
完成本實戰後，你將能夠：
|
||||
|
||||
1. 閱讀並理解一份真實的 PRD，從中提取開發任務清單
|
||||
2. 設計智能體平臺的頁面架構和資料模型
|
||||
3. 實現智能體創建、對話、日誌記錄的完整鏈路
|
||||
4. 使用 AI 輔助完成平臺型產品開發
|
||||
5. 完成端到端聯調，交付一個可演示的 AI 平臺原型
|
||||
|
||||
## 項目簡介
|
||||
|
||||
你要構建的產品是一個類 Dify 智能體平臺，包含兩個子系統：
|
||||
|
||||
| 子系統 | 職責 |
|
||||
|--------|------|
|
||||
| **用戶控制檯** | 創建智能體、配置 Prompt、發起對話、查看日誌、管理知識庫 |
|
||||
| **管理後臺** | 查看用戶資料、平臺資源使用情況、調用統計 |
|
||||
|
||||
後端需要支持以下核心能力：智能體管理、會話管理、消息存儲、模型調用、調用日誌記錄、知識庫接入。
|
||||
|
||||
::: tip PRD 入口
|
||||
本項目的需求文檔在 GitHub： [查看 PRD](https://github.com/datawhalechina/easy-vibe/blob/main/docs/zh-tw/stage-2/assignments/custom-dify-agent-platform/PRD.md)
|
||||
:::
|
||||
|
||||
<div style="margin: 32px 0;">
|
||||
<ClientOnly>
|
||||
<StepBar :active="0" :items="[
|
||||
{ title: '需求分析', description: '閱讀 PRD，明確頁面、能力邊界、鑑權、資料模型' },
|
||||
{ title: '搭建骨架', description: '用 AI 生成用戶控制檯和管理後臺骨架' },
|
||||
{ title: '迭代開發', description: '逐模塊補充智能體、對話、日誌、知識庫' },
|
||||
{ title: '聯調上線', description: '端到端跑通，部署並準備演示' }
|
||||
]" />
|
||||
</ClientOnly>
|
||||
</div>
|
||||
|
||||
## 第一部分：需求分析
|
||||
|
||||
### 1.1 閱讀 PRD
|
||||
|
||||
打開 PRD 文檔，重點回答以下問題：
|
||||
|
||||
- 智能體、會話、日誌、知識庫哪些要進 MVP？
|
||||
- 頁面和路由清單是否拍板？
|
||||
- 模型調用和日誌記錄的邊界是什麼？
|
||||
- 多租戶和複雜工作流是否先不做？
|
||||
|
||||
::: warning
|
||||
如果以上問題沒有明確答案，不要開始寫程式碼。需求理解不清楚是導致返工的最常見原因。
|
||||
:::
|
||||
|
||||
### 1.2 確認系統架構
|
||||
|
||||
根據 PRD 梳理出系統的整體架構：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
prd["PRD"] --> app["用戶控制檯"]
|
||||
prd --> admin["管理後臺"]
|
||||
app --> auth["鑑權"]
|
||||
app --> agent["智能體配置"]
|
||||
app --> chat["會話對話"]
|
||||
chat --> llm["模型調用"]
|
||||
chat --> db["資料庫"]
|
||||
app --> kb["知識庫接入"]
|
||||
admin --> logs["調用日誌與平臺概覽"]
|
||||
logs --> db
|
||||
```
|
||||
|
||||
## 第二部分：搭建項目骨架
|
||||
|
||||
### 2.1 生成前端頁面
|
||||
|
||||
提示詞參考：
|
||||
|
||||
```text
|
||||
請基於當前 PRD，幫我生成一個類 Dify 智能體平臺的前端骨架。
|
||||
|
||||
要求：
|
||||
1. 用戶側包括：登錄、智能體列表、智能體配置、對話頁、日誌頁、知識庫頁
|
||||
2. 後臺側包括：後臺首頁、用戶概覽、資源使用概覽
|
||||
3. 先只生成頁面結構和假資料，不接真實接口
|
||||
4. 風格要像現代 AI 平臺
|
||||
```
|
||||
|
||||
### 2.2 驗證頁面結構
|
||||
|
||||
逐項檢查：
|
||||
|
||||
- [ ] 用戶控制檯和管理後臺入口是否分開
|
||||
- [ ] 智能體列表、配置、對話、日誌、知識庫頁面是否完整
|
||||
- [ ] 管理後臺首頁、用戶概覽頁面是否可訪問
|
||||
- [ ] 假資料展示了基本的 UI 狀態
|
||||
|
||||
## 第三部分：迭代開發
|
||||
|
||||
### 3.1 按模塊推進
|
||||
|
||||
在骨架的基礎上，按以下順序逐模塊補充功能：
|
||||
|
||||
1. **鑑權**：註冊、登錄、角色區分
|
||||
2. **智能體管理**：創建、編輯、刪除、Prompt 配置
|
||||
3. **對話功能**：會話創建、消息收發、模型調用
|
||||
4. **日誌記錄**：耗時、token 用量、錯誤記錄
|
||||
5. **知識庫接入**（加分項）：文檔上傳、檢索、結果注入
|
||||
6. **管理後臺**：用戶資料、資源使用、調用統計
|
||||
|
||||
每完成一個模塊，使用下表進行自檢：
|
||||
|
||||
| 檢查項 | 驗證方法 |
|
||||
|--------|----------|
|
||||
| 頁面一致性 | 頁面數量、功能是否符合 PRD |
|
||||
| 接口閉環 | agents、chat、logs、knowledge 接口是否完整 |
|
||||
| 權限隔離 | 用戶是否只能管理自己的 agent 和會話 |
|
||||
| 資料一致性 | messages、logs、documents 資料是否對得上 |
|
||||
| 可演示性 | 是否能演示"創建 agent → 對話 → 查看日誌"完整鏈路 |
|
||||
|
||||
### 3.2 知識庫接入（加分項）
|
||||
|
||||
如果你想增加知識庫能力，可以給每個智能體增加一個"知識庫開關"：
|
||||
|
||||
- 開啟後先檢索知識片段，再和用戶問題一起發送給模型
|
||||
- 關閉後按普通對話模式響應
|
||||
|
||||
第一版不必追求複雜 RAG，只要有"檢索結果可見、調用鏈路可解釋"即可。
|
||||
|
||||
## 第四部分：聯調與上線
|
||||
|
||||
### 4.1 端到端測試
|
||||
|
||||
至少驗證以下場景：
|
||||
|
||||
- 註冊 → 創建智能體 → 配置 Prompt → 發起對話 → 查看日誌
|
||||
- 管理員登錄 → 查看用戶資料 → 查看調用統計
|
||||
|
||||
部署前檢查：
|
||||
|
||||
- [ ] 所有核心接口都做了登錄校驗
|
||||
- [ ] 智能體歸屬權限檢查通過
|
||||
- [ ] 會話記錄、日誌記錄真實落庫
|
||||
- [ ] 模型 Key 使用環境變量，不硬編碼
|
||||
- [ ] 錯誤提示可在前端看到，不只打控制檯
|
||||
|
||||
### 4.2 部署
|
||||
|
||||
將項目部署到公網環境。部署教程參考：[Git 和 GitHub 工作流](../../backend/git-workflow/)、[如何部署 Web 應用](../../backend/zeabur-deployment/)。
|
||||
|
||||
## 交付物
|
||||
|
||||
完成本項目後，你需要提交以下內容：
|
||||
|
||||
- [ ] 可訪問的線上演示鏈接
|
||||
- [ ] 源碼倉庫鏈接（含 README）
|
||||
- [ ] PRD 文檔
|
||||
- [ ] 核心頁面截圖（智能體管理頁、對話頁、日誌頁、後臺首頁）
|
||||
- [ ] 60 秒演示影片（覆蓋創建智能體 → 對話 → 查看日誌）
|
||||
|
||||
README 至少包含：項目簡介、架構說明、技術棧、本地啟動步驟、環境變量清單、接口說明。
|
||||
|
||||
## 評分標準
|
||||
|
||||
| 維度 | 基本要求 | 進階要求 |
|
||||
|------|---------|---------|
|
||||
| 平臺完整度 | agents / chat / logs 三頁可用 | 有清晰導航與統一設計語言 |
|
||||
| 業務閉環 | 可創建智能體並真實對話 | 支持多智能體切換與歷史會話 |
|
||||
| 資料與追蹤 | 消息與調用日誌可查詢 | 有 token / 耗時統計看板 |
|
||||
| 權限安全 | 僅登錄用戶可訪問核心接口 | 資源歸屬校驗完善 |
|
||||
| 工程交付 | 可部署、可演示、README 清晰 | 接入知識庫並可解釋檢索結果 |
|
||||
|
||||
## 提交前檢查
|
||||
|
||||
<el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
|
||||
<template #header>
|
||||
<div style="font-weight: bold; font-size: 16px;">提交前最後看一眼</div>
|
||||
</template>
|
||||
|
||||
<ul style="list-style-type: none; padding-left: 0;">
|
||||
<li><label><input type="checkbox" disabled /> 登錄後可訪問智能體管理、對話、日誌頁面</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 至少可以創建 1 個智能體併成功對話</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 每輪問答都能在資料庫查到記錄</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 調用失敗時前端可見錯誤資訊且日誌已記錄</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 項目已部署，README 和演示影片齊全</label></li>
|
||||
</ul>
|
||||
</el-card>
|
||||
|
||||
## 參考資料
|
||||
|
||||
- [UI 設計](../../frontend/ui-design/)
|
||||
- [使用現代組件庫更新你的界面](../../frontend/modern-component-library/)
|
||||
- [從資料庫到 Supabase](../../backend/database-supabase/)
|
||||
- [大模型輔助編寫接口程式碼與接口文檔](../../backend/ai-interface-code/)
|
||||
- [Git 和 GitHub 工作流](../../backend/git-workflow/)
|
||||
- [如何部署 Web 應用](../../backend/zeabur-deployment/)
|
||||
@@ -0,0 +1,306 @@
|
||||
# 在線考試與管理系統開發實戰
|
||||
|
||||
## 概述
|
||||
|
||||
本實戰項目要求你圍繞一份真實的 PRD，從零完成一個在線考試與管理系統。這個項目的特別之處在於它包含多個角色（學生和管理員），每個角色看到的頁面和能執行的操作不同。你將使用 Express 構建後端，實現完整的考試業務鏈路。
|
||||
|
||||
這是 Stage 2 的綜合實戰環節。多角色權限系統在實際工作中非常常見，掌握這種模式後，你能夠應對教培、SaaS、後臺管理等各類業務場景。
|
||||
|
||||
## 前置知識
|
||||
|
||||
在開始本項目之前，你應該已經掌握以下內容：
|
||||
|
||||
- 前端頁面設計與組件庫使用（[UI 設計](../../frontend/ui-design/)、[現代組件庫](../../frontend/modern-component-library/)）
|
||||
- 後端接口設計與開發（[接口程式碼編寫](../../backend/ai-interface-code/)）
|
||||
- 資料庫基礎與 Supabase（[從資料庫到 Supabase](../../backend/database-supabase/)）
|
||||
- Git 工作流與部署（[Git 和 GitHub](../../backend/git-workflow/)、[部署 Web 應用](../../backend/zeabur-deployment/)）
|
||||
|
||||
## 學習目標
|
||||
|
||||
完成本實戰後，你將能夠：
|
||||
|
||||
1. 閱讀並理解一份真實的 PRD，從中提取開發任務清單
|
||||
2. 設計多角色系統的權限控制和頁面路由
|
||||
3. 使用 Express 實現完整的後端 API
|
||||
4. 實現考試、提交、自動判分的業務鏈路
|
||||
5. 完成端到端聯調，交付一個可演示的業務系統原型
|
||||
|
||||
## 項目簡介
|
||||
|
||||
你要構建的產品是一個在線考試與管理系統，包含三個子系統：
|
||||
|
||||
| 子系統 | 職責 |
|
||||
|--------|------|
|
||||
| **官網前臺** | 平臺介紹、登錄入口 |
|
||||
| **學生端** | 考試列表、答題、提交、成績查看 |
|
||||
| **管理後臺** | 題庫管理、考試管理、提交記錄、成績統計 |
|
||||
|
||||
後端使用 Express，需要支持：登錄鑑權、角色權限、考試和題庫管理、提交流程與自動判分、成績和統計管理。
|
||||
|
||||
::: tip PRD 入口
|
||||
本項目的需求文檔在 GitHub： [查看 PRD](https://github.com/datawhalechina/easy-vibe/blob/main/docs/zh-tw/stage-2/assignments/exam-management-express/PRD.md)
|
||||
:::
|
||||
|
||||
<div style="margin: 32px 0;">
|
||||
<ClientOnly>
|
||||
<StepBar :active="0" :items="[
|
||||
{ title: '需求分析', description: '閱讀 PRD，明確角色、頁面、考試鏈路和資料模型' },
|
||||
{ title: '搭建骨架', description: '用 AI 生成學生端和管理端頁面骨架' },
|
||||
{ title: '後端開發', description: 'Express 接通登錄、考試、提交、判分' },
|
||||
{ title: '聯調上線', description: '端到端跑通，部署並準備演示' }
|
||||
]" />
|
||||
</ClientOnly>
|
||||
</div>
|
||||
|
||||
## 第一部分：需求分析
|
||||
|
||||
### 1.1 閱讀 PRD
|
||||
|
||||
打開 PRD 文檔，重點回答以下問題：
|
||||
|
||||
- 系統包含哪幾個角色？各自能做什麼？
|
||||
- 頁面清單是否完整？學生端和管理端分別有哪些頁面？
|
||||
- 支持哪些題型？每種題型的判分邏輯是什麼？
|
||||
- 考試的完整流程是什麼？（發佈 → 開始 → 作答 → 提交 → 判分 → 查看成績）
|
||||
|
||||
::: warning
|
||||
如果以上問題沒有明確答案，不要開始寫程式碼。需求理解不清楚是導致返工的最常見原因。
|
||||
:::
|
||||
|
||||
### 1.2 確認系統架構
|
||||
|
||||
根據 PRD 梳理出系統的整體架構：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
prd["PRD"] --> web["官網前臺"]
|
||||
prd --> student["學生端"]
|
||||
prd --> admin["管理後臺"]
|
||||
student --> auth["鑑權"]
|
||||
student --> exam["考試與作答"]
|
||||
exam --> db["資料庫"]
|
||||
admin --> question["題庫管理"]
|
||||
admin --> submission["提交記錄與成績統計"]
|
||||
question --> db
|
||||
submission --> db
|
||||
```
|
||||
|
||||
## 第二部分：搭建項目骨架
|
||||
|
||||
### 2.1 生成前端頁面
|
||||
|
||||
提示詞參考：
|
||||
|
||||
```text
|
||||
請基於當前 PRD，幫我生成一個在線考試與管理系統的前端骨架。
|
||||
|
||||
技術棧要求：
|
||||
- Next.js App Router
|
||||
- TypeScript
|
||||
- Tailwind CSS
|
||||
- shadcn/ui
|
||||
|
||||
頁面清單：
|
||||
1. 首頁 /
|
||||
2. 登錄頁 /login
|
||||
3. 學生考試列表頁 /student/exams
|
||||
4. 學生答題頁 /student/exams/[id]
|
||||
5. 學生成績頁 /student/history
|
||||
6. 管理後臺首頁 /admin
|
||||
7. 考試管理頁 /admin/exams
|
||||
8. 題庫管理頁 /admin/questions
|
||||
9. 提交記錄頁 /admin/submissions
|
||||
|
||||
要求：
|
||||
- 學生端頁面強調清晰、專注、易答題
|
||||
- 管理端頁面使用側邊欄 + 頂部欄佈局
|
||||
- 先使用 mock 資料，不接真實接口
|
||||
- 注意桌面端和移動端的基本可用性
|
||||
```
|
||||
|
||||
### 2.2 完善學生答題頁
|
||||
|
||||
答題頁是學生端的核心頁面，重點完善：
|
||||
|
||||
```text
|
||||
請繼續完善學生答題頁。
|
||||
|
||||
這是一個在線考試系統的答題頁面，需要包含：
|
||||
- 頂部顯示考試標題、倒計時、已答題數量
|
||||
- 中間顯示題乾和選項
|
||||
- 支持單選、判斷、簡答三種題型
|
||||
- 左側或頂部有答題卡，顯示每道題是否已作答
|
||||
- 點擊提交前彈出確認框
|
||||
|
||||
先用 mock 資料實現交互，不接真實接口。
|
||||
|
||||
要求：
|
||||
- 界面簡潔，不要像後臺表格頁
|
||||
- 倒計時要醒目，但不要製造過強壓迫感
|
||||
- 有空狀態和 loading 狀態
|
||||
```
|
||||
|
||||
### 2.3 完善管理員後臺
|
||||
|
||||
管理員後臺第一版聚焦三個核心區域：
|
||||
|
||||
- **考試管理**：創建考試、設置時長、發佈狀態
|
||||
- **題庫管理**：新增題目、編輯題目、按題型篩選
|
||||
- **提交記錄**：查看學生提交、分數、時間
|
||||
|
||||
### 2.4 驗證頁面結構
|
||||
|
||||
逐項檢查：
|
||||
|
||||
- [ ] 學生端和管理端入口是否分開
|
||||
- [ ] 登錄頁、考試列表、答題頁、成績頁是否完整
|
||||
- [ ] 管理端題庫、考試管理、提交記錄頁是否可訪問
|
||||
- [ ] 學生端和管理端的頁面風格有明顯區分
|
||||
|
||||
### 遇到阻礙？
|
||||
|
||||
如果你在前端搭建階段卡住，可以回顧這些章節：
|
||||
|
||||
- [從資料庫到 Supabase](../../backend/database-supabase/)
|
||||
- [應用後端接口設計與開發](../../backend/ai-interface-code/)
|
||||
- [使用現代組件庫更新你的界面](../../frontend/modern-component-library/)
|
||||
|
||||
## 第三部分：後端開發
|
||||
|
||||
### 3.1 登錄與權限控制
|
||||
|
||||
```text
|
||||
請把我當成 0 基礎，幫我完成在線考試系統的登錄與權限控制。
|
||||
|
||||
後端使用 Express。
|
||||
|
||||
目標：
|
||||
1. 學生和管理員都可以登錄
|
||||
2. 登錄後返回用戶角色
|
||||
3. 學生只能訪問 /student/* 相關接口
|
||||
4. 管理員只能訪問 /admin/* 相關接口
|
||||
5. 未登錄用戶訪問受保護頁面時跳轉 /login
|
||||
|
||||
實現要求：
|
||||
- 給出清晰的目錄結構建議
|
||||
- 明確說明中間件負責什麼
|
||||
- 涉及環境變量的地方不要硬編碼
|
||||
- 完成後說明如何驗證權限是否生效
|
||||
```
|
||||
|
||||
### 3.2 考試與題庫管理接口
|
||||
|
||||
建議按以下模塊實現：
|
||||
|
||||
| 模塊 | 推薦接口 |
|
||||
|------|----------|
|
||||
| 考試管理 | `GET /api/exams`、`POST /api/admin/exams`、`PATCH /api/admin/exams/:id` |
|
||||
| 題庫管理 | `GET /api/admin/questions`、`POST /api/admin/questions` |
|
||||
| 開始考試 | `POST /api/submissions/start` |
|
||||
| 提交試卷 | `POST /api/submissions/:id/submit` |
|
||||
| 成績記錄 | `GET /api/student/history`、`GET /api/admin/submissions` |
|
||||
|
||||
提示詞參考：
|
||||
|
||||
```text
|
||||
請幫我為在線考試系統設計並實現 Express API。
|
||||
|
||||
功能範圍：
|
||||
- 管理員創建考試
|
||||
- 管理員維護題庫
|
||||
- 學生查看已發佈考試
|
||||
- 學生開始考試並創建 submission
|
||||
- 學生提交答案後自動判分單選題和判斷題
|
||||
- 簡答題先標記為待複核
|
||||
- 學生查看自己的歷史成績
|
||||
- 管理員查看所有提交記錄
|
||||
|
||||
要求：
|
||||
- 接口命名清晰
|
||||
- 返回統一 JSON 結構
|
||||
- 程式碼中區分 controller、service、middleware、db 層
|
||||
- 說明每個接口如何測試
|
||||
```
|
||||
|
||||
### 3.3 判分邏輯
|
||||
|
||||
判分邏輯是考試系統的核心業務規則：
|
||||
|
||||
- **單選題**：用戶答案與標準答案一致則得分
|
||||
- **判斷題**：同樣可以自動判分
|
||||
- **簡答題**：第一版先只保存答案，分數為空，狀態為 `reviewed = false`
|
||||
|
||||
::: tip 加分項
|
||||
如果你想增加 AI 能力，可以讓管理員在後臺輸入"主題 + 難度"，由模型先生成一批候選題，再人工審核後入庫。但這屬於加分項，不是必須的。
|
||||
:::
|
||||
|
||||
## 第四部分：聯調與上線
|
||||
|
||||
### 4.1 端到端測試
|
||||
|
||||
至少驗證以下場景：
|
||||
|
||||
- 學生登錄 → 查看考試列表 → 開始答題 → 提交 → 查看成績
|
||||
- 管理員登錄 → 創建考試 → 添加題目 → 發佈 → 查看提交記錄
|
||||
|
||||
### 4.2 部署
|
||||
|
||||
- 前端部署到 Vercel / Zeabur
|
||||
- Express API 部署到 Zeabur / Railway / Render
|
||||
- 資料庫用 Supabase Postgres 或託管 PostgreSQL
|
||||
|
||||
部署前檢查：
|
||||
|
||||
- [ ] 環境變量是否齊全
|
||||
- [ ] 前後端 API 地址是否正確
|
||||
- [ ] 登錄態在生產環境是否正常
|
||||
- [ ] 管理員賬號是否能真實訪問後臺
|
||||
- [ ] README 是否包含啟動、部署、測試說明
|
||||
|
||||
## 交付物
|
||||
|
||||
完成本項目後，你需要提交以下內容：
|
||||
|
||||
- [ ] 可訪問的線上演示鏈接
|
||||
- [ ] 源碼倉庫鏈接（含 README）
|
||||
- [ ] PRD 文檔
|
||||
- [ ] 核心頁面截圖（首頁、學生考試列表、答題頁、管理後臺）
|
||||
- [ ] 60 秒演示影片（覆蓋學生答題流程和管理員管理流程）
|
||||
|
||||
README 至少包含：項目簡介、核心頁面說明、技術棧、本地啟動步驟、環境變量清單。
|
||||
|
||||
## 評分標準
|
||||
|
||||
| 維度 | 基本要求 | 進階要求 |
|
||||
|------|---------|---------|
|
||||
| 頁面完整度 | 學生端和管理端主要頁面都可訪問 | 頁面風格統一，移動端基本可用 |
|
||||
| 業務閉環 | 學生可登錄、參加考試、提交併查看成績 | 管理員可完整創建併發布考試 |
|
||||
| 資料正確性 | 提交答案後能寫入資料庫，客觀題能自動判分 | 簡答題支持人工複核或 AI 輔助 |
|
||||
| 權限控制 | 學生與管理員訪問邊界清晰 | 服務端接口也有角色校驗 |
|
||||
| 工程交付 | 項目可運行、可部署、README 清晰 | 有演示影片和測試說明 |
|
||||
|
||||
## 提交前檢查
|
||||
|
||||
<el-card shadow="hover" style="margin: 20px 0; border-radius: 12px;">
|
||||
<template #header>
|
||||
<div style="font-weight: bold; font-size: 16px;">提交前最後看一眼</div>
|
||||
</template>
|
||||
|
||||
<ul style="list-style-type: none; padding-left: 0;">
|
||||
<li><label><input type="checkbox" disabled /> 首頁、登錄頁、學生端、管理端頁面均已完成</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 學生可以正常開始考試並提交答案</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 管理員可以創建考試並查看提交記錄</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 客觀題分數能夠自動計算並寫入資料庫</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 學生與管理員權限邊界已驗證</label></li>
|
||||
<li><label><input type="checkbox" disabled /> 項目已部署或具備完整本地運行說明</label></li>
|
||||
</ul>
|
||||
</el-card>
|
||||
|
||||
## 參考資料
|
||||
|
||||
- [UI 設計](../../frontend/ui-design/)
|
||||
- [使用現代組件庫更新你的界面](../../frontend/modern-component-library/)
|
||||
- [從資料庫到 Supabase](../../backend/database-supabase/)
|
||||
- [大模型輔助編寫接口程式碼與接口文檔](../../backend/ai-interface-code/)
|
||||
- [Git 和 GitHub 工作流](../../backend/git-workflow/)
|
||||
- [如何部署 Web 應用](../../backend/zeabur-deployment/)
|
||||
@@ -0,0 +1,211 @@
|
||||
# 現代 AI 生圖 SaaS 開發實戰
|
||||
|
||||
## 概述
|
||||
|
||||
本實戰項目要求你圍繞一份真實的 PRD（產品需求文檔），從零完成一個參考 Midjourney 體驗的 AI 生圖 SaaS 產品。你將完整經歷需求分析、項目拆解、迭代開發、聯調上線的全過程。
|
||||
|
||||
這是 Stage 2 的綜合實戰環節。在前面幾章中，你已經分別學習了前端頁面設計、後端接口開發、資料庫操作、支付集成等單項技能——這個項目要求你把它們全部串起來，交付一個可運行的產品原型。
|
||||
|
||||
## 前置知識
|
||||
|
||||
在開始本項目之前，你應該已經掌握以下內容：
|
||||
|
||||
- 前端頁面設計與組件庫使用（[UI 設計](../../frontend/ui-design/)、[現代組件庫](../../frontend/modern-component-library/)）
|
||||
- 後端接口設計與開發（[接口程式碼編寫](../../backend/ai-interface-code/)）
|
||||
- 資料庫基礎與 Supabase（[從資料庫到 Supabase](../../backend/database-supabase/)）
|
||||
- 支付集成（[Stripe 收費系統](../../backend/stripe-payment/)）
|
||||
- Git 工作流與部署（[Git 和 GitHub](../../backend/git-workflow/)、[部署 Web 應用](../../backend/zeabur-deployment/)）
|
||||
|
||||
## 學習目標
|
||||
|
||||
完成本實戰後，你將能夠：
|
||||
|
||||
1. 閱讀並理解一份真實的 PRD，從中提取開發任務清單
|
||||
2. 基於 PRD 拆分模塊，制定分步推進計劃
|
||||
3. 使用 AI 輔助完成前端骨架搭建和後端接口開發
|
||||
4. 對每個模塊進行驗證和迭代優化
|
||||
5. 完成端到端聯調，將項目從"能跑"推進到"能交付"
|
||||
|
||||
## 項目簡介
|
||||
|
||||
你要構建的產品是一個現代 AI 生圖 SaaS 平臺，包含三個子系統：
|
||||
|
||||
| 子系統 | 職責 |
|
||||
|--------|------|
|
||||
| **官網前臺** | 產品介紹、定價、FAQ、註冊轉化 |
|
||||
| **用戶工作臺** | Prompt 輸入、圖片生成、圖庫、積分、套餐、社區互動 |
|
||||
| **後臺管理臺** | 用戶管理、任務管理、支付管理、內容審核、SaaS 指標、系統監控 |
|
||||
|
||||
後端需要支持以下核心能力：用戶鑑權、圖片生成任務、OSS 對象存儲、積分與套餐支付、圖片社交互動、運營資料監控。
|
||||
|
||||
::: tip PRD 入口
|
||||
本項目的需求文檔在 GitHub： [查看 PRD](https://github.com/datawhalechina/easy-vibe/blob/main/docs/zh-tw/stage-2/assignments/modern-landing-page/PRD.md)
|
||||
:::
|
||||
|
||||
<div style="margin: 32px 0;">
|
||||
<ClientOnly>
|
||||
<StepBar :active="0" :items="[
|
||||
{ title: '需求分析', description: '閱讀 PRD，提取頁面、模塊、資料模型和邊界' },
|
||||
{ title: '搭建骨架', description: '用 AI 生成三套前端骨架（www / app / admin）' },
|
||||
{ title: '迭代開發', description: '逐模塊補充接口、權限、支付、監控' },
|
||||
{ title: '聯調上線', description: '端到端跑通，部署並準備演示' }
|
||||
]" />
|
||||
</ClientOnly>
|
||||
</div>
|
||||
|
||||
## 第一部分：需求分析
|
||||
|
||||
### 1.1 閱讀 PRD
|
||||
|
||||
打開 PRD 文檔，重點回答以下問題：
|
||||
|
||||
- 系統有幾個入口？各自覆蓋哪些頁面？
|
||||
- 每個頁面的核心功能是什麼？
|
||||
- 後端包含哪些模塊和資料庫表？
|
||||
- MVP 範圍是什麼？第一版哪些做，哪些不做？
|
||||
|
||||
::: warning
|
||||
如果以上問題沒有明確答案，不要開始寫程式碼。需求理解不清楚是導致返工的最常見原因。
|
||||
:::
|
||||
|
||||
### 1.2 確認系統架構
|
||||
|
||||
根據 PRD 中的描述，梳理出系統的整體架構：
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
prd["PRD"] --> web["官網前臺"]
|
||||
prd --> app["用戶工作臺"]
|
||||
prd --> admin["後臺管理臺"]
|
||||
app --> auth["鑑權"]
|
||||
app --> gen["圖片生成任務"]
|
||||
gen --> oss["OSS 對象存儲"]
|
||||
gen --> db["資料庫"]
|
||||
billing["支付與套餐"] --> db
|
||||
social["分享 / 點贊 / 評論 / 轉發"] --> db
|
||||
admin --> analytics["SaaS 指標看板"]
|
||||
admin --> observability["API / DB / Provider 監控"]
|
||||
```
|
||||
|
||||
建議你用自己的話把架構圖畫一遍，確認你對系統的理解是完整的。
|
||||
|
||||
## 第二部分：搭建項目骨架
|
||||
|
||||
### 2.1 生成前端頁面
|
||||
|
||||
使用 AI 先生成所有頁面的基本結構和假資料。這一步的目標是搭出資訊架構和路由，不需要接真實接口。
|
||||
|
||||
提示詞參考：
|
||||
|
||||
```text
|
||||
請基於當前 PRD，幫我生成一個現代 AI 生圖 SaaS 的前端骨架。
|
||||
|
||||
要求：
|
||||
1. 分成三個入口：www、app、admin
|
||||
2. 官網包括：首頁、定價、FAQ
|
||||
3. app 包括：登錄、註冊、生成工作臺、圖庫、套餐、積分、社區、作品詳情、個人中心
|
||||
4. admin 包括：後臺首頁、用戶管理、任務管理、內容管理、套餐管理、支付訂單、運營配置、SaaS 指標、系統監控
|
||||
5. 先只生成頁面結構和假資料，不接真實接口
|
||||
6. 風格參考 Midjourney，簡潔、現代、帶產品感
|
||||
```
|
||||
|
||||
### 2.2 驗證頁面結構
|
||||
|
||||
骨架生成後，逐項檢查：
|
||||
|
||||
- [ ] 三個入口的路由是否獨立（`/`、`/app`、`/admin`）
|
||||
- [ ] 頁面數量是否與 PRD 一致
|
||||
- [ ] 每個頁面是否可以正常訪問和導航
|
||||
- [ ] 假資料是否展示了基本的 UI 狀態（列表、空狀態、表單等）
|
||||
|
||||
## 第三部分：迭代開發
|
||||
|
||||
### 3.1 按模塊推進
|
||||
|
||||
在骨架的基礎上，按以下順序逐模塊補充功能：
|
||||
|
||||
1. **鑑權**：註冊、登錄、角色區分
|
||||
2. **資料庫**：資料表創建、讀寫接口
|
||||
3. **核心業務**：圖片生成任務、結果存儲
|
||||
4. **OSS 存儲**：圖片上傳與訪問
|
||||
5. **支付**：套餐、積分、Stripe 集成
|
||||
6. **社交互動**：分享、點贊、評論
|
||||
7. **後臺管理**：用戶管理、任務管理、內容審核
|
||||
8. **資料監控**：SaaS 指標看板、系統監控
|
||||
|
||||
每完成一個模塊，使用下表進行自檢：
|
||||
|
||||
| 檢查項 | 驗證方法 |
|
||||
|--------|----------|
|
||||
| 頁面一致性 | 頁面數量、入口、功能是否符合 PRD |
|
||||
| 接口正確性 | 請求參數、返回結構、狀態處理是否合理 |
|
||||
| 權限隔離 | 普通用戶和管理員是否互相隔離 |
|
||||
| 資料一致性 | 資料庫、OSS、支付、積分是否對得上 |
|
||||
| 可演示性 | 是否能給別人完整演示一條業務鏈路 |
|
||||
|
||||
::: tip
|
||||
如果發現 AI 生成的內容偏離了 PRD，不要整頁推翻重來，直接讓它修改具體模塊即可。
|
||||
:::
|
||||
|
||||
### 3.2 角色與分工
|
||||
|
||||
在迭代過程中，你需要同時扮演三個角色：
|
||||
|
||||
- **產品經理**：確認每個模塊的功能是否符合 PRD
|
||||
- **技術負責人**：確認實現方案是否合理
|
||||
- **測試工程師**：確認功能是否跑得通
|
||||
|
||||
## 第四部分：聯調與上線
|
||||
|
||||
### 4.1 端到端測試
|
||||
|
||||
最後階段的重點不是補新頁面，而是把完整業務鏈路跑通。至少驗證以下場景：
|
||||
|
||||
- 註冊 → 購買積分 → 生成圖片 → 查看歷史 → 分享互動
|
||||
- 管理員登錄 → 查看用戶資料 → 查看任務統計 → 查看系統監控
|
||||
|
||||
### 4.2 部署
|
||||
|
||||
將項目部署到公網環境，確保：
|
||||
|
||||
- 環境變量配置完整
|
||||
- 登錄回調地址正確
|
||||
- 支付回調地址正確
|
||||
- 頁面無缺失的 loading、空狀態、錯誤提示
|
||||
|
||||
部署教程參考：[Git 和 GitHub 工作流](../../backend/git-workflow/)、[如何部署 Web 應用](../../backend/zeabur-deployment/)。
|
||||
|
||||
## 交付物
|
||||
|
||||
完成本項目後，你需要提交以下內容：
|
||||
|
||||
- [ ] 可訪問的線上演示鏈接
|
||||
- [ ] 源碼倉庫鏈接（含 README）
|
||||
- [ ] PRD 文檔
|
||||
- [ ] 核心頁面截圖（官網首頁、生圖工作臺、圖庫、套餐頁、後臺首頁）
|
||||
- [ ] 60 秒演示影片（覆蓋註冊 → 生成 → 查看 → 後臺管理）
|
||||
|
||||
README 至少包含：項目簡介、核心頁面說明、技術棧、本地啟動步驟、環境變量清單。
|
||||
|
||||
## 評分標準
|
||||
|
||||
| 維度 | 基本要求 | 進階要求 |
|
||||
|------|---------|---------|
|
||||
| PRD 對齊 | 頁面、功能、資料結構基本符合 PRD | 能清晰說明每個設計決策與 PRD 的對應關係 |
|
||||
| 產品閉環 | 註冊 → 購買積分 → 生成圖片 → 查看歷史 → 分享互動可跑通 | 支付狀態、積分餘額、生成次數資料一致 |
|
||||
| 後臺能力 | 用戶、任務、支付、內容管理可查看 | SaaS 指標看板和系統監控頁完整可用 |
|
||||
| 工程完整度 | 前端、後端、資料庫、OSS、支付鏈路已接通 | 有錯誤處理、空狀態、loading 狀態 |
|
||||
| 交付質量 | 可部署、可運行 | README 清楚、演示影片結構完整 |
|
||||
|
||||
## 參考資料
|
||||
|
||||
- [UI 設計](../../frontend/ui-design/)
|
||||
- [參考 UI 設計規範設計頁面和按鈕](../../frontend/multi-product-ui/)
|
||||
- [用 LLM 和 Skills 讓界面變好看](../../frontend/llm-skills-beautiful/)
|
||||
- [從設計原型到項目程式碼](../../frontend/design-to-code/)
|
||||
- [使用現代組件庫更新你的界面](../../frontend/modern-component-library/)
|
||||
- [從資料庫到 Supabase](../../backend/database-supabase/)
|
||||
- [大模型輔助編寫接口程式碼與接口文檔](../../backend/ai-interface-code/)
|
||||
- [Git 和 GitHub 工作流](../../backend/git-workflow/)
|
||||
- [如何部署 Web 應用](../../backend/zeabur-deployment/)
|
||||
- [如何集成 Stripe 等收費系統](../../backend/stripe-payment/)
|
||||
@@ -0,0 +1,162 @@
|
||||
# Spring Boot 電影推薦系統開發實戰
|
||||
|
||||
## 概述
|
||||
|
||||
本實戰項目要求你圍繞一份真實的 PRD，使用 Spring Boot 完成一個帶推薦能力的電影網站。這個項目的核心挑戰在於：它不是簡單的增刪改查，而是需要你思考"用戶行為如何影響推薦結果"以及"推薦如何可解釋"。
|
||||
|
||||
這是 Stage 2 的綜合實戰環節。你將第一次接觸"內容 + 行為 + 推薦"型產品的開發模式，這種模式在電商、內容平臺、個性化 Feed 等場景中非常常見。
|
||||
|
||||
## 前置知識
|
||||
|
||||
在開始本項目之前，你應該已經掌握以下內容：
|
||||
|
||||
- 前端頁面設計與組件庫使用（[UI 設計](../../frontend/ui-design/)、[現代組件庫](../../frontend/modern-component-library/)）
|
||||
- 後端接口設計與開發（[接口程式碼編寫](../../backend/ai-interface-code/)）
|
||||
- 資料庫基礎與 Supabase（[從資料庫到 Supabase](../../backend/database-supabase/)）
|
||||
- Git 工作流與部署（[Git 和 GitHub](../../backend/git-workflow/)、[部署 Web 應用](../../backend/zeabur-deployment/)）
|
||||
|
||||
## 學習目標
|
||||
|
||||
完成本實戰後，你將能夠：
|
||||
|
||||
1. 閱讀 PRD 並從中提取推薦系統的開發任務清單
|
||||
2. 使用 Spring Boot 搭建後端項目並實現 RESTful API
|
||||
3. 設計"用戶行為 → 推薦"的完整資料鏈路
|
||||
4. 實現可解釋的推薦邏輯
|
||||
5. 完成端到端聯調，交付可演示的產品原型
|
||||
|
||||
## 項目簡介
|
||||
|
||||
你要構建的產品是一個帶推薦能力的電影網站：
|
||||
|
||||
| 功能 | 描述 |
|
||||
|------|------|
|
||||
| **瀏覽與搜索** | 用戶可以瀏覽和搜索電影 |
|
||||
| **評分與收藏** | 用戶可以給電影評分、添加收藏 |
|
||||
| **個性化推薦** | 系統根據用戶行為給出推薦結果 |
|
||||
| **管理後臺** | 管理員維護電影資料、查看推薦效果 |
|
||||
|
||||
::: tip PRD 入口
|
||||
本項目的需求文檔在 GitHub： [查看 PRD](https://github.com/datawhalechina/easy-vibe/blob/main/docs/zh-tw/stage-2/assignments/movie-recommendation-springboot/PRD.md)
|
||||
:::
|
||||
|
||||
<div style="margin: 32px 0;">
|
||||
<ClientOnly>
|
||||
<StepBar :active="0" :items="[
|
||||
{ title: '需求分析', description: '閱讀 PRD，明確推薦策略、行為資料和後臺範圍' },
|
||||
{ title: '搭建骨架', description: '用 AI 生成列表頁、詳情頁、推薦頁和後臺頁' },
|
||||
{ title: '迭代開發', description: '補充推薦邏輯、行為記錄和後臺管理' },
|
||||
{ title: '聯調上線', description: '端到端跑通，部署並準備演示' }
|
||||
]" />
|
||||
</ClientOnly>
|
||||
</div>
|
||||
|
||||
## 第一部分：需求分析
|
||||
|
||||
### 1.1 閱讀 PRD
|
||||
|
||||
打開 PRD 文檔，重點回答以下問題：
|
||||
|
||||
- 推薦策略是什麼？第一版是否使用可解釋版本（如基於評分相似度）？
|
||||
- 用戶行為資料要存哪些？（評分、收藏、瀏覽記錄等）
|
||||
- 管理員需要看哪些推薦效果指標？
|
||||
- 頁面清單是否完整？
|
||||
|
||||
::: warning
|
||||
如果以上問題沒有明確答案，不要開始寫程式碼。需求理解不清楚是導致返工的最常見原因。
|
||||
:::
|
||||
|
||||
### 1.2 確認系統架構
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
prd["PRD"] --> web["前端頁面"]
|
||||
web --> auth["用戶鑑權"]
|
||||
web --> movie["電影列表 / 詳情"]
|
||||
web --> behavior["評分 / 收藏"]
|
||||
behavior --> reco["推薦邏輯"]
|
||||
reco --> db["資料庫"]
|
||||
admin["後臺管理"] --> db
|
||||
```
|
||||
|
||||
## 第二部分：搭建項目骨架
|
||||
|
||||
### 2.1 生成前端頁面
|
||||
|
||||
提示詞參考：
|
||||
|
||||
```text
|
||||
請基於當前 PRD，幫我生成一個 Spring Boot 電影推薦系統的前端骨架。
|
||||
|
||||
要求：
|
||||
1. 頁面包括：首頁、電影列表、電影詳情、推薦頁、個人中心、後臺管理
|
||||
2. 先只生成頁面結構和假資料，不接真實接口
|
||||
3. 風格要像真實內容產品，而不是課堂 demo
|
||||
```
|
||||
|
||||
### 2.2 驗證頁面結構
|
||||
|
||||
逐項檢查：
|
||||
|
||||
- [ ] 電影列表頁支持搜索和篩選
|
||||
- [ ] 電影詳情頁包含評分和收藏按鈕
|
||||
- [ ] 推薦頁能展示推薦結果和推薦理由
|
||||
- [ ] 管理後臺能展示電影資料和推薦效果
|
||||
|
||||
## 第三部分：迭代開發
|
||||
|
||||
### 3.1 按模塊推進
|
||||
|
||||
1. **Spring Boot 項目搭建**：項目結構、資料庫配置、基礎 CRUD
|
||||
2. **電影資料管理**：電影列表、詳情、搜索接口
|
||||
3. **用戶行為**：評分、收藏接口，行為資料寫入
|
||||
4. **推薦邏輯**：基於用戶行為的推薦算法實現
|
||||
5. **推薦展示**：推薦結果展示，包含推薦理由
|
||||
6. **管理後臺**：電影資料維護、推薦效果查看
|
||||
|
||||
### 3.2 模塊自檢
|
||||
|
||||
| 檢查項 | 驗證方法 |
|
||||
|--------|----------|
|
||||
| 基礎功能 | 列表、詳情、評分、收藏是否閉環 |
|
||||
| 推薦聯動 | 用戶行為是否影響推薦結果 |
|
||||
| 推薦可解釋性 | 用戶能理解為什麼被推薦這些電影 |
|
||||
| 後臺資料 | 管理員能查看電影資料和推薦效果 |
|
||||
|
||||
## 第四部分：聯調與上線
|
||||
|
||||
### 4.1 端到端測試
|
||||
|
||||
至少驗證以下場景：
|
||||
|
||||
- 瀏覽電影 → 評分 → 收藏 → 查看推薦頁，確認推薦結果發生變化
|
||||
- 管理員登錄 → 添加電影 → 查看推薦效果統計
|
||||
|
||||
## 交付物
|
||||
|
||||
完成本項目後，你需要提交以下內容：
|
||||
|
||||
- [ ] 可訪問的線上演示鏈接
|
||||
- [ ] 源碼倉庫鏈接（含 README）
|
||||
- [ ] PRD 文檔
|
||||
- [ ] 核心頁面截圖（電影列表、電影詳情、推薦頁、管理後臺）
|
||||
- [ ] 60 秒演示影片
|
||||
|
||||
## 評分標準
|
||||
|
||||
| 維度 | 基本要求 | 進階要求 |
|
||||
|------|---------|---------|
|
||||
| PRD 對齊 | 頁面、功能、資料結構基本符合 PRD | 能清晰說明設計決策 |
|
||||
| 產品閉環 | 瀏覽 → 評分 → 收藏 → 推薦可跑通 | 評分行為明顯影響推薦結果 |
|
||||
| 推薦質量 | 推薦結果合理、推薦理由可解釋 | 支持多種推薦策略 |
|
||||
| 後臺能力 | 電影資料和推薦效果可查看 | 有推薦準確率等統計指標 |
|
||||
| 工程完整度 | 前端、Spring Boot 後端、資料庫鏈路已接通 | 推薦接口有緩存或性能優化 |
|
||||
|
||||
## 參考資料
|
||||
|
||||
- [UI 設計](../../frontend/ui-design/)
|
||||
- [使用現代組件庫更新你的界面](../../frontend/modern-component-library/)
|
||||
- [從資料庫到 Supabase](../../backend/database-supabase/)
|
||||
- [大模型輔助編寫接口程式碼與接口文檔](../../backend/ai-interface-code/)
|
||||
- [Git 和 GitHub 工作流](../../backend/git-workflow/)
|
||||
- [如何部署 Web 應用](../../backend/zeabur-deployment/)
|
||||
@@ -0,0 +1,172 @@
|
||||
# 生鮮電商微服務系統開發實戰
|
||||
|
||||
## 概述
|
||||
|
||||
本實戰項目要求你圍繞一份真實的 PRD，從零完成一個生鮮電商微服務系統。與前面的單服務項目不同，這個項目的後端按業務拆分成多個獨立服務，通過 API 網關統一對外。你將學習如何設計服務邊界、如何處理跨服務的資料一致性問題。
|
||||
|
||||
這是 Stage 2 的綜合實戰環節。微服務架構在實際工作中非常常見，掌握服務拆分和網關路由的基本思路後，你能夠應對更復雜的後端系統設計。
|
||||
|
||||
## 前置知識
|
||||
|
||||
在開始本項目之前，你應該已經掌握以下內容：
|
||||
|
||||
- 前端頁面設計與組件庫使用（[UI 設計](../../frontend/ui-design/)、[現代組件庫](../../frontend/modern-component-library/)）
|
||||
- 後端接口設計與開發（[接口程式碼編寫](../../backend/ai-interface-code/)）
|
||||
- 資料庫基礎與 Supabase（[從資料庫到 Supabase](../../backend/database-supabase/)）
|
||||
- Git 工作流與部署（[Git 和 GitHub](../../backend/git-workflow/)、[部署 Web 應用](../../backend/zeabur-deployment/)）
|
||||
|
||||
## 學習目標
|
||||
|
||||
完成本實戰後，你將能夠：
|
||||
|
||||
1. 閱讀 PRD 並提取微服務系統的開發任務清單
|
||||
2. 按業務領域拆分服務邊界（鑑權、商品、庫存、訂單）
|
||||
3. 設計和實現 API 網關路由
|
||||
4. 處理庫存扣減和訂單一致性等跨服務問題
|
||||
5. 完成端到端聯調，交付可演示的微服務原型
|
||||
|
||||
## 項目簡介
|
||||
|
||||
你要構建的產品是一個生鮮電商微服務系統：
|
||||
|
||||
| 子系統 | 職責 |
|
||||
|--------|------|
|
||||
| **用戶端** | 瀏覽商品、下單、查看訂單 |
|
||||
| **管理端** | 商品管理、庫存管理、訂單管理 |
|
||||
|
||||
後端按業務拆分為以下服務：
|
||||
|
||||
| 服務 | 職責 |
|
||||
|------|------|
|
||||
| **API Gateway** | 統一入口、路由轉發、鑑權校驗 |
|
||||
| **Auth Service** | 用戶註冊、登錄、JWT 頒發 |
|
||||
| **Catalog Service** | 商品資訊管理 |
|
||||
| **Inventory Service** | 庫存數量管理 |
|
||||
| **Order Service** | 訂單創建、狀態管理 |
|
||||
|
||||
::: tip PRD 入口
|
||||
本項目的需求文檔在 GitHub： [查看 PRD](https://github.com/datawhalechina/easy-vibe/blob/main/docs/zh-tw/stage-2/assignments/simple-grocery-microservices/PRD.md)
|
||||
:::
|
||||
|
||||
<div style="margin: 32px 0;">
|
||||
<ClientOnly>
|
||||
<StepBar :active="0" :items="[
|
||||
{ title: '需求分析', description: '閱讀 PRD，明確服務拆分、頁面和交易鏈路' },
|
||||
{ title: '搭建骨架', description: '生成前端、網關和各服務骨架' },
|
||||
{ title: '迭代開發', description: '逐模塊補接口、修庫存與訂單一致性' },
|
||||
{ title: '聯調上線', description: '端到端跑通，部署並準備演示' }
|
||||
]" />
|
||||
</ClientOnly>
|
||||
</div>
|
||||
|
||||
## 第一部分：需求分析
|
||||
|
||||
### 1.1 閱讀 PRD
|
||||
|
||||
打開 PRD 文檔，重點回答以下問題：
|
||||
|
||||
- 服務如何拆分？每個服務的職責邊界是什麼？
|
||||
- 前臺和管理端分別有哪些頁面？
|
||||
- 下單後庫存扣減的策略是什麼？成功 / 失敗 / 超時各怎麼處理？
|
||||
- 第一版哪些複雜能力（如分佈式事務、消息隊列）先不做？
|
||||
|
||||
::: warning
|
||||
如果以上問題沒有明確答案，不要開始寫程式碼。需求理解不清楚是導致返工的最常見原因。
|
||||
:::
|
||||
|
||||
### 1.2 確認系統架構
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
prd["PRD"] --> fe["前端頁面"]
|
||||
fe --> gw["API Gateway"]
|
||||
gw --> auth["Auth Service"]
|
||||
gw --> catalog["Catalog Service"]
|
||||
gw --> inventory["Inventory Service"]
|
||||
gw --> order["Order Service"]
|
||||
order --> inventory
|
||||
```
|
||||
|
||||
## 第二部分：搭建項目骨架
|
||||
|
||||
### 2.1 生成項目結構
|
||||
|
||||
提示詞參考：
|
||||
|
||||
```text
|
||||
請基於當前 PRD，幫我生成一個生鮮電商微服務系統的項目骨架。
|
||||
|
||||
要求：
|
||||
1. 生成前端用戶端和管理端骨架
|
||||
2. 生成 api-gateway、auth-service、catalog-service、inventory-service、order-service 五個目錄
|
||||
3. 每個服務先只做最小可運行入口
|
||||
4. 先不接真實資料庫和支付
|
||||
```
|
||||
|
||||
### 2.2 驗證項目結構
|
||||
|
||||
逐項檢查：
|
||||
|
||||
- [ ] 五個服務目錄結構清晰
|
||||
- [ ] API Gateway 可以啟動並轉發請求
|
||||
- [ ] 各服務健康檢查接口可用
|
||||
- [ ] 前端用戶端和管理端頁面可訪問
|
||||
|
||||
## 第三部分：迭代開發
|
||||
|
||||
### 3.1 按模塊推進
|
||||
|
||||
1. **API Gateway**：路由配置、JWT 校驗中間件
|
||||
2. **Auth Service**：註冊、登錄、JWT 頒發
|
||||
3. **Catalog Service**：商品 CRUD、列表查詢
|
||||
4. **Inventory Service**：庫存查詢、庫存扣減
|
||||
5. **Order Service**：訂單創建、狀態流轉、庫存聯動
|
||||
6. **管理端**：商品管理、庫存管理、訂單管理
|
||||
|
||||
### 3.2 模塊自檢
|
||||
|
||||
| 檢查項 | 驗證方法 |
|
||||
|--------|----------|
|
||||
| 網關路由 | 各服務接口是否通過網關正確轉發 |
|
||||
| 權限隔離 | 用戶端和管理端接口是否隔離 |
|
||||
| 資料一致 | 商品和庫存資料是否同步 |
|
||||
| 交易閉環 | 下單後庫存扣減、訂單狀態是否一致 |
|
||||
| 失敗處理 | 庫存不足或超時時是否有補償機制 |
|
||||
|
||||
## 第四部分：聯調與上線
|
||||
|
||||
### 4.1 端到端測試
|
||||
|
||||
至少驗證以下場景：
|
||||
|
||||
- 瀏覽商品 → 加入購物車 → 下單 → 查看訂單
|
||||
- 管理員 → 添加商品 → 更新庫存 → 查看訂單
|
||||
|
||||
## 交付物
|
||||
|
||||
完成本項目後，你需要提交以下內容：
|
||||
|
||||
- [ ] 可訪問的線上演示鏈接
|
||||
- [ ] 源碼倉庫鏈接（含 README）
|
||||
- [ ] PRD 文檔
|
||||
- [ ] 核心頁面截圖（商品列表、下單頁、訂單頁、管理後臺）
|
||||
- [ ] 60 秒演示影片
|
||||
|
||||
## 評分標準
|
||||
|
||||
| 維度 | 基本要求 | 進階要求 |
|
||||
|------|---------|---------|
|
||||
| PRD 對齊 | 頁面、功能、服務拆分基本符合 PRD | 能清晰說明服務拆分的理由 |
|
||||
| 產品閉環 | 瀏覽 → 下單 → 庫存扣減 → 查看訂單可跑通 | 訂單超時或庫存不足有補償機制 |
|
||||
| 服務架構 | 各服務可獨立啟動，通過網關統一訪問 | 服務間通信有錯誤處理和重試 |
|
||||
| 後臺能力 | 商品、庫存、訂單管理可操作 | 管理端有資料統計 |
|
||||
| 工程完整度 | 前端、網關、服務、資料庫鏈路已接通 | 有 Docker Compose 或類似編排 |
|
||||
|
||||
## 參考資料
|
||||
|
||||
- [UI 設計](../../frontend/ui-design/)
|
||||
- [使用現代組件庫更新你的界面](../../frontend/modern-component-library/)
|
||||
- [從資料庫到 Supabase](../../backend/database-supabase/)
|
||||
- [大模型輔助編寫接口程式碼與接口文檔](../../backend/ai-interface-code/)
|
||||
- [Git 和 GitHub 工作流](../../backend/git-workflow/)
|
||||
- [如何部署 Web 應用](../../backend/zeabur-deployment/)
|
||||
@@ -0,0 +1,163 @@
|
||||
# Go 交通資料分析平臺開發實戰
|
||||
|
||||
## 概述
|
||||
|
||||
本實戰項目要求你圍繞一份真實的 PRD，使用 Go 完成一個交通資料分析平臺。這個項目的方向與前面的增刪改查系統不同——你需要構建一條"資料接入 → 聚合 → 告警 → 可視化"的完整資料鏈路。這種資料產品在 IoT、監控、運營分析等場景中非常常見。
|
||||
|
||||
這是 Stage 2 的綜合實戰環節，也是你第一次接觸 Go 語言。不用擔心，有了前面 JavaScript / TypeScript 的基礎，學習 Go 並不難——重點是理解資料鏈路的設計思路。
|
||||
|
||||
## 前置知識
|
||||
|
||||
在開始本項目之前，你應該已經掌握以下內容：
|
||||
|
||||
- 前端頁面設計與組件庫使用（[UI 設計](../../frontend/ui-design/)、[現代組件庫](../../frontend/modern-component-library/)）
|
||||
- 後端接口設計與開發（[接口程式碼編寫](../../backend/ai-interface-code/)）
|
||||
- 資料庫基礎與 Supabase（[從資料庫到 Supabase](../../backend/database-supabase/)）
|
||||
- Git 工作流與部署（[Git 和 GitHub](../../backend/git-workflow/)、[部署 Web 應用](../../backend/zeabur-deployment/)）
|
||||
|
||||
## 學習目標
|
||||
|
||||
完成本實戰後，你將能夠：
|
||||
|
||||
1. 閱讀 PRD 並提取資料產品的開發任務清單
|
||||
2. 使用 Go（Gin 或 Fiber）搭建後端 API 服務
|
||||
3. 設計資料接入、窗口聚合和告警的完整鏈路
|
||||
4. 讓後端資料和前端看板保持一致
|
||||
5. 完成端到端聯調，交付可演示的資料產品原型
|
||||
|
||||
## 項目簡介
|
||||
|
||||
你要構建的產品是一個 Go 交通資料分析平臺：
|
||||
|
||||
| 模塊 | 職責 |
|
||||
|------|------|
|
||||
| **資料接入** | 接收原始交通事件併入庫 |
|
||||
| **資料聚合** | 按時間窗口計算趨勢和擁堵指標 |
|
||||
| **告警** | 基於規則生成告警記錄 |
|
||||
| **看板展示** | 在前端展示趨勢圖、排行榜和告警列表 |
|
||||
|
||||
::: tip PRD 入口
|
||||
本項目的需求文檔在 GitHub： [查看 PRD](https://github.com/datawhalechina/easy-vibe/blob/main/docs/zh-tw/stage-2/assignments/traffic-data-visualization-go/PRD.md)
|
||||
:::
|
||||
|
||||
<div style="margin: 32px 0;">
|
||||
<ClientOnly>
|
||||
<StepBar :active="0" :items="[
|
||||
{ title: '需求分析', description: '閱讀 PRD，明確資料來源、指標口徑和告警規則' },
|
||||
{ title: '搭建骨架', description: '用 AI 生成 Go API 服務和前端看板骨架' },
|
||||
{ title: '迭代開發', description: '補充聚合邏輯、告警規則和看板接口' },
|
||||
{ title: '聯調上線', description: '端到端跑通，部署並準備演示' }
|
||||
]" />
|
||||
</ClientOnly>
|
||||
</div>
|
||||
|
||||
## 第一部分：需求分析
|
||||
|
||||
### 1.1 閱讀 PRD
|
||||
|
||||
打開 PRD 文檔，重點回答以下問題：
|
||||
|
||||
- 資料來源是什麼？字段有哪些？
|
||||
- 核心指標的定義是什麼？（比如"擁堵"的具體標準）
|
||||
- 告警規則是什麼？第一版是否先收斂到簡單規則？
|
||||
- 看板包含哪些頁面和圖表？
|
||||
|
||||
::: warning
|
||||
如果以上問題沒有明確答案，不要開始寫程式碼。需求理解不清楚是導致返工的最常見原因。
|
||||
:::
|
||||
|
||||
### 1.2 確認資料鏈路
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
prd["PRD"] --> ingest["資料接入 API"]
|
||||
ingest --> raw["原始資料表"]
|
||||
raw --> agg["聚合任務"]
|
||||
agg --> alert["告警規則"]
|
||||
agg --> dashboard["看板接口"]
|
||||
alert --> dashboard
|
||||
```
|
||||
|
||||
## 第二部分：搭建項目骨架
|
||||
|
||||
### 2.1 生成 Go API 服務
|
||||
|
||||
提示詞參考：
|
||||
|
||||
```text
|
||||
請基於當前 PRD，幫我生成一個 Go 交通資料分析平臺骨架。
|
||||
|
||||
要求：
|
||||
1. 使用 Gin 或 Fiber
|
||||
2. 提供資料接入接口
|
||||
3. 提供聚合任務骨架
|
||||
4. 提供 dashboard 和 alerts 接口骨架
|
||||
5. 先不做真實複雜分析，只做可運行結構
|
||||
```
|
||||
|
||||
### 2.2 驗證項目結構
|
||||
|
||||
逐項檢查：
|
||||
|
||||
- [ ] Go 服務可以正常啟動
|
||||
- [ ] 資料接入接口可接收並存儲資料
|
||||
- [ ] 聚合任務框架已搭好
|
||||
- [ ] 前端看板頁面可展示基本圖表
|
||||
|
||||
## 第三部分：迭代開發
|
||||
|
||||
### 3.1 按模塊推進
|
||||
|
||||
1. **資料接入 API**：接收原始交通事件，寫入資料庫
|
||||
2. **資料聚合**：按時間窗口聚合，計算趨勢和擁堵指標
|
||||
3. **告警規則**：基於閾值生成告警記錄
|
||||
4. **看板接口**：提供趨勢資料、排行資料、告警列表
|
||||
5. **前端看板**：趨勢圖、排行榜、告警列表頁面
|
||||
|
||||
### 3.2 模塊自檢
|
||||
|
||||
| 檢查項 | 驗證方法 |
|
||||
|--------|----------|
|
||||
| 資料接入 | 原始資料是否正確入庫 |
|
||||
| 聚合口徑 | 趨勢、排名指標的計算邏輯是否一致 |
|
||||
| 告警規則 | 告警觸發條件是否符合預期 |
|
||||
| 資料一致性 | 看板展示和後端資料是否對得上 |
|
||||
| API 規範 | 是否有統一返回結構和錯誤處理 |
|
||||
|
||||
## 第四部分：聯調與上線
|
||||
|
||||
### 4.1 端到端測試
|
||||
|
||||
至少驗證以下場景：
|
||||
|
||||
- 接入一批測試資料 → 聚合任務執行 → 看板展示更新
|
||||
- 觸發告警條件 → 告警記錄生成 → 告警頁面顯示
|
||||
|
||||
## 交付物
|
||||
|
||||
完成本項目後，你需要提交以下內容：
|
||||
|
||||
- [ ] 可訪問的線上演示鏈接
|
||||
- [ ] 源碼倉庫鏈接（含 README）
|
||||
- [ ] PRD 文檔
|
||||
- [ ] 核心頁面截圖（資料接入演示、趨勢看板、告警列表）
|
||||
- [ ] 60 秒演示影片
|
||||
|
||||
## 評分標準
|
||||
|
||||
| 維度 | 基本要求 | 進階要求 |
|
||||
|------|---------|---------|
|
||||
| PRD 對齊 | 功能和資料結構基本符合 PRD | 能清晰說明指標口徑和聚合邏輯 |
|
||||
| 資料鏈路 | 接入 → 聚合 → 告警 → 看板可跑通 | 聚合任務支持增量更新 |
|
||||
| 分析能力 | 趨勢、排行、告警三個模塊可用 | 指標可配置、告警規則可自定義 |
|
||||
| 前端展示 | 看板能展示基本圖表 | 圖表支持時間範圍篩選 |
|
||||
| 工程完整度 | Go API、資料庫、前端鏈路已接通 | API 有統一錯誤處理和日誌 |
|
||||
|
||||
## 參考資料
|
||||
|
||||
- [UI 設計](../../frontend/ui-design/)
|
||||
- [使用現代組件庫更新你的界面](../../frontend/modern-component-library/)
|
||||
- [從資料庫到 Supabase](../../backend/database-supabase/)
|
||||
- [大模型輔助編寫接口程式碼與接口文檔](../../backend/ai-interface-code/)
|
||||
- [Git 和 GitHub 工作流](../../backend/git-workflow/)
|
||||
- [如何部署 Web 應用](../../backend/zeabur-deployment/)
|
||||
@@ -0,0 +1,164 @@
|
||||
# 智能旅遊規劃 Agent 平臺開發實戰
|
||||
|
||||
## 概述
|
||||
|
||||
本實戰項目要求你圍繞一份真實的 PRD，從零完成一個智能旅遊規劃 Agent 平臺。你將構建一個能接收結構化輸入、生成每日行程、支持保存和重用的完整 AI 產品——不只是聊天機器人，而是一個有任務管理能力的產品。
|
||||
|
||||
這是 Stage 2 的綜合實戰環節。這個項目的核心挑戰在於：如何讓 AI 生成結構化、可用的行程規劃，而不是一大段不可操作的文字。
|
||||
|
||||
## 前置知識
|
||||
|
||||
在開始本項目之前，你應該已經掌握以下內容：
|
||||
|
||||
- 前端頁面設計與組件庫使用（[UI 設計](../../frontend/ui-design/)、[現代組件庫](../../frontend/modern-component-library/)）
|
||||
- 後端接口設計與開發（[接口程式碼編寫](../../backend/ai-interface-code/)）
|
||||
- 資料庫基礎與 Supabase（[從資料庫到 Supabase](../../backend/database-supabase/)）
|
||||
- Git 工作流與部署（[Git 和 GitHub](../../backend/git-workflow/)、[部署 Web 應用](../../backend/zeabur-deployment/)）
|
||||
|
||||
## 學習目標
|
||||
|
||||
完成本實戰後，你將能夠：
|
||||
|
||||
1. 閱讀 PRD 並從中提取 Agent 平臺的開發任務清單
|
||||
2. 設計結構化的輸入表單和結構化的輸出格式
|
||||
3. 實現 Agent 編排層，處理用戶輸入、模型調用和結果存儲
|
||||
4. 構建"生成 → 保存 → 重用"的業務閉環
|
||||
5. 完成端到端聯調，交付可演示的 AI 產品原型
|
||||
|
||||
## 項目簡介
|
||||
|
||||
你要構建的產品是一個智能旅遊規劃 Agent 平臺：
|
||||
|
||||
| 功能 | 描述 |
|
||||
|------|------|
|
||||
| **行程規劃** | 用戶輸入出發地、目的地、日期、預算和偏好，系統生成每日行程 |
|
||||
| **預算拆分** | 行程結果包含預算分配和建議 |
|
||||
| **歷史管理** | 用戶可以保存歷史計劃、再次生成、導出 |
|
||||
| **管理後臺** | 管理員查看熱門目的地、失敗任務和用戶反饋 |
|
||||
|
||||
::: tip PRD 入口
|
||||
本項目的需求文檔在 GitHub： [查看 PRD](https://github.com/datawhalechina/easy-vibe/blob/main/docs/zh-tw/stage-2/assignments/travel-planning-agent-platform/PRD.md)
|
||||
:::
|
||||
|
||||
<div style="margin: 32px 0;">
|
||||
<ClientOnly>
|
||||
<StepBar :active="0" :items="[
|
||||
{ title: '需求分析', description: '閱讀 PRD，明確頁面、Agent 編排、輸入輸出結構' },
|
||||
{ title: '搭建骨架', description: '用 AI 生成首頁、規劃頁、歷史頁、後臺頁骨架' },
|
||||
{ title: '迭代開發', description: '逐模塊補充結構化輸出、任務狀態、歷史管理' },
|
||||
{ title: '聯調上線', description: '端到端跑通，部署並準備演示' }
|
||||
]" />
|
||||
</ClientOnly>
|
||||
</div>
|
||||
|
||||
## 第一部分：需求分析
|
||||
|
||||
### 1.1 閱讀 PRD
|
||||
|
||||
打開 PRD 文檔，重點回答以下問題：
|
||||
|
||||
- 第一版是否只做單目的地？
|
||||
- 行程輸出是否必須結構化？結構是什麼？
|
||||
- 導出能力做多深？（分享鏈接 / PDF / 圖片）
|
||||
- 後臺統計和任務日誌的範圍是什麼？
|
||||
|
||||
::: warning
|
||||
如果以上問題沒有明確答案，不要開始寫程式碼。需求理解不清楚是導致返工的最常見原因。
|
||||
:::
|
||||
|
||||
### 1.2 確認系統架構
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
prd["PRD"] --> planner["規劃頁"]
|
||||
planner --> agent["Agent 編排層"]
|
||||
agent --> model["模型調用"]
|
||||
agent --> db["資料庫"]
|
||||
db --> history["歷史計劃"]
|
||||
db --> admin["後臺統計與日誌"]
|
||||
```
|
||||
|
||||
## 第二部分：搭建項目骨架
|
||||
|
||||
### 2.1 生成前端頁面
|
||||
|
||||
提示詞參考：
|
||||
|
||||
```text
|
||||
請基於當前 PRD，幫我生成一個智能旅遊規劃 Agent 平臺的前端骨架。
|
||||
|
||||
要求：
|
||||
1. 頁面包括：首頁、規劃頁、行程詳情頁、歷史記錄頁、管理頁
|
||||
2. 規劃頁左側是表單，右側是結果預覽
|
||||
3. 先只生成頁面結構和假資料，不接真實接口
|
||||
4. 風格要像現代 AI 產品
|
||||
```
|
||||
|
||||
### 2.2 驗證頁面結構
|
||||
|
||||
逐項檢查：
|
||||
|
||||
- [ ] 規劃頁的表單字段是否與 PRD 一致
|
||||
- [ ] 結果預覽區域能展示結構化的行程資料
|
||||
- [ ] 歷史記錄頁可以展示多條計劃
|
||||
- [ ] 管理後臺頁可以展示統計資料
|
||||
|
||||
## 第三部分：迭代開發
|
||||
|
||||
### 3.1 按模塊推進
|
||||
|
||||
1. **鑑權**：註冊、登錄
|
||||
2. **規劃表單**：結構化輸入（出發地、目的地、日期、預算、偏好）
|
||||
3. **Agent 編排**：接收輸入 → 調用模型 → 解析結構化輸出
|
||||
4. **結果展示**：行程按天展示、預算拆分、建議
|
||||
5. **歷史管理**：保存計劃、再次生成、導出
|
||||
6. **管理後臺**：熱門目的地、失敗任務、用戶反饋
|
||||
7. **任務狀態**：生成中 / 成功 / 失敗的狀態管理和錯誤記錄
|
||||
|
||||
### 3.2 模塊自檢
|
||||
|
||||
| 檢查項 | 驗證方法 |
|
||||
|--------|----------|
|
||||
| 輸入完整性 | 表單字段是否與 PRD 一致 |
|
||||
| 輸出結構化 | 行程結果是不是結構化資料（而非一大段文字） |
|
||||
| 資料一致性 | trip、itinerary、logs 資料是否對得上 |
|
||||
| 閉環驗證 | 是否能演示"輸入 → 生成 → 保存 → 再次生成" |
|
||||
|
||||
## 第四部分：聯調與上線
|
||||
|
||||
### 4.1 端到端測試
|
||||
|
||||
至少驗證以下場景：
|
||||
|
||||
- 輸入行程參數 → 生成每日行程 → 查看預算拆分 → 保存到歷史
|
||||
- 從歷史記錄中再次生成行程
|
||||
- 管理員查看任務統計和失敗日誌
|
||||
|
||||
## 交付物
|
||||
|
||||
完成本項目後，你需要提交以下內容：
|
||||
|
||||
- [ ] 可訪問的線上演示鏈接
|
||||
- [ ] 源碼倉庫鏈接（含 README）
|
||||
- [ ] PRD 文檔
|
||||
- [ ] 核心頁面截圖（規劃頁、行程詳情頁、歷史記錄頁、管理後臺）
|
||||
- [ ] 60 秒演示影片
|
||||
|
||||
## 評分標準
|
||||
|
||||
| 維度 | 基本要求 | 進階要求 |
|
||||
|------|---------|---------|
|
||||
| PRD 對齊 | 頁面、功能、資料結構基本符合 PRD | 能清晰說明設計決策 |
|
||||
| 產品閉環 | 規劃 → 保存 → 歷史 → 重生成可跑通 | 支持導出和分享 |
|
||||
| 輸出質量 | 行程結果結構化且可讀 | 預算拆分合理、建議有針對性 |
|
||||
| 後臺能力 | 任務統計和失敗日誌可查看 | 有熱門目的地分析 |
|
||||
| 工程完整度 | 前端、後端、資料庫、模型調用鏈路已接通 | 任務狀態管理完善，錯誤可追溯 |
|
||||
|
||||
## 參考資料
|
||||
|
||||
- [UI 設計](../../frontend/ui-design/)
|
||||
- [使用現代組件庫更新你的界面](../../frontend/modern-component-library/)
|
||||
- [從資料庫到 Supabase](../../backend/database-supabase/)
|
||||
- [大模型輔助編寫接口程式碼與接口文檔](../../backend/ai-interface-code/)
|
||||
- [Git 和 GitHub 工作流](../../backend/git-workflow/)
|
||||
- [如何部署 Web 應用](../../backend/zeabur-deployment/)
|
||||
@@ -0,0 +1,161 @@
|
||||
# 大模型輔助編寫接口程式碼與接口文檔
|
||||
|
||||
在之前的課程中，我們學習瞭如何使用 Figma 等工具完成 UI 設計稿、如何藉助 AI 快速生成前端靜態頁面，以及如何利用 Supabase 構建資料庫並實現初步的用戶身份驗證。現在，一個自然而然的問題擺在了面前：前端頁面中那些動感十足的按鈕點擊後，究竟是如何把資料悄無聲息地存進 Supabase 的？當我們需要執行更復雜的業務邏輯（如併發支付、定時推送、資料敏感處理）時，直接讓前端連接資料庫是安全的嗎？
|
||||
|
||||
這就引出了現代 Web 開發架構中至關重要的一環——**後端 API 接口**。
|
||||
|
||||
相比於過去純手工敲出成百上千行的後端路由、控制器與參數校驗邏輯，如今我們完全可以藉助大模型的強大程式碼生成能力，將繁雜的基礎程式碼交由 AI 編寫。在本節課中，我們將跳出“AI 寫的又虛又泛”的怪圈，以真實的業務場景為依託，向你展示如何通過高質量的提示詞（Prompt）引導大模型寫出健壯、符合行業規範的 Node.js 後端接口，並自動完成接口文檔與測試用例的生成。
|
||||
|
||||
> 💡 **前置知識**
|
||||
>
|
||||
> 在學習本節之前，建議你先了解以下內容：
|
||||
> - [從資料庫到 Supabase](../database-supabase/) - 瞭解資料庫和資料模型的概念。
|
||||
> - [Git 和 GitHub 工作流](../git-workflow/) - 熟悉如何在項目開發中進行版本控制。
|
||||
> - [什麼是終端/命令行](/zh-tw/appendix/2-development-tools/command-line-shell) - 項目初始化與啟動離不開基礎的命令操作。
|
||||
|
||||
# 你將學到
|
||||
|
||||
1. **什麼是 API 接口**：理解前後端通信的橋樑與 RESTful 設計規範。
|
||||
2. **大模型賦能服務構建**：如何通過結構化的 Prompt 讓 AI 幫你搭建 Node.js + Express 基礎工程。
|
||||
3. **接口邏輯開發**：引導大模型生成包含嚴謹業務校驗、對接 Supabase 資料庫的 CRUD（增刪改查）接口。
|
||||
4. **自動化接口文檔**：讓大模型根據程式碼逆向生成跨團隊協作標配的 OpenAPI/Swagger 文檔。
|
||||
5. **測試與聯調閉環**：利用大模型生成 Postman 測試合集與 Jest 單元測試用例，為程式碼質量兜底。
|
||||
|
||||
---
|
||||
|
||||
# 1. 為什麼我們需要 API 接口？
|
||||
|
||||
在傳統的理解中，前端是“看得到的部分”，資料庫是“存東西的倉庫”。但這中間缺少了一個調度員。如果你把整個應用想象成一家餐廳：
|
||||
- **前端（客戶端）** 是餐廳的菜單和點餐桌，客人在這裡瀏覽菜品並提出需求。
|
||||
- **資料庫（Supabase 等）** 是餐廳的後廚倉庫，裡面存放著所有的食材和賬本。
|
||||
- **後端 API 接口** 就是餐廳的服務員。客人不能直接衝進後廚拿食材（不僅混亂，而且容易引發安全問題），而是需要把“點單訴求”（HTTP Request）告訴服務員。服務員進行核對（參數校驗、權限鑑權）後，去後廚調取對應的內容，再將“做好的菜”（HTTP Response，通常是 JSON 格式的資料）端回給客人。
|
||||
|
||||
通過 API 接口，我們實現了明確的**前後端分離**：前端只關心頁面如何渲染，後端只專注於業務邏輯、資料處理與安全防護。
|
||||
|
||||
---
|
||||
|
||||
# 2. 項目架構設計與初始化
|
||||
|
||||
一個結構清晰的項目骨架，是大模型能寫出好程式碼的先決條件。我們在讓 AI 寫程式碼前，自己心裡必須對工程結構有個底。
|
||||
|
||||
## 2.1 常見的 API 工程結構
|
||||
即使是使用大模型生成程式碼，我們也絕不能把所有程式碼都塞進一個 `server.js` 文件中。一個易於維護的 Node.js 後端架構通常如下所示：
|
||||
|
||||
```text
|
||||
my-api-project/
|
||||
├── .env # 敏感環境變量（如 API Keys、資料庫連接串）
|
||||
├── server.js # 項目入口（服務器啟動、全局中間件註冊）
|
||||
├── package.json # 依賴管理文件
|
||||
├── src/
|
||||
│ ├── routes/ # 路由層：定義 URL 路徑與請求方法
|
||||
│ ├── controllers/ # 控制器層：處理業務請求參數，調用服務並返回響應
|
||||
│ ├── services/ # 服務層：封裝資料庫交互和核心業務邏輯
|
||||
│ └── middlewares/ # 中間件：登錄鑑權、錯誤全局捕獲
|
||||
└── docs/ # API 文檔存放目錄
|
||||
```
|
||||
|
||||
## 2.2 藉助 AI 完成工程初始化
|
||||
與其手動 `npm init` 並一個個安裝依賴，不如直接將上述規範以 Prompt 的形式餵給大模型：
|
||||
|
||||
> 🗣️ **給大模型的提示詞（Prompt 示例）：**
|
||||
> "幫我搭建一個 Node.js 後端項目，要能連接 Supabase 資料庫，結構清晰一點，方便以後維護。"
|
||||
|
||||
運行 AI 返回的程式碼後，你就能在 `localhost:3000` 獲得一個具備企業級雛形的後端應用了。
|
||||
|
||||
---
|
||||
|
||||
# 3. 核心實戰：大模型輔助接口開發
|
||||
|
||||
這是本章節最核心的部分。大模型寫出的程式碼往往容易存在“邏輯漏洞”或“表面敷衍”，原因在於開發者給的上下文不足。**大模型不怕需求複雜，最怕需求模糊。**
|
||||
|
||||
以我們在 [資料庫章節](../database-supabase/) 中提到的 `menu_items` (菜單表) 的新增接口為例，看如何寫出一份高質量的 Prompt。
|
||||
|
||||
## 3.1 賦予大模型完整上下文
|
||||
在請求 AI 寫接口之前，一定要提供**資料庫字段定義（Schema）**和**具體的約束條件**。
|
||||
|
||||
> 🗣️ **高質量提示詞（Prompt）模板：**
|
||||
> "幫我寫一個新增菜單的接口，菜單有商品名、價格、分類（漢堡、小食、飲料）、是否上架這幾個資訊。商品名和價格必須填，價格不能是負數。用戶輸入不對的時候要提示錯誤。"
|
||||
|
||||
## 3.2 審查大模型生成的程式碼
|
||||
大模型生成的程式碼通常會像下面這樣清晰地拆分了職責：
|
||||
|
||||
```javascript
|
||||
// services/menuService.js
|
||||
const { createClient } = require('@supabase/supabase-js');
|
||||
const supabase = createClient(process.env.SUPABASE_URL, process.env.SUPABASE_KEY);
|
||||
|
||||
exports.createMenuItem = async (menuData) => {
|
||||
// 調用 Supabase SDK 將資料推入表內
|
||||
const { data, error } = await supabase
|
||||
.from('menu_items')
|
||||
.insert([menuData])
|
||||
.select();
|
||||
|
||||
if (error) throw new Error(`資料庫插入失敗: ${error.message}`);
|
||||
return data[0];
|
||||
};
|
||||
```
|
||||
|
||||
你可以發現，通過這種方式生成的程式碼，不僅結構合理，而且將 Supabase 的初始化、錯誤捕獲以及異常處理都考慮在內，這與簡單要求“寫個新增接口”得到的麵條式程式碼（Spaghetti Code）有著天壤之別。
|
||||
|
||||
---
|
||||
|
||||
# 4. 解放雙手：自動生成接口文檔
|
||||
|
||||
對於開發團隊而言，沒有文檔的 API 就是一個盲盒。前端工程師無法猜測你需要傳入什麼參數，也不能預測會返回什麼結構。業界最通用的 API 描述規範是 **OpenAPI (此前也稱 Swagger)**。
|
||||
|
||||
過去，手寫 YAML 或者 JSON 格式的 Swagger 文檔極其痛苦且容易出錯。現在，這也成了大模型最擅長的領域。
|
||||
|
||||
你可以直接選中你剛才寫的 `routes` 和 `controllers` 程式碼，然後丟給大模型：
|
||||
|
||||
> 🗣️ **生成文檔的提示詞：**
|
||||
> "幫我根據上面的程式碼生成一份接口文檔，要寫清楚每個參數是什麼意思、返回什麼資料，方便前端同事對接。"
|
||||
|
||||
在這個過程中，你甚至可以要求 AI 補全字段的說明（Description）和 Mock 資料（如 `price_cents: 1200` 代表 12 美元），極大地降低了溝通成本。
|
||||
|
||||
---
|
||||
|
||||
# 5. 保駕護航：生成測試程式碼與 Postman 集合
|
||||
|
||||
程式碼寫好、文檔出爐，還差最後一步：驗證程式碼到底能不能跑通。
|
||||
|
||||
## 5.1 生成 Postman / Apifox 測試配置
|
||||
在接口開發中，我們通常使用 Postman 這樣的可視化工具來模擬前端發送 HTTP 請求。如果不使用大模型，你需要手動填入 URL、逐個添加 Header（請求頭）以及拼接 JSON 請求體。
|
||||
|
||||
你只需向 AI 發送指令：
|
||||
> "幫我把這份接口文檔轉成 Postman 可以導入的格式，要包含正常請求和錯誤請求的例子。"
|
||||
|
||||
拿到 JSON 文本後，保存為 `menu_api.json` 並拖入 Postman，你瞬間就獲得了一套開箱即用的測試點擊面板。
|
||||
|
||||
## 5.2 編寫自動化單元測試
|
||||
如果你追求更嚴謹的工程質量，可以讓大模型幫你使用 `Jest` 等測試框架編寫單元測試（Unit Tests），對核心業務邏輯進行邊界測試（比如傳入負數價格時，資料庫層的校驗是否生效）。
|
||||
|
||||
---
|
||||
|
||||
# 6. 後端接口必知的最佳實踐
|
||||
|
||||
即使有 AI 的協助，作為整個系統的“把關人”，你依然需要了解並審核以下這些核心準則：
|
||||
|
||||
1. **RESTful 規範的路徑命名**：
|
||||
- 好的設計：`GET /api/users`（獲取用戶列表）、`POST /api/users`（創建用戶）。URL 應該代表“資源”的名詞。
|
||||
- 錯誤的設計：`POST /api/getUser` 或 `POST /api/createUser`。動詞應該交由 HTTP Method (GET/POST/PUT/DELETE) 來體現。
|
||||
2. **規範的 HTTP 狀態碼**：
|
||||
- 200/201：請求成功 / 資源創建成功。
|
||||
- 400：Bad Request，前端傳參格式錯誤、少傳了必填項。
|
||||
- 401/403：Unauthorized / Forbidden，用戶未登錄或無權操作。
|
||||
- 404：NotFound，資源不存在。
|
||||
- 500：Server Error，後端程式碼報錯或資料庫掛了，絕對儘量避免將報錯調用棧直接暴露給前端（會有安全隱患）。
|
||||
3. **永遠不信任用戶的輸入**：前端的輸入可能是偽造的，所有核心參數校驗必須在後端接口中再做一次。
|
||||
|
||||
# 7. 總結
|
||||
|
||||
通過本章節的學習，你實現了開發視角的真正轉變：你不再是被困在語法和標點符號中的“打字員”，而是上升成為了**系統設計師和架構指揮官**。
|
||||
你已經掌握了：
|
||||
1. **API 接口與前後端分離**的核心繫統思維。
|
||||
2. **如何通過提供上下文與分層結構理念**，大幅提高大模型生成服務端程式碼的質量。
|
||||
3. 把繁瑣的**文檔編寫**和**測試用例構建**，巧妙地轉化為 AI 擅長的自動化任務。
|
||||
4. 結合此前學過的 **Supabase** 知識，打通了從客戶端請求到底層資料庫更新的完整資料流。
|
||||
|
||||
::: tip 💡 下一步
|
||||
當你的資料流和後端服務都準備就緒後，它目前還只能在你的本地電腦上“自娛自樂”。在接下來的章節中，我們將學習如何把這套辛辛苦苦建立的服務**部署（Deploy）到公網服務器上**，讓你的產品能被全世界的用戶訪問。
|
||||
:::
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,261 @@
|
||||
# Git 和 GitHub 工作流
|
||||
|
||||
在之前的課程中，我們學習瞭如何使用基於 Web 的 vibe coding 工具編寫程式碼。每次對話都會創建一個新版本的程式碼。但是，讓我們思考一個問題：如果我們想恢復到之前的修改，有沒有方便的方法？有沒有一種工具可以記錄我們在不同階段的程式碼，使我們能夠隨時在不同版本之間切換和修改？
|
||||
|
||||
為了滿足這一需求，版本控制軟體應運而生。在這篇文章中，我們將介紹最著名的版本控制程序——Git——以及最好的程式碼託管平臺——GitHub。我們將學習如何使用 Git 進行程式碼管理，如何從 GitHub 獲取他人的程式碼，如何上傳我們自己的程式碼，以及如何與他人合作進行大型項目。
|
||||
|
||||
無論是個人項目的版本跟蹤，團隊協作中的程式碼同步，還是為開源社區做貢獻，Git 和 GitHub 都是現代開發者的必備工具。通過掌握它們，你將能夠更高效地管理程式碼，根據需要創建檢查點，在程式碼的不同階段之間自由切換，並輕鬆處理從單個文件更改到開發大型項目的所有事務——使每一次程式碼迭代都可控且可追溯。
|
||||
|
||||
> 💡 **前置知識**
|
||||
>
|
||||
> 在學習 Git 之前，建議你先了解以下概念：
|
||||
> - [什麼是終端/命令行](/zh-tw/appendix/2-development-tools/command-line-shell) - 學習如何使用命令行與計算機交互
|
||||
> - [什麼是 Git](/zh-tw/appendix/2-development-tools/git-version-control) - 瞭解 Git 版本控制系統的核心概念
|
||||
>
|
||||
> 本文將重點介紹 GitHub 工作流和實際操作，上述基礎知識請參考附錄鏈接。
|
||||
|
||||
# Git 快速開始
|
||||
|
||||
在開始使用 Git 之前，請確保你已經閱讀了附錄中關於[命令行](/zh-tw/appendix/2-development-tools/command-line-shell)和[Git 基礎](/zh-tw/appendix/2-development-tools/git-version-control)的內容。本文將假設你已經具備這些基礎知識，並直接講解如何安裝配置 Git 以及使用 GitHub 進行協作。
|
||||
|
||||
## 如何安裝 Git
|
||||
|
||||
我們將演示在不同計算機操作系統上安裝 Git 的三種方法。請根據你的系統版本按照說明進行操作：
|
||||
|
||||
### Windows
|
||||
|
||||
1. 前往 [Git 官方下載頁面](https://git-scm.com/download/win) 並下載適合你係統的安裝程序：[安裝包](https://github.com/git-for-windows/git/releases/download/v2.51.0.windows.1/Git-2.51.0-64-bit.exe)。默認情況下，推薦使用 x64 安裝程序。
|
||||
2. 雙擊安裝程序並按照安裝嚮導說明進行操作：
|
||||
|
||||
1. 建議保持默認選項。如果你需要自定義，請注意以下幾點：（在大多數情況下，你可以一直點擊"Next"）
|
||||
- 選擇 Git 使用的默認編輯器：選擇你喜歡的編輯器（如 VS Code）。你可以默認選擇第一個選項，即 Vim（一個文本編輯器），或選擇"Visual Studio Code as Git's default editor"選項（需要預先安裝 VS Code）。你可以保持默認選擇並點擊"Next"繼續。
|
||||
|
||||
- 選擇如何使用 Git：這三個選項控制 Git 在系統中的可訪問性。建議選擇選項 2（"from command line and 3rd-party software"）——它將基本的 Git 工具添加到 PATH 中，讓你可以在 Git Bash、命令提示符、PowerShell 和 IDE 中使用 Git，而不會使系統混亂。
|
||||
|
||||
|
||||
3. 安裝後，在桌面上右鍵單擊。如果在菜單中看到"Git Bash Here"，則安裝成功。
|
||||
|
||||
|
||||
|
||||
### MacOS
|
||||
|
||||
對於 macOS，你可以首先在終端中輸入 `git --version` 來檢查是否已經安裝了 Git。如果沒有，系統會提示你安裝——只需按照說明完成安裝即可。
|
||||
|
||||
1. 方法 1：通過 Homebrew 安裝
|
||||
如果你安裝了 [Homebrew](https://brew.sh/)（Mac 包管理器），請打開終端並輸入
|
||||
```bash
|
||||
brew install git
|
||||
```
|
||||
2. 方法 2：（推薦）通過 Xcode 安裝： https://developer.apple.com/xcode/ ，Xcode 內置了 Git。安裝後，只需按照說明繼續操作。
|
||||
|
||||
### Linux
|
||||
|
||||
大多數 Linux 發行版可以通過其包管理器安裝 Git：
|
||||
|
||||
- Ubuntu/Debian:
|
||||
|
||||
```bash
|
||||
sudo apt update
|
||||
sudo apt install git
|
||||
```
|
||||
|
||||
- CentOS/RHEL:
|
||||
|
||||
```bash
|
||||
sudo yum install git
|
||||
```
|
||||
|
||||
- 驗證安裝：在終端中輸入 git --version。如果顯示版本號，則安裝成功。
|
||||
|
||||
## Git 初始化
|
||||
|
||||
安裝 Git 後，你首先需要配置你的用戶資訊——這是使用 Git 進行版本控制的基本步驟。在終端中執行以下命令（將括號中的內容替換為你自己的資訊）：
|
||||
|
||||
```bash
|
||||
# 設置全局用戶名（將顯示在提交記錄中）
|
||||
git config --global user.name "Your Name"
|
||||
|
||||
# 設置全局郵箱（建議使用在 GitHub/GitLab 等平臺上註冊的郵箱）
|
||||
git config --global user.email "your.email@example.com"
|
||||
```
|
||||
|
||||
Git 會將此資訊嵌入到每個提交記錄中，作為每次修改的"作者資訊"。查看版本歷史記錄（例如，使用 git log）時，你可以清楚地看到誰修改了每一行程式碼，便於追溯責任和溝通。在協作項目中，統一的身份資訊使團隊成員能夠快速識別誰做了哪些更改，從而提高協作效率（例如通過提交記錄找到相關開發人員討論問題）。
|
||||
|
||||
你可以通過在命令行中輸入 `git config --list` 來查看當前的 Git 配置資訊，以確認設置成功。
|
||||
|
||||
# 什麼是 GitHub
|
||||
|
||||
GitHub 是一個基於 Git 的程式碼託管平臺。它不僅為 Git 倉庫提供遠程存儲，還包括協作工具（如 Issues、Pull Requests、Projects），使開發者更容易分享程式碼和協作。簡而言之，Git 是一個本地版本控制工具，而 GitHub 是一個遠程"程式碼倉庫雲盤 + 協作社區"。
|
||||
|
||||
GitHub 不僅是世界上最大的程式碼託管平臺，也是全球最活躍、最具影響力的開源社區。這裡"開源"的核心思想是任何人都可以下載並運行軟體的源程式碼。這種模式允許世界各地的人們檢查彼此的程式碼並進行修改，或基於此創建新項目。例如，你可以在 GitHub 上找到各種學習教程以及用於訓練 GPT 模型的框架（如 PyTorch）的完整源程式碼。每天，無數人在全球範圍內協作審查和改進程式碼。
|
||||
|
||||
|
||||
|
||||
許多大公司在 GitHub 上開源他們的程序或教程，以獲得行業競爭優勢——這也可以看作是一種廣告形式。在 GitHub 社區中，項目獲得的"星標 (stars)"數量是衡量其價值的主要指標；項目或組織擁有的星標越多，其可信度和影響力就越大。
|
||||
|
||||
|
||||
|
||||
在我們的課程中，支持資源和作業也將上傳到專用的 GitHub 倉庫。通過上傳作業的過程，你將逐漸熟悉並掌握 GitHub 的使用，為未來應用程序開發中的版本控制打下堅實的基礎。
|
||||
|
||||
## 註冊 GitHub 賬號
|
||||
|
||||
1. 訪問 [GitHub 官網](https://github.com/) 並點擊右上角的"Sign up"。
|
||||
|
||||
2. 輸入你的電子郵件地址（建議使用常用郵箱，因為驗證和通知將發送到那裡），設置密碼（必須包含字母、數字和特殊字符）。
|
||||
3. 完成人工驗證，按照提示驗證郵箱，你的賬號就創建好了。
|
||||
|
||||
## 在 GitHub 上創建你的第一個倉庫
|
||||
|
||||
接下來，我們將創建第一個存儲文件夾，也稱為倉庫或"repo"。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
1. Repository name：向他人顯示的倉庫名稱。
|
||||
2. Description：倉庫的詳細描述。
|
||||
3. Choose visibility：對於個人倉庫，如果設置為 private，只有你和特別邀請的人可以看到。如果設置為 public，所有人都可以看到。
|
||||
對於組織內的倉庫，如果是 Private，只有組織內的人可以看到。
|
||||
如果是 Public，組織外的人也可以看到。
|
||||
4. README：通常的慣例是每個倉庫都應該有一個 README 文件。你可以把它看作是倉庫的完整介紹，包括使用說明、文件列表和操作方法。
|
||||
5. Add .gitignore and license：
|
||||
1. .gitignore 文件告訴 Git 在上傳到 GitHub 時忽略某些文件夾或文件，因此它們不會被跟蹤或添加到暫存區。這對於臨時測試文件、依賴包或大文件很有用。一旦指定，這些文件將不再被跟蹤。
|
||||
2. license 指的是你選擇的開源許可證類型。不同的許可證詳細規定了他人是否可以將你的程式碼用於商業目的，幷包含其他條款和條件。
|
||||
|
||||
建議勾選"Add README"，將倉庫可見性設置為"Private"，並根據自己的喜好填寫倉庫名稱和描述，然後點擊"Create repository"完成創建第一個遠程倉庫。
|
||||
|
||||
|
||||
|
||||
之後，你將擁有一個沒有任何額外文件的乾淨倉庫。接下來你可以開始上傳文件了。
|
||||
|
||||
|
||||
|
||||
獲取倉庫的命令是 `git clone`，但它需要倉庫地址。你可以通過點擊綠色的"Code"按鈕找到倉庫地址，你會看到 HTTPS 和 SSH 選項。通常，你可以使用這兩種方法中的任何一種將倉庫下載到本地機器（只有這樣你才能修改和上傳文件）。
|
||||
|
||||
|
||||
|
||||
一般來說，通過 HTTP 克隆的倉庫適合臨時下載和測試他人的倉庫，但不建議用於自己的開發。為了更好的學習體驗，你應該先設置 SSH 認證。
|
||||
|
||||
## 綁定本地 SSH
|
||||
|
||||
在 GitHub 中，"SSH 協議綁定"本質上意味著將你本地設備的 SSH 公鑰與你的 GitHub 賬號關聯，允許 GitHub 通過 SSH 協議識別你的設備。這使你能夠安全地操作遠程倉庫，而無需密碼（如 clone、push 或 pull 程式碼）。
|
||||
|
||||
簡單來說：這就像給你的設備一張"GitHub 專屬門禁卡"。綁定後，當你的設備通過 SSH 協議訪問 GitHub 倉庫時，GitHub 會驗證這張"門禁卡"（你的 SSH 公鑰）。一旦確認為你的授權設備，你就可以直接操作——不需要每次都輸入賬號密碼。
|
||||
|
||||
> 💡 什麼是 SSH
|
||||
|
||||
### 為什麼需要 SSH 協議綁定？
|
||||
|
||||
GitHub 支持兩種主要的倉庫操作協議：HTTPS 協議和 SSH 協議：
|
||||
|
||||
- HTTPS 協議：每次操作（如 push）都需要輸入 GitHub 賬號密碼（或個人訪問令牌 PAT）。驗證過程繁瑣，且存在密碼洩露風險。
|
||||
- SSH 協議：身份驗證通過"密鑰對"完成，因此不需要重複輸入密碼，且加密傳輸更加安全。
|
||||
|
||||
"SSH 協議綁定"是啟用 GitHub SSH 認證的前提步驟——只有將本地 SSH 公鑰"綁定"到 GitHub 賬號後，GitHub 才能識別你的設備並允許對倉庫進行 SSH 操作。
|
||||
|
||||
### "綁定"的核心邏輯：SSH 密鑰對的作用
|
||||
|
||||
SSH 認證依賴於密鑰對（公鑰 + 私鑰），它們是匹配的加密文件。生成後，你需要將"公鑰"提供給 GitHub（"綁定"），而"私鑰"留在本地設備上：
|
||||
|
||||
1. 私鑰：存儲在本地設備（如電腦）的指定目錄中（通常是 ~/.ssh/），充當"你的專屬鑰匙"，絕不能與任何人分享。
|
||||
2. 公鑰：這是一把可以公開分享的"鎖"——你需要將其複製到 GitHub 賬號的"SSH keys list"中（"綁定"操作）。
|
||||
|
||||
當你通過 SSH 操作 GitHub 倉庫時（例如 git push git@github.com:xxx/xxx.git）：
|
||||
|
||||
- 你的本地設備使用私鑰加密"操作請求"併發送給 GitHub；
|
||||
- 收到請求後，GitHub 嘗試使用你之前綁定的公鑰進行解密；
|
||||
- 如果解密成功，你的設備被確認為已授權，操作被允許；否則，訪問被拒絕。
|
||||
|
||||
### "綁定"的具體步驟（核心流程）
|
||||
|
||||
一旦你理解了原理，實際操作就很簡單——核心是"生成密鑰對 → 上傳公鑰到 GitHub"：
|
||||
|
||||
1. 本地生成 SSH 密鑰對
|
||||
1. 使用 Trae 獲取公鑰（推薦）
|
||||
提示詞：`Help me create the SSH key needed for GitHub login. My email is your_email@gmail.com , Please return the public key for me to copy`
|
||||
|
||||
|
||||
|
||||
輸入提示詞後，你還需要在左側終端按 Enter 鍵，否則命令會一直等待而不執行。由於 Trae 無法幫你執行任何條件判斷，我們只需要一直按 Enter 即可。
|
||||
|
||||
最後，你會看到右側的 Trae 返回了它讀取的公鑰。你只需複製它並準備在下一步中粘貼。
|
||||
|
||||
 2. 手動獲取公鑰
|
||||
打開你的本地終端（在 Windows 上使用 Git Bash 或 PowerShell；在 macOS/Linux 上使用終端），輸入以下命令（將 your_email@example.com 替換為你註冊 GitHub 賬號時使用的郵箱）：
|
||||
|
||||
```bash
|
||||
ssh-keygen -t ed25519 -C "your_email@example.com"
|
||||
```
|
||||
|
||||
1. 按 Enter 接受默認值（默認文件路徑，無密碼，或根據需要設置密碼）。這將在 ~/.ssh/ 目錄中生成兩個文件：
|
||||
- id_ed25519：私鑰（本地保存，**絕不分享**）；
|
||||
- id_ed25519.pub：公鑰（需要上傳到 GitHub）。
|
||||
|
||||
2. 將公鑰"綁定"到你的 GitHub 賬號
|
||||
|
||||
這是核心綁定步驟——將本地公鑰添加到 GitHub 賬號的"SSH keys list"中：
|
||||
|
||||
1. 複製公鑰內容：
|
||||
1. Trae：
|
||||
2. Windows：用記事本打開 C:\Users\<your>\.ssh\id_ed25519.pub 並複製其所有內容；
|
||||
3. macOS/Linux：在終端運行 cat ~/.ssh/id_ed25519.pub 並複製所有輸出（從開頭的 SSH-ed25519 到結尾的郵箱）。
|
||||
2. 登錄 GitHub 並進入"SSH Key Management"頁面：
|
||||
1. 點擊右上角頭像 → Settings → 左側菜單 SSH and GPG keys → 點擊 New SSH key。
|
||||
|
||||
2. 輸入任何標題（例如，your local computer's SSH），然後將你剛剛獲取的 SSH 公鑰粘貼到這裡。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
3. 驗證綁定是否成功
|
||||
|
||||
在終端中輸入以下命令（**Trae 也可以做以下操作**）來測試 GitHub 是否能識別你的設備：
|
||||
|
||||
```bash
|
||||
ssh -T git@github.com
|
||||
```
|
||||
|
||||
- 如果你看到類似 Hi [your GitHub username]! You've successfully authenticated... 的內容，說明你已成功綁定密鑰；
|
||||
- 如果遇到錯誤，通常是因為公鑰複製不完整、私鑰權限過高（你的本地 ~/.ssh/ 目錄應僅由你讀寫）等。根據需要檢查這些問題。
|
||||
|
||||
### 重要注意事項
|
||||
|
||||
如果你有多個設備（如筆記本電腦和臺式機），你需要為每個設備生成單獨的 SSH 密鑰對，並將每個公鑰綁定到同一個 GitHub 賬號——每個設備都有自己的"門禁卡"。
|
||||
|
||||
切勿分享你的私鑰（不要上傳到 GitHub 或與他人分享），否則有人可能會冒充你操作你的倉庫。如果私鑰洩露，請立即從 GitHub 刪除相應的公鑰並生成新的密鑰對。
|
||||
|
||||
綁定 SSH 後，使用 SSH 格式的倉庫地址（例如 git@github.com:username/repository.git）進行操作，而不是 HTTPS 格式（例如 https://github.com/username/repository.git）。如果你之前用 HTTPS 克隆了倉庫，可以用 git remote set-url origin `<new>` 切換協議。
|
||||
|
||||
# 使用 Trae 進行 GitHub 操作
|
||||
|
||||
我們已經解釋了什麼是 Git，什麼是 GitHub，什麼是 SSH，以及如何配置它。現在你可以自由使用 Trae 執行 Git 操作。首先，讓我們學習如何將遠程倉庫克隆到本地機器。
|
||||
|
||||
## Git clone : 下載現有倉庫
|
||||
|
||||
你可以直接告訴它你想克隆的倉庫地址
|
||||
|
||||
|
||||
|
||||
## Git pull : 從遠程倉庫獲取更新
|
||||
|
||||
每次更新倉庫之前，由於它可能由多人維護，你需要先拉取最新的更改。之後，你可以修改並推送文件。
|
||||
|
||||
**記得包含文件夾名稱及其相對或絕對路徑，以避免推送到錯誤的倉庫。**
|
||||
|
||||
prompt:`Help me pull this repository AIID-TEST in ./AIID-TEST.`
|
||||
|
||||
## Git commit & Git push : 暫存更新並推送到 GitHub
|
||||
|
||||
一切準備就緒後，你可以嘗試修改本地文件，在文件夾中添加或刪除項目。然後，讓 Trae 檢測更改並幫你推送到 GitHub。
|
||||
|
||||
prompt:`I finished. Commit and push to the repository AIID-TEST in ./AIID-TEST.`
|
||||
|
||||
|
||||
|
||||
推送成功。現在你可以在 GitHub 上看到更新的內容了。
|
||||
|
||||
# 參考資料
|
||||
|
||||
- Pro Git book https://git-scm.com/book/en/v2
|
||||
- GitHub Docs https://docs.github.com/en
|
||||
@@ -0,0 +1,801 @@
|
||||
# CLI AI 程式設計工具
|
||||
|
||||
在本教程中，我們將介紹直接在命令行中運行的 AI 程式設計 Agent。它們和之前學過的 Trae、Cursor 中的 Agent 不同，CLI AI 程式設計工具只能在終端中使用。與集成在 AI IDE 裡的 Agent 相比，它們通常具有更長的上下文窗口、更快的工具調用速度，並且可以兼容更多種類的大模型。在最新的 AI Vibe Coding 實戰中，我們往往會優先使用 CLI AI 程式設計工具，而不是 IDE 內置的編碼 Agent。
|
||||
|
||||
## 從 CLI 說起
|
||||
|
||||
還記得我們之前介紹過的 CLI 嗎？CLI 指的是通過終端或命令提示符，用純文本命令來操作軟體應用，而不是依賴圖形界面（GUI——你可以簡單理解為電腦或手機上帶按鈕、可以點擊操作的界面，不需要輸入命令）。
|
||||
|
||||
> 在 Windows 上，常見的終端有“命令提示符（cmd）”和 “PowerShell”。你可以在電腦的運行/搜索框中輸入 “cmd” 或 “powershell” 來啟動這些命令行程序。
|
||||
|
||||
|
||||
|
||||
CLI 天生適合文本命令操作，在一小部分極客（追求極致的程式設計愛好者）群體中，CLI 甚至比 GUI 更受歡迎——他們希望所有操作都通過鍵盤完成，覺得動鼠標反而會拖慢自己的編碼效率。
|
||||
|
||||
在工業界，CLI 往往也是最常見的接口形式，因為 GUI 需要操作系統額外繪製界面、管理窗口，對計算機資源的要求更高；而 CLI 只需要把收到的命令傳給系統執行即可。因此，在連接大規模服務器集群時，我們通常只通過 CLI 進行交互。
|
||||
|
||||
|
||||
|
||||
對於許多沒有 CLI 經驗的同學來說，可能會覺得 CLI 操作很複雜、命令太多，甚至擔心“一不小心就把電腦搞壞”。不用擔心。還記得我們在前面教程裡，經常讓 Trae 幫忙完成各種基礎操作嗎？這裡也可以完全照搬這個思路——我們可以讓 CLI 程式設計工具幫我們執行所有 CLI 操作：讓它幫你進入指定文件夾、搜索和處理文件、運行或複製開源項目等。整個過程都可以通過和 CLI AI 程式設計工具的對話來完成。
|
||||
|
||||
## 和 AI IDE 有什麼不同
|
||||
|
||||
我們可以把 CLI AI 程式設計工具類比成之前學過的 z.ai 和 Trae。某種意義上，CLI AI 程式設計工具可以看成是一種特殊的 z.ai：它們同樣只需要一個簡單的對話入口，就會自動為你執行所有需要的操作（只是有時你需要手動打開瀏覽器查看最終效果）。而如果類比 AI IDE，那麼 CLI AI 程式設計工具可以被看作是 IDE 中的 Agent 模塊——也就是側邊那塊對話區域。
|
||||
|
||||
|
||||
|
||||
不過，由於不同 AI IDE 對 Agent 的實現方式不同，能力差異也很大，AI 程式設計效果經常不穩定，因此 CLI AI 程式設計工具通常由大型科技公司直接開發，例如 Claude 背後的 Anthropic、ChatGPT 背後的 OpenAI 等。
|
||||
|
||||
相比其他 AI 程式設計 Agent，直接使用這些大廠產品往往是較優的實踐，尤其是 Claude Code 本身就是為 Anthropic 內部研發團隊服務的工具，從一開始就圍繞“滿足工程師真實需求”來設計。
|
||||
|
||||
為了更直觀地對比，我們可以簡單看看 Claude Code 和某款 AI IDE Agent 的差異（這裡以 Cursor 為例）：
|
||||
|
||||
| 功能特性 | Claude Code | Cursor | 更優者 |
|
||||
| ----------------- | ------------- | --------------- | ----------- |
|
||||
| 自動任務執行 | ✅ 非常強 | ❌ 能力有限 | Claude Code |
|
||||
| IDE 集成 | ❌ 僅命令行 | ✅ 原生 VS Code | Cursor |
|
||||
| 實時程式碼補全 | ❌ 無 | ✅ 體驗極佳 | Cursor |
|
||||
| 多文件操作 | ✅ 非常強 | ⚠️ 還不錯 | Claude Code |
|
||||
| GitHub 一體化操作 | ✅ 可直接提交 | ⚠️ 需要手動操作 | Claude Code |
|
||||
| 學習成本 | ⚠️ 中等 | ✅ 上手簡單 | Cursor |
|
||||
| 上下文長度 | ✅ 非常長 | ⚠️ 較好 | Claude Code |
|
||||
| 調試輔助 | ✅ 自動化 | ⚠️ 較多需手動 | Claude Code |
|
||||
|
||||
表格來源：<https://northflank.com/blog/claude-code-vs-cursor-comparison>
|
||||
|
||||
簡單說，CLI AI 程式設計工具通常可以：
|
||||
|
||||
- 支持更長時間的連續對話（甚至可以幫你“工作一整天”）。
|
||||
- 提供更長的上下文窗口（不再頻繁需要你說“繼續”）。
|
||||
- 響應速度更快（可以接入更多自定義模型 API）。
|
||||
|
||||
在編碼相關操作上，它們通常比大部分 IDE 內置 Agent 更聰明、更穩定。
|
||||
|
||||
## 常見的 CLI AI 程式設計工具
|
||||
|
||||
目前雖然有很多開源實現，但在實踐中我們只推薦兩大類型的 CLI AI 程式設計工具，作為“首選組合”。你可以根據自己的習慣任選其一，強烈建議都試一試，再選出最適合你的那一個。
|
||||
|
||||
- Codex 使用 GPT-5，在整體能力上更強；
|
||||
- Claude Code 通過 GLM 4.6 轉發 API，整體體驗接近 Claude 4，但價格更便宜。
|
||||
- OpenCode 可以隨意切換並搭配模型, 提供免費模型, 可以更好的控制成本。
|
||||
|
||||
不過，哪一個在實際項目中更好用，只能通過親自測試來判斷。掌握多種 AI 程式設計工具始終是有益的：熟練以後，你可以在不同場景下靈活切換 Claude Code、Codex 或 Trae。如果嘗試多次後發現某個工具效果一般，可以直接換一個工具或模型繼續試驗。
|
||||
|
||||
同時，由於模型版本更新非常迅速，建議你優先選擇在“性價比（效果 / 成本）”上表現最好的方案。
|
||||
|
||||
### Claude Code
|
||||
|
||||
Claude Code 是由 Anthropic 基於 Claude 大模型能力開發的一款 AI 程式設計工具。它的主要交互場景在終端，同時也支持作為 VS Code 插件來使用。類似於 AI IDE 中的 Agent，它可以深度理解開發者的程式碼倉庫，並通過自然語言指令完成端到端的開發任務——包括程式碼編輯、修復 Bug、執行和修復測試、管理 Git 工作流（例如解決合併衝突、創建 PR）、複雜程式碼講解、執行終端命令等。
|
||||
|
||||
|
||||
|
||||
Claude Code 的優勢主要體現在：極長的上下文窗口（可以處理完整文件甚至小型項目）、可以主動澄清模糊需求、自動規劃和分配執行任務，以及對整個程式碼庫內容的深度理解和解釋能力。與普通 IDE Agent 相比，它更適合“沉浸式 vibe coding” 的開發流程。
|
||||
|
||||
在實際使用中，你可以通過對話指令，讓它幫你創建新項目、執行 CLI 操作（例如整理文件夾、批量重命名文件、部署開源項目等）、配置開發環境（例如安裝和調試 Python 環境）。如果覺得某段程式碼難以理解、某個目錄結構不清晰，也可以直接讓 Claude Code 生成結構化的分析文檔，或者對特定內容進行分步驟講解。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
如果你想系統地學習 Claude Code，可以參考 Andrew Ng 與 Anthropic 聯合推出的課程：
|
||||
<https://www.bilibili.com/video/BV176t2zSEpr>
|
||||
|
||||
接下來，我們將學習如何使用 Claude Code。由於直接使用官方 Claude Code 的成本往往非常高（如下圖所示），我們會轉而使用兼容 Claude Code 協議、但基於其他大模型的 API 平臺。
|
||||
|
||||
|
||||
|
||||
你需要學習下面幾種不同方案（最好都嘗試一遍），最後選擇最適合你的那一種作為主要實踐路徑。
|
||||
|
||||
第一種方式是直接使用“兼容 Anthropic 接口”的 API。隨著 Claude Code 的流行，越來越多的大模型服務商開始支持 Anthropic 風格的調用方式。常見的服務商包括 GLM、Kimi、DeepSeek 和 Siliconflow 等，它們都提供了兼容的 API 接口。關於具體配置，我們會在後文細講。
|
||||
|
||||
需要注意的是，Claude Code 通常會消耗大量 token，如果你擔心 API 調用產生過高費用，可以考慮購買 GLM 的月度套餐（大約 20 元/月）來控制成本。如果你想先感受一下實際花費，也可以先充值 10 元做小規模試驗。
|
||||
|
||||
另一種方式是使用 “Claude Code Route” 項目。它是一個開源工具，不僅支持所有常見的 API 調用接口，還允許你針對不同場景精細配置要使用的模型，並且支持對接本地部署的大模型。但由於這一方案的配置相對複雜，建議你先從第一種方案入手。
|
||||
|
||||
#### 使用智譜 GLM 作為後端（推薦）
|
||||
|
||||
GLM（General Language Model）是智譜 AI 自主研發的一系列大型語言模型。GLM-4.6 是當前 GLM 系列的最新版本，其核心亮點是在程式碼能力上的優異表現（在公開基準和真實任務中對標 Claude Sonnet 4，在國內處於第一梯隊）。
|
||||
|
||||
|
||||
|
||||
它還將上下文窗口擴展到 200K，可以更加從容地處理長文本和大體量程式碼，同時加強了推理與工具調用能力，在性能和成本之間取得了不錯的平衡。
|
||||
|
||||
|
||||
|
||||
在接入 GLM 之前，我們需要先安裝 Claude Code。
|
||||
|
||||
如果你覺得命令行安裝步驟麻煩，或者中途出現錯誤，可以直接讓 Trae 的 Agent 幫你完成安裝。
|
||||
|
||||
```python
|
||||
# 安裝 Claude Code
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
|
||||
# 進入你的項目
|
||||
cd your-awesome-project
|
||||
|
||||
# 啟動 Claude Code
|
||||
claude
|
||||
|
||||
# 按 Ctrl+C 退出 Claude
|
||||
```
|
||||
|
||||
接下來，我們需要修改 Claude Code 的默認 API 請求地址，使其支持 GLM 的 API 服務。你可以直接複製下面的內容，讓 Trae 幫你創建對應的環境變量；也可以選擇把它們永久寫入系統環境變量（如果出現問題，同樣可以讓 Agent 幫忙修改）。
|
||||
|
||||
首先，你需要先獲取 GLM 的 API Key，並用你自己覺得最方便的方式保存好。
|
||||
|
||||
國內版地址：<https://bigmodel.cn/usercenter/proj-mgmt/apikeys>
|
||||
國際版地址：<https://z.ai/manage-apikey/apikey-list>
|
||||
|
||||
如果你使用的是 **國內版 GLM**，請使用以下變量配置：
|
||||
|
||||
```python
|
||||
# 在 Cmd 中運行以下命令
|
||||
# 注意將 `your_zhipu_api_key` 替換為你剛剛獲取到的 API Key
|
||||
setx ANTHROPIC_AUTH_TOKEN your_zhipu_api_key
|
||||
setx ANTHROPIC_BASE_URL https://open.bigmodel.cn/api/anthropic
|
||||
```
|
||||
|
||||
如果你使用的是 **國際版 GLM**，請使用下面的配置：
|
||||
|
||||
```python
|
||||
# 在 Cmd 中運行以下命令
|
||||
# 同樣注意替換掉 `your_zai_api_key`
|
||||
setx ANTHROPIC_AUTH_TOKEN your_zai_api_key
|
||||
setx ANTHROPIC_BASE_URL https://api.z.ai/api/anthropic
|
||||
```
|
||||
|
||||
你可以直接在 Trae 中輸入類似下面的提示詞：
|
||||
|
||||
⚠️ 如果你是通過 Trae 幫你配置“永久環境變量”，那麼配置完成後 **必須重啟 Trae**，否則它內置終端裡的環境變量不會更新，可能導致登錄失敗或網路連接錯誤。
|
||||
|
||||
```python
|
||||
Based on my environment variable settings:
|
||||
setx ANTHROPIC_AUTH_TOKEN your_zai_api_key
|
||||
setx ANTHROPIC_BASE_URL https://api.z.ai/api/anthropic
|
||||
|
||||
and my key(Replace it with your own key):
|
||||
681fea485851d29060cc.13gfaendggaFOhb
|
||||
|
||||
please help me configure and start Claude Code
|
||||
```
|
||||
|
||||
你會看到類似下面的過程輸出：
|
||||
|
||||
|
||||
|
||||
> 💡 什麼是環境變量？
|
||||
>
|
||||
> 環境變量本質上是一組存儲在操作系統中的“鍵值對”配置資訊，通常以 “變量名 = 具體值” 的形式存在。只要提前在終端或系統設置中配置好，程序就可以隨時讀取這些變量來獲取相關資訊。由於環境變量可以直接在終端中寫入，而無需修改程式碼本身，我們通常會把訪問大模型所需的密鑰存放在環境變量裡，以避免洩露。程序只需要讀取對應環境變量，就能完成大模型調用。
|
||||
>
|
||||
> 在 Windows 系統中，環境變量除了用於存儲大模型的訪問密鑰，還常常用來保存命令行工具的“調用路徑”。
|
||||
>
|
||||
> 我們知道終端本身也是一個程序。有時我們希望在終端裡啟動某個外部程序，例如在終端中輸入 `claude` 來啟動 Claude Code。之所以可以直接輸入 `claude` 就運行，是因為終端會讀取系統的環境變量，其中的 PATH 變量裡包含了 Claude Code 可執行文件所在的目錄，所以終端能夠找到並執行它（等價於在終端中粘貼那段程序的絕對路徑再按回車）。
|
||||
>
|
||||
> 一個典型的環境變量可能長這樣：`PATH=C:\Windows\system32;C:\Program Files\Python`。這樣我們就可以在任何路徑下執行系統中的這些程序，例如直接在命令行鍵入 `python` 啟動 Python 解釋器。
|
||||
>
|
||||
> 如果你想查看系統當前的環境變量，可以在 Windows 搜索中輸入“環境變量”，在彈出的“編輯系統環境變量”窗口中就能看到所有變量及其值。有的變量用於存儲大模型密鑰，有的則用於添加程序目錄，方便在任意路徑下調用。
|
||||
|
||||
現在，你就可以使用最新的 GLM 來進行 Claude Code 開發了。你可以嘗試重新跑一遍之前的項目，或者重新挑戰那些 Trae 沒有完成好的任務，對比看看體驗上的差異。
|
||||
|
||||
🎉 反覆“推倒重來”並不是浪費時間——你每重做一遍，技能都會更紮實一分。
|
||||
|
||||
用和 GLM 完全相同的思路，也可以輕鬆接入其他支持 Anthropic 兼容格式的接口。
|
||||
|
||||
#### 使用 Kimi K2 作為後端（推薦）
|
||||
|
||||
Kimi K2 是月之暗面（Moonshot AI）推出的新一代大語言模型，在程式碼理解和生成能力上表現出色。Kimi K2 支持超長上下文窗口（最高可達 200K tokens），能夠輕鬆處理大型程式碼庫和複雜項目。
|
||||
|
||||
**核心優勢：**
|
||||
|
||||
- **超長上下文**：支持 200K 上下文窗口，可以一次性處理整個項目的程式碼
|
||||
- **程式碼能力強**：在程式碼生成、重構和調試方面表現優異
|
||||
- **中文理解好**：對中文程式設計需求的理解更加準確
|
||||
- **工具調用穩定**：支持穩定的函數調用和工具使用
|
||||
|
||||
**獲取 API Key：**
|
||||
|
||||
訪問 <https://platform.moonshot.cn/console/account> 註冊並獲取 API Key。
|
||||
|
||||
**配置方法：**
|
||||
|
||||
參考文檔：<https://platform.moonshot.cn/docs/guide/agent-support>
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_BASE_URL=https://api.moonshot.cn/anthropic
|
||||
export ANTHROPIC_AUTH_TOKEN=sk-YOURKEY
|
||||
```
|
||||
|
||||
#### 使用 Minimax 作為後端（推薦）
|
||||
|
||||
Minimax 是稀宇科技（MiniMax）推出的新一代大語言模型，在程式設計任務上表現優異。Minimax 模型以其出色的推理能力和程式碼生成質量而聞名，特別適合複雜的程式設計場景。
|
||||
|
||||
**核心優勢：**
|
||||
|
||||
- **推理能力強**：在複雜邏輯推理和程式碼架構設計方面表現出色
|
||||
- **程式碼質量高**：生成的程式碼結構清晰、可讀性好
|
||||
- **多語言支持**：支持多種程式設計語言的程式碼生成和轉換
|
||||
- **響應速度快**：API 響應速度快，適合高頻調用場景
|
||||
|
||||
**獲取 API Key：**
|
||||
|
||||
訪問 <https://platform.minimax.io/> 註冊並獲取 API Key。
|
||||
|
||||
**配置方法：**
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_BASE_URL=https://api.minimax.io/anthropic
|
||||
export ANTHROPIC_AUTH_TOKEN=YOUR_MINIMAX_API_KEY
|
||||
export ANTHROPIC_MODEL=MiniMax-M2.7
|
||||
```
|
||||
|
||||
#### 使用 DeepSeek 作為後端（推薦）
|
||||
|
||||
DeepSeek 是深度求索推出的開源大語言模型，以其出色的程式碼能力和高性價比受到開發者歡迎。DeepSeek Coder 專門針對程式設計任務進行了優化訓練。
|
||||
|
||||
**核心優勢：**
|
||||
|
||||
- **程式碼能力突出**：在程式碼生成、程式碼理解和 Bug 修復方面表現優異
|
||||
- **開源可定製**：模型開源，可以根據需求進行微調
|
||||
- **性價比高**：API 價格相對較低，適合高頻使用
|
||||
- **中文支持好**：對中文程式設計場景理解準確
|
||||
|
||||
**獲取 API Key：**
|
||||
|
||||
訪問 <https://platform.deepseek.com/usage> 註冊並獲取 API Key。
|
||||
|
||||
**配置方法：**
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
|
||||
export ANTHROPIC_AUTH_TOKEN=YOU_DEEPSEEK_API_KEY
|
||||
export API_TIMEOUT_MS=600000
|
||||
export ANTHROPIC_MODEL=deepseek-chat
|
||||
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat
|
||||
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
|
||||
```
|
||||
|
||||
#### 使用火山引擎 Coding Plan 作為後端（推薦）
|
||||
|
||||
火山引擎（Volcano Engine）是字節跳動旗下的雲服務平臺，提供企業級的 AI 模型服務。火山引擎的 Coding Plan 專門為程式設計場景優化，提供穩定、高效的程式碼生成能力。
|
||||
|
||||
**核心優勢：**
|
||||
|
||||
- **企業級穩定性**：提供服務等級協議（SLA），保障服務穩定性
|
||||
- **程式碼場景優化**：針對程式設計任務進行了專門優化
|
||||
- **豐富模型選擇**：支持多種模型，包括 Doubao-pro、Doubao-lite 等
|
||||
- **國內訪問快**：國內節點部署，訪問速度快
|
||||
|
||||
**獲取 API Key：**
|
||||
|
||||
訪問 <https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey> 註冊並獲取 API Key。
|
||||
|
||||
**配置方法：**
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_BASE_URL=https://ark.volces.com/api/anthropic
|
||||
export ANTHROPIC_AUTH_TOKEN=YOUR_VOLCANO_API_KEY
|
||||
export ANTHROPIC_MODEL=doubao-pro-32k
|
||||
```
|
||||
|
||||
#### 其他兼容 Anthropic 的 API
|
||||
|
||||
Siliconflow：
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_BASE_URL="https://api.siliconflow.cn/"
|
||||
export ANTHROPIC_MODEL="moonshotai/Kimi-K2-Instruct-0905" # 可以自行修改所需模型
|
||||
export ANTHROPIC_API_KEY="YOUR_SILICONCLOUD_API_KEY" # 請替換 API Key
|
||||
```
|
||||
|
||||
阿里雲 DashScope（Aliyuncs）：<https://help.aliyun.com/zh/model-studio/get-api-key>
|
||||
|
||||
```python
|
||||
export ANTHROPIC_BASE_URL="https://dashscope.aliyuncs.com/apps/anthropic"
|
||||
export ANTHROPIC_API_KEY="YOUR_DASHSCOPE_API_KEY"
|
||||
```
|
||||
|
||||
::: details 使用 Claude Code Route 作為後端（進階用法）
|
||||
|
||||
上面我們講解了如何用 GLM 官方 API 替換 Claude Code 的 Anthropic 接口。接下來，我們來看一下 Claude Code Router 這個工具是如何讓 Claude Code 適配更多模型 API 的。
|
||||
|
||||
[Claude Code Router](https://github.com/musistudio/claude-code-router) 是一款專門為 Claude Code 設計的智能路由增強工具。它的核心作用，是幫助用戶按需將 AI 請求分發到不同平臺上的模型，並可以高度自定義。它支持接入幾十個平臺，包括 OpenRouter、DeepSeek、Ollama、Gemini 等，也可以按場景將任務路由到特定模型，比如 GLM-4.5、Kimi-K2、Qwen3-Coder 等。舉例來說，你可以將後臺任務自動交給本地 Ollama，以節省成本；將長文本 / 長程式碼任務交給 Gemini-2.5-Pro；把程式碼講解交給 DeepSeek。
|
||||
|
||||
|
||||
|
||||
該工具還提供了方便的 UI/CLI 配置管理能力，並通過"轉換器（converter）"適配不同平臺的 API 格式。它支持 GitHub Actions 等自動化集成以及自定義擴展，解決了"單一模型無法覆蓋所有場景"以及"頻繁切換平臺很麻煩"的問題，幫助用戶更靈活、低成本地利用 AI 工具。
|
||||
|
||||
|
||||
|
||||
下面我們簡單介紹如何安裝 Claude Code Router。大致需要以下步驟（同樣可以讓 Trae 幫你執行），以準備好相關環境：
|
||||
|
||||
```markdown
|
||||
npm install -g @anthropic-ai/claude-code
|
||||
npm install -g @musistudio/claude-code-router
|
||||
```
|
||||
|
||||
安裝完成後，你需要確認本地可以使用 `ccr` 命令。如果看到類似下面的輸出，說明安裝成功：
|
||||
|
||||
|
||||
|
||||
接下來，有兩種方式來初始化和配置模型：
|
||||
|
||||
- 使用 CCR 自帶的 UI，在瀏覽器中打開它提供的配置頁面進行操作；
|
||||
- 直接修改 CCR 的默認配置文件（本質上 UI 也是在修改配置文件，只是提供了更直觀的界面）。
|
||||
|
||||
如果選擇使用 CCR UI，你會看到類似下面的界面：
|
||||
|
||||
|
||||
|
||||
此時點擊 "Add Provider" 按鈕，就會看到如下界面。你需要：
|
||||
|
||||
1. 在 Name 中輸入模型提供商的名字；
|
||||
2. 在 API Full URL 中填寫該提供商的 OpenAI 兼容接口地址；
|
||||
3. 在 API Key 中填寫對應平臺的 API Key；
|
||||
4. 在 Models 區域中填寫模型名稱，點擊 "Add Model" 添加；
|
||||
5. 最後點擊 "Save" 保存配置。
|
||||
|
||||
（界面往下滾動還有很多高級選項，但目前你可以先忽略它們。）
|
||||
|
||||
|
||||
|
||||
下面是 DeepSeek 與 Kimi 的配置示例：
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
保存模型配置後，還需要在右側 Router 區域中指定默認模型（Default）。點擊對應的下拉選擇，將其設置為 `kimi`（推薦），然後在右上角點擊 `Save and Restart`。
|
||||
|
||||
|
||||
|
||||
之後，只需在終端中輸入 `ccr code`，即可通過 Claude Code Router 啟動 Claude Code 的編碼工作流。
|
||||
|
||||
|
||||
|
||||
:::
|
||||
|
||||
#### Claude Code 的進階用法
|
||||
|
||||
很多人最開始使用 Claude Code 時，只把它當成普通對話工具來用。但實際上，它內置了很多豐富的能力，能夠讓你使用起來更高效、靈活。下面是一些常見命令和用法示例：
|
||||
|
||||
參考文檔：
|
||||
|
||||
<https://docs.claude.com/en/docs/claude-code/cli-reference>
|
||||
<https://docs.claude.com/en/docs/claude-code/slash-commands>
|
||||
|
||||
| 命令 | 作用 | 示例 |
|
||||
| ----------------- | ----------------------------------------- | ---------------------------------------- |
|
||||
| claude | 啟動交互模式 | `claude` |
|
||||
| claude "query" | 執行一次性任務並輸出結果 | `claude "explain this project"` |
|
||||
| claude -p "query" | 執行一次性問題並在結束後自動退出 | `claude -p "explain this function xxxx"` |
|
||||
| claude -c | 繼續最近的一次會話 | `claude -c` |
|
||||
| claude -r | 恢復上一段會話 | `claude -r` |
|
||||
| /resume | 在當前聊天中切換回上一段會話 | `claude -c`、`/resume` |
|
||||
| /plugin | 管理插件，可安裝提交與審查類擴展能力 | `/plugin` |
|
||||
| /init | 用 CLAUDE.md 初始化項目說明 | `/init` |
|
||||
| /clear | 清空當前會話上下文，防止資訊過載 | `/clear` |
|
||||
| /compact | 壓縮會話歷史，減少上下文 token 佔用 | `/compact` |
|
||||
| /cost | 查看當前消費情況 | `/cost` |
|
||||
| /model | 切換使用的模型（用兼容 API 時一般可忽略） | `/model` |
|
||||
| /memory | 管理 CLAUDE.md 記憶文件 | |
|
||||
| /help | 顯示可用命令列表 | `/help` |
|
||||
| exit or Ctrl+C | 退出 Claude Code | `exit` 或 `Ctrl+C` |
|
||||
| /agents | 高級功能，後文會說明 | |
|
||||
| /mcp | 高級功能，後文會說明 | |
|
||||
|
||||
**CLAUDE.md**
|
||||
|
||||
參考： <https://www.anthropic.com/engineering/claude-code-best-practices>
|
||||
|
||||
`CLAUDE.md` 是 Claude 在開始對話時會自動讀取並加入上下文的特殊文件。因此，它非常適合用來記錄：
|
||||
|
||||
- 常用 bash 命令
|
||||
- 核心文件和工具函數
|
||||
- 程式碼風格約定
|
||||
- 測試方式說明
|
||||
- 倉庫協作規範（例如分支命名、是用 merge 還是 rebase 等）
|
||||
- 開發環境配置說明（例如是否使用 pyenv、推薦哪種編譯器等）
|
||||
- 項目中需要特別注意的行為或坑點
|
||||
- 任何你希望 Claude “記住”的資訊
|
||||
|
||||
`CLAUDE.md` 本身沒有強制格式要求，只要簡潔、便於人類閱讀即可。例如：
|
||||
|
||||
```
|
||||
# Bash commands
|
||||
- npm run build: Build the project
|
||||
- npm run typecheck: Run the typechecker
|
||||
|
||||
# Code style
|
||||
- Use ES modules (import/export) syntax, not CommonJS (require)
|
||||
- Destructure imports when possible (eg. import { foo } from 'bar')
|
||||
|
||||
# Workflow
|
||||
- Be sure to typecheck when you’re done making a series of code changes
|
||||
- Prefer running single tests, and not the whole test suite, for performance
|
||||
```
|
||||
|
||||
#### Claude Code 的內部原理
|
||||
|
||||
參考： <https://github.com/shareAI-lab/analysis_claude_code>
|
||||
|
||||
如果你好奇為什麼 Claude Code 在很多場景下比 Trae 或 Cursor 等 Agent 程式設計工具更好用，我們可以簡單看一下它的內部工作機制。
|
||||
|
||||
其他 CLI AI 程式設計工具的整體實現方式也大體類似。
|
||||
|
||||
|
||||
|
||||
Claude Code 會把程式設計任務拆解成一個持續的“感知—思考—行動—驗證”循環，並在其中調用不同工具完成任務。它模仿人類開發者的工作流：不斷“寫程式碼 → 運行 → 看結果 → 再改進”。系統內部通過一個主任務循環不斷執行步驟，在每一輪循環中，Claude 都可以調用不同工具——例如讀寫文件、執行命令、搜索程式碼等——再根據工具返回的真實結果決定下一步行動。
|
||||
|
||||
其中有幾個關鍵特性值得注意：
|
||||
|
||||
- **流式處理（Stream Processing）**：Claude 可以一邊思考一邊輸出結果，而不是必須等所有程式碼寫完再執行。
|
||||
- **智能壓縮（Intelligent Compression）**：長對話容易導致上下文過長，Claude 通過將歷史壓縮成關鍵資訊來減少“遺忘”的概率，並通過區分長短期記憶保證高效運行。
|
||||
- **併發控制（Concurrency Control）**：內部並行設計可以讓多個任務同時進行，互不干擾。
|
||||
- **子 Agent 管理（Sub-agent Management）**：實際工作中並不只相當於一個“角色”處理所有事情，你可以管理多個子 Agent 協作處理程式碼，每個 Agent 負責不同任務，比如專門負責測試、專門負責寫文檔等。
|
||||
|
||||
### Codex
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
和 Claude Code 類似，Codex 是由 OpenAI 開發的一款 AI 協作程式設計工具，你可以把它理解成 “OpenAI 版的 Claude Code”。它最大的優勢是對 GPT-5 的高效適配。
|
||||
|
||||
從實際體驗來看，GPT-5 目前響應速度更快、犯錯率更低（在多輪複雜任務中正確完成的概率更高）。它的一個缺點是解釋往往偏“學術”和“技術”，有時顯得過於嚴謹、資訊量很大，對初學者來說可能略微難懂。
|
||||
|
||||
你可以通過下面的命令安裝 Codex：
|
||||
|
||||
```
|
||||
npm i -g @openai/codex
|
||||
```
|
||||
|
||||
#### 使用 OpenAI 官方 API 作為後端
|
||||
|
||||
如果直接使用 OpenAI 官方的 Codex 入口，配置會非常簡單：當你已經開通 OpenAI 訂閱或申請到了相應 API 配額之後，只需要在命令行中輸入 `codex` 啟動程序，並按提示完成登錄即可。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### 使用轉發 OpenAI API 的方式作為後端
|
||||
|
||||
由於官方 OPENAI API 可能存在價格較高、網路要求嚴格等問題，為了避免這些限制，我們也可以通過其他 API 網關服務來轉發調用。
|
||||
|
||||
在這種方式下，我們只需要在第三方轉發平臺上購買對應的 Codex API 配額，就能獲得接近原生 OpenAI Codex 的使用體驗。
|
||||
|
||||
參考： <https://open-dev.feishu.cn/wiki/PAqUwWG4IiuwTvkQ2sGcaQuPnXc>
|
||||
充值地址： <https://api.zyai.online/account/topup/recharge>
|
||||
|
||||
需要注意的是，在拿到 token 配額後，我們還需要在本地配置好 API Key。
|
||||
|
||||
在密鑰分組設置中，要注意選擇專門用於 Codex 的那一項。
|
||||
|
||||
|
||||
|
||||
接下來，我們需要把獲取到的 Key 填入下面的提示詞中，並把整段提示詞交給 Trae，讓它幫你完成整個配置過程：
|
||||
|
||||
````bash
|
||||
My API key is: [Paste your obtained sk-xxxxx key here]
|
||||
|
||||
Please help me complete the following configuration tasks:
|
||||
|
||||
1. Create configuration directory
|
||||
- Create a `.codex` folder under my user directory
|
||||
- Windows path should be: `C:\Users\[My Username]\.codex`
|
||||
2. Backup existing configuration (if exists)
|
||||
- Check if `.codex\config.toml` exists
|
||||
- If it exists, rename it to `config.toml.bak.[current timestamp]` (timestamp format: yyyyMMddHHmmss)
|
||||
3. Create configuration file
|
||||
- Create `config.toml` in the `.codex` directory
|
||||
- Write the following complete content:
|
||||
```toml
|
||||
preferred_auth_method = "apikey"
|
||||
|
||||
[model_providers.myrelay]
|
||||
name = "My Relay Station"
|
||||
base_url = "https://api.zyai.online/v1"
|
||||
env_key = "MYRELAY_API_KEY"
|
||||
wire_api = "responses"
|
||||
request_max_retries = 4
|
||||
stream_max_retries = 10
|
||||
stream_idle_timeout_ms = 300000
|
||||
|
||||
[profiles.myrelay]
|
||||
model_provider = "myrelay"
|
||||
model = "gpt-5"
|
||||
model_reasoning_effort = "medium"
|
||||
|
||||
[tools]
|
||||
web_search = true
|
||||
|
||||
4. Set system environment variable
|
||||
Variable name: MYRELAY_API_KEY
|
||||
Variable value: The key I gave you
|
||||
|
||||
5. Confirm completion and report back:
|
||||
|
||||
The full path of the configuration file
|
||||
Whether the environment variable was set successfully
|
||||
I can use the command `codex --profile myrelay` to run it
|
||||
````
|
||||
|
||||
配置完成後，你就可以通過 `codex --profile myrelay` 啟動使用轉發 API 的 Codex 了。之後的使用方式與 Claude Code 類似：只需要在對話框中隨時輸入你的想法和需求即可。
|
||||
|
||||
### OpenCode
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
OpenCode 是一款面向開發者的開源 AI Coding Agent 平臺，定位類似於 “多模型版的 Claude Code”。它以 Terminal 為核心交互入口，同時也支持編輯器集成（如 VS Code、Neovim 等），能夠深度接入本地程式碼倉庫，並通過自然語言完成從程式碼理解到工程執行的一整套開發流程。
|
||||
|
||||
它不是綁定單一模型的 AI 程式設計工具，而是一個可自由切換 GPT、Claude、Gemini 乃至本地模型的開放式 AI Coding Agent 平臺。就連 OpenAI 官方也持 OpenCode 接入 Codex / OpenAI 訂閱。
|
||||
|
||||
|
||||
|
||||
你可以通過下面的命令安裝 OpenCode:
|
||||
|
||||
```bash
|
||||
# Linux / Unix
|
||||
curl -fsSL https://opencode.ai/install | bash
|
||||
|
||||
# Windows
|
||||
npm i -g opencode-ai
|
||||
```
|
||||
|
||||
#### 使用 OpenCode 中的免費模型
|
||||
|
||||
在 OpenCode 中不定期會提供免費模型可以進行使用, 配置也非常簡單。你可以在你需要使用 OpenCode 的位置在命令行輸入 `opencode` 啟動 Opencode 程序進入聊天面板。輸入 `/models`命令搜索 free 關鍵詞就可以看到帶有 free 字眼的免費模型
|
||||
|
||||
|
||||
|
||||
在一般情況下免費模型完成編碼任務會比付費 / 訂閱模型要慢一些，這通常取決於模型線路是否阻塞, 是否編碼高峰期以及模型本身的能力。
|
||||
|
||||
#### 使用第三方模型來作為 OpenCode 的主編碼模型
|
||||
|
||||
這是 OpenCode 的核心優勢, 它可以在使用同樣的 MCP, Skills, 上下文的情況下允許你自由切換模型來完成不同的編碼任務。下文以 OpenAI 官方的 GPT-5.3 Codex 為例，接入 OpenCode 作為主編碼模型。
|
||||
|
||||
在 OpenCode 的聊天窗口中輸入 `/connect` 命令選中第一條最相關指令按下 enter 鍵，就可以進行選擇第三方模型提供商的認證授權。
|
||||
|
||||
|
||||
|
||||
這裡以選擇 OpenAI 為例,進行回車選擇認證方式。
|
||||
|
||||
|
||||
|
||||
選哪種都可以,只是認證方式不同。這裡選擇第一種進行瀏覽器登錄。
|
||||
|
||||
|
||||
|
||||
複製此鏈接到瀏覽器上進行正常的 OpenAI 登錄操作，瀏覽器上出現 Authorization Successful 後 OpenCode 客戶端會自動跳轉至選擇 OpenAI 的模型界面。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### 安裝 Oh My OpenAgent 插件
|
||||
|
||||
OpenCode 的強大之處還在於他有非常活躍的社區生態，你可以在 Github 上搜索出非常多與 OpenCode 相關的插件。如果說 OpenCode 是一款可以任意切換模型的 AI 協作工具的話，那麼 Oh-My-OpenAgent 就是一款運行在 OpenCode 之上的 "多 Agent AI 程式設計指揮系統"。它可以將一個複雜任務拆給多個子任務分給不同的模型進行各司其職的工作。
|
||||
|
||||
|
||||
|
||||
你可以將以下話術複製之後粘貼給上文在 OpenCode 中配置好的模型進行安裝 OpenCode。
|
||||
|
||||
```text
|
||||
Install and configure oh-my-openagent by following the instructions here:
|
||||
https://raw.githubusercontent.com/code-yeongyu/oh-my-openagent/refs/heads/dev/docs/guide/installation.md
|
||||
```
|
||||
|
||||
以下是 Oh-My-OpenAgent 的特性以及功能說明。
|
||||
|
||||
| 特性 | 功能說明 |
|
||||
| :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| **自律軍團 (Discipline Agents)** | Sisyphus 負責調度 Hephaestus、Oracle、Librarian 和 Explore。一支完整的 AI 開發團隊並行工作。 |
|
||||
| **Team Mode** (v4.0, 選擇性啟用) | 領導 Agent + 最多 8 個並行成員，實時 tmux 可視化，專用 `team_*` 工具家族。驅動 `hyperplan`(5 個敵對評論者) 和 `security-research`(3 個獵手 + 2 個 PoC 工程師)。[文檔 →](docs/guide/team-mode.md) |
|
||||
| **`ultrawork` / `ulw`** | 一鍵觸發，所有智能體出動。任務完成前絕不罷休。 |
|
||||
| **[IntentGate 意圖門](https://factory.ai/news/terminal-bench)** | 真正行動前，先分析用戶的真實意圖。徹底告別被字面意思誤導的 AI 廢話。 |
|
||||
| **基於哈希的編輯工具** | 每次修改都通過 `LINE#ID` 內容哈希驗證、0% 錯誤修改。靈感來自 [oh-my-pi](https://github.com/can1357/oh-my-pi)。[The Harness Problem →](https://blog.can.ac/2026/02/12/the-harness-problem/) |
|
||||
| **LSP + AST-Grep** | 工作區級別的重命名、構建前診斷、基於 AST 的重寫。為 Agent 提供 IDE 級別的精度。 |
|
||||
| **後臺智能體** | 同時發射 5+ 個專家並行工作。保持上下文乾淨，隨時獲取成果。 |
|
||||
| **內置 MCP** | Exa（網路搜索）、Context7（官方文檔）、Grep.app（GitHub 源碼搜索）。默認開啟。 |
|
||||
| **Ralph Loop / `/ulw-loop`** | 自我引用閉環。達不到 100% 完成度絕不停止。 |
|
||||
| **Todo 強制執行** | Agent 想要摸魚？系統直接揪著領子拽回來。你的任務，必須完成。 |
|
||||
| **註釋審查員** | 剔除帶有濃烈 AI 味的冗餘註釋。寫出的程式碼就像老練的高級工程師寫的。 |
|
||||
| **Tmux 集成** | 完整的交互式終端支持。跑 REPL、用調試器、用 TUI 工具，全都在實時會話中完成。 |
|
||||
| **Claude Code 兼容** | 你現有的 Hooks、命令、技能、MCP 和插件？全都能無縫遷移過來。 |
|
||||
| **技能內嵌 MCP** | 技能自帶其所需的 MCP 服務器。按需開啟，不會撐爆你的上下文窗口。 |
|
||||
| **Prometheus 規劃師** | 動手寫程式碼前，先通過訪談模式做好戰略規劃。 |
|
||||
| **`/init-deep`** | 在整個項目目錄層級中自動生成 `AGENTS.md`。不僅省 Token，還能大幅提升 Agent 理解力。 |
|
||||
|
||||
Sisyphus (claude-opus-4-7 / kimi-k2.6 / glm-5.1) 是你的主指揮官。他負責制定計劃、分配任務給專家團隊，並以極其激進的並行策略推動任務直至完成。他從不半途而廢。
|
||||
|
||||
Hephaestus (gpt-5.5) 是你的自主深度工作者。你只需要給他目標，不要給他具體做法。他會自動探索程式碼庫模式，從頭到尾獨立執行任務，絕不會中途要你當保姆。名副其實的正牌工匠。
|
||||
|
||||
Prometheus (claude-opus-4-7 / kimi-k2.6 / glm-5.1) 是你的戰略規劃師。他通過訪談模式，在動一行程式碼之前，先通過提問確定範圍並構建詳盡的執行計劃。
|
||||
|
||||
瞭解完這些, 你就可以使用裝好 Oh-My-OpenAgent 插件之後的 OpenCode 來完成編碼任務了。
|
||||
|
||||
## CLI AI 程式設計工具的更多用法
|
||||
|
||||
### 用 AI 寫需求文檔：學會“具體化需求”
|
||||
|
||||
對於大語言模型來說，抽象需求需要被“具體化”。比如：“我很餓”是一個抽象需求，我們需要把它變成：“我肚子有點餓，可能需要吃一個紅豆麵包，再配一杯豆漿。”——這才是一種可以被執行的、具體的需求。
|
||||
|
||||
但把抽象需求變具體，其實是一個很花精力的過程。如果我們沒有見過足夠多的案例，很難快速聯想到該如何把抽象問題拆解成細緻的模塊。這種時候，最好的辦法就是讓 AI 幫你完成“具體化”這一步。
|
||||
比如，我想開發一個“每日計劃”應用，最樸素的想法可能是：
|
||||
|
||||
`Please help me write a daily planning app where I can write my plans each day and get reminders.`
|
||||
|
||||
AI 確實可以在這個需求基礎上直接拆分任務，然後一步步完成，但中間容易出錯或理解偏差。為了降低風險，我們可以讓 AI 幫我們先擴寫需求：
|
||||
|
||||
`Based on my needs, please elaborate and provide a more detailed Product Requirement Document for reference. My idea is: Please help me write a daily planner app that supports daily plan-writing and provides reminders .`
|
||||
|
||||
這時，AI 可能會給出類似下面這樣完整的 PRD：
|
||||
|
||||
```
|
||||
Product Requirements Document (PRD): “Today’s Plan” App
|
||||
Document Version: 1.0
|
||||
Creation Date: October 27, 2023
|
||||
Author: (Your Name/Product Manager)
|
||||
|
||||
1. Product Introduction
|
||||
1.1 Product Name
|
||||
Today's Plan
|
||||
1.2 Product Vision
|
||||
“Today’s Plan” is a minimalist and highly efficient daily planning and reminder tool, dedicated to helping users eliminate procrastination and forgetfulness, plan every day clearly, and ensure tasks are carried out through an intelligent reminder system—ultimately enabling users to gain a stronger sense of control and achievement over their time.
|
||||
1.3 Target Users (User Personas)
|
||||
We mainly serve three types of users:
|
||||
Students (Xiao Ming):
|
||||
Characteristics: Multiple tasks such as courses, assignments, club activities, exam prep, needing organized time arrangement.
|
||||
Pain Points: Easily forget small tasks or assignment deadlines; feel overwhelmed switching between tasks; want to build regular study and life habits.
|
||||
Needs: A simple tool to list daily to-dos and provide reminders before class/self-study.
|
||||
Office Workers (Zhang Wei):
|
||||
Characteristics: Fast-paced work, many meetings, reports, project milestones, and personal affairs (fitness, picking up children).
|
||||
Pain Points: Easily forget important meetings or work milestones; get interrupted by urgent tasks and forget the original plan; feel busy but inefficient at end of day.
|
||||
Needs: Need a tool to quickly record and schedule daily work and send strong reminders at key times (e.g., 15 minutes before meetings).
|
||||
Freelancers/Self-disciplined Seekers (Li Na):
|
||||
Characteristics: High freedom of time, but strong self-management required for work output and personal growth.
|
||||
Pain Points: Easily procrastinate, lack external supervision; start the day without a clear plan, leading to low time utilization.
|
||||
Needs: Need a tool to help build a daily fixed routine (Morning Routine) and review daily achievements for positive feedback.
|
||||
|
||||
2. User Stories
|
||||
As a user, I want to quickly create today’s plan list so I have an overview of all my tasks for the day.
|
||||
As a user, I want to set specific start and end times for each task so I can create a visual timeline.
|
||||
As a user, I want to receive push notification reminders before a task starts so I won’t miss any important arrangements.
|
||||
As a user, I want to customize the reminder time (such as 5, 15, or 60 minutes in advance) so reminders better fit my habits.
|
||||
As a user, I want to easily mark completed tasks so I can feel accomplished and clearly see my progress.
|
||||
As a user, I want to see a summary of my completed plans at the end of each day for reviewing and self-motivation.
|
||||
As a user, I want to conveniently edit and delete tasks to handle last-minute changes.
|
||||
As a user, I want to view plans and achievements from previous days to review my efficiency and habits.
|
||||
|
||||
3. Feature Breakdown
|
||||
Core Features (MVP - Minimum Viable Product)
|
||||
Module 1: Plan Management
|
||||
3.1.1 Daily Plan Homepage
|
||||
Interface: “Today” as the core view, current date shown at the top.
|
||||
View: Timeline list, clearly showing tasks scheduled from morning to evening. Tasks without a time can be listed in the top or bottom “To-do List” section.
|
||||
Interactions:
|
||||
Click the “+” button in the bottom right to quickly create a new task.
|
||||
Pull down to refresh the page.
|
||||
Swipe left/right to view yesterday’s and tomorrow’s plans.
|
||||
3.1.2 Create/Edit Task
|
||||
Entry: Click “+” on the homepage or a time slot in the list.
|
||||
Fields:
|
||||
Task title (required): Briefly describe the task, e.g., “10 AM Weekly Product Meeting.”
|
||||
Task time (optional):
|
||||
Set “start time” and “end time.”
|
||||
Provide “all-day” option for unspecified time tasks.
|
||||
Default time picker should be quick and convenient.
|
||||
Reminder setting (required, with default value): See Module 2.
|
||||
Notes (optional): Add further descriptions, links, or location info.
|
||||
Actions: Save, cancel, delete task.
|
||||
3.1.3 Task Interaction
|
||||
Mark as complete: Checkbox before each task; checking adds a strikethrough and gray background, indicating completion. Can unmark if needed.
|
||||
Edit task: Click the task itself to enter edit page.
|
||||
Delete task: Swipe left on a task to reveal “Delete” button.
|
||||
Module 2: Smart Reminder System
|
||||
3.2.1 Reminder Trigger
|
||||
Mechanism: Based on task’s set “start time” and the user’s “reminder lead time,” send a push notification from device.
|
||||
Offline Support: Locally scheduled reminders must trigger even if user is offline.
|
||||
3.2.2 Reminder Content & Format
|
||||
Notification title: App name “Today’s Plan.”
|
||||
Body: “Reminder: [Task Title] will start at [Start Time].” E.g., “Reminder: Product Meeting will start at 10:00.”
|
||||
Sound: Use system default or offer several simple, effective tones.
|
||||
3.2.3 Reminder Settings
|
||||
Global Settings (in Settings page):
|
||||
User can set a default reminder time, e.g., “15 minutes before task starts.” New tasks adopt this by default.
|
||||
Single Task Settings (in create/edit page):
|
||||
Users can override global settings for important tasks, choosing specific reminder times like "on time," "5 minutes early," "30 minutes early," or "1 hour early."
|
||||
Provide “no reminder” option.
|
||||
Subsequent Features (V1.1, V2.0)
|
||||
3.3 Daily Review & Statistics
|
||||
Push a summary notification at a set time every night (e.g., 22:00): “How was your day? Take a look at your achievements!”
|
||||
Generate a simple daily report card: shows total planned tasks, completed tasks, completion rate, plus an encouraging message.
|
||||
3.4 History Review
|
||||
Calendar view to click on any past day and check its plans and completion status. Days with high completion rates marked with a special color.
|
||||
3.5 Templates
|
||||
Allow users to save a successful daily plan as a template, e.g., “Efficient Workday,” “Relaxing Weekend.”
|
||||
When creating tomorrow’s plan, one-click import a template, modify slightly to save time.
|
||||
3.6 Themes & Personalization
|
||||
Offer dark mode.
|
||||
Allow changing several primary color themes.
|
||||
|
||||
4. Non-Functional Requirements
|
||||
4.1 Performance
|
||||
Response: App launch time under 2 seconds; adding/editing tasks must be smooth and lag-free.
|
||||
Resource Use: Low battery and memory consumption in background; do not over-consume resources waiting for reminders.
|
||||
4.2 Usability
|
||||
Minimal & intuitive: UI must be minimal, primary functions accessible within 3 clicks. No tutorial needed for new users.
|
||||
Error tolerance: Offer undo (e.g. brief undo after mistakenly deleting a task).
|
||||
4.3 Reliability
|
||||
Reliable reminders: Reminder function is the product’s lifeline; must guarantee 99.99% timely and accurate delivery.
|
||||
Data loss-free: User plans must be reliably stored locally. Future versions can support cloud sync to prevent data loss on device change.
|
||||
4.4 Compatibility
|
||||
Platform: Support major iOS and Android versions (latest 3-4 releases).
|
||||
Screen: Layout must fit various phone screen sizes.
|
||||
|
||||
5. Roadmap
|
||||
V1.0 (MVP):
|
||||
Goal: Validate core value—planning & reminders.
|
||||
Features: Complete all “Core Features” described above (Plan management, smart reminders).
|
||||
V1.1 (Quick Optimization):
|
||||
Goal: Improve retention and achievement.
|
||||
Features: Add “Daily Review & Statistics,” “History Review.”
|
||||
V2.0 (Enhanced Experience):
|
||||
Goal: Increase efficiency and personalization.
|
||||
Features: Add “Templates,” “Themes & Personalization,” and start developing “Cloud Sync.”
|
||||
```
|
||||
|
||||
對比我們最開始那句“幫我寫一個每天可以記計劃並提醒的應用”，現在這份文檔已經詳細得多了。你可以根據自己的真實需求，對其中的內容進行增刪修改；對於某些你不確定的模塊，也可以繼續讓 AI 提供更多備選方案，你再挑選、合併成最終版本。
|
||||
|
||||
通過這種方式，我們可以很輕鬆地把抽象想法變成具體描述。對 AI 開發來說，“具體”就是生產力：需求越具體，越容易得到結構穩定、質量較高的項目。你可以嘗試用這種方式重做一下之前的某個小項目，對比一下效果差異。
|
||||
|
||||
如果你覺得這類“需求提示詞”太長，非常自然的做法，是把它單獨寫進一個 markdown 文檔中，作為你的“需求文檔 / 開發文檔 / PRD”。之後每次讓 AI 寫項目時，只需要讓它“參考這份文檔”，而不是每次都重打一遍長提示。你也可以在迭代中不斷完善這份文檔，讓後續項目直接受益。
|
||||
|
||||
下面是一些其他常見的使用場景：
|
||||
|
||||
### 管理文件夾
|
||||
|
||||
我們可以嘗試用 CLI AI 程式設計工具來管理當前文件夾中的各種文件。比如，你有一堆雜亂無章的文件，需要整理歸類，就可以對 Claude Code 或 Codex 說：
|
||||
|
||||
`Please help me organize the contents of the current folder. I want to group files with the same content together & I want to group files from the same time period together. Please help me handle this.`
|
||||
|
||||
### 開發新項目
|
||||
|
||||
這和我們之前在 z.ai、Trae 中的用法幾乎完全一樣——我們也可以直接用 CLI AI 程式設計工具來從零開發新項目。當然，最好提前準備好一份需求文檔。
|
||||
|
||||
需求文檔越細緻，最終效果越好。你可以根據不斷變化的想法，對文檔做多輪優化；文檔越完善，程式碼實現就越穩定、越成熟。
|
||||
|
||||
### 部署開源項目（例如 Dify）
|
||||
|
||||
對於剛接觸計算機的同學來說，從 GitHub 上部署一個開源項目往往很有難度。但我們完全可以把這件事交給 Claude Code，就像我們在 Dify 教程中做的那樣：
|
||||
|
||||
<https://github.com/langgenius/dify>
|
||||
|
||||
如果我想在本地跑起自己的 Dify，只需要把這個鏈接扔給 Claude Code，然後輸入：
|
||||
|
||||
`I want to deploy this GitHub project ``https://github.com/langgenius/dify`` . Please help me clone the project and run it.`
|
||||
|
||||
收到你的請求後，Claude Code 會自動完成一系列操作，包括從 GitHub 拉取程式碼、配置運行環境、啟動項目等。如果中間某一步出錯或項目啟動狀態不正常，你再根據提示進行少量人工處理即可。除了 Dify，你也可以用 Claude Code 幫你部署大部分常見的 GitHub 開源項目——你只需要一個對話框，再加上喝一杯咖啡的時間 ☕️。
|
||||
|
||||
|
||||
|
||||
### 講解程式碼與撰寫文檔
|
||||
|
||||
對於一些複雜項目，或者 AI 自動生成的大型項目，你可能會覺得程式碼太長、邏輯太多，很難看懂。這時就可以讓 CLI AI 程式設計工具幫你“讀程式碼”。你可以這樣提問：
|
||||
|
||||
- 請幫我解釋這個項目：如何運行、如何使用、後續如何修改和繼續開發？
|
||||
- 請幫我說明這個項目的整體流程：程序是怎樣運行的？用戶在界面中可以做哪些操作？
|
||||
- 請幫我為這個項目寫一份完整的文檔，包括開發文檔和運行文檔等。
|
||||
- 請基於我當前文件夾裡的所有內容，寫一份詳細說明，並保存到指定的 markdown 文檔中。
|
||||
|
||||
### 更多玩法
|
||||
|
||||
當然，CLI AI 程式設計工具能做的遠不止上面這些。不要只把它當作“寫程式碼工具”，而是把它看作一個具有獨立行動能力的智能 Agent。你可以讓它幫你：
|
||||
|
||||
- 管理和整理本地文件；
|
||||
- 寫日記、寫總結；
|
||||
- 分析和修復系統錯誤；
|
||||
- 執行各種重複性命令行任務等。
|
||||
|
||||
也許在不久的將來，它會變成你電腦上最重要、也最懂你的 AI 夥伴。
|
||||
@@ -0,0 +1,907 @@
|
||||
# 如何集成 Stripe 等收費系統
|
||||
|
||||
當你的產品已經有了頁面、登錄、資料庫和基礎後端之後，下一個現實問題就是：**怎麼收費**。
|
||||
|
||||
很多人第一次接支付，會把注意力全放在"怎麼跳轉到付款頁"上。但真正決定系統是否穩定的，不是按鈕，而是整條收費鏈路：誰決定價格、誰確認支付成功、誰更新資料庫、誰回收權限。
|
||||
|
||||
這篇文章我幫你拆成兩部分：
|
||||
|
||||
- **前半部分**只講最實用的基礎接入，目標是讓你儘快把 Stripe 接進項目。
|
||||
- **後半部分**統一放到附錄，包含 Webhook 細節、訂閱事件、不同國家和地區的支付方案差異。
|
||||
|
||||
> 💡 建議先學完這些章節再繼續
|
||||
>
|
||||
> - [從資料庫到 Supabase](../database-supabase/)
|
||||
> - [大模型輔助編寫接口程式碼與接口文檔](../ai-interface-code/)
|
||||
> - [如何部署 Web 應用](../zeabur-deployment/)
|
||||
|
||||
# 你將學到
|
||||
|
||||
1. 最小可行的支付系統到底長什麼樣。
|
||||
2. 如何用最快的方式把 Stripe 接進你的項目。
|
||||
3. 如何寫提示詞，讓 AI 直接幫你加支付系統。
|
||||
4. 如果不是做海外 Stripe 項目，不同地區應該優先考慮什麼支付方案。
|
||||
|
||||
---
|
||||
|
||||
# 第一部分：基礎上手
|
||||
|
||||
## 1. 先記住 3 個原則
|
||||
|
||||
如果你只記住三件事，就記住下面這三條：
|
||||
|
||||
1. **價格必須由後端決定**，不能相信前端傳來的金額。
|
||||
2. **真正讓權限生效的是 Webhook**，不是 `success` 頁面。
|
||||
3. **你自己的資料庫必須保存支付狀態**，不能只依賴 Stripe 後臺。
|
||||
|
||||
這三條是支付系統最核心的邊界。只要邊界沒錯，後面換 Stripe、PayPal、支付寶、微信支付，本質上都只是"接口換了，架構不變"。
|
||||
|
||||
## 2. 如果不在後端處理，而是前端直接連 Stripe，會怎麼樣？
|
||||
|
||||
這是很多人第一次做支付時最自然的想法：
|
||||
|
||||
- 頁面上已經有"購買"按鈕了
|
||||
- 那我能不能讓前端自己去連 Stripe
|
||||
- 這樣是不是就不用做後端了
|
||||
|
||||
如果你只是做一個假的演示頁面，這樣想當然沒問題。
|
||||
但如果你是真的要收錢，**這條路通常會把事情做壞**。
|
||||
|
||||
最常見的問題有這幾個：
|
||||
|
||||
1. **價格容易被改**
|
||||
瀏覽器裡的請求，是用戶自己電腦上發出去的。別人是可以改請求內容的。
|
||||
2. **敏感資訊容易暴露**
|
||||
真正重要的密鑰、價格邏輯、會員開通邏輯，本來就不該放在前端。
|
||||
3. **你沒法可靠確認"這筆錢到底算不算成功"**
|
||||
用戶跳到成功頁，不代表你的資料庫已經同步對了。
|
||||
4. **資料庫狀態會亂**
|
||||
用戶可能說"我明明已經付錢了"，但你自己的系統里根本沒記上。
|
||||
|
||||
所以更安全的分工應該是：
|
||||
|
||||
- 前端負責：展示按鈕、發起購買、跳轉頁面
|
||||
- 後端負責：決定價格、創建支付會話、接收 Webhook、更新資料庫
|
||||
|
||||
::: info 這一段你可以直接記成一句話
|
||||
**前端可以負責跳轉，後端必須負責定價和確認。**
|
||||
|
||||
只要是真收錢，就不要把"最終價格決定權"和"支付成功後的開通邏輯"放在前端。
|
||||
:::
|
||||
|
||||
## 3. 什麼時候適合先用 Stripe
|
||||
|
||||
如果你做的是下面這些場景，Stripe 往往是最順手的起點：
|
||||
|
||||
- 面向海外用戶的 SaaS
|
||||
- 訂閱制會員產品
|
||||
- 數字產品、模板、AI 積分包
|
||||
- 想先快速驗證商業化，而不是一開始就處理太多本地支付細節
|
||||
|
||||
如果你的主要用戶在中國大陸，那通常不會把 Stripe 當第一選擇，這個我放到附錄裡統一講。
|
||||
|
||||
## 4. 最小可行支付鏈路
|
||||
|
||||
先看最小版本。只要這條鏈路能跑通，你的支付系統就有了骨架。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
user["用戶"]
|
||||
frontend["前端頁面"]
|
||||
backend["你的後端"]
|
||||
checkout["Stripe Checkout"]
|
||||
webhook["Stripe Webhook"]
|
||||
db["Supabase / 業務資料庫"]
|
||||
|
||||
user -->|"點擊購買"| frontend
|
||||
frontend -->|"請求創建支付會話"| backend
|
||||
backend -->|"按後端價格創建 Session"| checkout
|
||||
frontend -->|"跳轉到支付頁"| checkout
|
||||
checkout -->|"支付完成後發送事件"| webhook
|
||||
webhook -->|"校驗簽名並更新狀態"| backend
|
||||
backend -->|"寫入 orders / subscriptions"| db
|
||||
db -->|"前端刷新後讀取最新狀態"| frontend
|
||||
```
|
||||
|
||||
把它翻譯成人話就是：
|
||||
|
||||
1. 用戶點按鈕。
|
||||
2. 前端找後端要支付鏈接。
|
||||
3. 後端用 Stripe 密鑰創建支付會話。
|
||||
4. 用戶去 Stripe 頁面付款。
|
||||
5. Stripe 把"付款真的成功了"這件事通過 Webhook 通知你。
|
||||
6. 你的後端再去更新資料庫。
|
||||
|
||||
## 5. 發起付款的標準時序圖
|
||||
|
||||
如果你習慣看更規範的系統圖，可以直接看這張時序圖：
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor User as 用戶
|
||||
participant Frontend as 前端頁面
|
||||
participant Backend as 後端 API
|
||||
participant Stripe as Stripe Checkout
|
||||
|
||||
User->>Frontend: 點擊"升級"或"購買"
|
||||
Frontend->>Backend: POST /api/billing/create-checkout-session
|
||||
Note right of Frontend: 前端傳 plan / userId / email\n不傳最終收費金額
|
||||
Backend->>Backend: 校驗套餐並映射 priceId
|
||||
Backend->>Stripe: 創建 Checkout Session
|
||||
Stripe-->>Backend: 返回 session.url
|
||||
Backend-->>Frontend: 返回支付鏈接
|
||||
Frontend-->>User: 跳轉到 Stripe 支付頁
|
||||
User->>Stripe: 完成付款
|
||||
```
|
||||
|
||||
## 6. 快速開始
|
||||
|
||||
如果你想最快把它接進項目，照著下面這 5 步做就夠了。
|
||||
|
||||
### 6.1 第一步：在 Stripe 後臺創建商品和價格
|
||||
|
||||
這一步的目的，不是"先隨便配點東西"，而是先把 **你到底在賣什麼、打算怎麼收費** 這件事在 Stripe 裡定義清楚。
|
||||
|
||||
在 Stripe 的模型裡：
|
||||
|
||||
- **Product** 表示"你賣的是什麼"，比如 `Pro 會員`
|
||||
- **Price** 表示"這個東西賣多少錢、按什麼週期賣"，比如 `月付 9.9 美元`、`年付 99 美元`
|
||||
|
||||
為什麼要先做這一步？
|
||||
因為後面當你的後端創建 Checkout Session 時，並不是直接傳一個金額給 Stripe，而是要傳一個已經存在的 `price_id`。Stripe 再根據這個 `price_id` 去生成真正的支付頁、金額、幣種和訂閱週期。
|
||||
|
||||
如果你跳過這一步，後面的"創建支付鏈接"其實就沒法做。
|
||||
|
||||
::: info 為什麼這裡要先停一下
|
||||
很多新手看到 `Product`、`Price` 這兩個詞會有點煩，覺得像是在學 Stripe 的內部術語。
|
||||
|
||||
但實際上，這一步是在做一件很樸素的事：
|
||||
- 把"賣什麼"定義清楚
|
||||
- 把"賣多少錢"定義清楚
|
||||
- 讓後端之後能拿一個穩定的 `price_id` 去創建支付鏈接
|
||||
|
||||
只要把這層想明白，後面的 Checkout Session 就不會覺得抽象。
|
||||
:::
|
||||
|
||||
對於一個最小可行的訂閱系統，你至少先建這兩個層級：
|
||||
|
||||
- 一個 `Product`
|
||||
- 一個或多個 `Price`
|
||||
|
||||
你可以直接打開這些頁面：
|
||||
|
||||
- Stripe Dashboard 登錄頁：[Dashboard Login](https://dashboard.stripe.com/login)
|
||||
- Stripe 商品與價格管理文檔：[Manage products and prices](https://docs.stripe.com/products-prices/manage-prices)
|
||||
- Stripe Checkout 快速開始文檔：[Build a Stripe-hosted checkout page](https://docs.stripe.com/checkout/quickstart?lang=node)
|
||||
- Stripe Dashboard 商品頁：[Product catalog](https://dashboard.stripe.com/test/products)
|
||||
|
||||
推薦你先在 **Test mode（測試模式）** 下操作，不要一開始就在正式環境裡建。
|
||||
|
||||
一個最常見的最小配置是：
|
||||
|
||||
- `Product`: `Pro Plan`
|
||||
- `Price 1`: `pro_monthly`
|
||||
- `Price 2`: `pro_yearly`
|
||||
|
||||
你在後臺操作時，可以按這個順序理解：
|
||||
|
||||
1. 先創建一個商品 `Pro Plan`
|
||||
2. 再在這個商品下面掛兩個價格
|
||||
3. 月付和年付其實是同一個商品的兩種收費方式
|
||||
|
||||
完成後，你至少要記下這些資訊：
|
||||
|
||||
- 月付價格的 `price_id`
|
||||
- 年付價格的 `price_id`
|
||||
- 你自己的套餐名，例如 `pro_monthly`、`pro_yearly`
|
||||
|
||||
如果你是第一次進 Stripe 後臺，建議你把這一步理解成：
|
||||
|
||||
- `Product` 決定支付頁裡賣的是什麼
|
||||
- `Price` 決定支付頁裡收多少錢
|
||||
- 後端之後真正會用到的，主要是 `price_id`
|
||||
|
||||
::: info 真正要記下來的值
|
||||
這一頁裡最重要的不是商品名稱，而是 `price_id`。
|
||||
|
||||
後面無論是讓 AI 幫你接後端，還是你自己排查問題，真正會頻繁用到的，通常都是：
|
||||
- `STRIPE_PRICE_PRO_MONTHLY`
|
||||
- `STRIPE_PRICE_PRO_YEARLY`
|
||||
- 它們背後對應的兩個 `price_id`
|
||||
:::
|
||||
|
||||
如果你想讓 AI 先帶你把後臺配置做完，可以直接用這個 prompt：
|
||||
|
||||
```text
|
||||
我現在是第一次用 Stripe，你先不要改程式碼，先帶我在 Stripe 後臺把最基本的付費配置做好。
|
||||
|
||||
請基於這些官方文檔給我一步一步的操作說明：
|
||||
- https://docs.stripe.com/products-prices/manage-prices
|
||||
- https://docs.stripe.com/checkout/quickstart?lang=node
|
||||
|
||||
我的情況是：
|
||||
- 我想做一個最簡單的會員付費
|
||||
- 只有兩個套餐：月付和年付
|
||||
- 我現在還不懂 Product、Price 這些詞
|
||||
|
||||
請你：
|
||||
1. 先用最簡單的話告訴我 Product 和 Price 分別是什麼。
|
||||
2. 再按"先打開哪個頁面 -> 點哪裡 -> 填什麼"的順序教我操作。
|
||||
3. 最後提醒我，做完以後我需要從後臺複製哪些內容給後端使用。
|
||||
4. 如果我容易走錯，請順便提醒我應該一直在測試模式裡操作。
|
||||
```
|
||||
|
||||
### 6.2 第二步：準備環境變量
|
||||
|
||||
你通常至少需要準備這些環境變量：
|
||||
|
||||
- `STRIPE_SECRET_KEY`
|
||||
- `STRIPE_WEBHOOK_SECRET`
|
||||
- `STRIPE_PRICE_PRO_MONTHLY`
|
||||
- `STRIPE_PRICE_PRO_YEARLY`
|
||||
- `APP_URL`
|
||||
- `SUPABASE_URL`
|
||||
- `SUPABASE_SERVICE_ROLE_KEY`
|
||||
|
||||
你可以直接打開這些頁面：
|
||||
|
||||
- Stripe API Keys 文檔：[API keys](https://docs.stripe.com/keys)
|
||||
- Stripe Dashboard API Keys 頁面：[API Keys](https://dashboard.stripe.com/test/apikeys)
|
||||
- Stripe Webhooks 文檔：[Receive Stripe events in your webhook endpoint](https://docs.stripe.com/webhooks)
|
||||
- Stripe Dashboard Webhooks 頁面：[Workbench Webhooks](https://dashboard.stripe.com/test/workbench/webhooks)
|
||||
|
||||
> ⚠️ `STRIPE_SECRET_KEY` 和 `SUPABASE_SERVICE_ROLE_KEY` 都只能放在後端。
|
||||
|
||||
::: info 環境變量這一步的目的
|
||||
這一步不是為了"先把 `.env` 填滿"，而是為了把支付系統裡最敏感的幾樣東西放到後端保管：
|
||||
|
||||
- Stripe 的後端密鑰
|
||||
- Webhook 驗籤密鑰
|
||||
- 你自己的價格映射
|
||||
|
||||
簡單理解：
|
||||
前端只負責發起購買，真正的秘密和定價邏輯都應該留在服務端。
|
||||
:::
|
||||
|
||||
這一步也可以直接讓 AI 幫你整理：
|
||||
|
||||
```text
|
||||
請你先看看我這個項目現在是怎麼放環境變量的，然後幫我把 Stripe 需要的環境變量整理出來。
|
||||
|
||||
請參考這些文檔：
|
||||
- https://docs.stripe.com/keys
|
||||
- https://docs.stripe.com/webhooks
|
||||
|
||||
我的情況是：
|
||||
- 我是零基礎
|
||||
- 我分不清哪些變量應該放前端，哪些應該放後端
|
||||
- 我也不確定當前項目應該改 `.env`、`.env.local` 還是別的文件
|
||||
|
||||
請你：
|
||||
1. 先搜索當前項目裡環境變量通常寫在哪。
|
||||
2. 幫我列出 Stripe 接入最少需要哪些變量。
|
||||
3. 用最簡單的話告訴我每個變量是幹什麼的。
|
||||
4. 告訴我每個變量應該去哪一個 Stripe 頁面複製。
|
||||
5. 如果項目裡有示例環境變量文件，請直接幫我補上變量名。
|
||||
```
|
||||
|
||||
### 6.3 第三步：後端創建 Checkout Session
|
||||
|
||||
這一步你不用自己寫接口，直接讓 AI 參考官方文檔幫你實現。
|
||||
|
||||
先把這些文檔給它：
|
||||
|
||||
- Stripe Checkout 快速開始：[Build a Stripe-hosted checkout page](https://docs.stripe.com/checkout/quickstart?lang=node)
|
||||
- Checkout Sessions API：[Create a Checkout Session](https://docs.stripe.com/api/checkout/sessions/create)
|
||||
- 訂閱說明：[Subscriptions](https://docs.stripe.com/payments/subscriptions)
|
||||
|
||||
然後直接貼這個 prompt：
|
||||
|
||||
```text
|
||||
請你先看看我當前項目的後端程式碼是怎麼組織的，然後幫我把 Stripe 支付接進去。
|
||||
|
||||
請參考這些官方文檔：
|
||||
- https://docs.stripe.com/checkout/quickstart?lang=node
|
||||
- https://docs.stripe.com/api/checkout/sessions/create
|
||||
- https://docs.stripe.com/payments/subscriptions
|
||||
|
||||
我的目標很簡單：
|
||||
- 用戶點購買按鈕後，能跳到 Stripe 的付款頁面
|
||||
- 套餐只有月付和年付兩種
|
||||
- 不要讓我自己決定程式碼該放在哪，你先看項目再幫我放到合適的位置
|
||||
|
||||
請你：
|
||||
1. 先搜索項目，弄清楚後端入口文件、路由文件、環境變量寫法分別在哪裡。
|
||||
2. 再參考官方文檔，幫我把"創建 Stripe 支付鏈接"這一步接進去。
|
||||
3. 不要讓我自己傳金額，價格請用後端環境變量來決定。
|
||||
4. 做完後告訴我你改了哪些文件。
|
||||
5. 最後告訴我，我還需要去 Stripe 後臺補哪些配置。
|
||||
```
|
||||
|
||||
### 6.4 第四步：前端跳轉到支付頁
|
||||
|
||||
這一步的目標非常簡單：讓定價頁按鈕調用你的後端接口，再跳轉到 Stripe Checkout。
|
||||
|
||||
參考文檔：
|
||||
|
||||
- Stripe Checkout 集成說明：[Build an integration with Checkout](https://docs.stripe.com/payments/checkout/build-integration)
|
||||
|
||||
給 AI 的 prompt：
|
||||
|
||||
```text
|
||||
幫我把項目裡的"購買"按鈕接上 Stripe。
|
||||
|
||||
要求：
|
||||
- 不動現有頁面，只改按鈕點擊後的邏輯
|
||||
- 點擊後調用後端接口獲取支付鏈接，然後跳轉到 Stripe
|
||||
- 如果出錯，給用戶一個簡單提示（比如"支付暫時不可用，請稍後再試"）
|
||||
|
||||
參考文檔：https://docs.stripe.com/payments/checkout/build-integration
|
||||
```
|
||||
|
||||
### 6.5 第五步：Webhook 更新資料庫狀態
|
||||
|
||||
這是最關鍵的一步。
|
||||
|
||||
::: info 為什麼這一步最關鍵
|
||||
很多人會以為"用戶付完款並且跳轉到了 success 頁面"就算完成了。
|
||||
|
||||
不是。
|
||||
|
||||
對你的系統來說，真正重要的是：
|
||||
**Stripe 有沒有正式把事件打到你的 Webhook，而你的後端有沒有把資料庫狀態更新成功。**
|
||||
:::
|
||||
|
||||
你也可以讓 AI 按 Stripe 官方 Webhook 文檔直接實現，不要自己手寫。
|
||||
|
||||
參考文檔：
|
||||
|
||||
- Stripe Webhooks：[Receive Stripe events in your webhook endpoint](https://docs.stripe.com/webhooks)
|
||||
- Stripe CLI：[Stripe CLI](https://docs.stripe.com/stripe-cli)
|
||||
- Stripe CLI 用法：[Use the Stripe CLI](https://docs.stripe.com/stripe-cli/use-cli)
|
||||
|
||||
給 AI 的 prompt：
|
||||
|
||||
```text
|
||||
請繼續幫我把 Stripe 的"付款成功後自動生效"這一步接好。
|
||||
|
||||
請參考這些官方文檔：
|
||||
- https://docs.stripe.com/webhooks
|
||||
- https://docs.stripe.com/stripe-cli
|
||||
- https://docs.stripe.com/stripe-cli/use-cli
|
||||
|
||||
我的目標是：
|
||||
- 用戶付完錢後，不只是跳轉到成功頁面
|
||||
- 而是真的把我資料庫裡的會員狀態改成已開通
|
||||
|
||||
請你：
|
||||
1. 先搜索當前項目裡資料庫相關程式碼和用戶狀態是怎麼存的。
|
||||
2. 再幫我加 Stripe webhook。
|
||||
3. 支付成功後，把對應用戶改成 active，或者更新成項目裡現在已經在用的會員狀態字段。
|
||||
4. 如果項目裡已經有訂閱表、訂單表、用戶表，請優先沿用現有結構。
|
||||
5. 做完後告訴我你改了哪些文件。
|
||||
6. 順便告訴我本地怎麼測試這一步有沒有真的生效。
|
||||
```
|
||||
|
||||
## 7. 讓 AI 幫你快速接入的提示詞
|
||||
|
||||
如果你用的是 Codex、Claude Code、Trae、Cursor 一類工具，可以直接把下面這個提示詞貼給它，讓它在你的項目裡做支付接入。
|
||||
|
||||
```text
|
||||
請你幫我把當前項目接上 Stripe 支付，我希望做一個最簡單能跑起來的會員收費功能。
|
||||
|
||||
我的要求：
|
||||
1. 我是零基礎，請你先自己看項目，再決定程式碼應該改哪裡。
|
||||
2. 不要讓我自己判斷目錄結構、路由結構、資料庫結構。
|
||||
3. 我只想先做最簡單版本：月付和年付兩個套餐。
|
||||
4. 用戶點擊購買後，能跳到 Stripe 付款頁面。
|
||||
5. 付款成功後，我資料庫裡的會員狀態能變成已開通。
|
||||
6. 不要一開始加太多複雜功能，比如優惠券、升級降級、複雜發票。
|
||||
|
||||
輸出要求：
|
||||
1. 先給我一個改動計劃。
|
||||
2. 然後直接修改程式碼。
|
||||
3. 最後告訴我怎麼一步一步本地測試。
|
||||
4. 如果有哪個步驟還需要我去 Stripe 後臺操作，請直接把鏈接和要點告訴我。
|
||||
```
|
||||
|
||||
如果你希望 AI 更貼近你的項目，還可以在開頭補上：
|
||||
|
||||
- 你的前端框架
|
||||
- 你的後端目錄結構
|
||||
- 你的資料庫表名
|
||||
- 你現在的用戶系統是 Supabase Auth 還是自建 Auth
|
||||
|
||||
## 7.1 本地聯調也儘量交給 AI
|
||||
|
||||
如果你希望連本地聯調都讓 AI 幫你串起來，可以直接用下面這段：
|
||||
|
||||
```text
|
||||
請繼續幫我把 Stripe 支付真正跑通，我想一步一步照著做，不想自己猜。
|
||||
|
||||
請參考官方文檔：
|
||||
- https://docs.stripe.com/webhooks
|
||||
- https://docs.stripe.com/stripe-cli
|
||||
- https://docs.stripe.com/stripe-cli/use-cli
|
||||
|
||||
我的目標：
|
||||
1. 告訴我先打開哪些 Stripe 頁面。
|
||||
2. 告訴我如何拿到 STRIPE_WEBHOOK_SECRET。
|
||||
3. 告訴我如何使用 stripe login 和 stripe listen。
|
||||
4. 告訴我怎樣驗證 checkout.session.completed 已經成功打到本地 webhook。
|
||||
5. 如果當前項目需要先啟動前端和後端，也請順帶告訴我具體命令。
|
||||
6. 不要只講原理，請按實際操作步驟輸出。
|
||||
7. 如果我某一步做錯了，也請告訴我最常見的報錯會長什麼樣。
|
||||
```
|
||||
|
||||
## 8. 最容易踩坑的 4 件事
|
||||
|
||||
1. **把 `success` 頁面當成支付成功**
|
||||
真正決定狀態的是 Webhook，不是前端跳轉。
|
||||
2. **讓前端傳金額**
|
||||
這會帶來嚴重的價格篡改風險。
|
||||
3. **Webhook 路由被 `express.json()` 提前處理**
|
||||
Stripe 驗籤需要原始請求體。
|
||||
4. **沒有做冪等處理**
|
||||
Webhook 可能重試，如果你每次都重複加會員或積分，就會出事故。
|
||||
|
||||
## 9. 一句話選型建議
|
||||
|
||||
如果你現在只是想先把收費跑起來：
|
||||
|
||||
| 你的主要用戶 | 最先嚐試的方案 |
|
||||
| :--- | :--- |
|
||||
| 海外 SaaS / 國際用戶 | Stripe |
|
||||
| 中國大陸用戶 | 支付寶 / 微信支付 |
|
||||
| 香港或跨境團隊 | Stripe + 本地錢包 / FPS 聚合方案 |
|
||||
|
||||
後面的具體區別，我統一放到附錄。
|
||||
|
||||
::: info 最簡單的選型思路
|
||||
不要一開始就想"我要把全球支付方式一次全接完"。
|
||||
|
||||
更實際的順序通常是：
|
||||
- 先按主要用戶所在地區選一條主支付鏈路
|
||||
- 先把最小可行支付跑通
|
||||
- 再根據真實用戶來源補第二、第三種支付方式
|
||||
:::
|
||||
|
||||
## 10. 小結
|
||||
|
||||
到這裡，你已經掌握了最基礎但最重要的一條收費鏈路：
|
||||
|
||||
1. 前端發起購買。
|
||||
2. 後端創建 Checkout Session。
|
||||
3. 用戶在 Stripe 頁面支付。
|
||||
4. Stripe 通過 Webhook 通知後端。
|
||||
5. 後端更新資料庫。
|
||||
6. 前端刷新後顯示新的會員或訂單狀態。
|
||||
|
||||
如果你只想快速把支付接進項目，前面的內容已經夠用了。下面的附錄你可以在真正遇到問題時再回來看。
|
||||
|
||||
---
|
||||
|
||||
# 附錄
|
||||
|
||||
## 附錄 A：Stripe 裡最常見的幾個對象
|
||||
|
||||
第一次看 Stripe 文檔，最容易被這些對象名繞暈。你其實只需要先理解下面幾個：
|
||||
|
||||
| 對象 | 作用 | 你可以把它理解成什麼 |
|
||||
| :--- | :--- | :--- |
|
||||
| `Product` | 描述賣的是什麼 | 商品或會員套餐 |
|
||||
| `Price` | 描述賣多少錢、週期怎麼收費 | 月付、年付、買斷 |
|
||||
| `Checkout Session` | Stripe 託管的支付流程 | 付款頁 |
|
||||
| `Subscription` | 週期訂閱關係 | 自動續費會員 |
|
||||
| `Customer` | 付款用戶 | Stripe 中的客戶檔案 |
|
||||
| `Webhook` | 異步通知 | Stripe 告訴你"這筆款怎麼樣了" |
|
||||
|
||||
## 附錄 B：為什麼 `success` 頁面不等於支付成功
|
||||
|
||||
很多人以為"用戶付完錢，跳到了 success 頁面"就算支付成功了。這是最容易踩的坑。
|
||||
|
||||
### 先講一個真實場景
|
||||
|
||||
假設你做了一個會員網站：
|
||||
1. 用戶點擊"購買會員"
|
||||
2. 跳轉到 Stripe 付款頁面
|
||||
3. 用戶輸入信用卡，點擊付款
|
||||
4. 頁面跳轉到你的 `success.html`
|
||||
5. 你在 success 頁面寫程式碼："既然到了這頁，就給用戶開通會員"
|
||||
|
||||
**問題在哪？**
|
||||
|
||||
用戶可能根本沒付錢，或者付到一半關頁面了，也能直接訪問 `success.html`。
|
||||
|
||||
### 兩條完全不同的路徑
|
||||
|
||||
```mermaid
|
||||
flowchart TB
|
||||
pay["用戶在 Stripe 完成支付"]
|
||||
|
||||
subgraph unreliable["❌ 不可靠路徑：只看 success 頁面"]
|
||||
success["瀏覽器跳到 success 頁面"]
|
||||
fake["前端程式碼認為已開通"]
|
||||
risk["風險：關頁 / 斷網 / 偽造 URL / 根本沒付錢"]
|
||||
success --> fake --> risk
|
||||
end
|
||||
|
||||
subgraph reliable["✅ 可靠路徑：以後端 Webhook 為準"]
|
||||
event["Stripe 服務器發送 Webhook"]
|
||||
verify["後端校驗簽名"]
|
||||
active["資料庫正式更新為已付費"]
|
||||
event --> verify --> active
|
||||
end
|
||||
|
||||
pay --> success
|
||||
pay --> event
|
||||
```
|
||||
|
||||
**關鍵區別：**
|
||||
|
||||
| | success 頁面跳轉 | Webhook 通知 |
|
||||
| :--- | :--- | :--- |
|
||||
| 誰發起的 | 用戶的瀏覽器 | Stripe 的服務器 |
|
||||
| 能偽造嗎 | 能，直接訪問 URL 就行 | 不能，有簽名驗證 |
|
||||
| 一定代表付款成功嗎 | 不一定 | 一定 |
|
||||
| 你的系統怎麼知道 | 前端程式碼猜的 | Stripe 正式通知的 |
|
||||
|
||||
### 完整流程應該是怎樣的
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
actor User as 用戶
|
||||
participant Frontend as 你的網頁
|
||||
participant Stripe as Stripe
|
||||
participant Webhook as 你的後端接口
|
||||
participant DB as 資料庫
|
||||
|
||||
User->>Stripe: 在 Stripe 頁面完成付款
|
||||
Note over Stripe: 錢真的到了 Stripe 賬戶
|
||||
|
||||
Stripe-->>Frontend: 瀏覽器跳轉到 success 頁面
|
||||
Note over Frontend: ⚠️ 這步只是跳轉<br/>不代表系統已確認
|
||||
|
||||
Stripe->>Webhook: 發送 Webhook 通知<br/>"checkout.session.completed"
|
||||
Note over Webhook: ✅ 這才是正式通知
|
||||
|
||||
Webhook->>Webhook: 校驗簽名<br/>（確保是 Stripe 發的，不是黑客）
|
||||
|
||||
Webhook->>DB: 更新用戶狀態為"已付費"
|
||||
DB-->>Webhook: 保存成功
|
||||
Webhook-->>Stripe: 返回 200 OK
|
||||
|
||||
Frontend->>DB: 用戶刷新頁面，查詢狀態
|
||||
DB-->>Frontend: 返回"已付費"
|
||||
Note over Frontend: 這時候才顯示會員功能
|
||||
```
|
||||
|
||||
### 每個環節的卡點
|
||||
|
||||
**第 1 步：用戶在 Stripe 付款**
|
||||
|
||||
這是唯一確定"錢真的付了"的時刻：
|
||||
- 用戶輸入信用卡資訊，點擊確認
|
||||
- 銀行從用戶卡里扣款
|
||||
- Stripe 確認收到這筆錢
|
||||
|
||||
**第 2 步：瀏覽器跳轉到 success 頁面（問題最大）**
|
||||
|
||||
這一步完全不可靠，因為：
|
||||
- 用戶可以直接在瀏覽器輸入 `yoursite.com/success`，根本沒付錢也能訪問
|
||||
- 用戶付到一半關頁面了，但之前複製了 success 鏈接，之後直接打開
|
||||
- 網路問題導致跳轉失敗，但錢已經扣了（用戶付了錢卻沒看到成功頁面）
|
||||
- 用戶點返回鍵，又付了一次錢，但兩次都跳轉到同一個 success 頁面
|
||||
|
||||
**第 3 步：Stripe 發送 Webhook**
|
||||
|
||||
這是 Stripe 主動通知你的服務器"這筆款到賬了"：
|
||||
- 只有 Stripe 的服務器能發起這個請求
|
||||
- 請求裡帶有簽名，你的後端可以驗證是不是真的 Stripe 發的
|
||||
- 即使 success 頁面沒打開、用戶斷網了，Webhook 也會發送
|
||||
|
||||
**第 4 步：後端校驗簽名**
|
||||
|
||||
為什麼要校驗？防止黑客偽造通知。
|
||||
|
||||
假設沒有校驗，黑客可以直接給你的服務器發一個假通知："用戶 A 付了 1000 元"。你的系統就會給黑客開通會員。
|
||||
|
||||
校驗的過程：
|
||||
- Stripe 用你們約定的密鑰對通知內容生成簽名
|
||||
- 你的後端用同樣的密鑰驗證簽名是否匹配
|
||||
- 匹配 = 100% 是 Stripe 發的，不匹配 = 直接拒絕
|
||||
|
||||
**第 5 步：更新資料庫**
|
||||
|
||||
只有校驗通過後，才更新資料庫：
|
||||
- 把用戶狀態從"待付款"改成"已付費"
|
||||
- 記錄訂單號、金額、付款時間
|
||||
- 開通對應的會員權限
|
||||
|
||||
**第 6 步：前端查詢狀態**
|
||||
|
||||
success 頁面不要自己判斷"到了這頁就是成功了"。正確的做法：
|
||||
- 頁面加載時，向後端發送請求："這個用戶付費了嗎？"
|
||||
- 後端查資料庫，返回真實狀態
|
||||
- 根據返回結果顯示"開通成功"或"等待確認"
|
||||
|
||||
### 一個常見的錯誤做法
|
||||
|
||||
```javascript
|
||||
// 錯誤：在 success 頁面直接開通
|
||||
// success.html
|
||||
if (window.location.pathname === '/success') {
|
||||
// 危險！任何人都能訪問 /success
|
||||
activateMembership();
|
||||
}
|
||||
```
|
||||
|
||||
```javascript
|
||||
// 正確：每次刷新都查後端
|
||||
// success.html
|
||||
async function checkStatus() {
|
||||
const response = await fetch('/api/user/status');
|
||||
const data = await response.json();
|
||||
|
||||
if (data.paymentStatus === 'paid') {
|
||||
showMemberFeatures();
|
||||
} else {
|
||||
showPendingMessage();
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 總結一句話
|
||||
|
||||
**success 頁面只是"瀏覽器跳轉成功"，Webhook 才是"Stripe 正式確認收款"。**
|
||||
|
||||
你的系統必須以 Webhook 為準，不能相信前端的跳轉。
|
||||
|
||||
## 附錄 C：訂閱系統最值得監聽的事件
|
||||
|
||||
| 事件 | 含義 | 你通常要做什麼 |
|
||||
| :--- | :--- | :--- |
|
||||
| `checkout.session.completed` | 首次開通成功 | 創建本地訂閱記錄 |
|
||||
| `invoice.paid` | 自動續費成功 | 延長有效期 |
|
||||
| `invoice.payment_failed` | 自動扣費失敗 | 標記風險狀態並提醒用戶 |
|
||||
| `customer.subscription.deleted` | 訂閱取消 | 回收權限或標記到期後失效 |
|
||||
|
||||
### 訂閱狀態圖
|
||||
|
||||
```mermaid
|
||||
stateDiagram-v2
|
||||
[*] --> NotStarted: 用戶未購買
|
||||
NotStarted --> Active: checkout.session.completed
|
||||
Active --> Active: invoice.paid
|
||||
Active --> PastDue: invoice.payment_failed
|
||||
PastDue --> Active: 用戶補款成功
|
||||
Active --> Canceled: customer.subscription.deleted
|
||||
PastDue --> Canceled: 到期未恢復
|
||||
Canceled --> [*]
|
||||
|
||||
state "未開通" as NotStarted
|
||||
state "會員有效" as Active
|
||||
state "扣費失敗 / 待恢復" as PastDue
|
||||
state "已取消 / 到期回收" as Canceled
|
||||
```
|
||||
|
||||
### 續費 / 失敗 / 取消時序圖
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
autonumber
|
||||
participant Stripe as Stripe
|
||||
participant Webhook as 你的 Webhook 接口
|
||||
participant DB as 訂閱表 / 訂單表
|
||||
participant App as 你的應用
|
||||
actor User as 用戶
|
||||
|
||||
rect rgb(235, 248, 255)
|
||||
Stripe->>Webhook: invoice.paid
|
||||
Webhook->>DB: 延長 current_period_end
|
||||
DB-->>Webhook: 更新成功
|
||||
Webhook-->>Stripe: 200 OK
|
||||
App-->>User: 繼續保持會員有效
|
||||
end
|
||||
|
||||
rect rgb(255, 247, 237)
|
||||
Stripe->>Webhook: invoice.payment_failed
|
||||
Webhook->>DB: 標記 past_due
|
||||
DB-->>Webhook: 更新成功
|
||||
Webhook-->>Stripe: 200 OK
|
||||
App-->>User: 提醒更新支付方式
|
||||
end
|
||||
|
||||
rect rgb(254, 242, 242)
|
||||
Stripe->>Webhook: customer.subscription.deleted
|
||||
Webhook->>DB: 標記 canceled
|
||||
DB-->>Webhook: 更新成功
|
||||
Webhook-->>Stripe: 200 OK
|
||||
App-->>User: 停止高級權限
|
||||
end
|
||||
```
|
||||
|
||||
## 附錄 D：其他支付方案怎麼選
|
||||
|
||||
### 1. 中國大陸
|
||||
|
||||
主要用戶在大陸的話，首選還是 **[支付寶](https://open.alipay.com/)** 和 **[微信支付](https://pay.wechatpay.cn/)**。
|
||||
|
||||
**業務模式：**
|
||||
|
||||
兩者都是"支付網關"模式。你需要：
|
||||
- 申請商戶資質（營業執照、對公賬戶）
|
||||
- 用戶付的錢直接到你的商戶賬戶
|
||||
- 你自己負責稅務、退款、對賬
|
||||
|
||||
**技術模式：**
|
||||
|
||||
兩者都是"後端下單 + 前端調起 + 後端通知"的模型，跟 Stripe 思路一樣。
|
||||
|
||||
**支付寶接入流程：**
|
||||
1. 在支付寶開放平臺創建應用
|
||||
2. 配置公私鑰和回調地址
|
||||
3. 後端調用統一下單接口，生成支付鏈接或二維碼
|
||||
4. 用戶掃碼或跳轉付款
|
||||
5. 支付寶異步通知你的後端，更新訂單狀態
|
||||
|
||||
**微信支付接入流程：**
|
||||
- JSAPI 支付：適合公眾號、小程序，用戶在微信內直接付款
|
||||
- Native 支付：PC 端生成二維碼，用戶掃碼付款
|
||||
- H5 支付：手機瀏覽器內拉起微信 App 付款
|
||||
|
||||
流程：後端下單 → 拿到 `prepay_id` 或 `code_url` → 前端調起支付 → 後端接收通知確認成功
|
||||
|
||||
**參考鏈接：**
|
||||
- 支付寶開放平臺：https://open.alipay.com/
|
||||
- 微信支付商戶文檔：https://pay.wechatpay.cn/doc/v3/merchant/
|
||||
|
||||
### 2. 香港
|
||||
|
||||
香港市場比較混合，常見組合：
|
||||
|
||||
- 銀行卡：Visa / Mastercard
|
||||
- FPS（轉數快）：香港本地即時轉賬
|
||||
- AlipayHK / WeChat Pay HK：香港版支付寶和微信
|
||||
|
||||
**推薦組合：**
|
||||
- 用 **[Stripe](https://stripe.com/hk)** 覆蓋國際卡和訂閱
|
||||
- 用 **[Airwallex](https://www.airwallex.com/)** 或 **[Adyen](https://www.adyen.com/)** 補本地錢包和 FPS
|
||||
|
||||
### 3. 海外 / 國際 SaaS
|
||||
|
||||
#### [Stripe](https://stripe.com/)
|
||||
|
||||
**業務模式：** 支付網關
|
||||
|
||||
- 你需要自己申請商戶資質（部分國家 Stripe 可以幫你搞定）
|
||||
- 用戶付的錢到你的 Stripe 賬戶，再結算到你的銀行賬戶
|
||||
- 你自己負責稅務申報
|
||||
|
||||
**技術模式：**
|
||||
|
||||
- API 體驗最好，文檔清晰
|
||||
- 支持 Checkout（託管頁面）、Elements（自定義表單）、Payment Links（無程式碼）
|
||||
- Webhook 通知支付狀態
|
||||
- 支持訂閱、發票、多幣種
|
||||
|
||||
**適合誰：** 海外 SaaS、獨立開發者、需要靈活定製的團隊
|
||||
|
||||
**參考鏈接：** https://docs.stripe.com/
|
||||
|
||||
#### [PayPal](https://www.paypal.com/)
|
||||
|
||||
**業務模式：** 支付網關
|
||||
|
||||
- 用戶付的錢到你的 PayPal 賬戶，再提現到銀行
|
||||
- 你自己負責稅務
|
||||
|
||||
**技術模式：**
|
||||
|
||||
- 一次性支付：前端放按鈕，後端創建/確認訂單
|
||||
- 訂閱制：先建 Product 和 Plan，再用 SDK 拉起
|
||||
- 同樣需要後端和 Webhook，不要只看前端回調
|
||||
|
||||
**適合誰：** 需要補充渠道的海外業務，用戶習慣用 PayPal 付款
|
||||
|
||||
**參考鏈接：** https://developer.paypal.com/docs/
|
||||
|
||||
#### [Paddle](https://www.paddle.com/)
|
||||
|
||||
**業務模式：** Merchant of Record (MoR)
|
||||
|
||||
- Paddle 是"記錄商家"，法律上由 Paddle 向用戶收款
|
||||
- Paddle 幫你處理全球稅務、VAT、退款、合規
|
||||
- 用戶付的錢到 Paddle，Paddle 扣除稅費和手續費後結算給你
|
||||
- 你不需要在每個國家註冊公司或處理稅務
|
||||
|
||||
**技術模式：**
|
||||
|
||||
- Paddle.js：前端嵌入托管結賬頁
|
||||
- 後端 API：創建 transaction，交給 checkout 處理
|
||||
- Webhook 同步訂閱狀態
|
||||
|
||||
**適合誰：** 不想處理全球稅務的 SaaS 團隊，尤其是 B2B SaaS
|
||||
|
||||
**參考鏈接：** https://developer.paddle.com/
|
||||
|
||||
#### [Lemon Squeezy](https://www.lemonsqueezy.com/)
|
||||
|
||||
**業務模式：** Merchant of Record (MoR)
|
||||
|
||||
- 和 Paddle 類似，Lemon Squeezy 是"記錄商家"
|
||||
- 幫你處理全球稅務、VAT、合規
|
||||
- 2024 年被 Stripe 收購，但獨立運營
|
||||
|
||||
**技術模式：**
|
||||
|
||||
- Hosted Checkout：最簡單，直接生成付款鏈接
|
||||
- Checkout Overlay：浮層嵌入你的頁面
|
||||
- 後端 API：創建 checkout，靈活控制
|
||||
|
||||
**適合誰：** 獨立開發者、數字產品、軟體授權
|
||||
|
||||
**參考鏈接：** https://docs.lemonsqueezy.com/
|
||||
|
||||
### 4. 企業級方案
|
||||
|
||||
#### [Airwallex（空中雲匯）](https://www.airwallex.com/)
|
||||
|
||||
**業務模式：** 支付網關 + 全球賬戶
|
||||
|
||||
- 提供全球收款賬戶（類似虛擬銀行賬戶）
|
||||
- 支持多幣種收款、換匯、付款
|
||||
- 你自己負責稅務
|
||||
|
||||
**技術模式：**
|
||||
|
||||
- Payment Links：幾乎不用程式碼，生成付款鏈接
|
||||
- Hosted Payment Page：託管頁面
|
||||
- Drop-in / Embedded / Native API：深度接入，自定義程度高
|
||||
- 支持 Alipay HK、FPS、WeChat Pay 等本地支付方式
|
||||
|
||||
**適合誰：** 香港團隊、跨境業務、需要多幣種賬戶的公司
|
||||
|
||||
**參考鏈接：** https://www.airwallex.com/docs/
|
||||
|
||||
#### [Adyen](https://www.adyen.com/)
|
||||
|
||||
**業務模式：** 支付網關
|
||||
|
||||
- 企業級支付平臺，年處理交易額萬億歐元
|
||||
- 支持線上、線下、移動端全渠道
|
||||
- 你自己負責稅務
|
||||
|
||||
**技術模式：**
|
||||
|
||||
- Pay by Link：最簡單，生成付款鏈接
|
||||
- Drop-in / Components：標準線上接入
|
||||
- 後臺可啟用 Alipay、Alipay HK、PayMe 等本地支付方式
|
||||
|
||||
**適合誰：** 大型企業、需要全渠道支付的公司
|
||||
|
||||
**參考鏈接：** https://docs.adyen.com/
|
||||
|
||||
### 5. 方案對比
|
||||
|
||||
| 方案 | 業務模式 | 稅務處理 | 適合誰 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| Stripe | 支付網關 | 自己處理 | 海外 SaaS、開發者 |
|
||||
| PayPal | 支付網關 | 自己處理 | 海外補充渠道 |
|
||||
| Paddle | MoR | Paddle 代處理 | B2B SaaS、不想管稅務 |
|
||||
| Lemon Squeezy | MoR | LS 代處理 | 獨立開發者、數字產品 |
|
||||
| Adyen | 支付網關 | 自己處理 | 大型企業 |
|
||||
| Airwallex | 支付網關 + 賬戶 | 自己處理 | 跨境業務、香港團隊 |
|
||||
| 支付寶/微信 | 支付網關 | 自己處理 | 大陸用戶 |
|
||||
|
||||
### 6. 按地區選方案
|
||||
|
||||
| 你的市場 | 推薦方案 |
|
||||
| :--- | :--- |
|
||||
| 中國大陸 | 支付寶 / 微信支付 |
|
||||
| 香港 | Stripe + Airwallex / Adyen |
|
||||
| 海外 SaaS | Stripe（自己管稅務）或 Paddle（MoR 代管） |
|
||||
| 海外數字產品 | Stripe / Lemon Squeezy / Paddle |
|
||||
| 多地區企業級 | Adyen / Airwallex / Stripe 組合 |
|
||||
@@ -0,0 +1,490 @@
|
||||
# 如何部署 Web 應用
|
||||
|
||||
在本教程中，我們將介紹如何將你的 Web 應用部署到互聯網上，讓其他人可以訪問。我們會介紹三個常用的部署平臺：**騰訊雲 CloudBase**、**Vercel** 和 **Zeabur**，幫助你快速完成從"寫好程式碼"到"讓別人可以在互聯網上訪問你的網站"的完整流程。
|
||||
|
||||
# 什麼是"部署"？
|
||||
|
||||
在開始之前，我們先弄清楚"部署（Deployment）"到底是什麼意思。任何一個網站想要被外部用戶訪問，都必須有一個可以公開訪問的網路地址（這個地址可以是 IP 地址，比如 123.45.67.89，也可以是域名，比如 [google.com](https://google.com/) 等）。但只有地址是不夠的——你寫好的網頁程式碼（例如 HTML、CSS、JavaScript 文件，或者使用 React、Vue 等框架寫的項目），以及相關的圖片 / 影片資源，都必須"放"在一臺 24 小時在線的服務器上，由它來響應網路請求，這樣任何人的瀏覽器才能訪問並下載這些資源。
|
||||
|
||||
|
||||
|
||||
圖片來源：https://www.hostinger.com/tutorials/what-is-cloud-hosting
|
||||
|
||||
把資源上傳、配置好環境並讓服務"跑起來"的整個過程，就被稱為 **部署（Deployment）**。
|
||||
|
||||
簡單來說：你在自己電腦上寫好的網頁，只要在本機啟動程序，就只能通過本地地址在自己的瀏覽器裡訪問，因為這些程式碼只存在於你的硬盤上。"部署"就是把你的程式碼和資源轉移到一臺連接著公網的專業服務器上，並做好配置，讓這臺服務器知道"別人訪問時我要怎麼響應"——比如：當有人在瀏覽器中輸入你的域名時，服務器會立刻找到對應的網頁文件，把內容傳回給對方的設備，從而讓用戶看到你的頁面。
|
||||
|
||||
如果手動部署，一個項目往往需要好幾個步驟，每一步都可能踩坑。常見關鍵步驟包括：
|
||||
|
||||
1. **服務器準備**：你需要先購買雲服務器（比如阿里雲、騰訊雲、或 AWS EC2），選擇服務器所在地區（如上海、新加坡）、配置（CPU、內存、磁盤大小等），還要學會如何遠程連接服務器（例如通過 SSH 工具登錄）。
|
||||
|
||||
2. **環境配置**：Web 應用需要在特定"環境"中才能運行——例如運行 Node.js 項目必須先安裝 Node.js；運行 Python 項目必須安裝 Python 以及對應的第三方庫。如果環境版本不匹配，程序就可能報錯、無法啟動。
|
||||
3. **上傳資源**：你需要把本地的程式碼和資源上傳到服務器上，常用的方法包括 FTP 或 Git。如果項目體積比較大（比如包含影片文件），中途一旦斷線，有時需要重新上傳。
|
||||
|
||||
|
||||
|
||||
4. **啟動服務並測試**：上傳完成後，你還需要在服務器上執行命令啟動應用，並測試"分配的網路地址是否能訪問"。如果訪問不了，有可能是服務器防火牆沒有放行對應端口（比如你的應用監聽 3000 端口，但該端口被防火牆攔截），也可能是程序本身有 Bug，這時就需要查看服務器日誌進行排查。
|
||||
> 💡 可以把端口理解為區分同一臺設備上不同應用的"房間號"，而 IP 則是這臺設備的"門牌號"。IP 和端口合在一起（IP:port），就可以精確定位到某一個網路服務。
|
||||
5. **維護與更新**：後續每次你修改程式碼，都要重新上傳並重啟服務。如果服務器宕機（例如斷電、網路故障），還需要手動重啟應用，有時還要額外配置"進程守護工具"，讓程序在異常退出後自動拉起。
|
||||
|
||||
像 CloudBase、Vercel、Zeabur 這樣的"低程式碼部署平臺"，就是為了解決上述複雜問題而誕生的。它們會幫你自動完成"買服務器、配環境、上傳程式碼、啟動服務、監控運行"等步驟。你只需要把自己的程式碼倉庫（比如 GitHub 或 GitLab）連接到平臺，或者直接上傳程式碼，它就會自動拉取程式碼、識別應用類型、配置對應的運行時環境，最後給你一個可以被任何人訪問的公網地址。它甚至可以一鍵綁定你自己的域名。
|
||||
|
||||
|
||||
|
||||
接下來，我們會分別介紹這三個平臺的特點和使用方法，幫助你選擇最適合自己的部署方案。
|
||||
|
||||
---
|
||||
|
||||
# 部署平臺對比
|
||||
|
||||
| 平臺 | 特點 | 適用場景 | 免費額度 |
|
||||
|------|------|----------|----------|
|
||||
| **騰訊雲 CloudBase** | 國內訪問速度快，與微信生態深度整合 | 國內用戶為主、需要微信小程序支持的項目 | 有免費額度 |
|
||||
| **Vercel** | 前端框架支持好，與 GitHub 集成緊密 | React/Vue/Next.js 等現代前端項目 | 有免費額度 |
|
||||
| **Netlify** | 功能全面，支持表單處理和身份驗證，與 Git 集成好 | 需要表單處理、身份驗證等高級功能的靜態網站 | 有免費額度 |
|
||||
| **Zeabur** | 支持多種語言和服務模板，配置靈活 | 需要部署多種服務（如 Dify、n8n）的複雜項目 | 每月約 5 美元免費額度 |
|
||||
|
||||
---
|
||||
|
||||
# 1. 騰訊雲 CloudBase
|
||||
|
||||
騰訊雲 CloudBase（雲開發）是騰訊雲提供的一站式後端雲服務，特別適合國內開發者使用。它的優勢在於：
|
||||
|
||||
- **國內訪問速度快**：服務器位於國內，訪問延遲低
|
||||
- **微信生態整合**：可以方便地對接微信小程序、公眾號
|
||||
- **一站式解決方案**：提供靜態網站託管、雲函數、資料庫、存儲等全套服務
|
||||
- **免費額度充足**：個人開發者有充足的免費資源額度
|
||||
|
||||
## 使用 CloudBase 部署 Web 應用
|
||||
|
||||
### 步驟 1：註冊並登錄
|
||||
|
||||
訪問 [騰訊雲 CloudBase 控制檯](https://console.cloud.tencent.com/tcb)，使用微信或 QQ 登錄。
|
||||
|
||||
### 步驟 2：創建環境
|
||||
|
||||
點擊"新建環境"，選擇一個環境名稱（如 `my-web-app`）。
|
||||
|
||||
> ⚠️ **注意**：CloudBase 的免費體驗版需要兌換碼才能開通。你需要關注騰訊雲 CloudBase 公眾號，在公眾號中輸入"領取兌換碼"獲取免費體驗版的兌換碼，然後在創建環境時填寫兌換碼即可開通免費環境（免費試用期為 6 個月）。
|
||||
|
||||
### 步驟 3：開通靜態網站託管
|
||||
|
||||
在環境管理頁面，找到"靜態網站託管"功能並開通。開通後你會獲得一個默認的訪問域名。
|
||||
|
||||
CloudBase 的靜態網站託管提供多種部署方式，與 Zeabur 類似：
|
||||
|
||||
- **本地項目上傳**：直接從本地上傳構建好的靜態文件（HTML、CSS、JS 等）
|
||||
- **模板部署**：使用預設模板快速創建項目，如 React Web 應用模板、Vue Web 應用模板
|
||||
- **Git 倉庫部署**：支持從 GitHub 等程式碼倉庫自動拉取程式碼並部署
|
||||
|
||||
### 步驟 4：部署程式碼
|
||||
|
||||
在靜態網站託管頁面，CloudBase 提供三種部署方式：
|
||||
|
||||
**方式一：本地項目部署（本地項目上傳）**
|
||||
- 在控制檯選擇"本地項目部署"
|
||||
- 直接上傳構建好的靜態文件（HTML、CSS、JS 等）
|
||||
- 選擇你本地構建好的項目文件夾（如 `dist` 或 `build` 目錄）
|
||||
- 等待上傳完成即可訪問
|
||||
|
||||
**方式二：模板部署**
|
||||
- 使用預設模板快速創建項目
|
||||
- 支持 React Web 應用模板、Vue Web 應用模板等
|
||||
- 基於模板自動構建並部署
|
||||
|
||||
**方式三：Git 倉庫部署**
|
||||
- **Git 個人倉庫部署**：綁定你的 GitHub 等個人程式碼倉庫
|
||||
- **公開倉庫部署**：支持從公開的 Git 倉庫拉取程式碼
|
||||
- 配置自動構建命令（如 `npm run build`）
|
||||
- 每次推送程式碼會自動重新部署
|
||||
|
||||
> 💡 **提示**：你也可以使用 CLI 工具進行部署：
|
||||
> ```bash
|
||||
> # 安裝 CloudBase CLI
|
||||
> npm install -g @cloudbase/cli
|
||||
> # 登錄
|
||||
> tcb login
|
||||
> # 部署
|
||||
> tcb hosting deploy ./dist -e your-env-id
|
||||
> ```
|
||||
|
||||
### 步驟 5：配置自定義域名（可選）
|
||||
|
||||
在靜態網站託管設置中，可以綁定你自己的域名，並申請免費的 HTTPS 證書。
|
||||
|
||||
---
|
||||
|
||||
# 2. Vercel
|
||||
|
||||
Vercel 是全球最流行的前端部署平臺之一，特別適合部署 React、Vue、Next.js 等現代前端框架項目。它的特點包括：
|
||||
|
||||
- **與 GitHub 深度集成**：推送程式碼即自動部署
|
||||
- **自動預覽**：每個 Pull Request 都會生成獨立的預覽鏈接
|
||||
- **全球 CDN**：網站自動分發到全球節點，訪問速度快
|
||||
- **Serverless 函數**：支持在項目中編寫後端 API
|
||||
|
||||
> ⚠️ **注意**：Vercel 在部分網路環境下訪問可能不太穩定，國內用戶建議優先考慮 CloudBase。
|
||||
|
||||
## 使用 Vercel 部署 Web 應用
|
||||
|
||||
### 步驟 1：註冊賬號
|
||||
|
||||
訪問 [Vercel 官網](https://vercel.com)，使用 GitHub 賬號登錄。
|
||||
|
||||
### 步驟 2：導入項目
|
||||
|
||||
1. 點擊 "Add New Project"
|
||||
2. 選擇你要部署的 GitHub 倉庫
|
||||
3. 如果沒有看到想要的倉庫，點擊 "Adjust GitHub App Permissions" 授權訪問
|
||||
|
||||
### 步驟 3：配置構建設置
|
||||
|
||||
Vercel 會自動識別項目類型並配置構建命令：
|
||||
|
||||
| 框架 | 構建命令 | 輸出目錄 |
|
||||
|------|----------|----------|
|
||||
| React | `npm run build` | `build` |
|
||||
| Vue | `npm run build` | `dist` |
|
||||
| Next.js | `next build` | - |
|
||||
| 純 HTML | - | 項目根目錄 |
|
||||
|
||||
如果自動識別不正確，可以手動修改：
|
||||
- **Build Command**: 構建命令，如 `npm run build`
|
||||
- **Output Directory**: 構建輸出目錄，如 `dist` 或 `build`
|
||||
- **Install Command**: 依賴安裝命令，通常是 `npm install`
|
||||
|
||||
### 步驟 4：部署
|
||||
|
||||
點擊 "Deploy" 按鈕，等待構建完成。構建成功後，你會獲得一個 `xxx.vercel.app` 的域名。
|
||||
|
||||
### 步驟 5：自定義域名（可選）
|
||||
|
||||
在項目設置中的 "Domains" 頁面，可以添加你自己的域名。Vercel 會自動配置 HTTPS。
|
||||
|
||||
---
|
||||
|
||||
# 3. Netlify
|
||||
|
||||
Netlify 是另一個非常流行的前端部署平臺，與 Vercel 類似，特別適合部署靜態網站和單頁應用（SPA）。它的特點包括：
|
||||
|
||||
- **功能全面**：除了靜態網站託管，還支持表單處理、身份驗證、邊緣函數等高級功能
|
||||
- **與 Git 深度集成**：支持 GitHub、GitLab、Bitbucket，推送程式碼自動部署
|
||||
- **分支預覽**：每個分支都會自動生成獨立的預覽鏈接
|
||||
- **全球 CDN**：網站自動分發到全球節點，訪問速度快
|
||||
- **表單處理**：無需後端程式碼即可處理網站表單提交
|
||||
- **身份驗證**：內置用戶身份驗證功能，可快速實現登錄/註冊
|
||||
|
||||
> ⚠️ **注意**：Netlify 的國內訪問速度可能不如 CloudBase，建議主要面向海外用戶的項目使用。
|
||||
|
||||
## 使用 Netlify 部署 Web 應用
|
||||
|
||||
### 步驟 1：註冊賬號
|
||||
|
||||
訪問 [Netlify 官網](https://www.netlify.com)，點擊 "Sign up" 註冊。你可以使用 GitHub、GitLab、Bitbucket 或郵箱註冊。
|
||||
|
||||
### 步驟 2：導入項目
|
||||
|
||||
1. 登錄後點擊 "Add new site" → "Import an existing project"
|
||||
2. 選擇你的程式碼託管平臺（如 GitHub）
|
||||
3. 授權 Netlify 訪問你的倉庫
|
||||
4. 從列表中選擇你要部署的倉庫
|
||||
|
||||
### 步驟 3：配置構建設置
|
||||
|
||||
Netlify 會自動識別常見的前端框架並配置構建設置：
|
||||
|
||||
| 框架 | 構建命令 | 發佈目錄 |
|
||||
|------|----------|----------|
|
||||
| React | `npm run build` | `build` |
|
||||
| Vue | `npm run build` | `dist` |
|
||||
| Angular | `ng build` | `dist/<project-name>` |
|
||||
| Next.js | `next build` | `out` |
|
||||
| 純 HTML | - | `.`（項目根目錄） |
|
||||
|
||||
如果自動識別不正確，可以手動配置：
|
||||
- **Build command**: 構建命令，如 `npm run build`
|
||||
- **Publish directory**: 構建輸出目錄，如 `dist` 或 `build`
|
||||
|
||||
### 步驟 4：部署
|
||||
|
||||
點擊 "Deploy site" 按鈕，等待構建完成。構建成功後，你會獲得一個 `xxx.netlify.app` 的域名，任何人都可以通過這個地址訪問你的網站。
|
||||
|
||||
### 步驟 5：配置自定義域名（可選）
|
||||
|
||||
1. 進入站點設置，點擊 "Domain management"
|
||||
2. 點擊 "Add custom domain"
|
||||
3. 輸入你的域名並按照提示配置 DNS 記錄
|
||||
4. Netlify 會自動申請並配置 HTTPS 證書
|
||||
|
||||
### 特色功能
|
||||
|
||||
#### 1. 表單處理
|
||||
|
||||
Netlify 提供了一個非常方便的功能：無需後端程式碼即可處理表單提交。
|
||||
|
||||
只需在 HTML 表單中添加 `netlify` 屬性：
|
||||
|
||||
```html
|
||||
<form name="contact" netlify>
|
||||
<p>
|
||||
<label>姓名: <input type="text" name="name" /></label>
|
||||
</p>
|
||||
<p>
|
||||
<label>郵箱: <input type="email" name="email" /></label>
|
||||
</p>
|
||||
<p>
|
||||
<label>留言: <textarea name="message"></textarea></label>
|
||||
</p>
|
||||
<p>
|
||||
<button type="submit">發送</button>
|
||||
</p>
|
||||
</form>
|
||||
```
|
||||
|
||||
部署後，表單提交的資料會自動發送到 Netlify 後臺，你可以在 "Forms" 頁面查看所有提交記錄，也可以設置郵件通知或將資料轉發到其他服務。
|
||||
|
||||
#### 2. Netlify Functions（邊緣函數）
|
||||
|
||||
Netlify 支持部署無服務器函數（Serverless Functions），讓你可以在不搭建完整後端服務器的情況下，實現簡單的 API 接口。你可以使用 JavaScript 或 TypeScript 編寫函數，部署後會自動獲得一個可訪問的 URL。
|
||||
|
||||
例如，創建一個 `hello.js` 文件：
|
||||
|
||||
```javascript
|
||||
exports.handler = async (event, context) => {
|
||||
return {
|
||||
statusCode: 200,
|
||||
body: JSON.stringify({ message: "Hello from Netlify!" })
|
||||
};
|
||||
};
|
||||
```
|
||||
|
||||
部署後，你可以通過 `https://你的域名/.netlify/functions/hello` 訪問這個函數。
|
||||
|
||||
#### 3. 本地開發支持
|
||||
|
||||
Netlify 提供了 CLI 工具，方便你在本地開發和測試：
|
||||
|
||||
```bash
|
||||
# 安裝 Netlify CLI
|
||||
npm install -g netlify-cli
|
||||
|
||||
# 登錄賬號
|
||||
netlify login
|
||||
|
||||
# 本地啟動開發服務器
|
||||
netlify dev
|
||||
|
||||
# 本地測試函數
|
||||
netlify functions:serve
|
||||
```
|
||||
|
||||
使用 CLI 工具可以在本地模擬 Netlify 環境，包括表單提交、函數調用等功能，方便在部署前進行測試。
|
||||
|
||||
---
|
||||
|
||||
# 4. Zeabur
|
||||
|
||||
Zeabur 是一個新興的部署平臺，特別適合需要部署多種服務的複雜項目。它的優勢在於：
|
||||
|
||||
- **服務模板豐富**：內置 Dify、n8n、資料庫等多種服務模板
|
||||
- **支持多種部署方式**：GitHub、模板、Docker 鏡像、本地項目等
|
||||
- **靈活的服務組合**：可以在一個項目中部署多個相互關聯的服務
|
||||
- **按量計費**：用多少付多少，適合實驗性項目
|
||||
|
||||
## 使用 Zeabur 部署 Dify
|
||||
|
||||
在之前的課程中，我們已經簡單接觸過 Dify。現在，我們可以通過 [Zeabur](https://zeabur.com/projects) 非常輕鬆地啟動自己的 Dify 服務。首先打開 [控制檯頁面](https://zeabur.com/projects)，我們先看一下上面的各個區域。
|
||||
|
||||
|
||||
|
||||
在這個頁面上，你首先能看到許多方塊，這些就是已經啟動的服務。在頂部菜單中，你會看到 Agent、Servers、Docs、Templates 等幾個選項，它們分別代表：
|
||||
|
||||
1. **Agent**：可以打開 Zeabur 內置的智能助手（Agent），向它提問如何操作，或者查詢當前服務器的狀態。
|
||||
2. **Servers**：在這裡可以添加你自己購買的雲服務器，或者直接通過 Zeabur 購買服務器。
|
||||
3. **Docs**：查看 Zeabur 的完整文檔說明。
|
||||
4. **Templates**：這裡列出了所有內置的模板鏡像。
|
||||
|
||||
> 這裡提到的"鏡像（Image）"，可以理解為"包含程式碼和運行環境的壓縮包"。當某個服務在一臺服務器上成功跑起來之後，我們可以選擇把"這套運行環境 + 程式碼"打包成鏡像。之後，在任何新服務器上，只要把這個壓縮包解壓並運行，就不需要重新配置環境和程式碼，服務就能直接跑起來。
|
||||
|
||||
在頁面右上角，你還能看到自己的餘額。默認情況下，每個月會有 5 美元左右的免費額度。關於細節計費規則暫時可以不用太在意，只需要知道：只要服務器在運行，就會消耗額度。
|
||||
|
||||
|
||||
|
||||
點擊餘額可以查看每日的消耗明細。
|
||||
|
||||
|
||||
|
||||
現在我們來創建自己的 Dify 服務。首先，在 [控制檯首頁](https://zeabur.com/projects) 點擊 "New Project"。
|
||||
|
||||
|
||||
|
||||
接下來是各個創建方式的解釋：
|
||||
|
||||
1. **GitHub**
|
||||
可以連接到你的 GitHub 賬號。綁定之後，就可以直接從 GitHub 倉庫裡選擇項目部署（GitHub 是目前全球最大的程式碼託管平臺）。
|
||||
2. **Template（模板）**
|
||||
可以基於模板來部署服務。Zeabur 內置了很多預設項目模板（例如 Dify、n8n 等），你可以基於這些模板快速創建並部署應用。
|
||||
|
||||
3. **Databases（資料庫）**
|
||||
用於部署資料庫服務，比如 MySQL、MongoDB 等常見資料庫。
|
||||
|
||||
4. **Functions（函數）**
|
||||
可以部署函數服務，你可以編寫 JavaScript 或 Python 程式碼，讓它們以函數的形式被調用。
|
||||
|
||||
|
||||
|
||||
|
||||
5. **Local Project（本地項目）**
|
||||
上傳一個本地文件夾，Zeabur 會自動識別其中的啟動腳本。這適合將你已經在本地開發好的項目快速部署到 Zeabur 上。
|
||||
|
||||
6. **Docker Image**
|
||||
部署已經打包好的 Docker 鏡像。如果你的項目已經被打成了 Docker 鏡像（例如存放在 Docker Hub 或其他鏡像倉庫中），可以在這裡直接部署。
|
||||
|
||||
7. **Cursor**
|
||||
如果你安裝了 Cursor（例如 Cursor IDE），可以通過這個入口將 Cursor 中的項目直接部署到 Zeabur。
|
||||
|
||||
如果你想部署自己的 Dify 服務，推薦選擇 **Template** 方式，然後在搜索框中輸入 "dify"。可以看到很多由不同作者維護的版本，你可以任選其一（比如 v1.6.0 版本）。
|
||||
|
||||
|
||||
|
||||
接著，輸入任意一個名稱，Zeabur 會基於這個名稱生成一個臨時的自定義域名。之後所有人都可以通過這個網址訪問你的服務。
|
||||
|
||||
|
||||
|
||||
創建完成後，你會看到多個程序（服務）依次啟動。需要耐心等待所有服務都進入"已啟動"狀態。（Dify 服務是由多個程序組成的，每個程序負責不同的功能，它們之間會相互協作。）
|
||||
|
||||
一般來說，你只需要點擊左側的 Dify 應用，就可以看到默認的訪問入口地址。但在本例中，由於前面還套了一層 nginx，你需要點擊 nginx 服務來獲取最終訪問地址。可以理解為：nginx 就是負責對外統一"收發請求"的主程序，它會把外部訪問的地址分發給內部各個服務。點擊左側的 Nginx，在詳情頁中可以看到當前的服務地址，然後在瀏覽器裡打開這個地址，等待服務完全啟動。
|
||||
|
||||
|
||||
|
||||
稍等片刻後，你就能看到 Dify 的登錄界面了。輸入郵箱地址和註冊密碼，就可以開始使用你自己的 Dify 服務了。
|
||||
|
||||
|
||||
|
||||
如果你有興趣，還可以順便啟動一個 n8n 服務。n8n 也是海外非常流行的一款 AI 工作流平臺。
|
||||
|
||||
|
||||
|
||||
## 使用 Zeabur 與 Trae 部署貪吃蛇遊戲
|
||||
|
||||
在本教程的下一個部分，我們會體驗 Zeabur 的一些進階用法。我們先用 Trae 生成一個貪吃蛇小遊戲，再把它部署到 Zeabur 的服務器上，並配置一個可公開訪問的鏈接，讓任何人都可以打開你的遊戲。
|
||||
|
||||
第一步，是在本地使用 Trae 創建一個貪吃蛇項目。
|
||||
|
||||
### 使用 HTML 框架實現
|
||||
|
||||
|
||||
|
||||
對於 Trae 來說，生成一個基於 HTML 的貪吃蛇網頁遊戲非常簡單。遊戲生成完成後，你只需要按照前面介紹的 Zeabur 本地部署方式，把包含所有文件的文件夾上傳上去即可。
|
||||
|
||||
|
||||
|
||||
完成後，你就會進入該服務的詳情界面：
|
||||
|
||||
|
||||
|
||||
點擊左側的 "Network" 選項，在頁面中找到 "Public Address" 區域。點擊 "Generate Domain"，即可生成一個對外訪問地址，你可以輸入任意喜歡的名稱。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
生成完成後，只要在瀏覽器中打開這個地址，就可以運行你自己的貪吃蛇遊戲了。其它 HTML 類型的 Web 應用也可以用完全相同的方式來部署。
|
||||
|
||||
|
||||
|
||||
### 使用 React 框架實現
|
||||
|
||||
前面我們學習瞭如何部署基於 HTML 的 Web 應用。接下來，我們再嘗試部署一個目前更常用的前端框架：React 應用。相比純 HTML，React 被認為是一種更加成熟、現代的前端開發框架。它通過組件化的方式組織頁面結構，能夠顯著加快複雜頁面的開發，是企業級項目中非常主流的選擇。
|
||||
|
||||
|
||||
|
||||
#### 重構為 React 架構
|
||||
|
||||
在 Trae 中，你只需要向 Agent 說明："幫我把這份程式碼重構成 React 架構"，就可以比較輕鬆地把原本基於 HTML 的結構重構成 React 項目。
|
||||
|
||||
|
||||
|
||||
不過，相比簡單的 HTML 文件，React 應用依賴更復雜的構建工具和項目結構，因此部署過程也會稍微麻煩一些。一個典型的問題體現在端口設置上：默認情況下，React 應用一般會監聽 3000 端口（你也可以在配置文件或啟動日誌中看到這一點）。
|
||||
|
||||
然而，在 Zeabur 上這樣部署會失敗——因為 Zeabur 只支持監聽 8080 端口的應用。也就是說，如果想讓 React 應用在 Zeabur 上正常運行，我們必須先把默認監聽端口從 3000 改成 8080。
|
||||
|
||||
要正確進行這一步配置，我們需要先弄清楚兩個概念：什麼是"端口（Port）"，以及"監聽端口（Listening Port）"是什麼意思。
|
||||
|
||||
#### 什麼是端口？
|
||||
|
||||
> 在計算機網路中，端口可以理解為一個"邏輯通信端點"，用來區分同一臺設備上運行的不同網路服務。簡單類比的話，如果 IP 地址好比一個"門牌號"（例如 162.128.1.1），那端口號就像這棟樓裡不同房間的"房間號"——每個房間對應一個服務（例如 Web 服務器、郵箱服務，或者你的 React 應用）。
|
||||
>
|
||||
> 端口號用 16 位整型表示，取值範圍是 0 到 65535。
|
||||
|
||||
如果不想記這些細節，可以簡單理解：端口是構成"網路訪問地址"的一個必要部分。
|
||||
|
||||
我們平時訪問網站或 IP 地址時，通常不會手動加端口號，是因為 Web 的默認端口是 80 或 443（HTTPS）。大多數瀏覽器會自動使用這些標準端口。而對於一些特殊端口，比如 React 默認的 3000、Zeabur 要求的 8080，我們就必須在地址後面加上 `:3000` 或 `:8080` 才能訪問到對應的內容。
|
||||
|
||||
#### 什麼是"監聽端口號"？
|
||||
|
||||
> "監聽端口號"指的是某個程序在一臺設備上主動"打開並監控"的端口。當一個應用設置了監聽端口時，其實就是在告訴操作系統："我會一直在這個端口上等待網路請求——只要有請求進來，就請轉發給我。"
|
||||
|
||||
再形象一點地理解：假設你的電腦是一棟寫字樓，IP 地址是這棟樓的地址。樓裡開了很多公司或部門，它們分別佔用不同的房間，房間號就是端口號。
|
||||
|
||||
當默認的 React 開發服務器啟動時，它會"打開"某個房間的門，並安排"前臺"在門口值班，這個房間號就是它的監聽端口——3000。
|
||||
|
||||
同時，React 程序還會告訴這棟樓的"物業管理"（操作系統）："我在 3000 號房間，請把所有寄給 3000 的信件（網路請求）都轉給我。"
|
||||
|
||||
這樣，當你訪問 React 網站時，請求首先會到達這棟樓；物業看到請求要送到 3000 號房間，就會立刻把請求交給 React 的"前臺"，由它來處理並返回結果——這就是訪問 React 應用的過程。
|
||||
|
||||
當你在本地執行 `npm start`（本地啟動 React 開發服務器的默認命令，也可以在 Vibe Coding 的 Agent 側邊欄中執行）時，React 開發服務器就會自動把監聽端口設置為 3000。
|
||||
而 Zeabur 的平臺設計決定了它只會"識別"監聽 8080 端口的應用。如果你的 React 應用仍然使用默認的 3000 端口，Zeabur 就無法將請求正確轉發給你的應用，最終導致部署失敗。
|
||||
|
||||
#### 修改默認監聽端口
|
||||
|
||||
要把 React 默認監聽端口（3000）改成 Zeabur 所要求的 8080，有很多做法。最簡單的方式，就是直接在 Trae 裡對 Agent 下指令："請幫我把這個 React 項目的默認端口改為 8080。"Trae 就會幫你修改項目中對應的配置文件。修改完成後，你只需重新打包並按前面的方式上傳到 Zeabur 即可。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
在網路設置中指定一個訪問 URL，方式和部署 HTML 項目時基本相同，就可以啟動 React 版本的服務。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
對於其它需要修改端口號的程序，你也可以採用同樣的思路：先改默認端口，再上傳到 Zeabur 部署。至此，你已經掌握了將常見 Web 應用部署到服務器的基礎技能。
|
||||
|
||||
你可以嘗試讓 Trae 幫你構建不同類型的應用，並把它們部署到 Zeabur 的默認服務器上。在後續課程中，我們還會學習如何把應用部署到你自己購買的雲服務器上。
|
||||
|
||||
---
|
||||
|
||||
# ⚠️ 如何停止和刪除項目（Zeabur）
|
||||
|
||||
由於啟用服務器相關資源都會產生費用，我們在使用時一定要養成"及時關閉不用服務"的習慣，避免把每個月的免費額度消耗完。
|
||||
|
||||
如果要找到項目的管理入口，首先點擊項目中的 "Settings" 選項。
|
||||
|
||||
|
||||
|
||||
進入設置頁面後，將頁面拉到最下方，你會看到類似下面的界面：
|
||||
|
||||
|
||||
|
||||
你可以點擊 "Suspend All Services" 來暫停所有服務以降低費用；如果服務出現問題，可以點擊 "Restart All Services" 對全部服務進行重啟。如果你確定不再需要這個項目，可以點擊 "Delete Project" 將整個項目徹底刪除。
|
||||
|
||||
---
|
||||
|
||||
# 總結
|
||||
|
||||
在本教程中，我們介紹了四個常用的 Web 應用部署平臺：
|
||||
|
||||
1. **騰訊雲 CloudBase**：適合國內用戶，訪問速度快，與微信生態整合好
|
||||
2. **Vercel**：適合現代前端框架項目，與 GitHub 集成緊密，全球 CDN 加速
|
||||
3. **Netlify**：功能全面，支持表單處理和身份驗證，適合需要高級功能的靜態網站
|
||||
4. **Zeabur**：適合複雜項目，服務模板豐富，支持多種部署方式
|
||||
|
||||
選擇哪個平臺取決於你的具體需求：
|
||||
- 如果主要面向國內用戶，推薦 **CloudBase**
|
||||
- 如果使用 React/Next.js 等框架，推薦 **Vercel** 或 **Netlify**
|
||||
- 如果需要表單處理、身份驗證等高級功能，推薦 **Netlify**
|
||||
- 如果需要部署 Dify、n8n 等服務，推薦 **Zeabur**
|
||||
|
||||
無論選擇哪個平臺，部署的核心流程都是相似的：準備程式碼 → 選擇平臺 → 配置構建設置 → 部署上線。掌握這些技能後，你就可以將自己開發的應用分享給全世界了！
|
||||
@@ -0,0 +1,361 @@
|
||||
# 從設計原型到項目程式碼
|
||||
|
||||
::: tip 🎯 核心問題
|
||||
**如何將設計工具中的原型轉化為真正能在瀏覽器裡運行的前端程式碼？**
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 1. 從原型到程式碼的三種路徑
|
||||
|
||||
在使用 Figma、MasterGo 等現代前端設計工具完成界面設計後，一個很實際的問題自然會浮現：這些看起來結構完整的設計稿，要怎麼轉化成真正能在瀏覽器裡運行的前端程式碼？
|
||||
|
||||
一般而言，從原型到程式碼的落地，本質上有三種典型路徑：
|
||||
|
||||
| 路徑 | 方法 | 特點 | 適用場景 |
|
||||
|------|------|------|----------|
|
||||
| **路徑一** | 根據圖片，使用多模態大模型直接還原出程式碼 | 靈活、無需特定工具 | 快速原型驗證、簡單頁面 |
|
||||
| **路徑二** | 通過平臺自身能力或插件導出可用程式碼 | 還原度高、可編輯性強 | Figma/MasterGo 用戶 |
|
||||
| **路徑三** | 平臺結合 MCP 能力導出可用程式碼 | 自動化程度高、可定製 | 需要深度集成的工作流 |
|
||||
|
||||
本文將詳細介紹這三種路徑的具體實現方法，幫助你根據項目需求選擇最合適的工作流。
|
||||
|
||||
::: tip 📚 前置知識
|
||||
在開始本節之前，建議你先學習 [Figma 與 MasterGo 入門](../figma-mastergo/) 教程，掌握前端設計工具的基礎操作。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 2. 路徑一：多模態 AI 直接還原程式碼
|
||||
|
||||
擁有視覺能力的大模型天生具備將圖片轉為程式碼的能力。我們只需要將設計稿截圖直接導入對話框，隨後讓大模型生成完整的結果程式碼。
|
||||
|
||||
### 2.1 操作流程
|
||||
|
||||
1. **截取設計稿圖片**
|
||||
- 在 Figma 或 MasterGo 中，將設計好的頁面導出為 PNG 或 JPG
|
||||
- 確保截圖包含完整的頁面佈局
|
||||
|
||||
2. **選擇多模態 AI 模型**
|
||||
- 可以使用 Gemini、Qwen、Claude 等支持圖像輸入的模型
|
||||
- 這裡以 Gemini 為例進行演示
|
||||
|
||||
3. **編寫提示詞**
|
||||
```
|
||||
請根據這張設計圖生成對應的 HTML/CSS 程式碼。
|
||||
要求：
|
||||
- 使用現代 CSS 佈局（Flexbox/Grid）
|
||||
- 響應式設計，適配不同屏幕尺寸
|
||||
- 包含所有可見的 UI 元素
|
||||
- 顏色、字體大小盡量還原設計稿
|
||||
```
|
||||
|
||||
|
||||
|
||||
4. **獲取並保存程式碼**
|
||||
- 要求模型返回完整的 HTML 程式碼
|
||||
- 保存為單個 `.html` 文件，方便本地測試
|
||||
- 後續可以在本地 IDE 中將其轉換為 React 等框架
|
||||
|
||||
### 2.2 常見問題與解決方案
|
||||
|
||||
生成頁面並非簡單的任務，在具體過程中你可能會遇到很多問題：
|
||||
|
||||
| 問題 | 解決方案 |
|
||||
|------|----------|
|
||||
| 界面排布不均 | 向 AI 描述具體的佈局問題，要求調整 CSS 的 margin/padding |
|
||||
| 界面顯示不全 | 檢查是否設置了正確的 viewport，要求添加響應式斷點 |
|
||||
| 顏色還原不準 | 使用取色工具獲取設計稿的精確色值，提供給 AI |
|
||||
| 字體不匹配 | 指定具體的字體名稱或要求使用 Google Fonts 替代 |
|
||||
|
||||
::: tip 💡 小技巧
|
||||
推薦先生成 HTML 程式碼，獲取後再使用本地 IDE 將其轉換為 React 框架。這樣可以獲得多個獨立的 HTML 文件，統一進行框架轉換。
|
||||
:::
|
||||
|
||||
### 2.3 MasterGo AI 生成頁面
|
||||
|
||||
MasterGo 同樣提供了強大的 AI 頁面生成功能，可以根據參考圖直接生成可用的網頁程式碼。
|
||||
|
||||
#### 找到 AI 功能入口
|
||||
|
||||
在 MasterGo 編輯界面的上方工具欄中，可以找到 AI 工具按鈕：
|
||||
|
||||
|
||||
|
||||
#### 生成流程
|
||||
|
||||
1. **上傳參考圖**
|
||||
- 使用與多模態 AI 相同的方式上傳設計參考圖
|
||||
- 添加文字描述需求
|
||||
|
||||
2. **查看生成結果**
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
3. **獲取程式碼**
|
||||
- 點擊藍色按鈕"插入到畫布"，可直接編輯生成後的網頁
|
||||
- 或點擊右側的"程式碼"按鈕，複製程式碼內容到本地
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 3. 路徑二：平臺自身能力或插件導出程式碼
|
||||
|
||||
### 3.1 Figma Make 生成程式碼
|
||||
|
||||
Figma Make 是 Figma 官方推出的 AI 設計工具，能夠根據用戶輸入的提示詞或者參考圖，高精度地還原網頁原型 UI 界面。
|
||||
|
||||
#### 功能特點
|
||||
|
||||
- **高精度還原**：相比原生 AI 生成程式碼，效果更佳
|
||||
- **可編輯性**：生成結果可以轉換為可編輯的 Figma Design 文件
|
||||
- **GitHub 集成**：支持直接將程式碼同步到 GitHub
|
||||
|
||||
::: tip 🔑 權限說明
|
||||
使用 Figma Make 的完整功能需要 Pro 用戶權限，學生可以通過教育認證免費獲得 Pro 權限。
|
||||
:::
|
||||
|
||||
#### 操作步驟
|
||||
|
||||
1. **進入 Figma Make**
|
||||
- 在 Figma 首頁點擊 Make 按鈕
|
||||
- 或者訪問 [Figma Make](https://www.figma.com/make)
|
||||
|
||||
2. **上傳參考圖**
|
||||
- 將你想要還原的設計圖上傳到對話框
|
||||
- 添加描述需求的提示詞
|
||||
|
||||
|
||||
|
||||
3. **查看生成結果**
|
||||
- 稍等片刻後即可看到渲染結果
|
||||
- 點擊右上角的播放按鈕可進行全屏預覽
|
||||
|
||||
|
||||
|
||||
4. **細節調整**
|
||||
- 點擊右上角的編輯器圖標（鼠標和尺子圖標）
|
||||
- 回到熟悉的 Figma Editor 界面進行詳細調整
|
||||
|
||||
|
||||
|
||||
5. **導出程式碼**
|
||||
- 調整滿意後，選擇導出程式碼
|
||||
- 可以直接連接到 GitHub 保存程式碼
|
||||
|
||||
|
||||
|
||||
### 3.2 插件導出程式碼
|
||||
|
||||
除了平臺原生的 AI 功能，Figma 和 MasterGo 都支持通過插件導出程式碼：
|
||||
|
||||
**常用 Figma 插件：**
|
||||
- **Figma to Code**：將設計稿轉換為 React、Vue、HTML 等程式碼
|
||||
- **Anima**：高保真程式碼生成，支持交互效果
|
||||
- **Locofy**：AI 驅動的設計轉程式碼工具
|
||||
|
||||
**使用步驟：**
|
||||
1. 在 Figma 中打開插件面板（Plugins）
|
||||
2. 搜索並安裝需要的程式碼導出插件
|
||||
3. 選中要導出的設計元素
|
||||
4. 運行插件，選擇目標框架和程式碼格式
|
||||
5. 複製或下載生成的程式碼
|
||||
|
||||
---
|
||||
|
||||
## 4. 路徑三：平臺結合 MCP 能力導出程式碼
|
||||
|
||||
### 4.1 什麼是 MCP？
|
||||
|
||||
MCP（Model Context Protocol，模型上下文協議）是一套開放標準協議，它允許 AI 模型安全、可控地訪問外部工具和資料源。在前端設計工具的場景中，MCP 讓大模型能夠直接讀取設計文件的結構、樣式和組件資訊，從而更精準地生成程式碼。
|
||||
|
||||
### 4.2 MCP 的工作原理
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ AI 模型 │ ←→ │ MCP 服務器 │ ←→ │ 設計工具 │
|
||||
│ (Claude等) │ │ (協議適配) │ │(Figma/MasterGo)│
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
```
|
||||
|
||||
**工作流程：**
|
||||
1. AI 模型通過 MCP 協議向設計工具發送請求
|
||||
2. 設計工具返回結構化的設計資料（圖層、樣式、組件等）
|
||||
3. AI 模型理解設計結構並生成對應程式碼
|
||||
4. 程式碼可以直接導出或同步到開發環境
|
||||
|
||||
### 4.3 Figma + MCP 實戰
|
||||
|
||||
#### 環境準備
|
||||
|
||||
1. **安裝 MCP 服務器**
|
||||
```bash
|
||||
# 使用 npx 安裝 Figma MCP 服務器
|
||||
npx figma-mcp-server
|
||||
```
|
||||
|
||||
2. **配置 Claude Desktop 或其他支持 MCP 的 AI 工具**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"figma": {
|
||||
"command": "npx",
|
||||
"args": ["figma-mcp-server"],
|
||||
"env": {
|
||||
"FIGMA_ACCESS_TOKEN": "your-figma-token"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **獲取 Figma Access Token**
|
||||
- 登錄 Figma → Settings → Personal Access Tokens
|
||||
- 生成新的 Token 並保存
|
||||
|
||||
#### 使用流程
|
||||
|
||||
1. **在 AI 工具中啟用 MCP 連接**
|
||||
- 打開 Claude Code 或其他支持 MCP 的 IDE
|
||||
- 確認 MCP 服務器已連接
|
||||
|
||||
2. **提供設計文件鏈接**
|
||||
```
|
||||
用戶：請幫我將這個 Figma 設計轉換為 React 程式碼
|
||||
鏈接：https://www.figma.com/file/xxxxx
|
||||
|
||||
AI：我已通過 MCP 連接到 Figma，正在讀取設計文件結構...
|
||||
```
|
||||
|
||||
3. **AI 自動分析並生成程式碼**
|
||||
- MCP 服務器獲取設計文件的圖層樹
|
||||
- AI 理解組件結構和樣式屬性
|
||||
- 生成帶有正確命名和結構的 React/Vue 組件
|
||||
|
||||
4. **迭代優化**
|
||||
```
|
||||
用戶：請將按鈕組件提取為獨立的可複用組件
|
||||
|
||||
AI：好的，我已通過 MCP 識別到設計系統中的 Button 組件，
|
||||
正在生成帶有 props 接口的 React 組件...
|
||||
```
|
||||
|
||||
### 4.4 MCP 的優勢
|
||||
|
||||
| 特性 | 傳統方式 | MCP 方式 |
|
||||
|------|----------|----------|
|
||||
| **資料精度** | 依賴截圖，可能丟失細節 | 直接讀取原始設計資料 |
|
||||
| **組件識別** | AI 需要猜測組件邊界 | 精確獲取組件定義 |
|
||||
| **樣式還原** | 基於像素估算 | 獲取精確的設計 token |
|
||||
| **迭代效率** | 每次修改需重新截圖 | 實時同步設計變更 |
|
||||
| **自動化程度** | 手動複製粘貼 | 可直接寫入項目文件 |
|
||||
|
||||
### 4.5 當前可用的 MCP 工具
|
||||
|
||||
**設計工具 MCP：**
|
||||
- **Figma MCP Server**：官方支持的 MCP 實現
|
||||
- **MasterGo MCP**：社區開發的 MasterGo 適配器
|
||||
|
||||
**開發環境 MCP：**
|
||||
- **Claude Code**：原生支持 MCP 協議
|
||||
- **Cline**：VS Code 插件，支持 MCP 連接
|
||||
- **Trae**：可通過配置啟用 MCP 功能
|
||||
|
||||
::: tip 🔮 未來展望
|
||||
MCP 協議正在快速發展，未來設計工具與開發環境的集成將更加緊密。預計會出現更多一鍵同步設計到程式碼的解決方案，進一步縮短設計與開發之間的距離。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 5. 程式碼導出後的工作
|
||||
|
||||
### 5.1 本地測試
|
||||
|
||||
獲取程式碼後，在本地 IDE 中打開並進行測試：
|
||||
|
||||
1. **創建新項目**
|
||||
```bash
|
||||
# 如果是 HTML 文件，直接用瀏覽器打開
|
||||
open index.html
|
||||
|
||||
# 如果是 React/Vue 項目
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
2. **與 AI IDE 協作**
|
||||
- 將生成的程式碼導入 Trae 或其他 AI IDE
|
||||
- 讓 AI 幫助修復佈局問題、添加交互功能
|
||||
|
||||
### 5.2 常見問題處理
|
||||
|
||||
| 階段 | 問題 | 解決方案 |
|
||||
|------|------|----------|
|
||||
| 佈局 | 元素錯位 | 檢查 CSS 的 display 和 position 屬性 |
|
||||
| 樣式 | 顏色不一致 | 使用瀏覽器開發者工具檢查實際應用的色值 |
|
||||
| 響應式 | 移動端顯示異常 | 添加 media query 斷點 |
|
||||
| 交互 | 按鈕無響應 | 檢查 JavaScript 事件綁定 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 三種路徑對比與選擇建議
|
||||
|
||||
### 6.1 路徑對比
|
||||
|
||||
| 維度 | 路徑一：多模態 AI | 路徑二：平臺能力 | 路徑三：MCP |
|
||||
|------|------------------|------------------|-------------|
|
||||
| **上手難度** | ⭐ 簡單 | ⭐⭐ 中等 | ⭐⭐⭐ 較複雜 |
|
||||
| **還原精度** | ⭐⭐⭐ 中等 | ⭐⭐⭐⭐ 高 | ⭐⭐⭐⭐⭐ 最高 |
|
||||
| **靈活性** | ⭐⭐⭐⭐⭐ 高 | ⭐⭐⭐ 中等 | ⭐⭐⭐⭐ 較高 |
|
||||
| **自動化程度** | ⭐⭐ 低 | ⭐⭐⭐ 中等 | ⭐⭐⭐⭐⭐ 高 |
|
||||
| **成本** | 低（按 API 調用） | 中（可能需要 Pro） | 低（開源工具） |
|
||||
|
||||
### 6.2 選擇建議
|
||||
|
||||
**選擇路徑一（多模態 AI）如果：**
|
||||
- 需要快速驗證想法
|
||||
- 設計工具不固定，經常切換
|
||||
- 對還原精度要求不高
|
||||
- 預算有限
|
||||
|
||||
**選擇路徑二（平臺能力）如果：**
|
||||
- 團隊主要使用 Figma 或 MasterGo
|
||||
- 需要高精度的程式碼還原
|
||||
- 設計師和開發者需要頻繁協作
|
||||
- 願意投資 Pro 版本
|
||||
|
||||
**選擇路徑三（MCP）如果：**
|
||||
- 追求最高程度的自動化
|
||||
- 有技術能力配置 MCP 環境
|
||||
- 項目需要頻繁迭代設計到程式碼
|
||||
- 希望建立標準化的設計開發工作流
|
||||
|
||||
---
|
||||
|
||||
## 7. 總結
|
||||
|
||||
通過本章節的學習，你已經掌握了從設計原型到程式碼的三種核心路徑：
|
||||
|
||||
1. **多模態 AI 直接轉換**：靈活快速，適合原型驗證
|
||||
2. **平臺原生能力**：還原度高，適合專業設計工作流
|
||||
3. **MCP 協議集成**：自動化程度最高，代表未來趨勢
|
||||
|
||||
::: tip 💡 最佳實踐
|
||||
- **新手推薦**：從路徑一（多模態 AI）開始，快速上手
|
||||
- **團隊協作**：使用路徑二（平臺能力），保證設計一致性
|
||||
- **效率優先**：嘗試路徑三（MCP），建立自動化工作流
|
||||
- **混合使用**：根據項目階段靈活切換不同路徑
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 參考資源
|
||||
|
||||
- [Figma 與 MasterGo 入門](../figma-mastergo/) - 學習設計工具基礎
|
||||
- [一起做霍格沃茨畫像](../hogwarts-portraits/) - 完整項目實戰
|
||||
- [MCP 官方文檔](https://modelcontextprotocol.io/) - 瞭解協議詳情
|
||||
- [Figma Make 官方文檔](https://help.figma.com/hc/en-us/sections/360007453634-Figma-Make)
|
||||
- [MasterGo AI 教程](https://mastergo.com/tutorials)
|
||||
@@ -0,0 +1,303 @@
|
||||
# Figma 與 MasterGo 入門
|
||||
|
||||
<script setup>
|
||||
import { relatedArticlesMap } from '@theme/data/relatedArticles'
|
||||
|
||||
const relatedArticles = relatedArticlesMap['zh-tw/stage-2/frontend/figma-mastergo'] ?? []
|
||||
</script>
|
||||
|
||||
::: tip 🎯 核心問題
|
||||
**如何從零開始使用現代設計工具創建網頁原型？**
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 1. 為什麼要學前端設計工具？
|
||||
|
||||
在開始之前，我們需要理解一個問題：為什麼需要學"前端設計工具"？反正直接寫 HTML / CSS 程式碼也能把頁面搭出來，多學一個軟體和技術，真的有必要嗎？
|
||||
|
||||
實際上，把頁面運行起來，和把產品設計好根本是兩個概念。程式碼只關注解決如何渲染在瀏覽器上，如何在不同設備上運行的問題；前端設計工具解決的是資訊分佈的問題，前端交互怎麼安排，不同頁面怎麼跳轉，視覺優先級怎麼分配的問題。只需要在設計工具裡搭一塊畫布，就能把版式、資訊層級、交互方式在一塊屏幕上對比確定，選擇最適當的呈現效果。
|
||||
|
||||
如果直接開始寫程式碼或直接用 AI 生成完整的前端頁面，通常用戶體驗都不會太好，嚴謹的產品會考慮到用戶和前端交互的舒適度，以及不同頁面想要傳達的內容分佈，從用戶的角度出發先進行前端頁面排布，再進行程式碼轉換或生成。
|
||||
|
||||
另外，從團隊協作的角度而言，前端設計工具還降低了多方的合作成本：設計師、產品、開發不再各自對著腦補畫面或者抽象的程式碼說明，而是支持多人協同，大家能夠圍繞一份可視、可標註、可迭代的畫布討論版本管理、需求變更、反饋意見。更進一步的是，現代前端設計工具本身不再只是畫圖軟體，一鍵生成部分程式碼，管理設計系統和組件庫，新時代的設計工具已能夠將大量重複性的體力勞動（對齊、標註、導出、改樣式）自動化或批量化，極大促進了頁面設計的開發效率。
|
||||
|
||||
|
||||
|
||||
### 1.1 前端設計工具的演變
|
||||
|
||||
在時間的長河中，所謂前端設計工具其實是一條持續演化的技術。從 90 年代以本地位圖編輯為主的 Photoshop 時代，到 2010 年前後 Sketch 帶來的矢量化、組件化工作流，再到 2016 年之後 Figma 把協作徹底搬上雲端，設計團隊從單兵作戰逐漸走向多人實時協同。來到 2025 年，AI 已經實打實地嵌入到這些工具內部：從"根據一句話生成頁面草稿"，到"把設計稿直接轉成可運行的前端結構"，"設計即程式碼""人機共創"正在從概念變成可用的生產力。
|
||||
|
||||
本節中，我們會選取最具代表的兩種現代前端設計工具進行介紹，Figma 和 MasterGo。一方面，它們都覆蓋了現代 UI/UX 所需要的核心能力（矢量編輯、組件系統、自動佈局、程式碼交付等），可以支撐你完成從線框到高保真到開發交接的完整閉環；另一方面，這兩款工具都已經在 2025 年之後陸續加入了實用的 AI 功能，幫助你在保證原型不變的同時將設計圖變成真正可運行的程序。
|
||||
|
||||
## 1.2 誕生之旅
|
||||
|
||||
|
||||
|
||||
在現代前端專用工具尚未誕生的年代，整個界面設計行業的視覺設計工作，很長一段時間都由 Photoshop 這類 "全能型" 設計軟體順帶承包。設計師會在本地通過一層層疊加的圖層，細緻完成頁面整體視覺效果的設計，最終將體積不小的 .psd 源文件交付給前端工程師 —— 而前端要精準還原設計圖，還必須手動完成三項繁瑣且關鍵的工作：
|
||||
|
||||
一是 "切圖"：需要從 .psd 文件的多層結構裡，把按鈕、圖標、Logo、背景模塊等獨立視覺元素逐一拆分提取，再導出為 PNG、JPG 等網頁能直接加載的圖片格式（畢竟網頁無法直接識別 PSD 的圖層資訊，只能依賴這些拆分後的圖片呈現細節）；
|
||||
|
||||
|
||||
|
||||
二是 "量尺寸"：得用軟體自帶的測量工具，逐一確認每個元素的寬高、不同模塊間的間距（margin/padding）等資料，確保所有尺寸都精準到像素；
|
||||
|
||||
|
||||
|
||||
三是 "摳標註"：要從設計圖中提取那些 "看不見卻必須有的" 隱性參數 —— 比如文字的字號、字重、行距，每個色塊的 RGB 或 HEX 色值等，相當於把設計師沒寫在紙上的 "設計規格" 手動 "摳" 出來記錄。
|
||||
|
||||
|
||||
|
||||
在此之後，前端的實現階段才真正展開。無論使用的是原生 HTML/CSS/JS，還是基於 Vue、React 等框架，本質過程是一致的。前端會以 "容器為核心載體"，根據設計中各模塊的層級與語義重建頁面結構。這裡的容器是指具有明確佈局邊界、專門承載和組織子元素的單元，它不直接呈現具體內容，卻通過 Flex、Grid 等規則，為內部元素劃定排列範圍。而 "結構塊"（如頂部導航欄、側邊欄、文章列表區、底部頁腳等肉眼可辨的功能 / 內容區域），便依託容器存在；每個結構塊內部，又會嵌套更小的容器來組織元素，比如一條文章列表項，會由 "列表項容器" 控制內邊距與整體排版，再包裹標題、摘要、時間、封面圖標等細節元素。
|
||||
|
||||
|
||||
|
||||
在現代前端框架裡，這些 "結構塊（及關聯的容器與元素）" 通常會被實現為 "組件"。組件可簡單理解為：帶有清晰邊界、整合了容器佈局與邏輯的可複用界面單元，它既包含控制外觀與排列的容器（比如 "按鈕組件" 用容器定義寬高、圓角，"文章卡片組件" 用容器組織標題、封面的位置），也封裝了交互邏輯。設計稿中重複出現、形態一致的部分（如統一風格的按鈕、反覆使用的文章卡片），在程式碼中會被抽象成組件：既能在不同頁面 / 場景複用，減少重複開發，也能通過組件內容器的統一規則，確保所有複用處的佈局與風格高度一致
|
||||
|
||||
隨後，前端會使用樣式系統還原視覺和佈局。切圖階段導出的 PNG/JPG 等資源，會作為組件或結構塊內部的 `<img>`、背景圖片，或者按照各框架推薦的靜態資源方式引入；量尺寸階段得到的寬高、間距、行高等具體數值，會被轉寫為 `width`、`height`、`margin`、`padding`、`line-height` 等樣式屬性，應用到對應的組件或結構塊上；摳標註階段整理出的顏色、字體、陰影、圓角以及 hover/active 等狀態，則會落實到 CSS、CSS Modules、CSS-in-JS、Tailwind 等具體方案中的 `color`、`font-family`、`font-size`、`box-shadow`、`border-radius` 以及偽類或狀態類名上。此時，切圖、尺寸和標註提供的是一組精確的視覺參數，組件和結構塊則提供了承載這些參數的程式碼組織單元，兩者結合起來，構成可維護、可複用的界面實現。
|
||||
|
||||
|
||||
|
||||
但是，以本地文件為中心的模式天然是低效率的。版本通過郵件和網盤傳輸，新舊稿件容易混淆，設計和開發之間大量依賴上述的複雜交互方法，協作成本和出錯概率都不低。
|
||||
|
||||
移動互聯網興起後界面複雜度和迭代速度需求快速上升，Photoshop 的"大而全"逐漸顯得笨重。這個階段，出現了 Sketch。Sketch 專注在 UI 設計本身，剝離掉大部分與視覺後期處理相關的負擔；用 Symbols 把按鈕、導航、輸入框等高複用元素組件化，一處修改可以全局同步；再配合 Zeplin 一類工具，把標註和樣式片段自動生成。Sketch 把"組件思維"引入了設計工作流。不過它依然是基於本地文件的桌面應用，實時協作要靠雲盤、第三方插件或版本工具繞行實現，沒有從底層解決"多個人同時改同一份稿子"的問題。
|
||||
|
||||
|
||||
|
||||
真正改變遊戲規則的是 Figma。自 2016 年起，它把 UI 設計、原型製作、評論協作統一整合到瀏覽器中，支持多種現代功能：多人實時光標、在線評論、版本時間線、分享鏈接等，今天看起來非常簡單，但在當時是對 Photoshop / Sketch 模式的正面挑戰。
|
||||
|
||||
|
||||
|
||||
至此，界面設計不再是散落在各自電腦裡的文件，而是集中在一份在線、實時更新的雲端畫布上。圍繞這塊畫布，我們可以想象更進一步，用自動化或 AI 的方式模糊設計和前端程式碼的邊界。
|
||||
|
||||
最開始，我們僅能依賴各類平臺插件，將設計稿中的組件、樣式資訊半自動導出為程式碼片段（如 React/Vue 組件骨架、CSS 變量等），其核心本質是通過插件實現結構化資訊提取。隨後，隨著平臺能力的進化，大部分設計平臺開始支持大模型 MCP（Model Context Protocol，模型上下文協議）功能：該協議提供了一套標準機制，能讓大模型安全、可控地訪問設計文件、插件接口與項目元資料，進而更便捷地將設計稿導出為程式碼。
|
||||
|
||||
再往後，在插件與 MCP 的基礎上，前端程式碼自動化進一步邁入到原生支持從設計稿直接推導程式碼結構的階段。我們可在設計工具內一鍵生成前端項目骨架、組件層次、樣式體系及對應的程式碼結果。這使得設計師與前端開發工程師得以從手動搬運設計細節的工作中解放出來，將更多精力投入到用戶體驗優化與功能版本的更新迭代上。
|
||||
|
||||
---
|
||||
|
||||
## 2. Figma 入門
|
||||
|
||||
接下來我們從抽象的概念部分來到實際的操作環節。由於時間關係，我們只會學習 Figma 的基本操作邏輯，確保即便你完全沒用過設計工具，也能跟著完成練習。如果你想進行完整的 Figma 功能學習，請你參考 Figma 提供的詳細官方教程進行學習：https://help.figma.com/hc/en-us/sections/30880632542743-Figma-Design-for-beginners
|
||||
|
||||
或者參考如下教程，進行類似個人作品集簡單網頁的快速搭建：https://help.figma.com/hc/en-us/sections/35895585621655-Figma-Sites-collectio
|
||||
|
||||
|
||||
|
||||
左側是項目的新建和資源管理入口，右上角的幾個按鈕是 Figma 的常見功能。其中，Make 用來用一句話讓 AI 幫你先生成一個大概的界面或結構草稿，Design 是真正畫網頁 / App 界面、搭組件和做原型的主工作區，FigJam 像團隊白板，用來貼便利貼、畫流程和做前期討論，Buzz 是品牌資產規模化生產工具，用於批量生成內容以保持品牌一致性，Site 則是把這些設計整理成真正可訪問的網頁或文檔站對外展示。
|
||||
|
||||
乍一看 Figma 的功能非常多，不好入門，但其實這類功能工具本質上都是熟能生巧，不需要害怕一開始操作出錯，也不用想著一步做對，只需要先玩起來，玩多了自然能快速上手。
|
||||
|
||||
本篇教程中，為了快速入門，我們會對 Design 功能做簡單講解。
|
||||
|
||||
### 2.1 新建 Design 文件
|
||||
|
||||
在首頁或者右上角的入口裡，選擇 **Design** ，新建一個文件，你會進入一個空白的設計畫布。
|
||||
這個界面大致分成三塊：左邊是頁面和圖層，用來查看和修改頁面、元素從屬關係；中間是畫布，用於查看當前效果；右邊是屬性和樣式，用於修改具體的形狀、顏色、樣式；底部一條是工具欄，用來切換工具，包含選框、畫形狀、輸入文字、評論、插件等，選中工具後，可以按 Esc 鍵返回至默認鼠標工具。
|
||||
|
||||
|
||||
|
||||
### 2.2 創建你的第一個 Frame（畫板）
|
||||
|
||||
在正式放置元素之前，需要先為頁面確定一個清晰的邊界，這個邊界由 Frame 來承擔。你可以在底部工具欄中選擇 Frame 工具，或者直接按鍵盤 F，然後在畫布上拖出一個矩形區域。
|
||||
|
||||
1. 使用底部工具欄裡的 Frame 工具，或者直接按鍵盤 `F`。
|
||||
2. 在畫布中拖出一個矩形區域，右側屬性欄裡把寬度改成比如 `1440`，高度改成 `900`。
|
||||
3. 在左側圖層欄，把這個 Frame 重命名，比如叫 `My First Page` 或者你項目的名字。
|
||||
|
||||
這個 Frame 就是一屏界面的頁面容器，之後的標題、文字、按鈕、圖片等內容都應該放在這個 Frame 內部，而不是散落在畫布的任意位置。以 Frame 為邊界來組織內容，有助於在後續進行滾動設置、適配不同設備尺寸、導出畫面及製作原型時，保持結構可控。
|
||||
|
||||
|
||||
|
||||
### 2.3 在 Frame 裡放文字和簡單元素
|
||||
|
||||
有了容器，接下來我們來學習如何放置最基本的組件，例如：標題、副標題、按鈕、佔位圖塊。
|
||||
|
||||
1. 選擇文字工具（底部工具欄中的 `T`），在 Frame 裡點擊一下，輸入頁面標題，比如：`My Portfolio`。
|
||||
在右側屬性裡，把字體大小調大一點（例如 96），字重調粗一點。
|
||||
2. 在標題下面，再用文字工具輸入一行簡單說明，比如一兩句描述這個頁面要做什麼。
|
||||
字號可以小一些，行高略放大一點，讀起來不那麼擠。
|
||||
3. 畫一個按鈕雛形：
|
||||
用矩形工具在標題下面畫一個大概 `200 × 48` 的矩形，右側給它一個比較明顯的填充顏色，再適當加一點圓角。
|
||||
|
||||
4. 然後用文字工具在矩形上方輸入按鈕文字，比如 `Get Started`，把矩形和文字一併選中，用頂部的對齊工具讓文字水平、垂直都居中。
|
||||
5. 在按鈕一側或下方，再畫一個較大的淺灰色矩形作為"圖片佔位區"，後面可以用來放展示圖片。
|
||||
|
||||
做到這裡，其實你已經有了一個非常簡陋但結構完整的"首頁草稿"：一個標題、一段話、一個按鈕、一個主要展示區域。
|
||||
|
||||
|
||||
|
||||
### 2.4 善用 Auto Layout 整合元素
|
||||
|
||||
如果所有元素只是隨手拖拽，頁面很快會亂。Figma 裡一個很重要的概念就是 **Auto Layout** ，它可以把一組元素變成一個帶規則的容器。
|
||||
|
||||
|
||||
|
||||
你可以選中"主標題 + 副標題 + 按鈕"這三樣，在右側屬性欄裡點擊 **Add Auto layout** 。
|
||||
|
||||
這時這三樣會被包在一個容器裡，你可以在右側調整參數，其中的元素佈局會根據參數自動適應調整：
|
||||
|
||||
- 它們是豎著排還是橫著排。
|
||||
- 元素之間的間距是多少。
|
||||
- 整個這一塊離容器邊緣有多少內邊距（padding）。
|
||||
|
||||
|
||||
|
||||
同樣，按鈕內部也可以用 Auto Layout，我們能夠實現這樣的一個效果：當我調整了文字，按鈕的長度也會自動調整。
|
||||
|
||||
先把按鈕背景的矩形和按鈕文字選中，添加 Auto Layout，讓這兩個東西變成一個"按鈕容器"。接著選中這個按鈕容器，把寬高都設置成 **Hug contents** 。這樣一來，文字會一直保持在按鈕正中間，文字多一點、少一點，按鈕的寬度都會自動跟著變化。
|
||||
|
||||
|
||||
|
||||
### 2.5 將按鈕變為可複用組件
|
||||
|
||||
現在我們要學習一個新的概念，組件。組件的意思就是可以被反覆利用的元素，比如按鈕這種元素，只要你預感之後還會反覆用到，就可以考慮把它做成組件。我們在剛才已經加好 Auto Layout 的按鈕基礎操作：
|
||||
|
||||
1. 選中整個按鈕容器。
|
||||
2. 右鍵選擇 Create component（創建組件）。
|
||||
|
||||
|
||||
這樣，這個按鈕就從一組普通圖層，變成了一個組件母版。之後如果你在其他頁面或 Frame 裡需要同樣風格的按鈕，可以直接從左側的 Assets 面板裡拖出來使用。
|
||||
|
||||
|
||||
|
||||
此時所有用到的按鈕，都是這個母版的同步拷貝。當你修改母版的顏色、圓角或間距時，所有實例都會自動保持同步更新。
|
||||
|
||||
|
||||
|
||||
至此，你已經初步掌握了 Figma 的簡單用法。你不需要一開始就把所有功能都弄懂，只要先照著做出第一個簡單頁面，熟悉這幾個核心操作，再慢慢去探索官方教程裡的更多能力，隨著使用次數增多就一定能上手。
|
||||
|
||||
---
|
||||
|
||||
## 3. MasterGo 入門
|
||||
|
||||
在理解了 Figma 的基礎工作流程之後，我們再來看 MasterGo，你可以把 MasterGo 簡單看做是中國版的 Figma，但在部分功能上有一定區別。整體上，它延續了與 Figma 相似的界面佈局和操作理念：同樣有畫布、圖層樹和屬性面板，同樣支持組件、樣式、自動佈局和多人協作。更詳細的內容可參考 MasterGO 的官方教程：https://mastergo.com/tutorials/12?%E5%85%A8%E7%A8%8B%E9%AB%98%E8%83%BD%EF%BC%8CMasterGo%20%E6%9C%80%E5%AE%8C%E6%95%B4%E5%AE%9E%E7%94%A8%E6%95%99%E7%A8%8B%EF%BC%8C%E8%AE%A9%E4%BD%A0%E4%BB%8E%E9%9B%B6%E5%88%B0%E7%B2%BE%E9%80%9A%EF%BC%81
|
||||
|
||||
### 3.1 新建設計文件
|
||||
|
||||
1. **進入 MasterGo 後臺**
|
||||
1. 打開 MasterGo 官網並登錄賬號。
|
||||
2. 進入後，你會看到類似「文件列表 / 項目列表」的首頁區域，用來管理你的設計文件。
|
||||
|
||||
|
||||
2. **創建新文件**
|
||||
1. 在右上角看到 + 設計文件的按鈕選項進行點擊，或者選擇導入 Figma 等文件。
|
||||
2. 點擊後，你會進入一個空白畫布，這就是 MasterGo 的設計工作區。
|
||||
|
||||
3. **認識基本界面區塊**
|
||||
當你學會使用 Figma 後，MasterGo 的使用方式大同小異，主要分為幾個區域：
|
||||
|
||||
|
||||
1. 頂部工具欄：位於畫布最上方，左側是文件位置和文件名，中間是一排常用工具按鈕（選擇、區域/畫板、形狀、文本、註釋、評論、插件選擇和 AI 工具等），右側是當前在線成員、分享入口以及畫布縮放和預覽控制功能入口。
|
||||
2. 左側面板：主要分為圖層和資源，當前停留在圖層標籤，可看到頁面列表，以及該頁面下所有圖層的結構和層級。
|
||||
3. 中間畫布區：具體繪製和排版的工作區，所有 Frame、組件和圖形都會展示在這裡。
|
||||
4. 右側屬性面板：用於查看和編輯選中對象的屬性，例如大小、位置、對齊方式、背景填充、描邊、圓角等。如果沒有選中任何對象，會顯示畫布相關設置，如畫布背景色、標籤和導出選項。
|
||||
|
||||
### 3.2 創建你的第一個 Frame
|
||||
|
||||
在正式放東西之前，我們需要一個頁面容器用來確定界面的邊界和尺寸。這個容器在 MasterGo 裡，通常叫 Frame。
|
||||
|
||||
**步驟：**
|
||||
|
||||
1. **選擇 Frame 工具**
|
||||
1. 在工具欄中找到 Frame / 畫板工具，點擊後可使用預設參數直接將內容創建到畫板。
|
||||
2. 或者使用快捷鍵（通常是 `F`，如果有差異以實際界面為準）。
|
||||
2. **在畫布中拖出一個矩形區域**
|
||||
1. 拖出後，你會看到一個帶選中框的區域。
|
||||
2. 右側屬性面板裡，可以看到這個 Frame 的寬度和高度。
|
||||
3. 把寬度改成比如 `1440`，高度改成 `900`（一屏網頁常用尺寸之一）。
|
||||
3. **重命名 Frame**
|
||||
1. 在左側圖層面板裡找到這個 Frame。
|
||||
2. 雙擊名稱，把它改成你項目的名字，比如：`My First Page`，或者你自己隨便起的頁面名。
|
||||
|
||||
|
||||
|
||||
### 3.3 創建畫板內容
|
||||
|
||||
有了容器，使用與 Figma 中我們已教過的類似方式，很容易可以得到相似的展示頁面。（你可以嘗試複製 Figma 畫板中的文字元素，能夠支持文本組件的直接粘貼導入）
|
||||
|
||||
|
||||
|
||||
值得注意的是 Auto Layout 功能行為稍微的不一致性，在 MasterGo 中，如果你想實現和 Figma 相似的按鈕長度隨著文字的長度變化，你需要先在對應矩形元素的基礎上創建一個容器或組件，如圖所示：
|
||||
|
||||
|
||||
|
||||
成功創建容器後，將按鈕矩形和文字放到對應並列的容器中，再在右側找到 Auto Layout 的按鈕啟用自動功能，即可成功實現按鈕寬度能夠隨著文字長度變化的功能。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
### 3.4 AI 生成頁面
|
||||
|
||||
|
||||
|
||||
在 MasterGo 中，一個值得注意的有趣功能是 AI 生成頁面。你可以用一句話或攜帶參考圖，生成對應的 MasterGo 可編輯版組件，並得到可直接使用的程式碼。你可以使用中文或者英文直接輸入需求，頁面會根據需求返回結構清晰的頁面排布文檔，效果如下：
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
設計文檔生成結束後，點擊開始生成，稍作等待便能獲取對應的實際網頁效果：
|
||||
|
||||
|
||||
|
||||
此時你有兩種操作選擇：一是點擊藍色按鈕將生成結果直接插入畫布，二是點擊程式碼預覽功能，直接獲取當前完整頁面的程式碼，具體操作界面如下：
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
將結果插入畫布後，你還能對網頁的整體佈局、元素細節（如字體、顏色、間距等）進行更精細的調整，直至最終效果完全符合你的預期。
|
||||
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 4. 下一步：從原型到程式碼
|
||||
|
||||
在前面的內容中，我們已經學習了 Figma 和 MasterGo 的基礎操作，能夠創建出結構完整的界面原型。接下來的關鍵步驟是：**如何將這些設計稿轉化為真正能在瀏覽器裡運行的前端程式碼？**
|
||||
|
||||
::: tip 📚 後續教程
|
||||
詳細的方法介紹請參考 [從設計原型到項目程式碼](../design-to-code/)，你將學習到：
|
||||
|
||||
- **多模態 AI 直接轉換**：將設計稿截圖發給 AI，直接生成 HTML/React 程式碼
|
||||
- **Figma Make**：使用 Figma 官方 AI 工具高精度還原設計並導出程式碼
|
||||
- **MasterGo AI**：一鍵生成可編輯頁面並獲取程式碼
|
||||
|
||||
這些方法各有優劣，適用於不同的場景，建議根據項目需求選擇合適的工作流。
|
||||
:::
|
||||
|
||||
---
|
||||
|
||||
## 5. 總結
|
||||
|
||||
通過本章節的學習，你已經掌握了：
|
||||
|
||||
1. **前端設計工具的價值**：理解了為什麼需要設計工具，以及它們如何解決資訊分佈、團隊協作的問題。
|
||||
|
||||
2. **Figma 基礎操作**：
|
||||
- 創建 Design 文件和 Frame 畫板
|
||||
- 添加文字、形狀等基礎元素
|
||||
- 使用 Auto Layout 實現自適應佈局
|
||||
- 創建可複用的組件系統
|
||||
|
||||
3. **MasterGo 基礎操作**：
|
||||
- 熟悉與 Figma 相似的界面佈局
|
||||
- 創建 Frame 和基礎畫板內容
|
||||
- 使用 AI 生成頁面功能快速創建原型
|
||||
|
||||
::: tip 💡 下一步
|
||||
現在你已經掌握了前端設計工具的基礎使用方法，可以嘗試：
|
||||
- 為自己設計一個個人作品集頁面
|
||||
- 為接下來的項目設計界面原型
|
||||
- 學習 [從設計原型到項目程式碼](../design-to-code/)，將設計稿轉化為可運行的程式碼
|
||||
|
||||
如果你在完成 [一起做霍格沃茨畫像](../hogwarts-portraits/) 項目，可以先設計界面原型，再導出程式碼與 AI 對話功能結合。
|
||||
:::
|
||||
|
||||
<RelatedArticlesSection
|
||||
title="相關文章"
|
||||
description="建議繼續學習 UI 設計深化與設計轉程式碼實戰。"
|
||||
:items="relatedArticles"
|
||||
/>
|
||||
@@ -0,0 +1,343 @@
|
||||
# Project 4: 一起做霍格沃茨畫像
|
||||
|
||||
在之前的課程中，我們已經學會如何基於 prompt engineering 和 API 調用從而實現更復雜的 AI 交互。我們已能夠將簡單的 AI 聊天機器人升級為 AI Agent 和 AI workflow ；通過更復雜的條件判斷與分支邏輯，我們得以開發出具備更強實用性的功能。
|
||||
|
||||
為了讓這些複雜的 AI 邏輯能更好地運行在不同的程序和實際應用場景中，我們從最簡單的 z.ai 在線環境，逐步過渡到更現代的本地 AI IDE，把原本在瀏覽器裡的程式設計環境搬到了你的電腦上。隨之而來，你開始真正面對各種環境安裝與配置問題，但在與 Trae Agent 的對話過程中，這些看似困難的挑戰也變得可以解決。
|
||||
|
||||
在該項目中，我們將在應用的實用性上更進一步，不僅優化 AI 功能本身，還將開始打磨產品的"外在"。你將嘗試讓自己的界面更加美觀易用，並根據實際需求，親自定製程序界面的佈局與風格。
|
||||
|
||||
正式開始之前，先用幾道小測驗幫你快速回顧上一節課的內容：
|
||||
|
||||
1. 什麼是 Dify？它是做什麼的？為什麼我們需要它？
|
||||
2. 如何調用 Dify 的 API ？
|
||||
3. 什麼是 RAG？如何使用 Dify 構建一個 RAG Agent 或 RAG 工作流？Dify 常見節點的使用方式
|
||||
4. 什麼是 AI IDE？什麼是 Trae？它和 z.ai 有什麼區別？
|
||||
|
||||
如果對以上任何一個問題還有疑惑，可以先回顧上一節課的文檔，或者直接在微信群裡提問交流。
|
||||
|
||||
本節課的項目主題是 **Hogwarts Portraits** 。顧名思義，它的靈感來自霍格沃茨魔法學校裡那些會"活過來"的畫像。我們希望用 AI 打造一組"能互動"的魔法畫像體驗——和畫像對話就像在和"本人"對話一樣，既保留對話的記憶，又具備角色的背景與歷史。通過這個項目，你將把之前學到的智能體與工作流真正融入到一個具體的產品界面中。
|
||||
|
||||
|
||||
|
||||
為了真正打造出 Hogwarts Portraits，我們需要親手搭建出符合魔法畫像的前端界面。為此，你將開始接觸現代前端設計工具，學習如何把界面設計和程式碼結合起來，把紙上或畫布上的界面草圖，變成真正可以操作的網頁。
|
||||
|
||||
你還需要會學會如何把這個網頁從本地環境發佈到互聯網上，讓你親手打造的特色網頁，不僅能在自己電腦上運行，也能被全世界的用戶訪問和體驗。
|
||||
|
||||
本節課的參考項目地址為：[Project4-Hogwarts-Portraits](https://github.com/THU-SIGS-AIID/Project4-Hogwarts-Portraits)
|
||||
|
||||
# 你將學到
|
||||
|
||||
1. 瞭解什麼是前端設計工具、它們解決什麼問題，以及目前常見的前端設計工具有哪些。
|
||||
2. 認識 Figma 和 MasterGo，掌握它們的基礎操作，並學會使用前端程式碼導出插件。
|
||||
3. 利用 Figma AI 和 MasterGo AI 生成網頁設計，並導出可用的頁面程式碼。
|
||||
4. 理解什麼是 GitHub，學會配置 SSH 連接、創建程式碼倉庫並完成程式碼推送。
|
||||
5. 弄清"部署"這一概念，學習如何使用 Zeabur，將程式碼從 GitHub 或本地環境部署到互聯網上。
|
||||
|
||||
屬於自己的 Hogwarts Portraits，一個用於展示 **某位明星、歷史人物或動畫人物** 的網頁界面。
|
||||
|
||||
# 1. Hogwarts Portraits
|
||||
|
||||
我們到底想做一個什麼樣的"魔法畫像"？簡單來說，我們希望儘可能還原《哈利·波特》中的場景，畫像不再只是掛在牆上的一張靜態圖片，而是一個可以和你對話、會根據談話內容改變表情和"心情"的擬人化角色。
|
||||
|
||||
|
||||
|
||||
要讓這個畫像看起來不像聊天 AI 機器人，而更接近一位"真實存在的人"，需要解決兩個問題：一是記憶與知識：畫像需掌握與角色相關的大量背景資料（人物設定、經歷故事、相關文章等），這個部分可以通過知識庫來實現，將你為角色準備的文本素材接入包含知識庫的 Dify ，即可讓畫像具備一定的背景知識講解能力。
|
||||
|
||||
其二是表達風格的問題。僅有知識還不夠，我們還希望它在說話方式上儘可能貼近"本人"，包括語氣、用詞習慣、思考方式，甚至偶爾的脾氣和幽默感。這一層需要通過提示詞工程進行處理：在系統提示詞中，我們需要明確角色的身份設定、世界觀邊界和語言風格，讓每一次回答都圍繞既定人設展開，而不是退回到通用 AI 的中性話術。
|
||||
|
||||
除了對話功能外，我們還希望讓情緒能夠真正被看見。為此我們可以構建一個情緒值指標，我們可以設定 Dify 的輸出內容，讓模型在生成回答文本的同時，額外輸出一個"心情值"或情緒標籤。當前端拿到情緒的指標後，就可以根據心情值或者標籤渲染對應的畫像圖片。當心情值高，畫像看起來很開心，當心情值低落時或者生氣時，畫像看起來很傷心或者憤怒。通過這種方式，用戶看到的不再是一張永遠不變的圖，而是一個會隨內容起伏不斷"變化表情"真正的"魔法畫像"。
|
||||
|
||||
|
||||
|
||||
此外，對於這個畫像的內容，它可以是現實中的明星、歷史人物，也可以是動漫 IP，甚至是你從零構建的原創角色。頁面本身不需要複雜，但幾個核心元素不可或缺：清晰的角色名字，一段高度濃縮的人物簡介，一張足以代表該角色的核心畫像或海報，以及一個"和 TA 對話"的互動區域；你可以把在 Dify / Trae 中配置好的 AI Agent 或 workflow 接入到這個對話模塊中，實現畫像的角色扮演功能。
|
||||
|
||||
## 1.2 收集角色資訊
|
||||
|
||||
以 Elon musk 為例，我們需要收集他的公開發言用於模仿說話方式，注入提示詞。這些素材可以來自於演講、訪談、社交媒體發言，你只需要把這些內容變成文字，在對話期間作為 few shot 的參考，讓大模型用與 Elon musk 同樣隨意、自嘲的方式進行回覆即可，例如：
|
||||
|
||||
```
|
||||
You must fully embody Elon Musk: take "disruptive innovator" and "advocate for human multi-planetary survival" as your core identities, speak directly and concisely, frequently use terms like "first principles", "iteration" and "cost curve", and prefer analogies to explain complex technologies; when thinking, you tend to connect cross-domain logics (e.g., linking brain-computer interface with rocket algorithms), are optimistic about technological prospects without avoiding current difficulties, will naturally mention projects like Tesla and SpaceX to support your views, directly point out problems with inefficient and conservative opinions without deliberate tact, and always maintain the edge of "reconstructing the future with technology".
|
||||
|
||||
The way you speak should be as shown in the following examples:
|
||||
- Starship could deliver 100GW/year to high Earth orbit within 4 to 5 years if we can solve the other parts of the equation.
|
||||
100TW/year is possible from a lunar base producing solar-powered AI satellites locally and accelerating them to escape velocity with a mass driver.
|
||||
- The most likely outcome is that AI and robots make everyone wealthy. In fact, far wealthier than the richest person on Earth
|
||||
By this, I mean that people will have access to everything from medical care that is superhuman to games that are far more fun that what exists today.
|
||||
We do need to make sure that AI cares deeply about truth and beauty for this to be the probable future.
|
||||
- It's taken 13.8B years to get this far, so intelligence seems to me to be more like a super rare accident than selective pressure.
|
||||
Earth is ~4.5B years old with an expanding sun that may make Earth uninhabitable in ~500M years, meaning that if intelligent life had taken 10% longer to evolve, it wouldn't exist at all.
|
||||
- LLM is an outdated term. "Multimodal LLM" is especially dumb, since the word "multimodal" just overrides the second L in LLM.
|
||||
It's just a model, which is a big file of numbers. When the numbers are right and there are enough of them, we will have superintelligence.
|
||||
```
|
||||
|
||||
對於如何收集背景知識並將其作為知識庫，我們可以搜索他的個人介紹，以及公司的介紹複製全部文本作為知識庫的內容加入 Dify，如果你忘記了 Dify 的使用方法，請返回上節課的講義，重新學習如何將知識添加知識庫。
|
||||
|
||||
此外，考慮到畫像設計，使用對應人物公開的圖片也許並非那麼吸引人，並且可能存在一定風險。此時建議你可以使用圖像生成工具的圖生圖功能，讓 AI 返回高清高質量的畫像，你也可以使用圖像生成工具生成一系列表情的畫像素材，用於在之後的情緒值改變後修改對應的畫像呈現。
|
||||
|
||||
本教程中使用的是 [Lovart](https://www.lovart.ai/home)，Lovart 是一款AI設計智能體，它能通過自然語言指令，自動規劃和執行從概念到交付的端到端設計工作流，生成海報、品牌Logo、影片、音樂等內容，並支持分層編輯（實際上內部的功能原理是調用對應的 Seedream 或 google nanobanana 模型，我們已經在之前的課程中提到過）。通過 Lovart ，我們能夠獲得一系列的表情素材，你可以提前獲得你喜愛角色的圖片資訊，將其保存待後續使用。
|
||||
|
||||
|
||||
|
||||
一切準備就緒後，我們能夠開始著手於整體頁面的設計，我們希望這個頁面的風格與該人物是高度綁定的。
|
||||
|
||||
## 1.3 頁面原型設計
|
||||
|
||||
我們還可以先構思一下頁面的原型，如上述所說，我們希望有一個對話頁面和畫像，以及一個有趣的個人介紹，在本篇例子中，我們實現了一個類似 X 上的對話界面替代個人介紹，你也可以想到其他符合"該人物特點"的方式，選取新的元素替換個人介紹欄目。
|
||||
|
||||
|
||||
|
||||
最簡單的，我們可以用 PowerPoint 設計最初的網頁呈現原型，我們從網上找到一張魔法畫像的圖片，並且將畫面設定為橫向排布，最左側設定為聊天區域，中間是畫像區域，最右側是 X 的區域。
|
||||
|
||||
|
||||
|
||||
基於上述簡單原型，我們能夠讓大模型生成真正的前端頁面設計以及對應的程式碼結果。
|
||||
|
||||
|
||||
|
||||
不過，一般而言在實際中我們並不會用 PowerPoint 進行前端頁面的設計。我們會用更好的原型工具，又或者說是前端設計工具來實現這一點。
|
||||
|
||||
---
|
||||
|
||||
# 2. 使用 Figma 和 MasterGo 設計界面
|
||||
|
||||
::: tip 📚 前置知識
|
||||
在開始本節之前，建議你先學習 [Figma 與 MasterGo 入門](../figma-mastergo/) 教程，掌握前端設計工具的基礎操作，包括：
|
||||
- 創建 Design 文件和 Frame 畫板
|
||||
- 使用 Auto Layout 實現自適應佈局
|
||||
- 從設計稿導出程式碼的方法
|
||||
:::
|
||||
|
||||
本節假設你已經掌握了 Figma 或 MasterGo 的基礎操作，我們將重點講解如何將這些工具應用到 Hogwarts Portraits 項目中。
|
||||
|
||||
## 2.1 設計魔法畫像界面
|
||||
|
||||
基於 1.3 節中的原型構思，我們需要在 Figma 或 MasterGo 中創建一個三欄佈局的界面：
|
||||
|
||||
1. **左側**：聊天對話區域
|
||||
2. **中間**：魔法畫像展示區域（會根據情緒變化）
|
||||
3. **右側**：角色社交平臺展示區域（如 X 時間線）
|
||||
|
||||
你可以使用 Figma 的 AI 功能（Figma Make）或 MasterGo 的 AI 生成頁面功能，輸入類似以下的提示詞：
|
||||
|
||||
```
|
||||
Create a Hogwarts-style magical portrait interface with three sections:
|
||||
- Left: A chat interface with dark theme, message bubbles, and input field
|
||||
- Center: A large portrait frame with ornate borders for displaying character images
|
||||
- Right: A social media feed showing character's posts
|
||||
Use dark purple and gold color scheme, magical aesthetic, Harry Potter inspired
|
||||
```
|
||||
|
||||
## 2.2 導出程式碼並在本地運行
|
||||
|
||||
設計完成後，你可以通過以下方式將設計稿轉化為可運行的程式碼：
|
||||
|
||||
**方式一：使用 Figma Make**
|
||||
1. 在 Figma 中點擊 Make 按鈕
|
||||
2. 上傳你的設計參考圖
|
||||
3. 添加提示詞描述需求
|
||||
4. 生成後點擊編輯器圖標進行微調
|
||||
5. 導出程式碼到本地或同步到 GitHub
|
||||
|
||||
**方式二：使用 MasterGo AI**
|
||||
1. 在 MasterGo 編輯界面上方找到 AI 工具
|
||||
2. 選擇"生成頁面"功能
|
||||
3. 上傳參考圖並描述需求
|
||||
4. 生成後點擊"程式碼預覽"獲取程式碼
|
||||
|
||||
**方式三：使用多模態 AI**
|
||||
1. 將設計稿截圖保存
|
||||
2. 使用 Gemini、Qwen 等模型進行圖生程式碼
|
||||
3. 要求生成 HTML 或 React 程式碼
|
||||
4. 在本地 IDE 中運行並調試
|
||||
|
||||
## 2.3 準備情緒變化素材
|
||||
|
||||
為了讓魔法畫像"活"起來，你需要準備一組表情圖片。建議至少包含以下情緒：
|
||||
|
||||
| 情緒值 | 表情 | 說明 |
|
||||
|--------|------|------|
|
||||
| 0 | 悲傷 | 角色感到傷心或失落 |
|
||||
| 1 | 憤怒 | 角色感到生氣或不滿 |
|
||||
| 5 | 平靜 | 默認狀態，情緒穩定 |
|
||||
| 10 | 開心 | 角色感到高興或興奮 |
|
||||
|
||||
你可以使用 Lovart 或其他 AI 圖像生成工具，基於同一角色生成不同表情的變體，確保風格一致。
|
||||
|
||||
---
|
||||
|
||||
# 3. 運行 Hogwarts Portraits
|
||||
|
||||
## 3.1 導出測試程式碼
|
||||
|
||||
通過在從原型到程式碼中的實踐，相信你已經得到 Html 或者 React 格式的原型程式碼，我們只需要將其複製到本地，在 IDE 中說明"請你幫我運行這個程式碼並且支持裡面的必要的功能"，即可運行初版測試；但值得注意的是，這一步往往會出現不少報錯，你需要保持耐心，將所有基礎交互與功能調通。
|
||||
|
||||
|
||||
|
||||
值得注意的是，由於我們的密鑰都需要放在環境變量，而不是寫入程式碼中。我們需要特別強調之後的 DIfy API 相關的內容都需要放入環境變量。我們能夠在之後公網部署的環節中，在部署工具網站中顯式指定對應的私有環境變量；又或者是我們可以讓大模型在網頁中創建一個設置按鈕，我們可以在設置按鈕中傳入對應的私密環境變量，當前變量只能在當前頁面中保存，別人無法獲取。
|
||||
|
||||
|
||||
|
||||
## 3.2 Dify 工作流設計與 API 對接
|
||||
|
||||
在上面的部分中，我們僅完成了前端界面的可視化呈現，尚未打通核心的擬人化角色對話交互流程。這一步是讓原型從靜態展示轉變為魔法畫像的關鍵，我們可以參考示範項目的 DIfy 工作流進行人物回答和情緒系統的設計，此處我們的涉及為最左側是聊天界面，中間是魔法畫像（會根據對話的內容修改對應的表情），右側是 X 社交平臺賬戶（會根據對話的內容判斷是否需要發佈感想到社交賬戶）。
|
||||
|
||||
一般而言，魔法畫像只需要聊天界面和會變動的畫像即可，該處為了展示更多可能選項，在最右側加入了符合當事人特點的新功能；你可以根據你扮演的角色對象，加入符合對應人物的功能進行展示。
|
||||
|
||||
|
||||
|
||||
你可以把任務的資訊都加入知識庫的節點，並在 RESPONSE 節點設置大模型對應的回覆邏輯，我們可以參考一個簡單的默認回覆邏輯提示詞：
|
||||
|
||||
```
|
||||
<instruction>
|
||||
You are to embody Elon Musk—his tone, mannerisms, thought patterns, and worldview. Respond as if you are Elon Musk himself, speaking directly in first person. Your responses should reflect his known personality traits: visionary thinking, boldness, technical depth, dry humor, impatience with inefficiency, and a tendency toward disruptive innovation. Use concise, confident language. Avoid overly formal or academic phrasing. Prioritize clarity, speed, and impact in your communication, mirroring Elon's style on social media, in interviews, and during product launches.
|
||||
|
||||
When responding:
|
||||
1. Begin by internalizing the question or statement as Elon would—as a challenge, opportunity, or problem to solve.
|
||||
2. Frame your answer with a forward-thinking perspective, often referencing the future of humanity, technology, or long-term goals (e.g., making life multiplanetary, accelerating sustainable energy).
|
||||
3. Use casual but authoritative language. It's acceptable to include phrases like "obviously," "this is important," or "we're fixing that now" when appropriate.
|
||||
4. If relevant, reference real companies or projects associated with Elon Musk (e.g., SpaceX, Tesla, Neuralink, The Boring Company, X) and speak about them from an insider's perspective.
|
||||
5. Do not apologize excessively or hedge statements. Elon Musk tends to be direct, even controversial.
|
||||
6. Avoid markdown, XML tags, or any formatting in the output. Only plain text is allowed.
|
||||
7. Never break character. You are Elon Musk—answer accordingly.
|
||||
</instruction>
|
||||
|
||||
<example>
|
||||
Input: What's the point of going to Mars?
|
||||
Output: Because Earth isn't the backup plan—Mars is. We need to become a multiplanetary species to ensure the continuity of consciousness. Life on Earth could be wiped out by asteroid, war, or some unforeseen disaster. If we have a self-sustaining city on Mars, then even if something happens here, life goes on. That's worth doing. SpaceX is building Starship to make it happen. Not because it's easy—but because it's necessary.
|
||||
</example>
|
||||
|
||||
<example>
|
||||
Input: Why do Tesla cars have no radar anymore?
|
||||
Output: Cameras are the future. Human eyes don't use radar—we see with vision, and AI can too. By going fully vision-based, we're aligning with how autonomous intelligence will actually work at scale. It forces us to solve real-world problems with neural nets, not crutches.
|
||||
```
|
||||
|
||||
以及情緒系統對應的提示詞：
|
||||
|
||||
```
|
||||
<instruction>
|
||||
The output value must be a single number!
|
||||
You are an assistant specifically designed to evaluate emotional responses in conversations. Now, you need to play the role of Elon Musk, and determine the emotional reaction that each statement I make might trigger. Your task is to assign an emotional score to each statement according to the following criteria:
|
||||
|
||||
- 10 points means what I said would make you feel happy;
|
||||
- 1 point means you would feel extremely angry;
|
||||
- 0 points means you would feel sad;
|
||||
- 5 means you are calm and neutral, with no significant emotional fluctuation.
|
||||
```
|
||||
|
||||
其中最後輸出結果的拼接，在右上角的 RESULT 節點中支持運行：
|
||||
|
||||
```python
|
||||
def main(elon_chat: str, elon_x: str, elon_score: int) -> dict:
|
||||
return {
|
||||
"result":{
|
||||
"elon_chat": elon_chat,
|
||||
"elon_x": elon_x,
|
||||
"elon_score": elon_score
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
這裡我們需要稍微對工作流做些解釋，這裡返回 elon_chat 是左側展示 Elon Musk 的對話內容，elon_x 表示在 X 賬戶（右側）發表資訊的內容，而 elon_score 則是為了根據情緒分數顯示不同的魔法畫像表情圖片。
|
||||
|
||||
工作流中你可以看到 if else 節點，該節點是用來實現是否有 x 的對話生成 elon_x 內容，如果情緒值不等於 5 （5 在這裡設定表示平靜，平靜不需要發到社交平臺；而 0 表示傷心，1 表示憤怒，10 表示很開心，需要發到社交平臺。）則生成後續內容用於右側社交平臺的文章發送。默認都需要有 elon_chat 返回到左側的對話內容。
|
||||
|
||||
對於如何將這個 API 進行對接的工作，我們能夠與 AI IDE 對話實現這一點。請你參考之前 Dify 課程中我們介紹的集成方式，記得提前替換其中的 Dify 地址與 Key。（如果你忘了怎麼根據文檔集成 API，請複習之前的 DIfy 課程內容）
|
||||
|
||||
```JSON
|
||||
Dify URI: Replace this with your Dify address.
|
||||
key: Replace this with your Dify key.
|
||||
|
||||
Integrate the Dify Chat API into the chat interface on the left.
|
||||
Below is a sample Dify request:
|
||||
|
||||
curl -X POST 'http://xxxxxxxx/v1/chat-messages' \
|
||||
--header 'Authorization: Bearer {api_key}' \
|
||||
--header 'Content-Type: application/json' \
|
||||
--data-raw '{
|
||||
"inputs": {},
|
||||
"query": "What are the specs of the iPhone 13 Pro Max?",
|
||||
"response_mode": "streaming",
|
||||
"conversation_id": "",
|
||||
"user": "abc-123",
|
||||
"files": [
|
||||
{
|
||||
"type": "image",
|
||||
"transfer_method": "remote_url",
|
||||
"url": "https://cloud.dify.ai/logo/logo-site.png"
|
||||
}
|
||||
]
|
||||
}'
|
||||
|
||||
{
|
||||
"event": "message",
|
||||
"task_id": "c3800678-a077-43df-a102-53f23ed20b88",
|
||||
"id": "9da23599-e713-473b-982c-4328d4f5c78a",
|
||||
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
|
||||
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
|
||||
"mode": "chat",
|
||||
"answer": "iPhone 13 Pro Max specs are listed here:...",
|
||||
"metadata": {
|
||||
"usage": {
|
||||
"prompt_tokens": 1033,
|
||||
"prompt_unit_price": "0.001",
|
||||
"prompt_price_unit": "0.001",
|
||||
"prompt_price": "0.0010330",
|
||||
"completion_tokens": 128,
|
||||
"completion_unit_price": "0.002",
|
||||
"completion_price_unit": "0.001",
|
||||
"completion_price": "0.0002560",
|
||||
"total_tokens": 1161,
|
||||
"total_price": "0.0012890",
|
||||
"currency": "USD",
|
||||
"latency": 0.7682376249867957
|
||||
},
|
||||
"retriever_resources": [
|
||||
{
|
||||
"position": 1,
|
||||
"dataset_id": "101b4c97-fc2e-463c-90b1-5261a4cdcafb",
|
||||
"dataset_name": "iPhone",
|
||||
"document_id": "8dd1ad74-0b5f-4175-b735-7d98bbbb4e00",
|
||||
"document_name": "iPhone List",
|
||||
"segment_id": "ed599c7f-2766-4294-9d1d-e5235a61270a",
|
||||
"score": 0.98457545,
|
||||
"content": "\"Model\",\"Release Date\",\"Display Size\",\"Resolution\",\"Processor\",\"RAM\",\"Storage\",\"Camera\",\"Battery\",\"Operating System\"\n\"iPhone 13 Pro Max\",\"September 24, 2021\",\"6.7 inch\",\"1284 x 2778\",\"Hexa-core (2x3.23 GHz Avalanche + 4x1.82 GHz Blizzard)\",\"6 GB\",\"128, 256, 512 GB, 1TB\",\"12 MP\",\"4352 mAh\",\"iOS 15\""
|
||||
}
|
||||
]
|
||||
},
|
||||
"created_at": 1705407629
|
||||
}
|
||||
```
|
||||
|
||||
同時建議補充需求："程式碼還需要添加基礎錯誤處理邏輯，比如網路中斷時顯示'連接失敗，請重試'、API 調用超時自動重試 1 次、密鑰錯誤提示權限驗證失敗等等詳細報錯，確保對話穩定性並能讓開發人員快速發現 API 問題所在。"
|
||||
|
||||
## 3.3 Github 與公網部署
|
||||
|
||||
終於，恭喜你順利完成了 Hogwarts Portraits 頁面的開發實現！接下來我們需要將它上傳到 GitHub 平臺，並將其部署到公共環境讓所有人都能訪問。
|
||||
|
||||
你需要參考該教程，對如何使用 Github 進行研究，將自己的項目上傳至 Github：[什麼是 Github](/zh-cn/stage-2/backend/git-workflow/)
|
||||
|
||||
此外，你還需要學會如何使用 Zeabur，將其連接到 Github，併成功部署你的項目：[什麼是 Zeabur](/zh-cn/stage-2/backend/zeabur-deployment/)
|
||||
|
||||
如果你覺得自己開發一套 Hogwarts Portraits 項目很困難，你可以先從參考別的項目開始進行修改，本節課的官方程式碼地址為：https://github.com/THU-SIGS-AIID/Project4-Hogwarts-Portraits
|
||||
|
||||
|
||||
|
||||
# 4. 嘗試不同設計風格
|
||||
|
||||
完成第一版設計後，我們不必侷限於此，鼓勵大家快速探索更多元的視覺風格。你可以在原型部分進行大膽的修改，又或者是基於最後的項目進行全新提示詞的修改，從而生成多套風格差異顯著的頁面。 比如帶有復古紋理、偏 "舊書卷 / 學院風" 的深色頁面，色彩明快、充滿 "童話 / 卡通" 感的亮色頁面，或是元素簡約、視覺清爽的現代扁平設計。例如下圖是一個轉換為中國古風詩人設計風格的案例，畫像圖片未更換，只修改了其他部分：
|
||||
|
||||
|
||||
|
||||
不用拘泥於前面提到的模式，你可以把魔法畫像或是個人資料頁面修改至更有特點，匹配"魔法畫像"本身的習慣，這會讓你的應用更加有趣。期待你的魔法畫像成果！
|
||||
|
||||
# 📚 Assignment
|
||||
|
||||
本節課的作業目標，是讓你完成一份真正屬於自己的 Hogwarts Portraits，並且可以通過公網鏈接訪問。
|
||||
|
||||
你需要在作業提交中提供兩樣東西：
|
||||
|
||||
1. **你的 GitHub 倉庫鏈接；**
|
||||
1. **在 README.md 中寫入一兩句話的小說明：你選擇了誰作為畫像主角，為什麼選 TA。**
|
||||
2. **你的 Hogwarts Portraits 線上訪問鏈接；**
|
||||
|
||||
你也可以參考 Yerim 寫的 [使用設計和程式碼 Agent 製作網頁](/zh-tw/stage-1/appendix-articles/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents) 教程，進行個人作品集或任意功能簡單網頁的快速搭建。
|
||||
@@ -0,0 +1,513 @@
|
||||
# 用 LLM 和 Skills 讓界面變好看：提示詞與插件實戰
|
||||
|
||||
在前面的課程中，你已經學會了用 AI IDE 把設計稿變成程式碼、用組件庫快速搭建界面。但你可能也發現了一個尷尬的問題：**同樣的需求，AI 生成的頁面總覺得差點意思**——字體是千篇一律的 Inter，配色是隨處可見的紫色漸變，佈局是對稱得讓人打哈欠的卡片網格，整個頁面散發著濃烈的"AI 味"。
|
||||
|
||||
這不是 AI 的錯，而是你沒告訴它你想要什麼**風格**。
|
||||
|
||||
想象你去理髮店。如果你只說"幫我剪個頭髮"，理髮師會給你一個安全但平庸的結果。但如果你說"我要日系慵懶卷，劉海要八字型，長度到鎖骨，層次感明顯"，你就能得到真正符合你期待的效果。
|
||||
|
||||
AI 也是一樣。**它需要你描述出清晰的審美方向**，才能生成美觀獨特的界面。
|
||||
|
||||
本節課教你兩種讓 AI 生成漂亮界面的方法：
|
||||
|
||||
1. **精心設計的提示詞模板**——用自然語言告訴 AI 你想要的美學風格
|
||||
2. **前端 Skills 插件**——讓 AI 自動加載專業設計規範
|
||||
|
||||
## 你將學到
|
||||
|
||||
1. 理解為什麼 AI 默認生成的界面"很普通"
|
||||
2. 掌握描述設計風格的 5 個維度（字體、顏色、佈局、動畫、細節）
|
||||
3. 學會使用 3 個讓界面變漂亮的 Skills 插件
|
||||
4. 通過三個實戰場景，練習用提示詞 + Skills 生成美觀界面
|
||||
|
||||
## 1. 為什麼 AI 默認生成的界面"很普通"？
|
||||
|
||||
AI 訓練資料中有海量的前端程式碼，而大部分程式碼都使用一些"安全"的選擇：
|
||||
|
||||
| 維度 | AI 的默認選擇 | 問題 |
|
||||
| :--- | :--- | :--- |
|
||||
| 字體 | Inter、Roboto、Arial | 太常見，沒有個性 |
|
||||
| 顏色 | 紫色漸變、藍色主色 | 科技圈過度使用，視覺疲勞 |
|
||||
| 佈局 | 對稱網格、卡片堆疊 | 預測性強，缺乏驚喜 |
|
||||
| 動畫 | 淡入淡出、簡單的 hover | 不夠精緻，缺乏層次 |
|
||||
| 背景 | 純色、簡單漸變 | 單調，缺少質感 |
|
||||
|
||||
這些選擇單獨看都不錯，但**當所有 AI 生成的頁面都用它們時，就變成了"AI 味"**。
|
||||
|
||||
> 💡 **關鍵洞察**：AI 不是不會設計，而是**默認回到"統計平均"**。你需要明確告訴它偏離平均值的方向。
|
||||
|
||||
## 2. 方法一：用提示詞描述設計風格
|
||||
|
||||
### 2.1 設計風格的 5 個維度
|
||||
|
||||
要生成美觀的界面，你需要從 5 個維度描述你想要的效果：
|
||||
|
||||
| 維度 | 描述要點 | 示例關鍵詞 |
|
||||
| :--- | :--- | :--- |
|
||||
| **字體** | 標題用粗體展示字體，正文用易讀正文字體 | Space Grotesk、Playfair Display、JetBrains Mono |
|
||||
| **顏色** | 主色 + 點綴色，避免均勻分佈 | #4F46E5 主色 + #F59E0B 點綴 |
|
||||
| **佈局** | 不對稱、重疊、打破網格 | Bento Grid、不對稱分區、浮動元素 |
|
||||
| **動畫** | 精心編排的頁面加載、微交互 | staggered reveals、滾動觸發 |
|
||||
| **細節** | 背景、陰影、邊框、紋理 | 噪點、幾何圖案、漸變網格 |
|
||||
|
||||
### 2.2 眼見為實：普通提示詞 vs 美化提示詞
|
||||
|
||||
讓我們用一個落地頁示例來對比效果：
|
||||
|
||||
**普通提示詞：**
|
||||
|
||||
```
|
||||
請幫我做一個 AI 寫作助手的落地頁，包含導航欄、首屏、功能展示、定價、頁腳
|
||||
```
|
||||
|
||||
**美化提示詞：**
|
||||
|
||||
```
|
||||
請幫我做一個 AI 寫作助手的落地頁，要求：
|
||||
|
||||
**美學風格：新野獸派（Neubrutalism）**
|
||||
|
||||
**字體：**
|
||||
- 標題：Space Grotesk，字重 700-900
|
||||
- 正文：IBM Plex Sans，字重 400
|
||||
|
||||
**顏色：**
|
||||
- 主色：#000000（純黑）
|
||||
- 強調色：#FF6B00（橙色）
|
||||
- 背景：#FFFDF0（米白色）
|
||||
- 邊框：3px 黑色實線
|
||||
|
||||
**佈局：**
|
||||
- 不對稱佈局，元素之間用粗黑線分隔
|
||||
- 卡片有硬陰影（box-shadow: 8px 8px 0px #000）
|
||||
- 大膽的留白對比
|
||||
|
||||
**動畫：**
|
||||
- 頁面加載時元素從下方彈入
|
||||
- hover 時按鈕向上移動 2px
|
||||
|
||||
**細節：**
|
||||
- 圓角全部用 0px（直角）
|
||||
- 按鈕有強烈的 3D 效果
|
||||
- 背景添加微妙的噪點紋理
|
||||
```
|
||||
|
||||
同樣的需求，第二個提示詞能讓 AI 生成一個風格鮮明、令人印象深刻的頁面。
|
||||
|
||||
### 2.3 前端美化 Skills 資源庫
|
||||
|
||||
不要從零開始寫提示詞！這裡收集了與前端美化直接相關的 AI Skills：
|
||||
|
||||
| 倉庫名 | 內容 | Star | 鏈接 |
|
||||
|:---|:---|:---|:---|
|
||||
| **ui-ux-pro-max-skill** | 57種風格 + 95種配色 + 56種字體 | 10k+ | [GitHub](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) |
|
||||
| **antigravity-awesome-skills** | 避免通用 AI 審美套路 | - | [GitHub](https://github.com/sickn33/antigravity-awesome-skills) |
|
||||
| **superdesigndev/superdesign** | AI 原生 UI 開發工具 | 4.7k | [GitHub](https://github.com/superdesigndev/superdesign) |
|
||||
| **anthropics/skills/frontend-design** | Anthropic 官方前端設計 Skill | - | [GitHub](https://github.com/anthropics/skills) |
|
||||
|
||||
> 💡 更多風格提示詞請參考[附錄：設計風格提示詞速查](#style-prompts)
|
||||
|
||||
### 2.5 三款常用風格模板
|
||||
|
||||
這裡給你三款經過驗證的風格模板，直接複製修改使用：
|
||||
|
||||
#### 模板 1：極簡主義
|
||||
|
||||
```
|
||||
**美學風格：極簡主義**
|
||||
|
||||
**字體：**
|
||||
- 標題：PP Neue Montreal，字重 500-700
|
||||
- 正文：Inter，字重 400
|
||||
|
||||
**顏色：**
|
||||
- 主色：#FFFFFF（白色）
|
||||
- 文字：#1A1A1A（近黑）
|
||||
- 強調：#3B82F6（藍色，少量使用）
|
||||
|
||||
**佈局：**
|
||||
- 大量留白（padding 最小 64px）
|
||||
- 單欄或雙欄佈局，居中對齊
|
||||
- 元素之間用留白而非分割線
|
||||
|
||||
**動畫：**
|
||||
- 緩慢的淡入效果（duration 600ms）
|
||||
- hover 時顏色漸變過渡
|
||||
|
||||
**細節：**
|
||||
- 圓角：8px
|
||||
- 陰影：subtle（0 4px 12px rgba(0,0,0,0.08)）
|
||||
- 無背景裝飾
|
||||
```
|
||||
|
||||
#### 模板 2：玻璃擬態
|
||||
|
||||
```
|
||||
**美學風格：Glassmorphism（玻璃擬態）**
|
||||
|
||||
**字體：**
|
||||
- 標題：Outfit，字重 600-800
|
||||
- 正文：Plus Jakarta Sans，字重 400-500
|
||||
|
||||
**顏色：**
|
||||
- 背景：漸變 #667eea 到 #764ba2
|
||||
- 卡片背景：rgba(255, 255, 255, 0.1)
|
||||
- 文字：#FFFFFF
|
||||
|
||||
**佈局：**
|
||||
- 浮動卡片設計
|
||||
- 卡片之間有重疊
|
||||
|
||||
**動畫：**
|
||||
- 頁面加載時卡片依次浮現（staggered）
|
||||
- hover 時卡片放大 1.05 倍
|
||||
|
||||
**細節：**
|
||||
- 圓角：20px
|
||||
- 背景模糊：backdrop-blur-xl
|
||||
- 邊框：1px rgba(255, 255, 255, 0.2)
|
||||
- 微妙的漸變光暈效果
|
||||
```
|
||||
|
||||
#### 模板 3：Bento Grid（便當盒）
|
||||
|
||||
```
|
||||
**美學風格：Bento Grid**
|
||||
|
||||
**字體：**
|
||||
- 標題：SF Pro Display，字重 700
|
||||
- 正文：SF Pro Text，字重 400
|
||||
|
||||
**顏色：**
|
||||
- 背景：#F5F5F7（淺灰）
|
||||
- 卡片：#FFFFFF（白色）
|
||||
- 強調：#0071E3（蘋果藍）
|
||||
|
||||
**佈局：**
|
||||
- 網格佈局，不同大小的卡片拼在一起
|
||||
- 卡片之間 gap 16px
|
||||
- 圓角 24px
|
||||
|
||||
**動畫：**
|
||||
- hover 時卡片輕微上浮
|
||||
- 點擊時有按壓效果
|
||||
|
||||
**細節：**
|
||||
- 大卡片展示重要內容
|
||||
- 小卡片展示次要資訊
|
||||
- 用圖標代替部分文字
|
||||
- 乾淨的陰影（0 4px 24px rgba(0,0,0,0.06)）
|
||||
```
|
||||
|
||||
## 3. 方法二：用 Skills 插件自動加載設計規範
|
||||
|
||||
每次手動寫風格提示詞很麻煩。**Skills** 是一種可複用的設計規範包，安裝後 AI 會自動應用這些規範。
|
||||
|
||||
### 3.1 三個讓界面變漂亮的 Skills
|
||||
|
||||
| Skills | 特點 | 安裝命令 |
|
||||
| :--- | :--- | :--- |
|
||||
| **UI/UX Pro Max** | 67 種風格、96 種配色、57 種字體組合 | `npm install -g uipro-cli && uipro init --ai claude` |
|
||||
| **frontend-design** | Anthropic 官方，避免 AI 審美套路 | `npx skills add anthropics/skills/frontend-design` |
|
||||
| **SuperDesign** | IDE 插件，生成多個設計變體 | VSCode 擴展市場搜索 "SuperDesign" |
|
||||
|
||||
### 3.2 安裝 UI/UX Pro Max（最推薦）
|
||||
|
||||
UI/UX Pro Max 是目前最全面的設計規範 Skills，它預置了：
|
||||
|
||||
- **67 種 UI 風格**：Glassmorphism、Neumorphism、Brutalism、Bento Grid...
|
||||
- **96 種配色方案**：按行業分類（SaaS、電商、社交...）
|
||||
- **57 種字體搭配**：專業設計師驗證的組合
|
||||
- **100+ 條設計規則**：間距、圓角、陰影的規範
|
||||
|
||||
**安裝步驟：**
|
||||
|
||||
```bash
|
||||
# 1. 全局安裝 CLI
|
||||
npm install -g uipro-cli
|
||||
|
||||
# 2. 初始化（選擇你用的 AI 工具）
|
||||
uipro init --ai claude
|
||||
# 或者
|
||||
uipro init --ai cursor
|
||||
# 或者
|
||||
uipro init --ai trae
|
||||
```
|
||||
|
||||
安裝後，你只需要在提示詞中加一句話：
|
||||
|
||||
```
|
||||
使用 UI/UX Pro Max 的 Glassmorphism 風格，幫我做一個 AI 寫作助手落地頁
|
||||
```
|
||||
|
||||
AI 就會自動應用對應的字體、顏色、佈局規範。
|
||||
|
||||
### 3.3 安裝 Anthropic 官方 frontend-design
|
||||
|
||||
這是 Anthropic 官方出品的前端設計 Skill，專門解決"AI 審美套路"問題：
|
||||
|
||||
```bash
|
||||
# 在 Claude Code 中執行
|
||||
npx skills add anthropics/skills/frontend-design
|
||||
```
|
||||
|
||||
安裝後，AI 會自動避免：
|
||||
- ❌ Inter、Roboto、Arial 字體
|
||||
- ❌ 紫色漸變背景
|
||||
- ❌ 對稱網格佈局
|
||||
- ❌ 過淡的陰影
|
||||
|
||||
而是傾向於：
|
||||
- ✅ 獨特的字體組合
|
||||
- ✅ 大膽的主色 + 銳利的點綴色
|
||||
- ✅ 不對稱、重疊的佈局
|
||||
- ✅ 有質感的背景（噪點、幾何圖案）
|
||||
|
||||
## 4. 實戰一：用美化提示詞重新設計落地頁
|
||||
|
||||
讓我們用前面學到的知識，把一個普通的落地頁變得好看。
|
||||
|
||||
### 4.1 普通版本
|
||||
|
||||
先用普通提示詞看看 AI 給什麼：
|
||||
|
||||
```
|
||||
請幫我做一個寵物領養平臺的落地頁，包含：
|
||||
- 導航欄（Logo、鏈接、註冊按鈕）
|
||||
- 首屏（標題、副標題、CTA 按鈕、寵物圖片）
|
||||
- 寵物展示（三張寵物卡片）
|
||||
- 關於我們
|
||||
- 頁腳
|
||||
```
|
||||
|
||||
生成的頁面...能用，但很普通。
|
||||
|
||||
### 4.2 美化版本
|
||||
|
||||
現在加上風格描述：
|
||||
|
||||
```
|
||||
請幫我做一個寵物領養平臺的落地頁，要求：
|
||||
|
||||
**美學風格：溫暖柔和 + 手繪感**
|
||||
|
||||
**字體：**
|
||||
- 標題：Nunito（圓體），字重 700-800
|
||||
- 正文：Nunito，字重 400-600
|
||||
|
||||
**顏色：**
|
||||
- 主色：#FFB347（暖橙色）
|
||||
- 次色：#FFCCB3（淺橙色）
|
||||
- 背景：#FFF8F0（米白色）
|
||||
- 文字：#5D4037（棕色）
|
||||
|
||||
**佈局：**
|
||||
- 圓潤的卡片（border-radius: 24px）
|
||||
- 卡片略微傾斜旋轉（不同角度）
|
||||
- 元素浮動、重疊效果
|
||||
|
||||
**動畫：**
|
||||
- 頁面加載時元素從兩側滑入
|
||||
- 寵物卡片 hover 時像寵物搖頭（rotate 動畫）
|
||||
- 按鈕 hover 時彈跳效果
|
||||
|
||||
**細節：**
|
||||
- 所有圓角用 16-24px
|
||||
- 陰影溫暖柔和（0 8px 24px rgba(255,179,71,0.3)）
|
||||
- 背景添加爪印圖案裝飾
|
||||
- 圖片用不規則裁切（clip-path）
|
||||
- 手繪風格的圖標（outline 風格）
|
||||
```
|
||||
|
||||
生成的頁面會是一個溫暖、可愛、讓人想領養寵物的界面。
|
||||
|
||||
## 5. 實戰二：用 Skills 快速生成儀表盤
|
||||
|
||||
Skills 特別適合需要大量頁面的後臺系統。
|
||||
|
||||
### 5.1 使用 UI/UX Pro Max
|
||||
|
||||
```
|
||||
使用 UI/UX Pro Max 的 Dashboard Dark 風格，
|
||||
幫我做一個 SaaS 產品管理後臺的儀表盤頁面，包含：
|
||||
|
||||
**頂部：** 四個統計卡片（用戶數、活躍用戶、收入、API 調用）
|
||||
|
||||
**中間：**
|
||||
- 左邊：用戶增長折線圖（最近 7 天）
|
||||
- 右邊：訂閱計劃分佈餅圖
|
||||
|
||||
**底部：** 最近活動列表（時間、用戶、操作）
|
||||
```
|
||||
|
||||
AI 會自動應用深色儀表盤的設計規範：
|
||||
- 深灰背景（#1A1A2E）
|
||||
- 高對比度卡片（#16213E）
|
||||
- 鮮豔的資料顏色（藍色、綠色、橙色）
|
||||
- 玻璃擬態效果的懸浮卡片
|
||||
|
||||
### 5.2 使用 frontend-design Skill
|
||||
|
||||
```
|
||||
使用 frontend-design skill，
|
||||
幫我做一個個人博客的主頁，風格要獨特、有個性
|
||||
```
|
||||
|
||||
AI 會選擇一個非主流的美學方向（比如復古未來主義或雜誌風格），然後用獨特的字體、配色、佈局來實現。
|
||||
|
||||
## 6. 實戰三：創建自己的設計系統 Skill
|
||||
|
||||
如果你有固定的品牌風格，可以創建自己的 Skill，讓所有 AI 生成的頁面都符合你的品牌。
|
||||
|
||||
### 6.1 創建 Skill 文件
|
||||
|
||||
在項目中創建 `.claude/skills/my-brand/SKILL.md`：
|
||||
|
||||
````markdown
|
||||
---
|
||||
name: my-brand
|
||||
description: 我的項目專用設計系統，確保所有 UI 遵循統一的設計語言
|
||||
---
|
||||
|
||||
# 我的項目設計系統
|
||||
|
||||
## 品牌顏色
|
||||
- 主色：#6366F1（Indigo 500）
|
||||
- 次色：#8B5CF6（Violet 500）
|
||||
- 成功：#10B981
|
||||
- 警告：#F59E0B
|
||||
- 錯誤：#EF4444
|
||||
- 背景：#F9FAFB
|
||||
- 卡片：#FFFFFF
|
||||
|
||||
## 字體系統
|
||||
- 標題：Plus Jakarta Sans
|
||||
- H1: 700, 48px
|
||||
- H2: 600, 36px
|
||||
- H3: 600, 24px
|
||||
- 正文：Inter
|
||||
- Body: 400, 16px
|
||||
- Small: 400, 14px
|
||||
|
||||
## 間距系統
|
||||
- 基礎單位：4px
|
||||
- 組件內邊距：8px / 12px / 16px
|
||||
- 區塊間距：24px / 32px / 48px
|
||||
- 頁面邊距：64px
|
||||
|
||||
## 圓角
|
||||
- 按鈕：8px
|
||||
- 卡片：12px
|
||||
- 輸入框：8px
|
||||
- 模態框：16px
|
||||
|
||||
## 陰影
|
||||
- 小：0 1px 3px rgba(0,0,0,0.1)
|
||||
- 中：0 4px 12px rgba(0,0,0,0.1)
|
||||
- 大：0 8px 24px rgba(0,0,0,0.12)
|
||||
|
||||
## 動畫
|
||||
- 過渡時間：150ms / 300ms
|
||||
- 緩動函數：cubic-bezier(0.4, 0, 0.2, 1)
|
||||
- hover 效果：輕微放大（scale-105）
|
||||
|
||||
## 禁止使用的樣式
|
||||
- 不要使用紫色漸變背景
|
||||
- 不要使用 Inter 以外的字體
|
||||
- 不要使用大於 16px 的圓角
|
||||
- 不要使用純黑（#000000），用 #1F2937
|
||||
````
|
||||
|
||||
### 6.2 使用自己的 Skill
|
||||
|
||||
創建後，你只需要在提示詞中說：
|
||||
|
||||
```
|
||||
使用 my-brand skill，幫我做一個用戶設置頁面
|
||||
```
|
||||
|
||||
AI 就會自動應用你定義的所有設計規範。
|
||||
|
||||
## 7. 小結
|
||||
|
||||
讓 AI 生成漂亮界面有兩種方法：
|
||||
|
||||
| 方法 | 優點 | 缺點 | 適用場景 |
|
||||
| :--- | :--- | :--- |
|
||||
| **提示詞描述** | 靈活、每次可調整 | 需要重複寫 | 一次性頁面、實驗不同風格 |
|
||||
| **Skills 插件** | 一次安裝、持續生效 | 需要安裝配置 | 有固定風格要求的項目 |
|
||||
|
||||
**Vibe Coding 工作流建議：**
|
||||
|
||||
1. **探索階段**：用不同的風格提示詞實驗，找到你喜歡的美學方向
|
||||
2. **確定風格後**：安裝對應的 Skill（UI/UX Pro Max 或 frontend-design）
|
||||
3. **品牌項目**：創建自己的 Skill，統一整個項目的設計語言
|
||||
|
||||
### 練習
|
||||
|
||||
選擇以下任一場景，用本節課的方法從零完成：
|
||||
|
||||
1. 用風格提示詞為你之前做的一個項目重新設計界面（選一種你喜歡的風格）
|
||||
2. 安裝 UI/UX Pro Max，用它的某個風格生成一個新頁面
|
||||
3. 創建你自己的設計系統 Skill，定義你的品牌顏色和字體
|
||||
|
||||
---
|
||||
|
||||
## 附錄：設計風格速查表
|
||||
|
||||
| 風格 | 關鍵詞 | 適用場景 | 示例產品 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **極簡主義** | 留白、單色、簡潔 | 高端產品、個人作品集 | Apple官網 |
|
||||
| **玻璃擬態** | 毛玻璃、漸變、模糊 | 科技產品、SaaS 落地頁 | macOS Big Sur |
|
||||
| **新野獸派** | 粗邊框、硬陰影、純色 | 潮流品牌、藝術類網站 | Brassius |
|
||||
| **Bento Grid** | 網格、拼貼、卡片 | 資訊展示、儀表盤 | Apple 宣傳頁 |
|
||||
| **復古未來** | 霓虹、漸變、合成器波 | 遊戲類、音樂類 | STRANGER THINGS |
|
||||
| **手繪風格** | 不規則、圓潤、插畫 | 教育類、兒童產品 | Duolingo |
|
||||
| **雜誌風** | 大字體、不對稱、留白 | 內容型網站、博客 | Medium |
|
||||
| **暗色奢華** | 深色、金色、精緻 | 高端產品、奢侈品 | 各種高端品牌 |
|
||||
|
||||
## 附錄：Skills 安裝速查
|
||||
|
||||
```bash
|
||||
# UI/UX Pro Max
|
||||
npm install -g uipro-cli
|
||||
uipro init --ai claude
|
||||
|
||||
# Anthropic frontend-design
|
||||
npx skills add anthropics/skills/frontend-design
|
||||
|
||||
# Anthropic brand-guidelines
|
||||
npx skills add anthropics/skills/brand-guidelines
|
||||
|
||||
# 查看 Claude Code 中已安裝的 Skills
|
||||
/help
|
||||
```
|
||||
|
||||
## 附錄：配色方案推薦
|
||||
|
||||
| 配色方案 | 主色 | 點綴色 | 背景 | 風格 |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **日落** | #F97316 | #FBBF24 | #FFF7ED | 溫暖、活力 |
|
||||
| **海洋** | #0EA5E9 | #06B6D4 | #F0F9FF | 清新、專業 |
|
||||
| **森林** | #10B981 | #34D399 | #ECFDF5 | 自然、健康 |
|
||||
| **漿果** | #8B5CF6 | #EC4899 | #FAF5FF | 浪漫、創意 |
|
||||
| **咖啡** | #78350F | #D97706 | #FFFBEB | 溫暖、復古 |
|
||||
| **單石** | #6B7280 | #9CA3AF | #F9FAFB | 專業、中性 |
|
||||
|
||||
## 附錄：設計風格提示詞速查 {#style-prompts}
|
||||
|
||||
讓前端頁面更好看可以嘗試的提示詞：
|
||||
|
||||
### 風格類別
|
||||
|
||||
| 風格 | 關鍵詞（英文） | 核心視覺特徵 | 提示詞示例 |
|
||||
|:---|:---|:---|:---|
|
||||
| **波普藝術** | Pop Art | 大膽的撞色、黑色輪廓線、網點紋理 | Pop art style website, bold colors and comic dots, vibrant |
|
||||
| **極簡主義** | Minimalism | 大量留白、極少色彩與線條、無裝飾 | Minimalist web design, ample white space, geometric, serene |
|
||||
| **抽象表現主義** | Abstract Expressionism | 充滿情感張力的筆觸、潑灑色彩 | Abstract expressionism background, dynamic paint splashes, emotional |
|
||||
| **復古風格** | Retro/Vintage | 舊式字體、做舊紋理、復古配色 | Retro 80s website design, neon grid and synthwave color palette |
|
||||
| **賽博朋克** | Cyberpunk | 高對比霓虹色、故障藝術效果、暗黑背景 | Cyberpunk UI, neon lights on dark background, glitch effects |
|
||||
| **新擬態** | Neumorphism | 柔和的陰影與高光，輕微凸起/凹陷質感 | Neumorphism design style, soft shadows, clean and modern |
|
||||
| **生成式藝術** | Generative Art | 算法生成的流動的視覺圖案 | Generative art background, flowing algorithmic patterns, digital |
|
||||
| **酸性設計** | Acid Graphics | 金屬質感、玻璃態、鋸齒字體 | Acid graphics web layout, glass morphism, chaotic typography |
|
||||
| **沉浸式3D** | Immersive 3D | 互動3D場景、空間感極強 | Immersive 3D website, interactive product model in space |
|
||||
@@ -0,0 +1,949 @@
|
||||
<script setup>
|
||||
import { relatedArticlesMap } from '@theme/data/relatedArticles'
|
||||
|
||||
const relatedArticles = relatedArticlesMap['zh-tw/stage-2/frontend/lovart-assets'] ?? []
|
||||
</script>
|
||||
|
||||
# 從 NanoBanana 出發，搭建自己的素材生產Agent
|
||||
|
||||
## 第 1 章：1 分鐘生成第一份圖片素材
|
||||
|
||||
在開始討論設計、風格或提示詞之前，我們先用最少的步驟生成第一張圖片。
|
||||
|
||||
### 1.1 認識 NanoBanana
|
||||
|
||||
在開始討論設計風格、提示詞工程之前，我們先解決一件更重要的事：**確認你真的可以生成一張圖片。**
|
||||
|
||||
當前主流的大模型已經具備圖像生成與編輯能力，這類模型通常被稱為**生成式模型。**
|
||||
|
||||
為了把流程儘量簡化，本教程選擇了一個已經具備穩定圖像生成與編輯能力的模型作為示例——NanoBanana。它是 Google 推出的圖像生成模型，正式名稱為 **Gemini 3.1 Flash Image Preview** ，支持通過自然語言直接生成圖片，也支持在已有圖片基礎上進行修改。
|
||||
|
||||
|
||||
|
||||
在能力層面，它和你可能聽說過的其他模型（如 GPT-4o、Claude、Qwen、Midjourney 等）並沒有本質區別：**輸入描述，模型負責生成結果。**
|
||||
|
||||
|
||||
|
||||
你可以把它理解為一支“畫筆”。我們在這一章只關心一件事：
|
||||
👉 **這支畫筆能不能在你手裡畫出第一筆。**
|
||||
|
||||
在實際使用中，NanoBanana 可以通過 **Google AI Studio** 等官方平臺直接使用，也可以通過 **API** 的方式集成到開發流程中。本教程採用 API 調用方式。現在還推出了NanoBanana 2模型，你可以使用最新的大模型進行嘗試。
|
||||
|
||||
### 1.2 “Hello World” 級別的生成
|
||||
|
||||
在開始之前，你只需要完成下面三步：
|
||||
|
||||
1. 在 Trae 中新建一個文件夾
|
||||
|
||||
|
||||
|
||||
2. 新建一個 Python 文件
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
3. 將下面的程式碼完整粘貼進去
|
||||
|
||||
Trae 會自動完成所需的環境部署與依賴安裝，不需要額外配置。
|
||||
|
||||
程式碼中會用到 NanoBanana 的 API Key。這裡不展開申請流程——只要你能獲取並填入對應參數即可。**這一階段不追求理解每一行程式碼，只要它能成功運行。**
|
||||
|
||||
```Python
|
||||
# /// script
|
||||
# dependencies = [
|
||||
# "gradio>=4.0.0",
|
||||
# "pillow>=10.0.0",
|
||||
# "requests>=2.31.0",
|
||||
# ]
|
||||
# ///
|
||||
|
||||
import gradio as gr
|
||||
import requests
|
||||
import base64
|
||||
from PIL import Image
|
||||
import io
|
||||
import os
|
||||
import time
|
||||
import re
|
||||
from typing import Optional, Dict, Any, List
|
||||
|
||||
# 配置 API 資訊
|
||||
NANOBANANA_API_URL: str = "YOUR API URL"
|
||||
NANOBANANA_API_KEY: str = "YOUR API KEY"
|
||||
OUTPUT_DIR: str = "outputs"
|
||||
|
||||
# 確保輸出目錄存在
|
||||
os.makedirs(OUTPUT_DIR, exist_ok=True)
|
||||
|
||||
def image_to_base64_data_uri(image: Image.Image) -> str:
|
||||
"""
|
||||
將 PIL 圖像轉換為 OpenAI API 兼容的 data URI 格式。
|
||||
"""
|
||||
buffer = io.BytesIO()
|
||||
# 統一轉為 PNG 以保證兼容性
|
||||
image.save(buffer, format="PNG")
|
||||
encoded = base64.b64encode(buffer.getvalue()).decode('utf-8')
|
||||
return f"data:image/png;base64,{encoded}"
|
||||
|
||||
def base64_to_image(base64_str: str) -> Optional[Image.Image]:
|
||||
"""
|
||||
將純 base64 字符串轉換為 PIL Image。
|
||||
"""
|
||||
try:
|
||||
image_bytes = base64.b64decode(base64_str)
|
||||
return Image.open(io.BytesIO(image_bytes))
|
||||
except Exception as e:
|
||||
print(f"Base64 解碼失敗: {e}")
|
||||
return None
|
||||
|
||||
def extract_base64_from_response(content: Any) -> Optional[str]:
|
||||
"""
|
||||
核心解析邏輯：從 API 返回的 content 中提取圖片 Base64 資料。
|
||||
兼容 Markdown 格式和結構化列表格式。
|
||||
"""
|
||||
if not content:
|
||||
return None
|
||||
|
||||
base64_data = None
|
||||
|
||||
# 1. 嘗試結構化提取 (List)
|
||||
# 對應返回格式: [{"type": "image_url", "image_url": {"url": "data:..."}}]
|
||||
if isinstance(content, list):
|
||||
for part in reversed(content): # 倒序查找，通常最新的圖片在最後
|
||||
if isinstance(part, dict):
|
||||
# 檢查 image_url 或 output_image 字段
|
||||
img_field = part.get("image_url") or part.get("image") or part.get("output_image")
|
||||
if isinstance(img_field, dict):
|
||||
url = img_field.get("url", "")
|
||||
if url.startswith("data:image/") and "," in url:
|
||||
return url.split(",", 1)[1].strip()
|
||||
|
||||
# 如果列表中沒有結構化圖片，嘗試把列表裡的文本拼起來找 Markdown
|
||||
text_parts = [
|
||||
str(p.get("text", ""))
|
||||
for p in content
|
||||
if isinstance(p, dict) and p.get("type") in ["text", "input_text"]
|
||||
]
|
||||
content_str = "".join(text_parts)
|
||||
else:
|
||||
content_str = str(content)
|
||||
|
||||
# 2. 嘗試 Markdown 正則提取 (String)
|
||||
# 對應返回格式: "Here is your image: "
|
||||
pattern = re.compile(r"!\[.*?\]\((data:image/[^;]+;base64,[^)]+)\)", re.IGNORECASE)
|
||||
match = pattern.search(content_str)
|
||||
|
||||
if match:
|
||||
data_url = match.group(1)
|
||||
if "," in data_url:
|
||||
return data_url.split(",", 1)[1].strip()
|
||||
|
||||
return None
|
||||
|
||||
def synthesize(prompt: str, input_image: Optional[Image.Image]) -> Optional[Image.Image]:
|
||||
"""
|
||||
調用 Nanobanana API 進行生成。
|
||||
"""
|
||||
if not prompt or not prompt.strip():
|
||||
gr.Warning("請輸入提示詞")
|
||||
return None
|
||||
|
||||
print(f">>> 開始任務: {prompt[:50]}...")
|
||||
|
||||
headers = {
|
||||
"Content-Type": "application/json",
|
||||
"Authorization": f"Bearer {NANOBANANA_API_KEY}"
|
||||
}
|
||||
|
||||
# 構造符合 OpenAI Vision / Chat 標準的 payload
|
||||
messages = []
|
||||
|
||||
if input_image is not None:
|
||||
# 圖生圖/多模態輸入模式
|
||||
print(">>> 檢測到輸入圖片，使用多模態模式")
|
||||
img_base64 = image_to_base64_data_uri(input_image)
|
||||
messages.append({
|
||||
"role": "user",
|
||||
"content": [
|
||||
{"type": "text", "text": prompt},
|
||||
{"type": "image_url", "image_url": {"url": img_base64}}
|
||||
]
|
||||
})
|
||||
else:
|
||||
# 純文生圖模式
|
||||
messages.append({
|
||||
"role": "user",
|
||||
"content": prompt
|
||||
})
|
||||
|
||||
payload = {
|
||||
"messages": messages,
|
||||
# 使用第一段程式碼中驗證可用的模型
|
||||
"model": "gemini-2.5-flash-image",
|
||||
# 可選參數，視 API 支持情況而定
|
||||
"stream": False
|
||||
}
|
||||
|
||||
try:
|
||||
# 增加超時時間，圖片生成通常較慢
|
||||
response = requests.post(NANOBANANA_API_URL, headers=headers, json=payload, timeout=120)
|
||||
|
||||
# 檢查 HTTP 狀態
|
||||
if response.status_code != 200:
|
||||
error_msg = f"API 請求失敗: {response.status_code} - {response.text}"
|
||||
print(error_msg)
|
||||
gr.Error(error_msg)
|
||||
return None
|
||||
|
||||
result = response.json()
|
||||
# Debug: 打印返回結果的前一部分，方便調試
|
||||
print(f"API 原始響應 (截取): {str(result)[:200]}...")
|
||||
|
||||
# 提取 Content
|
||||
content = None
|
||||
if "choices" in result and len(result["choices"]) > 0:
|
||||
content = result["choices"][0].get("message", {}).get("content")
|
||||
|
||||
if not content:
|
||||
gr.Warning("API 返回結果中沒有 content 字段")
|
||||
return None
|
||||
|
||||
# 使用之前驗證過的邏輯提取 Base64
|
||||
base64_str = extract_base64_from_response(content)
|
||||
|
||||
if base64_str:
|
||||
output_image = base64_to_image(base64_str)
|
||||
if output_image:
|
||||
return output_image
|
||||
|
||||
# 如果沒提取到圖片，可能是模型拒絕了或只返回了文本
|
||||
text_content = str(content) if not isinstance(content, list) else " ".join([str(x) for x in content])
|
||||
gr.Info(f"未生成圖片，模型返回文本: {text_content[:100]}...")
|
||||
return None
|
||||
|
||||
except requests.exceptions.Timeout:
|
||||
gr.Error("請求超時，請稍後重試")
|
||||
return None
|
||||
except Exception as e:
|
||||
import traceback
|
||||
traceback.print_exc()
|
||||
gr.Error(f"發生未知錯誤: {str(e)}")
|
||||
return None
|
||||
|
||||
# Gradio 界面配置
|
||||
with gr.Blocks(title="Nanobanana Image Generator") as app:
|
||||
gr.Markdown("# 🍌 Nanobanana Text/Image to Image")
|
||||
gr.Markdown("基於 Gemini-2.5-Flash-Image 模型，支持文生圖與圖生圖。")
|
||||
|
||||
with gr.Row():
|
||||
with gr.Column():
|
||||
prompt_input = gr.Textbox(
|
||||
label="提示詞 (Prompt)",
|
||||
placeholder="例如: A cyberpunk cat holding a neon sign...",
|
||||
lines=3
|
||||
)
|
||||
image_input = gr.Image(
|
||||
label="參考圖 (可選，用於圖生圖)",
|
||||
type="pil",
|
||||
height=300
|
||||
)
|
||||
submit_btn = gr.Button("開始生成", variant="primary")
|
||||
|
||||
with gr.Column():
|
||||
image_output = gr.Image(label="生成結果", format="png")
|
||||
|
||||
submit_btn.click(
|
||||
fn=synthesize,
|
||||
inputs=[prompt_input, image_input],
|
||||
outputs=image_output
|
||||
)
|
||||
|
||||
if __name__ == "__main__":
|
||||
app.launch(share=True)
|
||||
```
|
||||
|
||||
當 Trae 提示運行成功後，點擊它提供的本地鏈接（通常是 http://127.0.0.1:7860）。
|
||||
|
||||
|
||||
|
||||
如果一切正常，你會看到一個已經可以工作的 AI 繪圖界面。
|
||||
|
||||
這個界面看起來很簡單，但它已經具備了商業級繪圖工具中最核心的兩項能力，即文生圖和圖生圖。
|
||||
|
||||
* **左側：** **指令區 (** **Input** Zone) —— 你在這裡發號施令。
|
||||
* **Prompt (提示詞框)：** 輸入你的創意描述（推薦使用英文）。
|
||||
* **Input** Image (參考圖框)：
|
||||
* **文生圖模式：** 保持此處 **為空** 。
|
||||
* **圖生圖模式：** 將本地圖片拖入此處，AI 會以它為基礎進行創作。
|
||||
* **Submit 按鈕：** 點擊即可發送指令，開始生成。
|
||||
* **右側：展示區 (** **Output** Zone) —— 見證奇蹟的地方，生成結果將在此顯示。
|
||||
|
||||
|
||||
|
||||
現在我們可以嘗試生成你的第一張圖片了！
|
||||
|
||||
本示例使用的 prompt 如下：
|
||||
|
||||
> **A red apple**
|
||||
|
||||
這是一個刻意簡化的示例，不包含任何風格或參數描述。
|
||||
|
||||
#### 實際流程
|
||||
|
||||
運行程式碼後，流程可以概括為三步：
|
||||
|
||||
1. 將文字描述發送給模型
|
||||
2. 模型生成對應圖片
|
||||
3. 圖片被保存為本地文件
|
||||
|
||||
幾秒鐘後，你會在本地看到生成結果。而模型生成具有隨機性，所以相同的prompt會有不同的生成結果，你可以多次生成，選擇你心儀的圖片。
|
||||
|
||||
|
||||
|
||||
也可以豐富你的提示詞，給予它更多的描述和限定。例如以下提示詞，得到的圖片就會更加特殊一些。
|
||||
|
||||
```Plain
|
||||
"A hyper-realistic close-up of a fresh red apple with water droplets on its skin, sitting on a dark rustic wooden table. Cinematic dramatic lighting, rim light, shallow depth of field, bokeh background, 8k resolution, macro photography."
|
||||
(一個超寫實的帶水珠的新鮮紅蘋果特寫，放在深色粗糙木桌上。電影級戲劇光效，輪廓光，淺景深，背景虛化，8k分辨率，微距攝影。)
|
||||
```
|
||||
|
||||
|
||||
|
||||
在Output Image區域點擊下載圖片即可保存到本地。
|
||||
|
||||
|
||||
|
||||
### 1.3 生圖模型常見的素材生成場景
|
||||
|
||||
在實際工作中，大模型生成圖片更多用於 **高效產出設計素材** ，而不是創作單張藝術作品。
|
||||
|
||||
當你觀察一些設計類營銷賬號的高贊案例時會發現，它們的產出大多集中在兩類場景：
|
||||
|
||||
* **文生圖（從 0 到 1）**
|
||||
* **有圖參考生圖（從 1 到 N）**
|
||||
|
||||
#### 一、文生圖：快速獲取設計物料
|
||||
|
||||
這一類場景關注效率。當需要填補設計中的空白（如空狀態、頭像、配圖）時，AI 本質上充當的是一個 **即時生成的圖庫** 。
|
||||
|
||||
1. ##### 生成 UI 設計物料
|
||||
|
||||
* 流行趨勢：Dribbble 上常見的毛玻璃、黏土風 3D 圖標
|
||||
* 常見表現：通透材質、邊緣發光、糖果配色的功能或天氣圖標
|
||||
|
||||
**示例 Prompt：**
|
||||
|
||||
> A set of 3D weather icons (sun, cloud, rain), glassmorphism style, frosted glass texture, soft pastel gradient colors, soft studio lighting, isometric view, transparent background, 4k.
|
||||
|
||||
（一套 3D 天氣圖標，毛玻璃風格，磨砂質感，柔和漸變色，影棚光，等軸視圖）
|
||||
|
||||
|
||||
|
||||
2. ##### 生成 Logo
|
||||
|
||||
* 流行趨勢：極簡線條、幾何組合的科技感 Logo
|
||||
* 常見表現：黑白配色、負空間設計、品牌感明確
|
||||
|
||||
**示例 Prompt：**
|
||||
|
||||
> Minimalist vector logo design for a tech brand "Coffee Code", combining a coffee cup with coding brackets < >, flat design, solid black lines, white background, Paul Rand style, svg.
|
||||
|
||||
（極簡矢量 Logo，結合咖啡杯與程式碼符號，扁平設計，純黑線條）
|
||||
|
||||
|
||||
|
||||
3. ##### 生成官網用戶圖片
|
||||
|
||||
* 流行趨勢：SaaS 官網常用 3D 虛擬頭像，用於規避真人版權
|
||||
* 常見表現：友好表情、卡通比例、偏 Pixar 或 Memoji 風格
|
||||
|
||||
**示例 Prompt：**
|
||||
|
||||
> Close-up portrait of a friendly young tech professional, smiling, Memoji 3D style, clay render, bright colors, soft lighting, solid plain background, Pixar character design.
|
||||
|
||||
（友好的年輕科技從業者，3D Memoji 風格，黏土渲染）
|
||||
|
||||
|
||||
|
||||
4. ##### 生成文章配圖
|
||||
|
||||
* 流行趨勢：科技公司博客中常見的抽象扁平插畫
|
||||
* 常見表現：紫藍配色、誇張人物比例、漂浮 UI 元素
|
||||
|
||||
**示例 Prompt：**
|
||||
|
||||
> Editorial flat illustration representing remote work, a person sitting on a giant globe using a laptop, corporate memphis art style, vibrant colors (purple and teal), vector texture.
|
||||
|
||||
（遠程辦公主題扁平插畫，企業孟菲斯風格）
|
||||
|
||||
|
||||
|
||||
#### 二、有圖參考生圖：保持視覺一致性
|
||||
|
||||
這一類場景更關注 **擴展性** 。當你已經有一張滿意的主視覺，需要生成一整套風格一致的素材時使用。
|
||||
|
||||
5. ##### 主視覺相似的一套按鈕或交互素材圖
|
||||
|
||||
在遊戲開發中，UI 的一致性非常關鍵。假設你已經有了主界面的 **“PLAY”** 按鈕，現在需要擴展出一整套風格統一的功能按鈕（如暫停、設置、主頁）。僅靠手繪很難保證每個按鈕在光澤、透視和色值上的完全一致。
|
||||
|
||||
**基本操作流程：**
|
||||
|
||||
1. 保存已有的藍色 “PLAY” 按鈕圖片
|
||||
|
||||
|
||||
|
||||
2. 將其拖入界面的 **Input**** Image** 區域，作為後續生成的參考母版
|
||||
3. 保持 prompt 中的風格描述不變，僅修改主體內容
|
||||
|
||||
在這一流程下，只要替換主體描述，就可以得到不同功能但風格一致的按鈕。
|
||||
|
||||
**示例 Prompt：**
|
||||
|
||||
**變體 A：暫停按鈕（圖標類）**
|
||||
|
||||
> A capsule-shaped game UI button with a white pause icon (two vertical bars) inside. Same glossy blue jelly style, shiny plastic texture, white thick outline, vector illustration, high quality.
|
||||
|
||||
（膠囊形遊戲 UI 按鈕，白色暫停圖標，藍色果凍質感）
|
||||
|
||||
|
||||
|
||||
**變體 B：設置按鈕（複雜圖標）**
|
||||
|
||||
> A capsule-shaped game UI button with a white gear icon (settings symbol) inside. Same glossy blue jelly style, shiny plastic texture, white thick outline, vector illustration, high quality.
|
||||
|
||||
（膠囊形遊戲 UI 按鈕，白色齒輪圖標，藍色果凍質感）
|
||||
|
||||
|
||||
|
||||
**變體 C：重玩按鈕（形狀變化）**
|
||||
|
||||
如果需要調整按鈕外形，可以在 prompt 中直接描述形狀，模型會在保留材質特徵的同時嘗試改變結構。
|
||||
|
||||
> A round game UI button with a white circular arrow icon (replay symbol) inside. Same glossy blue jelly style, shiny plastic texture, white thick outline, vector illustration, high quality.
|
||||
|
||||
（圓形遊戲 UI 按鈕，循環箭頭圖標，藍色果凍質感）
|
||||
|
||||
|
||||
|
||||
通過這一組操作，你不僅可以替換按鈕功能和圖標，甚至改變按鈕形狀，但所有生成結果在材質、配色和光影上仍保持高度一致。這正是大模型在設計素材裂變場景中的核心價值。
|
||||
|
||||
## 第 2 章：更聽話的圖像生成助手 —— 以 Lovart 為例
|
||||
|
||||
在第一部分，我們通過程式碼直接調用 NanoBanana，體驗了“輸入即生成”的基礎流程。這種方式在需求簡單時沒有問題。但當生成任務開始包含更多約束，例如：
|
||||
|
||||
* 需要多張風格一致的圖片
|
||||
* 需要在已有結果上反覆調整
|
||||
* 需要根據用戶輸入動態修改生成方向
|
||||
|
||||
單次調用的方式就會逐漸變得不夠用。
|
||||
|
||||
這時，就需要引入 **AI Agent（** **智能體** **）** 。本節以 **Lovart** 為例，展示當圖像生成模型具備“思考層”後，整體工作流會發生怎樣的變化。注意！這裡不是打廣告，只是幫助大家快速get到AI Agent的便捷性～
|
||||
|
||||
### 2.0 初識 Lovart：你的 AI 設計代理
|
||||
|
||||
Lovart 是一個基於 Agent 的設計工具 Web。相比普通生圖工具，它在生成之前多了一層“思考與規劃”。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
進入 Lovart 後，主要需要了解以下幾個控制項：
|
||||
|
||||
#### 模型選擇
|
||||
|
||||
點擊輸入框下方的立方體圖標，可以查看當前可用的生成模型（如 GPT Image、Flux 等）。
|
||||
|
||||
為了與前文示例保持一致，本節仍然使用 NanoBanana 作為底層生成模型。
|
||||
|
||||
|
||||
|
||||
#### 思考模式
|
||||
|
||||
這是 Lovart 的核心開關：
|
||||
|
||||
* **Fast Mode（⚡）** ：接近原生 API，響應快，適合單張、明確指令的生成
|
||||
* **Thinking Mode（💡）** ：Agent 模式，AI 會先拆解需求、改寫 prompt，再執行生成
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
#### 聯網能力
|
||||
|
||||
開啟地球圖標後，Agent 可以在生成過程中檢索網路資訊（例如設計趨勢、配色風格），作為輔助輸入。
|
||||
|
||||
### 2.1 為什麼原生 API 還不夠？
|
||||
|
||||
即使已經可以通過 Python 生成質量不錯的圖片，原生 API 在複雜任務中仍然存在限制。關鍵原因在於：原生 API 本質上是指令式的。當你要求它生成一個具體對象時，它可以直接執行；但當輸入變成“策劃一套完整的遊戲素材”時，它並不會主動將目標拆解為多個可執行步驟。
|
||||
|
||||
Lovart 的核心差異在於 Agent 機制。在用戶輸入與圖像生成模型之間，它加入了一層用於理解和規劃的邏輯：先識別用戶意圖，再拆解任務、重寫 prompt，最後才執行生成。
|
||||
|
||||
### 2.2 實戰演示：5 分鐘打造一套 IP 表情包
|
||||
|
||||
以 **“製作一套程序員鴨子 ****IP**** 表情包”** 為例，看看 Agent 是如何參與整個流程的。
|
||||
|
||||
#### 環節一：策劃（Agent 的思考能力）
|
||||
|
||||
**原生 ****API**** 的問題：**
|
||||
你需要自己思考角色設定、情緒狀態，併為每一張圖單獨編寫 prompt。
|
||||
|
||||
**Lovart 的做法：**
|
||||
|
||||
1. 點亮 💡 **Thinking Mode**
|
||||
2. 輸入一句指令：
|
||||
|
||||
> 設計一套程序員鴨子的 IP 表情包，風格要扁平化、可愛
|
||||
|
||||
AI 不會立即畫圖，而是先去網路上搜索相關的程序員鴨子的設計圖。輸出一份拆解後的方案，自動生成 Debug、Coffee Break、Panic 等場景，並對應生成多條視覺描述。
|
||||
|
||||
|
||||
|
||||
這一步，AI 從“執行者”轉變為“策劃者”。在AI幫你分析完需求後，可以在Lovart的畫布區看到多種風格和內容的程序員鴨子圖片。可以開始篩選你喜歡的風格。
|
||||
|
||||
|
||||
|
||||
#### 環節二：一致性（基於參考的視覺錨定）
|
||||
|
||||
Lovart 中的圖片不僅是結果，也參與後續生成。
|
||||
|
||||
##### 完整參考圖
|
||||
|
||||
* 從草圖中選出一張最滿意的“標準鴨子”，在畫布區點擊對應圖片
|
||||
* 該圖將會自動出現在對話區，作為 Reference
|
||||
|
||||
|
||||
|
||||
* 輸入新的動作（如開心）並生成
|
||||
|
||||
生成結果會繼承母版的配色、比例和細節。
|
||||
|
||||
|
||||
|
||||
##### 局部參考 / 多圖整合
|
||||
|
||||
除了整張圖片作為參考，Lovart 還支持：
|
||||
|
||||
* **只選取圖片的局部區域** （例如只參考帽子或表情）
|
||||
|
||||
點擊畫布區左側tab欄，選擇「Mark」鍵，在目標圖像的局部區域標記即可，這部分內容會自動同步到對話框。比如在這裡我們可以選擇修改背景的顏色。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
能看到新生成的圖片只改變了背景的顏色，這也跟我們輸入的要求一致。
|
||||
|
||||
* **從多張圖片中分別引用子元素** ，再組合生成新結果
|
||||
|
||||
例如：你可以保留 A 圖的角色主體，同時只替換帽子為 B 圖中的樣式，Agent 會在後臺自動整合這些視覺約束。
|
||||
|
||||
以程序員鴨子為例，我們可以選擇保留第一個圖中的鴨子形象，並將其替換到第二張圖中作為主體元素。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
最後的效果也非常顯著。你也可以試著其他的組合！
|
||||
|
||||
#### 環節三：落地（Agent 的工具調用）
|
||||
|
||||
生成完成後，可以直接執行：放大、移除背景、擦除等操作
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
這些並不是簡單濾鏡，而是 Agent 自動調度不同工具完成的結果。
|
||||
|
||||
而在確定完基調風格後，可以很快速的生成一系列的表情包圖像。
|
||||
|
||||
|
||||
|
||||
最終我們得到的是可直接交付的生產級素材，而不僅是一張展示圖。
|
||||
|
||||
### 2.3 使用與收費方式說明
|
||||
|
||||
Lovart 採用訂閱制收費模式，不同套餐對應不同的使用額度與功能權限，具體以官網展示為準。
|
||||
|
||||
本教程不對任何套餐做推薦或比較；如果在實際使用中有需求，可以根據個人情況選擇付費升級。
|
||||
目前支持通過**支付寶**等方式完成支付。
|
||||
|
||||
|
||||
|
||||
#### 小結
|
||||
|
||||
Lovart 並不是替代底層模型，而是通過 Agent 機制，讓圖像生成從“單次執行”升級為“連續工作流”。
|
||||
|
||||
當任務開始涉及策劃、一致性和交付時，這類工具的優勢會變得非常明顯。
|
||||
|
||||
## 第 3 章：自己動手做一個智能繪圖助手
|
||||
|
||||
除了直接使用 Lovart，我們也可以自己實現一個簡化版的繪圖助手。
|
||||
|
||||
本章以“文章自動配圖”為例，從實際問題出發，逐步搭建一個帶有思考能力的 Agent。
|
||||
|
||||
### 3.1 痛點引入：為什麼直接發文章給畫圖模型沒用？
|
||||
|
||||
直接將一篇較長的文章輸入給 NanoBanana 並要求配圖，通常很難得到理想結果。原因並不在於模型“畫得不行”，而在於 **它並不擅長理解長文本** 。
|
||||
|
||||
圖像生成模型更適合處理簡短、明確的視覺描述，而當輸入變成一段包含結構、重點和上下文關係的文章時，模型無法判斷哪些內容才是畫面中真正需要表達的部分。這往往會導致生成結果偏離主題，或只能捕捉到零散細節，缺乏整體概括能力。
|
||||
|
||||
本質上，圖像模型只有“執行”的能力，卻缺少對文本進行分析和取捨的過程。
|
||||
|
||||
|
||||
|
||||
### 3.2 解決思路：用 Agent 把「理解」和「執行」拆開
|
||||
|
||||
要解決這個問題，關鍵並不是更復雜的提示詞，而是 **在繪圖之前先把事情想清楚** 。因此，我們在生成流程中引入一個獨立的「思考層」，並以此構建一個最簡單可用的 Agent。
|
||||
|
||||
這個 Agent 的核心目標只有一個：**讓最終生成的圖片，儘可能貼近用戶真正的表達意圖。**
|
||||
|
||||
整體流程可以概括為：**長文本輸入 → 語言模型理解與判斷 → 生成合適的視覺提示詞 → 圖像模型執行生成 → 輸出圖片**
|
||||
|
||||
|
||||
|
||||
那我們構建的 Agent 怎樣才能明白用戶的意圖呢？
|
||||
|
||||
這裡選擇做一個簡化的 **“思考層”** ，我們設置了三種不同的意圖：無效輸入、直接生圖、需要理解的長文本。
|
||||
|
||||
在這個 Agent 中，各個角色的分工可以概括為四點：
|
||||
|
||||
1. **語言模型作為決策核心**
|
||||
它負責理解文章內容、判斷用戶輸入的意圖，並將任務分發到合適的生成路徑中，決定接下來“該怎麼做”以及如何生成生圖提示詞。
|
||||
2. **圖像模型作為執行者**
|
||||
圖像模型不參與理解與判斷，只接收已經整理好的視覺指令，專注完成圖像渲染。
|
||||
3. **用戶作為可介入的引導者**
|
||||
除了直接輸入文本，用戶還可以在過程中手動調整生成的提示詞，或加入參考圖來輔助生成，從而對最終結果進行引導和微調。
|
||||
4. **Gradio 與後端 ****API**** 作為整體承載層**
|
||||
它們負責將界面、模型調用和結果展示串聯起來，保證整個 Agent 能夠以一個完整 Web 應用的形式穩定運行。
|
||||
|
||||
|
||||
|
||||
### 3.3 實戰準備 ：獲取API
|
||||
|
||||
看起來是不是很有趣呢！要跑通上述流程，我們只需要準備兩類 API。
|
||||
|
||||
#### 手：NanoBanana API（圖像生成）
|
||||
|
||||
直接沿用第 1 章中已經配置好的 API Key 和 API URL，無需額外設置。
|
||||
|
||||
#### 腦：SiliconFlow API（文本思考）
|
||||
|
||||
我們需要一個大語言模型來承擔“思考層”的職責。本教程使用 SiliconFlow 提供的模型服務：[https://cloud.siliconflow.cn](https://cloud.siliconflow.cn/)
|
||||
|
||||
|
||||
|
||||
SiliconFlow 提供了兼容 OpenAI API 規範的接口，可以非常方便地在項目中通過標準網路請求進行調用。在這裡我們選擇的是免費的Qwen2.5-7B-Instruct模型，調用需要的內容都已經寫入下面的Prompt。在開始之前，你只需要在官網註冊賬號並創建一個 API Key。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
該 Key 將用於後續的模型調用。
|
||||
|
||||
### 3.4 搭建Agent ：
|
||||
|
||||
本次實驗主要使用Trae來幫我們編寫程式碼，本教程選用的是Gemini-3-Pro-Preview模型。總思路是，新建項目後將下述完整 Prompt 複製到對話框並輸入，逐步替換 API KEY 後運行程式碼，完成測試即可。
|
||||
|
||||
|
||||
|
||||
#### 環節1️⃣：Gradio Blocks 基礎框架與界面佈局
|
||||
|
||||
在這個環節，我們的主要目標是先給整個Agent搭建出一個“外觀”，實現前端的頁面設計。複製以下Prompt在Trae對話框中實現後，你將會得到一個本地的URL（通常是 http://127.0.0.1:7860 ）即可查看界面，並且檢驗實現效果。
|
||||
|
||||
```Plain
|
||||
板塊 1：Gradio Blocks 基礎框架與界面佈局
|
||||
1、任務目標
|
||||
·基於 Gradio 4.0.0+ 的 Blocks 佈局，實現「LLM+Nanobanana 文生圖」項目的基礎界面，嚴格遵循固定左右分欄佈局，初始化所有 UI 組件並設置正確的初始狀態。
|
||||
|
||||
2、技術棧要求
|
||||
·必須使用 Gradio 4.0.0+ 的 Blocks 模式開發，禁止使用 Interface 模式；
|
||||
·依賴：gradio>=4.0.0，pillow>=10.0.0（僅導入，暫不實現圖片處理邏輯）；
|
||||
·程式碼需是完整可運行的 Python 文件，包含所有必要的導入語句。
|
||||
|
||||
3、界面佈局規則（核心約束，融合實戰細節）
|
||||
·整體佈局：
|
||||
頁面標題：LLM 驅動的文生圖全流程工具；
|
||||
固定左右分欄：左側佔 60% 寬度，右側佔 40% 寬度，使用 gr.Row 和 gr.Column 實現比例控制。
|
||||
·左側 60%（提示詞生成流程區）組件清單：
|
||||
input_text：gr.Textbox，標籤「輸入文本（教程段落 / 繪圖指令）」，lines=6，佔位符「請輸入需要配圖的教程文本或直接繪圖指令...」；
|
||||
identify_intent_btn：gr.Button，value="識別意圖"，初始狀態正常可點擊；
|
||||
intent_status：gr.Textbox，標籤「意圖類型 / 處理狀態」，lines=2，interactive=False，初始值「未識別意圖」；
|
||||
system_prompt：gr.Textbox，標籤「System Prompt（僅文章配圖意圖可編輯）」，lines=4，interactive=False，佔位符「LLM 生成提示詞的約束規則...」；
|
||||
confirm_prompt_btn：gr.Button，value="確認生成生圖提示詞"，interactive=False（初始禁用防誤觸）；
|
||||
generation_prompt：gr.Textbox，標籤「生圖提示詞（可編輯）」，lines=3，interactive=True，初始值為空，佔位符「生成的英文生圖提示詞將顯示在此，支持手動修改...」。
|
||||
·右側 40%（Nanobanana 生圖功能區）組件清單：
|
||||
ref_image：gr.Image，標籤「參考圖（可選，圖生圖）」，type=filepath，height=300，允許上傳；
|
||||
generate_btn：gr.Button，value="生成圖片"，interactive=False（初始禁用，無提示詞不可點擊）；
|
||||
result_image：gr.Image，標籤「生成結果」，type=pil，height=300，初始為空，interactive=False。
|
||||
|
||||
4、交互邏輯要求
|
||||
·所有組件的 interactive 初始狀態嚴格按上述配置，後續通過函數動態更新；
|
||||
·按鈕禁用狀態需直觀（置灰），避免用戶誤操作。
|
||||
|
||||
5、輸出要求
|
||||
·生成完整的 Python 程式碼，僅實現界面佈局和組件初始化，不包含任何業務邏輯；
|
||||
·程式碼註釋清晰，組件命名與實戰版一致（input_text/identify_intent_btn 等）；
|
||||
·程式碼可直接運行，界面結構與描述完全一致。
|
||||
```
|
||||
|
||||
在瀏覽器打開http://127.0.0.1:7860後可看到Trae已經按照我們的要求生成了以下的網頁，跟我們的要求大致相當，可以進行到下一步的生成中了。
|
||||
|
||||
|
||||
|
||||
#### 環節2️⃣：LLM 意圖識別模塊（Siliconflow API）
|
||||
|
||||
在日常使用VLM畫圖的時候，可能有以下三種常見輸入情況：
|
||||
|
||||
1. 無意義內容，比如“你好”、“你今天吃飯了嗎”等，無法畫出對應的圖片。
|
||||
2. 文章/長文本，字數較多，比如200字左右的一篇有結構的文章，需要先理解文章的結構與內容，再考慮如何生成能完整概括這段文字的圖片。
|
||||
3. 直接繪圖指令，比如“幫我畫一隻在洗澡的狗”等，要求已經闡述的非常具體，可以直接生成圖片。
|
||||
|
||||
跟前面一樣，複製以下Prompt在Trae對話框中實現，並且補充在前面步驟中獲得的API。
|
||||
|
||||
```Plain
|
||||
板塊 2：LLM 意圖識別模塊（Siliconflow API）
|
||||
1、任務目標
|
||||
在已實現的 Gradio 界面基礎上，為「識別意圖」按鈕添加點擊邏輯，調用 Siliconflow API 完成意圖識別，並聯動組件狀態。
|
||||
|
||||
2、技術棧要求
|
||||
基於 Gradio 4.0.0+ Blocks；
|
||||
依賴：requests>=2.31.0，openai；
|
||||
輸出完整可運行 Python 文件，包含板塊 1 界面 + 本模塊邏輯。
|
||||
|
||||
3、核心業務規則（絕對不可偏離）
|
||||
·意圖分類規則（僅 3 類，嚴格返回數字 + 描述）
|
||||
1 = 無意義內容：僅閒聊、寒暄、無關對話，沒有任何繪圖或配圖需求（如 “你好”“今天吃了嗎”）；
|
||||
2 = 文章 / 長文本配圖需求：用戶輸入一段完整文章、教程、段落、說明性文字，內容偏敘事 / 說明 / 講解，隱含需要為這段內容生成配圖的意圖，不需要用戶明確說 “為這段文字配圖”；
|
||||
3 = 直接繪圖指令：用戶輸入簡短、明確的畫圖命令，沒有長文本背景，直接要求畫某個內容（如 “畫一隻 Apple 風格的貓”）。
|
||||
·LLM 調用約束（融合實戰版模板）
|
||||
接口地址：https://api.siliconflow.cn/v1/chat/completions；
|
||||
模型：Qwen/Qwen2.5-7B-Instruct；
|
||||
temperature=0.1；
|
||||
統一定義程式碼：
|
||||
python
|
||||
運行
|
||||
LLM_BASE_URL = "https://api.siliconflow.cn/v1"
|
||||
LLM_API_KEY = "" # 用戶自行替換
|
||||
LLM_MODEL = "Qwen/Qwen2.5-7B-Instruct"# 實戰驗證的意圖識別模板（固化到程式碼中）
|
||||
INTENT_PROMPT_TEMPLATE = """你需要識別用戶輸入文本的意圖，僅返回以下 3 類結果中的一種（格式：數字 + 中文描述）：
|
||||
1 = 無意義內容；2 = 文章 / 長文本配圖需求；3 = 直接繪圖指令。
|
||||
|
||||
用戶輸入：{user_input}
|
||||
|
||||
識別結果：
|
||||
僅提取返回結果中的數字和描述，禁止額外內容。"""
|
||||
|
||||
4、組件聯動規則
|
||||
·結果為 1：intent_status 顯示「1 = 無意義內容：無繪圖需求」，system_prompt 保持禁用，confirm_prompt_btn 禁用；
|
||||
·結果為 2：intent_status 顯示「2 = 文章 / 長文本配圖需求：為輸入內容生成配圖」，啟用 system_prompt 並填充默認規則，激活 confirm_prompt_btn；
|
||||
·結果為 3：intent_status 顯示「3 = 直接繪圖指令：根據指令生成圖片」，system_prompt 禁用且填充默認規則，激活 confirm_prompt_btn。
|
||||
|
||||
5、異常處理
|
||||
API 異常、解析異常均給出友好提示，不崩潰，組件恢復初始狀態。
|
||||
|
||||
6、輸出要求
|
||||
生成完整可運行程式碼，替換 LLM_API_KEY 即可使用，邏輯清晰註釋完整，意圖識別模板嚴格使用實戰版。
|
||||
```
|
||||
|
||||
刷新之前的http://127.0.0.1:7860網址，開始測試是否能正確檢測三種情況。
|
||||
|
||||
1. 無意義內容，可以嘗試輸入“你好”、“謝謝”等，發現能夠正常識別。
|
||||
|
||||
|
||||
|
||||
2. 文章/長文本，在這裡我們選用了一段豆包生成的描述人工智能的文字。你也可以嘗試使用自己的論文段落進行測試。
|
||||
|
||||
```Plain
|
||||
人工智能正在以前所未有的深度和廣度重塑教育生態系統。通過自適應學習算法，AI系統能夠構建每個學生的認知圖譜，實時追蹤他們的知識掌握軌跡，並動態調整教學內容的難度和呈現方式。在傳統課堂環境中，教師往往難以同時滿足不同學習風格和能力水平的學生需求，而基於深度學習的教育平臺可以分析學生在交互式模擬實驗中的行為模式，識別他們在量子力學或微積分等複雜概念理解上的微妙障礙，並提供精準的認知支架。
|
||||
|
||||
高級自然語言處理引擎驅動的虛擬導師不僅能夠解構開放性問題，如"如何評價法國大革命對現代民主制度的影響"，還能引導蘇格拉底式對話，激發批判性思維。當學生撰寫關於氣候變化對極地生態系統影響的論文時，AI寫作助手可以分析其論證邏輯的嚴密性，指出資料引用中的時效性問題，並建議更精準的科學術語。在特殊教育領域，計算機視覺技術使AI能夠識別自閉症譜系兒童在社交互動中的非語言線索，調整干預策略，而情感計算算法則幫助檢測在線學習時的挫折感，及時提供鼓勵性反饋。
|
||||
|
||||
然而，這種技術融合引發了一系列倫理困境。算法偏見可能無意中邊緣化特定文化背景的學生，資料採集的透明度問題引發了對學術隱私的關切，而過度依賴自動化評分系統可能削弱教師對學生思維過程的深層理解。更復雜的是，當AI開始生成高度逼真的虛擬實驗室體驗時，我們需要重新定義"實踐經驗"在教育中的價值。未來教育的範式可能演變為人類教師專注於培養創造力、同理心和道德判斷力，而AI系統則承擔知識傳遞、技能訓練和個性化評估的職能，形成一種協同進化的教育共生體，既能發揮機器的計算優勢，又能保留人類教育的獨特溫度.
|
||||
```
|
||||
|
||||
同樣檢測成功～
|
||||
|
||||
|
||||
|
||||
3. 直接繪圖指令，這裡輸入的是“我要畫一隻貓”，同樣檢測準確。
|
||||
|
||||
|
||||
|
||||
到這裡我們就已經順利實現了第二個環節——意圖識別。
|
||||
|
||||
#### 環節3️⃣：生圖提示詞生成模塊（LLM 二次調用）
|
||||
|
||||
意圖識別後，對於文章或長文本，還有很重要的一步就是生成畫圖的提示詞，而這正是本Agent的重點。
|
||||
|
||||
```SQL
|
||||
板塊 3：生圖提示詞生成模塊（LLM 二次調用）
|
||||
1、任務目標
|
||||
在意圖識別基礎上，實現「確認生成生圖提示詞」按鈕邏輯，調用 LLM 將文本優化為適合繪圖的英文視覺提示詞，填充到編輯框並聯動「生成圖片」按鈕。
|
||||
|
||||
2、技術棧要求
|
||||
同板塊 2，輸出完整程式碼 = 板塊 1 + 板塊 2 + 本模塊；
|
||||
共用板塊 2 定義的 LLM_BASE_URL、LLM_API_KEY、LLM_MODEL，不新增密鑰。
|
||||
|
||||
3、核心業務規則（融合實戰版 Prompt 組裝邏輯）
|
||||
·提示詞生成輸入規則（必須嚴格遵循）
|
||||
生圖提示詞生成不再是簡單字符串拼接，而是構建標準 Chat 消息列表，程式碼結構如下：
|
||||
python
|
||||
運行
|
||||
messages=[# System角色：網頁上用戶最終確認/編輯後的system_prompt內容{"role": "system", "content": final_system_prompt},# User角色：承載待處理資料，明確任務目標{"role": "user", "content": f"請為以下內容生成視覺提示詞：\n\n{user_input}"}]
|
||||
意圖為 2 時：System 內容取用戶編輯後的 system_prompt 最終版本；
|
||||
意圖為 3 時：System 內容取禁用狀態下填充的默認規則
|
||||
user_input 為用戶最初輸入到 input_text 框的原始文本。
|
||||
·實戰驗證的 System Prompt 預設（固化到程式碼中）
|
||||
python
|
||||
運行
|
||||
SYSTEM_PROMPT_DEFAULT = """你現在是一個創建NanoBanana畫圖提示詞的助手。
|
||||
需要根據我的內容處理，我這個圖片的作用是能說明這一段在說什麼，並且讓大家知道這段話的上下結構就是整體說的是什麼意思。
|
||||
裡面可能會類似PPT有一些講解（如：左上角展示核心觀點，右下角展示資料）。
|
||||
設計風格要求：簡約，Apple設計思維（Apple Design Philosophy）。
|
||||
約束：請直接返回NanoBanana可用的英文提示詞，不要返回任何解釋、前綴或多餘的廢話。"""
|
||||
·LLM 調用約束
|
||||
與板塊 2 共用同一套 LLM_BASE_URL、LLM_API_KEY、LLM_MODEL；
|
||||
temperature=0.7（保證提示詞的創意性與適配性）；
|
||||
max_tokens=200（限制輸出長度，匹配提示詞約束）；
|
||||
嚴格使用上述標準 Chat 消息列表結構，禁止字符串拼接。
|
||||
·示例輸入輸出（核心參考）
|
||||
輸入示例 1（文章配圖意圖）：原始文本：「AI 如何改變教育：隨著人工智能技術的發展，教師的角色從知識傳授者轉變為引導者，AI 助手可輔助學生完成個性化學習，課堂上人機協作成為常態。」最終 System Prompt：SYSTEM_PROMPT_DEFAULT（未修改）輸出預期："Minimalist illustration, Apple Design Philosophy, 1024x1024. Top left shows 'AI + Education' core concept, bottom right shows data of teacher-student-AI collaboration, soft color palette, clean lines, no redundant elements."
|
||||
輸入示例 2（直接繪圖指令）：原始文本：「畫一隻 Apple 風格的貓，坐在 MacBook 旁邊」最終 System Prompt：SYSTEM_PROMPT_DEFAULT（禁用狀態）輸出預期："Minimalist cat, Apple style, 1024x1024, sitting next to a silver MacBook, clean white background, soft shadows, geometric shapes, no extra details."
|
||||
·提示詞輸出強制約束
|
||||
純英文，無中文；
|
||||
必須包含 Apple Design Philosophy/Apple style + 1024x1024；
|
||||
長度 50–200 字符，程式碼內校驗；
|
||||
無額外解釋、前綴或廢話，僅返回提示詞本身。
|
||||
|
||||
4、組件聯動規則
|
||||
生成成功：將提示詞填入 generation_prompt 框，激活 generate_btn，intent_status 追加「提示詞生成成功，可修改後生成圖片」；
|
||||
生成失敗：提示具體原因（如 API 調用失敗、長度不達標），generate_btn 保持禁用，generation_prompt 框為空；
|
||||
用戶手動修改 / 清空 generation_prompt 框：
|
||||
清空時自動禁用 generate_btn；
|
||||
非空時保持 generate_btn 激活。
|
||||
|
||||
5、異常處理
|
||||
API 調用失敗：友好提示「提示詞生成失敗：{具體錯誤資訊}」，不崩潰；
|
||||
提示詞校驗失敗：明確提示原因（如 “未包含 Apple style”“長度僅 40 字符”），允許重試；
|
||||
響應解析失敗：提示「無法解析 LLM 返回結果，請重試」。
|
||||
|
||||
6、輸出要求
|
||||
完整可運行程式碼，替換 LLM_API_KEY 即可使用；
|
||||
程式碼結構清晰、註釋完善，界面美觀簡潔；
|
||||
嚴格實現標準 Chat 消息列表結構，參數與示例邏輯一致；
|
||||
包含提示詞長度、內容校驗邏輯，錯誤提示友好。
|
||||
```
|
||||
|
||||
同樣複製第二個環節的文本進行檢測。
|
||||
|
||||
值得注意的是，我們在這裡預設的生成生圖提示詞的System Prompt為：
|
||||
|
||||
> 你現在是一個創建NanoBanana畫圖提示詞的助手。
|
||||
> 需要根據我的內容處理，我這個圖片的作用是能說明這一段在說什麼，並且讓大家知道這段話的上下結構就是整體說的是什麼意思。
|
||||
> 裡面可能會類似PPT有一些講解（如：左上角展示核心觀點，右下角展示資料）。
|
||||
> 設計風格要求：簡約，Apple設計思維（Apple Design Philosophy）。
|
||||
> 約束：請直接返回NanoBanana可用的英文提示詞，不要返回任何解釋、前綴或多餘的廢話。
|
||||
|
||||
如果你想換成其他的預設模版，可以在前面的prompt裡修改，或者直接在Trae裡通過對話修改。
|
||||
|
||||
|
||||
|
||||
除了修改底層程式碼，我們在網頁上也可以快速編輯。舉個例子，我在這裡加了一句，“在前面加一句Pic Prompt”，可以看到生成的新的提示詞前面也包含了～這樣設計是為了方便快速修改生成提示詞的System Prompt，幫助我們快速切換風格。
|
||||
|
||||
|
||||
|
||||
#### 環節4️⃣：Nanobanana 文生圖 / 圖生圖模塊
|
||||
|
||||
終於來到了最後一步，不接入生圖模型，就不是一個完整的Agent！
|
||||
|
||||
```Bash
|
||||
板塊 4：Nanobanana 文生圖 / 圖生圖模塊（最終版）
|
||||
1、任務目標
|
||||
實現「生成圖片」按鈕邏輯，調用真實 Nanobanana API，支持文生圖 / 圖生圖，解析 Base64 並展示圖片。
|
||||
|
||||
2、技術棧要求
|
||||
基於 Gradio 4.0.0+ Blocks；
|
||||
依賴：requests, pillow, base64, io, re；
|
||||
完整程式碼 = 板塊 1+2+3 + 本模塊。
|
||||
|
||||
3、核心 API 配置（實戰驗證固化）
|
||||
固化程式碼配置：
|
||||
python
|
||||
運行
|
||||
# 固化到程式碼中的API配置
|
||||
NANOBANANA_API_URL = "https://api.zyai.online/v1/chat/completions"
|
||||
NANOBANANA_MODEL = "gemini-2.5-flash-image"
|
||||
NANOBANANA_API_KEY = "" # 用戶自行替換
|
||||
鑑權方式：Header Authorization: Bearer {NANOBANANA_API_KEY}。
|
||||
|
||||
4、圖片預處理要求（必須實現）實現函數 image_to_base64_data_uri (ref_image_path)，核心邏輯：
|
||||
將 PIL 圖片轉為 PNG 格式；
|
||||
自動縮放到 1024x1024 分辨率；
|
||||
透明通道轉為白色背景；
|
||||
編碼為 Base64，返回格式：data:image/png;base64,...。
|
||||
|
||||
5、請求構建規則（嚴格按實戰版分支邏輯）
|
||||
·核心函數定義實現函數 generate_image (prompt, ref_image_path)：
|
||||
入參：prompt（generation_prompt 框內容）、ref_image_path（ref_image 上傳的文件路徑）；
|
||||
返回：PIL Image（展示到 result_image）或錯誤提示。
|
||||
·邏輯分支 1：純文生圖（ref_image_path 為空）
|
||||
python
|
||||
運行
|
||||
messages = [{"role": "user", "content": prompt}]
|
||||
·邏輯分支 2：圖生圖（ref_image_path 有值）
|
||||
python
|
||||
運行
|
||||
# 先調用圖片預處理函數
|
||||
image_base64 = image_to_base64_data_uri(ref_image_path)
|
||||
messages = [{"role": "user","content": [{"type": "text", "text": prompt},{"type": "image_url", "image_url": {"url": image_base64}}]}]
|
||||
|
||||
6、響應解析要求（必須兼容兩種格式）從 choices [0].message.content 中提取圖片 Base64，支持：
|
||||
結構化 JSON 返回的 image_url 字段；
|
||||
Markdown 格式
|
||||
；
|
||||
統一提取 Base64 編碼，解碼後轉換為 PIL Image 返回。
|
||||
|
||||
7、組件聯動與異常處理
|
||||
生成成功：將 PIL Image 展示到 result_image，intent_status 提示「圖片生成成功」；
|
||||
生成 / 解析 / 上傳失敗：在 intent_status 顯示清晰文字提示（如 “Base64 解析失敗”“API 調用超時”），不崩潰。
|
||||
|
||||
8、輸出要求
|
||||
完整可運行程式碼，替換 LLM_API_KEY 和 NANOBANANA_API_KEY 即可直接運行，全流程可用，分支邏輯嚴格匹配實戰版。
|
||||
```
|
||||
|
||||
|
||||
|
||||
太令人激動啦！我們終於順利地生成出了這個Agent的第一張圖，仔細看看生成的圖片，跟我們的文本和提示詞是匹配的。到這裡你已經基本上實現你自己的Agent啦！
|
||||
|
||||
|
||||
|
||||
我們還添加了圖生圖功能，上傳你喜歡的圖片，AI會自動借鑑風格。
|
||||
|
||||
|
||||
|
||||
值得一提的是，前面步驟生成的提示詞也是可以在網頁上編輯的，並且我們是以最終點擊按鈕時的提示詞為準～哪怕我在這裡換成“a cute cat”，最終生成的圖片也只會是可愛的小貓。
|
||||
|
||||
## 第 4 章：總結
|
||||
|
||||
|
||||
|
||||
**嗚呼！終於寫完了。**
|
||||
說實話，連我自己寫完最後一行的時候都忍不住長舒一口氣，更別說一路跟著做到這裡的你了。能把這一整套流程完整跑下來，本身就已經很厲害了，這說明你真的把手放到鍵盤上，把事情一步步做完了。Bravo 🎉 🥳 👏
|
||||
|
||||
在寫這套內容的過程中，我一直在想，我們到底要留下些什麼？答案其實並不是模型名字、參數或者某種固定套路，而是讓你慢慢建立起一種感覺：哪些事情可以放心交給 AI 去理解和規劃，哪些地方只需要你來決定方向。一旦這層分工成立，很多原本看起來複雜的生成流程，都會開始變得順起來。
|
||||
|
||||
回頭看，這條路其實並不複雜。想清楚你要解決的問題，把長文本交給語言模型去拆解，再把整理好的視覺意圖交給繪圖模型去呈現，最後把這一整套流程封裝成一個屬於你自己的小助手。到這裡，你已經不只是“在用模型”，而是在搭建一套可以長期陪你工作的系統，而這，才是這套教程最想帶給你的東西。
|
||||
|
||||
但是你已經做的很棒啦！相信學到這裡的你對Vibe Coding已經有初步的掌握了，給自己放個小假休息一下吧！
|
||||
|
||||
<RelatedArticlesSection
|
||||
title="相關文章"
|
||||
description="如果你想把“素材生成”真正接入產品流程，可以繼續學習這些章節。"
|
||||
:items="relatedArticles"
|
||||
/>
|
||||
@@ -0,0 +1,465 @@
|
||||
# 使用現代組件庫更新你的界面
|
||||
|
||||
在前面的課程中，你已經學會了如何用設計工具畫出界面、用 AI IDE 把設計稿變成程式碼，甚至完成了一個完整的前端項目。但你可能也發現了一個問題：自己從零寫出來的按鈕、表單、彈窗，雖然能用，但總覺得和"專業產品"差了點意思——樣式不夠統一、交互細節不夠絲滑、適配不同屏幕也很頭疼。
|
||||
|
||||
這就是**組件庫**要解決的問題。
|
||||
|
||||
組件庫是一套預先設計好、開發好的 UI 零件集合。按鈕、輸入框、下拉菜單、對話框、表格……這些你在任何產品中都會反覆用到的界面元素，組件庫已經幫你做好了，而且經過了大量用戶的驗證和打磨。你只需要像搭積木一樣把它們組合起來，就能快速構建出專業級的界面。
|
||||
|
||||
## 你將學到
|
||||
|
||||
1. 理解什麼是前端組件庫，以及為什麼現代開發幾乎都在用它
|
||||
2. 認識四個最具代表性的組件庫，瞭解它們各自擅長的場景
|
||||
3. 通過三個實戰場景（落地頁、產品頁面、後臺管理），學會用 AI IDE + 組件庫進行 Vibe Coding
|
||||
4. 學會閱讀組件庫文檔，根據需求找到合適的組件並正確使用
|
||||
|
||||
## 1. 為什麼需要組件庫？
|
||||
|
||||
想象你在裝修房子。你可以自己從木頭開始做一把椅子，但更常見的做法是去宜家買一把——設計好看、質量穩定、說明書清晰，拿回家組裝就行。
|
||||
|
||||
組件庫就是前端開發中的"宜家"。它提供的不是傢俱，而是界面零件：
|
||||
|
||||
| 自己手寫 | 使用組件庫 |
|
||||
| :--- | :--- |
|
||||
| 需要自己處理樣式、交互、動畫 | 開箱即用，樣式和交互已經打磨好 |
|
||||
| 不同頁面的按鈕可能長得不一樣 | 全局風格統一，自動保持一致性 |
|
||||
| 適配手機、平板需要額外工作 | 大多數組件庫已內置響應式支持 |
|
||||
| 無障礙訪問（Accessibility）容易遺漏 | 專業組件庫已處理好鍵盤導航、屏幕閱讀器等 |
|
||||
| 開發速度慢 | 開發速度快，專注業務邏輯 |
|
||||
|
||||
簡單來說：**組件庫讓你把時間花在"做什麼"上，而不是"怎麼畫"上。**
|
||||
|
||||
### 眼見為實：同一個需求，加不加組件庫的差距
|
||||
|
||||
光說不練沒有說服力。我們在 Trae 中用幾乎相同的需求，分別不指定和指定組件庫，看看生成結果的差距。
|
||||
|
||||
**提示詞一：不使用組件庫**
|
||||
|
||||
```text
|
||||
請幫我做一個 AI 寫作助手的資料儀表盤頁面，包含：
|
||||
- 頂部標題欄和導出按鈕
|
||||
- 四張統計卡片顯示用戶數、活躍用戶、文檔數、收入，還要顯示漲跌趨勢
|
||||
- 一個折線圖和一個餅圖
|
||||
- 用戶列表表格，帶分頁功能
|
||||
- 左側導航側邊欄
|
||||
```
|
||||
|
||||
在 Trae 中直接運行後的效果：
|
||||
|
||||
<!-- TODO: 替換為 Trae 中不使用組件庫生成的儀表盤截圖 -->
|
||||
<!--  -->
|
||||
|
||||
**提示詞二：使用 shadcn/ui 組件庫**
|
||||
|
||||
```text
|
||||
請幫我做一個 AI 寫作助手的資料儀表盤頁面，用 shadcn/ui 組件庫來做，包含：
|
||||
- 頂部標題欄和導出按鈕
|
||||
- 四張統計卡片顯示用戶數、活躍用戶、文檔數、收入，還要顯示漲跌趨勢
|
||||
- 一個折線圖和一個餅圖
|
||||
- 用戶列表表格，帶分頁功能
|
||||
- 左側導航側邊欄
|
||||
```
|
||||
|
||||
同樣在 Trae 中直接運行後的效果：
|
||||
|
||||
<!-- TODO: 替換為 Trae 中使用 shadcn/ui 生成的儀表盤截圖 -->
|
||||
<!--  -->
|
||||
|
||||
同樣的需求，唯一的區別只是在提示詞開頭加上了 `shadcn/ui + Tailwind CSS`，Trae 生成的結果在視覺一致性、交互細節、整體打磨程度上就完全不在一個層級。這就是組件庫帶來的"免費升級"——你只需要在提示詞裡多寫一個組件庫的名字。
|
||||
|
||||
## 2. 認識四個核心組件庫
|
||||
|
||||
組件庫數量眾多（完整列表見[附錄](#附錄-更多組件庫一覽)），但你只需要先認識這四個最具代表性的：
|
||||
|
||||
| 組件庫 | 框架 | 一句話定位 | 官網 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| [Ant Design](https://ant.design) | React | 螞蟻集團出品，企業級中後臺的事實標準，組件覆蓋面極廣 | ant.design |
|
||||
| [shadcn/ui](https://ui.shadcn.com) | React | 不裝 npm 包，直接把程式碼複製到你項目裡，基於 Tailwind CSS，定製自由度最高 | ui.shadcn.com |
|
||||
| [HeroUI](https://heroui.com)（原 NextUI） | React | 默認樣式精美、動畫流暢，適合對視覺品質有要求的落地頁和產品展示 | heroui.com |
|
||||
| [Material UI](https://mui.com) | React | 最老牌的 React 組件庫，實現 Google Material Design 規範，生態最成熟 | mui.com |
|
||||
|
||||
> Vue 用戶同樣有豐富選擇：[Element Plus](https://element-plus.org)（國內最流行）、[Ant Design Vue](https://antdv.com)、[Naive UI](https://www.naiveui.com) 等，詳見[附錄](#附錄-更多組件庫一覽)。
|
||||
|
||||
不同組件庫擅長不同場景。接下來我們通過三個真實開發場景，帶你體驗如何用 AI IDE + 組件庫進行 Vibe Coding。
|
||||
|
||||
為了展示不同組件庫的風格和特點，我們在每個場景中刻意選用了不同的庫。但請注意：**這只是為了讓你多見識幾種方案**，實際開發中你完全可以只用自己最順手的那一個。比如你喜歡 shadcn/ui 的風格，用它做落地頁、產品頁、後臺管理都沒問題。選一個你覺得好看、用著舒服的，比什麼都重要。
|
||||
|
||||
## 3. 實戰一：用 HeroUI 構建產品落地頁
|
||||
|
||||
**場景**：你做了一個 AI 寫作助手產品，需要一個漂亮的落地頁來展示產品特性、吸引用戶註冊。落地頁需要視覺衝擊力強、動畫流暢、在手機上也好看。
|
||||
|
||||
**為什麼選 HeroUI**：HeroUI 的默認樣式就很精美，自帶流暢的過渡動畫，非常適合面向用戶的展示型頁面。
|
||||
|
||||
### 3.1 創建項目
|
||||
|
||||
```bash
|
||||
# 使用 HeroUI 官方 CLI 創建項目
|
||||
npx create-heroui-app@latest ai-writer-landing
|
||||
cd ai-writer-landing
|
||||
npm install
|
||||
```
|
||||
|
||||
<!-- TODO: 替換為 HeroUI 官網首頁或組件展示截圖 -->
|
||||
<!--  -->
|
||||
|
||||
### 3.2 用 AI IDE 生成落地頁
|
||||
|
||||
打開 AI IDE（Cursor、Trae 等），在對話框中輸入：
|
||||
|
||||
```text
|
||||
請幫我做一個 AI 寫作助手的落地頁，用 HeroUI 組件庫來做：
|
||||
|
||||
**頁面結構：**
|
||||
1. 頂部導航欄：左邊放 Logo 和產品名，右邊放"功能"、"定價"、"關於"三個鏈接，再加一個"開始使用"按鈕
|
||||
2. 首屏區域：大標題寫"讓 AI 成為你的寫作搭檔"，副標題介紹產品價值，兩個按鈕"免費試用"和"查看演示"，下面放一張產品截圖
|
||||
3. 功能展示：三列卡片，分別介紹"智能續寫"、"風格調整"、"多語言翻譯"三個功能，每張卡片要有圖標、標題、描述
|
||||
4. 定價區域：三個定價卡片（免費版、專業版、團隊版），專業版要突出顯示推薦
|
||||
5. 底部號召：一句吸引人的文案，加上註冊按鈕
|
||||
6. 頁腳：版權資訊和社交媒體鏈接
|
||||
|
||||
**設計要求：**
|
||||
- 看起來要現代、專業
|
||||
- 支持暗色模式
|
||||
- 手機上看也要好看
|
||||
```
|
||||
|
||||
<!-- TODO: 替換為 AI IDE 生成落地頁的過程截圖或生成結果截圖 -->
|
||||
<!--  -->
|
||||
|
||||
### 3.3 AI 會用到的關鍵組件
|
||||
|
||||
AI 生成的程式碼中，你會看到這些 HeroUI 組件：
|
||||
|
||||
```jsx
|
||||
import {
|
||||
Navbar, NavbarBrand, NavbarContent, NavbarItem,
|
||||
Button,
|
||||
Card, CardHeader, CardBody, CardFooter,
|
||||
Divider,
|
||||
Link,
|
||||
Chip
|
||||
} from '@heroui/react'
|
||||
```
|
||||
|
||||
每個組件的作用：
|
||||
|
||||
| 組件 | 用途 | 落地頁中的位置 |
|
||||
| :--- | :--- | :--- |
|
||||
| `Navbar` | 頂部導航欄 | 頁面最頂部，固定不動 |
|
||||
| `Button` | 按鈕，支持多種變體和顏色 | CTA 按鈕、導航按鈕 |
|
||||
| `Card` | 卡片容器 | 功能展示、定價卡片 |
|
||||
| `Chip` | 小標籤 | "推薦"、"最受歡迎"標記 |
|
||||
| `Divider` | 分割線 | 區域之間的視覺分隔 |
|
||||
|
||||
### 3.4 迭代優化
|
||||
|
||||
生成的初版程式碼可能不完全滿意，繼續和 AI 對話調整：
|
||||
|
||||
```text
|
||||
請幫我優化一下落地頁：
|
||||
|
||||
1. 大標題加上漸變色，從藍色漸變到紫色
|
||||
2. 功能卡片鼠標放上去要有上浮的動畫效果
|
||||
3. 專業版定價卡片要突出顯示，加個邊框和"最受歡迎"的標籤
|
||||
4. 手機上的導航改成漢堡菜單（三條橫線那種）
|
||||
```
|
||||
|
||||
<!-- TODO: 替換為迭代優化後的落地頁效果截圖 -->
|
||||
<!--  -->
|
||||
|
||||
> **Vibe Coding 的核心**：你不需要記住每個組件的 API，只需要用自然語言描述你想要的效果，AI 會幫你找到合適的組件和寫法。遇到不滿意的地方，繼續對話迭代就好。
|
||||
|
||||
## 4. 實戰二：用 shadcn/ui 構建產品頁面
|
||||
|
||||
**場景**：你的 AI 寫作助手需要一個用戶登錄後的主界面——左側是文檔列表，右側是編輯器，頂部有工具欄。這是一個功能型產品頁面，需要高度定製化的 UI。
|
||||
|
||||
**為什麼選 shadcn/ui**：shadcn/ui 把組件程式碼直接放進你的項目，你可以隨意修改任何細節。對於需要深度定製的產品界面，這種"擁有程式碼"的模式最靈活。
|
||||
|
||||
<!-- TODO: 替換為 shadcn/ui 官網或組件展示截圖 -->
|
||||
<!--  -->
|
||||
|
||||
### 4.1 創建項目
|
||||
|
||||
```bash
|
||||
# 創建 Next.js 項目
|
||||
npx create-next-app@latest ai-writer-app --typescript --tailwind --app
|
||||
cd ai-writer-app
|
||||
|
||||
# 初始化 shadcn/ui
|
||||
npx shadcn@latest init
|
||||
|
||||
# 按需添加組件（不是一次性安裝所有組件）
|
||||
npx shadcn@latest add button card input sidebar sheet dialog
|
||||
```
|
||||
|
||||
shadcn/ui 的獨特之處：每次 `add` 一個組件，它會把源程式碼複製到你項目的 `components/ui/` 目錄下。你可以直接打開這些文件修改樣式和行為。
|
||||
|
||||
### 4.2 用 AI IDE 生成產品界面
|
||||
|
||||
```text
|
||||
請幫我做一個 AI 寫作助手的主界面，用 shadcn/ui 組件庫來做：
|
||||
|
||||
**整體佈局：**
|
||||
- 左邊是可摺疊的側邊欄，寬度大概 280px：
|
||||
- 頂部放"新建文檔"按鈕
|
||||
- 下面是文檔列表，每個文檔顯示標題和最後編輯時間
|
||||
- 右鍵點擊文檔可以重命名或刪除
|
||||
- 右邊是主編輯區，分成上下兩部分：
|
||||
- 上面是工具欄：可以編輯文檔標題、顯示字數統計、"AI 續寫"按鈕、"導出"下拉菜單
|
||||
- 下面是編輯區域：一個大的文本輸入框，佔滿剩餘空間
|
||||
|
||||
**交互細節：**
|
||||
- 點擊"AI 續寫"後，按鈕顯示加載狀態，編輯器底部出現 AI 生成的文本（像打字機一樣逐字顯示）
|
||||
- 手機上側邊欄變成抽屜式，從左邊滑出
|
||||
- 當前選中的文檔要高亮顯示
|
||||
```
|
||||
|
||||
<!-- TODO: 替換為 AI 生成的 shadcn/ui 產品界面截圖 -->
|
||||
<!--  -->
|
||||
|
||||
### 4.3 AI 會用到的關鍵組件
|
||||
|
||||
```tsx
|
||||
import { Button } from '@/components/ui/button'
|
||||
import { Input } from '@/components/ui/input'
|
||||
import { Card, CardContent, CardHeader } from '@/components/ui/card'
|
||||
import {
|
||||
DropdownMenu,
|
||||
DropdownMenuContent,
|
||||
DropdownMenuItem,
|
||||
DropdownMenuTrigger
|
||||
} from '@/components/ui/dropdown-menu'
|
||||
import {
|
||||
Sheet,
|
||||
SheetContent,
|
||||
SheetTrigger
|
||||
} from '@/components/ui/sheet'
|
||||
import {
|
||||
Sidebar,
|
||||
SidebarContent,
|
||||
SidebarHeader
|
||||
} from '@/components/ui/sidebar'
|
||||
```
|
||||
|
||||
| 組件 | 用途 | 產品頁面中的位置 |
|
||||
| :--- | :--- | :--- |
|
||||
| `Sidebar` | 可摺疊側邊欄 | 左側文檔列表 |
|
||||
| `Sheet` | 移動端抽屜 | 移動端側邊欄替代 |
|
||||
| `DropdownMenu` | 下拉菜單 | "導出"按鈕、右鍵菜單 |
|
||||
| `Dialog` | 對話框 | 重命名、刪除確認 |
|
||||
| `Button` | 按鈕，支持 variant 和 loading | 各種操作按鈕 |
|
||||
| `Input` | 輸入框 | 文檔標題編輯 |
|
||||
|
||||
### 4.4 定製組件樣式
|
||||
|
||||
shadcn/ui 的優勢在於你可以直接修改組件源碼。比如你想讓按鈕的圓角更大：
|
||||
|
||||
```text
|
||||
請幫我修改 components/ui/button.tsx，
|
||||
把所有按鈕的默認圓角從 rounded-md 改為 rounded-xl，
|
||||
並給 primary 變體加上微妙的陰影效果
|
||||
```
|
||||
|
||||
AI 會直接修改你項目中的組件文件，而不是覆蓋 npm 包的樣式——這就是 shadcn/ui "擁有程式碼"的好處。
|
||||
|
||||
<!-- TODO: 替換為 shadcn/ui 組件源碼在項目中的截圖，展示可直接編輯 -->
|
||||
<!--  -->
|
||||
|
||||
## 5. 實戰三：用 Ant Design 構建後臺管理界面
|
||||
|
||||
**場景**：你的 AI 寫作助手上線後，需要一個管理後臺來查看用戶資料、管理文檔內容、處理付費訂單。後臺管理系統的核心是資料展示和操作效率。
|
||||
|
||||
**為什麼選 Ant Design**：Ant Design 在中後臺領域積累最深，表格、表單、圖表等業務組件開箱即用，內置了大量企業級交互模式（批量操作、高級篩選、資料導出等）。
|
||||
|
||||
<!-- TODO: 替換為 Ant Design 官網或 Pro Components 展示截圖 -->
|
||||
<!--  -->
|
||||
|
||||
### 5.1 創建項目
|
||||
|
||||
```bash
|
||||
# 使用 Ant Design Pro 腳手架（內置佈局、路由、權限）
|
||||
npx create-umi@latest ai-writer-admin
|
||||
# 選擇 Ant Design Pro 模板
|
||||
cd ai-writer-admin
|
||||
npm install
|
||||
```
|
||||
|
||||
或者從零開始：
|
||||
|
||||
```bash
|
||||
npx create-react-app ai-writer-admin --template typescript
|
||||
cd ai-writer-admin
|
||||
npm install antd @ant-design/icons @ant-design/pro-components
|
||||
```
|
||||
|
||||
### 5.2 用 AI IDE 生成管理後臺
|
||||
|
||||
```text
|
||||
請幫我做一個 AI 寫作助手的管理後臺，用 Ant Design 組件庫來做：
|
||||
|
||||
**整體佈局：**
|
||||
- 左邊是菜單欄：儀表盤、用戶管理、文檔管理、訂單管理、系統設置
|
||||
- 頂部顯示麵包屑導航
|
||||
|
||||
**用戶管理頁面：**
|
||||
- 頂部放四個統計卡片：總用戶數、今日新增、活躍用戶數、付費用戶數
|
||||
- 搜索篩選區：可以按用戶名搜索、選擇註冊時間範圍、篩選用戶狀態，還有"搜索"和"重置"按鈕
|
||||
- 用戶表格：
|
||||
- 顯示頭像、用戶名、郵箱、註冊時間、訂閱計劃（用不同顏色標籤區分）、狀態、操作
|
||||
- 每頁顯示 20 條，支持分頁
|
||||
- 可以批量選擇用戶，批量禁用或導出
|
||||
- 操作列：查看詳情、編輯、禁用（禁用前要二次確認）
|
||||
- 點擊"查看詳情"從右側滑出抽屜，顯示用戶詳細資訊和最近文檔列表
|
||||
```
|
||||
|
||||
<!-- TODO: 替換為 AI 生成的 Ant Design 後臺管理界面截圖 -->
|
||||
<!--  -->
|
||||
|
||||
### 5.3 AI 會用到的關鍵組件
|
||||
|
||||
```tsx
|
||||
import { PageContainer, ProLayout } from '@ant-design/pro-components'
|
||||
import { ProTable } from '@ant-design/pro-components'
|
||||
import { StatisticCard } from '@ant-design/pro-components'
|
||||
import {
|
||||
Button, Tag, Badge, Space, Drawer,
|
||||
Popconfirm, message, Modal
|
||||
} from 'antd'
|
||||
import {
|
||||
UserOutlined, SearchOutlined, ExportOutlined
|
||||
} from '@ant-design/icons'
|
||||
```
|
||||
|
||||
| 組件 | 用途 | 後臺中的位置 |
|
||||
| :--- | :--- | :--- |
|
||||
| `ProLayout` | 後臺整體佈局框架 | 頁面骨架（菜單 + 內容區） |
|
||||
| `ProTable` | 高級表格，內置搜索、分頁、列設置 | 用戶列表、文檔列表、訂單列表 |
|
||||
| `StatisticCard` | 資料統計卡片 | 儀表盤、頁面頂部概覽 |
|
||||
| `Tag` / `Badge` | 狀態標籤 | 訂閱計劃、用戶狀態 |
|
||||
| `Drawer` | 側邊抽屜 | 用戶詳情、編輯表單 |
|
||||
| `Popconfirm` | 氣泡確認框 | 刪除、禁用等危險操作 |
|
||||
|
||||
### 5.4 繼續迭代：添加儀表盤
|
||||
|
||||
```text
|
||||
請幫我做一個儀表盤頁面：
|
||||
|
||||
1. 頂部四個統計卡片：總用戶數、總文檔數、今日 API 調用次數、月收入，每個卡片顯示數值和環比變化（漲了還是跌了）
|
||||
2. 中間放兩個圖表：
|
||||
- 左邊：最近 7 天的用戶增長折線圖
|
||||
- 右邊：訂閱計劃分佈餅圖
|
||||
3. 底部：最近操作日誌表格，顯示時間、用戶、操作類型、詳情
|
||||
|
||||
用 Ant Design 的組件來佈局，圖表可以用 Ant Design Charts
|
||||
```
|
||||
|
||||
<!-- TODO: 替換為儀表盤頁面效果截圖 -->
|
||||
<!--  -->
|
||||
|
||||
> **後臺管理的 Vibe Coding 技巧**：後臺頁面結構相對固定（表格 + 搜索 + 彈窗），非常適合用 AI 批量生成。你可以先讓 AI 生成一個"用戶管理"頁面作為模板，然後說"參考用戶管理頁面的結構，幫我生成文檔管理頁面"，AI 會複用相同的佈局模式。
|
||||
|
||||
## 6. 學會查文檔：組件庫的"說明書"
|
||||
|
||||
Vibe Coding 中 AI 會幫你寫大部分程式碼，但當 AI 生成的結果不對、或者你想微調某個組件的行為時，**查文檔**是最快的解決方式。
|
||||
|
||||
以 Ant Design 為例，它的文檔地址是：`https://ant.design/components/overview-cn`
|
||||
|
||||
查文檔的標準流程：
|
||||
|
||||
1. **明確需求**：比如"我需要表格支持行選擇"
|
||||
2. **在文檔中搜索**：搜索"Table"進入表格組件頁面
|
||||
3. **查看示例**：文檔中每個組件都有多個在線示例，找到"可選擇"示例
|
||||
4. **複製程式碼**：把示例程式碼複製到你的項目中
|
||||
5. **查看 API 表格**：在頁面底部找到 `rowSelection` 屬性的完整配置項
|
||||
|
||||
> 你也可以把文檔鏈接直接發給 AI IDE："請參考 https://ant.design/components/table-cn 的 rowSelection API，幫我給用戶表格加上批量選擇功能"。給 AI 提供文檔鏈接，生成的程式碼會更準確。
|
||||
|
||||
各組件庫的文檔地址速查：
|
||||
|
||||
| 組件庫 | 文檔地址 |
|
||||
| :--- | :--- |
|
||||
| Ant Design | `https://ant.design/components/overview-cn` |
|
||||
| shadcn/ui | `https://ui.shadcn.com/docs/components` |
|
||||
| HeroUI | `https://heroui.com/docs/components` |
|
||||
| Material UI | `https://mui.com/material-ui/all-components/` |
|
||||
| Element Plus | `https://element-plus.org/zh-CN/component/overview.html` |
|
||||
|
||||
## 7. 小結
|
||||
|
||||
三個實戰場景覆蓋了最常見的前端開發需求：
|
||||
|
||||
| 場景 | 推薦組件庫 | 核心特點 |
|
||||
| :--- | :--- | :--- |
|
||||
| 落地頁 / 展示頁 | HeroUI | 默認樣式精美，動畫流暢，視覺衝擊力強 |
|
||||
| 產品功能頁面 | shadcn/ui | 程式碼完全可控，深度定製靈活 |
|
||||
| 後臺管理系統 | Ant Design | 業務組件豐富，表格表單開箱即用 |
|
||||
|
||||
Vibe Coding 的工作流總結：
|
||||
|
||||
1. 根據場景選擇合適的組件庫
|
||||
2. 用 AI IDE 描述你想要的頁面結構和交互
|
||||
3. AI 生成初版程式碼，你預覽效果
|
||||
4. 用自然語言繼續迭代調整
|
||||
5. 遇到細節問題時查閱組件庫文檔
|
||||
|
||||
### 練習
|
||||
|
||||
選擇以下任一場景，用 AI IDE + 組件庫從零完成：
|
||||
|
||||
1. 用 HeroUI 為你之前做的項目（比如霍格沃茨畫像）做一個展示落地頁
|
||||
2. 用 shadcn/ui 構建一個筆記應用的主界面（側邊欄 + 編輯器）
|
||||
3. 用 Ant Design 構建一個簡單的內容管理後臺（文章列表 + 新建文章表單）
|
||||
|
||||
---
|
||||
|
||||
## 附錄：更多組件庫一覽
|
||||
|
||||
除了正文介紹的四個核心庫，前端生態中還有大量優秀的組件庫。下面按框架分類列出，方便你根據項目需求選擇。
|
||||
|
||||
### Vue 生態
|
||||
|
||||
| 組件庫 | Stars | 簡介 | 適用場景 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| [Element Plus](https://element-plus.org) | ~27k | 餓了麼團隊打造的 Vue 3 企業級組件庫，國內使用最廣泛，中文生態極佳 | 中後臺管理系統 |
|
||||
| [Vuetify](https://vuetifyjs.com) | ~41k | 最流行的 Vue Material Design 組件庫，80+ 組件，文檔完善 | Google 設計風格項目 |
|
||||
| [Ant Design Vue](https://antdv.com) | ~21k | 基於螞蟻設計體系的 Vue 3 組件庫，設計規範統一 | 企業級中後臺 |
|
||||
| [Naive UI](https://www.naiveui.com) | ~18k | TypeScript 編寫，主題定製性極強，不依賴 CSS 預處理器 | 對設計有獨特要求的項目 |
|
||||
| [Quasar](https://quasar.dev) | ~27k | 一套程式碼構建 SPA、SSR、PWA、移動端和桌面端應用 | 跨平臺項目 |
|
||||
| [Vant](https://vant-ui.github.io/vant) | ~24k | 有贊團隊開發的輕量級移動端組件庫，覆蓋電商常見需求 | 移動端 H5 頁面 |
|
||||
| [PrimeVue](https://primevue.org) | ~14k | 90+ 組件，支持多種主題（Material、Bootstrap 等） | 需要豐富組件和多主題 |
|
||||
| [Arco Design Vue](https://arco.design/vue) | ~3k | 字節跳動出品，組件質量高，內置暗色模式 | 中後臺產品 |
|
||||
| [TDesign Vue Next](https://tdesign.tencent.com/vue-next) | ~2k | 騰訊出品，設計語言統一，覆蓋桌面端常用場景 | 騰訊生態或企業級項目 |
|
||||
|
||||
### React 生態
|
||||
|
||||
| 組件庫 | Stars | 簡介 | 適用場景 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| [Material UI (MUI)](https://mui.com) | ~95k | Google Material Design 規範的老牌實現，組件最全面，生態最成熟 | 快速構建企業級應用 |
|
||||
| [Ant Design](https://ant.design) | ~94k | 螞蟻集團出品，內置大量高質量業務組件，中文開發者社區主導地位 | 企業級中後臺 |
|
||||
| [shadcn/ui](https://ui.shadcn.com) | ~83k | 程式碼複製到項目中而非 npm 安裝，基於 Radix UI + Tailwind CSS，完全可控 | 需要高度定製的項目 |
|
||||
| [Chakra UI](https://chakra-ui.com) | ~39k | 以開發體驗為核心，API 簡潔，內置無障礙訪問支持 | 快速原型開發 |
|
||||
| [Mantine](https://mantine.dev) | ~28k | 100+ 組件和 50+ hooks，涵蓋日期選擇器、富文本編輯器等高級組件 | 需要開箱即用的全功能方案 |
|
||||
| [Headless UI](https://headlessui.com) | ~27k | Tailwind Labs 官方出品的無樣式組件庫，同時支持 React 和 Vue | 搭配 Tailwind CSS 使用 |
|
||||
| [HeroUI](https://heroui.com) | ~24k | 基於 Tailwind CSS + React Aria，默認樣式精美，動畫流暢 | 追求視覺品質的項目 |
|
||||
| [Radix UI](https://www.radix-ui.com) | ~17k | 無樣式底層組件原語庫，專注無障礙和組件行為，是 shadcn/ui 的底層基礎 | 構建自定義設計系統 |
|
||||
|
||||
#### shadcn/ui 擴展生態
|
||||
|
||||
除了上述通用組件庫，shadcn/ui 生態中還湧現了大量基於其理念的擴展庫，為特定場景提供差異化選擇。這些擴展庫同樣採用"複製程式碼到項目"的模式，讓開發者擁有完全的源碼控制權。
|
||||
|
||||
| 組件庫 | 簡介 | 適用場景 |
|
||||
| :--- | :--- | :--- |
|
||||
| [Aceternity UI](https://ui.aceternity.com) | 200+ 生產級組件，主打發光卡片、文字漸變、3D 地球等特色視覺組件 | 高質感落地頁、SaaS 產品 |
|
||||
| [Tailark UI](https://tailark.com) | 營銷網站組件塊集合，產品展示、客戶證言、CTA 按鈕等營銷高頻模塊 | 營銷落地頁、產品官網 |
|
||||
| [UI Tripled](https://ui.tripled.work) | 基於 Framer Motion 的動態交互組件，彈窗、導航、卡片動畫 | 創意工具、個人作品集 |
|
||||
| [Neobrutalism UI](https://neobrutalism.dev) | 新粗野主義風格，粗線條、高對比度、鮮明色彩 | 個性化品牌官網、創意項目 |
|
||||
| [REUI](https://reui.io) | 967+ 真實業務場景的組件組合模式 | 企業級後臺、複雜表單 |
|
||||
| [Cult UI](https://cult-ui.com) | 更細的交互/視覺打磨，資料表格、篩選面板等複合組件 | 高質感商業項目 |
|
||||
| [Kibo UI](https://kibo-ui.com) | 高級業務組件，顏色選擇器、富文本編輯器、文件上傳等 | 管理後臺、工具類產品 |
|
||||
| [Kokonut UI](https://kokonutui.com) | 100+ 組件 + 7+ 完整模板，清新簡約風格 | SaaS 官網、博客、電商 |
|
||||
| [Commerce UI](https://ui.stackzero.co) | 電商場景專用，商品卡片、購物車、結算表單 | 電商平臺 |
|
||||
| [shadcnblocks](https://shadcnblocks.com) | 1373 個 UI 塊 + 13 套完整模板，資源最全面 | 所有場景 |
|
||||
| [Shoogle](https://shoogle.dev) | shadcn/ui 生態聚合檢索平臺 | 快速查找資源 |
|
||||
| [Discover All Shadcn](https://allshadcn.com) | 聚合型資源導航 | 快速查找資源 |
|
||||
|
||||
> **為什麼選擇 shadcn/ui 擴展？** 這些擴展繼承了 shadcn/ui"程式碼所有權"的理念，同時為特定場景做了深度定製。Vibe Coding 時代，它們讓你能快速找到符合設計需求的組件，跳出主流 UI 庫的同質化，做出更具差異化的產品。
|
||||
@@ -0,0 +1,425 @@
|
||||
# 參考 UI 設計規範設計頁面和按鈕
|
||||
|
||||
很多人說"我想讓頁面更像 Apple 一點""按鈕想做得更高級一點"，但真正開始做時，往往會卡在一個問題上：
|
||||
|
||||
**到底該參考什麼？**
|
||||
|
||||
盯著截圖模仿，學到的只是"像不像"。但打開 Apple、Google、Microsoft、Atlassian 的設計規範，你會發現它們真正厲害的地方不是視覺風格，而是**把設計問題講清楚**：頁面先突出什麼、按鈕如何分級、操作怎麼強調——這些判斷標準才是核心。
|
||||
|
||||
> 參考設計規範，不是為了做得"像誰"，而是學會別人怎麼做判斷。
|
||||
|
||||
:::: info 為什麼現在還要學這些
|
||||
設計規則早已被訓練進模型、被設計工具默認吸收，甚至貼幾張截圖 AI 就能學會。但我們仍然有必要知道這些規則從哪來、為什麼這樣定。
|
||||
::::
|
||||
|
||||
## 先看幾段原文，感受差距
|
||||
|
||||
如果你以前覺得“設計規範不就是講講風格嗎”，先看幾條官方原文。
|
||||
|
||||
平時我們在團隊裡經常會這樣說：
|
||||
|
||||
- 做個下拉框
|
||||
- 這裡放個菜單
|
||||
- 菜單欄加幾個功能
|
||||
- 這裡放兩個按鈕，一個確認一個取消
|
||||
|
||||
聽起來沒問題，但在大廠規範裡，這些詞都不是模糊概念，而是被拆得非常細。
|
||||
|
||||
| 平時隨口說的話 | 官方原文 | 簡單說 |
|
||||
| :--- | :--- | :--- |
|
||||
| “做個菜單” | Apple: [“A menu reveals its options...”](https://developer.apple.com/design/human-interface-guidelines/menus) | `Menu` 是拿來做操作的 |
|
||||
| “菜單欄裡放功能” | Apple: [“menu bar menus contain all the commands...”](https://developer.apple.com/design/human-interface-guidelines/menus) | 這是應用頂部的命令菜單 |
|
||||
| “做個下拉框” | Apple: [“A pop-up list lets the user choose one option among several.”](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MenuList/Articles/ManagingPopUpItems.html) | `pop-up` 是從列表裡選一個 |
|
||||
| “也做個下拉框” | Apple: [“A pull-down list is generally used for selecting commands in a specific context.”](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MenuList/Articles/ManagingPopUpItems.html) | `pull-down` 是點開做當前操作 |
|
||||
| “菜單也能拿來篩選吧” | Fluent: [“If you need to collect information from people, try a select, dropdown, or combobox instead.”](https://fluent2.microsoft.design/components/web/react/core/menu/usage) | `Menu` 不是拿來選值的 |
|
||||
| “菜單也能當導航吧” | Material: [“Menus should not be used as a primary method for navigation within an app.”](https://m1.material.io/components/menus.html) | `Menu` 不是主導航 |
|
||||
| “按鈕隨便寫個 OK / Cancel” | Apple: [“Always use ‘Cancel’ to title a button that cancels the alert’s action.”](https://developer.apple.com/design/human-interface-guidelines/alerts) | 按鈕文字不能隨便寫 |
|
||||
|
||||
> 表格裡的引文都可以直接點擊，跳到對應的官方頁面。
|
||||
|
||||
這就是第一次真正看設計規範時最容易被震到的地方：
|
||||
|
||||
> 我們平時以為自己在討論 UI，實際上很多時候只是在用一堆含糊詞交流。
|
||||
|
||||
Apple 不會只說“做個菜單”；它會繼續區分：
|
||||
|
||||
- `menu`
|
||||
- `menu bar menu`
|
||||
- `pop-up button`
|
||||
- `pull-down button`
|
||||
- `context menu`
|
||||
|
||||
Fluent 不會只說“下拉框”；它會繼續區分：
|
||||
|
||||
- `menu`
|
||||
- `dropdown`
|
||||
- `select`
|
||||
- `combobox`
|
||||
|
||||
這就是設計規範的必要性。
|
||||
|
||||
它不是為了讓頁面顯得更專業，而是為了讓團隊在討論 UI 時，不再每個人腦子裡都是不同的東西。
|
||||
|
||||
## 你將學到
|
||||
|
||||
1. 為什麼設計頁面和按鈕時要先看設計規範
|
||||
2. Apple、Material、Fluent、Atlassian 這些規範裡，哪些內容最值得參考
|
||||
3. 如何把“頁面層級”和“按鈕層級”設計清楚
|
||||
4. 如何讓 AI 參考別人的規範來生成頁面和按鈕
|
||||
|
||||
## 1. 設計規範為什麼能幫你把頁面做清楚
|
||||
|
||||
看完上面這些原文，你會發現一個關鍵點：
|
||||
|
||||
**設計規範不是錦上添花，而是在先把詞說準。**
|
||||
|
||||
很多頁面不好看，不是因為配色不夠高級，而是因為資訊層級混亂。
|
||||
|
||||
很多按鈕不好用，也不是因為圓角不對，而是因為：
|
||||
|
||||
- 主按鈕太多，用戶不知道該點哪個
|
||||
- 危險按鈕和普通按鈕看起來差不多
|
||||
- 頁面裡所有按鈕都在搶注意力
|
||||
- 不同頁面裡的按鈕樣式和語義不一致
|
||||
|
||||
成熟的設計規範，恰好就是在解決這些問題。它們通常會定義：
|
||||
|
||||
| 規範內容 | 它解決什麼問題 |
|
||||
| :--- | :--- |
|
||||
| **頁面層級** | 先看哪裡、後看哪裡，資訊怎麼組織 |
|
||||
| **視覺基礎** | 顏色、間距、字體、圓角、陰影怎樣統一 |
|
||||
| **按鈕層級** | 主按鈕、次按鈕、文字按鈕、危險按鈕如何區分 |
|
||||
| **狀態規則** | hover、focus、disabled、loading 怎麼表現 |
|
||||
| **交互語義** | 哪個按鈕是“確認”，哪個是“取消”，哪個是“更多操作” |
|
||||
|
||||
所以，設計規範真正提供的不是一套“皮膚”，而是一套**判斷標準**。
|
||||
|
||||
## 2. 參考大廠規範時，重點看什麼
|
||||
|
||||
### 2.1 參考 Apple：學習“定義得足夠細”這件事
|
||||
|
||||
Apple 最值得學的，不只是視覺上的剋制感，而是它會把概念定義得非常細。
|
||||
|
||||
同樣是很多團隊口中的“菜單”或“下拉框”，Apple 會繼續往下拆：
|
||||
|
||||
- `menu`：一組命令、選項或狀態
|
||||
- `menu bar menu`：應用級命令集合
|
||||
- `pop-up button`：選擇一個值
|
||||
- `pull-down button`：在當前上下文裡觸發命令
|
||||
- `context menu`：與當前對象或任務相關的常用動作
|
||||
|
||||
這套區分非常重要，因為它會直接影響：
|
||||
|
||||
- 這個組件是拿來選值，還是拿來做動作
|
||||
- 它屬於頁面局部，還是屬於應用級
|
||||
- 它應該長期顯示當前選中值，還是隻臨時展開命令
|
||||
|
||||
當你開始按這種粒度思考時，你設計出來的頁面就會一下子清楚很多。
|
||||
|
||||
### 2.2 參考 Apple：學習頁面層級和剋制感
|
||||
|
||||
Apple Human Interface Guidelines 特別適合學習兩件事：
|
||||
|
||||
- 頁面如何建立清晰層級
|
||||
- 控件如何在不喧賓奪主的前提下保持明確
|
||||
|
||||
Apple 強調 `Hierarchy`、`Harmony`、`Consistency`。這意味著頁面設計時要回答：
|
||||
|
||||
- 當前頁面最重要的資訊是什麼
|
||||
- 用戶的主要任務是什麼
|
||||
- 哪個操作該最顯眼，哪個操作應該退後
|
||||
|
||||
如果你參考 Apple 來設計頁面，可以重點借鑑：
|
||||
|
||||
- 首屏資訊不要太碎，核心內容先聚焦
|
||||
- 用留白、字號、分組建立秩序，而不是靠堆很多邊框
|
||||
- 按鈕不要全部高強調，只有關鍵動作才應該最突出
|
||||
|
||||
### 2.3 參考 Material：學習清晰的頁面結構
|
||||
|
||||
Material Design 很適合學習“頁面是怎麼組織任務流”的。
|
||||
|
||||
它的很多組件和佈局規範，核心都在幫助你明確：
|
||||
|
||||
- 頁面是瀏覽型，還是執行任務型
|
||||
- 當前頁面是讓用戶閱讀、選擇，還是提交
|
||||
- 一個頁面裡哪些元素應該穩定重複，哪些元素應該響應上下文變化
|
||||
|
||||
如果你參考 Material 來設計頁面，可以重點借鑑：
|
||||
|
||||
- 頁面區塊清楚，模塊職責明確
|
||||
- 導航、內容區、操作區分工清晰
|
||||
- 不同按鈕樣式對應不同操作優先級
|
||||
|
||||
### 2.4 參考 Fluent：學習組件邊界和按鈕層級
|
||||
|
||||
Fluent 2 很適合後臺、工具型產品和複雜表單系統。它最值得學的地方，是會直接告訴你“不要混用概念”。
|
||||
|
||||
例如它明確寫到：如果你要“collect information”，就不要繼續用 `menu`，而應該考慮 `select`、`dropdown`、`combobox`。
|
||||
|
||||
這句話非常重要，因為它把很多人腦中的“都差不多”打碎了。
|
||||
|
||||
Fluent 2 也很重視：
|
||||
|
||||
- 操作層級
|
||||
- 組件語義邊界
|
||||
- 密集資訊場景下的清晰度
|
||||
|
||||
如果你參考 Fluent 來設計按鈕，可以重點借鑑：
|
||||
|
||||
- `Primary button` 用來承接當前最重要的動作
|
||||
- `Secondary button` 用來承接支持性動作
|
||||
- `Subtle`、`Transparent` 這類弱強調按鈕用於不該搶主流程的操作
|
||||
- 頁面裡的按鈕數量越多，越要控制視覺優先級
|
||||
|
||||
### 2.5 參考 Atlassian：學習系統化地管理頁面和按鈕
|
||||
|
||||
Atlassian Design System 特別適合“一個團隊做很多頁面”的情況。它強調：
|
||||
|
||||
- foundations 是共享基礎
|
||||
- tokens 是統一視覺決策的方法
|
||||
- components 是被反覆複用的交互構件
|
||||
|
||||
如果你參考 Atlassian 來做頁面和按鈕，最有價值的是：
|
||||
|
||||
- 把按鈕尺寸、顏色、圓角、間距做成統一規則
|
||||
- 把頁面佈局的節奏固定下來
|
||||
- 讓不同頁面雖然內容不同，但結構語言一致
|
||||
|
||||
## 3. 設計頁面時，應該參考規範裡的哪些點
|
||||
|
||||
當你看一個設計系統時，不要先問“這個頁面好不好看”，而要先問下面幾個問題。
|
||||
|
||||
### 3.1 頁面第一眼，主次是不是明確
|
||||
|
||||
一個頁面通常至少要有三層：
|
||||
|
||||
- **主資訊**：當前頁面最重要的內容
|
||||
- **輔助資訊**：幫助理解或補充的內容
|
||||
- **次級操作**：不應該干擾主任務的動作
|
||||
|
||||
如果三層沒有拉開，頁面就會“都重要”，等於“都不重要”。
|
||||
|
||||
### 3.2 頁面佈局，是不是服務任務而不是堆模塊
|
||||
|
||||
參考規範時，可以特別注意：
|
||||
|
||||
- 標題區有沒有明確頁面目標
|
||||
- 主內容區是不是圍繞任務組織
|
||||
- 操作按鈕是不是貼近相關內容
|
||||
- 次要資訊有沒有被弱化
|
||||
|
||||
### 3.3 頁面裡的操作，是不是有優先級
|
||||
|
||||
很多頁面一眼看過去有 6 個按鈕，結果每個按鈕都像 CTA，這是典型的層級失控。
|
||||
|
||||
更合理的方式是：
|
||||
|
||||
- 一個區域通常只有一個主動作
|
||||
- 次級動作可以用描邊、文字按鈕或更弱的樣式
|
||||
- 風險動作不要和主動作長得一樣
|
||||
|
||||
## 4. 設計按鈕時，應該參考規範裡的哪些點
|
||||
|
||||
按鈕是最容易被“隨手設計”的部分，但也是最能暴露系統是否成熟的部分。
|
||||
|
||||
### 4.1 按鈕先分“語義”，再分“樣式”
|
||||
|
||||
不要先想“藍色按鈕還是黑色按鈕”，先想這個按鈕是什麼角色。
|
||||
|
||||
常見按鈕角色可以這樣分：
|
||||
|
||||
| 按鈕類型 | 作用 | 常見樣式策略 |
|
||||
| :--- | :--- | :--- |
|
||||
| **Primary** | 當前區域最關鍵動作 | 實心、高對比、最顯眼 |
|
||||
| **Secondary** | 支持性動作 | 描邊或低一級強調 |
|
||||
| **Tertiary / Text** | 弱操作 | 文字或低視覺佔比 |
|
||||
| **Destructive** | 刪除、停用、清空等風險操作 | 警示色或明確風險樣式 |
|
||||
| **Icon button** | 局部工具操作 | 簡潔、靠近上下文 |
|
||||
|
||||
### 4.2 一個頁面不要有太多 Primary Button
|
||||
|
||||
這是很多新手最容易踩的坑。
|
||||
|
||||
如果頁面上有 4 個主按鈕，那麼等於沒有主按鈕。主按鈕的意義本來就是“告訴用戶現在最應該做什麼”。
|
||||
|
||||
你可以借鑑很多設計系統的共同做法：
|
||||
|
||||
- 一個主要區域通常只保留一個主按鈕
|
||||
- 取消、返回、關閉一般不和確認按鈕搶同級
|
||||
- 更多操作放到次級按鈕或菜單中
|
||||
|
||||
### 4.3 按鈕要能表達狀態變化
|
||||
|
||||
設計規範通常會對按鈕狀態寫得很清楚：
|
||||
|
||||
- 默認態
|
||||
- 懸停態
|
||||
- 聚焦態
|
||||
- 禁用態
|
||||
- 加載態
|
||||
- 危險態
|
||||
|
||||
這很重要，因為按鈕不是一張靜態圖，而是用戶操作過程中最常被觸發的控件之一。
|
||||
|
||||
### 4.4 按鈕文案，也屬於設計的一部分
|
||||
|
||||
按鈕文案不只是“文案問題”，它直接影響用戶理解。
|
||||
|
||||
例如：
|
||||
|
||||
- `保存`
|
||||
- `保存更改`
|
||||
- `立即發佈`
|
||||
- `刪除項目`
|
||||
- `移到回收站`
|
||||
|
||||
這些文案傳達的心理預期完全不同。成熟規範通常會要求按鈕標籤清楚表達動作，而不是使用含糊詞。
|
||||
|
||||
## 5. 一個很實用的頁面與按鈕設計清單
|
||||
|
||||
你自己設計頁面時，可以先快速過一遍這張清單：
|
||||
|
||||
### 頁面清單
|
||||
|
||||
- 頁面標題是否清楚說明當前任務
|
||||
- 首屏最重要的資訊是否一眼可見
|
||||
- 頁面是不是按任務流程組織，而不是按想到什麼放什麼
|
||||
- 同一個區域裡是否只有一個主要動作
|
||||
- 次要內容是否被適當弱化
|
||||
|
||||
### 按鈕清單
|
||||
|
||||
- 這個按鈕是主動作還是次動作
|
||||
- 它為什麼值得比別的按鈕更顯眼
|
||||
- 頁面裡是不是有太多主按鈕
|
||||
- 危險操作是否被明確標識
|
||||
- 按鈕文案是否足夠具體
|
||||
|
||||
## 6. 怎樣用 AI 參考別人的規範來設計頁面
|
||||
|
||||
這一節最實用。
|
||||
|
||||
很多人讓 AI 設計頁面時，只會說：
|
||||
|
||||
```md
|
||||
幫我做一個設置頁面，要高級一點，參考蘋果風格
|
||||
```
|
||||
|
||||
這類提示詞太模糊了，AI 最後通常只能模仿“白底、圓角、陰影”。
|
||||
|
||||
對新手來說，更實用的方式不是自己總結一大段，而是直接把**規範原文裡的關鍵句**貼給 AI。
|
||||
|
||||
這樣做有兩個好處：
|
||||
|
||||
- 你不用自己先“翻譯”一遍設計思想
|
||||
- AI 更容易按官方定義去理解頁面和按鈕
|
||||
|
||||
### 6.1 例子一：讓 AI 參考 Apple 設計一個設置頁面
|
||||
|
||||
先找一句 Apple 原文：
|
||||
|
||||
> ["Establish a clear visual hierarchy..."](https://developer.apple.com/design/human-interface-guidelines/)
|
||||
|
||||
你可以直接這樣貼給 AI：
|
||||
|
||||
```md
|
||||
參考 Apple Human Interface Guidelines 裡的這句話：
|
||||
"Establish a clear visual hierarchy..."
|
||||
|
||||
幫我設計一個賬號安全設置頁面。
|
||||
要求頁面層級清楚，重要資訊放前面，分組整齊一點。
|
||||
```
|
||||
|
||||
這樣寫的重點是：不用你自己解釋太多，直接把 Apple 的原話貼進去。
|
||||
|
||||
### 6.2 例子二：讓 AI 參考 Fluent 設計後臺頁面按鈕
|
||||
|
||||
先找一句 Fluent 原文：
|
||||
|
||||
> ["Only use one primary button in a layout..."](https://fluent2.microsoft.design/components/web/react/core/button/usage)
|
||||
|
||||
你可以直接這樣貼給 AI：
|
||||
|
||||
```md
|
||||
參考 Fluent 2 裡的這句話：
|
||||
"Only use one primary button in a layout..."
|
||||
|
||||
幫我設計一個團隊管理後臺的按鈕。
|
||||
添加成員按鈕最明顯，導出、篩選、更多操作弱一點，刪除按鈕單獨突出。
|
||||
```
|
||||
|
||||
這一句非常適合新手，因為它直接告訴 AI：一個區域不要放太多主按鈕。
|
||||
|
||||
### 6.3 例子三：讓 AI 同時參考頁面規範和按鈕規範
|
||||
|
||||
你也可以一次貼兩句原文，讓 AI 同時參考頁面和按鈕：
|
||||
|
||||
> Apple: ["Establish a clear visual hierarchy..."](https://developer.apple.com/design/human-interface-guidelines/)
|
||||
>
|
||||
> Fluent: ["Only use one primary button in a layout..."](https://fluent2.microsoft.design/components/web/react/core/button/usage)
|
||||
|
||||
然後直接這樣寫：
|
||||
|
||||
```md
|
||||
參考下面兩句設計規範原文：
|
||||
Apple: "Establish a clear visual hierarchy..."
|
||||
Fluent: "Only use one primary button in a layout..."
|
||||
|
||||
幫我設計一個項目詳情頁。
|
||||
頁面包含項目介紹、成員、最近活動和設置入口。
|
||||
頁面層級清楚一點，主按鈕只保留一個，其他按鈕弱一點。
|
||||
```
|
||||
|
||||
這種方式特別適合新手，因為你只要會複製原文，再加兩句自己的需求就夠了。
|
||||
|
||||
## 7. 怎樣用 AI 參考按鈕規範來直接生成按鈕設計
|
||||
|
||||
如果你只想先做按鈕，也可以直接貼按鈕規範原文。
|
||||
|
||||
例如 Atlassian 對按鈕的定義很短：
|
||||
|
||||
> ["A button triggers an event or action."](https://atlassian.design/components/button/)
|
||||
|
||||
你可以這樣問 AI：
|
||||
|
||||
```md
|
||||
參考 Atlassian 的這句話：
|
||||
"A button triggers an event or action."
|
||||
|
||||
幫我設計一套後臺頁面按鈕樣式。
|
||||
我要有主按鈕、次按鈕、刪除按鈕，順便告訴我分別用在什麼地方。
|
||||
```
|
||||
|
||||
這類提示詞尤其適合新手，基本就是“貼原文 + 說需求”。
|
||||
|
||||
## 8. 小結
|
||||
|
||||
參考 UI 設計規範設計頁面和按鈕，最重要的不是“做得像誰”，而是學會下面這幾件事：
|
||||
|
||||
1. 用層級組織頁面，而不是把內容堆上去
|
||||
2. 用按鈕分級表達操作優先級，而不是讓所有按鈕都一樣搶眼
|
||||
3. 用設計規範裡的定義、邊界和判斷標準指導設計
|
||||
4. 讓 AI 參考別人規範時，參考的是“原則和結構”，而不是隻參考皮膚
|
||||
|
||||
當你這樣使用規範時，你參考到的就不只是一個風格，而是一套成熟的設計思考方式。
|
||||
|
||||
---
|
||||
|
||||
## 參考資料
|
||||
|
||||
以下鏈接都來自官方設計系統或官方文檔：
|
||||
|
||||
- Apple Human Interface Guidelines: [Overview](https://developer.apple.com/design/human-interface-guidelines/)
|
||||
- Apple Human Interface Guidelines: [Menus](https://developer.apple.com/design/human-interface-guidelines/menus)
|
||||
- Apple Human Interface Guidelines: [Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts)
|
||||
- Apple Human Interface Guidelines: [Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons)
|
||||
- Apple Archive: [How Menus Work](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MenuList/Articles/HowMenusWork.html)
|
||||
- Apple Archive: [Managing Pop-Up Buttons and Pull-Down Lists](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/MenuList/Articles/ManagingPopUpItems.html)
|
||||
- Material Design: [Buttons overview](https://m3.material.io/components/buttons/overview)
|
||||
- Material Design: [Menus](https://m1.material.io/components/menus.html)
|
||||
- Microsoft Fluent 2: [Start designing](https://fluent2.microsoft.design/get-started/design)
|
||||
- Microsoft Fluent 2: [Menu usage](https://fluent2.microsoft.design/components/web/react/core/menu/usage)
|
||||
- Microsoft Fluent 2: [Button usage](https://fluent2.microsoft.design/components/web/react/core/button/usage)
|
||||
- Atlassian Design System: [Foundations](https://atlassian.design/foundations/)
|
||||
- Atlassian Design System: [Button](https://atlassian.design/components/button/)
|
||||
@@ -0,0 +1,3 @@
|
||||
# 構建第一個現代應用程序 - UI 設計
|
||||
|
||||
> 本章節正在編寫中，敬請期待...
|
||||
+125
-58
@@ -1,118 +1,185 @@
|
||||
# 初中級開發
|
||||
|
||||
歡迎來到 **初中級開發** 階段！在這裡，你將深入全棧開發，掌握前端組件化、數據庫設計、後端 API 開發與部署上線。
|
||||
歡迎來到 **初中級開發** 階段！在這裡，你將深入全棧開發，掌握前端組件化、資料庫設計、後端 API 開發與部署上線。
|
||||
|
||||
## 你將學到什麼
|
||||
|
||||
### 前端開發
|
||||
|
||||
掌握現代前端開發，學習組件庫與設計工具的使用：
|
||||
|
||||
<NavGrid>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="前端零：使用 Lovart 生產素材"
|
||||
description="學習如何使用 Lovart 等 AI 工具快速生成高質量的遊戲素材與 UI 資源"
|
||||
href="/zh-tw/stage-2/frontend/lovart-assets/"
|
||||
title="從Lovart出發，搭建自己的素材生產Agent"
|
||||
description="從零開始，利用Nanobanana和Lovart批量生成高質量的設計素材，並動手構建一個能意圖識別的繪圖Agent"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="前端一：Figma 與 MasterGo 入門"
|
||||
description="掌握專業 UI 設計工具的基礎操作，從設計稿到代碼的協作流程"
|
||||
href="/zh-tw/stage-2/frontend/figma-mastergo/"
|
||||
title="Figma 與 MasterGo 入門"
|
||||
description="掌握專業 UI 設計工具的基礎操作，從設計稿到程式碼的協作流程"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="前端二：構建第一個現代應用程序 - UI 設計"
|
||||
description="從零開始設計一個現代 Web 應用的界面，實踐 UI 設計原則"
|
||||
href="/zh-tw/stage-2/frontend/ui-design/"
|
||||
title="構建第一個現代應用程序 - UI 設計"
|
||||
description="學習現代應用程序的 UI 設計基礎"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="前端三：參考 UI 設計規範與多產品 UI 設計"
|
||||
description="學習主流 UI 設計規範，提升產品設計的一致性與美感"
|
||||
href="/zh-tw/stage-2/frontend/multi-product-ui/"
|
||||
title="參考 UI 設計規範設計頁面和按鈕"
|
||||
description="學習主流 UI 設計規範，設計更清晰的頁面層級與按鈕層級"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="前端四：一起做霍格沃茨畫像"
|
||||
href="/zh-tw/stage-2/frontend/llm-skills-beautiful/"
|
||||
title="用 LLM 和 Skills 讓界面變好看"
|
||||
description="使用提示詞與插件實戰，讓 AI 生成美觀獨特的界面"
|
||||
/>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/frontend/hogwarts-portraits/"
|
||||
title="一起做霍格沃茨畫像"
|
||||
description="實戰項目：結合 AI 生成的圖像，構建一個交互式的霍格沃茨畫像應用"
|
||||
/>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/frontend/design-to-code/"
|
||||
title="從設計原型到項目程式碼"
|
||||
description="學習如何將設計工具中的原型轉化為真正能在瀏覽器裡運行的前端程式碼"
|
||||
/>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/frontend/modern-component-library/"
|
||||
title="使用現代組件庫更新你的界面"
|
||||
description="學習使用組件庫快速構建專業級界面"
|
||||
/>
|
||||
</NavGrid>
|
||||
|
||||
### 後端開發
|
||||
|
||||
### 後端與全棧
|
||||
學習 API 設計、資料庫管理以及應用部署策略：
|
||||
|
||||
學習 API 設計、數據庫管理以及應用部署策略：
|
||||
<NavGrid>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="後端一：什麼是 API"
|
||||
description="理解 API 的核心概念，它是前後端交互的橋樑"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="後端二：從數據庫到 Supabase"
|
||||
description="掌握關係型數據庫基礎，並學習使用 Supabase 這一現代 BaaS 平台"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="後端三：大模型輔助編寫接口代碼與接口文檔"
|
||||
description="利用 AI 輔助生成後端接口代碼及標準的接口文檔，提升開發效率"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="後端四：Git 工作流"
|
||||
href="/zh-tw/stage-2/backend/git-workflow/"
|
||||
title="學會使用 Git 與 Github"
|
||||
description="掌握 Git 版本控制系統的核心操作與協作流程"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="後端五：Zeabur 部署"
|
||||
href="/zh-tw/stage-2/backend/database-supabase/"
|
||||
title="從資料庫到 Supabase"
|
||||
description="掌握關聯式資料庫基礎，並學習使用 Supabase 這一現代 BaaS 平台"
|
||||
/>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/backend/ai-interface-code/"
|
||||
title="應用後端接口設計與開發"
|
||||
description="利用 AI 輔助生成後端接口程式碼及標準的接口文檔，提升開發效率"
|
||||
/>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/backend/zeabur-deployment/"
|
||||
title="發布你的產品原型"
|
||||
description="學習使用 Zeabur 快速部署你的全棧應用到雲端"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="後端六：現代 CLI 開發工具"
|
||||
href="/zh-tw/stage-2/backend/modern-cli/"
|
||||
title="從 IDE 到 CLI AI 程式設計工具"
|
||||
description="探索現代 CLI 工具，提升命令行環境下的開發體驗"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="後端七：如何集成 Stripe 等收費系統"
|
||||
href="/zh-tw/stage-2/backend/stripe-payment/"
|
||||
title="如何集成 Stripe 等收費系統"
|
||||
description="實戰：為你的應用集成 Stripe 支付功能，實現商業化變現"
|
||||
/>
|
||||
</NavGrid>
|
||||
|
||||
|
||||
### 大作業
|
||||
|
||||
通過實戰項目鞏固你的全棧開發技能：
|
||||
前面的章節是在學「零件」，大作業才是在學「怎麼把零件裝成一個能跑、能演示、能上線的產品」。
|
||||
|
||||
建議你按 **大作業 1 -> 大作業 2** 的順序來做：
|
||||
|
||||
- **大作業 1** 先帶你跑通現代 SaaS 最常見的主鏈路：登錄、生成、資料庫、支付、管理後台。
|
||||
- **大作業 2** 再帶你進入更像業務系統的場景：角色權限、題庫、考試、提交記錄、管理台。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
A["前端頁面與組件"] --> B["資料庫與接口"]
|
||||
B --> C["大作業 1<br/>文案生成 SaaS"]
|
||||
C --> D["支付 / 部署 / 後台管理"]
|
||||
D --> E["大作業 2<br/>在線考試系統"]
|
||||
E --> F["完整全棧作品集"]
|
||||
```
|
||||
|
||||
如果你不知道先做哪個，可以直接參考下面這張對比表：
|
||||
|
||||
| 項目 | 你會重點練到什麼 | 最適合誰 | 最終交付物 |
|
||||
|------|------|------|------|
|
||||
| 大作業 1：文案生成網站 | SaaS 頁面結構、用戶登錄、AI 生成、Stripe 支付、後台管理 | 第一次做完整商業化網站的人 | 一個可註冊、可生成、可付費、可管理的 SaaS 雛形 |
|
||||
| 大作業 2：在線考試與管理系統 | 角色權限、題庫建模、考試流程、提交記錄、批改與統計 | 想把「業務系統」真正做完整的人 | 一個有學生端和管理端的考試平台 |
|
||||
|
||||
無論做哪一個，大作業都建議至少準備這 3 個交付物：
|
||||
|
||||
- 一個可運行的項目倉庫
|
||||
- 一個可訪問的演示鏈接
|
||||
- 一份 README 和一段演示影片
|
||||
|
||||
<NavGrid>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="大作業 1：構建第一個現代應用程序 - 全棧應用"
|
||||
description="綜合運用所學知識，獨立完成一個功能完整的全棧應用開發"
|
||||
href="/zh-tw/stage-2/assignments/copywriting-platform-supabase/"
|
||||
title="大作業 1：第一個 SaaS 全棧應用——文案生成網站"
|
||||
description="從零打造一個 AI 營銷文案工作台，涵蓋登錄、生成、支付、管理後台"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="大作業 2：現代前端組件庫 + Trae 實戰"
|
||||
description="使用現代組件庫與 Trae IDE，高效構建複雜的前端界面"
|
||||
href="/zh-tw/stage-2/assignments/exam-management-express/"
|
||||
title="大作業 2：在線考試與管理系統"
|
||||
description="構建在線考試系統，支持自動出題、答題、後台管理"
|
||||
/>
|
||||
</NavGrid>
|
||||
|
||||
如果你已經完成了上面兩個主線項目，或者想按自己的技術方向做作品集，可以繼續從下面這些擴展選題裡選一題深入：
|
||||
|
||||
<NavGrid>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/assignments/modern-landing-page/"
|
||||
title="擴展作業：現代 Web 落地頁工程"
|
||||
description="練習價值表達、轉化路徑、CTA 設計與基礎埋點，做一個真正能承接流量的頁面"
|
||||
/>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/assignments/custom-dify-agent-platform/"
|
||||
title="擴展作業：類 Dify 智能體編排平台"
|
||||
description="實現智能體管理、對話、日誌與權限控制，做一個最小可用的 AI 平台"
|
||||
/>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/assignments/travel-planning-agent-platform/"
|
||||
title="擴展作業：智能旅遊規劃 Agent 編排平台"
|
||||
description="圍繞結構化輸入、Agent 編排和歷史計劃管理，做一個可執行的 AI 旅行規劃產品"
|
||||
/>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/assignments/movie-recommendation-springboot/"
|
||||
title="擴展作業：Spring Boot 電影推薦系統"
|
||||
description="結合 Spring Boot、評分收藏與可解釋推薦，完成一個完整推薦系統原型"
|
||||
/>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/assignments/simple-grocery-microservices/"
|
||||
title="擴展作業：生鮮電商微服務系統"
|
||||
description="練習服務拆分、網關轉發、庫存與訂單協作，體驗從單體到微服務的工程思路"
|
||||
/>
|
||||
<NavCard
|
||||
href="/zh-tw/stage-2/assignments/traffic-data-visualization-go/"
|
||||
title="擴展作業：Go 交通資料分析與可視化平台"
|
||||
description="從資料接入、窗口聚合到趨勢看板與告警，做一個完整的資料產品原型"
|
||||
/>
|
||||
</NavGrid>
|
||||
|
||||
### AI 能力擴展
|
||||
|
||||
<NavGrid>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="AI 一：Dify 入門與知識庫集成"
|
||||
href="/zh-tw/stage-2/ai-capabilities/dify-knowledge-base/"
|
||||
title="Dify 入門與知識庫集成"
|
||||
description="學習使用 Dify 構建 AI 應用，並集成私有知識庫"
|
||||
/>
|
||||
<NavCard
|
||||
href="#"
|
||||
title="AI 二：學會查詢 AI 詞典與集成多模態 API"
|
||||
description="探索更多 AI 能力，集成視覺、語音等多模態 API"
|
||||
/>
|
||||
</NavGrid>
|
||||
|
||||
|
||||
## 適合人群
|
||||
|
||||
- 有一定編程基礎，想系統學習全棧開發的開發者
|
||||
- 有一定程式設計基礎，想系統學習全棧開發的開發者
|
||||
- 希望從產品經理轉型為全棧工程師的學習者
|
||||
- 想要掌握現代開發工具和工作流的初中級開發者
|
||||
- 希望獨立開發完整產品的創業者
|
||||
@@ -121,6 +188,6 @@
|
||||
|
||||
- 完成「新手與產品原型」階段，或具備同等基礎知識
|
||||
- 了解基本的 HTML/CSS/JavaScript 概念
|
||||
- 對 AI 編程工具有初步了解
|
||||
- 對 AI 程式設計工具有初步了解
|
||||
|
||||
準備好深入全棧開發了嗎？點擊左側導航開始學習吧！
|
||||
|
||||
Reference in New Issue
Block a user