Yunzai-Bot AI 聊天插件

🤖 基于 OpenAI API 协议的 Yunzai-Bot AI 对话插件

📖 目录

简介
主要特性
技术栈
安装说明
配置说明
使用指南
功能特性详解
API 文档
最佳实践
常见问题
开发指南
贡献指南
许可证
致谢

🌟 简介

Yunzai-Bot AI 聊天插件是一款为 Yunzai-Bot 设计的智能对话插件，基于 OpenAI API 协议，支持多种大语言模型。它能够为 QQ 群聊提供智能的 AI 对话服务，支持图片识别、记忆系统、个性化人格等高级功能。

核心功能

💬 智能对话：基于 OpenAI API 的自然语言对话
🖼️ 视觉识别：支持图片理解和多模态对话
🧠 记忆系统：基于 ChromaDB 的长期记忆存储和检索
🎭 多个人格：支持为不同群聊配置不同的 AI 人格
🎯 智能回复：可配置的回复概率、冷却时间、时间段控制
🛡️ 安全控制：内容过滤、速率限制、用户白名单/黑名单
📊 性能优化：请求队列、错误重试、资源监控
🔧 可视化管理：完整的锅巴后台管理界面

应用场景

QQ 群聊智能助手
24 小时在线的群聊伙伴
多语言翻译助手
编程技术支持
生活技巧分享
心理咨询陪伴

✨ 主要特性

1. 多模型支持

✅ 支持 OpenAI API 协议的所有模型（GPT-3.5/4、Claude 等）
✅ 多模型配置管理，可快速切换
✅ 模型健康检查自动监控
✅ 自定义 API 端点支持

2. 提示词模板系统

✅ 12 种预置人格模板（友好助手、严谨老师、幽默伙伴等）
✅ 自定义提示词创建和管理
✅ 分类管理和标签搜索
✅ 一键导入导出模板

3. MemPalace 记忆集成

✅ 基于 ChromaDB 的向量数据库
✅ 语义搜索和智能检索
✅ 群聊记忆完全隔离
✅ 自动清理过期记忆
✅ 4 种记忆类型（对话/偏好/事实/上下文）

4. 智能回复控制

✅ 可配置回复概率（0-100%）
✅ @触发 100% 响应
✅ 回复冷却时间控制
✅ 时间段调度（Cron 表达式支持）
✅ 用户白名单/黑名单

5. 视觉能力

✅ 图片理解和描述
✅ 多图片批量处理
✅ 图片缓存和去重
✅ 图片质量可配置

6. 性能优化

✅ 请求队列管理（优先级调度）
✅ 指数退避重试机制
✅ 资源监控和告警
✅ 速率限制保护

7. 安全特性

✅ 敏感内容过滤
✅ 配置加密存储
✅ 操作日志审计
✅ 配置备份恢复

🛠 技术栈

类别	技术	说明
运行时	Node.js >= 18.0.0	JavaScript 运行时
Bot 框架	Yunzai-Bot	QQ 机器人框架
后台管理	锅巴 (Guoba)	Yunzai 插件管理面板
AI API	OpenAI API	大语言模型接口
向量数据库	ChromaDB	记忆存储和检索
嵌入模型	Xenova Transformers	本地文本嵌入
工具库	Lodash	JavaScript 工具库
加密	Crypto-JS	配置加密
HTTP	Axios	HTTP 客户端
定时任务	Node-Schedule	定时任务调度

📦 安装说明

前置要求

在开始安装之前，请确保满足以下要求：

要求	版本	说明
Node.js	>= 18.0.0	推荐使用 LTS 版本
Yunzai-Bot	最新版	QQ 机器人框架
锅巴插件	已安装	用于后台管理
API 密钥	-	OpenAI 或兼容 API 提供商

安装步骤

1. 克隆插件

# 进入 Yunzai-Bot 根目录
cd /path/to/Yunzai-Bot

# 克隆插件到 plugins 目录
git clone https://github.com/yunzai-bot/yunzai-ai-chat.git plugins/yunzai-ai-chat

2. 安装依赖

# 进入插件目录
cd plugins/yunzai-ai-chat

