create-zleap-app 0.10.6 → 0.12.0

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

@@ -0,0 +1,304 @@
+# 界面：官方样式 zleap.css 与常用版式
+
+`zleap.css` 随 `@zleap-ai/app-sdk` 分发（包内文件，符合沙箱 CSP）。颜色、圆角、字号与 zleapOS 桌面同源，
+桌面切换亮 / 暗时应用窗口自动跟随（宿主把主题设到窗口上，页面里 `prefers-color-scheme` 随之变化），不需要写代码。
+
+- vanilla：`<link rel="stylesheet" href="./sdk/zleap.css" />`（`npm install` / `npm run deploy` 自动复制到 `app/sdk/`）
+- React：`import '@zleap-ai/app-sdk/zleap.css'`（放在应用自己的 css 之前）
+- 原生模板：`./sdk/zleap.css`
+
+组件类都以 `zl-` 开头；自己的样式只用 `--zl-*` 变量取色，覆盖时改变量，不改 zleap.css。
+
+## 变量
+
+| 变量 | 用途 |
+| --- | --- |
+| `--zl-bg` / `--zl-surface` | 页面底色 / 卡片、列表、输入框底色 |
+| `--zl-ink` / `--zl-ink-muted` / `--zl-ink-faint` | 正文 / 次要文字 / 最弱文字 |
+| `--zl-line` / `--zl-line-strong` | 分隔线 / 控件边框 |
+| `--zl-accent` / `--zl-accent-text` / `--zl-accent-subtle` | 主题色 / 主题色文字 / 主题色浅底 |
+| `--zl-success` `--zl-warning` `--zl-danger`（及 `-subtle`） | 成功 / 提醒 / 危险 |
+| `--zl-radius-sm/md/lg/xl`、`--zl-font-xs/sm/base/lg/xl`、`--zl-shadow` | 圆角、字号、阴影 |
+
+## 类
+
+| 分类 | 类 |
+| --- | --- |
+| 版式 | `zl-page`（`--wide` / `--full`）、`zl-split`（左列表右详情）、`zl-header`、`zl-title`、`zl-subtitle`、`zl-section`、`zl-section-title`、`zl-stack`（`--sm`/`--lg`）、`zl-row`（`--between`/`--end`）、`zl-spacer`、`zl-grid`、`zl-divider` |
+| 卡片 | `zl-card`（`--flat` / `--interactive`）、`zl-card-title` |
+| 文字 | `zl-muted`、`zl-faint`、`zl-text-sm`、`zl-text-xs`、`zl-strong`、`zl-num`（等宽数字）、`zl-text-success`、`zl-text-danger`、`zl-ellipsis`、`zl-prose`（长文本 / AI 结果，保留换行） |
+| 按钮 | `zl-btn` + `--primary` / `--danger` / `--ghost`，尺寸 `--sm` / `--lg` / `--block`；处理中加 `aria-busy="true"`（自动转圈） |
+| 表单 | `zl-field`、`zl-label`、`zl-hint`、`zl-input`（行内编辑加 `--inline`；原生 `type="date"` 可用）、`zl-textarea`、`zl-select`、`zl-check`、`zl-composer`（一行输入 + 按钮）、`zl-segmented`（按钮带 `aria-pressed`）；出错加 `aria-invalid="true"` |
+| 列表 | `zl-list`、`zl-list-item`（完成态 `is-done`；可点选的行用 `<button>`，选中加 `aria-current="true"`）、`zl-item-main`、`zl-item-title`、`zl-item-meta`、`zl-item-actions`（`--hover`：悬停才显示） |
+| 标签 / 状态 | `zl-tag`（`--accent`/`--success`/`--warning`/`--danger`）、`zl-status`（`data-state`：connecting / ready / error / preview） |
+| 提示 | `zl-alert`（`--info`/`--success`/`--warning`/`--danger`）、`zl-toast` |
+| 空 / 加载 | `zl-empty`、`zl-empty-icon`、`zl-empty-title`、`zl-empty-text`、`zl-skeleton`、`zl-spinner` |
+| 数据 | `zl-stats`、`zl-stat`、`zl-stat-label`、`zl-stat-value`、`zl-progress`（内部 `<span style="width:40%">`） |
+| 动效 | `zl-enter`（新出现的块淡入）；系统开启「减少动态效果」时自动关闭 |
+
+## 版式
+
+下面的示例只示意**结构和类名**。中文都是占位，换成你应用自己的文案；凡是数据（列表、数量、时间、状态）都由代码渲染，
+不要把示例里的结构连同内容原样写死在 HTML 里。每块数据都要有加载中 / 出错 / 空 / 有数据四种状态。
+
+vanilla 示例用下面这个小工具建元素：文字一律走 `textContent`，不拼 HTML 字符串（避免把用户输入当成 HTML）。
+React 直接用 JSX，`className` 写同样的类。
+
+```js
+// 建元素：h('li', { class: 'zl-list-item', onclick: fn }, 子元素或文字…)
+export function h(tag, props = {}, ...children) {
+  const el = document.createElement(tag);
+  for (const [key, value] of Object.entries(props)) {
+    if (key.startsWith('on')) el.addEventListener(key.slice(2), value);
+    else if (key === 'class') el.className = value;
+    else if (value === true) el.setAttribute(key, '');
+    else if (value !== false && value != null) el.setAttribute(key, value);
+  }
+  el.append(...children.filter((child) => child != null && child !== false));
+  return el;
+}
+```
+
+### 页面骨架（所有应用）
+
+HTML 里只放固定的骨架，状态和数据由脚本填：
+
+```html
+<main class="zl-page">
+  <header class="zl-header">
+    <div>
+      <h1 class="zl-title">应用名</h1>
+      <p class="zl-subtitle">一句话说明这个应用做什么</p>
+    </div>
+    <span id="status" class="zl-status" data-state="connecting">
+      正在连接
+    </span>
+  </header>
+  <div id="error" class="zl-alert zl-alert--danger" role="alert" hidden>
+    <div><strong id="error-title"></strong><span id="error-text"></span></div>
+    <button id="retry" class="zl-btn zl-btn--sm" type="button">重试</button>
+  </div>
+  <section class="zl-section">…</section>
+</main>
+```
+
+### 列表（筛选、空状态、行内操作）
+
+骨架：
+
+```html
+<section class="zl-section">
+  <div class="zl-section-title">
+    <div id="filters" class="zl-segmented" role="group" aria-label="筛选">
+      <button type="button" data-filter="all">全部</button>
+      <button type="button" data-filter="open">未完成</button>
+    </div>
+    <span id="count" class="zl-num zl-text-sm"></span>
+  </div>
+  <ul id="loading" class="zl-list" aria-busy="true">
+    <li class="zl-list-item">
+      <span class="zl-skeleton" style="width: 60%"></span>
+    </li>
+    <li class="zl-list-item">
+      <span class="zl-skeleton" style="width: 40%"></span>
+    </li>
+  </ul>
+  <ul id="list" class="zl-list" hidden></ul>
+  <div id="empty" class="zl-empty" hidden>
+    <div class="zl-empty-icon" aria-hidden="true">＋</div>
+    <p id="empty-title" class="zl-empty-title"></p>
+    <p id="empty-text" class="zl-empty-text"></p>
+  </div>
+</section>
+```
+
+渲染（`items` 来自集合查询或 OS 接口；`remove` 是你的删除函数）：
+
+```js
+const $ = (id) => document.getElementById(id);
+
+function row(item) {
+  const actions = h('div', { class: 'zl-item-actions zl-item-actions--hover' });
+  // 沙箱里不能用 confirm()：删除用行内二次确认
+  const ask = () => actions.replaceChildren(
+    h('button', {
+      class: 'zl-btn zl-btn--danger zl-btn--sm', type: 'button',
+      onclick: () => remove(item),
+    }, '确认删除'),
+    h('button', {
+      class: 'zl-btn zl-btn--ghost zl-btn--sm', type: 'button',
+      onclick: () => render(),
+    }, '取消'),
+  );
+  actions.append(h('button', {
+    class: 'zl-btn zl-btn--ghost zl-btn--sm', type: 'button', onclick: ask,
+  }, '删除'));
+  return h('li', { class: 'zl-list-item' + (item.done ? ' is-done' : '') },
+    h('div', { class: 'zl-item-main' },
+      h('span', { class: 'zl-item-title' }, item.title),
+      h('span', { class: 'zl-item-meta' }, formatTime(item.updated_at)),
+    ),
+    item.tag && h('span', { class: 'zl-tag zl-tag--accent' }, item.tag),
+    actions,
+  );
+}
+
+function render() {
+  const visible = items.filter((it) => filter === 'all' || !it.done);
+  $('loading').hidden = true;
+  $('count').textContent = items.length ? `${visible.length} 条` : '';
+  $('list').replaceChildren(...visible.map(row));
+  $('list').hidden = visible.length === 0;
+  $('empty').hidden = visible.length > 0;
+  // 空状态分两种：真的没有数据 / 筛选后没有
+  $('empty-title').textContent = items.length ? '没有符合条件的' : '还没有内容';
+  $('empty-text').textContent = items.length
+    ? '换个筛选看看。'
+    : '告诉用户下一步做什么，比如「在上面新建第一条」。';
+  for (const btn of $('filters').querySelectorAll('button')) {
+    btn.setAttribute('aria-pressed', String(btn.dataset.filter === filter));
+  }
+}
+```
+
+React 写法相同，按状态返回不同的块：
+
+```tsx
+if (loading) return <ListSkeleton />;
+if (error) return <Alert tone="danger" onRetry={reload}>{error}</Alert>;
+if (items.length === 0) return <Empty title="还没有内容" text="下一步做什么" />;
+return (
+  <ul className="zl-list">
+    {items.map((item) => (
+      <li key={item._id} className="zl-list-item">
+        <div className="zl-item-main">
+          <span className="zl-item-title">{item.title}</span>
+          <span className="zl-item-meta">{formatTime(item.updated_at)}</span>
+        </div>
+      </li>
+    ))}
+  </ul>
+);
+```
+
+### 表单 / 输入区（卡片包裹）
+
+```html
+<form id="form" class="zl-card zl-stack">
+  <div class="zl-field">
+    <label class="zl-label" for="name">字段名</label>
+    <input id="name" class="zl-input" required />
+  </div>
+  <div class="zl-field">
+    <label class="zl-label" for="body">长文本字段</label>
+    <textarea id="body" class="zl-textarea" rows="6"></textarea>
+    <span class="zl-hint">告诉用户怎么填</span>
+  </div>
+  <div class="zl-row zl-row--end">
+    <button id="submit" class="zl-btn zl-btn--primary" type="submit">
+      提交
+    </button>
+  </div>
+</form>
+```
+
+提交时按钮加 `aria-busy="true"` 并禁用，结束后恢复；校验失败给对应输入框加 `aria-invalid="true"`，
+在 `zl-hint` 里写原因。
+
+### 左列表右详情（记录列表 + 当前项）
+
+```html
+<main class="zl-page zl-page--wide">
+  <header class="zl-header">…</header>
+  <div class="zl-split">
+    <aside class="zl-stack zl-stack--sm">
+      <button id="new" class="zl-btn zl-btn--primary zl-btn--block"
+        type="button">新建</button>
+      <div id="records" class="zl-list"></div>
+    </aside>
+    <section id="detail" class="zl-card zl-stack"></section>
+  </div>
+</main>
+```
+
+```js
+function recordButton(record) {
+  return h('button', {
+    class: 'zl-list-item', type: 'button',
+    'aria-current': record._id === selectedId ? 'true' : false,
+    onclick: () => select(record._id),
+  },
+    h('span', { class: 'zl-item-main' },
+      h('span', { class: 'zl-item-title zl-ellipsis' }, record.title),
+      h('span', { class: 'zl-item-meta' }, formatTime(record.updated_at)),
+    ),
+  );
+}
+```
+
+- 窗口窄于 720px 时自动上下排；宽窗口里左栏吸顶、单独滚动；
+- 没有记录时左栏放 `zl-empty`，右栏直接显示新建表单，不要两边都空；
+- 切换选中项时右栏先显示骨架，再填详情。
+
+### 行内可编辑字段（日期、负责人这类）
+
+```js
+function dateField(item) {
+  const input = h('input', {
+    class: 'zl-input zl-input--inline', type: 'date',
+    value: item.due ?? '', 'aria-label': '日期',
+  });
+  input.addEventListener('change', async () => {
+    const before = item.due ?? '';
+    try {
+      await save(item, { due: input.value || null });
+    } catch (error) {
+      input.value = before; // 保存失败：值改回去并提示
+      toast('没有保存：' + describe(error));
+    }
+  });
+  return input;
+}
+```
+
+- `zl-input--inline` 平时像文字，悬停 / 聚焦才显出边框，适合放在列表行里；
+- 原生 `type="date"`、`type="time"` 在沙箱里可用，弹出的日历也跟随亮 / 暗；原生 `<select>` 也可用，
+  选项少（≤ 5）时 `zl-segmented` 更好点。
+
+### 统计 + 占比
+
+数值由数据计算，骨架里留空：
+
+```js
+$('stats').replaceChildren(
+  ...summary.map(({ label, value, tone }) =>
+    h('div', { class: 'zl-stat' },
+      h('div', { class: 'zl-stat-label' }, label),
+      h('div', { class: 'zl-stat-value' + (tone ? ` zl-text-${tone}` : '') },
+        value),
+    ),
+  ),
+);
+const bar = (percent) =>
+  h('div', { class: 'zl-progress' },
+    h('span', { style: `width: ${Math.round(percent)}%` }));
+```
+
+### AI 结果（耗时操作）
+
+- 点击后按钮 `aria-busy="true"`，旁边一句 `<span class="zl-muted zl-text-sm">` 说明预计要多久；
+- 结果放进 `zl-card`，正文用 `zl-prose`，要点用列表，新出现的块加 `zl-enter`；
+- 失败用 `zl-alert--danger` 显示原因和「重试」。
+
+### 卡片网格（多个对象并列）
+
+`<div class="zl-grid">` 里放若干 `<article class="zl-card zl-card--interactive">`，每张卡片：标题 `zl-card-title`、
+一行 `zl-item-meta`、底部 `zl-row` 放标签或操作；同样由数据渲染。
+
+## 交付前自查
+
+1. `npm run preview` 打开，亮色、暗色各看一遍（浏览器或系统切换外观）；
+2. 有数据、空、加载中、出错四种状态都能看到合理的界面；
+3. 窗口缩窄到 400px 左右不出现横向滚动、按钮不挤成两行；
+4. 只用 `--zl-*` 变量取色；每屏最多一个 `zl-btn--primary`；
+5. 部署后在 zleapOS 里打开再看一眼（真实数据量、真实错误提示）。

