بروتوكول مزود الأدلة

نظرة سريعة

ما: بروتوكول JSON-RPC 2.0 لمزودي الأدلة الخارجيين (MCP) لماذا: السماح لـ Decision Gate باستدعاء مصادر الأدلة المخصصة دون تغييرات جوهرية من: مطورو المزودين، مهندسو التكامل، منفذو MCP المتطلبات المسبقة: JSON-RPC 2.0 و evidence_flow_and_execution_model.md

---

كيف تستدعي بوابة القرار مقدمي الخدمة

• يستدعي Decision Gate أداة واحدة: evidence_query.
• المكالمات هي دائمًا tools/call مع name = "evidence_query".
• بوابة القرار لا تعتمد على tools/list في وقت التشغيل؛ يتم تحميل قدرات المزود من capabilities_path في التكوين.

يجب على مقدمي الخدمة تنفيذ tools/list من أجل التوافق مع MCP وقوالب SDK، لكن Decision Gate لا تعتمد عليه.

---

إعداد موفر خارجي

يستخدم مقدمو الخدمات الخارجيون type = "mcp" ويجب عليهم إعلان capabilities_path:

[[providers]]
name = "git"
type = "mcp"
# stdio transport
command = ["/usr/local/bin/git-provider", "--repo", "/repo"]
capabilities_path = "contracts/git.json"

[[providers]]
name = "cloud"
type = "mcp"
# HTTP transport
url = "https://evidence.example.com/rpc"
allow_insecure_http = false
capabilities_path = "contracts/cloud.json"
# Optional auth + timeouts
# auth = { bearer_token = "YOUR_TOKEN" }
# timeouts = { connect_timeout_ms = 2000, request_timeout_ms = 10000 }

موفرو الخدمة المدمجون يستخدمون type = "builtin" وهم ليسوا خوادم MCP. يجب أن تكون أسماء الموفرين فريدة؛ المعرفات المدمجة (time, env, json, http) محجوزة ولا يمكن استخدامها من قبل موفري MCP.

---

أداة الاستدعاء: evidence_query

الطلب (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "evidence_query",
    "arguments": {
      "query": {
        "provider_id": "file-provider",
        "check_id": "file_size",
        "params": { "path": "report.json" }
      },
      "context": {
        "tenant_id": 1,
        "namespace_id": 1,
        "run_id": "run-123",
        "scenario_id": "ci-gate",
        "stage_id": "main",
        "trigger_id": "commit-abc",
        "trigger_time": { "kind": "unix_millis", "value": 1710000000000 },
        "correlation_id": null
      }
    }
  }
}

الاستجابة (JSON-RPC)

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "json",
        "json": {
          "value": { "kind": "json", "value": 1024 },
          "lane": "verified",
          "error": null,
          "evidence_hash": null,
          "evidence_ref": { "uri": "dg+file://evidence-root/report.json" },
          "evidence_anchor": {
            "anchor_type": "file_path_rooted",
            "anchor_value": "{\"path\":\"report.json\",\"root_id\":\"evidence-root\",\"size\":1024}"
          },
          "signature": null,
          "content_type": "application/json"
        }
      }
    ]
  }
}

مهم: evidence_anchor.anchor_value هو سلسلة نصية. إذا كنت بحاجة إلى بيانات مرجعية منظمة، قم بتشفيرها كـ JSON قياسي واحتفظ بسلسلة JSON. بالنسبة لـ file_path_rooted، قم بتضمين الحقول العددية root_id و path.

---

هيكل EvidenceQuery

{
  "provider_id": "string",
  "check_id": "string",
  "params": "any"  // optional
}

• provider_id يتطابق مع اسم المزود في الإعدادات.
• check_id هو اسم قدرة المزود (ليس معرف شرط السيناريو).
• params هو خاص بمزود الخدمة؛ يمكن تجاهله أو أن يكون null.

---

هيكل EvidenceContext

{
  "tenant_id": 1,
  "namespace_id": 1,
  "run_id": "run-123",
  "scenario_id": "ci-gate",
  "stage_id": "main",
  "trigger_id": "commit-abc",
  "trigger_time": { "kind": "unix_millis", "value": 1710000000000 },
  "correlation_id": null
}

يتم توفير السياق بواسطة Decision Gate وهو متاح لمقدمي الخدمات للاستفسارات الحتمية (مثل، الفحوصات في نقطة زمنية معينة).

---

هيكل EvidenceResult

{
  "value": { "kind": "json|bytes", "value": "any" } | null,
  "lane": "verified|asserted",
  "error": { "code": "string", "message": "string", "details": "object|null" } | null,
  "evidence_hash": { "algorithm": "sha256", "value": "hex" } | null,
  "evidence_ref": { "uri": "string" } | null,
  "evidence_anchor": { "anchor_type": "string", "anchor_value": "string" } | null,
  "signature": { "scheme": "ed25519", "key_id": "string", "signature": [0, 1, 2] } | null,
  "content_type": "string" | null
}

ملاحظات:

• value.kind = "bytes" يستخدم مصفوفة JSON من الأعداد الصحيحة 0..255.
• signature.signature هو مصفوفة JSON من البايتات (تسلسل Vec<u8>).
• إذا كان evidence_hash مفقودًا، يقوم Decision Gate بحسابه من value قبل التحقق.
• إذا كان evidence_hash موجودًا، يجب أن يتطابق مع الهاش القياسي لـ value أو سيتم رفض الاستجابة.

---

معالجة الأخطاء

يجب على المزودين إرجاع EvidenceResult مع تعيين error للفشل المتوقع (مثل الملفات المفقودة، المعلمات غير الصالحة، إلخ).

إذا أعاد المزود خطأ JSON-RPC، فإن بوابة القرار تعامله على أنه فشل من المزود وتظهره كـ code = "provider_error" من جانبها.

---

ملاحظات النقل

stdio

• Decision Gate ينشئ المزود باستخدام command = [..].
• يتم تأطير الرسائل باستخدام رؤوس Content-Length.

HTTP

• يقوم Decision Gate بإرسال POST بتنسيق JSON-RPC إلى url المكون.
• يمكن تكوين رمز الحامل الاختياري عبر auth.bearer_token.

---

معجم

EvidenceQuery: طلب مزود { provider_id, check_id, params }. EvidenceResult: استجابة المزود (القيمة + البيانات الوصفية). MCP: بروتوكول سياق النموذج (استدعاءات أدوات JSON-RPC 2.0). Provider Contract: ملف JSON يعلن عن الفحوصات، مخطط المعلمات، مخطط النتائج، والمقارنات المسموح بها.