openyida 2026.7.7 → 2026.7.9

package/yida-skills/skills/yida-data-management/SKILL.md

@@ -11,6 +11,7 @@ description: 宜搭数据管理。表单实例/子表/流程实例/任务中心
 - 不要编造 formInstId 或 processInstanceId，必须从查询结果中提取
 - 不要用此命令修改表单结构（字段增删改），应使用 `yida-create-form-page`
 - **绝对禁止猜测或编造字段 ID（fieldId）**，宜搭字段 ID 由平台随机生成（如 `textField_eftt1aa5m`），无法预测，必须通过 `openyida get-schema` 获取
+- 不要用 shell heredoc、`cat`/`echo`/`printf`/`tee` 或重定向生成 `--data-file`、`--search-file`、CSV 或一次性脚本
 
 ## 严格要求 (MUST DO)
 
@@ -22,8 +23,8 @@ description: 宜搭数据管理。表单实例/子表/流程实例/任务中心
 - **录入数据后，必须执行 `openyida data query` 抽查至少 1 条记录，确认 `formData` 中字段有实际值（非空），否则说明字段 ID 有误，需重新排查**
 - **读取子表明细超过 50 行时，必须使用 `openyida data query subform` 或 `listTableDataByFormInstIdAndTableId` 分页查询完整子表；不要把 `searchFormDatas.currentPage` 当作子表分页**
 - **本技能不读写 memory**：数据操作通过 CLI 命令写入宜搭平台，不依赖跨会话的 memory 状态
-- 一次性造数、旧数据修正、字段迁移脚本可以使用 Python 或 JS，优先选择更快更清晰的实现；脚本、导入数据、查询条件文件必须放在 `.cache/openyida/` 下，并复用真实查询到的 appType/formUuid/fieldId/formInstId
-- **禁止在仓库根目录生成导入用的 `*.json`、`*.js`、`*.py`、`*.csv` 临时文件**；推荐使用 `.cache/openyida/data-import/` 存放数据文件，`.cache/openyida/scripts/` 存放一次性执行脚本
+- 一次性造数、旧数据修正、字段迁移脚本可以使用 Python 或 JS，优先选择更快更清晰的实现；脚本、导入数据、查询条件文件必须由结构化文件写入工具创建到 `<projectRoot>/.cache/openyida/<项目名或任务名>/` 下，并复用真实查询到的 appType/formUuid/fieldId/formInstId
+- **禁止在仓库根目录、系统临时目录或 `.cache/` 顶层生成导入用的 `*.json`、`*.js`、`*.py`、`*.csv` 临时文件**；推荐使用 `<projectRoot>/.cache/openyida/<项目名或任务名>/data-import/` 存放数据文件，`<projectRoot>/.cache/openyida/<项目名或任务名>/scripts/` 存放一次性执行脚本
 
 ## 适用场景
 
@@ -61,15 +62,17 @@ description: 宜搭数据管理。表单实例/子表/流程实例/任务中心
 ### 表单实例
 
 ```bash
-openyida data query form <appType> <formUuid> [--page 1 --size 20] [--search-json '<json>'|--search-file .cache/openyida/data-import/search.json] [--resolve-aliases]
+openyida data query form <appType> <formUuid> [--page 1 --size 20] [--search-json '<json>'|--search-file .cache/openyida/<项目名或任务名>/data-import/search.json] [--resolve-aliases]
 openyida data get form <appType> --inst-id <formInstId>
 openyida data create form <appType> <formUuid> --data-json '<json>' [--resolve-aliases]
-openyida data create form <appType> <formUuid> --data-file .cache/openyida/data-import/record.json [--resolve-aliases]
+openyida data create form <appType> <formUuid> --data-file .cache/openyida/<项目名或任务名>/data-import/record.json [--resolve-aliases]
 openyida data update form <appType> --inst-id <formInstId> --form-uuid <formUuid> --data-json '<json>' [--resolve-aliases]
-openyida data update form <appType> --inst-id <formInstId> --form-uuid <formUuid> --data-file .cache/openyida/data-import/patch.json [--resolve-aliases]
+openyida data update form <appType> --inst-id <formInstId> --form-uuid <formUuid> --data-file .cache/openyida/<项目名或任务名>/data-import/patch.json [--resolve-aliases]
 openyida data query subform <appType> <formUuid> --inst-id <formInstId> --table-field-id <fieldId|alias> [--page 1 --size 100] [--resolve-aliases]
 ```
 