package/skills/zleap-cloud-app-release/references/app-center-install.md

@@ -184,7 +184,7 @@
 **更新时授权怎么处理**（`appversion/apply.go`）：
 
 - 新版本的 `requires` **没有变宽**：除后台能力外的授权（含 Cloud 数据读写、数据权限）原样延续到新版本；
-- `requires` **变宽**（新增能力或范围）：这些授权全部撤销，**不会自动重新授予**——重新打开应用后要在应用窗口「权限」（含底部「管理其他权限」）里重新勾选保存；
+- `requires` **变宽**（新增能力或范围）：这些授权全部撤销，**不会自动重新授予**——重新打开应用后要在应用窗口「权限」（含底部「管理其他权限」）里重新勾选保存。打开窗口时宿主会主动弹出缺的授权：云数据授权缺项时弹「应用权限」，安装级权限缺项时弹「数据权限」（每个版本只主动弹一次，缺的项已预先勾好）；
 - 后台能力逐项比较：权限没变宽的「延续」，变宽的「需要重新确认」，新版本删掉的「已移除」；
 - 运行会话、文件票据一律作废，应用会重新加载。
 
@@ -234,10 +234,10 @@ CLI 走的是开发会话接口（`appinstallation/version.go` 的 `SwitchVersio
 
 「权限」按钮打开哪个对话框，取决于应用声明了什么：
 
-| 应用声明                                                                             | 点「权限」                                                                                                       |
-| ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
-| 用了 Cloud：有 `runtime.backend`，或 `requires` 里有 `cloud.*` / `os.agent.complete` | 打开「应用权限」对话框（见下文）；若还声明了安装级权限，对话框底部有「**管理其他权限**」，进入「数据权限」对话框 |
-| 只声明了安装级权限（`storage.kv` / `space.read` / `space.write` / `notify.send`）    | 直接打开「数据权限」对话框                                                                                       |
+| 应用声明                                                                                                                                                                       | 点「权限」                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
+| 用了 Cloud：有 `runtime.backend`，或 `requires` 里有 `cloud.*` / `os.agent.complete`                                                                                           | 打开「应用权限」对话框（见下文）；若还声明了安装级权限，对话框底部有「**管理其他权限**」，进入「数据权限」对话框 |
+| 只声明了安装级权限（`storage.kv` / `space.read` / `space.write` / `notify.send`，或 `host_api.requires` 里的 `clipboard.write` / `workspace.files` / `workspace.images.read`） | 直接打开「数据权限」对话框                                                                                       |
 
 两类授权对应服务端两套独立闸门，**不要混为一谈**。
 
@@ -304,6 +304,8 @@ CLI 走的是开发会话接口（`appinstallation/version.go` 的 `SwitchVersio
 
 入口：「应用权限」对话框底部的「**管理其他权限**」；只声明了安装级权限、没用 Cloud 的应用，点窗口顶部「**权限**」直接打开。
 
