@xiuchang-midscene/shared 2.0.2

package/src/constants/example-code.ts

@@ -0,0 +1,223 @@
+export const PLAYWRIGHT_EXAMPLE_CODE = `
+// Reference the following code to generate Midscene test cases
+// The following is test code for Midscene AI, for reference
+// The following is Playwright syntax, you can use Playwright to assist in test generation
+IMPORTANT: Follow these exact type signatures for AI functions:
+
+// Type signatures for AI functions:
+aiAct(prompt: string, options?: { cacheable?: boolean, deepThink?: 'unset' | true | false }): Promise<void>
+aiInput(text: string, locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>
+aiTap(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>
+aiHover(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>
+aiDoubleClick(locate: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>
+aiKeyboardPress(key: string, locate?: string, options?: { deepLocate?: boolean, xpath?: string, cacheable?: boolean }): Promise<void>
+aiScroll(locate: string | undefined, options: {
+  direction?: 'up' | 'down' | 'left' | 'right',
+  scrollType?: 'singleAction' | 'scrollToBottom' | 'scrollToTop' | 'scrollToRight' | 'scrollToLeft',
+  distance?: number | null,
+  deepLocate?: boolean,
+  xpath?: string,
+  cacheable?: boolean
+}): Promise<void>
+aiAssert(assertion: string, options?: { errorMessage?: string }): Promise<void>
+aiWaitFor(prompt: string, options?: { timeout?: number }): Promise<void>
+aiQuery<T>(queryObject: Record<string, string>): Promise<T> // Extracts data from page based on descriptions
+
+// examples:
+// Reference the following code to generate Midscene test cases
+// The following is test code for Midscene AI, for reference
+// The following is Playwright syntax, you can use Playwright to assist in test generation
+import { test as base } from '@playwright/test';
+import type { PlayWrightAiFixtureType } from '@midscene/web/playwright';
+import { PlaywrightAiFixture } from '@midscene/web/playwright';
+
+const test = base.extend<PlayWrightAiFixtureType>(PlaywrightAiFixture({
+  waitForNetworkIdleTimeout: 2000, // optional, the timeout for waiting for network idle between each action, default is 2000ms
+}));
+
+
+test.beforeEach(async ({ page }) => {
+  await page.goto('https://www.xxx.com/');
+  await page.setViewportSize({ width: 1920, height: 1080 });
+});
+
+test('ai shop', async ({
+  aiAct,
+  aiInput,
+  aiAssert,
+  aiQuery,
+  aiKeyboardPress,
+  aiHover,
+  aiTap,
+  aiWaitFor,
+  agentForPage,
+  page,
+}) => {
+  // login
+  await aiAssert('The page shows the login interface');
+  await aiInput('user_name', 'in user name input');
+  await aiInput('password', 'in password input');
+  await aiKeyboardPress('Enter', 'Login Button');
+
+  // check the login success
+  await aiWaitFor('The page shows that the loading is complete');
+  await aiAssert('The current page shows the product detail page');
+
+  // check the product info
+  const dataA = await aiQuery({
+    userInfo: 'User information in the format {name: string}',
+    theFirstProductInfo: 'The first product info in the format {name: string, price: number}',
+  });
+  expect(dataA.theFirstProductInfo.name).toBe('xxx');
+  expect(dataA.theFirstProductInfo.price).toBe(100);
+
+
+  // add to cart
+  await aiTap('click add to cart button');
+  
+  await aiTap('click right top cart icon');
+  await aiAssert('The cart icon shows the number 1');
+});
+`;
+
+export const YAML_EXAMPLE_CODE = `
+1. Format:
+
+web:
+  url: "starting_url"
+  viewportWidth: 1280
+  viewportHeight: 960
+
+tasks:
+  - name: "descriptive task name"
+    flow:
+      - aiTap: "element description"
+      - aiInput: 'text value'
+        locate: 'input field description'
+      - aiScroll:
+        direction: down/up
+        scrollType: scrollToBottom/scrollToTop/singleAction
+      - aiAssert: "expected state"
+      - sleep: milliseconds
+
+2. Action Types:
+- aiTap: for clicks (natural language targeting)
+- aiInput: for text input with 'locate' field
+- aiScroll: with direction and scrollType
+- aiAssert: for validations
+- sleep: for delays (milliseconds)
+
+3. Best Practices:
+- Group related actions into logical tasks
+- Use natural language descriptions
+- Add deepLocate: true for complex interactions
+- Keep task names concise but descriptive
+
+4. CRITICAL - YAML Indentation Rules:
+- For actions with additional parameters (aiScroll, aiInput, aiKeyboardPress), the parameters must be SIBLING keys, NOT nested children
+- Parameters like direction, scrollType, locate must align with the action key, not indented further
+- CORRECT indentation example:
+      - aiScroll:
+        direction: down
+        scrollType: singleAction
+- WRONG indentation (DO NOT do this):
+      - aiScroll:
+          direction: down
+          scrollType: singleAction
+
+
+
+YAML type
+tasks:
+  - name: <name>
+    continueOnError: <boolean> # Optional, whether to continue to the next task on error, defaults to false.
+    flow:
+      # Auto Planning (.ai)
+      # ----------------
+
+      # Perform an interaction. \`ai\` is a shorthand for \`aiAct\`.
+      - ai: <prompt>
+        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.
+
+      # This usage is the same as \`ai\`.
+      - aiAct: <prompt>
+        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.
+
+      # Instant Action (.aiTap, .aiDoubleClick, .aiHover, .aiInput, .aiKeyboardPress, .aiScroll)
+      # ----------------
+
+      # Tap an element described by a prompt.
+      - aiTap: <prompt>
+        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.
+        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.
+        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.
+
+      # Double click an element described by a prompt.
+      - aiDoubleClick: <prompt>
+        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.
+        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.
+        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.
+
+      # Hover over an element described by a prompt.
+      - aiHover: <prompt>
+        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.
+        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.
+        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.
+
+      # Input text into an element described by a prompt.
+      - aiInput: <final text content of the input>
+        locate: <prompt>
+        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.
+        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.
+        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.
+
+      # Press a key (e.g., Enter, Tab, Escape) on an element described by a prompt.
+      - aiKeyboardPress: <key>
+        locate: <prompt>
+        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.
+        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.
+        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.
+
+      # Scroll globally or on an element described by a prompt.
+      - aiScroll:
+        direction: 'up' # or 'down' | 'left' | 'right'
+        scrollType: 'singleAction' # or 'scrollToTop' | 'scrollToBottom' | 'scrollToLeft' | 'scrollToRight'
+        distance: <number> # Optional, the scroll distance in pixels.
+        locate: <prompt> # Optional, the element to scroll on.
+        deepLocate: <boolean> # Optional, whether to use deepLocate to precisely locate the element. Defaults to False.
+        xpath: <xpath> # Optional, the xpath of the target element for the operation. If provided, Midscene will prioritize this xpath to find the element before using the cache and the AI model. Defaults to empty.
+        cacheable: <boolean> # Optional, whether to cache the result of this API call when the [caching feature](./caching.mdx) is enabled. Defaults to True.
+
+      # Record the current screenshot with a description in the report file.
+      - recordToReport: <title> # Optional, the title of the screenshot. If not provided, the title will be 'untitled'.
+        content: <content> # Optional, the description of the screenshot.
+
+      # Data Extraction
+      # ----------------
+
+      # Perform a query that returns a JSON object.
+      - aiQuery: <prompt> # Remember to describe the format of the result in the prompt.
+        name: <name> # The key for the query result in the JSON output.
+
+      # More APIs
+      # ----------------
+
+      # Wait for a condition to be met, with a timeout (in ms, optional, defaults to 30000).
+      - aiWaitFor: <prompt>
+        timeout: <ms>
+
+      # Perform an assertion.
+      - aiAssert: <prompt>
+        errorMessage: <error-message> # Optional, the error message to print if the assertion fails.
+
+      # Wait for a specified amount of time.
+      - sleep: <ms>
+
+      # Execute a piece of JavaScript code in the web page context.
+      - javascript: <javascript>
+        name: <name> # Optional, assign a name to the return value, which will be used as a key in the JSON output.
+
+  - name: <name>
+    flow:
+      # ...
+`;

