🎣 Koishi 回合制钓鱼大师 (turnbase-fishing-game)

一款为 Koishi 打造的深度回合制钓鱼 RPG 插件。拥有超过 600 种可收集生物、动态世界事件、完整的技能树与等级系统、波动的市场经济以及策略性的装备管理。这不仅是钓鱼，更是一场冒险。

核心特色

• ⚔️ 互动式钓鱼战斗: 与鱼儿展开一场体力与策略的较量！通过【坚持】、【放线】、【收线】等操作，在消耗鱼的斗志和控制鱼线张力之间找到平衡，最终将其捕获。

• 📖 超过 600 种可收集物: 内置超过 600 种设计各异的生物和物品，从普通的"鲫鱼"到神话中的"东方青龙"，每一次上钩都充满惊喜。

• 🗺️ 广阔的探索地图: 包含【柳溪河】、【镜之湖】、【黄金海岸】、【风暴深海】、【无光之渊】以及神秘的【传说之泉】等多个钓场。每个地图都有其独特的鱼类分布，高级地图需要购买【准钓证】才能进入。

• 🌪️ 动态世界事件: 天气、节日、生物迁徙等随机事件会实时影响钓鱼难度、稀有度乃至市场价格，让每次出航都充满变数。

• 🧠 深度 RPG 成长: 独特的等级和技能树系统！通过升级获得技能点，自由构筑"战斗技巧"、"幸运"、"洞察力"和"装备保养"等不同流派的钓鱼大师。

• 📈 动态经济系统: 真正的玩家驱动市场！鱼类的价格会根据全服玩家的捕获量动态波动，抓住商机，低买高卖，成为渔业大亨。

• 🛠️ 策略性装备管理: 鱼竿不仅有等级之分，更有耐久度设定！挑战超出负荷的巨物可能导致装备损坏甚至永久报废，修理和选择合适的装备是成功的关键。

• 🏆 成就与社交: 解锁数十种称号，从【钓鱼菜鸟】到【神话创造者】，并通过排行榜与好友一较高下，争夺服务器的最高荣誉。

指令一览

核心指令

• 钓鱼 / fish / f: 开始钓鱼，进入回合制战斗。
• 钓鱼.签到: 每日签到以获取金币奖励。
• 钓鱼.天气: 查看当前天气、时段和节日加成。
• 钓鱼.事件: 查看当前活跃的全局/地图事件。
• 钓鱼.切换地图 [地图名]: 查看或切换钓鱼地点。
• 钓鱼.传说之泉: 查询传说之泉每日开放时间。

信息查询

• 钓鱼.状态 / 钓鱼.s / 钓鱼.my: 查看个人统计、等级、体力、装备信息。
• 钓鱼.背包 / 钓鱼.b: 查看鱼、鱼竿、药水、道具等物品。
• 钓鱼.图鉴 [页码]: 分页查看已解锁的鱼类。
• 钓鱼.称号 [称号名]: 查看称号列表或佩戴指定称号。
• 钓鱼.排行榜 [类型]: 查看各类排行榜（巨物/富豪/累计/传奇/等级/虔诚/大赛）。
• 钓鱼.百科 [分类]: 查看战斗/经济/妈祖/鱼竿/技能等机制说明。

任务与成就

• 钓鱼.任务 [序号]: 查看今日任务或领取指定任务奖励。
• 钓鱼.成就 [页码]: 查看成就列表和解锁进度。

商店装备

• 钓鱼.商店 [分类]: 打开商店（1鱼饵/2药水/3道具/4鱼竿/5鱼线/6准钓证/7组合包/8行情）。
• 钓鱼.购买 <商品名> [数量]: 购买指定商品。
• 钓鱼.装备 <类型> <名称>: 装备鱼竿/鱼线/鱼饵。
• 钓鱼.出售 [-a全部/-r稀有度/-b低于重量/-o高于重量/鱼名]: 出售鱼。
• 钓鱼.修理 <鱼竿名>: 修理损坏的鱼竿。
• 钓鱼.修理.重铸 <鱼竿名>: 重铸鱼竿（需要海洋之泪）。
• 钓鱼.使用 <物品名>: 使用药水/道具/凭证。
• 钓鱼.丢弃 <物品名> [数量]: 丢弃物品。

