@heybox/hb-sdk 0.6.8 → 0.6.9-alpha.0

package/dist/miniapp-publish.esm.js

@@ -2834,6 +2834,10 @@ const UPDATE_SQUARE_DISPLAY_API_PATH = '/mall/developer/user_miniprogram/square_
 const LIST_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/list';
 const FNV_OFFSET = 0x811c9dc5;
 const FNV_PRIME = 0x01000193;
+const MINIAPP_UPLOAD_SESSION_REF_LENGTH = 10;
+const MINIAPP_ARTIFACT_SIGNATURE_MAGIC = 'heybox-user-miniprogram-artifact\0v1\0';
+const UNPAIRED_SURROGATE_PATTERN = /[\ud800-\udbff](?![\udc00-\udfff])|(^|[^\ud800-\udbff])[\udc00-\udfff]/;
+const textEncoder = new TextEncoder();
 function normalizeRelativePath(relativePath) {
     return String(relativePath || '')
         .replace(/\\/g, '/')
@@ -2927,5 +2931,201 @@ function shouldUploadDistFile(relativePath) {
     }
     return true;
 }
+/**
+ * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
+ *
+ * @param files 待处理的构建产物文件。
+ * @returns 保留输入附加字段的有序文件列表。
+ * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
+ */
+function prepareMiniappArtifactFiles(files) {
+    if (files.length > 0xffffffff) {
+        throw new Error('构建产物文件数量超出签名协议上限');
+    }
+    const usedPaths = new Set();
+    const prepared = files.map(file => {
+        const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
+        if (usedPaths.has(relativePath)) {
+            throw new Error(`构建产物包含重复文件路径：${relativePath}`);
+        }
+        usedPaths.add(relativePath);
+        validateArtifactFileSize(file.size, relativePath);
+        return { ...file, relativePath };
+    });
+    return prepared.sort((left, right) => compareBytes(textEncoder.encode(left.relativePath), textEncoder.encode(right.relativePath)));
+}
+/**
+ * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
+ *
+ * @param files 待上传的构建产物文件。
+ * @param options 小程序和长度限制配置。
+ * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
+ */
+function validateMiniappUploadPathLengths(files, options) {
+    const maxLength = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
+    const prefix = `/u/${getMiniProgramUploadAlias(options.miniProgramId)}/${'x'.repeat(MINIAPP_UPLOAD_SESSION_REF_LENGTH)}/`;
+    const prefixLength = textEncoder.encode(prefix).length;
+    const tooLongFile = files.find(file => {
+        const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
+        return prefixLength + textEncoder.encode(relativePath).length > maxLength;
+    });
+    return tooLongFile ? `文件路径过长，请缩短构建产物文件名或目录层级：${tooLongFile.relativePath}` : undefined;
+}
+/**
+ * 创建 v1 整包签名头。
+ *
+ * @param fileCount 参与签名的文件数量。
+ * @returns 包含协议标识和文件数量的字节数组。
+ * @throws 文件数量超出协议范围时抛出错误。
+ */
+function createMiniappArtifactSignatureHeader(fileCount) {
+    if (!Number.isInteger(fileCount) || fileCount < 0 || fileCount > 0xffffffff) {
+        throw new Error('构建产物文件数量超出签名协议上限');
+    }
+    return concatBytes(textEncoder.encode(MINIAPP_ARTIFACT_SIGNATURE_MAGIC), encodeUint32BE(fileCount));
+}
+/**
+ * 创建单个文件的 v1 framing header。
+ *
+ * @param file 已规范化或待校验的构建产物文件。
+ * @returns 包含路径长度、路径和文件大小的字节数组。
+ * @throws 文件路径或大小非法时抛出错误。
+ */
+function createMiniappArtifactFileHeader(file) {
+    const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
+    validateArtifactFileSize(file.size, relativePath);
+    const pathBytes = textEncoder.encode(relativePath);
+    return concatBytes(encodeUint32BE(pathBytes.length), pathBytes, encodeUint64BE(file.size));
+}
+/**
+ * 校验服务端 session 文件映射，并计算仍需上传的文件。
+ *
+ * @param localFiles 本地构建产物文件。
+ * @param serverFiles 服务端签发的文件映射。
+ * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @returns 完整映射、待上传文件和已确认 key。
+ * @throws 服务端映射与本地产物不一致时抛出错误。
+ */
+function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys) {
+    const preparedFiles = prepareMiniappArtifactFiles(localFiles);
+    if (serverFiles.length !== preparedFiles.length) {
+        throw new Error(`上传会话文件数量异常：期望 ${preparedFiles.length}，实际 ${serverFiles.length}`);
+    }
+    const mappings = new Map();
+    const serverSizes = new Map();
+    const knownKeys = new Set();
+    for (const serverFile of serverFiles) {
+        const relativePath = normalizeMiniappArtifactRelativePath(serverFile.relative_path);
+        if (mappings.has(relativePath)) {
+            throw new Error(`上传会话返回重复文件路径：${relativePath}`);
+        }
+        const key = String(serverFile.key || '');
+        if (!key) {
+            throw new Error(`上传会话未返回文件 key：${relativePath}`);
+        }
+        if (knownKeys.has(key)) {
+            throw new Error(`上传会话返回重复文件 key：${relativePath}`);
+        }
+        const size = Number(serverFile.size);
+        if (!Number.isSafeInteger(size) || size < 0) {
+            throw new Error(`上传会话返回文件大小异常：${relativePath}`);
+        }
+        mappings.set(relativePath, key);
+        serverSizes.set(relativePath, size);
+        knownKeys.add(key);
+    }
+    const files = preparedFiles.map(file => {
+        const key = mappings.get(file.relativePath);
+        if (!key) {
+            throw new Error(`上传会话缺少文件映射：${file.relativePath}`);
+        }
+        if (serverSizes.get(file.relativePath) !== file.size) {
+            throw new Error(`上传会话文件大小与本地构建不一致：${file.relativePath}`);
+        }
+        return { file, key };
+    });
+    const completed = new Set();
+    for (const rawKey of uploadedKeys) {
+        const key = String(rawKey || '');
+        if (!knownKeys.has(key)) {
+            throw new Error('上传会话返回了不属于当前产物的已上传文件');
+        }
+        completed.add(key);
+    }
+    return {
+        files,
+        missingFiles: files.filter(file => !completed.has(file.key)),
+        uploadedKeys: [...completed],
+    };
+}
+function normalizeMiniappArtifactRelativePath(relativePath) {
+    const value = String(relativePath || '');
+    if (!value) {
+        throw new Error('构建产物包含空文件路径');
+    }
+    if (value.includes('\\')) {
+        throw new Error(`构建产物路径不能包含反斜杠：${value}`);
+    }
+    if (value.startsWith('/') || value.endsWith('/') || /^[a-zA-Z]:\//.test(value)) {
+        throw new Error(`构建产物必须使用相对文件路径：${value}`);
+    }
+    if (containsControlCharacter(value) || UNPAIRED_SURROGATE_PATTERN.test(value)) {
+        throw new Error(`构建产物路径包含非法字符：${value}`);
+    }
+    if (value.split('/').some(segment => !segment || segment === '.' || segment === '..')) {
+        throw new Error(`构建产物路径包含非法目录段：${value}`);
+    }
+    if (value.includes(',')) {
+        throw new Error(`构建产物路径不能包含逗号：${value}`);
+    }
+    if (value.includes('*') || value.includes('?')) {
+        throw new Error(`构建产物路径不能包含通配符：${value}`);
+    }
+    return value;
+}
+function containsControlCharacter(value) {
+    for (const character of value) {
+        const code = character.charCodeAt(0);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) {
+            return true;
+        }
+    }
+    return false;
+}
+function validateArtifactFileSize(size, relativePath) {
+    if (!Number.isSafeInteger(size) || size < 0) {
+        throw new Error(`构建产物文件大小无效：${relativePath}`);
+    }
+}
+function encodeUint32BE(value) {
+    const bytes = new Uint8Array(4);
+    new DataView(bytes.buffer).setUint32(0, value, false);
+    return bytes;
+}
+function encodeUint64BE(value) {
+    const bytes = new Uint8Array(8);
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, Math.floor(value / 0x100000000), false);
+    view.setUint32(4, value % 0x100000000, false);
+    return bytes;
+}
+function concatBytes(...parts) {
+    const result = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.length;
+    }
+    return result;
+}
+function compareBytes(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        if (left[index] !== right[index]) {
+            return left[index] - right[index];
+        }
+    }
+    return left.length - right.length;
+}
 
