ساخت تحلیلگر شطرنج محلی با پایتون و Stockfish؛ بررسی حرفه‌ای بازی‌ها بدون اینترنت

بررسی و آنالیز بازی‌های شطرنج یکی از اصلی‌ترین روش‌ها برای پیشرفت در این ورزش فکری است. بسیاری از بازیکنان برای بررسی پوزیشن‌ها، پیدا کردن اشتباهات و کشف حرکات بهینه به پلتفرم‌های آنلاین وابسته‌اند. اما وابستگی به سرویس‌های ابری گاهی با محدودیت‌های دسترسی، قطعی اینترنت یا هزینه‌های اشتراک همراه است. توسعه‌دهندگان و علاقه‌مندان به برنامه‌نویسی می‌توانند با استفاده از زبان پایتون و موتور پردازشی قدرتمند Stockfish، یک سیستم تحلیلگر کاملاً محلی، سریع و رایگان روی سیستم خود راه‌اندازی کنند. در این مقاله یاد می‌گیرید چگونه با چند خط کد، فایل‌های ثبت بازی را بخوانید، پوزیشن‌ها را ارزیابی کنید و گزارش کاملی از کیفیت حرکات به دست آورید.

مسئله: نیاز به تحلیل آفلاین و دقیق بازی‌های شطرنج ذخیره شده

هنگامی که مسابقات محلی، آنلاین یا تمرینی خود را در قالب فایل‌های استاندارد PGN (Portable Game Notation) ذخیره می‌کنید، مرور تک‌تک حرکات به صورت دستی زمان‌بر است. از طرفی، ارسال مداوم فایل‌ها به سرویس‌های ابری همیشه مطلوب نیست. ما به ابزاری نیاز داریم که به‌صورت خودکار فایل PGN را پردازش کند، تخته شطرنج را در هر ثانیه از بازی بازسازی کند، موتور شطرنج را روی پوزیشن فعلی اعمال کند و امتیاز دقیق هر حرکت را بر حسب سانتی‌پاون (Centipawns) یا مات‌های آتی استخراج نماید. این ساختار محلی به شما اجازه می‌دهد حتی در زمان قطع ارتباط با اینترنت، کیفیت بازی خود را زیر ذره‌بین ببرید و برای تولید اسکریپت‌های پیچیده‌تر، مانند ابزارهایی که در مقالاتی مثل راهنمای ابزار Blackbox؛ تبدیل سریع متن به کد با هوش مصنوعی بررسی کردیم، آمادگی بهتری داشته باشید.

نصب کتابخانه‌ها و آماده‌سازی موتور Stockfish

برای اجرای این پروژه به کتابخانه رسمی مدیریت تخته و فایل‌های PGN در پایتون یعنی python-chess نیاز داریم. همچنین باید باینری موتور Stockfish را متناسب با سیستم‌عامل خود (ویندوز، لینوکس یا مک) دانلود کرده و مسیر آن را در دسترس اسکریپت قرار دهید. موتور استاک‌فیش به عنوان یک فرآیند مستقل (External Process) اجرا می‌شود و پایتون از طریق پروتکل UCI با آن ارتباط برقرار می‌کند.

برای نصب کتابخانه مورد نیاز، دستور زیر را در ترمینال سیستم خود اجرا کنید:

pip install python-chess

پس از اجرای دستور فوق، کتابخانه مدیریت شطرنج پایتون نصب می‌شود. حتماً فایل اجرایی Stockfish را از وب‌سایت رسمی آن دانلود کرده و در پوشه پروژه یا در مسیر متغیرهای سیستمی (PATH) قرار دهید تا اسکریپت بتواند به راحتی آن را فراخوانی کند.

کد کامل تحلیلگر شطرنج محلی

اسکریپت زیر یک فایل PGN فرضی را می‌خواند، تمام حرکات بازی را طی می‌کند، موتور Stockfish را روی هر پوزیشن اعمال کرده و امتیاز ارزیابی به همراه بهترین حرکت پیشنهادی را در ترمینال چاپ می‌کند. این کد کاملاً یکپارچه و اجرایی است.

import chess
import chess.pgn
import chess.engine
import io

# مسیر فایل باینری موتور استاک‌فیش (نام فایل یا مسیر کامل آن را جایگزین کنید)
STOCKFISH_PATH = "stockfish"

# متن نمونه بازی شطرنج در فرمت PGN برای تست سریع اسکریپت
SAMPLE_PGN = """
[Event "Casual Game"]
[Site "Localhost"]
[Date "2026.10.31"]
[Round "1"]
[White "Player One"]
[Black "Player Two"]
[Result "1-0"]

1. e4 e5 2. Nf3 Nc6 3. Bc4 Bc5 4. b4 Bxb4 5. c3 Ba5 6. d4 exd4 7. O-O dxc3 8. Qb3 Qf6 9. e5 Qg6 10. Nxc3 Nge7 11. Ba3 b5 12. Qxb5 Bxc3 13. Rac1 Ba5 14. Bxe7 Kxe7 15. Bd5 Rb8 16. Qc5+ Kd8 17. Bxc6 Bb6 18. Qa3 dxc6 19. Rfd1+ Bd7 20. e6 fxe6 21. Ne5 Qe8 22. Nxc6+ Kc8 23. Qa6+ Rb7 24. Rxd7 Qxd7 25. Nxa7+ Bxa7 26. Rd1 Qxd1+ 27. Qf1 Qxf1+ 28. Kxf1 1-0
"""

def analyze_chess_game(pgn_text, engine_path):
    # خواندن متن PGN با استفاده از کتابخانه io
    pgn_game = chess.pgn.read_game(io.StringIO(pgn_text.strip()))
    
    if pgn_game is None:
        print("خطا: فایل یا متن PGN نامعتبر است.")
        return

    board = pgn_game.board()
    
    # راه‌اندازی موتور شطرنج Stockfish
    try:
        engine = chess.engine.SimpleEngine.spawn(engine_path)
    except Exception as e:
        print(f"خطا در اجرای موتور استاک‌فیش: {e}")
        print("لطفاً مطمئن شوید موتور استاک‌فیش نصب شده و مسیر آن درست است.")
        return

    print("=" * 60)
    print(f"شروع تحلیل بازی: {pgn_game.headers.get('White', 'White')} در برابر {pgn_game.headers.get('Black', 'Black')}")
    print("=" * 60)

    move_counter = 1
    
    # پیمایش گام به گام روی حرکات بازی
    for node in pgn_game.mainline():
        move = node.move
        board.push(move)
        
        # ارزیابی پوزیشن فعلی توسط موتور با عمق مشخص (مثلاً عمق 12 برای سرعت مناسب)
        info = engine.analyse(board, chess.engine.Limit(depth=12))
        score = info["score"].white()
        
        # پیدا کردن بهترین حرکت پیشنهادی موتور در این پوزیشن
        best_move_result = engine.play(board, chess.engine.Limit(depth=10))
        best_move = best_move_result.move

        turn_str = "سفید" if board.turn == chess.BLACK else "سیاه"
        print(f"حرکت {move_counter}: انجام شده ({move}) | نوبت بعدی: {turn_str}")
        print(f"  امتیاز ارزیابی پوزیشن (بر حسب سانتی‌پاون): {score}")
        print(f"  بهترین حرکت جایگزین از نظر موتور: {best_move}")
        print("-" * 60)
        
        move_counter += 1

    # بستن ایمن اتصال موتور
    engine.quit()
    print("تحلیل بازی با موفقیت به پایان رسید.")

if __name__ == "__main__":
    analyze_chess_game(SAMPLE_PGN, STOCKFISH_PATH)

بررسی بخش به بخش منطق کد

برای درک عمیق‌تر نحوه‌ی کارکرد این اسکریپت، بخش‌های کلیدی آن را بررسی می‌کنیم:

• واردسازی ماژول‌ها: ما از chess برای ساختار تخته و قوانین، chess.pgn برای تحلیل فایل‌های بازی، و chess.engine برای ارتباط با هوش مصنوعی شطرنج استفاده کرده‌ایم. ماژول io نیز برای تبدیل رشته متنی PGN به یک شیء قابل خواندن توسط مفسر به کار رفته است.
• خوانش اطلاعات PGN: تابع chess.pgn.read_game متن بازی را تجزیه کرده و به یک درخت از حرکات تبدیل می‌کند. هدرهای بازی مثل نام بازیکنان نیز از طریق متد headers استخراج می‌شوند.
• ارتباط با موتور (UCI Protocol): خط chess.engine.SimpleEngine.spawn(engine_path) یک فرآیند زیرین ایجاد می‌کند که پایتون از طریق استاندارد ورودی و خروجی با استاک‌فیش صحبت می‌کند.
• حلقه ارزیابی حرکات: با متد board.push(move) تخته به روز می‌شود. سپس تابع engine.analyse پوزیشن را بررسی کرده و امتیاز را از دید بازیکن سفید (score.white()) بازمی‌گرداند. مثبت بودن امتیاز به معنای برتری سفید و منفی بودن نشانه برتری سیاه است.

