نسخه ۰.۱.۰ — ۹۸ تست پاس‌شده

ربات بله بساز.
بدون محدودیت.

فریمورک همه کاره، async و AI-Native برای بله. از کسی که کد بلد نیست تا مهندسی که به RPC خام نیاز دارد — سه لایه دسترسی، همه باز.

۹۸تست پاس
۶۲صادرات
۷۶ماژول
۳لایه دسترسی
MITمجوز

نصب

Python 3.9 یا بالاتر. بدون وابستگی سنگین.

# از PyPI
pip install badking

# یا با uv (سریع‌تر)
uv pip install badking

# یا آخرین نسخه توسعه
pip install git+https://github.com/badking-daniyal/badking.git
بدون توکن هم تست می‌شود: python examples/echo_bot.py --mock — ربات را در حالت شبیه‌سازی اجرا می‌کند، بدون نیاز به @botfather.

شروع در ۵ دقیقه

توکن را از @botfather در بله بگیر. بدون لاگین شماره، بدون session file.

import asyncio
from badking import Bot, Dispatcher, F

bot = Bot("123456789:TOKEN_FROM_BOTFATHER")
dp = Dispatcher()

@dp.message(F.text == "/start")
async def start(message, bot):
    await bot.send_message(message.chat.id, "خوش آمدی! 🚀")

@dp.message(F.text)
async def echo(message, bot):
    await bot.send_message(message.chat.id, f"شما گفتید: {message.text}")

asyncio.run(bot.polling(dp))

همین. پارامتر bot خودکار تزریق می‌شود — لازم نیست دستی پاس بدهی.

نمونه‌های واقعی

هر نمونه کد کامل و قابل اجراست، نه شبه‌کد.

۱. ویزارد چندمرحله‌ای

پرسش‌وپاسخ خطی بدون دست‌وپنجه نرم کردن با FSM:

from badking import Bot, Dispatcher, F, ConversationManager

bot = Bot("TOKEN")
dp = Dispatcher()
convos = ConversationManager()
dp.register_middleware(convos)

@dp.message(F.text == "/register")
async def register(message, bot):
    async with convos.conversation(bot, message.chat.id) as conv:
        await conv.send("اسم کاملت چیه؟")
        name = await conv.get_response(timeout=60)

        await conv.send("شماره تماس؟")
        phone = await conv.get_response(timeout=60)

        await conv.send(f"ثبت شد ✅\nنام: {name.text}\nتلفن: {phone.text}")

اگر کاربر جواب ندهد ConversationTimeout می‌گیری. اگر چت دیگری پیام بدهد، مزاحم مکالمه نمی‌شود.

۲. منوی چندصفحه‌ای

from badking import KeyboardPaginator, F

products = ["کتاب پایتون", "هدفون", "ماوس", "کیبورد", "مانیتور"]
paginator = KeyboardPaginator(products, per_page=3, prefix="shop")

@dp.message(F.text == "/shop")
async def shop(message, bot):
    await bot.send_message(
        message.chat.id, "محصولی انتخاب کن:",
        reply_markup=paginator.markup(page=0).model_dump(exclude_none=True),
    )

@dp.callback_query(F.data.startswith("shop:"))
async def on_shop(cq, bot):
    parsed = paginator.parse(cq.data)
    if not parsed:
        return
    kind, value = parsed
    if kind == "page":
        await bot.edit_message_text(
            cq.message.chat.id, cq.message.message_id, "محصولی انتخاب کن:",
            reply_markup=paginator.markup(page=value).model_dump(exclude_none=True),
        )
    elif kind == "item":
        await bot.answer_callback_query(cq.id, f"انتخاب شد: {products[value]}")

دکمه‌های «قبلی / بعدی» و شماره صفحه خودکار ساخته می‌شوند.

۳. FSM پایدار با SQLite

from badking import Bot, Dispatcher, F, State, StatesGroup, SQLiteStorage

class Order(StatesGroup):
    item = State()
    address = State()

dp = Dispatcher(storage=SQLiteStorage("orders.db"))
bot = Bot("TOKEN")

@dp.message(F.text == "/order")
async def start_order(message, state):
    await state.set_state(Order.item)
    await bot.send_message(message.chat.id, "چه چیزی می‌خواهی؟")

@dp.message(Order.item)
async def get_item(message, state):
    await state.update_data(item=message.text)
    await state.set_state(Order.address)
    await bot.send_message(message.chat.id, "آدرس تحویل؟")

@dp.message(Order.address)
async def get_address(message, state):
    data = await state.get_data()
    await state.clear()
    await bot.send_message(
        message.chat.id,
        f"سفارش ثبت شد ✅\nکالا: {data['item']}\nآدرس: {message.text}",
    )

ربات را ری‌استارت کن — state سر جایش است.

۴. دستیار هوشمند با ابزار

from badking import AIAssistant, OpenAICompatibleLLM

llm = OpenAICompatibleLLM(
    base_url="https://api.openai.com/v1",
    api_key="sk-...",
    model="gpt-4o-mini",
)

assistant = AIAssistant(
    llm,
    persona="دستیار فروشگاه، مودب و کوتاه جواب بده",
    tools=[check_order_status, get_price],
)

answer = await assistant.reply(user_key=str(message.from_user.id), text=message.text)
await bot.send_message(message.chat.id, answer)

مدل خودش تصمیم می‌گیرد کدام ابزار را صدا بزند. اگر ابزار خطا بدهد، کل مکالمه نمی‌شکند.

۵. RAG روی مستندات خودت

from badking import SimpleRAG, AIAssistant, OpenAICompatibleLLM

rag = SimpleRAG()
rag.add_text(open("faq.txt", encoding="utf-8").read(), source="faq")
rag.add_text(open("policies.txt", encoding="utf-8").read(), source="policies")

assistant = AIAssistant(OpenAICompatibleLLM(...), rag=rag)

ربات از محتوای فایل‌های تو جواب می‌دهد، نه از خودش.

۶. اتصال به هر سرویس خارجی

from badking import Connector, Auth

zarinpal = Connector(
    base_url="https://api.zarinpal.com",
    auth=Auth(type="bearer", token="..."),
    retries=3,
)

result = await zarinpal.post("/pg/v4/payment/request.json", json_body={
    "merchant_id": "....",
    "amount": 50000,
    "callback_url": "https://example.com/callback",
})

Retry خودکار روی 5xx و 429، با احترام به Retry-After.

۷. پرداخت داخل بله

from badking import PaymentToolkit

pay = PaymentToolkit(bot)

await pay.send_invoice(
    chat_id=message.chat.id,
    title="کتاب پایتون",
    description="نسخه چاپی، ارسال رایگان",
    payload="order-1234",
    provider_token="...",
    prices=[{"label": "کتاب", "amount": 500000}],
)

۸. مینی‌اپ با اعتبارسنجی امن

from badking import validate_init_data

# در سرور مینی‌اپ، initData را از کلاینت بگیر
data = validate_init_data(init_data_from_client, bot_token="123456:ABC...")
print(data.user.id, data.user.first_name)   # امضا تأیید شد

الگوریتم دقیقاً مطابق مستندات رسمی بله: فیلدها الفبایی مرتب، با \n متصل، HMAC-SHA256.

سه لایه دسترسی

هر لایه برای یک مخاطب. لایه پایین‌تر همیشه باز است.

لایهمخاطبابزار
۰ — بدون کدصاحب کسب‌وکارFlow Builder، CLI، dry-run
۱ — پایتونبرنامه‌نویسDispatcher، FSM، Filter، AI، Connector، Conversation
۲ — خاممهندسbot.request("anyMethod", {...}) — هر متد، هر JSON
قانون: هر کاری لایه ۱ می‌کند، لایه ۲ هم می‌کند. چیزی پنهان نیست.

ربات بدون نوشتن کد

برای کسی که پایتون نمی‌داند ولی ربات می‌خواهد.

badking new mybot       # ساخت پروژه کامل
badking dry-run         # تست جریان بدون توکن
badking codegen         # تبدیل flow.json به کد پایتون
badking setup           # تنظیم توکن
badking run             # اجرا

flow.json را با Notepad ویرایش کن:

{
  "start": "welcome",
  "steps": {
    "welcome": {"type": "message", "text": "سلام! 👋", "next": "ask_name"},
    "ask_name": {"type": "ask", "text": "اسمت چیه؟", "save": "name", "next": "done"},
    "done": {"type": "message", "text": "خوش آمدی {name}!"}
  }
}

