@heybox/hb-sdk 0.6.8-alpha.2 → 0.6.9-alpha.0

package/dist/miniapp-publish.esm.js

@@ -2834,6 +2834,10 @@ const UPDATE_SQUARE_DISPLAY_API_PATH = '/mall/developer/user_miniprogram/square_
 const LIST_USER_MINIPROGRAM_VERSION_API_PATH = '/mall/developer/user_miniprogram/version/list';
 const FNV_OFFSET = 0x811c9dc5;
 const FNV_PRIME = 0x01000193;
+const MINIAPP_UPLOAD_SESSION_REF_LENGTH = 10;
+const MINIAPP_ARTIFACT_SIGNATURE_MAGIC = 'heybox-user-miniprogram-artifact\0v1\0';
+const UNPAIRED_SURROGATE_PATTERN = /[\ud800-\udbff](?![\udc00-\udfff])|(^|[^\ud800-\udbff])[\udc00-\udfff]/;
+const textEncoder = new TextEncoder();
 function normalizeRelativePath(relativePath) {
     return String(relativePath || '')
         .replace(/\\/g, '/')
@@ -2927,5 +2931,201 @@ function shouldUploadDistFile(relativePath) {
     }
     return true;
 }
+/**
+ * 校验构建产物路径和大小，并按路径 UTF-8 字节序排序。
+ *
+ * @param files 待处理的构建产物文件。
+ * @returns 保留输入附加字段的有序文件列表。
+ * @throws 路径不规范、路径重复或文件大小非法时抛出错误。
+ */
+function prepareMiniappArtifactFiles(files) {
+    if (files.length > 0xffffffff) {
+        throw new Error('构建产物文件数量超出签名协议上限');
+    }
+    const usedPaths = new Set();
+    const prepared = files.map(file => {
+        const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
+        if (usedPaths.has(relativePath)) {
+            throw new Error(`构建产物包含重复文件路径：${relativePath}`);
+        }
+        usedPaths.add(relativePath);
+        validateArtifactFileSize(file.size, relativePath);
+        return { ...file, relativePath };
+    });
+    return prepared.sort((left, right) => compareBytes(textEncoder.encode(left.relativePath), textEncoder.encode(right.relativePath)));
+}
+/**
+ * 按服务端 session key 前缀校验最终上传路径的 UTF-8 字节长度。
+ *
+ * @param files 待上传的构建产物文件。
+ * @param options 小程序和长度限制配置。
+ * @returns 第一个超长路径的错误提示；全部合法时返回 `undefined`。
+ */
+function validateMiniappUploadPathLengths(files, options) {
+    const maxLength = options.maxLength ?? ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
+    const prefix = `/u/${getMiniProgramUploadAlias(options.miniProgramId)}/${'x'.repeat(MINIAPP_UPLOAD_SESSION_REF_LENGTH)}/`;
+    const prefixLength = textEncoder.encode(prefix).length;
+    const tooLongFile = files.find(file => {
+        const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
+        return prefixLength + textEncoder.encode(relativePath).length > maxLength;
+    });
+    return tooLongFile ? `文件路径过长，请缩短构建产物文件名或目录层级：${tooLongFile.relativePath}` : undefined;
+}
+/**
+ * 创建 v1 整包签名头。
+ *
+ * @param fileCount 参与签名的文件数量。
+ * @returns 包含协议标识和文件数量的字节数组。
+ * @throws 文件数量超出协议范围时抛出错误。
+ */
+function createMiniappArtifactSignatureHeader(fileCount) {
+    if (!Number.isInteger(fileCount) || fileCount < 0 || fileCount > 0xffffffff) {
+        throw new Error('构建产物文件数量超出签名协议上限');
+    }
+    return concatBytes(textEncoder.encode(MINIAPP_ARTIFACT_SIGNATURE_MAGIC), encodeUint32BE(fileCount));
+}
+/**
+ * 创建单个文件的 v1 framing header。
+ *
+ * @param file 已规范化或待校验的构建产物文件。
+ * @returns 包含路径长度、路径和文件大小的字节数组。
+ * @throws 文件路径或大小非法时抛出错误。
+ */
+function createMiniappArtifactFileHeader(file) {
+    const relativePath = normalizeMiniappArtifactRelativePath(file.relativePath);
+    validateArtifactFileSize(file.size, relativePath);
+    const pathBytes = textEncoder.encode(relativePath);
+    return concatBytes(encodeUint32BE(pathBytes.length), pathBytes, encodeUint64BE(file.size));
+}
+/**
+ * 校验服务端 session 文件映射，并计算仍需上传的文件。
+ *
+ * @param localFiles 本地构建产物文件。
+ * @param serverFiles 服务端签发的文件映射。
+ * @param uploadedKeys 服务端已确认上传成功的 key。
+ * @returns 完整映射、待上传文件和已确认 key。
+ * @throws 服务端映射与本地产物不一致时抛出错误。
+ */
+function resolveMiniappUploadSessionFiles(localFiles, serverFiles, uploadedKeys) {
+    const preparedFiles = prepareMiniappArtifactFiles(localFiles);
+    if (serverFiles.length !== preparedFiles.length) {
+        throw new Error(`上传会话文件数量异常：期望 ${preparedFiles.length}，实际 ${serverFiles.length}`);
+    }
+    const mappings = new Map();
+    const serverSizes = new Map();
+    const knownKeys = new Set();
+    for (const serverFile of serverFiles) {
+        const relativePath = normalizeMiniappArtifactRelativePath(serverFile.relative_path);
+        if (mappings.has(relativePath)) {
+            throw new Error(`上传会话返回重复文件路径：${relativePath}`);
+        }
+        const key = String(serverFile.key || '');
+        if (!key) {
+            throw new Error(`上传会话未返回文件 key：${relativePath}`);
+        }
+        if (knownKeys.has(key)) {
+            throw new Error(`上传会话返回重复文件 key：${relativePath}`);
+        }
+        const size = Number(serverFile.size);
+        if (!Number.isSafeInteger(size) || size < 0) {
+            throw new Error(`上传会话返回文件大小异常：${relativePath}`);
+        }
+        mappings.set(relativePath, key);
+        serverSizes.set(relativePath, size);
+        knownKeys.add(key);
+    }
+    const files = preparedFiles.map(file => {
+        const key = mappings.get(file.relativePath);
+        if (!key) {
+            throw new Error(`上传会话缺少文件映射：${file.relativePath}`);
+        }
+        if (serverSizes.get(file.relativePath) !== file.size) {
+            throw new Error(`上传会话文件大小与本地构建不一致：${file.relativePath}`);
+        }
+        return { file, key };
+    });
+    const completed = new Set();
+    for (const rawKey of uploadedKeys) {
+        const key = String(rawKey || '');
+        if (!knownKeys.has(key)) {
+            throw new Error('上传会话返回了不属于当前产物的已上传文件');
+        }
+        completed.add(key);
+    }
+    return {
+        files,
+        missingFiles: files.filter(file => !completed.has(file.key)),
+        uploadedKeys: [...completed],
+    };
+}
+function normalizeMiniappArtifactRelativePath(relativePath) {
+    const value = String(relativePath || '');
+    if (!value) {
+        throw new Error('构建产物包含空文件路径');
+    }
+    if (value.includes('\\')) {
+        throw new Error(`构建产物路径不能包含反斜杠：${value}`);
+    }
+    if (value.startsWith('/') || value.endsWith('/') || /^[a-zA-Z]:\//.test(value)) {
+        throw new Error(`构建产物必须使用相对文件路径：${value}`);
+    }
+    if (containsControlCharacter(value) || UNPAIRED_SURROGATE_PATTERN.test(value)) {
+        throw new Error(`构建产物路径包含非法字符：${value}`);
+    }
+    if (value.split('/').some(segment => !segment || segment === '.' || segment === '..')) {
+        throw new Error(`构建产物路径包含非法目录段：${value}`);
+    }
+    if (value.includes(',')) {
+        throw new Error(`构建产物路径不能包含逗号：${value}`);
+    }
+    if (value.includes('*') || value.includes('?')) {
+        throw new Error(`构建产物路径不能包含通配符：${value}`);
+    }
+    return value;
+}
+function containsControlCharacter(value) {
+    for (const character of value) {
+        const code = character.charCodeAt(0);
+        if (code <= 0x1f || (code >= 0x7f && code <= 0x9f)) {
+            return true;
+        }
+    }
+    return false;
+}
+function validateArtifactFileSize(size, relativePath) {
+    if (!Number.isSafeInteger(size) || size < 0) {
+        throw new Error(`构建产物文件大小无效：${relativePath}`);
+    }
+}
+function encodeUint32BE(value) {
+    const bytes = new Uint8Array(4);
+    new DataView(bytes.buffer).setUint32(0, value, false);
+    return bytes;
+}
+function encodeUint64BE(value) {
+    const bytes = new Uint8Array(8);
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, Math.floor(value / 0x100000000), false);
+    view.setUint32(4, value % 0x100000000, false);
+    return bytes;
+}
+function concatBytes(...parts) {
+    const result = new Uint8Array(parts.reduce((total, part) => total + part.length, 0));
+    let offset = 0;
+    for (const part of parts) {
+        result.set(part, offset);
+        offset += part.length;
+    }
+    return result;
+}
+function compareBytes(left, right) {
+    const length = Math.min(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        if (left[index] !== right[index]) {
+            return left[index] - right[index];
+        }
+    }
+    return left.length - right.length;
+}
 
