docs(api-intro): rewrite API introduction with interactive examples and clearer explanations

- Restructure content with more engaging metaphors and practical examples
- Add simplified interactive components to demonstrate key concepts
- Improve readability with better organization and visual aids
- Update terminology to be more beginner-friendly
- Include real-world API usage scenarios

docs/zh-cn/appendix/api-intro.md

@@ -1,148 +1,382 @@
 # API 入门（0 基础版）
 
-> 💡 **学习指南**：这是写给 0 基础新手的。你先记住一句话：**API 就是“别的软件给你用的按钮/入口”**。你按它的规则“提交信息”，它按规则“把结果给你”。
+> 💡 **学习指南**：本章节无需编程基础，通过交互式演示和生动比喻带你深入理解 API 的核心概念。我们将从"餐厅点餐"这个生活场景讲起，一步步揭开 API 的神秘面纱。
 
 <ApiQuickStartDemo />
 
----
+## 0. 引言：从餐厅点餐到软件协作
 
-## 0. 引言：你真正依赖的不是“服务器”，而是“接口”
+想象一下，你走进一家餐厅：
 
-当你说“我要调一下接口”，你其实是在说：
+1. **你**（顾客）拿着菜单，告诉服务员："我要一份宫保鸡丁，加辣。"
+2. **服务员**（接口）把你的要求记下来，送到厨房。
+3. **厨房**（对方的系统）根据要求做菜。
+4. **服务员**把做好的菜端给你。
 
-> 我希望<strong>按某种约定</strong>把输入交给对方系统，然后<strong>按约定</strong>拿到输出（成功或失败）。
+在这个过程中，**你不需要知道**：
+- 厨房有几个厨师
+- 他们用什么锅铲炒菜
+- 蔬菜是从哪个市场买的
+- 厨师今天心情好不好
 
-这份“约定”就是 API。
+**你只需要知道**：
+- 怎么点菜（喊服务员或填单子）
+- 要告诉对方什么（菜名、口味要求）
+- 会得到什么（你点的菜）
 
-你可以先把 API 当成一句大白话：
+**这就是 API 的本质**：它就像餐厅的**服务员**，是你和"对方的系统"之间的**桥梁**。
 
-> API = 别的软件给你用的“入口”：你按它说的来，它把结果给你。
+> **API（Application Programming Interface）** = **应用之间的"接口/入口"**：你按约定把请求交给对方，对方按约定把结果给你。
 
 ---
 
-## 1. 什么是 API？（新手版一句话）
+## 1. 核心：API 的三个关键问题
 
-**API** 可以翻译成：**应用之间的“接口/入口”**。
+就像去餐厅点菜一样，使用 API 时你只需要搞清楚 3 个问题：
 
-对新手来说，你只要先记住 3 件事（够用了）：
+### 1.1 怎么点菜？（入口在哪里）
 
-1. **怎么用它**（入口是什么：一个网址 / 一个函数名）
-2. **要填什么**（你要告诉它哪些信息）
-3. **会得到什么**（成功给你什么；失败会怎么提示）
+你首先得知道"怎么叫服务员"。在软件世界里，入口通常有两种：
+
+- **HTTP API**：像一个"网址"，你发送网络请求过去
+  - 例如：`https://api.example.com/getUser`
+- **SDK/API**：像一个"函数名"，你在代码里直接调用
+  - 例如：`getUserInfo(userId)`
+
+### 1.2 要说什么？（你要填什么信息）
+
+你不能只说"我要菜"，你得告诉服务员：
+- 你要什么菜？（模型名称）
+- 有什么要求？（提示词、参数）
+- 你是谁？（API Key，相当于会员卡）
+
+### 1.3 会得到什么？（成功/失败的结果）
+
+服务员可能会端来：
+- ✅ 你点的菜（成功返回的数据）
+- ❌ "不好意思，这道菜卖完了"（错误提示，比如 404、500）
 
 <ApiConceptDemo />
 
-### 1.1 API 不等于“实现”
+### 1.4 API 的核心价值：把复杂度藏起来
 
-API 只描述“怎么用”，不描述“怎么做”。
+回到餐厅的比喻：
 
