Skip to content

joyehuang/qq-bot

BranchesTags

Repository files navigation

QQ 打卡机器人

Version Node.js TypeScript License

一个基于 NapCat 的 QQ 群打卡机器人
帮助群成员记录和追踪学习、运动等活动时长

功能特性

核心功能

功能 描述
打卡记录 支持多种时长格式（分钟、小时、天等），支持为他人打卡
贷款打卡 预支未来打卡时长，产生负债，通过正常打卡自动抵消
撤销打卡 撤销今日最后一条打卡记录
打卡统计 查看个人打卡历史和累计时间，含 AI 分析
周报 查看本周打卡数据和 AI 总结

AI 智能功能

功能 描述
智能分类 自动识别打卡内容的分类（学习、工作、运动、娱乐、其他），支持二级细分
AI 风格 6 种回复风格：温柔鼓励、严厉激励、搞笑吐槽、专业分析、中二羞辱、循循善诱的导师
智能分析 基于打卡历史的个性化洞察和建议

社交功能

功能 描述
排行榜 今日/本周/总排行榜，支持多种排行维度
群统计 查看群整体打卡数据和趋势
成就系统 10 种可解锁成就，涵盖打卡时长、连续天数等
群头衔 自动为排行榜前列和成就解锁者设置专属头衔

自动功能

功能 描述
打卡督促 每日定时提醒管理员打卡
断签提醒 双重提醒机制，帮助连续打卡用户避免断签
GitHub 集成 查看今日代码提交数量

个性化

功能 描述
每日目标 设置打卡目标，显示进度条
连续打卡 自动追踪连续打卡天数和历史最高记录
AI 互动 智能识别身份询问、打招呼等对话

技术栈

机器人主程序

技术 说明
运行时 Node.js 18+ + TypeScript 5.0+
QQ 协议 NapCat (OneBot 11)
数据库 SQLite + Prisma ORM
通信 WebSocket
AI SiliconFlow API (Qwen)
部署 Docker Compose

管理后台

技术 说明
后端 Express.js + TypeScript
前端 Vue 3 + TypeScript + Element Plus
状态管理 Pinia
图表 ECharts
认证 JWT
部署 Docker + Nginx

快速开始

Docker 部署（推荐）

  1. 克隆项目并配置环境变量
git clone https://github.com/joyehuang/qq-bot.git
cd qq-bot
cp .env.example .env
# 编辑 .env 文件填入配置
  1. 启动服务
docker compose up -d
  1. 扫码登录 NapCat（首次启动）

本地开发

  1. 安装依赖
npm install
  1. 配置环境变量（创建 .env 文件）
# 核心配置
DATABASE_URL="file:./dev.db"
ADMIN_QQ="你的QQ号"
BOT_QQ="机器人QQ号"

# 打卡督促配置
REMINDER_GROUP_ID="群号"
REMINDER_HOUR="19"
REMINDER_MINUTE="0"
REMINDER_TIMEZONE="Asia/Shanghai"

# 断签提醒配置
STREAK_WARNING_HOUR="21"
STREAK_TAUNT_HOUR="9"

# GitHub 配置（可选）
GITHUB_USERNAME="你的GitHub用户名"
GITHUB_TOKEN="ghp_xxxx"

# AI 配置（可选，用于个性化分析）
AI_API_KEY="your-siliconflow-api-key"
AI_MODEL="Qwen/Qwen2.5-7B-Instruct"

# 群头衔配置（可选）
TITLE_GROUP_ID="群号"
DEBT_THRESHOLD="300"

# 管理后台配置
ADMIN_USERNAME="admin"
ADMIN_PASSWORD="your-secure-password"
JWT_SECRET="your-jwt-secret-key"
ADMIN_API_PORT="3001"
  1. 初始化数据库
npx prisma migrate dev
  1. 启动机器人
npx ts-node src/index.ts

使用方法

命令调用方式

在群里 @机器人 后发送命令，私聊可直接发送。

支持的 @ 方式：

  • QQ 原生 @（从成员列表选择）
  • 手动输入 @JoyeBot、@joye、@打卡 等

常用命令速查

打卡相关

命令 说明 示例
我想打卡 / 注册 新人注册 我想打卡
打卡 [时长] [内容] 记录打卡 打卡 30分钟 学习TypeScript
@某人 打卡 [时长] [内容] 为他人打卡 @小明 打卡 1小时 帮忙学习
打卡 贷款 [时长] [内容] 贷款打卡 打卡 贷款 1小时 学习
撤销打卡 / 撤销 撤销今日最后一条 撤销打卡
打卡记录 / 我的打卡 查看统计（含 AI 分析） 打卡记录
查看打卡 @某人 查看他人打卡 查看打卡 @小明
周报 / 本周报告 查看本周报告 周报
负债 / 我的负债 查看贷款负债 负债

