@heybox/hb-sdk 0.4.5 → 0.4.6

package/dist/cli-chunks/{session-BAgaqpNL.cjs → session-D7lF9mpd.cjs}

@@ -1,7 +1,8 @@
 'use strict';
 
+var index = require('./index-DuwxUSkq.cjs');
+var node_crypto = require('node:crypto');
 var path = require('node:path');
-var index = require('./index-BYMTp2I6.cjs');
 var require$$0$2 = require('fs');
 var require$$0 = require('constants');
 var require$$0$1 = require('stream');
@@ -66,6 +67,281 @@ function isTruthyEnvFlag(value) {
         .toLowerCase());
 }
 
+const globalHeyboxCliRequestConfig = {};
+function readHeyboxCliRequestConfig() {
+    return normalizeHeyboxRylaiServiceTagConfig(globalHeyboxCliRequestConfig);
+}
+function resolveHeyboxRylaiServiceTag(pathWithQuery, config = readHeyboxCliRequestConfig()) {
+    const normalized = normalizeHeyboxRylaiServiceTagConfig(config);
+    const pathname = pathWithQuery ? getPathname(pathWithQuery) : '';
+    const specialTag = normalized.special_tag;
+    if (pathname && specialTag?.path_prefix_list.some((prefix) => pathname.startsWith(prefix))) {
+        return specialTag.tag_name;
+    }
+    return normalized.default_tag;
+}
+function normalizeHeyboxRylaiServiceTagConfig(config) {
+    const defaultTag = normalizeHeyboxRylaiServiceTag(config.default_tag);
+    const specialTagName = normalizeHeyboxRylaiServiceTag(config.special_tag?.tag_name);
+    const pathPrefixList = config.special_tag?.path_prefix_list?.filter(isValidPathPrefix) || [];
+    return {
+        ...(defaultTag ? { default_tag: defaultTag } : {}),
+        ...(specialTagName && pathPrefixList.length
+            ? {
+                special_tag: {
+                    tag_name: specialTagName,
+                    path_prefix_list: pathPrefixList,
+                },
+            }
+            : {}),
+    };
+}
+function normalizeHeyboxRylaiServiceTag(value) {
+    const tag = String(value ?? '').trim();
+    if (!tag) {
+        return undefined;
+    }
+    if (/[\r\n]/.test(tag)) {
+        throw new Error('x-rylai-service-tag 不允许包含换行符');
+    }
+    return tag;
+}
+function isValidPathPrefix(value) {
+    return typeof value === 'string' && value.startsWith('/') && !/[\r\n]/.test(value);
+}
+function getPathname(pathWithQuery) {
+    try {
+        return new URL(pathWithQuery, 'https://api.xiaoheihe.cn').pathname;
+    }
+    catch {
+        return '';
+    }
+}
+
+const SIGN_VERSION = '999.0.4';
+const SIGN_CHARSET = 'AB45STUVWZEFGJ6CH01D237IXYPQRKLMN89';
+function createHeyboxOpenPlatformSignParams(pathname, options = {}) {
+    const now = options.now ?? new Date();
+    const time = Math.trunc(now.getTime() / 1000);
+    const nonce = options.nonce ?? md5(`${time}${Date.now()}${node_crypto.randomBytes(16).toString('hex')}`).toUpperCase();
+    return {
+        version: SIGN_VERSION,
+        hkey: generateSignature(pathname, time + 1, nonce),
+        _time: time,
+        nonce,
+    };
+}
+function generateSignature(path, time, nonce) {
+    const normalizedPath = `/${path
+        .split('/')
+        .filter(Boolean)
+        .join('/')}/`;
+    const transformedTime = transformWithOffset(String(time), SIGN_CHARSET, -2);
+    const transformedPath = transform(normalizedPath, SIGN_CHARSET);
+    const transformedNonce = transform(nonce, SIGN_CHARSET);
+    const combined = interleave([transformedTime, transformedPath, transformedNonce]).slice(0, 20);
+    const hash = md5(combined);
+    let sign = `${mixColumns(hash.slice(-6).split('').map((char) => char.charCodeAt(0))).reduce((sum, value) => sum + value, 0) % 100}`;
+    sign = sign.length < 2 ? `0${sign}` : sign;
+    return `${transformWithOffset(hash.substring(0, 5), SIGN_CHARSET, -4)}${sign}`;
+}
+function transformWithOffset(str, charset, offset) {
+    return transform(str, charset.slice(0, offset));
+}
+function transform(str, charset) {
+    let output = '';
+    for (let index = 0; index < str.length; index += 1) {
+        output += charset[str.charCodeAt(index) % charset.length];
+    }
+    return output;
+}
+function interleave(strings) {
+    let output = '';
+    const maxLength = Math.max(...strings.map((str) => str.length));
+    for (let index = 0; index < maxLength; index += 1) {
+        for (const str of strings) {
+            if (index < str.length) {
+                output += str[index];
+            }
+        }
+    }
+    return output;
+}
+function mixColumns(column) {
+    const output = [...column];
+    output[0] = multiplyE(column[0]) ^ multiply4(column[1]) ^ multiply3(column[2]) ^ multiply2(column[3]);
+    output[1] = multiply2(column[0]) ^ multiplyE(column[1]) ^ multiply4(column[2]) ^ multiply3(column[3]);
+    output[2] = multiply3(column[0]) ^ multiply2(column[1]) ^ multiplyE(column[2]) ^ multiply4(column[3]);
+    output[3] = multiply4(column[0]) ^ multiply3(column[1]) ^ multiply2(column[2]) ^ multiplyE(column[3]);
+    return output;
+}
+function multiply1(value) {
+    if (value & 0x80) {
+        return ((value << 1) ^ 0x1b) & 0xff;
+    }
+    return value << 1;
+}
+function multiply2(value) {
+    return multiply1(value) ^ value;
+}
+function multiply3(value) {
+    return multiply2(multiply1(value));
+}
+function multiply4(value) {
+    return multiply3(multiply2(multiply1(value)));
+}
+function multiplyE(value) {
+    return multiply4(value) ^ multiply3(value) ^ multiply2(value);
+}
+function md5(input) {
+    return node_crypto.createHash('md5').update(input).digest('hex');
+}
+
+const DEFAULT_PLATFORM_PARAMS = {
+    os_type: 'web',
+    app: 'heybox',
+    x_client_type: 'web',
+    x_os_type: 'Mac',
+    x_app: 'heybox',
+    x_client_version: '999.999.999',
+};
+const HEYBOX_WEB_REFERER = 'https://www.xiaoheihe.cn/';
+function resolveHeyboxId(session) {
+    if (session.heyboxId.trim()) {
+        return session.heyboxId.trim();
+    }
+    return session.cookieHeader
+        .split(';')
+        .map((part) => part.trim())
+        .find((part) => part.startsWith('heybox_id='))
+        ?.slice('heybox_id='.length);
+}
+function createHeyboxAuthHeaders(session, options = {}) {
+    const serviceTag = resolveHeyboxRylaiServiceTag(options.pathWithQuery);
+    return {
+        Cookie: session.cookieHeader,
+        Referer: HEYBOX_WEB_REFERER,
+        ...(options.contentType ? { 'Content-Type': options.contentType } : {}),
+        ...(serviceTag ? { 'x-rylai-service-tag': serviceTag } : {}),
+    };
+}
+function createHeyboxRequestContext(session, options = {}) {
+    const heyboxId = resolveHeyboxId(session);
+    const serviceTag = resolveHeyboxRylaiServiceTag(options.pathWithQuery);
+    return {
+        baseUrl: HEYBOX_API_BASE_URL,
+        headers: createHeyboxAuthHeaders(session, options),
+        platformParams: {
+            ...DEFAULT_PLATFORM_PARAMS,
+            ...options.platformParams,
+            ...(heyboxId ? { heybox_id: heyboxId } : {}),
+            ...(serviceTag ? { special_tag: serviceTag } : {}),
+        },
+    };
+}
+function createHeyboxOpenPlatformRequestContext(session, pathWithQuery, options = {}) {
+    return createHeyboxRequestContext(session, {
+        ...options,
+        pathWithQuery,
+        platformParams: {
+            x_app: 'heybox_website',
+            ...createHeyboxOpenPlatformSignParams(getApiPathname(pathWithQuery)),
+            ...options.platformParams,
+        },
+    });
+}
+function createHeyboxApiUrl(baseUrl, pathWithQuery, params) {
+    const url = new URL(pathWithQuery, baseUrl);
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== '') {
+            url.searchParams.set(key, String(value));
+        }
+    }
+    return url.toString();
+}
+function getApiPathname(pathWithQuery) {
+    return new URL(pathWithQuery, HEYBOX_API_BASE_URL).pathname;
+}
+const ENVELOPE_BODY_PREVIEW_LENGTH = 1000;
+async function readHeyboxApiEnvelope(response, options) {
+    const rawBody = await response.text();
+    let envelope = null;
+    let parseError = null;
+    if (rawBody) {
+        try {
+            envelope = JSON.parse(rawBody);
+        }
+        catch (error) {
+            parseError = error;
+        }
+    }
+    const envelopeOk = envelope?.status === 'ok' && (!options.requireResult || envelope?.result !== undefined);
+    if (response.ok && envelopeOk) {
+        return envelope.result;
+    }
+    const { message, verboseMessage } = formatHeyboxEnvelopeError({
+        response,
+        envelope,
+        parseError,
+        rawBody,
+        pathWithQuery: options.pathWithQuery,
+    });
+    throw new index.CliError(message, verboseMessage);
+}
+function formatHeyboxEnvelopeError(input) {
+    const parts = [`Heybox API ${input.pathWithQuery} failed`, `HTTP ${input.response.status}`];
+    if (input.envelope) {
+        const msg = typeof input.envelope.msg === 'string' ? input.envelope.msg.trim() : '';
+        const sbeUserMessage = readSbeUserMessage(input.envelope.result);
+        parts.push(`msg=${msg || '(empty)'}`);
+        if (typeof input.envelope.status === 'string') {
+            parts.push(`envelope.status=${input.envelope.status}`);
+        }
+        const { status: _s, msg: _m, result: _r, ...extras } = input.envelope;
+        if (Object.keys(extras).length > 0) {
+            parts.push(`extras=${truncate(safeJsonStringify(extras), ENVELOPE_BODY_PREVIEW_LENGTH)}`);
+        }
+        if (input.envelope.result !== undefined) {
+            parts.push(`result=${truncate(safeJsonStringify(input.envelope.result), ENVELOPE_BODY_PREVIEW_LENGTH)}`);
+        }
+        return {
+            message: sbeUserMessage || msg || `Heybox API ${input.pathWithQuery} 请求失败`,
+            verboseMessage: parts.join(' '),
+        };
+    }
+    if (input.parseError) {
+        const parseMsg = input.parseError instanceof Error ? input.parseError.message : String(input.parseError);
+        parts.push(`parseError=${parseMsg}`);
+    }
+    parts.push(input.rawBody ? `body=${truncate(input.rawBody, ENVELOPE_BODY_PREVIEW_LENGTH)}` : 'body=(empty)');
+    return {
+        message: `Heybox API ${input.pathWithQuery} 请求失败`,
+        verboseMessage: parts.join(' '),
+    };
+}
+function readSbeUserMessage(result) {
+    if (!result || typeof result !== 'object') {
+        return '';
+    }
+    const sbe = result.sbe;
+    if (!sbe || typeof sbe !== 'object') {
+        return '';
+    }
+    const userMessage = sbe.user_message;
+    return typeof userMessage === 'string' ? userMessage.trim() : '';
+}
+function truncate(value, max) {
+    return value.length > max ? `${value.slice(0, max)}...(+${value.length - max} chars)` : value;
+}
+function safeJsonStringify(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+
 var fs$1 = {};
 
 var universalify = {};
@@ -2959,20 +3235,39 @@ async function requireHeyboxAuthSession(options = {}) {
     return session;
 }
 async function writeHeyboxAuthSession(session, options = {}) {
-    const cacheFile = getAuthCacheFilePath(options);
     const cache = {
         version: AUTH_CACHE_VERSION,
         updatedAt: (options.now?.() ?? new Date()).toISOString(),
         heybox: session,
     };
-    await fs.ensureDir(path.dirname(cacheFile));
-    await fs.writeJson(cacheFile, cache, { spaces: 2 });
-    await fs.chmod(cacheFile, 0o600);
-    return cache;
+    return writeAuthCache(cache, options);
 }
 async function clearHeyboxAuthSession(options = {}) {
     await fs.remove(getAuthCacheFilePath(options));
 }
+function createSelectedDeveloperEntitySnapshot(input, options = {}) {
+    return {
+        entityId: input.entityId,
+        entityName: input.entityName,
+        ...(input.ownerHeyboxId === undefined ? {} : { ownerHeyboxId: input.ownerHeyboxId }),
+        selectedAt: (options.now?.() ?? new Date()).toISOString(),
+    };
+}
+async function setSelectedDeveloperEntitySnapshot(input, options = {}) {
+    const cache = await readAuthCache(options);
+    if (!cache.heybox) {
+        throw new Error('未发现 Heybox 登录态，请先运行 hb-sdk login');
+    }
+    const selectedEntity = createSelectedDeveloperEntitySnapshot(input, options);
+    return writeAuthCache({
+        version: AUTH_CACHE_VERSION,
+        updatedAt: (options.now?.() ?? new Date()).toISOString(),
+        heybox: {
+            ...cache.heybox,
+            selectedEntity,
+        },
+    }, options);
+}
 async function readRedactedHeyboxAuthStatus(options = {}) {
     const cacheFile = getAuthCacheFilePath(options);
     const session = await readHeyboxAuthSession(options);
@@ -2988,8 +3283,16 @@ async function readRedactedHeyboxAuthStatus(options = {}) {
         loginBaseUrl: session.loginBaseUrl,
         loggedIn: true,
         loggedInAt: session.loggedInAt,
+        ...(session.selectedEntity ? { selectedEntity: session.selectedEntity } : {}),
     };
 }
+async function writeAuthCache(cache, options = {}) {
+    const cacheFile = getAuthCacheFilePath(options);
+    await fs.ensureDir(path.dirname(cacheFile));
+    await fs.writeJson(cacheFile, cache, { spaces: 2 });
+    await fs.chmod(cacheFile, 0o600);
+    return cache;
+}
 function createEmptyAuthCache(options = {}) {
     return {
         version: AUTH_CACHE_VERSION,
@@ -3020,21 +3323,56 @@ function isHeyboxAuthSession(value) {
         typeof value.loggedInAt === 'string');
 }
 function normalizeHeyboxAuthSession(session) {
-    return {
-        ...session,
+    const normalized = {
+        heyboxId: session.heyboxId,
+        pkey: session.pkey,
+        xXhhHeyboxId: session.xXhhHeyboxId,
+        cookieHeader: session.cookieHeader,
+        loggedInAt: session.loggedInAt,
         loginBaseUrl: resolveHeyboxLoginBaseUrl({ loginBaseUrl: session.loginBaseUrl }),
     };
+    const selectedEntity = normalizeSelectedDeveloperEntitySnapshot(session.selectedEntity);
+    if (selectedEntity) {
+        normalized.selectedEntity = selectedEntity;
+    }
+    return normalized;
+}
+function normalizeSelectedDeveloperEntitySnapshot(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    if (typeof value.entityId !== 'number' || !Number.isFinite(value.entityId)) {
+        return undefined;
+    }
+    if (typeof value.entityName !== 'string' || value.entityName.length === 0) {
+        return undefined;
+    }
+    if (value.ownerHeyboxId !== undefined && (typeof value.ownerHeyboxId !== 'number' || !Number.isFinite(value.ownerHeyboxId))) {
+        return undefined;
+    }
+    if (typeof value.selectedAt !== 'string' || value.selectedAt.length === 0) {
+        return undefined;
+    }
+    return {
+        entityId: value.entityId,
+        entityName: value.entityName,
+        ...(value.ownerHeyboxId === undefined ? {} : { ownerHeyboxId: value.ownerHeyboxId }),
+        selectedAt: value.selectedAt,
+    };
 }
 function isRecord(value) {
     return Object.prototype.toString.call(value) === '[object Object]';
 }
 
-exports.HEYBOX_API_BASE_URL = HEYBOX_API_BASE_URL;
 exports.clearHeyboxAuthSession = clearHeyboxAuthSession;
+exports.createHeyboxApiUrl = createHeyboxApiUrl;
 exports.createHeyboxAuthSession = createHeyboxAuthSession;
+exports.createHeyboxOpenPlatformRequestContext = createHeyboxOpenPlatformRequestContext;
 exports.getAuthCacheFilePath = getAuthCacheFilePath;
+exports.readHeyboxApiEnvelope = readHeyboxApiEnvelope;
 exports.readRedactedHeyboxAuthStatus = readRedactedHeyboxAuthStatus;
 exports.requireHeyboxAuthSession = requireHeyboxAuthSession;
 exports.resolveHeyboxApiBaseUrl = resolveHeyboxApiBaseUrl;
 exports.resolveHeyboxLoginBaseUrl = resolveHeyboxLoginBaseUrl;
+exports.setSelectedDeveloperEntitySnapshot = setSelectedDeveloperEntitySnapshot;
 exports.writeHeyboxAuthSession = writeHeyboxAuthSession;

package/dist/cli.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var index = require('./cli-chunks/index-BYMTp2I6.cjs');
+var index = require('./cli-chunks/index-DuwxUSkq.cjs');
 require('node:module');
 require('node:fs');
 require('node:fs/promises');

package/dist/miniapp-publish.cjs.js

@@ -2812,6 +2812,8 @@ function getMiniappManifestVersionError(version) {
 const MINIAPP_UPLOAD_SCOPE = 'activity';
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = '/mall/developer/user_miniprogram/access_status';
+const DEVELOPER_ENTITY_LIST_API_PATH = '/mall/developer/entity/list';
+const DEVELOPER_ENTITY_SWITCH_API_PATH = '/mall/developer/entity/switch';
 const LIST_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/list';
 const CREATE_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/create';
 const UPDATE_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/update';
@@ -2887,6 +2889,8 @@ function shouldUploadDistFile(relativePath) {
 exports.ACTIVITY_UPLOAD_KEY_MAX_LENGTH = ACTIVITY_UPLOAD_KEY_MAX_LENGTH;
 exports.CREATE_USER_MINIPROGRAM_API_PATH = CREATE_USER_MINIPROGRAM_API_PATH;
 exports.DETAIL_USER_MINIPROGRAM_API_PATH = DETAIL_USER_MINIPROGRAM_API_PATH;
+exports.DEVELOPER_ENTITY_LIST_API_PATH = DEVELOPER_ENTITY_LIST_API_PATH;
+exports.DEVELOPER_ENTITY_SWITCH_API_PATH = DEVELOPER_ENTITY_SWITCH_API_PATH;
 exports.LIST_USER_MINIPROGRAM_API_PATH = LIST_USER_MINIPROGRAM_API_PATH;
 exports.LIST_USER_MINIPROGRAM_VERSION_API_PATH = LIST_USER_MINIPROGRAM_VERSION_API_PATH;
 exports.MINIAPP_UPLOAD_SCOPE = MINIAPP_UPLOAD_SCOPE;

package/dist/miniapp-publish.esm.js

@@ -2810,6 +2810,8 @@ function getMiniappManifestVersionError(version) {
 const MINIAPP_UPLOAD_SCOPE = 'activity';
 const ACTIVITY_UPLOAD_KEY_MAX_LENGTH = 64;
 const USER_MINIPROGRAM_ACCESS_STATUS_API_PATH = '/mall/developer/user_miniprogram/access_status';
+const DEVELOPER_ENTITY_LIST_API_PATH = '/mall/developer/entity/list';
+const DEVELOPER_ENTITY_SWITCH_API_PATH = '/mall/developer/entity/switch';
 const LIST_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/list';
 const CREATE_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/create';
 const UPDATE_USER_MINIPROGRAM_API_PATH = '/mall/developer/user_miniprogram/update';
@@ -2882,4 +2884,4 @@ function shouldUploadDistFile(relativePath) {
     return true;
 }
 
-export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, CREATE_USER_MINIPROGRAM_API_PATH, DETAIL_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_VERSION_API_PATH, MINIAPP_UPLOAD_SCOPE, 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_USER_MINIPROGRAM_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 };
+export { ACTIVITY_UPLOAD_KEY_MAX_LENGTH, CREATE_USER_MINIPROGRAM_API_PATH, DETAIL_USER_MINIPROGRAM_API_PATH, DEVELOPER_ENTITY_LIST_API_PATH, DEVELOPER_ENTITY_SWITCH_API_PATH, LIST_USER_MINIPROGRAM_API_PATH, LIST_USER_MINIPROGRAM_VERSION_API_PATH, MINIAPP_UPLOAD_SCOPE, 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_USER_MINIPROGRAM_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 };

package/dist/templates/vue3-vite-ts/README.md.ejs

@@ -21,7 +21,7 @@ npm run deploy
 
 - `npm run dev`：启动本地 Vite 服务和 `hb-sdk` 内置 mock runtime host，适合本地调试 SDK 能力；调试页内可点击按钮在 Mac 版 APP 中启动同一页面，也可以选择局域网网卡后用手机小黑盒 APP 扫码调试。手机需要与电脑处在同一局域网，并使用支持小程序调试壳的新版小黑盒 APP。Codex、VSCode 等内嵌浏览器可能无法唤起系统 APP，需要时请在系统浏览器中打开同一个调试页后重试。
 - `npm run build`：先执行 TypeScript 检查，再构建生产产物。
-- `npm run deploy -- --release-note "..."`：运行 `hb-sdk remote deploy`，构建、上传并提交当前小程序版本审核。部署前需要先通过 `hb-sdk remote create --name "..."` 创建并绑定远端小程序，或用 `hb-sdk remote bind <mini-program-id>` 绑定已有小程序，并执行过 `npx hb-sdk login`；默认审核通过后用 `hb-sdk remote versions` 查看状态，再用 `hb-sdk remote release <version>` 发布，如需审核通过后自动发布可追加 `--auto-publish`。顶层 `hb-sdk deploy` 已删除，不再作为兼容别名保留。
+- `npm run deploy -- --release-note "..."`：运行 `hb-sdk remote deploy`，构建、上传并提交当前小程序版本审核。部署前需要先执行过 `npx hb-sdk login`；多主体账号还应通过 `npx hb-sdk remote entity current` 确认服务端 current entity。远端小程序可通过 `npx hb-sdk remote create --name "..."` 在 current entity 下创建并绑定，或用 `npx hb-sdk remote bind <mini-program-id>` 绑定 current entity 可管理的已有小程序。`selectedEntity` 只是 CLI 登录缓存中的提示快照，实际 deploy/create/bind 以服务端 current entity 为准。默认审核通过后用 `hb-sdk remote versions` 查看状态，再用 `hb-sdk remote release <version>` 发布，如需审核通过后自动发布可追加 `--auto-publish`。顶层 `hb-sdk deploy` 已删除，不再作为兼容别名保留。
 
 ## 更多能力
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heybox/hb-sdk",
-  "version": "0.4.5",
+  "version": "0.4.6",
   "description": "",
   "exports": {
     ".": {

package/skill/SKILL.md

@@ -49,28 +49,30 @@ Apply these instructions when writing, reviewing, or debugging code that consume
 1. Use `hb-sdk create <project-name>` to scaffold a standalone external mini-program template.
 2. Use `hb-sdk dev` for local browser debugging through the built-in mock runtime host.
 3. Use `hb-sdk remote ...` for developer-owned remote mini-program management. Top-level `hb-sdk deploy` has been hard-cut and must not be recommended as a compatibility alias.
-4. Use `hb-sdk remote create --name <name>` to create a remote mini-program and bind the returned id into `package.json.heybox.miniProgramId`; use `hb-sdk remote bind <mini-program-id>` to bind an existing remote mini-program after manageability is verified.
-5. Use `hb-sdk remote info`, `hb-sdk remote update`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for read/basic/preview management workflows. Discovery commands may show multiple remote mini-programs, but write commands target the current project binding rather than arbitrary ids.
-6. Use `hb-sdk remote deploy --release-note <text>` to build, upload, and submit the current project for audit. It reads `package.json.heybox.miniProgramId`, prechecks `package.json.version` before build, runs the project's `build` script via the package manager auto-detected by lockfile, uploads `dist/` to CDN (skipping `manifest.json`, `.DS_Store`, `.map`), then calls the submit-audit API.
-7. Use `hb-sdk remote deploy --skip-build --release-note <text>` only when the `dist/` directory is already prepared by an upstream CI stage. In this mode the CLI reads `dist/manifest.json.version` before precheck. Missing `dist/manifest.json` or `dist/index.html` aborts the run.
-8. Always provide a concise release note before deploy. Non-interactive environments must pass `--release-note`; interactive terminals may prompt for it. The default is manual release after approval with `hb-sdk remote release <version>`; use `--auto-publish` when the audited version should automatically release after approval.
-9. Use `hb-sdk remote release <version>`, `hb-sdk remote withdraw <version>`, `hb-sdk remote take-down`, and `hb-sdk remote reopen` for dangerous remote changes. Interactive terminals should confirm after showing enough context; non-interactive environments must pass `--yes`.
-10. For internal test/staging backend operations, use origin-only custom URLs: `HB_SDK_API_BASE_URL` or `hb-sdk remote ... --api-base-url <url>` for remote platform APIs, and `HB_SDK_LOGIN_BASE_URL` or `hb-sdk login --login-base-url <url>` for browser login. CLI flags override env vars. API base URLs must be Heybox trusted HTTPS origins by default; use `--allow-unsafe-api-base-url` or `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` only for local backend debugging. Do not include path, query, or hash in these URLs.
-11. For development routing or gray validation, configure `packages/hb-sdk/src/cli/config.ts` with `@heybox/hb-types` `RylaiServiceTagConfig` (`default_tag` / path-specific `special_tag`) to attach `x-rylai-service-tag` and the matching `special_tag` query parameter to Heybox backend API requests.
-12. If a remote command targets a custom login environment, pass the same `--login-base-url` or `HB_SDK_LOGIN_BASE_URL` used for `hb-sdk login`; remote commands reject cached CLI login state from a different login origin.
-13. Add `--verbose` / `-v` only when diagnosing failures; default CLI errors are intentionally concise, while verbose output includes backend envelope, HTTP status, trace fields, raw body, or original submit-audit failure details.
-14. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
-15. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
-16. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; the phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
-17. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
-18. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
-19. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
-20. Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
-21. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
-22. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
-23. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
-24. Do not pass `mini_program_id` as a CLI flag or environment variable; it must come from `package.json.heybox.miniProgramId`.
-25. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publish-pipeline helpers is `@heybox/hb-sdk/miniapp-publish`.
+4. Use `hb-sdk remote entity list`, `hb-sdk remote entity current`, and `hb-sdk remote entity switch <entity-id>` to inspect or change the developer platform server-side current entity before remote management commands.
+5. Use `hb-sdk remote create --name <name>` to create a remote mini-program under the server-side current entity and bind the returned id into `package.json.heybox.miniProgramId`; use `hb-sdk remote bind <mini-program-id>` to bind an existing remote mini-program after current-entity manageability is verified.
+6. Use `hb-sdk remote info`, `hb-sdk remote update`, `hb-sdk remote list`, `hb-sdk remote access`, `hb-sdk remote versions`, `hb-sdk remote preview <version>`, and `hb-sdk remote allowlist ...` for read/basic/preview management workflows. Discovery commands show the server-side current entity scope; write commands target the current project binding rather than arbitrary ids.
+7. Use `hb-sdk remote deploy --release-note <text>` to build, upload, and submit the current project for audit. It reads `package.json.heybox.miniProgramId`, validates that the bound mini-program belongs to the server-side current entity before precheck/build/upload, prechecks `package.json.version` before build, runs the project's `build` script via the package manager auto-detected by lockfile, uploads `dist/` to CDN (skipping `manifest.json`, `.DS_Store`, `.map`), then calls the submit-audit API.
+8. Use `hb-sdk remote deploy --skip-build --release-note <text>` only when the `dist/` directory is already prepared by an upstream CI stage. In this mode the CLI reads `dist/manifest.json.version` before precheck. Missing `dist/manifest.json` or `dist/index.html` aborts the run.
+9. Always provide a concise release note before deploy. Non-interactive environments must pass `--release-note`; interactive terminals may prompt for it. The default is manual release after approval with `hb-sdk remote release <version>`; use `--auto-publish` when the audited version should automatically release after approval.
+10. Use `hb-sdk remote release <version>`, `hb-sdk remote withdraw <version>`, `hb-sdk remote take-down`, and `hb-sdk remote reopen` for dangerous remote changes. Interactive terminals should confirm after showing enough context; non-interactive environments must pass `--yes`.
+11. For internal test/staging backend operations, use origin-only custom URLs: `HB_SDK_API_BASE_URL` or `hb-sdk remote ... --api-base-url <url>` for remote platform APIs, and `HB_SDK_LOGIN_BASE_URL` or `hb-sdk login --login-base-url <url>` for browser login. CLI flags override env vars. API base URLs must be Heybox trusted HTTPS origins by default; use `--allow-unsafe-api-base-url` or `HB_SDK_ALLOW_UNSAFE_API_BASE_URL=1` only for local backend debugging. Do not include path, query, or hash in these URLs.
+12. For development routing or gray validation, configure `packages/hb-sdk/src/cli/config.ts` with `@heybox/hb-types` `RylaiServiceTagConfig` (`default_tag` / path-specific `special_tag`) to attach `x-rylai-service-tag` and the matching `special_tag` query parameter to Heybox backend API requests.
+13. If a remote command targets a custom login environment, pass the same `--login-base-url` or `HB_SDK_LOGIN_BASE_URL` used for `hb-sdk login`; remote commands reject cached CLI login state from a different login origin.
+14. Add `--verbose` / `-v` only when diagnosing failures; default CLI errors are intentionally concise, while verbose output includes backend envelope, HTTP status, trace fields, raw body, or original submit-audit failure details.
+15. Use `--json` for script consumption of `hb-sdk remote` commands. With `--json`, stdout must contain exactly one JSON object; progress, warnings, update reminders, and verbose diagnostics must not pollute stdout.
+16. Do not expect custom base URLs to affect `hb-sdk doctor`, npm latest checks, or mock-host `network.request()`.
+17. Use the Mock runtime host's "在 Mac 版 APP 中启动" button for Mac App debugging, or the "Mobile App" QR code after selecting a LAN interface for phone App debugging; the phone must be on the same LAN and use a Heybox App version that supports the mini-program dev shell.
+18. Use `--port`, `--mock-port`, and `--no-open` when the default Vite/mock ports or browser opening behavior need to be controlled.
+19. Use `hb-sdk login`, `hb-sdk login status`, and `hb-sdk login clear` only for the CLI's own Heybox auth cache. Keep `hb-sdk login` top-level; it is not a remote mini-program command.
+20. Treat `selectedEntity` in the CLI auth cache as a non-authoritative hint snapshot only. Every remote command must use the server-side current entity as the source of truth.
+21. Use `hb-sdk doctor` to diagnose whether the local `hb-sdk` skill matches the installed SDK and remote latest skill metadata.
+22. Do not use `hb-sdk doctor` to auto-install skills; when installation or refresh is needed, tell the user to run `npx skills add https://open.xiaoheihe.cn/agent-skills/hb-sdk`.
+23. If doctor reports `SDK_MISMATCH`, upgrade `@heybox/hb-sdk@latest` before reinstalling the skill.
+24. Do not treat CLI login cache as iframe SDK login state; it does not change `auth.login()`, `user.getInfo()`, `network.request()`, or mock-user behavior.
+25. Keep the CLI and mock runtime under `@heybox/hb-sdk`; do not create or revive a separate mock runtime package.
+26. Do not pass `mini_program_id` or `entity_id` as general CLI flags or environment variables; the mini-program id must come from `package.json.heybox.miniProgramId`, and the entity must come from the server-side current entity.
+27. Do not import deploy / upload internals from outside the CLI; the only externally consumable subpath for publish-pipeline helpers is `@heybox/hb-sdk/miniapp-publish`.
 
 ## Step 6: Preserve capability boundaries
 

package/skill/references/api-root.md

@@ -19,7 +19,7 @@
 ## Package metadata
 
 - Package: `@heybox/hb-sdk`
-- Version at generation time: `0.4.5`
+- Version at generation time: `0.4.6`
 - Public root export: `@heybox/hb-sdk`
 - Protocol export: `@heybox/hb-sdk/protocol`
 - Vite plugin export: `@heybox/hb-sdk/vite`