+当前版本声明了、但还没授权的安装级权限（例如新版本新加了 `storage`），打开应用窗口时会自动弹出这个对话框，并预先勾好缺的项；每个版本只主动弹一次，关掉后从入口自己改。没授权时应用调用会收到 40300，错误信息里写明缺哪项权限、去哪里开。
+
 **标题**：`{应用名}` 的数据权限
 
 **说明**：
@@ -316,12 +318,17 @@ CLI 走的是开发会话接口（`appinstallation/version.go` 的 `SwitchVersio
 
 **复选框**（只列出该版本声明的项）：
 
-| 复选框文案                   | 对应能力      |
-| ---------------------------- | ------------- |
-| **读取和保存此应用的设置**   | `storage.kv`  |
-| **读取此应用中的个人文件**   | `space.read`  |
-| **为此应用创建个人文件版本** | `space.write` |
-| **发送此应用的通知**         | `notify.send` |
+| 复选框文案                               | 对应能力                |
+| ---------------------------------------- | ----------------------- |
+| **读取和保存此应用的设置**               | `storage.kv`            |
+| **读取此应用中的个人文件**               | `space.read`            |
+| **为此应用创建个人文件版本**             | `space.write`           |
+| **发送此应用的通知**                     | `notify.send`           |
+| **写入剪贴板**                           | `clipboard.write`       |
+| **读取及整理你选定的空间文件夹内的文件** | `workspace.files`       |
+| **读取你选定的空间文件夹内的图片**       | `workspace.images.read` |
+
+后三项是 `host_api.requires` 里的宿主能力：安装时一并授予；**新版本才声明**的（切换版本不会自动授予），打开应用时同样自动弹出这个对话框让你补授权。
 
 **按钮**：撤销全部 / 关闭 / 保存（未改动时不可点）
 
@@ -338,6 +345,7 @@ CLI 走的是开发会话接口（`appinstallation/version.go` 的 `SwitchVersio
 
 声明了 `host_api.requires: ["workspace.files"]` 的应用，在调用时会弹出「选择工作文件夹 · {应用}」，其中写明：
 「应用权限已在安装时授予。这里只选择工作范围；实际操作仍受你的空间权限限制。」——即这里**不是**再授权一次，只是选范围。
