docs: update documentation content and structure

- Update appendix article titles for better clarity - Add chapter introductions to appendix articles - Improve formatting and readability of troubleshooting section - Expand Vibe Coding platform comparison content
2026-01-14 17:13:28 +08:00
parent 69073e2eae
commit a9f4071308
4 changed files with 65 additions and 15 deletions
@@ -324,28 +324,28 @@ Thinking 是好事，但不可 over thinking，我们就此控制过度反思，

 常见的处理方式只有三种：

- **方式一：页面或终端报错**
+- **方式一：页面或终端报错**  
 页面变红、白屏，或终端出现一堆红字时，直接截图或复制全部错误信息发给 AI，让它帮你修。

- **方式二：功能不对但没报错**
+- **方式二：功能不对但没报错**  
 比如按钮没反应、数据没显示、样式乱了，用大白话描述“现在发生了什么 + 你本来想要什么”，必要时加一张截图。

- **方式三：不确定有没有问题**
+- **方式三：不确定有没有问题**  
 可以直接问 AI：“帮我检查一下这个功能有没有明显问题，需不需要调整。”

 #### 2.3.1 新手常见疑问

- **Q：我不知道错误信息在哪里？**
-  A：一般来说，看所有“红色的字”。在终端、控制台或页面上，找到红色提示，全选复制给 AI 即可。
+- **Q：我不知道错误信息在哪里？** 
+- A：一般来说，看所有“红色的字”。在终端、控制台或页面上，找到红色提示，全选复制给 AI 即可。

- **Q：AI 改完还是报同样的错怎么办？**
-  A：这是常见情况。继续截图或复制最新的错误信息发给它，让它在上一次修改基础上进一步修复。
+- **Q：AI 改完还是报同样的错怎么办？**  
+- A：这是常见情况。继续截图或复制最新的错误信息发给它，让它在上一次修改基础上进一步修复。

- **Q：我需要完全理解 AI 的修复方案吗？**
-  A：不需要一次性全部搞懂。可以每次只关注一两个点，久而久之，你会逐渐看懂越来越多代码，就像积累英语词汇一样。
+- **Q：我需要完全理解 AI 的修复方案吗？** 
+- A：不需要一次性全部搞懂。可以每次只关注一两个点，久而久之，你会逐渐看懂越来越多代码，就像积累英语词汇一样。

- **Q：改了很多次，问题还是没解决怎么办？**
-  A：可以尝试：
+- **Q：改了很多次，问题还是没解决怎么办？** 
+- A：可以尝试：
  - 使用 IDE 的“版本回退”功能，在智能体对话处找到撤回按钮，回到一个可运行的版本重新开始；
  - 更换模型或调整提示词，将现象、错误信息讲得更具体；
  - 将“当前代码 + 错误日志 + 预期行为”打包，一次性发给 AI，让它整体重构问题部分。
@@ -1,4 +1,12 @@
-# 用 Vibe Coding 搭建贪吃蛇游戏：完整实战教程
+# 附录示例 1：7 款主流 Vibe Coding 在线平台实测对比
+
+## 本章导读
+
+面对琳琅满目的 AI 编程工具，哪一款才最适合你？本章通过一个统一的实战任务——开发“贪吃蛇 + AI 写诗”游戏，对 Lovable、Replit、Z.ai 等 7 款主流 Web Vibe Coding 平台进行了深度横向评测。我们将从新手友好度、代码可控性、部署便捷性等多维度对比，助你快速选出最强开发辅助工具。
+
+---
+
+# 1. 用 Vibe Coding 搭建贪吃蛇游戏：完整实战教程

 本文介绍了一种新兴的软件开发实践——“Vibe Coding（氛围式编码）”，它利用人工智能来加速应用构建过程。

@@ -13,7 +21,7 @@
 - **平台对比：** 从初学者视角出发，对 7 个不同 AI Agent 平台的优劣势进行评测与对比。
 - **UI / UX 工具：** 学会如何将 Figma、Mastergo 等 UI/UX 工具融入到整体工作流中。

-# 1. 引言
+## 1. 引言

 在此前的课程中，我们一直使用 z.ai 的全栈开发模型来完成编程任务。

@@ -40,9 +48,43 @@ Vibe Coding 的核心思想，是从 **“以代码为中心（code-first）”*
 - **提高效率：** 自动处理大量重复、机械的编码工作（如模板代码），让开发者可以把精力放在架构设计和问题抽象上。
 - **利于试验：** 鼓励先快速产出，再不断完善的方式，更便于尝试新点子和新功能。

+## 2. 什么是 Vibe Coding 在线平台（Web-based）？
+
+在本次实测中，你会发现我们评测的工具被分为了两类：**Web-based（在线平台）** 和 **IDE（本地开发环境）**。
+
+虽然它们的核心都是用 AI 帮你写代码，但在使用体验和适用场景上有着巨大的区别：
+
+### Vibe Coding 在线平台 (Web-based)
+
+**代表工具：** Lovable, Replit, Z.ai, v0
+
+这就像是“拎包入住”的酒店式公寓。
+
+- **无需环境配置：** 你不需要关心什么是 Python 环境、Node.js 版本，也不用管依赖安装。打开浏览器，输入网址，直接就能开始写代码。
+- **一键预览与部署：** 代码生成后，平台通常会自动在右侧窗口展示运行效果。做好了，点一个按钮就能生成一个链接分享给朋友。
+- **适合场景：**
+  - **快速验证想法（MVP）：** 脑子里有个点子，想花半小时看看能不能做出来。
+  - **新手入门：** 完全不想被复杂的环境报错劝退，只想体验 AI 编程的乐趣。
+  - **轻量级应用：** 做个简单的工具网页、小游戏或者个人展示页。
+
+### AI IDE (本地开发环境)
+
+**代表工具：** Cursor, Trae, VS Code + AI 插件
+
+这就像是“精装修”的自有住房。
+
+- **强大的本地能力：** 它运行在你的电脑上，可以直接访问你所有的本地文件，利用你电脑的算力。
+- **无缝对接专业工作流：** 适合大型项目，可以自由安装各种插件，连接本地数据库，进行复杂的调试。
+- **适合场景：**
+  - **专业项目开发：** 需要长期维护、结构复杂的商业项目。
+  - **深度定制：** 需要对代码细节有极致掌控，或者需要与现有的本地工作流（如 Git、Docker）深度结合。
+  - **数据隐私：** 代码完全在本地，更符合某些企业的安全规范。
+
+**总结来说：** 如果你是刚开始接触 AI 编程，或者只想快速做一个小东西玩玩，**在线平台**是绝佳的起点。如果你是专业开发者，或者项目越来越复杂，**本地 IDE** 则会提供更高的上限。
+
 ---

-## 2. 什么是 AI Agent？
+## 3. 什么是 AI Agent？

 ### 什么是 AI Agent？

@@ -1,3 +1,11 @@
+# 附录示例 2：利用设计与编程 Agent 搭建网站
+
+## 本章导读
+
+本章将展示设计与开发如何通过 AI 完美协作。你将扮演产品经理的角色，指挥“设计 Agent”完成 Logo 设计、配色方案与页面布局，再协同“编程 Agent”将视觉稿转化为可运行的代码。从创意构思到网站上线，体验全链路的 AI 赋能开发流程，让一个人成为一支队伍。
+
+---
+
 # 1. 入门指南

 ## 1. 教程简介