기여

AISCouncil는 모델 레지스트리, 번역, 문서, 미니 프로그램, 핵심 코드 등 여러 영역에서 기여를 환영합니다. 이 가이드는 각 기여 경로를 다룹니다.

기여 영역

영역	난이도	파일	검증
모델 레지스트리	쉬움	`registry/models.json`	`python3 registry/validate.py`
번역	쉬움	`registry/locale/{lang}.json`	`python3 registry/locale/validate_locale.py`
문서	쉬움	`doc.aiscouncil.net/site/docs/`	`npm start`로 로컬 미리보기
미니 프로그램	보통	`manifest.json` + `index.html`	`python3 registry/validate.py packages`
버그 수정 / 기능	보통-어려움	`src/.js`, `modules//index.ts`	`./build.sh && npm test`

모델 레지스트리

모델 레지스트리(registry/models.json)는 커뮤니티에서 유지 관리하는 LLM 제공자와 모델 목록입니다. 새 모델을 추가하는 것이 가장 쉬운 기여 방법입니다.

모델 추가

저장소 포크
registry/models.json 편집 -- 적절한 제공자 아래에 모델 추가
검증:

python3 registry/validate.py

풀 리퀘스트 제출

모델 항목 형식

각 모델은 다음 필드가 필요합니다:

{
  "id": "model-id-from-provider",
  "name": "Human-Readable Name",
  "provider": "provider-id",
  "context": 128000,
  "maxOutput": 8192,
  "pricing": { "input": 3.0, "output": 15.0 },
  "capabilities": ["streaming", "vision", "tools"],
  "tier": "paid"
}

검증 스크립트는 다음을 확인합니다:

유효한 JSON 구조
모든 필수 필드 존재 (id, name, provider, context, maxOutput, pricing, capabilities, tier)
중복 모델 ID 없음
허용된 집합의 기능: vision, tools, streaming, json_mode, reasoning, code
허용된 집합의 등급: free, paid, enterprise

팁

models.json의 기존 항목을 예시로 확인하세요. 깔끔한 diff를 위해 형식 스타일(2-공간 들여쓰기, 같은 순서의 필드)을 일치시키세요.

번역

앱은 국제화를 위해 커뮤니티에서 기여한 로캘 파일을 사용합니다. 각 로캘 파일은 마법사와 UI 문자열을 번역합니다.

번역 추가 또는 업데이트

registry/locale/en.json을 registry/locale/{lang}.json으로 복사 (ISO 639-1 코드 사용: es, zh, ar, fr 등)
모든 문자열 값 번역 (각 키-값 쌍의 오른쪽)
_meta.lang과 _meta.name 업데이트
검증:

python3 registry/locale/validate_locale.py registry/locale/{lang}.json

풀 리퀘스트 제출

번역 규칙

번역: 모든 문자열 값과 _meta.name
변경하지 마세요: 키 이름, _meta.lang 코드, _meta.version, {curly braces} 내부의 템플릿 변수

{name}, {count}, {error}와 같은 템플릿 변수는 런타임에 교체됩니다. 영어 소스에 나타나는 대로 정확히 유지하세요.

{
  "_meta": {
    "lang": "es",
    "name": "Espanol",
    "version": 1,
    "module": "wizard"
  },
  "createProfile": "Crear Perfil de IA",
  "operator": "Operador: {name}",
  "modelsSelected": "{count} seleccionados:"
}

정보

문자 인코딩 규칙과 우선순위 언어를 포함한 전체 번역 가이드는 registry/locale/TRANSLATING.md를 참조하세요.

현재 필요한 언어

영어, 스페인어, 중국어, 아랍어, 프랑스어, 포르투갈어, 일본어, 한국어, 독일어, 러시아어에 대한 완전한 번역이 존재합니다. 힌디어, 터키어, 우크라이나어, 태국어, 폴란드어, 이탈리아어, 네덜란드어, 인도네시아어, 베트남어에 대한 번역이 여전히 필요합니다.

문서

문서는 doc.aiscouncil.net/site/docs/의 Docusaurus 사이트에 있습니다.

문서 편집

doc.aiscouncil.net/site/docs/에서 Markdown 파일 편집 또는 생성
로컬에서 미리보기:

cd doc.aiscouncil.net/site
npm install
npm start

새 페이지를 추가하는 경우 doc.aiscouncil.net/site/sidebars.ts에 등록
풀 리퀘스트 제출

문서 규칙

sidebar_position, title, description으로 프론트매터 사용
콜아웃에 :::tip, :::info, :::warning 어드모니션 사용
구조화된 비교를 위해 표 사용
해당하는 경우 명령 예시 포함
산문을 직접적이고 간결하게 유지

미니 프로그램

미니 프로그램은 iframe을 통해 AISCouncil 플랫폼 내에서 실행되는 샌드박스 웹 앱입니다.

미니 프로그램 생성

manifest.json 생성:

{
  "name": "my-app",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "title": "My App",
  "description": "What my app does",
  "entry": "index.html",
  "base_url": "https://your-cdn.com/my-app/",
  "permissions": ["storage"]
}

window.ais SDK를 사용하여 index.html 생성:

<!DOCTYPE html>
<html>
  <body>
    <h1>내 앱</h1>
    <script>
      ais.ready(() => {
        ais.ui.toast("내 앱에서 안녕하세요!");
      });
    </script>
  </body>
</html>

모든 CDN에서 파일 호스팅 (GitHub Pages, Cloudflare Pages, Vercel)
매니페스트 URL로 설치하여 로컬에서 테스트:

AIS.MiniPrograms.install("https://your-cdn.com/my-app/manifest.json");

레지스트리에 게시

