«سفر پیاده‌سازی»؛ متد جدید Docket برای نمایش استدلال‌های عامل‌های کدنویس

تصور کنید یک همکار برنامه‌نویس کدی را به شما تحویل می‌دهد که در ظاهر درست کار می‌کند، اما شما نمی‌دانید او برای رسیدن به این جواب چه مسیرهای غلطی را طی کرده است. اگر از عامل‌های کدنویس استفاده می‌کنید، احتمالاً با همین «جعبه سیاه» مواجهید؛ جایی که شما فقط مقصد را می‌بینید، نه سفر را.

Docket که در ۱۳ سپتامبر ۲۰۲۶ منتشر شد، دقیقاً همین شکاف را پر می‌کند. این ابزار هر گام استدلالی، هر تلاش ناموفق و هر بررسی تأییدی را که یک عامل (Agent) — شبیه به دستیاری که هم‌زمان کد می‌زند و یادداشت برمی‌دارد — پیش از ثبت نهایی کد انجام می‌دهد، ضبط می‌کند. طبق گزارش مستندات این پروژه، عامل‌های کدنویس اکنون با سرعتی تغییرات را اعمال می‌کنند که بازبینی انسانی آن‌ها عملاً غیرممکن است.

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

برای مثال، سناریویی را تصور کنید که در آن یک عامل سه روش مختلف برای رفع یک باگ امتحان می‌کند، در دو مورد اول شکست می‌خورد و در نهایت موفق می‌شود. بدون داشتن یک رکورد، بازبین فقط موفقیت نهایی را می‌بیند. او هیچ راهی ندارد تا بداند آیا عامل در مسیر رفع باگ قدیمی، به‌طور اتفاقی باگ جدیدی ایجاد کرده یا اینکه راهکار نهایی صرفاً تنها گزینه‌ای بوده که باعث کرش کردن مجموعه تست‌ها (Test Suite) نشده است.

مکانیزم ثبت شواهد

Docket به‌عنوان یک رکورد شواهد برای هر کامیت عمل می‌کند و سفر عامل را در مقابل تغییرات نهایی (Diff) قرار می‌دهد. این ابزار برای هر بخش از کد (Hunk) یک رکورد شواهد تولید می‌کند تا توجه انسان دقیقاً روی نقاطی متمرکز شود که شواهدی برای آن‌ها وجود ندارد.

به نقل از مستندات پروژه، وقتی کاربر دستور docket show HEAD را اجرا می‌کند، جزئیات دقیقی از کامیت را می‌بیند. برای مثال، یک رکورد ممکن است یک کد شناسایی SHA256 خاص (مانند sha256:046c5278e93cb516e3ba72400fd1a69648c85b93833d31d57648e9ed8e535ebf) و یک سطح اعتماد را نمایش دهد. این گزارش تعداد Hunkها، فایل‌ها و خطوط اضافه شده را به همراه میانگین «تراکم شواهد» (Evidence Density) لیست می‌کند.

در یک نمونه واقعی از رفع مشکل Session Fixation در فایل src/auth.js:3-6، این ابزار نشان می‌دهد که ۴ خط اضافه شده، ۱۰۰٪ به یک ویرایش ثبت‌شده مربوط است و تراکم شواهد آن ۰.۷۷ است. همچنین وظیفه (Task) و استدلال عامل را ثبت کرده است: «وظیفه: رفع مشکل Session Fixation در هنگام قصد ورود؛ استدلال: UUID خام در ورودها تکرار می‌شود، بنابراین یک ID پیشوندی ایجاد می‌کنم».

بر اساس مستندات گیت‌هاب، این سیستم سه میدان اصلی را برای پاسخ به سؤال «چرا کد این‌گونه است» دنبال می‌کند:

• وظیفه (Task): درخواست اصلی انسان (مثلاً: «رفع مشکل Session Fixation در هنگام قصد ورود»).
• قصد (Intent): استدلال بیان‌شده توسط عامل درست پیش از انجام ویرایش. اینجاست که استدلال با کلمات خود عامل ثبت می‌شود (مثلاً: «Postgres jsonb ترتیب کلیدها را نرمال‌سازی می‌کند... بنابراین json نوع ستون مناسب‌تری است»).
• تلاش (Attempt): کدهایی که در یک ناحیه نوشته شده و سپس حذف شده‌اند، شامل بررسی خاصی که با شکست مواجه شده است. برای مثال، یک عامل ممکن است سعی کند «زمان ایجاد را روی جلسه ثبت کند تا انقضا قابل بررسی باشد»، اما دستور npx vitest run شکست بخورد و این تلاش به‌عنوان [superseded] یا جایگزین‌شده علامت بخورد. این رویکردهای رها شده، بخش‌هایی هستند که در غیر این صورت ظرف چند ساعت برای همیشه گم می‌شدند. این نوع ثبت دقیق از تاریخچه، شباهت زیادی به سیستم RepoTrials دارد که تاریخچه گیت را به بنچ‌مارک‌های اختصاصی تبدیل می‌کند تا عملکرد عامل‌ها ارزیابی شود.

