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/limits.md CHANGED
@@ -14,36 +14,37 @@
14
14
 
15
15
  ## 能力开放状态
16
16
 
17
- | 能力 | 状态 | 说明 |
18
- | --------------------------------- | ------------- | ----------------------------------------------------------- |
19
- | 云数据库 | ✅ 开放 | 集合按 Manifest 自动创建；文档、索引、备份恢复 |
20
- | 文件存储 | ✅ 开放 | 分块上传、下载、条件覆盖、软删除 |
21
- | 日志 | ✅ 开放 | 查询 + 追尾；生产环境只读，发布者可见全部调用日志 |
22
- | 云函数 / 后台能力 | ⚠️ 视部署而定 | 需要部署了函数运行环境；还需签名发布、激活并授权 |
23
- | 发布版本 · 发布候选、签名验证 | ✅ 开放 | 签名需部署配置发布信任策略，否则报「发布信任策略尚未配置…」 |
24
- | 发布版本 · 激活开发 | ✅ 开放 | 把已就绪候选绑定到当前安装的开发环境 |
25
- | 发布版本 · 激活到生产 | ⚠️ 视部署而定 | 发布信任配置未就绪时控制台没有生产入口；开放后需通过生产门禁 |
26
- | 生产环境数据 / 文件管理（控制台） | ⚠️ 视部署而定 | 生产开放后可在控制台查看和修改（页面有影响范围提示） |
27
- | 应用中心 · 更新 / 回滚 | ✅ 开放 | 有升级预检；只切换当前用户自己的安装 |
28
- | 应用中心 · 企业目录上架 | ✅ 开放 | 无审核步骤，见 上传与发布（文档站 /app-center/publish） |
29
- | 应用成员（管理员 / 开发者） | ✅ 开放 | 控制台「团队」→「成员」，见 [成员管理](console-members.md) |
30
- | 运行 / 切换其他成员的开发版本 | ❌ 未开放 | 每个成员只能使用自己上传的版本 |
31
- | 「版本与激活」查看其他成员的发布 | ❌ 未开放 | 只列出你本人上传的版本对应的发布 |
32
- | 纯后台（`headless`）应用 | ❌ 基本不可用 | 声明云函数等即「运行环境未开放」，请用 `both` |
33
- | `agent.interaction` | ❌ 未开放 | 声明会导致应用无法安装 |
34
- | 集合分区 `app` | ❌ 未开放 | Manifest 写 `partition: "app"` 会被拒绝 |
17
+ | 能力 | 状态 | 说明 |
18
+ | -------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------- |
19
+ | 云数据库 | ✅ 开放 | 集合按 Manifest 自动创建；文档、索引、备份恢复 |
20
+ | 文件存储 | ✅ 开放 | 分块上传、下载、条件覆盖、软删除 |
21
+ | 日志 | ✅ 开放 | 查询 + 追尾；生产环境只读，发布者可见全部调用日志 |
22
+ | 云函数 / 后台能力 | ⚠️ 视部署而定 | 需要部署了函数运行环境；还需签名发布、激活并授权 |
23
+ | 控制台版本页 · 发布候选、签名验证 | ✅ 开放 | `appid` 应用在「版本管理」，旧 `app_key` 应用在「版本与激活」；签名需部署配置发布信任策略，否则报「发布信任策略尚未配置…」 |
24
+ | 控制台版本页 · 激活开发 | ✅ 开放 | 把已就绪候选绑定到当前安装的开发环境 |
25
+ | 控制台版本页 · 激活到生产 | ⚠️ 视部署而定 | `appid` 应用首次「发布为线上版本」会自动准备生产；发布信任配置未就绪时控制台没有生产入口，开放后需通过生产门禁 |
26
+ | 生产环境数据 / 文件管理（控制台） | ⚠️ 视部署而定 | 生产开放后可在控制台查看和修改（页面有影响范围提示） |
27
+ | 应用中心 · 更新 / 回滚 | ✅ 开放 | 有升级预检；只切换当前用户自己的安装 |
28
+ | 应用中心 · 企业目录上架（旧应用） | ✅ 开放 | 仅旧 `app_key` 应用；无审核步骤，见 上传与发布（文档站 /app-center/publish） |
29
+ | 控制台 · 发布为线上版本（`appid`） | ✅ 开放 | 控制台「发布 → 版本管理」；发布后全企业可见，无审核步骤 |
30
+ | 应用成员（管理员 / 开发者） | ✅ 开放 | 控制台「团队」→「成员」，见 [成员管理](console-members.md) |
31
+ | 使用其他成员上传的开发版本（`appid`） | ✅ 开放 | 版本可见性为 `members`；成员在「版本管理」里用「我也用这个」切换 |
32
+ | 旧 `app_key` 应用使用别人上传的 private 版本 | ❌ 未开放 | private 版本只有上传者本人能安装；其他人只能安装企业可见版本 |
33
+ | 纯后台（`headless`）应用 | ❌ 基本不可用 | 声明云函数等即「运行环境未开放」，请用 `both` |
34
+ | `agent.interaction` | ❌ 未开放 | 声明会导致应用无法安装 |
35
+ | 集合分区 `app` | ❌ 未开放 | Manifest 写 `partition: "app"` 会被拒绝 |
35
36
 
