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

اتوماسیون فرآیند توسعه در سال‌های اخیر از ابزارهای تعاملی درون ادیتور فراتر رفته و به سمت «ایجنت‌های پس‌زمینه» حرکت کرده است؛ ابزارهایی که با زدن یک برچسب روی ایشوی گیت‌هاب، به‌صورت مستقل محیط پروژه را می‌سازند، باگ را رفع می‌کنند، تست‌های CI را پاس کرده و پول‌ریکوئست نهایی را برای بررسی ارسال می‌کنند. هدف این درس پیاده‌سازی معماری یک سرویس مستقل و خودمیزبان مشابه ابزارهایی مثل Cursor Background Agents یا AWS Remote SWE Agents است تا بدون وابستگی کامل به پلتفرم‌های انحصاری گران‌قیمت، جریان کاری تیم را خودکار کنید.

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

روی یک ایشو (issue) برچسب بزنید و پول‌ریکوئست (PR) تحویل بگیرید؛ این شکل محصولی ایجنت‌های کدنویسی خودکار در سال 2026 است: اجرای یک ایجنت درون ساندباکس (sandbox) ابری، اعتبارسنجی قبولی تست‌ها و ارسال یک PR آماده‌ی بررسی همراه با توضیح منطق تغییرات. سرویس‌های AWS Remote SWE Agents، ‏Cursor Background Agents، ‏OpenAI Codex cloud و Google Jules همگی این قابلیت را عرضه کرده‌اند. بخش‌های دشوار کار عبارتند از بازتولید خودکار محیط ساخت (build) مخزن، جلوگیری از نشت اطلاعات حساس و اعتبارسنجی (credentials)، اعمال سقف بودجه به ازای هر مخزن و اطمینان از اینکه ایجنت نتواند force-push کند. این پروژه‌ی پایانی، نسخه‌ی خودمیزبان (self-hosted) را پیاده‌سازی می‌کند و آن را از نظر هزینه و نرخ قبولی (pass rate) با جایگزین‌های میزبانی‌شده مقایسه می‌نماید.

فازهای تمرین‌شده: P11 · P13 · P14 · P15 · P17
مدت زمان: 30 ساعت

صورت مسئله

ایجنت کدنویسی ابری غیرهمگام (async cloud coding agent) دسته‌بندی محصولی متفاوتی نسبت به ایجنت‌های کدنویسی تعاملی (پروژه‌ی پایانی 01) دارد. رابط کاربری در اینجا فقط یک برچسب در GitHub است. به یک ایشو برچسب @agent fix this می‌زنید، یک ورکر (worker) درون ساندباکس ابری بالا می‌آید، مخزن را کلون می‌کند، تست‌ها را اجرا می‌نماید، فایل‌ها را تغییر می‌دهد، تغییرات را می‌سنجد و یک PR باز می‌کند که منطق تصمیم‌گیری ایجنت در متن آن ثبت شده است. نه حلقه‌ی تعاملی در کار است و نه ترمینالی. سرویس‌های AWS Remote SWE Agents، ‏Cursor Background Agents، ‏OpenAI Codex cloud، ‏Google Jules و Factory Droids همگی به سمت همین الگو رفته‌اند.

چالش‌های مهندسی این رویکرد کاملاً عینی هستند: بازتولید محیط (ایجنت باید بتواند مخزن را از صفر و بدون ایمیج توسعه‌ی کش‌شده بسازد)، تست‌های ناپایدار (flaky tests که باید دوباره اجرا یا جداسازی شوند)، محدودسازی دامنه‌ی اطلاعات اعتبارسنجی (یک GitHub App با کمترین دسترسی‌های جزئی)، اعمال بودجه به ازای هر مخزن در هر روز و سیاست منع force-push. این پروژه‌ی پایانی نرخ قبولی، هزینه و امنیت سیستم را در مقایسه با جایگزین‌های میزبانی‌شده ارزیابی می‌کند.

مفاهیم پایه

محرک شروع کار یک وب‌هوک در GitHub است (برچسب‌گذاری روی ایشو یا کامنت روی PR). توزیع‌کننده‌ی کار (dispatcher) وظایف را در صف ECS Fargate یا Lambda قرار می‌دهد. ورکر، مخزن را درون یک ساندباکس Daytona یا E2B بالا می‌کشد؛ آن هم با یک Dockerfile عمومی که از خود مخزن (زبان برنامه‌نویسی و فریم‌ورک) استنباط شده است. ایجنت حلقه‌ی mini-swe-agent یا SWE-agent v2 را روی مدل‌های Claude Opus 4.7 یا GPT-5.4-Codex اجرا می‌کند. کار در چند گام تکرار می‌شود: خواندن کد، پیشنهاد اصلاحیه، اعمال تکه (patch) و اجرای تست‌ها.

اعتبارسنجی، دروازه‌ی نهایی ورود به مرحله‌ی بعد است. پیش از باز شدن PR، باید خط لوله‌ی کامل CI درون ساندباکس با موفقیت پاس شود. تغییر پوشش آزمون (coverage delta) محاسبه می‌شود؛ اگر افت آن از حد آستانه بیشتر باشد، PR همچنان باز می‌شود اما برچسب needs-review می‌خورد. ایجنت توضیحات و منطق تغییرات را در قالب شرح PR می‌نویسد و یک ترد (thread) با اشاره‌ی (mention) ‏@agent ایجاد می‌کند تا بازبین بتواند پیگیری‌های بعدی را از همان‌جا انجام دهد.

امنیت از طریق دو سازوکار مجزای GitHub محدود و مدیریت می‌شود: سرویس GitHub App یک توکن نصب کوتاه‌مدت با دسترسی workflows: read و دامنه‌ی دسترسی محدود به محتوای مخزن و PRها فراهم می‌کند؛ در مقابل، قابلیت محافظت از branch (نه دسترسی‌های خود اپلیکیشن) قانون «عدم نوشتن مستقیم روی main» و «ممنوعیت force-push» را تضمین می‌کند و خود اپلیکیشن هرگز به لیست استثناهای دور زدن (bypass list) اضافه نمی‌شود. از آنجا که محدود کردن دسترسی فقط‌خواندنی به تفکیک مسیر برای .github/workflows جزو اجزای سازنده‌ی (primitive) واقعی GitHub App نیست، لیست مجاز (allow-list) ایجنت برای ویرایش فایل‌ها باید این محدودیت را در سطح ورکر کنترل و اعمال کند. سقف بودجه‌ی روزانه برای هر مخزن نیز در سطح دیسپچر اعمال می‌شود (برای مثال، حداکثر 5 عدد PR در روز به ازای هر مخزن و سقف 20 دلار برای هر PR).

معماری

GitHub issue labeled `@agent fix` or PR comment
            |
            v
    GitHub App webhook -> AWS Lambda dispatcher
            |
            v
    ECS Fargate task (or GitHub Actions self-hosted runner)
       - pull repo
       - infer Dockerfile (language, package manager)
       - Daytona / E2B sandbox with target runtime
       - clone -> git worktree -> agent branch
            |
            v
    mini-swe-agent / SWE-agent v2 loop
       Claude Opus 4.7 or GPT-5.4-Codex
       tools: ripgrep, tree-sitter, read/edit, run_tests, git
            |
            v
    verify CI passes in-sandbox + coverage delta check
            |
            v (verified)
    git push + open PR via GitHub App
       PR body = rationale + diff summary + trace URL
       label: needs-review
            |
            v
    operator reviews; can @-mention agent for follow-ups

ابزارها و فناوری‌ها

• محرک: GitHub App با توکن دسترسی جزئی؛ دریافت‌کننده‌ی وب‌هوک از طریق Lambda یا Fly.io
• ورکر: وظیفه‌ی (task) ‏ECS Fargate (یا رانر خودمیزبان GitHub Actions)
• ساندباکس: devcontainer دیتونا (Daytona) یا ساندباکس E2B به ازای هر وظیفه
• حلقه‌ی ایجنت: خط مبنای mini-swe-agent یا SWE-agent v2 روی Claude Opus 4.7 / GPT-5.4-Codex
• بازیابی: نقشه‌ی مخزن با tree-sitter به‌همراه ripgrep
• اعتبارسنجی: اجرای کامل CI داخل ساندباکس + بررسی آستانه‌ی افت پوشش آزمون
• مشاهده‌پذیری: سیستم Langfuse همراه با آرشیو ردگیری محاسبات (trace) به ازای هر PR که لینک آن در متن PR قرار می‌گیرد
• بودجه: سقف دلاری روزانه به ازای هر مخزن؛ حداکثر تعداد PR در هر مخزن در طول روز

پیاده‌سازی از صفر

1. برنامه‌ی گیت‌هاب (GitHub App). توکن نصب با دسترسی‌های محدود: دسترسی read+write برای issues، دسترسی write برای pull_requests، دسترسی read+write برای contents، و دسترسی read برای workflows. قوانین محافظت از branch (تنها ابزاری که قادر به انجام این کار است) شروط «عدم push مستقیم روی main» و «ممنوعیت force-push» را اعمال می‌کنند؛ اپلیکیشن در لیست مجاز برای دور زدن قوانین نیست. ورکر قانون «ممنوعیت تغییرات ذیل .github/workflows» را با بررسی لیست مجاز روی تغییرات پیشنهادی اعمال می‌کند، زیرا دسترسی‌های GitHub App بر اساس مسیر فایل تفکیک نمی‌شوند.

2. دریافت‌کننده‌ی وب‌هوک. یک تابع Lambda وب‌هوک‌های مربوط به برچسب‌های ایشو یا کامنت‌های PR را دریافت می‌کند. رویدادها را بر اساس برچسب @agent fix this فیلتر کرده و وظیفه را وارد صف SQS می‌کند.

3. توزیع‌کننده (Dispatcher). وظایف را از صف SQS برمی‌دارد. سقف بودجه‌ی روزانه به ازای هر مخزن را اعمال می‌کند. یک وظیفه‌ی ECS Fargate را همراه با آدرس مخزن، متن ایشو و یک ساندباکس تازه‌ی Daytona بالا می‌آورد.