-export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, CREATE_USER_MINIPROGRAM_API_PATH, CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DETAIL_USER_MINIPROGRAM_API_PATH, DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DEVELOPER_ENTITY_LIST_API_PATH, DEVELOPER_ENTITY_SWITCH_API_PATH, LIST_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH, LIST_USER_MINIPROGRAM_VERSION_API_PATH, MINIAPP_UPLOAD_BATCH_SIZE, MINIAPP_UPLOAD_SCOPE, MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES, PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH, RELEASE_USER_MINIPROGRAM_VERSION_API_PATH, REOPEN_USER_MINIPROGRAM_API_PATH, SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH, TAKE_DOWN_USER_MINIPROGRAM_API_PATH, UPDATE_SQUARE_DISPLAY_API_PATH, UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_ACCESS_STATUS_API_PATH, USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH, WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH, getMiniProgramUploadAlias, getMiniappUploadKey, isValidMiniappManifestVersion as isValidVersion, normalizeRelativePath, relativePathContainsNodeModulesSegment, shouldUploadDistFile, validateUploadPaths, validateUploadTotalSize };
+export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, CREATE_USER_MINIPROGRAM_API_PATH, CREATE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DELETE_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DETAIL_USER_MINIPROGRAM_API_PATH, DETAIL_USER_MINIPROGRAM_LEADERBOARD_API_PATH, DEVELOPER_ENTITY_LIST_API_PATH, DEVELOPER_ENTITY_SWITCH_API_PATH, LIST_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_LEADERBOARD_API_PATH, LIST_USER_MINIPROGRAM_VERSION_API_PATH, MINIAPP_UPLOAD_BATCH_SIZE, MINIAPP_UPLOAD_SCOPE, MINIAPP_UPLOAD_TOTAL_SIZE_LIMIT_BYTES, PRECHECK_USER_MINIPROGRAM_VERSION_API_PATH, RELEASE_USER_MINIPROGRAM_VERSION_API_PATH, REOPEN_USER_MINIPROGRAM_API_PATH, SUBMIT_USER_MINIPROGRAM_AUDIT_API_PATH, TAKE_DOWN_USER_MINIPROGRAM_API_PATH, UPDATE_SQUARE_DISPLAY_API_PATH, UPDATE_USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_ACCESS_STATUS_API_PATH, USER_MINIPROGRAM_PREVIEW_ALLOWLIST_API_PATH, USER_MINIPROGRAM_VERSION_PREVIEW_INFO_API_PATH, WITHDRAW_USER_MINIPROGRAM_VERSION_API_PATH, createMiniappArtifactFileHeader, createMiniappArtifactSignatureHeader, getMiniProgramUploadAlias, getMiniappUploadKey, isValidMiniappManifestVersion as isValidVersion, normalizeRelativePath, prepareMiniappArtifactFiles, relativePathContainsNodeModulesSegment, resolveMiniappUploadSessionFiles, shouldUploadDistFile, validateMiniappUploadPathLengths, validateUploadPaths, validateUploadTotalSize };

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.2';
+    : '0.6.9-alpha.0';
 
 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.2';
