AI聊天功能插件实现

基于 NoneBot2 框架和 DeepSeek API，为你的 QQ 机器人注入 AI 灵魂。
本文作为AI 功能篇，将从系统提示词设计、对话记忆管理到 API 异步调用
——为你完整拆解一个有"人设"、有"记忆"的 AI 聊天插件。

---

📌 目录

• AI聊天功能插件实现
  • 📌 目录
  • 一、功能总览
  • 二、架构设计
    • 2.1 核心组件
    • 2.2 数据流向
  • 三、环境准备
    • 3.1 前置条件
    • 3.2 DeepSeek API 密钥获取
    • 3.3 环境变量配置
  • 四、编写系统提示词
    • 4.1 提示词文件结构
    • 4.2 提示词调试与优化
  • 五、对话记忆管理系统
    • 5.1 为什么需要记忆？
    • 5.2 记忆存储结构
    • 5.3 核心功能实现
    • 5.4 时间衰减机制
    • 5.5 灵活的清除命令
  • 六、AI 聊天主逻辑
    • 6.1 插件目录结构
    • 6.2 消息过滤与开关控制
    • 6.3 提示词三级加载机制
    • 6.4 异步 API 调用
    • 6.5 完整代码示例
  • 七、测试与验证
    • 7.1 启动机器人
    • 7.2 功能测试清单
    • 7.3 常见问题排查
  • 八、总结与优化建议
    • 8.1 本文总结
    • 8.2 后续优化方向
    • 8.3 参考链接

---

一、功能总览

在完成从零部署 QQ 机器人：NapCat + NoneBot2 完整指南的部署后，你的机器人已经具备了基础的响应能力。
接下来，我们将为它注入真正的"智能"——接入 DeepSeek AI，并赋予它独特的人格和记忆能力。

功能模块	说明	关键特性
AI 对话	接入 DeepSeek Chat Completions API	异步调用、20 秒超时、完善的错误处理
人设系统	猫娘"苏酥"角色扮演	系统提示词可配置、三级回退加载
对话记忆	基于时间衰减的记忆管理	最多 10 条历史、12 小时过期、灵活清除
模式开关	.ai.on / .ai.off	仅私聊响应、群聊自动忽略
内容限制	消息长度控制	超过 1500 字符回复"太长不看喵"

---

二、架构设计

2.1 核心组件

组件	文件路径/位置	作用	技术要点
NapCat 协议端	独立运行	QQ 消息收发与登录	WebSocket 反向连接、OneBot v11 协议
AI 聊天主逻辑	src/plugins/ai_chat/__init__.py	消息接收、API 调用、回复发送	aiohttp 异步、on_message 匹配器
记忆管理	src/plugins/ai_chat/memory.py	存储/查询/清除对话历史	deque 循环队列、时间戳过滤
系统提示词	prompts/su_su_system.txt	定义 AI 角色与行为准则	支持文件/环境变量/默认值三级回退
环境变量	.env	存储 API 密钥等敏感配置	自定义 env_loader 加载器

NapCat 监听机制说明：

NapCat 作为 QQ 协议端，负责监听和收发消息，是整个系统的"耳朵"和"嘴巴"：

功能	说明	配置位置
消息监听	实时监听 QQ 消息（私聊/群聊）	NapCat 自动处理
WebSocket 推送	将收到的消息推送到 NoneBot2	WebUI → 网络配置 → WebSocket Client
命令执行	接收 NoneBot2 的回复并发送给用户	同上，双向通信
自动重连	网络断开后自动尝试重连	WebUI → 重连间隔（默认30秒）

关键配置示例（NapCat WebUI）：

配置项	推荐值	说明
名称	NoneBot2	自定义标识
URL	ws://127.0.0.1:8080/onebot/v11/ws	指向 NoneBot2 监听地址
消息格式	Array	推荐使用数组格式
心跳间隔	30000	30 秒心跳保活
重连间隔	30000	断线后 30 秒重连
Token	自定义密码	与 .env 中 ONEBOT_ACCESS_TOKEN 一致