成长系统

• 钓鱼.技能 [技能名]: 查看技能树或学习技能。
• 钓鱼.神器 [神器名]: 查看神器等级和属性。
• 钓鱼.妈祖: 神龛供奉与祈愿（提升运气）。
• 钓鱼.设置: 设置昵称/自动喝药/自动续费鱼线。

料理系统

• 钓鱼.料理: 查看配方和已制作料理。
• 钓鱼.烹饪 <配方名>: 用鱼制作 Buff 料理。
• 钓鱼.食用 <料理名>: 享用料理获得 Buff。

玩家交易

• 钓鱼.转账 @用户 <金额>: 向其他玩家转账（5%手续费）。
• 钓鱼.寄卖行: 查看全服交易市场。
• 钓鱼.寄卖行.挂单 <鱼名> <数量> <单价>: 挂单出售。
• 钓鱼.寄卖行.搜索/购买/撤单/我的挂单: 交易操作。

AI 助手（需配置 aiConfig.enabled）

• 钓鱼.助手 [问题]: 咨询钓鱼建议或询问鱼类知识。

帮助

• 钓鱼.帮助 / fishing-help: 显示本插件的详细帮助信息。

配置项

| 配置项 | 类型 | 默认值 | 说明 | | :--- | :--- | :--- | :--- | | cooldown | number | 30000 | 玩家每次钓鱼后的冷却时间（毫秒）。 | | normalBaitPrice | number | 5 | 商店中单个普通鱼饵的购买价格。 | | advancedBaitPrice | number | 100 | 商店中单个高级鱼饵的购买价格。 | | baitPrices | object | {} | 特色鱼饵价格覆盖，如 {"night_bait": 90}。 | | baitCost | number | 1 | 每次钓鱼消耗的普通鱼饵数量。 | | advancedBaitCost | number | 1 | 每次钓鱼消耗的高级鱼饵数量。 | | signInBonus | number | 200 | 玩家每日签到时获得的金币数量。 | | fishingStaminaCost | number | 10 | 每次抛出鱼竿开始钓鱼时，基础消耗的体力值。 | | defaultMaxStamina | number | 100 | 新玩家或重置时，初始的最大体力值。 | | staminaPerLevel | number | 5 | 玩家每提升一个等级，最大体力值增加的点数。 | | staminaOverflowMultiplier | number | 2.0 | 使用体力药水时，允许体力溢出基础最大体力的倍数。 | | rodMaxDurability | number | 100 | 所有普通鱼竿的初始和修理后的最大耐久度。 | | rodDurabilityPenaltyThreshold | number | 0.3 | 鱼竿耐久度低于此比例时，性能将开始下降。 | | rodOverloadDamageThreshold | number | 1.0 | 鱼竿承重超过此阈值倍数时，鱼竿开始承受过载损伤。 | | rodRepairCostMultiplier | number | 0.15 | 计算鱼竿修理费用时的基础费率。 | | quickFish | object | {...} | 控制快速钓鱼功能的行为。 | | dmMode | boolean | false | 钓鱼战斗是否在私聊中进行。 | | junkChance | number | 0.05 | 每次抛竿钓到垃圾的基础概率。 | | staminaCostsPerAction | object | {...} | 配置【坚持】、【放线】、【收线】的体力消耗。 | | advancedBaitEffects | object | {...} | 配置高级鱼饵的重量加成、难度降低等效果。 | | eventUpdateInterval | number | 1 | 全局事件系统每隔多少小时更新一次。 | | specialEncounter | object | {...} | 控制特殊生物的出现概率及其 Pity 保底机制。 | | reforgeSystem | object | {...} | 配置鱼竿"重铸"操作的条件和花费。 | | combatMechanics | object | {...} | 调整钓鱼战斗核心平衡性的数值。 | | formula | object | {...} | （v5.0 新增）公式设置：集中调整战斗手感、咬钩机制、经济、斗志/体力等核心系数，改动即时生效、无需改代码。含 combat（回合数/连击/收线权重/完美收线等）、bite（咬钩开关/等待与提竿时长/关键词）、economy（鱼价/经验倍率）、willStamina（初始斗志/体力消耗）四组。 | | mapData | array | [...] | 所有可用的钓鱼地图及其配置。 | | rodData | array | [...] | 所有可购买的鱼竿及其属性。 | | rarityConfig | object | {...} | 鱼类稀有度的全局配置。 | | potionPrices | array | [...] | 商店中可购买的体力药水列表。 | | titles | array | [...] | 所有可获得的称号及其解锁条件。 | | weatherCity | string | "" | 天气查询城市名，留空则自动检测 IP 位置。 | | aiConfig | object | {...} | 本地 LLM (Ollama) 智能助手配置。 |

