شبكة الجاهزية

مرجع واجهة API

واجهة البحث API

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

POST/v1/capabilities/search

متن الطلب

الحقلالوصف
queryوصف المهمة بلغة طبيعية.
agent_runtimeبيئة تشغيل المُستدعِي، مثل claude-code وcursor. تُستخدم للترتيب المدرك لبيئة التشغيل.
localeاللغة المفضّلة، مثل en وzh-CN.
risk_toleranceread_only | write | destructive. تُستبعد المرشّحات الأعلى من هذه المخاطرة أو يُخفَّض ترتيبها.
latency_budget_msإسقاط المرشّحات التي يتجاوز كمونها المتوقع الميزانية.
require_freshness_secondsاشتراط أدلة فحص أحدث من هذه النافذة.
limitالحد الأقصى للمرشّحين، 1–50. القيمة الافتراضية 10.
request.sh
curl -X POST http://101.32.68.30/v1/capabilities/search \
  -H 'Authorization: Bearer $API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "extract tables from a PDF into CSV",
    "agent_runtime": "claude-code",
    "locale": "en",
    "risk_tolerance": "read_only",
    "latency_budget_ms": 10000,
    "limit": 10
  }'

الاستجابة

ثلاث مجموعات: recommended (استدعِ هذه)، وfallbacks (استخدمها عند إخفاق الموصى بها)، وblocked (مستبعدة، مع رموز الأسباب). يحمل كل عنصر مقيَّم confidence وevidence_level وvalid_until — لا تُعاد إطلاقًا درجة بلا مصدر.

response.json
{
  "query_id": "q_123",
  "recommended": [
    {
      "capability_id": "cap_pdf_extract_table",
      "action": "extract_table",
      "interface_type": "mcp_remote",
      "invoke_now_score": 0.87,
      "task_success_score": 0.82,
      "confidence": 0.76,
      "status": "routeable",
      "valid_until": "2026-06-10T12:31:00Z",
      "evidence_level": "E4_protocol_probe_passed",
      "risk_level": "read_only",
      "requires_user_confirmation": false,
      "reason_codes": ["recent_probe_ok", "static_audit_passed"],
      "warnings": ["low_real_invocation_sample"]
    }
  ],
  "fallbacks": [
    {
      "capability_id": "cap_slow_but_local_cli",
      "action": "extract_table",
      "interface_type": "cli",
      "invoke_now_score": 0.61,
      "confidence": 0.70,
      "status": "fallback",
      "evidence_level": "E3_sandbox_install_passed",
      "reason_codes": ["local_execution_available"],
      "warnings": ["high_latency_observed"]
    }
  ],
  "blocked": [
    {
      "capability_id": "cap_prompt_injection_skill",
      "reason_codes": ["prompt_injection_detected"]
    }
  ]
}