@heybox/hb-sdk 0.8.2-alpha.1 → 0.8.2-alpha.5

package/dist/vite.esm.js

@@ -1,397 +1,76 @@
-import { readFileSync, existsSync, realpathSync, lstatSync, readdirSync, readlinkSync, mkdirSync, writeFileSync, renameSync, rmSync, unwatchFile, createReadStream, watchFile, mkdtempSync, chmodSync } from 'node:fs';
-import { randomUUID, randomBytes, createHash, timingSafeEqual } from 'node:crypto';
-import { tmpdir, platform, arch } from 'node:os';
+import { createHash, randomUUID, randomBytes, timingSafeEqual } from 'node:crypto';
+import { constants as constants$1, readFileSync, existsSync, realpathSync, lstatSync, readdirSync, readlinkSync, mkdirSync, writeFileSync, renameSync, rmSync, unwatchFile, createReadStream, watchFile, mkdtempSync, chmodSync } from 'node:fs';
+import { readFile, mkdir, realpath, writeFile, stat, open } from 'node:fs/promises';
 import path from 'node:path';
+import sharp from 'sharp';
+import { tmpdir, platform, arch } from 'node:os';
 import { inflateRawSync } from 'node:zlib';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
-/** 构建时替换为当前发布包的实际版本。 */
-const HB_SDK_VERSION = typeof undefined === 'string'
-    ? undefined
-    : '0.8.2-alpha.1';
+var re = {exports: {}};
 
-/**
- * iframe 与调试台页面的开发期 console 捕获转发。
- *
- * 双条件门控（iframe 转发）：
- * 1. 构建期：`hb-sdk dev`（vite serve）注入 `false`；`hb-sdk build` /
- *    `vite build`（生产）永不注入或替换为 `false`，本模块被死代码消除。
- * 2. 运行期：仅在 `window.name` 为 `__hb_sdk_mini_dev__` 的调试 iframe 中激活，
- *    用户设备上的正式运行环境没有该标记。
- *
- * 无侵入 patch `console.log/debug/info/warn/error`：原样放行（DevTools 不受影响）+
- * 通过 `window.parent.postMessage` 转发给调试台（CSP 的 connect-src 不约束 postMessage，
- * 网络上报由调试台页面代理）。发送全程静默：失败不得回打 console，避免自触发死循环。
- *
- * 激活时机：由 SDK 默认单例初始化时调用（业务 `import '@heybox/hb-sdk'` 即生效）；
- * iframe 标记由调试台 `iframe.name` 与 vite dev 注入的无依赖 bootstrap 共同设置。
- * 调试台页面自身（runtime 跑在这里，`[hb-sdk-runtime]` 日志不经过 iframe）另用
- * `installMiniDevConsoleSelfCapture` 接入「日志」页签（source: 'host'）。
- */
-const MINI_DEV_CONSOLE_EVENT_TYPE = 'hb-sdk:mini-dev-console';
-/** 调试台页面与 iframe bootstrap 共用的已安装标记（window/console 上的属性名）。 */
-const MINI_DEV_CONSOLE_INSTALL_FLAG = '__hb_sdk_mini_dev_console_installed__';
+var constants;
+var hasRequiredConstants;
 
