liuwei_x_x/abot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

修仙功能开发上线

Browse Source
This commit is contained in:
liuwei
2025-11-18 11:19:59 +08:00
parent ca6969303d
commit eddc013182
6 changed files with 1883 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

373
plugins/xiuxian/README.md Normal file
View File

@@ -0,0 +1,373 @@
好的，我将把我们讨论过的**所有细节**，包括灵根类型、双轨制突破、所有保护机制、数据库设计、Redis 方案和防封策略，全部汇总成一份详尽的、可直接用于开发的 Markdown 研发文档。
-----
# 🚀 (终稿) 群聊文字修仙Bot - 综合研发文档
## 1\. 核心设计原则
本项目旨在实现一个功能完整、可玩性高、同时严格遵守平台规则的文字修仙 Bot。
1. **简化交互 (防封/防骚扰):** 杜绝一切“问答式”或“多步骤”指令。所有指令都必须是原子操作（一次性完成）。通过强制冷却 (Cooldown) 和清晰的玩家状态机来防止刷屏和恶意PVP。
2. **高性能:** 核心热数据（玩家状态、排行榜）必须由 Redis 管理，数据库 (MariaDB) 仅作为持久化存储。
3. **策略深度:** 玩家有明确的“策略分支”，例如【丹药 vs 强行】突破，【PVE vs PVP】资源获取，【灵根天赋】带来的个体差异。
好的，道友。修行之路漫漫，境界划分乃是天道之基石。
这里为你拟定一份详尽的、以“每阶10层”为基础的修炼级别体系。此体系平衡了前期“凡人”到“修士”的过渡，以及中后期“成仙”的漫长道路。
---
### 凡人篇 (Mortal Phase)
* **凡人 (Mortal)**
* (无层级之分，尚未感应灵气)
### 人仙篇 (Human Immortal Path)
#### 第 1 境：练气 (Lianqi / Qi Refining)
* *描述：* 感应灵气，引气入体，淬炼肉身，开辟丹田。此为修行之始。
* *层级：* **练气 1 层 ~ 练气 10 层 (大圆满)**
* *瓶颈：* 10层大圆满后，需冲击 **筑基** 瓶颈。
#### 第 2 境：筑基 (Zhuji / Foundation Establishment)
* *描述：* 灵气化液，在丹田内筑下道基。神识诞生，寿命大涨。
* *层级：* **筑基 1 层 ~ 筑基 10 层 (大圆满)**
* *瓶颈：* 10层大圆满后，需碎丹田道基，凝结 **金丹**。
#### 第 3 境：金丹 (Jindan / Golden Core)
* *描述：* 灵液归一，结成金丹。丹成无悔，自此踏入修仙坦途，可御空飞行。
* *层级：* **金丹 1 层 ~ 金丹 10 层 (大圆满)**
* *瓶颈：* 10层大圆满后，需碎丹，使丹中“真灵”化为 **元婴**。
#### 第 4 境：元婴 (Yuanying / Nascent Soul)
* *描述：* 金丹破碎，元婴出世。元婴为修士“第二性命”，可神魂出窍，夺舍重生。
* *层级：* **元婴 1 层 ~ 元婴 10 层 (大圆满)**
* *瓶颈：* 10层大圆满后，需元婴与神魂合一，领悟天地法则，是为 **化神**。
#### 第 5 境：化神 (Huashang / Spirit Transformation)
* *描述：* 神游太虚，领悟法则。元神合一，开始真正掌控天地灵气，法力无边。
* *层级：* **化神 1 层 ~ 化神 10 层 (大圆满)**
* *瓶颈：* 10层大圆满后，需元神与肉身彻底融合，达 **合体** 之境。
---
### 地仙篇 (Earthly Immortal Path)
*(后续境界通常更为艰难，可作为游戏的后期内容)*
#### 第 6 境：合体 (Heti / Integration)
* *描述：* 元神与肉身完美融合，不分彼此。举手投足引动天地之力，肉身不朽。
* *层级：* **合体 1 层 ~ 合体 10 层 (大圆满)**
#### 第 7 境：大乘 (Dacheng / Mahayana)
* *描述：* 法则大成，法力无边，已是人界巅峰。开始为飞升仙界做最后准备，积累底蕴。
* *层级：* **大乘 1 层 ~ 大乘 10 层 (大圆满)**
#### 第 8 境：渡劫 (Dujie / Tribulation)
* *描述：* 积累圆满，引动天劫（雷劫、心魔劫等）。此为成仙最后一道门槛，九死一生。
* *层级：* **渡劫 1 层 ~ 渡劫 10 层 (大圆满)**
*(注：此处 10 层可理解为承受“十重天劫”，或积累底蕴的十个阶段)*
### 真仙 (True Immortal)
* *描述：* 成功渡过天劫，飞升上界。
* *(游戏终点或新篇章起点)*
## 2\. 🛠️ 技术栈
| 类别 | 技术 | 备注 |
| :--- | :--- | :--- |
| 语言 | **Python 3.10+** | 异步 (asyncio) |
| Bot框架 | **NoneBot2** / **python-telegram-bot** | |
| 数据库 | **MariaDB 10.5+** | (InnoDB, utf8mb4) |
| ORM | **SQLAlchemy 2.0 (Async)** | |
| 缓存/限流 | **Redis** | 性能与防封的核心 |
## 3\. 💾 数据库设计 (MariaDB)
### 表 1: `t_xiuxian_player` (玩家核心表)
```sql
CREATE TABLE t_xiuxian_player (
-- 核心ID
user_id VARCHAR(100) NOT NULL COMMENT '平台用户ID',
group_id VARCHAR(100) NOT NULL COMMENT '主要所在群ID',
-- 基础信息
dao_name VARCHAR(100) NOT NULL COMMENT '道号',
realm VARCHAR(50) DEFAULT '凡人' COMMENT '境界 (如: 炼气1层, 筑基2层)',
spirit_root VARCHAR(50) DEFAULT '凡灵根' COMMENT '灵根天赋',
clan_id BIGINT DEFAULT NULL COMMENT '所属门派ID (外键)',
-- 资源
cultivation_points BIGINT DEFAULT 0 COMMENT '修为',
spirit_stone BIGINT DEFAULT 0 COMMENT '灵石 (对接你的积分系统)',
-- 状态机
status VARCHAR(20) DEFAULT 'Idle' COMMENT '玩家状态: Idle, Cultivating, Unstable_Qi, Injured',
status_until DATETIME DEFAULT NULL COMMENT '状态到期时间',
last_cultivate_time DATETIME DEFAULT NULL COMMENT '上次闭关开始时间',
PRIMARY KEY (user_id),
KEY idx_clan_id (clan_id),
KEY idx_realm (realm),
CONSTRAINT fk_clan_id FOREIGN KEY (clan_id) REFERENCES t_xiuxian_clan(clan_id) ON DELETE SET NULL
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='玩家核心数据表';
```
### 表 2: `t_xiuxian_clan` (门派表)
```sql
CREATE TABLE t_xiuxian_clan (
clan_id BIGINT NOT NULL AUTO_INCREMENT COMMENT '门派ID',
clan_name VARCHAR(100) NOT NULL COMMENT '门派名称',
group_id VARCHAR(100) NOT NULL COMMENT '所属群ID',
leader_user_id VARCHAR(100) NOT NULL COMMENT '掌门ID',
PRIMARY KEY (clan_id),
UNIQUE KEY uk_group_clan_name (group_id, clan_name) COMMENT '同一群内门派名唯一'
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='门派表';
```
### 表 3: `t_xiuxian_item` (物品表 - 静态)
```sql
CREATE TABLE t_xiuxian_item (
item_id INT NOT NULL AUTO_INCREMENT COMMENT '物品ID',
name VARCHAR(100) NOT NULL COMMENT '物品名称',
type VARCHAR(50) NOT NULL COMMENT '物品类型 (丹药, 材料)',
description TEXT COMMENT '物品描述',
PRIMARY KEY (item_id),
UNIQUE KEY uk_name (name)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='物品定义表 (静态数据)';
```
*注：开发初期，此表内容可硬编码在 `Config` 中。*
### 表 4: `t_xiuxian_inventory` (玩家背包表)
```sql
CREATE TABLE t_xiuxian_inventory (
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '背包条目ID',
user_id VARCHAR(100) NOT NULL COMMENT '玩家ID (外键)',
item_id INT NOT NULL COMMENT '物品ID (外键)',
quantity INT NOT NULL DEFAULT 0 COMMENT '数量',
PRIMARY KEY (id),
UNIQUE KEY uk_user_item (user_id, item_id) COMMENT '同一玩家同种物品只有一条记录',
CONSTRAINT fk_inv_user FOREIGN KEY (user_id) REFERENCES t_xiuxian_player(user_id) ON DELETE CASCADE,
CONSTRAINT fk_inv_item FOREIGN KEY (item_id) REFERENCES t_xiuxian_item(item_id) ON DELETE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='玩家背包表';
```
-----
## 4\. ⚙️ 核心系统配置 (Config)
这是游戏平衡性的核心，**必须**以配置文件 (如 `config.py`) 存在，**严禁**硬编码在逻辑中。
### 4.1. 灵根配置 (`SPIRIT_ROOT_CONFIG`)
用于 `/注册修仙` 和 `/出关`。
```python
# 灵根名称: (出现权重, 修为加成乘数)
SPIRIT_ROOT_CONFIG = {
"废灵根": (40, 0.8), # 40% 概率抽到, 修为效率 0.8x
"凡灵根": (30, 1.0), # 30% 概率, 基础效率 1.0x
"真灵根": (15, 1.2), # 15% 概率, 效率 1.2x
"异灵根": (10, 1.5), # 10% 概率, 效率 1.5x
"天灵根": (5, 2.0), # 5% 概率, 效率 2.0x
}
# 基础修为速率 (每小时)
BASE_CULTIVATION_RATE = 100
```
### 4.2. 突破配置 (`BREAKTHROUGH_CONFIG`)
用于 `/突破` 和 `/强行突破`。这是**双轨制**设计的核心。
```python
# Key 是玩家当前境界
BREAKTHROUGH_CONFIG = {
"炼气10层": {
"path_pill": {
"name": "丹药突破",
"required_item_id": 101, # 物品ID (筑基丹)
"required_item_name": "筑基丹",
"cultivation_cost": 5000, # 消耗修为 (低)
"base_success_rate": 0.4, # 成功率 (高)
"target_realm": "筑基1层" # 成功后的境界
},
"path_hard": {
"name": "强行突破",
"cultivation_cost": 20000, # 消耗修为 (非常高)
"base_success_rate": 0.1, # 成功率 (非常低)
"target_realm": "筑基2层" # 成功后的境界 (奖励更高！)
}
},
"筑基10层": {
"path_pill": {
"name": "丹药突破",
"required_item_id": 102, # 物品ID (金元丹)
"required_item_name": "金元丹",
"cultivation_cost": 50000,
"base_success_rate": 0.2,
"target_realm": "金丹1层"
},
"path_hard": {
"name": "强行突破",
"cultivation_cost": 200000,
"base_success_rate": 0.05,
"target_realm": "金丹2层"
}
}
# ... 更多境界
}
```
## 5\. 🚀 核心系统设计
### 5.1. Redis 集成 (性能 & 防封)
1. **玩家数据缓存 (Cache-Aside):**
* **Key:** `xiuxian:cache:player:{user_id}`
* **Value:** `t_xiuxian_player` 数据的 JSON 序列化。
* **读取:** 99% 的指令（如 `/我的状态`, `/劫掠` 检查）**必须**先读 Redis。
* **写入:** 所有修改 `Player` 数据的操作（如 `/出关`），在写入 **MariaDB** 成功后，**必须** `DEL` 对应的 Redis 缓存键 (`...player:{user_id}`)，实现“写后失效”。
2. **指令冷却 (Rate Limiting) - 防封核心:**
* **Key:** `xiuxian:rate_limit:user:{user_id}:cmd:{command_name}`
* **逻辑:** 在执行**任何**指令前，检查此 Key。如果存在，静默失败或回复“操作过于频繁”。如果不存在，执行指令，并 `SET` 此 Key，设置 `EXPIRE`。
* *（ cooldown 时间见下方指令清单）*
3. **排行榜 (Leaderboard):**
* **Key:** `xiuxian:zset:leaderboard:realm` (Sorted Set)
* **逻辑:** 玩家 `/突破` 成功时，更新其 `Score` (可用境界等级量化)。
### 5.2. 玩家状态机 (防骚扰核心)
这是 `t_xiuxian_player.status` 字段的流转设计，用于平衡 PVP 和 PVE。
| 状态 | 描述 | 能否被劫掠? | 能否 `/闭关`? |
| :--- | :--- | :--- | :--- |
| **`Idle`** (空闲) | 默认状态。 | ✅ **是** (危险) | ✅ **是** |
| **`Cultivating`** (闭关中)| `/闭关` 后进入。 | ❌ **否** (安全) | ❌ 否 |
| **`Unstable_Qi`** (气息不稳)| `/出关` 后进入，持续15分钟。 | ✅ **是** (强制暴露) | ❌ **否** (强制CD) |
| **`Injured`** (受伤中) | 被 `/劫掠` 成功后进入，持续1小时。| ❌ **否** (PVP保护) | ✅ **是** |
**状态自动流转 (重要)：**
所有指令在执行前，都必须调用一个 `check_status_update(user_id)` 函数。
此函数检查玩家 `status` 是否为 `Unstable_Qi` 或 `Injured`，并检查 `status_until` 是否已过期。如果已过期，自动将其 `status` 改回 `Idle` (并更新DB和缓存)。
### 5.3. 玩家PVE循环 (成长)
* **`/注册修仙 [道号]`**
1. 检查 `user_id` 是否已存在。
2. 根据 `SPIRIT_ROOT_CONFIG` 的**权重**，为玩家随机抽取一个 `spirit_root`。
3. `INSERT` 到 `t_xiuxian_player`。
4. 回复："一道灵光注入你的体内...经检测，你的灵根为：**【天灵根】**！"
* **`/闭关`**
1. 调用 `check_status_update()`。
2. 检查 `status` 必须是 `Idle` 或 `Injured`。
3. `UPDATE Player SET status='Cultivating', last_cultivate_time=now()`。
4. 回复："你已进入闭关，修行期间无法被劫掠。"
* **`/出关`**
1. 检查 `status` 必须是 `Cultivating`。
2. **[平衡点1]** `duration = min(now() - last_cultivate_time, 8 hours)` (8小时收益上限)。
3. **[平衡点2]** `rate = BASE_CULTIVATION_RATE * spirit_root_multiplier` (灵根加成)。
4. `total_gain = duration * rate`。
5. **[平衡点3]** `UPDATE Player SET cultivation_points += total_gain, status='Unstable_Qi', status_until=now()+15 minutes`。
6. 回复："你结束了闭关，获得了 X 点修为。你刚出关气息不稳，15分钟内无法再次闭关。"
* **`/聚灵 [数量]`**
1. 检查 `spirit_stone` (灵石) 是否 \> `[数量]`。
2. `UPDATE Player SET spirit_stone -= [数量], cultivation_points += ([数量] * 10)` (比例可调)。
* **`/突破` (丹药路径)**
1. 从 `BREAKTHROUGH_CONFIG` 获取当前 `realm` 的 `path_pill` 配置。
2. 检查 `cultivation_points` 和 `背包` (是否有 `required_item_id`)。
3. (不满足) 回复："丹药突破需：[筑基丹]x1, 修为x5000。你条件不足。"
4. (满足) 扣除资源。Roll点 (按 `base_success_rate`)。
5. (成功) `UPDATE Player SET realm = '筑基1层'`。回复："【突破成功！】..."
6. (失败) 回复："【突破失败！】..."
* **`/强行突破` (无丹药路径)**
1. 从 `BREAKTHROUGH_CONFIG` 获取 `path_hard` 配置。
2. 检查 `cultivation_points`。
3. (不满足) 回复："强行突破需：修为x20000。你条件不足。"
4. (满足) 扣除修为。Roll点 (按 `base_success_rate`)。
5. (成功) `UPDATE Player SET realm = '筑基2层'`。回复："【天道酬勤！】你强行突破成功，直达 **筑基2层**！"
6. (失败) 回复："【突破失败！】灵气反噬，你身受重伤！" (可选惩罚：`status` -\> `Injured`)
### 5.4. 经济与PVP/GvG循环
* **`/签到`**
* (对接你的积分系统) 奖励 `spirit_stone`。
* **`/坊市`, `/购买`, `/背包`**
* 常规的 `Item` 和 `Inventory` 表的 `CRUD` 操作。
* **`/劫掠 @某人`**
1. (调用 `check_status_update()` 检查自己和目标的状态)。
2. **[保护1]** 检查目标 `realm` (例如：必须 "筑基" 以上，新手保护)。
3. **[保护2]** 检查目标 `status` (必须是 `Idle` 或 `Unstable_Qi`)。
4. **[保护3]** 检查 `clan_id` (双方 `clan_id` 相同且不为 `NULL` 则禁止同门相残)。
5. (通过) 判定：根据双方 `realm` 计算成功率。
6. (成功) 转移 `spirit_stone`。`UPDATE Target SET status='Injured', status_until=now()+1 hour`。
* **`/赠与 @某人 [数量]` (灵石)**
1. **限制：** 双方 `clan_id` 必须相同且不为 `NULL`。
2. **操作：** 转移 `t_xiuxian_player.spirit_stone`。
* **`/赠送 @某人 [物品] [数量]` (丹药/物品)**
1. **限制：** 无限制（自由交易）。
2. **操作：** 转移 `t_xiuxian_inventory` 记录 (**必须使用数据库事务**)。
* **`/创建门派`, `/加入门派`, `/退出门派`**
* 常规的 `Clan` 表和 `Player.clan_id` 的 `CRUD` 操作。
-----
## 6\. 📋 最终指令清单 (附防封冷却)
| 类别 | 指令 | 冷却 (建议) | 备注 |
| :--- | :--- | :--- | :--- |
| **核心** | `/注册修仙 [道号]` | 1次/天 | 随机灵根 |
| | `/我的状态` | 5 秒 | 显示核心数据 (含灵根) |
| **修行** | `/闭关` | 10 秒 | `status` -\> `Cultivating` (安全) |
| | `/出关` | 10 秒 | 结算修为 (8h上限)。`status` -\> `Unstable_Qi` (危险) |
| | `/聚灵 [数量]` | 30 秒 | (消耗灵石) 灵石 -\> 修为 |
| **突破** | `/突破` | 60 秒 | **[简化]** 丹药路径 (稳妥) |
| | `/强行突破` | 60 秒 | **[简化]** 无丹药路径 (高风险高回报) |
| **经济** | `/签到` | 1次/天 | 获得灵石 |
| | `/坊市` | 10 秒 | 查看商店 |
| | `/购买 [物品] [数量]`| 5 秒 | 灵石 -\> 物品 |
| | `/背包` | 5 秒 | 查看物品 |
| **社交** | `/劫掠 @某人` | 30 秒 | 抢夺灵石 (PVP) |
| | `/赠与 @某人 [数量]` | 10 秒 | **(同门)** 赠送灵石 |
| | `/赠送 @某人 [物品] [数量]`| 10 秒 | **(自由)** 赠送物品/丹药 |
| **门派** | `/创建门派 [名称]` | 1次/天 | |
| | `/加入门派 [名称]` | 1次/周 | |
| | `/退出门派` | 1次/周 | |
| **信息** | `/排行榜` | 60 秒 | 从 Redis 读取 |
-----
## 7\. 🛣️ 建议的开发路线图
1. **Step 1: 基础建设 (V0.1)**
* 搭建数据库 (4个表)。
* 创建 `Config` 文件 (灵根, 突破)。
* 实现 Redis 缓存 `Player` 数据的 `getter/setter`。
2. **Step 2: PVE 核心循环 (V0.5)**
* 实现 `/注册修仙`, `/我的状态`。
* 实现 `/闭关`, `/出关` (包含灵根加成 和 8小时上限)。
* 实现 `check_status_update()` 函数和 `Unstable_Qi` 状态流转。
3. **Step 3: 经济与突破 (V0.8)**
* 实现 `/坊市`, `/购买`, `/背包`。
* 实现 `/聚灵`。
* 实现 `/突破` 和 `/强行突破` (双轨制)。
4. **Step 4: PVP 与社交 (V1.0)**
* 对接 `/签到` 和 `/劫掠` (包含所有保护机制)。
* 实现 `/创建门派`, `/加入门派`。
* 实现 `/赠与` (灵石) 和 `/赠送` (物品)。
5. **Step 5: 优化 (V1.1)**
* 实现所有指令的 Redis 冷却 (防封)。
* 实现 `/排行榜` (Redis Sorted Set)。