@heybox/hb-sdk 0.8.0 → 0.8.1-alpha.10

package/dist/vite.esm.js

@@ -1,11 +1,14 @@
-import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+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 path from 'node:path';
+import { inflateRawSync } from 'node:zlib';
 import { AsyncLocalStorage } from 'node:async_hooks';
 
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.8.0';
+    : '0.8.1-alpha.10';
 
 /**
  * iframe 与调试台页面的开发期 console 捕获转发。
@@ -25,11 +28,306 @@ const HB_SDK_VERSION = typeof undefined === 'string'
  * 调试台页面自身（runtime 跑在这里，`[hb-sdk-runtime]` 日志不经过 iframe）另用
  * `installMiniDevConsoleSelfCapture` 接入「日志」页签（source: 'host'）。
  */
-const MINI_DEV_IFRAME_WINDOW_NAME = '__hb_sdk_mini_dev__';
 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 re = {exports: {}};
 
 var constants;
@@ -2818,6 +3116,8 @@ var semverExports = requireSemver();
 const MINI_PROGRAM_MESSAGE_NAMESPACE = 'heybox:miniprogram';
 const MINI_PROGRAM_MESSAGE_VERSION = 2;
 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}$/;
 
 const MINI_PROGRAM_PERMISSION_KEYS = [
     'userInfo',
@@ -2828,6 +3128,7 @@ const MINI_PROGRAM_PERMISSION_KEYS = [
     'clipboard',
     'leaderboard',
     'network',
+    'companion',
 ];
 const MINI_PROGRAM_PERMISSION_CATALOG = [
     {
@@ -2940,6 +3241,29 @@ const MINI_PROGRAM_PERMISSION_CATALOG = [
         methods: ['network.request', 'network.download'],
         conditions: ['声明后仍需平台批准，并继续执行网络安全策略。'],
     },
+    {
+        key: 'companion',
+        name: '桌面辅助应用',
+        description: '下载、准备并运行随当前小程序版本发布的受管桌面程序。',
+        access: 'platform-approval',
+        risk: 'high',
+        config: {},
+        methods: [
+            'companion.getInfo',
+            'companion.getPreparationStatus',
+            'companion.prepare',
+            'companion.cancelPreparation',
+            'companion.getActiveSession',
+            'companion.launch',
+            'companion.session.write',
+            'companion.session.closeStdin',
+            'companion.session.terminate',
+            'companion.session.ackOutput',
+            'companion.openAttachment',
+            'companion.showNotification',
+        ],
+        conditions: ['声明后仍需平台批准，并继续执行可信用户手势、Host 能力和当前版本 Manifest 校验。'],
+    },
 ];
 new Set(MINI_PROGRAM_PERMISSION_KEYS);
 
@@ -2954,7 +3278,7 @@ function parseMiniappPermissions(value, options) {
         }
         return { declared: false };
     }
-    if (!isRecord$1(value)) {
+    if (!isRecord$2(value)) {
         throw new Error(`${sourceLabel} 必须是 JSON 对象`);
     }
     const knownKeys = new Set(MINIAPP_PERMISSION_KEYS);
@@ -2968,7 +3292,7 @@ function parseMiniappPermissions(value, options) {
             continue;
         const declaration = value[key];
         const itemLabel = `${sourceLabel}.${key}`;
-        if (!isRecord$1(declaration))
+        if (!isRecord$2(declaration))
             throw new Error(`${itemLabel} 必须是 JSON 对象`);
         const definition = MINI_PROGRAM_PERMISSION_CATALOG.find((item) => item.key === key);
         if (!definition)
@@ -3002,7 +3326,7 @@ function requiresExplicitPermissions(sdkVersion) {
 function getMissingPermissionsWarning(sourceLabel = 'package.json#heybox.permissions') {
     return `${sourceLabel} 尚未声明。当前按 0.8 兼容行为构建；0.9.0 起将拒绝构建，请尽快补充权限声明（无权限需求时配置 {}）。`;
 }
-function isRecord$1(value) {
+function isRecord$2(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
@@ -3024,6 +3348,7 @@ function renderMiniappManifest(manifest) {
         sdkVersion: manifest.sdkVersion,
         platforms,
         ...(manifest.permissions === undefined ? {} : { permissions: manifest.permissions }),
+        ...(manifest.companions === undefined ? {} : { companions: manifest.companions }),
     };
     return `${JSON.stringify(output, null, 2)}\n`;
 }
@@ -3082,14 +3407,30 @@ function findNearestPackageJsonPath(startDir) {
 function readMiniappVersionFromPackageJson(root) {
     return readMiniappPackageJson(root, true).version;
 }
+/** Companion source 始终相对声明所在 package.json，而非 Vite 的 HTML root。 */
+function readMiniappCompanionsFromPackageJson(root) {
+    const { packageJson, packageJsonPath } = readMiniappPackageJson(root, false);
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    const declarations = heybox?.companions;
+    if (declarations !== undefined && (!isRecord$1(declarations) || Object.keys(declarations).length === 0)) {
+        throw new Error('package.json#heybox.companions 必须是非空对象');
+    }
+    return {
+        declarations: declarations,
+        projectRoot: path.dirname(packageJsonPath),
+        packageJsonPath,
+    };
+}
+function readMiniappPlatformsFromPackageJson(root) {
+    const { packageJson } = readMiniappPackageJson(root, false);
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    return validateMiniappPlatforms(heybox?.platforms, 'package.json#heybox.platforms');
+}
 function readMiniappPermissionsFromPackageJson(root, sdkVersion) {
     const { packageJson } = readMiniappPackageJson(root, false);
-    const heybox = packageJson.heybox;
-    if (heybox !== undefined && !isRecord(heybox)) {
-        throw new Error('@heybox/hb-sdk 提示：package.json#heybox 必须是 JSON 对象');
-    }
-    const present = isRecord(heybox) && Object.prototype.hasOwnProperty.call(heybox, 'permissions');
-    return parseMiniappPermissions(isRecord(heybox) ? heybox.permissions : undefined, {
+    const heybox = readMiniappHeyboxConfig(packageJson);
+    const present = heybox !== undefined && Object.prototype.hasOwnProperty.call(heybox, 'permissions');
+    return parseMiniappPermissions(heybox?.permissions, {
         present,
         sdkVersion,
     });
@@ -3113,9 +3454,17 @@ function readMiniappPackageJson(root, requireVersion) {
     if (requireVersion && (typeof packageJson.version !== 'string' || packageJson.version.trim() === '')) {
         throw new Error('@heybox/hb-sdk 提示：package.json.version 必须是非空字符串');
     }
-    return { packageJson, version: typeof packageJson.version === 'string' ? packageJson.version.trim() : '' };
+    return { packageJson, packageJsonPath, version: typeof packageJson.version === 'string' ? packageJson.version.trim() : '' };
 }
-function isRecord(value) {
+function readMiniappHeyboxConfig(packageJson) {
+    if (packageJson.heybox === undefined)
+        return undefined;
+    if (!isRecord$1(packageJson.heybox)) {
+        throw new Error('@heybox/hb-sdk 提示：package.json#heybox 必须是 JSON 对象');
+    }
+    return packageJson.heybox;
+}
+function isRecord$1(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 function formatReason(error) {
@@ -3125,6 +3474,646 @@ function formatReason(error) {
     return String(error);
 }
 
+/** 检查原生入口的文件格式与目标架构；文件后缀和执行位不能代替此门禁。 */
+function assertCompanionExecutable(bytes, target) {
+    const fail = () => { throw new Error('Companion 入口必须是目标架构的原生可执行文件，禁止脚本或损坏的二进制'); };
+    if (target === 'windows-x64') {
+        if (bytes.length < 64 || bytes.readUInt16LE(0) !== 0x5a4d)
+            fail();
+        const pe = bytes.readUInt32LE(60);
+        if (pe < 64 || pe > bytes.length - 24 || bytes.readUInt32LE(pe) !== 0x00004550
+            || bytes.readUInt16LE(pe + 4) !== 0x8664)
+            fail();
+        const optionalSize = bytes.readUInt16LE(pe + 20);
+        const characteristics = bytes.readUInt16LE(pe + 22);
+        if (optionalSize < 112 || pe + 24 + optionalSize > bytes.length
+            || bytes.readUInt16LE(pe + 24) !== 0x20b || !(characteristics & 2) || (characteristics & 0x2000))
+            fail();
+        return;
+    }
+    const thin = (slice) => {
+        if (slice.length < 32)
+            return false;
+        const magic = slice.readUInt32LE(0);
+        if (magic !== 0xfeedfacf && magic !== 0xcffaedfe)
+            return false;
+        const read = (offset) => magic === 0xfeedfacf ? slice.readUInt32LE(offset) : slice.readUInt32BE(offset);
+        return read(4) === 0x0100000c && read(12) === 2 && read(20) <= slice.length - 32;
+    };
+    if (thin(bytes))
+        return;
+    if (bytes.length < 8)
+        fail();
+    const magic = bytes.readUInt32BE(0);
+    if (![0xcafebabe, 0xbebafeca, 0xcafebabf, 0xbfbafeca].includes(magic))
+        fail();
+    const little = magic === 0xbebafeca || magic === 0xbfbafeca;
+    const wide = magic === 0xcafebabf || magic === 0xbfbafeca;
+    const read = (offset) => little ? bytes.readUInt32LE(offset) : bytes.readUInt32BE(offset);
+    const count = read(4);
+    const stride = wide ? 32 : 20;
+    if (!count || count > 64 || 8 + count * stride > bytes.length)
+        fail();
+    let arm64 = false;
+    const ranges = [];
+    for (let i = 0; i < count; i++) {
+        const record = 8 + i * stride;
+        const integer = (offset) => {
+            if (!wide)
+                return read(offset);
+            const value = little ? bytes.readBigUInt64LE(offset) : bytes.readBigUInt64BE(offset);
+            return value <= BigInt(Number.MAX_SAFE_INTEGER) ? Number(value) : -1;
+        };
+        const offset = integer(record + 8);
+        const size = integer(record + (wide ? 16 : 12));
+        if (offset < 8 + count * stride || size < 1 || offset > bytes.length - size
+            || ranges.some(([start, end]) => offset < end && offset + size > start))
+            fail();
+        ranges.push([offset, offset + size]);
+        if (read(record) === 0x0100000c) {
+            if (!thin(bytes.subarray(offset, offset + size)))
+                fail();
+            arm64 = true;
+        }
+    }
+    if (!arm64)
+        fail();
+}
+/** 只解析 bundle 主字典的 CFBundleExecutable，兼容 XML 与 binary plist。 */
+function companionBundleExecutable(plist) {
+    let name;
+    if (plist.subarray(0, 8).toString() === 'bplist00') {
+        if (plist.length < 40)
+            throw new Error('Companion Info.plist 损坏');
+        const trailer = plist.length - 32;
+        const offsetSize = plist[trailer + 6];
+        const refSize = plist[trailer + 7];
+        const integer = (offset, size) => {
+            if (size < 1 || size > 8 || offset < 0 || offset + size > plist.length)
+                throw new Error('Companion Info.plist 损坏');
+            let value = 0;
+            for (let i = 0; i < size; i++)
+                value = value * 256 + plist[offset + i];
+            if (!Number.isSafeInteger(value))
+                throw new Error('Companion Info.plist 过大');
+            return value;
+        };
+        const u64 = (offset) => {
+            const value = plist.readBigUInt64BE(offset);
+            if (value > BigInt(Number.MAX_SAFE_INTEGER))
+                throw new Error('Companion Info.plist 过大');
+            return Number(value);
+        };
+        const count = u64(trailer + 8), top = u64(trailer + 16), table = u64(trailer + 24);
+        if (count > 10000 || top >= count || table < 8 || table + count * offsetSize > trailer)
+            throw new Error('Companion Info.plist 损坏');
+        const object = (ref) => {
+            if (ref >= count)
+                throw new Error('Companion Info.plist 损坏');
+            const offset = integer(table + ref * offsetSize, offsetSize);
+            if (offset < 8 || offset >= table)
+                throw new Error('Companion Info.plist 损坏');
+            const type = plist[offset] >> 4;
+            let length = plist[offset] & 15, data = offset + 1;
+            if (length === 15) {
+                const marker = plist[data++];
+                if ((marker >> 4) !== 1)
+                    throw new Error('Companion Info.plist 损坏');
+                const size = 2 ** (marker & 15);
+                length = integer(data, size);
+                data += size;
+            }
+            if (length > 10000 || data + length * (type === 13 ? refSize * 2 : type === 6 ? 2 : 1) > table)
+                throw new Error('Companion Info.plist 损坏');
+            return { type, length, data };
+        };
+        const string = (ref) => {
+            const item = object(ref);
+            if (item.type === 5)
+                return plist.subarray(item.data, item.data + item.length).toString('ascii');
+            if (item.type === 6)
+                return Buffer.from(plist.subarray(item.data, item.data + item.length * 2)).swap16().toString('utf16le');
+            return undefined;
+        };
+        const root = object(top);
+        if (root.type !== 13)
+            throw new Error('Companion Info.plist 必须是字典');
+        for (let i = 0; i < root.length; i++) {
+            if (string(integer(root.data + i * refSize, refSize)) === 'CFBundleExecutable') {
+                if (name !== undefined)
+                    throw new Error('Companion Info.plist 含重复入口');
+                name = string(integer(root.data + (root.length + i) * refSize, refSize));
+            }
+        }
+    }
+    else {
+        const xml = plist.toString('utf8').replace(/<!--[\s\S]*?-->/g, '');
+        const matches = [...xml.matchAll(/<key>\s*CFBundleExecutable\s*<\/key>\s*<string>([^<]*)<\/string>/g)];
+        if (matches.length === 1)
+            name = matches[0][1];
+    }
+    if (typeof name !== 'string' || !/^[^/\\\u0000-\u001f\u007f&]{1,255}$/.test(name) || name === '.' || name === '..')
+        throw new Error('Companion Info.plist 缺少安全的 CFBundleExecutable');
+    return name;
+}
+
+const MAX_BYTES = 2 * 1024 * 1024 * 1024;
+const MAX_ENTRIES = 10_000;
+/** 双次读取校验输入稳定性；保留 .app 安全链接以避免破坏签名。 */
+function packCompanionDirectory(root, label) {
+    root = realpathSync(root);
+    const first = snapshot(root, label);
+    let second;
+    try {
+        second = snapshot(root, label);
+    }
+    catch (cause) {
+        throw new Error(`${label}.source 产物读取期间发生变化，请等待编译完成后重试`, { cause });
+    }
+    if (first.fingerprint !== second.fingerprint)
+        throw new Error(`${label}.source 产物读取期间发生变化，请等待编译完成后重试`);
+    return zip(first.entries);
+}
+function snapshot(root, label) {
+    const entries = [];
+    const hash = createHash('sha256');
+    let total = 0;
+    const inside = (candidate) => {
+        const relative = path.relative(root, candidate);
+        return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+    };
+    const checked = new Set();
+    function checkCycles(diskPath, active) {
+        if (active.size > 128)
+            throw new Error(`${label}.source 目录层级过深`);
+        const real = realpathSync(diskPath);
+        if (!inside(real))
+            throw new Error(`${label}.source 符号链接逃逸产物目录`);
+        if (active.has(real))
+            throw new Error(`${label}.source 包含循环符号链接`);
+        if (checked.has(real))
+            return;
+        if (checked.size >= MAX_ENTRIES)
+            throw new Error(`${label}.source 文件数超限`);
+        if (lstatSync(real).isDirectory()) {
+            const next = new Set(active).add(real);
+            for (const child of readdirSync(real).sort())
+                checkCycles(path.join(real, child), next);
+        }
+        checked.add(real);
+    }
+    checkCycles(root, new Set());
+    function visit(diskPath, name, ancestors) {
+        const stat = lstatSync(diskPath);
+        hash.update(JSON.stringify([name, stat.dev, stat.ino, stat.size, stat.mtimeMs, stat.ctimeMs, stat.mode]));
+        if (stat.isSymbolicLink()) {
+            const link = readlinkSync(diskPath);
+            const parts = name.split('/');
+            const bundleIndex = parts.findIndex(segment => segment.endsWith('.app'));
+            if (bundleIndex < 0 || !link || /[\u0000-\u001f\u007f]/.test(link) || path.isAbsolute(link) || link.includes('\\') || /^[A-Za-z]:/.test(link)) {
+                throw new Error(`${label}.source 仅允许 .app 内部的相对符号链接`);
+            }
+            const resolvedLink = realpathSync(diskPath);
+            const bundle = path.join(root, ...parts.slice(0, bundleIndex + 1));
+            const lexicalLink = path.relative(bundle, path.resolve(path.dirname(diskPath), link));
+            const relativeLink = path.relative(bundle, resolvedLink);
+            if ([lexicalLink, relativeLink].some(relative => relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)))
+                throw new Error(`${label}.source 符号链接逃逸产物目录`);
+            if (ancestors.has(resolvedLink))
+                throw new Error(`${label}.source 包含循环符号链接`);
+            const targetStat = lstatSync(resolvedLink);
+            if (!targetStat.isDirectory() && !targetStat.isFile())
+                throw new Error(`${label}.source 不允许特殊文件`);
+            if (entries.length >= MAX_ENTRIES)
+                throw new Error(`${label}.source 文件数超限`);
+            hash.update(link);
+            entries.push({ name, bytes: Buffer.from(link), directory: false, executable: false, symlink: true });
+            return;
+        }
+        const real = realpathSync(diskPath);
+        if (!inside(real))
+            throw new Error(`${label}.source 符号链接逃逸产物目录`);
+        if (ancestors.has(real))
+            throw new Error(`${label}.source 包含循环符号链接`);
+        const resolved = lstatSync(real);
+        if (!resolved.isDirectory() && !resolved.isFile())
+            throw new Error(`${label}.source 不允许特殊文件`);
+        if (name) {
+            if (entries.length >= MAX_ENTRIES)
+                throw new Error(`${label}.source 文件数超限`);
+            if (resolved.isFile() && (total += resolved.size) > MAX_BYTES)
+                throw new Error(`${label}.source 文件大小预算超限`);
+            const bytes = resolved.isFile() ? readFileSync(real) : Buffer.alloc(0);
+            hash.update(bytes);
+            entries.push({ name, bytes, directory: resolved.isDirectory(), executable: (resolved.mode & 0o111) !== 0 });
+        }
+        if (resolved.isDirectory()) {
+            const next = new Set(ancestors).add(real);
+            for (const child of readdirSync(real).sort())
+                visit(path.join(real, child), name ? `${name}/${child}` : child, next);
+        }
+    }
+    visit(root, '', new Set());
+    return { entries, fingerprint: hash.digest('hex') };
+}
+const CRC_TABLE = Array.from({ length: 256 }, (_, value) => {
+    let crc = value;
+    for (let bit = 0; bit < 8; bit++)
+        crc = (crc >>> 1) ^ ((crc & 1) ? 0xedb88320 : 0);
+    return crc >>> 0;
+});
+function crc32(bytes) {
+    let crc = 0xffffffff;
+    for (const byte of bytes) {
+        crc = (crc >>> 8) ^ CRC_TABLE[(crc ^ byte) & 0xff];
+    }
+    return (crc ^ 0xffffffff) >>> 0;
+}
+/** 使用 ZIP store 避免不同压缩器版本改变摘要，也避免高压缩率资源触发解压预算门禁。 */
+function zip(entries) {
+    const locals = [];
+    const records = [];
+    let offset = 0;
+    for (const entry of entries) {
+        const name = Buffer.from(entry.name + (entry.directory ? '/' : ''));
+        if (name.length > 65535)
+            throw new Error('Companion 产物路径过长');
+        const crc = crc32(entry.bytes);
+        const local = Buffer.alloc(30 + name.length);
+        local.writeUInt32LE(0x04034b50);
+        local.writeUInt16LE(20, 4);
+        local.writeUInt16LE(0x800, 6);
+        local.writeUInt16LE(33, 12);
+        local.writeUInt32LE(crc, 14);
+        local.writeUInt32LE(entry.bytes.length, 18);
+        local.writeUInt32LE(entry.bytes.length, 22);
+        local.writeUInt16LE(name.length, 26);
+        name.copy(local, 30);
+        const record = Buffer.alloc(46 + name.length);
+        record.writeUInt32LE(0x02014b50);
+        record.writeUInt16LE(0x314, 4);
+        record.writeUInt16LE(20, 6);
+        record.writeUInt16LE(0x800, 8);
+        record.writeUInt16LE(33, 14);
+        record.writeUInt32LE(crc, 16);
+        record.writeUInt32LE(entry.bytes.length, 20);
+        record.writeUInt32LE(entry.bytes.length, 24);
+        record.writeUInt16LE(name.length, 28);
+        const mode = entry.symlink ? 0o120777 : entry.directory ? 0o040755 : entry.executable ? 0o100755 : 0o100644;
+        record.writeUInt32LE((mode * 65536) >>> 0, 38);
+        record.writeUInt32LE(offset, 42);
+        name.copy(record, 46);
+        locals.push(local, entry.bytes);
+        records.push(record);
+        offset += local.length + entry.bytes.length;
+    }
+    const central = Buffer.concat(records);
+    const end = Buffer.alloc(22);
+    end.writeUInt32LE(0x06054b50);
+    end.writeUInt16LE(entries.length, 8);
+    end.writeUInt16LE(entries.length, 10);
+    end.writeUInt32LE(central.length, 12);
+    end.writeUInt32LE(offset, 16);
+    return Buffer.concat([...locals, central, end]);
+}
+
+const MINIAPP_COMPANION_TARGETS = ['windows-x64', 'macos-arm64'];
+const MINIAPP_COMPANION_CAPABILITIES = ['stdio', 'attachments', 'notifications'];
+
+const MAX_ENTRY_COUNT = 10_000;
+const MAX_UNCOMPRESSED_BYTES = 2 * 1024 * 1024 * 1024;
+const MAX_COMPRESSION_RATIO = 200;
+const MAX_DISPLAY_NAME_CODE_POINTS = 120;
+const MAX_ARG_COUNT = 64;
+const MAX_ARG_BYTES = 1024;
+const MAX_ARGS_TOTAL_BYTES = 16_384;
+function prepareMiniappCompanions(declarations, options) {
+    if (declarations === undefined)
+        return undefined;
+    if (!isRecord(declarations) || Object.keys(declarations).length === 0) {
+        throw new Error('package.json#heybox.companions 必须是非空对象');
+    }
+    const output = {};
+    for (const alias of Object.keys(declarations).sort()) {
+        if (!COMPANION_ALIAS_PATTERN.test(alias))
+            throw new Error(`Companion alias 不合法：${alias}`);
+        const definition = declarations[alias];
+        assertExactKeys(definition, ['displayName', 'capabilities', 'targets'], `companions.${alias}`);
+        if (typeof definition.displayName !== 'string' || !definition.displayName.trim()) {
+            throw new Error(`companions.${alias}.displayName 必须是非空字符串`);
+        }
+        if (Array.from(definition.displayName.trim()).length > MAX_DISPLAY_NAME_CODE_POINTS) {
+            throw new Error(`companions.${alias}.displayName 最多允许 ${MAX_DISPLAY_NAME_CODE_POINTS} 个 Unicode 字符`);
+        }
+        const capabilities = validateCapabilities(definition.capabilities, alias);
+        if (!isRecord(definition.targets) || Object.keys(definition.targets).length === 0) {
+            throw new Error(`companions.${alias}.targets 必须是非空对象`);
+        }
+        const targets = {};
+        for (const targetName of Object.keys(definition.targets).sort()) {
+            if (!MINIAPP_COMPANION_TARGETS.includes(targetName)) {
+                throw new Error(`companions.${alias}.targets 包含不支持的平台：${targetName}`);
+            }
+            const platform = targetName.startsWith('windows-') ? 'windows' : 'macos';
+            if (options.platforms && !options.platforms.includes(platform)) {
+                throw new Error(`companions.${alias}.targets.${targetName} 未包含在 package.json#heybox.platforms 中`);
+            }
+            const target = definition.targets[targetName];
+            if (!target)
+                continue;
+            if (options.targets && !options.targets.includes(targetName))
+                continue;
+            targets[targetName] = prepareTarget(alias, targetName, target, options);
+        }
+        if (!options.targets || Object.keys(targets).length)
+            output[alias] = { displayName: definition.displayName.trim(), capabilities, targets };
+    }
+    return options.targets && Object.keys(output).length === 0 ? undefined : output;
+}
+function prepareTarget(alias, targetName, target, options) {
+    const label = `companions.${alias}.targets.${targetName}`;
+    assertExactKeys(target, ['source', 'entrypoint', 'elevation', 'args'], label);
+    if (typeof target.source !== 'string' || !target.source.trim())
+        throw new Error(`${label}.source 必须是非空字符串`);
+    if (!isRecord(target.entrypoint))
+        throw new Error(`${label}.entrypoint 必须是对象`);
+    assertExactKeys(target.entrypoint, ['kind', 'path'], `${label}.entrypoint`);
+    const entrypointPath = validateArchivePath(target.entrypoint.path, `${label}.entrypoint.path`);
+    validateEntrypoint(targetName, target.entrypoint.kind, entrypointPath, label);
+    const elevation = target.elevation ?? 'none';
+    if (elevation !== 'none')
+        throw new Error(`${label}.elevation V1 仅支持 none，暂不支持管理员权限启动`);
+    const args = validateArgs(target.args, label);
+    const projectRoot = realpathSync(options.root);
+    const outputRoot = resolveRealPathIfPresent(options.outputRoot);
+    const sourcePath = path.resolve(projectRoot, target.source);
+    if (!isPathInside(projectRoot, sourcePath))
+        throw new Error(`${label}.source 必须位于项目目录内`);
+    if (isPathInside(outputRoot, sourcePath, true))
+        throw new Error(`${label}.source 不能位于构建输出目录内`);
+    const sourceStat = lstatSync(sourcePath);
+    if (sourceStat.isFile())
+        throw new Error(`${label}.source 必须是产物目录；请将旧 ZIP 解压到 companion 目录并修改 source，SDK 会自动打包`);
+    if (sourceStat.isSymbolicLink() || !sourceStat.isDirectory())
+        throw new Error(`${label}.source 必须是普通产物目录`);
+    const realSourcePath = realpathSync(sourcePath);
+    if (!isPathInside(projectRoot, realSourcePath))
+        throw new Error(`${label}.source 不能通过符号链接逃逸项目目录`);
+    if (isPathInside(outputRoot, realSourcePath, true))
+        throw new Error(`${label}.source 不能位于构建输出目录内`);
+    if (isPathInside(realSourcePath, outputRoot, true))
+        throw new Error(`${label}.source 不能包含构建输出目录`);
+    const archive = packCompanionDirectory(realSourcePath, label);
+    const entries = inspectZipArchive(archive, label);
+    assertEntrypointExists(entries, target.entrypoint.kind, entrypointPath, label);
+    const readEntry = (name, visited = new Set()) => {
+        if (visited.has(name))
+            throw new Error(`${label} 包含循环符号链接`);
+        visited.add(name);
+        const segments = name.split('/');
+        for (let end = 1; end <= segments.length; end++) {
+            const prefix = segments.slice(0, end).join('/');
+            const link = entries.find(item => item.name === prefix && item.symlink);
+            if (link) {
+                const target = archive.subarray(link.dataStart, link.localEnd).toString('utf8');
+                const resolved = path.posix.join(path.posix.dirname(prefix), target, ...segments.slice(end));
+                validateArchivePath(resolved, `${label} 符号链接目标`);
+                return readEntry(resolved, visited);
+            }
+        }
+        const entry = entries.find((item) => item.name === name && !item.directory);
+        if (!entry)
+            throw new Error(`${label} 的入口文件在 ZIP 中不存在`);
+        const compressed = archive.subarray(entry.dataStart, entry.localEnd);
+        const bytes = entry.compressionMethod === 0 ? compressed
+            : entry.compressionMethod === 8 ? inflateRawSync(compressed, { maxOutputLength: Math.max(1, entry.uncompressedSize) })
+                : undefined;
+        if (!bytes || bytes.length !== entry.uncompressedSize)
+            throw new Error(`${label} 的入口 ZIP 数据损坏或压缩格式不支持`);
+        return bytes;
+    };
+    const executablePath = target.entrypoint.kind === 'executable' ? entrypointPath
+        : `${entrypointPath}/Contents/MacOS/${companionBundleExecutable(readEntry(`${entrypointPath}/Contents/Info.plist`))}`;
+    assertCompanionExecutable(readEntry(executablePath), targetName);
+    const relativePath = `companions/${alias}/${targetName}.zip`;
+    const destination = path.join(options.outputRoot, ...relativePath.split('/'));
+    if (options.copyArtifacts !== false) {
+        mkdirSync(path.dirname(destination), { recursive: true });
+        const temporaryDestination = path.join(path.dirname(destination), `.${path.basename(destination)}.${randomUUID()}.tmp`);
+        try {
+            writeFileSync(temporaryDestination, archive, { flag: 'wx' });
+            renameSync(temporaryDestination, destination);
+        }
+        finally {
+            rmSync(temporaryDestination, { force: true });
+        }
+    }
+    const size = archive.length;
+    options.onPreparedArtifact?.({ archive, path: relativePath, size, sourcePath: realSourcePath });
+    return {
+        path: relativePath,
+        size,
+        sha256: createHash('sha256').update(archive).digest('hex'),
+        entrypoint: { kind: target.entrypoint.kind, path: entrypointPath },
+        elevation,
+        args,
+    };
+}
+function inspectZipArchive(archive, label) {
+    const eocd = findEndOfCentralDirectory(archive);
+    const entryCount = archive.readUInt16LE(eocd + 10);
+    if (entryCount !== archive.readUInt16LE(eocd + 8))
+        throw new Error(`${label}.source ZIP 条目数量不一致`);
+    const centralSize = archive.readUInt32LE(eocd + 12);
+    const centralOffset = archive.readUInt32LE(eocd + 16);
+    if (entryCount === 0 || entryCount > MAX_ENTRY_COUNT)
+        throw new Error(`${label}.source ZIP 文件数不合法`);
+    if (centralOffset + centralSize > eocd)
+        throw new Error(`${label}.source ZIP 中央目录损坏`);
+    const names = new Set();
+    const foldedNames = new Set();
+    const entries = [];
+    let cursor = centralOffset;
+    let totalUncompressed = 0;
+    for (let index = 0; index < entryCount; index += 1) {
+        if (cursor + 46 > archive.length || archive.readUInt32LE(cursor) !== 0x02014b50)
+            throw new Error(`${label}.source ZIP 中央目录损坏`);
+        const flags = archive.readUInt16LE(cursor + 8);
+        const compressionMethod = archive.readUInt16LE(cursor + 10);
+        const crc32 = archive.readUInt32LE(cursor + 16);
+        const compressedSize = archive.readUInt32LE(cursor + 20);
+        const uncompressedSize = archive.readUInt32LE(cursor + 24);
+        const nameLength = archive.readUInt16LE(cursor + 28);
+        const extraLength = archive.readUInt16LE(cursor + 30);
+        const commentLength = archive.readUInt16LE(cursor + 32);
+        const externalAttributes = archive.readUInt32LE(cursor + 38);
+        const localOffset = archive.readUInt32LE(cursor + 42);
+        const end = cursor + 46 + nameLength + extraLength + commentLength;
+        if (end > archive.length || (flags & 1) !== 0)
+            throw new Error(`${label}.source ZIP 包含加密或损坏的条目`);
+        if (compressedSize === 0xffffffff || uncompressedSize === 0xffffffff)
+            throw new Error(`${label}.source ZIP 暂不支持 ZIP64`);
+        const centralName = archive.subarray(cursor + 46, cursor + 46 + nameLength);
+        const name = centralName.toString('utf8');
+        if ((flags & 0x800) === 0 && /[^\x00-\x7f]/.test(name))
+            throw new Error(`${label}.source ZIP 非 ASCII 路径必须声明 UTF-8`);
+        const normalized = validateArchivePath(name.replace(/\/$/, ''), `${label}.source ZIP 条目`);
+        const unixMode = externalAttributes >>> 16;
+        const fileType = unixMode & 0o170000;
+        if (fileType && fileType !== 0o100000 && fileType !== 0o040000 && fileType !== 0o120000)
+            throw new Error(`${label}.source ZIP 不允许特殊文件：${normalized}`);
+        const folded = normalized.toLocaleLowerCase('en-US');
+        if (names.has(normalized) || foldedNames.has(folded))
+            throw new Error(`${label}.source ZIP 包含重复或大小写冲突条目：${normalized}`);
+        names.add(normalized);
+        foldedNames.add(folded);
+        totalUncompressed += uncompressedSize;
+        if (totalUncompressed > MAX_UNCOMPRESSED_BYTES ||
+            (compressedSize === 0 ? uncompressedSize > 0 : uncompressedSize / compressedSize > MAX_COMPRESSION_RATIO)) {
+            throw new Error(`${label}.source ZIP 解压预算超限`);
+        }
+        const local = inspectLocalEntry(archive, {
+            centralOffset,
+            compressedSize,
+            compressionMethod,
+            crc32,
+            flags,
+            localOffset,
+            name: centralName,
+            uncompressedSize,
+        }, label);
+        entries.push({ name: normalized, directory: name.endsWith('/'), symlink: fileType === 0o120000, ...local });
+        cursor = end;
+    }
+    if (cursor !== centralOffset + centralSize)
+        throw new Error(`${label}.source ZIP 中央目录长度不一致`);
+    const orderedLocalEntries = [...entries].sort((left, right) => left.localStart - right.localStart);
+    for (let index = 1; index < orderedLocalEntries.length; index += 1) {
+        if (orderedLocalEntries[index].localStart < orderedLocalEntries[index - 1].localEnd) {
+            throw new Error(`${label}.source ZIP local entry 范围重叠`);
+        }
+    }
+    return entries;
+}
+function inspectLocalEntry(archive, expected, label) {
+    const start = expected.localOffset;
+    if (start + 30 > expected.centralOffset || archive.readUInt32LE(start) !== 0x04034b50) {
+        throw new Error(`${label}.source ZIP local header 损坏`);
+    }
+    const flags = archive.readUInt16LE(start + 6);
+    const compressionMethod = archive.readUInt16LE(start + 8);
+    const crc32 = archive.readUInt32LE(start + 14);
+    const compressedSize = archive.readUInt32LE(start + 18);
+    const uncompressedSize = archive.readUInt32LE(start + 22);
+    const nameLength = archive.readUInt16LE(start + 26);
+    const extraLength = archive.readUInt16LE(start + 28);
+    const nameStart = start + 30;
+    const dataStart = nameStart + nameLength + extraLength;
+    const dataEnd = dataStart + expected.compressedSize;
+    if (dataEnd > expected.centralOffset || !archive.subarray(nameStart, nameStart + nameLength).equals(expected.name)) {
+        throw new Error(`${label}.source ZIP central/local 路径或数据范围不一致`);
+    }
+    if (flags !== expected.flags || compressionMethod !== expected.compressionMethod) {
+        throw new Error(`${label}.source ZIP central/local metadata 不一致`);
+    }
+    if ((flags & 0x08) === 0 &&
+        (crc32 !== expected.crc32 || compressedSize !== expected.compressedSize || uncompressedSize !== expected.uncompressedSize)) {
+        throw new Error(`${label}.source ZIP central/local 大小或 CRC 不一致`);
+    }
+    return { localStart: start, localEnd: dataEnd, dataStart, compressionMethod, uncompressedSize: expected.uncompressedSize };
+}
+function findEndOfCentralDirectory(archive) {
+    const minimum = Math.max(0, archive.length - 65_557);
+    for (let offset = archive.length - 22; offset >= minimum; offset -= 1) {
+        if (archive.readUInt32LE(offset) === 0x06054b50) {
+            if (archive.readUInt16LE(offset + 4) !== 0 || archive.readUInt16LE(offset + 6) !== 0)
+                throw new Error('Companion ZIP 不支持多磁盘归档');
+            return offset;
+        }
+    }
+    throw new Error('Companion source 不是有效 ZIP');
+}
+function validateArchivePath(value, label) {
+    if (typeof value !== 'string' || !value || value.includes('\\') || value.startsWith('/') || /^[A-Za-z]:/.test(value))
+        throw new Error(`${label} 必须是 ZIP 内相对 POSIX 路径`);
+    const segments = value.split('/');
+    if (segments.some((segment) => !segment || segment === '.' || segment === '..') || /[\u0000-\u001f\u007f]/.test(value))
+        throw new Error(`${label} 包含不安全路径`);
+    return value;
+}
+function validateEntrypoint(target, kind, entrypointPath, label) {
+    if (kind !== 'executable' && kind !== 'app-bundle')
+        throw new Error(`${label}.entrypoint.kind 不合法`);
+    if (target === 'windows-x64' && (kind !== 'executable' || !entrypointPath.toLowerCase().endsWith('.exe')))
+        throw new Error(`${label} 必须声明 .exe executable`);
+    if (target === 'macos-arm64' && kind === 'app-bundle' && !entrypointPath.endsWith('.app'))
+        throw new Error(`${label} 的 app-bundle 必须指向 .app`);
+}
+function assertEntrypointExists(entries, kind, entrypointPath, label) {
+    const exists = kind === 'app-bundle'
+        ? entries.some((entry) => entry.name === entrypointPath || entry.name.startsWith(`${entrypointPath}/`))
+        : entries.some((entry) => entry.name === entrypointPath && !entry.directory);
+    if (!exists)
+        throw new Error(`${label}.entrypoint 在 ZIP 中不存在：${entrypointPath}`);
+}
+function validateCapabilities(value, alias) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`companions.${alias}.capabilities 必须是数组`);
+    const result = [];
+    for (const capability of value) {
+        if (!MINIAPP_COMPANION_CAPABILITIES.includes(capability))
+            throw new Error(`companions.${alias}.capabilities 包含未知能力：${capability}`);
+        if (result.includes(capability))
+            throw new Error(`companions.${alias}.capabilities 包含重复能力：${capability}`);
+        result.push(capability);
+    }
+    return result.sort((left, right) => MINIAPP_COMPANION_CAPABILITIES.indexOf(left) - MINIAPP_COMPANION_CAPABILITIES.indexOf(right));
+}
+function validateArgs(value, label) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > MAX_ARG_COUNT)
+        throw new Error(`${label}.args 不合法`);
+    let totalBytes = 0;
+    for (const item of value) {
+        if (typeof item !== 'string' || /[\u0000\r\n]/.test(item))
+            throw new Error(`${label}.args 不合法`);
+        const bytes = Buffer.byteLength(item, 'utf8');
+        if (bytes > MAX_ARG_BYTES)
+            throw new Error(`${label}.args 单项最多允许 ${MAX_ARG_BYTES} UTF-8 bytes`);
+        totalBytes += bytes;
+    }
+    if (totalBytes > MAX_ARGS_TOTAL_BYTES)
+        throw new Error(`${label}.args 总计最多允许 ${MAX_ARGS_TOTAL_BYTES} UTF-8 bytes`);
+    return [...value];
+}
+function resolveRealPathIfPresent(value) {
+    try {
+        return realpathSync(value);
+    }
+    catch {
+        const absolute = path.resolve(value);
+        const parent = path.dirname(absolute);
+        return parent === absolute ? absolute : path.join(resolveRealPathIfPresent(parent), path.basename(absolute));
+    }
+}
+function isPathInside(root, candidate, allowEqual = false) {
+    const relative = path.relative(root, candidate);
+    return ((allowEqual && relative === '') || (relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)));
+}
+function assertExactKeys(value, allowed, label) {
+    if (!isRecord(value))
+        throw new Error(`${label} 必须是对象`);
+    const unknown = Object.keys(value).find((key) => !allowed.includes(key));
+    if (unknown)
+        throw new Error(`${label} 包含未知字段：${unknown}`);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
 const UNDEFINED_CODE_POINTS = new Set([
     65534, 65535, 131070, 131071, 196606, 196607, 262142, 262143, 327678, 327679, 393214,
     393215, 458750, 458751, 524286, 524287, 589822, 589823, 655358, 655359, 720894,
@@ -11889,7 +12878,7 @@ function shouldSkipMiniappPlatformCspFromEnv(env = process.env) {
  * 检测同款 INSTALL_FLAG，不会重复 patch。
  */
 function injectMiniDevConsoleBootstrap(html) {
-    const bootstrap = `<script>(function(){var LEVELS=['log','debug','info','warn','error'];var FLAG='${MINI_DEV_CONSOLE_INSTALL_FLAG}';var TYPE='${MINI_DEV_CONSOLE_EVENT_TYPE}';if(window.name!=='${MINI_DEV_IFRAME_WINDOW_NAME}')window.name='${MINI_DEV_IFRAME_WINDOW_NAME}';if(window[FLAG])return;var patched=false;for(var i=0;i<LEVELS.length;i++)(function(level){var original=console[level];if(typeof original!=='function')return;console[level]=function(){try{parent.postMessage({type:TYPE,detail:{level:level,args:Array.prototype.slice.call(arguments),timestamp:Date.now()}},'*')}catch(e){}return original.apply(this,arguments)};patched=true})(LEVELS[i]);if(patched)window[FLAG]=true})();</script>`;
+    const bootstrap = `<script>(function(){var LEVELS=['log','debug','info','warn','error'];var FLAG='${MINI_DEV_CONSOLE_INSTALL_FLAG}';var TYPE='${MINI_DEV_CONSOLE_EVENT_TYPE}';if(window[FLAG])return;var patched=false;for(var i=0;i<LEVELS.length;i++)(function(level){var original=console[level];if(typeof original!=='function')return;console[level]=function(){try{parent.postMessage({type:TYPE,detail:{level:level,args:Array.prototype.slice.call(arguments),timestamp:Date.now()}},'*')}catch(e){}return original.apply(this,arguments)};patched=true})(LEVELS[i]);if(patched)window[FLAG]=true})();</script>`;
     const headIndex = html.indexOf('<head>');
     if (headIndex < 0) {
         return html;
@@ -11900,9 +12889,29 @@ function injectMiniDevConsoleBootstrap(html) {
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 const miniDevLoggingConstant = ['__HB_SDK_DEV', 'LOGGING__'].join('_');
-function miniappManifest(options) {
-    const platforms = validateMiniappPlatforms(options?.platforms, 'miniappManifest().platforms');
+const DEV_MANIFEST_PATH = '/__hb_sdk__/companion/manifest.json';
+const DEV_TOKEN_HEADER = 'x-hb-sdk-companion-dev-token';
+const DEV_DIGEST_HEADER = 'x-hb-sdk-companion-manifest-sha256';
+const DEV_ERROR_MESSAGE = 'Companion 开发资源暂时不可用';
+const DEV_COMPANION_PATH_PATTERN = /^\/__hb_sdk__\/companions\/([a-z][a-z0-9-]{0,31})\/(windows-x64|macos-arm64)\.zip$/;
+const HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV = 'HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN';
+const devSnapshotStoreKey = Symbol.for('@heybox/hb-sdk/dev-companion-snapshots');
+const devSnapshotRegistry = globalThis;
+if (!devSnapshotRegistry[devSnapshotStoreKey]) {
+    devSnapshotRegistry[devSnapshotStoreKey] = new Map();
+    process.once('exit', () => {
+        for (const store of devSnapshotRegistry[devSnapshotStoreKey].values()) {
+            for (const snapshot of store.snapshots.values())
+                rmSync(snapshot.root, { force: true, recursive: true });
+        }
+    });
+}
+const devSnapshotStores = devSnapshotRegistry[devSnapshotStoreKey];
+function miniappManifest() {
+    const includeCompanions = process.env.HB_SDK_SKIP_COMPANIONS !== '1';
+    const deviceLogs = new DeviceLogStore();
     const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
+    let companionArtifactAccessToken = parseCompanionArtifactAccessToken(process.env[HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV]);
     let root = process.cwd();
     let outDir = 'dist';
     let command = 'build';
@@ -11937,6 +12946,211 @@ function miniappManifest(options) {
             command = resolved.command;
             hmrWebSocketUrl = resolveHmrWebSocketUrl(resolved);
         },
+        configureServer(server) {
+            let unregisterLogs;
+            const registerLogs = () => {
+                const address = server.httpServer?.address();
+                if (address && typeof address !== 'string')
+                    unregisterLogs = registerDeviceLogs(address.port, deviceLogs);
+            };
+            server.httpServer?.once('listening', registerLogs);
+            server.httpServer?.once('close', () => unregisterLogs?.());
+            if (server.httpServer?.listening)
+                registerLogs();
+            let store = devSnapshotStores.get(root);
+            companionArtifactAccessToken ??= store?.token;
+            if (!store || store.token !== companionArtifactAccessToken) {
+                store = { token: companionArtifactAccessToken ?? '', snapshots: new Map() };
+                devSnapshotStores.set(root, store);
+            }
+            const snapshots = store.snapshots;
+            if (server.restart) {
+                const restart = server.restart.bind(server);
+                server.restart = async (forceOptimize) => {
+                    store.restarting = true;
+                    try {
+                        await restart(forceOptimize);
+                    }
+                    finally {
+                        store.restarting = false;
+                    }
+                };
+            }
+            let dirty = true;
+            let latestDigest;
+            let changedAt = 0;
+            let sourceRoots = [];
+            const watchPaths = new Set();
+            const invalidate = () => {
+                dirty = true;
+                changedAt = Date.now();
+                // 目录自身的变化发现新增/删除子项；文件监听发现原地编译与资源覆盖。
+                updateWatchPaths(sourceRoots);
+            };
+            const updateWatchPaths = (files) => {
+                sourceRoots = files;
+                const next = new Set(files.flatMap(collectCompanionWatchPaths));
+                for (const file of watchPaths)
+                    if (!next.has(file)) {
+                        unwatchFile(file, invalidate);
+                        watchPaths.delete(file);
+                    }
+                for (const file of next)
+                    if (!watchPaths.has(file)) {
+                        watchFile(file, { interval: 500, persistent: false }, invalidate);
+                        watchPaths.add(file);
+                    }
+            };
+            updateWatchPaths([path.join(root, 'package.json')]);
+            server.httpServer?.once('close', () => {
+                for (const file of watchPaths)
+                    unwatchFile(file, invalidate);
+                if (store.restarting)
+                    return;
+                for (const snapshot of snapshots.values())
+                    rmSync(snapshot.root, { force: true, recursive: true });
+                if (devSnapshotStores.get(root) === store)
+                    devSnapshotStores.delete(root);
+            });
+            const getSnapshot = (requestedDigest) => {
+                if (requestedDigest)
+                    return snapshots.get(requestedDigest);
+                if (!dirty && latestDigest)
+                    return snapshots.get(latestDigest);
+                if (Date.now() - changedAt < 200)
+                    throw new Error('Companion 产物准备中');
+                const snapshotRoot = mkdtempSync(path.join(tmpdir(), 'hb-sdk-companion-snapshot-'));
+                chmodSync(snapshotRoot, 0o700);
+                try {
+                    const config = readMiniappCompanionsFromPackageJson(root);
+                    const sources = Object.values(config.declarations ?? {}).flatMap(definition => definition && typeof definition === 'object' && definition.targets && typeof definition.targets === 'object'
+                        ? Object.entries(definition.targets).flatMap(([name, target]) => currentCompanionTargets().includes(name) && target && typeof target.source === 'string'
+                            ? [path.resolve(config.projectRoot, target.source)] : []) : [])
+                        .filter(source => source.startsWith(`${config.projectRoot}${path.sep}`));
+                    updateWatchPaths([config.packageJsonPath, ...sources]);
+                    const snapshot = prepareDevSnapshot(root, outDir, readMiniappPlatformsFromPackageJson(root), config.declarations, snapshotRoot, config.projectRoot);
+                    const digest = createHash('sha256').update(snapshot.manifestBytes).digest('hex');
+                    if (snapshots.has(digest))
+                        rmSync(snapshotRoot, { force: true, recursive: true });
+                    else {
+                        const totalBytes = [...snapshots.values(), snapshot].reduce((total, item) => total + [...item.artifacts.values()].reduce((size, artifact) => size + artifact.size, 0), 0);
+                        if (snapshots.size >= 32 || totalBytes > 1024 * 1024 * 1024) {
+                            throw new Error('Companion 快照存储已达到上限，请结束旧调试会话后重启 dev');
+                        }
+                        snapshots.set(digest, { ...snapshot, root: snapshotRoot });
+                    }
+                    latestDigest = digest;
+                    dirty = false;
+                    return snapshots.get(digest);
+                }
+                catch (error) {
+                    rmSync(snapshotRoot, { force: true, recursive: true });
+                    throw error;
+                }
+            };
+            server.middlewares.use(async (request, response, next) => {
+                const pathname = parseRequestPathname(request.url);
+                if (pathname === DEVICE_LOG_PATH) {
+                    const origin = request.headers.origin;
+                    let allowed = false;
+                    try {
+                        allowed = Boolean(origin && new URL(origin).host === request.headers.host);
+                    }
+                    catch { /* 拒绝畸形 Origin。 */ }
+                    if (!allowed) {
+                        response.writeHead(403).end();
+                        return;
+                    }
+                    await deviceLogs.upload(request, response);
+                    return;
+                }
+                const companionMatch = pathname?.match(DEV_COMPANION_PATH_PATTERN);
+                if (pathname !== DEV_MANIFEST_PATH && !companionMatch) {
+                    next();
+                    return;
+                }
+                if (request.method !== 'GET' && request.method !== 'HEAD') {
+                    response.statusCode = 405;
+                    response.setHeader('Allow', 'GET, HEAD');
+                    response.end();
+                    return;
+                }
+                if (!companionArtifactAccessToken ||
+                    !isNumericLoopbackRequest(request) ||
+                    !isNumericLoopbackHost(request.headers.host) ||
+                    !hasValidCompanionArtifactToken(request, companionArtifactAccessToken)) {
+                    response.statusCode = 403;
+                    response.end();
+                    return;
+                }
+                try {
+                    const requestedDigest = request.headers[DEV_DIGEST_HEADER];
+                    if (requestedDigest !== undefined && (typeof requestedDigest !== 'string' || !/^[a-f0-9]{64}$/.test(requestedDigest))) {
+                        response.statusCode = 400;
+                        response.end();
+                        return;
+                    }
+                    const snapshot = getSnapshot(requestedDigest);
+                    if (!snapshot) {
+                        response.statusCode = 404;
+                        response.end();
+                        return;
+                    }
+                    response.setHeader('Cache-Control', 'no-store');
+                    response.setHeader('X-Content-Type-Options', 'nosniff');
+                    if (pathname === DEV_MANIFEST_PATH) {
+                        response.statusCode = 200;
+                        response.setHeader('Content-Type', 'application/json; charset=utf-8');
+                        response.setHeader('Content-Length', snapshot.manifestBytes.length);
+                        response.end(request.method === 'HEAD' ? undefined : snapshot.manifestBytes);
+                        return;
+                    }
+                    const [, alias, target] = companionMatch;
+                    const artifact = snapshot.artifacts.get(`companions/${alias}/${target}.zip`);
+                    if (!artifact || `/__hb_sdk__/${artifact.path}` !== pathname) {
+                        response.statusCode = 404;
+                        response.end();
+                        return;
+                    }
+                    response.statusCode = 200;
+                    response.setHeader('Content-Type', 'application/zip');
+                    response.setHeader('Content-Length', artifact.size);
+                    if (request.method === 'HEAD') {
+                        response.end();
+                        return;
+                    }
+                    const stream = createReadStream(artifact.sourcePath);
+                    const stopStreaming = () => stream.destroy();
+                    request.once('aborted', stopStreaming);
+                    response.once('close', stopStreaming);
+                    stream.once('close', () => {
+                        request.off('aborted', stopStreaming);
+                        response.off('close', stopStreaming);
+                    });
+                    stream.on('error', () => {
+                        if (response.headersSent) {
+                            response.destroy();
+                            return;
+                        }
+                        response.statusCode = 500;
+                        response.removeHeader('Content-Length');
+                        response.setHeader('Content-Type', 'text/plain; charset=utf-8');
+                        response.end(DEV_ERROR_MESSAGE);
+                    });
+                    stream.pipe(response);
+                }
+                catch (error) {
+                    response.statusCode = 500;
+                    const message = error instanceof Error ? error.message : '';
+                    response.setHeader('X-Hb-Sdk-Companion-Error', /ENOENT/.test(message) ? 'artifact-missing'
+                        : /快照存储/.test(message) ? 'snapshot-limit'
+                            : /产物准备中/.test(message) ? 'artifact-updating'
+                                : /package.json|JSON|permissions/.test(message) ? 'invalid-manifest' : 'invalid-artifact');
+                    response.setHeader('Content-Type', 'text/plain; charset=utf-8');
+                    response.end(DEV_ERROR_MESSAGE);
+                }
+            });
+        },
         buildEnd(error) {
             if (error) {
                 priorBuildError = priorBuildError ?? toError(error);
@@ -11947,8 +13161,14 @@ function miniappManifest(options) {
                 ...(command === 'serve' ? { hmrWebSocketUrl } : {}),
                 skipPlatformCsp,
             });
-            return command === 'serve' ? injectMiniDevConsoleBootstrap(enforced) : enforced;
-        }, async closeBundle() {
+            return command === 'serve'
+                ? injectMiniDevConsoleBootstrap(enforced.replace('<head>', `<head>${deviceLogBootstrap(deviceLogs.uploadToken)}`))
+                : enforced;
+        },
+        async closeBundle() {
+            // Vite dev 的关闭/配置重载同样会触发此钩子，不执行发布打包。
+            if (command === 'serve')
+                return;
             // Rollup 在 buildStart/transform 失败后仍会调用 closeBundle。
             // 若此时再抛「缺 index.html」等二次错误，会掩盖真实失败原因。
             if (priorBuildError) {
@@ -11956,9 +13176,15 @@ function miniappManifest(options) {
             }
             const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
             const sdkVersion = resolveSdkVersion();
+            const platforms = readMiniappPlatformsFromPackageJson(root);
             const parsedPermissions = readMiniappPermissionsFromPackageJson(root, sdkVersion);
+            const companionConfig = readMiniappCompanionsFromPackageJson(root);
+            const companionDeclarations = includeCompanions ? companionConfig.declarations : undefined;
             if (!parsedPermissions.declared)
                 this.warn(getMissingPermissionsWarning());
+            if (companionDeclarations && !parsedPermissions.permissions?.companion) {
+                throw new Error('配置 companions 时必须声明 package.json#heybox.permissions.companion.enabled=true');
+            }
             const outputRoot = path.resolve(root, outDir);
             const htmlFiles = collectHtmlFiles(outputRoot);
             const unexpectedHtmlFiles = htmlFiles.filter((file) => path.relative(outputRoot, file) !== 'index.html');
@@ -11973,16 +13199,104 @@ function miniappManifest(options) {
             }
             writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(readFileSync(indexHtmlPath, 'utf8'), { skipPlatformCsp }));
             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({
                 version,
                 sdkVersion,
                 platforms,
                 ...(parsedPermissions.permissions === undefined ? {} : { permissions: parsedPermissions.permissions }),
+                ...(companions === undefined ? {} : { companions }),
             }));
         },
     };
 }
+function prepareDevSnapshot(root, outDir, platforms, declarations, snapshotRoot, projectRoot = root) {
+    const version = validateMiniappPackageVersionForBuild(readMiniappVersionFromPackageJson(root));
+    const sdkVersion = resolveSdkVersion();
+    const permissions = readMiniappPermissionsFromPackageJson(root, sdkVersion).permissions;
+    if (declarations && !permissions?.companion) {
+        throw new Error('配置 companions 时必须声明 package.json#heybox.permissions.companion.enabled=true');
+    }
+    const artifacts = new Map();
+    const companions = prepareMiniappCompanions(declarations, {
+        root: projectRoot,
+        outputRoot: path.resolve(root, outDir),
+        platforms,
+        targets: currentCompanionTargets(),
+        copyArtifacts: false,
+        onPreparedArtifact: ({ archive, path: artifactPath, size }) => {
+            const sourcePath = path.join(snapshotRoot, ...artifactPath.split('/'));
+            mkdirSync(path.dirname(sourcePath), { mode: 0o700, recursive: true });
+            writeFileSync(sourcePath, archive, { flag: 'wx', mode: 0o600 });
+            artifacts.set(artifactPath, { path: artifactPath, size, sourcePath });
+        },
+    });
+    const manifest = {
+        version,
+        sdkVersion,
+        platforms,
+        ...(permissions === undefined ? {} : { permissions }),
+        ...(companions === undefined ? {} : { companions }),
+    };
+    return { artifacts, manifestBytes: Buffer.from(renderMiniappManifest(manifest)) };
+}
+function currentCompanionTargets() {
+    if (platform() === 'win32' && arch() === 'x64')
+        return ['windows-x64'];
+    if (platform() === 'darwin' && arch() === 'arm64')
+        return ['macos-arm64'];
+    return [];
+}
+/** 不跟随链接扫描；合法 .app 链接的最终目标仍在此树内，由普通路径负责监听。 */
+function collectCompanionWatchPaths(root) {
+    const paths = [root];
+    try {
+        if (lstatSync(root).isDirectory()) {
+            for (const name of readdirSync(root))
+                paths.push(...collectCompanionWatchPaths(path.join(root, name)));
+        }
+    }
+    catch {
+        // 缺失目录也保留监听，允许第一次编译或原子替换后自动恢复。
+    }
+    return paths;
+}
+function parseRequestPathname(value) {
+    if (!value)
+        return undefined;
+    try {
+        const url = new URL(value, 'http://127.0.0.1');
+        return url.search || url.hash ? undefined : url.pathname;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isNumericLoopbackRequest(request) {
+    const remoteAddress = request.socket.remoteAddress;
+    return remoteAddress === '127.0.0.1' || remoteAddress === '::1' || remoteAddress === '::ffff:127.0.0.1';
+}
+function isNumericLoopbackHost(host) {
+    if (!host)
+        return false;
+    const match = host.match(/^(?:127\.0\.0\.1|\[::1\]):(\d{1,5})$/);
+    if (!match)
+        return false;
+    const port = Number(match[1]);
+    return port >= 1 && port <= 65_535;
+}
+function parseCompanionArtifactAccessToken(value) {
+    return value && /^[A-Za-z0-9_-]{43}$/.test(value) ? value : undefined;
+}
+function hasValidCompanionArtifactToken(request, expected) {
+    const value = request.headers[DEV_TOKEN_HEADER];
+    const candidate = Buffer.alloc(43);
+    if (typeof value === 'string')
+        Buffer.from(value).copy(candidate, 0, 0, candidate.length);
+    const matches = timingSafeEqual(candidate, Buffer.from(expected));
+    return matches && typeof value === 'string' && /^[A-Za-z0-9_-]{43}$/.test(value);
+}
 function assertMiniappViteBase(base) {
     if (base !== undefined && base !== '' && base !== './') {
         throw new Error(`工坊小程序 Vite base 仅支持空字符串或 "./"，当前值：${base}`);
@@ -12025,4 +13339,4 @@ function resolveHmrWebSocketUrl(resolved) {
     return `${protocol}://${host}${port ? `:${port}` : ''}`;
 }
 
-export { MINIAPP_PLATFORM_VALUES, miniappManifest };
+export { HB_SDK_COMPANION_ARTIFACT_ACCESS_TOKEN_ENV, MINIAPP_PLATFORM_VALUES, miniappManifest };