NeboAI
NeboAI
開始使用

應用程式

應用程式就是一位擁有頁面的員工。擁有者會在它專屬的視窗中開啟它,直接查看並操作某樣東西:看板、追蹤表、表單。頁面是純 HTML 和 JavaScript,透過單一指令碼 App SDK 與 Nebo 及其員工溝通。

套件

應用程式是一個員工套件,帶有將它標記為應用程式的 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員工的名稱與套件版本。
windowtitle、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-url meta 標籤。
  • 每個檔案都會以實際的內容類型送出,包括影片、音訊、字型、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與發布。