From 09fb29c382d88bb7136bfac4a7bb00983e225fdb Mon Sep 17 00:00:00 2001
From: hblu <hblu1985@163.com>
Date: Sun, 4 Jan 2026 18:46:58 +0800
Subject: [PATCH] docs: update project README content

---
 README.md | 135 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 127 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index fa77707..81b337f 100644
--- a/README.md
+++ b/README.md
@@ -138,22 +138,108 @@ uv --version      # 应显示 uv 0.x.x
     uv run main.py
     ```
 
-#### DeepSeek API 快速入门 (使用 OpenAI SDK)
-```python
-# 推荐使用 uv 管理依赖: uv add openai
-from openai import OpenAI
+#### DeepSeek API 快速入门 (主流推荐)
+
+DeepSeek API 完全兼容 OpenAI SDK，这意味着你可以直接使用最成熟的生态工具。
+
+**方式一：使用 OpenAI SDK (标准用法)**
+
+适合：简单对话、流式输出、不需要强类型约束的场景。
+
+```python
+# 1. 安装库
+# uv add openai python-dotenv
+
+import os
+from openai import OpenAI
+# .env 文件像一个保险箱，用来存放 API Key 等敏感信息，防止你把它上传到 GitHub 上被人盗用。
+from dotenv import load_dotenv
+
+# 加载当前目录下的 .env 文件内容到环境变量中
+load_dotenv()
 
-# 初始化客户端
 client = OpenAI(
-    api_key="your-api-key",  # 建议使用环境变量
+    # 从环境变量中读取 Key，更加安全
+    api_key=os.getenv("DEEPSEEK_API_KEY"), 
     base_url="https://api.deepseek.com"
 )
 
-# ... (代码保持不变)
+# 非流式调用 (一次性返回)
+response = client.chat.completions.create(
+    model="deepseek-chat", # 或 deepseek-reasoner (R1)
+    messages=[
+        # System Role: 给 AI 设定"人设"或"岗位职责"，它会始终遵守。
+        {"role": "system", "content": "你是一个金牌销售，说话极其有煽动性。"},
+        # User Role: 真实用户的输入。
+        {"role": "user", "content": "把这支钢笔卖给我。"}
+    ],
+    # Temperature (温度): 控制 AI 的"创造力"。
+    # 0.0 = 极其严谨、固定 (像个机器人)，适合写代码、数学题。
+    # 1.0 = 标准创造力 (默认)。
+    # 1.5+ = 脑洞大开、放飞自我 (可能胡说八道)，适合写诗、头脑风暴。
+    temperature=1.3 
+)
+print(response.choices[0].message.content)
+
+# 流式调用 (像 ChatGPT 打字机效果)
+stream = client.chat.completions.create(
+    model="deepseek-chat",
+    messages=[
+        {"role": "system", "content": "你是一个诗人。"},
+        {"role": "user", "content": "写一首关于Python的十四行诗"}
+        ],
+    temperature=1.3,
+    stream=True
+)
+for chunk in stream:
+    if chunk.choices[0].delta.content:
+        print(chunk.choices[0].delta.content, end="", flush=True)
+```
+
+**方式二：使用 PydanticAI (进阶 Agent 开发)**
+
+适合：需要**结构化输出** (JSON)、工具调用 (Tool Calling)、类型安全保障的现代 Agent 开发。
+
+```python
+# 1. 安装库
+# uv add pydantic-ai pydantic
+
+import os
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent
+
+# 加载环境变量 (确保 .env 文件中有 DEEPSEEK_API_KEY)
+load_dotenv()
+
+# 定义你期望的输出结构 (Schema)
+class MovieScript(BaseModel):
+    title: str = Field(description="电影标题")
+    genre: str = Field(description="流派，如科幻、悬疑")
+    characters: list[str] = Field(description="主要角色名单")
+    plot_twist: str = Field(description="意想不到的结局反转")
+
+# 初始化 Agent (2026 最佳实践: 使用 Short-hand 语法)
+# PydanticAI 会自动识别 'deepseek:deepseek-chat' 并从环境变量加载 API Key
+agent = Agent(
+    'deepseek:deepseek-chat',
+    output_type=MovieScript, 
+    system_prompt="你是一个好莱坞金牌编剧，擅长写出人意料的剧本。"
+)
+
+# 运行 Agent
+result = agent.run_sync('写一个关于程序员穿越到20年前的微电影剧本')
+
+# 直接获取结构化数据 (IDE会有智能提示！)
+print(f"🎬 标题: {result.output.title}")
+print(f"🎭 类型: {result.output.genre}")
+print(f"🎭 角色: {result.output.characters}")
+print(f"🤯 反转: {result.output.plot_twist}")
 ```
 
 > [!TIP]