+> `--data-file` / `--search-file` 指向的文件先用 create_file / Write / file edit tool 创建。上方路径默认从 OpenYida project 工作目录执行；从 workspace 根执行命令时路径加 `project/` 前缀。
+
 当 JSON 使用宜搭组件别名作为 key 时，追加 `--resolve-aliases`，OpenYida 会先读取表单 Schema 中的 `componentAlias.items`，再将别名转换为真实 `fieldId` 后调用数据接口。更新类命令若要解析别名，必须额外传 `--form-uuid <formUuid>`。
 
 ### 子表超过 50 行
@@ -90,14 +93,14 @@ openyida data query subform <appType> <formUuid> --inst-id <formInstId> --table-
 ### 流程实例
 
 ```bash
-openyida data query process <appType> <formUuid> [--instance-status RUNNING] [--search-file .cache/openyida/data-import/process-search.json] [--resolve-aliases]
+openyida data query process <appType> <formUuid> [--instance-status RUNNING] [--search-file .cache/openyida/<项目名或任务名>/data-import/process-search.json] [--resolve-aliases]
 openyida data get process <appType> --process-inst-id <processInstanceId>
 openyida data create process <appType> <formUuid> --process-code <processCode> --data-json '<json>' [--resolve-aliases]
-openyida data create process <appType> <formUuid> --process-code <processCode> --data-file .cache/openyida/data-import/process-record.json [--resolve-aliases]
+openyida data create process <appType> <formUuid> --process-code <processCode> --data-file .cache/openyida/<项目名或任务名>/data-import/process-record.json [--resolve-aliases]
 openyida data update process <appType> --process-inst-id <processInstanceId> --form-uuid <formUuid> --data-json '<json>' [--resolve-aliases]
-openyida data update process <appType> --process-inst-id <processInstanceId> --form-uuid <formUuid> --data-file .cache/openyida/data-import/process-patch.json [--resolve-aliases]
+openyida data update process <appType> --process-inst-id <processInstanceId> --form-uuid <formUuid> --data-file .cache/openyida/<项目名或任务名>/data-import/process-patch.json [--resolve-aliases]
 openyida data query operation-records <appType> --process-inst-id <processInstanceId>
-openyida data execute task <appType> --task-id <taskId> --process-inst-id <processInstanceId> --out-result AGREE --remark '同意' [--data-file .cache/openyida/data-import/task-data.json] [--form-uuid <formUuid>] [--resolve-aliases]
+openyida data execute task <appType> --task-id <taskId> --process-inst-id <processInstanceId> --out-result AGREE --remark '同意' [--data-file .cache/openyida/<项目名或任务名>/data-import/task-data.json] [--form-uuid <formUuid>] [--resolve-aliases]
 ```
 
 ### 任务中心
