openyida 2026.9.21 → 2026.9.22-beta.2

package/yida-skills/skills/yida-image-assets/SKILL.md

@@ -1,114 +1,91 @@
 ---
 name: yida-image-assets
 description: >
-  宜搭页面图片准备：每个位置一张图，最多两轮，按页并发采集和交接。
+  宜搭页面需要图片时使用。根据设计槽位选图、上传宜搭图片附件、补齐失败项，输出可按页面使用的 asset-manifest.json。
 ---
 
 # 准备页面图片
 
-按 `design.md.assetStrategy` 准备图片，每页输出 `prd/<项目名>/asset-manifests/<pageId>.json`。
+输入是 `design.md.assetStrategy`，输出是 `prd/<项目名>/asset-manifest.json`。按已有设计准备图片，不改业务需求和视觉方案。
 
-搜索、生图、看图使用当前宿主工具；链接检查、必要的上传和写清单使用 `asset resolve`。Plan 确认后按 `materialize.assetTasks` 启动；Fast 设计就绪即启动。启动前读取已有页面清单，复用符合当前用途与尺寸要求的 final 图片，其余位置接着原轮次处理。
-
-## 后台启动与接收
-
-**先判宿主能力，再决定执行方式，不能把同步 Agent 调用当成后台任务。** 复用 `agent-capabilities --summary-json` 的 `asset_capabilities.background_agent/background_shell/execution`，对照本轮真实工具参数和结果接收能力；宿主名称、任务标题和“并行”话术都不是证据。
-
-| 当前实际能力 | 执行方式 |
-| --- | --- |
-| Agent 支持非阻塞后台派发，立即返回可查询任务编号 | 后台采集该页素材，主流程立即继续业务 |
-| Agent 只有同步调用，但 Bash 支持后台执行 | 可脚本化步骤用后台 Bash；宿主专有搜图、生图、看图判断留在前台分批处理，不整包交给同步 Agent |
-| 两种后台能力均不可用或未能验证 | 先做已获授权的应用/表单创建或复用、范围内种子数据、无图页面及有图页面布局交互，再分批素材；批次间继续独立工作，记录限制 |
-
-QwenWork 优先检查实际 Bash 工具是否提供 `run_in_background`；支持时这是 **Bash 工具参数**，不是 `openyida` CLI 参数。用它后台执行已具备命令入口的搜索、允许的下载上传、`asset resolve`。从 `assetTasks.resolve.argv` 构造命令，路径按实际 shell 正确引用；上传填真实 appType。保存工具返回的任务编号、日志/清单路径和派发返回时间后立刻继续主流程，不紧接着调用等待工具。到所属页面接图时再读取任务状态、退出码和清单；退出码 2 表示仍有素材缺口，不能当成功。宿主若只有轮询就按需查询，不承诺自动通知。
-
-Bash 不能直接执行仅 Agent 可用的搜图/生图/看图工具。后台 shell 只证明可脚本化部分异步，不能据此宣称整条采集链都在后台。普通命令末尾加 `&` 或看到 PID 不足以证明任务能跨工具调用存活、收取结果和取消。只有真实工具核实后才设置 `OPENYIDA_AGENT_BACKGROUND_AGENT` / `OPENYIDA_AGENT_BACKGROUND_SHELL` 为 1/0；未知保持 unknown，CLI 不凭 QwenWork 名称自动放行。
+`asset resolve` 负责下载和上传图片，不负责搜索或生图。搜索、生图、看图由当前宿主工具完成。
 
+## 1. 确定哪些页面需要图片
 
-1. **启动**：应用编排按上述能力决策选择后台工具或业务优先的同步批次，传入当前页设计、`searches`、`draft`、`manifest` 和时间预算。收到真实任务编号后，立即继续创建应用、表单和页面；有图页面先做布局、文字、真实数据绑定和交互。
-2. **记录**：编排负责维护 `taskState`，记录 `taskKey`、`pageId`、`hostTaskId`、`executionMode`、`toolName`、`backgroundOption`、`dispatchReturnedAt`、`status`、`startedAt`、`endedAt`、`firstSearchAt`、`deadlineAt`、各位置已用轮次及输出路径。状态使用 `pending/running/completed/partial/failed`；真实启动后才记为 `running`。executionMode 使用 background_agent/background_shell/synchronous；同步时记录 fallbackReason，复用 final 图片记录 reused 和 reuseEvidence。主流程另外记录 businessWork 的真实 startedAt/endedAt（含时区），收尾汇总至 build-manifest.assetExecution。采集任务独占该页草稿和清单，每轮开始及结束时向编排报告轮次和进度，编排统一保存任务记录。Fast 使用同样规则，任务记录位于页面清单旁的 `<pageId>.task.json`，`taskKey` 使用清单绝对路径。
-3. **复用**：按 `taskKey` 找已有任务，结合宿主状态核对是否仍在运行；运行中接收原任务，已完成则读取清单。恢复中断任务时沿用已用轮次和原截止时间，并核对图片用途、尺寸和当前设计。设计变化时先终止旧任务，确认退出后再交接文件写入权。
-4. **接收**：主流程在当前页接图前读取一次结果；仍在运行时先完成其他独立工作，确需结果时使用宿主等待工具。按该页清单验收真实图片，再发布页面。`completed` 表示清单检查通过，`partial` 表示仍有必需图片缺口；宿主任务结束后由编排回读清单再更新状态。
+读取 `assetStrategy.pages[]`，按 `pageId` 找页面，按 `slotId` 找图片位置。
 
-CLI 的 `assetTasks` 是派发输入，后台执行能力来自宿主。仅支持同步工具时先推进独立业务，再批量调用搜索和检查，完成一批后继续独立业务工作，并记录实际等待；禁止把整包素材放在应用创建之前。用户待办沿用简短阶段名称，图片任务显示为“准备页面图片”，“创建应用”保持独立待办。仅在素材与业务执行区间实际重叠时，进度描述才使用“素材采集&应用创建”；单独采集时写“素材采集”。图片数量、子任务、槽位、编号、轮次和耗时写入内部执行记录。
+| imageNeed | 常见页面 | 怎么做 |
+| --- | --- | --- |
+| `required` | 品牌、营销、商品目录、菜单、封面、作品展示 | 准备设计要求的图片；缺图时该页面保持草稿 |
+| `beneficial` | 门户、工作台、知识库、引导页、空态 | 有槽位就准备图片；没有槽位则跳过 |
+| `none` | 表单、审批、财务、权限、设置、CRUD 台账、统计 | 跳过素材采集，使用图标、图表和排版 |
 
-## 1. 确定哪些页面需要图片
+完整应用必须有设计槽位。设计缺失时交回 `yida-design` 补齐，不用空清单代替。多个图片位置使用不同的 `slotId`；`count > 1` 的展开规则见 [清单契约](references/manifest-contract.md)。
 
-按 `assetStrategy.pages[].pageId` 找页面，按 `slotId` 找图片位置。
+## 2. 检查当前能用的工具
 
-| imageNeed | 怎么做 |
-| --- | --- |
-| `required` | 准备设计要求的图片；缺必需图片时该页保持草稿 |
-| `beneficial` | 有图片位置就准备，没有则跳过 |
-| `none` | 直接使用图标、图表和排版 |
+运行 `openyida agent-capabilities --summary-json`，分别查看 `online_search`、`image_search`、`image_generation`。
 
-设计缺失时交回 `yida-design` 补齐。每个位置一个 `slotId`、一张图，`count` 省略或填 `1`。
+- `unavailable`：跳过这项能力。
+- `unknown` 或 `requires_host_tool_inventory_check=true`：检查当前宿主工具清单。
+- `available`：使用实际存在的对应工具；若工具不存在，按不可用处理。CLI 的运行环境默认值不能代替工具调用结果。
 
-## 2. 检查工具
+没有搜图或生图能力时，使用用户已提供的素材；仍缺图就记录缺口，继续不依赖这些图片的页面。
 
-复用当前环境的能力查询结果；尚未查询时运行 `openyida agent-capabilities --summary-json`，查看 `online_search`、`image_search`、`image_generation`。
+## 3. 选图并查看
 
-- `unavailable`：跳过。
-- `unknown` 或 `requires_host_tool_inventory_check=true`：查看宿主实际工具清单。
-- `available`：使用实际存在的工具；工具缺失则按不可用处理。
+按以下顺序准备每个槽位：
 
-工具不可用时复用用户图片，记录剩余缺口，继续其他页面。
+1. 用户提供的本地图片或图片链接，记录 `source=user`。
+2. 从 **Unsplash / Pexels** 搜索，记录 `source=search`。图库采集仅支持这两个网站。
+3. 槽位允许生成、且宿主有生图工具时生成图片，记录 `source=generated`、`isIllustrative=true`。
+4. 仍无合适图片时保留缺口。可用中性占位说明缺图，但不能把占位记为已完成素材。
 
-## 3. 最多两轮，按页面并发
+查看实际图片，确认内容、比例、清晰度和主体位置适合槽位。商品、房源、人员、案例图片表达业务事实，不能用生成图冒充真实对象。
 
-优先用用户图片，其次搜索 **Unsplash / Pexels**；设计允许示意图时可用宿主生图。来源填写 `source=user|search|generated`，生成图标记 `isIllustrative=true`。
+采集图库素材前读 [来源规则](references/source-policy.md)：图库图片保留来源页、摄影师、许可、署名和真实下载动作记录。只选择允许下载和转存的图片。不编造图片 URL、来源或下载记录。
 
-1. **第一轮**：批量找图，每个位置选一张信息齐全的图片，查看合适后交给 CLI 检查，允许外链就直接使用。
-2. **第二轮**：只补第一轮失败的必需位置，每个位置换一张；允许示意图时可改用生图。
-3. **结束**：可选位置用设计允许的无图布局，必需位置保留缺口。用户后续明确要求补图时再继续。
+## 4. 写草稿并上传
 
-每页最多两轮，每个位置每轮最多一个候选，同一候选尝试一次。一轮包括选图、看图、来源记录、链接检查和必要的上传。换来源、换工具或恢复上传都接着当前轮次。Agent 记录各页轮次、失败位置和不可用来源。
+按 [清单契约](references/manifest-contract.md) 写 `manifest-draft.json`。每项填写 `slotId`、`input`、`source`、`alt` 和对应来源信息；尺寸由 CLI 实际读取，不靠手填宽高通过校验。
 
-各页及同页各图片位置同时搜索，整次采集共用最多四个在途请求，完成一个就补下一个；使用宿主批量并发调用或并行任务。每个位置返回选图和来源，由该页唯一写入者组装草稿，CLI 并发检查图片，仅需托管的图片下载上传。记录请求起止时间确认实际重叠。主流程同时创建应用、表单和无图页面；有图页面先做布局与交互，接图和验收时汇合。
+```bash
+openyida asset resolve --input <草稿> --manifest <asset-manifest.json> --design <design.md> --app-type <真实appType> --json
+```
 
-调度先处理必需位置，同级优先 `usage=hero`，其余保持设计顺序；首屏其他图片按实际用途由编排优先派发。四个搜索名额由编排统一分配给各页，后台任务按分配额度执行。
+上传前需要有效宜搭登录态和目标应用 `appType`。已有应用直接使用；尚未创建应用时先选图、保存草稿，等应用创建后再执行上传。不编造 appType。省略 `--app-type` 时 CLI 读取当前项目 `config.json.appType`。
 
-默认单次搜索或来源信息查询最多 30 秒，每页从首次实际发起搜索起共用 3 分钟采集预算，排队时间另记。宿主负责传入超时、设置截止时间并在到期时停止采集；恢复任务沿用原截止时间。工具无法中断时记录限制，并让主流程继续独立工作。两轮或时间预算任一耗尽即收口：已取得候选完成检查，可选位置采用设计允许的无图布局，必需位置记录缺口；已验证结果保留。用户明确指定时限时沿用用户要求。
+默认按以下规则落地，不需要配置自有 CDN，也不需要加 `--upload-assets`：
 
-### 失败后立即切换
+1. **不超过 20 MiB（20 × 1024 × 1024 字节）**：外链先下载，本地图直接使用；通过宜搭 `ImageField` 附件上传，取得公开图片链接后直接写入清单，不再额外请求原图或上传地址做可用性校验。
+2. **超过 20 MiB**：外链保留原始 `input` 链接，不上传。CLI 检查响应大小和实际下载大小；下载中超过限制立即停止并清理临时文件。
+3. **大于限制的本地图**：没有原始外链可回退，保持 `draft`；补原始图片 URL 或换成较小图片。
+4. **下载失败**：跳过该素材，不重试、不上传、不回退失败外链；记录缺口，需要时换图。登录或上传失败同样记录缺口，不把临时签名链接当公开链接。
 
-搜索入口出现 401、403、429、反爬挑战或超时，立即切换可用来源；其他页面和后续轮次复用这份记录。已取得的独立图片直链按自身检查结果处理。图片直链失效、返回验证网页、尺寸不足或来源信息缺失时，在剩余轮次内换图。
+`--design` 核对全部设计槽位、页面归属和最小尺寸。漏项自动成为缺口，重复或未声明的槽位会报错。格式和尺寸从本次下载内容读取，来源从草稿记录读取，不额外联网校验。
 
-查看实际图片的内容、比例、清晰度和主体位置。商品、房源、人员、案例使用真实图片。来源记录和使用条件见 [来源规则](references/source-policy.md)。
+## 5. 处理结果和补图
 
-## 4. 检查图片并写入清单
+- 退出码 `0`：本次清单为 `final` 或 `none`。
+- 退出码 `2`、`ASSET_MATERIAL_NOT_FINAL`：清单已写入，但仍有缺口。读取 `gaps`，只修失败项；其他错误先修参数或输入文件。
+- 缺原图就补 `input`，尺寸不够就换图，缺来源信息就补真实记录；不要手动改状态为 `final`。
 
