درون ساختار HagiCode؛ تفکیک مدیریت دسترسی از تخصیص مهارت‌ها

تصور کنید می‌خواهید یک دستیار کدنویسی بسازید که در یک لحظه نیاز به دسترسی به داده‌های ۳۰ روز اخیر دارد و در لحظه بعد باید مانند یک متخصص رابط کاربری (UI) عمل کند؛ اما سیستم شما مجبور است برای هر تغییر کوچک، کل تنظیمات را از نو تعریف کند یا سیستم را به‌طور کامل ری‌بوت کند. چگونه می‌توان یک پیش‌تنظیم (Preset) واحد هوش مصنوعی را به‌گونه‌ای طراحی کرد که دستورات مجزا را به مهارت‌های مختلف هدایت کند، بدون اینکه باعث تورم پیکربندی یا پیچیدگی بیش از حد شود؟ طبق اعلام تیم HagiCode در ۲۳ ژون ۲۰۲۶، یک بازطراحی ساختاری این محدودیت بحرانی را حل کرده است. در طراحی قبلی، تمام دستورات موجود در یک پیش‌تنظیم مجبور بودند الزامات یکسانی داشته باشند؛ اما اکنون با قابلیت «اتصال دقیق مهارت در سطح دستور»، این مشکل برطرف شده است.

پیاده‌سازی یک دستیار کدنویسی هوش مصنوعی مستلزم ایجاد تعادل دقیق بین سادگی برای کاربر نهایی و انعطاف‌پذیری فنی برای توسعه‌دهنده است. در اکوسیستم فعلی HagiCode، وظایف پیش‌فرض (Preset Tasks) مانند ابزارهایی مبتنی بر پلاگین عمل می‌کنند که کاربران با پر کردن پنل‌های بصری، جلسات خودکار را فعال می‌کنند. از نظر ساختاری، هر پیش‌تنظیم در واقع یک دایرکتوری یا پوشه است که شامل چندین فایل کلیدی می‌باشد: فایل manifest.json برای ثبت اطلاعات هویتی، panel.json برای تعریف فرم‌های بصری، commands.json برای لیست دستورات اجرایی و در نهایت task-preset.json (یا prompts.json) برای تعیین پارامترها و مهارت‌های مورد نیاز.

همان‌طور که در تحلیل‌های پیشین ما درباره‌ی مدیریت ابزارهای عامل‌محور اشاره کردیم، مشکل اصلی در این بود که مهارت‌های مورد نیاز تنها در آرایه‌ی الزامات (Requirements Array) در سطح کل پیش‌تنظیم تعریف می‌شدند. این یعنی تمام دستورات درون یک بسته، به‌اجبار باید مهارت‌های یکسانی داشتند. برای مثال، اگر یک پیش‌تنظیم دارای ۵ دستور بود که دستور اول به مهارت last30days نیاز داشت، دستور سوم به ui-master و سه دستور دیگر به هیچ مهارتی نیاز نداشتند، طراحی قدیمی نمی‌توانست این تفاوت را مدیریت کند. برای دستیابی به مسیریابی (Routing) متفاوت، توسعه‌دهندگان مجبور بودند دستورات را به‌اجبار به چندین پیش‌تنظیم مختلف تقسیم کنند. این رویکرد باعث می‌شد حجم فایل‌های پیکربندی بلافاصله افزایش یابد و مدیریت آن‌ها دشوار شود. این دقیقاً همان نقطه‌ی بحرانی است که پیشنهاد extend-preset-task-multiple-skills-support برای حل آن ارائه شد.

تفکیک مسئولیت در دو لایه