# 安装 npm 依赖
npm install

3. 首次使用配置

方式一：锅巴后台配置（推荐）

启动 Yunzai-Bot
打开锅巴后台管理界面
在插件列表中找到 "AI 聊天"
点击进入配置页面
填写 API 密钥和配置
点击保存

方式二：配置文件

# 复制默认配置文件
cp config/default.js config/custom.js

# 编辑配置文件
nano config/custom.js

修改以下关键配置：

export const defaultConfig = {
  api: {
    apiKey: 'sk-your-api-key-here', // 替换为你的 API 密钥
    baseURL: 'https://api.openai.com/v1', // 或自定义 API 地址
    model: 'gpt-3.5-turbo' // 默认模型
  },
  reply: {
    enable: true,
    replyProbability: 0.3,
    atTrigger: true
  }
}

验证安装

安装完成后，可以通过以下方式验证：

检查依赖：npm list 应显示所有依赖已安装
测试连接：在锅巴后台点击「测试连接」按钮
群聊测试：在 QQ 群中发送消息测试回复

⚙️ 配置说明

完整配置项总览

配置模块	配置项	类型	默认值	说明
API 配置
	`api.apiKey`	string	-	API 密钥（必填）
	`api.baseURL`	string	`https://api.openai.com/v1`	API 基础地址
	`api.model`	string	`gpt-3.5-turbo`	默认模型
	`api.timeout`	number	`30000`	超时时间（毫秒）
	`api.maxRetries`	number	`3`	最大重试次数
	`api.temperature`	number	`0.7`	温度值（0-2）
	`api.maxTokens`	number	`2048`	最大 Token 数
回复控制
	`reply.enable`	boolean	`true`	启用回复
	`reply.replyProbability`	number	`0.3`	回复概率（0-1）
	`reply.contextSize`	number	`10`	上下文大小
	`reply.atTrigger`	boolean	`true`	@触发
	`reply.cooldown`	number	`5000`	冷却时间（毫秒）
	`reply.timeRange.enable`	boolean	`false`	启用时间段
	`reply.timeRange.start`	string	`08:00`	开始时间
	`reply.timeRange.end`	string	`23:00`	结束时间
	`reply.userWhitelist`	array	`[]`	白名单用户
	`reply.userBlacklist`	array	`[]`	黑名单用户
视觉能力
	`vision.enable`	boolean	`false`	启用视觉
	`vision.maxImageSize`	number	`10485760`	最大图片大小（字节）
	`vision.maxImagesPerMessage`	number	`4`	最多图片数
	`vision.imageCache`	boolean	`true`	图片缓存
	`vision.maxCacheSize`	number	`100`	最大缓存数
	`vision.imageQuality`	string	`auto`	图片质量
记忆系统
	`memory.enable`	boolean	`true`	启用记忆
	`memory.provider`	string	`chromadb`	存储提供者
	`memory.maxMemorySize`	number	`100`	最大记忆数
	`memory.collectionName`	string	`yunzai_ai_chat`	集合名称
安全配置
	`security.enableFilter`	boolean	`true`	内容过滤
	`security.blockedWords`	array	`[]`	屏蔽词列表
	`security.maxMessageLength`	number	`2000`	最大消息长度

API 配置详解

密钥配置

api: {
  apiKey: 'sk-your-api-key-here'
}

说明：

OpenAI API 密钥，用于认证 API 请求
可从 OpenAI Dashboard 获取
支持兼容 API（如 Azure OpenAI、本地部署等）

自定义 API 地址

api: {
  baseURL: 'https://your-custom-api.com/v1'
}

常见 API 地址：

提供商	API 地址	说明
OpenAI	`https://api.openai.com/v1`	官方 API
Azure	`https://your-resource.openai.azure.com/openai/deployments/{deployment-id}`	Azure OpenAI
本地部署	`http://localhost:11434/v1`	Ollama 等本地服务

模型配置

api: {
  model: 'gpt-3.5-turbo' // 或 'gpt-4', 'claude-3', 等
}

推荐模型：

