استخدام Tanrei مع وكلاء الذكاء الاصطناعي

يحتاج وكيل البرمجة الذي يكتب واجهة منتجك إلى ما يحتاج إليه أي شخص في فريقك: ما المكوّنات الموجودة، وما الذي يأخذه كل مكوّن، ومن أين تأتي كل قيمة. ويحفظ نظام Tanrei هذه الثلاثة في ملفات تأتي مع حزمه وفي خادم MCP، فيستطيع الوكيل أن يرجع إليها بدل أن يخمّن. تبيّن هذه الصفحة كيف تصلها، وتعطيك ملف قواعد تنسخه إلى مستودعك.

ما يستطيع الوكيل قراءته في الحزم

المكوّنات. تأتي الحزمة @tanrei/web بملف Custom Elements Manifest هو custom-elements.json: فيه كل عنصر بخصائص HTML (attributes) وخصائص العنصر والأحداث والمنافذ (slots) وأجزاء CSS، ولكلٍّ منها وصف. وتأتي الحزمة @tanrei/react بأنواع المكوّنات نفسها، فتفشل خاصية غير موجودة عند فحص الأنواع.
القيم. كل رمز تصميم (design token) هو خاصية مخصَّصة في @tanrei/web/tokens.css، اسمها مأخوذ من مساره: الرمز tanrei.sys.color.primary هو --tanrei-sys-color-primary. وإن كانت لمنتجك طبقته الخاصة، فإن المُخرَج tokens من الأمر tanrei build حزمة DTCG تحمل كل مجموعة فيها إرشادات استخدام للوكلاء في $extensions["dev.tanrei.llm"] (نظام التصميم الخاص بك).
ما الخطأ. المكوّن المستخدَم استخدامًا خاطئًا يُرسم مع ذلك، وفي بنية التطوير يكتب في وحدة التحكم تحذيرًا أوله [tanrei] يسمّي العنصر والمشكلة والقاعدة التي خالفها: زر بلا تسمية ولا أيقونة، أو كلمة لم يعطها منتجك، أو مكوّن يستبعده النظام. أما بنية الإنتاج (NODE_ENV=production) فلا تكتب شيئًا.

وصل خادم MCP

الحزمة @tanrei/mcp خادم Model Context Protocol لرموز Tanrei ولطبقات أنظمة التصميم. يسأله الوكيل: ما الرموز الموجودة، وإلامَ يؤول رمز في نظام ما ولماذا، وما الذي تستطيع الطبقة تغييره وكيف، وهل تعديلٌ على طبقة صالح قبل أن يكتبه. كل أدواته للقراءة فقط: الوكيل هو من يعدّل ملف طبقتك، والخادم يتحقق من التعديل بالبناء نفسه الذي يشغّله الأمر tanrei build. ولا يجيب عن المكوّنات، فعقدها هو الملف المذكور أعلاه.

إصدار تمهيدي

نُشر 0.1.0-next.0 على npm تحت وسم التوزيع (dist-tag) next: وحتى 0.1.0، ثبِّت @tanrei/mcp@next. لا يُحافَظ على التوافق مع الإصدارات السابقة طوال الإصدارات التمهيدية 0.x: قد يكسر أي إصدار تمهيدي أي شيء دون أن يُعلَن شيء مهمَلًا قبله، ويذكر الـ changeset الخاص به ما الذي انكسر.

أبقِ @tanrei/mcp على الإصدار نفسه الذي عليه @tanrei/web و @tanrei/cli وسائر المكتبات، فهي تتشارك مفردات واحدة.

في Claude Code، شغّل هذا الأمر في مستودعك:

claude mcp add --scope project tanrei -- npx -y @tanrei/mcp

يكتب الخيار --scope project الخادم في الملف .mcp.json في جذر المستودع. أودِع هذا الملف (commit)، فيكون الخادم نفسه لدى كل من يعمل في المستودع.

ويقرأ محرر Cursor (.cursor/mcp.json) وتطبيق Claude Desktop ومعظم العملاء الآخرين الخادم نفسه من JSON، عبر stdio:

{
  "mcpServers": {
    "tanrei": {
      "command": "npx",
      "args": ["-y", "@tanrei/mcp"]
    }
  }
}

