openyida 2026.9.21 → 2026.9.22-beta.2

package/yida-skills/skills/yida-design/references/app/blueprint.md

@@ -0,0 +1,70 @@
+# 应用结构字段
+
+用于单个页面需要感知完整应用时，承接 `yida-design` 的输出。
+
+## 必填字段
+
+| 字段 | 说明 |
+| --- | --- |
+| `appName` | 应用名 |
+| `entry` | 首页或入口页 |
+| `shell` | `side_nav/top_nav/l_shaped/fullbleed-screen/split-pane/single_page` |
+| `roles` | 用户角色 |
+| `navigationGroups` | 导航分组和页面列表 |
+| `pages` | 页面清单，含 `name/scene/targetRole/purpose/blocks` |
+| `resourceBlueprint` | 页面、普通表单、流程表单、报表等资源清单 |
+
+## 使用规则
+
+- 页面 PRD 章节只引用与当前页有关的应用结构信息，不展开整个应用 PRD。
+- 多页面应用的首页不一定是工作台：外部传播可用 landing，管理决策可用 dashboard，投屏可用 screen。
+
+导航字段按下表写，不能混用：
+
+| 需求 | 字段 | 后续技能/命令 |
+| --- | --- | --- |
+| 常规应用导航、导航分组、页面排序 | `navigationGroups` | `yida-nav-group` |
+| 自定义页自绘应用级顶部/侧边/导航壳 | `hideAppNav='y'` | `yida-nav-shell` + `openyida update-app <appType> --hide-app-nav` |
+| 页面隐藏导航、无导航、`isRenderNav=false` | 页面级隐藏配置 | `yida-page-config` / `update-form-config` |
+
+默认导航可见并优先与宜搭运行态融合；普通页面内 tab、分段筛选和快捷入口不隐藏平台导航。用户只要求页面隐藏导航、无导航或 `isRenderNav=false` 时，记录页面级隐藏配置，不自动写 `hideAppNav`。
+
+## resourceBlueprint
+
+`resourceBlueprint` 对齐 `yida-app` 的页面与表单设计，描述“应该有什么资源”，运行后 ID 由实现阶段记录。
+
+```json
+{
+  "pages": [
+    {
+      "name": "经营工作台",
+      "resourceType": "display-page",
+      "scene": "workbench",
+      "isMain": true,
+      "purpose": "应用第一入口、今日概览、快捷入口"
+    }
+  ],
+  "forms": [
+    {
+      "name": "商品管理",
+      "formKind": "normal-form",
+      "purpose": "维护商品基础资料",
+      "fields": ["商品名称", "商品分类", "售价", "商品状态"]
+    },
+    {
+      "name": "采购审批",
+      "formKind": "process-form",
+      "purpose": "采购申请与审批流转",
+      "process": ["发起", "主管审批", "采购执行"]
+    }
+  ],
+  "reports": [
+    {
+      "name": "销售趋势报表",
+      "purpose": "汇总订单金额和销量趋势"
+    }
+  ]
+}
+```
+
+字段写业务名、字段类型、必填、默认值、Divider 分组等语义；真实 `formUuid`、`fieldId`、`processCode` 由实现阶段创建后写入 `.cache/<项目名>-schema.json`。

package/yida-skills/skills/yida-design/references/app/navigation-patterns.md

@@ -0,0 +1,43 @@
+# 导航模式
+
+## 快速判断
+
+| 需求 | 使用模式 | 要不要隐藏应用导航 | 备注 |
+| --- | --- | --- | --- |
+| 常规业务系统、多页面后台 | 平台导航 | 不隐藏 | 用 `yida-nav-group` 管导航分组和顺序 |
+| 自定义页自绘应用级顶部/侧边/导航壳 | 页面内导航壳 | 隐藏 | 设置 `hideAppNav='y'`，再用 `yida-nav-shell` |
+| 页面内 tab、分段、局部切换 | 混合导航 | 不隐藏 | 这是当前页面内部结构 |
+| 页面全屏、无导航、`isRenderNav=false` | 页面级隐藏 | 不一定 | 不等同于隐藏应用导航 |
+
+## 平台导航
+
+适合常规中后台、多页面业务系统。优先使用宜搭左侧导航分组，页面内容保持与平台主题融合。
+
+规则：
+
+- 门面页靠前，配置/录入类页面靠后。
+- 同一角色的高频页面放同组。
+- 同应用内页面优先在平台应用导航内切换；不要把一组同应用页面复制成自定义页里的快捷入口卡。
+- 看板、工作台、列表、详情不要无序混排。
+
+## 页面内导航壳
+
+适合应用导航已隐藏，且自定义页需要自己承担应用级入口的场景。
+
+规则：
+
+- 默认不要在自定义页里自建同级导航。
+- 只有明确要顶部导航、侧边导航、导航壳、自绘应用级导航或隐藏应用导航时才使用。
+- 自绘应用级导航前必须开启 `hideAppNav`；不要用 `isRenderNav=false` 表达应用导航隐藏。
+- 顶部导航适合官网/门户；侧边导航适合复杂后台；浮动胶囊适合沉浸展示。
+- 页面内导航只负责当前沉浸体验，不替代平台真实导航管理。
+
+## 混合导航
+
+适合复杂应用：平台导航承载模块，页面内 tab 承载同页子视图。
+
+规则：
+
+- 平台层做跨模块跳转。
+- 页面层做当前模块内切换。
+- 不同时出现两套同级导航。

package/yida-skills/skills/yida-design/references/app/role-journey.md

