چیت‌شیت
ایجنت‌های برنامه‌نویس: چشم‌انداز و پروژه‌های پایانی
Coding Agents: Landscape and Capstones
انتخاب ساختار پایه، تعیین بودجه‌ها و گیت‌های کنترلی، اجرای ایجنت‌های پروژه پایانی و سه پروژه‌ی ایجنت برنامه‌نویس.
فهرست مطالب
فراخوانی ابزار JSON در مقابل CodeAct
مقایسه| عامل | فراخوانی ابزار JSON | CodeAct |
|---|---|---|
| یک اکشن شامل | یک پی‌لود ساختاریافته‌ی JSON | یک برنامه‌ی کامل Python |
| بازرسی | ساده، یک اکشن در هر نوبت گفت‌وگو | سخت‌تر، شعاع تخریب گسترده |
| ترکیب‌پذیری | محدود | حلقه‌ها، زنجیره‌سازی ابزارها، مدیریت خطاها |
| ایمنی | اعتبارسنج روی هر فراخوانی | نیازمند یک ساندباکس تقویت‌شده |
| شعاع تخریب نمونه آزمایشی | 1 فایل در هر اکشن | تمام فایل‌های دارای خطا به صورت همزمان |
| غالب در | سرویس‌های مدیریت‌شده | پلتفرم‌های متن‌باز |
سه ایجنت پروژه پایانی
مقایسه| عامل | ایجنت ترمینال (01) | از ایشو تا PR (16) | مهاجرت (09) |
|---|---|---|---|
| محرک اجرا | agent run <repo> "<task>" | لیبل ایشو: @agent fix this | migrate <repo> --target java17 |
| ساندباکس | E2B یا Daytona، ورک‌تری git | Daytona یا E2B برای هر وظیفه | Daytona برای هر branch |
| سقف نوبت گفت‌وگو | 50 نوبت گفت‌وگو | 30 نوبت گردش ایجنت | 20 نوبت گردش ایجنت |
| سقف هزینه | 5 دلار برای هر وظیفه | 20 دلار برای هر PR، سقف 5 PR در روز برای هر مخزن | 8 دلار برای هر مخزن |
| سایر محدودیت‌ها | 200 هزار توکن کانتکست | 30 دقیقه زمان واقعی | 30 دقیقه برای هر مخزن |
| گیت قبل از PR | قبولی تست‌ها | اجرای کامل CI در ساندباکس، تغییر پوشش آزمون | قبولی تست‌ها، عدم کاهش بیش از 2% در پوشش آزمون |
| هنگام شکست | هوک Stop یک بسته ردگیری محاسبات می‌نویسد | شکست CI: توقف، بدون ثبت PR | دسته‌بندی شکست به همراه گام‌های بازتولید |
چه زمانی استفاده کنیم؟
مفهوم‌ها- استفاده از فراخوانی ابزار JSON زمانی که
- هر اکشن نیازمند اعتبارسنج صریح و بازرسی ساده باشد.
- استفاده از CodeAct زمانی که
- یک اکشن باید ابزارها را روی فایل‌های متعددی زنجیره‌سازی کند. ابتدا ساندباکس را ایمن‌سازی کنید.
- استفاده از ایجنت ترمینال زمانی که
- ورودی کار CLI، خروجی pull request و همراه با یک برنامه‌ی پویا باشد.
- استفاده از ایشو تا PR زمانی که
- رابط کاربری یک لیبل GitHub است. بدون حلقه‌ی تعاملی و بدون ترمینال.
- استفاده از ایجنت مهاجرت زمانی که
- مجموعه‌ی تست‌ها، حقیقت پایه در چندین مخزن است.
- ابتدا از دستورالعمل‌های قطعی استفاده کنید
- آنها 70 تا 80 درصد از اصلاحات مکانیکی مهاجرت را پوشش می‌دهند.
اعدادی که باید بدانید
مفهوم‌ها- معیار SWE-bench Verified
- رشد از 4% به 80.9% در کمتر از سه سال. شامل 500 وظیفه با ارزیابی دستی انسانی.
- تفاوت ساختار پایه
- مدل Claude Sonnet 4.5 روی SWE-agent v1 امتیاز 43.2% و روی Cline امتیاز 59.8% گرفت.
- بخش ساده تسک‌ها
- 161 وظیفه از 500 وظیفه در Verified فقط نیازمند 1 یا 2 خط تغییر هستند.
- معیار SWE-bench Pro
- تغییرات بیش از 10 خط. سیستم‌های پیشرو امتیاز 23 تا 59% کسب می‌کنند.
- حلقه‌ی اعتبارسنج
- ارتقای بیش از 10 نمره‌ای در SWE-bench.
- سیستم Live-SWE-agent
- امتیاز 79.2% در SWE-bench Verified با مدل Opus 4.5.
بستر آزمایشی ایجنت ترمینال (01)
معماریاجرای درس‌ها
کار و کد| وظیفه | کد |
|---|---|
| مقایسه‌ی ساختارهای پایه‌ی ساده (L09) | code/main.py |
| حلقه‌ی برنامه‌ریزی، اقدام، مشاهده (01) | python main.py |
| دموی بستر آزمایشی TS به همراه ارزیابی آفلاین | npm start |
| شبیه‌سازی 50 مهاجرت (09) | python main.py |
| توزیع 20 ایشو روی 3 مخزن (16) | python main.py |
| اصلاح مجموعه‌داده‌ی نمونه fizz (29) | python3 code/main.py |
| تست دموی سرتاسری | python3 -m pytest code/tests/ -v |
سه پروژه
مقایسه| عامل | tiny-coding-agent | rust-agent-shell | pr-review-reporter |
|---|---|---|---|
| خروجی ساخت | حلقه‌ی ترمیم محدود با پچ‌های دقیق | حلقه‌ی اکشن stdin/stdout در Rust | گزارش بررسی پچ تثبیت‌شده |
| زبان | Python 3.10+ | زبان Rust همراه با یک تطبیق‌دهنده Python | TypeScript روی Node 22.18+، Python |
| ورودی | فضای کاری همراه با proposals.json | فضای کاری همراه با requests.jsonl | تفاوت‌های بازنگری یکپارچه، stdin یا --repo |
| خروجی | repair-trace.json | رویدادهای JSONL به ازای شناسه‌ی هر درخواست | review.json، review.html و SARIF |
| بودجه | --max-steps پیش‌فرض 6 | --limit پیش‌فرض 50 | تفاوت‌های بازنگری حداکثر یک مگابایت |
| ایمنی | مهار مسیر، یک دستور تست تک | بدون شل سیستم‌عامل، خواندن حداکثر 16 کیلوبایت | گریز از کاراکترهای HTML، گیت کنترلی نقل‌قول دقیق |
| وضعیت‌های پایانی | completed، failed، budget_exhausted | ok، error، rejected | یافته‌های تأییدشده یا ردشده |
دستورات پروژه
دستورها| دستور | عملکرد |
|---|---|
project_test.py <project> --init learning-artifacts/<project> | ایجاد یک فضای کاری برای یادگیرنده |
project_test.py <project> --stage 1 --path <workspace> | نمره‌دهی به یک مرحله |
project_test.py <project> --all --solution --strict | بررسی کد مرجع |
cli.py <workspace> <proposals> --copy-to <dir> --out <trace> | ترمیم یک نسخه‌ی موقت |
client.py <workspace> <requests> --limit 8 --out <file> | اجرای شل Rust از طریق تطبیق‌دهنده |
node cli.ts --diff samples/change.diff --sarif review.sarif | نوشتن خروجی‌های JSON، HTML و SARIF |
--repo /path --base REF --head REF | حالت فقط‌خواندنی تفاوت‌های بازنگری Git |
--candidates recorded-findings.json | اعتبارسنجی یافته‌های یک بازبین دیگر |
بودجه‌ها در کد
پیش‌فرض‌ها| تنظیم | پیش‌فرض | توضیحات |
|---|---|---|
max_turns | 50 | Budget در پروژه پایانی 01 |
max_tokens | 200_000 | سقف کانتکست در پروژه پایانی 01 |
max_dollars | 5.00 | پروژه پایانی 01، برای هر وظیفه |
TRUNCATE_BYTES | 4096 | سقف خروجی ابزار در 01 |
BUDGET_TURNS | 20 | مهاجرت، با BUDGET_USD معادل 8.0 |
step_budget | 12 | AgentRun در L29 |
زنجیره گیت و ساندباکس (29)
کدpython
chain = GateChain(gates=(
WhitelistGate(allowed=frozenset({"read_file", "write_file", "run_tests"})), # مجموعه‌ی مجازها (allow-set)
RegexGate.from_strings(items=(r"\brm\s+-rf\b", r"\bsudo\b", r"^/etc/")), # الگوهای ردشده
BudgetGate(max_tokens=budget), # بودجه‌ی مشاهده
))
outcome = self.chain.evaluate(call, ctx) # توقف با اولین دستور نامجاز
sandbox = Sandbox(project_root=repo, timeout_seconds=10.0) # لیست سیاه همراه با زندان مسیر
عیب‌یابی
عیبیابیکرش کردن حلقه روی 8 مگابایت خروجی ripgrep
- علت
- خروجی کوتاه نشده‌ی ابزار
- راه‌حل
- تعیین سقف 4 هزار توکن برای هر فراخوانی
رسیدن
rm -rfبه ساندباکس- علت
- نبود گارد محافظتی
PreToolUse - راه‌حل
destructive_guardوضعیت را بهblockedتغییر می‌دهد
امتیاز Verified بالا اما نتایج ضعیف در دنیای واقعی
- علت
- بخش ساده تسک‌ها، 161 وظیفه از 500 وظیفه
- راه‌حل
- ارزیابی زیرمجموعه‌ای شبیه به تسک‌های Pro از بک‌لاگ خودتان
budget_exhausted- علت
- مصرف شدن 30 دقیقه، 8 دلار یا 20 نوبت گفت‌وگو
- راه‌حل
- ثبت وضعیت مخزن با تفاوت‌های بازنگری فعلی
coverage_regression- علت
- کاهش پوشش آزمون به میزان بیش از 2%
- راه‌حل
- دسته‌بندی در کلاس مربوطه، بدون ثبت PR
policy_denied- علت
- تابع
can("force_push")مقدار False برمی‌گرداند - راه‌حل
- محافظت از branch، عدم حضور اپلیکیشن در لیست مجاز گذر از گیت
patch must match exactly once- علت
- متن قبلی یافت نشد یا یکتا نیست
- راه‌حل
- استفاده از یک رشته‌ی متنی قدیمی، دقیق و یکتا
path escapes root- علت
- مسیر از ریشه‌ی مجاز خارج می‌شود
- راه‌حل
- ارسال یک مسیر نسبی معتبر درون ریشه
پرسش و پاسخ
پرسش و پاسخ- کدام ایجنت برنامه‌نویس بهترین است؟
- سوال اشتباه است. قابلیت اطمینان را بر اساس توزیع وظایف خاص خود بسنجید.
- چرا ساختار ساده‌ی CodeAct نوبت‌های گفت‌وگوی کمتری مصرف می‌کند؟
- یک قطعه‌کد به صورت همزمان تمام فایل‌های دارای خطا را بازنویسی می‌کند.
- چرا برای گیت ایمنی از
assertاستفاده نمی‌شود؟ - فلگ
python -Oتمام عبارت‌های assert را حذف می‌کند.