个性化设置

命令 说明 示例
设置目标 [时长] 设置每日目标 设置目标 2小时
设置目标 清除 清除每日目标 设置目标 清除
风格列表 查看所有 AI 风格 风格列表
设置风格 [风格ID] 设置 AI 回复风格 设置风格 strict

可用 AI 风格：

风格ID 风格名称 描述
encourage 温柔鼓励型 正能量满满，给予温暖的鼓励（默认）
strict 严厉激励型 严格要求，激发斗志
funny 搞笑吐槽型 轻松幽默，带点调侃
professional 专业分析型 客观理性，数据导向
ridicule 中二羞辱型 恶趣味激将，适合重口味
teacher 循循善诱的导师 像一位耐心的老师，引导你理解知识背后的原理

排行榜

命令 说明
今日排行 / 日榜 今日打卡排行榜
本周排行 / 周榜 本周打卡排行榜
总排行 / 总榜 总打卡排行榜
群统计 / 群数据 查看群整体数据

其他功能

命令 说明
成就 / 我的成就 查看已解锁和未解锁的成就
github / 代码 查看今日 GitHub 提交
建议 [内容] 提交功能建议
帮助 / help 查看帮助信息
ping 测试机器人

管理员命令

命令 说明
闭嘴 / 关机 暂停机器人响应
开机 / 唤醒 恢复机器人响应
管理员列表 查看所有管理员

超级管理员命令

命令 说明
测试模式 / test 切换测试模式（打卡不保存）
添加管理 [QQ] 添加新管理员
删除管理 [QQ] 删除管理员
督促 / 测试督促 手动触发打卡督促
发布更新 [内容] 发送版本更新通知

学习系统命令

命令 说明
/study-join / 我想学习 加入 MiniMind 学习计划（快捷指令）
/study minimind join 加入学习计划
/study minimind status 查看学习进度
/study minimind checkin [内容] 学习打卡
/study minimind reminder [on/off] 开关学习提醒
/study minimind leave 退出学习计划

学习系统特性：

  • 📚 结构化学习路径：模块化学习，清晰的任务分解
  • ⏰ 定时督促：每天 19:00 自动发送学习提醒
  • 👨‍🏫 Teacher 风格：循循善诱，引导你理解知识背后的原理
  • 📊 进度追踪：模块级别的学习进度管理
  • 💡 个性化建议：根据学习进度提供定制化学习建议

支持的时长格式

类型 格式示例
分钟 30分钟、45m、30分、60min
小时 1小时、2h、1.5时、3hr
复合 1小时30分钟、2h30m
天数 1天、2d
秒数 3600秒、1800s（自动转分钟）
纯数字 30（默认为分钟）

AI 智能分类

机器人会 自动分析 每次打卡内容，无需手动添加标签！

分类体系：

  • 学习 → 计算机（算法、前端、后端、数据库等）/ 英语（听力、口语、词汇等）/ 其他学习
  • 工作 → 项目开发、文档、会议
  • 运动 → 跑步、健身、球类等
  • 娱乐 → 游戏、追剧、社交
  • 其他 → 其他活动

智能识别示例：

打卡 2小时 刷 leetcode  → 【学习·计算机·算法】
打卡 1小时 背雅思单词   → 【学习·英语·词汇】
打卡 30分钟 跑步       → 【运动】
打卡 1小时 写项目代码   → 【工作】

成就系统

成就 名称 条件
🎯 初来乍到 完成首次打卡
🔥 小试牛刀 连续打卡 3 天
💪 持之以恒 连续打卡 7 天
🏆 打卡狂人 连续打卡 30 天
⭐ 崭露头角 累计打卡 1 小时
🌟 初具规模 累计打卡 10 小时
💎 百炼成钢 累计打卡 100 小时
✨ 信用良好 还清所有贷款负债
🌅 早起鸟儿 早上 6-8 点打卡
🌙 夜猫子 晚上 22-24 点打卡

项目结构

qq-bot/
├── src/
│   └── index.ts          # 机器人主程序
├── admin/                # 管理后台
│   ├── server/           # 后端 API (Express + TypeScript)
│   │   ├── src/
│   │   ├── Dockerfile
│   │   └── package.json
│   └── web/              # 前端界面 (Vue 3 + TypeScript)
│       ├── src/
│       ├── Dockerfile
│       ├── nginx.conf
│       └── package.json
├── prisma/
│   ├── schema.prisma     # 数据库模型
│   └── migrations/       # 数据库迁移
├── napcat/
│   └── config/           # NapCat 配置
├── docker-compose.yml    # Docker 配置
├── deploy-qqbot.sh       # Bot 部署脚本
├── deploy-admin.sh       # 管理后台部署脚本
├── COMMANDS.md           # 完整指令文档
├── CLAUDE.md             # 开发规范
└── README.md             # 项目说明

数据库模型

模型 描述
User 用户信息（QQ号、昵称、连续天数、目标、AI风格等）
Checkin 打卡记录（时长、内容、分类、是否贷款等）
Achievement 用户成就（成就解锁记录）
Suggestion 功能建议（用户反馈建议）
StudyProject 学习项目（如 MiniMind）
StudyPlan 用户学习计划（进度追踪）
StudyCheckpoint 学习打卡记录（模块级别）

管理后台

功能特性

功能 描述
数据概览 总用户数、总打卡数、总时长、今日活跃等统计
打卡趋势 可视化打卡趋势图表（日/周/月）
分类统计 打卡分类占比饼图
排行榜 本周打卡排行榜
打卡记录管理 查看、搜索、筛选、删除打卡记录，支持导出 CSV
用户管理 查看用户列表和详情，包括打卡统计和成就
暗黑模式 支持明/暗主题切换
响应式设计 支持移动端访问

开发环境

  1. 启动后端 API（端口 3001）
cd admin/server
npm install
npm run dev
  1. 启动前端（端口 5173/5174）
cd admin/web
npm install
npm run dev
  1. 访问 http://localhost:5173

登录凭据：

  • 用户名：admin
  • 密码：见 .env 文件中的 ADMIN_PASSWORD

Docker 部署

docker compose up -d --build admin-api admin-web

访问地址：

API 文档

端点 方法 描述
/api/auth/login POST 用户登录
/api/auth/verify POST 验证 Token
/api/checkins GET 获取打卡记录列表
/api/checkins/:id GET 获取单条打卡记录
/api/checkins/:id DELETE 删除打卡记录
/api/checkins/export/csv GET 导出 CSV
/api/users GET 获取用户列表
/api/users/:id GET 获取用户详情
/api/users/:id/checkins GET 获取用户打卡记录
/api/stats/overview GET 获取概览统计
/api/stats/trend GET 获取趋势数据
/api/stats/category GET 获取分类统计
/api/stats/leaderboard GET 获取排行榜

详见 ADMIN_DEV_PLAN.md

自动功能

打卡督促

机器人会在每天指定时间检查超级管理员是否已打卡，如未打卡则在群里 @提醒。

  • 默认时间：北京时间 19:00
  • 可通过环境变量自定义时间和时区

断签提醒

双重提醒机制，只对连续打卡 ≥5 天 的用户生效：

  1. 断签警告（避免断签）

    • 每天晚上 21:00（可配置）
    • 检查连续打卡 ≥5 天但今天还没打卡的用户
    • @提醒避免断签

  2. 断签调侃（已经断了）

    • 每天早上 9:00（可配置）
    • 检查连续打卡 ≥5 天但昨天断签的用户
    • @调侃已经断签的用户

学习督促

针对参与学习项目的用户，每天 19:00 自动发送学习提醒（与通用打卡督促并行）：

  • ⏰ 每天固定时间发送学习提醒
  • 📖 显示当前学习模块和任务
  • 👨‍🏫 Teacher 风格的循循善诱
  • 💡 根据学习进度提供个性化建议
  • 🔔 支持开启/关闭提醒

群头衔系统

自动为用户设置专属头衔（机器人需要是群管理员）：

头衔 获得条件 保持时间
今日第一🥇 当天打卡时长第一名 每次打卡后更新
周榜第一🥇 本周打卡时长第一名 每天 0 点更新
周榜第二🥈 本周打卡时长第二名 每天 0 点更新
周榜第三🥉 本周打卡时长第三名 每天 0 点更新
打卡老赖💸 贷款负债超过 5 小时 还清负债后清除
成就头衔 解锁对应成就时 24 小时后自动清除

详细文档

License

MIT

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

v1.1.0 - AI风格系统与群头衔系统 Latest
Nov 27, 2025
+ 1 release

Packages

 
 
 

Contributors 2

  •  
  •  

Languages