docs: 更新 API 文档和 AI 能力集成页面

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

@@ -1,382 +1,152 @@
-# API 入门（0 基础版）
+# API 入门：怎么跟计算机"说人话"？
 
-> 💡 **学习指南**：本章节无需编程基础，通过交互式演示和生动比喻带你深入理解 API 的核心概念。我们将从"餐厅点餐"这个生活场景讲起，一步步揭开 API 的神秘面纱。
+> 💡 **写在前面**：这一章不教写代码，只教**"怎么跟别人的软件打交道"**。
+> 
+> 你可能听说过 "API" 这个词一万次了，但它到底是个啥？别被它的英文全称吓到，把它当成**"连接器"**或者**"传声筒"**就好。
 
 <ApiQuickStartDemo />
 
-## 0. 引言：从餐厅点餐到软件协作
+## 0. 为什么需要 API？
 
-想象一下，你走进一家餐厅：
+想象一下，你想用 DeepSeek 的 AI 能力，但 DeepSeek 的核心程序跑在他们自家机房的超级电脑里。
+你总不能直接跑去他们机房，插上键盘敲代码吧？
 
-1. **你**（顾客）拿着菜单，告诉服务员："我要一份宫保鸡丁，加辣。"
-2. **服务员**（接口）把你的要求记下来，送到厨房。
-3. **厨房**（对方的系统）根据要求做菜。
-4. **服务员**把做好的菜端给你。
+所以，DeepSeek 需要开一个**"窗口"**，让你在千里之外也能用上他们的 AI。
 
-在这个过程中，**你不需要知道**：
-- 厨房有几个厨师
-- 他们用什么锅铲炒菜
-- 蔬菜是从哪个市场买的
-- 厨师今天心情好不好
-
-**你只需要知道**：
-- 怎么点菜（喊服务员或填单子）
-- 要告诉对方什么（菜名、口味要求）
-- 会得到什么（你点的菜）
-
-**这就是 API 的本质**：它就像餐厅的**服务员**，是你和"对方的系统"之间的**桥梁**。
-
-> **API（Application Programming Interface）** = **应用之间的"接口/入口"**：你按约定把请求交给对方，对方按约定把结果给你。
+这个**"窗口"**，就是 **API**。
 
 ---
 
-## 1. 核心：API 的三个关键问题
+## 1. 核心概念：餐厅里的潜规则
 
-就像去餐厅点菜一样，使用 API 时你只需要搞清楚 3 个问题：
+为了让你秒懂，我们还是得请出那位经典的**"服务员"**。
+但这次我们换个角度：**你是一个只会吃、不会做的顾客**（就像我们只会用 AI、不会写 AI 模型一样）。
 
-### 1.1 怎么点菜？（入口在哪里）
+### 1.1 你面临的三个问题
 
-你首先得知道"怎么叫服务员"。在软件世界里，入口通常有两种：
+当你走进一家外国餐厅（陌生的软件系统），你只想吃饱，但你面临三个问题：
 
-- **HTTP API**：像一个"网址"，你发送网络请求过去
-  - 例如：`https://api.example.com/getUser`
-- **SDK/API**：像一个"函数名"，你在代码里直接调用
-  - 例如：`getUserInfo(userId)`
+1.  **跟谁说？**（谁是服务员？）
+2.  **怎么说？**（用中文还是英文？要填单子还是直接喊？）
+3.  **结果咋样？**（菜上了还是卖完了？）
 
-### 1.2 要说什么？（你要填什么信息）
+在 API 的世界里，这三个问题对应了三个术语：
 
-你不能只说"我要菜"，你得告诉服务员：
-- 你要什么菜？（模型名称）
-- 有什么要求？（提示词、参数）
-- 你是谁？（API Key，相当于会员卡）
+| 餐厅里的问题 | 计算机里的术语 | 黑话 (行话) |
+| :--- | :--- | :--- |
+| **跟谁说？** | **Endpoint (端点)** | "接口地址"、"URL" |
+| **怎么说？** | **Request (请求)** | "传参"、"Payload" |
+| **结果咋样？** | **Response (响应)** | "返回值"、"返回包" |
 
-### 1.3 会得到什么？（成功/失败的结果）
+### 1.2 互动演示：点一道 AI 料理
 
-服务员可能会端来：
-- ✅ 你点的菜（成功返回的数据）
-- ❌ "不好意思，这道菜卖完了"（错误提示，比如 404、500）
+别光看字，来亲自试一下"点菜"的感觉。
+下面这个小工具模拟了你向 AI **"点一道笑话"** 的过程。
 
 <ApiConceptDemo />
 
-### 1.4 API 的核心价值：把复杂度藏起来
-
-回到餐厅的比喻：
-
-**餐厅**需要做的事情（实现细节）：
-- 采购食材、处理库存
-- 安排厨师、协调后厨
-- 控制火候、调味摆盘
-- 清洗餐具、打扫卫生
-
-**顾客**完全不需要知道这些！顾客只需要：
-- 看菜单点菜
-- 等菜上桌
-- 享用美食
-
-**API 就像菜单和服务员**，它把"怎么做"的复杂度全部藏起来，只暴露"怎么用"的简单接口。
-
-这就带来两个好处：
-1. **简化使用**：调用者不需要理解内部实现
-2. **灵活变更**：餐厅换了厨师、改了做法，但菜单不变，顾客完全无感
-
 ---
 
-## 2. 两种常见的 API 形式
+## 2. 两种"点菜"流派：外卖 vs 堂食
 
-在现实世界里，你会遇到两种"点菜方式"：
+你在教程里经常会看到两种调用方式：**HTTP** 和 **SDK**。
+很多新手会被绕晕，其实它们就是**"点外卖"**和**"堂食"**的区别。
 
-### 2.1 外卖配送（HTTP API）
+### 2.1 HTTP API（点外卖）
 
-你不用亲自去餐厅，只需要：
-1. 打开外卖 APP（找到入口：网址）
-2. 选好菜品、填好地址（准备请求：参数）
-3. 等外卖员送到（接收响应：数据）
+这是最原始、最通用的方式。就像**填一张外卖单子**。
 
-**HTTP API** 就是这种方式：通过网络发送请求，等待返回结果。
+*   **特点**：**死板但通用**。
+*   **怎么做**：你需要严格按照格式，填好地址（URL）、选好菜（参数）、贴好邮票（API Key），然后通过网络发出去。
+*   **谁在用**：所有编程语言都能用，甚至你在浏览器地址栏里敲一行字也是一种 HTTP 请求。
 
-**流程是这样的**：
-```
-你的电脑 → 发送请求 → 网络传输 → 对方服务器
-                        ↓
-                  处理你的请求
-                        ↓
-你的电脑 ← 接收结果 ← 网络传输 ← 对方服务器
-```
+### 2.2 SDK（堂食/VIP服务）
 
-<RequestResponseFlow />
+SDK (Software Development Kit) 就像是餐厅派给你的**专属管家**。
 
-**举个例子**：调用 AI 模型生成文本
-- 你发送："帮我写一首关于春天的诗"
-- 对方处理：调用大语言模型生成
-- 你接收：返回生成的诗歌
-
-### 2.2 餐堂堂食（SDK/API）
-
-你走进餐厅，直接对服务员说：
-- "来一份宫保鸡丁"
-
-**SDK（软件开发工具包）** 就像是餐厅的"服务员"，它已经在餐厅里了，你只需要说话（调用函数），它会帮你：
-- 把要求转达给厨房（内部帮你调用 HTTP API）
-- 处理各种复杂细节（鉴权、重试、数据格式）
-- 最后把结果整理好给你
-
-**所以你会听到两种说法**：
-- "调用这个服务的 API"（通常指 HTTP API，像外卖）
-- "调用这个 SDK 的 API"（通常指函数接口，像堂食）
-
----
-
-## 3. 真实世界：怎么和 AI 服务"对话"
-
-让我们看一个真实的例子：调用 AI 模型。
-
-**场景**：你想让 AI 帮你写一段产品文案。
-
-### 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 的方式更简单，因为它帮你处理了很多细节！
+*   **特点**：**省心但挑人**。
+*   **怎么做**：你不需要自己填单子、贴邮票。你只需要跟管家说："来份宫保鸡丁"。管家会自己在后台帮你填单子、发请求、处理报错。
+*   **谁在用**：通常针对特定语言（比如 Python 版管家、Node.js 版管家）。
 
 <RealWorldApiDemo />
 
-### 3.3 两种方式的对比
-
-| 特点 | HTTP API（外卖） | SDK API（堂食） |
-|------|------------------|-----------------|
-| **使用门槛** | 需要理解网络请求、数据格式 | 只需会调用函数 |
-| **灵活性** | 更灵活，任何语言都能用 | 通常限定特定语言 |
-| **复杂度** | 你要处理很多细节（鉴权、错误等） | SDK 帮你处理细节 |
-| **典型场景** | 跨语言调用、学习原理 | 日常开发、快速集成 |
+> **新手建议**：能用 SDK 就用 SDK，**把麻烦事留给别人，把时间留给自己**。
 
 ---
 
-## 4. 进阶：GET 和 POST 有什么区别？
+## 3. 进阶：GET 和 POST 到底有啥区别？
 
-> 🎯 **新手提示**：这一节可以暂时跳过。等你熟悉了基本调用，再回来了解也不迟。
+在看文档时，你总能看到这俩词。
+其实很简单，就看**"你是否想改变世界"**。
 
