abot/plugins/xiuxian

好的，我将把我们讨论过的所有细节，包括灵根类型、双轨制突破、所有保护机制、数据库设计、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)

• 描述： 成功渡过天劫，飞升上界。
• (游戏终点或新篇章起点)

---

📖 玩家用户手册（如何玩）

快速开始

• 注册角色：发送 注册修仙 道号
• 查看状态：发送 我的状态
• 开始修炼：发送 闭关（进入闭关状态，安全不可被劫掠）
• 结束修炼：适时发送 出关（获得修为，进入“气息不稳”短暂状态）
• 聚灵提升：发送 聚灵 数量（消耗灵石，提升修为）
• 查看帮助：发送 修仙帮助（或 帮助、help、修仙指令、指令）

日常玩法

• 签到领石：修仙签到（每日一次，获得灵石）
• 坊市购物：
  • 查看商品：坊市
  • 购买物品：购买 物品名称 数量
  • 查看背包：乾坤袋
• 积分兑换灵石：积分购石 积分数
  • 比例：10 积分 = 1 灵石
  • 示例：积分购石 100 → 获得 10 灵石

境界与修炼

• 境界层数：每个境界均为 1–10 层，达到 10 层为瓶颈（如 炼气10层）
• 自动层提升：修为达到阈值自动提升层数（不跨瓶颈）。不同境界阈值不同：
  • 炼气：每层约需 1000 修为
  • 筑基：每层约需 5000 修为
  • 金丹：每层约需 50000 修为
• 突破瓶颈：当到达 当前境界10层 可发起突破：
  • 丹药突破：突破（需丹药，如 筑基丹，成功率较高、修为消耗较低）
  • 强行突破：强行突破（不需丹药，成功率较低、修为消耗较高）
  • 成功则进入下一境界；失败则保留当前境界与修为变动

门派系统

• 创建门派：创建门派 名称（元婴期及以上）
• 加入门派：加入门派 名称
• 退出门派：退出门派
• 同门规则：仅同门可 赠与 灵石、赠送 物品；不可劫掠同门

PVP 劫掠

• 发起劫掠：劫掠 目标wxid
• 限制与保护：
  • 新手保护：炼气期目标不可劫掠
  • 状态保护：闭关或受伤保护中不可被劫掠
  • 群限制：仅限同一群内劫掠
  • 门派限制：不可劫掠同门
• 结果：成功夺取对方约 20% 灵石，对方进入 受伤保护；失败无收益

排行榜

• 修为榜：排行榜（Top10）；可能开启境界分值榜（按境界映射分加层数）

冷却与撤回

• 指令独立冷却（如 闭关/出关≈5s、聚灵≈30s、突破≈60s）
• 消息自动撤回：错误提示≈5s，成功提示≈10s，列表展示≈20–30s

常用示例

• 注册：注册修仙 张三；状态：我的状态
• 闭关/出关：闭关 → 出关
• 聚灵：聚灵 10
• 坊市：坊市 → 购买 筑基丹 1 → 乾坤袋
• 积分换石：积分购石 100（得 10 灵石）
• 突破：突破（需 筑基丹）或 强行突破
• 赠与：赠与 @wxid_xxx 50；赠送：赠送 @wxid_xxx 筑基丹 1
• 劫掠：劫掠 @wxid_xxx
• 门派：创建门派 凌霄阁、加入门派 凌霄阁、退出门派
• 排行：排行榜

常见问题

• “未注册”：先发送 注册修仙 道号
• “命令格式错误”：参考 修仙帮助 用法提示
• 积分不足/灵石不足：指令会提示当前剩余或不足原因
• 未到瓶颈：请先提升到 当前境界10层
• 强行突破失败：属正常设定，建议用丹药或补足修为

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 (玩家核心表)

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 (门派表)

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 (物品表 - 静态)

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 (玩家背包表)

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)

用于 /注册修仙 和 /出关。

# 灵根名称: (出现权重, 修为加成乘数)
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)

用于 /突破 和 /强行突破。这是双轨制设计的核心。

# 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)。