openyida 2026.5.13 → 2026.5.15

package/README.md

@@ -167,6 +167,7 @@ openyida/
 openyida create-app "CRM"
 openyida create-app --name "CRM" --desc "Customer management" --theme deepBlue
 openyida app-list --size 20
+openyida corp-efficiency
 openyida create-form create APP_XXX "Customer" .cache/openyida/forms/customer-fields.json
 openyida create-form update APP_XXX FORM_XXX .cache/openyida/forms/customer-changes.json
 openyida get-schema APP_XXX FORM_XXX
@@ -254,9 +255,10 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | Command | Description |
 |---------|-------------|
 | `openyida env [--json]` | Detect the active AI tool environment and login state |
+| `openyida env setup` | Choose a customer-friendly login environment preset: public, overseas, Alibaba intranet, or private deployment |
 | `openyida env <list\|show\|switch\|add\|remove>` | Manage public/private Yida environment profiles |
 | `openyida commands [--json]` | Emit the machine-readable command manifest |
-| `openyida login [--qr\|--agent-qr\|--codex\|--browser] [--corp-id <corpId>]` | Log in to Yida |
+| `openyida login [--qr\|--agent-qr\|--codex\|--browser] [--env <name>\|--overseas] [--corp-id <corpId>]` | Log in to Yida |
 | `openyida logout` | Log out or switch account |
 | `openyida auth <status\|login\|refresh\|logout>` | Manage login status |
 | `openyida org list` | List accessible organizations |
@@ -267,6 +269,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | Command | Description |
 |---------|-------------|
 | `openyida app-list [--size N]` | List Yida applications |
+| `openyida corp-efficiency [overview\|details\|detail\|groups\|notify] [options] [--open\|--no-open]` | Query enterprise efficiency metrics, detail report entries, and related notification actions |
 | `openyida create-app "<name>"\|--name <name> [options] [--open\|--no-open]` | Create an application and output `appType` |
 | `openyida update-app <appType> --name "..."` | Update application metadata |
 | `openyida export <appType> [output]` | Export an application migration package |

package/bin/yida.js

@@ -284,6 +284,39 @@ function getArgValue(cliArgs, name) {
   return cliArgs[index + 1];
 }
 
