delorex/test-repo
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(docs): integrate version2 curriculum and stage-3 updates

Browse Source 
概要
- 将 version2 分支的课程结构重构、第三阶段章节新增、示例资源迁移、高级 RAG 文档与 Vercel 部署配置等整合为 main 上的一次汇总提交

内容导航与 README 调整
- 更新 README 的总体介绍文案，引入“第零阶段 + 第一到第三阶段”的完整学习路径描述
- 将原先的“三阶段实战路径”说明替换为新版分阶段描述，突出从小游戏到跨平台复杂应用的学习节奏
- 删除已过时的“第二次更新将在分支 version2 合并到主分支”的提示，改为直接以 main 为主线
- 统一 README 顶部标题和排版风格，保证中英文导航、徽章展示等视觉结构一致

课程结构与章节导航更新
- 调整 docs 目录下的学习阶段导航结构，使 README 中的导航表与各 stage 实际目录对齐
- 补全并创建 stage-3 相关章节入口文件，用于承载高级阶段的课程内容
- 新增或更新以下章节入口：
  - 高级核心技能：
    - docs/stage-3/core-skills/3.1-mcp-claudecode-skills/index.md
    - docs/stage-3/core-skills/3.2-long-running-tasks/index.md
  - 多平台开发：
    - docs/stage-3/cross-platform/3.3-wechat-miniprogram/index.md
    - docs/stage-3/cross-platform/3.4-wechat-miniprogram-backend/index.md
    - docs/stage-3/cross-platform/3.5-android-app/index.md
    - docs/stage-3/cross-platform/3.6-ios-app/index.md
  - 个人品牌：
    - docs/stage-3/personal-brand/3.7-personal-website-blog/index.md
- 保持 stage-0、stage-1、stage-2 既有章节结构不变的前提下，对导航表格进行排版和链接校正，使整体课程地图清晰、可点击

示例与图片资源重组
- 将原先位于 docs/examples/example1/images/ 下的微信小程序示例图片，整体迁移到 stage-3 的正式课程路径中：
  - 目标路径：docs/stage-3/3.3-how-to-build-a-wechat-miniprogram/example1/images/
- 通过 rename 方式保留 git 历史关系，避免图片资源被视为完全新增，从而方便后续追踪
- 为微信小程序示例新增 index 页面：
  - docs/stage-3/3.3-how-to-build-a-wechat-miniprogram/example1/index.md
- 使该示例在“高级三：多平台开发：如何构建微信小程序”章节中有清晰的入口，对应实际实战内容

高级 RAG 与 AI 进阶文档
- 新增一篇系统介绍 RAG 的高级文档：
  - docs/stage-3/ai-advanced/3.a1-rag-introduction/extra5-what-is-rag-and-how-does-it-work-and-future.md
- 覆盖内容包括：RAG 的基本概念、典型架构、工作流程以及未来演进方向，为第三阶段的复杂应用提供知识检索基础
- 配套引入多张插图，帮助读者从架构图和流程视角理解 RAG：
  - docs/stage-3/ai-advanced/3.a1-rag-introduction/images/image1.png ~ image15.png

部署与工程配置
- 新增 vercel.json 配置文件，为项目在 Vercel 上的部署提供基础配置
  - 明确文档构建产物的输出路径和静态站点托管方式
  - 为之后的一键部署和自动化预览打下基础

依赖与锁文件更新
- 调整 package.json 中与新版文档结构和部署相关的配置，保持脚本和依赖与当前课程形态同步
- 更新 package-lock.json，以反映最新的依赖树和版本锁定状态
- 保证在执行 npm install / npm run build 时，依赖环境与 version2 中的实际使用情况一致

兼容性与行为说明
- 该提交通过 npm run build 验证，确保在整合 version2 内容后，VitePress 构建过程正常完成
- main 分支上的历史被压缩为一条有语义的“第二次大更新”提交，详细的开发过程仍保留在 version2 分支，用于后续需要时回溯
This commit is contained in:
sanbuphy
2026-01-12 12:21:35 +08:00
parent 307a37cdb9
commit a4b583b13f
632 changed files with 18082 additions and 8092 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/deploy.yml
+60
View File
@@ -0,0 +1,60 @@
# Sample workflow for building and deploying a VitePress site to GitHub Pages
name: Deploy VitePress site to Pages
on:
# Runs on pushes targeting the `main` branch. Change this to `master` if you're using `master` branch.
push:
branches: [main, master, version2]
# Allows you to run this workflow manually from the Actions tab
workflow_dispatch:
# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
contents: read
pages: write
id-token: write
# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
concurrency:
group: pages
cancel-in-progress: false
jobs:
# Build job
build:
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
with:
fetch-depth: 0 # Not needed if lastUpdated is not enabled
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
cache: npm
- name: Setup Pages
uses: actions/configure-pages@v4
- name: Install dependencies
run: npm ci
- name: Build with VitePress
run: npm run build
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/.vitepress/dist
# Deployment job
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
needs: build
runs-on: ubuntu-latest
name: Deploy
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
.gitignore
+4 -2
View File
@@ -1,3 +1,5 @@
.DS_Store .DS_Store
node_modules/* node_modules
tools/* tools/*
docs/.vitepress/dist
docs/.vitepress/cache
.prettierrc
+5
View File
@@ -0,0 +1,5 @@
{
"semi": false,
"singleQuote": true,
"trailingComma": "none"
}
.vscode/settings.json
Vendored
+12 -2
View File
@@ -1,3 +1,13 @@
{ {
"cSpell.words": [] "cSpell.words": [],
} "pasteImage.path": "${currentFileDir}/images",
"pasteImage.defaultName": "${currentFileNameWithoutExt}-YYYY-MM-DD-HH-mm-ss",
"pasteImage.prefix": "images/",
"pasteImage.insertPattern": "![](${imageFilePath})",
"pasteImage.basePath": "${currentFileDir}/images",
"markdown.copyFiles.destination": {
"*.md": "images/${fileName}"
},
"markdown.editor.drop.enabled": false,
"markdown.editor.pasteUrlAsFormattedLink.enabled": false
}
CLAUDE.md
+153
View File
@@ -0,0 +1,153 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is **Easy-Vibe**, an educational curriculum for learning AI Vibe Coding from zero to advanced levels. It's a documentation-based project using Docsify to serve educational content about AI-assisted software development.
The curriculum follows a progressive four-stage structure:
- **Stage 0 (幼儿园)**: Introduction to AI programming through games
- **Stage 1 (AI 产品经理)**: Building AI-powered web application prototypes
- **Stage 2 (初中级开发工程师)**: Full-stack development with databases and deployment
- **Stage 3 (高级开发工程师)**: Cross-platform development (WeChat mini-programs, Android apps, MCP)
## Development Commands
### Start Local Documentation Server
```bash
npm install # Install dependencies (first time only)
npm run dev # Start docsify server on port 3000
# or
npm start # Same as npm run dev
```
The documentation will be available at `http://localhost:3000`
### Build/Run Commands
- `npm run dev` - Serves the documentation using docsify-cli on port 3000
- No build step required - docsify serves markdown files directly
## Project Architecture
### Directory Structure
```
easy-vibe/
├── docs/ # Main documentation content (served by docsify)
│ ├── index.html # Docsify configuration and plugins
│ ├── _sidebar.md # Sidebar navigation structure
│ ├── README.md # Homepage (symlink to root README.md)
│ ├── stage-0/ # Stage 0 content (幼儿园)
│ ├── stage-1/ # Stage 1 content (AI 产品经理)
│ ├── stage-2/ # Stage 2 content (初中级开发工程师)
│ ├── stage-3/ # Stage 3 content (高级开发工程师)
│ ├── appendix/ # Reference materials (AI capability dictionary)
│ ├── examples/ # Practical examples and tutorials
│ ├── extra/ # Additional knowledge (Git, API, RAG, etc.)
│ └── project/ # Legacy project documentation
├── assets/ # Images and static assets (symlinked in docs/)
├── package.json # Project dependencies and scripts
└── README.md # Project overview and contribution guide
```
### Content Organization
Each stage follows a numbered chapter structure:
```
stage-{N}/
└── {N}.{M}-{chapter-name}/
├── index.md # Main content file
└── images/ # Chapter-specific images
```
Example: `stage-1/1.1-introduction-to-ai-ide/index.md`
### Documentation System (Docsify)
The project uses **Docsify** with the following key configuration in `docs/index.html`:
- **Single Sidebar**: `loadSidebar: true` with `/_sidebar.md` alias for all routes
- **Search**: Full-text search across all documentation
- **Dark Mode**: Theme toggle with localStorage persistence
- **Image Viewer**: Viewer.js for image zoom/rotate/flip
- **Code Copy**: Copy code button on all code blocks
- **Pagination**: Previous/Next navigation between chapters
- **Word Count**: Chinese word count display on each page
### Sidebar Management
The sidebar is defined in `docs/_sidebar.md`. When adding new chapters:
1. Add the chapter entry to the appropriate stage section
2. Follow the existing pattern: `* [Chapter Title](stage-{N}/{chapter-dir}/index.md)`
3. Ensure relative paths match the actual directory structure
### Asset Management
- Static assets are in `/assets/` at the root level
- Chapter-specific images go in `stage-{N}/{chapter-dir}/images/`
- Images are referenced with relative paths from the markdown file location
- Global CSS limits image display to max 80% width, 300px height with centered alignment
### Legacy Content Structure
The project maintains three legacy sections in the sidebar for backward compatibility:
1. **Project 文档** (`project/`): Older chapter-based tutorials
2. **Extra 扩展知识** (`extra/`): Supplementary topics (Git, APIs, RAG, deployment)
3. **Examples 实战案例** (`examples/`): Practical tutorials (some moved to stage-3)
When updating content, prefer integrating into the stage structure over adding to legacy sections.
## Content Guidelines
### Writing New Chapters
1. Create directory: `docs/stage-{N}/{N}.{M}-{chapter-name}/`
2. Create `index.md` with chapter content
3. Add images subdirectory if needed: `images/`
4. Update `docs/_sidebar.md` with the new entry
5. Follow Chinese language conventions (this is a Chinese curriculum)
### Content Status Markers
In README.md, use these status indicators:
- ✅ Completed
- 🚧 In progress/Under construction
### File Naming Conventions
- Use kebab-case for directories: `1.1-introduction-to-ai-ide`
- Use `index.md` for primary content files
- Images use descriptive names in their respective chapter directories
## Permissions
The project has configured bash permissions in `.claude/settings.local.json`:
- File operations: `which`, `find`, `mv`, `tree`, `cat`, `curl`, `lsof`
- Process management: `xargs ps`, `kill`
- Development: `npm run dev`
## Key Context for Development
- **Educational Focus**: This is curriculum content, not application code
- **Target Audience**: Beginners to advanced developers learning AI-assisted programming
- **Language**: Primary content is in Chinese
- **No Build Pipeline**: Docsify serves markdown directly, no compilation needed
- **Git Workflow**: Content changes should preserve formatting and structure
- **Asset Paths**: Always use relative paths from markdown file location
When making changes:
- Preserve the Docsify configuration in `docs/index.html`
- Maintain sidebar structure consistency
- Test locally with `npm run dev` before committing
- Check that image links work correctly
- Ensure dark mode styles are not broken
README.md
+68 -67
View File
@@ -3,7 +3,7 @@
<img src="./assets/head.png" alt="easy-vibe" width="100%"> <img src="./assets/head.png" alt="easy-vibe" width="100%">
</div> </div>
<div align="center"> <div align="center">
<h1>Easy-Vibe : Learn Vibe Coding from 0 to 1</h1> <h1>Easy-Vibe : Learn Vibe Coding from 0 to 1 </h1>
<img src="https://img.shields.io/github/stars/datawhalechina/easy-vibe?style=flat&logo=github" alt="GitHub stars"/> <img src="https://img.shields.io/github/stars/datawhalechina/easy-vibe?style=flat&logo=github" alt="GitHub stars"/>
<img src="https://img.shields.io/github/forks/datawhalechina/easy-vibe?style=flat&logo=github" alt="GitHub forks"/> <img src="https://img.shields.io/github/forks/datawhalechina/easy-vibe?style=flat&logo=github" alt="GitHub forks"/>
<img src="https://img.shields.io/badge/language-Chinese-brightgreen?style=flat" alt="Language"/> <img src="https://img.shields.io/badge/language-Chinese-brightgreen?style=flat" alt="Language"/>
@@ -24,11 +24,11 @@
2025年，被很多人视为AI编程的元年。越来越多的人开始用AI写代码，但往往做出来的还停留在玩具层面——不知道如何用Vibe Coding组织开发流程，不知道该选哪些工具，更不清楚从原型到上线中间还差哪些关键步骤。 2025年，被很多人视为AI编程的元年。越来越多的人开始用AI写代码，但往往做出来的还停留在玩具层面——不知道如何用Vibe Coding组织开发流程，不知道该选哪些工具，更不清楚从原型到上线中间还差哪些关键步骤。
我们采用循序渐进的**三阶段实战路径**：第一阶段掌握Vibe Coding工作方式并完成Web应用原型，第二阶段学习全栈开发与部署上线，第三阶段构建跨平台复杂应用。 我们采用循序渐进的**三阶段实战路径**：第零阶段通过小游戏快速上手AI编程，第一阶段掌握Vibe Coding工作方式并完成Web应用原型，第二阶段学习全栈开发与部署上线，第三阶段构建跨平台复杂应用。
每个阶段都配有完整项目实战，让你在真实挑战中从玩具走向产品，最终具备**将任何想法落地为可用应用**的能力。 每个阶段都配有完整项目实战，让你在真实挑战中从玩具走向产品，最终具备**将任何想法落地为可用应用**的能力。
我们相信，掌握Vibe Coding并配合系统化训练，你一个人就能成为**集前后端开发、AI能力集成、产品设计于一身的全能开发者**。 我们相信，掌握Vibe Coding并配合系统化训练，你一个人就能成为**集前后端开发、AI 能力集成、产品设计于一身的全能开发者**。
本项目主要面向三类学习者： 本项目主要面向三类学习者：
@@ -36,90 +36,91 @@
- **初中级开发者（有一定基础的学生和开发者）**：系统掌握 vibe coding 与原生 AI 应用开发。 - **初中级开发者（有一定基础的学生和开发者）**：系统掌握 vibe coding 与原生 AI 应用开发。
- **高级开发者（公司与初创、开源与独立开发者）**：支持团队和个人快速搭建、验证与迭代原生 AI 应用。 - **高级开发者（公司与初创、开源与独立开发者）**：支持团队和个人快速搭建、验证与迭代原生 AI 应用。
### 你将收获什么？
- 理解什么是 vibe coding 以及它的一般做法，掌握实现原生 AI 应用的基本路径
- 通过多个完整项目，熟悉游戏、工具类、产品原型等不同形态的 AI 应用开发
- 了解并实践 Git、API、RAG、AI IDE、Zeabur 等关键工具与基础设施
- 掌握产品思维，学会构建符合用户需求的产品
## 📖 内容导航 ## 📖 内容导航
**注: 本项目快速更新中，第二次更新在[分支 verison2](https://github.com/datawhalechina/easy-vibe/tree/version2)预计将于 1 月 20 日之前合并替换主分支，尽请期待** ### 总附录
### Project 部分 [AI 能力词典：常见 AI 核心概念与名词、场景解释](docs/appendix/ai-capability-dictionary.md)
本教程将 Project 分为三个阶段，帮助你从零开始掌握 Vibe Coding： ### 零、幼儿园
| 章节 | 关键内容 | 难度 | 状态 | | 章节 | 关键内容 | 状态 |
| :--- | :--- | :--- | :--- | | :----------------------------------------------------------------------------------------- | :------------------------------------- | :--- |
| **第一阶段：本地基础开发** | | | | | [前言：学习地图](docs/stage-0/0.1-learning-map/index.md) | 整体学习路径导览 | ✅ |
| [前言：课程学习地图](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter0-learning-map/chapter0-learning-map.md) | 课程学习地图、学习目标、常见问题解答 | 初 | ✅ | | [初级一：AI 时代，会说话就会编程](docs/stage-0/0.2-ai-capabilities-through-games/index.md) | 通过贪吃蛇等案例初步感受 AI 编程的能力 | ✅ |
| [Project 1: 如何构建贪吃蛇游戏](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter1/chapter1-how-to-build-a-snake-game.md) | 网页端 AI 编程入门、实现贪吃蛇、文字和生图 API 调用、制作小游戏 | 初 | ✅ |
| [Project 2: 探索 AI 工具的能力边界](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter2/chapter2-reach-the-capability-boundaries-of-ai-tools.md) | 提示词工程练习、AI 编程入门进阶、图片视频生成 API 进阶、理解 AI 能力边界 | 初 | ✅ |
| [Project 3: Dify 入门与知识库集成](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | Dify 平台实战、RAG 检索增强生成、Workflow 编排、Dify API 调用 | 初 | ✅ |
| **第二阶段：数据库与全栈部署** | | | |
| [Project 4: 一起做霍格沃茨画像](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter4/chapter4-lets-build-hogwarts-portraits.md) | 前端原型设计、前端原型转代码、AI IDE 入门、Dify API 集成、网页部署 | 中 | ✅ |
| [Project 5: 从数据库到 Supabase](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter5/chapter5-from-database-to-supabase.md) | 数据库与 JSON 入门、Supabase 后端服务、用户鉴权系统、边缘函数、鉴权、存储桶 | 中 | ✅ |
| [Project 6: 别急着写代码，先想一个好点子](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter6/chapter6-no-code-without-an-idea.md) | 产品思维、学会抽象思路变具体、如何制作好应用、用户需求与增长 | 中 | ✅ |
| **第三阶段：现代全栈网页应用实战** | | | |
| Project 7: 构建第一个现代应用程序-UI设计 | 现代前端组件库、前端编辑工具进阶、UI 设计规范 | 高 | 🚧 |
| Project 8: 构建第一个现代应用程序-功能设计 | 市场调研、产品 PRD 构建、原型设计深度解析、多页面架构设计 | 高 | 🚧 |
| Project 9: 构建第一个现代应用程序-全栈应用 | 全栈应用构建方案、独立后端鉴权、设计到上线开发闭环 | 高 | 🚧 |
### 扩展知识部分 ### 一、AI 产品经理
| 章节 | 关键内容 | 难度 | 状态 | | 章节 | 关键内容 | 状态 |
| :--- | :--- | :--- | :--- | | :---------------------------------------------------------------------------------- | :------------------------------------------------ | :--- |
| [扩展知识 1: 什么是 Git 和 GitHub](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra1/extra1-what-is-git-and-what-is-github.md) | Git 版本控制、GitHub 协作流程、代码仓库管理、SSH 配置 | 初 | ✅ | | [初级二：认识 AI IDE 工具](docs/stage-1/1.1-introduction-to-ai-ide/index.md) | 学会使用 IDE，掌握界面结构和高效提示方式 | ✅ |
| [扩展知识 2: 什么是 API](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra2/extra2-what-is-api.md) | API 原理与机制、接口请求/响应、第三方服务集成、HTTP 基础 | 初 | ✅ | | [初级三：动手做出原型](docs/stage-1/1.2-building-prototype/index.md) | 从产品分析拆解，到多页面产品原型实现的完整闭环 | ✅ |
| [扩展知识 3: AI 词典](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra3/extra3-ai-capability-starter-handbook.md) | AI 能力全景图、主流模型选型 (LLM/图像/语音/视频/时间序列)、AI 工程能力全景图 | 初 | ✅ | | [初级四：给原型加上 AI 能力](docs/stage-1/1.3-integrating-ai-capabilities/index.md) | 理解并完成常见 AI 能力（文本图片视频）的 API 接入 | ✅ |
| [扩展知识 4: 什么是 AI IDE 和 Trae](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra4/extra4-what-is-ai-ide-and-trae.md) | IDE 与 AI IDE 概念、Trae 工具实战入门 | 初 | ✅ | | [初级五：完整项目实战](docs/stage-1/1.4-complete-project-practice/index.md) | 模拟真实场景、接受用户反馈迭代并完成项目展示 | ✅ |
| [扩展知识 5: 什么是 RAG 以及它如何工作](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md) | RAG 技术原理、文档切片与索引、RAG 进阶方案、RAG 企业方案 | 中 | ✅ | | [大作业：做一个完整的 Web 应用原型并展示](docs/stage-1/1.5-final-project/index.md) | 独立用 AI IDE 落地并演示一个可用 Web 应用 | ✅ |
| [扩展知识 6: Zeabur 与 Web 应用部署](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | Web 应用部署、Zeabur 平台使用方法 | 中 | ✅ |
| [扩展知识 7: CLI AI 编程工具](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | 终端介绍、CLI AI 编程工具、Claude Code/Codex | 中 | ✅ |
| 扩展知识 8: MCP 与 ClaudeCode skills | MCP 协议、ClaudeCode Skills、工具扩展机制 | 中 | 🚧 |
| 扩展知识 9: 使用 Trae SOLO 模式深度开发 | PRD 生成、需求驱动开发、前后端集成 | 中 | 🚧 |
| 扩展知识 10: 尝试提高 vibe coding 的品味 | 测试驱动开发、设立中间检查点、约束条件 | 高 | 🚧 |
| 扩展知识 11: 如何让 Coding Tools 长时间工作 | 自动化开发配置、长时间任务管理、CLI 工具稳定性优化 | 高 | 🚧 |
### 实践项目部分 #### 附录
| 章节 | 关键内容 | 难度 | 状态 | | 章节 | 关键内容 | 状态 |
| :--- | :--- | :--- | :--- | | :-------------------------------------------------------------------------- | :---------------------------------------- | :--- |
| [Example 0-1: 使用 Vibe Coding 工具完成贪吃蛇教程](https://github.com/datawhalechina/easy-vibe/blob/main/docs/examples/example0/vibe-coding-tools-snake-game-tutorial/README.md) | 基于 Vibe Coding 工具复现与扩展贪吃蛇游戏的补充文章与实践记录 | 中 | 🚧 | | [附录A：产品思维补充](docs/stage-1/appendix-a-product-thinking/index.md) | 从想法评估到需求拆解与 MVP 的产品思维框架 | ✅ |
| [Example 0-2: 使用 Vibe Coding 工具与设计智能体搭建网站](https://github.com/datawhalechina/easy-vibe/blob/main/docs/examples/example0/vibe-coding-tools-build-website-with-ai-coding-and-design-agents/README.md) | 结合 Vibe Coding 工具与设计智能体从 0 到 1 搭建网站的补充文章与实践记录 | 中 | 🚧 | | [附录B：常见报错及解决方案](docs/stage-1/appendix-b-common-errors/index.md) | vibe coding 中的常见错误及排查方法 | ✅ |
| [Example 1: 如何构建微信小程序](https://github.com/datawhalechina/easy-vibe/blob/main/docs/examples/example1/example1-how-to-build-a-wechat-miniprogram.md) | 了解微信小程序生态与开发链路，结合 Trae + HBuilderX + 微信开发者工具，全流程开发贪吃蛇小程序 | 中 | ✅ |
| Example 2: 如何构建微信小程序-包含后端 | 使用 vibe coding 从 0 到 1 构建具有后端数据库的微信小程序 | 中 | 🚧 |
| Example 3: 如何构建安卓程序 | 结合 Expo，使用 vibe coding 从 0 到 1 构建安卓应用并上架 | 高 | 🚧 |
### 二、初中级开发工程师
### 路线图 #### 前端部分
- [ ] 1 月 11 日前实现大纲更新，更符合逻辑和学习习惯。 | 章节 | 关键内容 | 状态 |
| :------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------- | :--- |
| [前端零：使用 lovart 生产素材](docs/stage-2/frontend/2.0-lovart-assets/) | 学会用 lovart 批量生成人物、场景等视觉素材，为 UI 设计和前端开发提供素材基础 | 🚧 |
| [前端一：Figma 与 MasterGo 入门](docs/stage-2/frontend/2.1-figma-mastergo/) | 用设计工具梳理信息架构和页面结构，为前端实现打基础 | 🚧 |
| [前端二：构建第一个现代应用程序-UI 设计](docs/stage-2/frontend/2.2-ui-design/) | 基于设计稿完成组件化界面，实现从设计到代码的第一条链路 | 🚧 |
| [前端三：参考 UI 设计规范与多产品 UI 设计](docs/stage-2/frontend/2.3-multi-product-ui/) | 围绕统一主视觉扩展多产品界面，练习系统化设计能力 | 🚧 |
| [前端四：一起做霍格沃茨画像](docs/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits) | 从 0 到 1 做出接入 AI 能力的前端应用，串联设计与开发 | 🚧 |
#### 更新 #### 后端与全栈部分
- [ ] 补全未完成的 project extra 文档 | 章节 | 关键内容 | 状态 |
- [ ] 补充关于 IOS 平台 vibecoding 文档 | :------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------ | :--- |
- [ ] 补充关于更多开发基础知识的 vibe coding 理解方案 | [后端一：什么是 API](docs/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api) | 理解 HTTP 接口与请求响应模型，为后端集成与联调做准备 | 🚧 |
| [后端二：从数据库到 Supabase](docs/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase) | 在 Supabase 上落地数据库和 API，打通数据模型与前端页面 | 🚧 |
| [后端三：大模型辅助编写接口代码与接口文档](docs/stage-2/backend/2.3-ai-interface-code/) | 用大模型协助生成接口与数据库文档及代码，实现可读可测的后端 | 🚧 |
| [后端四：Git 工作流](docs/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github) | 在 Git 工作流中管理代码，进行版本控制和协作 | 🚧 |
| [后端五：Zeabur 部署](docs/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications) | 将应用部署到 Zeabur 上线 | 🚧 |
| [后端六：现代 CLI 开发工具](docs/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development) | 使用 CLI 类 AI 编程工具加速开发与调试，形成个人工程化工作流 | 🚧 |
| [后端七：如何集成 Stripe 等收费系统](docs/stage-2/backend/2.7-stripe-payment/) | 接入支付系统，完成收费链路与基础结算流程 | 🚧 |
| [大作业 1：构建第一个现代应用程序-全栈应用](docs/stage-2/assignments/2.1-fullstack-app/) | 综合前端、后端与支付模块，完成可上线的全栈 Web 应用 | 🚧 |
| [大作业 2：现代前端组件库 + Trae 实战](docs/stage-2/assignments/2.2-modern-frontend-trae/) | 使用现代前端组件库与 Trae，独立完成可登录注册并支持收费的产品 | 🚧 |
#### 修复 #### AI 能力附录
- [ ] 根据内测内容反馈补充润色 project 1 与 2 、extra 2 的内容，修复不自然的语言转换部分 | 章节 | 关键内容 | 状态 |
- [ ] 修复 extra 失效部分内容 | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :--- |
- [ ] 将未推送的教程补充推送，同时优化在线阅读体验 | [AI 一：Dify 入门与知识库集成](docs/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration) | 用 Dify Workflow 与基础 RAG 搭建工具类产品，为后续应用升级打样 | 🚧 |
- [ ] 修复英文版仓库不自然的部分 | [AI 二：学会查询 AI 词典与集成多模态 API](docs/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook) | 学会查找合适的模型与 API，并把文本、图像等多模态能力接入产品 | 🚧 |
### 三、高级开发工程师
| 章节 | 关键内容 | 状态 |
| :-------------------------------------------------------------------- | :----------------------------------------------------------- | :--- |
| [高级一：MCP 与 ClaudeCode Skills](docs/stage-3/core-skills/3.1-mcp-claudecode-skills/) | 通过 MCP 与 Skills 扩展 IDE 能力，把外部服务接成工具 | 🚧 |
| [高级二：如何让 Coding Tools 长时间工作](docs/stage-3/core-skills/3.2-long-running-tasks/) | 设计和配置长时间运行的任务，让 Coding Tools 更稳定可靠 | 🚧 |
| [高级三：多平台开发：如何构建微信小程序](docs/stage-3/cross-platform/3.3-wechat-miniprogram/) | 了解微信小程序生态，从官方模板到上线完成一个前端小程序 | 🚧 |
| [高级四：多平台开发：如何构建微信小程序-包含后端](docs/stage-3/cross-platform/3.4-wechat-miniprogram-backend/) | 在小程序中接入数据库与后端逻辑，打通完整业务闭环 | 🚧 |
| [高级五：多平台开发：如何构建安卓程序](docs/stage-3/cross-platform/3.5-android-app/) | 使用 Expo 等工具，完成 Web/原生一体化的安卓应用开发 | 🚧 |
| [高级六：多平台开发：如何构建 iOS 程序](docs/stage-3/cross-platform/3.6-ios-app/) | 使用 Expo 等工具，完成 Web/原生一体化的 iOS 应用开发 | 🚧 |
| [高级七：如何构建属于自己的个人网页与学术博客](docs/stage-3/personal-brand/3.7-personal-website-blog/) | 从选型、搭建到部署，构建展示个人项目与学术成果的长久在线主页 | 🚧 |
#### AI 能力附录
| 章节 | 关键内容 | 状态 |
| :-------------------------------------------------------------------- | :------------------------------------------------------ | :--- |
| [高级 AI 一：什么是 RAG 以及它如何工作](docs/stage-3/ai-advanced/3.a1-rag-introduction/extra5/extra5-what-is-rag-and-how-does-it-work-and-future) | 系统理解 RAG 原理与常见架构，为复杂应用提供知识检索基础 | 🚧 |
| [高级 AI 二：中高级 RAG 与工作流编排：以 LangGraph 为例](docs/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/) | 使用 LangGraph 等工具设计多步工作流与中高级 RAG 系统 | 🚧 |
## 如何学习 ## 如何学习
- 建议具备基本编程经验（任意一门语言均可），并对 AI 与产品开发有兴趣 - 根据个人能力，选择性地阅读和实践相关章节，如果有问题欢迎 issue 提问。
- 按照 Project 模块从 0 到 6 依次实践，完成从小游戏到完整应用原型的进阶
- 在 Extra 模块中补充 Git、API、RAG、部署等通识知识，完善你的 AI 开发知识图谱
- 遇到问题时优先尝试自己排查与检索，再对照教程与源码进行比对和反思
你可以根据个人时间与需求，选择性地阅读和实践相关章节，但推荐至少完成全部 Project，以形成一套完整的实践闭环。
## 本地启动本课件 ## 本地启动本课件
docs/.nojekyll
View File
docs/.vitepress/config.mjs
+301
View File
@@ -0,0 +1,301 @@
import { defineConfig } from 'vitepress'
export default defineConfig({
base: '/',
title: 'Easy-Vibe Tutorial',
description: 'Easy-Vibe 中文实战课 - 零基础学会用 AI 干实际工作',
head: [['link', { rel: 'icon', href: '/logo.png' }]],
themeConfig: {
logo: '/logo.png',
search: {
provider: 'local'
},
outline: {
level: 'deep',
label: '页面导航'
},
nav: [
{ text: '首页', link: '/' },
{ text: '纯新手', link: '/stage-0/0.1-learning-map/' },
{ text: '产品经理', link: '/stage-1/1.1-introduction-to-ai-ide/' },
{
text: '初中级开发',
link: '/stage-2/frontend/2.0-lovart-assets/'
},
{
text: '高级开发',
link: '/stage-3/core-skills/3.1-mcp-claudecode-skills/'
},
{ text: '附录', link: '/appendix/ai-capability-dictionary' }
],
sidebar: {
'/stage-0/': [
{ text: '0.1 学习地图', link: '/stage-0/0.1-learning-map/' },
{
text: '0.2 AI 时代，会说话就会编程',
link: '/stage-0/0.2-ai-capabilities-through-games/'
}
],
'/stage-1/': [
{
text: '1.1 认识 AI IDE 工具',
link: '/stage-1/1.1-introduction-to-ai-ide/'
},
{
text: '1.2 动手做出原型',
link: '/stage-1/1.2-building-prototype/'
},
{
text: '1.3 给原型加上 AI 能力',
link: '/stage-1/1.3-integrating-ai-capabilities/'
},
{
text: '1.4 完整项目实战',
link: '/stage-1/1.4-complete-project-practice/'
},
{
text: '1.5 大作业：完成一个 Web 应用原型',
link: '/stage-1/1.5-final-project/'
},
{
text: '附录 A：产品思维补充',
link: '/stage-1/appendix-a-product-thinking/'
},
{
text: '附录 B：常见报错及解决方案',
link: '/stage-1/appendix-b-common-errors/'
}
],
'/stage-2/': [
{
text: '前端开发',
collapsed: false,
items: [
{
text: '前端零：使用 Lovart 生产素材',
link: '/stage-2/frontend/2.0-lovart-assets/'
},
{
text: '前端一：Figma 与 MasterGo 入门',
link: '/stage-2/frontend/2.1-figma-mastergo/'
},
{
text: '前端二：构建第一个现代应用程序 - UI 设计',
link: '/stage-2/frontend/2.2-ui-design/'
},
{
text: '前端三：参考 UI 设计规范与多产品 UI 设计',
link: '/stage-2/frontend/2.3-multi-product-ui/'
},
{
text: '前端四：一起做霍格沃茨画像',
link: '/stage-2/frontend/2.4-hogwarts-portraits/chapter4-lets-build-hogwarts-portraits'
}
]
},
{
text: '后端与全栈',
collapsed: false,
items: [
{
text: '后端一：什么是 API',
link: '/stage-2/backend/2.1-what-is-api/extra2/extra2-what-is-api'
},
{
text: '后端二：从数据库到 Supabase',
link: '/stage-2/backend/2.2-database-supabase/chapter5/chapter5-from-database-to-supabase'
},
{
text: '后端三：大模型辅助编写接口代码与接口文档',
link: '/stage-2/backend/2.3-ai-interface-code/'
},
{
text: '后端四：Git 工作流',
link: '/stage-2/backend/2.4-git-workflow/extra1/extra1-what-is-git-and-what-is-github'
},
{
text: '后端五：Zeabur 部署',
link: '/stage-2/backend/2.5-zeabur-deployment/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications'
},
{
text: '后端六：现代 CLI 开发工具',
link: '/stage-2/backend/2.6-modern-cli/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development'
},
{
text: '后端七：如何集成 Stripe 等收费系统',
link: '/stage-2/backend/2.7-stripe-payment/'
}
]
},
{
text: '大作业',
collapsed: false,
items: [
{
text: '大作业 1：构建第一个现代应用程序 - 全栈应用',
link: '/stage-2/assignments/2.1-fullstack-app/'
},
{
text: '大作业 2：现代前端组件库 + Trae 实战',
link: '/stage-2/assignments/2.2-modern-frontend-trae/'
}
]
},
{
text: 'AI 能力附录',
collapsed: false,
items: [
{
text: 'AI 一：Dify 入门与知识库集成',
link: '/stage-2/ai-capabilities/2.1-dify-knowledge-base/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration'
},
{
text: 'AI 二：学会查询 AI 词典与集成多模态 API',
link: '/stage-2/ai-capabilities/2.2-multimodal-api/extra3/extra3-ai-capability-starter-handbook'
}
]
}
],
'/stage-3/': [
{
text: '核心技能',
collapsed: false,
items: [
{
text: '高级一：MCP 与 ClaudeCode Skills',
link: '/stage-3/core-skills/3.1-mcp-claudecode-skills/'
},
{
text: '高级二：如何让 Coding Tools 长时间工作',
link: '/stage-3/core-skills/3.2-long-running-tasks/'
}
]
},
{
text: '多平台开发',
collapsed: false,
items: [
{
text: '高级三：如何构建微信小程序',
link: '/stage-3/cross-platform/3.3-wechat-miniprogram/example1/index'
},
{
text: '高级四：如何构建微信小程序（包含后端）',
link: '/stage-3/cross-platform/3.4-wechat-miniprogram-backend/'
},
{
text: '高级五：如何构建安卓程序',
link: '/stage-3/cross-platform/3.5-android-app/'
},
{
text: '高级六：如何构建 iOS 程序',
link: '/stage-3/cross-platform/3.6-ios-app/'
}
]
},
{
text: '个人品牌',
collapsed: false,
items: [
{
text: '高级七：如何构建属于自己的个人网页与学术博客',
link: '/stage-3/personal-brand/3.7-personal-website-blog/'
}
]
},
{
text: 'AI 能力附录',
collapsed: false,
items: [
{
text: '高级 AI 一：什么是 RAG 以及它如何工作',
link: '/stage-3/ai-advanced/3.a1-rag-introduction/extra5/extra5-what-is-rag-and-how-does-it-work-and-future'
},
{
text: '高级 AI 二：中高级 RAG 与工作流编排 - 以 LangGraph 为例',
link: '/stage-3/ai-advanced/3.a2-langgraph-advanced-rag/'
}
]
}
],
'/guide/': [
{
text: '课程指南',
items: [{ text: '课程介绍', link: '/guide/introduction' }]
}
],
'/extra/': [
{
text: 'Extra 扩展知识（旧版，已迁移到 Stage 2/3）',
items: [
{
text: 'Extra 1: Git & GitHub',
link: '/extra/extra1/extra1-what-is-git-and-what-is-github'
},
{
text: 'Extra 2: What is API',
link: '/extra/extra2/extra2-what-is-api'
},
{
text: 'Extra 5: What is RAG',
link: '/extra/extra5/extra5-what-is-rag-and-how-does-it-work-and-future'
},
{
text: 'Extra 6: Zeabur Deployment',
link: '/extra/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications'
},
{
text: 'Extra 7: CLI AI Tools & TDD',
link: '/extra/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development'
}
]
}
],
'/examples/': [
{
text: 'Examples 实战案例（旧版，已迁移到 Stage 0/3）',
items: [
{
text: 'Ex 0.1: Snake Game',
link: '/examples/example0/example0-1/vibe-coding-tools-snake-game-tutorial'
},
{
text: 'Ex 0.2: Build Website with AI',
link: '/examples/example0/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents'
}
]
}
],
'/project/': [
{
text: 'Project 文档（旧版，已迁移到 Stage 2）',
items: [
{
text: '前端四：霍格沃茨画像',
link: '/project/chapter4/chapter4-lets-build-hogwarts-portraits'
},
{
text: '后端二：Supabase 数据库',
link: '/project/chapter5/chapter5-from-database-to-supabase'
},
{
text: 'AI 一：Dify & Knowledge Base',
link: '/project/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration'
}
]
}
],
'/appendix/': [
{
text: '附录',
items: [
{ text: 'AI 能力词典', link: '/appendix/ai-capability-dictionary' }
]
}
]
},
socialLinks: [
{ icon: 'github', link: 'https://github.com/datawhalechina/easy-vibe' }
]
}
})
docs/.vitepress/theme/Layout.vue
+27
View File
@@ -0,0 +1,27 @@
<script setup>
import DefaultTheme from 'vitepress/theme'
import { useData } from 'vitepress'
import TextType from './components/TextType.vue'
const { frontmatter } = useData()
const homeTaglineTyping = {
typingSpeed: 45,
initialDelay: 0,
pauseDuration: 2500,
postDeletingDelay: 500,
deletingSpeed: 18
}
</script>
<template>
<DefaultTheme.Layout>
<template #home-hero-info-after>
<div v-if="frontmatter.layout === 'home' && frontmatter.hero?.tagline" class="vp-typed-tagline">
<ClientOnly>
<TextType :text="frontmatter.hero.tagline" v-bind="homeTaglineTyping" :loop="true" />
</ClientOnly>
</div>
</template>
</DefaultTheme.Layout>
</template>
docs/.vitepress/theme/components/TextType.vue
+260
View File
@@ -0,0 +1,260 @@
<script setup>
import { computed, onMounted, onUnmounted, ref, useAttrs, watchEffect } from 'vue'
const props = defineProps({
text: {
type: [String, Array],
required: true
},
as: {
type: [String, Object],
default: 'div'
},
typingSpeed: {
type: Number,
default: 50
},
initialDelay: {
type: Number,
default: 0
},
pauseDuration: {
type: Number,
default: 2000
},
postDeletingDelay: {
type: Number,
default: 0
},
deletingSpeed: {
type: Number,
default: 30
},
loop: {
type: Boolean,
default: true
},
className: {
type: String,
default: ''
},
showCursor: {
type: Boolean,
default: true
},
hideCursorWhileTyping: {
type: Boolean,
default: false
},
cursorCharacter: {
type: String,
default: '|'
},
cursorClassName: {
type: String,
default: ''
},
cursorBlinkDuration: {
type: Number,
default: 0.5
},
textColors: {
type: Array,
default: () => []
},
variableSpeed: {
type: Object,
default: null
},
onSentenceComplete: {
type: Function,
default: null
},
startOnVisible: {
type: Boolean,
default: false
},
reverseMode: {
type: Boolean,
default: false
}
})
const isClient = typeof window !== 'undefined'
const attrs = useAttrs()
const displayedText = ref('')
const currentCharIndex = ref(0)
const isDeleting = ref(false)
const currentTextIndex = ref(0)
const isVisible = ref(!props.startOnVisible)
const containerRef = ref(null)
const textArray = computed(() => (Array.isArray(props.text) ? props.text : [props.text]))
const cursorStyle = computed(() => ({
animationDuration: `${props.cursorBlinkDuration}s`
}))
const currentColor = computed(() => {
if (!props.textColors.length) return undefined
return props.textColors[currentTextIndex.value % props.textColors.length]
})
const getRandomSpeed = () => {
if (!props.variableSpeed) return props.typingSpeed
const min = typeof props.variableSpeed.min === 'number' ? props.variableSpeed.min : props.typingSpeed
const max = typeof props.variableSpeed.max === 'number' ? props.variableSpeed.max : props.typingSpeed
if (max <= min) return min
return Math.random() * (max - min) + min
}
let observer
onMounted(() => {
if (!props.startOnVisible || !containerRef.value) return
observer = new IntersectionObserver(
entries => {
for (const entry of entries) {
if (entry.isIntersecting) {
isVisible.value = true
break
}
}
},
{ threshold: 0.1 }
)
observer.observe(containerRef.value)
})
onUnmounted(() => {
if (observer) observer.disconnect()
})
watchEffect(onCleanup => {
if (!isVisible.value) return
if (!textArray.value.length) {
displayedText.value = ''
return
}
const currentText = textArray.value[currentTextIndex.value] ?? ''
const processedText = props.reverseMode ? String(currentText).split('').reverse().join('') : String(currentText)
if (!isClient) {
return
}
const shouldStopAtEnd = !props.loop && currentTextIndex.value === textArray.value.length - 1
let timeoutId
const schedule = () => {
if (isDeleting.value) {
if (!displayedText.value) {
isDeleting.value = false
if (props.onSentenceComplete) {
props.onSentenceComplete(textArray.value[currentTextIndex.value], currentTextIndex.value)
}
if (shouldStopAtEnd) return
timeoutId = setTimeout(() => {
currentTextIndex.value = (currentTextIndex.value + 1) % textArray.value.length
currentCharIndex.value = 0
}, props.postDeletingDelay)
return
}
timeoutId = setTimeout(() => {
displayedText.value = displayedText.value.slice(0, -1)
}, props.deletingSpeed)
return
}
if (currentCharIndex.value < processedText.length) {
timeoutId = setTimeout(() => {
displayedText.value += processedText[currentCharIndex.value]
currentCharIndex.value += 1
}, props.variableSpeed ? getRandomSpeed() : props.typingSpeed)
return
}
if (shouldStopAtEnd) return
timeoutId = setTimeout(() => {
isDeleting.value = true
}, props.pauseDuration)
}
if (currentCharIndex.value === 0 && !isDeleting.value && !displayedText.value) {
timeoutId = setTimeout(schedule, props.initialDelay)
} else {
schedule()
}
onCleanup(() => clearTimeout(timeoutId))
})
const shouldHideCursor = computed(() => {
if (!props.hideCursorWhileTyping) return false
const currentText = textArray.value[currentTextIndex.value] ?? ''
const processedText = props.reverseMode ? String(currentText).split('').reverse().join('') : String(currentText)
return currentCharIndex.value < processedText.length || isDeleting.value
})
</script>
<template>
<component
:is="as"
ref="containerRef"
:class="['text-type', className]"
v-bind="attrs"
>
<span class="text-type__content" :style="{ color: currentColor || 'inherit' }">
{{ displayedText }}
</span>
<span
v-if="showCursor"
class="text-type__cursor"
:class="[cursorClassName, shouldHideCursor ? 'text-type__cursor--hidden' : '']"
:style="cursorStyle"
>
{{ cursorCharacter }}
</span>
</component>
</template>
<style>
.text-type {
display: inline-flex;
align-items: baseline;
white-space: nowrap;
}
.text-type__content {
display: inline-block;
white-space: nowrap;
}
.text-type__cursor {
display: inline-block;
margin-left: 2px;
animation-name: text-type-blink;
animation-timing-function: ease-in-out;
animation-iteration-count: infinite;
animation-direction: alternate;
}
.text-type__cursor--hidden {
opacity: 0;
animation: none;
}
@keyframes text-type-blink {
from {
opacity: 1;
}
to {
opacity: 0;
}
}
</style>
docs/.vitepress/theme/index.js
+119
View File
@@ -0,0 +1,119 @@
import DefaultTheme from 'vitepress/theme'
import Viewer from 'viewerjs'
import 'viewerjs/dist/viewer.css'
import TypeIt from 'typeit'
import { onMounted, watch, nextTick } from 'vue'
import { useRoute, useData } from 'vitepress'
import './style.css'
export default {
extends: DefaultTheme,
setup() {
const route = useRoute()
const { frontmatter } = useData()
let viewer = null
const initViewer = () => {
// 销毁旧实例
if (viewer) {
viewer.destroy()
viewer = null
}
// 找到文章内容容器
const doc = document.querySelector('.vp-doc')
if (doc) {
// 初始化 Viewer，配置一些常用选项
viewer = new Viewer(doc, {
button: true, // 显示右上角关闭按钮
navbar: true, // 显示底部缩略图导航
title: true, // 显示图片标题（alt 属性）
toolbar: true, // 显示工具栏（缩放、旋转等）
tooltip: true, // 显示缩放百分比
movable: true, // 允许拖拽
zoomable: true, // 允许缩放
rotatable: true, // 允许旋转
scalable: true, // 允许翻转
transition: false, // 禁用自带动画，确保打开瞬间无飞入
fullscreen: true, // 允许全屏播放
shown() {
// 打开完成后，标记为 ready，CSS 此时才会介入 transition
document.body.classList.add('viewer-ready')
},
hide() {
// 关闭前移除标记，确保关闭瞬间无动画
document.body.classList.remove('viewer-ready')
},
keyboard: true, // 允许键盘控制
url: 'src', // 图片源
// 过滤掉不想查看的图片（比如表情包等小图标，如果需要的话）
filter(image) {
return !image.classList.contains('no-viewer')
}
})
}
}
const initTypewriter = () => {
const taglineData = frontmatter.value.hero?.tagline
if (Array.isArray(taglineData) && taglineData.length > 0) {
const taglineEl = document.querySelector('.VPHomeHero .tagline')
if (taglineEl) {
taglineEl.innerHTML = ''
const typeIt = new TypeIt(taglineEl, {
speed: 50,
startDelay: 500,
loop: true
})
taglineData.forEach((text) => {
typeIt.type(text).pause(2000).delete().pause(500)
})
typeIt.go()
}
}
}
const optimizeImages = () => {
const images = document.querySelectorAll('.vp-doc img')
images.forEach(img => {
if (img.complete) {
applyImageStyle(img)
} else {
img.onload = () => applyImageStyle(img)
}
})
}
const applyImageStyle = (img) => {
const { naturalWidth, naturalHeight } = img
if (!naturalWidth || !naturalHeight) return
const ratio = naturalHeight / naturalWidth
img.classList.remove('img-tall', 'img-very-tall')
if (ratio > 2) {
img.classList.add('img-very-tall')
} else if (ratio > 1.2) {
img.classList.add('img-tall')
}
}
onMounted(() => {
initViewer()
initTypewriter()
optimizeImages()
})
watch(
() => route.path,
() => nextTick(() => {
initViewer()
initTypewriter()
optimizeImages()
})
)
}
}
docs/.vitepress/theme/style.css
+38
View File
@@ -0,0 +1,38 @@
/* Custom styles for viewerjs */
.viewer-container {
z-index: 9999 !important; /* Ensure it's above everything including navbar */
}
/* Optional: Adjust backdrop opacity if needed */
.viewer-backdrop {
background-color: rgba(0, 0, 0, 0.9); /* Darker backdrop for better focus */
}
/*
Core Logic:
1. Default (opening/closing): No transition -> Instant.
2. body.viewer-ready (viewing): Force transition -> Smooth Zoom.
*/
body.viewer-ready .viewer-canvas > img {
transition: transform 0.2s ease-out !important;
}
/* Limit image max height in document content */
.vp-doc img {
max-height: 500px;
width: auto;
margin: 16px auto; /* Center with spacing */
display: block;
border-radius: 8px; /* Optional: Rounded corners */
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1); /* Optional: Shadow */
}
/* Tall images (e.g. mobile screenshots) - ratio > 1.2 */
.vp-doc img.img-tall {
max-height: 400px;
}
/* Very tall images (e.g. long screenshots) - ratio > 2 */
.vp-doc img.img-very-tall {
max-height: 300px;
}
docs/README.md
-132
View File
@@ -1,132 +0,0 @@
# Vibe Coding 101 课件
<div align="center">
<h1>Easy-Vibe</h1>
<img src="https://img.shields.io/github/stars/datawhalechina/easy-vibe?style=flat&logo=github" alt="GitHub stars"/>
<img src="https://img.shields.io/github/forks/datawhalechina/easy-vibe?style=flat&logo=github" alt="GitHub forks"/>
<img src="https://img.shields.io/badge/language-Chinese-brightgreen?style=flat" alt="Language"/>
<a href="https://github.com/datawhalechina/easy-vibe"><img src="https://img.shields.io/badge/GitHub-Project-blue?style=flat&logo=github" alt="GitHub Project"></a>
</div>
<div align="center">
[中文](https://github.com/datawhalechina/easy-vibe/blob/main/README.md) | [English](https://github.com/THU-SIGS-AIID/ai-vibe-coding-101/blob/main/README.md)
</div>
<div align="center">
<h3>📚 AI Vibe Coding 101 教程</h3>
<p>零基础，在项目制学习中掌握 Vibe Coding 与 AI 技能，构建第一个 AI 原生产品</p>
</div>
## 项目介绍
2025 年，被很多人视为 AI 编程的元年。越来越多的人已经开始用 AI 写代码，但做出来的东西往往还停留在玩具层面。且一到真正动手，大家常常会被各种门槛劝退：
- 不知道用什么 AI 编程工具写代码比较好；
- 不知道怎么把大模型的能力应用到具体产品上；
- 不清楚 AI 写出的代码，距离真实能上线运行还差多远。
通过这个项目，我们希望帮你掌握和 AI 搭档写代码的最佳实践。你将学会借助 AI 的力量，在一个又一个的项目制学习挑战中，独立完成游戏、实用工具、产品原型的实现，最后制作一款属于自己的产品。
我们相信，你一个人就可以成为前后端开发、AI 算法开发、产品经理。
### 项目受众
本项目主要面向希望系统学习 vibe coding 与原生 AI 应用开发的学习者，包括但不限于：
- 计算机科学、人工智能及相关或跨学科专业的学生，希望通过实践经验系统地介绍 vibe coding 和原生 AI 开发
- 具有基本编程技能的初中级开发人员，希望学习 vibe coding 并构建原生 AI 应用程序
- 开源爱好者和独立开发者，希望降低 AI 原生开发的门槛，并利用免费资源创建衍生作品
- 旨在快速制作原生 AI 应用程序原型的企业技术团队和 AI 初创公司
- 非开发人员角色（如产品经理），希望掌握基本开发任务并为 AI 计划提供技术支持
### 你将收获什么？
- 理解什么是 vibe coding 以及它的一般做法
- 掌握从零到一设计和实现原生 AI 应用的基本路径
- 通过多个完整项目，熟悉游戏、工具类、产品原型等不同形态的 AI 应用开发
- 了解并实践 Git、API、RAG、AI IDE、Zeabur 等关键工具与基础设施
- 掌握产品思维，学会构建符合用户需求的产品
- 在实践中形成一套可复用的 AI 原生产品开发工作流
### 路线图
- [ ] 修复 extra 失效部分内容
- [ ] 补全未完成的 project extra 文档
- [ ] 根据内测内容反馈补充润色 project 1 与 2 、extra 2 的内容
- [ ] 将未推送的教程补充推送，同时优化在线阅读体验
- [ ] 修复英文版仓库不自然的部分
## 内容导航
本教程将内容分为三个难度等级，供不同阶段的学习者参考：
- **初级**：适合 AI 编程新手，侧重于工具的基础使用与简单应用体验。
- **中级**：适合具备一定基础的开发者，涉及前后端交互、数据库集成及多模态能力。
- **高级**：适合进阶学习者，涵盖全栈开发、系统架构设计及复杂的工程化配置。
### Project 部分
| 难度 | 章节 | 关键内容 | 状态 |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------- | ---- |
| 初 | [前言：课程学习地图](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter0-learning-map/chapter0-learning-map.md) | 课程学习地图、学习目标、常见问题解答 | ✅ |
| 初 | [Project 1: 如何构建贪吃蛇游戏](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter1/chapter1-how-to-build-a-snake-game.md) | 网页 AI 编程基础、实现贪吃蛇、集成文字、生图 API | ✅ |
| 初 | [Project 2: 探索 AI 工具的能力边界](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter2/chapter2-reach-the-capability-boundaries-of-ai-tools.md) | 提示词工程练习、AI 编程基础、图片视频生成 API、理解 AI 能力边界 | ✅ |
| 初 | [Project 3: Dify 入门与知识库集成](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md) | Dify 平台实战、RAG 检索增强生成、Workflow 编排 | ✅ |
| 中 | [Project 4: 一起做霍格沃茨画像](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter4/chapter4-lets-build-hogwarts-portraits.md) | 前端原型设计、前端原型转代码、AI IDE 入门、Dify API 集成、网页部署 | ✅ |
| 中 | [Project 5: 从数据库到 Supabase](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter5/chapter5-from-database-to-supabase.md) | 数据库与 JSON 入门、Supabase 后端服务、用户鉴权系统、边缘函数、鉴权、存储桶 | ✅ |
| 中 | [Project 6: 别急着写代码，先想一个好点子](https://github.com/datawhalechina/easy-vibe/blob/main/docs/project/chapter6/chapter6-no-code-without-an-idea.md) | 产品思维、学会抽象思路变具体、如何制作好应用、用户需求与增长 | ✅ |
| 高 | Project 7: 构建第一个现代应用程序-UI设计 | 现代前端组件库、前端编辑工具进阶、UI 设计规范 | 🚧 |
| 高 | Project 8: 构建第一个现代应用程序-功能设计 | 市场调研、产品 PRD 构建、原型设计深度解析、多页面架构设计 | 🚧 |
| 高 | Project 9: 构建第一个现代应用程序-全栈应用 | 全栈应用构建方案、独立后端鉴权、设计到上线开发闭环 | 🚧 |
### 扩展知识部分
| 难度 | 章节 | 关键内容 | 状态 |
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ---- |
| 初 | [扩展知识 1: 什么是 Git 和 GitHub](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra1/extra1-what-is-git-and-what-is-github.md) | Git 版本控制、GitHub 协作流程、代码仓库管理、SSH 配置 | ✅ |
| 初 | [扩展知识 2: 什么是 API](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra2/extra2-what-is-api.md) | API 原理与机制、接口请求/响应、第三方服务集成、HTTP 基础 | ✅ |
| 初 | [扩展知识 3: AI 能力入门手册](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra3/extra3-ai-capability-starter-handbook.md) | AI 能力全景图、主流模型选型 (LLM/图像/语音/视频/时间序列)、AI 工程能力全景图 | ✅ |
| 初 | [扩展知识 4: 什么是 AI IDE 和 Trae](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra4/extra4-what-is-ai-ide-and-trae.md) | IDE 与 AI IDE 概念、Trae 工具实战入门 | ✅ |
| 中 | [扩展知识 5: 什么是 RAG 以及它如何工作](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md) | RAG 技术原理、文档切片与索引、RAG 进阶方案、RAG 企业方案 | ✅ |
| 中 | [扩展知识 6: Zeabur 与 Web 应用部署](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md) | Web 应用部署、Zeabur 平台使用方法 | ✅ |
| 中 | [扩展知识 7: CLI AI 编程工具](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra7/extra9-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md) | 终端介绍、CLI AI 编程工具、Claude Code/Codex | ✅ |
| 中 | 扩展知识 8: MCP 与 ClaudeCode skills | MCP 协议、ClaudeCode Skills、工具扩展机制 | 🚧 |
| 高 | 扩展知识 9: 如何让 Coding Tools 长时间工作 | 自动化开发配置、长时间任务管理、CLI 工具稳定性优化 | 🚧 |
### 实践项目部分
该部分将会覆盖常见电脑应用形式的 0-1 Vibe Coding 开发过程。
| 难度 | 章节 | 关键内容 | 状态 |
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
| 初 | [Example 0-1: Vibe Coding 入门与贪吃蛇游戏实战](https://github.com/datawhalechina/easy-vibe/blob/main/docs/examples/example0/example0-1/vibe-coding-tools-snake-game-tutorial.md) | 认识 Vibe Coding 与在线 AI Agent 编码平台，学习提示词编写方法，对比不同平台 vibe coding 贪吃蛇游戏的效果。 | ✅ |
| 初 | [Example 0-2: 使用 AI 设计与编码 Agent 搭建网站](https://github.com/datawhalechina/easy-vibe/blob/main/docs/examples/example0/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md) | 使用设计 Agent + 编码 Agent，从零完成 Logo 设计、网站结构规划与单页网站搭建全流程。 | ✅ |
| 中 | [Example 1: 如何构建微信小程序](https://github.com/datawhalechina/easy-vibe/blob/main/docs/examples/example1/example1-how-to-build-a-wechat-miniprogram.md) | 了解微信小程序生态与开发链路，结合 **Trae** + **HBuilderX** + **微信开发者工具**，通过 AI 辅助从环境搭建到代码生成，全流程开发**贪吃蛇小程序**。 | ✅ |
| 中 | Example 2: 如何构建微信小程序-包含后端 | 使用 vibe coding 从 0 到 1 构建具有后端数据库的微信小程序 | 🚧 |
| 高 | Example 3: 如何构建安卓程序 | 结合 Expo，使用 vibe coding 从 0 到 1 构建安卓应用并上架 | 🚧 |
## 如何学习
- 建议具备基本编程经验（任意一门语言均可），并对 AI 与产品开发有兴趣
- 按照 Project 模块从 0 到 6 依次实践，完成从小游戏到完整应用原型的进阶
- 在 Extra 模块中补充 Git、API、RAG、部署等通识知识，完善你的 AI 开发知识图谱
- 遇到问题时优先尝试自己排查与检索，再对照教程与源码进行比对和反思
你可以根据个人时间与需求，选择性地阅读和实践相关章节，但推荐至少完成全部 Project，以形成一套完整的实践闭环。
## 本地启动本课件
### 现代方案
在 AI IDE 对话框（vscode、cursor、trae 等）中，输入下列提示词启动本课件：
```
请你帮我运行这个项目的本地服务
```
### 旧方案
1. npm install
2. npm run dev
3. 打开浏览器访问 `http://localhost:3000` 即可查看。
docs/_sidebar.md
-24
View File
@@ -1,24 +0,0 @@
* [首页](README.md)
* Project
* [学习地图](project/chapter0-learning-map/chapter0-learning-map.md)
* [Project 1: 如何构建贪吃蛇游戏](project/chapter1/chapter1-how-to-build-a-snake-game.md)
* [Project 2: 探索 AI 工具的能力边界](project/chapter2/chapter2-reach-the-capability-boundaries-of-ai-tools.md)
* [Project 3: Dify 入门与知识库集成](project/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md)
* [Project 4: 一起做霍格沃茨画像](project/chapter4/chapter4-lets-build-hogwarts-portraits.md)
* [Project 5: 从数据库到 Supabase](project/chapter5/chapter5-from-database-to-supabase.md)
* [Project 6: 没有 idea 就没有代码](project/chapter6/chapter6-no-code-without-an-idea.md)
* Extra
* [扩展知识 1: 什么是 Git 和 GitHub](extra/extra1/extra1-what-is-git-and-what-is-github.md)
* [扩展知识 2: 什么是 API](extra/extra2/extra2-what-is-api.md)
* [扩展知识 3: AI 能力入门手册](extra/extra3/extra3-ai-capability-starter-handbook.md)
* [扩展知识 4: 什么是 AI IDE 和 Trae](extra/extra4/extra4-what-is-ai-ide-and-trae.md)
* [扩展知识 5: 什么是 RAG 以及它如何工作](extra/extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md)
* [扩展知识 6: Zeabur 与 Web 应用部署](extra/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md)
* [扩展知识 7: 命令行 AI 编程工具介绍](extra/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md)
* Examples
* * [完整实战 0-1: Vibe Coding 入门与贪吃蛇游戏实战](examples/example0/example0-1/vibe-coding-tools-snake-game-tutorial.md)
* * [完整实战 0-2: 使用 AI 设计与编码 Agent 搭建网站](examples/example0/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md)
* * [完整实战项目 1: 如何写一个微信小程序](examples/example1/example1-how-to-build-a-wechat-miniprogram.md)
docs/appendix/ai-capability-dictionary.md
+3267
View File
File diff suppressed because it is too large Load Diff
docs/assets
Symlink
+1
View File
@@ -0,0 +1 @@
../assets
docs/demo.md
+63
View File
@@ -0,0 +1,63 @@
# 组件库演示 (Element Plus)
Easy-Vibe 已经集成了 [Element Plus](https://element-plus.org/)，你可以在 Markdown 中直接使用 Vue 组件。
## 按钮示例
<el-row class="mb-4">
<el-button>Default</el-button>
<el-button type="primary">Primary</el-button>
<el-button type="success">Success</el-button>
<el-button type="info">Info</el-button>
<el-button type="warning">Warning</el-button>
<el-button type="danger">Danger</el-button>
</el-row>
## 图标示例
<el-icon :size="20" color="#409EFC" class="no-inherit">
<Edit />
</el-icon>
<el-icon :size="20" color="#67C23A" class="no-inherit">
<Share />
</el-icon>
<el-icon :size="20" color="#F56C6C" class="no-inherit">
<Delete />
</el-icon>
<el-icon :size="20" class="is-loading no-inherit">
<Loading />
</el-icon>
::: tip
要使用图标，你可能需要手动导入具体的图标组件，或者配置自动导入。上面的示例假设你已经配置好了或使用了简单的图标。
:::
## 卡片示例
<el-card class="box-card" style="width: 480px">
<template #header>
<div class="card-header">
<span>Card name</span>
<el-button class="button" text>Operation button</el-button>
</div>
</template>
<div v-for="o in 4" :key="o" class="text item">
{{'List item ' + o }}
</div>
</el-card>
<style>
.card-header {
display: flex;
justify-content: space-between;
align-items: center;
}
.text {
font-size: 14px;
}
.item {
margin-bottom: 18px;
}
</style>
docs/examples/README.md
+7
View File
@@ -0,0 +1,7 @@
# Examples 实战案例
这里包含了实战案例的文档：
- [Example 0.1: Snake Game Tutorial](example0/example0-1/vibe-coding-tools-snake-game-tutorial.md)
- [Example 0.2: Build Website with AI](example0/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md)
- [Example 1: Build WeChat MiniProgram](example1/example1-how-to-build-a-wechat-miniprogram.md)
docs/examples/example0/example0-1/vibe-coding-tools-snake-game-tutorial.md
+136 -130
View File
@@ -4,12 +4,12 @@
### **你将学到：** ### **你将学到：**
* **什么是 Vibe Coding：** 了解它的定义、工作流和关键优势。 - **什么是 Vibe Coding：** 了解它的定义、工作流和关键优势。
* **AI Agent 的角色：** 理解 AI Agent 的工作方式，以及它与传统程序的差异。 - **AI Agent 的角色：** 理解 AI Agent 的工作方式，以及它与传统程序的差异。
* **如何写好提示词：** 掌握清晰、具体的提示词写法，以获得更好的结果。 - **如何写好提示词：** 掌握清晰、具体的提示词写法，以获得更好的结果。
* **Vibe Coding 工具：** 认识一批主流的 AI 编程与设计平台。 - **Vibe Coding 工具：** 认识一批主流的 AI 编程与设计平台。
* **平台对比：** 从初学者视角出发，对 7 个不同 AI Agent 平台的优劣势进行评测与对比。 - **平台对比：** 从初学者视角出发，对 7 个不同 AI Agent 平台的优劣势进行评测与对比。
* **UI / UX 工具：** 学会如何将 Figma、Mastergo 等 UI/UX 工具融入到整体工作流中。 - **UI / UX 工具：** 学会如何将 Figma、Mastergo 等 UI/UX 工具融入到整体工作流中。
# 1. 引言 # 1. 引言
@@ -25,18 +25,18 @@ Vibe Coding 的核心思想，是从 **“以代码为中心（code-first）”*
典型的 Vibe Coding 工作流程是一个不断迭代的循环： 典型的 Vibe Coding 工作流程是一个不断迭代的循环：
* **描述目标：** 先用一句话或一段话描述你想要实现的功能，例如：“做一个带有 Python 后端、可以生成诗歌的简单贪吃蛇游戏。” - **描述目标：** 先用一句话或一段话描述你想要实现的功能，例如：“做一个带有 Python 后端、可以生成诗歌的简单贪吃蛇游戏。”
* **AI 生成代码：** AI Agent 解析你的需求，生成初版代码，包括基本结构、前端页面和后端逻辑。 - **AI 生成代码：** AI Agent 解析你的需求，生成初版代码，包括基本结构、前端页面和后端逻辑。
* **运行并观察：** 运行生成的代码，检查其是否按预期工作，同时发现 bug 或不足之处。 - **运行并观察：** 运行生成的代码，检查其是否按预期工作，同时发现 bug 或不足之处。
* **反馈并迭代：** 如果有错误或效果不理想，就在对话中继续下指令，例如：“蛇移动太慢了，把速度调快些”，或者“现在 `.env` 文件里的 API Key 没被正确读取，请修复后端代码。” - **反馈并迭代：** 如果有错误或效果不理想，就在对话中继续下指令，例如：“蛇移动太慢了，把速度调快些”，或者“现在 `.env` 文件里的 API Key 没被正确读取，请修复后端代码。”
* **重复上述步骤：** 不断在“描述 → 生成 → 运行 → 反馈”的循环中迭代，直到应用达到满意的状态。 - **重复上述步骤：** 不断在“描述 → 生成 → 运行 → 反馈”的循环中迭代，直到应用达到满意的状态。
### Vibe Coding 的主要优势： ### Vibe Coding 的主要优势：
* **降低门槛：** 让缺乏编程经验的设计师、创业者、学生等，也可以通过自然语言参与应用开发。 - **降低门槛：** 让缺乏编程经验的设计师、创业者、学生等，也可以通过自然语言参与应用开发。
* **快速原型：** 从想法到最小可行产品（MVP）的时间大幅缩短。 - **快速原型：** 从想法到最小可行产品（MVP）的时间大幅缩短。
* **提高效率：** 自动处理大量重复、机械的编码工作（如模板代码），让开发者可以把精力放在架构设计和问题抽象上。 - **提高效率：** 自动处理大量重复、机械的编码工作（如模板代码），让开发者可以把精力放在架构设计和问题抽象上。
* **利于试验：** 鼓励先快速产出，再不断完善的方式，更便于尝试新点子和新功能。 - **利于试验：** 鼓励先快速产出，再不断完善的方式，更便于尝试新点子和新功能。
--- ---
@@ -48,20 +48,21 @@ AI Agent 是一种软件系统，它能够感知环境、做出决策，并自
下面是一些将 AI Agent 与传统程序区分开的关键特征： 下面是一些将 AI Agent 与传统程序区分开的关键特征：
* **自主性（Autonomy）：** AI Agent 具有较高的独立性。传统程序通常需要人一步一步触发，而 Agent 可以根据目标自主决定下一步要做什么。 - **自主性（Autonomy）：** AI Agent 具有较高的独立性。传统程序通常需要人一步一步触发，而 Agent 可以根据目标自主决定下一步要做什么。
* **感知与记忆（Perception & Memory）：** Agent 会从环境中收集数据（例如 API 响应、传感器数据、用户输入等），并通过“记忆”保留上下文，从而在后续行动中复用经验、持续改进效果。 - **感知与记忆（Perception & Memory）：** Agent 会从环境中收集数据（例如 API 响应、传感器数据、用户输入等），并通过“记忆”保留上下文，从而在后续行动中复用经验、持续改进效果。
* **理性与目标导向（Rationality & Goal-Orientation）：** Agent 会围绕给定的目标进行分析与规划，选择最合适的行动序列来追求更高的“绩效指标”。 - **理性与目标导向（Rationality & Goal-Orientation）：** Agent 会围绕给定的目标进行分析与规划，选择最合适的行动序列来追求更高的“绩效指标”。
* **工具使用（Tool Use）：** 现代 AI Agent 的一大特征，是可以调用外部工具，不再局限于“生成文字”。例如，它可以浏览网页、运行代码、查询数据库、发送邮件等，是一个会“调度工具”的大脑。 - **工具使用（Tool Use）：** 现代 AI Agent 的一大特征，是可以调用外部工具，不再局限于“生成文字”。例如，它可以浏览网页、运行代码、查询数据库、发送邮件等，是一个会“调度工具”的大脑。
可以这样类比理解： 可以这样类比理解：
* 一个 **传统程序** 像是计算器。你给它输入数字和运算符，它只在你按下按钮时执行计算。 - 一个 **传统程序** 像是计算器。你给它输入数字和运算符，它只在你按下按钮时执行计算。
* 一个 **AI 助手** 像是人类助理。你让它“帮我找附近的餐馆”，它会给你搜索结果并列出选项，但最后还是由你做决策。 - 一个 **AI 助手** 像是人类助理。你让它“帮我找附近的餐馆”，它会给你搜索结果并列出选项，但最后还是由你做决策。
* 一个 **AI Agent** 则更像是一支自动化研究团队。你只需要给出高层目标（比如“帮我规划一次日本旅行”），它就会分解任务、上网查资料、预定机票酒店（通过 API）、整理日程，最终把结果交付给你，全程几乎不需要你干预细节。 - 一个 **AI Agent** 则更像是一支自动化研究团队。你只需要给出高层目标（比如“帮我规划一次日本旅行”），它就会分解任务、上网查资料、预定机票酒店（通过 API）、整理日程，最终把结果交付给你，全程几乎不需要你干预细节。
--- ---
# 2. 关于提示词编写 # 2. 关于提示词编写
## 1. 提示词一次写完好，还是拆成多步更好？ ## 1. 提示词一次写完好，还是拆成多步更好？
很多人会忍不住想直接在一个提示词里，把“做一个完整的全栈应用”一次性说清楚。事实上，当前工具已经足够强大，确实有机会一次性给出一个看上去还不错的结果。但从整体体验和成功率来看，把工作拆成小步骤、按阶段迭代，效果往往会更好，也更不容易陷入“改不动”的死胡同。 很多人会忍不住想直接在一个提示词里，把“做一个完整的全栈应用”一次性说清楚。事实上，当前工具已经足够强大，确实有机会一次性给出一个看上去还不错的结果。但从整体体验和成功率来看，把工作拆成小步骤、按阶段迭代，效果往往会更好，也更不容易陷入“改不动”的死胡同。
@@ -75,91 +76,92 @@ AI Agent 是一种软件系统，它能够感知环境、做出决策，并自
## 2. 越清晰，越好 ## 2. 越清晰，越好
* 在 Vibe Coding 中，你写的提示词和你写的代码一样重要。提示越清晰、越具体，结果就越接近你心中所想。 - 在 Vibe Coding 中，你写的提示词和你写的代码一样重要。提示越清晰、越具体，结果就越接近你心中所想。
* 一开始就把目标与约束条件说清楚，可以减少后续反复修改的次数，这不仅省时间，也能节省使用额度和成本。 - 一开始就把目标与约束条件说清楚，可以减少后续反复修改的次数，这不仅省时间，也能节省使用额度和成本。
--- ---
# 3. 工具总览（Vibe Coding / UIUX 工具） # 3. 工具总览（Vibe Coding / UIUX 工具）
## 1. AI Agent 平台 ## 1. AI Agent 平台
| **Name** | **Platform** | | **Name** | **Platform** |
| --------------------------------------------- | ------------------ | | ------------------------------------------ | ------------ |
| **[Lovable](https://lovable.dev/)** | Web-based | | **[Lovable](https://lovable.dev/)** | Web-based |
| **[Cursor](https://cursor.com/cn/agents)** | PC | | **[Cursor](https://cursor.com/cn/agents)** | PC |
| **[Z.ai](https://chat.z.ai/)** | Web-based | | **[Z.ai](https://chat.z.ai/)** | Web-based |
| **[Replit](https://replit.com/~)** | Web-based | | **[Replit](https://replit.com/~)** | Web-based |
| **[Minimax](https://agent.minimaxi.com/)** | Web-based | | **[Minimax](https://agent.minimaxi.com/)** | Web-based |
| **[Trae](https://www.trae.ai/)** | PC | | **[Trae](https://www.trae.ai/)** | PC |
| **[V0](https://v0.app/)** | Web-based | | **[V0](https://v0.app/)** | Web-based |
## 2. AI UIUX 平台 ## 2. AI UIUX 平台
| **Name** | **Platform** | | **Name** | **Platform** |
| ---------------------------------------- | -------------------- | | ------------------------------------- | -------------------- |
| **[Mastergo](https://mastergo.com/)** | Web-based | | **[Mastergo](https://mastergo.com/)** | Web-based |
| **[FIgma](https://www.figma.com/)** | Web-based, PC Plugin | | **[FIgma](https://www.figma.com/)** | Web-based, PC Plugin |
--- ---
# 4. 实战教程（Vibe Coding + UI 结合） # 4. 实战教程（Vibe Coding + UI 结合）
1. 在你准备进行 Vibe Coding 的平台聊天窗口中，输入你想要的程序描述。 1. 在你准备进行 Vibe Coding 的平台聊天窗口中，输入你想要的程序描述。
示例： 示例：
> 请构建一个带前端和后端的简单贪吃蛇（Snake）网页应用。 > 请构建一个带前端和后端的简单贪吃蛇（Snake）网页应用。
> >
> 1. 前端 > 1. 前端
> >
> - 页面 1：游戏页面 > - 页面 1：游戏页面
> - 使用键盘控制蛇的移动。
> - 蛇吃掉的不是食物，而是英文单词。
> - 页面侧边栏展示已收集单词及其数量。
> - 游戏结束后，已收集的单词仍然保留，并在新一局中延续。
> >
> * 使用键盘控制蛇的移动。 > - 页面 2：写诗页面（Make Poem）
> * 蛇吃掉的不是食物，而是英文单词。 > - 展示与游戏页面相同的单词列表（数据一致）。
> * 页面侧边栏展示已收集单词及其数量。 > - 提供一个按钮，将当前收集的单词发送给后端生成一首诗。
> * 游戏结束后，已收集的单词仍然保留，并在新一局中延续。 > - 生成诗歌后，将被使用到的单词从列表中移除或递减计数。
> - 页面 2：写诗页面（Make Poem）
> >
> * 展示与游戏页面相同的单词列表（数据一致）。 > * 添加简单的导航，在 Game 和 Make Poem 两个页面之间切换。
> * 提供一个按钮，将当前收集的单词发送给后端生成一首诗。 > * 确保收集到的单词在两个页面中都能看到。
> * 生成诗歌后，将被使用到的单词从列表中移除或递减计数。
> >
> * 添加简单的导航，在 Game 和 Make Poem 两个页面之间切换。 > 2. 后端
> * 确保收集到的单词在两个页面中都能看到。
> >
> 2. 后端 > - 提供一个后端接口，接收收集到的单词并返回一首诗。
> > - 使用 DeepSeek API 生成诗歌。
> * 提供一个后端接口，接收收集到的单词并返回一首诗。 > - 将 API Key 存放在 `.env` 文件中，并在 `.gitignore` 中忽略该文件。
> * 使用 DeepSeek API 生成诗歌。
> * 将 API Key 存放在 `.env` 文件中，并在 `.gitignore` 中忽略该文件。
>
2. 输入你的 DeepSeek API Key。（可以在 [https://platform.deepseek.com/](https://platform.deepseek.com/) 获取）
2. 输入你的 DeepSeek API Key。（可以在 [https://platform.deepseek.com/](https://platform.deepseek.com/) 获取）
1. LLM 的 API Key 用于在你自己的项目中调用大模型。由于这是敏感信息，不能公开，因此需要单独写在配置文件里。 1. LLM 的 API Key 用于在你自己的项目中调用大模型。由于这是敏感信息，不能公开，因此需要单独写在配置文件里。
**为什么要用 `.env` 文件，并且不要把它上传到 GitHub？** **为什么要用 `.env` 文件，并且不要把它上传到 GitHub？**
- `.env` 文件专门用来存放 **密钥或密码**（例如 DeepSeek API Key）。
- 如果这个文件被上传到 GitHub，全世界的人都能看到你的密钥并盗用它。
- 为了安全起见，我们需要在 `.gitignore` 文件中声明忽略 `.env`，让 Git 不跟踪它。
- 这样一来，你的项目仍然可以在本机正常使用这些密钥，但不会在仓库中泄露。
* `.env` 文件专门用来存放 **密钥或密码**（例如 DeepSeek API Key）。
* 如果这个文件被上传到 GitHub，全世界的人都能看到你的密钥并盗用它。
* 为了安全起见，我们需要在 `.gitignore` 文件中声明忽略 `.env`，让 Git 不跟踪它。
* 这样一来，你的项目仍然可以在本机正常使用这些密钥，但不会在仓库中泄露。
3. 查看生成结果后，如果发现错误或有需要修改的地方，可以直接在聊天窗口中输入你的修改请求。 3. 查看生成结果后，如果发现错误或有需要修改的地方，可以直接在聊天窗口中输入你的修改请求。
4. 如果你对页面设计不满意，也可以选择在 Figma 或 Mastergo 中重新设计界面，再把设计思路反馈给 Agent。 4. 如果你对页面设计不满意，也可以选择在 Figma 或 Mastergo 中重新设计界面，再把设计思路反馈给 Agent。
* **示例** - **示例**
> 请设计一个名为 *Word-Snake* 的 **双页面 Web 应用**。 > 请设计一个名为 _Word-Snake_ 的 **双页面 Web 应用**。
> >
> * **Game 页面：** > - **Game 页面：**
> * 蛇通过键盘控制移动。 > - 蛇通过键盘控制移动。
> * 蛇吃掉的是英文单词，而不是普通食物。 > - 蛇吃掉的是英文单词，而不是普通食物。
> * 右侧面板展示已收集单词及数量。 > - 右侧面板展示已收集单词及数量。
> * 游戏结束后，单词库存不会清空，在新一轮中继续使用。 > - 游戏结束后，单词库存不会清空，在新一轮中继续使用。
> * **Make Poem 页面：** > - **Make Poem 页面：**
> * 展示同一份共享单词库存。 > - 展示同一份共享单词库存。
> * 用户选择部分单词并点击 **Generate Poem** 按钮。 > - 用户选择部分单词并点击 **Generate Poem** 按钮。
> * 将这些单词发送给后端，由 DeepSeek API 生成一首诗。 > - 将这些单词发送给后端，由 DeepSeek API 生成一首诗。
> * 生成诗歌后，从库存中删除或减少被使用的单词。 > - 生成诗歌后，从库存中删除或减少被使用的单词。
> * **导航：** 通过简单的 Tab 或顶部菜单在两个页面之间切换。 > - **导航：** 通过简单的 Tab 或顶部菜单在两个页面之间切换。
> * **共享状态：** 确保收集到的单词在两个页面始终保持同步可见。 > - **共享状态：** 确保收集到的单词在两个页面始终保持同步可见。
* **效果示例** - **效果示例**
![](images/image1.png)![](images/image2.png) ![](images/image1.png)![](images/image2.png)
@@ -170,137 +172,141 @@ AI Agent 是一种软件系统，它能够感知环境、做出决策，并自
不同的 Vibe Coding 平台各有特色和工作流。我们使用同一套“带 DeepSeek API 的贪吃蛇游戏”需求，在多个平台上进行实测，从初学者的角度评估它们的优劣。以下是总结。 不同的 Vibe Coding 平台各有特色和工作流。我们使用同一套“带 DeepSeek API 的贪吃蛇游戏”需求，在多个平台上进行实测，从初学者的角度评估它们的优劣。以下是总结。
## 1. 对比标准 ## 1. 对比标准
1. **目标（Goal）** 1. **目标（Goal）**
构建一个接入 DeepSeek API 的贪吃蛇（Snake）网页应用。 构建一个接入 DeepSeek API 的贪吃蛇（Snake）网页应用。
2. **游戏细节（Game Details）** 2. **游戏细节（Game Details）**
1. 游戏通过 DeepSeek LLM API 生成诗歌。 1. 游戏通过 DeepSeek LLM API 生成诗歌。
2. 蛇吃掉的是英文单词，收集到的单词会在游戏结束后保留，并在新一局中继续使用。相同单词可以被多次收集，并分别计数。 2. 蛇吃掉的是英文单词，收集到的单词会在游戏结束后保留，并在新一局中继续使用。相同单词可以被多次收集，并分别计数。
3. 当生成一首诗后，被使用到的单词会从库存中移除。 3. 当生成一首诗后，被使用到的单词会从库存中移除。
3. **必备功能（Must-Haves）**
3. **必备功能（Must-Haves）**
1. 一个可运行的前端页面，包含贪吃蛇游戏（键盘控制、Canvas 渲染）。 1. 一个可运行的前端页面，包含贪吃蛇游戏（键盘控制、Canvas 渲染）。
2. 单词收集机制（单词出现在棋盘上，蛇吃掉单词后，侧栏列表更新）。 2. 单词收集机制（单词出现在棋盘上，蛇吃掉单词后，侧栏列表更新）。
3. 在多轮游戏之间保持单词库存的持久化。 3. 在多轮游戏之间保持单词库存的持久化。
4. 使用 DeepSeek API 的后端（如果没有 API Key，可以先返回模拟诗歌）。 4. 使用 DeepSeek API 的后端（如果没有 API Key，可以先返回模拟诗歌）。
5. “生成诗歌”按钮：点击后调用后端，显示诗歌，并根据使用情况更新单词库存。 5. “生成诗歌”按钮：点击后调用后端，显示诗歌，并根据使用情况更新单词库存。
6. 对 API Key 的 `.env` 支持，以及通过 `.gitignore` 避免密钥泄漏。 6. 对 API Key 的 `.env` 支持，以及通过 `.gitignore` 避免密钥泄漏。
4. **加分项（Nice-to-Haves）**
4. **加分项（Nice-to-Haves）**
1. 用户可以选择要用哪些词来生成诗歌。 1. 用户可以选择要用哪些词来生成诗歌。
2. 用户体验友好（例如侧边栏清晰展示单词列表、诗歌展示区布局合理）。 2. 用户体验友好（例如侧边栏清晰展示单词列表、诗歌展示区布局合理）。
3. 为初学者在代码中加入注释，解释关键逻辑。 3. 为初学者在代码中加入注释，解释关键逻辑。
## 2. 编码输出对比 ## 2. 编码输出对比
### 1. Lovable（Web-based） ### 1. Lovable（Web-based）
* **平台类型：** Web 端 - **平台类型：** Web 端
* **主要特性与工作流：** Lovable 在集成与协作方面做得很好，它自动完成诸如连接 Supabase 数据库等初始化工作，使项目搭建过程非常顺畅。你只需描述项目需求，Agent 就会帮你把各类服务串联起来，构建好基本结构。 - **主要特性与工作流：** Lovable 在集成与协作方面做得很好，它自动完成诸如连接 Supabase 数据库等初始化工作，使项目搭建过程非常顺畅。你只需描述项目需求，Agent 就会帮你把各类服务串联起来，构建好基本结构。
* **适合的用户：** 对于第一次尝试 Vibe Coding 的新手来说，Lovable 是非常友好的选择。它简化了多服务联动的复杂度，让你可以把注意力集中在提示词与迭代上，而不是环境配置。得益于高度自动化，你能很快得到一个可运行的原型。 - **适合的用户：** 对于第一次尝试 Vibe Coding 的新手来说，Lovable 是非常友好的选择。它简化了多服务联动的复杂度，让你可以把注意力集中在提示词与迭代上，而不是环境配置。得益于高度自动化，你能很快得到一个可运行的原型。
* **提示词过程：** - **提示词过程：**
![](images/image3.png) ![](images/image3.png)
* **贪吃蛇游戏效果：** - **贪吃蛇游戏效果：**
![](images/image4.png)![](images/image5.png) ![](images/image4.png)![](images/image5.png)
* **价格：** 相对偏贵，但如果你有学校邮箱，可以通过学生验证以半价使用。 - **价格：** 相对偏贵，但如果你有学校邮箱，可以通过学生验证以半价使用。
![](images/image6.png) ![](images/image6.png)
### 2. Cursor（IDE） ### 2. Cursor（IDE）
* **平台类型：** 桌面应用（PC） - **平台类型：** 桌面应用（PC）
* **主要特性与工作流：** Cursor 是一款集成了 AI 能力的专有 IDE，支持 Windows、macOS 和 Linux。它把代码生成、智能重写、代码库查询等功能直接嵌入在开发环境中。与 Web 工具相比，它更接近传统本地开发体验。由于是本地环境，不同电脑的配置各异，偶尔会遇到环境相关问题。好处是项目就在本机，无需再额外下载或配置运行环境，Cursor 会帮你处理很多繁琐步骤。 - **主要特性与工作流：** Cursor 是一款集成了 AI 能力的专有 IDE，支持 Windows、macOS 和 Linux。它把代码生成、智能重写、代码库查询等功能直接嵌入在开发环境中。与 Web 工具相比，它更接近传统本地开发体验。由于是本地环境，不同电脑的配置各异，偶尔会遇到环境相关问题。好处是项目就在本机，无需再额外下载或配置运行环境，Cursor 会帮你处理很多繁琐步骤。
* **适合的用户：** 对已有一定编程基础的用户，Cursor 是一个非常强大又熟悉的环境。但对完全零基础的新手来说，需要自己理解项目结构、依赖管理和文件组织等概念，学习曲线会更陡一些。更适合想在传统编码流程中加入 AI 助手的开发者。 - **适合的用户：** 对已有一定编程基础的用户，Cursor 是一个非常强大又熟悉的环境。但对完全零基础的新手来说，需要自己理解项目结构、依赖管理和文件组织等概念，学习曲线会更陡一些。更适合想在传统编码流程中加入 AI 助手的开发者。
* **提示词过程：** - **提示词过程：**
![](images/image7.png) ![](images/image7.png)
* **贪吃蛇游戏效果：** - **贪吃蛇游戏效果：**
![](images/image8.png)![](images/image9.png) ![](images/image8.png)![](images/image9.png)
* **价格：** - **价格：**
![](images/image10.png) ![](images/image10.png)
### 3. Z.ai（Web-based） ### 3. Z.ai（Web-based）
* **平台类型：** Web 端 - **平台类型：** Web 端
* **主要特性与工作流：** Z.ai 的使用方式比较直接，但一个明显的挑战在于：你需要 **手动复制粘贴生成的代码**。平台本身缺少实时预览窗口，因此很难第一时间看到代码运行效果。 - **主要特性与工作流：** Z.ai 的使用方式比较直接，但一个明显的挑战在于：你需要 **手动复制粘贴生成的代码**。平台本身缺少实时预览窗口，因此很难第一时间看到代码运行效果。
* **适合的用户：** 这个平台要求比较“动手”的使用方式。缺少自动化意味着你必须与代码直接打交道，这对想深入理解 AI 输出内容的人来说反而是种训练。但频繁的复制粘贴会带来效率问题和出错风险。更适合想看“原生 AI 输出代码”的同学，而不是追求一键式体验的人。 - **适合的用户：** 这个平台要求比较“动手”的使用方式。缺少自动化意味着你必须与代码直接打交道，这对想深入理解 AI 输出内容的人来说反而是种训练。但频繁的复制粘贴会带来效率问题和出错风险。更适合想看“原生 AI 输出代码”的同学，而不是追求一键式体验的人。
* **提示词过程：** - **提示词过程：**
![](images/image11.png) ![](images/image11.png)
* **贪吃蛇游戏效果：** - **贪吃蛇游戏效果：**
![](images/image12.png)![](images/image13.png) ![](images/image12.png)![](images/image13.png)
* **价格：** - **价格：**
![](images/image14.png) ![](images/image14.png)
### 4. Replit（Web-based） ### 4. Replit（Web-based）
* **平台类型：** Web 端 - **平台类型：** Web 端
* **主要特性与工作流：** Replit 是一体化的在线开发与部署环境，浏览器里就可以写代码、运行程序、生成线上访问地址。开始编码前，它会给出清晰的行动计划；同时还提供可视化编辑器，你可以在预览窗口里直接改 UI，源码会自动同步更新。这样可以让你随时校验 AI 的输出是否符合预期，大幅减少来回修改的次数。 - **主要特性与工作流：** Replit 是一体化的在线开发与部署环境，浏览器里就可以写代码、运行程序、生成线上访问地址。开始编码前，它会给出清晰的行动计划；同时还提供可视化编辑器，你可以在预览窗口里直接改 UI，源码会自动同步更新。这样可以让你随时校验 AI 的输出是否符合预期，大幅减少来回修改的次数。
![](images/image15.png) ![](images/image15.png)
* **适合的用户：** Replit 对新手十分友好。它简化了从编码到部署的完整闭环，无需自己额外配置服务器或托管服务。协作功能也很强，适合同学之间一起做项目或请他人远程帮忙查看代码。
* **提示词过程：** 在构建过程中，AI 并不是一开始就完全理解需求，中间经历了大约 3 轮迭代，最终输出才达到了理想效果。 - **适合的用户：** Replit 对新手十分友好。它简化了从编码到部署的完整闭环，无需自己额外配置服务器或托管服务。协作功能也很强，适合同学之间一起做项目或请他人远程帮忙查看代码。
- **提示词过程：** 在构建过程中，AI 并不是一开始就完全理解需求，中间经历了大约 3 轮迭代，最终输出才达到了理想效果。
![](images/image16.png) ![](images/image16.png)
* **贪吃蛇游戏效果：** - **贪吃蛇游戏效果：**
![](images/image17.png)![](images/image18.png) ![](images/image17.png)![](images/image18.png)
* **价格：** - **价格：**
![](images/image19.png) ![](images/image19.png)
### 5. Minimax（Web-based） ### 5. Minimax（Web-based）
* **平台类型：** Web 端 - **平台类型：** Web 端
* **主要特性与工作流：** Minimax 在执行任务时通常比较耗时。其流程往往包括：AI 自动发现并修复错误，因此整个过程可能较慢、甚至略显折腾。以本项目为例，Agent 一般会先生成一个详细计划，然后一步步搭建后端、数据库和前端逻辑。 - **主要特性与工作流：** Minimax 在执行任务时通常比较耗时。其流程往往包括：AI 自动发现并修复错误，因此整个过程可能较慢、甚至略显折腾。以本项目为例，Agent 一般会先生成一个详细计划，然后一步步搭建后端、数据库和前端逻辑。
* **适合的用户：** 由于它会自动运行测试和修复错误，时间与 Token 消耗都比较大，但你可以清楚看到 AI 如何定位并解决问题，从学习角度看很有价值。 - **适合的用户：** 由于它会自动运行测试和修复错误，时间与 Token 消耗都比较大，但你可以清楚看到 AI 如何定位并解决问题，从学习角度看很有价值。
* **提示词过程：** - **提示词过程：**
![](images/image20.png)![](images/image21.png)![](images/image22.png)![](images/image23.png) ![](images/image20.png)![](images/image21.png)![](images/image22.png)![](images/image23.png)
* **贪吃蛇游戏效果：** - **贪吃蛇游戏效果：**
![](images/image24.png)![](images/image25.png) ![](images/image24.png)![](images/image25.png)
* **价格：** 免费版在复杂项目中很可能无法顺利从头跑到尾，因此更推荐付费升级，以确保项目可以完整构建。 - **价格：** 免费版在复杂项目中很可能无法顺利从头跑到尾，因此更推荐付费升级，以确保项目可以完整构建。
![](images/image26.png) ![](images/image26.png)
### 6. Trae（IDE） ### 6. Trae（IDE）
* **平台类型：** 桌面应用（PC） - **平台类型：** 桌面应用（PC）
* **主要特性与工作流：** 作为桌面应用，Trae 相比 Web 工具在性能和响应速度上通常更有优势。但它需要下载安装，对一些用户来说入门门槛稍高。同样地，由于是本地环境，不同电脑配置和依赖环境的差异，会带来一定的不确定性。优势在于，Trae 会帮助你在本地完成项目创建与运行配置，你可以直接在本机开发与调试。 - **主要特性与工作流：** 作为桌面应用，Trae 相比 Web 工具在性能和响应速度上通常更有优势。但它需要下载安装，对一些用户来说入门门槛稍高。同样地，由于是本地环境，不同电脑配置和依赖环境的差异，会带来一定的不确定性。优势在于，Trae 会帮助你在本地完成项目创建与运行配置，你可以直接在本机开发与调试。
* **适合的用户：** 更适合计划长期进行 Vibe Coding 项目、并希望使用专门桌面工具的用户。对于只想“偶尔玩一下”的同学，可能不是最轻量的选择。 - **适合的用户：** 更适合计划长期进行 Vibe Coding 项目、并希望使用专门桌面工具的用户。对于只想“偶尔玩一下”的同学，可能不是最轻量的选择。
* **提示词过程：** - **提示词过程：**
![](images/image27.png) ![](images/image27.png)
* **贪吃蛇游戏效果：** - **贪吃蛇游戏效果：**
![](images/image28.png)![](images/image29.png) ![](images/image28.png)![](images/image29.png)
* **价格：** 价格相对亲民，即便是免费版本，也足以完成质量不错的小项目。 - **价格：** 价格相对亲民，即便是免费版本，也足以完成质量不错的小项目。
![](images/image30.png) ![](images/image30.png)
### 7. V0（Web-based） ### 7. V0（Web-based）
* **平台类型：** Web 端 - **平台类型：** Web 端
* **主要特性与工作流：** V0 是一个专注于生成 React UI 组件的工具，由 Vercel 提供。它在生成高质量、可用于生产环境的界面方面表现出色。但在实际使用中，会遇到诸如“难以找到代码视图”、“没有清晰说明 API Key 应该配置在何处”等问题。 - **主要特性与工作流：** V0 是一个专注于生成 React UI 组件的工具，由 Vercel 提供。它在生成高质量、可用于生产环境的界面方面表现出色。但在实际使用中，会遇到诸如“难以找到代码视图”、“没有清晰说明 API Key 应该配置在何处”等问题。
* **适合的用户：** V0 非常适合专注前端和 UI/UX 设计的学生或设计师。但它并不是完整的全栈解决方案，你仍然需要使用其他平台来实现后端逻辑与 API 集成，因此如果你的目标是“一站式搭建完整应用”，它可能不是最佳首选。 - **适合的用户：** V0 非常适合专注前端和 UI/UX 设计的学生或设计师。但它并不是完整的全栈解决方案，你仍然需要使用其他平台来实现后端逻辑与 API 集成，因此如果你的目标是“一站式搭建完整应用”，它可能不是最佳首选。
* **提示词过程：** - **提示词过程：**
![](images/image31.png) ![](images/image31.png)
![](images/image32.png) ![](images/image32.png)
* **贪吃蛇游戏效果：**
- **贪吃蛇游戏效果：**
![](images/image33.png)![](images/image34.png) ![](images/image33.png)![](images/image34.png)
* **价格：** 免费用户大约可以构建 4–5 个简单项目。 - **价格：** 免费用户大约可以构建 4–5 个简单项目。
![](images/image35.png) ![](images/image35.png)
## 3. 平台总结对比 ## 3. 平台总结对比
| **平台** | **Review** | **Platform** | **Notes** | | **平台** | **Review** | **Platform** | **Notes** |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ------------------------------------------ | ------------------------------------------------------------------------------ | ------------ | ------------------------------------------------------------------------------ |
| **[Lovable](https://lovable.dev/)** | 对 AI 编程新手非常友好，上手简单、体验顺滑，是理想的入门选择。 | Web-based | 自动完成 Supabase 等服务连接，减少配置成本。 | | **[Lovable](https://lovable.dev/)** | 对 AI 编程新手非常友好，上手简单、体验顺滑，是理想的入门选择。 | Web-based | 自动完成 Supabase 等服务连接，减少配置成本。 |
| **[Cursor](https://cursor.com/cn/agents)** | 适合已有开发经验的用户，大幅提升生产力与代码质量。 | PC | 需要一定编程基础，本地环境中需自己理解项目结构和依赖。 | | **[Cursor](https://cursor.com/cn/agents)** | 适合已有开发经验的用户，大幅提升生产力与代码质量。 | PC | 需要一定编程基础，本地环境中需自己理解项目结构和依赖。 |
| **[Z.ai](https://chat.z.ai/)** | 更适合有编程基础、想直接研究 AI 输出代码细节的用户。 | Web-based | 无预览窗口，检查结果较麻烦；需要手动粘贴代码、创建文件夹和文件并手动运行服务。 | | **[Z.ai](https://chat.z.ai/)** | 更适合有编程基础、想直接研究 AI 输出代码细节的用户。 | Web-based | 无预览窗口，检查结果较麻烦；需要手动粘贴代码、创建文件夹和文件并手动运行服务。 |
| **[Replit](https://replit.com/~)** | 推荐给想快速把点子变成可访问在线服务的用户。 | Web-based | 一体化在线开发与部署，支持协作并提供可视化编辑器。 | | **[Replit](https://replit.com/~)** | 推荐给想快速把点子变成可访问在线服务的用户。 | Web-based | 一体化在线开发与部署，支持协作并提供可视化编辑器。 |
| **[Minimax](https://agent.minimaxi.com/)** | 适合希望看到 AI 自动查错与修复全过程、并从中学习的人，但整体较慢且耗费 Token。 | Web-based | 整个过程较长，AI 会多次自动运行测试并修复错误。 | | **[Minimax](https://agent.minimaxi.com/)** | 适合希望看到 AI 自动查错与修复全过程、并从中学习的人，但整体较慢且耗费 Token。 | Web-based | 整个过程较长，AI 会多次自动运行测试并修复错误。 |
| **[Trae](https://www.trae.ai/)** | 针对有编程经验、希望使用桌面 IDE + AI Agent 组合的用户，是提升效率的有力工具。 | PC | 需本地安装与环境配置，但性能更好，适合长期进行 Vibe Coding 项目。 | | **[Trae](https://www.trae.ai/)** | 针对有编程经验、希望使用桌面 IDE + AI Agent 组合的用户，是提升效率的有力工具。 | PC | 需本地安装与环境配置，但性能更好，适合长期进行 Vibe Coding 项目。 |
| **[V0](https://v0.app/)** | 为想快速做出 React UI 视觉效果的非开发者进行了优化，适合前端 / 设计向的学生。 | Web-based | 专注生成 React UI，需要与其他平台配合完成后端和完整应用搭建。 | | **[V0](https://v0.app/)** | 为想快速做出 React UI 视觉效果的非开发者进行了优化，适合前端 / 设计向的学生。 | Web-based | 专注生成 React UI，需要与其他平台配合完成后端和完整应用搭建。 |
docs/examples/example0/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md
+67 -61
View File
@@ -1,83 +1,86 @@
# 1. 入门指南 # 1. 入门指南
## 1. 教程简介 ## 1. 教程简介
让我们使用 AI 设计 Agent 和编码 Agent，从零开始搭建一个完整的网站。 让我们使用 AI 设计 Agent 和编码 Agent，从零开始搭建一个完整的网站。
* **设计 Agent**：负责创建 logo、网页布局、配色方案和其他视觉元素 - **设计 Agent**：负责创建 logo、网页布局、配色方案和其他视觉元素
* **编码 Agent**：根据你在提示中提出的需求与布局，编写 HTML/CSS/JS 等实际代码，构建可运行的网站 - **编码 Agent**：根据你在提示中提出的需求与布局，编写 HTML/CSS/JS 等实际代码，构建可运行的网站
## 2. 设计 Agent 与编码 Agent ## 2. 设计 Agent 与编码 Agent
* **设计 Agent**：根据你提供的提示，生成图片、页面模型或设计风格的 AI。 - **设计 Agent**：根据你提供的提示，生成图片、页面模型或设计风格的 AI。
* Mastergo - Mastergo
* Lovart - Lovart
* Figma MCP - Figma MCP
* **编码 Agent**：根据你在提示中请求的功能与布局，编写实际的代码（HTML/CSS/JS 等）的 AI。 - **编码 Agent**：根据你在提示中请求的功能与布局，编写实际的代码（HTML/CSS/JS 等）的 AI。
* Z.AI - Z.AI
* Trae - Trae
* Cursor - Cursor
* Lovable - Lovable
--- ---
# 2. 使用设计 Agent 创建 Logo # 2. 使用设计 Agent 创建 Logo
## 1. 设计 Logo 时需要考虑的关键要素 ## 1. 设计 Logo 时需要考虑的关键要素
Logo 是决定你网站第一印象的关键元素之一。想要从 AI 设计 Agent 那里获得满意的结果，你需要在提示中清楚地描述你想要的 Logo 类型。 Logo 是决定你网站第一印象的关键元素之一。想要从 AI 设计 Agent 那里获得满意的结果，你需要在提示中清楚地描述你想要的 Logo 类型。
1. **品牌名称 / 文本** 1. **品牌名称 / 文本**
* 必须出现在 Logo 中的文字（例如：网站标题、品牌名称等）。 - 必须出现在 Logo 中的文字（例如：网站标题、品牌名称等）。
2. **风格（情绪 / 气氛）** 2. **风格（情绪 / 气氛）**
* Logo 想要传达的整体感觉或氛围。 - Logo 想要传达的整体感觉或氛围。
* *示例：极简、可爱、简洁、现代、复古、未来感等。* - _示例：极简、可爱、简洁、现代、复古、未来感等。_
3. **配色方案**（可选） 3. **配色方案**（可选）
* 最好让 Logo 的配色与整个网站的整体基调相匹配。 - 最好让 Logo 的配色与整个网站的整体基调相匹配。
* 可以指定具体的十六进制色号，或大致的色调（冷色、暖色等）。 - 可以指定具体的十六进制色号，或大致的色调（冷色、暖色等）。
* *示例：**`#171721`**（黑色）、**`#FF7130`**（橙色）。* - _示例：**`#171721`**（黑色）、**`#FF7130`**（橙色）。_
4. **形式（形状 / 结构）** 4. **形式（形状 / 结构）**
* 明确 Logo 是否需要特定的形状或构图。 - 明确 Logo 是否需要特定的形状或构图。
* *示例：文字在圆形内部、图标 + 文字组合、以图标为主的 Logo 等。* - _示例：文字在圆形内部、图标 + 文字组合、以图标为主的 Logo 等。_
5. **图标 / 符号元素**（可选） 5. **图标 / 符号元素**（可选）
* 希望出现在 Logo 中的图形或符号。 - 希望出现在 Logo 中的图形或符号。
* *示例：书本图标、闪电符号、与 AI 相关的图形、抽象几何图形等。* - _示例：书本图标、闪电符号、与 AI 相关的图形、抽象几何图形等。_
## 2. 编写 Logo 设计提示词 ## 2. 编写 Logo 设计提示词
**示例提示词** **示例提示词**
```Plain ```Plain
"请为我设计一个极简风格的 Logo，品牌名称是 ‘My First Website’。 "请为我设计一个极简风格的 Logo，品牌名称是 ‘My First Website’。
使用黑色 (#171721) 和橙色 (#FF7130)，并将文字放在一个圆形内部。" 使用黑色 (#171721) 和橙色 (#FF7130)，并将文字放在一个圆形内部。"
``` ```
```Plain ```Plain
"请设计一个以 ‘AIID’ 为品牌名的 Logo。 "请设计一个以 ‘AIID’ 为品牌名的 Logo。
整体风格要未来感、干净简洁，主色为蓝色与白色。 整体风格要未来感、干净简洁，主色为蓝色与白色。
将象征 AI 的抽象图形与文字相结合，并导出为带透明背景的 PNG。" 将象征 AI 的抽象图形与文字相结合，并导出为带透明背景的 PNG。"
``` ```
## 3. 向 Agent 请求设计 ## 3. 向 Agent 请求设计
* 输入上述提示词 → 比对 Agent 生成的多个设计稿。 - 输入上述提示词 → 比对 Agent 生成的多个设计稿。
![](images/image1.png)![](images/image2.png) ![](images/image1.png)![](images/image2.png)
## 4. 确定最终 Logo ## 4. 确定最终 Logo
* 从草稿中选择你最喜欢的版本并下载。 - 从草稿中选择你最喜欢的版本并下载。
--- ---
# 3. 规划你的网站结构 # 3. 规划你的网站结构
## 1. 了解基础版块 ## 1. 了解基础版块
在真正开始制作网站前，先规划好要包含哪些菜单（版块）非常重要。菜单的设计取决于你希望访客看到什么、以及你希望他们采取什么行动。 在真正开始制作网站前，先规划好要包含哪些菜单（版块）非常重要。菜单的设计取决于你希望访客看到什么、以及你希望他们采取什么行动。
@@ -103,18 +106,18 @@ Logo 是决定你网站第一印象的关键元素之一。想要从 AI 设计 A
### 可选菜单 ### 可选菜单
4. **Services / Projects** 4. **Services / Projects**
1. 展示你提供的服务，或你的项目 / 作品集 1. 展示你提供的服务，或你的项目 / 作品集
2. 通常以列表或卡片形式展示 2. 通常以列表或卡片形式展示
5. **Gallery** 5. **Gallery**
1. 用于展示图片、照片或设计作品 1. 用于展示图片、照片或设计作品
6. **Blog / News** 6. **Blog / News**
1. 用于发布文章、动态或日志 1. 用于发布文章、动态或日志
7. **FAQ**
7. **FAQ**
1. 整理访客经常会问的问题及解答 1. 整理访客经常会问的问题及解答
## 3. 选择配色方案（可选） ## 3. 选择配色方案（可选）
如果你已经有了 Logo，或者想用特定的颜色搭配来设计网站，也可以直接在提示词中写上你想使用的颜色代码。 如果你已经有了 Logo，或者想用特定的颜色搭配来设计网站，也可以直接在提示词中写上你想使用的颜色代码。
@@ -123,13 +126,13 @@ Logo 是决定你网站第一印象的关键元素之一。想要从 AI 设计 A
即使你暂时想不到配色方案，也可以通过配色网站或搜索关键词来找到灵感。 即使你暂时想不到配色方案，也可以通过配色网站或搜索关键词来找到灵感。
* **配色参考网站** - **配色参考网站**
* https://colorhunt.co/ - https://colorhunt.co/
* https://coolors.co/ - https://coolors.co/
![](images/image3.png)![](images/image4.png) ![](images/image3.png)![](images/image4.png)
* **在 Google 上通过关键词搜索配色** - **在 Google 上通过关键词搜索配色**
![](images/image5.png) ![](images/image5.png)
@@ -138,17 +141,18 @@ Logo 是决定你网站第一印象的关键元素之一。想要从 AI 设计 A
**示例提示词** **示例提示词**
```Plain ```Plain
"请设计一个由 Home、About、Contact 三个版块构成的单页网站。 "请设计一个由 Home、About、Contact 三个版块构成的单页网站。
使用配色 #171721、#FF7130 和 #FF3C68。 使用配色 #171721、#FF7130 和 #FF3C68。
整体风格要现代、简洁。" 整体风格要现代、简洁。"
``` ```
--- ---
# 4. 使用设计 Agent 设计网站 # 4. 使用设计 Agent 设计网站
## 1. 输入提示词 → 生成设计稿 ## 1. 输入提示词 → 生成设计稿
* 在提示词中写出你规划好的结构以及选定的配色。 - 在提示词中写出你规划好的结构以及选定的配色。
**Mastergo 提示词示例** **Mastergo 提示词示例**
@@ -158,10 +162,10 @@ Logo 是决定你网站第一印象的关键元素之一。想要从 AI 设计 A
你可以根据自己的需求，向 Agent 提出反馈，例如： 你可以根据自己的需求，向 Agent 提出反馈，例如：
* “太花哨了，整体风格改得更简洁一些。” - “太花哨了，整体风格改得更简洁一些。”
* “换一种字体。” - “换一种字体。”
* “调整一下颜色搭配。” - “调整一下颜色搭配。”
* “把这里这一块删掉。” - “把这里这一块删掉。”
![](images/image8.png) ![](images/image8.png)
@@ -188,21 +192,22 @@ Logo 是决定你网站第一印象的关键元素之一。想要从 AI 设计 A
--- ---
# 5. 使用编码 Agent 搭建网站 # 5. 使用编码 Agent 搭建网站
## 1. 理解 HTML/CSS/JS 的基础概念 ## 1. 理解 HTML/CSS/JS 的基础概念
一个网站本质上由三种语言构成： 一个网站本质上由三种语言构成：
* **HTML（HyperText Markup Language）** → 结构（骨架） - **HTML（HyperText Markup Language）** → 结构（骨架）
* **CSS（Cascading Style Sheets）** → 样式（外观） - **CSS（Cascading Style Sheets）** → 样式（外观）
* **JavaScript（JS）** → 功能（交互） - **JavaScript（JS）** → 功能（交互）
这三者配合在一起，构成我们看到的完整网页。 这三者配合在一起，构成我们看到的完整网页。
1. **🏗️ HTML（结构）** 1. **🏗️ HTML（结构）**
* 定义页面中“展示什么” - 定义页面中“展示什么”
* 用来放置文本、图片、按钮、链接等元素 - 用来放置文本、图片、按钮、链接等元素
* 类似于建筑物的 **墙体和框架** - 类似于建筑物的 **墙体和框架**
**示例** **示例**
@@ -214,9 +219,9 @@ Logo 是决定你网站第一印象的关键元素之一。想要从 AI 设计 A
2. **🎨 CSS（样式）** 2. **🎨 CSS（样式）**
* 决定“内容怎样展示” - 决定“内容怎样展示”
* 控制文字大小、颜色、间距、背景、按钮形状等 - 控制文字大小、颜色、间距、背景、按钮形状等
* 让 HTML 有了“衣服”和视觉风格 - 让 HTML 有了“衣服”和视觉风格
**示例** **示例**
@@ -235,9 +240,9 @@ body {
3. **⚙️ JavaScript（JS）（功能）** 3. **⚙️ JavaScript（JS）（功能）**
* 让网页能够和用户互动 - 让网页能够和用户互动
* 可以实现按钮点击、菜单展开、图片轮播、表单提交等动态效果 - 可以实现按钮点击、菜单展开、图片轮播、表单提交等动态效果
* 如果说 HTML/CSS 是静态的骨架和外观，那么 JS 就是让网页“活起来”的 **大脑** - 如果说 HTML/CSS 是静态的骨架和外观，那么 JS 就是让网页“活起来”的 **大脑**
**示例** **示例**
@@ -256,8 +261,8 @@ function showAlert() {
**示例提示词** **示例提示词**
```Plain ```Plain
"请为一个包含 Home、About 和 Contact 版块的单页网站编写 HTML 和 CSS。 "请为一个包含 Home、About 和 Contact 版块的单页网站编写 HTML 和 CSS。
使用配色 #171721、#FF7130、#FF3C68。 使用配色 #171721、#FF7130、#FF3C68。
背景为黑色，文字为白色。" 背景为黑色，文字为白色。"
``` ```
@@ -279,8 +284,8 @@ function showAlert() {
你可以继续通过自然语言对草稿进行微调，例如： 你可以继续通过自然语言对草稿进行微调，例如：
* “把按钮做大一点。” - “把按钮做大一点。”
* “字体粗一点。” - “字体粗一点。”
![](images/image13.png)![](images/image14.png) ![](images/image13.png)![](images/image14.png)
@@ -306,25 +311,26 @@ Agent 生成的初版网站，通常会包含一些自动生成的占位文本
如果你想加入特定图片（例如 Logo、背景图等），可以先把图片上传到项目文件夹中，然后在提示词里说明要在页面的什么位置使用这些图片。 如果你想加入特定图片（例如 Logo、背景图等），可以先把图片上传到项目文件夹中，然后在提示词里说明要在页面的什么位置使用这些图片。
* **示例：** - **示例：**
![](images/image18.png)![](images/image19.png)![](images/image20.png) ![](images/image18.png)![](images/image19.png)![](images/image20.png)
* **结果：** - **结果：**
![](images/image21.png) ![](images/image21.png)
--- ---
# 6. 将设计与代码整合 # 6. 将设计与代码整合
## 1. 将设计文件与网站代码整合（可选） ## 1. 将设计文件与网站代码整合（可选）
当你从设计 Agent 那里下载到了代码文件后，可以把它们移动到当前项目目录中，然后请编码 Agent 帮你将这些设计代码与现有项目进行合并。 当你从设计 Agent 那里下载到了代码文件后，可以把它们移动到当前项目目录中，然后请编码 Agent 帮你将这些设计代码与现有项目进行合并。
* **示例：** - **示例：**
![](images/image22.png) ![](images/image22.png)
* **结果：** - **结果：**
![](images/image23.png) ![](images/image23.png)
docs/examples/example1/example1-how-to-build-a-wechat-miniprogram.md
+2 -446
View File
@@ -1,447 +1,3 @@
# 如何构建一个最简单的微信小程序 # 微信小程序开发实战
# 1. 什么是微信小程序和微信小程序开发
在这篇教程中，我们将完整跑通一条闭环：从脑海中的一个想法，到在微信里可以搜索、可以扫码打开的真实小程序。 > 本章节正在编写中，敬请期待...
开始动手之前，我们需要先建立两个基本认知。
第一个是 **本质**：微信小程序到底是什么？它和普通 App、网页有什么不同？为什么这么多产品会选择用小程序这种形态？只有理解了小程序的底层逻辑，你才能判断自己的想法是否适合用小程序来实现。
第二个是 **路径**：当你说「我要做一个小程序」时，从零到上线的完整路径是什么样的？这条路上有哪些关键节点——构思阶段要考虑什么、开发环境怎么搭建、如何用 AI 辅助开发提高效率、模拟器调试有哪些坑、测试号和正式发布各自解决什么问题。把整个流程在脑子里先跑一遍，后面实操时才不会迷路。
搞清楚这两个问题之后，我们就可以正式进入开发环节了。接下来，让我们先从第一个问题开始：微信小程序究竟是什么。
## 1.1 微信小程序
微信小程序可以看成藏在微信里的应用。它不需要你去应用商店搜索、下载、安装，只要在微信里搜名字、扫码，或者点开别人分享的卡片，就能马上使用。用完直接关掉，下次需要再打开即可，不会长期占据你的手机桌面和存储空间。
对普通用户来说，小程序解决的是很多「一件小事」：查快递、点咖啡、看订单、玩一局小游戏。打开速度快、入口统一在微信里，这是它最大的体验特征。
对企业和开发者来说，小程序是一种可以被搜索、被分享的「小应用形态」。只要在微信公众平台上注册、配置好信息，通过审核，小程序就能对所有微信用户开放。和传统 App 相比，它更容易获得第一批用户，因为大家已经习惯在微信里完成很多事情。
在本教程里，我们不会做复杂的业务系统，而是选一个很经典的例子——贪吃蛇小游戏。它体量小、逻辑清晰，却又包含了一个完整小程序需要具备的元素：多个页面、简单交互、状态变化、分数记录等，非常适合作为你的第一个作品。
## 1.2 微信小程序开发
理解了「小程序是什么」，接下来要回答的问题是：那开发一个小程序，到底要做什么？
你需要有一个清晰的目标（例如：做一个可以随时玩一局的贪吃蛇），设计出用户会看到的界面，告诉系统在不同操作下应该发生什么，并最终把这个作品发布出去。
在传统的开发流程里，上面这些步骤往往都由程序员主导，需要写大量代码。而在 AI 辅助开发的场景下，这件事可以拆得更细：你负责讲清楚想做什么，AI 帮你完成大部分具体怎么写。 这也意味着，对于刚入门的人来说，最重要的能力不再是背多少语法，而是能不能把需求描述清楚、能不能读懂 AI 给出的结果。
## 1.3 微信小程序开发的几种方法
真正做小程序时，大家采用的技术路线并不完全一样。为了避免你一上来就被各种名词淹没，我们只做一个粗略分类，让你知道常见的几条路分别长什么样。
第一种方式，是直接使用微信官方提供的原生能力。在微信开发者工具中创建项目后，你会看到一组固定的文件类型，用它们来描述页面结构、样式和逻辑。这种方式贴近官方文档，控制力强，但对第一次接触前端的人来说，学习曲线会稍微曲折一些。
第二种方式，是利用多端框架，比如 uni-app 等。你在本地主要是写类似网页的代码（例如 .vue 文件），然后通过框架把这套代码转换成微信小程序可以识别的形式。这样的好处是：结构更统一，以后如果想把产品发布到其他平台（比如 H5、App），改动会相对少一些。
基于以上两种方式，本教程会重点讲述使用 AI 辅助开发工具的小程序开发SOP。比如把整个项目在 Trae 里打开，然后直接对内置的 AI 助手说： 请帮我在这个文件里加一个首页，有标题和按钮——请帮我写一个游戏页面，可以显示贪吃蛇和分数，AI 会在理解现有代码的基础上，为你生成新的代码片段，或者帮你修改、重构。
这三种方式并不是互斥的。你完全可以在一个 uni-app 项目里，借助 Trae 的 AI 功能来完成大部分编码工作。关键不是选哪一个方法，而是知道：自己现在处在什么位置，以及有哪些工具可以用。
## 1.4 本文介绍的微信小程序开发步骤（粗略预览）
本教程会带着**从环境到成品**的节奏，专门围绕贪吃蛇这个例子，结合 Trae 的 vibecoding 方式，把整个过程拆成一条你可以反复复用的路线。整体上，你将在后面的章节里经历这样几个阶段：
1. 先搭建认知地基：弄清楚什么是微信小程序、常见的开发方式有哪些，以及我们要做的这款贪吃蛇小程序面向谁、在什么场景被使用。
2. 然后完成环境准备：注册小程序账号，安装 HBuilderX、Trae 和微信开发者工具，并用 HBuilderX 创建一个可以在微信开发者工具中跑起来的基础项目骨架，让屏幕上先出现一个最简单的页面。
3. 接下来进入正式开发：在 Trae 中打开这个项目，用 vibecoding 的方式和 AI 对话，一步步生成首页和游戏页的布局，实现蛇移动、吃食物、游戏结束等核心玩法。
4. 在功能跑通之后，学会把 AI 当成「调试和重构伙伴」：遇到 bug 时请它一起排查，觉得结构乱时让它帮忙整理，并逐渐加上开始 / 暂停、最高分记录、界面微调等细节体验。
5. 最后进入发布环节：把项目构建成微信可识别的版本，在微信开发者工具中做预览和真机测试，先以测试号和体验版的形式上线验证流程，完成备案和审核后，再把小程序正式发布出去，让别人也能在微信里搜索到、玩到你的作品。
这一节只负责把全景图画出来，不展开具体命令和代码。你现在需要做的只是先大致记住这 5 步： **理解 → 搭环境 → vibecoding 开发 → 调试打磨 → 构建发布** 。后面的章节会在每一步上慢慢放大，告诉你要准备什么、要和 AI 说什么，以及在每个阶段你应该在屏幕上看到怎样的结果。
# 2. 环境准备
在开始写任何一行代码之前，我们先把开发环境准备好。 这一部分的目标，是让你在后面的章节里不再纠结 **去哪儿下载软件、为什么运行不了** ，而是可以直接把注意力放在和 AI 对话、实现需求上。
你只需要会打开浏览器、下载文件、双击安装程序，就可以完成本节全部步骤。
## 2.1 本教程会用到的三个工具
整个贪吃蛇小程序的开发，我们会同时用到三个工具，它们各自负责不同的环节：
1. 第一个是 Trae。你可以把它理解为一款集成了 AI 的代码编辑器，既能像普通 IDE 一样打开项目文件，又能让你直接用自然语言和 AI 交流，请它帮你写代码、改代码、解释代码。本教程里，大部分「和 AI 一起写小程序」的操作，都会在 Trae 里完成。你可以在浏览器中访问 https://www.trae.cn 获取最新版本。
2. 第二个是 HBuilderX。它是一款对 Vue 和 uni-app 支持特别好的编辑器，官方提供了很多现成的小程序项目模板。我们会用它来「一键生成」一个基础的小程序项目，相当于先打好地基，再把地基交给 Trae 和 AI 去改造。HBuilderX 的下载地址是 https://www.dcloud.io/hbuilderx.html 。
3. 第三个是微信开发者工具。这是微信官方提供的专门用来开发和预览小程序的工具。它负责把你写好的项目在电脑上跑起来，并支持在手机上进行真机调试。你可以从 https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html 下载适合你操作系统的版本。
简单总结一下：HBuilderX 帮你快速建一个小程序项目，Trae 帮你和 AI 一起写代码，微信开发者工具帮你看到真正运行中的小程序。
## 2.2 注册微信公众平台账号并获取 AppID
有了工具，还需要一个 **小程序身份** ，这一步在微信公众平台上完成。 如果你之前从来没有注册过微信小程序，可以按照下面的顺序来做：
1. 在浏览器地址栏输入 https://mp.weixin.qq.com ，打开微信公众平台网页，用你的微信扫码登录。
![](images/image1.png)
2. 在首页选择「小程序」，按照页面提示完成注册流程，填写邮箱、手机号以及主体类型（个人或企业）。
![](images/image2.png)
3. 注册成功并进入后台后，找到「开发管理」或「开发设置」页面，就能看到一个唯一的编号，名字叫 AppID 。这个编号后面会用在项目配置里，相当于你这个小程序在微信里的身份证。
![](images/image3.png)
建议你把 AppID 记录在一个方便找到的地方。后续章节在配置项目时，我们会直接把这个值填进去，让本地项目和线上小程序对应起来。
## 2.3 安装微信开发者工具
接下来，我们需要一个地方实际运行和预览小程序，这就是微信开发者工具存在的意义。
1. 访问下载页面 https://developers.weixin.qq.com/miniprogram/dev/devtools/download.html 。 在这个页面上，你会看到针对不同操作系统的多个版本，通常选择与你电脑系统匹配的稳定版即可，比如 Windows 64 位或 macOS 版本。
2. 下载完成后，双击安装包，按照安装向导一步步点击下一步。如果你不清楚要改什么设置，保持默认选项就可以。
3. 安装结束后，从桌面或开始菜单启动微信开发者工具。首次启动时，它会在屏幕上显示一个二维码，提示你用手机微信扫码登录。用自己的微信扫码并确认授权后，就可以进入主界面。
![](images/image4.png)![](images/image5.png)
后面当我们在 Trae 中准备好项目文件之后，就会把构建好的小程序导入到微信开发者工具里，在这里看到真实的运行效果。
## 2.4 准备 Trae 和 HBuilderX
最后，我们把真正负责写项目的两个工具安装好：Trae 和 HBuilderX。
你可以 **先安装 Trae** 。打开浏览器访问 https://www.trae.cn ，根据页面提示下载适合你系统的版本。安装过程和普通软件一样，双击安装包，按提示完成即可。安装完成后，你会得到一个可以打开本地文件夹、查看代码、和 AI 对话的 IDE，后续所有 vibecoding 步骤都会在这里进行。
![](images/image6.png)
**接着安装 HBuilderX** 。访问 https://www.dcloud.io/hbuilderx.html ，选择对应操作系统的发行包下载。HBuilderX 的包体非常小，启动速度也很快。安装完成后，你可以先熟悉一下它的界面，不需要深入研究功能；在后面的章节中，我们会用它来创建一个 uni-app 小程序模板，作为整个项目的起点。
![](images/image7.png)
完成本节的所有步骤之后，你已经具备了完整的开发环境：有微信小程序的账号和 AppID，有可以预览的小程序运行环境，也有可以和 AI 一起写代码的 IDE。在接下来的部分，我们会从**创建第一个小程序项目骨架**开始，让这些工具真正跑起来。
## 2.5基础文件准备
1. 点击新建项目
![](images/image8.png)
2. 选择默认模板，给小程序起名，选择存放路径，带你及右下角的创建：
![](images/image9.png)
3. 显示创建成功！
![](images/image10.png)
4. 接着可以在对应的文件夹中找到该文件夹，在Trae里面打开该文件夹，可以看到地基文件已经全部建造好：
![](images/image11.png)
# 3. 小程序开发
前面两部分，我们已经搞清楚了「小程序是什么」、以及「环境怎么配、工具怎么装」。 从这一节开始，正式进入实战：不再停留在概念层面，而是让 AI 真正帮你把贪吃蛇小程序从无到有做出来。
这一节，你会完整走完一次「开发环节」的 SOP，大致包括几步：
1. 在 Trae 里把当前项目打开，给 AI 下第一条完整指令，让它基于现有骨架设计并实现一个可运行的贪吃蛇版本。
2. 让 Trae 直接改动真实项目文件，而不是只给你“示例代码”，并学会用回退功能在需要时恢复到修改前的状态。
3. 回到 HBuilderX 和微信开发者工具，通过「运行到小程序模拟器」的方式在模拟器里试玩这一版，实现从“代码视角”到“用户视角”的切换。
4. 根据试玩结果，用自然语言持续提出修改需求，让 AI 帮你从按键控制迭代到摇杆控制，顺便体验一次「发现问题 → 描述问题 → AI 修复 → 再次验证」的闭环。
你当然可以选择先在开发前，把每个页面、每个按钮都想得一清二楚，再交给 AI。 但对完全小白来说，小程序的界面和交互设计本身也是一个全新的领域（后面我们会教你怎么用 AI 帮忙做设计），所以在这一次，我们刻意采用另一种方式： 先开干 ——让 AI 先生成一个能跑起来的版本，再一边看效果、一边用自然语言慢慢打磨和调整。
## 3.1 把需求一次性说清楚：给 Trae 下第一条“总指令”
打开 Trae，载入前面已经准备好的小程序项目之后，我先没有急着改某一行代码，而是对内置的 AI 助手说了这样一件事：
**我向AI“发号施令”，说我现在需要基于现在的框架写一个贪吃蛇小程序，请给设计此小程序并我写一个prompt。**
也就是说，我不是「一点点要求它写某个函数」，而是先抛出一个完整目标，让 AI 帮我规划，但是AI不仅帮我做了计划，还直接落地第一版实现。
Trae 收到这条指令之后，会自动阅读当前项目结构，判断应该在哪些文件里增加页面、在哪些地方补充逻辑，然后直接对项目中的文件或代码做出修改，而不需要你自己去手搓代码或者增删改查文件/文件夹。
## 3.2 让 AI 自动修改代码，而不是“手搓”
当你在 Trae 中点击执行这条指令时，AI 会进入一个「帮你改工程」的流程。 在这个过程中，你可以看到几个关键点：
1. 它会在对话区解释自己的思路，比如会在哪个目录下新增页面、打算如何组织游戏逻辑。
![](images/image12.png)![](images/image13.png)
2. 它会直接对真实项目文件做增删改，而不是只给你一段「示例代码」让你自己拷贝。
3. 修改完成后，Trae 会生成一个简短的小结，告诉你：这次它改了哪些文件，大致做了哪些事情。
如果你对这一轮修改不满意（或者觉得某一步有问题），也不用紧张。Trae 在你发出对话的对话框外的左上角提供了「回退」能力，你可以一键把工程恢复到本次指令执行之前的状态，相当于给这次操作加了一个安全的撤销键。
![](images/image14.png)
![](images/image15.png)
## 3.3 在 HBuilderX 和微信开发者工具中查看效果
AI 完成第一轮开发之后，代码已经落在项目里了，但这时候你还没有看到玩家视角的效果。 下一步，我们需要把它跑起来。
具体做法是：回到 HBuilderX，找到顶部菜单的「运行」选项，选择「运行到小程序模拟器」中的「微信开发者工具」。这一操作会触发项目编译，并将结果交给微信开发者工具打开。
![](images/image16.png)
底部的输出窗口会显示编译的过程。如果最终状态是「ready」且没有报错，就说明构建成功，你可以切到微信开发者工具里查看这一版小程序的界面和功能。
![](images/image17.png)
在大多数情况下，HBuilderX 会自动帮你打开微信开发者工具，让你直接看到新的小程序。如果没有自动打开，你可以按下面的方式处理：
1. 先在 HBuilderX 中停止当前运行。
2. 手动启动微信开发者工具，让它处于打开状态。
3. 回到 HBuilderX，再次点击「运行 → 运行到小程序模拟器 → 微信开发者工具」。
这样我们就可以微信小程序开发者工具中看到我们Vibecoding的小程序：
![](images/image18.png)
## 3.4 用自然语言反复调整和完善小程序，直到我们满意
在这次实践中，AI 一开始给我生成的是按键控制方向的贪吃蛇：屏幕上有四个方向按钮，点击不同方向，蛇就会改变运动方向。 功能上完全可以玩，但我个人更喜欢用摇杆控制。对于你的调整需求（不仅限于功能、UI设计、界面，等你熟练后，你甚至可以用自然语言让AI帮你接入其他大模型的API或接入数据库）——再强调一遍，你只需要用自然语言告诉大模型即可。
这就是 vibecoding 的优势所在：你不必自己去翻代码，查找事件绑定的位置、计算坐标的逻辑，而是直接把想法告诉 AI。例如，你可以在 Trae 的对话框里这样描述：
把按键换成摇杆控制，并且用户松开摇杆时蛇保持同方向移动，直到用户再次松开摇杆。
只要你把需求讲得足够清楚，AI 会自动定位到对应界面和逻辑文件，替你完成控件样式、交互绑定和方向处理等改动。
![](images/image19.png)
修改完成后，再回到微信开发者工具中查看。 如果没有立刻看到变化，可以尝试点击开发者工具上的「运行」按钮，或者刷新小程序预览窗口，让最新的构建结果生效。 仍然没有更新时，可以在 HBuilderX 中先停止运行，再重新执行一次「运行到小程序模拟器」，即可看到调整之后的小程序：
![](images/image20.png)
## 3.5 出现问题怎么办：继续用自然语言沟通
AI 生成的版本不一定一开始就完美。有时候你会遇到这些情况：
* 运行时报错，小程序无法正常打开；
* 功能大致正确，但细节和你想象的不太一样；
* 界面可以用，但你觉得还可以更好看或更顺手。
在这些时候，不需要自己钻进代码里盲改，而是可以把遇到的问题直接用自然语言重新描述给 Trae 中的 AI 助手，例如：
现在摇杆控制已经生效了，但有时候蛇会突然停止不动，请帮我检查当前实现哪里有问题。 或者： 现在游戏可以玩，但界面有点拥挤，我希望在手机上显示时上下留出更多空白。请你帮我调整布局。
AI 会根据你当前的项目状态和描述，给出修改建议并直接应用在代码里。如果修改之后结果更糟或方向不对，你依然可以使用回退，把工程恢复到前一个稳定版本，再换一种说法尝试。
通过这几轮往返，你会从最初的“毛坯版本”，逐步打磨出一个更贴近自己喜好的摇杆版贪吃蛇小程序。例如我给出了一种图画风格，让AI根据此风格来调整小程序的UI风格：
![](images/image21.png)
## 3.6 最终成品与本节小结
经过一轮又一轮的 **自然语言叙述 → AI 修改 → 在微信开发者工具中预览 → 继续对话微调** ，我最终得到的是这样一个成品：
* 有完整的游戏页面；
* 蛇可以顺畅移动并吃到食物；
* 支持摇杆控制；
* 在小程序模拟器中可以顺利运行。
最终开发成品如下：
![](images/image22.png)![](images/image23.png)![](images/image24.png)
在这一节里，你已经看到了一个完整的闭环：
1. 在 Trae 中用一句清晰的指令，让 AI 搭出第一版贪吃蛇小程序；
2. 借助 HBuilderX 和微信开发者工具，从用户视角检查实际效果；
3. 用自然语言反复向 AI 提出修改需求，让它替你完成功能调整和界面优化；
4. 在任何一步出现问题时，都可以通过回退和重新运行来保证安全。
接下来，你可以按照同样的节奏去尝试自己的想法：不一定非要是贪吃蛇，也可以是一个工具小程序、一个活动页，甚至是你工作中真正需要的业务原型。你的主要任务，是把需求想清楚、说清楚，其余的交给 AI 和这些工具来配合完成。
# 4.小程序发布
前面三章，我们已经完成了从 **搭环境** ——**和 AI 一起开发**到**在本地模拟器里跑通贪吃蛇**的整个流程。
从这一章开始，我们关心的问题变成了：**怎样把这个作品真正挂到微信上，不只是一个小玩具，而是所有人都可以使用的微信小程序呢？**
为了降低门槛，我们先走一条 **最短闭环** ：只让它以**测试号**的形式上线，先自己和少数同学体验；等到你觉得功能和体验都足够稳定，再走正式上线流程。
本章先讲到 4.1，帮你完成**测试号上线**这条最短路径；关于面向所有用户的正式上线，会在 4.2 中再展开。
## 4.1 最短 SOP —— 测试号上线
这一小节的目标只有一个：让你在微信里，真的能以**体验版**的形式打开自己的贪吃蛇小程序。
整个流程可以理解为四件事：
1. 在微信公众平台找到并确认自己的 AppID。
2. 在项目里把这个 AppID 配置好。
3. 用微信开发者工具上传当前版本。
4. 回到公众平台，把这次上传的版本设置为「体验版」。
下面我们按照这个顺序来走一遍。
### 4.1.1 在微信公众平台确认 AppID
第一步，是在微信公众平台上确认你的小程序 AppID。
这一步你之前在**2.环境准备**时已经做过一次，这里是把它真正用起来。
1. 打开浏览器，访问 `https://mp.weixin.qq.com`，登录你的小程序后台。
2. 在左侧菜单中找到「开发管理」，进入其中的「开发设置」。
3. 在页面上方，你会看到一块叫做「开发者 ID」的区域，里面有一行「AppID（小程序 ID）」——这就是你的小程序唯一编号。
这串编号需要和项目中的配置一一对应，否则微信会认为你上传的是「别人的小程序」，自然无法正常预览和发布。
![](images/image25.png)
### 4.1.2 在项目中填写 AppID
第二步是把这个 AppID 写进你的项目配置里，让本地构建出来的小程序和公众平台上的这个「账号」对应上。
如果你是用 uni-app 模板来做的项目，可以按照下面的方式操作：
1. 打开 HBuilderX，载入你的贪吃蛇项目。
2. 在左侧文件树中找到 `manifest.json`，双击打开。
3. 下拉到「微信小程序配置」这一栏，你会看到一个输入框，提示类似「微信小程序 AppID（请在微信开发者工具中获取）」。
4. 把刚才在公众平台上看到的 AppID 原样粘贴进来，保存文件。
![](images/image26.png)
到这里为止，你的本地项目就已经认领了这个小程序身份。接下来，只要通过微信开发者工具上传版本，它就会被记在这个 AppID 名下。
### 4.1.3 在微信开发者工具中上传一个版本
前面我们已经用 HBuilderX 把项目运行到微信开发者工具里，看过模拟器中的效果。
现在要做的是：在开发者工具中，把当前这份代码“”打一个版本包”上传到服务器上。
大致步骤如下：
1. 在微信开发者工具顶部工具栏的右侧，你会看到一个「上传」按钮，点击它。
2. 弹出的窗口中，需要填写两个关键字段：
1. 版本号：例如 `1.0.0`，只允许数字和小数点。
2. 项目备注：写一段简短说明，比如「完成基本功能的开发」。
3. 检查无误后，点击「上传」按钮。下面的输出区域会显示编译过程，所有步骤变成绿色并提示上传完成，就说明这一版已经成功提交到了微信服务器。
![](images/image27.png)
![](images/image28.png)
![](images/image29.png)![](images/image30.png)
### 4.1.4 在管理后台中把版本设为体验版
上传只是把代码送到了微信这边，还没告诉系统“这是一版可以试用的体验版本”。
最后一步，我们回到公众平台的小程序后台，完成这个闭环。
1. 再次打开 `https://mp.weixin.qq.com`，进入你的小程序后台。
2. 在左侧找到「管理」下面的「版本管理」，点击进入。
3. 在页面的「开发版本」一栏，你应该能看到刚刚上传的那个版本：版本号是 `1.0.0`，备注是你写的那一段说明，时间是刚刚的上传时间。
4. 在这一行的右侧，会有一个下拉按钮或操作按钮，可以选择「设为体验版」，点击之后，确认操作，注意在这一步之前请确保你已经在首页-小程序类目设置好了你的主营类目。
![](images/image31.png)
![](images/image32.png)
完成之后，这个版本就变成了你的小程序「体验版」。你可以在后台生成体验版二维码，也可以把自己和同事加入「体验成员」，让大家用微信扫描后，在真机上体验这款贪吃蛇小程序。
到这里，我们就完成了从本地项目到测试号上线的最短闭环：
你不需要一开始就面向所有微信用户开放，只是在一个安全的范围内，让真实的小程序跑在真实的微信环境里。这足够你用来测试功能、收集反馈、继续迭代。
## 4.2 小程序正式上线
体验版跑通之后，你已经可以在自己的微信里玩到这款贪吃蛇小程序了。 接下来要做的，就是把它从只有少数体验成员能用的状态，推进到全民可用正式微信小程序。
把这件事拆成几步：先补充信息，再选择类目，然后完成备案，最后提交审核。下面按照这个顺序走一遍。
### 4.2.1 进入小程序发布流程
首先回到微信公众平台后台，登录你的小程序账号。 在左侧导航里找到与「版本管理 / 发布」相关的入口（不同时间界面可能略有调整），展开后会看到「小程序发布流程」这一项。
点击进入之后，界面上方会显示一个进度条，下面依次列出几个步骤，例如：
1. 小程序信息
2. 小程序类目
3. 运营信息 / 小程序备案
4. 微信认证（视你的主体而定）
一开始进度会显示 0%，随着你完成每一步，系统会自动把进度向前推进。
![](images/image33.png)
### 4.2.2 填写小程序基本信息
第一步是把小程序的「名片」补充完整，这也是用户在微信里第一次看到你的时候会接触到的内容。
在「小程序信息」页面，你通常需要填写和确认以下内容：
1. 小程序名称 这个名字会出现在搜索结果和小程序顶部，有长度限制，同时需要符合微信的命名规范。建议选择既能表达功能，又方便记忆的名称，例如「贪吃蛇 vibecoding 版」这一类。
2. 功能介绍 / 简介 用一两句话说明这个小程序是做什么的，例如：「一款用 AI 辅助开发完成的贪吃蛇小游戏，适合在碎片时间玩一局。」 注意简介要和实际功能一致，避免使用夸张宣传语。
3. 图标和展示图片
1. 图标一般要求为正方形图片，支持 PNG/JPG 等格式，大小和像素有明确限制（以页面说明为准），建议提供一张简洁、对比度高的图。
2. 展示图片可以上传几张小程序页面的截图，例如首页、游戏页面、设置界面等，这些会出现在详情页中，帮助用户了解内容。
4. 其他必要信息 例如标签、服务区域等，根据页面提示填写即可。 原则只有一个：所有填写的内容都要和这款贪吃蛇小程序真实功能相符。
![](images/image34.png)
全部填写完毕后，点击保存或下一步，发布流程中的第一步就完成了。
### 4.2.3 选择小程序服务类目
完成基本信息后，向导会引导你进入「小程序类目」步骤。 类目可以理解为小程序在微信里的「归属分类」，决定它在审核时会被归入哪一类应用，也会影响后续展示和运营。
![](images/image35.png)
在这个页面，你会看到「添加类目」按钮。点击后，可以从系统提供的分类树中选择适合你小程序的方向，例如：
![](images/image36.png)
1. 先选择「教育」这一大类；
2. 再在下面选择「教育工具 / 教学辅助」等更具体的子类，本次我选择了教育器具，当做大家学习Vibecoding的教具吧~
你在自己的项目里，只需要根据实际用途选择最贴切的一项即可。
![](images/image37.png)
![](images/image38.png)
确认类目后，点击保存。如果页面提示「创建类目成功」，并在列表中显示你刚刚添加的那一项，就说明这一步已经完成。
### 4.2.4 完成小程序备案信息
接下来，发布流程会要求你完成「运营信息 / 小程序备案」部分。这一步是为了验证小程序的主体身份，确保上线的应用有明确责任人。
![](images/image39.png)
在个人主体的示例下，大致会经历这样几个动作：
1. 选择备案类型 页面会让你在不同主体类型之间进行选择，例如「个人」「企业」等。根据你注册小程序时的主体保持一致即可。
2. 填写主体信息 包括姓名、证件类型、证件号码等基本信息。 这一部分需要与注册信息保持一致，否则可能会在审核时被退回。
3. 上传证明材料 页面通常会要求你上传身份证照片或其他证明文件，具体格式、清晰度和大小要求会写在说明里。 按提示准备好图片后上传，确保内容清晰可辨。
![](images/image40.png)
提交之后，系统会进入「审核中」状态，页面上会显示类似「信息已提交，请耐心等待」的提示。这个过程可能需要一定时间，你可以在后台随时查看备案进度。
![](images/image41.png)
### 4.2.5 提交审核并等待正式发布
当「小程序信息」「小程序类目」「运营信息 / 备案」等步骤全部被勾选完成后，你就可以进行最后一个动作：提交审核。
1. 回到「小程序发布流程」总览页面，确认每一项都显示为已完成，进度条接近 100%。
2. 根据页面提示，点击「提交审核」或类似按钮，把当前开发版本送交微信团队审核。
3. 在「版本管理」中，你会看到这次提交的版本状态变为「审核中」。通过后，会变成「已发布」或可选择「上线」的状态。
备案审核不通过会打电话给开发者，提示不通过的部分。
备案会收到“工业和信息化部”发来的验证码，和核验链接，点击进入把验证码和个人信息填入就行（核验有效期是1天）备案通过会收到“工业和信息化部”发送的邮件和短信通知，并且告知备案号。微信认证：个人缴纳30元，公司企业貌似是300元，不管认证是否通过都钱都不退回，会收到认证通知，并且接到电话确认信息
提交进行审核，要上传操作视频和页面，填好信息提交即可 ，点击“提交发布”，就正式发布了
![](images/image42.png)
# 5.总结
到这里，你已经完整跑完了一次**从0到1**的小程序开发闭环： 从认识微信小程序，到装好 Trae、HBuilderX 和微信开发者工具；从把想法丢给 AI，让它在代码里替你“搬砖”，到在模拟器里试玩第一版贪吃蛇；再到把作品打成体验版、走完备案和审核，真正在微信里让人使用——这条链路你已经亲手走通了一遍。
更重要的是，你不是靠死记硬背语法做到这一点的，而是靠清楚地表达需求 + 和 AI 有效沟通来实现的 。你已经体验过 **:一句自然语言指令，可以让AI完美满足你的开发要求** 。这种能力不会只停留在贪吃蛇上，它可以迁移到你以后想做的任何小程序——工具、活动页、教学应用，甚至是你工作中的真实项目。
如果要给你一个 **通用SOP** ，其实只有五步：** 想清楚一个小需求 → 在 Trae 里搭好项目骨架 → 用 vibecoding 和 AI 搭出第一版 → 在微信开发者工具里不断试玩和改进 → 上传、备案、审核、上线。** 每次你重复这五步，就会多一个真正能被人打开、能被分享的小程序，也会多一份「我可以用 AI 把点子变成产品」的信心。
接下来，你可以继续打磨这款贪吃蛇，也可以关掉它，重新起一个空项目，从你自己的想法出发。无论做什么，只要记住一点： 你不再只是一个「想做点东西」的人，而是已经跑通了全流程的 vibecoding 开发者。剩下的，就是多做几次，把这种能力变成习惯。
# 参考资料：
- https://zhuanlan.zhihu.com/p/1889401120939567074
- https://blog.csdn.net/2401_87407347/article/details/155193007
docs/extra/README.md
+10
View File
@@ -0,0 +1,10 @@
# Extra 扩展知识
这里包含了额外的扩展知识文档：
- [Extra 1: Git and GitHub](extra1/extra1-what-is-git-and-what-is-github.md)
- [Extra 2: What is API](extra2/extra2-what-is-api.md)
- [Extra 3: AI Capability Starter Handbook](extra3/extra3-ai-capability-starter-handbook.md)
- [Extra 5: What is RAG](extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md)
- [Extra 6: Zeabur Deployment](extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md)
- [Extra 7: CLI AI Coding Tools](extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md)
docs/extra/extra1/extra1-what-is-git-and-what-is-github.md
+32 -32
View File
@@ -44,13 +44,13 @@ Git 是由 Linux 内核开发者 Linus Torvalds 于 2005 年创建的分布式
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 安装程序。 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. 双击安装程序并按照安装向导说明进行操作： 2. 双击安装程序并按照安装向导说明进行操作：
![](images/image5.png) ![](images/image5.png)
1. 建议保持默认选项。如果你需要自定义，请注意以下几点：（在大多数情况下，你可以一直点击“Next”） 1. 建议保持默认选项。如果你需要自定义，请注意以下几点：（在大多数情况下，你可以一直点击“Next”）
* 选择 Git 使用的默认编辑器：选择你喜欢的编辑器（如 VS Code）。你可以默认选择第一个选项，即 Vim（一个文本编辑器），或选择“Visual Studio Code as Git's default editor”选项（需要预先安装 VS Code）。你可以保持默认选择并点击“Next”继续。 - 选择 Git 使用的默认编辑器：选择你喜欢的编辑器（如 VS Code）。你可以默认选择第一个选项，即 Vim（一个文本编辑器），或选择“Visual Studio Code as Git's default editor”选项（需要预先安装 VS Code）。你可以保持默认选择并点击“Next”继续。
![](images/image6.png) ![](images/image6.png)
* 选择如何使用 Git：这三个选项控制 Git 在系统中的可访问性。建议选择选项 2（“from command line and 3rd-party software”）——它将基本的 Git 工具添加到 PATH 中，让你可以在 Git Bash、命令提示符、PowerShell 和 IDE 中使用 Git，而不会使系统混乱。 - 选择如何使用 Git：这三个选项控制 Git 在系统中的可访问性。建议选择选项 2（“from command line and 3rd-party software”）——它将基本的 Git 工具添加到 PATH 中，让你可以在 Git Bash、命令提示符、PowerShell 和 IDE 中使用 Git，而不会使系统混乱。
![](images/image7.png) ![](images/image7.png)
3. 安装后，在桌面上右键单击。如果在菜单中看到“Git Bash Here”，则安装成功。 3. 安装后，在桌面上右键单击。如果在菜单中看到“Git Bash Here”，则安装成功。
![](images/image8.png) ![](images/image8.png)
@@ -70,20 +70,20 @@ Git 是由 Linux 内核开发者 Linus Torvalds 于 2005 年创建的分布式
大多数 Linux 发行版可以通过其包管理器安装 Git： 大多数 Linux 发行版可以通过其包管理器安装 Git：
* Ubuntu/Debian: - Ubuntu/Debian:
```Bash ```Bash
sudo apt update sudo apt update
sudo apt install git sudo apt install git
``` ```
* CentOS/RHEL: - CentOS/RHEL:
```Bash ```Bash
sudo yum install git sudo yum install git
``` ```
* 验证安装：在终端中输入 git --version。如果显示版本号，则安装成功。 - 验证安装：在终端中输入 git --version。如果显示版本号，则安装成功。
## Git 初始化 ## Git 初始化
@@ -118,7 +118,7 @@ GitHub 不仅是世界上最大的代码托管平台，也是全球最活跃、
## 注册 GitHub 账号 ## 注册 GitHub 账号
1. 访问 [GitHub 官网](https://github.com/) 并点击右上角的“Sign up”。 1. 访问 [GitHub 官网](https://github.com/) 并点击右上角的“Sign up”。
![](images/image11.png) ![](images/image11.png)
2. 输入你的电子邮件地址（建议使用常用邮箱，因为验证和通知将发送到那里），设置密码（必须包含字母、数字和特殊字符）。 2. 输入你的电子邮件地址（建议使用常用邮箱，因为验证和通知将发送到那里），设置密码（必须包含字母、数字和特殊字符）。
3. 完成人工验证，按照提示验证邮箱，你的账号就创建好了。 3. 完成人工验证，按照提示验证邮箱，你的账号就创建好了。
@@ -166,8 +166,8 @@ GitHub 不仅是世界上最大的代码托管平台，也是全球最活跃、
GitHub 支持两种主要的仓库操作协议：HTTPS 协议和 SSH 协议： GitHub 支持两种主要的仓库操作协议：HTTPS 协议和 SSH 协议：
* HTTPS 协议：每次操作（如 push）都需要输入 GitHub 账号密码（或个人访问令牌 PAT）。验证过程繁琐，且存在密码泄露风险。 - HTTPS 协议：每次操作（如 push）都需要输入 GitHub 账号密码（或个人访问令牌 PAT）。验证过程繁琐，且存在密码泄露风险。
* SSH 协议：身份验证通过“密钥对”完成，因此不需要重复输入密码，且加密传输更加安全。 - SSH 协议：身份验证通过“密钥对”完成，因此不需要重复输入密码，且加密传输更加安全。
“SSH 协议绑定”是启用 GitHub SSH 认证的前提步骤——只有将本地 SSH 公钥“绑定”到 GitHub 账号后，GitHub 才能识别你的设备并允许对仓库进行 SSH 操作。 “SSH 协议绑定”是启用 GitHub SSH 认证的前提步骤——只有将本地 SSH 公钥“绑定”到 GitHub 账号后，GitHub 才能识别你的设备并允许对仓库进行 SSH 操作。
@@ -180,9 +180,9 @@ SSH 认证依赖于密钥对（公钥 + 私钥），它们是匹配的加密文
当你通过 SSH 操作 GitHub 仓库时（例如 git push git@github.com:xxx/xxx.git）： 当你通过 SSH 操作 GitHub 仓库时（例如 git push git@github.com:xxx/xxx.git）：
* 你的本地设备使用私钥加密“操作请求”并发送给 GitHub； - 你的本地设备使用私钥加密“操作请求”并发送给 GitHub；
* 收到请求后，GitHub 尝试使用你之前绑定的公钥进行解密； - 收到请求后，GitHub 尝试使用你之前绑定的公钥进行解密；
* 如果解密成功，你的设备被确认为已授权，操作被允许；否则，访问被拒绝。 - 如果解密成功，你的设备被确认为已授权，操作被允许；否则，访问被拒绝。
### “绑定”的具体步骤（核心流程） ### “绑定”的具体步骤（核心流程）
@@ -192,23 +192,23 @@ SSH 认证依赖于密钥对（公钥 + 私钥），它们是匹配的加密文
1. 使用 Trae 获取公钥（推荐） 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` 提示词：`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`
![](images/image18.png) ![](images/image18.png)
输入提示词后，你还需要在左侧终端按 Enter 键，否则命令会一直等待而不执行。由于 Trae 无法帮你执行任何条件判断，我们只需要一直按 Enter 即可。 输入提示词后，你还需要在左侧终端按 Enter 键，否则命令会一直等待而不执行。由于 Trae 无法帮你执行任何条件判断，我们只需要一直按 Enter 即可。
最后，你会看到右侧的 Trae 返回了它读取的公钥。你只需复制它并准备在下一步中粘贴。 最后，你会看到右侧的 Trae 返回了它读取的公钥。你只需复制它并准备在下一步中粘贴。
![](images/image19.png) ![](images/image19.png) 2. 手动获取公钥
2. 手动获取公钥 打开你的本地终端（在 Windows 上使用 Git Bash 或 PowerShell；在 macOS/Linux 上使用终端），输入以下命令（将 your_email@example.com 替换为你注册 GitHub 账号时使用的邮箱）：
打开你的本地终端（在 Windows 上使用 Git Bash 或 PowerShell；在 macOS/Linux 上使用终端），输入以下命令（将 your_email@example.com 替换为你注册 GitHub 账号时使用的邮箱）：
```Bash ```Bash
ssh-keygen -t ed25519 -C "your_email@example.com" ssh-keygen -t ed25519 -C "your_email@example.com"
``` ```
1. 按 Enter 接受默认值（默认文件路径，无密码，或根据需要设置密码）。这将在 ~/.ssh/ 目录中生成两个文件：
- id_ed25519：私钥（本地保存，**绝不分享**）；
- id_ed25519.pub：公钥（需要上传到 GitHub）。
1. 按 Enter 接受默认值（默认文件路径，无密码，或根据需要设置密码）。这将在 ~/.ssh/ 目录中生成两个文件：
* id_ed25519：私钥（本地保存，**绝不分享**）；
* id_ed25519.pub：公钥（需要上传到 GitHub）。
2. 将公钥“绑定”到你的 GitHub 账号 2. 将公钥“绑定”到你的 GitHub 账号
这是核心绑定步骤——将本地公钥添加到 GitHub 账号的“SSH keys list”中： 这是核心绑定步骤——将本地公钥添加到 GitHub 账号的“SSH keys list”中：
@@ -219,7 +219,7 @@ SSH 认证依赖于密钥对（公钥 + 私钥），它们是匹配的加密文
3. macOS/Linux：在终端运行 cat ~/.ssh/id_ed25519.pub 并复制所有输出（从开头的 SSH-ed25519 到结尾的邮箱）。 3. macOS/Linux：在终端运行 cat ~/.ssh/id_ed25519.pub 并复制所有输出（从开头的 SSH-ed25519 到结尾的邮箱）。
2. 登录 GitHub 并进入“SSH Key Management”页面： 2. 登录 GitHub 并进入“SSH Key Management”页面：
1. 点击右上角头像 → Settings → 左侧菜单 SSH and GPG keys → 点击 New SSH key。 1. 点击右上角头像 → Settings → 左侧菜单 SSH and GPG keys → 点击 New SSH key。
![](images/image20.png)![](images/image21.png) ![](images/image20.png)![](images/image21.png)
2. 输入任何标题（例如，your local computer's SSH），然后将你刚刚获取的 SSH 公钥粘贴到这里。 2. 输入任何标题（例如，your local computer's SSH），然后将你刚刚获取的 SSH 公钥粘贴到这里。
![](images/image22.png) ![](images/image22.png)
@@ -234,8 +234,8 @@ SSH 认证依赖于密钥对（公钥 + 私钥），它们是匹配的加密文
ssh -T git@github.com ssh -T git@github.com
``` ```
* 如果你看到类似 Hi [your GitHub username]! You've successfully authenticated... 的内容，说明你已成功绑定密钥； - 如果你看到类似 Hi [your GitHub username]! You've successfully authenticated... 的内容，说明你已成功绑定密钥；
* 如果遇到错误，通常是因为公钥复制不完整、私钥权限过高（你的本地 ~/.ssh/ 目录应仅由你读写）等。根据需要检查这些问题。 - 如果遇到错误，通常是因为公钥复制不完整、私钥权限过高（你的本地 ~/.ssh/ 目录应仅由你读写）等。根据需要检查这些问题。
### 重要注意事项 ### 重要注意事项
@@ -275,5 +275,5 @@ prompt:`I finished. Commit and push to the repository AIID-TEST in ./AIID-TEST.`
# 参考资料 # 参考资料
* Pro Git book https://git-scm.com/book/en/v2 - Pro Git book https://git-scm.com/book/en/v2
* GitHub Docs https://docs.github.com/en - GitHub Docs https://docs.github.com/en
docs/extra/extra2/extra2-what-is-api.md
+44 -39
View File
@@ -6,19 +6,19 @@
为了解决这些痛点，本篇手册以“API 核心逻辑”为整理思路。在这本手册里，我们想做的不是堆名词，而是帮你快速搞清楚三件事：**“这件事可以用什么 API 做？它的本质逻辑是什么？接下来该怎么安全地调用它？”** 通过从生活类比到代码实践的系统梳理，我们将为你揭开 API 的神秘面纱，帮你建立起从“逻辑认知”到“场景映射”再到“代码实现”的完整链路。 为了解决这些痛点，本篇手册以“API 核心逻辑”为整理思路。在这本手册里，我们想做的不是堆名词，而是帮你快速搞清楚三件事：**“这件事可以用什么 API 做？它的本质逻辑是什么？接下来该怎么安全地调用它？”** 通过从生活类比到代码实践的系统梳理，我们将为你揭开 API 的神秘面纱，帮你建立起从“逻辑认知”到“场景映射”再到“代码实现”的完整链路。
> 由于 **内容较多** ，你可以在实践过程中遇到场景不知道如何选型的问题再查阅手册寻找参考；推荐你**根据具体应用方向，让 AI 参考该手册，给出可参考的模型选型建议、方案 API 调用建议即可。** > 由于 **内容较多** ，你可以在实践过程中遇到场景不知道如何选型的问题再查阅手册寻找参考；推荐你**根据具体应用方向，让 AI 参考该手册，给出可参考的模型选型建议、方案 API 调用建议即可。**
> >
> 如果你只想了解对应的类别，不想看具体内容，只需要看每个大章节的初始段内容即可，例如 1 、2 的内容，但不需要看 5.1 或者 5.2 的代码细节。 > 如果你只想了解对应的类别，不想看具体内容，只需要看每个大章节的初始段内容即可，例如 1 、2 的内容，但不需要看 5.1 或者 5.2 的代码细节。
> >
> **推荐本手册只在需要时查阅对应部分或只浏览一级目录部分，若有兴趣再浏览全文。** > **推荐本手册只在需要时查阅对应部分或只浏览一级目录部分，若有兴趣再浏览全文。**
> >
> **之后更新会在每个章节部分，推荐可尝试使用的模型 API 服务地址。** > **之后更新会在每个章节部分，推荐可尝试使用的模型 API 服务地址。**
# 本节课你将学到 # 本节课你将学到
* **核心概念映射**：通过“电源插座”与“餐厅点餐”等经典类比，建立对 API 请求与响应循环的直观理解。 - **核心概念映射**：通过“电源插座”与“餐厅点餐”等经典类比，建立对 API 请求与响应循环的直观理解。
* **现实场景解析**：了解天气、地图、社交登录及大语言模型等主流 API 的工作原理，掌握从“功能”到“接口”的映射方法。 - **现实场景解析**：了解天气、地图、社交登录及大语言模型等主流 API 的工作原理，掌握从“功能”到“接口”的映射方法。
* **代码实践与安全**：掌握 Python 环境下 AI API 的调用方式，并理解前端开发中后端代理等安全工程实践的重要性。 - **代码实践与安全**：掌握 Python 环境下 AI API 的调用方式，并理解前端开发中后端代理等安全工程实践的重要性。
完成本手册的学习后，你将对主流 API 能力建立起入门级的系统化认知，不仅知道“市面上有哪些接口、常配哪些产品”，更能理解它们在整体架构中的位置和相互关系。知道在面对具体业务需求时，如何快速定位所需能力、做出有依据的选型，为构建 AI 应用体系打下坚实基础。 完成本手册的学习后，你将对主流 API 能力建立起入门级的系统化认知，不仅知道“市面上有哪些接口、常配哪些产品”，更能理解它们在整体架构中的位置和相互关系。知道在面对具体业务需求时，如何快速定位所需能力、做出有依据的选型，为构建 AI 应用体系打下坚实基础。
@@ -51,28 +51,28 @@ API 无处不在，在后台默默工作。
**天气预报 API** **天气预报 API**
它就像一个专门提供气象信息的窗口。你的天气应用向它发送坐标和密钥，它就回传一串 JSON 数据。 它就像一个专门提供气象信息的窗口。你的天气应用向它发送坐标和密钥，它就回传一串 JSON 数据。
* **一个简单的“请求”示例：** - **一个简单的“请求”示例：**
* **Endpoint:** `/current-weather` - **Endpoint:** `/current-weather`
* **Parameters:** `city=London` & `apiKey=your_access_key` - **Parameters:** `city=London` & `apiKey=your_access_key`
* **“响应”（回传的数据）：** - **“响应”（回传的数据）：**
```json `json
{ {
"city": "London", "city": "London",
"temperature": "15°C", "temperature": "15°C",
"condition": "Cloudy", "condition": "Cloudy",
"humidity": "70%" "humidity": "70%"
} }
``` `
应用拿到这些数据后，再把它们漂亮地展示在你的手机屏幕上。 应用拿到这些数据后，再把它们漂亮地展示在你的手机屏幕上。
**地图服务 API** **地图服务 API**
不管是外卖平台还是打车软件，它们本身并不生产地图。它们通过调用高德或 Google Maps 的 API，就能获得精准的路线规划和导航功能。 不管是外卖平台还是打车软件，它们本身并不生产地图。它们通过调用高德或 Google Maps 的 API，就能获得精准的路线规划和导航功能。
* **一个简单的“请求”示例：** - **一个简单的“请求”示例：**
* **Endpoint:** `/directions` - **Endpoint:** `/directions`
* **Parameters:** `origin=Eiffel Tower` & `destination=Louvre Museum` & `mode=driving` - **Parameters:** `origin=Eiffel Tower` & `destination=Louvre Museum` & `mode=driving`
* **“响应”（回传的数据）：** - **“响应”（回传的数据）：**
```json `json
{ {
"total_distance": "4.5 kilometers", "total_distance": "4.5 kilometers",
"estimated_time": "15 minutes", "estimated_time": "15 minutes",
@@ -82,8 +82,8 @@ API 无处不在，在后台默默工作。
"..." "..."
] ]
} }
``` `
通过这些数据，应用就能在地图上绘制路线并提供导航指令。 通过这些数据，应用就能在地图上绘制路线并提供导航指令。
**社交媒体登录 API** **社交媒体登录 API**
当你点击“使用 Google 登录"时，购物应用会问 Google API：“这个用户是谁？”Google 验证后告诉应用：“他是 John Doe”。这样，你不用输入密码就能安全登录。 当你点击“使用 Google 登录"时，购物应用会问 Google API：“这个用户是谁？”Google 验证后告诉应用：“他是 John Doe”。这样，你不用输入密码就能安全登录。
@@ -96,6 +96,7 @@ API 无处不在，在后台默默工作。
当你真正开始动手写代码时，会遇到一些技术名词。别担心，你不需要现在就记住所有细节，只需要看看它们在代码里是怎么“呼吸”的。 当你真正开始动手写代码时，会遇到一些技术名词。别担心，你不需要现在就记住所有细节，只需要看看它们在代码里是怎么“呼吸”的。
### 5.1 Python 中的 AI 调用 ### 5.1 Python 中的 AI 调用
在 Python 中调用 OpenAI 的 API 非常直观。你可以通过设置 `base_url` 来指定服务器地址。 在 Python 中调用 OpenAI 的 API 非常直观。你可以通过设置 `base_url` 来指定服务器地址。
```python ```python
@@ -119,37 +120,39 @@ print(response.choices[0].message["content"])
许多模型（如 DeepSeek）都兼容 OpenAI 的格式。你只需要更换 API 密钥和地址，就能无缝切换。 许多模型（如 DeepSeek）都兼容 OpenAI 的格式。你只需要更换 API 密钥和地址，就能无缝切换。
### 5.2 前端开发中的安全实践 ### 5.2 前端开发中的安全实践
如果你在做网页，切记不要在浏览器代码里直接写 API 密钥，否则会被人偷走。通常的做法是写一个**后端代理**，让服务器去替你完成调用。 如果你在做网页，切记不要在浏览器代码里直接写 API 密钥，否则会被人偷走。通常的做法是写一个**后端代理**，让服务器去替你完成调用。
```javascript ```javascript
// 后端 Node.js 示例 // 后端 Node.js 示例
const express = require("express"); const express = require('express')
const axios = require("axios"); const axios = require('axios')
const app = express(); const app = express()
app.use(express.json()); app.use(express.json())
app.post("/api/chat", async (req, res) => { app.post('/api/chat', async (req, res) => {
try { try {
const response = await axios.post( const response = await axios.post(
"https://api.openai.com/v1/chat/completions", 'https://api.openai.com/v1/chat/completions',
{ {
model: "gpt-3.5-turbo", model: 'gpt-3.5-turbo',
messages: [{ role: "user", content: req.body.message }] messages: [{ role: 'user', content: req.body.message }]
}, },
{ {
headers: { "Authorization": `Bearer ${process.env.OPENAI_API_KEY}` } headers: { Authorization: `Bearer ${process.env.OPENAI_API_KEY}` }
} }
); )
res.json({ reply: response.data.choices[0].message.content }); res.json({ reply: response.data.choices[0].message.content })
} catch (error) { } catch (error) {
res.status(500).json({ error: error.message }); res.status(500).json({ error: error.message })
} }
}); })
app.listen(3001, () => console.log("服务器运行在 3001 端口")); app.listen(3001, () => console.log('服务器运行在 3001 端口'))
``` ```
你可以使用 `curl` 命令来测试这个接口： 你可以使用 `curl` 命令来测试这个接口：
```bash ```bash
curl -X POST http://localhost:3001/api/chat \ curl -X POST http://localhost:3001/api/chat \
-H "Content-Type: application/json" \ -H "Content-Type: application/json" \
@@ -161,5 +164,7 @@ curl -X POST http://localhost:3001/api/chat \
API 是现代数字世界的基石。通过理解“请求与响应”这个简单的逻辑，你已经迈出了通往软件开发广阔世界的第一步。在接下来的 Z.ai 探索中，我们将亲手尝试这些调用，感受 AI API 的魅力。 API 是现代数字世界的基石。通过理解“请求与响应”这个简单的逻辑，你已经迈出了通往软件开发广阔世界的第一步。在接下来的 Z.ai 探索中，我们将亲手尝试这些调用，感受 AI API 的魅力。
--- ---
**参考资料** **参考资料**
* [Postman: What is an API?](https://www.postman.com/what-is-an-api/)
- [Postman: What is an API?](https://www.postman.com/what-is-an-api/)
docs/extra/extra3/extra3-ai-capability-starter-handbook.md
+2 -3266
View File
File diff suppressed because it is too large Load Diff
docs/extra/extra4/extra4-what-is-ai-ide-and-trae.md
-168
View File
@@ -1,168 +0,0 @@
# 扩展知识 4 - 什么是 AI IDE 和 Trae
在之前的学习阶段，我们使用 z.ai 搭建了最简单的 Web 程序和网页小游戏。但如果我们想要构建更复杂的应用——比如功能更完善的网站、桌面程序，甚至是手机应用——就必须在自己的电脑上使用专业的编程软件来编写代码。
最早的时候，只需要在一个简单的文本文件里写好程序，再用专门的语言处理器去读取并打包执行就够了。但随着代码量越来越大、项目结构越来越复杂，人工管理大量文件、手动编辑庞大的项目变得越来越困难。开发者因此迫切需要一种工具，能够高效管理和切换大量代码文件，支持多种编程语言的语法高亮，并可以快速定位和调试问题。于是，集成开发环境（IDE，Integrated Development Environment）就应运而生了。
你可以把 IDE 理解成一种专门用来“编辑、管理、运行和调试”各种应用源代码的程序。在真正打包发布之前，不同语言写出来的程序本质上只是特定格式的代码文件而已，你可以用普通文本编辑器打开它们，也可以用 IDE 打开。早期的计算机几乎完全通过终端来操作（只用键盘就能完成所有操作，几乎不需要鼠标），所以早期的 IDE 外观也非常“原始”——除非你额外安装插件来实现简单的交互式界面。
![](images/image1.png)![](images/image2.png)
终端界面（Terminal）
图片来源：https://en.wikipedia.org/wiki/File:Emacs-screenshot.png
一个非常知名、功能成熟的“内置 IDE”叫做 `Vim`。在很多服务器上，你都可以直接用它来编辑文件（服务器通常没有显示屏，只能通过键盘远程操作）。
![](images/image3.png)
现代 IDE 通常具有更加美观直观的图形界面，并提供更强大的编辑、运行和调试能力。一个典型的 IDE 通常包含以下核心组件：
* **源代码编辑器（Source Code Editor）**：专门用于编写和编辑代码的文本编辑器，一般具备语法高亮、代码自动补全、实时错误提示等功能。
* **构建与运行工具（编译器 / 解释器）**：IDE 内置编译器或解释器，可以将开发者写好的源代码转换成计算机可以执行的机器代码。
* **调试器（Debugger）**：用于测试和排查代码错误的工具。它支持逐行执行代码、查看变量状态、设置断点等，帮助开发者定位并修复程序中的问题。
除此之外，现代 IDE 往往还内置版本控制工具（如 Git）和项目管理工具等实用功能。当下最流行的 IDE 之一是微软出品的 **[Visual Studio Code (VS Code)](https://code.visualstudio.com/)**。它轻量、可扩展性极强，因此被广泛使用。当然，也有很多开发者推荐 JetBrains 家的专业 IDE，比如用于 Python 的 PyCharm、用于 C/C++ 的 CLion 等，它们对特定语言提供了更深入、更完整的支持。但从入门友好度和通用性角度出发，我们更推荐初学者优先选择 VS Code 作为主要开发工具。
![](images/image4.png)
# 现代 IDE：VS Code
Visual Studio Code（简称 VS Code）是由微软开发的一款免费、开源且功能强大的现代代码编辑器。自 2015 年发布以来，凭借优异的性能和灵活性，它迅速成为全球最受欢迎的开发工具之一。
VS Code 的核心理念之一是“一切皆插件”。不同编程语言可以用来编写不同类型的程序，而每种语言都有自己独特的语法高亮规则和导航能力（比如“跳转到定义”“查找引用”等）。要让一个 IDE 原生支持所有语言几乎是不可能的——从逻辑上讲，你会需要为每一种语言单独准备一个 IDE 才行。
VS Code 巧妙地通过“插件机制”解决了这一问题。比如，如果你要写 Python，就安装 Python 插件，它会提供 Python 专属的语法高亮、自动补全和代码导航功能；如果你要写 C/C++，则可以安装对应的 C/C++ 插件来获得相应支持。在不安装任何插件的情况下，VS Code 本质上只是一个“高级的文本文件管理器”；当你为某种语言安装了对应插件之后，它就会“变身”成该语言的理想开发工具。
![](images/image5.png)
除了编写代码以外，你甚至可以把 VS Code 当作编辑 Markdown 文档的工具来使用。
![](images/image6.png)
总之，你可以在 VS Code 的扩展市场中浏览和下载各类扩展，为不同类型的文件提供更好用的编辑体验，也可以根据需要搜索不同语言和调试工具的插件，尝试它们如何提升你的工作效率。
# 现代 AI IDE
上面介绍的都属于“传统意义上的现代 IDE”。但随着人工智能时代的到来，越来越多的代码开始由大语言模型来自动生成，这自然催生出一种新的开发工具形态——AI IDE，也就是可以利用大语言模型自动写代码的 IDE。
在最新版 VS Code 中，已经内置了一个大语言模型助手。你可以直接针对整个代码仓库、某个文件，甚至某个函数与模型对话。
你也可以像之前在 Web 端使用自动写代码工具一样，将需求以提示词的形式发给内置的编码 Agent，让它自动帮你实现所需功能、创建文件、修改代码、配置环境等。
典型的 AI IDE 一般具备以下核心能力：
* 智能代码生成与补全：在传统 IDE 中，我们通常是输入几个字符来补全变量名或函数名；在现代 AI IDE 中，你可以写几行伪代码或者简单说明需求，让 IDE 自动补全完整的逻辑，甚至根据指令直接生成一大段甚至整块代码。
* 代码理解与问答：IDE 能够理解并回答关于某段代码、某个文件，甚至整个工程目录结构的问题。
* 代码重构与优化：IDE 可以根据你的意图，重写或优化指定代码片段的实现逻辑。
* 自动生成测试：IDE 可以自动生成针对不同函数和模块的测试代码，方便你进行有针对性的测试。
* Agent 式任务执行：智能 Agent 可以自动生成、打包、安装、运行和修改代码，在很多任务上可以部分替代初级软件工程师的工作。
在最新版 VS Code 中，你可以点击右上角的侧边栏入口，打开 AI 功能区域，体验这些能力。
![](images/image7.png)
不过，VS Code 并不是 AI 能力最强的 IDE。对于需要大量 AI 辅助编码的场景，我们往往希望使用“更聪明、效率更高”的工具——好的 AI IDE 能显著节省写代码和改 Bug 的时间。下面我们会介绍几款目前比较流行的 AI IDE，重点讲解 Trae IDE。你可以根据个人喜好选择任意一款 AI IDE 使用。
由于 VS Code 是开源的（任何人都可以下载源码并自行编译），目前市面上绝大多数 AI IDE 都是在 VS Code 基础上二次开发而来。所以你不必担心要“学习很多种 IDE”——一旦你熟悉了 VS Code 的基本用法，迁移到这些 AI IDE 基本不需要重新学习。
如果要简单概括这些 AI IDE 之间的差异，主要集中在四个方面：价格；可使用的模型种类（部分高级模型在某些地区可能受限）；Agent 的能力（在协助写代码时的智能程度和执行能力）；以及运行速度与性能。
## Trae
![](images/image8.png)
Trae 是字节跳动推出的一款 AI 编程助手，支持 100 多种编程语言，并能集成到主流 IDE 中。它的功能包括：用自然语言生成代码、自动调试、把设计稿转换为 React/Vue 组件等。在 2025 年 8 月的更新之后，Trae 新增了智能依赖导入、重命名建议、任务清单管理等功能；SOLO 模式也开始支持后端代码生成和技术架构文档编辑。
## Cursor
Cursor 是 Anysphere 开发的一款 AI 代码编辑器，基于 VS Code 定制，重点优化了大规模代码仓库和多文件协同的场景。它支持 GPT-4o、Claude 3.7 等模型；2025 年推出的 Claude Max 模式可以处理数百万行代码级别的项目。专业版取消了请求次数限制，非常适合复杂的企业级项目。
目前，Cursor 可以说是“带前端界面的 AI IDE”中综合体验最好的一款之一，用户数量庞大，功能迭代频率也很高。它最大的缺点是价格较高——专业版大约需要每月 20 美元。
![](images/image9.png)
## Qoder
Qoder 是阿里巴巴推出的一款强调“透明协作”和“增强上下文工程能力”的 AI IDE。它通过 Action Flow 支持把任务拆解成多个步骤，并实时跟踪 AI 的执行过程；还支持多模型动态路由和任务状态机管理，非常适合在中大型项目中做架构治理和对遗留系统进行“反向工程”分析。
![](images/image10.png)
## CodeBuddy
CodeBuddy 是腾讯云推出的一款 AI 编程工具，强调对中文指令的支持以及企业级合规能力。它提供代码补全、批量代码审查和多模型切换等功能；其中的 Craft 智能体可以实现多文件代码生成和 API 集成。企业版支持私有化部署，并通过了三级等保认证，适合金融、医疗等对数据安全要求较高的行业。
![](images/image11.png)
## windsurf（已不推荐）
Windsurf 最初因其基于 Agent 的 AI 编程能力而受到关注。但由于 2024 年团队调整以及模型权限问题，它的稳定性大幅下降，目前已经不再推荐使用。尽管在前一年它还可以与 Cursor 分庭抗礼，但现在基本可以视为“被淘汰”的工具。
![](images/image12.png)
## VS Code + Cline
Cline 是 VS Code（Visual Studio Code）的一款 AI 编程 Agent 插件，可以通过配置不同的 API 端点来灵活切换所使用的大模型。Cline 支持多模态输入、MCP 工具扩展以及成本监控，所有操作都需要用户确认后才会执行。它非常适合用于快速验证想法，或与现有开发流程集成。基础功能是免费的，企业版则支持在私有环境中部署模型。
![](images/image13.png)
![](images/image14.png)
# 什么是 Trae
Trae 的全称可以理解为 “The Real AI Engineer”，是一款由字节跳动开发的自适应 AI 集成开发环境（IDE）。它是在流行的 VS Code 基础之上构建的，这意味着，如果你之前已经习惯了 VS Code，那么在使用 Trae 时，无论是界面布局还是基础操作都会感到非常熟悉、舒适。
Trae 的核心目标是成为开发者的“智能编程伙伴”。通过深度集成 AI 能力，它可以自动处理大量重复性工作，为你提供更直观、更高效的开发体验。它并不仅仅是一个“代码补全工具”，而是希望贯穿整个开发工作流，从创建项目、编写代码、调试、测试到部署都提供帮助。
## 安装 Trae
Trae 分为国际版和中国版。国际版需要能够访问海外网络，但可以使用 GPT-5、Claude 4 等最新的海外模型；中国版则主要支持国内最新的大模型，例如 GLM、Qwen、Kimi 等。
国际版下载地址：
https://www.trae.ai/
![](images/image15.png)
中国版下载地址：
https://www.trae.cn/
![](images/image16.png)
## Trae 界面简介
简单来说，Trae 和 VS Code 看起来几乎一模一样。
![](images/image17.png)
右侧的侧边栏就是 Copilot 交互窗口，也可以理解为 Agent 窗口。如果你暂时看不到它，可以点击 Trae 右上角的侧边栏图标将其打开。
![](images/image18.png)
打开侧边栏之后，你会看到一个 `Builder` 选项，这就是 Agent 模式。简单理解，它相当于 z.ai 的“本地版”，可以帮你操作本机环境，安装运行环境、打开网页等。
![](images/image19.png)
点击 “Builder” 后，你会看到 “Chat” 模式和 “Builder with MCP” 模式：
* **Chat 模式**：主要用于和当前文件夹里的代码对话，或者当作普通聊天模型来使用。（你可以通过左上角的 “File” 菜单打开一个文件夹，在这个文件夹中进行编辑操作。在这种情况下，Builder 创建或修改的文件都只会发生在这个文件夹内部。）
* **Builder with MCP 模式**：为 Agent 提供了更多可用工具（例如把语言模型和其他软件联通起来、查询天气等）。你可以简单理解为：MCP 能让语言模型更方便地调用各种外部工具。
![](images/image20.png)
在下面的区域，你还会看到模型选择选项，点击即可修改当前使用的大模型。在中国版中，你可以选择使用 Kimi k2 或 GLM 等国内模型；如果你使用的是国际版 Trae，还可以选择 ChatGPT 或 Claude 等海外模型。不过，由于国内大模型发展非常快，Kimi、Qwen、GLM 等在很多任务上的实际体验已经接近 Claude 3.5 或 3.7，对日常开发来说已经完全够用。
![](images/image21.png)
以上就是对 Trae 的一个简单介绍。接下来，我们可以回顾一下之前在 z.ai 中做过的操作，并尝试在 Trae 中做同样的事情。
## 使用 Trae 安装 Python 和前端环境
大多数情况下，我们的 Windows 笔记本电脑默认不会预装前端开发所需的 Node.js 环境，或用于后端 / 通用开发的 Python 环境。我们可以尝试直接在 Trae 的 Agent 模式中跟它对话，让它帮我们安装 Python 环境或 Node.js 环境。
![](images/image22.png)
## 📚 作业：用 Trae 写你的第一个程序
接下来，请尝试用 Trae 来完成你的第一个程序！你还记得之前的 AI 贪吃蛇游戏吗？把当时在 z.ai 中使用的那条提示词原封不动地输入到 Trae 的 Agent 模式中，看看会发生什么吧！
docs/extra/extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md
+90 -92
View File
@@ -10,13 +10,13 @@
# 本节课你将学到 # 本节课你将学到
* RAG的核心价值：深入理解它如何解决长上下文在成本、注意力、知识更新上的核心难题 - RAG的核心价值：深入理解它如何解决长上下文在成本、注意力、知识更新上的核心难题
* RAG的工作原理：通过具体案例看它如何完成从检索到生成的闭环 - RAG的工作原理：通过具体案例看它如何完成从检索到生成的闭环
* RAG的技术演进脉络：从基础的Naive RAG到Advanced RAG再到模块化的Modular RAG - RAG的技术演进脉络：从基础的Naive RAG到Advanced RAG再到模块化的Modular RAG
* RAG的模型选型建议：掌握Embedding、Rerank和LLM三大关键模型的评估与选择策略 - RAG的模型选型建议：掌握Embedding、Rerank和LLM三大关键模型的评估与选择策略
* RAG的企业级实践：学习从数据预处理到系统上线评估的全链路构建指南 - RAG的企业级实践：学习从数据预处理到系统上线评估的全链路构建指南
* RAG的效果评估与调优：了解核心评测指标、主流框架与持续优化的方法 - RAG的效果评估与调优：了解核心评测指标、主流框架与持续优化的方法
* RAG的前沿趋势：探索其与智能体、多模态等技术融合的未来方向 - RAG的前沿趋势：探索其与智能体、多模态等技术融合的未来方向
# 本节课你将收获 # 本节课你将收获
@@ -40,7 +40,7 @@
> 上下文（context）从意义上指模型在回答当前问题时所“参考”的背景信息与对话历史；从技术上则是指一次推理时输入给模型的 Token 序列（如 system/user 指令、历史消息、检索片段等）的总和。 > 上下文（context）从意义上指模型在回答当前问题时所“参考”的背景信息与对话历史；从技术上则是指一次推理时输入给模型的 Token 序列（如 system/user 指令、历史消息、检索片段等）的总和。
> >
> “上下文窗口”是这批输入内容的 **容量上限** ：模型一次最多只能“看到”这么多 Token。在当前主流的大模型架构（例如 Transformer）中，这些 Token 会在模型的每一层里彼此做注意力计算、反复参与运算，因此一旦窗口变长、Token 变多，计算量和成本都会成倍甚至指数级增加。 > “上下文窗口”是这批输入内容的 **容量上限** ：模型一次最多只能“看到”这么多 Token。在当前主流的大模型架构（例如 Transformer）中，这些 Token 会在模型的每一层里彼此做注意力计算、反复参与运算，因此一旦窗口变长、Token 变多，计算量和成本都会成倍甚至指数级增加。
>
3. 计算资源存在大量浪费：绝大多数任务仅需极少量与当前问题高度相关的信息，将全量文档塞入上下文，会造成严重的计算资源闲置与浪费，进而降低系统吞吐量，拖慢响应速度，最终影响用户体验。 3. 计算资源存在大量浪费：绝大多数任务仅需极少量与当前问题高度相关的信息，将全量文档塞入上下文，会造成严重的计算资源闲置与浪费，进而降低系统吞吐量，拖慢响应速度，最终影响用户体验。
4. **注意力与聚焦的问题** ： 4. **注意力与聚焦的问题** ：
大模型虽能 “覆盖” 超长上下文，却无法对每一段信息都实现同等质量的利用。当上下文长度达到一定阈值时，模型会出现明显的 “注意力偏差”： 大模型虽能 “覆盖” 超长上下文，却无法对每一段信息都实现同等质量的利用。当上下文长度达到一定阈值时，模型会出现明显的 “注意力偏差”：
@@ -83,9 +83,9 @@ RAG（Retrieval-Augmented Generation，检索增强生成）的核心思路是
在图中，这一阶段对应右上角紫色区域 “Indexing”。从 “Documents” 出发，经由 “Chunks / Vectors” 到 “embeddings” 的那一部分，就是在说明文档被切块并转换为向量、写入索引的过程。具体过程如下： 在图中，这一阶段对应右上角紫色区域 “Indexing”。从 “Documents” 出发，经由 “Chunks / Vectors” 到 “embeddings” 的那一部分，就是在说明文档被切块并转换为向量、写入索引的过程。具体过程如下：
* 文档被划分为若干个语义相对完整的 chunks，每个 chunk 可能对应一小段新闻、一段说明或一段分析。 - 文档被划分为若干个语义相对完整的 chunks，每个 chunk 可能对应一小段新闻、一段说明或一段分析。
* 每个 chunk 会通过 embedding 模型转换成高维向量，并存入向量索引中。 - 每个 chunk 会通过 embedding 模型转换成高维向量，并存入向量索引中。
* 这个索引支持后续基于相似度的检索，为回答问题提前准备好“可被查阅的知识库”。 - 这个索引支持后续基于相似度的检索，为回答问题提前准备好“可被查阅的知识库”。
2. **检索阶段 + 基于检索结果生成答案** 2. **检索阶段 + 基于检索结果生成答案**
@@ -166,9 +166,9 @@ RAG（Retrieval-Augmented Generation，检索增强生成）的核心思路是
简化示例（实际向量维度高得多，这里仅示意）： 简化示例（实际向量维度高得多，这里仅示意）：
* 文档A向量（关于苹果公司创立）：`[0.85, -0.23, 0.41, -0.56, 0.12, 0.78, ...]` - 文档A向量（关于苹果公司创立）：`[0.85, -0.23, 0.41, -0.56, 0.12, 0.78, ...]`
* 文档B向量（关于水果苹果）：`[-0.12, 0.95, -0.34, 0.67, -0.89, 0.05, ...]` - 文档B向量（关于水果苹果）：`[-0.12, 0.95, -0.34, 0.67, -0.89, 0.05, ...]`
* 文档C向量（关于iPhone发布）：`[0.79, -0.18, 0.52, -0.61, 0.23, 0.81, ...]` - 文档C向量（关于iPhone发布）：`[0.79, -0.18, 0.52, -0.61, 0.23, 0.81, ...]`
相关向量需存入向量数据库（如 Pinecone、Weaviate、FAISS）用于之后的检索召回工作。 相关向量需存入向量数据库（如 Pinecone、Weaviate、FAISS）用于之后的检索召回工作。
@@ -186,9 +186,9 @@ RAG（Retrieval-Augmented Generation，检索增强生成）的核心思路是
接下来系统将进行相似度检索 (Top-K, K=2)操作，计算该查询向量与知识库中所有文档向量的余弦相似度（一种衡量向量方向接近程度的指标）。结果如下： 接下来系统将进行相似度检索 (Top-K, K=2)操作，计算该查询向量与知识库中所有文档向量的余弦相似度（一种衡量向量方向接近程度的指标）。结果如下：
* 与文档A（公司创立）相似度：0.97（高度相关） - 与文档A（公司创立）相似度：0.97（高度相关）
* 与文档C（iPhone发布）相似度：0.88（相关，同属公司主题） - 与文档C（iPhone发布）相似度：0.88（相关，同属公司主题）
* 与文档B（水果营养）相似度：0.12（几乎不相关） - 与文档B（水果营养）相似度：0.12（几乎不相关）
> Top-K 是向量检索场景中常用的筛选策略，核心含义是 “从所有匹配结果中，按相似度从高到低排序后，选取排名前 K 个的结果”；而 K=2 则是对该策略的具体数值定义，即明确要求系统仅保留相似度排名前 2 的文档向量，过滤掉其余相似度更低的结果，以确保后续仅基于最相关的 2 个文档片段生成答案。 > Top-K 是向量检索场景中常用的筛选策略，核心含义是 “从所有匹配结果中，按相似度从高到低排序后，选取排名前 K 个的结果”；而 K=2 则是对该策略的具体数值定义，即明确要求系统仅保留相似度排名前 2 的文档向量，过滤掉其余相似度更低的结果，以确保后续仅基于最相关的 2 个文档片段生成答案。
@@ -220,9 +220,9 @@ LLM接收到上述结构化输入后，会遵循系统指令，将“参考信
接下来系统将进行相似度检索 (Top-K, K=2) 操作，计算该查询向量与知识库中所有文档向量的余弦相似度。结果如下： 接下来系统将进行相似度检索 (Top-K, K=2) 操作，计算该查询向量与知识库中所有文档向量的余弦相似度。结果如下：
* 与文档B（水果营养）相似度：0.95（高度相关） - 与文档B（水果营养）相似度：0.95（高度相关）
* 与文档C（iPhone发布）相似度：0.18（几乎不相关） - 与文档C（iPhone发布）相似度：0.18（几乎不相关）
* 与文档A（公司创立）相似度：0.15（几乎不相关） - 与文档A（公司创立）相似度：0.15（几乎不相关）
系统根据相似度分数从高到低，返回 Top‑2 的文档片段作为证据： 系统根据相似度分数从高到低，返回 Top‑2 的文档片段作为证据：
@@ -254,9 +254,9 @@ LLM接收到上述结构化输入后，其最终回复将类似：
接下来系统将进行相似度检索 (Top-K, K=2) 操作，计算余弦相似度。由于问题主题与知识库内容无关，整体相似度得分都很低。结果如下： 接下来系统将进行相似度检索 (Top-K, K=2) 操作，计算余弦相似度。由于问题主题与知识库内容无关，整体相似度得分都很低。结果如下：
* 与文档B（水果营养）相似度：0.18（极低） - 与文档B（水果营养）相似度：0.18（极低）
* 与文档C（iPhone发布）相似度：0.10（几乎不相关） - 与文档C（iPhone发布）相似度：0.10（几乎不相关）
* 与文档A（公司创立）相似度：0.08（几乎不相关） - 与文档A（公司创立）相似度：0.08（几乎不相关）
Top-K 仍会返回相似度排名前 K 个结果，但在该场景下，这些结果并不能提供有效证据。实际系统常会结合“最低相似度阈值”直接返回空召回，即没有任何召回的结果，参考信息为 0，以减少无关信息干扰。 Top-K 仍会返回相似度排名前 K 个结果，但在该场景下，这些结果并不能提供有效证据。实际系统常会结合“最低相似度阈值”直接返回空召回，即没有任何召回的结果，参考信息为 0，以减少无关信息干扰。
@@ -310,48 +310,46 @@ Naive RAG可以理解为基础的 RAG 形态，它在工程上非常直接，典
在检索前，重点是把“存什么”和“怎么问”处理好： 在检索前，重点是把“存什么”和“怎么问”处理好：
* 在索引端，从固定长度切分演进到语义感知分块与分层索引，例如按章节、小节、段落或句子边界进行切分，辅以滑动窗口和多粒度索引结构。 - 在索引端，从固定长度切分演进到语义感知分块与分层索引，例如按章节、小节、段落或句子边界进行切分，辅以滑动窗口和多粒度索引结构。
* 为每个文档块附加丰富的元数据，例如来源、时间、作者、主题、文档类型等，为后续的过滤和排序提供更多维度。 - 为每个文档块附加丰富的元数据，例如来源、时间、作者、主题、文档类型等，为后续的过滤和排序提供更多维度。
* 在查询端，对用户原始问题进行重写、扩展和拆分，例如通过 Query Rewrite、多路查询（Multi-Query）、子问题分解（Sub-Query）、Step-back Prompting 等方式，将含糊或口语化的问题转换为更利于检索理解的表达。 - 在查询端，对用户原始问题进行重写、扩展和拆分，例如通过 Query Rewrite、多路查询（Multi-Query）、子问题分解（Sub-Query）、Step-back Prompting 等方式，将含糊或口语化的问题转换为更利于检索理解的表达。
> 1. Query Rewrite（查询重写） > 1. Query Rewrite（查询重写）
> >
> 核心是将用户模糊、口语化或不规范的原始查询，转化为检索系统更易理解的标准化表述，补充关键信息、修正歧义。 > 核心是将用户模糊、口语化或不规范的原始查询，转化为检索系统更易理解的标准化表述，补充关键信息、修正歧义。
> >
> * 用户原始问题为 “咋查明天北京的天气啊”，会去除 “咋”“啊” 等口语化词汇，补充 “实时”“全天” 等关键限定，重写为 “查询北京市明日全天实时天气”； > - 用户原始问题为 “咋查明天北京的天气啊”，会去除 “咋”“啊” 等口语化词汇，补充 “实时”“全天” 等关键限定，重写为 “查询北京市明日全天实时天气”；
> * 用户原始问题为 “推荐好看的电影”，若结合用户历史行为发现其常看悬疑片，会补充 “2024 年高分”“悬疑题材” 等信息，重写为 “推荐 2024 年高分悬疑题材电影”。 > - 用户原始问题为 “推荐好看的电影”，若结合用户历史行为发现其常看悬疑片，会补充 “2024 年高分”“悬疑题材” 等信息，重写为 “推荐 2024 年高分悬疑题材电影”。
> >
> 2. Multi-Query（多路查询） > 2. Multi-Query（多路查询）
> >
> 基于原始问题生成多个 “语义相关但角度不同” 的查询语句，避免单一查询遗漏潜在结果，覆盖用户未明确的潜在需求。 > 基于原始问题生成多个 “语义相关但角度不同” 的查询语句，避免单一查询遗漏潜在结果，覆盖用户未明确的潜在需求。
> >
> * 用户原始问题为 “如何给刚满月的宝宝拍嗝”，会生成聚焦 “姿势” 的查询：“新生儿拍嗝的正确姿势”； > - 用户原始问题为 “如何给刚满月的宝宝拍嗝”，会生成聚焦 “姿势” 的查询：“新生儿拍嗝的正确姿势”；
> * 生成聚焦 “防吐奶” 的查询：“满月宝宝拍嗝避免吐奶的方法”； > - 生成聚焦 “防吐奶” 的查询：“满月宝宝拍嗝避免吐奶的方法”；
> * 生成聚焦 “月龄适配” 的查询：“婴儿拍嗝的步骤（0-1 个月）”； > - 生成聚焦 “月龄适配” 的查询：“婴儿拍嗝的步骤（0-1 个月）”；
> * 生成聚焦 “新手场景” 的查询：“新手爸妈给满月宝宝拍嗝技巧”。 > - 生成聚焦 “新手场景” 的查询：“新手爸妈给满月宝宝拍嗝技巧”。
> >
> 3. Sub-Query（子问题分解） > 3. Sub-Query（子问题分解）
> >
> 针对包含多个诉求的复合问题，拆分为独立、简单的子查询，让检索系统针对单一诉求精准匹配数据，避免信息混杂缺失。 > 针对包含多个诉求的复合问题，拆分为独立、简单的子查询，让检索系统针对单一诉求精准匹配数据，避免信息混杂缺失。
> >
> * 用户原始复合问题为 “北京到上海的高铁，明天有哪些班次？票价多少？需要坐多久？”，会拆解出聚焦 “班次” 的子查询：“北京市至上海市 明日高铁班次表”； > - 用户原始复合问题为 “北京到上海的高铁，明天有哪些班次？票价多少？需要坐多久？”，会拆解出聚焦 “班次” 的子查询：“北京市至上海市 明日高铁班次表”；
> * 拆解出聚焦 “票价” 的子查询：“北京到上海高铁 二等座 / 一等座票价”； > - 拆解出聚焦 “票价” 的子查询：“北京到上海高铁 二等座 / 一等座票价”；
> * 拆解出聚焦 “时长” 的子查询：“北京到上海高铁 行驶时长（最快 / 平均）”。 > - 拆解出聚焦 “时长” 的子查询：“北京到上海高铁 行驶时长（最快 / 平均）”。
> >
> 4. Step-back Prompting（回溯提示） > 4. Step-back Prompting（回溯提示）
> >
> 先生成 “比原始问题更宏观的上位问题”，再基于上位逻辑回推检索方向，解决原始问题因聚焦细节导致的理解偏差。 > 先生成 “比原始问题更宏观的上位问题”，再基于上位逻辑回推检索方向，解决原始问题因聚焦细节导致的理解偏差。
> >
> * 用户原始问题为 “为什么 2024 年某国产新能源汽车品牌的销量突然下降？”，第一步生成宏观上位问题：“影响新能源汽车品牌短期销量波动的核心因素有哪些？”（如产品迭代、竞品动作、政策变化、市场需求等）； > - 用户原始问题为 “为什么 2024 年某国产新能源汽车品牌的销量突然下降？”，第一步生成宏观上位问题：“影响新能源汽车品牌短期销量波动的核心因素有哪些？”（如产品迭代、竞品动作、政策变化、市场需求等）；
> * 第二步基于上位问题逻辑，生成具体检索方向：“2024 年某国产新能源品牌 产品更新情况”“2024 年新能源汽车市场 竞品定价策略”“2024 年新能源汽车补贴政策调整”。 > - 第二步基于上位问题逻辑，生成具体检索方向：“2024 年某国产新能源品牌 产品更新情况”“2024 年新能源汽车市场 竞品定价策略”“2024 年新能源汽车补贴政策调整”。
>
在检索后，重点是把“取回来的内容”治理好： 在检索后，重点是把“取回来的内容”治理好：
* 使用专门的 Rerank 模型或 LLM 对候选文档进行重新排序，确保最关键、最贴近问题的内容优先进入上下文。 - 使用专门的 Rerank 模型或 LLM 对候选文档进行重新排序，确保最关键、最贴近问题的内容优先进入上下文。
> Rerank 模型是信息检索流程中的关键组件，主要用于对 “召回阶段” 初步筛选出的候选结果进行二次排序 —— 它会借助更复杂的语义理解能力（常基于 Transformer 等深度学习架构），分析用户需求与候选结果的深层关联，修正初步排序中可能存在的语义偏差，最终让更贴合用户需求的结果排在更靠前的位置，提升用户获取有效信息的效率。 > Rerank 模型是信息检索流程中的关键组件，主要用于对 “召回阶段” 初步筛选出的候选结果进行二次排序 —— 它会借助更复杂的语义理解能力（常基于 Transformer 等深度学习架构），分析用户需求与候选结果的深层关联，修正初步排序中可能存在的语义偏差，最终让更贴合用户需求的结果排在更靠前的位置，提升用户获取有效信息的效率。
> - 对检索结果进行筛选、去重与压缩，去掉明显无关或高度重复的片段，缓解长上下文中部信息被忽略的问题。
* 对检索结果进行筛选、去重与压缩，去掉明显无关或高度重复的片段，缓解长上下文中部信息被忽略的问题。 - 在必要时，结合轻量的模型微调，使 LLM 更倾向于依据检索证据作答，并在回答中附带引用或出处信息。
* 在必要时，结合轻量的模型微调，使 LLM 更倾向于依据检索证据作答，并在回答中附带引用或出处信息。
总体来看，第二代检索增强生成技术其关注点不再局限于 “是否需要检索”“能否检索到信息” 这两个基础问题，而是进一步聚焦于三个更大的挑战：“能否精准定位到真正关键的段落内容”“传递给大模型的上下文是否简洁有序、具备清晰结构且易于高效利用”“当面临信息噪音、内容冲突或多资料源查找需求时，系统整体性能是否依然稳健可靠”。 总体来看，第二代检索增强生成技术其关注点不再局限于 “是否需要检索”“能否检索到信息” 这两个基础问题，而是进一步聚焦于三个更大的挑战：“能否精准定位到真正关键的段落内容”“传递给大模型的上下文是否简洁有序、具备清晰结构且易于高效利用”“当面临信息噪音、内容冲突或多资料源查找需求时，系统整体性能是否依然稳健可靠”。
@@ -452,8 +450,8 @@ MTEB为各类Embedding模型提供了一个统一、客观的评估框架。它
在选择 Embedding 模型时，我们可以用 MTEB 这样的 benchmark。而对于 Rerank 模型我们可以参考 Agentset 的 [Reranker Leaderboard](https://agentset.ai/rerankers)，该网站针对 RAG 场景下的重排能力做了系统测试。 在选择 Embedding 模型时，我们可以用 MTEB 这样的 benchmark。而对于 Rerank 模型我们可以参考 Agentset 的 [Reranker Leaderboard](https://agentset.ai/rerankers)，该网站针对 RAG 场景下的重排能力做了系统测试。
| Model Name↑ | ELO | nDCG@10 | Latency (ms) | Price / 1M | License | | Model Name↑ | ELO | nDCG@10 | Latency (ms) | Price / 1M | License |
| --------------------------------------------------------------------------------------------------- | ---- | ------- | ------------ | ---------- | ------------ | | ------------------------------------------------------------------------------------------------------ | ---- | ------- | ------------ | ---------- | ------------ |
| [BAAI/BGE Reranker v2 M3](https://agentset.ai/rerankers/baaibge-reranker-v2-m3) | 1314 | 0.201 | 2383 | $0.02 | Apache 2.0 | | [BAAI/BGE Reranker v2 M3](https://agentset.ai/rerankers/baaibge-reranker-v2-m3) | 1314 | 0.201 | 2383 | $0.02 | Apache 2.0 |
| [Cohere Rerank 3.5](https://agentset.ai/rerankers/cohere-rerank-35) | 1452 | 0.2 | 392 | $0.05 | Proprietary | | [Cohere Rerank 3.5](https://agentset.ai/rerankers/cohere-rerank-35) | 1452 | 0.2 | 392 | $0.05 | Proprietary |
| [Cohere Rerank 4 Fast](https://agentset.ai/rerankers/cohere-rerank-4-fast) | 1506 | 0.216 | 447 | $0.05 | Proprietary | | [Cohere Rerank 4 Fast](https://agentset.ai/rerankers/cohere-rerank-4-fast) | 1506 | 0.216 | 447 | $0.05 | Proprietary |
@@ -472,8 +470,8 @@ MTEB为各类Embedding模型提供了一个统一、客观的评估框架。它
在此基础上，基准测试还设计了两组互补性指标，用于对模型进行多维度综合评估： 在此基础上，基准测试还设计了两组互补性指标，用于对模型进行多维度综合评估：
* nDCG@5/10：聚焦排序精准度，重点衡量相关文档是否被合理置于结果前列，直接反映 “排得准” 的能力； - nDCG@5/10：聚焦排序精准度，重点衡量相关文档是否被合理置于结果前列，直接反映 “排得准” 的能力；
* Recall@5/10：侧重结果覆盖面，核心评估系统能否识别出所有与查询相关的文档，对应 “找得全” 的能力。 - Recall@5/10：侧重结果覆盖面，核心评估系统能否识别出所有与查询相关的文档，对应 “找得全” 的能力。
这两组指标相辅相成，共同构建起对 Rerank 模型的完整评估体系，确保评估结果更具全面性与参考价值。 这两组指标相辅相成，共同构建起对 Rerank 模型的完整评估体系，确保评估结果更具全面性与参考价值。
@@ -493,8 +491,8 @@ MTEB为各类Embedding模型提供了一个统一、客观的评估框架。它
以下是竞技场排名的示例（截止至 2025 年 12 月 15 日） 以下是竞技场排名的示例（截止至 2025 年 12 月 15 日）
| Rank | Model | Score | Votes | Organization | License | | Rank | Model | Score | Votes | Organization | License |
| ---- | ---------------------------------------------------------------------------------------- | ----- | ------ | ------------ | ----------- | | ---- | ------------------------------------------------------------------------------------------- | ----- | ------ | ------------ | ----------- |
| 1 | [gemini-3-pro](http://aistudio.google.com/app/prompts/new_chat?model=gemini-3-pro-preview) | 1492 | 15,871 | Google | Proprietary | | 1 | [gemini-3-pro](http://aistudio.google.com/app/prompts/new_chat?model=gemini-3-pro-preview) | 1492 | 15,871 | Google | Proprietary |
| 2 | [grok-4.1-thinking](https://x.ai/news/grok-4-1) | 1478 | 16,660 | xAI | Proprietary | | 2 | [grok-4.1-thinking](https://x.ai/news/grok-4-1) | 1478 | 16,660 | xAI | Proprietary |
| 3 | [claude-opus-4-5-20251101-thinking-32k](https://www.anthropic.com/news/claude-opus-4-5) | 1470 | 9,879 | Anthropic | Proprietary | | 3 | [claude-opus-4-5-20251101-thinking-32k](https://www.anthropic.com/news/claude-opus-4-5) | 1470 | 9,879 | Anthropic | Proprietary |
@@ -516,20 +514,20 @@ LMArena的独特价值在于其评估方式更贴近真实用户体验，而非
在实际工程实践中，通常不需要从零开始构建整个 RAG 系统。目前业界已有多个成熟的开源框架可供选择，它们在架构设计、模块集成和开发效率等方面各有特色。企业可以根据自身的技术储备和业务场景，选择合适的框架快速搭建系统。常见的框架类型包括： 在实际工程实践中，通常不需要从零开始构建整个 RAG 系统。目前业界已有多个成熟的开源框架可供选择，它们在架构设计、模块集成和开发效率等方面各有特色。企业可以根据自身的技术储备和业务场景，选择合适的框架快速搭建系统。常见的框架类型包括：
**低代码** **/可视化平台** **低代码** **/可视化平台**
* [Dify](https://dify.ai)：提供直观的可视化界面，支持快速搭建 RAG 应用，适合非技术团队或快速原型验证场景。内置多模型接入、工作流编排和 prompt 管理功能。 - [Dify](https://dify.ai)：提供直观的可视化界面，支持快速搭建 RAG 应用，适合非技术团队或快速原型验证场景。内置多模型接入、工作流编排和 prompt 管理功能。
* [Coze](https://www.coze.com/)：字节跳动推出的 AI Bot 开发平台，提供零代码的可视化搭建能力。特色在于与豆包等字节系大模型深度集成，支持插件市场、定时任务和多渠道发布（飞书、微信等），适合快速构建面向 C 端用户的对话应用或企业内部智能助手。 - [Coze](https://www.coze.com/)：字节跳动推出的 AI Bot 开发平台，提供零代码的可视化搭建能力。特色在于与豆包等字节系大模型深度集成，支持插件市场、定时任务和多渠道发布（飞书、微信等），适合快速构建面向 C 端用户的对话应用或企业内部智能助手。
* [n8n](https://n8n.io/)：一个开源的、基于节点的工作流自动化平台。它通过可视化的方式连接各类应用、API和数据源。在RAG场景中，可以利用n8n编排复杂的业务逻辑，将数据预处理、向量数据库操作、大模型调用以及后续动作（如发送邮件、更新工单）串联成一个自动化流程。 - [n8n](https://n8n.io/)：一个开源的、基于节点的工作流自动化平台。它通过可视化的方式连接各类应用、API和数据源。在RAG场景中，可以利用n8n编排复杂的业务逻辑，将数据预处理、向量数据库操作、大模型调用以及后续动作（如发送邮件、更新工单）串联成一个自动化流程。
* [RAGFlow](https://ragflow.io/)：专注于深度版面分析和知识抽取能力，对复杂文档（如多栏 PDF、表格密集型文档）的处理效果较好，适合文档结构复杂的企业知识库场景。 - [RAGFlow](https://ragflow.io/)：专注于深度版面分析和知识抽取能力，对复杂文档（如多栏 PDF、表格密集型文档）的处理效果较好，适合文档结构复杂的企业知识库场景。
* [FastGPT](https://fastgpt.io/en)：中国国内开源方案,集成了知识库管理、对话流程编排和应用发布功能，中文文档完善，适合快速部署中文 RAG 应用。 - [FastGPT](https://fastgpt.io/en)：中国国内开源方案,集成了知识库管理、对话流程编排和应用发布功能，中文文档完善，适合快速部署中文 RAG 应用。
**代码框架/开发库** **代码框架/开发库**
以下介绍的软件通常都有不同平台（前后端）语言的实现方式，你可以根据当前应用的语言选择下列对应软件的语言版本（例如 Python 或 Java 版）。 以下介绍的软件通常都有不同平台（前后端）语言的实现方式，你可以根据当前应用的语言选择下列对应软件的语言版本（例如 Python 或 Java 版）。
* [LlamaIndex](https://www.llamaindex.ai/)：专为 RAG 场景设计的 Python 框架，提供丰富的数据连接器（Connector）、索引结构和查询引擎,模块化程度高,适合需要深度定制检索策略或集成多种数据源的场景。 - [LlamaIndex](https://www.llamaindex.ai/)：专为 RAG 场景设计的 Python 框架，提供丰富的数据连接器（Connector）、索引结构和查询引擎,模块化程度高,适合需要深度定制检索策略或集成多种数据源的场景。
* [LangChain](https://www.langchain.com/)：通用 LLM 应用开发框架，RAG 只是其中一个应用方向。优势在于生态丰富、组件齐全，支持复杂的 Agent 和工作流编排，但学习曲线相对陡峭,适合构建复杂的多模块 LLM 应用。 - [LangChain](https://www.langchain.com/)：通用 LLM 应用开发框架，RAG 只是其中一个应用方向。优势在于生态丰富、组件齐全，支持复杂的 Agent 和工作流编排，但学习曲线相对陡峭,适合构建复杂的多模块 LLM 应用。
如果团队技术储备有限、追求快速上线，可优先考虑 Dify 、Coze 或 FastGPT 等低代码平台；如果需要深度定制检索框架、对接特殊数据源或优化性能细节，LlamaIndex 和 LangChain 提供了更大的灵活性。实际项目中，也可以采用"混合方案"：用低代码平台快速验证可行性，再用代码框架实现生产级部署和性能优化。此外，这些框架大多支持主流 Embedding、Rerank 和 LLM 模型的快速接入，可以基于前文提到的模型选型标准灵活组合最后使用的模型型号。 如果团队技术储备有限、追求快速上线，可优先考虑 Dify 、Coze 或 FastGPT 等低代码平台；如果需要深度定制检索框架、对接特殊数据源或优化性能细节，LlamaIndex 和 LangChain 提供了更大的灵活性。实际项目中，也可以采用"混合方案"：用低代码平台快速验证可行性，再用代码框架实现生产级部署和性能优化。此外，这些框架大多支持主流 Embedding、Rerank 和 LLM 模型的快速接入，可以基于前文提到的模型选型标准灵活组合最后使用的模型型号。
@@ -543,9 +541,9 @@ LMArena的独特价值在于其评估方式更贴近真实用户体验，而非
具体而言，该流程通常包含三个关键步骤： 具体而言，该流程通常包含三个关键步骤：
* 首先合成评测数据集，我们需要从知识库中采样文档，并指令 LLM 生成与之对应的、高质量的“问题-参考答案”对，再经过相关性、事实 groundedness 等过滤，形成基准测试集； - 首先合成评测数据集，我们需要从知识库中采样文档，并指令 LLM 生成与之对应的、高质量的“问题-参考答案”对，再经过相关性、事实 groundedness 等过滤，形成基准测试集；
* 其次，运行 RAG 系统并收集答案，让待评估的系统处理测试集中的每个问题，得到其生成的答案； - 其次，运行 RAG 系统并收集答案，让待评估的系统处理测试集中的每个问题，得到其生成的答案；
* 最后，进行自动化判分，调用另一个作为“裁判”的 LLM，将系统生成的答案与参考答案进行对比，从准确性、完整性等维度给出量化评分。 - 最后，进行自动化判分，调用另一个作为“裁判”的 LLM，将系统生成的答案与参考答案进行对比，从准确性、完整性等维度给出量化评分。
可以用一个简单的例子展示其过程： 可以用一个简单的例子展示其过程：
@@ -559,8 +557,8 @@ LMArena的独特价值在于其评估方式更贴近真实用户体验，而非
若你需要深入掌握具体细节（如指标的数学计算逻辑、框架的实操部署步骤、不同基准数据集的适用场景等），建议参考以下两篇 RAG 评测领域的论文： 若你需要深入掌握具体细节（如指标的数学计算逻辑、框架的实操部署步骤、不同基准数据集的适用场景等），建议参考以下两篇 RAG 评测领域的论文：
* [https://arxiv.org/pdf/2504.14891](https://arxiv.org/pdf/2504.14891)（《Retrieval Augmented Generation Evaluation in the Era of Large Language Models: A Comprehensive Survey》）：系统梳理了 LLM 时代 RAG 的内外部评测方法，涵盖组件级与系统级评估，还汇总了海量评测数据集与框架，并分析了当前研究趋势与挑战。 - [https://arxiv.org/pdf/2504.14891](https://arxiv.org/pdf/2504.14891)（《Retrieval Augmented Generation Evaluation in the Era of Large Language Models: A Comprehensive Survey》）：系统梳理了 LLM 时代 RAG 的内外部评测方法，涵盖组件级与系统级评估，还汇总了海量评测数据集与框架，并分析了当前研究趋势与挑战。
* [https://arxiv.org/pdf/2405.07437](https://arxiv.org/pdf/2405.07437)（《Evaluation of Retrieval-Augmented Generation: A Survey》）：提出了统一的 RAG 评测流程（Auepora），从 “评测目标、数据集、指标” 三维度拆解评测逻辑，同时对比了不同基准的优劣，为实践提供了清晰指引。 - [https://arxiv.org/pdf/2405.07437](https://arxiv.org/pdf/2405.07437)（《Evaluation of Retrieval-Augmented Generation: A Survey》）：提出了统一的 RAG 评测流程（Auepora），从 “评测目标、数据集、指标” 三维度拆解评测逻辑，同时对比了不同基准的优劣，为实践提供了清晰指引。
### 5.3.2 评测指标 ### 5.3.2 评测指标
@@ -574,9 +572,9 @@ RAG系统的评估本质上围绕两个核心问题：检索模块能否准确
首先是一组衡量召回基本质量的经典指标：Recall@K、Precision@K和F1。 首先是一组衡量召回基本质量的经典指标：Recall@K、Precision@K和F1。
* **Recall@K** 衡量在前K条检索结果中，相关文档被找回的比例。比如知识库中有5篇相关文档,前10条结果找回了3篇,则Recall@10为60%。这个指标告诉我们检索的"覆盖面"如何。 - **Recall@K** 衡量在前K条检索结果中，相关文档被找回的比例。比如知识库中有5篇相关文档,前10条结果找回了3篇,则Recall@10为60%。这个指标告诉我们检索的"覆盖面"如何。
* **Precision** **@K** 衡量前K条结果中真正相关文档的占比。同样是前10条结果,如果其中有3篇相关、7篇不相关,则Precision@10为30%。这个指标反映检索的"准确度"。 - **Precision** **@K** 衡量前K条结果中真正相关文档的占比。同样是前10条结果,如果其中有3篇相关、7篇不相关,则Precision@10为30%。这个指标反映检索的"准确度"。
* **F1** 则是Recall和Precision的调和平均,在两者间寻求平衡。 - **F1** 则是Recall和Precision的调和平均,在两者间寻求平衡。
这组指标适合快速发现召回阶段的基础问题,比如向量化模型是否有效、检索策略是否合理、Query改写是否到位等。如果Recall很低,说明相关文档根本没被找到;如果Precision很低,说明检索噪声太大。 这组指标适合快速发现召回阶段的基础问题,比如向量化模型是否有效、检索策略是否合理、Query改写是否到位等。如果Recall很低,说明相关文档根本没被找到;如果Precision很低,说明检索噪声太大。
@@ -584,9 +582,9 @@ RAG系统的评估本质上围绕两个核心问题：检索模块能否准确
找到相关文档只是第一步,更重要的是把最相关的文档排在前面。这就需要关注排序质量的指标：MRR、NDCG@K和MAP。 找到相关文档只是第一步,更重要的是把最相关的文档排在前面。这就需要关注排序质量的指标：MRR、NDCG@K和MAP。
* **MRR** **(** **Mean Reciprocal Rank** **)** 计算第一个相关文档出现位置的倒数均值。如果第一个相关文档出现在第3位,该条查询的RR就是1/3。MRR适合那些只需要一个正确答案的场景,比如问答系统。 - **MRR** **(** **Mean Reciprocal Rank** **)** 计算第一个相关文档出现位置的倒数均值。如果第一个相关文档出现在第3位,该条查询的RR就是1/3。MRR适合那些只需要一个正确答案的场景,比如问答系统。
* **NDCG@K(Normalized Discounted Cumulative Gain)** 考虑了相关性分级和位置衰减两个因素。它不仅关注文档是否相关,还关注相关程度;同时,越相关的文档排在越前面,得分越高。这使得NDCG成为衡量排序质量最全面的指标之一。 - **NDCG@K(Normalized Discounted Cumulative Gain)** 考虑了相关性分级和位置衰减两个因素。它不仅关注文档是否相关,还关注相关程度;同时,越相关的文档排在越前面,得分越高。这使得NDCG成为衡量排序质量最全面的指标之一。
* **MAP(Mean ** **Average Precision** **)** 综合考虑所有相关文档的位置,对整体排序质量更为敏感。 - **MAP(Mean ** **Average Precision** **)** 综合考虑所有相关文档的位置,对整体排序质量更为敏感。
在实际工程中,我们通常采用 Recall@K + MRR@K 的组合,既保证召回覆盖面又约束排序质量。举个例子,如果发现Recall@10达到80%但MRR@10只有0.3,说明相关文档虽然被找到了但都埋在后面,这时就需要优化重排序策略,比如引入交叉编码器或调整多路召回的权重分配。 在实际工程中,我们通常采用 Recall@K + MRR@K 的组合,既保证召回覆盖面又约束排序质量。举个例子,如果发现Recall@10达到80%但MRR@10只有0.3,说明相关文档虽然被找到了但都埋在后面,这时就需要优化重排序策略,比如引入交叉编码器或调整多路召回的权重分配。
@@ -598,11 +596,11 @@ RAG系统的评估本质上围绕两个核心问题：检索模块能否准确
**精确匹配与文本相似度** **精确匹配与文本相似度**
最直接的评估方式是 **EM(Exact Match)** ,要求生成答案与参考答案完全一致。这个指标适合答案唯一、形式固定的场景,比如"成立日期是什么时候?""总部在哪里?"这类事实性问答。但EM过于严格,同样正确的"2020年1月1日"和"2020-01-01"会被判为不匹配。 最直接的评估方式是 **EM(Exact Match)** ,要求生成答案与参考答案完全一致。这个指标适合答案唯一、形式固定的场景,比如"成立日期是什么时候?""总部在哪里?"这类事实性问答。但EM过于严格,同样正确的"2020年1月1日"和"2020-01-01"会被判为不匹配。
因此,更常用的是基于n-gram重叠的相似度指标： **ROUGE** **、** **BLEU** **、METEOR** 。它们通过计算生成内容与参考答案的词汇重叠程度来打分。其中,ROUGE-L关注最长公共子序列,对答案的流畅性更敏感;BLEU源自机器翻译领域,注重精确匹配;METEOR则加入了同义词和词干的考量。这些指标的优势是计算简单、易于理解,但也有明显局限——它们只看表面词汇匹配,对语义理解不够深入。 因此,更常用的是基于n-gram重叠的相似度指标： **ROUGE** **、** **BLEU** **、METEOR** 。它们通过计算生成内容与参考答案的词汇重叠程度来打分。其中,ROUGE-L关注最长公共子序列,对答案的流畅性更敏感;BLEU源自机器翻译领域,注重精确匹配;METEOR则加入了同义词和词干的考量。这些指标的优势是计算简单、易于理解,但也有明显局限——它们只看表面词汇匹配,对语义理解不够深入。
为了弥补这一不足,我们可以引入 **BertScore** 或直接的 **向量相似度** 。它们利用预训练模型的向量表示来计算语义相似度,更能容忍表述差异。比如"这款产品很受欢迎"和"该设备广受好评"在词汇上几乎没有重叠,但向量相似度会很高。这对于需要改写、总结、解释的生成任务特别有效。 为了弥补这一不足,我们可以引入 **BertScore** 或直接的 **向量相似度** 。它们利用预训练模型的向量表示来计算语义相似度,更能容忍表述差异。比如"这款产品很受欢迎"和"该设备广受好评"在词汇上几乎没有重叠,但向量相似度会很高。这对于需要改写、总结、解释的生成任务特别有效。
**事实忠实度与幻觉检测** **事实忠实度与幻觉检测**
@@ -618,10 +616,10 @@ RAG系统的评估本质上围绕两个核心问题：检索模块能否准确
具体做法是:将问题、检索文档、系统回答、参考答案一并输入一个独立的大模型(通常选择能力较强的模型如GPT-4或Claude),让它按多个维度进行综合评分： 具体做法是:将问题、检索文档、系统回答、参考答案一并输入一个独立的大模型(通常选择能力较强的模型如GPT-4或Claude),让它按多个维度进行综合评分：
* **问题相关性** ：答案是否真正回应了用户问题,有没有答非所问? - **问题相关性** ：答案是否真正回应了用户问题,有没有答非所问?
* **信息完整性** ：该涵盖的要点是否都说到了,有没有遗漏关键信息? - **信息完整性** ：该涵盖的要点是否都说到了,有没有遗漏关键信息?
* **事实忠实性** ：答案是否出现了检索文档中不存在的内容,有没有幻觉? - **事实忠实性** ：答案是否出现了检索文档中不存在的内容,有没有幻觉?
* **整体正确性** ：与参考答案相比,生成答案的质量如何? - **整体正确性** ：与参考答案相比,生成答案的质量如何?
LLM裁判的优势在于能进行更接近人类的整体性判断——它可以理解上下文、把握语义、识别逻辑,甚至能发现一些自动化指标捕捉不到的细微问题,比如语气不当、逻辑矛盾、表述含糊等。当然,裁判本身也需要精心设计prompt,并用人工标注样本进行校准,确保评分标准的一致性和可靠性。 LLM裁判的优势在于能进行更接近人类的整体性判断——它可以理解上下文、把握语义、识别逻辑,甚至能发现一些自动化指标捕捉不到的细微问题,比如语气不当、逻辑矛盾、表述含糊等。当然,裁判本身也需要精心设计prompt,并用人工标注样本进行校准,确保评分标准的一致性和可靠性。
@@ -631,9 +629,9 @@ LLM裁判的优势在于能进行更接近人类的整体性判断——它可
一个务实的建议是 **从精简组合开始,逐步完善** ： 一个务实的建议是 **从精简组合开始,逐步完善** ：
* **检索评估** ：采用 Recall@K + MRR@K 的核心组合,快速把握召回覆盖和排序质量 - **检索评估** ：采用 Recall@K + MRR@K 的核心组合,快速把握召回覆盖和排序质量
* **生成评估** ：根据任务特点,从 EM、ROUGE-L、BertScore 中选择一到两个作为基线 - **生成评估** ：根据任务特点,从 EM、ROUGE-L、BertScore 中选择一到两个作为基线
* **综合评估** ：引入 LLM裁判,重点关注相关性、完整性、忠实性三个维度 - **综合评估** ：引入 LLM裁判,重点关注相关性、完整性、忠实性三个维度
在此基础上,采用"评测→发现问题→调整策略→再评测"的循环迭代。比如,发现召回率不错但MRR很低,就重点优化重排序;发现幻觉率偏高,就加强对检索文档的忠实度约束;发现某些类型的问题回答质量不好,就针对性地补充细分指标。 在此基础上,采用"评测→发现问题→调整策略→再评测"的循环迭代。比如,发现召回率不错但MRR很低,就重点优化重排序;发现幻觉率偏高,就加强对检索文档的忠实度约束;发现某些类型的问题回答质量不好,就针对性地补充细分指标。
@@ -649,13 +647,13 @@ LLM裁判的优势在于能进行更接近人类的整体性判断——它可
**研究型框架**主要服务于学术研究和前沿探索,特点是评测维度细致、方法创新性强。代表性的如FiD-Light和Diversity Reranker,它们专注于检索阶段的细粒度评估,前者关注召回的延迟性(Latency),后者强调结果的多样性(Diversity)。这类框架通常会深入到RAG系统的某个特定环节,提供精细化的诊断能力。 **研究型框架**主要服务于学术研究和前沿探索,特点是评测维度细致、方法创新性强。代表性的如FiD-Light和Diversity Reranker,它们专注于检索阶段的细粒度评估,前者关注召回的延迟性(Latency),后者强调结果的多样性(Diversity)。这类框架通常会深入到RAG系统的某个特定环节,提供精细化的诊断能力。
**基准测试****框架**则提供了标准化的测试集和评测流程,用于横向比较不同RAG系统的性能。这类框架数量最多、影响最广。例如： **基准测试\*\***框架\*\*则提供了标准化的测试集和评测流程,用于横向比较不同RAG系统的性能。这类框架数量最多、影响最广。例如：
* **RAGAS** （2023.09）是最早的综合性RAG评测框架之一,采用LLM-as-a-Judge模式,同时评估检索和生成两个环节 - **RAGAS** （2023.09）是最早的综合性RAG评测框架之一,采用LLM-as-a-Judge模式,同时评估检索和生成两个环节
* **ARES** （2023.11）引入了分类器辅助的评测方法,结合LLM判断和传统分类器来评估Context相关性和Answer相关性 - **ARES** （2023.11）引入了分类器辅助的评测方法,结合LLM判断和传统分类器来评估Context相关性和Answer相关性
* **RGB** （2023.12）专注于生成阶段的评估,提出了信息整合(Info Integration)、噪声鲁棒性(NoiseRobust)、负样本拒绝(NegRejection)、反事实鲁棒性(Counterfact)等细分维度 - **RGB** （2023.12）专注于生成阶段的评估,提出了信息整合(Info Integration)、噪声鲁棒性(NoiseRobust)、负样本拒绝(NegRejection)、反事实鲁棒性(Counterfact)等细分维度
* **MultiHop-RAG** （2024.01）针对多跳推理场景,重点评估检索的相关性(Retrieval C)和回答的正确性(Response C),使用MAP、MRR、Hit@K等指标 - **MultiHop-RAG** （2024.01）针对多跳推理场景,重点评估检索的相关性(Retrieval C)和回答的正确性(Response C),使用MAP、MRR、Hit@K等指标
* **CRUD-RAG** （2024.02）模拟真实的知识管理场景,评估系统在Create、Read、Update、Delete四种操作下的表现,引入了RAGQuerEval评分体系 - **CRUD-RAG** （2024.02）模拟真实的知识管理场景,评估系统在Create、Read、Update、Delete四种操作下的表现,引入了RAGQuerEval评分体系
进入2024年后,评测框架呈现出明显的专业化和细分化趋势。医疗领域有MedRAG,法律领域有LegalBench-RAG,金融领域有相关的domain-specific框架。这些领域框架不仅提供了专业数据集,还针对行业特点设计了定制化的评测指标,比如医疗场景特别关注准确性(Accuracy),法律场景强调文档级精确度(Doc-level Precision)和引用相关性(Citation Relevance)。 进入2024年后,评测框架呈现出明显的专业化和细分化趋势。医疗领域有MedRAG,法律领域有LegalBench-RAG,金融领域有相关的domain-specific框架。这些领域框架不仅提供了专业数据集,还针对行业特点设计了定制化的评测指标,比如医疗场景特别关注准确性(Accuracy),法律场景强调文档级精确度(Doc-level Precision)和引用相关性(Citation Relevance)。
@@ -663,9 +661,9 @@ LLM裁判的优势在于能进行更接近人类的整体性判断——它可
上述我们介绍了多种不同的 RAG 评测框架，但在具体实战中该如何选择？不妨先选取 GitHub 星标数量较多的几款进行初步测试；而当企业面临丰富的框架选择、需要落地决策时，可从以下几方面着手。 上述我们介绍了多种不同的 RAG 评测框架，但在具体实战中该如何选择？不妨先选取 GitHub 星标数量较多的几款进行初步测试；而当企业面临丰富的框架选择、需要落地决策时，可从以下几方面着手。
* 快速上手需求：若需快速搭建基线评测，可选择 RAGAS、RAGEval 等综合性框架，它们能提供开箱即用的完整流程，若需深入诊断某一环节问题，则需选用针对性框架 ：例如检索效果不佳时可用 MultiHop-RAG，幻觉问题突出时则可采用 CoURAGE 或 RAG Unfairness。 - 快速上手需求：若需快速搭建基线评测，可选择 RAGAS、RAGEval 等综合性框架，它们能提供开箱即用的完整流程，若需深入诊断某一环节问题，则需选用针对性框架 ：例如检索效果不佳时可用 MultiHop-RAG，幻觉问题突出时则可采用 CoURAGE 或 RAG Unfairness。
* 结合行业进行选择：若应用于医疗、法律、金融等专业领域，应优先选择适配该领域的框架，这类框架往往内置专业术语处理、合规性检查等关键能力，通用框架虽功能全面，但在专业场景中易出现 “水土不服” 的情况。 - 结合行业进行选择：若应用于医疗、法律、金融等专业领域，应优先选择适配该领域的框架，这类框架往往内置专业术语处理、合规性检查等关键能力，通用框架虽功能全面，但在专业场景中易出现 “水土不服” 的情况。
* 根据集成成本选择：像 LangChain Benchmarks、TruEra RAG Triad 等框架已与主流开发框架深度集成，能快速接入现有系统，而部分学术框架虽技术方法先进，却需额外投入工程适配工作；最后需关注持续维护情况，应优先选择社区活跃、文档完善且持续更新的框架，避开已停止维护的项目，具体可参考 GitHub 星标数量、更新频率、Issue 响应速度等指标。 - 根据集成成本选择：像 LangChain Benchmarks、TruEra RAG Triad 等框架已与主流开发框架深度集成，能快速接入现有系统，而部分学术框架虽技术方法先进，却需额外投入工程适配工作；最后需关注持续维护情况，应优先选择社区活跃、文档完善且持续更新的框架，避开已停止维护的项目，具体可参考 GitHub 星标数量、更新频率、Issue 响应速度等指标。
除此之外，在社区中还公认推荐了一批工具，部分框架已在上述内容中提到：Ragas 提供了丰富指标且不绑定特定框架；Continuous Eval 以轻量和低成本为特点，支持构建具备数学保证的评估流水线；TruLens‑Eval 与 LangChain、Llama‑Index 等主流框架集成良好，并提供可视化分析；而 Llama‑Index 自身生态中也集成了评估与合成数据生成功能，便于对其构建的应用进行闭环测试。还有 Phoenix、DeepEval、LangSmith 和 OpenAI Evals 等工具也在持续迭代中，你可综合自身需求和对应工具的口碑进一步选用。 除此之外，在社区中还公认推荐了一批工具，部分框架已在上述内容中提到：Ragas 提供了丰富指标且不绑定特定框架；Continuous Eval 以轻量和低成本为特点，支持构建具备数学保证的评估流水线；TruLens‑Eval 与 LangChain、Llama‑Index 等主流框架集成良好，并提供可视化分析；而 Llama‑Index 自身生态中也集成了评估与合成数据生成功能，便于对其构建的应用进行闭环测试。还有 Phoenix、DeepEval、LangSmith 和 OpenAI Evals 等工具也在持续迭代中，你可综合自身需求和对应工具的口碑进一步选用。
@@ -677,9 +675,9 @@ LLM裁判的优势在于能进行更接近人类的整体性判断——它可
对于大多数企业而言，由于业务场景存在独特性，最终往往需要构建自己的评测数据集。 对于大多数企业而言，由于业务场景存在独特性，最终往往需要构建自己的评测数据集。
* 构建过程可以从业务日志中提取真实用户问题入手，并依据类型、频率和难度进行分层采样，以保证数据的代表性。对于简单问题可由领域专家直接标注,复杂问题则可先用高质量LLM生成候选答案,再由专家审核修改,这种"机器生成+人工校准"的方式能显著降低标注成本。 - 构建过程可以从业务日志中提取真实用户问题入手，并依据类型、频率和难度进行分层采样，以保证数据的代表性。对于简单问题可由领域专家直接标注,复杂问题则可先用高质量LLM生成候选答案,再由专家审核修改,这种"机器生成+人工校准"的方式能显著降低标注成本。
* 除答案本身,标注相关文档、答案类型、难度等级等元信息,为后续细分析提供支持。建立标注规范,进行多人交叉验证,计算标注一致性(如Kappa系数),确保数据质量。 - 除答案本身,标注相关文档、答案类型、难度等级等元信息,为后续细分析提供支持。建立标注规范,进行多人交叉验证,计算标注一致性(如Kappa系数),确保数据质量。
* 定期从线上反馈中补充新的测试用例,尤其是系统回答不好的问题,让评测数据与系统能力同步演进。这种持续迭代的机制能让评测基准始终保持对业务场景的敏感度和有效性。 - 定期从线上反馈中补充新的测试用例,尤其是系统回答不好的问题,让评测数据与系统能力同步演进。这种持续迭代的机制能让评测基准始终保持对业务场景的敏感度和有效性。
当然，如果团队资源有限或希望快速建立基线，参考业界成熟的公开评测基准也是一个可行的起点。截至2025年，已有诸多涵盖通用领域和垂直行业的基准可供选择（见图表）。 当然，如果团队资源有限或希望快速建立基线，参考业界成熟的公开评测基准也是一个可行的起点。截至2025年，已有诸多涵盖通用领域和垂直行业的基准可供选择（见图表）。
@@ -846,9 +844,9 @@ RAG技术已从最初的检索增强生成工具，发展为构建智能体认
Agentic RAG实现上述复杂任务处理的关键，在于其建立了一个多层次的主动循环工作机制。 面对复杂查询，智能体首先分析问题本质，将其拆解为子问题，并为每个子问题设计精准的检索策略。获得初步结果后，智能体进行评估与反思，判断信息的完整性和相关性，识别知识缺口，并动态生成更精确的新查询。这种迭代过程常包含多跳检索，即基于前一轮结果发现新的检索方向，形成类似人类研究者的知识探索链条。然而，要支撑这种持续的、迭代的智能行为，尤其是实现长期交互中的个性化和知识积累，仅依赖单次会话的短期上下文（短期记忆）是远远不够的。这引出了对长期、结构化记忆能力的需求。 Agentic RAG实现上述复杂任务处理的关键，在于其建立了一个多层次的主动循环工作机制。 面对复杂查询，智能体首先分析问题本质，将其拆解为子问题，并为每个子问题设计精准的检索策略。获得初步结果后，智能体进行评估与反思，判断信息的完整性和相关性，识别知识缺口，并动态生成更精确的新查询。这种迭代过程常包含多跳检索，即基于前一轮结果发现新的检索方向，形成类似人类研究者的知识探索链条。然而，要支撑这种持续的、迭代的智能行为，尤其是实现长期交互中的个性化和知识积累，仅依赖单次会话的短期上下文（短期记忆）是远远不够的。这引出了对长期、结构化记忆能力的需求。
正是为了满足这一需求，RAG被赋予了作为智能体长期记忆系统的角色，构建了一个完整的外部记忆架构。 该系统与负责维护当前会话上下文的短期记忆形成互补。该长期记忆系统的核心运作依赖于三项关键机制： 正是为了满足这一需求，RAG被赋予了作为智能体长期记忆系统的角色，构建了一个完整的外部记忆架构。 该系统与负责维护当前会话上下文的短期记忆形成互补。该长期记忆系统的核心运作依赖于三项关键机制：
第一，结构化索引能力：使智能体能够为海量非结构化数据建立多维索引体系（如按时间、主题或实体关系），支持多角度高效检索，模拟人脑通过不同线索回忆信息的方式。 第一，结构化索引能力：使智能体能够为海量非结构化数据建立多维索引体系（如按时间、主题或实体关系），支持多角度高效检索，模拟人脑通过不同线索回忆信息的方式。
第二，智能遗忘机制：通过价值评估算法，系统对使用频率低、相关性弱或过时的信息进行权重衰减或选择性剔除，维持记忆系统的精炼高效，防止信息过载。 第二，智能遗忘机制：通过价值评估算法，系统对使用频率低、相关性弱或过时的信息进行权重衰减或选择性剔除，维持记忆系统的精炼高效，防止信息过载。
第三，知识巩固过程：系统将零散对话和交互经验提炼为结构化知识，利用实体识别、关系抽取和语义聚类等技术，将碎片信息整合连接成知识图谱，完成从短期经验到长期知识的转化与沉淀。 第三，知识巩固过程：系统将零散对话和交互经验提炼为结构化知识，利用实体识别、关系抽取和语义聚类等技术，将碎片信息整合连接成知识图谱，完成从短期经验到长期知识的转化与沉淀。
这种由RAG构建的外部记忆系统，不仅极大地扩展了智能体的认知边界，更重要的是赋予了其持续学习和知识进化的能力。 它使得智能体能够在长期互动中积累经验，形成个性化的处理模式和领域专业知识体系，从而为执行更复杂、更持久的任务提供了坚实的基础。 这种由RAG构建的外部记忆系统，不仅极大地扩展了智能体的认知边界，更重要的是赋予了其持续学习和知识进化的能力。 它使得智能体能够在长期互动中积累经验，形成个性化的处理模式和领域专业知识体系，从而为执行更复杂、更持久的任务提供了坚实的基础。
docs/extra/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md
+4 -3
View File
@@ -17,7 +17,7 @@
如果手动部署，一个项目往往需要好几个步骤，每一步都可能踩坑。常见关键步骤包括： 如果手动部署，一个项目往往需要好几个步骤，每一步都可能踩坑。常见关键步骤包括：
1. **服务器准备**：你需要先购买云服务器（比如阿里云、腾讯云、或 AWS EC2），选择服务器所在地区（如上海、新加坡）、配置（CPU、内存、磁盘大小等），还要学会如何远程连接服务器（例如通过 SSH 工具登录）。 1. **服务器准备**：你需要先购买云服务器（比如阿里云、腾讯云、或 AWS EC2），选择服务器所在地区（如上海、新加坡）、配置（CPU、内存、磁盘大小等），还要学会如何远程连接服务器（例如通过 SSH 工具登录）。
![](images/image2.png) ![](images/image2.png)
2. **环境配置**：Web 应用需要在特定“环境”中才能运行——例如运行 Node.js 项目必须先安装 Node.js；运行 Python 项目必须安装 Python 以及对应的第三方库。如果环境版本不匹配，程序就可能报错、无法启动。 2. **环境配置**：Web 应用需要在特定“环境”中才能运行——例如运行 Node.js 项目必须先安装 Node.js；运行 Python 项目必须安装 Python 以及对应的第三方库。如果环境版本不匹配，程序就可能报错、无法启动。
3. **上传资源**：你需要把本地的代码和资源上传到服务器上，常用的方法包括 FTP 或 Git。如果项目体积比较大（比如包含视频文件），中途一旦断线，有时需要重新上传。 3. **上传资源**：你需要把本地的代码和资源上传到服务器上，常用的方法包括 FTP 或 Git。如果项目体积比较大（比如包含视频文件），中途一旦断线，有时需要重新上传。
@@ -65,8 +65,8 @@
1. **GitHub** 1. **GitHub**
可以连接到你的 GitHub 账号。绑定之后，就可以直接从 GitHub 仓库里选择项目部署（GitHub 是目前全球最大的代码托管平台）。 可以连接到你的 GitHub 账号。绑定之后，就可以直接从 GitHub 仓库里选择项目部署（GitHub 是目前全球最大的代码托管平台）。
2. **Template（模板）** 2. **Template（模板）**
可以基于模板来部署服务。Zeabur 内置了很多预设项目模板（例如 Dify、n8n 等），你可以基于这些模板快速创建并部署应用。 可以基于模板来部署服务。Zeabur 内置了很多预设项目模板（例如 Dify、n8n 等），你可以基于这些模板快速创建并部署应用。
![](images/image9.png) ![](images/image9.png)
3. **Databases（数据库）** 3. **Databases（数据库）**
用于部署数据库服务，比如 MySQL、MongoDB 等常见数据库。 用于部署数据库服务，比如 MySQL、MongoDB 等常见数据库。
![](images/image10.png) ![](images/image10.png)
@@ -75,6 +75,7 @@
![](images/image11.png) ![](images/image11.png)
![](images/image12.png) ![](images/image12.png)
5. **Local Project（本地项目）** 5. **Local Project（本地项目）**
上传一个本地文件夹，Zeabur 会自动识别其中的启动脚本。这适合将你已经在本地开发好的项目快速部署到 Zeabur 上。 上传一个本地文件夹，Zeabur 会自动识别其中的启动脚本。这适合将你已经在本地开发好的项目快速部署到 Zeabur 上。
![](images/image13.png) ![](images/image13.png)
docs/extra/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md
+13 -13
View File
@@ -30,16 +30,16 @@ CLI 天生适合文本命令操作，在一小部分极客（追求极致的编
为了更直观地对比，我们可以简单看看 Claude Code 和某款 AI IDE Agent 的差异（这里以 Cursor 为例）： 为了更直观地对比，我们可以简单看看 Claude Code 和某款 AI IDE Agent 的差异（这里以 Cursor 为例）：
| 功能特性 | Claude Code | Cursor | 更优者 | | 功能特性 | Claude Code | Cursor | 更优者 |
| ------------------------ | -------------------- | ----------------- | ----------- | | ----------------- | ------------- | --------------- | ----------- |
| 自动任务执行 | ✅ 非常强 | ❌ 能力有限 | Claude Code | | 自动任务执行 | ✅ 非常强 | ❌ 能力有限 | Claude Code |
| IDE 集成 | ❌ 仅命令行 | ✅ 原生 VS Code | Cursor | | IDE 集成 | ❌ 仅命令行 | ✅ 原生 VS Code | Cursor |
| 实时代码补全 | ❌ 无 | ✅ 体验极佳 | Cursor | | 实时代码补全 | ❌ 无 | ✅ 体验极佳 | Cursor |
| 多文件操作 | ✅ 非常强 | ⚠️ 还不错 | Claude Code | | 多文件操作 | ✅ 非常强 | ⚠️ 还不错 | Claude Code |
| GitHub 一体化操作 | ✅ 可直接提交 | ⚠️ 需要手动操作 | Claude Code | | GitHub 一体化操作 | ✅ 可直接提交 | ⚠️ 需要手动操作 | Claude Code |
| 学习成本 | ⚠️ 中等 | ✅ 上手简单 | Cursor | | 学习成本 | ⚠️ 中等 | ✅ 上手简单 | Cursor |
| 上下文长度 | ✅ 非常长 | ⚠️ 较好 | Claude Code | | 上下文长度 | ✅ 非常长 | ⚠️ 较好 | Claude Code |
| 调试辅助 | ✅ 自动化 | ⚠️ 较多需手动 | Claude Code | | 调试辅助 | ✅ 自动化 | ⚠️ 较多需手动 | Claude Code |
表格来源：https://northflank.com/blog/claude-code-vs-cursor-comparison 表格来源：https://northflank.com/blog/claude-code-vs-cursor-comparison
@@ -152,7 +152,7 @@ Based on my environment variable settings:
setx ANTHROPIC_AUTH_TOKEN your_zai_api_key setx ANTHROPIC_AUTH_TOKEN your_zai_api_key
setx ANTHROPIC_BASE_URL https://api.z.ai/api/anthropic setx ANTHROPIC_BASE_URL https://api.z.ai/api/anthropic
and my key(Replace it with your own key): and my key(Replace it with your own key):
681fea485851d29060cc.13gfaendggaFOhb 681fea485851d29060cc.13gfaendggaFOhb
please help me configure and start Claude Code please help me configure and start Claude Code
@@ -397,7 +397,7 @@ npm i -g @openai/codex
接下来，我们需要把获取到的 Key 填入下面的提示词中，并把整段提示词交给 Trae，让它帮你完成整个配置过程： 接下来，我们需要把获取到的 Key 填入下面的提示词中，并把整段提示词交给 Trae，让它帮你完成整个配置过程：
```Bash ````Bash
My API key is: [Paste your obtained sk-xxxxx key here] My API key is: [Paste your obtained sk-xxxxx key here]
Please help me complete the following configuration tasks: Please help me complete the following configuration tasks:
@@ -440,7 +440,7 @@ Variable value: The key I gave you
The full path of the configuration file The full path of the configuration file
Whether the environment variable was set successfully Whether the environment variable was set successfully
I can use the command `codex --profile myrelay` to run it I can use the command `codex --profile myrelay` to run it
``` ````
配置完成后，你就可以通过 `codex --profile myrelay` 启动使用转发 API 的 Codex 了。之后的使用方式与 Claude Code 类似：只需要在对话框中随时输入你的想法和需求即可。 配置完成后，你就可以通过 `codex --profile myrelay` 启动使用转发 API 的 Codex 了。之后的使用方式与 Claude Code 类似：只需要在对话框中随时输入你的想法和需求即可。
docs/guide/introduction.md
+79
View File
@@ -0,0 +1,79 @@
# 项目介绍
2025年，被很多人视为AI编程的元年。越来越多的人开始用AI写代码，但往往做出来的还停留在玩具层面——不知道如何用Vibe Coding组织开发流程，不知道该选哪些工具，更不清楚从原型到上线中间还差哪些关键步骤。
我们采用循序渐进的**三阶段实战路径**：第零阶段通过小游戏快速上手AI编程，第一阶段掌握Vibe Coding工作方式并完成Web应用原型，第二阶段学习全栈开发与部署上线，第三阶段构建跨平台复杂应用。
每个阶段都配有完整项目实战，让你在真实挑战中从玩具走向产品，最终具备**将任何想法落地为可用应用**的能力。
我们相信，掌握Vibe Coding并配合系统化训练，你一个人就能成为**集前后端开发、AI能力集成、产品设计于一身的全能开发者**。
本项目主要面向三类学习者：
- **新手（普通人 / 产品与运营侧）**：帮助非技术背景角色和入门学习者听懂关键概念，完成第一个 AI 小工具或产品原型。
- **初中级开发者（有一定基础的学生和开发者）**：系统掌握 vibe coding 与原生 AI 应用开发。
- **高级开发者（公司与初创、开源与独立开发者）**：支持团队和个人快速搭建、验证与迭代原生 AI 应用。
## 📖 内容导航
### 总附录
[AI 能力词典：常见 AI 核心概念与名词、场景解释](/appendix/ai-capability-dictionary)
### 零、幼儿园
| 章节 | 关键内容 | 状态 |
| :----------------------------------------------------------------------------- | :------------------------------------- | :--- |
| [前言：学习地图](/stage-0/0.1-learning-map/) | 整体学习路径导览 | ✅ |
| [初级一：AI 时代，会说话就会编程](/stage-0/0.2-ai-capabilities-through-games/) | 通过贪吃蛇等案例初步感受 AI 编程的能力 | ✅ |
### 一、AI 产品经理
| 章节 | 关键内容 | 状态 |
| :---------------------------------------------------------------------- | :------------------------------------------------ | :--- |
| [初级二：认识 AI IDE 工具](/stage-1/1.1-introduction-to-ai-ide/) | 学会使用 IDE，掌握界面结构和高效提示方式 | ✅ |
| [初级三：动手做出原型](/stage-1/1.2-building-prototype/) | 从产品分析拆解，到多页面产品原型实现的完整闭环 | ✅ |
| [初级四：给原型加上 AI 能力](/stage-1/1.3-integrating-ai-capabilities/) | 理解并完成常见 AI 能力（文本图片视频）的 API 接入 | ✅ |
| [初级五：完整项目实战](/stage-1/1.4-complete-project-practice/) | 模拟真实场景、接受用户反馈迭代并完成项目展示 | ✅ |
| [大作业：做一个完整的 Web 应用原型并展示](/stage-1/1.5-final-project/) | 独立用 AI IDE 落地并演示一个可用 Web 应用 | ✅ |
#### 附录
| 章节 | 关键内容 | 状态 |
| :-------------------------------------------------------------- | :---------------------------------------- | :--- |
| [附录A：产品思维补充](/stage-1/appendix-a-product-thinking/) | 从想法评估到需求拆解与 MVP 的产品思维框架 | ✅ |
| [附录B：常见报错及解决方案](/stage-1/appendix-b-common-errors/) | vibe coding 中的常见错误及排查方法 | ✅ |
### 二、初中级开发工程师
#### 前端部分
| 章节 | 关键内容 | 状态 |
| :------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------- | :--- |
| 前端零：使用 lovart 生产素材 | 学会用 lovart 批量生成人物、场景等视觉素材，为 UI 设计和前端开发提供素材基础 | 🚧 |
| 前端一：Figma 与 MasterGo 入门 | 用设计工具梳理信息架构和页面结构，为前端实现打基础 | 🚧 |
| 前端二：构建第一个现代应用程序-UI 设计 | 基于设计稿完成组件化界面，实现从设计到代码的第一条链路 | 🚧 |
| 前端三：参考 UI 设计规范与多产品 UI 设计 | 围绕统一主视觉扩展多产品界面，练习系统化设计能力 | 🚧 |
| [前端四：一起做霍格沃茨画像](/project/chapter4/chapter4-lets-build-hogwarts-portraits) | 从 0 到 1 做出接入 AI 能力的前端应用，串联设计与开发 | 🚧 |
#### 后端与全栈部分
| 章节 | 关键内容 | 状态 |
| :---------------------------------------------------------------------------------- | :------------------------------------------------------------ | :--- |
| 后端一：什么是 API | 理解 HTTP 接口与请求响应模型，为后端集成与联调做准备 | 🚧 |
| [后端二：从数据库到 Supabase](/project/chapter5/chapter5-from-database-to-supabase) | 在 Supabase 上落地数据库和 API，打通数据模型与前端页面 | 🚧 |
| 后端三：大模型辅助编写接口代码与接口文档 | 用大模型协助生成接口与数据库文档及代码，实现可读可测的后端 | 🚧 |
| 后端四：Git 工作流与 Zeabur 部署 | 在 Git 工作流中管理代码，并将应用部署到 Zeabur 上线 | 🚧 |
| 后端五：现代 CLI 开发工具 | 使用 CLI 类 AI 编程工具加速开发与调试，形成个人工程化工作流 | 🚧 |
| 后端六：如何集成 stripe 等收费系统 | 接入支付系统，完成收费链路与基础结算流程 | 🚧 |
| 大作业 1：构建第一个现代应用程序-全栈应用 | 综合前端、后端与支付模块，完成可上线的全栈 Web 应用 | 🚧 |
| 大作业 2：现代前端组件库 + Trae 实战 | 使用现代前端组件库与 Trae，独立完成可登录注册并支持收费的产品 | 🚧 |
#### AI 能力附录
| 章节 | 关键内容 | 状态 |
| :---------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------- | :--- |
| [AI 一：Dify 入门与知识库集成](/project/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration) | 用 Dify Workflow 与基础 RAG 搭建工具类产品，为后续应用升级打样 | 🚧 |
| AI 二：学会查询 AI 词典与集成多模态 API | 学会查找合适的模型与 API，并把文本、图像等多模态能力接入产品 | 🚧 |
### 三、高级开发工程师
docs/index.html
-268
View File
@@ -1,268 +0,0 @@
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="UTF-8" />
<title>Vibe Coding 101</title>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0" />
<!-- Theme: Vue -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css" onerror="this.onerror=null;this.href='https://unpkg.com/docsify@4/lib/themes/vue.css';" />
<!-- Katex CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.0/dist/katex.min.css" onerror="this.onerror=null;this.href='https://unpkg.com/katex@0.16.0/dist/katex.min.css';" />
<!-- Viewer.js CSS -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/viewerjs@1.11.6/dist/viewer.min.css" />
<style>
/* --- 样式保持不变 --- */
.github-corner:hover .octo-arm { animation: octocat-wave 560ms ease-in-out; }
@keyframes octocat-wave { 0%, 100% { transform: rotate(0); } 20%, 60% { transform: rotate(-25deg); } 40%, 80% { transform: rotate(10deg); } }
@media (max-width: 500px) { .github-corner:hover .octo-arm { animation: none; } .github-corner .octo-arm { animation: octocat-wave 560ms ease-in-out; } }
:root { --sidebar-width: 230px; --sidebar-padding: 12px 24px; --theme-color: #42b983; }
.markdown-section {
padding: 24px 40px 40px 24px;
max-width: 850px; /* 增加内容宽度，减少左右空白 */
}
.sidebar-nav ul { list-style-type: none; }
/* 优化侧边栏主菜单间距 */
.sidebar-nav li { margin: 0; }
.sidebar-nav ul li a {
padding: 3px 0;
line-height: 1.4;
font-weight: bold; /* 文件标题加粗 */
}
.app-sub-sidebar li { list-style-type: none !important; }
.app-sub-sidebar li::before { content: none !important; }
/* 目录内容（TOC）不加粗，并提高优先级覆盖上面的设置 */
.sidebar-nav .app-sub-sidebar li a {
padding: 2px 0;
line-height: 1.3;
display: block;
font-weight: normal;
}
/* --- 暗黑模式样式 --- */
:root {
--dark-bg: #1a1a1a;
--dark-sidebar: #141414;
--dark-border: #333;
--dark-text: #e6e6e6;
--dark-code-text: #f8f8f2;
--dark-code-bg: #2b2b2b;
}
body.dark-mode { background-color: var(--dark-bg); color: var(--dark-text); }
body.dark-mode .sidebar { background-color: var(--dark-sidebar); border-right: 1px solid var(--dark-border); color: var(--dark-text); }
body.dark-mode .sidebar-nav li a { color: #999; }
body.dark-mode .sidebar-nav li.active > a { color: var(--theme-color); border-right: 2px solid var(--theme-color); }
body.dark-mode .search { border-bottom: 1px solid var(--dark-border); }
body.dark-mode .search input { background-color: transparent; color: var(--dark-text); }
body.dark-mode .results-panel { background-color: var(--dark-bg); color: var(--dark-text); }
body.dark-mode .matching-post { border-bottom: 1px solid var(--dark-border); }
body.dark-mode .matching-post h2, body.dark-mode .matching-post p { color: var(--dark-text); }
body.dark-mode pre { background-color: var(--dark-code-bg) !important; }
body.dark-mode code { background-color: var(--dark-code-bg) !important; color: var(--dark-code-text) !important; }
body.dark-mode .markdown-section code { color: #f08d49; background-color: rgba(255,255,255,0.1); }
body.dark-mode h1, body.dark-mode h2, body.dark-mode h3, body.dark-mode h4, body.dark-mode h5, body.dark-mode h6 { color: #ffffff; }
body.dark-mode blockquote { color: #b0b0b0; background: rgba(255,255,255,0.05); border-left-color: var(--theme-color); }
body.dark-mode strong { color: #fff; }
body.dark-mode .markdown-section tr:nth-child(2n) { background-color: rgba(255,255,255,0.03); }
body.dark-mode .markdown-section td, body.dark-mode .markdown-section th { border-color: var(--dark-border); }
.vibe-toggle-text { cursor: pointer; display: inline-flex; align-items: center; padding: 0; margin-left: 8px; font-size: 14px; border: none; background: transparent; transition: opacity 0.2s; vertical-align: middle; line-height: 1; color: inherit; font-weight: normal; }
body.dark-mode .vibe-toggle-text { background: transparent; border: none; }
.vibe-toggle-text:hover { opacity: 0.7; }
.vibe-toggle-text span { margin-left: 4px; font-size: 13px; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif; }
/* --- 全局图片样式控制 --- */
.markdown-section img {
max-width: 80%; /* 限制最大宽度为 80% */
max-height: 300px; /* 限制最大高度为 300px */
display: block; /* 块级显示 */
margin: 10px auto; /* 上下间距 10px，左右自动居中 */
border-radius: 4px; /* 轻微圆角 */
box-shadow: 0 2px 10px rgba(0,0,0,0.1); /* 轻微阴影，增加质感 */
}
</style>
</head>
<body>
<div id="app">加载中... (如果长时间未加载，请尝试刷新)</div>
<a href="https://github.com/datawhalechina/vibe-coding" class="github-corner" aria-label="View source on GitHub">
<svg width="80" height="80" viewBox="0 0 250 250" style="fill: #64ceaa; color: #fff; position: absolute; top: 0; border: 0; right: 0;" aria-hidden="true">
<path d="M0,0 L115,115 L130,115 L142,142 L250,250 L250,0 Z"></path>
<path d="M128.3,109.0 C113.8,99.7 119.0,89.6 119.0,89.6 C122.0,82.7 120.5,78.6 120.5,78.6 C119.2,72.0 123.4,76.3 123.4,76.3 C127.3,80.9 125.5,87.3 125.5,87.3 C122.9,97.6 130.6,101.9 134.4,103.2" fill="currentColor" style="transform-origin: 130px 106px;" class="octo-arm"></path>
<path d="M115.0,115.0 C114.9,115.1 118.7,116.5 119.8,115.4 L133.7,101.6 C136.9,99.2 139.9,98.4 142.2,98.6 C133.8,88.0 127.5,74.4 143.8,58.0 C148.5,53.4 154.0,51.2 159.7,51.0 C160.3,49.4 163.2,43.6 171.4,40.1 C171.4,40.1 176.1,42.5 178.8,56.2 C183.1,58.6 187.2,61.8 190.9,65.4 C194.5,69.0 197.7,73.2 200.1,77.6 C213.8,80.2 216.3,84.9 216.3,84.9 C212.7,93.1 206.9,96.0 205.4,96.6 C205.1,102.4 203.0,107.8 198.3,112.5 C181.9,128.9 168.3,122.5 157.7,114.1 C157.9,116.9 156.9,120.9 152.7,125.1 L141.0,136.9 C139.8,138.0 141.6,141.9 141.8,141.8 Z" fill="currentColor" class="octo-body"></path>
</svg>
</a>
<script>
window.$docsify = {
name: 'Vibe Coding 101',
repo: '',
loadSidebar: true,
// 核心修复：禁用了 relativePath，避免搜索插件路径解析错误
// relativePath: true,
alias: {
'/.*/_sidebar.md': '/_sidebar.md'
},
subMaxLevel: 2,
homepage: 'README.md',
// --- 搜索配置 ---
search: {
maxAge: 86400000,
paths: [
'README.md',
'project/chapter0-learning-map/chapter0-learning-map.md',
'project/chapter1/chapter1-how-to-build-a-snake-game.md',
'project/chapter2/chapter2-reach-the-capability-boundaries-of-ai-tools.md',
'project/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md',
'project/chapter4/chapter4-lets-build-hogwarts-portraits.md',
'project/chapter5/chapter5-from-database-to-supabase.md',
'project/chapter6/chapter6-no-code-without-an-idea.md',
'extra/extra1/extra1-what-is-git-and-what-is-github.md',
'extra/extra2/extra2-what-is-api.md',
'extra/extra3/extra3-ai-capability-starter-handbook.md',
'extra/extra4/extra4-what-is-ai-ide-and-trae.md',
'extra/extra5/extra5-what-is-rag-and-how-does-it-work-and-future.md',
'extra/extra6/extra6-zeabur-what-is-it-and-how-to-deploy-web-applications.md',
'extra/extra7/extra7-cli-ai-coding-tools-and-the-principles-of-test-driven-development.md',
'examples/example0/example0-1/vibe-coding-tools-snake-game-tutorial.md',
'examples/example0/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents.md',
'examples/example1/example1-how-to-build-a-wechat-miniprogram.md'
],
placeholder: '🔍 搜索',
noData: '😞 找不到结果',
depth: 3,
namespace: 'vibe-coding-search-v5' // 更新命名空间以清理旧缓存
},
pagination: {
previousText: '上一页',
nextText: '下一页',
crossChapter: true,
crossChapterText: true
},
count: {
countable: true,
position: 'top',
margin: '10px 0 20px 0',
float: 'left',
fontsize: '0.9em',
color: 'rgb(90,90,90)',
language: 'chinese',
isExpected: true
},
plugins: [
function (hook, vm) {
hook.doneEach(function () {
// 暗黑模式切换按钮逻辑
var appName = document.querySelector('.app-name');
if (appName) {
var existing = document.querySelector('.vibe-toggle-text');
if (!existing) {
existing = document.createElement('span');
existing.className = 'vibe-toggle-text';
existing.onclick = function (e) {
e.stopPropagation();
e.preventDefault();
document.body.classList.toggle('dark-mode');
var isDark = document.body.classList.contains('dark-mode');
localStorage.setItem('theme-mode', isDark ? 'dark' : 'light');
var html = isDark
? '🌙 <span style="display:inline; color:inherit;">Dark</span>'
: '☀️ <span style="display:inline; color:inherit;">Light</span>';
if (existing.innerHTML !== html) existing.innerHTML = html;
};
appName.appendChild(existing);
}
var savedTheme = localStorage.getItem('theme-mode');
var isDark = savedTheme === 'dark';
if (isDark) document.body.classList.add('dark-mode');
else document.body.classList.remove('dark-mode');
var html = isDark
? '🌙 <span style="display:inline; color:inherit;">Dark</span>'
: '☀️ <span style="display:inline; color:inherit;">Light</span>';
if (existing.innerHTML !== html) existing.innerHTML = html;
}
// 字数统计位置调整
setTimeout(function () {
var section = document.querySelector('.markdown-section');
if (!section) return;
var title = section.querySelector('h1');
var counter = section.querySelector('.countable');
if (title && counter && title.nextSibling !== counter) {
title.parentNode.insertBefore(counter, title.nextSibling);
counter.style.display = 'block';
counter.style.float = 'none';
counter.style.margin = '10px 0 20px 0';
}
}, 0);
});
},
function (hook, vm) {
hook.doneEach(function () {
// Viewer.js 图片预览插件初始化
var container = document.querySelector('.markdown-section');
if (container) {
new Viewer(container, {
filter: function(image) {
// 过滤掉 emoji 和非内容图片
return !image.classList.contains('emoji');
},
// 工具栏配置：显示缩放、旋转、翻转等
toolbar: {
zoomIn: 4,
zoomOut: 4,
oneToOne: 4,
reset: 4,
prev: 0,
play: 0,
next: 0,
rotateLeft: 4,
rotateRight: 4,
flipHorizontal: 4,
flipVertical: 4,
},
title: false, // 不显示标题
navbar: false, // 不显示底部缩略图导航
movable: true, // 允许拖动
zoomable: true, // 允许缩放
rotatable: true, // 允许旋转
scalable: true, // 允许翻转
});
}
});
}
]
};
</script>
<!-- 核心 Docsify - 优先使用 jsDelivr -->
<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js" onerror="this.onerror=null;this.src='https://unpkg.com/docsify@4/lib/docsify.min.js';"></script>
<!-- 插件 -->
<script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.min.js" onerror="this.onerror=null;this.src='https://unpkg.com/docsify@4/lib/plugins/search.min.js';"></script>
<!-- Viewer.js 替代 zoom-image -->
<script src="https://cdn.jsdelivr.net/npm/viewerjs@1.11.6/dist/viewer.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js" onerror="this.onerror=null;this.src='https://unpkg.com/docsify-copy-code/dist/docsify-copy-code.min.js';"></script>
<!-- Prism 代码高亮 -->
<script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js" onerror="this.onerror=null;this.src='https://unpkg.com/prismjs@1/components/prism-bash.min.js';"></script>
<script src="https://cdn.jsdelivr.net/npm/prismjs@1/components/prism-python.min.js" onerror="this.onerror=null;this.src='https://unpkg.com/prismjs@1/components/prism-python.min.js';"></script>
<!-- 分页 -->
<script src="https://cdn.jsdelivr.net/npm/docsify-pagination@2/dist/docsify-pagination.min.js" onerror="this.onerror=null;this.src='https://unpkg.com/docsify-pagination@2/dist/docsify-pagination.min.js';"></script>
<!-- Katex 公式 - 确保版本匹配 -->
<script src="https://cdn.jsdelivr.net/npm/katex@0.16.0/dist/katex.min.js" onerror="this.onerror=null;this.src='https://unpkg.com/katex@0.16.0/dist/katex.min.js';"></script>
<script src="https://cdn.jsdelivr.net/npm/docsify-katex@latest/dist/docsify-katex.js" onerror="this.onerror=null;this.src='https://unpkg.com/docsify-katex@latest/dist/docsify-katex.js';"></script>
<!-- 字数统计 -->
<script src="https://cdn.jsdelivr.net/npm/docsify-count@latest/dist/countable.min.js" onerror="this.onerror=null;this.src='https://unpkg.com/docsify-count/dist/countable.js';"></script>
</body>
</html>
docs/index.md
+239
View File
@@ -0,0 +1,239 @@
---
layout: home
hero:
name: 'Easy-Vibe'
text: 'Learn Vibe Coding from 0 to 1'
tagline:
- 不止是写代码，而是成为集产品、设计、全栈开发于一身的超级个体。
- 从想法到原型，从原型到上线，把每一次输出变成可交付的产品。
- 让 AI 成为你的搭档：更快、更稳、更有创造力。
- 用系统化的学习路径，构建你的个人技术与产品护城河。
actions:
- theme: brand
text: 开启学习之旅
link: /stage-0/0.1-learning-map/
- theme: alt
text: ⭐️ github 加速更新
link: https://github.com/datawhalechina/easy-vibe
features:
- title: 零基础友好
details: 专为非技术背景设计。从“会说话就会编程”开始，通过贪吃蛇等小游戏快速上手，打破技术恐惧。
- title: 循序渐进的实战路径
details: 独创“三阶段”学习法。从 AI 产品经理思维，到全栈开发落地，再到复杂应用构建，步步为营。
- title: Vibe Coding 新范式
details: 掌握 AI 时代的编程核心。学会与 AI 结对编程，让 IDE 成为你的最强搭档。
- title: 真实项目驱动
details: 拒绝玩具代码。亲手构建 Web 原型、全栈应用、微信小程序，将每一个想法真正落地为产品。
---
<div align="center" style="margin-top: 40px; margin-bottom: 40px;">
<h2 style="border: none; font-size: 2rem; font-weight: 700; margin-bottom: 20px;">为什么选择 Easy-Vibe？</h2>
<p style="font-size: 1.2rem; color: var(--vp-c-text-2); max-width: 800px; margin: 0 auto; line-height: 1.6;">
2025 年是 AI 编程的元年。越来越多的人开始尝试 AI 编程，但往往止步于简单的 Demo。<br>
Easy-Vibe 致力于填补这一空白，教你如何像专业人士一样，用 AI 组织开发流程，从原型到上线，打通产品落地的最后一公里。
</p>
</div>
<div class="stage-container">
<div class="stage-card">
<div class="stage-icon">🌱</div>
<h3>Stage 0: 纯新手</h3>
<p>适合产品、运营及非技术背景。通过做游戏理解 AI 编程逻辑，建立信心。</p>
<a href="/stage-0/0.1-learning-map/">查看详情 →</a>
</div>
<div class="stage-card">
<div class="stage-icon">🎨</div>
<h3>Stage 1: AI 产品经理</h3>
<p>掌握 Vibe Coding 工作流。学会拆解需求，独立完成高保真 Web 应用原型。</p>
<a href="/stage-1/1.1-introduction-to-ai-ide/">查看详情 →</a>
</div>
<div class="stage-card">
<div class="stage-icon">💻</div>
<h3>Stage 2: 初中级开发</h3>
<p>深入全栈开发。前端组件化、数据库设计、后端 API 开发与部署上线。</p>
<a href="/project/chapter4/chapter4-lets-build-hogwarts-portraits">查看详情 →</a>
</div>
<div class="stage-card">
<div class="stage-icon">🚀</div>
<h3>Stage 3: 高级开发</h3>
<p>构建复杂跨平台应用。微信小程序实战，挑战更高阶的 AI 原生应用开发。</p>
<a href="/stage-3/3.3-how-to-build-a-wechat-miniprogram/example1/index">查看详情 →</a>
</div>
</div>
<style>
.VPHomeHero .text {
font-size: 1.8rem;
}
.stage-container {
display: grid;
grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
gap: 20px;
max-width: 1152px;
margin: 0 auto;
padding: 20px;
}
.stage-card:nth-child(1) { --card-color: #10b981; } /* Green for Stage 0 */
.stage-card:nth-child(2) { --card-color: #3b82f6; } /* Blue for Stage 1 */
.stage-card:nth-child(3) { --card-color: #8b5cf6; } /* Purple for Stage 2 */
.stage-card:nth-child(4) { --card-color: #f59e0b; } /* Orange for Stage 3 */
.stage-card {
background-color: var(--vp-c-bg-soft);
border-radius: 12px;
padding: 24px;
transition: transform 0.2s, box-shadow 0.2s, border-color 0.2s;
border: 1px solid var(--vp-c-bg-soft);
position: relative;
overflow: hidden;
}
.stage-card::before {
content: '';
position: absolute;
top: 0;
left: 0;
width: 4px;
height: 100%;
background-color: var(--card-color);
opacity: 0.5;
transition: opacity 0.2s;
}
.stage-card:hover {
transform: translateY(-5px);
box-shadow: 0 10px 30px rgba(0, 0, 0, 0.1);
border-color: var(--card-color);
}
.stage-card:hover::before {
opacity: 1;
}
.stage-icon {
font-size: 3rem;
margin-bottom: 16px;
filter: drop-shadow(0 4px 6px rgba(0,0,0,0.1));
}
.stage-card h3 {
font-size: 1.2rem;
font-weight: 600;
margin-bottom: 8px;
color: var(--vp-c-text-1);
transition: color 0.2s;
}
.stage-card:hover h3 {
color: var(--card-color);
}
.stage-card p {
font-size: 0.9rem;
color: var(--vp-c-text-2);
margin-bottom: 16px;
line-height: 1.5;
}
.stage-card a {
color: var(--card-color);
font-weight: 500;
text-decoration: none;
font-size: 0.9rem;
display: inline-flex;
align-items: center;
transition: transform 0.2s;
}
.stage-card a:hover {
text-decoration: none;
transform: translateX(4px);
}
</style>
<div class="footer-cta">
<p class="love-text">Made with ❤️ by Open Source Contributors</p>
<h3 class="support-title">觉得有帮助？</h3>
<p class="support-text">你的 Star 是我们持续更新的动力 🚀</p>
<div class="github-badge">
<a href="https://github.com/datawhalechina/easy-vibe" target="_blank" rel="noopener noreferrer">
<img src="https://img.shields.io/github/stars/datawhalechina/easy-vibe?style=social&label=Star on GitHub" alt="GitHub stars"/>
</a>
</div>
</div>
<style>
/* ... existing styles ... */
.footer-cta {
margin-top: 100px;
padding: 40px 24px;
text-align: center;
background: var(--vp-c-bg-soft);
border-radius: 24px;
max-width: 600px;
margin-left: auto;
margin-right: auto;
margin-bottom: 40px;
border: 1px solid var(--vp-c-bg-soft);
transition: border-color 0.3s;
}
.footer-cta:hover {
border-color: var(--vp-c-brand);
}
.love-text {
color: var(--vp-c-text-3);
font-size: 0.875rem;
margin-bottom: 24px;
font-family: var(--vp-font-family-mono);
}
.support-title {
font-size: 1.5rem;
font-weight: 700;
margin-bottom: 8px;
color: var(--vp-c-text-1);
}
.support-text {
font-size: 1.1rem;
color: var(--vp-c-text-2);
margin-bottom: 24px;
}
.github-badge {
display: flex;
justify-content: center;
align-items: center;
}
.github-badge img {
height: 32px; /* Make the button slightly larger */
}
/* Custom style for the GitHub Star button in Hero section */
.VPButton.alt[href*="github.com"] {
background: linear-gradient(90deg, #8B5CF6, #EC4899, #8B5CF6);
background-size: 200% auto;
border: 1px solid transparent !important;
color: white !important;
font-weight: 600;
animation: gradient 3s linear infinite;
box-shadow: 0 4px 14px 0 rgba(139, 92, 246, 0.5);
transition: all 0.3s ease;
}
.VPButton.alt[href*="github.com"]:hover {
transform: translateY(-2px);
box-shadow: 0 6px 20px rgba(236, 72, 153, 0.6);
background-position: right center;
}
@keyframes gradient {
0% { background-position: 0% 50%; }
100% { background-position: 200% 50%; }
}
</style>
docs/project/README.md
+7
View File
@@ -0,0 +1,7 @@
# Project 文档
这里包含了项目实战的相关文档：
- [Chapter 3: Getting Started with Dify](chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md)
- [Chapter 4: Let's Build Hogwarts Portraits](chapter4/chapter4-lets-build-hogwarts-portraits.md)
- [Chapter 5: From Database to Supabase](chapter5/chapter5-from-database-to-supabase.md)
docs/project/chapter0-learning-map/chapter0-learning-map.md
-57
View File
@@ -1,57 +0,0 @@
# 从创意到 AI 产品
我们目前正经历着由大语言模型（LLMs）驱动的 AI 技术应用的爆炸式浪潮。与过去 AI 开发严重依赖算法研究不同，现在行业的重点已转移到有效利用现有的强大 AI 模型来创建有价值的应用程序。这一转变显着降低了 AI 开发的门槛，将重心从“从头构建模型”转移到了“将 AI 能力封装成现实世界的解决方案”。
对于大多数初学者和开发者来说，今天最大的机会不在于发明新算法，而在于学习如何有效地调用、编排和工程化 AI 功能，以满足特定的市场和用户需求。
尽管有了这种转变，许多学习者发现，掌握与 AI 交互或生成内容的技能只是一个起点。一个普遍存在的挑战仍然存在：如何实现从“AI 用户”到“AI 应用创造者”的跨越。关键问题包括：如何将分散的 AI 功能集成到自动化工作流中？如何为 AI 应用程序构建健壮可靠的前端和后端，并将它们在线部署？如何跨越从开发到实际运营的关键“最后一公里”？
本课程正是为了解决这些关键障碍而设计的。它不拘泥于抽象理论，而是致力于 AI 原生应用开发的端到端实践培训。
# 为什么要学这个？它将如何帮助我的未来？
本课程侧重于 AI 原生应用的实际开发和创新思维的培养，专为初级水平的学生量身定制。通过理论指导和动手实践相结合，学生将逐步掌握 AI 应用开发必不可少的核心方法和创新途径：
* **基本掌握多模态 AI 模型的应用方法和适用场景：**
* 能够使用 vibe coding 工具调用主流多模态理解和生成模型 API（涵盖文本、图像、视频、音频等）。
* 能够分析不同模型的能力边界，并根据特定应用场景适当地选择模型。
* **能够利用和分析前沿 AI 产品：**
* 能够研究和分析行业内各种最先进的 AI 产品（基于文本、图像、视频），学习分析产品构建背后的技术原理，并了解竞争对手使用的常见实现方法。
* **基本理解和实践不同的 AI 应用框架和核心工作流：**
* **知识库与 AI 工作流：** 了解知识库构建的基础知识，并开发使用它们的基础和中级技能，以及设计、实施和优化 AI 工作流的能力。
* **智能体 (Agent)：** 了解智能体的原理，并获得智能体开发和应用的初步实践经验。
* **图像生成和编辑：** 掌握图像生成和编辑工作流中的入门级和高级技术。
* **AI 原生应用开发和运营的实践经验：**
* 学习使用先进的 AI 编码工具；了解前端和后端数据库的作用；并能够独立开发和部署 AI 应用程序（APP / Web 应用程序）。
* 了解用户管理和支付等核心功能模块的实现方法。
* 获得用户研究、产品推广和应用分享的基本技能；同时，通过与企业合作或独立运营，开始探索 AI 应用的价值创造闭环。
# 为什么要用项目制来训练？
原因其实很简单：按照大多数同学现在的状态，直接走入职场，很可能会在真实项目和老板 / 客户的“社会毒打”下寸步难行。现实世界更常见的场景是：
> 你的导师 / 老板：我们要做一个 xxx，目标是达到 yyy 的效果。
>
> 文档？现成框架？详细的需求说明？很多时候都不存在。
真实工作中的许多任务，本质上就是在高度不确定的环境下解决从未见过的问题：需求是模糊的，边界是变化的，没人告诉你标准答案，你需要自己查资料、做实验、搭原型、不断迭代，最后给出一个“能跑、能用、能上线”的解决方案。
这门课想做的，就是在一个相对安全的环境里，提前给你一次“模拟社会毒打”：
- 通过看似有一定难度的项目任务，迫使你练习拆解问题、设计方案、自己寻找资料
- 通过不那么“傻瓜化”的脚手架和代码，让你学会阅读、理解和改造一份中大型代码库
- 通过从创意到上线的完整闭环，让你体验真实产品从 0 到 1 的完整过程
短期来看，这种训练确实比较折磨人；但从长期来看，它会极大提高你在求职和职业发展中的竞争力：你会更能扛事儿，更能在不确定环境中找到突破口，也更有能力把 AI 变成真正落地的产品，而不是停留在“玩玩 Demo”阶段。
# 坚持了好久还是搞不定，我想放弃了
也许是你坚持的方法不对。不要一个人在黑暗中硬撑，可以来跟作者和助教们聊聊：把你已经尝试过的方法、遇到的具体卡点、和你目前的心理状态，坦诚地说出来。很多时候，只要稍微调整一下方向、补上一个关键知识点，你就能继续往前走。
# 我觉得教程有的设计不合理
欢迎随时联系作者、提交 issue，或者在群里 / 课堂上直接反馈。我们非常希望和你一起把这套教程打磨得越来越好：哪里不清晰、哪里体验不好、哪里让你白费力气，都可以坦诚指出来。越真实、越具体的反馈，越能帮助后来者少踩坑。
# Reference
- [南京大学 计算机科学与技术系 计算机系统基础 课程实验](https://nju-projectn.github.io/ics-pa-gitbook/ics2025/)
docs/project/chapter1/chapter1-how-to-build-a-snake-game.md
-652
View File
@@ -1,652 +0,0 @@
# Project 1: 如何构建贪吃蛇游戏
这是一个**基于项目的**学习教程。我们鼓励你跟随步骤一步步操作，并尝试复现结果。不要担心犯错或修改内容——最重要的是请记住： 🎉 **完成比完美更重要**
在软件工程中，不断迭代更新推翻重做一个项目是十分正常的，包括本教程也经历过多次的推翻重构。所以，你不需要一次性就创造出一个完整的产品，一开始做个垃圾也没关系，如果一开始就做出好的作品，请快快联系我加入贡献作者群。你只需要记住：**从小处着手，边做边改，持之以恒。**
第一个 Project 结合了最简单的在线编程工具以及 AI 能力调用方法，能够方便你理解制作程序以及调用 AI 能力的基本概念。我们将学习如何使用最基础的 **vibe coding** 技巧来创建一个现代版的 AI 原生贪吃蛇游戏。我们将从贪吃蛇游戏的基本机制开始，然后对其进行修改，让蛇吃掉字符而不是点。最后，游戏将根据这些字符生成一首诗，并绘制一幅受这首诗启发的图画。
> 💡 什么是 Vibe Coding？计算机科学家 [Andrej Karpathy](https://karpathy.ai/)（OpenAI 的联合创始人之一，特斯拉前 AI 负责人）于 2025 年 2 月提出了 **vibe coding** 一词。这个概念指的是一种依赖于 LLM 的编码方法，允许程序员通过提供自然语言描述而不是手动编写代码来生成可工作的代码。
>
> ![1767350588191](images/1767350588191.png)
>
> 点击这里查看更多关于 vibe coding 的细节：[https://www.ibm.com/think/topics/vibe-coding](https://www.ibm.com/think/topics/vibe-coding)
>
> 点击这里查看更多关于 Karpathy 的分享内容：[https://karpathy.bearblog.dev/blog/](https://karpathy.bearblog.dev/blog/)
# 你将学到
* 使用提示词（prompts）构建一个简单的游戏。
* 如果你看到错误，告诉 AI 并让它帮你修复。
* 为你的游戏添加文本和图像生成功能，使其更有趣。
# 1. 准备工作
## 1.1 我们应该使用哪些工具？
我们将使用一个非常简单的工具来构建一个最小化的游戏。你不需要知道如何调用大语言模型或图像生成模型。
这个工具叫做 [z.ai](https://chat.z.ai/)，由智谱 AI（中国领先的 LLM 公司之一）开发。它支持多种功能，如 AI 驱动的幻灯片生成、海报设计和全栈开发。在本教程中，我们将重点关注其全栈开发模块。
![](images/image2.png)
[z.ai](https://chat.z.ai/) 中的全栈开发模块支持网页的实时编辑和预览。
![](images/image3.png)
通过点击全栈开发示例，你可以看到网页创建的整个过程。并且等一杯咖啡的时间，你的结果也就出来了！
![](images/image5.png)
你可以上下滚动浏览此网页，或点击顶部的 🧭 按钮以全屏模式查看页面。
![](images/image6.png)
如果你想查看此网页的源代码，可以点击右上角的图标查看所有代码。
![img](images/image7.png)
![](images/image8.png)
## 1.2 我们需要前端开发知识吗？
我们在开始时不需要掌握前端甚至后端开发技能。我们只需要学习如何与大语言模型聊天，如何根据当前的运行结果向 LLM 提出新需求，以及当代码运行失败时如何向 LLM 提供准确的错误信息。
但我们建议你学习一些前端和后端开发的基础知识，因为这将帮助你让 LLM 创建更好的程序。
别担心，你只需要在学习过程中逐渐掌握这些知识，不需要一开始就是专家。
> 💡 更多关于前端开发的信息
>
> 前端开发通常意味着使用 **HTML**、**CSS** 和 **JavaScript** 来创建网站或应用程序的用户界面。然而，在本教程中，我们将跳过前端编码的复杂性，因为我们使用的工具会自动为我们生成并运行界面。
>
> 但了解幕后发生的事情是有帮助的。传统上，构建 Web 界面涉及编写用于结构的 **HTML**、用于样式的 **CSS** 和用于交互性的 **JavaScript**。
>
> 例如，这是一个非常简单的网页，但它结合了三种不同类型的代码：
>
> ![](images/image9.png)
>
> * 一个简单的 HTML 按钮：
>
> ```HTML
> <button>Click Me</button>
> ```
>
> * 基本的 CSS 让按钮变蓝：
>
> ```CSS
> button {
> background-color: #3498db;
> color: white;
> border: none;
> padding: 10px 20px;
> border-radius: 4px;
> }
> ```
>
> * 一点 JavaScript 来在点击按钮时显示提示：
>
> ```JavaScript
> document.querySelector('button').onclick = function() {
> alert('Button was clicked!');
> }
> ```
>
> 当你尝试点击这个按钮时，你会在浏览器中看到一个提示信息：
>
> ![](images/image10.png)
>
> 此外，我们可以尝试理解这三种代码的深层含义：
>
> **什么是 HTML？**
>
> HTML，全称 **超文本标记语言 (HyperText Markup Language)**，是网页的骨架。它的工作是定义页面的结构和内容，如标题、段落、图像、链接，以及示例中看到的按钮本身。
>
> * **HTML 决定页面上有什么**：它告诉浏览器，“这是一个按钮”，“这是一段文本”，或者“在这里显示一张图片”。
> * **它使用“标签”来组织内容**：`<button>Click Me</button>` 是一个 HTML 标签，定义了一个按钮，并在其中包含了“Click Me”这个文本。
>
> **什么是 CSS？**
>
> CSS，或层叠样式表 (Cascading Style Sheets)，负责网页的“外观和感觉”。它用于设计和美化 HTML 元素，控制颜色、字体、布局和间距等。
>
> * **CSS 决定页面看起来怎么样**：在我们的示例中，CSS 代码将标准 HTML 按钮变成了一个带有蓝色背景、白色文本、圆角和一些内边距的按钮。
> * **它将内容与表现分离**：这是一个关键概念。你可以有一个用于内容的 HTML 文件，并使用一个单独的 CSS 文件来设置它的样式。这使得维护和更新整个网站的设计变得更加容易。
>
> **什么是 JavaScript？**
>
> JavaScript 是一种编程语言，它为网页添加交互性和动态行为。如果说 HTML 是骨架，CSS 是皮肤，那么 JavaScript 就是大脑和肌肉，让页面“活起来”。
>
> * **JavaScript 决定页面的行为**：在示例中，JavaScript 代码使得点击按钮时弹出提示框。它定义了响应用户输入时应该发生的操作。
> * **它可以创建复杂的功能**：除了简单的提示，JavaScript 还用于处理表单提交、创建动画、在不重新加载页面的情况下加载新数据、构建像游戏这样的复杂应用程序等等。
>
> 随着项目变得越来越大，交互性越来越强，仅使用纯 HTML、CSS 和 JavaScript 管理代码会变得复杂且难以维护。这就是现代前端库如 **React** 发挥作用的地方。
>
> ![](images/image11.png)
>
> **[React](https://react.dev/)** 是一个用于构建用户界面的流行 JavaScript 库。它帮助开发者将代码组织成可重用的组件，使得构建和维护复杂的应用程序变得更加容易。
>
> React 允许你编写管理自己逻辑和外观的组件，然后将它们组合起来构建更大的界面。
>
> 随着我们的深入，我们将探索更多关于 React 如何工作以及它如何适应我们的工作流程的内容。现在，只需要知道，虽然前端开发通常意味着编写像这样的代码，但我们的工具会自动处理大部分工作——我们只需要知道如何向大语言模型清楚地表达我们的需求！
# 2. 构建你的第一个游戏
## 2.1 与 LLM 对话时给出清晰的指令
在一开始，我们可以用最简单的方式与大模型对话，这将帮助我们快速获得产品原型。我们可以直接在聊天框中输入：
> **💡 示例提示词：** 帮我做一个贪吃蛇游戏
>
> ![](images/image12.png)
> **💡 示例提示词：** 帮我做一个贪吃蛇游戏，它应该支持
>
> 1. 我可以吃不同的单词，它们会被收集在一个盒子里
> ![](images/image13.png)
> **💡 示例提示词：** 帮我做一个贪吃蛇游戏，它应该支持：
>
> 1. 我可以吃不同的单词，它们会被收集在一个盒子里
> 2. 当蛇吃了8个单词时，llm 应该根据这些单词创作一首诗，我们可以根据需要重新混合这首诗。
> 3. 当诗完成后，下一步将自动根据这首诗创建一幅图像。
>
> ![](images/image14.png)
## 2.2 尝试修复过程中出现的错误
在开发过程中，我们可能会遇到不尽如人意的问题，例如点击按钮没有任何反应、使用功能时报错、功能未按预期工作，或者前端页面与预期设计不符。
在这种情况下，我们需要进一步向模型提问，以帮助修复这些意外问题。
![](images/image15.png)
## 2.3 如何假装自己是 Vibe Coding 大师
实际上，在真正的 vibe coding 过程中，我们通常不会使用很多复杂的提示词。也许我们在开始时需要为整个程序提供一个具体且适度复杂的提示词，但在那之后的每一步，你可能只需要以下类型的提示词：
```JSON
"代码里有个 bug，请修复它。"
"我不要部分代码，给我完整的修改后的代码。"
"你的代码还是有问题。"
"请再次修改并给我完整的修正后的代码。"
"刚才还能运行，为什么现在不能运行了？"
"你没理解我的意思吗？不要改我原来的代码。"
"不要添加任何调试功能。"
"不要做我没让你做的事。"
"我让你实现的功能在哪里？"
"你听不懂我说的话吗？"
"我只要一个函数。"
"我告诉过你参考我之前的代码。"
"请不要添加不必要的注释。"
"请不要修改我原始代码的基本逻辑。"
"帮我修改代码。"
"基于我的代码修改..."
"不要改我的变量名！！！"
"不要改原来的函数名！"
"不要乱动我的变量。"
"不要添加额外的功能。"
"不要只生成框架，生成完整的代码。"
```
这听起来可能有点夸张，但实际上，这些就是我们在日常工作中可能使用的提示词。由于大语言模型的上下文长度限制，或者有时因为它们的指令遵循能力不是很强，模型可能会忘记对话早些时候讨论的内容。
或者，由于训练数据集的风格，大模型倾向于以其训练数据的风格回答。例如，有些人说话很严肃，有些人喜欢添加很多修饰，而有些大模型喜欢在代码中添加很多注释或不必要的模块。
这就是为什么我们需要在开始时明确设定界限，例如：不要添加新模块，不要包含太多注释。每个大模型都有自己的风格，我们只能通过实际使用找到我们最喜欢的那个。
> 💡 什么是模型上下文？
>
> 模型上下文就像 AI 的 **短期记忆**。它是 AI 记住的当前对话中的所有文本。这使你能够提出后续问题并进行自然的对话，因为 AI “记得”你刚才在谈论什么。没有上下文，你问的每个问题都将是一个全新的、独立的对话。
>
> 每个模型都有不同的有效上下文长度，通常从 **32k 到 128k** tokens 不等。如果你想让大语言模型一次性阅读一篇很长的文章，或者有许多材料和对话希望 LLM 参考，你可能会发现 LLM 经常忘记长文本中的一些重要内容，或者你可能会注意到对话过程中主题逐渐偏移，这是由上下文限制引起的现象。
>
> 因此，对于模型，我们也关注上下文。然而，值得注意的是，上下文越长，资源消耗越大，收取的费用也越高。在行业中，有许多压缩上下文的方法，我们将在随后的学习中一一介绍。
> 💡 什么是指令遵循能力？
>
> 指令遵循能力指的是 **AI 理解并准确执行你提供的命令的能力**。它不仅仅是回答问题，而是根据你的具体要求完成任务，例如“将这篇文章总结为三个要点”、“用正式的语气写回复”或“翻译这个词并在句子中使用它”。
>
> 具有强指令遵循能力的模型将完全按照你的指示完成这些操作，而不会执行任何不必要的额外操作。
>
> 例如，当我们希望 LLM 将一篇文章总结为三个关键点时，我们不希望它给我们五个；当我们希望它从文章中提取某些关键要素（如作者、时间及发生的事件）时，我们不希望它遗漏任何要素。
>
> 因此，我们希望 LLM 拥有足够强的指令遵循能力，因为这带来了稳定性及 **可复现性**，使它们成为工业应用中的重要组成部分。
# 3. 使用 API：调用 LLM 和图像生成器
## 3.1 什么是 API
首先，**你需要知道什么是 API** [Extra Knowledge 2 - What is API](https://github.com/datawhalechina/easy-vibe/blob/main/docs/extra/extra2/extra2-what-is-api.md)
我们将尝试集成两个 API：一个是调用 DeepSeek LLM，另一个是调用 Seedream (即梦) 模型。这两个模型都很棒，性能出色。
在使用 API 的过程中，只有两个最重要的元素：
1. API key (密钥)
2. 官方文档示例
只要你能找到这两个，你就可以让 LLM 帮你修改并实现所有类型的 API 调用。
## 3.2 将 DeepSeek API 集成到 z.ai 中
### 什么是 DeepSeek
![](images/image16.png)
> 📚 信息引用自 [DeepSeek Wiki](https://en.wikipedia.org/wiki/DeepSeek)
>
> **杭州深度求索人工智能基础技术研究有限公司**（**Hangzhou DeepSeek Artificial Intelligence Basic Technology Research Co., Ltd.**），以 **DeepSeek** 为商号，是一家开发大语言模型（LLMs）的中国人工智能（AI）公司。DeepSeek 总部位于浙江杭州，由中国对冲基金幻方量化（High-Flyer）拥有并资助。DeepSeek 由幻方量化的联合创始人梁文锋于 2023 年 7 月创立，他也同时担任这两家公司的 CEO。该公司于 2025 年 1 月推出了同名聊天机器人及其 DeepSeek-R1 模型。
>
> 让我们看看 DeepSeek 在 GPQA 基准排名中与其他顶级模型的表现对比。值得注意的是，DeepSeek 是一个开源（每个人都可以从互联网下载模型）模型，而其他常见模型如 Grok、Google Gemini 和 ChatGPT 都是闭源的。正如我们所见，DeepSeek 已经很大程度上接近了第一梯队的模型。
>
> ![](images/image17.png)
>
> GPQA 是“研究生级 Google-Proof 问答基准”的缩写，这是一个用于科学问答任务的研究生级基准。以下是详细介绍。
>
> GPQA 包含 448 个多项选择题，涵盖生物学、物理学和化学的子领域，如量子力学、有机化学、分子生物学等。这些问题由 61 位持有博士学位或正在攻读博士学位的专家编写，并经过了严格的验证过程。
### 如何获取 deepseek API
我们将尝试根据我们已有的信息，让 z.ai 直接将 DeepSeek API 集成到项目中。
首先，我们需要在 DeepSeek 开放平台注册一个账户。
https://platform.deepseek.com/sign_up
然后，你会看到像这样的网页界面：
![](images/image18.png)
要使用 API，我们需要先充值 token。10 元人民币足够使用一段时间了！
![](images/image19.png)
点击“API KEYS”并在屏幕下方找到“create new API key”。你最终会得到一个像 `sk-8573341c39fc44315aadc071c53rh7d2` 这样的 API key。
![](images/image20.png)
一旦你获得了密钥，你就拥有了调用模型的权限。
此时，你可以直接阅读 [API 文档](https://api-docs.deepseek.com/)，它通常提供 curl 或 Python 的调用示例。
![](images/image21.png)
找到示例后，你可以将文档中与密钥相关的所有内容复制到 z.ai，并要求它尝试帮你集成 LLM。
![](images/image22.png)
![](images/image23.png)
自动集成可以在很短的时间内完成。我们可以询问它的操作员确认 DeepSeek API 是否已经在使用中。
![](images/image24.png)
或者，我们可以要求 z.ai 帮我们定位项目中调用 LLM 的部分。
然后我们可以独立确认是否正在使用 DeepSeek。具体来说，我们可以直接请求：`"告诉我项目中所有需要调用 LLM 的代码位置，我需要检查是否是 DeepSeek。"`，z.ai 将返回所有 API 调用的详细地址。
![](images/image25.png)
接下来，我们将简要介绍目前可用的三种最先进的图像生成模型。你可以根据自己的喜好选择一种集成到 z.ai 中。
## 3.3 将 SiliconFlow QwenImage API 集成到 z.ai 中
### 什么是 SiliconFlow
> [Silicon Flow (硅基流动)](https://cloud.siliconflow.com/me/models) 成立于 2023 年 8 月，是一家世界领先的 AI 能力提供商。它提供 SiliconCloud（具有自研推理加速的大模型云平台）和 BizyAir（用于 AI 图像生成的 ComfyUI 插件）等核心产品，为客户提供 AI 基础设施能力，拥有战略合作伙伴关系，并持有顶级行业认证。
>
> ![](images/image26.png)
### 什么是 QwenImage
> Qwen-Image 是一个强大的图像生成基础模型，能够进行复杂的文本渲染和精确的图像编辑。这是一个 20B MMDiT 图像基础模型，在复杂的文本渲染和精确的图像编辑方面取得了重大进展。实验表明，它在图像生成和编辑方面都具有很强的通用能力，在文本渲染方面表现尤为出色，尤其是中文。
>
> 从中文到英文，QwenImage 可以像 GPT-4o 或 Seedream 模型一样生成高质量的文本。
>
> ![](images/image27.png)
>
> ![](images/image28.png)
>
> ![](images/image29.png)
>
> ![](images/image30.png)
### 如何获取 SiliconFlow QwenImage API
https://cloud.siliconflow.com/me/models
查看 SiliconFlow 的官网。左侧有一个“Playground”部分，你可以在不进行 API 调用的情况下试用不同的模型。在网页顶部有一个“Filters”按钮；点击它可以筛选右侧的模型列表。
如果你选择“Image”，你将只看到当前支持的所有文生图模型。在这种情况下，我们将使用 Qwen/Qwen-Image。
![](images/image31.png)
要调用 API，首先我们需要点击左侧设置中的“API Keys”，然后点击“Create API Key”按钮生成一个 API key。记得保存这个 API key。
![](images/image32.png)
要查看可用余额，我们需要打开左侧设置中的“Payments”。在这里，你可以看到 1 美元的赠金。但是，如果你想使用 FLUX 文生图模型，你需要先充值账户。
https://cloud.siliconflow.com/me/account/ak
![](images/image33.png)
一切设置好后，我们需要参考相应的图像生成 API 文档。你可以在官方文档页面找到任何标记为“API Reference”的部分。点击它，然后导航到图像生成的 API 端点部分并找到相关的请求示例。
https://docs.siliconflow.com/en/userguide/introduction
![](images/image34.png)
```Bash
curl --request POST \
--url https://api.siliconflow.com/v1/images/generations \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "black-forest-labs/FLUX.1-Kontext-max",
"prompt": "an island near sea, with seagulls, moon shining over the sea, light house, boats int he background, fish flying over the sea"
}'
```
记得将你打算使用的模型和 API key 填入相应的字段。之后，你可以在计算机的命令行中使用该命令运行直接请求测试。
```Bash
curl --request POST \
--url https://api.siliconflow.com/v1/images/generations \
--header 'Authorization: Bearer sk-defrgqrgrganpncxxibfyzfocgafga' \
--header 'Content-Type: application/json' \
--data '{
"model": "Qwen/Qwen-Image",
"prompt": "an island near sea, with seagulls, moon shining over the sea, light house, boats int he background, fish flying over the sea"
}'
```
![](images/image35.png)
你可以将下面修改后的代码行发送给 z.ai，并要求它帮你创建一个前端测试演示。很快，你就能实现 SiliconFlow 的基本 API 调用。
![](images/image36.png)
## 3.4 将 Recraft API 集成到 z.ai 中
### 什么是 Recraft
> Recraft 是一款面向设计师、插画师和营销人员的 AI 工具——于 2022 年在美国成立，总部位于伦敦。它帮助生成/迭代视觉效果（图像、矢量艺术、3D 图形），具有高质量输出（任何文本大小/长度）、精确元素定位和品牌一致性设计等优势。受到 200 个国家/地区 300 多万用户（包括奥美、Netflix）的信任，并已创建了 3.5 亿多张图像，其团队旨在使其成为必备的设计师工具，确保创作者能够控制他们的 AI 辅助工作流程。
>
> ![](images/image37.png)
>
> ![](images/image38.png)
>
> ![](images/image39.png)
### 如何获取 Recraft API
首先，我们仍然需要找到重要的 API 入口以获取我们的 API key。 https://www.recraft.ai/profile/api
由于这里没有提供免费额度，我们需要自己充值 1,000 积分。这个网站支持支付宝和微信支付，所以很容易获得 1,000 积分（注意：不要充值超过必要的金额）。
![](images/image40.png)
之后，我们仍然遵循通常的方法：去官方文档找到相应的请求示例。
https://www.recraft.ai/docs/api-reference/getting-started
https://www.recraft.ai/docs/api-reference/usage
https://www.recraft.ai/docs/api-reference/examples#create-own-style-by-uploading-reference-images-and-use-them-for-generation
在这里，我们可以 ctrl+ A 选中全屏，直接复制整个内容并粘贴到 z.ai。
![](images/image41.png)
注意，在聊天窗口中，输入你的 API key 和文档内容就足够了；z.ai 会自动为你构建前端。
如果过程中出现错误，你可以直接将错误信息粘贴到聊天窗口，让 z.ai 帮你自动解决。
![](images/image42.png)
## 3.5 将 Seedream API 集成到 z.ai 中（针对中国用户）
### 什么是 Seedream 4.0
https://seed.bytedance.com/en/seedream4_0
![](images/image43.png)
> 也许你已经知道 Nano Banana（Google 开发），但你最好不要错过 Seedream。Seedream 4.0 是字节跳动打造的新一代图像创作模型。它将图像生成和图像编辑能力集成到一个统一的架构中。这使得它能够灵活处理复杂的多模态任务，如基于知识的生成、复杂推理和参考一致性。此外，它的推理速度比前代产品快得多，并且可以生成分辨率高达 4K 的令人惊叹的高清图像。
>
> ![](images/image44.png)
>
> ![](images/image45.png)
>
> ![](images/image46.png)
### 如何获取 Seedream API - 火山引擎 (Volcengine)（针对中国用户）
我们将逐步演示如何将 Seedream API 集成到 z.ai 示例中。
https://www.volcengine.com/experience/ark?launch=seedream
访问页面后，点击登录。
![](images/image47.png)
登录后，找到页面右上角的充值选项。
![](images/image48.png)
进行充值需要实名认证。
![](images/image49.png)
认证成功后，你可以充值 1 元用于测试。
https://console.volcengine.com/finance/fund/recharge
![](images/image50.png)
返回[初始界面](https://www.volcengine.com/experience/ark?launch=seedream)并点击 API 访问。
![](images/image51.png)
首先，创建一个 API key，然后点击选择选项。
![](images/image52.png)
这将带你进入第 2 步。在这里，你需要确认调用的服务是 Seedream 4.0，并复制提供的调用示例。
![](images/image53.png)
准备好 API key 和调用示例后，你可以直接将它们粘贴到 z.ai 中以生成前端交互演示。
重要提示：这里的默认示例相对复杂。记得禁用“添加水印”选项和“流式响应”选项，以确保不生成水印且不会发生请求失败。
![](images/image54.png)
输入提示词后，你将收到生成的结果。享受它吧！
![](images/image55.png)
# 让它更有趣
完成基本功能后，我们可以尝试给我们的程序添加一些新花样！如果你觉得蛇吃单词或字符的过程有点枯燥，你可以让蛇吃不同颜色的单词，并相应地改变蛇的颜色。
你还可以为“吃”的过程添加特效，或者引入触发特效的魔法单词——比如增加蛇的速度或大小。另一个想法是每当蛇吃一个单词时就让模型生成一首诗和一幅图，而不是等到它吃掉八个单词。
如果觉得这些有挑战性，你可以直接向语言模型求助！它可以提供创意建议，让你的游戏更有趣。试一试吧！
```JavaScript
1. "单词解锁世界" 机制
每当蛇吃掉一个单词，LLM 会对该单词进行诗意联想（例如，“树”→“森林”、“绿荫”），图像模型会即时为该单词生成一个小艺术品。这些图像逐渐拼凑成一个独特的、玩家创造的全景图，所以玩家每次游玩都在“作画和写诗”。
2. "诗歌拼图" 玩法
蛇吃掉的每个单词都会触发 LLM 生成简短的诗句，图像模型生成插图。这些诗句和图像像拼图一样组合在一起，在回合结束时形成一首 AI 协作的诗和画。
3. "魔法单词" & "故事分支"
特殊的“魔法单词”（例如，“风”、“夜”、“梦”）不仅触发 LLM 生成诗歌，还会改变场景的情绪或主题——将生成图像的风格转变为夜晚、暴风雨或梦幻般的氛围。
分支故事：LLM 在开始时给出一个主题或谜语（例如，“秋天的回忆”）。玩家的单词选择直接影响故事和诗歌的演变，图像模型实时更新背景和视觉效果。
4. "实时互动生成"
每个单词之后，LLM 生成一行对话或描述，游戏中的 NPC 可以对玩家“说话”，或者环境可以相应地改变。
蛇的外观或游戏中的障碍物可以根据吃掉的单词在视觉上发生变化，这要归功于图像模型。
5. "创作 & 分享"
玩家可以在会话结束时保存并分享他们 AI 创作的诗歌和图像，炫耀他们独特的“AI 协作”。
“最美诗歌+艺术”、“最有创意单词组合”等排行榜，鼓励重玩和创造力。
6. "按句贪吃蛇" 挑战
反向模式：LLM 给出一句诗或一个谜语，玩家必须引导蛇按顺序吃掉单词来重构句子。吃错单词会通过图像生成模型触发有趣或艺术性的后果。
7. "主题关卡" & "风格选择"
游戏开始时，玩家选择一个主题（例如，“童话”、“科幻”、“唐诗”），LLM 和图像模型都会调整单词选择、诗歌风格和视觉效果以匹配，使每次运行都感觉新鲜。
8. "现场共创"
当吃掉一个特殊单词时，LLM 可以提示玩家输入短语或选择风格，然后 AI 生成相应的诗句和插图，使其成为真正的人类-AI 共创。
9. "AI 彩蛋 & 成就"
某些单词组合被 LLM 识别为特殊主题或内部笑话（例如，“月亮”、“桂花”、“河岸”），触发稀有的诗句和插图，奖励探索。
10. "成长的故事"
随着蛇的成长，LLM 生成一个连续的故事诗，图像模型创建一个无缝的长卷或全景图，所以玩家同时在“写作、绘画和玩耍”。
```
此外，我们还可以要求 LLM 帮你直接生成项目级的提示词。在上一节中，我们只自己写了贪吃蛇游戏的提示词。现在让我们尝试让大模型生成一个带有整体框架和实现路径的提示词（你可以直接用 z.ai 生成）：
> 我想让 AI 生成一个网页贪吃蛇游戏，需要一个更完整的提示词，让生成结果更令人印象深刻和有趣。请生成相应的提示词。当前目标是：生成一个贪吃蛇游戏，需要实现吃不同单词生成诗歌的功能，并且应该包含图像生成模块。
z.ai 的回复将会是这样的：
![](images/image56.png)
我们可以使用这个提示词在全栈开发模式下重新生成项目：
![](images/image57.png)
![](images/image58.png)
# 更多参考案例
除了贪吃蛇（游戏），我们可以让想象力尽情驰骋。
创造任何我们想创造的东西，甚至尝试搞砸一切！然后重头再来！
```YAML
1. AI 艺术画廊平台
描述：一个展示 AI 生成艺术作品的在线画廊，用户可以上传、分享和评论 AI 艺术作品。
功能：用户账户系统、艺术作品上传和展示、评分系统、分类浏览、AI 生成工具集成。
技术亮点：React/Vue 前端、Node.js 后端、MongoDB 数据库、AI API 集成。
2. 复古游戏档案馆
描述：一个致敬经典游戏的网站，包含游戏历史、玩法指南和在线可玩复古游戏。
功能：游戏数据库、时间轴展示、在线模拟器、用户评论、游戏收藏功能。
技术亮点：响应式设计、WebGL/Canvas 游戏实现、RESTful API、用户认证系统。
3. 可持续生活追踪器
描述：一个帮助用户通过环保提示和社区挑战来追踪和减少碳足迹的网站。
功能：个人碳足迹计算器、目标设定、进度追踪、社区挑战、环保知识库。
技术亮点：数据可视化、移动端优化、社交功能、推送通知。
4. 虚拟厨房助手
描述：一个基于 AI 的烹饪指导平台，提供个性化食谱推荐和分步烹饪说明。
功能：食谱数据库、食材识别、个性化推荐、烹饪计时器、营养分析。
技术亮点：图像识别 API、机器学习推荐系统、语音控制、实时视频指导。
5. 地下音乐发现平台
描述：一个专注于独立和新兴艺术家的音乐流媒体平台，提供独特的发现体验。
功能：音乐流媒体、艺术家资料、个性化推荐、播放列表创建、社区评论。
技术亮点：音频流处理、推荐算法、社交功能、音乐可视化。
6. 极简任务管理系统
描述：一个具有禅意美学的任务管理工具，专注于简单和高效的任务组织。
功能：任务创建和分类、优先级设置、进度追踪、团队协作、数据分析。
技术亮点：极简 UI 设计、拖放功能、实时同步、跨平台兼容性。
7. 科幻写作工坊
描述：一个为科幻作家提供创意工具和灵感的平台，包括世界观构建辅助和角色开发工具。
功能：故事结构工具、角色资料、世界观构建模板、写作统计、社区反馈。
技术亮点：富文本编辑器、数据可视化、协作编辑、AI 辅助创作。
8. 个人知识图谱
描述：一个帮助用户构建个人知识网络，可视化并连接各种想法和信息的工具。
功能：节点创建和连接、标签系统、搜索功能、导入/导出工具、可视化图表。
技术亮点：图数据库、数据可视化算法、Markdown 支持、跨设备同步。
9. 虚拟植物园
描述：一个互动植物百科全书，用户可以探索植物世界并创建虚拟花园。
功能：植物数据库、3D 植物模型、生长模拟、园艺指南、社区展示。
技术亮点：3D 渲染、季节变化模拟、AR 集成、植物识别 API。
10. 编程挑战竞技场
描述：一个面向程序员的在线竞赛平台，具有各种难度级别的编程挑战。
功能：挑战问题、代码编辑器、自动评估、排行榜、学习路径。
技术亮点：代码沙箱环境、实时评估系统、算法可视化、社交学习功能。
```
还有... 如果你喜欢玩游戏，让我们一起尝试创造游戏吧！
```SQL
1. 3D 开放世界 RPG
描述：一个具有广阔开放世界、任务和角色成长的奇幻 RPG。
功能：昼夜循环、动态天气、技能树、多人合作、制作系统。
技术亮点：Three.js 或 Babylon.js 用于 3D 渲染、服务器端游戏逻辑、角色自定义、存档系统。
2. 第一人称射击 (FPS) 竞技场
描述：一个快节奏的多人 FPS，具有各种游戏模式和地图。
功能：团队死斗、夺旗、武器自定义、排位赛。
技术亮点：WebGL/Three.js 用于 3D 图形、多人网络代码、命中检测、语音聊天。
3. AI 国际象棋和多人游戏
描述：一个功能齐全的国际象棋平台，具有 AI 对手和在线对战功能。
功能：AI 难度级别、残局挑战、锦标赛模式、回放分析。
技术亮点：国际象棋逻辑库、WebSocket 用于实时对战、ELO 排名系统、反作弊。
4. 麻将在线多人游戏
描述：一个具有在线多人游戏和计分功能的传统麻将游戏。
功能：多种规则集、私人房间、排名系统、回放功能。
技术亮点：牌匹配逻辑、实时多人游戏、大厅系统、分数追踪。
5. 回合制策略游戏
描述：一个具有网格战斗和单位管理的战术策略游戏。
功能：战役模式、遭遇战、单位升级、战争迷雾、多人对战。
技术亮点：网格移动系统、AI 决策、回合同步、存档/读档系统。
6. 计时赛赛车游戏
描述：一个专注于计时赛和赛道记录的 3D 赛车游戏。
功能：多条赛道、汽车自定义、幽灵回放、排行榜。
技术亮点：3D 汽车物理、赛道编辑器、回放系统、在线排行榜。
7. 卡牌对战游戏 (卡组构建)
描述：一个策略卡牌游戏，玩家构建卡组并与对手战斗。
功能：卡牌收集、卡组构建、排位赛、赛季活动。
技术亮点：卡牌游戏逻辑、匹配系统、AI 对手、卡牌动画。
8. 大逃杀 (俯视 2D)
描述：一个俯视 2D 大逃杀游戏，具有缩小的游戏区域和战利品机制。
功能：单人和小队模式、武器多样性、局内事件、排行榜。
技术亮点：实时多人游戏、区域缩小逻辑、战利品生成系统、匹配。
9. 恐怖生存游戏 (第一人称)
描述：一个具有资源管理和逃生机制的第一人称恐怖游戏。
功能：氛围环境、解谜、敌人 AI、多重结局。
技术亮点：动态照明、声音设计、敌人寻路、存档系统。
10. 音乐节奏游戏 (3D)
描述：一个 3D 节奏游戏，玩家随着音乐节拍击打音符。
功能：多种难度级别、赛道编辑器、自定义歌曲支持、排行榜。
技术亮点：音频分析、节拍同步、3D 音符轨道、输入时机检测。
```
# 总结
这就是完整的教程！你可能需要 **4 小时** 才能完成所有内容并构建你自己的贪吃蛇游戏。不要着急——探索、实验并享受这个过程。
如果你有不同的游戏想法，那也很好。最重要的是开始构建。
祝你好运，欢迎来到 AI 原生创造力的世界 :)
# 📚 Assignment
- 完成一份属于自己的 AI 原生的贪吃蛇游戏。
- 若有余力，根据更多参考案例实现不同种类好玩的 AI 原生游戏。
docs/project/chapter1/images/image8.png
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 149 KiB

docs/project/chapter3/chapter3-getting-started-with-dify-and-its-knowledge-base-integration.md
+89 -88
View File
@@ -27,9 +27,9 @@
4. RAG 的实现方法与价值，为什么需要检索增强生成？ 4. RAG 的实现方法与价值，为什么需要检索增强生成？
5. 如何从 0 到 1 学会使用 Dify 和 AI IDE Trae (`Extra Knowledge 4 - What is AI IDE and Trae`)，包括搭建 智能体、工作流，并基于 Dify API 制作前端对话机器人网页程序。 5. 如何从 0 到 1 学会使用 Dify 和 AI IDE Trae (`Extra Knowledge 4 - What is AI IDE and Trae`)，包括搭建 智能体、工作流，并基于 Dify API 制作前端对话机器人网页程序。
* Dify 的基本使用原理与智能体、工作流制作方法，API 调用方法。 - Dify 的基本使用原理与智能体、工作流制作方法，API 调用方法。
* AI IDE 的使用方法，如何使用 AI IDE 编程。 - AI IDE 的使用方法，如何使用 AI IDE 编程。
* 一个可进行对话的前端网页智能体程序。 - 一个可进行对话的前端网页智能体程序。
# 1. 从对话到智能体 # 1. 从对话到智能体
@@ -77,10 +77,10 @@ RAG 的基本思路是：在用户提问时，系统首先从企业知识库中
完成搭建后，你可以尝试提出各类问题来检验它的能力，例如： 完成搭建后，你可以尝试提出各类问题来检验它的能力，例如：
* “我们产品A的最新版本有哪些主要功能升级？” - “我们产品A的最新版本有哪些主要功能升级？”
* “请根据员工手册，说明今年的年假制度是如何规定的？” - “请根据员工手册，说明今年的年假制度是如何规定的？”
* “在XX项目中，我们遇到的技术挑战‘XXX’是如何解决的？” - “在XX项目中，我们遇到的技术挑战‘XXX’是如何解决的？”
* “这篇论文中提到的核心研究方法是什么？” - “这篇论文中提到的核心研究方法是什么？”
你将亲身感受 RAG 技术如何将静态分散的文档资料，转化为一个精准的智能知识库，为各种场景提供高精度问答支持。 你将亲身感受 RAG 技术如何将静态分散的文档资料，转化为一个精准的智能知识库，为各种场景提供高精度问答支持。
@@ -220,7 +220,7 @@ Dify 是一个用于开发 LLM 应用的开源平台。它提供了直观的界
## 2.2 创建第一个 Dify Chatbot 应用 ## 2.2 创建第一个 Dify Chatbot 应用
访问 Dify 首页 [https://cloud.dify.ai/apps](https://cloud.dify.ai/apps) 并注册和登录后，选择 Studio，你会看到如下界面： 访问 Dify 首页 [https://cloud.dify.ai/apps](https://cloud.dify.ai/apps) 并注册和登录后，选择 Studio，你会看到如下界面：
![](images/image14.png) ![](images/image14.png)
@@ -276,13 +276,14 @@ Dify 能够灵活接入来自 OpenAI、Azure、Anthropic 等主流服务商的
3. 安装结束后，我们能够配置支持新的模型供应商，在设置里的模型提供商部分，我们可以看到目前支持的所有模型商： 3. 安装结束后，我们能够配置支持新的模型供应商，在设置里的模型提供商部分，我们可以看到目前支持的所有模型商：
![](images/image24.png) ![](images/image24.png)
4. 在开始使用前，需要先完成模型的配置。对于 OpenAI-API-compatible 插件，你可以点击 “Add Model” 来添加并配置任意模型。你可以在 “Model Type” 中选择该模型是LLM还是 Embedding，你需要确保模型的类型被正确配置。 4. 在开始使用前，需要先完成模型的配置。对于 OpenAI-API-compatible 插件，你可以点击 “Add Model” 来添加并配置任意模型。你可以在 “Model Type” 中选择该模型是LLM还是 Embedding，你需要确保模型的类型被正确配置。
你需要写入具体的模型名字、模型 endpoint URL 以及 API Key 才能确保模型启用，如果你初步觉得配置该参数麻烦，你可以直接跳到后者的 SiliconFLow 平台的 Key 配置，或者安装 OpenRouter 等第三方服务商插件进行简单的模型支持配置。（确保服务商内有剩余可使用额度） 你需要写入具体的模型名字、模型 endpoint URL 以及 API Key 才能确保模型启用，如果你初步觉得配置该参数麻烦，你可以直接跳到后者的 SiliconFLow 平台的 Key 配置，或者安装 OpenRouter 等第三方服务商插件进行简单的模型支持配置。（确保服务商内有剩余可使用额度）
![](images/image25.png) ![](images/image25.png)
对于 `SiliconFlow` 插件，只需要点击 Setup 配置 key 后即可使用 Embedding 和 Rerank 模型进行测试，你可以点击 Get you API Key from SiliconFlow 获得鉴权密钥。 对于 `SiliconFlow` 插件，只需要点击 Setup 配置 key 后即可使用 Embedding 和 Rerank 模型进行测试，你可以点击 Get you API Key from SiliconFlow 获得鉴权密钥。
![](images/image26.png) ![](images/image26.png)
5. 配置完成后，你可以点击模型列表查看当前支持多少模型，此时已经完成了基础模型的全部配置。 5. 配置完成后，你可以点击模型列表查看当前支持多少模型，此时已经完成了基础模型的全部配置。
![](images/image27.png) ![](images/image27.png)
@@ -310,11 +311,11 @@ Dify 能够灵活接入来自 OpenAI、Azure、Anthropic 等主流服务商的
首先在 **General** 设置中，你可以把这里理解成“文本切分规则”的设置区域。因为我们需要把很长的文本切分成小块，所以必须先定义切分规则。在入门阶段，你只需要关注 **maximum chunk length（最大切分长度）** 。可以尝试设置为 512、2048 或 4096，然后点击 **Preview Chunk** 预览不同设置下的效果。 首先在 **General** 设置中，你可以把这里理解成“文本切分规则”的设置区域。因为我们需要把很长的文本切分成小块，所以必须先定义切分规则。在入门阶段，你只需要关注 **maximum chunk length（最大切分长度）** 。可以尝试设置为 512、2048 或 4096，然后点击 **Preview Chunk** 预览不同设置下的效果。
你也可以调整 **Chunk overlap（切片重叠）** 选项。它决定相邻片段之间是否会保留一部分重叠内容。适当的重叠有助于避免重要信息被拆到不同片段而难以理解。 你也可以调整 **Chunk overlap（切片重叠）** 选项。它决定相邻片段之间是否会保留一部分重叠内容。适当的重叠有助于避免重要信息被拆到不同片段而难以理解。
![](images/image32.png) ![](images/image32.png)
在设置中还有一个选项叫做 **Chunk using Q&A format in English** 。启用后，系统会使用大语言模型，将知识库的一部分内容转换成问答形式来存储，这在某些场景下可以显著提升检索效果。 在设置中还有一个选项叫做 **Chunk using Q&A format in English** 。启用后，系统会使用大语言模型，将知识库的一部分内容转换成问答形式来存储，这在某些场景下可以显著提升检索效果。
在真实业务中，根据场景选择合适的切分策略，能够更好地优化检索结果，保证查询能够返回你期望的信息。 在真实业务中，根据场景选择合适的切分策略，能够更好地优化检索结果，保证查询能够返回你期望的信息。
@@ -326,7 +327,7 @@ Embedding 模型的选择会显著影响最终的检索效果（例如匹配准
![](images/image33.png) ![](images/image33.png)
在此处，你还会看到另一个模型设置叫做 **Rerank model** ，默认值是 **Jina-rerank-m0** 。（如果你非校园内的学生，此时你可能会看到 Rerank 模型缺失的报错，你需要在模型处配置 rerank 模型才能在此处启用使用） 在此处，你还会看到另一个模型设置叫做 **Rerank model** ，默认值是 **Jina-rerank-m0** 。（如果你非校园内的学生，此时你可能会看到 Rerank 模型缺失的报错，你需要在模型处配置 rerank 模型才能在此处启用使用）
Rerank 模型的主要作用，是对“初步筛选出的候选结果”进行二次、更精细的排序，让和用户需求最匹配的结果排在更靠前的位置，从而显著提升最终结果的相关性和用户体验。 Rerank 模型的主要作用，是对“初步筛选出的候选结果”进行二次、更精细的排序，让和用户需求最匹配的结果排在更靠前的位置，从而显著提升最终结果的相关性和用户体验。
@@ -336,11 +337,11 @@ Rerank 模型的主要作用，是对“初步筛选出的候选结果”进行
![](images/image34.png) ![](images/image34.png)
当所有设置完成后，点击 **Save & Process** ，系统就会进入知识库向量化阶段。在这一阶段，Embedding 模型会把切分后的文本转换为向量表示。 当所有设置完成后，点击 **Save & Process** ，系统就会进入知识库向量化阶段。在这一阶段，Embedding 模型会把切分后的文本转换为向量表示。
![](images/image35.png) ![](images/image35.png)
处理完成后，点击 **Go to document** ，可以查看已经处理完毕并存储好的知识库内容。 处理完成后，点击 **Go to document** ，可以查看已经处理完毕并存储好的知识库内容。
![](images/image36.png) ![](images/image36.png)
@@ -459,11 +460,11 @@ Dify 中提供了多种节点，你可以先了解每个节点的基本功能。
此类节点负责工作流中的核心流程。 此类节点负责工作流中的核心流程。
* LLM节点：核心计算单元，用于调用大语言模型。其配置重点在于提示词工程与参数调优，将业务问题转化为模型的执行指令。 - LLM节点：核心计算单元，用于调用大语言模型。其配置重点在于提示词工程与参数调优，将业务问题转化为模型的执行指令。
* Knowledge Retrieval 节点：知识检索单元，负责从预设知识库、外部权威数据源中检索与业务问题相关的信息，为 LLM 节点提供精准的知识支撑，帮助减少大语言模型输出的 “幻觉” 问题。 - Knowledge Retrieval 节点：知识检索单元，负责从预设知识库、外部权威数据源中检索与业务问题相关的信息，为 LLM 节点提供精准的知识支撑，帮助减少大语言模型输出的 “幻觉” 问题。
* Answer 节点：结果输出单元，负责接收 LLM 处理后的内容，将其整理为符合业务场景需求的最终成果形式。其配置重点在于输出格式的定义（如话术模板、排版规范）。 - Answer 节点：结果输出单元，负责接收 LLM 处理后的内容，将其整理为符合业务场景需求的最终成果形式。其配置重点在于输出格式的定义（如话术模板、排版规范）。
* Agent节点：高阶决策单元。它不仅调用模型，还可实施多步骤规划、自主选择并调用外部工具，适用于需要动态决策的复杂任务链。 - Agent节点：高阶决策单元。它不仅调用模型，还可实施多步骤规划、自主选择并调用外部工具，适用于需要动态决策的复杂任务链。
* Question Classifier 节点：问题分类单元，负责对输入的业务问题进行类型识别与归类（比如按问题意图、主题领域等维度划分），帮助后续流程精准匹配对应的处理节点（如不同类型的问题适配不同的 LLM 提示词或工具链）。 - Question Classifier 节点：问题分类单元，负责对输入的业务问题进行类型识别与归类（比如按问题意图、主题领域等维度划分），帮助后续流程精准匹配对应的处理节点（如不同类型的问题适配不同的 LLM 提示词或工具链）。
2. 逻辑与流程控制节点 2. 逻辑与流程控制节点
@@ -471,22 +472,22 @@ Dify 中提供了多种节点，你可以先了解每个节点的基本功能。
此类节点定义工作流的执行路径与规则。 此类节点定义工作流的执行路径与规则。
* 条件节点：如 `IF/ELSE`，通过布尔判断实现流程分支。其设计关键在于条件表达式的严谨性，确保逻辑覆盖所有业务场景。 - 条件节点：如 `IF/ELSE`，通过布尔判断实现流程分支。其设计关键在于条件表达式的严谨性，确保逻辑覆盖所有业务场景。
* Iteration 节点：作为无状态的批量并行处理单元，它专为子任务间无数据依赖、可独立处理的场景设计，例如批量翻译段落、并行审核多条内容或同时生成多份报告。该节点会接收一个输入数组并自动分片，将每个元素分发至相同处理链路并行执行，用户可在迭代体内通过 {{item}} 访问当前元素、{{index}} 获取其索引，输出则会自动聚合成结果数组；配置时需重点设定并行度以平衡效率与系统负载，同时通过重试策略（如重试次数、间隔）和失败处理（如记录日志、返回默认值）保障批量作业的稳定性。 - Iteration 节点：作为无状态的批量并行处理单元，它专为子任务间无数据依赖、可独立处理的场景设计，例如批量翻译段落、并行审核多条内容或同时生成多份报告。该节点会接收一个输入数组并自动分片，将每个元素分发至相同处理链路并行执行，用户可在迭代体内通过 {{item}} 访问当前元素、{{index}} 获取其索引，输出则会自动聚合成结果数组；配置时需重点设定并行度以平衡效率与系统负载，同时通过重试策略（如重试次数、间隔）和失败处理（如记录日志、返回默认值）保障批量作业的稳定性。
* Loop 节点：有状态的递归迭代器，适用于结果依赖前一轮输出的场景，比如多轮参数调优、递归式内容优化（如反复修订文案直至满意）及依赖上次结果的链式计算。其核心是 “状态变量”，需在循环开始前初始化（如当前迭代次数、中间计算结果），并在每轮迭代中明确更新以作为下一轮输入；为防止无限循环，必须定义终止条件（包括基于计数器的 “最多循环 10 次”、基于结果判定的 “满意度评分 > 9”、基于外部信号的 “检测到‘停止’输入”），同时需设置循环超时配置，并规划异常处理路径（如跳出循环或重置状态后重试），确保流程稳定运行。 - Loop 节点：有状态的递归迭代器，适用于结果依赖前一轮输出的场景，比如多轮参数调优、递归式内容优化（如反复修订文案直至满意）及依赖上次结果的链式计算。其核心是 “状态变量”，需在循环开始前初始化（如当前迭代次数、中间计算结果），并在每轮迭代中明确更新以作为下一轮输入；为防止无限循环，必须定义终止条件（包括基于计数器的 “最多循环 10 次”、基于结果判定的 “满意度评分 > 9”、基于外部信号的 “检测到‘停止’输入”），同时需设置循环超时配置，并规划异常处理路径（如跳出循环或重置状态后重试），确保流程稳定运行。
3. 数据操作与集成节点 3. 数据操作与集成节点
![](images/image57.png) ![](images/image57.png)
* Code 节点：代码处理单元，负责在工作流中执行自定义代码逻辑，可实现数据格式转换、复杂计算等个性化处理需求。其配置重点在于代码语法的正确性与执行环境的适配。 - Code 节点：代码处理单元，负责在工作流中执行自定义代码逻辑，可实现数据格式转换、复杂计算等个性化处理需求。其配置重点在于代码语法的正确性与执行环境的适配。
* Template 节点：模板处理单元，负责将动态数据填充至预设模板中，生成符合格式要求的内容（如定制化文案、报告框架）。其配置重点在于模板语法的编写与变量映射规则的设置。 - Template 节点：模板处理单元，负责将动态数据填充至预设模板中，生成符合格式要求的内容（如定制化文案、报告框架）。其配置重点在于模板语法的编写与变量映射规则的设置。
* Variable Aggregator 节点：变量聚合单元，负责收集工作流中多个节点输出的变量数据，将分散的变量整合为统一数据集。其配置重点在于聚合的变量范围与数据合并规则的定义。 - Variable Aggregator 节点：变量聚合单元，负责收集工作流中多个节点输出的变量数据，将分散的变量整合为统一数据集。其配置重点在于聚合的变量范围与数据合并规则的定义。
* Doc Extractor 节点：文档提取单元，负责从 PDF、Word 等各类文档中提取文本、表格等关键内容，转化为工作流可处理的结构化数据。其配置重点在于文档类型的适配与提取内容的筛选规则。 - Doc Extractor 节点：文档提取单元，负责从 PDF、Word 等各类文档中提取文本、表格等关键内容，转化为工作流可处理的结构化数据。其配置重点在于文档类型的适配与提取内容的筛选规则。
* Variable Assigner 节点：变量赋值单元，负责定义、初始化或更新工作流中的变量，为流程内的数据传递提供载体。其配置重点在于变量的命名、数据类型及赋值逻辑的设定。 - Variable Assigner 节点：变量赋值单元，负责定义、初始化或更新工作流中的变量，为流程内的数据传递提供载体。其配置重点在于变量的命名、数据类型及赋值逻辑的设定。
* Parameter Extractor 节点：参数提取单元，负责从用户请求、接口返回等输入内容中提取指定参数，将非结构化信息转化为结构化数据。其配置重点在于提取规则（如正则表达式、JSON 路径）的配置。 - Parameter Extractor 节点：参数提取单元，负责从用户请求、接口返回等输入内容中提取指定参数，将非结构化信息转化为结构化数据。其配置重点在于提取规则（如正则表达式、JSON 路径）的配置。
* HTTP Request 节点：HTTP 请求单元，负责向外部系统接口发起 HTTP 请求（含 GET、POST 等方法），实现工作流与外部服务的数据交互。其配置重点在于请求地址、请求方法及参数 /headers 的设置。 - HTTP Request 节点：HTTP 请求单元，负责向外部系统接口发起 HTTP 请求（含 GET、POST 等方法），实现工作流与外部服务的数据交互。其配置重点在于请求地址、请求方法及参数 /headers 的设置。
* List Operator 节点：列表操作单元，负责对数组、列表类型的数据进行处理（如过滤、排序、拆分），调整数据结构以适配后续流程。其配置重点在于操作类型（如过滤条件、排序规则）的定义。 - List Operator 节点：列表操作单元，负责对数组、列表类型的数据进行处理（如过滤、排序、拆分），调整数据结构以适配后续流程。其配置重点在于操作类型（如过滤条件、排序规则）的定义。
### 2.6.2 常见工具介绍 ### 2.6.2 常见工具介绍
@@ -496,13 +497,13 @@ Dify 中提供了多种节点，你可以先了解每个节点的基本功能。
在左侧或右侧的节点面板中，可以查看所有可用工具节点，也可以通过插件市场扩展更多工具能力。简单介绍几个常见工具的作用： 在左侧或右侧的节点面板中，可以查看所有可用工具节点，也可以通过插件市场扩展更多工具能力。简单介绍几个常见工具的作用：
* 网络搜索工具 - 网络搜索工具
以 Tavily Search 为代表，为大模型提供面向 AI 优化的实时检索能力。 以 Tavily Search 为代表，为大模型提供面向 AI 优化的实时检索能力。
它会返回结构化的搜索结果（如标题、摘要、链接等），可以直接作为 LLM 提示词的一部分，用于回答最新资讯类或需要权威依据的问题。 它会返回结构化的搜索结果（如标题、摘要、链接等），可以直接作为 LLM 提示词的一部分，用于回答最新资讯类或需要权威依据的问题。
* 数据处理工具 - 数据处理工具
例如 JSON Process 插件，用于对 JSON 数据进行查询、筛选、转换、合并等高级操作。 例如 JSON Process 插件，用于对 JSON 数据进行查询、筛选、转换、合并等高级操作。
在处理复杂 API 响应或多层嵌套数据时，你可以将“数据清洗 + 重组”的逻辑交给该工具，从而简化在 Code 节点中频繁手写解析代码的工作。 在处理复杂 API 响应或多层嵌套数据时，你可以将“数据清洗 + 重组”的逻辑交给该工具，从而简化在 Code 节点中频繁手写解析代码的工作。
* 格式处理工具 - 格式处理工具
如 Markdown Exporter，可以将生成内容按指定格式导出，例如 Markdown 文档、特定排版模板等，方便后续用于展示、汇报或集成到其他系统。 如 Markdown Exporter，可以将生成内容按指定格式导出，例如 Markdown 文档、特定排版模板等，方便后续用于展示、汇报或集成到其他系统。
你可以在工具列表中看到这些插件的安装量和简介，初期可优先尝试安装“Featured / 推荐”里的工具，往往覆盖了最常见的业务场景。 你可以在工具列表中看到这些插件的安装量和简介，初期可优先尝试安装“Featured / 推荐”里的工具，往往覆盖了最常见的业务场景。
@@ -524,32 +525,32 @@ Dify 中提供了多种节点，你可以先了解每个节点的基本功能。
本节的目标是让系统能处理一个餐饮场景下的多类对话。你可以跟着操作做一遍加深印象。首先需要做的是定义场景为意图分类： 本节的目标是让系统能处理一个餐饮场景下的多类对话。你可以跟着操作做一遍加深印象。首先需要做的是定义场景为意图分类：
* **下单购买 (buy_food)** ：用户表达明确的购买意愿。 - **下单购买 (buy_food)** ：用户表达明确的购买意愿。
* *例如：“给我来一份炸鸡，再加一杯可乐。”* - _例如：“给我来一份炸鸡，再加一杯可乐。”_
* **抱怨投诉 (complain)** ：用户在表达不满、催促或负面反馈。 - **抱怨投诉 (complain)** ：用户在表达不满、催促或负面反馈。
* *例如：“你们也太慢了吧？等一个小时了。”* - _例如：“你们也太慢了吧？等一个小时了。”_
* **闲聊咨询 (chitchat)** ：用户在进行开放式询问、寻求建议，但无明确下单指令。 - **闲聊咨询 (chitchat)** ：用户在进行开放式询问、寻求建议，但无明确下单指令。
* *例如：“今天吃什么好呢，你有什么推荐吗？”* - _例如：“今天吃什么好呢，你有什么推荐吗？”_
* **其他意图 (other)** ：用户的输入与餐饮场景无关。 - **其他意图 (other)** ：用户的输入与餐饮场景无关。
* *例如：“帮我写个搞笑文案发朋友圈。”* - _例如：“帮我写个搞笑文案发朋友圈。”_
针对这四种意图，我们为系统预设了四种不同的“沟通人格”，分别由四个独立的 LLM 节点承载，每个节点都需要由具有不同人设的 LLM 进行扮演。 针对这四种意图，我们为系统预设了四种不同的“沟通人格”，分别由四个独立的 LLM 节点承载，每个节点都需要由具有不同人设的 LLM 进行扮演。
* **下单助手 (LLM_BuyFood)** ：专业、高效，核心任务是确认订单细节，并主动补全缺失信息。 - **下单助手 (LLM_BuyFood)** ：专业、高效，核心任务是确认订单细节，并主动补全缺失信息。
* **客服专家 (LLM_Complain)** ：共情、稳重，首要任务是安抚用户情绪，并提供清晰的解决方案。 - **客服专家 (LLM_Complain)** ：共情、稳重，首要任务是安抚用户情绪，并提供清晰的解决方案。
* **聊天伙伴 (LLM_Chitchat)** ：轻松、友好，旨在提供个性化推荐，引导潜在消费。 - **聊天伙伴 (LLM_Chitchat)** ：轻松、友好，旨在提供个性化推荐，引导潜在消费。
* **礼貌门卫 (LLM_Other)** ：专注、边界清晰，负责将偏离主题的对话礼貌地引导回核心业务。 - **礼貌门卫 (LLM_Other)** ：专注、边界清晰，负责将偏离主题的对话礼貌地引导回核心业务。
#### 工作流编排设计 #### 工作流编排设计
接下来我们进行工作流的编排设定，决定大概需要有哪些工作流节点。对于新手而言，很难想到需要有哪些节点能被用到（对于老手来说也懒得自己思考，用大模型给建议通常是最快最好的选择），所以我们能够使用大模型给出对应的编排建议，其核心节点结构如下： 接下来我们进行工作流的编排设定，决定大概需要有哪些工作流节点。对于新手而言，很难想到需要有哪些节点能被用到（对于老手来说也懒得自己思考，用大模型给建议通常是最快最好的选择），所以我们能够使用大模型给出对应的编排建议，其核心节点结构如下：
* Start (起点)：作为数据入口，负责接收用户的原始输入 `user_text`。 - Start (起点)：作为数据入口，负责接收用户的原始输入 `user_text`。
* Question Classifier (意图分类器)：工作流的“大脑”与“调度中心”。它负责对 `user_text` 进行分析，并从我们预设的四种意图标签中选择最匹配的一个。 - Question Classifier (意图分类器)：工作流的“大脑”与“调度中心”。它负责对 `user_text` 进行分析，并从我们预设的四种意图标签中选择最匹配的一个。
* Condition (条件分支)：扮演“分流阀”的角色。它根据分类器输出的意图标签，决定接下来将任务导向哪一个专处理路径。 - Condition (条件分支)：扮演“分流阀”的角色。它根据分类器输出的意图标签，决定接下来将任务导向哪一个专处理路径。
* 四个并行的 LLM 节点 (LLM_BuyFood, LLM_Complain, LLM_Chitchat, LLM_Other)：这是四个独立的“专家处理单元”。每个节点都接收原始问题，但依据自身独特的 System Prompt（系统提示词）生成风格和目标截然不同的回复。 - 四个并行的 LLM 节点 (LLM_BuyFood, LLM_Complain, LLM_Chitchat, LLM_Other)：这是四个独立的“专家处理单元”。每个节点都接收原始问题，但依据自身独特的 System Prompt（系统提示词）生成风格和目标截然不同的回复。
* Variable Aggregator (变量聚合器)：在多条路径处理完成后，需要一个“汇集点”。此节点将四个分支中唯一被激活并产生结果的回复，收束成一个统一的变量 `final_reply`，确保了输出结构的稳定性。 - Variable Aggregator (变量聚合器)：在多条路径处理完成后，需要一个“汇集点”。此节点将四个分支中唯一被激活并产生结果的回复，收束成一个统一的变量 `final_reply`，确保了输出结构的稳定性。
* Output (终点)：作为最终的出口，负责将意图标签、原始问题、以及经过处理生成的回复，以结构化的形式（如 JSON）统一输出，便于后续系统调用或调试分析。 - Output (终点)：作为最终的出口，负责将意图标签、原始问题、以及经过处理生成的回复，以结构化的形式（如 JSON）统一输出，便于后续系统调用或调试分析。
#### 工作流编排实现 #### 工作流编排实现
@@ -567,10 +568,10 @@ Dify 中提供了多种节点，你可以先了解每个节点的基本功能。
随后我们需要点击输入节点后的 + 符号，选择 Question Classifier 节点添加，并且我们需为其配置四类标签，并为每个标签提供清晰的描述和示例。 随后我们需要点击输入节点后的 + 符号，选择 Question Classifier 节点添加，并且我们需为其配置四类标签，并为每个标签提供清晰的描述和示例。
* `buy_food`: 用户明确想买吃的、点餐、下单。 - `buy_food`: 用户明确想买吃的、点餐、下单。
* `complain`: 用户在抱怨、吐槽、发脾气，通常带有不满情绪。 - `complain`: 用户在抱怨、吐槽、发脾气，通常带有不满情绪。
* `chitchat`: 用户在闲聊、讨论吃什么、咨询推荐。 - `chitchat`: 用户在闲聊、讨论吃什么、咨询推荐。
* `other`: 与餐饮场景无关，或难以判断的内容。 - `other`: 与餐饮场景无关，或难以判断的内容。
此外，你还需要在 ADVANCED SETTING 中写入提示词，让大模型能够正确根据用户输入进行分类测试。示例提示词如下： 此外，你还需要在 ADVANCED SETTING 中写入提示词，让大模型能够正确根据用户输入进行分类测试。示例提示词如下：
@@ -590,19 +591,19 @@ Dify 中提供了多种节点，你可以先了解每个节点的基本功能。
接下来，我们需要给分类器接上后续的大模型输出，例如，当 `label` 等于 `"buy_food"` 时，工作流便会精确地流向 `LLM_BuyFood` 节点。我们需要新建四个 LLM 节点，并设置不同的 System Prompt ；不同 System Prompt 的差异决定了它们不同的回应方式。 接下来，我们需要给分类器接上后续的大模型输出，例如，当 `label` 等于 `"buy_food"` 时，工作流便会精确地流向 `LLM_BuyFood` 节点。我们需要新建四个 LLM 节点，并设置不同的 System Prompt ；不同 System Prompt 的差异决定了它们不同的回应方式。
* LLM_BuyFood (点餐助手)： - LLM_BuyFood (点餐助手)：
你是一个点餐助手。要求：1. 确认用户想点的内容。2. 如果信息不完整，友好地补充询问。3. 语气礼貌简洁。 你是一个点餐助手。要求：1. 确认用户想点的内容。2. 如果信息不完整，友好地补充询问。3. 语气礼貌简洁。
* LLM_Complain (客服专家)： - LLM_Complain (客服专家)：
你是一个餐饮客服，专门处理抱怨。要求：1. 真诚道歉。2. 简要说明可能的原因（不推卸责任）。3. 给出清晰的下一步解决方案。 你是一个餐饮客服，专门处理抱怨。要求：1. 真诚道歉。2. 简要说明可能的原因（不推卸责任）。3. 给出清晰的下一步解决方案。
* LLM_Chitchat (聊天伙伴)： - LLM_Chitchat (聊天伙伴)：
你是一个帮人选吃的的聊天小助手。要求：1. 用轻松友好的语气。2. 给出 1~3 个简单推荐。3. 如果用户没有偏好，就给出不同风格的选择。 你是一个帮人选吃的的聊天小助手。要求：1. 用轻松友好的语气。2. 给出 1~3 个简单推荐。3. 如果用户没有偏好，就给出不同风格的选择。
* LLM_Other (礼貌门卫)： - LLM_Other (礼貌门卫)：
你是一个餐饮点餐小助手，只擅长跟‘吃’相关的话题。当用户说的话无关时：1. 礼貌说明自己的能力范围。2. 引导用户回到主场景。 你是一个餐饮点餐小助手，只擅长跟‘吃’相关的话题。当用户说的话无关时：1. 礼貌说明自己的能力范围。2. 引导用户回到主场景。
@@ -618,9 +619,9 @@ Dify 中提供了多种节点，你可以先了解每个节点的基本功能。
接下来我们需要对所有的输出进行聚合，最后得到我们想要的结果，包含用户的输入、分类、以及回复。由于我们使用的是 Workflow 而不是 Chatflow，故没有 Answer 节点选择进行结果的聚合，我们能够选择其他节点变相实现结果的聚合与输出，此时选择 Template 节点，在变量部分指定用户意图分类结果、用户的输入值、变量聚合的最终回复，并且在 CODE 中写入最后回复的 json 格式模板，我们可以得到： 接下来我们需要对所有的输出进行聚合，最后得到我们想要的结果，包含用户的输入、分类、以及回复。由于我们使用的是 Workflow 而不是 Chatflow，故没有 Answer 节点选择进行结果的聚合，我们能够选择其他节点变相实现结果的聚合与输出，此时选择 Template 节点，在变量部分指定用户意图分类结果、用户的输入值、变量聚合的最终回复，并且在 CODE 中写入最后回复的 json 格式模板，我们可以得到：
* `intent` ← `class_name` - `intent` ← `class_name`
* `original_text` ← `user_text` - `original_text` ← `user_text`
* `final_reply` ← `variable_aggregator` - `final_reply` ← `variable_aggregator`
```Plain ```Plain
{ {
@@ -640,18 +641,18 @@ Dify 中提供了多种节点，你可以先了解每个节点的基本功能。
大功告成，我们可以尝试运行这套工作流的效果。它能根据不同的输入，展现出截然不同的行为模式： 大功告成，我们可以尝试运行这套工作流的效果。它能根据不同的输入，展现出截然不同的行为模式：
* 输入 (点餐): "给我来一份香辣鸡腿堡套餐，大杯可乐。" - 输入 (点餐): "给我来一份香辣鸡腿堡套餐，大杯可乐。"
* 路径: `buy_food` → `LLM_BuyFood` - 路径: `buy_food` → `LLM_BuyFood`
* 输出 reply: "好的，一份香辣鸡腿堡套餐和大杯可乐已为您记录。请问套餐里的薯条需要更换吗？" - 输出 reply: "好的，一份香辣鸡腿堡套餐和大杯可乐已为您记录。请问套餐里的薯条需要更换吗？"
* 输入 (抱怨): "你们也太慢了吧？我都等一个多小时了！" - 输入 (抱怨): "你们也太慢了吧？我都等一个多小时了！"
* 路径: `complain` → `LLM_Complain` - 路径: `complain` → `LLM_Complain`
* 输出 reply: "非常抱歉让您等了这么久，这确实是我们的疏忽，给您带来了很不好的体验。我们正在紧急核实您的订单配送情况，并会为您申请相应的补偿，感谢您的耐心与反馈。" - 输出 reply: "非常抱歉让您等了这么久，这确实是我们的疏忽，给您带来了很不好的体验。我们正在紧急核实您的订单配送情况，并会为您申请相应的补偿，感谢您的耐心与反馈。"
* 输入 (闲聊): "今天吃什么比较健康？" - 输入 (闲聊): "今天吃什么比较健康？"
* 路径: `chitchat` → `LLM_Complain` - 路径: `chitchat` → `LLM_Complain`
* 输出 reply: "追求健康的话，可以试试我们的轻食沙拉系列，或者烤鸡胸肉配时蔬。您是喜欢口味清淡一些还是稍微丰富一点的呢？我可以给您更具体的推荐。" - 输出 reply: "追求健康的话，可以试试我们的轻食沙拉系列，或者烤鸡胸肉配时蔬。您是喜欢口味清淡一些还是稍微丰富一点的呢？我可以给您更具体的推荐。"
* 输入 (无关内容): "帮我想个明天开会的笑话。" - 输入 (无关内容): "帮我想个明天开会的笑话。"
* 路径: `other` → `LLM_Other` - 路径: `other` → `LLM_Other`
* 输出 reply: "这听起来是个有趣的挑战！不过我主要是个美食推荐和点餐助手。如果您需要点些什么来犒劳一下辛苦工作的自己，我随时可以帮忙！" - 输出 reply: "这听起来是个有趣的挑战！不过我主要是个美食推荐和点餐助手。如果您需要点些什么来犒劳一下辛苦工作的自己，我随时可以帮忙！"
> 隐藏 Bug ：需要说明的是，若你遇到与 aggregation group 相关的奇怪问题，这大概率是 Dify 的一个内置 bug。可能在特定操作下被触发；如果你曾经开启又关闭过 AGGREGATION GROUP，系统可能生成过 group 配置且残留了相关异常参数，即便现在开关看起来是关闭的，这些残留配置也可能导致问题，比如出现 `any` 相关参数的报错。此时你只需要删除该节点并重新创建即可。 > 隐藏 Bug ：需要说明的是，若你遇到与 aggregation group 相关的奇怪问题，这大概率是 Dify 的一个内置 bug。可能在特定操作下被触发；如果你曾经开启又关闭过 AGGREGATION GROUP，系统可能生成过 group 配置且残留了相关异常参数，即便现在开关看起来是关闭的，这些残留配置也可能导致问题，比如出现 `any` 相关参数的报错。此时你只需要删除该节点并重新创建即可。
@@ -783,7 +784,7 @@ curl -X POST 'http://{DIFY_API_URL}/v1/chat-messages' \
{ {
"event": "message", "event": "message",
"task_id": "c3800678-a077-43df-a102-53f23ed20b88", "task_id": "c3800678-a077-43df-a102-53f23ed20b88",
"id": "9da23599-e713-473b-982c-4328d4f5c78a", "id": "9da23599-e713-473b-982c-4328d4f5c78a",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
@@ -888,25 +889,25 @@ curl -X POST 'http://{DIFY_API_URL}/v1/chat-messages' \
## 3.3 学习生活工作流 ## 3.3 学习生活工作流
1. 学术论文深度解析与笔记生成器（复杂） 1. 学术论文深度解析与笔记生成器（复杂）
1. 思路：上传论文PDF，自动生成结构化笔记。 1. 思路：上传论文PDF，自动生成结构化笔记。
2. 实现：`Start` 上传PDF -> `Document Extractor` 提取全文 -> 并行多个 `LLM` 节点分工总结摘要、方法、发现、参考文献 -> `Variable Aggregator` 汇总 -> `Answer` 输出Markdown笔记。复杂度在于并行处理长文本的不同部分。 2. 实现：`Start` 上传PDF -> `Document Extractor` 提取全文 -> 并行多个 `LLM` 节点分工总结摘要、方法、发现、参考文献 -> `Variable Aggregator` 汇总 -> `Answer` 输出Markdown笔记。复杂度在于并行处理长文本的不同部分。
2. 个性化旅行计划定制师（中等）
2. 个性化旅行计划定制师（中等）
1. 思路：根据用户偏好，自动规划详尽行程。 1. 思路：根据用户偏好，自动规划详尽行程。
2. 实现：`Start` 输入需求（目的地、天数、预算、兴趣）-> `Tool` 节点调用搜索引擎或地图API获取地点信息 -> `LLM` 整合信息，设计每日行程（含时间、活动、预算估算）。复杂度在于外部信息获取与结构化规划。 2. 实现：`Start` 输入需求（目的地、天数、预算、兴趣）-> `Tool` 节点调用搜索引擎或地图API获取地点信息 -> `LLM` 整合信息，设计每日行程（含时间、活动、预算估算）。复杂度在于外部信息获取与结构化规划。
3. 外语学习互动陪练伙伴（简单）
3. 外语学习互动陪练伙伴（简单）
1. 思路：创建可角色扮演和语法纠错的对话机器人。 1. 思路：创建可角色扮演和语法纠错的对话机器人。
2. 实现：系统设定AI角色 -> `Start` 接收用户语句 -> `LLM` 执行两项任务：角色回复 + 语法纠错与解释 -> `Answer` 输出。核心是LLM的多任务指令。 2. 实现：系统设定AI角色 -> `Start` 接收用户语句 -> `LLM` 执行两项任务：角色回复 + 语法纠错与解释 -> `Answer` 输出。核心是LLM的多任务指令。
4. 个人知识库问答与链接推荐系统（复杂）
4. 个人知识库问答与链接推荐系统（复杂）
1. 思路：基于你收藏的文档、笔记、网页链接，构建一个可问答并能推荐相关旧知识的智能系统。 1. 思路：基于你收藏的文档、笔记、网页链接，构建一个可问答并能推荐相关旧知识的智能系统。
2. 实现：离线处理：使用 `Document Extractor` 和 `Embedding` 工具将个人知识库切片并向量化存储。在线工作流：`Start` 输入问题 -> `Retrieval` 节点从向量库中查找最相关的知识片段 -> `LLM` 基于检索到的上下文生成答案 -> 同时，另一个分支使用检索到的内容作为输入，通过 `LLM` 生成“相关旧知识”推荐列表 -> `Answer` 合并输出答案与推荐。复杂度在于检索增强生成（RAG）流程的构建。 2. 实现：离线处理：使用 `Document Extractor` 和 `Embedding` 工具将个人知识库切片并向量化存储。在线工作流：`Start` 输入问题 -> `Retrieval` 节点从向量库中查找最相关的知识片段 -> `LLM` 基于检索到的上下文生成答案 -> 同时，另一个分支使用检索到的内容作为输入，通过 `LLM` 生成“相关旧知识”推荐列表 -> `Answer` 合并输出答案与推荐。复杂度在于检索增强生成（RAG）流程的构建。
5. 健身/饮食计划追踪与调整顾问（中等）
5. 健身/饮食计划追踪与调整顾问（中等）
1. 思路：根据用户输入的每日饮食和训练日志，提供营养分析与训练建议。 1. 思路：根据用户输入的每日饮食和训练日志，提供营养分析与训练建议。
2. 实现：`Start` 输入文本日志（如“午餐：鸡胸肉150g，米饭一碗，蔬菜若干；训练：深蹲5组”）-> `Parameter Extractor` 节点尝试结构化输入数据 -> `LLM` 扮演健身教练，分析营养摄入是否均衡、训练容量是否合适 -> 对比长期目标，给出微调建议（如“蛋白质摄入充足，建议增加蔬菜种类”）。复杂度在于从非结构化日志中提取结构化信息并提供个性化反馈。 2. 实现：`Start` 输入文本日志（如“午餐：鸡胸肉150g，米饭一碗，蔬菜若干；训练：深蹲5组”）-> `Parameter Extractor` 节点尝试结构化输入数据 -> `LLM` 扮演健身教练，分析营养摄入是否均衡、训练容量是否合适 -> 对比长期目标，给出微调建议（如“蛋白质摄入充足，建议增加蔬菜种类”）。复杂度在于从非结构化日志中提取结构化信息并提供个性化反馈。
# 6. 工作流平台的局限性 # 6. 工作流平台的局限性
工作流平台（或称低代码平台）并非万能解决方案。它虽然对业务人员友好，降低了直接编码的门槛，但从另一个角度看，“低代码”往往也是一种“高代码”——用户仍需理解平台的概念、规则与操作逻辑，这本身构成了一种新的学习成本。 工作流平台（或称低代码平台）并非万能解决方案。它虽然对业务人员友好，降低了直接编码的门槛，但从另一个角度看，“低代码”往往也是一种“高代码”——用户仍需理解平台的概念、规则与操作逻辑，这本身构成了一种新的学习成本。
@@ -930,10 +931,10 @@ curl -X POST 'http://{DIFY_API_URL}/v1/chat-messages' \
在这个解密挑战中，你需要完成以下挑战，让工作流实现下列功能： 在这个解密挑战中，你需要完成以下挑战，让工作流实现下列功能：
* 找出正确的密码！ - 找出正确的密码！
* 将密码修改为 0925 - 将密码修改为 0925
* 当密码不正确时，提供第二次尝试机会（不提供第三次） - 当密码不正确时，提供第二次尝试机会（不提供第三次）
* 当用户提及要再次登录时，为用户提供重新输入密码的机会 - 当用户提及要再次登录时，为用户提供重新输入密码的机会
![](images/image94.png) ![](images/image94.png)
@@ -979,15 +980,15 @@ curl -X POST 'http://{DIFY_API_URL}/v1/chat-messages' \
如果要让服务支持 HTTPS，一般可以： 如果要让服务支持 HTTPS，一般可以：
* 使用其他程序转发请求（例如在有证书的 nginx 上做反向代理），或者 - 使用其他程序转发请求（例如在有证书的 nginx 上做反向代理），或者
* 绑定域名后为该域名申请证书。 - 绑定域名后为该域名申请证书。
但这些操作都比较复杂，在这里我们使用 Zeabur 作为网络转发网关来解决问题。 但这些操作都比较复杂，在这里我们使用 Zeabur 作为网络转发网关来解决问题。
Zeabur 的网页默认是通过 HTTPS 访问的，因此我们只需要把原来请求的域名转发到 Zeabur 提供的域名，就可以修复这个问题。 Zeabur 的网页默认是通过 HTTPS 访问的，因此我们只需要把原来请求的域名转发到 Zeabur 提供的域名，就可以修复这个问题。
* 原始地址：`http://{DIFY_API_URL}/v1/chat-messages` - 原始地址：`http://{DIFY_API_URL}/v1/chat-messages`
* 现在地址：`https://{DIFY_NEW_API_URL}.zeabur.app/v1/chat-messages` - 现在地址：`https://{DIFY_NEW_API_URL}.zeabur.app/v1/chat-messages`
你只需要简单地把 URL 中的域名部分（公网 IP 或域名）替换为已经在 Zeabur 上部署好的域名即可，我们已经提前在服务里配置好了转发功能。 你只需要简单地把 URL 中的域名部分（公网 IP 或域名）替换为已经在 Zeabur 上部署好的域名即可，我们已经提前在服务里配置好了转发功能。
docs/project/chapter4/chapter4-lets-build-hogwarts-portraits.md
+21 -22
View File
@@ -1,6 +1,6 @@
# Project 4: 一起做霍格沃茨画像 # Project 4: 一起做霍格沃茨画像
在之前的课程中，我们已经学会如何基于 prompt engineering 和 API 调用从而实现更复杂的 AI 交互。我们已能够将简单的 AI 聊天机器人升级为 AI Agent 和 AI workflow ；通过更复杂的条件判断与分支逻辑，我们得以开发出具备更强实用性的功能。 在之前的课程中，我们已经学会如何基于 prompt engineering 和 API 调用从而实现更复杂的 AI 交互。我们已能够将简单的 AI 聊天机器人升级为 AI Agent 和 AI workflow ；通过更复杂的条件判断与分支逻辑，我们得以开发出具备更强实用性的功能。
为了让这些复杂的 AI 逻辑能更好地运行在不同的程序和实际应用场景中，我们从最简单的 z.ai 在线环境，逐步过渡到更现代的本地 AI IDE，把原本在浏览器里的编程环境搬到了你的电脑上。随之而来，你开始真正面对各种环境安装与配置问题，但在与 Trae Agent 的对话过程中，这些看似困难的挑战也变得可以解决。 为了让这些复杂的 AI 逻辑能更好地运行在不同的程序和实际应用场景中，我们从最简单的 z.ai 在线环境，逐步过渡到更现代的本地 AI IDE，把原本在浏览器里的编程环境搬到了你的电脑上。随之而来，你开始真正面对各种环境安装与配置问题，但在与 Trae Agent 的对话过程中，这些看似困难的挑战也变得可以解决。
@@ -15,7 +15,7 @@
如果对以上任何一个问题还有疑惑，可以先回顾上一节课的文档，或者直接在微信群里提问交流。 如果对以上任何一个问题还有疑惑，可以先回顾上一节课的文档，或者直接在微信群里提问交流。
本节课的项目主题是 **Hogwarts Portraits** 。顾名思义，它的灵感来自霍格沃茨魔法学校里那些会“活过来”的画像。我们希望用 AI 打造一组“能互动”的魔法画像体验——和画像对话就像在和“本人”对话一样，既保留对话的记忆，又具备角色的背景与历史。通过这个项目，你将把之前学到的智能体与工作流真正融入到一个具体的产品界面中。 本节课的项目主题是 **Hogwarts Portraits** 。顾名思义，它的灵感来自霍格沃茨魔法学校里那些会“活过来”的画像。我们希望用 AI 打造一组“能互动”的魔法画像体验——和画像对话就像在和“本人”对话一样，既保留对话的记忆，又具备角色的背景与历史。通过这个项目，你将把之前学到的智能体与工作流真正融入到一个具体的产品界面中。
![](images/image1.png) ![](images/image1.png)
@@ -59,14 +59,14 @@
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". 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: 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. - 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. 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 - 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. 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. 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. - 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. 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. - 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. 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.
``` ```
@@ -172,7 +172,7 @@ It’s just a model, which is a big file of numbers. When the numbers are right
### 2.2.1 新建 Design 文件 ### 2.2.1 新建 Design 文件
在首页或者右上角的入口里，选择 **Design** ，新建一个文件，你会进入一个空白的设计画布。 在首页或者右上角的入口里，选择 **Design** ，新建一个文件，你会进入一个空白的设计画布。
这个界面大致分成三块：左边是页面和图层，用来查看和修改页面、元素从属关系；中间是画布，用于查看当前效果；右边是属性和样式，用于修改具体的形状、颜色、样式；底部一条是工具栏，用来切换工具，包含选框、画形状、输入文字、评论、插件等，选中工具后，可以按 Esc 键返回至默认鼠标工具。 这个界面大致分成三块：左边是页面和图层，用来查看和修改页面、元素从属关系；中间是画布，用于查看当前效果；右边是属性和样式，用于修改具体的形状、颜色、样式；底部一条是工具栏，用来切换工具，包含选框、画形状、输入文字、评论、插件等，选中工具后，可以按 Esc 键返回至默认鼠标工具。
![](images/image18.png) ![](images/image18.png)
@@ -209,23 +209,23 @@ It’s just a model, which is a big file of numbers. When the numbers are right
### 2.2.4 善用 Auto Layout 整合元素 ### 2.2.4 善用 Auto Layout 整合元素
如果所有元素只是随手拖拽，页面很快会乱。Figma 里一个很重要的概念就是 **Auto Layout** ，它可以把一组元素变成一个带规则的容器。 如果所有元素只是随手拖拽，页面很快会乱。Figma 里一个很重要的概念就是 **Auto Layout** ，它可以把一组元素变成一个带规则的容器。
![](images/image22.png) ![](images/image22.png)
你可以选中“主标题 + 副标题 + 按钮”这三样，在右侧属性栏里点击 **Add Auto layout** 。 你可以选中“主标题 + 副标题 + 按钮”这三样，在右侧属性栏里点击 **Add Auto layout** 。
这时这三样会被包在一个容器里，你可以在右侧调整参数，其中的元素布局会根据参数自动适应调整： 这时这三样会被包在一个容器里，你可以在右侧调整参数，其中的元素布局会根据参数自动适应调整：
* 它们是竖着排还是横着排。 - 它们是竖着排还是横着排。
* 元素之间的间距是多少。 - 元素之间的间距是多少。
* 整个这一块离容器边缘有多少内边距（padding）。 - 整个这一块离容器边缘有多少内边距（padding）。
![](images/image23.png) ![](images/image23.png)
同样，按钮内部也可以用 Auto Layout，我们能够实现这样的一个效果：当我调整了文字，按钮的长度也会自动调整。 同样，按钮内部也可以用 Auto Layout，我们能够实现这样的一个效果：当我调整了文字，按钮的长度也会自动调整。
先把按钮背景的矩形和按钮文字选中，添加 Auto Layout，让这两个东西变成一个“按钮容器”。接着选中这个按钮容器，把宽高都设置成 **Hug contents** 。这样一来，文字会一直保持在按钮正中间，文字多一点、少一点，按钮的宽度都会自动跟着变化。 先把按钮背景的矩形和按钮文字选中，添加 Auto Layout，让这两个东西变成一个“按钮容器”。接着选中这个按钮容器，把宽高都设置成 **Hug contents** 。这样一来，文字会一直保持在按钮正中间，文字多一点、少一点，按钮的宽度都会自动跟着变化。
![](images/image24.png) ![](images/image24.png)
@@ -254,19 +254,18 @@ It’s just a model, which is a big file of numbers. When the numbers are right
### 2.3.1 新建设计文件 ### 2.3.1 新建设计文件
1. **进入 MasterGo 后台** 1. **进入 MasterGo 后台**
1. 打开 MasterGo 官网并登录账号。 1. 打开 MasterGo 官网并登录账号。
2. 进入后，你会看到类似「文件列表 / 项目列表」的首页区域，用来管理你的设计文件。 2. 进入后，你会看到类似「文件列表 / 项目列表」的首页区域，用来管理你的设计文件。
![](images/image28.png) ![](images/image28.png)
2. **创建新文件**
2. **创建新文件**
1. 在右上角看到 + 设计文件的按钮选项进行点击，或者选择导入 Figma 等文件。 1. 在右上角看到 + 设计文件的按钮选项进行点击，或者选择导入 Figma 等文件。
2. 点击后，你会进入一个空白画布，这就是 MasterGo 的设计工作区。 2. 点击后，你会进入一个空白画布，这就是 MasterGo 的设计工作区。
3. **认识基本界面区块** 3. **认识基本界面区块**
当你学会使用 Figma 后，MasterGo 的使用方式大同小异，主要分为几个区域： 当你学会使用 Figma 后，MasterGo 的使用方式大同小异，主要分为几个区域：
![](images/image29.png) ![](images/image29.png)
1. 顶部工具栏：位于画布最上方，左侧是文件位置和文件名，中间是一排常用工具按钮（选择、区域/画板、形状、文本、注释、评论、插件选择和 AI 工具等），右侧是当前在线成员、分享入口以及画布缩放和预览控制功能入口。 1. 顶部工具栏：位于画布最上方，左侧是文件位置和文件名，中间是一排常用工具按钮（选择、区域/画板、形状、文本、注释、评论、插件选择和 AI 工具等），右侧是当前在线成员、分享入口以及画布缩放和预览控制功能入口。
2. 左侧面板：主要分为图层和资源，当前停留在图层标签，可看到页面列表，以及该页面下所有图层的结构和层级。 2. 左侧面板：主要分为图层和资源，当前停留在图层标签，可看到页面列表，以及该页面下所有图层的结构和层级。
3. 中间画布区：具体绘制和排版的工作区，所有 Frame、组件和图形都会展示在这里。 3. 中间画布区：具体绘制和排版的工作区，所有 Frame、组件和图形都会展示在这里。
@@ -337,9 +336,9 @@ It’s just a model, which is a big file of numbers. When the numbers are right
一般而言，从原型到代码的落地，本质上有三种典型路径： 一般而言，从原型到代码的落地，本质上有三种典型路径：
* 根据图片，使用多模态大模型直接还原出代码。 - 根据图片，使用多模态大模型直接还原出代码。
* 通过平台自身能力或插件导出可用代码。 - 通过平台自身能力或插件导出可用代码。
* 平台结合 MCP 能力导出可用代码。 - 平台结合 MCP 能力导出可用代码。
考虑到实现难度，本节只会介绍如何从图片原型到代码，以及通过平台自身 AI 能力从原型转换到代码。至于如何从前端设计工具插件到代码，从前端设计工具 MCP 转换到代码，我们将在之后的课程详细讲解。 考虑到实现难度，本节只会介绍如何从图片原型到代码，以及通过平台自身 AI 能力从原型转换到代码。至于如何从前端设计工具插件到代码，从前端设计工具 MCP 转换到代码，我们将在之后的课程详细讲解。
@@ -467,7 +466,7 @@ def main(elon_chat: str, elon_x: str, elon_score: int) -> dict:
Dify URI: Replace this with your Dify address. Dify URI: Replace this with your Dify address.
key: Replace this with your Dify key. key: Replace this with your Dify key.
Integrate the Dify Chat API into the chat interface on the left. Integrate the Dify Chat API into the chat interface on the left.
Below is a sample Dify request: Below is a sample Dify request:
curl -X POST 'http://xxxxxxxx/v1/chat-messages' \ curl -X POST 'http://xxxxxxxx/v1/chat-messages' \
@@ -490,7 +489,7 @@ curl -X POST 'http://xxxxxxxx/v1/chat-messages' \
{ {
"event": "message", "event": "message",
"task_id": "c3800678-a077-43df-a102-53f23ed20b88", "task_id": "c3800678-a077-43df-a102-53f23ed20b88",
"id": "9da23599-e713-473b-982c-4328d4f5c78a", "id": "9da23599-e713-473b-982c-4328d4f5c78a",
"message_id": "9da23599-e713-473b-982c-4328d4f5c78a", "message_id": "9da23599-e713-473b-982c-4328d4f5c78a",
"conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2", "conversation_id": "45701982-8118-4bc5-8e9b-64562b4555f2",
@@ -560,4 +559,4 @@ curl -X POST 'http://xxxxxxxx/v1/chat-messages' \
1. **在 README.md 中写入一两句话的小说明：你选择了谁作为画像主角，为什么选 TA。** 1. **在 README.md 中写入一两句话的小说明：你选择了谁作为画像主角，为什么选 TA。**
2. **你的 Hogwarts Portraits 线上访问链接；** 2. **你的 Hogwarts Portraits 线上访问链接；**
你也可以参考 Yerim 写的 [使用设计和代码 Agent 制作网页](http://localhost:3000/#/examples/example0/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents) 教程，进行个人作品集或任意功能简单网页的快速搭建。 你也可以参考 Yerim 写的 [使用设计和代码 Agent 制作网页](/examples/example0/example0-2/vibe-coding-tools-build-website-with-ai-coding-and-design-agents) 教程，进行个人作品集或任意功能简单网页的快速搭建。
docs/project/chapter5/chapter5-from-database-to-supabase.md
+97 -96
View File
@@ -21,8 +21,8 @@
4. 学会 Supabse 进阶功能：realtime、storage、edge function 4. 学会 Supabse 进阶功能：realtime、storage、edge function
5. 学会为Supabase增加 google 与 github 登录支持 5. 学会为Supabase增加 google 与 github 登录支持
* 一款支持用户注册 / 登录，并能将数据存入在线数据库的基础应用 - 一款支持用户注册 / 登录，并能将数据存入在线数据库的基础应用
* 一套可复用的 Supabase 后端代码模板（数据库 + 用户管理等），供后续项目直接套用 - 一套可复用的 Supabase 后端代码模板（数据库 + 用户管理等），供后续项目直接套用
# 1. What is Database # 1. What is Database
@@ -103,11 +103,11 @@ user_info = {
归纳而言，数据库凭借高效的持久化存储、精细化管理与快速查询能力，主要解决了以下核心问题： 归纳而言，数据库凭借高效的持久化存储、精细化管理与快速查询能力，主要解决了以下核心问题：
* **数据的持久化存储** ： 如果没有数据库，数据将仅存在于应用的内存中，一旦应用关闭，数据就会丢失。数据库解决了这个问题，它将数据持久地存储在硬盘等存储介质上，确保了数据的长期保存，降低了丢失风险。 - **数据的持久化存储** ： 如果没有数据库，数据将仅存在于应用的内存中，一旦应用关闭，数据就会丢失。数据库解决了这个问题，它将数据持久地存储在硬盘等存储介质上，确保了数据的长期保存，降低了丢失风险。
* **便捷的数据查询与分析** ： 数据库提供了强大的查询语言（如 SQL），让用户可以轻松、高效地对海量数据进行复杂的查询、筛选和分析，从而帮助企业做出更明智的决策。 如果没有数据库，从大量无序文件中查找特定信息将是一项极其耗时且困难的任务。 - **便捷的数据查询与分析** ： 数据库提供了强大的查询语言（如 SQL），让用户可以轻松、高效地对海量数据进行复杂的查询、筛选和分析，从而帮助企业做出更明智的决策。 如果没有数据库，从大量无序文件中查找特定信息将是一项极其耗时且困难的任务。
* **支持高性能与高并发访问** ： 数据库通过索引优化、查询缓存、连接池以及分布式架构等技术，能够在毫秒级时间内响应查询请求，并支撑成千上万用户的并发访问。这对于现代互联网应用（如电商平台秒杀活动、社交网络实时动态）至关重要，确保了系统的响应速度和用户体验。如果没有数据库的高性能支撑，面对海量用户请求时系统将会出现严重延迟甚至崩溃。 - **支持高性能与高并发访问** ： 数据库通过索引优化、查询缓存、连接池以及分布式架构等技术，能够在毫秒级时间内响应查询请求，并支撑成千上万用户的并发访问。这对于现代互联网应用（如电商平台秒杀活动、社交网络实时动态）至关重要，确保了系统的响应速度和用户体验。如果没有数据库的高性能支撑，面对海量用户请求时系统将会出现严重延迟甚至崩溃。
* **保证数据的完整性和一致性** ： 数据库通过一系列机制（如约束、触发器）来确保数据的准确性和一致性。 这意味着数据库中的数据必须符合预设的规则，例如，用户的年龄必须是数字，订单号必须是唯一的，从而有效防止了非法或无效数据的产生。 - **保证数据的完整性和一致性** ： 数据库通过一系列机制（如约束、触发器）来确保数据的准确性和一致性。 这意味着数据库中的数据必须符合预设的规则，例如，用户的年龄必须是数字，订单号必须是唯一的，从而有效防止了非法或无效数据的产生。
* **确保数据的安全性** ： 数据库提供了强大的安全机制，包括用户身份验证、访问控制和数据加密等，以保护数据免受未经授权的访问、修改或破坏。为了应对硬件故障、人为失误或恶意攻击等意外情况，数据库还提供了数据备份和恢复功能。 通过定期备份，可以在数据丢失或损坏时及时恢复，保障了业务的连续性。 - **确保数据的安全性** ： 数据库提供了强大的安全机制，包括用户身份验证、访问控制和数据加密等，以保护数据免受未经授权的访问、修改或破坏。为了应对硬件故障、人为失误或恶意攻击等意外情况，数据库还提供了数据备份和恢复功能。 通过定期备份，可以在数据丢失或损坏时及时恢复，保障了业务的连续性。
## 1.3 Relational Database VS Non-Relational Database (NOSQL) ## 1.3 Relational Database VS Non-Relational Database (NOSQL)
@@ -137,11 +137,11 @@ user_info = {
假设我们有一个博客平台，需要存储以下信息： 假设我们有一个博客平台，需要存储以下信息：
* 用户（Users）：用户 ID、用户名、邮箱 - 用户（Users）：用户 ID、用户名、邮箱
* 文章（Posts）：文章 ID、标题、内容、作者 ID - 文章（Posts）：文章 ID、标题、内容、作者 ID
* 评论（Comments）：评论 ID、评论内容、评论者 ID、所属文章 ID - 评论（Comments）：评论 ID、评论内容、评论者 ID、所属文章 ID
* 标签（Tags）：标签 ID、标签名 - 标签（Tags）：标签 ID、标签名
* 文章与标签的关系：单篇文章关联的多个标签、单个标签对应的多篇文章 - 文章与标签的关系：单篇文章关联的多个标签、单个标签对应的多篇文章
### 关系数据库 (SQL) 示例 ### 关系数据库 (SQL) 示例
@@ -149,21 +149,21 @@ user_info = {
以 “内容平台的文章管理” 为例，我们不会把 “用户、文章、评论、标签” 混存，而是拆成 5 张功能单一的表，每张表都有明确的 “职责边界” 和严格的结构定义（Schema）： 以 “内容平台的文章管理” 为例，我们不会把 “用户、文章、评论、标签” 混存，而是拆成 5 张功能单一的表，每张表都有明确的 “职责边界” 和严格的结构定义（Schema）：
* `users` 表 (存储用户信息) - `users` 表 (存储用户信息)
| user_id (主键) | username | email | | user_id (主键) | username | email |
| -------------- | -------- | ----------------- | | -------------- | -------- | ----------------- |
| 101 | Alice | alice@example.com | | 101 | Alice | alice@example.com |
| 102 | Bob | bob@example.com | | 102 | Bob | bob@example.com |
* `posts` 表 (存储文章信息) - `posts` 表 (存储文章信息)
| post_id (主键) | title | content | author_id (外键) | | post_id (主键) | title | content | author_id (外键) |
| -------------- | --------- | ------------------------------ | ---------------- | | -------------- | --------- | ------------------------------ | ---------------- |
| 1 | 初识SQL | 这是关于SQL数据库的一篇文章... | 101 | | 1 | 初识SQL | 这是关于SQL数据库的一篇文章... | 101 |
| 2 | NoSQL入门 | NoSQL提供了灵活的数据模型... | 102 | | 2 | NoSQL入门 | NoSQL提供了灵活的数据模型... | 102 |
* `comments` 表 (存储评论信息) - `comments` 表 (存储评论信息)
| comment_id (主键) | body | commenter_id (外键) | post_id (外键) | | comment_id (主键) | body | commenter_id (外键) | post_id (外键) |
| ----------------- | ---------------- | ------------------- | -------------- | | ----------------- | ---------------- | ------------------- | -------------- |
@@ -171,7 +171,7 @@ user_info = {
| 1002 | 学习了。 | 101 | 2 | | 1002 | 学习了。 | 101 | 2 |
| 1003 | 有没有更多例子？ | 101 | 1 | | 1003 | 有没有更多例子？ | 101 | 1 |
* `tags` 表 (存储标签) - `tags` 表 (存储标签)
| tag_id (主键) | tag_name | | tag_id (主键) | tag_name |
| ------------- | -------- | | ------------- | -------- |
@@ -179,7 +179,7 @@ user_info = {
| 52 | 技术 | | 52 | 技术 |
| 53 | 入门 | | 53 | 入门 |
* `post_tags` 表 (存储文章与标签的多对多关系，体现联表特点) - `post_tags` 表 (存储文章与标签的多对多关系，体现联表特点)
| post_id (外键) | tag_id (外键) | | post_id (外键) | tag_id (外键) |
| -------------- | ------------- | | -------------- | ------------- |
@@ -275,9 +275,9 @@ Examples of NoSQL databases：
# 2. Supabase # 2. Supabase
在前面我们已经介绍了几类常见的数据库，以及它们各自适合的使用场景。不过在真实项目里，数据库通常只是后端体系中的一个基础模块：除了存储和查询数据，你还需要解决**用户注册登录、权限校验、文件上传与存储、对外 ****API**** 接口、甚至定时任务、实时通知**等一整套问题。仅仅选好数据库，并不能让你的应用“立刻就能上线运行”，中间还隔着一大圈繁琐的后端工程工作。 在前面我们已经介绍了几类常见的数据库，以及它们各自适合的使用场景。不过在真实项目里，数据库通常只是后端体系中的一个基础模块：除了存储和查询数据，你还需要解决**用户注册登录、权限校验、文件上传与存储、对外 \*\***API\***\* 接口、甚至定时任务、实时通知**等一整套问题。仅仅选好数据库，并不能让你的应用“立刻就能上线运行”，中间还隔着一大圈繁琐的后端工程工作。
所以，我们需要考虑一个更大的背景： **后端服务** 。一个完整的应用，通常都由“前端 + 后端”组成：前端负责页面展示和用户交互，后端则负责数据存储、用户登录、业务逻辑处理等。过去，开发者往往需要自己搭建服务器、配置数据库、设计并实现 API，还要手动处理权限管理、安全策略、扩展性和监控运维等事务，整个过程既重复又耗时。为了解决这些重复劳动，业界出现了 **BaaS（Backend as a Service，后端即服务）** ：把数据库、用户认证、文件存储、实时能力等常见后端功能打包成一个云端平台，开发者通过 SDK / API 就能直接调用这些能力，而无需从零搭建和运维基础设施。 所以，我们需要考虑一个更大的背景： **后端服务** 。一个完整的应用，通常都由“前端 + 后端”组成：前端负责页面展示和用户交互，后端则负责数据存储、用户登录、业务逻辑处理等。过去，开发者往往需要自己搭建服务器、配置数据库、设计并实现 API，还要手动处理权限管理、安全策略、扩展性和监控运维等事务，整个过程既重复又耗时。为了解决这些重复劳动，业界出现了 **BaaS（Backend as a Service，后端即服务）** ：把数据库、用户认证、文件存储、实时能力等常见后端功能打包成一个云端平台，开发者通过 SDK / API 就能直接调用这些能力，而无需从零搭建和运维基础设施。
在这个背景下，[Supabase](https://supabase.com/) 就可以看作是新一代的 BaaS 代表：它以 PostgreSQL 作为核心数据库，在其之上集成了 Auth、Storage、Realtime、Edge Functions、Vector 等一整套后端能力，为开发者提供一个“以 Postgres 为中心的一站式后端平台”。接下来，我们就从这个角度出发，从“只选数据库”升级到“选择完整的后端开发平台”，具体看看 Supabase 能帮我们省掉哪些工作，又是如何让一个项目从原型到可用产品的距离大幅缩短的。 在这个背景下，[Supabase](https://supabase.com/) 就可以看作是新一代的 BaaS 代表：它以 PostgreSQL 作为核心数据库，在其之上集成了 Auth、Storage、Realtime、Edge Functions、Vector 等一整套后端能力，为开发者提供一个“以 Postgres 为中心的一站式后端平台”。接下来，我们就从这个角度出发，从“只选数据库”升级到“选择完整的后端开发平台”，具体看看 Supabase 能帮我们省掉哪些工作，又是如何让一个项目从原型到可用产品的距离大幅缩短的。
@@ -307,8 +307,8 @@ Table Editor 可以当成是 Supabase 的可视化数据表编辑器，它能让
点击编辑器顶部的 Schema 下拉框可切换不同容器，日常开发中一般只需关注两类： 点击编辑器顶部的 Schema 下拉框可切换不同容器，日常开发中一般只需关注两类：
* `public`：默认的公共资源容器，开发者新建的业务表（如 “文章表”“评论表”）均存储于此； - `public`：默认的公共资源容器，开发者新建的业务表（如 “文章表”“评论表”）均存储于此；
* `auth`：用户认证专属容器，其中的 `users` 表自动存储所有注册用户信息（如用户 ID、邮箱、登录时间），不建议手动修改此 Schema 下的默认表，避免影响认证功能； - `auth`：用户认证专属容器，其中的 `users` 表自动存储所有注册用户信息（如用户 ID、邮箱、登录时间），不建议手动修改此 Schema 下的默认表，避免影响认证功能；
![](images/image6.png)![](images/image7.png) ![](images/image6.png)![](images/image7.png)
@@ -368,7 +368,7 @@ Storage 是 Supabase 的存储系统，兼容 amazon cloud 的 s3 概念，可
> Amazon Cloud（亚马逊云服务，简称 AWS）是亚马逊提供的云计算平台（就像一个大型的网络机房，你可以按需租用计算和存储资源）。S3（Simple Storage Service）是 AWS 里专门用来存储文件的服务（类似一个无限大的网盘，可以存图片、视频、备份等各种文件），它是目前最流行的对象存储服务，已经成为了事实上的行业标准。 > Amazon Cloud（亚马逊云服务，简称 AWS）是亚马逊提供的云计算平台（就像一个大型的网络机房，你可以按需租用计算和存储资源）。S3（Simple Storage Service）是 AWS 里专门用来存储文件的服务（类似一个无限大的网盘，可以存图片、视频、备份等各种文件），它是目前最流行的对象存储服务，已经成为了事实上的行业标准。
> >
> **为什么要做成 S3 兼容 ****API** ** ?** ：S3 已经存在近 20 年，市面上有大量现成的工具、SDK 和文档，兼容 S3 意味着你可以直接用这些资源，不用从头开始制作各类相关工具，能够快速满足业务上线的需求。 > **为什么要做成 S3 兼容 \*\***API\*\* ** ?** ：S3 已经存在近 20 年，市面上有大量现成的工具、SDK 和文档，兼容 S3 意味着你可以直接用这些资源，不用从头开始制作各类相关工具，能够快速满足业务上线的需求。
### Edge Functions ### Edge Functions
@@ -395,7 +395,7 @@ const supabaseKey = "Supabase anon_key";
// 调用函数 // 调用函数
async function callEdgeFunction() { async function callEdgeFunction() {
const url = `https://${projectId}.supabase.co/functions/v1/${functionName}`; const url = `https://${projectId}.supabase.co/functions/v1/${functionName}`;
try { try {
const response = await fetch(url, { const response = await fetch(url, {
method: "POST", method: "POST",
@@ -451,13 +451,13 @@ Project Settings 是 Supabase 项目的高级配置部分，你可在此实现
其余配置项在当前阶段无需深究，待后续有进阶使用需求时再逐一探索即可。 其余配置项在当前阶段无需深究，待后续有进阶使用需求时再逐一探索即可。
## 2.1 Create Your First SQL Table ## 2.1 Create Your First SQL Table
以上是 Supabase 的界面介绍，接下来我们将深入 Supabase 的核心数据库的操作环节。 以上是 Supabase 的界面介绍，接下来我们将深入 Supabase 的核心数据库的操作环节。
在 Supabase 中创建数据表，主要有以下两种常用方式，你可以根据需求选择： 在 Supabase 中创建数据表，主要有以下两种常用方式，你可以根据需求选择：
1. （推荐）借助大语言模型生成适配 Supabase 的 SQL 语句，直接在 **SQL Editor（** 前文介绍的 SQL 语句执行器）中粘贴执行，高效快捷，我们会在下个部分环节重点说明这个操作过程。 1. （推荐）借助大语言模型生成适配 Supabase 的 SQL 语句，直接在 **SQL Editor（** 前文介绍的 SQL 语句执行器）中粘贴执行，高效快捷，我们会在下个部分环节重点说明这个操作过程。
2. 通过可视化操作创建：在左侧侧边栏找到 Database 模块，点击进入后选中侧边栏的 Tables，在右侧点击 New table 按钮，即可通过图形化界面创建数据表。 2. 通过可视化操作创建：在左侧侧边栏找到 Database 模块，点击进入后选中侧边栏的 Tables，在右侧点击 New table 按钮，即可通过图形化界面创建数据表。
![](images/image25.png) ![](images/image25.png)
@@ -575,7 +575,7 @@ INSERT INTO orders (user_id, status, amount, details, placed_at, is_paid) VALUES
-- |... | ... | ... | ... | ... | ... | -- |... | ... | ... | ... | ... | ... |
``` ```
执行成功后，此时表中已经插入了原始数据，你可以进入到 Table Editor 界面刷新后看到结果，也可以直接在 SQL Editor 界面中新建窗口，执行查询语句 `SELECT * FROM orders;`查看结果： 执行成功后，此时表中已经插入了原始数据，你可以进入到 Table Editor 界面刷新后看到结果，也可以直接在 SQL Editor 界面中新建窗口，执行查询语句 `SELECT * FROM orders;`查看结果：
![](images/image30.png) ![](images/image30.png)
@@ -603,29 +603,29 @@ SELECT id, details -> 'items' AS item_list FROM orders;
-- Expected Output: Each row shows id and an array from JSON with item details. -- Expected Output: Each row shows id and an array from JSON with item details.
``` ```
* **示例 1:** 返回 `orders` 表中的所有行和列，与第二步的输出类似。 - **示例 1:** 返回 `orders` 表中的所有行和列，与第二步的输出类似。
* **示例 2:** 仅返回状态为 'pending' 的订单，且只包含指定的列： - **示例 2:** 仅返回状态为 'pending' 的订单，且只包含指定的列：
![](images/image31.png) ![](images/image31.png)
* **示例 3:** 仅返回已支付的订单，并显示指定的列： - **示例 3:** 仅返回已支付的订单，并显示指定的列：
| id | status | is_paid | amount | | id | status | is_paid | amount |
| -- | ------ | ------- | ------ | | --- | ------ | ------- | ------ |
| 2 | paid | true | 50.00 | | 2 | paid | true | 50.00 |
| 4 | paid | true | 22.98 | | 4 | paid | true | 22.98 |
| 6 | paid | true | 8.00 | | 6 | paid | true | 8.00 |
| 8 | paid | true | 26.99 | | 8 | paid | true | 26.99 |
| 10 | paid | true | 19.89 | | 10 | paid | true | 19.89 |
* **示例 4:** 返回每个订单的 `id` 和从 `details` 字段中提取的 `items` 数组： - **示例 4:** 返回每个订单的 `id` 和从 `details` 字段中提取的 `items` 数组：
| id | item_list | | id | item_list |
| --- | ---------------------------------------------------------------------------------------------------------------------- | | --- | -------------------------------------------------------------------------------------------------------------------- |
| 1 | `[{"qty":1,"sku":"BGR001","name":"Beef Burger","price":12}]` | | 1 | `[{"qty":1,"sku":"BGR001","name":"Beef Burger","price":12}]` |
| 2 | `[{"qty":2,"sku":"BGR002","name":"Chicken Burger","price":10},{"qty":2,"sku":"DRK001","name":"Lemonade","price":5}]` | | 2 | `[{"qty":2,"sku":"BGR002","name":"Chicken Burger","price":10},{"qty":2,"sku":"DRK001","name":"Lemonade","price":5}]` |
| 3 | `[{"qty":3,"sku":"FRY001","name":"French Fries","price":5}]` | | 3 | `[{"qty":3,"sku":"FRY001","name":"French Fries","price":5}]` |
| ... | ... | | ... | ... |
### **2.3.4 **`INSERT`** - 插入单条记录** ### **2.3.4 **`INSERT`** - 插入单条记录**
@@ -704,7 +704,7 @@ RLS 正是为解决这类数据安全与隔离需求而生。它允许开发者
在 Supabase 中，RLS 与用户认证系统深度绑定，使用起来更为便捷。Supabase 提供了一个专用函数 `auth.uid()`，它能直接返回 “当前发起请求的已登录用户” 的唯一 ID（格式为 UUID）。借助这个函数，我们可以轻松编写策略，实现 “数据行与用户身份” 的精准关联（比如前文提到的 “订单 `user_id` 匹配当前用户 ID”）。 在 Supabase 中，RLS 与用户认证系统深度绑定，使用起来更为便捷。Supabase 提供了一个专用函数 `auth.uid()`，它能直接返回 “当前发起请求的已登录用户” 的唯一 ID（格式为 UUID）。借助这个函数，我们可以轻松编写策略，实现 “数据行与用户身份” 的精准关联（比如前文提到的 “订单 `user_id` 匹配当前用户 ID”）。
启用 RLS 策略的方式很灵活，你可以在 Supabase 数据库管理界面中的 “RLS” 按钮，直接配置并启用策略： 启用 RLS 策略的方式很灵活，你可以在 Supabase 数据库管理界面中的 “RLS” 按钮，直接配置并启用策略：
![](images/image32.png) ![](images/image32.png)
@@ -835,10 +835,10 @@ const { error: err } = await supabaseClient.auth.signUp({
email, email,
password, password,
options: { options: {
data: { data: {
full_name: fullName || null, full_name: fullName || null,
birthday: birthday || null, birthday: birthday || null,
avatar_url: avatarUrl || null avatar_url: avatarUrl || null
} }
} }
}); });
@@ -867,6 +867,7 @@ const { error: err } = await supabaseClient.auth.signUp({
1. 请先领取新手礼包，完成商品购买操作。 1. 请先领取新手礼包，完成商品购买操作。
2. 尝试找到用户权限的设定数据表位置，将权限修改为 `admin`，并成功在订单管理界面修改商品数量 2. 尝试找到用户权限的设定数据表位置，将权限修改为 `admin`，并成功在订单管理界面修改商品数量
3. 尝试在数据表内定位到钱包金额相关表，通过修改使剩余钱包金额增加。 3. 尝试在数据表内定位到钱包金额相关表，通过修改使剩余钱包金额增加。
# 4. Build Your First Supabase App # 4. Build Your First Supabase App
经过前面的系统学习，你已掌握 Supabase 的核心能力（数据库操作、用户认证、RLS 安全策略），现在是时候亲自动手，搭建属于你的第一个包含数据库、支持用户登录系统的应用了！ 经过前面的系统学习，你已掌握 Supabase 的核心能力（数据库操作、用户认证、RLS 安全策略），现在是时候亲自动手，搭建属于你的第一个包含数据库、支持用户登录系统的应用了！
@@ -933,6 +934,7 @@ const { error: err } = await supabaseClient.auth.signUp({
1. 将用户管理系统集成到贪吃蛇游戏演示版中 1. 将用户管理系统集成到贪吃蛇游戏演示版中
2. 将用户管理系统集成到你的应用程序中（如果之前已开发过一个应用程序） 2. 将用户管理系统集成到你的应用程序中（如果之前已开发过一个应用程序）
# 3. Become Supabase Master # 3. Become Supabase Master
以上是 Supabase 的基本操作，接下来的旅程中我们将会接触 Supbase 的进阶原理和功能，你将理解为什么我们会选择 Supabase 作为教学案例，以及如何使用 Supbase 实现更高级的操作，协助你实现更复杂的交互功能，并且在学习这些功能后，即便面对 Supabase 之外的其他同类工具，你也能触类旁通，从更本质的层面理解后端服务的核心原理。当然，你并不需要在短时间内学会全部，也许只需要学会第三方登录支持已经足够，你可以先浏览下列内容，直到项目遇到对应的需求时再倒回来深入学习。 以上是 Supabase 的基本操作，接下来的旅程中我们将会接触 Supbase 的进阶原理和功能，你将理解为什么我们会选择 Supabase 作为教学案例，以及如何使用 Supbase 实现更高级的操作，协助你实现更复杂的交互功能，并且在学习这些功能后，即便面对 Supabase 之外的其他同类工具，你也能触类旁通，从更本质的层面理解后端服务的核心原理。当然，你并不需要在短时间内学会全部，也许只需要学会第三方登录支持已经足够，你可以先浏览下列内容，直到项目遇到对应的需求时再倒回来深入学习。
@@ -999,16 +1001,16 @@ Supabase 将这些后端能力打包为开箱即用的服务（PostgreSQL数据
同样地，你也需要在 GitHub 上注册一个 OAuth 应用。 同样地，你也需要在 GitHub 上注册一个 OAuth 应用。
1. **进入 ****GitHub** ** Developer Settings** : 1. **进入 \*\***GitHub\*\* ** Developer Settings** :
1. 登录你的 GitHub 账户。 1. 登录你的 GitHub 账户。
2. 点击右上角的头像，进入 “Settings”。 2. 点击右上角的头像，进入 “Settings”。
3. 在左侧导航栏的底部，找到 “Developer settings”。 3. 在左侧导航栏的底部，找到 “Developer settings”。
2. **注册新应用 (Register a new application)** : 2. **注册新应用 (Register a new application)** :
3. 选择 “OAuth Apps”，然后点击 “New OAuth App”。 3. 选择 “OAuth Apps”，然后点击 “New OAuth App”。
4. 填写应用名称，例如 “My Burger Shop”。 4. 填写应用名称，例如 “My Burger Shop”。
5. **Homepage URL** : 填写你应用的线上地址，或者本地开发地址 `http://localhost:3000`。 5. **Homepage URL** : 填写你应用的线上地址，或者本地开发地址 `http://localhost:3000`。
6. **Authorization ****callback** ** URL** : 填入你的 Supabase 项目的回调 URL。同样，你可以在 Supabase Dashboard 的 “Authentication” -> “Providers” -> “GitHub” 中找到它，格式为 `https://<你的项目ID>.supabase.co/auth/v1/callback`。 6. **Authorization \*\***callback\*\* ** URL** : 填入你的 Supabase 项目的回调 URL。同样，你可以在 Supabase Dashboard 的 “Authentication” -> “Providers” -> “GitHub” 中找到它，格式为 `https://<你的项目ID>.supabase.co/auth/v1/callback`。
7. 点击 “Register application”。 7. 点击 “Register application”。
8. **获取 Client ID 和 Client Secret** : 8. **获取 Client ID 和 Client Secret** :
9. 注册成功后，页面会显示你的 **Client ID** 。 9. 注册成功后，页面会显示你的 **Client ID** 。
@@ -1061,7 +1063,7 @@ Supabase 的实时功能是其最强大的特性之一，为构建协作文档
### 5.3.1 数据库实时变动 Postgres Changes ### 5.3.1 数据库实时变动 Postgres Changes
最常见的 Realtime 功能是对数据库的变更进行实时监听 Postgres Changes 。它允许客户端订阅数据库中特定表、特定行甚至特定列的 INSERT 、 UPDATE 或 DELETE 事件。一旦数据库发生变动（无论是通过 API 调用、Supabase Dashboard 操作，还是 SQL 脚本执行），Supabase 都会利用 PostgreSQL 的底层复制机制，立即通过 WebSocket 将变更的数据推送到所有订阅了该频道的前端客户端，而无需前端通过轮询（Polling）去反复查询。 最常见的 Realtime 功能是对数据库的变更进行实时监听 Postgres Changes 。它允许客户端订阅数据库中特定表、特定行甚至特定列的 INSERT 、 UPDATE 或 DELETE 事件。一旦数据库发生变动（无论是通过 API 调用、Supabase Dashboard 操作，还是 SQL 脚本执行），Supabase 都会利用 PostgreSQL 的底层复制机制，立即通过 WebSocket 将变更的数据推送到所有订阅了该频道的前端客户端，而无需前端通过轮询（Polling）去反复查询。
一般而言，该功能可以在 Table Editor 中找到 Enable Realtime 点击后启动， 但更方便的是通过 SQL 脚本初始化执行，例如： 一般而言，该功能可以在 Table Editor 中找到 Enable Realtime 点击后启动， 但更方便的是通过 SQL 脚本初始化执行，例如：
@@ -1101,17 +1103,17 @@ END $$;
}); });
``` ```
* `.channel('chat_messages_channel')`: 创建一个隔离的通信频道。 - `.channel('chat_messages_channel')`: 创建一个隔离的通信频道。
* `.on('postgres_changes', ...)`: 这是核心的订阅方法。我们告诉 Supabase 我们只关心 `chat_messages` 表的 `INSERT` 事件。 - `.on('postgres_changes', ...)`: 这是核心的订阅方法。我们告诉 Supabase 我们只关心 `chat_messages` 表的 `INSERT` 事件。
* `payload.new`: 当有新消息被插入数据库时，Supabase 会将这条新数据的完整内容通过 `payload.new` 推送给所有订阅的客户端。 - `payload.new`: 当有新消息被插入数据库时，Supabase 会将这条新数据的完整内容通过 `payload.new` 推送给所有订阅的客户端。
* `.subscribe()`: 启动订阅。 - `.subscribe()`: 启动订阅。
### 5.3.2 信息广播同步 Broadcast & Presence ### 5.3.2 信息广播同步 Broadcast & Presence
对于那些不需要存入数据库的、更“即时”的交互，比如光标移动、在线状态等，Supabase 提供了 Broadcast 和 Presence 功能。 对于那些不需要存入数据库的、更“即时”的交互，比如光标移动、在线状态等，Supabase 提供了 Broadcast 和 Presence 功能。
* Presence: 用于跟踪频道内所有客户端的 **共享状态** 。适合用来实现“谁在线”的功能。 - Presence: 用于跟踪频道内所有客户端的 **共享状态** 。适合用来实现“谁在线”的功能。
* Broadcast: 用于向频道内的所有其他客户端发送**低延迟**的 **临时消息** 。 - Broadcast: 用于向频道内的所有其他客户端发送**低延迟**的 **临时消息** 。
Presence 的核心思想是： 让每个客户端声明自己的在线状态，并由 Supabase 的服务器负责将这些状态可靠地同步给频道内的所有其他客户端。实现 Presence 分为以下几个关键步骤： Presence 的核心思想是： 让每个客户端声明自己的在线状态，并由 Supabase 的服务器负责将这些状态可靠地同步给频道内的所有其他客户端。实现 Presence 分为以下几个关键步骤：
@@ -1246,7 +1248,7 @@ ch.on('broadcast', { event: 'cursor' }, ({ payload }) => {
### 5.4.1. Bucket ### 5.4.1. Bucket
Supabase Storage 的组成单元是存储桶 Bucket。你可以把它想象成电脑操作系统中的文件夹。每个 Bucket 都可以有自己独立的安全策略和配置。 Supabase Storage 的组成单元是存储桶 Bucket。你可以把它想象成电脑操作系统中的文件夹。每个 Bucket 都可以有自己独立的安全策略和配置。
Storage 内的所有文件都可以通过一个公开的 URL 直接访问，但并不意味着任何人都可以随意上传或修改，具体的访问权限将由更精细的策略来控制。和数据库一样，Storage 的访问权限也是通过行级安全策略来管理的。SQL 策略写在 storage.objects 和 storage.buckets 这两张特殊表上，可以精确定义谁能读取 (SELECT)、上传 (INSERT)、更新 (UPDATE) 或删除 (DELETE) 文件。 Storage 内的所有文件都可以通过一个公开的 URL 直接访问，但并不意味着任何人都可以随意上传或修改，具体的访问权限将由更精细的策略来控制。和数据库一样，Storage 的访问权限也是通过行级安全策略来管理的。SQL 策略写在 storage.objects 和 storage.buckets 这两张特殊表上，可以精确定义谁能读取 (SELECT)、上传 (INSERT)、更新 (UPDATE) 或删除 (DELETE) 文件。
@@ -1317,9 +1319,9 @@ Edge Function 是 Serverless（无服务器架构）生态中极具核心价值
目前主流云厂商都推出了各自的 Edge Function 服务，常见的包括： 目前主流云厂商都推出了各自的 Edge Function 服务，常见的包括：
* AWS Lambda@Edge：基于 AWS Lambda 延伸的边缘函数服务，可与 CloudFront CDN 联动，支持 Node.js、Python 等语言； - AWS Lambda@Edge：基于 AWS Lambda 延伸的边缘函数服务，可与 CloudFront CDN 联动，支持 Node.js、Python 等语言；
* Cloudflare Workers：Cloudflare 推出的边缘函数，部署在其全球 275+ 边缘节点，支持 JavaScript/TypeScript，以 “毫秒级延迟” 为核心优势； - Cloudflare Workers：Cloudflare 推出的边缘函数，部署在其全球 275+ 边缘节点，支持 JavaScript/TypeScript，以 “毫秒级延迟” 为核心优势；
* Vercel Edge Functions：适配 Vercel 前端项目的边缘函数，与 Next.js 深度集成，支持 TypeScript，主打 “前端与边缘逻辑无缝衔接”； - Vercel Edge Functions：适配 Vercel 前端项目的边缘函数，与 Next.js 深度集成，支持 TypeScript，主打 “前端与边缘逻辑无缝衔接”；
回到 Supabase ，当你的应用需要执行 “不能在客户端（浏览器）完成” 的逻辑时，比如用私密密钥调用第三方 API（如 LLM 接口）、处理计算密集型任务（如图片压缩）、或强制执行权限校验（如文件访问规则）时，Supabase Edge Functions 就能发挥作用。它基于 Deno runtime 和 TypeScript 构建，部署在全球边缘节点上，能以 “靠近用户的物理距离” 实现极低的执行延迟，是编写自定义、可信服务器端逻辑的核心工具。 回到 Supabase ，当你的应用需要执行 “不能在客户端（浏览器）完成” 的逻辑时，比如用私密密钥调用第三方 API（如 LLM 接口）、处理计算密集型任务（如图片压缩）、或强制执行权限校验（如文件访问规则）时，Supabase Edge Functions 就能发挥作用。它基于 Deno runtime 和 TypeScript 构建，部署在全球边缘节点上，能以 “靠近用户的物理距离” 实现极低的执行延迟，是编写自定义、可信服务器端逻辑的核心工具。
@@ -1377,8 +1379,7 @@ Supabase 提供了非常友好的界面，让你无需接触命令行即可完
8. 在弹出的在线编辑器中， **删除所有默认的占位代码** 。 8. 在弹出的在线编辑器中， **删除所有默认的占位代码** 。
9. 打开你本地的 `llm-chat.ts` 文件， **复制其全部内容** 。 9. 打开你本地的 `llm-chat.ts` 文件， **复制其全部内容** 。
10. 将复制的代码**粘贴**到 Supabase 的在线编辑器中。 10. 将复制的代码**粘贴**到 Supabase 的在线编辑器中。
11. **配置****环境变量** ** (Secrets)** : 11. **配置\*\***环境变量\*\* ** (Secrets)** :
1. 在侧边栏找到 Secrets。 1. 在侧边栏找到 Secrets。
![](images/image60.png) ![](images/image60.png)
2. Name: 输入 `OPENAI_API_KEY`。 2. Name: 输入 `OPENAI_API_KEY`。
@@ -1391,8 +1392,8 @@ Supabase 提供了非常友好的界面，让你无需接触命令行即可完
如果你想探索更多可能性，可以参考项目中的其他示例。例如： 如果你想探索更多可能性，可以参考项目中的其他示例。例如：
* 图片生成 ( txt2img.ts ) : 这个函数展示了如何利用 Edge Function 调用第三方的文生图（Text-to-Image）API（如 Stability AI, Midjourney 等）来动态生成图片。这是一种典型的计算密集型或需要安全调用外部服务的场景。与 llm-chat 案例一样，API 密钥被安全地存储在 Supabase 后端，前端只负责发送文本描述，然后接收并展示生成的图片，整个过程安全、高效。 - 图片生成 ( txt2img.ts ) : 这个函数展示了如何利用 Edge Function 调用第三方的文生图（Text-to-Image）API（如 Stability AI, Midjourney 等）来动态生成图片。这是一种典型的计算密集型或需要安全调用外部服务的场景。与 llm-chat 案例一样，API 密钥被安全地存储在 Supabase 后端，前端只负责发送文本描述，然后接收并展示生成的图片，整个过程安全、高效。
* 发送邮件 ( send-email.ts ) : 在应用中发送欢迎邮件、交易通知或密码重置邮件是常见需求。 send-email.ts 示例演示了如何通过 Edge Function 集成邮件服务（如 Resend, SendGrid）。你无需在客户端代码中暴露敏感的邮件服务 API Key，只需创建一个函数，让前端通过调用这个函数来触发邮件发送。 - 发送邮件 ( send-email.ts ) : 在应用中发送欢迎邮件、交易通知或密码重置邮件是常见需求。 send-email.ts 示例演示了如何通过 Edge Function 集成邮件服务（如 Resend, SendGrid）。你无需在客户端代码中暴露敏感的邮件服务 API Key，只需创建一个函数，让前端通过调用这个函数来触发邮件发送。
## 5.6 Clerk Login ## 5.6 Clerk Login
@@ -1586,10 +1587,10 @@ serve(async (req) => {
}) })
``` ```
初始化 Supabase 数据表与函数结束后，你还需要在 Clerk 中启用 Webhooks 支持： 初始化 Supabase 数据表与函数结束后，你还需要在 Clerk 中启用 Webhooks 支持：
* 在 Clerk Dashboard -> **Webhooks** 中添加 Endpoint，填入Supabase Edge Function 的 URL。 - 在 Clerk Dashboard -> **Webhooks** 中添加 Endpoint，填入Supabase Edge Function 的 URL。
* 勾选 `user.created`, `user.updated`, `user.deleted` 等事件。 - 勾选 `user.created`, `user.updated`, `user.deleted` 等事件。
![](images/image65.png) ![](images/image65.png)
@@ -1599,8 +1600,8 @@ serve(async (req) => {
在深入了解如何对 Clerk 支持第三方登录前，我们先明确两个核心概念：开发环境与生产环境，这是软件从 “开发测试” 到 “上线可用” 的两个关键阶段，二者的定位、用途和安全要求截然不同： 在深入了解如何对 Clerk 支持第三方登录前，我们先明确两个核心概念：开发环境与生产环境，这是软件从 “开发测试” 到 “上线可用” 的两个关键阶段，二者的定位、用途和安全要求截然不同：
* 开发环境：开发者本地或测试服务器使用的环境，仅用于功能开发、调试和内部验证（如本地 localhost:3000 服务），不对外开放 - 开发环境：开发者本地或测试服务器使用的环境，仅用于功能开发、调试和内部验证（如本地 localhost:3000 服务），不对外开放
* 生产环境：应用正式上线后，面向真实用户的公开环境（如部署在 Vercel、阿里云等平台的 https://my-app.com） - 生产环境：应用正式上线后，面向真实用户的公开环境（如部署在 Vercel、阿里云等平台的 https://my-app.com）
而 Clerk 对社交登录区分这两种环境，本质是平衡 “开发效率” 与 “生产安全”：开发阶段需减少冗余配置以快速验证功能，生产阶段需通过专属凭证保障数据安全，同时符合 Google、GitHub 等第三方 OAuth 平台的规则（线上应用必须绑定专属域名与凭证，不允许使用共享资源）。下面具体说明两种环境下 Clerk 社交登录的差异配置： 而 Clerk 对社交登录区分这两种环境，本质是平衡 “开发效率” 与 “生产安全”：开发阶段需减少冗余配置以快速验证功能，生产阶段需通过专属凭证保障数据安全，同时符合 Google、GitHub 等第三方 OAuth 平台的规则（线上应用必须绑定专属域名与凭证，不允许使用共享资源）。下面具体说明两种环境下 Clerk 社交登录的差异配置：
@@ -1608,10 +1609,10 @@ serve(async (req) => {
开发环境中，Clerk 已预置共享 OAuth 凭证和默认重定向 URI，无需前往 GitHub/Google 申请专属凭证，操作步骤如下： 开发环境中，Clerk 已预置共享 OAuth 凭证和默认重定向 URI，无需前往 GitHub/Google 申请专属凭证，操作步骤如下：
* 登录 Clerk Dashboard ，在左侧导航栏进入 SSO connections （SSO 连接）页面。 - 登录 Clerk Dashboard ，在左侧导航栏进入 SSO connections （SSO 连接）页面。
* 点击 Add connection （添加连接），选择 For all users （对所有用户生效）。 - 点击 Add connection （添加连接），选择 For all users （对所有用户生效）。
* 在 Choose provider （选择提供商）下拉菜单中，按需选择 GitHub 或 Google 。 - 在 Choose provider （选择提供商）下拉菜单中，按需选择 GitHub 或 Google 。
* 直接点击 Add connection （添加连接），Clerk 会自动用共享凭证完成绑定。 - 直接点击 Add connection （添加连接），Clerk 会自动用共享凭证完成绑定。
配置后，本地启动应用（如 `localhost:3000`）并点击“Sign in with GitHub/Google”，Clerk 会自动代理登录请求，快速验证功能是否正常。 配置后，本地启动应用（如 `localhost:3000`）并点击“Sign in with GitHub/Google”，Clerk 会自动代理登录请求，快速验证功能是否正常。
@@ -1621,23 +1622,23 @@ serve(async (req) => {
应用部署上线（如 Vercel、阿里云）并切换到 Clerk Production Instance 后，共享凭证失效，需为 GitHub/Google 配置自定义 OAuth 凭证（建议同时打开 Clerk Dashboard 和第三方平台页面，方便同步操作）： 应用部署上线（如 Vercel、阿里云）并切换到 Clerk Production Instance 后，共享凭证失效，需为 GitHub/Google 配置自定义 OAuth 凭证（建议同时打开 Clerk Dashboard 和第三方平台页面，方便同步操作）：
* 前置通用操作（Clerk 控制台）： - 前置通用操作（Clerk 控制台）：
* 进入 Clerk SSO connections 页面，点击 Add connection → 选择 For all users 。 - 进入 Clerk SSO connections 页面，点击 Add connection → 选择 For all users 。
* 选择目标平台（GitHub/Google），确保开启 Enable for sign-up and sign-in （允许注册登录）和 Use custom credentials （使用自定义凭证）。 - 选择目标平台（GitHub/Google），确保开启 Enable for sign-up and sign-in （允许注册登录）和 Use custom credentials （使用自定义凭证）。
* 复制页面中的 Authorization Callback URL （GitHub）或 Authorized Redirect URI （Google），保存到安全位置，不要关闭当前页面/弹窗。 - 复制页面中的 Authorization Callback URL （GitHub）或 Authorized Redirect URI （Google），保存到安全位置，不要关闭当前页面/弹窗。
* 2.1 GitHub 平台配置： - 2.1 GitHub 平台配置：
* 登录 GitHub，进入 Developer Settings （路径：头像 → Settings → Developer settings → OAuth Apps）。 - 登录 GitHub，进入 Developer Settings （路径：头像 → Settings → Developer settings → OAuth Apps）。
* 点击 New OAuth app ，填写信息：`Application name`（应用名称）、`Homepage URL`（生产域名，如 `https://my-app.com`）、`Authorization Callback URL`（粘贴从 Clerk 复制的地址）。 - 点击 New OAuth app ，填写信息：`Application name`（应用名称）、`Homepage URL`（生产域名，如 `https://my-app.com`）、`Authorization Callback URL`（粘贴从 Clerk 复制的地址）。
* 点击 Register application ，再点击 Generate a new client secret ，保存生成的 Client ID 和 Client Secret （Secret 仅显示一次）。 - 点击 Register application ，再点击 Generate a new client secret ，保存生成的 Client ID 和 Client Secret （Secret 仅显示一次）。
* 回到 Clerk 弹窗，粘贴 Client ID 和 Client Secret，点击 Add connection 完成配置（若关闭弹窗，可在 SSO connections 找到 GitHub 连接，在“Use custom credentials”模块补填）。 - 回到 Clerk 弹窗，粘贴 Client ID 和 Client Secret，点击 Add connection 完成配置（若关闭弹窗，可在 SSO connections 找到 GitHub 连接，在“Use custom credentials”模块补填）。
* 2.2 Google 平台配置： - 2.2 Google 平台配置：
* 登录 Google Cloud Console ，选择已有项目或新建项目（如“My App Production”）。 - 登录 Google Cloud Console ，选择已有项目或新建项目（如“My App Production”）。
* 点击左上角菜单 → APIs & Services → Credentials ，点击 Create Credentials → OAuth client ID （首次配置需先完成 OAuth consent screen 设置，选择“External”并填写应用信息）。 - 点击左上角菜单 → APIs & Services → Credentials ，点击 Create Credentials → OAuth client ID （首次配置需先完成 OAuth consent screen 设置，选择“External”并填写应用信息）。
* 选择 Application type 为 Web application ，配置： - 选择 Application type 为 Web application ，配置：
1. `Authorized JavaScript origins`：添加生产域名（如 `https://my-app.com`、`https://www.my-app.com`），本地验证可补充 `http://localhost:端口号`。 1. `Authorized JavaScript origins`：添加生产域名（如 `https://my-app.com`、`https://www.my-app.com`），本地验证可补充 `http://localhost:端口号`。
2. `Authorized Redirect URIs`：粘贴从 Clerk 复制的地址。 2. `Authorized Redirect URIs`：粘贴从 Clerk 复制的地址。
* 点击 Create ，保存弹窗中的 Client ID 和 Client Secret ，回到 Clerk 弹窗粘贴并点击 Add connection 。 - 点击 Create ，保存弹窗中的 Client ID 和 Client Secret ，回到 Clerk 弹窗粘贴并点击 Add connection 。
* 关键注意事项： - 关键注意事项：
1. 禁止 WebView 登录：Google OAuth 不支持应用内浏览器登录，需参考 [Google 官方文档](https://support.google.com/cloud/answer/7657789) 调整。 1. 禁止 WebView 登录：Google OAuth 不支持应用内浏览器登录，需参考 [Google 官方文档](https://support.google.com/cloud/answer/7657789) 调整。
2. 切换发布状态：默认“Testing”状态仅支持 100 个测试用户，需在 OAuth consent screen 将“Publishing status”改为 In production （需通过 Google 审核）。 2. 切换发布状态：默认“Testing”状态仅支持 100 个测试用户，需在 OAuth consent screen 将“Publishing status”改为 In production （需通过 Google 审核）。
3. 阻止子邮箱：Clerk 默认拦截含 `+`/`=`/`#` 的 Google 邮箱（如 `user+alias@example.com`），可在 Google 连接详情页开启/关闭 Block email subaddresses （建议开启提升安全性）。 3. 阻止子邮箱：Clerk 默认拦截含 `+`/`=`/`#` 的 Google 邮箱（如 `user+alias@example.com`），可在 Google 连接详情页开启/关闭 Block email subaddresses （建议开启提升安全性）。
@@ -1647,11 +1648,11 @@ serve(async (req) => {
配置完成后，通过 Clerk 内置 Account Portal 验证功能： 配置完成后，通过 Clerk 内置 Account Portal 验证功能：
* 进入 Clerk Dashboard，左侧导航栏进入 Account Portal 页面。 - 进入 Clerk Dashboard，左侧导航栏进入 Account Portal 页面。
* 在“Sign-in”模块右侧，点击“访问登录页面”按钮，跳转至对应环境登录页： - 在“Sign-in”模块右侧，点击“访问登录页面”按钮，跳转至对应环境登录页：
* 开发环境：`https://你的域名.accounts.dev/sign-in`（如 `https://my-app.accounts.dev/sign-in`）。 - 开发环境：`https://你的域名.accounts.dev/sign-in`（如 `https://my-app.accounts.dev/sign-in`）。
* 生产环境：`https://accounts.你的域名.com/sign-in`（如 `https://accounts.my-app.com/sign-in`）。 - 生产环境：`https://accounts.你的域名.com/sign-in`（如 `https://accounts.my-app.com/sign-in`）。
* 点击“Sign in with GitHub/Google”，用对应平台账号登录，若能成功跳转并返回应用，说明连接配置正常。 - 点击“Sign in with GitHub/Google”，用对应平台账号登录，若能成功跳转并返回应用，说明连接配置正常。
# 6. 从 Supabase 到更多后端开发组件（进阶） # 6. 从 Supabase 到更多后端开发组件（进阶）
@@ -1659,9 +1660,9 @@ serve(async (req) => {
但从更长期、更工程化的角度来看， **Supabase 提供的每一块能力（Auth / Storage / Edge Functions / Realtime / Database），在业界几乎都有对应的专业替代方案** ——既包括同类 BaaS 平台，也包括更“单点突破”的云服务和开源组件。作为上进的个人开发者和初创团队来说，了解这些替代选项有几个好处： 但从更长期、更工程化的角度来看， **Supabase 提供的每一块能力（Auth / Storage / Edge Functions / Realtime / Database），在业界几乎都有对应的专业替代方案** ——既包括同类 BaaS 平台，也包括更“单点突破”的云服务和开源组件。作为上进的个人开发者和初创团队来说，了解这些替代选项有几个好处：
* 判断当前项目是否“全用 Supabase 就够了”，还是某一块需要更专业/更便宜/更易合规的专用服务； - 判断当前项目是否“全用 Supabase 就够了”，还是某一块需要更专业/更便宜/更易合规的专用服务；
* 当项目规模变大或需求变复杂时，是否可以把某个模块从 Supabase 替换出去（例如改用专门的 Auth 平台或对象存储），而不是一开始就被平台彻底锁死； - 当项目规模变大或需求变复杂时，是否可以把某个模块从 Supabase 替换出去（例如改用专门的 Auth 平台或对象存储），而不是一开始就被平台彻底锁死；
* 拓宽技术选型视野，即使暂时不更换，也能大致知道“如果不用 Supabase 的 X 功能，我还有哪些常见选择”。 - 拓宽技术选型视野，即使暂时不更换，也能大致知道“如果不用 Supabase 的 X 功能，我还有哪些常见选择”。
本节将分别介绍 Supabase 所覆盖的几大能力在市场上的主流替代方案，例如：认证（Auth）、文件存储（Storage）、边缘函数（Edge Functions）、实时通信（Realtime）、数据库托管等。简单对比它们在功能特性、免费额度/定价、易用性以及社区流行度等方面的差异， 让你对后端组件工具库有更全面的理解。 本节将分别介绍 Supabase 所覆盖的几大能力在市场上的主流替代方案，例如：认证（Auth）、文件存储（Storage）、边缘函数（Edge Functions）、实时通信（Realtime）、数据库托管等。简单对比它们在功能特性、免费额度/定价、易用性以及社区流行度等方面的差异， 让你对后端组件工具库有更全面的理解。
@@ -1674,7 +1675,7 @@ serve(async (req) => {
| Firebase（Google） | 全托管 BaaS（Auth + Firestore + Storage + Functions + Hosting） | Spark：免费轻量额度；Blaze：按量计费（Firestore/Storage/Functions 分别算） | 行业最成熟、文档好、上手快、实时能力强。适用于中小型产品、移动/前端主导团队。缺点：计费复杂、锁定性强、查询限制多（尤其 Firestore）。 | | Firebase（Google） | 全托管 BaaS（Auth + Firestore + Storage + Functions + Hosting） | Spark：免费轻量额度；Blaze：按量计费（Firestore/Storage/Functions 分别算） | 行业最成熟、文档好、上手快、实时能力强。适用于中小型产品、移动/前端主导团队。缺点：计费复杂、锁定性强、查询限制多（尤其 Firestore）。 |
| Supabase | 开源 BaaS（Postgres + Auth + Storage + Edge Functions + Realtime） | 免费：500MB DB、1GB Storage、无服务器函数少量调用；Pro：按实例计费 | 最像 Firebase 的 SQL 版；界面优秀、体验现代、可自托管。适用于需要强 SQL、BI、事务能力的应用。缺点：高并发或复杂函数成本较高。 | | Supabase | 开源 BaaS（Postgres + Auth + Storage + Edge Functions + Realtime） | 免费：500MB DB、1GB Storage、无服务器函数少量调用；Pro：按实例计费 | 最像 Firebase 的 SQL 版；界面优秀、体验现代、可自托管。适用于需要强 SQL、BI、事务能力的应用。缺点：高并发或复杂函数成本较高。 |
| Appwrite Cloud | 开源一站式 BaaS（DB + Auth + Storage + Functions + Realtime） | 免费：包含基本 DB/Storage/FaaS；付费按资源级别计费 | 体验现代化、API 统一、可自托管；适合开发者友好的应用快速迭代。缺点：生态还不如 Firebase/Supabase 成熟；性能在大型应用中需要测试。 | | Appwrite Cloud | 开源一站式 BaaS（DB + Auth + Storage + Functions + Realtime） | 免费：包含基本 DB/Storage/FaaS；付费按资源级别计费 | 体验现代化、API 统一、可自托管；适合开发者友好的应用快速迭代。缺点：生态还不如 Firebase/Supabase 成熟；性能在大型应用中需要测试。 |
| Nhost | Postgres + GraphQL + Auth + Storage + Functions | 免费：1GB DB、1GB Storage、少量函数调用 | 类似“Supabase + Hasura”；天然 GraphQL；适合前端团队与 React/Next.js 项目。缺点：生态小、成本随用量升高。 | | Nhost | Postgres + GraphQL + Auth + Storage + Functions | 免费：1GB DB、1GB Storage、少量函数调用 | 类似“Supabase + Hasura”；天然 GraphQL；适合前端团队与 React/Next.js 项目。缺点：生态小、成本随用量升高。 |
| AWS Amplify | AWS 一站式后端（Cognito + AppSync + DynamoDB + Storage + Functions + Hosting） | 免费：Hosting 额度 + Cognito 10k MAU + 部分函数额度 | 大而全，适合已有 AWS 基础的团队；企业级可靠性。缺点：最难上手，服务碎片化；初创团队维护成本高。 | | AWS Amplify | AWS 一站式后端（Cognito + AppSync + DynamoDB + Storage + Functions + Hosting） | 免费：Hosting 额度 + Cognito 10k MAU + 部分函数额度 | 大而全，适合已有 AWS 基础的团队；企业级可靠性。缺点：最难上手，服务碎片化；初创团队维护成本高。 |
| Xata（近两年快速增长） | 多模型数据库 + Auth + Edge Functions | 免费：250k 记录、15GB 带宽 | 虽然更偏「DB + API」，但提供 Auth、文件、逻辑，可作为轻量全栈后端。UI/开发体验极佳。缺点：功能不如 Firebase/Supabase 全面。 | | Xata（近两年快速增长） | 多模型数据库 + Auth + Edge Functions | 免费：250k 记录、15GB 带宽 | 虽然更偏「DB + API」，但提供 Auth、文件、逻辑，可作为轻量全栈后端。UI/开发体验极佳。缺点：功能不如 Firebase/Supabase 全面。 |
| Convex（开发者体验极强） | 托管数据库 + Auth + Functions（前端优先） | 免费开发版；付费按请求量计费 | 极简上手；无需 schema；前端写函数即可用后端。适合 MVP/快速验证。缺点：高度绑定平台，迁移成本高；不算完全传统 BaaS。 | | Convex（开发者体验极强） | 托管数据库 + Auth + Functions（前端优先） | 免费开发版；付费按请求量计费 | 极简上手；无需 schema；前端写函数即可用后端。适合 MVP/快速验证。缺点：高度绑定平台，迁移成本高；不算完全传统 BaaS。 |
docs/public/logo.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 374 KiB

docs/stage-0/0.1-learning-map/index.md
+122
View File
@@ -0,0 +1,122 @@
# 从创意到 AI 产品
我们正身处由大语言模型（LLM）推动的人工智能应用爆发期。与以往AI开发高度依赖算法研究不同，**当前行业的重心已转向如何有效利用现有强大模型，构建具有实际价值的应用。**这一转变大幅降低了AI开发的门槛，将焦点从"从零开始构建模型"转移到"将AI能力封装为可落地的解决方案"。
对大多数人而言，如今最大的机遇并非发明新算法，而是学会如何借助AI编码工具快速实现想法。
AI coding的出现正在改写传统编程学习的规则。你不再需要花费数年时间精通某门语言的每个细节，而是可以通过与AI协作，**以"vibecoding"的方式将创意直接转化为可运行的代码**。会使用大模型生成代码片段只是起点。
当前真正的挑战在于：如何引导AI生成高质量、可维护的代码？如何将前后端代码组装成完整应用并成功部署上线？在AI时代，如何将文本生成、图像处理、语音识别等AI能力集成到你的应用中？本课程正是为应对这些挑战而设计。
我们不空谈理论，聚焦于AI辅助编程的端到端实战——**从利用 AI IDE 等工具快速构建原型，到将想法落地为真实可用的产品**。你将学会如何与AI高效协作编码，如何利用vibecoding思维快速迭代，如何调用常见的AI功能（文本生成、图像处理等）为应用赋能，以及如何完成从开发到上线的完整闭环。
# 为什么要学这个？它将如何帮助我的未来？
本课程专为初级水平的学生设计，侧重于 AI 原生应用的实际开发和创新思维培养。通过三个循序渐进的学习阶段，你将从零基础逐步成长为能够独立开发和运营 AI 应用的全栈开发者。
## 三个阶段的成长路径：从“会用 AI”到“会做 AI 产品”
**第零阶段：体验 AI 编程的魔力**
通过贪吃蛇等小游戏，你将第一次体验到 AI 辅助编程的能力与边界。这个阶段不需要任何编程基础，只需要你愿意动手尝试——看着 AI 在几分钟内帮你生成一个可玩的游戏，你会直观感受到 vibecoding 的强大。
**第一阶段：掌握产品开发的完整闭环**
学会使用 AI IDE（如 Cursor、Claude 等工具）将想法转化为可运行的 Web 应用原型。你将学习如何拆解需求、设计多页面应用、接入 AI 能力（文本生成、图像处理等），并用模拟数据完成一个完整的产品 demo。这个阶段结束时，你能独立完成一个像“霍格沃茨画像”那样接入 AI 能力的前端应用。
**第二阶段：成为能上线产品的工程师**
这是质的飞跃。你将学习现代 Web 开发的核心技能：从 Figma 设计稿到组件化前端实现，从 Supabase 数据库到 API 接口开发，从 Git 版本管理到 Zeabur 部署上线。更重要的是，你将学会集成支付系统（如 Stripe），让你的应用具备真实的商业价值。通过 Dify 等工具，你还将掌握知识库与工作流的构建，为应用注入更强的 AI 能力。
**第三阶段：构建跨平台的复杂应用**
掌握多平台开发能力，将同一个应用部署到 Web、微信小程序、安卓等多个平台。学习 MCP 等高级工具扩展 IDE 能力，深入理解 RAG 原理并使用 LangGraph 等框架设计复杂的 AI 工作流。这个阶段你将具备高级工程师的思维方式和工具链。
## 你将获得的核心能力
通过这个完整的学习路径，你将获得：
- **Vibe Coding开发能力：** 熟练使用 vibecoding 思维和 AI 编码工具，将开发效率提升数倍。不再需要死记硬背语法，而是学会如何引导 AI 生成高质量代码。
- **全栈开发技能：** 从 UI 设计到前端实现，从数据库设计到 API 开发，从本地开发到云端部署，掌握现代 Web 应用的完整技术栈。
- **AI 能力集成：** 学会调用各类多模态 AI API，将文本、图像、语音等 AI 能力无缝集成到你的应用中，并通过 RAG 等技术构建智能化产品。
- **产品思维与运营能力：** 从用户研究到需求拆解，从 MVP 设计到产品迭代，从支付集成到用户管理，形成完整的产品开发与运营闭环。
# 第一阶段学习目标
本阶段本质上是一套“AI 产品经理 Vibe Coding 能力培训课程”，主要面向希望进入 AI 产品方向、但编程基础较弱或几乎为零的同学，目标是在 AI 的帮助下完成一个“能跑、能展示”的 Web 应用原型。
```
## 模块一：AI 时代，会说话就会编程
- 1.1 普通人的困境与机会？
- 1.2 AI 能帮你做到什么程度？
- 1.3 动手：你的第一个 AI 原生应用
## 模块二：认识 AI IDE 工具
- 2.1 写代码需要什么环境和工具
- 2.2 什么是 IDE，为什么需要 IDE
- 2.3 AI IDE 和普通 IDE 有什么不同
- 2.4 界面上每个按钮是干什么的
- 2.5 怎么跟 AI 说话才有效
## 模块三：动手做出原型
- 3.1 把需求变成代码的过程
- 3.2 从一个单页面开始
- 3.3 遇到报错了怎么办
- 3.4 做多个页面的应用
- 3.5 把原型做得像那么回事
## 模块四：给原型加上 AI 能力
- 4.1 什么是 AI 能力接入（API 调用）
- 4.2 如何接入文生图能力
- 4.3 如何接入视频生成能力
- 4.4 其他常见 AI 能力的接入方法
- 4.5 成本控制和错误处理
## 模块五：完整项目实战
- 5.1 制造模拟数据让原型看起来真实
- 5.2 收集反馈并快速调整
- 5.3 展示你的成果
## 大作业
- 做一个完整的 Web 应用原型并展示
## 附录A：产品思维补充
- A.1 什么是好的产品想法
- A.2 如何发现用户真正的需求
- A.3 功能优先级怎么排
- A.4 MVP 思维：最小可行产品
## 附录B：常见报错及解决方案
- B.1 页面显示空白或不加载
- B.2 数据保存不成功
- B.3 样式显示不正常
- B.4 点击按钮没反应
- B.5 API 调用失败
- B.6 如何把报错信息有效地反馈给 AI
```
# 为什么要用项目制来训练？
原因其实很简单：按照大多数同学现在的状态，直接走入职场，很可能会在真实项目和老板 / 客户的“社会毒打”下寸步难行。现实世界更常见的场景是：
> 你的导师 / 老板：我们要做一个 xxx，目标是达到 yyy 的效果。
>
> 文档？现成框架？详细的需求说明？很多时候都不存在。
真实工作中的许多任务，本质上就是在高度不确定的环境下解决从未见过的问题：需求是模糊的，边界是变化的，没人告诉你标准答案，你需要自己查资料、做实验、搭原型、不断迭代，最后给出一个“能跑、能用、能上线”的解决方案。
这门课想做的，就是在一个相对安全的环境里，提前给你一次“模拟社会毒打”：
- 通过看似有一定难度的项目任务，迫使你练习拆解问题、设计方案、自己寻找资料
- 通过不那么“傻瓜化”的脚手架和代码，让你学会阅读、理解和改造一份中大型代码库
- 通过从创意到上线的完整闭环，让你体验真实产品从 0 到 1 的完整过程
短期来看，这种训练确实比较折磨人；但从长期来看，它会极大提高你在求职和职业发展中的竞争力：你会更能扛事儿，更能在不确定环境中找到突破口，也更有能力把 AI 变成真正落地的产品，而不是停留在“玩玩 Demo”阶段。
# 坚持了好久还是搞不定，我想放弃了
也许是你坚持的方法不对。不要一个人在黑暗中硬撑，可以来跟作者和助教们聊聊：把你已经尝试过的方法、遇到的具体卡点、和你目前的心理状态，坦诚地说出来。很多时候，只要稍微调整一下方向、补上一个关键知识点，你就能继续往前走。
# 我觉得教程有的设计不合理
欢迎随时联系作者、提交 issue，或者在群里 / 课堂上直接反馈。我们非常希望和你一起把这套教程打磨得越来越好：哪里不清晰、哪里体验不好、哪里让你白费力气，都可以坦诚指出来。越真实、越具体的反馈，越能帮助后来者少踩坑。
# Reference
- [南京大学 计算机科学与技术系 计算机系统基础 课程实验](https://nju-projectn.github.io/ics-pa-gitbook/ics2025/)
docs/project/chapter1/images/1767350588191.png → docs/stage-0/0.2-ai-capabilities-through-games/images/1767350588191.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 623 KiB

After

Width:  |  Height:  |  Size: 623 KiB

docs/project/chapter1/images/image1.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image1.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.1 MiB

After

Width:  |  Height:  |  Size: 1.1 MiB

docs/project/chapter1/images/image10.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image10.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 64 KiB

After

Width:  |  Height:  |  Size: 64 KiB

docs/project/chapter1/images/image11.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image11.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 107 KiB

After

Width:  |  Height:  |  Size: 107 KiB

docs/project/chapter1/images/image12.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image12.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 379 KiB

After

Width:  |  Height:  |  Size: 379 KiB

docs/project/chapter1/images/image13.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image13.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 373 KiB

After

Width:  |  Height:  |  Size: 373 KiB

docs/project/chapter1/images/image14.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image14.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 656 KiB

After

Width:  |  Height:  |  Size: 656 KiB

docs/project/chapter1/images/image15.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image15.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 318 KiB

After

Width:  |  Height:  |  Size: 318 KiB

docs/project/chapter1/images/image16.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image16.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 41 KiB

After

Width:  |  Height:  |  Size: 41 KiB

docs/project/chapter1/images/image17.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image17.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 283 KiB

After

Width:  |  Height:  |  Size: 283 KiB

docs/project/chapter1/images/image18.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image18.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 119 KiB

After

Width:  |  Height:  |  Size: 119 KiB

docs/project/chapter1/images/image19.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image19.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 127 KiB

After

Width:  |  Height:  |  Size: 127 KiB

docs/project/chapter1/images/image2.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image2.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 108 KiB

After

Width:  |  Height:  |  Size: 108 KiB

docs/project/chapter1/images/image20.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image20.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 223 KiB

After

Width:  |  Height:  |  Size: 223 KiB

docs/project/chapter1/images/image21.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image21.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 385 KiB

After

Width:  |  Height:  |  Size: 385 KiB

docs/project/chapter1/images/image22.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image22.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 299 KiB

After

Width:  |  Height:  |  Size: 299 KiB

docs/project/chapter1/images/image23.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image23.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 98 KiB

After

Width:  |  Height:  |  Size: 98 KiB

docs/project/chapter1/images/image24.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image24.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 268 KiB

After

Width:  |  Height:  |  Size: 268 KiB

docs/project/chapter1/images/image25.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image25.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 167 KiB

After

Width:  |  Height:  |  Size: 167 KiB

docs/project/chapter1/images/image26.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image26.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 640 KiB

After

Width:  |  Height:  |  Size: 640 KiB

docs/project/chapter1/images/image27.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image27.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 13 MiB

After

Width:  |  Height:  |  Size: 13 MiB

docs/project/chapter1/images/image28.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image28.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.9 MiB

After

Width:  |  Height:  |  Size: 2.9 MiB

docs/project/chapter1/images/image29.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image29.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 514 KiB

After

Width:  |  Height:  |  Size: 514 KiB

docs/project/chapter1/images/image3.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image3.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 148 KiB

After

Width:  |  Height:  |  Size: 148 KiB

docs/project/chapter1/images/image30.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image30.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 5.3 MiB

After

Width:  |  Height:  |  Size: 5.3 MiB

docs/project/chapter1/images/image31.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image31.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 529 KiB

After

Width:  |  Height:  |  Size: 529 KiB

docs/project/chapter1/images/image32.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image32.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 313 KiB

After

Width:  |  Height:  |  Size: 313 KiB

docs/project/chapter1/images/image33.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image33.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 407 KiB

After

Width:  |  Height:  |  Size: 407 KiB

docs/project/chapter1/images/image34.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image34.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 587 KiB

After

Width:  |  Height:  |  Size: 587 KiB

docs/project/chapter1/images/image35.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image35.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 234 KiB

After

Width:  |  Height:  |  Size: 234 KiB

docs/project/chapter1/images/image36.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image36.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 651 KiB

After

Width:  |  Height:  |  Size: 651 KiB

docs/project/chapter1/images/image37.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image37.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.3 MiB

After

Width:  |  Height:  |  Size: 3.3 MiB

docs/project/chapter1/images/image38.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image38.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.1 MiB

After

Width:  |  Height:  |  Size: 3.1 MiB

docs/project/chapter1/images/image39.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image39.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 124 KiB

After

Width:  |  Height:  |  Size: 124 KiB

docs/project/chapter1/images/image4.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image4.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 238 KiB

After

Width:  |  Height:  |  Size: 238 KiB

docs/project/chapter1/images/image40.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image40.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 183 KiB

After

Width:  |  Height:  |  Size: 183 KiB

docs/project/chapter1/images/image41.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image41.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 442 KiB

After

Width:  |  Height:  |  Size: 442 KiB

docs/project/chapter1/images/image42.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image42.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 540 KiB

After

Width:  |  Height:  |  Size: 540 KiB

docs/project/chapter1/images/image43.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image43.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 4.1 MiB

After

Width:  |  Height:  |  Size: 4.1 MiB

docs/project/chapter1/images/image44.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image44.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.6 MiB

After

Width:  |  Height:  |  Size: 2.6 MiB

docs/project/chapter1/images/image45.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image45.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 3.7 MiB

After

Width:  |  Height:  |  Size: 3.7 MiB

docs/project/chapter1/images/image46.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image46.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.3 MiB

After

Width:  |  Height:  |  Size: 2.3 MiB

docs/project/chapter1/images/image47.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image47.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.1 MiB

After

Width:  |  Height:  |  Size: 1.1 MiB

docs/project/chapter1/images/image48.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image48.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 57 KiB

After

Width:  |  Height:  |  Size: 57 KiB

docs/project/chapter1/images/image49.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image49.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 602 KiB

After

Width:  |  Height:  |  Size: 602 KiB

docs/project/chapter1/images/image5.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image5.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 658 KiB

After

Width:  |  Height:  |  Size: 658 KiB

docs/project/chapter1/images/image50.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image50.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 333 KiB

After

Width:  |  Height:  |  Size: 333 KiB

docs/project/chapter1/images/image51.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image51.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

docs/project/chapter1/images/image52.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image52.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 97 KiB

After

Width:  |  Height:  |  Size: 97 KiB

docs/project/chapter1/images/image53.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image53.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 236 KiB

After

Width:  |  Height:  |  Size: 236 KiB

docs/project/chapter1/images/image54.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image54.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 336 KiB

After

Width:  |  Height:  |  Size: 336 KiB

docs/project/chapter1/images/image55.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image55.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 880 KiB

After

Width:  |  Height:  |  Size: 880 KiB

docs/project/chapter1/images/image56.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image56.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 201 KiB

After

Width:  |  Height:  |  Size: 201 KiB

docs/project/chapter1/images/image57.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image57.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 388 KiB

After

Width:  |  Height:  |  Size: 388 KiB

docs/project/chapter1/images/image58.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image58.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 556 KiB

After

Width:  |  Height:  |  Size: 556 KiB

docs/project/chapter1/images/image6.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image6.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 478 KiB

After

Width:  |  Height:  |  Size: 478 KiB

docs/project/chapter1/images/image7.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image7.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 44 KiB

docs/project/chapter1/images/image9.png → docs/stage-0/0.2-ai-capabilities-through-games/images/image9.png
View File
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 23 KiB

docs/stage-0/0.2-ai-capabilities-through-games/images/index-2026-01-07-18-25-03.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 92 KiB

Some files were not shown because too many files have changed in this diff Show More