create-zleap-app 0.10.6 → 0.12.0
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.
- package/index.js +16 -14
- package/lib/scaffold.js +18 -5
- package/package.json +4 -4
- package/skills/zleap-cloud-app/SKILL.md +47 -11
- package/skills/zleap-cloud-app/references/cloud-functions.md +11 -6
- package/skills/zleap-cloud-app/references/limits.md +22 -19
- package/skills/zleap-cloud-app/references/sdk-database-files.md +4 -4
- package/skills/zleap-cloud-app/references/status-codes.md +24 -20
- package/skills/zleap-cloud-app/references/ui.md +304 -0
- package/skills/zleap-cloud-app-release/references/app-center-install.md +19 -11
- package/skills/zleap-cloud-app-release/references/app-center-publish.md +6 -6
- package/skills/zleap-cloud-app-release/references/console-release.md +1 -1
- package/skills/zleap-cloud-app-release/references/dev-to-production.md +67 -1
- package/skills/zleap-cloud-app-release/references/status-codes.md +24 -20
- package/templates/_shared/.cursor/mcp.json +14 -0
- package/templates/_shared/.mcp.json +14 -0
- package/templates/{react-ts → _shared}/scripts/zleap.mjs +138 -83
- package/templates/react-ts/AGENTS.md +9 -3
- package/templates/react-ts/package.json +4 -0
- package/templates/react-ts/src/App.tsx +227 -96
- package/templates/react-ts/src/cloud/client.ts +21 -6
- package/templates/react-ts/src/cloud/preview.ts +116 -0
- package/templates/react-ts/src/cloud/useCloudConnection.ts +2 -2
- package/templates/react-ts/src/index.css +5 -241
- package/templates/react-ts/src/main.tsx +3 -0
- package/templates/vanilla/AGENTS.md +37 -0
- package/templates/vanilla/CLAUDE.md +1 -0
- package/templates/vanilla/README.md +37 -0
- package/templates/vanilla/_gitignore +7 -0
- package/templates/vanilla/app/LICENSE +21 -0
- package/templates/vanilla/app/index.html +67 -0
- package/templates/vanilla/app/main.js +222 -0
- package/templates/vanilla/app/manifest.json +33 -0
- package/templates/vanilla/app/preview.js +114 -0
- package/templates/vanilla/app/style.css +5 -0
- package/templates/vanilla/package.json +32 -0
|
@@ -1,27 +1,35 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
// 项目内的一键命令,封装 zleap-app CLI:
|
|
3
3
|
//
|
|
4
|
-
// npm run login [-- --target https://os.example.com]
|
|
5
|
-
// npm run deploy [-- --no-build] [--no-install] 构建 → 检查 →
|
|
4
|
+
// npm run login [-- --target https://os.example.com] [--browser-timeout 10m] 浏览器授权,保存开发会话(自动续期,最长 30 天)
|
|
5
|
+
// npm run deploy [-- --no-build] [--no-install] 构建 → 检查 → zleap-app deploy(上传开发版本 → 安装/切换 → 按诊断准备资源)
|
|
6
6
|
// npm run status 查看本应用的安装、权限与可用版本
|
|
7
7
|
// npm run versions 列出全部成员上传的开发版本、当前线上版本和发布记录
|
|
8
8
|
// npm run release [-- --version-id <id>] [--notes 说明] [--yes]
|
|
9
9
|
// 把开发版本(默认最近一次 deploy 的)发布为线上版本;回退 = 发布旧版本
|
|
10
10
|
// npm run logs [-- --environment dev|prod] [--invocation <调用编号>]
|
|
11
11
|
// 查看最近 24 小时应用页面上报的错误与本人云函数日志
|
|
12
|
+
// npm run preview [-- --port 5180] 预览模式:浏览器直接打开页面,用示例数据渲染界面(调样式、截图自查)
|
|
13
|
+
// node scripts/zleap.mjs sdk vanilla 模板:把 Cloud SDK 从 node_modules 复制进应用目录
|
|
12
14
|
//
|
|
13
15
|
// 设计约束(与平台一致):结果未知(COMMIT_UNKNOWN)时不自动重试;不替你做数据迁移;不碰生产环境。
|
|
14
16
|
import { spawnSync } from 'node:child_process';
|
|
15
|
-
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
16
|
-
import {
|
|
17
|
+
import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
|
|
18
|
+
import { createServer } from 'node:http';
|
|
19
|
+
import { dirname, extname, join, normalize, resolve, sep } from 'node:path';
|
|
17
20
|
import { createInterface } from 'node:readline/promises';
|
|
18
21
|
import { fileURLToPath } from 'node:url';
|
|
19
22
|
|
|
20
23
|
const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
|
21
24
|
const stateDir = join(root, '.zleap'); // zleap-app pack 会排除 .zleap/,且已写入 .gitignore
|
|
22
25
|
const configFile = join(stateDir, 'config.json');
|
|
23
|
-
const stateFile = join(stateDir, 'state.json');
|
|
24
|
-
|
|
26
|
+
const stateFile = join(stateDir, 'state.json'); // 由 zleap-app deploy 写入,本脚本只读
|
|
27
|
+
// 项目形态写在 package.json 的 zleap 字段:packageDir 是上传的目录,build=false 表示不用构建(vanilla 模板),
|
|
28
|
+
// sdkDir 是要从 node_modules 复制 Cloud SDK 的目录。React 模板缺省为 dist/ + 构建。
|
|
29
|
+
const project = { packageDir: 'dist', build: true, sdkDir: '', ...(readJSON(join(root, 'package.json'), {}).zleap ?? {}) };
|
|
30
|
+
const packageDir = project.packageDir;
|
|
31
|
+
// 构建型项目的 manifest 在项目根目录(构建时复制进产物);不构建的项目 manifest 就在上传目录里。
|
|
32
|
+
const manifestFile = existsSync(join(root, 'manifest.json')) ? join(root, 'manifest.json') : join(root, packageDir, 'manifest.json');
|
|
25
33
|
|
|
26
34
|
const argv = process.argv.slice(2);
|
|
27
35
|
const command = argv[0];
|
|
@@ -55,14 +63,14 @@ function cliCommand() {
|
|
|
55
63
|
return { file: bin, prefix: [], shell: process.platform === 'win32' };
|
|
56
64
|
}
|
|
57
65
|
|
|
58
|
-
/** 调用 zleap-app。capture=true 时解析 stdout 中的 JSON
|
|
59
|
-
function cli(args, { capture = true } = {}) {
|
|
66
|
+
/** 调用 zleap-app。capture=true 时解析 stdout 中的 JSON;liveStderr=true 时进度(如授权链接)直接显示在终端。 */
|
|
67
|
+
function cli(args, { capture = true, liveStderr = false } = {}) {
|
|
60
68
|
const { file, prefix, shell } = cliCommand();
|
|
61
69
|
const result = spawnSync(file, [...prefix, ...args], {
|
|
62
70
|
cwd: root,
|
|
63
71
|
shell,
|
|
64
72
|
encoding: 'utf8',
|
|
65
|
-
stdio: capture ? ['inherit', 'pipe', 'pipe'] : 'inherit',
|
|
73
|
+
stdio: capture ? ['inherit', 'pipe', liveStderr ? 'inherit' : 'pipe'] : 'inherit',
|
|
66
74
|
});
|
|
67
75
|
if (result.error) throw new StepError(`无法运行 zleap-app:${result.error.message}`);
|
|
68
76
|
// 被信号杀掉时 status 为 null、没有任何输出(例如 macOS 拒绝运行签名缓存不一致的二进制会发 SIGKILL)。
|
|
@@ -100,9 +108,9 @@ function needLogin(stderr) {
|
|
|
100
108
|
|
|
101
109
|
function manifest() {
|
|
102
110
|
const value = readJSON(manifestFile);
|
|
103
|
-
// appid
|
|
111
|
+
// appid 由平台生成:npm run login 时自动新建,或在云开发控制台「创建应用」后填入;旧项目写的是 app_key,同样可用
|
|
104
112
|
if (!value?.appid && !value?.app_key)
|
|
105
|
-
throw new StepError('manifest.json
|
|
113
|
+
throw new StepError('manifest.json 还没有 appid:先运行 npm run login(会在授权时自动新建应用),或把云开发控制台里应用的 appid 填进 manifest.json');
|
|
106
114
|
return value;
|
|
107
115
|
}
|
|
108
116
|
|
|
@@ -133,13 +141,30 @@ async function login() {
|
|
|
133
141
|
let target = option('target') || process.env.ZLEAP_TARGET || config.target;
|
|
134
142
|
if (!target) target = await ask('zleapOS 地址(例如 https://os.example.com):', '');
|
|
135
143
|
if (!target) throw new StepError('请提供 OS 地址:npm run login -- --target https://os.example.com');
|
|
136
|
-
const
|
|
137
|
-
|
|
138
|
-
|
|
144
|
+
const value = readJSON(manifestFile, {});
|
|
145
|
+
const appKey = appIdOf(value);
|
|
146
|
+
let args;
|
|
147
|
+
if (appKey) {
|
|
148
|
+
log(`登录 ${target}(应用 ${appKey})。浏览器打开后,核对页面与终端里的确认码一致再允许。`);
|
|
149
|
+
args = ['auth', 'login', '--target', target, '--app-key', appKey];
|
|
150
|
+
} else {
|
|
151
|
+
// 还没有 appid:在同一次授权里新建应用(本人为管理员,一次授权最多建一个),CLI 把 appid 写回 manifest.json。
|
|
152
|
+
if (!value?.name) throw new StepError('manifest.json 缺少 name,无法新建应用');
|
|
153
|
+
log(`登录 ${target} 并新建应用「${value.name}」。浏览器打开后,核对确认码一致再允许。`);
|
|
154
|
+
args = ['auth', 'login', '--target', target, '--create-app', '--name', value.name];
|
|
155
|
+
}
|
|
139
156
|
if (has('no-browser')) args.push('--no-browser');
|
|
140
|
-
|
|
141
|
-
if (
|
|
157
|
+
// 浏览器授权默认等 5 分钟;需要更久(例如要先找管理员开账号)时用 --browser-timeout 10m。
|
|
158
|
+
if (option('browser-timeout')) args.push('--browser-timeout', option('browser-timeout'));
|
|
142
159
|
writeJSON(configFile, { ...config, target });
|
|
160
|
+
// 新建应用时要拿到 stdout 里的 appid,授权链接和确认码仍实时显示。
|
|
161
|
+
const result = cli(args, { capture: !appKey, liveStderr: true });
|
|
162
|
+
if (result.code !== 0) {
|
|
163
|
+
throw new StepError(
|
|
164
|
+
appKey ? '登录未完成' : '登录未完成:如果上面提示该部署不支持登录时新建应用,请在云开发控制台「创建应用」,把 appid 填进 manifest.json 后重新 npm run login',
|
|
165
|
+
);
|
|
166
|
+
}
|
|
167
|
+
if (!appKey) ok(`已新建应用:appid=${result.json?.app_key ?? appIdOf(readJSON(manifestFile, {}))}(已写入 manifest.json)`);
|
|
143
168
|
ok('已登录:访问凭据自动续期,授权最长 30 天(到期或 auth logout 后重新登录)');
|
|
144
169
|
}
|
|
145
170
|
|
|
@@ -152,8 +177,19 @@ function publishedVersions() {
|
|
|
152
177
|
return Array.isArray(result.json) ? result.json : [];
|
|
153
178
|
}
|
|
154
179
|
|
|
180
|
+
/** vanilla 模板:把 npm 包里的 Cloud SDK 复制到应用目录,页面用 import { zl } from './sdk/index.js'。 */
|
|
181
|
+
function syncSdk() {
|
|
182
|
+
if (!project.sdkDir) return;
|
|
183
|
+
const from = join(root, 'node_modules', '@zleap-ai', 'app-sdk', 'dist');
|
|
184
|
+
if (!existsSync(join(from, 'index.js'))) throw new StepError('没有找到 @zleap-ai/app-sdk,请先安装依赖(npm install)。');
|
|
185
|
+
mkdirSync(join(root, project.sdkDir), { recursive: true });
|
|
186
|
+
for (const file of ['index.js', 'host.js', 'workspace.js', 'zleap.css']) {
|
|
187
|
+
if (existsSync(join(from, file))) copyFileSync(join(from, file), join(root, project.sdkDir, file));
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
|
|
155
191
|
function checkDist() {
|
|
156
|
-
const result = cli(['check',
|
|
192
|
+
const result = cli(['check', packageDir]);
|
|
157
193
|
if (result.code !== 0 || result.json?.status !== 'passed') {
|
|
158
194
|
throw new StepError(`本地检查未通过:${result.stderr || result.stdout}`);
|
|
159
195
|
}
|
|
@@ -170,10 +206,12 @@ function requireSupportedNode() {
|
|
|
170
206
|
}
|
|
171
207
|
|
|
172
208
|
async function deploy() {
|
|
173
|
-
|
|
209
|
+
manifest(); // 还没有 appid 时先说清楚:npm run login 会新建应用
|
|
210
|
+
if (project.build) requireSupportedNode();
|
|
174
211
|
const build = () => {
|
|
175
|
-
|
|
176
|
-
|
|
212
|
+
syncSdk();
|
|
213
|
+
if (!project.build || has('no-build')) return;
|
|
214
|
+
log(`构建 ${packageDir}/`);
|
|
177
215
|
npmRun('build');
|
|
178
216
|
};
|
|
179
217
|
|
|
@@ -181,10 +219,10 @@ async function deploy() {
|
|
|
181
219
|
let report = checkDist();
|
|
182
220
|
ok(`检查通过:${report.app_key} v${report.version}(${report.files} 个文件,runtime_test=${report.runtime_test})`);
|
|
183
221
|
|
|
184
|
-
//
|
|
222
|
+
// 同一版本号只能对应一份内容;内容变了就自动递增补丁号(构建型项目要重新构建,所以在这里做)。
|
|
185
223
|
const existing = publishedVersions().find((row) => row.app_key === report.app_key && row.version === report.version);
|
|
186
224
|
if (existing && (stripDigest(existing.digest) !== stripDigest(report.digest) || !['private', 'members'].includes(existing.visibility))) {
|
|
187
|
-
if (has('no-build')) throw new StepError(`版本 ${report.version} 已上传过不同内容,请修改 version 后重新构建`);
|
|
225
|
+
if (project.build && has('no-build')) throw new StepError(`版本 ${report.version} 已上传过不同内容,请修改 version 后重新构建`);
|
|
188
226
|
const current = manifest();
|
|
189
227
|
const next = bumpPatch(current.version);
|
|
190
228
|
warn(`版本 ${current.version} 已上传过不同内容,自动递增为 ${next}`);
|
|
@@ -193,69 +231,37 @@ async function deploy() {
|
|
|
193
231
|
report = checkDist();
|
|
194
232
|
}
|
|
195
233
|
|
|
196
|
-
//
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
throw new StepError(
|
|
234
|
+
// 上传、安装 / 切换本人安装、按诊断准备资源都交给 zleap-app deploy:每步先查平台事实,重复执行安全,
|
|
235
|
+
// 部署记录写在 .zleap/state.json。appid 应用的上传是只有成员可见的开发版本,不会直接给全企业用。
|
|
236
|
+
log('上传开发版本并装到本人');
|
|
237
|
+
const args = ['deploy', '.', '--package-dir', packageDir];
|
|
238
|
+
if (has('no-install')) args.push('--no-install');
|
|
239
|
+
const result = cli(args);
|
|
240
|
+
const out = result.json ?? {};
|
|
241
|
+
if (result.code !== 0) {
|
|
242
|
+
if (/未知命令 deploy/.test(result.stderr)) {
|
|
243
|
+
throw new StepError(`当前 zleap-app 版本太旧,不支持 deploy:npm i -D ${'@zleap-ai/app-cli'}@latest @zleap-ai/app-sdk@latest`);
|
|
244
|
+
}
|
|
245
|
+
if (needLogin(result.stderr)) throw new StepError(`${result.stderr}\n先运行 npm run login`);
|
|
246
|
+
if (result.code === 6 || out.status === 'unknown') {
|
|
247
|
+
throw new StepError(`${out.stage ?? '部署'}结果未知(COMMIT_UNKNOWN):不要手动重复操作。重新运行 npm run deploy 会先按原操作号核对,不会重复上传。`);
|
|
248
|
+
}
|
|
249
|
+
const reason = out.error ?? result.stderr;
|
|
250
|
+
throw new StepError([`部署停在「${out.stage ?? '未知阶段'}」:${reason}`, out.next].filter(Boolean).join('\n'));
|
|
208
251
|
}
|
|
209
|
-
const
|
|
210
|
-
const
|
|
211
|
-
|
|
212
|
-
const packageId = id(pack.id);
|
|
213
|
-
if (!appId || !versionId) throw new StepError(`上传回执缺少 app_id / version_id:${published.stdout}`);
|
|
214
|
-
ok(`已上传 v${report.version}:app_id=${appId} version_id=${versionId} package_id=${packageId}`);
|
|
252
|
+
const appId = id(out.app_id);
|
|
253
|
+
const versionId = id(out.version_id);
|
|
254
|
+
ok(`已上传 v${report.version}:app_id=${appId} version_id=${versionId} package_id=${id(out.package_id)}`);
|
|
215
255
|
// 平台 appid 应用:带云函数 / 后台能力的版本上传后平台自动签名;签不上时回执带原因(旧平台没有这个字段)。
|
|
216
|
-
|
|
217
|
-
if (autoSign?.status === 'failed') {
|
|
256
|
+
if (out.auto_sign?.status === 'failed') {
|
|
218
257
|
warn(
|
|
219
|
-
`平台自动签名失败(${
|
|
258
|
+
`平台自动签名失败(${out.auto_sign.reason ?? '未知原因'}):云函数 / 后台能力暂时不可用。打开应用或切换版本时平台会自动重试;` +
|
|
220
259
|
`也可以运行 npx zleap-app prepare ${appId} --version-id ${versionId} 查看详细错误。`,
|
|
221
260
|
);
|
|
222
261
|
}
|
|
223
|
-
writeJSON(stateFile, { appId, versionId, packageId, version: report.version, digest: report.digest, at: new Date().toISOString() });
|
|
224
|
-
|
|
225
262
|
if (has('no-install')) return finish(appId, false);
|
|
226
|
-
|
|
227
|
-
let diagnosis = cli(['diagnose', appId]);
|
|
228
|
-
if (diagnosis.code !== 0) throw new StepError(`读取安装状态失败:${diagnosis.stderr}`);
|
|
229
|
-
if (!diagnosis.json?.installed) {
|
|
230
|
-
log('安装给自己');
|
|
231
|
-
const installed = cli(['install', appId]);
|
|
232
|
-
if (installed.code !== 0) throw new StepError(`安装失败:${installed.stderr}`);
|
|
233
|
-
diagnosis = cli(['diagnose', appId]);
|
|
234
|
-
}
|
|
235
|
-
const current = id(diagnosis.json?.version_id);
|
|
236
|
-
if (current && current !== versionId) {
|
|
237
|
-
log(`把本人安装从 version_id=${current} 切换到 ${versionId}`);
|
|
238
|
-
const updated = cli(['update', appId, '--expected-version-id', current, '--version-id', versionId]);
|
|
239
|
-
if (updated.code !== 0) {
|
|
240
|
-
if (/COLLECTION_PARTITION_IMMUTABLE/.test(updated.stderr)) {
|
|
241
|
-
throw new StepError(
|
|
242
|
-
'新版本改了已有集合的 private / shared(数据归属),平台拒绝切换(COLLECTION_PARTITION_IMMUTABLE),当前安装保持原版本。\n' +
|
|
243
|
-
'集合建好后归属不能改:把这些集合的 partition 改回和当前版本一致;要换归属请新建一个集合并迁移数据。',
|
|
244
|
-
);
|
|
245
|
-
}
|
|
246
|
-
if (/DATA_MIGRATION_REQUIRED/.test(updated.stderr)) {
|
|
247
|
-
throw new StepError(
|
|
248
|
-
'新版本改动了 data / storage 声明,平台拒绝直接切换(DATA_MIGRATION_REQUIRED),当前安装保持原版本。\n' +
|
|
249
|
-
'注意:已建好的集合结构不会随新版本改变。开发阶段可以 npx zleap-app uninstall <app_id> 后再 npm run deploy(卸载保留数据);\n' +
|
|
250
|
-
'要改字段结构请新建集合并自行迁移数据。',
|
|
251
|
-
);
|
|
252
|
-
}
|
|
253
|
-
if (updated.code === 6) throw new StepError(`切换结果未知,先运行 npm run status 核对,不要重复切换。`);
|
|
254
|
-
throw new StepError(`切换版本失败:${updated.stderr}`);
|
|
255
|
-
}
|
|
256
|
-
}
|
|
257
263
|
ok(`本人安装已是 v${report.version}`);
|
|
258
|
-
finish(appId, true,
|
|
264
|
+
finish(appId, true, out.diagnosis ?? null);
|
|
259
265
|
}
|
|
260
266
|
|
|
261
267
|
/** 安装时平台会自动创建开发环境并开通数据库;这里按真实状态提示,而不是一律让用户去控制台创建。 */
|
|
@@ -267,10 +273,19 @@ function cloudStatus(diagnosis) {
|
|
|
267
273
|
return { dev: keys.includes('dev'), prod: keys.includes('prod'), databaseReady: allocation === 'ready' };
|
|
268
274
|
}
|
|
269
275
|
|
|
276
|
+
/** manifest 是否用到云资源(集合、cloud.* 权限或后台能力);用不到时不提示开发环境与数据库。 */
|
|
277
|
+
function needsCloud(value) {
|
|
278
|
+
const collections = value?.data?.collections;
|
|
279
|
+
const requires = value?.runtime?.capabilities?.requires;
|
|
280
|
+
return (
|
|
281
|
+
(Array.isArray(collections) && collections.length > 0) ||
|
|
282
|
+
(Array.isArray(requires) && requires.some((item) => String(item?.id ?? '').startsWith('cloud.'))) ||
|
|
283
|
+
hasBackgroundCapabilities(value)
|
|
284
|
+
);
|
|
285
|
+
}
|
|
286
|
+
|
|
270
287
|
function finish(appId, installed, diagnosis = null) {
|
|
271
|
-
const
|
|
272
|
-
writeJSON(stateFile, { ...state, appId });
|
|
273
|
-
const cloud = cloudStatus(diagnosis);
|
|
288
|
+
const cloud = needsCloud(readJSON(manifestFile, {})) ? cloudStatus(diagnosis) : null;
|
|
274
289
|
if (cloud) {
|
|
275
290
|
const parts = [`开发环境${cloud.dev ? '已创建' : '未创建'}`, `数据库${cloud.databaseReady ? '已就绪' : '未就绪'}`];
|
|
276
291
|
if (cloud.prod) parts.push('已有生产环境(应用默认运行在生产数据域)');
|
|
@@ -284,8 +299,8 @@ function finish(appId, installed, diagnosis = null) {
|
|
|
284
299
|
`有云函数 / 后台能力:npx zleap-app prepare ${appId} --version-id ${readJSON(stateFile, {}).versionId ?? '<version_id>'} 补做开发环境准备(平台上传时通常已自动签名并绑定,只有自动签名失败时才会走到这一步),再在应用窗口「权限」里允许后台能力。`,
|
|
285
300
|
);
|
|
286
301
|
}
|
|
287
|
-
if (
|
|
288
|
-
steps.push('
|
|
302
|
+
if (cloud && (!cloud.dev || !cloud.databaseReady)) {
|
|
303
|
+
steps.push('开发环境或数据库还没就绪(安装后通常一分钟内自动就绪):打开「云开发控制台」选中本应用 → 概览,按提示「创建开发环境」/ 等数据库「已就绪」。');
|
|
289
304
|
}
|
|
290
305
|
steps.push('出问题:npm run status 看安装与权限,npm run logs 看页面错误,控制台「运行体检」逐层排查。');
|
|
291
306
|
const manifestValue = readJSON(manifestFile, {});
|
|
@@ -379,6 +394,42 @@ function passthrough(args) {
|
|
|
379
394
|
if (result.code !== 0) process.exitCode = result.code;
|
|
380
395
|
}
|
|
381
396
|
|
|
397
|
+
/**
|
|
398
|
+
* 预览模式:不连 zleapOS,用页面里 preview 模块的示例数据把界面渲染出来,方便调样式、截图自查。
|
|
399
|
+
* 功能是否可用仍以部署后在 zleapOS 里打开为准。React 模板交给 Vite;vanilla 模板用内置静态服务。
|
|
400
|
+
*/
|
|
401
|
+
function preview() {
|
|
402
|
+
const port = Number(option('port') ?? process.env.PORT ?? 5180);
|
|
403
|
+
if (project.build) {
|
|
404
|
+
const vite = join(root, 'node_modules', '.bin', process.platform === 'win32' ? 'vite.cmd' : 'vite');
|
|
405
|
+
if (!existsSync(vite)) throw new StepError('没有找到 vite,请先安装依赖(npm install)。');
|
|
406
|
+
const result = spawnSync(vite, ['--host', '127.0.0.1', '--port', String(port), '--strictPort'], { cwd: root, stdio: 'inherit', shell: process.platform === 'win32' });
|
|
407
|
+
process.exitCode = result.status ?? 1;
|
|
408
|
+
return;
|
|
409
|
+
}
|
|
410
|
+
syncSdk();
|
|
411
|
+
const base = resolve(root, packageDir);
|
|
412
|
+
const types = { '.html': 'text/html', '.js': 'text/javascript', '.mjs': 'text/javascript', '.css': 'text/css', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.ico': 'image/x-icon', '.woff2': 'font/woff2' };
|
|
413
|
+
createServer((req, res) => {
|
|
414
|
+
const path = decodeURIComponent(new URL(req.url ?? '/', 'http://localhost').pathname);
|
|
415
|
+
let file = normalize(join(base, path));
|
|
416
|
+
if (file !== base && !file.startsWith(base + sep)) {
|
|
417
|
+
res.writeHead(403).end();
|
|
418
|
+
return;
|
|
419
|
+
}
|
|
420
|
+
if (existsSync(file) && statSync(file).isDirectory()) file = join(file, 'index.html');
|
|
421
|
+
if (!existsSync(file)) {
|
|
422
|
+
res.writeHead(404).end('not found');
|
|
423
|
+
return;
|
|
424
|
+
}
|
|
425
|
+
res.writeHead(200, { 'Content-Type': `${types[extname(file).toLowerCase()] ?? 'application/octet-stream'}; charset=utf-8`, 'Cache-Control': 'no-store' });
|
|
426
|
+
res.end(readFileSync(file));
|
|
427
|
+
}).listen(port, '127.0.0.1', () => {
|
|
428
|
+
ok(`预览模式:http://127.0.0.1:${port}/`);
|
|
429
|
+
console.log(' 页面不连 zleapOS,数据来自 preview.js 的示例;改完文件刷新即可。功能以 npm run deploy 后在 zleapOS 里打开为准。按 Ctrl+C 结束。');
|
|
430
|
+
});
|
|
431
|
+
}
|
|
432
|
+
|
|
382
433
|
async function main() {
|
|
383
434
|
switch (command) {
|
|
384
435
|
case 'login':
|
|
@@ -393,8 +444,12 @@ async function main() {
|
|
|
393
444
|
return versions();
|
|
394
445
|
case 'release':
|
|
395
446
|
return release();
|
|
447
|
+
case 'preview':
|
|
448
|
+
return preview();
|
|
449
|
+
case 'sdk':
|
|
450
|
+
return syncSdk();
|
|
396
451
|
default:
|
|
397
|
-
console.log('用法:node scripts/zleap.mjs <login|deploy|status|logs|versions|release>');
|
|
452
|
+
console.log('用法:node scripts/zleap.mjs <login|deploy|status|logs|versions|release|preview|sdk>');
|
|
398
453
|
process.exitCode = 1;
|
|
399
454
|
}
|
|
400
455
|
}
|
|
@@ -3,13 +3,19 @@
|
|
|
3
3
|
本项目是运行在 zleapOS 沙箱窗口里的云开发应用:React + Vite 构建到 `dist/`,`dist/` 就是应用包根目录。
|
|
4
4
|
做任何云开发相关改动前,先读项目内 skill `zleap-cloud-app`(`.agents/skills/` 或 `.claude/skills/`)。
|
|
5
5
|
|
|
6
|
+
**开发路线**:先用 MCP 服务 `zleap-app`(`.mcp.json` 已配好)查当前用户可用的 OS 接口和 SDK——`os_business_search` → `os_business_get` → `os_business_call` 试调(写 / 删接口先传 `dry_run: true` 只校验不执行;搜索结果 `page_api.enabled` 为 false 时页面不能调 OS 接口);OS 已有的数据和功能直接用 `zl.cloud.os.api.fetch`;应用自己产生的数据才建集合;都没有的后端逻辑才写云函数。不要猜接口,不要重复造轮子。
|
|
7
|
+
|
|
8
|
+
**界面**:用官方样式 `zleap.css` 的 `zl-` 类(与 zleapOS 桌面同色、自动跟随亮 / 暗),自己的样式只用 `var(--zl-*)` 取色;每块数据做全加载中 / 出错 / 空 / 有数据四种状态。
|
|
9
|
+
写完界面运行 `npm run preview` 在浏览器里看效果(示例数据,亮 / 暗都看)。类清单与常用版式见 skill 的 `references/ui.md`。
|
|
10
|
+
|
|
6
11
|
## 命令
|
|
7
12
|
|
|
8
13
|
| 目的 | 命令 |
|
|
9
14
|
| --- | --- |
|
|
15
|
+
| 预览界面(不连 zleapOS,示例数据来自 preview 模块) | `npm run preview` |
|
|
10
16
|
| 类型检查 | `npm run typecheck` |
|
|
11
17
|
| 构建 + 平台静态检查 | `npm run check`(`runtime_test=not_checked`,不代表能用) |
|
|
12
|
-
| 登录 OS(浏览器授权,自动续期,最长 30
|
|
18
|
+
| 登录 OS(浏览器授权,自动续期,最长 30 天;manifest 还没有 appid 时同时新建应用) | `npm run login -- --target <OS 地址>` |
|
|
13
19
|
| 构建→检查→上传开发版本→装到本人 | `npm run deploy` |
|
|
14
20
|
| 安装/权限/版本诊断 | `npm run status` |
|
|
15
21
|
| 页面错误与云函数日志(24h) | `npm run logs`(`-- --environment dev\|prod`、`--invocation <调用编号>`) |
|
|
@@ -23,9 +29,9 @@
|
|
|
23
29
|
- **一切先声明**:集合与结构写在 `manifest.json` 的 `data.collections` + `data.schemas`;权限写在 `runtime.capabilities.requires`。没声明的运行时一律拿不到。
|
|
24
30
|
- **集合结构上线后不可改**:已建集合不会随新版本更新 Schema,改字段要新建集合并迁移。`additionalProperties` 缺省按 `false`。
|
|
25
31
|
- **沙箱**:opaque origin + CSP `connect-src 'none'`、`worker-src 'none'`、只允许包内脚本/样式/字体。不能 `fetch`、不能用外部 CDN/字体、不能用 `localStorage`、不能 `alert/confirm`、不能开 Worker。
|
|
26
|
-
- **只通过 `src/cloud/` 访问 SDK**;环境用 `DYNAMIC_CURRENT_ENV`,不要写死 dev/prod。SDK 是 npm 包 `@zleap-ai/app-sdk`(另有 `/host` 宿主能力、`/workspace` 工作区入口),API 以 `node_modules/@zleap-ai/app-sdk/dist/types/*.d.ts`
|
|
32
|
+
- **只通过 `src/cloud/` 访问 SDK**;环境用 `DYNAMIC_CURRENT_ENV`,不要写死 dev/prod。SDK 是 npm 包 `@zleap-ai/app-sdk`(另有 `/host` 宿主能力、`/workspace` 工作区入口),API 以 `node_modules/@zleap-ai/app-sdk/dist/types/*.d.ts` 为准;SDK 与 `@zleap-ai/app-cli` 各自独立发版,升级时都装 `@latest` 即可。
|
|
27
33
|
- **单次读取最多 100 条**,用 `skip` 翻页(skip ≤ 1000)。更新/删除带 `expectedVersion`。
|
|
28
34
|
- **结果未知不重试**:`COMMIT_UNKNOWN` 时先重读核对;部署脚本退出码 6 同理。
|
|
29
|
-
-
|
|
35
|
+
- **明确失败优于假成功**:在 zleapOS 里不要用模拟数据、假登录或吞掉错误来让界面「看起来能用」;示例数据只用于 `npm run preview` 的预览模式。
|
|
30
36
|
- **用户信息只走授权登录**:`zl.auth.authorize` 在按钮点击时调用,manifest `host_api.requires` 声明 `user.*`;用户键用 openid,不要找平台用户 ID。
|
|
31
37
|
- 每次上传都要新版本号(`npm run deploy` 会在内容变化时自动递增补丁号)。
|
|
@@ -3,11 +3,15 @@
|
|
|
3
3
|
"private": true,
|
|
4
4
|
"version": "0.0.0",
|
|
5
5
|
"type": "module",
|
|
6
|
+
"zleap": {
|
|
7
|
+
"packageDir": "dist"
|
|
8
|
+
},
|
|
6
9
|
"engines": {
|
|
7
10
|
"node": "^20.19.0 || >=22.12.0"
|
|
8
11
|
},
|
|
9
12
|
"scripts": {
|
|
10
13
|
"dev": "vite",
|
|
14
|
+
"preview": "node scripts/zleap.mjs preview",
|
|
11
15
|
"build": "tsc -b && vite build",
|
|
12
16
|
"typecheck": "tsc -b",
|
|
13
17
|
"check": "npm run build && zleap-app check dist",
|