ويقرأ محرر VS Code الملف .vscode/mcp.json، وفيه توضع الخوادم تحت servers وتسمّي طريقة نقلها:

{
  "servers": {
    "tanrei": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@tanrei/mcp"]
    }
  }
}

يحتاج الخادم إلى Node.js 20 أو أحدث. ويحلّ المسار النسبي في layerFile انطلاقًا من مجلد عمله، وهو عادةً جذر المستودع.

ما يجيب عنه الخادم

أدواته، وما تجيب عنه كل أداة:

الأداة list_systems: الأنظمة المضمَّنة في Tanrei، وإن أعطيتها ملف طبقتك فسلسلة طبقات منتجك، مع ما أضافته كل طبقة إلى المفردات ونتائج فحص إمكانية الوصول
الأداة list_components: المكوّنات التي يضمّها نظام، من بيان مكوّناته، كلٌّ مع الوحدة التي تسجّله وقيم variant التي يقدّمها النظام، وما لا يضمّه النظام مع ما يُستعمل بدلًا منه؛ يستدعيها الوكيل أولًا
الأداة get_component: مكوّن واحد كما تصفه مواصفته، لنظام واحد: خصائصه وأحداثه وفتحاته وحالاته، وسلوكه قواعدَ لكلٍّ منها معرّف ثابت، وإمكانية الوصول إليه، ومثال واحد
الأداة find_component: مكوّنات النظام التي تؤدي مهمة تصفها بكلمات عادية، الأنسب أولًا، وعلى حدة ما يطابقها ولا يضمّه النظام، مع ما يُستعمل بدلًا منه
الأداة check_usage: كل عنصر واستيراد وvariant في شيفرتك لا يضمّه النظام، مع ملفه وسطره وعموده وما يُستعمل بدلًا منه؛ ولا تكتب شيئًا
الأداة search_tokens: الرموز التي يُعثر عليها بجزء من المعرّف أو بنمط glob، مع نوع كل رمز وصنفه ووصفه
الأداة resolve: إلامَ يؤول رمز في نظام ونظام ألوان، وعبر أي أسماء بديلة وقواعد، وأي طبقة حدّدته، وخاصيته المخصَّصة في CSS
الأداة explain_token: لماذا يوجد الرمز، وما الذي يتبعه، والتغييرات التي تستطيع الطبقة كتابتها له، وكيف تضاف مفردات بجانبه، وكل ذلك جزءًا من طبقة
الأداة diff_systems: الرموز التي تختلف قيمها بين نظامين
الأداة validate_layer: كل مشكلات الطبقة دفعة واحدة، مع طريقة حل كل منها، ثم البناء الفعلي والتحذيرات التي يطبعها. لا تكتب شيئًا
الأداة propose_extension: درجة أو حجم أو طراز جديد أو رمز خاص بك جزءًا من طبقة، متحقَّقًا منه ببناء تجريبي، مع القيم التي ينتجها
الأداة mimicry_gaps: سمات أنظمة التصميم الأخرى التي لا يستطيع أي رمز التعبير عنها بعد

موارده، وما يحويه كل مورد:

المورد tanrei://philosophy: الأفكار التي تقوم عليها المفردات والقواعد التي تتبعها الطبقة، في صفحة واحدة
المورد tanrei://schema/system: مخطط JSON Schema لملف الطبقة
المورد tanrei://systems/<id>: ملف الطبقة لكل نظام مضمَّن، كما هو مكتوب
المورد tanrei://components/<id>: بيان المكوّنات لكل نظام مضمَّن، كما يولّده المستودع

ويعطي الخادم الوكيلَ قواعده أيضًا عند الاتصال: لا تستعمل مكوّنًا لا يذكره بيان النظام، وغيّر القيم عبر طبقة، ولا تضف مفردات إلا تحت vocabulary ومعها مبرّر، وأعطِ كل قيمة مثبَّتة سببًا، ولا تغيّر أبدًا عتبة من عتبات إمكانية الوصول، ولا تعدّل أبدًا ملفًا مولَّدًا. هاتان القائمتان هما قائمتا الخادم نفسه: فحصٌ يُبقي هذه الصفحة، بكل لغة، مطابقة لأدوات الخادم وموارده، فإذا اكتسب الخادم أداة أضيفت هنا معها.

