راهنمای استفاده
پلاگین‌ها
سیستم پلاگین WZML-X؛ مدیریت با دستور /plugins، نصب از zip، GitHub یا Marketplace، متغیرهای DISABLE_PLUGINS و PLUGIN_INDEXES و پلاگین‌های همراه ربات.
پلاگین‌ها دستورهای تازه‌ای به ربات اضافه می‌کنند، بدون اینکه کد اصلی را تغییر دهید. هر پلاگین یک پوشه در plugins/ است که یک فایل مشخصات به نام wzml_plugin.yml و یک یا چند فایل پایتون دارد. مدیریت پلاگین‌ها از داخل تلگرام و با دستور /plugins انجام می‌شود و فعال یا غیرفعال کردن آن‌ها ری‌استارت نمی‌خواهد.
دستور /plugins
/plugins برای مالک ربات و کاربران سودو فعال است. صفحهٔ اول خلاصه‌ای نشان می‌دهد (تعداد نصب‌شده، فعال، غیرفعال، بارگذاری‌نشده و مسیر پوشهٔ پلاگین‌ها) و این دکمه‌ها را دارد:
| دکمه | کار |
|---|---|
Installed (N) | فهرست پلاگین‌ها. رنگ دکمه وضعیت را نشان می‌دهد. |
Marketplace | فهرست پلاگین‌های قابل نصب از فایل‌های ایندکس. |
Install | نصب از فایل zip یا از GitHub (فقط برای سودوها و مالک نمایش داده می‌شود). |
Close | بستن منو |
وضعیت‌ها
| رنگ دکمه | وضعیت | معنی |
|---|---|---|
| سبز | Enabled | در حافظه است و دستورهایش کار می‌کنند. |
| قرمز | Disabled | در حافظه است اما دستورهایش خاموش‌اند. |
| ساده | Not Loaded | فایل‌هایش روی دیسک است ولی بارگذاری نشده. |
چه کسی چه کاری می‌تواند بکند؟
- مالک ربات: فعال و غیرفعال کردن، حذف (uninstall)، به‌روزرسانی،
Rescan، تأیید نصب وابستگی‌ها و تغییر تنظیمات پلاگین. - سودوها: مرور فهرست‌ها و نصب پلاگین جدید. اگر سودو بخواهد پلاگین موجود را تغییر دهد، پیام
Only the owner can change plugins.را می‌گیرد.
کارهایی که روی هر پلاگین می‌شود کرد
- فعال/غیرفعال: غیرفعال کردن فقط دستورهای پلاگین را جدا می‌کند و کد در حافظه می‌ماند، پس فعال کردن دوباره فوری است. انتخاب شما در پایگاه داده ذخیره می‌شود و بعد از ری‌استارت هم باقی می‌ماند.
Rescan: پوشه‌هایی را که در حین اجرای ربات بهplugins/اضافه کرده‌اید پیدا و بارگذاری می‌کند.- به‌روزرسانی: اگر پلاگین از GitHub، Marketplace یا یک URL نصب شده باشد، دوباره از همان منبع گرفته می‌شود؛ پلاگین‌های همراه ربات یا دستی کپی‌شده از مخزن و شاخهٔ
UPSTREAM_REPOوUPSTREAM_BRANCHگرفته می‌شوند. - حذف: دستورها جدا، فایل‌ها پاک و رکورد پایگاه داده حذف می‌شود.
Settings: اگر پلاگین تنظیماتی تعریف کرده باشد، از این دکمه ویرایش می‌شود. مقادیر برای هر ربات جداگانه در پایگاه داده ذخیره می‌شوند.
نصب پلاگین
از /plugins ← Install سه راه دارید:
Upload a .zip: فایل zip پوشهٔ پلاگین را بفرستید. هم zip شامل خود فایل‌ها و هم zip شامل یک پوشه با نام پلاگین پذیرفته می‌شود.From GitHub: یکی از این‌ها را بفرستید:owner/repo،owner/repo@branchیا آدرس کامل GitHub. ربات همهٔ پوشه‌های پلاگین داخل مخزن را پیدا می‌کند و فهرستشان را نشان می‌دهد؛ سبز یعنی هنوز نصب نشده و آبی یعنی قبلاً دارید.Marketplace: از فهرست ایندکس‌ها انتخاب کنید.
محدودیت‌های فایل فشرده: حداکثر ۱۶ مگابایت فشرده، ۴۸ مگابایت پس از باز شدن و ۵۱۲ فایل. اگر پلاگین بستهٔ پایتونی لازم داشته باشد که نصب نیست، ربات فهرست آن‌ها را نشان می‌دهد و فقط با تأیید مالک آن‌ها را نصب می‌کند.
Marketplace و PLUGIN_INDEXES
Marketplace فهرستش را از فایل‌های ایندکس JSON می‌خواند. ایندکس رسمی از مخزن بالادستی شما و با این الگو خوانده می‌شود: https://raw.githubusercontent.com/<UPSTREAM_REPO>/<UPSTREAM_BRANCH>/plugins/index.json.
اگر UPSTREAM_REPO خالی باشد یا آدرس GitHub نباشد، مخزن SilentDemonSD/WZML-X استفاده می‌شود. آدرس دقیقی که ربات استفاده می‌کند در صفحهٔ Marketplace نمایش داده می‌شود. فایل plugins/index.json مخزن همین فهرست را برای پلاگین‌های همراه ربات نگه می‌دارد.
PLUGIN_INDEXES (مرجع متغیرها) فقط برای ایندکس‌های اضافه است. یک فهرست از آدرس‌ها بدهید؛ هر آدرس باید به یک فایل JSON اشاره کند که فهرستی به نام plugins دارد:
PLUGIN_INDEXES = ["https://example.com/my-plugins/index.json"]DISABLE_PLUGINS
با روشن کردن DISABLE_PLUGINS (در /bsetting ← Module Settings ← On/Off Settings، دکمهٔ PLUGINS؛ نگاه کنید به تنظیمات ربات)، همهٔ پلاگین‌ها همان لحظه از حافظه خارج می‌شوند، هنگام شروع ربات هم بارگذاری نمی‌شوند و هر تغییری در /plugins با پیام Plugins are switched off in Module Settings. رد می‌شود. با خاموش کردن دوباره‌اش، پلاگین‌ها بدون ری‌استارت برمی‌گردند.
پلاگین‌های همراه ربات
این هفت پلاگین همراه ربات می‌آیند. اگر برای پلاگینی هنوز رکوردی در پایگاه داده نباشد، فعال شروع می‌شود. وابستگی‌های پایتونی آن‌ها در requirements.txt پروژه هم آمده است.
| پلاگین | دستورها | دسترسی | چه می‌کند |
|---|---|---|---|
anilist | /anime (یا /anilist)، /character، /manga، /animehelp | کاربران مجاز | جست‌وجوی انیمه، شخصیت و مانگا در AniList. تنظیمات: anime_template (قالب HTML کپشن) و description_limit (طول خلاصه، پیش‌فرض 500). |
imdb | /imdb | کاربران مجاز | جست‌وجوی عنوان یا شناسهٔ tt… در IMDB و فرستادن یک کارت اطلاعات. اگر IMDB_TEMPLATE خالی باشد از پیام‌های Rich استفاده می‌کند، وگرنه از قالب HTML شما. |
mediainfo | /mediainfo (یا /mi) | کاربران مجاز | با ریپلای روی یک فایل یا با یک لینک مستقیم، اطلاعات MediaInfo را در یک صفحهٔ Telegraph نشان می‌دهد. |
mydramalist | /mdl (یا /mydramalist) | کاربران مجاز | جست‌وجوی سریال و فیلم در MyDramaList و انتخاب از نتایج. تنظیمات: template، synopsis_limit (پیش‌فرض 300) و results (تعداد نتایج، پیش‌فرض 8). |
nzb_search | /nzbsearch (یا /ns) | کاربران مجاز | جست‌وجو در ایندکسرهای Usenet از طریق NZBHydra؛ به HYDRA_IP و HYDRA_API_KEY نیاز دارد و وقتی DISABLE_NZB روشن است کار نمی‌کند. |
speedtest | /speedtest (یا /spt) | کاربران مجاز | اندازه‌گیری سرعت اینترنت سرور. |
gen_pyro_sess | /exportsession | سودو | ساختن استرینگ سشن Pyrogram قدم‌به‌قدم؛ فقط در چت خصوصی. |
دربارهٔ /exportsession
این پلاگین راه داخل تلگرامِ ساختن USER_SESSION_STRING است:
- در چت خصوصی با ربات
/exportsessionرا بفرستید. - اگر
TELEGRAM_APIوTELEGRAM_HASHدر پیکربندی ربات باشند، از همان‌ها استفاده می‌شود؛ وگرنه ربات آن‌ها را می‌پرسد. - شمارهٔ تلفن را با کد کشور بفرستید و با
yتأیید کنید. - کدی را که تلگرام فرستاده با فاصله بین رقم‌ها بفرستید (مثلاً
1 2 3 4 5). اگر حساب تأیید دومرحله‌ای دارد، رمز آن را هم می‌پرسد. - استرینگ سشن در Saved Messages همان حساب فرستاده می‌شود.
هر مرحله ۱۲۰ ثانیه مهلت دارد و با دکمهٔ Cancel Process می‌توانید کار را لغو کنید.
نوشتن پلاگین
یک پلاگین ساده دو فایل دارد. نام پوشه باید با name در فایل مشخصات یکی باشد:
# plugins/hello/wzml_plugin.yml
name: hello
version: "1.0.0"
author: You
description: Say hello
entry: hello.py
commands:
- name: hello
handler: hello_command
description: Say hello
access: authorized# plugins/hello/hello.py
from bot.helper.ext_utils.bot_utils import new_task
from bot.helper.telegram_helper.message_utils import send_message
@new_task
async def hello_command(_, message):
await send_message(message, "<b>Hello!</b>")بعد از Rescan در /plugins ← Installed (یا ری‌استارت)، دستور /hello کار می‌کند و در /help هم نمایش داده می‌شود (فهرست دستورهای اصلی در دستورات). مقدار access می‌تواند authorized، sudo، owner یا authorized_uset باشد و CMD_SUFFIX خودکار به نام دستورهای پلاگین هم اضافه می‌شود.
مرجع کامل فایل مشخصات، چرخهٔ عمر، تنظیمات و قالب ایندکس در فایل plugins/README.md مخزن آمده است.