package/src/constants/index.ts

@@ -0,0 +1,29 @@
+export const TEXT_SIZE_THRESHOLD = 9;
+
+export const TEXT_MAX_SIZE = 40;
+
+export const CONTAINER_MINI_HEIGHT = 3;
+export const CONTAINER_MINI_WIDTH = 3;
+
+export enum NodeType {
+  CONTAINER = 'CONTAINER Node',
+  FORM_ITEM = 'FORM_ITEM Node',
+  BUTTON = 'BUTTON Node',
+  A = 'Anchor Node',
+  IMG = 'IMG Node',
+  TEXT = 'TEXT Node',
+  POSITION = 'POSITION Node',
+}
+
+export const PLAYGROUND_SERVER_PORT = 5800;
+export const SCRCPY_SERVER_PORT = 5700;
+
+// WebDriver constants
+export const WEBDRIVER_ELEMENT_ID_KEY = 'element-6066-11e4-a52e-4f735466cecf';
+export const DEFAULT_WDA_PORT = 8100;
+
+export const DEFAULT_WAIT_FOR_NAVIGATION_TIMEOUT = 5000;
+export const DEFAULT_WAIT_FOR_NETWORK_IDLE_TIMEOUT = 2000;
+export const DEFAULT_WAIT_FOR_NETWORK_IDLE_CONCURRENCY = 2;
+
+export { PLAYWRIGHT_EXAMPLE_CODE, YAML_EXAMPLE_CODE } from './example-code';