+    : '0.6.9-alpha.0';
 
 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.2",
+  "version": "0.6.9-alpha.0",
   "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.11"
   },
   "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.2`
+- Version at generation time: `0.6.9-alpha.0`
 - 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

package/skill/references/cli.md

@@ -106,6 +106,8 @@ CLI 会启动页面服务并自动打开本地调试页。调试页会展示小
 
 未登录或未绑定小程序时，浏览器、Mac 和手机调试入口仍然可用，但受管能力会默认拒绝。登录并绑定后，调试页才能根据当前小程序的线上配置提示差异。
 
+`hb-sdk dev` 会在启动 Vite 前读取远端权限。只有远端权限快照有效、`network.request.status=enabled` 且 `useOfficialDomain=true` 时才跳过平台 CSP；未登录、未绑定、读取失败、非法快照或仅在 Dev Context 中开启本地权限覆盖时都继续注入 CSP。
+
 ### 2. 先用浏览器 Mock 验收
 
 浏览器 Mock 支持热更新，适合快速检查：
@@ -152,6 +154,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
@@ -192,6 +196,14 @@ hb-sdk remote deploy --release-note "修复登录状态展示"
 
 这条命令会完成检查、执行项目的 `scripts.build`、上传和提交审核，因此项目定义的类型检查仍会执行。默认在审核通过后等待手动发布；普通低风险版本可以追加 `--auto-publish`。完整命令见 `hb-sdk remote --help`，提交要求见[小程序工坊上架规则](https://docs.xiaoheihe.cn/hb_sdk/guide/mini-program-publishing-rules)。
 
+构建产物上传从 `0.6.8` 起强制使用服务端上传 session，`0.6.7` 及更早版本不能继续部署，请先升级 `@heybox/hb-sdk`。deploy 从整包签名开始到上传结束都把 `dist/` 视为稳定输出，不要在此期间由其他进程修改构建目录；上传中断后可重新执行 deploy，服务端会按已确认回执恢复缺失文件。
+
+普通 deploy 会按 API 环境、`miniProgramId` 和版本在本机缓存目录获取短文件锁，避免两个 CLI 进程同时构建并上传同一版本。进程异常退出后锁可按 PID 回收；缓存目录不可用时会降级为无锁执行，不影响上传主流程。`--from-version` 不执行本地构建和上传，因此不会获取该锁。
+
+上传信息、上传凭证和上传回调按每批最多 50 个文件串行处理，批内保持 4 并发。CLI 每批获取一次仅授权当前 session 目录前缀的凭证，并校验服务端返回的 key 和 size 与本地文件完全一致；任何异常都会停止后续上传且不会提交审核。
+
+普通构建上传时，CLI 会计算整包签名，并把相对路径和文件大小一起提交给服务端创建或恢复上传会话；同一账号下签名和文件清单一致时，服务端返回已有 session 与 `uploaded_keys`，CLI 只上传缺失文件。CLI 不保存本地上传会话缓存。构建产物变化时服务端会创建新的隔离目录，并尽力清理旧目录。上传回调在当前命令内失败会重试；仍失败时可重新执行 deploy，服务端根据 `uploaded_keys` 继续恢复，同 key 的 COS 重传是幂等的。
+
 Before publishing, `hb-sdk remote deploy` verifies that the bound mini-program belongs to the current developer account. If it does not, the command stops and asks the user to switch accounts.
 
 Agent rules:

package/skill/references/examples.md

@@ -48,7 +48,7 @@ export async function ensureLogin() {
 ### Network request
 
 ```ts
-import { ready, network, HbMiniProgramNetworkError } from '@heybox/hb-sdk';
+import { ready, network, HbMiniProgramNetworkError, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
 try {
   await ready();
@@ -59,9 +59,23 @@ try {
     validateStatus: status => status >= 200 && status < 400,
   });
   console.log(response.data.ok);
+
+  // form POST only: App Host does not support multipart/form-data
+  await network.request({
+    url: 'https://api.example.com/form',
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8',
+    },
+    data: new URLSearchParams({ gameId: '3', roleId: '1' }).toString(),
+  });
 } catch (error) {
   if (error instanceof HbMiniProgramNetworkError) {
-    console.warn(error.status, error.response?.data);
+    // Target HTTP non-2xx, or host-side network_error (message says so)
+    console.warn(error.status, error.message, error.data);
+  } else if (error instanceof HbMiniProgramSDKError) {
+    // e.g. INVALID_PARAMS for unsupported multipart shape
+    console.warn(error.code, error.message);
   }
 }
 ```
@@ -116,6 +130,7 @@ export default defineConfig({
 - Do not create raw `postMessage` bridge envelopes in business pages.
 - Do not call unsupported storage delete/clear/info operations.
 - Do not pass raw internal share/network protocol fields from mini-program code.
+- Do not send `multipart/form-data` (or handcrafted multipart bodies) through `network.request`; use form-urlencoded string body or a dedicated upload capability.
 - Do not treat `hb-sdk login` as iframe SDK authentication state.
 - Do not create a second mock runtime package when `hb-sdk dev` is the supported local mock workflow.
 - Do not import `@heybox/hb-sdk/vite` from iframe business code or fetch a deployed `manifest.json` directly.

package/skill/references/safety-boundaries.md

@@ -14,6 +14,8 @@
 - `auth.login()` 只能由明确的用户操作触发，不要在页面初始化时自动登录。
 - `on()` 返回取消监听函数，组件卸载或页面销毁时需要调用。
 - 业务网络请求使用 `network.request()`，不要依赖浏览器原生网络出口。
+- `network.request` 不支持 `multipart/form-data`；App Host 仅支持 form（`application/x-www-form-urlencoded`）与 JSON。表单请用 `URLSearchParams#toString()` 作为 `data`，文件上传请走专用上传能力。
+- 仅当远端已启用 `network.request` 且 `useOfficialDomain=true` 时，`hb-sdk dev` 与 `hb-sdk remote deploy` 构建才会跳过平台 CSP；其他构建继续注入平台 CSP。
 - 构建必须启用 `miniappManifest()`，推荐统一使用 `hb-sdk build`。
 
 ## Agent rules

package/skill/scripts/sync-references.mjs

@@ -587,7 +587,7 @@ export async function ensureLogin() {
 
 ### Network request
 
-${fenced('ts', `import { ready, network, HbMiniProgramNetworkError } from '@heybox/hb-sdk';
+${fenced('ts', `import { ready, network, HbMiniProgramNetworkError, HbMiniProgramSDKError } from '@heybox/hb-sdk';
 
 try {
   await ready();
@@ -598,9 +598,23 @@ try {
     validateStatus: status => status >= 200 && status < 400,
   });
   console.log(response.data.ok);
+
+  // form POST only: App Host does not support multipart/form-data
+  await network.request({
+    url: 'https://api.example.com/form',
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded; charset=utf-8',
+    },
+    data: new URLSearchParams({ gameId: '3', roleId: '1' }).toString(),
+  });
 } catch (error) {
   if (error instanceof HbMiniProgramNetworkError) {
-    console.warn(error.status, error.response?.data);
+    // Target HTTP non-2xx, or host-side network_error (message says so)
+    console.warn(error.status, error.message, error.data);
+  } else if (error instanceof HbMiniProgramSDKError) {
+    // e.g. INVALID_PARAMS for unsupported multipart shape
+    console.warn(error.code, error.message);
   }
 }`)}
 
@@ -646,6 +660,7 @@ export default defineConfig({
 - Do not create raw \`postMessage\` bridge envelopes in business pages.
 - Do not call unsupported storage delete/clear/info operations.
 - Do not pass raw internal share/network protocol fields from mini-program code.
+- Do not send \`multipart/form-data\` (or handcrafted multipart bodies) through \`network.request\`; use form-urlencoded string body or a dedicated upload capability.
 - Do not treat \`hb-sdk login\` as iframe SDK authentication state.
 - Do not create a second mock runtime package when \`hb-sdk dev\` is the supported local mock workflow.
 - Do not import \`@heybox/hb-sdk/vite\` from iframe business code or fetch a deployed \`manifest.json\` directly.

package/skill/skill.json

@@ -1,11 +1,11 @@
 {
   "name": "hb-sdk",
-  "skillVersion": "0.6.8-alpha.2+skill.03258ceeb905",
+  "skillVersion": "0.6.9-alpha.0+skill.a578097b3a33",
   "sdk": {
     "package": "@heybox/hb-sdk",
-    "version": "0.6.8-alpha.2",
-    "compatibility": "0.6.8-alpha.2"
+    "version": "0.6.9-alpha.0",
+    "compatibility": "0.6.9-alpha.0"
   },
   "source": "https://open.xiaoheihe.cn/agent-skills/hb-sdk",
-  "integrity": "sha256-03258ceeb90522900faaeb182c1949333923c794a9f4ff83530923585302fddb"
+  "integrity": "sha256-a578097b3a3302d8149c3a09107a71516d84861022ddc4adb6ef1d465a423bfa"
 }

package/types/core/network-sanitize.d.ts

@@ -0,0 +1,31 @@
+/**
+ * network.request 诊断日志的纯脱敏工具。
+ *
+ * @remarks
+ * 放在 `core` 而非 `modules/network`：无错误类型依赖，供 SDK 错误文案、
+ * modules observability、devtools Mock Host / proxy 共用，并满足 boundary
+ *（devtools 不得直接 import runtime capability modules）。
+ */
+export type MiniProgramNetworkHeadersLike = Record<string, string>;
+/**
+ * 脱敏请求 URL：去掉 userinfo，并将 query / fragment 中的敏感参数值替换为 `[redacted]`。
+ */
+export declare function sanitizeNetworkRequestUrl(url: string): string;
+/**
+ * 脱敏请求/响应头；敏感名（含 heybox 前缀）替换为 `[redacted]`。
+ */
+export declare function sanitizeNetworkHeaders(headers?: MiniProgramNetworkHeadersLike): MiniProgramNetworkHeadersLike;
+/**
+ * 预览请求/响应 data：递归脱敏敏感字段，截断长文本与大数组。
+ */
+export declare function previewNetworkData(data: unknown): unknown;
+/**
+ * 递归脱敏日志对象（payload / result）：敏感 key、headers、url 字段统一处理。
+ */
+export declare function redactNetworkLogValue(value: unknown): unknown;
+/**
+ * 诊断 message 中的 URL 片段做脱敏，避免 error.message 二次泄漏 query secrets。
+ */
+export declare function sanitizeDiagnosticMessage(message: string): string;
+export declare function isSensitiveNetworkHeaderName(headerName: string): boolean;
+export declare function isSensitiveNetworkKey(key: string): boolean;