مواصفات إضافة الطريقة (Method Plugin)

الإصدار: 1.1
الجمهور المستهدف: مطورو الإضافات
المخطط المعياري: shared/schemas/champollion-plugin.schema.json

نظرة عامة

يستخدم champollion نظام طرق قابلاً للتوصيل. يمكن لكل زوج لغوي استخدام طريقة ترجمة مختلفة (LLM، أو موجَّهة، أو محوِّل نصوص، إلخ). تُسجَّل الطرق في lib/translate.js وتُحدَّد لكل زوج عبر lib/pairs.js.

مهمة منصة التقييم (eval harness) هي تطوير واختبار وتصدير طرق الترجمة. أما مهمة champollion فهي استهلاكها وتنفيذها. الإضافة بيانات فقط — إعدادات، ومحتوى توجيهي، ونتائج معايير قياسية. لا توجد أكواد Python ولا اعتماديات على منصة التقييم.

تدفق البيانات

تقوم منصة التقييم بتطوير الطرق واختبارها بلغة Python. وعندما تصبح الطريقة جاهزة للنشر، تصدِّر المنصة بيان method.json وملفات بيانات توجيهية اختيارية. يقوم Champollion بتثبيت الطريقة وتنفيذها باستخدام تنفيذات الطرق المدمجة الخاصة به.

---

تنسيق إضافة الطريقة

إضافة الطريقة هي ملف JSON واحد (method.json) مع ملفات بيانات توجيهية اختيارية.

method.json — مطلوب

{
  "name": "french-formal-v1",
  "type": "llm-coached",
  "version": "1.0.0",
  "description": "Formally-tuned French with terminology enforcement and grammar coaching",
  "author": "Plugin Author",

  "config": {
    "model": "google/gemini-3.5-flash",
    "temperature": 0.2,
    "batchSize": 80,
    "register": "formal",
    "coachingFile": null,
    "coachingPrompt": null,
    "promptContext": null,
    "qualityTier": null
  },

  "locales": ["fr"],

  "benchmarks": {
    "fr": {
      "date": "2026-05-11T00:00:00Z",
      "corpus_size": 500,
      "exact_match_rate": 0.42,
      "corpus_chrf": 72.3,
      "corpus_bleu": 45.1,
      "model": "google/gemini-3.5-flash",
      "harness_version": "1.0.0"
    }
  },

  "provenance": {
    "resources": [],
    "commercialReady": false,
    "flags": ["license-unclear"]
  },

  "coaching": {
    "dir": "coaching"
  }
}

مرجع الحقول

الحقل	النوع	مطلوب	الوصف
name	string	✅	معرّف فريد للطريقة (بصيغة kebab-case)
type	string	✅	نوع طريقة Champollion: llm، llm-coached، api، google-translate، deepl، microsoft-translator، libretranslate، openai، anthropic، gemini
version	string	✅	إصدار بصيغة Semver (مثل 1.0.0)
locales	string[]	✅	رموز اللغات المحلية التي تستهدفها هذه الطريقة (واحد على الأقل)
description	string	—	وصف مقروء للبشر
author	string	—	الجهة التي طوّرت/اختبرت هذه الطريقة
config.model	string	—	معرّف نموذج OpenRouter
config.temperature	number	—	درجة حرارة LLM (من 0.0 إلى 2.0، الافتراضي: 0.3)
config.batchSize	number	—	عدد المفاتيح لكل دفعة API (من 1 إلى 200، الافتراضي: 80)
config.register	string | null	—	مستوى/نبرة اللغة الهدف (مفتاح إعداد مسبق أو نص حر)
config.coachingFile	string | null	—	مسار ملف موجّه التوجيه النصي الحر (نسبةً إلى جذر المشروع)
config.coachingPrompt	string | null	—	نص موجّه التوجيه المحلول (يُقرأ من coachingFile عند التشغيل)
config.promptContext	string | null	—	سياق التطبيق المُدرج في موجّه النظام (مثل: "أوصاف منتجات التجارة الإلكترونية")
config.qualityTier	string | null	—	فئة الجودة من تقييم المعايير القياسية (standard، high، research، verified)
benchmarks	object	—	نتائج المعايير القياسية لكل لغة محلية من منصة التقييم
provenance	object	—	الترخيص واعتماديات الموارد
coaching.dir	string	—	مسار نسبي إلى دليل بيانات التوجيه

:::info Canonical MethodConfig Shape تستخدم كتلة config مخطط MethodConfig المعياري — وهي الحقول الثمانية نفسها المستخدمة عبر champollion.config.json، وبطاقات تشغيل منصة التقييم، وmt-eval export-config، ونشر/تثبيت لوحة المتصدرين. جميع الحقول موجودة دائمًا؛ والقيم غير المستخدمة تكون null. يضمن ذلك انتقالًا سلسًا تمامًا ذهابًا وإيابًا بين التقييم والإنتاج. :::

كائن المعيار القياسي (لكل لغة محلية)

الحقل	النوع	مطلوب	الوصف
date	string	✅	طابع زمني بصيغة ISO 8601 لتشغيل المعيار القياسي
corpus_size	number	✅	عدد الإدخالات التي تم تقييمها
exact_match_rate	number	✅	من 0.0 إلى 1.0، نسبة التطابقات التامة
corpus_chrf	number	—	درجة chrF++‎ (من 0 إلى 100)
corpus_bleu	number	—	درجة BLEU (من 0 إلى 100)
model	string	✅	النموذج المستخدم أثناء التقييم
harness_version	string	✅	إصدار منصة التقييم المستخدمة

:::info Which metrics are displayed? يعرض الأمر champollion status درجتي chrF++‎ ومعدل التطابق التام من كتلة المعيار القياسي. يُقبل corpus_bleu في البيان لكنه لا يُعرض حاليًا ولا يستخدمه أي أمر من أوامر champollion. تتتبع لوحة متصدري الطرق درجات chrF++‎، والتطابق التام، ومعدل قبول FST. :::

---

كائن المصدر (Provenance)

تُبلِّغ كتلة المصدر عن حالة ترخيص الموارد المضمَّنة في الإضافة.

الحقل	النوع	الافتراضي	الوصف
resources	object[]	[]	قائمة بالموارد المضمَّنة مع name وlicense وtype
commercialReady	boolean	false	ما إذا كانت الإضافة مصرَّحًا لها بالتوزيع التجاري
flags	string[]	["license-unclear"]	أعلام حالة قابلة للقراءة آليًا

الحالة الافتراضية — تُصدَّر الإضافات مع commercialReady: false وflags: ["license-unclear"].

الحالة المصرَّح بها — عند التحقق من الترخيص: عيِّن commercialReady: true وامسح الأعلام.

---

تنسيق بيانات التوجيه

إذا كان type هو llm-coached، فينبغي أن تتضمن الإضافة ملفات بيانات توجيهية في الدليل الفرعي coaching/.

coaching/<locale>.json

{
  "grammar_rules": [
    "French adjectives agree in gender and number with the noun they modify",
    "Use 'vous' for formal contexts, 'tu' for informal"
  ],
  "dictionary": {
    "dashboard": "tableau de bord",
    "deployment": "déploiement",
    "settings": "paramètres"
  },
  "style_notes": "Prefer active voice. Avoid anglicisms where a native French term exists."
}

الحقل	النوع	مطلوب	الوصف
grammar_rules	string[]	—	قواعد تُدرج في كل موجّه LLM لهذه اللغة المحلية
dictionary	object	—	خريطة من المصطلح إلى الترجمة. تُدرج المصطلحات المطابقة كمصطلحات إلزامية.
style_notes	string	—	تعليمات أسلوبية بنص حر تُضاف إلى الموجّه

---

بنية الدليل

french-formal-v1/
  method.json                 # Method manifest with benchmarks
  coaching/
    fr.json                   # Coaching data for French

للطرق متعددة اللغات المحلية:

european-formal-v2/
  method.json                 # locales: ["fr", "de", "es", "it"]
  coaching/
    fr.json
    de.json
    es.json
    it.json

---

كيف يستهلك Champollion الإضافات

التثبيت

champollion plugin install ./french-formal-v1/

يُحفظ في .champollion/methods/french-formal-v1/.

الإعداد

champollion.config.json

{
  "pairs": {
    "en:fr": {
      "methodPlugin": "french-formal-v1"
    }
  }
}

:::info Merge semantics تحدد الإضافة ما هي الطريقة المستخدمة (type). أما إعدادات الزوج فتضبط كيفية تشغيلها (model، register، batchSize). إذا عيّن الزوج model، فإنه يتجاوز القيمة الافتراضية للإضافة. :::

وقت التشغيل

1. يقرأ Champollion method.json من .champollion/methods/french-formal-v1/
2. يحدد حقل type في الإضافة طريقة الترجمة (مثل llm-coached)
3. يُحمِّل بيانات التوجيه من دليل coaching/ الخاص بالإضافة
4. يستخدم كتلة config لسد الفجوات في النموذج/المستوى اللغوي/درجة الحرارة
5. تُعرض كتلة benchmarks في مخرجات champollion status
6. يفحص champollion provenance كتلة provenance بحثًا عن أعلام الترخيص

---

التحقق من صحة المخطط

يتم التحقق من صحة بيانات الإضافات عند التثبيت وفقًا لـ shared/schemas/champollion-plugin.schema.json.

أشِر إلى المخطط في method.json الخاص بك للحصول على الإكمال التلقائي في بيئة التطوير:

{
  "$schema": "./node_modules/champollion/shared/schemas/champollion-plugin.schema.json",
  "name": "my-method-v1"
}

---

ما لا ينبغي تضمينه

• ❌ لا أكواد Python ولا اعتماديات على منصة التقييم
• ❌ لا بيانات نصوص خام ولا سجلات تشغيل
• ❌ لا مفاتيح API ولا بيانات اعتماد
• ❌ لا إعدادات منصة التقييم
• ❌ لا قوالب موجّهات داخلية (فهذه موجودة في تنفيذات الطرق الخاصة بـ champollion)

الإضافة بيانات فقط: إعدادات، ومحتوى توجيهي، ونتائج معايير قياسية.

---

انظر أيضًا

• طرق الترجمة — كيف تعمل كل طريقة مدمجة
• الإعدادات — الإعدادات لكل زوج ولكل لغة
• تقديم طريقة عبر API — استضافة الطرق كخدمات HTTP
• دليل عملي: خط أنابيب مقيَّد بـ FST — بناء خط أنابيب وتغليفه
• تقييم الترجمة الآلية — قياس الطرق معياريًا لتقديمها إلى لوحة المتصدرين
• دعم لغة منخفضة الموارد — حالة الاستخدام لإضافات المجتمع