套件
應用程式是一個員工套件,帶有將它標記為應用程式的 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,若是行動版 App,再設定 orientation:portrait(預設)、landscape 或 any。寫入 manifest 時,其他任何方向值都會被拒絕。
{
"type": "app",
"permissions": ["storage:readwrite", "device:motion"],
"window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
} - 在桌面版上,應用程式會在全螢幕視窗中開啟。
- 在行動版 App 中,沒有應用程式列、系統列會隱藏、螢幕保持喚醒,且下拉重新整理會關閉。左上角有一個小小的「關閉」膠囊按鈕,幾秒後會淡出;點觸靠近頂端的地方就會再出現。iOS 的邊緣滑動會關閉,Android 的返回鍵會先在頁面的瀏覽紀錄中返回,最後才關閉。
- 使用
env(safe-area-inset-*)與viewport-fit=cover為頁面加上內距,並讓控制項避開左上角。
語音控制
每個在 Nebo 桌面版 App 或行動版 App 中開啟的應用程式,右下角都會顯示一個小小的語音控制,讓擁有者能在應用程式員工處理頁面時與它對話。這個控制位於你的頁面之外,所以重新載入頁面永遠不會中斷通話。
- 在桌面版上,它是一條約 300 × 48 像素的橫列,距離視窗右下角 16 像素。
- 在行動版 App 中,它是安全區域內一個 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,在一次呼叫中寫好資料夾、manifest、人設與頁面。幾秒內,應用程式就會出現在擁有者的人力團隊中。
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 會在
/apps/<id>/ui/提供ui/,並在專屬的視窗中開啟它。 - 沒有對應檔案的路徑會退回到
index.html,所以用戶端路由可以正常運作。 - HTML 頁面會取得
nebo-app-id與nebo-base-urlmeta 標籤。 - 每個檔案都會以實際的內容類型送出,包括影片、音訊、字型、
wasm和 3D 模型(glb、gltf)。副檔名不明的檔案會以application/octet-stream送出,瀏覽器不會使用它。 - 檔案支援範圍請求(
206,若範圍超出結尾則為416),因此影片和音訊可以跳轉。在行動 app 中,影片不用點按就會直接在原處播放:<video muted playsinline autoplay loop poster="assets/hero.jpg" src="assets/hero.mp4"></video> - 檔名帶有內容雜湊值的檔案,例如
main-0a8ksftt.js,會快取一年。其他所有檔案,包括index.html,每次開啟時都會檢查,未變更時回應304。請在建置時使用雜湊檔名,而不是手動重新命名檔案。 - 每個頁面檔案最大為 10 MB。
- 刪除資料夾會停用這位員工;
delete_employee則會將它完全移除。
加入 sidecar
當頁面需要伺服器邏輯、自己的資料,或員工可以呼叫的工具時,就加入一個 sidecar:一個由 Nebo 在應用程式旁執行的二進位檔。頁面透過 neboFetch 搭配相對路徑存取它。請參閱應用程式 Sidecar。
從 Nebo 發布
擁有者自己做的應用程式可以自行發布。擁有者說「發布你自己」,或在應用程式的聊天中、在行動版 App 的應用程式畫面上(位於頂端列,或在全螢幕應用程式中「關閉」旁的膠囊按鈕)點按發布,或從桌面版選單中選擇發布此應用程式…(在 macOS 上,當應用程式視窗位於最前方時,位於「檔案」選單;在 Windows 與 Linux 上,位於應用程式視窗的「App」選單)。員工會根據應用程式草擬上架資訊、拍攝 3 到 5 張螢幕截圖,並在聊天中顯示上架資訊,讓擁有者以對話的方式調整。在擁有者以點按或語音回答卡片上的提交審核之前,不會送出任何東西。
擁有者自己做的應用程式,一律能使用自己的開發者工具:重新載入、狀態、主控台、螢幕截圖與發布。App 開發者模式(機器人設定、開發者)讓其他員工也能處理擁有者的任何應用程式,在頁面上加入浮動主控台,並關閉快取。從市集安裝的應用程式永遠不會有開發者工具或發布按鈕。
自行發布應用程式
只有頁面的應用程式會使用 agent 工具以單一套件發布。AGENT.md 的 frontmatter 必須寫明 artifact_type: app,否則市集會建立一位沒有頁面的一般員工。任何包含「冒號後接空格」的值都要加上引號;若未加引號,frontmatter 就無法讀取,應用程式會悄悄變成一般員工。
--- 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 | 人設與上架資訊的 manifest。 |
agent.json | 員工的設定。{} 也可以。 |
manifest.json | 保留作為應用程式的 manifest:視窗與權限設定會套用到已安裝的應用程式。必須是有效的 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 將某個應用程式從市集下架,每個安裝了它的機器人都會將它關閉並通知擁有者。不會刪除任何東西:應用程式儲存的所有內容都會保留。
- 具備 sidecar 的應用程式則改用
binary-token上傳各平台的二進位檔,頁面則以ui封存檔上傳。請參閱應用程式 Sidecar與發布。