بازبینی هوش مصنوعی

شکل یک بازبینی

بازبینی هوش مصنوعی یک اجرای پایپ‌لاین از پیش تعریف‌شدهٔ pr_review روی یک pull request باز است. پایپ‌لاین فضای بازبینی PR را باز می‌کند، عامل‌های بازبین را پخش می‌کند تا دیف را در checkout جداشدهٔ آن فضا بخوانند، هرکدام یافته‌هایش را به‌صورت گره‌های بازبینی ساختاریافته ثبت می‌کند، یک عامل راهبر آن‌ها را در قالب یک مرور گام‌به‌گام یکپارچه می‌کند و یک نهایی‌ساز یک حکم می‌سازد: Ship، Hold یا Block. آنچه پایپ‌لاین هرگز انجام نمی‌دهد انتشار است — ارسال به GitHub گامی جداگانه و آگاهانه است که یک انسان برمی‌دارد.

ادامهٔ این صفحه اجزا را توضیح می‌دهد و اینکه چرا این شکل را دارند.

یک فضای بازبینی برای هر PR

بافت بازبینی یک PR یک فضای پیام‌رسانی است — حالت review، نوع pr — که با یک پیوند فضای بازبینی به pull request وصل می‌شود. به‌شکل خودتکرار ساخته می‌شود: صفحهٔ PR، پایپ‌لاین بازبینی و سطوح گفتگو همگی فضای پشتیبان یکتای PR را از مسیر کد یکسانی حل می‌کنند، بنابراین قالبی که PR را بازبینی می‌کند و انسانی که بازش می‌کند هرگز نمی‌توانند به دو اتاق متفاوت و روبه‌روی دو checkout متفاوت برسند.

worktree جداشدهٔ فضا، PR را روی head ref آن checkout کرده دارد. یک اتاق یعنی یک checkout: هر بازبین در همان فضا کار می‌کند، نه اینکه هرکدام کلون خودش از فضای کاری را بگیرد.

هر بازبین در جریان نام‌دار خودش درون همان یک فضا می‌نویسد و یافته‌ها پیام‌های review_node هستند، نه متن ساده. گردآوری فضاعرض در پایان آگاهانه است — حکمی که از یافته‌های یک رشته محاسبه شود، بی‌سروصدا حکمی دربارهٔ یک بازبین خواهد بود.

این پیوند یک نردبان وضعیت دارد — requested → in progress → awaiting approval → completed — و همان است که انتشار در GitHub را در زبانهٔ بازبینی PR دروازه‌بانی می‌کند.

سطح‌های بازبینی

اینکه بازبینی تا چه عمقی می‌رود یک سیاست فضای کاری با سه سطح است که در تنظیمات → فضای کاری → عمومی، روی کارت سیاست فضای کاری تنظیم می‌شود:

سطح	بازبین‌هایی که پخش می‌شوند	گزارش‌دهی
light	فقط مهندس	فقط آنچه واقعاً مهم است
balanced	مهندس، تضمین کیفیت، معمار (پیش‌فرض)	بررسی استاندارد
thorough	هر پنج مورد، شامل امنیت و عملکرد	هیچ یافته‌ای تنزل داده نمی‌شود

سطح، دو تنظیم را هم‌زمان تغییر می‌دهد: اینکه کدام بازبین‌ها پخش شوند — که با دروازه‌های وضعیت runWhen در قالب پایپ‌لاین اعمال می‌شود، نه با جمله‌بندی پرامپت؛ جمله‌بندی پرامپت را می‌توان نادیده گرفت، اما دروازه را نمی‌توان — و اینکه یافته‌های زیر آستانه کجا نمایش داده شوند. هیچ‌کدام از این دو تنظیم هرگز یافته‌ای را حذف نمی‌کند: سطحی که کمتر گزارش می‌دهد، باز هم دقیقاً همان‌قدر ثبت می‌کند و باقی را گروه‌بندی می‌کند.

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

گره‌های بازبینی: یافته به‌مثابهٔ داده، نه متن

