매니페스트 참조

모든 미니 프로그램, 애드온, 플러그인은 확장 프로그램의 메타데이터, 권한, 진입점을 설명하는 manifest.json 파일이 필요합니다. 매니페스트는 Manifest v2 스키마를 따릅니다.

최소 예시

미니 프로그램을 위한 가장 간단한 유효한 매니페스트:

{
  "name": "my-app",
  "version": "1.0.0",
  "abi": 1,
  "type": "mini-program",
  "entry": "index.html",
  "base_url": "https://cdn.example.com/my-app/"
}

전체 예시

일반적으로 사용되는 모든 필드가 포함된 완전한 매니페스트:

{
  "name": "word-counter",
  "version": "1.2.0",
  "abi": 1,
  "type": "mini-program",
  "title": "Word Counter",
  "description": "Count words in your chat history by role and visualize trends",
  "icon": "https://cdn.example.com/word-counter/icon.png",
  "author": {
    "name": "Jane Developer",
    "url": "https://janedev.com"
  },
  "entry": "index.html",
  "base_url": "https://cdn.example.com/word-counter/",
  "permissions": ["storage", "chat:read", "ui:toast"],
  "keywords": ["statistics", "utility", "word-count"],
  "license": "MIT",
  "repository": "https://github.com/janedev/word-counter",
  "min_platform_version": "1.0.0"
}

필드 참조

필수 필드

`name`

고유 패키지 이름. 저장소 격리, 설치 확인, 레지스트리 조회를 위한 내부 식별자로 사용됩니다.

속성	값
타입	`string`
패턴	`^[a-z0-9-]+$` (소문자, 숫자, 하이픈만)
최대 길이	64자
필수	예

"name": "word-counter"

주의

이름은 레지스트리 내에서 전역적으로 고유해야 합니다. 설명적인 이름을 선택하세요. 게시 후에는 새 패키지 항목을 만들지 않고는 변경할 수 없습니다.

`version`

시맨틱 버전 문자열. semver 형식을 따라야 합니다.

속성	값
타입	`string`
패턴	`^\d+\.\d+\.\d+` (major.minor.patch, 선택적 프리릴리스)
필수	예

"version": "1.0.0"

레지스트리에서 앱을 업데이트할 때 매니페스트와 registry/packages.json 항목 모두에서 버전을 올리세요.

강력히 권장되는 필드

`abi`

이 매니페스트가 대상으로 하는 ABI(Application Binary Interface) 버전. 현재 플랫폼에서는 1이어야 합니다.

속성	값
타입	`integer`
상수	`1`
필수	기술적으로 선택사항이지만 강력히 권장됨

"abi": 1

플랫폼은 1이 아닌 abi 값을 가진 매니페스트를 거부합니다. 생략하면 플랫폼은 ABI 1을 가정하지만 전방 호환성을 위해 명시적 선언이 권장됩니다.

`type`

확장 프로그램 타입. 런타임 환경과 사용 가능한 기능을 결정합니다.

속성	값
타입	`string`
Enum	`"plugin"`, `"addon"`, `"mini-program"`
기본값	`"plugin"`

"type": "mini-program"

타입	런타임	UI 표면	요구사항
`plugin`	WASM (커널 슬롯 4-7)	없음 (훅만)	`wasm` + `wasm_sha256`
`addon`	WASM 또는 JS	명명된 UI 슬롯	`wasm` 또는 `entry`
`mini-program`	샌드박스 iframe (null origin)	전체 패널 (채팅 대체)	`entry` + `base_url`

`entry`

진입 HTML 파일의 경로. base_url에 상대적입니다.

속성	값
타입	`string`
필수	미니 프로그램과 HTML 애드온에 필수

"entry": "index.html"

플랫폼은 설치 시점에 {base_url}{entry}를 가져와 오프라인 사용을 위해 HTML을 캐시합니다.

`base_url`

진입 파일과 상대 에셋 경로(이미지, 스크립트, 스타일시트)를 해결하기 위한 기본 URL.

속성	값
타입	`string` (URI)
필수	미니 프로그램에 필수

"base_url": "https://cdn.example.com/word-counter/"

HTML의 상대 경로가 올바르게 해결되도록 <base href="{base_url}"> 태그가 iframe에 주입됩니다.

정보

