CourseDesignTemplate/示例项目-角色扮演聊天室/README.md

# 🎭 AI 角色扮演聊天室

一个基于 DeepSeek API + Streamlit 构建的角色扮演聊天应用，支持多种预设角色和自定义角色创建。

![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)
![Streamlit](https://img.shields.io/badge/Streamlit-1.28+-red.svg)
![DeepSeek](https://img.shields.io/badge/DeepSeek-API-green.svg)

## ✨ 功能特性

- 🎭 **多种预设角色**：傲娇猫娘、智慧老者、毒舌AI、科学怪人等
- ✨ **自定义角色**：创建你想象中的任何角色
- 💬 **多轮对话**：保留对话历史，角色会记住上下文
- ⚡ **流式输出**：打字机效果，实时显示 AI 回复
- 🎨 **美观界面**：精心设计的 UI，渐变色彩和动画效果

## 🖼️ 界面预览

```
┌─────────────────────────────────────────────────────────────┐
│  🎭 角色设置                │  🎭 AI 角色扮演聊天室          │
│  ─────────────              │  ─────────────────────          │
│  🔑 API 配置                │                                  │
│  [DeepSeek API Key]         │  🐱                              │
│  ─────────────              │  正在与 小喵 对话                │
│  🎭 选择角色                │                                  │
│  [🐱 傲娇猫娘      ▼]       │  ────────────────────────────    │
│                             │                                  │
│  ┌─────────────────┐        │  👤: 你好呀！                    │
│  │ 🐱 小喵          │        │                                  │
│  │ 你是一个傲娇的   │        │  🐱: 哼，才不是特意来跟你打招   │
│  │ 猫娘...         │        │      呼的呢！...喵~ (｡･ω･｡)    │
│  └─────────────────┘        │                                  │
│                             │  ────────────────────────────    │
│  [🗑️ 清空对话历史]          │  [输入你想说的话...          ]   │
└─────────────────────────────────────────────────────────────┘
```

## 🚀 快速开始

### 1. 克隆/下载项目

```bash
cd 示例项目-角色扮演聊天室
```

### 2. 创建虚拟环境（推荐）

```bash
python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate
```

### 3. 安装依赖

```bash
pip install -r requirements.txt
```

### 4. 配置 API Key

复制环境变量示例文件：

```bash
cp .env.example .env
```

编辑 `.env` 文件，填入你的 DeepSeek API Key：

```
DEEPSEEK_API_KEY=sk-your-actual-api-key
```

> 💡 **获取 API Key**：访问 [DeepSeek 开放平台](https://platform.deepseek.com)，注册账号后在控制台创建。

### 5. 运行应用

```bash
streamlit run app.py
```

应用将在浏览器中自动打开，默认地址：http://localhost:8501

## 📁 项目结构

```
示例项目-角色扮演聊天室/
├── app.py              # 主程序
├── requirements.txt    # 项目依赖
├── .env.example        # 环境变量示例
├── .env                # 环境变量（需自行创建，不要提交！）
├── .gitignore          # Git 忽略文件
└── README.md           # 项目说明
```

## 🎭 预设角色介绍

| 角色 | 名称 | 特点 |
|:---:|:---|:---|
| 🐱 | 傲娇猫娘·小喵 | 傲娇但可爱，句尾带"喵~"，会用颜文字 |
| 🧙 | 智慧老者·玄清子 | 富有哲理，喜欢引用古诗词 |
| 🤖 | 毒舌AI·犀利哥 | 说话犀利一针见血，但有建设性 |
| 👨‍🔬 | 科学怪人·Dr.Eureka | 疯狂科学家，热衷科学分析 |
| 🎮 | 游戏解说·电竞小王 | 充满激情，使用游戏术语 |
| 📚 | 文艺青年·林小诗 | 说话有诗意，会即兴创作 |

## 🛠️ 技术实现

### 核心技术点

1. **DeepSeek API 调用**
   - 使用 OpenAI SDK 兼容接口
   - 流式输出（Streaming）实现打字机效果

2. **Streamlit 组件**
   - `st.chat_message` - 聊天消息展示
   - `st.chat_input` - 聊天输入框
   - `st.session_state` - 对话历史管理
   - `st.write_stream` - 流式输出渲染

3. **角色扮演机制**
   - System Prompt 定义角色性格和说话方式
   - 多轮对话保持角色一致性

### 关键代码解析

#### 流式输出实现

```python
stream = client.chat.completions.create(
    model=MODEL,
    messages=messages_for_api,
    stream=True,  # 启用流式输出
)

response = st.write_stream(
    chunk.choices[0].delta.content or ""
    for chunk in stream
    if chunk.choices[0].delta.content
)
```

#### 对话历史管理

```python
# 初始化
if "messages" not in st.session_state:
    st.session_state.messages = []

# 添加消息
st.session_state.messages.append({"role": "user", "content": prompt})

# 构建 API 请求
messages_for_api = [
    {"role": "system", "content": system_prompt}  # 角色设定
] + st.session_state.messages  # 历史消息
```

## 🎨 自定义角色指南

创建一个好的自定义角色，需要在角色设定中包含：

1. **身份定义**：角色是谁，背景是什么
2. **性格特点**：外向/内向、温柔/严厉等
3. **说话方式**：口癖、常用词、语气
4. **对用户态度**：如何称呼用户，关系定位
5. **特殊行为**：是否使用emoji、颜文字等

### 示例：创建一个"中二少年"角色

```
你是一个中二病少年，自称"黑暗骑士·雷恩"。你的特点：
- 认为自己拥有被封印的黑暗力量
- 经常用"我的右手又在疼了..."这样的台词
- 说话夸张，喜欢用"区区凡人"称呼用户
- 会假装痛苦地按住眼睛说"黑暗之眼快要觉醒了"
- 其实很好说话，问什么都会认真回答（虽然用中二的方式）
```

## 📝 开发心得

这个项目使用 **Vibe Coding** 方式开发，主要通过自然语言描述需求，让 AI 代码编辑器生成代码。

**开发过程中的 Prompt 示例：**

> "帮我创建一个角色扮演聊天应用，使用 DeepSeek API 和 Streamlit。
> 要求：左侧边栏选择角色，支持自定义角色，聊天界面要美观，
> 使用流式输出，要保存对话历史。"

**迭代优化：**

> "给界面加上渐变色效果，让角色卡片更好看一些"

> "添加一个清空对话的按钮"

## ⚠️ 注意事项

1. **保护 API Key**：不要将 `.env` 文件提交到代码仓库
2. **控制成本**：DeepSeek API 按 Token 计费，长对话会消耗更多 Token
3. **角色设定**：过长的 System Prompt 会增加每次请求的成本

## 📚 参考资料

- [DeepSeek API 文档](https://platform.deepseek.com/api-docs)
- [Streamlit 官方文档](https://docs.streamlit.io)
- [OpenAI Python SDK](https://github.com/openai/openai-python)

## 👤 作者

Python 程序设计课程设计 - 示例项目

---

**Happy Vibe Coding! 🚀**