HTML을 쓸 줄 알면, 플러그인도 쓸 줄 아는 것.
플러그인은 본질적으로 웹페이지(HTML / CSS / JS)입니다. 페이지를 작성한 뒤 CosmosBox 안의 플러그인 패키저로 .cbplugin 파일에 원클릭 패키징하면, 누구에게 보내도 설치해서 실행할 수 있습니다.
더 빠른 길: AI 원클릭 생성 — AI 채팅에서 요구사항을 말하면("전자 목어를 만들어 줘"), AI가 설치 가능한 플러그인을 바로 만들어냅니다.
플러그인은 단일 파일이어도, 여러 파일의 디렉터리여도 됩니다(.cbplugin은 본질적으로 zip 패키지):
my-plugin/
├── manifest.json // 플러그인 매니페스트(필수)
├── index.html // 엔트리 페이지(entry가 이것을 가리킴)
├── style.css // 선택 리소스
└── app.js // 선택 스크립트{
"pluginId": "a3f8c1d2-9b4e-4f6a-8c5d-1e2f3a4b5c6d", // UUID v4 고유 ID(패키저가 자동 생성 권장)
"id": "mobi.reader", // 구식 짧은 ID(호환용)
"name": "MOBI Reader",
"version": "1.2.0",
"author": "YuzhouHe",
"description": "MOBI / AZW3 전자책 읽기",
"icon": "📖", // 이모지 / 이미지 URL / Base64
"entry": "index.html",
"permissions": ["file.read", "storage"],
"fileTypes": ["mobi", "azw3"] // 파일 라우팅: 종류별 자동 열기
}| 필드 | 필수 | 설명 |
|---|---|---|
pluginId | ✓ | UUID v4 고유 ID, 시스템 레벨 충돌 방지; 패키저가 자동 생성하게 권장 |
id | — | 구식 짧은 ID(예: mobi.reader). 새 플러그인은 생략 권장, 호환 전용 |
name | ✓ | 플러그인 표시 이름 |
version | ✓ | 시맨틱 버전, 예: 1.2.0 |
author | — | 작성자 이름 |
description | — | 한 줄 기능 설명, 플러그인 마켓에서 표시 |
icon | — | 이모지, 이미지 URL 또는 Base64 이미지 |
entry | ✓ | 엔트리 파일 상대 경로(보통 index.html) |
permissions | ✓ | 권한 선언(예: file.read / storage), 권한 센터에서 개별 부여 |
fileTypes | — | 선언된 파일 확장자 목록, 파일 라우팅에 연결(외부에서 자동 열기) |
.cbplugin; 유료/비공개 → .encplugin(AES 암호화 + 비밀번호 이중 확인으로 오입력 방지)pack_plugins.ps1 스크립트를 제공합니다. 플러그인을 수정한 뒤 한 번 실행하면 모든 .cbplugin을 재생성합니다(.git / node_modules / build 디렉터리 자동 제외)..cbplugin | .encplugin | |
|---|---|---|
| 용도 | 공개 공유 | 유료 / 비공개 배포 |
| 내용 | 평문 zip | AES 암호화 |
| 가져오기 | 바로 설치 | 비밀번호 입력(외부에서 열면 자동 다이얼로그) |
⚠️ 암호화 플러그인의 비밀번호는 복구할 수 없습니다 — 잊어버리면 플러그인은 영원히 복호화할 수 없습니다. 잘 보관하세요.
플러그인은 샌드박스 WebView에서 실행됩니다 — 개방과 안전을 동시에:
| 메커니즘 | 설명 |
|---|---|
| CSP 보안 헤더 주입 | meta 태그 + HTTP 헤더 이중 경로, 외부 스크립트 로딩 제한 |
| eval / Function 비활성화 | Object.defineProperty 완전 커버, 동적 코드 실행 금지 |
| 네트워크 제한 | 플러그인 네트워크 요청 60회/분 제한, 악용 방지 |
| 경로 격리 | 플러그인은 자신의 샌드박스 디렉터리만 읽기/쓰기 가능(경로 탐색 방지) |
| 권한 센터 | permissions 선언 + 개별 부여, 모든 행동 감사 가능 |
| JS 브리지 | 브리지 API로 네이티브 기능 호출(저장 / 클립보드 / 파일 등), 기본 라이브러리는 호스트가 자동 주입 |
플러그인 ID는 UUID v4(122비트 랜덤 엔트로피)를 사용 — 충돌 확률은 무시할 수 있는 수준이라, 사용자 측 ID가 중복돼도 서로 덮어쓰거나 잘못 삭제되지 않습니다. 패키저가 자동 생성하게 하는 것을 권장합니다. 수동 지정 시 전체 UUID 형식(8-4-4-4-12)으로 — 패키저가 형식 검증을 합니다.
CosmosBox의 AI 채팅에서 바로 요구사항을 말하세요:
사용자 → 전자 목어를 만들어 줘. 누르면 소리와 애니메이션 포함
AI → ✅ 플러그인 「전자 목어」 생성 완료 — 원클릭 설치·실행 가능AI 생성 플러그인에는 기본 라이브러리가 자동 주입되고(저장 / 클립보드 / 다크 모드 대응), 생성 후 바로 플러그인 센터에서 설치할 수 있습니다. 마음에 안 들면 편집 페이지에서 AI에게 계속 수정하라고 하면 됩니다.