钓鱼战斗机制

咬钩阶段（v5.0 新增）

抛竿后不会立刻进入战斗，而是先模拟真实的等待过程：

1. 等待咬钩: 鱼钩入水后随机等待一段时间（默认 1.5~5 秒），静候鱼儿上钩。
2. 提竿窗口: 浮漂猛沉时进入限时窗口（默认 8 秒），及时发送「提竿 / 收 / 拉」或**直接回复「1」**即可中鱼。
3. 错过处理: 反应太慢或提竿动作不对，鱼儿会吐钩逃走；默认不消耗鱼饵（自动归还），鼓励反复尝试。

咬钩机制可在配置项「公式设置 → 咬钩机制」中整体开启或关闭；提竿窗口时长（strikeWindowMs）与提竿关键词（strikeKeywords）均可在此自定义。关闭咬钩后恢复"抛竿即战斗"的旧流程。

回合制搏斗

进入战斗后是回合制的体力与策略较量：

1. 【坚持】: 消耗鱼的斗志，积累连击数（每连击 +6% 收线成功率，上限 +50%）。
2. 【放线】: 降低鱼线张力，防止断线；小概率触发"诱鱼"进一步削弱斗志。
3. 【收线】: 尝试捕获，成功率 =(1-斗志)×(1-张力×权重)×(1-难度×权重)+ 技能 + 连击。
4. 【剪线】: 主动放弃，保护鱼竿免受损坏。

最佳策略: 先【坚持】积累 5+ 连击 → 再【收线】，成功率大幅提升！

完美收线: 斗志 <20% 且张力 <30% 时收线，额外 +30% 成功率。

关于力竭: 默认开启「必须收线才能上鱼」，鱼力竭时不会自动捕获，需主动【收线】收服（会有强提示）。若在配置项中关闭该开关，则鱼斗志≤3% 时继续【坚持】会自动力竭捕获。

示例

你在【柳溪河】抛出了【新手竹竿】,使用了【普通鱼饵】...
🎣 鱼钩已入水，静候鱼儿上钩……（留意浮漂动静）

❗ 浮漂猛地一沉——有鱼咬钩！
⏱️ 在 8 秒内发送「提竿」或直接回复「1」提竿！

1

✅ 提竿成功！鱼线瞬间绷紧——开始较量！

===== 🎣 战斗回合 1/20 =====
🐟 手感: 5.2kg | 新手竹竿

⚡ 斗志: ██████████░░ 85%
🪢 张力: ██░░░░░░░░░░ 18%
💪 体力: ███████████░ 90/100

━━━━━━━━━━━━━━━━━
[1] 坚持 (-9⚡) | 推荐：斗志高时使用
[2] 放线 (-3⚡)  | 推荐：张力高时使用
[3] 收线 (-13⚡) | 成功率估算: 低 (12%)
[4] 剪线 (放弃)
━━━━━━━━━━━━━━━━━
💡 建议：鱼还在奋力挣扎，先坚持消耗斗志。

1

你紧握鱼竿全力对抗！斗志-8.4% | 连击×1 | 继续坚持可提升收线成功率

... (坚持数回合积累连击，斗志降低后收线) ...

