openyida 2026.7.19 → 2026.7.21

package/lib/core/legacy-schema-guard.js

@@ -0,0 +1,408 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { CliError } = require('./cli-error');
+
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'y', 'on', 'schema-managed']);
+const CONTEXT_FLAGS = new Set(['--schema-managed-context', '--resource-context', '--schema-context']);
+const STATE_FLAGS = new Set(['--schema-state', '--schema-state-path']);
+
+function extractLegacyGuardArgs(rawArgs = []) {
+  const args = [];
+  const guardOptions = {
+    schemaManaged: false,
+    contextInputs: [],
+    statePaths: [],
+  };
+
+  for (let index = 0; index < rawArgs.length; index++) {
+    const arg = rawArgs[index];
+    if (arg === '--schema-managed') {
+      guardOptions.schemaManaged = true;
+      continue;
+    }
+    if (typeof arg === 'string' && arg.startsWith('--schema-managed=')) {
+      guardOptions.schemaManaged = isTruthy(arg.slice('--schema-managed='.length));
+      continue;
+    }
+    const inlineContext = readInlineValue(arg, CONTEXT_FLAGS);
+    if (inlineContext !== null) {
+      guardOptions.contextInputs.push(inlineContext);
+      continue;
+    }
+    if (CONTEXT_FLAGS.has(arg)) {
+      const value = rawArgs[index + 1];
+      if (!value || String(value).startsWith('--')) {
+        throw invalidGuardInput(`${arg} requires a JSON value or file path`);
+      }
+      guardOptions.contextInputs.push(value);
+      index += 1;
+      continue;
+    }
+    const inlineState = readInlineValue(arg, STATE_FLAGS);
+    if (inlineState !== null) {
+      guardOptions.statePaths.push(inlineState);
+      continue;
+    }
+    if (STATE_FLAGS.has(arg)) {
+      const value = rawArgs[index + 1];
+      if (!value || String(value).startsWith('--')) {
+        throw invalidGuardInput(`${arg} requires a state file path`);
+      }
+      guardOptions.statePaths.push(value);
+      index += 1;
+      continue;
+    }
+    args.push(arg);
+  }
+
+  return { args, guardOptions };
+}
+
+function assertLegacyDirectWriteAllowed(target = {}, options = {}) {
+  const env = options.env || process.env;
+  const fsImpl = options.fsImpl || fs;
+  const cwd = options.cwd || process.cwd();
+  const guardOptions = options.guardOptions || {};
+  const contexts = collectContexts(guardOptions, env, fsImpl, cwd);
+  const statePaths = collectStatePaths(guardOptions, env);
+  const reasons = [];
+
+  if (guardOptions.schemaManaged || isTruthy(env.OPENYIDA_SCHEMA_MANAGED)) {
+    reasons.push({ source: 'explicit_schema_managed_flag' });
+  }
+
+  for (const context of contexts) {
+    const managedReason = matchManagedContext(context, target);
+    if (managedReason) {
+      reasons.push(managedReason);
+    }
+  }
+
+  for (const statePath of statePaths) {
+    const stateReason = matchManagedStatePath(statePath, target, { fsImpl, cwd });
+    if (stateReason) {
+      reasons.push(stateReason);
+    }
+  }
+
+  if (reasons.length > 0) {
+    throw new CliError(
+      `Refusing legacy direct ${target.command || 'write'} because the target is schema-managed. Use openyida schema validate -> schema plan -> schema apply.`,
+      {
+        code: 'LEGACY_SCHEMA_MANAGED_GUARD',
+        details: sanitizeGuardDetails(target, reasons),
+      }
+    );
+  }
+
+  const conflict = findBoundResourceConflict(contexts, target);
+  if (conflict) {
+    throw new CliError(
+      `Refusing legacy direct ${target.command || 'create'} because resource context already contains a bound ${conflict.resourceType}. Reuse the bound resource or set allowCreate=true explicitly.`,
+      {
+        code: 'LEGACY_RESOURCE_CONTEXT_CONFLICT',
+        details: sanitizeGuardDetails(target, [conflict]),
+      }
+    );
+  }
+}
+
+function collectContexts(guardOptions, env, fsImpl, cwd) {
+  const inputs = [];
+  if (env.OPENYIDA_RESOURCE_CONTEXT) {
+    inputs.push(env.OPENYIDA_RESOURCE_CONTEXT);
+  }
+  if (env.OPENYIDA_SCHEMA_CONTEXT) {
+    inputs.push(env.OPENYIDA_SCHEMA_CONTEXT);
+  }
+  if (env.OPENYIDA_SCHEMA_MANAGED_CONTEXT) {
+    inputs.push(env.OPENYIDA_SCHEMA_MANAGED_CONTEXT);
+  }
+  if (Array.isArray(guardOptions.contextInputs)) {
+    inputs.push(...guardOptions.contextInputs);
+  }
+  return inputs.map(input => parseContextInput(input, { fsImpl, cwd }));
+}
+
+function collectStatePaths(guardOptions, env) {
+  const paths = [];
+  if (env.OPENYIDA_SCHEMA_STATE) {
+    paths.push(env.OPENYIDA_SCHEMA_STATE);
+  }
+  if (env.OPENYIDA_SCHEMA_STATE_PATH) {
+    paths.push(env.OPENYIDA_SCHEMA_STATE_PATH);
+  }
+  if (Array.isArray(guardOptions.statePaths)) {
+    paths.push(...guardOptions.statePaths);
+  }
+  return paths.filter(Boolean);
+}
+
+function parseContextInput(input, options = {}) {
+  if (input && typeof input === 'object' && !Array.isArray(input)) {
+    return input;
+  }
+  const raw = String(input || '').trim();
+  if (!raw) {
+    throw invalidGuardInput('Resource context is empty');
+  }
+  const fsImpl = options.fsImpl || fs;
+  const cwd = options.cwd || process.cwd();
+  if (raw.startsWith('{') || raw.startsWith('[')) {
+    return parseJson(raw, 'Resource context is not valid JSON');
+  }
+  const contextPath = path.resolve(cwd, raw);
+  if (!fsImpl.existsSync(contextPath)) {
+    throw invalidGuardInput(`Resource context file not found: ${raw}`);
+  }
+  return parseJson(fsImpl.readFileSync(contextPath, 'utf8'), `Resource context file is not valid JSON: ${raw}`);
+}
+
+function matchManagedContext(context, target) {
+  if (!context || typeof context !== 'object' || Array.isArray(context)) {
+    return null;
+  }
+  if (isManagedMarker(context)) {
+    return { source: 'schema_managed_context', resourceType: target.resourceType };
+  }
+  const candidates = collectContextResources(context, target.resourceType);
+  for (const candidate of candidates) {
+    if (isManagedMarker(candidate) && resourceMatchesTarget(candidate, target)) {
+      return {
+        source: 'schema_managed_context',
+        resourceType: target.resourceType,
+        key: candidate.key || candidate.name || candidate.source,
+      };
+    }
+  }
+  if (target.resourceType === 'process' && target.formUuid) {
+    for (const candidate of collectContextResources(context, 'form')) {
+      if (isManagedMarker(candidate) && resourceMatchesTarget(candidate, { resourceType: 'form', formUuid: target.formUuid })) {
+        return {
+          source: 'schema_managed_form_context',
+          resourceType: 'form',
+          key: candidate.key || candidate.name || candidate.source,
+        };
+      }
+    }
+  }
+  if (target.resourceType !== 'app' && target.appType) {
+    for (const candidate of collectContextResources(context, 'app')) {
+      if (isManagedMarker(candidate) && resourceMatchesTarget(candidate, { resourceType: 'app', appType: target.appType })) {
+        return {
+          source: 'schema_managed_app_context',
+          resourceType: 'app',
+          key: candidate.key || candidate.name || candidate.source,
+        };
+      }
+    }
+  }
+  return null;
+}
+
+function collectContextResources(context, resourceType) {
+  const values = [];
+  const direct = context[resourceType];
+  if (direct) {
+    values.push(direct);
+  }
+  if (resourceType === 'page' && context.pageContext) {
+    values.push(context.pageContext);
+  }
+  if (resourceType === 'form' && context.formContext) {
+    values.push(context.formContext);
+  }
+  if (Array.isArray(context.resources)) {
+    values.push(...context.resources.filter(item => !item.resourceType || item.resourceType === resourceType));
+  }
+  return values.filter(item => item && typeof item === 'object' && !Array.isArray(item));
+}
+
+function matchManagedStatePath(statePath, target, options = {}) {
+  const fsImpl = options.fsImpl || fs;
+  const cwd = options.cwd || process.cwd();
+  const resolved = path.resolve(cwd, statePath);
+  if (!fsImpl.existsSync(resolved)) {
+    throw invalidGuardInput(`Schema state file not found: ${statePath}`);
+  }
+  const state = parseJson(fsImpl.readFileSync(resolved, 'utf8'), `Schema state file is not valid JSON: ${statePath}`);
+  if (!state || state.kind !== 'openyida_resource_state' || !state.resources || typeof state.resources !== 'object') {
+    throw invalidGuardInput(`Schema state file is not an OpenYida resource state: ${statePath}`);
+  }
+  const directMatch = matchStateResourceCollection(state.resources[target.resourceType], target);
+  if (directMatch) {
+    return { source: 'schema_state', statePath, resourceType: target.resourceType, key: directMatch.key };
+  }
+  if (target.resourceType === 'process' && target.formUuid) {
+    const formMatch = matchStateResourceCollection(state.resources.form, { resourceType: 'form', formUuid: target.formUuid });
+    if (formMatch) {
+      return { source: 'schema_state_form', statePath, resourceType: 'form', key: formMatch.key };
+    }
+  }
+  if (target.appType) {
+    const appMatch = matchStateResourceCollection(state.resources.app, { resourceType: 'app', appType: target.appType });
+    if (appMatch) {
+      return { source: 'schema_state_app', statePath, resourceType: 'app', key: appMatch.key };
+    }
+  }
+  return null;
+}
+
+function matchStateResourceCollection(collection, target) {
+  if (!collection || typeof collection !== 'object') {
+    return null;
+  }
+  for (const [key, entry] of Object.entries(collection)) {
+    if (entry && typeof entry === 'object' && resourceMatchesTarget(entry.bindings || {}, target)) {
+      return { key };
+    }
+  }
+  return null;
+}
+
+function findBoundResourceConflict(contexts, target) {
+  if (target.action !== 'create') {
+    return null;
+  }
+  for (const context of contexts) {
+    for (const resourceType of getCreateConflictResourceTypes(target)) {
+      const candidates = collectContextResources(context, resourceType);
+      for (const candidate of candidates) {
+        if (candidate && candidate.allowCreate === false && hasBoundIdentity(candidate, resourceType)) {
+          return {
+            source: 'resource_context',
+            resourceType,
+          };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function getCreateConflictResourceTypes(target) {
+  if (target.resourceType === 'process') {
+    return ['process', 'form'];
+  }
+  return [target.resourceType];
+}
+
+function hasBoundIdentity(resource, resourceType) {
+  if (resourceType === 'app') {
+    return hasNonEmptyString(resource.appType);
+  }
+  if (resourceType === 'page' || resourceType === 'form') {
+    return hasNonEmptyString(resource.formUuid) || hasNonEmptyString(resource.pageId);
+  }
+  if (resourceType === 'process') {
+    return hasNonEmptyString(resource.processCode) || hasNonEmptyString(resource.formUuid);
+  }
+  return false;
+}
+
+function resourceMatchesTarget(resource, target) {
+  if (!resource || typeof resource !== 'object') {
+    return false;
+  }
+
+  if (target.resourceType === 'app') {
+    return hasNonEmptyString(target.appType) &&
+      hasNonEmptyString(resource.appType) &&
+      String(resource.appType) === String(target.appType);
+  }
+
+  if (target.resourceType === 'form' || target.resourceType === 'page') {
+    const targetFormUuid = target.formUuid || target.pageId;
+    const resourceFormUuid = resource.formUuid || resource.pageId;
+    return hasNonEmptyString(targetFormUuid) &&
+      hasNonEmptyString(resourceFormUuid) &&
+      String(resourceFormUuid) === String(targetFormUuid);
+  }
+
+  if (target.resourceType === 'process') {
+    if (hasNonEmptyString(target.processCode)) {
+      return hasNonEmptyString(resource.processCode) &&
+        String(resource.processCode) === String(target.processCode);
+    }
+    const targetFormUuid = target.formUuid || target.pageId;
+    const resourceFormUuid = resource.formUuid || resource.pageId;
+    return hasNonEmptyString(targetFormUuid) &&
+      hasNonEmptyString(resourceFormUuid) &&
+      String(resourceFormUuid) === String(targetFormUuid);
+  }
+
+  return false;
+}
+
+function isManagedMarker(value) {
+  if (!value || typeof value !== 'object') {
+    return false;
+  }
+  return value.schemaManaged === true ||
+    value.managed === true ||
+    value.executionPath === 'schema-managed' ||
+    value.path === 'schema-managed' ||
+    value.managedBy === 'schema' ||
+    value.source === 'schema_state' ||
+    value.source === 'schema_manifest' ||
+    value.kind === 'openyida_schema_managed_context';
+}
+
+function readInlineValue(arg, names) {
+  if (typeof arg !== 'string') {
+    return null;
+  }
+  for (const name of names) {
+    const prefix = `${name}=`;
+    if (arg.startsWith(prefix)) {
+      return arg.slice(prefix.length);
+    }
+  }
+  return null;
+}
+
+function parseJson(raw, message) {
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw invalidGuardInput(message);
+  }
+}
+
+function invalidGuardInput(message) {
+  return new CliError(message, {
+    code: 'LEGACY_SCHEMA_GUARD_INVALID_CONTEXT',
+  });
+}
+
+function isTruthy(value) {
+  return TRUE_VALUES.has(String(value || '').trim().toLowerCase());
+}
+
+function hasNonEmptyString(value) {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function sanitizeGuardDetails(target, reasons) {
+  return {
+    command: target.command,
+    resourceType: target.resourceType,
+    action: target.action,
+    appType: target.appType,
+    formUuid: target.formUuid,
+    processCode: target.processCode,
+    reasons,
+  };
+}
+
+module.exports = {
+  assertLegacyDirectWriteAllowed,
+  extractLegacyGuardArgs,
+  _private: {
+    matchManagedContext,
+    matchManagedStatePath,
+    resourceMatchesTarget,
+  },
+};

package/lib/core/locales/en.js

@@ -43,6 +43,10 @@ module.exports = {
     cmd_publish: 'Compile and publish custom page',
     cmd_update_form_config: 'Update form configuration',
     cmd_get_form_config: 'Query form configuration',
+    group_schema: 'Schema-as-Code',
+    cmd_schema_validate: 'Validate Schema-as-Code manifest locally',
+    cmd_schema_plan: 'Plan Schema-as-Code changes with read-only remote observation',
+    cmd_schema_apply: 'Apply a reviewed Schema-as-Code plan with checkpoints and recovery guards',
     group_data: 'Data & Permissions',
     cmd_data: 'Unified data management (form/process/task/subform)',
     cmd_task_center: 'Global task center (todo/processed/cc etc.)',
@@ -127,7 +131,7 @@ Usage:
 Commands:
   env                                                          Detect AI tool environment and login status
   copy [--force]                                               Copy project directory to current AI tool environment
-  login                                                        Manage login credentials (cache first, then QR scan)
+  login                                                        Manage OAuth token credentials
   logout                                                       Logout / switch account
   create-app "<name>" [desc] [icon] [color] [theme] [nav] [layout]  Create an app, output appType
   create-page <appType> "<pageName>" [--mode dashboard]        Create a custom page, output pageId
@@ -285,6 +289,9 @@ Examples:
     save_permission_usage: 'Usage: openyida save-permission <appType> <formUuid> [--data-permission <json>] [--action-permission <json>]',
     save_permission_example: "Example: openyida save-permission APP_XXX FORM-XXX --data-permission '{\"role\":\"DEFAULT\",\"dataRange\":\"SELF\"}'",
     exec_failed: '\n❌ Execution failed: {0}',
+    login_usage: 'Usage: openyida login [entryUrl|--public|--alibaba|--intl] [--check-only] [--json] [--client-id <clientId>]',
+    login_example: 'Examples:\n  openyida login                         # Open browser via OAuth loopback login\n  openyida login --check-only --json     # Check token auth status only\n  openyida login --intl                  # Login against the international environment\n  OPENYIDA_NO_BROWSER=1 openyida login   # Only suppress auto-opening the browser; this is not a CLI login mode\n  openyida auth login                    # Login alias',
+    login_unsupported_option: 'Removed legacy login option is no longer supported: {0}. Use token/OAuth login; host-injected mode only checks the injected token.',
     auth_usage: 'Usage: openyida auth <status|login|refresh|logout>',
     auth_example: 'Examples:\n  openyida auth status         # View login status\n  openyida auth login          # Perform login\n  openyida auth refresh        # Refresh login session\n  openyida auth logout         # Logout',
     org_usage: 'Usage: openyida org <list|switch> [--json] [--corp-id <corpId>]',
@@ -488,8 +495,6 @@ Examples:
     csrf_ok: '  ✅ csrf_token: {0}...',
     corp_id_ok: '  ✅ corpId: {0}',
     no_playwright: '\n❌ This version only supports token login. Run openyida login.',
-    playwright_install1: '   npm install -g playwright',
-    playwright_install2: '   npx playwright install chromium',
     browser_opening: '\n🔐 Opening browser for OAuth login...',
     login_url_label: '  Login URL: {0}',
     waiting_login: '  Waiting for login (up to 10 minutes)...',
@@ -1200,49 +1205,6 @@ Examples:
     example: 'Example: openyida publish pages/src/xxx.js APP_XXX FORM-XXX --health-check',
   },
 
-  // ── token-only disabled QR login ────────────────────────────────
-  qr_login: {
-    title: '🔐 Yida Terminal QR Code Login',
-    step_init: '  Step 1: Initializing session...',
-    step_get_qr: '  Step 2: Fetching QR code...',
-    scan_hint: '  📱 Please scan the QR code below with DingTalk:',
-    browser_alternative: '  💡 If this is not a cloud/remote machine, use browser login instead; if QR scan fails, try: {0}',
-    qr_url_label: '  QR code URL: {0}',
-    waiting_scan: '  ⏳ Waiting for scan (up to 2 minutes)...',
-    scanned_confirm: '  ✅ QR code scanned! Please confirm login on your phone...',
-    scan_success: '  ✅ Scan confirmed!',
-    step_exchange: '  Step 4: Exchanging login credentials...',
-    step_get_corps: '  Step 5: Fetching organization list...',
-    step_switch_corp: '  Step 7: Switching to selected organization...',
-    only_one_corp: '  ✅ Single organization detected: {0}, auto-selected',
-    select_corp_prompt: '  🏢 Multiple organizations found, please select one:',
-    select_corp_input: '  Enter number (1-{0}): ',
-    select_corp_invalid: '  ❌ Invalid input, please enter a number between 1 and {0}',
-    target_corp_not_found: 'Specified corpId was not found in accessible organizations: {0}',
-    corp_selected: '  ✅ Selected organization: {0}',
-    login_success: '✅ Login successful!',
-    qrcode_fallback: '  ⚠️  qrcode package not installed, please visit the URL below manually:',
-    qrcode_render_failed: '  ⚠️  QR code render failed ({0}), please visit the URL below:',
-    get_qr_failed: 'Failed to parse QR code response: {0}',
-    get_qr_api_failed: 'QR code API failed: {0}',
-    get_qr_error: 'Failed to get QR code: {0}',
-    qr_expired: 'QR code expired, please login again',
-    poll_timeout: 'Scan timeout (2 minutes), please login again',
-    poll_error: 'Failed to poll scan status: {0}',
-    exchange_failed: 'Failed to parse auth code exchange response: {0}',
-    exchange_api_failed: 'Auth code exchange API failed: {0}',
-    exchange_error: 'Failed to exchange auth code: {0}',
-    get_corp_list_failed: 'Failed to parse organization list response: {0}',
-    get_corp_list_api_failed: 'Organization list API failed: {0}',
-    get_corps_warn: '  ⚠️  Failed to get organization list ({0}), using default organization',
-    switch_corp_failed: 'Failed to switch organization: {0}',
-    switch_corp_warn: '  ⚠️  Failed to switch organization ({0}), using current organization',
-    select_corp_warn: '  ⚠️  Organization selection failed ({0}), using default organization',
-    no_corp_available: 'No accessible organizations found',
-    no_csrf_in_cookie: 'Login succeeded but no csrf_token found, please try again',
-    stdin_closed: 'Input stream closed, cannot select organization',
-  },
-
   // ── scripts/postinstall.js ─────────────────────────
   postinstall: {
     welcome_title: '  🎉 Welcome to OpenYida!                                     ',

package/lib/core/locales/zh.js

@@ -43,6 +43,10 @@ module.exports = {
     cmd_publish: '编译并发布自定义页面',
     cmd_update_form_config: '更新表单配置',
     cmd_get_form_config: '查询表单配置',
+    group_schema: 'Schema-as-Code',
+    cmd_schema_validate: '本地校验 Schema-as-Code Manifest',
+    cmd_schema_plan: '只读观测远端并规划 Schema-as-Code 变更',
+    cmd_schema_apply: '使用 checkpoint 和恢复护栏执行已审阅的 Schema-as-Code 计划',
     group_data: '数据 & 权限',
     cmd_data: '统一数据管理（表单/流程/任务/子表单）',
     cmd_task_center: '全局任务中心（待办/已处理/抄送等）',
@@ -127,7 +131,7 @@ openyida - 宜搭命令行工具
 命令：
   env                                                          检测当前 AI 工具环境和登录态
   copy [--force]                                               复制 project 工作目录到当前 AI 工具环境
-  login                                                        登录态管理（优先缓存，否则扫码）
+  login                                                        OAuth token 登录态管理
   logout                                                       退出登录 / 切换账号
   create-app "<名称>" [描述] [图标] [颜色] [主题色] [导航风格] [布局]   创建应用，输出 appType
   create-page <appType> "<页面名>" [--mode dashboard]          创建自定义页面，输出 pageId
@@ -286,6 +290,9 @@ openyida - 宜搭命令行工具
     save_permission_usage: '用法: openyida save-permission <appType> <formUuid> [--data-permission <json>] [--action-permission <json>]',
     save_permission_example: "示例: openyida save-permission APP_XXX FORM-XXX --data-permission '{\"role\":\"DEFAULT\",\"dataRange\":\"SELF\"}'",
     exec_failed: '\n❌ 执行失败: {0}',
+    login_usage: '用法: openyida login [entryUrl|--public|--alibaba|--intl] [--check-only] [--json] [--client-id <clientId>]',
+    login_example: '示例:\n  openyida login                         # 通过 OAuth loopback 打开浏览器登录\n  openyida login --check-only --json     # 只检查 token 登录态\n  openyida login --intl                  # 使用国际站环境登录\n  OPENYIDA_NO_BROWSER=1 openyida login   # 仅抑制自动打开浏览器，不是 CLI 登录模式\n  openyida auth login                    # 登录入口别名',
+    login_unsupported_option: '已删除的旧登录参数不再支持: {0}。请使用 token/OAuth 登录；host 注入模式下只检查宿主注入的 token。',
     first_run_title: '  🤖 OpenYida - AI 问答模式已开启！                         ',
     first_run_welcome: '  {0}欢迎首次使用 OpenYida！{1} 以下是快速上手指南：',
     first_run_way1_title: '  📝 方式一：直接描述需求',
@@ -460,8 +467,6 @@ openyida - 宜搭命令行工具
     csrf_ok: '  ✅ csrf_token: {0}...',
     corp_id_ok: '  ✅ corpId: {0}',
     no_playwright: '\n❌ 当前版本仅支持 token 登录，请运行 openyida login。',
-    playwright_install1: '   npm install -g playwright',
-    playwright_install2: '   npx playwright install chromium',
     browser_opening: '\n🔐 正在打开浏览器完成 OAuth 登录...',
     login_url_label: '  登录地址: {0}',
     waiting_login: '  等待登录完成（最长等待 10 分钟）...',
@@ -1194,49 +1199,6 @@ openyida - 宜搭命令行工具
     example: '示例：openyida publish pages/src/xxx.js APP_XXX FORM-XXX --health-check',
   },
 
-  // ── token-only disabled QR login ────────────────────────────────
-  qr_login: {
-    title: '🔐 宜搭终端二维码登录',
-    step_init: '  Step 1: 初始化会话...',
-    step_get_qr: '  Step 2: 获取二维码...',
-    scan_hint: '  📱 请用钉钉扫描以下二维码登录：',
-    browser_alternative: '  💡 如果当前不是云端/远程电脑，建议使用浏览器登录；扫码失败也请尝试：{0}',
-    qr_url_label: '  二维码链接: {0}',
-    waiting_scan: '  ⏳ 等待扫码中（最长 2 分钟）...',
-    scanned_confirm: '  ✅ 已扫码！请在手机上确认登录...',
-    scan_success: '  ✅ 扫码确认成功！',
-    step_exchange: '  Step 4: 获取登录凭证...',
-    step_get_corps: '  Step 5: 获取组织列表...',
-    step_switch_corp: '  Step 7: 切换到目标组织...',
-    only_one_corp: '  ✅ 检测到唯一组织：{0}，自动选择',
-    select_corp_prompt: '  🏢 检测到多个可访问组织，请选择：',
-    select_corp_input: '  请输入序号 (1-{0}): ',
-    select_corp_invalid: '  ❌ 无效输入，请输入 1 到 {0} 之间的数字',
-    target_corp_not_found: '未在可访问组织中找到指定 corpId：{0}',
-    corp_selected: '  ✅ 已选择组织：{0}',
-    login_success: '✅ 登录成功！',
-    qrcode_fallback: '  ⚠️  qrcode 包未安装，请手动访问以下链接完成登录：',
-    qrcode_render_failed: '  ⚠️  二维码渲染失败（{0}），请手动访问以下链接：',
-    get_qr_failed: '获取二维码响应解析失败: {0}',
-    get_qr_api_failed: '获取二维码接口失败: {0}',
-    get_qr_error: '获取二维码失败: {0}',
-    qr_expired: '二维码已过期，请重新登录',
-    poll_timeout: '等待扫码超时（2 分钟），请重新登录',
-    poll_error: '轮询扫码状态失败: {0}',
-    exchange_failed: '换取登录凭证响应解析失败: {0}',
-    exchange_api_failed: '换取登录凭证接口失败: {0}',
-    exchange_error: '换取登录凭证失败: {0}',
-    get_corp_list_failed: '获取组织列表响应解析失败: {0}',
-    get_corp_list_api_failed: '获取组织列表接口失败: {0}',
-    get_corps_warn: '  ⚠️  获取组织列表失败（{0}），将使用默认组织',
-    switch_corp_failed: '切换组织失败: {0}',
-    switch_corp_warn: '  ⚠️  切换组织失败（{0}），将使用当前组织',
-    select_corp_warn: '  ⚠️  组织选择失败（{0}），将使用默认组织',
-    no_corp_available: '未找到可访问的组织',
-    no_csrf_in_cookie: '登录成功但未获取到 csrf_token，请重试',
-    stdin_closed: '输入流已关闭，无法选择组织',
-  },
-
   // ── scripts/postinstall.js ─────────────────────────
   postinstall: {
     welcome_title: '  🎉 欢迎使用 OpenYida！                                    ',

package/lib/core/sample.js

@@ -171,7 +171,7 @@ function applyTemplateVariables(content, variables) {
  */
 async function run(args) {
   // --list 模式
-  if (args.includes('--list') || args.length === 0) {
+  if (args.includes('--list') || args.includes('--help') || args.includes('-h') || args.length === 0) {
     printSampleList();
     return;
   }