36
37
  ## 未实现的 SDK 功能
37
38
 
38
- 以下调用会**明确抛出** `UNSUPPORTED_OPERATION`，不会静默失败：
39
+ 以下调用会**明确抛出**错误（一般是 `UNSUPPORTED_OPERATION`；宿主没协商到 `app-execution/1` 时是 `BACKGROUND_CAPABILITY_UNAVAILABLE`），不会静默失败：
39
40
 
40
- | 功能 | 说明 |
41
- | ------------------------------------------------ | ------------------------ |
42
- | 数据库事务 `runTransaction()` | 不支持 |
43
- | 按条件批量写 `where(...).update()` / `.remove()` | 只能按文档逐条写 |
44
- | 游标分页 `query.after()` | 用 `skip` + `limit` 分页 |
45
- | 临时文件链接 `getTempFileURL()` | 用 `downloadFile()` |
46
- | 握手未声明的协议 profile 或运算符 | 宿主未协商的能力 |
41
+ | 功能 | 说明 |
42
+ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
43
+ | 数据库事务 `runTransaction()` | 不支持 |
44
+ | 按条件批量写 `where(...).update()` / `.remove()` | 只能按文档逐条写 |
45
+ | 游标分页 `query.after()` | 用 `skip` + `limit` 分页 |
46
+ | 临时文件链接 `getTempFileURL()` | 用 `downloadFile()` |
47
+ | 握手未声明的协议 profile 或运算符 | 宿主未协商的能力；`app-execution/1` 缺失时 `callFunction` / `capabilities.invoke` 抛 `BACKGROUND_CAPABILITY_UNAVAILABLE`，其余情况抛 `UNSUPPORTED_OPERATION` |
47
48
 
48
49
  另外，iframe 内的 SDK **不能跨应用调用**其他应用的能力。
49
50
 
@@ -66,15 +67,15 @@
66
67
 
67
68
  ### Manifest
68
69
 
69
- | 项 | 限制 |
70
- | ------------- | --------------------- |
71
- | 嵌套深度 | ≤ **24** |
72
- | 节点总数 | ≤ **16384** |
70
+ | 项 | 限制 |
71
+ | ------------- | ------------------------------------------------------------------------- |
72
+ | 嵌套深度 | ≤ **24** |
73
+ | 节点总数 | ≤ **16384** |
73
74
  | `appid` | `zl` + 16 位小写十六进制，由平台生成；旧 `app_key` 为 2–64 位命名空间形式 |
74
- | `name` | 1–128 位 |
75
- | `description` | ≤ 2000 位 |
76
- | `icon` | ≤ 512 位 |
77
- | `version` | ≤ 32 位（语义化版本） |
75
+ | `name` | 1–128 位 |
76
+ | `description` | ≤ 2000 位 |
77
+ | `icon` | ≤ 512 位 |
78
+ | `version` | ≤ 32 位（语义化版本） |
78
79
 
79
80
  ### 云函数与 Provider
80
81
 
@@ -214,12 +215,12 @@
214
215
 
215
216
  ### 开发工具（`zleap-app`）
216
217
 
217
- | 项 | 限制 |
218
- | ------------------------ | ------------------------------------------------------------------------------------------------------ |
219
- | 开发会话 | 访问凭据 **30 分钟**，自动续期，自首次授权起最长 **30 天**；只限一个 `appid`；`auth logout` 立即撤销 |
220
- | 浏览器验收 | 单次 ≤ 128 步，总计 ≤ 5 分钟 |
221
- | `workspace.files` 单目录 | ≤ 500 个文件、100 个直接子目录 |
222
- | `workspace.files` 移动 | 每次 ≤ 100 个文件；目录句柄最多保留 1 小时 |
218
+ | 项 | 限制 |
219
+ | ------------------------ | ---------------------------------------------------------------------------------------------------- |
220
+ | 开发会话 | 访问凭据 **30 分钟**，自动续期，自首次授权起最长 **30 天**；只限一个 `appid`；`auth logout` 立即撤销 |
221
+ | 浏览器验收 | 单次 ≤ 128 步，总计 ≤ 5 分钟 |
222
+ | `workspace.files` 单目录 | ≤ 500 个文件、100 个直接子目录 |
223
+ | `workspace.files` 移动 | 每次 ≤ 100 个文件；目录句柄最多保留 1 小时 |
223
224
 
224
225
  ## 平台不做什么
225
226
 
@@ -242,17 +243,17 @@
242
243
 
243
244
  结构合法但被运行能力检查拒绝时，`zleap-app check` 不通过，应用中心无法安装打开：
244
245
 
245
- | # | 配置 | 原因码 | 修法 |
246
- | --- | -------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------- |
247
- | 1 | `schema` 不是 `zleap.app/2` | `MANIFEST_UNSUPPORTED` | 升级 Manifest |
248
- | 2 | `runtime.ui.type` 为 `builtin` | `RUNTIME_UNAVAILABLE` | 改为 `iframe` |
249
- | 3 | 无 `ui` 的 `backend` 含函数、`managed_function` 或未知 `builtin` | `RUNTIME_UNAVAILABLE` | 加前台界面，改为 `both` |
250
- | 4 | `runtime.ui.providers` 非空 | `FEATURE_UNAVAILABLE` | 删掉 `providers` |
251
- | 5 | `provides` 含 `execution: "foreground"` | `FEATURE_UNAVAILABLE` | 改 `headless` 或删除 |
252
- | 6 | 声明了 `agent.interaction` | `FEATURE_UNAVAILABLE` | 删掉 |
253
- | 7 | `requires` 含开放清单外的非可选能力 | `FEATURE_UNAVAILABLE` | 删掉或设 `optional: true` |
254
- | 8 | 没有 `backend` 却非可选地申请 `os.agent.complete` | `FEATURE_UNAVAILABLE` | 加 `backend` 或删掉 |
255
- | 9 | `host_api.profile` 不是 `app-runtime/2`，或 `requires` 含 `clipboard.write`、`workspace.files`、`workspace.images.read`、`user.*` 之外的值 | `FEATURE_UNAVAILABLE` | 改正或删掉 |
246
+ | # | 配置 | 原因码 | 修法 |
247
+ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | ------------------------- |
248
+ | 1 | `schema` 不是 `zleap.app/2` | `MANIFEST_UNSUPPORTED` | 升级 Manifest |
249
+ | 2 | `runtime.ui.type` 为 `builtin` | `RUNTIME_UNAVAILABLE` | 改为 `iframe` |
250
+ | 3 | 无 `ui` 的 `backend` 含函数、`managed_function` 或未知 `builtin` | `RUNTIME_UNAVAILABLE` | 加前台界面，改为 `both` |
251
+ | 4 | `runtime.ui.providers` 非空 | `FEATURE_UNAVAILABLE` | 删掉 `providers` |
252
+ | 5 | `provides` 含 `execution: "foreground"` | `FEATURE_UNAVAILABLE` | 改 `headless` 或删除 |
253
+ | 6 | 声明了 `agent.interaction` | `FEATURE_UNAVAILABLE` | 删掉 |
254
+ | 7 | `requires` 含开放清单外的非可选能力 | `FEATURE_UNAVAILABLE` | 删掉或设 `optional: true` |
255
+ | 8 | 没有 `backend` 却非可选地申请 `os.agent.complete` | `FEATURE_UNAVAILABLE` | 加 `backend` 或删掉 |
256
+ | 9 | `host_api.profile` 不是 `app-runtime/2`，或 `requires` 含 `clipboard.write`、`workspace.files`、`workspace.images.read`、`credentials.use`、`user.*` 之外的值 | `FEATURE_UNAVAILABLE` | 改正或删掉 |
256
257
 