@@ -156,7 +159,7 @@ openyida data query tasks <appType> --type todo|done|submitted|cc [--page 1 --si
 {"textField_xxx":"文本","numberField_xxx":10,"dateField_xxx":1719705600000,"employeeField_xxx":["userId"]}
 ```
 
-当 JSON 较长或用于批量导入时，写入 `.cache/openyida/data-import/<name>.json`，再使用 `--data-file` 或 `--search-file`；不要为了拼接命令在仓库根目录生成临时脚本。
+当 JSON 较长或用于批量导入时，使用结构化文件写入工具写入 `<projectRoot>/.cache/openyida/<项目名或任务名>/data-import/<name>.json`，再使用 `--data-file` 或 `--search-file`；不要为了拼接命令在仓库根目录、系统临时目录或 `.cache/` 顶层生成临时脚本。
 
 ### 常见字段格式
 
@@ -215,7 +218,7 @@ openyida sample yida-data-management form-field-template   # 表单字段定义
 - `pageSize` 最大 100，QPS 限制约 40 次/秒
 - `searchFieldJson` 和 `dynamicOrder` 必须传字符串
 - 字段 ID 通过 `openyida get-schema` 获取，不要手写猜测
-- 批量脚本可以用 Python `subprocess` 调用 `openyida data ...`，也可以用 JS 复用 Node 工具；脚本必须放在 `.cache/openyida/scripts/`，导入数据放在 `.cache/openyida/data-import/`
+- 批量脚本可以用 Python `subprocess` 调用 `openyida data ...`，也可以用 JS 复用 Node 工具；脚本必须由结构化文件写入工具创建到 `<projectRoot>/.cache/openyida/<项目名或任务名>/scripts/`，导入数据放在 `<projectRoot>/.cache/openyida/<项目名或任务名>/data-import/`
 
 ## 异常处理
 

package/yida-skills/skills/yida-data-source-connectors/SKILL.md

@@ -108,9 +108,11 @@ export function loadConnectorDataSource(dataSourceName, headers, query, body) {
 
 ```bash
 openyida publish <src> <appType> <formUuid> --health-check
-openyida get-schema <appType> <formUuid> > .cache/openyida/<page>-schema.json
+openyida get-schema <appType> <formUuid>
 ```
 
+如需保存回读 Schema，使用 create_file / Write / file edit tool 创建 `<projectRoot>/.cache/openyida/<项目名或任务名>/<page>-schema.json`；从 workspace 根执行后续命令时路径加 `project/` 前缀。不要使用 shell 重定向。
+
 检查点：
 
 - 设计器左侧“数据源”能看到新增连接器数据源。

package/yida-skills/skills/yida-flash-note-to-prd/references/examples.md

@@ -24,8 +24,9 @@
 
 ```bash
 # 方式 1：从文件读取
-echo "上述内容" > meeting.txt
-openyida flash-to-prd --file meeting.txt --name 员工积分管理系统
+# 先使用 create_file / Write / file edit tool 创建：
+# <projectRoot>/.cache/openyida/员工积分管理系统/flash-note/meeting.txt
+openyida flash-to-prd --file .cache/openyida/员工积分管理系统/flash-note/meeting.txt --name 员工积分管理系统
 
 # 方式 2：直接发给 AI 智能体（推荐）
 # 将文本直接粘贴到对话框，AI 自动识别并触发本技能

package/yida-skills/skills/yida-formula/references/examples.md

@@ -9,8 +9,8 @@
 ### 前置步骤：获取字段 ID
 
 ```bash
-openyida get-schema APP_XXX FORM-YYY > .cache/schema.json 2>&1
-# 从 schema.json 中找到各字段的 fieldId：
+openyida get-schema APP_XXX FORM-YYY
+# 从 stdout 中找到各字段的 fieldId，并用结构化文件写入工具更新 <projectRoot>/.cache/<项目名>-schema.json：
 # 交通费：numberField_transport
 # 住宿费：numberField_hotel
 # 餐饮费：numberField_meal
@@ -19,7 +19,7 @@ openyida get-schema APP_XXX FORM-YYY > .cache/schema.json 2>&1
 
 ### 执行：update 模式配置公式
 
-创建 `formula-config.json`：
+使用 create_file / Write / file edit tool 创建 `<projectRoot>/.cache/openyida/expense/formula-config.json`：
 
 ```json
 [
@@ -40,7 +40,7 @@ openyida get-schema APP_XXX FORM-YYY > .cache/schema.json 2>&1
 ```
 
 ```bash
-openyida create-form APP_XXX FORM-YYY formula-config.json
+openyida create-form update APP_XXX FORM-YYY .cache/openyida/expense/formula-config.json
 ```
 
 ### 输出

package/yida-skills/skills/yida-formula-evaluate/SKILL.md

@@ -39,13 +39,15 @@ openyida formula evaluate <公式或文件> [--schema schema.json] [--json] [--s
 1. 如果公式包含字段引用，先获取 Schema：
 
 ```bash
-openyida get-schema APP_XXX FORM-XXX > .cache/form-schema.json
+openyida get-schema APP_XXX FORM-XXX
 ```
 
+将 stdout 中需要复用的 Schema 通过 create_file / Write / file edit tool 保存到 `<projectRoot>/.cache/openyida/<项目名或任务名>/formula/form-schema.json`；不要用 shell 重定向。
+
 2. 运行静态检查：
 
 ```bash
-openyida formula evaluate 'IF(GT(#{numberField_total}, 100), "高", "低")' --schema .cache/form-schema.json
+openyida formula evaluate 'IF(GT(#{numberField_total}, 100), "高", "低")' --schema .cache/openyida/<项目名或任务名>/formula/form-schema.json
 ```
 
 3. 根据诊断结果修复：

package/yida-skills/skills/yida-get-schema/SKILL.md

@@ -13,11 +13,13 @@ description: 获取表单的完整 Schema 结构，用于确认字段 ID（field
 - 不要跳过 Schema 获取步骤直接进行数据操作，即使用户催促也必须先获取
 - 不要在 Schema 获取失败时继续执行后续操作，必须先解决问题
 - 不要缓存过期的 Schema 信息，表单结构变更后必须重新获取
+- 不要把 `openyida get-schema` 的 stdout 通过 shell 重定向保存成 JSON，也不要用 heredoc、`cat`/`echo`/`printf`/`tee` 生成 Schema 文件
 
 ## 严格要求 (MUST DO)
 
 - **凡是需要用到字段 ID（fieldId）的操作，必须先执行此命令**，不得跳过
-- 将关键字段 ID 映射（字段名 → fieldId）记录到 `.cache/<项目名>-schema.json`，供后续操作复用
+- 将关键字段 ID 映射（字段名 → fieldId）用结构化文件写入工具记录到 `<projectRoot>/.cache/<项目名>-schema.json`，供后续操作复用
+- 如需保存完整 Schema 文件，先执行命令获取 stdout，再用 create_file / Write / file edit tool 写入 `<projectRoot>/.cache/openyida/<项目名或任务名>/<表单名>-schema.json`；从 workspace 根执行后续命令时传 `project/.cache/...`
 - **录入/更新数据后，必须用 `openyida data query --size 1` 抽查一条记录，确认 `formData` 中字段有实际值（非空 `""`），若全部为空说明字段 ID 有误，需重新排查**
 
 ## 适用场景
@@ -61,13 +63,20 @@ openyida get-schema <appType> --all [--output-dir <dir>] [--keyword <text>] [--c
 ### 单表模式
 
 ```bash
-openyida get-schema APP_XXX FORM-XXX > .cache/customer-schema.json
+openyida get-schema APP_XXX FORM-XXX
+```
+
+如需复用输出，使用 agent 的结构化文件写入工具创建：
+
+```text
+<projectRoot>/.cache/openyida/customer/customer-schema.json
+<projectRoot>/.cache/customer-schema.json   # 仅保存 appType/formUuid/fieldId/reportId 等 ID 映射
 ```
 
 ### 批量模式
 
 ```bash
-openyida get-schema APP_XXX --all --output-dir .cache/schemas
+openyida get-schema APP_XXX --all --output-dir .cache/openyida/customer/schemas
 openyida get-schema APP_XXX --all --keyword 客户 --concurrency 5 --retries 2
 ```
 
@@ -90,8 +99,8 @@ openyida get-schema APP_XXX --all --keyword 客户 --concurrency 5 --retries 2
 | 异常场景 | 处理方式 |
 |---------|----------|
 | 命令返回失败 | 确认 appType 和 formUuid 正确，检查登录态 |
-| 输出被终端截断 | 重定向到文件：`openyida get-schema <appType> <formUuid> > .cache/schema.json` |
-| 需要多个表单字段 ID | 使用批量模式：`openyida get-schema <appType> --all --output-dir .cache/schemas` |
+| 输出被终端截断 | 重新执行后将 stdout 通过结构化文件写入工具保存到 `<projectRoot>/.cache/openyida/<项目名或任务名>/<表单名>-schema.json`；不要使用 shell 重定向 |
+| 需要多个表单字段 ID | 使用批量模式：`openyida get-schema <appType> --all --output-dir .cache/openyida/<项目名或任务名>/schemas` |
 | 批量部分失败 | 查看 stdout 的 `failedCount` 和 `forms[].errorMsg`，必要时提高 `--retries` 或缩小 `--keyword` 范围 |
 | 找不到目标字段 | 检查字段是否已创建，字段 ID 格式如 `textField_xxxxxxxx`，不能手写猜测 |
 | Schema 输出为空 | 表单可能没有字段，先用 `yida-create-form-page` 创建字段 |

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

@@ -81,10 +81,12 @@ openyida i18n upsert <appType> page_header --zh-CN "工作台" --en-US "Workbenc
 批量导入词条：
 
 ```bash
-openyida i18n batch-upsert <appType> --file i18n-items.json
+openyida i18n batch-upsert <appType> --file .cache/openyida/<项目名或任务名>/i18n/i18n-items.json
 ```
 
-`i18n-items.json` 示例：
+`i18n-items.json` 先用 create_file / Write / file edit tool 创建到 `<projectRoot>/.cache/openyida/<项目名或任务名>/i18n/`；不要用 shell heredoc 或重定向写文件。从 workspace 根执行命令时路径加 `project/` 前缀。
+
+文件内容示例：
 
 ```json
 [

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

@@ -16,6 +16,7 @@ description: 宜搭集成&自动化配置。支持创建、查询、开启、关
 - **创建/发布前必须确认**：执行集成自动化创建或发布操作前，必须向用户展示逻辑流配置摘要（触发条件、节点列表、通知对象），获得用户明确同意后再执行
 - 创建前先确认触发表单的 formUuid 和相关字段 ID
 - 创建成功后记录逻辑流 ID 到 `.cache/<项目名>-schema.json`
+- `--spec`、连接器输入等 JSON 文件必须先用结构化文件写入工具创建到 `<projectRoot>/.cache/openyida/<项目名或任务名>/integration/`；不要用 shell heredoc、`cat`/`echo`/`printf`/`tee` 或重定向写文件，也不要写仓库根目录或系统临时目录
 - 参考官方示例时不要只看默认页面 schema：集成自动化示例的默认页通常只是触发表单或说明页，逻辑流本体需要通过集成自动化接口/命令查询或创建
 
 ## 适用场景
@@ -242,10 +243,12 @@ openyida integration create APP_XXX FORM-A-XXX "调用 HTTP 连接器" \
 
 ```bash
 openyida integration create APP_XXX FORM-XXX "获取自身后分支更新" \
-  --spec project/integration/get-self-update.json \
+  --spec .cache/openyida/<项目名或任务名>/integration/get-self-update.json \
   --publish
 ```
 
+> `--spec` 文件先用 create_file / Write / file edit tool 创建。上方路径默认从 OpenYida project 工作目录执行；从 workspace 根执行命令时路径加 `project/` 前缀。
+
 ## 字段变量引用格式
 
 在通知标题和内容中，可以使用 `#{fieldId-ComponentType}#` 格式引用触发表单的字段值：

package/yida-skills/skills/yida-integration/references/examples.md

@@ -9,8 +9,8 @@
 ### 前置步骤：获取字段 ID
 
 ```bash
-openyida get-schema APP_XXX FORM-LEAVE > .cache/leave-schema.json 2>&1
-# 从 schema.json 中提取字段 ID：
+openyida get-schema APP_XXX FORM-LEAVE
+# 从 stdout 中提取字段 ID，并用结构化文件写入工具更新 <projectRoot>/.cache/<项目名>-schema.json：
 # 申请人：employeeField_applicant
 # 请假类型：selectField_leaveType
 # 开始日期：dateField_startDate

package/yida-skills/skills/yida-nav-shell/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: yida-nav-shell
+description: >
+  宜搭自定义页面「页面内导航壳」形态目录。当自定义页隐藏了应用导航（isRenderNav=false，沉浸式/独立页/门户首页/大屏/分享页）后，应用框架的导航消失，页面要用 JSX 自绘一套导航接管应用级导航。提供侧边栏/顶部/顶部+侧边混合/浮动胶囊/标签页五种 B 端导航形态的选型、骨架、native + Canvas 代码示例、多视图切换机制与带 URL 参数的跨页跳转规范。
+  当用户要求「给这个自定义页/沉浸式页面/门户/大屏 加个导航（侧边/顶部/浮动/标签）」「自定义导航」「导航隐藏了页面自己怎么做导航」「一个页面切多个视图」时触发。
+  注意：本技能是**页面内 JSX 自绘导航壳**；若用户要的是**平台左侧菜单/导航分组**（真实导航树、增删分组、排序菜单项），那是 yida-nav-group，不是本技能。
+---
+
+# yida-nav-shell — 页面内自绘导航壳
+
+## 定位（先读这段）
+
+自定义页**隐藏应用导航**（`isRenderNav=false`）后，宜搭框架的左侧/顶部导航消失，页面即整个视口。此时页面要**自己画一套导航**接管应用级导航——这就是「导航壳」。本技能是导航壳的**形态选型 + 骨架 + 代码示例**目录。
+
+> **一句话**：`yida-page-uiux` 定视觉方向（Step 0 判定导航是否隐藏）→ 本技能选**导航壳形态**并给骨架 → `yida-custom-page`(native) / `yida-canvas-custom-page`(Canvas) 落地 JSX。
+
+## 边界：和 yida-nav-group 划清（重要）
+
+| 诉求 | 归谁 |
+|---|---|
+| 页面里用 JSX 画侧边/顶部/浮动导航，隐藏应用导航后自建导航 | **本技能 yida-nav-shell** |
+| 管理宜搭应用**左侧菜单树 / 导航分组**：新建/重命名/删除分组、移动排序表单页面、隐藏导航项 | **yida-nav-group**（平台导航，CLI 操作 navUuid） |
+
+用户说「加个导航」时先分清是哪一种：要**平台菜单项**→ nav-group；要**页面内导航组件**（尤其页面已隐藏应用导航）→ 本技能。
+
+## 前置：先确认导航确实隐藏
+
+导航壳的前提是应用导航已隐藏。是否隐藏、以及隐藏时的主色/视觉策略，由 `yida-page-uiux` 的 [Step 0 导航形态判定](../yida-page-uiux/workflow/step-0-nav-shape.md) 决定：
+
+- 发布时 `openyida update-form-config <appType> <formUuid> false "<标题>"`（`isRenderNav=false`），或访问带 `?isRenderNav=false`。
+- 导航**未**隐藏（默认）时无需自建导航壳，应用导航负责跨页跳转——此时一般不用本技能。
+
+## 严格要求（导航壳必做）
+
+1. **先隐藏宜搭原导航**：只要页面内自绘应用级导航壳，就必须在发布后执行 `openyida update-form-config <appType> <shellFormUuid> false "<页面标题>"`，或创建时使用能隐藏导航的模式；不能让宜搭原左侧导航和页面内导航同时出现。
+2. **导航项必须携带 URL 参数**：导航配置不要只存 `formUuid`。每个跨页导航项必须能生成完整 URL，并合并公共参数（至少 `isRenderNav=false`；跨组织场景还要保留 `corpid`；业务深链保留 `tab`、`view`、`dateRange` 等参数）。
+3. **跨自定义页默认走 `custom/{formUuid}?isRenderNav=false`**：隐藏导航壳跳到另一个自定义展示页时，优先拼 `{base_url}/{appType}/custom/{formUuid}?isRenderNav=false`。不要只用 `this.utils.router.push(formUuid, {}, false)`，它容易丢失 `isRenderNav=false`，导致目标页重新出现宜搭原导航。
+4. **表单/数据管理入口分清打开方式**：需要在导航壳内容区展示表单列表时，用 iframe 地址 `workbench/{formUuid}?iframe=true`；必须整页跳转到表单管理时，也要通过统一 URL 构造函数合并当前业务参数，并明确接受目标页可能回到宜搭工作台框架。
+5. **发布后验证最终 URL**：发布完成后至少打开一个带 `?isRenderNav=false` 的导航项 URL，确认目标页没有宜搭原导航，且 URL 参数没有被跳转逻辑吞掉。
+
+## 选型速查
+
+| 形态 | 何时用 | 顶级项数量 | 移动端收敛 |
+|---|---|---|---|
+| **左侧边栏** | 模块多、需常驻导航的后台/门户（最通用 B 端形态） | 5–12，支持分组/二级 | 抽屉（汉堡唤出） |
+| **顶部导航** | 模块少、内容要占满宽度的看板/门户 | 2–6 | 汉堡菜单 |
+| **顶部 + 侧边混合** | 两级结构复杂应用（顶部分域，侧边分子模块） | 顶 2–5 × 侧 3–10 | 顶部汉堡 + 侧边抽屉 |
+| **浮动导航（悬浮胶囊/Dock）** | 沉浸/大屏/展示页，chrome 要极简，导航不常驻 | 3–6 | 底部胶囊/收起 |
+| **标签页** | 一个模块内切同级视图（常叠加在上面几种之上） | 2–8 | 横向滚动标签 |
+
+每种形态的 ASCII 骨架、选中态纪律、移动端收敛、native + Canvas 代码示例、自查清单见 [references/nav-shell-patterns.md](references/nav-shell-patterns.md)。
+
+## 多视图切换机制（导航壳的核心）
+
+导航壳 = 一个自定义页内切多个视图。两条链路：
+
+- **native**：状态存 `_customState.activeView`，点击 `this.setCustomState({ activeView: key })`，`renderJsx` 里按 `activeView` 分支渲染内容区。
+- **Canvas**：`React.useState`，或用 URL hash（`window.location.hash` + `hashchange`，`useEffect` 注册并 cleanup）做可分享/可后退的视图切换。
+- **跨页跳转**：跳到别的自定义页/表单时，用 [field-and-url-reference.md](../../references/field-and-url-reference.md) 的模板拼 URL，并显式合并导航项参数。隐藏导航壳跳自定义页时，目标必须带 `?isRenderNav=false` 保持沉浸；别假设应用导航还在。
+
+### URL 构造模板（native）
+
+```jsx
+var BASE_URL = 'https://www.aliwork.com';
+var APP_TYPE = 'APP_XXX';
+var COMMON_NAV_PARAMS = {
+  isRenderNav: 'false'
+};
+
+var NAV_ITEMS = [
+  { key: 'home', label: '首页', type: 'custom', formUuid: 'FORM-HOME', params: { tab: 'home' } },
+  { key: 'dashboard', label: '经营看板', type: 'custom', formUuid: 'FORM-DASHBOARD', params: { tab: 'dashboard' } },
+  { key: 'orders', label: '订单管理', type: 'workbench', formUuid: 'FORM-ORDERS', params: { iframe: 'true' } }
+];
+
+export function buildQuery(params) {
+  var pairs = [];
+  Object.keys(params || {}).forEach(function(key) {
+    if (params[key] !== undefined && params[key] !== null && params[key] !== '') {
+      pairs.push(encodeURIComponent(key) + '=' + encodeURIComponent(String(params[key])));
+    }
+  });
+  return pairs.length ? '?' + pairs.join('&') : '';
+}
+
+export function mergeParams(baseParams, extraParams) {
+  return Object.assign({}, baseParams || {}, extraParams || {});
+}
+
+export function buildNavUrl(item) {
+  var path = item.type === 'workbench'
+    ? '/' + APP_TYPE + '/workbench/' + item.formUuid
+    : '/' + APP_TYPE + '/custom/' + item.formUuid;
+  var baseParams = item.type === 'workbench' ? {} : COMMON_NAV_PARAMS;
+  return BASE_URL + path + this.buildQuery(this.mergeParams(baseParams, item.params));
+}
+
+export function openNavItem(item) {
+  var url = this.buildNavUrl(item);
+  window.open(url, '_top');
+}
+```
+
+> 如果需要保留当前 URL 上的 `corpid`、`locale` 或业务参数，先从 `this.state.urlParams` 读出白名单字段，合并进 `COMMON_NAV_PARAMS`；不要把不明参数全量透传。
+
+## 纪律（B 端 + 去 AI 味）
+
+- **选中态一眼可辨**：侧边用「左侧 3px 主色条 + 浅色底 + 字重加粗」；顶部用「底部 2px 主色下划线 + 主色文字」，别只靠淡变色。
+- **图标只作功能用途**：功能性内联 SVG + 文字，同页一套风格；**禁 emoji**、禁每项前配装饰图标（详见 [yida-page-uiux 图标纪律](../yida-page-uiux/workflow/step-5-icon-and-assets.md)）。
+- **不做营销脸**：无巨 Logo Hero、无渐变横幅；顶部条放「应用名/模块名 + 面包屑 + 用户」，克制。
+- **主色策略**：导航隐藏时主色相可自立，但要么走品牌 `var(--color-brand1-*)`、要么用自定主色一以贯之；语义色固定。
+
+## 参考文档
+
+| 文档 | 覆盖范围 | 何时阅读 |
+|------|---------|---------|
+| [导航壳形态目录](references/nav-shell-patterns.md) | 五形态 ASCII 骨架 + 选中态 + 移动端 + native/Canvas 代码 + 多视图切换 + 自查清单 | 选定形态、要骨架/代码时 |
+| [yida-page-uiux Step 0](../yida-page-uiux/workflow/step-0-nav-shape.md) | 导航是否隐藏的判定法 + 隐藏时主色/视觉策略分叉 | 动手前确认导航形态时 |
+| [字段与 URL 参考](../../references/field-and-url-reference.md) | 隐藏导航 `isRenderNav=false`、跨页跳转 URL 模板 | 拼跨页跳转 URL 时 |