CourseDesignTemplate/README.md

# Python程序设计课程设计

## 🎯 课程概述

**课程主题**：基于 DeepSeek API + Streamlit 的 AI 应用开发

**课程理念**：

> 在 AI 时代，代码可以生成，Bug 可以修复，文档可以自动撰写——
> 
> **但判断什么值得做、为结果负责、理解用户真实需求、在约束中做取舍，这些能力永远属于你。**

本课程通过 AI 代码编辑器（如 Cursor、Windsurf）进行 **Vibe Coding**，让学生体验"用自然语言编程"的全新开发方式。但更重要的是，在这个过程中**思考人与 AI 的协作边界**，培养 AI 时代真正不可替代的能力。

**技术栈**：
- 🐍 **Python 3.14+** (2026 Stable)
- ⚡ **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)。
- **Python 3.14+**: 访问 [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.14.x
uv --version      # 应显示 uv 0.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
    ```
3.  **运行 (Run)**: 一键启动，无需担心环境冲突。
    ```bash
    uv run main.py
    ```

#### DeepSeek API 快速入门 (使用 OpenAI SDK)
```python
# 推荐使用 uv 管理依赖: uv add openai
from openai import OpenAI

# 初始化客户端
client = OpenAI(
    api_key="your-api-key",  # 建议使用环境变量
    base_url="https://api.deepseek.com"
)

# ... (代码保持不变)
```

> [!TIP]
> **进阶选择**：对于复杂的 Agent 开发，推荐使用 **PydanticAI**，它能提供更好的类型安全和结构化输出支持。

#### 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()
```

### 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("字数限制", 50, 200, 100)

# 3. 主界面输入
theme = st.text_input("你想写关于什么主题的文案？", placeholder="例如：周五下班、喝咖啡、新发型")

# 4. 按钮与 AI 调用
if st.button("🪄 生成文案"):
    if not theme:
        st.warning("请先输入主题！")
    else:
        with st.spinner("AI 正在榨干脑汁..."):
            try:
                prompt = f"请用{style}写一段关于'{theme}'的朋友圈文案，带Emoji，{length}字以内。"
                
                response = client.chat.completions.create(
                    model="deepseek-chat",
                    messages=[{"role": "user", "content": prompt}]
                )
                result = response.choices[0].message.content
                
                st.success("生成成功！")
                st.markdown(f"### 📝 结果：\n{result}")
            except Exception as e:
                st.error(f"发生错误：{e}")
```
**运行**：
```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. 准备消息历史
    # (注意：实际项目中需要维护 st.session_state 或 cl.user_session 来保留上下文，这里仅演示单轮回复)
    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
    )
    
    for chunk in stream:
        if token := chunk.choices[0].delta.content:
            await msg.stream_token(token)
    
    # 4. 完成更新
    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)
- 🤖 **DeepSeek API**：[platform.deepseek.com](https://platform.deepseek.com)
- 📺 **教程**：B站搜索 "Streamlit 入门" 或 "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. 提交材料
1. **源代码**：完整项目文件夹。
2. **README.md**：项目说明文档。
3. **依赖文件**：包含 `pyproject.toml` 和 `uv.lock` (确保别人可以用 `uv sync` 还原你的环境)。
4. **开发心得**：Markdown 格式，**不少于 500 字**。

### 2. README.md 模板
```markdown
# [项目名称]

## 简介
这句话介绍你的项目是做什么的，解决了什么问题。

## 如何运行
1. 安装依赖：`uv sync`
2. 配置 Key：复制 `.env.example` 为 `.env` 并填入 Key。
3. 运行：`uv run streamlit run app.py`

## 功能列表
- [x] 功能 A
- [ ] 功能 B (待开发)
```

### 3. 📝 开发心得（必填，>500字）

**请围绕以下核心问题撰写：**

1. **选题思考**：为什么做这个？解决了谁的痛苦？
2. **AI 协作体验**：
   - 第一次用 AI 写代码的感觉？
   - 哪个 Prompt 让你直呼"牛逼"？哪个让你想砸键盘？
   - AI 生成的 Bug 你是怎么解的？
3. **自我反思**：
   - 离开 AI，我还能写出这个吗？
   - AI 时代，我作为程序员的核心竞争力到底是什么？

> 💡 **真情实感最重要**。我们不想看套话，想看你的真实挣扎与顿悟。

---

## 🔗 附录：环境配置指南

### 1. 基础环境
- **Python**: 推荐 3.14+ (2026 Stable)
- **依赖管理**: **uv** (强烈推荐，替代 pip/venv)
- **编辑器**: 推荐 Cursor 或 VS Code + Windsurf 插件。

### 2. 项目初始化 (使用 uv)
```bash
# 1. 安装 uv (MacOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. 初始化项目
mkdir my-ai-app
cd my-ai-app
uv init

# 3. 添加依赖
uv add streamlit chainlit openai python-dotenv

# 4. 运行应用
uv run streamlit run app.py
# 或
uv run chainlit run app.py -w
```

### 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")
```

---

## 🌟 结语

> **代码是 AI 写的没关系，**
>
> **但选题是你定的，需求是你理解的，取舍是你做的，结果是你交付的，成长是你自己的。**

祝大家在 **Vibe Coding** 中找到属于自己的价值！🚀