یافته‌ای که با add_review_node ثبت می‌شود به یک گرهٔ بازبینی روی PR تبدیل می‌شود — همان چیزی که زبانهٔ بازبینی نمایش می‌دهد، حکم از آن محاسبه می‌شود و “انتشار در GitHub” آن را به یک نظر درون‌خطی تبدیل می‌کند. بازبینی که فقط متن برمی‌گرداند، یک اجرای پایپ‌لاین ظاهراً موفق و یک سطح بازبینی خالی تولید می‌کند؛ ثبت کردن، بخش باربر است.

هر گره این‌ها را همراه دارد:

فیلد	مقدارها
نوع	bug، suggestion، recommendation، question، ticket
اولویت	P0 (بحرانی) → P3 (جزئی)
سه‌گانهٔ تریاژ	دسته (security، stability، …)، شدت، تلاش
لنگر	مسیر فایل، شروع و پایان خط
همراه اصلاح	خطوط جانشین پیشنهادی، یک دیف اختیاری، یک پرامپت اصلاح اختیاری
اطمینان	امتیازی در [0, 1]
استدلال	تحلیل، که پیش از یافته نوشته می‌شود

دو جزئیات آگاهانه‌اند. پیشنهاد یک‌کلیکی GitHub تنها زمانی ارائه می‌شود که بازبین خطوط جانشین دقیق را فراهم کرده باشد — استنباط آن‌ها از یک دیف یکپارچه بی‌سروصدا اشتباه پیش می‌رود و کامیت یک‌کلیکیِ یک استنباط اشتباه از نداشتن دکمه هم بدتر است. و شِمای add_review_node، reasoning را پیش از یافته ارائه می‌کند، بنابراین مدلی که شیء را به ترتیب شِما پر می‌کند، تحلیل را اول می‌نویسد. این فیلد اختیاری است: حذفش گره را رد نمی‌کند. گرهی که داده‌اش ناسالم باشد ناپدید می‌شود، به‌جای اینکه بازبینی را آلوده کند.

اجماع همتا

یک گره مسیر open → consensus-ready → resolved یا dismissed را طی می‌کند. گام میانی قلب این مدل است: یک یافته تنها زمانی ارتقا می‌یابد که یک بازبین همتا تأییدش کند، و یک عامل هرگز نمی‌تواند یافتهٔ خودش را تأیید کند. ابزار MCP publish_review_to_github و پیش‌فرض RPC همچنان تنها یافته‌های تأییدشدهٔ همتا را منتشر می‌کنند. در مقابل، دکمهٔ انتشار در GitHub در زبانهٔ بازبینی هر یافتهٔ باز باقی‌مانده را می‌فرستد.

این قاعده در سه جای مستقل اعمال می‌شود — ابزار تأیید، نهایی‌ساز و منتشرکننده — بنابراین از پسِ یک فراخوانِ باگ‌دار در هر کدام از آن‌ها برمی‌آید. همهٔ تغییرهای وضعیت از یک سرویس عبور می‌کنند و همین است که به وضعیت معنا می‌دهد: پیش از آن، دو مسیر نیمه‌کاره می‌توانستند دربارهٔ حل‌شدنِ یک یافتهٔ یکسان اختلاف داشته باشند.

وقتی بازبین‌ها اختلاف دارند — همان فایل و خط، اولویت‌هایی با فاصلهٔ دو سطح یا بیشتر، یا اینکه یکی آن را bug بنامد و دیگری suggestion — این اختلاف بالای فهرست یافته‌ها نمایان می‌شود. همان‌جاست که نظر بازبین‌ها واگرا می‌شود و قضاوت انسان بیشترین ارزش را دارد.

رد کردن یک یافته همچنین یک واقعیت سرکوب نرم را با اطمینان پایین در دامنهٔ حافظه می‌نویسد — یک بار رد کردن یک ترجیح است، نه یک قاعده.

گروه‌ها: بازبینی حول چه چیزی گروه‌بندی می‌شود

