836 lines
31 KiB
Markdown
836 lines
31 KiB
Markdown
# Python程序设计课程设计
|
||
|
||
## 🎯 课程概述
|
||
|
||
**课程主题**：基于 DeepSeek API + Streamlit 的 AI 应用开发
|
||
|
||
**课程理念**：
|
||
|
||
> 在 AI 时代，代码可以生成，Bug 可以修复，文档可以自动撰写——
|
||
>
|
||
> **但判断什么值得做、为结果负责、理解用户真实需求、在约束中做取舍，这些能力永远属于你。**
|
||
|
||
本课程通过 AI 代码编辑器（如 Cursor、Windsurf）进行 **Vibe Coding**，让学生体验"用自然语言编程"的全新开发方式。但更重要的是，在这个过程中**思考人与 AI 的协作边界**，培养 AI 时代真正不可替代的能力。
|
||
|
||
**技术栈**：
|
||
- 🐍 **Python 3.12+** (2026 Recommended)
|
||
- ⚡ **uv** (极速 Python 项目管理)
|
||
- 🤖 **DeepSeek API** + **PydanticAI** (Agent 框架)
|
||
- 🎨 **Streamlit** (Data Apps) / **Chainlit** (Chatbots)
|
||
- 🛠️ **Cursor / Windsurf** (AI 代码编辑器)
|
||
|
||
---
|
||
|
||
## 📅 课程安排
|
||
|
||
| 日期 | 内容 | 形式 |
|
||
|:---:|:---:|:---:|
|
||
| **第1天** | 课程讲解与演示 | 教师授课 |
|
||
| **第2天** | 自主开发 | 学生自学 |
|
||
| **第3天** | 中期答疑 | 集中答疑 |
|
||
| **第4天** | 自主开发 | 学生自学 |
|
||
| **第5天** | 项目展示与评审 | 成果展示 |
|
||
|
||
---
|
||
|
||
## 🛠️ 第0天：环境预备 (Day 0)
|
||
|
||
> [!IMPORTANT]
|
||
> **请在正式上课前完成以下准备**。这能让你在第一天直接进入"Vibe Coding"状态，而不是卡在安装软件上。
|
||
|
||
### 1. 软件安装清单
|
||
- **Code Editor**: 推荐 [Cursor](https://cursor.com) (自带 AI) 或 VS Code + Windsurf 插件, [TRAE CN](https://www.trae.cn)。
|
||
- **Git**: 分布式版本控制系统 (必装)。[下载地址](https://git-scm.com/)。
|
||
- **Python 3.12+**: 访问 [python.org](https://www.python.org/downloads/) 下载。
|
||
- **uv**: 极速 Python 包管理器 (比 pip 快 10-100 倍)。
|
||
- Mac/Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
|
||
- Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
|
||
|
||
### 2. 验证环境
|
||
在终端 (Terminal) 输入以下命令，看到版本号即成功：
|
||
```bash
|
||
python --version # 应显示 Python 3.12.x 或更高
|
||
uv --version # 应显示 uv 0.x.x
|
||
git --version # 应显示 git version 2.x.x
|
||
```
|
||
|
||
---
|
||
|
||
## 📚 第1天：课程讲解与演示（3学时）
|
||
|
||
### 1.1 课程导入（30分钟）
|
||
|
||
#### 什么是 Vibe Coding？
|
||
- **定义**：一种"以人为本、AI 为器"的编程范式。开发者专注于**意图描述**和**结果验收**，而将代码实现、调试细节交由 AI 辅助完成。
|
||
- **核心逻辑**："描述你想要什么，而不是告诉计算机怎么做"。
|
||
- **演示**：用自然语言在 3 分钟内创建一个完整应用。
|
||
|
||
#### 为什么要学 Python 基础？(The "Why" in AI Era)
|
||
|
||
很多同学会问：*"既然 AI 能写代码，我为什么还要学基础语法？"*
|
||
|
||
> **即使是法拉利，也需要懂驾驶原理的赛车手。**
|
||
|
||
在 Vibe Coding 中，你需要具备**两种核心能力**才能驾驭 AI：
|
||
1. **准确描述 (Prompting)**: 你需要懂一点术语 (如 "List", "Loop", "Function") 才能精准指挥 AI。
|
||
2. **验证结果 (Auditing)**: AI 会犯错 (幻觉)。你需要能读懂代码，判断它是不是在"一本正经地胡说八道"。
|
||
|
||
**重点掌握：**
|
||
* **0-Based Indexing**: 为什么计算机从 0 开始数数？(因为偏移量的概念)。
|
||
* **逻辑控制**: `if`, `for`, `while` 是所有程序的骨架。
|
||
* **函数思维**: 把大问题拆解成小模块 (Input -> Process -> Output)。
|
||
|
||
#### AI 时代，什么能力真正属于你？
|
||
|
||
> **AI 能做的事越来越多：** 语法查询、代码生成、Bug 修复、文档撰写、测试创建、架构建议、代码重构...
|
||
>
|
||
> **但这些能力永远属于你：**
|
||
> - 🎯 **判断什么值得做** —— 选题的眼光和价值判断
|
||
> - 📋 **为结果负责** —— 代码能跑不等于问题解决
|
||
> - 👥 **理解真实需求** —— 用户要的不是功能，是解决方案
|
||
> - ⚖️ **在约束中取舍** —— 时间、资源、技术的平衡
|
||
> - 🤝 **与人协作** —— 包括与 AI 协作
|
||
|
||
本课程不只是教你用 AI 写代码，更是让你**体验和思考这些不可替代的能力**。
|
||
|
||
#### AI 代码编辑器介绍
|
||
- **Cursor**：[https://cursor.com](https://cursor.com)
|
||
- **Windsurf**：[https://codeium.com/windsurf](https://codeium.com/windsurf)
|
||
- **TRAE CN**：[https://www.trae.cn](https://www.trae.cn)
|
||
- **核心模式**：
|
||
- **Approve/Reject**：人是最终的决策者。
|
||
- **Context Awareness**：如何让 AI "看见"你的整个项目。
|
||
|
||
### 1.2 Vibe Coding 快速上手：新手四步法 (The 4-Step Loop)
|
||
|
||
对于 0 基础的新手，不要试图一次性写出完美代码。请遵循 **"D-P-R-I"** 循环：
|
||
|
||
1. **Define (定义)**：用一句话说清楚你要做什么。
|
||
* ❌ *"写个程序"*
|
||
* ✅ *"写一个倒计时器，要有开始/暂停按钮，时间到了会弹窗提示"*
|
||
2. **Prompt (提示)**：扮演产品经理，给 AI 下指令。
|
||
* **公式**：`角色 + 任务 + 限制条件`
|
||
* *例："你是一个 Python 专家。请用 Streamlit 写一个 番茄钟应用。要求：界面简洁，背景是黑色，使用 Session State 记录时间。"*
|
||
3. **Review (审查)**：AI 写完后，不要盲目运行。
|
||
* **一眼定真**：代码里有没有显然的红色波浪线 (报错)？
|
||
* **结构检查**：有没有 `import`？有没有主函数？
|
||
4. **Iterate (迭代)**：运行 -> 报错 -> 把报错扔给 AI。
|
||
* *"Vibe Coding 的精髓不在于一次写对，而在于快速试错。"*
|
||
* **黄金法则**：如果 AI 连续改 3 次还没修好，**停下来**！这通常意味着你的 Prompt 逻辑有问题，或者方向错了。
|
||
|
||
### 1.3 技术栈讲解（60分钟）
|
||
|
||
#### ⚡ 2026 现代 Python 工作流 (uv)
|
||
|
||
我们将告别繁琐的 `pip` 和虚拟环境配置，使用 Rust 编写的 **uv** 作为唯一工具。
|
||
|
||
**核心三步走 (The 3-Step Vibe)**:
|
||
|
||
1. **初始化 (Init)**: 创建一个干净的"代码工作台"。
|
||
```bash
|
||
uv init my-ai-app
|
||
cd my-ai-app
|
||
```
|
||
2. **添加工具 (Add)**: 就像给手机装 App 一样简单。
|
||
```bash
|
||
uv add streamlit chainlit openai python-dotenv
|
||
```
|
||
|
||
> [!TIP]
|
||
> **国内用户加速指南 (Domestic Mirror)**:
|
||
> 建议配置国内镜像源（如清华源）以获得极速体验。
|
||
> **全局配置 (Global Config)**:
|
||
> ```bash
|
||
> # macOS/Linux
|
||
> mkdir -p ~/.config/uv
|
||
> echo '[[index]]' > ~/.config/uv/uv.toml
|
||
> echo 'url = "https://pypi.tuna.tsinghua.edu.cn/simple"' >> ~/.config/uv/uv.toml
|
||
> echo 'default = true' >> ~/.config/uv/uv.toml
|
||
>
|
||
> # Windows (PowerShell)
|
||
> md -Force $env:APPDATA\uv
|
||
> @('[[index]]', 'url = "https://pypi.tuna.tsinghua.edu.cn/simple"', 'default = true') | Set-Content $env:APPDATA\uv\uv.toml
|
||
> ```
|
||
3. **运行 (Run)**: 一键启动，无需担心环境冲突。
|
||
```bash
|
||
uv run main.py
|
||
```
|
||
|
||
|
||
### 1.3.0 核心概念补课: DeepSeek 与 API
|
||
|
||
#### 🦄 什么是 DeepSeek?
|
||
DeepSeek 是 2026 年最耀眼的 **开源 AI 模型**。
|
||
* **代码天才**: 它的 Coding 能力在 2026 年稳居第一梯队，甚至超过了许多闭源模型。
|
||
* **性价比之王**: API 价格极低（几乎是免费的），非常适合学生党和初创项目。
|
||
* **开源精神**: "Open Weights" 让它成为全球开发者的宠儿。
|
||
|
||
#### 🔌 什么是 API (Application Programming Interface)?
|
||
想象你在去一家餐厅吃饭：
|
||
* **你 (User)**: 想要吃饭（比如"生成一段代码"）。
|
||
* **厨房 (LLM)**: 大厨负责做饭（生成内容），但你不能直接冲进厨房。
|
||
* **服务员 (API)**: 你把菜单（Prompt）给服务员，服务员把需求传给厨房，再把菜端给你。
|
||
|
||
**API 就是那个"服务员"**。它让你的 Python 代码能优雅地和远端的 AI 大脑对话。
|
||
|
||
#### 💡 为什么要用 LLM API？
|
||
1. **稳定性**: 网页版 ChatGPT 可能会封号、会变慢，API 则是为工业级应用设计的，稳定可靠。
|
||
2. **可集成 (Embeddable)**: 你不能把网页版 ChatGPT 塞进你的 Excel 里，但 API 可以。你可以把 AI 的"大脑"装进任何 APP、网页或脚本中。
|
||
3. **自动化 (Automation)**: 网页版一次问一个问题；API 可以写个循环，一分钟处理 1000 个 Excel 表格。
|
||
|
||
#### 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(
|
||
# 从环境变量中读取 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]
|
||
> **为什么要用 PydanticAI？**
|
||
> 相比手动解析 JSON 字符串，PydanticAI 能自动处理重试、验证错误，并给你完美的 IDE 代码提示 (Autocomplete)。这是开发复杂 AI 应用的终极武器。
|
||
|
||
#### Streamlit vs Chainlit
|
||
|
||
- **Streamlit**: 适合构建 **数据仪表板**、**工具类应用** (如 Excel 处理、图表分析)。
|
||
- **Chainlit**: 适合构建 **聊天机器人**、**多轮对话 Agent** (自带优美的聊天界面)。
|
||
|
||
**Streamlit 示例 (数据应用)**:
|
||
```python
|
||
import streamlit as st
|
||
|
||
st.title("数据分析看板")
|
||
st.line_chart([1, 5, 2, 6])
|
||
```
|
||
|
||
**Chainlit 示例 (对话应用)**:
|
||
```python
|
||
import chainlit as cl
|
||
|
||
@cl.on_message
|
||
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)
|
||
|
||
接下来的 45 分钟，请跟随老师在你的电脑上运行这三个示例。这是你迈向 Vibe Coding 的第一步。
|
||
|
||
> [!NOTE]
|
||
> **准备工作**：
|
||
> 确保你已经初始化了项目并填入了 Key：
|
||
> ```bash
|
||
> mkdir day1-demo
|
||
> cd day1-demo
|
||
> uv init
|
||
> uv add openai python-dotenv streamlit chainlit
|
||
> # 创建 .env 文件并填入: DEEPSEEK_API_KEY=sk-xxxxxx
|
||
> ```
|
||
|
||
#### 示例 A: Hello AI (CLI 脚本)
|
||
**目标**：理解 OpenAI SDK 的最基本调用方式。
|
||
**文件**：`main.py`
|
||
|
||
```python
|
||
import os
|
||
from openai import OpenAI
|
||
from dotenv import load_dotenv
|
||
|
||
# 1. 加载环境变量 (.env)
|
||
load_dotenv()
|
||
api_key = os.getenv("DEEPSEEK_API_KEY")
|
||
|
||
if not api_key:
|
||
print("❌ 错误：未找到 DEEPSEEK_API_KEY，请检查 .env 文件")
|
||
exit()
|
||
|
||
# 2. 初始化客户端
|
||
client = OpenAI(api_key=api_key, base_url="https://api.deepseek.com")
|
||
|
||
# 3. 发送请求
|
||
print("🤖 AI 正在思考...")
|
||
response = client.chat.completions.create(
|
||
model="deepseek-chat",
|
||
messages=[
|
||
{"role": "system", "content": "你是一个赛博朋克风格的诗人。"},
|
||
{"role": "user", "content": "用两句话描述代码的魅力。"},
|
||
],
|
||
stream=False
|
||
)
|
||
|
||
# 4. 输出结果
|
||
print("\n" + "="*30)
|
||
print(response.choices[0].message.content)
|
||
print("="*30 + "\n")
|
||
```
|
||
**运行**：
|
||
```bash
|
||
uv run main.py
|
||
```
|
||
|
||
#### 示例 B: 魔法文案生成器 (Streamlit)
|
||
**目标**：不写 HTML/CSS，用 Python 5分钟构建可视化的 AI 应用。
|
||
**文件**：`app_gui.py`
|
||
|
||
```python
|
||
import streamlit as st
|
||
import os
|
||
from openai import OpenAI
|
||
from dotenv import load_dotenv
|
||
|
||
load_dotenv()
|
||
client = OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com")
|
||
|
||
# 1. 页面配置
|
||
st.set_page_config(page_title="魔法文案生成器", page_icon="✨")
|
||
st.title("✨ 魔法文案生成器")
|
||
|
||
# 2. 左侧侧边栏
|
||
with st.sidebar:
|
||
st.header("配置")
|
||
style = st.selectbox("选择风格", ["文艺风", "幽默风", "硬核科技风", "发疯文学"])
|
||
length = st.slider("字数限制", 5, 100, 50)
|
||
|
||
# 3. 主界面 chat intent
|
||
# 初始化聊天记录
|
||
if "messages" not in st.session_state:
|
||
st.session_state.messages = []
|
||
|
||
# 显示历史消息
|
||
for message in st.session_state.messages:
|
||
with st.chat_message(message["role"]):
|
||
st.markdown(message["content"])
|
||
|
||
# 4. 处理用户输入
|
||
if theme := st.chat_input("你想写关于什么主题的文案？(例如：周五下班)"):
|
||
# 显示用户消息
|
||
st.session_state.messages.append({"role": "user", "content": theme})
|
||
with st.chat_message("user"):
|
||
st.markdown(theme)
|
||
|
||
# 生成并显示助手回复
|
||
with st.chat_message("assistant"):
|
||
prompt = f"请用{style}写一段关于'{theme}'的朋友圈文案，带Emoji，{length}字以内。"
|
||
|
||
# 使用流式输出 (Stream) 增加"Vibe"
|
||
stream = client.chat.completions.create(
|
||
model="deepseek-chat",
|
||
messages=[{"role": "user", "content": prompt}],
|
||
stream=True
|
||
)
|
||
response = st.write_stream(stream)
|
||
|
||
st.session_state.messages.append({"role": "assistant", "content": response})
|
||
```
|
||
**运行**：
|
||
```bash
|
||
uv run streamlit run app_gui.py
|
||
```
|
||
|
||
#### 示例 C: 会聊天的猫 (Chainlit)
|
||
**目标**：构建像 ChatGPT 一样的对话界面，支持流式输出 (Streaming)。
|
||
**文件**：`app_chat.py`
|
||
|
||
```python
|
||
import chainlit as cl
|
||
import os
|
||
from openai import OpenAI
|
||
from dotenv import load_dotenv
|
||
|
||
load_dotenv()
|
||
client = OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com")
|
||
|
||
@cl.on_message
|
||
async def main(message: cl.Message):
|
||
# 1. 准备消息历史
|
||
# Chainlit 会自动管理 session，但这里我们构建一个简单的历史传给 API
|
||
msg_history = [
|
||
{"role": "system", "content": "你是一只高冷的猫，说话句尾要带'喵'。"},
|
||
{"role": "user", "content": message.content}
|
||
]
|
||
|
||
# 2. 创建回复消息容器
|
||
msg = cl.Message(content="")
|
||
await msg.send()
|
||
|
||
# 3. 调用 AI 并流式(stream)接收
|
||
stream = client.chat.completions.create(
|
||
model="deepseek-chat",
|
||
messages=msg_history,
|
||
stream=True
|
||
)
|
||
|
||
# 4. 实时推送到界面
|
||
for chunk in stream:
|
||
if token := chunk.choices[0].delta.content:
|
||
await msg.stream_token(token)
|
||
|
||
# 5. 完成更新
|
||
await msg.update()
|
||
```
|
||
**运行**：
|
||
```bash
|
||
uv run chainlit run app_chat.py -w
|
||
```
|
||
|
||
### 1.5 项目要求说明（15分钟）
|
||
|
||
#### 项目选题（任选其一或自拟）
|
||
|
||
| 难度 | 项目名称 | 服务对象/场景 | 解决的真实问题/价值 |
|
||
|:---:|:---|:---|:---|
|
||
| ⭐⭐ | AI 写作助手 | 学生/自媒体 | 写作与润色提效，输出更顺畅 |
|
||
| ⭐⭐ | 智能单词本 | 英语学习者 | 释义+例句，降低背词与造句门槛 |
|
||
| ⭐⭐ | AI 任务拆解教练 | 学习/入职 | 把目标拆成可执行步骤与提醒 |
|
||
| ⭐⭐⭐ | 会议纪要助手 | 团队会议 | 自动要点/待办提炼，减少遗漏 |
|
||
| ⭐⭐⭐ | 代码解释与修复 | 编程学习者 | 逐行讲解+修复建议，缩短排错时间 |
|
||
| ⭐⭐⭐ | 产品需求澄清助手 | PM/开发 | 拆解模糊需求→可执行条目 |
|
||
| ⭐⭐⭐ | 学习笔记整理 | 学生/职场 | 将笔记结构化，生成概要/测验题 |
|
||
| ⭐⭐⭐⭐ | 智能知识库问答 | 企业/课程 | 自有文档精准问答，减少人工答疑 |
|
||
| ⭐⭐⭐⭐ | AI 数据洞察仪表盘 | 中小团队 | 上传表格自动生成洞察与可视化 |
|
||
| ⭐⭐⭐⭐ | AI 面试官 | 求职者 | 简历定制问答，练习反馈与改进建议 |
|
||
| ⭐⭐⭐⭐⭐ | 多 Agent 决策工作坊 | 方案评审 | 多角色视角辩论，生成决策要点 |
|
||
|
||
> 💡 **选题思考**：不只是"我能做什么"，更要思考"这个项目**对谁有价值**？解决什么**真实问题**？"
|
||
|
||
#### 🚀 从 0 到 1：如何开始？(Starter Kit)
|
||
|
||
面对空白的代码编辑器感到迷茫？请按以下步骤操作：
|
||
|
||
**Step 1: 只要写出 README.md，你就完成了一半**
|
||
不要急着写代码。先用自然语言在 `Project_Design.md` (或草稿纸) 上写下：
|
||
1. **一句话描述**：我的应用叫什么？它是给谁用的？
|
||
2. **核心功能**：它*必须*有的 3 个功能是什么？(MVP)
|
||
3. **交互流程**：用户打开 App -> 点击什么 -> 看到什么？
|
||
|
||
**Step 2: 让 AI 写第一行代码**
|
||
把Step 1的内容喂给 Cursor/Windsurf：
|
||
> *"我正在开发一个[项目名]。请阅读我的设计思路：[粘贴你的描述]。请帮我生成项目结构，并创建最基础的 app.py 框架。"*
|
||
|
||
**Step 3: 最小可行性验证**
|
||
* 生成的代码能跑吗？(Run it)
|
||
* 界面上能看到按钮吗？(See it)
|
||
* 如果报错，直接把报错信息截图或复制给 AI。
|
||
|
||
> **记住**：你是在搭建积木，不是在烧制砖块。先搭出轮廓，再修饰细节。
|
||
|
||
---
|
||
|
||
## 🔧 第2天：自主开发
|
||
|
||
### 建议学习路线
|
||
|
||
```
|
||
上午：环境搭建 + 熟悉工具
|
||
├── 安装 Python、Cursor/Windsurf
|
||
├── 申请 DeepSeek API Key
|
||
├── 运行第一天的示例代码
|
||
└── 熟悉 AI 编辑器的操作（Composer/Chat 模式）
|
||
|
||
下午：开始项目开发
|
||
├── 确定项目选题
|
||
├── 用自然语言描述项目需求（Project Requirements）
|
||
├── 让 AI 生成初始代码框架
|
||
└── 运行调试，迭代优化
|
||
```
|
||
|
||
### Vibe Coding 技巧
|
||
|
||
#### 1. 上下文管理（Context）
|
||
AI 不是神，它需要知道你的代码、你的报错、你的意图。
|
||
- **@Files**：在 Cursor 中使用 `@` 引用相关文件。
|
||
- **Paste Error**：直接粘贴报错信息，不要只说"报错了"。
|
||
|
||
#### 2. 有效的 Prompt 模板
|
||
```markdown
|
||
角色：你是一个 Python 专家。
|
||
任务：创建一个 [项目类型]，使用 [技术栈]。
|
||
|
||
功能需求：
|
||
1. [功能1]
|
||
2. [功能2]
|
||
|
||
约束条件：
|
||
- 代码简洁，有注释
|
||
- 使用 Streamlit 的 sidebar 布局
|
||
```
|
||
|
||
#### 3. 常见问题排查
|
||
- **Streamlit 页面频繁刷新？** -> 检查是否把初始化代码放在了循环里，或者没用 `st.session_state`。
|
||
- **API 报错 401？** -> 检查 API Key 是否正确，环境变量是否生效。
|
||
|
||
### 学习资源
|
||
- 📚 **Streamlit 文档**：[docs.streamlit.io](https://docs.streamlit.io) (推荐阅读 `st.chat_message` 和 `st.write_stream` 章节)
|
||
- 🤖 **DeepSeek API**：[platform.deepseek.com](https://platform.deepseek.com)
|
||
- 📺 **教程**：B站搜索 "Streamlit Chatbot" 或 "Cursor 教程"
|
||
|
||
---
|
||
|
||
## ❓ 第3天：中期答疑
|
||
|
||
### 答疑内容
|
||
- ✅ 项目选题确认
|
||
- 🐛 疑难 Bug 攻关
|
||
- 🏗️ 架构设计与优化建议
|
||
|
||
### 常见问题解决方案表
|
||
|
||
| 问题分类 | 现象描述 | 解决方案核心 |
|
||
|:---|:---|:---|
|
||
| **环境** | `ModuleNotFoundError` | 运行 `pip install <库名>` |
|
||
| **API** | `402 Payment Required` | 账户余额不足，需充值 |
|
||
| **API** | 回复中断/不完整 | 检查 `max_tokens` 设置，或上下文超长 |
|
||
| **Streamlit** | 变量一点按钮就重置 | **必须**使用 `st.session_state` 存储变量 |
|
||
| **Streamlit** | 运行无反应 | 确保命令是 `streamlit run app.py` 而不是 `python app.py` |
|
||
|
||
### 中期检查清单
|
||
- [ ] 选题已定，核心功能跑通
|
||
- [ ] 理解核心代码逻辑（能给别人讲清楚）
|
||
- [ ] 无论是 Git 还是手动备份，确保代码有存档
|
||
- [ ] 能清晰回答：**我的项目为谁解决了什么问题？**
|
||
|
||
---
|
||
|
||
## 🔧 第4天：自主开发
|
||
|
||
### 建议工作重点
|
||
- **完善功能**：处理边界情况（如用户输入为空、API 请求失败）。
|
||
- **美化界面**：使用 `st.columns` 排版，添加 Emoji，优化提示语。
|
||
- **准备展示**：开始思考演示流程，准备 README。
|
||
|
||
> [!TIP]
|
||
> **加分项**：
|
||
> - 💾 **数据持久化**：对话不丢失（存本地 JSON 或 SQLite）。
|
||
> - 📱 **响应式**：手机端打开也好看。
|
||
> - 📊 **可视化**：用图表直观展示数据。
|
||
|
||
---
|
||
|
||
## 🎤 第5天：项目展示与评审
|
||
|
||
### 展示形式
|
||
- **时间**：每组 (2-3人) **5分钟**。
|
||
- **内容**：PPT/文档介绍 (1min) + 实机演示 (4min) + 心得分享 (2min)。
|
||
|
||
### 评分标准（总分 100）
|
||
|
||
| 维度 | 分值 | 核心考量 |
|
||
|:---|:---:|:---|
|
||
| **功能完成度** | 25 | 核心功能由无 Bug，流程跑通 |
|
||
| **创意与体验** | 20 | 界面美观，交互顺滑，解决痛点 |
|
||
| **技术实现** | 20 | 代码结构清晰，错误处理完善 |
|
||
| **展示表现** | 10 | 表达清晰，演示流畅 |
|
||
| **开发心得** | 15 | **(重要)** 对 AI 协作的真实思考与反思 |
|
||
| **学习态度** | 10 | 课堂与答疑的参与度 |
|
||
|
||
> **难度系数**：
|
||
> 基础项目 (⭐⭐) 系数 ×1.0；挑战项目 (⭐⭐⭐⭐) 系数 ×1.1。
|
||
> *鼓励挑战，但也尊重将简单事情做到极致。*
|
||
|
||
---
|
||
|
||
## 📦 提交要求
|
||
|
||
### 1. Git 提交指南 (必做)
|
||
本课程通过校内 Git 平台提交作业。请组长负责统一提交。
|
||
|
||
#### Step 1: 注册与建仓
|
||
1. **访问平台**: [HBLU Git](http://hblu.top:3000/Python2025-CourseDesign) (校内自建 Gitea)。
|
||
2. **注册账号**: 组长注册一个账号。
|
||
3. **创建仓库**: 在 `Python2025-CourseDesign` 组织下新建仓库。
|
||
- 命名格式建议: `GroupXX-ProjectName` (如 `Group01-AIWriter`)。
|
||
|
||
#### Step 2: 规范化提交
|
||
请确保你的项目符合以下 Git 规范：
|
||
|
||
1. **添加 `.gitignore` (至关重要)**
|
||
> ⚠️ **严禁上传**: `.env` (包含 API Key) 和 `.venv` (包含几千个依赖文件)。
|
||
|
||
在项目根目录新建 `.gitignore` 文件，填入以下内容：
|
||
```bash
|
||
.env
|
||
.venv/
|
||
__pycache__/
|
||
.DS_Store
|
||
```
|
||
|
||
2. **推送代码**
|
||
```bash
|
||
git init
|
||
git add .
|
||
git commit -m "Complete Course Design Project"
|
||
# 将下面的 URL 换成你刚才创建的仓库地址
|
||
git remote add origin http://hblu.top:3000/Python2025-CourseDesign/Your-Repo-Name.git
|
||
git push -u origin main
|
||
```
|
||
|
||
### 2. 这里的 README.md 怎么写？
|
||
你的仓库 `README.md` **必须**包含以下三个模块：
|
||
|
||
#### 2.1 团队成员与贡献 (必填)
|
||
| 姓名 | 学号 | 主要贡献 (具体分工) |
|
||
|:---:|:---:|:---|
|
||
| 张三 | 2023xxx | (组长) 核心逻辑开发、Prompt 编写 |
|
||
| 李四 | 2023xxx | 前端界面设计、PPT 制作 |
|
||
| 王五 | 2023xxx | 文档撰写、测试与 Bug 修复 |
|
||
|
||
#### 2.2 项目简介 & 运行指南
|
||
```markdown
|
||
## 简介
|
||
(一句话介绍：这个项目解决了什么痛点？)
|
||
|
||
## 如何运行
|
||
1. 安装依赖：`uv sync`
|
||
2. 配置 Key：复制 `.env.example` 为 `.env` 并填入 Key
|
||
3. 启动：`uv run streamlit run app.py`
|
||
```
|
||
|
||
#### 2.3 开发心得 (不少于 500 字)
|
||
> 请直接写在 README 的末尾，或单独创建一个 `REFLECTION.md`。
|
||
|
||
**请围绕以下核心问题撰写：**
|
||
1. **选题思考**：为什么做这个？解决了谁的痛苦？
|
||
2. **AI 协作体验**：
|
||
- 第一次用 AI 写代码的感觉？
|
||
- 哪个 Prompt 让你直呼"牛逼"？哪个让你想砸键盘？
|
||
3. **自我反思**：
|
||
- AI 时代，我作为程序员的核心竞争力到底是什么？
|
||
|
||
---
|
||
|
||
## 🔗 附录：环境配置指南
|
||
|
||
### 1. 基础环境
|
||
- **Python**: 推荐 3.12+ (2026 Recommended)
|
||
- **依赖管理**: **uv** (强烈推荐，替代 pip/venv)
|
||
- **编辑器**: 推荐 Cursor 或 VS Code + Windsurf 插件。
|
||
|
||
### 2. uv 核心操作指南
|
||
|
||
#### 2.1 安装 uv
|
||
- **Mac/Linux**: `curl -LsSf https://astral.sh/uv/install.sh | sh`
|
||
- **Windows**: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
|
||
|
||
#### 2.2 Python 版本管理 (无需手动下载 Python!)
|
||
uv 会自动管理 Python 版本，**你甚至不需要去 python.org 下载 installer**。
|
||
- `uv python install 3.12` # 下载并安装 Python 3.12
|
||
- `uv python list` # 查看已安装和可用的 Python 版本
|
||
- `uv python pin 3.12` # 锁定当前项目使用的 Python 版本 (生成 .python-version)
|
||
|
||
#### 2.3 项目与依赖管理
|
||
- `uv init <项目名>` # 初始化一个新项目
|
||
- `uv add <库名>` # 添加依赖 (例: `uv add streamlit`)
|
||
- `uv remove <库名>` # 移除依赖
|
||
- `uv tree` # 查看依赖关系树
|
||
- `uv sync` # 根据 lock 文件同步环境 (团队协作神器)
|
||
|
||
#### 2.4 运行代码
|
||
使用 `uv run` 可以自动检测虚拟环境，无需手动 activate。
|
||
- `uv run app.py` # 运行 Python 脚本
|
||
- `uv run streamlit run app.py` # 运行 Streamlit 应用
|
||
- `uv run --with pandas script.py` # 临时安装 pandas 并运行脚本 (不污染环境)
|
||
|
||
### 3. API Key 管理示例 (`.env`)
|
||
不要把 Key 写死在代码里！
|
||
```python
|
||
# .env 文件
|
||
DEEPSEEK_API_KEY=sk-xxxxxxx
|
||
```
|
||
```python
|
||
# app.py
|
||
import os
|
||
# uv add python-dotenv
|
||
from dotenv import load_dotenv
|
||
|
||
load_dotenv() # 加载 .env
|
||
api_key = os.getenv("DEEPSEEK_API_KEY")
|
||
```
|
||
|
||
> [!IMPORTANT]
|
||
> **安全最佳实践**：
|
||
> 1. **添加 `.env` 到 `.gitignore`**：确保 `.gitignore` 文件中包含 `.env`，防止 API Key 被误上传到 Git 仓库。
|
||
> 2. **创建 `.env-example` 模板文件**：在项目中提供一个 `.env-example` 文件，列出所需的环境变量 (但**不包含真实的 Key**)，方便其他开发者或组员快速配置。
|
||
>
|
||
> ```bash
|
||
> # .env-example 文件内容 (提交到 Git)
|
||
> DEEPSEEK_API_KEY=your_api_key_here
|
||
> ```
|
||
>
|
||
> 组员克隆项目后，只需：
|
||
> ```bash
|
||
> cp .env-example .env # 复制模板
|
||
> # 然后编辑 .env 填入自己的 API Key
|
||
> ```
|
||
|
||
|
||
### 4. Git 简明操作手册 (Cheatsheet)
|
||
|
||
Git 是程序员的"后悔药"，它能记录你代码的每一次修改。
|
||
|
||
#### 4.1 第一次安装后的配置 (仅需一次)
|
||
告诉 Git 你是谁：
|
||
```bash
|
||
git config --global user.name "Your Name" # 用英文名
|
||
git config --global user.email "your_email@example.com"
|
||
```
|
||
|
||
#### 4.2 常用指令图解
|
||
1. **`git init`**: 初始化仓库 (在项目根目录运行，"我要开始记录这个项目了")。
|
||
2. **`git status`**: 查看状态 ("现在有哪些文件变了？")。
|
||
3. **`git add .`**: 暂存所有修改 ("把这些变化放进暂存区，准备存档")。
|
||
* *就像玩游戏时按了“保存”，但还没确认覆盖存档覆盖。*
|
||
4. **`git commit -m "描述"`**: 提交存档 ("确认保存，并写个备注")。
|
||
* *备注要清晰，例如 "Fix: 修复了登录按钮的Bug"*。
|
||
5. **`git log`**: 查看历史 ("查看存档记录")。
|
||
|
||
#### 4.3 常用场景速查
|
||
- **我想把代码存到服务器 (Gitea)**:
|
||
```bash
|
||
git remote add origin <仓库地址>
|
||
git push -u origin main
|
||
```
|
||
- **我想下载别人的代码**:
|
||
```bash
|
||
git clone <仓库地址>
|
||
```
|
||
- **后悔了，想撤销刚才的 `git add`**:
|
||
```bash
|
||
git reset
|
||
```
|
||
|
||
---
|
||
|
||
## 🌟 结语
|
||
|
||
> **代码是 AI 写的没关系，**
|
||
>
|
||
> **但选题是你定的，需求是你理解的，取舍是你做的，结果是你交付的，成长是你自己的。**
|
||
|
||
祝大家在 **Vibe Coding** 中找到属于自己的价值！🚀
|
||
|