package/src/env/basic.ts

@@ -0,0 +1,12 @@
+import { BASIC_ENV_KEYS } from './types';
+
+/**
+ * get basic env value from process.env
+ * use a single file to avoid circular dependency
+ */
+export const getBasicEnvValue = (key: (typeof BASIC_ENV_KEYS)[number]) => {
+  if (!BASIC_ENV_KEYS.includes(key)) {
+    throw new Error(`getBasicEnvValue with key ${key} is not supported.`);
+  }
+  return process.env[key];
+};

package/src/env/constants.ts

@@ -0,0 +1,234 @@
+import {
+  MIDSCENE_INSIGHT_MODEL_API_KEY,
+  MIDSCENE_INSIGHT_MODEL_BASE_URL,
+  MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON,
+  MIDSCENE_INSIGHT_MODEL_FAMILY,
+  MIDSCENE_INSIGHT_MODEL_HTTP_PROXY,
+  MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON,
+  MIDSCENE_INSIGHT_MODEL_NAME,
+  MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET,
+  MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT,
+  MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED,
+  MIDSCENE_INSIGHT_MODEL_RETRY_COUNT,
+  MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL,
+  MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY,
+  MIDSCENE_INSIGHT_MODEL_TEMPERATURE,
+  MIDSCENE_INSIGHT_MODEL_TIMEOUT,
+  MIDSCENE_MODEL_API_KEY,
+  MIDSCENE_MODEL_BASE_URL,
+  MIDSCENE_MODEL_EXTRA_BODY_JSON,
+  MIDSCENE_MODEL_FAMILY,
+  MIDSCENE_MODEL_HTTP_PROXY,
+  MIDSCENE_MODEL_INIT_CONFIG_JSON,
+  MIDSCENE_MODEL_NAME,
+  MIDSCENE_MODEL_REASONING_BUDGET,
+  MIDSCENE_MODEL_REASONING_EFFORT,
+  MIDSCENE_MODEL_REASONING_ENABLED,
+  MIDSCENE_MODEL_RETRY_COUNT,
+  MIDSCENE_MODEL_RETRY_INTERVAL,
+  MIDSCENE_MODEL_SOCKS_PROXY,
+  MIDSCENE_MODEL_TEMPERATURE,
+  MIDSCENE_MODEL_TIMEOUT,
+  MIDSCENE_OPENAI_HTTP_PROXY,
+  MIDSCENE_OPENAI_INIT_CONFIG_JSON,
+  MIDSCENE_OPENAI_SOCKS_PROXY,
+  MIDSCENE_PLANNING_MODEL_API_KEY,
+  MIDSCENE_PLANNING_MODEL_BASE_URL,
+  MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON,
+  MIDSCENE_PLANNING_MODEL_FAMILY,
+  MIDSCENE_PLANNING_MODEL_HTTP_PROXY,
+  MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON,
+  MIDSCENE_PLANNING_MODEL_NAME,
+  MIDSCENE_PLANNING_MODEL_REASONING_BUDGET,
+  MIDSCENE_PLANNING_MODEL_REASONING_EFFORT,
+  MIDSCENE_PLANNING_MODEL_REASONING_ENABLED,
+  MIDSCENE_PLANNING_MODEL_RETRY_COUNT,
+  MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL,
+  MIDSCENE_PLANNING_MODEL_SOCKS_PROXY,
+  MIDSCENE_PLANNING_MODEL_TEMPERATURE,
+  MIDSCENE_PLANNING_MODEL_TIMEOUT,
+  OPENAI_API_KEY,
+  OPENAI_BASE_URL,
+} from './types';
+
+interface IModelConfigKeys {
+  modelName: string;
+  /**
+   * proxy
+   */
+  socksProxy: string;
+  httpProxy: string;
+  /**
+   * OpenAI
+   */
+  openaiBaseURL: string;
+  openaiApiKey: string;
+  openaiExtraConfig: string;
+  extraBody: string;
+  /**
+   * Extra
+   */
+  modelFamily: string;
+  /**
+   * Timeout
+   */
+  timeout: string;
+  /**
+   * Temperature
+   */
+  temperature: string;
+  /**
+   * Retry
+   */
+  retryCount: string;
+  retryInterval: string;
+  reasoningEffort: string;
+  reasoningEnabled: string;
+  reasoningBudget: string;
+}
+
+export const INSIGHT_MODEL_CONFIG_KEYS: IModelConfigKeys = {
+  modelName: MIDSCENE_INSIGHT_MODEL_NAME,
+  /**
+   * proxy
+   */
+  socksProxy: MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY,
+  httpProxy: MIDSCENE_INSIGHT_MODEL_HTTP_PROXY,
+  /**
+   * OpenAI
+   */
+  openaiBaseURL: MIDSCENE_INSIGHT_MODEL_BASE_URL,
+  openaiApiKey: MIDSCENE_INSIGHT_MODEL_API_KEY,
+  openaiExtraConfig: MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON,
+  extraBody: MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON,
+  /**
+   * Extra
+   */
+  modelFamily: MIDSCENE_INSIGHT_MODEL_FAMILY,
+  /**
+   * Timeout
+   */
+  timeout: MIDSCENE_INSIGHT_MODEL_TIMEOUT,
+  /**
+   * Temperature
+   */
+  temperature: MIDSCENE_INSIGHT_MODEL_TEMPERATURE,
+  /**
+   * Retry
+   */
+  retryCount: MIDSCENE_INSIGHT_MODEL_RETRY_COUNT,
+  retryInterval: MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL,
+  reasoningEffort: MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT,
+  reasoningEnabled: MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED,
+  reasoningBudget: MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET,
+} as const;
+
+export const PLANNING_MODEL_CONFIG_KEYS: IModelConfigKeys = {
+  modelName: MIDSCENE_PLANNING_MODEL_NAME,
+  /**
+   * proxy
+   */
+  socksProxy: MIDSCENE_PLANNING_MODEL_SOCKS_PROXY,
+  httpProxy: MIDSCENE_PLANNING_MODEL_HTTP_PROXY,
+  /**
+   * OpenAI
+   */
+  openaiBaseURL: MIDSCENE_PLANNING_MODEL_BASE_URL,
+  openaiApiKey: MIDSCENE_PLANNING_MODEL_API_KEY,
+  openaiExtraConfig: MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON,
+  extraBody: MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON,
+  /**
+   * Extra
+   */
+  modelFamily: MIDSCENE_PLANNING_MODEL_FAMILY,
+  /**
+   * Timeout
+   */
+  timeout: MIDSCENE_PLANNING_MODEL_TIMEOUT,
+  /**
+   * Temperature
+   */
+  temperature: MIDSCENE_PLANNING_MODEL_TEMPERATURE,
+  /**
+   * Retry
+   */
+  retryCount: MIDSCENE_PLANNING_MODEL_RETRY_COUNT,
+  retryInterval: MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL,
+  reasoningEffort: MIDSCENE_PLANNING_MODEL_REASONING_EFFORT,
+  reasoningEnabled: MIDSCENE_PLANNING_MODEL_REASONING_ENABLED,
+  reasoningBudget: MIDSCENE_PLANNING_MODEL_REASONING_BUDGET,
+} as const;
+
+// modelConfig return default
+export const DEFAULT_MODEL_CONFIG_KEYS: IModelConfigKeys = {
+  modelName: MIDSCENE_MODEL_NAME,
+  /**
+   * proxy
+   */
+  socksProxy: MIDSCENE_MODEL_SOCKS_PROXY,
+  httpProxy: MIDSCENE_MODEL_HTTP_PROXY,
+  /**
+   * OpenAI
+   */
+  openaiBaseURL: MIDSCENE_MODEL_BASE_URL,
+  openaiApiKey: MIDSCENE_MODEL_API_KEY,
+  openaiExtraConfig: MIDSCENE_MODEL_INIT_CONFIG_JSON,
+  extraBody: MIDSCENE_MODEL_EXTRA_BODY_JSON,
+  /**
+   * Extra
+   */
+  modelFamily: MIDSCENE_MODEL_FAMILY,
+  /**
+   * Timeout
+   */
+  timeout: MIDSCENE_MODEL_TIMEOUT,
+  /**
+   * Temperature
+   */
+  temperature: MIDSCENE_MODEL_TEMPERATURE,
+  /**
+   * Retry
+   */
+  retryCount: MIDSCENE_MODEL_RETRY_COUNT,
+  retryInterval: MIDSCENE_MODEL_RETRY_INTERVAL,
+  reasoningEffort: MIDSCENE_MODEL_REASONING_EFFORT,
+  reasoningEnabled: MIDSCENE_MODEL_REASONING_ENABLED,
+  reasoningBudget: MIDSCENE_MODEL_REASONING_BUDGET,
+} as const;
+
+// read from process.env
+export const DEFAULT_MODEL_CONFIG_KEYS_LEGACY: IModelConfigKeys = {
+  modelName: MIDSCENE_MODEL_NAME,
+  /**
+   * proxy - Uses legacy MIDSCENE_OPENAI_* variables for backward compatibility
+   */
+  socksProxy: MIDSCENE_OPENAI_SOCKS_PROXY,
+  httpProxy: MIDSCENE_OPENAI_HTTP_PROXY,
+  /**
+   * Model API - Uses legacy OPENAI_* variables for backward compatibility
+   */
+  openaiBaseURL: OPENAI_BASE_URL,
+  openaiApiKey: OPENAI_API_KEY,
+  openaiExtraConfig: MIDSCENE_OPENAI_INIT_CONFIG_JSON,
+  extraBody: MIDSCENE_MODEL_EXTRA_BODY_JSON,
+  /**
+   * Extra
+   */
+  modelFamily: 'DEFAULT_MODEL_CONFIG_KEYS has no modelFamily key',
+  /**
+   * Timeout - use the new key for legacy mode too
+   */
+  timeout: MIDSCENE_MODEL_TIMEOUT,
+  /**
+   * Temperature - use the new key for legacy mode too
+   */
+  temperature: MIDSCENE_MODEL_TEMPERATURE,
+  /**
+   * Retry - use the new key for legacy mode too
+   */
+  retryCount: MIDSCENE_MODEL_RETRY_COUNT,
+  retryInterval: MIDSCENE_MODEL_RETRY_INTERVAL,
+  reasoningEffort: MIDSCENE_MODEL_REASONING_EFFORT,
+  reasoningEnabled: MIDSCENE_MODEL_REASONING_ENABLED,
+  reasoningBudget: MIDSCENE_MODEL_REASONING_BUDGET,
+} as const;

