应用类型与 manifest
OpenMax 应用目前支持的模板,以及 manifest(openmax.app.v1)的字段、示例、入口格式和提交时的校验规则。
应用类型与 manifest
一个应用 = 一份 manifest(openmax.app.v1)+ 你自己部署的带后端的网页。这页讲目前能做哪种应用,以及 manifest 怎么写、提交时会被怎么校验。
应用类型
| 模板 | 在哪出现 | 怎么拿身份 | 状态 |
|---|---|---|---|
| 页面应用 · 带后端 | Workspace 应用页 / 侧边栏,iframe 内嵌或新标签打开 | 审批通过后签发 App ID;提交人或管理员生成 App Secret(只显示一次,放后端)。应用自己跳授权端点,后端用 code + code_verifier + App ID + App Secret 换当前用户的 token | 目前唯一的模板 |
| 页面应用 · 纯前端(PKCE 公开客户端) | — | — | 延后;manifest 里写 public_client 会被拒(见下文「保留字段」) |
- iframe 永远拿不到用户的 Workspace 登录态,只拿得到为本应用签发的 token。
- Agent 不能打开应用(授权时报
APP_PRINCIPAL_KIND_INVALID)。由 AI Agent 代做时,提交可以由 Agent 完成;审批、生成 App Secret、首次打开验收要由人类成员来做。
manifest(openmax.app.v1)
manifest 是白名单:只能写下表列出的键,写了没列出的键报 unknown_field。
| 字段 | 是否必填 | 说明 |
|---|---|---|
schema |
必填 | 固定为 openmax.app.v1 |
slug |
必填 | 2~63 位,小写字母、数字和 -;保留词不能用;组织内唯一,发新版本时不能改 |
name |
必填 | 入口上显示的名字(name.zh 必填,name.en 可选) |
description |
可选 | 一句话介绍 |
icon |
必填 | https 图片地址,或 1–2 个字符 / emoji |
version |
必填 | 只收 X.Y.Z 三段数字(如 1.0.0),1.0.0-beta 这类会被拒;每次提交必须比已有版本大 |
url |
必填 | 应用自己的网页(https);外壳打开 url + 子路径。主机规则见「校验规则」 |
redirect_uri |
必填 | 授权回调地址(在你的后端),主机必须和 url 的主机相同。授权请求和换 token 时带的 redirect_uri 必须和它逐字节相同(大小写、末尾斜杠、端口都算) |
open |
必填 | "embed"(Workspace 内 iframe)、"external"(新标签),可以都选 |
entries[] |
必填 | 入口,见「entries 格式」 |
scopes[] |
必填 | 需要的 OpenMax 权限,从 scope 目录里选(见「scope」);要在用户不在时运行,加 offline_access。服务端会自动补上 org:me:read,不写也会有 |
另外两类键不能由开发者写:
- 保留字段:
public_client、slot、events、capabilities、tools、surfaces、credential_mode、egress_domains、card_actions这 9 个。组织应用填了报field_not_enabled。 - 平台写入的字段:
regions、publisher由平台写入。开发者填了,提交报field_server_managed。
示例
{
"schema": "openmax.app.v1",
"slug": "my-app",
"name": { "zh": "我的应用", "en": "My App" },
"description": "一句话说明这个应用做什么",
"icon": "我",
"version": "1.0.0",
"url": "https://my-app.example.com/",
"redirect_uri": "https://my-app.example.com/auth/openmax/callback",
"open": ["embed", "external"],
"entries": [
{ "path": "/", "title": "首页" },
{ "path": "/settings", "title": "设置", "roles": ["owner", "admin"] }
],
"scopes": ["org:me:read", "org:me.email:read", "work:project:read"]
}
entries 格式
- 1–20 个;必须有一个
path: "/"的入口。 path:以单个/开头的子路径,最长 512,不能含空白、?、#、\;各入口不能重复。title:可选,字符串,不分语言(写成{ "zh": … }这样的对象会报错),最长 40。roles:可选,取owner/admin/member;省略 = 所有成员可见。只管「谁看得到、能不能打开」,入口里的细粒度权限由你自己判断。- 不认识的键(如旧版的
slot)报错。
入口怎么被选中、怎么拼成实际打开的地址,见打开方式与地址。
校验规则
提交时校验,报错带字段路径。
schema必须是openmax.app.v1。slug:格式不对(不是 2~63 位小写字母、数字和-)、用了保留词、在本组织已被占用、或发新版本时改了,都报错。version必须是X.Y.Z三段数字,且大于当前版本。- 键必须在白名单里:没列出的键报
unknown_field;上面 9 个保留字段,组织应用填了报field_not_enabled;regions、publisher填了报field_server_managed。 url和redirect_uri都必须是 https,都不能带用户信息(如https://user@host/)或#fragment。url、redirect_uri的主机:- 比较前先转小写,并按国际化域名(IDN)统一编码。
redirect_uri的主机必须和url的主机相同。- 不能用 IP(以数字结尾的主机按 IP 算)。
- 不能用单段主机名(如
myapp)。 - 不能用平台自己的域名和它的子域。
- 不能用这些内网后缀:
localhost、local、localdomain、internal、intranet、lan、home、corp、private、home.arpa、test、invalid。
redirect_uri要和使用时的值逐字节相同:授权时(包括嵌入时用 requestAuthCode 向宿主要授权码)和换 token 时带的 redirect_uri,都必须和 manifest 里登记的值逐字节相同(/callback与/callback/是两个地址)。open只能取embed/external,至少一个、不重复。scopes里每一项都必须在目录里,且是应用可申请的:apps:badge:write可以申请;其余apps:*不能申请。- 伞形 scope(
api、read_api)不能申请。