-按 [清单契约](references/manifest-contract.md) 写每页草稿。每张图片同时记录已取得的图片 ID、作者、来源页、许可链接、实际核对日期及必要授权凭证，字段见[来源与授权留证](references/manifest-contract.md#来源与授权留证)：
+修改上次清单中的失败项后重跑：
 
 ```bash
-openyida asset resolve --input asset-manifests/<pageId>.draft.json --manifest asset-manifests/<pageId>.json --design design.md --page-id <pageId> --json
+openyida asset resolve --input asset-manifest.json --manifest asset-manifest.json --design design.md --app-type <真实appType> --json
 ```
 
-页面草稿就绪即可执行。直链检查无需登录或等待应用创建；上传时追加 `--app-type <真实appType>`，省略时读取项目配置。
-
-允许外链的图片经格式和尺寸检查后直接使用。用户或生成的外链经核实后填 `hotlinkAllowed=true`；本地图片和需托管的图片在允许转存时上传，最大 20 MiB。上传失败时保留已验证且允许外链的原地址。访问失败的图片记录缺口，按两轮规则换图。
-
-## 5. 处理结果
-
-- 退出码 `0`：清单为 `final` 或 `none`。
-- 退出码 `2`、`ASSET_MATERIAL_NOT_FINAL`：清单已保存，按 `gaps` 找缺口。
-- 其他错误：按错误修正参数或文件。
-
-第二轮修改失败位置的 `input`，将该页清单同时作为 `--input` 和 `--manifest`。CLI 在原图内容未变时复用附件链接。字段、尺寸及错误处理见清单契约。
+清单保留原始输入和尺寸要求。CLI 在原图内容未变时直接复用已有宜搭附件链接，不额外联网探测。更换素材时修改 `input`，不要只修改输出 `url`。`--offline` 不联网、不上传，离线处理的图片仍保持草稿。
 
 ## 6. 交给页面使用
 
-素材采集完成后直接继续搭建，沿用已有方案确认。读取该页清单的 `pages[].materialStatus`；已有总清单 `asset-manifest.json` 按 `pageId` 读取。
-
-- `final`：该页可继续，只使用 `assets[].materialStatus=final` 的图片 URL。
-- `draft`：该页缺必需图片；剩余轮次内补图，用尽则保留缺口，其他页面继续。
-- `none`：该页直接继续。
-
-可选图片失败时采用设计允许的无图布局。根状态只表示当前清单的整体结果。
+读取 `pages[]` 中当前 `pageId` 的 `materialStatus`：
 
-页面任务只写自己的清单。需要更新 PRD/design 时，由应用编排汇总后统一处理：
+- `final`：当前页面可继续；只使用该页 `assets[]` 中 `materialStatus=final` 的图片 URL。
+- `draft`：当前页面仍缺必需素材，先补图。
+- `none`：当前页面没有图片槽位，直接继续。
 
-- **Plan**：更新 `visualStyle.forUser.assetStrategy.materialStatus` 和 `missingAssets`，执行一次 `design-plan patch --set ... --materialize --json`。CLI 保留 revision 与已有确认，生成的文档直接用于开发。
-- **Fast**：直接更新文档中的素材进度。
+根级 `materialStatus` 表示全部素材是否齐备。它是 `draft` 时，已为 `final` 的页面仍可继续。`required=false` 的槽位失败不阻塞页面，但该图片不能使用；采用设计允许的无图布局。
 
-功能、页面结构或整体风格变化时交回规划技能。交付时说明哪些页面可以继续、哪些页面缺什么图。
+交付时说明：哪些页面已就绪、哪些页面缺图、每个缺口需要补什么。上传成功后，仍要确认图片内容适合页面。

package/yida-skills/skills/yida-image-assets/references/manifest-contract.md

@@ -2,7 +2,7 @@
 
 ## 设计槽位
 
-Fast 和 Plan 在 `design.md` 的 frontmatter 保留主题等字段，并用一行 JSON 写 `assetStrategy`：
+Fast 和 Plan 都在 `design.md` 的 frontmatter 中写一行 JSON 格式的 `assetStrategy`。例如：
 
 ```yaml
 ---
@@ -10,108 +10,78 @@ assetStrategy: {"pages":[{"pageId":"home","imageNeed":"required","slots":[{"slot
 ---
 ```
 
-- 每页有唯一 `pageId`、`imageNeed` 和 `slots`，每个位置有唯一 `slotId` 和 `usage`。
-- 每个位置一张图，`count` 省略或填 `1`。旧计划的 count>1 仍展开为独立位置。
-- `required` 默认 true；设计允许无图布局时可设 false。
-- `minSize` 为 `宽x高`，也可填非负整数 `minWidth/minHeight`。CLI 使用设计和草稿中较高的尺寸要求。
-- `generationAllowed=false` 只接受真实素材。
-- `imageNeed=none` 省略 slots 时 CLI 补空数组；required/beneficial 页面显式填写 slots。Plan 生成方案时即校验位置、用途和尺寸；required 页面空 slots 时保持 draft。
+实际文件保留原有主题等 frontmatter 字段。CLI 的 `--design` 读取这行 JSON；不要改成多行 YAML 对象。
 
-## 输入草稿
-
-```json
-{"assets":[{"slotId":"home.hero","usage":"hero","input":"./assets/home.png","source":"user","alt":"团队讨论方案"}]}
-```
-
-`input` 使用实际本地文件或 HTTP(S) 图片地址。相对路径基于命令工作目录，跨目录处理使用绝对路径。NOT_FOUND 返回 resolvedPath 与 baseDir，核对实际查找位置后修正 input；这类文件路径修正直接重跑该页素材任务。
-
-| source | 来源字段 |
-| --- | --- |
-| user | 保留用户图片的用途 |
-| generated | isIllustrative=true，查看实际图片 |
-| search | provider=unsplash 或 pexels，填写 sourcePage、creator、license、attribution |
-| Unsplash 搜索结果 | 实际完成下载动作记录后填写 downloadLocation、downloadTracked=true |
-
-### 来源与授权留证
+- 每页必须有唯一 `pageId`、`imageNeed` 和 `slots` 数组；每个槽位必须有唯一 `slotId` 和 `usage`。
+- 一个槽位对应一张图。`count` 默认 `1`；若为 `3`，CLI 展开为 `slotId[0]`、`slotId[1]`、`slotId[2]`，草稿使用展开后的 ID。`count` 支持 1–100。
+- `required` 默认 `true`。仅在设计允许无图布局时设为 `false`。
+- `minSize` 格式为 `宽x高`，如 `1600x900`；也可写非负整数 `minWidth/minHeight`。草稿不能降低设计的最小尺寸。
+- `generationAllowed=false` 的槽位不接受 `source=generated`。
+- `imageNeed=none` 的页面写空 `slots`；`required` 页面没有槽位时保持 `draft`。
 
-在每张图片的 `assets[]` 记录中填写下列信息，通过 `--input` 传入。CLI 将它们保留在输出清单和 JSON 结果中；图片检查失败、离线执行或用清单重试时也会保留。
-
-| 字段 | 填写内容 |
-| --- | --- |
-| assetId | 来源网站的图片 ID；用户素材使用已有内部编号，无编号留空。与页面位置 slotId 区分。 |
-| creator | 作者或权利人，沿用已有字段 |
-| sourcePage | 对应图片的官方详情页或用户提供的来源页，沿用已有字段 |
-| license | 许可名称或已取得的授权说明，沿用已有字段 |
-| licenseUrl | 实际核对的许可条款 HTTP(S) 链接 |
-| licenseCheckedAt | 实际核对许可的日期，格式 YYYY-MM-DD；CLI 不自动填今天 |
-| authorizationEvidence | 必要授权凭证的链接或文件路径数组，如购买凭证、人物或场地产权授权；本地凭证建议使用项目内可持续保留的绝对路径 |
+## 输入草稿
 
-例如，已取得用户图片授权时，可在该图片记录中补充以下字段（示例值需替换为真实记录）：
+根字段为 `assets` 数组。用户图片和生成图片只需基础字段；图库图片还要填写来源信息。
 
 ```json
 {
-  "assetId": "company-team-001",
-  "creator": "公司摄影团队",
-  "sourcePage": "https://example.com/media/company-team-001",
-  "license": "公司授权用于本项目官网",
-  "licenseUrl": "https://example.com/media/usage-terms",
-  "licenseCheckedAt": "2026-09-18",
-  "authorizationEvidence": ["/project/assets/licenses/company-team-001.pdf"]
+  "assets": [{
+    "slotId": "home.hero",
+    "usage": "hero",
+    "input": "./assets/home-hero.png",
+    "source": "user",
+    "alt": "团队在会议室讨论方案"
+  }]
 }
 ```
 
-未取得的信息留空：文本字段为 `""`，凭证列表为 `[]`；不要编造图片 ID、核对日期或凭证。换图时同步更新这些记录，不能沿用上一张图的授权信息。CLI 检查新增字段的类型、许可链接格式和日期格式，不访问凭证或判断授权是否有效。`final` 仍表示图片满足现有素材就绪检查，不代表已认证可商用。
+`input` 可用本地路径或 HTTP(S) 图片 URL。本地相对路径相对于运行命令的工作目录；跨目录重跑使用绝对路径。不要写搜索结果页、网页地址或未生成的文件路径。
 
-## 按页面执行
+| source | 额外字段 |
+| --- | --- |
+| `user` | 用户提供的图片；保留实际用途 |
+| `generated` | `isIllustrative=true`；查看实际生成结果 |
+| `search` | `provider` 仅 `unsplash` 或 `pexels`；填写 `sourcePage`、`creator`、`license`、`attribution` |
+| Unsplash 搜索结果 | 另填 `downloadLocation`、`downloadTracked=true`；只有真实完成下载动作记录后才能写 true |
 
 ```bash
-openyida asset resolve --input asset-manifests/home.draft.json --manifest asset-manifests/home.json --design design.md --page-id home --json
+openyida asset resolve --input manifest-draft.json --manifest asset-manifest.json --design design.md --app-type <真实appType> --json
 ```
 
-完整应用带 `--design` 校验槽位。`--page-id` 只处理指定页；省略时处理整份清单。各页使用不同的 `--manifest` 文件，同时运行、独立交接。第二轮更新失败项 input，再将页面清单同时作为输入和输出。轮次和并发规则见 [主流程](../SKILL.md#3-最多两轮按页面并发)。
+完整应用始终带 `--design`，以最新设计为准。独立检查单张图片可以省略 `--design`，但它只证明传入素材的状态，不证明应用槽位齐备。`--slot home.hero=<路径或URL> --source user` 适合快速检查，缺少用途、alt 等元数据时仍为 `draft`。
 
-独立图片可用 `--slot home.hero=<图片> --source user` 检查；这只验证传入图片，完整应用仍需设计槽位校验。
+图片默认下载后上传宜搭 `ImageField` 附件，再换取公开链接；下载前后和上传后均不额外发送 URL 探测请求。`input` 始终保留原图，`url` 是页面使用的最终链接；上传不改变 `source` 的来源分类。超过 20 MiB 的外链直接保留 `input`，不用上传；20 MiB 整仍上传。`--upload-assets` 仅兼容旧命令，已无需手动指定。
 
-## 链接检查与上传
+## 输出和重跑
 
-- `deliveryMode=auto`（默认）：允许外链的 HTTP(S) 图片经一次检查后直接使用。检查最多读取 128 KiB，核对真实格式和尺寸；内容、构图与用途由宿主看图确认。
-- `hotlinkAllowed`、`rehostAllowed` 为布尔值，分别表示允许外链展示、允许转存。搜索得到的 Unsplash/Pexels 官方图片直链默认允许外链，Unsplash 默认仅用直链。其他来源沿用已核实的转存许可，允许外链时显式填 `hotlinkAllowed=true`；明确禁止转存时填 `rehostAllowed=false`。
-- 本地图片上传宜搭附件；`deliveryMode=upload` 或命令 `--upload-assets` 请求上传允许转存的外链。上传最大 20 MiB，需要登录态和真实 appType，可通过 `--app-type` 指定或读取项目配置。
-- 上传失败或图片超出上传限制时，只有已验证且允许外链的原地址可以继续使用；其他情况记录缺口。返回验证网页、403、超时或尺寸不足的地址按失败处理。
-- input 保留原图，url 保存最终链接，source 保留来源分类；许可和 deliveryMode 随清单保留。原图内容相同时复用已有附件，上传流程直接复用下载内容的检查结果。
-- `--offline` 关闭联网和上传，图片保持 draft。
-
-## 输出
-
-`schemaVersion=2`：
+输出 `schemaVersion=2`：
 
 | 字段 | 含义 |
 | --- | --- |
-| materialStatus | 本文件内素材的总状态：final/draft/none |
-| assetStrategy | 本次设计要求；重跑保留，传 --design 时以设计文件为准 |
-| pages[] | pageId、imageNeed、slotIds、materialStatus、gaps |
-| assets[] | input、url、页面/位置 ID、用途、尺寸、来源、alt、materialStatus、gaps |
-| assets[].assetId / creator / sourcePage / license / licenseUrl / licenseCheckedAt / authorizationEvidence | 图片编号、作者、来源页、许可名称、许可链接、核对日期和授权凭证记录；未提供的值留空 |
-| assets[].delivery | CLI 生成的交付记录；yida-attachment 表示上传，external 表示已验证的直链；reason=OK_DIRECT 表示直接交付，其他 reason 保留上传失败或超限原因 |
-| gaps | 缺口及错误码，按 pageId/slotId 定位 |
-| capabilityEvidence | 宿主能力、uploadTarget、maxUploadBytes、online；cdnConfigured 是旧兼容字段 |
+| `materialStatus` | 全部素材的总状态：`final` / `draft` / `none` |
+| `assetStrategy` | 本次设计要求；重跑时保留。再次传 `--design` 时以设计文件覆盖 |
+| `pages[]` | 每页的 `pageId`、`imageNeed`、`slotIds`、`materialStatus`、`gaps` |
+| `assets[]` | 每张图的原始 `input`、页面/槽位 ID、尺寸要求、来源信息、实际宽高、落地 URL、`materialStatus`、`gaps` |
+| `assets[].delivery` | CLI 生成的交付记录，用于内容比较和宜搭附件复用；`source=yida-attachment` 表示上传，`source=external` 且 `reason=ASSET_TOO_LARGE` 表示超限保留原链接；保留原样，不手工构造 |
+| `gaps` | 全部缺口，按 `pageId/slotId` 定位 |
+| `capabilityEvidence` | 宿主能力声明、`uploadTarget`、`maxUploadBytes` 和本次联网开关；旧 `cdnConfigured` 仅兼容字段，不决定上传能力 |
+
+每张图取得公开 URL（或超限时保留原链接）、实际尺寸及所需元数据齐全时才为 `final`。不支持解析的格式或无法读取尺寸的图片保持 `draft`，应换成可验证的 PNG、JPEG、WebP 等格式。
 
-取得已验证的图片直链或附件公开 URL、实际尺寸和完整来源信息后，图片才为 final。页面必需位置全部 final 即可继续，可选缺口仍保留在 gaps。旧清单可继续使用，缺原始 input 时先补齐。
+页面必需槽位全部为 `final` 时页面可继续；可选槽位失败仍记录缺口，但不阻塞页面。根状态保留 `draft`，便于继续补图。
 
-## 常见缺口
+缺图后可以直接编辑输出清单，再把它同时作为 `--input` 和 `--manifest`。失败项保留原始 `input` 和尺寸要求；成功项在原图内容未变时直接复用附件链接。旧版清单仍可作为输入，但缺失的原始输入需人工补齐，首次重跑不保证复用旧上传结果。
 
-| 错误 | 处理 |
+| 缺口/错误 | 处理方式 |
 | --- | --- |
-| EMPTY / NOT_FOUND | 补实际图片路径或地址 |
-| INVALID_IMAGE_CONTENT / NOT_IMAGE_FILE / DIMENSIONS_UNAVAILABLE | 换可读取尺寸的 PNG、JPEG、WebP 等真实图片 |
-| WIDTH_TOO_SMALL / HEIGHT_TOO_SMALL | 换更大图片 |
-| MISSING_METADATA | 补用途、alt、已取得的来源记录；获取失败则换图 |
-| ASSET_APP_TYPE_REQUIRED | 上传时填真实 appType |
-| REHOST_NOT_ALLOWED | 使用允许外链的原地址，或换可转存的图片 |
-| ASSET_TOO_LARGE | 换小图；允许外链时保留已验证原地址 |
-| ASSET_TOO_LARGE_NO_ORIGINAL_URL | 补原始外链或换小图 |
-| ASSET_ATTACHMENT_URL_INVALID | 检查公开链接转换结果 |
-| ASSET_DUPLICATE_SLOT / ASSET_UNDECLARED_SLOT | 对齐设计位置 ID |
-| MISSING_PAGE_SLOTS / ASSET_DESIGN_INVALID | 修正设计槽位 |
-| ASSET_PAGE_REQUIRES_DESIGN / ASSET_PAGE_NOT_FOUND | 提供设计并核对 pageId |
-| 下载、登录、上传错误 | 在剩余轮次内补必需图片，用尽后保留缺口 |
+| `EMPTY` / `NOT_FOUND` | 补正确的图片输入路径或 URL |
+| `INVALID_IMAGE_CONTENT` / `NOT_IMAGE_FILE` / `DIMENSIONS_UNAVAILABLE` | 换成可读取格式与尺寸的真实图片；不要手填宽高绕过 |
+| `WIDTH_TOO_SMALL` / `HEIGHT_TOO_SMALL` | 换更大图片 |
+| `MISSING_METADATA` | 按缺失字段补用途、alt 或真实来源记录 |
+| `ASSET_APP_TYPE_REQUIRED` | 传入真实 `--app-type`，或在当前项目配置 appType |
+| `ASSET_TOO_LARGE_NO_ORIGINAL_URL` | 本地图超过 20 MiB，补原始图片 URL 或换小图 |
+| `ASSET_ATTACHMENT_URL_INVALID` | 上传接口未返回 HTTP(S) 公开链接，排查转换接口；不使用签名下载地址 |
+| `ASSET_DUPLICATE_SLOT` / `ASSET_UNDECLARED_SLOT` | 修正槽位 ID，使其与设计一致 |
+| `MISSING_PAGE_SLOTS` / `ASSET_DESIGN_INVALID` | 回到设计阶段补齐或修正 `assetStrategy` |
+| 下载错误（如 `HTTP_404`、`TIMEOUT`） | 本次跳过，不上传、不使用原链接；需要该图时换 `input` |
+| 登录、上传、离线错误 | 恢复相应能力后，用保留的原始输入重跑 |

package/yida-skills/skills/yida-image-assets/references/source-policy.md

@@ -1,18 +1,19 @@
-# 图片来源规则
+# 图片来源与落地规则
 
-采集前核对来源的使用条件，优先选允许外链展示的图片；需要托管时选允许转存的图片。
+选图时使用；上线前核对官方条款。
 
-| 来源 | 记录与使用 |
-| --- | --- |
-| 用户图片 | 保留用途和授权信息 |
-| 生成图片 | 用于背景、空态、示意图，查看后标记 isIllustrative=true |
-| [Unsplash API](https://help.unsplash.com/en/articles/2511245-unsplash-api-guidelines) | 使用 API 返回的 photo.urls 图片直链并保留署名，实际请求 download_location 后记录选用动作 |
-| [Pexels API](https://www.pexels.com/api/documentation/) | 使用 API 返回的图片直链，保留来源页和摄影师署名 |
+| 来源 | 搜索/使用规则 | 页面落地 |
+| --- | --- | --- |
+| 用户提供 | 确认使用权，保留用途说明 | 本地图直接上传宜搭附件；授权外链下载后上传，不改变真实对象含义 |
+| Agent 生成 | 用于背景、抽象视觉、空态和示意图 | 查看后上传；标记 `isIllustrative=true` |
+| [Unsplash API](https://help.unsplash.com/en/articles/2511245-unsplash-api-guidelines) | 保留署名；API 选用时请求 `download_location`，遵守对应获取方式的使用条款 | 选取允许下载和转存的素材，再上传宜搭附件 |
+| [Pexels API](https://www.pexels.com/api/documentation/) | 保留 Pexels 链接，尽可能署名摄影师 | 下载后上传宜搭附件 |
 
-搜索图片填写 `source=search`、`provider=unsplash|pexels`，记录 sourcePage、creator、license、attribution；Unsplash 另记 downloadLocation、downloadTracked。用户外链使用 source=user。取得图片 ID、许可链接、核对日期及必要授权凭证后，按[来源与授权留证](manifest-contract.md#来源与授权留证)写入同一张图片的记录，不另建清单，也不把未知信息写成已授权。
+## 通用门禁
 
-失败来源按 [失败后立即切换](../SKILL.md#失败后立即切换) 记录，所有页面共用。换来源、恢复服务仍计入两轮上限。
-
-查看实际图片：背景保证文字清晰，商品图用 contain，场景图用 cover 并确认主体位置；品牌、人物和真实业务对象保留授权及真实关系。
-
-链接检查和上传见 [清单契约](manifest-contract.md#链接检查与上传)。Unsplash API 图片按[官方规则](https://help.unsplash.com/en/articles/2511271-guideline-hotlinking-images)直接展示；另行获得转存许可时才填写 `rehostAllowed=true`。用户和生成的外链，核实允许公开展示且地址长期可用后填写 `hotlinkAllowed=true`；仅允许转存时填写 `hotlinkAllowed=false`，明确禁止转存时填写 `rehostAllowed=false`。
+- 记录 `provider/sourcePage/creator/license/attribution`；Unsplash 另记 `downloadLocation/downloadTracked`。
+- 搜索素材使用 `source=search`，只接受 `provider=unsplash|pexels`；用户授权外链使用 `--source user`。
+- 品牌、人物和敏感场景记录授权与真实关系。
+- 背景图检查文字对比度；商品图用 `contain`；场景图用 `cover` 并记录焦点。
+- 默认上传宜搭图片附件；外链超过 20 MiB 才保留原链接。下载失败直接跳过并记录缺口；上传失败保持草稿。
+- API 或具体授权要求热链且不允许转存时，改选允许转存的素材；不要把更换托管地址当作取得授权。

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

@@ -421,7 +421,6 @@ openyida integration diagnose --file project/tickets/automation-error.txt --json
 - 流水号：新增/编辑触发时，触发 payload 中的流水号可能为空或不是最新值；需要先获取自身，再引用获取节点里的流水号。
 - 定时自动化：定时触发值可能是历史数据；需要最新值时先获取自身或获取目标数据。
 - 直接更新：匹配字段只能消费当前触发表字段，不能随意匹配前置节点字段；文本字段不要匹配单选/多选字段。直接更新不会触发被更新表单上的集成自动化。
-- 跨应用写入不级联触发（阻塞项）：A 应用表单的集成自动化通过内置新增/编辑/删除数据节点写 B 应用表单（跨应用）时，B 表单上已配置的新增/编辑/删除自动触发集成业务流不会生效。涉及跨应用链式联动时这是阻塞项，不得假设 B 表自动化会被接力触发。
 - 条件分支：空值判断优先用公式 `ISEMPTY()`，不要只依赖“没有值”选项。
 - 异常重试：重试通常会从头执行，已执行过的新增/更新节点可能再次写入或覆盖数据；重试前先确认幂等性。
 

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

@@ -56,8 +56,6 @@ openyida auth refresh
 openyida auth logout
 ```
 
-生成新命令统一使用 `openyida auth profiles --json`。CLI 同时兼容旧写法 `openyida auth profile list --json`，两者都只查询，不切换组织或登录态。
-
 ## Profile 选择原则
 
 - 当前已有多个 profile 且 snapshot 返回 `profile_required` 时，不要根据目录、组织名片段或最近操作猜测组织。

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

@@ -1,6 +1,6 @@
 ---
 name: yida-nav-group
-description: 整理宜搭已有的导航菜单时使用。支持查看菜单、新建或调整分组、移动和排序页面、隐藏或显示菜单项。
+description: 宜搭应用左侧导航分组管理。查询导航树、新建/重命名/删除分组、移动或排序表单/页面/外链、隐藏或显示导航项。
 ---
 
 # 应用导航分组
@@ -13,15 +13,13 @@ description: 整理宜搭已有的导航菜单时使用。支持查看菜单、
 - **完整应用排序时机**：等待本轮全部页面开发、发布及资源创建完成，再统一执行一次排序；逐页发布不使用 `--auto-nav-order`。用户单独要求调整已有导航时直接按本次要求执行。
 - **PRD 导航优先**：PRD 写明页面/表单清单顺序时，使用 `openyida nav-group order <appType> <页面/表单...>`；PRD 只写宽泛分组或缺少导航顺序时，使用 `openyida nav-group auto-order <appType>` 或发布命令的 `--auto-nav-order` 兜底。两种排序互斥，同一 Run 只执行一次，不生成逐项 `move` 循环。
 - **兜底自动排序优先级**：门户/首页/工作台入口 > 自定义展示页面 > 流程表单 > 普通表单。这是工具兜底顺序，不替代 PRD 导航顺序。
-- **默认原则：面向决策者的总览/驾驶舱看板作为应用门面靠前，数据录入/明细表单在其后。** 仅适用于已确认的管理概览需求，不自动创建首页，也不将独立访客首页混入管理端。判断某个看板是否靠前，看它是不是主要「查看/决策」入口：
+- **默认原则：面向决策者的总览/驾驶舱看板作为应用门面靠前，数据录入/明细表单在其后。** 判断某个看板是否靠前，看它是不是主要「查看/决策」入口：
   - 有独立总览首页看板时：`总览首页看板 → 专题看板 → 核心业务表单 → 明细/配置表单`。
   - 没有独立首页、专题看板本身就是主要决策视图时（如「双11看板/618看板」面向运营主管只读查看）：这些**专题看板靠前**，数据录入/明细表单在后。
 - "不要无脑把看板全置顶"针对的是：当存在明确操作旅程（先录入后查看）、且看板只是次要报表时，按旅程排；不要把与主流程无关的次要看板也塞最前。多数带看板的应用，决策看板应先于录入表单。
 - 删除分组默认只删除空分组；非空分组必须先移动子项，除非用户明确要求 `--force`。
 - 分组节点是 `navType: "NAV"`，普通页面是 `navType: "PAGE"`，外链是 `navType: "LINK"`，系统节点不要移动或删除。
 
-前后台双入口的排序以 [访问态入口契约](../yida-app/references/entry-navigation.md) 的管理菜单为准；auto-order 不理解业务身份，不能用于双入口的管理菜单决策。隐藏项同时影响共享平台菜单，不是按角色隐藏，也不是权限拒绝。
-
 ## 命令
 
 ### 查询导航树

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

@@ -1,20 +1,19 @@
 ---
 name: yida-nav-shell
-description: 为应用或独立前台页面制作自己的导航菜单时使用。只做前台菜单时，保留管理端的宜搭导航；整个应用都使用自定义菜单时，再隐藏应用导航。
+description: 自定义页明确要自绘应用级导航时使用；先隐藏应用导航 hideAppNav。页面级 isRenderNav=false 不等于应用导航隐藏。
 ---
 
 # yida-nav-shell
 
 ## 先判断
 
-先看需求和方案：是要制作自己的菜单，还是只整理宜搭已有的菜单？前者使用本技能，后者使用 `yida-nav-group`。同一个应用可以让前台使用自己的菜单、管理端继续使用宜搭菜单。用户已有明确要求时直接沿用；尚未确定时按 [导航决策](../yida-design/references/navigation-decision.md) 选择。
+默认不用本技能。宜搭应用的页面切换优先交给平台导航和 `yida-nav-group`。
 
 | 用户需求 | 怎么处理 |
 | --- | --- |
 | 导航分组、页面排序、隐藏/显示导航项 | 用 `yida-nav-group` |
 | 页面内 tab、分段、筛选、卡片切换 | 当前页内容结构，不用本技能 |
-| 独立前台要自己的顶部/侧边菜单 | 用本技能，只配置该页面独立展示，后台保留平台导航 |
-| 整个应用采用自绘应用级导航 | 用本技能，按应用级范围隐藏应用导航 |
+| 自定义页要顶部导航、侧边导航、导航壳、自绘应用级导航 | 用本技能，并先隐藏应用导航 |
 | 用户只说隐藏应用导航 | 执行 `update-app --hide-app-nav`；需要自绘导航时再用本技能 |
 | 用户只说全屏、无导航、`isRenderNav=false` | 这是页面级隐藏，优先用 `yida-page-config` |
 
@@ -25,58 +24,36 @@ description: 为应用或独立前台页面制作自己的导航菜单时使用
 - 不要用 `isRenderNav=false` 代替 `hideAppNav`。
 - 不要让平台应用导航和自绘应用级导航同时出现。
 
-平台导航下的管理页只实现业务内容，不默认使用本技能或导航壳片段；同任务分类使用页内 Tab，跨模块由平台菜单切换。管理入口的任务清单不等于页面菜单，详见[管理页面边界](../yida-canvas-custom-page/references/navigation-and-entry-guide.md#平台导航下的管理页面)。
-
 ## 必做配置
 
-先读 PRD 的应用 `navigationType` 与当前页 `pageSpecHandoff.entryMode/navigation`，分别处理：
-
-### 仅独立前台菜单
-
-需要让应用管理员返回业务管理时，使用 [管理员工作台入口](../yida-canvas-custom-page/references/navigation-and-entry-guide.md#管理员返回业务工作台) 的 `canvas-admin-entry`，放在导航操作区并跟随主题。按当前访问者与当前应用的身份展示，指向真实业务管理页面；这只是访问态入口，不是开发后台按钮，不自动授予或调整管理员权限。
-
-应用为 platform-top/platform-side/platform-l-shape、当前页为 standalone 时，只对该页面执行下面的 `update-form-config` 和回读；不调用 `update-app --hide-app-nav`，不批量隐藏后台表单或其他页面。需要应用级主题更新时继续保留平台导航。发布后分别验证前台页面链接与后台 workbench 链接；前台仍出现平台菜单时，先排查实际访问路径与页面配置，不能通过全局隐藏“修复”。
-
-### 整个应用自定义导航
-
-需求规划采用自定义导航后，就将应用导航隐藏纳入应用基础设置更新：新建应用时，等 `app-theme.css` 生成后，将 `--hide-app-nav` 与主题、Logo、布局等设置合并到同一次 `update-app`，按 [应用设置同步](../yida-app/workflow/step-3-create-or-reuse-app.md) 执行并回读。已有应用只需切换导航时执行：
+用户确认自定义导航后，就将应用导航隐藏纳入应用基础设置更新：新建应用时，等 `app-theme.css` 生成后，将 `--hide-app-nav` 与主题、Logo、布局等设置合并到同一次 `update-app`，按 [应用设置同步](../yida-app/workflow/step-3-create-or-reuse-app.md) 执行并回读。已有应用只需切换导航时执行：
 
 ```bash
 openyida update-app <appType> --hide-app-nav
 ```
 
-只有整个应用采用自定义导航时，才对 PRD 本轮范围内全部普通表单、流程表单、自定义页面及其他支持页面配置的资源逐页执行；使用已解析的真实 `formUuid` 和原页面标题：
+自定义导航必须对 PRD 本轮范围内全部普通表单、流程表单、自定义页面及其他支持页面配置的资源逐页执行；使用已解析的真实 `formUuid` 和原页面标题：
 
 ```bash
 openyida update-form-config <appType> <formUuid> false "<页面标题>"
 openyida get-form-config <appType> <formUuid> --json
 ```
 
-每页回读 `renderNav=false` 才完成；仅缺少 `renderNav` 时兼容 `isRenderNav`，布尔值及字符串 `"false"` 均表示隐藏，缺失或无效值不算成功。失败时修复该页配置并重读。表单及自定义页面在创建或复用并取得真实 `formUuid` 后立即配置，可与页面代码开发并行，不等待页面发布。发布后只回读核对；若发布改变了配置才补写修复，最终按 PRD 清单逐项核对。`create-page --hide-nav` 已包含配置、回读及一次补写，`navigationVerification.verified=true` 可作为创建时的证据，无需重复配置；URL 参数不能代替持久化设置。
-
-## 访问态入口与权限
-
-前台和管理端可以使用不同的菜单，管理端也可以直接打开业务列表，无需首页。菜单显示什么与用户能操作什么要分别处理：平台隐藏的菜单项，仍可能是前台需要的任务；能看到一个页面，也不代表能提交或修改数据。
-
-公开内容的纯页内视图使用本地数组直接切换，或 `mode=local`，不请求平台菜单接口；叶子项需 `key/viewKey/targetType=local`。沿用平台菜单范围时使用 `platform` 模式并绑定真实资源 ID；按资源权限独立组织任务时使用 `independent` 模式，并查询当前用户的真实权限。local 中声明的 access 也必须校验，不得删除声明规避权限；业务查询、提交和管理操作继续校验平台权限。权限查询尚未接通时，不放行相关菜单，明确记录未完成项。字段和步骤见 [前台与管理端的菜单规则](../yida-app/references/entry-navigation.md)。
+每页回读 `isRenderNav=false` 才完成；失败时修复该页配置并重读。表单及自定义页面在创建或复用并取得真实 `formUuid` 后立即配置，可与页面代码开发并行，不等待页面发布。发布后只回读核对；若发布改变了配置才补写修复，最终按 PRD 清单逐项核对。`create-page --hide-nav` 可用于新建页初始配置，仍需回读；URL 参数不能代替持久化设置。
 
 ## 实现要点
 
-本节的 iframe 与原生表单打开规则用于计划选择复用原生页面的工作区。全码前台默认在同一页面切换业务视图、完成填写与结果展示，连接真实数据；不把默认 iframe 当作全码前台。菜单只包含该入口的有效任务，不能把后台菜单自动带入前台。
-
-先读取 [页面与导航连续性](../yida-design/references/page-continuity.md)，落实 design.md 中的共同画布、滚动归属及往返状态。导航布局与内容切换共同设计；不要只生成菜单外形。
-
 - **MUST：应用内切换保留导航壳**：点击自定义导航后，导航必须仍然可见且可继续操作；默认只切换主内容区。原生提交页、数据管理页嵌入主内容 iframe，本地工作台切换 React 内容。只有确认目标页面也承载同一套导航壳时才允许整页跳转；不能直接跳到隐藏导航的原生页面。外链和用户主动新窗口打开单独处理。见 [保留导航壳的最小示例](references/nav-shell-patterns.md#保留导航壳的最小示例)。
 
-- **按场景选择内容布局**：先执行 `openyida sample openyida-page-template canvas-nav-content` 并整体合并 `CanvasNavigationContent`，保持 `.openyida-nav-layout` / `.openyida-nav-content` 布局结构。业务工作区使用默认 `layout="workspace"`，从壳到 main、iframe 建立完整 flex 高度链，每个可收缩层设置 `min-height:0`；工作台内容区滚动，原生页仅 iframe 内滚动。沉浸官网或连续展示页使用 `layout="document"`，导航与首屏叠在共同画布上、沿用页面滚动，不套定高内滚动工作区。顶部导航通过 `navigation` 接入，提取 canvas-nav-top 时传 `headerOnly`，有首屏背景再传 `overlay`；不能再嵌一整套带 main 的导航壳。document 的 main/content 使用自然高度，禁止套用 workspace 的 flex 零基准或定高内滚动。见 [连续展示页](references/nav-shell-patterns.md#连续展示页共享首屏背景) 和 [主内容撑满剩余空间](references/nav-shell-patterns.md#must主内容撑满剩余空间)。
+- **MUST：内容区撑满剩余空间**：先执行 `openyida sample openyida-page-template canvas-nav-content` 并整体合并 `CanvasNavigationContent`，保持 `.openyida-nav-layout` / `.openyida-nav-content` 布局结构；顶部导航通过 `navigation` 接入，侧栏布局在右侧确定高度的内容区域使用。从确定高度的导航壳到 main、iframe 视口建立完整 flex 高度链，每个可收缩内容层设置 `min-height:0`；工作台自身滚动，原生页仅 iframe 内滚动。切换视图保持内容宽度和外侧留白连续，禁止父级 block、子级只写 `flex:1` 的无效布局。实现与验收见 [主内容撑满剩余空间](references/nav-shell-patterns.md#must主内容撑满剩余空间)。
 
-- **画布与间距**：宿主消费 `--pod-page-bg-color`，内部画布按 design.md 配色和材质，只作用于当前页，不改全局变量。根用 flow-root 或 flex/grid；沉浸页遵循共同背景规则，工作区按主题保证导航可读。
+- **画布与浮导间距**：平台宿主继续消费 `--pod-page-bg-color`；自绘导航页的内部画布由 `design.md` 定义，可采用浅灰、浅彩、渐变或局部纹理，不强制跟随白色平台底色。浅色非白画布上，顶部浮导默认白色或近白半透明，卡片默认白色无框；品牌色集中于选中态和主操作，深色方案单独设计。只作用于当前页面选择器，不修改应用全局变量。根节点使用 `display:flow-root` 或 flex/grid，让浮导上边距留在根节点内。
 
 - **先选形态，再写 UI**：根据已确认的 PRD、`design.md` 和用户参考确定布局。模块多用侧栏，模块少且内容需要宽度用顶部，两级业务用顶部＋侧边，沉浸展示可用悬浮 Dock，同模块视图用标签。已确认的选择直接沿用，不重新提问。
-- 自定义顶部导航默认贴顶通栏，不默认浮导；胶囊或悬浮栏仅按明确设计选用。有首屏背景图时默认叠加背景、初始透明，滚动后增加遮罩底色，回顶恢复透明；展开菜单保持可读底色。工作区导航占位。定位方式与外观分开选择，遵循 [连续性规则](../yida-design/references/page-continuity.md)，不改变导航归属。
+- 自定义顶部导航默认推荐浮导，可按内容宽度设计为紧凑胶囊或悬浮栏；“顶部导航”不等于贴边通栏。位置、比例、留白、材质和选中态根据业务与设计实现，不由现成组件决定。此推荐只针对顶部样式，“平台导航 / 自定义导航”选项保持中性。
 - 需要布局方向和小段代码时读 [导航壳形态目录](references/nav-shell-patterns.md)。按场景设计和手写实现，不强制复制任何导航组件。已有导航符合设计时直接复用，只补缺失功能；不能仅因存在新示例而替换现有外观。
 - 自定义侧边导航（含顶部＋侧边）的 PC 端必须支持折叠/展开和拖拽调宽；展开恢复折叠前宽度，宽度变化时内容区同步调整。移动端改为可展开/收起的菜单，详见 [侧栏交互](references/nav-shell-patterns.md#侧栏交互)。
-- 菜单数量、名称、顺序、分组和入口用途来自 PRD，默认落点按当前入口任务确定；平台模式用当前访问者的 `getAccessableNavs.json` 过滤展示，独立资源菜单及任何声明 access 的菜单必须接入真实权限适配，详见 [导航数据来源](references/nav-shell-patterns.md#导航数据来源)。数据逻辑可直接复用，不要求采用同一套 UI。
+- 菜单数量、名称、顺序、分组和入口用途来自 PRD，通常工作台在首位；用当前访问者的 `getAccessableNavs.json` 过滤可见范围，详见 [导航数据来源](references/nav-shell-patterns.md#导航数据来源)。数据逻辑可直接复用，不要求采用同一套 UI。
 - 只在当前页切视图时用 React 状态；需要分享、刷新恢复、前进后退时同步 URL hash。跨真实页面时沿用应用路由与数据桥，详见 [菜单契约](references/nav-shell-patterns.md#菜单契约)。`hashchange`、`matchMedia` 等监听必须 cleanup。
 - **满足导航壳保留条件后的跨页跳转，避免重复应用前缀**：完整的 `/APP_xxx/workbench/FORM_xxx` 地址通过数据桥调用 `router.push(href, params, false, true)`，第三参 `false` 表示不新开标签，第四参 `true` 表示 URL 模式。数据桥已修复省略第四参时的自动识别，但不会覆盖显式传入的 `false`；生成代码仍须明确传 `true`，详见 [路由模式与数据桥兜底](references/nav-shell-patterns.md#路由模式与数据桥兜底)。
 - 导航项保存真实资源 ID、入口用途和 `params`；办理任务、数据管理与页面内新增/详情按钮按 [入口用途与嵌入页面](references/nav-shell-patterns.md#入口用途与嵌入页面) 分别处理。用 `URL` / `URLSearchParams` 保留 `corpid`、`locale` 和业务参数。
@@ -84,10 +61,9 @@ openyida get-form-config <appType> <formUuid> --json
 ## UI 和验收
 
 - 导航表达应用身份、业务层级和当前位置；选中态清晰，图标使用 `lucide-react` 或 `@ant-design/icons`，不用 emoji、字母占位或 CSS 拼图标。
-- 视觉按 [导航与应用框架](../yida-design/references/application-theme-consistency.md#导航与应用框架) 落实 `design.md` 的完整导航 token；背景、文字、悬停/选中、边界、形状、字体和间距与表单、详情和内容区协调。对照用户参考检查位置、比例及首屏/滚动态，样式由当前导航组件消费应用主题。
+- 视觉对照 `design.md` 和用户参考检查，尤其是浮导的容器比例、留白、位置与内容关系。导航消费应用主题 token，不另注一套全局主题。
 - 导航选中态已标明当前页时，内容区从业务开始；独立页头只补充对象、任务说明或操作，避免重复菜单标题。
 - 侧栏已验证折叠、恢复宽度、拖拽上下限和内容联动；顶部窄屏可展开菜单，Dock 不遮内容和主要操作。
-- 按范围验收：应用级自定义导航核验应用 `hideAppNav` 与各页 `renderNav=false`；仅前台菜单核验该页独立展示，并确认后台应用导航仍可用。配置均需持久化并回读；菜单可见性、选中态、内容与路由一致，深链、刷新及前进后退正常。
+- 应用 `hideAppNav` 与各页 `isRenderNav=false` 均已持久化并回读；菜单可见性、选中态、内容与路由一致，深链、刷新及前进后退正常。
 - 逐项点击应用内导航，确认导航壳、当前选中项和主内容同时正确；切换后还能返回工作台。不能只验证目标页面打开成功。
-- 实际滚动到页脚并回顶，确认 main 没有塌缩到导航高度；检查首屏、第二屏与窄屏菜单展开态，无背景断带、遮挡或双滚动；测试往返、快速连点、重复点击、刷新、前进后退、加载失败及未保存输入，按连续性规则核验状态和焦点。
 - 完整检查见 [验证清单](references/nav-shell-patterns.md#验证)。本地编译后按 `yida-publish-page` 发布并检查实际页面，编译通过不等于视觉验收通过。