+新版本才声明 `workspace.files` 时，授权在「数据权限」对话框里补（打开应用会自动弹出），之后再选文件夹。
 
 ### 已授权信息
 

package/skills/zleap-cloud-app-release/references/app-center-publish.md

@@ -14,7 +14,7 @@
 >
 >
 > - **上传**：把 ZIP 变成一个固定版本。每次上传得到的都是**开发版本**，只有应用成员看得到、装得上。
-> - **发布为线上版本**（CLI 叫 `release`）：在云开发控制台「版本管理」里把**某一个开发版本**设为线上版本，全企业可见。**没有审核步骤**。在「我的发布」里点成员版本的「**去版本管理发布**」也能直接打开对应入口。
+> - **发布为线上版本**（CLI 叫 `release`）：在云开发控制台「版本管理」里把**某一个开发版本**设为线上版本，全企业可见。**没有审核步骤**。在「我的发布」里点开发版本的「**去版本管理发布**」也能直接打开对应入口。
 > - **回退**：把旧版本再发布一次，控制台里的按钮是「**回退到此版本**」。
 > - **签名与绑定**（让云函数 / 后台任务能跑）：带后台（headless）能力的版本上传时平台自动签名；安装、切换版本、允许后台运行时如果缺签，平台会自动补签并绑定，不需要手动操作。
 >