-export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, CREATE_USER_MINIPROGRAM_API_PATH, CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DETAIL_USER_MINIPROGRAM_API_PATH, DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DEVELOPER_ENTITY_LIST_API_PATH, DEVELOPER_ENTITY_SWITCH_API_PATH, LIST_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH, LIST_USER_MINIPROGRAM_VERSION_API_PATH, MINIAPP_UPLOAD_BATCH_SIZE, MINIAPP_UPLOAD_SCOPE, MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES, PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH, RELEASE_USER_MINIPROGRAM_VERSION_API_PATH, REOPEN_USER_MINIPROGRAM_API_PATH, SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH, TAKE_DOWN_USER_MINIPROGRAM_API_PATH, UPDATE_SQUARE_DISPLAY_API_PATH, UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_ACCESS_STATUS_API_PATH, USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH, WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH, getMiniProgramUploadAlias, getMiniappUploadKey, isValidMiniappManifestVersion as isValidVersion, normalizeRelativePath, relativePathContainsNodeModulesSegment, shouldUploadDistFile, validateUploadPaths, validateUploadTotalSize };
+export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, CREATE_USER_MINIPROGRAM_API_PATH, CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DETAIL_USER_MINIPROGRAM_API_PATH, DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DEVELOPER_ENTITY_LIST_API_PATH, DEVELOPER_ENTITY_SWITCH_API_PATH, LIST_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH, LIST_USER_MINIPROGRAM_VERSION_API_PATH, MINIAPP_UPLOAD_BATCH_SIZE, MINIAPP_UPLOAD_SCOPE, MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES, PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH, RELEASE_USER_MINIPROGRAM_VERSION_API_PATH, REOPEN_USER_MINIPROGRAM_API_PATH, SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH, TAKE_DOWN_USER_MINIPROGRAM_API_PATH, UPDATE_SQUARE_DISPLAY_API_PATH, UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_ACCESS_STATUS_API_PATH, USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH, WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH, createMiniappArtifactFileHeader, createMiniappArtifactSignatureHeader, getMiniProgramUploadAlias, getMiniappUploadKey, isValidMiniappManifestVersion as isValidVersion, normalizeRelativePath, prepareMiniappArtifactFiles, relativePathContainsNodeModulesSegment, resolveMiniappUploadSessionFiles, shouldUploadDistFile, validateMiniappUploadPathLengths, validateUploadPaths, validateUploadTotalSize };

