openyida 2026.9.2 → 2026.9.3

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

@@ -1,10 +1,10 @@
 # 自定义页面实现入口
 
-使用 `YidaCodeCanvas` 组件实现的自定义页面消费 `yida-design` 输出的 `prd.md` 与 `design.md`，或单页 PRD 章节 + design spec，把页面场景、区块、主题、交互、数据绑定和素材清单实现成 `.canvas.jsx` / `.canvas.tsx`。
+使用 `YidaCodeCanvas` 组件实现的自定义页面消费 `yida-prd` 输出的 `prd.md` 与 `yida-design` 输出的 `design.md`，或单页 PRD 章节 + design spec，把页面场景、区块、主题、交互、数据绑定和素材清单实现成 `.canvas.jsx` / `.canvas.tsx`。
 
 ## 页面场景到实现入口
 
-用户描述页面目标后，先读取 `yida-design` 的 `prd/<项目名>/prd.md` 和 `prd/<项目名>/design.md`，或单页 PRD 章节和对应 design spec。PRD 用来确认页面场景、区块、数据来源、主操作和移动端要求；design.md 用来确认主题色、页面风格、视觉 DNA、布局配方、材质、圆角、密度、呼吸感、组件和状态规则。实现时按下表选择页面结构；页面结构、数据桥和样式细节已经明确时，直接手写 `.canvas.jsx`。
+用户描述页面目标后，先读取 `yida-prd` 的 `prd/<项目名>/prd.md` 和 `yida-design` 的 `prd/<项目名>/design.md`，或单页 PRD 章节和对应 design spec。PRD 用来确认页面场景、区块、数据来源、主操作和移动端要求；design.md 用来确认主题色、页面风格、视觉 DNA、布局配方、材质、圆角、密度、呼吸感、组件和状态规则。实现时按下表选择页面结构；页面结构、数据桥和样式细节已经明确时，直接手写 `.canvas.jsx`。
 
 结构化实现工具提供可编译运行时结构、数据桥、主题变量和基础 primitives。真实业务页结合 `prd.md` 落地业务化区块顺序、数据和文案，结合 `design.md` 落地信息层级、局部构图和样式节奏。
 
@@ -94,7 +94,7 @@ PRD 写有 `pageSpecHandoff` 时，可以把 `pageSpecHandoff` 转成 `page-spec
 | 表单新建/提交 | `targetType: "submission"` + `openMode: "responsive-drawer"` | PC 用 `FormOpenContainer` 右侧抽屉 iframe，URL 带 `isRenderNav=false` |
 | 表单查看详情 | `targetType: "detail"` + 目标 `formUuid` + 真实 `formInstId` 来源 | PC 用同一套抽屉宽度，详情 URL 带 `navConfig.layout=1180&isRenderNav=false` |
 
-表单提交/详情里的 `isRenderNav=false` 只隐藏原生表单页或详情页的页面导航，不用于隐藏自定义页应用导航。PC 抽屉 iframe 与移动端整页都由服务端自行加载应用主题文件；`FormOpenContainer` 不接收或同步父页面主题数据。
+表单提交/详情里的 `isRenderNav=false` 只隐藏原生表单页或详情页的页面导航，不用于隐藏自定义页应用导航。
 
 ## 官网与品牌页素材流程
 
@@ -128,9 +128,9 @@ PRD 写有 `pageSpecHandoff` 时，可以把 `pageSpecHandoff` 转成 `page-spec
 
 ## 主题实现
 
-主题色决策来自 `yida-design` 的 `design.md`，业务场景和页面边界来自 `prd.md` 或派生的 `page-spec.json`。所有页面都以当前应用主题为唯一主题来源；缺少主题证据时，按业务气质选择平台预置主题或生成应用自定义主题文件，不固定回到 `podBlue` / #1677ff。`themeProfile: { "name": "yida-app-theme" }` 表示跟随宜搭运行态主题：新版线上由应用自定义主题 CSS 中的 `--color-brand1-*` 和 `--color-group` 决定页面主色、图表色组和强调色。
+主题色决策来自 `yida-design` 的 `design.md`。`app-theme.css` 只在应用级配置，由平台统一作用于整个应用。
 
-`page-spec.json` 只保存与 design.md 一致的主题摘要。新版主题必须在 design.md 中写清应用主题模板、CSS 产物、`--color-brand1-6`、`navTheme`、`logoSource` 和 `layoutDirection`，并通过 `create-app/update-app --theme-file/--nav-theme/--logo-source/--layout` 联合保存。运行容器在自定义页面与 `FormOpenContainer` 的提交页/详情页 iframe 中加载同一应用主题文件。
+`page-spec.json` 只保存与 `design.md` 一致的主题摘要。自定义页面只在 `YidaComp` 内消费当前应用的 `--color-brand1-*`、`--color-group` 和 `--pod-*`，不向上层写入或同步主题样式。
 
 从 PRD 或派生的 `page-spec.json` 读取业务边界，从 design.md 读取应用主题 token 与视觉执行规则。全局换肤、导航与内容统一换色或新品牌色都通过应用主题 CSS、`themeColor` 和 `navTheme` 配置；单页美化沿用该应用主题并调整页面结构和视觉语言。
 
@@ -170,8 +170,7 @@ PRD 写有 `pageSpecHandoff` 时，可以把 `pageSpecHandoff` 转成 `page-spec
   "designRefs": ["themeProfile", "sceneRecipes.dashboard", "components.charts", "states.empty"],
   "themeSummary": {
     "themeColor": "青绿色应用主题",
-    "styleKeywords": ["运营洞察", "轻量玻璃感", "高密信息"],
-    "themeDelivery": "app-custom-theme-file"
+    "styleKeywords": ["运营洞察", "轻量玻璃感", "高密信息"]
   },
   "researchLevel": "none",
   "archetype": "analysis",

package/yida-skills/skills/yida-canvas-table-form/SKILL.md

@@ -38,7 +38,7 @@ description: 自定义页面表格批量录入技能。使用 `YidaCodeCanvas`
 5. **分批并发而非无限并发**：按固定批次切分，批次内使用 `Promise.all` 并发，批次间顺序推进；不得逐行串行，也不得一次性无限并发。
 6. **失败行必须保留**：每行保存 `_status`、`_errors` 和 `_submitError`；部分失败后只重试失败行，成功行不能重复提交。
 7. **真实交付要发布证据**：创建或修改 `.canvas.jsx` / `.canvas.tsx` 页面源码后，只有 `openyida publish <source> <appType> <displayPageFormUuid>` 成功才能声明页面已发布。
-8. **页面表面跟随应用主题**：运行容器加载应用主题文件后，`YidaCodeCanvas` 下生成页面的根画布使用 `min-height: 100vh`，背景使用 `var(--pod-page-bg-color, var(--color-white, #fff))`；表格面板使用 `--pod-card-bg-color`、`--pod-card-border` 和 `--pod-card-border-radius`，antd 主色读取 `--color-brand1-6`。不得固定绿色渐变或纯白卡片。
+8. **页面表面跟随应用主题**：`YidaCodeCanvas` 下生成页面的根画布使用 `min-height: 100vh`，背景使用 `var(--pod-page-bg-color, var(--color-white, #fff))`；表格面板使用当前应用主题中的 `--pod-card-bg-color`、`--pod-card-border` 和 `--pod-card-border-radius`，antd 主色读取 `--color-brand1-6`。
 
 ## 数据桥契约
 
@@ -142,7 +142,7 @@ openyida publish project/pages/src/table-form-batch-submit.canvas.jsx <appType>
 - [ ] 分批并发受控，成功/失败数量可见。
 - [ ] 部分失败后失败行可编辑、可单独重试，成功行不会重复写入。
 - [ ] 未验证写入桥时按钮禁用并显示未闭环原因。
-- [ ] 页面根画布使用 `min-height: 100vh` 并绑定 `--pod-page-bg-color`，表格面板和 antd 主色使用运行容器加载的应用主题变量。
+- [ ] 页面根画布使用 `min-height: 100vh` 并绑定 `--pod-page-bg-color`，表格面板和 antd 主色直接使用当前应用主题变量。
 - [ ] 真实接口验证与页面发布都有证据后，才声明完整交付。
 
 ## 完成证据

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

@@ -28,14 +28,14 @@ description: 创建宜搭应用并返回 appType；仅当没有目标 app 且用
 ## 严格要求 (MUST DO)
 
 - 创建成功后，将 appType 记录到 `.cache/<项目名>-schema.json`
-- 创建成功后，把真实 `appType` 交给 `yida-design` 生成或更新 `prd/<项目名>/prd.md` 与 `prd/<项目名>/design.md`；后续表单、流程、页面和发布都按 PRD 执行业务，按 design.md 执行视觉。
+- 若完整搭建已完成 artifact join，创建成功后不得回写 `.cache/openyida/<项目名>/requirement-brief.json`，也不得仅因拿到真实 `appType` 重跑 `yida-prd`、`yida-design` 或 join；真实 `appType` 只写入 schema 或当前任务资源上下文。
 - 创建前确认当前登录的组织（corpId）与目标组织一致
 - **本技能不读写 memory**：appType 等信息输出到 stdout，通过 `.cache/<项目名>-schema.json` 持久化，不依赖跨会话的 memory 状态
 
 ## 适用场景
 
 用户说"只创建应用壳"、"新建应用并返回 appType"，且 resource context 没有目标 app 时使用此技能。
-创建应用后，先用 `yida-design` 产出或更新 PRD，再继续执行：创建/更新表单（`yida-create-form-page`）→ 创建或复用页面（`yida-create-page` / existing page）→ 发布页面（`yida-publish-page`）。
+创建应用后，若任务只是创建应用壳则返回真实 `appType` 即可；若继续完整搭建，把真实 `appType` 写入 `.cache/<项目名>-schema.json` 或当前任务资源上下文，然后直接按已经 join 的 PRD 与视觉 artifact 执行：创建/更新表单（`yida-create-form-page`）→ 创建或复用页面（`yida-create-page` / existing page）→ 发布页面（`yida-publish-page`）。
 后续如果需要自定义页面，源码写到 `project/pages/src/<页面名>.canvas.jsx` 并发布。
 
 ---
@@ -54,7 +54,7 @@ openyida create-app --name <appName> [--desc <description>] [--theme-file <app-t
 | `description` | 否 | 同 appName | 应用描述 |
 | `icon` | 否 | 见下文 | 显式指定优先；否则优先使用命中的行业图标，仅未命中行业时从平台系统图标中随机选择 |
 | `iconColor` | 否 | 见下文 | 传主题文件时统一跟随 `--color-brand1-6` 的 HEX 值；未传主题文件时保留兼容默认值 |
-| `themeFile` | 否，推荐 | — | 基于 `yida-design/references/theme/app-custom-theme-template.css` 生成的 CSS；必须完整声明平台实际生成的 `--color-brand1-1/2/3/5/6/9/10`，不要补造 `4/7/8`；其中 `--color-brand1-6` 必须为字面量，CLI 自动以它保存 `themeColor` |
+| `themeFile` | 否，推荐 | — | 先通过 `openyida sample yida-design app-theme --output <app-theme.css>` 复制模板，再按主题色修改对应 token。严禁重新生成或覆盖整份 CSS；主色写入 `--color-brand1-6` |
 | `navTheme` | 否 | `themeFile` 场景默认 `light` | 导航风格：`light` / `dark` / `white` / `gray` |
 | `logoSource` | 否 | `themeFile` 场景默认 `appIcon` | 新建应用只支持应用图标；`customImage` 需要已有 `homepageLogo`，只在已有应用更新时使用 |
 | `layoutDirection` | 否 | `l_shape` | 新建应用默认使用 L 型导航；可显式改为 `side`（侧边）/ `top`（顶部）/ `l_shape`（L 型） |
@@ -71,7 +71,7 @@ openyida create-app --name <appName> [--desc <description>] [--theme-file <app-t
 | 咨询、审计、会计、投顾、企业服务 | `podBlue` | `xian-qiye #5C72FF podBlue` | `official-homepage` 或工作台，按用户目标选择 |
 | 普通内部管理、CRM、OA、项目管理 | `podBlue`，业务强调增长/活力时可选 `podOrange` | 可使用默认或用户指定参数 | `product-homepage --scene workbench` |
 
-CLI 内部的 `colour` 仅用于 `registerApp` 创建阶段兼容，不作为新版主题设计结果。完整应用、带 PRD/design.md 的应用和用户要求新版主题时，默认推荐传主题文件；只有用户明确只要兼容空壳、暂不配置主题或需要保留旧创建方式时才省略。省略 `--theme-file` 不报错，也不会上传或伪造主题配置。
+CLI 内部的 `colour` 仅用于 `registerApp` 创建阶段兼容，不作为应用主题设计结果。创建完整应用、使用 PRD/design.md 或用户要求配置主题时，默认传入主题文件；只有用户明确只创建空壳或暂不配置主题时才省略。省略 `--theme-file` 不报错，也不会上传或伪造主题配置。
 
 CLI 始终按“显式 `--icon` → 行业推断 → 随机系统图标”的顺序选择图标，只有未显式指定且未命中行业时才随机，与是否传主题文件无关。所有新建应用未显式传 `--layout` 时默认使用 `layoutDirection=l_shape`。传入主题文件时，CLI 还会在创建前校验 CSS，并将图标颜色统一为 `--color-brand1-6` 转换后的 HEX；未显式指定主题导航配置时使用 `navTheme=light`、`logoSource=appIcon`。
 
@@ -79,13 +79,19 @@ CLI 始终按“显式 `--icon` → 行业推断 → 随机系统图标”的顺
 
 默认不要把黑色、深灰或灰黑中性色作为普通应用主题色。创建业务系统、工作台、门户、数据管理类应用时，先根据行业、品牌、业务情绪和视觉目标做创意色彩判断；`podBlue`、`podGreen`、`podOrange` 只是常用浅底候选，不是固定默认，也不是行业刻板答案。`black` 仅在用户明确要求暗色模式、高对比、奢侈品牌或极简黑色视觉时使用，`greyBlue` 也只在工业制造、技术工程等稳重场景下作为 fallback。
 
-主题颜色不受平台预置 key 限制。读取 `yida-design/references/theme/app-custom-theme-template.css` 生成主题文件，将任意设计主色写入 `--color-brand1-6`，再执行：
+主题颜色不受平台预置 key 限制。先执行以下命令复制内置主题模板，再定点修改品牌相关 token：
+
+```bash
+openyida sample yida-design app-theme --output .cache/openyida/<项目名>/app-theme.css
+```
+
+将任意设计主色写入 `--color-brand1-6` 后执行：
 
 ```bash
 openyida create-app --name "<应用名>" --desc "<描述>" --theme-file <app-theme.css> --nav-theme light --logo-source appIcon --layout l_shape
 ```
 
-CLI 会先校验主题文件完整声明平台实际生成的 `--color-brand1-1/2/3/5/6/9/10`，并允许不存在 `--color-brand1-4/7/8`。创建成功后在同一流程中上传 CSS，并联合保存从 `--color-brand1-6` 提取的 `themeColor`、`customThemeStyle`、`navTheme`、`logoSource` 和 `layoutDirection`。创建或更新主题时，系统应用图标会同步保存为 `iconName%%主题色HEX`；外链或上传图片图标保持原值。运行容器会在自定义页面、表单、提交页和 formDetail 中加载同一应用主题文件。
+CLI 会先校验主题文件完整声明平台实际生成的 `--color-brand1-1/2/3/5/6/9/10`，并允许不存在 `--color-brand1-4/7/8`。创建成功后在同一流程中上传 CSS，并联合保存从 `--color-brand1-6` 提取的 `themeColor`、`customThemeStyle`、`navTheme`、`logoSource` 和 `layoutDirection`。创建或更新主题时，系统应用图标会同步保存为 `iconName%%主题色HEX`；外链或上传图片图标保持原值。
 
 完整应用主题 key、颜色倾向和 token 变量统一维护在 `yida-design/references/theme/theme-token-presets.md`，本技能不重复维护完整清单。
 
@@ -112,7 +118,7 @@ CLI 会先校验主题文件完整声明平台实际生成的 `--color-brand1-1/
 | 火车 | `huoche` | | 查询 | `chaxun` |
 | 申报 | `shenbao` | | 打卡 | `daka` |
 
-**图标背景色**：新版主题固定跟随 CSS 的 `--color-brand1-6`；下面这些颜色仅用于未传主题文件的兼容创建：`#0089FF` `#00B853` `#FFA200` `#FF7357` `#5C72FF` `#85C700` `#FFC505` `#FF6B7A` `#8F66FF` `#14A9FF`
+**图标背景色**：传入主题文件时固定跟随 CSS 的 `--color-brand1-6`；下面这些颜色仅用于未传主题文件的空壳创建：`#0089FF` `#00B853` `#FFA200` `#FF7357` `#5C72FF` `#85C700` `#FFC505` `#FF6B7A` `#8F66FF` `#14A9FF`
 
 ## 创建后交付约定
 

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

@@ -1,6 +1,6 @@
 ---
 name: yida-create-form-page
-description: 表单页面创建与更新，默认加载 yida-form-detail 作为表单视觉引导，并合并 Divider 分割线语义分组；新版主题由运行容器在表单与 formDetail 中加载同一应用级主题 CSS；支持 19 种业务字段和 Divider、ColumnContainer 等表单展示布局组件，PageSection/GroupContainer 仅少量特殊场景使用；支持联动规则和数据源绑定。
+description: 表单页面创建与更新；支持 19 种业务字段和 Divider、ColumnContainer 等表单展示布局组件，PageSection/GroupContainer 仅少量特殊场景使用；支持联动规则和数据源绑定。
 ---
 
 # 表单页面创建与更新
@@ -26,11 +26,11 @@ description: 表单页面创建与更新，默认加载 yida-form-detail 作为
 - OpenYida CLI 不要加 `2>/dev/null`；失败时保留 stdout/stderr 诊断，遇到 DENIED 或重复失败必须换策略
 - 已有目标表单且用户是改字段/联动/属性时，不要创建新表单；必须走 update/patch/rule/bind-datasource。
 - 不要用 `GroupContainer` / `PageSection` 承载普通业务分组；普通分组必须优先用 `Divider`
+- 严禁为原生表单或 `formDetail` 生成、注入 CSS、JS、HTML 或主题代码；详情页由平台渲染。
 
 ## 严格要求 (MUST DO)
 
-- 表单页开发默认先加载 `yida-form-detail` 作为视觉引导和详情页主题消费策略，再由本技能落地字段 JSON；视觉引导必须和 `Divider` 分割线语义分组合并执行。
-- 拿到或确认真实 `formUuid` 后确认应用级自定义主题 CSS 已保存，并由提交页和 formDetail 运行容器加载。
+- 拿到或确认真实 `formUuid` 后，用于后续字段更新、数据绑定和页面入口配置。
 - create 成功后，将 formUuid 记录到 `.cache/<项目名>-schema.json`
 - 完整应用生成场景中，create 成功并记录 formUuid 后，把核心普通表单交给 `yida-data-management` 默认写入 1-3 条业务化示例记录；不要在本技能里直接操作数据记录。
 - update / add-option / bind-datasource / validation / rule 等字段级操作不要求先执行外部 `get-schema`；直接提交 compact JSON 或字段 label/fieldId，CLI 会内部读取 schema、定位字段，并在成功 JSON 中输出 compact `resolved`/`updatedProps` evidence。字段解析失败/歧义时按 `diagnostics[].candidates` 补 `tableLabel`、修正 label 或再执行一次 compact `get-schema`。
@@ -69,14 +69,14 @@ description: 表单页面创建与更新，默认加载 yida-form-detail 作为
 
 ## 布局决策规则
 
-默认表单是单列。表单页开发必须先按 `yida-form-detail` 的视觉引导确定填写路径、字段密度和分组结构，再用 `Divider` / `ColumnContainer` / 标准字段表达。不要为了“更高级”默认把整表改成双列，也不要用 `GroupContainer` / `PageSection` 做普通分组。
+默认表单是单列，使用 `Divider` / `ColumnContainer` / 标准字段表达业务结构。严禁为了“更高级”默认把整表改成双列；严禁用 `GroupContainer` / `PageSection` 做普通分组。
 
 - 默认单列：字段较少、流程表单、移动端优先、长文本、说明、附件、地址、子表、审批意见、需要逐项认真填写的字段。
 - 局部多列：短字段且天然成对或成组时使用 `ColumnContainer`，例如开始/结束日期、姓名/工号、部门/岗位、金额/币种、联系人/电话。
 - 全局 `--layout double`：只有用户明确要求“整个表单双列”时才使用；一般更推荐在字段 JSON 内用 `ColumnContainer` 做局部多列。
 - 语义分组：按业务含义分段，不按字段数量平均分。常见分组包括“基本信息”“业务信息”“时间计划”“补充材料”“审批信息”。
 - Divider 样式：默认 `bold-with-thin`；显式样式按 `bold-with-thin` → `double-color-trapezoid` → `left-dot-title` → `solid` / `dashed` / `thick` / `dotted` 优先级选择；门户/强分区场景可统一显式使用 `multi-parallelograms-end`。
-- 新版主题与 formDetail 样式来自应用级自定义主题 CSS，字段 JSON 和表单 Schema JS 只承载表单结构与业务动作。
+- 字段 JSON 和表单 Schema JS 只承载表单结构与业务动作。
 
 推荐结构：
 
@@ -98,17 +98,12 @@ Divider > Field
 - 审批人、审批状态、审批节点等流程运行字段由流程能力承载；表单只收集业务数据。
 - 表单标题、字段 label/title、选项、提示语、校验文案、动作源码、字段 JSON 常量和字段 JSON 文件路径都禁止 emoji；`create-form` / schema compiler 报 emoji 错误时必须改字段 JSON 或路径，不能重复 create 或用同义命令绕过。
 
-## 表单全局主题规则
+## 表单布局样式
 
-表单和流程表单必须和应用、自定义页面使用同一套主题 token。运行容器把应用 `customThemeStyle.cssUrl` 分别加载到提交页、详情页、自定义页面和抽屉 iframe，本技能只生成表单字段 JSON。
-
-- 普通业务分组：`Divider` 标题跟随应用主题，下面直接接字段或 `ColumnContainer`
-- 默认 `Divider` 不写颜色属性，或保持 `colorType: "theme"`
-- 详情差异统一写入应用主题 CSS 的语义 token，由提交页和详情页运行容器加载
-- 新表单页默认消费 `podBlue`、`podGreen`、`podOrange` 等应用主题对应 token；`blue`、`green`、`orange` 作为应用主题 token profile 保留原名。本技能只消费服务端加载的应用主题变量，不把 legacy 名称当作表单 `--theme` 或应用 `--theme` 参数
-- 局部多列容器：保持背景克制，避免给每个列容器单独上色
-- 流程表单：更偏单列和清晰分段，颜色只用于章节识别，不要做大面积品牌色块
-- 自定义色：只有用户明确说“红色警示”“绿色成功态”“品牌色 #xxx”时才写 `colorType: "custom"` 和具体色值
+- 普通业务分组使用 `Divider`，下面直接接字段或 `ColumnContainer`
+- 局部多列容器保持背景克制，避免给每个列容器单独上色
+- 流程表单更偏单列和清晰分段，颜色只用于章节识别
+- 用户明确指定颜色时才写 `colorType: "custom"` 和具体色值
 
 ## create 模式
 
@@ -119,12 +114,16 @@ openyida create-form create <appType> <formTitle> <fieldsJsonOrFile> [--layout d
 # 文件路径示例：.cache/openyida/<项目名或任务名>/<表单名>-fields.json
 ```
 
+创建成功后 CLI 会根据表单标题和字段语义选择导航图标，再更新导航节点并回读校验。需要指定时传 `--icon <iconName>`；用 `openyida create-form icons --json` 查看与 yida-next 页面导航选择器一致的 86 个可用值。表单导航图标是纯图标名（如 `name-card`、`Project`、`Todo`、`clock`），不是应用图标的 `xian-*%%color` 协议。
+
+导航图标更新必须先读取 `getFormNavigationListByOrder.json` 的当前节点，像 yida-next 的 `DB.Nav.update({ ...node, title: JSON.stringify(node.title), formUuid: node.formUuid || 'NAV-SYSTEM-FROM-ME-UUID', icon })` 一样保留 `gmtModified`、`formType`、`isNewForm`、`listOrder` 等原值，再请求带 `_api=Nav.update&_mock=false&_stamp=...` 的 `updateFormNavigation.json`，最后重新读取导航列表校验图标。禁止仅凭 formUuid 拼一个精简更新 payload。
+
 > 文件先用 create_file / Write / file edit tool 创建。上方路径默认从 OpenYida project 工作目录执行；如果从 workspace 根执行命令，传 `project/.cache/openyida/<项目名或任务名>/<表单名>-fields.json`。
 
 输出：
 
 ```json
-{"success":true,"formUuid":"FORM-XXX","formTitle":"用户信息表","appType":"APP_xxx","fieldCount":4,"url":"{base_url}/APP_xxx/workbench/FORM-XXX"}
+{"success":true,"formUuid":"FORM-XXX","formTitle":"用户信息表","appType":"APP_xxx","fieldCount":4,"icon":"name-card","iconSource":"auto","url":"{base_url}/APP_xxx/workbench/FORM-XXX"}
 ```
 
 完整应用模式下的下一步：
@@ -249,7 +248,6 @@ openyida create-form rule <appType> <formUuid> <rulesJsonOrFile>
 | [field-definition-guide.md](references/field-definition-guide.md) | 需要完整字段属性、布局组件、update changes 或字段类型表时 |
 | [advanced-form-modes.md](references/advanced-form-modes.md) | 使用 patch / rule / validation / bind-datasource 高级模式前必须读取 |
 | [form-field-properties.md](references/form-field-properties.md) | 需要字段属性细节或平台属性映射时 |
-| `yida-form-detail` | 表单页开发默认加载；产出表单视觉引导、Divider 分组策略和应用级 formDetail 主题适配边界 |
 | [employee-field.md](references/employee-field.md) | 成员字段配置 |
 | [association-form-field.md](references/association-form-field.md) | 关联表单字段配置 |
 | [serial-number-field.md](references/serial-number-field.md) | 流水号字段配置 |

package/yida-skills/skills/yida-create-form-page/references/form-field-properties.md

@@ -48,14 +48,13 @@ Divider > Field
 
 ### 主题规则
 
-表单布局组件应跟随运行态主题变量。本参考只说明字段 JSON 如何使用主题；新版主题运行容器将同一应用级自定义主题 CSS 分别加载到提交页、详情页、自定义页面和表单 iframe。
+本参考只说明字段 JSON 和表单布局属性。
 
 生成建议：
 
 - 默认 `Divider` 使用主题模式：不写 `colorType` 或写 `"theme"`。
 - 不要为了“更好看”给每个 Divider 随机写 `backgroundColor` / `secondaryColor`。
 - 只有用户明确指定颜色时，才使用 `colorType: "custom"` 并写 `backgroundColor`、`secondaryColor`、`titleColor`。
-- 新表单页默认消费 `podBlue`、`podGreen`、`podOrange` 对应主题变量；`blue`、`green`、`orange` 作为应用主题 token profile 保留原名。本参考只消费运行态变量，不把 legacy 名称当作表单 `--theme` 或应用 `--theme` 参数。
 
 ### Divider
 
@@ -71,8 +70,6 @@ Divider > Field
 
 生成 Schema 时默认写入 `props.type: "bold-with-thin"`。只有在用户明确指定样式时才通过 `dividerType` 覆盖 `props.type`。同一张表单中的 `Divider` 必须保持同一个 `props.type`，避免章节样式跳变。如果是修改已有表单，先看线上 Schema 中 Divider 的原始 `props.type`，属于上述支持清单或强分区特殊值时优先复用。
 
-执行规则：OpenYida 生成字段结构和业务动作；表单主题由运行容器加载应用主题文件。
-
 | 属性 | 默认值 | 说明 |
 | --- | --- | --- |
 | `behavior` | `"NORMAL"` | 默认状态，支持 `"NORMAL"` / `"HIDDEN"` |

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

@@ -42,7 +42,7 @@ description: JSX 自定义页面开发规范（React 16 平台 Jsx 组件、expo
 
 影响代码质量和用户体验：
 
-0. **视觉方向先于编码**：单点页面美化、页面重构、用户明确要求好看/去 AI 味，或完整应用进入页面实现阶段时，调用 `use_skill("yida-design", "确定自定义页面视觉方向")` 完成产品设计或 UI 设计。默认产出 `prd/<项目名>/prd.md` 与 `prd/<项目名>/design.md`，或单页 PRD 章节 + design spec；PRD 包含页面场景、页面区块、`functionContract`、素材策略、原生表单入口和业务化自检，design.md 包含 `themeProfile`、tokens、视觉 DNA、`visualScaffold`、圆角、密度、组件和状态规则。页面重构默认以当前应用主题色为基准，并保持现有数据源、字段映射、按钮动作、筛选逻辑、提交 URL、权限和业务状态。应用主题统一通过 `create-app/update-app --theme-file/--nav-theme/--logo-source/--layout` 保存，主色由 CSS 的 `--color-brand1-6` 派生；运行容器在页面与表单 iframe 中加载同一主题文件。
+0. **视觉方向先于编码**：单点页面美化、页面重构、用户明确要求好看/去 AI 味，或完整应用进入页面实现阶段时，分别读取 `yida-prd` 的产品事实和调用 `use_skill("yida-design", "确定自定义页面视觉方向")` 获取 UI 设计。完整应用由 `yida-prd` 产出 `prd/<项目名>/prd.md`、由 `yida-design` 产出 `prd/<项目名>/design.md`，或提供单页 PRD 章节 + design spec；PRD 包含页面场景、页面区块、`functionContract`、素材策略、原生表单入口和业务化自检，design.md 包含 `themeProfile`、tokens、视觉 DNA、`visualScaffold`、圆角、密度、组件和状态规则。页面重构默认以当前应用主题色为基准，并保持现有数据源、字段映射、按钮动作、筛选逻辑、提交 URL、权限和业务状态。
 1. **代码生成前确认功能摘要**：详见 [编码指南 编注 0](references/coding-guide.md)
 2. **pageSize 推荐 50，最大 100**：列表/看板默认 `pageSize: 50`；分页接口 `searchFormDatas` 等的 `pageSize` 最大 100
 3. **didUnmount 清理定时器**：在 `didUnmount` 中清理所有 `setInterval`/`setTimeout`，防止内存泄漏
@@ -51,7 +51,7 @@ description: JSX 自定义页面开发规范（React 16 平台 Jsx 组件、expo
 6. **forceUpdate 后延迟操作 DOM**：`forceUpdate()` 后 DOM 不会立即更新，ECharts/Canvas/第三方组件初始化必须放入 `setTimeout` 或 `requestAnimationFrame`
 7. **多端适配**：使用 `this.utils.isMobile()` 判断设备类型，适配 PC 和移动端
 8. **输入法组合输入处理**：使用 `_isComposing` 标记配合 `compositionstart`/`compositionend` 事件，避免输入过程中触发提交
-9. **表单打开入口统一容器**：数据列表用 `workbench/{formUuid}?iframe=true`，禁止用 `formDetail` 冒充列表；新增/提交/查看详情入口统一封装为 `FormOpenContainer`。PC 端默认用半屏 `50vw` 抽屉 iframe 承载页面级隐藏导航的 `submission/{formUuid}?isRenderNav=false` 或 `formDetail/{formUuid}?formInstId=...&navConfig.layout=1180&isRenderNav=false`，提交页和详情页使用同一宽度规则；详情实例 ID 必须优先取 `row.formInstId`，缺失时禁用或提示，不打开空 `formInstId`；运行容器在页面和 iframe 中加载同一应用主题文件；移动端才整页或新页打开原生表单页；不要在按钮里直接 `window.open`
+9. **表单打开入口统一容器**：数据列表用 `workbench/{formUuid}?iframe=true`，禁止用 `formDetail` 冒充列表；新增/提交/查看详情入口统一封装为 `FormOpenContainer`。PC 端默认用半屏 `50vw` 抽屉 iframe 承载页面级隐藏导航的 `submission/{formUuid}?isRenderNav=false` 或 `formDetail/{formUuid}?formInstId=...&navConfig.layout=1180&isRenderNav=false`，提交页和详情页使用同一宽度规则；详情实例 ID 必须优先取 `row.formInstId`，缺失时禁用或提示，不打开空 `formInstId`；移动端才整页或新页打开原生表单页；不要在按钮里直接 `window.open`
 10. **Tabs 显隐控制**：下拉值变更后自动回退到第一个可见 Tab，内容区用 `display: none` 保留 DOM
 11. **加载态必须可恢复**：列表/看板页默认保留空态或演示数据；接口失败、超时或返回异常时必须把 `loading` 置回 `false`，不要只渲染“正在加载...”挡住整页
 12. **禁止可见原生下拉**：筛选、预约、审批等用户可见下拉交互不要使用 `<select>`；普通自定义页也不要把表单设计器里的 `SelectField` 当 React 筛选组件直接渲染。默认使用 Tailwind className 组合 `button + menu + option` 的自定义下拉组件，并带 `.oyd-select-arrow` 下箭头、`.oyd-select-check` 选中标记和页面级 focus reset；light 模式下选中项整块背景必须用 `--oyd-control-selected-bg` 这类低透明度浅色 token，不要直接用 `--color-brand1-1`
@@ -60,7 +60,7 @@ description: JSX 自定义页面开发规范（React 16 平台 Jsx 组件、expo
 15. **发布前必须跑检查链路**：先执行 `openyida check-page <file>` 和 `openyida compile <file>`；若出现 warning/error，按规则修复后再发布
 16. **源码修改发布闭环**：只要本轮 Write/Edit/Create 了 `project/pages/src/*.{oyd.jsx,jsx,tsx}` 普通自定义页面源码，`check-page` / `compile` 只证明源码可发布，不等于远端页面已更新；final 前必须看到成功的 `openyida publish <source> <appType> <displayPageFormUuid>`。没有 publish 成功证据时，只能说“源码已修改，尚未发布”，不能说“页面已更新 / 已重新发布”。
 
-> 每条规则的代码示例、反模式和常见错误见 [编码指南](references/coding-guide.md)；完整应用统一编排默认先遵守 `yida-design` 的 `prd.md`、`design.md` 和本技能正文，不预读长 reference，只有 check-page 报错、复杂交互或正文覆盖不了的问题时才读取。
+> 每条规则的代码示例、反模式和常见错误见 [编码指南](references/coding-guide.md)；完整应用统一编排默认先遵守 `yida-prd` 的 `prd.md`、`yida-design` 的 `design.md` 和本技能正文，不预读长 reference，只有 check-page 报错、复杂交互或正文覆盖不了的问题时才读取。
 > 运行时易错点、`check-page` 规则和兼容层自动修复边界见 [运行时护栏](references/runtime-guardrails.md)，按需读取。
 > 表单类 JSX 控件、筛选栏、表格等组件写法见 [组件指南](references/component-jsx-guide.md)，涉及这些复杂组件时读取；未验证的平台组件能力不得编造。
 
@@ -183,7 +183,7 @@ export function loadVisitorList() {
 
 ## 开发规范
 
-> 完整应用统一编排默认不读取长 reference，直接遵守 `yida-design` 的 `prd.md`、`design.md`、本技能正文的核心规则和页面结构。只有 check-page 报错、复杂交互/复杂组件或正文覆盖不了的运行时问题，才读取下方 Available Files。
+> 完整应用统一编排默认不读取长 reference，直接遵守 `yida-prd` 的 `prd.md`、`yida-design` 的 `design.md`、本技能正文的核心规则和页面结构。只有 check-page 报错、复杂交互/复杂组件或正文覆盖不了的运行时问题，才读取下方 Available Files。
 > 涉及输入控件、日期、选择、表格或筛选栏时，读取 [组件指南](references/component-jsx-guide.md)。
 
 ## 编码指南与注意事项
@@ -251,7 +251,7 @@ openyida check-page pages/src/home.oyd.jsx --json      # 输出机器可读的
 | 文档 | 覆盖范围 | 何时阅读 |
 |------|---------|---------|
 | **本技能文档** | | |
-| `yida-design` 子技能 | 产品定位、页面场景、主题色和 token、UI 视觉、状态规则、去 AI 味自检、图标策略 | 页面实现前加载；完整应用统一编排使用 `prd/<项目名>/prd.md` 与 `prd/<项目名>/design.md`，用户明确要求好看/去 AI 味时按入口路由读取更多 reference |
+| `yida-prd` + `yida-design` 子技能 | `yida-prd` 提供产品定位与页面场景；`yida-design` 提供主题色、token、UI 视觉、状态规则、去 AI 味自检和图标策略 | 页面实现前加载；完整应用统一编排使用 `prd/<项目名>/prd.md` 与 `prd/<项目名>/design.md`，用户明确要求好看/去 AI 味时按入口路由读取更多 reference |
 | [编码指南](references/coding-guide.md) | 文件结构模板、状态管理、生命周期、19 条编码规范 | check-page 报错、复杂交互、状态管理问题时阅读 |
 | [运行时护栏](references/runtime-guardrails.md) | pageSize、loading 恢复、ECharts DOM 时序、setState 约束、check-page 规则映射 | 页面运行时报错、check-page 规则不清或编译兼容边界不清时阅读 |
 | [平台 JSX 组件样式实现适配](references/design-system.md) | 将 `design.md` 的色彩、圆角、字体、间距、组件和状态规则落到平台 JSX 组件页面 | 用户明确要求视觉细化，或已进入 `yida-design` 后阅读 |

package/yida-skills/skills/yida-custom-page/references/coding-guide.md

@@ -81,7 +81,7 @@ export function injectNativeControlReset() {
   }
 
   style.innerHTML = [
-    '.oyd-page{--oyd-control-border:#D0D5DD;--oyd-control-hover:var(--color-brand1-4,#8BB8FF);--oyd-control-focus:var(--color-brand1-6,#2F6FED);--oyd-control-focus-ring:rgba(47,111,237,.14);--oyd-control-selected-bg:rgba(47,111,237,.08);--oyd-control-info-bg:rgba(47,111,237,.08);}',
+    '.oyd-page{--oyd-control-border:#D0D5DD;--oyd-control-hover:var(--color-brand1-5,#8BB8FF);--oyd-control-focus:var(--color-brand1-6,#2F6FED);--oyd-control-focus-ring:rgba(47,111,237,.14);--oyd-control-selected-bg:rgba(47,111,237,.08);--oyd-control-info-bg:rgba(47,111,237,.08);}',
     '.oyd-page input,.oyd-page textarea,.oyd-page select,.oyd-page .oyd-input,.oyd-page .oyd-select-trigger{appearance:none;-webkit-appearance:none;font-family:inherit;font-weight:400;color:#1D2939;outline:none!important;box-shadow:none;}',
     '.oyd-page input,.oyd-page textarea,.oyd-page select,.oyd-page .oyd-input{border:1px solid var(--oyd-control-border);border-radius:6px;background:#fff;}',
     '.oyd-page input:hover,.oyd-page textarea:hover,.oyd-page select:hover,.oyd-page .oyd-input:hover,.oyd-page .oyd-select-trigger:hover{border-color:var(--oyd-control-hover)!important;}',
@@ -625,14 +625,10 @@ export function closeYidaForm() {
 }
 ```
 
-`renderJsx` 中根据 `formOpenRequest` 渲染右侧抽屉和 `<iframe src={state.formOpenRequest.iframeUrl}>`；PC 抽屉宽度使用 `state.formOpenRequest.drawerWidth || '50vw'`，提交页和详情页默认一致。iframe 由新版主题运行时加载与应用一致的自定义主题 CSS。关闭抽屉时清空 `formOpenRequest` 并重新查询列表。不要假设平台提供 `openDrawer` 内置方法，也不要为提交和详情各写一套 drawer 状态。
+`renderJsx` 中根据 `formOpenRequest` 渲染右侧抽屉和 `<iframe src={state.formOpenRequest.iframeUrl}>`；PC 抽屉宽度使用 `state.formOpenRequest.drawerWidth || '50vw'`，提交页和详情页默认一致。关闭抽屉时清空 `formOpenRequest` 并重新查询列表。不要假设平台提供 `openDrawer` 内置方法，也不要为提交和详情各写一套 drawer 状态。
 
 > `viewUuid` 可选，从宜搭「数据管理」→「报表视图」页面的 URL 中获取，不传则使用默认视图。
 
-### 16.1 自定义主题消费
-
-平台 JSX 页面和 `FormOpenContainer` 的表单 iframe 由运行容器分别加载同一份应用级主题 CSS，并使用一致的主题变量。需要不同主题时通过应用级 `update-app --theme-file/--nav-theme/--logo-source/--layout` 配置，主色由 CSS 的 `--color-brand1-6` 自动派生。
-
 ### 17. 下拉选项控制选项卡（Tabs）表格页显示/隐藏
 
 当页面中存在选项卡组件包含多个表格页，需要根据下拉选择框的值动态控制特定表格页的显示或隐藏时，使用状态驱动的条件渲染实现。

package/yida-skills/skills/yida-custom-page/references/design-system.md

@@ -1,6 +1,6 @@
 # 宜搭普通自定义页面样式实现适配
 
-> **本文件是平台 JSX 组件页面的 token / 组件实现适配层（数值层）**：提供色彩、圆角、字体、间距的具体值与组件模板，不产出配色、视觉 DNA 或页面风格。设计事实唯一来自 `yida-design` 输出的 `prd.md` 与 `design.md`；本文件只负责把 `design.md` 的视觉方向落到平台 JSX 组件页面的内联样式、Tailwind className、组件和状态上。
+> **本文件是平台 JSX 组件页面的 token / 组件实现适配层（数值层）**：提供色彩、圆角、字体、间距的具体值与组件模板，不产出配色、视觉 DNA 或页面风格。业务事实来自 `yida-prd` 输出的 `prd.md`，视觉事实来自 `yida-design` 输出的 `design.md`；本文件只负责把 `design.md` 的视觉方向落到平台 JSX 组件页面的内联样式、Tailwind className、组件和状态上。
 
 > 宜搭自定义页面默认使用 Tailwind utility `className` 组织视觉层，并保留内联 `style` 兜底。不能使用 CSS 文件、CSS Modules、shadcn/ui 或构建期样式方案。
 
@@ -30,21 +30,21 @@
 >
 > | 内容 | 使用方式 | 落地规则 |
 > | --- | --- | --- |
-> | 平台品牌色变量 | `--color-brand1-*` 是平台层品牌色变量；`--color-brand1-6` 是主色，`--color-brand1-1/2/3` 是浅底，`--color-brand1-7/9/10` 是深档或透明档 | 真实业务页的主操作、链接、选中态、信息提示和标签默认读取这些平台变量 |
+> | 平台品牌色变量 | `--color-brand1-*` 是平台层品牌色变量；`--color-brand1-6` 是主色，`--color-brand1-1/2/3` 是浅底，`--color-brand1-9/10` 是深档或透明档 | 真实业务页的主操作、链接、选中态、信息提示和标签默认读取这些平台变量 |
 > | 页面重构与局部美化 | 以当前应用主题为基准 | 优先调整布局、密度、间距、层级、素材、图标表达和局部辅助色 |
 > | 语义色 | 成功、警告、错误使用固定色 | 保持状态含义稳定，不跟随品牌色随意变化 |
 > | 大面积浅底 | 下拉选中项、提示块等使用页面级低透明度 token | 优先使用 `--oyd-control-selected-bg` / `--oyd-control-info-bg` |
 >
 > **light 模式用色**：业务协同表、数据管理页、录入表、工作台和门户在 light 模式下使用深色正文保证可读性，强调、选中、按钮、焦点和批量操作使用平台品牌色变量或当前页面确认的品牌色，边框使用浅色品牌混合。
 >
-> ⚠️ **常见错误**：把 `primaryHover` 设成 `brand1-1`（最浅档）会让填充主按钮 hover 时「泛白」；把 `hover` 设成 `brand1-9`（深档）当行 hover 底会让行「变暗」。填充按钮 hover 要比主色**亮一档**（`brand1-5`）、按下**深一档**（`brand1-7`）；通用浅色 hover 底用 `brand1-1`。
+> ⚠️ **常见错误**：把 `primaryHover` 设成 `brand1-1`（最浅档）会让填充主按钮 hover 时「泛白」；把 `hover` 设成 `brand1-9`（深档）当行 hover 底会让行「变暗」。填充按钮 hover 使用 `brand1-5`，按下使用深色档 `brand1-9`；通用浅色 hover 底用 `brand1-1`。
 
 ```javascript
 export function renderJsx() {
   var colors = {
     primary:       'var(--color-brand1-6)',  // 主色，用于主操作按钮、链接、选中态高亮
     primaryHover:  'var(--color-brand1-5)',  // 主色 hover：填充按钮/链接 hover，比主色亮一档
-    primaryActive: 'var(--color-brand1-7)',  // 主色按下：填充按钮 active，比主色深一档
+    primaryActive: 'var(--color-brand1-9)',  // 主色按下：填充按钮 active 使用深色档
     hover:         'var(--color-brand1-1)',  // 通用浅色 hover 底：列表行 hover、菜单项 hover
     active:        'var(--color-brand1-2)',  // 通用浅色激活/按下底
     disabled:      'var(--color-brand1-3)',  // 禁用态：浅、去饱和

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

@@ -242,7 +242,7 @@ openyida data query tasks <appType> --type todo|done|submitted|cc [--page 1 --si
 | 成员 | `["userId"]` | `["userId"]` |
 | 部门 | `["deptId"]` | `["deptId"]` |
 | 子表 | `"模糊搜索"` | `[{"textField_xxx":"值"}]` |
-| 关联表单 | 不支持直接查询 | `[{"appType":"xxx","formUuid":"xxx","instanceId":"xxx"}]` |
+| 关联表单 | 不支持直接查询 | `[{"appType":"xxx","formUuid":"xxx","formType":"receipt","instanceId":"xxx","title":"关联记录标题"}]` |
 
 ### 日期字段写入约定
 
@@ -261,17 +261,19 @@ openyida data create form APP_xxx FORM-xxx --expect-form-name 合同信息 --exp
 
 ### 关联表单字段
 
-关联表单字段保存时必须使用数组对象格式，包含三个必填字段：
+关联表单字段保存时必须使用数组对象格式，每项包含五个必填字段；`subTitle` 可选，省略时 CLI 会补为空字符串：
 
 ```bash
 # 示例：创建带关联客户的商机
 openyida data create form APP_xxx FORM-商机表 --expect-form-name 商机表 --expect-form-type receipt --data-json '{
   "textField_xxx": "商机名称",
-  "associationFormField_xxx": [{"appType":"APP_xxx","formUuid":"FORM-客户表","instanceId":"FINST-xxx"}]
+  "associationFormField_xxx": [{"appType":"APP_xxx","formUuid":"FORM-客户表","formType":"receipt","instanceId":"FINST-xxx","title":"客户名称","subTitle":""}]
 }'
 ```
 
-> 注意：字段名是 `instanceId`（不是 formInstId），三个字段缺一不可
+> 注意：字段名是 `instanceId`（不是 `formInstId`）。`appType`、`formUuid`、`formType`、`instanceId`、`title` 五个字段缺一不可。
+>
+> 查询结果中的 `associationFormField_xxx_id` 是只读派生字段，只用于读取关联 ID；保存和更新必须写原始的 `associationFormField_xxx` 字段。
 
 
 ## 实现前准备

package/yida-skills/skills/yida-data-management/references/data-format-guide.md

@@ -66,7 +66,7 @@
 | 部门 | `1123456` 或 `["1123456"]` | `["1123456"]` |
 | 城市 | `[省ID,市ID,区ID]` | `[省ID,市ID,区ID]` |
 | 子表单 | `"模糊搜索文本"` | `[{"textField_xxx":"值"}]` |
-| 关联表单 | 不支持直接查询 | `[{"appType":"xxx","formUuid":"xxx","instanceId":"xxx"}]` |
+| 关联表单 | 不支持直接查询 | `[{"appType":"xxx","formUuid":"xxx","formType":"receipt","instanceId":"xxx","title":"关联记录标题"}]` |
 
 ## 日期字段（DateField / CascadeDateField）
 
@@ -101,14 +101,17 @@ new Date('2024-06-30T00:00:00+08:00').getTime()
 
 ### 保存格式
 
-必须传入**数组对象**，每个对象包含三个必填字段：
+必须传入**数组对象**，每个对象包含五个必填字段；`subTitle` 可选，省略时 CLI 会补为空字符串：
 
 ```json
 [
   {
     "appType": "APP_xxx",
     "formUuid": "FORM-xxx",
-    "instanceId": "FINST-xxx"
+    "formType": "receipt",
+    "instanceId": "FINST-xxx",
+    "title": "客户名称",
+    "subTitle": ""
   }
 ]
 ```
@@ -117,7 +120,10 @@ new Date('2024-06-30T00:00:00+08:00').getTime()
 | --- | --- |
 | `appType` | 被关联表单所属应用的 appType |
 | `formUuid` | 被关联表单的 formUuid |
+| `formType` | 被关联表单类型，普通表单使用 `receipt` |
 | `instanceId` | 被关联数据的 formInstId（注意：字段名是 instanceId，不是 formInstId） |
+| `title` | 被关联记录在关联组件中展示的标题，应取真实记录标题字段值 |
+| `subTitle` | 可选的展示副标题；无值时传空字符串或省略 |
 
 ### 示例
 
@@ -129,7 +135,7 @@ openyida data query form APP_xxx FORM-客户表 --size 1
 # 2. 创建带关联的数据
 openyida data create form APP_xxx FORM-商机表 --expect-form-name 商机表 --expect-form-type receipt --data-json '{
   "textField_xxx": "商机名称",
-  "associationFormField_xxx": [{"appType":"APP_xxx","formUuid":"FORM-客户表","instanceId":"FINST-ABC123"}]
+  "associationFormField_xxx": [{"appType":"APP_xxx","formUuid":"FORM-客户表","formType":"receipt","instanceId":"FINST-ABC123","title":"杭州客户"}]
 }'
 ```
 
@@ -143,11 +149,13 @@ openyida data create form APP_xxx FORM-商机表 --expect-form-name 商机表 --
 }
 ```
 
+`associationFormField_xxx_id` 是查询投影出的只读派生字段，不能复制回 create/update payload。写入时必须使用不带 `_id` 后缀的原始字段 `associationFormField_xxx`。
+
 ### 注意事项
 
 - **instanceId 命名**：保存时字段名必须是 `instanceId`，不是 `formInstId`
 - **数组格式**：即使只关联一条数据，也必须使用数组格式 `[{...}]`
-- **三字段必填**：`appType`、`formUuid`、`instanceId` 缺一不可，否则返回参数校验失败
+- **五字段必填**：`appType`、`formUuid`、`formType`、`instanceId`、`title` 缺一不可；CLI 会在请求前拒绝不完整值
 - **跨应用关联**：如果关联的是其他应用的表单，需要使用对应应用的 appType
 - **API 限制**：部分宜搭环境可能限制通过 API 写入关联表单数据，建议在表单界面手动测试确认