OpenMax
免费试用

应用类型与 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)不能申请。