create-zleap-app 0.10.0 → 0.10.2

package/skills/zleap-cloud-app/references/cloud-functions.md

@@ -11,7 +11,7 @@
 
 | 名词                                | 是什么                                                                                                    | 写在哪                                                        |
 | ----------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
-| **函数**（function）                | 一段 Node 代码，入口导出 `main(event)`                                                                    | `runtime.backend.functions[]` + 包里的 `cloudfunctions/` 目录 |
+| **函数**（function）                | 一段 Node 代码，入口导出一个函数（平台按函数名 / `main` / default 查找）                                  | `runtime.backend.functions[]` + 包里的 `cloudfunctions/` 目录 |
 | **Provider**                        | 「由谁来实现」：可以是函数（`managed_function`）、平台逻辑单元（`logic_unit`）或平台内置动作（`builtin`） | `runtime.backend.providers[]`                                 |
 | **后台能力**（headless capability） | 对外可调用的一个操作，指向某个 provider，带输入 / 输出 Schema                                             | `runtime.capabilities.provides[]`，`execution: "headless"`    |
 
@@ -142,35 +142,37 @@ my-app/
 - 路径不存在时报「云函数制品入口缺失」/ `FUNCTION_ARTIFACT_MISSING`；
 - 单个函数目录最多 4096 个文件、合计 20 MiB（`FUNCTION_ARTIFACT_TOO_LARGE`）。
 
-入口必须导出 **`main`**，接收 `event`（即调用时传入的 `input` / `data`），返回值就是作业的 `result`：
+入口的导出由 runner 按 **`module[函数名] ?? module.main ?? module.default`** 查找：导出与 `functions[].name` 同名的函数最稳妥，也支持导出 `main`（或 default）。
+调用签名是 **`(event, context)`**，返回值就是作业的 `result`。`event` 是调用时传入的 `input` / `data`；
+`context` 带 `invocationId`、`jobId`、`attemptId`、`deadlineAt` 和 `signal`——`signal` 是 `AbortSignal`，到截止时间触发，长任务应当响应取消。
 
 ```js
 import { zl } from '@zleap/app-cloud-server';
 
-export async function main(event) {
+export async function main(event, context) {
   zl.cloud.init({ env: zl.cloud.DYNAMIC_CURRENT_ENV });
   const logger = zl.cloud.getLogger();
-  const context = zl.cloud.getContext();
 
   const draftId = typeof event?.draft_id === 'string' ? event.draft_id : '';
   if (!draftId) throw new Error('DRAFT_ID_REQUIRED');
 
-  logger.info('processing draft', { draftId });
+  logger.info('processing draft', { draftId, invocationId: context.invocationId });
+  if (context.signal.aborted) throw new Error('CANCELLED');
   return { summary: `已处理 ${draftId}` };
 }
 ```
 
 ### 运行环境 `node-lts/1`
 
-| 项                    | 值                                                            |
-| --------------------- | ------------------------------------------------------------- |
-| Node 版本             | 24.21.0（linux / arm64，非 root 用户）                        |
-| 网络                  | **无**（`network_policy: none`）——函数里不能 `fetch` 外部地址 |
-| `timeout_seconds`     | 1–300，默认 30                                                |
-| `memory_mb`           | 64–4096，默认 512                                             |
-| CPU / 进程数 / 临时盘 | 1000 millicore / 64 / 64 MB（固定，不可配置）                 |
-| 返回值大小            | ≤ 256 KiB                                                     |
-| 日志                  | 每次调用 ≤ 1 MiB，单行 ≤ 16 KiB                               |
+| 项                    | 值                                                                                                                                                                                                                                             |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Node 版本             | **以实际部署镜像为准。** `node-lts/1` 画像在 `profile.json` 里登记为 Node 24.21.0（linux / arm64，非 root），但仓库中的沙箱镜像 Dockerfile 目前基于 `node:22-bookworm-slim`，两者尚未对齐。请勿依赖 Node 22 之后才有的特性，也不要写死补丁版本 |
+| 网络                  | **无**（`network_policy: none`）——函数里不能 `fetch` 外部地址                                                                                                                                                                                  |
+| `timeout_seconds`     | 1–300，默认 30                                                                                                                                                                                                                                 |
+| `memory_mb`           | 64–4096，默认 512                                                                                                                                                                                                                              |
+| CPU / 进程数 / 临时盘 | 1000 millicore / 64 / 64 MB（固定，不可配置）                                                                                                                                                                                                  |
+| 返回值大小            | ≤ 256 KiB                                                                                                                                                                                                                                      |
+| 日志                  | 每次调用 ≤ 1 MiB，单行 ≤ 16 KiB                                                                                                                                                                                                                |
 
 `@zleap/app-cloud-server` 由运行时提供，**不需要也不应该**打进包里。第三方 npm 依赖能否随包使用**未验证**；
 由于没有网络，任何需要联网的库都用不了。
