# 蛋定助手插件文档

## 项目概述

蛋定助手是一个基于 NoneBot2 框架开发的 QQ 机器人，提供多种功能插件，包括 AI 聊天、游戏辅助、积分系统、社群管理等。

## 插件总览

| 插件名称 | 描述 | 触发方式 | 权限要求 |
|---------|------|---------|---------|
| [chatai](#1-chatai---ai-聊天) | AI 聊天（DeepSeek），支持图文回复 | `*` 开头消息 | 所有用户 |
| [auto_recall](#2-auto_recall---自动撤回) | 自动撤回机器人发送的消息 | 自动执行 | 系统自动 |
| [auto_friend_accept](#3-auto_friend_accept---自动接受好友) | 自动同意好友请求并发送欢迎语 | 自动执行 | 系统自动 |
| [welcome_plugin](#4-welcome_plugin---入群欢迎) | 新成员入群欢迎并发送帮助菜单 | 自动执行 | 特定群 (621016172) |
| [danding_qqpush](#5-danding_qqpush---消息推送) | 通过 HTTP API 向指定群推送图文通知 | HTTP POST | 接口 Token 验证 |
| [danding_points](#6-danding_points---积分系统核心) | 积分系统数据库与 API 核心 | API 调用 | 系统内部 |
| [danding_points_query](#7-danding_points_query---积分查询) | 查询余额、排行及交易记录 | 命令触发 | 所有用户 |
| [group_horse_racing](#8-group_horse_racing---群赛马游戏) | 多人赛马游戏，支持下注与积分奖惩 | 命令触发 | 允许的群聊 |
| [onmyoji_gacha](#9-onmyoji_gacha---阴阳师抽卡模拟) | 阴阳师主题抽卡，包含成就与卡密奖励 | 命令触发 | 允许的群聊/用户 |
| [damo_balance](#10-damo_balance---大漠账户查询) | 查询大漠平台账户余额 | 命令触发 | 特定用户 |
| [danding_api](#11-danding_api---管理-api) | 管理员操作：卡密管理、加时、在线查询 | 命令触发 | 超级用户 |
| [danding_help](#12-danding_help---帮助菜单) | 提供教程、下载及功能指引 | 命令触发 | 特定群 (621016172) |
| [command_list](#13-command_list---指令列表) | 获取系统支持的所有指令列表 | 命令触发 | 所有用户 |

---

## 详细插件文档

### 1. chatai - AI 聊天

基于 DeepSeek AI 的聊天功能，支持将回复转换为图片形式，并在一定时间后自动撤回。

- **使用方法**: 发送以 `*` 开头的消息。
- **配置项**: `DEEPSEEK_TOKEN` (必填)。
- **特性**: AI 回复会自动转为图片显示，默认 120 秒后撤回。

### 2. auto_recall - 自动撤回

监控机器人发出的消息，并在指定时间后自动撤回，保持聊天环境整洁。

- **配置项**: 
  - `RECALL_DELAY`: 普通消息撤回延迟（默认 110s）。
  - `QQPUSH_RECALL_DELAY`: 推送消息撤回延迟（默认 3600s）。

### 3. auto_friend_accept - 自动接受好友

自动处理好友请求，提升用户接入效率。

- **配置项**: 
  - `auto_accept_enabled`: 是否开启自动接受。
  - `auto_reply_message`: 接受后的欢迎语。

### 4. welcome_plugin - 入群欢迎

针对特定群聊的新成员欢迎功能。

- **触发场景**: 新成员加入群 `621016172`。
- **功能**: 随机发送欢迎语，并附带帮助菜单图片。

### 5. danding_qqpush - 消息推送

提供外部系统向 QQ 推送通知的 HTTP 接口。

- **接口**: `POST /danding/qqpush/{token}`
- **功能**: 自动将长文本转换为图片，支持 `@用户` 和换行符 `#`。
- **配置**: `DANDING_QQPUSH_TOKEN`。

### 6. danding_points - 积分系统核心

为其他插件提供积分存储与结算的基础设施。

- **功能**: 数据库管理（SQLite）、余额增减、排行榜计算、交易日志记录。
- **数据库路径**: `data/danding_points/points.db`

### 7. danding_points_query - 积分查询

用户通过命令与积分系统交互。

- **主要命令**:
  - `我的积分`: 查看个人余额。
  - `积分查询 @用户`: 查看他人余额。
  - `积分排行`: 查看前 10 名。
  - `积分历史查询`: 查看最近 5 条变动记录。
  - `积分帮助`: 获取指令指引。

### 8. group_horse_racing - 群赛马游戏

集成积分系统的多人互动游戏。

- **主要命令**:
  - `/赛马报名 [马名]`: 参加比赛。
  - `/赛马下注 <序号> <金额>`: 对马匹下注。
  - `/赛马开赛`: 开始比赛（至少 2 人）。
- **积分逻辑**: 参赛奖励 50 分，冠军奖励 200 分，支持下注赔率结算。

### 9. onmyoji_gacha - 阴阳师抽卡模拟

高度还原的抽卡模拟，包含成就系统。

- **主要命令**:
  - `抽卡`: 执行单抽。
  - `三连抽`: 执行三连抽。
  - `我的抽卡`: 查看个人统计。
  - `查询成就`: 查看已解锁成就及进度（非酋、勤勤恳恳系列）。
  - `抽卡介绍`: 查看详细机制与奖励说明。
- **特性**: 抽中 SSR/SP 可获得“蛋定助手”卡密奖励（需联系管理员领取）。包含每日抽卡签到积分奖励。

### 10. damo_balance - 大漠账户查询

查询大漠平台账户余额。

- **命令**: `大漠余额` 或 `余额查询`。
- **限制**: 仅特定用户可用，需输入验证码。

### 11. danding_api - 管理 API

供超级用户使用的后台管理功能。

- **主要命令**:
  - `在线人数`: 查询当前活跃用户。
  - `生成卡密 <类型>`: 生成天/周/月卡。
  - `用户加时 <用户名> <类型>`: 直接为特定用户增加时长。

### 12. danding_help - 帮助菜单

系统的官方指引手册。

- **主要命令**: `帮助`、`下载`、`正式版如何运行` 等。
- **限制**: 仅在特定群 `621016172` 可用。

### 13. command_list - 指令列表

快速查阅所有可用指令。

- **命令**: `指令列表`。

---

## 常见问题 (FAQ)

- **Q: 为什么某些命令没反应？**  
  A: 部分插件（如 `danding_help`）限制了特定群聊使用；管理指令需要配置 `SUPERUSERS`。
- **Q: 积分有什么用？**  
  A: 目前主要用于赛马下注及展示排名。
- **Q: 抽卡奖励如何领取？**  
  A: 抽中 SSR/SP 或解锁特定成就后，请截屏联系管理员。