openyida 2026.8.17-3 → 2026.8.19

package/README.md

@@ -377,7 +377,7 @@ Run `openyida --help` or `openyida <command> --help` for detailed usage.
 | `openyida app-list [--size N]` | List my Yida apps |
 | `openyida corp-efficiency [overview\|details\|detail\|groups\|notify] [options] [--open\|--no-open]` | Query enterprise efficiency overview and detail reports |
 | `openyida create-app "<name>"\|--name <name> [options] [--locale zh_CN\|en_US\|ja_JP] [--open\|--no-open]` | Create a Yida app |
-| `openyida update-app <appType> [--name "..."] [--layout slide\|ver] [--theme deepBlue]` | Update app info |
+| `openyida update-app <appType> [--name "..."] [--layout slide\|ver] [--theme deepBlue] [--hide-app-nav\|--show-app-nav]` | Update app info |
 | `openyida app-online <appType> [--to-ding-app-center] [--show-app-center]` | Enable a Yida app |
 | `openyida app-offline <appType> [--to-ding-app-center] [--show-app-center]` | Disable a Yida app |
 | `openyida nav-group <list\|create\|rename\|delete\|move\|order\|auto-order\|hide\|show> <appType> ...` | Manage app sidebar navigation groups |

package/docs/capabilities.md

@@ -1,6 +1,6 @@
 # OpenYida 功能完整列表
 
-这份清单面向宜搭使用者和 AI Agent，按本地 OpenYida `2026.8.12-1` 的 101 条命令和技能路由整理。参数细节可以继续查看 `openyida --help`、`openyida <command> --help` 或 `openyida commands --json`。
+这份清单面向宜搭使用者和 AI Agent，按本地 OpenYida `2026.8.19` 的 101 条命令和技能路由整理。参数细节可以继续查看 `openyida --help`、`openyida <command> --help` 或 `openyida commands --json`。
 
 <Note>
 日常使用建议先运行 `openyida agent-capabilities --summary-json`，它会轻量返回版本、登录态、组织、工作目录和命令清单摘要。只有排查命令契约、权限元数据或登录异常时，再使用完整的 `openyida agent-capabilities --json`。
@@ -30,12 +30,12 @@
 |---|---|
 | 查询我的应用 | `openyida app-list [--size N]` |
 | 创建应用 | `openyida create-app "<应用名称>"` |
-| 更新应用名称、布局、主题 | `openyida update-app <appType> [--name "..."] [--layout slide\|ver] [--theme deepBlue]` |
+| 更新应用名称、布局、主题、访问态应用导航显示 | `openyida update-app <appType> [--name "..."] [--layout slide\|ver] [--theme deepBlue] [--hide-app-nav\|--show-app-nav]` |
 | 启用应用 / 上线应用 | `openyida app-online <appType> [--to-ding-app-center] [--show-app-center]` |
 | 停用应用 / 下线应用 | `openyida app-offline <appType> [--to-ding-app-center] [--show-app-center]` |
 | 导出应用迁移包 | `openyida export <appType> [output]` |
 | 导入应用迁移包 | `openyida import <file> [name]` |
-| 管理左侧导航分组 | `openyida nav-group <list\|create\|rename\|delete\|move\|order\|hide\|show> <appType> ...` |
+| 管理左侧导航分组 | `openyida nav-group <list\|create\|rename\|delete\|move\|order\|auto-order\|hide\|show> <appType> ...` |
 | 管理应用管理员 | `openyida app-permission <get\|set\|add\|remove\|search-user> ...` |
 | 管理应用多语言 | `openyida i18n <overview\|config\|languages\|list\|upsert\|delete\|translate\|translate-all\|upgrade> <appType> ...` |
 | 查询组织基础信息、容量、额度、域名 | `openyida basic-info <overview\|commodity\|grant\|capacity\|quota\|abs-path\|dataflow\|i18n\|domain>` |

package/lib/app/builder-ai-source.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const { detectActiveTool } = require('../core/utils');
+
+const BUILDER_AI_SOURCE_FALLBACK = 'local';
+const SUPPORTED_BUILDER_AI_SOURCES = new Set([
+  BUILDER_AI_SOURCE_FALLBACK,
+  'codex',
+  'qwenwork',
+  'qoderwork',
+  'qoder',
+  'wukong',
+  'mulerun',
+  'claude-code',
+  'opencode',
+  'cursor',
+  'aone-copilot',
+]);
+
+function normalizeBuilderAiSource(source) {
+  const normalized = String(source || '').trim().toLowerCase();
+  return SUPPORTED_BUILDER_AI_SOURCES.has(normalized) ? normalized : null;
+}
+
+function resolveBuilderAiSource() {
+  try {
+    const activeTool = detectActiveTool();
+    return normalizeBuilderAiSource(activeTool && activeTool.tool) || BUILDER_AI_SOURCE_FALLBACK;
+  } catch (err) {
+    return BUILDER_AI_SOURCE_FALLBACK;
+  }
+}
+
+module.exports = {
+  BUILDER_AI_SOURCE_FALLBACK,
+  SUPPORTED_BUILDER_AI_SOURCES,
+  normalizeBuilderAiSource,
+  resolveBuilderAiSource,
+};

package/lib/app/create-app.js

@@ -19,6 +19,7 @@ const { buildYidaI18n, normalizeYidaLocale, resolveContentLocale } = require('..
 const { parseOpenOption, withBrowserHandoff } = require('../core/browser-handoff');
 const { throwCommandError } = require('../core/command-errors');
 const { assertPresetThemeKey } = require('./theme-presets');
+const { resolveBuilderAiSource } = require('./builder-ai-source');
 
 const DEFAULT_APP_OPTIONS = {
   icon: 'xian-yingyong',
@@ -270,7 +271,7 @@ function buildCreateAppPayload(params, auth, contentLocale, openExclusive, openP
     openExclusiveUnit: 'n',
     group: 'ALL',
     fromBuilderAi: 'y',
-    builderAiSource: 'local',
+    builderAiSource: resolveBuilderAiSource(),
   };
   if (navTheme) {
     payload.navTheme = navTheme;

package/lib/app/import-app.js

@@ -21,6 +21,7 @@ const { buildYidaI18n, resolveContentLocale } = require('../core/yida-i18n');
 const { banner, step, label, success, fail, warn, info, error, result, usage, hint } = require('../core/chalk');
 const { throwUsage } = require('../core/command-errors');
 const { getSchemaServerRevision } = require('../core/server-revision');
+const { resolveBuilderAiSource } = require('./builder-ai-source');
 
 // ── 创建新应用 ────────────────────────────────────────
 
@@ -41,7 +42,7 @@ async function createApp(appName, authRef) {
       openExclusiveUnit: 'n',
       group: 'ALL',
       fromBuilderAi: 'y',
-      builderAiSource: 'local',
+      builderAiSource: resolveBuilderAiSource(),
     });
     return httpPost(auth.baseUrl, '/query/app/registerApp.json', postData);
   }, authRef);

package/lib/app/update-app.js

