الإفصاح التدريجي: نوافذ سطر الأوامر (CLI) إلى أنظمة الوكلاء

تعكس الأرقام في هذا المنشور حالة النظام وقت النشر (يناير 2026). راجع صفحة فريقنا للأرقام الحالية.

أنظمة الوكلاء معتِمة بالتصميم. تتخذ قرارات، وتستدعي أدوات، وتنسِّق العمل عبر عشرات المتخصصين. لكن عندما يسوء شيء ما — أو عندما تريد ببساطة أن تفهم ما يحدث — أين تنظر؟

الجواب هو الإفصاح التدريجي: واجهة متعددة الطبقات تكشف بالضبط عن قدر التعقيد الذي تحتاجه، بالضبط عندما تحتاجه.

مشكلة العتامة

قد يمتلك نظام تنسيق وكلاء حديث:

• أكثر من 40 وكيلًا متخصصًا، لكل منهم قدرات مميزة
• أكثر من 700 مهارة تمتد عبر الأتمتة الداخلية وتكاملات البائعين
• أكثر من 470 قرارًا معماريًا يُشكِّل السلوك
• عشرات خوادم أدوات MCP التي توفِّر قدرات خارجية

هذا التعقيد مقصود. يحتاج الوكلاء إلى وصول لسياق غني — معرفة المجال، وذكاء الكود، ومخططات قواعد البيانات — لاتخاذ قرارات جيدة. لكن ذلك الغنى نفسه يخلق مشكلة رؤية.

كيف تعرف أي وكيل يتعامل مع ترحيلات قاعدة البيانات؟ ما القرارات التي شكَّلت سلوك ترتيب نظام البحث؟ أي الأدوات يستطيع مستشار البنية المعمارية الوصول إليها؟

دون وصول منظَّم، يُترَك لك قراءة كود المصدر أو الأمل في أن يكون التوثيق حديثًا.

الإفصاح التدريجي كبنية

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

بالنسبة إلى أنظمة الوكلاء، يُترجَم هذا إلى أوامر سطر أوامر بأعماق متزايدة:

المستوى	الأمر	السؤال المُجاب عنه
1	orkestra system status	هل كل شيء سليم؟
2	orkestra agents list	ما الوكلاء الموجودة؟
3	orkestra agents info <name>	ماذا يفعل هذا الوكيل؟
4	orkestra decisions search	لماذا يعمل بهذه الطريقة؟
5	أدوات Maguyva MCP	أرِني الكود.

يجيب كل مستوى عن سؤال متابعة طبيعي. نادرًا ما تحتاج إلى القفز مباشرة إلى المستوى 5.

المستوى 1: سلامة النظام

السؤال الأول هو دائمًا: هل كل شيء يعمل؟

$ orkestra system status

