QQbot/docs/AI_QUICKSTART.md

AI模型接入快速开始

🚀 快速开始

1. 安装依赖

pip install -r requirements-ai.txt

2. 配置环境变量

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

cp .env.ai.example .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. 启动机器人

python main.py

或使用启动脚本：

# 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：

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

创建自定义技能

# 使用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：

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

📖 详细文档

查看完整文档：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. 技能开发

   • 保持技能功能单一
   • 提供清晰的工具描述
   • 处理异常情况

📊 性能优化

记忆系统优化

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

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

模型参数调整

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