-> **进阶选择**：对于复杂的 Agent 开发，推荐使用 **PydanticAI**，它能提供更好的类型安全和结构化输出支持。
+> **为什么要用 PydanticAI？**
+> 相比手动解析 JSON 字符串，PydanticAI 能自动处理重试、验证错误，并给你完美的 IDE 代码提示 (Autocomplete)。这是开发复杂 AI 应用的终极武器。
 
 #### Streamlit vs Chainlit
 
@@ -177,6 +263,39 @@ async def main(message: cl.Message):
     # 这里调用 DeepSeek API
     await cl.Message(content=f"你说了: {message.content}").send()
 ```
+#### 🌐 Context7: 跨越 AI 的知识断层 (The Documentation Bridge)
+
+在 Vibe Coding 中，你可能会遇到这样一个尴尬场景：AI 写得头头是道，代码运行却满屏爆红。
+
+**1. LLM 的阿喀琉斯之踵 (The Limitations)**
+*   **知识截止 (Knowledge Cutoff)**: AI 的记忆停留在训练结束那一刻。它不知道昨天发布的 `PydanticAI 2.0` 有什么新特性，也不知道 `Streamlit` 刚废弃了哪个旧接口。
+*   **一本正经的胡说 (Hallucination)**: 当 AI 不知道某个库的用法时，它倾向于"猜"一个看起来合理的函数名（例如臆造一个 `st.make_it_beautiful()`），导致代码根本跑不通。
+
+**2. 为什么必须用 Context7 MCP?**
+*   **实时获取**：Context7 是一个直接连接官方文档的管道。它能抓取最新的 API 定义和代码示例。
+*   **对症下药**：使用 Context7，你的 AI 助手可以先"查字典"（阅读最新文档），再"写作文"（生成代码）。
+*   **2026 开发标配**：对于本课程使用的 `PydanticAI`、`Streamlit` 等更新极快的现代化框架，**不查文档直接写的代码，可用性几乎为零**。
+
+> [!TIP]
+> **最佳实践**：
+> 在 Cursor 中，当你使用较新的库时，请在 Prompt 中显式要求：
+> *"使用 Context7 查阅最新的 PydanticAI 文档，然后帮我写..."*
+
+#### 🚀 为什么追求"Using the Edge"？ (Why Cutting-Edge Matters)
+
+本课程特意选择了 `uv`, `PydanticAI` (2025/2026), `Python 3.14` 等最新技术栈，而非传统的 `pip` 或 `LangChain`。这并非为了"赶时髦"，而是基于 **AI 时代的生存法则**：
+
+1.  **为 AI 而生 (AI-Native)**:
+    *   **Old Way**: 旧框架（如 Django）是为人写的，文档冗长，配置复杂。
+    *   **New Way**: 新框架（如 PydanticAI）天然支持 Type Hint 和 Schema 生成，这种"强类型"代码是 AI 最容易理解和生成的语言，能显著减少 AI 的幻觉和 Bug。
+
+2.  **极速迭代 (Velocity)**:
+    *   **uv** 比 pip 快 100 倍。在 Vibe Coding 中，你的灵感转瞬即逝，工具不应该成为等待的瓶颈。
+
+3.  **拥抱变化 (Future-Proofing)**:
+    *   AI 领域一周的更新量等于过去一年。掌握 2026 年的 Best Practices，意味着你拥有最先进的生产力工具，而不是在学习即将被淘汰的技术。
+
+> **Simple is Better**: 你会发现，最先进的工具往往也是最简单的。没有复杂的 `requirements.txt` 和虚拟环境路径地狱，只有一个 `uv add`。
 
 ### 1.4 动手实践：三个"最小可运行"示例 (MVP Hands-on)