🔥 5连击发威！鱼儿被强势拉出水面！
🎉 恭喜！你成功钓到了【巨型乌鳢】！
✨ 巨型乌鳢 (稀有) ✨
📏 重量: 6.80 kg
💰 估价: 163 金币
🌟 获得经验: 45 XP
📝 体型巨大的乌鳢,攻击性极强,是淡水中的霸主。

更新记录

v5.0.1 (2026-07-16)

• 更新部分遗漏

v5.0.0-alpha2 (2026-07-16)

• 咬钩机制（#6 真实钓鱼手感）:
  • 抛竿后新增「等待咬钩 → 提竿窗口」两个阶段，只有在限时窗口内发送提竿关键词才能中鱼
  • 默认开启「必须收线才能上鱼」：鱼力竭时不再自动捕获，需主动【收线】收服（附强提示文本）
  • 错过咬钩默认不消耗鱼饵（自动归还），鼓励反复尝试
  • 全部时间/关键词/开关可在配置项「公式设置 → 咬钩机制」实时调整；关闭后恢复"抛竿即战斗"旧流程
• 公式可配置化（#5）:
  • 新增 formula 配置分组，将原先散落在 combat.js/calculations.js 的硬编码系数统一抽出到 data/formula-config.js
  • 涵盖：战斗手感（回合数、连击、张力权重、超重惩罚、完美收线、逃脱、诱鱼、回合节奏）、咬钩机制、经济（鱼价/经验稀有度系数）、斗志与体力（初始斗志、伤害、体力消耗）、稀有度（鱼竿加成、重量采样）
  • 所有系数均带默认值回退，缺省场景不崩溃；管理员改配置即时生效，无需改代码
• 料理系统重做（#4 内容扩充 + #10 修正误导）:
  • 严重 Bug 修复：原料理 Buff 使用 effect:'focus' 字符串，但引擎只识别 effects:{} 对象结构，导致刺身拼盘/海鲜盛宴/寿司卷等全部 Buff 料理的加成实际不生效（描述承诺"+10%成功率"等却毫无作用）。现全部改为引擎可消费的 effects 结构，加成真实生效
  • getAggregatedBuffEffects 补充聚合 reelSuccessModifier；在 getUserData 中把料理/祝福的 sellPriceBonus/xpGainBonus/staminaCostReduction/reelSuccessModifier 并入 skillEffects（复制后叠加，不污染技能缓存），使价格/经验/收线/体力等下游函数正确读取
  • 修正 Buff 时长误导：duration 实为「钓鱼次数」而非「分钟」，文案统一改为"接下来 N 次钓鱼"
  • 配方从 8 个扩充至 12 个：新增暖心火锅（大回体力）、能量鱼糕（省体力）、幸运鱼饼（降垃圾率+提稀有）、鱼子酱盛盘（收线+售价），并按恢复/战斗/收益/幸运/随机分类
• 代码清理:
  • 删除 35 个历史死代码文件
• QQ 文案与文本审查（#8/#10）:
  • 主菜单精简为紧凑网格布局，移除过时的"v4.0"硬编码版本号
  • 钓鱼.图鉴 头部新增「已发现 X/总物种 (百分比)」完成度展示
  • 钓鱼.百科 战斗 改为动态反映咬钩/必须收线/完美收线机制（依据实时配置渲染）
  • 钓鱼.百科 经济 修正稀有度倍率说明：从旧硬编码"×1/×2.5/×6/×15/×35"改为与实际公式一致的"√value×50+1"派生倍率（普通≈12x…传说≈46x）
  • 钓鱼.帮助 修正 v4.0 标题、错误的"钓鱼.神龛"（实为「妈祖」）及过时价格参考公式
• Bug 修复:
  • 修复 钓鱼.设置 自动喝药 开 因参数解析（[action:string] 仅捕获单词）导致始终显示"已关闭"的问题，改用 [action:text] 捕获整行

v5.0.0 (2026-07-12)