registry/packages.json에 앱 항목 추가
검증:

python3 registry/validate.py packages

풀 리퀘스트 제출

전체 미니 프로그램 API는 SDK 문서와 sdk/ais.d.ts를 참조하세요.

팁

examples/hello-world/ 디렉토리에 시작점으로 사용할 수 있는 완전한 작동 미니 프로그램이 있습니다.

코드 기여

개발 설정

git clone https://github.com/nicholasgasior/bcz.git
cd bcz
npm install
./build.sh
npm test

편집-빌드-테스트 주기

src/에서 소스 파일 편집 (index.html을 직접 편집하지 마세요)
빌드: ./build.sh
테스트: npm test
검증: ./build.sh --check

TypeScript 모듈의 경우:

편집: modules/{name}/index.ts
타입 체크: npm run check
빌드: ./build.sh (TypeScript 자동 컴파일)
테스트: npm run test:modules

코드 스타일

코드베이스는 엄격한 규칙을 따릅니다. 코드를 제출하기 전에 검토하세요:

외부 의존성 없음. 브라우저 번들은 바닐라 JS와 선택적 WASM만 포함합니다. 런타임에 React 없음, jQuery 없음, lodash 없음, npm 패키지 없음.

시맨틱 HTML. 모달에 <dialog>, 접이식에 <details>, 라이브 영역에 <output>, 가시성에 hidden 속성을 사용하세요. JS를 작성하기 전에 네이티브 HTML 요소를 찾으세요.

클래스 없는 CSS. ID, 시맨틱 태그, 또는 data-* 속성으로 요소를 대상으로 하세요. 클래스는 다음에만 사용: 상태 토글(.active, .collapsed), 동적 JS 컴포넌트(.council-member-row), 유틸리티 약어(.f1, .sc).

/* 좋음: 시맨틱 선택자 */
#messages > article[data-from="user"] { ... }
article menu button { ... }

/* 피하기: 클래스 중심 선택자 */
.message-container .message--user .message__actions .btn { ... }

14px 최소 폰트 크기. 모든 텍스트는 최소 14px여야 합니다. 이것은 UI와 상호작용하는 비전 LLM의 가독성을 보장합니다.

VLM 친화적 클릭 타겟. 인터랙티브 요소는 높이가 최소 48px여야 합니다. 토글 스위치는 44x24px입니다. 이것은 AI 비전 모델이 좌표로 요소를 클릭할 수 있게 합니다.

새 모듈에 AIS.lazy(). 모든 비코어 모듈은 지연 하이드레이션 패턴을 사용해야 합니다. 팩토리 함수는 첫 번째 접근 시에만 실행됩니다:

if (!AIS.MyModule)
  AIS.lazy("MyModule", function () {
    "use strict";
    // 모듈 코드
    return { publicMethod };
  });

이벤트 위임. 컨테이너 요소에 단일 리스너를 연결하세요. 각 자식에 개별 리스너가 아닙니다:

// 좋음: 위임으로 단일 리스너
container.addEventListener("click", (e) => {
  const btn = e.target.closest("[data-action]");
  if (btn) handleAction(btn.dataset.action);
});

// 피하기: 항목별 리스너
items.forEach((item) => item.addEventListener("click", handler));

제로 폴링. 비애니메이션 작업을 위한 setInterval, requestAnimationFrame 루프 없음. 이벤트 기반 업데이트와 Page Visibility API를 사용하세요.

수동 리스너. 모든 취소 불가능한 이벤트 핸들러는 { passive: true }를 사용합니다:

window.addEventListener("resize", onResize, { passive: true });

Worker 테스트

Worker 코드는 자체 테스트 스위트가 있습니다:

cd worker
npm install
npm test

Python 도구

Python은 검증과 빌드 스크립트에만 사용됩니다. 브라우저로 전송되지 않습니다:

# 모델 레지스트리 검증
python3 registry/validate.py

# 패키지 레지스트리 검증
python3 registry/validate.py packages

# 매니페스트 파일 검증
python3 registry/validate.py manifest path/to/manifest.json

# 로캘 파일 검증
python3 registry/locale/validate_locale.py registry/locale/es.json

풀 리퀘스트 프로세스

저장소 포크
변경을 위한 브랜치 생성 (예: add-model-deepseek-v3, translate-hindi, fix-streaming-bug)
위의 규칙에 따라 변경
검증과 테스트 실행:

# 레지스트리 변경의 경우
python3 registry/validate.py

# 코드 변경의 경우
./build.sh
npm test
./build.sh --check

# 로캘 변경의 경우
python3 registry/locale/validate_locale.py registry/locale/{lang}.json

무엇이 변경되었고 왜 변경되었는지 명확한 설명과 함께 main 브랜치로 PR 제출

정보

레지스트리 전용 변경(모델, 패키지, 번역)은 빌드하거나 전체 테스트 스위트를 실행할 필요가 없습니다. 관련 검증 스크립트만 실행하면 됩니다.

도움 받기

버그나 기능 요청을 위해 GitHub 이슈 열기
doc.aiscouncil.net에서 기존 문서 확인
전체 아키텍처 참조는 저장소 루트의 CLAUDE.md 검토

기여 영역​

모델 레지스트리​

모델 추가​

모델 항목 형식​

번역​

번역 추가 또는 업데이트​

번역 규칙​

현재 필요한 언어​

문서​

문서 편집​

문서 규칙​

미니 프로그램​

미니 프로그램 생성​

레지스트리에 게시​

코드 기여​

개발 설정​

편집-빌드-테스트 주기​

코드 스타일​

Worker 테스트​

Python 도구​

풀 리퀘스트 프로세스​

도움 받기​