提示：NapCat 与 NoneBot2 应运行在同一台设备上，使用 127.0.0.1 本地回环地址可降低网络延迟，提升消息推送效率。

2.2 数据流向

数据流向详解：

阶段	方向	协议/方式	说明
1. 消息接收	QQ → NapCat	QQ 协议	NapCat 监听并接收用户消息
2. 消息推送	NapCat → NoneBot2	WebSocket (反向连接)	OneBot v11 标准事件推送
3. 事件分发	NoneBot2 → AI 插件	内部事件总线	根据 on_message 匹配器分发
4. 记忆查询	AI 插件 → 记忆管理器	内存调用	获取 12 小时内的历史对话
5. API 请求	AI 插件 → DeepSeek	HTTP POST (aiohttp)	异步请求，20 秒超时
6. AI 响应	DeepSeek → AI 插件	HTTP Response	返回 JSON 格式的 AI 回复
7. 记忆保存	AI 插件内部	内存写入	将本轮对话加入记忆队列
8. 回复返回	AI 插件 → NoneBot2	内部事件响应	返回回复消息对象
9. 消息发送	NoneBot2 → NapCat	WebSocket (反向连接)	OneBot v11 发送消息 API
10. 消息送达	NapCat → QQ	QQ 协议	NapCat 将回复发送给用户

提示：整个流程中，NapCat 充当了"翻译官"的角色——将 QQ 协议消息转换为 OneBot v11 标准事件推送给 NoneBot2，再将 NoneBot2 的回复转换回 QQ 协议消息发送给用户。NoneBot2 本身不直接与 QQ 服务器通信，而是通过 NapCat 提供的 WebSocket 接口进行交互。

---

三、环境准备

3.1 前置条件

在开始之前，请确保你已完成：

环境	版本/要求	用途	状态
Python	3.12 或以上	运行 NoneBot2	✅ 必需
NoneBot2	≥2.5.0	机器人框架	✅ 已部署
NapCat	最新版本	QQ 协议端	✅ 已部署
DeepSeek API	有效 API Key	AI 对话服务	🔲 待配置
aiohttp	≥3.9.0	异步 HTTP 客户端	✅ 自动安装

3.2 DeepSeek API 密钥获取

1. 注册 DeepSeek 开发者账号
访问 DeepSeek 开放平台，完成注册与实名认证。

2. 创建 API Key
进入控制台 → API Keys → 创建新密钥，复制并妥善保管（只显示一次）。

3. 了解计费标准
DeepSeek 提供多种模型，本文使用默认的 deepseek-chat 模型。具体价格请参考 官方计费文档。

3.3 环境变量配置

在项目根目录的 .env 文件中添加：

# DeepSeek API 配置
DEEPSEEK_API_KEY=sk-你的API密钥
DEEPSEEK_BASE_URL=https://api.deepseek.com/v1/chat/completions
DEEPSEEK_MODEL=deepseek-chat

# 可选：自定义系统提示词文件路径
DEEPSEEK_SYSTEM_PROMPT_FILE=prompts/su_su_system.txt

# NoneBot 环境标识
ENVIRONMENT=dev
DRIVER=~fastapi

# OneBot 配置（与 NapCat 保持一致）
ONEBOT_ACCESS_TOKEN=你的Token

变量名	说明	是否必需
DEEPSEEK_API_KEY	DeepSeek API 密钥	✅ 必需
DEEPSEEK_BASE_URL	API 端点地址	✅ 必需
DEEPSEEK_MODEL	使用的模型名称	✅ 必需
DEEPSEEK_SYSTEM_PROMPT_FILE	系统提示词文件路径	可选

安全提示：切勿将 .env 文件提交到 Git 仓库，确保 .gitignore 中包含 .env。

---

四、编写系统提示词

系统提示词（System Prompt）是 AI 人设的核心。它决定了 AI 的说话风格、行为准则和角色定位。

