员工包
应用是一个员工包,其中有一个把它标记为应用的 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>">。把状态保存在应用的存储中,而不是页面里:窗口会关闭,而存储会保留下来。
页面如何提供
- Nebo 在
/apps/<id>/ui/提供ui/,并在独立窗口中打开它。 - 没有匹配文件的路径会回退到
index.html,因此客户端路由可以正常工作。 - HTML 页面会带有
nebo-app-id和nebo-base-urlmeta 标签。 - 每个文件都以其真实的内容类型发送,包括视频、声音、字体、
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)会被缓存一年。其他所有文件(包括index.html)每次打开时都会检查,未变化时返回304。请在构建时生成带哈希的文件名,而不是手动重命名文件。 - 每个页面文件最大为 10 MB。
- 删除该文件夹会停用该员工;
delete_employee则会将其彻底移除。
添加 sidecar
当页面需要服务端逻辑、自己的数据,或员工可以调用的工具时,就添加一个 sidecar:一个由 Nebo 在应用旁边运行的二进制程序。页面用 neboFetch 加相对路径访问它。参见应用 Sidecar。
从 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 将某个应用从市场撤下,每个安装了它的机器人都会将其关闭并通知所有者。不会删除任何东西:应用保存的一切都会保留。
- 带有 sidecar 的应用则改用
binary-token上传各平台的二进制文件,页面以ui压缩包的形式上传。参见应用 Sidecar和发布。