package/dist/vite.cjs.js

@@ -8,7 +8,7 @@ var _documentCurrentScript = typeof document !== 'undefined' ? document.currentS
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.8';
+    : '0.6.9-alpha.0';
 
 var re = {exports: {}};
 

package/dist/vite.esm.js

@@ -5,7 +5,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.8';
+    : '0.6.9-alpha.0';
 
 var re = {exports: {}};
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.6.8",
+  "version": "0.6.9-alpha.0",
   "sideEffects": [
     "./src/index.ts",
     "./src/core/singleton.ts",
@@ -95,7 +95,7 @@
     "vue": "^2.7.16",
     "vite": "^8.0.12",
     "vitest": "^3.2.4",
-    "@heybox/hb-api": "~1.25.10"
+    "@heybox/hb-api": "~1.25.11"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",

package/skill/references/api-root.md

@@ -23,7 +23,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.8`
+- Version at generation time: `0.6.9-alpha.0`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`

package/skill/references/cli.md

@@ -196,6 +196,14 @@ hb-sdk remote deploy --release-note "修复登录状态展示"
 
 这条命令会完成检查、执行项目的 `scripts.build`、上传和提交审核，因此项目定义的类型检查仍会执行。默认在审核通过后等待手动发布；普通低风险版本可以追加 `--auto-publish`。完整命令见 `hb-sdk remote --help`，提交要求见[小程序工坊上架规则](https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)。
 
+构建产物上传从 `0.6.8` 起强制使用服务端上传 session，`0.6.7` 及更早版本不能继续部署，请先升级 `@heybox/hb-sdk`。deploy 从整包签名开始到上传结束都把 `dist/` 视为稳定输出，不要在此期间由其他进程修改构建目录；上传中断后可重新执行 deploy，服务端会按已确认回执恢复缺失文件。
+
+普通 deploy 会按 API 环境、`miniProgramId` 和版本在本机缓存目录获取短文件锁，避免两个 CLI 进程同时构建并上传同一版本。进程异常退出后锁可按 PID 回收；缓存目录不可用时会降级为无锁执行，不影响上传主流程。`--from-version` 不执行本地构建和上传，因此不会获取该锁。
+
+上传信息、上传凭证和上传回调按每批最多 50 个文件串行处理，批内保持 4 并发。CLI 每批获取一次仅授权当前 session 目录前缀的凭证，并校验服务端返回的 key 和 size 与本地文件完全一致；任何异常都会停止后续上传且不会提交审核。
+
+普通构建上传时，CLI 会计算整包签名，并把相对路径和文件大小一起提交给服务端创建或恢复上传会话；同一账号下签名和文件清单一致时，服务端返回已有 session 与 `uploaded_keys`，CLI 只上传缺失文件。CLI 不保存本地上传会话缓存。构建产物变化时服务端会创建新的隔离目录，并尽力清理旧目录。上传回调在当前命令内失败会重试；仍失败时可重新执行 deploy，服务端根据 `uploaded_keys` 继续恢复，同 key 的 COS 重传是幂等的。
+
 Before publishing, `hb-sdk remote deploy` verifies that the bound mini-program belongs to the current developer account. If it does not, the command stops and asks the user to switch accounts.
 
 Agent rules:

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.6.8+skill.79001ff42152",
+  "skillVersion": "0.6.9-alpha.0+skill.a578097b3a33",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.6.8",
-    "compatibility": "0.6.8"
+    "version": "0.6.9-alpha.0",
+    "compatibility": "0.6.9-alpha.0"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-79001ff42152003dc0b79b0ddd0945843f7eade237defb024c609a5d5b3048c0"
+  "integrity": "sha256-a578097b3a3302d8149c3a09107a71516d84861022ddc4adb6ef1d465a423bfa"
 }