گذر محاسبهٔ بازبینی، فایل‌های تغییریافتهٔ یک PR را در گروههایی که از گراف کد مشتق شده‌اند گروه‌بندی می‌کند: فایل‌های تغییریافته به نمادهایی که لمس می‌کنند نگاشت می‌شوند، نمادها به اجزای هم‌بند، و گروه‌ها بر اساس شعاع اثر رتبه‌بندی می‌شوند. یک گروه به‌جای یک فهرست تخت فایل، ترتیب مطالعهٔ هدایت‌شده، نمودارها و بینش‌ها را همراه دارد.

دو قاعدهٔ صداقت این را شکل می‌دهند. کلیدهای گروه از محتوا مشتق می‌شوند و در طول pushها پایدار می‌مانند، بنابراین یافته‌ها و پیشرفت بازبینی از یک rebase یا force-push جان سالم به در می‌برند، به‌جای اینکه یتیم شوند. و وقتی مخزن نمایهٔ کد ندارد، گروه‌بندی به مسیرهای ساده عقب‌نشینی می‌کند و همین را می‌گوید — این عقب‌نشینی هرگز اطمینان معنایی را جعل نمی‌کند.

محورهای بازبینی و دروازه‌ها

در کنار یافته‌های بازبین‌ها، یک بازبینی نتایج محور جمع می‌کند: شش محور، از دو نوع.

محور	نوع	برگرفته از
correctness، security	مبتنی بر توکن	یافته‌های خود بازبین‌ها
testGap	مبتنی بر توکن	یافته‌های بازبین‌ها
visual، apiContract	قطعی	محاسبه‌شده بدون صرف توکن
performance	قطعی	فقط یک enum — هیچ‌چیز در محصول نتیجه‌ای محاسبه نمی‌کند

حکم یک محور pass، warn، fail، partial یا unavailable است — و تنها pass یا warn یک دروازه را باز می‌کند. تمایز میان fail، partial و unavailable باربر است: محوری که دروازه‌بانی می‌شود و نتوانسته کامل شود یا اصلاً نتوانسته اجرا شود، حکم کلی را نگه می‌دارد، نه اینکه آن را بگذراند. نبود شواهد هرگز به یک دروازهٔ سبز تبدیل نمی‌شود.

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

حکم

نهایی‌ساز حکم را روی یافته‌هایی با وضعیت open یا consensus-ready محاسبه می‌کند:

• هر یافتهٔ P0 با اطمینان ≥ 0.7 → Block
• در غیر این صورت، هر P0 (کم‌اطمینان) یا هر P1 → Hold
• در غیر این صورت → Ship

حکم یک اطمینان تجمعی دارد که از پراکندگی اطمینان‌های سهیم مشتق می‌شود — هم‌رأیی آن را بالا می‌برد، واگرایی پایین می‌آورد.

یکپارچه‌سازی عامل راهبر (CEO) یک گذر ویرایشی است، نه فهرست‌کردن دوباره: نسخهٔ دوم دست‌نویس از یافته‌ها دقیقاً همان چیزی است که از نسخهٔ واقعی فاصله می‌گیرد. یافته‌های تکراری تنزل داده می‌شوند نه تکرار — چند بازبین با حدودِ عمداً هم‌پوشان به یک دیف نشانه گرفته می‌شوند، پس رسیدن سه‌بارهٔ یک نقص یکسان به نهایی‌ساز یعنی سیستم دارد کار می‌کند؛ انتشار سه‌بارهٔ آن یعنی سیستم معماری خودش را در صندوق ورودی خواننده می‌ریزد. در یک بازبینی مجدد، یافته‌ها اثرانگشت می‌گیرند و با دور قبل دیف می‌شوند، بنابراین آنچه نمایان می‌شود دلتاست.

سرانجام محورها وارد می‌شوند و فقط می‌توانند حکم را سخت‌تر کنند: یک محور دروازه‌بانی‌شدهٔ مردود، Block را تحمیل می‌کند — نمی‌توان با یافته‌ها رأی آن را رد کرد — و محور دروازه‌بانی‌شده‌ای که نتوانسته کامل شود، حداقل Hold را تحمیل می‌کند.

انتشار بر عهدهٔ خودتان می‌ماند

