패키지
앱은 앱임을 표시하는 manifest.json과 페이지가 담긴 ui/ 폴더를 가진 직원 패키지입니다.
<data>/user/agents/deal-board/
├── manifest.json # marks the employee as an app
├── AGENT.md # the employee behind the page
├── agent.json # optional: sidecar tools, workflows
└── ui/
├── index.html
└── app.js {
"id": "<minted UUID>",
"name": "deal-board",
"version": "1.0.0",
"type": "app",
"window": { "title": "Deal Board", "width": 900, "height": 700, "resizable": true },
"permissions": ["storage:readwrite"]
} | 필드 | 의미 |
|---|---|
type | "app". 직원을 앱으로 만듭니다. Nebo는 예전의 artifact_type도 읽습니다. |
id | 앱을 만들 때 발급되는 UUID. 페이지는 /apps/<id>/ui/에서 제공됩니다. |
name, version | 직원의 이름과 패키지 버전. |
window | title, width, height, resizable, fullscreen, orientation. 기본값: 1024 × 768, 크기 조절 가능, 전체 화면 아님, 세로 방향, 직원 이름을 제목으로 사용. |
permissions | 페이지가 할 수 있는 일. 기본값 ["storage:readwrite"]. |
권한
| 권한 | 허용 범위 |
|---|---|
storage:readwrite | 앱의 키-값 저장소. |
subagent:<employee-id> | 페이지에서 다른 직원에게 묻기. 앱 자신의 직원에게는 권한이 필요 없습니다. |
network:<host> 또는 network:* | Nebo의 프록시를 거쳐 외부 호스트로 보내는 요청. |
device:motion | 이 페이지에서만 쓰는 자이로스코프와 가속도계. iPhone에서는 페이지가 탭 동작에서 DeviceMotionEvent.requestPermission()도 호출합니다. |
모든 권한은 prefix:scope 형식입니다. 앱에 필요한 최소한만 요청하세요.
전체 화면, 방향, 기울기
게임과 영상은 화면 전체를 쓸 수 있습니다. fullscreen을 설정하고, 모바일 앱용으로 orientation을 지정하세요: portrait(기본값), landscape 또는 any. 그 밖의 방향은 매니페스트를 작성할 때 거부됩니다.
{
"type": "app",
"permissions": ["storage:readwrite", "device:motion"],
"window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
} - 데스크톱에서는 앱이 전체 화면 창으로 열립니다.
- 모바일 앱에서는 앱 바가 없고, 시스템 바가 숨겨지며, 화면이 꺼지지 않고, 당겨서 새로고침이 꺼집니다. 왼쪽 위 모서리에 작은 닫기 버튼이 있다가 몇 초 후 사라지며, 위쪽 근처를 터치하면 다시 나타납니다. iOS의 가장자리 스와이프는 꺼지고, Android의 뒤로 버튼은 페이지 기록을 거슬러 올라간 뒤 앱을 닫습니다.
env(safe-area-inset-*)와viewport-fit=cover로 페이지에 여백을 주고, 왼쪽 위 모서리에는 컨트롤을 두지 마세요.
음성 컨트롤
Nebo 데스크톱 앱이나 모바일 앱에서 연 모든 앱의 오른쪽 아래 모서리에는 작은 음성 컨트롤이 표시되어, 소유자가 페이지에서 작업 중인 앱 직원과 대화할 수 있습니다. 이 컨트롤은 페이지 바깥에 있으므로 페이지를 새로고침해도 통화가 끊기지 않습니다.
- 데스크톱에서는 약 300 × 48픽셀 크기의 바로, 창의 오른쪽 아래 모서리에서 16픽셀 안쪽에 있습니다.
- 모바일 앱에서는 안전 영역 안의 48포인트 원형 버튼이며, 소유자가 양쪽 어디로든 끌어 옮길 수 있습니다. 전체 화면 앱에서는 통화가 시작되고 몇 초 후 다시 이 버튼으로 접힙니다.
- 중요한 컨트롤은 오른쪽 아래 모서리에 두지 마세요.
- 통화 중 긴 작업을 할 때 직원은 “지금 편집 중입니다.” 같은 짧은 진행 상황만 말하며, 파일 이름이나 명령을 소리 내어 읽지 않습니다.
앱 만들기
직원은 두 가지 방법으로 앱을 만들 수 있으며, 소유자의 말에 따라 방법을 고릅니다. “주문 관리용 앱을 만들어 줘”라고 하면 새 앱 직원을 만듭니다. “네가 앱이 되어 줘” 또는 “직접 게임이 되어 봐”라고 하면 소유자가 대화 중인 직원 자신이 앱이 됩니다. 채팅, 메모리, 페르소나는 그대로 유지되고, 소유자가 대화하는 동안 페이지가 다시 로드됩니다. 대화 중에 채용한 직원에게도 똑같이 작동합니다. 소유자가 어느 쪽을 뜻하는지 분명하지 않으면 직원이 한 번 묻습니다.
update_employee(
name: "<the employee's own name>",
app: { window: { title: "Solitaire", fullscreen: true, orientation: "landscape" } },
ui: { "index.html": "<!doctype html>..." }
) 트래커, 양식, 작은 대시보드 같은 일상적인 도구는 Nebo에 내장된 앱 스킬로 만듭니다. 영화 같은 랜딩 페이지, 스크롤로 진행되는 영상, 생성 아트, 게임처럼 생성된 느낌이 아니라 디자인된 느낌이어야 하는 페이지는 마켓플레이스의 App Studio 스킬로 만듭니다.
새 앱을 만드는 가장 간단한 방법은 직원에게 부탁하는 것입니다. Nebo에는 앱 제작용 내장 스킬이 있으며, 직원은 create_employee를 사용해 폴더, 매니페스트, 페르소나, 페이지를 한 번의 호출로 작성합니다. 앱은 몇 초 안에 소유자의 인력 화면에 나타납니다.
create_employee(
name: "deal-board",
description: "A board of open deals, sorted by close date.",
app: {
window: { title: "Deal Board", width: 900, height: 700, resizable: true },
permissions: ["storage:readwrite"]
},
ui: { "index.html": "<!doctype html>..." }
) update_employee는 같은 ui, app, agent_md 인수를 받습니다. ui의 경로 하나는 해당 파일 하나를 교체합니다. 페이지는 요청마다 디스크에서 읽히므로 창을 새로고침하면 변경 사항이 보입니다.
최소 페이지
이 페이지는 SDK를 로드하고, 자신의 직원이 누구인지 묻고, 그 답을 출력합니다. 직원의 id와 이름이 표시되면 연결이 제대로 된 것입니다.
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>Deal Board</title>
</head>
<body>
<h1>Deal Board</h1>
<pre id="who">loading...</pre>
<script src="/sdk/nebo.global.js"></script>
<script>
NeboAppSDK.nebo.identity.get()
.then(me => { document.getElementById('who').textContent = JSON.stringify(me, null, 2); })
.catch(err => { document.getElementById('who').textContent = String(err); });
</script>
</body>
</html> SDK는 페이지 주소에서 앱 id를 찾습니다. 다른 곳에서 제공되는 페이지에는 <meta name="nebo-app-id" content="<id>">가 필요합니다. 상태는 페이지가 아니라 앱의 storage에 보관하세요. 창은 닫히지만 storage는 남습니다.
페이지가 제공되는 방식
- Nebo는
ui/를/apps/<id>/ui/에서 제공하고 자체 창으로 엽니다. - 일치하는 파일이 없는 경로는
index.html로 대체되므로 클라이언트 측 라우팅이 작동합니다. - HTML 페이지에는
nebo-app-id와nebo-base-url메타 태그가 붙습니다. - 모든 파일은 영상, 소리, 글꼴,
wasm, 3D 모델(glb,gltf)을 포함해 실제 콘텐츠 유형으로 전송됩니다. 확장자를 알 수 없는 파일은application/octet-stream으로 전송되며 브라우저가 사용하지 않습니다. - 파일은 범위 요청에 응답하므로(
206, 범위가 끝을 넘으면416) 동영상과 소리를 원하는 위치로 이동할 수 있습니다. 모바일 앱에서는 동영상이 탭하지 않아도 그 자리에서 재생됩니다.<video muted playsinline autoplay loop poster="assets/hero.jpg" src="assets/hero.mp4"></video> main-0a8ksftt.js처럼 이름에 콘텐츠 해시가 들어간 파일은 1년 동안 캐시됩니다.index.html을 포함한 나머지는 열 때마다 확인하며, 바뀌지 않았으면304로 응답합니다. 파일 이름을 손으로 바꾸지 말고 해시 이름으로 빌드하세요.- 페이지 파일 하나는 최대 10 MB입니다.
- 폴더를 삭제하면 직원이 비활성화되고,
delete_employee는 직원을 완전히 제거합니다.
사이드카 추가하기
페이지에 서버 로직, 자체 데이터, 또는 직원이 호출할 수 있는 도구가 필요하면 사이드카를 추가하세요. Nebo가 앱 옆에서 실행하는 바이너리입니다. 페이지는 neboFetch와 상대 경로로 사이드카에 접근합니다. 앱 사이드카를 참조하세요.
Nebo에서 게시하기
소유자가 만든 앱은 스스로 게시할 수 있습니다. 소유자가 “직접 게시해 줘”라고 말하거나, 앱 채팅에서, 모바일 앱의 앱 화면에서(상단 바, 또는 전체 화면 앱이라면 닫기 옆의 버튼) 게시를 탭하거나, 데스크톱 메뉴에서 이 앱 게시…를 선택하면 됩니다(macOS에서는 앱 창이 앞에 있을 때 파일 메뉴, Windows와 Linux에서는 앱 창의 앱 메뉴). 직원은 앱을 바탕으로 등록 정보 초안을 작성하고, 스크린샷을 3~5장 찍고, 채팅에 등록 정보를 보여 주어 대화로 다듬을 수 있게 합니다. 소유자가 카드에서 탭이나 음성으로 검토 제출이라고 답하기 전까지는 아무것도 전송되지 않습니다.
소유자가 만든 앱은 언제나 자신을 위한 개발자 도구를 가집니다: 새로고침, 상태, 콘솔, 스크린샷, 게시. 앱 개발자 모드(봇 설정, 개발자)를 켜면 다른 직원도 소유자의 어떤 앱이든 작업할 수 있고, 페이지에 떠 있는 콘솔이 추가되며, 캐시가 꺼집니다. 마켓플레이스에서 설치한 앱에는 개발자 도구나 게시 버튼이 절대 생기지 않습니다.
직접 앱 게시하기
페이지만 있는 앱은 agent 도구로 번들 하나로 게시합니다. AGENT.md 프런트매터에는 반드시 artifact_type: app이 있어야 하며, 없으면 마켓플레이스가 페이지 없는 일반 직원을 만듭니다. 콜론 뒤에 공백이 오는 값은 따옴표로 감싸세요. 따옴표가 없으면 프런트매터를 읽을 수 없어 앱이 아무 알림 없이 일반 직원이 됩니다.
--- name: deal-board description: "A board of open deals: sorted by close date, with a chat that knows each deal." artifact_type: app metadata: version: "1.0.0" --- # Deal Board You work beside the Deal Board app. ...
agent(action: "create", name: "deal-board", version: "1.0.0",
description: "A board of open deals, sorted by close date.",
manifestContent: "<contents of AGENT.md>")
agent(action: "bundle-token", id: "<app id>")
zip -r deal-board.zip deal-board -x '*/.git/*' '*/node_modules/*' '*/src/*'
curl -X POST "https://neboai.com/api/v1/skills/<app id>/bundle" \
-H "Authorization: Bearer <token>" \
-F file=@deal-board.zip
agent(action: "submit", id: "<app id>", version: "1.0.0") | zip 안의 항목 | 처리 방식 |
|---|---|
AGENT.md | 페르소나와 등록 정보의 매니페스트. |
agent.json | 직원의 구성. {}여도 괜찮습니다. |
manifest.json | 앱의 매니페스트로 유지됩니다: 창 설정과 권한이 설치된 앱에 그대로 적용됩니다. 유효한 JSON이어야 합니다. |
ui/ | 페이지. 허용 형식: html, css, js, mjs, ts, jsx, tsx, json, map, txt, md, 이미지(png, jpg, gif, svg, webp, avif, ico, bmp), 글꼴(woff, woff2, ttf, otf), 소리(mp3, wav, ogg, m4a, aac, flac, opus), 영상(mp4, webm, mov, m4v), wasm, glb, gltf, pdf. 점으로 시작하는 파일과 node_modules/는 제외됩니다. |
skills/<name>/ | 직원 자신의 스킬. 단독으로 업로드한 스킬처럼 검사됩니다: SKILL.md는 유지, scripts/와 bin/은 모든 유형 허용, 그 밖에는 스킬 허용 목록에 있는 것만. |
- 한도: 파일당 10 MB, 번들당 50 MB. 10 MB를 넘는 파일은 건너뛰고(결과의
filesSkipped와uiFilesStored를 확인하세요), 50 MB를 넘는 번들은 거부됩니다. - 업로드 토큰은 5분 동안 유효합니다. zip 안에 최상위 폴더가 하나만 있으면 그 폴더는 벗겨집니다.
- 비공개 앱이나 채널 전용 앱은 업로드할 때마다 설치 패키지가 즉시 다시 빌드되고, Nebo가 앱을 설치한 봇에 알립니다. 온라인 상태인 봇은 다시 빌드된 패키지를 바로 적용하고, 오프라인 상태인 봇은 다음에 연결될 때 적용합니다. 이를 위해 버전을 올릴 필요는 없으며, 앱에 대한 소유자의 설정, 일정, 데이터는 유지됩니다. 공개, 목록 비공개, 초대 전용 앱은 새 버전이 검토를 통과할 때까지 승인된 패키지를 유지합니다.
- 새 버전은 앱에 대한 각 소유자의 자동 업데이트 설정을 따릅니다. 소유자가 켜지 않는 한 꺼져 있으므로, 기본적으로 봇에 "업데이트 가능"이 표시되고 소유자가 설정의 업데이트 또는 받은편지함에서 적용합니다. 업데이트는 새 권한을 부여하지 않습니다. 새 버전이 추가한 권한은 앱이 처음 그 권한을 필요로 할 때 요청됩니다.
- NeboAI가 마켓플레이스에서 앱을 철회하면, 앱을 설치한 모든 봇이 앱을 끄고 소유자에게 알립니다. 삭제되는 것은 없습니다. 앱이 저장한 모든 것은 유지됩니다.
- 사이드카가 있는 앱은 대신
binary-token으로 플랫폼별 바이너리를 업로드하고, 페이지는ui아카이브로 업로드합니다. 앱 사이드카와 게시를 참조하세요.