میز کار (workbench) یک ایجنت وضعیت پایدار (durable state) خود را بین نشستها (sessions) با این کد ذخیره میکند. آن را بررسی کنید. چه مشکلی ممکن است پیش بیاید، نویسندهی این درس چه رویکرد متفاوتی در پیش میگیرد و چه موارد دیگری باید پیرامون این فرایند نوشتن پیادهسازی شوند؟
def save_state(path, state):
try:
path.write_text(json.dumps(state))
except Exception:
returnاول خودتان جواب بدهید، بعد پاسخ را باز کنید.
پاسخ کوتاه
دو ایراد اساسی وجود دارد: کرش کردن برنامه در میانهی نوشتن، فایلی ناقص برجا میگذارد که نشست بعدی آن را بهعنوان وضعیت خراب لود میکند؛ از طرفی بلاک except بیصدا نیز این خطا را پنهان میسازد، در نتیجه ایجنت بدون هیچ هشداری کارش را با دادههای معیوب ادامه میدهد. نویسندهی این درس ابتدا یک فایل موقت در همان دایرکتوری ایجاد میکند، دادهها را مینویسد، آن را با دیسک همگامسازی (sync) میکند و سپس با تغییر نام روی فایل مقصد مینشاند؛ به این ترتیب فایل روی دیسک همیشه یا نسخهی قدیمی است یا نسخهی جدید. پیرامون این نوشتن، اعتبارسنجی اسکیما (schema) برای رد وضعیت نامعتبر پیش از ذخیره، یک فیلد نسخه همراه با مسیر مهاجرت (migration path)، و کلیدهای یکتایی تراکنش (idempotency keys) برای فراخوانی ابزارهایی (tool calls) که تکرارشان امن نیست نیز باید پیادهسازی شوند.
پاسخ کامل
دو باگ موجود
این درس به گزارش باگی از یک پروژهی منبعباز در مارس 2026 اشاره میکند که دقیقاً همین ساختار را داشت: فایل وضعیت با یک دستور نوشتن متنی ساده ذخیره میشد و استثناها بیصدا نادیده گرفته میشدند. عملیاتهای نیمهکارهی نوشتن باعث میشدند نشستها بدون هیچ نشانهای کار را با وضعیت خراب از سر بگیرند. اولین باگ، نوشتن غیراتمیک (non-atomic write) است. دومین باگ، عبارت except است که یک شکست فاحش و پرسروصدا را به خطایی پنهان و بیصدا تبدیل میکند.
راهکار نوشتن اتمیک
- یک فایل موقت با دستور
tempfile.mkstempدر کنار فایل مقصد و درون همان دایرکتوری بسازید. - محتوا را بنویسید.
- دستور
fsyncرا اجرا کنید تا بایتها حتماً روی دیسک بنشینند. - با
os.replaceفایل موقت را جایگزین فایل مقصد کنید؛ این عملیات در هر دو سیستمعامل POSIX و Windows یک تغییر نام اتمیک (atomic rename) به حساب میآید.
فرایند خواندن همیشه یا فایل قبلی را میبیند یا فایل جدید را؛ هیچوقت حالتی میان این دو اتفاق نمیافتد.
رویکرد اسکیمامحور
فایل وضعیت حامل یک پیمان مشخص است: کلیدهای الزامی، یک فهرست شمارشی (enum) از مقادیر مجاز برای فیلد وضعیت، مقادیر غیرمجاز مانند null برای آرایهها، الگوی مشخص برای شناسهی وظایف (task ids)، و یک عدد صحیح برای schema_version. لایهی مدیریت پیش از نوشتن، دادهها را اعتبارسنجی میکند؛ بنابراین نوشتن نامعتبر بلافاصله پس زده میشود و از لود فایلی با نسخهای که امکان مهاجرت برای آن وجود ندارد نیز جلوگیری میکند. با هر بار ارتقای اسکیما، یک اسکریپت مهاجرت نیز ارائه میشود که هنگام راهاندازی، بهصورت بیاثر در تکرار (idempotent) اجرا خواهد شد.
جزئیات تکمیلی پیرامون نوشتن
- کلیدهای یکتایی تراکنش: اگر متوقف شدن برنامه درست بین فراخوانی ابزار و ثبت چکپوینت (checkpoint) آن رخ دهد، فرایند بازیابی دوباره آن ابزار را فراخوانی میکند. این موضوع برای عملیات خواندن مشکلی ندارد؛ اما برای ارسال ایمیل یا درج در دیتابیس خطرناک است. پیش از اجرا، یک رکورد آغاز فراخوانی همراه با شناسهی فراخوانی ثبت کنید و پس از اجرا، رکورد پایان را به همراه نتیجه در لاگ بیاورید. در اجرای مجدد، فراخوانیای که رکورد پایان دارد نادیده گرفته شده و از نتیجهی ذخیرهشدهاش استفاده میشود. فراخوانیای که فقط رکورد آغاز دارد ممکن است اجرا شده باشد یا نشده باشد؛ پس پیش از تکرار یا صرفنظر کردن، ابتدا وضعیت را تطبیق دهید (reconcile)؛ مثلاً از سامانهی مقصد بپرسید آیا آن کلید یکتایی اعمال شده است یا خیر.
- وضعیت کمحجم، دستسازههای مجزا: متن کامل گفتوگوها (transcripts)، فایلهای تولیدشده و مجموعهدادهها باید در فایلهای جداگانه یا در فضای ذخیرهسازی شیء (object storage) نگهداری شوند؛ فایل وضعیت فقط باید مسیر این فایلها را نگه دارد.
- لاگ رویدادها همراه با اسنپشات: هرگونه تغییر را به لاگ رویدادها (event log) اضافه کنید و طبق یک زمانبندی مشخص از وضعیت، اسنپشات (snapshot) بگیرید. هنگام ادامهی کار، سیستم اسنپشات را میخواند و رویدادهای بعدی را بازپخش (replay) میکند؛ این ویژگی همچنین امکان بازپخش تصمیمهای ایجنت را در زمان اشکالزدایی برایتان فراهم میسازد.
چه مواردی باید درون این فایل قرار بگیرند؟
شناسهی وظیفهی فعال، فایلهای دستکاریشده در این نشست، فرضیات در نظر گرفتهشده، موانع موجود و اقدام بعدی (next action). متن کامل گفتوگوها، ردگیری محاسبات استدلال (reasoning traces)، نمونه خروجیهای مدل یا شناسهی مدلهای ارائهدهندگان نباید در این فایل ذخیره شوند. ملاک سنجش این است: آیا ذخیرهی این مورد سه ماه بعد در اجرای مجدد CI بهدرد میخورد یا خیر؟
سؤالهای تکمیلی مصاحبهگر
- سطح 3: چرا فایل موقت در همان دایرکتوری فایل مقصد ایجاد میشود؟ انتظار میرود: تا مرحلهی پایانی عملیات، یک تغییر نام در همان سیستم فایل باشد و خصلت اتمیک خود را حفظ کند؛ دستورالعمل درس عبارت است از: فایل موقت کنار مقصد، نوشتن، همگامسازی و در نهایت جایگزینی.
- سطح 4: اگر ایجنت پس از فراخوانی ابزار و پیش از ثبت چکپوینت متوقف شود، چه مشکلی در بازیابی پیش میآید و راهحل چیست؟ انتظار میرود: فراخوانی دوباره تکرار میشود که این امر برای کارهایی مثل ارسال ایمیل یا درج در دیتابیس خطرناک است؛ باید پیش از اجرا رکورد آغاز همراه با شناسهی فراخوانی، و پس از اجرا رکورد پایان همراه با نتیجه لاگ شود؛ از نتیجهی فراخوانی کاملشده مجدداً استفاده شود، و فراخوانیای که صرفاً رکورد آغاز دارد قبل از تکرار اعتبارسنجی و تطبیق داده شود.
- سطح 4: اگر دو ایجنت با فاصلهی 50 میلیثانیه روی یک فایل وضعیت بنویسند، تغییر نام اتمیک مانع از چه چیزی میشود و جلوی چه چیزی را نمیگیرد؟ انتظار میرود: مانع از نصفهکاره ماندن و خرابی ساختار فایل میشود؛ بنابراین هر خوانندهای یک نسخهی کامل را میبیند؛ اما جلوی رونویسی و جایگزین شدن فایل دوم روی فایل اول را نمیگیرد که برای حل این مشکل، نیاز به هماهنگی بین نویسندهها داریم.
- سطح 4: چه چیزهایی باید در فایل وضعیت ذخیره شوند و چه چیزهایی نباید؟ انتظار میرود: وظیفهی فعال، فایلهای تغییریافته، فرضیات، موانع و اقدام بعدی ذخیره شوند؛ متن گفتوگوها، ردگیری محاسبات استدلال، خروجیهای مدل یا شناسهی مدلهای ارائهدهندگان نباید ذخیره شوند و دستسازههای (artifacts) حجیم نیز تنها از طریق مسیر فایل ارجاع داده شوند.
جوابهای اشتباهی که مصاحبهگرها زیاد میشنوند
- «استثنا را بگیرید و به کار ادامه دهید، در نوشتن بعدی درست میشود.» بلاک
exceptبیصدا دومین باگ این کد است؛ چون باعث پنهان ماندن یک فایل ناقص میشود که نشست بعدی آن را لود خواهد کرد. - «دادهها را در یک فایل موقت بنویسید، سپس آن را روی فایل مقصد کپی کنید.» عملیات کپی هم ممکن است نیمهکاره قطع شود؛ بخش اتمیک کار دقیقاً همان تغییر نام است.
- «متن کامل گفتوگوها را در وضعیت ذخیره کنید تا چیزی گم نشود.» متن گفتوگوها جزو دادههای تلهمتری (telemetry) هستند، نه وضعیت پایدار؛ فایل را کوچک نگه دارید، دستسازهها را در فایلهای جداگانه قرار دهید و فقط مسیرشان را در وضعیت ثبت کنید.
کجای دوره آموزش داده میشود
درس حافظهی مخزن، دستورالعمل نوشتن اتمیک، رویکرد اسکیمامحور، کلیدهای یکتایی تراکنش و الگوی لاگ رویدادها را آموزش میدهد.