# 💖 NPC好感度系统使用指南

## 📚 概述

赛博小镇的NPC现在拥有了**好感度系统**,能够根据与玩家的对话内容自动调整好感度,并影响后续对话的风格和态度!

---

## ✨ 核心功能

### 1. **自动情感分析**
- 🤖 使用LLM Agent分析对话情感
- 📊 判断玩家态度 (友好/中立/不友好)
- 🎯 评估对话质量 (深入/一般/敷衍)
- 💬 识别情感倾向 (赞美/批评/中性)

### 2. **好感度动态调整**
- 📈 友好对话提升好感度 (+1 到 +10)
- 📉 批评对话降低好感度 (-3 到 -15)
- 🔄 自动更新好感度值 (0-100)
- 🎚️ 限制在合理范围内

### 3. **关系等级系统**
- 🥶 **陌生** (0-20): 冷淡疏离,不太愿意多说
- 😐 **熟悉** (20-40): 礼貌但略显生疏
- 😊 **友好** (40-60): 礼貌友善,正常交流
- 🤗 **亲密** (60-80): 友好热情,愿意多聊
- 💕 **挚友** (80-100): 非常热情,像老朋友一样

### 4. **对话风格调整**
- 🎭 好感度影响NPC的对话风格
- 💬 高好感度: 更热情、更愿意分享
- 😶 低好感度: 更冷淡、回答简短
- 🔄 动态调整,实时生效

---

## 🎯 使用示例

### 示例1: 好感度提升

```
初始好感度: 50 (友好)

第一次对话:
玩家: "你好,很高兴认识你!"
张三: "你好!我也很高兴认识你。"
📈 好感度: 50 -> 55 (友好问候)

第二次对话:
玩家: "你的代码写得真棒!"
张三: "谢谢!我最近在研究新技术,你对这个感兴趣吗?"
📈 好感度: 55 -> 63 (赞美工作) → 关系等级提升: 友好 -> 亲密

第三次对话:
玩家: "能教教我吗?"
张三: "当然可以!我很乐意分享。你想从哪里开始?"
📈 好感度: 63 -> 69 (请教学习)
```

### 示例2: 好感度降低

```
当前好感度: 69 (亲密)

批评对话:
玩家: "你这个代码写得太烂了!"
张三: "抱歉,我会改进的..."
📉 好感度: 69 -> 61 (批评工作) → 关系等级降低: 亲密 -> 友好
```

### 示例3: 对话风格变化

```
好感度: 30 (熟悉)
玩家: "你好,最近怎么样?"
李四: "还行吧。" (简短回答)

好感度: 70 (亲密)
玩家: "你好,最近怎么样?"
李四: "挺好的!最近在做一个很有意思的项目,你要不要听听?" (热情详细)

好感度: 90 (挚友)
玩家: "你好,最近怎么样?"
李四: "哈哈,老朋友!最近忙得不行,但很充实。对了,上次你问的那个问题,我找到答案了!" (亲切主动)
```

---

## 🔧 技术实现

### 架构设计

```
RelationshipManager
├── affinity_scores: Dict[str, Dict[str, float]]  # NPC好感度存储
├── analyzer_agent: SimpleAgent                   # 情感分析Agent
├── get_affinity(npc_name, player_id)            # 获取好感度
├── analyze_and_update_affinity(...)             # 分析并更新好感度
├── get_affinity_level(affinity)                 # 获取关系等级
└── get_affinity_modifier(affinity)              # 获取对话风格修饰词
```

### 情感分析流程

```
1. 玩家发送消息
   ↓
2. NPC生成回复
   ↓
3. 情感分析Agent分析对话
   ├── 分析玩家态度
   ├── 评估对话内容
   ├── 判断情感倾向
   └── 计算好感度变化量
   ↓
4. 更新好感度
   ├── 当前好感度 + 变化量
   ├── 限制在0-100范围
   └── 检查等级变化
   ↓
5. 保存到记忆系统
   └── 记录好感度和情感信息
```

### 好感度变化规则

| 对话类型 | 变化量 | 示例 |
|---------|--------|------|
| 赞美、感谢、请教 | +3 到 +8 | "你真棒!" "谢谢你!" "能教教我吗?" |
| 友好问候、正常交流 | +1 到 +3 | "你好!" "最近怎么样?" |
| 普通闲聊、中性话题 | 0 | "今天天气不错" |
| 批评、质疑、不耐烦 | -3 到 -8 | "这个不太好" "真的吗?" |
| 侮辱、攻击、恶意 | -8 到 -15 | "你太烂了!" |

---

## 🚀 API接口

### 1. 获取NPC好感度

```http
GET /npcs/张三/affinity?player_id=player
```

**响应:**
```json
{
    "npc_name": "张三",
    "player_id": "player",
    "affinity": 65.0,
    "level": "亲密",
    "modifier": "友好热情,愿意多聊,会主动关心对方"
}
```

### 2. 获取所有NPC好感度

```http
GET /affinities?player_id=player
```

