چگونه روبات بازبینی «راهنمای وب نوین» به MetaMask کمک می‌کند واسط کاربر دسترس‌پذیر و نوین ارائه دهد

Gilberto Cocchi

Rick Viscomi

تاریخ انتشار: ۱۰ نوامبر ۲۰۲۶

‫MetaMask یک پلاتفرم مالی خودحضانتی با بیش‌از ۱۰۰ میلیون بارگیری در حدود ۱۹۰ کشور است. افزونه مرورگر آن به‌صورت باز توسعه یافته است، بنابراین جریانی مداوم از درخواست‌های واکشی ازسوی مشارکت‌کنندگان داخل و خارج از شرکت ارسال می‌شود.

فرانسیس نپوموسنو، مهندس تجربه کاربری MetaMask، بسیاری از این درخواست‌های واکشی را بررسی کرد و به‌دنبال روشی منسجم بود تا به همیاران کمک کند بهترین شیوه‌های دسترس‌پذیری را اعمال کنند و از ویژگی‌های وب مدرن استفاده کنند. او در ویرایشگر خود قبلاً از راهنمای وب نوین Chrome استفاده کرده بود، مجموعه‌ای از مهارت‌ها که روال‌های مطلوب پلاتفرم وب و داده‌های سازگاری مرورگر را به عوامل کدنویسی می‌آورد. برای ارائه همین راهنمایی به همیاران دیگر، او رباتی راه‌اندازی کرد تا هر درخواست واکشی به مخزن متن‌باز MetaMask را، صرف‌نظر از ابزارهایی که نویسنده آن استفاده کرده بود، بازبینی کند.

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

HTML و CSS مدرن همچنان ویژگی‌هایی را اضافه می‌کنند که دسترس‌پذیری و تجربه کاربر را بهبود می‌بخشند، و پیگیری اینکه کدام‌یک در مرورگرها کار می‌کنند دشوار است. با وجود همیاران زیاد، این دانش باید به همه کسانی که درخواست واکشی را باز می‌کنند برسد.

امنیت دلیل دیگری برای اهمیت دادن به این موضوع است: MetaMask به‌طور پیش‌فرض هر وابستگی شخص ثالث را در محیط امن قرار می‌دهد، که باعث می‌شود پذیرش ویژگی مرورگر بومی ارزان‌تر از جایگزین کتابخانه باشد. As Nepomuceno put it, "having access to these modern APIs, like being able to use dialogs and dropdowns without JavaScript, was a big win."

راه‌حل: «راهنمای وب نوین» هر درخواست واکشی را مرور می‌کند

در ۱۶ سپتامبر ۲۰۲۶، یک درخواست ادغام به MetaMask/metamask-extension اضافه شد که صفحه «نحوه عملکرد» با پرسشگان ساخته‌شده به روشی که اکثر پرسشگان‌های React ساخته می‌شوند را اضافه کرد:

// Before: Custom React state (removes content from DOM)
const [expanded, setExpanded] = useState(false);
<button type="button" aria-expanded={expanded} onClick={() => setExpanded(c => !c)}>
  <Text>{question}</Text>
</button>
{expanded ? <Text>{answer}</Text> : null}

حدود پنج دقیقه بعد، روبات نظر داد. با استناد به راهنمای search-hidden-content ، سه نکته را مطرح کرد:

• ارائه هر پاسخ به‌صورت شرطی آن را از DOM حذف می‌کند، بنابراین نوشتار جمع‌شده را نمی‌توان با «یافتن در صفحه» مرورگر پیدا کرد و فناوری کمکی سخت‌تر می‌تواند آن را کشف کند.
• شفاف‌سازی بومی <details>/<summary> (خط پایه از ۲۰۲۰) محتوا را با معناشناسی درست در DOM نگه می‌دارد. برای پانل‌های ناسازگار، مشخصه مشترک name (خط پایه به‌تازگی از ۲۰۲۴ دردسترس است) پانل‌های دیگر را به‌طور خودکار می‌بندد؛ برای پرسشگان چندباز، آن را حذف کنید.
• اگر تیم مؤلفه شفاف‌سازی موجود را ترجیح می‌دهد، باید حداقل پاسخ‌ها را در DOM با hidden="until-found" و شنونده beforematch که aria-expanded و وضعیت نماد را همگام‌سازی می‌کند نگه دارد.

// After: Native <details> / <summary> disclosure (findable with find-in-page)
<details>
  <summary>
    <Text>{question}</Text>
  </summary>
  <Text>{answer}</Text>
</details>

سیزده دقیقه بعد، نویسنده اصلاحیه‌ای را منتشر کرد. این مؤلفه به شفاف‌سازی بومی <details>/<summary> تبدیل شد، پاسخ‌های جمع‌شده در DOM برای «یافتن در صفحه» باقی ماندند، و دو دکمه پیمایش به پیوند تبدیل شدند.

