openyida 2026.7.19 → 2026.7.21

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

@@ -1,6 +1,6 @@
 ---
 name: yida-app
-description: 宜搭完整应用开发编排技能。从零搭建应用时使用；默认走 fast_build，创建应用、必要表单、主页面、发布并输出链接。
+description: 宜搭完整应用开发编排技能。对普通 OpenYida 应用做完整搭建或补齐时使用；默认走 fast_build，先解析资源上下文，再创建缺失资源、更新主页面并发布输出链接。
 ---
 
 # yida-app — 完整应用编排契约
@@ -9,17 +9,47 @@ description: 宜搭完整应用开发编排技能。从零搭建应用时使用
 
 ## 触发条件
 
-用户要求从零创建、搭建、生成一个完整宜搭应用/系统/平台/管理工具时使用本技能。
+用户要求从零创建、搭建、生成一个完整宜搭应用/系统/平台/管理工具，或已有 app/page 需要补齐成完整业务系统时使用本技能。
 
 用户说“按默认方案”“不要追问”“直接创建”“尽快搭建”等，必须选择 `fast_build`，用合理 MVP 假设直接执行，不展开深度 PRD 讨论。
 
-**默认判定**：从零搭建完整应用时，只要用户表达“默认方案 / 不要追问 / 直接创建 / 尽快搭建”等快速交付信号，就必须命中 `fast_build`。默认完成链路固定为 `创建应用 → 核心表单 → 主页面 → 编写主页面源码 → 发布 → 返回访问链接`。
+**默认判定**：完整应用搭建或补齐时，只要用户表达“默认方案 / 不要追问 / 直接创建 / 尽快搭建”等快速交付信号，就必须命中 `fast_build`。默认完成链路固定为 `resolve app → resolve forms → resolve main page → create missing resources only → 编写/更新主页面源码 → 发布 → 返回访问链接`。
+
+> 资源边界：本技能只处理普通 OpenYida 资源；若根技能、上下文或 CLI guard 显示目标是 schema-managed，停止本技能并走 schema workflow；目标不明时回到根技能确认。
+
+## 阶段 0：resolve_resource_context
+
+进入 `fast_build` / `full_demo` / `deep_design` 前，先按根技能的 Resource-First 规则解析本次目标 app/page/form/process：
+
+- 来源优先级：本轮显式 `appType` / `formUuid` / URL → agent bound context → workspace config/cache → 会话历史 → 明确从零创建。
+- agent bound context 只是默认候选，不是锁定目标；如果用户本轮明确提到另一个 app/page/form/process，必须重新解析本轮目标，能唯一解析则切换，不能唯一解析才问用户。
+- 已有 app 时在该 app 内补齐资源，不加载 `yida-create-app`；只有无 app 且用户意图允许创建时才创建。
+- 若已有 app 来自 agent 预创建占位资源，先记录 `app.source`、`precreated`、`placeholderName`、`allowRename` 和用户是否要求保留原名，后续在语义应用名稳定后决定是否改名。
+- 已有主页面 URL / `formUuid` / bound page 时，直接写源码并发布到该页面，不加载 `yida-create-page`；已有页面 update path 也必须在本轮源码 Write/Edit 后执行真实 `openyida publish <source> <appType> <displayPageFormUuid>`，只有缺少 display page 且本次意图允许新增页面时才创建。
+- 已有表单 context 时，字段诉求走 `yida-create-form-page` 的 update/patch/rule/bind-datasource；只有已有 app 但缺少业务数据表时才 create form。
+- 已有流程表单或 `processCode` 时，流程诉求走 `yida-process-rule`；只有没有表单/流程且用户要新建审批表单时才进入 `yida-create-process`。
+- 多个同优先级候选、当前轮显式资源冲突或目标不明时才问用户；不要因为 cache 和历史里同时存在资源就默认打断。
+
+该阶段只决定普通 OpenYida resource context；schema-managed 路径仍以 schema CLI 的 validate/plan/apply 结果为准。schema-managed create/update 必须停在当前 `planId`，等待用户显式批准后才可执行 `apply`；`nextAction`、错误恢复或本技能判断都不能授予 `mixed/write`。Phase 1 中 report、automation、page config、delete、pull 不从 Manifest fallback 到本技能的 legacy workflow。
+
+## 阶段 1：resolve app name / rename placeholder app
+
+完成最小需求分析后，先确定稳定语义应用名（如“访客管理系统”“CRM 客户管理系统”），再进入表单或页面创建/更新。若目标 app 来自 agent 预创建占位资源，且满足以下条件，必须复用当前 `appType` 并执行改名：
+
+- `app.source === "agent_bound"`；
+- `precreated === true`，或当前名称 / `placeholderName` 命中“新应用 / 未命名 / 占位 / APP_xxx”等占位样式；
+- `allowRename !== false`；
+- 用户没有明确要求“保持应用名称不变”或指定保留原名称；
+- 目标不是 schema-managed；
+- 已从本轮需求得到稳定语义应用名，且该名称不是占位名。
+
+命令固定使用现有 CLI：`openyida update-app <appType> --name "<语义应用名>"`。该调用应在创建表单/页面前执行；若受信息收集顺序限制，最晚在发布前执行。不要在本技能中重写平台 API，不要加载 `yida-create-app` 处理改名，不要按标题发现/adopt 其他应用，不要 cleanup orphan，不要对已命名的真实业务应用自动改名，不要把 schema-managed 资源交给 legacy `update-app`。
 
 ## 模式
 
 | 模式 | 何时使用 | 目标 |
 |------|----------|------|
-| `fast_build` | 默认；用户要求不追问/直接创建 | 创建应用、必要表单、主页面，发布并输出访问 URL |
+| `fast_build` | 默认；用户要求不追问/直接创建 | 复用已解析资源，只创建缺失且允许创建的应用/表单/页面，发布并输出访问 URL |
 | `full_demo` | 用户明确要演示完整、示例数据、导航整理、可点验收 | 在 `fast_build` 后补导航、示例数据、公开访问或截图 |
 | `deep_design` | 用户明确要深度产品设计、视觉方向、多角色、多页面、复杂流程 | 先做详细 PRD/应用体验蓝图/视觉决策，再执行多阶段搭建 |
 
@@ -48,7 +78,7 @@ description: 宜搭完整应用开发编排技能。从零搭建应用时使用
               ↓
 [Step 6] 编写自定义页面代码 → 默认 use_skill("yida-canvas-custom-page", "生成 Code Canvas 主页面")
               ↓      先写业务化 page-spec.json，再 openyida generate-page <模板> --theme-profile yida-app-theme --theme-scope page --spec <page-spec.json> --compile