-比如一个“获取用户信息”的 API，调用方需要知道：
+**餐厅**需要做的事情（实现细节）：
+- 采购食材、处理库存
+- 安排厨师、协调后厨
+- 控制火候、调味摆盘
+- 清洗餐具、打扫卫生
 
-- 你要带用户 id 吗？
-- 你要不要带 Token？
-- 成功返回什么字段？
-- 用户不存在会返回什么错误？
+**顾客**完全不需要知道这些！顾客只需要：
+- 看菜单点菜
+- 等菜上桌
+- 享用美食
 
-但调用方不需要知道：
+**API 就像菜单和服务员**，它把"怎么做"的复杂度全部藏起来，只暴露"怎么用"的简单接口。
 
-- 用户表怎么设计
-- 服务拆成几个微服务
-- 缓存怎么做
-
-把实现细节藏起来，让双方能**各做各的**，这就是 API 的价值。
+这就带来两个好处：
+1. **简化使用**：调用者不需要理解内部实现
+2. **灵活变更**：餐厅换了厨师、改了做法，但菜单不变，顾客完全无感
 
 ---
 
-## 2. 为什么 HTTP 调用可以叫 API？
+## 2. 两种常见的 API 形式
 
-因为用“网址发请求”本身就像按一个按钮：你把信息发过去，对方把结果回给你。（这类通常就叫 HTTP API）
+在现实世界里，你会遇到两种"点菜方式"：
 
-你不用记复杂的术语，先看流程就够了：**发过去 → 对方处理 → 回给你**。
+### 2.1 外卖配送（HTTP API）
+
+你不用亲自去餐厅，只需要：
+1. 打开外卖 APP（找到入口：网址）
+2. 选好菜品、填好地址（准备请求：参数）
+3. 等外卖员送到（接收响应：数据）
+
+**HTTP API** 就是这种方式：通过网络发送请求，等待返回结果。
+
+**流程是这样的**：
+```
+你的电脑 → 发送请求 → 网络传输 → 对方服务器
+                        ↓
+                  处理你的请求
+                        ↓
+你的电脑 ← 接收结果 ← 网络传输 ← 对方服务器
+```
 
 <RequestResponseFlow />
 
-一句话总结：HTTP API 就是“用网址去叫别人做事”。
+**举个例子**：调用 AI 模型生成文本
+- 你发送："帮我写一首关于春天的诗"
+- 对方处理：调用大语言模型生成
+- 你接收：返回生成的诗歌
+
+### 2.2 餐堂堂食（SDK/API）
+
+你走进餐厅，直接对服务员说：
+- "来一份宫保鸡丁"
+
+**SDK（软件开发工具包）** 就像是餐厅的"服务员"，它已经在餐厅里了，你只需要说话（调用函数），它会帮你：
+- 把要求转达给厨房（内部帮你调用 HTTP API）
+- 处理各种复杂细节（鉴权、重试、数据格式）
+- 最后把结果整理好给你
+
+**所以你会听到两种说法**：
+- "调用这个服务的 API"（通常指 HTTP API，像外卖）
+- "调用这个 SDK 的 API"（通常指函数接口，像堂食）
 
 ---
 
-## 3. 为什么 SDK 的调用接口也叫 API？
+## 3. 真实世界：怎么和 AI 服务"对话"
 
-因为 SDK 本质上也是一个“工具包/库”。它对外公开的函数/方法，本来就可以叫 API（入口）。
+让我们看一个真实的例子：调用 AI 模型。
 
-同时，很多 SDK 会在背后帮你调用 HTTP API（还会顺便帮你处理：加“钥匙”、失败重试、把数据整理成好用的样子），所以大家会同时说：
+**场景**：你想让 AI 帮你写一段产品文案。
 
