Skip to content

قرارات الوكيل: اختيار المهارات وتحويلها إلى استدعاءات دوال ​

💡 خلاصة في جملة واحدة: باستخدام Jev لإدارة قرارات الوكيل — سؤال Choice واحد يرتّب 194 مهارة، وبوّابتان تقرران القول أو عدم القول، وتتحول طلبات اللغة الطبيعية إلى استدعاءات دوال ذات أنواع تظل معاملاتها قانونية دائمًا.

أسئلة مثل: أي مهارة ينبغي للوكيل تحميلها، وأي دالة ينبغي استدعاؤها — إذا ألقيتها إلى LLM تحصل على نص يحتاج إلى تحليل لاحق؛ وإذا ألقيتها إلى Jev تحصل على إجابة ذات أنواع + احتمالات، ويبقى قرار الحسم في كودك.

فكّك المسؤول هذه الوصفة لقرارات الوكيل عبر Jev في كتابين طبخ (cookbook): Skill suggestion يتولى فحص المهارات لوكيل يحمل 194 مهارة، وFunction calling يحوّل طلبات التداول باللغة الطبيعية إلى استدعاءات دوال عادية ذات أنواع. وكلاهما يتشارك الفلسفة نفسها: Jev يُصدر الأحكام والكود يتخذ القرارات.

text
طلب المستخدم في هذا الدور
        │
        ▼  طلب TypeSafe رقم 1 (الترتيب + البوابة، نفس الحالة تُقيَّم بالتوازي)
┌──────────────────────────────────────────────┐
│ سؤال Choice واحد: أي مهارة من 194؟               │
│   → الاحتمالات هي الترتيب، والكود يأخذ الثلاثة الأولى        │
│ ثلاثة أسئلة Noul: هل نتدخل؟ (ثلاث صياغات مختلفة)          │
│ سؤال Noul واحد: هل ذُكرت أداة / قالب / طريقة محددة بالاسم؟   │
└──────────────────────────────────────────────┘
        │
        ▼  الكود: gate ≥ 0.30 أو named ≥ 0.50؟
   لا ──┤── التوصية بعدم تحميل أي شيء (مع إرسال عبارة «لا توجد مهارات ذات صلة»)
        │ نعم
        ▼  طلب TypeSafe رقم 2 (النظر في الثلاثة الأولى فقط، مع الوصف الكامل + بداية SKILL.md)
┌──────────────────────────────────────────────┐
│ سؤال Choice واحد: أي واحدة من الثلاثة بالضبط؟               │
│ ثلاثة أسئلة Noul: هل تؤدي هذه المهارة هذا العمل فعلًا؟ (كل سؤال بإجابته) │
└──────────────────────────────────────────────┘
        │
        ▼  الكود: أفضل fits ≥ 0.30؟
   لا ──┤── التوصية بعدم تحميل أي شيء
        │ نعم
        ▼
كتلة <skill_relevance> تُلحق بعد الـ roster ← يحتفظ الـ agent بحكمه الخاص

لماذا نضع حكمًا آخر قبل حكم الـ agent؟ الجواب الرسمي مباشر: الـ agent ذو كتالوج المهارات الضخم يختار عمليًا بلا معلومات — يصل الكتالوج في صورة فهرس، مهارة واحدة في كل سطر، مع قصّ الوصف حتى لا يزاحم المحادثة؛ بعد القصّ إلى 60 حرفًا، تصبح مهارة Office التي تحرّر .pptx والمهارة المالية التي تبني deck تُقرأ كلتاهما كـ «أداة PowerPoint». وفي الأدوار التي لا توجد فيها مهارة مناسبة أصلًا، قد يحمّل واحدة قسرًا، لأن قائمة أسماء وحدها تغري بالتخمين.

هذا الدرس نحو 20 دقيقة. جميع الأرقام المقيسة في الصفحة مأخوذة من بيانات التسجيل في cookbook الرسمي: اقتراح المهارات بـ jev-1.14.0 (الـ agent المُختبَر claude-haiku-4-5-20251001، عرض 2026-10-30)، واستدعاء الدوال بـ jev-1.12؛ ملفات التسجيل منشورة مع المستودع الرسمي، ويمكن إعادة تشغيلها والتحقق منها بدون أي مفتاح.

بعد إتمام الدرس ماذا ستستطيع أن تفعل ​

  • إضافة حاجز «أي مهارة ينبغي تحميلها» للـ agent المعتمد على المهارات: طلبان (أولًا طلب Choice لترتيب 194 مهارة، ثم مراجعة الثلاثة الأولى)، القياس الرسمي: التحميل الخاطئ من 15.7% إلى 7.9%، والتحميل غير المفيد من 14.0% إلى 5.2%
  • كتابة suggest(): يُرجع اسم مهارة واحدًا كحد أقصى، ويُغلَّف بـ suggestion_block() في كتلة <skill_relevance> تُلحق بـ system prompt — يحتفظ الـ agent بالفهرس الكامل وحكمه الخاص، والتوصية تقول فقط «انظر إلى أيٍّ منها أولًا»
  • تحويل الطلبات بلغة طبيعية إلى استدعاءات دوال مُنمَّطة: closed_sets يقرأ توقيعات الدوال، Literal ← Choice، وlist[Literal[...]] ← سؤال Noul لكل عنصر، وbool ← Noul، و54 سؤالًا تُطرح كلها في طلب واحد، وما يدخل الدالة هو دائمًا قيمة صالحة من التوقيع
  • فهم استخدامَي الثقة: في استدعاء الدوال confidence = أكثر الحكمات ضعفًا في الاستدعاء كله (معامل واحد خاطئ يفسد الكل)؛ وعند اختيار المهارات مع الاهتمام فقط بـ «اختيار الأفضل»، خُذ مباشرة الخيار الأعلى احتمالًا دون حاجة لتعيين عتبات confidence في كل مكان

لماذا Jev، بدلًا من ترك الـ agent يختار بنفسه؟ ​

القدرةLLM يختار بنفسه من الفهرس / يولّد JSONJev قرار مُهيكل
هل يميّز بين «من يبني deck» و«من يعدّل deck»❌ وصف الفهرس مقصوص إلى 60 حرفًا، فتُقرأ مهارتا .pptx كلتاهما كأداة PowerPoint، والقياس الرسمي 15.7% تحميل خاطئ✅ طلب المراجعة يحمل الوصف الكامل + أول 700 حرفًا من SKILL.md، فطلب deck ينقلب من pptx-author إلى microsoft-office
هل يجرؤ على الصمت حين لا توجد مهارة مناسبة❌ قائمة أسماء تغري بالتخمين الأعمى، والقياس الرسمي 14.0% تحميل قسري✅ أربعة أسئلة Noul تحرس الباب، وإذا رسب الجميع في المراجعة تُقترح «عدم تحميل أي شيء» (5.2%)
هل معاملات الدالة قانونية❌ LLM يولّد JSON ثم يُحلَّل، وقد تُختلَق قيم الحقول ويتراكم كود التحليل✅ معاملات المجموعات المغلقة تُحوَّل إلى Choice / Noul، وبالصياغة الرسمية: ما يدخل الدالة هو دائمًا من القيم التي تقبلها الدالة
ما مدى الثقة اللازمة للتنفيذ❌ الثقة التي يصرّح بها LLM نصٌّ يحتاج إلى تحليل مرة أخرى✅ تدريب معايرة RLCD (الأحداث الموسومة بـ 0.2 تحدث في نحو 20% من الجري الطويل)، وconfidence = أضعف حكم، وإذا نزل عن العتبة يتحول إلى طلب تأكيد
تعديل سياسة القرار❌ تعديل الـ prompt وإعادة تشغيل كل شيء، ويصعب تتبّعه عند الـ review✅ عتبتان + صياغات الأسئلة مجمّعة في ثوابت الكود، والتوصية الرسمية وضعها في ملف واحد لتسهيل المراجعة البشرية

