Skip to content

Orange20000922/RobotDev

BranchesTags

Repository files navigation

RobotDev - QQ 机器人

一个基于 Spring Boot 和 Shiro 框架的 QQ 机器人项目，支持命令系统和 AI 对话功能。

📋 项目信息

  • 框架: Spring Boot 3.5.7 + Shiro 2.4.7
  • 语言: Java 17
  • 构建工具: Maven
  • AI 集成: OpenAI API

🚀 快速开始

1. 克隆项目

git clone <your-repo-url>
cd RobotDev

2. 配置环境变量

复制 .env.example 为 .env 并填写配置：

cp .env.example .env

编辑 .env 文件：

OPENAI_API_KEY=your-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MAX_RETRIES=3

3. 运行项目

# 使用 Maven
mvn spring-boot:run

# 或直接运行 JAR
mvn clean package
java -jar target/RobotDev-0.0.1-SNAPSHOT.war

📖 命令系统

已实现的命令

命令 别名 说明 示例
/help h, ? 显示帮助信息 /help echo
/echo say 回显消息 /echo Hello World
/ping p 测试机器人响应 /ping
/status stat, info 显示机器人状态 /status
/ai ask, gpt AI 对话 /ai 你好
/clear reset, new 清空 AI 对话历史 /clear

命令使用示例

# 查看所有命令
/help

# 查看特定命令的帮助
/help echo

# 回显消息
/echo 你好，世界！

# 测试响应
/ping

# 查看状态
/status

# AI 对话
/ai 你好，请介绍一下你自己
/ai 帮我写一个 Python 快速排序
/ai 解释什么是递归

# 清空 AI 对话历史
/clear

🤖 AI 对话功能

快速开始

  1. 配置 API Key

    # 在 .env 文件中设置
OPENAI_API_KEY=sk-xxxxxxxxxxxxx

  2. 开始对话

    /ai 你好
/ai 今天天气怎么样？
/ai 帮我写一个 Python 的冒泡排序

  3. 多轮对话

    用户: /ai 我叫小明
AI: 你好小明！

用户: /ai 我刚才说我叫什么？
AI: 你叫小明。

特性

  • ✅ 上下文记忆 - AI 会记住对话历史
  • ✅ 独立会话 - 每个用户有独立的对话空间
  • ✅ 自动清理 - 30分钟不活动自动清理会话
  • ✅ 可配置 - 支持自定义 AI 人设、模型等

详细说明请查看 AI_CHAT_GUIDE.md

🏗️ 命令系统架构

核心组件

command/
├── Command.java           # 命令接口
├── CommandContext.java    # 命令执行上下文
├── CommandResult.java     # 命令执行结果
├── CommandRegistry.java   # 命令注册中心
├── CommandParser.java     # 命令解析器
├── CommandManager.java    # 命令管理器
└── impl/
    ├── HelpCommand.java   # 帮助命令
    ├── EchoCommand.java   # 回显命令
    ├── PingCommand.java   # Ping 命令
    └── StatusCommand.java # 状态命令

如何添加新命令

  1. 创建命令类

在 command/impl/ 目录下创建新的命令类：

package com.example.robotdev.command.impl;

import com.example.robotdev.command.*;
import org.springframework.stereotype.Component;
import java.util.List;

@Component
public class MyCommand implements Command {

    @Override
    public String getName() {
        return "mycommand";
    }

    @Override
    public List<String> getAliases() {
        return List.of("mc");
    }

    @Override
    public String getDescription() {
        return "我的自定义命令";
    }

    @Override
    public String getUsage() {
        return "/mycommand <参数>";
    }

    @Override
    public CommandResult execute(CommandContext context) {
        // 实现命令逻辑
        return CommandResult.success("执行成功");
    }
}
  1. 自动注册

Spring 会自动扫描并注册所有带 @Component 注解的命令类。

  1. 测试命令

启动项目后，直接使用 /mycommand 即可。

🔧 配置说明

application.yml

server:
  port: 8080