نحوه اجرا و دریافت خروجی نمونه

برای اجرای این اسکریپت کافی است کد بالا را در فایلی با نام دلخواه (مثلاً chess_analyzer.py) ذخیره کنید و دستور زیر را در ترمینال کامپیوتر خود بنویسید:

python chess_analyzer.py

پس از اجرای موفقیت‌آمیز، خروجی متنی زیر در ترمینال نمایش داده خواهد شد که نشان‌دهنده ارزیابی لحظه‌به‌لحظه بازی است:

============================================================
شروع تحلیل بازی: Player One در برابر Player Two
============================================================
حرکت 1: انجام شده (e2e4) | نوبت بعدی: سیاه
  امتیاز ارزیابی پوزیشن (بر حسب سانتی‌پاون): +0.32
  بهترین حرکت جایگزین از نظر موتور: e7e5
------------------------------------------------------------
حرکت 2: انجام شده (e7e5) | نوبت بعدی: سفید
  امتیاز ارزیابی پوزیشن (بر حسب سانتی‌پاون): +0.25
  بهترین حرکت جایگزین از نظر موتور: g1f3
------------------------------------------------------------
حرکت 3: انجام شده (g1f3) | نوبت بعدی: سیاه
  امتیاز ارزیابی پوزیشن (بر حسب سانتی‌پاون): +0.30
  بهترین حرکت جایگزین از نظر موتور: b8c6
------------------------------------------------------------

ایده‌های توسعه و شخصی‌سازی اسکریپت

این اسکریپت پایه‌ی مناسبی برای پروژه‌های بزرگ‌تر است. شما می‌توانید با افزودن ماژول‌های دیگر، قابلیت‌های پیشرفته‌ای به آن اضافه کنید. برای مثال، می‌توانید خروجی برنام را به جای ترمینال، به یک فایل گزارش HTML تبدیل کنید یا با استفاده از فریم‌ورک‌های سبک، یک پنل وب محلی مشابه ابزارهای معرفی شده در مقالاتی نظیر معرفی نرم‌افزار IntelliEdit؛ جایگزین متن‌باز و پیشرفته نوت‌پد بسازید تا تخته شطرنج را به صورت گرافیکی مرور کنید. ذخیره‌سازی نتایج در پایگاه داده‌های سبک محلی (مانند SQLite) برای مقایسه پیشرفت در طول زمان نیز ایده جذاب دیگری است.

خطاهای رایج و راه‌حل‌ها

هنگام کار با موتورهای پردازشی خارجی ممکن است با برخی خطاهای متداول روبه‌رو شوید که رفع آن‌ها بسیار ساده است:

• خطای FileNotFoundError در اجرای موتور: این خطا زمانی رخ می‌دهد که پایتون نتواند فایل باینری استاک‌فیش را پیدا کند. مطمئن شوید نام فایل دقیق است یا مسیر کامل فایل (مثلاً C:/tools/stockfish.exe در ویندوز) را در متغیر STOCKFISH_PATH وارد کرده‌اید.
• کند شدن اجرای اسکریپت: ارزیابی عمق‌های بالا (مانند Depth 20 به بالا) پردازنده سیستم را درگیر می‌کند و زمان تحلیل را افزایش می‌دهد. برای تست سریع، عمق موتور را روی اعداد کمتر (بین 10 تا 14) تنظیم کنید.
• خطای فرمت PGN: اگر فایل یا رشته PGN دارای اشکال نگارشی یا حرکات نامعتبر باشد، تابع خوانش مقدار None برمی‌گرداند. حتماً از استاندارد بودن متن ورودی اطمینان حاصل کنید.

پرسش‌های متداول

جمع‌بندی

ساخت یک تحلیلگر شطرنج محلی با پایتون و Stockfish نه تنها تسلط شما را بر مفاهیم پردازش داده و ارتباط با فرآیندهای خارجی افزایش می‌دهد، بلکه ابزاری قدرتمند، سریع و رایگان برای بررسی بدون واسطه بازی‌هایتان در اختیارتان می‌گذارد. با کپی کردن این کد و شخصی‌سازی پارامترهای آن، می‌توانید باشگاه تحلیل شطرنج شخصی خود را روی کامپیوترتان راه‌اندازی کنید.