@@ -0,0 +1,30 @@
+# 角色旅程
+
+应用级体验要先回答“谁进来做什么”。
+
+## 角色卡
+
+```markdown
+- 角色：经销商
+- 第一入口：经销商数据看板
+- 高频任务：查看 GMV / 补货风险 / 活动转化 / 巡店建议
+- 需要页面：dashboard + list + detail
+- 不需要页面：内部配置表单直接暴露在首屏
+```
+
+## 页面映射
+
+| 角色需求 | 页面类型 |
+| --- | --- |
+| 了解品牌价值 | landing |
+| 处理待办和入口 | workbench |
+| 判断业务健康 | dashboard |
+| 监控态势 | screen |
+| 找对象和批处理 | list |
+| 看单个对象全貌 | detail |
+
+## 验收
+
+- 每个核心角色至少有一个明确入口。
+- 页面命名体现角色任务，不用泛化标题。
+- 不为所有角色展示同一套入口密度。

package/yida-skills/skills/yida-design/references/ask-human-interaction-contract.md

@@ -12,14 +12,13 @@
 
 1. 需求识别与分析
 2. 设计功能和页面
-3. 确认搭建方案
+3. 生成PRD方案&确认
 4. 创建应用
 5. 搭建表单与审批流
 6. 准备示例数据
-7. 准备页面图片
-8. 搭建业务页面
-9. 发布页面与配置导航
-10. 检查功能并交付
+7. 搭建业务页面
+8. 发布页面与配置导航
+9. 检查功能并交付
 
 **Fast 模式**
 
@@ -28,14 +27,13 @@
 3. 创建应用
 4. 搭建表单与审批流
 5. 准备示例数据
-6. 准备页面图片
-7. 搭建业务页面
-8. 发布页面与配置导航
-9. 检查功能并交付
+6. 搭建业务页面
+7. 发布页面与配置导航
+8. 检查功能并交付
 
-按本轮范围选用步骤：已有应用时省略“创建应用”，无需示例数据或图片时省略对应步骤，并重新编号。
+已有应用时，直接省略“创建应用”，不另列“复用现有应用”待办，后续步骤重新编号；无需示例数据时跳过对应步骤。步骤状态按真实进度更新，有独立输入的工作可同时进行。
 
-每项待办对应一个阶段，直接使用上方短标题。创建应用、表单、数据、图片、页面和发布分别展示。执行中保持标题与列表顺序稳定，完成后标记完成并保留记录。图片准备与表单、页面搭建可同时进行，列表顺序仅用于展示。业务细节写在进度消息中，任务编号、命令、路径、授权依据和耗时写入内部执行记录；用户要求的耗时统计集中放入报告。素材采集与应用创建同时进行时，进度描述统一为“素材采集&应用创建”；单独进行时使用对应阶段名称。图片数量、用途及任务详情归入内部执行记录。
+禁区：待办标题、说明和进度不出现技能名、命令、文件路径、登录账号、内部资源 ID；这些留在工具调用里。用户明确询问技术细节时再解释。
 
 保存需求答案包含在“需求识别与分析”中，不另列需求简报任务或要求用户重复确认；步骤状态按实际进展更新。
 
@@ -45,11 +43,10 @@
 | --- | --- |
 | 需求识别与分析 | 正在梳理商品、订单和养护的管理需求。 |
 | 设计功能和页面 | 正在设计工作台、商品列表和绿色界面。 |
-| 确认搭建方案 | 正在整理功能和页面方案，完成后请你确认。 |
+| 生成PRD方案&确认 | 正在整理功能和页面方案，完成后请你确认。 |
 | 创建应用 | 正在创建绿植售卖管理应用。 |
 | 搭建表单与审批流 | 正在搭建商品、订单和养护表单，以及相应审批流程。 |
 | 准备示例数据 | 正在准备商品和订单样例，方便你体验功能。 |
-| 准备页面图片 | 素材采集 |
 | 搭建业务页面 | 正在搭建工作台、商品管理和订单查询页面。 |
 | 发布页面与配置导航 | 正在发布已完成的页面，并配置各功能入口。 |
 | 检查功能并交付 | 正在检查商品录入、订单查询和工单处理。 |
@@ -58,34 +55,15 @@
 
 ## 用户可见表达
 
-面向非技术用户，用日常用语和短句说清楚：正在做什么、结果怎么样、接下来做什么；需要用户决定时，直接问具体问题。一句话说一件事，先说结果或动作，再补必要原因。
-
-### 按场景直接说
-
-| 场景 | 写法 | 示例 |
-| --- | --- | --- |
-| 说明功能 | 谁可以做什么 | 客人可以查看房型、选择日期并提交预约。 |
-| 说明方案 | 具体页面或操作＋用途 | 客人从官网预约，工作人员在管理页面处理订单。 |
-| 汇报进度 | 当前动作＋下一步 | 房型页面已搭好，接下来连接预约表单。 |
-| 需要选择 | 一个具体问题＋选项的用途 | 客人提交预约后，需要工作人员确认吗？ |
-| 素材采集与应用创建同时进行 | 简短阶段组合 | 素材采集&应用创建 |
-| 等待较久 | 正在处理什么＋对进度的影响 | 正在准备首页图片，客房列表会同时搭建。 |
-| 部分失败 | 哪部分失败＋实际影响＋处理办法 | 首页图片下载失败，我会换一张；客房列表继续搭建。 |
-| 结果待核实 | 已知结果＋待检查内容＋下一步 | 发布请求已发出，暂时还没收到结果。我先检查页面是否发布成功。 |
-| 交付 | 已验证的功能＋访问入口＋剩余事项 | 已验证房型浏览和预约提交，可从“酒店官网”进入。订单提醒还未完成。 |
-
-按实际情况改写示例：原因有证据再说明，原因未知写待检查内容；下一步写可执行的方案。耗时有依据再估计，情况变化及时更新。
-
-### 统一写法
+用户可见内容只说明三件事：已经理解或完成什么、接下来做什么、用户现在需要决定什么。
 
 1. 进度消息使用业务结果和下一步动作。结构化问题紧随其后时，不额外发送内部分析结论；多个问题确需共同背景时，只在整组交互的引导中说明一次，不写入每个问题的 `title` 或 `prompt`。
-2. `title`、`prompt`、`label`、`description` 和普通对话使用具体的业务名称和动作，例如“预约表单”“提交订单”“查看处理结果”。必要的专业词第一次出现时，用一句日常用语解释。
+2. `title`、`prompt`、`label`、`description` 和普通对话只使用用户能直接理解的业务词。
 3. `interactionId`、`questionType`、`value`、`writeBackPath`、`reason`、状态字段和文件路径仅供内部执行，不进入用户可见内容。
-4. `title` 只写确认主题，`prompt` 只写用户当前需要回答的问题；搭建模式保持中性，不在引导或描述中偏向某一模式；选项顺序、推荐标记及预选能力遵守宿主规则，UI 默认状态不视为用户答案。导航方式、布局和呈现样式由 AI 根据场景确定，用户明确要求优先。其他问题存在合理默认值时可标记。只有某个选择会产生重要且难以撤销的影响时，才在对应选项的 `description` 中说明影响。
+4. `title` 只写确认主题，`prompt` 只写用户当前需要回答的问题；搭建模式、导航归属保持中性，不标记“推荐”或“默认”，不预选、不按偏好排序，也不在引导或描述中推荐。导航布局和呈现样式根据场景确定，不进入提问选项；用户明确的布局和样式优先。其他问题存在合理默认值时可标记。只有某个选择会产生重要且难以撤销的影响时，才在对应选项的 `description` 中说明影响。
 5. 用户已经提供的信息直接写入内部事实，不重复总结成“缺口分析”或再次追问。
 6. PRD 的业务说明、HTML、进度消息和交付总结使用功能、体验和验收结果描述配置。接口参数、配置键值、内部 ID 和 CLI 选项保留在 Agent 实施交接中；访问链接使用业务名称，链接目标保留必需参数。用户明确询问实现细节时，再解释对应技术内容。
-7. 交付卡片的 `description` 写已验证的业务能力、核验结果和剩余事项；宿主没有交付工具时，在最终回复中给出相同内容与入口。
-8. 规划写预期行为，进度写正在进行的动作，完成总结依据实际验证结果。导航方案写“采用自定义导航，支持各业务页面间切换”；完成配置并验证跳转后写“已启用自定义导航，可在各业务页面间切换”。
+7. 规划写预期行为，进度写正在进行的动作，完成总结依据实际验证结果。导航方案写“采用自定义导航，支持各业务页面间切换”；完成配置并验证跳转后写“已启用自定义导航，可在各业务页面间切换”。
 
 内部表达按下表转换为用户可见表达：
 
@@ -93,43 +71,41 @@
 | --- | --- |
 | 技能名、执行身份、加载技能或交互契约 | 按当前动作表述为“需求分析”“业务规划”或“视觉设计”，说明正在处理的业务内容 |
 | 读取视觉规则、查找主题模板、生成候选 | 准备期间说明当前应用正在设计的配色、界面风格及业务用途；方案就绪后直接邀请用户选择应用风格 |
-| 主题匹配完成、主题已选定 | 说明设计风格和适用场景，例如“设计主题风格为轻盈媒体栅格，适合产品展示型品牌官网。”建议阶段使用“建议采用……风格” |
 | Gate、选择设计模式、`designMode` | 选择搭建方式 |
 | Fast Design | Fast（快速搭建） |
 | Plan Design | Plan（先确认 PRD 再搭建） |
 | 进入 Step、加载分支、返回上层流程 | 说明下一项业务动作；没有用户价值时省略 |
 | 缺口、阻塞项、对焦 | 还需要确认的关键信息 |
 | `required`、`missingSlots`、`writeBackPath`、`reason` | 仅内部使用，不展示 |
-| `meta.revision`、`meta.status`、`planState` | 当前方案（不显示修订序号） |
+| `meta.revision`、`meta.status`、`planState` | 当前这版方案或第 N 版方案 |
 | `hideAppNav=y`、`isRenderNav=false` | 隐藏平台导航，使用自定义导航或独立页面入口；按当前导航方案描述 |
 | `appType`、`formUuid`、接口参数、CLI 选项 | 使用应用名、页面名及对应业务动作描述 |
 
-发送前按上表检查，确保用户看得懂、能作出选择。把“消费设计产物”“完成物化”“执行回读”等内部说法，改成“按方案搭建页面”“生成方案”“检查保存结果”等具体动作。技术字段和错误码保留在工具结果与实施交接中，用户询问技术细节时结合业务影响解释。
+发送用户可见内容或执行 `ask_human` 前检查：展示字段不包含 Skill 名、Gate、Fast Design、Plan Design、`ask_human`、Step、交互契约、状态字段、缺口、阻塞项、对焦、加载分支或写回路径。
 
-Fast / Plan 是面向用户的模式名称，仅在首轮澄清后的模式路由仍有必要时询问。已有详细计划时询问是否整理成 PRD 供确认；细节不足时询问 Fast / Plan，说明先确认方案所需的额外时间。
+Fast / Plan 是面向用户的模式名称，可以展示。已有详细计划时询问是否整理成 PRD 供确认；细节不足时询问 Fast / Plan，说明先确认方案所需的额外时间。
 
 ## 逻辑动作与宿主适配
 
 技能文档统一使用 `ask_human` 表示“向用户提问并等待回答”的逻辑动作。宿主按当前可用能力完成适配：
 
