openyida 2026.7.21 → 2026.7.22

package/bin/yida.js

@@ -14,7 +14,7 @@ const { version: currentVersion } = require('../package.json');
 const { t } = require('../lib/core/i18n');
 const { warn } = require('../lib/core/chalk');
 const { CliError, isCliError, toErrorPayload } = require('../lib/core/cli-error');
-const { COMMAND_GROUPS, buildCommandManifest } = require('../lib/core/command-manifest');
+const { COMMAND_GROUPS, buildCommandManifest, findCommandSuggestion } = require('../lib/core/command-manifest');
 
 const command = process.argv[2];
 const args = process.argv.slice(3);
@@ -477,6 +477,33 @@ function throwCliUsage(...lines) {
   });
 }
 
+function formatSuggestionMessage(suggestion) {
+  if (!suggestion) {
+    return '';
+  }
+  if (suggestion.message_key) {
+    return t(suggestion.message_key, ...(suggestion.message_args || []));
+  }
+  return '';
+}
+
+function throwUnknownCommand(commandName, commandArgs = []) {
+  const suggestion = findCommandSuggestion([commandName, ...commandArgs]);
+  const lines = [t('cli.unknown_command', commandName)];
+  if (suggestion) {
+    lines.push(t('cli.command_suggestion', suggestion.suggested_usage));
+    const suggestionMessage = formatSuggestionMessage(suggestion);
+    if (suggestionMessage) {
+      lines.push(suggestionMessage);
+    }
+  }
+  lines.push(t('cli.run_help'));
+  throw new CliError(lines.filter(Boolean).join('\n'), {
+    code: 'INVALID_ARGUMENTS',
+    details: suggestion ? { suggestion } : undefined,
+  });
+}
+
 function hasHelpFlag(cliArgs = []) {
   return cliArgs.includes('--help') || cliArgs.includes('-h');
 }
@@ -1147,7 +1174,7 @@ async function main() {
     }
 
     default: {
-      throwCliUsage(t('cli.unknown_command', command), t('cli.run_help'));
+      throwUnknownCommand(command, args);
     }
   }
 }

package/lib/app/canvas-compile.js

@@ -35,8 +35,9 @@ const Babel = require('@babel/standalone');
  * 逐条镜像自 @ali/vc-deep-yida 的
  *   src/components/yida-code-canvas/dependencies.ts → getModuleAliasMap()
  * 只保留运行时真正用到的 windowAlias（资源 URL 由画布运行时按别名注入，