پایپ‌لاین آگاهانه به GitHub ارسال نمی‌کند؛ انتشار به دست کاربر دروازه‌بانی می‌شود تا یک بازبینی هرگز دوبار منتشر نشود. وقتی انتشار در GitHub را فشار می‌دهید:

• یک بازبینی GitHub ثبت می‌شود. یافته‌هایی که قبلاً حل یا رد شده‌اند نادیده گرفته می‌شوند. این دکمه هر یافتهٔ باز باقی‌مانده را منتشر می‌کند (selection: all_open). ابزار MCP publish_review_to_github همچنان به‌طور پیش‌فرض فقط یافته‌های تأییدشدهٔ همتا را منتشر می‌کند (consensus).
• یافته‌های لنگرشده به یک فایل و خط به نظرهای درون‌خطی تبدیل می‌شوند؛ هر چیز دیگری در بدنهٔ خلاصه گنجانده می‌شود و هرکدام یک پایین‌بند “— Control Center AI review” همراه دارد تا منبع بی‌ابهام باشد.
• لنگرها هنگام انتشار دوباره در برابر دیف فعلی PR بازبینی می‌شوند. نظری روی کدی که پیش‌تر بازنویسی شده، بیشترین آسیب به اعتماد را می‌زند که یک بازبین می‌تواند برجای بگذارد؛ اگر GitHub به هر حال یک لنگر درون‌خطی را رد کند، کل بازبینی دوباره فرستاده می‌شود و هر یافته در بدنه گنجانده می‌شود تا چیزی بی‌سروصدا از قلم نیفتد.
• حکم Block به‌صورت REQUEST_CHANGES ثبت می‌شود؛ Hold به‌صورت COMMENT؛ Ship از طریق دکمه به‌صورت APPROVE (approve_on_ship: true). ابزار MCP، Ship را به‌صورت COMMENT رها می‌کند، مگر اینکه approve_on_ship را بفرستید.
• بازبینی تحت هویت برنامهٔ سرور ارسال می‌شود. اینکه چه کسی Publish را فشار داده برای دروازهٔ نقش و گزارش حسابرسی ثبت می‌شود؛ نویسندهٔ GitHub نیست.

انتشار کلاس کنش prPublish را اعلام می‌کند، بنابراین گلوگاه گاردریل آن را مانند هر کنش تغییردهنده‌ای دروازه‌بانی می‌کند — به‌طور پیش‌فرض درخواست تأیید می‌کند و وقتی هیچ تأییدکننده‌ای متصل نیست، به‌صورت بسته شکست می‌خورد. گاردریل‌ها را ببینید.

بازبین چه کاری می‌تواند انجام دهد

عامل‌های بازبین در حالت review اجرا می‌شوند: یک سندباکس فقط‌خواندنی و یک فهرست مجاز گزیدهٔ ابزارها که یافته‌ها، تفسیر، تیکت‌ها و بازبینی همتا را پوشش می‌دهد — اما هیچ کنش تغییردهنده‌ای. یک بازبین نمی‌تواند کدی را که نقد می‌کند اصلاح کند؛ می‌تواند یک اصلاح پیشنهادی ضمیمه کند که یک انسان اعمالش می‌کند. پیام امتناع این حالت به عاملی که به هر حال تلاش می‌کند کنش کند می‌گوید بازبینی را نهایی کند و بگذارد کاربر بر اساس خلاصهٔ منتشرشده عمل کند.

مفهوم‌های مرتبط

• گاردریل‌ها — موتور سیاستی که انتشار را دروازه‌بانی می‌کند
• حالت‌ها — حالت review چه چیزی را برای یک عامل تغییر می‌دهد
• پایپ‌لاین‌ها و خودکارسازی — موتوری که بازبینی روی آن اجرا می‌شود
• چرخهٔ عمر اعزام عامل — worktree جداشده از کجا می‌آید

راهنماهای مرتبط

• استفاده از بازبینی مبتنی بر هوش مصنوعی — یک بازبینی اجرا کنید و منتشرش کنید
• اعزام عامل‌های بازبین — خودتان بازبین‌ها را انتخاب کنید
• محاسبهٔ بازبینی — گروه‌ها، محورها و دیف‌ها