@heybox/hb-sdk 0.2.0-alpha.2 → 0.3.1

package/dist/cli.cjs

@@ -22,14 +22,14 @@ var require$$4$3 = require('https');
 var require$$5$2 = require('zlib');
 var require$$1$4 = require('querystring');
 var require$$3$3 = require('tls');
-var node_http = require('node:http');
+var node_crypto = require('node:crypto');
 var node_url = require('node:url');
 var net = require('node:net');
 var os = require('node:os');
+var node_http = require('node:http');
 var process$1 = require('node:process');
 var node_buffer = require('node:buffer');
 var node_util = require('node:util');
-var node_crypto = require('node:crypto');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 var commonjsGlobal = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : typeof global !== 'undefined' ? global : typeof self !== 'undefined' ? self : {};
@@ -5162,15 +5162,55 @@ function quoteShellPath(value) {
     return `'${value.replace(/'/g, "'\\''")}'`;
 }
 
+const MINIAPP_TEMPLATE_VERSION = '0.0.0';
+const PUBLISH_VERSION_RE = /^\d+\.\d+\.\d+$/;
+function isValidMiniappManifestVersion(version) {
+    return PUBLISH_VERSION_RE.test(String(version || '').trim());
+}
+function parseMiniappManifestJson(raw, sourceLabel = 'manifest.json') {
+    const hadBom = raw.charCodeAt(0) === 0xfeff;
+    const text = hadBom ? raw.slice(1) : raw;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new Error(`${sourceLabel} 不是合法 JSON：${formatReason(error)}`);
+    }
+    if (!isManifestRecord(parsed)) {
+        throw new Error(`${sourceLabel} 必须是 JSON 对象`);
+    }
+    return {
+        manifest: {
+            version: parsed.version,
+        },
+        hadBom,
+    };
+}
+function validateMiniappManifestForDeploy(manifest) {
+    if (manifest.version === MINIAPP_TEMPLATE_VERSION) {
+        throw new Error('manifest.version 仍是模板默认的 0.0.0，请改成实际版本号后再发布');
+    }
+    if (typeof manifest.version !== 'string' || !isValidMiniappManifestVersion(manifest.version)) {
+        throw new Error(`manifest.version 格式错误，必须是 x.y.z：${String(manifest.version)}`);
+    }
+    return manifest.version;
+}
+function isManifestRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function formatReason(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+
 const MINIAPP_UPLOAD_SCOPE = 'activity';
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 const PUBLISH_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/publish';
-const VERSION_PATTERN = /^\d+\.\d+\.\d+$/;
 const FNV_OFFSET = 0x811c9dc5;
 const FNV_PRIME = 0x01000193;
-function isValidVersion(version) {
-    return VERSION_PATTERN.test(String(version || '').trim());
-}
 function normalizeRelativePath(relativePath) {
     return String(relativePath || '')
         .replace(/\\/g, '/')
@@ -6596,30 +6636,47 @@ function requireUtimes () {
 	const u = requireUniversalify().fromPromise;
 
 	async function utimesMillis (path, atime, mtime) {
-	  // if (!HAS_MILLIS_RES) return fs.utimes(path, atime, mtime, callback)
 	  const fd = await fs.open(path, 'r+');
 
-	  let closeErr = null;
+	  let error = null;
 
 	  try {
 	    await fs.futimes(fd, atime, mtime);
+	  } catch (futimesErr) {
+	    error = futimesErr;
 	  } finally {
 	    try {
 	      await fs.close(fd);
-	    } catch (e) {
-	      closeErr = e;
+	    } catch (closeErr) {
+	      if (!error) error = closeErr;
 	    }
 	  }
 
-	  if (closeErr) {
-	    throw closeErr
+	  if (error) {
+	    throw error
 	  }
 	}
 
 	function utimesMillisSync (path, atime, mtime) {
 	  const fd = fs.openSync(path, 'r+');
-	  fs.futimesSync(fd, atime, mtime);
-	  return fs.closeSync(fd)
+
+	  let error = null;
+
+	  try {
+	    fs.futimesSync(fd, atime, mtime);
+	  } catch (futimesErr) {
+	    error = futimesErr;
+	  } finally {
+	    try {
+	      fs.closeSync(fd);
+	    } catch (closeErr) {
+	      if (!error) error = closeErr;
+	    }
+	  }
+
+	  if (error) {
+	    throw error
+	  }
 	}
 
 	utimes = {
@@ -7383,14 +7440,14 @@ function requireLink () {
 	async function createLink (srcpath, dstpath) {
 	  let dstStat;
 	  try {
-	    dstStat = await fs.lstat(dstpath);
+	    dstStat = await fs.lstat(dstpath, { bigint: true });
 	  } catch {
 	    // ignore error
 	  }
 
 	  let srcStat;
 	  try {
-	    srcStat = await fs.lstat(srcpath);
+	    srcStat = await fs.lstat(srcpath, { bigint: true });
 	  } catch (err) {
 	    err.message = err.message.replace('lstat', 'ensureLink');
 	    throw err
@@ -7412,11 +7469,11 @@ function requireLink () {
 	function createLinkSync (srcpath, dstpath) {
 	  let dstStat;
 	  try {
-	    dstStat = fs.lstatSync(dstpath);
+	    dstStat = fs.lstatSync(dstpath, { bigint: true });
 	  } catch {}
 
 	  try {
-	    const srcStat = fs.lstatSync(srcpath);
+	    const srcStat = fs.lstatSync(srcpath, { bigint: true });
 	    if (dstStat && areIdentical(srcStat, dstStat)) return
 	  } catch (err) {
 	    err.message = err.message.replace('lstat', 'ensureLink');
@@ -7620,18 +7677,18 @@ function requireSymlink () {
 	    // (standard symlink behavior) or fall back to cwd if that doesn't exist
 	    let srcStat;
 	    if (path.isAbsolute(srcpath)) {
-	      srcStat = await fs.stat(srcpath);
+	      srcStat = await fs.stat(srcpath, { bigint: true });
 	    } else {
 	      const dstdir = path.dirname(dstpath);
 	      const relativeToDst = path.join(dstdir, srcpath);
 	      try {
-	        srcStat = await fs.stat(relativeToDst);
+	        srcStat = await fs.stat(relativeToDst, { bigint: true });
 	      } catch {
-	        srcStat = await fs.stat(srcpath);
+	        srcStat = await fs.stat(srcpath, { bigint: true });
 	      }
 	    }
 
-	    const dstStat = await fs.stat(dstpath);
+	    const dstStat = await fs.stat(dstpath, { bigint: true });
 	    if (areIdentical(srcStat, dstStat)) return
 	  }
 
@@ -7657,18 +7714,18 @@ function requireSymlink () {
 	    // (standard symlink behavior) or fall back to cwd if that doesn't exist
 	    let srcStat;
 	    if (path.isAbsolute(srcpath)) {
-	      srcStat = fs.statSync(srcpath);
+	      srcStat = fs.statSync(srcpath, { bigint: true });
 	    } else {
 	      const dstdir = path.dirname(dstpath);
 	      const relativeToDst = path.join(dstdir, srcpath);
 	      try {
-	        srcStat = fs.statSync(relativeToDst);
+	        srcStat = fs.statSync(relativeToDst, { bigint: true });
 	      } catch {
-	        srcStat = fs.statSync(srcpath);
+	        srcStat = fs.statSync(srcpath, { bigint: true });
 	      }
 	    }
 
-	    const dstStat = fs.statSync(dstpath);
+	    const dstStat = fs.statSync(dstpath, { bigint: true });
 	    if (areIdentical(srcStat, dstStat)) return
 	  }
 
@@ -8224,7 +8281,7 @@ function createCookie(name, value) {
     return `${name}=${value}`;
 }
 function isHeyboxAuthSession(value) {
-    if (!isRecord$1(value)) {
+    if (!isRecord$2(value)) {
         return false;
     }
     return (typeof value.heyboxId === 'string' &&
@@ -8233,7 +8290,7 @@ function isHeyboxAuthSession(value) {
         typeof value.cookieHeader === 'string' &&
         typeof value.loggedInAt === 'string');
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
     return Object.prototype.toString.call(value) === '[object Object]';
 }
 
@@ -59248,11 +59305,6 @@ function requireCompile () {
 	    , defaultsHash = {}
 	    , customRules = [];
 
-	  function patternCode(i, patterns) {
-	    var regExpCode = opts.regExp ? 'regExp' : 'new RegExp';
-	    return 'var pattern' + i + ' = ' + regExpCode + '(' + util.toQuotedString(patterns[i]) + ');';
-	  }
-
 	  root = root || { schema: schema, refVal: refVal, refs: refs };
 
 	  var c = checkCompiling.call(this, schema, root, baseId);
@@ -59339,7 +59391,6 @@ function requireCompile () {
 	        'equal',
 	        'ucs2length',
 	        'ValidationError',
-	        'regExp',
 	        sourceCode
 	      );
 
@@ -59353,8 +59404,7 @@ function requireCompile () {
 	        customRules,
 	        equal,
 	        ucs2length,
-	        ValidationError,
-	        opts.regExp
+	        ValidationError
 	      );
 
 	      refVal[0] = validate;
@@ -59571,6 +59621,11 @@ function requireCompile () {
 	}
 
 
+	function patternCode(i, patterns) {
+	  return 'var pattern' + i + ' = new RegExp(' + util.toQuotedString(patterns[i]) + ');';
+	}
+
+
 	function defaultCode(i) {
 	  return 'var default' + i + ' = defaults[' + i + '];';
 	}
@@ -61594,7 +61649,6 @@ function requirePattern () {
 	  var $errSchemaPath = it.errSchemaPath + '/' + $keyword;
 	  var $breakOnError = !it.opts.allErrors;
 	  var $data = 'data' + ($dataLvl || '');
-	  var $valid = 'valid' + $lvl;
 	  var $isData = it.opts.$data && $schema && $schema.$data,
 	    $schemaValue;
 	  if ($isData) {
@@ -61603,21 +61657,12 @@ function requirePattern () {
 	  } else {
 	    $schemaValue = $schema;
 	  }
-	  var $regExpCode = it.opts.regExp ? 'regExp' : 'new RegExp';
+	  var $regexp = $isData ? '(new RegExp(' + $schemaValue + '))' : it.usePattern($schema);
+	  out += 'if ( ';
 	  if ($isData) {
-	    out += ' var ' + ($valid) + ' = true; try { ' + ($valid) + ' = ' + ($regExpCode) + '(' + ($schemaValue) + ').test(' + ($data) + '); } catch(e) { ' + ($valid) + ' = false; } if ( ';
-	    if ($isData) {
-	      out += ' (' + ($schemaValue) + ' !== undefined && typeof ' + ($schemaValue) + ' != \'string\') || ';
-	    }
-	    out += ' !' + ($valid) + ') {';
-	  } else {
-	    var $regexp = it.usePattern($schema);
-	    out += ' if ( ';
-	    if ($isData) {
-	      out += ' (' + ($schemaValue) + ' !== undefined && typeof ' + ($schemaValue) + ' != \'string\') || ';
-	    }
-	    out += ' !' + ($regexp) + '.test(' + ($data) + ') ) {';
+	    out += ' (' + ($schemaValue) + ' !== undefined && typeof ' + ($schemaValue) + ' != \'string\') || ';
 	  }
+	  out += ' !' + ($regexp) + '.test(' + ($data) + ') ) {   ';
 	  var $$outStack = $$outStack || [];
 	  $$outStack.push(out);
 	  out = ''; /* istanbul ignore else */
@@ -75090,8 +75135,105 @@ function requireCosNodejsSdkV5 () {
 var cosNodejsSdkV5Exports = requireCosNodejsSdkV5();
 var COS = /*@__PURE__*/getDefaultExportFromCjs(cosNodejsSdkV5Exports);
 
+const SIGN_VERSION = '999.0.4';
+const SIGN_CHARSET = 'AB45STUVWZEFGJ6CH01D237IXYPQRKLMN89';
+function createHeyboxOpenPlatformSignParams(pathname, options = {}) {
+    const now = options.now ?? new Date();
+    const time = Math.trunc(now.getTime() / 1000);
+    const nonce = options.nonce ?? md5(`${time}${Date.now()}${node_crypto.randomBytes(16).toString('hex')}`).toUpperCase();
+    return {
+        version: SIGN_VERSION,
+        hkey: generateSignature(pathname, time + 1, nonce),
+        _time: time,
+        nonce,
+    };
+}
+function generateSignature(path, time, nonce) {
+    const normalizedPath = `/${path
+        .split('/')
+        .filter(Boolean)
+        .join('/')}/`;
+    const transformedTime = transformWithOffset(String(time), SIGN_CHARSET, -2);
+    const transformedPath = transform(normalizedPath, SIGN_CHARSET);
+    const transformedNonce = transform(nonce, SIGN_CHARSET);
+    const combined = interleave([transformedTime, transformedPath, transformedNonce]).slice(0, 20);
+    const hash = md5(combined);
+    let sign = `${mixColumns(hash.slice(-6).split('').map((char) => char.charCodeAt(0))).reduce((sum, value) => sum + value, 0) % 100}`;
+    sign = sign.length < 2 ? `0${sign}` : sign;
+    return `${transformWithOffset(hash.substring(0, 5), SIGN_CHARSET, -4)}${sign}`;
+}
+function transformWithOffset(str, charset, offset) {
+    return transform(str, charset.slice(0, offset));
+}
+function transform(str, charset) {
+    let output = '';
+    for (let index = 0; index < str.length; index += 1) {
+        output += charset[str.charCodeAt(index) % charset.length];
+    }
+    return output;
+}
+function interleave(strings) {
+    let output = '';
+    const maxLength = Math.max(...strings.map((str) => str.length));
+    for (let index = 0; index < maxLength; index += 1) {
+        for (const str of strings) {
+            if (index < str.length) {
+                output += str[index];
+            }
+        }
+    }
+    return output;
+}
+function mixColumns(column) {
+    const output = [...column];
+    output[0] = multiplyE(column[0]) ^ multiply4(column[1]) ^ multiply3(column[2]) ^ multiply2(column[3]);
+    output[1] = multiply2(column[0]) ^ multiplyE(column[1]) ^ multiply4(column[2]) ^ multiply3(column[3]);
+    output[2] = multiply3(column[0]) ^ multiply2(column[1]) ^ multiplyE(column[2]) ^ multiply4(column[3]);
+    output[3] = multiply4(column[0]) ^ multiply3(column[1]) ^ multiply2(column[2]) ^ multiplyE(column[3]);
+    return output;
+}
+function multiply1(value) {
+    if (value & 0x80) {
+        return ((value << 1) ^ 0x1b) & 0xff;
+    }
+    return value << 1;
+}
+function multiply2(value) {
+    return multiply1(value) ^ value;
+}
+function multiply3(value) {
+    return multiply2(multiply1(value));
+}
+function multiply4(value) {
+    return multiply3(multiply2(multiply1(value)));
+}
+function multiplyE(value) {
+    return multiply4(value) ^ multiply3(value) ^ multiply2(value);
+}
+function md5(input) {
+    return node_crypto.createHash('md5').update(input).digest('hex');
+}
+
+const DEFAULT_PLATFORM_PARAMS = {
+    os_type: 'web',
+    app: 'heybox',
+    x_client_type: 'web',
+    x_os_type: 'Mac',
+    x_app: 'heybox',
+    x_client_version: '999.999.999',
+};
 const HEYBOX_API_BASE_URL = 'https://api.xiaoheihe.cn';
 const HEYBOX_WEB_REFERER = 'https://www.xiaoheihe.cn/';
+function resolveHeyboxId(session) {
+    if (session.heyboxId.trim()) {
+        return session.heyboxId.trim();
+    }
+    return session.cookieHeader
+        .split(';')
+        .map((part) => part.trim())
+        .find((part) => part.startsWith('heybox_id='))
+        ?.slice('heybox_id='.length);
+}
 function createHeyboxAuthHeaders(session, options = {}) {
     return {
         Cookie: session.cookieHeader,
@@ -75099,6 +75241,94 @@ function createHeyboxAuthHeaders(session, options = {}) {
         ...(options.contentType ? { 'Content-Type': options.contentType } : {}),
     };
 }
+function createHeyboxRequestContext(session, options = {}) {
+    const heyboxId = resolveHeyboxId(session);
+    return {
+        baseUrl: HEYBOX_API_BASE_URL,
+        headers: createHeyboxAuthHeaders(session, options),
+        platformParams: {
+            ...DEFAULT_PLATFORM_PARAMS,
+            ...options.platformParams,
+            ...(heyboxId ? { heybox_id: heyboxId } : {}),
+        },
+    };
+}
+function createHeyboxOpenPlatformRequestContext(session, pathWithQuery, options = {}) {
+    return createHeyboxRequestContext(session, {
+        ...options,
+        platformParams: {
+            x_app: 'heybox_website',
+            ...createHeyboxOpenPlatformSignParams(getApiPathname(pathWithQuery)),
+            ...options.platformParams,
+        },
+    });
+}
+function createHeyboxApiUrl(baseUrl, pathWithQuery, params) {
+    const url = new URL(pathWithQuery, baseUrl);
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== '') {
+            url.searchParams.set(key, String(value));
+        }
+    }
+    return url.toString();
+}
+function getApiPathname(pathWithQuery) {
+    return new URL(pathWithQuery, HEYBOX_API_BASE_URL).pathname;
+}
+const ENVELOPE_BODY_PREVIEW_LENGTH = 1000;
+async function readHeyboxApiEnvelope(response, options) {
+    const rawBody = await response.text();
+    let envelope = null;
+    let parseError = null;
+    if (rawBody) {
+        try {
+            envelope = JSON.parse(rawBody);
+        }
+        catch (error) {
+            parseError = error;
+        }
+    }
+    const envelopeOk = envelope?.status === 'ok' && (!options.requireResult || envelope?.result !== undefined);
+    if (response.ok && envelopeOk) {
+        return envelope.result;
+    }
+    throw new Error(formatHeyboxEnvelopeError({ response, envelope, parseError, rawBody, pathWithQuery: options.pathWithQuery }));
+}
+function formatHeyboxEnvelopeError(input) {
+    const parts = [`Heybox API ${input.pathWithQuery} failed`, `HTTP ${input.response.status}`];
+    if (input.envelope) {
+        const msg = typeof input.envelope.msg === 'string' ? input.envelope.msg.trim() : '';
+        parts.push(`msg=${msg || '(empty)'}`);
+        if (typeof input.envelope.status === 'string') {
+            parts.push(`envelope.status=${input.envelope.status}`);
+        }
+        const { status: _s, msg: _m, result: _r, ...extras } = input.envelope;
+        if (Object.keys(extras).length > 0) {
+            parts.push(`extras=${truncate(safeJsonStringify(extras), ENVELOPE_BODY_PREVIEW_LENGTH)}`);
+        }
+        if (input.envelope.result !== undefined) {
+            parts.push(`result=${truncate(safeJsonStringify(input.envelope.result), ENVELOPE_BODY_PREVIEW_LENGTH)}`);
+        }
+        return parts.join(' ');
+    }
+    if (input.parseError) {
+        const parseMsg = input.parseError instanceof Error ? input.parseError.message : String(input.parseError);
+        parts.push(`parseError=${parseMsg}`);
+    }
+    parts.push(input.rawBody ? `body=${truncate(input.rawBody, ENVELOPE_BODY_PREVIEW_LENGTH)}` : 'body=(empty)');
+    return parts.join(' ');
+}
+function truncate(value, max) {
+    return value.length > max ? `${value.slice(0, max)}...(+${value.length - max} chars)` : value;
+}
+function safeJsonStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
 
 async function getCDNUploadInfo(options, runtime = {}) {
     const body = new URLSearchParams();
@@ -75110,7 +75340,7 @@ async function getCDNUploadInfo(options, runtime = {}) {
 async function getCDNUploadToken(options, runtime = {}) {
     const body = new URLSearchParams();
     body.set('bucket', options.bucket);
-    body.set('path', options.path);
+    body.set('keys', JSON.stringify(options.keys));
     body.set('mimetypes', JSON.stringify(options.mimetypes));
     body.set('is_multipart_upload', String(options.isMultipartUpload));
     return postHeyboxApi('/bbs/app/api/qcloud/cos/upload/token/v2', body, options.session, runtime);
@@ -75123,17 +75353,14 @@ async function postCDNUploadCallback(options, runtime = {}) {
 }
 async function postHeyboxApi(pathWithQuery, body, session, runtime) {
     const fetchImpl = runtime.fetchImpl ?? fetch;
-    const baseUrl = runtime.baseUrl ?? HEYBOX_API_BASE_URL;
-    const response = await fetchImpl(`${baseUrl}${pathWithQuery}`, {
+    const context = createHeyboxRequestContext(session, { contentType: 'application/x-www-form-urlencoded' });
+    const response = await fetchImpl(createHeyboxApiUrl(runtime.baseUrl ?? context.baseUrl, pathWithQuery, context.platformParams), {
         method: 'POST',
-        headers: createHeyboxAuthHeaders(session, { contentType: 'application/x-www-form-urlencoded' }),
+        headers: context.headers,
         body: body.toString(),
     });
-    const envelope = (await response.json());
-    if (envelope.status !== 'ok' || envelope.result === undefined) {
-        throw new Error(envelope.msg || `Heybox API ${pathWithQuery} returned status ${envelope.status}`);
-    }
-    return envelope.result;
+    const result = await readHeyboxApiEnvelope(response, { pathWithQuery, requireResult: true });
+    return result;
 }
 
 const DEFAULT_CONCURRENCY = 4;
@@ -75146,8 +75373,6 @@ async function runUpload(options, runtime = {}) {
     const getCDNUploadToken$1 = runtime.getCDNUploadToken ?? getCDNUploadToken;
     const postCDNUploadCallback$1 = runtime.postCDNUploadCallback ?? postCDNUploadCallback;
     const createReadStream = runtime.createReadStream ?? fs$4.createReadStream;
-    const createCosClient = runtime.createCosClient ??
-        (({ session }) => createDefaultCosClient(session, { baseUrl: runtime.baseUrl, fetchImpl, getCDNUploadToken: getCDNUploadToken$1 }));
     const orderedFiles = [...options.files].sort((a, b) => a.relativePath.localeCompare(b.relativePath));
     const fileInfos = orderedFiles.map((file) => ({
         name: file.relativePath.split('/').pop() ?? file.relativePath,
@@ -75161,8 +75386,16 @@ async function runUpload(options, runtime = {}) {
     }));
     log(`[hb-sdk] Uploading ${orderedFiles.length} files (${concurrency} concurrent) ...`);
     const uploadInfo = await getCDNUploadInfo$1({ session: options.session, scope: MINIAPP_UPLOAD_SCOPE, fileInfos, needCache: false }, { baseUrl: runtime.baseUrl, fetchImpl });
-    const cos = createCosClient({ session: options.session });
     const indexedFiles = orderedFiles.map((file, index) => ({ file, key: uploadInfo.keys[index] }));
+    const cos = runtime.createCosClient
+        ? runtime.createCosClient({ session: options.session })
+        : createDefaultCosClient(await getCDNUploadToken$1({
+            session: options.session,
+            bucket: uploadInfo.bucket,
+            keys: indexedFiles.map(({ key }) => key),
+            mimetypes: indexedFiles.map(({ file }) => file.mimeType),
+            isMultipartUpload: 0,
+        }, { baseUrl: runtime.baseUrl, fetchImpl }));
     const queue = indexedFiles.slice();
     let completed = 0;
     const workers = Array.from({ length: Math.min(concurrency, indexedFiles.length) }, async () => {
@@ -75185,7 +75418,7 @@ async function runUpload(options, runtime = {}) {
             }
             catch (error) {
                 completed += 1;
-                log(`[hb-sdk]   [${String(completed).padStart(2)}/${indexedFiles.length}] error ${task.file.relativePath} -> ${readErrorMessage$1(error)}`);
+                log(`[hb-sdk]   [${String(completed).padStart(2)}/${indexedFiles.length}] error ${task.file.relativePath} -> ${readErrorMessage$2(error)}`);
                 throw error;
             }
         }
@@ -75194,28 +75427,15 @@ async function runUpload(options, runtime = {}) {
     await postCDNUploadCallback$1({ session: options.session, keys: uploadInfo.keys, isFinished: true }, { baseUrl: runtime.baseUrl, fetchImpl });
     log(`[hb-sdk] Upload finished: ${indexedFiles.length} files.`);
 }
-function createDefaultCosClient(session, options) {
+function createDefaultCosClient(uploadToken) {
     const cos = new COS({
-        getAuthorization(input, callback) {
-            options
-                .getCDNUploadToken({
-                session,
-                bucket: input.Bucket ?? '',
-                path: input.Key ?? '',
-                mimetypes: [],
-                isMultipartUpload: 0,
-            }, { baseUrl: options.baseUrl, fetchImpl: options.fetchImpl })
-                .then((token) => {
-                callback({
-                    TmpSecretId: token.credentials.tmpSecretId,
-                    TmpSecretKey: token.credentials.tmpSecretKey,
-                    XCosSecurityToken: token.credentials.sessionToken,
-                    StartTime: token.startTime,
-                    ExpiredTime: token.expiredTime,
-                });
-            })
-                .catch((error) => {
-                callback({ error });
+        getAuthorization(_input, callback) {
+            callback({
+                TmpSecretId: uploadToken.credentials.tmpSecretId,
+                TmpSecretKey: uploadToken.credentials.tmpSecretKey,
+                XCosSecurityToken: uploadToken.credentials.sessionToken,
+                StartTime: uploadToken.startTime,
+                ExpiredTime: uploadToken.expiredTime,
             });
         },
     });
@@ -75224,7 +75444,7 @@ function createDefaultCosClient(session, options) {
             return new Promise((resolve, reject) => {
                 cos.putObject(params, (err, result) => {
                     if (err) {
-                        reject(err instanceof Error ? err : new Error(String(err)));
+                        reject(err instanceof Error ? err : new Error(readErrorMessage$2(err)));
                         return;
                     }
                     resolve(result);
@@ -75242,26 +75462,51 @@ function formatSize(bytes) {
     }
     return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
 }
-function readErrorMessage$1(error) {
-    return error instanceof Error ? error.message : String(error);
+function readErrorMessage$2(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    if (isRecord$1(error)) {
+        const primary = readStringField(error, ['message', 'Message', 'errorMessage', 'msg']);
+        const code = readStringField(error, ['code', 'Code', 'errorCode', 'name']);
+        const statusCode = readStringField(error, ['statusCode']);
+        return [code, statusCode, primary].filter(Boolean).join(' ') || JSON.stringify(error);
+    }
+    return String(error);
+}
+function readStringField(record, fields) {
+    for (const field of fields) {
+        const value = record[field];
+        if (typeof value === 'string' && value.trim()) {
+            return value.trim();
+        }
+        if (typeof value === 'number') {
+            return String(value);
+        }
+    }
+    return '';
+}
+function isRecord$1(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
 }
 
 async function publishUserMiniprogram(options, runtime = {}) {
     const fetchImpl = runtime.fetchImpl ?? fetch;
-    const baseUrl = runtime.baseUrl ?? HEYBOX_API_BASE_URL;
+    const context = createHeyboxOpenPlatformRequestContext(options.session, PUBLISH_USER_MINIPROGRAM_API_PATH, {
+        contentType: 'application/x-www-form-urlencoded',
+    });
     const body = new URLSearchParams();
     body.set('mini_program_id', options.miniProgramId);
     body.set('manifest', JSON.stringify(options.manifest));
-    const response = await fetchImpl(`${baseUrl}${PUBLISH_USER_MINIPROGRAM_API_PATH}`, {
+    const response = await fetchImpl(createHeyboxApiUrl(runtime.baseUrl ?? context.baseUrl, PUBLISH_USER_MINIPROGRAM_API_PATH, context.platformParams), {
         method: 'POST',
-        headers: createHeyboxAuthHeaders(options.session, { contentType: 'application/x-www-form-urlencoded' }),
+        headers: context.headers,
         body: body.toString(),
     });
-    const envelope = (await response.json());
-    if (envelope.status !== 'ok') {
-        throw new Error(envelope.msg || 'publish API returned non-ok status');
-    }
-    return envelope.result ?? {};
+    const result = await readHeyboxApiEnvelope(response, {
+        pathWithQuery: PUBLISH_USER_MINIPROGRAM_API_PATH,
+    });
+    return result ?? {};
 }
 
 const SUPPORTED_PACKAGE_MANAGERS = [
@@ -75314,14 +75559,11 @@ async function runDeployCommand(options, runtime = {}) {
     if (!fs$4.existsSync(entryHtmlPath)) {
         throw new Error('未找到 dist/index.html，dist 目录残缺，请重新 build');
     }
-    const { manifest, hadBom } = await readManifest(manifestPath);
+    const { manifest, hadBom } = parseMiniappManifestJson(await fs$3.readFile(manifestPath, 'utf8'), 'dist/manifest.json');
     if (hadBom) {
         output.log('[hb-sdk] dist/manifest.json 包含 BOM，已自动剥离');
     }
-    const version = manifest.version;
-    if (typeof version !== 'string' || !isValidVersion(version)) {
-        throw new Error(`manifest.version 格式错误，必须是 x.y.z：${String(version)}`);
-    }
+    const version = validateMiniappManifestForDeploy(manifest);
     const allFiles = await walkDistFiles(distDir);
     const blocked = allFiles.find((entry) => relativePathContainsNodeModulesSegment(entry.relativePath));
     if (blocked) {
@@ -75332,8 +75574,14 @@ async function runDeployCommand(options, runtime = {}) {
     if (pathError) {
         throw new Error(pathError);
     }
-    await (runtime.runUpload ?? runUpload)({ session, miniProgramId, version, files: uploadFiles }, { console: output, fetchImpl: runtime.fetchImpl });
-    const publishResult = await (runtime.publishUserMiniprogram ?? publishUserMiniprogram)({ session, miniProgramId, manifest }, { fetchImpl: runtime.fetchImpl });
+    let publishResult;
+    try {
+        await (runtime.runUpload ?? runUpload)({ session, miniProgramId, version, files: uploadFiles }, { console: output, fetchImpl: runtime.fetchImpl });
+        publishResult = await (runtime.publishUserMiniprogram ?? publishUserMiniprogram)({ session, miniProgramId, manifest }, { fetchImpl: runtime.fetchImpl });
+    }
+    catch (error) {
+        throw translateHeyboxDeployError(error, { projectRoot, version });
+    }
     output.log(`[hb-sdk] Publish ok: ${miniProgramId} ${version}`);
     if (publishResult.publish_url) {
         output.log(`[hb-sdk] Publish URL: ${publishResult.publish_url}`);
@@ -75381,17 +75629,6 @@ async function runBuildScript(pm, cwd, spawnImpl) {
         });
     });
 }
-async function readManifest(manifestPath) {
-    const raw = await fs$3.readFile(manifestPath, 'utf8');
-    const hadBom = raw.charCodeAt(0) === 0xfeff;
-    const text = hadBom ? raw.slice(1) : raw;
-    try {
-        return { manifest: JSON.parse(text), hadBom };
-    }
-    catch (error) {
-        throw new Error(`dist/manifest.json 不是合法 JSON：${error instanceof Error ? error.message : String(error)}`);
-    }
-}
 async function walkDistFiles(distDir) {
     const results = [];
     await walk(distDir, '');
@@ -75425,6 +75662,39 @@ async function walkDistFiles(distDir) {
 function inferMimeType(fileName) {
     return MIME_BY_EXT[path.extname(fileName).toLowerCase()] || 'application/octet-stream';
 }
+function translateHeyboxDeployError(error, options) {
+    const message = error instanceof Error && error.message ? error.message : String(error);
+    if (isDuplicateUploadErrorMessage(message)) {
+        const packageJsonPath = path.join(options.projectRoot, 'package.json');
+        const nextVersion = suggestNextPatchVersion(options.version);
+        return new Error([
+            `当前小程序版本 ${options.version} 的上传文件已存在，不能覆盖同版本发布产物。`,
+            `请升级 ${packageJsonPath} 中的 version${nextVersion ? `（例如 ${nextVersion}）` : ''}，重新 build 后再 deploy。`,
+            `原始错误：${message}`,
+        ].join('\n'));
+    }
+    if (isAuthExpiredErrorMessage(message)) {
+        return new Error([
+            'Heybox 登录态已失效（服务端 session 已过期或被清除）。',
+            '请运行 `hb-sdk login` 重新登录后再执行 deploy。',
+            `原始错误：${message}`,
+        ].join('\n'));
+    }
+    return error instanceof Error ? error : new Error(message);
+}
+function isDuplicateUploadErrorMessage(message) {
+    return /重名|duplicate|already exists|exists/i.test(message);
+}
+function isAuthExpiredErrorMessage(message) {
+    return /请重新登录|未登录|登录已失效|登录态已失效|unauthorized|未授权/i.test(message);
+}
+function suggestNextPatchVersion(version) {
+    const matched = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+    if (!matched) {
+        return '';
+    }
+    return `${matched[1]}.${matched[2]}.${Number(matched[3]) + 1}`;
+}
 
 class Locked extends Error {
 	constructor(port) {
@@ -75442,11 +75712,6 @@ const lockedPorts = {
 // and a new young set for locked ports are created.
 const releaseOldLockedPortsIntervalMs = 1000 * 15;
 
-// Keep `reserve` deliberately process-wide by port number.
-// It is meant to avoid in-process races, not to model every possible
-// IPv4/IPv6 or host-specific bind combination.
-const reservedPorts = new Set();
-
 // Lazily create timeout on first use
 let timeout;
 
@@ -75498,8 +75763,6 @@ const getAvailablePort = async (options, hosts) => {
 	return options.port;
 };
 
-const isLockedPort = port => lockedPorts.old.has(port) || lockedPorts.young.has(port) || reservedPorts.has(port);
-
 const portCheckSequence = function * (ports) {
 	if (ports) {
 		yield * ports;
@@ -75538,8 +75801,6 @@ async function getPorts(options) {
 		}
 	}
 
-	const {reserve, ...netOptions} = options ?? {};
-
 	if (timeout === undefined) {
 		timeout = setTimeout(() => {
 			timeout = undefined;
@@ -75562,20 +75823,16 @@ async function getPorts(options) {
 				continue;
 			}
 
-			let availablePort = await getAvailablePort({...netOptions, port}, hosts); // eslint-disable-line no-await-in-loop
-			while (isLockedPort(availablePort)) {
+			let availablePort = await getAvailablePort({...options, port}, hosts); // eslint-disable-line no-await-in-loop
+			while (lockedPorts.old.has(availablePort) || lockedPorts.young.has(availablePort)) {
 				if (port !== 0) {
 					throw new Locked(port);
 				}
 
-				availablePort = await getAvailablePort({...netOptions, port}, hosts); // eslint-disable-line no-await-in-loop
+				availablePort = await getAvailablePort({...options, port}, hosts); // eslint-disable-line no-await-in-loop
 			}
 
-			if (reserve) {
-				reservedPorts.add(availablePort);
-			} else {
-				lockedPorts.young.add(availablePort);
-			}
+			lockedPorts.young.add(availablePort);
 
 			return availablePort;
 		} catch (error) {
@@ -75588,6 +75845,337 @@ async function getPorts(options) {
 	throw new Error('No available ports found');
 }
 
+const MINI_PROGRAM_URL_QUERY_PARAM = 'mini_url';
+const MOCK_NETWORK_PROXY_PATH = '/__hb_sdk_mock_network__';
+const MOCK_NETWORK_PROXY_BODY_LIMIT = 1024 * 1024;
+const MOCK_HOST_ROOT_CANDIDATES = [
+    path.resolve(__dirname, 'devtools/mock-host'),
+    path.resolve(__dirname, '../devtools/mock-host'),
+    path.resolve(__dirname, '../../devtools/mock-host'),
+    path.resolve(__dirname, '../../../devtools/mock-host'),
+];
+async function startMiniProgramMockHostServer(options) {
+    const root = options.root ?? resolveMiniProgramMockHostRoot(options.rootCandidates);
+    const server = createMiniProgramMockHostServer(root, {
+        fetchImpl: options.fetchImpl ?? fetch,
+    });
+    const port = await listenHttpServer(server, {
+        host: options.host,
+        port: options.port,
+    }, options.getPort ?? getPorts);
+    return {
+        close: () => new Promise((resolve) => {
+            server.close(() => resolve());
+        }),
+        port,
+        root,
+        server,
+        url: createMiniProgramMockHostUrl({
+            appUrl: options.appUrl,
+            host: options.host,
+            port,
+        }),
+    };
+}
+function resolveMiniProgramMockHostRoot(candidates = MOCK_HOST_ROOT_CANDIDATES) {
+    const found = candidates.find((candidate) => fs$4.existsSync(path.join(candidate, 'index.html')));
+    if (!found) {
+        throw new Error('未找到 hb-sdk mock host 静态产物。请先执行 @heybox/hb-sdk 的 build:mock-host。');
+    }
+    return found;
+}
+function createMiniProgramMockHostUrl(options) {
+    const url = new URL(`http://${toDisplayHost$1(options.host)}:${options.port}/`);
+    url.searchParams.set(MINI_PROGRAM_URL_QUERY_PARAM, options.appUrl);
+    return url.toString();
+}
+function createMiniProgramMockHostServer(root, runtime) {
+    return node_http.createServer(async (request, response) => {
+        const requestUrl = new URL(request.url, 'http://localhost');
+        const pathname = decodeURIComponent(requestUrl.pathname);
+        if (pathname === MOCK_NETWORK_PROXY_PATH) {
+            await handleMockNetworkProxy(request, response, runtime.fetchImpl);
+            return;
+        }
+        const targetPath = resolveStaticPath(root, pathname);
+        if (!targetPath) {
+            response.writeHead(404);
+            response.end('Not found');
+            return;
+        }
+        try {
+            const stat = fs$4.statSync(targetPath);
+            if (stat.isDirectory()) {
+                response.writeHead(404);
+                response.end('Not found');
+                return;
+            }
+            response.writeHead(200, {
+                'content-type': readContentType(targetPath),
+                'cache-control': 'no-store',
+            });
+            fs$4.createReadStream(targetPath).pipe(response);
+        }
+        catch {
+            response.writeHead(404);
+            response.end('Not found');
+        }
+    });
+}
+async function handleMockNetworkProxy(request, response, fetchImpl) {
+    if (request.method === 'OPTIONS') {
+        writeJsonResponse(response, 204, undefined);
+        return;
+    }
+    if (request.method !== 'POST') {
+        writeJsonResponse(response, 405, {
+            code: 'METHOD_NOT_ALLOWED',
+            message: 'mock network proxy only supports POST',
+        });
+        return;
+    }
+    try {
+        const payload = await readJsonRequestBody(request);
+        const result = await requestMockNetwork(payload, fetchImpl);
+        writeJsonResponse(response, 200, result);
+    }
+    catch (error) {
+        writeJsonResponse(response, readMockNetworkErrorStatus(error), toMockNetworkErrorPayload(error));
+    }
+}
+async function requestMockNetwork(payload, fetchImpl) {
+    if (!isRecord(payload) || typeof payload.url !== 'string' || !payload.url.trim()) {
+        throw createMockNetworkError(400, 'INVALID_NETWORK_REQUEST', 'network.request url 必须是非空字符串');
+    }
+    const url = createMockNetworkUrl(payload.url, payload.params);
+    const method = typeof payload.method === 'string' && payload.method.trim() ? payload.method.trim().toUpperCase() : 'GET';
+    const headers = normalizeMockNetworkHeaders(payload.headers);
+    const controller = new AbortController();
+    const timeout = Number(payload.timeout) > 0 ? Number(payload.timeout) : 10000;
+    const timer = setTimeout(() => controller.abort(), timeout);
+    try {
+        const response = await fetchImpl(url.toString(), {
+            method,
+            headers,
+            body: createMockNetworkBody(method, payload.data, headers),
+            redirect: 'follow',
+            signal: controller.signal,
+        });
+        const contentType = response.headers.get('content-type') || '';
+        const text = await response.text();
+        clearTimeout(timer);
+        return {
+            data: contentType.includes('application/json') ? safeJsonParse(text) : text,
+            status: response.status,
+            statusText: response.statusText,
+            headers: Object.fromEntries(response.headers.entries()),
+        };
+    }
+    catch (error) {
+        clearTimeout(timer);
+        throw createMockNetworkError(502, 'MOCK_NETWORK_REQUEST_FAILED', error instanceof Error && error.name === 'AbortError'
+            ? `network.request timeout after ${timeout}ms`
+            : readErrorMessage$1(error));
+    }
+}
+function createMockNetworkUrl(input, params) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw createMockNetworkError(400, 'INVALID_NETWORK_REQUEST', 'network.request url 必须是合法 URL');
+    }
+    if (!['http:', 'https:'].includes(url.protocol)) {
+        throw createMockNetworkError(400, 'INVALID_NETWORK_REQUEST', 'network.request 仅支持 HTTP(S) URL');
+    }
+    if (isRecord(params)) {
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined && value !== null) {
+                url.searchParams.set(key, String(value));
+            }
+        });
+    }
+    return url;
+}
+function normalizeMockNetworkHeaders(headers) {
+    const normalized = new Headers();
+    if (!isRecord(headers)) {
+        return normalized;
+    }
+    Object.entries(headers).forEach(([key, value]) => {
+        if (typeof value === 'string' && !isBlockedMockNetworkHeader(key)) {
+            normalized.set(key, value);
+        }
+    });
+    return normalized;
+}
+function isBlockedMockNetworkHeader(key) {
+    return [
+        'connection',
+        'content-length',
+        'host',
+        'keep-alive',
+        'proxy-authenticate',
+        'proxy-authorization',
+        'te',
+        'trailer',
+        'transfer-encoding',
+        'upgrade',
+    ].includes(key.toLowerCase());
+}
+function createMockNetworkBody(method, data, headers) {
+    if (data === undefined || method === 'GET' || method === 'HEAD') {
+        return undefined;
+    }
+    if (typeof data === 'string') {
+        return data;
+    }
+    if (!headers.has('content-type')) {
+        headers.set('content-type', 'application/json');
+    }
+    return JSON.stringify(data);
+}
+function readJsonRequestBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        request.on('data', (chunk) => {
+            const buffer = Buffer.from(chunk);
+            size += buffer.byteLength;
+            if (size > MOCK_NETWORK_PROXY_BODY_LIMIT) {
+                reject(createMockNetworkError(413, 'REQUEST_ENTITY_TOO_LARGE', 'mock network proxy request body too large'));
+                request.destroy();
+                return;
+            }
+            chunks.push(buffer);
+        });
+        request.on('error', reject);
+        request.on('aborted', () => {
+            reject('mock network proxy request aborted');
+        });
+        request.on('end', () => {
+            const rawBody = Buffer.concat(chunks).toString('utf8');
+            if (!rawBody.trim()) {
+                resolve({});
+                return;
+            }
+            try {
+                resolve(JSON.parse(rawBody));
+            }
+            catch {
+                reject(createMockNetworkError(400, 'INVALID_JSON', 'mock network proxy received invalid JSON'));
+            }
+        });
+    });
+}
+function writeJsonResponse(response, status, body) {
+    response.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'cache-control': 'no-store',
+    });
+    response.end(body === undefined ? '' : JSON.stringify(body));
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function isRecord(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+function createMockNetworkError(status, code, message) {
+    const error = new Error(message);
+    error.code = code;
+    error.status = status;
+    return error;
+}
+function readMockNetworkErrorStatus(error) {
+    return isObjectLike(error) && typeof error.status === 'number' ? error.status : 500;
+}
+function toMockNetworkErrorPayload(error) {
+    if (isObjectLike(error) && typeof error.code === 'string' && typeof error.message === 'string') {
+        return {
+            code: error.code,
+            message: error.message,
+        };
+    }
+    return {
+        code: 'MOCK_NETWORK_ERROR',
+        message: readErrorMessage$1(error),
+    };
+}
+function isObjectLike(value) {
+    return (typeof value === 'object' || typeof value === 'function') && value !== null;
+}
+function resolveStaticPath(root, pathname) {
+    const safePathname = pathname === '/' ? '/index.html' : pathname;
+    const normalizedRoot = path.normalize(root);
+    const targetPath = path.normalize(path.join(normalizedRoot, safePathname));
+    if (targetPath !== normalizedRoot && !targetPath.startsWith(`${normalizedRoot}${path.sep}`)) {
+        return undefined;
+    }
+    return targetPath;
+}
+function readContentType(filePath) {
+    if (filePath.endsWith('.html')) {
+        return 'text/html; charset=utf-8';
+    }
+    if (filePath.endsWith('.js')) {
+        return 'text/javascript; charset=utf-8';
+    }
+    if (filePath.endsWith('.css')) {
+        return 'text/css; charset=utf-8';
+    }
+    if (filePath.endsWith('.json')) {
+        return 'application/json; charset=utf-8';
+    }
+    if (filePath.endsWith('.svg')) {
+        return 'image/svg+xml';
+    }
+    return 'application/octet-stream';
+}
+async function listenHttpServer(server, options, getPortImpl) {
+    const maxAttempts = 20;
+    const port = await getPortImpl({
+        host: options.host,
+        port: createPortCandidates(options.port, maxAttempts),
+    });
+    if (port < options.port || port >= options.port + maxAttempts) {
+        throw new Error(`无法找到可用 mock host 端口，起始端口: ${options.port}`);
+    }
+    await new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off('listening', onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off('error', onError);
+            resolve();
+        };
+        server.once('error', onError);
+        server.once('listening', onListening);
+        server.listen(port, options.host);
+    });
+    const address = server.address();
+    return address.port;
+}
+function createPortCandidates(startPort, count) {
+    return Array.from({ length: count }, (_, index) => startPort + index);
+}
+function toDisplayHost$1(host) {
+    if (!host || host === '0.0.0.0' || host === '::') {
+        return 'localhost';
+    }
+    return host;
+}
+function readErrorMessage$1(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+
 let isDockerCached;
 
 function hasDockerEnv() {
@@ -75651,20 +76239,11 @@ const isWsl = () => {
 	}
 
 	try {
-		if (fs$4.readFileSync('/proc/version', 'utf8').toLowerCase().includes('microsoft')) {
-			return !isInsideContainer();
-		}
-	} catch {}
-
-	// Fallback for custom kernels: check WSL-specific paths.
-	if (
-		fs$4.existsSync('/proc/sys/fs/binfmt_misc/WSLInterop')
-		|| fs$4.existsSync('/run/WSL')
-	) {
-		return !isInsideContainer();
+		return fs$4.readFileSync('/proc/version', 'utf8').toLowerCase().includes('microsoft')
+			? !isInsideContainer() : false;
+	} catch {
+		return false;
 	}
-
-	return false;
 };
 
 var isWsl$1 = process$1.env.__IS_WSL_TEST__ ? isWsl : isWsl();
@@ -76221,9 +76800,6 @@ function readErrorMessage(error) {
 
 const DEFAULT_APP_PORT = 5173;
 const DEFAULT_MOCK_PORT = 5174;
-const MINI_PROGRAM_URL_QUERY_PARAM = 'mini_url';
-const MOCK_NETWORK_PROXY_PATH = '/__hb_sdk_mock_network__';
-const MOCK_NETWORK_PROXY_BODY_LIMIT = 1024 * 1024;
 // Shared with Heybox H5 Vite plugins so hb-sdk can own the launch output.
 const MANAGED_DEV_OUTPUT_ENV = 'HEYBOX_DEV_SERVER_MANAGED_OUTPUT';
 const VITE_LOG_LEVEL = 'warn';
@@ -76237,26 +76813,29 @@ async function runDevCommand(options, runtime = {}) {
     await appServer.listen(options.port ?? DEFAULT_APP_PORT);
     const appUrl = await resolveViteAppUrl(appServer, options, fetchImpl);
     const closers = [() => appServer.close()];
-    const mockHostRoot = runtime.mockHostRoot ?? resolveMockHostRoot(runtime.mockHostRootCandidates);
-    const mockServer = createMockHostServer(mockHostRoot, { fetchImpl });
-    const mockPort = await listenHttpServer(mockServer, {
-        host: options.host,
-        port: options.mockPort ?? DEFAULT_MOCK_PORT,
-    }, runtime.getPort ?? getPorts);
-    const mockUrl = createMockHostUrl({
-        appUrl,
-        host: options.host,
-        port: mockPort,
-    });
-    closers.push(() => new Promise((resolve) => {
-        mockServer.close(() => resolve());
-    }));
+    let mockHost;
+    try {
+        mockHost = await startMiniProgramMockHostServer({
+            appUrl,
+            fetchImpl,
+            getPort: runtime.getPort ?? getPorts,
+            host: options.host,
+            port: options.mockPort ?? DEFAULT_MOCK_PORT,
+            root: runtime.mockHostRoot,
+            rootCandidates: runtime.mockHostRootCandidates,
+        });
+    }
+    catch (error) {
+        await closeAll(closers);
+        throw error;
+    }
+    closers.push(() => mockHost.close());
     output.log(`\n[hb-sdk] Mock runtime host is ready`);
-    output.log(`[hb-sdk] Mock runtime host: ${mockUrl}`);
+    output.log(`[hb-sdk] Mock runtime host: ${mockHost.url}`);
     output.log(`[hb-sdk] Mini program URL: ${appUrl}`);
     output.log(`[hb-sdk] Mac APP: use the button in Mock runtime host`);
     if (options.open !== false) {
-        void openUrl(mockUrl);
+        void openUrl(mockHost.url);
     }
     installShutdownHandlers(closers, runtime.process ?? process);
 }
@@ -76276,6 +76855,10 @@ function findProjectRoot(startDir) {
 async function loadProjectVite(projectRoot) {
     const projectRequire = node_module.createRequire(path.join(projectRoot, 'package.json'));
     try {
+        const packageJson = JSON.parse(await fs$3.readFile(path.join(projectRoot, 'package.json'), 'utf8'));
+        if (!hasPackageDependency(packageJson, 'vite')) {
+            throw new Error('package.json 未声明 vite');
+        }
         const viteEntry = projectRequire.resolve('vite');
         return (await import(node_url.pathToFileURL(viteEntry).href));
     }
@@ -76283,6 +76866,12 @@ async function loadProjectVite(projectRoot) {
         throw new Error(`当前项目未安装 vite。请先安装项目依赖，或将 vite 放到项目 devDependencies。原始错误: ${readErrorMessage(error)}`);
     }
 }
+function hasPackageDependency(packageJson, name) {
+    return Boolean(packageJson.dependencies?.[name] ||
+        packageJson.devDependencies?.[name] ||
+        packageJson.optionalDependencies?.[name] ||
+        packageJson.peerDependencies?.[name]);
+}
 function createViteServerOptions(projectRoot, options) {
     const configFile = resolveProjectViteConfig(projectRoot);
     const server = {
@@ -76379,299 +76968,6 @@ async function canReachDocumentUrl(url, fetchImpl) {
 function ensureTrailingSlash(value) {
     return value.endsWith('/') ? value : `${value}/`;
 }
-const MOCK_HOST_ROOT_CANDIDATES = [
-    path.resolve(__dirname, 'devtools/mock-host'),
-    path.resolve(__dirname, '../devtools/mock-host'),
-    path.resolve(__dirname, '../../devtools/mock-host'),
-    path.resolve(__dirname, '../../../devtools/mock-host'),
-];
-function resolveMockHostRoot(candidates = MOCK_HOST_ROOT_CANDIDATES) {
-    const found = candidates.find((candidate) => fs$4.existsSync(path.join(candidate, 'index.html')));
-    if (!found) {
-        throw new Error(`未找到 hb-sdk mock host 静态产物。请先执行 @heybox/hb-sdk 的 build:mock-host。`);
-    }
-    return found;
-}
-function createMockHostServer(root, runtime) {
-    return node_http.createServer(async (request, response) => {
-        const requestUrl = new URL(request.url, 'http://localhost');
-        const pathname = decodeURIComponent(requestUrl.pathname);
-        if (pathname === MOCK_NETWORK_PROXY_PATH) {
-            await handleMockNetworkProxy(request, response, runtime.fetchImpl);
-            return;
-        }
-        const targetPath = resolveStaticPath(root, pathname);
-        if (!targetPath) {
-            response.writeHead(404);
-            response.end('Not found');
-            return;
-        }
-        try {
-            const stat = fs$4.statSync(targetPath);
-            if (stat.isDirectory()) {
-                response.writeHead(404);
-                response.end('Not found');
-                return;
-            }
-            response.writeHead(200, {
-                'content-type': readContentType(targetPath),
-                'cache-control': 'no-store',
-            });
-            fs$4.createReadStream(targetPath).pipe(response);
-        }
-        catch {
-            response.writeHead(404);
-            response.end('Not found');
-        }
-    });
-}
-async function handleMockNetworkProxy(request, response, fetchImpl) {
-    if (request.method === 'OPTIONS') {
-        writeJsonResponse(response, 204, undefined);
-        return;
-    }
-    if (request.method !== 'POST') {
-        writeJsonResponse(response, 405, {
-            code: 'METHOD_NOT_ALLOWED',
-            message: 'mock network proxy only supports POST',
-        });
-        return;
-    }
-    try {
-        const payload = await readJsonRequestBody(request);
-        const result = await requestMockNetwork(payload, fetchImpl);
-        writeJsonResponse(response, 200, result);
-    }
-    catch (error) {
-        writeJsonResponse(response, readMockNetworkErrorStatus(error), toMockNetworkErrorPayload(error));
-    }
-}
-async function requestMockNetwork(payload, fetchImpl) {
-    if (!isRecord(payload) || typeof payload.url !== 'string' || !payload.url.trim()) {
-        throw createMockNetworkError(400, 'INVALID_NETWORK_REQUEST', 'network.request url 必须是非空字符串');
-    }
-    const url = createMockNetworkUrl(payload.url, payload.params);
-    const method = typeof payload.method === 'string' && payload.method.trim() ? payload.method.trim().toUpperCase() : 'GET';
-    const headers = normalizeMockNetworkHeaders(payload.headers);
-    const controller = new AbortController();
-    const timeout = Number(payload.timeout) > 0 ? Number(payload.timeout) : 10000;
-    const timer = setTimeout(() => controller.abort(), timeout);
-    try {
-        const response = await fetchImpl(url.toString(), {
-            method,
-            headers,
-            body: createMockNetworkBody(method, payload.data, headers),
-            redirect: 'follow',
-            signal: controller.signal,
-        });
-        const contentType = response.headers.get('content-type') || '';
-        const text = await response.text();
-        clearTimeout(timer);
-        return {
-            data: contentType.includes('application/json') ? safeJsonParse(text) : text,
-            status: response.status,
-            statusText: response.statusText,
-            headers: Object.fromEntries(response.headers.entries()),
-        };
-    }
-    catch (error) {
-        clearTimeout(timer);
-        throw createMockNetworkError(502, 'MOCK_NETWORK_REQUEST_FAILED', error instanceof Error && error.name === 'AbortError' ? `network.request timeout after ${timeout}ms` : readErrorMessage(error));
-    }
-}
-function createMockNetworkUrl(input, params) {
-    let url;
-    try {
-        url = new URL(input);
-    }
-    catch {
-        throw createMockNetworkError(400, 'INVALID_NETWORK_REQUEST', 'network.request url 必须是合法 URL');
-    }
-    if (!['http:', 'https:'].includes(url.protocol)) {
-        throw createMockNetworkError(400, 'INVALID_NETWORK_REQUEST', 'network.request 仅支持 HTTP(S) URL');
-    }
-    if (isRecord(params)) {
-        Object.entries(params).forEach(([key, value]) => {
-            if (value !== undefined && value !== null) {
-                url.searchParams.set(key, String(value));
-            }
-        });
-    }
-    return url;
-}
-function normalizeMockNetworkHeaders(headers) {
-    const normalized = new Headers();
-    if (!isRecord(headers)) {
-        return normalized;
-    }
-    Object.entries(headers).forEach(([key, value]) => {
-        if (typeof value === 'string' && !isBlockedMockNetworkHeader(key)) {
-            normalized.set(key, value);
-        }
-    });
-    return normalized;
-}
-function isBlockedMockNetworkHeader(key) {
-    return [
-        'connection',
-        'content-length',
-        'host',
-        'keep-alive',
-        'proxy-authenticate',
-        'proxy-authorization',
-        'te',
-        'trailer',
-        'transfer-encoding',
-        'upgrade',
-    ].includes(key.toLowerCase());
-}
-function createMockNetworkBody(method, data, headers) {
-    if (data === undefined || method === 'GET' || method === 'HEAD') {
-        return undefined;
-    }
-    if (typeof data === 'string') {
-        return data;
-    }
-    if (!headers.has('content-type')) {
-        headers.set('content-type', 'application/json');
-    }
-    return JSON.stringify(data);
-}
-function readJsonRequestBody(request) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        let size = 0;
-        request.on('data', (chunk) => {
-            const buffer = Buffer.from(chunk);
-            size += buffer.byteLength;
-            if (size > MOCK_NETWORK_PROXY_BODY_LIMIT) {
-                reject(createMockNetworkError(413, 'REQUEST_ENTITY_TOO_LARGE', 'mock network proxy request body too large'));
-                request.destroy();
-                return;
-            }
-            chunks.push(buffer);
-        });
-        request.on('error', reject);
-        request.on('aborted', () => {
-            reject('mock network proxy request aborted');
-        });
-        request.on('end', () => {
-            const rawBody = Buffer.concat(chunks).toString('utf8');
-            if (!rawBody.trim()) {
-                resolve({});
-                return;
-            }
-            try {
-                resolve(JSON.parse(rawBody));
-            }
-            catch {
-                reject(createMockNetworkError(400, 'INVALID_JSON', 'mock network proxy received invalid JSON'));
-            }
-        });
-    });
-}
-function writeJsonResponse(response, status, body) {
-    response.writeHead(status, {
-        'content-type': 'application/json; charset=utf-8',
-        'cache-control': 'no-store',
-    });
-    response.end(body === undefined ? '' : JSON.stringify(body));
-}
-function safeJsonParse(text) {
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return text;
-    }
-}
-function isRecord(value) {
-    return Object.prototype.toString.call(value) === '[object Object]';
-}
-function createMockNetworkError(status, code, message) {
-    const error = new Error(message);
-    error.code = code;
-    error.status = status;
-    return error;
-}
-function readMockNetworkErrorStatus(error) {
-    return isObjectLike(error) && typeof error.status === 'number' ? error.status : 500;
-}
-function toMockNetworkErrorPayload(error) {
-    if (isObjectLike(error) && typeof error.code === 'string' && typeof error.message === 'string') {
-        return {
-            code: error.code,
-            message: error.message,
-        };
-    }
-    return {
-        code: 'MOCK_NETWORK_ERROR',
-        message: readErrorMessage(error),
-    };
-}
-function isObjectLike(value) {
-    return (typeof value === 'object' || typeof value === 'function') && value !== null;
-}
-function resolveStaticPath(root, pathname) {
-    const safePathname = pathname === '/' ? '/index.html' : pathname;
-    const normalizedRoot = path.normalize(root);
-    const targetPath = path.normalize(path.join(normalizedRoot, safePathname));
-    if (targetPath !== normalizedRoot && !targetPath.startsWith(`${normalizedRoot}${path.sep}`)) {
-        return undefined;
-    }
-    return targetPath;
-}
-function readContentType(filePath) {
-    if (filePath.endsWith('.html')) {
-        return 'text/html; charset=utf-8';
-    }
-    if (filePath.endsWith('.js')) {
-        return 'text/javascript; charset=utf-8';
-    }
-    if (filePath.endsWith('.css')) {
-        return 'text/css; charset=utf-8';
-    }
-    if (filePath.endsWith('.json')) {
-        return 'application/json; charset=utf-8';
-    }
-    if (filePath.endsWith('.svg')) {
-        return 'image/svg+xml';
-    }
-    return 'application/octet-stream';
-}
-async function listenHttpServer(server, options, getPortImpl) {
-    const maxAttempts = 20;
-    const port = await getPortImpl({
-        host: options.host,
-        port: createPortCandidates(options.port, maxAttempts),
-    });
-    if (port < options.port || port >= options.port + maxAttempts) {
-        throw new Error(`无法找到可用 mock host 端口，起始端口: ${options.port}`);
-    }
-    await new Promise((resolve, reject) => {
-        const onError = (error) => {
-            server.off('listening', onListening);
-            reject(error);
-        };
-        const onListening = () => {
-            server.off('error', onError);
-            resolve();
-        };
-        server.once('error', onError);
-        server.once('listening', onListening);
-        server.listen(port, options.host);
-    });
-    const address = server.address();
-    return address.port;
-}
-function createPortCandidates(startPort, count) {
-    return Array.from({ length: count }, (_, index) => startPort + index);
-}
-function createMockHostUrl(options) {
-    const url = new URL(`http://${toDisplayHost(options.host)}:${options.port}/`);
-    url.searchParams.set(MINI_PROGRAM_URL_QUERY_PARAM, options.appUrl);
-    return url.toString();
-}
 async function withManagedDevOutputEnv(action, env = process.env) {
     const previous = env[MANAGED_DEV_OUTPUT_ENV];
     env[MANAGED_DEV_OUTPUT_ENV] = '1';
@@ -76695,7 +76991,7 @@ function toDisplayHost(host) {
 }
 function installShutdownHandlers(closers, processLike) {
     const shutdown = async () => {
-        await Promise.allSettled(closers.map((close) => close()));
+        await closeAll(closers);
         processLike.exit(0);
     };
     processLike.once('SIGINT', () => {
@@ -76705,13 +77001,18 @@ function installShutdownHandlers(closers, processLike) {
         void shutdown();
     });
 }
+async function closeAll(closers) {
+    await Promise.allSettled(closers.map((close) => close()));
+}
+
+const HB_SDK_PACKAGE_NAME = '@heybox/hb-sdk';
+const HB_SDK_SKILL_NAME = 'hb-sdk';
+const HB_SDK_AGENT_SKILLS_BASE_URL = 'https://open.xiaoheihe.cn/agent-skills';
+const HB_SDK_SKILL_SOURCE = `${HB_SDK_AGENT_SKILLS_BASE_URL}/${HB_SDK_SKILL_NAME}`;
+const HB_SDK_SKILL_INDEX_URL = `${HB_SDK_AGENT_SKILLS_BASE_URL}/.well-known/agent-skills/index.json`;
+const HB_SDK_SKILL_INSTALL_COMMAND = `npx skills add ${HB_SDK_SKILL_SOURCE}`;
 
-const PACKAGE_NAME$1 = '@heybox/hb-sdk';
-const SKILL_NAME = 'hb-sdk';
-const DEFAULT_SKILL_SOURCE = 'https://open.xiaoheihe.cn/agent-skills/hb-sdk';
-const DEFAULT_REMOTE_INDEX_URL = 'https://open.xiaoheihe.cn/agent-skills/.well-known/agent-skills/index.json';
 const DEFAULT_TIMEOUT_MS$1 = 3000;
-const SKILL_INSTALL_COMMAND = `npx skills add ${DEFAULT_SKILL_SOURCE}`;
 const PACKAGE_JSON_CANDIDATES$2 = [
     path.resolve(__dirname, '..', 'package.json'),
     path.resolve(__dirname, '..', '..', 'package.json'),
@@ -76756,7 +77057,7 @@ async function getDoctorResult(runtime = {}) {
         };
     }
     if (!localSkill.manifest ||
-        localSkill.manifest.name !== SKILL_NAME ||
+        localSkill.manifest.name !== HB_SDK_SKILL_NAME ||
         localSkill.manifest.skillVersion !== remoteSkill.version ||
         localSkill.manifest.sdk?.version !== remoteSkill.sdk?.version) {
         return {
@@ -76788,26 +77089,26 @@ function printDoctorNextStep(result, output) {
         return;
     }
     if (result.status === 'SDK_MISMATCH') {
-        output.log(`[hb-sdk] Current SDK does not match the latest skill metadata. Upgrade with: npm i -D ${PACKAGE_NAME$1}@latest`);
+        output.log(`[hb-sdk] Current SDK does not match the latest skill metadata. Upgrade with: npm i -D ${HB_SDK_PACKAGE_NAME}@latest`);
         output.log(`[hb-sdk] Then install or refresh the skill manually: ${formatSkillInstallCommand(result)}`);
         return;
     }
     if (result.status === 'REMOTE_UNAVAILABLE') {
         output.log('[hb-sdk] Remote skill metadata is unavailable. Try again later.');
-        output.log(`[hb-sdk] Manual install command: ${SKILL_INSTALL_COMMAND}`);
+        output.log(`[hb-sdk] Manual install command: ${HB_SDK_SKILL_INSTALL_COMMAND}`);
         return;
     }
     output.log(`[hb-sdk] Install or refresh the skill manually: ${formatSkillInstallCommand(result)}`);
 }
 function formatSkillInstallCommand(result) {
-    return `npx skills add ${result.remoteSkill?.source || DEFAULT_SKILL_SOURCE}`;
+    return `npx skills add ${result.remoteSkill?.source || HB_SDK_SKILL_SOURCE}`;
 }
 async function fetchRemoteSkill(runtime) {
     const fetchImpl = runtime.fetchImpl ?? fetch;
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), runtime.timeoutMs ?? DEFAULT_TIMEOUT_MS$1);
     try {
-        const response = await fetchImpl(runtime.remoteIndexUrl ?? DEFAULT_REMOTE_INDEX_URL, {
+        const response = await fetchImpl(runtime.remoteIndexUrl ?? HB_SDK_SKILL_INDEX_URL, {
             headers: {
                 accept: 'application/json',
             },
@@ -76817,8 +77118,8 @@ async function fetchRemoteSkill(runtime) {
             throw new Error(`remote skill index returned ${response.status}`);
         }
         const index = (await response.json());
-        const skill = index.skills?.find(item => item.name === SKILL_NAME);
-        if (!skill?.version || skill.sdk?.package !== PACKAGE_NAME$1 || !skill.sdk.version) {
+        const skill = index.skills?.find(item => item.name === HB_SDK_SKILL_NAME);
+        if (!skill?.version || skill.sdk?.package !== HB_SDK_PACKAGE_NAME || !skill.sdk.version) {
             throw new Error('remote hb-sdk skill metadata is incomplete');
         }
         return skill;
@@ -76862,7 +77163,7 @@ function resolveLocalSkillJsonPath(runtime) {
         return runtime.localSkillJsonPath;
     }
     const codexHome = runtime.codexHome ?? runtime.env?.CODEX_HOME ?? process.env.CODEX_HOME ?? path.join(os.homedir(), '.codex');
-    return path.join(codexHome, 'skills', SKILL_NAME, 'skill.json');
+    return path.join(codexHome, 'skills', HB_SDK_SKILL_NAME, 'skill.json');
 }
 async function pathExists$2(filePath) {
     try {
@@ -77028,12 +77329,11 @@ async function clearLoginStatus(options = {}) {
     output.log(`cache: ${getAuthCacheFilePath(options)}`);
 }
 
-const PACKAGE_NAME = '@heybox/hb-sdk';
 const UPDATE_CHECK_CACHE_VERSION = 1;
 const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
 const DEFAULT_TIMEOUT_MS = 1500;
 const UPDATE_CHECK_CACHE_FILE = 'update-check.json';
-const NPM_REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME)}`;
+const NPM_REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(HB_SDK_PACKAGE_NAME)}`;
 const paths = envPaths('hb-sdk', { suffix: '' });
 const PACKAGE_JSON_CANDIDATES$1 = [
     path.resolve(__dirname, '..', 'package.json'),
@@ -77082,7 +77382,7 @@ async function getUpdateReminder(options = {}) {
     return createUpdateReminder(currentVersion, latestVersion);
 }
 function formatUpdateReminder(reminder) {
-    return `[hb-sdk] New version available: ${reminder.currentVersion} -> ${reminder.latestVersion}. Upgrade with: npm i -D ${PACKAGE_NAME}@latest`;
+    return `[hb-sdk] New version available: ${reminder.currentVersion} -> ${reminder.latestVersion}. Upgrade with: npm i -D ${HB_SDK_PACKAGE_NAME}@latest`;
 }
 function isVersionGreater(version, baseline) {
     const compared = compareSemver(version, baseline);
@@ -77259,7 +77559,7 @@ async function pathExists$1(filePath) {
 }
 
 const CLI_VERSION_PLACEHOLDER = ['__HB', 'SDK', 'CLI', 'VERSION__'].join('_');
-const BUILT_CLI_VERSION = '0.2.0-alpha.2';
+const BUILT_CLI_VERSION = '0.3.1';
 const PACKAGE_JSON_CANDIDATES = [
     path.resolve(__dirname, '..', '..', 'package.json'),
     path.resolve(__dirname, '..', 'package.json'),