模型	适用场景	成本
`gpt-3.5-turbo`	日常对话、快速响应	低
`gpt-4`	复杂推理、高质量回复	高
`gpt-4-turbo`	平衡性能和成本	中

回复控制配置

回复概率

reply: {
  replyProbability: 0.3 // 30% 概率回复
}

推荐设置：

群聊规模	推荐概率	说明
大型群聊（>100 人）	0.1-0.3	避免刷屏
中型群聊（20-100 人）	0.3-0.5	平衡活跃度
小型群聊（<20 人）	0.5-0.8	提高互动性

时间段控制

reply: {
  timeRange: {
    enable: true,
    start: '08:00',
    end: '23:00'
  }
}

说明：仅在指定时间段内回复，避免深夜打扰。

冷却时间

reply: {
  cooldown: 5000 // 5 秒冷却
}

说明：两次回复之间的最小间隔，防止消息轰炸。

视觉能力配置

vision: {
  enable: true,
  maxImageSize: 10485760, // 10MB
  maxImagesPerMessage: 4,
  imageCache: true,
  maxCacheSize: 100,
  imageQuality: 'auto'
}

图片质量说明：

质量	Token 消耗	适用场景
`low`	~85 tokens/张	快速识别、低成本
`high`	~765+ tokens/张	详细分析、高精度
`auto`	自动选择	默认推荐

记忆系统配置

memory: {
  enable: true,
  provider: 'chromadb',
  maxMemorySize: 100,
  autoClean: {
    enable: true,
    interval: 3600000, // 1 小时
    cleanExpired: true,
    cleanExcess: true
  },
  embedding: {
    provider: 'local',
    local: {
      modelName: 'Xenova/all-MiniLM-L6-v2'
    }
  }
}

记忆类型：

类型	说明	默认最大数量
`conversations`	对话记录	100
`preferences`	用户偏好	50
`important_facts`	重要事实	50
`context`	上下文信息	100

安全配置

security: {
  enableFilter: true,
  blockedWords: ['敏感词 1', '敏感词 2'],
  maxMessageLength: 2000
}

说明：

启用内容过滤可屏蔽敏感内容
屏蔽词列表支持自定义
消息长度限制防止超长回复

📖 使用指南

基础使用示例

1. 简单对话

在 QQ 群中发送消息，AI 会根据配置的概率回复：

你：今天天气真好
AI: 是啊，好天气让人心情愉悦！有什么出行计划吗？

2. @AI 触发

@机器人会 100% 触发回复：

你：@机器人 你是谁？
AI: 我是 Yunzai-Bot 的 AI 聊天插件，基于大语言模型的智能助手~

3. 图片识别

发送图片（需启用视觉能力）：

[图片：一只可爱的小猫]
AI: 好可爱的小猫！它看起来很有精神，是你养的吗？

锅巴后台配置教程

步骤 1：访问后台

启动 Yunzai-Bot
打开浏览器访问锅巴后台（通常是 http://localhost:3000）
在插件列表中找到 "AI 聊天"

步骤 2：API 配置

点击 "API 配置" 分组
填写 API 密钥
选择或输入 API 地址
选择默认模型
点击「测试连接」验证

步骤 3：回复控制

展开 "回复控制" 分组
设置回复概率（建议 0.3）
启用@触发
设置冷却时间（5000ms）
可选：设置时间段限制

步骤 4：功能开关

根据需要启用视觉能力
启用记忆系统
启用内容过滤
点击「保存配置」

多模型配置教程

添加新模型

进入「模型配置管理」模块
点击「添加模型」按钮

填写模型信息：

配置名称：GPT-4 配置
API 密钥：sk-xxx
API 地址：https://api.openai.com/v1
模型：gpt-4
启用：✓

点击保存

切换模型

在模型列表中找到目标模型
点击「切换」按钮
确认切换

群聊独立模型

进入「群聊人格配置」
添加群聊配置
选择模型配置
保存并启用

提示词模板使用

使用预置模板

进入「提示词管理」模块
浏览预置模板列表
查看模板详情
点击「设为默认」

创建自定义模板

点击「添加模板」

填写模板信息：