مأزقك الحالي ​

  • «الـ agent معلّق عليه 194 مهارة، وكل وصف في الفهرس لا يزيد عن 60 حرفًا — طلبت منه تعديل deck موجود، فحمّل مهارة بناء deck جديدة؛ وفي الأدوار التي لا توجد فيها مهارة مناسبة أصلًا، يحمّل واحدة قسرًا»
  • «استدعاء الدوال يعتمد على توليد LLM لـ JSON ثم تحليله، فتُختلَق قيم المعاملات أحيانًا ولا تتطابق أسماء الحقول، ويتراكم كود التحليل أكثر فأكثر»
  • «أريد أن يحكم النموذج بنفسه على «ما الخطوة التالية»، فتأتي الإجابة نصًا، والعتبات وإعادة المحاولة وآليات الاحتياط مبعثرة كلها في الـ prompt، ويصعب تتبّعها عند الـ review»

متى تستخدم هذه الحيلة ​

عندما تحتاج إلى:

  • دليل مهارات/أدوات الـ agent كبير إلى حدّ تُقتطع فيه الأوصاف، وتبدأ التحميلات الخاطئة وغير المفيدة في التهام الموثوقية
  • تحويل طلب المستخدم باللغة الطبيعية إلى استدعاء دوال مُعرَّفة الأنواع موجودة مسبقًا، مع معاملات مأخوذة من قائمة ثابتة
  • عتبة «هل ينبغي فعل ذلك أم لا» موضوعة صراحةً في الكود، وتغيير السياسة لا يعني إعادة كتابة الـ prompt

ولا تريد:

  • حشر نص الدليل كاملًا في الـ system prompt — النص الرسمي الحرفي: ذلك يجعل اختيار المهارات يتراجع، ويجلب context rot لبقية المحادثة
  • دفع تكلفة استدعاء توليد LLM كامل إضافي في كل جولة ليعمل كحَكَم
  • تحليل JSON يخرجه الـ LLM

🎒 تجهيزات قبل البدء ​

  • أنجزت سؤال الاختيار Choice: تعرف خريطة الخيارات criteria وprobabilities — أول طلب في هذه الصفحة هو Choice بـ 194 خيارًا (الحد الأقصى 255)
  • أنجزت الأسئلة المتوازية والتوسع التخميني: تعرف أن «الكود لا يستطيع بناء الطلب التالي إلا بعد حصوله على الإجابة السابقة» هو ما يُعد اعتمادًا حقيقيًا — الطلبان في هذه الصفحة هما بالضبط أحد حالات الطلبين الحقيقيين الثلاث الرسمية
  • شغّلت بنجاحالتثبيت وأول طلب: .venv يحتوي على typesafe-sdk، وTYPESAFE_API_KEY موجود في متغيرات البيئة
  • (اختياري، إعادة إنتاج بدون أي مفتاح) نزّل البيانات الرسمية: مستودع typesafe-public-examples — الملفات hermes_roster.json وrequests.json وjson_cache.json في دليل cookbooks/skill_suggestion، والملفات trader.py وdispatch.py وspec.json وjson_cache.json في دليل cookbooks/function_calling — شغّلها كما هي في الكود الرسمي، دون الحاجة إلى أي مفتاح
  • لن تحتاج إلى ANTHROPIC_API_KEY إلا إذا أردت تشغيل الاختبار الكامل المقترح للمهارة (الخطوة 4): الـ agent الخاضع للاختبار هو نموذج من Anthropic؛ أما إذا اكتفيت بالخطوتين 2 و3 باستخدام suggest()، فإن TYPESAFE_API_KEY وحده يكفي
  • اعرف مصدر الأرقام في هذه الصفحة: توصية المهارة سُجّلت باستخدام jev-1.14.0 (عرض 2026-10-30)، واستدعاء الدوال سُجّل باستخدام jev-1.12؛ أما تشغيلك المباشر الآن فسيستخدم jev-latest (يشير حاليًا إلى jev-1.14.0)، وقد تختلف الاحتمالات — اضبط العتبات وفق الإصدار الذي ثبّته

اتبع خطواتي ​

الخطوة 1: التعرّف على دليل المهارات وخط الأساس للـ agent المجرّد (نمط فشل فهرسة 60 محرفًا) ​

لماذا: يعرض المسؤول أولًا نمط فشل «اختيار الـ agent بنفسه»: مهارات Hermes البالغة 194 تدخل الـ system prompt في صورة فهرس، مهارة واحدة في كل سطر، والأوصاف مقتطعة إلى 60 محرفًا.

اسحب أولًا بيانات cookbook الاثنين إلى دليل العمل (تُثبَّت التبعيات بسطرين: سطر pip الرسمي لدى الطرفين لم يكن يتضمن typesafe-sdk أصلًا، ونضيفه هنا):

bash
mkdir agent-decisions && cd agent-decisions
base=https://raw.githubusercontent.com/typesafe-ai/typesafe-public-examples/main/cookbooks
curl -sLO $base/skill_suggestion/hermes_roster.json
curl -sLO $base/skill_suggestion/requests.json
curl -sLO $base/skill_suggestion/json_cache.json
curl -sLO $base/function_calling/trader.py
curl -sLO $base/function_calling/dispatch.py
curl -sLO $base/function_calling/spec.json
curl -sLO $base/function_calling/json_cache.json
pip install typesafe-sdk anthropic matplotlib ipython polars numpy 'cooksafe>=0.2.0,<0.3.0'

hermes_roster.json هو 194 مهارة من NousResearch/hermes-agent على commit مثبّت: كل سجل يحتوي على name وcategory ووصف مقتطع كما في الفهرس ووصفًا كاملًا وبداية SKILL.md. حمّله وشاهد مخرجات الإحصاءات الرسمية (مقتطف من وحدة الخطوة الرسمية 1):

python
import json
from collections import defaultdict
from pathlib import Path

ROSTER = json.loads(Path("hermes_roster.json").read_text(encoding="utf-8"))
BY_NAME = {skill["name"]: skill for skill in ROSTER}

def render_index() -> str:
    """The body of <available_skills>: skills grouped by category, both sorted by name."""
    by_category = defaultdict(list)
    for skill in ROSTER:
        by_category[skill["category"]].append(skill)
    lines = []
    for category in sorted(by_category):
        skills = sorted(by_category[category], key=lambda s: s["name"])
        if len(skills) == 1:  # a one-skill category is a single top-level row
            lines.append(f"  - {skills[0]['name']}: {skills[0]['description']}")
            continue
        lines.append(f"  {category}:")
        lines.extend(f"    - {skill['name']}: {skill['description']}" for skill in skills)
    return "\n".join(lines)

widths = [len(skill["description"]) for skill in ROSTER]
print(f"{len(ROSTER)} skills in {len({s['category'] for s in ROSTER})} categories")
print(f"index description: {sum(widths) / len(widths):.0f} characters on average, "
      f"{max(widths)} at most")

ينبغي أن ترى (من الإصدار الرسمي):

text
194 skills in 32 categories
index description: 55 characters on average, 60 at most

requests.json هو 452 طلبًا أحادي الجولة: 280 طلبًا يغطيه مهارة واحدة بالضبط (145 مهارة مختلفة)، و172 طلبًا لا تغطيه أي مهارة. الطلبات المغطاة كتبها Claude Sonnet 5 انطلاقًا من SKILL.md الخاص بكل مهارة؛ أما 172 طلبًا غير مغطى فكلها كُتبت لـ «معاقبة التخمين الأعمى» — 84 طلبًا يوميًا، و42 سؤالًا تقنيًا لا تخدمه أي مهارة (explain what a monad is)، و46 طلبًا لأشياء ليست في الدليل (post this to Mastodon والدليل لا يغطي X إلا).

خط الأساس للوكيل الخام (تشغيل 452 طلبًا واحدًا تلو الآخر، مع تثبيت النموذج الخاضع للاختبار على claude-haiku-4-5-20251001):

text
wrong loads    15.7%   (280 covered requests)
needless loads 14.0%   (172 uncovered requests)

of 26 wrong first picks, 11 came from the right skill's own category

كلا المقياسين هما معدلا خطأ، والأقل أفضل: wrong load يعني أن أول استدعاء لـ skill_view في الطلبات المغطاة لم يكن للمهارة المغطاة (ويُحتسب أيضًا عدم التحميل إطلاقًا)؛ أما needless load فيعني استدعاء skill_view في الطلبات غير المغطاة. من بين 26 تحميلًا خاطئًا، وقع 11 منها في تصنيف المهارة الصحيحة نفسها — الوكيل نظر تقريبًا إلى المكان الصحيح، والصعب هو التمييز بين عدة مهارات متشابهة المظهر.