-              ↓      需要真实数据时在 spec.dataBinding 写 appType/formUuid/字段映射；深度接入再加载 yida-canvas-data-binding
+              ↓      本轮已创建/解析业务表单且页面需要列表/看板/详情数据时，必须在 spec.dataBinding 写 mode=form + 真实 appType/formUuid/fieldId；深度接入再加载 yida-canvas-data-binding
               ↓      明确要求普通自定义页面 JSX/Jsx 组件链路，或强依赖 this.$ / this.utils.yida.* / this.dataSourceMap 等实例桥时选择 yida-custom-page
               ↓
 [Step 7] 发布页面 → use_skill("yida-publish-page", "发布主页面") → openyida publish <源文件路径> <appType> <formUuid> [--health-check]
@@ -79,13 +109,21 @@ UI 不是独立替代主流程的步骤，而是按模式插入到页面生成
 - 用户明确要求普通自定义页面 JSX/Jsx 组件链路，或页面强依赖普通自定义页实例桥时，选择 `yida-custom-page`：`this.$(fieldId)` 双向绑定、`this.utils.yida.*`、`this.dataSourceMap`、表单提交或流程发起与页面实例深度耦合。
 - 普通自定义页面使用 `.oyd.jsx`、`renderJsx()`、`check-page` / `compile`，发布为平台 `Jsx` 组件；Code Canvas 使用 `.canvas.jsx`、`YidaComp`、`openyida generate-page ... --compile` 或 Canvas 本地快检，发布为 `YidaCodeCanvas` 组件。
 
+## 页面源码修改发布闭环
+
+完整应用、补齐应用和已有主页面 update path 都按同一个 doneWhen 判断：
+
+- 只要本轮 Write/Edit/Create 了 `project/pages/src/*.{canvas.jsx,canvas.tsx,oyd.jsx,jsx,tsx}`，阶段 5 的本地源码校验只算“可发布”，不算远端页面完成。
+- final 前必须经过 `yida-publish-page`，并看到成功的 `openyida publish <source> <appType> <displayPageFormUuid>` 命令结果；发布的 `<source>` 必须是本轮修改过的页面源码，`<displayPageFormUuid>` 必须是已解析的 display 自定义页面。
+- 如果没有 publish 成功证据，只能对用户说明“源码已修改，尚未发布”，不得声称“页面已更新 / 已重新发布 / 已上线”。规则归页面技能，完成证据归 publish guard，不能靠 final 口头补齐。
+
 ## Sample 与业务页边界
 
 `openyida sample` 和 `openyida generate-page <模板>` 只能提供可编译骨架、运行时契约和 primitive 结构，不能当成真实业务页面的最终稿。生成应用时必须把用户需求转成业务化 `page-spec.json`，至少覆盖：
 
 - `brandName` / `tagline` / `heroText`：使用当前应用的业务名称、角色和问题域，不沿用模板默认标题。
 - `features`：写真实业务对象、模块入口或处理事项，不写“统一入口 / 状态跟进 / 流程闭环”这类通用模板卖点。
-- `metrics`：写贴合场景的指标口径；没有真实数据时也要使用业务占位口径，并在 `dataBinding.seedStrategy` 标明演示数据。
+- `metrics` / 列表 / 看板 / 详情数据：写贴合场景的指标口径；完整应用或真实交付页不得用前端 seedRows 冒充真实业务记录。本轮已有业务表单时必须写 `dataBinding.mode=form`、真实 `appType/formUuid` 和字段映射；若需要演示数据，先通过表单数据写入链路创建 demo/mock records，再让 Canvas 页面读取这些真实表单记录。没有写入 demo records 且没有真实数据时，页面展示空态、表单入口、刷新/登记按钮，并在 final 明确“未接真实表单数据”。
 - `roadmap` 或 `interactionProfile`：写用户动作、筛选、下钻、批量处理、空/载/错状态。
 - `visualProfile`：写一个区别于 sample 的视觉方向，例如信息密度、构图节奏、强调色来源、图表/列表/队列母题。
 - 官网/品牌页还必须写 `assets` 或明确素材缺口；看板/列表/详情页优先写 `dataBinding`、字段映射或表单链接。
@@ -117,13 +155,14 @@ UI 不是独立替代主流程的步骤，而是按模式插入到页面生成
 
 | 阶段 | 子技能 | 必做动作 | doneWhen |
 |------|--------|----------|----------|
-| 1. 创建应用 | `yida-create-app` | `openyida create-app`，提取 `appType` | 拿到真实 `appType` |
-| 2. 记录最小需求 | 无 | 写 `prd/<项目名>.md`：只记录 MVP 假设、核心表单/页面、完成标准；写 `.cache/<项目名>-schema.json` 初始骨架；不要写长 PRD。多页面或复杂角色只在 `deep_design` 中补应用体验蓝图 | 业务语义和 ID 存储位置明确 |
-| 3. 创建必要表单 | `yida-create-form-page` | 只创建支撑 MVP 的核心表单；生成表单 schema 前必须先加载该技能；字段配置文件写入 `.cache/openyida/<项目名>/` | 拿到表单 `formUuid` 和真实 `fieldId` |
-| 4. 创建主页面 | `yida-create-page` | 创建一个用户主入口页面，通常是工作台/看板/列表入口 | 拿到页面 `formUuid` |
-| 5. 编写页面 | 默认 `yida-canvas-custom-page`；明确要求 JSX/Jsx 组件链路或实例桥强依赖时选择 `yida-custom-page` | 生成主页面源码；只实现 MVP 首屏和核心操作。可用已创建表单链接、轻量统计占位、基础列表/入口布局完成主页面；不要加载视觉/密度/报表/数据源等额外技能 | 本地源码通过对应页面链路的基础校验 |
-| 6. 发布页面 | `yida-publish-page` | 按页面链路校验后发布：Canvas `.canvas.jsx` 使用 `openyida publish` 的 Canvas 编译阶段或 `compileCanvasLocal` 快检；普通自定义页面 `.oyd.jsx` / `.jsx` 跑 `check-page` / `compile`；再发布主页面 | 发布成功并获得可访问 URL |
-| 7. 输出结果 | 无 | 返回应用链接、主页面链接、已创建资源摘要、后续可选项 | 用户拿到 URL |
+| 0. 解析资源上下文 | 无 | 合并本轮显式资源、agent bound context、workspace config/cache、会话历史；本轮显式目标覆盖 bound context；判定 app/page/form/process 的 `source` 和 `allowCreate` | 明确复用、创建缺口或需要 ask_human |
+| 1. resolve app + app name | `yida-create-app` 仅在 app 缺失且允许创建时加载；`openyida update-app` 仅用于预创建占位 app 改名 | 已有 `appType`/应用 URL/bound app 时直接复用；若 bound/precreated app 仍是占位名，在语义名稳定后执行 `openyida update-app <appType> --name "<语义应用名>"`；否则创建应用并提取真实 `appType` | 拿到真实目标 `appType`，预创建占位 app 已改成语义名或明确跳过，且不会重复创建同类 app |
+| 2. 记录最小需求 | 无 | 写 `prd/<项目名>.md`：只记录 MVP 假设、核心表单/页面、完成标准；写/更新 `.cache/<项目名>-schema.json` standalone 映射；不要写长 PRD | 业务语义和 ID 存储位置明确 |
+| 3. resolve forms | `yida-create-form-page` | 已有目标表单时 update/patch/rule/bind-datasource；缺少支撑 MVP 的核心表单且允许创建时才 create；字段配置文件写入 `.cache/openyida/<项目名>/` | 拿到或确认表单 `formUuid` 和真实 `fieldId` |
+| 4. resolve main page | `yida-create-page` 仅在主页面缺失且允许创建时加载 | 已有页面 URL / `formUuid` / bound page 时直接作为主页面；否则创建一个用户主入口 display page | 拿到真实目标页面 `formUuid`，且不会重复创建页面 |
+| 5. 编写/更新页面 | 默认 `yida-canvas-custom-page`；明确要求 JSX/Jsx 组件链路或实例桥强依赖时选择 `yida-custom-page` | 生成或修改主页面源码；只实现 MVP 首屏和核心操作。可用已解析表单链接、真实空态、表单入口和轻量指标口径完成主页面；若展示业务列表/看板/详情记录，必须接本轮真实表单 `dataBinding.mode=form`，或先写入 demo records 后再读取；不要加载视觉/密度/报表/数据源等额外技能 | 本地源码通过对应页面技能的基础校验；未执行 publish 时仍是“源码已修改，尚未发布” |
+| 6. 发布页面 | `yida-publish-page` | 按页面链路校验后发布到已解析主页面：Canvas `.canvas.jsx` 使用 `openyida publish` 的 Canvas 编译阶段或 `compileCanvasLocal` 快检；普通自定义页面 `.oyd.jsx` / `.jsx` 跑 `check-page` / `compile`；再执行 `openyida publish <source> <appType> <displayPageFormUuid>` 发布主页面 | 发布成功并获得可访问 URL |
+| 7. 输出结果 | 无 | 返回应用链接、主页面链接、复用/创建/更新的资源摘要、后续可选项 | 用户拿到 URL |
 
 `fast_build` 不默认执行：`yida-page-uiux`、`yida-app-uiux`、`yida-canvas-data-binding`、`yida-data-source-connectors`、`yida-data-management`、`yida-nav-group`、`yida-dashboard`、导航重排、示例数据、截图验收、公开访问配置、深度 UI 设计、长 PRD、TaskCreate / 继续规划任务，也不默认读取 `references/app-build-contract.md`。
 
@@ -176,6 +215,7 @@ UI 不是独立替代主流程的步骤，而是按模式插入到页面生成
 
 - 默认页面源码不得使用 `this.dataSourceMap.*`，除非本轮已经明确创建并绑定对应设计器数据源。
 - 默认页面只走两类可闭环方案：入口型页面（表单入口、资源链接、轻量统计占位）或内置数据 API 页面（`this.utils.yida.searchFormDatas` / `saveFormData` 等查询本轮已创建表单）。
+- Canvas 列表/看板/详情页的业务记录不得回退到前端 seedRows 冒充真实数据。`openyida sample` 原样发布可以显示 sample/seed 并标注；完整应用交付页必须优先在 `page-spec.json` 中写 `dataBinding.mode=form`，用本轮真实 `appType/formUuid/fieldId` 读取表单。若用户要求可演示数据，先加载数据写入链路把 demo/mock records 写入表单并抽查，再由 Canvas 读取；没写入记录时展示空态和登记入口。
 - 如果页面源码确实需要 `this.dataSourceMap.*`，必须先把模式升级为可选数据源链路：加载 `yida-data-source-connectors`，创建/绑定数据源，并在发布后确认页面 Schema 中存在对应数据源；否则 `fast_build` 未完成。
 - 发布输出出现 `No custom page data sources to preserve` 时，只有源码不依赖 `this.dataSourceMap.*` 才能视为正常；若源码依赖 dataSourceMap，必须改源码或补数据源后重新发布。
 
@@ -209,9 +249,11 @@ UI 不是独立替代主流程的步骤，而是按模式插入到页面生成
 
 1. 主页面发布成功；
 2. 输出可访问 URL；
-3. 输出真实 `appType`、页面 `formUuid`、核心表单 `formUuid` 摘要；
+3. 输出真实 `appType`、页面 `formUuid`、核心表单 `formUuid` 摘要，并标明关键资源是复用、创建还是更新；
 4. 未继续执行可选后置动作。
 
+若本轮修改过页面源码但没有成功执行 `openyida publish <source> <appType> <displayPageFormUuid>`，完整应用仍未达到 doneWhen；只能交付本地源码修改说明和未发布原因，不能宣称远端主页面已更新。
+
 发布成功并拿到访问 URL 后即完成，不要继续 TaskCreate、重复读技能、重复规划后续阶段。
 
 ## 错误处理
@@ -219,6 +261,10 @@ UI 不是独立替代主流程的步骤，而是按模式插入到页面生成
 - 不编造 `appType`、`formUuid`、`fieldId`、`reportId`。
 - 同一命令失败后，必须改变登录态、组织、参数、输入文件或字段 ID 后才能重试；禁止无修改连续重试。
 - corpId 与目标组织不一致时先停下，让用户选择重新登录或在当前组织继续。
+- 已有目标 app/page/form/process 时默认复用；只有用户明确要求新建另一个同类资源，或目标缺失且本次意图允许创建时，才加载 create 类子技能。
+- 当前轮用户明确指定的资源优先于 agent bound context；例如会话绑定页面 A、用户要求修复页面 B 时，先解析 B，不能唯一解析才问用户，不要默认改 A。
+- agent 预创建占位 app 只作为默认资源；满足改名条件时只调用 `openyida update-app` 修正语义名，不创建新 app，不改非占位真实业务 app。
+- 多个同优先级资源候选或当前轮显式资源冲突时，先问用户确认目标，不要通过重复创建规避冲突。
 - 输入 JSON/YAML/CSV/JSX 等业务文件必须用结构化文件写入工具创建，不用 shell heredoc、`cat`、`echo`、`printf`、`tee` 或重定向。
 - 用户要求删除应用时，必须展示应用名称、应用 ID、影响范围，并等待用户明确回复“确认删除”后才可执行。
 

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

@@ -86,10 +86,11 @@ openyida sample yida-canvas-custom-page portal-native-components --output projec
 
 1. **Canvas 入口明确**：源码必须导出或返回 `YidaComp`，并把主组件作为默认导出或 `YidaComp` 暴露。
 2. **发布链路正确**：Canvas 源码使用 `.canvas.jsx` / `.canvas.tsx`，或发布时显式加 `--canvas`。
-3. **依赖可加载**：普通 import 只使用 Code Canvas 白名单依赖；宜搭运行态组件走原生组件桥。
-4. **不使用普通页实例契约**：Canvas 中不写 `renderJsx()`、`didMount()`、`this.forceUpdate()`、`this.utils.yida.*`、`this.dataSourceMap`。
-5. **副作用清理**：`useEffect` 注册事件、定时器、图表实例时必须返回 cleanup。
-6. **交互控件必须受控且真正驱动数据**：凡是暗示“会改变下方数据/视图”的控件（筛选 `Select`、搜索 `Input`/`Input.Search`、周期切换、`Tabs`/`Segmented`、批量/重置 `Button` 等），禁止只写 `defaultValue` 当装饰。必须用 `useState` 建立受控状态、绑定 `onChange`/`onClick`，并让 `Table`/列表/卡片的数据源经过基于该状态的 `useMemo` 派生过滤后再渲染。**反例（会导致“点了筛选下面数据不变”）**：把固定 `seedRows` 直接喂给 `<Table dataSource={rows} />`，同时摆一排 `defaultValue` 且无 `onChange` 的筛选控件。切换筛选后若可能让当前选中项失效，需回退选中态（如 `selected < filteredRows.length ? selected : 0`）。
+3. **源码修改发布闭环**：只要本轮 Write/Edit/Create 了 `project/pages/src/*.canvas.jsx` 或 `project/pages/src/*.canvas.tsx`，本技能的本地校验只证明源码可发布，不等于远端页面已更新；final 前必须看到成功的 `openyida publish <source> <appType> <displayPageFormUuid>`。没有 publish 成功证据时，只能说“Canvas 源码已修改，尚未发布”，不能说“页面已更新 / 已重新发布”。
+4. **依赖可加载**：普通 import 只使用 Code Canvas 白名单依赖；宜搭运行态组件走原生组件桥。
+5. **不使用普通页实例契约**：Canvas 中不写 `renderJsx()`、`didMount()`、`this.forceUpdate()`、`this.utils.yida.*`、`this.dataSourceMap`。
+6. **副作用清理**：`useEffect` 注册事件、定时器、图表实例时必须返回 cleanup。
+7. **交互控件必须受控且真正驱动数据**：凡是暗示“会改变下方数据/视图”的控件（筛选 `Select`、搜索 `Input`/`Input.Search`、周期切换、`Tabs`/`Segmented`、批量/重置 `Button` 等），禁止只写 `defaultValue` 当装饰。必须用 `useState` 建立受控状态、绑定 `onChange`/`onClick`，并让 `Table`/列表/卡片的数据源经过基于该状态的 `useMemo` 派生过滤后再渲染。**反例（会导致“点了筛选下面数据不变”）**：把固定 `seedRows` 直接喂给 `<Table dataSource={rows} />`，同时摆一排 `defaultValue` 且无 `onChange` 的筛选控件。切换筛选后若可能让当前选中项失效，需回退选中态（如 `selected < filteredRows.length ? selected : 0`）。
 
 ### 重要规则（IMPORTANT）
 
@@ -102,6 +103,16 @@ openyida sample yida-canvas-custom-page portal-native-components --output projec
 7. **light 页面禁灰黑主题**：业务列表、协同表、数据管理页、工作台和门户默认不要用 `#111827` 这类近黑色做按钮、描边、选中态或大阴影；主操作、选中态、筛选焦点和批量操作使用品牌色或 sample 自带主题色，边框用浅色品牌混合。只有用户明确要求暗色大屏/夜间模式/高对比风格时才使用深色主视觉。
 8. **门户运行态组件要补必需 props 和局部降级**：`QuickAccessCard` / `RecentlyUsedCard` 必须传 `theme="row-white"` 等必需 props，避免运行态读取 `theme.includes(...)` 报错；所有门户/字段/上传增强组件外层加局部 ErrorBoundary，单个组件不兼容时只降级该块，不让整页进入 Canvas 错误态。
 9. **自定义主题必须页面内注入**：`--theme` 只接受平台预置 key；如果页面设计使用非预置主题（例如活力橙、深玫红、自定义暗黑金），Canvas 页面必须在自身源码中注入 `style#yida-global-theme` 或等价 scoped CSS vars，并在根节点设置 `data-theme-scope="page"`。官方 sample 每个页面都要做，避免宿主应用 `black` 主题把页面染成黑灰。
+10. **真实交付不使用前端 seed 冒充业务数据**：`openyida sample` 原样发布可以保留 sample/seed 数据，但必须在页面上标注为 sample/seed。完整应用或真实交付页只要需要列表、看板、详情记录，并且本轮已经创建/解析业务表单，就必须在 `page-spec.json` 写入 `dataBinding.mode=form`、真实 `appType/formUuid` 和字段映射，让页面从表单读取。若需要演示数据，先通过表单数据写入链路创建 demo/mock records，再由 Canvas 读取这些真实表单记录；未写入 demo records 且没有真实数据时展示空态、表单入口、刷新/登记按钮。
+
+## 数据真实性边界
+
+Canvas 模板有两种允许状态：
+
+- **Sample / 离线预览**：`openyida sample` 或模板原样发布可以显示内置 seedRows，页面必须标注 `sample/seed`，final 也要说明“当前为演示数据/未接真实表单数据”。
+- **完整应用 / 真实交付**：先解析真实 `appType/formUuid/fieldId`，写入 `page-spec.json` 的 `dataBinding.mode=form` 后再 `openyida generate-page ... --spec <page-spec.json>`。需要 demo/mock 记录时，先用数据写入链路把记录写入表单并抽查，再让页面读取；不能把前端 seedRows、静态 DEFAULT_FEATURES 或固定指标说成真实业务数据。
+
+生成后如果 `.openyida-page.json` 的 `dataBinding.enabled !== true`，且页面仍展示列表/看板/详情业务记录，只能标为 sample/draft；完整应用 final 不得说“已接真实数据”。未接数据的交付页应保留真实空态、登记入口、刷新按钮和数据接入提示。
 
 ## 模板占位符防回归
 
@@ -132,7 +143,7 @@ npx jest tests/canvas-compile.test.js tests/generate-page.test.js --runInBand
 - **说清参考转译**：交付 sample 改造时要用 1-2 句话说明参考被转译成了什么，例如“详情页采用对象 hero + sticky 元信息 + 时间线结构”、“数据管理页采用多维表工具栏 + 分组行 + 彩色标签密集表格”。不要只说“已参考 Dribbble”。
 - **每页独立主题**：sample 页默认 `themeScope=page` 或等价固定 CSS 变量；业务列表、详情、门户、工作台、官网、数据管理、大屏要有不同色相和不同信息节奏，不被宿主应用主题统一染色。
 - **非预置主题不走 `--theme`**：`deepBlue/podBlue/.../black` 这些平台 key 才能传给 `--theme`；自己设计的主题色要写到页面 `style#yida-global-theme` / scoped token 中，并确保每个 sample 页面都有这段注入。
-- **数据要像真实业务**：列表、详情、数据管理、工作台、大屏必须模拟足够丰富的数据、状态、筛选、趋势、分组、时间线或指标，不要只放 3 个卡片和空泛文案。
+- **Sample 数据要像真实业务，但不能冒充真实交付数据**：列表、详情、数据管理、工作台、大屏 sample 必须模拟足够丰富的数据、状态、筛选、趋势、分组、时间线或指标，不要只放 3 个卡片和空泛文案；完整应用/真实交付页必须优先接 `dataBinding.mode=form` 或展示真实空态，不把 sample seed 当业务主列表。
 - **工作台不是 demo 壳**：工作台页面要铺满应用内容区，侧栏/导航/主面板形成真实产品首页；禁止用 `max-width + margin: 0 auto + 外层 padding` 做居中展示框，也不要把 `dribbble research`、`sample`、`workbench + operation` 这类设计过程词露给用户。
 - **数据大屏地图要稳定**：大屏中心态势图如果是地图，不能只依赖外部 ECharts CDN / GeoJSON 成功后才显示；优先探测宜搭宿主地图组件（如 `YoushuMap` / `ChinaMap` / `MapChart` 等），并提供内置区域地图组件兜底。禁止把“地图组件暂不可用”作为正常展示态暴露给用户。
 - **截图问题要反哺模板**：用户指出导航未覆盖、地图抽象、颜色不好、内容不丰富、产品首页不像首页等问题时，不只修当前 JSX；如果属于模板共性，补到 sample 模板、测试或本技能规则。
@@ -161,14 +172,14 @@ openyida sample yida-canvas-custom-page portal-native-components --output projec
 # 4. 本地 Canvas 快检
 node -e "const fs=require('fs'); const {compileCanvasLocal}=require('./lib/app/canvas-compile'); const src=fs.readFileSync('project/pages/src/<页面名>.canvas.jsx','utf8'); console.log(compileCanvasLocal(src).importedModules)"
 
-# 5. 发布
+# 5. 发布（本轮修改源码后的远端完成证据）
 openyida publish project/pages/src/<页面名>.canvas.jsx <appType> <formUuid>
 
 # 6. 发布后回读 Schema 验收
 openyida get-schema <appType> <formUuid> > .cache/openyida/<页面名>-schema.json
 ```
 
-`openyida check-page` / `openyida compile` 当前面向普通自定义页面 `.oyd.jsx` / `.jsx`；Canvas 以 `compileCanvasLocal` 和 `openyida publish .canvas.jsx` 的 Canvas 编译阶段为准。
+`openyida check-page` / `openyida compile` 当前面向普通自定义页面 `.oyd.jsx` / `.jsx`；Canvas 以 `compileCanvasLocal` 和 `openyida publish .canvas.jsx` 的 Canvas 编译阶段为准。`compileCanvasLocal` 是发布前快检，不能替代 `openyida publish` 的远端写入证据。
 
 如需保存完整 Schema，使用 create_file / Write / file edit tool 创建 `<projectRoot>/.cache/openyida/<页面名或任务名>/<页面名>-schema.json`；从 workspace 根执行后续命令时路径加 `project/` 前缀。不要把 `openyida` stdout 通过 shell 重定向保存成 JSON。
 

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

@@ -41,7 +41,7 @@ OpenYida `generate-page --spec` 支持把 Canvas 数据契约写成结构化 `da
 
 - `mode=form` 必须来自真实 `appType/formUuid` 和字段 ID，不要猜字段。
 - `mode=connector/url` 必须使用同源代理端点，不把第三方密钥放进 Canvas 源码。
-- `mode=seed` 只能作为演示，不能标注“已接真实数据”。
+- `mode=seed` 只能用于 `openyida sample`、离线预览或明确标注的演示页，不能标注“已接真实数据”；完整应用/真实交付页需要演示记录时，先把 demo/mock records 写入真实表单，再用 `mode=form` 读取。
 - 模板生成的 `DataBridge` 状态要保留，方便线上排查“接口没通 / 结构没识别 / 权限不足”。
 
 ## 可复用读数据 Hook