هسته این بازطراحی، جداسازی سخت‌گیرانه‌ی «اتصال» (Binding) و «دروازبانی» (Gatekeeping) است. پیش از رسیدن به طراحی نهایی، تیم توسعه بررسی کرد که آیا می‌توان از یک جدول نگاشت به نام commandSkillMappings برای ذخیره رابطه «شناسه دستور $\rightarrow$ مهارت» استفاده کند یا خیر. اما این ایده رد شد. دلیل رد آن این بود که هر دستور در فایل commands.json پیش از این یک شناسه (ID) دارد؛ کپی کردن این شناسه در یک جدول نگاشت جداگانه باعث ایجاد «رانش داده‌ها» (Data Drift) می‌شد. به این معنا که اگر دستوری به‌روزرسانی می‌شد اما جدول نگاشت فراموش می‌شد، سیستم با خطا مواجه می‌گشت. تیم نتیجه گرفت که «جداسازی صرف به خاطر جداسازی»، هزینه‌های نگهداری را به قدری بالا می‌برد که مزایای ظاهری آن را می‌پوشاند.

به همین دلیل، یک سیستم مسئولیت دو لایه پیاده شد:

• فیلد مهارت در سطح دستور (Command-level skill field): این فیلد به‌صورت اختیاری مستقیماً در commands.json قرار دارد و تنها مسئول «اعلام اتصال» است. این لایه به سیستم می‌گوید که برای رندر کردن پیش‌گفتارهای پرامپت و نمایش در رابط کاربری (UI)، کدام مهارت باید متصل شود. در واقع این لایه به سؤال «چه چیزی متصل شود و چه چیزی نمایش داده شود» پاسخ می‌دهد.
• آرایه‌ی الزامات در سطح پیش‌فرض (Preset-level requirements array): این بخش در task-preset.json قرار دارد و به عنوان مرجع نهایی و فهرست authoritative عمل می‌کند. این لایه نقش واقعی دروازه‌بان را ایفا می‌کند و تعیین می‌کند که آیا کل پیش‌تنظیم اصلاً اجازه اجرا دارد یا خیر. این لایه به سؤال «آیا اجرای این عملیات مجاز است؟» پاسخ می‌دهد.

با جداسازی این دو لایه، سیستم از پرس‌وجوهای تکراری و هزینه‌بر جلوگیری می‌کند. چون لایه‌ی دروازه‌بان همیشه بر اساس الزامات سطح پیش‌تنظیم عمل می‌کند و توسط CacheKey بهینه‌سازی (Deduplicated) می‌شود، حتی اگر چندین دستور به یک مهارت واحد متصل باشند، تنها یک بار بررسی (Probe) انجام می‌شود. این امر تضمین می‌کند که افزودن مهارت‌ها در سطح دستور، هیچ‌گونه سربار پردازشی اضافی ایجاد نکند.

ساختار داده و پیاده‌سازی فنی

در بازطراحی تعریف دستورات، یک فیلد اختیاری به نام skill به ساختار اصلی اضافه شده است. در بسته‌ی bundled مربوط به last30days، فایل commands.json (که اکنون به نسخه ۱.۱ ارتقا یافته) به این شکل است:

{
  "$schema": "../../schemas/commands.schema.json",
  "version": "1.1",
  "commands": [
    { "id": "research", "skill": "last30days", "prompt": "调研一下最近30天大家对 {topic} 的真实讨论" },
    { "id": "summarize", "prompt": "把上面的调研结果整理成一份摘要" }
  ]
}

در این مثال، دستور research به مهارت last30days متصل شده است، در حالی که دستور summarize به هیچ مهارتی متصل نیست و مسیر پیش‌فرض را طی می‌کند. نکته مهم این است که دروازه‌بان واقعی همچنان در فایل task-preset.json باقی مانده است:

{
  "requirements": [
    { "key": "last30days", "cacheKey": "skill:last30days" }
  ]
}

شبکه‌های ایمنی و اعتبارسنجی

برای جلوگیری از بروز «اتصالات یتیم» (Orphan Bindings) — وضعیتی که در آن یک دستور به مهارتی متصل می‌شود که در لیست الزامات سطح پیش‌تنظیم تعریف نشده است — HagiCode یک شبکه ایمنی به نام ValidateCommandSkills را معرفی کرد. این عملیات اعتبارسنجی دقیقاً یک بار در مرحله بارگذاری بسته (Package Loading Phase) اجرا می‌شود و هر مهارتِ متصل به دستور را با لیست الزامات کلی تطبیق می‌دهد.

اگر تطابق پیدا نشود، سیستم اقدامات زیر را انجام می‌دهد:

• کل بسته را به عنوان «غیرقانونی» (Illegal) قضاوت می‌کند.
• کل پیش‌تنظیم را غیرفعال (Disable) می‌کند.
• کد تشخیص خطای command-skill-not-in-requirements را صادر می‌کند.

تیم توسعه تصمیم گرفت به‌جای نادیده گرفتن یا حذف یک دستور واحد، کل بسته را غیرفعال کند. دلیل این تصمیم، وجود «وابستگی‌های متوالی» (Sequential Dependencies) در دستورات است؛ اگر یک دستور به‌طور خاموش حذف شود، دستورات بعدی ورودی خالی دریافت می‌کنند و این منجر به رفتارهای غیرقابل پیش‌بینی در هوش مصنوعی می‌شود. با اجرای این بررسی در مرحله بارگذاری، خطا در زمان ثبت (Registration) کشف می‌شود، نه زمانی که کاربر روی دکمه «اجرا» کلیک می‌کند؛ این یعنی «کشف زودهنگام» به‌جای «انفجار دیرهنگام».

الحاق هوشمند پرامپت‌ها

زنجیره اجرا از مکانیزم خاصی به نام CombineCommandSkillPrelude استفاده می‌کند. وقتی دستوری به یک مهارت متصل است، سیستم باید اطلاعات آن مهارت را به‌عنوان یک پیش‌وند (Prefix) به پرامپت دستور الحاق (Splicing) کند و سپس آن را به اجراکننده (Executor) بفرستد.

برای مثال، پرامپت دستور research که عبارت است از «تحقیق درباره بحث‌های واقعی ۳۰ روز اخیر درباره {topic}» با اتصال به مهارت last30days تبدیل می‌شود به:
/last30days 调研一下最近30天大家对 {topic} 的真实讨论

برای حفظ پایداری، سیستم از اصل «تکرارناپذیری» (Idempotency) استفاده می‌کند. اگر کاربر به‌صورت دستی پیش‌وند را در پرامپت نوشته باشد یا آن را کپی کرده باشد، یک سیستم ساده منجر به ایجاد پیش‌وند دوتایی می‌شود (مانند /last30days /last30days). برای جلوگیری از این اتفاق، CombineCommandSkillPrelude پیش از الحاق، بررسی می‌کند که آیا پیش‌وند از قبل وجود دارد یا خیر. این منطق توسط BuildCommandPrelude در لایه‌ی PresetTaskCatalogProvider مدیریت می‌شود. از آنجایی که این تغییر در لایه‌ی تعریف (Definition Layer) محصور شده است، کد ایجاد جلسه در SessionsController به هیچ وجه نیازی به تغییر ندارد.

تجربه کاربری و نمایش بصری

برای اینکه این تغییرات فنی در پس‌زمینه برای کاربران ملموس باشد، رابط کاربری HagiCode سه بهبود مشخص را دریافت کرد:

• نشان‌های دستور (Command Badges): در انتخاب‌گر دستورات (Command-picker)، یک نشان (Badge) کوچک در کنار هر دستوری که به یک مهارت متصل است ظاهر می‌شود. این ویژگی به کاربر اجازه می‌دهد در یک نگاه تشخیص دهد کدام دستورات «دارای مهارت» (Skill-enabled) هستند و کدام یک دستورات معمولی‌اند.
• بلاک خلاصه بررسی الزامات: پنل دارای یک ناحیه اختصاصی است که از نگاشت commandSkillsByRequirementKey استفاده می‌کند. این بخش دستورات را بر اساس کلید الزامات متصل‌شده گروه‌بندی و تجمیع می‌کند تا کاربران بتوانند تطابق الزامات با اتصالات واقعی را مقایسه کنند.
• لینک‌های مستقیم نصب (Deep Links): اگر بررسی الزامات متوجه فقدان یک مهارت شود، رابط کاربری یک دکمه لینک مستقیم ارائه می‌دهد. این دکمه کاربر را مستقیماً به فرآیند نصب مهارت مورد نظر می‌برد و فاصله بین کشف مشکل و حل آن را به حداقل می‌رساند.