@@ -187,24 +189,22 @@ export async function main(event) {
 | `zl.cloud.init({ env: zl.cloud.DYNAMIC_CURRENT_ENV })` | 建议第一行调用。只接受 `env: DYNAMIC_CURRENT_ENV` 或不传；写 `'dev'` 等会抛 `ENV_MISMATCH` |
 | `zl.cloud.getContext()`                                | 本次调用的上下文（见下表）                                                                 |
 | `zl.cloud.getLogger()`                                 | 结构化日志                                                                                 |
-| `zl.cloud.os.database.query(args)`                     | 读（`get` 单条 / `query` 多条）                                                            |
+| `zl.cloud.os.database.query(args)`                     | 读（只支持 `get` 单条 / `count` 计数）                                                     |
 | `zl.cloud.os.database.mutate(args)`                    | 写（`add` / `set` / `update` / `remove`）                                                  |
-| `zl.cloud.auth.getOpenId()`                            | 调用者在本应用里的 `openid`（不需要用户同意），用作应用里的用户键                          |
-| `zl.cloud.auth.getUserInfo()`                          | 调用者的 `openid` 与他授权给应用的信息，见 [授权登录](app-runtime.md#在云函数里读取) |
 
-云函数里**没有** `zl.cloud.database()`、文件存储、`callFunction` 或能力调用。
+云函数里**没有** `zl.cloud.database()`、文件存储、`callFunction` 或能力调用，也**没有** `zl.cloud.auth`：`getOpenId()` / `getUserInfo()` 目前不可用。需要 `openid` 时，由页面用 `zl.auth.getIdentity()` 取到后作为输入传入，或使用文档自带的 `_openid`（见下文）。
 
 ### `getContext()`
 
-| 字段                                    | 说明                                                                     |
-| --------------------------------------- | ------------------------------------------------------------------------ |
-| `invocationId`                          | **调用编号**——日志筛选用它                                               |
-| `jobId`                                 | 作业编号                                                                 |
-| `attemptId`                             | 本次尝试编号（重试时不同）                                               |
-| `appId` / `environmentId` / `bindingId` | 应用、环境、数据绑定 ID                                                  |
-| `userId`                                | **已废弃**：平台内部用户 ID。要区分用户请用 `await zl.cloud.auth.getOpenId()` |
-| `traceId`                               | 链路追踪 ID                                                              |
-| `deadlineAt`                            | 截止时间（秒级时间戳）；过了之后 SDK 调用抛 `FUNCTION_DEADLINE_EXCEEDED` |
+| 字段                                    | 说明                                                                                                                                  |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `invocationId`                          | **调用编号**——日志筛选用它                                                                                                            |
+| `jobId`                                 | 作业编号                                                                                                                              |
+| `attemptId`                             | 本次尝试编号（重试时不同）                                                                                                            |
+| `appId` / `environmentId` / `bindingId` | 应用、环境、数据绑定 ID                                                                                                               |
+| `userId`                                | **已废弃**：平台内部用户 ID。当前服务端 SDK 没有 `auth` 命名空间，不要用它区分业务用户；用文档自带的 `_openid`，或由页面传入 `openid` |
+| `traceId`                               | 链路追踪 ID                                                                                                                           |
+| `deadlineAt`                            | 截止时间（秒级时间戳）；过了之后 SDK 调用抛 `FUNCTION_DEADLINE_EXCEEDED`                                                              |
 
 ### `getLogger()`
 
@@ -339,15 +339,19 @@ await zl.cloud.os.database.mutate({
 
 > **给云函数用的 provider 一定要写 `fields`**（注意）
 >
-> Manifest 校验允许省略 `fields`，但云函数数据网关会把**空 `fields` 当成没有任何字段授权**而拒绝。
+> Manifest 校验技术上允许省略 `fields`（默认就是空数组），但云函数数据网关会把**空 `fields` 当成没有任何字段授权**而拒绝。
 
 数据范围由平台按调用身份和数据绑定自动限定，函数里传 `user_id` 之类的字段绕不过去。
 
-> **用 openid 区分用户，不要用 `userId`**（提示）
+> **用 openid 区分用户：从输入或 `_openid` 来**（提示）
+>
+> 当前服务端 SDK **没有** `zl.cloud.auth.getOpenId()` / `getUserInfo()`。需要「谁的数据」这类键时，有两个来源：
 >
+> - 页面用 `zl.auth.getIdentity()` 拿到 `openid`，作为能力的输入传给函数；
+> - 私有集合里读到的文档自带 `_openid`（写入者标识），可以直接用（`examples/moments` 的 `stats` 就是这么做的）。
+>
+> 由页面传入的 `openid` 只是业务参数，函数无法再向平台核验；手机号 / 邮箱同理，函数拿不到授权登录的信息。
 > `getContext().userId` 是平台内部用户 ID，只为兼容旧应用保留，新应用不要存它、也不要返回给前端。
-> 需要「谁的数据」这类键时用 `await zl.cloud.auth.getOpenId()`：它和前端 `zl.auth.getIdentity()` 拿到的 `openid` 一致，
-> 同一用户在不同应用里不同。
 
 ### 读写失败时拿到什么
 
@@ -390,28 +394,208 @@ function operationIdFor(context, purpose) {
 > **跨 attempt 能否被识别为同一写入未验证**。带副作用的写操作建议 `retry.mode: "none"`，
 > 或用 `expected_version` 乐观锁兜底，避免重复写入。
 
+## 最小可运行示例：同事圈（moments）
+
+仓库里的 `zleap-app-kit/examples/moments` 是一个完整可运行的示例（React + Vite）：它用一个云函数 `stats` 统计「我的互动」，每 5 分钟由定时触发器跑一次。下面是它的关键声明和函数代码（节选，完整 Manifest 见该目录的 `manifest.json`）。
+
+**1. 声明函数与 provider**（`runtime.backend` 下的两个数组）
+
+```json
+"functions": [
+  {
+    "name": "stats",
+    "entry": "cloudfunctions/stats",
+    "runtime_profile": "node-lts/1",
+    "timeout_seconds": 30,
+    "memory_mb": 256
+  }
+],
+"providers": [
+  {
+    "id": "moments.stats",
+    "type": "managed_function",
+    "function": "stats",
+    "permissions": {
+      "capabilities": ["cloud.database.read", "cloud.database.write"],
+      "data": [
+        { "collection": "me", "scope": "current_user", "actions": ["get"], "fields": ["nickname", "created_at"] },
+        { "collection": "posts", "scope": "current_user", "actions": ["query"], "fields": ["author"] },
+        { "collection": "likes", "scope": "current_user", "actions": ["query"], "fields": ["post_author", "author"] },
+        { "collection": "comments", "scope": "current_user", "actions": ["query"], "fields": ["post_author", "author"] },
+        { "collection": "digest", "scope": "current_user", "actions": ["get", "set"], "fields": ["posts", "likes_received", "comments_received", "source", "updated_at"] }
+      ]
+    },
+    "retry": { "mode": "none", "max_attempts": 1 }
+  }
+]
+```
+
+**2. 声明对外能力**（`runtime.capabilities.provides` 里的一项）
+
+```json
+{
+  "id": "zl7b2843d539ca2df7.stats",
+  "contract_version": "1.0.0",
+  "title": "统计我的互动",
+  "execution": "headless",
+  "provider": "moments.stats",
+  "effect": "write",
+  "discoverable": false,
+  "input_schema": {
+    "type": "object",
+    "properties": { "source": { "type": "string", "enum": ["manual", "scheduled"] } },
+    "additionalProperties": false
+  },
+  "output_schema": {
+    "type": "object",
+    "properties": {
+      "posts": { "type": "integer", "minimum": 0 },
+      "likes_received": { "type": "integer", "minimum": 0 },
+      "comments_received": { "type": "integer", "minimum": 0 },
+      "error": { "type": "string", "maxLength": 300 }
+    },
+    "additionalProperties": false
+  }
+}
+```
+
+**3. 写函数** — `cloudfunctions/stats/index.mjs`：
+
+```js
+// 统计「我的互动」：我发了几条动态、收到多少赞和评论（不算自己给自己的），写进私有集合 digest。
+// 云函数里只能 get / count；本人在数据域里的标识从私有集合 me/profile 的 _openid 读出来。
+import { createHash } from 'node:crypto';
+import { zl } from '@zleap/app-cloud-server';
+
+const opId = (ctx, purpose) =>
+  `op_${Math.floor(Date.now() / 1000)}_${createHash('sha256').update(`${ctx.invocationId}:${purpose}`).digest('hex').slice(0, 32)}`;
+
+export async function main(event) {
+  zl.cloud.init({ env: zl.cloud.DYNAMIC_CURRENT_ENV });
+  const ctx = zl.cloud.getContext();
+  const logger = zl.cloud.getLogger();
+  const db = zl.cloud.os.database;
+  const rid = (purpose) => `${ctx.invocationId}:${purpose}`.slice(0, 128);
+  try {
+    const found = await db
+      .query({ collection: 'me', operation: 'get', document_key: 'profile', request_id: rid('me') })
+      .catch((e) => {
+        if (e?.code === 'DOCUMENT_NOT_FOUND') return null;
+        throw e;
+      });
+    const me = Array.isArray(found?.list) ? found.list[0] : null;
+    if (!me?._openid)
+      return {
+        posts: 0,
+        likes_received: 0,
+        comments_received: 0,
+        error: '还没打开过同事圈，没有资料',
+      };
+    const openid = me._openid;
+    const count = async (collection, filter, purpose) => {
+      const res = await db.query({
+        collection,
+        operation: 'count',
+        filter,
+        request_id: rid(purpose),
+      });
+      return Number(res?.total ?? res?.count ?? 0);
+    };
+    const others = (field) => ({
+      op: 'and',
+      filters: [
+        { op: 'eq', field, value: openid },
+        { op: 'neq', field: 'author', value: openid },
+      ],
+    });
+    const posts = await count('posts', { op: 'eq', field: 'author', value: openid }, 'posts');
+    const likes = await count('likes', others('post_author'), 'likes');
+    const comments = await count('comments', others('post_author'), 'comments');
+    const source = event?.source === 'scheduled' ? 'scheduled' : 'manual';
+    await db.mutate({
+      collection: 'digest',
+      operation: 'set',
+      document_key: 'latest',
+      data: {
+        posts,
+        likes_received: likes,
+        comments_received: comments,
+        source,
+        updated_at: Date.now(),
+      },
+      value_types: { '/updated_at': 'date' },
+      operation_id: opId(ctx, 'digest'),
+      request_id: rid('digest'),
+    });
+    logger.info('stats refreshed', { posts, likes, comments, source });
+    return { posts, likes_received: likes, comments_received: comments };
+  } catch (error) {
+    logger.error('stats failed', { code: error?.code });
+    return {
+      posts: 0,
+      likes_received: 0,
+      comments_received: 0,
+      error: `${error?.code ?? 'ERROR'}: ${error?.message ?? error}`.slice(0, 300),
+    };
+  }
+}
+```
+
+几个和声明对应的地方：
+
+- 函数叫 `stats`，`entry` 指向目录 `cloudfunctions/stats`，runner 会在目录里找到 `index.mjs`；
+- 函数只 `get` 了 `me`、`count` 了 `posts` / `likes` / `comments`，但 provider 里后三个集合声明的是 `query`——**`count` 按 `query` 动作核对**，只写 `count` 会被拒；
+- `data.collections` 必须包含 `me`、`posts`、`likes`、`comments`、`digest`；示例另外还声明了 `photos` 和 `schemas` / `policies`；
+- 写 `digest` 用 `set`，所以 `actions` 里要有 `set`（示例同时给了 `get`）。
+
+**4. 构建与上传**
+
+示例的 `vite.config.ts` 里有一个 `zleapPackage` 插件：构建时把项目根的 `manifest.json`、`LICENSE` 和整个 `cloudfunctions/` **原样复制进 `dist/`**（跳过 `node_modules`），并校验 `runtime.ui.entry` 是 `index.html`。所以构建产物 `dist/` 就是应用包根目录，可以直接交给 CLI：
+
+```bash
+npx zleap-app check dist
+npx zleap-app pack dist --output out/app.zip
+npx zleap-app publish dist
+```
+
+示例项目已经把这些串成脚本：`npm run deploy`（构建 → 检查 → 上传开发版本 → 装到自己桌面）、`npm run release -- --notes "…"`（发布为线上版本）。
+
+包上传后还差平台侧两步：在应用窗口「权限」里勾选「统计我的互动」这项后台能力；再到控制台「版本管理」页下方「开发环境：云函数激活」把该版本激活到开发。定时触发器 `stats_refresh` 还要在控制台「触发器」里启用，否则只会手动调用时运行。
+
 ## 第三步：上传、签名、激活、授权
 
 函数代码写好后，要走完下面这条链才会真正执行。缺任何一步，调用都不会进入函数沙箱：
 
 ```
-① 上传：zleap-app publish 或应用中心「上传应用包」（会自动生成一个草稿发布候选）
+① 上传：zleap-app publish 或应用中心「上传应用包」
 ② 安装（安装即授予声明的 cloud.* 权限；后台能力为「停用」）
 ③ 开发环境与数据库：声明了集合的应用安装时自动创建并开通（集合按声明自动创建）；否则在控制台「创建开发环境」
-④ 控制台「发布版本」：发布候选「验证并签发」→ 就绪 →「激活开发」
+④ 激活开发：控制台「版本管理」页下方的「开发环境：云函数激活」（新建候选 → 签名验证 → 激活开发），
+   或在项目里运行 `npx zleap-app prepare <app_id> --version-id <id>`（只准备开发环境）
+   概览开通清单里对应「去签名」/「升级安装并激活」；这里只列出你本人上传的版本
 ⑤ 应用窗口「权限」→「后台能力（定时任务 / 云函数）」勾选该能力 →「保存并重新加载」
    （或在控制台「后台能力」里点「允许后台运行」）
 ```
 
-详细界面见 发布版本（文档站 /console/release）、云函数与后台能力（文档站 /console/functions）、安装与卸载（文档站 /app-center/install），
+详细界面见 版本管理（文档站 /console/release）、云函数与后台能力（文档站 /console/functions）、安装与卸载（文档站 /app-center/install），
 端到端顺序见 从开发到上线（文档站 /guide/dev-to-production）。
 
-| 少了哪一步                                            | 现象                                                                                                                                        |
-| ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| 没有任何已启用的后台能力                              | 会话里没有 `app-execution/1`，前端 `callFunction` / `capabilities.invoke` **在发请求前**就抛 `UNSUPPORTED_OPERATION`                        |
-| 这项能力没被授权                                      | 403「此能力尚未由用户授权」                                                                                                                 |
-| 没有「激活开发」（`managed_function` 没绑定就绪发布） | `FUNCTION_RELEASE_REQUIRED`；「权限」对话框里该项下方提示「该版本尚未激活发布版本，暂时无法执行。请到「发布版本」页完成「激活开发」。」 |
-| 部署没接入函数计算节点 / 调度服务                     | `FUNCTION_RUNTIME_UNAVAILABLE`（平台未开放，不是你写错了）                                                                                  |
+| 少了哪一步                                            | 现象                                                                                                                                                                  |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 没有任何已启用的后台能力                              | 会话里没有 `app-execution/1`，前端 `callFunction` / `capabilities.invoke` **在发请求前**就抛 `BACKGROUND_CAPABILITY_UNAVAILABLE`（旧 SDK 为 `UNSUPPORTED_OPERATION`） |
+| 这项能力没被授权                                      | 403「此能力尚未由用户授权」                                                                                                                                           |
+| 没有「激活开发」（`managed_function` 没绑定就绪发布） | `FUNCTION_RELEASE_REQUIRED`；「权限」对话框里该项下方提示「该版本尚未激活发布版本，暂时无法执行。请到「发布版本」页完成「激活开发」。」                               |
+| 部署没接入函数计算节点 / 调度服务                     | `FUNCTION_RUNTIME_UNAVAILABLE`（平台未开放，不是你写错了）                                                                                                            |
+
+### 开发环境激活 ≠ 生产发布
+
+上面第 ④ 步只让云函数在**开发环境**运行。要让其他使用者在生产环境用上它：
+
+- **appid 应用**：把版本「发布为线上版本」（控制台「版本管理」，或 `zleap-app release`）。带云资源的版本**第一次**发布时，平台以上传者身份自动准备生产（生产环境、生产授权、签名、激活、生产集合）；上传者当前必须安装的就是这个版本，否则返回 40900（`UPLOADER_NOT_ON_VERSION`）。已经发布过的版本再次发布直接复用，不再要求。只用宿主能力的应用直接发布，不需要签名激活。
+- **旧 `app_key` 应用**：继续在「版本与激活」里走发布候选 / 签名 / 激活。
+
+`zleap-app prepare` 对两类应用都可用：**appid 应用**只准备开发环境（等价于上面的「开发环境：云函数激活」，不会碰生产），
+准备完成后用 `zleap-app invoke <app_id> --capability <id> --environment dev` 测试；**旧 `app_key` 应用**只接受本人 private 包，一路准备到生产。
 
 `logic_unit` 和 `builtin` provider 不进函数沙箱，**不需要**签名发布，授权后台能力即可执行。
 
@@ -634,16 +818,19 @@ const job = await zl.cloud.os.capabilities.invoke({
 见示例应用 `zleap-web/examples/app-cloud/copilot-studio/`：`cloudfunctions/reviewContent` 读取草稿、计算摘要、带乐观锁写回；
 `nightlyReview` 由定时触发器驱动；另有 `logic_unit` 与 `builtin`（`os.agent.complete`）两种 provider 的对照。
 
+带云函数的可运行前端示例见 `zleap-app-kit/examples/moments`，声明与代码摘录见上文「最小可运行示例」。
+
 ## 常见问题
 
-### 前端调用直接抛 `UNSUPPORTED_OPERATION`
+### 前端调用直接抛 `BACKGROUND_CAPABILITY_UNAVAILABLE`
 
 当前会话没有协商出 `app-execution/1`：这个安装在当前数据域里**没有任何已启用的后台能力**。
 到应用窗口「权限」里勾选后台能力并保存，再重新加载应用。这不是函数写错了。
+旧版 SDK 在同样情况下抛的是 `UNSUPPORTED_OPERATION`，看到旧错误码时处理方式相同。
 
 ### `FUNCTION_RELEASE_REQUIRED`
 
-`managed_function` 必须绑定**就绪且已激活**的发布。到 发布版本（文档站 /console/release） 完成「验证并签发」和「激活开发」，
+`managed_function` 必须绑定**就绪且已激活**的发布。appid 应用到控制台「版本管理」页下方的「开发环境：云函数激活」完成激活，
 然后重新打开应用窗口「权限」确认该能力下没有「尚未激活发布版本」的提示，再重新加载应用。
 
 ### `RUNTIME_GATEWAY_UNAVAILABLE` / 其他 `RUNTIME_GATEWAY_*`
@@ -675,6 +862,6 @@ const job = await zl.cloud.os.capabilities.invoke({
 - [权限与授权](permissions.md) — 安装授权、Cloud 数据授权与后台能力授权
 - [Manifest v2 配置](manifest.md) — 函数与 provider 的声明
 - 云函数与后台能力（控制台）（文档站 /console/functions）
-- 发布版本（文档站 /console/release）
+- 版本管理（文档站 /console/release）
 - 日志（文档站 /console/logs）
 - [状态与错误码](status-codes.md)

package/skills/zleap-cloud-app/references/console-database.md

@@ -152,6 +152,10 @@
 
 集合里还没有你的文档时显示「**这个集合还没有文档**」——「新建一条文档，或在应用里通过 Cloud SDK 写入后刷新。」
 
+（截图：数据库文档视图，见文档站）
+
+文档标签页：左侧集合列表，右侧文档表格、筛选、输入文档键直接打开、新建文档与备份入口。
+
 ### 筛选与排序
 
 点「**筛选**」打开「**按条件筛选**」弹层：
@@ -281,6 +285,10 @@ JSON 视图提示「必须是 JSON 对象，字段需符合集合结构。」
 表格列：「字段」「类型」「必填」（必填 / 可选）「约束」（选项值、「最多 {n} 字符」、日期字段「按毫秒时间戳存储」）。
 底部「**查看 JSON Schema 原文**」展开服务端保存的完整定义。
 
+（截图：集合结构标签页，见文档站）
+
+结构标签页：明确写出「结构创建后不能修改」，下面按字段列出类型、必填与约束。
+
 > **新版本改 Schema 不会更新已有集合**（注意）
 >
 > 集合一旦建好，后续版本 Manifest 里改了它的 Schema 也**不会**应用上去；私有 / 共享分区也不能改。

package/skills/zleap-cloud-app/references/console-members.md

@@ -8,7 +8,7 @@
 > **一句话流程**（提示）
 >
 > 控制台「创建应用」→ 复制 `appid` → 脚手架带上 `appid` 或写进 `manifest.json` → `npm run deploy` 上传 →
-> （需要协作时）「团队」→「成员」里添加开发者 →（给全企业用时）「版本管理」里发布为线上版本。
+> （需要协作时）「团队」→「成员」里添加开发者 →（给全企业用时）「版本管理」里发布为线上版本（这一步只适用于 `appid` 应用）。
 
 ## 创建应用
 
@@ -20,10 +20,10 @@
 
 打开的抽屉标题为「**创建应用**」，副标题「平台会生成 appid，你自动成为管理员」：
 
-| 字段             | 说明                       |
-| ---------------- | -------------------------- |
-| 应用名称         | 必填，最多 64 个字         |
-| 应用说明（可选） | 最多 2000 字               |
+| 字段             | 说明               |
+| ---------------- | ------------------ |
+| 应用名称         | 必填，最多 64 个字 |
+| 应用说明（可选） | 最多 2000 字       |
 
 抽屉底部提示「创建后把 appid 写进 manifest 即可上传；名称和说明以后上传的 manifest 为准。」点「**创建**」完成。
 
@@ -38,7 +38,7 @@
 刚创建、还没有上传过任何版本的应用，控制台不显示环境和开通清单，而是一张引导页：
 「应用已创建，还没有上传过代码。按下面三步把第一个版本传上来。」
 
-页面顶部是 `appid`，旁边有「**复制 appid**」按钮。三步是：
+页面顶部是 `appid` 芯片，旁边是「**复制**」按钮（无障碍名称是「复制 appid」，复制后短暂显示「已复制」）。三步是：
 
 1. **新项目：用脚手架创建，自动带上 appid**
 
@@ -68,10 +68,16 @@
 
 侧栏「**团队**」分组下的「**成员**」，页面说明「管理员和开发者都能上传、在控制台管理这个应用；只有管理员能增删成员。」
 
-| 角色       | 能做什么                                                                 |
-| ---------- | ------------------------------------------------------------------------ |
-| **管理员** | 管理成员与应用：添加、移除成员，修改角色；也能上传、调试与管理          |
-| **开发者** | 上传、调试与管理：用同一个 `appid` 上传版本、在控制台管理这个应用        |
+页面顶部是一条 appid 栏：`appid` 芯片、旁边的「**复制**」按钮，以及你在该应用里的**当前角色标签**（「管理员」或「开发者」）。
+
+（截图：成员页，见文档站）
+
+成员页：顶部是 appid + 复制 + 当前角色，下面是添加成员、成员行与角色、退出操作。
+
+| 角色       | 能做什么                                                          |
+| ---------- | ----------------------------------------------------------------- |
+| **管理员** | 管理成员与应用：添加、移除成员，修改角色；也能上传、调试与管理    |
+| **开发者** | 上传、调试与管理：用同一个 `appid` 上传版本、在控制台管理这个应用 |
 
 控制台的应用切换下拉列出**你是管理员或开发者的全部应用**。
 
@@ -80,17 +86,17 @@
 在「**添加成员**」里输入对方的**登录名、手机号或邮箱**，选择角色（默认开发者），点「**添加**」。
 输入框下方提示「管理员：管理成员与应用；开发者：上传、调试与管理。」
 
-| 提示                                     | 含义                                             |
-| ---------------------------------------- | ------------------------------------------------ |
-| 没有找到这个用户                         | 对方还没在本企业开通账号，或登录名 / 手机号 / 邮箱写错 |
-| 该账号匹配到多个用户，请改用登录名添加   | 手机号或邮箱对应了多个账号                       |
-| 该用户已经是成员                         | 需要调整角色请直接修改角色                       |
+| 提示                                   | 含义                                                   |
+| -------------------------------------- | ------------------------------------------------------ |
+| 没有找到这个用户                       | 对方还没在本企业开通账号，或登录名 / 手机号 / 邮箱写错 |
+| 该账号匹配到多个用户，请改用登录名添加 | 手机号或邮箱对应了多个账号                             |
+| 该用户已经是成员                       | 需要调整角色请直接修改角色                             |
 
 ### 修改角色、移除与退出
 
 - **修改角色**（管理员）：在成员行的角色下拉里切换「管理员 / 开发者」；
 - **移除**（管理员）：点成员行的「**移除**」，确认「移除 {名字}？——移除后对方不能再上传或管理这个应用，已上传的版本保留。」；
-- **退出**（任何成员）：在自己那一行点「**退出**」，确认「退出「{应用}」？——退出后你不能再上传或管理这个应用，需要管理员重新添加。」
+- **退出**（自己，且不是旧应用的上传者成员）：在自己那一行点「**退出**」，确认「退出「{应用}」？——退出后你不能再上传或管理这个应用，需要管理员重新添加。」
 
 应用**至少要保留一位管理员**。移除、退出或降级会让应用没有管理员时，操作被拒绝：
 40900「应用至少要保留一位管理员」，处理方式是先把另一位成员设为管理员，再做这个操作。
@@ -99,21 +105,23 @@
 
 ### 旧应用（`app_key`）
 
-用旧 `app_key` 命名空间上传的已有应用，**上传过应用包的人视为管理员**，在成员列表里显示为管理员，但不能在这里修改其角色或移除。
+用旧 `app_key` 命名空间上传的已有应用，**上传过应用包的人视为管理员**，在成员列表里显示为管理员，
+但那一行只有角色标签：没有角色下拉，也没有「移除」/「退出」按钮，不能在这里修改角色或退出。
+（其他通过邀请加入的成员仍按上面的规则管理。）
 
 ## 上传时的成员校验
 
 用 `appid` 的应用，谁能上传由成员决定，Manifest 里的 `publisher` 不再起作用：
 
-| 情况                    | 结果                                                                                                                       |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| `appid` 还没创建        | 40400「appid 不存在」（`detail.reason` 为 `APP_NOT_FOUND`）：先在云开发控制台「创建应用」                                   |
-| 上传者不是应用成员      | 40300「你不是这个应用的开发者」（`detail.reason` 为 `NOT_APP_MEMBER`）：请联系应用管理员在云开发控制台「成员」里把你加为开发者 |
-| 管理员或开发者上传      | 正常上传                                                                                                                   |
+| 情况               | 结果                                                                                                                           |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `appid` 还没创建   | 40400「appid 不存在」（`detail.reason` 为 `APP_NOT_FOUND`）：先在云开发控制台「创建应用」                                      |
+| 上传者不是应用成员 | 40300「你不是这个应用的开发者」（`detail.reason` 为 `NOT_APP_MEMBER`）：请联系应用管理员在云开发控制台「成员」里把你加为开发者 |
+| 管理员或开发者上传 | 正常上传                                                                                                                       |
 
 ## 成员上传的版本
 
-每个成员上传的都是一个**开发版本**，全部列在侧栏「发布」组的「版本管理（文档站 /console/release#版本管理）」里，标出上传者和上传时间：
+用 `appid` 的应用里，每个成员上传的都是一个**开发版本**，全部列在侧栏「发布」组的「版本管理（文档站 /console/release#版本管理）」里，标出上传者和上传时间：
 
 - 任何成员（管理员或开发者）都可以把其中一个「发布为线上版本」，或「回退到此版本」；
 - 「我也用这个」把你本人的安装切到任一成员上传的版本，包括同事还没发布的版本（方便联调）；
@@ -121,16 +129,22 @@
 
 ## 用户授权
 
-侧栏「团队」组的「**用户授权**」页统计使用者通过[授权登录](app-runtime.md#授权登录)给本应用的个人信息：
+侧栏「团队」组的「**用户授权**」页（appid 应用）统计使用者通过[授权登录](app-runtime.md#授权登录)给本应用的个人信息。
+页面说明是「使用者通过授权登录（zl.auth.authorize）给本应用的个人信息：只统计人数，不展示具体用户和手机号。」
 
-| 数字           | 含义                                         |
-| -------------- | -------------------------------------------- |
-| 已授权人数     | 当前同意过至少一项的使用者人数               |
-| 头像和昵称 / 手机号 / 邮箱 | 各项同意人数                     |
-| 已撤销         | 同意过、后来在「已授权信息」里撤销了的人数   |
+| 数字                       | 含义                                       |
+| -------------------------- | ------------------------------------------ |
+| 已授权人数                 | 当前同意过至少一项的使用者人数             |
+| 头像和昵称 / 手机号 / 邮箱 | 各项同意人数                               |
+| 已撤销                     | 同意过、后来在「已授权信息」里撤销了的人数 |
 
 只有人数，**看不到具体用户和手机号**——具体信息只在使用者本人同意后交给应用运行时。每次同意、拒绝、撤销和云函数读取都会记审计日志。
-还没有人授权时显示「还没有人授权」。接口：`GET /api/v1/app-cloud/apps/{app_id}/auth-stats`（成员）。
+还没有人授权时显示「**还没有人授权**」，下方说明：应用调用 `zl.auth.authorize` 并且用户点了「允许」后，这里会显示人数。
+接口：`GET /api/v1/app-cloud/apps/{app_id}/auth-stats`（成员）。
+
+（截图：用户授权页，见文档站）
+
+用户授权页：只展示人数统计，不展示具体用户（图为还没有人授权时的空状态）。
 
 ## 目前的限制