NeboAI
NeboAI
开始使用

应用

应用就是一位带页面的员工。所有者在独立窗口中打开它,直接查看和操作某样东西:一块看板、一个跟踪器、一张表单。页面就是普通的 HTML 和 JavaScript,它通过一个脚本——应用 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,并为移动应用设置 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-url meta 标签。
  • 每个文件都以其真实的内容类型发送,包括视频、声音、字体、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和发布。