💡 هذا هو شكل «السؤال في الطبقة الخطأ»

ملف SKILL.md الخاص بمهارة الوكيل الرسمية يقولها بصراحة: المشكلات التي تجعل Jev يتخذ القرار مباشرة («هل يجب تصعيد هذه التذكرة؟» «ماذا يفعل الوكيل في الخطوة التالية؟») تعني عادةً أن السؤال طُرح في الطبقة الخطأ — فكّك القرار إلى الأحكام التي يعتمد عليها، واكتب القرار نفسه في الكود ليكون مرئيًا وقابلًا للاختبار. الفلسفة الكاملة موجودة في التطوير بالتعاون مع Claude Code، وهذه الصفحة تتبعها طوال الوقت: Jev يرتب ويفحص، والكود يحتفظ بالعتبات وحق قرار «القول أو عدم القول».

  • أستطيع أن أقول ماذا يقيس كل من معدلي خطأ الأساس، وماذا يعني أن 11 من أصل 26 تحميلًا خاطئًا جاءت من تصنيف المهارة الصحيحة نفسها

الخطوة 2: الطلب الأول — سؤال Choice واحد يرتب 194 مهارة، وأربعة أسئلة Noul تحرس البوابة ​

لماذا: حكما الترتيب و«هل تحتاج هذه الجولة إلى مهارة» يتشاركان نفس الحالة (state)، والإرشادات الرسمية وضعتها في طلب واحد — فـ probabilities الخاص بـ Choice هو الترتيب، وأربعة أسئلة Noul مسؤولة عن البوابة.

طلب Choice واحد يتسع بسهولة لـ 194 خيارًا (الحد الأقصى 255)؛ والرسمية تركت ملاحظة: إذا كبر أكثر بضع مرات فقسّم الترتيب إلى كتل وأعد ترتيب الفائزين من كل كتلة. أما criteria الخيارات فتستخدم وصف الفهرس الذي يراه الوكيل نفسه (نفس المقطع النصي)، ونص instructions للسؤال كما يلي:

python
CHOICE_INSTRUCTIONS = (
    "Which of these skills, if any, is the right one to load to help with the "
    "user's latest request?"
)

البوابة هي أربعة طلبات Noul: ثلاثة تسأل من زوايا مختلفة «هل نحتاج إلى فعل شيء في هذه الجولة»، بالإضافة إلى واحد يسأل «هل ذُكرت طريقة محددة بالاسم» — فأسباب حاجة الجولة إلى مهارة اثنان فقط: إما التعرض لملفات / حساب / جهاز المستخدم، أو ذكر طريقة بالاسم تملكها إحدى المهارات (قالب meme، أو prompt لـ Suno).

python
GATE_QUESTIONS = {
    "acts_on_user_system": (
        "Is the assistant being asked to act on the user's files, accounts, devices, "
        "or online services, rather than only to explain or advise?"
    ),
    "would_follow_documented_procedure": (
        "Would a careful expert answering this consult a specific documented procedure "
        "or set of commands, rather than answering from general understanding?"
    ),
    "prose_suffices": (
        "Could a knowledgeable generalist fully satisfy this request in prose, with "
        "no tools, no documentation, and no access to the user's files or accounts?"
    ),
}
INVERTED = {"prose_suffices"}  # a yes here points away from needing a skill
NAMED_QUESTION = (
    "Does the request ask for a specific named tool, format, template, or method to be "
    "used, rather than for general help?"
)

GATE_THRESHOLD = 0.30   # mean of the three action nouls; at or above it, a skill is wanted
NAMED_THRESHOLD = 0.50   # the "names a method" noul; at or above it, a skill is wanted too

def build_state(request: str) -> dict:
    return {"request": request, "recent_context": ""}

@json_cache
def rank_wide(request: str) -> dict:
    """Request 1: rank all 194 skills, and score the request for whether a skill applies."""
    questions = {
        "which": Choice(
            instructions=CHOICE_INSTRUCTIONS,
            criteria={skill["name"]: skill["description"] for skill in ROSTER},
        )
    }
    for key, text in GATE_QUESTIONS.items():
        questions[f"gate::{key}"] = Noul(instructions=text)
    questions["named"] = Noul(instructions=NAMED_QUESTION)
    response = client.system_one(
        state=build_state(request), questions=questions, model=TYPESAFE_MODEL
    )
    ranked = sorted(
        response.answers["which"].probabilities.items(), key=lambda kv: -kv[1]
    )
    values = {
        key.removeprefix("gate::"): answer.noul
        for key, answer in response.answers.items()
        if key.startswith("gate::")
    }
    oriented = [(1.0 - v) if k in INVERTED else v for k, v in values.items()]
    return {
        "ranked": ranked[:12],
        "gate": sum(oriented) / len(oriented),
        "named": response.answers["named"].noul,
    }

def needs_skill(wide: dict) -> bool:
    """Either reason is enough: an action is wanted, or a named method is asked for."""
    return wide["gate"] >= GATE_THRESHOLD or wide["named"] >= NAMED_THRESHOLD

ثلاث نقاط تصميم تستحق المتابعة:

  • أسئلة الفعل تسأل «هل نحتاج إلى فعل شيء»، لا «ما هو الموضوع». أسئلة الموضوع لا تفرّق بين explain what a monad is والطلبات التي تحتاج مهارة — كلاهما برمجيات.
  • prose_suffices سؤال معكوس: إجابته بـ yes تعني بالضبط عدم الحاجة إلى مهارة، لذلك نأخذ 1.0 - v قبل إدخاله في المتوسط.
  • named لا يدخل في المتوسط ويفتح البوابة بشكل مستقل. النص الرسمي: إجابات الأفعال الثلاث ستصوّت ضده (outvote)؛ الجولات التي ذُكرت فيها طريقة لكن دون فعل شيء (صنع meme) لا يمكن إنقاذها إلا بواسطته.

needs_skill هو المدخلان في جدول الحقيقة: متوسط بوابة الفعل ≥ 0.30 أو ذكر بالاسم ≥ 0.50، وعند تجاوز أيٍّ منهما للخط نستمر؛ وإذا كان كلاهما منخفضًا فالتوصية هي عدم تحميل أي شيء.

تشغيلها على طلبات DEMO الرسمية الأربعة (المخرجات هي القيم المنشورة رسميًا):

text
"Can you save this recipe as a new note in my 'Recipes' folder in Notes.app so "
  action 0.83, names a method 0.88 -> suggest   (0.14s)
    0.990  apple-notes                           Manage Apple Notes via memo CLI: create, search, edit.
    0.010  computer-use                          Drive the desktop background-first; escalate on signal.
    0.000  apple-reminders                       Apple Reminders via remindctl: add, list, complete.

"I've got a client pitch deck as a .pptx template - I need to duplicate slide 4"
  action 0.73, names a method 0.64 -> suggest   (0.25s)
    0.730  pptx-author                           Build PowerPoint decks headless with python-pptx.
    0.270  microsoft-office                      Create, read, and edit Word, PowerPoint, and Excel files.
    0.000  apple-notes                           Manage Apple Notes via memo CLI: create, search, edit.

"Post this announcement to my Mastodon account."
  action 0.86, names a method 0.61 -> suggest   (0.1s)
    0.280  xurl                                  X/Twitter via xurl CLI: raw post search, posting, DM, media.
    0.240  social-media-content-calendar         Plan multi-platform social campaigns: briefs to posting.
    0.190  computer-use                          Drive the desktop background-first; escalate on signal.

"Can you make me a Gru's Plan meme about a developer's plan to refactor the cod"
  action 0.12, names a method 0.87 -> suggest   (0.12s)
    1.000  meme-generation                       Create meme PNGs from templates with Pillow text overlay.
    0.000  apple-notes                           Manage Apple Notes via memo CLI: create, search, edit.
    0.000  apple-reminders                       Apple Reminders via remindctl: add, list, complete.