@@ -1,7 +1,7 @@
 /**
  * update-app.js - 更新宜搭应用信息
  *
- * 用法：openyida update-app <appType> --name "新名称" [--desc "描述"] [--icon "图标"] [--layout slide|ver]
+ * 用法：openyida update-app <appType> --name "新名称" [--desc "描述"] [--icon "图标"] [--layout slide|ver] [--hide-app-nav]
  */
 
 'use strict';
@@ -33,6 +33,7 @@ function parseArgs(args) {
     colour: null,
     navTheme: null,
     layoutDirection: null,
+    hideAppNav: null,
   };
 
   // 第一个参数是 appType
@@ -95,6 +96,12 @@ function parseArgs(args) {
           i++;
         }
         break;
+      case '--hide-app-nav':
+        result.hideAppNav = 'y';
+        break;
+      case '--show-app-nav':
+        result.hideAppNav = 'n';
+        break;
     }
   }
 
@@ -111,7 +118,7 @@ function printUsage() {
 }
 
 function hasShellUpdate(params) {
-  return !!(params.icon || params.colour || params.navTheme || params.layoutDirection);
+  return !!(params.icon || params.colour || params.navTheme || params.layoutDirection || params.hideAppNav !== null);
 }
 
 function pickText(value, fallback) {
@@ -162,7 +169,7 @@ function buildUpdateAppPostData(params, currentApp = {}, authRef) {
     ? `${params.icon}%%${params.iconColor || '#0089FF'}`
     : (currentApp.icon || currentApp.iconUrl || 'xian-yingyong%%#0089FF');
 
-  return {
+  const postDataObj = {
     _csrf_token: authRef.csrfToken,
     _locale_time_zone_offset: '28800000',
     appType: params.appType,
@@ -196,6 +203,12 @@ function buildUpdateAppPostData(params, currentApp = {}, authRef) {
     addWaterMark: currentApp.addWaterMark || (currentApp.config && currentApp.config.ADDWATERMARK) || 'y',
     sentryMode: currentApp.sentryMode || (currentApp.config && currentApp.config.SENTRY_MODE) || 'y',
   };
+
+  if (params.hideAppNav !== null) {
+    postDataObj.hideAppNav = params.hideAppNav;
+  }
+
+  return postDataObj;
 }
 
 async function fetchCurrentApp(appType, authRef) {
@@ -229,7 +242,15 @@ async function run(args) {
     throwUsage(t('update_app.missing_app_type'), t('update_app.usage'));
   }
 
-  if (!params.name && !params.desc && !params.icon && !params.colour && !params.navTheme && !params.layoutDirection) {
+  if (
+    !params.name &&
+    !params.desc &&
+    !params.icon &&
+    !params.colour &&
+    !params.navTheme &&
+    !params.layoutDirection &&
+    params.hideAppNav === null
+  ) {
     chalkError(t('update_app.missing_update_field'), { exit: false });
     printUsage();
     throwUsage(t('update_app.missing_update_field'), t('update_app.usage'));
@@ -244,6 +265,9 @@ async function run(args) {
   if (params.colour || params.navTheme || params.layoutDirection) {
     label('Theme', `${params.colour || '-'} / ${params.navTheme || '-'} / ${params.layoutDirection || '-'}`);
   }
+  if (params.hideAppNav !== null) {
+    label('Hide App Nav', params.hideAppNav);
+  }
 
   // Step 1: 读取登录态
   step(1, t('common.step_login', 1));
@@ -291,6 +315,7 @@ async function run(args) {
         colour: params.colour || undefined,
         navTheme: params.navTheme || undefined,
         layoutDirection: params.layoutDirection || undefined,
+        hideAppNav: params.hideAppNav === null ? undefined : params.hideAppNav,
       },
     }));
   } else {

package/lib/core/command-manifest.js

@@ -1037,7 +1037,7 @@ const COMMAND_GROUPS = [
         output: 'json',
       }),
       command('create-app', ['create-app'], 'create-app "<name>"|--name <name> [options] [--locale zh_CN|en_US|ja_JP] [--open|--no-open]', 'help.cmd_create_app'),
-      command('update-app', ['update-app'], 'update-app <appType> [--name "..."] [--layout slide|ver] [--theme deepBlue]', 'help.cmd_update_app'),
+      command('update-app', ['update-app'], 'update-app <appType> [--name "..."] [--layout slide|ver] [--theme deepBlue] [--hide-app-nav|--show-app-nav]', 'help.cmd_update_app'),
       command('app-online', ['app-online'], 'app-online <appType> [--to-ding-app-center] [--show-app-center]', 'help.cmd_app_online'),
       command('app-offline', ['app-offline'], 'app-offline <appType> [--to-ding-app-center] [--show-app-center]', 'help.cmd_app_offline'),
       command('nav-group', ['nav-group'], 'nav-group <list|create|rename|delete|move|order|auto-order|hide|show> <appType> ...', 'help.cmd_nav_group', {

package/lib/core/locales/en.js

@@ -137,6 +137,7 @@ Commands:
   logout                                                       Logout / switch account
   create-app "<name>" [desc] [icon] [color] [theme] [nav] [layout]  Create an app, output appType
   create-page <appType> "<pageName>" [--mode dashboard] [--hide-nav] Create a custom page, output pageId
+  update-app <appType> [--name "..."] [--hide-app-nav|--show-app-nav] Update app info
   create-form create <appType> "<formName>" <fieldsJSON> [--layout <layout>] [--theme <theme>] [--label-align <align>]  Create a form page
   create-form update <appType> <formUuid> <changesJSON>        Update a form page
   list-forms <appType> [--keyword <text>]                      List forms/pages in an app
@@ -283,8 +284,8 @@ Examples:
     page_config_example: 'Example: openyida get-page-config APP_XXX FORM-XXX',
     form_config_usage: 'Usage: openyida update-form-config <appType> <formUuid> <isRenderNav> <title>',
     form_config_example: 'Example: openyida update-form-config APP_XXX FORM-XXX false "Page Title"',
-    update_app_usage: 'Usage: openyida update-app <appType> --name "New Name" [--desc "Description"] [--icon "icon-name"]',
-    update_app_example: 'Example: openyida update-app APP_XXX --name "New App Name" --desc "New Description"',
+    update_app_usage: 'Usage: openyida update-app <appType> [--name "New Name"] [--desc "Description"] [--icon "icon-name"] [--hide-app-nav|--show-app-nav]',
+    update_app_example: 'Example: openyida update-app APP_XXX --name "New App Name" --desc "New Description"; openyida update-app APP_XXX --hide-app-nav',
     export_usage: 'Usage: openyida export <appType> [output]',
     export_example1: 'Example: openyida export APP_XXX',
     export_example2: '        openyida export APP_XXX ./my-app-backup.json',
@@ -606,17 +607,17 @@ Examples:
   create_page: {
     title: '  openyida create-page - Yida Custom Page Creation Tool',
     usage: 'Usage: openyida create-page <appType> "<pageName>" [--mode dashboard] [--hide-nav]',
-    example: 'Example: openyida create-page "APP_XXX" "Game Home" --mode dashboard; explicitly hide nav: openyida create-page "APP_XXX" "Fullscreen Dashboard" --mode dashboard --hide-nav',
+    example: 'Example: openyida create-page "APP_XXX" "Game Home" --mode dashboard; explicitly hide page nav: openyida create-page "APP_XXX" "Fullscreen Dashboard" --mode dashboard --hide-nav',
     app_id: '  App ID:    {0}',
     page_name: '  Page name: {0}',
     step_create: '\n📄 Step 2: Create Custom Page\n',
     sending: '  Sending saveFormSchemaInfo request...',
     success: '  ✅ Page created successfully!',
-    step_dashboard_config: '\n🖥️  Step 3: Configure hidden navigation',
-    dashboard_config_ok: '  ✅ Navigation hidden by explicit request, chromeless custom URL enabled',
-    dashboard_config_failed: '  ⚠️  Hidden navigation config failed: {0}',
+    step_dashboard_config: '\n🖥️  Step 3: Configure page-level hidden navigation',
+    dashboard_config_ok: '  ✅ Page navigation hidden by explicit request, chromeless custom URL enabled',
+    dashboard_config_failed: '  ⚠️  Page-level hidden navigation config failed: {0}',
     err_mode_invalid: 'Unsupported page mode: {0}',
-    mode_hint: 'Available modes: default, dashboard. Navigation is visible by default; pass --hide-nav or --render-nav false to hide it.',
+    mode_hint: 'Available modes: default, dashboard. Page navigation is visible by default; pass --hide-nav or --render-nav false to hide page navigation. Use update-app --hide-app-nav to hide app navigation.',
     page_id_label: '  pageId: {0}',
     url_label: '  URL: {0}',
     failed: '  ❌ Creation failed: {0}',
@@ -950,11 +951,11 @@ Examples:
 
   // ── lib/update-app.js ─────────────────────────────
   update_app: {
-    usage: 'Usage: openyida update-app <appType> [--name "New Name"] [--desc "Description"] [--layout slide|ver] [--theme deepBlue]',
-    example: 'Example: openyida update-app APP_XXX --name "New App Name" --layout ver --theme deepBlue',
-    options: 'Options:\n  --name, -n      App name (specify at least one update field)\n  --desc, -d      App description\n  --icon          Icon name (e.g. xian-yingyong)\n  --icon-color    Icon color (default: #0089FF)\n  --theme         App theme colour\n  --nav-theme     Navigation theme navTheme\n  --layout        Layout direction layoutDirection (slide or ver)',
+    usage: 'Usage: openyida update-app <appType> [--name "New Name"] [--desc "Description"] [--layout slide|ver] [--theme deepBlue] [--hide-app-nav|--show-app-nav]',
+    example: 'Example: openyida update-app APP_XXX --name "New App Name" --layout ver --theme deepBlue; page shell nav: openyida update-app APP_XXX --hide-app-nav',
+    options: 'Options:\n  --name, -n      App name (specify at least one update field)\n  --desc, -d      App description\n  --icon          Icon name (e.g. xian-yingyong)\n  --icon-color    Icon color (default: #0089FF)\n  --theme         App theme colour\n  --nav-theme     Navigation theme navTheme\n  --layout        Layout direction layoutDirection (slide or ver)\n  --hide-app-nav  Hide app navigation in visit mode, only for custom pages with self-rendered top/side navigation\n  --show-app-nav  Restore app navigation in visit mode',
     missing_app_type: 'Error: missing appType argument',
-    missing_update_field: 'Error: at least one update field must be specified (--name, --desc, --icon, --theme, --nav-theme, --layout)',
+    missing_update_field: 'Error: at least one update field must be specified (--name, --desc, --icon, --theme, --nav-theme, --layout, --hide-app-nav, --show-app-nav)',
     title: '  update-app - Yida App Info Update Tool',
     app_type: '\n  App ID:       {0}',
     new_name: '  New name:     {0}',

package/lib/core/locales/zh.js

@@ -137,6 +137,7 @@ openyida - 宜搭命令行工具
   logout                                                       退出登录 / 切换账号
   create-app "<名称>" [描述] [图标] [颜色] [主题色] [导航风格] [布局]   创建应用，输出 appType
   create-page <appType> "<页面名>" [--mode dashboard] [--hide-nav] 创建自定义页面，输出 pageId
+  update-app <appType> [--name "..."] [--hide-app-nav|--show-app-nav] 更新应用信息
   create-form create <appType> "<表单名>" <字段JSON> [--layout <布局>] [--theme <主题>] [--label-align <对齐>]  创建表单页面
   create-form update <appType> <formUuid> <修改JSON>           更新表单页面
   list-forms <appType> [--keyword <关键词>]                    列出应用下的表单/页面
@@ -284,8 +285,8 @@ openyida - 宜搭命令行工具
     page_config_example: '示例: openyida get-page-config APP_XXX FORM-XXX',
     form_config_usage: '用法: openyida update-form-config <appType> <formUuid> <isRenderNav> <title>',
     form_config_example: '示例: openyida update-form-config APP_XXX FORM-XXX false "页面标题"',
-    update_app_usage: '用法: openyida update-app <appType> --name "新名称" [--desc "描述"] [--icon "图标"]',
-    update_app_example: '示例: openyida update-app APP_XXX --name "新应用名称" --desc "新描述"',
+    update_app_usage: '用法: openyida update-app <appType> [--name "新名称"] [--desc "描述"] [--icon "图标"] [--hide-app-nav|--show-app-nav]',
+    update_app_example: '示例: openyida update-app APP_XXX --name "新应用名称" --desc "新描述"；openyida update-app APP_XXX --hide-app-nav',
     export_usage: '用法: openyida export <appType> [output]',
     export_example1: '示例: openyida export APP_XXX',
     export_example2: '      openyida export APP_XXX ./my-app-backup.json',
@@ -578,17 +579,17 @@ openyida - 宜搭命令行工具
   create_page: {
     title: '  openyida create-page - 宜搭自定义页面创建工具',
     usage: '用法: openyida create-page <appType> "<pageName>" [--mode dashboard] [--hide-nav]',
-    example: '示例: openyida create-page "APP_XXX" "驾驶舱" --mode dashboard；显式隐藏导航: openyida create-page "APP_XXX" "全屏看板" --mode dashboard --hide-nav',
+    example: '示例: openyida create-page "APP_XXX" "驾驶舱" --mode dashboard；显式隐藏页面导航: openyida create-page "APP_XXX" "全屏看板" --mode dashboard --hide-nav',
     app_id: '  应用 ID:  {0}',
     page_name: '  页面名称: {0}',
     step_create: '\n📄 Step 2: 创建自定义页面\n',
     sending: '  发送 saveFormSchemaInfo 请求...',
     success: '  ✅ 页面创建成功！',
-    step_dashboard_config: '\n🖥️  Step 3: 配置隐藏导航',
-    dashboard_config_ok: '  ✅ 已按显式要求隐藏导航，并输出无左侧栏的 custom URL',
-    dashboard_config_failed: '  ⚠️  隐藏导航配置失败: {0}',
+    step_dashboard_config: '\n🖥️  Step 3: 配置页面级隐藏导航',
+    dashboard_config_ok: '  ✅ 已按显式要求隐藏页面导航，并输出页面级隐藏导航的 custom URL',
+    dashboard_config_failed: '  ⚠️  页面级隐藏导航配置失败: {0}',
     err_mode_invalid: '不支持的页面模式: {0}',
-    mode_hint: '可用模式: default, dashboard；默认导航可见，只有传 --hide-nav 或 --render-nav false 才隐藏导航',
+    mode_hint: '可用模式: default, dashboard；默认页面导航可见，只有传 --hide-nav 或 --render-nav false 才隐藏页面导航；应用导航隐藏请用 update-app --hide-app-nav',
     page_id_label: '  pageId:   {0}',
     url_label: '  访问地址: {0}',
     failed: '  ❌ 创建失败: {0}',
@@ -879,11 +880,11 @@ openyida - 宜搭命令行工具
 
   // ── lib/update-app.js ─────────────────────────────
   update_app: {
-    usage: '用法: openyida update-app <appType> [--name "新名称"] [--desc "描述"] [--layout slide|ver] [--theme deepBlue]',
-    example: '示例: openyida update-app APP_XXX --name "新应用名称" --layout ver --theme deepBlue',
-    options: '选项:\n  --name, -n      应用名称（至少指定一个更新字段）\n  --desc, -d      应用描述\n  --icon          图标名称（如: xian-yingyong）\n  --icon-color    图标颜色（默认: #0089FF）\n  --theme         应用主题 colour\n  --nav-theme     导航主题 navTheme\n  --layout        布局方向 layoutDirection（slide 或 ver）',
+    usage: '用法: openyida update-app <appType> [--name "新名称"] [--desc "描述"] [--layout slide|ver] [--theme deepBlue] [--hide-app-nav|--show-app-nav]',
+    example: '示例: openyida update-app APP_XXX --name "新应用名称" --layout ver --theme deepBlue；页面内自绘导航时: openyida update-app APP_XXX --hide-app-nav',
+    options: '选项:\n  --name, -n      应用名称（至少指定一个更新字段）\n  --desc, -d      应用描述\n  --icon          图标名称（如: xian-yingyong）\n  --icon-color    图标颜色（默认: #0089FF）\n  --theme         应用主题 colour\n  --nav-theme     导航主题 navTheme\n  --layout        布局方向 layoutDirection（slide 或 ver）\n  --hide-app-nav  隐藏访问态应用导航，仅在自定义页自绘顶部/侧边导航壳时使用\n  --show-app-nav  恢复访问态应用导航',
     missing_app_type: '错误: 缺少 appType 参数',
-    missing_update_field: '错误: 至少需要指定一个更新字段（--name, --desc, --icon, --theme, --nav-theme, --layout）',
+    missing_update_field: '错误: 至少需要指定一个更新字段（--name, --desc, --icon, --theme, --nav-theme, --layout, --hide-app-nav, --show-app-nav）',
     title: '  update-app - 宜搭应用信息更新工具',
     app_type: '\n  应用 ID:      {0}',
     new_name: '  新名称:       {0}',

package/package.json

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

package/yida-skills/SKILL.md

@@ -112,7 +112,7 @@ description: >
 | 页面视觉方向、页面美化、去 AI 味 | `yida-design` 产出 `prd/<项目名>/prd.md` 和 `prd/<项目名>/design.md`，或单页 PRD 章节 + design spec；实现阶段默认交给 `yida-canvas-custom-page` |
 | 应用级主题、品牌色、全局换肤 | `yida-design` |
 | 平台左侧导航树分组/排序 | `yida-nav-group` |
-| 页面隐藏原导航后自绘导航壳 | `yida-nav-shell` |
+| 应用导航隐藏后自绘导航壳 | `yida-nav-shell` |
 | 普通报表/统计 | `yida-report` |
 | PPT 页面 | `yida-ppt-slider` |
 | 公开访问/组织内分享 | `yida-page-config` |

package/yida-skills/references/field-and-url-reference.md

@@ -30,6 +30,14 @@
 
 拼接模板（`{base_url}` 取自登录域名，如公有云 `https://www.aliwork.com`）：
 
+先分清导航控制口径：
+
+| 要控制什么 | 配置/参数 | 适用对象 | 不要怎么做 |
+| --- | --- | --- | --- |
+| 应用导航隐藏 | `hideAppNav='y'` | 自定义页自绘顶部/侧边/导航壳 | 不要给自定义页 URL 拼 `isRenderNav=false` 来代替 |
+| 页面导航隐藏 | `isRenderNav=false` | 页面、提交页、详情页 | 不要据此自动隐藏应用导航 |
+| 平台导航排序 | `yida-nav-group` | 常规多页面应用 | 不要在自定义页重复做同级应用导航 |
+
 | 页面类型 | URL 格式 |
 |---------|---------|
 | 应用首页 | `{base_url}/{appType}/workbench` |
@@ -37,19 +45,29 @@
 | 数据管理页（列表） | `{base_url}/{appType}/workbench/{formUuid}` |
 | 数据管理页（iframe 嵌入） | `{base_url}/{appType}/workbench/{formUuid}?iframe=true` |
 | 自定义页面 | `{base_url}/{appType}/custom/{formUuid}` |
-| 自定义页面（隐藏导航） | 上行 + `?isRenderNav=false` |
+| 自定义页面（应用导航隐藏） | URL 仍为上行；通过应用基础设置 `hideAppNav='y'` 控制 |
 | 表单详情页（抽屉/隐藏导航） | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}&navConfig.layout=1180&isRenderNav=false` |
 | 表单详情页（编辑态） | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}&mode=edit&navConfig.layout=1180&isRenderNav=false` |
 
 > 任意地址可追加 `corpid={corpId}` 自动切到对应组织；无 query 时用 `?corpid=...`，已有 query 时用 `&corpid=...`。
 
-> 自定义页里的新增/提交入口默认使用 `?isRenderNav=false`，对应表单设置里的 `isRenderNav=false`。需要持久化表单提交页导航设置时，可在创建表单后执行 `openyida update-form-config <appType> <formUuid> false "<表单标题>"`；已有 query 时按 `&isRenderNav=false` 合并。
+> 自定义页里的新增/提交入口默认使用 `?isRenderNav=false`，对应表单/页面设置里的 `isRenderNav=false`。这是表单页或页面级导航隐藏，不是应用导航隐藏。需要持久化表单提交页导航设置时，可在创建表单后执行 `openyida update-form-config <appType> <formUuid> false "<表单标题>"`；已有 query 时按 `&isRenderNav=false` 合并。
 
 ## 页面内自定义导航 URL 参数规则
 
+默认不要在自定义页面中自己绘制应用级侧边导航、顶部导航或同级模块菜单；同应用页面切换优先交给宜搭平台导航和 `yida-nav-group`。
+
+只有用户显式要求在自定义页面中实现自己的顶部导航、侧边导航、导航壳或自绘应用级导航时，才进入本节规则，并执行：
+
+```bash
+openyida update-app <appType> --hide-app-nav
+```
+
+用户只要求页面隐藏导航、无导航、全屏无框或 `isRenderNav=false` 时，走页面级隐藏逻辑，不自动隐藏应用导航。
+
 当自定义页自己绘制导航壳、并隐藏宜搭原导航时，导航项不能只保存 `formUuid`，必须保存可合并的 URL 参数：
 
-- 自定义展示页目标：使用 `{base_url}/{appType}/custom/{formUuid}?isRenderNav=false`，保持目标页也不显示宜搭原导航。
+- 自定义展示页目标：使用 `{base_url}/{appType}/custom/{formUuid}`；应用导航是否显示由应用基础设置 `hideAppNav` 决定，不通过 `isRenderNav=false` 传递。
 - 数据表单目标：若在导航壳内容区嵌入，用 `{base_url}/{appType}/workbench/{formUuid}?iframe=true`；若整页跳转到 workbench，明确接受目标页回到宜搭工作台框架。
 - 跨组织访问：在已有 query 后追加 `&corpid={corpId}`；没有 query 时用 `?corpid={corpId}`。
 - 业务深链：导航项可带 `tab`、`view`、`dateRange`、`mode` 等白名单参数；拼 URL 时与公共参数合并，不能被 `router.push(formUuid)` 吞掉。

package/yida-skills/references/task-retrospective.md

@@ -35,7 +35,7 @@ OpenYida 任务完成后，除了交付当前结果，还要判断是否有可
    用户要求参考 Dribbble / 优秀示例时，必须把参考转成可执行设计变量：页面类型、构图、视觉锚点、信息密度、色彩关系、组件细节、反默认点。交付时说明“参考转译成了什么”。
 
 2. **独立品牌页使用页面级主题**
-   独立品牌页、活动页和隐藏导航沉浸页应自带页面级主题 token。普通业务页、页面重构和局部美化优先读取当前应用主题色。
+   独立品牌页、活动页、页面级沉浸页和应用导航隐藏后的自绘壳应自带页面级主题 token。普通业务页、页面重构和局部美化优先读取当前应用主题色。
 
 3. **`--theme` 只能填平台预置 key**
    `deepBlue/podBlue/royalBlue/lightBlue/teal/podGreen/deepPurple/purple/podOrange/yellow/magenta/red/greyBlue/coffee/black` 才能作为 app `colour`。默认优先使用 `podBlue`、`podGreen`、`podOrange`；自定义“活力橙”“深玫红”“暗黑金”等设计主题，应在每个页面注入 `style#yida-global-theme` 或 scoped tokens，`blue`、`green`、`orange` 作为应用主题 token profile 保留原名。

package/yida-skills/skills/yida-app/workflow/step-7-page-code.md

@@ -17,8 +17,9 @@
 3. 页面结构已明确且适合生成器时，从 PRD + `design.md` 派生当前业务自己的 `page-spec.json`。
 4. `page-spec.json` 写 `sourceOfTruth`、`prdFile`、`designFile`、`designRefs` 和 `conflictPolicy: "prd-design-win"`。
 5. 列表、看板、详情页优先读取真实表单数据，写 `dataBinding.mode=form`、真实 `appType/formUuid/fieldId` 和字段映射。
-6. 没有真实数据时，页面展示空态、表单入口、刷新或登记按钮。
-7. 页面源码用 `.canvas.jsx` / `.canvas.tsx`、`YidaComp`、页面生成器或本地快检。
+6. 页面源码默认不自绘应用级侧边导航、顶部应用导航或同级模块菜单；PRD 的导航顺序交给 Step 8 的平台导航排序处理。只有用户显式要求在自定义页面内实现自己的应用级导航、隐藏应用导航或独立全屏应用壳时，才执行 `use_skill("yida-nav-shell")`。
+7. 没有真实数据时，页面展示空态、表单入口、刷新或登记按钮。
+8. 页面源码用 `.canvas.jsx` / `.canvas.tsx`、`YidaComp`、页面生成器或本地快检。
 
 ## 事实源修正
 
@@ -39,6 +40,7 @@
 ## Checklist
 
 - [ ] 页面实现已读取 PRD 和 `design.md`；
+- [ ] 页面没有默认自绘应用级侧边导航 / 顶部导航；如有页面内自绘导航，已有用户显式要求和 `yida-nav-shell` 依据；
 - [ ] 页面数据优先接真实表单；
 - [ ] 页面源码没有 emoji 和裸中文 JSX 表达式；
 - [ ] 本地校验通过，或已有明确错误和修复动作。

package/yida-skills/skills/yida-app/workflow/step-8-publish-navigation.md

@@ -23,6 +23,7 @@ openyida publish <source> <appType> <displayPageFormUuid> --auto-nav-order
 5. PRD 写明页面/表单清单顺序时，执行 `openyida nav-group order <appType> <页面/表单...>`。
 6. PRD 缺少明确页面清单时，用 `--auto-nav-order` / `nav-group auto-order` 兜底。
 7. 兜底顺序为：门户/首页/工作台入口、业务办理、数据管理、经营分析、系统配置。
+8. 本步骤配置宜搭平台导航，不要求页面源码实现侧边栏或顶部应用导航；除非用户显式要求页面内自绘导航，否则不要回头在自定义页面中补导航壳。
 
 ## 产出
 

package/yida-skills/skills/yida-app/workflow/step-9-output-finish.md

@@ -74,7 +74,7 @@
 | 应用首页 | `{base_url}/{appType}/workbench` |
 | 表单提交页（默认隐藏导航） | `{base_url}/{appType}/submission/{formUuid}?isRenderNav=false` |
 | 自定义页面 | `{base_url}/{appType}/custom/{formUuid}` |
-| 自定义页面（隐藏导航） | `{base_url}/{appType}/custom/{formUuid}?isRenderNav=false` |
+| 自定义页面（应用导航隐藏） | `{base_url}/{appType}/custom/{formUuid}`；由应用基础设置 `hideAppNav='y'` 控制 |
 | 表单详情页（抽屉/隐藏导航） | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}&navConfig.layout=1180&isRenderNav=false` |
 | 表单详情页（编辑模式） | `{base_url}/{appType}/formDetail/{formUuid}?formInstId={formInstId}&mode=edit&navConfig.layout=1180&isRenderNav=false` |
 

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

@@ -92,7 +92,7 @@ UI 和产品设计输入来自 `yida-design` 输出的 `prd/<项目名>/prd.md`
 2. **组件增强可降级**：门户、成员、部门、上传组件都做 feature detect 和 fallback；组件缺失时页面仍展示自绘基线。
 3. **值先归一化**：成员、部门、文件的原始返回值保留到 `raw` 用于检查，业务 payload 使用统一结构。
 4. **UI 改造保持功能契约**：页面美感提升、页面重构和局部美化只调整颜色、布局、密度、间距、视觉层级、素材和图标表达；已有数据源、字段映射、按钮动作、筛选逻辑、提交 URL、权限和业务状态按原有实现保留。
-5. **主题实现消费设计结果**：`themeProfile`、`themeScope`、`themeColorSource` 来自 `yida-design` 的 `design.md`，业务场景和页面边界来自 `prd.md` 或派生 `page-spec.json`；真实业务页、页面重构和局部美化以当前应用主题色为基准，并读取对应 `--color-brand1-*` 与 `--color-group`。独立品牌/活动页、隐藏导航沉浸页和用户明确要求完全不同风格的页面，使用页面级固定主题（`followRuntimeTheme: false` 或等价 CSS 变量）。需要自定义色盘时复制 `references/theme-runtime-helpers.md` 的 `YidaCodeCanvas` helper，向当前文档、同源可访问父级 iframe 文档，以及 `FormOpenContainer` 打开的同源提交页/详情页子 iframe 文档注入 `style#yida-global-theme`。
+5. **主题实现消费设计结果**：`themeProfile`、`themeScope`、`themeColorSource` 来自 `yida-design` 的 `design.md`，业务场景和页面边界来自 `prd.md` 或派生 `page-spec.json`；真实业务页、页面重构和局部美化以当前应用主题色为基准，并读取对应 `--color-brand1-*` 与 `--color-group`。独立品牌/活动页、页面级沉浸页、应用导航隐藏后的自绘壳和用户明确要求完全不同风格的页面，使用页面级固定主题（`followRuntimeTheme: false` 或等价 CSS 变量）。需要自定义色盘时复制 `references/theme-runtime-helpers.md` 的 `YidaCodeCanvas` helper，向当前文档、同源可访问父级 iframe 文档，以及 `FormOpenContainer` 打开的同源提交页/详情页子 iframe 文档注入 `style#yida-global-theme`。
 6. **先验证再扩展业务**：原生组件、上传、组织搜索、弹层类能力先做 smoke 页面，确认 PC/移动端都可用后再进入复杂业务页面。
 7. **生成骨架占位符必须可直发**：可编译页面骨架同时支持生成器替换变量和原样发布。JSON 占位符用 `parseTemplateJson(raw, fallback)`，展示文案占位符用 `withFallback` / `applyPageFallbacks` 兜底，未替换时页面继续可运行，并显示业务化 fallback 文案。
 8. **light 页面使用清爽业务色**：业务列表、协同表、数据管理页、工作台和门户默认使用 light 模式；主操作、选中态、筛选焦点和批量操作使用品牌色，边框用浅色品牌混合。用户明确要求暗色大屏/夜间模式/高对比风格时使用深色主视觉。
@@ -104,8 +104,8 @@ UI 和产品设计输入来自 `yida-design` 输出的 `prd/<项目名>/prd.md`
 14. **实现骨架消费业务 spec**：品牌名、行业词、导航、指标、卡片标题、图片 alt、CTA、色彩 profile 和 section 说明来自当前业务 spec。若 CLI 报业务内容不足，补齐/改写 spec 或 patch 源码后重新生成/编译。
 15. **页面产物使用纯文本业务文案**：`.canvas.jsx` 源码、`page-spec.json` 中会渲染到页面的文案、JS 注释、数据常量和产物文件路径都使用无 emoji 文本。页面生成、`compileCanvasLocal` 或 `publish` 报 emoji 错误时，先改 spec/源码/路径，再重新校验发布。若 emoji 原本承担图标含义，必须按 `design.md.iconSystem` 改成 `lucide-react` 或 `@ant-design/icons` 的具体组件，默认 `lucide-react`；不得用 CSS 绘制图形、单字母、首字母、标点符号、Unicode 符号或临时 SVG 冒充图标。
 16. **JSX 文案只能是文本或字符串**：JSX 文案只能写成纯文本 `所有级别` 或带引号字符串 `{'所有级别'}`；筛选项、按钮、状态、空态和表格列名等中文业务文案都按此规则书写。花括号里只能放真实 JS 变量/表达式，不能把中文文案写成 `{所有级别}`、`{处理中}`；Unicode escape 被工具解码后也必须保留字符串引号。
-17. **同应用页面入口归入导航**：快捷入口目标如果是同应用内页面，优先写入 `appBlueprint.navigation` 或平台导航分组，由应用导航内切换；自定义页内容区的 `quickEntries` 只放当前页动作、表单新建/查看、外部链接、跨应用资源，或显式隐藏平台导航后的页面内导航壳入口。
-18. **表单打开入口统一容器**：自定义页内「新建 / 提交表单 / 查看详情」保留原生表单能力，并统一封装为 `FormOpenContainer`。按钮事件只能调用 `openForm({ type: "submission" | "detail", ... })`。查看详情必须先从 `searchFormDatas` 返回行解析真实实例 ID，顺序固定为 `row.formInstId || row.formInstanceId || row.instanceId || row.id`，并优先使用 `row.formInstId`；缺少实例 ID 时禁用详情按钮或提示，不得打开空 `formInstId` 的详情页。PC 端主操作使用右侧抽屉 + iframe 承载隐藏导航的提交页或详情页，抽屉默认半屏 `50vw`，提交页和详情页使用同一宽度规则；详情页 URL 固定追加 `formInstId`、`navConfig.layout=1180` 和 `isRenderNav=false`；iframe `onLoad` 后必须用 `installYidaGlobalThemeIntoFrame(themeTokens, iframeElement)` 把当前页面主题同步到同源子文档；关闭后回到当前列表/工作台并刷新数据。移动端可直接进入提交页/详情页或新页打开，依赖表单自身 JS 注入的 `style#yida-global-theme`。
+17. **应用级导航归平台承载**：默认不要在自定义页面中创建侧边导航、顶部应用导航、门户导航壳或同级模块菜单；同应用页面入口优先写入 `appBlueprint.navigation` 或平台导航分组，由应用导航内切换。自定义页内容区只放当前页动作、表单新建/查看、外部链接、跨应用资源。只有用户显式要求“在自定义页面中实现自己的顶部导航 / 侧边导航 / 导航壳 / 自绘应用级导航 / 隐藏应用导航”时，才执行 `use_skill("yida-nav-shell")`，生成页面内导航壳，并在发布后执行 `openyida update-app <appType> --hide-app-nav`；只要求页面隐藏导航、无导航全屏或 `isRenderNav=false` 时，走页面级配置，不自动配置 `hideAppNav`。其他自定义页默认不配置 `hideAppNav`。
+18. **表单打开入口统一容器**：自定义页内「新建 / 提交表单 / 查看详情」保留原生表单能力，并统一封装为 `FormOpenContainer`。按钮事件只能调用 `openForm({ type: "submission" | "detail", ... })`。查看详情必须先从 `searchFormDatas` 返回行解析真实实例 ID，顺序固定为 `row.formInstId || row.formInstanceId || row.instanceId || row.id`，并优先使用 `row.formInstId`；缺少实例 ID 时禁用详情按钮或提示，不得打开空 `formInstId` 的详情页。PC 端主操作使用右侧抽屉 + iframe 承载页面级隐藏导航的提交页或详情页，抽屉默认半屏 `50vw`，提交页和详情页使用同一宽度规则；详情页 URL 固定追加 `formInstId`、`navConfig.layout=1180` 和 `isRenderNav=false`；iframe `onLoad` 后必须用 `installYidaGlobalThemeIntoFrame(themeTokens, iframeElement)` 把当前页面主题同步到同源子文档；关闭后回到当前列表/工作台并刷新数据。移动端可直接进入提交页/详情页或新页打开，依赖表单自身 JS 注入的 `style#yida-global-theme`。
 19. **图标资源固定为可加载库**：页面图标只使用 `lucide-react` 或 `@ant-design/icons`，默认使用 `lucide-react` named import。只有页面已经采用 Ant Design 图标语言、或 antd 组件语境需要 Outlined 图标时，才使用 `@ant-design/icons`。快捷入口、按钮、状态、导航和空态图标在写源码前先建立 `actionIconMap` / `statusIconMap`，按业务语义映射到具体组件，例如 `Plus`、`Upload`、`Download`、`Eye`、`Building2`、`AlertCircle`、`Check`。图标外层可以用 CSS 控制尺寸、颜色、圆角、背景和 hover，但图标本体必须来自上述两类组件，不能用 CSS 形状、字母或 emoji 替代。
 
 ## 数据真实性边界
@@ -155,6 +155,6 @@ openyida get-schema <appType> <formUuid> --field-map-json
 | [employeefield-verification.md](references/employeefield-verification.md) | 运行时事实、原生组件验证、EmployeeField 验收 | 验证成员/字段组件时阅读 |
 | [data-bridge-guide.md](references/data-bridge-guide.md) | `YidaCodeCanvas` 组件内自建 HTTP 数据桥 | 接入真实数据时阅读 |
 | [canvas-style-implementation-guide.md](references/canvas-style-implementation-guide.md) | 将 `design.md` 的 App 主题色、antd token、背景层、圆角密度、控件焦点/下拉 reset、图表配色落到 `YidaCodeCanvas` 组件 | 写样式和主题时阅读 |
-| [theme-runtime-helpers.md](references/theme-runtime-helpers.md) | `YidaCodeCanvas` 组件 / 平台 JSX 组件自定义主题注入 helper，支持 iframe 父级窗口和表单抽屉同源子 iframe | 自定义色盘、`style#yida-global-theme`、隐藏导航沉浸页或 FormOpenContainer 时阅读 |
+| [theme-runtime-helpers.md](references/theme-runtime-helpers.md) | `YidaCodeCanvas` 组件 / 平台 JSX 组件自定义主题注入 helper，支持 iframe 父级窗口和表单抽屉同源子 iframe | 自定义色盘、`style#yida-global-theme`、页面级沉浸页、应用导航隐藏后的自绘壳或 FormOpenContainer 时阅读 |
 | [component-library-guide.md](references/component-library-guide.md) | 组件库推荐组合和页面选型建议 | 选择 UI/图表依赖时阅读 |
 | [canvas-authoring-examples.md](references/canvas-authoring-examples.md) | 最小组件、hooks、副作用、图表示例 | 手写 `.canvas.jsx` 代码时阅读 |

package/yida-skills/skills/yida-canvas-custom-page/references/canvas-style-implementation-guide.md

@@ -2,7 +2,7 @@
 
 本文件是 `YidaCodeCanvas` 组件的样式实现适配指南，不是新的设计系统，也不产出配色、视觉 DNA 或页面风格。设计事实唯一来自 `yida-design` 输出的 `prd.md` 与 `design.md`：PRD 给业务场景和页面边界，`design.md` 给完整主题、token、视觉 DNA、布局、材质、圆角、密度、呼吸感、背景层、组件和状态规则。`YidaCodeCanvas` 组件只负责把这些规则落到 antd token、CSS 变量、Tailwind、图表、控件状态、背景 CSS 和表单 iframe 主题同步。
 
-真实业务页、页面重构和局部美化以当前应用主题色为基准；缺少主题证据时先按业务气质选择平台预置主题或自定义色盘，不固定回到 `podBlue` / #1677ff。独立品牌/活动页、隐藏导航沉浸页和用户明确要求完全不同风格的页面使用页面级固定主题和差异化色盘。
+真实业务页、页面重构和局部美化以当前应用主题色为基准；缺少主题证据时先按业务气质选择平台预置主题或自定义色盘，不固定回到 `podBlue` / #1677ff。独立品牌/活动页、页面级沉浸页、应用导航隐藏后的自绘壳和用户明确要求完全不同风格的页面使用页面级固定主题和差异化色盘。
 
 ## 应用主题与页面风格冲突处理
 
@@ -11,7 +11,7 @@
 | 左侧平台导航选中态是应用主题色，页面主按钮 / 标题强调 / 卡片选中态用了另一套主色 | 页面主操作、链接、选中态、重点标签和图表主序列改回应用主题 `--color-brand1-*` |
 | design.md 生成了青绿、紫色、蓝色等辅助色，但当前应用主题是橙色或其他色 | 保留 `design.md` 的布局、卡片、密度、图表语言，把生成色彩降为辅助色、浅底背景、分组色或第二图表序列 |
 | 用户要求导航和内容一起换色 | 走 `themeScope=app`，由应用主题配置或壳层主题更新统一处理 |
-| 页面是隐藏导航的独立官网、活动页、公开落地页 | 走 `themeScope=page`，页面根节点注入 scoped CSS vars，并在 PRD 写明独立色盘原因 |
+| 页面是页面级沉浸页、应用导航隐藏后的自绘壳、独立官网、活动页、公开落地页 | 走 `themeScope=page`，页面根节点注入 scoped CSS vars，并在 PRD 写明独立色盘原因 |
 
 实现时先读取 `themeRelation`。默认值是 `跟随应用主题`，不是 `跟随生成色盘色相`。
 

package/yida-skills/skills/yida-canvas-custom-page/references/navigation-and-entry-guide.md

@@ -1,6 +1,6 @@
 # YidaCodeCanvas 应用内导航与快捷入口
 
-自定义页面里的快捷入口先判定目标类型，再选择跳转方式。目标是应用内页面时，用户应感觉是在宜搭应用导航内切换，而不是弹出一个脱离左侧导航的新页面。
+自定义页面里的快捷入口先判定目标类型，再选择跳转方式。目标是应用内页面时，用户应感觉是在宜搭应用导航内切换，而不是弹出一个脱离左侧导航的新页面，也不是在当前自定义页面中额外生成一套侧边导航或顶部应用导航。
 
 ## 运行态事实
 
@@ -8,11 +8,27 @@
 - `openPage` / `window.open` 更适合外部链接、新标签、钉钉链接、文件预览等场景；同应用页面默认在当前应用壳内切换。
 - 页面隐藏应用导航后，页面内自绘导航壳接管跨视图切换；导航可见时使用平台导航承载同级页面切换。
 
+## 导航决策
+
+| 用户说法 | 怎么理解 | 怎么做 |
+| --- | --- | --- |
+| “加侧边导航 / 顶部导航 / 导航壳 / 自绘应用导航” | 自定义页要承担应用级导航 | 进入 `yida-nav-shell`，并执行 `openyida update-app <appType> --hide-app-nav` |
+| “隐藏应用导航” | 应用基础设置隐藏导航 | 执行 `update-app --hide-app-nav`；需要自绘导航时再进 `yida-nav-shell` |
+| “隐藏页面导航 / 全屏 / 无导航 / isRenderNav=false” | 页面级导航隐藏 | 走 `yida-page-config`，不自动隐藏应用导航 |
+| “页面内 tab / 分段 / 内容区局部导航” | 当前页面内部切换 | 保留平台应用导航，不进入 `yida-nav-shell` |
+| “工作台 / 门户 / 看板 / 首页” | 页面类型或入口，不是隐藏导航信号 | 默认保留平台应用导航 |
+
 ## 设计优先级
 
 同应用内页面优先在平台应用导航内切换。用户要求“加快捷入口/常用入口”时，先把目标页面归入应用导航或导航分组；自定义页内容区聚焦当前页操作和跨资源入口。
 
-自定义页内容区的快捷入口优先承载当前页动作、表单新建/查看、外部链接和跨应用资源。只有用户显式要求隐藏平台导航、页面内门户壳或自绘导航时，同应用页面切换才进入页面内导航壳。
+自定义页内容区的快捷入口优先承载当前页动作、表单新建/查看、外部链接和跨应用资源。只有用户显式要求隐藏应用导航、页面内门户壳或自绘应用级导航时，同应用页面切换才进入页面内导航壳。
+
+不要做三件事：
+
+- 不要因为“快捷入口多”就在自定义页里做一套应用级侧边导航。
+- 不要用 `isRenderNav=false` 隐藏自定义页的应用导航。
+- 不要让平台应用导航和自绘应用级导航同时出现。
 
 ## 目标分类
 
@@ -27,6 +43,8 @@
 
 保留 `linkType: "page" | "app" | "url"` 这类语义配置；只有 `url` 类型写普通链接。
 
+`submission` 和 `detail` 的 `isRenderNav=false` 只用于原生表单页/详情页隐藏页面导航，不表示自定义页隐藏应用导航。
+
 ## Page Spec 建议字段
 
 工作台、门户首页和管理首页含快捷入口时，在 `page-spec.json` 中写结构化入口，方便生成器和后续 patch 保留语义：

package/yida-skills/skills/yida-canvas-custom-page/references/page-generation-guide.md

@@ -70,13 +70,31 @@ PRD 写有 `pageSpecHandoff` 时，可以把 `pageSpecHandoff` 转成 `page-spec
 | 列表、管理页、订单管理、客户列表、工单池 | `business-list` | `list` | 搜索筛选、表格、状态标签、详情抽屉 |
 | 详情页、客户档案、订单详情、项目详情 | `detail-profile` | `detail` | 单对象摘要、章节、侧栏元信息、时间线 |
 | 主从分栏、工单处理台、左列表右详情 | `split-pane-detail` | `list` | 左侧队列、右侧详情、时间线、动作区 |
-| 页面内门户壳、多入口门户、隐藏导航门户 | `portal-shell-home` | `workbench` | 仅显式要求页面内门户壳、自绘导航或隐藏平台导航时使用；默认门户/工作台不自建导航 |
+| 页面内门户壳、多入口门户、隐藏应用导航门户 | `portal-shell-home` | `workbench` | 仅显式要求页面内门户壳、自绘顶部/侧边导航或隐藏应用导航时使用；默认门户/工作台不自建导航 |
 
 如果用户要求“门户组件 / 成员 / 部门 / 上传组件”，继续使用本技能，并按 [native-components-bridge.md](native-components-bridge.md) 的桥接规则用 `YidaCodeCanvas` 组件实现。
 
-默认实现保留平台应用导航，同应用内页面入口写入 `appBlueprint.navigation` 或平台导航分组。页面内 tab、自绘侧边栏或独立门户壳最多写 `appBlueprint.hasPageNavigation: true`，并保持平台导航可见；PRD 明确隐藏平台导航、无导航全屏体验或 `isRenderNav=false` 时，在 spec 里写 `appBlueprint.renderNav: false`；发布后再用 `openyida update-form-config <appType> <formUuid> false "<页面标题>"` 隐藏平台导航，保持页面单导航。
+### 导航生成规则
 
-快捷入口目标是同应用内页面时，先把目标放入 `appBlueprint.navigation` / 平台导航分组，由应用导航内切换；默认工作台或门户内容区聚焦当前页动作、表单新建/查看、外部链接、跨应用资源，或用户显式隐藏平台导航后的页面内导航壳。表单新建/提交入口必须写清 `targetType: "submission"` 与 `openMode: "responsive-drawer"`；表单查看入口必须写清 `targetType: "detail"`、目标 `formUuid` 和真实 `formInstId` 来源。两类入口都默认 `hideNav: true` / `isRenderNav=false`：PC 端生成 `FormOpenContainer` 右侧抽屉 iframe，抽屉默认半屏 `50vw`，提交页和详情页使用同一宽度规则；移动端整页或新页打开隐藏导航原生表单页。PC 抽屉 iframe 不会自动继承父页面 CSS 变量，`FormOpenContainer` 必须接收 design.md 派生的 `themeTokens`，并在 iframe `onLoad` 后调用 `installYidaGlobalThemeIntoFrame(themeTokens, iframeElement)`，保证提交页和详情页同源子文档也有 `style#yida-global-theme`。
+| 场景 | spec 字段 | 发布后动作 |
+| --- | --- | --- |
+| 普通自定义页、工作台、门户、看板、首页 | 不写 `hideAppNav` | 保留平台应用导航 |
+| 页面内 tab、分段筛选、内容区快捷入口 | 不写 `hideAppNav` | 保留平台应用导航 |
+| 自定义页顶部导航、侧边导航、导航壳、自绘应用级导航 | 写 `appBlueprint.hideAppNav: 'y'` | 执行 `openyida update-app <appType> --hide-app-nav` |
+| 页面隐藏导航、无导航全屏、`isRenderNav=false` | 写 `appBlueprint.renderNav: false` | 执行 `openyida update-form-config <appType> <formUuid> false "<页面标题>"` |
+
+两条规则必须分开：`hideAppNav` 控制应用导航，`renderNav/isRenderNav=false` 控制页面导航。其他自定义页默认不调用 `update-app --hide-app-nav`。
+
+### 快捷入口生成规则
+
+| 入口目标 | spec 写法 | 页面实现 |
+| --- | --- | --- |
+| 同应用内页面 | 放入 `appBlueprint.navigation` / 平台导航分组 | 由应用导航内切换 |
+| 当前页动作、外部链接、跨应用资源 | 写当前页快捷入口 | 留在自定义页内容区 |
+| 表单新建/提交 | `targetType: "submission"` + `openMode: "responsive-drawer"` | PC 用 `FormOpenContainer` 右侧抽屉 iframe，URL 带 `isRenderNav=false` |
+| 表单查看详情 | `targetType: "detail"` + 目标 `formUuid` + 真实 `formInstId` 来源 | PC 用同一套抽屉宽度，详情 URL 带 `navConfig.layout=1180&isRenderNav=false` |
+
+表单提交/详情里的 `isRenderNav=false` 只隐藏原生表单页或详情页的页面导航，不用于隐藏自定义页应用导航。PC 抽屉 iframe 不会自动继承父页面 CSS 变量，`FormOpenContainer` 必须接收 design.md 派生的 `themeTokens`，并在 iframe `onLoad` 后调用 `installYidaGlobalThemeIntoFrame(themeTokens, iframeElement)`，保证提交页和详情页同源子文档也有 `style#yida-global-theme`。移动端整页或新页打开隐藏导航原生表单页。
 
 ## 官网与品牌页素材流程