آن روبات یک Cursor Automation است که Modern Web Guidance را اجرا می‌کند و نپوموسنو آن را با یک پیام‌واره سه‌خطی راه‌اندازی کرده است. تا ۲۱ اکتبر ۲۰۲۶، پنج هفته در:

• این روبات تقریباً روی ۴۸۰ درخواست واکشی اجرا شده بود و روی ۶۴ مورد از آن‌ها (۵۷ درخواست واکشی ویژگی و اصلاح، به‌علاوه ۷ درخواست واکشی انتشار و همگام‌سازی خودکار) از ۲۶ نویسنده نظر داده بود.
• در درخواست‌های واکشی ویژگی و اصلاح، مهندسان ۴۳ مورد از یافته‌های آن را برطرف کردند، و ۳ مورد دیگر را تاحدی در ۲۲ درخواست واکشی برطرف کردند.
• مهندسان به‌سرعت اقدام کردند: از ۳۸ اصلاحیه با commit قابل‌شناسایی، ۱۹ مورد ظرف ۱۵ دقیقه و ۲۶ مورد ظرف یک ساعت اعمال شدند، با میانگین ۱۵٫۲ دقیقه از زمان نظر تا اصلاح.

در اینجا نحوه پیکربندی ربات توسط MetaMask، آنچه که شناسایی کرد، و جایی که پر سروصدا بود آورده شده است.

راه‌اندازی یک پیام‌واره سه خطی است

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

- Run /modern-web-guidance for any client-facing changes
- Run /chrome-extensions for any relevant extension changes
- Comment on the PR only when there are issues to address. Keep the comment focused on actionable items

نحوه عملکرد آن در عمل:

• این ربات مشورتی است: در دو روز اول، ربات مرورهای «درخواست تغییرات» (و یک تأیید) را پست کرد که نویسندگان پس‌از رسیدگی به آن‌ها، آن‌ها را رد کردند؛ از ۱۸ سپتامبر، هر مرور به‌صورت نظر بوده است. این ویژگی مانع ادغام نمی‌شود، بنابراین نویسندگان تصمیم نهایی را درباره هر پیشنهاد می‌گیرند.
• به راهنماها و فایل‌های خاصی در مخزن ارجاع می‌دهد: در ۶۴ درخواست واکشی که درباره آن‌ها نظر داده است، این روبات ۱۲۲ یافته را مطرح کرده است. از ۱۰۲ درخواست ادغام ویژگی و رفع اشکال، ۶۳ مورد نام راهنمای خاص «راهنمای وب نوین» را که اعمال می‌کنند ذکر می‌کنند، مانند search-hidden-content، state-aware-sticky-headers، یا sms-otp-form، و به فایل موجود در مخزن اشاره می‌کنند که از الگوی توصیه‌شده استفاده می‌کند.
• این ربات ساکت می‌ماند مگراینکه درخواست واکشی با واسط کاربر تداخل داشته باشد: از حدود ۴۸۰ درخواست واکشی در آن پنج هفته، حداقل ۱۰۰ مورد با واسط کاربر یا کد مشتری تداخل داشتند و ربات به‌طور میانگین حدود دو یافته برای هر درخواست واکشی که درباره آن نظر داده بود داشت. تیم‌هایی که بیشتر مخازن پیش‌نما دارند می‌توانند انتظار داشته باشند که این ابزار روی بخش بزرگ‌تری نظر بدهد.

خود پیام‌واره با هر اجراکننده عاملی کار می‌کند؛ «راهنمای وب نوین» به‌عنوان یک مهارت یا افزونه برای Cursor،‏ Claude Code،‏ Codex،‏ GitHub Copilot،‏ Antigravity، و دیگر عامل‌های کدنویسی نصب می‌شود. وقتی عاملی مهارت را اجرا می‌کند، راهنماهای منطبق را در نمایه محلی بدون نیاز به کلیدهای میانای برنامه‌سازی کاربردی جستجو می‌کند و تفاوت را با آن‌ها بررسی می‌کند، بااستفاده از هر مدلی که اجراکننده عامل تیم قبلاً ارائه کرده است.

آنچه «راهنمای وب نوین» تشخیص می‌دهد اما خطایاب‌های نحوی تشخیص نمی‌دهند

A static linter can flag a missing attribute on a single element, but the findings that follow came down to interaction behavior, HTML semantics, and how components fit together across files.

فیلد کارمزد تراکنش که قابل‌ویرایش به‌نظر می‌رسید اما ورودی را بدون اطلاع نادیده می‌گرفت

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

ربات با استناد به راهنمای فرم‌ها، سه اصلاح را پرچم‌گذاری کرد:

• Disable the gas limit field when no estimate is available, and connect its visible status text to the field so that assistive technology reads the explanation.
• دکمه «ذخیره» غیرفعال را به همان نوشتار وضعیت متصل کنید تا صفحه‌خوان‌ها بدانند چرا غیرفعال است.
• فیلد را به حالت ورودی عددی تغییر دهید تا کاربران تلفن همراه صفحه‌کلید عددی دریافت کنند.

نویسنده هر سه اصلاح را در هر دو پنجره تنظیمات اعمال کرد و آن‌ها را در یک مؤلفه واحد ادغام کرد.

دکمه‌های برنما که نشانی وب آن‌ها پنهان شده است

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

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

ورودی‌های درستی‌سنجی که برچسب‌هایشان در جای دیگری قرار داشت

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

چند مورد دیگر که ربات متوجه شد

پنج یافته دیگر از همان دوره پنج هفته‌ای:

• جزئیات CSS که مهندس پشت روبات از قلم انداخته بود: درخواست کشش خود Nepomuceno برای برگه‌های چسبان صفحه اصلی، پُرسمان‌های CSS scroll-state را بدون نام‌گذاری محفظه‌هایشان تودرتو کرده بود و حاشیه‌ای را به‌گونه‌ای تغییر داده بود که چیدمان را در میان پیمایش جابه‌جا می‌کرد. روبات به راهنمای سرصفحه‌های چسبان آگاه از وضعیت ارجاع داد، و او هر دو را اصلاح کرد. او مرورها را برای موقعیت‌یابی لنگر و پُرسمان‌های وضعیت پیمایش مفید دانست.
• لغزش در میان کلیدزنی محدود شد: ورودی‌های لغزش سفارشی (حرکت قیمت که کاربر در معامله تحمل می‌کند) مقادیر بالای ۱۰۰٪ را در هر کلیدزنی محدود می‌کرد و درحالی‌که کاربر هنوز درحال تایپ بود، ۱۰۱ را به ۱۰۰ تبدیل می‌کرد. با پیروی از راهنمای فرم‌ها، اصلاح اعتبارسنجی را به زمانی منتقل کرد که فیلد تمرکز را ازدست می‌دهد و برنمای هشدار قابل‌مشاهده‌ای اضافه کرد.
• نشانگر بارگیری‌ای که صفحه‌خوان‌ها نمی‌توانستند از آن استفاده کنند: اسکلت بارگیری فهرست نشان، برچسب «بارگیری» خود را روی عنصری عمومی بدون نقش قرار داده بود که ARIA آن را ممنوع کرده است. ربات به دو مؤلفه در پایگاه کد اشاره کرد که قبلاً از الگوی فقط صفحه‌خوان MetaMask استفاده می‌کردند (هر دو پس‌از بازبینی «راهنمای وب نوین» در شش روز قبل به‌روز شده بودند)، و نویسنده هشت دقیقه بعد اسکلت را با آن الگو تراز کرد.
• کنش ناهمگام بدون محافظ: دکمه ناهمگام «مشاهده در ارائه‌دهنده» محافظ درحال اجرا نداشت، بنابراین دوکلیک می‌توانست برگه‌های تکراری و ناظران پس‌زمینه را باز کند. نویسنده کمتر از چهار دقیقه پس‌از نظر، یک محافظ اضافه کرد.
• اعتبارسنجی کلیدزنی بدون فرم: صفحه «وارد کردن NFT» با هر کلیدزنی اعتبارسنجی می‌شد و فاقد عنصر <form> برای معناشناسی ارسال بود. هر دو مشکل ۱۹ دقیقه پس‌از بازبینی برطرف شد.

همه مرورها عمومی هستند. نظرات کامل روبات در هر درخواست دریافت پیوندشده قرار دارد، و می‌توانید همه آن‌ها را در GitHub مرور کنید.

چه چیزی را اصلاح نکرده است و چقدر نویز دارد

همه یافته‌ها ثبت نشده است. جدول زیر نشان می‌دهد که MetaMask چگونه ۱۰۲ یافته را در درخواست‌های واکشی ویژگی و اصلاح شمارش کرده است (۲۰ یافته دیگر در ۷ درخواست واکشی انتشار و همگام‌سازی قرار گرفتند، جایی که انتظار نمی‌رود بازبینی کد را تغییر دهد):

تفکیک‌شده براساس موضوع در هر ۱۲۲ یافته (ازجمله ۲۰ یافته مربوط به درخواست‌های واکشی انتشار و همگام‌سازی):

چند الگو در این اعداد:

• اصلاحاتی که در یک مؤلفه باقی می‌مانند بسیار بیشتر از تغییرات دسترس‌پذیری متقاطع اتفاق می‌افتند. فرم‌ها و اصلاحات HTML در داخل مؤلفه تحت بررسی باقی می‌مانند، بنابراین نویسندگان معمولاً آن‌ها را فوراً اعمال می‌کنند (۱۹ مورد از ۳۱ مورد اصلاح شده است). دسترس‌پذیری بیشترین یافته‌ها را داشت (۳۸) اما فقط ۱۲ مورد برطرف شد، معمولاً به این دلیل که اصلاح خارج از محدوده درخواست واکشی بود یا به مؤلفه سیستم طراحی مشترکی نیاز داشت که هنوز وجود نداشت.
• «دیگر» جایی است که از راهنمای پلاتفرم وب خارج می‌شود. شانزده یافته شامل سازگاری سیستم طراحی، اشکالات منطقی، کپی، کیفیت آزمایش، حالت تاریک، و بهداشت کد بود؛ ۳ مورد اقدام شد، یکی‌از آن‌ها پس‌رفت واقعی بود (تغییر فهرست شبکه که پیش‌تکمیل فرم را خراب کرد). Most of those 16 were easy to pass over, but catching that regression made them worth a quick look.
• مثبت‌های کاذب ناشی از نحوه اعمال راهنماها توسط نماینده بود و بیشتر نویزها در راه‌اندازی قابل‌رفع است. چون روبات بازبینی عاملی است که تفاوت‌ها را می‌خواند و نه یک خطایاب نحوی ایستا، موارد مثبت کاذب آن ناشی از خواندن اشتباه کد اطراف یا اعمال سخت‌گیرانه‌تر قانون نسبت‌به راهنمای پیوندشده است. رد شدن از شاخه‌های انتشار و همگام‌سازی و سخت‌گیرانه‌تر کردن پیام‌واره به‌طوری‌که عامل به‌طور صریح به قوانین ذکرشده در راهنما پایبند باشد، اصلاحات بعدی واضح هستند.

نپوموسنو تأثیر گسترده‌تر بر تیم و زمان لازم برای بررسی را این‌گونه توصیف می‌کند:

دیوید مرداک، مهندس MetaMask، نیز در خود راهنما مشارکت داشته است: وقتی راهنمای چیدمان CSS در یکی از مثال‌هایش خطا داشت، او مشکل را ثبت کرد و تیم «راهنمای وب نوین» دو روز بعد اصلاحیه را ادغام کرد.

آنچه MetaMask به تیمی که آن را درنظر می‌گیرد می‌گوید

• قبل‌از نوشتن هر چیزی، راهنمایی را بخوانید. npx modern-web-guidance@latest search "accordion find in page" را اجرا کنید تا ببینید نماینده کدام راهنماها را برای تکلیف بازیابی می‌کند. همچنین می‌توانید مجموعه کامل راهنماهای «راهنمای وب نوین» را مرور کنید.
• با پیام‌واره سه‌خطی و عاملی که قبلاً اجرا کرده‌اید شروع کنید. مهارت (npx modern-web-guidance@latest install، یا فرمان افزایه نماینده) را نصب کنید، هر چیزی را که می‌تواند روی درخواست‌های کشیدن اجرا شود به آن اشاره کنید، و به آن بگویید که فقط زمانی نظر دهد که چیزی قابل اجرا وجود دارد و به قوانینی که صریحاً در راهنما بیان شده است پایبند باشد. ساکت نگه داشتن ربات وقتی مشکلی وجود ندارد دلیل این است که مهندسان MetaMask هنوز نظرات آن را می‌خوانند.
• انتظار داشته باشید که به برخی‌از یافته‌ها رسیدگی نشود. از ۱۰۲ یافته درباره ویژگی و درخواست‌های واکشی اصلاح، ۴۳ مورد اصلاح شد و ۳۶ مورد رد شد یا به آن‌ها رسیدگی نشد. این نسبت برای ربات بازبینی مشاوره‌ای خوب کار می‌کند، درحالی‌که به‌عنوان بررسی مسدودکننده مخرب خواهد بود.
• بازبینی انسانی را حفظ کنید. این روبات در معناشناسی پلاتفرم وب، CSS مدرن، و الگوهای تعاملی خوب است، اما محصول را نمی‌شناسد.

There is also what MetaMask hasn't measured yet: five weeks in, the team hasn't tracked per-pull-request cost, runtime, model comparisons, or how the review bot behaves outside a React codebase.

با سه خط پیکربندی، MetaMask یک روبات بازبینی دریافت کرد که برای اکثر یافته‌ها به یک راهنمای خاص (و یک نمونه موجود در مخزن درصورت وجود) ارجاع می‌دهد. پیشنهادهای پذیرفته‌شده آن معمولاً ظرف یک ساعت اصلاح می‌شود.