• 架构重建: 两套并行代码彻底清理，35个死文件删除
• 经济重平衡: 新卖价公式消除通胀，753种鱼 basePrice 重标
• QQ 官方 Bot: 全新无状态模式，战斗状态机+独立动作指令
• 配置精简: 三层分类架构(常用/进阶/代码内)，从30+项缩到8项
• 战斗公式修正: 所有概率 clamp 保护，相对张力替代绝对值，删除死分支
• 称号扩充: 从9个扩充到27个（地图大师/稀有度专精/锦标赛冠军等）
• 指令精简: 分组归并，去掉双轨数字菜单
• 管理功能重做: 备份走文件系统、发放用选项参数、玩家管理补全
• 性能优化: 鱼池预建索引、惰性迁移+版本号、派生值缓存
• 交互抽象层: ui/session.js 统一处理双模式分流

v4.1.1-alpha1 (2026-06-28)

• 严重Bug修复:
  • BUG-02: 修复 case '4' (剪线) 缺少块作用域导致的 SyntaxError: Lexical declaration cannot appear in a single-statement context
  • BUG-04: 重写 migrateAllUsers，使用 ctx.database.get('fishing_users', {}) + 逐条 set 替代不存在的 ctx.database.eval API，启动迁移不再崩溃
  • BUG-01: 修复 pityCounter 在垃圾(junk)判定前就写入数据库的时序问题，现在仅在成功进入战斗后才增长
• 战斗重平衡:
  • 体力公式重做: calculateDynamicStaminaCost 改用对数平滑（log₂(weight/10+1)），加入 maxStamina × 40% 硬上限，高端内容体力消耗降低约 60%
  • 放线重设计: 不再恢复鱼斗志，改为 10% 概率诱鱼（-斗志），耐力大师技能提供 25% 诱鱼概率且不清零连击
  • 完美收线系统: 斗志<20% 且张力<30% 时触发，成功率额外 +30%，附带特殊动画文本
  • 耐力不足非阻塞: 体力不足时不再弹出交互确认框，直接结束战斗，减少等待
• 技能/效果修复:
  • BUG-09: 连击助推器（combo_booster）正式生效，战斗中聚合 session_buff 效果，hold 伤害乘以 (1 + comboBoostMultiplier × comboCount)
  • holdTensionModifier 技能效果（张力控制1-3）现正确应用于坚持操作的张力增长
  • staminaCostReduction 补全到技能效果聚合引擎，耐力大师/气象护符生效
• 经济系统优化:
  • BUG-14: 鱼价公式从硬编码稀有度倍率改为从 rarityConfig.value 派生（value=0.05→~12x, 0.80→~45x），管理员调整配置后价格同步变化
  • XP稀有度倍率同样从 rarityConfig.value 派生（Math.max(1, round(value × 20))）
  • 收购订单系统: 每日随机选5种鱼给予 1.3~3.0x 价格加成，在 钓鱼.行情 中查看
  • BUG-06: 签到奖励改为 config.signInBonus（默认300）为基础值 × 连签倍率（30天=4.0x），管理员可配置生效
• 鱼线系统修复:
  • BUG-07: 新增 lineStatus 字段持久化每条鱼线的独立耐久度，切换鱼线时保存旧线耐久、恢复新线耐久，杜绝切换重置漏洞
  • createNewUser、getUserData 字段修复、handleFishCapture 耐久同步均覆盖
• 事件/经验修复:
  • BUG-03: handleFishCapture 和 handleXpAndLevelUp 透传 activeEvents 参数至 calculateXpGained，活跃事件XP加成在捕获时正确生效
  • BUG-13: checkAndUnlockTitles 支持传入现有 userData 避免额外DB查询
• 数据安全:
  • BUG-11: getRandomFish 归一化分母 totalProb === 0 时回退默认概率，防止 NaN/Infinity
  • BUG-05: handleSpecialEncounter Buff消耗逻辑重构，零价值祝福分支与其他分支明确分离
  • BUG-12: 背包满载检测改为捕获后重新读取数据库实际大小
  • BUG-10: BAIT_TYPES require 移出 getRandomFish 函数体到文件顶部