كل طلب من الأربعة يوضح أمرًا واحدًا: طلب Notes لا لبس فيه، والمتصدر هو الصحيح؛ طلب deck يتقدم فيه مهارتان بامتداد .pptx، لكن في وصف من 60 حرفًا تأتي pptx-author لبناء deck في المقدمة — وطلب يريد تعديل deck موجود، وهذا بالضبط مؤشر على الخطأ؛ طلب Mastodon تمرره بوابة الفعل عند 0.86 (النشر فعل)، لكن المتصدر xurl هو مهارة النشر على X — الترتيب لا ينقذ ما ليس في الدليل؛ طلب meme بوابة الفعل فيه منخفضة عند 0.12، ويعتمد كليًا على named عند 0.87 لفتح البوابة، والمتصدر هو مهارة meme بالضبط.

💡 هذه هي القيمة الفريدة لـ Jev

الترتيب (طلب Choice واحد) والبوابة (أربعة طلبات Noul) يقيّمان نفس الحالة بالتوازي وبشكل مستقل في نفس الطلب الواحد — إضافة الأسئلة لا تزيد زمن الاستجابة تقريبًا، بل تضيف فقط tokens أسئلة قليلة. في التسجيل الرسمي استغرق الطلب الأول 0.1–0.25 ثانية. قارن ذلك بـ «وضع حكم LLM في كل جولة»: هناك تدفع تكلفة استدعاء توليد كامل للترتيب وآخر للبوابة، بالإضافة إلى تحليل النص الذي يبصقه الحكم. آلية الطلب الواحد متعدد الأسئلة موجودة في الأسئلة المتوازية والتوسع التخميني.

💡 انتبه للمحتوى الصيني

الشرح الرسمي: الإنجليزية هي اللغة الرئيسة في تدريب Jev، واللغات الأخرى بما فيها الصينية تعمل لكن بدقة أقل. يُنصح بالإبقاء على النص الإنجليزي الأصلي لجميع الأسئلة أعلاه (الصياغة الرسمية خضعت لاختبارات فعلية)؛ ولتقديم اقتراحات مهارات للطلبات الصينية، شغّل أولًا دفعة على بياناتك الخاصة وراقب توزيع الاحتمالات قبل تحديد العتبات.

يجب أن ترى: بوابات وترتيب حالات DEMO الأربع متطابقة مع الجدول أعلاه (متطابقة رقمًا برقم عند إعادة تشغيل الكاش؛ أثناء التشغيل المباشر ستكون هناك فروقات احتمالية، والاتجاه المرجعي هو النسخة التي ثبّتها).

الخطوة 3: الطلب الثاني — إعادة فحص الثلاثة الأوائل، مع السماح برفض الجميع ​

لماذا: هذه واحدة من حالات «الطلب الثاني الحقيقي» الثلاث الرسمية: يجب أن يحصل الكود على ترتيب الطلب الأول حتى يستطيع بناء خيارات الطلب الثاني — كلٌّ من الثلاثة الأوائل يُرفق معه الوصف الكامل وبداية SKILL.md.

مبدأ الأسئلة المتوازية هو «ما يمكن سؤاله معًا يُسأل معًا»، فلماذا نرسل طلبًا ثانيًا هنا تحديدًا؟ لأن خيارات الطلب الثاني تعتمد على إجابة الطلب الأول: كل مرشح يجب أن يُرفق معه description_full وبداية body من أول 700 حرفًا (كل سجل في ملف roster يخزّن 1600 حرفًا)، وهذه النصوص الطويلة لا يمكن دمجها في criteria إلا بعد معرفة من هم الثلاثة الأوائل. توثيق primitives الرسمي يذكر هذا الـ cookbook صراحةً كطلب ثانٍ حقيقي: طلب واحد يرتّب جميع المهارات، ثم تُؤخذ النصوص الكاملة للثلاثة الأوائل ويُحكم مرة أخرى مقابل أدلة أفضل.

python
SHORTLIST = 3       # candidates carried from the first request into the second
EXCERPT_CHARS = 700  # SKILL.md characters each candidate brings; the roster file stores 1600
FITS_THRESHOLD = 0.30  # a shortlist whose best "does this fit" noul is under this is dropped

RERANK_INSTRUCTIONS = (
    "Exactly one of these skills is the right one to load for the user's latest "
    "request. Which one? Read what each actually does, not just its name."
)

def rerank_questions(names, excerpt):
    questions = {
        "which": Choice(
            instructions=RERANK_INSTRUCTIONS,
            criteria={
                name: f"{BY_NAME[name]['description_full']} — {BY_NAME[name]['body'][:excerpt]}"
                for name in names
            },
        )
    }
    for name in names:
        questions[f"fits::{name}"] = Noul(
            instructions=(
                f"Does the skill '{name}' do the specific thing the user's request asks "
                f"for? It is described as: {BY_NAME[name]['description_full']}"
            )
        )
    return questions

@json_cache
def rerank(request, names, excerpt):
    """Request 2: the same Choice over a shortlist, plus one absolute noul per candidate."""
    response = client.system_one(
        state=build_state(request),
        questions=rerank_questions(names, excerpt),
        model=TYPESAFE_MODEL,
    )
    return {
        "winner": response.answers["which"].choice,
        "fits": {
            key.removeprefix("fits::"): answer.noul
            for key, answer in response.answers.items()
            if key.startswith("fits::")
        },
    }

fits الثلاثة تجيب كلٌّ على حدة ويمكن أن تكون جميعها منخفضة — فهي و which يقرران أمرين مختلفين: which يحدد «أي واحد من الثلاثة»، و fits يحدد «هل نقول شيئًا أصلًا أم لا». بمتابعة حالات DEMO الأربع حتى النهاية (القيم الرسمية المنشورة):

text
"Can you save this recipe as a new note in my 'Recipes' folder in Notes.app so "
  was apple-notes -> apple-notes   (0.11s)
    fits 0.81  apple-notes
    fits 0.50  computer-use
    fits 0.02  apple-reminders

"I've got a client pitch deck as a .pptx template - I need to duplicate slide 4"
  was pptx-author -> microsoft-office   (0.11s)
    fits 0.77  pptx-author
    fits 0.76  microsoft-office
    fits 0.01  apple-notes

"Post this announcement to my Mastodon account."
  was xurl -> nothing fits   (0.07s)
    fits 0.10  xurl
    fits 0.27  social-media-content-calendar
    fits 0.28  computer-use

"Can you make me a Gru's Plan meme about a developer's plan to refactor the cod"
  was meme-generation -> meme-generation   (0.16s)
    fits 0.84  meme-generation
    fits 0.03  apple-notes
    fits 0.01  apple-reminders

.pptx المشهد المشهور ينقلب في الطلب الثاني: بمجرد فصل المهارتين ومع كل واحدة نصها الكامل، يتحول طلب deck من pptx-author إلى microsoft-office الخاص بتحرير الملفات الموجودة. لاحظ أن قيمتي fits لديه ليستا منخفضتين (0.77 / 0.76 — كلاهما قادر على فعل شيء ما بـ deck)، لكن هذا السؤال لا يحدد «أي واحد»، والانقلاب جاء من Choice.

طلب Mastodon يتوقف عند الطلب الثاني: من بين ثلاث مهارات متقاربة لا توجد واحدة تفعل هذا فعلًا، وأفضل fits وهو 0.28 أقل من 0.30، فتُهجر المجموعة كلها — هذا الطلب عبر البوابة في المرتين، ومع ذلك انتهى به الأمر إلى التوصية بعدم تحميل أي شيء، وهذا هو معنى «السماح برفض الجميع».

بجمع الطلبين والعتبتين في دالة واحدة — هذا كل ما في الوصفة:

python
def suggest(request: str) -> tuple[str, ...]:
    """At most one skill name for a request, or () for "nothing here applies"."""
    wide = rank_wide(request)
    if not needs_skill(wide):
        return ()
    shortlist = tuple(name for name, _ in wide["ranked"][:SHORTLIST])
    result = rerank(request, shortlist, EXCERPT_CHARS)
    if max(result["fits"].values()) < FITS_THRESHOLD:
        return ()
    return (result["winner"],)