@@ -47,7 +47,7 @@
 
 1. 点「**上传应用包**」。
 2. 选择 `.zip` 文件。
-3. 等待上传完成。列表刷新后，新版本出现在应用卡片里，初始是「**仅成员可见**」的开发版本。
+3. 等待上传完成。列表刷新后，新版本出现在应用卡片里，初始是「**仅本人和开发人员可见**」的开发版本。
 
 要让同事用上，点这个版本行上的「**去版本管理发布**」，或在云开发控制台「版本管理」里点「**发布为线上版本**」。
 
@@ -126,7 +126,7 @@
 
 ### 版本列表
 
-展开后标题「**版本列表**」，说明：「这是 appid 应用：每次上传都是只有应用成员可见的开发版本，在云开发控制台「版本管理」里发布为线上版本后全企业可见。」
+展开后标题「**版本列表**」，说明：「这是 appid 应用：每次上传都是仅本人和开发人员可见的开发版本，在云开发控制台「版本管理」里发布为线上版本后全企业可见。」
 
 每一行：
 
@@ -134,14 +134,14 @@
 | ---- | ---------------------------------------------------------------------------------------------------- |
 | 左   | 版本号；最新上传的那一行带「**最近上传**」标记                                                       |
 | 中   | 上传时间、包大小                                                                                     |
-| 状态 | 「**仅成员可见**」或「**企业可见**」；已停用的版本另有「**已停用**」                                 |
-| 按钮 | 成员版本：「**去版本管理发布**」；已发布为线上版本的：「**云开发**」→ 打开控制台版本页并定位到该版本 |
+| 状态 | 「**仅本人和开发人员可见**」或「**企业可见**」；已停用的版本另有「**已停用**」                                 |
+| 按钮 | 开发版本：「**去版本管理发布**」；已发布为线上版本的：「**云开发**」→ 打开控制台版本页并定位到该版本 |
 
 已停用的版本没有「去版本管理发布」按钮，「云开发」按钮也不可点。
 
 > **版本行的两种状态**（提示）
 >
