AstrBot 钓鱼插件

astrbot_plugin_fishing 是一个基于早期钓鱼插件持续演进的 AstrBot 二开维护版本。

原始插件已停止维护；当前版本围绕 AstrBot 新版生态、MySQL 持久化、图片化交互、交易所、多商店与 Web 管理持续修复和扩展。

本项目当前目标不是“兼容旧实现的最小补丁”，而是：

• 在 AstrBot 4.x 生态内保持可运行、可维护、可扩展
• 将核心业务逐步统一到 MySQL 主路径
• 让管理员可以通过 Web 管理界面 配置更多实际玩法参数
• 保持对旧存档/旧玩法的兼容迁移能力

当前状态

• 当前主维护版本：v2.4.7
• 当前推荐存储后端：MySQL
• 当前插件状态：持续维护中
• 当前开发方向：修复 + 稳定化 + Web 可配置化 + 新系统扩展

主要功能

• 完整钓鱼系统：区域、鱼类、稀有度、品质、高品质双倍价值
• 背包与资产系统：鱼塘、水族箱、鱼竿、鱼饵、饰品、道具、锁定、精炼
• 经济系统：金币、高级货币、用户转账、税收机制
• 商店系统：多商店、多商品、复杂成本、限购、时段控制
• 玩家市场：鱼类、装备、道具上架与购买
• 交易所系统：大宗商品、动态价格、价格历史、持仓盈亏、清仓、容量控制
• 社交玩法：偷鱼、偷看鱼塘、红包、排行、称号、成就
• 抽卡与小游戏：抽卡、擦弹、骰宝、命运之轮
• 管理功能：Web 管理后台、模板数据管理、CSV 导入导出、交易所参数配置

当前架构说明

1. 存储后端

本项目当前以 MySQL 为主路径。

• external_sql.backend = mysql 时，插件使用 Mysql*Repository
• SQLite migration / sync 仅在 backend = sqlite 场景下作为旧路径使用
• 当前维护方向是不再继续扩大 SQLite 运行路径，而是保留迁移与兼容能力

2. 模块结构

• main.py：插件入口、命令路由、服务装配
• handlers/：命令处理层
• core/services/：业务服务层
• core/repositories/：仓储层（MySQL / SQLite）
• core/database/：连接、迁移、同步、数据库工具
• draw/：图片渲染层
• manager/：Web 管理后台

3. Web 管理

当前 Web 管理已支持：

• 鱼类、鱼竿、鱼饵、饰品模板管理
• 交易所管理
• 新增交易所商品时同步维护：
  • 初始价格
  • 波动率
  • 保质期
  • 作用效果文案
• 新增鱼竿 / 鱼饵 / 饰品时维护“实际作用效果”说明

安装方式

方式一：放入插件目录

将插件目录放入：

AstrBot/data/plugins/astrbot_plugin_fishing

然后重启 AstrBot 或在 WebUI 中重载插件。

方式二：从插件地址安装

可通过 AstrBot 插件管理界面安装对应仓库地址。

配置重点

核心配置文件：

data/config/astrbot_plugin_fishing_config.json

重点配置项：

• external_sql.backend
• external_sql.mysql_url
• external_sql.connect_timeout
• external_sql.read_timeout
• external_sql.write_timeout
• exchange.initial_prices
• exchange.volatility
• exchange.shelf_life_days
• exchange.commodity_effects
• item_effect_notes

开发说明

本项目遵循 AstrBot 官方插件开发思路，但由于它属于“停止维护插件的持续二开版本”，开发时请优先考虑以下现实原则：

1. 以当前项目结构为准，而不是以模板工程为准

AstrBot 官方模板适用于新插件；本项目属于复杂历史项目，开发时请优先：

• 理解现有服务层 / 仓储层边界
• 优先修复已有行为，而非大面积推翻重写
• 新功能尽量落到 Web 管理或配置结构中，减少硬编码

2. 以 MySQL 为主路径

新增功能、修复逻辑时请默认考虑：

• MySQL 仓储是否已实现
• 是否会误触 SQLite-only 逻辑
• 是否需要数据迁移或配置兼容

3. 新增项目要同时补齐“实际作用”

如果你新增的是：

• 交易所商品
• 鱼竿
• 鱼饵
• 饰品

请不要只新增模板本体，还应同步补齐：

• 展示名称
• 描述文案
• 实际作用效果说明
• 对应数值参数（如波动率、保质期、加成倍率等）
• Web 管理可配置入口（如适用）

推荐开发流程

1. 环境准备

建议你已具备：

• Python 开发经验
• Git / GitHub 基础
• AstrBot 本体运行经验

2. 本地开发

推荐目录结构：

git clone https://github.com/AstrBotDevs/AstrBot
mkdir -p AstrBot/data/plugins
cd AstrBot/data/plugins
git clone <your-repo>

3. 调试方式

AstrBot 插件采用运行时注入机制，请通过 AstrBot 本体进行调试。

推荐方式：

• 在 WebUI 插件页重载插件
• 出错时查看 AstrBot 容器 / 进程日志
• 避免只做静态改动不实际验证命令链路

命令手册

以下命令手册以当前 draw/help.py 与 main.py 实际路由为准。

基础与核心玩法

