HextaUI با متادیتای ماشین‌خوان نرخ خطای عامل‌های کدنویسی را کاهش داد

اگر امروز از Claude Code یا Cursor برای توسعه استفاده می‌کنید، احتمالاً متوجه شده‌اید که دیگر دستورات نصب را تایپ نمی‌کنید، بلکه به یک عامل (Agent) دستور می‌دهید تا این کار را انجام دهد. اما مشکلی وجود دارد: اگر رجیستری کامپوننت‌های شما فقط برای انسان‌هایی طراحی شده باشد که در یک وب‌سایت کلیک می‌کنند، هوش مصنوعی احتمالاً ویژگی‌هایی (Props) را اختراع می‌کند که اصلاً در کتابخانه وجود ندارد یا کل کامپوننت شما را از ابتدا بازنویسی می‌کند.

این تغییر در رفتار کاربر به این معناست که «مصرف‌کننده» اصلی کتابخانه‌های رابط کاربری (UI) مدرن، دیگر برنامه‌نویس نیست، بلکه یک مدل زبانی بزرگ (LLM) است — شبیه کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن کتاب‌ها جواب می‌دهد. همان‌طور که در تحلیل قبلی ما درباره‌ی نحوه مدیریت مهارت‌های پیچیده در Claude Code اشاره کردیم، چالش فعلی از مهندسی پرامپت ساده فراتر رفته و به ایجاد یک زیرساخت ماشین‌خوان تبدیل شده است که از شکست عامل‌ها جلوگیری می‌کند. در این مسیر، در حالی که HextaUI بر تسهیل دسترسی تمرکز دارد، برخی توسعه‌دهندگان برای محافظت از مالکیت معنوی خود از روش‌های متفاوتی استفاده می‌کنند؛ برای مثال، تکنیک‌های مسموم‌سازی پرامپت به عنوان راهکاری برای جلوگیری از کپی‌برداری بی‌رویه هوش مصنوعی از کدهای منبع معرفی شده‌اند.

به نقل از راهنمای فنی HextaUI که در ۱۶ اکتبر ۲۰۲۶ منتشر شد، هدف اصلی حذف «حدس زدن» در فرآیند نصب است. وقتی یک عامل نمی‌تواند یک رجیستری معتبر را بیابد، به طور پیش‌فرض کد را از حافظه می‌نویسد که اغلب منجر به باگ‌های جدی و استفاده نادرست از API می‌شود.

زیربنا: اعتبارسنجی و فضای نام

پایداری سیستم با رجیستری‌هایی شروع می‌شود که اعتبارسنجی سخت‌گیرانه را پاس کنند. هر آیتم باید یک فایل JSON مطابق با اسکیمای رجیستری باشد که شامل نام، نوع، فایل‌ها، وابستگی‌ها و registryDependencies است. این فایل‌ها باید در URLهای پایدار و پیش‌بینی‌پذیر میزبانی شوند، مانند https://your-site.com/r/registry.json و https://your-site.com/r/button.json.

