أنماط التكامل

نظرة سريعة

ما: أنماط النشر الشائعة لـ CI/CD، حلقات الوكلاء، وعمليات الامتثال لماذا: اختر الاستراتيجية الصحيحة للتكامل لتلبية احتياجات الثقة والتدقيق من: المعماريون والمطورون الذين يخططون لنشر بوابة القرار المتطلبات المسبقة: getting_started.md

نظرة عامة على النمط

النمط	مسار الثقة	السرعة	أثر التدقيق	حالة الاستخدام
بوابة CI/CD	تم التحقق منه	أبطأ	تشغيل كامل	نشر الإنتاج
حلقة الوكيل	مؤكد -> تم التحقق منه	سريع -> بطيء	اختياري -> كامل	تخطيط LLM نحو البوابات
الإفصاح المنظم	تم التحقق منه	بطيء	كامل	إصدار البيانات مع التدقيق
سير عمل الامتثال	تم التحقق منه	بطيء	كامل	بوابات متعددة المراحل
اتحاد MCP	تم التحقق منه	متنوع	كامل	مصادر الأدلة الخارجية

النمط 1: بوابة CI/CD

متى تستخدم: بوابات الجودة الآلية في خطوط أنابيب CI/CD

تدفق:

تشغيل الأدوات -> إصدار JSON
scenario_start -> إنشاء تشغيل
scenario_next -> DG يقرأ JSON عبر مزود json
نتيجة القرار تدفع النشر

قم بتكوين مزود json مع جذر يشير إلى مساحة عمل الأدلة الخاصة بك، واحتفظ بمسارات الملفات نسبية لذلك الجذر.

السيناريو (حقول دقيقة، الحد الأدنى):

{
  "scenario_id": "ci-gate",
  "namespace_id": 1,
  "spec_version": "v1",
  "stages": [
    {
      "stage_id": "quality",
      "entry_packets": [],
      "gates": [
        {
          "gate_id": "quality-checks",
          "requirement": {
            "And": [
              { "Condition": "tests_ok" },
              { "Condition": "coverage_ok" },
              { "Condition": "scan_ok" }
            ]
          }
        }
      ],
      "advance_to": { "kind": "terminal" },
      "timeout": null,
      "on_timeout": "fail"
    }
  ],
  "conditions": [
    {
      "condition_id": "tests_ok",
      "query": {
        "provider_id": "json",
        "check_id": "path",
        "params": {
          "file": "test-results.json",
          "jsonpath": "$.summary.failed"
        }
      },
      "comparator": "equals",
      "expected": 0,
      "policy_tags": []
    },
    {
      "condition_id": "coverage_ok",
      "query": {
        "provider_id": "json",
        "check_id": "path",
        "params": {
          "file": "coverage.json",
          "jsonpath": "$.total.lines.percent"
        }
      },
      "comparator": "greater_than_or_equal",
      "expected": 85,
      "policy_tags": []
    },
    {
      "condition_id": "scan_ok",
      "query": {
        "provider_id": "json",
        "check_id": "path",
        "params": {
          "file": "scan.json",
          "jsonpath": "$.summary.critical"
        }
      },
      "comparator": "equals",
      "expected": 0,
      "policy_tags": []
    }
  ],
  "policies": [],
  "schemas": [],
  "default_tenant_id": 1
}

تفسير نتيجة scenario_next:

Look at result.decision.outcome.kind:
- تقدم / اكتمال -> الأبواب التي تم اجتيازها
- hold -> الأبواب غير مُرضية
- فشل -> تشغيل فشل
اختياري: feedback: "trace" يمكن أن يعيد حالة البوابة + الحالة الشرطية (إذا سمحت سياسة ملاحظات الخادم بذلك).

النمط 2: حلقة الوكيل

متى تستخدم: وكلاء LLM الذين يتجهون نحو تحقيق البوابة

تدفق:

يقوم الوكيل بتشغيل الأدوات -> استخراج القيم
precheck -> تقييم سريع (أدلة مؤكدة)
إذا مرت البوابات -> تشغيل scenario_next

مخرجات الفحص المسبق محدودة:

تعيد { decision, gate_evaluations }.
gate_evaluations تحتوي على gate_id، status، وتتبع الحالة فقط.
إنه لا يتضمن قيم الأدلة أو الأخطاء.

إذا كنت بحاجة إلى أخطاء الاستدلال، استخدم evidence_query أو runpack_export في تشغيل مباشر.

النمط 3: الإفصاح المنظم

متى تستخدم: إصدار البيانات مع سجل التدقيق

تدفق نموذجي:

موافقات البوابة باستخدام RequireGroup.
عند المرور، استخدم scenario_submit لتسجيل البيانات الوصفية.
إرسال حزم البيانات (تحت التحكم في السياسة).

scenario_submit هو فقط للتدقيق ويتطلب:

run_id, tenant_id, namespace_id, submission_id
payload, content_type, submitted_at

النمط 4: سير عمل الامتثال (متعدد المراحل)

استخدم ترتيب المرحلة بالإضافة إلى advance_to.kind = "linear" للانتقال إلى المرحلة التالية حسب ترتيب المواصفات:

{
  "stage_id": "dev",
  "advance_to": { "kind": "linear" }
}

استخدم branch عندما تحتاج إلى وجهات مختلفة بناءً على نتيجة البوابة.

النمط 5: اتحاد MCP (المزودون الخارجيون)

متى تستخدم: مصادر الأدلة خارج المدمجة

الإعداد (بالضبط):

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

[[providers]]
name = "cloud"
type = "mcp"
url = "https://cloud.example.com/rpc"
capabilities_path = "contracts/cloud.json"
allow_insecure_http = false
timeouts = { connect_timeout_ms = 2000, request_timeout_ms = 10000 }

[trust]
# Require signatures from these key files
default_policy = { require_signature = { keys = ["/etc/decision-gate/keys/cloud.pub"] } }

ملاحظات التفاعل (Runpack + النصوص)

checkedfiles في runpackexport مقابل runpack_verify

عند استدعاء runpack_export مع include_verification = true، تعكس قيمة report.checked_files التي تم إرجاعها التحقق الذي تم تنفيذه قبل إضافة artifacts/verifier_report.json إلى البيان. بالنسبة لنفس عملية runpack، من المتوقع أن تكون runpack_verify.report.checked_files بالضبط +1 لأنها تتحقق من البيان النهائي (بما في ذلك verifier_report.json).

آثار النص: العقد مقابل إطار الاختبار

DG runpack artifact artifacts/tool_calls.json is the canonical contract DG runpack artifact artifacts/tool_calls.json هو السطح القياسي للعقد ويحتوي على سجلات استدعاء أدوات حالة التشغيل التي تحتوي على تجزئة فقط.
System-test artifact tool_transcript.json is raw client-side capture used نظام الاختبار tool_transcript.json هو تسجيل خام من جانب العميل يستخدم للتشخيصات وليس قطعة أثرية لعقد تشغيل DG.

تحذير من الحمولة الحساسة

scenario_submit.payload و scenario_trigger.payload يتم الاحتفاظ بهما في سجلات حالة التشغيل ويتم تصديرهما إلى حزم التشغيل حسب التصميم. لا تضع الأسرار الخام في هذه الحقول.

قائمة التحقق من النشر

يقوم التكوين بالتحقق من الصحة (decision-gate config validate)
يجب أن تحتوي مقدمو الخدمة على ملفات capabilities_path صالحة
namespace.allow_default تم تعيينه بشكل صحيح للاستخدام المحلي فقط
تم تكوين المصادقة + TLS (أو tls_termination = "upstream") للربط غير المتكرر
trust.default_policy و min_lane تم تعيينهما للإنتاج
سياسة الكشف عن الأدلة تم تعيينها (allow_raw_values, require_provider_opt_in)