انتساب فنی و اعتبارسنجی

برای تضمین دقت، Docket از یک بردار منشأ (Provenance Vector) برای ردیابی هر خط کد استفاده می‌کند. این ابزار رونوشت‌های عامل را به یک جریان رویداد مرتب تبدیل کرده و هر ویرایش را بازپخش می‌کند. یک خط تنها زمانی به یک ویرایش نسبت داده می‌شود که متن آن در موقعیت دقیق تراز شده در خروجی ثبت‌شده یافت شود.

اگر انسانی یا یک دستور شل، فایل را بین ویرایش عامل و کامیت تغییر دهد، Docket این عدم تطابق را تشخیص می‌دهد. این ابزار به‌جای حدس زدن، آن خطوط را «نامشخص» (Unknown) علامت می‌زند. این رویکرد مانع از ارائه «پاسخ‌های با اعتمادبه‌نفس اما غلط» می‌شود؛ خطایی که در بسیاری از ابزارهای انتساب AI رایج است. یک موتور انتساب که با اعتمادبه‌نفس پاسخ غلط می‌دهد، بدتر از نبودِ محصول است.

یکپارچگی و ابزارها

این ابزار به‌گونه‌ای طراحی شده که مستقل از نوع عامل باشد (Agent-agnostic) و در حال حاضر از خواننده‌های (Readers) Claude Code، Codex CLI و opencode پشتیبانی می‌کند:

• Claude Code: فایل‌های .jsonl را از مسیر ~/.claude/projects/ می‌خواند تا فراخوانی‌های Edit/Write، دستورات شل و روایت‌ها (Narration) را ثبت کند.
• Codex CLI: فایل‌های rollout-*.jsonl را از مسیر ~/.codex/sessions/ می‌خواند تا فراخوانی‌های apply_patch و کدهای خروج (Exit codes) را ثبت کند.
• opencode: از یک پایگاه‌داده SQLite در مسیر ~/.local/share/opencode/opencode.db برای ردیابی فراخوانی‌های نوشتن و ویرایش استفاده می‌کند.

برای عامل‌هایی که فایل‌ها را از طریق شل می‌نویسند (با استفاده از sed -i، heredocs یا ژنراتورها)، Docket از قلاب‌های PreToolUse و PostToolUse برای ثبت وضعیت لحظه‌ای (Snapshot) درخت کاری و ذخیره تغییرات به‌عنوان git blobs استفاده می‌کند. این تغییرات به‌جای «رونوشت» (Transcript)، به‌عنوان «مشاهده شده» (Observed) علامت می‌خورند.

جزئیات گردش کار گیت

این ابزار مستقیماً با گردش کار گیت از طریق چندین مکانیزم ادغام می‌شود:

• قلاب prepare-commit-msg: یک تریلر (Trailer) به پیام کامیت اضافه می‌کند (مثلاً Docket: sha256:db77fdb4...) در جایی که Signed-off-by و Reviewed-by قرار دارند. نکته مهم این است که عامل مورد بازبینی هرگز رکورد حسابرسی خود را نمی‌نویسد.
• قلاب post-commit: رکورد واقعی را در یک رفرنس یتیم (refs/docket/*) در داخل مخزن ذخیره می‌کند.
• GitHub Action: این رکوردها را در هنگام Pull Requestها می‌خواند و ترتیب Diff را به‌گونه‌ای تغییر می‌دهد که Hunkهای تأییدنشده در ابتدا ظاهر شوند، در حالی که کدهای تکراری (Boilerplate) که پوشش خوبی دارند، جمع (Collapse) شوند. این اکشن همان باینری نصب محلی را دانلود می‌کند و نیازی به تنظیمات Runner ندارد.
• ردپای کامیت (Commit Footprint): تنها تغییر در تاریخچه، یک خط اضافه در بلوک تریلر است. دستور git log --oneline بدون تغییر باقی می‌ماند و خطوط موضوع (Subject lines) دست‌نخورده می‌مانند.
• یکپارچگی تاریخچه: چون کد هضم (Digest) به یک رکورد امضا شده در refs/docket/records اشاره می‌کند و نه به یک URL، تاریخچه به وجود یک سرویس خارجی وابسته نیست.
• موارد خاص (Edge Cases): اصلاح یک کامیت (Amending) باعث بازسازی رکورد و جایگزینی تریلر می‌شود. ادغام‌ها (Merges) و کامیت‌های بدون محتوای قابل انتساب، تریلری دریافت نمی‌کنند. در مورد Rebase و Cherry-pick، چون گیت قلاب prepare-commit-msg را برای آن‌ها اجرا نمی‌کند، ممکن است تریلر به Diffی منتقل شود که برای آن ساخته نشده است. در این موارد، دستور docket verify عدم تطابق را به‌وضوح گزارش می‌کند.

اندازه‌گیری تراکم شواهد

Docket برای هر بخش کد، امتیازی بین ۰ و ۱ برای «تراکم شواهد» محاسبه می‌کند. این یک امتیاز کیفی کلی نیست، بلکه مجموع وزنی از واقعیت‌های قابل تأیید است:

• پوشش (Coverage): تا ۰.۵ امتیاز. این مقدار به‌صورت خط‌به‌خط با گزارش‌های istanbul (coverage-final.json) یا lcov تطبیق داده می‌شود. گزارش‌های قدیمی‌تر از کد نادیده گرفته می‌شوند.
• اجرای تست: یک بررسی موفق پس از ویرایش، ۰.۳ امتیاز اضافه می‌کند (یا ۰.۳۵ اگر تغییر باعث تبدیل یک تست شکست‌خورده به موفق شده باشد).
• تحلیل استاتیک: بررسی‌های نوع (Type checks) و تحلیل‌های استاتیک مجموعاً ۰.۱ امتیاز می‌آورند.
• تعامل انسانی: ثبت تعامل انسان ۰.۱ امتیاز اضافه می‌کند.

اگر هیچ کدی اجرا نشده باشد، امتیاز حداکثر ۰.۱۵ است. اگر نویسنده نامشخص باشد، امتیاز حداکثر ۰.۵ است. یک رکورد که به‌صورت محلی ادعا شده است، ۰.۹ امتیازِ رکوردی را می‌گیرد که توسط CI تأیید شده است. این سیستم تضمین می‌کند کدهای ساده و تکراری صرفاً به‌دلیل سادگی، باکیفیت جلوه نکنند.

عملکرد و حریم خصوصی

در تست‌های اندازه‌گیری داخلی با استفاده از docket gate، این ابزار به دقت انتساب بالایی دست یافت:

• موتور Laravel (Claude Code): ۹۸.۱٪ Hunkها در فایل‌های ویرایش‌شده، ۹۹.۸٪ محتوای تأییدشده و ۱۰۰٪ خطوط اضافه شده.
• اپلیکیشن پایتون (Codex CLI): ۹۴.۷٪ Hunkها در فایل‌های ویرایش‌شده، ۹۵.۷٪ محتوای تأییدشده و ۹۹.۸٪ خطوط اضافه شده.
• پروژه FastAPI (opencode): ۹۲.۹٪ Hunkها در فایل‌های ویرایش‌شده.
• فریم‌ورک PHP (Claude Code از طریق شل): ۵۹.۲٪ Hunkها در فایل‌های ویرایش‌شده، ۸۲.۱٪ محتوای تأییدشده و ۱۰۰٪ خطوط اضافه شده.

در کل Diffها، نرخ‌های کلی پایین‌تر است (مثلاً ۳۷٪ تا ۹۴٪) زیرا کامیت‌های واقعی شامل فایل‌هایی مانند composer.lock یا مدل‌های اسکلتی هستند که هیچ عاملی هرگز آن‌ها را لمس نکرده است. Docket این موارد را به‌جای میانگین‌گیری، به‌عنوان «نامشخص» گزارش می‌کند.

در مورد حریم خصوصی، Docket از یک لایه حذف داده‌های حساس (Redaction) تهاجمی استفاده می‌کند. این ابزار کل رونوشت‌ها یا فایل‌ها را ذخیره نمی‌کند، زیرا ممکن است حاوی اسرار (Secrets) باشند. این ابزار الگوهای شناخته‌شده اعتبارنامه‌ها، کلیدهای خصوصی، JWTها، هدرهای احراز هویت و هر توکن تصادفی طولانی را حذف می‌کند. تمام رکوردها امضا شده‌اند؛ رکوردهای ایجاد شده در ماشین توسعه‌دهنده به‌عنوان local_claimed و رکوردهای CI (با استفاده از DOCKET_SIGNING_KEY در CI) به‌عنوان ci_attested علامت می‌خورند.

نصب و نگهداری

این ابزار به‌عنوان یک باینری استاتیک واحد توزیع می‌شود و نیازی به زنجیره ابزار Go یا Runtime ندارد. نصب آن از طریق یک اسکریپت شل ساده انجام می‌شود: curl -fsSL https://raw.githubusercontent.com/Dillonsmart/docket/main/install.sh | sh. هر نسخه دارای فایل SHA256SUMS است که نصب‌کننده آن را تأیید می‌کند.

به‌روزرسانی با اجرای مجدد نصب‌کننده انجام می‌شود. برای تثبیت روی یک نسخه خاص، کاربران می‌توانند متغیر DOCKET_VERSION را تنظیم کنند (مثلاً DOCKET_VERSION=v0.0.2). توجه داشته باشید که این متغیر باید در سمت sh لوله (Pipe) باشد تا برای اسکریپت مؤثر باشد.

به‌دلیل داشتن نسخه طرح‌واره (Schema) در هر رکورد، نیازی به مهاجرت داده‌ها در هنگام به‌روزرسانی نیست. تنها وضعیت محلی، کلید امضا در .git/docket/ است که در طول به‌روزرسانی‌ها دست‌نخورده می‌ماند. کاربران تنها در صورتی که باینری به دایرکتوری جدیدی منتقل شود، نیاز به اجرای مجدد docket init دارند، زیرا قلاب‌ها آن را با مسیر مطلق فراخوانی می‌کنند.

کاربران همچنین می‌توانند از طریق سورس با دستور go install github.com/Dillonsmart/docket/cmd/docket@latest آن را بسازند. برای کسانی که می‌خواهند بدون ابزارسازی کد خود، آن را تست کنند، Docket می‌تواند یک مخزن موقت در دایرکتوری temp بسازد تا نحوه رفع باگ Session Fixation توسط یک عامل (با یک بار شکست و یک بار موفقیت) را نمایش دهد. این دایرکتوری دمو در هنگام خروج حذف می‌شود.

دستورات عملیاتی

توسعه‌دهندگان می‌توانند از طریق چندین دستور تخصصی با رکورد شواهد تعامل داشته باشند:

• docket show HEAD: نمایش رکورد یک کامیت، مرتب شده بر اساس سطح ریسک.
• docket explain <file:line>: استفاده از git blame برای یافتن کامیت و توضیح دلیل وجود یک خط خاص.
• docket review --format md: تولید یک کامنت برای Pull Request.
• docket verify HEAD: بررسی کد هضم، امضا و اتصال به کامیت.
• docket push: ارسال رکوردها به میزبان گیت ریموت.
• docket doctor: تشخیص آنچه ابزار در محیط فعلی می‌تواند یا نمی‌تواند ببیند.
• docket gate --commits 20: اندازه‌گیری صحت انتساب در برابر تاریخچه واقعی.

این تغییر، فرآیند بازبینی AI را از «اعتماد به خروجی» به «تأیید فرآیند» منتقل می‌کند. با نمایش رویکردهای رها شده و تست‌های شکست‌خورده، Docket جعبه سیاه کدنویسی عامل‌محور را به یک ردپای حسابرسی شفاف تبدیل می‌کند. فرمت رکورد به‌عنوان «رکورد شواهد کامیت» تحت لایسنس Apache 2.0 تعریف شده است تا ساده و توسط ابزارهای دیگر قابل پیاده‌سازی باشد.

وضعیت فعلی و نقشه راه

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

• خواننده‌های در انتظار: پشتیبانی از Gemini CLI و عامل‌های ACP-native.
• گسترش پوشش: همبستگی فراتر از istanbul و lcov.
• پشتیبانی از پلتفرم: یکپارچگی با GitLab.
• ویژگی‌های پیشرفته: تجمیع بین‌مخزنی، لایه‌های سیاست‌گذاری (Policy gates) روی مسیرهای خاص و یک سطح اشتراکی برای تیم‌ها.

گام بعدی شما

• اگر از Claude Code یا Codex CLI استفاده می‌کنید، Docket را نصب کنید تا متوجه شوید عامل شما کجاها «شانس آورده» و کجاها واقعاً استدلال کرده است.
• در Pull Requestهای بعدی، به‌جای خواندن خط‌به‌خط کد، ابتدا بخش‌های «فاقد شواهد» (Unverified) را بررسی کنید.
• دستور docket explain را برای تحلیل کدهای قدیمی که توسط AI نوشته شده‌اند به کار ببرید.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.