-- “这个服务的 API”（通常指 HTTP 接口）
-- “这个 SDK 的 API”（通常指库里的函数接口）
+### 3.1 用 HTTP API 的方式（外卖模式）
+
+就像发外卖订单一样，你需要：
+
+```bash
+# 1. 打开外卖 APP（找到网址）
+curl https://api.openai.com/v1/chat/completions
+
+# 2. 选好菜品、填好地址（带上你的信息和要求）
+--header 'Authorization: Bearer 你的API密钥'  # 你的会员卡
+--header 'Content-Type: application/json'     # 说明你点的是菜单（JSON格式）
+
+# 3. 告诉服务员你要什么（请求内容）
+--data '{
+  "model": "gpt-4",           # 选哪个厨师
+  "messages": [               # 你的要求
+    { "role": "system", "content": "你是一个营销文案专家" },
+    { "role": "user", "content": "帮我为这款智能手表写一段吸引人的产品文案" }
+  ]
+}'
+
+# 4. 等待配送（接收响应）
+# 返回：{"choices": [{"message": {"content": "生成的文案..."}}]}
+```
+
+### 3.2 用 SDK 的方式（堂食模式）
+
+就像走进餐厅直接点餐：
+
+```javascript
+// 安装 SDK（相当于走进餐厅）
+import OpenAI from 'openai';
+
+// 创建"服务员"（初始化客户端）
+const client = new OpenAI({
+  apiKey: '你的API密钥'  # 你的会员卡
+});
+
+// 直接点菜（调用函数）
+const response = await client.chat.completions.create({
+  model: 'gpt-4',           # 选哪个厨师
+  messages: [               # 你的要求
+    { role: 'system', content: '你是一个营销文案专家' },
+    { role: 'user', content: '帮我为这款智能手表写一段吸引人的产品文案' }
+  ]
+});
+
+// 享用美食（使用结果）
+console.log(response.choices[0].message.content);
+```
+
+**看出来了吗？** SDK 的方式更简单，因为它帮你处理了很多细节！
 
 <RealWorldApiDemo />
 
+### 3.3 两种方式的对比
+
+| 特点 | HTTP API（外卖） | SDK API（堂食） |
+|------|------------------|-----------------|
+| **使用门槛** | 需要理解网络请求、数据格式 | 只需会调用函数 |
+| **灵活性** | 更灵活，任何语言都能用 | 通常限定特定语言 |
+| **复杂度** | 你要处理很多细节（鉴权、错误等） | SDK 帮你处理细节 |
+| **典型场景** | 跨语言调用、学习原理 | 日常开发、快速集成 |
+
 ---
 
-## 4. （选读）GET/POST 这些词到底在说什么？
+## 4. 进阶：GET 和 POST 有什么区别？
 
-新手可以先跳过这一节：你只要先学会“看文档、会调用”就够用了。
+> 🎯 **新手提示**：这一节可以暂时跳过。等你熟悉了基本调用，再回来了解也不迟。
 
 <details>
-<summary>点我展开：进阶一点点（但我尽量讲人话）</summary>
+<summary>点我展开：进阶内容（用人话讲）</summary>
+
+在 HTTP API 的世界里，你会经常看到 **GET** 和 **POST** 这两个词。它们就像两种不同的"点菜方式"。
+
+### 4.1 GET：像看菜单（只看不吃）
+
+**特点**：
+- 只是想"获取"信息，不会改变服务器状态
+- 就像在餐厅看菜单，你看一遍菜单，厨房的菜不会被消耗
+- **可以安全重试**：看一遍菜单没看清，再看一遍，没问题
+
+**例子**：
+- 查询用户信息：`GET /api/user/123`
+- 搜索商品：`GET /api/products?keyword=手机`
+- 获取文章列表：`GET /api/articles`
+
+### 4.2 POST：像下单（会真的执行）
+
+**特点**：
+- 会"创建"或"修改"服务器上的数据
+- 就像你下了单，厨房真的开始做菜了
+- **不能随意重试**：下错了单，再下一遍，你就点了双份！
+
+**例子**：
+- 创建用户：`POST /api/users`（会真的创建一个新用户）
+- 下单购买：`POST /api/orders`（会真的扣钱、发货）
+- 发表评论：`POST /api/comments`（会真的保存一条评论）
 
 <ApiMethodDemo />
 
-这节想讲的只有一件事：有些请求“重试很安全”（比如 GET），有些“重试可能出事”（比如创建接口）。
+### 4.3 还有哪些方法？（简单了解）
+
+除了 GET 和 POST，还有：
+- **PUT**：更新（替换整个资源）
+- **PATCH**：打补丁（更新部分字段）
+- **DELETE**：删除
+
+**新手建议**：先学会用 GET 和 POST，其他的慢慢来。
 
 </details>
 
 ---
 