-1. 使用当前宿主实际可用、当前模式允许的结构化工具；同步工具受限时优先使用可用且允许的异步工具。不能因为工具存在就调用模式禁止的能力。
-2. 无可用工具或允许的工具均失败时，按宿主规则在对话中补问，不伪造工具调用或回答。关键问题未答时只推进不依赖答案的工作。
-3. 工具名称与参数以实际 schema 为准。下面的逻辑字段用于表达意图，不强行传入宿主不支持的字段；多选能力不存在时使用用途清楚的功能组合或自由输入，不伪造 multi_choice。
-4. 异步返回、默认勾选、未回复和超时都不是答案。收到有效回答后才写回对应业务字段；用户委托时保留依据，AI 决定不记成用户选择。
-5. 一题一个决定。工具已有自由输入时不另设“其他”，不为问题数量限制合并模式、功能、风格等无关决定。首轮通常 1–3 题，删去低价值扩展，不机械拆轮。
+1. 宿主提供结构化提问工具时，必须实际调用该工具并等待结果；文字说明、Markdown 选项、JSON 问题对象都不能替代工具调用。
+2. 宿主没有结构化提问工具，或工具调用失败时，使用普通对话展示相同问题和选项，并停止后续执行直到用户回答。
+3. 宿主工具名称由运行环境决定。技能不固定写死 `request_user_input`、`AskUserQuestion` 或其他实现名称。
+4. 用户回答后，将结果写入问题声明的 `writeBackPath`，再继续当前阶段。
 
 ## 交互类型
 
 | 场景             | 类型                                           | 必填内容                     | 回写位置                      |
 | ---------------- | ---------------------------------------------- | ---------------------------- | ----------------------------- |
 | 搭建方式 | `single_choice` | 按需求详细程度提供 PRD 是/否或 Fast/Plan | brief 的 `intake.designMode` |
-| 核心功能 | `multi_choice` | 功能名称＋一句用途，说明谁做什么；按宿主能力适配 | brief 的 `coreFunctions/businessObjects/userTasks` |
-| 关键用法 | `single_choice` | 能改变范围或入口判断的实际使用方式 | brief 的 `userTasks/entryRecommendation` |
+| 业务模块与页面范围 | `multi_choice` | 具体业务模块、对应页面、表单及用途，可合为一题 | brief 的 `coreFunctions/businessObjects/pageScenes/explicitScope` |
+| 导航归属 | `single_choice` | 仅“宜搭原生导航”和“自定义导航”两个选项；原生导航就是平台导航，布局根据场景确定 | brief 的 `navigation`（按场景补齐 `type`，自定义含 `variant`，`reason` 区分用户归属选择与布局依据） |
 | 应用设计风格 | `single_choice` | 面向业务的风格选项与自定义偏好 | brief 的 `visualSelection` |
 | 来源补齐         | `free_text`                                    | 可读正文、链接或附件         | `meta.source`                 |
 | 最新搭建计划确认 | `confirm`                                      | 当前版本、确认生成、继续调整 | `meta.planState`              |
 
-逻辑问题按以下信息组织；仅向实际工具传入 schema 支持的字段：
+每个逻辑问题至少包含：
 
 - `interactionId`：当前交互唯一标识。
 - `questionType`：交互类型。
@@ -148,31 +124,31 @@ Fast / Plan 是面向用户的模式名称，仅在首轮澄清后的模式路
 
 ## 首次搭建确认
 