-<details>
-<summary>点我展开：进阶内容（用人话讲）</summary>
+### 3.1 GET：只看不买
 
-在 HTTP API 的世界里，你会经常看到 **GET** 和 **POST** 这两个词。它们就像两种不同的"点菜方式"。
+*   **含义**：**获取**信息。
+*   **场景**：刷朋友圈、看新闻、查天气。
+*   **特点**：你做这件事一万次，服务器里的数据也不会变（除了访问量+1）。
+*   **比喻**：你看菜单，看一眼是看，看一百眼还是看，菜单不会变。
 
-### 4.1 GET：像看菜单（只看不吃）
+### 3.2 POST：搞点事情
 
-**特点**：
-- 只是想"获取"信息，不会改变服务器状态
-- 就像在餐厅看菜单，你看一遍菜单，厨房的菜不会被消耗
-- **可以安全重试**：看一遍菜单没看清，再看一遍，没问题
-
-**例子**：
-- 查询用户信息：`GET /api/user/123`
-- 搜索商品：`GET /api/products?keyword=手机`
-- 获取文章列表：`GET /api/articles`
-
-### 4.2 POST：像下单（会真的执行）
-
-**特点**：
-- 会"创建"或"修改"服务器上的数据
-- 就像你下了单，厨房真的开始做菜了
-- **不能随意重试**：下错了单，再下一遍，你就点了双份！
-
-**例子**：
-- 创建用户：`POST /api/users`（会真的创建一个新用户）
-- 下单购买：`POST /api/orders`（会真的扣钱、发货）
-- 发表评论：`POST /api/comments`（会真的保存一条评论）
+*   **含义**：**提交**信息。
+*   **场景**：发朋友圈、注册账号、**让 AI 写文章**。
+*   **特点**：你做这件事，服务器里就会**多出**一条记录，或者**生成**一段新的内容。
+*   **比喻**：你下单点菜。你下一次单，厨房就得忙活一次，你的钱包就得瘪一次。
 
 <ApiMethodDemo />
 
-### 4.3 还有哪些方法？（简单了解）
-
-除了 GET 和 POST，还有：
-- **PUT**：更新（替换整个资源）
-- **PATCH**：打补丁（更新部分字段）
-- **DELETE**：删除
-
-**新手建议**：先学会用 GET 和 POST，其他的慢慢来。
-
-</details>
-
 ---
 
-## 5. 怎么读 API 文档？（像看菜单一样简单）
+## 4. 怎么看 API 文档？
 
-API 文档就像餐厅的**菜单 + 说明书**，告诉你：
-- 有哪些菜可以点（提供哪些功能）
-- 每道菜是什么（接口说明）
-- 怎么点（怎么调用）
-- 什么价格（返回什么数据）
-- 有没有忌口/限量（注意事项）
+文档就像**"说明书 + 菜单"**。
+你不需要从头读到尾，只需要学会**"查字典"**。
+
+### 4.1 文档里的"藏宝图"
+
+打开任何一个 API 文档（比如 OpenAI 或 DeepSeek），你只需要找这几样东西：
+
+1.  **Base URL**：根地址（餐厅在哪？）。
+2.  **Authentication**：怎么证明你是会员？（通常是加个 `Authorization: Bearer sk-...` 头）。
+3.  **Endpoints**：具体的菜品列表。
+    *   `/v1/chat/completions` -> 对话（最常用的）
+    *   `/v1/images/generations` -> 画图
+4.  **Parameters**：必填项有哪些？
+    *   `model`: 选哪个厨师？
+    *   `messages`: 你想聊啥？
 
 <ApiDocumentDemo />
 
-### 5.1 阅读 API 文档的 5 步法
+### 4.2 常见的"餐厅黑话"（状态码）
 
-就像看菜单点菜一样，按这个流程来：
+服务员（API）回复你的时候，通常会先喊一个数字代码：
 
