Method-Plugin-Spezifikation

Version: 1.1
Zielgruppe: Plugin-Entwickler
Kanonisches Schema: shared/schemas/champollion-plugin.schema.json

Überblick

champollion verwendet ein steckbares Methodensystem. Jedes Sprachpaar kann eine andere Übersetzungsmethode verwenden (LLM, coached, script-converter usw.). Methoden werden in lib/translate.js registriert und pro Paar über lib/pairs.js aufgelöst.

Die Aufgabe des Eval-Harness ist es, Übersetzungsmethoden zu entwickeln, zu testen und zu exportieren. Die Aufgabe von champollion ist es, sie zu konsumieren und auszuführen. Das Plugin enthält nur Daten — Konfiguration, Coaching-Inhalte und Benchmark-Ergebnisse. Kein Python-Code, keine Harness-Abhängigkeiten.

Datenfluss

Der Harness entwickelt und testet Methoden in Python. Wenn eine Methode für den Einsatz bereit ist, exportiert der Harness ein method.json-Manifest sowie optionale Coaching-Datendateien. Champollion installiert und führt die Methode mithilfe seiner eigenen integrierten Methodenimplementierungen aus.

Method-Plugin-Format

Ein Method-Plugin ist eine einzelne JSON-Datei (method.json) mit optionalen Coaching-Datendateien.

`method.json` — Erforderlich

{
  "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"
  }
}

Feldreferenz

