VibeCoding实战三个AI小项目-VibeCoding入门笔记02

VibeCoding 实战入门：用 Claude Code 从零做出 3 个 AI 小项目（含全部提示词）

📚 本文系统梳理 前后端关系、SSE 流式输出、提示词写法进化、推理模型双通道 等核心概念，并附 3 个完整实战项目的复盘------三个项目的代码 100% 由 AI 编写，我只负责提需求、验收和迭代 。

内容是我入门 AI 应用开发过程中的学习与整理，适合零基础或想了解"用自然语言驱动 AI 写代码"工作方式的同学。

[VibeCoding 实战的核心方法论](#VibeCoding 实战的核心方法论)
前置知识：前端和后端到底是什么关系
实战一：贪吃蛇------一句话提示词的奇迹
[实战二：AI 聊天机器人→AI 女友------前后端协作](#实战二：AI 聊天机器人→AI 女友——前后端协作)
[实战三：AI 学习计划生成器------最详细的需求文档](#实战三：AI 学习计划生成器——最详细的需求文档)
回看提示词进化之路
三个项目的难度阶梯与知识点地图
实战中踩的坑与解决方案
衍生知识点（进阶补充）
自测题

1. VibeCoding 实战的核心方法论

三个项目做下来，最震撼的事实是：我没手写过一行代码 。贪吃蛇的游戏循环、聊天机器人的流式解析、学习计划的 Excel 落盘------全部由 AI 编写。我的工作只有三件事：提需求 → 验收效果 → 提改进。

1.1 提需求的正确姿势

VibeCoding 的第一课是学会"说话"。同一个需求，两种说法效果天差地别：

❌ 模糊需求	✅ 清晰需求
"做个贪吃蛇"	"用单个 HTML 文件实现贪吃蛇：24×24 网格、三档难度、方向键控制、吃食物加分加速、最高分存 localStorage、深色主题"
"做个 AI 聊天"	"前端 HTML/CSS/JS，后端 Python Flask，对接 OpenAI 兼容接口，要求流式输出、多会话 localStorage 持久化、明暗双主题，API Key 只放后端"

💡 衍生理解------为什么描述要具体？ AI 没有上下文时只能"猜"你的意图：猜得对，一次到位；猜错，来回返工消耗 token。需求写得越像一份小型需求文档，AI 的输出就越接近你要的东西。本文第 6 章会展示我三个项目的真实提示词------你会看到它们从一句话进化成完整需求文档的全过程。

1.2 迭代而不是一次成型

不要指望一次对话出完美产品。健康的节奏是：

复制代码

提需求 → AI 生成 v1 → 运行验证 → 指出问题/提出升级 → AI 修改 v2 → 再验证 → ...

每轮迭代只提 1~2 个明确改动点。最典型的例子：聊天机器人做完后，我用一条"升级提示词"把它改造成了 AI 女友（见 4.6 节）------在已有项目上做增量升级，比从零重写又快又稳。

1.3 CLAUDE.md：给 AI 的项目说明书

每个项目完成后，我都会让 AI 生成一份 CLAUDE.md 放在项目根目录，内容包括：

项目概述：一句话说清这是什么、用什么技术；
常用命令：怎么装依赖、怎么启动、怎么自测；
架构：核心流程图 + 关键设计点（比如"流式解析在哪个函数"）；
测试陷阱：Windows 终端的编码坑、真实消耗额度的注意事项。

💡 衍生理解------为什么要写这个文件？ 下次再打开这个项目（哪怕三个月后），AI 读一遍 CLAUDE.md 就能接上上下文，不需要你重新解释项目结构。它既是给 AI 的记忆，也是给你自己的复习笔记------写不清说明书的项目，说明你自己还没真正理解它。

2. 前置知识：前端和后端到底是什么关系

三个项目里有两个是"前后端分离"的，动手前必须搞懂这对概念。

2.1 一句话定义

角色	是什么	我的项目里是
前端（Frontend）	运行在用户浏览器里的界面代码：用户看到什么、点什么	`index.html` + `css` + `js`
后端（Backend）	运行在服务器/本机上的程序：处理逻辑、连接数据库和大模型	`app.py`（Python Flask）

类比餐厅：前端是前厅（菜单、点菜、上菜摆盘），后端是后厨（真正做菜、管食材、管库存）。客人不进后厨，后厨也不直接端菜给客人。

2.2 它们怎么通信

前后端是两个独立运行的程序，通过 HTTP 请求 对话，通用语言是 JSON：

复制代码

前端（浏览器）                          后端（Flask）
     │  POST /api/chat                      │
     │  请求体: {"messages":[...]}           │
     │ ────────────────────────────────────→ │
     │                                       │  转发给大模型 API
     │                                       │ ↓
     │  响应: SSE 流 data: {"content":"..."}  │
     │ ←──────────────────────────────────── │

三个关键约定：

接口（API）就是两家之间的"窗口" ：前端只认 POST /api/chat 这个地址和它收发的数据格式，完全不关心后厨怎么做；
数据格式用 JSON ：{"姓名": "张三", "年龄": 20} 这种键值对，双方都认识；
AI 应用多了一种特殊响应：SSE 流（第 4 章详讲）------不是一次性给完整数据，而是服务器持续推送小片段。

2.3 为什么非要有后端？直接浏览器连大模型不行吗

这是新手最常见的疑问，也是 AI 应用第一条安全红线：

复制代码

❌ 错误架构                          ✅ 正确架构
浏览器 ──── API Key 暴露！──→ 大模型   浏览器 ──→ 自己的后端 ──→ 大模型
（F12 就能看到 Key，                （Key 只在后端，
  任何人都能偷走盗刷）                  前端零密钥）

后端代理还带来两个附赠好处：

解决跨域（CORS） ：浏览器有安全限制，不允许页面随便请求别的域名。我的做法更彻底------Flask 用 static_folder 直接托管前端页面，前后端同源部署，天然没有跨域问题，还少起一个静态服务器；
统一管理：换大模型、改提示词、加业务规则，只改后端一处，前端完全不用动。

2.4 一次完整请求的旅程

以聊天机器人发一句话为例：

复制代码

你在输入框打字，点发送
  → 前端 JS 把会话历史打包成 JSON，POST 给 /api/chat
    → Flask 收到，取出 API Key，转发给大模型（stream=true）
      → 大模型逐字生成，返回 SSE 流
        → Flask 逐行翻译成自己的 SSE 事件流
          → 前端边收边渲染，你看到打字机效果

看懂这条链路，你就看懂了所有 AI 应用的骨架。

3. 实战一：贪吃蛇------一句话提示词的奇迹

3.1 我的提示词（完整实录）

复制代码

帮我写一个贪吃蛇小游戏

没错，就这一句。AI 交付了一个 snake.html 单文件游戏（HTML5 Canvas + 原生 JavaScript）：三档难度选择、方向键控制、吃食物加分、每 3 个食物加速一次、撞墙/撞自己结束、最高分存 localStorage、深色主题。

3.2 值得学的实现细节

虽然我只给了一句话，AI 写的代码里却有几个"老手才知道"的细节：

javascript 复制代码

// ① 方向缓冲：键盘事件只写 nextDir，游戏节拍才应用
// 防止一帧内连按两键导致 180° 反向自杀（贪吃蛇经典 bug）
keydown → nextDir = 新方向
tick() 开头 → dir = nextDir

// ② 撞自己判定时排除尾巴（尾巴这一帧即将移走，不算碰撞）

// ③ 速度模型：speed 是"走一格的毫秒间隔"，数值越小越快
// 加速 = 缩短间隔，但有 minSpeed 下限防止快到没法玩

💡 衍生知识点------为什么从游戏开始练手？ 游戏的反馈是即时的（下一秒就能玩），验证零成本；而且游戏逻辑（状态机、循环、碰撞）麻雀虽小五脏俱全。VibeCoding 的第一课不是学语法，是建立"我说 → 它做 → 我验证"的肌肉记忆和信心。一句话能做出能玩的游戏，这个心理冲击就是最好的入门仪式。

3.3 怎么验证（无测试框架的项目）

用 Node 的 vm.runInContext 加手写的 DOM/Canvas 桩对象做冒烟测试：提取 <script> 内容，模拟 document.getElementById、setInterval，派发模拟键盘事件断言行为。不涉及逻辑的样式改动不用测，动了碰撞/加速逻辑就先跑一遍。

4. 实战二：AI 聊天机器人→AI 女友------前后端协作

4.1 我的提示词（完整实录）

复制代码

帮我写一个AI聊天机器人
前端利用html，css，js，axios完成。页面你自己设计，主要保证美观即可
后端利用python完成
对接大模型，地址：https://（我的中转站地址），大模型的名字：deepseek-v4-flash
APIKey: sk-（密钥已打码）

对比贪吃蛇的一句话，这里已经说清了技术栈分工（前端用什么/后端用什么）、外部服务（地址/模型名/Key）、审美要求（美观即可）。AI 交付了完整的"星云 AI"聊天应用。

4.2 产出与项目结构

前端：原生 HTML/CSS/JS + axios（本地引入，不依赖 CDN）；
后端：Python Flask；
大模型：OpenAI 兼容接口（deepseek-v4-flash，推理模型）。

chat-robot/
├── backend/
│ ├── app.py # Flask：静态托管 + /api/chat 流式代理
│ └── requirements.txt # flask + requests 两个依赖
├── frontend/
│ ├── index.html
│ ├── css/style.css # 双主题（CSS 变量）
│ └── js/app.js # 会话/流式解析/Markdown 渲染
└── README.md

4.3 核心知识点一：SSE 流式输出（本项目的灵魂）

SSE（Server-Sent Events，服务器推送事件） 是 AI 应用最常见的交互形态------回答不是一次性返回，而是像打字机一样逐字出现。

整条链路：

复制代码

浏览器 app.js（axios onDownloadProgress 边收边解析 SSE）
  → Flask /api/chat（生成器逐行翻译上游 SSE）
    → 大模型 API（stream=true 的响应流）

为什么需要"逐字输出"？ 一方面是体验（10 秒白屏等一大段 vs 逐字看到生成过程，感知完全不同）；另一方面是首字时间：推理模型可能思考几十秒，流式让用户第一时间看到"它在思考"，而不是以为程序卡死了。

4.4 核心知识点二：推理模型的双通道输出

deepseek-v4-flash 是推理模型，回答前会先输出一段思考过程。API 返回的增量（delta）里有两个字段：

json 复制代码

{"delta": {"reasoning_content": "思考过程片段..."}}   // 阶段一：思考
{"delta": {"content": "正式回答片段..."}}              // 阶段二：正文

后端把它们翻译成两种自定义 SSE 事件转发，前端分别渲染：

reasoning_content → 可折叠的"深度思考"盒子（默认收起）；
content → 正文聊天气泡。

⚠️ 易错点 ：如果后端只转发 content，前端在模型思考的 70~90 秒里就是黑盒干等------用户以为卡死了。做推理模型的应用，"让思考过程可见"不是锦上添花，是核心体验设计。

4.5 前端流式解析的技巧（全项目最精巧的部分）

浏览器端 axios 不支持 ReadableStream，流式解析靠 onDownloadProgress 回调：每次回调拿到的是累积的 responseText，所以要：

按 \n\n 切分 SSE 事件（SSE 协议规定事件以空行分隔）；
用 consumedEvents 计数器记住已消费的事件数，只处理新增的完整事件；
尾部不完整的块（还没收到结束的 \n\n）留给下一次回调处理。

这本质上是手工实现了流式解析器的"断句"逻辑------网络分包不管你 JSON 切在哪，你必须自己维护边界。

4.6 迭代升级：一条提示词把聊天机器人改造成 AI 女友

项目跑通后，我追加了一条升级提示词：

复制代码

我现在要把当前文件夹中的项目去改成AI女友对话机器人
前端页面刚启动的时候会让你选择女友的性格，温柔，暴躁，犀利，害羞等
选择性格之后，输入自己给女友起的名字，最后再进入到AI对话机器人的聊天框中
此时AI就扮演我设定好的女友跟我对话
你帮我修改前端，后端相关的模块

AI 在不推翻原有代码的前提下完成了增量改造：前端加了"性格选择 → 起名 → 进聊天框"的引导流程，后端把性格设定拼进发给大模型的系统提示词，让模型始终"扮演"这个角色。

💡 衍生理解------这是 VibeCoding 迭代式开发的完美范例 ：改造方向（选性格→起名→对话）、角色约束（AI 扮演设定好的女友）说得清清楚楚，但不规定实现细节（信任 AI 决定怎么改前后端模块）。升级提示词的要点是"说清要什么新体验"，而不是"教 AI 怎么写"。

从技术上看，"AI 女友"和"AI 聊天"的差别只在于系统提示词（System Prompt）里的角色设定------这正是所有 AI 角色扮演产品（AI 伴侣、AI 客服、AI 面试官）的核心原理。

5. 实战三：AI 学习计划生成器------最详细的需求文档

5.1 我的提示词（节选实录，完整版更长）

复制代码

帮我制作一个学习计划程序，给自己定制一个具体的学习建议，并给出可实施的方案，
并把最终的结果保存到本地Excel中。文件名就叫做:学习计划。

前端页面逻辑:
  姓名:后面是输入框，自己输入
  性别:后面是单选按钮，自己选择
  年龄:后面是输入框，自己输入
  学历:后面是下拉框，内容为:硕士及以上，本科，专升本，专科，其他，默认显示本科
  知识基础:后面是输入框，输入自己会的计算机知识，比如:MySQL、C语言基础语法，不会就输入0基础
  学习习惯:后面是输入框，输入自己的学习习惯，比如:早上昏昏欲睡，中午吃完饭犯困，晚上精神百倍
  点击生成学习计划之后，将输入的信息发送给后端。

后端页面逻辑:
  1.接收前端发送过来的学生信息
  2.先简单的初步判断：
    a.学历选择其他，表示低于专科，不需要访问大模型，直接劝退。
      给前端返回:同学，可以考虑其他非开发类的方向。
  3.将前端发送过来的学生信息，还有学习路线安排，一起发送给大模型。

  （课程安排如下------8 门课程清单）
  备注:因为学习内容是固定的，所以直接保存在后端，不需要前端输入。

这份提示词已经是一份正经的需求文档了：前端每个字段的控件类型（输入框/单选/下拉框）、下拉框的选项和默认值、后端的判断分支、甚至"课程固定放后端"这种数据归属决策都写明了。

5.2 产出

整个项目就三个文件：index.html + app.py（Flask）+ requirements.txt（flask、openai、openpyxl）。功能：表单收集学生信息 → 后端组装提示词 → 大模型流式生成个性化学习计划 → 前端进度条 → 自动保存 Excel（学习计划.xlsx）。

5.3 核心知识点一：提示词的工程化拼接

后端不是简单转发用户输入，而是组装了一份结构化提示词：

python 复制代码

提示词 = 【学生信息】(表单数据)
       + 【课程安排】(后端硬编码的 8 门课, "必须覆盖以下全部课程")
       + 【要求】(5 条明确指令: 逐门给建议/作息安排/阶段划分/薄弱点补充/排版要求)

💡 衍生理解------这是提示词工程（Prompt Engineering）的基本范式 ：数据 + 约束 + 输出格式三段式。把"你是谁、有什么信息、必须做什么、按什么格式"全部说死，模型的输出才稳定可预期。

5.4 核心知识点二：业务硬规则不交给 AI

需求里那条"学历为其他直接劝退"，AI 用后端代码实现------判断学历字段，返回 reject 事件，根本不访问大模型。

方案	问题
❌ 让 AI 判断要不要劝退	多消耗一次调用、可能判断不稳定、响应慢
✅ 代码硬判断，AI 只负责生成	秒回、零成本、100% 可靠

💡 衍生理解------这是 AI 应用设计的黄金原则：确定性的业务规则用代码，创造性的内容生成交给 AI。不要把 AI 当万能锤子：能用 if-else 100% 解决的事，绝不花 token 让模型"大概率"解决。

5.5 核心知识点三：自定义 SSE 事件协议

这个项目把前后端通信协议用得更系统，定义了 5 种事件类型驱动整个前端 UI：

type	含义	前端行为
`thinking`	模型思考片段	进度条 0→30% 阶段
`chunk`	正文片段	进度条 30→95%，内容渲染
`done`	完成，Excel 已保存	进度条 100%，提示文件位置
`reject`	劝退	展示劝退文案
`error`	出错	展示错误 + 重试提示

前端用 fetch + resp.body.getReader() 逐块读取（⚠️ 注意：不能用 EventSource，因为它只支持 GET 请求，POST 表单必须用 fetch 手动读流）。

5.6 数据持久化：AI 输出落盘 Excel

生成完成后，用 openpyxl 把学生信息和计划写入 Excel。这一步补全了"数据去哪"的闭环：

复制代码

用户输入(表单) → 提示词 → 大模型(流式生成) → 前端(实时展示) → Excel(落盘保存)

至此，一个"输入 → AI 处理 → 展示 → 持久化"的完整 AI 应用形态就齐了。

6. 回看提示词进化之路

把三个项目的提示词放在一起，能看到一条清晰的进化曲线：

项目	提示词长度	说清了什么	AI 的自由度
贪吃蛇	1 句话	只说要什么	几乎全权决定（难度、加速、主题都是它自己加的）
聊天机器人	5 行	技术栈分工 + 外部服务 + 审美要求	页面设计自由，架构被约束
学习计划	30+ 行	每个字段的控件类型、默认值、后端分支、数据归属	几乎没有自由度，纯执行

规律：需求越复杂/越接近真实产品，提示词就该越像需求文档。但注意不是越长越好------

贪吃蛇用一句话，反而是对的：练手项目让 AI 自由发挥，惊喜更多；
学习计划写得细，也是对的：产品有明确的业务规则，模糊即返工。

💡 衍生理解------怎么判断该写多细？问自己：这个细节我验收时会在意吗？ 在意就写（如"默认显示本科"），不在意就留给 AI（如"页面保证美观即可"）。提示词的粒度 = 你的验收标准。

7. 三个项目的难度阶梯与知识点地图

维度	贪吃蛇	AI 聊天机器人→AI 女友	AI 学习计划生成器
文件规模	1 个 HTML	前后端分离 6+ 文件	3 个文件
依赖	零依赖	flask + requests	flask + openai + openpyxl
涉及 AI	❌	✅ 对话 + 流式 + 角色扮演	✅ 提示词工程 + 流式
前后端通信	无	SSE 代理翻译	自定义 5 事件协议
业务规则	无	无	劝退分支（代码硬判断）
难度	⭐	⭐⭐⭐	⭐⭐

设计意图 ：先建立信心（纯前端能跑就行）→ 再攻克 AI 应用最核心的流式链路（前后端 + 大模型三方协作）→ 最后练业务整合（规则判断、提示词工程、数据落盘）。难度不是线性的，最硬的骨头（流式）在中间。

8. 实战中踩的坑与解决方案

这些是真实踩到并记录在案的问题，比知识点更值钱：

坑	现象	根因	解决
Git Bash 的 curl 传中文乱码	接口测试永远返回 400	curl 在 Git Bash 里把中文按 GBK 编码发送，Flask 按 UTF-8 解析失败	用 Python 写 UTF-8 的 JSON 文件再 `--data-binary @file` 发送
终端中文乱码误导判断	看输出以为代码错了	Windows 终端编码与 UTF-8 文件不一致	用 Python 读文件验证实际内容，不凭终端显示下结论
Windows curl 访问 https 报错	证书吊销检查失败	Windows schannel 的离线吊销检查机制	加 `--ssl-no-revoke` 参数
流式响应中途断流	偶发生成中断	上游 API 中转站不稳定	前端兜底：未收到 done 事件就提示重试
中文路径的隐患	部分工具行为异常	开发工具链对中文路径支持差	项目路径尽量纯英文
自测烧钱	每次测试消耗真实额度	接口按 token 计费	设计不耗额度的测试分支（如劝退分支）；完整分支用短问题测
API Key 硬编码	Key 写进了代码文件	图方便直接粘贴	改为 `os.getenv()` 读环境变量；已公开过的 Key 立即作废

💡 衍生理解------为什么"踩坑记录"是 VibeCoding 最宝贵的产出？ AI 能帮你写代码，但不能替你踩坑。每个坑都是你的环境和工具链独有的，把这些沉淀进 CLAUDE.md，下次 AI 帮你干活时就不会重蹈覆辙。这就是"人机协作"中人类增值的部分。

9. 衍生知识点（进阶补充）

9.1 SSE vs WebSocket：AI 应用为什么选前者

对比	SSE	WebSocket
方向	单向（服务器 → 客户端）	双向
协议	普通 HTTP	独立协议（需升级握手）
实现	几行代码，天然过代理/防火墙	需要专门的库和配置
自动重连	浏览器内置	需自己实现

AI 生成的场景恰好是单向的（服务器持续推、客户端只收），SSE 完全够用还更简单。只有在需要"用户随时打断 AI"这种双向实时场景才需要 WebSocket------我的聊天机器人里"停止生成"按钮就是前端直接丢弃后续事件实现的，不需要双向通道。

9.2 Markdown 渲染与 XSS 防护

AI 回复是 Markdown 格式，渲染时要先整体 HTML 转义再替换 ，防止模型输出里被注入 <script>。我的实现里代码块用占位符先提取出来，最后再放回------避免代码内容被 Markdown 规则二次处理。凡是把 AI 输出渲染成 HTML 的地方，都必须过转义这道闸。

9.3 "边生成边渲染"的流式 Markdown

流式输出时，最后一段代码块可能还没闭合（```只出现了一半）。处理方式：未闭合的代码围栏按代码块渲染，等闭合的内容到了再重新渲染。不做这个处理，用户会看到大段裸 Markdown 源码闪烁。

9.4 会话历史的截断策略

聊天机器人每次请求都带全量历史吗？不是------后端只截最近 30 条发给模型。原因：① 控制 token 消耗（历史越长越贵）；② 上下文窗口有限，无限增长必然溢出；③ 太老的历史对当前对话价值很低。这是所有对话产品的通用策略。

9.5 环境变量管理 API Key 的进阶姿势

python 复制代码

API_KEY = os.getenv("LLM_API_KEY", "默认值")

优先读环境变量，代码里不硬编码真实 Key。更规范的做法是配合 .env 文件 + .gitignore，把密钥彻底排除在版本库之外。

10. 自测题

前端和后端各自的职责是什么？它们通过什么协议、什么格式通信？
为什么 AI 应用的 API Key 必须放在后端？后端代理还顺带解决了什么问题？
什么是"前后端同源部署"？它有什么好处？
什么是 SSE？AI 应用为什么普遍用 SSE 而不是 WebSocket？
推理模型的"双通道输出"指什么？如果后端只转发 content 会发生什么？
前端用 axios 做流式解析，为什么要维护"已消费事件计数器"？
"AI 女友"和"AI 聊天"在技术上的核心差别是什么？
"学历为其他直接劝退"这类业务规则，为什么不交给 AI 判断？
为什么不能用 EventSource 实现 POST 表单的流式请求？替代方案是什么？
提示词的粒度应该怎么把握？判断标准是什么？

👉 查看参考答案

前端是浏览器里的界面代码（看到什么点什么），后端是服务器上的程序（业务逻辑、连数据库和大模型）；通过 HTTP 请求通信，数据格式用 JSON，AI 应用还会用 SSE 流。
前端源码里的 Key 任何人 F12 都能偷走盗刷额度；后端代理还解决了 CORS 跨域问题（同源部署更彻底）。
后端（Flask static_folder）直接托管前端页面，两者跑在同一个地址/端口下；天然无跨域，还少起一个静态服务器。
服务器推送事件，基于普通 HTTP 的单向推送；AI 生成恰好是单向场景，SSE 实现简单、天然过代理、浏览器自带重连。
reasoning_content（思考过程）和 content（正式回答）两个增量字段；只转发 content 的话，模型思考的几十秒里前端黑盒干等，用户以为卡死。
onDownloadProgress 每次给的是累积文本，网络分包位置不确定；计数器保证只消费新增的完整事件，尾部不完整块留给下次回调。
系统提示词里的角色设定------后端把性格设定拼进发给大模型的 system prompt，模型据此"扮演"。
确定性规则用代码 100% 可靠、零成本、秒回；交给 AI 多花钱、响应慢、还可能判断不稳定。
EventSource 只支持 GET；POST 场景用 fetch + resp.body.getReader() 手动读流。
问自己"这个细节验收时在不在意"：在意就写进提示词，不在意就留给 AI 自由发挥------提示词的粒度等于验收标准。