模板名称：我的助手
描述：个性化的 AI 助手
内容：你是一个...（详细的人格描述）
分类：助手
标签：个性化、助手

点击保存

为群聊绑定人格

进入「群聊人格配置」
添加群聊配置（填写群 ID）
人格类型选择「使用预置模板」
选择人格模板
保存并启用

记忆管理

查看记忆

进入「记忆管理」模块
选择群聊
点击「查看记忆」
浏览记忆列表和详情

搜索记忆

在搜索框输入关键词
选择记忆类型（可选）
点击搜索
查看相关记忆

清空记忆

选择要清空的群聊
点击「清空群记忆」
确认操作

🔍 功能特性详解

1. 多模型支持

支持的模型

插件支持所有兼容 OpenAI API 协议的模型：

OpenAI 系列：GPT-3.5-Turbo、GPT-4、GPT-4-Turbo
Claude 系列：Claude-3-Opus、Claude-3-Sonnet、Claude-3-Haiku
本地部署：Ollama、LocalAI 等
其他提供商：Azure OpenAI、AWS Bedrock 等

模型配置示例

models: [
  {
    id: 'gpt-3.5',
    name: 'GPT-3.5 配置',
    apiKey: 'sk-xxx',
    baseURL: 'https://api.openai.com/v1',
    model: 'gpt-3.5-turbo',
    enabled: true,
    vision: false
  },
  {
    id: 'gpt-4-vision',
    name: 'GPT-4 视觉配置',
    apiKey: 'sk-xxx',
    baseURL: 'https://api.openai.com/v1',
    model: 'gpt-4-turbo',
    enabled: true,
    vision: true
  }
]

健康检查

系统会定期执行模型健康检查：

检查 API 连接状态
测量响应时间
记录成功率
自动标记不健康模型

2. 提示词模板系统

预置模板列表

模板名称	分类	适用场景
友好助手	助手	日常交流
严谨老师	老师	学习辅导
幽默伙伴	幽默	轻松聊天
程序员助手	程序员	编程支持
创意作家	创意	文学创作
心理咨询师	助手	情感陪伴
学术研究员	老师	学术讨论
生活达人	助手	生活技巧
哲学思考者	严谨	深度思考
儿童教育者	老师	儿童教育
商务顾问	助手	商务咨询
极简主义者	通用	简洁回复

模板结构

{
  name: '友好助手',
  content: '你是一个友好、乐于助人的 AI 助手...',
  description: '适合日常交流的友好型 AI 助手人格',
  category: '助手',
  tags: ['助手', '友好', '日常'],
  enabled: true,
  isDefault: true
}

3. MemPalace 记忆集成

架构设计

Palace (ChromaDB)
├── Wing_群聊 1
│   ├── Hall_conversations (对话记忆)
│   ├── Hall_preferences (用户偏好)
│   ├── Hall_important_facts (重要事实)
│   └── Hall_context (上下文)
├── Wing_群聊 2
│   └── ...
└── ...

记忆添加

await memoryService.addMemory({
  groupId: '123456',
  content: '用户说他喜欢喝奶茶',
  hall: 'preferences',
  userId: '789012'
})

记忆检索

const memories = await memoryService.retrieveMemories({
  groupId: '123456',
  query: '用户喜欢喝什么？',
  limit: 5,
  threshold: 0.5
})

自动清理

过期清理：根据 TTL 自动清理过期记忆
超限清理：FIFO 清理超出限制的记忆
定时任务：每小时执行一次清理

4. 智能回复控制

回复决策流程

1. 检查群聊是否启用回复
2. 检查用户是否在黑名单
3. 检查用户是否在白名单（是→100% 回复）
4. 检查是否被@（是→100% 回复）
5. 检查时间段限制
6. 检查冷却时间
7. 概率判定

优先级系统

优先级	触发条件	响应率
高	@AI	100%
中	白名单用户	100%
低	普通消息	配置概率

5. 视觉能力

图片处理流程

1. 接收图片消息
2. 检查图片大小和格式
3. 计算图片哈希（去重）
4. 检查缓存（命中→跳过）
5. 转换为 Base64
6. 发送到视觉模型
7. 获取图片描述
8. 结合对话生成回复

多图片支持

vision: {
  maxImagesPerMessage: 4 // 单条消息最多处理 4 张图片
}

6. 性能优化

请求队列

优先级调度：@AI > 图片 > 普通消息
并发控制：最大并发数可配置
超时处理：不同优先级不同超时

错误重试

指数退避：1s, 2s, 4s, 8s...
最大重试：默认 3 次
错误分类：区分可重试/不可重试错误

资源监控

内存监控：heapUsed、heapTotal
请求频率：req/s 统计
队列长度：实时监控
告警系统：阈值告警

7. 安全特性

内容过滤

security: {
  enableFilter: true,
  blockedWords: ['敏感词 1', '敏感词 2'],
  maxMessageLength: 2000
}

速率限制

全局限流：100 req/min
群聊限流：50 req/min
用户限流：20 req/min

配置加密

security: {
  enableEncryption: true,
  encryptionKey: 'your-secret-key'
}

📚 API 文档

服务层 API

1. OpenAIClient

位置：services/openai-client.js

主要方法：

// 创建聊天补全
async createChatCompletion(messages, options)

// 流式聊天
async *createStreamChatCompletion(messages, options)

// 健康检查
async healthCheck(modelId)

// 测试连接
async testConnection()

// 获取模型列表
async listModels()

使用示例：

import OpenAIClient from './services/openai-client.js'

const client = new OpenAIClient({
  apiKey: 'sk-xxx',
  baseURL: 'https://api.openai.com/v1',
  model: 'gpt-3.5-turbo'
})

const response = await client.createChatCompletion([
  { role: 'user', content: '你好' }
])

2. MemoryService

位置：services/memory-service.js

主要方法：

// 初始化
async init()

// 添加记忆
async addMemory({ groupId, content, hall, userId })

// 检索记忆
async retrieveMemories({ groupId, query, hall, limit, threshold })

// 删除记忆
async deleteMemory(groupId, memoryId)

// 清空记忆
async clearGroupMemories(groupId)

// 获取统计
async getStatistics(groupId)

使用示例：

import { MemoryService } from './services/memory-service.js'

const memoryService = new MemoryService()
await memoryService.init()

// 添加记忆
await memoryService.addMemory({
  groupId: '123456',
  content: '用户喜欢喝奶茶',
  hall: 'preferences'
})

// 检索记忆
const memories = await memoryService.retrieveMemories({
  groupId: '123456',
  query: '用户喜欢喝什么？',
  limit: 5
})

3. ReplyControlService

位置：services/reply-control-service.js

主要方法：

// 检查是否应该回复
async shouldReply(e)

// 获取群聊配置
getGroupConfig(groupId)

// 更新群聊配置
updateGroupConfig(groupId, config)

// 设置回复概率
setGroupReplyProbability(groupId, probability)

// 检查白名单
isUserWhitelisted(userId)

// 检查黑名单
isUserBlacklisted(userId)

4. ContextBuilderService

位置：services/context-builder-service.js

主要方法：

// 构建上下文
async buildContext({ groupId, userId, currentMessage, images })

// 添加消息到上下文
addMessageToContext(e, role, content, options)

// 获取上下文消息
getContextMessages(groupId)

// 清空上下文
clearContext(groupId)

事件监听

消息处理流程

// 1. 消息接收
MessageHandlerService.handleMessage(e)

// 2. 回复判定
ReplyControlService.shouldReply(e)

// 3. 上下文构建
ContextBuilderService.buildContext(...)

// 4. AI 回复生成
AIResponseService.generateResponse(...)

// 5. 回复发送
ReplySenderService.sendReply(...)

冷却事件

// 记录回复
CooldownService.recordReply(groupId)

// 检查冷却
CooldownService.isOnCooldown(groupId)

// 清除冷却
CooldownService.clearCooldown(groupId)

🎯 最佳实践

配置建议

API 配置

✅ 推荐：

使用环境变量存储 API 密钥
设置合理的超时时间（30-60 秒）
启用健康检查监控模型状态
为不同用途创建多个模型配置

❌ 避免：

不要在代码中硬编码 API 密钥
不要设置过短的超时（<10 秒）
不要使用过高的温度值（>1.5）

回复控制

✅ 推荐：

大型群聊：0.1-0.3 回复概率
启用@触发确保可交互
设置 5-10 秒冷却时间
为管理员设置白名单

❌ 避免：

不要在大型群聊 100% 回复
不要设置过短冷却（<2 秒）
不要将太多用户加入白名单

记忆系统

✅ 推荐：

为活跃群聊启用记忆
定期导出记忆备份
设置合理的记忆数量限制
启用自动清理

❌ 避免：

不要在所有群聊启用记忆
不要设置过大的记忆数量（>1000）

性能调优

队列优化

requestQueue: {
  maxSize: 100,           // 根据服务器性能调整
  maxConcurrent: 3,       // CPU 密集型：2-3，IO 密集型：5-10
  timeout: 30000,         // 根据 API 响应时间调整
  priorityTimeout: {
    [HIGH]: 5000,         // @AI 消息优先
    [MEDIUM]: 10000,      // 图片消息
    [LOW]: 30000          // 普通消息
  }
}

重试优化

retry: {
  maxRetries: 3,          // 不要超过 5 次
  baseDelay: 1000,        // 1 秒基础延迟
  maxDelay: 30000,        // 最大 30 秒延迟
  backoffMultiplier: 2    // 指数退避
}

资源监控

resourceMonitor: {
  memoryThreshold: 0.8,        // 80% 内存使用告警
  requestRateThreshold: 100,   // 100 req/s 告警
  cacheSizeThreshold: 1000,    // 1000 项缓存告警
  queueLengthThreshold: 50,    // 50 个请求告警
  monitorInterval: 5000,       // 5 秒检查间隔
  alertCooldown: 60000         // 60 秒告警冷却
}

安全建议

配置安全

启用加密：

security: {
  enableEncryption: true,
  encryptionKey: crypto.randomBytes(32).toString('hex')
}

定期备份：

backup: {
  enable: true,
  maxBackups: 10,
  backupInterval: 86400000 // 每天备份
}

操作审计：
- 启用操作日志
- 定期查看日志
- 设置异常告警

速率限制

rateLimit: {
  globalLimit: 100,    // 全局限流
  groupLimit: 50,      // 群聊限流
  userLimit: 20,       // 用户限流
  windowSize: 60000    // 60 秒窗口
}

故障排查

常见问题诊断流程

1. 检查日志 → 查看错误信息
2. 测试连接 → 验证 API 配置
3. 检查配置 → 确认配置正确
4. 查看监控 → 分析性能指标
5. 排查网络 → 检查连接状态

日志级别

logging: {
  level: 'debug'  // debug < info < warn < error
}

调试技巧：

开发环境：使用 debug 级别
生产环境：使用 info 级别
问题排查：临时切换到 debug

❓ 常见问题（FAQ）

安装问题

Q1: 依赖安装失败

问题：npm install 报错

解决方案：

# 清理 npm 缓存
npm cache clean --force

# 删除 node_modules
rm -rf node_modules

# 重新安装
npm install

# 如果仍然失败，尝试使用 yarn
yarn install

Q2: ChromaDB 初始化失败

问题：记忆服务无法启动

解决方案：

检查 ChromaDB 是否正确安装
确保 ./data/chromadb 目录可写
检查 Node.js 版本（>=18）
尝试重装 ChromaDB：npm rebuild chromadb

配置问题

Q3: API 连接失败

问题：测试连接失败

解决方案：

检查 API 密钥是否正确
验证 API 地址是否正确
检查网络连接
查看防火墙设置
尝试更换 API 提供商

Q4: 配置不生效

问题：修改配置后没有效果

解决方案：

确认已点击「保存配置」
检查配置验证是否通过
重启 Yunzai-Bot
查看操作日志确认配置已保存

使用问题

Q5: AI 不回复消息

问题：发送消息后没有回复

排查步骤：

检查回复开关是否启用
查看回复概率设置
检查用户是否在黑名单
查看冷却时间是否未到
检查时间段限制
查看 Bot 日志