-> 开发版本显示「**仅成员可见**」和「**去版本管理发布**」；发布为线上版本后，这一行变为「**企业可见**」并保留「**云开发**」按钮。
+> 开发版本显示「**仅本人和开发人员可见**」和「**去版本管理发布**」；发布为线上版本后，这一行变为「**企业可见**」并保留「**云开发**」按钮。
 > 卡片统计始终是「**企业 n / 开发版本 n**」。
 
 ## 发布为线上版本

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

@@ -7,7 +7,7 @@
 
 > **应用中心「我的发布」与这里的关系**（提示）
 >
-> `appid` 应用的版本在应用中心显示「**仅成员可见**」（卡片统计为「企业 n / 开发版本 n」），成员版本上的主按钮是「**去版本管理发布**」，
+> `appid` 应用的版本在应用中心显示「**仅本人和开发人员可见**」（卡片统计为「企业 n / 开发版本 n」），开发版本上的主按钮是「**去版本管理发布**」，
 > 点它会打开本页；已发布的版本显示「**企业可见**」，并保留「**云开发**」按钮。上线、回退都在本页完成。
 
 ## 版本管理

package/skills/zleap-cloud-app-release/references/dev-to-production.md

@@ -125,6 +125,72 @@ npm run deploy
 - 命令是 `zleap-app test <plan.json> --runner-config <运行器配置>`，第一个参数是**计划文件**，不是应用目录；
 - 报告用 `zleap-app logs <report_id>` 查看。只用专用测试账号和测试数据。
 
+#### 验收计划怎么写
+
+验收由运维或你本人在本机准备的「运行器」执行，分两份文件：运行器配置（含测试账号，只放本机）和验收计划（描述要点什么、核对什么）。
+AI 工具通过 MCP 调用时用同一份运行器配置：启动 `zleap-app mcp serve` 时加 `--runner-config`，再用 `app_test` 提交计划。
+
+**运行器配置**：JSON 文件，权限 0600，放在应用目录之外，绝不能打进应用包。
+
+| 字段                                  | 说明                                                                                                                                                   |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `node`、`puppeteer_module`、`browser` | Node.js（≥ 22.12）、Puppeteer Core（≥ 25）入口和 Chrome 可执行文件的绝对路径                                                                           |
+| `auth_file`                           | 测试账号认证 JSON 的绝对路径（含 `access_token`，可含 `refresh_token`，0600）。由你用专用账号正常登录获得，只给运行器读取，不能放进 MCP 参数或交给应用 |
+| `os_url`、`target`                    | 目标 OS 地址                                                                                                                                           |
+| `app_key`                             | 固定为本应用（appid）                                                                                                                                  |
+| `app_id`、`app_name`                  | 可留空，由当前会话的发布记录按不可变 `version_id` 解析                                                                                                 |
+| `allow_mutation`                      | 必须显式写 `true`，表示允许验收写入专用测试数据                                                                                                        |
+| `probes`                              | 探针名到同一部署只读 API 路径的映射，例如 `{"todos": "/api/v1/…"}`；参数按 `app_api_get` 查到的契约填写                                                |
+
+测试账号必须和开发会话是同一个账号。可用的探针名可以用 `app_caps_get` 查看（`acceptance_runner.configured` 与 `probe_names`），
+计划里只能引用这里配置过的探针，不接受应用传入新的 URL、身份、脚本或浏览器跳转。
+
+**验收计划**：`app_key`、`version_id` 和 4 到 128 个 `steps`。每一步都要写 `phase`，取值 `read`、`write` 或 `persistence`；
+`target` 可选 `app`（应用窗口内）或 `host`（宿主页面）。可用的动作：
+
+| 动作                      | 必填字段                                                     | 说明                                                                                       |
+| ------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
+| `click`、`fill`、`select` | `selector`                                                   | 交互，`fill` / `select` 用 `value` 给出要填或要选的值；放在 `write` 阶段时算一次真实写操作 |
+| `click_text`              | `text`                                                       | 按文字点击                                                                                 |
+| `assert_text`             | `text`                                                       | 页面出现指定文字                                                                           |
+| `assert_count`            | `selector`、`count`（0–10000）                               | 匹配元素的数量                                                                             |
+| `assert_image`            | `selector`                                                   | 图片必须真正解码成功、宽高非零，只检查有 `img` 标签不算通过                                |
+| `probe`                   | `probe`，以及 `expected` 或非空 `contains`（可配 `pointer`） | 用运行器配置里的探针独立读取数据核对                                                       |
+| `reload`                  | —                                                            | 刷新页面                                                                                   |
+
+编排规则，运行器会逐条校验：
+
+1. 必须有 `read` 阶段的断言。
+2. 必须有 `write` 阶段的真实写操作，并在写之后用 `probe` 独立核对数据。
+3. `reload` 只能放在写操作和写后探针之后。
+4. `persistence` 阶段的断言必须在 `reload` 之后，证明刷新后数据还在。
+
+示例（待办应用：读取列表，新增一条，探针核对，刷新后确认还在）：
+
+```json
+{
+  "app_key": "<appid>",
+  "version_id": "<要验收的版本 ID>",
+  "steps": [
+    { "phase": "read", "action": "assert_text", "target": "app", "text": "待办" },
+    {
+      "phase": "write",
+      "action": "fill",
+      "target": "app",
+      "selector": "input[name=title]",
+      "value": "验收-001"
+    },
+    { "phase": "write", "action": "click_text", "target": "app", "text": "添加" },
+    { "phase": "write", "action": "probe", "probe": "todos", "contains": "验收-001" },
+    { "phase": "persistence", "action": "reload" },
+    { "phase": "persistence", "action": "assert_text", "target": "app", "text": "验收-001" }
+  ]
+}
+```
+
+选择器和文字按你自己的页面填写，动作名以 `app_spec_get(section=acceptance)` 返回的 schema 为准。
+报告 `status` 为 `passed` 且 `browser_tested` 为 `true` 才算通过。验收期间如果版本发生变化，结果作废，需要重新验收。
+
 （截图：部署后的应用窗口：OS 已连接，能读写待办，见文档站）
 
 > **开发环境只对应用成员开放**（说明）