از نظر فنی، تایپ‌های فرانت-اند با افزودن skill?: string به تایپ دستور محدود شدند و از نرمال‌سازی (|| undefined) استفاده شد تا رشته‌های خالی در منطق قضاوت سیستم تداخل ایجاد نکنند.

مسیر مهاجرت و اجرای عملیاتی

این بازطراحی در ۵ گام مجزا به اتمام رسید:

1. گسترش اسکیما: به‌روزرسانی commands.schema.json برای گنجاندن فیلد اختیاری مهارت و ارتقای نسخه به ۱.۱.
2. تحلیل و اعتبارسنجی: پیاده‌سازی NormalizeCommands برای پارس کردن داده‌ها و ValidateCommandSkills برای اعتبارسنجی متقاطع با الزامات پیش‌تنظیم.
3. تزریق پیش‌گفتار: ایجاد منطق الحاق تکرارناپذیر در BuildCommandPrelude تا SessionsController دست‌نخورده باقی بماند.
4. مهاجرت پیش‌تنظیم‌های bundled: اصلاح فایل commands.json برای بسته‌های داخلی مانند last30days و ui-master. این مرحله فقط فایل commands.json را تغییر داد تا از تغییرات غیرمنتظره در سایر فایل‌ها جلوگیری شود.
5. بصری‌سازی فرانت-اند: افزودن تایپ‌ها، نشان‌های انتخاب‌گر، بلاک خلاصه و لینک‌های مستقیم خطا.

محدودیت‌های پیاده‌سازی و تست

در طول پیاده‌سازی عملی، تیم به چندین محدودیت سخت‌گیرانه پایبند بود:

• اتصال یک‌به‌یک: در حال حاضر، هر دستور تنها می‌تواند به یک مهارت متصل شود. اگر دستوری به چندین مهارت نیاز داشته باشد، راهکار فعلی این است که چندین مهارت در الزامات سطح پیش‌تنظیم تعریف شوند تا بتوانند در کنار هم حضور داشته باشند.
• سناریوهای تست بک-اند: تست‌ها سه مورد اصلی را پوشش دادند: دستوراتی با مهارت‌های موجود در الزامات (پذیرفته شد)، دستوراتی با مهارت‌های تعریف‌نشده در الزامات (غیرفعال کردن بسته) و اتصال چندین دستور به یک مهارت واحد (تأیید عملکرد صحیح حذف تکراری‌ها).

این تغییر معماری، این فرض را که هر پیش‌تنظیم وظیفه باید یک بلوک یکپارچه از الزامات باشد، تغییر داد. با تبدیل مهارت‌ها به اتصالات محلی (Local Bindings) و الزامات به دروازه‌های جهانی (Global Gates)، HagiCode نقشه‌راهی برای مدیریت ابزارهای پیچیده در جریان‌های کاری عامل‌محور (Agentic Workflows) بدون قربانی کردن پایداری سیستم ارائه داده است. جداسازی «چه چیزی متصل شود» (فیلد مهارت) از «آیا می‌تواند اجرا شود» (الزامات)، تضمین می‌کند که اعتبارسنجی، حذف تکراری‌ها و نمایش UI ساده و پیش‌بینی‌پذیر باقی بماند.

توسعه‌دهندگانی که به دنبال پیاده‌سازی مسیریابی مشابه هستند، می‌توانند پیاده‌سازی کامل را در سورس‌کد HagiCode-org/site در گیت‌هاب مطالعه کنند یا سند طراحی اصلی را تحت پیشنهاد OpenSpec با عنوان extend-preset-task-multiple-skills-support بررسی نمایند.

گام بعدی شما

• اگر توسعه‌دهنده ابزارهای هوش مصنوعی هستید، معماری «جداسازی اتصال از دروازبانی» را برای کاهش تکرار در فایل‌های JSON بررسی کنید.
• مستندات extend-preset-task-multiple-skills-support را در گیت‌هاب HagiCode-org مطالعه کنید تا با نحوه مدیریت وابستگی‌های متوالی آشنا شوید.
• برای بهینه‌سازی UX، از سیستم Badge برای تفکیک دستورات دارای قابلیت از دستورات ساده استفاده کنید.

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