OpenMax
免费试用

提交审批与安装

应用怎么提交、谁审批、怎么安装 / 停用 / 卸载;应用角标;scope 之外应用自己要做的权限和审计。

提交审批与安装

这页讲应用从提交到装进组织的过程,以及怎样给成员的应用入口设角标。能申请哪些 scope(权限)见「scope」。

提交、审批、安装

提交

应用页 →「提交应用」→ 选模板(manifest 自动填好)→ 粘贴 / 上传 manifest.json,或按表单填写(生成同一份 manifest)。页面实时校验,错误标到字段上。应用页和提交页都有「开发文档」抽屉(快速开始 / manifest 字段 / scope 列表 / 示例代码)。

manifest 字段和校验规则见应用类型与 manifest。

可见性与审批

组织应用 全局应用
谁能看到 本组织 所有组织(出现在目录里)
谁审批 本组织管理员(owner / admin),审批人不能是申请人本人;管理员 / 超管自己提交自动通过 平台(暂不对外开放)
地址 /workspace/apps/custom/{slug}-{4 位随机} /workspace/apps/{slug}
  • 目前第三方只能做组织应用。上架到所有组织的全局应用暂不对外开放。
  • 任何成员都能提交新应用、给本组织任何应用发新版本。成员(非管理员)和 Agent 提交的每个新版本都要一位管理员审批。
  • 首次审批通过后分配平台链接和 App ID。
  • 提交人或管理员点「生成 App Secret」:只显示一次,可轮换;轮换后旧 Secret 保留 24 小时,最多同时两个。

安装、停用、卸载

  • 安装到组织:组织应用首次审批通过后自动装到本组织,无需另装。「安装 / 申请安装」只针对目录里的(全局 / 官方)应用:管理员直接安装;成员只能「申请安装」,由管理员批准。没有逐人同意:管理员批给安装的 scope 就是每个成员 token 的 scope。
  • 停用:入口消失,已签发的 access token 全部失效(最多 30 秒),应用调接口返回 401,授权回调 access_denied。重新启用后用户重新打开即可。
  • 卸载:入口移除;吊销 App Secret、全部 refresh token;地址作废、不再复用。不可撤销。
  • 成员离开组织:该成员的 refresh token 一起吊销。
  • 平台不主动通知应用这些变化:收到 401 就当授权没了处理,别无限重试。

应用角标

现状:已上线。

应用可以给组织里的成员设角标(数字或小红点),显示在 Workspace 里该应用的入口上,例如「你有 7 条待审批」。角标由应用服务端写,用 App ID + App Secret 认证,不需要成员在线。

开通

  1. manifest 的 scopes 里加上 apps:badge:write。
  2. 提交新版本。成员提交的版本要一位管理员审批,审批单会标出新增的 scope;管理员自己提交自动通过。
  3. 新版本审批通过后生效。

写接口

PUT /api/v1/app-badges

认证:只用 App ID + App Secret,下面两种二选一:

  • HTTP Basic(用户名 App ID,密码 App Secret);
  • 请求 body 里放 app_id / app_secret。

两种都给回 400。不接受 Bearer token(成员的 access token 不能用来写角标)。

请求 body:

{
  "org_id": "…",
  "items": [
    { "member_id": "…", "count": 7 },
    { "member_id": "…", "dot": true },
    { "member_id": "…", "count": 0 }
  ],
  "as_of": "2026-11-06T09:30:00Z"
}
字段 说明
org_id 必填。写哪个组织的角标
items 必填,1~500 条
items[].member_id 必填。同一个 member_id 在一次请求里不能出现两次
items[].count 数字角标,取 1~1000000;0 表示清除
items[].dot true 表示小红点;false 表示清除
as_of 可选,RFC 3339 时间,最多比服务器时间超前 5 分钟
  • 每条 count 和 dot 只能给一个。
  • 带了 as_of 时,旧的 as_of 不会覆盖新的值,也不会把已清除的角标写回来。乱序到达的请求不会把角标改回旧值。

返回:

{ "data": { "applied": 3, "cleared": 1, "skipped": 0 } }
  • applied:设上的条数。
  • cleared:清除的条数。
  • skipped:跳过的条数,即不属于该组织的有效成员(包括 Agent)。返回里不说明具体原因。

错误:响应体是 HTTP problem JSON。

HTTP 错误码 含义
400 — 请求不合法,例如 items 为空、同一条同时给 count 和 dot、Basic 和 body 凭证同时给
422 — 字段校验失败,例如超过 500 条、未知字段
401 AUTH_INVALID_CREDENTIALS App ID / App Secret 不对
403 APP_INSTALLATION_INACTIVE 该组织没装这个应用,或已停用
403 AUTH_APP_INSUFFICIENT_SCOPE 安装没批 apps:badge:write
429 APP_BADGE_RATE_LIMITED 超过频率限制,按 Retry-After 头等待后再发

频率限制:每个安装每分钟 120 次。限额是近似值,不是精确上限,别把它当作可以打满的额度。

生命周期

  • 应用卸载时,它的角标全部删除。
  • 安装停用期间不显示角标。

显示

  • 数字大于 99 时显示为「99+」。
  • 页面不轮询角标。以下时机刷新:页面加载、切换应用、窗口切回来。
  • 同一应用内换页不刷新角标。

建议用法

  • 某个人的数变了就发一条请求,只带这个人。
  • 再每隔几分钟按全量补一次,每 500 人一批,修正漏发和失败的写入。
  • 两种请求都可以带上 as_of(数据的时间点),这样晚到的旧数据不会盖掉新数据。

权限与审计

平台规则:「scope」、上面的「提交、审批、安装」、「token」、「发新版本」、「错误处理」。有效权限 = 已批准的 scope ∩ 这个人本身的权限;平台没有按动作收窄的授权,也没有审计要求和审计接口。下面是参考实现(OpenMax Workflows)的做法,是建议,不是平台要求。

权限

建议做法

  • 主人授权 agent 用你的应用:主人点「让它用」,服务端调 /api/v1/app-agent-grants 登记;管理员在 OpenMax 侧可撤(见 Agent 调用应用)。
  • 需要「只许它做这一类事」时,在应用里自己限。
  • 高风险写操作二次确认:先 dry_run 返回将要改的清单和摘要,再带 confirm_digest 提交。摘要只证明「看过这份清单」,不是授权凭证,权限照常校验。
  • 放大权限要确认,收窄可以直接改。
  • 代人办事权限两档取低(说话人和 agent)。

踩过的坑

  • manifest 新增一个 scope 后,新版本审批通过前用不到它;通过后老 token 也换不出新 scope。缺 scope 的提示要同时给组织管理员(去批)和当事人(重新登录)。

审计

建议

  • 每次写都记:谁、从哪个入口、做了什么。入口区分开,例如:网页会话、个人 key、系统、OpenMax 登录、agent 代办。
  • 被拒的写也记一行(allowed=false)。为防刷屏可合并:同一个键 10 分钟内只写前 5 行,之后合成一行汇总。
  • 代办记本人:agent 替人办事时,入口记「代办」,操作人记说话的那个人,不记成 agent。
  • 登录也要审计:记从 OpenMax 登录;嵌入用请求头会话的另记交付方式和浏览器大类,不记完整 UA。
  • 审计里不放秘密:授权 code、verifier、nonce、token、密码、会话 id 不进日志、审计和回包;业务内容也不进审计详情。
  • 防篡改:审计表只能追加(触发器禁止 UPDATE / DELETE / TRUNCATE),用哈希链(每行存上一行哈希)。
  • 运维检查要读到审计表:健康检查是绿的不代表库可读,巡检要能真的读到审计表。

为什么建议做

  • 平台停用应用、撤销授权都不通知应用,出了事只能靠你自己的记录还原「谁在什么时候做了什么」。
  • agent 代人办事时,没有审计就分不清是人做的还是 agent 做的。