def suggestion_block(names: tuple[str, ...]) -> str:
    """What gets appended after the roster, in the suggestion."""
    body = (
        f"Relevant to the current request: {', '.join(names)}. Ignore this if it does not "
        "fit what the user actually asked for."
        if names
        else "No skill in the roster appears relevant to this request."
    )
    return f"\n\n<skill_relevance>\n{body}\n</skill_relevance>"

print(suggestion_block(suggest(DEMO[1])))
print(suggestion_block(suggest(DEMO[2])))

يجب أن ترى:

text
<skill_relevance>
Relevant to the current request: microsoft-office. Ignore this if it does not fit what the user actually asked for.
</skill_relevance>

<skill_relevance>
No skill in the roster appears relevant to this request.
</skill_relevance>

اسم الفائز يدخل سطرًا واحدًا فقط في system prompt. يحتفظ الـ agent بالفهرس الكامل وبحكمه الخاص، وذلك السطر يخبره فقط «أي سجل ينظر إليه أولًا». كلتا نقطتي الصياغة جاءتا من الاختبار الفعلي (النص الرسمي):

  • التوصية مكتوبة بصيغة «يمكن تجاهلها»: كلما شدّدت التوصية أكثر، ارتفعت معها نسبة الامتثال للتوصيات الخاطئة أيضًا — والتوصية الخاطئة أسوأ من لا توصية.
  • حتى بدون توصية يُرسل سطر «لا توجد مهارات ذات صلة»: إن لم يُرسل أي شيء، يبقى تعليمة roster نفسها «فضّل التحميل الزائد» بلا منافس.

لاحظ أيضًا الموضع: كتلة التوصية تُضاف بعد الـ roster وليس داخله — نص الـ roster يبقى متطابقًا كل جولة، وهذا ما يجعل prefix caching يعمل.

  • أستطيع أن أشرح ماذا يفعل كل من الطلبين ولماذا يجب إرسالهما مرتين (خيارات الطلب الثاني يحددها جواب الطلب الأول)
  • طلب Mastodon عبر البوابة مرتين وانتهى بالتوصية بعدم تحميل أي شيء — أستطيع أن أشير إلى أي سؤال هو الذي أوقفه

الخطوة 4: الموازنة — اختبار فعلي بثلاثة أذرع لـ 452 طلبًا ​

لماذا: رسميًا شُغِّل كل من 452 طلبًا ثلاث مرات، والأذرع الثلاثة تختلف في شيء واحد فقط: ما الذي حُشو في system prompt إلى جانب الـ roster.

ما الذي حُشو في system prompt
agent alone (خط الأساس)لا شيء
agent with a suggestionsuggest() كتلة التوصية المُعادة
agent given the answerاسم المهارة الصحيحة، و«nothing applies» إن لم توجد مهارة تغطية

الذراع الثالثة هي الأرضية: لا يوجد أي نظام حقيقي يعرف المهارة المغطية مسبقًا، لذا فهي ترسم الحد الأدنى للذراعين الأوليين — لا يمكن لأي طريقة اختيار مهما كانت جيدة أن تتغلب عليها.

text
run         wrong loads  needless loads
baseline          15.7%           14.0%
TypeSafe           7.9%            5.2%
oracle             3.2%            4.1%

baseline -> TypeSafe:  2.0x fewer wrong loads, 2.7x fewer needless ones

الخلاصة الرسمية: التحميل الخاطئ انخفض بأكثر من النصف (15.7% → 7.9%)، مغلقًا أكثر من نصف الفجوة بين «التخمين من فهرس مقتطع» و«الحصول على الإجابة مباشرةً»؛ والتحميل غير المفيد انخفض بنحو الثلثين (14.0% → 5.2%)، مغلقًا تلك الفجوة تقريبًا بالكامل.

والثمن معروض أيضًا: من 280 طلب تغطية، تُصلح التوصيات **29 وتُفسد 7 **. بعض الطلبات كان الوكيل فيها محقًا أصلًا، لكنه انحرف بعد تعليق توصية خاطئة واثقة عليها — تقول الجهة الرسمية إن هذا هو ثمن وضع توصية قبل الدور.

**يجب أن ترى **: جدول معدلات الخطأ بثلاثة صفوف وعمودين مطابق لما سبق (إعادة تشغيل الذاكرة المؤقتة متطابقة تمامًا على مستوى البتات؛ أما التشغيل المباشر فيعتمد على الإصدار الذي ثبّته).

  • أستطيع أن أقول أين يختلف كل من الأذرع الثلاثة، ولماذا يكون oracle أرضيةً لا متسابقًا
  • أعرف أن 7.9% ليست مجانية: 29 إصلاحًا و7 إفسادًا، لذلك يجب أن تتضمن صياغة التوصية عبارة «يمكن تجاهلها»

الخطوة 5: التحويل إلى استدعاء دوال — closed_sets يقرأ التوقيع، 54 سؤالًا في طلب واحد ​

لماذا: التطبيق الثاني لنفس الفلسفة: الدوال لا تتغير سطرًا واحدًا، بل نضيف spec — سؤال واحد لكل معامل، وسطر وصف لكل خيار، وفقرة وصف لكل دالة، إضافة إلى سؤال لاختيار الدالة.

استعارة الجهة الرسمية مباشرة: عندما تطلب «لاتيه مثلج بحجم كبير بشوفان دون سكر»، لا يسجّل الباريستا كلماتك الحرفية بل يؤشّر أربعة خيارات على الكوب. هذا الـ cookbook يفعل الشيء نفسه لواجهة API للتداول — جملة تدخل، واسم دالة وقيم معاملات تخرج، كل منها بدرجة ثقة:

text
"plot rolling correlation between nvda and spy for the past month"
    rolling_correlation(symbol='NVDA', benchmark='SPY', window='1mo')   confidence 0.91

"compare nvda amd and msft over the past three months"
    compare_returns(symbols=['NVDA', 'AMD', 'MSFT'], window='3mo')      confidence 0.94

"show me apple daily with volume"
    plot_price(symbol='AAPL', resolution='1d', include_volume=True)     confidence 0.75

"what tickers do you have"
    list_symbols()                                                     confidence 1.00

trader.py هو عشر دوال عادية. المعاملات التي تأتي قيمها من قوائم ثابتة تكون في التعليقات التوضيحية للأنواع بالفعل Literal — closed_sets يقرأ التوقيع ويقسّم المعاملات القابلة للتعبئة إلى ثلاثة أشكال:

python
def plot_price(
    symbol: Literal["SPY", "NVDA", "AMD", "AAPL", "MSFT", "TSLA"],
    style: Literal["line", "candles"] = "line",
    resolution: Literal["1m", "5m", "15m", "1h", "1d"] = "15m",
    window: Literal["1d", "1w", "1mo", "3mo"] = "1w",
    include_volume: bool = False,
    moving_average: Literal["9", "20", "50"] | None = None,
    log_scale: bool = False,
): ...
الشكلالتعليق التوضيحي للنوعإلى أي سؤال يتحول
choiceLiteral[...]سؤال Choice واحد، الخيارات هي القيم القانونية
setlist[Literal[...]]سؤال Noul لكل عضو ({} يُستبدل باسم العضو)
flagboolسؤال Noul واحد، ≥ 0.5 يعني مفعّلًا

الأنواع الأخرى — نص حر، أرقام، تواريخ — لا تولّد أسئلة، وتظل القيم الافتراضية للدوال قائمة: المعامل الثالث لـ top_movers وهو limit: int = 3 لا يولّد سؤالًا أبدًا ويحتفظ دائمًا بالقيمة الافتراضية 3.

يوجد الـ spec في spec.json، ويوضّح بجملة واحدة «ماذا يعني كلام المستخدم» — Literal لا يعطي سوى السلسلتين "1mo" و"3mo"، ولا يستطيع أن يقول إن «this quarter» تعني الأخيرة. وتضيف الجهة الرسمية جملة: يمكن للـ spec أن يكتبه لك الـ LLM من التوقيع. rolling_correlation سؤالا الدور لمعاملين من أصل واحد يستحقان القراءة حرفيًا:

json
"symbol": {
  "question": "Which stock is the user asking about - the one being measured, named first?",
  "options": { "SPY": "SPY, the S&P 500 index ETF, the market as a whole", "…": "…" }
},
"benchmark": {
  "question": "Which stock is it being compared against - the second one named, the yardstick?",
  "stated": "Does the user name a second symbol to compare against?",
  "options": { "SPY": "SPY, the S&P 500 index ETF, the market as a whole", "…": "…" }
}

symbol وbenchmark يسحبان من نفس مجموعة الاختيار السداسية، ويُرتَّبان في مكانيهما بفضل سؤالي الدور — «الذي يُقاس، المذكور أولًا» مقابل «المذكور ثانيًا، المسطرة المرجعية». مفاتيح الخيارات هي نفس السلاسل التي تستقبلها الدالة، ما يوفّر طبقة تحويل.

stated يجعل المعامل اختياريًا: إنه سؤال ثانٍ بنعم/لا، يسأل «هل ذُكر هذا المعامل في الأمر». إن لم يُذكر (أقل من 0.5)، لا يُعبَّأ المعامل كله وتسري القيمة الافتراضية للدالة نفسها.

Dispatcher يبني كل الأسئلة دفعة واحدة من الـ spec. بعدها كل أمر هو طلب واحد: يُرفق اختيار الدالة مع جميع معاملات الدوال العشر معًا، والكود يقرأ إجابات الدالة المختارة فقط — تُطرح كل الأسئلة قبل معرفة «أي دالة اختيرت»، وهذا هو الشكل الأقصى للتوسع التخميني:

python
assistant = Dispatcher(SPEC, TOOLS, client)   # SPEC 来自 spec.json,TOOLS 来自 trader.py
print(f"{len(assistant.questions)} questions per command, among them:")
for qid in ("__tool__", "plot_price.style", "plot_price.style?", "compare_returns.symbols.NVDA"):
    question = assistant.questions[qid]
    print(f"  {qid:<30}{question['type']:<8}{str(question['instructions'])[:64]}")

ينبغي أن ترى (من الإصدار الرسمي):

text
54 questions per command, among them:
  __tool__                      choice  What is the user asking the trading assistant to do?
  plot_price.style              choice  Does the user want a plain line or candles?
  plot_price.style?             noul    Does the user say how the chart should be drawn, such as a line,
  compare_returns.symbols.NVDA  noul    Does the user want NVDA in the comparison?

الدوال العشر فيها 28 معاملًا قابلًا للتعبئة، وبإضافة اختيار الدالة وسؤال stated لكل منها، يُطرح 54 سؤالًا لكل أمر في طلب واحد. تُكتب الأسئلة بـ«الفكرة» لا بـ«الكلمات التي قد يقولها المستخدم»: المطابقة تكون للمعنى — is amd tracking nvidia lately تصيب rolling_correlation، بينما كلمتا tracking وlately لا تظهران أصلًا في spec.json.

شغّل أوامر الجهة الرسمية البالغة 14 أمرًا (المخرجات هي القيم المنشورة رسميًا):

text
  "show nvda 1h"
      plot_price(symbol='NVDA', resolution='1h')                        confidence 0.78   tool 1.00
  "plot rolling correlation between nvda and spy for the past month"
      rolling_correlation(symbol='NVDA', benchmark='SPY', window='1mo') confidence 0.91   tool 1.00
  "when during the day does nvda trade the most"
      intraday_pattern(symbol='NVDA')                                   confidence 0.53   tool 1.00
  "what moved today"
      top_movers(window='1d', direction='gainers')                      confidence 0.90   tool 0.90
  "what tickers do you have"
      list_symbols()                                                    confidence 1.00   tool 1.00
  "how did the market do this week"
      market_summary(window='1w')                                       confidence 0.96   tool 0.99
  "candles for tesla with a 20 period moving average"
      plot_price(symbol='TSLA', style='candles', moving_average='20')   confidence 0.69   tool 0.97
  "compare nvda amd and msft over the past three months"
      compare_returns(symbols=['NVDA', 'AMD', 'MSFT'], window='3mo')   confidence 0.94   tool 1.00
  "how volatile is tsla"
      volatility(symbol='TSLA')                                         confidence 0.96   tool 1.00
  "biggest losers today"
      top_movers(window='1d', direction='losers')                       confidence 0.98   tool 0.98
  "worst drawdown for nvda this quarter, and chart it please"
      drawdown(symbol='NVDA', window='3mo', plot=True)                  confidence 0.84   tool 0.84
  "spy stats for the last month"
      summary_stats(symbol='SPY', window='1mo')                         confidence 0.88   tool 0.88
  "show me apple daily with volume"
      plot_price(symbol='AAPL', resolution='1d', include_volume=True)   confidence 0.75   tool 0.85
  "is amd tracking nvidia lately"
      rolling_correlation(symbol='AMD', benchmark='NVDA')               confidence 0.82   tool 0.82

الأمران الطويلان يُظهران القيمة بأوضح صورة: أمر rolling correlation يملأ أربعة معاملات بجملة واحدة، ويضع symbol وbenchmark كلًّا في مكانه؛ وأمر compare يضع ثلاثة ticker في المجموعة ويترك ثلاثة أخرى خارجها.

  • أستطيع أن أقول إلى أي سؤال يتحول كل من أشكال المجموعات المغلقة الثلاثة، ولماذا لا يظهر limit: int ضمن أسئلة الـ 54
  • أعرف لماذا تستخدم مفاتيح خيارات الـ spec مباشرةً السلاسل التي تستقبلها الدالة

الخطوة 6: قراءة confidence — أضعف حكم يحدد ثقة الاستدعاء كله ​

لماذا: قيمة confidence في استدعاء الدوال تُبلِّغ عن أضعف حكم في الاستدعاء بأكمله، لا عن حاصل ضرب جميع الأحكام — فمعامل واحد خاطئ يكفي لإفساد النتيجة.

النص الرسمي: حاصل الضرب يجيب عن سؤال آخر («هل كل جزء صحيح؟»)، وكلما زادت المعاملات انخفض، بغضّ النظر عن الحكم المُشكِّك فيه حقًا. min يتيح لك رؤية نقطة الضعف مباشرة. مطابقة معاملًا بمعامل لطلب is amd tracking nvidia lately (القيم الرسمية المنشورة):

text
"is amd tracking nvidia lately"  ->  rolling_correlation(symbol='AMD', benchmark='NVDA')   confidence 0.82
  symbol      'AMD'                     p 0.87   AMD 0.87  NVDA 0.13  AAPL 0.00
  benchmark   'NVDA'                    p 0.78   NVDA 0.92  AMD 0.08  AAPL 0.00
  window      omitted, default stands   p 0.96
  resolution  omitted, default stands   p 0.99
  weakest argument: benchmark

window وresolution كلاهما محذوف — كلمة lately لم تحدّد مدى المدة الرجعية ولا أي bar، لذا يعمل rolling_correlation وفق قيمه الافتراضية: شهر واحد، وشموع ساعية. هذا هو دور stated: بدونه يُضطر Choice إلى تحديد نافذة، وسيفعل ذلك بثقة تامة.

قيمة confidence وهي 0.82 تأتي من أضعف benchmark (p يساوي 0.78). هذه المعلومة قابلة للاستخدام مباشرة لقرار التنفيذ من عدمه، أو لسؤال المستخدم «هل المقارنة مع NVDA مناسبة؟» — والعتبة تُحدَّد في الكود الذي تكتبه.

أخيرًا نعيد ربط السيناريوهين بالمبدأ نفسه. في جانب اختيار المهارة، تقول الأسئلة الشائعة الرسمية لـ Agent Skill العكس تمامًا: إذا كنت تهتم فقط بـ«اختيار الأفضل»، خذ الخيار ذا الاحتمال الأعلى مباشرة، ولا حاجة لتعيين عتبات confidence في كل مكان؛ أما عند الحاجة إلى خوارزميات إحصائية فاستخدم probabilities. أما الطلبان اللذان ناقشناهما فيضبطان «هل نقول أم لا» — وهي بوابة تُضبط باحتمالات Noul نفسها، إذ لا يملك Noul أصلًا قيمة confidence منفصلة.