파일 업로드에서 설치된 .ais 번들의 경우 모든 에셋이 인라인되므로 base_url은 자동으로 local://로 설정됩니다.

선택적 메타데이터 필드

`title`

앱 스토어와 권한 대화상자에 표시되는 사람이 읽을 수 있는 표시 이름. 생략하면 name이 사용됩니다.

속성	값
타입	`string`

"title": "Word Counter"

`description`

스토어 목록 및 권한 대화상자를 위한 짧은 설명.

속성	값
타입	`string`
최대 길이	256자

"description": "Count words in your chat history by role and visualize trends"

`icon`

정사각형 아이콘 이미지 URL. 권장 크기: 128x128 PNG. 앱 그리드와 스토어 목록에 표시됩니다.

속성	값
타입	`string` (URI)

"icon": "https://cdn.example.com/word-counter/icon.png"

팁

플랫폼의 다크 테마에 맞게 투명 또는 어두운 배경의 128x128 픽셀 정사각형 PNG를 사용하세요. SVG도 허용됩니다.

`author`

작성자 정보.

속성	값
타입	`object`
속성	`name` (문자열, 최대 100), `url` (문자열, URI)

"author": {
  "name": "Jane Developer",
  "url": "https://janedev.com"
}

`license`

SPDX 라이선스 식별자.

속성	값
타입	`string`

"license": "MIT"

`repository`

소스 저장소 URL.

속성	값
타입	`string` (URI)

"repository": "https://github.com/janedev/word-counter"

`keywords`

앱 스토어에서 검색 가능성을 위한 키워드.

속성	값
타입	`string[]`
최대 항목	10
키워드당 최대	32자

"keywords": ["statistics", "utility", "word-count"]

`min_platform_version`

이 확장 프로그램을 실행하는 데 필요한 최소 AISCouncil 플랫폼 버전.

속성	값
타입	`string` (semver)

"min_platform_version": "1.0.0"

권한

`permissions`

확장 프로그램이 요청하는 권한 문자열 배열. 사용자가 설치 시점에 승인해야 합니다.

속성	값
타입	`string[]`
고유 항목	예

"permissions": ["storage", "chat:read", "ui:toast"]

사용 가능한 권한

권한	설명	자동 승인?
`storage`	앱별 격리된 키-값 저장소	예 (항상 허용)
`chat:read`	채팅 기록 읽기 및 새 메시지 구독	아니오
`chat:write`	사용자로서 메시지 보내기 (AI 응답 트리거)	아니오
`config:read`	활성 봇 설정 읽기 (제공자, 모델, 시스템 프롬프트)	아니오
`config:write`	활성 봇 설정 수정	아니오
`auth:read`	사용자 정보 읽기 (이름, 이메일, 프로필 사진) 및 구독 등급	아니오
`ui:toast`	플랫폼 UI에 토스트 알림 표시	아니오
`ui:modal`	확인 대화상자 표시	아니오
`hooks:action`	훅 이벤트 등록 및 발생	아니오
`hooks:filter`	필터 훅 등록	아니오
`network:fetch`	플랫폼을 통한 프록시 네트워크 요청 (향후)	아니오
`secrets:sync`	기기 간 전송을 위한 API 키 읽기 및 쓰기	아니오
`pages:publish`	bcz.co에 웹 페이지 게시	아니오

경고

앱에 실제로 필요한 권한만 요청하세요. 추가 권한은 설치 장벽을 높입니다. 권한이 적은 앱일수록 사용자가 승인할 가능성이 높습니다.

플러그인 전용 필드

이 필드는 미니 프로그램이 아닌 플러그인과 WASM 애드온에서 사용됩니다.

`wasm`

WASM 바이너리 URL.

속성	값
타입	`string` (URI)
필수	플러그인의 경우

"wasm": "https://cdn.example.com/my-plugin/plugin.wasm"

`wasm_sha256`

무결성 검증을 위한 WASM 바이너리의 SHA-256 16진수 다이제스트.

속성	값
타입	`string`
패턴	`^[0-9a-f]{64}$`
필수	플러그인의 경우

"wasm_sha256": "a1b2c3d4e5f6..."

`segment_size`

WASM 모듈 메모리 세그먼트 크기 (바이트).

속성	값
타입	`integer`
최소	0