بدون یک خط پایتون، یک ربات مکالمه‌ای داری. وقتی بزرگ شد، badking codegen همان جریان را به کد تبدیل می‌کند.

مقایسه با aiobale

صادقانه، بدون اغراق.

قابلیتaiobaleBADKING
توکن رسمی @botfather✗✓
Self-bot / Internal API✓✓ ایزوله، پیش‌فرض خاموش
FSM + SQLite✓✓
Conversation (ویزارد)✓✓
KeyboardPaginator✓✓
Magic Filter F✓✓
Middleware + Rate Limit✓✓
Webhook Server✓✓
MiniApp + HMAC✗✓
سفیر (OTP، قالب)✗✓
پرداخت فاکتور رسمی✗✓
Business API✗✓
AI: Tool Calling + RAG✗✓
بدون‌کد (Flow Builder)✗✓
Connector به هر API✗✓
Observability (Prometheus)✗✓
Docker + CI آماده✗✓
مستندات فارسی✗✓

ساختار پروژه

۷۶ ماژول، هر کدام یک مسئولیت.

badking/
├── core/           Bot، Dispatcher، Router، خطاها
├── types/          مدل‌های Pydantic
├── filters/        Magic Filter F
├── fsm/            State، StatesGroup، FSMContext
├── storage/        Memory، SQLite
├── conversation/   ویزارد پرسش‌وپاسخ
├── keyboards/      KeyboardPaginator
├── miniapp/        اعتبارسنجی HMAC initData
├── safir/          سرویس سفیر (OTP، قالب)
├── payments/       فاکتور و پرداخت
├── business/       Business API
├── ai/             LLM، حافظه، RAG، دستیار
├── flows/          Flow Builder بدون کد
├── connectors/     HTTP به هر سرویس
├── jobs/           Scheduler، JobQueue
├── events/         Event Bus
├── orm/            Store
├── media/          Voice، OCR
├── observability/  Metrics، لاگ JSON
├── security/       AntiSpam، AuditLog، RBAC، Secrets
├── testing/        DryBot، Health
├── middleware/     logging، metrics، antispam
├── ratelimit/      Rate Limiter با اولویت
├── recovery/       Offset Store اتمیک
├── adapters/       Multi-platform
├── compat/         سازگاری aiogram/PTB
└── hybrid/         Self-bot (ایزوله، پیش‌فرض خاموش)

مرز صادقانه

این‌ها را باید بدانی، نه اینکه بعداً کشف کنی.

هر کاری API رسمی بله ندهد، با توکن رسمی از هیچ کتابخانه‌ای برنمی‌آید. نه BADKING، نه aiobale، نه هیچ‌کس دیگر. این محدودیت بله است، نه کتابخانه.

تاریخچه پیام‌ها

iter_messages ما آپدیت‌های موجود را می‌پیماید. تاریخچه کامل و قدیمی‌تر از ۲۴ ساعت با توکن رسمی ممکن نیست — برای آن لایه hybrid لازم است.

ریسک self-bot

لایه hybrid پیش‌فرض خاموش است و بدون ack_risk=True فعال نمی‌شود. دلیلش: Internal API غیررسمی است، می‌شکند، و می‌تواند اکانت شخصی‌ات را ببندد.

اعداد تأییدنشده

اعدادی مثل «۴۰۹۶ کاراکتر» یا «حذف تا ۴۸ ساعت» در مستندات رسمی بله نیامده‌اند. در BADKING پیش‌فرض قابل‌تنظیم‌اند و از retry_after واقعی سرور یاد می‌گیرند.

RPC داخلی self-bot

پیاده‌سازی کامل ۸۰+ متد RPC داخلی هنوز انجام نشده. رابط و ایزولاسیون آماده است؛ خود RPC به‌عنوان پلاگین جداگانه منتشر می‌شود.

بیشتر

مستندات بله

خلاصه مستندات رسمی API بله، با نکات عملی.

نقشه راه

وضعیت فازها و آنچه در نسخه‌های بعدی می‌آید.

هشدار self-bot

چرا لایه hybrid ایزوله است و چه ریسکی دارد.

شروع سریع

راهنمای قدم‌به‌قدم فارسی برای اولین ربات.