@@ -200,7 +266,7 @@ npm run release -- --notes "本次更新说明"
 
 > **应用中心「我的发布」里的版本**（提示）
 >
-> 版本行显示「**仅成员可见**」，卡片统计是「企业 n / 开发版本 n」。成员版本的主按钮是「**去版本管理发布**」，点它打开云开发控制台「版本管理」；
+> 版本行显示「**仅本人和开发人员可见**」，卡片统计是「企业 n / 开发版本 n」。开发版本的主按钮是「**去版本管理发布**」，点它打开云开发控制台「版本管理」；
 > 已发布的版本显示「**企业可见**」并保留「**云开发**」按钮。上线统一在「版本管理」里点「发布为线上版本」。
 
 > **第一次发布没成功**（提示）

package/skills/zleap-cloud-app-release/references/status-codes.md

@@ -145,15 +145,15 @@
 
 ### 数据
 
-| 错误码                 | 含义                                       | 处理                                                        |
-| ---------------------- | ------------------------------------------ | ----------------------------------------------------------- |
-| `SCHEMA_INVALID`       | 参数或文档不符合规则（含大小、嵌套等超限） | 见本页末尾「排查：`SCHEMA_INVALID`」                        |
-| `VERSION_CONFLICT`     | 乐观锁冲突，或键已存在等 409 类错误        | 重新读取最新版本再改                                        |
-| `DOCUMENT_NOT_FOUND`   | 文档不存在（或 404 类错误）                | 检查文档键；读取时可用 `throwOnNotFound: false`             |
-| `COLLECTION_NOT_FOUND` | 集合不存在                                 | 在 Manifest `data.collections` 声明；生产环境要单独开通集合 |
+| 错误码                 | 含义                                         | 处理                                                                             |
+| ---------------------- | -------------------------------------------- | -------------------------------------------------------------------------------- |
+| `SCHEMA_INVALID`       | 参数或文档不符合规则（含大小、嵌套等超限）   | 见本页末尾「排查：`SCHEMA_INVALID`」                                             |
+| `VERSION_CONFLICT`     | 乐观锁冲突，或键已存在等 409 类错误          | 重新读取最新版本再改                                                             |
+| `DOCUMENT_NOT_FOUND`   | 文档不存在（或 404 类错误）                  | 检查文档键；读取时可用 `throwOnNotFound: false`                                  |
+| `COLLECTION_NOT_FOUND` | 集合不存在                                   | 在 Manifest `data.collections` 声明；生产环境要单独开通集合                      |
 | `SCOPE_FORBIDDEN`      | 读写了 manifest **没声明**的集合（或没授权） | 先在 `data.collections` 声明再部署；已声明还报这个，看「权限」里是否勾了数据读写 |
-| `INDEX_REQUIRED`       | 查询需要扫描的行数超过单次上限             | 给筛选字段建索引；已有索引仍超限时缩小筛选范围              |
-| `RESOURCE_NOT_READY`   | 云数据库正在开通，或数据服务还没加载本应用 | 通常一分钟内自动就绪，稍后刷新重试                          |
+| `INDEX_REQUIRED`       | 查询需要扫描的行数超过单次上限               | 给筛选字段建索引；已有索引仍超限时缩小筛选范围                                   |
+| `RESOURCE_NOT_READY`   | 云数据库正在开通，或数据服务还没加载本应用   | 通常一分钟内自动就绪，稍后刷新重试                                               |
 
 ### 文件存储
 