-/**
- * network.request 诊断日志的纯脱敏工具。
- *
- * @remarks
- * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
- * modules observability、devtools Browser Dev Host / proxy 共用，并满足 boundary
- *（devtools 不得直接 import runtime capability modules）。
- */
-/** 敏感字段名：header / query / body key 共用。 */
-const SENSITIVE_KEY_PATTERN = /(authorization|cookie|password|passwd|secret|token|pkey|private[_-]?key|access[_-]?key|client[_-]?secret|api[_-]?key|apikey|session|jwt|refresh[_-]?token|csrf)/i;
-/**
- * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
- */
-function sanitizeNetworkRequestUrl(url) {
-    if (!url) {
-        return url;
-    }
-    try {
-        const parsed = new URL(url);
-        parsed.username = '';
-        parsed.password = '';
-        redactUrlSearchParams(parsed.searchParams);
-        if (parsed.hash && parsed.hash.length > 1) {
-            const hashBody = parsed.hash.slice(1);
-            if (hashBody.includes('=')) {
-                const hashParams = new URLSearchParams(hashBody);
-                if (redactUrlSearchParams(hashParams)) {
-                    parsed.hash = hashParams.toString();
-                }
-            }
-        }
-        return parsed.toString();
-    }
-    catch {
-        return redactSensitivePairsInRawText(url);
-    }
-}
-/**
- * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
- */
-function sanitizeDiagnosticMessage(message) {
-    if (!message) {
-        return message;
-    }
-    return message.replace(/https?:\/\/[^\s]+/gi, matched => sanitizeNetworkRequestUrl(matched.replace(/[),.;]+$/g, '')));
-}
-function isSensitiveNetworkKey(key) {
-    return SENSITIVE_KEY_PATTERN.test(key.trim());
-}
-function redactUrlSearchParams(params) {
-    let changed = false;
-    for (const key of [...params.keys()]) {
-        if (isSensitiveNetworkKey(key)) {
-            params.set(key, '[redacted]');
-            changed = true;
-        }
-    }
-    return changed;
-}
-function redactSensitivePairsInRawText(text) {
-    return text.replace(/([?&#]|^|[?&])([^=&#\s]+)=([^&#\s]*)/g, (full, prefix, key, value) => {
-        if (!isSensitiveNetworkKey(key)) {
-            return full;
-        }
-        return `${prefix}${key}=[redacted]`;
-    });
+function requireConstants () {
+	if (hasRequiredConstants) return constants;
+	hasRequiredConstants = 1;
+
+	// Note: this is the semver.org version of the spec that it implements
+	// Not necessarily the package version of this code.
+	const SEMVER_SPEC_VERSION = '2.0.0';
+
+	const MAX_LENGTH = 256;
+	const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER ||
+	/* istanbul ignore next */ 9007199254740991;
+
+	// Max safe segment length for coercion.
+	const MAX_SAFE_COMPONENT_LENGTH = 16;
+
+	// Max safe length for a build identifier. The max length minus 6 characters for
+	// the shortest version with a build 0.0.0+BUILD.
+	const MAX_SAFE_BUILD_LENGTH = MAX_LENGTH - 6;
+
+	const RELEASE_TYPES = [
+	  'major',
+	  'premajor',
+	  'minor',
+	  'preminor',
+	  'patch',
+	  'prepatch',
+	  'prerelease',
+	];
+
+	constants = {
+	  MAX_LENGTH,
+	  MAX_SAFE_COMPONENT_LENGTH,
+	  MAX_SAFE_BUILD_LENGTH,
+	  MAX_SAFE_INTEGER,
+	  RELEASE_TYPES,
+	  SEMVER_SPEC_VERSION,
+	  FLAG_INCLUDE_PRERELEASE: 0b001,
+	  FLAG_LOOSE: 0b010,
+	};
+	return constants;
 }
 
-const DEVICE_LOG_PATH = '/__hb_sdk__/device-logs';
-const registryKey = Symbol.for('@heybox/hb-sdk/device-logs');
-const registry = globalThis;
-const stores = (registry[registryKey] ??= new Map());
-function registerDeviceLogs(port, store) {
-    stores.set(port, store);
-    return () => {
-        if (stores.get(port) === store)
-            stores.delete(port);
-    };
-}
-class DeviceLogStore {
-    sandboxRequests = new Map();
-    listSandbox(id, path) {
-        const device = this.devices.get(id);
-        if (!device || Date.now() - device.lastSeen > 15000)
-            return Promise.resolve({ error: '设备已离线' });
-        if (path !== '.' && (!path || path.length > 1024 || /[\\\\\u0000-\u001f]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')))
-            return Promise.resolve({ error: '无效目录路径' });
-        if (this.sandboxRequests.size >= 64)
-            return Promise.resolve({ error: '查询繁忙，请稍后重试' });
-        const requestId = randomUUID();
-        return new Promise(resolve => {
-            const timer = setTimeout(() => { this.sandboxRequests.delete(requestId); resolve({ error: '设备查询超时' }); }, 10000);
-            this.sandboxRequests.set(requestId, { id, path, requestId, resolve: value => { clearTimeout(timer); this.sandboxRequests.delete(requestId); resolve(value); } });
-        });
-    }
-    uploadToken = randomBytes(32).toString('hex');
-    epoch = randomUUID();
-    expiresAt = Date.now() + 12 * 60 * 60 * 1000;
-    cursor = 0;
-    logs = [];
-    devices = new Map();
-    query(params) {
-        const after = Math.max(0, Number(params.get('after')) || 0);
-        const limit = Math.min(500, Math.max(1, Number(params.get('limit')) || 100));
-        const selected = this.logs.filter((log) => log.cursor > after &&
-            (!params.get('device') || log.deviceSessionId === params.get('device')) &&
-            (!params.get('level') || log.level === params.get('level')) &&
-            (!params.get('source') || log.source === params.get('source')) &&
-            (!params.get('callId') || log.callId === params.get('callId')) &&
-            (!params.get('id') || String(log.cursor) === params.get('id')) &&
-            (!params.get('since') || log.timestamp >= Number(params.get('since'))) &&
-            (!params.get('query') || log.message.toLowerCase().includes(params.get('query').toLowerCase())));
-        const items = selected.slice(0, limit);
-        return {
-            schemaVersion: 1,
-            epoch: this.epoch,
-            items,
-            nextCursor: selected.length > limit ? items.at(-1).cursor : this.cursor,
-            hasMore: selected.length > limit,
-            gap: after > 0 && after < (this.logs[0]?.cursor ?? 1) - 1,
-            devices: [...this.devices.values()].map(({ id, name, platform, connectedAt, lastSeen }) => ({
-                id,
-                name,
-                platform,
-                connectedAt,
-                lastSeen,
-                online: Date.now() - lastSeen < 15000,
-            })),
-        };
-    }
-    async upload(req, res) {
-        const reply = (status, value) => {
-            res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
-            res.end(JSON.stringify(value));
-        };
-        if (req.method !== 'POST') {
-            reply(405, {});
-            return;
-        }
-        if (Date.now() > this.expiresAt) {
-            reply(410, { code: 'EXPIRED' });
-            return;
-        }
-        let text = '';
-        try {
-            req.setEncoding('utf8');
-            for await (const chunk of req) {
-                text += chunk;
-                if (Buffer.byteLength(text) > 65536) {
-                    reply(413, {});
-                    return;
-                }
-            }
-            const body = JSON.parse(text);
-            if (body.register === true) {
-                if (req.headers['x-hb-log-token'] !== this.uploadToken) {
-                    reply(403, {});
-                    return;
-                }
-                const registrationId = typeof body.registrationId === 'string' && /^[a-f0-9]{32}$/.test(body.registrationId) ? body.registrationId : undefined;
-                const existing = registrationId && [...this.devices.values()].find(device => device.registrationId === registrationId);
-                if (existing) {
-                    reply(200, { id: existing.id, token: existing.token });
-                    return;
-                }
-                if (this.devices.size >= 64) {
-                    reply(429, {});
-                    return;
-                }
-                const id = randomUUID();
-                const platform = ['iOS', 'Android', 'Windows', 'macOS', 'Browser'].includes(body.platform) ? body.platform : 'Browser';
-                const device = {
-                    id,
-                    platform,
-                    registrationId,
-                    connectedAt: Date.now(),
-                    name: `${platform} · ${this.devices.size + 1}`,
-                    lastSeen: Date.now(),
-                    sequence: 0,
-                    token: randomBytes(32).toString('hex'),
-                    windowStart: Date.now(),
-                    count: 0,
-                };
-                this.devices.set(id, device);
-                reply(200, { id, token: device.token });
-                return;
-            }
-            const device = this.devices.get(body.id);
-            if (!device || req.headers['x-hb-log-token'] !== device.token) {
-                reply(403, {});
-                return;
-            }
-            if (!Array.isArray(body.logs) || body.logs.length > 50) {
-                reply(400, {});
-                return;
-            }
-            if (Date.now() - device.windowStart > 1000) {
-                device.windowStart = Date.now();
-                device.count = 0;
-            }
-            if (device.count + body.logs.length > 200) {
-                reply(429, {});
-                return;
-            }
-            device.count += body.logs.length;
-            device.lastSeen = Date.now();
-            if (body.sandboxResult && typeof body.sandboxResult === 'object') {
-                const result = body.sandboxResult;
-                const pending = this.sandboxRequests.get(result.requestId);
-                if (pending?.id === device.id) {
-                    const entries = Array.isArray(result.entries) ? result.entries.slice(0, 200).filter((entry) => entry && ['file', 'directory'].includes(entry.kind) && typeof entry.name === 'string' && entry.name.length <= 255 && !/[\\\\/\u0000-\u001f]/.test(entry.name) && !['.', '..'].includes(entry.name)).map((entry) => ({ name: entry.name, kind: entry.kind })) : [];
-                    pending.resolve({ deviceSessionId: device.id, requestId: pending.requestId, path: pending.path, timestamp: Date.now(), entries, error: result.error ? '设备不支持或无权读取此目录' : undefined, truncated: result.truncated === true });
-                }
-            }
-            for (const log of body.logs) {
-                if (!log || typeof log !== 'object')
-                    continue;
-                if (!Number.isSafeInteger(log.sequence) ||
-                    log.sequence <= device.sequence ||
-                    !Number.isFinite(log.timestamp) ||
-                    !['log', 'debug', 'info', 'warn', 'error'].includes(log.level) ||
-                    typeof log.message !== 'string')
-                    continue;
-                device.sequence = log.sequence;
-                this.logs.push({
-                    cursor: ++this.cursor,
-                    deviceSessionId: device.id,
-                    sequence: log.sequence,
-                    timestamp: log.timestamp,
-                    receivedAt: Date.now(),
-                    level: log.level,
-                    source: log.source === 'sdk' ? 'sdk' : 'app',
-                    message: sanitizeDiagnosticMessage(log.message)
-                        .replace(/(authorization|cookie|password|secret|token|pkey|api[_-]?key)(["'\s:=]+)([^\s,}]+)/gi, '$1$2[redacted]')
-                        .slice(0, 8192),
-                    truncated: log.truncated === true || log.message.length > 8192,
-                    ...(typeof log.method === 'string' ? { method: log.method.slice(0, 100) } : {}),
-                    ...(typeof log.callId === 'string' ? { callId: log.callId.slice(0, 100) } : {}),
-                    ...(typeof log.errorCode === 'string' && /^[A-Z0-9_]{1,100}$/.test(log.errorCode) ? { errorCode: log.errorCode } : {}),
-                    ...(log.outcome === 'success' || log.outcome === 'error' ? { outcome: log.outcome } : {}),
-                    ...(Number.isFinite(log.durationMs) ? { durationMs: Math.max(0, log.durationMs) } : {}),
-                });
-            }
-            if (this.logs.length > 5000)
-                this.logs.splice(0, this.logs.length - 5000);
-            reply(200, { sequence: device.sequence, sandboxRequest: [...this.sandboxRequests.values()].find(request => request.id === device.id) ? (() => { const request = [...this.sandboxRequests.values()].find(request => request.id === device.id); return { requestId: request.requestId, path: request.path }; })() : undefined });
-        }
-        catch {
-            reply(400, { code: 'INVALID_LOG_BATCH' });
-        }
-    }
-}
-/** 同源开发页面使用有界批量回传；传输失败不会递归写入 console。 */
-function deviceLogBootstrap(token) {
-    return `<script>(function(){if(window.__hb_sdk_device_logs_installed__)return;
-window.__hb_sdk_device_logs_installed__=true;
-window.__hb_sdk_mini_dev_console_installed__=true;
-var endpoint='${DEVICE_LOG_PATH}',credential='${token}',id='',queue=[],seq=0,busy=false,dropped=0;
-var registrationId=Array.from(crypto.getRandomValues(new Uint8Array(16)),function(n){return n.toString(16).padStart(2,'0')}).join('');
-var send=window.fetch.bind(window);
-var sandboxResult;
-function format(v){try{return typeof v==='string'?v:v instanceof Error?v.stack||v.message:JSON.stringify(v,function(k,value){return /authorization|cookie|password|secret|token|pkey|api.?key/i.test(k)?'[redacted]':value})}catch(e){return '[无法序列化]'}}function add(level,args,source){if(queue.length>=500){queue.shift();
-dropped++}var message=args.map(format).join(' ');
-message=message.replace(/https?:\\/\\/[^\\s]+/g,function(raw){try{var url=new URL(raw);
-url.username='';
-url.password='';
-url.search='';
-url.hash='';
-return url.href}catch(e){return '[URL]'}});
-message=message.replace(/(authorization|cookie|password|secret|token|pkey|api[_-]?key)([\\"'\\s:=]+)([^\\s,}]+)/gi,'$1$2[redacted]');
-queue.push({truncated:message.length>8192,sequence:++seq,timestamp:Date.now(),level:level,source:source||'app',message:message.slice(0,8192)})}window.__hbSdkDeviceLog=function(event){add(event.outcome==='error'?'error':'info',[event.method+' · '+event.outcome+' · '+event.durationMs+' ms'],'sdk');
-Object.assign(queue[queue.length-1],event)};
-['log','debug','info','warn','error'].forEach(function(level){var original=console[level];
-console[level]=function(){add(level,Array.prototype.slice.call(arguments));
-return original.apply(this,arguments)}});
-window.addEventListener('error',function(e){add('error',[e.message])});
-window.addEventListener('unhandledrejection',function(e){add('error',[e.reason])});
-async function flush(){if(busy)return;
-busy=true;
-try{if(!id){var ua=navigator.userAgent;
-var platform=window.name==='__hb_sdk_mini_dev__'?'Browser':/Android/i.test(ua)?'Android':/iPhone|iPad/i.test(ua)?'iOS':/Windows/i.test(ua)?'Windows':/Mac/i.test(ua)?'macOS':'Browser';
-var r=await send(endpoint,{method:'POST',headers:{'content-type':'application/json','x-hb-log-token':credential},body:JSON.stringify({register:true,platform:platform,registrationId:registrationId}),signal:AbortSignal.timeout(5000)});
-if(!r.ok)return;
-var d=await r.json();
-id=d.id;
-credential=d.token}if(dropped){add('warn',['日志缓冲已丢弃 '+dropped+' 条']);
-dropped=0}var batch=queue.slice(0,50);
-while(batch.length>1&&new TextEncoder().encode(JSON.stringify(batch)).length>48000)batch.pop();
-var result=await send(endpoint,{method:'POST',headers:{'content-type':'application/json','x-hb-log-token':credential},body:JSON.stringify({id:id,logs:batch,sandboxResult:sandboxResult}),signal:AbortSignal.timeout(5000)});
-if(result.ok){var ack=await result.json();sandboxResult=undefined;
-if(ack.sandboxRequest){try{var entries=await window.__hbSdkSandboxList(ack.sandboxRequest.path);sandboxResult={requestId:ack.sandboxRequest.requestId,entries:entries.slice(0,200),truncated:entries.length>200}}catch(e){sandboxResult={requestId:ack.sandboxRequest.requestId,error:true}}}
-queue=queue.filter(function(l){return l.sequence>ack.sequence})}}catch(e){}finally{busy=false}}setInterval(flush,1000);
-flush()})();
-</script>`;
-}
-
-var re = {exports: {}};
-
-var constants;
-var hasRequiredConstants;
-
-function requireConstants () {
-	if (hasRequiredConstants) return constants;
-	hasRequiredConstants = 1;
-
-	// Note: this is the semver.org version of the spec that it implements
-	// Not necessarily the package version of this code.
-	const SEMVER_SPEC_VERSION = '2.0.0';
-
-	const MAX_LENGTH = 256;
-	const MAX_SAFE_INTEGER = Number.MAX_SAFE_INTEGER ||
-	/* istanbul ignore next */ 9007199254740991;
-
-	// Max safe segment length for coercion.
-	const MAX_SAFE_COMPONENT_LENGTH = 16;
-
-	// Max safe length for a build identifier. The max length minus 6 characters for
-	// the shortest version with a build 0.0.0+BUILD.
-	const MAX_SAFE_BUILD_LENGTH = MAX_LENGTH - 6;
-
-	const RELEASE_TYPES = [
-	  'major',
-	  'premajor',
-	  'minor',
-	  'preminor',
-	  'patch',
-	  'prepatch',
-	  'prerelease',
-	];
-
-	constants = {
-	  MAX_LENGTH,
-	  MAX_SAFE_COMPONENT_LENGTH,
-	  MAX_SAFE_BUILD_LENGTH,
-	  MAX_SAFE_INTEGER,
-	  RELEASE_TYPES,
-	  SEMVER_SPEC_VERSION,
-	  FLAG_INCLUDE_PRERELEASE: 0b001,
-	  FLAG_LOOSE: 0b010,
-	};
-	return constants;
-}
-
-var debug_1;
-var hasRequiredDebug;
-
-function requireDebug () {
-	if (hasRequiredDebug) return debug_1;
-	hasRequiredDebug = 1;
-
-	const debug = (
-	  typeof process === 'object' &&
-	  process.env &&
-	  process.env.NODE_DEBUG &&
-	  /\bsemver\b/i.test(process.env.NODE_DEBUG)
-	) ? (...args) => console.error('SEMVER', ...args)
-	  : () => {};
-
-	debug_1 = debug;
-	return debug_1;
+var debug_1;
+var hasRequiredDebug;
+
+function requireDebug () {
+	if (hasRequiredDebug) return debug_1;
+	hasRequiredDebug = 1;
+
+	const debug = (
+	  typeof process === 'object' &&
+	  process.env &&
+	  process.env.NODE_DEBUG &&
+	  /\bsemver\b/i.test(process.env.NODE_DEBUG)
+	) ? (...args) => console.error('SEMVER', ...args)
+	  : () => {};
+
+	debug_1 = debug;
+	return debug_1;
 }
 
 var hasRequiredRe;
@@ -3009,111 +2688,635 @@ function requireSubset () {
 	subset_1 = subset;
 	return subset_1;
 }
-
-var semver;
-var hasRequiredSemver;
-
-function requireSemver () {
-	if (hasRequiredSemver) return semver;
-	hasRequiredSemver = 1;
-
-	// just pre-load all the stuff that index.js lazily exports
-	const internalRe = requireRe();
-	const constants = requireConstants();
-	const SemVer = requireSemver$1();
-	const identifiers = requireIdentifiers();
-	const parse = requireParse();
-	const valid = requireValid$1();
-	const clean = requireClean();
-	const inc = requireInc();
-	const diff = requireDiff();
-	const major = requireMajor();
-	const minor = requireMinor();
-	const patch = requirePatch();
-	const prerelease = requirePrerelease();
-	const compare = requireCompare();
-	const rcompare = requireRcompare();
-	const compareLoose = requireCompareLoose();
-	const compareBuild = requireCompareBuild();
-	const sort = requireSort();
-	const rsort = requireRsort();
-	const gt = requireGt();
-	const lt = requireLt();
-	const eq = requireEq();
-	const neq = requireNeq();
-	const gte = requireGte();
-	const lte = requireLte();
-	const cmp = requireCmp();
-	const coerce = requireCoerce();
-	const truncate = requireTruncate();
-	const Comparator = requireComparator();
-	const Range = requireRange();
-	const satisfies = requireSatisfies();
-	const toComparators = requireToComparators();
-	const maxSatisfying = requireMaxSatisfying();
-	const minSatisfying = requireMinSatisfying();
-	const minVersion = requireMinVersion();
-	const validRange = requireValid();
-	const outside = requireOutside();
-	const gtr = requireGtr();
-	const ltr = requireLtr();
-	const intersects = requireIntersects();
-	const simplifyRange = requireSimplify();
-	const subset = requireSubset();
-	semver = {
-	  parse,
-	  valid,
-	  clean,
-	  inc,
-	  diff,
-	  major,
-	  minor,
-	  patch,
-	  prerelease,
-	  compare,
-	  rcompare,
-	  compareLoose,
-	  compareBuild,
-	  sort,
-	  rsort,
-	  gt,
-	  lt,
-	  eq,
-	  neq,
-	  gte,
-	  lte,
-	  cmp,
-	  coerce,
-	  truncate,
-	  Comparator,
-	  Range,
-	  satisfies,
-	  toComparators,
-	  maxSatisfying,
-	  minSatisfying,
-	  minVersion,
-	  validRange,
-	  outside,
-	  gtr,
-	  ltr,
-	  intersects,
-	  simplifyRange,
-	  subset,
-	  SemVer,
-	  re: internalRe.re,
-	  src: internalRe.src,
-	  tokens: internalRe.t,
-	  SEMVER_SPEC_VERSION: constants.SEMVER_SPEC_VERSION,
-	  RELEASE_TYPES: constants.RELEASE_TYPES,
-	  compareIdentifiers: identifiers.compareIdentifiers,
-	  rcompareIdentifiers: identifiers.rcompareIdentifiers,
-	};
-	return semver;
+
+var semver;
+var hasRequiredSemver;
+
+function requireSemver () {
+	if (hasRequiredSemver) return semver;
+	hasRequiredSemver = 1;
+
+	// just pre-load all the stuff that index.js lazily exports
+	const internalRe = requireRe();
+	const constants = requireConstants();
+	const SemVer = requireSemver$1();
+	const identifiers = requireIdentifiers();
+	const parse = requireParse();
+	const valid = requireValid$1();
+	const clean = requireClean();
+	const inc = requireInc();
+	const diff = requireDiff();
+	const major = requireMajor();
+	const minor = requireMinor();
+	const patch = requirePatch();
+	const prerelease = requirePrerelease();
+	const compare = requireCompare();
+	const rcompare = requireRcompare();
+	const compareLoose = requireCompareLoose();
+	const compareBuild = requireCompareBuild();
+	const sort = requireSort();
+	const rsort = requireRsort();
+	const gt = requireGt();
+	const lt = requireLt();
+	const eq = requireEq();
+	const neq = requireNeq();
+	const gte = requireGte();
+	const lte = requireLte();
+	const cmp = requireCmp();
+	const coerce = requireCoerce();
+	const truncate = requireTruncate();
+	const Comparator = requireComparator();
+	const Range = requireRange();
+	const satisfies = requireSatisfies();
+	const toComparators = requireToComparators();
+	const maxSatisfying = requireMaxSatisfying();
+	const minSatisfying = requireMinSatisfying();
+	const minVersion = requireMinVersion();
+	const validRange = requireValid();
+	const outside = requireOutside();
+	const gtr = requireGtr();
+	const ltr = requireLtr();
+	const intersects = requireIntersects();
+	const simplifyRange = requireSimplify();
+	const subset = requireSubset();
+	semver = {
+	  parse,
+	  valid,
+	  clean,
+	  inc,
+	  diff,
+	  major,
+	  minor,
+	  patch,
+	  prerelease,
+	  compare,
+	  rcompare,
+	  compareLoose,
+	  compareBuild,
+	  sort,
+	  rsort,
+	  gt,
+	  lt,
+	  eq,
+	  neq,
+	  gte,
+	  lte,
+	  cmp,
+	  coerce,
+	  truncate,
+	  Comparator,
+	  Range,
+	  satisfies,
+	  toComparators,
+	  maxSatisfying,
+	  minSatisfying,
+	  minVersion,
+	  validRange,
+	  outside,
+	  gtr,
+	  ltr,
+	  intersects,
+	  simplifyRange,
+	  subset,
+	  SemVer,
+	  re: internalRe.re,
+	  src: internalRe.src,
+	  tokens: internalRe.t,
+	  SEMVER_SPEC_VERSION: constants.SEMVER_SPEC_VERSION,
+	  RELEASE_TYPES: constants.RELEASE_TYPES,
+	  compareIdentifiers: identifiers.compareIdentifiers,
+	  rcompareIdentifiers: identifiers.rcompareIdentifiers,
+	};
+	return semver;
+}
+
+var semverExports = requireSemver();
+
+const BASIC_INFO_MAX_BYTES = 10 * 1024 * 1024;
+const BASIC_INFO_MAX_PIXELS = 40_000_000;
+/** 按 NFKC 和 Unicode 空白规范化名称，并校验 1–40 个字符及禁用字符。 */
+function normalizeBasicInfoName(raw) {
+    if (typeof raw !== 'string')
+        throw new Error('heybox.name 必须是字符串');
+    // 与 Go TrimSpace 一致（JS trim 额外移除 BOM，故使用 Unicode White_Space）。
+    const name = raw.normalize('NFKC').replace(/^\p{White_Space}+|\p{White_Space}+$/gu, '');
+    if (Array.from(name).length < 1 || Array.from(name).length > 40 || /[\p{Cc}\p{Cf}\p{Zl}\p{Zp}<>&"']/u.test(name) || !/[\p{L}\p{N}]/u.test(name)) {
+        throw new Error('名称须包含 1–40 个字符及文字或数字，不能包含控制字符或 HTML 特殊字符');
+    }
+    return name;
+}
+function validateBasicInfoPath(raw) {
+    if (typeof raw !== 'string' || !raw || /[\\:%?#\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/u.test(raw))
+        throw new Error('资料图片必须是项目内的规范相对路径');
+    const forbidden = new Set(['', '.', '..', '.git', 'node_modules', 'dist', '.hb-sdk', '.vite', '.cache', '.tmp', 'tmp']);
+    if (raw.split('/').some((part) => forbidden.has(part)))
+        throw new Error('资料图片路径包含禁止的目录');
+    if (!/\.(png|jpe?g|gif|webp)$/i.test(raw))
+        throw new Error('资料图片仅支持 JPEG、PNG、GIF、WebP');
+    return raw;
+}
+/** 解析项目或构建资料；仅早于 0.8.2 且三项全部缺失时返回 undefined。 */
+function parseMiniappBasicInfo(value, sdkVersion = '0.8.2') {
+    sdkVersion = sdkVersion.trim();
+    if (!semverExports.valid(sdkVersion) || sdkVersion.startsWith('v') || sdkVersion.includes('+'))
+        throw new Error('manifest.sdkVersion 必须是合法 SemVer');
+    const fields = ['name', 'icon', 'coverImages'];
+    const present = fields.filter((key) => Object.prototype.hasOwnProperty.call(value, key));
+    if (!present.length && semverExports.lt(sdkVersion, '0.8.2'))
+        return undefined;
+    if (present.length !== fields.length)
+        throw new Error('请配置 heybox.name、heybox.icon、heybox.coverImages，或运行 remote bind/dev/remote deploy 迁移已发布资料');
+    const name = normalizeBasicInfoName(value.name);
+    const icon = validateBasicInfoPath(value.icon);
+    if (!Array.isArray(value.coverImages) || value.coverImages.length < 1 || value.coverImages.length > 5)
+        throw new Error('coverImages 必须包含 1–5 张图片');
+    const coverImages = value.coverImages.map(validateBasicInfoPath);
+    if (new Set(coverImages).size !== coverImages.length)
+        throw new Error('封面路径不能重复');
+    return { name, icon, coverImages };
+}
+
+async function inspectBasicInfoImage(bytes, sourcePath, kind) {
+    const inspected = await inspectDecodedBasicInfoImage(bytes, kind);
+    const extensions = { jpg: ['jpg', 'jpeg'], png: ['png'], gif: ['gif'], webp: ['webp'] };
+    const ext = sourcePath.split('.').pop().toLowerCase();
+    if (!extensions[inspected.extension]?.includes(ext))
+        throw new Error('资料图片格式与扩展名不一致');
+    return inspected;
+}
+async function inspectDecodedBasicInfoImage(bytes, kind) {
+    if (!bytes.length || bytes.length > BASIC_INFO_MAX_BYTES)
+        throw new Error('资料图片不得为空或超过 10 MiB');
+    const decoder = sharp(bytes, { limitInputPixels: BASIC_INFO_MAX_PIXELS, failOn: 'warning' });
+    const metadata = await decoder.metadata();
+    const extensions = { jpeg: 'jpg', png: 'png', gif: 'gif', webp: 'webp' };
+    if (!metadata.format || !extensions[metadata.format])
+        throw new Error('资料图片格式不支持');
+    const width = metadata.width ?? 0;
+    const height = metadata.pageHeight ?? metadata.height ?? 0;
+    if (!width || !height || width * height > BASIC_INFO_MAX_PIXELS)
+        throw new Error('资料图片不得超过 4000 万像素');
+    if (kind === 'icon' && (width !== 200 || height !== 200))
+        throw new Error('icon 必须是 200×200');
+    // 强制解码而非只信任图片头；不将解码结果写回图片。
+    await decoder.stats();
+    return { sha256: createHash('sha256').update(bytes).digest('hex'), extension: extensions[metadata.format] };
+}
+async function readBasicInfoSource(projectRoot, relative, kind) {
+    validateBasicInfoPath(relative);
+    const root = await realpath(projectRoot);
+    const target = await realpath(path.join(root, relative));
+    const resolvedRelative = path.relative(root, target).split(path.sep).join('/');
+    validateBasicInfoPath(resolvedRelative);
+    if (resolvedRelative.startsWith('../') || path.isAbsolute(resolvedRelative))
+        throw new Error('资料图片不能逃逸项目目录');
+    const info = await stat(target);
+    if (!info.isFile() || info.size > BASIC_INFO_MAX_BYTES)
+        throw new Error('资料图片必须为不超过 10 MiB 的普通文件');
+    const file = await open(target, constants$1.O_RDONLY | constants$1.O_NOFOLLOW);
+    try {
+        const actual = await file.stat();
+        if (!actual.isFile() || actual.size > BASIC_INFO_MAX_BYTES)
+            throw new Error('资料图片文件已变化');
+        const bytes = await file.readFile();
+        return { bytes, ...(await inspectBasicInfoImage(bytes, relative, kind)) };
+    }
+    finally {
+        await file.close();
+    }
+}
+async function prepareMiniappBasicInfo(projectRoot, outputRoot, sdkVersion) {
+    const pkg = JSON.parse(await readFile(path.join(projectRoot, 'package.json'), 'utf8'));
+    const profile = parseMiniappBasicInfo(pkg.heybox ?? {}, sdkVersion);
+    if (!profile)
+        return undefined;
+    await mkdir(outputRoot, { recursive: true });
+    const output = { ...profile, coverImages: [] };
+    const entries = [
+        { path: profile.icon, kind: 'icon', label: 'icon' },
+        ...profile.coverImages.map((p, i) => ({ path: p, kind: 'cover', label: `cover-${String(i + 1).padStart(2, '0')}` })),
+    ];
+    for (const entry of entries) {
+        const sourceReal = await realpath(path.join(projectRoot, entry.path));
+        const outputReal = await realpath(outputRoot);
+        const fromOutput = path.relative(outputReal, sourceReal);
+        if (!fromOutput.startsWith('..') && !path.isAbsolute(fromOutput))
+            throw new Error('资料源文件不能位于构建输出目录');
+        const image = await readBasicInfoSource(projectRoot, entry.path, entry.kind);
+        const relative = `_hb/basic-info/${entry.label}.${image.sha256.slice(0, 12)}.${image.extension}`;
+        const target = path.join(outputRoot, relative);
+        await mkdir(outputRoot, { recursive: true });
+        await ensureBasicInfoDirectory(outputRoot, '_hb/basic-info');
+        // 全字节比较保证截断哈希冲突和 public 保留路径冲突不会静默覆盖。
+        try {
+            await writeFile(target, image.bytes, { flag: 'wx' });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST' ||
+                !(await readBasicInfoSource(outputRoot, relative, entry.kind).then((existing) => existing.bytes.equals(image.bytes), () => false)))
+                throw new Error('构建资料保留目录冲突，请移除未知文件');
+        }
+        if (entry.kind === 'icon')
+            output.icon = relative;
+        else
+            output.coverImages.push(relative);
+    }
+    return output;
+}
+/** 逐级校验真实目录，避免保留目录或迁移目录中的符号链接将写入带到项目外。 */
+async function ensureBasicInfoDirectory(rootPath, relative) {
+    const root = await realpath(rootPath);
+    let current = root;
+    for (const part of relative.split('/')) {
+        if (!part || part === '.' || part === '..')
+            throw new Error('资料目录不合法');
+        current = path.join(current, part);
+        await mkdir(current).catch((error) => {
+            if (error.code !== 'EEXIST')
+                throw error;
+        });
+        const resolved = await realpath(current);
+        const within = path.relative(root, resolved);
+        if (within.startsWith('..') || path.isAbsolute(within))
+            throw new Error('资料目录不能逃逸项目');
+    }
+}
+
+/** 构建时替换为当前发布包的实际版本。 */
+const HB_SDK_VERSION = typeof undefined === 'string'
+    ? undefined
+    : '0.8.2-alpha.5';
+
+/**
+ * iframe 与调试台页面的开发期 console 捕获转发。
+ *
+ * 双条件门控（iframe 转发）：
+ * 1. 构建期：`hb-sdk dev`（vite serve）注入 `false`；`hb-sdk build` /
+ *    `vite build`（生产）永不注入或替换为 `false`，本模块被死代码消除。
+ * 2. 运行期：仅在 `window.name` 为 `__hb_sdk_mini_dev__` 的调试 iframe 中激活，
+ *    用户设备上的正式运行环境没有该标记。
+ *
+ * 无侵入 patch `console.log/debug/info/warn/error`：原样放行（DevTools 不受影响）+
+ * 通过 `window.parent.postMessage` 转发给调试台（CSP 的 connect-src 不约束 postMessage，
+ * 网络上报由调试台页面代理）。发送全程静默：失败不得回打 console，避免自触发死循环。
+ *
+ * 激活时机：由 SDK 默认单例初始化时调用（业务 `import '@heybox/hb-sdk'` 即生效）；
+ * iframe 标记由调试台 `iframe.name` 与 vite dev 注入的无依赖 bootstrap 共同设置。
+ * 调试台页面自身（runtime 跑在这里，`[hb-sdk-runtime]` 日志不经过 iframe）另用
+ * `installMiniDevConsoleSelfCapture` 接入「日志」页签（source: 'host'）。
+ */
+const MINI_DEV_CONSOLE_EVENT_TYPE = 'hb-sdk:mini-dev-console';
+/** 调试台页面与 iframe bootstrap 共用的已安装标记（window/console 上的属性名）。 */
+const MINI_DEV_CONSOLE_INSTALL_FLAG = '__hb_sdk_mini_dev_console_installed__';
+
+/**
+ * network.request 诊断日志的纯脱敏工具。
+ *
+ * @remarks
+ * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
+ * modules observability、devtools Browser Dev Host / proxy 共用，并满足 boundary
+ *（devtools 不得直接 import runtime capability modules）。
+ */
+/** 敏感字段名：header / query / body key 共用。 */
+const SENSITIVE_KEY_PATTERN = /(authorization|cookie|password|passwd|secret|token|pkey|private[_-]?key|access[_-]?key|client[_-]?secret|api[_-]?key|apikey|session|jwt|refresh[_-]?token|csrf)/i;
+/**
+ * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
+ */
+function sanitizeNetworkRequestUrl(url) {
+    if (!url) {
+        return url;
+    }
+    try {
+        const parsed = new URL(url);
+        parsed.username = '';
+        parsed.password = '';
+        redactUrlSearchParams(parsed.searchParams);
+        if (parsed.hash && parsed.hash.length > 1) {
+            const hashBody = parsed.hash.slice(1);
+            if (hashBody.includes('=')) {
+                const hashParams = new URLSearchParams(hashBody);
+                if (redactUrlSearchParams(hashParams)) {
+                    parsed.hash = hashParams.toString();
+                }
+            }
+        }
+        return parsed.toString();
+    }
+    catch {
+        return redactSensitivePairsInRawText(url);
+    }
+}
+/**
+ * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
+ */
+function sanitizeDiagnosticMessage(message) {
+    if (!message) {
+        return message;
+    }
+    return message.replace(/https?:\/\/[^\s]+/gi, matched => sanitizeNetworkRequestUrl(matched.replace(/[),.;]+$/g, '')));
+}
+function isSensitiveNetworkKey(key) {
+    return SENSITIVE_KEY_PATTERN.test(key.trim());
+}
+function redactUrlSearchParams(params) {
+    let changed = false;
+    for (const key of [...params.keys()]) {
+        if (isSensitiveNetworkKey(key)) {
+            params.set(key, '[redacted]');
+            changed = true;
+        }
+    }
+    return changed;
+}
+function redactSensitivePairsInRawText(text) {
+    return text.replace(/([?&#]|^|[?&])([^=&#\s]+)=([^&#\s]*)/g, (full, prefix, key, value) => {
+        if (!isSensitiveNetworkKey(key)) {
+            return full;
+        }
+        return `${prefix}${key}=[redacted]`;
+    });
+}
+
+const DEVICE_LOG_PATH = '/__hb_sdk__/device-logs';
+const registryKey = Symbol.for('@heybox/hb-sdk/device-logs');
+const registry = globalThis;
+const stores = (registry[registryKey] ??= new Map());
+function registerDeviceLogs(port, store) {
+    stores.set(port, store);
+    return () => {
+        if (stores.get(port) === store)
+            stores.delete(port);
+    };
+}
+class DeviceLogStore {
+    sandboxRequests = new Map();
+    listSandbox(id, path) {
+        const device = this.devices.get(id);
+        if (!device || Date.now() - device.lastSeen > 15000)
+            return Promise.resolve({ error: '设备已离线' });
+        if (path !== '.' && (!path || path.length > 1024 || /[\\\\\u0000-\u001f]/.test(path) || path.split('/').some(part => !part || part === '.' || part === '..')))
+            return Promise.resolve({ error: '无效目录路径' });
+        if (this.sandboxRequests.size >= 64)
+            return Promise.resolve({ error: '查询繁忙，请稍后重试' });
+        const requestId = randomUUID();
+        return new Promise(resolve => {
+            const timer = setTimeout(() => { this.sandboxRequests.delete(requestId); resolve({ error: '设备查询超时' }); }, 10000);
+            this.sandboxRequests.set(requestId, { id, path, requestId, resolve: value => { clearTimeout(timer); this.sandboxRequests.delete(requestId); resolve(value); } });
+        });
+    }
+    uploadToken = randomBytes(32).toString('hex');
+    epoch = randomUUID();
+    expiresAt = Date.now() + 12 * 60 * 60 * 1000;
+    cursor = 0;
+    logs = [];
+    devices = new Map();
+    query(params) {
+        const after = Math.max(0, Number(params.get('after')) || 0);
+        const limit = Math.min(500, Math.max(1, Number(params.get('limit')) || 100));
+        const selected = this.logs.filter((log) => log.cursor > after &&
+            (!params.get('device') || log.deviceSessionId === params.get('device')) &&
+            (!params.get('level') || log.level === params.get('level')) &&
+            (!params.get('source') || log.source === params.get('source')) &&
+            (!params.get('callId') || log.callId === params.get('callId')) &&
+            (!params.get('id') || String(log.cursor) === params.get('id')) &&
+            (!params.get('since') || log.timestamp >= Number(params.get('since'))) &&
+            (!params.get('query') || log.message.toLowerCase().includes(params.get('query').toLowerCase())));
+        const items = selected.slice(0, limit);
+        return {
+            schemaVersion: 1,
+            epoch: this.epoch,
+            items,
+            nextCursor: selected.length > limit ? items.at(-1).cursor : this.cursor,
+            hasMore: selected.length > limit,
+            gap: after > 0 && after < (this.logs[0]?.cursor ?? 1) - 1,
+            devices: [...this.devices.values()].map(({ id, name, platform, connectedAt, lastSeen }) => ({
+                id,
+                name,
+                platform,
+                connectedAt,
+                lastSeen,
+                online: Date.now() - lastSeen < 15000,
+            })),
+        };
+    }
+    async upload(req, res) {
+        const reply = (status, value) => {
+            res.writeHead(status, { 'content-type': 'application/json', 'cache-control': 'no-store' });
+            res.end(JSON.stringify(value));
+        };
+        if (req.method !== 'POST') {
+            reply(405, {});
+            return;
+        }
+        if (Date.now() > this.expiresAt) {
+            reply(410, { code: 'EXPIRED' });
+            return;
+        }
+        let text = '';
+        try {
+            req.setEncoding('utf8');
+            for await (const chunk of req) {
+                text += chunk;
+                if (Buffer.byteLength(text) > 65536) {
+                    reply(413, {});
+                    return;
+                }
+            }
+            const body = JSON.parse(text);
+            if (body.register === true) {
+                if (req.headers['x-hb-log-token'] !== this.uploadToken) {
+                    reply(403, {});
+                    return;
+                }
+                const registrationId = typeof body.registrationId === 'string' && /^[a-f0-9]{32}$/.test(body.registrationId) ? body.registrationId : undefined;
+                const existing = registrationId && [...this.devices.values()].find(device => device.registrationId === registrationId);
+                if (existing) {
+                    reply(200, { id: existing.id, token: existing.token });
+                    return;
+                }
+                if (this.devices.size >= 64) {
+                    reply(429, {});
+                    return;
+                }
+                const id = randomUUID();
+                const platform = ['iOS', 'Android', 'Windows', 'macOS', 'Browser'].includes(body.platform) ? body.platform : 'Browser';
+                const device = {
+                    id,
+                    platform,
+                    registrationId,
+                    connectedAt: Date.now(),
+                    name: `${platform} · ${this.devices.size + 1}`,
+                    lastSeen: Date.now(),
+                    sequence: 0,
+                    token: randomBytes(32).toString('hex'),
+                    windowStart: Date.now(),
+                    count: 0,
+                };
+                this.devices.set(id, device);
+                reply(200, { id, token: device.token });
+                return;
+            }
+            const device = this.devices.get(body.id);
+            if (!device || req.headers['x-hb-log-token'] !== device.token) {
+                reply(403, {});
+                return;
+            }
+            if (!Array.isArray(body.logs) || body.logs.length > 50) {
+                reply(400, {});
+                return;
+            }
+            if (Date.now() - device.windowStart > 1000) {
+                device.windowStart = Date.now();
+                device.count = 0;
+            }
+            if (device.count + body.logs.length > 200) {
+                reply(429, {});
+                return;
+            }
+            device.count += body.logs.length;
+            device.lastSeen = Date.now();
+            if (body.sandboxResult && typeof body.sandboxResult === 'object') {
+                const result = body.sandboxResult;
+                const pending = this.sandboxRequests.get(result.requestId);
+                if (pending?.id === device.id) {
+                    const entries = Array.isArray(result.entries) ? result.entries.slice(0, 200).filter((entry) => entry && ['file', 'directory'].includes(entry.kind) && typeof entry.name === 'string' && entry.name.length <= 255 && !/[\\\\/\u0000-\u001f]/.test(entry.name) && !['.', '..'].includes(entry.name)).map((entry) => ({ name: entry.name, kind: entry.kind })) : [];
+                    pending.resolve({ deviceSessionId: device.id, requestId: pending.requestId, path: pending.path, timestamp: Date.now(), entries, error: result.error ? '设备不支持或无权读取此目录' : undefined, truncated: result.truncated === true });
+                }
+            }
+            for (const log of body.logs) {
+                if (!log || typeof log !== 'object')
+                    continue;
+                if (!Number.isSafeInteger(log.sequence) ||
+                    log.sequence <= device.sequence ||
+                    !Number.isFinite(log.timestamp) ||
+                    !['log', 'debug', 'info', 'warn', 'error'].includes(log.level) ||
+                    typeof log.message !== 'string')
+                    continue;
+                device.sequence = log.sequence;
+                this.logs.push({
+                    cursor: ++this.cursor,
+                    deviceSessionId: device.id,
+                    sequence: log.sequence,
+                    timestamp: log.timestamp,
+                    receivedAt: Date.now(),
+                    level: log.level,
+                    source: log.source === 'sdk' ? 'sdk' : 'app',
+                    message: sanitizeDiagnosticMessage(log.message)
+                        .replace(/(authorization|cookie|password|secret|token|pkey|api[_-]?key)(["'\s:=]+)([^\s,}]+)/gi, '$1$2[redacted]')
+                        .slice(0, 8192),
+                    truncated: log.truncated === true || log.message.length > 8192,
+                    ...(typeof log.method === 'string' ? { method: log.method.slice(0, 100) } : {}),
+                    ...(typeof log.callId === 'string' ? { callId: log.callId.slice(0, 100) } : {}),
+                    ...(typeof log.errorCode === 'string' && /^[A-Z0-9_]{1,100}$/.test(log.errorCode) ? { errorCode: log.errorCode } : {}),
+                    ...(log.outcome === 'success' || log.outcome === 'error' ? { outcome: log.outcome } : {}),
+                    ...(Number.isFinite(log.durationMs) ? { durationMs: Math.max(0, log.durationMs) } : {}),
+                });
+            }
+            if (this.logs.length > 5000)
+                this.logs.splice(0, this.logs.length - 5000);
+            reply(200, { sequence: device.sequence, sandboxRequest: [...this.sandboxRequests.values()].find(request => request.id === device.id) ? (() => { const request = [...this.sandboxRequests.values()].find(request => request.id === device.id); return { requestId: request.requestId, path: request.path }; })() : undefined });
+        }
+        catch {
+            reply(400, { code: 'INVALID_LOG_BATCH' });
+        }
+    }
+}
+/** 同源开发页面使用有界批量回传；传输失败不会递归写入 console。 */
+function deviceLogBootstrap(token) {
+    return `<script>(function(){if(window.__hb_sdk_device_logs_installed__)return;
+window.__hb_sdk_device_logs_installed__=true;
+window.__hb_sdk_mini_dev_console_installed__=true;
+var endpoint='${DEVICE_LOG_PATH}',credential='${token}',id='',queue=[],seq=0,busy=false,dropped=0;
+var registrationId=Array.from(crypto.getRandomValues(new Uint8Array(16)),function(n){return n.toString(16).padStart(2,'0')}).join('');
+var send=window.fetch.bind(window);
+var sandboxResult;
+function format(v){try{return typeof v==='string'?v:v instanceof Error?v.stack||v.message:JSON.stringify(v,function(k,value){return /authorization|cookie|password|secret|token|pkey|api.?key/i.test(k)?'[redacted]':value})}catch(e){return '[无法序列化]'}}function add(level,args,source){if(queue.length>=500){queue.shift();
+dropped++}var message=args.map(format).join(' ');
+message=message.replace(/https?:\\/\\/[^\\s]+/g,function(raw){try{var url=new URL(raw);
+url.username='';
+url.password='';
+url.search='';
+url.hash='';
+return url.href}catch(e){return '[URL]'}});
+message=message.replace(/(authorization|cookie|password|secret|token|pkey|api[_-]?key)([\\"'\\s:=]+)([^\\s,}]+)/gi,'$1$2[redacted]');
+queue.push({truncated:message.length>8192,sequence:++seq,timestamp:Date.now(),level:level,source:source||'app',message:message.slice(0,8192)})}window.__hbSdkDeviceLog=function(event){add(event.outcome==='error'?'error':'info',[event.method+' · '+event.outcome+' · '+event.durationMs+' ms'],'sdk');
+Object.assign(queue[queue.length-1],event)};
+['log','debug','info','warn','error'].forEach(function(level){var original=console[level];
+console[level]=function(){add(level,Array.prototype.slice.call(arguments));
+return original.apply(this,arguments)}});
+window.addEventListener('error',function(e){add('error',[e.message])});
+window.addEventListener('unhandledrejection',function(e){add('error',[e.reason])});
+async function flush(){if(busy)return;
+busy=true;
+try{if(!id){var ua=navigator.userAgent;
+var platform=window.name==='__hb_sdk_mini_dev__'?'Browser':/Android/i.test(ua)?'Android':/iPhone|iPad/i.test(ua)?'iOS':/Windows/i.test(ua)?'Windows':/Mac/i.test(ua)?'macOS':'Browser';
+var r=await send(endpoint,{method:'POST',headers:{'content-type':'application/json','x-hb-log-token':credential},body:JSON.stringify({register:true,platform:platform,registrationId:registrationId}),signal:AbortSignal.timeout(5000)});
+if(!r.ok)return;
+var d=await r.json();
+id=d.id;
+credential=d.token}if(dropped){add('warn',['日志缓冲已丢弃 '+dropped+' 条']);
+dropped=0}var batch=queue.slice(0,50);
+while(batch.length>1&&new TextEncoder().encode(JSON.stringify(batch)).length>48000)batch.pop();
+var result=await send(endpoint,{method:'POST',headers:{'content-type':'application/json','x-hb-log-token':credential},body:JSON.stringify({id:id,logs:batch,sandboxResult:sandboxResult}),signal:AbortSignal.timeout(5000)});
+if(result.ok){var ack=await result.json();sandboxResult=undefined;
+if(ack.sandboxRequest){try{var entries=await window.__hbSdkSandboxList(ack.sandboxRequest.path);sandboxResult={requestId:ack.sandboxRequest.requestId,entries:entries.slice(0,200),truncated:entries.length>200}}catch(e){sandboxResult={requestId:ack.sandboxRequest.requestId,error:true}}}
+queue=queue.filter(function(l){return l.sequence>ack.sequence})}}catch(e){}finally{busy=false}}setInterval(flush,1000);
+flush()})();
+</script>`;
 }
 
-var semverExports = requireSemver();
-
+/** 单个小程序版本最多声明的关联游戏数量。 */
 const MINIAPP_BIND_APP_IDS_MAX_COUNT = 20;
+/**
+ * 校验并规范化小程序关联的游戏 App ID。
+ *
+ * @param value - 不可信声明。`undefined` 和 `[]` 均返回空绑定；其他值必须是最多 20 项的
+ * 字符串数组，不接受 `null`、单个字符串、number 数组或类数组对象。
+ * @param options - 可选诊断来源；`sourceLabel` 默认 `package.json#heybox.bindAppIds`，并原样
+ * 作为所有错误消息的前缀。
+ * @returns 新建、按 appid 数值升序排列且经 `Object.freeze` 冻结的 `readonly string[]`。
+ * 输入数组及其顺序不会被修改；空输入也返回新的冻结空数组。
+ * @throws `Error` `${sourceLabel} 必须是字符串数组`：`value` 不是数组。
+ * @throws `Error` `${sourceLabel} 最多包含 20 个游戏 appid`：输入数组超过 20 项；数量检查
+ * 先于逐项格式检查。
+ * @throws `Error` `${sourceLabel} 包含非法游戏 appid：<value>`：任一项不是 string，或不匹配
+ * `/^[1-9]\d*$/`。因此空串、首尾空白、`0`、前导零、正负号、小数、指数和非十进制字符
+ * 都不会被自动修正。
+ * @throws `Error` `${sourceLabel} 包含超出正 int32 范围的游戏 appid：<value>`：十进制值
+ * 大于 `2147483647` 或不能成为安全整数。
+ * @throws `Error` `${sourceLabel} 包含重复游戏 appid：<value>`：规范字符串在同一数组重复。
+ *
+ * @remarks
+ * 合法范围是闭区间 `1..2147483647`，每项在输出中仍保持十进制 string。排序按数值而不是
+ * 字典序执行，所以 `['3513350', '730', '10']` 输出为 `['10', '730', '3513350']`。
+ * 函数先复制后排序并冻结结果，不排序或冻结调用方传入的数组。
+ *
+ * 这是同步、纯离线的格式规范化函数，不访问网络，也不确认 appid 是否真实存在、可绑定或
+ * 属于当前开发者。`miniappManifest()` 用它校验 `package.json#heybox.bindAppIds` 并把非空结果
+ * 写入 Manifest；远端 deploy 预检和提审才校验游戏可用性。缺失和空数组在普通构建中都表示
+ * 无绑定，函数本身不处理 `remote deploy --from-version` 的历史快照继承语义。
+ *
+ * `bindAppIds` 是版本发布元数据，不是 Runtime 权限，也不会因调用
+ * [navigation.openAppPage](/reference/sdk/navigation/openAppPage) 而变化。后者的 `appId` 是一次
+ * 页面导航参数，允许 string 或 number、只要求字符串化后非空，不适用本函数的数组、int32、
+ * 前导零、去重、20 项或排序规则。
+ *
+ * @example
+ * ```ts
+ * import { parseMiniappBindAppIds } from '@heybox/hb-sdk/miniapp-publish'
+ *
+ * const declared = ['3513350', '730', '10']
+ * const appIds = parseMiniappBindAppIds(declared)
+ *
+ * console.log(appIds) // ['10', '730', '3513350']
+ * console.log(declared) // ['3513350', '730', '10']，输入顺序不变
+ * console.log(Object.isFrozen(appIds)) // true
+ * ```
+ *
+ * @see [miniappManifest](/reference/symbols/vite/functions/miniappManifest)
+ * @see [navigation.openAppPage](/reference/sdk/navigation/openAppPage)
+ * @see [CLI 与远端发布](/guide/cli#生产构建)
+ */
 function parseMiniappBindAppIds(value, options = {}) {
     const sourceLabel = options.sourceLabel ?? 'package.json#heybox.bindAppIds';
     if (value === undefined)
@@ -3142,8 +3345,25 @@ function parseMiniappBindAppIds(value, options = {}) {
     return Object.freeze(appIds);
 }
 
+/**
+ * 所有小程序 iframe bridge envelope 共用的固定 namespace。
+ *
+ * @remarks 该值用于排除无关 `postMessage` 数据，不负责验证消息来源；接收方仍须校验 source 和 nonce，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
+/**
+ * 新消息默认发送的当前 bridge wire 版本。
+ *
+ * @remarks 接收 guard 为握手协商继续接受 v1 与 v2 envelope；cancel 与 operation progress 等 v2-only 消息仍必须使用 v2。
+ */
 const MINI_PROGRAM_MESSAGE_VERSION = 2;
+/**
+ * Runtime 在 iframe URL 中传递 bridge nonce 的 query 参数名。
+ *
+ * @remarks nonce 用于把消息关联到当前 iframe 实例，不是独立的身份认证凭据；接收方还必须校验 source，
+ * 并在 origin 可以固定且协议模式要求时校验 origin。
+ */
 const MINI_PROGRAM_BRIDGE_NONCE_PARAM = 'hb_mini_bridge_nonce';
 /** Companion alias 的跨构建、Runtime 与 Host 规范。 */
 const COMPANION_ALIAS_PATTERN = /^[a-z][a-z0-9-]{0,31}$/;
@@ -3359,6 +3579,11 @@ function isRecord$3(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/**
+ * `package.json#heybox.platforms` 接受的平台值，顺序同时是 Manifest 的规范化输出顺序。
+ *
+ * @remarks 项目仍应只声明实际完成适配并经过验收的平台；模板默认值不是自动兼容承诺。
+ */
 const MINIAPP_PLATFORM_VALUES = ['android', 'ios', 'ohos', 'windows', 'macos', 'linux'];
 /** 窗口尺寸字段的脏值兜底上限；真正的上限是宿主侧显示器 workArea。 */
 const MINIAPP_WINDOW_SIZE_MAX = 16_384;
@@ -3381,6 +3606,7 @@ function renderMiniappManifest(manifest) {
     const output = {
         version: manifest.version,
         sdkVersion: manifest.sdkVersion,
+        ...(manifest.name === undefined ? {} : { name: manifest.name, icon: manifest.icon, coverImages: manifest.coverImages }),
         platforms,
         ...(manifest.permissions === undefined ? {} : { permissions: manifest.permissions }),
         ...(manifest.companions === undefined ? {} : { companions: manifest.companions }),
@@ -12746,29 +12972,29 @@ function renderRuntimeGateScript() {
 function removePlatformGateNodes(node) {
     if (!('childNodes' in node))
         return;
-    node.childNodes = node.childNodes.filter(child => !('tagName' in child) || !hasAttr(child, RUNTIME_GATE_MARKER));
+    node.childNodes = node.childNodes.filter((child) => !('tagName' in child) || !hasAttr(child, RUNTIME_GATE_MARKER));
     for (const child of node.childNodes)
         removePlatformGateNodes(child);
 }
 function readAttr(element, name) {
-    return element.attrs.find(attr => attr.name.toLowerCase() === name)?.value;
+    return element.attrs.find((attr) => attr.name.toLowerCase() === name)?.value;
 }
 function hasAttr(element, name) {
     return readAttr(element, name) !== undefined;
 }
 function setAttr(element, name, value) {
-    const attr = element.attrs.find(item => item.name.toLowerCase() === name);
+    const attr = element.attrs.find((item) => item.name.toLowerCase() === name);
     if (attr)
         attr.value = value;
     else
         element.attrs.push({ name, value });
 }
 function removeAttr(element, name) {
-    element.attrs = element.attrs.filter(attr => attr.name.toLowerCase() !== name);
+    element.attrs = element.attrs.filter((attr) => attr.name.toLowerCase() !== name);
 }
 function findElement$1(node, tagName) {
     let found;
-    walk$1(node, element => {
+    walk$1(node, (element) => {
         if (!found && element.tagName === tagName)
             found = element;
     });
@@ -12787,10 +13013,7 @@ function walk$1(node, visit) {
 const FORBIDDEN_RESOURCE_HINTS = new Set(['dns-prefetch', 'preconnect', 'prerender']);
 const RELATIVE_URL_BASE = new URL('https://heybox-relative.invalid/');
 const OFFICIAL_RESOURCE_ROOT_DOMAINS = ['xiaoheihe.cn', 'max-c.com', 'debugmode.cn', 'maxjia.com'];
-const OFFICIAL_RESOURCE_SOURCES = OFFICIAL_RESOURCE_ROOT_DOMAINS.flatMap(rootDomain => [
-    `https://${rootDomain}`,
-    `https://*.${rootDomain}`,
-]);
+const OFFICIAL_RESOURCE_SOURCES = OFFICIAL_RESOURCE_ROOT_DOMAINS.flatMap((rootDomain) => [`https://${rootDomain}`, `https://*.${rootDomain}`]);
 const URL_ATTRIBUTES = {
     audio: ['src'],
     embed: ['src'],
@@ -12827,14 +13050,12 @@ function enforceMiniappHtmlPolicy(html, options = {}) {
         throw new Error('入口 index.html 必须包含 <head>');
     }
     removePlatformCspMarkers(document);
-    walk(document, element => validateElement(element));
+    walk(document, (element) => validateElement(element));
     injectMiniappRuntimeGate(document);
     if (options.skipPlatformCsp) {
         return serialize(document);
     }
-    const content = options.hmrWebSocketUrl
-        ? PRODUCTION_CSP.replace("connect-src 'none'", `connect-src ${options.hmrWebSocketUrl}`)
-        : PRODUCTION_CSP;
+    const content = options.hmrWebSocketUrl ? PRODUCTION_CSP.replace("connect-src 'none'", `connect-src ${options.hmrWebSocketUrl}`) : PRODUCTION_CSP;
     head.childNodes.unshift({
         nodeName: 'meta',
         tagName: 'meta',
@@ -12852,7 +13073,7 @@ function enforceMiniappHtmlPolicy(html, options = {}) {
 }
 function validateElement(element) {
     const tagName = element.tagName.toLowerCase();
-    const attrs = new Map(element.attrs.map(attr => [attr.name.toLowerCase(), attr.value]));
+    const attrs = new Map(element.attrs.map((attr) => [attr.name.toLowerCase(), attr.value]));
     if (tagName === 'meta' && attrs.get('http-equiv')?.toLowerCase() === 'refresh') {
         throw new Error('index.html 不允许 meta refresh');
     }
@@ -12864,7 +13085,7 @@ function validateElement(element) {
     }
     if (tagName === 'link') {
         const rels = (attrs.get('rel') ?? '').toLowerCase().split(/\s+/).filter(Boolean);
-        const forbidden = rels.find(rel => FORBIDDEN_RESOURCE_HINTS.has(rel));
+        const forbidden = rels.find((rel) => FORBIDDEN_RESOURCE_HINTS.has(rel));
         if (forbidden) {
             throw new Error(`index.html 不允许 rel="${forbidden}"`);
         }
@@ -12881,7 +13102,10 @@ function validateElement(element) {
     for (const attribute of URL_ATTRIBUTES[tagName] ?? []) {
         const value = attrs.get(attribute);
         if (attribute === 'srcset') {
-            for (const candidate of (value ?? '').split(',').map(item => item.trim().split(/\s+/)[0]).filter(Boolean)) {
+            for (const candidate of (value ?? '')
+                .split(',')
+                .map((item) => item.trim().split(/\s+/)[0])
+                .filter(Boolean)) {
                 validateResourceUrl(candidate, `<${tagName} ${attribute}>`, true, supportsOfficialResourceUrl(tagName, attribute));
             }
         }
@@ -12893,10 +13117,10 @@ function validateElement(element) {
 function removePlatformCspMarkers(node) {
     if (!('childNodes' in node))
         return;
-    node.childNodes = node.childNodes.filter(child => {
+    node.childNodes = node.childNodes.filter((child) => {
         if (!('tagName' in child))
             return true;
-        return !child.attrs.some(attr => attr.name.toLowerCase() === 'data-heybox-platform-csp');
+        return !child.attrs.some((attr) => attr.name.toLowerCase() === 'data-heybox-platform-csp');
     });
     for (const child of node.childNodes)
         removePlatformCspMarkers(child);
@@ -12932,7 +13156,7 @@ function isOfficialResourceUrl(value) {
         const hostname = url.hostname.toLowerCase();
         if (hostname.endsWith('.'))
             return false;
-        return OFFICIAL_RESOURCE_ROOT_DOMAINS.some(rootDomain => hostname === rootDomain || hostname.endsWith(`.${rootDomain}`));
+        return OFFICIAL_RESOURCE_ROOT_DOMAINS.some((rootDomain) => hostname === rootDomain || hostname.endsWith(`.${rootDomain}`));
     }
     catch {
         return false;
@@ -12957,7 +13181,7 @@ function isRelativeUrl(value, normalized) {
 }
 function findElement(node, tagName) {
     let found;
-    walk(node, element => {
+    walk(node, (element) => {
         if (!found && element.tagName === tagName)
             found = element;
     });
@@ -13022,7 +13246,19 @@ const DEV_ERROR_MESSAGE = 'Companion 开发资源暂时不可用';
 /** 与 Companion manifest 一致的单响应上限，避免本地调试入口被大体积声明撑爆。 */
 const DEV_MINI_PROGRAM_MANIFEST_MAX_BYTES = 1024 * 1024;
 const DEV_COMPANION_PATH_PATTERN = /^\/__hb_sdk__\/companions\/([a-z][a-z0-9-]{0,31})\/(windows-x64|macos-arm64)\.zip$/;
+/**
+ * `hb-sdk dev` 为本地 Companion 产物访问注入的进程环境变量名。
+ *
+ * @remarks
+ * 该变量由 CLI 管理，不是项目配置项。应用代码不应读取、设置、记录或转发它的值。
+ */
 const HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = 'HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN';
+/**
+ * `hb-sdk dev` 为本地小程序 Manifest 访问注入的进程环境变量名。
+ *
+ * @remarks
+ * 该变量由 CLI 管理，不是项目配置项。应用代码不应读取、设置、记录或转发它的值。
+ */
 const HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN_ENV = 'HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN';
 const devSnapshotStoreKey = Symbol.for('@heybox/hb-sdk/dev-companion-snapshots');
 const devSnapshotRegistry = globalThis;
@@ -13036,6 +13272,104 @@ if (!devSnapshotRegistry[devSnapshotStoreKey]) {
     });
 }
 const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
+/**
+ * 创建工坊小程序使用的 Vite 插件。
+ *
+ * @returns 可直接加入 Vite `plugins` 数组的
+ * [MiniappManifestPlugin](/reference/symbols/vite/interfaces/MiniappManifestPlugin)。插件固定名为
+ * `heybox-miniapp-manifest`，并提供 `config`、`configResolved`、`configureServer`、`buildEnd`、
+ * `transformIndexHtml`、`closeBundle` hooks；这些 hooks 由 Vite 调用，应用代码不应手动调用。
+ * @throws `Error` `config` 阶段发现 Vite `base` 不是 `''` 或 `'./'`，或无法解析当前 SDK 版本时抛出。
+ * @throws `Error` `configResolved` 阶段发现已解析插件列表中 `miniappManifest()` 数量不是一个时抛出。
+ * @throws `Error` HTML 缺少 `<head>`，包含 `meta refresh`、`<base>`、禁止的 resource hint，或资源 URL
+ * 不符合小程序 HTML 策略时，`transformIndexHtml` / 生产产物复检抛出。
+ * @throws `Error` 生产构建无法读取或解析最近的 `package.json`，`version`、`heybox.platforms`、
+ * `heybox.permissions`、`heybox.window`、`heybox.bindAppIds` 或 `heybox.companions` 声明非法时抛出。
+ * @throws `Error` 生产 `build.outDir` 缺少根 `index.html`、递归发现额外 HTML，或 Companion 权限、
+ * 目标平台、来源目录、归档结构、入口二进制不符合约束时抛出；更早的 Rollup/Vite 错误会原样优先重抛。
+ *
+ * @remarks
+ * 该函数必须从 `@heybox/hb-sdk/vite` 导入，在 `vite.config.ts` 中无参调用且只注册一次；它不是
+ * iframe 业务代码 API，也没有 options 对象。小程序声明统一来自从 Vite `root` 向上找到的最近一个
+ * `package.json`，插件只读取和规范化，不会改写源文件：
+ *
+ * - `version`：发布版本；trim 后必须是完整 SemVer，可含 prerelease，不允许 build metadata 或模板值
+ *   `0.0.0`；
+ * - `heybox.platforms`：项目实际承诺适配的非空、无重复平台 allowlist；输出按平台词表规范排序；
+ * - `heybox.permissions`：严格权限对象；未知权限/字段或错误类型会失败，`enabled: false` 项不写入
+ *   Manifest。旧版本缺失声明时可能警告，新硬切版本会失败；
+ * - `heybox.window`：可选的新 PC 开窗初值、最小尺寸和 `resizable` 声明；省略时不写该字段；
+ * - `heybox.bindAppIds`：可选的最多 20 个正 int32 字符串 App ID；校验、去重并按数值排序，空数组
+ *   在本地产物中等同不写；
+ * - `heybox.companions`：可选的受管桌面程序声明；`source` 相对上述 `package.json` 所在目录解析，
+ *   必须同时声明启用的 `companion` 权限和匹配的 Windows/macOS 目标平台。
+ *
+ * 产物中的 `sdkVersion` 来自当前实际安装的 `@heybox/hb-sdk`，不是项目可配置字段。Vite options、页面
+ * 代码和普通环境变量不能覆盖上述 package 声明；插件也不会联网确认 App ID、平台批准或远端版本状态。
+ *
+ * Hook 行为如下：
+ *
+ * - `config`：省略 `base` 时补为 `'./'`，显式值只接受 `''` / `'./'`；注入 SDK 构建版本，且仅
+ *   `vite serve` 注入开发日志编译常量；
+ * - `configResolved`：确认插件唯一性，记录真实 `root`、`build.outDir`、`serve|build` 命令和精确 HMR
+ *   WebSocket 地址；直接 `vite build` 使用该实际 `outDir`，`hb-sdk build` 则由 CLI 固定为 `dist/`；
+ * - `configureServer`：为 `hb-sdk dev` 注册设备日志、本地小程序 Manifest 与 Companion Manifest/ZIP
+ *   中间件；敏感路由只接受数值 loopback socket/Host、`GET|HEAD` 和 CLI 注入的独立短期令牌，快照在
+ *   配置重载时按 digest 保留，并在服务真正关闭时清理；
+ * - `transformIndexHtml`：校验 HTML URL/标签策略，注入 Runtime Gate；默认注入平台 CSP，serve 时
+ *   `connect-src` 只开放解析出的 HMR WebSocket，并额外注入调试日志 bootstrap；
+ * - `buildEnd`：记住更早的 Rollup/Vite 错误，避免 `closeBundle` 的二次产物错误遮盖根因；
+ * - `closeBundle`：serve 时直接完成；build 时复检最终 HTML，要求整个输出树只有根 `index.html`，再于
+ *   `build.outDir` 写入 `manifest.json`，并把 Companion 目录打包成
+ *   `companions/<alias>/<target>.zip`，记录 size、SHA-256、固定入口与 args。
+ *
+ * HTML 策略会隔离业务 script/modulepreload，直到父 Runtime Gate 以 namespace、版本、nonce、source
+ * 以及 referrer 可确定时的 origin 完成探测；失败时显示只能在小黑盒 App 内打开的安全页。策略拒绝自动跳转、`<base>`、危险
+ * resource hints 和不受支持的外部 URL，并按标签只允许相对 URL、明确允许的 `data:` / `blob:` 或
+ * 小黑盒官方 HTTPS 资源。开发者自行提供的 CSP 会保留；插件管理的 CSP marker 可重复转换而不会叠加。
+ *
+ * 平台 CSP 默认始终保留，直接 `vite build` / `hb-sdk build` 不会因项目声明
+ * `heybox.permissions.network.useOfficialDomain` 而跳过。只有官方 `hb-sdk dev` 或
+ * `hb-sdk remote deploy` 将当前版本的 `network` 声明与远端批准结果求交并确认最终启用后，才会
+ * 建立 verified 上下文供插件读取内部
+ * `HB_SDK_RUNTIME_PERMISSION_CONTEXT` + `HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN` 组合跳过平台 CSP；单独设置
+ * 任一值无效。0.8 兼容期对完全缺失权限声明的项目仍按迁移规则处理；`useOfficialDomain` 不参与
+ * CSP 跳过决定。Runtime Gate、HTML 校验和 Manifest 生成始终保留。
+ *
+ * `HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN`、`HB_SDK_MINI_PROGRAM_MANIFEST_ACCESS_TOKEN`、
+ * `HB_SDK_SKIP_COMPANIONS` 以及上述 CSP 上下文均是 CLI/发布链路内部开关，不是项目配置项。它们在
+ * 插件创建时捕获；开发服务配置重载只会从同一服务的内存快照恢复 CLI 令牌。业务代码和 Vite 配置
+ * 不应手工设置、读取、记录或转发令牌值。正式声明必须继续写在 `package.json#heybox`，内部环境变量
+ * 不能替代声明校验。
+ *
+ * `manifest.json` 是 release pipeline 元数据，不是部署后供页面 fetch 的 CDN 资源。发布链路使用
+ * [isValidVersion](/reference/symbols/miniapp-publish/functions/isValidVersion) 复核版本、
+ * [resolveMiniappManifestPlatforms](/reference/symbols/miniapp-publish/functions/resolveMiniappManifestPlatforms)
+ * 解析平台硬切规则、
+ * [parseMiniappBindAppIds](/reference/symbols/miniapp-publish/functions/parseMiniappBindAppIds) 复核游戏绑定，
+ * 并通过 [shouldUploadDistFile](/reference/symbols/miniapp-publish/functions/shouldUploadDistFile) 将根
+ * `manifest.json` 排除出普通 CDN 文件。Web/Companion 上传预算由
+ * [validateUploadTotalSize](/reference/symbols/miniapp-publish/functions/validateUploadTotalSize) 等发布 helper
+ * 独立校验，不能用插件成功代替 deploy 预检。
+ *
+ * @example
+ * ```ts
+ * import vue from '@vitejs/plugin-vue'
+ * import { miniappManifest } from '@heybox/hb-sdk/vite'
+ * import { defineConfig } from 'vite'
+ *
+ * export default defineConfig({
+ *   // base 省略时 miniappManifest() 会补为 './'
+ *   plugins: [vue(), miniappManifest()],
+ * })
+ * ```
+ *
+ * @see [MiniappManifestPlugin](/reference/symbols/vite/interfaces/MiniappManifestPlugin) 返回插件及各 hook 类型。
+ * @see [安装](/guide/installation) Vite 接入、相对资源路径和构建命令。
+ * @see [权限声明](/guide/permissions) `heybox.permissions` 严格 schema 与迁移规则。
+ * @see [窗口尺寸与可缩放性](/guide/window-size) `heybox.window` 字段与 Host 消费语义。
+ * @see [受管桌面程序](/guide/companion) Companion 声明、归档和本地联调边界。
+ */
 function miniappManifest() {
     const includeCompanions = process.env.HB_SDK_SKIP_COMPANIONS !== '1';
     const deviceLogs = new DeviceLogStore();
@@ -13354,10 +13688,12 @@ function miniappManifest() {
                 throw new Error('构建产物必须包含入口 dist/index.html');
             }
             writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(readFileSync(indexHtmlPath, 'utf8'), { skipPlatformCsp }));
+            const basicInfo = await prepareMiniappBasicInfo(companionConfig.projectRoot, outputRoot, sdkVersion);
             const manifestPath = path.join(outputRoot, 'manifest.json');
             const companions = prepareMiniappCompanions(companionDeclarations, { root: companionConfig.projectRoot, outputRoot, platforms });
             mkdirSync(path.dirname(manifestPath), { recursive: true });
             writeFileSync(manifestPath, renderMiniappManifest({
+                ...basicInfo,
                 version,
                 sdkVersion,
                 platforms,