Method Plugin 명세

Version: 1.1
Audience: Plugin 개발자
Canonical Schema: shared/schemas/champollion-plugin.schema.json

개요

champollion은 플러그형 메서드 시스템을 사용해요. 각 언어 쌍은 서로 다른 번역 메서드(LLM, coached, script-converter 등)를 사용할 수 있어요. 메서드는 lib/translate.js에 등록되고 lib/pairs.js을 통해 쌍별로 해석돼요.

eval harness의 역할은 번역 메서드를 개발하고, 테스트하고, 내보내는 것이에요. champollion의 역할은 그것들을 소비하고 실행하는 것이에요. 플러그인은 데이터 전용이에요 — 구성, 코칭 콘텐츠, 벤치마크 결과. Python 코드도, harness 의존성도 없어요.

데이터 흐름

harness는 Python으로 메서드를 개발하고 테스트해요. 메서드가 배포 준비가 되면, harness는 method.json 매니페스트와 선택적 코칭 데이터 파일을 내보내요. Champollion은 자체 내장 메서드 구현을 사용하여 메서드를 설치하고 실행해요.

Method Plugin 형식

method plugin은 선택적 코칭 데이터 파일이 있는 단일 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"
  }
}

필드 참조

Field	Type	Required	Description
`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[]	✅	이 메서드가 대상으로 하는 locale 코드 (최소 1개)
`description`	string	—	사람이 읽을 수 있는 설명
`author`	string	—	이 메서드를 개발/테스트한 사람
`config.model`	string	—	OpenRouter 모델 식별자
`config.temperature`	number	—	LLM temperature (0.0–2.0, 기본값: 0.3)
`config.batchSize`	number	—	API 배치당 키 개수 (1–200, 기본값: 80)
`config.register`	string \| null	—	대상 언어 register/tone (preset 키 또는 자유 형식 텍스트)
`config.coachingFile`	string \| null	—	자유 텍스트 코칭 프롬프트 파일 경로 (프로젝트 루트 기준 상대 경로)
`config.coachingPrompt`	string \| null	—	해석된 코칭 프롬프트 텍스트 (런타임에 `coachingFile`에서 읽음)
`config.promptContext`	string \| null	—	시스템 프롬프트에 주입되는 애플리케이션 컨텍스트 (예: "E-commerce product descriptions")
`config.qualityTier`	string \| null	—	벤치마크 평가에서 나온 품질 등급 (`standard`, `high`, `research`, `verified`)
`benchmarks`	object	—	eval harness에서 나온 locale별 벤치마크 결과
`provenance`	object	—	라이선싱 및 리소스 의존성
`coaching.dir`	string	—	코칭 데이터 디렉터리에 대한 상대 경로

:::info Canonical MethodConfig Shape config 블록은 canonical MethodConfig 스키마를 사용해요 — champollion.config.json, harness 실행 카드, mt-eval export-config, leaderboard 게시/설치 전반에서 사용되는 동일한 8개 필드예요. 모든 필드는 항상 존재하며, 사용되지 않는 값은 null이에요. 이를 통해 평가와 프로덕션 사이의 마찰 없는 왕복이 보장돼요. :::

Benchmark 객체 (locale별)

Field	Type	Required	Description
`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	✅	eval 중 사용된 모델
`harness_version`	string	✅	사용된 평가 harness의 버전

:::info 어떤 메트릭이 표시되나요? champollion status 명령어는 benchmark 블록에서 **chrF++**와 정확 일치율을 표시해요. corpus_bleu는 매니페스트에서 허용되지만 현재 어떤 champollion 명령어에서도 표시되거나 사용되지 않아요. Method Leaderboard는 chrF++, 정확 일치, FST 수용률을 추적해요. :::

Provenance 객체

provenance 블록은 플러그인에 번들된 리소스의 라이선싱 상태를 전달해요.

Field	Type	Default	Description
`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."
}

Field	Type	Required	Description
`grammar_rules`	string[]	—	이 locale에 대한 모든 LLM 프롬프트에 주입되는 규칙
`dictionary`	object	—	용어 → 번역 맵. 일치하는 용어는 필수 용어로 주입돼요.
`style_notes`	string	—	프롬프트에 추가되는 자유 형식 스타일 지침

디렉터리 구조

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

다중 locale 메서드의 경우:

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 병합 의미 플러그인은 어떤 메서드를 사용할지 정의해요(type). 쌍 구성은 그것을 어떻게 실행할지 조정해요(model, register, batchSize). 쌍이 model를 설정하면, 플러그인의 기본값을 재정의해요. :::

런타임

Champollion은 .champollion/methods/french-formal-v1/에서 method.json를 읽어요
플러그인의 type 필드가 번역 메서드를 설정해요 (예: llm-coached)
플러그인의 coaching/ 디렉터리에서 코칭 데이터를 로드해요
config 블록을 사용하여 모델/register/temperature의 공백을 채워요
benchmarks 블록은 champollion status 출력에 표시돼요
provenance 블록은 라이선싱 플래그에 대해 champollion provenance로 확인돼요

스키마 검증

플러그인 매니페스트는 설치 시 shared/schemas/champollion-plugin.schema.json에 대해 검증돼요.

IDE 자동 완성을 위해 method.json에서 스키마를 참조하세요:

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

포함하지 말아야 할 것

❌ Python 코드나 harness 의존성 금지
❌ 원시 corpus 데이터나 실행 로그 금지
❌ API 키나 자격 증명 금지
❌ harness 구성 금지
❌ 내부 프롬프트 템플릿 금지 (그것들은 champollion의 메서드 구현 안에 있음)

플러그인은 데이터 전용이에요: 구성, 코칭 콘텐츠, 벤치마크 결과.

함께 보기

Translation Methods — 각 내장 메서드의 작동 방식
Configuration — 쌍별 및 언어별 구성
Serving a Method via API — 메서드를 HTTP 서비스로 호스팅하기
Cookbook: FST-Gated Pipeline — 파이프라인 빌드 및 패키징
MT Evaluation — leaderboard 제출을 위한 메서드 벤치마킹
Support a Low-Resource Language — 커뮤니티 플러그인의 사용 사례

개요​

데이터 흐름​

Method Plugin 형식​

method.json — 필수​

필드 참조​

Benchmark 객체 (locale별)​

Provenance 객체​

코칭 데이터 형식​

coaching/<locale>.json​

디렉터리 구조​

Champollion이 플러그인을 소비하는 방법​

설치​

구성​

런타임​

스키마 검증​

포함하지 말아야 할 것​

함께 보기​

개요