@@ -194,7 +194,7 @@ function normalizeFormRow(row) {
 
 保护规则：
 
-- 首屏可以用 seed 数据做本地预览兜底，但真实接口返回后必须以接口为准。
+- 首屏只有 sample/离线预览可以用 seed 数据做本地预览兜底；真实交付页未接表单数据时展示空态和登记入口，不用 seedRows 冒充业务记录。真实接口返回后必须以接口为准。
 - 如果 `getTotalCount(json) > 0` 且 `unwrapRows(json).length === 0`，抛出“接口返回结构未识别”，不要展示“暂无数据”。
 - 用 `openyida data query form <appType> <formUuid> --size 20` 或数据管理页核对总数，页面统计必须和真实表单一致。
 
@@ -342,7 +342,7 @@ function fieldOf(row, fieldId) { return (row.formData || row)[fieldId]; }
 1. **把 Code Canvas 当普通自定义页面写**：Canvas 没有 `this.utils.yida.*` / `dataSourceMap`，必须自写 HTTP 桥。
 2. **CSRF 来源取错**：只从 `document.cookie` 找 token 会失败，因为 Cookie 可能是 HttpOnly；应从 `window.g_config` 取页面上下文 token。
 3. **响应结构只解析一层**：表单查询可能返回 `content.result.data` 这类多层包裹，页面只读 `json.data` 就会显示 0 条。
-4. **Demo 数据掩盖真实错误**：seed 数据让页面看起来“有内容”，但没有证明接口数据真的接入；真实数据页必须用 `totalCount` 做保护。
+4. **Demo 数据掩盖真实错误**：seed 数据让页面看起来“有内容”，但没有证明接口数据真的接入；真实数据页必须用 `totalCount` 做保护，接口异常或未接 dataBinding 时展示错误/空态，不回退成漂亮 demo 列表。
 5. **刷新策略不对**：多人状态同步需要 5 秒左右轮询，但轮询只能刷新数值和列表，不能整页 reload，也不能首屏之后反复清空旧数据。
 6. **排序口径混淆**：数据存在但按点赞排行时，0 赞新数据可能排在后面；验收时要同时看总数和列表排序规则。
 

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

@@ -14,7 +14,13 @@
 - `draft-needs-domain-spec`：用户已有业务要求，但 page spec 仍缺业务对象、指标、交互或视觉方向；继续补 spec 或改源码。
 - `sample-reference`：基本没有业务化输入，结果只能当 sample 参考，不能交付为真实应用页面。
 
-真实业务页的 `page-spec.json` 不能只写 `template/title/output`。至少写清业务名称与定位、业务模块/对象、指标口径、用户动作或下钻方式、视觉方向；看板/列表/详情优先写 `dataBinding` 或字段映射，官网/品牌页优先写 `assets` 或素材缺口。`sample` 是例子，不是框架；如果 `domainFidelity.sampleFallbacks` 里还出现 `features`、`metrics`、`roadmap`、`heroText` 等关键项，必须继续定制。
+真实业务页的 `page-spec.json` 不能只写 `template/title/output`。至少写清业务名称与定位、业务模块/对象、指标口径、用户动作或下钻方式、视觉方向；看板/列表/详情如果本轮已经创建或解析业务表单，必须写 `dataBinding.mode=form`、真实 `appType/formUuid` 和字段映射，官网/品牌页优先写 `assets` 或素材缺口。`sample` 是例子，不是框架；如果 `domainFidelity.sampleFallbacks` 里还出现 `features`、`metrics`、`roadmap`、`heroText` 等关键项，必须继续定制。
+
+数据真实性边界：
+
+- `openyida sample` 或模板原样发布可以展示 sample/seed 数据，但页面必须标注 sample/seed。
+- 完整应用或真实交付页不能用前端 seedRows 冒充业务记录；需要演示数据时，先把 demo/mock records 写入真实宜搭表单，再由 Canvas 读取。
+- 未写入 demo records 且没有真实数据时，页面应展示空态、表单入口、刷新/登记按钮和 dataBinding 接入提示。
 
 | 用户需求 | CLI 模板 | scene | 视觉要点 |
 | --- | --- | --- | --- |

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

@@ -1,14 +1,30 @@
 ---
 name: yida-create-app
-description: 创建宜搭应用，返回 appType。搭建应用的第一步。适用于从零新建全新应用时。
+description: 创建宜搭应用并返回 appType；仅当没有目标 app 且用户意图允许新建时使用。schema-managed 应用由根技能或明确 context 路由到 schema workflow。
 ---
 
 # 创建应用
 
+> 资源边界：本技能只处理普通 OpenYida 资源；若根技能、上下文或 CLI guard 显示目标是 schema-managed，停止本技能并走 schema workflow；目标不明时回到根技能确认。
+> direct/standalone 路径才可执行本技能；schema-managed 路径必须回到 schema validate → plan → apply，不在本技能内降级写入。
+
+## Resource-First 使用门槛
+
+本技能不是完整搭建的默认第一步，只能在以下条件同时满足时加载/执行：
+
+1. 根技能或 `yida-app` 已完成 `resolve_resource_context`；
+2. 没有从本轮 prompt、应用 URL、agent bound context、workspace config/cache 或会话历史解析到目标 `appType`；
+3. 用户明确要求从零创建应用，或完整搭建缺少 app 且 `allowCreate=true`。
+
+若已解析到 `appType`、应用 URL、bound app 或 workspace 中可确认的 standalone app，必须复用该 app 并继续后续表单/页面/发布步骤，不得调用 `openyida create-app`。若用户说“新建另一个应用”，先确认目标组织和新应用名，再执行本技能。
+
+若该 app 是 yida-agent / 宿主预创建的占位 app（例如名称为“新应用”“未命名”“占位”或 `APP_xxx` 样式，且 context 标记 `source=agent_bound`、`precreated=true`、`allowRename !== false`），也仍然视为“已有目标 app”：不得调用 `openyida create-app`。占位名修正由 `yida-app` 在最小需求分析得到稳定语义应用名后调用 `openyida update-app <appType> --name "<语义应用名>"` 完成；本技能只负责在确实没有目标 app 且允许创建时新建应用。
+
 ## 严格禁止 (NEVER DO)
 - 不要编造 appType，必须从命令返回的 JSON 中提取
 - 不要在未确认 corpId 的情况下创建应用（先运行 `openyida env` 确认登录态）
 - 不要在同一轮已成功创建应用后重复创建。若接口明确返回名称冲突，单点任务先询问用户；`yida-app fast_build` 可追加短后缀重试一次，不要为了查重额外探测。
+- 已有 `appType`、应用 URL、bound app 或 workspace app 时，不要创建新应用；除非用户明确要求新建另一个应用并确认。
 
 ## 严格要求 (MUST DO)
 
@@ -18,8 +34,8 @@ description: 创建宜搭应用，返回 appType。搭建应用的第一步。
 
 ## 适用场景
 
-用户说"创建应用"、"新建系统"、"搭建平台"时使用此技能。
-创建应用后，通常需要继续执行：创建表单（`yida-create-form-page`）→ 创建页面（`yida-create-page`）→ 发布页面（`yida-publish-page`）。
+用户说"从零创建应用"、"新建另一个系统"、"新建应用并返回 appType"，且 resource context 没有目标 app 时使用此技能。
+创建应用后，通常需要继续执行：创建/更新表单（`yida-create-form-page`）→ 创建或复用页面（`yida-create-page` / existing page）→ 发布页面（`yida-publish-page`）。
 后续如果需要自定义页面，默认走 Code Canvas 链路：源码写到 `project/pages/src/<页面名>.canvas.jsx`，通过 Canvas 编译链路发布。用户明确要求普通自定义页面 JSX/Jsx 组件链路，或页面强依赖普通自定义页实例桥（`this.$(fieldId)`、`this.utils.yida.*`、`this.dataSourceMap`、表单提交或字段双向绑定深度耦合）时，选择 `.oyd.jsx` / `.jsx` 并执行 `openyida check-page` / `openyida compile`。
 
 ---
@@ -30,6 +46,8 @@ description: 创建宜搭应用，返回 appType。搭建应用的第一步。
 openyida create-app <appName> [description] [icon] [iconColor] [colour] [navTheme] [layoutDirection]
 ```
 
+`openyida create-app` 不支持 `--json` 参数；不要添加 `--json`。创建成功时命令本身会输出一行 JSON，从该输出中提取 `appType`。
+
 | 参数 | 必填 | 默认值 | 说明 |
 |------|------|--------|------|
 | `appName` | 是 | — | 应用名称 |

package/yida-skills/skills/yida-create-form-page/SKILL.md

@@ -1,16 +1,30 @@
 ---
 name: yida-create-form-page
-description: 表单页面创建与更新，支持 19 种业务字段和 Divider、ColumnContainer 等表单展示布局组件，PageSection/GroupContainer 仅少量特殊场景使用；支持联动规则和数据源绑定。适用于新建表单、设计表单结构、添加或修改表单字段。
+description: 表单页面创建与更新，支持 19 种业务字段和 Divider、ColumnContainer 等表单展示布局组件，PageSection/GroupContainer 仅少量特殊场景使用；支持联动规则和数据源绑定。适用于新建表单、设计表单结构、添加或修改表单字段；schema-managed 表单由根技能或明确 context 路由到 schema workflow。
 ---
 
 # 表单页面创建与更新
 
+> 资源边界：本技能只处理普通 OpenYida 资源；若根技能、上下文或 CLI guard 显示目标是 schema-managed，停止本技能并走 schema workflow；目标不明时回到根技能确认。
+> direct/standalone 路径才可执行本技能；schema-managed 路径必须回到 schema validate → plan → apply，不在本技能内降级写入。
+
+## Resource-First create/update 判定
+
+执行本技能前必须先解析 app/form resource context：
+
+- 已有目标 `formUuid`、表单 URL、bound form，或 workspace cache/config 中可确认的 standalone form 时，字段结构诉求默认走 update/patch/rule/bind-datasource 模式；不要再 create 同名或同类表单。
+- bound form/page 只是默认候选，不是锁定目标；如果当前会话绑定表单或页面 A，但用户本轮明确要求修改 B 的字段，必须先解析 B 对应的表单 `formUuid`。B 能唯一解析时改 B；B 无法唯一解析或字段归属不清时问用户；禁止默认改 A。
+- 已有目标 app 但缺少业务数据表，且用户明确要求“增加客户表 / 新建订单表 / 新增数据收集入口”等，才使用 create 模式创建新表单。
+- 用户给页面 URL 或自定义页面 `formUuid` 且诉求是优化页面 UI 时，改走 `yida-custom-page` + `yida-publish-page`；不要创建表单。
+- 多个表单候选时按根技能来源优先级选择；同级冲突、字段目标不明或无法判断要改哪张表时才问用户。
+
 ## 严格禁止 (NEVER DO)
 
 - 不要编造 formUuid，必须从命令返回的 JSON 中提取
 - 不要在 update / patch / rule / validation / bind-datasource 模式中使用猜测的 fieldId，必须先用 `yida-get-schema` 获取
 - 不要用此命令操作数据记录（增删改查），应使用 `yida-data-management`
 - 不要用 shell heredoc、`cat`/`echo`/`printf`/`tee` 或重定向生成字段、变更、补丁、规则、数据源 JSON 文件
+- 已有目标表单且用户是改字段/联动/属性时，不要创建新表单；必须走 update/patch/rule/bind-datasource。
 - 不要用 `GroupContainer` / `PageSection` 承载普通业务分组；普通分组必须优先用 `Divider`
 
 ## 严格要求 (MUST DO)
@@ -91,6 +105,8 @@ Divider > Field
 
 ## create 模式
 
+仅当目标表单缺失且用户意图允许新增数据收集入口时使用。已有 `formUuid` / 表单 URL / bound form 时禁止使用 create 模式。
+
 ```bash
 openyida create-form create <appType> <formTitle> <fieldsJsonOrFile> [--layout double|card] [--theme compact|comfortable] [--label-align top|left]
 # 文件路径示例：.cache/openyida/<项目名或任务名>/<表单名>-fields.json
@@ -106,6 +122,8 @@ openyida create-form create <appType> <formTitle> <fieldsJsonOrFile> [--layout d
 
 ## update 模式
 
+已有 `formUuid` / 表单 URL / bound form 时优先使用本模式；修改字段前必须用 `openyida get-schema` 确认字段 ID 和当前结构。
+
 ```bash
 openyida create-form update <appType> <formUuid> <changesJsonOrFile>
 # 文件路径示例：.cache/openyida/<项目名或任务名>/<表单名>-changes.json

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

@@ -1,13 +1,26 @@
 ---
 name: yida-create-page
-description: 在宜搭应用中创建自定义展示页面（display 类型），返回 formUuid。适用于需要新建空白自定义页面，后续编写 JSX 代码并发布。
+description: 创建自定义展示页面（display 类型）并返回 formUuid；仅当目标 page 缺失且用户意图允许新增页面时使用。schema-managed 页面由根技能或明确 context 路由到 schema workflow。
 ---
 # 创建自定义页面
 
+> 资源边界：本技能只处理普通 OpenYida 资源；若根技能、上下文或 CLI guard 显示目标是 schema-managed，停止本技能并走 schema workflow；目标不明时回到根技能确认。
+> direct/standalone 路径才可执行本技能；schema-managed 路径必须回到 schema validate → plan → apply，不在本技能内降级写入。
+
+## Resource-First 使用门槛
+
+本技能只负责创建缺失的 display page，不负责优化、修改或重新发布已有页面。执行前必须已经解析 resource context：
+
+- 如果本轮用户给了页面 URL、`formUuid`、bound page，或 workspace cache/config 中已有目标 display page，禁止调用 `openyida create-page`；直接进入 `yida-custom-page` / `yida-canvas-custom-page` 编写或修改源码，再用 `yida-publish-page` 发布到该页面。
+- 如果用户给的是普通表单 `formUuid` 且诉求是改字段结构，改用 `yida-create-form-page`；不要把表单 ID 当作自定义页面创建目标。
+- 只有目标 app 已明确、目标 display page 缺失，并且用户意图允许新增页面（例如“在 APP_xxx 里增加回访页面”）时，才加载并执行本技能。
+- 多个已有页面候选按根技能来源优先级选择；同级冲突或无法判断主页面时才问用户。
+
 ## 严格禁止 (NEVER DO)
 
 - 不要编造 formUuid，必须从命令返回的 JSON 中提取
 - 不要用此命令创建表单页面（带字段的数据收集页），应使用 `yida-create-form-page`
+- 已有页面 URL / `formUuid` / bound page 时，不要创建新页面；除非用户明确要求新增另一个页面并确认。
 
 ## 严格要求 (MUST DO)
 
@@ -19,7 +32,7 @@ description: 在宜搭应用中创建自定义展示页面（display 类型）
 
 ## 适用场景
 
-用户需要创建"自定义展示页面"、"可视化大屏"、"自定义 UI 页面"时使用。
+用户需要创建"自定义展示页面"、"可视化大屏"、"自定义 UI 页面"，且 resource context 未解析到目标页面时使用。
 
 **关键区分**：
 - 自定义展示页面（无字段，纯 JSX/React 开发）→ 本技能
@@ -30,7 +43,7 @@ description: 在宜搭应用中创建自定义展示页面（display 类型）
 **正向触发**：
 - "创建自定义展示页面"、"新建可视化大屏"
 - "创建自定义 UI 页面"、"新建一个页面"
-- 完整应用开发流程中的页面创建步骤（由 `yida-app` 编排调用）
+- 完整应用开发流程中主页面缺失且允许创建的页面创建步骤（由 `yida-app` 编排调用）
 
 ---
 

package/yida-skills/skills/yida-create-process/SKILL.md

@@ -1,14 +1,29 @@
 ---
 name: yida-create-process
-description: 流程表单一体化创建（创建表单 → 转流程 → 获取 processCode → 配置流程）。适用于从零搭建需要审批的流程表单。
+description: 流程表单一体化创建（创建表单 → 转流程 → 配置流程）；仅当无既有流程/表单上下文且用户意图允许新建流程表单时使用。schema-managed 流程由根技能或明确 context 路由到 schema workflow。
 ---
 # 流程表单一体化创建
 
+> 资源边界：本技能只处理普通 OpenYida 资源；若根技能、上下文或 CLI guard 显示目标是 schema-managed，停止本技能并走 schema workflow；目标不明时回到根技能确认。
+> direct/standalone 路径才可执行本技能；schema-managed 路径必须回到 schema validate → plan → apply，不在本技能内降级写入。
+
+## Resource-First 使用门槛
+
+本技能不是“审批/流程”诉求的默认入口。执行前必须先解析 app/form/process context：
+
+- 已有流程表单、`processCode`、流程表单 URL 或 bound process 时，禁止从零创建，改用 `yida-process-rule` 配置/更新节点、分支、字段权限。
+- 已有普通表单 `formUuid` 且用户明确要把这张表单转成审批流程时，可使用用法 2（`--formUuid`）复用该表单；不得新建同名表单。
+- 只有没有目标表单/流程，且用户明确要新建带审批的数据入口或完整审批系统时，才使用用法 1 或推荐两步流程创建新表单再转流程。
+- 多个表单/流程候选按根技能来源优先级选择；同级冲突或无法判断要改哪条流程时才问用户。
+
 ## 严格禁止 (NEVER DO)
 
 - 不要编造 processCode，必须从命令返回的 JSON 中提取
 - 不要在流程定义中使用猜测的 fieldId，必须先用 `yida-get-schema` 获取
+- 不要在流程定义 `nodes` 中声明 `start` / `startNode` / `end` / `endNode` / `finish` 节点；OpenYida 会自动生成发起和结束节点
+- 不要把审批节点写成 `approve`；CLI 支持的是 `approval`（名词），别名可用 `approver` / `approvalNode`
 - 不要用 shell heredoc、`cat`/`echo`/`printf`/`tee` 或重定向生成字段定义、流程定义 JSON 文件
+- 已有流程表单、`processCode` 或 bound process 时，不要从零创建流程表单；改用 `yida-process-rule`。
 
 ## 严格要求 (MUST DO)
 
@@ -21,18 +36,18 @@ description: 流程表单一体化创建（创建表单 → 转流程 → 获取
 
 ## 适用场景
 
-用户需要"创建审批流程"、"新建流程表单"、"搭建审批系统"时使用。
+用户需要"创建审批流程"、"新建流程表单"、"搭建审批系统"，且 resource context 没有既有流程/表单目标时使用。
 
 **关键区分**：
 - 从零创建流程表单（含表单+流程配置）→ 本技能
-- 为已有表单配置/修改审批规则 → `yida-process-rule`
+- 为已有表单或流程配置/修改审批规则 → `yida-process-rule`；已有普通表单要转流程时仅使用本技能的 `--formUuid` 复用模式
 
 ## 触发条件
 
 **正向触发**：
 - "创建审批流程"、"新建流程表单"
 - "搭建审批系统"、"创建带审批的表单"
-- 需求中含「审批」「流程」「申请」「审核」「工单」等关键词，且尚无表单
+- 需求中含「审批」「流程」「申请」「审核」「工单」等关键词，且尚无目标表单/流程
 
 ---
 
@@ -65,6 +80,87 @@ openyida create-process <appType> --formUuid <formUuid> <processDefinitionFile>
 {"success":true,"formUuid":"FORM-YYY","formTitle":"订单处理表","appType":"APP_XXX","fieldCount":6,"processCode":"TPROC--XXX","url":"{base_url}/APP_XXX/workbench/FORM-YYY"}
 ```
 
+## 流程定义最小 DSL 合约
+
+`processDefinitionFile` 只描述发起和结束之间的业务节点。OpenYida 编译器会自动注入发起节点和结束节点，`nodes` 数组里不要手写任何 start/end 节点。
+
+合法基础节点类型只使用这些值：
+
+| 节点意图 | `type` 写法 |
+|------|------|
+| 审批 | `approval` |
+| 办理 / 填写 | `operator` |
+| 条件分支 | `route` |
+| 并行分支 | `parallel` |
+| 抄送 | `carbon` |
+
+常见误写必须修正：
+
+| 错误写法 | 正确处理 |
+|------|------|
+| `start`, `startNode`, `StartNode` | 删除该节点，CLI 自动生成发起节点 |
+| `end`, `endNode`, `finish`, `FinishNode` | 删除该节点，CLI 自动生成结束节点 |
+| `approve` | 改成 `approval` |
+
+最小合法流程定义示例：
+
+```json
+{
+  "nodes": [
+    {
+      "type": "approval",
+      "name": "主管审批",
+      "approver": "originator"
+    }
+  ]
+}
+```
+
+带条件分支示例：
+
+```json
+{
+  "nodes": [
+    {
+      "type": "route",
+      "name": "金额分支",
+      "conditions": [
+        {
+          "name": "5万以上",
+          "rules": [
+            {
+              "fieldId": "numberField_amount",
+              "fieldName": "采购金额",
+              "componentType": "NumberField",
+              "op": "GreaterThanOrEqual",
+              "value": 50000
+            }
+          ],
+          "childNodes": [
+            { "type": "approval", "name": "总经理审批", "approver": "originator" }
+          ]
+        },
+        {
+          "name": "5万以下",
+          "rules": [
+            {
+              "fieldId": "numberField_amount",
+              "fieldName": "采购金额",
+              "componentType": "NumberField",
+              "op": "LessThan",
+              "value": 50000
+            }
+          ],
+          "childNodes": [
+            { "type": "approval", "name": "部门经理审批", "approver": "originator" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+```
+
 ## 推荐两步流程
 
 1. 使用 create_file / Write / file edit tool 创建字段定义：