Q6: 回复速度很慢

问题：AI 回复延迟高

解决方案：

检查 API 响应时间
查看队列是否积压
增加并发处理数
降低温度值（减少生成时间）
使用更快的模型

性能问题

Q7: 内存占用过高

问题：内存使用持续增长

解决方案：

减少上下文大小
降低记忆数量限制
减少图片缓存大小
启用自动清理
定期重启 Bot

Q8: 请求积压严重

问题：队列长度持续增长

解决方案：

增加 maxConcurrent
减少 timeout
检查 API 调用性能
查看失败请求比例
启用速率限制

👨‍💻 开发指南

项目结构

plugins/yunzai-ai-chat/
├── config/                  # 配置文件
│   ├── default.js          # 默认配置
│   ├── default-prompts.js  # 预置提示词
│   ├── guoba.support.js    # 锅巴后台配置
│   ├── memory-config.js    # 记忆系统配置
│   └── validator.js        # 配置验证
├── models/                  # 数据模型
│   ├── index.js            # 模型导出
│   └── types.js            # 类型定义
├── services/                # 服务层
│   ├── ai-response-service.js      # AI 回复生成
│   ├── config-manager-service.js   # 配置管理
│   ├── context-builder-service.js  # 上下文构建
│   ├── memory-service.js           # 记忆管理
│   ├── openai-client.js            # OpenAI 客户端
│   ├── reply-control-service.js    # 回复控制
│   └── ... (其他服务)
├── utils/                   # 工具函数
│   ├── crypto.js           # 加密工具
│   ├── logger.js           # 日志工具
│   └── index.js            # 工具导出
├── docs/                    # 文档
│   ├── GUOBA-ADMIN.md      # 锅巴后台文档
│   ├── MEMORY-MANAGEMENT.md # 记忆系统文档
│   └── ... (其他文档)
├── index.js                 # 插件入口
└── package.json             # 依赖配置

开发环境搭建

1. 克隆项目

git clone https://github.com/yunzai-bot/yunzai-ai-chat.git
cd yunzai-ai-chat

2. 安装依赖

npm install

3. 配置开发环境

# 复制配置文件
cp config/default.js config/dev.js

# 编辑开发配置
nano config/dev.js

4. 运行测试

npm test

代码规范

命名规范

文件命名：kebab-case（如 reply-control-service.js）
类命名：PascalCase（如 MemoryService）
函数命名：camelCase（如 addMemory）
常量命名：UPPER_SNAKE_CASE（如 MAX_MEMORY_SIZE）

注释规范

/**
 * 添加记忆
 * @param {object} params - 参数
 * @param {string} params.groupId - 群 ID
 * @param {string} params.content - 记忆内容
 * @param {string} params.hall - 记忆类型
 * @returns {Promise<string>} 记忆 ID
 */
async addMemory({ groupId, content, hall }) {
  // 实现代码
}

错误处理

try {
  await someOperation()
} catch (error) {
  this.logger.error('操作失败:', error)
  throw error // 或返回错误对象
}

测试方法

单元测试

// services/memory-test.js
import { MemoryService } from './memory-service.js'

describe('MemoryService', () => {
  it('应该成功添加记忆', async () => {
    const memoryService = new MemoryService()
    await memoryService.init()
    
    const memoryId = await memoryService.addMemory({
      groupId: 'test_group',
      content: 'test content',
      hall: 'conversations'
    })
    
    expect(memoryId).toBeDefined()
  })
})

集成测试

// 测试完整流程
async function testFullFlow() {
  // 1. 初始化插件
  const plugin = getPlugin()
  await plugin.init()
  
  // 2. 模拟消息
  const mockEvent = createMockEvent('你好')
  
  // 3. 处理消息
  await plugin.handleMessage(mockEvent)
  
  // 4. 验证结果
  assert(mockEvent.replyCalled)
}

🤝 贡献指南

提交 Issue

Bug 报告

请提供以下信息：