# OpenAI 配置
openai:
  api-key: ${OPENAI_API_KEY:}
  base-url: ${OPENAI_BASE_URL:https://api.openai.com/v1}
  max-retries: ${OPENAI_MAX_RETRIES:3}

# Shiro 配置
shiro:
  ws:
    server:
      enable: true
      url: "/xm"
  plugin-list: com.example.robotdev.TestPlugin

环境变量

变量名 说明 默认值
OPENAI_API_KEY OpenAI API 密钥 无
OPENAI_BASE_URL API 基础 URL https://api.openai.com/v1
OPENAI_MAX_RETRIES 最大重试次数 3

📚 项目结构

RobotDev/
├── src/main/java/com/example/robotdev/
│   ├── RobotDevApplication.java      # 主启动类
│   ├── TestPlugin.java               # 机器人插件
│   ├── command/                      # 命令系统
│   │   ├── Command.java              # 命令接口
│   │   ├── CommandContext.java       # 上下文
│   │   ├── CommandResult.java        # 结果
│   │   ├── CommandRegistry.java      # 注册中心
│   │   ├── CommandParser.java        # 解析器
│   │   ├── CommandManager.java       # 管理器
│   │   └── impl/                     # 命令实现
│   │       ├── HelpCommand.java
│   │       ├── EchoCommand.java
│   │       ├── PingCommand.java
│   │       ├── StatusCommand.java
│   │       ├── AICommand.java        # AI 对话命令
│   │       └── ClearCommand.java     # 清空对话命令
│   ├── ai/                           # AI 对话系统
│   │   ├── AIChatService.java        # AI 对话服务
│   │   ├── AIChatProperties.java     # AI 配置
│   │   ├── ChatSession.java          # 对话会话
│   │   └── ChatSessionManager.java   # 会话管理器
│   └── config/                       # 配置类
│       ├── OpenAIConfig.java
│       └── OpenAIProperties.java
├── src/main/resources/
│   └── application.yml               # 应用配置
├── .env.example                      # 环境变量示例
├── .gitignore                        # Git 忽略文件
├── pom.xml                           # Maven 配置
├── README.md                         # 本文件
└── AI_CHAT_GUIDE.md                  # AI 对话使用指南

🔐 安全配置

敏感信息管理

  • ✅ 使用环境变量存储 API Key
  • ✅ .env 文件已添加到 .gitignore
  • ✅ 提供 .env.example 作为示例
  • ⚠️ 永远不要将 API Key 提交到版本控制

权限系统

命令接口提供了 hasPermission() 方法，可以自定义权限检查：

@Override
public boolean hasPermission(CommandContext context) {
    // 自定义权限检查逻辑
    return context.getUserId().equals(adminUserId);
}

🧪 测试

# 运行所有测试
mvn test

# 运行特定测试
mvn test -Dtest=CommandParserTest

🔧 常见问题

1. PostConstruct 注解报错

错误信息：

Cannot resolve symbol 'PostConstruct'

原因：Spring Boot 3.x 使用 jakarta.* 而不是 javax.*

解决：

// ❌ 错误
import javax.annotation.PostConstruct;

// ✅ 正确
import jakarta.annotation.PostConstruct;

详细说明请查看 SPRING_BOOT_3_MIGRATION.md

2. OpenAI API Key 未配置

错误信息：

OpenAI client is not configured. AI features will be disabled.

解决：设置环境变量 OPENAI_API_KEY

3. 命令不响应

检查事项：

  • 命令是否以 / 开头
  • 机器人是否有管理员权限（如果需要）
  • 查看日志输出确认命令是否被识别

📝 TODO

  • 添加基本命令（help, echo, ping, status）
  • 实现 AI 对话功能
  • 添加用户权限系统
  • 添加命令冷却时间
  • 添加命令使用统计
  • 添加更多实用命令（天气、翻译、计算器等）
  • 完善单元测试

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 许可证

本项目仅用于学习和研究目的。

🎉 更新日志

v0.2.0 (2026-01-01)

新增功能:

  • ✅ AI 对话功能
    • 支持上下文记忆
    • 独立用户会话
    • 自动会话清理
    • 可自定义 AI 人设
  • ✅ 新命令
    • /ai - AI 对话
    • /clear - 清空对话历史

改进:

  • ✅ 启用定时任务支持
  • ✅ 完善配置系统
  • ✅ 新增 AI 对话使用指南

v0.1.0 (2026-01-01)

  • ✅ 重构命令系统
  • ✅ 实现基本命令（help, echo, ping, status）
  • ✅ 集成 OpenAI API
  • ✅ 使用环境变量管理敏感配置
  • ✅ 完善项目文档

最后更新: 2026-01-01

About

一个基于NapCat和Spring Boot的QQ机器人。

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages