OpenMax
免费试用

发布与版本

怎么发新版本、从旧 launch 方式迁移,以及发版的实践建议和上线前自查。

发布与版本

发新版本

  • manifest 的 version 只收 X.Y.Z 三段数字(如 1.0.0、1.2.10)。1.0.0-beta 这类带后缀的写法会被拒收。
  • 每次提交的 version 必须比已有版本大。slug 发新版本时不能改。
  • 成员(非管理员)或 Agent 提交的每个新版本都要一位管理员审批;管理员(有应用管理权限的人类成员)自己提交自动通过。要不要审批只看提交人,跟 scope 有没有变化无关;新增 scope 时,审批单会标出新增的权限。审批通过前,应用继续按旧版本运行。
  • 新增 scope 批准后,成员在应用下一次授权时自动带上,不再弹确认。
  • redirect_uri 以已安装版本为准;改了它要等新版本安装生效后再切换代码。

manifest 的其他校验规则见应用类型与 manifest「校验规则」。

从旧 launch 方式迁移

旧流程是:外壳调 launch 签发 code,带 ?code=&state= 打开你的 redirect_uri,首次打开弹「申请了新的权限」同意框。这套流程已删除,不保留兼容:launch-app / consent-app 接口已下线,外壳不再给你送 code。

要改三处:

  1. 加一个「发起授权」入口:应用自己判断没有会话,就生成 state、nonce、code_verifier 存服务端,跳 {issuer}/api/v1/apps/authorize(参数见登录「授权请求参数」)。去掉「等外壳带 code 打开回调」的假设。外壳现在打开的是你的 url + 子路径,query 上只有显示用的 theme / openmax_lang(见打开方式与地址「入口地址上的参数」),没有 code / state,也没有任何身份参数。
  2. 回调改成核自己的 state 和 iss,并带 code_verifier 换 token:state 由你生成(以前由外壳生成、里面带 JSON 路径),返回路径改存服务端流程。token 请求不带 code_verifier 会被拒(invalid_request)。建议改用 id_token + nonce 拿身份,用户标识用 member_id。
  3. 嵌入与错误处理:嵌入时改用宿主代发授权码(见登录「嵌入时登录」),不在 iframe 里跳转,不靠 cookie。仍保留的 cookie 改成 SameSite=None; Secure; Partitioned,frame-ancestors 填对环境的 Workspace origin。处理 login_required / access_denied 并加防循环标记。删掉所有依赖「首次打开同意框」的逻辑(现在没有逐人同意)。

发版实践

平台要求:「校验规则」、上面的「发新版本」、「可见性与审批」、「上线清单」。manifest 的 version 只收 X.Y.Z,每次都要比上一版大。下面是参考实现(OpenMax Workflows)的做法,是建议,不是平台要求。

建议做法

  • 产品版本只有一个来源:仓库根目录 VERSION。开发中写 X.Y.Z-dev;发版在 release/X.Y.Z 分支改成 X.Y.Z,同时 main 改成下一个版本 -dev。正式环境只发不带 -dev 的提交。
  • 构建时注入版本号、提交号、部署时间,页面底部用人的话显示「应用名 1.2.0 · 11-04 更新」;不显示 manifest 的版本。
  • 合进主干不等于可以部署:部署前报批,部署后跑冒烟测试。
  • 反向代理:剥掉内部使用的身份请求头,防止外部伪造;有 SSE 的话读超时设到 ≥3600 秒。
  • skill 和 CLI 一起发:公开仓库 release 附各平台二进制和 sha256,安装时核对(见 Agent 调用应用)。
  • 只在某个环境用的配置都做成可选,代码里不写死某个环境的地址和配置。

上线前自查

  • 过完上线清单(嵌入、新标签两种打开方式各一遍)
  • manifest version 是 X.Y.Z 且已递增
  • iPhone / iPad / 桌面 Safari 嵌入能登录(requestAuthCode)
  • 手机宽度(390)嵌入下没有横向滚动(见页面 UX 规范)
  • 新版本已由管理员审批通过(成员提交要一位管理员审批,新增 scope 会在审批单里标出)