ينبغي أن ترى: التفكيك معاملًا بمعامل يطابق الجدول أعلاه؛ وسطر weakest argument: benchmark يشير إلى المعامل الأكثر إثارة للشك في الاستدعاء بأكمله.

  • أستطيع أن أشرح لماذا يُؤخذ confidence كحد أدنى (min) لا حاصل ضرب، ومن أين تأتي القيم الافتراضية عند حذف stated

📋 Prompt السحري ​

«Prompt» في هذه الصفحة هو قالب للأسئلة وكود اتخاذ القرار الموجَّه إلى API — انسخه واستبدل العناصر النائبة 【】 (والتي تحمل ? اختيارية) لتستخدمه مباشرة.

📝 مجموعة أسئلة ترتيب المهارات (سؤال Choice واحد + أربعة أسئلة Noul) ​

النتيجة المتوقعة: تفكيك «أي مهارة يجب تحميلها» إلى مجموعتي حكم — ترتيب وبوابات — والحصول على جميع الإجابات في طلب واحد.

python
QUESTIONS = {
    "which": Choice(
        instructions="【这些技能里哪个适合用户的这一轮请求?】",
        criteria={【技能名】: 【一行索引描述】},  # 194 个也放得下,上限 255
    ),
    "gate::acts": Noul(
        instructions="【用户是要对文件 / 账户 / 设备 / 线上服务动手,还是只要解释或建议?】",
    ),
    "gate::procedure": Noul(
        instructions="【认真回答这个问题的专家要不要查一份具体流程或命令集?】",
    ),
    "gate::prose": Noul(
        instructions="【一个什么都接触不到的通才,纯靠文字能把这请求答满意吗?】",  # 反向题:yes = 不需要技能
    ),
    "named": Noul(
        instructions="【请求点名了具体工具、格式、模板或方法吗?】",
    ),
}
# 必填项:state = {"request": 【用户这轮的原话】, "recent_context": 【近期对话,可为空串】}
# 选填项:闸门题按你的领域改问法,但保持「问动作,不问主题」?
# 输出规范:probabilities 降序取前三;gate = 三道动作题的均值(prose 取 1-p 再平均);named 单独读
# 约束条件:
# ✅ 问「要不要动手」,别问「主题是什么」——主题题分不开 explain what a monad is
# ✅ 官方英文原文经过了 452 请求实测,中文化前先用自己的数据验证
# ❌ 不要问「该不该建议技能」——那是代码的活,改政策不该改问题

✅ القرار المقترح للعتبتين (الختام بجدول قيم الحقيقة) ​

النتيجة المتوقعة: تحوُّل مجموعتي الاحتمالات إلى «اسم مهارة واحد على الأكثر»، مع وقوع السياسة بأكملها في ثوابت مرئية.

python
GATE_THRESHOLD = 【0.30】   # 三道动作 Noul 的均值,官方给这套请求挑的起点
NAMED_THRESHOLD = 【0.50】  # 「点名了方法」单独开门,不进平均
FITS_THRESHOLD  = 【0.30】  # 复查里最好的 fits 低于它就整组放弃
SHORTLIST = 【3】            # 第一道带进第二道的候选数

def suggest(request):
    wide = rank_wide(request)
    if not (wide["gate"] >= GATE_THRESHOLD or wide["named"] >= NAMED_THRESHOLD):
        return ()                        # 两个理由都不成立:什么都不建议
    shortlist = top(wide["ranked"], SHORTLIST)
    result = rerank(request, shortlist)  # 第二道:选项 = 前三的全文,真二请求
    if max(result["fits"].values()) < FITS_THRESHOLD:
        return ()                        # 允许全员落选
    return (result["winner"],)
# 必填项:三个阈值——官方说明它们是起点,不是默认值
# 选填项:建议块措辞保留「可以忽略」,并给「没有建议」也发一句话?
# 输出规范:至多一个技能名,或 ();包进 <skill_relevance> 块加在 roster 之后
# 约束条件:
# ✅ 建议块加在 roster 之后,别改 roster 文本——prefix caching 靠它逐回合一致
# ✅ 阈值、问题措辞集中在一个文件里,方便人审(官方 Agent Skill 的建议)
# ❌ 不要把建议写死成命令——自信的错误建议比没有更糟(实测弄坏 7 个本来对的)

🔧 قالب spec لاستدعاء الدوال (مدخل واحد لكل دالة) ​

النتيجة المتوقعة: كل معامل من معاملات المجموعات المغلقة في التوقيع يحصل على سؤال «يستطلع الرأي»، فتكون القيم الداخلة إلى الدالة قانونية دائمًا.

json
{
  "question": "【用户想让这个助手做什么?(挑函数的那道题)】",
  "functions": {
    "【函数名】": {
      "description": "【用户想要这个函数做什么,一段话】",
      "arguments": {
        "【参数名】": {
          "question": "【这个参数用户要什么——按想法问,不按参数名问】",
          "stated": "【用户说没说这个参数?】",
          "options": {
            "【合法值,即 Literal 成员】": "【这个值是什么意思,一行】"
          }
        }
      }
    }
  }
}
# 必填项:每个 Literal 参数一条;list[Literal] 的 question 里放 {} 占位(每成员一道 Noul)
# 选填项:可选参数配 stated;bool 参数不需要 options(一道 Noul ≥ 0.5 为开)?
# 输出规范:Dispatcher 一次建 54 道问题(本页示例规模),每条命令一次请求
# 约束条件:
# ✅ 选项键 = 函数收的字符串,省掉映射层
# ✅ spec 可以让 LLM 从签名帮你写(官方原话),写完人审一遍
# ❌ 不要拿参数名当问题("Which resolution?")——没给命令任何可匹配的东西

نقاط تحقق ✅ ​

  • أستطيع أن أصف ما يفعله كل من الطلبين: الأول سؤال Choice واحد يرتّب 194 مهارة + أربعة أسئلة Noul للبوابات؛ والثاني يقتصر على الثلاثة الأولى، مع إعادة فحص بالوصف الكامل، مع السماح برفض الجميع
  • أعرف لماذا يجب إرسال طلب ثانٍ: خيارات الطلب الثاني (النص الكامل للثلاثة الأولى) لا يمكن بناؤها إلا بعد ترتيب الطلب الأول — وهي إحدى حالات الطلبين الحقيقيتين الثلاث الرسمية
  • أستطيع أن أروي تجربة الأذرع الثلاثة: التحميل الخاطئ 15.7% ← 7.9% (أكثر من النصف)، والتحميل غير المفيد 14.0% ← 5.2% (قرابة الثلثين)؛ أرضية oracle هي 3.2% / 4.1%
  • أستطيع أن أعدّد أشكال المجموعات المغلقة الثلاثة في استدعاء الدوال: Literal ← Choice، وlist[Literal[...]] ← سؤال Noul لكل عنصر، وbool ← Noul؛ الأرقام والنص الحر لا يُسأل عنها، وتُحفظ القيم الافتراضية
  • أعرف أن confidence في استدعاء الدوال يُؤخذ من أضعف حكم (min) لا من حاصل الضرب، وأعرف أيضًا أنه عند اختيار المهارة بـ«الأفضل فقط» لا حاجة لتعيين عتبات في كل مكان

تنبيهات للمزالق ​

❌ مطالبة Jev بالإجابة مباشرة عن «ماذا يجب أن يفعل الـ agent في الخطوة التالية» ​

النص الأصلي في SKILL.md: هذا النوع من الأسئلة يعني عادةً أنك تسأل في الطبقة الخاطئة. الأسلوب الصحيح هو تفكيك القرار إلى الأحكام التي يعتمد عليها — الترتيب، وبوابة الإجراء، وبوابة التسمية، وfits — فتُعطى الأحكام إلى Jev، بينما يُكتب القرار (عتبتان + جدول قيم الحقيقة) في الكود، مرئيًا وقابلًا للاختبار. الطلبان في هذه الصفحة، والثوابت الأربعة، هما نموذج كامل لذلك.

❌ تعيين عتبات confidence في كل مكان ​

هذه الفقرة موجودة في قائمة الأسئلة الشائعة الرسمية لـ Agent Skill: إذا كنت تهتم فقط بـ«اختيار الأفضل»، خذ الخيار ذا الاحتمال الأعلى مباشرة. وعند الحاجة إلى خوارزميات إحصائية استخدم probabilities. البوابات في هذه الصفحة تستخدم احتمالات Noul نفسها (فـ Noul لا يملك قيمة confidence منفصلة)؛ أما confidence في جانب استدعاء الدوال فيُستخدم فعلًا كـ«درجة اليقين»، ويُؤخذ من أضعف حكم فقط.

