@heybox/hb-sdk 0.5.8 → 0.5.10

package/README.md

@@ -345,7 +345,7 @@ try {
 | `hb-sdk remote bind <mini-program-id> [--force]`                                        | 校验当前 CLI 用户可管理目标小程序后，再把它绑定到当前项目。                                                           |
 | `hb-sdk remote info`                                                                    | 查看当前项目绑定的小程序详情。                                                                                        |
 | `hb-sdk remote allowlist list/add/remove/set ...`                                       | 管理绑定小程序的预览白名单。                                                                                          |
-| `hb-sdk remote deploy --release-note <text> [--skip-build] [--auto-publish]`            | 构建、上传并提交当前小程序版本审核；`--skip-build` 跳过 build 直接上传 `dist/`。                                      |
+| `hb-sdk remote deploy --release-note <text> [--skip-build \| --from-version <version>] [--auto-publish]` | 构建、上传并提交当前小程序版本审核；`--skip-build` 跳过 build 直接上传 `dist/`，`--from-version` 复用指定历史版本产物。 |
 | `hb-sdk remote versions`                                                                | 列出绑定小程序的远端版本。                                                                                            |
 | `hb-sdk remote preview <version>`                                                       | 查看指定版本的远端预览入口。                                                                                          |
 | `hb-sdk remote release <version> [--yes]`                                               | 发布审核通过的版本；非 TTY 环境必须传 `--yes`。                                                                       |
@@ -389,16 +389,19 @@ try {
 4. 触发 `<pm> run build`，除非使用 `--skip-build`。
 5. 解析 `dist/manifest.json`，校验 `version` 为 `x.y.z`，自动剥离 BOM；普通 remote deploy 要求该版本与 precheck 使用的 `package.json.version` 一致。
 6. `--skip-build` 会先读取已有 `dist/manifest.json.version`，再调用 precheck。
-7. 遍历 `dist/` 文件，跳过 `manifest.json`、`.DS_Store`、`.map`；遇到 symlink 或 `node_modules` 直接报错。
-8. 校验所有上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
-9. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 COS。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
-10. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
-11. 全部上传成功后调用 `/mall/developer/user_miniprogram/version/submit_audit`，输出提交审核成功、发布策略和可用的 preview URL；后端原始失败细节只在 `--verbose` 下展示。
+7. `--from-version <version>` 会跳过本地 build、`dist/` 读取和 CDN 上传，直接让远端复用指定历史版本产物提交审核；它与 `--skip-build` 互斥。
+8. 遍历 `dist/` 文件，跳过 `manifest.json`、`.DS_Store`、`.map`；遇到 symlink 或 `node_modules` 直接报错。
+9. 校验所有上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
+10. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 COS。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
+11. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
+12. 全部上传成功后调用 `/mall/developer/user_miniprogram/version/submit_audit`；`--from-version` 路径会直接调用提交审核接口并传入 `source_version`。CLI 输出提交审核成功、发布策略和可用的 preview URL；后端原始失败细节只在 `--verbose` 下展示。
 
 默认 `auto_publish=false`，审核通过后使用 `hb-sdk remote versions` 查看版本状态，再用 `hb-sdk remote release <version>` 发布；使用 `--auto-publish` 时提交 `auto_publish=true`，审核通过后自动发布。未发布候选版本可通过 `hb-sdk remote allowlist add <heybox_id>` 加入预览白名单，让指定用户在广场看到；正式入口使用 `mini_program_id`，`mini_url` 仅用于本地调试。
 
 `--skip-build` 用于 CI 双阶段：上一步已经 build 完缓存好了 `dist/`，本步只做预检、上传和提交审核。`dist/manifest.json` 或 `dist/index.html` 缺失会立即报错。
 
+`--from-version <version>` 用于复用已经上传过的远端历史版本产物提交新一轮审核。该模式不读取本地 `dist/`，也不会执行 build 或上传；目标审核版本由服务端根据版本表最高 SemVer 自动派生。不要和 `--skip-build` 同时使用。
+
 `manifest.json` 不会上传到 CDN，只作为 submit audit 请求的 `manifest` 字段提交。这与 Vite 插件文档中的契约一致。名称、icon 和介绍图从 `package.json.heybox.miniProgramProfile` 读取，并随 precheck 和 submit audit 一起提交：
 
 ```json
@@ -448,7 +451,7 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 | `hb-sdk remote allowlist add <heybox-id...>`                                            | 添加十进制 Heybox ID 到预览白名单。                                                                                                                |
 | `hb-sdk remote allowlist remove <heybox-id...>`                                         | 从预览白名单移除非 owner 条目。                                                                                                                    |
 | `hb-sdk remote allowlist set <heybox-id...>`                                            | 替换非 owner 白名单条目，并保留平台返回的 owner 语义。                                                                                             |
-| `hb-sdk remote deploy --release-note <text> [--skip-build] [--auto-publish]`            | 构建、上传并提交当前版本审核。                                                                                                                     |
+| `hb-sdk remote deploy --release-note <text> [--skip-build \| --from-version <version>] [--auto-publish]` | 构建、上传或复用历史产物并提交当前版本审核。                                                                                                       |
 | `hb-sdk remote versions`                                                                | 列出当前绑定小程序的远端版本。                                                                                                                     |
 | `hb-sdk remote preview <version>`                                                       | 查看指定版本的远端预览入口。                                                                                                                       |
 | `hb-sdk remote release <version> [--yes]`                                               | 发布审核通过的版本；交互式终端会确认，非 TTY 必须传 `--yes`。                                                                                      |

package/dist/cli-chunks/{create-DxRc3VpZ.cjs → create-D1W2pkHZ.cjs}

@@ -5,7 +5,7 @@ var fs = require('node:fs/promises');
 var path = require('node:path');
 var require$$0 = require('fs');
 var require$$1 = require('path');
-var index = require('./index-Dyn_R89O.cjs');
+var index = require('./index-BBatNb1l.cjs');
 require('node:module');
 require('os');
 require('readline');

package/dist/cli-chunks/{dev-C9Jkdl7Y.cjs → dev-DwbE-c1x.cjs}

@@ -9,7 +9,7 @@ var node_url = require('node:url');
 var net = require('node:net');
 var node_http = require('node:http');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-Dyn_R89O.cjs');
+var index = require('./index-BBatNb1l.cjs');
 require('node:process');
 require('node:buffer');
 require('node:util');

package/dist/cli-chunks/{doctor-DoiRoJd5.cjs → doctor-Bx71WFjM.cjs}

@@ -4,7 +4,7 @@ var fs$1 = require('node:fs');
 var fs = require('node:fs/promises');
 var os = require('node:os');
 var path = require('node:path');
-var index = require('./index-Dyn_R89O.cjs');
+var index = require('./index-BBatNb1l.cjs');
 require('node:module');
 require('path');
 require('os');

package/dist/cli-chunks/{index-Dyn_R89O.cjs → index-BBatNb1l.cjs}

@@ -234,19 +234,19 @@ function requireArgument () {
 
 var command = {};
 
-const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-Dyn_R89O.cjs', document.baseURI).href)));
+const require$5 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BBatNb1l.cjs', document.baseURI).href)));
 function __require$4() { return require$5("node:events"); }
 
-const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-Dyn_R89O.cjs', document.baseURI).href)));
+const require$4 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BBatNb1l.cjs', document.baseURI).href)));
 function __require$3() { return require$4("node:child_process"); }
 
-const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-Dyn_R89O.cjs', document.baseURI).href)));
+const require$3 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BBatNb1l.cjs', document.baseURI).href)));
 function __require$2() { return require$3("node:path"); }
 
-const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-Dyn_R89O.cjs', document.baseURI).href)));
+const require$2 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BBatNb1l.cjs', document.baseURI).href)));
 function __require$1() { return require$2("node:fs"); }
 
-const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-Dyn_R89O.cjs', document.baseURI).href)));
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli-chunks/index-BBatNb1l.cjs', document.baseURI).href)));
 function __require() { return require$1("node:process"); }
 
 var help = {};
@@ -13094,7 +13094,7 @@ function readErrorMessage(error, options = {}) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.5.8';
+const BUILT_CLI_VERSION = '0.5.10';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),
@@ -13263,11 +13263,13 @@ function installRemoteCommands(program, handlers, resolveLogger) {
         .command('deploy')
         .description('构建并提交当前小程序版本审核')
         .option('--skip-build', '跳过 build，直接读 dist 目录上传并提交审核')
+        .option('--from-version <version>', '复用指定历史版本产物提交审核')
         .option('--release-note <text>', '发布日志，提交审核必填')
         .option('--auto-publish', '审核通过后自动发布；默认需在 CLI 中手动发布')).action(createRemoteAction(handlers, resolveLogger, 'deploy', (command) => {
         const options = readCommandOptionsWithAncestors(command);
         return {
             autoPublish: Boolean(options.autoPublish),
+            fromVersion: readStringOption(options.fromVersion),
             releaseNote: readStringOption(options.releaseNote),
             skipBuild: Boolean(options.skipBuild),
         };
@@ -13372,31 +13374,31 @@ function createCommandLoggerResolver(options) {
     };
 }
 const defaultClearLoginStatus = async (...args) => {
-    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-Dwx2nD5p.cjs'); });
+    const { clearLoginStatus } = await Promise.resolve().then(function () { return require('./login-BX0YmVyi.cjs'); });
     return clearLoginStatus(...args);
 };
 const defaultLoginToHeybox = async (...args) => {
-    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-Dwx2nD5p.cjs'); });
+    const { loginToHeybox } = await Promise.resolve().then(function () { return require('./login-BX0YmVyi.cjs'); });
     return loginToHeybox(...args);
 };
 const defaultPrintLoginStatus = async (...args) => {
-    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-Dwx2nD5p.cjs'); });
+    const { printLoginStatus } = await Promise.resolve().then(function () { return require('./login-BX0YmVyi.cjs'); });
     return printLoginStatus(...args);
 };
 const defaultRunCreateCommand = async (...args) => {
-    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-DxRc3VpZ.cjs'); });
+    const { runCreateCommand } = await Promise.resolve().then(function () { return require('./create-D1W2pkHZ.cjs'); });
     return runCreateCommand(...args);
 };
 const defaultRunDevCommand = async (...args) => {
-    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-C9Jkdl7Y.cjs'); });
+    const { runDevCommand } = await Promise.resolve().then(function () { return require('./dev-DwbE-c1x.cjs'); });
     return runDevCommand(...args);
 };
 const defaultRunDoctorCommand = async (...args) => {
-    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-DoiRoJd5.cjs'); });
+    const { runDoctorCommand } = await Promise.resolve().then(function () { return require('./doctor-Bx71WFjM.cjs'); });
     return runDoctorCommand(...args);
 };
 const defaultRunRemoteCommand = async (...args) => {
-    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-C5pPFOvG.cjs'); }).then(function (n) { return n.remote; });
+    const { runRemoteCommand } = await Promise.resolve().then(function () { return require('./remote-YDmSxyYi.cjs'); }).then(function (n) { return n.remote; });
     return runRemoteCommand(...args);
 };
 function resolveStandaloneLogger(options, verbose) {

package/dist/cli-chunks/{index-DLZbkW1t.cjs → index-D5bZjpH9.cjs}

@@ -1,13 +1,13 @@
 'use strict';
 
-var index$2 = require('./index-Dyn_R89O.cjs');
+var index$2 = require('./index-BBatNb1l.cjs');
 var require$$0$2 = require('fs');
 var require$$2$1 = require('crypto');
 var require$$1$2 = require('path');
 var require$$0$3 = require('assert');
 var require$$4$2 = require('events');
 var require$$1$1 = require('util');
-var remote = require('./remote-C5pPFOvG.cjs');
+var remote = require('./remote-YDmSxyYi.cjs');
 var require$$0$5 = require('net');
 var require$$0$4 = require('url');
 var require$$2$2 = require('http');

package/dist/cli-chunks/{login-Dwx2nD5p.cjs → login-BX0YmVyi.cjs}

@@ -3,9 +3,9 @@
 var promises = require('node:readline/promises');
 var node_crypto = require('node:crypto');
 var node_http = require('node:http');
-var session = require('./session-tV_vO27h.cjs');
+var session = require('./session-BxZBXDZ-.cjs');
 var browser = require('./browser-RAy8e8cV.cjs');
-var index = require('./index-Dyn_R89O.cjs');
+var index = require('./index-BBatNb1l.cjs');
 require('node:path');
 require('fs');
 require('constants');

package/dist/cli-chunks/{remote-C5pPFOvG.cjs → remote-YDmSxyYi.cjs}

@@ -1,12 +1,12 @@
 'use strict';
 
 var promises = require('node:readline/promises');
-var session = require('./session-tV_vO27h.cjs');
+var session = require('./session-BxZBXDZ-.cjs');
 var childProcess = require('node:child_process');
 var fs = require('node:fs');
 var fs$1 = require('node:fs/promises');
 var path = require('node:path');
-var index = require('./index-Dyn_R89O.cjs');
+var index = require('./index-BBatNb1l.cjs');
 
 var re = {exports: {}};
 
@@ -3111,7 +3111,7 @@ async function createDefaultCosClient(uploadToken) {
     };
 }
 async function loadCosConstructor() {
-    const cosModule = await Promise.resolve().then(function () { return require('./index-DLZbkW1t.cjs'); }).then(function (n) { return n.index; });
+    const cosModule = await Promise.resolve().then(function () { return require('./index-D5bZjpH9.cjs'); }).then(function (n) { return n.index; });
     return cosModule.default;
 }
 function formatSize(bytes) {
@@ -3159,7 +3159,8 @@ async function precheckUserMiniprogramVersion$1(options, runtime = {}) {
         name: options.name,
         icon_url: options.iconUrl,
         cover_image_urls: options.coverImageUrls.join(','),
-        version: options.version,
+        ...(options.version ? { version: options.version } : {}),
+        ...(options.source_version ? { source_version: options.source_version } : {}),
         release_note: options.releaseNote,
         auto_publish: String(options.autoPublish),
     }, runtime);
@@ -3169,7 +3170,8 @@ async function submitUserMiniprogramAudit$1(options, runtime = {}) {
         name: options.name,
         icon_url: options.iconUrl,
         cover_image_urls: options.coverImageUrls.join(','),
-        manifest: JSON.stringify(options.manifest),
+        ...(options.manifest ? { manifest: JSON.stringify(options.manifest) } : {}),
+        ...(options.source_version ? { source_version: options.source_version } : {}),
         release_note: options.releaseNote,
         auto_publish: String(options.autoPublish),
     }, runtime);
@@ -3231,12 +3233,28 @@ async function runDeployCommand(options, runtime = {}) {
         throw new Error('未在 package.json 中找到 heybox.miniProgramId，请先配置 mini program id');
     }
     const miniProgramProfile = readMiniProgramVersionProfile(packageJson);
+    const fromVersion = options.fromVersion?.trim();
+    if (fromVersion && options.skipBuild) {
+        throw new Error('--from-version 与 --skip-build 不能同时使用：--from-version 会复用远端历史产物，不读取本地 dist/');
+    }
     const releaseNote = await resolveDeployReleaseNote(options, runtime);
     const session$1 = await logger.task('正在校验 Heybox 登录态', () => (runtime.requireAuthSession ?? session.requireHeyboxAuthSession)({ loginBaseUrl }), { successText: 'Heybox 登录态有效' });
     logger.debug(`Heybox API: ${apiBaseUrl}`);
     let precheckVersion;
     let parsedManifest;
-    if (!options.skipBuild) {
+    const historyArtifact = fromVersion ? { source_version: fromVersion } : {};
+    if (fromVersion) {
+        const precheck = await runVersionPrecheck({
+            session: session$1,
+            miniProgramId,
+            ...miniProgramProfile,
+            ...historyArtifact,
+            releaseNote,
+            autoPublish,
+        }, runtime, apiBaseUrl, projectRoot, logger);
+        precheckVersion = precheck.version || precheck.version_normalized || fromVersion;
+    }
+    else if (!options.skipBuild) {
         if (typeof packageJson.scripts?.build !== 'string') {
             throw new Error('package.json scripts.build 未定义，请添加 build 脚本或使用 --skip-build 跳过构建');
         }
@@ -3269,44 +3287,61 @@ async function runDeployCommand(options, runtime = {}) {
             autoPublish,
         }, runtime, apiBaseUrl, projectRoot, logger);
     }
-    const distDir = path.join(projectRoot, 'dist');
-    parsedManifest ??= await readDeployManifest(projectRoot, logger);
-    const { manifest, version } = parsedManifest;
-    if (version !== precheckVersion) {
-        throw new Error(`dist/manifest.json.version (${version}) 与预检版本 (${precheckVersion}) 不一致，请重新 build 后再 deploy`);
-    }
-    const uploadFiles = await logger.task('正在校验 dist 上传文件', async () => {
-        const allFiles = await walkDistFiles(distDir);
-        const blocked = allFiles.find((entry) => relativePathContainsNodeModulesSegment(entry.relativePath));
-        if (blocked) {
-            throw new Error(`dist 目录含 node_modules：${blocked.relativePath}`);
+    let submitAuditResult;
+    let version = precheckVersion;
+    let manifest;
+    if (!fromVersion) {
+        const distDir = path.join(projectRoot, 'dist');
+        parsedManifest ??= await readDeployManifest(projectRoot, logger);
+        ({ manifest, version } = parsedManifest);
+        if (version !== precheckVersion) {
+            throw new Error(`dist/manifest.json.version (${version}) 与预检版本 (${precheckVersion}) 不一致，请重新 build 后再 deploy`);
         }
-        const files = allFiles.filter((entry) => shouldUploadDistFile(entry.relativePath));
-        const pathError = validateUploadPaths(files, { miniProgramId, version, maxLength: ACTIVITY_UPLOAD_KEY_MAX_LENGTH });
-        if (pathError) {
-            throw new Error(pathError);
+        const uploadFiles = await logger.task('正在校验 dist 上传文件', async () => {
+            const allFiles = await walkDistFiles(distDir);
+            const blocked = allFiles.find((entry) => relativePathContainsNodeModulesSegment(entry.relativePath));
+            if (blocked) {
+                throw new Error(`dist 目录含 node_modules：${blocked.relativePath}`);
+            }
+            const files = allFiles.filter((entry) => shouldUploadDistFile(entry.relativePath));
+            const pathError = validateUploadPaths(files, { miniProgramId, version, maxLength: ACTIVITY_UPLOAD_KEY_MAX_LENGTH });
+            if (pathError) {
+                throw new Error(pathError);
+            }
+            const sizeError = validateUploadTotalSize(files);
+            if (sizeError) {
+                throw new Error(sizeError);
+            }
+            logger.debug(`待上传文件数: ${files.length}`);
+            return files;
+        }, { successText: 'dist 上传文件校验完成' });
+        try {
+            await (runtime.runUpload ?? runUpload)({ session: session$1, miniProgramId, version, files: uploadFiles }, { baseUrl: apiBaseUrl, fetchImpl: runtime.fetchImpl, logger });
         }
-        const sizeError = validateUploadTotalSize(files);
-        if (sizeError) {
-            throw new Error(sizeError);
+        catch (error) {
+            throw translateHeyboxDeployError(error, { projectRoot, stage: 'upload', version });
         }
-        logger.debug(`待上传文件数: ${files.length}`);
-        return files;
-    }, { successText: 'dist 上传文件校验完成' });
-    let submitAuditResult;
-    try {
-        await (runtime.runUpload ?? runUpload)({ session: session$1, miniProgramId, version, files: uploadFiles }, { baseUrl: apiBaseUrl, fetchImpl: runtime.fetchImpl, logger });
-    }
-    catch (error) {
-        throw translateHeyboxDeployError(error, { projectRoot, stage: 'upload', version });
     }
     try {
-        submitAuditResult = await logger.task('正在提交审核', () => (runtime.submitUserMiniprogramAudit ?? submitUserMiniprogramAudit$1)({ session: session$1, miniProgramId, ...miniProgramProfile, manifest, releaseNote, autoPublish }, { baseUrl: apiBaseUrl, fetchImpl: runtime.fetchImpl }), { successText: '审核提交完成' });
+        const submitOptions = fromVersion
+            ? { session: session$1, miniProgramId, ...miniProgramProfile, ...historyArtifact, releaseNote, autoPublish }
+            : { session: session$1, miniProgramId, ...miniProgramProfile, manifest, releaseNote, autoPublish };
+        submitAuditResult = await logger.task('正在提交审核', () => (runtime.submitUserMiniprogramAudit ?? submitUserMiniprogramAudit$1)(submitOptions, {
+            baseUrl: apiBaseUrl,
+            fetchImpl: runtime.fetchImpl,
+        }), { successText: '审核提交完成' });
     }
     catch (error) {
         throw translateHeyboxDeployError(error, { projectRoot, stage: 'submitAudit', version });
     }
-    printDeploySuccess({ autoPublish, logger, miniProgramId, mode: options.successOutputMode ?? 'legacy', protocolString: submitAuditResult.protocol_string, version });
+    printDeploySuccess({
+        autoPublish,
+        logger,
+        miniProgramId,
+        mode: options.successOutputMode ?? 'legacy',
+        protocolString: submitAuditResult.protocol_string,
+        version,
+    });
     return {
         autoPublish,
         changed: true,
@@ -3375,9 +3410,7 @@ function readCoverImageUrls(value) {
     if (!Array.isArray(value)) {
         throw new Error('heybox.miniProgramProfile.coverImageUrls 至少配置 1 张 HTTPS 图片');
     }
-    const urls = value
-        .map((item) => (typeof item === 'string' ? item.trim() : ''))
-        .filter(Boolean);
+    const urls = value.map((item) => (typeof item === 'string' ? item.trim() : '')).filter(Boolean);
     if (urls.length === 0) {
         throw new Error('heybox.miniProgramProfile.coverImageUrls 至少配置 1 张 HTTPS 图片');
     }
@@ -3446,13 +3479,14 @@ async function maybePromptReleaseNote(runtime) {
 }
 async function runVersionPrecheck(options, runtime, apiBaseUrl, projectRoot, logger) {
     try {
-        await logger.task(`正在预检版本 ${options.version}`, () => (runtime.precheckUserMiniprogramVersion ?? precheckUserMiniprogramVersion$1)(options, {
+        const label = options.version ?? options.source_version ?? '';
+        return await logger.task(`正在预检版本 ${label}`, () => (runtime.precheckUserMiniprogramVersion ?? precheckUserMiniprogramVersion$1)(options, {
             baseUrl: apiBaseUrl,
             fetchImpl: runtime.fetchImpl,
-        }), { successText: `版本 ${options.version} 预检通过` });
+        }), { successText: `版本 ${label} 预检通过` });
     }
     catch (error) {
-        throw translateHeyboxDeployError(error, { projectRoot, stage: 'precheck', version: options.version });
+        throw translateHeyboxDeployError(error, { projectRoot, stage: 'precheck', version: options.version ?? options.source_version ?? '' });
     }
 }
 function detectPackageManager(projectRoot) {
@@ -3632,10 +3666,11 @@ async function precheckUserMiniprogramVersion(options, runtime) {
     return remotePostForm(PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH, options, runtime);
 }
 async function submitUserMiniprogramAudit(options, runtime) {
-    return remotePostForm(SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH, {
-        ...options,
-        manifest: typeof options.manifest === 'string' ? options.manifest : JSON.stringify(options.manifest),
-    }, runtime);
+    const form = { ...options };
+    if (form.manifest && typeof form.manifest !== 'string') {
+        form.manifest = JSON.stringify(form.manifest);
+    }
+    return remotePostForm(SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH, form, runtime);
 }
 async function getVersionPreviewInfo(options, runtime) {
     return remoteGet(USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH, {
@@ -3897,6 +3932,7 @@ async function runRemoteDeployCommand(options, runtime) {
         apiBaseUrl: options.apiBaseUrl,
         autoPublish: options.autoPublish,
         env: options.env,
+        fromVersion: options.fromVersion,
         loginBaseUrl: options.loginBaseUrl,
         releaseNote: options.releaseNote,
         skipBuild: options.skipBuild,

package/dist/cli-chunks/{session-tV_vO27h.cjs → session-BxZBXDZ-.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./index-Dyn_R89O.cjs');
+var index = require('./index-BBatNb1l.cjs');
 var node_crypto = require('node:crypto');
 var path = require('node:path');
 var require$$0$2 = require('fs');

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./cli-chunks/index-Dyn_R89O.cjs');
+var index = require('./cli-chunks/index-BBatNb1l.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.5.8",
+  "version": "0.5.10",
   "description": "",
   "exports": {
     ".": {
@@ -117,6 +117,8 @@
     "build:types": "tsc -p tsconfig.dts.json",
     "check:boundary": "node scripts/check-boundary.cjs",
     "check:docs-sync": "node scripts/check-docs-sync.cjs",
+    "sync:agent-skills-payload": "node skill/scripts/sync-agent-skills-payload.mjs",
+    "check:agent-skills-payload": "node skill/scripts/sync-agent-skills-payload.mjs --check",
     "clean": "rimraf ./dist && rimraf ./types",
     "test:unit": "NODE_OPTIONS='--conditions=heybox' vitest run",
     "test:unit:coverage": "NODE_OPTIONS='--conditions=heybox' vitest run --coverage",

package/skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: hb-sdk
-description: Uses @heybox/hb-sdk and its hb-sdk CLI for Heybox external mini-program iframe pages, local mock development, template creation, skill version checks, and host/runtime protocol integration. Use for ready/auth/user/share/viewport/storage/network APIs, lifecycle events, hb-sdk create/dev/login/doctor, mock runtime debugging, custom SDK instances, or @heybox/hb-sdk/protocol contracts. Don't use for raw postMessage bridge construction in app code, direct cookie/token access, internal Heybox client protocols, separate mock runtimes, or non-Heybox SDKs.
+description: Uses @heybox/hb-sdk and its hb-sdk CLI for Heybox external mini-program iframe pages, local mock development, template creation, skill version checks, host/runtime protocol integration, and mini-program listing/audit/compliance review. Use for ready/auth/user/share/viewport/storage/network APIs, lifecycle events, hb-sdk create/dev/login/doctor, mock runtime debugging, custom SDK instances, or @heybox/hb-sdk/protocol contracts. Don't use for raw postMessage bridge construction in app code, direct cookie/token access, internal Heybox client protocols, separate mock runtimes, or non-Heybox SDKs.
 ---
 
 # hb-sdk Agent Procedure
@@ -12,8 +12,9 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 1. If the task is iframe mini-program business code, use the root package import path `@heybox/hb-sdk`.
 2. If the task is parent-container runtime, bridge-server, protocol contract, or `@heybox/hb-sdk-runtime` work, use `@heybox/hb-sdk/protocol` only for shared constants and types.
 3. If the task is project scaffolding, local Vite startup, browser mock runtime, CLI login cache, Agent Skill version diagnosis, or CLI troubleshooting, use the `hb-sdk` CLI workflow.
-4. If the task asks for direct login-state extraction, cookies, tokens, raw Heybox client protocols, or internal hb-sdk package paths, refuse that approach and use the public SDK or CLI boundary instead.
-5. If the task is not about Heybox external mini-program SDK usage, CLI usage, mock runtime, or protocol contracts, do not apply this skill.
+4. If the task is reviewing a mini-program for submission, listing, audit, publishing, content compliance, data/privacy compliance, runtime quality, or icon/cover design requirements, use the online publishing rules workflow.
+5. If the task asks for direct login-state extraction, cookies, tokens, raw Heybox client protocols, or internal hb-sdk package paths, refuse that approach and use the public SDK or CLI boundary instead.
+6. If the task is not about Heybox external mini-program SDK usage, CLI usage, mock runtime, protocol contracts, or mini-program listing/audit/compliance review, do not apply this skill.
 
 ## Step 2: Load only the needed reference
 
@@ -26,6 +27,7 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 7. For generated documentation provenance and deeper API lookup paths, read `references/llms-index.md`.
 8. For smoke-test expectations, positive examples, and anti-examples, read `references/examples.md`.
 9. For evaluating whether another agent followed this skill, read `references/smoke-evaluation.md`.
+10. For mini-program listing/audit/compliance review, fetch the online rules Markdown from `https://open.xiaoheihe.cn/docs/hb_sdk/llms/guide/mini-program-publishing-rules.md`. Do not rely on a bundled `references/` copy of this document; if the URL is unavailable or returns the docs app shell instead of Markdown, report that the online rules are unavailable and do not complete the review from stale local text.
 
 ## Step 3: Follow import rules
 
@@ -54,25 +56,26 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 6. Use `hb-sdk remote info`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for read/basic/preview management workflows. Mini-program name and image changes must go through version audit, so the CLI must not expose a basic-info update command.
 7. Use `hb-sdk remote deploy --release-note <text>` to build, upload, and submit the current project for audit. It reads `package.json.heybox.miniProgramId`, validates that the bound mini-program belongs to the server-side current entity before precheck/build/upload, prechecks `package.json.version` before build, runs the project's `build` script via the package manager auto-detected by lockfile, uploads `dist/` to CDN (skipping `manifest.json`, `.DS_Store`, `.map`), then calls the submit-audit API. The deploy upload pipeline rejects actual upload artifacts over 100MiB before any upload request, processes CDN upload metadata and callback confirmation at 50 files per batch, keeps 4-way upload concurrency within each batch, and validates CDN-returned keys exactly against the local expected upload keys.
 8. Use `hb-sdk remote deploy --skip-build --release-note <text>` only when the `dist/` directory is already prepared by an upstream CI stage. In this mode the CLI reads `dist/manifest.json.version` before precheck. Missing `dist/manifest.json` or `dist/index.html` aborts the run.
-9. Always provide a concise release note before deploy. Non-interactive environments must pass `--release-note`; interactive terminals may prompt for it. The default is manual release after approval with `hb-sdk remote release <version>`; use `--auto-publish` when the audited version should automatically release after approval.
-10. Use `hb-sdk remote release <version>`, `hb-sdk remote withdraw <version>`, `hb-sdk remote take-down`, and `hb-sdk remote reopen` for dangerous remote changes. Interactive terminals should confirm after showing enough context; non-interactive environments must pass `--yes`.
-11. For internal test/staging backend operations, use origin-only custom URLs: `HB_SDK_API_BASE_URL` or `hb-sdk remote ... --api-base-url <url>` for remote platform APIs, and `HB_SDK_LOGIN_BASE_URL` or `hb-sdk login --login-base-url <url>` for browser login. CLI flags override env vars. API base URLs must be Heybox trusted HTTPS origins by default; use `--allow-unsafe-api-base-url` or `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` only for local backend debugging. Do not include path, query, or hash in these URLs.
-12. For development routing or gray validation, configure `packages/hb-sdk/src/cli/config.ts` with `@heybox/hb-types` `RylaiServiceTagConfig` (`default_tag` / path-specific `special_tag`) to attach `x-rylai-service-tag` and the matching `special_tag` query parameter to Heybox backend API requests.
-13. If a remote command targets a custom login environment, pass the same `--login-base-url` or `HB_SDK_LOGIN_BASE_URL` used for `hb-sdk login`; remote commands reject cached CLI login state from a different login origin.
-14. Add `--verbose` / `-v` only when diagnosing failures; default CLI errors are intentionally concise, while verbose output includes backend envelope, HTTP status, trace fields, raw body, or original submit-audit failure details.
-15. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
-16. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
-17. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; the phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
-18. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
-19. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
-20. Treat `selectedEntity` in the CLI auth cache as a non-authoritative hint snapshot only. Every remote command must use the server-side current entity as the source of truth.
-21. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
-22. Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
-23. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
-24. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
-25. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
-26. Do not pass `mini_program_id` or `entity_id` as general CLI flags or environment variables; the mini-program id must come from `package.json.heybox.miniProgramId`, and the entity must come from the server-side current entity.
-27. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publish-pipeline helpers is `@heybox/hb-sdk/miniapp-publish`.
+9. Use `hb-sdk remote deploy --from-version <version> --release-note <text>` to reuse a previously uploaded remote version artifact and submit a new audit version without reading local `dist/`, building, or uploading. Do not combine `--from-version` with `--skip-build`.
+10. Always provide a concise release note before deploy. Non-interactive environments must pass `--release-note`; interactive terminals may prompt for it. The default is manual release after approval with `hb-sdk remote release <version>`; use `--auto-publish` when the audited version should automatically release after approval.
+11. Use `hb-sdk remote release <version>`, `hb-sdk remote withdraw <version>`, `hb-sdk remote take-down`, and `hb-sdk remote reopen` for dangerous remote changes. Interactive terminals should confirm after showing enough context; non-interactive environments must pass `--yes`.
+12. For internal test/staging backend operations, use origin-only custom URLs: `HB_SDK_API_BASE_URL` or `hb-sdk remote ... --api-base-url <url>` for remote platform APIs, and `HB_SDK_LOGIN_BASE_URL` or `hb-sdk login --login-base-url <url>` for browser login. CLI flags override env vars. API base URLs must be Heybox trusted HTTPS origins by default; use `--allow-unsafe-api-base-url` or `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` only for local backend debugging. Do not include path, query, or hash in these URLs.
+13. For development routing or gray validation, configure `packages/hb-sdk/src/cli/config.ts` with `@heybox/hb-types` `RylaiServiceTagConfig` (`default_tag` / path-specific `special_tag`) to attach `x-rylai-service-tag` and the matching `special_tag` query parameter to Heybox backend API requests.
+14. If a remote command targets a custom login environment, pass the same `--login-base-url` or `HB_SDK_LOGIN_BASE_URL` used for `hb-sdk login`; remote commands reject cached CLI login state from a different login origin.
+15. Add `--verbose` / `-v` only when diagnosing failures; default CLI errors are intentionally concise, while verbose output includes backend envelope, HTTP status, trace fields, raw body, or original submit-audit failure details.
+16. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
+17. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
+18. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; the phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
+19. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
+20. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
+21. Treat `selectedEntity` in the CLI auth cache as a non-authoritative hint snapshot only. Every remote command must use the server-side current entity as the source of truth.
+22. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
+23. Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
+24. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+25. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
+26. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
+27. Do not pass `mini_program_id` or `entity_id` as general CLI flags or environment variables; the mini-program id must come from `package.json.heybox.miniProgramId`, and the entity must come from the server-side current entity.
+28. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publish-pipeline helpers is `@heybox/hb-sdk/miniapp-publish`.
 
 ## Step 6: Preserve capability boundaries
 

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.5.7`
+- Version at generation time: `0.5.9`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`

package/skill/references/cli.md

@@ -56,7 +56,7 @@ hb-sdk remote allowlist list
 hb-sdk remote allowlist add <heybox-id...>
 hb-sdk remote allowlist remove <heybox-id...>
 hb-sdk remote allowlist set <heybox-id...>
-hb-sdk remote deploy --release-note <text> [--skip-build] [--auto-publish]
+hb-sdk remote deploy --release-note <text> [--skip-build | --from-version <version>] [--auto-publish]
 hb-sdk remote versions
 hb-sdk remote preview <version>
 hb-sdk remote release <version> [--yes]
@@ -132,6 +132,7 @@ Use `hb-sdk dev` for local browser SDK debugging. Use the Mock runtime host's "
 hb-sdk remote deploy --release-note "修复登录状态展示，补充异常提示"
 hb-sdk remote deploy --release-note "审核通过后自动发布" --auto-publish
 hb-sdk remote deploy --skip-build --release-note "复用已有 dist 构建产物"
+hb-sdk remote deploy --from-version 1.2.3 --release-note "复用 1.2.3 历史产物"
 hb-sdk remote deploy --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "测试环境验证"
 hb-sdk remote deploy --verbose --api-base-url https://api.test.xiaoheihe.cn --login-base-url https://login.test.xiaoheihe.cn --release-note "排查预检失败"
 HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://127.0.0.1:8080 --release-note "本地后台联调"
@@ -145,13 +146,14 @@ HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1 hb-sdk remote deploy --api-base-url http://12
 4. 读取并校验 `--release-note`；TTY 环境缺失时会提示输入，CI / 非 TTY 环境缺失时直接失败。建议让 AI 生成 1-5 条简短发布日志。
 5. 普通 remote deploy 先读取 `package.json.version`，登录后、build 前调用版本预检接口；预检通过后才执行 `<pm> run build`。
 6. `--skip-build` 跳过构建，但会先读取已有 `dist/manifest.json.version`，再调用版本预检接口。
-7. 解析 `dist/manifest.json`，自动剥离 BOM，并校验 `version` 是合法 SemVer：允许 prerelease，例如 `1.2.3-rc.1`；拒绝 build metadata，例如 `1.2.3+build.1`；拒绝 `0.0.0`。
-8. 普通 remote deploy 的 `dist/manifest.json.version` 必须与预检使用的 `package.json.version` 一致，否则失败且不上传。
-9. 遍历 `dist/` 文件，过滤掉 `manifest.json`、`.DS_Store`、`*.map`；遇到 symbolic link 或 `node_modules` 路径直接报错。
-10. 校验上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
-11. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 CDN。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
-12. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
-13. 全部上传成功后调用提交审核接口，CLI 输出提交审核成功、发布策略和可用的 preview URL。
+7. `--from-version <version>` 跳过本地构建、`dist/` 读取和上传，复用指定历史版本产物提交审核；它与 `--skip-build` 互斥。
+8. 解析 `dist/manifest.json`，自动剥离 BOM，并校验 `version` 是合法 SemVer：允许 prerelease，例如 `1.2.3-rc.1`；拒绝 build metadata，例如 `1.2.3+build.1`；拒绝 `0.0.0`。
+9. 普通 remote deploy 的 `dist/manifest.json.version` 必须与预检使用的 `package.json.version` 一致，否则失败且不上传。
+10. 遍历 `dist/` 文件，过滤掉 `manifest.json`、`.DS_Store`、`*.map`；遇到 symbolic link 或 `node_modules` 路径直接报错。
+11. 校验上传路径长度不超过 64，并在任何上传请求发生前限制实际上传产物总大小不超过 100MiB。错误提示中使用 `100MB`，方便开发者理解。
+12. 上传信息、上传凭证和上传回调按批次执行，每批最多 50 个文件；批次串行，批内保持 4 并发上传到 CDN。CLI 会校验 CDN 上传信息接口返回的 key 与本地期望 key 完全一致，异常时停止后续批次且不提交审核。
+13. 默认只展示上传阶段和文件总数，例如 `正在上传 137/244 个文件`；`--verbose` 会展示并发数、批次数、当前批次、bucket / region 和逐文件结果，但不会输出 keys、签名、cookie、pkey、token 或临时密钥。
+14. 全部上传成功后调用提交审核接口；`--from-version` 路径会直接提交 `source_version`。CLI 输出提交审核成功、发布策略和可用的 preview URL。
 
 `mini_program_id` 没有 CLI flag，必须落在 `package.json` 里：
 
@@ -176,6 +178,7 @@ Before precheck, build, upload, or submit audit, `hb-sdk remote deploy` must ver
 Agent rules:
 
 - Use `hb-sdk remote deploy --release-note <text>` for normal build, upload, and submit-audit flows.
+- Use `hb-sdk remote deploy --from-version <version> --release-note <text>` to reuse a remote history artifact. Do not combine `--from-version` with `--skip-build`.
 - Verify remote deploy guidance says current-entity mismatch fails before precheck/build/upload/submit and never auto-switches the developer entity.
 - Never recommend top-level `hb-sdk deploy`; it has been removed rather than retained as a compatibility alias.
 - After non-auto deploy succeeds, suggest `hb-sdk remote versions` and then `hb-sdk remote release <version>` after approval. Do not send the user to Open for manual publish when the CLI command exists.

package/skill/references/llms-index.md

@@ -35,6 +35,7 @@ This site documents the iframe-side SDK for external mini programs. For AI retri
 - [错误处理](./llms/guide/error-handling.md): SDK 对外抛出的标准错误类型是 `HbMiniProgramSDKError`。
 - [安装与运行环境](./llms/guide/installation.md): 如果工坊小程序只是普通展示页面，不调用黑盒开放能力，也不监听 SDK 生命周期事件，可以不安装、不引用、不初始化 `@heybox/hb-sdk`。父容器仍可能在 URL 上注入 `hb_mini_bridge_nonce`，业务页可以直接忽略。
 - [事件与生命周期](./llms/guide/lifecycle.md): SDK 通过 `on` 监听父容器派发的小程序生命周期和业务事件。
+- [小程序工坊上架规则 v2（试行）](./llms/guide/mini-program-publishing-rules.md): 本规则用于说明小程序工坊的小程序发布、上架和持续在线要求。通过审核不等于获得推荐或公开展示；工坊广场、推荐位、搜索等流量分发规则另行制定。
 - [快速开始](./llms/guide/quick-start.md): 如果页面不需要黑盒开放能力，可以不接入 SDK。这是一条需要用户能力时的最短接入路径：等待 SDK 完成握手，然后读取当前用户登录态。
 ## Recipes
 - [独立 SDK 实例](./llms/recipes/custom-instance.md): 大多数业务页使用默认单例即可。只有在需要隔离上下文时，再创建独立实例。

package/skill/scripts/sync-agent-skills-payload.mjs

@@ -0,0 +1,359 @@
+#!/usr/bin/env node
+import { Buffer } from 'node:buffer';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { HB_SDK_PACKAGE_NAME } from './skill-metadata.mjs';
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+const HB_SDK_ROOT = path.resolve(SCRIPT_DIR, '../..');
+const REPO_ROOT = path.resolve(HB_SDK_ROOT, '../..');
+const WELL_KNOWN_ROOT = path.join('.well-known', 'agent-skills');
+const AGENT_SKILL_PACKAGES = [
+  {
+    packageName: HB_SDK_PACKAGE_NAME,
+    skillDir: 'skill',
+  },
+];
+
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
+const TEXT_FILE_RE = /\.(?:md|mjs|js|cjs|ts|tsx|json|txt|sh|yaml|yml)$/i;
+const PREFERRED_ORDER = new Map([
+  ['SKILL.md', 0],
+  ['skill.json', 1],
+  ['references/api-root.md', 100],
+  ['references/api-protocol.md', 101],
+  ['references/cli.md', 102],
+  ['references/recipes.md', 103],
+  ['references/safety-boundaries.md', 104],
+  ['references/llms-index.md', 105],
+  ['references/examples.md', 106],
+  ['references/smoke-evaluation.md', 107],
+  ['scripts/sync-references.mjs', 200],
+  ['scripts/check-references.mjs', 201],
+  ['scripts/validate-skill.mjs', 202],
+  ['scripts/package-skill.mjs', 203],
+  ['scripts/package-skill.sh', 204],
+]);
+
+function parseCliArgs(argv) {
+  const args = argv.slice(2);
+  let outDir = path.resolve(process.cwd(), '.agent-skills-payload');
+  let check = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--check') {
+      check = true;
+      continue;
+    }
+    if (arg === '--out-dir') {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error('--out-dir requires a path argument');
+      }
+      outDir = path.resolve(process.cwd(), value);
+      index += 1;
+    }
+  }
+
+  return { outDir, check };
+}
+
+function toPosixPath(value) {
+  return value.split(path.sep).join('/');
+}
+
+function assertSafeRelativePath(relativePath, context) {
+  const normalized = path.posix.normalize(relativePath);
+
+  if (path.isAbsolute(relativePath) || normalized.startsWith('../') || normalized === '..') {
+    throw new Error(`${context} has unsafe path: ${relativePath}`);
+  }
+
+  if (normalized !== relativePath) {
+    throw new Error(`${context} must be normalized: ${relativePath}`);
+  }
+
+  if (relativePath.includes('/../') || relativePath.endsWith('/..')) {
+    throw new Error(`${context} cannot contain parent traversal: ${relativePath}`);
+  }
+
+  if (/\.zip$/i.test(relativePath)) {
+    throw new Error(`${context} must not include zip archives: ${relativePath}`);
+  }
+}
+
+function parseFrontmatter(skillText, skillPath) {
+  const match = skillText.match(FRONTMATTER_RE);
+  if (!match) {
+    throw new Error(`${skillPath} is missing YAML frontmatter`);
+  }
+
+  const metadata = {};
+  for (const rawLine of match[1].split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#') || line.startsWith('metadata:')) {
+      continue;
+    }
+
+    const keyValue = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!keyValue) {
+      continue;
+    }
+
+    const [, key, rawValue] = keyValue;
+    metadata[key] = rawValue.replace(/^['"]|['"]$/g, '').trim();
+  }
+
+  return metadata;
+}
+
+async function exists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function readJsonFile(filePath) {
+  return JSON.parse(await fs.readFile(filePath, 'utf8'));
+}
+
+async function resolvePackageRoot(packageSource) {
+  if (packageSource.packageName !== HB_SDK_PACKAGE_NAME) {
+    throw new Error(`Unsupported agent skill package: ${packageSource.packageName}`);
+  }
+
+  if (!(await exists(path.join(HB_SDK_ROOT, 'package.json')))) {
+    throw new Error(`Cannot resolve ${packageSource.packageName}: missing package root at ${toPosixPath(HB_SDK_ROOT)}`);
+  }
+
+  return HB_SDK_ROOT;
+}
+
+async function listFilesRecursive(rootDir, relativeBase = '', options = {}) {
+  if (!(await exists(rootDir))) {
+    return [];
+  }
+
+  const entries = await fs.readdir(rootDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    if (!options.includeHidden && entry.name.startsWith('.')) {
+      continue;
+    }
+
+    const absolutePath = path.join(rootDir, entry.name);
+    const relativePath = path.posix.join(relativeBase, entry.name);
+
+    if (entry.isDirectory()) {
+      files.push(...(await listFilesRecursive(absolutePath, relativePath, options)));
+      continue;
+    }
+
+    if (entry.isFile()) {
+      files.push(relativePath);
+    }
+  }
+
+  return files;
+}
+
+function sortSkillFiles(files) {
+  return [...files].sort((left, right) => {
+    const leftOrder = PREFERRED_ORDER.get(left) ?? 10_000;
+    const rightOrder = PREFERRED_ORDER.get(right) ?? 10_000;
+    return leftOrder - rightOrder || left.localeCompare(right);
+  });
+}
+
+async function discoverSkill(packageSource) {
+  const packageRoot = await resolvePackageRoot(packageSource);
+  const skillDir = path.join(packageRoot, packageSource.skillDir);
+  const skillMarkdownPath = path.join(skillDir, 'SKILL.md');
+
+  if (!(await exists(skillMarkdownPath))) {
+    throw new Error(`${packageSource.packageName} must provide ${packageSource.skillDir}/SKILL.md.`);
+  }
+
+  const skillMarkdown = await fs.readFile(skillMarkdownPath, 'utf8');
+  const frontmatter = parseFrontmatter(skillMarkdown, skillMarkdownPath);
+  const skillName = frontmatter.name;
+
+  if (!skillName) {
+    throw new Error(`${skillMarkdownPath} frontmatter must include name`);
+  }
+
+  if (!frontmatter.description) {
+    throw new Error(`${skillMarkdownPath} frontmatter must include description`);
+  }
+
+  const files = ['SKILL.md'];
+  const skillJsonPath = path.join(skillDir, 'skill.json');
+  let metadata = null;
+
+  if (await exists(skillJsonPath)) {
+    const relativeFile = 'skill.json';
+    assertSafeRelativePath(relativeFile, `${skillName} source file`);
+    files.push(relativeFile);
+    metadata = await readJsonFile(skillJsonPath);
+    if (metadata.name !== skillName) {
+      throw new Error(`${skillJsonPath} name (${metadata.name}) must match SKILL.md frontmatter (${skillName})`);
+    }
+  }
+
+  for (const topLevelDir of ['references', 'scripts', 'assets']) {
+    const nestedFiles = await listFilesRecursive(path.join(skillDir, topLevelDir), topLevelDir);
+    for (const relativeFile of nestedFiles) {
+      if (!TEXT_FILE_RE.test(relativeFile)) {
+        continue;
+      }
+      assertSafeRelativePath(relativeFile, `${skillName} source file`);
+      files.push(relativeFile);
+    }
+  }
+
+  return {
+    sourceDir: skillDir,
+    name: skillName,
+    description: frontmatter.description,
+    files: sortSkillFiles(files),
+    metadata,
+  };
+}
+
+async function discoverSkills() {
+  const skills = [];
+
+  for (const packageSource of AGENT_SKILL_PACKAGES) {
+    skills.push(await discoverSkill(packageSource));
+  }
+
+  if (skills.length === 0) {
+    throw new Error('No configured agent skills found.');
+  }
+
+  return skills;
+}
+
+export function createSkillIndex(skills) {
+  return {
+    skills: skills.map((skill) => ({
+      name: skill.name,
+      description: skill.description,
+      ...(skill.metadata
+        ? {
+            version: skill.metadata.skillVersion,
+            sdk: skill.metadata.sdk,
+            source: skill.metadata.source,
+            integrity: skill.metadata.integrity,
+          }
+        : {}),
+      files: skill.files,
+    })),
+  };
+}
+
+async function addIndexFile(outputFiles, baseDir, skills) {
+  const indexPath = path.join(baseDir, WELL_KNOWN_ROOT, 'index.json');
+  const index = createSkillIndex(skills);
+
+  outputFiles.set(indexPath, Buffer.from(`${JSON.stringify(index, null, 2)}\n`, 'utf8'));
+}
+
+async function addSkillFiles(outputFiles, baseDir, skills) {
+  for (const skill of skills) {
+    for (const relativeFile of skill.files) {
+      assertSafeRelativePath(relativeFile, `${skill.name} generated file`);
+      const sourcePath = path.join(skill.sourceDir, ...relativeFile.split('/'));
+      const targetPath = path.join(baseDir, WELL_KNOWN_ROOT, skill.name, ...relativeFile.split('/'));
+      outputFiles.set(targetPath, await fs.readFile(sourcePath));
+    }
+  }
+}
+
+async function buildExpectedOutput(skills, targetRoot) {
+  const outputFiles = new Map();
+
+  await addIndexFile(outputFiles, targetRoot, skills);
+  await addSkillFiles(outputFiles, targetRoot, skills);
+
+  return outputFiles;
+}
+
+async function listExistingGeneratedFiles(targetRoot) {
+  if (!(await exists(targetRoot))) {
+    return [];
+  }
+
+  const relativeFiles = await listFilesRecursive(targetRoot, '', { includeHidden: true });
+  return relativeFiles.map((relativeFile) => path.join(targetRoot, ...relativeFile.split('/')));
+}
+
+async function syncFiles(expectedOutput, targetRoot) {
+  await fs.rm(targetRoot, { recursive: true, force: true });
+
+  for (const [targetPath, content] of [...expectedOutput.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+    await fs.writeFile(targetPath, content);
+  }
+}
+
+async function checkFiles(expectedOutput, targetRoot) {
+  const expectedPaths = new Set(expectedOutput.keys());
+  const existingPaths = new Set(await listExistingGeneratedFiles(targetRoot));
+  const problems = [];
+
+  for (const expectedPath of [...expectedPaths].sort()) {
+    if (!existingPaths.has(expectedPath)) {
+      problems.push(`missing ${path.relative(REPO_ROOT, expectedPath)}`);
+      continue;
+    }
+
+    const actual = await fs.readFile(expectedPath);
+    const expected = expectedOutput.get(expectedPath);
+    if (!actual.equals(expected)) {
+      problems.push(`stale ${path.relative(REPO_ROOT, expectedPath)}`);
+    }
+  }
+
+  for (const existingPath of [...existingPaths].sort()) {
+    if (!expectedPaths.has(existingPath)) {
+      problems.push(`extra ${path.relative(REPO_ROOT, existingPath)}`);
+    }
+  }
+
+  if (problems.length > 0) {
+    throw new Error(`Agent skills payload is out of sync:\n${problems.map((problem) => `- ${problem}`).join('\n')}`);
+  }
+}
+
+async function main() {
+  const { outDir, check } = parseCliArgs(process.argv);
+  const skills = await discoverSkills();
+  const expectedOutput = await buildExpectedOutput(skills, outDir);
+
+  if (check) {
+    await checkFiles(expectedOutput, outDir);
+    console.log(
+      `Agent skills payload is in sync at ${toPosixPath(path.relative(REPO_ROOT, outDir))} (${expectedOutput.size} files, ${skills.length} skills).`,
+    );
+    return;
+  }
+
+  await syncFiles(expectedOutput, outDir);
+  console.log(
+    `Synced ${skills.length} skills to ${toPosixPath(path.relative(REPO_ROOT, outDir))} (${expectedOutput.size} files).`,
+  );
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((error) => {
+    console.error(error.message);
+    process.exitCode = 1;
+  });
+}

package/skill/scripts/sync-references.mjs

@@ -225,7 +225,7 @@ hb-sdk remote allowlist list
 hb-sdk remote allowlist add <heybox-id...>
 hb-sdk remote allowlist remove <heybox-id...>
 hb-sdk remote allowlist set <heybox-id...>
-hb-sdk remote deploy --release-note <text> [--skip-build] [--auto-publish]
+hb-sdk remote deploy --release-note <text> [--skip-build | --from-version <version>] [--auto-publish]
 hb-sdk remote versions
 hb-sdk remote preview <version>
 hb-sdk remote release <version> [--yes]
@@ -385,6 +385,7 @@ ${cliRemoteEntityDeploySection}
 Agent rules:
 
 - Use \`hb-sdk remote deploy --release-note <text>\` for normal build, upload, and submit-audit flows.
+- Use \`hb-sdk remote deploy --from-version <version> --release-note <text>\` to reuse a remote history artifact. Do not combine \`--from-version\` with \`--skip-build\`.
 - Verify remote deploy guidance says current-entity mismatch fails before precheck/build/upload/submit and never auto-switches the developer entity.
 - Never recommend top-level \`hb-sdk deploy\`; it has been removed rather than retained as a compatibility alias.
 - After non-auto deploy succeeds, suggest \`hb-sdk remote versions\` and then \`hb-sdk remote release <version>\` after approval. Do not send the user to Open for manual publish when the CLI command exists.

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.5.7+skill.90b5f340fde8",
+  "skillVersion": "0.5.9+skill.02be68ce07ce",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.5.7",
-    "compatibility": "0.5.7"
+    "version": "0.5.9",
+    "compatibility": "0.5.9"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-90b5f340fde847a24ce8fe26b6f2134999c19deb0ac0585a431149ca97aa117b"
+  "integrity": "sha256-02be68ce07ce1cf0ecba354d764a47977e4fc3c189b5e4aed3cee1f844fddfd4"
 }