Feld	Typ	Erforderlich	Beschreibung
`name`	string	✅	Eindeutige Methodenkennung (kebab-case)
`type`	string	✅	Champollion-Methodentyp: `llm`, `llm-coached`, `api`, `google-translate`, `deepl`, `microsoft-translator`, `libretranslate`, `openai`, `anthropic`, `gemini`
`version`	string	✅	Semver-Version (z. B. `1.0.0`)
`locales`	string[]	✅	Welche Locale-Codes diese Methode adressiert (mindestens 1)
`description`	string	—	Menschenlesbare Beschreibung
`author`	string	—	Wer diese Methode entwickelt/getestet hat
`config.model`	string	—	OpenRouter-Modellkennung
`config.temperature`	number	—	LLM-Temperatur (0.0–2.0, Standard: 0.3)
`config.batchSize`	number	—	Schlüssel pro API-Batch (1–200, Standard: 80)
`config.register`	string \| null	—	Register/Tonalität der Zielsprache (Preset-Schlüssel oder Freitext)
`config.coachingFile`	string \| null	—	Pfad zur Freitext-Coaching-Prompt-Datei (relativ zum Projektstamm)
`config.coachingPrompt`	string \| null	—	Aufgelöster Coaching-Prompt-Text (zur Laufzeit aus `coachingFile` gelesen)
`config.promptContext`	string \| null	—	In den System-Prompt eingefügter Anwendungskontext (z. B. „E-Commerce-Produktbeschreibungen")
`config.qualityTier`	string \| null	—	Qualitätsstufe aus der Benchmark-Bewertung (`standard`, `high`, `research`, `verified`)
`benchmarks`	object	—	Locale-spezifische Benchmark-Ergebnisse aus dem Eval-Harness
`provenance`	object	—	Lizenzierungs- und Ressourcenabhängigkeiten
`coaching.dir`	string	—	Relativer Pfad zum Coaching-Datenverzeichnis

:::info Kanonische MethodConfig-Struktur Der config-Block verwendet das kanonische MethodConfig-Schema — dieselben 8 Felder, die über champollion.config.json, Harness-Run-Cards, mt-eval export-config sowie Leaderboard-Publish/Install hinweg genutzt werden. Alle Felder sind stets vorhanden; nicht verwendete Werte sind null. Dies ermöglicht ein reibungsloses Hin- und Herübertragen zwischen Bewertung und Produktion. :::

Benchmark-Objekt (pro Locale)

Feld	Typ	Erforderlich	Beschreibung
`date`	string	✅	ISO-8601-Zeitstempel des Benchmark-Laufs
`corpus_size`	number	✅	Anzahl der bewerteten Einträge
`exact_match_rate`	number	✅	0.0–1.0, Anteil exakter Übereinstimmungen
`corpus_chrf`	number	—	chrF++-Wert (0–100)
`corpus_bleu`	number	—	BLEU-Wert (0–100)
`model`	string	✅	Während der Bewertung verwendetes Modell
`harness_version`	string	✅	Verwendete Version des Bewertungs-Harness

:::info Welche Metriken werden angezeigt? Der Befehl champollion status zeigt chrF++ und die Rate exakter Übereinstimmungen aus dem Benchmark-Block an. corpus_bleu wird im Manifest akzeptiert, wird derzeit jedoch von keinem champollion-Befehl angezeigt oder verwendet. Das Method Leaderboard erfasst chrF++, exakte Übereinstimmungen und die FST-Akzeptanzrate. :::

Provenance-Objekt

Der Provenance-Block kommuniziert den Lizenzierungsstatus der im Plugin gebündelten Ressourcen.

Feld	Typ	Standard	Beschreibung
`resources`	object[]	`[]`	Liste der gebündelten Ressourcen mit `name`, `license` und `type`
`commercialReady`	boolean	`false`	Ob das Plugin für die kommerzielle Distribution freigegeben ist
`flags`	string[]	`["license-unclear"]`	Maschinenlesbare Status-Flags

Standardzustand — exportierte Plugins werden mit commercialReady: false und flags: ["license-unclear"] ausgeliefert.

Freigegebener Zustand — wenn die Lizenzierung verifiziert wurde: Setzen Sie commercialReady: true und entfernen Sie die Flags.

Coaching-Datenformat

Wenn type den Wert llm-coached hat, sollte das Plugin Coaching-Datendateien im Unterverzeichnis coaching/ enthalten.

`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."
}

Feld	Typ	Erforderlich	Beschreibung
`grammar_rules`	string[]	—	Regeln, die in jeden LLM-Prompt für diese Locale eingefügt werden
`dictionary`	object	—	Term → Übersetzung-Zuordnung. Übereinstimmende Terme werden als erforderliche Terminologie eingefügt.
`style_notes`	string	—	Freitext-Stilanweisungen, die an den Prompt angehängt werden

Verzeichnisstruktur

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

Für Methoden mit mehreren Locales:

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

Wie Champollion Plugins konsumiert

Installation

champollion plugin install ./french-formal-v1/

Speichert in .champollion/methods/french-formal-v1/.

Konfiguration

champollion.config.json
{
  "pairs": {
    "en:fr": {
      "methodPlugin": "french-formal-v1"
    }
  }
}

:::info Merge-Semantik Das Plugin definiert, welche Methode verwendet wird (type). Die Paar-Konfiguration steuert, wie sie ausgeführt wird (model, register, batchSize). Wenn das Paar model setzt, überschreibt dies den Standardwert des Plugins. :::

Laufzeit

Champollion liest method.json aus .champollion/methods/french-formal-v1/
Das Feld type des Plugins legt die Übersetzungsmethode fest (z. B. llm-coached)
Lädt Coaching-Daten aus dem Verzeichnis coaching/ des Plugins
Verwendet den Block config, um Lücken bei Modell/Register/Temperatur zu füllen
Der Block benchmarks wird in der Ausgabe von champollion status angezeigt
Der Block provenance wird von champollion provenance auf Lizenzierungs-Flags geprüft

Schema-Validierung

Plugin-Manifeste werden zur Installationszeit gegen shared/schemas/champollion-plugin.schema.json validiert.

Referenzieren Sie das Schema in Ihrer method.json für die IDE-Autovervollständigung:

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

Was NICHT enthalten sein sollte

❌ Kein Python-Code und keine Harness-Abhängigkeiten
❌ Keine Roh-Korpusdaten oder Run-Logs
❌ Keine API-Schlüssel oder Anmeldedaten
❌ Keine Harness-Konfiguration
❌ Keine internen Prompt-Vorlagen (diese befinden sich in den Methodenimplementierungen von champollion)

Das Plugin enthält nur Daten: Konfiguration, Coaching-Inhalte und Benchmark-Ergebnisse.

Siehe auch

Translation Methods — wie jede integrierte Methode funktioniert
Configuration — Konfiguration pro Paar und pro Sprache
Serving a Method via API — Hosting von Methoden als HTTP-Dienste
Cookbook: FST-Gated Pipeline — Erstellen und Verpacken einer Pipeline
MT Evaluation — Benchmarking von Methoden für die Leaderboard-Einreichung
Support a Low-Resource Language — der Anwendungsfall für Community-Plugins

Überblick​

Datenfluss​

Method-Plugin-Format​

method.json — Erforderlich​

Feldreferenz​

Benchmark-Objekt (pro Locale)​

Provenance-Objekt​

Coaching-Datenformat​

coaching/<locale>.json​

Verzeichnisstruktur​

Wie Champollion Plugins konsumiert​

Installation​

Konfiguration​

Laufzeit​

Schema-Validierung​

Was NICHT enthalten sein sollte​

Siehe auch​