دفتر کل JSON؛ راهکار جدید برای همگام‌سازی عامل‌های Claude و Codex

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

بر اساس مستندات این پروژه، یک اسکریپت ۱۲۰ خطی با Node.js اکنون هماهنگی بین Claude و Codex را در یک خط لوله تولید محتوا مدیریت می‌کند. توسعه‌دهنده با پیاده‌سازی یک دفتر کل انتقال (Handoff Ledger) مبتنی بر JSON، توانسته ۱۱۴ چرخه بازبینی مقاله را بدون حتی یک شکست در هماهنگی ردیابی کند. این سیستم تضمین می‌کند که عامل‌ها (Agents) — همان برنامه‌های هوش مصنوعی که می‌توانند هدفمند عمل کنند — حتی پس از پایان جلسه کاری خود، بتوانند وضعیت آمادگی و رای نهایی را از طریق یک فایل ماندگار منتقل کنند.

این معماری شکافی حیاتی در جریان‌های کاری عامل‌محور (Agentic) را پر می‌کند؛ جایی که جلسات مستقل در GitHub Actions نمی‌توانند به‌صورت آنی با هم صحبت کنند. مشکل این است که Claude یک مقاله می‌نویسد و جلسه او بسته می‌شود، در حالی که Codex در یک جریان کاری مجزا که با یک commit تحریک شده، بازبینی را آغاز می‌کند. تا زمانی که Codex رای خود را بنویسد، جلسه Claude دیگر وجود ندارد. در حالی که ما پیش‌تر بررسی کردیم که چگونه Claude می‌تواند بدهی فنی ایجاد کند — مثلاً با تولید صدها اندازه فونت هاردکد شده — این رویکرد جدید بر نظم عملیاتی لازم برای حسابرسی و تأیید خروجی هوش مصنوعی تمرکز دارد. این مدل از سیستم ناپایدار «اعلان‌های فشاری» (Push) به سمت یک وضعیت پایدار و تحت کنترل نسخه حرکت کرده است. این رویکرد یادآور راهکارهای Armorer Labs است که برای حل شکاف نظارتی در سامانه‌های چندعاملی از رسیدهای تحویل استفاده کردند.

سازوکار دفتر کل مبتنی بر بازیابی

برخلاف سیستم‌های Push که در آن یک عامل پایان کار را به دیگری خبر می‌دهد (که برای سرویس‌های در حال اجرای مداوم مناسب است)، این سیستم از روش نظرسنجی (Polling) استفاده می‌کند. از آن‌جایی که عامل‌های مبتنی بر cron اجرا شده، کار خود را انجام داده و سپس بسته می‌شوند، هیچ شنونده فعال برای دریافت اعلان وجود ندارد. بنابراین، خودِ مخزن (Repository) به عنوان وضعیت مشترک عمل می‌کند. یک فایل JSON در مسیر data/coordination/codex-handoffs.json وضعیت هر Task را ذخیره می‌کند.

این الگو دقیقاً شبیه خودِ گیت است: یک commit یک رکورد در فضای ذخیره‌سازی مشترک است، نه یک پیام برای مشترکان. با انتخاب یک دفتر کل شفاف در مخزن، توسعه‌دهنده نیاز به سرویس‌های خارجی، چرخش توکن‌های احرازی و پرش‌های شبکه اضافی را حذف کرده است. چون خط لوله CI پیش از این از مخزن به عنوان منبع حقیقت استفاده می‌کرد، قرار دادن دفتر کل در اینجا تداوم کامل داده‌ها را تضمین می‌کند. این بهره‌گیری از زیرساخت گیت برای مدیریت وضعیت، مشابه آن چیزی است که در به‌کارگیری چارچوب GitOps برای کاهش زمان دیباگ عامل‌ها مشاهده شده است.

جزئیات ساختار دفتر کل

هر رکورد در این دفتر کل ساختاری دقیق برای تضمین پاسخگویی دارد. برای مثال، یک رکورد نمونه برای article-114-review شامل موارد زیر است:

• شناسه و مرحله: یک ID منحصر‌به‌فرد (مانند article-114-review) و یک شناسه‌ی متنی برای مرحله (مانند article-review).
• مالکیت: فیلدهای owner (که به codex اختصاص یافته) و requester (که به claude اختصاص یافته) جهت مستندسازی قصد و نیت عملیات.
• مسیر اثر: مسیر دقیق فایل مورد نظر، مانند content/articles/114-2026-07-20-notable-this-week.md.
• برچسب‌های زمانی: زمان‌های started_at و updated_at با استاندارد ISO (برای مثال 2026-07-20T22:08:36.527Z) برای ایجاد یک ردپای دقیق حسابرسی.
• کنترل زمان: مقدار max_silence_minutes و برچسب زمانی next_check_at برای مدیریت زمان‌بندی بررسی‌ها.
• یادداشت‌ها: یک فیلد note خالی برای افزودن زمینه‌های اضافی در صورت نیاز.

منطق عملیاتی و مدیریت خطا

هسته هماهنگی بر پایه فیلد next_check_at می‌چرخد. این برچسب زمانی به درخواست‌کننده می‌گوید دقیقاً چه زمانی دوباره دفتر کل را چک کند. وقتی یک تسک در جریان (In-flight) است، این مقدار را نگه می‌دارد و به محض تکمیل تسک، این مقدار برابر با null قرار می‌گیرد. سیستم از سه فرمان Node.js برای مدیریت چرخه حیات استفاده می‌کند:

• start: ثبت یک تسک بازبینی جدید. برای مثال: node scripts/codex-handoff.mjs start --id article-115-review --stage article-review --artifact content/articles/115-2026-07-21-....md --check-in 10. پرچم --check-in 10 زمان بررسی اولیه را ۱۰ دقیقه بعد تنظیم می‌کند. اگر تسکی با همین ID فعال باشد، این فرمان خطا می‌دهد تا از بازنویسی‌های خاموش (Silent Overwrites) که پیش‌تر در سیستم auto-tuner نویسنده رخ می‌داد، جلوگیری شود.
• check: بررسی دفتر کل. اگر زمان next_check_at یک تسک فعال گذشته باشد اما تسک همچنان در حال اجرا باشد، با کد خروجی ۳ می‌بندد؛ در غیر این صورت اگر همه چیز مرتب باشد، کد ۰ می‌دهد. یک گام در CI مستقیماً از این کد خروجی برای تصمیم‌گیری استفاده می‌کند.
• complete: علامت‌گذاری پایان کار: node scripts/codex-handoff.mjs complete --id article-115-review. این فرمان معمولاً به عنوان آخرین گام در جریان کاری بازبینی Codex فراخوانی می‌شود.

برای جلوگیری از ایجاد «تسک‌های زامبی» که ناشی از پیکربندی‌های غلط تحریک‌کننده (Trigger) در CI هستند، اسکریپت از متغیر max_silence_minutes (تنظیم شده روی ۳۰ دقیقه) استفاده می‌کند. اگر مجموع زمان started_at به‌علاوه max_silence_minutes سپری شده باشد و تسک همچنان در جریان باشد، فرمان check بدون توجه به مقدار next_check_at آن را به عنوان خطا علامت می‌زند. این تضمین می‌کند که اگر جریان کاری Codex هرگز اجرا نشود، شکست سیستم برملا شود و پنهان نماند.

زیرساخت و مقیاس‌پذیری

انتخاب این روش برای حذف سربار سرویس‌های خارجی و تأخیر شبکه بود. با ثبت مستقیم دفتر کل در مخزن، سیستم یک ردپای حسابرسی رایگان از طریق دستور git log -p -- data/coordination/codex-handoffs.json به دست می‌آورد. این به توسعه‌دهنده اجازه می‌دهد دقیقاً ببیند یک تسک چه زمانی ثبت و چه زمانی تکمیل شده است. در حال حاضر، این سیستم به‌طور طبیعی با کلاینت ETL مدل Claude Haiku یکپارچه شده است، جایی که هر جلسه با کلون کردن مخزن، به وضعیت کامل دسترسی پیدا می‌کند.

