feat(env): add backward compatibility for MIDSCENE_OPENAI_* environment variables

[quanru]

Summary

This PR adds backward compatibility support for legacy MIDSCENE_OPENAI_* environment variables that were renamed during the recent refactoring. This ensures existing users can continue using the old variable names without breaking their configurations.

Background

During the recent environment variable refactoring (#1375), the following variables were renamed but backward compatibility was not fully implemented:

• MIDSCENE_OPENAI_INIT_CONFIG_JSON → MIDSCENE_MODEL_INIT_CONFIG_JSON
• MIDSCENE_OPENAI_HTTP_PROXY → MIDSCENE_MODEL_HTTP_PROXY
• MIDSCENE_OPENAI_SOCKS_PROXY → MIDSCENE_MODEL_SOCKS_PROXY

This caused overrideAIConfig() to reject these legacy variable names with the error:

Failed to apply AI configuration: Failed to override AI config, invalid key: MIDSCENE_OPENAI_INIT_CONFIG_JSON

Changes

Code Changes

1. packages/shared/src/env/types.ts

   • Added deprecated constants with @deprecated JSDoc tags
   • Added legacy variables to MODEL_ENV_KEYS array to support overrideAIConfig()
   • Updated IModelConfigForDefaultLegacy interface to use legacy variable names

2. packages/shared/src/env/constants.ts

   • Imported new legacy constants
   • Updated DEFAULT_MODEL_CONFIG_KEYS_LEGACY to use legacy variable names for proxy and init config

3. packages/shared/src/env/decide-model-config.ts

   • Implemented priority fallback logic in decideOpenaiSdkConfig():
     • When legacy keys are used, check new variable names first
     • Fall back to legacy names if new ones are not set
     • Follows the same pattern as OPENAI_API_KEY / OPENAI_BASE_URL

Documentation Updates

4. apps/site/docs/zh/model-provider.mdx (Chinese)

   • Updated advanced configuration table with both new (recommended) and legacy (deprecated) variables
   • Added clear deprecation notices

5. apps/site/docs/en/model-provider.mdx (English)

   • Same updates as Chinese documentation

Priority Logic

When both old and new variables are set, new variables take precedence:

Legacy Variable (Deprecated)	New Variable (Recommended)	Priority
MIDSCENE_OPENAI_INIT_CONFIG_JSON	MIDSCENE_MODEL_INIT_CONFIG_JSON	New first
MIDSCENE_OPENAI_HTTP_PROXY	MIDSCENE_MODEL_HTTP_PROXY	New first
MIDSCENE_OPENAI_SOCKS_PROXY	MIDSCENE_MODEL_SOCKS_PROXY	New first

Testing

✅ All 139 tests pass in packages/shared

• Environment configuration tests
• Global config manager tests
• Model config manager tests
• Decision logic tests

Backward Compatibility

This PR ensures:

• ✅ Existing users can continue using legacy variable names
• ✅ overrideAIConfig() accepts legacy variable names
• ✅ Gradual migration path to new variable names
• ✅ Clear deprecation warnings in documentation
• ✅ No breaking changes to existing configurations

Related

• Related to refactor(env): modernize model configuration environment variables #1375 (original refactoring PR)

🤖 Generated with Claude Code

[netlify]

✅ Deploy Preview for midscene ready!

Name	Link
🔨 Latest commit	a754756
🔍 Latest deploy log	https://app.netlify.com/projects/midscene/deploys/68ff34f7fdfc53000884dc6b
😎 Deploy Preview	https://deploy-preview-1388--midscene.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
2 out of 3 committers have signed the CLA.

✅ quanru
✅ yuyutaotao
❌ Copilot
_{You have signed the CLA already but the status is still pending? Let us recheck it.}