• /注册 / /註冊
• /钓鱼 / /釣魚
• /签到 / /簽到
• /自动钓鱼 / /自動釣魚
• /钓鱼区域 [ID]
• /钓鱼记录 / /钓鱼日志 / /钓鱼历史
• /更新昵称 [新昵称]
• /钓鱼帮助 / /帮助

背包与资产管理

• /状态 / /狀態
• /背包
• /鱼塘 / /魚塘
• /鱼塘容量
• /升级鱼塘
• /水族箱
• /水族箱帮助
• /放入水族箱 [FID] [数量]
• /移出水族箱 [FID] [数量]
• /升级水族箱
• /鱼竿
• /鱼饵
• /饰品
• /道具
• /使用 [ID]
• /开启全部钱袋
• /精炼 [ID]
• /出售 [ID]
• /锁定 [ID]
• /解锁 [ID]
• /金币
• /高级货币

商店与市场

• /全部卖出
• /保留卖出
• /砸锅卖铁
• /出售稀有度 [1-5]
• /出售所有鱼竿
• /出售所有饰品
• /商店
• /商店购买 [商店ID] [商品ID] [数量]
• /市场
• /上架 [ID] [价格] [数量] [匿名]
• /购买 [ID]
• /我的上架
• /下架 [ID]

抽卡与概率玩法

• /抽卡 [卡池ID]
• /十连 [卡池ID]
• /查看卡池 [ID]
• /抽卡记录
• /擦弹 [金额]
• /擦弹记录
• /命运之轮 [金额]
• /继续
• /放弃

骰宝游戏

• /开庄
• /大 [金额]
• /小 [金额]
• /单 [金额]
• /双 [金额]
• /豹子 [金额]
• /一点 [金额]
• /4点 [金额]
• /17点 [金额]
• /骰宝状态
• /我的下注
• /骰宝帮助
• /骰宝赔率
• /骰宝结算
• /骰宝倒计时 [秒数]
• /骰宝模式 [模式]

社交功能

• /排行榜 [类型]
• /偷鱼 [@用户]
• /电鱼 [@用户]
• /驱灵 [@用户]
• /偷看鱼塘 [@用户]
• /转账 [@用户/用户ID] [金额]
• /发红包 [金额] [数量] [类型] [口令]
• /领红包 [ID] [口令]
• /红包列表
• /红包详情 [ID]
• /撤回红包 [ID]
• /清理红包 [所有]
• /查看称号
• /使用称号 [ID]
• /查看成就
• /税收记录
• /鱼类图鉴

交易所

• /交易所
• /交易所 开户
• /交易所 买入 [商品] [数量]
• /交易所 卖出 [商品] [数量]
• /交易所 帮助
• /持仓
• /清仓

交易所子命令已支持繁简通用，例如：

• /交易所 開戶
• /交易所 買入 魚骨 1
• /交易所 賣出 魚骨 1
• /交易所 幫助
• /持倉
• /清倉

也支持直接子命令：

• /开户 / /開戶
• /买入 / /買入
• /卖出 / /賣出

管理后台（管理员）

• /修改金币 [用户ID] [数量]
• /奖励金币 [用户ID] [数量]
• /扣除金币 [用户ID] [数量]
• /修改高级货币 [用户ID] [数量]
• /奖励高级货币 [用户ID] [数量]
• /扣除高级货币 [用户ID] [数量]
• /全体奖励金币 [数量]
• /全体奖励高级货币 [数量]
• /全体扣除金币 [数量]
• /全体扣除高级货币 [数量]
• /全体发放道具 [道具ID] [数量]
• /授予称号 [@用户/用户ID] [称号名称]
• /移除称号 [@用户/用户ID] [称号名称]
• /创建称号 [称号名称] [描述] [显示格式]
• /补充鱼池
• /开启钓鱼后台管理
• /关闭钓鱼后台管理
• /代理上线 [用户ID]
• /代理下线
• /同步初始设定

4. 依赖管理

如插件使用第三方库，请在插件目录维护：

requirements.txt

避免用户安装后出现 ModuleNotFoundError。

开发原则

• 功能必须经过测试，至少做核心命令烟雾验证
• 新增数据库逻辑必须考虑 MySQL 路径
• 持久化数据存于 data/，不要写入插件代码目录
• 保持良好的错误处理，不让单点异常拖垮整个插件
• 新增玩法参数尽量可配置，避免继续扩大硬编码
• 网络请求避免使用 requests，优先使用异步方案
• 提交前建议进行格式化与基础静态检查

文档约定

当前仓库内文档分工如下：

• README.md：项目总览、安装、架构、开发说明
• CONTRIBUTING.md：贡献流程、提交规范、PR 目标分支
• CHANGELOG.md：版本更新记录
• DATABASE_FIX_README.md / QUICK_FIX_GUIDE.md：历史修复与应急文档

兼容说明

本项目支持从旧钓鱼插件数据迁移，但不代表旧实现中的所有设计都继续保留。

当前维护策略是：

• 能兼容的尽量兼容
• 会阻碍维护的旧路径逐步收敛
• 新功能优先纳入现有服务层和 Web 管理体系

贡献建议

如果你是功能扩展贡献者，优先考虑以下方向：

• MySQL 路径补全
• Web 管理可配置化
• 图片渲染稳定性
• 交易所 / 商店 / 市场的参数统一
• 命令繁简兼容与帮助文档同步

如需提交 PR，请先阅读 CONTRIBUTING.md。