+function applyLoginEnvironmentFlags(cliArgs) {
+  const envFlagMap = {
+    '--public': 'public',
+    '--intl': 'intl',
+    '--overseas': 'intl',
+    '--international': 'intl',
+    '--global': 'intl',
+    '--alibaba': 'alibaba',
+    '--internal': 'alibaba',
+    '--intranet': 'alibaba',
+  };
+  const filteredArgs = [];
+
+  for (let index = 0; index < cliArgs.length; index++) {
+    const arg = cliArgs[index];
+    if (arg === '--env') {
+      const envName = cliArgs[index + 1];
+      if (envName && !envName.startsWith('--')) {
+        process.env.OPENYIDA_ENV = envName;
+        index++;
+      }
+      continue;
+    }
+    if (envFlagMap[arg]) {
+      process.env.OPENYIDA_ENV = envFlagMap[arg];
+      continue;
+    }
+    filteredArgs.push(arg);
+  }
+
+  return filteredArgs;
+}
+
 // 解析全局 --quiet 开关：从 args 中剔除并设置 YIDA_QUIET=1，让 chalk.js
 // 的所有装饰输出（banner/step/info/...）变 no-op，AI 即可直接 `... --quiet | jq`。
 function applyQuietFlag() {
@@ -352,40 +385,41 @@ async function main() {
 
     case 'login': {
       const { checkLoginOnly } = require('../lib/auth/login');
-      if (args.includes('--agent-poll') || args.includes('--codex-poll')) {
-        const sessionFile = getArgValue(args, '--agent-poll') || getArgValue(args, '--codex-poll');
+      const loginArgs = applyLoginEnvironmentFlags(args);
+      if (loginArgs.includes('--agent-poll') || loginArgs.includes('--codex-poll')) {
+        const sessionFile = getArgValue(loginArgs, '--agent-poll') || getArgValue(loginArgs, '--codex-poll');
         const { pollCodexQrLogin } = require('../lib/auth/qr-login');
         const result = await pollCodexQrLogin(sessionFile, {
-          corpId: getArgValue(args, '--corp-id'),
+          corpId: getArgValue(loginArgs, '--corp-id'),
         });
         printLoginResult(result);
-      } else if (args.includes('--agent-select') || args.includes('--codex-select')) {
-        const sessionFile = getArgValue(args, '--agent-select') || getArgValue(args, '--codex-select');
+      } else if (loginArgs.includes('--agent-select') || loginArgs.includes('--codex-select')) {
+        const sessionFile = getArgValue(loginArgs, '--agent-select') || getArgValue(loginArgs, '--codex-select');
         const { selectCodexQrCorp } = require('../lib/auth/qr-login');
         const result = await selectCodexQrCorp(sessionFile, {
-          corpId: getArgValue(args, '--corp-id'),
+          corpId: getArgValue(loginArgs, '--corp-id'),
         });
         printLoginResult(result);
-      } else if (args[0] === '--check-only') {
-        const result = checkLoginOnly({ includeSecrets: args.includes('--with-cookies') });
+      } else if (loginArgs[0] === '--check-only') {
+        const result = checkLoginOnly({ includeSecrets: loginArgs.includes('--with-cookies') });
         console.log(JSON.stringify(result, null, 2));
-      } else if (shouldUseCodexQrLogin(args)) {
+      } else if (shouldUseCodexQrLogin(loginArgs)) {
         const { startCodexQrLogin } = require('../lib/auth/qr-login');
-        const result = await startCodexQrLogin({ corpId: getArgValue(args, '--corp-id') });
+        const result = await startCodexQrLogin({ corpId: getArgValue(loginArgs, '--corp-id') });
         printLoginResult(result);
-      } else if (args.includes('--browser')) {
+      } else if (loginArgs.includes('--browser')) {
         const { interactiveLogin } = require('../lib/auth/login');
         const result = interactiveLogin({ force: true });
         printLoginResult(result);
-      } else if (args.includes('--qoder') || args.includes('--wukong')) {
+      } else if (loginArgs.includes('--qoder') || loginArgs.includes('--wukong')) {
         const { codexLogin } = require('../lib/auth/codex-login');
-        const result = await codexLogin({ tool: args.includes('--qoder') ? 'qoder' : 'wukong' });
+        const result = await codexLogin({ tool: loginArgs.includes('--qoder') ? 'qoder' : 'wukong' });
         printLoginResult(result);
-      } else if (args.includes('--qr')) {
+      } else if (loginArgs.includes('--qr')) {
         const { qrLogin } = require('../lib/auth/qr-login');
-        const result = await qrLogin({ corpId: getArgValue(args, '--corp-id') });
+        const result = await qrLogin({ corpId: getArgValue(loginArgs, '--corp-id') });
         console.log(JSON.stringify(result));
-      } else if (shouldUseAgentLogin(args)) {
+      } else if (shouldUseAgentLogin(loginArgs)) {
         const cachedResult = checkLoginOnly({ includeSecrets: true });
         if (cachedResult.status === 'ok') {
           printLoginResult(cachedResult);
@@ -398,17 +432,17 @@ async function main() {
             printLoginResult(browserResult);
           } else {
             const { startCodexQrLogin } = require('../lib/auth/qr-login');
-            const result = await startCodexQrLogin({ corpId: getArgValue(args, '--corp-id') });
+            const result = await startCodexQrLogin({ corpId: getArgValue(loginArgs, '--corp-id') });
             printLoginResult(result);
           }
         }
-      } else if (shouldUseBrowserHandoffLogin(args)) {
+      } else if (shouldUseBrowserHandoffLogin(loginArgs)) {
         const cachedResult = checkLoginOnly({ includeSecrets: true });
         if (cachedResult.status === 'ok') {
           printLoginResult(cachedResult);
         } else {
           const { codexLogin } = require('../lib/auth/codex-login');
-          const result = await codexLogin({ tool: args.includes('--codex') ? 'codex' : undefined });
+          const result = await codexLogin({ tool: loginArgs.includes('--codex') ? 'codex' : undefined });
           printLoginResult(result);
         }
       } else {
@@ -418,7 +452,7 @@ async function main() {
           break;
         }
         const { qrLogin } = require('../lib/auth/qr-login');
-        const result = await qrLogin({ corpId: getArgValue(args, '--corp-id') });
+        const result = await qrLogin({ corpId: getArgValue(loginArgs, '--corp-id') });
         console.log(JSON.stringify(result));
       }
       break;
@@ -437,8 +471,9 @@ async function main() {
       if (subCommand === 'status') {
         authStatus();
       } else if (subCommand === 'login') {
-        const loginType = shouldUseBrowserHandoffLogin(args) ? 'browser' : 'qrcode';
-        await authLogin({ type: loginType, corpId: getArgValue(args, '--corp-id') });
+        const authArgs = [subCommand, ...applyLoginEnvironmentFlags(args.slice(1))];
+        const loginType = shouldUseBrowserHandoffLogin(authArgs) ? 'browser' : 'qrcode';
+        await authLogin({ type: loginType, corpId: getArgValue(authArgs, '--corp-id') });
       } else if (subCommand === 'refresh') {
         authRefresh();
       } else if (subCommand === 'logout') {
@@ -493,6 +528,12 @@ async function main() {
       break;
     }
 
+    case 'corp-efficiency': {
+      const { run } = require('../lib/corp-efficiency/corp-efficiency');
+      await run(args);
+      break;
+    }
+
     case 'create-app': {
       const { run } = require('../lib/app/create-app');
       await run(args);
@@ -879,6 +920,9 @@ async function main() {
       } else if (subCommand === 'disable') {
         const { runDisable } = require('../lib/integration/integration-list');
         await runDisable(subArgs);
+      } else if (subCommand === 'check') {
+        const { run: runIntegrationCheck } = require('../lib/integration/integration-check');
+        await runIntegrationCheck(subArgs);
       } else {
         warn(t('cli.integration_unknown', subCommand));
         warn(t('cli.integration_help_hint'));

package/lib/auth/qr-login.js

@@ -24,7 +24,7 @@ const { saveCookieCache } = require('./login');
 const { t } = require('../core/i18n');
 const { warn } = require('../core/chalk');
 
-const { resolveLoginUrl, resolveEndpoint, deriveBaseUrlFromUrl } = require('../core/env-manager');
+const { resolveLoginUrl, resolveEndpoint, deriveBaseUrlFromUrl, getCurrentEnvConfig } = require('../core/env-manager');
 
 function shellQuote(value) {
   return `'${String(value).replace(/'/g, "'\\''")}'`;
@@ -34,9 +34,11 @@ function getTargetCorpId(options = {}, session = {}) {
   return options.corpId || options.targetCorpId || session.targetCorpId || null;
 }
 
-function buildCodexPollCommand(sessionFile, targetCorpId) {
+function buildCodexPollCommand(sessionFile, targetCorpId, envName) {
   const baseCommand = `openyida login --agent-poll ${shellQuote(sessionFile)}`;
-  return targetCorpId ? `${baseCommand} --corp-id ${shellQuote(targetCorpId)}` : baseCommand;
+  const envArg = envName ? ` --env ${shellQuote(envName)}` : '';
+  const corpArg = targetCorpId ? ` --corp-id ${shellQuote(targetCorpId)}` : '';
+  return `${baseCommand}${envArg}${corpArg}`;
 }
 
 function buildQrImageMarkdown(qrImageFile) {
@@ -55,7 +57,7 @@ function buildAgentQrResponseMarkdown(result) {
   return lines.join('\n');
 }
 
-function buildNeedQrScanResult({ qrUrl, qrImageFile, sessionFile, targetCorpId }) {
+function buildNeedQrScanResult({ qrUrl, qrImageFile, sessionFile, targetCorpId, envName }) {
   const qrImageMarkdown = buildQrImageMarkdown(qrImageFile);
   const result = {
     status: 'need_qr_scan',
@@ -65,7 +67,7 @@ function buildNeedQrScanResult({ qrUrl, qrImageFile, sessionFile, targetCorpId }
     qr_image_file: qrImageFile || null,
     qr_image_markdown: qrImageMarkdown,
     session_file: sessionFile,
-    poll_command: buildCodexPollCommand(sessionFile, targetCorpId),
+    poll_command: buildCodexPollCommand(sessionFile, targetCorpId, envName),
     message: 'Scan the QR code with DingTalk, then run poll_command.',
   };
   result.agent_response_markdown = buildAgentQrResponseMarkdown(result);
@@ -366,8 +368,9 @@ async function writeQrCodeImage(url, filePath, options = {}) {
 function isDingtalkOAuthChallengeUrl(url) {
   try {
     const parsedUrl = new URL(url);
-    return parsedUrl.hostname.endsWith('dingtalk.com') &&
-      parsedUrl.pathname.startsWith('/oauth2/');
+    const hostname = parsedUrl.hostname;
+    const isDingtalkDomain = hostname.endsWith('dingtalk.com') || hostname.endsWith('dingtalk.io');
+    return isDingtalkDomain && parsedUrl.pathname.startsWith('/oauth2/');
   } catch {
     return false;
   }
@@ -1012,7 +1015,8 @@ function buildCodexCorpInteraction(corpList) {
   };
 }
 
-function buildNeedCorpSelectionResult(sessionFile, corpList) {
+function buildNeedCorpSelectionResult(sessionFile, corpList, envName) {
+  const envArg = envName ? ` --env ${shellQuote(envName)}` : '';
   return {
     status: 'need_corp_selection',
     handoff_type: 'codex_native_select',
@@ -1024,7 +1028,7 @@ function buildNeedCorpSelectionResult(sessionFile, corpList) {
       main_org: !!corp.mainOrg,
     })),
     interaction: buildCodexCorpInteraction(corpList),
-    select_command_template: `openyida login --codex-select ${shellQuote(sessionFile)} --corp-id <corpId>`,
+    select_command_template: `openyida login --codex-select ${shellQuote(sessionFile)}${envArg} --corp-id <corpId>`,
   };
 }
 
@@ -1086,7 +1090,7 @@ async function maybeReturnCorpSelectionAfterExchange(session, sessionFile, optio
       stage: 'pending_corp_switch',
       updatedAt: new Date().toISOString(),
     });
-    return buildNeedCorpSelectionResult(sessionFile, corpList);
+    return buildNeedCorpSelectionResult(sessionFile, corpList, session.currentEnvName);
   }
 
   if (!selectedCorp && corpList.length === 1) {
@@ -1100,6 +1104,7 @@ function buildFakeCodexQrLoginResult(options = {}) {
   const sessionId = 'test-session';
   const { sessionFile, qrImageFile } = getCodexQrSessionPaths(sessionId);
   const targetCorpId = getTargetCorpId(options);
+  const currentEnvName = getCurrentEnvConfig().name;
   saveCodexQrSession(sessionFile, {
     schema_version: 1,
     mode: 'codex_qr_login',
@@ -1110,6 +1115,7 @@ function buildFakeCodexQrLoginResult(options = {}) {
     cookieHeader: '',
     context: { type: 'legacy' },
     targetCorpId,
+    currentEnvName,
     createdAt: new Date().toISOString(),
   });
 
@@ -1118,6 +1124,7 @@ function buildFakeCodexQrLoginResult(options = {}) {
     qrImageFile,
     sessionFile,
     targetCorpId,
+    envName: currentEnvName,
   });
 }
 
@@ -1128,6 +1135,7 @@ async function startCodexQrLogin(options = {}) {
 
   const baseUrl = (options.baseUrl || resolveEndpoint(null)).replace(/\/+$/, '');
   const targetCorpId = getTargetCorpId(options);
+  const currentEnvName = getCurrentEnvConfig().name;
   const sessionId = options.sessionId || createCodexQrSessionId();
   const { sessionFile, qrImageFile } = getCodexQrSessionPaths(sessionId);
 
@@ -1157,6 +1165,7 @@ async function startCodexQrLogin(options = {}) {
     cookieHeader,
     context,
     targetCorpId,
+    currentEnvName,
     createdAt: new Date().toISOString(),
   });
 
@@ -1165,6 +1174,7 @@ async function startCodexQrLogin(options = {}) {
     qrImageFile: imageWritten ? qrImageFile : null,
     sessionFile,
     targetCorpId,
+    envName: currentEnvName,
   });
 }
 
@@ -1199,9 +1209,10 @@ async function pollCodexQrLogin(sessionFile, options = {}) {
           corpList,
           stage: 'pending_dingtalk_oauth_org',
           targetCorpId,
+          currentEnvName: session.currentEnvName,
           updatedAt: new Date().toISOString(),
         });
-        return buildNeedCorpSelectionResult(sessionFile, corpList);
+        return buildNeedCorpSelectionResult(sessionFile, corpList, session.currentEnvName);
       }
     }
 
@@ -1436,5 +1447,6 @@ module.exports = {
     buildNeedQrScanResult,
     getTargetCorpId,
     deriveAliworkBaseUrl,
+    isDingtalkOAuthChallengeUrl,
   },
 };

package/lib/core/command-manifest.js

@@ -20,7 +20,7 @@ const COMMAND_GROUPS = [
     id: 'auth',
     titleKey: 'help.group_auth',
     commands: [
-      command('login', ['login'], 'login [--qr|--agent-qr|--codex|--browser] [--corp-id <corpId>]', 'help.cmd_login', {
+      command('login', ['login'], 'login [--qr|--agent-qr|--codex|--browser] [--env <name>|--overseas] [--corp-id <corpId>]', 'help.cmd_login', {
         requiresLogin: false,
         output: 'json',
       }),
@@ -31,7 +31,7 @@ const COMMAND_GROUPS = [
         requiresLogin: false,
         output: 'text|json',
       }),
-      command('env-management', ['env'], 'env <list|show|switch|add|remove>', 'help.cmd_env_management', {
+      command('env-management', ['env'], 'env <setup|list|show|switch|add|remove>', 'help.cmd_env_management', {
         requiresLogin: false,
       }),
     ],
@@ -41,6 +41,9 @@ const COMMAND_GROUPS = [
     titleKey: 'help.group_app',
     commands: [
       command('app-list', ['app-list'], 'app-list [--size N]', 'help.cmd_app_list'),
+      command('corp-efficiency', ['corp-efficiency'], 'corp-efficiency [overview|details|detail|groups|notify] [options] [--open|--no-open]', 'help.cmd_corp_efficiency', {
+        output: 'json',
+      }),
       command('create-app', ['create-app'], 'create-app "<name>"|--name <name> [options] [--open|--no-open]', 'help.cmd_create_app'),
       command('update-app', ['update-app'], 'update-app <appType> --name "..."', 'help.cmd_update_app'),
       command('export', ['export'], 'export <appType> [output]', 'help.cmd_export'),
@@ -128,6 +131,7 @@ const COMMAND_GROUPS = [
     titleKey: 'help.group_integration',
     commands: [
       command('integration.create', ['integration', 'create'], 'integration create <appType> ...', 'help.cmd_integration'),
+      command('integration.check', ['integration', 'check'], 'integration check <appType...>', 'help.cmd_integration_check'),
       command('dws', ['dws'], 'dws <command> [args]', 'help.cmd_dws'),
       command('dingtalk-link', ['dingtalk-link'], 'dingtalk-link <url> [--target fullScreen] [--legacy-scheme] [--json]', 'help.cmd_dingtalk_link', {
         requiresLogin: false,

package/lib/core/env-cmd.js

@@ -11,6 +11,7 @@
 
 'use strict';
 
+const { execSync } = require('child_process');
 const readline = require('readline');
 const { warn } = require('./chalk');
 const {
@@ -18,6 +19,10 @@ const {
   saveEnvsConfig,
   DEFAULT_BASE_URL,
   DEFAULT_LOGIN_URL,
+  DEFAULT_PUBLIC_ENV,
+  DEFAULT_INTERNATIONAL_ENV,
+  DEFAULT_ALIBABA_INTERNAL_ENV,
+  resolveEnvNameAlias,
 } = require('./env-manager');
 
 // ── 颜色常量 ──────────────────────────────────────────
@@ -67,6 +72,79 @@ function formatEnvLabel(envName, currentEnv) {
   return `${CYAN}${envName}${RESET}`;
 }
 
+function getLoginHost(loginUrl) {
+  try {
+    return new URL(loginUrl || DEFAULT_LOGIN_URL).hostname;
+  } catch {
+    return loginUrl || DEFAULT_LOGIN_URL;
+  }
+}
+
+function isBuiltinEnvName(envName) {
+  return ['public', 'intl', 'alibaba'].includes(envName);
+}
+
+function isDingTalkWukongRunning() {
+  if (process.platform !== 'darwin') {return false;}
+  try {
+    return execSync('ps -axo args', { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] })
+      .includes('/Applications/DingTalkWuKong.app/');
+  } catch {
+    return false;
+  }
+}
+
+function detectSetupRecommendation() {
+  if (process.env.OPENYIDA_ENV) {
+    return resolveEnvNameAlias(process.env.OPENYIDA_ENV);
+  }
+  if ((process.env.OPENYIDA_LOGIN_URL || '').includes('login.dingtalk.io')) {
+    return 'intl';
+  }
+  if ((process.env.OPENYIDA_ENDPOINT || '').includes('alibaba-inc.com')) {
+    return 'alibaba';
+  }
+  if (isDingTalkWukongRunning()) {
+    return 'intl';
+  }
+
+  let activeTool = null;
+  try {
+    activeTool = require('./utils').detectActiveTool();
+  } catch {
+    activeTool = null;
+  }
+  if (activeTool && activeTool.tool === 'wukong') {
+    return 'intl';
+  }
+
+  return 'public';
+}
+
+function switchToEnv(envName) {
+  const resolvedEnvName = resolveEnvNameAlias(envName);
+  const config = loadEnvsConfig();
+
+  if (!config.environments[resolvedEnvName]) {
+    warn(`${RED}错误：环境 "${envName}" 不存在${RESET}`);
+    warn(`使用 ${CYAN}openyida env list${RESET} 查看所有环境`);
+    process.exit(1);
+  }
+
+  const previousEnv = config.current;
+  config.current = resolvedEnvName;
+  saveEnvsConfig(config);
+
+  console.log('');
+  console.log(`${GREEN}✅ 已切换环境${RESET}`);
+  console.log(`  ${DIM}${previousEnv}${RESET} → ${GREEN}${BOLD}${resolvedEnvName}${RESET}`);
+  console.log(`  地址：${config.environments[resolvedEnvName].baseUrl}`);
+  console.log(`  登录：${getLoginHost(config.environments[resolvedEnvName].loginUrl)}`);
+  console.log('');
+  console.log(`${DIM}下一步：运行 openyida login；在悟空中可运行 openyida login --wukong${RESET}`);
+  console.log('');
+}
+
 // ── 子命令实现 ────────────────────────────────────────
 
 /**
@@ -88,6 +166,7 @@ function cmdList() {
       const label = formatEnvLabel(envName, config.current);
       console.log(`  ${label}`);
       console.log(`    ${DIM}地址：${RESET}${envConfig.baseUrl || DEFAULT_BASE_URL}`);
+      console.log(`    ${DIM}登录：${RESET}${getLoginHost(envConfig.loginUrl || DEFAULT_LOGIN_URL)}`);
       if (envConfig.description) {
         console.log(`    ${DIM}描述：${RESET}${envConfig.description}`);
       }
@@ -95,7 +174,7 @@ function cmdList() {
   }
 
   console.log('');
-  console.log(`${DIM}使用 openyida env switch <name> 切换环境${RESET}`);
+  console.log(`${DIM}使用 openyida env setup 进入向导，或 openyida env switch <name> 切换环境${RESET}`);
   console.log(`${DIM}使用 openyida env add <name> 添加私有化环境${RESET}`);
   console.log('');
 }
@@ -106,7 +185,7 @@ function cmdList() {
  */
 function cmdShow(envName) {
   const config = loadEnvsConfig();
-  const targetName = envName || config.current;
+  const targetName = resolveEnvNameAlias(envName || config.current);
   const envConfig = config.environments[targetName];
 
   if (!envConfig) {
@@ -146,30 +225,21 @@ function cmdSwitch(envName) {
     process.exit(1);
   }
 
+  const resolvedEnvName = resolveEnvNameAlias(envName);
   const config = loadEnvsConfig();
 
-  if (!config.environments[envName]) {
+  if (!config.environments[resolvedEnvName]) {
     warn(`${RED}错误：环境 "${envName}" 不存在${RESET}`);
     warn(`使用 ${CYAN}openyida env list${RESET} 查看所有环境`);
     process.exit(1);
   }
 
-  if (config.current === envName) {
-    console.log(`${YELLOW}当前已在 "${envName}" 环境，无需切换${RESET}`);
+  if (config.current === resolvedEnvName) {
+    console.log(`${YELLOW}当前已在 "${resolvedEnvName}" 环境，无需切换${RESET}`);
     return;
   }
 
-  const previousEnv = config.current;
-  config.current = envName;
-  saveEnvsConfig(config);
-
-  console.log('');
-  console.log(`${GREEN}✅ 已切换环境${RESET}`);
-  console.log(`  ${DIM}${previousEnv}${RESET} → ${GREEN}${BOLD}${envName}${RESET}`);
-  console.log(`  地址：${config.environments[envName].baseUrl}`);
-  console.log('');
-  console.log(`${DIM}提示：登录态已自动切换，如需重新登录请运行 openyida login --qr${RESET}`);
-  console.log('');
+  switchToEnv(resolvedEnvName);
 }
 
 /**
@@ -183,8 +253,9 @@ function cmdRemove(envName) {
     process.exit(1);
   }
 
-  if (envName === 'public') {
-    warn(`${RED}错误：不能删除默认的公有云环境 "public"${RESET}`);
+  envName = resolveEnvNameAlias(envName);
+  if (isBuiltinEnvName(envName)) {
+    warn(`${RED}错误：不能删除内置环境 "${envName}"${RESET}`);
     process.exit(1);
   }
 
@@ -235,6 +306,11 @@ async function cmdAdd(envName) {
     process.exit(1);
   }
 
+  if (resolveEnvNameAlias(envName) !== envName || isBuiltinEnvName(envName)) {
+    warn(`${RED}错误："${envName}" 是内置环境或内置别名，不能作为私有化环境名称${RESET}`);
+    process.exit(1);
+  }
+
   const config = loadEnvsConfig();
   const existingConfig = config.environments[envName];
 
@@ -302,6 +378,75 @@ async function cmdAdd(envName) {
   console.log('');
 }
 
+async function cmdSetup() {
+  const config = loadEnvsConfig();
+  const recommendedEnv = detectSetupRecommendation();
+  const options = [
+    {
+      key: 'public',
+      title: '阿里云公有云 / 国内钉钉',
+      baseUrl: DEFAULT_PUBLIC_ENV.baseUrl,
+      loginUrl: DEFAULT_PUBLIC_ENV.loginUrl,
+    },
+    {
+      key: 'intl',
+      title: '海外 DingTalk / Dingtalk Wukong',
+      baseUrl: DEFAULT_INTERNATIONAL_ENV.baseUrl,
+      loginUrl: DEFAULT_INTERNATIONAL_ENV.loginUrl,
+    },
+    {
+      key: 'alibaba',
+      title: '阿里内网员工环境',
+      baseUrl: DEFAULT_ALIBABA_INTERNAL_ENV.baseUrl,
+      loginUrl: DEFAULT_ALIBABA_INTERNAL_ENV.loginUrl,
+    },
+    {
+      key: 'custom',
+      title: '私有化部署 / 专属域名',
+      baseUrl: '自定义',
+      loginUrl: '自定义',
+    },
+  ];
+  const defaultIndex = Math.max(0, options.findIndex((item) => item.key === recommendedEnv));
+
+  console.log('');
+  console.log(`${BOLD}OpenYida 环境设置向导${RESET}`);
+  console.log(`${'─'.repeat(50)}`);
+  console.log(`${DIM}请选择客户实际登录入口。可随时用 openyida env switch 切换。${RESET}`);
+  console.log('');
+
+  options.forEach((item, index) => {
+    const isRecommended = index === defaultIndex;
+    console.log(`  ${CYAN}${index + 1}.${RESET} ${item.title}${isRecommended ? ` ${GREEN}← 推荐${RESET}` : ''}`);
+    console.log(`     ${DIM}地址：${item.baseUrl}${RESET}`);
+    console.log(`     ${DIM}登录：${getLoginHost(item.loginUrl)}${RESET}`);
+  });
+  console.log('');
+
+  const answer = await askQuestion(`${BOLD}选择环境${RESET}（1-${options.length}）：`, String(defaultIndex + 1));
+  const selectedIndex = Number.parseInt(answer, 10) - 1;
+  const selected = options[selectedIndex];
+  if (!selected) {
+    warn(`${RED}错误：无效选择${RESET}`);
+    process.exit(1);
+  }
+
+  if (selected.key === 'custom') {
+    const envName = await askQuestion(`${BOLD}私有化环境名称${RESET}（如 private-prod）：`, '');
+    await cmdAdd(envName);
+    return;
+  }
+
+  if (config.current === selected.key) {
+    console.log('');
+    console.log(`${YELLOW}当前已在 "${selected.key}" 环境，无需切换${RESET}`);
+    console.log('');
+    return;
+  }
+
+  switchToEnv(selected.key);
+}
+
 /**
  * 显示 env 命令帮助信息。
  */
@@ -314,6 +459,7 @@ function showHelp() {
   console.log('');
   console.log(`${CYAN}子命令：${RESET}`);
   console.log(`  ${GREEN}list${RESET}              列出所有环境及当前激活环境`);
+  console.log(`  ${GREEN}setup${RESET}             交互式选择公有云、海外、内网或私有化环境`);
   console.log(`  ${GREEN}add <name>${RESET}        交互式添加私有化环境配置`);
   console.log(`  ${GREEN}switch <name>${RESET}     切换当前激活环境`);
   console.log(`  ${GREEN}remove <name>${RESET}     移除环境配置`);
@@ -321,6 +467,7 @@ function showHelp() {
   console.log('');
   console.log(`${CYAN}示例：${RESET}`);
   console.log(`  ${BLUE}openyida env list${RESET}                     查看所有环境`);
+  console.log(`  ${BLUE}openyida env setup${RESET}                    进入环境设置向导`);
   console.log(`  ${BLUE}openyida env add private-prod${RESET}         添加私有化生产环境`);
   console.log(`  ${BLUE}openyida env switch private-prod${RESET}      切换到私有化环境`);
   console.log(`  ${BLUE}openyida env show private-prod${RESET}        查看环境详情`);
@@ -358,6 +505,12 @@ async function run(args) {
       cmdSwitch(subArgs[0]);
       break;
 
+    case 'setup':
+    case 'init':
+    case 'configure':
+      await cmdSetup();
+      break;
+
     case 'remove':
     case 'rm':
     case 'delete':