create-zleap-app 0.10.0 → 0.10.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/index.js +24 -2
  2. package/lib/scaffold.js +10 -0
  3. package/package.json +4 -4
  4. package/skills/zleap-cloud-app/SKILL.md +6 -6
  5. package/skills/zleap-cloud-app/references/app-runtime.md +82 -75
  6. package/skills/zleap-cloud-app/references/cloud-functions.md +230 -43
  7. package/skills/zleap-cloud-app/references/console-database.md +8 -0
  8. package/skills/zleap-cloud-app/references/console-members.md +44 -30
  9. package/skills/zleap-cloud-app/references/limits.md +57 -56
  10. package/skills/zleap-cloud-app/references/manifest.md +36 -35
  11. package/skills/zleap-cloud-app/references/permissions.md +40 -47
  12. package/skills/zleap-cloud-app/references/sdk-database-files.md +116 -49
  13. package/skills/zleap-cloud-app/references/status-codes.md +126 -94
  14. package/skills/zleap-cloud-app/references/triggers.md +24 -24
  15. package/skills/zleap-cloud-app-release/SKILL.md +5 -2
  16. package/skills/zleap-cloud-app-release/references/app-center-install.md +64 -52
  17. package/skills/zleap-cloud-app-release/references/app-center-publish.md +118 -49
  18. package/skills/zleap-cloud-app-release/references/console-functions.md +12 -4
  19. package/skills/zleap-cloud-app-release/references/console-legacy-release.md +5 -2
  20. package/skills/zleap-cloud-app-release/references/console-members.md +44 -30
  21. package/skills/zleap-cloud-app-release/references/console-release.md +39 -28
  22. package/skills/zleap-cloud-app-release/references/console-workspace.md +32 -16
  23. package/skills/zleap-cloud-app-release/references/dev-to-production.md +330 -113
  24. package/skills/zleap-cloud-app-release/references/permissions.md +40 -47
  25. package/skills/zleap-cloud-app-release/references/status-codes.md +126 -94
  26. package/templates/react-ts/AGENTS.md +2 -2
  27. package/templates/react-ts/README.md +1 -1
  28. package/templates/react-ts/package.json +3 -0
  29. package/templates/react-ts/scripts/zleap.mjs +25 -3
  30. package/templates/react-ts/src/cloud/client.ts +2 -2
package/skills/zleap-cloud-app/references/sdk-database-files.md CHANGED
@@ -2,15 +2,17 @@
2
2
 
3
3
  # 云数据库 API
4
4
 
5
- 面向**应用页面**（iframe 里的前端代码）的 Cloud SDK 参考：初始化、数据库、文件、后台调用、操作回执与错误处理。
5
+ 面向**应用页面**（iframe 里的前端代码）的 Cloud SDK 参考：初始化、数据库、文件、页面接口、后台调用、操作回执与错误处理。
6
6
  云函数里用的是另一套服务端 SDK，见 [云函数开发](cloud-functions.md)。
7
7
 
8
- 本页以 SDK 源码为准：`zleap-web/packages/app-cloud-sdk/src/`（`index.ts`、`values.ts`、`files.ts`、`execution.ts`、`protocol.ts`、`transport.ts`），
9
- 以及 CLI 模板里随附的 `sdk/*.d.ts`。
8
+ 本页以发布的 SDK 为准：npm 包 `@zleap-ai/app-sdk` 的类型声明 `dist/types/*.d.ts`（`index.d.ts`、`values.d.ts`、`files.d.ts`、`execution.d.ts`、`protocol.d.ts`、`transport.d.ts`），
9
+ 以及 CLI 内嵌、`zleap-app init` 生成的 `sdk/` 目录（同一份实现，源码在 `zleap-service/internal/appdevcli/templates/todo/sdk`）。
10
+ 安装、入口与逐步上手见 Cloud SDK 使用（文档站 /guide/sdk）。
10
11
 
11
12
  ## 获取 SDK
12
13
 
13
- SDK 是纯 ESM、零依赖的静态文件，**随应用包一起分发**，不从 npm 或 CDN 加载（应用 iframe 的 `connect-src` 是 `'none'`，也加载不了）。
14
+ SDK 是纯 ESM、零依赖的静态文件。原生模板把它放在包内 `sdk/` 随应用包分发；React 项目从 npm 安装后由构建工具打进包——两种方式都**不从 CDN 加载**。
15
+ 应用 iframe 默认把 `connect-src` 限制为 `'none'`；部署开启页面 API（`APP_PAGE_API_ENABLED`，默认关闭）后，CSP 会放开到 `<host>/api/v1/app-api/`，可以用本页的 `zl.cloud.os.api.fetch` 调 OS 普通业务接口。**外部地址仍然不可访问**。
14
16
 
15
17
  用 `zleap-app`（文档站 /guide/quickstart） 生成项目时，模板已经带好 `sdk/` 目录：
16
18
 
@@ -27,12 +29,19 @@ my-todo/
27
29
  ├── index.js / index.d.ts # zl.cloud：数据库、文件、后台调用（本页）
28
30
  ├── execution.js / files.js / values.js / protocol.js / transport.js（及 .d.ts）
29
31
  ├── workspace.js / workspace.d.ts # 工作区文件（host_api.requires: workspace.files；读图片另需 workspace.images.read）
30
- └── zleap-sdk.js / zleap-sdk.d.ts # 宿主 SDK：connectHostedApp()（剪贴板等宿主能力）
32
+ └── zleap-sdk.js / zleap-sdk.d.ts # 宿主 SDK：connectHostedApp()（kv、files、close；不含剪贴板封装）
31
33
  ```
32
34
 
33
35
  SDK 版本与 `zleap-app` 可执行文件一起发布。用 `npm create zleap-app` 生成的 React 项目改为依赖 npm 包
34
- `@zleap-web/app-sdk`：`@zleap-web/app-sdk` 对应 `sdk/index.js`，`/host` 对应 `sdk/zleap-sdk.js`，`/workspace` 对应 `sdk/workspace.js`，
35
- API 完全相同，版本与 `@zleap-web/app-cli` 保持一致。**不要**再从 `zleap-web` 源码自行构建、复制 SDK——旧文档里的做法已过时，
36
+ `@zleap-ai/app-sdk`：`@zleap-ai/app-sdk` 对应 `sdk/index.js`，`/host` 对应 `sdk/zleap-sdk.js`，`/workspace` 对应 `sdk/workspace.js`，
37
+ API 完全相同，版本与 `@zleap-ai/app-cli` 保持一致（同为 `0.10.x`）：
38
+
39
+ ```bash
40
+ npm i @zleap-ai/app-sdk
41
+ npm i -D @zleap-ai/app-cli # 两者同版本，握手协议才匹配
42
+ ```
43
+
44
+ **不要**再从 `zleap-web` 源码自行构建、复制 SDK——旧文档里的做法已过时，
36
45
  版本不匹配会在握手时报 `PROTOCOL_MISMATCH`。
37
46
 
38
47
  > **三种「存储」别混用**（提示）
@@ -70,7 +79,7 @@ const db = zl.cloud.database();
70
79
 
71
80
  > **为什么用 `DYNAMIC_CURRENT_ENV`**（提示）
72
81
  >
73
- > 数据域（dev / prod）是「部署 + 当前用户 + 应用有没有生产环境」决定的：开发数据域默认只对发布者开放；
82
+ > 数据域（dev / prod）是「部署 + 当前用户 + 应用有没有生产环境」决定的：开发数据域默认只对开发团队（`appid` 应用成员 / 旧应用上传者）开放；
74
83
  > 部署开放生产后其他使用者都用 prod，发布者本人在应用有了生产环境后也用 prod。
75
84
  > 应用自己判断不了，所以传哨兵 `DYNAMIC_CURRENT_ENV`，由宿主在握手时替你解析成具体值。
76
85
  > 写死 `'dev'` 或 `'prod'` 时，如果那不是当前对你开放的数据域，打开会话会被拒绝。
@@ -100,15 +109,16 @@ const caps = await zl.cloud.os.ready();
100
109
 
101
110
  ### Profile：决定哪些 API 能用
102
111
 
103
- 每个 API 都要求握手时协商到对应的 **profile**（能力档位），没有时调用直接抛 `UNSUPPORTED_OPERATION`。
112
+ 每个 API 都要求握手时协商到对应的 **profile**（能力档位），没有时调用直接抛错：
113
+ 数据库 / 文件相关的 profile 或操作符缺失抛 `UNSUPPORTED_OPERATION`；后台执行（`app-execution/1`）缺失抛 `BACKGROUND_CAPABILITY_UNAVAILABLE`（旧 SDK 才是 `UNSUPPORTED_OPERATION`）。
104
114
  服务端只在条件满足时下发 profile（`zleap-service/internal/services/cloudauthority/runtime_session.go`）：
105
115
 
106
- | Profile | 解锁的 API | 服务端下发条件 |
107
- | ------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
108
- | `document-core/1` | `get` / `count` / `add` / `set` / `update` / `remove` / `operations.get` | 数据库已就绪、Manifest 声明了 `data.collections`、已授予 `cloud.database.read` 或 `write` |
109
- | `watch-snapshot/1` | `watch()` | 在上一条基础上，声明并授予了 `cloud.database.read` |
110
- | `storage-object/1` | `uploadFile` / `downloadFile` / `deleteFile` / `os.files.*` | 部署启用了对象存储、授予了 `cloud.storage.read` 或 `write`；生产数据域还要求当前安装绑定了已就绪的签名发布 |
111
- | `app-execution/1` | `callFunction` / `os.capabilities` / `os.jobs` | 当前安装有已激活的后台能力授权（发布并「激活开发」，且在应用窗口「权限」里勾选了后台能力） |
116
+ | Profile | 解锁的 API | 服务端下发条件 |
117
+ | ------------------ | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
118
+ | `document-core/1` | `get` / `count` / `add` / `set` / `update` / `remove` / `operations.get` | 数据库已就绪、Manifest 的 `data.collections` 非空、已授予 `cloud.database.read` 或 `write`（`data.schemas` 可选，不写就是灵活集合） |
119
+ | `watch-snapshot/1` | `watch()` | 在上一条基础上，声明并授予了 `cloud.database.read` |
120
+ | `storage-object/1` | `uploadFile` / `downloadFile` / `deleteFile` / `os.files.*` | 部署启用了对象存储、授予了 `cloud.storage.read` 或 `write`；生产数据域还要求当前安装绑定了已就绪的签名发布 |
121
+ | `app-execution/1` | `callFunction` / `os.capabilities` / `os.jobs` | 当前安装有已激活的后台能力授权（发布并「激活开发」，且在应用窗口「权限」里勾选了后台能力）；缺失时抛 `BACKGROUND_CAPABILITY_UNAVAILABLE` |
112
122
 
113
123
  ```js
114
124
  const { profiles } = await zl.cloud.os.ready();
@@ -117,8 +127,9 @@ const canUpload = profiles.includes('storage-object/1');
117
127
 
118
128
  > **profile 没有 ≠ 你的代码写错**（注意）
119
129
  >
120
- > `UNSUPPORTED_OPERATION` 常见于「平台 / 部署未开放」或「还没开通、没授权」。先看控制台 总览（文档站 /console/overview） 的开通清单和应用窗口的「权限」，
121
- > 再怀疑代码。
130
+ > `UNSUPPORTED_OPERATION` / `BACKGROUND_CAPABILITY_UNAVAILABLE` 常见于「平台 / 部署未开放」或「还没开通、没授权」。
131
+ > 后台能力相关的 `BACKGROUND_CAPABILITY_UNAVAILABLE`，先看应用窗口的「权限」里有没有勾选后台能力；
132
+ > 数据库 / 文件相关的 `UNSUPPORTED_OPERATION`，先看控制台 总览（文档站 /console/overview） 的开通清单。再怀疑代码。
122
133
 
123
134
  ### `zl.cloud.os.getCapabilities()` / `zl.cloud.os.close()`
124
135
 
@@ -379,7 +390,10 @@ off(); // 取消订阅
379
390
 
380
391
  ### 不支持的方法
381
392
 
382
- 这些方法在类型里声明为 `never`，**调用会明确抛 `UNSUPPORTED_OPERATION`**，不会静默成功：
393
+ 这些方法目前都**不支持**，调用会明确抛 `UNSUPPORTED_OPERATION`，不会静默成功。类型声明上分两类：
394
+
395
+ - `query.after()`、`query.update()`、`query.remove()` 声明为 `never`；
396
+ - `db.runTransaction()`、`zl.cloud.getTempFileURL()` 为了兼容回调风格，声明为 `(...) => void | Promise<never>`——**调用即失败**，不要因为看到 `void` 就以为可以随便调。
383
397
 
384
398
  | 方法 | 说明 |
385
399
  | ----------------------------------- | ---------------------------------------------- |
@@ -483,13 +497,60 @@ try {
483
497
 
484
498
  文件操作的回执用 `os.files.getOperation`，**不要**用 `os.operations.get`（后者只查数据库写入）。
485
499
 
500
+ ## 页面接口 — `zl.cloud.os.api`
501
+
502
+ 应用页面可以直接调用 zleapOS 的**普通业务接口**（例如待办、文件写入），不必经过自己的数据库。它和 App Cloud 是两条独立通道：**不需要 `zl.cloud.init()`，不需要声明 `cloud.*` 能力，也不依赖 Cloud 会话**；只调用页面接口的应用安装后就能用。
503
+
504
+ > **需要部署开启，默认关闭**（注意）
505
+ >
506
+ > 页面接口由部署配置 `APP_PAGE_API_ENABLED` 控制，**默认关闭**。关闭时申请令牌会失败，网关返回 404「当前部署未开放应用接口」。
507
+ > 开启后 iframe 的 CSP 只放开到 `<host>/api/v1/app-api/`，**外部地址仍然不可访问**。
508
+
509
+ ### `zl.cloud.os.api.token()`
510
+
511
+ 返回 `Promise<{ token, baseUrl, expiresAt }>`：
512
+
513
+ ```js
514
+ const { token, baseUrl, expiresAt } = await zl.cloud.os.api.token();
515
+ // expiresAt 是秒级时间戳
516
+ ```
517
+
518
+ 返回宿主代签的短期应用令牌。一般不需要自己拿——`fetch` 会自动取用并在过期前续签；只有需要自行组装请求时才用。
519
+
520
+ ### `zl.cloud.os.api.fetch(path, init?)`
521
+
522
+ ```js
523
+ const res = await zl.cloud.os.api.fetch('/todos?page=1&page_size=20');
524
+ if (!res.ok) throw new Error(`HTTP ${res.status}`);
525
+ const body = await res.json(); // 与原接口响应相同：{ code, message, data }
526
+ // 按接口约定检查 body.code / body.message 后再使用 body.data
527
+ ```
528
+
529
+ | 规则 | 说明 |
530
+ | ---------- | -------------------------------------------------------------------------- |
531
+ | 路径基准 | 相对 `/api/v1`：`/todos` 就是 `GET /api/v1/todos` |
532
+ | 路径格式 | 必须以 `/` 开头，且不能以 `//` 开头；否则抛 `SCHEMA_INVALID` |
533
+ | 身份与权限 | 按当前使用者的权限执行；页面拿不到用户登录 token |
534
+ | 401 重试 | **只有 `GET` / `HEAD`** 在 401 时自动换新令牌重试一次；写操作不自动重试 |
535
+ | 响应 | 与原接口一致，必须同时检查 HTTP 状态和响应体里的 `code` |
536
+ | 可用接口 | 与 `os_business_search` 的目录一致；管理员、组织和平台控制类接口**不开放** |
537
+ | 不支持 | 二进制上传、二进制下载和流式响应 |
538
+ | 外部网络 | 不能请求外部地址 |
539
+
540
+ 文字内容可以用 `POST /files/write` 存成文件。写操作结果不明时，先查询确认，不要直接换请求重试；具体接口可用 `zleap-app business call` 或 MCP 的 `os_business_call` 先调试。
541
+
486
542
  ## 操作编号与回执
487
543
 
488
544
  ### `zl.cloud.os.operations.createId()`
489
545
 
490
546
  生成 `op_<10 位秒级时间戳>_<32 位十六进制>` 格式的操作编号（时间戳已按服务端时间校正）。
491
- 所有写入（`add` / `set` / `update` / `remove`、文件上传与删除、后台调用）都可以通过 `agentos.operationId`（后台调用是 `operationId`）传入；不传时 SDK 自动生成，
492
- 并在返回值 `_meta.operationId` 和错误对象 `error.operationId` 里带回来。
547
+ 所有写入都可以显式传操作编号，但**位置不同**：
548
+
549
+ - 数据库写入（`add` / `set` / `update` / `remove`）和文件上传 / 删除：传 `agentos.operationId`；
550
+ - `capabilities.invoke` / `jobs.submit`：传顶层的 `operationId`；
551
+ - `callFunction`：传 `agentos.operationId`。
552
+
553
+ 不传时 SDK 自动生成，并在返回值 `_meta.operationId` 和错误对象 `error.operationId` 里带回来。
493
554
 
494
555
  服务端规则（`zleap-service/internal/cloudplane/dataplane/scope.go`）：
495
556
 
@@ -637,28 +698,33 @@ const job = await zl.cloud.callFunction({
637
698
 
638
699
  所有失败都以 `CloudError` 抛出：
639
700
 
640
- | 字段 | 说明 |
641
- | ------------------------ | -------------------------------------------------------------------- |
642
- | `errCode` | 错误码，如 `SCOPE_FORBIDDEN` |
643
- | `errMsg` | `App Cloud: <errCode>` |
644
- | `requestId` | 请求编号 |
645
- | `operationId` | 写操作的操作编号（自动生成的也会带上） |
646
- | `retryable` | 仅 `CALL_TIMEOUT`、`RUNTIME_UNAVAILABLE`、`COMMIT_UNKNOWN` 为 `true` |
647
- | `jobId` / `invocationId` | 后台调用相关错误时存在 |
701
+ | 字段 | 说明 |
702
+ | ------------------------ | --------------------------------------------------------------------------------------------------- |
703
+ | `errCode` | 错误码，如 `SCOPE_FORBIDDEN` |
704
+ | `errMsg` | 一般是 `App Cloud: <errCode>`；个别码有更具体的中文长说明（如 `BACKGROUND_CAPABILITY_UNAVAILABLE`） |
705
+ | `requestId` | 请求编号（读 `error.requestId`，不是 `error._meta.requestId`） |
706
+ | `operationId` | 写操作的操作编号（自动生成的也会带上） |
707
+ | `retryable` | 仅 `CALL_TIMEOUT`、`RUNTIME_UNAVAILABLE`、`COMMIT_UNKNOWN` 为 `true` |
708
+ | `jobId` / `invocationId` | 后台调用相关错误时存在 |
709
+
710
+ > **`_meta.requestId` 只在成功结果里**（提示）
711
+ >
712
+ > 成功结果可能带 `_meta.requestId`；失败时用 `error.requestId`。不要用 `_meta.requestId` 去读错误。
648
713
 
649
714
  服务端原因码会被宿主归类后再交给应用，完整列表见 [状态与错误码](status-codes.md)。
650
715
 
651
716
  ### 通道层面的错误
652
717
 
653
- | 情况 | `errCode` |
654
- | ------------------------------------ | ----------------------- |
655
- | 读请求 30 秒未返回 | `CALL_TIMEOUT` |
656
- | 写请求 30 秒未返回 / 写途中通道断开 | `COMMIT_UNKNOWN` |
657
- | 同时在途请求超过 8 个 | `RESOURCE_EXHAUSTED` |
658
- | 请求体超过 256 KiB（或协商的更小值） | `REQUEST_TOO_LARGE` |
659
- | 未协商到对应 profile / 操作符 | `UNSUPPORTED_OPERATION` |
660
- | 响应结构异常 | `PROTOCOL_MISMATCH` |
661
- | 通道已关闭 | `RUNTIME_UNAVAILABLE` |
718
+ | 情况 | `errCode` |
719
+ | ------------------------------------------------------ | ------------------------------------------------------------------------ |
720
+ | 读请求 30 秒未返回 | `CALL_TIMEOUT` |
721
+ | 写请求 30 秒未返回 / 写途中通道断开 | `COMMIT_UNKNOWN` |
722
+ | 同时在途请求超过 8 个 | `RESOURCE_EXHAUSTED` |
723
+ | 请求体超过 256 KiB（或协商的更小值） | `REQUEST_TOO_LARGE` |
724
+ | 未协商到数据库 / 文件相关的 profile，或操作符不支持 | `UNSUPPORTED_OPERATION` |
725
+ | 未协商到 `app-execution/1`（没有任何已启用的后台能力） | `BACKGROUND_CAPABILITY_UNAVAILABLE`（旧 SDK 为 `UNSUPPORTED_OPERATION`） |
726
+ | 响应结构异常 | `PROTOCOL_MISMATCH` |
727
+ | 通道已关闭 | `RUNTIME_UNAVAILABLE` |
662
728
 
663
729
  ### 回调风格
664
730
 
@@ -680,18 +746,19 @@ todos.add({
680
746
 
681
747
  ## 已知限制速查
682
748
 
683
- | 项 | 限制 |
684
- | ------------------------------------------------ | --------------------------------------- |
685
- | 分页 | `limit` 1–100（默认 20），`skip` ≤ 1000 |
686
- | 排序字段 | ≤ 4 |
687
- | `watch` | `maxDocs` ≤ 100，不支持 `skip` |
688
- | 请求体 | ≤ 256 KiB |
689
- | 在途请求 | ≤ 8 |
690
- | 单次请求超时 | 30 秒；握手 15 秒 |
691
- | 操作编号 | 首次使用 300 秒窗口，回执保留 24 小时 |
692
- | 单文件 | ≤ 4 MiB |
693
- | 能力调用入参 | ≤ 64 KiB，`waitSeconds` ≤ 25 |
694
- | 事务 / 批量写 / 游标分页 / 临时 URL / 跨应用调用 | 不支持 |
749
+ | 项 | 限制 |
750
+ | ------------------------------------------------ | --------------------------------------------------------------------------- |
751
+ | 分页 | `limit` 1–100（默认 20），`skip` ≤ 1000 |
752
+ | 排序字段 | ≤ 4 |
753
+ | `watch` | `maxDocs` ≤ 100，不支持 `skip` |
754
+ | 请求体 | ≤ 256 KiB |
755
+ | 在途请求 | ≤ 8 |
756
+ | 单次请求超时 | 30 秒；握手 15 秒 |
757
+ | 操作编号 | 首次使用 300 秒窗口，回执保留 24 小时 |
758
+ | 单文件 | ≤ 4 MiB |
759
+ | 能力调用入参 | ≤ 64 KiB，`waitSeconds` ≤ 25 |
760
+ | 页面 API（`zl.cloud.os.api`） | 仅部署开启 `APP_PAGE_API_ENABLED` 时可用；不支持二进制上传 / 下载与流式响应 |
761
+ | 事务 / 批量写 / 游标分页 / 临时 URL / 跨应用调用 | 不支持 |
695
762
 
696
763
  完整数值见 [平台边界与限制](limits.md)。
697
764
 
package/skills/zleap-cloud-app/references/status-codes.md CHANGED
@@ -58,14 +58,14 @@
58
58
 
59
59
  应用里的 Cloud SDK 抛出 `CloudError`：
60
60
 
61
- | 字段 | 含义 |
62
- | ------------------------ | ---------------------------------------------------------------------- |
63
- | `errCode` | 错误码 |
64
- | `errMsg` | 固定为 `App Cloud: <errCode>`，**不含服务端的中文说明** |
65
- | `retryable` | 只有 `CALL_TIMEOUT`、`RUNTIME_UNAVAILABLE`、`COMMIT_UNKNOWN` 为 `true` |
66
- | `requestId` | 本次请求编号 |
67
- | `operationId` | 写操作的操作编号（`op_<秒级时间戳>_<32 位十六进制>`） |
68
- | `jobId` / `invocationId` | 后台调用的作业编号，可用 `jobs.get` / `jobs.wait` 继续查 |
61
+ | 字段 | 含义 |
62
+ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
63
+ | `errCode` | 错误码 |
64
+ | `errMsg` | 一般是 `App Cloud: <errCode>`，**不含服务端的中文说明**；少数由 SDK 本地判定的错误（如 `BACKGROUND_CAPABILITY_UNAVAILABLE`）带一段中文说明 |
65
+ | `retryable` | 只有 `CALL_TIMEOUT`、`RUNTIME_UNAVAILABLE`、`COMMIT_UNKNOWN` 为 `true` |
66
+ | `requestId` | 本次请求编号 |
67
+ | `operationId` | 写操作的操作编号（`op_<秒级时间戳>_<32 位十六进制>`） |
68
+ | `jobId` / `invocationId` | 后台调用的作业编号，可用 `jobs.get` / `jobs.wait` 继续查 |
69
69
 
70
70
  宿主只把服务端的 `reason` 交给应用，**不传 `message` 和 `next_action`**。要给用户看的提示文案，
71
71
  按 `errCode` 在应用里自己写（脚手架模板 `src/cloud/client.ts` 的 `describeError` 就是这样做的）。
@@ -112,35 +112,36 @@
112
112
 
113
113
  ### 通道与调用
114
114
 
115
- | 错误码 | 含义 | 可重试 | 处理 |
116
- | ----------------------- | ---------------------------------------------------- | ------ | ---------------------------------------------------------- |
117
- | `COMMIT_UNKNOWN` | **写操作结果未知**（写请求 30 秒未返回等） | ✅ | **用原 `operationId` 查回执**，确认前不要换编号重新写 |
118
- | `CALL_TIMEOUT` | 读请求 30 秒未返回 / 握手 15 秒未完成 / 作业等待超时 | ✅ | 可重试；带 `jobId` 时用 `jobs.wait` 继续等 |
119
- | `RUNTIME_UNAVAILABLE` | 通道已关闭或服务暂不可用 | ✅ | 稍后重试；页面卸载后通道不可再用 |
120
- | `APP_RATE_LIMITED` | 本应用此刻并发请求过多（单应用并发槽被占满） | ❌\* | 稍后重试；不要立刻循环重试 |
121
- | `RESOURCE_EXHAUSTED` | 超出限制（并发 >8、分页/排序/大小上限、配额） | — | 对照 [限制](limits.md) 调整；配额类需清理数据 |
122
- | `REQUEST_TOO_LARGE` | 请求体超过协商上限（默认 256 KiB） | ❌ | 拆分请求 |
123
- | `IDEMPOTENCY_CONFLICT` | 同一请求编号被重复使用，或同一操作编号用于不同内容 | ❌ | 新请求用新编号；重试同一写入时内容必须完全相同 |
124
- | `OPERATION_EXPIRED` | 操作编号超出首次使用窗口（300 秒）或回执已过期 | ❌ | 重新读取最新状态后，用新编号发起 |
125
- | `PROTOCOL_MISMATCH` | SDK 与宿主协议不一致，或响应结构异常 | ❌ | 使用与当前 OS 匹配的 SDK 版本 |
126
- | `UNSUPPORTED_OPERATION` | 平台未实现或未协商的操作 | ❌ | 改实现，见 [未实现的 SDK 功能](limits.md#未实现的-sdk-功能) |
115
+ | 错误码 | 含义 | 可重试 | 处理 |
116
+ | ----------------------------------- | --------------------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
117
+ | `COMMIT_UNKNOWN` | **写操作结果未知**（写请求 30 秒未返回等） | ✅ | **用原 `operationId` 查回执**，确认前不要换编号重新写 |
118
+ | `CALL_TIMEOUT` | 读请求 30 秒未返回 / 握手 15 秒未完成 / 作业等待超时 | ✅ | 可重试；带 `jobId` 时用 `jobs.wait` 继续等 |
119
+ | `RUNTIME_UNAVAILABLE` | 通道已关闭或服务暂不可用 | ✅ | 稍后重试；页面卸载后通道不可再用 |
120
+ | `APP_RATE_LIMITED` | 本应用此刻并发请求过多（单应用并发槽被占满） | ❌\* | 稍后重试；不要立刻循环重试 |
121
+ | `RESOURCE_EXHAUSTED` | 超出限制（并发 >8、分页/排序/大小上限、配额） | — | 对照 [限制](limits.md) 调整；配额类需清理数据 |
122
+ | `REQUEST_TOO_LARGE` | 请求体超过协商上限（默认 256 KiB） | ❌ | 拆分请求 |
123
+ | `IDEMPOTENCY_CONFLICT` | 同一请求编号被重复使用，或同一操作编号用于不同内容 | ❌ | 新请求用新编号；重试同一写入时内容必须完全相同 |
124
+ | `OPERATION_EXPIRED` | 操作编号超出首次使用窗口（300 秒）或回执已过期 | ❌ | 重新读取最新状态后，用新编号发起 |
125
+ | `PROTOCOL_MISMATCH` | SDK 与宿主协议不一致，或响应结构异常 | ❌ | 使用与当前 OS 匹配的 SDK 版本 |
126
+ | `BACKGROUND_CAPABILITY_UNAVAILABLE` | 宿主没有协商到 `app-execution/1`，`callFunction` / `capabilities.invoke` 无法执行 | ❌ | 先让使用者在应用窗口「权限」里勾选后台能力并保存；确认版本已签发并激活、部署开放后台执行。旧 SDK 报的是 `UNSUPPORTED_OPERATION`，升级 SDK |
127
+ | `UNSUPPORTED_OPERATION` | 平台未实现或未协商的操作 | ❌ | 改实现，见 [未实现的 SDK 功能](limits.md#未实现的-sdk-功能) |
127
128
 
128
129
  \* `retryable` 为 `false`，但稍等后重试通常能成功；持续出现说明有长任务占满了并发。
129
130
 
130
131
  ### 初始化与授权
131
132
 
132
- | 错误码 | 含义 | 处理 |
133
- | ---------------------- | ------------------------------------------------------------ | ------------------------------------------------------- |
134
- | `INIT_REQUIRED` | 调用 `ready()` 前没有 `zl.cloud.init()` | 先初始化 |
135
- | `INIT_CONFLICT` | 同一页面用不同环境再次初始化 | 一个页面只绑定一个环境 |
136
- | `ENV_MISMATCH` | `env` 取值非法 | 只能是 `dev` / `prod`（或 `DYNAMIC_CURRENT_ENV`） |
137
- | `AUTH_REQUIRED` | 登录态或运行会话失效 | 重新打开应用 |
138
- | `SCOPE_FORBIDDEN` | 权限范围不允许（含未授权数据访问、生产文件存储未开放） | 见本页末尾「排查：`SCOPE_FORBIDDEN`」 |
139
- | `ENV_FORBIDDEN` | 应用要用的环境不存在或已停用 | 见下方「打开应用时的错误」 |
140
- | `PUBLISHER_REQUIRED` | 开发数据域只对发布者本人开放 | 用发布者账号；给其他人用需要上线到生产 |
141
- | `STALE_GENERATION` | 授权或数据绑定已换代（如重新授权、恢复备份） | 重新打开应用，建立新会话 |
142
- | `RULE_DENIED` | 集合记录规则拒绝了本次读/写 | 检查 `data.policies` 的 `read`/`write` 表达式与文档内容 |
143
- | `QUERY_NOT_AUTHORIZED` | 查询不在授权范围内（宿主白名单中的码，服务端来源**未验证**） | 检查查询条件与授权 |
133
+ | 错误码 | 含义 | 处理 |
134
+ | ---------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------- |
135
+ | `INIT_REQUIRED` | 调用 `ready()` 前没有 `zl.cloud.init()` | 先初始化 |
136
+ | `INIT_CONFLICT` | 同一页面用不同环境再次初始化 | 一个页面只绑定一个环境 |
137
+ | `ENV_MISMATCH` | `env` 取值非法 | 只能是 `dev` / `prod`（或 `DYNAMIC_CURRENT_ENV`） |
138
+ | `AUTH_REQUIRED` | 登录态或运行会话失效 | 重新打开应用 |
139
+ | `SCOPE_FORBIDDEN` | 权限范围不允许（含未授权数据访问、生产文件存储未开放） | 见本页末尾「排查：`SCOPE_FORBIDDEN`」 |
140
+ | `ENV_FORBIDDEN` | 应用要用的环境不存在或已停用 | 见下方「打开应用时的错误」 |
141
+ | `PUBLISHER_REQUIRED` | 开发数据域只对开发团队开放（`appid` 应用成员 / 旧应用该版本上传者） | 请管理员在控制台「成员」里把你加为开发者；给其他人用需要发布为线上版本 |
142
+ | `STALE_GENERATION` | 授权或数据绑定已换代（如重新授权、恢复备份） | 重新打开应用，建立新会话 |
143
+ | `RULE_DENIED` | 集合记录规则拒绝了本次读/写 | 检查 `data.policies` 的 `read`/`write` 表达式与文档内容 |
144
+ | `QUERY_NOT_AUTHORIZED` | 查询不在授权范围内（宿主白名单中的码，服务端来源**未验证**） | 检查查询条件与授权 |
144
145
 
145
146
  ### 数据
146
147
 
@@ -163,17 +164,17 @@
163
164
 
164
165
  ### 发布与后台调用
165
166
 
166
- | 错误码 | 含义 | 处理 |
167
- | ----------------------------------- | -------------------------------------------------- | ------------------------------------------------------ |
168
- | `FUNCTION_RELEASE_REQUIRED` | 当前安装还没有绑定已签发并激活的发布 | 在控制台「发布版本」签发并激活 |
169
- | `RELEASE_UNAVAILABLE` | 发布代数已变化（激活了新版本），旧会话作废 | 宿主会自动重开会话并重试一次；仍失败时重新打开应用 |
170
- | `RELEASE_NOT_READY` | 发布候选尚未就绪 | 先完成签发 |
171
- | `RELEASE_DISABLED` | 发布候选已撤回 | 使用其他就绪候选 |
172
- | `RELEASE_ACTIVATION_UNAVAILABLE` | 目标环境不存在且无法自动创建 | 见 [发布与激活](#发布与激活) |
173
- | `RELEASE_ACTIVATION_TARGET_MISSING` | 激活目标与校验后的 Manifest 不一致（少见） | 见 [发布与激活](#发布与激活) |
174
- | `NODE_LOST` | 执行节点失联，**结果未确认**（作业状态 `unknown`） | 不要重复提交；用 `jobId` / `invocationId` 核对 |
175
- | `NODE_LOST_EXPIRED` | 节点失联且超过对账期限 | 到控制台运行记录核对是否已产生写入，再决定是否重新提交 |
176
- | `EXECUTION_FAILED` | `callFunction` 作业失败且没有更具体的错误码 | 到控制台运行记录或日志查看失败原因 |
167
+ | 错误码 | 含义 | 处理 |
168
+ | ----------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
169
+ | `FUNCTION_RELEASE_REQUIRED` | 当前安装还没有绑定已签发并激活的发布 | 在控制台版本页签发并激活（`appid` 应用：版本管理 → 开发环境：云函数激活） |
170
+ | `RELEASE_UNAVAILABLE` | 发布代数已变化（激活了新版本），旧会话作废 | 宿主会自动重开会话并重试一次；仍失败时重新打开应用 |
171
+ | `RELEASE_NOT_READY` | 发布候选尚未就绪 | 先完成签发 |
172
+ | `RELEASE_DISABLED` | 发布候选已撤回 | 使用其他就绪候选 |
173
+ | `RELEASE_ACTIVATION_UNAVAILABLE` | 目标环境不存在且无法自动创建 | 见 [发布与激活](#发布与激活) |
174
+ | `RELEASE_ACTIVATION_TARGET_MISSING` | 激活目标与校验后的 Manifest 不一致（少见） | 见 [发布与激活](#发布与激活) |
175
+ | `NODE_LOST` | 执行节点失联，**结果未确认**（作业状态 `unknown`） | 不要重复提交；用 `jobId` / `invocationId` 核对 |
176
+ | `NODE_LOST_EXPIRED` | 节点失联且超过对账期限 | 到控制台运行记录核对是否已产生写入，再决定是否重新提交 |
177
+ | `EXECUTION_FAILED` | `callFunction` 作业失败且没有更具体的错误码 | 到控制台运行记录或日志查看失败原因 |
177
178
 
178
179
  `callFunction` 失败时，`errCode` 优先使用作业结果里的 `errorCode`；作业状态为 `unknown` 时抛 `COMMIT_UNKNOWN`，
179
180
  仍在排队/执行时抛 `CALL_TIMEOUT`（都带 `jobId`，可用 `jobs.wait` 继续等）。`capabilities.invoke` 不抛错，
@@ -184,19 +185,19 @@
184
185
  `zl.app`（更新管理器）和 `zl.auth`（授权登录）失败时抛出的是 `AppError`（不是 `CloudError`），只有 `errCode` 和 `message`。
185
186
  详见 [版本更新与授权登录](app-runtime.md#错误码)。
186
187
 
187
- | errCode | 含义 | 处理 |
188
- | ----------------------- | ------------------------------------------------------------ | -------------------------------------- |
189
- | `AUTH_DENIED` | 用户在系统授权框里点了「拒绝」，或 24 小时内拒绝过这些项 | 按未授权处理，等用户主动操作时再申请 |
190
- | `AUTH_IN_PROGRESS` | 授权框已打开，又发起了一次 `authorize` | 等上一次结果 |
191
- | `AUTH_GESTURE_REQUIRED` | 需要弹授权框，但不是在用户点击 / 按键之后调用 | 放到按钮点击事件里调用 |
192
- | `AUTH_SCOPE_UNDECLARED` | 申请了 Manifest `host_api.requires` 没声明的 `user.*` | 补上声明，重新上传 |
193
- | `SCHEMA_INVALID` | `scopes` 为空或含其他值，或 `reason` 超过 60 字 | 改代码 |
194
- | `OPEN_IN_ZLEAP_OS` | 不在 zleapOS 窗口里打开 | 部署后从启动台打开 |
195
- | `HOST_UNAVAILABLE` | 宿主 15 秒内没有响应 | 升级 zleapOS 后重试 |
196
- | `RUNTIME_UNAVAILABLE` | 通道已关闭或平台接口暂不可用 | 稍后重试；仍失败时重新打开应用 |
197
- | `CALL_TIMEOUT` | 调用超时 | 可以重试 |
198
- | `UPDATE_FAILED` | `applyUpdate()` 切换失败 | 提示用户重新打开应用或到应用中心更新 |
199
- | `UNSUPPORTED_OPERATION` | 宿主不支持这个方法 | 升级 zleapOS |
188
+ | errCode | 含义 | 处理 |
189
+ | ----------------------- | -------------------------------------------------------- | ------------------------------------ |
190
+ | `AUTH_DENIED` | 用户在系统授权框里点了「拒绝」，或 24 小时内拒绝过这些项 | 按未授权处理，等用户主动操作时再申请 |
191
+ | `AUTH_IN_PROGRESS` | 授权框已打开，又发起了一次 `authorize` | 等上一次结果 |
192
+ | `AUTH_GESTURE_REQUIRED` | 需要弹授权框，但不是在用户点击 / 按键之后调用 | 放到按钮点击事件里调用 |
193
+ | `AUTH_SCOPE_UNDECLARED` | 申请了 Manifest `host_api.requires` 没声明的 `user.*` | 补上声明，重新上传 |
194
+ | `SCHEMA_INVALID` | `scopes` 为空或含其他值，或 `reason` 超过 60 字 | 改代码 |
195
+ | `OPEN_IN_ZLEAP_OS` | 不在 zleapOS 窗口里打开 | 部署后从启动台打开 |
196
+ | `HOST_UNAVAILABLE` | 宿主 15 秒内没有响应 | 升级 zleapOS 后重试 |
197
+ | `RUNTIME_UNAVAILABLE` | 通道已关闭或平台接口暂不可用 | 稍后重试；仍失败时重新打开应用 |
198
+ | `CALL_TIMEOUT` | 调用超时 | 可以重试 |
199
+ | `UPDATE_FAILED` | `applyUpdate()` 切换失败 | 提示用户重新打开应用或到应用中心更新 |
200
+ | `UNSUPPORTED_OPERATION` | 宿主不支持这个方法 | 升级 zleapOS |
200
201
 
201
202
  ## 打开应用时的错误
202
203
 
@@ -400,19 +401,29 @@
400
401
  ```
401
402
 
402
403
  `next_action`、`reason` 都在 `detail=` 的 JSON 里。退出码：结果未知（输出含 `COMMIT_UNKNOWN`）为 **6**，其他错误为 **2**；
403
- 通过 npm 包 `@zleap-web/app-cli` 运行但本机缺少对应平台的二进制时为 **127**。MCP 工具出错时返回 `isError: true`，
404
+ 通过 npm 包 `@zleap-ai/app-cli` 运行但本机缺少对应平台的二进制时为 **127**。MCP 工具出错时返回 `isError: true`，
404
405
  内容是 `{"status": "failed" | "unknown" | "unconfirmed", "message": "平台错误 …"}`。
405
406
 
406
407
  `zleap-app prepare` 的特殊结果：
407
408
 
408
- - 应用没有声明云资源（无 `cloud.*` 权限、无后台能力、无集合）时直接成功，`status` 为 **`not_required`**，
409
+ - **平台 `appid` 应用**只准备开发环境：只声明数据的应用在开发权限阶段后结束，`status` 为 **`ready`**，响应里 `"environment": "dev"`；
410
+ Manifest 声明了 headless 后台能力时，还会创建发布候选、签名并激活到开发。
411
+ - **旧 `app_key` 应用**没有声明云资源（无 `cloud.*` 权限、无后台能力、无集合）时直接返回 `status` 为 **`not_required`**，
409
412
  `next` 提示「应用未声明云资源或后台执行，安装后即可运行」。
410
413
  - 某个阶段失败时，`data` 里带 `stage`（失败的阶段）、`completed_stages`（已完成的阶段）、`cause.reason`（原因码）、
411
414
  `next`（「用app_diagnose核对当前状态；不自动重试准备写操作」），内层错误有 `next_action` 时也一并带上。
412
415
  用**同一个** `--request-id` 重试会从失败的阶段继续。
413
416
  - 其他失败：42200「version_id和32位小写十六进制request_id必填」、40900「请先安装指定版本」、
414
- 40300「只能准备本人private应用」、42200「应用执行或共享调度未启用，需要平台管理员完成部署」、
415
- 40900「准备结果未确认，请先诊断」。不传 `--request-id` 时命令行会自动生成。
417
+ 40300「只能准备本人private应用」（旧应用）、40300「只能准备本人上传的版本」（`appid` 应用传了别人上传的 `version_id`）、
418
+ 42200「应用执行或共享调度未启用，需要平台管理员完成部署」、40900「准备结果未确认，请先诊断」。不传 `--request-id` 时命令行会自动生成。
419
+
420
+ > **`prepare` 支持哪些版本**（说明）
421
+ >
422
+ >
423
+ > - **平台 `appid` 应用**：接受**本人上传**的版本（可见性 `private` 或 `members`），只准备开发环境
424
+ > （开发环境 → 数据库 → 开发数据域权限，声明了 headless 时再加签名并激活到开发），不会碰生产；
425
+ > 生产由**首次 `release`（发布为线上版本）**自动准备。声明了 headless 时，它等同于控制台「版本管理」下方「**开发环境：云函数激活**」。
426
+ > - **旧 `app_key` 应用**：只接受**本人 private、且已安装**的包，一路准备到生产。
416
427
 
417
428
  `zleap-app publish` 等写操作网络结果不明时返回 `COMMIT_UNKNOWN`，**不会自动重传**：
418
429
  用 `zleap-app operation --request-id <原操作号>` 或 `zleap-app status` 查询原结果。
@@ -421,58 +432,76 @@
421
432
 
422
433
  上传、`zleap-app check` 或安装时，Manifest 相关失败通过 `detail.reason` 返回：
423
434
 
424
- | 原因 | 含义 | 处理 |
425
- | ----------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------- |
435
+ | 原因 | 含义 | 处理 |
436
+ | ----------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------- |
426
437
  | `MANIFEST_UNSUPPORTED` | `schema` 不是 `zleap.app/2`、结构/引用/执行形态无效，或 `appid` 与 `app_key` 不一致 | 对照 [Manifest](manifest.md) 逐字段核对 |
427
- | `SCHEMA_INVALID` | 集合 Schema 不符合数据面契约（`detail.collection` 指出集合） | 只用集合 Schema 子集 |
428
- | `RULE_DENIED` | 集合记录规则表达式无效 | 修正表达式 |
429
- | `RULE_FIELD_UNDECLARED` | 记录规则引用了 Schema 未声明的字段 | 在 Schema 顶层声明该字段 |
430
- | `RUNTIME_UNAVAILABLE` | 运行环境未开放（`builtin` UI、纯后台带函数等） | 见 [不可安装的配置](limits.md#已知会导致「应用不可安装」的配置) |
431
- | `FEATURE_UNAVAILABLE` | 声明了未开放的能力或写法 | 同上 |
438
+ | `SCHEMA_INVALID` | 集合 Schema 不符合数据面契约（`detail.collection` 指出集合） | 只用集合 Schema 子集 |
439
+ | `RULE_DENIED` | 集合记录规则表达式无效 | 修正表达式 |
440
+ | `RULE_FIELD_UNDECLARED` | 记录规则引用了 Schema 未声明的字段 | 在 Schema 顶层声明该字段 |
441
+ | `RUNTIME_UNAVAILABLE` | 运行环境未开放（`builtin` UI、纯后台带函数等） | 见 [不可安装的配置](limits.md#已知会导致「应用不可安装」的配置) |
442
+ | `FEATURE_UNAVAILABLE` | 声明了未开放的能力或写法 | 同上 |
432
443
 
433
444
  常见的上传失败文案（没有原因码，直接看提示）：
434
445
 
435
- | 提示 | 原因 |
436
- | ----------------------------------------------------- | --------------------------------------------------- |
437
- | 应用包根目录必须包含非空 LICENSE 文件 | 缺少 `LICENSE` 或内容为空 |
438
- | manifest entry 必须指向存在的包内 HTML 文件 | `entry` 不是包内 `.html`/`.htm`，或文件不存在 |
446
+ | 提示 | 原因 |
447
+ | ----------------------------------------------------- | ----------------------------------------------------------------- |
448
+ | 应用包根目录必须包含非空 LICENSE 文件 | 缺少 `LICENSE` 或内容为空 |
449
+ | manifest entry 必须指向存在的包内 HTML 文件 | `entry` 不是包内 `.html`/`.htm`，或文件不存在 |
439
450
  | manifest 的 appid 与 app_key 不一致 | 同时写了 `appid` 和 `app_key` 且两者不同（42200），只保留 `appid` |
440
- | manifest app_key 必须使用包含发布者前缀的小写命名空间 | 应用标识既不是平台 `appid`，也不符合旧 `app_key` 命名空间规则 |
441
- | 发布者声明不属于当前登录用户 | 仅旧 `app_key` 应用：`publisher.publisher_id` 不是上传者本人 |
442
- | 不能覆盖其他发布者的应用标识 | 仅旧 `app_key` 应用：`app_key` 已被别人使用 |
443
- | 该版本已经存在，请更换版本号 | 同版本号、内容不同 |
444
- | 云函数制品入口缺失 | 函数 `entry` 在包里不存在 |
445
- | 应用包不在开发会话授权范围 | 包里的 `appid` 与 `zleap-app auth login` 时不一致 |
451
+ | manifest app_key 必须使用包含发布者前缀的小写命名空间 | 应用标识既不是平台 `appid`，也不符合旧 `app_key` 命名空间规则 |
452
+ | 发布者声明不属于当前登录用户 | 仅旧 `app_key` 应用：`publisher.publisher_id` 不是上传者本人 |
453
+ | 不能覆盖其他发布者的应用标识 | 仅旧 `app_key` 应用：`app_key` 已被别人使用 |
454
+ | 该版本已经存在，请更换版本号 | 同版本号、内容不同 |
455
+ | 云函数制品入口缺失 | 函数 `entry` 在包里不存在 |
456
+ | 应用包不在开发会话授权范围 | 包里的 `appid` 与 `zleap-app auth login` 时不一致 |
446
457
 
447
458
  ### 应用与成员
448
459
 
449
460
  用 `appid` 的应用，上传和成员管理按应用成员判权：
450
461
 
451
- | 业务码 | message | `detail.reason` | 处理（`next_action`） |
452
- | ------ | -------------------------------- | ---------------- | -------------------------------------------------------------- |
453
- | 40400 | appid 不存在 | `APP_NOT_FOUND` | 先在云开发控制台「创建应用」 |
454
- | 40300 | 你不是这个应用的开发者 | `NOT_APP_MEMBER` | 请联系应用管理员在云开发控制台「成员」里把你加为开发者 |
455
- | 40300 | 只有应用管理员可以管理成员 | — | 请管理员添加、移除成员或修改角色 |
456
- | 40900 | 应用至少要保留一位管理员 | — | 先把另一位成员设为管理员，再做这个操作 |
462
+ | 业务码 | message | `detail.reason` | 处理（`next_action`） |
463
+ | ------ | -------------------------- | ---------------- | ------------------------------------------------------ |
464
+ | 40400 | appid 不存在 | `APP_NOT_FOUND` | 先在云开发控制台「创建应用」 |
465
+ | 40300 | 你不是这个应用的开发者 | `NOT_APP_MEMBER` | 请联系应用管理员在云开发控制台「成员」里把你加为开发者 |
466
+ | 40300 | 只有应用管理员可以管理成员 | — | 请管理员添加、移除成员或修改角色 |
467
+ | 40900 | 应用至少要保留一位管理员 | — | 先把另一位成员设为管理员，再做这个操作 |
457
468
 
458
469
  成员管理见 [成员管理](console-members.md)。
459
470
 
460
- ### 发布为线上版本
471
+ ### 发布为线上版本与目录可见性
461
472
 
462
- 控制台「版本管理」发布或回退时（`POST /api/v1/app-cloud/apps/{app_id}/publish`）：
473
+ 控制台「版本管理」发布 / 回退（`POST /api/v1/app-cloud/apps/{app_id}/publish`），以及应用中心「发布到企业目录 / 撤回企业目录」：
463
474
 
464
- | 业务码 | message | `detail.reason` | 处理（`next_action`） |
465
- | ------ | ------------------------------------------------------------------ | ------------------------- | ---------------------------------------------------------------------- |
466
- | 40900 | 发布带云资源的版本前，上传者需要正在使用这个版本 | `UPLOADER_NOT_ON_VERSION` | 请上传者打开应用并切换到这个版本（npm run deploy 会自动切换），再发布 |
467
- | 40900 | 该应用使用旧的命名空间标识，请在「版本与激活」里管理版本 | `LEGACY_APP` | 旧 `app_key` 应用走「版本与激活」 |
468
- | 40400 | 版本不存在或已删除 / 该版本没有可用制品 | — | 刷新版本列表后重试 |
469
- | 42200 | 发布说明最多 500 字 | — | 缩短发布说明 |
470
- | 40400 | 应用不存在，或你不是这个应用的成员 | — | 请联系应用管理员在云开发控制台「成员」里把你加为开发者 |
475
+ | 业务码 | message | `detail.reason` | 处理（`next_action`） |
476
+ | ------ | -------------------------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------ |
477
+ | 40900 | 发布带云资源的版本前，上传者需要正在使用这个版本 | `UPLOADER_NOT_ON_VERSION` | 请上传者打开应用并切换到这个版本（npm run deploy 会自动切换），再发布 |
478
+ | 40900 | 这个应用请在云开发控制台「版本管理」里发布或回退 | `USE_VERSION_MANAGEMENT` | 应用中心不能改平台 `appid` 应用的线上版本；到控制台「发布 → 版本管理」点「发布为线上版本」或「回退到此版本」 |
479
+ | 40900 | 该应用使用旧的命名空间标识，请在「版本与激活」里管理版本 | `LEGACY_APP` | 旧 `app_key` 应用走「版本与激活」 |
480
+ | 40400 | 版本不存在或已删除 / 该版本没有可用制品 | — | 刷新版本列表后重试 |
481
+ | 42200 | 发布说明最多 500 字 | — | 缩短发布说明 |
482
+ | 40400 | 应用不存在，或你不是这个应用的成员 | — | 请联系应用管理员在云开发控制台「成员」里把你加为开发者 |
471
483
 
472
- `UPLOADER_NOT_ON_VERSION` 只出现在带云资源（集合、`cloud.*` 能力、`runtime.backend` 或 headless 能力）的版本上，见 版本管理 · 带云资源的版本（文档站 /console/release#带云资源的版本）。
484
+ `USE_VERSION_MANAGEMENT` 来自应用中心的「发布到企业目录 / 撤回企业目录」接口，不是版本管理接口本身的错误；
485
+ 它表示**这个应用不该在应用中心改线上状态**。平台 `appid` 应用请改用控制台「版本管理」。
486
+
487
+ `UPLOADER_NOT_ON_VERSION` 只出现在带云资源（集合、`cloud.*` 能力、`runtime.backend` 或 headless 能力）的版本上，且只在**第一次发布**时要求；已经发布过的版本再次发布会复用生产准备。见 版本管理 · 带云资源的版本（文档站 /console/release#带云资源的版本）。
473
488
 
474
489
  ## 版本更新与回滚
475
490
 
491
+ ### 版本切换（控制台「我也用这个」/ CLI `update`、`rollback`）
492
+
493
+ 这些码来自安装版本切换接口（`appversion/read.go`、`official.go`、`apply.go`）：
494
+
495
+ | 业务码 | message | `detail.reason` | 处理 |
496
+ | ------ | -------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
497
+ | 42200 | 应用没有可切换的版本 | `VERSION_LIST_EMPTY` | 该应用还没有任何有效版本，或你的账号看不到任何版本；先在控制台的版本页确认已有上传（`appid`：版本管理；旧应用：版本与激活），再刷新 |
498
+ | 42200 | 官方版本切换必须指定当前安装版本 | `EXPECTED_VERSION_REQUIRED` | 请求里带上当前安装的版本 ID（CLI 用 `--expected-version-id`），不要省略 |
499
+ | 40900 | 安装版本已变化 | `INSTALLATION_VERSION_STALE` | 你带来的「当前版本」与安装记录不一致；重新读取安装状态后，用最新的版本 ID 再操作 |
500
+ | 40900 | 安装版本已变化 | `INSTALLATION_VERSION_CHANGED` | 提交期间安装被其他操作改掉了；刷新后重新读取，再决定是否重试 |
501
+
502
+ `INSTALLATION_VERSION_STALE` 在写入前检查就失败；`INSTALLATION_VERSION_CHANGED` 是写入时的并发校验失败（CAS 没命中）。
503
+ 两者都**不要用旧的版本 ID 盲目重试**，先 `zleap-app diagnose` 或在控制台刷新安装状态。
504
+
476
505
  ### 应用中心「更新」的预检
477
506
 
478
507
  | 原因码 | 级别 | 界面文案 |
@@ -485,6 +514,9 @@
485
514
  | `CONTINUITY_UNKNOWN` | 提醒 | 旧版本清单不可解析，本次升级将撤销全部后台能力授权。 |
486
515
  | `DATA_DELTA_UNKNOWN` | 提醒 | 数据声明无法比对，请人工确认集合变更。 |
487
516
 
517
+ `VERSION_NOT_AVAILABLE` 不在这张预检表里：它是「更新」页读取可切换版本列表时的**前端阻断**（`upgrade-model.ts`），
518
+ 表示目标版本不在当前账号可见的版本列表里，界面文案为「该版本当前不可切换（可能已下架或不可见）。」
519
+
488
520
  > **预检阻断只是提示**（注意）
489
521
  >
490
522
  > 实测预检返回「阻断」（`can_upgrade: false`）时，直接调用升级接口仍会执行。应用中心界面会按预检拦住，
@@ -503,7 +535,7 @@
503
535
 
504
536
  ## 签名证明验证
505
537
 
506
- 在控制台「发布版本」验证签名证明时，失败按原因码归类显示：
538
+ 在控制台版本页（`appid` 应用是「版本管理」，旧 `app_key` 应用是「版本与激活」）验证签名证明时，失败按原因码归类显示：
507
539
 
508
540
  | 服务端原因码 | 界面文案 |
509
541
  | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |