چیت‌شیت

حافظه‌ی مخزن، اسکریپت‌های راه‌اندازی و تحویل وظیفه

Repo Memory, Init Scripts and Handoffs

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

  • ۱۲ بخش
  • ۵ درس مرتبط
  • کد و دستورها عیناً از دوره‌ی اصلی
فهرست مطالب
  1. یک نشست میز کار
  2. دستورها
  3. وضعیت با رویکرد اسکیما‌محور
  4. پروب‌های راه‌اندازی
  5. پیش‌فرض‌ها و اعداد
  6. هفت فیلد تحویل وظیفه
  7. فقط پرامپت در برابر هدایت‌شده با میز کار
  8. چهارچوب وظیفه
  9. دسته‌بندی هر مجهول
  10. عیب‌یابی
  11. پرسش‌ها
  12. نکات

یک نشست میز کار

گام‌به‌گام
  1. چهارچوب‌بندینوشتن هدف، فکت‌ها، مسیرها، پذیرش و نادانسته‌ها قبل از هر ویرایش.
  2. اسکریپت راه‌اندازیپروب کردن میز کار. در صورت خطا، توقف و ارجاع به انسان.
  3. خواندنبارگذاری قرارداد دامنه و agent_state.json.
  4. ویرایشفقط تغییر فایل‌های مجاز.
  5. اثباتاجرای دستور پذیرش از طریق اجراکننده‌ی بازخورد.
  6. داوریاجرای گیت اعتبارسنجی، سپس بازبین.
  7. پاک‌سازیclean_state.json باید شامل یک لیست خالی باشد.
  8. تحویل وظیفهتولید handoff.md و handoff.json.

دستورها

دستورها
دستورعملکرد
python3 code/main.pyدموی درس را اجرا می‌کند. هر کدام فایل‌های خود را کنار اسکریپت می‌نویسد
`python3 code/main.py` in lesson 34workdir/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 40handoff.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_SECONDS24 * 60 * 60وضعیت قدیمی‌تر هشدار می‌دهد
LOCK_TTL_SECONDS24 * 60 * 60قفل تازه پروب‌ها را دور می‌زند
PROBE_BUDGET_SECONDS3.0قبولی کندتر تبدیل به هشدار می‌شود
LKG_FILE_DIFF_BUDGET50فایل‌های تغییریافته‌ی بیشتر شکست محسوب می‌شود
schema_version1تنها مقدار مجاز enum
TAIL_K5رکوردهای بازخورد نگه‌داری‌شده در تحویل وظیفه
Review total risk7پایین‌تر از آن، تحویل وظیفه هشدار اضافه می‌کند

هفت فیلد تحویل وظیفه

مفهوم‌ها
summary
یک پاراگراف از آنچه انجام شد.
changed_files
نگاه اجمالی به تفاوت‌های بازنگری.
commands_run
آنچه واقعاً اجرا شد.
failed_attempts
آنچه امتحان شد و دلیل شکست آن.
open_risks
مواردی که ممکن است نشست بعدی را با مشکل مواجه کند، به همراه سطح اهمیت.
next_action
اولین گام ملموس؛ فیلد حیاتی و کلیدی.
verdict_pointer
outputs/verification/<task_id>.json و بازبینی.
feedback_tail
آخرین رکوردهای TAIL_K به علاوه‌ی هر خروج غیرصفر.

فقط پرامپت در برابر هدایت‌شده با میز کار

مقایسه
نتیجهفقط پرامپتهدایت‌شده با میز کار
tests_actually_runFalseTrue
acceptance_metFalseTrue
files_outside_scope20
handoff_qualityناقص / مفقودبسته‌ی کامل
reviewer_total39
مراحلخواندن، ویرایش، ادعای اتمام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 نمی‌شود.