package/types/miniapp-publish/index.d.ts

@@ -51,3 +51,80 @@ export interface ValidateUploadTotalSizeOptions {
 }
 export declare function validateUploadTotalSize(items: UploadSizeItem[], options?: ValidateUploadTotalSizeOptions): "构建产物总大小超过 100MB，请删除未引用资源或压缩图片后重新 deploy" | undefined;
 export declare function shouldUploadDistFile(relativePath: string): boolean;
+/** 参与整包签名和上传会话映射的构建产物文件。 */
+export interface MiniappArtifactFile {
+    /** 使用 `/` 分隔的构建产物相对路径。 */
+    relativePath: string;
+    /** 文件字节数。 */
+    size: number;
+}
+/** 服务端上传会话返回的文件映射。 */
+export interface MiniappUploadSessionFile {
+    /** 与创建会话时提交值一致的相对路径。 */
+    relative_path: string;
+    /** 服务端签发的完整上传 key。 */
+    key: string;
+    /** 服务端记录的文件字节数。 */
+    size: number;
+}
+/**
+ * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
+ *
+ * @param files 待处理的构建产物文件。
+ * @returns 保留输入附加字段的有序文件列表。
+ * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
+ */
+export declare function prepareMiniappArtifactFiles<T extends MiniappArtifactFile>(files: readonly T[]): (T & {
+    relativePath: string;
+})[];
+/**
+ * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
+ *
+ * @param files 待上传的构建产物文件。
+ * @param options 小程序和长度限制配置。
+ * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
+ */
+export declare function validateMiniappUploadPathLengths(files: readonly Pick<MiniappArtifactFile, 'relativePath'>[], options: {
+    miniProgramId: string;
+    maxLength?: number;
+}): string | undefined;
+/**
+ * 创建 v1 整包签名头。
+ *
+ * @param fileCount 参与签名的文件数量。
+ * @returns 包含协议标识和文件数量的字节数组。
+ * @throws 文件数量超出协议范围时抛出错误。
+ */
+export declare function createMiniappArtifactSignatureHeader(fileCount: number): Uint8Array<ArrayBuffer>;
+/**
+ * 创建单个文件的 v1 framing header。
+ *
+ * @param file 已规范化或待校验的构建产物文件。
+ * @returns 包含路径长度、路径和文件大小的字节数组。
+ * @throws 文件路径或大小非法时抛出错误。
+ */
+export declare function createMiniappArtifactFileHeader(file: MiniappArtifactFile): Uint8Array<ArrayBuffer>;
+/**
+ * 校验服务端 session 文件映射，并计算仍需上传的文件。
+ *
+ * @param localFiles 本地构建产物文件。
+ * @param serverFiles 服务端签发的文件映射。
+ * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @returns 完整映射、待上传文件和已确认 key。
+ * @throws 服务端映射与本地产物不一致时抛出错误。
+ */
+export declare function resolveMiniappUploadSessionFiles<T extends MiniappArtifactFile>(localFiles: readonly T[], serverFiles: readonly MiniappUploadSessionFile[], uploadedKeys: readonly string[]): {
+    files: {
+        file: T & {
+            relativePath: string;
+        };
+        key: string;
+    }[];
+    missingFiles: {
+        file: T & {
+            relativePath: string;
+        };
+        key: string;
+    }[];
+    uploadedKeys: string[];
+};