问题描述：清晰描述问题现象
复现步骤：详细的复现步骤
环境信息：
- Node.js 版本
- Yunzai-Bot 版本
- 插件版本
日志信息：相关错误日志
预期行为：期望的正确行为

功能请求

请提供以下信息：

功能描述：详细描述功能需求
使用场景：功能的使用场景
实现建议：可选的实现建议
替代方案：已考虑的替代方案

提交 PR

开发流程

Fork 项目
```
# Fork 项目到个人仓库
```

创建分支

git checkout -b feature/your-feature-name

开发功能
- 遵循代码规范
- 编写测试用例
- 更新文档

提交代码

git add .
git commit -m "feat: 添加新功能"

推送代码

git push origin feature/your-feature-name

创建 Pull Request
- 填写 PR 描述
- 关联相关 Issue
- 等待代码审查

提交规范

Commit Message 格式：

<type>(<scope>): <subject>

<body>

<footer>

Type 类型：

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码格式调整
refactor: 代码重构
test: 测试相关
chore: 构建/工具相关

示例：

feat(memory): 添加记忆批量导出功能

- 实现批量导出记忆到 JSON
- 支持按类型过滤
- 添加导入功能

Closes #123

开发路线图

短期目标（v1.1.0）

支持流式回复
添加更多预置人格
优化记忆检索性能
支持自定义命令

中期目标（v1.2.0）

支持多模态记忆
实现记忆摘要功能
添加知识图谱
支持插件市场

长期目标（v2.0.0）

重构核心架构
支持分布式部署
实现 AAAK 压缩
完整的 API 文档

📄 许可证

本项目采用 MIT 许可证

MIT License

Copyright (c) 2026 Yunzai-Bot AIChat

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

🙏 致谢

本项目感谢以下项目和贡献者：

核心依赖

Yunzai-Bot - QQ 机器人框架
锅巴插件 - 后台管理面板
OpenAI API - 大语言模型 API
ChromaDB - 向量数据库

架构参考

MemPalace - 记忆宫殿架构
LangChain - LLM 应用框架

工具库

Lodash - JavaScript 工具库
Crypto-JS - 加密库
Axios - HTTP 客户端
Node-Schedule - 定时任务

社区贡献

感谢所有为 Yunzai-Bot 生态做出贡献的开发者和用户！

📞 联系方式

Issue 反馈：GitHub Issues
讨论区：GitHub Discussions
文档：项目 Wiki

Made with ❤️ by Yunzai-Bot Community

返回顶部

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.trae/specs/yunzai-ai-chat		.trae/specs/yunzai-ai-chat
config		config
docs		docs
models		models
services		services
utils		utils
README.md		README.md
index.js		index.js
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

Yunzai-Bot AI 聊天插件

📖 目录

🌟 简介

核心功能

应用场景

✨ 主要特性

1. 多模型支持

2. 提示词模板系统

3. MemPalace 记忆集成

4. 智能回复控制

5. 视觉能力

6. 性能优化

7. 安全特性

🛠 技术栈

📦 安装说明

前置要求

安装步骤

1. 克隆插件

2. 安装依赖

3. 首次使用配置

验证安装

⚙️ 配置说明

完整配置项总览

API 配置详解

密钥配置

自定义 API 地址

模型配置

回复控制配置

回复概率

时间段控制

冷却时间

视觉能力配置

记忆系统配置

安全配置

📖 使用指南

基础使用示例

1. 简单对话

2. @AI 触发

3. 图片识别

锅巴后台配置教程

步骤 1：访问后台

步骤 2：API 配置

步骤 3：回复控制

步骤 4：功能开关

多模型配置教程

添加新模型

切换模型

群聊独立模型

提示词模板使用

使用预置模板

创建自定义模板

为群聊绑定人格

记忆管理

查看记忆

搜索记忆

清空记忆

🔍 功能特性详解

1. 多模型支持

支持的模型

模型配置示例

健康检查

2. 提示词模板系统

预置模板列表

模板结构

3. MemPalace 记忆集成

架构设计

记忆添加

记忆检索

自动清理

4. 智能回复控制

回复决策流程

优先级系统

5. 视觉能力

图片处理流程

多图片支持

6. 性能优化