@midscene/shared 1.0.1-beta-20251118021215.0 → 1.0.1-beta-20251118060105.0

package/dist/es/env/decide-model-config.mjs

@@ -4,7 +4,7 @@ import { getDebug } from "../logger.mjs";
 import { assert } from "../utils.mjs";
 import { createAssert, maskConfig, parseJson } from "./helper.mjs";
 import { initDebugConfig } from "./init-debug.mjs";
-import { parseVlModeAndUiTarsFromGlobalConfig, parseVlModeAndUiTarsModelVersionFromRawValue } from "./parse.mjs";
+import { parseModelFamilyFromEnv, parseVlModeAndUiTarsFromGlobalConfig, parseVlModeAndUiTarsModelVersionFromRawValue } from "./parse.mjs";
 const KEYS_MAP = {
     insight: INSIGHT_MODEL_CONFIG_KEYS,
     planning: PLANNING_MODEL_CONFIG_KEYS,
@@ -41,6 +41,33 @@ const getModelDescription = (vlMode, uiTarsVersion)=>{
     else return `${vlMode} mode`;
     return '';
 };
+const parseVlModeForIntent = (intent, allEnvConfig, result, debugLog)=>{
+    if ('planning' === intent) {
+        const parseResult = parseModelFamilyFromEnv(allEnvConfig);
+        parseResult.warnings.forEach((warning)=>{
+            console.warn(`[Midscene] ${warning}`);
+        });
+        if (parseResult.modelFamily) debugLog(`Using model family: ${parseResult.modelFamily}`);
+        return {
+            vlMode: parseResult.vlMode,
+            uiTarsVersion: parseResult.uiTarsVersion
+        };
+    }
+    if (void 0 !== result.vlModeRaw) {
+        const parsed = parseVlModeAndUiTarsModelVersionFromRawValue(result.vlModeRaw);
+        return {
+            vlMode: parsed.vlMode,
+            uiTarsVersion: parsed.uiTarsVersion
+        };
+    }
+    {
+        const parsed = parseVlModeAndUiTarsFromGlobalConfig(allEnvConfig);
+        return {
+            vlMode: parsed.vlMode,
+            uiTarsVersion: parsed.uiTarsVersion
+        };
+    }
+};
 const decideModelConfigFromIntentConfig = (intent, intentConfig)=>{
     const debugLog = getDebug('ai:config');
     debugLog('decideModelConfig base on agent.modelConfig()');
@@ -87,7 +114,7 @@ const decideModelConfigFromEnv = (intent, allEnvConfig)=>{
             provider: allEnvConfig,
             valueAssert: createAssert(keysForEnv.modelName, 'process.env', modelName)
         });
-        const { vlMode, uiTarsVersion } = parseVlModeAndUiTarsModelVersionFromRawValue(result.vlModeRaw);
+        const { vlMode, uiTarsVersion } = parseVlModeForIntent(intent, allEnvConfig, result, debugLog);
         const modelDescription = getModelDescription(vlMode, uiTarsVersion);
         const finalResult = {
             ...result,
@@ -107,7 +134,7 @@ const decideModelConfigFromEnv = (intent, allEnvConfig)=>{
         provider: allEnvConfig,
         valueAssert: createAssert(DEFAULT_MODEL_CONFIG_KEYS_LEGACY.modelName, 'process.env')
     });
-    const { vlMode, uiTarsVersion } = parseVlModeAndUiTarsFromGlobalConfig(allEnvConfig);
+    const { vlMode, uiTarsVersion } = parseVlModeForIntent(intent, allEnvConfig, result, debugLog);
     const modelDescription = getModelDescription(vlMode, uiTarsVersion);
     const finalResult = {
         ...result,

package/dist/es/env/parse.mjs

@@ -1,4 +1,4 @@
-import { MIDSCENE_USE_DOUBAO_VISION, MIDSCENE_USE_GEMINI, MIDSCENE_USE_QWEN3_VL, MIDSCENE_USE_QWEN_VL, MIDSCENE_USE_VLM_UI_TARS, UITarsModelVersion, VL_MODE_RAW_VALID_VALUES } from "./types.mjs";
+import { MIDSCENE_MODEL_FAMILY, MIDSCENE_USE_DOUBAO_VISION, MIDSCENE_USE_GEMINI, MIDSCENE_USE_QWEN3_VL, MIDSCENE_USE_QWEN_VL, MIDSCENE_USE_VLM_UI_TARS, MODEL_FAMILY_VALUES, UITarsModelVersion, VL_MODE_RAW_VALID_VALUES } from "./types.mjs";
 const parseVlModeAndUiTarsModelVersionFromRawValue = (vlModeRaw)=>{
     if (!vlModeRaw) return {
         vlMode: void 0,
@@ -38,7 +38,7 @@ const parseVlModeAndUiTarsFromGlobalConfig = (provider)=>{
         uiTarsVersion: void 0
     };
     if (isQwen) return {
-        vlMode: 'qwen-vl',
+        vlMode: 'qwen2.5-vl',
         uiTarsVersion: void 0
     };
     if (isDoubao) return {
@@ -66,4 +66,53 @@ const parseVlModeAndUiTarsFromGlobalConfig = (provider)=>{
         uiTarsVersion: void 0
     };
 };
-export { parseVlModeAndUiTarsFromGlobalConfig, parseVlModeAndUiTarsModelVersionFromRawValue };
+const detectLegacyVlModeEnvVars = (provider)=>{
+    const legacyVars = [
+        MIDSCENE_USE_DOUBAO_VISION,
+        MIDSCENE_USE_QWEN_VL,
+        MIDSCENE_USE_QWEN3_VL,
+        MIDSCENE_USE_VLM_UI_TARS,
+        MIDSCENE_USE_GEMINI
+    ];
+    return legacyVars.filter((varName)=>provider[varName]);
+};
+function isValidModelFamily(value) {
+    return MODEL_FAMILY_VALUES.includes(value);
+}
+function mapLegacyToModelFamily(vlMode, uiTarsVersion) {
+    if (!vlMode) return;
+    if ('vlm-ui-tars' === vlMode) if (uiTarsVersion === UITarsModelVersion.V1_0) return 'vlm-ui-tars';
+    else if (uiTarsVersion === UITarsModelVersion.DOUBAO_1_5_20B) return 'vlm-ui-tars-doubao-1.5';
+    else return 'vlm-ui-tars-doubao';
+    return vlMode;
+}
+const parseModelFamilyFromEnv = (provider)=>{
+    const warnings = [];
+    const modelFamilyRaw = provider[MIDSCENE_MODEL_FAMILY];
+    const legacyVars = detectLegacyVlModeEnvVars(provider);
+    if (modelFamilyRaw && legacyVars.length > 0) throw new Error(`Conflicting configuration detected: Both MIDSCENE_MODEL_FAMILY and legacy environment variables (${legacyVars.join(', ')}) are set. Please use only MIDSCENE_MODEL_FAMILY.`);
+    if (modelFamilyRaw) {
+        if (!isValidModelFamily(modelFamilyRaw)) throw new Error(`Invalid MIDSCENE_MODEL_FAMILY value: "${modelFamilyRaw}". Must be one of: ${MODEL_FAMILY_VALUES.join(', ')}. See documentation: https://midscenejs.com/model-provider.html`);
+        const modelFamily = modelFamilyRaw;
+        const parsed = parseVlModeAndUiTarsModelVersionFromRawValue(modelFamily);
+        return {
+            vlMode: parsed.vlMode,
+            uiTarsVersion: parsed.uiTarsVersion,
+            modelFamily,
+            warnings
+        };
+    }
+    if (legacyVars.length > 0) {
+        const legacyResult = parseVlModeAndUiTarsFromGlobalConfig(provider);
+        warnings.push(`DEPRECATED: Environment ${legacyVars.length > 1 ? 'variables' : 'variable'} ${legacyVars.join(', ')} ${legacyVars.length > 1 ? 'are' : 'is'} deprecated. Please use MIDSCENE_MODEL_FAMILY instead. See migration guide for details.`);
+        const modelFamily = mapLegacyToModelFamily(legacyResult.vlMode, legacyResult.uiTarsVersion);
+        return {
+            vlMode: legacyResult.vlMode,
+            uiTarsVersion: legacyResult.uiTarsVersion,
+            modelFamily,
+            warnings
+        };
+    }
+    throw new Error(`MIDSCENE_MODEL_FAMILY is required for planning tasks. Please set it to one of: ${MODEL_FAMILY_VALUES.join(', ')}. See documentation: https://midscenejs.com/model-provider.html`);
+};
+export { detectLegacyVlModeEnvVars, parseModelFamilyFromEnv, parseVlModeAndUiTarsFromGlobalConfig, parseVlModeAndUiTarsModelVersionFromRawValue };

package/dist/es/env/types.mjs

@@ -56,6 +56,7 @@ const MIDSCENE_PLANNING_MODEL_BASE_URL = 'MIDSCENE_PLANNING_MODEL_BASE_URL';
 const MIDSCENE_PLANNING_MODEL_API_KEY = 'MIDSCENE_PLANNING_MODEL_API_KEY';
 const MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON = 'MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON';
 const MIDSCENE_PLANNING_LOCATOR_MODE = 'MIDSCENE_PLANNING_LOCATOR_MODE';
+const MIDSCENE_MODEL_FAMILY = 'MIDSCENE_MODEL_FAMILY';
 const UNUSED_ENV_KEYS = [
     MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG
 ];
@@ -129,7 +130,8 @@ const MODEL_ENV_KEYS = [
     MIDSCENE_PLANNING_MODEL_BASE_URL,
     MIDSCENE_PLANNING_MODEL_API_KEY,
     MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON,
-    MIDSCENE_PLANNING_LOCATOR_MODE
+    MIDSCENE_PLANNING_LOCATOR_MODE,
+    MIDSCENE_MODEL_FAMILY
 ];
 const ALL_ENV_KEYS = [
     ...UNUSED_ENV_KEYS,
@@ -137,20 +139,23 @@ const ALL_ENV_KEYS = [
     ...GLOBAL_ENV_KEYS,
     ...MODEL_ENV_KEYS
 ];
-var types_UITarsModelVersion = /*#__PURE__*/ function(UITarsModelVersion) {
-    UITarsModelVersion["V1_0"] = "1.0";
-    UITarsModelVersion["V1_5"] = "1.5";
-    UITarsModelVersion["DOUBAO_1_5_15B"] = "doubao-1.5-15B";
-    UITarsModelVersion["DOUBAO_1_5_20B"] = "doubao-1.5-20B";
-    return UITarsModelVersion;
-}({});
 const VL_MODE_RAW_VALID_VALUES = [
     'doubao-vision',
     'gemini',
-    'qwen-vl',
+    'qwen2.5-vl',
     'qwen3-vl',
     'vlm-ui-tars',
     'vlm-ui-tars-doubao',
     'vlm-ui-tars-doubao-1.5'
 ];
-export { ALL_ENV_KEYS, BASIC_ENV_KEYS, BOOLEAN_ENV_KEYS, DOCKER_CONTAINER, GLOBAL_ENV_KEYS, MATCH_BY_POSITION, MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, MIDSCENE_CACHE, MIDSCENE_CACHE_MAX_FILENAME_LENGTH, MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG, MIDSCENE_DEBUG_MODE, MIDSCENE_DEBUG_MODEL_PROFILE, MIDSCENE_DEBUG_MODEL_RESPONSE, MIDSCENE_FORCE_DEEP_THINK, MIDSCENE_INSIGHT_LOCATOR_MODE, MIDSCENE_INSIGHT_MODEL_API_KEY, MIDSCENE_INSIGHT_MODEL_BASE_URL, MIDSCENE_INSIGHT_MODEL_HTTP_PROXY, MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON, MIDSCENE_INSIGHT_MODEL_NAME, MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY, MIDSCENE_IOS_DEVICE_UDID, MIDSCENE_IOS_SIMULATOR_UDID, MIDSCENE_LOCATOR_MODE, MIDSCENE_MCP_ANDROID_MODE, MIDSCENE_MCP_CHROME_PATH, MIDSCENE_MCP_USE_PUPPETEER_MODE, MIDSCENE_MODEL_API_KEY, MIDSCENE_MODEL_BASE_URL, MIDSCENE_MODEL_HTTP_PROXY, MIDSCENE_MODEL_INIT_CONFIG_JSON, MIDSCENE_MODEL_MAX_TOKENS, MIDSCENE_MODEL_NAME, MIDSCENE_MODEL_SOCKS_PROXY, MIDSCENE_OPENAI_HTTP_PROXY, MIDSCENE_OPENAI_INIT_CONFIG_JSON, MIDSCENE_OPENAI_SOCKS_PROXY, MIDSCENE_PLANNING_LOCATOR_MODE, MIDSCENE_PLANNING_MODEL_API_KEY, MIDSCENE_PLANNING_MODEL_BASE_URL, MIDSCENE_PLANNING_MODEL_HTTP_PROXY, MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON, MIDSCENE_PLANNING_MODEL_NAME, MIDSCENE_PLANNING_MODEL_SOCKS_PROXY, MIDSCENE_PREFERRED_LANGUAGE, MIDSCENE_REPLANNING_CYCLE_LIMIT, MIDSCENE_REPORT_TAG_NAME, MIDSCENE_RUN_DIR, MIDSCENE_USE_DOUBAO_VISION, MIDSCENE_USE_GEMINI, MIDSCENE_USE_QWEN3_VL, MIDSCENE_USE_QWEN_VL, MIDSCENE_USE_VLM_UI_TARS, MIDSCENE_USE_VL_MODEL, MODEL_API_KEY, MODEL_BASE_URL, MODEL_ENV_KEYS, NUMBER_ENV_KEYS, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MAX_TOKENS, STRING_ENV_KEYS, types_UITarsModelVersion as UITarsModelVersion, UNUSED_ENV_KEYS, VL_MODE_RAW_VALID_VALUES };
+const MODEL_FAMILY_VALUES = [
+    ...VL_MODE_RAW_VALID_VALUES
+];
+var types_UITarsModelVersion = /*#__PURE__*/ function(UITarsModelVersion) {
+    UITarsModelVersion["V1_0"] = "1.0";
+    UITarsModelVersion["V1_5"] = "1.5";
+    UITarsModelVersion["DOUBAO_1_5_15B"] = "doubao-1.5-15B";
+    UITarsModelVersion["DOUBAO_1_5_20B"] = "doubao-1.5-20B";
+    return UITarsModelVersion;
+}({});
+export { ALL_ENV_KEYS, BASIC_ENV_KEYS, BOOLEAN_ENV_KEYS, DOCKER_CONTAINER, GLOBAL_ENV_KEYS, MATCH_BY_POSITION, MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, MIDSCENE_CACHE, MIDSCENE_CACHE_MAX_FILENAME_LENGTH, MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG, MIDSCENE_DEBUG_MODE, MIDSCENE_DEBUG_MODEL_PROFILE, MIDSCENE_DEBUG_MODEL_RESPONSE, MIDSCENE_FORCE_DEEP_THINK, MIDSCENE_INSIGHT_LOCATOR_MODE, MIDSCENE_INSIGHT_MODEL_API_KEY, MIDSCENE_INSIGHT_MODEL_BASE_URL, MIDSCENE_INSIGHT_MODEL_HTTP_PROXY, MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON, MIDSCENE_INSIGHT_MODEL_NAME, MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY, MIDSCENE_IOS_DEVICE_UDID, MIDSCENE_IOS_SIMULATOR_UDID, MIDSCENE_LOCATOR_MODE, MIDSCENE_MCP_ANDROID_MODE, MIDSCENE_MCP_CHROME_PATH, MIDSCENE_MCP_USE_PUPPETEER_MODE, MIDSCENE_MODEL_API_KEY, MIDSCENE_MODEL_BASE_URL, MIDSCENE_MODEL_FAMILY, MIDSCENE_MODEL_HTTP_PROXY, MIDSCENE_MODEL_INIT_CONFIG_JSON, MIDSCENE_MODEL_MAX_TOKENS, MIDSCENE_MODEL_NAME, MIDSCENE_MODEL_SOCKS_PROXY, MIDSCENE_OPENAI_HTTP_PROXY, MIDSCENE_OPENAI_INIT_CONFIG_JSON, MIDSCENE_OPENAI_SOCKS_PROXY, MIDSCENE_PLANNING_LOCATOR_MODE, MIDSCENE_PLANNING_MODEL_API_KEY, MIDSCENE_PLANNING_MODEL_BASE_URL, MIDSCENE_PLANNING_MODEL_HTTP_PROXY, MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON, MIDSCENE_PLANNING_MODEL_NAME, MIDSCENE_PLANNING_MODEL_SOCKS_PROXY, MIDSCENE_PREFERRED_LANGUAGE, MIDSCENE_REPLANNING_CYCLE_LIMIT, MIDSCENE_REPORT_TAG_NAME, MIDSCENE_RUN_DIR, MIDSCENE_USE_DOUBAO_VISION, MIDSCENE_USE_GEMINI, MIDSCENE_USE_QWEN3_VL, MIDSCENE_USE_QWEN_VL, MIDSCENE_USE_VLM_UI_TARS, MIDSCENE_USE_VL_MODEL, MODEL_API_KEY, MODEL_BASE_URL, MODEL_ENV_KEYS, MODEL_FAMILY_VALUES, NUMBER_ENV_KEYS, OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MAX_TOKENS, STRING_ENV_KEYS, types_UITarsModelVersion as UITarsModelVersion, UNUSED_ENV_KEYS, VL_MODE_RAW_VALID_VALUES };

package/dist/lib/env/decide-model-config.js

@@ -71,6 +71,33 @@ const getModelDescription = (vlMode, uiTarsVersion)=>{
     else return `${vlMode} mode`;
     return '';
 };
+const parseVlModeForIntent = (intent, allEnvConfig, result, debugLog)=>{
+    if ('planning' === intent) {
+        const parseResult = (0, external_parse_js_namespaceObject.parseModelFamilyFromEnv)(allEnvConfig);
+        parseResult.warnings.forEach((warning)=>{
+            console.warn(`[Midscene] ${warning}`);
+        });
+        if (parseResult.modelFamily) debugLog(`Using model family: ${parseResult.modelFamily}`);
+        return {
+            vlMode: parseResult.vlMode,
+            uiTarsVersion: parseResult.uiTarsVersion
+        };
+    }
+    if (void 0 !== result.vlModeRaw) {
+        const parsed = (0, external_parse_js_namespaceObject.parseVlModeAndUiTarsModelVersionFromRawValue)(result.vlModeRaw);
+        return {
+            vlMode: parsed.vlMode,
+            uiTarsVersion: parsed.uiTarsVersion
+        };
+    }
+    {
+        const parsed = (0, external_parse_js_namespaceObject.parseVlModeAndUiTarsFromGlobalConfig)(allEnvConfig);
+        return {
+            vlMode: parsed.vlMode,
+            uiTarsVersion: parsed.uiTarsVersion
+        };
+    }
+};
 const decideModelConfigFromIntentConfig = (intent, intentConfig)=>{
     const debugLog = (0, external_logger_js_namespaceObject.getDebug)('ai:config');
     debugLog('decideModelConfig base on agent.modelConfig()');
@@ -117,7 +144,7 @@ const decideModelConfigFromEnv = (intent, allEnvConfig)=>{
             provider: allEnvConfig,
             valueAssert: (0, external_helper_js_namespaceObject.createAssert)(keysForEnv.modelName, 'process.env', modelName)
         });
-        const { vlMode, uiTarsVersion } = (0, external_parse_js_namespaceObject.parseVlModeAndUiTarsModelVersionFromRawValue)(result.vlModeRaw);
+        const { vlMode, uiTarsVersion } = parseVlModeForIntent(intent, allEnvConfig, result, debugLog);
         const modelDescription = getModelDescription(vlMode, uiTarsVersion);
         const finalResult = {
             ...result,
@@ -137,7 +164,7 @@ const decideModelConfigFromEnv = (intent, allEnvConfig)=>{
         provider: allEnvConfig,
         valueAssert: (0, external_helper_js_namespaceObject.createAssert)(external_constants_js_namespaceObject.DEFAULT_MODEL_CONFIG_KEYS_LEGACY.modelName, 'process.env')
     });
-    const { vlMode, uiTarsVersion } = (0, external_parse_js_namespaceObject.parseVlModeAndUiTarsFromGlobalConfig)(allEnvConfig);
+    const { vlMode, uiTarsVersion } = parseVlModeForIntent(intent, allEnvConfig, result, debugLog);
     const modelDescription = getModelDescription(vlMode, uiTarsVersion);
     const finalResult = {
         ...result,

package/dist/lib/env/parse.js

@@ -25,6 +25,8 @@ var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
     parseVlModeAndUiTarsFromGlobalConfig: ()=>parseVlModeAndUiTarsFromGlobalConfig,
+    detectLegacyVlModeEnvVars: ()=>detectLegacyVlModeEnvVars,
+    parseModelFamilyFromEnv: ()=>parseModelFamilyFromEnv,
     parseVlModeAndUiTarsModelVersionFromRawValue: ()=>parseVlModeAndUiTarsModelVersionFromRawValue
 });
 const external_types_js_namespaceObject = require("./types.js");
@@ -67,7 +69,7 @@ const parseVlModeAndUiTarsFromGlobalConfig = (provider)=>{
         uiTarsVersion: void 0
     };
     if (isQwen) return {
-        vlMode: 'qwen-vl',
+        vlMode: 'qwen2.5-vl',
         uiTarsVersion: void 0
     };
     if (isDoubao) return {
@@ -95,9 +97,62 @@ const parseVlModeAndUiTarsFromGlobalConfig = (provider)=>{
         uiTarsVersion: void 0
     };
 };
+const detectLegacyVlModeEnvVars = (provider)=>{
+    const legacyVars = [
+        external_types_js_namespaceObject.MIDSCENE_USE_DOUBAO_VISION,
+        external_types_js_namespaceObject.MIDSCENE_USE_QWEN_VL,
+        external_types_js_namespaceObject.MIDSCENE_USE_QWEN3_VL,
+        external_types_js_namespaceObject.MIDSCENE_USE_VLM_UI_TARS,
+        external_types_js_namespaceObject.MIDSCENE_USE_GEMINI
+    ];
+    return legacyVars.filter((varName)=>provider[varName]);
+};
+function isValidModelFamily(value) {
+    return external_types_js_namespaceObject.MODEL_FAMILY_VALUES.includes(value);
+}
+function mapLegacyToModelFamily(vlMode, uiTarsVersion) {
+    if (!vlMode) return;
+    if ('vlm-ui-tars' === vlMode) if (uiTarsVersion === external_types_js_namespaceObject.UITarsModelVersion.V1_0) return 'vlm-ui-tars';
+    else if (uiTarsVersion === external_types_js_namespaceObject.UITarsModelVersion.DOUBAO_1_5_20B) return 'vlm-ui-tars-doubao-1.5';
+    else return 'vlm-ui-tars-doubao';
+    return vlMode;
+}
+const parseModelFamilyFromEnv = (provider)=>{
+    const warnings = [];
+    const modelFamilyRaw = provider[external_types_js_namespaceObject.MIDSCENE_MODEL_FAMILY];
+    const legacyVars = detectLegacyVlModeEnvVars(provider);
+    if (modelFamilyRaw && legacyVars.length > 0) throw new Error(`Conflicting configuration detected: Both MIDSCENE_MODEL_FAMILY and legacy environment variables (${legacyVars.join(', ')}) are set. Please use only MIDSCENE_MODEL_FAMILY.`);
+    if (modelFamilyRaw) {
+        if (!isValidModelFamily(modelFamilyRaw)) throw new Error(`Invalid MIDSCENE_MODEL_FAMILY value: "${modelFamilyRaw}". Must be one of: ${external_types_js_namespaceObject.MODEL_FAMILY_VALUES.join(', ')}. See documentation: https://midscenejs.com/model-provider.html`);
+        const modelFamily = modelFamilyRaw;
+        const parsed = parseVlModeAndUiTarsModelVersionFromRawValue(modelFamily);
+        return {
+            vlMode: parsed.vlMode,
+            uiTarsVersion: parsed.uiTarsVersion,
+            modelFamily,
+            warnings
+        };
+    }
+    if (legacyVars.length > 0) {
+        const legacyResult = parseVlModeAndUiTarsFromGlobalConfig(provider);
+        warnings.push(`DEPRECATED: Environment ${legacyVars.length > 1 ? 'variables' : 'variable'} ${legacyVars.join(', ')} ${legacyVars.length > 1 ? 'are' : 'is'} deprecated. Please use MIDSCENE_MODEL_FAMILY instead. See migration guide for details.`);
+        const modelFamily = mapLegacyToModelFamily(legacyResult.vlMode, legacyResult.uiTarsVersion);
+        return {
+            vlMode: legacyResult.vlMode,
+            uiTarsVersion: legacyResult.uiTarsVersion,
+            modelFamily,
+            warnings
+        };
+    }
+    throw new Error(`MIDSCENE_MODEL_FAMILY is required for planning tasks. Please set it to one of: ${external_types_js_namespaceObject.MODEL_FAMILY_VALUES.join(', ')}. See documentation: https://midscenejs.com/model-provider.html`);
+};
+exports.detectLegacyVlModeEnvVars = __webpack_exports__.detectLegacyVlModeEnvVars;
+exports.parseModelFamilyFromEnv = __webpack_exports__.parseModelFamilyFromEnv;
 exports.parseVlModeAndUiTarsFromGlobalConfig = __webpack_exports__.parseVlModeAndUiTarsFromGlobalConfig;
 exports.parseVlModeAndUiTarsModelVersionFromRawValue = __webpack_exports__.parseVlModeAndUiTarsModelVersionFromRawValue;
 for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "detectLegacyVlModeEnvVars",
+    "parseModelFamilyFromEnv",
     "parseVlModeAndUiTarsFromGlobalConfig",
     "parseVlModeAndUiTarsModelVersionFromRawValue"
 ].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];

package/dist/lib/env/types.js

@@ -56,6 +56,7 @@ __webpack_require__.d(__webpack_exports__, {
     MIDSCENE_MCP_USE_PUPPETEER_MODE: ()=>MIDSCENE_MCP_USE_PUPPETEER_MODE,
     MIDSCENE_MODEL_API_KEY: ()=>MIDSCENE_MODEL_API_KEY,
     MIDSCENE_MODEL_BASE_URL: ()=>MIDSCENE_MODEL_BASE_URL,
+    MIDSCENE_MODEL_FAMILY: ()=>MIDSCENE_MODEL_FAMILY,
     MIDSCENE_MODEL_HTTP_PROXY: ()=>MIDSCENE_MODEL_HTTP_PROXY,
     MIDSCENE_MODEL_INIT_CONFIG_JSON: ()=>MIDSCENE_MODEL_INIT_CONFIG_JSON,
     MIDSCENE_MODEL_MAX_TOKENS: ()=>MIDSCENE_MODEL_MAX_TOKENS,
@@ -84,6 +85,7 @@ __webpack_require__.d(__webpack_exports__, {
     MODEL_API_KEY: ()=>MODEL_API_KEY,
     MODEL_BASE_URL: ()=>MODEL_BASE_URL,
     MODEL_ENV_KEYS: ()=>MODEL_ENV_KEYS,
+    MODEL_FAMILY_VALUES: ()=>MODEL_FAMILY_VALUES,
     NUMBER_ENV_KEYS: ()=>NUMBER_ENV_KEYS,
     OPENAI_API_KEY: ()=>OPENAI_API_KEY,
     OPENAI_BASE_URL: ()=>OPENAI_BASE_URL,
@@ -151,6 +153,7 @@ const MIDSCENE_PLANNING_MODEL_BASE_URL = 'MIDSCENE_PLANNING_MODEL_BASE_URL';
 const MIDSCENE_PLANNING_MODEL_API_KEY = 'MIDSCENE_PLANNING_MODEL_API_KEY';
 const MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON = 'MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON';
 const MIDSCENE_PLANNING_LOCATOR_MODE = 'MIDSCENE_PLANNING_LOCATOR_MODE';
+const MIDSCENE_MODEL_FAMILY = 'MIDSCENE_MODEL_FAMILY';
 const UNUSED_ENV_KEYS = [
     MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG
 ];
@@ -224,7 +227,8 @@ const MODEL_ENV_KEYS = [
     MIDSCENE_PLANNING_MODEL_BASE_URL,
     MIDSCENE_PLANNING_MODEL_API_KEY,
     MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON,
-    MIDSCENE_PLANNING_LOCATOR_MODE
+    MIDSCENE_PLANNING_LOCATOR_MODE,
+    MIDSCENE_MODEL_FAMILY
 ];
 const ALL_ENV_KEYS = [
     ...UNUSED_ENV_KEYS,
@@ -232,22 +236,25 @@ const ALL_ENV_KEYS = [
     ...GLOBAL_ENV_KEYS,
     ...MODEL_ENV_KEYS
 ];
-var UITarsModelVersion = /*#__PURE__*/ function(UITarsModelVersion) {
-    UITarsModelVersion["V1_0"] = "1.0";
-    UITarsModelVersion["V1_5"] = "1.5";
-    UITarsModelVersion["DOUBAO_1_5_15B"] = "doubao-1.5-15B";
-    UITarsModelVersion["DOUBAO_1_5_20B"] = "doubao-1.5-20B";
-    return UITarsModelVersion;
-}({});
 const VL_MODE_RAW_VALID_VALUES = [
     'doubao-vision',
     'gemini',
-    'qwen-vl',
+    'qwen2.5-vl',
     'qwen3-vl',
     'vlm-ui-tars',
     'vlm-ui-tars-doubao',
     'vlm-ui-tars-doubao-1.5'
 ];
+const MODEL_FAMILY_VALUES = [
+    ...VL_MODE_RAW_VALID_VALUES
+];
+var UITarsModelVersion = /*#__PURE__*/ function(UITarsModelVersion) {
+    UITarsModelVersion["V1_0"] = "1.0";
+    UITarsModelVersion["V1_5"] = "1.5";
+    UITarsModelVersion["DOUBAO_1_5_15B"] = "doubao-1.5-15B";
+    UITarsModelVersion["DOUBAO_1_5_20B"] = "doubao-1.5-20B";
+    return UITarsModelVersion;
+}({});
 exports.ALL_ENV_KEYS = __webpack_exports__.ALL_ENV_KEYS;
 exports.BASIC_ENV_KEYS = __webpack_exports__.BASIC_ENV_KEYS;
 exports.BOOLEAN_ENV_KEYS = __webpack_exports__.BOOLEAN_ENV_KEYS;
@@ -280,6 +287,7 @@ exports.MIDSCENE_MCP_CHROME_PATH = __webpack_exports__.MIDSCENE_MCP_CHROME_PATH;
 exports.MIDSCENE_MCP_USE_PUPPETEER_MODE = __webpack_exports__.MIDSCENE_MCP_USE_PUPPETEER_MODE;
 exports.MIDSCENE_MODEL_API_KEY = __webpack_exports__.MIDSCENE_MODEL_API_KEY;
 exports.MIDSCENE_MODEL_BASE_URL = __webpack_exports__.MIDSCENE_MODEL_BASE_URL;
+exports.MIDSCENE_MODEL_FAMILY = __webpack_exports__.MIDSCENE_MODEL_FAMILY;
 exports.MIDSCENE_MODEL_HTTP_PROXY = __webpack_exports__.MIDSCENE_MODEL_HTTP_PROXY;
 exports.MIDSCENE_MODEL_INIT_CONFIG_JSON = __webpack_exports__.MIDSCENE_MODEL_INIT_CONFIG_JSON;
 exports.MIDSCENE_MODEL_MAX_TOKENS = __webpack_exports__.MIDSCENE_MODEL_MAX_TOKENS;
@@ -308,6 +316,7 @@ exports.MIDSCENE_USE_VL_MODEL = __webpack_exports__.MIDSCENE_USE_VL_MODEL;
 exports.MODEL_API_KEY = __webpack_exports__.MODEL_API_KEY;
 exports.MODEL_BASE_URL = __webpack_exports__.MODEL_BASE_URL;
 exports.MODEL_ENV_KEYS = __webpack_exports__.MODEL_ENV_KEYS;
+exports.MODEL_FAMILY_VALUES = __webpack_exports__.MODEL_FAMILY_VALUES;
 exports.NUMBER_ENV_KEYS = __webpack_exports__.NUMBER_ENV_KEYS;
 exports.OPENAI_API_KEY = __webpack_exports__.OPENAI_API_KEY;
 exports.OPENAI_BASE_URL = __webpack_exports__.OPENAI_BASE_URL;
@@ -349,6 +358,7 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "MIDSCENE_MCP_USE_PUPPETEER_MODE",
     "MIDSCENE_MODEL_API_KEY",
     "MIDSCENE_MODEL_BASE_URL",
+    "MIDSCENE_MODEL_FAMILY",
     "MIDSCENE_MODEL_HTTP_PROXY",
     "MIDSCENE_MODEL_INIT_CONFIG_JSON",
     "MIDSCENE_MODEL_MAX_TOKENS",
@@ -377,6 +387,7 @@ for(var __webpack_i__ in __webpack_exports__)if (-1 === [
     "MODEL_API_KEY",
     "MODEL_BASE_URL",
     "MODEL_ENV_KEYS",
+    "MODEL_FAMILY_VALUES",
     "NUMBER_ENV_KEYS",
     "OPENAI_API_KEY",
     "OPENAI_BASE_URL",

package/dist/types/env/parse.d.ts

@@ -1,4 +1,4 @@
-import { type TVlModeTypes, UITarsModelVersion } from './types';
+import { type TModelFamily, type TVlModeTypes, UITarsModelVersion } from './types';
 export declare const parseVlModeAndUiTarsModelVersionFromRawValue: (vlModeRaw?: string) => {
     vlMode?: TVlModeTypes;
     uiTarsVersion?: UITarsModelVersion;
@@ -10,3 +10,22 @@ export declare const parseVlModeAndUiTarsFromGlobalConfig: (provider: Record<str
     vlMode?: TVlModeTypes;
     uiTarsVersion?: UITarsModelVersion;
 };
+/**
+ * Check if old MIDSCENE_USE_* environment variables are being used
+ * @param provider - Environment variable provider
+ * @returns Array of legacy environment variable names that are set
+ */
+export declare const detectLegacyVlModeEnvVars: (provider: Record<string, string | undefined>) => string[];
+/**
+ * Parse model family from environment variables with validation and warnings
+ * Supports both new MIDSCENE_MODEL_FAMILY and legacy MIDSCENE_USE_* variables
+ *
+ * @param provider - Environment variable provider
+ * @returns Object with vlMode, uiTarsVersion, and warnings
+ */
+export declare const parseModelFamilyFromEnv: (provider: Record<string, string | undefined>) => {
+    vlMode?: TVlModeTypes;
+    uiTarsVersion?: UITarsModelVersion;
+    warnings: string[];
+    modelFamily?: TModelFamily;
+};

package/dist/types/env/types.d.ts

@@ -80,6 +80,7 @@ export declare const MIDSCENE_PLANNING_MODEL_BASE_URL = "MIDSCENE_PLANNING_MODEL
 export declare const MIDSCENE_PLANNING_MODEL_API_KEY = "MIDSCENE_PLANNING_MODEL_API_KEY";
 export declare const MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON = "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON";
 export declare const MIDSCENE_PLANNING_LOCATOR_MODE = "MIDSCENE_PLANNING_LOCATOR_MODE";
+export declare const MIDSCENE_MODEL_FAMILY = "MIDSCENE_MODEL_FAMILY";
 /**
  * env keys declared but unused
  */
@@ -103,12 +104,23 @@ export declare const GLOBAL_ENV_KEYS: readonly ["MIDSCENE_CACHE", "MIDSCENE_FORC
  * Can be override by both agent.modelConfig and overrideAIConfig
  * Can only be access after agent.constructor
  */
-export declare const MODEL_ENV_KEYS: readonly ["MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "MIDSCENE_LOCATOR_MODE", "OPENAI_API_KEY", "OPENAI_BASE_URL", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MODEL_API_KEY", "MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_LOCATOR_MODE", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_LOCATOR_MODE"];
-export declare const ALL_ENV_KEYS: readonly [...string[], "MIDSCENE_DEBUG_MODE", "MIDSCENE_DEBUG_MODEL_PROFILE", "MIDSCENE_DEBUG_MODEL_RESPONSE", "MIDSCENE_RUN_DIR", "MIDSCENE_CACHE", "MIDSCENE_FORCE_DEEP_THINK", "MIDSCENE_MCP_USE_PUPPETEER_MODE", "MIDSCENE_MCP_ANDROID_MODE", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT", "MIDSCENE_MODEL_MAX_TOKENS", "OPENAI_MAX_TOKENS", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER", "MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "MIDSCENE_LOCATOR_MODE", "OPENAI_API_KEY", "OPENAI_BASE_URL", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MODEL_API_KEY", "MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_LOCATOR_MODE", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_LOCATOR_MODE"];
+export declare const MODEL_ENV_KEYS: readonly ["MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "MIDSCENE_LOCATOR_MODE", "OPENAI_API_KEY", "OPENAI_BASE_URL", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MODEL_API_KEY", "MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_LOCATOR_MODE", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_LOCATOR_MODE", "MIDSCENE_MODEL_FAMILY"];
+export declare const ALL_ENV_KEYS: readonly [...string[], "MIDSCENE_DEBUG_MODE", "MIDSCENE_DEBUG_MODEL_PROFILE", "MIDSCENE_DEBUG_MODEL_RESPONSE", "MIDSCENE_RUN_DIR", "MIDSCENE_CACHE", "MIDSCENE_FORCE_DEEP_THINK", "MIDSCENE_MCP_USE_PUPPETEER_MODE", "MIDSCENE_MCP_ANDROID_MODE", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT", "MIDSCENE_MODEL_MAX_TOKENS", "OPENAI_MAX_TOKENS", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER", "MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "MIDSCENE_LOCATOR_MODE", "OPENAI_API_KEY", "OPENAI_BASE_URL", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MODEL_API_KEY", "MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_LOCATOR_MODE", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_LOCATOR_MODE", "MIDSCENE_MODEL_FAMILY"];
 export type TEnvKeys = (typeof ALL_ENV_KEYS)[number];
 export type TGlobalConfig = Record<TEnvKeys, string | undefined>;
-export type TVlModeValues = 'qwen-vl' | 'qwen3-vl' | 'doubao-vision' | 'gemini' | 'vlm-ui-tars' | 'vlm-ui-tars-doubao' | 'vlm-ui-tars-doubao-1.5';
-export type TVlModeTypes = 'qwen-vl' | 'qwen3-vl' | 'doubao-vision' | 'gemini' | 'vlm-ui-tars';
+export type TVlModeValues = 'qwen2.5-vl' | 'qwen3-vl' | 'doubao-vision' | 'gemini' | 'vlm-ui-tars' | 'vlm-ui-tars-doubao' | 'vlm-ui-tars-doubao-1.5';
+export type TVlModeTypes = 'qwen2.5-vl' | 'qwen3-vl' | 'doubao-vision' | 'gemini' | 'vlm-ui-tars';
+export declare const VL_MODE_RAW_VALID_VALUES: TVlModeValues[];
+/**
+ * Model family values - unified model configuration approach
+ * Replaces the old MIDSCENE_USE_* environment variables
+ *
+ * Note: These values directly correspond to VL_MODE_RAW_VALID_VALUES
+ * - 'qwen2.5-vl' is Qwen 2.5
+ * - 'qwen3-vl' is Qwen 3
+ */
+export type TModelFamily = TVlModeValues;
+export declare const MODEL_FAMILY_VALUES: TVlModeValues[];
 export interface IModelConfigForInsight {
     [MIDSCENE_INSIGHT_MODEL_NAME]: string;
     [MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY]?: string;
@@ -125,7 +137,7 @@ export interface IModelConfigForInsight {
  * DOM-based planning is not supported.
  *
  * Required: MIDSCENE_PLANNING_LOCATOR_MODE must be set to one of:
- *   - 'qwen-vl'
+ *   - 'qwen2.5-vl'
  *   - 'qwen3-vl'
  *   - 'gemini'
  *   - 'doubao-vision'
@@ -184,7 +196,6 @@ export declare enum UITarsModelVersion {
     DOUBAO_1_5_15B = "doubao-1.5-15B",
     DOUBAO_1_5_20B = "doubao-1.5-20B"
 }
-export declare const VL_MODE_RAW_VALID_VALUES: TVlModeValues[];
 /**
  * Callback to create custom OpenAI client instance
  * @param config - Resolved model configuration including apiKey, baseURL, modelName, intent, etc.
@@ -229,8 +240,8 @@ export interface IModelConfig {
     openaiApiKey?: string;
     openaiExtraConfig?: Record<string, unknown>;
     /**
-     * - vlModeRaw: exists only in non-legacy logic. value can be 'doubao-vision', 'gemini', 'qwen-vl', 'vlm-ui-tars', 'vlm-ui-tars-doubao', 'vlm-ui-tars-doubao-1.5'
-     * - vlMode: based on the results of the vlModoRaw classification，value can be 'doubao-vision', 'gemini', 'qwen-vl', 'vlm-ui-tars'
+     * - vlModeRaw: exists only in non-legacy logic. value can be 'doubao-vision', 'gemini', 'qwen2.5-vl', 'vlm-ui-tars', 'vlm-ui-tars-doubao', 'vlm-ui-tars-doubao-1.5'
+     * - vlMode: based on the results of the vlModoRaw classification，value can be 'doubao-vision', 'gemini', 'qwen2.5-vl', 'vlm-ui-tars'
      */
     vlModeRaw?: string;
     vlMode?: TVlModeTypes;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/shared",
-  "version": "1.0.1-beta-20251118021215.0",
+  "version": "1.0.1-beta-20251118060105.0",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "types": "./dist/types/index.d.ts",

package/src/env/decide-model-config.ts

@@ -31,6 +31,7 @@ import { assert } from '../utils';
 import { createAssert, maskConfig, parseJson } from './helper';
 import { initDebugConfig } from './init-debug';
 import {
+  parseModelFamilyFromEnv,
   parseVlModeAndUiTarsFromGlobalConfig,
   parseVlModeAndUiTarsModelVersionFromRawValue,
 } from './parse';
@@ -167,6 +168,56 @@ const getModelDescription = (
   return '';
 };
 
+/**
+ * Parse vlMode and uiTarsVersion based on intent and config
+ * Consolidates the logic for handling planning intent vs other intents
+ */
+const parseVlModeForIntent = (
+  intent: TIntent,
+  allEnvConfig: Record<string, string | undefined>,
+  result: { vlModeRaw?: string },
+  debugLog: (...args: any[]) => void,
+): {
+  vlMode?: TVlModeTypes;
+  uiTarsVersion?: UITarsModelVersion;
+} => {
+  if (intent === 'planning') {
+    const parseResult = parseModelFamilyFromEnv(allEnvConfig);
+
+    // Output warnings to debug log
+    parseResult.warnings.forEach((warning) => {
+      console.warn(`[Midscene] ${warning}`);
+    });
+
+    if (parseResult.modelFamily) {
+      debugLog(`Using model family: ${parseResult.modelFamily}`);
+    }
+
+    return {
+      vlMode: parseResult.vlMode,
+      uiTarsVersion: parseResult.uiTarsVersion,
+    };
+  } else {
+    // For other intents, use parseVlModeAndUiTarsModelVersionFromRawValue if vlModeRaw is available
+    // Otherwise, use parseVlModeAndUiTarsFromGlobalConfig
+    if (result.vlModeRaw !== undefined) {
+      const parsed = parseVlModeAndUiTarsModelVersionFromRawValue(
+        result.vlModeRaw,
+      );
+      return {
+        vlMode: parsed.vlMode,
+        uiTarsVersion: parsed.uiTarsVersion,
+      };
+    } else {
+      const parsed = parseVlModeAndUiTarsFromGlobalConfig(allEnvConfig);
+      return {
+        vlMode: parsed.vlMode,
+        uiTarsVersion: parsed.uiTarsVersion,
+      };
+    }
+  }
+};
+
 export const decideModelConfigFromIntentConfig = (
   intent: TIntent,
   intentConfig: Record<string, string | undefined>,
@@ -254,8 +305,13 @@ export const decideModelConfigFromEnv = (
       valueAssert: createAssert(keysForEnv.modelName, 'process.env', modelName),
     });
 
-    const { vlMode, uiTarsVersion } =
-      parseVlModeAndUiTarsModelVersionFromRawValue(result.vlModeRaw);
+    const { vlMode, uiTarsVersion } = parseVlModeForIntent(
+      intent,
+      allEnvConfig,
+      result,
+      debugLog,
+    );
+
     const modelDescription = getModelDescription(vlMode, uiTarsVersion);
 
     const finalResult: IModelConfig = {
@@ -287,8 +343,12 @@ export const decideModelConfigFromEnv = (
     ),
   });
 
-  const { vlMode, uiTarsVersion } =
-    parseVlModeAndUiTarsFromGlobalConfig(allEnvConfig);
+  const { vlMode, uiTarsVersion } = parseVlModeForIntent(
+    intent,
+    allEnvConfig,
+    result,
+    debugLog,
+  );
 
   const modelDescription = getModelDescription(vlMode, uiTarsVersion);
 

package/src/env/parse.ts

@@ -1,9 +1,12 @@
 import {
+  MIDSCENE_MODEL_FAMILY,
   MIDSCENE_USE_DOUBAO_VISION,
   MIDSCENE_USE_GEMINI,
   MIDSCENE_USE_QWEN3_VL,
   MIDSCENE_USE_QWEN_VL,
   MIDSCENE_USE_VLM_UI_TARS,
+  MODEL_FAMILY_VALUES,
+  type TModelFamily,
   type TVlModeTypes,
   type TVlModeValues,
   UITarsModelVersion,
@@ -17,10 +20,7 @@ export const parseVlModeAndUiTarsModelVersionFromRawValue = (
   uiTarsVersion?: UITarsModelVersion;
 } => {
   if (!vlModeRaw) {
-    return {
-      vlMode: undefined,
-      uiTarsVersion: undefined,
-    };
+    return { vlMode: undefined, uiTarsVersion: undefined };
   }
 
   if (!VL_MODE_RAW_VALID_VALUES.includes(vlModeRaw as never)) {
@@ -31,21 +31,17 @@ export const parseVlModeAndUiTarsModelVersionFromRawValue = (
   const raw = vlModeRaw as TVlModeValues;
 
   if (raw === 'vlm-ui-tars') {
-    return {
-      vlMode: 'vlm-ui-tars',
-      uiTarsVersion: UITarsModelVersion.V1_0,
-    };
-  } else if (raw === 'vlm-ui-tars-doubao' || raw === 'vlm-ui-tars-doubao-1.5') {
+    return { vlMode: 'vlm-ui-tars', uiTarsVersion: UITarsModelVersion.V1_0 };
+  }
+
+  if (raw === 'vlm-ui-tars-doubao' || raw === 'vlm-ui-tars-doubao-1.5') {
     return {
       vlMode: 'vlm-ui-tars',
       uiTarsVersion: UITarsModelVersion.DOUBAO_1_5_20B,
     };
   }
 
-  return {
-    vlMode: raw as TVlModeTypes,
-    uiTarsVersion: undefined,
-  };
+  return { vlMode: raw as TVlModeTypes, uiTarsVersion: undefined };
 };
 
 /**
@@ -77,34 +73,13 @@ export const parseVlModeAndUiTarsFromGlobalConfig = (
     );
   }
 
-  if (isQwen3) {
-    return {
-      vlMode: 'qwen3-vl',
-      uiTarsVersion: undefined,
-    };
-  }
-
-  if (isQwen) {
-    return {
-      vlMode: 'qwen-vl',
-      uiTarsVersion: undefined,
-    };
-  }
-
-  if (isDoubao) {
-    return {
-      vlMode: 'doubao-vision',
-      uiTarsVersion: undefined,
-    };
-  }
-
-  if (isGemini) {
-    return {
-      vlMode: 'gemini',
-      uiTarsVersion: undefined,
-    };
-  }
+  // Simple modes without version
+  if (isQwen3) return { vlMode: 'qwen3-vl', uiTarsVersion: undefined };
+  if (isQwen) return { vlMode: 'qwen2.5-vl', uiTarsVersion: undefined };
+  if (isDoubao) return { vlMode: 'doubao-vision', uiTarsVersion: undefined };
+  if (isGemini) return { vlMode: 'gemini', uiTarsVersion: undefined };
 
+  // UI-TARS with version detection
   if (isUiTars) {
     if (isUiTars === '1') {
       return {
@@ -124,8 +99,131 @@ export const parseVlModeAndUiTarsFromGlobalConfig = (
     }
   }
 
-  return {
-    vlMode: undefined,
-    uiTarsVersion: undefined,
-  };
+  return { vlMode: undefined, uiTarsVersion: undefined };
+};
+
+/**
+ * Check if old MIDSCENE_USE_* environment variables are being used
+ * @param provider - Environment variable provider
+ * @returns Array of legacy environment variable names that are set
+ */
+export const detectLegacyVlModeEnvVars = (
+  provider: Record<string, string | undefined>,
+): string[] => {
+  const legacyVars = [
+    MIDSCENE_USE_DOUBAO_VISION,
+    MIDSCENE_USE_QWEN_VL,
+    MIDSCENE_USE_QWEN3_VL,
+    MIDSCENE_USE_VLM_UI_TARS,
+    MIDSCENE_USE_GEMINI,
+  ];
+
+  return legacyVars.filter((varName) => provider[varName]);
+};
+
+/**
+ * Type guard to check if a string is a valid TModelFamily
+ */
+function isValidModelFamily(value: string): value is TModelFamily {
+  return (MODEL_FAMILY_VALUES as readonly string[]).includes(value);
+}
+
+/**
+ * Map legacy vlMode and uiTarsVersion to model family
+ * @param vlMode - The VL mode type
+ * @param uiTarsVersion - The UI-TARS version (if applicable)
+ * @returns The corresponding model family value
+ */
+function mapLegacyToModelFamily(
+  vlMode?: TVlModeTypes,
+  uiTarsVersion?: UITarsModelVersion,
+): TModelFamily | undefined {
+  if (!vlMode) return undefined;
+
+  if (vlMode === 'vlm-ui-tars') {
+    // UI-TARS needs special handling for version
+    if (uiTarsVersion === UITarsModelVersion.V1_0) {
+      return 'vlm-ui-tars';
+    } else if (uiTarsVersion === UITarsModelVersion.DOUBAO_1_5_20B) {
+      return 'vlm-ui-tars-doubao-1.5';
+    } else {
+      // Handle other UI-TARS versions (vlm-ui-tars-doubao)
+      return 'vlm-ui-tars-doubao';
+    }
+  }
+
+  // For other modes, model family directly matches vlMode
+  return vlMode as TModelFamily;
+}
+
+/**
+ * Parse model family from environment variables with validation and warnings
+ * Supports both new MIDSCENE_MODEL_FAMILY and legacy MIDSCENE_USE_* variables
+ *
+ * @param provider - Environment variable provider
+ * @returns Object with vlMode, uiTarsVersion, and warnings
+ */
+export const parseModelFamilyFromEnv = (
+  provider: Record<string, string | undefined>,
+): {
+  vlMode?: TVlModeTypes;
+  uiTarsVersion?: UITarsModelVersion;
+  warnings: string[];
+  modelFamily?: TModelFamily;
+} => {
+  const warnings: string[] = [];
+  const modelFamilyRaw = provider[MIDSCENE_MODEL_FAMILY];
+  const legacyVars = detectLegacyVlModeEnvVars(provider);
+
+  // Case 1: Both new and legacy variables are set - ERROR
+  if (modelFamilyRaw && legacyVars.length > 0) {
+    throw new Error(
+      `Conflicting configuration detected: Both MIDSCENE_MODEL_FAMILY and legacy environment variables (${legacyVars.join(', ')}) are set. Please use only MIDSCENE_MODEL_FAMILY.`,
+    );
+  }
+
+  // Case 2: Only new MIDSCENE_MODEL_FAMILY is set
+  if (modelFamilyRaw) {
+    // Validate model family value
+    if (!isValidModelFamily(modelFamilyRaw)) {
+      throw new Error(
+        `Invalid MIDSCENE_MODEL_FAMILY value: "${modelFamilyRaw}". Must be one of: ${MODEL_FAMILY_VALUES.join(', ')}. See documentation: https://midscenejs.com/model-provider.html`,
+      );
+    }
+
+    const modelFamily = modelFamilyRaw;
+    const parsed = parseVlModeAndUiTarsModelVersionFromRawValue(modelFamily);
+    return {
+      vlMode: parsed.vlMode,
+      uiTarsVersion: parsed.uiTarsVersion,
+      modelFamily,
+      warnings,
+    };
+  }
+
+  // Case 3: Only legacy variables are set - WARN
+  if (legacyVars.length > 0) {
+    const legacyResult = parseVlModeAndUiTarsFromGlobalConfig(provider);
+
+    warnings.push(
+      `DEPRECATED: Environment ${legacyVars.length > 1 ? 'variables' : 'variable'} ${legacyVars.join(', ')} ${legacyVars.length > 1 ? 'are' : 'is'} deprecated. Please use MIDSCENE_MODEL_FAMILY instead. See migration guide for details.`,
+    );
+
+    const modelFamily = mapLegacyToModelFamily(
+      legacyResult.vlMode,
+      legacyResult.uiTarsVersion,
+    );
+
+    return {
+      vlMode: legacyResult.vlMode,
+      uiTarsVersion: legacyResult.uiTarsVersion,
+      modelFamily,
+      warnings,
+    };
+  }
+
+  // Case 4: No configuration set - ERROR
+  throw new Error(
+    `MIDSCENE_MODEL_FAMILY is required for planning tasks. Please set it to one of: ${MODEL_FAMILY_VALUES.join(', ')}. See documentation: https://midscenejs.com/model-provider.html`,
+  );
 };

package/src/env/types.ts

@@ -114,6 +114,7 @@ export const MIDSCENE_PLANNING_MODEL_API_KEY =
 export const MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON =
   'MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON';
 export const MIDSCENE_PLANNING_LOCATOR_MODE = 'MIDSCENE_PLANNING_LOCATOR_MODE';
+export const MIDSCENE_MODEL_FAMILY = 'MIDSCENE_MODEL_FAMILY';
 
 /**
  * env keys declared but unused
@@ -214,6 +215,7 @@ export const MODEL_ENV_KEYS = [
   MIDSCENE_PLANNING_MODEL_API_KEY,
   MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON,
   MIDSCENE_PLANNING_LOCATOR_MODE,
+  MIDSCENE_MODEL_FAMILY,
 ] as const;
 
 export const ALL_ENV_KEYS = [
@@ -227,7 +229,7 @@ export type TEnvKeys = (typeof ALL_ENV_KEYS)[number];
 export type TGlobalConfig = Record<TEnvKeys, string | undefined>;
 
 export type TVlModeValues =
-  | 'qwen-vl'
+  | 'qwen2.5-vl'
   | 'qwen3-vl'
   | 'doubao-vision'
   | 'gemini'
@@ -236,12 +238,36 @@ export type TVlModeValues =
   | 'vlm-ui-tars-doubao-1.5';
 
 export type TVlModeTypes =
-  | 'qwen-vl'
+  | 'qwen2.5-vl'
   | 'qwen3-vl'
   | 'doubao-vision'
   | 'gemini'
   | 'vlm-ui-tars';
 
+export const VL_MODE_RAW_VALID_VALUES: TVlModeValues[] = [
+  'doubao-vision',
+  'gemini',
+  'qwen2.5-vl',
+  'qwen3-vl',
+  'vlm-ui-tars',
+  'vlm-ui-tars-doubao',
+  'vlm-ui-tars-doubao-1.5',
+];
+
+/**
+ * Model family values - unified model configuration approach
+ * Replaces the old MIDSCENE_USE_* environment variables
+ *
+ * Note: These values directly correspond to VL_MODE_RAW_VALID_VALUES
+ * - 'qwen2.5-vl' is Qwen 2.5
+ * - 'qwen3-vl' is Qwen 3
+ */
+export type TModelFamily = TVlModeValues;
+
+export const MODEL_FAMILY_VALUES: TVlModeValues[] = [
+  ...VL_MODE_RAW_VALID_VALUES,
+];
+
 export interface IModelConfigForInsight {
   // model name
   [MIDSCENE_INSIGHT_MODEL_NAME]: string;
@@ -263,7 +289,7 @@ export interface IModelConfigForInsight {
  * DOM-based planning is not supported.
  *
  * Required: MIDSCENE_PLANNING_LOCATOR_MODE must be set to one of:
- *   - 'qwen-vl'
+ *   - 'qwen2.5-vl'
  *   - 'qwen3-vl'
  *   - 'gemini'
  *   - 'doubao-vision'
@@ -344,16 +370,6 @@ export enum UITarsModelVersion {
   DOUBAO_1_5_20B = 'doubao-1.5-20B',
 }
 
-export const VL_MODE_RAW_VALID_VALUES: TVlModeValues[] = [
-  'doubao-vision',
-  'gemini',
-  'qwen-vl',
-  'qwen3-vl',
-  'vlm-ui-tars',
-  'vlm-ui-tars-doubao',
-  'vlm-ui-tars-doubao-1.5',
-];
-
 /**
  * Callback to create custom OpenAI client instance
  * @param config - Resolved model configuration including apiKey, baseURL, modelName, intent, etc.
@@ -402,8 +418,8 @@ export interface IModelConfig {
   openaiApiKey?: string;
   openaiExtraConfig?: Record<string, unknown>;
   /**
-   * - vlModeRaw: exists only in non-legacy logic. value can be 'doubao-vision', 'gemini', 'qwen-vl', 'vlm-ui-tars', 'vlm-ui-tars-doubao', 'vlm-ui-tars-doubao-1.5'
-   * - vlMode: based on the results of the vlModoRaw classification，value can be 'doubao-vision', 'gemini', 'qwen-vl', 'vlm-ui-tars'
+   * - vlModeRaw: exists only in non-legacy logic. value can be 'doubao-vision', 'gemini', 'qwen2.5-vl', 'vlm-ui-tars', 'vlm-ui-tars-doubao', 'vlm-ui-tars-doubao-1.5'
+   * - vlMode: based on the results of the vlModoRaw classification，value can be 'doubao-vision', 'gemini', 'qwen2.5-vl', 'vlm-ui-tars'
    */
   vlModeRaw?: string;
   vlMode?: TVlModeTypes;