-## 5. 怎么读 API 文档？（先看能不能用，再看怎么用）
+## 5. 怎么读 API 文档？（像看菜单一样简单）
 
-API 文档可以当成“菜单 + 说明书”：
+API 文档就像餐厅的**菜单 + 说明书**，告诉你：
+- 有哪些菜可以点（提供哪些功能）
+- 每道菜是什么（接口说明）
+- 怎么点（怎么调用）
+- 什么价格（返回什么数据）
+- 有没有忌口/限量（注意事项）
 
 <ApiDocumentDemo />
 
-### 5.1 阅读 API 文档的 5 步
+### 5.1 阅读 API 文档的 5 步法
 
-1. **确认能力**：这个接口是不是你要的（做什么）
-2. **确认怎么用**：网址/函数名 + 需要填什么
-3. **确认参数**：必填/可选/默认值/类型
-4. **确认返回**：字段含义、是否可能为空
-5. **确认边界**：失败会怎样、太频繁会不会被拒绝
+就像看菜单点菜一样，按这个流程来：
+
+**第 1 步：确认这道菜是不是你要的**
+- 这个接口能做什么？
+- 符合你的需求吗？
+
+**第 2 步：找到"点菜入口"**
+- HTTP API：网址（URL）是什么？
+- SDK：函数名是什么？
+
+**第 3 步：看看要填什么信息**
+- **必填项**：就像"必须选辣度/份量"，不填不行
+- **可选项**：就像"要不要加葱花"，可以不填
+- **默认值**：就像"默认中辣"，你不填就按这个来
+
+**第 4 步：看看会端上来什么**
+- 成功时返回什么数据？
+- 字段代表什么意思？
+- 可能是空的吗？
+
+**第 5 步：了解"餐厅规则"**
+- 没钱了会怎样？（余额不足）
+- 点太快会怎样？（限流/Rate Limit）
+- 菜卖完了会怎样？（404 资源不存在）
+- 厨房出错会怎样？（500 服务器错误）
+
+### 5.2 常见的状态码（就像餐厅的回复）
+
+| 状态码 | 含义 | 餐厅类比 |
+|--------|------|----------|
+| **200** | 成功 | "这是您的菜，请慢用" |
+| **400** | 请求错误 | "您点的菜我们有，但您填的信息有问题" |
+| **401** | 未授权 | "请先出示会员卡" |
+| **403** | 禁止访问 | "您的会员卡等级不够，点不了这道菜" |
+| **404** | 资源不存在 | "对不起，您点的菜卖完了" |
+| **429** | 请求过多 | "您点太快了，请稍后再试" |
+| **500** | 服务器错误 | "厨房出故障了，请稍后再试" |
 
 ---
 
-## 6. 实战：用“模拟 API”练出手感
+## 6. 实战：用"模拟 API"练出手感
 
-真实世界里你会用 Postman/curl/代码去调 API；这里我们用一个“不会被 CORS/网络干扰”的练习场，把核心手感练出来。
+理论讲完了，该动手了！在真实世界里，你会用 Postman、curl 或代码去调用 API。但这里我们准备了一个"练习场"，不用担心网络问题、CORS 错误，专注于练出核心手感。
 
 <ApiPlayground />
 
-建议你按顺序试这几件事：
+### 6.1 建议按顺序试试这些"场景"
 
-1. 把 “登录/钥匙” 改成“没有” → 看看失败会怎么提示
-2. 连续点击“调用” → 看看“太频繁会被拒绝”的提示
-3. 选 POST 创建用户，把 Body 改成非法 JSON → 观察 400
-4. 把用户 id 改成 `u_404` → 观察 404（资源不存在）
+就像去餐厅"踩点"一样，试试各种情况：
+
+**场景 1：忘带会员卡**
+- 把"登录/钥匙"改成"没有"
+- 观察返回什么错误（通常是 401）
+
+**场景 2：点太快被限流**
+- 连续快速点击"调用"按钮
+- 观察返回什么错误（通常是 429）
+
+**场景 3：点菜信息填错了**
+- 选 POST 创建用户
+- 把 Body 改成非法的 JSON 格式
+- 观察返回什么错误（通常是 400）
+
+**场景 4：点的菜卖完了**
+- 把用户 ID 改成 `u_404`（不存在的用户）
+- 观察返回什么错误（通常是 404）
+
+### 6.2 练习目标
+
+通过这些练习，你要掌握：
+1. **能看懂成功响应**：知道返回的数据在哪里
+2. **能看懂错误提示**：知道为什么失败、怎么改
+3. **有手感**：知道调用 API 的基本流程
 
 ---
 