• اعتبارسنجی: طبق مستندات، CLI شرکت shadcn در می ۲۰۲۶ مرحله registry validate را اضافه کرد. رجیستری‌هایی که در این بررسی شکست می‌خورند، برای عامل‌ها به‌صورت بی‌صدا (silently) نامرئی می‌شوند و این امر باعث فعال شدن حالت «توهم» می‌گردد؛ جایی که عامل کامپوننت را با دست می‌نویسد و در نهایت آن را اشتباه پیاده می‌کند.
• URLهای کامل: استفاده از آدرس‌های کامل در registryDependencies (مثلاً https://your-site.com/r/button.json) به‌جای استفاده از نام ساده مانند button تضمین می‌کند که CLI به‌جای نسخه سفارشی شما، به‌طور تصادفی نسخه پیش‌فرض shadcn/ui را نصب نکند.
• فایل all.json: ایجاد یک آیتم واحد که به تمام کامپوننت‌ها وابسته است، به عامل‌هایی که از آن‌ها خواسته شده «سیستم طراحی را راه‌اندازی کن»، اجازه می‌دهد این کار را تنها با یک دستور انجام دهند.

برای شناسایی راحت‌تر، HextaUI ثبت یک فضای نام (Namespace) در components.json را توصیه می‌کند. این کار اجازه می‌دهد کاربران قطعه کدی مانند {"registries": {"@hextaui": "https://hextaui.com/r/{name}.json"}} را به پیکربندی خود اضافه کنند. این قابلیت، نصب از طریق نام‌های کوتاه مانند npx shadcn@latest add @hextaui/dialog را ممکن می‌سازد.

بدون فضای نام، یک رجیستری عملاً برای سرور پروتکل زمینهٔ مدل (MCP) — ابزار اصلی عامل‌ها برای گشت‌وگذار در کامپوننت‌ها — نامرئی است. برای رجیستری‌های خصوصی، فرمت شیء (Object) از هدرهایی با متغیرهای محیطی پشتیبانی می‌کند که CLI بدون ثبت در لاگ، آن‌ها را گسترش می‌دهد؛ مانند: {"registries": {"@acme-pro": {"url": "https://acme.com/r/pro/{name}.json", "headers": {"Authorization": "Bearer ${ACME_TOKEN}"}}}}.

بهینه‌سازی برای مصرف مدل‌های زبانی

عامل‌ها با HTML مشکل دارند اما در خواندن Markdown استادند. HextaUI استراتژی «همزاد مارک‌داون» را اجرا کرده است؛ یعنی هر صفحه مستندات، یک مسیر .md متناظر دارد (مثلاً https://hextaui.com/docs/button.md).

این فایل‌های مارک‌داون به‌صورت دستی نوشته نشده‌اند، بلکه از طریق سریال‌سازی درخت React صفحه زنده تولید می‌شوند. این روش تضمین می‌کند که محتوا — شامل توصیفات، دستورات نصب، سورس کامل، نحوه استفاده، مثال‌ها، پشتیبانی از کیبورد و جدول API — هرگز با کد واقعی فاصله نگیرد. مرجع API حیاتی‌ترین بخش است؛ عاملی که بتواند جدول Props را بخواند، ویژگی size="xl" را که وجود ندارد، اختراع نمی‌کند.

فراتر از صفحات تکی، رجیستری از دو فایل شاخص در ریشه استفاده می‌کند:

۱. llms.txt: یک فهرست مارک‌داون شامل توصیف پروژه، زمان استفاده (و زمان عدم استفاده)، دستورات نصب، قطعه کد فضای نام و یک خط برای هر صفحه مستندات که به نسخه .md آن لینک می‌دهد. قرار دادن دستور نصب در ۱۰ خط اول حیاتی است چون عامل‌ها ابتدا بالای صفحه را می‌خوانند.
۲. llms-full.txt: نسخه‌ای ادغام‌شده از تمام صفحات مستندات برای عامل‌هایی که ترجیح می‌دهند کل زمینه (Context) را یک‌باره بارگذاری کنند.

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

لایه عامل‌محور: MCP و OpenAPI

در حالی که CLI پیش‌فرض shadcn یک سرور MCP ساده (npx shadcn@latest mcp) برای نصب ارائه می‌دهد، این سرور مستندات، نقشه‌های کیبورد یا مثال‌ها را پوشش نمی‌دهد. HextaUI یک سرور MCP ثانویه، خواندنی و بدون نیاز به کلید API در آدرس https://hextaui.com/mcp با استفاده از Streamable HTTP راه‌اندازی کرده است. این سرور پنج ابزار خاص را فراهم می‌کند:

• search_docs
• get_component
• get_component_api
• get_examples
• get_install_command

این ساختار اجازه می‌دهد کاربر از Claude Code بخواهد «یک combobox با نتایج async اضافه کن» و عامل بتواند پیش از اجرای دستور نصب، جست‌وجوی مستندات و خواندن API را انجام دهد. Claude Code از طریق دستور claude mcp add --transport http hextaui https://hextaui.com/mcp متصل می‌شود، در حالی که Cursor و VS Code از همان URL در تنظیمات MCP خود استفاده می‌کنند. برای افزایش قابلیت کشف، یک کارت سرور در /.well-known/mcp/server-card.json و یک فایل server.json در فرمت رجیستری MCP منتشر شده است.

برای سخت‌تر کردن رابط، رجیستری از مشخصات OpenAPI (openapi.json) با Operation IDها و پاسخ‌های تایپ‌شده برای فراخوانی‌های مستقیم HTTP استفاده می‌کند. این سیستم خطاها را با فرمت RFC 9457 application/problem+json برمی‌گرداند. به‌جای یک صفحه ۴۰۴ ساده، API یک فیلد resolution ارائه می‌دهد؛ مثلاً: {"type": "https://hextaui.com/docs/api#not-found", "title": "Component not found", "status": 404, "detail": "No component named 'modal'.", "resolution": "Try 'dialog' or 'alert-dialog'. The catalog is at /mcp/index.json."}. این امر به عامل اجازه می‌دهد به‌جای تسلیم شدن و نوشتن کد از حافظه، مسیر جایگزین را امتحان کند.

در نهایت، سیستم شامل یک فایل SKILL.md در مسیر /.well-known/agent-skills/<name>/SKILL.md است. این فایل مانند یک دفترچه راهنمای عملیاتی با اهرم بالا عمل می‌کند و به عامل می‌گوید دقیقاً چگونه کامپوننت‌ها را بیابد، بخواند و با دستورات دقیق نصب کند.

استاندارد جدید مستندات: تجربه عامل (AX)

برای اطمینان از عملکرد سیستم، HextaUI با باز کردن یک پروژه Next.js خام در Claude Code، در حالی که سرور MCP متصل است و هیچ زمینه دیگری وجود ندارد، تست انجام می‌دهد. با درخواست یک کامپوننت پیچیده — مانند «یک date picker با بازه زمانی و قانون غیرفعال کردن آخر هفته‌ها» — توسعه‌دهندگان می‌توانند شکاف‌های موجود در مستندات .md یا llms.txt را بر اساس حدس‌های اشتباه عامل شناسایی کنند. رجیستری باید به‌صورت سلسله‌مراتبی از MCP به llms.txt و در نهایت به یک URL ساده تنزل (Degrade) یابد.

این رویکرد نشان‌دهنده یک چرخش بنیادین در تجربه توسعه‌دهنده (DX) است. برای سال‌ها، DX به معنای بصری بهتر و ناوبری بصری برای انسان‌ها بود. اکنون، DX در حال تبدیل شدن به تجربه عامل (Agent Experience یا AX) است، جایی که معیار اصلی، نرخ موفقیت فراخوانی ابزار (Tool-call) توسط یک LLM است.

با تبدیل رجیستری به یک API به‌جای یک وب‌سایت، HextaUI اصطکاک پذیرش را کاهش می‌دهد. بخش رجیستری پروژه حدود یک هفته زمان برد، اما زیرساخت‌های سمت عامل زمان بیشتری گرفت و در نهایت همان چیزی بود که رجیستری را برای انسان‌ها (و عامل‌هایی) که اکنون بیشترِ نصب‌ها را انجام می‌دهند، کاربردی کرد. کتابخانه‌هایی با AX برتر، رشد سریع‌تری خواهند داشت، زیرا آن‌ها همان‌هایی هستند که عامل‌های هوش مصنوعی به‌طور مداوم توصیه و با موفقیت نصب می‌کنند.

در گام بعدی، توسعه‌دهندگان باید پیشنهاد llms.txt را بررسی کنند تا ببینند سایر فریم‌ورک‌های بزرگ چگونه در حال استانداردسازی مستندات ماشین‌خوان خود برای عصر عامل‌ها هستند.

گام بعدی شما

• اگر صاحب یک کتابخانه UI هستید، یک فایل llms.txt ساده در ریشه سایت خود بسازید تا برای مدل‌های زبانی قابل کشف شوید.
• مستندات API خود را به فرمت Markdown تبدیل کنید تا نرخ توهم عامل‌ها در هنگام استفاده از کامپوننت‌های شما کاهش یابد.
• پروتکل MCP را برای تبدیل مستندات استاتیک به ابزارهای قابل فراخوانی توسط AI بررسی کنید.

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