ساخت عامل برنامه‌نویس با پایتون خالص بدون وابستگی به فریم‌ورک‌های سنگین

آیا یک تیم دو نفره می‌تواند ابزارهای هوش مصنوعی در سطح حرفه‌ای را بدون تحمل بار سنگین فریم‌ورک‌های حجیم عرضه کند؟ پروژه CodeLite ثابت می‌کند که این امر ممکن است و نشان می‌دهد که یک دستیار برنامه‌نویسی قدرتمند تنها به پایتون خالص و یک API سازگار با OpenAI نیاز دارد تا با رویکردی بدون وابستگی (Zero-dependency)، در مقیاس واقعی عمل کند.

این چرخش به سمت معماری مینیمال در زمانی رخ می‌دهد که توسعه‌دهندگان به‌طور فزاینده‌ای با ماهیت «جعبه سیاه» لایه‌های ارکستراسیون سنگین دست‌وپنجه نرم می‌کنند. همان‌طور که در تحلیل قبلی ما درباره‌ی اینکه چرا طراحی حلقهٔ عامل (Agent Loop) از خودِ پرامپت اهمیت بیشتری دارد اشاره کردیم، این پیاده‌سازی تمرکز را از مهندسی پرامپت به اجرای مکانیکی وظایف منتقل می‌کند. در واقع، بسیاری از توسعه‌دهندگان به اشتباه سعی می‌کنند مشکلات ساختاری را با تغییرات جزئی در متن دستورات حل کنند، در حالی که تغییر مداوم پرامپت‌ها اغلب خطاهای بنیادین در معماری عامل‌های هوشمند را می‌پوشاند و از حل ریشه‌ای مشکل جلوگیری می‌کند. تصور کنید سیستمی دارید که در آن مدل زبانی بزرگ (LLM) — مثل کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن کتاب‌ها جواب می‌دهد — فقط کد پیشنهاد نمی‌دهد، بلکه به‌طور فعال سیستم فایل شما را مدیریت کرده و تست‌ها را به‌طور خودکار اجرا می‌کند.

مکانیسم حلقهٔ عامل

در قلب CodeLite، حلقهٔ عامل (Agent Loop) قرار دارد؛ چرخه‌ای مداوم از تفکر، تصمیم‌گیری، اجرا و مشاهده. سیستم بر اساس یک حلقه سخت‌گیرانه عمل می‌کند که با محدود کردن تعداد تکرارها به ۳۰ مورد، از ورود مدل زبانی بزرگ به بازگشت‌های بی‌نهایت (Infinite Recursion) جلوگیری می‌کند.

طبق مستندات فنی این پروژه، فرآیند از یک توالی مشخص پیروی می‌کند: مدل ابتدا درخواست کاربر را تحلیل می‌کند، ابزاری را از یک فهرست پیش‌تعریف‌شده انتخاب می‌کند، تابع پایتون مربوطه را اجرا کرده و پیش از تصمیم‌گیری درباره تکمیل وظیفه، خروجی را مشاهده می‌کند. این منطق در یک حلقه ساده while True پیاده شده است: عامل مدل را فراخوانی می‌کند، وجود tool_calls را بررسی می‌کند، توابع مرتبط را اجرا کرده، نتایج را به تاریخچه پیام‌ها می‌افزاید و این روند را تا رسیدن به پاسخ نهایی تکرار می‌کند.

برای اجرای این سازوکار، حلقهٔ عامل از مشخصات فراخوانی تابع (Function Calling) شرکت OpenAI استفاده می‌کند. ساختار اصلی شامل تعریف یک آرایه از ابزارهاست که نام تابع، یک شرح دقیق و پارامترهای مورد نیاز را در بر می‌گیرد. وقتی مدل پاسخ می‌دهد، یک میدان tool_calls شامل یک شناسه منحصربه‌فرد (مثلاً call_abc123) و آرگومان‌های خاص مورد نیاز برای فراخوانی تابع را برمی‌گرداند؛ برای مثال، برای درخواست read_file آرگومان {"path": "main.py"} ارسال می‌شود.

ثبت ابزار و تولید طرح‌واره

این پروژه از دکوراتورهای پایتون برای ثبت ابزارها استفاده می‌کند. این سیستم به توسعه‌دهندگان اجازه می‌دهد تا قابلیت‌های جدید — مثل خواندن فایل‌ها یا اجرای دستورات شل — را تنها با یک تگ ساده @tool اضافه کنند.

جزئیات این سیستم ثبت عبارت است از:

• تولید خودکار طرح‌واره (Schema): سیستم با استفاده از ماژول inspect در پایتون، طرح‌واره‌های JSON را مستقیماً از راهنمای نوع (Type Hints) استخراج می‌کند. اگر پارامتر به عنوان str تعریف شده باشد، به "string"، اگر int باشد به "integer" و اگر bool باشد به "boolean" نگاشت می‌شود. این امر نیاز به نوشتن دستی تعاریف توابع OpenAI را کاملاً از بین می‌برد.
• استخراج پویا از Docstring: دکوراتور به‌طور خودکار نام تابع (یا نام سفارشی ارائه شده) را می‌گیرد و از اولین خطِ Docstring تابع به‌عنوان شرح ابزار برای مدل زبانی استفاده می‌کند.
• برچسب‌گذاری خطر: ابزارها می‌توانند با تگ dangerous=True علامت‌گذاری شوند که باعث فعال شدن یک لایه امنیتی یکپارچه پیش از اجرا می‌شود. برای مثال، ابزار run_command که از subprocess.run استفاده می‌کند، به دلیل توانایی ایجاد تغییرات در سیستم، به‌عنوان ابزار خطرناک شناسایی و علامت‌گذاری می‌شود.

لایه امنیتی و طبقه‌بندی ریسک

در CodeLite، امنیت یک جزء اصلی معماری است و نه یک الحاقیه که در انتها به سیستم اضافه شده باشد. این سیستم از یک طبقه‌بندی ریسک سه‌سطحی استفاده می‌کند تا از حذف تصادفی دایرکتوری ریشه یا اجرای دستورات sudo غیرمجاز توسط هوش مصنوعی جلوگیری کند.

الگوهای ریسک
فیلترهای امنیتی با استفاده از عبارت‌های منظم (Regular Expressions) برای دسته‌بندی دستورات به کار می‌روند:

• الگوهای خطرناک: شامل دستورات حذف بازگشتی rm -rf، فرمت کردن درایو format C:، دستورات sudo (مدیریت privileged)، تغییر دسترسی‌های ناامن chmod 777 و همچنین الگوی بسیار خطرناک curl | sh است.
• الگوهای تأییدی: شامل عملیات Git مانند git push، git commit، git merge و git rebase و همچنین نصب بسته‌ها از طریق pip install، npm install و مدیریت کانتینرهای docker run/rm/stop است.

سطوح اجرا
بر اساس این الگوها، سیستم دستورات را به سه سطح تقسیم می‌کند:

• 🟢 ایمن (Safe): دستوراتی مانند ls (مشاهده فایل‌ها)، cat (خواندن محتوا) یا git status فوراً و بدون وقفه اجرا می‌شوند.
• 🟡 تأییدی (Confirm): عملیاتی مانند pip install یا git push نیاز به تأیید صریح کاربر دارند.
• 🔴 خطرناک (Dangerous): الگوهای پرریسک مانند rm -rf یا sudo باعث ایجاد درخواست‌های تأیید دو مرحله‌ای می‌شوند. اگر کاربر عملیات را لغو کند، سیستم نتیجه را به صورت «کاربر عملیات را لغو کرد» (User cancelled the operation) به مدل بازمی‌گرداند تا مدل از این وضعیت آگاه شود.

مدیریت وضعیت و زمینه

برای حل مشکل رایج سرریز توکن (Token Overflow) در جلسات طولانی کدنویسی، یک مکانیسم فشرده‌سازی هوشمند زمینه پیاده شده است. وقتی حجم گفتگو به ۸۰٪ از حد مجاز پنجرهٔ زمینه (Context Window) — که به‌طور پیش‌فرض روی ۳۰,۰۰۰ توکن تنظیم شده است — می‌رسد، عامل به‌طور خودکار دورهای قدیمی‌تر گفتگو را خلاصه می‌کند.

این روش تضمین می‌کند که دستیار حافظه منسجمی از ساختار پروژه داشته باشد بدون اینکه به‌دلیل محدودیت‌های پنجره زمینه متوقف یا کراش کند. متد maybe_compress سیستم، ۱۰ پیام اخیر را به‌طور کامل حفظ کرده و تمام پیام‌های قدیمی‌تر را با یک پرامپت خاص به مدل می‌فرستد: «لطفاً اطلاعات کلیدی این گفتگو را به‌طور موجز خلاصه کن». سپس این خلاصه به‌عنوان یک پیام سیستمی (System Message) به تاریخچه گفتگو بازمی‌گردد تا پیوستگی حفظ شده و مصرف توکن‌ها به‌شدت کاهش یابد.

سازگاری جهانی با مدل‌های مختلف