**响应:**
```json
{
    "player_id": "player",
    "affinities": {
        "张三": {
            "affinity": 65.0,
            "level": "亲密",
            "modifier": "友好热情,愿意多聊,会主动关心对方"
        },
        "李四": {
            "affinity": 50.0,
            "level": "友好",
            "modifier": "礼貌友善,正常交流,保持专业"
        },
        "王五": {
            "affinity": 72.0,
            "level": "亲密",
            "modifier": "友好热情,愿意多聊,会主动关心对方"
        }
    }
}
```

### 3. 设置NPC好感度 (测试用)

```http
PUT /npcs/张三/affinity?affinity=80&player_id=player
```

**响应:**
```json
{
    "message": "已设置张三对玩家的好感度",
    "npc_name": "张三",
    "player_id": "player",
    "affinity": 80.0,
    "level": "挚友",
    "modifier": "非常热情友好,像老朋友一样亲切,愿意分享私人话题"
}
```

---

## 🧪 测试方法

### 方法1: 使用测试脚本

```bash
cd backend
python test_affinity.py
```

**测试内容:**
- ✅ 基本好感度功能
- ✅ 好感度提升/降低
- ✅ 关系等级变化
- ✅ 对话风格调整
- ✅ 好感度渐进提升

### 方法2: 使用API测试

1. 启动后端服务:
```bash
cd backend
python main.py
```

2. 访问API文档: http://localhost:8000/docs

3. 测试好感度接口:
   - 对话: POST /chat
   - 查看好感度: GET /npcs/张三/affinity
   - 查看所有好感度: GET /affinities

---

## 📊 好感度系统配置

### 情感分析提示词

情感分析Agent使用精心设计的提示词来分析对话:

```python
【分析维度】
1. 玩家态度: 友好/中立/不友好
2. 对话内容: 积极/中立/消极
3. 互动质量: 深入/一般/敷衍
4. 情感倾向: 赞美/批评/中性

【输出格式】
{
    "should_change": true/false,
    "change_amount": -15到+10之间的整数,
    "reason": "简短说明原因",
    "sentiment": "positive/neutral/negative"
}
```

### 调整建议

如果想调整好感度变化的敏感度,可以修改 `relationship_manager.py` 中的提示词:

- **更敏感**: 增加变化量范围 (例如: -20 到 +15)
- **更保守**: 减少变化量范围 (例如: -5 到 +5)
- **更细腻**: 添加更多分析维度
- **更简单**: 简化分析规则

---

## 🎓 教学价值

### 学习要点

1. **LLM情感分析**
   - 如何使用LLM分析对话情感
   - 如何设计情感分析提示词
   - 如何解析LLM的JSON响应

2. **好感度系统设计**
   - 如何设计好感度变化规则
   - 如何实现关系等级系统
   - 如何将好感度与对话风格关联

3. **系统集成**
   - 如何将好感度系统集成到Agent
   - 如何与记忆系统协同工作
   - 如何通过API暴露功能

4. **用户体验设计**
   - 如何让NPC更有人情味
   - 如何提升对话的连贯性
   - 如何增强游戏的沉浸感

---

## 🔍 调试技巧

### 1. 查看好感度变化日志

```python
# 在agents.py的chat方法中
📈 张三对玩家的好感度: 50.0 -> 55.0 (友好问候)
🎉 关系等级提升: 友好 -> 亲密
```

### 2. 检查情感分析结果

```python
# 在relationship_manager.py中添加调试输出
print(f"情感分析结果: {analysis}")
```

### 3. 测试不同对话类型

```python
# 使用test_affinity.py测试不同类型的对话
friendly_messages = ["你好!", "你真棒!", "能教教我吗?"]
critical_messages = ["这个不好", "你太烂了"]
neutral_messages = ["今天天气不错", "嗯"]
```

---

## ❓ 常见问题

### Q1: 好感度为什么没有变化?

**可能原因:**
- 对话内容过于中性
- 情感分析Agent判断为不需要改变
- LLM响应解析失败

**解决方法:**
- 使用更明确的情感表达
- 检查日志中的情感分析结果
- 调整情感分析提示词

### Q2: 好感度变化太快/太慢?

**解决方法:**
- 修改 `relationship_manager.py` 中的变化量范围
- 调整情感分析提示词中的规则
- 使用 `set_npc_affinity` 手动设置初始值

### Q3: 对话风格没有明显变化?

**可能原因:**
- 好感度差异不够大
- NPC的system_prompt没有充分利用好感度修饰词

**解决方法:**
- 增大好感度差异 (例如: 20 vs 80)
- 在system_prompt中强调对话风格的重要性

---

## 🎉 总结

✅ NPC好感度系统已成功集成到赛博小镇!

**核心特性:**
- 🤖 自动情感分析
- 📊 动态好感度调整
- 🎚️ 关系等级系统
- 💬 对话风格调整
- 💾 与记忆系统集成

**教学价值:**
- LLM情感分析的实战应用
- 好感度系统的设计与实现
- 多系统协同工作
- 用户体验优化

**下一步:**
- 在Godot中显示好感度UI
- 添加好感度相关的游戏机制
- 优化情感分析算法

---

**作者:** HelloAgents团队  
**日期:** 2024-01-15  
**版本:** v1.0