package/src/env/global-config-manager.ts

@@ -0,0 +1,191 @@
+import { initDebugConfig } from './init-debug';
+import type { ModelConfigManager } from './model-config-manager';
+import {
+  BOOLEAN_ENV_KEYS,
+  GLOBAL_ENV_KEYS,
+  NUMBER_ENV_KEYS,
+  STRING_ENV_KEYS,
+} from './types';
+
+import {
+  ALL_ENV_KEYS,
+  MATCH_BY_POSITION,
+  MODEL_ENV_KEYS,
+  type TGlobalConfig,
+} from './types';
+
+/**
+ * Collect global configs from process.env, overrideAIConfig, etc.
+ * And provider methods to get merged config value
+ */
+export class GlobalConfigManager {
+  private override:
+    | {
+        newConfig?: Partial<TGlobalConfig>;
+        extendMode?: boolean;
+      }
+    | undefined;
+
+  private keysHaveBeenRead: Record<string, boolean> = {};
+
+  private globalModelConfigManager: ModelConfigManager | undefined = undefined;
+
+  constructor() {
+    initDebugConfig();
+  }
+
+  /**
+   * recalculate allEnvConfig every time because process.env can be updated any time
+   */
+  public getAllEnvConfig() {
+    const envConfig = ALL_ENV_KEYS.reduce(
+      (p, name) => {
+        p[name] = process.env[name];
+        return p;
+      },
+      Object.create(null) as Record<string, string | undefined>,
+    );
+
+    if (this.override) {
+      const { newConfig, extendMode } = this.override;
+      if (extendMode) {
+        return { ...envConfig, ...newConfig };
+      } else {
+        return { ...newConfig };
+      }
+    } else {
+      return envConfig;
+    }
+  }
+
+  getEnvConfigValue(key: (typeof STRING_ENV_KEYS)[number]) {
+    const allConfig = this.getAllEnvConfig();
+
+    if (key === MATCH_BY_POSITION) {
+      throw new Error(
+        'MATCH_BY_POSITION is discarded, use MIDSCENE_MODEL_FAMILY instead',
+      );
+    }
+
+    if (!STRING_ENV_KEYS.includes(key)) {
+      throw new Error(`getEnvConfigValue with key ${key} is not supported.`);
+    }
+
+    const value = allConfig[key];
+    this.keysHaveBeenRead[key] = true;
+    if (typeof value === 'string') {
+      return value.trim();
+    }
+    return value;
+  }
+
+  /**
+   * read boolean only from process.env
+   */
+  getEnvConfigInBoolean(key: (typeof BOOLEAN_ENV_KEYS)[number]): boolean {
+    const allConfig = this.getAllEnvConfig();
+
+    if (!BOOLEAN_ENV_KEYS.includes(key)) {
+      throw new Error(`getEnvConfigInBoolean with key ${key} is not supported`);
+    }
+
+    const value = allConfig[key];
+    this.keysHaveBeenRead[key] = true;
+
+    if (!value) {
+      return false;
+    }
+    if (/^(true|1)$/i.test(value)) {
+      return true;
+    }
+    if (/^(false|0)$/i.test(value)) {
+      return false;
+    }
+    return !!value.trim();
+  }
+
+  /**
+   * Read environment variable value and convert it to number.
+   * Returns undefined if the value is not set or cannot be converted to a valid number.
+   */
+  getEnvConfigValueAsNumber(
+    key: (typeof STRING_ENV_KEYS)[number] | (typeof NUMBER_ENV_KEYS)[number],
+  ): number | undefined {
+    if (
+      !STRING_ENV_KEYS.includes(key as never) &&
+      !NUMBER_ENV_KEYS.includes(key as never)
+    ) {
+      throw new Error(
+        `getEnvConfigValueAsNumber with key ${key} is not supported.`,
+      );
+    }
+
+    const allConfig = this.getAllEnvConfig();
+    const value = allConfig[key];
+    this.keysHaveBeenRead[key] = true;
+
+    if (typeof value !== 'string') {
+      return undefined;
+    }
+    const trimmed = value.trim();
+    if (!trimmed) {
+      return undefined;
+    }
+    const numValue = Number(trimmed);
+    return Number.isNaN(numValue) ? undefined : numValue;
+  }
+
+  registerModelConfigManager(globalModelConfigManager: ModelConfigManager) {
+    this.globalModelConfigManager = globalModelConfigManager;
+  }
+
+  /**
+   * @deprecated use the modelConfig param in Agent constructor instead
+   */
+  overrideAIConfig(
+    newConfig: Partial<
+      Record<
+        (typeof GLOBAL_ENV_KEYS)[number] | (typeof MODEL_ENV_KEYS)[number],
+        string
+      >
+    >,
+    extendMode = false, // true: merge with global config, false: override global config
+  ) {
+    for (const key in newConfig) {
+      if (![...GLOBAL_ENV_KEYS, ...MODEL_ENV_KEYS].includes(key as never)) {
+        throw new Error(`Failed to override AI config, invalid key: ${key}`);
+      }
+      const value = newConfig[key as keyof typeof newConfig];
+      if (typeof value !== 'string') {
+        throw new Error(
+          `Failed to override AI config, value for key ${key} must be a string, but got with type ${typeof value}`,
+        );
+      }
+      if (this.keysHaveBeenRead[key]) {
+        console.warn(
+          `Warning: try to override AI config with key ${key} ,but it has been read.`,
+        );
+      }
+    }
+    const savedNewConfig = extendMode
+      ? {
+          ...this.override?.newConfig,
+          ...newConfig,
+        }
+      : newConfig;
+
+    this.override = {
+      newConfig: {
+        ...savedNewConfig,
+      },
+      extendMode,
+    };
+
+    if (!this.globalModelConfigManager) {
+      throw new Error(
+        'globalModelConfigManager is not registered, which should not happen',
+      );
+    }
+    this.globalModelConfigManager.clearModelConfigMap();
+  }
+}