-## 7. 总结：一句话把三种“API”说清楚
+## 7. 总结：记住这三句话就够了
 
-- **HTTP API**：通过网络调用（你发请求，它回结果）
-- **SDK API**：通过库函数调用（你调函数，它内部帮你发请求）
-- **库 API**：本地函数接口（不走网络）
+### 7.1 API 的三种形式
 
-它们共同点只有一个：**把“怎么用”写清楚**。
+| 类型 | 比喻 | 特点 |
+|------|------|------|
+| **HTTP API** | 外卖配送 | 通过网络调用，你发请求它回结果 |
+| **SDK API** | 餐厅堂食 | 通过函数调用，它内部帮你发请求 |
+| **库 API** | 自己做菜 | 本地函数，不走网络 |
+
+### 7.2 核心记忆点
+
+1. **API = 接口**：就像餐厅的服务员，是你和对方系统的桥梁
+2. **调用三要素**：入口（网址/函数名）、参数（要告诉什么）、返回（会得到什么）
+3. **学会读文档**：就像看菜单，先确认能不能用，再看怎么用
+
+### 7.3 下一步建议
+
+现在你已经理解了 API 的基本概念，可以去：
+- 读一读真实的 API 文档（比如 OpenAI、DeepSeek 的文档）
+- 用 Postman 或 curl 试试真实的 API 调用
+- 在你的项目里接入第一个 API
 
 ---
 
 ## 8. 名词速查表
 
-> 不想背词也没关系：你只要会“看文档、会填参数、能看懂成功/失败”，就已经能开始用 API 了。
+> 💡 **使用建议**：不用背！遇到不懂的词回来查就行。你只要会"看文档、会填参数、能看懂成功/失败"，就已经能开始用 API 了。
 
-| 名词       | 英文                              | 解释                                      |
-| :--------- | :-------------------------------- | :---------------------------------------- |
-| API        | Application Programming Interface | 软件对外公开的接口/入口                   |
-| URL/地址   | -                                 | 你要访问的“网址/路径”                     |
-| 参数       | -                                 | 你要告诉对方的信息（例如：id、页码）      |
-| 返回       | -                                 | 对方给你的结果（数据或错误提示）          |
-| 状态码     | -                                 | 成功/失败的数字提示（例如：200 表示成功） |
-| Rate Limit | -                                 | 限流/配额（常见 429）                     |
+| 名词 | 英文 | 解释 |
+|------|------|------|
+| **API** | Application Programming Interface | 软件对外公开的接口/入口，像餐厅的服务员 |
+| **HTTP API** | HTTP API | 通过网络调用的接口，像外卖配送 |
+| **SDK** | Software Development Kit | 软件开发工具包，像餐厅的服务员（帮你处理细节） |
+| **URL** | Uniform Resource Locator | 你要访问的"网址"，像餐厅的地址 |
+| **参数** | Parameter | 你要告诉对方的信息，像点菜时的要求（辣度、份量） |
+| **请求** | Request | 你发给对方的要求，像点菜单 |
+| **响应** | Response | 对方给你的结果，像端上来的菜 |
+| **状态码** | Status Code | 成功/失败的数字提示，200=成功，4xx=你错了，5xx=服务器错了 |
+| **API Key** | API Key | 调用 API 的密钥，像餐厅的会员卡 |
+| **限流** | Rate Limit | 限制调用频率，像餐厅说"您点太快了" |
+| **GET/POST** | HTTP Methods | 请求方法，GET=获取信息（看菜单），POST=创建/修改（下单） |
+| **JSON** | JavaScript Object Notation | 数据格式，像菜单上的格式（统一的排版） |
+| **Header** | Header | 请求头，像点菜单上的备注栏（放会员卡等信息） |
+| **Body** | Body | 请求体，像点菜单的详细内容（具体的菜品要求） |