QQbot/docs/CHANGELOG.md

# 更新说明 - v1.0.1

## 🔄 本次更新内容

### 1. ✅ 统一配置管理

**问题**：之前AI配置分散在多个文件中  
**解决**：所有配置现在统一在 `.env` 文件中管理

**更新的文件**：
- `.env.example` - 添加了完整的AI配置项
- `src/core/config.py` - 添加了AI嵌入模型配置
- 删除了 `.env.ai.example`（已合并到 `.env.example`）

### 2. ✅ 文档结构优化

**问题**：文档散落在项目根目录  
**解决**：所有文档移动到对应的 `docs` 目录

**新的文档结构**：
```
docs/
├── README.md              # 文档索引（新增）
├── CONFIG_GUIDE.md        # 配置指南（新增）
├── AI_QUICKSTART.md       # 快速开始
├── AI_IMPLEMENTATION.md   # 实现总结
└── AI_SUMMARY.md          # 功能总结

src/ai/docs/
└── README.md              # 完整文档

skills/docs/
└── (技能相关文档)
```

### 3. ✅ RAG嵌入模型配置

**问题**：RAG功能需要嵌入模型，但没有配置选项  
**解决**：添加了独立的嵌入模型配置

**新增配置项**：
```env
# AI嵌入模型配置（用于RAG记忆检索）
AI_EMBED_PROVIDER=openai
AI_EMBED_MODEL=text-embedding-3-small
AI_EMBED_API_KEY=  # 留空则使用 AI_API_KEY
AI_EMBED_API_BASE=  # 留空则使用 AI_API_BASE
```

**更新的文件**：
- `src/ai/client.py` - 支持独立的嵌入模型配置
- `src/handlers/message_handler_ai.py` - 传递嵌入模型配置

**工作原理**：
1. 如果配置了嵌入模型，优先使用独立的嵌入模型
2. 如果没有配置，尝试使用主模型的嵌入功能
3. 如果主模型不支持（如Claude），RAG功能降级为基于重要性的检索

## 📝 配置示例

### 完整配置（推荐）

```env
# QQ机器人配置
BOT_APPID=你的机器人APPID
BOT_SECRET=你的机器人SECRET

# AI主模型
AI_PROVIDER=openai
AI_MODEL=gpt-4
AI_API_KEY=sk-xxx

# AI嵌入模型（用于RAG）
AI_EMBED_PROVIDER=openai
AI_EMBED_MODEL=text-embedding-3-small
AI_EMBED_API_KEY=  # 留空使用主模型的key
```

### 使用Claude + OpenAI嵌入

```env
# 主模型（Claude）
AI_PROVIDER=anthropic
AI_MODEL=claude-3-5-sonnet-20241022
AI_API_KEY=sk-ant-xxx

# 嵌入模型（OpenAI）
AI_EMBED_PROVIDER=openai
AI_EMBED_MODEL=text-embedding-3-small
AI_EMBED_API_KEY=sk-xxx  # 需要单独的OpenAI key
```

### 最简配置（不使用RAG）

```env
# 只配置主模型
AI_PROVIDER=openai
AI_MODEL=gpt-4
AI_API_KEY=sk-xxx

# 不配置嵌入模型，RAG功能会降级
```

## 🚀 如何更新

### 1. 更新配置文件

```bash
# 备份现有配置
cp .env .env.backup

# 查看新的配置模板
cat .env.example

# 手动添加嵌入模型配置到 .env
```

在 `.env` 文件中添加：
```env
# AI嵌入模型配置（用于RAG记忆检索）
AI_EMBED_PROVIDER=openai
AI_EMBED_MODEL=text-embedding-3-small
AI_EMBED_API_KEY=
AI_EMBED_API_BASE=
```

### 2. 查看新文档

```bash
# 查看文档索引
cat docs/README.md

# 查看配置指南
cat docs/CONFIG_GUIDE.md
```

### 3. 重启机器人

```bash
python main.py
```

查看日志确认配置成功：
```
✅ AI配置: openai/gpt-4
✅ 嵌入模型初始化: openai/text-embedding-3-small
✅ AI客户端初始化完成: openai/gpt-4
```

## 📚 文档导航

- **配置说明**：`docs/CONFIG_GUIDE.md` ⭐ 重要！
- **快速开始**：`docs/AI_QUICKSTART.md`
- **完整文档**：`src/ai/docs/README.md`
- **文档索引**：`docs/README.md`

## ⚠️ 注意事项

1. **嵌入模型是可选的**
   - 如果不配置，系统会尝试使用主模型的嵌入功能
   - 如果主模型不支持，RAG功能会降级但不影响基本使用

2. **Claude用户需要额外配置**
   - Claude不提供嵌入API
   - 建议配置OpenAI的嵌入模型作为补充

3. **配置文件位置**
   - 所有配置都在 `.env` 文件中
   - 不再需要 `.env.ai.example`

## 🐛 问题排查

### 问题1: 找不到嵌入模型配置

**解决**：检查 `.env` 文件是否包含 `AI_EMBED_*` 配置项

### 问题2: RAG功能不工作

**解决**：
1. 检查是否配置了嵌入模型
2. 查看日志是否有 "嵌入模型初始化" 的提示
3. 如果没有配置，RAG会降级为基于重要性的检索

### 问题3: 文档找不到了

**解决**：文档已移动到 `docs/` 目录，查看 `docs/README.md` 获取索引

## 📊 版本对比

| 功能 | v1.0.0 | v1.0.1 |
|------|--------|--------|
| 配置文件 | 分散 | 统一在.env |
| 文档位置 | 根目录 | docs目录 |
| RAG嵌入模型 | 未配置 | 可配置 |
| 配置指南 | 无 | 新增 |

## 🎉 总结

本次更新主要解决了三个问题：
1. ✅ 配置统一管理
2. ✅ 文档结构优化
3. ✅ RAG嵌入模型支持

所有功能保持向后兼容，现有配置无需修改即可继续使用！

---

**更新时间**：2024-03-02  
**版本**：v1.0.1  
**上一版本**：v1.0.0