-按 [首轮需求分析](../../yida-requirement-analysis/workflow/prepare-brief.md) 尽早确认核心功能与关键用法，已有信息直接复用。首轮集中确认核心功能和实际用法；视觉风格可先记录建议。需求澄清后，由应用编排确定执行方式，AI 规划页面、导航和布局。
+先完成需求分析，再按 [首次搭建确认表](../../yida-requirement-analysis/workflow/prepare-brief.md#2-确认首次搭建的未决事项) 询问尚未明确的事项。该表统一维护详细计划复用、搭建方式、业务模块、导航归属、风格和页面范围；已有业务应用的局部增改按本次疑问澄清。
 
-首轮澄清结束后，编排按 [模式路由](design-mode.md) 处理尚未明确的执行方式，并按 [导航决策](navigation-decision.md) 由 AI 确定平台导航或自定义导航及布局。导航没有独立选择或确认轮，用户主动指定时沿用；Plan 将 AI 建议随整体方案展示。`intake.confirmed` 仅表示需求澄清完成，不表示方案获批。
+首次搭建的全部未决事项在一次结构化提问调用中呈现并一次性作答，Fast / Plan、导航归属、业务模块和页面范围不得分轮收集。导航仅提供“宜搭原生导航”和“自定义导航”两个选项，按 [导航选项说明](../../yida-requirement-analysis/workflow/prepare-brief.md#导航选项说明) 附带实现方式说明；宜搭原生导航就是平台导航。支持 `description` 时写入该字段，否则在选项后括号备注。顶部、侧边、L 型、浮导、底部菜单等布局或样式不进入 `ask_human`；Agent 在已选归属内根据场景确定，记录布局依据并交给后续规划，不补问位置。用户已明确的归属、布局或样式直接沿用。工具限制问题数量时合并为复合问题，多选能力不足时使用同组自由输入；没有可用结构化工具时，在一条消息中展示全部问题。具体合并方式遵守首次搭建确认表，全部必要回答写回后才开始后续规划。
 
-视觉方向与后续映射统一写入 brief 的 `visualSelection`；Plan 没有明确完整视觉方向时，必须使用“应用设计风格”交互展示共用规则生成的三套候选。未选候选不进入有效范围，失效推导同步移除。
+视觉映射统一写入 brief 的 `visualSelection`，由后续计划沿用 visualDirection、selectedTheme、colorStrategy、navigationStyle；未选候选保留在会话中。
 
 ## 搭建计划展示
 
 Plan Design 完成当前版本后，按以下顺序与用户交互：
 
-1. 在会话中使用“搭建方案”或“当前方案”，给出 3-7 条业务摘要。用户可见的 PRD / HTML 标题、摘要、附件名称和确认问题都不展示修订序号或原始 `meta.revision`；修订标识仅保留在内部元数据和确认字段中。
+1. 在会话中使用“当前这版方案”或“第 N 版方案”，给出 3-7 条业务摘要；原始 `meta.revision` 仅用于内部状态绑定。
 2. 在“最新搭建计划确认”的同一次 `ask_human` 中，通过 `attachments` 展示可打开的 `prd/<项目名>/build-plan.html`，并以 `revision` 绑定当前 `meta.revision`。
-3. 结构化交互成功创建后将 `meta.planState.presentedRevision=meta.revision` 写回源 JSON，不再物化；awaiting_confirmation 在生成前写入。
+3. 结构化交互成功创建后令 `meta.planState.presentedRevision` 等于 `meta.revision`；awaiting_confirmation 在生成前写入。
 4. 提供“确认并开始搭建”和“继续调整”两个选择，并等待用户回答。
 
 `build-plan.html` 不承载对话控件或确认按钮；用户在会话中完成确认。
 
-最终确认是一个 `single_select` 语义问题。它只有下面这一份可调用 schema；顶层字段集合固定为 `question`、`title`、`options`、`attachments`、`revision`、`submitLabel`。将路径和 `{revision}` 替换为本次 materialize 返回的真实值：
-
-#### 最终确认 `ask_human` payload
+最终确认使用以下逻辑问题，其中 `{revision}` 替换为当前版本号：
 
 ```json
 {
-  "question": "是否按当前方案开始搭建？",
+  "interactionId": "plan_confirm_r{revision}",
+  "questionType": "confirm",
   "title": "确认整体方案",
+  "prompt": "是否按当前这版方案开始搭建？",
   "options": [
     {
       "value": "confirm_build",
@@ -185,19 +161,18 @@ Plan Design 完成当前版本后，按以下顺序与用户交互：
       "description": "继续完善当前方案，确认后再开始搭建。"
     }
   ],
+  "allowCustom": false,
+  "writeBackPath": "meta.planState",
   "attachments": [
     {
-      "name": "build-plan.html",
+      "name": "当前搭建方案",
       "path": "prd/<项目名>/build-plan.html"
     }
   ],
-  "revision": "{revision}",
-  "submitLabel": "提交选择"
+  "revision": "{revision}"
 }
 ```
 
-`options` 固定为 `confirm_build`、`continue_editing` 两项。最终确认只收集当前 revision 的去向；调整内容在下一次交互中收集。内部交互身份使用 `plan_confirm_r{revision}`，回答写入 `meta.planState`。
-
 ## 版本与确认状态
 
 `build-plan.json` 使用 `meta.revision`、`meta.status` 和 `meta.planState` 共同记录当前计划状态：
@@ -216,11 +191,11 @@ Plan Design 完成当前版本后，按以下顺序与用户交互：
 }
 ```
 
-状态转换规则：
+状态更新规则：
 
 1. 首次生成计划时创建 `meta.revision`，设置 `meta.status=draft`、`meta.planState.planConfirmed=false`。
-2. 业务方案或视觉方案变化时生成新的 `meta.revision`，并清空旧确认信息。素材采集后的进度同步保留版本与已有确认，直接继续搭建。
-3. 计划展示成功后向源 JSON 写回 `meta.status=awaiting_confirmation` 和 `presentedRevision=meta.revision`。
-4. 用户在最终确认交互中选择 `confirm_build`（确认并开始搭建）且回传 revision 等于展示 revision 时，设置 `meta.status=confirmed`、`planConfirmed=true`、`confirmedRevision=meta.revision`，同时记录交互 ID 和确认时间。
+2. 每次修改影响搭建计划事实时生成新的 `meta.revision`，并清空旧确认信息。
+3. 计划展示完成后设置 `meta.status=awaiting_confirmation` 和 `presentedRevision=meta.revision`。
+4. 用户在最终确认交互中选择“确认并开始搭建”时，设置 `meta.status=confirmed`、`planConfirmed=true`、`confirmedRevision=meta.revision`，同时记录交互 ID 和确认时间。
 5. 只有 `meta.status=confirmed`、`planConfirmed=true` 且 `meta.revision=presentedRevision=confirmedRevision` 时，Plan Design 才能返回 `yida-app` Step 3。
-6. 用户选择“继续调整”时保持在 Plan Design，本轮不创建应用资源；下一轮单独收集调整内容，生成新 revision 并重新确认。用户取消或关闭交互时停止执行，不创建应用资源。
+6. 用户选择“继续调整”时保持在 Plan Design；用户取消或关闭交互时停止执行，不创建应用资源。

package/yida-skills/skills/yida-design/references/asset-workflow.md

@@ -4,8 +4,6 @@
 
 ## 规则
 
-Plan 方案确认后、Fast 设计就绪后，按[后台启动与接收](../../yida-image-assets/SKILL.md#后台启动与接收)派发素材任务，与应用、表单、页面创建以及布局、数据绑定和交互开发同时推进，各页及同页图片位置并发搜索；每个位置一张图、最多两轮；第二轮只补失败的必需位置。各页通过 `--page-id` 写入独立的 `asset-manifests/<pageId>.json`，就绪后立即交给页面开发。
-
 1. 先用用户素材，再从 Unsplash/Pexels 搜图，仍有缺口时使用宿主生图。
 2. 图片统一写入 manifest 草稿并通过 `asset resolve`。
 3. 按 `pages[].materialStatus` 判断当前页：`final` 可继续，`draft` 要补必需素材，`none` 无需图片。只使用该页 `assets[].materialStatus=final` 的 URL；总状态 `draft` 不阻塞其他页面。
@@ -16,9 +14,7 @@ Plan 方案确认后、Fast 设计就绪后，按[后台启动与接收](../../y
 | --- | --- |
 | `openyida asset status --json` | 检测宿主和 CDN 能力 |
 | `openyida asset sources --json` | 查看来源规则 |
-| `openyida asset resolve --input <草稿> --manifest <页面清单> --design <design.md> --page-id <pageId> --json` | 并发处理当前页槽位并写清单 |
+| `openyida asset resolve --input <草稿> --manifest <清单> --design <design.md> --json` | 校验全部槽位并写清单 |
 | `openyida asset resolve --slot <slotId>=<路径或URL> --json` | 快速检查单个槽位 |
 
-允许外链的图片检查后直接交付，页面草稿就绪即可处理。`--upload-assets` 请求上传可转存的图片，上传时使用真实 appType；`--offline` 仅做离线检查。尺寸和来源规则见 [素材技能](../../yida-image-assets/SKILL.md)。
-
-派发前分别核实后台 Agent 和后台 Bash；QwenWork 的 Bash.run_in_background 只有实际工具支持时才使用。同步 Agent 不等于后台任务；无法后台时先推进已授权资源与独立页面，再分批素材。只在对应页接图和验收时汇合，按 yida-image-assets 的 executionContract 记录实际执行证据。
+`--offline` 禁止外链校验和上传。`--upload-assets` 只转存允许自托管的素材，Unsplash API 图片始终保留热链。

package/yida-skills/skills/yida-design/references/design-mode.md

@@ -1,14 +1,14 @@
 # Fast / Plan 路由
 
-完整应用先完成 [需求分析与首次搭建确认](../../yida-requirement-analysis/workflow/prepare-brief.md)，再读取 brief 的 `intake.designMode` 进入对应流程。首轮只澄清关键业务范围和用法，本节在澄清结束后的规划准备阶段执行。
+完整应用先完成 [需求分析与首次搭建确认](../../yida-requirement-analysis/workflow/prepare-brief.md)，再读取 brief 的 `intake.designMode` 进入对应流程。首次搭建的判断、详细计划复用和提问规则统一在该文档维护。
 
 | 已确认意图 | 执行方式 |
 | --- | --- |
 | Fast、直接搭建、按现有需求快速搭建 | 完成业务与视觉规划后直接搭建 |
 | Plan、先出 PRD、确认方案后搭建 | 执行 [Plan 编排](../../yida-app/workflow/plan/workflow.md)，确认当前方案后搭建 |
 
-用户同时要求先出计划和少提问时采用 Plan，复用已知信息。未指定模式且明确要求“不要追问/按默认方案/代为决定”时，采用 Fast 并记录委托依据，不将它标记为用户明确选择。其他首次完整搭建仅在模式仍未明确时，由 `yida-app` 在需求澄清后问一次执行方式：已有详细计划时问是否先整理 PRD 供确认，否则给出 Fast/Plan 的中性说明。按宿主 schema 展示，不默认替用户作答；已有方式直接复用，不能把导航或页面范围合并到这题。用户指定的详细计划作为规划基础，补齐实施所需的缺项。
+用户同时要求先出计划和少提问时采用 Plan，复用已知信息。用户指定的详细计划作为规划基础，补齐实施所需的缺项。
 
-同一目标、同一次搭建以 `intake.designMode` 作为权威模式状态。需求澄清、`ask_human` 恢复和 brief 合并都携带该状态；用户新的明确模式选择触发状态转换，其他回答只更新各自声明的字段。新目标重新初始化模式判断。已有应用的局部增改、单页美化和主题调整直接处理本次任务，遇到会改变范围的问题再澄清。
+同一目标、同一次搭建复用已确认方式；该选择在需求澄清、`ask_human` 恢复和 brief 合并中保持粘性，回答未重复提到模式不代表改选。只有用户明确要求改用另一方式时才更新 `intake.designMode`。切换目标时重新判断。已有应用的局部增改、单页美化和主题调整直接处理本次任务，遇到会改变范围的问题再澄清。
 
-两种方式与单页设计共用 [主题索引](../templates/design-themes/index.json) 和 [选型规则](theme-selection.md)，选前只读摘要、选后读取一份完整主题；共用业务和视觉契约；Plan 额外展示方案并绑定当前版本确认。面向用户的表达与宿主适配见 [用户交互契约](ask-human-interaction-contract.md)。
+两种方式共用业务和视觉契约；Plan 额外展示方案并绑定当前版本确认。面向用户的表达与宿主适配见 [用户交互契约](ask-human-interaction-contract.md)。

package/yida-skills/skills/yida-design/references/page-quality-gates.md

@@ -1,6 +1,6 @@
 # 页面质量门禁
 
-本文件为完整应用的页面结构、视觉设计和最终交付提供自检门禁。页面设计必须先通过这些门禁，再交给实现阶段。形状、间距、材质和装饰按选中的共享主题检查；下述通用参考值只补主题未定义项，不覆盖主题明确规则。PRD 负责业务结构、应用主题色和风格摘要，`design.md` 负责完整 UI 设计规则；不要把 `design.md` 内容复制进 PRD。
+本文件为完整应用的页面结构、视觉设计和最终交付提供自检门禁。页面设计必须先通过这些门禁，再交给实现阶段。PRD 负责业务结构、应用主题色和风格摘要，`design.md` 负责完整 UI 设计规则；不要把 `design.md` 内容复制进 PRD。
 
 ## 1. 区块丰富度建议
 
@@ -9,11 +9,22 @@
 - 每个区块必须写清目的、数据来源、主操作和状态。
 - 重复指标、重复入口、列表行、图表点、装饰块、空白容器不计数；窄场景可以少于参考数量，并说明业务取舍。
 
-## 2. 可实现页面门禁
+## 2. 源码槽位门禁
 
-每个实际自定义页须按 [输出契约的八项要点](../workflow/output-design.md#页面设计的八项要点) 写出具体设计。页面外壳、焦点、主内容、动作、上下文、状态与移动端关系都应清楚，但不要求对应同名英文字段。
+每个 display 页面都要能落到下列源码槽位：
 
-缺少首屏焦点、主要内容安排或空/载/错反馈，不能交付为可实现设计；“继承主题”只能说明共享规则来源，不能替代页面布局与响应式决定。没有真实内容的可选侧栏、摘要或图形应明确不使用，不能为补槽位造业务。
+| 槽位 | 必须写清 |
+| --- | --- |
+| `rootShell` | 页面外层背景、内容宽度、是否显示平台导航、移动端退化 |
+| `prioritySurface` | 首屏最大视觉锚点：主趋势、主任务、主对象摘要或主视觉区 |
+| `statusPrimitive` | 紧凑状态摘要、数据在线、更新时间、主健康分或状态胶囊 |
+| `actionPrimitive` | 主操作、次操作、高频动作条、批量动作条或原生表单入口 |
+| `contentPrimitive` | 表格、列表、任务流、事件流、排行、时间线、图表或详情预览 |
+| `contextPrimitive` | 右侧洞察、风险、负责人、下一步建议或关联对象 |
+| `statePrimitive` | loading、empty、error、未接数据、无权限和刷新/登记/补录动作 |
+| `responsiveRule` | PC 到移动端的分栏退化顺序和关键区块保留规则 |
+
+缺少 `prioritySurface`、`contentPrimitive` 或 `statePrimitive` 任意一项，不能交付为可实现页面设计。
 
 ## 3. 低密大卡片门禁
 
@@ -32,24 +43,20 @@
 - KPI 改成 64-88px 紧凑摘要条、分段摘要或侧栏小面板；如果横向占满宽度，必须补充趋势、更新时间、筛选、主操作或风险状态，不能只有稀疏数字。
 - 高频动作改成按钮组、工具条或紧凑入口，低频动作折叠。
 - 空态放在列表、表格或上下文面板内，并提供登记、刷新、补录或查看配置动作。
-- 业务已有风险、提醒、负责人、最近动态、洞察或下一步建议时可以用于右侧；没有这些内容则收窄或移除空栏。
+- 右侧补充风险、提醒、负责人、最近动态、业务洞察或下一步建议。
 
 圆角、间距与呼吸感门禁：
 
-- 卡片、控件、浮层与标签按主题的用途映射取圆角，不能统一使用一个大圆角；未定义项可参考业务卡片 20-24px、控件 10-14px。
-- 密度与主题和业务任务一致；主题未定义时参考页面边距 20-28px、gap 12-18px、padding 22-28px、列表行 44-56px、主操作 36-40px，不把这些数值当作所有主题的硬门槛。
-- 页面布局按主题保留稳定分组间隔，主题未定义时可参考 14-24px；区块内部文本、按钮和状态标签不能贴边；同一组信息内部更紧凑，跨组信息通过间距、浅底条或细线分开。
+- 卡片圆角范围 0-32px；业务卡片默认 20-24px，主面板、抽屉和重点容器默认 22-32px，输入框、选择器和按钮 10-14px，状态标签 999px。
+- 圆润形状必须配合紧凑密度：页面边距 20-28px，卡片和卡片的 gap 12-18px 且必须小于 20px，卡片 padding 22-28px 且必须大于 20px，列表行 44-56px，主操作高度 36-40px。
+- 页面布局必须有呼吸感：首屏主区、列表区、右侧上下文和操作条之间保留 14-24px 稳定间隔；区块内部文本、按钮和状态标签不能贴边；同一组信息内部更紧凑，跨组信息通过间距、浅底条或细线分开。
 - 呼吸感不是低密留白：如果某个红框区域只有 1-2 行内容却占据大块高度，必须压缩高度、改成薄行/侧栏/工具条，或补充真实业务信息和下一步动作。
 - 空态高度默认 88-120px 内；超过 120px 时必须包含解释、下一步动作、示意图或配置入口，超过 160px 的纯空白卡不通过。
 - 截图验收时，如果红框区域内部内容少于 3 个信息点或 1 个动作，必须压缩高度/宽度，或补充最近记录、动态、风险、负责人、说明和下一步动作。
 
 ## 4. 主题一致性门禁
 
-- 图标与紧贴的底色一起配色：无底盒时用可读文字色，浅底配深图标，实色底按实际对比度选前景，不能默认白色就清楚。业务图标与相邻底色至少达到 3:1；保留品牌主色，优先调整局部前景或底盒。
-- 在页面中核对图标的最终颜色、描边/填充和父级透明度，覆盖默认、悬停、选中与暗色状态。渐变、图片和半透明底色检查最难辨认的位置，必要时加稳定底色；不能靠阴影或加粗描边代替配色修正。CLI 只检查设计中已登记的配色，不能代替实际画面验收。
-- 按 [共用主题与验收规则](application-theme-consistency.md) 核对全局风格已写入变量、自定义页引用相同角色，并分别检查已有原生页和自定义页；只有资源绑定证据时标记视觉待验证。
-
-- 导航、按钮、指标和图表按项目颜色角色搭配，不以全部同色为验收标准；对照整页检查主次、颜色面积、前景可读性和跨页一致性，模板默认色不能覆盖项目设计。
+- 平台导航可见时，页面主按钮、链接、选中态、重点标签和图表主序列跟随应用主题。
 - 模型生成的业务色相只作为辅助色、浅背景、图表第二序列或装饰气质；最终以当前项目 `design.md` 和应用主题关系为准。
 - 沉浸页、自绘壳、独立品牌页、活动页和公开落地页使用当前应用主题，差异通过布局、材质、素材和构图表达。
 - 默认业务页使用 light 模式；暗色只用于用户明确说暗色、夜间、高对比、黑金或暗色科技风。
@@ -60,19 +67,22 @@
 
 需要“玻璃感、质感、高级、丰富、惊艳、驾驶舱、工作台打磨、卡片太平、页面太空”时，`design.md` 必须写清视觉层次，不建议只输出无层次的白底白卡。PRD 只引用 `design.md` 中的相关章节。
 
-在正文相应章节说明以下设计含义，避免再建立一份字段副本：
-
-- 画布、表面与层次：背景、内容面、边界、阴影、共容器或留白如何区分内容。
-- 色彩角色：品牌、辅助、语义、图形与中性色分别服务什么信息。
-- 形状与密度：容器、控件、浮层的圆角、内距、组间距与信息行高如何消费主题 token。
-- 呼吸节奏：组内/组间关系、内容安全内距、空内容压缩与移动端重排。
-- 需要玻璃或光效时：材质参数、背景关系、文字对比与动效降级。
+| 字段 | 必须写清 |
+| --- | --- |
+| `backgroundLayer` | 页面底色、背景 primitive、顶部不规则色块、柔和光洗、细线装饰、弱纹理、动效静态降级和对比度；推荐避免无层次的纯空白背景 |
+| `surfaceMaterial` | 玻璃、实色、细线面板、浅底条或列表行；玻璃要写 `rgba`、`backdrop-filter`、边框和阴影角色 |
+| `surfaceContrast` | 页面背景与卡片背景的层次搭配；背景和卡片不可相近或相同，必须写清边框、色差或玻璃材质 |
+| `colorRoles` | 主色、辅助色、语义色、图表色、弱背景色分别服务什么业务含义 |
+| `depthRule` | 哪些区块有阴影/模糊/边框，哪些区块保持平面，避免全页同一种卡片 |
+| `densityRule` | 页面边距、卡片 gap、状态摘要高度、列表行高、卡片 padding、空态高度和何时压缩空白 |
+| `breathingRule` | 首屏分组节奏、区块间距、内容安全内距、贴边修正、空白压缩条件和移动端折叠后间距 |
+| `roundedRule` | 业务面板、主面板、控件、标签、抽屉和弹层的圆角数值 |
 
 背景层推荐要求：
 
 - 页面根容器推荐避免无层次的纯空白画布；可使用 `softTintCanvas`，也可使用近白画布 + 淡渐变、细线、星芒、局部装饰、插图或内容密度形成背景感。
-- 页面背景与内容层次符合主题定义；色差、细边框、共容器和留白都可承担分组，不能用通用浅底白卡或强投影覆盖已选主题。
-- 背景 primitive 仅在主题或用户需要时启用：`topIrregularWash`、`radialGlowWash`、`flowLight` 或 `organicNoise`；平整画布主题无需加装饰。
+- 页面背景与卡片背景必须形成明显层次对比，不可相近或相同；默认背景保持浅色调，并按白色/浅色背景配有边框卡片、浅灰背景（如 `#F3F4F6`）配白色无边框卡片、浅彩背景配白色无边框卡片、渐变背景配玻璃感卡片四类方案选择。
+- 展示型页面、工作台、看板、门户、官网、登录页和空状态页推荐选择一种背景 primitive：`topIrregularWash`、`radialGlowWash`、`flowLight` 或 `organicNoise`；极简页面可以不选，但要说明背景感来自哪里。
 - `topIrregularWash` 用在首屏顶部、登录页侧图、品牌页或空状态安全区，可以是波浪、斜切、流体色块、有机边界、轻装饰曲线或图形标记；内容排版仍按规则网格对齐。
 - `radialGlowWash` 是大面积柔和光洗，不是离散装饰圆球、bokeh 或随机漂浮点；不能遮挡文字和控件。
 - `flowLight`、流动线条或光影动效只允许低速、低对比、低透明度，并必须写 `prefers-reduced-motion` 静态降级。
@@ -85,14 +95,14 @@
 - 玻璃面板使用半透明表面、细边框、柔和阴影和 `backdrop-filter`；避免退化成普通纯白不透明卡片。
 - 色彩至少包含应用主色、1-2 个辅助色和稳定语义色；辅助色用于图表、状态或分组，不随机涂满卡片。
 - 卡片、列表、图表和右侧上下文的容器形态要有差异，不能全部是同一种白卡片。
-- 已确定玻璃材质时保持半透明关系；其他主题中的渐变可以搭配主题指定的实色表面。
+- 渐变背景上的卡片必须是玻璃感材质；不能把普通白卡直接贴在渐变背景上。
 
 ## 6. 双文件输出门禁
 
 每个完整应用设计必须输出两份文件：
 
 - `prd/<项目名>/prd.md`：业务、资源、页面结构、数据来源、主操作、顺序和验收。
-- `prd/<项目名>/design.md`：主题 token、视觉特征、布局密度、表面材质、场景配方、组件规则和状态规则。
+- `prd/<项目名>/design.md`：主题 token、视觉 DNA、布局密度、表面材质、场景配方、组件规则和状态规则。
 
 每个 display 页面在 PRD 中必须输出薄 `pageSpecHandoff`，并至少包含：
 
@@ -108,6 +118,8 @@
   - primaryAction：<主操作和打开方式>
 ```
 
-`design.md` 的每个实际自定义页必须有具体八项要点和可定位 anchor。共享视觉、组件与状态规则只写一次；frontmatter 仅保存机器字段与引用索引，不复制正文。
+`design.md` 必须包含 `rootShell`、`prioritySurface`、`statusPrimitive`、`actionPrimitive`、`contentPrimitive`、`contextPrimitive`、`statePrimitive`、`responsiveRule`、`backgroundLayer`、`surfaceMaterial`、`surfaceContrast`、`colorRoles` 和 `depthRule`。
+
+`design.md` 还必须写清 `densityRule`、`breathingRule` 与 `roundedRule`。缺少圆角、间距、呼吸节奏、状态摘要高度、列表行高或空态高度的具体数值时，不能交付给自定义页面实现。
 
-Fast 交接前执行 `openyida check-design <design.md> --prd <prd.md> --json`；PRD 尚未就绪时先做单文件校验，在合并阶段补跨文档检查。Plan 使用同一校验。缺少 `pageSpecHandoff`、设计文件、有效设计引用或真实页面设计时，交接不算完成。
+缺少 `pageSpecHandoff`、缺少 `design.md`、或 `pageSpecHandoff` 没有引用 `designFile/designRefs` 时，视觉设计交接不算完成。