ملف قواعد لمستودعك

كثير من وكلاء البرمجة يقرؤون الملف AGENTS.md في جذر المستودع، ومنهم Cursor. ويقرؤه Claude Code حين لا يكون في المستودع ملف CLAUDE.md؛ فإن كان فيه، فأضف إليه سطرًا هو @AGENTS.md، فيقرأ Claude Code الملفين. انسخ هذا القسم إلى ملفك AGENTS.md:

## UI

This product's interface is built with Tanrei (https://tanrei.chnotchy.com), on its default design system, `tanrei`.

- Write UI with Tanrei's components. Before you build a control, a menu, a dialog, a list or a navigation element by hand, look for the component that does it: node_modules/@tanrei/web/custom-elements.json lists every element with its attributes, properties, events, slots and parts, and https://tanrei.chnotchy.com/components/ has a page for each.
- Use a component through what its manifest lists. Do not restyle it from outside and do not copy its markup. A look the components do not have is a change to the design system, not to one screen: ask before you make it.
- Take every color, radius, spacing, text style, elevation, motion and opacity from a token: var(--tanrei-sys-…) in CSS, for example --tanrei-sys-color-primary, --tanrei-sys-space-space200, --tanrei-sys-shape-corner-medium, --tanrei-sys-typescale-body-font. Never write a color, a length, a duration or a font for these yourself.
- Stay on the default system. Do not set data-tanrei-system, and do not import @tanrei/web/systems/*.css. Do not use a component, or a variant of one, that the system leaves out: its page says "Not in tanrei", or lists the variant under "Variants not shipped in", and in a development build it warns.
- A console message that starts with [tanrei] in a development build is a bug. Fix what it names before you finish.
- Give the product's words once, with setWords() from @tanrei/web: Tanrei ships none.
- Keep every @tanrei/* package on the same version.

القواعد مكتوبة بالإنجليزية، لغة الأسماء في الشيفرة؛ فترجمها إن كان فريقك يكتب قواعده بلغة أخرى. وإن كانت لمنتجك طبقته الخاصة، فضع مكان القاعدة «Stay on the default system» هاتين القاعدتين، باسم طبقتك وملفها:

- Our design system is the layer design/acme.system.json, which extends tanrei. Change a value there, never in a generated file: check the edit with the tanrei MCP server's validate_layer before you write it, and run npx tanrei build after.
- Set data-tanrei-system="acme" once, on <html>, and no other system anywhere.

ويقرأ Cursor أيضًا قواعد المشروع من .cursor/rules/*.mdc؛ فإن كنت تحفظ قواعدك هناك، فبوسع قاعدةٍ فيها alwaysApply: true أن تحمل النص نفسه.

إبقاء الوكيل ضمن مكوّنات النظام الافتراضي

يستبعد النظام الافتراضي tanrei بضعة مكوّنات وطُرُز، تحتفظ بها أنظمة مضمَّنة أخرى. وهي تُرسم وتعمل تحته مع ذلك، فالذي يمنع الوكيل من اللجوء إليها هو القاعدة أعلاه والإشارات أدناه. يستبعد النظام الافتراضي اليوم ما يلي:

وهذا ما يُعلم الوكيل، ومن يراجع عمله، بأنه لجأ إلى واحد منها:

تذكر صفحة كل مكوّن، في نظرتها العامة، الأنظمةَ التي لا توفّره، أو الطُرُز التي تستبعدها منه.
في بنية التطوير، يحذّر كل عنصر يستبعده النظام النشط مرة واحدة في وحدة التحكم: حين يتصل بالصفحة، وحين يتغيّر variant الخاص به.

وتستطيع اختبارات المتصفح في منتجك أن تحفظ هذا الحد: اجعل الصفحة تفشل عند أي تحذير [tanrei]. مع Playwright:

import { expect, test } from '@playwright/test';

test('the home page draws no Tanrei warning', async ({ page }) => {
  const warnings: string[] = [];
  page.on('console', (message) => {
    if (message.text().startsWith('[tanrei]')) warnings.push(message.text());
  });
  await page.goto('/');
  expect(warnings).toEqual([]);
});

شغّله على بنية التطوير: بنية الإنتاج لا تكتب أي تحذير.

الشيفرة المصدرية والمشكلات على GitHub