Gói
Ứng dụng là một gói nhân viên có manifest.json đánh dấu nó là ứng dụng và một thư mục ui/ chứa trang.
<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"]
} | Trường | Ý nghĩa |
|---|---|
type | "app". Biến nhân viên thành ứng dụng. Nebo cũng đọc trường cũ artifact_type. |
id | Một UUID được tạo khi ứng dụng được tạo. Trang được phục vụ tại /apps/<id>/ui/. |
name, version | Tên của nhân viên và phiên bản của gói. |
window | title, width, height, resizable, fullscreen, orientation. Mặc định: 1024 × 768, có thể đổi kích thước, không toàn màn hình, hướng dọc, tiêu đề theo tên nhân viên. |
permissions | Những gì trang được phép làm. Mặc định ["storage:readwrite"]. |
Quyền
| Quyền | Cho phép |
|---|---|
storage:readwrite | Kho khóa-giá trị của ứng dụng. |
subagent:<employee-id> | Hỏi một nhân viên khác từ trang. Nhân viên của chính ứng dụng không cần quyền. |
network:<host> hoặc network:* | Các yêu cầu tới máy chủ bên ngoài qua proxy của Nebo. |
device:motion | Con quay hồi chuyển và gia tốc kế, chỉ cho trang này. Trên iPhone, trang cũng gọi DeviceMotionEvent.requestPermission() từ một lần chạm. |
Mọi quyền đều có dạng prefix:scope. Chỉ xin những gì tối thiểu ứng dụng cần.
Toàn màn hình, hướng màn hình và độ nghiêng
Trò chơi và phim có thể chiếm toàn bộ màn hình. Đặt fullscreen và, với ứng dụng di động, một orientation: portrait (mặc định), landscape hoặc any. Mọi hướng khác đều bị từ chối khi manifest được ghi.
{
"type": "app",
"permissions": ["storage:readwrite", "device:motion"],
"window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
} - Trên máy tính, ứng dụng mở trong một cửa sổ toàn màn hình.
- Trong ứng dụng di động không có thanh ứng dụng, các thanh hệ thống được ẩn, màn hình luôn sáng và tính năng kéo để làm mới bị tắt. Một nút Đóng nhỏ nằm ở góc trên bên trái và mờ dần sau vài giây; chạm gần mép trên sẽ hiện lại nút. Thao tác vuốt từ cạnh trên iOS bị tắt, và nút quay lại của Android sẽ đi lùi qua lịch sử của trang trước khi đóng.
- Đệm trang bằng
env(safe-area-inset-*)vàviewport-fit=cover, và giữ các nút điều khiển tránh xa góc trên bên trái.
Nút điều khiển giọng nói
Mọi ứng dụng mở trong ứng dụng Nebo trên máy tính hoặc trong ứng dụng di động đều hiển thị một nút điều khiển giọng nói nhỏ ở góc dưới bên phải, để chủ sở hữu có thể nói chuyện với nhân viên của ứng dụng trong khi nhân viên làm việc trên trang. Nút điều khiển nằm bên ngoài trang của bạn, nên tải lại trang không bao giờ làm ngắt cuộc gọi.
- Trên máy tính, đó là một thanh khoảng 300 x 48 pixel, cách góc dưới bên phải cửa sổ 16 pixel.
- Trong ứng dụng di động, đó là một nút tròn 48 point nằm trong vùng an toàn mà chủ sở hữu có thể kéo sang bất kỳ bên nào. Trong ứng dụng toàn màn hình, nó thu lại thành nút đó sau vài giây kể từ khi cuộc gọi bắt đầu.
- Giữ các nút điều khiển quan trọng tránh xa góc dưới bên phải.
- Trong một việc kéo dài khi đang gọi, nhân viên nói những cập nhật ngắn như “Đang chỉnh sửa.” và không bao giờ đọc to tên tệp hay lệnh.
Tạo một ứng dụng
Nhân viên có thể xây dựng ứng dụng theo hai cách, và chọn dựa trên những gì chủ sở hữu nói. “Làm cho tôi một ứng dụng quản lý đơn hàng” sẽ tạo một nhân viên ứng dụng mới. “Bạn chính là ứng dụng” hoặc “tự làm cho mình một trò chơi” sẽ biến nhân viên mà chủ sở hữu đang trò chuyện thành ứng dụng: nhân viên giữ nguyên cuộc trò chuyện, bộ nhớ và tính cách, và trang của nó tải lại trong khi chủ sở hữu đang nói chuyện. Điều này cũng áp dụng cho nhân viên được tuyển ngay trong cuộc trò chuyện. Khi chưa rõ chủ sở hữu muốn cách nào, nhân viên sẽ hỏi một lần.
update_employee(
name: "<the employee's own name>",
app: { window: { title: "Solitaire", fullscreen: true, orientation: "landscape" } },
ui: { "index.html": "<!doctype html>..." }
) Các công cụ hằng ngày (trình theo dõi, biểu mẫu, bảng điều khiển nhỏ) được xây dựng bằng kỹ năng ứng dụng tích hợp sẵn của Nebo. Một trang cần trông như được thiết kế thay vì được tạo tự động, chẳng hạn trang đích điện ảnh, phim chạy theo thao tác cuộn, tranh được tạo hoặc trò chơi, được xây dựng bằng kỹ năng App Studio từ chợ ứng dụng.
Với một ứng dụng mới, cách đơn giản nhất là nhờ một nhân viên. Nebo có sẵn một kỹ năng để xây dựng ứng dụng, và nhân viên dùng create_employee, công cụ này ghi thư mục, manifest, tính cách và trang chỉ trong một lệnh gọi. Ứng dụng xuất hiện trong đội ngũ AI của chủ sở hữu chỉ trong vài giây.
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 nhận cùng các đối số ui, app và agent_md. Một đường dẫn trong ui sẽ thay thế đúng tệp đó. Trang được đọc từ ổ đĩa trong mọi yêu cầu, nên tải lại cửa sổ sẽ hiển thị thay đổi.
Một trang tối thiểu
Trang này nạp SDK, hỏi nhân viên của nó là ai và in câu trả lời. Nếu nó hiển thị id và tên của nhân viên, việc kết nối đã đúng.
<!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 tìm id ứng dụng từ địa chỉ của trang. Một trang được phục vụ từ nơi khác cần <meta name="nebo-app-id" content="<id>">. Giữ trạng thái trong storage của ứng dụng, không phải trong trang: cửa sổ sẽ đóng, còn storage thì vẫn còn.
Cách trang được phục vụ
- Nebo phục vụ
ui/tại/apps/<id>/ui/và mở nó trong cửa sổ riêng. - Một đường dẫn không có tệp tương ứng sẽ quay về
index.html, nên định tuyến phía client vẫn hoạt động. - Các trang HTML nhận các thẻ meta
nebo-app-idvànebo-base-url. - Mọi tệp đều được gửi đi với đúng content type thực của nó, bao gồm video, âm thanh, phông chữ,
wasmvà mô hình 3D (glb,gltf). Tệp có phần mở rộng không xác định được gửi dưới dạngapplication/octet-streamvà trình duyệt sẽ không dùng nó. - Tệp hỗ trợ yêu cầu theo phạm vi (
206, hoặc416cho phạm vi vượt quá cuối tệp), nên video và âm thanh có thể tua. Trong ứng dụng di động, video phát ngay tại chỗ mà không cần chạm:<video muted playsinline autoplay loop poster="assets/hero.jpg" src="assets/hero.mp4"></video> - Tệp có tên chứa mã băm nội dung, chẳng hạn
main-0a8ksftt.js, được lưu đệm trong một năm. Mọi tệp khác, kể cảindex.html, được kiểm tra mỗi lần mở và trả về304khi không thay đổi. Hãy build với tên có mã băm thay vì tự đổi tên tệp. - Mỗi tệp của trang tối đa 10 MB.
- Xóa thư mục sẽ vô hiệu hóa nhân viên;
delete_employeegỡ bỏ hoàn toàn nhân viên.
Thêm sidecar
Khi trang cần logic phía máy chủ, dữ liệu riêng hoặc công cụ mà nhân viên có thể gọi, hãy thêm một sidecar: một tệp nhị phân Nebo chạy bên cạnh ứng dụng. Trang truy cập nó bằng neboFetch với một đường dẫn tương đối. Xem App Sidecar.
Xuất bản từ Nebo
Một ứng dụng do chủ sở hữu tạo có thể tự xuất bản. Chủ sở hữu nói “hãy tự xuất bản”, hoặc chạm Xuất bản trong cuộc trò chuyện của ứng dụng, trên màn hình của ứng dụng trong ứng dụng di động (ở thanh trên cùng, hoặc dưới dạng nút cạnh nút Đóng với ứng dụng toàn màn hình), hoặc chọn Xuất bản ứng dụng này… từ menu trên máy tính (menu File trên macOS khi cửa sổ ứng dụng đang ở phía trước; menu App của cửa sổ ứng dụng trên Windows và Linux). Nhân viên soạn trang niêm yết từ ứng dụng, chụp 3 đến 5 ảnh màn hình và hiển thị trang niêm yết trong cuộc trò chuyện để chỉnh sửa bằng cách trò chuyện. Không có gì được gửi đi cho đến khi chủ sở hữu trả lời Gửi để kiểm duyệt trên thẻ, bằng cách chạm hoặc bằng giọng nói.
Một ứng dụng do chủ sở hữu tạo luôn có công cụ dành cho nhà phát triển cho chính nó: tải lại, trạng thái, console, ảnh chụp màn hình và xuất bản. Chế độ Nhà phát triển ứng dụng (Cài đặt bot, Nhà phát triển) cho phép các nhân viên khác làm việc trên bất kỳ ứng dụng nào của chủ sở hữu, thêm một console nổi vào trang và tắt bộ nhớ đệm. Ứng dụng cài từ chợ ứng dụng không bao giờ có công cụ dành cho nhà phát triển hay nút Xuất bản.
Tự xuất bản một ứng dụng
Một ứng dụng chỉ có trang được xuất bản dưới dạng một gói duy nhất bằng công cụ agent. Frontmatter của AGENT.md phải ghi artifact_type: app, nếu không chợ ứng dụng sẽ tạo một nhân viên thông thường không có trang. Hãy đặt trong dấu ngoặc kép mọi giá trị có chứa dấu hai chấm theo sau là dấu cách; nếu không có dấu ngoặc kép, frontmatter không đọc được và ứng dụng sẽ âm thầm trở thành một nhân viên thông thường.
--- 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") | Trong tệp zip | Điều gì xảy ra |
|---|---|
AGENT.md | Tính cách và manifest của trang niêm yết. |
agent.json | Cấu hình của nhân viên. {} cũng được. |
manifest.json | Được giữ làm manifest của ứng dụng: cửa sổ và quyền được chuyển tới ứng dụng đã cài. Phải là JSON hợp lệ. |
ui/ | Trang. Được phép: html, css, js, mjs, ts, jsx, tsx, json, map, txt, md, hình ảnh (png, jpg, gif, svg, webp, avif, ico, bmp), phông chữ (woff, woff2, ttf, otf), âm thanh (mp3, wav, ogg, m4a, aac, flac, opus), video (mp4, webm, mov, m4v), wasm, glb, gltf, pdf. Các tệp bắt đầu bằng dấu chấm và node_modules/ bị loại bỏ. |
skills/<name>/ | Các kỹ năng riêng của nhân viên, được kiểm tra như một kỹ năng tải lên riêng: giữ SKILL.md, scripts/ và bin/ mọi loại tệp, mọi thứ khác phải nằm trong danh sách cho phép của kỹ năng. |
- Giới hạn: 10 MB mỗi tệp và 50 MB mỗi gói. Tệp lớn hơn 10 MB bị bỏ qua (kiểm tra
filesSkippedvàuiFilesStoredtrong kết quả); gói lớn hơn 50 MB bị từ chối. - Token tải lên có hiệu lực trong 5 phút. Một thư mục cấp cao nhất duy nhất trong tệp zip sẽ bị bỏ đi.
- Với ứng dụng riêng tư hoặc chỉ dành cho các kênh, mỗi lần tải lên sẽ dựng lại ngay gói cài đặt và Nebo thông báo cho các bot đã cài ứng dụng. Bot đang trực tuyến đặt gói mới dựng vào chỗ ngay lập tức; bot ngoại tuyến sẽ làm việc đó khi kết nối lần tới. Bạn không cần tăng phiên bản cho việc này, và các cài đặt, lịch và dữ liệu của chủ sở hữu cho ứng dụng vẫn được giữ nguyên. Ứng dụng công khai, không niêm yết và chỉ dành cho người được mời giữ gói đã được duyệt cho đến khi phiên bản mới qua kiểm duyệt.
- Một phiên bản mới tuân theo cài đặt tự động cập nhật của từng chủ sở hữu cho ứng dụng đó. Cài đặt này tắt trừ khi chủ sở hữu bật lên, nên theo mặc định bot sẽ hiện "Có bản cập nhật" và chủ sở hữu áp dụng từ Cài đặt, rồi Cập nhật, hoặc từ Hộp thư đến. Bản cập nhật không bao giờ cấp quyền mới; quyền mà phiên bản mới thêm vào sẽ được hỏi khi ứng dụng cần đến lần đầu.
- Nếu NeboAI rút một ứng dụng khỏi chợ ứng dụng, mọi bot đã cài sẽ tắt ứng dụng đó và thông báo cho chủ sở hữu. Không có gì bị xóa: mọi thứ ứng dụng đã lưu đều được giữ lại.
- Một ứng dụng có sidecar thì tải lên tệp nhị phân của từng nền tảng bằng
binary-token, còn trang dưới dạng kho lưu trữui. Xem App Sidecar và Xuất bản.