@@ -419,6 +419,10 @@
 `zleap-app publish` 等写操作网络结果不明时返回 `COMMIT_UNKNOWN`，**不会自动重传**：
 用 `zleap-app operation --request-id <原操作号>` 或 `zleap-app status` 查询原结果。
 
+`zleap-app business get` / `call`（以及 MCP 的 `os_business_get` / `os_business_call`）请求超管、账号与组织、内部控制或未审核的接口时，
+返回 403 `OPERATION_NOT_EXPOSED`。应用页面直接调用 OS 接口时，未向应用开放的接口同样返回 `OPERATION_NOT_EXPOSED`（「该接口未向应用开放」）。
+这类接口不会开放，先用 `business search` 找可用的替代接口。
+
 ## 上传与 Manifest 校验
 
 上传、`zleap-app check` 或安装时，Manifest 相关失败通过 `detail.reason` 返回：
@@ -524,18 +528,18 @@
 平台在上传带后台能力的版本时自动签发开发发布，首次发布为线上版本时自动签发生产发布。
 签发或验签失败时按原因码归类返回：
 
-| 服务端原因码                                                                      | 含义                                                                     |
-| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
-| `RELEASE_PROOF_TOO_LARGE`                                                         | 证明文件超过 2 MiB 限制                                                  |
-| `RELEASE_PROOF_INVALID`                                                           | 证明 JSON 或签名信封无效                                                 |
-| `RELEASE_IDENTITY_MISMATCH`、`RELEASE_DIGEST_MISMATCH`、`RELEASE_SOURCE_MISMATCH` | 证明与当前应用、发布、包、来源、摘要或策略不匹配                         |
-| `RELEASE_SIGNATURE_INVALID`                                                       | 无法验证发布签名                                                         |
-| `RELEASE_ARTIFACT_MISMATCH`、`RELEASE_MANIFEST_MISMATCH`                          | 签名 Manifest 或包制品清单不匹配                                         |
-| `RELEASE_POLICY_STALE`                                                            | 策略审核已过期或不是当前策略                                             |
-| `RELEASE_POLICY_UNAVAILABLE`                                                      | 尚未配置发布策略，无法验证                                               |
-| `RELEASE_TRUST_UNAVAILABLE`                                                       | 发布信任策略尚未配置，或发布者密钥不可用、已撤销或已过期；由管理员检查   |
-| `RELEASE_DISABLED`                                                                | 发布候选已撤回                                                           |
-| 其他                                                                              | 签名验证请求被拒绝                                                       |
+| 服务端原因码                                                                      | 含义                                                                   |
+| --------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `RELEASE_PROOF_TOO_LARGE`                                                         | 证明文件超过 2 MiB 限制                                                |
+| `RELEASE_PROOF_INVALID`                                                           | 证明 JSON 或签名信封无效                                               |
+| `RELEASE_IDENTITY_MISMATCH`、`RELEASE_DIGEST_MISMATCH`、`RELEASE_SOURCE_MISMATCH` | 证明与当前应用、发布、包、来源、摘要或策略不匹配                       |
+| `RELEASE_SIGNATURE_INVALID`                                                       | 无法验证发布签名                                                       |
+| `RELEASE_ARTIFACT_MISMATCH`、`RELEASE_MANIFEST_MISMATCH`                          | 签名 Manifest 或包制品清单不匹配                                       |
+| `RELEASE_POLICY_STALE`                                                            | 策略审核已过期或不是当前策略                                           |
+| `RELEASE_POLICY_UNAVAILABLE`                                                      | 尚未配置发布策略，无法验证                                             |
+| `RELEASE_TRUST_UNAVAILABLE`                                                       | 发布信任策略尚未配置，或发布者密钥不可用、已撤销或已过期；由管理员检查 |
+| `RELEASE_DISABLED`                                                                | 发布候选已撤回                                                         |
+| 其他                                                                              | 签名验证请求被拒绝                                                     |
 
 签发时的 `RELEASE_POLICY_UNAVAILABLE`、`RELEASE_TRUST_UNAVAILABLE` 属于**部署未配置**；
 发布生产版本时的 `RELEASE_TRUST_UNAVAILABLE` 则表示这个发布的签名与当前信任策略对不上，重新发布即可（见 [发布与生产门禁](#发布与生产门禁)）。

package/templates/_shared/.cursor/mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "zleap-app": {
+      "command": "npx",
+      "args": [
+        "zleap-app",
+        "mcp",
+        "serve",
+        "--workspace",
+        "."
+      ]
+    }
+  }
+}

package/templates/_shared/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "zleap-app": {
+      "command": "npx",
+      "args": [
+        "zleap-app",
+        "mcp",
+        "serve",
+        "--workspace",
+        "."
+      ]
+    }
+  }
+}