173 lines
8.1 KiB
Markdown
173 lines
8.1 KiB
Markdown
# 蛋定助手插件文档
|
||
|
||
## 项目概述
|
||
|
||
蛋定助手是一个基于 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---指令列表) | 获取系统支持的所有指令列表 | 命令触发 | 所有用户 |
|
||
| [danding_sign_in](#14-danding_sign_in---每日签到) | 独立每日签到，与抽卡签到共用数据 | 命令触发 | 白名单群聊/管理员 |
|
||
|
||
---
|
||
|
||
## 详细插件文档
|
||
|
||
### 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 - 阴阳师抽卡模拟
|
||
|
||
高度还原的抽卡模拟，包含成就系统。采用模块化架构，职责分明。
|
||
|
||
- **模块结构**:
|
||
- `__init__.py`: 路由注册与matcher定义（167行）
|
||
- `config.py`: Pydantic配置管理
|
||
- `gacha.py`: 抽卡核心逻辑（GachaSystem类）
|
||
- `data_manager.py`: SQLite数据持久化（DataManager类）
|
||
- `rules.py`: 命令匹配规则（check_permission等）
|
||
- `formatters.py`: 消息格式化（9个格式化函数）
|
||
- `handlers/`: 命令处理函数（9个handler模块）
|
||
- `utils.py`: 通用工具函数
|
||
- `api_utils.py`: 积分系统API交互
|
||
- `web_api.py`: HTTP API路由
|
||
|
||
- **主要命令**:
|
||
- `抽卡`: 执行单抽。
|
||
- `三连抽`: 执行三连抽。
|
||
- `我的抽卡`: 查看个人统计。
|
||
- `抽卡排行`: 查看抽卡排行榜。
|
||
- `今日抽卡`: 查看今日抽卡统计。
|
||
- `查询成就`: 查看已解锁成就及进度（非酋、勤勤恳恳系列）。
|
||
- `抽卡介绍`: 查看详细机制与奖励说明。
|
||
- `积分商店`（`兑换商店`）: 查看可兑换商品、余额与剩余抽卡次数。
|
||
- `兑换抽卡`（`积分兑换`）: 消耗 99 Bot 积分兑换 1 次当日抽卡机会。
|
||
- **特性**: 抽中 SSR/SP 可获得"蛋定助手"卡密奖励（需联系管理员领取）。包含每日抽卡签到积分奖励（与独立「签到」命令、WPF 客户端共用同一份签到数据，每天仅一次）。成就系统自动发放积分奖励。
|
||
### 10. damo_balance - 大漠账户查询
|
||
|
||
查询大漠平台账户余额。
|
||
|
||
- **命令**: `大漠余额` 或 `余额查询`。
|
||
- **限制**: 仅特定用户可用，需输入验证码。
|
||
|
||
### 11. danding_api - 管理 API
|
||
|
||
供超级用户使用的后台管理功能。
|
||
|
||
- **主要命令**:
|
||
- `在线人数`: 查询当前活跃用户。
|
||
- `生成卡密 <类型>`: 生成天/周/月卡。
|
||
- `用户加时 <用户名> <类型>`: 直接为特定用户增加时长。
|
||
|
||
### 12. danding_help - 帮助菜单
|
||
|
||
系统的官方指引手册。
|
||
|
||
- **主要命令**: `帮助`、`下载`、`活动`（别名：`最新活动`、`群活动`、`hd`）、`每日试用`、`正式版如何运行` 等。
|
||
- **活动海报推送**: 发送 `活动` 时自动请求服务端接口获取当前正在进行中的运营活动，并向群内发送对应的活动宣传海报及说明。
|
||
- **限制**: 仅在特定群 `621016172` 可用。
|
||
|
||
### 13. command_list - 指令列表
|
||
|
||
快速查阅所有可用指令。
|
||
|
||
- **命令**: `指令列表`。
|
||
|
||
### 14. danding_sign_in - 每日签到
|
||
|
||
独立的每日签到命令，与抽卡签到、WPF 客户端签到**共用同一份签到数据**（xapi `bot_gacha_daily_sign_in` 表，每用户每天仅一次，任一入口先到先得）。
|
||
|
||
- **主要命令**: `签到`（别名：`每日签到`、`打卡`）。
|
||
- **积分奖励**: 随机 1-100 积分（与抽卡签到一致），积分流水 `source=gacha_sign`、`reason=抽卡签到`。
|
||
- **权限**: 白名单群聊 `621016172` 或管理员可用；私聊非管理员不可用。
|
||
- **数据共用说明**: 同一天内，抽卡/WPF/命令签到任一入口先触发者获得积分，后触发者提示"今天已签到"，不会重复发放。
|
||
|
||
---
|
||
|
||
## 常见问题 (FAQ)
|
||
|
||
- **Q: 为什么某些命令没反应？**
|
||
A: 部分插件（如 `danding_help`）限制了特定群聊使用；管理指令需要配置 `SUPERUSERS`。
|
||
- **Q: 积分有什么用？**
|
||
A: 目前主要用于赛马下注及展示排名。
|
||
- **Q: 抽卡奖励如何领取？**
|
||
A: 抽中 SSR/SP 或解锁特定成就后，请截屏联系管理员。
|