4. استنباط محیط. شناسایی زبان (Python، ‏Node، ‏Go، ‏Rust) و مدیر بسته (uv، ‏pnpm، ‏go mod، ‏cargo). اگر Dockerfile در پروژه موجود نباشد، آن را به‌صورت آنی تولید می‌کند.

5. حلقه‌ی ایجنت. اجرای mini-swe-agent یا SWE-agent v2 با مدل Claude Opus 4.7. ابزارها: ripgrep، نقشه‌ی مخزن مبتنی بر tree-sitter، دستورهای read_file، ‏edit_file، ‏run_tests و git. محدودیت‌های قطعی: سقف هزینه 20 دلار، حداکثر زمان واقعی 30 دقیقه، حداکثر 30 نوبت گفت‌وگو (turn) برای ایجنت.

6. اعتبارسنجی. پس از پایان حلقه‌ی اجرا، تمام تست‌ها را درون ساندباکس اجرا کنید. تغییرات پوشش آزمون را با jacoco یا coverage.py محاسبه نمایید. اگر وضعیت CI قرمز شد: عملیات متوقف شود و هیچ PR جدیدی باز نشود. اگر افت پوشش آزمون بیشتر از 2% بود: PR همراه با برچسب needs-review ایجاد شود.

7. ارسال PR. شاخه‌ی ایجنت را push کنید. با استفاده از API گیت‌هاب یک PR با این اطلاعات باز کنید: عنوان، منطق تصمیم‌گیری، خلاصه‌ی تغییرات (diff)، آدرس اینترنتی trace، هزینه و تعداد نوبت‌های گفت‌وگو.

8. بهداشت اطلاعات اعتبارسنجی. ورکر با یک توکن نصب کوتاه‌مدت GitHub App اجرا می‌شود. لاگ‌ها پیش از ذخیره و آرشیو شدن، برای جلوگیری از افشای اسرار (secrets) به‌طور کامل پاکسازی می‌شوند.

9. ارزیابی. 30 ایشوی داخلی از پیش تعریف‌شده با سطوح دشواری مختلف. نرخ قبولی، کیفیت PR (حجم تغییرات، سبک کدنویسی، پوشش تست)، هزینه و تاخیر را بسنجید. خروجی را برای همان ایشوها با Cursor Background Agents و AWS Remote SWE Agents مقایسه کنید.

استفاده از ابزارهای واقعی

# on github.com
  - user labels issue #842 with `@agent fix this`
  - PR #1903 appears 14 minutes later
  - body:
    > Fixed NPE in widget.dedupe() caused by null comparator entry.
    > Added regression test widget_test.go::TestDedupeNullComparator.
    > Coverage delta: +0.12%
    > Turns: 7  Cost: $1.80  Trace: langfuse:...
    > Label: needs-review

تحویل پروژه

فایل outputs/skill-issue-to-pr.md خروجی تحویلی این بخش است: یک GitHub App به‌همراه ورکر ابری غیرهمگام که ایشوهای برچسب‌خورده را با هزینه‌ی مهارشده و دسترسی‌های محدود، به PRهای آماده‌ی بررسی تبدیل می‌کند.

تمرین‌ها

1. حالت «اصلاح تست‌های ناپایدار» (fix flaky test) را اضافه کنید: برچسب @agent stabilize-flake TestX تست موردنظر را 50 بار داخل ساندباکس اجرا می‌کند و یک تغییر حداقلی برای تثبیت آن پیشنهاد می‌دهد.

2. هزینه‌ی کار را با Cursor Background Agents روی سه ایشوی مشترک مقایسه کنید. گزارش دهید که هر ابزار در کدام سناریوها برتری دارد.

3. یک داشبورد بودجه پیاده‌سازی کنید: هزینه‌ی روزانه به ازای هر مخزن و هزینه به ازای هر کاربر را نمایش دهید. در صورت بروز رفتار غیرعادی، هشدار ارسال کنید.

4. حالتی برای «اجرای آزمایشی» (dry-run) بسازید که بدون اجرای تست‌های CI یک پیش‌نویس PR باز کند تا بازبین‌ها بتوانند برنامه‌ی ایجنت را ارزان و سریع بررسی کنند.

5. سیاست نگهداری را اضافه کنید: branchهای PRهایی که بیش از 7 روز از عمرشان گذشته و merge نشده‌اند، به‌طور خودکار حذف شوند.

اصطلاحات کلیدی

برای مطالعه‌ی بیشتر

• AWS Remote SWE Agents — مرجع اصلی برای ایجنت‌های ابری غیرهمگام
• SWE-agent — مرجع CLI
• Cursor Background Agents — جایگزین تجاری
• OpenAI Codex (cloud) — رقیب تجاری میزبانی‌شده
• Google Jules — نسخه‌ی میزبانی‌شده‌ی گوگل
• Factory Droids — دیگر نمونه‌ی مرجع تجاری
• GitHub App documentation — هویت ربات با دامنه‌ی دسترسی مشخص
• Daytona cloud sandboxes — ساندباکس مرجع