• 新内容:
  • 新增技能×3：精准抛竿（稀有鱼感知+15%）、耐力大师（放线不清零连击+诱鱼概率）、市场嗅觉（售价+10%）
  • 新增 WEATHER_FISH_EFFECTS 常量和 seasonRates 支持（鱼类季节权重渐变）
  • 会话管理改进：ctx.on('dispose') 清理所有活跃钓鱼会话的 timeout，防止热重载泄露

v4.1.0-alpha1 (2026-06-28)

• 你的意思是没bug了？！

v4.0.3-alpha2 (2026-05-19)

• 修复:无法出售问题
• 修复:天气变化异常问题

v4.0.3-alpha1 (2026-05-17)

• 全面数值重平衡: 鱼价公式改为对数生长模型（基础价 × (1+ln(重量+1)) × 稀有度倍率），防止价格爆炸
  • 鲫鱼(1.5kg)≈15g | 稀有鱼(50kg)≈3500g | 传说(200kg)≈110,000g
  • XP公式同样使用对数生长，限制单次经验增长
• 新手体验优化: 新手竹竿承重5→10kg，结实铁竿20→30kg
• 出售功能重做: 支持自然语言（钓鱼.出售 -a, 钓鱼.出售 鲫鱼），直接显示背包鱼获概览
• 供奉功能重做: 支持自然语言格式（钓鱼.妈祖.供奉 鲫鱼 1），默认数量为1，增加确认步骤
• 祝福泛滥彻底修复:
  • 特殊邂逅池只过滤真正的特殊生物（排除垃圾物品）
  • 降低基础概率（0.05%），非传说地图概率再×0.3
  • 旧用户pityCounter和buff自动重置迁移
• 交互改进: 钓鱼命令直接开始钓鱼，钓鱼 菜单或钓鱼 6打开菜单
• 修复: 出售/供奉参数解析问题，供奉返回0虔诚度问题
• 文档: 更新package.json版本号，更新README更新记录

v4.0.2-alpha1 (2026-05-15)

• 总之先更新个版本号

v4.0.1-alpha2 (2026-05-15)

• 写错版本号了...再改一次

v4.0.1-alpha2 (2026-05-15)

• 继续修复大量bug
• 修复: 用户自定义称号缺少 description 导致插件启动失败的问题。
• 修复: 鱼饵价格显示与配置不同步的问题，现在 normalBaitPrice、advancedBaitPrice 和 baitPrices 会动态影响商店显示和购买价格。
• 修复: 菜单中“事件”(16) 和“天气”(17) 无反应的问题，新增了 钓鱼.事件 和 钓鱼.天气 命令。
• 修复: 执行 钓鱼.天气 时进入钓鱼战斗并报错的问题，原因是命令未注册及 activeEvents 参数可能为 null。
• 修复: 图鉴显示空白的问题，增加自动从 backpack 重建 fishRecords 的迁移脚本。
• 优化: 为常用命令增加短别名（如 .s、.b、.my 等），提升使用便捷性。
• 优化: 主菜单数字直达功能保持不变，用户无需记忆命令名。
• 文档: 更新 README，添加新的配置项和命令说明，记录更新历史。

v4.0.0-alpha2 (2026-05-14)

• 完整重构：模块化架构（index.js 5430行→351行，22个清晰分层文件）
• 修复鱼饵系统（9种鱼饵完整购买/切换/效果）
• 修复隐藏地图（解锁检查+专属鱼类）
• 战斗透明化（显示完整成功率公式）
• 删除8个废弃模块，AI助手移除
• QQ官方Bot兼容配置项 qqOfficialMode
• 数据库完全兼容v3.0.1

v4.0.0-alpha1 (2026-05-13)

• 初次发布重构的 alpha 版本。

v3.0.1 (2026-04-20)

• 修复版本号与文档同步问题
• 优化 README 文档结构，与实际代码指令保持一致

v3.0.0

• 回合制钓鱼战斗系统
• 600+ 种鱼类和物品
• 技能树与等级系统
• 动态市场经济
• 装备耐久度管理
• 成就与排行榜系统

问题及 Bug 提交

请在 GitHub Issues 中提交问题，或联系插件作者。

许可证: MIT