发布与版本
怎么发新版本、从旧 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。
要改三处:
- 加一个「发起授权」入口:应用自己判断没有会话,就生成
state、nonce、code_verifier存服务端,跳{issuer}/api/v1/apps/authorize(参数见登录「授权请求参数」)。去掉「等外壳带 code 打开回调」的假设。外壳现在打开的是你的url+ 子路径,query 上只有显示用的theme/openmax_lang(见打开方式与地址「入口地址上的参数」),没有 code / state,也没有任何身份参数。 - 回调改成核自己的 state 和 iss,并带
code_verifier换 token:state 由你生成(以前由外壳生成、里面带 JSON 路径),返回路径改存服务端流程。token 请求不带code_verifier会被拒(invalid_request)。建议改用 id_token +nonce拿身份,用户标识用member_id。 - 嵌入与错误处理:嵌入时改用宿主代发授权码(见登录「嵌入时登录」),不在 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 调用应用)。
- 只在某个环境用的配置都做成可选,代码里不写死某个环境的地址和配置。