on
{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

أمر واحد. أربعة أرقام. كافٍ لمعرفة أن النظام مُهيَّأ وأن السجلات مأهولة.

إذا انخفض عدد الوكلاء بشكل غير متوقَّع أو فشلت المهارات في التحميل، تراه هنا أولًا. لا حاجة للغوص في السجلات.

المستوى 2: جرد الوكلاء

بمجرد أن تعرف أن النظام سليم، السؤال التالي هو: ما المتاح؟

$ orkestra agents list

هذا يُعيد بيانات منظَّمة — أسماء الوكلاء، وأوصافهم، وتفضيلات النموذج، وتغطية المجال. المخرَج JSON افتراضيًا، مما يسهِّل تمريره عبر أنبوب إلى jq للتصفية:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

تريد وكلاء يتعاملون مع عمل قاعدة البيانات؟ أمر البحث يُضيِّق النطاق:

$ orkestra agents search "database"

هذا يفحص الأسماء، والأوصاف، والقدرات. تجد المتخصص الصحيح دون قراءة 40 تعريف وكيل.

المستوى 3: الغوص العميق في الوكيل

وجدت وكيلًا يبدو ذا صلة؟ يكشف أمر info كل شيء:

$ orkestra agents info architecture-advisor

يتضمَّن المخرَج:

• البيانات الوصفية: الاسم، والفئة، وتفضيل النموذج، والوصف
• المجالات: أي مجالات معرفة يغطيها هذا الوكيل
• الهوية: سمات الشخصية (architect، strategist، knowledge-architect)
• أدلة الأدوات: أي توثيق أدوات يُحقَن في السياق
• الأدوات: القائمة الكاملة لأدوات MCP المتاحة لهذا الوكيل

إليك عيّنة مما تراه:

on
{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

هذا يخبرك بالضبط بما يستطيع الوكيل فعله. لا حاجة إلى كود المصدر.

المستوى 4: علم آثار القرارات

تتصرف الوكلاء وفق قرارات موثَّقة. عندما تحتاج إلى فهم لماذا يعمل شيء ما بطريقة معينة، سجل القرارات هو مصدر الحقيقة.

$ orkestra decisions search "agent"

هذا يُعيد القرارات المعمارية المطابقة:

on
{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

لكل قرار مصدر كامل — متى اتُّخذ، ولماذا، وأي مقايضات جرى النظر فيها، وأي التزامات (commits) نفَّذته:

$ orkestra decisions info DEC-SR-049

on
{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

هذا توثيق معماري يبقى حديثًا لأنه مُعدَّن من الالتزامات، لا مُصانًا يدويًا.

المستوى 5: ذكاء الكود المباشر

عندما تحتاج إلى رؤية التنفيذ الفعلي — لا بيانات وصفية عنه — توفِّر أدوات MCP الخاصة بـMaguyva وصولًا مباشرًا.

من داخل جلسة وكيل:

mcp__maguyva__intelligent_search
  query: "agent context loading"

هذا يوجِّه تلقائيًا عبر البحث الدلالي والنصي وAST لإيجاد الكود ذي الصلة. لرموز محدَّدة:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

لتحليل التبعيات:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

هذه ليست مجرد بدائل لـgrep. إنها واعية بالرسم البياني، ومفهرَسة دلاليًا، ومتكاملة مع ذكاء الكود نفسه الذي يُشغِّل الوكلاء أنفسهم.

بحث موحَّد عبر السجلات

أحيانًا لا تعرف أي سجل يحمل الإجابة. البحث الموحَّد يمتد عبر كل شيء:

$ orkestra search "database" --summary

on
{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 تطابقًا عبر خمسة سجلات. يخبرك الملخَّص أين تتعمَّق. أزِل --summary للنتائج التفصيلية، أو أضِف --limit 5 لإبقاء المخرَج قابلًا للإدارة.

لماذا يهم هذا

الإفصاح التدريجي لا يتعلق فقط بالراحة. إنه يُغيِّر كيفية تفاعلك مع الأنظمة المعقدة.

يصبح التصحيح ممكنًا عمليًا. عندما يتخذ وكيل قرارًا غير متوقَّع، لا تبحث عبر السجلات بـgrep. تتحقق من الأدوات التي يستطيع الوصول إليها (agents info)، والقرارات التي تُشكِّل سلوكه (decisions search)، وتتبَّع التنفيذ إن لزم (intelligent_search).

تتسارع التهيئة الأولية. لا يحتاج أعضاء الفريق الجدد إلى قراءة قاعدة الكود بأكملها. يبدؤون بـsystem status، ويستكشفون بـagents list، ويتعمَّقون فقط عندما يصادفون شيئًا لا يفهمونه.

يبقى التوثيق حديثًا. لأن سطر الأوامر يقرأ من السجلات نفسها التي تُهيِّئ الوكلاء، المخرَج دقيق دائمًا. لا يوجد انحراف بين ما يقوله التوثيق وما يفعله النظام.

سطر الأوامر كواجهة

كان بإمكاننا بناء لوحة معلومات على الويب. كان بإمكاننا كتابة توثيق مطوَّل. بدلًا من ذلك، بنينا سطر أوامر يقرأ من مصدر الحقيقة.

لسطر الأوامر مزايا:

• قابل للتركيب: وجِّه المخرَج عبر jq، وادمجه مع السكربتات
• قابل للبرمجة: أتمِت الفحوصات، وولِّد التقارير
• سريع: لا تحميل صفحات، ولا تدفقات مصادقة
• دقيق: يقرأ الإعداد الفعلي، لا تمثيلًا مُخزَّنًا مؤقتًا

بالنسبة إلى الأنظمة التي تهم فيها الصحة أكثر من الجمالية، يفوز سطر الأوامر.

بناء إفصاحك التدريجي الخاص

إذا كنت تبني أنظمة وكلاء، فكِّر في كيفية فحص المستخدمين لها:

1. ابدأ بفحوصات السلامة. أمر واحد يخبرك ما إذا كانت الأمور تعمل.
2. وفِّر طرق عرض الجرد. اسرد ما هو موجود قبل شرح ما يفعله.
3. مكِّن الاستعلامات الموجَّهة. البحث يتفوق على التصفح على نطاق واسع.
4. اعرض المصدر. دَع المستخدمين يتتبَّعون القرارات إلى أصولها.
5. اتصل بذكاء الكود. في النهاية، يحتاج المستخدمون إلى رؤية التنفيذ.

تجيب كل طبقة عن سؤال متابعة. ابنِها بترتيب التكرار — يتوقف معظم المستخدمين عند الطبقة 2 أو 3. المستخدمون المتقدِّمون فقط يصلون إلى الطبقة 5.

الهدف ليس كشف كل شيء. إنه كشف بالضبط ما هو ضروري، بالضبط عندما يكون ضروريًا. هذا هو الإفصاح التدريجي مُطبَّقًا على بنية الوكلاء.