طبق گزارشی که در ژوئیه ۲۰۲۶ منتشر شد، اندازه فعلی دفتر کل برای ۱۱۴ تسک حدود ۱۸ کیلوبایت است. با این حال، نویسنده سه محدودیت فنی اصلی را برای رشد آینده شناسایی کرده است:

• اندازه فایل: زمانی که حجم JSON از ۱۰۰ کیلوبایت عبور کند، یک مرحله پاک‌سازی (Trim pass) اضافه خواهد شد تا ورودی‌های قدیمی‌تر از ۳۰ روز به فایل codex-handoffs-archive.json منتقل شوند تا از بهینه‌سازی زودرس جلوگیری شود.
• شفافیت: در حال حاضر خروجی‌های check به stdout می‌روند. نویسنده پیشنهاد می‌کند از $GITHUB_STEP_SUMMARY برای نمایش هشدارها در تب Actions استفاده شود، زیرا چهار اسکریپت فعلی کنترل کیفیت محتوا (QC) نقطه کور مشابهی دارند؛ جایی که کدهای خروجی درست هستند اما خروجی‌ها برای اسکن کردن دشوارند.
• هم‌زمانی: ساختار فعلی فرض می‌کند کامیت‌ها متوالی هستند. اگر پردازش‌های موازی وارد شوند، نویسنده مهاجرت از JSON به SQLite را پیشنهاد می‌کند تا نوشتن‌های هم‌زمان به‌طور بومی مدیریت شوند و از شکست‌های خاموش جلوگیری شود.

جمع‌بندی نهایی الگو

این پیاده‌سازی که بخشی از یک آزمایش ۶ ماهه روی سه سایت دایرکتوری مدیریت شده با AI است، ثابت می‌کند که هماهنگی ساده و فایل-محور می‌تواند از معماری‌های پیچیده مبتنی بر رویداد (Event-driven) برای عامل‌های دسته‌ای (Batch-processed) قابل‌اعتمادتر باشد. این روش هیچ وابستگی خارجی جز کتابخانه استاندارد Node.js ندارد.

انتخاب یک دفتر کل شفاف و ثبت‌شده، خطاهای آشکار را بر بازیابی‌های خاموش ترجیح می‌دهد. در خط لوله‌های هوش مصنوعی، خطایی که برملا شود، باگی است که می‌توان آن را اصلاح کرد، اما بازیابی خاموش اغلب انحراف عمیق در رفتار مدل را می‌پوشاند. این رویکرد تمرکز را از اجرای «روان» به اجرای «قابل حسابرسی» تغییر می‌دهد. توسعه‌دهندگانی که خط لوله‌های چند-عاملی را مدیریت می‌کنند باید ارزیابی کنند که آیا مدیریت وضعیت فعلی آن‌ها پس از پایان جلسه (Session Termination) دوام می‌آورد یا خیر. شما می‌توانید برای حذف وابستگی به APIهای خارجی در جریان‌های کاری ناهمگام بعدی خود، رویکرد مشابه دفتر کل JSON را آزمایش کنید.

گام بعدی شما

• اگر جریان‌های کاری ناهمگام دارید، وابستگی به APIهای خارجی برای مدیریت State را حذف و از یک فایل JSON در مخزن استفاده کنید.
• برای هر تسک، حتماً یک Brach-out Timestamp (مثل max_silence_minutes) تعریف کنید تا از گم شدن تسک‌های شکست‌خورده جلوگیری شود.
• در صورت افزایش حجم تراکنش‌های هم‌زمان، سریعاً از JSON به SQLite مهاجرت کنید تا از تداخل در نوشتن داده‌ها جلوگیری شود.

اما تأثیر این مدل بر کاهش هزینه‌های استنتاج در مقیاس بالا جالب‌تر است — به تحلیل ما درباره مدیریت منابع GPU مراجعه کنید.