QQbot/docs/AI_QUICKSTART.md

# AI模型接入快速开始

## 🚀 快速开始

### 1. 安装依赖

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

### 2. 配置环境变量

复制 `.env.ai.example` 到 `.env` 并填入你的配置：

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

编辑 `.env` 文件：

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

# AI配置
AI_PROVIDER=openai  # 可选: openai, anthropic, deepseek, qwen
AI_MODEL=gpt-4
AI_API_KEY=你的API密钥
AI_API_BASE=https://api.openai.com/v1  # 可选
```

### 3. 启动机器人

```bash
python main.py
```

或使用启动脚本：

```bash
# Windows
start.bat

# Linux/Mac
./start.sh
```

## 📚 功能说明

### ✅ 已实现功能

1. **多模型支持**
   - OpenAI (GPT-4, GPT-3.5等)
   - Anthropic Claude
   - DeepSeek
   - Qwen (通义千问)

2. **人格系统**
   - 预设3种人格：默认助手、技术专家、创意伙伴
   - 支持自定义人格
   - 可动态切换

3. **记忆系统**
   - 短期记忆：最近20条对话，30分钟过期
   - 长期记忆：重要对话持久化存储
   - RAG检索：基于向量相似度的智能检索

4. **长任务处理**
   - 多步骤任务分解
   - 进度跟踪
   - 任务暂停/恢复/取消

5. **Skills插件系统**
   - 可扩展的技能插件
   - 示例：天气查询技能
   - 支持热加载/卸载

6. **MCP支持**
   - Model Context Protocol标准
   - 文件系统访问服务器
   - 可自定义MCP服务器

## 🎮 使用命令

在QQ中@机器人使用以下命令：

### 基础命令

- `/help` - 显示帮助信息
- `/clear` - 清除对话记忆
- `/personality` - 查看当前人格
- `/personality list` - 查看全部人格
- `/personality set <key>` - 切换人格
- `/personality add <key> <json或管道格式>` - 新增人格（角色扮演）
- `/personality remove <key>` - 删除人格

### 技能命令

- `/skills` - 查看已加载的技能
- `/skills install <source> [skill_name]` - 从本地/网络安装并加载技能
- `/skills uninstall <skill_name>` - 卸载技能
- `/skills reload <skill_name>` - 重载技能
- `/task <任务ID>` - 查看任务状态

`source` 支持：
- 本地技能名，如 `weather`
- URL（zip 包）
- GitHub 简写，如 `owner/repo` 或 `owner/repo#branch`

### 对话示例

```
用户: @机器人 你好
机器人: 你好！我是小助手，很高兴为你服务。有什么我可以帮助你的吗？

用户: @机器人 我喜欢编程
机器人: 太好了！编程是一项很有趣的技能。你主要使用什么编程语言呢？

用户: @机器人 /personality set tech_expert
机器人: ✅ 已切换到人格: tech_expert

用户: @机器人 如何优化Python性能？
机器人: 从技术角度来看，Python性能优化可以从以下几个方面入手：
1. 使用内置函数和标准库
2. 避免全局变量
3. 使用列表推导式
...
```

## 🔧 高级配置

### 自定义人格

编辑 `config/personalities.json`：

```json
{
  "my_personality": {
    "name": "我的人格",
    "description": "描述",
    "traits": ["FRIENDLY", "CREATIVE"],
    "speaking_style": "说话风格",
    "example_responses": ["示例1", "示例2"],
    "custom_instructions": "特殊指令"
  }
}
```

### 创建自定义技能

```bash
# 使用Python创建技能模板
python -c "from src.ai.skills.base import create_skill_template; from pathlib import Path; create_skill_template('my_skill', Path('skills'))"
```

然后编辑 `skills/my_skill/main.py` 实现你的技能。

### 配置MCP服务器

编辑 `config/mcp.json`：

```json
{
  "filesystem": {
    "enabled": true,
    "root_path": "data"
  }
}
```

## 📖 详细文档

查看完整文档：[src/ai/README.md](src/ai/README.md)

## 🐛 故障排查

### 问题1: AI功能不可用

**解决方案：**
1. 检查 `.env` 文件中的 `AI_API_KEY` 是否正确
2. 检查网络连接
3. 查看日志文件 `botpy.log`

### 问题2: 技能加载失败

**解决方案：**
1. 检查 `skills/技能名/skill.json` 格式是否正确
2. 确保 `main.py` 中有继承自 `Skill` 的类
3. 查看日志中的错误信息

### 问题3: 记忆系统不工作

**解决方案：**
1. 确保 `data/ai` 目录有写入权限
2. 检查是否在对话时设置了 `use_memory=True`
3. 查看 `data/ai/long_term_memory.json` 是否正常

## 🎯 最佳实践

1. **合理使用记忆**
   - 重要对话会自动保存到长期记忆
   - 定期使用 `/clear` 清理短期记忆
   - 为重要信息添加关键词（如"重要"、"记住"）

2. **人格切换**
   - 根据场景选择合适的人格
   - 技术问题用 `tech_expert`
   - 创意讨论用 `creative`
   - 日常对话用 `default`

3. **技能开发**
   - 保持技能功能单一
   - 提供清晰的工具描述
   - 处理异常情况

## 📊 性能优化

### 记忆系统优化

```python
# 调整短期记忆大小
client.memory.short_term.max_size = 30  # 默认20

# 调整重要性阈值
client.memory.importance_threshold = 0.7  # 默认0.6
```

### 模型参数调整

```python
config = ModelConfig(
    provider=ModelProvider.OPENAI,
    model_name="gpt-4",
    temperature=0.7,  # 创造性 0-2
    max_tokens=4096,  # 最大输出长度
    top_p=1.0,        # 采样参数
)
```

## 🔄 更新日志

### v1.0.0 (2024-03-02)
- ✅ 初始版本
- ✅ 支持多种AI模型
- ✅ 人格系统
- ✅ 记忆系统（短期+长期+RAG）
- ✅ 长任务处理
- ✅ Skills插件系统
- ✅ MCP支持

## 📝 示例代码

查看 `examples/ai_example.py` 获取完整示例。

## 🤝 贡献

欢迎提交Issue和Pull Request！

## 📄 许可证

MIT License