❌ استخدام سؤال الموضوع كبوابة ​

سؤال «هل هذا متعلق بالبرمجيات؟» لا يفصل بين explain what a monad is وطلب برمجي يحتاج إلى مهارة — فكلاهما برمجي. سؤال الإجراء يسأل عن «هل سنتدخل في ملفات المستخدم أو حسابه أو أجهزته أو خدماته عبر الإنترنت»، وهذا ما يفصل حقًا. وفي الأسئلة العكسية (prose_suffices) تذكّر أخذ 1-p قبل إدخالها في المتوسط.

❌ استخدام اسم المعامل كسؤال ​

"Which resolution?" الانتقاد الرسمي المباشر: لم يُعطَ الأمر أي شيء يمكن مطابقته. اسأل عن الفكرة: "How far back is the user asking about - today, the past week, the past month, or the past three months?" — وبهذا فقط يقع this quarter على 3mo، وlately لا يملأ شيئًا بصدق.

تقنيات متقدمة (اختياري) ​

🔧 وجّهها إلى دليل مهاراتك الخاص. النص الرسمي حرفيًا: يكفي استبدال hermes_roster.json — كل سؤال في الأعلى يقرأ أربعة حقول فقط هي name وdescription وdescription_full وbody، ولا يوجد في suggest() أي شيء آخر خاص بـ Hermes.

📚 ماذا لو كان الدليل أكبر. التوصية الرسمية: بهذا الحجم يكفي سؤال Choice واحد تمامًا؛ وإذا تضاعف الحجم عدة مرات فقسّمه إلى كتل ورتّبها، ثم أعد ترتيب الفائزين من كل كتلة كما في الخطوة 3. يستخدم دليل Rerank (البحث والمطابقة) النهج نفسه بخطوتين «قائمة قصيرة أولًا ثم إعادة التقييم»، مع استبدال السؤال الأول الرخيص بـ BM25.

⏳ إعادة تشغيل جميع الأرقام بدون أي مفتاح. استدعاءات الدليلين مسجلة في json_cache.json الخاص بكل منهما ومفهرسة حسب المدخلات، وإعادة التشغيل لا ترسل أي طلب؛ احذف ملف الكاش فيصبح كل شيء live. تسجيلات اقتراحات المهارات المنشورة تستخدم jev-1.14.0 + claude-haiku-4-5-20251001 (عرض 2026-10-30)، واستدعاءات الدوال تستخدم jev-1.12.

🚀 دع وكيل البرمجة يكتب هذه الأشياء عنك. ثبّت Agent Skill الخاص بـ TypeSafe وسلّمه هذه الصفحة لينفذها كما هي:

bash
claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

التوصية الرسمية هي تجميع الأسئلة وثوابت العتبات في ملف واحد لتسهيل المراجعة البشرية — وGATE_THRESHOLD / NAMED_THRESHOLD / FITS_THRESHOLD في هذه الصفحة وأسئلة البوابات الأربعة هي بالضبط ما يجب وضعه في ذلك الملف الواحد. راجع التطوير مع Claude Code.

خلاصة الدرس ​

✅ اقتراح المهارات = طلبان + عتبتان: الطلب الأول سؤال Choice واحد يرتّب جميع المهارات الـ 194، وأربعة أسئلة Noul تحرس البوابة (ثلاثة أسئلة إجراء تسأل «هل نتدخل» وسؤال واحد يسأل «هل ورد ذكر صريح»)؛ الطلب الثاني ينظر إلى الثلاثة الأوائل فقط، ومع كل منها وصف كامل + أول 700 حرفًا من SKILL.md، وإذا كانت fits كلها منخفضة فتُهمل المجموعة بأكملها. الناتج اسم مهارة واحد على الأكثر، ويُضاف كتلة <skill_relevance> بعد الـ roster.

✅ الفوائد والتكاليف المقاسة فعليًا: التحميل الخاطئ 15.7% → 7.9%، والتحميل غير المفيد 14.0% → 5.2%؛ أرضية oracle البالغة 3.2% / 4.1% تبيّن أن أفضل اقتراح لا يمكنه التفوق على «إعطاء الإجابة مباشرة». من 280 طلبًا مغطى حسّن الاقتراح 29 منها وأفسد 7 — وجود عبارة «يمكن تجاهله» في صياغة الاقتراح ليس مجاملة.

✅ استدعاء الدوال = مواصفة واحدة + طلب واحد: closed_sets يقرأ التواقيع ويصنّف معاملات المجموعات المغلقة إلى ثلاثة أشكال: choice / set / flag؛ تُطرح 54 سؤالًا في طلب واحد، والكود يقرأ إجابات الدالة المختارة فقط. ما يدخل الدالة هو دائمًا قيمة قانونية من Literal؛ الأرقام والنص الحر لا تُسأل عنها وتُترك على الافتراضي.

✅ الثقة تُؤخذ من الأضعف: يقين الاستدعاء كله يحدده الحكم الأقل يقينًا (min، وليس حاصل الضرب)؛ stated يجعل المعامل غير المذكور يُحذف بالكامل فيعمل الافتراضي؛ weakest() يشير إلى المعامل الذي يجب الشك فيه.

مراجعة حقول الإعداد الرئيسية:

الحقلقيمة هذه الصفحةالشرح
SHORTLIST3عدد المرشحين الذين يحملهم الطلب الأول إلى الثاني
EXCERPT_CHARS700عدد أحرف بداية SKILL.md التي يحملها كل مرشح (يخزن ملف roster لكل عنصر 1600)
GATE_THRESHOLD0.30متوسط Noul لأفعال ثلاثة يتجاوز الحد يعني «طلب مهارة»
NAMED_THRESHOLD0.50«تمت تسمية طريقة» يفتح بابًا منفصلًا ولا يدخل في المتوسط
FITS_THRESHOLD0.30إذا كان أفضل fits في الفحص المتكرر أقل منه فتُهْمَل المجموعة بأكملها
MEMBER / STATED0.5دخول أعضاء set إلى المجموعة / عتبة تعبئة المعامل الاختياري
TYPESAFE_MODELjev-1.14.0 (مهارة) / jev-1.12 (استدعاء دالة)النسخة المسجّلة رسميًا؛ التشغيل المباشر يقفل نسخة الـ ID الخاصة بك
AGENT_MODELclaude-haiku-4-5-20251001الوكيل الخاضع للاختبار، ملاحظة رسمية: التثبيت يضمن ثبات النتيجة

دروس ذات صلة:

استعراض الدرس التالي ​

الـ harness في هذا الدرس يقرر «أي أداة تُستدعى وأي مهارة تُختار»، والدرس التالي يضيف الذاكرة إلى الـ harness: نظام ذاكرة بسيط: دع Jev يقرر ما يُحفظ.

ستتعلم:

  • بوابة Noul واحدة بعد الاستدعاء تحكم «هل صرّح هذا الطلب بحقيقة عن العميل تستحق الحفظ»، ولا يُخزَّن إلا إذا كانت P ≥ 0.5
  • تُخزَّن الذاكرة في قاموس Python عادي وتُدمَج في state قبل الاستدعاء——ask_with_memory() و ask() بنفس المعاملات ونفس قيمة الإرجاع، واستبدالها لا يتطلب تعديل أي كود آخر
  • قياس رسمي فعلي: توجيه التذاكر اللاحقة تحوّل من 3/6 إلى 6/6، مع طلب إضافي واحد فقط لكل استدعاء
  • مفهوم الـ harness كما عرّفته الجهة الرسمية: الكود المحيط بالنموذج الذي يمنحه قدرات إضافية (tool calls، تشغيل في حلقة)——الـ Dispatcher في هذه الصفحة هو النوع الذي يضيف tool calls إلى النموذج
gaodong.aiAboutPrivacyContact

Independent tutorials, not affiliated with any product mentioned. Product names and trademarks belong to their owners. Check official pages for prices and policies.