257
258
  开放能力清单见 [Manifest · 目前开放的能力](manifest.md#目前开放的能力)。
258
259
  可安装的参考实现：`examples/app-cloud/copilot-studio`（`both` 形态）。
@@ -261,12 +262,12 @@
261
262
 
262
263
  以下能力**取决于部署是否配置**，不是你的代码能决定的。遇到时不要用回退数据冒充成功：
263
264
 
264
- | 项目 | 未配置时的表现 |
265
- | ------------ | ------------------------------------------------------------------------ |
266
- | 函数运行环境 | 控制台云函数显示 `RUNTIME_UNAVAILABLE · 函数执行 Provider 尚未开放。` |
267
- | 发布信任策略 | 签名验证报「发布信任策略尚未配置，或发布者密钥不可用、已撤销或已过期。」 |
265
+ | 项目 | 未配置时的表现 |
266
+ | ------------ | ------------------------------------------------------------------------------------- |
267
+ | 函数运行环境 | 控制台云函数显示 `RUNTIME_UNAVAILABLE · 函数执行 Provider 尚未开放。` |
268
+ | 发布信任策略 | 签名验证报「发布信任策略尚未配置，或发布者密钥不可用、已撤销或已过期。」 |
268
269
  | 生产激活 | 发布信任配置未就绪时控制台不出现生产入口；激活接口报 `PRODUCTION_RELEASE_UNAVAILABLE` |
269
- | 数据服务 | `RESOURCE_NOT_READY` / `DATA_SERVICE_UNAVAILABLE` |
270
+ | 数据服务 | `RESOURCE_NOT_READY` / `DATA_SERVICE_UNAVAILABLE` |
270
271
 
271
272
  > **关于「能跑」的判断标准**（注意）
272
273
  >
package/skills/zleap-cloud-app/references/manifest.md CHANGED
@@ -64,28 +64,28 @@ ZIP 根目录还必须有 `index.html`（入口）和**非空的 `LICENSE` 文
64
64
 
65
65
  ## 顶层字段
66
66
 
67
- | 字段 | 必填 | 类型 | 说明 |
68
- | --------------- | ---- | ------ | ------------------------------------------------------------------- |
69
- | `schema` | ✅ | 字符串 | 固定为 `"zleap.app/2"`，其他值会直接被拒绝 |
70
- | `appid` | ✅ | 字符串 | 应用唯一标识，在云开发控制台「创建应用」后由平台生成，见下方说明 |
67
+ | 字段 | 必填 | 类型 | 说明 |
68
+ | --------------- | ---- | ------ | -------------------------------------------------------------------------- |
69
+ | `schema` | ✅ | 字符串 | 固定为 `"zleap.app/2"`，其他值会直接被拒绝 |
70
+ | `appid` | ✅ | 字符串 | 应用唯一标识，在云开发控制台「创建应用」后由平台生成，见下方说明 |
71
71
  | `app_key` | | 字符串 | **旧写法**，仅已有应用继续使用，见下方 [旧写法 `app_key`](#旧写法-app-key) |
72
- | `name` | ✅ | 字符串 | 显示名，1–128 位，**必须有可见字符** |
73
- | `version` | ✅ | 字符串 | 语义化版本（SemVer），≤32 位，如 `1.0.0`、`1.2.0-beta.1` |
74
- | `publisher` | | 对象 | 不再需要；`appid` 应用会忽略它，见下方说明 |
75
- | `description` | | 字符串 | ≤2000 位 |
76
- | `icon` | | 字符串 | ≤512 位 |
77
- | `execution` | ✅ | 枚举 | `foreground` / `headless` / `both`，必须与 `runtime` 一致 |
78
- | `runtime` | ✅ | 对象 | 运行环境声明（见下） |
79
- | `background` | | 对象 | 后台运行模式，默认 `{ "on_install": "disabled", "modes": [] }` |
80
- | `triggers` | | 对象 | 触发器声明，默认 `{ "scheduled": [], "events": [] }` |
81
- | `events` | | 对象 | 事件发布与订阅，默认 `{ "publishes": [], "subscribes": [] }` |
82
- | `data` | | 对象 | 数据集合、集合 Schema 与访问规则（见下） |
83
- | `resources` | | 对象 | 资源限制，默认 `{ "max_concurrency": 1 }` |
84
- | `host_api` | | 对象 | 宿主能力声明，默认 `{ "profile": "app-runtime/2", "requires": [] }` |
85
- | `agent` | | 对象 | Agent 交互声明 |
86
- | `capabilities` | | 数组 | 只能是 `["notify.send"]`（应用通知，见下） |
87
- | `notifications` | | 对象 | 通知频道声明（见下） |
88
- | `storage` | | 对象 | 宿主 KV / 数据空间声明（见下） |
72
+ | `name` | ✅ | 字符串 | 显示名，1–128 位，**必须有可见字符** |
73
+ | `version` | ✅ | 字符串 | 语义化版本（SemVer），≤32 位，如 `1.0.0`、`1.2.0-beta.1` |
74
+ | `publisher` | | 对象 | 不再需要；`appid` 应用会忽略它，见下方说明 |
75
+ | `description` | | 字符串 | ≤2000 位 |
76
+ | `icon` | | 字符串 | ≤512 位 |
77
+ | `execution` | ✅ | 枚举 | `foreground` / `headless` / `both`，必须与 `runtime` 一致 |
78
+ | `runtime` | ✅ | 对象 | 运行环境声明（见下） |
79
+ | `background` | | 对象 | 后台运行模式，默认 `{ "on_install": "disabled", "modes": [] }` |
80
+ | `triggers` | | 对象 | 触发器声明，默认 `{ "scheduled": [], "events": [] }` |
81
+ | `events` | | 对象 | 事件发布与订阅，默认 `{ "publishes": [], "subscribes": [] }` |
82
+ | `data` | | 对象 | 数据集合、集合 Schema 与访问规则（见下） |
83
+ | `resources` | | 对象 | 资源限制，默认 `{ "max_concurrency": 1 }` |
84
+ | `host_api` | | 对象 | 宿主能力声明，默认 `{ "profile": "app-runtime/2", "requires": [] }` |
85
+ | `agent` | | 对象 | Agent 交互声明 |
86
+ | `capabilities` | | 数组 | 只能是 `["notify.send"]`（应用通知，见下） |
87
+ | `notifications` | | 对象 | 通知频道声明（见下） |
88
+ | `storage` | | 对象 | 宿主 KV / 数据空间声明（见下） |
89
89
 
90
90
  ### `appid`
91
91
 
@@ -212,7 +212,7 @@ ZIP 根目录还必须有 `index.html`（入口）和**非空的 `LICENSE` 文
212
212
  > - 声明了 `agent.interaction`；
213
213
  > - `runtime.capabilities.requires` 里有[开放清单](#目前开放的能力)之外的**非可选**能力；
214
214
  > - 没有 `backend` 却非可选地申请 `os.agent.complete`；
215
- > - `host_api.profile` 不是 `app-runtime/2`，或 `host_api.requires` 里有 `clipboard.write`、`workspace.files`、`workspace.images.read`、`user.profile`、`user.phone`、`user.email` 之外的值。
215
+ > - `host_api.profile` 不是 `app-runtime/2`，或 `host_api.requires` 里有 `clipboard.write`、`workspace.files`、`workspace.images.read`、`credentials.use`、`user.profile`、`user.phone`、`user.email` 之外的值。
216
216
  >
217
217
  > 可正常安装的写法：`runtime.ui` 只写 `type` 和 `entry`，`provides` 全部用 `headless`。
218
218
  > 参考仓库里的 `examples/app-cloud/copilot-studio`。
@@ -291,12 +291,12 @@ ZIP 根目录还必须有 `index.html`（入口）和**非空的 `LICENSE` 文
291
291
 
292
292
  `permissions.data[]` 每一条：
293
293
 
294
- | 字段 | 必填 | 说明 |
295
- | ------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------- |
296
- | `collection` | ✅ | 必须已在 `data.collections` 里声明 |
297
- | `scope` | ✅ | `invocation` / `current_user` / `user` / `space` / `organization` |
298
- | `actions` | ✅ | 从 `get`、`query`、`count`、`add`、`set`、`update`、`remove` 中选，最多 7 个。云函数里 `count` 计数按 `query` 核对，要计数请声明 `query` |
299
- | `fields` | | 允许访问的字段，最多 256 个；不写表示不按字段收窄。**云函数经数据网关访问时必须显式列出字段**，为空会被拒绝（「云函数数据字段未授权」） |
294
+ | 字段 | 必填 | 说明 |
295
+ | ------------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
296
+ | `collection` | ✅ | 必须已在 `data.collections` 里声明 |
297
+ | `scope` | ✅ | `invocation` / `current_user` / `user` / `space` / `organization` |
298
+ | `actions` | ✅ | 从 `get`、`query`、`count`、`add`、`set`、`update`、`remove` 中选，最多 7 个。云函数里 `count` 计数按 `query` 核对，要计数请声明 `query` |
299
+ | `fields` | | 允许访问的字段，最多 256 个；**不写时默认为空数组**，即没有按字段授权任何字段（不是「不按字段收窄」）。**云函数经数据网关访问时必须显式列出字段**，空 `fields` 会被拒绝（「云函数数据字段未授权」） |
300
300
 
301
301
  `permissions` 的含义与授权流程见 [权限与授权](permissions.md)。
302
302
 
@@ -605,14 +605,15 @@ Manifest 校验器接受 `^[a-zA-Z][a-zA-Z0-9_.-]*$`（≤128），但**数据
605
605
  | `profile` | 写 `"app-runtime/2"`（默认值）；其他值会让应用不可运行 |
606
606
  | `requires` | 只能从下表中选 |
607
607
 
608
- | 值 | 安装确认时的文案 | 说明 |
609
- | ----------------------- | -------------------------------- | -------------------------------------------------------------------------------------------------------------- |
610
- | `clipboard.write` | 写入剪贴板 | |
611
- | `workspace.files` | 读取及整理选定空间文件夹内的文件 | 配合模板里的 `sdk/workspace.js` 使用；用户在运行时选择文件夹 |
612
- | `workspace.images.read` | （安装确认显示原始 ID） | 读取选定文件夹里的图片：`workspace.readImage(handle, fileId, expectedVersion)`；必须同时声明 `workspace.files` |
608
+ | 值 | 安装确认时的文案 | 说明 |
609
+ | ----------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
610
+ | `clipboard.write` | 写入剪贴板 | 宿主桥支持该能力，但当前 SDK 的 `connectHostedApp()` 没有提供剪贴板方法（只有 `kv`、`files`、`close`） |
611
+ | `workspace.files` | 读取及整理选定空间文件夹内的文件 | 配合模板里的 `sdk/workspace.js` 使用；用户在运行时选择文件夹 |
612
+ | `workspace.images.read` | （安装确认显示原始 ID） | 读取选定文件夹里的图片：`workspace.readImage(handle, fileId, expectedVersion)`；必须同时声明 `workspace.files` |
613
+ | `credentials.use` | （安装确认文案未核实） | 使用钥匙串里的登录凭据；当前 SDK 未提供封装，本文档站暂不展开用法 |
613
614
  | `user.profile` | 使用时可能申请你的头像和昵称（由你决定是否同意） | 授权登录 `zl.auth.authorize({ scopes: ['profile'] })`，见[授权登录](app-runtime.md#先在-manifest-里声明) |
614
- | `user.phone` | 使用时可能申请你的手机号（由你决定是否同意） | 同上，`scopes` 含 `'phone'` |
615
- | `user.email` | 使用时可能申请你的邮箱（由你决定是否同意） | 同上，`scopes` 含 `'email'` |
615
+ | `user.phone` | 使用时可能申请你的手机号（由你决定是否同意） | 同上，`scopes` 含 `'phone'` |
616
+ | `user.email` | 使用时可能申请你的邮箱（由你决定是否同意） | 同上，`scopes` 含 `'email'` |
616
617
 
617
618
  写了其他值，应用会被判定为不可运行。没用到的能力不要写——每一项都会展示给用户。
618
619
 
package/skills/zleap-cloud-app/references/permissions.md CHANGED
@@ -65,11 +65,11 @@
65
65
 
66
66
  除 `requires` 外，以下声明也属于安装时要授予的权限：
67
67
 
68
- | 声明位置 | 可用值 | 在哪里调整 |
69
- | ------------------------------------------------------------ | ------------------------------------------------------------- | -------------------- |
70
- | `host_api.requires` | `clipboard.write`、`workspace.files`、`workspace.images.read` | 不可在窗口里单独撤销 |
71
- | `host_api.requires`（个人信息） | `user.profile`、`user.phone`、`user.email` | 安装时**不授予**，使用时由用户在授权框里逐项同意；应用窗口「已授权信息」撤销 |
72
- | 顶层 `capabilities` / `storage.capabilities`（宿主托管数据） | `storage.kv`、`space.read`、`space.write`、`notify.send` | 应用窗口「权限」 |
68
+ | 声明位置 | 可用值 | 在哪里调整 |
69
+ | ------------------------------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
70
+ | `host_api.requires` | `clipboard.write`、`workspace.files`、`workspace.images.read`、`credentials.use` | 不可在窗口里单独撤销 |
71
+ | `host_api.requires`（个人信息） | `user.profile`、`user.phone`、`user.email` | 安装时**不授予**，使用时由用户在授权框里逐项同意；应用窗口「已授权信息」撤销 |
72
+ | 顶层 `capabilities` / `storage.capabilities`（宿主托管数据） | `storage.kv`、`space.read`、`space.write`、`notify.send` | 应用窗口「权限」 |
73
73
 
74
74
  ### 也要声明集合
75
75
 
@@ -109,10 +109,10 @@
109
109
 
110
110
  打开应用后，窗口内容区顶部右侧只有**一个**「**权限**」按钮，但背后是两类**独立**的授权，对应服务端两套闸门，不要混为一谈：
111
111
 
112
- | 授权 | 管什么 | 怎么打开 |
113
- | ------------------------------------------ | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
114
- | **Cloud 数据授权**（「应用权限」对话框） | 云数据库 / 存储读写、后台能力 | 应用声明了 `runtime.backend`，或 `requires` 里有 `cloud.*` / `os.agent.complete` 时，点「权限」直接打开 |
115
- | **安装级权限**（宿主托管数据） | `storage.kv` / `space.read` / `space.write` / `notify.send` | 在「应用权限」对话框底部点「**管理其他权限**」；只声明了这些权限、没用 Cloud 的应用，点「权限」直接打开 |
112
+ | 授权 | 管什么 | 怎么打开 |
113
+ | ---------------------------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
114
+ | **Cloud 数据授权**（「应用权限」对话框） | 云数据库 / 存储读写、后台能力 | 应用声明了 `runtime.backend`，或 `requires` 里有 `cloud.*` / `os.agent.complete` 时，点「权限」直接打开 |
115
+ | **安装级权限**（宿主托管数据） | `storage.kv` / `space.read` / `space.write` / `notify.send` | 在「应用权限」对话框底部点「**管理其他权限**」；只声明了这些权限、没用 Cloud 的应用，点「权限」直接打开 |
116
116
 
117
117
  两类都没声明的应用不显示「权限」按钮。两个对话框的完整文案见 安装与卸载 · 应用窗口顶部的按钮（文档站 /app-center/install）。这里只讲授权语义。
118
118
 
@@ -138,29 +138,29 @@
138
138
 
139
139
  对话框里**没有环境选择**。数据域（dev「调试」/ prod「生产」）由宿主根据部署决定，对话框只显示当前是哪个：
140
140
 
141
- | 部署状态 | 数据域 | 谁能用 |
142
- | ---------- | ------ | ------------------------------------------------------------------------------------------------------------------------------- |
143
- | 未开放生产 | dev | 默认**只有该版本的发布者本人**（非发布者报 `PUBLISHER_REQUIRED`，对话框显示「当前安装未申请此能力，或你无权访问应用云空间。」） |
144
- | 已开放生产 | prod | 其他安装者一律走生产（应用没有生产环境时报 `ENV_FORBIDDEN`）；发布者本人在应用有生产环境后走生产，否则仍走 dev |
141
+ | 部署状态 | 数据域 | 谁能用 |
142
+ | ---------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
143
+ | 未开放生产 | dev | 默认只有开发团队：`appid` 应用的全部成员；旧 `app_key` 应用只有该版本的上传者本人（其他人报 `PUBLISHER_REQUIRED`，对话框显示「当前安装未申请此能力，或你无权访问应用云空间。」） |
144
+ | 已开放生产 | prod | 其他安装者一律走生产（应用没有生产环境时报 `ENV_FORBIDDEN`）；发布者本人在应用有生产环境后走生产，否则仍走 dev |
145
145
 
146
146
  生产是否开放取决于部署：发布信任配置就绪即开放（由运维自动配置），不由应用决定。
147
147
  应用代码里只写 `zl.cloud.init({ env: zl.cloud.DYNAMIC_CURRENT_ENV })`，**不要写死 `'dev'` / `'prod'`**。
148
148
 
149
149
  > **生产未开放时，同事用不了 Cloud 数据**（注意）
150
150
  >
151
- > 此时所有人都走 dev，而 dev 默认只对发布者开放（部署可另行放开）。你把应用发布到企业目录后，
151
+ > 此时所有人都走 dev，而 dev 默认只对开发团队（`appid` 应用成员 / 旧应用上传者）开放（部署可另行放开）。你把应用发布到企业目录后，
152
152
  > 同事能安装、能打开，但云数据读写会被拒绝。这属于「平台未开放」，不是代码写错了。
153
153
 
154
154
  ### 授权与会话的关系
155
155
 
156
156
  应用打开时，宿主为当前数据域建立 Cloud 会话，并按此刻的授权**一次性算出**可用的能力集合（profiles）：
157
157
 
158
- | profile | 需要 | 缺了的现象 |
159
- | ------------------ | ---------------------------------------------------- | ----------------------------------------------------------------- |
160
- | `document-core/1` | 数据库已开通 + 声明了集合 + 至少授权了数据库读或写 | 数据库调用抛 `UNSUPPORTED_OPERATION` |
161
- | `watch-snapshot/1` | 上面 + 授权了数据库读 | `watch` 不可用 |
162
- | `storage-object/1` | 存储已启用 + 授权了文件读/写（生产还需绑定就绪发布） | 文件接口抛 `UNSUPPORTED_OPERATION` |
163
- | `app-execution/1` | 至少一项后台能力已启用 | `callFunction` / `capabilities.invoke` 抛 `UNSUPPORTED_OPERATION` |
158
+ | profile | 需要 | 缺了的现象 |
159
+ | ------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
160
+ | `document-core/1` | 数据库已开通 + 声明了集合 + 至少授权了数据库读或写 | 数据库调用抛 `UNSUPPORTED_OPERATION` |
161
+ | `watch-snapshot/1` | 上面 + 授权了数据库读 | `watch` 不可用 |
162
+ | `storage-object/1` | 存储已启用 + 授权了文件读/写（生产还需绑定就绪发布） | 文件接口抛 `UNSUPPORTED_OPERATION` |
163
+ | `app-execution/1` | 至少一项后台能力已启用 | `callFunction` / `capabilities.invoke` 抛 `BACKGROUND_CAPABILITY_UNAVAILABLE`（旧 SDK 抛 `UNSUPPORTED_OPERATION`） |
164
164
 
165
165
  数据库和存储一项都没授权、也没有已启用的后台能力时，会话直接被拒：`CONSENT_REQUIRED`。
166
166
 
@@ -196,7 +196,7 @@ Cloud 授权的键形如 `cloud.database.dev.read`，记录在**这个安装的
196
196
  > 授权后，本应用可在关窗后按你勾选的能力运行（如定时巡检），只作用于你本人的数据，其他使用者看不到。
197
197
 
198
198
  - 授权限定在**这个安装 + 这个版本 + 这个环境**；每一步执行前都会重新检查；
199
- - `managed_function`（云函数）还要求绑定**就绪并已激活**的发布，否则提示「该版本尚未激活发布版本，暂时无法执行。请到「发布版本」页完成「激活开发」。」，调用返回 `FUNCTION_RELEASE_REQUIRED`；
199
+ - `managed_function`（云函数）还要求绑定**就绪并已激活**的发布，否则提示「该版本尚未激活发布版本，暂时无法执行。请到「发布版本」页完成「激活开发」。」，调用返回 `FUNCTION_RELEASE_REQUIRED`。appid 应用到控制台「版本管理」页下方的「开发环境：云函数激活」完成这一步；
200
200
  - `logic_unit` / `builtin` provider 不需要发布；
201
201
  - `os.agent.complete` 等内置动作同样是一项后台能力，要在这里启用后才能调用。
202
202
 
@@ -245,7 +245,7 @@ Cloud 授权的键形如 `cloud.database.dev.read`，记录在**这个安装的
245
245
 
246
246
  > **云函数的 `fields` 不能省略**（注意）
247
247
  >
248
- > Manifest 校验允许省略 `fields`，但云函数的数据网关把空 `fields` 当成「没有任何字段授权」，读写都会被拒（「云函数数据字段未授权」）。
248
+ > Manifest 校验技术上允许省略 `fields`（默认空数组），但云函数的数据网关把空 `fields` 当成「没有任何字段授权」，读写都会被拒（「云函数数据字段未授权」）。
249
249
  > 网关逐请求核对的完整规则见 [云函数开发](cloud-functions.md)。
250
250
 
251
251
  `actions` 合法值：`get`、`query`、`count`、`add`、`set`、`update`、`remove`。注意 `get` 是按文档键读**单条**，`query` 是按条件**查多条**——
@@ -315,19 +315,12 @@ Cloud 授权的键形如 `cloud.database.dev.read`，记录在**这个安装的
315
315
 
316
316
  | 能力 | 说明 | 用法 |
317
317
  | ----------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
318
- | `clipboard.write` | 写入剪贴板 | `sdk/zleap-sdk.js` 的 `connectHostedApp()` |
318
+ | `clipboard.write` | 写入剪贴板 | 宿主桥支持这个能力，但当前 SDK 的 `connectHostedApp()` 只有 `kv`、`files`、`close`，**没有剪贴板方法**；本文档站暂不提供调用示例 |
319
319
  | `workspace.files` | 读取及整理选定空间文件夹内的文件 | 模板里的 `sdk/workspace.js`；运行时由用户选择工作文件夹 |
320
320
  | `workspace.images.read` | 读取选定文件夹里的图片 | 需同时声明 `workspace.files`；`workspace.readImage(handle, fileId, expectedVersion)` 返回校验过的图片 Blob（JPEG/PNG/GIF/WebP，≤ 20 MiB） |
321
+ | `credentials.use` | 使用钥匙串里的登录凭据 | 宿主桥能力；当前 SDK 未提供封装，本文档站暂不展开 |
321
322
 
322
- ```js
323
- import { connectHostedApp } from './sdk/zleap-sdk.js';
324
-
325
- const host = await connectHostedApp();
326
- // 需在用户点击等手势里调用
327
- await host.clipboard.writeText({ text: '工作总结' });
328
- ```
329
-
330
- - `host_api.profile` 必须是 `app-runtime/2`；`requires` 写这两项之外的值，应用变成不可运行；
323
+ - `host_api.profile` 必须是 `app-runtime/2`；`requires` 写了白名单之外的值，应用变成不可运行；
331
324
  - 宿主桥会拒绝**未声明**的方法调用，返回错误而不是静默忽略；
332
325
  - `workspace.files` 弹出的「选择工作文件夹」只是选范围，权限已在安装时授予，实际操作仍受你的空间权限限制；
333
326
  - `workspace.files` 与 `cloud.storage.*` 是两回事：后者是本应用自己的云存储，不能互相代替；
@@ -335,21 +328,21 @@ await host.clipboard.writeText({ text: '工作总结' });
335
328
 
336
329
  ## 排查「没权限」
337
330
 
338
- | 症状 | 检查项 |
339
- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
340
- | 应用显示「暂不可用」，装不上 | `requires` 里有白名单外的非可选能力？声明了 `agent.interaction`、前台 provider / 前台 provides？`host_api` 写错？ |
341
- | 上传就失败 | `appid` 是否已在控制台创建、你是否是应用成员、provider `permissions` 是否 ⊆ `requires`、集合是否已声明 |
342
- | 打开应用报 `CONSENT_REQUIRED` | 「权限」里的四项全被取消且没有已启用的后台能力——勾选后保存 |
343
- | `PUBLISHER_REQUIRED` | 当前数据域是 dev，而你不是该版本的发布者。等部署开放生产，或用发布者账号验证 |
344
- | `ENV_FORBIDDEN` | 当前数据域的环境未创建 / 不可用，或部署未开放生产 |
345
- | 数据库调用 `UNSUPPORTED_OPERATION` | 环境、数据库是否就绪？是否授权了数据库读写？改完后重新加载应用了吗？ |
346
- | `SCOPE_FORBIDDEN` / `RULE_DENIED` | 授权是否被取消？集合是否在 `data.collections` 里？记录规则是否允许？详见 [状态与错误码](status-codes.md) |
347
- | 云函数访问不到字段 | provider 的 `permissions.data[].fields` 写了且包含该字段吗？`actions` 允许这个操作吗？ |
348
- | 用户之间看不到彼此数据 | 集合是私有的（默认）。需要共享就在**创建集合之前**声明 `shared_collections` / `partition: "shared"` |
349
- | 前端调用后台能力 `UNSUPPORTED_OPERATION` | 没有任何已启用的后台能力——在应用窗口「权限」里勾选并重新加载 |
350
- | 云函数 `FUNCTION_RELEASE_REQUIRED` | 到「发布版本」完成签发与「激活开发」 |
351
- | 更新版本后后台任务不跑了 | 应用中心更新时权限变宽的能力需重新确认；CLI `update` 会停用全部后台能力 |
352
- | 跨应用调用失败 | 普通 SDK 不支持跨应用调用 |
331
+ | 症状 | 检查项 |
332
+ | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
333
+ | 应用显示「暂不可用」，装不上 | `requires` 里有白名单外的非可选能力？声明了 `agent.interaction`、前台 provider / 前台 provides？`host_api` 写错？ |
334
+ | 上传就失败 | `appid` 是否已在控制台创建、你是否是应用成员、provider `permissions` 是否 ⊆ `requires`、集合是否已声明 |
335
+ | 打开应用报 `CONSENT_REQUIRED` | 「权限」里的四项全被取消且没有已启用的后台能力——勾选后保存 |
336
+ | `PUBLISHER_REQUIRED` | 当前数据域是 dev，而你不是该版本的发布者。等部署开放生产，或用发布者账号验证 |
337
+ | `ENV_FORBIDDEN` | 当前数据域的环境未创建 / 不可用，或部署未开放生产 |
338
+ | 数据库调用 `UNSUPPORTED_OPERATION` | 环境、数据库是否就绪？是否授权了数据库读写？改完后重新加载应用了吗？ |
339
+ | `SCOPE_FORBIDDEN` / `RULE_DENIED` | 授权是否被取消？集合是否在 `data.collections` 里？记录规则是否允许？详见 [状态与错误码](status-codes.md) |
340
+ | 云函数访问不到字段 | provider 的 `permissions.data[].fields` 写了且包含该字段吗？`actions` 允许这个操作吗？ |
341
+ | 用户之间看不到彼此数据 | 集合是私有的（默认）。需要共享就在**创建集合之前**声明 `shared_collections` / `partition: "shared"` |
342
+ | 前端调用后台能力 `BACKGROUND_CAPABILITY_UNAVAILABLE` | 没有任何已启用的后台能力——在应用窗口「权限」里勾选并重新加载（旧 SDK 报 `UNSUPPORTED_OPERATION`） |
343
+ | 云函数 `FUNCTION_RELEASE_REQUIRED` | 到「版本管理」页下方「开发环境：云函数激活」（或概览的「去签名」）完成签发与「激活开发」 |
344
+ | 更新版本后后台任务不跑了 | 应用中心更新时权限变宽的能力需重新确认；CLI `update` 会停用全部后台能力 |
345
+ | 跨应用调用失败 | 普通 SDK 不支持跨应用调用 |
353
346
 
354
347
  ## 相关
355
348