"segment_size": 4194304

고급 필드

`pages`

다중 페이지 미니 프로그램을 위한 추가 페이지 경로.

속성	값
타입	`string[]`

"pages": ["settings.html", "about.html"]

`hooks`

플러그인과 애드온을 위한 훅 등록. 각 훅에는 이름과 선택적 우선순위가 있습니다.

속성	값
타입	`object[]`

"hooks": [
  { "name": "chat:before-send", "priority": 50 },
  { "name": "message:filter", "priority": 100 }
]

훅 이름은 ^[a-z][a-z0-9_.:-]*$와 일치해야 하며 최대 128자여야 합니다. 우선순위는 0(가장 빠름)에서 999(가장 늦음)까지이며 기본값은 100입니다.

`settings`

플랫폼 설정 UI에 표시되는 사용자 구성 가능 설정.

속성	값
타입	`object` (키는 설정 이름, 값은 설정 정의)

"settings": {
  "theme": {
    "type": "select",
    "label": "색상 테마",
    "default": "dark",
    "options": [
      { "value": "dark", "label": "다크" },
      { "value": "light", "label": "라이트" }
    ]
  },
  "maxMessages": {
    "type": "number",
    "label": "분석할 최대 메시지 수",
    "default": 500,
    "description": "로드되는 채팅 메시지 수 제한"
  },
  "autoRefresh": {
    "type": "boolean",
    "label": "열 때 자동 새로고침",
    "default": true
  }
}

설정 타입: string, number, boolean, select.

`mcp_tools`

이 확장 프로그램이 제공하는 MCP(Model Context Protocol) 도구 선언.

속성	값
타입	`object[]`

"mcp_tools": [
  {
    "name": "count-words",
    "description": "주어진 텍스트의 단어 수 세기",
    "inputSchema": {
      "type": "object",
      "properties": {
        "text": { "type": "string" }
      },
      "required": ["text"]
    }
  }
]

타입별 요구사항

필드	플러그인	애드온	미니 프로그램
`name`	필수	필수	필수
`version`	필수	필수	필수
`type`	`"plugin"`	`"addon"`	`"mini-program"`
`wasm`	필수	`entry` 없으면 필수	사용 안 함
`wasm_sha256`	필수	`wasm` 사용 시 필수	사용 안 함
`entry`	사용 안 함	`wasm` 없으면 필수	필수
`base_url`	사용 안 함	선택	필수

검증

게시 전에 내장 검증 스크립트로 매니페스트를 확인하세요:

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

검증기는 다음을 확인합니다:

필수 필드 존재
name이 ^[a-z0-9-]+$ 패턴과 일치하고 최대 64자
version이 유효한 semver
abi가 1 (존재하는 경우)
type이 plugin, addon, mini-program 중 하나
권한이 허용된 집합에서
타입별 필수 필드 존재 (예: 미니 프로그램의 entry)
알 수 없는 필드 없음 (스키마는 additionalProperties: false로 엄격)

팁

JSON 스키마는 registry/manifest-schema.json에 게시되어 있습니다. IDE 통합이나 CI 파이프라인을 위해 모든 JSON 스키마 검증기와 함께 사용할 수 있습니다.

스키마 참조

매니페스트 스키마는 JSON Schema (Draft 2020-12)로 정의되어 있으며 다음에서 사용할 수 있습니다:

https://aiscouncil.com/schema/manifest/v2

에디터 자동완성을 위해 매니페스트에서 참조하세요:

{
  "$schema": "https://aiscouncil.com/schema/manifest/v2",
  "name": "my-app",
  "version": "1.0.0"
}

대부분의 에디터(VS Code, JetBrains 등)는 $schema 필드가 있을 때 자동완성과 검증을 제공합니다.

최소 예시​

전체 예시​

필드 참조​

필수 필드​

name​

version​

강력히 권장되는 필드​

abi​

type​

entry​

base_url​

선택적 메타데이터 필드​

title​

description​

icon​

author​

license​

repository​

keywords​

min_platform_version​

권한​

permissions​

사용 가능한 권한​

플러그인 전용 필드​

wasm​

wasm_sha256​

segment_size​

고급 필드​

pages​

hooks​

settings​

mcp_tools​

타입별 요구사항​

검증​

스키마 참조​