obabot 用于 Telegram 和 Max 机器人

# obabot：Telegram 和 Max 机器人的通用库

obabot 库让你用单一的异步 Python 机器人代码同时部署到 Telegram 和 Max 平台。其 API 与 aiogram 3.x 完全兼容：Telegram 使用原生 aiogram，Max 通过适配器将事件转换为兼容对象。安装超简单，一行命令搞定：pip install obabot aiogram>=3.0.0 umaxbot>=0.1.7。

核心函数 create_bot() 接受平台令牌，返回 (bot, dispatcher, router) 元组。消息处理器编写统一，不受平台限制。

初始化示例

Telegram 示例：

from obabot import create_bot
from obabot.filters import Command

bot, dp, router = create_bot(tg_token="YOUR_TG_TOKEN")

@router.message(Command("start"))
async def start(message):
    await message.answer(f"来自 {message.platform} 的问候！")

await dp.start_polling(bot)

Max 示例：

from obabot import create_bot
from obabot.filters import Command

bot, dp, router = create_bot(max_token="YOUR_MAX_TOKEN")

@router.message(Command("start"))
async def start(message):
    await message.answer(f"来自 {message.platform} 的问候！")

await dp.start_polling(bot)

同时支持两个平台：

from obabot import create_bot
from obabot.filters import Command

bot, dp, router = create_bot(
    tg_token="YOUR_TG_TOKEN",
    max_token="YOUR_MAX_TOKEN"
)

@router.message(Command("start"))
async def start(message):
    await message.answer(f"来自 {message.platform} 的问候！")

await dp.start_polling(bot)

message.platform 属性返回 "telegram" 或 "max"，方便平台特定逻辑。

从 aiogram 迁移

从纯 aiogram 3.x 切换只需微调：替换导入并用 create_bot() 替代单独的 Bot、Dispatcher 和 Router。

原 aiogram 代码：

from aiogram import Bot, Dispatcher, Router
from aiogram.filters import Command
from aiogram.fsm.state import State, StatesGroup
from aiogram.fsm.context import FSMContext

bot = Bot(token="TOKEN")
dp = Dispatcher()
router = Router()
dp.include_router(router)

@router.message(Command("start"))
async def start(message):
    await message.answer("你好！")

await dp.start_polling(bot)

迁移后：

from obabot import create_bot
from obabot.filters import Command
from obabot.fsm import State, StatesGroup, FSMContext

bot, dp, router = create_bot(tg_token="TOKEN")

@router.message(Command("start"))
async def start(message):
    await message.answer("你好！")

await dp.start_polling(bot)

其余代码——包括 FSM、过滤器和键盘——完全不变。

Message 接口和基础方法

所有 Message 对象共享统一接口：

• message.text — 文本内容
• message.from_user — 发送者
• message.chat — 聊天
• message.message_id — 消息 ID
• message.platform — 平台

常用方法：

• await message.answer("回复")
• await message.reply("回复消息")
• await message.delete()
• await message.edit_text("新文本")

FSM：状态机

FSM 与 aiogram 完全一致：

from obabot.fsm import State, StatesGroup, FSMContext

class Form(StatesGroup):
    name = State()
    age = State()

@router.message(Command("start"))
async def start(message, state: FSMContext):
    await state.set_state(Form.name)
    await message.answer("你叫什么名字？")

@router.message(Form.name)
async def process_name(message, state: FSMContext):
    await state.update_data(name=message.text)
    await state.set_state(Form.age)
    await message.answer("你多大了？")

行内键盘和过滤器

创建键盘：

from obabot.types import InlineKeyboardMarkup, InlineKeyboardButton

keyboard = InlineKeyboardMarkup(inline_keyboard=[
    [
        InlineKeyboardButton(text="按钮1", callback_data="btn1"),
        InlineKeyboardButton(text="按钮2", callback_data="btn2"),
    ]
])

await message.answer("请选择：", reply_markup=keyboard)

过滤器：

• @router.message(Command("start", "help")) — 多命令
• @router.message(F.text.startswith("!")) — 前缀
• @router.message(F.photo) — 图片
• @router.callback_query(F.data == "click") — 回调

无令牌测试

test_mode=True 跳过所有网络调用：

bot, dp, router = create_bot(test_mode=True)

支持 Python 3.10–3.14，aiogram 3.0.0–3.24。完整单元测试覆盖。

核心优势

• 单一代码库：Telegram 和 Max 共用一套处理器，无需适配器。
• 完全兼容：100% aiogram 3.x API + platform 属性。
• FSM 和过滤器：完整支持状态、行内键盘、魔法过滤器 F。
• 轻松迁移：只需换 2 行导入和初始化。
• 测试友好：隔离模式，无 API 调用。

— Editorial Team