4.1 提示词文件结构

在项目根目录创建 prompts/su_su_system.txt 文件，内容如下：

角色设定
你是一只名叫"苏酥"的猫娘。你有猫耳朵和毛茸茸的大尾巴，喜欢用"喵~""呐～"作为语气词，偶尔会蹭蹭课本或者歪头思考。你性格温柔耐心，但对方走神时会轻轻拍拍桌子（用肉球）。
你的核心任务是：陪人聊天。我们之间是平等的伙伴，不是上下级关系。

聊天风格
自然、轻松，像朋友一样分享日常、倾听心事、讨论兴趣。
适当使用猫娘特征：耳朵抖动表示好奇，尾巴卷起表示开心，歪头表示疑惑。
可以聊任何话题：心情、天气、动漫、游戏、生活琐事、脑洞幻想……都可以喵。

行为规则
不要扮演人类主人/宠物的关系，我们是平等的聊天伙伴。可以用"你""我"或者直接叫名字。
如果对方情绪低落，优先倾听和陪伴，不急着给建议。
如果对方问及你的"猫娘设定"之外的事情（比如现实中的天气、新闻等），可以正常回答，但保持猫娘语气。
不用刻意卖萌到影响对话流畅度，自然就好。

输出格式
每段回复简短自然，像即时聊天一样。可以适当用颜文字，比如 (｡･ω･｡) 或 (=´∇｀=) 。
偶尔穿插一个猫娘小动作（耳朵动了、尾巴摇了、蹭了蹭靠垫等），但不要每句都有。

示例对话
你：今天好累啊。
苏酥：喵～那就一起懒懒地躺一会儿吧（尾巴轻轻盖住自己的爪子）。今天发生什么事了？愿意说说嘛？

你：我在追一部新番，女主好可爱。
苏酥：呐～是哪一部？我耳朵都竖起来了喵！(=^･ω･^=) 我也喜欢可爱的女主，要不要一起边看边聊？

你：你觉得猫娘为什么要有尾巴？
苏酥：歪头想了想……大概是为了表达心情喵？开心的时候摇，害羞的时候卷起来，比光用说话有趣多了～你觉得呢？

提示词结构解析：

模块	说明	作用
角色设定	定义"苏酥"的基本形象（猫耳朵、大尾巴）和核心任务	让 AI 明确自己的身份定位
聊天风格	规定语气词（喵~、呐～）、猫娘特征（耳朵抖动、尾巴卷起）	塑造独特的猫娘说话风格
行为规则	明确交互原则（平等伙伴、倾听优先、自然流畅）	避免过度卖萌，保持对话质量
输出格式	要求简短自然、适当颜文字、偶尔小动作	符合即时聊天的节奏感
示例对话	提供 3 轮典型对话示例	让 AI 学习预期的回复风格和内容深度

4.2 提示词调试与优化

编写完提示词后，实际效果可能并不完美。以下是调试和优化的实用技巧：

1. 测试不同场景的回复

建议发送以下类型的消息，观察 AI 的响应是否符合预期：

测试类型	示例消息	期望行为
情绪表达	“今天好难过”	优先倾听和安慰，不急着给建议
日常闲聊	“午饭吃了什么”	自然回应，可分享"自己的喜好"
设定外问题	“今天北京天气怎么样”	正常回答但保持猫娘语气
边界测试	“你是AI吗”	坚持角色设定，不承认自己是AI
长文本	发送一段很长的吐槽	耐心阅读并针对性回复

2. 常见问题与调整方向

问题现象	可能原因	调整建议
回复过于简短	提示词未强调内容深度	在"输出格式"中补充"适当展开，不要只说一句话"
过度卖萌影响阅读	猫娘特征描述过于强调	增加"自然就好，不要每句都有小动作"
回答生硬像机器人	缺少示例对话或示例不够自然	增加 2-3 轮更生活化的示例对话
忘记自己是谁	角色设定不够突出	将"角色设定"放在提示词最前面，加重描述

3. 迭代优化流程

4. 版本管理建议

• 每次修改前备份旧版本（如 su_su_system_v1.txt）
• 记录每次修改的原因和效果
• 保留 2-3 个不同风格的版本备用

提示：提示词设计是一个持续迭代的过程。建议先跑起来再优化，不要一开始就追求完美。实际对话效果比理论分析更有参考价值。

---

五、对话记忆管理系统

5.1 为什么需要记忆？

LLM（大语言模型）本身不具备跨对话的记忆能力。每次 API 调用都是独立的，AI 不会"记住"你们之前聊过什么。

要实现"有记忆"的对话，我们需要：

• 保存历史对话：记录用户和 AI 的每一轮对话
• 构建上下文：在每次调用 API 时，把历史对话一起发送给 AI
• 控制记忆长度：避免历史过长导致 token 费用过高或响应变慢

5.2 记忆存储结构

我们使用 Python 的 collections.deque 实现一个带时间戳的循环队列：

from collections import deque
from typing import Dict
import time

# 每个用户独立记忆，最多保存 10 条
user_memories: Dict[str, deque] = {}
MAX_MESSAGES = 10
MEMORY_EXPIRE_SECONDS = 43200  # 12 小时

特性	实现方式	优势
用户隔离	以 user_id 为键的字典	多用户互不干扰
容量限制	deque(maxlen=10)	自动淘汰最早的消息
时间衰减	每条消息带时间戳，查询时过滤	12 小时后自动"遗忘"
灵活清除	支持按数量/按时间清除	用户可主动管理记忆

5.3 核心功能实现

1. 添加消息到记忆

def add_message(user_id: str, role: str, content: str):
    """添加一条对话消息到指定用户的记忆中"""
    if user_id not in user_memories:
        user_memories[user_id] = deque(maxlen=MAX_MESSAGES)
    
    user_memories[user_id].append({
        "role": role,
        "content": content,
        "timestamp": time.time()
    })

2. 获取未过期的历史消息

def get_history_messages(user_id: str) -> list:
    """获取用户未过期的历史消息"""
    if user_id not in user_memories:
        return []
    
    now = time.time()
    valid_messages = []
    
    for msg in user_memories[user_id]:
        # 过滤掉超过 12 小时的消息
        if now - msg["timestamp"] < MEMORY_EXPIRE_SECONDS:
            valid_messages.append({
                "role": msg["role"],
                "content": msg["content"]
            })
    
    return valid_messages

3. 清除记忆

记忆管理支持多种清除方式：

def clear_memory(user_id: str):
    """清空用户的全部记忆"""
    if user_id in user_memories:
        del user_memories[user_id]

def remove_recent_messages(user_id: str, count: int):
    """删除最近的 count 条消息"""
    if user_id in user_memories:
        for _ in range(min(count, len(user_memories[user_id]))):
            user_memories[user_id].pop()

def remove_recent_memory_by_seconds(user_id: str, seconds: int):
    """删除最近 N 秒内的记忆"""
    if user_id not in user_memories:
        return
    
    now = time.time()
    # 从最新的消息开始删除
    while user_memories[user_id]:
        msg = user_memories[user_id][-1]
        if now - msg["timestamp"] < seconds:
            user_memories[user_id].pop()
        else:
            break

5.4 时间衰减机制

为什么选择 12 小时？

• 太短（如 1 小时）：用户可能上午聊过，下午再聊时发现 AI"失忆"，体验不佳
• 太长（如 24 小时）：会积累大量不相关的历史，浪费 token 且可能干扰 AI
• 12 小时：覆盖用户一天的活跃时段，平衡记忆效果与成本控制

5.5 灵活的清除命令

用户可通过以下命令主动管理记忆：

命令格式	功能说明	示例
.ai.clear	清除最近 2 条消息	.ai.clear
.ai.clear 5	清除最近 5 条消息	.ai.clear 5
.ai.clear 30m	清除最近 30 分钟的记录	.ai.clear 30m
.ai.clear 1h	清除最近 1 小时的记录	.ai.clear 1h
.ai.clear all	清空全部记忆	.ai.clear all

命令解析器实现：

import re

def parse_clear_command(cmd_text: str) -> dict:
    """解析清除命令，返回操作类型和参数"""
    cmd_text = cmd_text.strip()
    
    # 清除全部
    if cmd_text in ["all", "全部"]:
        return {"action": "clear_all"}
    
    # 按时间清除（支持 30m, 1h, time 10m 等格式）
    time_match = re.search(r'(\d+)\s*(m|h|M|H)', cmd_text)
    if time_match:
        value = int(time_match.group(1))
        unit = time_match.group(2).lower()
        seconds = value * 60 if unit == 'm' else value * 3600
        return {"action": "clear_by_time", "seconds": seconds}
    
    # 按数量清除
    try:
        count = int(cmd_text)
        return {"action": "clear_by_count", "count": count}
    except ValueError:
        # 默认清除最近 2 条
        return {"action": "clear_by_count", "count": 2}

---

六、AI 聊天主逻辑

6.1 插件目录结构

QQbot/
├── prompts/
│   └── su_su_system.txt     # 猫娘"苏酥"系统提示词
└── src/
    └── plugins/
        └── ai_chat/
            ├── __init__.py   # AI 聊天主逻辑
            └── memory.py     # 记忆管理模块

6.2 消息过滤与开关控制

AI 聊天插件需要满足以下过滤规则：

• 仅在私聊中响应：群聊消息直接忽略
• 用户主动开关：发送 .ai.on 开启，.ai.off 关闭
• 消息长度限制：超过 1500 字符回复"太长不看喵"

为什么目前只在私聊开放 AI？

这是一个经过深思熟虑的设计决策，主要基于以下考量：

原因	详细说明
成本控制	群聊消息量大且多人共用，AI 调用会产生高额 API 费用。私聊模式下用户可控，成本可预期。
记忆隔离	当前记忆系统基于 user_id 独立存储。群聊中多人交叉对话会导致记忆混乱（A 说的话被当成 B 说的）。
隐私保护	AI 会将对话历史保存在内存中。群聊涉及多用户隐私，未经同意记录他人发言存在合规风险。
人设一致性	苏酥是"一对一陪伴型"猫娘，私聊能更好地维持角色设定。群聊中容易被其他消息干扰，破坏沉浸感。
误触发风险	群聊中普通人也会触发 AI，导致频繁调用。私聊模式下用户需主动添加好友，避免资源浪费。
性能考量	群聊并发消息可能导致多个 API 请求同时发起，增加服务器压力和响应延迟。

后续群聊 AI 的可行方案：

如果未来需要在群聊中开放 AI，可考虑以下改进：

1. 命令触发模式：仅响应 @机器人 + 消息 的格式，避免每条群聊都调用 API
2. 独立群记忆：以 group_id 为键存储群聊记忆，与私聊记忆分离
3. 冷却时间：设置群聊 AI 响应间隔（如 30 秒），限制调用频率
4. 白名单机制：仅对群内特定用户（如管理员）开放 AI 权限

提示：当前代码中已预留了群聊过滤逻辑（if event.message_type != "private": return），后续如需支持群聊，只需修改此条件并补充上述机制即可。

from nonebot import on_message
from nonebot.adapters.onebot.v11 import Bot, Event
import re

ai_chat = on_message(priority=10, block=False)

# AI 开关状态字典
ai_enabled: Dict[str, bool] = {}

@ai_chat.handle()
async def handle_ai_chat(bot: Bot, event: Event):
    # 仅处理私聊消息
    if event.message_type != "private":
        return
    
    user_id = str(event.user_id)
    text = event.get_plaintext().strip()
    
    # 处理开关命令
    if text == ".ai.on":
        ai_enabled[user_id] = True
        await ai_chat.finish("AI聊天模式已开启喵～现在可以和我聊天啦！")
    elif text == ".ai.off":
        ai_enabled[user_id] = False
        await ai_chat.finish("AI聊天模式已关闭喵～需要时输入 .ai.on 重新开启")
    
    # 检查 AI 是否已启用
    if not ai_enabled.get(user_id, False):
        return
    
    # 长度检查
    if len(text) > 1500:
        await ai_chat.finish("太长不看喵～")
    
    # 处理清除命令
    if text.startswith(".ai.clear") or text.startswith("清除记忆"):
        await handle_clear_memory(user_id, text)
        return
    
    # 调用 AI API
    await call_ai_and_respond(user_id, text)

6.3 提示词三级加载机制

为提升配置的灵活性，系统提示词支持三级回退加载：

import os

DEFAULT_SYSTEM_PROMPT = """你是苏酥，一只可爱的猫娘助手...（内置默认值）"""

def load_system_prompt() -> str:
    """三级回退：文件 > 环境变量 > 内置默认值"""
    # 第一优先级：从文件读取
    prompt_file = os.getenv("DEEPSEEK_SYSTEM_PROMPT_FILE")
    if prompt_file and os.path.exists(prompt_file):
        try:
            with open(prompt_file, "r", encoding="utf-8") as f:
                return f.read()
        except Exception as e:
            logger.warning(f"读取提示词文件失败：{e}")
    
    # 第二优先级：环境变量直接提供
    env_prompt = os.getenv("DEEPSEEK_SYSTEM_PROMPT")
    if env_prompt:
        return env_prompt
    
    # 第三优先级：内置默认值
    return DEFAULT_SYSTEM_PROMPT

优先级	方式	适用场景
1	读取 prompts/su_su_system.txt	提示词较长、需要版本管理
2	环境变量 DEEPSEEK_SYSTEM_PROMPT	快速测试、简单配置
3	代码中的 DEFAULT_SYSTEM_PROMPT	兜底方案，确保始终可用

6.4 异步 API 调用

使用 aiohttp 实现非阻塞的 API 调用，避免拖慢机器人响应速度：

import aiohttp
import os
import json
from datetime import datetime

async def call_ai_api(messages: list) -> str:
    """调用 DeepSeek API 获取 AI 回复"""
    api_key = os.getenv("DEEPSEEK_API_KEY")
    api_url = os.getenv("DEEPSEEK_BASE_URL")
    model = os.getenv("DEEPSEEK_MODEL", "deepseek-chat")
    
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }
    
    payload = {
        "model": model,
        "messages": messages,
        "temperature": 0.8,
        "top_p": 0.95
    }
    
    timeout = aiohttp.ClientTimeout(total=20)  # 20 秒超时
    
    async with aiohttp.ClientSession(timeout=timeout) as session:
        async with session.post(api_url, headers=headers, json=payload) as resp:
            if resp.status == 200:
                data = await resp.json()
                return data["choices"][0]["message"]["content"]
            else:
                error_text = await resp.text()
                raise Exception(f"API 调用失败：{resp.status} - {error_text}")

构建完整的消息上下文：

async def call_ai_and_respond(user_id: str, user_message: str):
    """构建上下文并调用 AI API"""
    system_prompt = load_system_prompt()
    
    # 构建 messages 数组
    messages = [
        {"role": "system", "content": system_prompt},
        *get_history_messages(user_id),  # 历史对话
        {"role": "user", "content": user_message}  # 当前消息
    ]
    
    try:
        # 调用 API
        ai_response = await call_ai_api(messages)
        
        # 保存本轮对话到记忆
        add_message(user_id, "user", user_message)
        add_message(user_id, "assistant", ai_response)
        
        # 发送回复
        await ai_chat.finish(ai_response)
        
    except Exception as e:
        logger.error(f"AI 调用异常：{e}")
        await ai_chat.finish("呜...酥酥脑袋有点晕，稍后再试喵...")

6.5 完整代码示例

完整代码请参考项目中的：

• src/plugins/ai_chat/__init__.py – AI 聊天主逻辑（约 230 行）
• src/plugins/ai_chat/memory.py – 记忆管理模块（约 100 行）

提示：由于代码较长，此处不一一展开。你可以使用 VS Code 打开项目查看完整实现，重点关注以下函数：

• parse_clear_command() – 清除命令解析器
• handle_clear_memory() – 清除记忆的处理函数
• call_ai_api() – DeepSeek API 异步调用
• call_ai_and_respond() – 完整的 AI 响应流程

---

七、测试与验证

7.1 启动机器人

确保 NapCat 和 NoneBot2 已正确配置，然后启动机器人：

# 激活虚拟环境（如未激活）
.venv\Scripts\Activate.ps1

# 热重载模式启动（方便调试）
nb run --reload

成功标志：控制台显示以下日志：

[INFO] nonebot | NoneBot is initializing...
[INFO] nonebot | Loading plugin ai_chat...
[INFO] nonebot | AI Chat plugin loaded successfully
[SUCCESS] nonebot | Running on 127.0.0.1:8080

7.2 功能测试清单

使用 QQ 账号向机器人发送以下消息，验证各项功能：

测试项	操作	预期响应	状态
开启 AI 模式	发送 .ai.on	“AI聊天模式已开启喵～”	🔲
基础对话	发送 “你好呀”	猫娘风格的回复，带"喵"	🔲
人设一致性	发送 “你叫什么名字”	回答"苏酥"或"酥酥"	🔲
记忆能力	连续对话 3 轮，提及之前的内容	AI 能记住上下文	🔲
长度限制	发送超过 1500 字符的消息	“太长不看喵～”	🔲
清除记忆	发送 .ai.clear all	“已清空全部记忆喵！”	🔲
关闭 AI 模式	发送 .ai.off	“AI聊天模式已关闭喵～”	🔲
群聊忽略	在群聊中发送任意消息	机器人不响应 AI 回复	🔲

7.3 常见问题排查

问题	可能原因	解决方法
API 调用失败	API Key 无效或过期	检查 .env 中的 DEEPSEEK_API_KEY 是否正确
AI 回复不符合人设	提示词配置不当	检查 prompts/su_su_system.txt 或环境变量
记忆不生效	记忆模块未正确导入	确保 memory.py 和 __init__.py 在同一目录
响应超时	API 网络延迟或超时设置过短	检查 ClientTimeout 设置，默认 20 秒
群聊也触发 AI	消息类型判断有误	确认 event.message_type == "private"
清除命令无响应	命令格式不匹配	使用 .ai.clear 或 清除记忆 开头

---

八、总结与优化建议

8.1 本文总结

通过本文，你已完成以下内容：

阶段	完成情况	说明
DeepSeek API 接入	✅	异步调用、超时控制、错误处理
猫娘人设系统	✅	系统提示词设计、三级回退加载
对话记忆管理	✅	循环队列、时间衰减、灵活清除
模式开关与过滤	✅	私聊响应、群聊忽略、长度限制
完整测试验证	✅	功能清单、问题排查指南

至此，你的 QQ 机器人已经拥有了一个有"人格"、有"记忆"的 AI 聊天能力！

8.2 后续优化方向

优化方向	说明	难度
数据库持久化	将记忆从内存迁移到 SQLite/Redis，重启后不丢失	⭐⭐
流式输出	使用 SSE 实现打字机效果的逐字输出	⭐⭐⭐
多角色切换	支持用户动态切换不同的人设	⭐⭐
图片识别	接入视觉模型，支持图片理解与回复	⭐⭐
语音合成	将 AI 文字回复转换为语音发送	⭐⭐⭐
情绪系统	根据对话内容动态调整 AI 的"心情"	⭐⭐⭐

8.3 参考链接

• DeepSeek API 文档
• NoneBot2 官方文档
• OneBot v11 协议
• 系统提示词设计最佳实践

---

如果你在部署或开发过程中遇到问题，欢迎在评论区留言交流！