به دلیل پایبندی به استاندارد فراخوانی تابع OpenAI، کلاینت CodeLite مستقل از ارائه‌دهنده (Provider-agnostic) است. کلاس LLMClient به‌گونه‌ای طراحی شده که با هر سرویسی که نقطه پایانی /chat/completions را پشتیبانی کند، به‌طور کامل سازگار باشد.

این یعنی سیستم به‌طور یکپارچه با مدل‌های زیر کار می‌کند:

• DeepSeek و DashScope (Tongyi Qianwen)
• Ollama برای میزبانی مدل‌های محلی روی سیستم کاربر
• MiMo (توسعه یافته توسط شیائومی)

این کلاینت به‌طور ویژه از خروجی جریانی (Streaming) پشتیبانی می‌کند. سیستم تکه‌های داده ورودی را تجزیه کرده، قطعات tool_calls را در لحظه با هم ادغام می‌کند و محتوا را هم‌زمان با تولید در کنسول چاپ می‌کند تا تجربه کاربری سریع و پاسخگو باشد.

سناریوهای کاربردی در دنیای واقعی

در تست‌های عملی، این عامل توانایی مدیریت گردش‌های کاری پیچیده و چندمرحله‌ای را از طریق حلقه خود نشان داده است.

سناریوی اول: نقشه‌برداری پروژه
وقتی کاربر می‌خواهد ساختار کلی پروژه را ببیند، عامل تابع tree_view(path=".", max_depth=2) را فراخوانی می‌کند. این کار به مدل اجازه می‌دهد سلسله‌مراتب دایرکتوری‌ها، شامل پوشه‌های src/، tests/ و فایل requirements.txt را تجسم و تحلیل کند.

سناریوی دوم: بازسازی کد (Refactoring)
در یک سناریوی بازسازی کد، عامل ابتدا فایل utils.py را با دستور read_file می‌خواند. پس از شناسایی سه مورد از کدهای تکراری و زائد، تابع edit_file را فراخوانی می‌کند تا متن قدیمی را با یک تابع بهینه جایگزین کند. در این مثال، حجم فایل از ۱۵۰ خط به ۸۰ خط کاهش یافت.

سناریوی سوم: حلقه خود-ترمیم (Auto-Repair)
یکی از قابلیت‌های حیاتی، مکانیسم «خود-ترمیم» است. اگر دستوری شکست بخورد — برای مثال وقوع خطای ModuleNotFoundError: No module named 'requests' در حین اجرای pytest — عامل صرفاً خطا را گزارش نمی‌دهد. بلکه خروجی را تحلیل کرده، وابستگی گم‌شده را شناسایی می‌کند و به‌طور خودکار راهکار را پیشنهاد می‌دهد: «پیشنهاد: وابستگی گم‌شده شناسایی شد، دستور pip install requests را اجرا کنید». سپس عامل خودش اقدام به نصب کرده و تست‌ها را مجدداً اجرا می‌کند تا زمانی که با موفقیت پاس شوند.

مقایسه: پایتون خالص در برابر فریم‌ورک‌ها

این پیاده‌سازی سبک در تضاد کامل با عامل‌های پیچیده‌ای است که با LangChain یا LlamaIndex ساخته می‌شوند. در حالی که فریم‌ورک‌ها نمونه‌سازی سریع (Prototyping) را تسهیل می‌کنند، رویکرد پایتون خالص کنترل مطلق روی پشتهٔ اجرا (Execution Stack) فراهم می‌آورد.

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

اگر در حال مدیریت یک کدبیس موجود هستید، گام منطقی بعدی این است که ارزیابی کنید آیا فریم‌ورک «جعبه سیاه» فعلی شما باعث ایجاد تأخیر یا رفتارهای غیرقابل‌پیش‌بینی شده است که یک حلقه سفارشی و سبک می‌تواند آن‌ها را حل کند. با تسلط بر این پنج مؤلفه اصلی — ثبت ابزار، حلقهٔ عامل، کلاینت LLM، لایه امنیتی و مدیریت زمینه — شما نقشه راه (Blueprint) هر معماری مدرن برای عامل‌های هوش مصنوعی را در اختیار دارید.

گام بعدی شما

• اگر از عامل‌های مبتنی بر فریم‌ورک استفاده می‌کنید، بررسی کنید آیا لایه‌های انتزاعی باعث تأخیر یا رفتارهای غیرقابل‌پیش‌بینی در سیستم شما شده‌اند.
• سعی کنید یک حلقهٔ ساده while را برای مدیریت فراخوانی توابع در پروژه کوچک خود پیاده کنید تا کنترل بیشتری روی جریان داده داشته باشید.
• لایه امنیتی مبتنی بر عبارت‌های منظم (Regex) را برای هر ابزاری که دسترسی به سیستم فایل دارد، پیاده‌سازی کنید.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.