@heybox/hb-sdk 0.6.8-alpha.1 → 0.6.8

package/dist/index.esm.js

@@ -1,3 +1,274 @@
+/**
+ * network.request 请求体形态校验与宿主失败诊断文案。
+ *
+ * @remarks
+ * App Host 的 heybox 客户端代发 transport 仅声明 form/json，不支持 multipart。
+ * 本地 Mock 若直接走 fetch 会“能通”，上线后却变成难以理解的 500 network_error。
+ * 因此在 SDK 侧统一提前拒绝 multipart，并在宿主伪装 HTTP 失败时给出可操作提示。
+ */
+/** multipart 不被 App Host 支持时的稳定说明（开发者可见）。 */
+const NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE = 'network.request 不支持 multipart/form-data。App Host 客户端代发仅支持 application/x-www-form-urlencoded（form）与 application/json；请将 data 编码为 form 字符串（例如 new URLSearchParams({...}).toString()）并设置 Content-Type: application/x-www-form-urlencoded。文件上传请使用专用上传能力，勿手写 multipart boundary。';
+/**
+ * 读取请求头中的 Content-Type（大小写不敏感）。
+ */
+function readNetworkContentType(headers) {
+    if (!headers) {
+        return undefined;
+    }
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.trim().toLowerCase() === 'content-type' && typeof value === 'string') {
+            return value;
+        }
+    }
+    return undefined;
+}
+/**
+ * 判断 Content-Type 是否声明为 multipart/form-data。
+ */
+function isMultipartContentType(contentType) {
+    return typeof contentType === 'string' && contentType.toLowerCase().includes('multipart/form-data');
+}
+/**
+ * 判断字符串 body 是否像手写 multipart 实体。
+ */
+function looksLikeMultipartBody(data) {
+    if (typeof data !== 'string') {
+        return false;
+    }
+    const trimmed = data.trimStart();
+    return trimmed.startsWith('--') && /content-disposition\s*:\s*form-data/i.test(data);
+}
+/**
+ * 判断公开请求配置是否使用了 Host 不支持的 multipart 形态。
+ */
+function isUnsupportedMultipartNetworkRequest(config) {
+    return isMultipartContentType(readNetworkContentType(config.headers)) || looksLikeMultipartBody(config.data);
+}
+function isPlainObject$2(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+/**
+ * 从宿主返回的“完成态”响应中提取更清晰的失败原因。
+ *
+ * @remarks
+ * Host 可能把 transport 不支持等内部错误包装成 HTTP 500 + `{ status: 'network_error', msg }`。
+ * 此时 `status=500` 并不代表目标站点返回了 500。
+ */
+function describeHostNetworkFailure(response) {
+    const data = response.data;
+    const hostStatus = isPlainObject$2(data) && typeof data.status === 'string' ? data.status : undefined;
+    const hostMsg = isPlainObject$2(data) && typeof data.msg === 'string'
+        ? data.msg
+        : isPlainObject$2(data) && typeof data.message === 'string'
+            ? data.message
+            : undefined;
+    const isHostNetworkError = hostStatus === 'network_error';
+    const mentionsUnsupportedShape = typeof hostMsg === 'string' &&
+        (hostMsg.includes('unsupported-request-shape') || hostMsg.includes('unsupported_request_shape'));
+    const requestLooksMultipart = isUnsupportedMultipartNetworkRequest(response.config || {});
+    if (!isHostNetworkError && !mentionsUnsupportedShape && !(requestLooksMultipart && response.status >= 500)) {
+        return undefined;
+    }
+    const lines = [
+        '原因: 这是宿主网络层失败，不是目标 URL 的业务 HTTP 响应。',
+    ];
+    if (hostMsg) {
+        lines.push(`宿主信息: ${hostMsg}`);
+    }
+    if (requestLooksMultipart || mentionsUnsupportedShape) {
+        lines.push(NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE);
+    }
+    else if (isHostNetworkError) {
+        lines.push('请检查请求 URL、headers、body 编码与 Host 网络权限；本地 Mock 与 App Host 能力并不完全一致。');
+    }
+    return lines.join(' ');
+}
+
+/**
+ * network.request 诊断日志的纯脱敏工具。
+ *
+ * @remarks
+ * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
+ * modules observability、devtools Mock Host / proxy 共用，并满足 boundary
+ *（devtools 不得直接 import runtime capability modules）。
+ */
+const DATA_PREVIEW_MAX_CHARS = 500;
+const SENSITIVE_HEADER_NAMES = new Set([
+    'authorization',
+    'cookie',
+    'proxy-authorization',
+    'set-cookie',
+    'token',
+    'x-pkey',
+    'api-key',
+    'apikey',
+    'x-api-key',
+    'x-auth-token',
+    'x-access-token',
+    'session',
+    'session-id',
+    'jwt',
+    'refresh-token',
+    'x-csrf-token',
+]);
+/** 敏感字段名：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);
+    }
+}
+/**
+ * 脱敏请求/响应头；敏感名（含 heybox 前缀）替换为 `[redacted]`。
+ */
+function sanitizeNetworkHeaders(headers) {
+    if (!headers) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(headers).map(([key, value]) => [
+        key,
+        isSensitiveNetworkHeaderName(key) ? '[redacted]' : value,
+    ]));
+}
+/**
+ * 预览请求/响应 data：递归脱敏敏感字段，截断长文本与大数组。
+ */
+function previewNetworkData(data) {
+    if (data === undefined) {
+        return undefined;
+    }
+    if (typeof data === 'string') {
+        return previewNetworkStringData(data);
+    }
+    if (typeof data === 'number' || typeof data === 'boolean' || data === null) {
+        return data;
+    }
+    try {
+        const sanitized = sanitizeNetworkDataValue(data);
+        const serialized = JSON.stringify(sanitized);
+        if (serialized === undefined) {
+            return '[unserializable]';
+        }
+        if (serialized.length <= DATA_PREVIEW_MAX_CHARS) {
+            return sanitized;
+        }
+        return truncateText(serialized, DATA_PREVIEW_MAX_CHARS);
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * 诊断 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 isSensitiveNetworkHeaderName(headerName) {
+    const normalized = headerName.trim().toLowerCase();
+    return (SENSITIVE_HEADER_NAMES.has(normalized) ||
+        isSensitiveNetworkKey(normalized) ||
+        normalized.startsWith('x-heybox-') ||
+        normalized.startsWith('x-xhh-'));
+}
+function isSensitiveNetworkKey(key) {
+    return SENSITIVE_KEY_PATTERN.test(key.trim());
+}
+function previewNetworkStringData(data) {
+    const trimmed = data.trim();
+    if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+        try {
+            return previewNetworkData(JSON.parse(trimmed));
+        }
+        catch {
+            // fall through
+        }
+    }
+    if (trimmed.includes('=') && !trimmed.includes('\n') && trimmed.length <= DATA_PREVIEW_MAX_CHARS * 2) {
+        try {
+            const params = new URLSearchParams(trimmed);
+            if ([...params.keys()].length > 0) {
+                const redacted = Object.fromEntries([...params.entries()].map(([key, value]) => [
+                    key,
+                    isSensitiveNetworkKey(key) ? '[redacted]' : value,
+                ]));
+                return previewNetworkData(redacted);
+            }
+        }
+        catch {
+            // fall through
+        }
+    }
+    return truncateText(redactSensitivePairsInRawText(data), DATA_PREVIEW_MAX_CHARS);
+}
+function sanitizeNetworkDataValue(value) {
+    if (Array.isArray(value)) {
+        return value.slice(0, 20).map(item => sanitizeNetworkDataValue(item));
+    }
+    if (!isPlainObject$1(value)) {
+        if (typeof value === 'string') {
+            return truncateText(value, DATA_PREVIEW_MAX_CHARS);
+        }
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        isSensitiveNetworkKey(key) ? '[redacted]' : sanitizeNetworkDataValue(item),
+    ]));
+}
+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 truncateText(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    return `${value.slice(0, maxChars)}…(truncated, total=${value.length})`;
+}
+function isPlainObject$1(value) {
+    return Object.prototype.toString.call(value) === '[object Object]';
+}
+
 /**
  * SDK 对外抛出的标准 bridge / runtime 错误类型。
  *
@@ -60,7 +331,14 @@ class HbMiniProgramNetworkError extends Error {
      * @param response 已完成请求的标准化网络响应。
      */
     constructor(response) {
-        super(`network.request failed with status ${response.status}`);
+        const method = (response.config.method || 'GET').toUpperCase();
+        // 诊断文案使用脱敏 URL，避免 query 中的 token 等经 error.message 泄漏。
+        const url = sanitizeNetworkRequestUrl(response.config.url || '');
+        const statusText = response.statusText ? ` ${response.statusText}` : '';
+        const baseMessage = `network.request failed with status ${response.status}${statusText}: ${method} ${url}`;
+        // 宿主可能把 transport 不支持等内部错误伪装成 HTTP 500；补充可操作提示。
+        const hostHint = describeHostNetworkFailure(response);
+        super(hostHint ? `${baseMessage}\n${hostHint}` : baseMessage);
         this.name = 'HbMiniProgramNetworkError';
         this.status = response.status;
         this.data = response.data;
@@ -321,7 +599,7 @@ function createMessageId() {
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.8-alpha.1';
+    : '0.6.8';
 
 /**
  * 判断未知数据是否符合小程序 bridge 消息信封。
@@ -888,6 +1166,77 @@ function createStorageModule(requester) {
     };
 }
 
+const LOG_PREFIX = '[hb-sdk][network.request]';
+/**
+ * 记录 `network.request` 失败，保证异常路径在开发者控制台可观测。
+ *
+ * @remarks
+ * - 仅用于诊断，不改变错误抛出语义。
+ * - 会脱敏 token/cookie 等敏感头与字段，并截断 body 预览。
+ * - detail 构造与 logger 调用均包在 try 内，日志失败不得影响业务错误抛出。
+ */
+function logNetworkRequestFailure(config, error, extras) {
+    try {
+        const consoleRef = typeof console === 'undefined' ? undefined : console;
+        const logger = consoleRef?.warn || consoleRef?.error || consoleRef?.log;
+        if (!logger) {
+            return;
+        }
+        const detail = createNetworkRequestFailureLog(config, error, extras);
+        logger.call(consoleRef, LOG_PREFIX, formatNetworkRequestFailureMessage(detail), detail);
+    }
+    catch {
+        // 日志失败不得影响业务错误抛出。
+    }
+}
+function createNetworkRequestFailureLog(config, error, extras) {
+    const method = (config.method || 'GET').toUpperCase();
+    const detail = {
+        kind: extras.kind,
+        method,
+        url: sanitizeNetworkRequestUrl(config.url),
+    };
+    if (typeof extras.status === 'number') {
+        detail.status = extras.status;
+    }
+    else if (error instanceof HbMiniProgramNetworkError) {
+        detail.status = error.status;
+    }
+    if (typeof extras.statusText === 'string' && extras.statusText) {
+        detail.statusText = extras.statusText;
+    }
+    // NetworkError 已有 method/url/status 结构化字段；不再回写 message，避免 raw URL 二次泄漏。
+    if (!(error instanceof HbMiniProgramNetworkError)) {
+        if (error instanceof HbMiniProgramSDKError) {
+            detail.code = error.code;
+            detail.message = sanitizeDiagnosticMessage(error.message);
+        }
+        else if (error instanceof Error) {
+            detail.message = sanitizeDiagnosticMessage(error.message);
+        }
+    }
+    if (config.timeout !== undefined) {
+        detail.timeout = config.timeout;
+    }
+    if (config.withCredentials !== undefined) {
+        detail.withCredentials = config.withCredentials;
+    }
+    const headers = sanitizeNetworkHeaders(extras.headers || config.headers);
+    if (Object.keys(headers).length > 0) {
+        detail.headers = headers;
+    }
+    const dataPreview = previewNetworkData(extras.data !== undefined ? extras.data : config.data);
+    if (dataPreview !== undefined) {
+        detail.dataPreview = dataPreview;
+    }
+    return detail;
+}
+function formatNetworkRequestFailureMessage(detail) {
+    const statusPart = detail.status === undefined ? '' : ` status=${detail.status}`;
+    const codePart = detail.code ? ` code=${detail.code}` : '';
+    return `${detail.kind} ${detail.method} ${detail.url}${statusPart}${codePart}`;
+}
+
 const DEFAULT_VALIDATE_STATUS = status => status >= 200 && status < 300;
 function isPlainObject(value) {
     return Object.prototype.toString.call(value) === '[object Object]';
@@ -931,6 +1280,9 @@ function normalizeHeaders(headers) {
     return Object.fromEntries(Object.entries(headers).flatMap(([key, value]) => (typeof value === 'string' ? [[key, value]] : [])));
 }
 function toNetworkResponse(payload, config) {
+    if (payload == null || typeof payload !== 'object') {
+        throw createSDKError('INVALID_NETWORK_RESPONSE', 'network.request 返回了无效的响应', payload);
+    }
     if (typeof payload.status !== 'number' || Number.isNaN(payload.status)) {
         throw createSDKError('INVALID_NETWORK_RESPONSE', 'network.request 返回了无效的 status', payload);
     }
@@ -965,12 +1317,56 @@ function toNetworkResponse(payload, config) {
  */
 async function request(requester, config) {
     const validateStatus = config.validateStatus || DEFAULT_VALIDATE_STATUS;
-    const responsePayload = await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config));
-    const response = toNetworkResponse(responsePayload, config);
-    if (!validateStatus(response.status)) {
-        throw new HbMiniProgramNetworkError(response);
+    try {
+        assertSupportedPublicNetworkRequest(config);
+        const responsePayload = await requester.request(NETWORK_REQUEST_METHOD, toRequestPayload(config));
+        const response = toNetworkResponse(responsePayload, config);
+        if (!validateStatus(response.status)) {
+            const error = new HbMiniProgramNetworkError(response);
+            logNetworkRequestFailure(config, error, {
+                kind: 'http_status',
+                status: response.status,
+                statusText: response.statusText,
+                data: response.data,
+                headers: response.headers,
+            });
+            throw error;
+        }
+        return response;
+    }
+    catch (error) {
+        if (error instanceof HbMiniProgramNetworkError) {
+            throw error;
+        }
+        if (error instanceof HbMiniProgramSDKError && error.code === 'INVALID_PARAMS') {
+            logNetworkRequestFailure(config, error, {
+                kind: 'bridge_error',
+            });
+            throw error;
+        }
+        if (error instanceof HbMiniProgramSDKError && error.code === 'INVALID_NETWORK_RESPONSE') {
+            logNetworkRequestFailure(config, error, {
+                kind: 'invalid_response',
+                data: error.data,
+            });
+            throw error;
+        }
+        logNetworkRequestFailure(config, error, {
+            kind: error instanceof HbMiniProgramSDKError ? 'bridge_error' : 'unknown',
+        });
+        throw error;
+    }
+}
+/**
+ * 在进入 bridge 前拒绝 Host 能力明确不支持的公开请求形态。
+ *
+ * @remarks
+ * 提前失败可避免本地 Mock（fetch）与 App Host（heybox）能力差造成“本地成功、上线 500”。
+ */
+function assertSupportedPublicNetworkRequest(config) {
+    if (isUnsupportedMultipartNetworkRequest(config)) {
+        throw createSDKError('INVALID_PARAMS', NETWORK_REQUEST_MULTIPART_UNSUPPORTED_MESSAGE);
     }
-    return response;
 }
 /**
  * 创建 network 模块。

package/dist/vite.cjs.js

@@ -2,12 +2,13 @@
 
 var node_fs = require('node:fs');
 var path = require('node:path');
+var node_async_hooks = require('node:async_hooks');
 
 var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.8-alpha.1';
+    : '0.6.8';
 
 var re = {exports: {}};
 
@@ -11475,6 +11476,9 @@ function enforceMiniappHtmlPolicy(html, options = {}) {
     removePlatformCspMarkers(document);
     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;
@@ -11617,9 +11621,19 @@ function walk(node, visit) {
         walk(node.content, visit);
 }
 
+const HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN_ENV = 'HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN';
+const HB_SDK_RUNTIME_PERMISSION_CONTEXT_ENV = 'HB_SDK_RUNTIME_PERMISSION_CONTEXT';
+const VERIFIED_RUNTIME_PERMISSION_CONTEXT = 'verified';
+new node_async_hooks.AsyncLocalStorage();
+Promise.resolve();
+function shouldSkipMiniappPlatformCspFromEnv(env = process.env) {
+    return env[HB_SDK_RUNTIME_PERMISSION_CONTEXT_ENV] === VERIFIED_RUNTIME_PERMISSION_CONTEXT && env[HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN_ENV] === '1';
+}
+
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 function miniappManifest() {
+    const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
     let root = process.cwd();
     let outDir = 'dist';
     let command = 'build';
@@ -11651,6 +11665,7 @@ function miniappManifest() {
         transformIndexHtml(html) {
             return enforceMiniappHtmlPolicy(html, {
                 ...(command === 'serve' ? { hmrWebSocketUrl } : {}),
+                skipPlatformCsp,
             });
         },
         async closeBundle() {
@@ -11673,7 +11688,7 @@ function miniappManifest() {
             if (!htmlFiles.includes(indexHtmlPath)) {
                 throw new Error('构建产物必须包含入口 dist/index.html');
             }
-            node_fs.writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(node_fs.readFileSync(indexHtmlPath, 'utf8')));
+            node_fs.writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(node_fs.readFileSync(indexHtmlPath, 'utf8'), { skipPlatformCsp }));
             const manifestPath = path.join(outputRoot, 'manifest.json');
             node_fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
             node_fs.writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion }));

package/dist/vite.esm.js

@@ -1,10 +1,11 @@
 import { readFileSync, existsSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
 import path from 'node:path';
+import { AsyncLocalStorage } from 'node:async_hooks';
 
 /** 构建时替换为当前发布包的实际版本。 */
 const HB_SDK_VERSION = typeof undefined === 'string'
     ? undefined
-    : '0.6.8-alpha.1';
+    : '0.6.8';
 
 var re = {exports: {}};
 
@@ -11472,6 +11473,9 @@ function enforceMiniappHtmlPolicy(html, options = {}) {
     removePlatformCspMarkers(document);
     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;
@@ -11614,9 +11618,19 @@ function walk(node, visit) {
         walk(node.content, visit);
 }
 
+const HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN_ENV = 'HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN';
+const HB_SDK_RUNTIME_PERMISSION_CONTEXT_ENV = 'HB_SDK_RUNTIME_PERMISSION_CONTEXT';
+const VERIFIED_RUNTIME_PERMISSION_CONTEXT = 'verified';
+new AsyncLocalStorage();
+Promise.resolve();
+function shouldSkipMiniappPlatformCspFromEnv(env = process.env) {
+    return env[HB_SDK_RUNTIME_PERMISSION_CONTEXT_ENV] === VERIFIED_RUNTIME_PERMISSION_CONTEXT && env[HB_SDK_RUNTIME_USE_OFFICIAL_DOMAIN_ENV] === '1';
+}
+
 const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 function miniappManifest() {
+    const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
     let root = process.cwd();
     let outDir = 'dist';
     let command = 'build';
@@ -11648,6 +11662,7 @@ function miniappManifest() {
         transformIndexHtml(html) {
             return enforceMiniappHtmlPolicy(html, {
                 ...(command === 'serve' ? { hmrWebSocketUrl } : {}),
+                skipPlatformCsp,
             });
         },
         async closeBundle() {
@@ -11670,7 +11685,7 @@ function miniappManifest() {
             if (!htmlFiles.includes(indexHtmlPath)) {
                 throw new Error('构建产物必须包含入口 dist/index.html');
             }
-            writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(readFileSync(indexHtmlPath, 'utf8')));
+            writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(readFileSync(indexHtmlPath, 'utf8'), { skipPlatformCsp }));
             const manifestPath = path.join(outputRoot, 'manifest.json');
             mkdirSync(path.dirname(manifestPath), { recursive: true });
             writeFileSync(manifestPath, renderMiniappManifest({ version, sdkVersion }));

package/package.json

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

package/skill/SKILL.md

@@ -61,12 +61,13 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 10. Use `hb-sdk remote create` to create and bind a mini-program; use `hb-sdk remote bind <mini-program-id>` to bind an existing manageable mini-program.
 11. Use `hb-sdk remote info`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for remote inspection and preview management.
 12. Use `hb-sdk remote deploy --release-note <text>` to run the project's `scripts.build`, upload, and submit the current project for audit. Do not recommend the removed top-level `hb-sdk deploy` alias.
-13. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
-14. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
-15. Use `hb-sdk remote withdraw`, `hb-sdk remote take-down`, `hb-sdk remote reopen`, and square visibility commands only after showing the target and obtaining required confirmation.
-16. Use `--json` for remote script consumption and `--verbose` only when concise output is insufficient for diagnosis.
-17. Use `hb-sdk doctor` to diagnose whether the local Skill matches the installed SDK; follow its output to install or refresh the Skill.
-18. Do not print or expose cookies, tokens, private headers, or other credentials.
+13. `hb-sdk dev` and `hb-sdk remote deploy` skip the platform CSP only when the validated remote permission snapshot has `network.request.status=enabled` and `useOfficialDomain=true`. Direct `hb-sdk build`, direct Vite build, anonymous or invalid snapshots, and local Dev Context overrides must keep the platform CSP. Runtime Gate, Manifest, and HTML validation always remain active.
+14. After approval, use `hb-sdk remote release <version>` for manual release or `--auto-publish` when an eligible low-risk version should release automatically.
+15. Treat approval, release, and public display as separate states. Do not promise square, search, or recommendation visibility after release.
+16. Use `hb-sdk remote withdraw`, `hb-sdk remote take-down`, `hb-sdk remote reopen`, and square visibility commands only after showing the target and obtaining required confirmation.
+17. Use `--json` for remote script consumption and `--verbose` only when concise output is insufficient for diagnosis.
+18. Use `hb-sdk doctor` to diagnose whether the local Skill matches the installed SDK; follow its output to install or refresh the Skill.
+19. Do not print or expose cookies, tokens, private headers, or other credentials.
 
 ## Step 6: Preserve capability boundaries
 

package/skill/references/api-root.md

@@ -23,7 +23,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.6.8-alpha.0`
+- Version at generation time: `0.6.8`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`
@@ -208,6 +208,7 @@ import { HB_SDK_VERSION } from '../core/version';
 import { renderMiniappManifest, validateMiniappPackageVersionForBuild } from '../miniapp-manifest/schema';
 import { readMiniappVersionFromPackageJson } from '../miniapp-manifest/node';
 import { enforceMiniappHtmlPolicy } from './html-policy';
+import { shouldSkipMiniappPlatformCspFromEnv } from './runtime-permission-env';
 
 type MiniappManifestPlugin = {
   name: string;
@@ -253,6 +254,7 @@ const sdkVersionPlaceholder = ['__HB_SDK', 'VERSION__'].join('_');
 const sdkVersionBuildConstant = ['__HB_SDK_BUILD', 'VERSION__'].join('_');
 
 export function miniappManifest(): MiniappManifestPlugin {
+  const skipPlatformCsp = shouldSkipMiniappPlatformCspFromEnv();
   let root = process.cwd();
   let outDir = 'dist';
   let command: 'build' | 'serve' = 'build';
@@ -285,6 +287,7 @@ export function miniappManifest(): MiniappManifestPlugin {
     transformIndexHtml(html) {
       return enforceMiniappHtmlPolicy(html, {
         ...(command === 'serve' ? { hmrWebSocketUrl } : {}),
+        skipPlatformCsp,
       });
     },
     async closeBundle() {
@@ -310,7 +313,7 @@ export function miniappManifest(): MiniappManifestPlugin {
       if (!htmlFiles.includes(indexHtmlPath)) {
         throw new Error('构建产物必须包含入口 dist/index.html');
       }
-      writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(readFileSync(indexHtmlPath, 'utf8')));
+      writeFileSync(indexHtmlPath, enforceMiniappHtmlPolicy(readFileSync(indexHtmlPath, 'utf8'), { skipPlatformCsp }));
 
       const manifestPath = path.join(outputRoot, 'manifest.json');
       mkdirSync(path.dirname(manifestPath), { recursive: true });
@@ -369,6 +372,8 @@ hb-sdk build [--env <name>] [--verbose]
 
 `hb-sdk build` 直接使用项目安装的 Vite，先清理再生成固定的 `dist/`，并校验小程序入口、Manifest 和可上传产物。它不执行类型检查，不要求 CLI 登录或绑定小程序，也不访问远端服务。项目必须在 `vite.config.ts` 中显式注册 `miniappManifest()`。
 
+直接运行 `hb-sdk build` 或 `vite build` 时默认注入平台 CSP。`hb-sdk remote deploy` 会在构建前读取绑定小程序的远端权限；仅当 `network.request.status=enabled` 且 `useOfficialDomain=true` 时向子构建传递已验证上下文并跳过平台 CSP。权限缺失、非法或读取失败时继续注入，Runtime Gate、Manifest 与 HTML 构建检查始终保留。
+
 推荐由项目的 `scripts.build` 保留类型检查：
 
 ```json