-**第 1 步：确认这道菜是不是你要的**
-- 这个接口能做什么？
-- 符合你的需求吗？
-
-**第 2 步：找到"点菜入口"**
-- HTTP API：网址（URL）是什么？
-- SDK：函数名是什么？
-
-**第 3 步：看看要填什么信息**
-- **必填项**：就像"必须选辣度/份量"，不填不行
-- **可选项**：就像"要不要加葱花"，可以不填
-- **默认值**：就像"默认中辣"，你不填就按这个来
-
-**第 4 步：看看会端上来什么**
-- 成功时返回什么数据？
-- 字段代表什么意思？
-- 可能是空的吗？
-
-**第 5 步：了解"餐厅规则"**
-- 没钱了会怎样？（余额不足）
-- 点太快会怎样？（限流/Rate Limit）
-- 菜卖完了会怎样？（404 资源不存在）
-- 厨房出错会怎样？（500 服务器错误）
-
-### 5.2 常见的状态码（就像餐厅的回复）
-
-| 状态码 | 含义 | 餐厅类比 |
-|--------|------|----------|
-| **200** | 成功 | "这是您的菜，请慢用" |
-| **400** | 请求错误 | "您点的菜我们有，但您填的信息有问题" |
-| **401** | 未授权 | "请先出示会员卡" |
-| **403** | 禁止访问 | "您的会员卡等级不够，点不了这道菜" |
-| **404** | 资源不存在 | "对不起，您点的菜卖完了" |
-| **429** | 请求过多 | "您点太快了，请稍后再试" |
-| **500** | 服务器错误 | "厨房出故障了，请稍后再试" |
+*   **200 OK**：菜齐了，慢用。（成功）
+*   **400 Bad Request**：你点的菜菜单上没有，或者你没填辣度。（你填错了）
+*   **401 Unauthorized**：会员卡过期了，或者假卡。（没权限）
+*   **404 Not Found**：找不到这道菜，或者找不到这家店。（地址错了）
+*   **429 Too Many Requests**：你点太快了，厨师炒不过来了。（限流）
+*   **500 Internal Server Error**：厨房炸了，不是你的锅。（服务器崩了）
 
 ---
 
-## 6. 实战：用"模拟 API"练出手感
+## 5. 练手场：弄坏它也没关系
 
-理论讲完了，该动手了！在真实世界里，你会用 Postman、curl 或代码去调用 API。但这里我们准备了一个"练习场"，不用担心网络问题、CORS 错误，专注于练出核心手感。
+光说不练假把式。
+这里有个模拟 API。你可以随便填参数、随便改地址，看看会发生什么。
+试着触发一下 **401**（假装没带钱）或者 **404**（瞎填地址）。
 
 <ApiPlayground />
 
-### 6.1 建议按顺序试试这些"场景"
-
-就像去餐厅"踩点"一样，试试各种情况：
-
-**场景 1：忘带会员卡**
-- 把"登录/钥匙"改成"没有"
-- 观察返回什么错误（通常是 401）
-
-**场景 2：点太快被限流**
-- 连续快速点击"调用"按钮
-- 观察返回什么错误（通常是 429）
-
-**场景 3：点菜信息填错了**
-- 选 POST 创建用户
-- 把 Body 改成非法的 JSON 格式
-- 观察返回什么错误（通常是 400）
-
-**场景 4：点的菜卖完了**
-- 把用户 ID 改成 `u_404`（不存在的用户）
-- 观察返回什么错误（通常是 404）
-
-### 6.2 练习目标
-
-通过这些练习，你要掌握：
-1. **能看懂成功响应**：知道返回的数据在哪里
-2. **能看懂错误提示**：知道为什么失败、怎么改
-3. **有手感**：知道调用 API 的基本流程
-
 ---
 
-## 7. 总结：记住这三句话就够了
+## 6. 总结
 
-### 7.1 API 的三种形式
+别把 API 想得太高大上。
+在 AI 编程的时代，你只需要记住：
 
-| 类型 | 比喻 | 特点 |
-|------|------|------|
-| **HTTP API** | 外卖配送 | 通过网络调用，你发请求它回结果 |
-| **SDK API** | 餐厅堂食 | 通过函数调用，它内部帮你发请求 |
-| **库 API** | 自己做菜 | 本地函数，不走网络 |
+1.  **API 就是传声筒**：帮你把话传给 AI 模型。
+2.  **SDK 是好管家**：能用管家就别自己跑腿。
+3.  **看文档找三样**：地址、密钥、参数。
 
-### 7.2 核心记忆点
-
-1. **API = 接口**：就像餐厅的服务员，是你和对方系统的桥梁
-2. **调用三要素**：入口（网址/函数名）、参数（要告诉什么）、返回（会得到什么）
-3. **学会读文档**：就像看菜单，先确认能不能用，再看怎么用
-
-### 7.3 下一步建议
-
-现在你已经理解了 API 的基本概念，可以去：
-- 读一读真实的 API 文档（比如 OpenAI、DeepSeek 的文档）
-- 用 Postman 或 curl 试试真实的 API 调用
-- 在你的项目里接入第一个 API
-
----
-
-## 8. 名词速查表
-
-> 💡 **使用建议**：不用背！遇到不懂的词回来查就行。你只要会"看文档、会填参数、能看懂成功/失败"，就已经能开始用 API 了。
-
-| 名词 | 英文 | 解释 |
-|------|------|------|
-| **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 | 请求体，像点菜单的详细内容（具体的菜品要求） |
+这就够了。剩下的，交给 IDE 去写吧。