ข้อกำหนด Method Plugin

เวอร์ชัน: 1.1 กลุ่มเป้าหมาย: นักพัฒนา Plugin Canonical Schema: shared/schemas/champollion-plugin.schema.json

ภาพรวม

champollion ใช้ ระบบ method แบบ pluggable แต่ละคู่ภาษาสามารถใช้ translation method ที่แตกต่างกันได้ (LLM, coached, script-converter ฯลฯ) Method ต่างๆ ถูกลงทะเบียนไว้ใน lib/translate.js และถูก resolve ต่อคู่ภาษาผ่าน lib/pairs.js

หน้าที่ของ eval harness คือ พัฒนา ทดสอบ และ export translation method ส่วนหน้าที่ของ champollion คือ นำไปใช้และประมวลผล Plugin เป็น ข้อมูลเท่านั้น — ได้แก่ configuration, coaching content, และผลลัพธ์ benchmark ไม่มี Python code และไม่มี harness dependencies

Data Flow

Harness พัฒนาและทดสอบ method ใน Python เมื่อ method พร้อมสำหรับการ deploy แล้ว harness จะ export manifest method.json และไฟล์ coaching data เสริม (ถ้ามี) Champollion ติดตั้งและประมวลผล method โดยใช้ built-in method implementations ของตัวเอง

---

รูปแบบ Method Plugin

Method plugin คือไฟล์ JSON ไฟล์เดียว (method.json) พร้อมไฟล์ coaching data เสริม (ถ้ามี)

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

อ้างอิง Field

Field	ประเภท	จำเป็น	คำอธิบาย
name	string	✅	ตัวระบุ method ที่ไม่ซ้ำกัน (kebab-case)
type	string	✅	ประเภท method ของ Champollion: llm, llm-coached, api, google-translate, deepl, microsoft-translator, libretranslate, openai, anthropic, gemini
version	string	✅	เวอร์ชัน Semver (เช่น 1.0.0)
locales	string[]	✅	รหัส locale ที่ method นี้รองรับ (อย่างน้อย 1 รายการ)
description	string	—	คำอธิบายที่มนุษย์อ่านได้
author	string	—	ผู้พัฒนา/ทดสอบ method นี้
config.model	string	—	ตัวระบุ model ของ OpenRouter
config.temperature	number	—	ค่า temperature ของ LLM (0.0–2.0, ค่าเริ่มต้น: 0.3)
config.batchSize	number	—	จำนวน key ต่อ API batch (1–200, ค่าเริ่มต้น: 80)
config.register	string | null	—	ระดับภาษา/โทนของภาษาเป้าหมาย (preset key หรือข้อความอิสระ)
config.coachingFile	string | null	—	path ไปยังไฟล์ coaching prompt แบบข้อความอิสระ (relative จาก project root)
config.coachingPrompt	string | null	—	ข้อความ coaching prompt ที่ถูก resolve แล้ว (อ่านจาก coachingFile ขณะ runtime)
config.promptContext	string | null	—	บริบทของแอปพลิเคชันที่ inject เข้า system prompt (เช่น "E-commerce product descriptions")
config.qualityTier	string | null	—	ระดับคุณภาพจากการประเมิน benchmark (standard, high, research, verified)
benchmarks	object	—	ผลลัพธ์ benchmark ต่อ locale จาก eval harness
provenance	object	—	ข้อมูลสิทธิ์การใช้งานและ resource dependencies
coaching.dir	string	—	relative path ไปยังไดเรกทอรี coaching data

:::info รูปแบบ Canonical MethodConfig บล็อก config ใช้ canonical MethodConfig schema — ชุด field เดียวกัน 8 field ที่ใช้ใน champollion.config.json, harness run cards, mt-eval export-config, และการ publish/install บน leaderboard ทุก field มีอยู่เสมอ ค่าที่ไม่ได้ใช้จะเป็น null ซึ่งช่วยให้การ round-trip ระหว่างการประเมินและ production เป็นไปอย่างราบรื่น :::

Benchmark Object (ต่อ locale)

Field	ประเภท	จำเป็น	คำอธิบาย
date	string	✅	timestamp รูปแบบ ISO 8601 ของการรัน benchmark
corpus_size	number	✅	จำนวน entry ที่ประเมิน
exact_match_rate	number	✅	0.0–1.0 สัดส่วนของ exact match
corpus_chrf	number	—	คะแนน chrF++ (0–100)
corpus_bleu	number	—	คะแนน BLEU (0–100)
model	string	✅	Model ที่ใช้ระหว่างการประเมิน
harness_version	string	✅	เวอร์ชันของ evaluation harness ที่ใช้