- * 本地编译不关心 CDN 地址）。若此处与物料白名单漂移，编译产物仍可运行，
- * 只是未收录的包会在浏览器端 `${name} is not found in dependencies map` 告警。
+ * 本地编译不关心 CDN 地址）。默认拒绝未收录依赖；如果宜搭物料依赖表已经
+ * 先于 CLI 升级，可临时设置 OPENYIDA_CANVAS_ALLOW_UNSUPPORTED_IMPORTS=1
+ * 退回旧的 window["pkg"] 映射，避免白名单漂移阻断发布。
  * @type {Record<string, string>}
  */
 const MODULE_ALIAS_MAP = {
@@ -59,6 +60,19 @@ const IMPORT_SIDE_EFFECT_PATTERN = /import\s+['"]([^'"]+)['"]/g;
 const REQUIRE_PATTERN = /require\(\s*['"]([^'"]+)['"]\s*\)/g;
 const DYNAMIC_IMPORT_PATTERN = /import\(\s*['"]([^'"]+)['"]\s*\)/g;
 
+function isTruthy(value) {
+  return ['1', 'true', 'yes', 'on'].includes(String(value || '').trim().toLowerCase());
+}
+
+function shouldAllowUnsupportedBareImports(options = {}, env = process.env) {
+  return options.allowUnsupportedBareImports === true ||
+    isTruthy(env.OPENYIDA_CANVAS_ALLOW_UNSUPPORTED_IMPORTS);
+}
+
+function packageTempName(pkg) {
+  return String(pkg || 'module').replace(/[^A-Za-z0-9_$]+/g, '_') || 'module';
+}
+
 function stripJsComments(code) {
   return String(code || '')
     .replace(/\/\*[\s\S]*?\*\//g, '')
@@ -113,16 +127,27 @@ function resolveWindowAlias(pkg) {
  *   export const x = ...            → const x = ...（去掉 export 关键字）
  * @param {{ types: import('@babel/types') }} babel
  */
-function esmToWindowPlugin({ types: t }) {
-  function moduleExpr(pkg) {
-    const alias = resolveWindowAlias(pkg);
+function esmToWindowPlugin({ types: t }, options = {}) {
+  const allowUnsupportedBareImports = options.allowUnsupportedBareImports === true;
+
+  function moduleExpr(pkg, alias) {
     if (alias) {
       return t.memberExpression(t.identifier('window'), t.identifier(alias));
     }
-    // 未收录包：退化为 window["pkg"]，运行时若未注入会自然报错（与线上一致）。
     return t.memberExpression(t.identifier('window'), t.stringLiteral(pkg), true);
   }
 
+  function buildUnsupportedBareImportError(path, pkg) {
+    return path.buildCodeFrameError(
+      `Code Canvas 不支持从裸包 "${pkg}" 导入绑定。`
+      + '只允许 MODULE_ALIAS_MAP 白名单依赖；'
+      + '宜搭平台运行态全局对象请显式使用 window.* 访问'
+      + '（例如 window.Deep、window.DeepYida、window.YidaNativeComponents），不要从包中 import。'
+      + '若已确认宜搭物料运行态已注入该包且 CLI 白名单滞后，可临时设置 '
+      + 'OPENYIDA_CANVAS_ALLOW_UNSUPPORTED_IMPORTS=1 退回 legacy window["pkg"] 映射。'
+    );
+  }
+
   return {
     name: 'yida-esm-to-window',
     visitor: {
@@ -140,10 +165,14 @@ function esmToWindowPlugin({ types: t }) {
           path.remove();
           return;
         }
+        const alias = resolveWindowAlias(pkg);
+        if (!alias && !allowUnsupportedBareImports) {
+          throw buildUnsupportedBareImportError(path, pkg);
+        }
 
         const decls = [];
-        const tmp = path.scope.generateUidIdentifier(resolveWindowAlias(pkg) || 'mod');
-        decls.push(t.variableDeclarator(t.cloneNode(tmp), moduleExpr(pkg)));
+        const tmp = path.scope.generateUidIdentifier(alias || packageTempName(pkg));
+        decls.push(t.variableDeclarator(t.cloneNode(tmp), moduleExpr(pkg, alias)));
 
         const namedProps = [];
         for (const spec of specifiers) {
@@ -230,7 +259,7 @@ function esmToWindowPlugin({ types: t }) {
  * @param {string} source 原始 React/JSX/TSX 源码
  * @returns {{ runtimeCode: string, importedModules: string }}
  */
-function compileCanvasLocal(source) {
+function compileCanvasLocal(source, options = {}) {
   const importedModules = extractImportedModules(source);
 
   // 第一步：剥类型 + 转 JSX（classic runtime，产出 React.createElement，
@@ -265,7 +294,9 @@ function compileCanvasLocal(source) {
   // 第二步：把 import/export 改写成 window 别名 + YidaComp。
   const stage2 = Babel.transform(intermediate, {
     filename: 'canvas.js',
-    plugins: [esmToWindowPlugin],
+    plugins: [[esmToWindowPlugin, {
+      allowUnsupportedBareImports: shouldAllowUnsupportedBareImports(options),
+    }]],
     sourceType: 'module',
     compact: false,
     babelrc: false,
@@ -286,14 +317,14 @@ function compileCanvasLocal(source) {
  * @param {object} [options] 兼容占位，未使用
  * @returns {Promise<{ runtimeCode: string, importedModules: string }>}
  */
-function compileCanvas(source, options = {}) { // eslint-disable-line no-unused-vars
+function compileCanvas(source, options = {}) {
   return new Promise((resolve, reject) => {
     if (typeof source !== 'string' || source.trim() === '') {
       reject(new Error('canvas 编译源码为空'));
       return;
     }
     try {
-      resolve(compileCanvasLocal(source));
+      resolve(compileCanvasLocal(source, options));
     } catch (compileError) {
       const detail = compileError && compileError.message ? compileError.message : String(compileError);
       reject(new Error(`Code Canvas 本地编译失败: ${detail}`));
@@ -306,5 +337,6 @@ module.exports = {
   compileCanvasLocal,
   extractImportedModules,
   resolveWindowAlias,
+  shouldAllowUnsupportedBareImports,
   MODULE_ALIAS_MAP,
 };

package/lib/app/publish.js

@@ -126,6 +126,28 @@ function parseArgs(argv = process.argv.slice(2)) {
   };
 }
 
+function normalizeSourcePathForHint(sourceFile) {
+  return String(sourceFile || '')
+    .replace(/\\/g, '/')
+    .replace(/^\.\//, '');
+}
+
+function buildMissingSourceHints(sourceFile, cwd = process.cwd()) {
+  const normalized = normalizeSourcePathForHint(sourceFile);
+  const candidates = [];
+
+  if (normalized.startsWith('project/pages/src/')) {
+    candidates.push(normalized.slice('project/'.length));
+  }
+
+  if (normalized.startsWith('pages/src/')) {
+    candidates.push(`project/${normalized}`);
+  }
+
+  return Array.from(new Set(candidates))
+    .filter(candidate => fs.existsSync(path.resolve(cwd, candidate)));
+}
+
 // ── 2. 读取并构建 Schema ────────────────────────────
 
 async function fetchExistingSchemaContent(appType, formUuid, authRef) {
@@ -618,6 +640,10 @@ async function main(argv) {
   let sourcePath = path.resolve(sourceFile);
   if (!fs.existsSync(sourcePath)) {
     error(t('publish.source_not_found', sourcePath));
+    buildMissingSourceHints(sourceFile).forEach((candidate) => {
+      hint(t('publish.source_path_hint', candidate));
+    });
+    process.exit(1);
   }
 
   // 路由：默认 native；.canvas.jsx / .canvas.tsx 源文件自动走 Code Canvas 链路，
@@ -799,6 +825,7 @@ if (require.main === module) {
   module.exports = main;
   module.exports.parseArgs = parseArgs;
   module.exports.normalizePublishArgs = normalizePublishArgs;
+  module.exports.buildMissingSourceHints = buildMissingSourceHints;
   module.exports.findDuplicateSourceMismatches = findDuplicateSourceMismatches;
   module.exports.sendHealthCheckRequest = sendHealthCheckRequest;
   module.exports.normalizeFormType = normalizeFormType;

package/lib/core/agent-capabilities.js

@@ -24,6 +24,247 @@ function compactLogin(login) {
   };
 }
 
+function isTruthyEnv(value) {
+  return ['1', 'true', 'yes', 'on'].includes(String(value || '').trim().toLowerCase());
+}
+
+function hasEnvTokenCredential(env = process.env) {
+  return !!(
+    String(env.OPENYIDA_ACCESS_TOKEN || '').trim() ||
+    String(env.OPENYIDA_REFRESH_TOKEN || '').trim()
+  );
+}
+
+const BUILDER_CORE_COMMAND_IDS = Object.freeze([
+  'agent-capabilities',
+  'commands',
+  'app-list',
+  'list-forms',
+  'get-schema',
+  'create-app',
+  'create-form.create',
+  'create-page',
+  'publish',
+]);
+
+function commandBriefs(manifest, commandIds) {
+  const byId = new Map((manifest.commands || []).map(entry => [entry.id, entry]));
+  return commandIds
+    .map(id => byId.get(id))
+    .filter(Boolean)
+    .map(entry => ({
+      id: entry.id,
+      usage: entry.usage,
+      requires_login: entry.requires_login,
+      output: entry.output,
+      permission_mode: entry.permission && entry.permission.mode,
+      side_effect_kind: entry.side_effect && entry.side_effect.kind,
+    }));
+}
+
+function forbiddenAliasBriefs(manifest) {
+  return (manifest.forbidden_aliases || []).map(entry => ({
+    pattern: entry.pattern,
+    matcher: entry.matcher,
+    suggested_command_id: entry.suggested_command_id,
+    suggested_usage: entry.suggested_usage,
+    alternative_command_ids: entry.alternative_command_ids || [],
+    alternative_usages: entry.alternative_usages || [],
+    message_key: entry.message_key,
+    message_args: entry.message_args || [],
+    message: entry.message,
+  }));
+}
+
+function buildAuthFastPath(login, env = process.env) {
+  const hostInjectedTokenMode = isTruthyEnv(env.YIDA_AUTH_ENABLED);
+  const envTokenPresent = hasEnvTokenCredential(env);
+  const authSource = login.auth_source || (hostInjectedTokenMode || envTokenPresent ? 'env' : 'token_session');
+  const hostTokenEnvDetected = hostInjectedTokenMode || envTokenPresent || authSource === 'env';
+
+  return {
+    mode: login.auth_mode || 'token',
+    source: authSource,
+    can_auto_use: login.can_auto_use === true,
+    host_injected_token_mode: hostInjectedTokenMode,
+    host_token_env_detected: hostTokenEnvDetected,
+    env_token_present: envTokenPresent,
+    interactive_login_allowed: !hostTokenEnvDetected,
+    browser_session_auth_allowed: false,
+    auth_runtime: 'token_oauth_session',
+    cookie_auth_supported: false,
+    cookie_check_required: false,
+    playwright_cookie_check_required: false,
+    qr_login_required: false,
+    prohibited_legacy_checks: [
+      'browser_cookie',
+      'playwright_cookie',
+      'qr_login',
+      'cookie_cache',
+    ],
+    missing_token_action: hostInjectedTokenMode
+      ? 'STOP_AND_REQUEST_HOST_TOKEN'
+      : 'RUN_OPENYIDA_LOGIN_IF_USER_APPROVES',
+  };
+}
+
+function buildBuilderFastPath(login, projectRoot, manifest, env = process.env) {
+  const auth = buildAuthFastPath(login, env);
+  const canTrustSummaryPreflight = auth.can_auto_use === true || auth.host_injected_token_mode === true;
+
+  return {
+    schema_version: 1,
+    preflight: {
+      recommended_command: 'openyida agent-capabilities --summary-json',
+      run_once: true,
+      additional_env_check_default: false,
+      additional_login_check_default: false,
+      trust_summary_json_as_builder_preflight: true,
+      full_capabilities_command: 'openyida agent-capabilities --json',
+      full_capabilities_only_when: 'Need full command_manifest.commands, forbidden_aliases, or detailed environment diagnostics.',
+    },
+    auth,
+    environment_check_simplification: {
+      contract_role: 'machine_readable_fast_path_for_builder_runtime_not_yida_agent_business_logic',
+      minimal_probe_commands: [
+        'which openyida',
+        'openyida agent-capabilities --summary-json',
+      ],
+      can_skip_default_exploration_when_summary_ok: canTrustSummaryPreflight,
+      skip_default_command_patterns: [
+        'openyida --help',
+        'openyida <command> --help',
+        'openyida env --json',
+        'openyida login --check-only --json',
+        'browser login',
+        'qr login',
+        'Playwright cookie inspection',
+        'cookie cache inspection',
+        'openyida app-list',
+      ],
+      skip_help_discovery_default: true,
+      skip_env_noise_default: true,
+      skip_login_check_only_default: canTrustSummaryPreflight,
+      skip_browser_login_default: auth.host_token_env_detected,
+      skip_cookie_or_playwright_checks_default: true,
+      default_app_list_policy: 'skip_when_bound_app_type_unique',
+      stop_when_host_token_missing: auth.host_injected_token_mode && !auth.env_token_present,
+    },
+    command_contract: {
+      command_prefix: manifest.command_prefix,
+      supported_command_count: manifest.commands.length,
+      supported_command_ids: manifest.commands.map(entry => entry.id),
+      canonical_builder_commands: commandBriefs(manifest, BUILDER_CORE_COMMAND_IDS),
+      forbidden_aliases_available_in: 'openyida commands --json',
+      forbidden_alias_count: manifest.forbidden_aliases.length,
+      forbidden_aliases: forbiddenAliasBriefs(manifest),
+      unknown_command_policy: 'deny_with_manifest_suggestion_before_asking_user',
+    },
+    bound_context: {
+      existing_app_type_policy: 'do_not_call_app_list_by_default',
+      skip_app_list_when: [
+        'appType is already provided by the user',
+        'a bound app context is already available',
+      ],
+      call_app_list_only_when: [
+        'name_search',
+        'target_conflict',
+        'failure_diagnosis',
+      ],
+    },
+    resource_context_resolution: {
+      contract_role: 'structured_runtime_hint_not_skill_stage_rewrite',
+      if_bound_app_type_unique: {
+        action: 'reuse_bound_app_type',
+        command: null,
+        skip_command_ids: ['app-list'],
+      },
+      app_name_search: {
+        command_id: 'app-list',
+        usage: 'openyida app-list [--size N]',
+      },
+      app_forms_or_pages_lookup: {
+        command_id: 'list-forms',
+        usage: 'openyida list-forms <appType> [--keyword <text>]',
+      },
+      schema_or_field_lookup: {
+        command_id: 'get-schema',
+        usages: [
+          'openyida get-schema <appType> <formUuid> --summary-json',
+          'openyida get-schema <appType> --all --summary-json --keyword <text> --output-dir .cache/openyida/<task>/schemas',
+        ],
+      },
+      preflight_context: {
+        command_id: 'agent-capabilities',
+        usage: 'openyida agent-capabilities --summary-json',
+      },
+    },
+    paths: {
+      workdir: projectRoot,
+      page_source_cli_path_policy: 'If builder Bash cwd is the project/ directory, pass page source paths as pages/src/<file>.',
+      page_source_examples: [
+        'pages/src/home.canvas.jsx',
+        'pages/src/dashboard.oyd.jsx',
+      ],
+    },
+  };
+}
+
+function compactBuilderFastPath(builderFastPath) {
+  const environment = builderFastPath.environment_check_simplification;
+  const commandContract = builderFastPath.command_contract;
+  const resourceContext = builderFastPath.resource_context_resolution;
+  const paths = builderFastPath.paths;
+
+  return {
+    schema_version: builderFastPath.schema_version,
+    preflight: builderFastPath.preflight,
+    auth: {
+      mode: builderFastPath.auth.mode,
+      source: builderFastPath.auth.source,
+      can_auto_use: builderFastPath.auth.can_auto_use,
+      host_injected_token_mode: builderFastPath.auth.host_injected_token_mode,
+      host_token_env_detected: builderFastPath.auth.host_token_env_detected,
+      env_token_present: builderFastPath.auth.env_token_present,
+      interactive_login_allowed: builderFastPath.auth.interactive_login_allowed,
+      browser_session_auth_allowed: builderFastPath.auth.browser_session_auth_allowed,
+      auth_runtime: builderFastPath.auth.auth_runtime,
+      cookie_auth_supported: builderFastPath.auth.cookie_auth_supported,
+      cookie_check_required: builderFastPath.auth.cookie_check_required,
+      playwright_cookie_check_required: builderFastPath.auth.playwright_cookie_check_required,
+      qr_login_required: builderFastPath.auth.qr_login_required,
+      missing_token_action: builderFastPath.auth.missing_token_action,
+    },
+    environment_check_simplification: {
+      minimal_probe_commands: environment.minimal_probe_commands,
+      can_skip_default_exploration_when_summary_ok: environment.can_skip_default_exploration_when_summary_ok,
+      skip_login_check_only_default: environment.skip_login_check_only_default,
+      skip_browser_login_default: environment.skip_browser_login_default,
+      skip_cookie_or_playwright_checks_default: environment.skip_cookie_or_playwright_checks_default,
+      stop_when_host_token_missing: environment.stop_when_host_token_missing,
+      default_app_list_policy: environment.default_app_list_policy,
+    },
+    command_contract: {
+      command_prefix: commandContract.command_prefix,
+      supported_command_count: commandContract.supported_command_count,
+      canonical_builder_command_ids: commandContract.canonical_builder_commands.map(entry => entry.id),
+      forbidden_aliases_available_in: commandContract.forbidden_aliases_available_in,
+      forbidden_alias_count: commandContract.forbidden_alias_count,
+      unknown_command_policy: commandContract.unknown_command_policy,
+    },
+    bound_context: {
+      existing_app_type_policy: builderFastPath.bound_context.existing_app_type_policy,
+    },
+    resource_context_resolution: {
+      if_bound_app_type_unique: resourceContext.if_bound_app_type_unique,
+      full_contract_in: 'openyida agent-capabilities --json',
+    },
+    paths: {
+      page_source_cli_path_policy: paths.page_source_cli_path_policy,
+    },
+  };
+}
+
 function canonicalize(value) {
   if (Array.isArray(value)) {
     return value.map(canonicalize);
@@ -47,10 +288,16 @@ function buildCommandManifestDigest(manifest) {
     summary: {
       command_count: manifest.summary.command_count,
       group_count: manifest.summary.group_count,
+      forbidden_alias_count: manifest.summary.forbidden_alias_count,
       side_effect_counts: manifest.summary.side_effect_counts,
       permission_mode_counts: manifest.summary.permission_mode_counts,
       core_workflows: manifest.summary.core_workflows,
     },
+    forbidden_aliases: (manifest.forbidden_aliases || []).map(entry => ({
+      pattern: entry.pattern,
+      suggested_command_id: entry.suggested_command_id,
+      suggested_usage: entry.suggested_usage,
+    })),
     commands: manifest.commands.map(entry => ({
       id: entry.id,
       usage: entry.usage,
@@ -73,6 +320,9 @@ function buildAgentCapabilitiesSummary() {
   const manifest = buildCommandManifest({ t, version });
   const projectRoot = envSnapshot.active.projectRoot;
   const loginStatus = getAuthStatus({ projectRoot, includeSecrets: false });
+  const builderFastPath = compactBuilderFastPath(
+    buildBuilderFastPath(loginStatus, projectRoot, manifest)
+  );
 
   return {
     schema_version: 1,
@@ -87,6 +337,7 @@ function buildAgentCapabilitiesSummary() {
     command_manifest_digest_algorithm: 'sha256',
     command_count: manifest.summary.command_count,
     full_capabilities_command: 'openyida agent-capabilities --json',
+    builder_fast_path: builderFastPath,
   };
 }
 
@@ -95,6 +346,7 @@ function buildAgentCapabilities() {
   const manifest = buildCommandManifest({ t, version });
   const projectRoot = envSnapshot.active.projectRoot;
   const loginStatus = redactLogin(getAuthStatus({ projectRoot, includeSecrets: false }));
+  const builderFastPath = buildBuilderFastPath(loginStatus, projectRoot, manifest);
 
   return {
     schema_version: 1,
@@ -116,6 +368,7 @@ function buildAgentCapabilities() {
       openyida_task_cache_dir: path.join(projectRoot, '.cache', 'openyida'),
       default_full_app_workflow: manifest.summary.core_workflows.full_app_fast_build,
     },
+    builder_fast_path: builderFastPath,
     skills: {
       index_file: 'skills-index.json',
       entry: 'openyida',
@@ -134,6 +387,8 @@ function buildAgentCapabilities() {
       ask_command_ids: manifest.summary.ask_command_ids,
       deny_command_ids: manifest.summary.deny_command_ids,
       core_workflows: manifest.summary.core_workflows,
+      forbidden_alias_count: manifest.summary.forbidden_alias_count,
+      forbidden_alias_patterns: manifest.summary.forbidden_alias_patterns,
     },
     sideEffects: {
       read_only_preflight: [
@@ -153,6 +408,8 @@ function buildAgentCapabilities() {
       groups: manifest.groups,
       side_effect_schema: manifest.side_effect_schema,
       permission_schema: manifest.permission_schema,
+      forbidden_alias_schema: manifest.forbidden_alias_schema,
+      forbidden_aliases: manifest.forbidden_aliases,
       summary: manifest.summary,
       commands: manifest.commands,
     },
@@ -173,6 +430,7 @@ async function run(args = []) {
 module.exports = {
   buildAgentCapabilities,
   buildAgentCapabilitiesSummary,
+  compactBuilderFastPath,
   buildCommandManifestDigest,
   run,
 };

package/lib/core/command-manifest.js

@@ -77,6 +77,26 @@ const PERMISSION_SCHEMA = Object.freeze({
   },
 });
 
+const FORBIDDEN_ALIAS_SCHEMA = Object.freeze({
+  version: 1,
+  fields: {
+    pattern: 'Human-readable forbidden argv pattern. Match against arguments after openyida/yida.',
+    matcher: 'Structured matcher for agents that need deterministic deny decisions.',
+    suggested_command_id: 'Canonical command id to run instead.',
+    suggested_usage: 'Concrete canonical OpenYida usage to show or execute after parameter correction.',
+    alternative_command_ids: 'Optional extra command ids when the alias is ambiguous.',
+    alternative_usages: 'Optional concrete usages for alternative command ids.',
+    message_key: 'i18n key for the explanation suitable for a CLI hint or agent denial reason.',
+    message_args: 'Arguments for message_key interpolation.',
+    message: 'Localized explanation generated from message_key when a translator is available.',
+  },
+  matcher_types: {
+    argv_prefix: 'Deny when the invocation argv begins with matcher.tokens.',
+    command_has_option: 'Deny when matcher.command is the command root and matcher.option appears anywhere in argv.',
+  },
+  agent_policy: 'Deny forbidden aliases before asking the user; return suggested_command_id and suggested_usage as the repair hint.',
+});
+
 function sideEffect(kind, overrides = {}) {
   if (!SIDE_EFFECT_BASES[kind]) {
     throw new Error('Unknown side effect kind: ' + kind);
@@ -142,6 +162,46 @@ function clonePermissionSchema() {
   return JSON.parse(JSON.stringify(PERMISSION_SCHEMA));
 }
 
+function cloneForbiddenAliasSchema() {
+  return JSON.parse(JSON.stringify(FORBIDDEN_ALIAS_SCHEMA));
+}
+
+function cloneMatcher(matcher) {
+  if (!matcher || typeof matcher !== 'object') {
+    return matcher;
+  }
+  const cloned = { ...matcher };
+  if (Array.isArray(matcher.tokens)) {
+    cloned.tokens = [...matcher.tokens];
+  }
+  return cloned;
+}
+
+function cloneForbiddenAlias(entry) {
+  const cloned = {
+    ...entry,
+    matcher: cloneMatcher(entry.matcher),
+  };
+  if (Array.isArray(entry.alternative_command_ids)) {
+    cloned.alternative_command_ids = [...entry.alternative_command_ids];
+  }
+  if (Array.isArray(entry.alternative_usages)) {
+    cloned.alternative_usages = [...entry.alternative_usages];
+  }
+  if (Array.isArray(entry.message_args)) {
+    cloned.message_args = [...entry.message_args];
+  }
+  return cloned;
+}
+
+function localizeForbiddenAlias(entry, translate) {
+  const localized = cloneForbiddenAlias(entry);
+  if (localized.message_key) {
+    localized.message = translate(localized.message_key, ...(localized.message_args || []));
+  }
+  return localized;
+}
+
 function normalizePermission(metadata, sideEffectMetadata) {
   const normalized = { ...metadata };
   if (sideEffectMetadata && sideEffectMetadata.kind === 'mixed') {
@@ -185,6 +245,114 @@ function listCommandPermissionIds() {
   return [...COMMAND_PERMISSIONS.keys()].sort();
 }
 
+function normalizeInvocationArgv(argv = []) {
+  const normalized = (Array.isArray(argv) ? argv : [])
+    .map(value => String(value || '').trim())
+    .filter(Boolean);
+  if (normalized[0] === 'openyida' || normalized[0] === 'yida') {
+    return normalized.slice(1);
+  }
+  return normalized;
+}
+
+function matcherMatchesArgv(argv, matcher) {
+  const normalized = normalizeInvocationArgv(argv);
+  if (!matcher || typeof matcher !== 'object' || normalized.length === 0) {
+    return false;
+  }
+
+  if (matcher.type === 'argv_prefix') {
+    const tokens = Array.isArray(matcher.tokens) ? matcher.tokens : [];
+    return tokens.length > 0 && tokens.every((token, index) => normalized[index] === token);
+  }
+
+  if (matcher.type === 'command_has_option') {
+    return normalized[0] === matcher.command && normalized.includes(matcher.option);
+  }
+
+  return false;
+}
+
+function findForbiddenAliasSuggestion(argv = []) {
+  const match = FORBIDDEN_ALIASES.find(entry => matcherMatchesArgv(argv, entry.matcher));
+  return match ? cloneForbiddenAlias(match) : null;
+}
+
+function levenshteinDistance(left, right) {
+  const a = String(left || '');
+  const b = String(right || '');
+  const dp = Array.from({ length: a.length + 1 }, () => Array(b.length + 1).fill(0));
+  for (let i = 0; i <= a.length; i++) {
+    dp[i][0] = i;
+  }
+  for (let j = 0; j <= b.length; j++) {
+    dp[0][j] = j;
+  }
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      dp[i][j] = Math.min(
+        dp[i - 1][j] + 1,
+        dp[i][j - 1] + 1,
+        dp[i - 1][j - 1] + cost
+      );
+    }
+  }
+  return dp[a.length][b.length];
+}
+
+function findNearestCommandSuggestion(argv = []) {
+  const normalized = normalizeInvocationArgv(argv);
+  const root = normalized[0];
+  if (!root) {
+    return null;
+  }
+
+  const candidates = new Map();
+  for (const entry of flattenCommandManifest()) {
+    if (!entry.hidden && entry.path && entry.path[0] && !candidates.has(entry.path[0])) {
+      candidates.set(entry.path[0], entry);
+    }
+    for (const alias of entry.aliases || []) {
+      const aliasRoot = String(alias || '').trim().split(/\s+/)[0];
+      if (aliasRoot && !candidates.has(aliasRoot)) {
+        candidates.set(aliasRoot, entry);
+      }
+    }
+  }
+
+  if (candidates.has(root)) {
+    return null;
+  }
+
+  let best = null;
+  for (const [candidate, entry] of candidates) {
+    const distance = levenshteinDistance(root, candidate);
+    if (!best || distance < best.distance) {
+      best = { candidate, entry, distance };
+    }
+  }
+
+  const threshold = Math.max(2, Math.floor(root.length / 3));
+  if (!best || best.distance > threshold) {
+    return null;
+  }
+
+  return {
+    id: `nearest.${root}`,
+    pattern: root,
+    matcher: { type: 'argv_prefix', tokens: [root] },
+    suggested_command_id: best.entry.id,
+    suggested_usage: `openyida ${best.entry.usage}`,
+    message_key: 'cli.nearest_command_suggestion',
+    message_args: [root, best.candidate],
+  };
+}
+
+function findCommandSuggestion(argv = []) {
+  return findForbiddenAliasSuggestion(argv) || findNearestCommandSuggestion(argv);
+}
+
 const COMMAND_SIDE_EFFECTS = new Map([
   ...sideEffectEntries([
     'agent-capabilities',
@@ -723,6 +891,68 @@ const COMMAND_PERMISSIONS = new Map([
   })),
 ]);
 
+const FORBIDDEN_ALIASES = Object.freeze([
+  Object.freeze({
+    id: 'forbidden-alias.list-apps',
+    pattern: 'list-apps',
+    matcher: { type: 'argv_prefix', tokens: ['list-apps'] },
+    suggested_command_id: 'app-list',
+    suggested_usage: 'openyida app-list [--size N]',
+    message_key: 'cli.forbidden_alias_list_apps',
+    message_args: ['list-apps', 'app-list'],
+  }),
+  Object.freeze({
+    id: 'forbidden-alias.get-app',
+    pattern: 'get-app',
+    matcher: { type: 'argv_prefix', tokens: ['get-app'] },
+    suggested_command_id: 'app-list',
+    suggested_usage: 'openyida app-list [--size N]',
+    alternative_command_ids: ['get-schema', 'agent-capabilities'],
+    alternative_usages: [
+      'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json]',
+      'openyida agent-capabilities --summary-json',
+    ],
+    message_key: 'cli.forbidden_alias_get_app',
+    message_args: ['get-app', 'app-list', 'get-schema', 'agent-capabilities'],
+  }),
+  Object.freeze({
+    id: 'forbidden-alias.create-app-json',
+    pattern: 'create-app --json',
+    matcher: { type: 'command_has_option', command: 'create-app', option: '--json' },
+    suggested_command_id: 'create-app',
+    suggested_usage: 'openyida create-app "<name>"|--name <name> [options] [--locale zh_CN|en_US|ja_JP] [--open|--no-open]',
+    message_key: 'cli.forbidden_alias_create_app_json',
+    message_args: ['create-app --json', 'create-app'],
+  }),
+  Object.freeze({
+    id: 'forbidden-alias.create-page-app-type-option',
+    pattern: 'create-page --app-type',
+    matcher: { type: 'command_has_option', command: 'create-page', option: '--app-type' },
+    suggested_command_id: 'create-page',
+    suggested_usage: 'openyida create-page <appType> "<name>" [--mode dashboard] [--locale zh_CN|en_US|ja_JP] [--open|--no-open]',
+    message_key: 'cli.forbidden_alias_create_page_app_type_option',
+    message_args: ['create-page', '--app-type'],
+  }),
+  Object.freeze({
+    id: 'forbidden-alias.get-schema-app-type-option',
+    pattern: 'get-schema --app-type',
+    matcher: { type: 'command_has_option', command: 'get-schema', option: '--app-type' },
+    suggested_command_id: 'get-schema',
+    suggested_usage: 'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json]',
+    message_key: 'cli.forbidden_alias_get_schema_app_type_option',
+    message_args: ['get-schema', '--app-type'],
+  }),
+  Object.freeze({
+    id: 'forbidden-alias.get-schema-form-uuid-option',
+    pattern: 'get-schema --form-uuid',
+    matcher: { type: 'command_has_option', command: 'get-schema', option: '--form-uuid' },
+    suggested_command_id: 'get-schema',
+    suggested_usage: 'openyida get-schema <appType> <formUuid|--all> [--summary-json|--field-map-json]',
+    message_key: 'cli.forbidden_alias_get_schema_form_uuid_option',
+    message_args: ['get-schema', '--form-uuid'],
+  }),
+]);
+
 function command(id, path, usage, descriptionKey, options = {}) {
   const commandSideEffect = COMMAND_SIDE_EFFECTS.get(id);
   if (!commandSideEffect) {
@@ -1069,6 +1299,8 @@ function summarizeLocalizedCommands(commands) {
   return {
     command_count: commands.length,
     group_count: COMMAND_GROUPS.length,
+    forbidden_alias_count: FORBIDDEN_ALIASES.length,
+    forbidden_alias_patterns: FORBIDDEN_ALIASES.map(entry => entry.pattern),
     side_effect_counts: sideEffectCounts,
     ids_by_side_effect: idsBySideEffect,
     read_only_command_ids: readOnlyCommandIds,
@@ -1138,6 +1370,8 @@ function buildCommandManifest(options = {}) {
     })),
     side_effect_schema: cloneSideEffectSchema(),
     permission_schema: clonePermissionSchema(),
+    forbidden_alias_schema: cloneForbiddenAliasSchema(),
+    forbidden_aliases: FORBIDDEN_ALIASES.map(entry => localizeForbiddenAlias(entry, translate)),
     summary: summarizeLocalizedCommands(localizedCommands),
     commands: localizedCommands,
   };
@@ -1146,6 +1380,8 @@ function buildCommandManifest(options = {}) {
 module.exports = {
   COMMAND_GROUPS,
   buildCommandManifest,
+  findCommandSuggestion,
+  findForbiddenAliasSuggestion,
   flattenCommandManifest,
   listCommandPermissionIds,
   listCommandSideEffectIds,

package/lib/core/locales/en.js

@@ -239,6 +239,14 @@ Examples:
   openyida export-conversation --list             List available conversations
 `,
     unknown_command: 'Unknown command: {0}',
+    command_suggestion: 'Suggested command: {0}',
+    forbidden_alias_list_apps: '`{0}` is not an OpenYida command; use `{1}` for application discovery.',
+    forbidden_alias_get_app: '`{0}` is ambiguous; use `{1}` for app name search, `{2}` for form/schema lookup, or `{3}` for bound context preflight.',
+    forbidden_alias_create_app_json: '`{0}` is not a separate command contract; use canonical `{1}` output.',
+    forbidden_alias_create_page_app_type_option: '`{0}` takes appType as the first positional argument, not `{1}`.',
+    forbidden_alias_get_schema_app_type_option: '`{0}` takes appType as the first positional argument, not `{1}`.',
+    forbidden_alias_get_schema_form_uuid_option: '`{0}` takes formUuid as the second positional argument, not `{1}`.',
+    nearest_command_suggestion: 'Unknown OpenYida command root "{0}". Did you mean "{1}"?',
     run_help: 'Run openyida --help for usage',
     integration_help: 'Usage: openyida integration <create|list|enable|disable|check|diagnose> ...',
     integration_unknown: 'Unknown integration subcommand: {0}',
@@ -1201,6 +1209,7 @@ Examples:
     exception: '\n❌ Publish error: {0}',
     error: '\n❌ Publish error: {0}',
     source_not_found: '❌ Source file not found: {0}',
+    source_path_hint: '💡 Try this source file path: {0}',
     usage: 'Usage: openyida publish <sourceFile> <appType> <formUuid> [--health-check] [--canvas]',
     example: 'Example: openyida publish pages/src/xxx.js APP_XXX FORM-XXX --health-check',
   },

package/lib/core/locales/zh.js

@@ -240,6 +240,14 @@ openyida - 宜搭命令行工具
   openyida export-conversation --list             列出可用对话
 `,
     unknown_command: '未知命令: {0}',
+    command_suggestion: '建议命令: {0}',
+    forbidden_alias_list_apps: '`{0}` 不是 OpenYida 命令；请使用 `{1}` 查询应用。',
+    forbidden_alias_get_app: '`{0}` 含义不明确；按应用名称搜索请用 `{1}`，查询表单/字段结构请用 `{2}`，读取绑定上下文请用 `{3}`。',
+    forbidden_alias_create_app_json: '`{0}` 不是独立命令契约；请使用规范的 `{1}` 输出。',
+    forbidden_alias_create_page_app_type_option: '`{0}` 使用第一个位置参数传入 appType，不使用 `{1}`。',
+    forbidden_alias_get_schema_app_type_option: '`{0}` 使用第一个位置参数传入 appType，不使用 `{1}`。',
+    forbidden_alias_get_schema_form_uuid_option: '`{0}` 使用第二个位置参数传入 formUuid，不使用 `{1}`。',
+    nearest_command_suggestion: '未知 OpenYida 命令根「{0}」。你是不是想用「{1}」？',
     run_help: '运行 openyida --help 查看帮助',
     integration_help: '用法: openyida integration <create|list|enable|disable|check|diagnose> ...',
     integration_unknown: '未知的 integration 子命令: {0}',
@@ -1195,6 +1203,7 @@ openyida - 宜搭命令行工具
     exception: '\n❌ 发布异常: {0}',
     error: '\n❌ 发布异常: {0}',
     source_not_found: '❌ 源文件不存在：{0}',
+    source_path_hint: '💡 可尝试使用源文件路径：{0}',
     usage: '用法: openyida publish <源文件路径> <appType> <formUuid> [--health-check] [--canvas]',
     example: '示例：openyida publish pages/src/xxx.js APP_XXX FORM-XXX --health-check',
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openyida",
-  "version": "2026.7.21",
+  "version": "2026.7.22",
   "description": "OpenYida CLI - 宜搭低代码 AI 开发工具（安装即用，零配置）",
   "bin": {
     "openyida": "bin/yida.js",

package/scripts/validate-command-manifest.js

@@ -260,6 +260,77 @@ function validatePermissions(commands) {
   }
 }
 
+function validateForbiddenAliases() {
+  const manifest = require('../lib/core/command-manifest').buildCommandManifest();
+  const commandIds = new Set(flattenCommandManifest().map(entry => entry.id));
+  const allowedMatcherTypes = new Set([
+    'argv_prefix',
+    'command_has_option',
+  ]);
+  const seenPatterns = new Set();
+
+  if (!manifest.forbidden_alias_schema || manifest.forbidden_alias_schema.version !== 1) {
+    errors.push('Command manifest is missing forbidden_alias_schema.version 1');
+  }
+  if (!Array.isArray(manifest.forbidden_aliases)) {
+    errors.push('Command manifest forbidden_aliases must be an array');
+    return;
+  }
+
+  for (const entry of manifest.forbidden_aliases) {
+    if (!entry || typeof entry !== 'object') {
+      errors.push('Forbidden alias entries must be objects');
+      continue;
+    }
+    if (typeof entry.id !== 'string' || !entry.id.trim()) {
+      errors.push('Forbidden alias entry is missing id');
+    }
+    if (typeof entry.pattern !== 'string' || !entry.pattern.trim()) {
+      errors.push(`Forbidden alias "${entry.id || '(missing id)'}" is missing pattern`);
+    } else if (seenPatterns.has(entry.pattern)) {
+      errors.push(`Duplicate forbidden alias pattern: ${entry.pattern}`);
+    } else {
+      seenPatterns.add(entry.pattern);
+    }
+    if (!entry.matcher || typeof entry.matcher !== 'object' || Array.isArray(entry.matcher)) {
+      errors.push(`Forbidden alias "${entry.id}" matcher must be an object`);
+    } else if (!allowedMatcherTypes.has(entry.matcher.type)) {
+      errors.push(`Forbidden alias "${entry.id}" has invalid matcher type "${entry.matcher.type}"`);
+    } else if (entry.matcher.type === 'argv_prefix') {
+      if (!Array.isArray(entry.matcher.tokens) || entry.matcher.tokens.length === 0) {
+        errors.push(`Forbidden alias "${entry.id}" argv_prefix matcher.tokens must be a non-empty array`);
+      }
+    } else if (entry.matcher.type === 'command_has_option') {
+      if (typeof entry.matcher.command !== 'string' || !entry.matcher.command.trim()) {
+        errors.push(`Forbidden alias "${entry.id}" command_has_option matcher.command must be a non-empty string`);
+      }
+      if (typeof entry.matcher.option !== 'string' || !entry.matcher.option.startsWith('--')) {
+        errors.push(`Forbidden alias "${entry.id}" command_has_option matcher.option must be a --option string`);
+      }
+    }
+    if (!commandIds.has(entry.suggested_command_id)) {
+      errors.push(`Forbidden alias "${entry.id}" references unknown suggested_command_id "${entry.suggested_command_id}"`);
+    }
+    if (typeof entry.suggested_usage !== 'string' || !entry.suggested_usage.startsWith('openyida ')) {
+      errors.push(`Forbidden alias "${entry.id}" suggested_usage must start with "openyida "`);
+    }
+    if (typeof entry.message_key !== 'string' || !entry.message_key.trim()) {
+      errors.push(`Forbidden alias "${entry.id}" message_key must be a non-empty string`);
+    }
+    if (entry.message_args !== undefined && !Array.isArray(entry.message_args)) {
+      errors.push(`Forbidden alias "${entry.id}" message_args must be an array when present`);
+    }
+    if (entry.message !== undefined && (typeof entry.message !== 'string' || !entry.message.trim())) {
+      errors.push(`Forbidden alias "${entry.id}" message must be a non-empty string when present`);
+    }
+    for (const commandId of entry.alternative_command_ids || []) {
+      if (!commandIds.has(commandId)) {
+        errors.push(`Forbidden alias "${entry.id}" references unknown alternative_command_id "${commandId}"`);
+      }
+    }
+  }
+}
+
 function collectPatternCovers(patterns) {
   if (!Array.isArray(patterns)) {
     return [];
@@ -316,6 +387,7 @@ function run() {
   validateReadmeCoverage(commands);
   validateSideEffects(commands);
   validatePermissions(commands);
+  validateForbiddenAliases();
 
   if (errors.length > 0) {
     console.error('Command manifest validation failed:');

package/yida-skills/SKILL.md

@@ -8,7 +8,7 @@ description: >
 
 # 宜搭 AI 应用开发指南
 
-通过有 AI Coding 能力的智能体（悟空/Claude/Open Code 等）+ 宜搭低代码平台，实现一句话搭建或修改完整应用。所有操作通过 **`openyida`** CLI 统一执行。IF 未设置 `YIDA_AUTH_ENABLED=true`：默认 OAuth token，token 不可用才执行 `openyida login`。IF `YIDA_AUTH_ENABLED=true`：进入宿主注入 token 模式，仅使用 `OPENYIDA_ACCESS_TOKEN` / `OPENYIDA_REFRESH_TOKEN` 等 token env；缺 token 必须 STOP 回宿主，禁止触发 OAuth，禁止读 `.cache/cookies*.json`。
+通过有 AI Coding 能力的智能体（悟空/Claude/Open Code 等）+ 宜搭低代码平台，实现一句话搭建或修改完整应用。所有操作通过 **`openyida`** CLI 统一执行。登录态分流必须以 `openyida agent-capabilities --summary-json` 或 `openyida login --check-only --json` 返回的 auth snapshot 为准；只有 snapshot 明确返回 `login.auth_source=env` 或 `failure_reason=env_token_missing` 时，才按宿主注入 token 模式处理。其他未登录 token 场景走默认 OAuth token 登录，不要根据 agent 名称、宿主类型或手写环境判断自行分流；禁止读取 `.cache/cookies*.json`。
 
 ---
 
@@ -38,8 +38,9 @@ description: >
 |---------|------|
 | 命令跑不了（`command not found`） | openyida 未安装 → `npm install -g openyida` |
 | Node/npm 版本不达标 | 先升级 Node（≥16）再装/升级 openyida |
-| `login.auth_mode=token` 且未登录，且未开启 `YIDA_AUTH_ENABLED` | `openyida login`（指定入口带 URL 或 flag） |
-| `login.auth_mode=token` 且 `auth_source=env` / `failure_reason=env_token_missing` | STOP；宿主必须注入 `OPENYIDA_ACCESS_TOKEN` 或 `OPENYIDA_REFRESH_TOKEN`；禁止触发 OAuth；禁止读 `.cache/cookies*.json` |
+| `login.auth_mode=token` 且 `status=ok` / `can_auto_use=true` | 继续执行业务命令 |
+| snapshot 返回 `login.auth_source=env` / `failure_reason=env_token_missing` | STOP；宿主必须注入 `OPENYIDA_ACCESS_TOKEN` 或 `OPENYIDA_REFRESH_TOKEN`；禁止触发 OAuth；禁止读 `.cache/cookies*.json` |
+| `login.auth_mode=token` 且未登录，且 snapshot 未返回 env 注入模式 | `openyida login`（指定入口带 URL 或 flag），完成后再 `openyida login --check-only --json` 验证 |
 | `workdir_exists` / `active.projectRootExists` 为 false | 无工作目录 → `openyida copy` 初始化 |
 
 **👉 环境异常、登录失败、悟空降级、OAuth token 登录异常等特殊分支 → [references/setup-and-env.md](references/setup-and-env.md)。正常 `agent-capabilities` 通过时不要默认读取该 reference。**
@@ -221,10 +222,11 @@ schema-managed create/update 必须等待用户对当前 `planId` 显式批准
 ### 致命规则（FATAL，违反即失败/报错）
 
 1. **技能加载唯一入口**：执行任何子技能前，支持 `use_skill` 的宿主必须调用 `use_skill("<技能名>", "<本阶段目的>")` 加载对应技能；不要用 `Read` / `read_file` / `cat` 读取 SKILL.md 路径，不凭记忆猜参数格式。
-2. **corpId 一致性检查**：创建或发布页面前对比 prd/resource context 与当前 auth context（默认 token session；`YIDA_AUTH_ENABLED=true` 时为宿主注入 token）的 corpId，不一致必须询问用户（重新登录到目标组织，或确认在当前组织继续操作已解析资源/缺失资源）。
+2. **corpId 一致性检查**：创建或发布页面前对比 prd/resource context 与当前 auth snapshot（本地 OAuth token session 或 snapshot 明确返回的宿主注入 env token）中的 corpId，不一致必须询问用户（重新登录到目标组织，或确认在当前组织继续操作已解析资源/缺失资源）。
 3. **发布前本地校验**：普通自定义页面 `.oyd.jsx` / `.jsx` 发布前跑 `openyida check-page` + `openyida compile`；Code Canvas `.canvas.jsx` 不跑这两个普通自定义页面检查，改由 `openyida publish` 的 Canvas 编译阶段或 `compileCanvasLocal` 快检校验；JSON 配置写盘后先解析校验，再调用平台命令。
 4. **页面源码修改必须发布闭环**：只要本轮 Write/Edit/Create 了页面源码 `project/pages/src/*.{canvas.jsx,canvas.tsx,oyd.jsx,jsx,tsx}`（含完整搭建、补齐、已有页面 update path、单点优化），final 前必须看到成功的 `openyida publish <source> <appType> <displayPageFormUuid>` 命令结果；本地文件编辑、diff、本地校验或编译只证明源码可发布，不等于远端页面已更新。若没有 publish 成功证据，final 只能说“源码已修改，尚未发布”，禁止说“页面已更新 / 已重新发布 / 已上线”。
 5. **命令输入文件禁止 shell 写入**：当 OpenYida 命令需要 JSON/YAML/CSV/config/script 文件参数时，先使用当前 agent 运行时提供的结构化文件写入工具（如 create_file / Write / file edit tool）创建文件，再把路径传给命令；禁止用 shell heredoc、`cat`/`echo`/`printf`/`tee` 加输出重定向，或把命令 stdout 重定向成业务文件。
+6. **读文件少用 Bash 噪声**：读取或定位 workspace 文件优先用宿主的 Read / Glob / Grep；OpenYida CLI 已返回成功 JSON、URL 或 `formUuid/appType` 时，不要再用 Bash `cat`/`ls` 做无意义复核。
 
 ### 重要规则（IMPORTANT，影响质量/性能/可维护性）
 

package/yida-skills/references/setup-and-env.md

@@ -15,8 +15,10 @@ openyida login --check-only --json
 
 ## Auth Mode
 
-- IF `login.auth_mode=token`: OAuth token mode.
-- IF `YIDA_AUTH_ENABLED=true`: host-injected token mode; the host must provide token env such as `OPENYIDA_ACCESS_TOKEN` or `OPENYIDA_REFRESH_TOKEN`.
+- Do not infer auth mode from agent name, host product, workspace path, or a guessed environment variable.
+- First use `openyida agent-capabilities --summary-json`; fallback to `openyida login --check-only --json` only when the compact snapshot is unavailable or insufficient.
+- If the snapshot reports `login.auth_source=env` or `failure_reason=env_token_missing`, treat it as host-injected token mode; the host must provide token env such as `OPENYIDA_ACCESS_TOKEN` or `OPENYIDA_REFRESH_TOKEN`.
+- Otherwise, `login.auth_mode=token` uses the default OAuth token session flow.
 - NEVER infer auth from `.cache/cookies*.json`.
 
 ## Decision Table
@@ -26,13 +28,13 @@ openyida login --check-only --json
 | command not found | install/update `openyida`; do not create resources |
 | `workdir_exists=false` or `active.projectRootExists=false` | run `openyida copy`; do not create resources before workspace exists |
 | `auth_mode=token`, `status=ok` or `can_auto_use=true` | continue |
-| `auth_mode=token`, `failure_reason=env_token_missing` | STOP; host must inject `OPENYIDA_ACCESS_TOKEN` or `OPENYIDA_REFRESH_TOKEN`; do not run OAuth |
-| `auth_mode=token`, not logged in, `YIDA_AUTH_ENABLED` is not true | run `openyida login`; verify with `openyida login --check-only --json` |
-| `auth_mode=token`, access token expired | run `openyida auth refresh`; if still failed and `YIDA_AUTH_ENABLED` is not true, run `openyida login` |
+| snapshot reports `auth_source=env` / `failure_reason=env_token_missing` | Treat as host-injected token mode; if token is missing, STOP and ask host to inject `OPENYIDA_ACCESS_TOKEN` or `OPENYIDA_REFRESH_TOKEN`; do not run OAuth |
+| `auth_mode=token`, not logged in, and snapshot does not report env injection | run `openyida login`; verify with `openyida login --check-only --json` |
+| `auth_mode=token`, access token expired | run `openyida auth refresh`; if still failed and snapshot does not report env injection, run `openyida login` |
 
 ## Token Mode Commands
 
-Use OAuth login only when `YIDA_AUTH_ENABLED` is not true.
+Use OAuth login only when the auth snapshot does not report env injection.
 
 ```bash
 openyida login
@@ -54,7 +56,7 @@ Overseas / international / global / Japan / Global YiDA => add `--intl` or equiv
 
 ## Host-Injected Token Mode Commands
 
-Use only when `YIDA_AUTH_ENABLED=true`.
+Use only after the auth snapshot reports `auth_source=env` or `failure_reason=env_token_missing`.
 
 ```bash
 openyida agent-capabilities --summary-json
@@ -75,11 +77,11 @@ Allowed result:
 }
 ```
 
-If the host did not inject token env, failure result includes `failure_reason=env_token_missing`; stop the task and go back to the host. Do not launch OAuth from this mode.
+If the host did not inject token env, the snapshot includes `failure_reason=env_token_missing`; stop the task and go back to the host. Do not launch OAuth from this mode.
 
 ## NEVER
 
-- Never run `openyida login` in host-injected token mode.
+- Never run `openyida login` after the snapshot reports host-injected token mode.
 - Never read `.cache/cookies*.json` as yida-agent auth.
 - Never ask the user to export browser Cookie.
 - Never print Cookie, CSRF, `access_token`, or `refresh_token`.
@@ -87,5 +89,5 @@ If the host did not inject token env, failure result includes `failure_reason=en
 ## Wukong / Codex
 
 - Same auth mode rules as above.
-- Do not special-case Wukong or Codex into OAuth login when `YIDA_AUTH_ENABLED=true`.
+- Do not special-case Wukong, Codex, yida-agent, or any host identity into an auth branch; follow the OpenYida auth snapshot.
 - Do not create app/page/form/publish until auth snapshot is usable.

package/yida-skills/skills/yida-app/SKILL.md

@@ -30,6 +30,14 @@ description: 宜搭完整应用开发编排技能。对普通 OpenYida 应用做
 - 已有流程表单或 `processCode` 时，流程诉求走 `yida-process-rule`；只有没有表单/流程且用户要新建审批表单时才进入 `yida-create-process`。
 - 多个同优先级候选、当前轮显式资源冲突或目标不明时才问用户；不要因为 cache 和历史里同时存在资源就默认打断。
 
+### 阶段 0 命令选择（不要猜命令）
+
+- 已有显式 `appType`、应用 URL 或 agent bound `appType` 且能唯一解析时，直接复用该 app；不要调用 `app-list` 做存在性确认。
+- 只有用户只给应用名称、存在多个候选、resource context 冲突，或需要诊断目标 app 访问失败时，才运行 `openyida app-list [--size N]`。
+- 已知 `appType` 后，查询该应用下表单/页面用 `openyida list-forms <appType> [--keyword <text>]`；选择页面发布目标时只用 `formType=display`。
+- 查询表单/页面 Schema、字段 ID 或批量字段摘要用 `openyida get-schema <appType> <formUuid|--all> ...`。
+- 阶段 0 禁止编造 `list-apps` / `get-app`；也不要把 `--app-type` / `--form-uuid` 当成 `list-forms` 或 `get-schema` 的参数。按目的在 `app-list`、`list-forms`、`get-schema` 三者中选择。
+
 该阶段只决定普通 OpenYida resource context；schema-managed 路径仍以 schema CLI 的 validate/plan/apply 结果为准。schema-managed create/update 必须停在当前 `planId`，等待用户显式批准后才可执行 `apply`；`nextAction`、错误恢复或本技能判断都不能授予 `mixed/write`。Phase 1 中 report、automation、page config、delete、pull 不从 Manifest fallback 到本技能的 legacy workflow。
 
 ## 阶段 1：resolve app name / rename placeholder app
@@ -59,6 +67,11 @@ description: 宜搭完整应用开发编排技能。对普通 OpenYida 应用做
 
 遵循根入口的只读预检结果。若当前会话还没做预检，先按根入口执行一次只读校验；只有登录态可用后，才执行会创建、修改或发布宜搭资源的命令。不要在每个阶段重复跑 env/help/login 探测。
 
+## 路径与文件读取口径
+
+- 页面源码路径按当前 Bash cwd 选择：从仓库根执行时用 `project/pages/src/...`；如果 cwd 已是 `<workspace>/project`，用 `pages/src/...`，不要传 `project/pages/src/...` 导致 `project/project`。
+- 读取 PRD、字段 JSON、页面源码或 schema 文件时优先用宿主 Read / Glob / Grep；OpenYida CLI 成功输出已经是操作证据，不要再 Bash `cat`/`ls` 复核。
+
 ## 标准执行流
 
 ```text

package/yida-skills/skills/yida-canvas-custom-page/SKILL.md

@@ -22,6 +22,7 @@ Code Canvas 是宜搭的代码画布自定义页面链路：以 `YidaCodeCanvas`
 ## 运行时事实
 
 - Canvas 源码写成 `.canvas.jsx` / `.canvas.tsx`，`openyida publish` 会自动走 Canvas 链路。
+- 页面源码路径按 Bash cwd 选择：从仓库根执行命令时用 `project/pages/src/...`；如果 cwd 已是 `<workspace>/project`，用 `pages/src/...`，不要写成 `project/pages/src/...`。
 - `runtimeCode` 在宿主页真实 `window` 中执行，入口必须返回 `YidaComp` / `YidaComp.default` / 组件函数。
 - Canvas 组件没有普通页面实例上下文；数据读写通过 fetch、开放 API、连接器代理或显式 props 数据桥完成。
 - 第三方依赖走白名单；React、antd、ahooks、d3、recharts、Radix、framer-motion 等可按规则 import。
@@ -154,6 +155,8 @@ npx jest tests/canvas-compile.test.js tests/generate-page.test.js --runInBand
 
 ## 开发流程
 
+下面命令以仓库根为视角；如果当前 cwd 已经是 `<workspace>/project`，把 `project/pages/src/...` 改成 `pages/src/...`。读取生成文件、Schema 或校验产物时优先用宿主 Read / Glob / Grep，不要在 CLI 成功后 Bash `cat`/`ls` 复核。
+
 ```bash
 # 1. 只读检查环境和登录态；真实创建资源前必须通过
 openyida env --json

package/yida-skills/skills/yida-canvas-custom-page/references/dependencies-and-cdn.md

@@ -21,7 +21,11 @@
 | framer-motion | `FramerMotion` | `${cdn}/.../framerMotion.js` |
 | yida-plugin-markdown | `YidaMarkdown` | moduleFederation 0.0.4 |
 
-新增依赖必须同时满足：① 编译能把 import 抽进 `importedModules` 并映射到 windowAlias（见 `canvas-compile.js` 的 `MODULE_ALIAS_MAP`）；② 上表或平台运行时能把依赖加载到 window；③ `runtimeCode` 引用的变量名与 windowAlias 一致；④ CSS 资源可加载，否则组件可能渲染但样式/弹层异常。白名单外的包（yida-utils、`@ali/deep`、原生字段组件等）不能 `import`。
+新增依赖必须同时满足：① 编译能把 import 抽进 `importedModules` 并映射到 windowAlias（见 `canvas-compile.js` 的 `MODULE_ALIAS_MAP`）；② 上表或平台运行时能把依赖加载到 window；③ `runtimeCode` 引用的变量名与 windowAlias 一致；④ CSS 资源可加载，否则组件可能渲染但样式/弹层异常。白名单外的包（yida-utils、`@ali/deep`、原生字段组件等）不能 `import`；带绑定的非白名单裸包 import 会在本地编译阶段硬失败。宜搭平台运行态全局对象必须显式使用 `window.Deep`、`window.DeepYida`、`window.YidaNativeComponents` 等 `window.*` 访问，不要从包中导入。
+
+如果宜搭物料依赖表已经先于 OpenYida CLI 升级，且你已经确认运行时确实会注入某个新裸包，可以临时设置 `OPENYIDA_CANVAS_ALLOW_UNSUPPORTED_IMPORTS=1` 退回 legacy `window["pkg"]` 映射发布；这只是白名单漂移逃生舱，不应用来绕过 `useDataBinding` 这类不存在的 hook 或未验证依赖。
+
+Canvas 没有官方 `useDataBinding` hook，不得从任何包 `import { useDataBinding }`。真实表单数据绑定使用页面内本地 `useYidaData(binding)`、`DataBridge` 与同源 `fetch` 实现。
 
 编译位置：OpenYida CLI **本地用 Babel** 把源码转译为 `runtimeCode` + `importedModules`（`import`→`window.<别名>`、`export default`→`YidaComp`、依赖名正则抽取），不调用任何在线编译服务，因此不依赖登录态、不经过风控。别名映射逐条镜像自 `dependencies.ts` 的 `getModuleAliasMap()`；运行时消费契约见 `factory.tsx`（`new Function` 执行 `runtimeCode` 取 `YidaComp`）。
 

package/yida-skills/skills/yida-canvas-data-binding/SKILL.md

@@ -16,6 +16,7 @@ Code Canvas 运行时是标准 React 组件环境，组件没有普通宜搭自
 - `YidaCodeCanvas` 物料只透传 `code / runtimeCode / importedModules / pageType`。
 - 组件内没有 `this` 上下文，也没有 `dataSourceMap`。
 - `this.utils.yida.*`、`didMount()`、`_customState` 等普通页面契约不可用。
+- Canvas 没有官方 `useDataBinding` hook，不得从任何包 `import { useDataBinding }`；真实表单数据绑定用页面内本地 `useYidaData(binding)`、`DataBridge` 和同源 `fetch` 实现。
 - Cookie 由浏览器同源请求自动携带，前端代码不能硬编码 Cookie、appSecret、accessKey 或外部密钥。
 - 调宜搭同源端点时，请求必须带 `credentials: 'include'`。
 - CSRF 优先从 `window.g_config._csrf_token` 或 `window.g_config.csrfToken` 读取；内部端点常同时需要 `_csrf_token` 参数和 `global_csrf_token` 请求头。

package/yida-skills/skills/yida-custom-page/SKILL.md

@@ -16,6 +16,7 @@ description: 宜搭普通自定义页面 JSX / Jsx 组件开发规范（React 16
 - 完整应用 `fast_build` 如果已有 bound app/page，主页面源码直接落到该页面；只在缺少主入口 display page 且用户意图允许新增时创建页面容器。
 - 用户只说“优化这个页面 URL / 修改现有页面 / 重新发布”时，本技能与 `yida-publish-page` 配合即可完成，不创建 app/page。
 - 如果用户给的是普通表单 `formUuid`，页面源码只能把它作为数据源或入口链接使用；不能把数据表单 ID 当作发布目标。
+- 页面源码路径按 Bash cwd 选择：从仓库根执行命令时用 `project/pages/src/...`；如果 cwd 已是 `<workspace>/project`，用 `pages/src/...`，不要写成 `project/pages/src/...`。
 
 ## 核心规则
 
@@ -85,6 +86,8 @@ description: 宜搭普通自定义页面 JSX / Jsx 组件开发规范（React 16
 
 以开发「员工信息查询页」为例，完整流程如下：
 
+下面命令以仓库根为视角；如果当前 cwd 已经是 `<workspace>/project`，把 `project/pages/src/...` 改成 `pages/src/...`。读取生成文件和 Schema 时优先用宿主 Read / Glob / Grep，不要在 CLI 成功后 Bash `cat`/`ls` 复核。
+
 1. 获取表单 Schema，确认字段 ID：
 
 ```bash

package/yida-skills/skills/yida-login/SKILL.md

@@ -1,14 +1,16 @@
 ---
 name: yida-login
-description: 宜搭登录态管理。默认 OAuth token；YIDA_AUTH_ENABLED=true 时使用宿主注入 token。
+description: 宜搭登录态管理。以 OpenYida auth snapshot 为准；默认 OAuth token，snapshot 返回 env 注入状态时使用宿主 token。
 ---
 
 # yida-login
 
 ## Mode
 
-- IF `YIDA_AUTH_ENABLED=true`: `auth_mode=token`, `auth_source=env`; only credential sources are host-injected token env such as `OPENYIDA_ACCESS_TOKEN` and `OPENYIDA_REFRESH_TOKEN`.
-- ELSE: `auth_mode=token`; use OAuth token flow only.
+- Do not infer auth mode from agent name, host product, workspace path, or a guessed environment variable.
+- First read `openyida agent-capabilities --summary-json`; fallback to `openyida login --check-only --json` only when needed.
+- If the snapshot reports `login.auth_source=env` or `failure_reason=env_token_missing`, treat it as host-injected token mode. The only credential sources are host-injected token env such as `OPENYIDA_ACCESS_TOKEN` and `OPENYIDA_REFRESH_TOKEN`.
+- Otherwise, `auth_mode=token` uses the default OAuth token session flow.
 - NEVER infer auth from `.cache/cookies*.json`.
 
 ## Preflight
@@ -31,12 +33,12 @@ openyida login --check-only --json
 | Observed status | Action |
 |---|---|
 | `auth_mode=token`, `status=ok` or `can_auto_use=true` | Continue business command |
-| `failure_reason=env_token_missing` | STOP; host did not inject `OPENYIDA_ACCESS_TOKEN` or `OPENYIDA_REFRESH_TOKEN`; do not OAuth |
-| `auth_mode=token`, not logged in, `YIDA_AUTH_ENABLED` is not true | Run `openyida login`, then verify with `openyida login --check-only --json` |
+| `auth_source=env` / `failure_reason=env_token_missing` | Treat as host-injected token mode; if token is missing, STOP and ask host to inject `OPENYIDA_ACCESS_TOKEN` or `OPENYIDA_REFRESH_TOKEN`; do not OAuth |
+| `auth_mode=token`, not logged in, and snapshot does not report env injection | Run `openyida login`, then verify with `openyida login --check-only --json` |
 
 ## Token Mode Commands
 
-Use OAuth login only when `YIDA_AUTH_ENABLED` is not true.
+Use OAuth login only when the auth snapshot does not report env injection.
 
 ```bash
 openyida login
@@ -58,7 +60,7 @@ Overseas / international / global / Japan / Global YiDA => add `--intl` or equiv
 
 ## Host-Injected Token Mode Commands
 
-Use only when `YIDA_AUTH_ENABLED=true`.
+Use only after the auth snapshot reports `auth_source=env` or `failure_reason=env_token_missing`.
 
 ```bash
 openyida agent-capabilities --summary-json

package/yida-skills/skills/yida-publish-page/SKILL.md

@@ -63,6 +63,8 @@ description: 自定义页面 JSX 编译发布技能；schema-managed 页面由
 openyida publish <源文件路径> <appType> <formUuid> [--compat] [--canvas] [--health-check] [--force]
 ```
 
+路径口径：从仓库根执行时，源文件用 `project/pages/src/...`；如果 Bash cwd 已经是 `<workspace>/project`，源文件用 `pages/src/...`，不要传 `project/pages/src/...` 导致查找 `project/project/pages/src/...`。发布失败提示源文件不存在时，先按该规则切换路径，不要自动发布另一份文件。
+
 > 本技能覆盖两条并列发布链路：**普通自定义页面 JSX/Jsx 组件链路**（`.oyd.jsx` / `.jsx`，Babel + UglifyJS + `Jsx` 组件 Schema）和 **Code Canvas 链路**（`.canvas.jsx`，本地 Babel 编译 + `YidaCodeCanvas` Schema）。从零写普通自定义页面见 `yida-custom-page`；从零写或迁移 Canvas 页见 `yida-canvas-custom-page` / `yida-canvas-upgrade`。
 > 注意：`openyida check-page` / `openyida compile` 当前是普通自定义页面检查器，不适合作为 `.canvas.jsx` 的预检；Canvas 预检以 `publish` 的「编译 Code Canvas 源码」阶段为准。
 
@@ -139,7 +141,7 @@ body { background-color: #f2f3f5; }
 
 ## 注意事项
 
-- 发布目标地址由当前环境配置和 auth context（默认 token session；`YIDA_AUTH_ENABLED=true` 时为宿主注入 token）中的 `base_url` 决定
+- 发布目标地址由当前环境配置和 auth snapshot（本地 OAuth token session 或 snapshot 明确返回的宿主注入 env token）中的 `base_url` 决定
 - 碰到组织 corpId 不匹配时，询问用户是重新登录到目标组织，还是确认在当前组织继续发布到已解析页面；不要通过新建应用规避不匹配
 - **编写源码前必须先加载对应页面子技能**：普通自定义页面 JSX/Jsx 组件链路调用 `use_skill("yida-custom-page", "编写宜搭普通自定义页面 JSX")`；Code Canvas 链路调用 `use_skill("yida-canvas-custom-page", "编写 Code Canvas 自定义页面")`。旧式 `renderJsx` 写法不要使用 Hooks，现代普通自定义页面 authoring 写法必须走 `.oyd.jsx` 兼容编译；Canvas 源码写成 `.canvas.jsx`
 

package/yida-skills/skills-index.json

@@ -713,7 +713,7 @@
       "name": "yida-login",
       "path": "skills/yida-login/SKILL.md",
       "display_name": "宜搭登录态管理",
-      "description": "宜搭登录态管理。默认 OAuth token 模式；YIDA_AUTH_ENABLED=true 时使用宿主注入 token。",
+      "description": "宜搭登录态管理。以 OpenYida auth snapshot 为准；默认 OAuth token，snapshot 返回 env 注入状态时使用宿主 token。",
       "category": "yida-skills/context",
       "tags": [
         "登录",