چیتشیت
حافظهی مخزن، اسکریپتهای راهاندازی و تحویل وظیفه
Repo Memory, Init Scripts and Handoffs
چهارچوببندی وظیفه، ذخیرهی وضعیت در فایلهای دارای اعتبارسنجی اسکیما، اجرای آزمون قبل از شروع، و پایان دادن به هر نشست با یک بستهی تحویل وظیفه.
فهرست مطالب
یک نشست میز کار
گامبهگام- چهارچوببندینوشتن هدف، فکتها، مسیرها، پذیرش و نادانستهها قبل از هر ویرایش.
- اسکریپت راهاندازیپروب کردن میز کار. در صورت خطا، توقف و ارجاع به انسان.
- خواندنبارگذاری قرارداد دامنه و
agent_state.json. - ویرایشفقط تغییر فایلهای مجاز.
- اثباتاجرای دستور پذیرش از طریق اجراکنندهی بازخورد.
- داوریاجرای گیت اعتبارسنجی، سپس بازبین.
- پاکسازی
clean_state.jsonباید شامل یک لیست خالی باشد. - تحویل وظیفهتولید
handoff.mdوhandoff.json.
دستورها
دستورها| دستور | عملکرد |
|---|---|
python3 code/main.py | دموی درس را اجرا میکند. هر کدام فایلهای خود را کنار اسکریپت مینویسد |
`python3 code/main.py` in lesson 34 | workdir/agent_state.json و workdir/task_board.json را مینویسد |
python3 code/main.py --no-cache | درس 35: نادیده گرفتن prereqs.lock و اجرای تمام پروبها |
python3 code/main.py --write-lkg | درس 35: پین کردن HEAD فعلی به عنوان آخرین وضعیت مناسبِ مشخص (last-known-good) |
git diff --name-only <baseline> HEAD | دستور پشت آزمون ارزیابی lkg_diff |
`python3 code/main.py` in lesson 40 | handoff.md و handoff.json را مینویسد |
python3 -m unittest discover code/tests -v | درس 43: اعتبارسنج چهارچوب وظیفه را تست میکند |
python3 -m unittest tests.test_accounts | دستور پذیرش چهارچوب نمونه |
وضعیت با رویکرد اسکیمامحور
کدpython
"required": ["schema_version", "active_task_id", "touched_files", "next_action"]
"active_task_id": {"type": ["string", "null"], "pattern": r"^(T-\d{3,}|)$"}
"status": {"enum": ["todo", "in_progress", "done", "blocked"]}
mgr = StateManager(state_path, STATE_SCHEMA)
state = mgr.load() # خواندن، سپس اعتبارسنجی
mgr.commit(state) # اعتبارسنجی، سپس atomic_write
fd, tmp_name = tempfile.mkstemp(prefix=path.name + ".", dir=path.parent)
os.fsync(fh.fileno()) # ابتدا تخلیه روی دیسک (flush)
os.replace(tmp_name, path) # تغییر نام اتمیک (atomic rename)
پروبهای راهاندازی
مفهومهاprobe_runtime- پایینتر از
REQUIRED_PYTHONشکست میخورد. probe_dependencies- اجرای
importlib.util.find_specبرای هر وابستگی. probe_test_command- اجرای
shutil.whichروی دستور تست. probe_env- در صورت نبود متغیر محیطی شکست میخورد.
probe_state_freshness- هشدار در صورتی که وضعیت قدیمی یا غایب باشد.
probe_lkg_diff- در صورت فراتر رفتن از سقف بودجهی تفاوتهای بازنگری، شکست میخورد.
- آزمون ارزیابی
- برگرداندن
(name, status, detail). - گزارش
init_report.json. خروج با کد 1 در صورت هرگونه خطا.
پیشفرضها و اعداد
پیشفرضها| تنظیم | پیشفرض | نکته |
|---|---|---|
REQUIRED_PYTHON | (3, 10) | کف آزمون ارزیابی محیط اجرا |
STATE_FRESHNESS_SECONDS | 24 * 60 * 60 | وضعیت قدیمیتر هشدار میدهد |
LOCK_TTL_SECONDS | 24 * 60 * 60 | قفل تازه پروبها را دور میزند |
PROBE_BUDGET_SECONDS | 3.0 | قبولی کندتر تبدیل به هشدار میشود |
LKG_FILE_DIFF_BUDGET | 50 | فایلهای تغییریافتهی بیشتر شکست محسوب میشود |
schema_version | 1 | تنها مقدار مجاز enum |
TAIL_K | 5 | رکوردهای بازخورد نگهداریشده در تحویل وظیفه |
Review total risk | 7 | پایینتر از آن، تحویل وظیفه هشدار اضافه میکند |
هفت فیلد تحویل وظیفه
مفهومهاsummary- یک پاراگراف از آنچه انجام شد.
changed_files- نگاه اجمالی به تفاوتهای بازنگری.
commands_run- آنچه واقعاً اجرا شد.
failed_attempts- آنچه امتحان شد و دلیل شکست آن.
open_risks- مواردی که ممکن است نشست بعدی را با مشکل مواجه کند، به همراه سطح اهمیت.
next_action- اولین گام ملموس؛ فیلد حیاتی و کلیدی.
verdict_pointeroutputs/verification/<task_id>.jsonو بازبینی.feedback_tail- آخرین رکوردهای
TAIL_Kبه علاوهی هر خروج غیرصفر.
فقط پرامپت در برابر هدایتشده با میز کار
مقایسه| نتیجه | فقط پرامپت | هدایتشده با میز کار |
|---|---|---|
tests_actually_run | False | True |
acceptance_met | False | True |
files_outside_scope | 2 | 0 |
handoff_quality | ناقص / مفقود | بستهی کامل |
reviewer_total | 3 | 9 |
| مراحل | خواندن، ویرایش، ادعای اتمام | 8 مرحله، از راهاندازی تا تحویل وظیفه |
چهارچوب وظیفه
کدpython
frame = TaskFrame(
goal="Prevent duplicate email addresses during signup",
allowed_paths=["app/accounts.py", "tests/test_accounts.py"],
forbidden_paths=["migrations/**", "deploy/**"],
acceptance=["python3 -m unittest tests.test_accounts"],
facts=[RepositoryFact("Duplicate errors use status 409",
"tests/test_accounts.py:44")], # رسید شواهد
unknowns=["Whether email comparison is case-insensitive"])
issues = validate(frame) # لیست خالی به معنی READY است
render(frame) # Markdown، وضعیت: READY یا BLOCKED
دستهبندی هر مجهول
مفهومها- قابل کشف (Discoverable)
- مخزن یا سیستمِ در حال اجرا میتواند به آن پاسخ دهد. ادامه دهید.
- قابل تصمیمگیری (Decidable)
- قرارداد وظیفه به ایجنت اختیار میدهد. ادامه دهید.
- انسانی (Human)
- رفتار محصول، هزینه، ریسک یا سازگاری عمومی را تغییر میدهد. متوقف شوید.
- معوق (Deferred)
- خارج از این بخش وظیفه. آن را در نااهداف قرار دهید.
عیبیابی
عیبیابینشست بعدی کار انجامشده را دوباره انجام میدهد
- علت
- وضعیت در چت قرار داشت، نه در مخزن
- راهحل
- وضعیت را در JSON با اعتبارسنجی اسکیما در مخزن نگهداری کنید
نشست با وضعیت خراب و نامعتبر از سر گرفته میشود
- علت
write_text()همراه با پنهانسازی استثناها (silenced exceptions)- راهحل
- استفاده از
atomic_write: توابعmkstemp،fsyncوos.replace
does not matchرویT-bogus- علت
- شناسهی وظیفه الگو را نقض میکند
- راهحل
- از شناسههایی مانند T-001 استفاده کنید
init failed; refuse to launch agent- علت
- وضعیت یکی از پروبها fail است
- راهحل
- پروب را اصلاح کنید؛ ایجنت را استارت نزنید
خطای
lkg_diff؛ تغییر فایلها فراتر از سقف تعیینشده- علت
- بیش از 50 فایل تغییر پس از آخرین وضعیت خوبِ تاییدشده
- راهحل
- انسان با دستور
--write-lkgخط مبنا را تایید میکند
Probe pass turns to warn with
slow:- علت
- زمان آزمون ارزیابی بیشتر از سقف بودجهی 3 ثانیهای
- راهحل
- آن را از init خارج کنید یا نتیجهاش را کش نمایید
no next_action recorded; needs human- علت
- وضعیت فاقد فیلد
next_actionاست - راهحل
- قبل از تحویل وظیفه، مقدار
next_actionرا مشخص کنید
چهارچوب در وضعیت
Status: BLOCKED- علت
- تابع
validateمواردی از خطا پیدا کرد - راهحل
- هر خط ذیل Blocking issues را برطرف کنید
پرسشها
پرسش و پاسخ- چه چیزی در حافظهی مخزن ذخیره میشود؟
- دادههایی که سه ماه بعد در اجرای مجدد CI مفید خواهند بود.
- دو بار اجرای پشت سر هم init؟
- دومی هیچ عملیاتی انجام نمیدهد (no-op)، جز بهروزرسانی برچسب زمانی.
- تحویل وظیفه بدون
next_action؟ - این فقط یک گزارش وضعیت است، نه تحویل وظیفه.
- اختلاف میان
handoff.mdوhandoff.json؟ - اولویت با JSON است.
- چه زمانی خواندن مخزن متوقف شود؟
- وقتی هر تصمیم شواهد دارد، واگذار شده یا به عنوان نادانسته ثبت شده است.
- چه زمانی کار جمعبندی شود؟
- در 50 تا 75 درصد بودجهی کانتکست، نه در 95 درصد.
نکات
نکتهها- دستسازههای حجیم را از
agent_state.jsonدور نگه دارید؛ فقط مسیر آنها را ذخیره کنید. - هر شناسه فراخوانی ابزار را پیش از اجرا در
pending_calls.jsonlلاگ کنید. - هر تغییر را به
state.events.jsonlاضافه کنید؛ اسنپشات را درstate.jsonذخیره کنید. - به ازای هر branch و موضوع، تنها یک تحویل وظیفه فعال نگه دارید.
- برای هر فکت یک رسید ارائه دهید: مسیر فایل و شماره خط.
- راهاندازی شامل هیچ درخواست شبکه و هیچ فراخوانی LLM نمیشود.