:::info metric ใดที่แสดงผล? คำสั่ง champollion status แสดง chrF++ และ exact match rate จากบล็อก benchmark corpus_bleu ได้รับการยอมรับใน manifest แต่ปัจจุบันยังไม่ถูกแสดงหรือใช้งานโดยคำสั่ง champollion ใดๆ Method Leaderboard ติดตาม chrF++, exact match, และ FST acceptance rate :::

---

Provenance Object

บล็อก provenance สื่อสารสถานะสิทธิ์การใช้งานของ resource ที่รวมอยู่ใน plugin

Field	ประเภท	ค่าเริ่มต้น	คำอธิบาย
resources	object[]	[]	รายการ resource ที่รวมอยู่ พร้อม name, license, และ type
commercialReady	boolean	false	plugin ได้รับการอนุมัติสำหรับการเผยแพร่เชิงพาณิชย์หรือไม่
flags	string[]	["license-unclear"]	flag สถานะที่เครื่องอ่านได้

สถานะเริ่มต้น — plugin ที่ export มาจะมาพร้อมกับ commercialReady: false และ flags: ["license-unclear"]

สถานะที่ได้รับการอนุมัติ — เมื่อตรวจสอบสิทธิ์การใช้งานแล้ว: ตั้งค่า commercialReady: true และล้าง flag ออก

---

รูปแบบ Coaching Data

หาก type เป็น llm-coached plugin ควรรวมไฟล์ coaching data ไว้ในไดเรกทอรีย่อย 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."
}

Field	ประเภท	จำเป็น	คำอธิบาย
grammar_rules	string[]	—	กฎที่ inject เข้า LLM prompt ทุกรายการสำหรับ locale นี้
dictionary	object	—	แผนที่ term → การแปล term ที่ตรงกันจะถูก inject เป็น required terminology
style_notes	string	—	คำแนะนำด้านสไตล์แบบอิสระที่ต่อท้าย prompt

---

โครงสร้างไดเรกทอรี

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

สำหรับ method ที่รองรับหลาย locale:

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

---

วิธีที่ Champollion ใช้งาน Plugin

การติดตั้ง

champollion plugin install ./french-formal-v1/

บันทึกไปยัง .champollion/methods/french-formal-v1/

การกำหนดค่า

champollion.config.json

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

:::info Merge semantics Plugin กำหนด method ที่จะใช้ (type) ส่วน pair config ปรับแต่ง วิธีการรัน (model, register, batchSize) หาก pair ตั้งค่า model ค่านั้นจะ override ค่าเริ่มต้นของ plugin :::

Runtime

1. Champollion อ่าน method.json จาก .champollion/methods/french-formal-v1/
2. Field type ของ plugin กำหนด translation method (เช่น llm-coached)
3. โหลด coaching data จากไดเรกทอรี coaching/ ของ plugin
4. ใช้บล็อก config เพื่อเติมค่าที่ขาดหายไปสำหรับ model/register/temperature
5. บล็อก benchmarks จะแสดงในผลลัพธ์ของ champollion status
6. บล็อก provenance จะถูกตรวจสอบโดย champollion provenance สำหรับ licensing flag

---

Schema Validation

Plugin manifest จะถูกตรวจสอบความถูกต้องขณะติดตั้งโดยเทียบกับ shared/schemas/champollion-plugin.schema.json

อ้างอิง schema ใน method.json ของคุณเพื่อเปิดใช้งาน IDE autocompletion:

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

---

สิ่งที่ไม่ควรรวมไว้

• ❌ ไม่มี Python code หรือ harness dependencies
• ❌ ไม่มีข้อมูล corpus ดิบหรือ run log
• ❌ ไม่มี API key หรือ credentials
• ❌ ไม่มี harness configuration
• ❌ ไม่มี internal prompt template (สิ่งเหล่านั้นอยู่ใน method implementations ของ champollion)

Plugin เป็น ข้อมูลเท่านั้น: configuration, coaching content, และผลลัพธ์ benchmark

---

ดูเพิ่มเติม

• Translation Methods — วิธีการทำงานของแต่ละ built-in method
• Configuration — การกำหนดค่าต่อคู่ภาษาและต่อภาษา
• Serving a Method via API — การ host method เป็น HTTP service
• Cookbook: FST-Gated Pipeline — การสร้างและ package pipeline
• MT Evaluation — การ benchmark method สำหรับการส่งเข้า leaderboard
• Support a Low-Resource Language — กรณีการใช้งานสำหรับ community plugin