npm - openyida - Versions diffs - 2026.7.27-beta.1 → 2026.7.27 - Mend

openyida 2026.7.27-beta.1 → 2026.7.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "openyida",
-  "version": "2026.7.27-beta.1",
+  "version": "2026.7.27",
   "description": "OpenYida CLI - 宜搭低代码 AI 开发工具（安装即用，零配置）",
   "bin": {
     "openyida": "bin/yida.js",

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

@@ -1,6 +1,6 @@
 ---
 name: yida-canvas-custom-page
-description: 宜搭 Code Canvas / 代码画布自定义页面开发规范，是自定义页面的默认链路。用于现代 React 交互、hooks 状态、可视化、AI 生成、官网、看板、工作台、列表、详情或需要崩溃隔离的页面（真 React18 + runtimeCode + importedModules）。也覆盖用户明确提到 code canvas、代码画布、YidaCodeCanvas、runtimeCode、importedModules，或在 Code Canvas 中使用门户、数据管理视图、成员、部门、上传等宜搭运行态组件的场景。
+description: 宜搭 Code Canvas / 代码画布自定义页面开发规范，是现代 React18 自定义页面的默认链路。用于官网、看板、工作台、列表、详情、门户壳、可视化、hooks 交互，以及用户明确提到 code canvas、代码画布、YidaCodeCanvas、runtimeCode、importedModules、门户组件、数据管理视图、成员、部门或上传组件的场景。
 ---
 # 宜搭 Code Canvas 自定义页面开发
@@ -12,22 +12,22 @@ Code Canvas 是宜搭的代码画布自定义页面链路：以 `YidaCodeCanvas`
 相较普通 `.oyd.jsx` 自定义页，Code Canvas 更适合：
 - 现代 React hooks 交互、图表、动效、复杂状态。
-- AI 首次生成页面：官网、看板、工作台、列表、详情、门户壳。
-- 需要组件级崩溃隔离和更现代前端体验的页面。
+- 首版页面生成：官网、看板、工作台、列表、详情、门户壳。
+- 需要 React18 函数组件、状态隔离和现代前端体验的页面。
 - 只需要通过 HTTP / 连接器读写数据的页面。
 - 需要在 Canvas 内受控接入门户、成员、部门、上传等宜搭运行态组件的页面。
-如果用户明确要求普通自定义页面 JSX/Jsx 组件链路，或页面强依赖普通自定义页实例桥，则选择 `yida-custom-page`：例如 `this.$(fieldId)` 双向绑定、`this.utils.yida.*`、`this.dataSourceMap`、提交流程深度耦合等。
+普通自定义页面使用 `yida-custom-page`：适用于用户明确要求 JSX/Jsx 普通页面，或页面需要 `this.$(fieldId)` 双向绑定、`this.utils.yida.*`、`this.dataSourceMap`、提交流程深度耦合等普通页面实例桥能力。
 ## 运行时事实
 - Canvas 源码写成 `.canvas.jsx` / `.canvas.tsx`，`openyida publish` 会自动走 Canvas 链路。
-- 页面源码路径按 Bash cwd 选择：从仓库根执行命令时用 `project/pages/src/...`；如果 cwd 已是 `<workspace>/project`，用 `pages/src/...`，不要写成 `project/pages/src/...`。
+- 页面源码路径按 Bash cwd 选择：从仓库根执行命令时用 `project/pages/src/...`；cwd 已是 `<workspace>/project` 时用 `pages/src/...`。
 - `runtimeCode` 在宿主页真实 `window` 中执行，入口必须返回 `YidaComp` / `YidaComp.default` / 组件函数。
 - 推荐入口写法是 `function YidaComp(props) { ... }`，或 `const App = ...; export default App;`。CLI 已兼容 `const/let/class YidaComp; export default YidaComp`，但生成新代码时优先避开同名默认导出，减少不同 Canvas 运行态装配器下的重复声明风险。
 - Canvas 组件没有普通页面实例上下文；数据读写通过 fetch、开放 API、连接器代理或显式 props 数据桥完成。
 - 第三方依赖走白名单；React、antd、ahooks、d3、recharts、Radix、framer-motion 等可按规则 import。
-- 宜搭运行态组件通过“原生组件桥 + fallback + 值归一化”接入；不改 `vc-deep-yida` 时，以宿主已存在的 `window.Deep` / `window.DeepYida` 探测为主，`window.YidaNativeComponents` 仅作为兼容入口。需要嵌入门户数据管理视图时探测 `DataManageViews`，并显式传入目标表单 `form.value/formUuid`。
+- 宜搭运行态组件通过“先探测、可用再增强、不可用就 fallback、值统一归一化”接入；以 `window.Deep` / `window.DeepYida` 探测为主，`window.YidaNativeComponents` 作为兼容入口。嵌入门户数据管理视图时使用 `DataManageViews`，并显式传入目标表单 `form.value/formUuid`。
 > 依赖白名单和运行时细节见 [dependencies-and-cdn.md](references/dependencies-and-cdn.md) 与 [employeefield-verification.md](references/employeefield-verification.md)。
@@ -40,8 +40,8 @@ Code Canvas 是宜搭的代码画布自定义页面链路：以 `YidaCodeCanvas`
 | 需要门户 topBanner / quickEntry / 数据卡片 | 使用本技能，按“门户组件桥”接入，必要时 fallback 自绘 |
 | 需要成员、部门、附件上传、图片上传 | 使用本技能，按“宜搭组件桥”接入并归一化值 |
 | 需要字段结构、公式、联动、权限、报表、流程 | 使用对应配置型技能承载，Canvas 只做展示和事件分发 |
-| 深度依赖普通页 `this` 实例桥 | 选择 `yida-custom-page` |
-| 强依赖普通自定义页实例数据桥：表单内字段双向绑定 `this.$(fieldId)`、`this.utils.yida.*`、`dataSourceMap`、提交流程深度耦合 | 使用 `yida-custom-page`（该实例桥由普通自定义页面提供） |
+| 深度依赖普通页 `this` 实例桥 | 使用 `yida-custom-page` |
+| 表单内字段双向绑定 `this.$(fieldId)`、`this.utils.yida.*`、`dataSourceMap`、提交流程深度耦合 | 使用 `yida-custom-page`（该实例桥由普通自定义页面提供） |
 ## 两类特殊组件场景
@@ -59,9 +59,9 @@ openyida sample yida-canvas-custom-page portal-native-components --output projec
 - `PortalTopBanner`、`PortalQuickEntry`：优先接入，适合门户首页的 Banner 和快捷入口。
 - `QuickAccessCard`、`RecentlyUsedCard`：先做运行态验证，再用于动态门户卡片。
-- `DataCard`、`PortalContainer`：依赖门户上下文、数据卡片配置和样式变量，作为增强能力谨慎启用。
+- `DataCard`、`PortalContainer`：仅在目标门户上下文、数据卡片配置和样式变量都验证通过后启用。
-做法：从 `window.Deep`、`window.DeepYida` 探测组件；若环境已有 `window.YidaNativeComponents` 也可兼容读取。探测失败时使用 Canvas 自绘卡片，页面仍保持可用。
+做法：从 `window.Deep`、`window.DeepYida` 探测组件；若环境已有 `window.YidaNativeComponents` 也可兼容读取。探测到组件时渲染原生组件；未探测到时渲染 Canvas 自绘卡片，页面保持可用。
 ### 2. 成员、部门、上传组件
@@ -78,7 +78,7 @@ openyida sample yida-canvas-custom-page portal-native-components --output projec
 - `DepartmentSelectField`：验证部门搜索、弹层、权限提示、单选/多选后启用。
 - `AttachmentField` / `ImageField`：验证 OSS 签名、上传权限、预览、删除、失败提示后启用。
-做法：原生组件只负责交互输入；页面业务状态保存归一化后的成员、部门、文件结构；提交仍通过 fetch / 连接器 / 开放 API 完成。组件条件未满足时 fallback 到 Canvas 自绘输入、搜索或链接录入。
+做法：原生组件负责交互输入；页面业务状态保存归一化后的成员、部门、文件结构；提交通过 fetch / 连接器 / 开放 API 完成。组件验证通过时使用原生组件；验证未通过时使用 Canvas 自绘输入、搜索或链接录入。
 > 详细桥接规则、值结构和验收清单见 [native-components-bridge.md](references/native-components-bridge.md)。
@@ -88,35 +88,35 @@ openyida sample yida-canvas-custom-page portal-native-components --output projec
 1. **Canvas 入口明确**：源码必须导出或返回 `YidaComp`，并把主组件作为默认导出或 `YidaComp` 暴露。
 2. **发布链路正确**：Canvas 源码使用 `.canvas.jsx` / `.canvas.tsx`，或发布时显式加 `--canvas`。
-3. **源码修改发布闭环**：只要本轮 Write/Edit/Create 了 `project/pages/src/*.canvas.jsx` 或 `project/pages/src/*.canvas.tsx`，本技能的本地校验只证明源码可发布，不等于远端页面已更新；final 前必须看到成功的 `openyida publish <source> <appType> <displayPageFormUuid>`。没有 publish 成功证据时，只能说“Canvas 源码已修改，尚未发布”，不能说“页面已更新 / 已重新发布”。
+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`。
+5. **使用 Canvas 函数组件契约**：Canvas 代码写 `YidaComp` React 函数组件；数据、生命周期和渲染都通过 hooks、props、fetch/连接器完成。需要 `renderJsx()`、`didMount()`、`this.forceUpdate()`、`this.utils.yida.*`、`this.dataSourceMap` 时切到 `yida-custom-page`。
 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`）。
+7. **交互控件必须受控且真正驱动数据**：筛选 `Select`、搜索 `Input`/`Input.Search`、周期切换、`Tabs`/`Segmented`、批量/重置 `Button` 等控件都用 `useState` 建立受控状态，绑定 `onChange`/`onClick`，并让 `Table`/列表/卡片的数据源通过 `useMemo` 按状态派生后渲染。切换筛选后若当前选中项失效，回退选中态（如 `selected < filteredRows.length ? selected : 0`）。
 ### 重要规则（IMPORTANT）
-1. **数据桥显式化**：通过 fetch、连接器或开放 API 读写数据，避免在页面里硬编码 Cookie、CSRF 或密钥。
-2. **组件增强可降级**：门户、成员、部门、上传组件都要 feature detect 和 fallback，组件缺失时页面不白屏。
-3. **值先归一化**：成员、部门、文件的原始返回值只作为 `raw` 调试，业务 payload 使用统一结构。
-4. **业务页主色跟随应用主题，sample 例外**：真实业务页默认读取 `--color-brand1-*` 与 `--color-group`，避免硬编码蓝色；但 `lib/samples/**` 和官方 sample 展示应用必须自带页面级固定主题（`followRuntimeTheme: false` 或等价 CSS 变量），每个 sample 使用不同色相，不允许被宿主应用主题统一染成黑灰。
+1. **数据桥显式化**：通过 fetch、连接器或开放 API 读写数据；Cookie、CSRF、密钥和签名留在平台、连接器或后端服务侧。
+2. **组件增强可降级**：门户、成员、部门、上传组件都做 feature detect 和 fallback；组件缺失时页面仍展示 Canvas 自绘基线。
+3. **值先归一化**：成员、部门、文件的原始返回值只作为 `raw` 检查信息，业务 payload 使用统一结构。
+4. **业务页主色跟随应用主题，sample 例外**：真实业务页默认读取 `--color-brand1-*` 与 `--color-group`；`lib/samples/**` 和官方 sample 展示应用自带页面级固定主题（`followRuntimeTheme: false` 或等价 CSS 变量），每个 sample 使用不同色相。
 5. **先验证再扩展业务**：原生组件、上传、组织搜索、弹层类能力先做 smoke 页面，确认 PC/移动端都可用后再承载复杂业务。
-6. **模板占位符必须可直发**：Canvas sample / generate-page 模板要同时支持“生成器替换变量”和“sample 原样发布”。禁止写 `JSON.parse('{{FEATURES_JSON}}')` 这类裸解析；JSON 占位符必须用 `parseTemplateJson(raw, fallback)`，展示文案占位符必须用 `withFallback` / `applyPageFallbacks` 兜底，确保未替换时不会运行期崩溃，也不会把 `{{BRAND_NAME}}`、`{{HERO_TEXT}}`、`{{OPENYIDA_RESEARCH_LEVEL}}` 等直接显示到页面。
-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 且没有真实数据时展示空态、表单入口、刷新/登记按钮。
-11. **页面生成二选一**：选择模板路径时，`openyida generate-page ... --spec ... --compile` 之后只读取 CLI 摘要或 `.openyida-page.json` 判断 `domainFidelity` / dataBinding，并对生成源码做小范围 Edit/patch；禁止立刻 Read 大段源码后全量 Write 覆盖同一路径。选择手写路径时，直接 Write 最终 `.canvas.jsx` 并快检/发布，不要先跑 `generate-page` 再完全覆盖。
-12. **Canvas 产物硬禁 emoji**：`.canvas.jsx` 源码、模板 spec 会渲染到页面的文案、JS 注释、数据常量和产物文件路径都不能包含 emoji。`generate-page --compile`、`compileCanvasLocal` 或 `publish` 报 emoji 错误时，先改 spec/源码/路径；不要尝试跳过 lint 或重复发布。
+6. **模板占位符必须可直发**：Canvas sample / generate-page 模板同时支持“生成器替换变量”和“sample 原样发布”。JSON 占位符用 `parseTemplateJson(raw, fallback)`，展示文案占位符用 `withFallback` / `applyPageFallbacks` 兜底，未替换时页面继续可运行，并显示业务化 fallback 文案。
+7. **light 页面使用清爽业务色**：业务列表、协同表、数据管理页、工作台和门户默认使用 light 模式；主操作、选中态、筛选焦点和批量操作使用品牌色或 sample 自带主题色，边框用浅色品牌混合。用户明确要求暗色大屏/夜间模式/高对比风格时使用深色主视觉。
+8. **门户运行态组件要补必需 props 和局部降级**：`QuickAccessCard` / `RecentlyUsedCard` 传 `theme="row-white"` 等必需 props；所有门户/字段/上传增强组件外层加局部 ErrorBoundary，单个组件不兼容时只降级该块，整页保持可用。
+9. **自定义主题必须页面内注入**：`--theme` 只接受平台预置 key；页面设计使用非预置主题（例如活力橙、深玫红、自定义暗黑金）时，在 Canvas 源码中注入 `style#yida-global-theme` 或等价 scoped CSS vars，并在根节点设置 `data-theme-scope="page"`。官方 sample 每个页面都做页面级主题注入。
+10. **真实交付使用真实数据源**：`openyida sample` 原样发布可以保留 sample/seed 数据，并在页面上标注为 sample/seed。完整应用或真实交付页只要需要列表、看板、详情记录，并且本轮已经创建/解析业务表单，就在 `page-spec.json` 写入 `dataBinding.mode=form`、真实 `appType/formUuid` 和字段映射，让页面从表单读取。需要演示数据时，先通过表单数据写入链路创建 demo/mock records，再由 Canvas 读取这些真实表单记录；没有真实数据时展示空态、表单入口、刷新/登记按钮。
+11. **页面生成二选一**：模板路径先写 `page-spec.json`，执行 `openyida generate-page ... --spec ... --compile`，之后读取 CLI 摘要或 `.openyida-page.json` 判断 `domainFidelity` / dataBinding，并对生成源码做小范围 Edit/patch。手写路径直接 Write 最终 `.canvas.jsx` 并快检/发布。
+12. **Canvas 产物使用纯文本业务文案**：`.canvas.jsx` 源码、模板 spec 会渲染到页面的文案、JS 注释、数据常量和产物文件路径都使用无 emoji 文本。`generate-page --compile`、`compileCanvasLocal` 或 `publish` 报 emoji 错误时，先改 spec/源码/路径，再重新校验发布。
 ## 数据真实性边界
 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 或固定指标说成真实业务数据。
+- **完整应用 / 真实交付**：先解析真实 `appType/formUuid/fieldId`，写入 `page-spec.json` 的 `dataBinding.mode=form` 后再 `openyida generate-page ... --spec <page-spec.json>`。需要 demo/mock 记录时，先用数据写入链路把记录写入表单并抽查，再让页面读取；前端 seedRows、静态 DEFAULT_FEATURES 或固定指标只作为 sample 数据标注。
-生成后如果 `.openyida-page.json` 的 `dataBinding.enabled !== true`，且页面仍展示列表/看板/详情业务记录，只能标为 sample/draft；完整应用 final 不得说“已接真实数据”。未接数据的交付页应保留真实空态、登记入口、刷新按钮和数据接入提示。
+生成后如果 `.openyida-page.json` 的 `dataBinding.enabled !== true`，且页面仍展示列表/看板/详情业务记录，交付状态标为 sample/draft；完整应用 final 只有在真实数据绑定已启用并验证后表述为“已接真实数据”。未接数据的交付页保留真实空态、登记入口、刷新按钮和数据接入提示。
 ## 模板占位符防回归
@@ -128,9 +128,9 @@ Canvas 模板有两条真实使用链路：
 因此模板源码必须满足：
 - 原始 sample 经过 `compileCanvasLocal` 能通过。
-- 原始 sample 执行 `YidaComp()` 不应抛错。
-- 可见渲染内容不得泄漏 `{{...}}` 占位符。
-- 源码不得包含 `JSON.parse('{{...}}')`；用安全解析函数接默认数据。
+- 原始 sample 执行 `YidaComp()` 能正常返回组件。
+- 可见渲染内容显示业务化文案或 fallback 文案。
+- JSON 占位符使用安全解析函数接默认数据。
 改 Canvas sample 后运行：
@@ -138,27 +138,26 @@ Canvas 模板有两条真实使用链路：
 npx jest tests/canvas-compile.test.js tests/generate-page.test.js --runInBand
 ```
-## Sample 改造沉淀纪律
+## Sample 质量规则
-批量优化 `lib/samples/**` 或官方 sample 展示应用时，不能只按当前模板微调颜色。每个 sample 都要形成可复用经验：
+批量优化 `lib/samples/**` 或官方 sample 展示应用时，按以下质量规则执行：
-- **先读复盘规范**：如果用户要求总结上轮经验、继续优化官方 sample、同步到官方 Samples 应用，或多次基于截图纠正页面质量，先读全局 [任务复盘与沉淀规范](../../references/task-retrospective.md)，再判断要补模板、测试、CLI 还是 skill。
-- **先看参考再动手**：用户要求“高级、Dribbble、好看、像产品/官网/详情页/数据表”时，先参考 Dribbble 的同类构图和免费可商用素材站的真实图片，再抽象成布局、层次、色彩和数据密度原则；不要照搬单个作品。
-- **说清参考转译**：交付 sample 改造时要用 1-2 句话说明参考被转译成了什么，例如“详情页采用对象 hero + sticky 元信息 + 时间线结构”、“数据管理页采用多维表工具栏 + 分组行 + 彩色标签密集表格”。不要只说“已参考 Dribbble”。
+- **先看参考再动手**：用户要求“高级、Dribbble、好看、像产品/官网/详情页/数据表”时，先参考 Dribbble 的同类构图和免费可商用素材站的真实图片，再抽象成布局、层次、色彩和数据密度原则，并转译为当前业务页面。
+- **说清参考转译**：交付 sample 改造时要用 1-2 句话说明参考被转译成了什么，例如“详情页采用对象 hero + sticky 元信息 + 时间线结构”、“数据管理页采用多维表工具栏 + 分组行 + 彩色标签密集表格”。
 - **每页独立主题**：sample 页默认 `themeScope=page` 或等价固定 CSS 变量；业务列表、详情、门户、工作台、官网、数据管理、大屏要有不同色相和不同信息节奏，不被宿主应用主题统一染色。
 - **非预置主题不走 `--theme`**：`deepBlue/podBlue/.../black` 这些平台 key 才能传给 `--theme`；自己设计的主题色要写到页面 `style#yida-global-theme` / scoped token 中，并确保每个 sample 页面都有这段注入。
-- **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 模板、测试或本技能规则。
-- **官网实景化不是只换 Hero**：强视觉官网至少形成“场景 Hero + 产品/服务 + 过程/空间”的摄影故事，品牌色从真实材质提取，section 要覆盖真实产品、制作/服务过程与到店/使用情境。具体按 `yida-page-uiux/references/landing/realistic-brand-homepage.md` 执行。
-- **交互要真的联动数据**：改完带筛选/搜索/切换的 sample，必须实际验证“改筛选 → 下方列表/表格/卡片数据发生变化”，不能只看 `compileCanvasLocal` 编译通过。装饰性 `defaultValue` 控件（无 `onChange`、数据源恒为固定 `seedRows`）视为缺陷，等同“按钮点了没反应”。
+- **Sample 数据要像真实业务，真实交付要接真实数据**：列表、详情、数据管理、工作台、大屏 sample 模拟足够丰富的数据、状态、筛选、趋势、分组、时间线或指标；完整应用/真实交付页优先接 `dataBinding.mode=form`，未接入时展示真实空态。
+- **工作台使用真实产品首页结构**：工作台页面铺满应用内容区，侧栏/导航/主面板形成真实产品首页；设计过程词不出现在可见页面。
+- **数据大屏地图要稳定**：大屏中心态势图如果是地图，优先探测宜搭宿主地图组件（如 `YoushuMap` / `ChinaMap` / `MapChart` 等），并提供内置区域地图组件兜底；正常展示态呈现地图、区域态势或业务空态。
+- **截图验收要覆盖模板共性**：导航覆盖、地图表现、配色、内容丰富度、产品首页结构等属于模板共性时，同步补 sample 模板、测试或本技能规则。
+- **官网实景化覆盖完整品牌旅程**：强视觉官网至少形成“场景 Hero + 产品/服务 + 过程/空间”的摄影故事，品牌色从真实材质提取，section 覆盖真实产品、制作/服务过程与到店/使用情境。具体按 `yida-page-uiux/references/landing/realistic-brand-homepage.md` 执行。
+- **交互要真的联动数据**：改完带筛选/搜索/切换的 sample，实际验证“改筛选 → 下方列表/表格/卡片数据发生变化”。控件使用受控状态、`onChange`/`onClick` 和派生数据源。
 - **线上发布后回读**：发布到官方 sample 应用后，用 `get-schema` 回读确认 `YidaCodeCanvas/runtimeCode` 已更新，必要时检查页面 class/关键文案/关键区块存在。
-- **CLI 缺口要落盘**：如果改造过程中发现 CLI 行为“回包成功但未生效”、缺少 sample 注册、缺少模板类型或测试覆盖，应优先补 CLI/测试，而不是只用一次性脚本绕过。
+- **CLI 能力缺口要补齐**：sample 注册、模板类型、发布生效、测试覆盖等 CLI 共性缺口优先补 CLI/测试。
 ## 开发流程
-下面命令以仓库根为视角；如果当前 cwd 已经是 `<workspace>/project`，把 `project/pages/src/...` 改成 `pages/src/...`。读取生成文件、Schema 或校验产物时优先用宿主 Read / Glob / Grep，不要在 CLI 成功后 Bash `cat`/`ls` 复核。
+下面命令以仓库根为视角；如果当前 cwd 已经是 `<workspace>/project`，把 `project/pages/src/...` 改成 `pages/src/...`。读取生成文件、Schema 或校验产物时优先用宿主 Read / Glob / Grep。
 ```bash
 # 1. 只读检查环境和登录态；真实创建资源前必须通过
@@ -187,9 +186,9 @@ openyida publish project/pages/src/<页面名>.canvas.jsx <appType> <formUuid>
 openyida get-schema <appType> <formUuid> --field-map-json
 ```
-`openyida check-page` / `openyida compile` 当前面向普通自定义页面 `.oyd.jsx` / `.jsx`；Canvas 以 `compileCanvasLocal` 和 `openyida publish .canvas.jsx` 的 Canvas 编译阶段为准。`compileCanvasLocal` 是发布前快检，不能替代 `openyida publish` 的远端写入证据。
+`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。
+如需保存完整 Schema，使用 create_file / Write / file edit tool 创建 `<projectRoot>/.cache/openyida/<页面名或任务名>/<页面名>-schema.json`；从 workspace 根执行后续命令时路径加 `project/` 前缀。
 ## 模板速查
@@ -211,11 +210,10 @@ openyida get-schema <appType> <formUuid> --field-map-json
 | --- | --- | --- |
 | [page-generation-guide.md](references/page-generation-guide.md) | 模板路由、官网素材、themeScope、Page Spec、primitives | 生成页面前必读 |
 | [native-components-bridge.md](references/native-components-bridge.md) | 门户、成员、部门、上传组件桥接和值归一化 | 需要宜搭运行态组件时必读 |
-| [dependencies-and-cdn.md](references/dependencies-and-cdn.md) | 依赖白名单、windowAlias、CDN、antd/dayjs 问题 | 新增依赖或排查依赖加载时必读 |
+| [dependencies-and-cdn.md](references/dependencies-and-cdn.md) | 依赖白名单、windowAlias、CDN 加载契约 | 新增依赖或验证依赖加载时必读 |
 | [employeefield-verification.md](references/employeefield-verification.md) | 运行时事实、原生组件验证、EmployeeField 验收 | 验证成员/字段组件时阅读 |
 | [data-bridge-guide.md](references/data-bridge-guide.md) | Canvas 内自建 HTTP 数据桥 | 接入真实数据时阅读 |
 | [canvas-design-system.md](references/canvas-design-system.md) | App 主题色、antd token、控件焦点/下拉 reset、图表配色 | 写样式和主题时阅读 |
 | [component-library-guide.md](references/component-library-guide.md) | 开源组件库推荐组合和禁用清单 | 选择 UI/图表依赖时阅读 |
 | [canvas-authoring-examples.md](references/canvas-authoring-examples.md) | 最小组件、hooks、副作用、图表示例 | 手写 Canvas 代码时阅读 |
 | [真实品牌官网 Playbook](../yida-page-uiux/references/landing/realistic-brand-homepage.md) | 实景素材组、材质配色、品牌旅程、Sample 无 CDN 兜底和视觉验收 | 生成或改造强视觉官网时必读 |
-| [任务复盘与沉淀规范](../../references/task-retrospective.md) | 官方 sample 改造经验、Dribbble 转译、页面级主题、发布回读、CLI/skill 反哺 | sample 批量优化、截图纠错、用户要求总结经验时阅读 |

package/yida-skills/skills/yida-canvas-custom-page/references/canvas-authoring-examples.md CHANGED Viewed

@@ -2,7 +2,7 @@
 本文件是从零写 Code Canvas 页面的 vetted 模板集。所有示例都遵守运行时事实：`YidaComp` 是普通 React18 函数组件，必须**导出或返回** `YidaComp` / `YidaComp.default`；只 `import` 依赖白名单内的包；副作用在 `useEffect` 里注册并返回 cleanup。
-> 白名单、windowAlias、CDN 与 antd/dayjs 陷阱见 [dependencies-and-cdn.md](dependencies-and-cdn.md)；读写宜搭数据见 [data-bridge-guide.md](data-bridge-guide.md)。
+> 白名单、windowAlias 与 CDN 加载契约见 [dependencies-and-cdn.md](dependencies-and-cdn.md)；读写宜搭数据见 [data-bridge-guide.md](data-bridge-guide.md)。
 ## 1. 最小可运行组件（入口 + 本地状态）
@@ -60,7 +60,7 @@ export default YidaComp;
 ## 3. 可视化：recharts 图表
-`recharts` 在白名单内（windowAlias `Recharts`）。标准 `import` 即可，CLI 本地编译会把它计入 `importedModules`。图表容器给定高度，避免 0 高度不渲染。图表颜色是 JS 传给库的字符串，**不能硬编码蓝**——用 `readBrandColor` 读平台品牌色，让线条跟随 App 主题（见 [canvas-design-system.md](canvas-design-system.md)）。
+`recharts` 在白名单内（windowAlias `Recharts`）。标准 `import` 即可，CLI 本地编译会把它计入 `importedModules`。图表容器给定高度，保证首屏可渲染。图表颜色是 JS 传给库的字符串，用 `readBrandColor` 读平台品牌色，让线条跟随 App 主题（见 [canvas-design-system.md](canvas-design-system.md)）。
 ```jsx
 import React from 'react';

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

@@ -1,11 +1,11 @@
 # Code Canvas 主色对齐与视觉落地
-本文件是 Code Canvas 页面的**实现层**引导：真实业务页怎么跟随宿主 App 的品牌主题色，而不是永远一片 antd 默认蓝；官方 sample / 示例展示应用则相反，必须自带页面级固定主题和差异化色盘，不被宿主 App 主题统一接管。视觉方向怎么定（页面类型、差异化、去 AI 味）是**栈无关**的，走共用的决策层技能 `yida-page-uiux`，本文件只讲 Canvas（React18 + antd + Tailwind）这套栈怎么把主色落地。
+本文件是 Code Canvas 页面的**实现层**引导：真实业务页跟随宿主 App 的品牌主题色；官方 sample / 示例展示应用自带页面级固定主题和差异化色盘。视觉方向（页面类型、差异化、去 AI 味）走共用的决策层技能 `yida-page-uiux`，本文件只讲 Canvas（React18 + antd + Tailwind）这套栈怎么把主色落地。
-> 决策层：需要视觉方向时调用 `use_skill("yida-page-uiux", "确定 Code Canvas 页面视觉方向")`（先做 Step 0 导航形态判定，再定工作台/仪表盘/列表/详情、5 维差异化、去 AI 味、禁 emoji）。
+> 决策层：需要视觉方向时先遵循 `yida-page-uiux` 技能（先做 Step 0 导航形态判定，再定工作台/仪表盘/列表/详情、5 维差异化、去 AI 味、禁 emoji）。
 > 实现层：本文件负责把「真实业务页主色跟随 App 品牌」和「sample 页面级独立主题」落到 antd token / Tailwind / 图表。
-> **前提是导航可见且是真实业务页**：跟随品牌主色是为了跟应用框架融合。若页面隐藏了应用导航（`isRenderNav=false`，沉浸/独立/门户/大屏，由 `yida-page-uiux` Step 0 判定），主色相可自立、不必严格跟品牌。若是 `lib/samples/**` 或官方 sample 展示应用，也必须自立主色相：`followRuntimeTheme: false`，antd `colorPrimary` / 图表色 / CSS 变量都喂页面自己的固定色盘，**语义色仍固定、去 AI 味红线仍生效**。
+> **前提是导航可见且是真实业务页**：跟随品牌主色是为了跟应用框架融合。页面隐藏应用导航（`isRenderNav=false`，沉浸/独立/门户/大屏，由 `yida-page-uiux` Step 0 判定）时，主色相可自立。`lib/samples/**` 或官方 sample 展示应用也使用自立主色相：`followRuntimeTheme: false`，antd `colorPrimary` / 图表色 / CSS 变量都喂页面自己的固定色盘，语义色保持固定。
 ## themeScope：页面级与应用级换肤
@@ -63,11 +63,11 @@ React.useEffect(function () {
 }, []);
 ```
-命令侧：`openyida generate-page product-homepage --theme-profile yida-app-theme --theme-scope page|app --compile`。不要默认手写全局 `:root` 覆盖；应用级换肤必须是显式选择。
+命令侧：`openyida generate-page product-homepage --theme-profile yida-app-theme --theme-scope page|app --compile`。页面级换肤写 scoped 变量；应用级换肤使用显式 `themeScope: app`。
 ## 自然语言推断规则
-Agent 不应要求用户说出 `themeScope`。当用户表达以下含义时，直接在 spec 中写入对应字段：
+按用户自然语言直接推断 `themeScope` 并写入 spec：
 | 用户说法 | spec |
 | --- | --- |
@@ -78,7 +78,7 @@ Agent 不应要求用户说出 `themeScope`。当用户表达以下含义时，
 同一句话同时出现“整体应用”和“不要影响导航”这类冲突时，以限制更强的 `page` 为准，或者简短确认一次。
-## 核心事实：CSS 变量能穿透，antd token 不能
+## 核心事实：CSS 变量直接级联，antd token 使用解析色值
 Canvas 的 `runtimeCode` 在**宿主页真实 `window`** 里 `new Function` 执行（见 SKILL.md「运行时事实」），组件挂在宿主 DOM 树内。由此得到主色落地的分界：
@@ -113,7 +113,7 @@ function useBrandColor(level, fallback) {
 }
 ```
-> ⚠️ **变量作用域**：若平台把 `--color-brand1-*` 定义在某个容器而非 `:root`，`document.documentElement` 可能读到空串 → 命中 fallback。更稳的做法是给组件根节点挂 `ref`，在 `useEffect` 里读 `getComputedStyle(rootRef.current)`（组件节点一定在变量作用域内），读到后 `setState` 触发一次重渲染。先用 `documentElement` 同步取，空串再降级到 ref 方案即可。
+> **变量作用域**：平台把 `--color-brand1-*` 定义在页面容器时，给组件根节点挂 `ref`，在 `useEffect` 里读 `getComputedStyle(rootRef.current)`，读到后 `setState` 触发一次重渲染。默认先用 `documentElement` 同步取值，空串时再用根节点 ref 读取。
 ## antd：ConfigProvider 注入 colorPrimary
@@ -157,17 +157,17 @@ export default YidaComp;
 ## 默认 light 模式避免灰黑主题
-业务列表、协同表、数据管理页、工作台和门户默认都是 light 模式。用户没有明确要求暗色大屏、夜间模式或高对比风格时，禁止把 `#111827`、近黑按钮、近黑描边、灰黑大阴影作为主题质感。正文可保留深色以保证可读性，但主操作、选中态、筛选焦点、批量操作和信息标签必须使用品牌色或 sample 自带主题色；卡片边框、表格分割线和下拉浮层边框使用浅色品牌混合，例如 `#DCE6F2`、`color-mix(in srgb, var(--oy-brand) 16%, #DDE8F4)`。
+业务列表、协同表、数据管理页、工作台和门户默认都是 light 模式。正文使用深色保证可读性；主操作、选中态、筛选焦点、批量操作和信息标签使用品牌色或 sample 自带主题色；卡片边框、表格分割线和下拉浮层边框使用浅色品牌混合，例如 `#DCE6F2`、`color-mix(in srgb, var(--oy-brand) 16%, #DDE8F4)`。用户明确要求暗色大屏、夜间模式或高对比风格时使用深色主视觉。
 ## 控件焦点态与下拉浮层 reset
-Code Canvas 页面只要出现搜索框、筛选下拉、日期选择、文本输入、成员/部门/上传等运行态控件，就必须在页面 `<style>` 顶部注入控件 reset。否则浏览器默认样式或宿主样式会在 focus 时把输入框/下拉触发器变成黑色粗边、字重变粗，用户会感觉和宜搭平台控件风格割裂。
+Code Canvas 页面只要出现搜索框、筛选下拉、日期选择、文本输入、成员/部门/上传等运行态控件，就在页面 `<style>` 顶部注入控件 reset，统一输入框、下拉触发器、focus ring 和字体粗细。
 实现规则：
 - `ConfigProvider` 增加 `getPopupContainer={(triggerNode) => (triggerNode && triggerNode.parentElement) || document.body}`，让 antd Select / DatePicker 等弹层留在当前页面作用域，避免浮层脱离页面样式。
 - 页面根节点使用 `oy-*` 根类，并在 `<style>` 顶部放 `OPENYIDA_CANVAS_CONTROL_CSS` 同款 reset。
-- 控件默认边框使用浅灰蓝，hover 使用品牌色低饱和混合，focus 使用浅品牌描边 + 3px 柔和 ring；禁止黑色粗边、系统默认 outline、突兀加粗。
+- 控件默认边框使用浅灰蓝，hover 使用品牌色低饱和混合，focus 使用浅品牌描边 + 3px 柔和 ring。
 - 下拉浮层统一 10px 圆角、浅边框、柔和阴影，active / selected 选项使用品牌浅底，不用黑色描边或浏览器原生 select。
 最小片段：
@@ -221,7 +221,7 @@ Canvas 节点在宿主树内，Tailwind 运行时对普通元素直接用 arbitr
 ## 图表 / recharts：用解析后的品牌色组
-图表颜色是 JS 传给库的字符串，必须用 `readBrandColor` 或解析 `--color-group`，不能硬编码 `#1677ff`。多系列图表优先读 `--color-group`，这样应用主题里的色组可以控制趋势线、柱状、排名和环形图的层次。
+图表颜色是 JS 传给库的字符串，使用 `readBrandColor` 或解析 `--color-group`。多系列图表优先读 `--color-group`，这样应用主题里的色组可以控制趋势线、柱状、排名和环形图的层次。
 ```jsx
 import React from 'react';

package/yida-skills/skills/yida-canvas-custom-page/references/component-library-guide.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Code Canvas 开源组件库选型
-本文件回答「Code Canvas 还能用哪些开源组件库」以及生成页面时该怎么选。结论先行：**只推荐已经在 Code Canvas 依赖白名单内、且 OpenYida 本地编译能映射到 windowAlias 的库**。白名单外的开源库即使 npm 上可用，也不能在 Canvas 源码里直接 `import`，否则运行时依赖加载不了。
+本文件回答「Code Canvas 还能用哪些开源组件库」以及生成页面时该怎么选。结论先行：页面默认使用已经在 Code Canvas 依赖白名单内、且 OpenYida 本地编译能映射到 windowAlias 的库；白名单外能力先走 Canvas 自绘、连接器、运行态组件桥或新增依赖评审。
 依赖白名单、版本和 windowAlias 以 [dependencies-and-cdn.md](dependencies-and-cdn.md) 为准；本文件只做产品化选型建议。
@@ -8,20 +8,20 @@
 | 场景 | 推荐库 | 何时使用 | 注意事项 |
 | --- | --- | --- | --- |
-| B 端业务界面 | `antd` | 表格、表单控件、按钮、弹窗、Tabs、Tag、Dropdown、分页 | 最外层包 `ConfigProvider`，主色用 `readBrandColor` 注入；线上环境注意 antd/dayjs 加载顺序问题 |
+| B 端业务界面 | `antd` | 表格、表单控件、按钮、弹窗、Tabs、Tag、Dropdown、分页 | 最外层包 `ConfigProvider`，主色用 `readBrandColor` 注入；按白名单 import，不自行注入依赖脚本 |
 | 图表看板 | `recharts` | 折线、柱状、面积、饼图、简单仪表盘 | 容器必须有稳定高度；颜色用品牌色和语义色，不硬编码默认蓝 |
 | 复杂可视化 | `d3` | 自定义关系图、力导向、桑基、特殊坐标系 | 只在 Recharts 覆盖不了时使用；自己管理 DOM/cleanup |
-| 图标 | 内联 SVG 语义集 | 按钮、操作、状态、导航等功能性图标 | 默认方案，零依赖且不会出现运行时组件 undefined |
-| 交互动效 | `framer-motion` | 抽屉、轻量过渡、局部状态切换 | B 端页面保持克制，避免大面积入场动画和炫技动效 |
-| Hooks 工具 | `ahooks` | 防抖、请求状态、定时器、列表状态等 | 用来简化状态逻辑，不要替代数据源治理 |
+| 图标 | 内联 SVG 语义集 | 按钮、操作、状态、导航等功能性图标 | 默认选择，零依赖且不会出现运行时组件 undefined |
+| 交互动效 | `framer-motion` | 抽屉、轻量过渡、局部状态切换 | B 端页面使用克制、局部、服务状态理解的动效 |
+| Hooks 工具 | `ahooks` | 防抖、请求状态、定时器、列表状态等 | 用来简化状态逻辑；数据读写仍走明确数据桥 |
 | 轻量主题组件 | `@radix-ui/themes` | 需要更原子化、更少 antd 味的按钮、卡片、布局控件 | 与 antd 混用时要统一圆角、字体、色彩和弹层层级 |
-| Markdown 展示 | `yida-plugin-markdown` | PRD、公告、帮助文档、AI 输出内容展示 | 只用于展示可信内容；不要把用户输入的 HTML 当可信内容渲染 |
+| Markdown 展示 | `yida-plugin-markdown` | PRD、公告、帮助文档、AI 输出内容展示 | 用于展示可信 Markdown 内容；用户输入内容先清洗再展示 |
 ## 默认选型规则
 1. **普通业务页默认 `antd + ahooks + 内联 SVG 图标`**：这是最稳的 B 端组合，适合列表、工作台、详情、审批辅助页。
 2. **看板默认 `antd + recharts + ahooks + 内联 SVG 图标`**：KPI、筛选、图表和明细表都能覆盖；只有 Recharts 做不了的图才引入 `d3`。
-3. **需要去 antd 味时，少量使用 `@radix-ui/themes`**：适合展示页、门户页、较轻的工具页；不要和 antd 两套视觉语言平均混用。
+3. **需要去 antd 味时，少量使用 `@radix-ui/themes`**：适合展示页、门户页、较轻的工具页；同一页面选一个主视觉语言，另一套组件只做局部补充。
 4. **动效只作为状态反馈**：`framer-motion` 用在抽屉、折叠、局部切换，不用于整页炫酷入场。
 5. **图标只作功能用途**：默认内联 SVG；`lucide-react` 只有在当前租户环境最小验证通过后才可使用，不进入默认模板。
@@ -29,11 +29,11 @@
 `lucide-react` 在依赖白名单内，但不同运行时打包形态可能只暴露 `window.DynamicIcon`，不一定稳定提供 `RefreshCw`、`TrendingUp` 等 named exports。若页面直接写 `<RefreshCw />` 而运行时该导出为 `undefined`，React 会报 `Minified React error #130`。
-因此默认模板和 AI 生成默认策略**不要 import `lucide-react`**。需要使用时先创建最小验证页，确认目标图标组件确实存在；未验证时用内联 SVG。
+因此默认模板使用内联 SVG 图标。需要使用 `lucide-react` 时先创建最小验证页，确认目标图标组件确实存在；验证前沿用内联 SVG。
-## 不推荐直接使用
+## 需要扩展白名单后使用
-以下库虽然开源常见，但当前 Code Canvas 白名单未承诺加载，不要在页面源码里直接 `import`：
+以下库属于常见开源选择，但当前 Code Canvas 白名单未承诺加载。页面先使用上文推荐组合；确需使用这些库时，先完成依赖扩展和运行时验证：
 - `@mui/material` / MUI
 - `@mantine/core`
@@ -43,7 +43,7 @@
 - `echarts`（普通自定义页面可通过 `loadScript` 用 ECharts；Canvas 当前白名单优先用 `recharts` / `d3`）
 - 任意未在 [dependencies-and-cdn.md](dependencies-and-cdn.md) 出现的 npm 包
-如果确实要新增库，必须先补齐三件事：OpenYida `canvas-compile.js` 的 alias 映射、Code Canvas 物料运行时依赖白名单和 CDN 资源、样式资源加载验证。缺一项都不能进入生成默认推荐。
+新增库需要补齐三件事：OpenYida `canvas-compile.js` 的 alias 映射、Code Canvas 物料运行时依赖白名单和 CDN 资源、样式资源加载验证。三项都完成后，再进入生成默认推荐。
 ## 生成页面时的组合示例
@@ -64,7 +64,7 @@ node -e "const fs=require('fs'); const {compileCanvasLocal}=require('./lib/app/c
 ## 自查清单
 - 所有 `import` 都在白名单内，并能出现在 `importedModules`。
-- 页面视觉方向已经先走 `yida-page-uiux`，不是靠组件库默认样式堆页面。
+- 页面视觉方向已经先走 `yida-page-uiux`，组件库服务于既定视觉方向。
 - antd 主色通过 `ConfigProvider` 跟随 App 品牌色。
-- 图表和图标服务于信息层级，不做装饰性堆叠；图标默认内联 SVG，不默认依赖 `lucide-react`。
-- 白名单外库没有被写进默认模板、示例或 agent 推荐话术。
+- 图表和图标服务于信息层级；图标默认内联 SVG，`lucide-react` 通过最小验证后再启用。
+- 默认模板、示例和推荐话术只包含当前已验证白名单能力。

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

@@ -1,6 +1,6 @@
 # Code Canvas 数据桥指南（自写 HTTP 读写宜搭数据）
-Code Canvas 运行时**没有** `this.utils.yida.*` / `dataSourceMap` / `this.$(fieldId)` 实例数据桥（核实自 `factory.tsx`：物料只透传 `code / runtimeCode / importedModules / pageType`，`YidaComp` 是普通函数组件，wrapper 只注入 `window`）。因此 `YidaComp` 要读写宜搭数据，只能**自己补一座 HTTP 桥**。本文件给出干净、可复用、合规的写法。
+Code Canvas 运行时**没有** `this.utils.yida.*` / `dataSourceMap` / `this.$(fieldId)` 实例数据桥；`YidaComp` 是普通 React 函数组件。因此 `YidaComp` 要读写宜搭数据，只能在组件内使用 HTTP 数据桥、连接器代理或显式 props 注入。本文件给出干净、可复用、合规的写法。
 ## 三条数据路径，先选对
@@ -8,9 +8,9 @@ Code Canvas 运行时**没有** `this.utils.yida.*` / `dataSourceMap` / `this.$(
 | --- | --- | --- |
 | 宜搭开放 API（OpenAPI，`appKey`/`appSecret` 签名） | **不可** | 需服务端签名；在浏览器里必然泄露 secret。只能由后端 / 连接器代理调，Canvas 不直连。 |
 | 平台已配置**连接器**（HTTP 连接器暴露的同源代理端点） | **推荐** | 同源 `fetch(url, { credentials: 'include' })` 带 cookie 即可，鉴权与密钥留在平台侧，符合数据源治理。 |
-| 内部表单数据端点（同源、依赖登录 cookie + CSRF） | 可，但要谨慎 | 与普通自定义页面 `this.utils.yida.searchFormDatas` 命中的是同类端点；需自行带 CSRF token，端点随环境可能变化，不要硬编码跨域绝对地址。 |
+| 内部表单数据端点（同源、依赖登录 cookie + CSRF） | 可，但要谨慎 | 与普通自定义页面 `this.utils.yida.searchFormDatas` 命中的是同类端点；使用同源相对路径、`credentials: 'include'` 和运行态 CSRF token。 |
-选路原则：**优先走连接器代理**（编码规则 #6「不要绕过数据源治理」）。真需要直连内部端点时，只用**同源相对路径** + `credentials: 'include'`，绝不在源码里硬编码 Cookie / CSRF / appSecret。
+选路原则：优先走连接器代理，让鉴权、密钥和数据源治理留在平台侧。真需要直连内部端点时，使用**同源相对路径** + `credentials: 'include'`，Cookie / CSRF / appSecret 由平台上下文或后端服务提供。
 ## 推荐：先写 dataBinding，再生成数据桥
@@ -39,10 +39,10 @@ OpenYida `generate-page --spec` 支持把 Canvas 数据契约写成结构化 `da
 数据绑定规则：
-- `mode=form` 必须来自真实 `appType/formUuid` 和字段 ID，不要猜字段。
-- `mode=connector/url` 必须使用同源代理端点，不把第三方密钥放进 Canvas 源码。
-- `mode=seed` 只能用于 `openyida sample`、离线预览或明确标注的演示页，不能标注“已接真实数据”；完整应用/真实交付页需要演示记录时，先把 demo/mock records 写入真实表单，再用 `mode=form` 读取。
-- 模板生成的 `DataBridge` 状态要保留，方便线上排查“接口没通 / 结构没识别 / 权限不足”。
+- `mode=form` 使用真实 `appType/formUuid` 和字段 ID，字段来源为 `get-schema`、表单创建结果或已确认的业务 Schema。
+- `mode=connector/url` 使用同源代理端点，第三方密钥留在连接器或后端服务侧。
+- `mode=seed` 用于 `openyida sample`、离线预览或明确标注的演示页；完整应用/真实交付页需要演示记录时，先把 demo/mock records 写入真实表单，再用 `mode=form` 读取。
+- 模板生成的 `DataBridge` 状态要保留，用于呈现“接口没通 / 结构没识别 / 权限不足”等运行时状态。
 ## 可复用读数据 Hook
@@ -125,14 +125,14 @@ function useYidaFetch(buildRequest, deps) {
 要点：
-- `credentials: 'include'` 让浏览器带上同源登录态，**不要**手动拼 `Cookie`；很多 Cookie 是 HttpOnly，`document.cookie` 读不到。
-- 如需 CSRF，优先从 `window.g_config._csrf_token` / `window.g_config.csrfToken` 动态读取，按接口要求放入 `_csrf_token` 请求参数和 / 或 `global_csrf_token` 头，别写死。
+- `credentials: 'include'` 让浏览器带上同源登录态；Cookie 由浏览器和平台管理。
+- 如需 CSRF，优先从 `window.g_config._csrf_token` / `window.g_config.csrfToken` 动态读取，按接口要求放入 `_csrf_token` 请求参数和 / 或 `global_csrf_token` 头。
 - 用 `AbortController` 在卸载 / 依赖变化时取消，避免 setState-after-unmount（对应编码规则 #5 副作用清理）。
-- 解析响应按**真实返回结构**处理，不要假设字段名；不同端点和运行态会出现 `data`、`result.data`、`content.data`、`content.result.data`、`list`、`values`、`records` 等包装。
+- 解析响应按**真实返回结构**处理；不同端点和运行态会出现 `data`、`result.data`、`content.data`、`content.result.data`、`list`、`values`、`records` 等包装。
 ## 表单查询返回体必须递归解析
-“数据管理里有 9 条，但 Code Canvas 页面显示 0 条”的常见根因不是没发请求，而是响应体被多层包装，页面只读了错误层级。统一使用下面的解析器，既兼容数组位置，也能在 `totalCount > 0` 但解析为 0 条时主动暴露故障。
+“数据管理里有数据，但 Code Canvas 页面显示 0 条”的常见失败模式是响应体被多层包装，页面只读了错误层级。统一使用下面的解析器，既兼容数组位置，也能在 `totalCount > 0` 但解析为 0 条时主动暴露故障。
 ```jsx
 function unwrapRows(payload) {
@@ -194,8 +194,8 @@ function normalizeFormRow(row) {
 保护规则：
-- 首屏只有 sample/离线预览可以用 seed 数据做本地预览兜底；真实交付页未接表单数据时展示空态和登记入口，不用 seedRows 冒充业务记录。真实接口返回后必须以接口为准。
-- 如果 `getTotalCount(json) > 0` 且 `unwrapRows(json).length === 0`，抛出“接口返回结构未识别”，不要展示“暂无数据”。
+- 首屏只有 sample/离线预览可以用 seed 数据做本地预览兜底；真实交付页未接表单数据时展示空态和登记入口。真实接口返回后以接口数据为准。
+- 如果 `getTotalCount(json) > 0` 且 `unwrapRows(json).length === 0`，展示“接口返回结构未识别”，并保留原始错误状态供定位。
 - 用 `openyida data query form <appType> <formUuid> --size 20` 或数据管理页核对总数，页面统计必须和真实表单一致。
 ## 在组件里用
@@ -239,7 +239,7 @@ export default YidaComp;
 ## 轮询只刷新数据，不刷新整页
-多人同时提交、点赞、更新状态的留言板 / 投票墙 / 任务看板，需要轮询让不同用户看到同一份状态。轮询只应更新统计和列表，不应刷新浏览器页面，也不应每次把页面打回 loading。
+多人同时提交、点赞、更新状态的留言板 / 投票墙 / 任务看板，需要轮询让不同用户看到同一份状态。轮询更新统计和列表，保留当前页面和已加载数据状态。
 ```jsx
 var POLL_INTERVAL_MS = 5000;
@@ -263,7 +263,7 @@ function YidaComp() {
       setLoading(true);
     }
-    // ⚠️ 直连 searchFormDatas.json 必须 GET + query（见下文「直连内部端点」红线）：
+    // 直连 searchFormDatas.json 必须 GET + query（见下文请求契约）：
     // formUuid/appType 放 URL query，分页参数名是 currentPage（不是 pageNumber）。
     var qs = new URLSearchParams({
       formUuid: '<FORM_UUID>',
@@ -307,18 +307,18 @@ function YidaComp() {
 }
 ```
-排序也要按用户语义明确：如果页面是“最新建议”，按 `gmtCreate` / 提交日期倒序；如果页面是“排行榜”，先按点赞数倒序，再用创建时间做 tie-break。不要因为按点赞排序，就误判新增的 0 赞数据“没有同步”。
+排序也要按用户语义明确：页面是“最新建议”时，按 `gmtCreate` / 提交日期倒序；页面是“排行榜”时，先按点赞数倒序，再用创建时间做 tie-break。验收时同时看总数和排序规则，确认新增记录是否进入正确位置。
-## 直连内部端点 `searchFormDatas.json` 红线（已验证，看板/列表最常踩）
+## 直连内部端点 `searchFormDatas.json` 请求契约
-不方便配连接器、只需读本应用表单数据时，可同源直连内部端点 `searchFormDatas.json`。三个**踩过坑、务必照做**的点，写错任意一个都会「看板全 0」或报「参数校验失败formUuid」，且三个请求会一起 reject：
+不方便配连接器、只需读本应用表单数据时，可同源直连内部端点 `searchFormDatas.json`。必须遵守三点请求契约，写错任意一个都会导致列表为空或接口报「参数校验失败formUuid」：
 1. **必须 `GET` + query 参数**，`formUuid`/`appType` 放 **URL query**。若用 `POST` 把 `formUuid` 塞进 body，后端从 query 读不到 → 直接报 **`参数校验失败formUuid`**。
 2. **分页参数名是 `currentPage`**（不是 `pageNumber`）；`searchFieldJson` 传 `'{}'` 表示不过滤。
 3. **返回列表在 `content.data`**，不是顶层 `data`。响应形如 `{ content: { data: [...], totalCount, currentPage }, success: true }`。上文的 `unwrapRows` 已递归兜底解包，直接用即可。（注意：openyida CLI `data query` 会**归一化**把 `data` 提到顶层，你用 CLI 抽查看到的是顶层 `data`，别被误导——浏览器直连拿到的是 `content.data`。）每行字段值在 `row.formData[fieldId]`，`SelectField`/`RadioField` 已是纯字符串，`DateField` 是 13 位毫秒数。
 ```jsx
-// 已验证：GET + query，读一个表单的数据
+// GET + query，读一个表单的数据
 function fetchFormData(appType, formUuid, signal) {
   var qs = new URLSearchParams({
     formUuid: formUuid,
@@ -337,20 +337,11 @@ function fetchFormData(appType, formUuid, signal) {
 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` 做保护，接口异常或未接 dataBinding 时展示错误/空态，不回退成漂亮 demo 列表。
-5. **刷新策略不对**：多人状态同步需要 5 秒左右轮询，但轮询只能刷新数值和列表，不能整页 reload，也不能首屏之后反复清空旧数据。
-6. **排序口径混淆**：数据存在但按点赞排行时，0 赞新数据可能排在后面；验收时要同时看总数和列表排序规则。
-交付验收清单：
+## 数据接入验收清单
 - 已确认 appType、formUuid 和字段 ID 来自真实表单 Schema。
 - 页面首屏接口返回后，统计总数与数据管理页 / `openyida data query form` 的总数一致。
-- 真实接口异常时显示错误原因，不静默回退成“暂无数据”。
+- 真实接口异常时显示错误原因和重试入口。
 - 提交、点赞等写操作成功后调用 silent reload，只更新统计和列表。
 - 轮询 `setInterval` 有 cleanup，页面隐藏时暂停请求。
@@ -358,5 +349,5 @@ function fieldOf(row, fieldId) { return (row.formData || row)[fieldId]; }
 - **确认再写**：删除、批量更新等不可逆操作，先让用户在 UI 里显式确认，不在 `useEffect` 里静默触发。
 - **幂等**：提交按钮加 loading 锁与去重键，避免重复写入。
-- **权限**：写操作是否允许由平台权限决定，浏览器侧不要伪造身份；失败按后端返回的 `errorMsg` 提示，不吞错。
-- **不硬编码密钥**：任何 `appSecret` / 签名逻辑都必须留在服务端 / 连接器，Canvas 源码里只出现同源相对路径与业务参数。
+- **权限**：写操作是否允许由平台权限决定；失败按后端返回的 `errorMsg` 提示。
+- **密钥位置**：任何 `appSecret` / 签名逻辑都留在服务端 / 连接器，Canvas 源码里只出现同源相对路径与业务参数。

package/yida-skills/skills/yida-canvas-custom-page/references/dependencies-and-cdn.md CHANGED Viewed

@@ -1,18 +1,17 @@
 # Code Canvas 依赖白名单与 CDN 加载
-本文件承载 Code Canvas 的依赖白名单、windowAlias 映射、编译改写规则，以及「预发正常、线上 `antd is not defined`」的根因与物料侧修复方向。核实自 `vc-deep-yida/src/components/yida-code-canvas` 源码（`dependencies.ts` / `factory.tsx`）。
+本文件承载 Code Canvas 的依赖白名单、windowAlias 映射与编译改写规则。依赖加载细节以当前宜搭物料运行时为准；本文只保留页面作者需要遵循的 import / CDN 契约。核实自 `vc-deep-yida/src/components/yida-code-canvas` 源码（`dependencies.ts` / `factory.tsx`）。
 ## 依赖白名单（核实自 `yida-code-canvas/dependencies.ts`）
-编译阶段把 `import` 改写为下列白名单的 `windowAlias` 引用，运行时按 `windowAlias` 加载到 `window` 上。带 `${cdn}` 的资源在预发走 `dev.g.alicdn.com`、线上走 `g.alicdn.com`（由 `isProd` 决定，见下方「预发/线上差异」）。
+编译阶段把 `import` 改写为下列白名单的 `windowAlias` 引用，运行时按 `windowAlias` 加载到 `window` 上。带 `${cdn}` 的资源前缀由平台运行时按当前环境决定。
 | 包名 | windowAlias | 资源 |
 | --- | --- | --- |
 | react | `React` | g.alicdn.com react 18.3.1 |
 | react-dom | `ReactDOM` | g.alicdn.com react-dom 18.3.1 |
-| antd | `antd` | g.alicdn.com antd **5.23.3** `antd-with-locales.js`（**依赖外部 `window.dayjs`**）|
+| antd | `antd` | g.alicdn.com antd **5.23.3** `antd-with-locales.js` |
 | @ant-design/icons | `icons` | g.alicdn.com ant-design-icons 5.5.1 |
-| dayjs | `dayjs` | 仅 `assetUrlPlaceholder`（dev CDN 的 locale 文件），**无 `assetUrl`** → 画布自身不会加载 dayjs core，依赖宿主提供 |
 | ahooks | `ahooks` | `${cdn}/platform/yida-assets/ahooks.js`（默认追加） |
 | d3 | `d3` | g.alicdn.com d3 7.9.0 |
 | recharts | `Recharts` | g.alicdn.com recharts 2.15.0 |
@@ -21,29 +20,10 @@
 | framer-motion | `FramerMotion` | `${cdn}/.../framerMotion.js` |
 | yida-plugin-markdown | `YidaMarkdown` | moduleFederation 0.0.4 |
-新增依赖必须同时满足：① 编译能把 import 抽进 `importedModules` 并映射到 windowAlias（见 `canvas-compile.js` 的 `MODULE_ALIAS_MAP`）；② 上表或平台运行时能把依赖加载到 window；③ `runtimeCode` 引用的变量名与 windowAlias 一致；④ CSS 资源可加载，否则组件可能渲染但样式/弹层异常。白名单外的包（yida-utils、`@ali/deep`、原生字段组件等）不能 `import`；带绑定的非白名单裸包 import 会在本地编译阶段硬失败。宜搭平台运行态全局对象必须显式使用 `window.Deep`、`window.DeepYida`、`window.YidaNativeComponents` 等 `window.*` 访问，不要从包中导入。
+新增依赖必须同时满足：① 编译能把 import 抽进 `importedModules` 并映射到 windowAlias（见 `canvas-compile.js` 的 `MODULE_ALIAS_MAP`）；② 上表或平台运行时能把依赖加载到 window；③ `runtimeCode` 引用的变量名与 windowAlias 一致；④ CSS 资源可加载。页面源码只 import 白名单包；`yida-utils`、`@ali/deep`、原生字段组件等宜搭运行态能力通过 `window.Deep`、`window.DeepYida`、`window.YidaNativeComponents` 等 `window.*` 访问。
-如果宜搭物料依赖表已经先于 OpenYida CLI 升级，且你已经确认运行时确实会注入某个新裸包，可以临时设置 `OPENYIDA_CANVAS_ALLOW_UNSUPPORTED_IMPORTS=1` 退回旧式 `window["pkg"]` 映射发布；这只是白名单漂移逃生舱，不应用来绕过 `useDataBinding` 这类不存在的 hook 或未验证依赖。
+当宜搭物料依赖表已经先于 OpenYida CLI 升级，且已确认运行时确实会注入某个新裸包时，可以临时设置 `OPENYIDA_CANVAS_ALLOW_UNSUPPORTED_IMPORTS=1` 退回旧式 `window["pkg"]` 映射发布。该开关只用于白名单漂移期间的发布验证；常规页面仍使用上表白名单和明确的 `windowAlias`。
-Canvas 没有官方 `useDataBinding` hook，不得从任何包 `import { useDataBinding }`。真实表单数据绑定使用页面内本地 `useYidaData(binding)`、`DataBridge` 与同源 `fetch` 实现。
+真实表单数据绑定使用页面内本地 `useYidaData(binding)`、`DataBridge` 与同源 `fetch` 实现。
 编译位置：OpenYida CLI **本地用 Babel** 把源码转译为 `runtimeCode` + `importedModules`（`import`→`window.<别名>`、`export default`→`YidaComp`、依赖名正则抽取），不调用任何在线编译服务，因此不依赖登录态、不经过风控。别名映射逐条镜像自 `dependencies.ts` 的 `getModuleAliasMap()`；运行时消费契约见 `factory.tsx`（`new Function` 执行 `runtimeCode` 取 `YidaComp`）。
-## 预发正常、线上报 `antd is not defined` 的根因
-现象：预发（`pre-*.alibaba-inc.com`）页面正常；线上（如 `*.aliwork.com`）白屏，控制台报 `antd is not defined` + `antd-with-locales.js` / `dayjs.js` 抛 `Cannot read properties of undefined (reading 'extend')`。
-根因（核实自源码）：
-- `antd-with-locales.js`（UMD）初始化时会执行 `dayjs.extend(...)`，其中 `dayjs` 是**外部依赖**，解析为 `window.dayjs`。若加载 antd 前 `window.dayjs` 未就绪 → `undefined.extend` 抛错 → antd 模块未定义 → 业务代码引用 `antd` 报 `antd is not defined`。
-- 正确顺序见 `vc-procode-comp/view.js`：先 `window.dayjs = window.__YCCommon?.Common?.dayjs` 再注入 antd。**但 `yida-code-canvas/factory.tsx` 原实现没有这步**：它 `loadDependencies` 时对 antd 只 `push(assetUrl)`，而 dayjs 条目只有 `assetUrlPlaceholder`、无 `assetUrl`，画布自身根本不会加载 dayjs；且加载前 `if (window[windowAlias]) return` 会跳过已存在依赖。
-- 于是环境差异被放大：
-  - **预发**：宿主设计器 / 同页其它 procode 组件已把 `window.antd`（含 dayjs）挂到全局 → 画布命中 `if (window.antd) return`，直接复用宿主 antd，正常。
-  - **线上该租户域**：宿主未预置 `window.antd` / `window.dayjs` → 画布现加载 `antd-with-locales.js`，但没有先设 `window.dayjs` → antd 初始化即抛错。（浏览器 debugger 里可见 `finalDependencies` 含 `antd` 却不含 `dayjs`，`window.dayjs` 为 `undefined`，即命中此缺陷。）
-- 附带因素：`isProd = location.hostname.indexOf('pre-') === -1` 是脆弱的域名启发式，非 `pre-` 前缀域一律判为线上，走 `g.alicdn.com` 前缀；antd 本身两端都硬编码 `g.alicdn.com`，故该差异不是 antd 主因，但会影响 `${cdn}` 类依赖（ahooks/radix/lucide/framer-motion/tailwind）的可达性。
-## 物料侧修复方向
-这是**物料层缺陷**（`factory.tsx` 未在 antd 前保证 `window.dayjs`），页面作者难以在 Canvas 源码内自救（`import dayjs` 也因 dayjs 无 `assetUrl` 不落地）。正确修复在 `factory.tsx` 的 `loadDependencies`：当 `finalDependencies` 含 `antd` 且 `window.dayjs` 未就绪时，**先**复用宿主 `window.__YCCommon?.Common?.dayjs`，否则**单独 `await` 加载 dayjs core**（如 `g.alicdn.com/code/lib/dayjs/<ver>/dayjs.min.js`），确保早于 antd 脚本执行，再进入原有 `assetsUrls` 批量加载。要点：dayjs 必须在**独立且被 await 的加载步骤**里先就绪，避免与 antd 放同一批并行加载产生竞态。
-临时规避（未改物料时）：让宿主页先行加载 antd/dayjs，或页面改用不依赖 dayjs 的轻组件（避开 DatePicker、时间 locale 等触发 `dayjs.extend` 的能力）。

package/yida-skills/skills/yida-canvas-custom-page/references/employeefield-verification.md CHANGED Viewed

@@ -1,42 +1,74 @@
 # Code Canvas 运行时事实与 EmployeeField 验证
-本文件承载 `yida-canvas-custom-page` 的运行时细节与原生组件验证示例，SKILL.md 只保留摘要与链接。
+本文件承载 `yida-canvas-custom-page` 的运行时边界与 EmployeeField 验证示例，SKILL.md 只保留摘要与链接。
-## 运行时事实（以 `vc-deep-yida/src/components/yida-code-canvas` 源码为准）
+## 运行时事实
-- `factory.tsx` 读取 `runtimeCode` 和 `importedModules`；用 `<Component {...props} />` 渲染，**只透传** `code / runtimeCode / importedModules / pageType` 四个属性。
-- `prototype.tsx` 的物料配置也只声明这四个属性，**没有** `dataSource` / `dataSourceMap` 绑定。
-- 代码经 `new Function` 包裹执行，wrapper 只注入 `window`（`iframeWindow` / `parentWindow`），**不注入 `this` 上下文**。因此 `YidaComp` 是普通 React 函数组件，**`this.utils.yida.*`、`this.dataSourceMap`、`export function didMount()` 等普通页面契约都不可用**。
+- Code Canvas 源码在宿主页 `window` 中执行，`YidaComp` 是普通 React 函数组件。
+- Canvas 使用 React 函数组件上下文；数据读写、生命周期和渲染通过 hooks、props、HTTP 数据桥或连接器完成。需要 `this.utils.yida.*`、`this.dataSourceMap`、`this.$(fieldId)`、`export function didMount()` 等普通页面契约时，使用 `yida-custom-page`。
 - 代码执行后必须返回 `YidaComp`、`YidaComp.default` 或组件函数。
-- Canvas 要读宜搭数据，只能在组件内**自写 HTTP 调用**（fetch 宜搭开放 API / 连接器）或依赖 props 注入，即“自己补一座数据桥”。如果用户明确要求普通自定义页面 JSX/Jsx 组件链路，或页面强依赖普通自定义页实例桥（`this.utils.yida.*`、`this.dataSourceMap`、`this.$(fieldId)` 双向绑定、流程提交深度耦合），选择 `yida-custom-page`。
+- Canvas 要读写宜搭数据，只能在组件内使用 HTTP 数据桥、连接器代理或显式 props 注入。如果用户明确要求普通自定义页面 JSX/Jsx 组件链路，或页面强依赖普通自定义页实例桥，选择 `yida-custom-page`。
-> 📦 依赖白名单表、windowAlias 映射、编译端点，以及「预发正常、线上 `antd is not defined`」根因与物料侧修复方向已拆到 [dependencies-and-cdn.md](dependencies-and-cdn.md)。
+> 依赖白名单表、windowAlias 映射与编译端点已拆到 [dependencies-and-cdn.md](dependencies-and-cdn.md)。
 ## 宜搭原生组件判断
-`EmployeeField`、`SelectField`、`DepartmentSelectField`、`AttachmentField` 等宜搭原生字段组件不能因为表单 Schema 支持同名字段，就默认在 Code Canvas JSX 中可用。使用前必须确认：
+`EmployeeField`、`SelectField`、`DepartmentSelectField`、`AttachmentField` 等宜搭原生字段组件按运行态组件接入。使用前确认：
-- `importedModules` 包含可解析的宜搭组件库，例如 `@ali/deep` 或平台约定的字段组件包。
-- Code Canvas 运行时有对应依赖映射和 CSS。
-- 组件所需页面上下文、组织权限、弹层容器、移动端版本均可用。
+- 宿主 `window.Deep` / `window.DeepYida` / `window.YidaNativeComponents` 能探测到目标组件。
+- 组件所需 CSS、页面上下文、组织权限、弹层容器、移动端版本均可用。
 - `onChange` 返回值结构能被后续数据保存或查询逻辑消费。
-如果缺少任一证据，降级为普通 UI：用 antd 或自定义控件选择候选用户，值只存已知 userId / unionId / 文本快照，不伪造成原生字段组件。
+这些原生组件从宿主 `window` 探测，不从 `@ali/deep` 等裸包 import。确认条件齐全时渲染原生组件；确认条件不足时使用普通 UI：用 antd 或自定义控件选择候选用户，值只存已知 userId / unionId / 文本快照。
 ## EmployeeField 验证示例
-示例只用于 Code Canvas 验证，不要复制到普通 `.oyd.jsx` 自定义页：
+示例用于 Code Canvas 验证；普通 `.oyd.jsx` 自定义页使用 `yida-custom-page` 的实例桥写法。
 ```jsx
-import React, { useState } from 'react';
-import { EmployeeField } from '@ali/deep';
+import React from 'react';
+function findEmployeeField() {
+  var sources = [];
+  if (window.Deep) { sources.push(window.Deep); }
+  if (window.YidaNativeComponents) { sources.push(window.YidaNativeComponents); }
+  if (window.DeepYida) {
+    sources.push(window.DeepYida.default || window.DeepYida);
+    if (Array.isArray(window.DeepYida)) {
+      sources = sources.concat(window.DeepYida);
+    }
+  }
+  for (var i = 0; i < sources.length; i += 1) {
+    var source = sources[i];
+    if (source && source.EmployeeField) {
+      return source.EmployeeField;
+    }
+  }
+  return null;
+}
 function YidaComp(props) {
-  var ReactRef = React;
-  var state = ReactRef.useState([]);
+  var EmployeeField = findEmployeeField();
+  var state = React.useState([]);
   var value = state[0];
   var setValue = state[1];
+  if (!EmployeeField) {
+    return (
+      <div style={{ padding: 16 }}>
+        <label style={{ display: 'block', marginBottom: 8 }}>负责人</label>
+        <input
+          placeholder="EmployeeField 不可用，使用文本 fallback"
+          onChange={function (event) {
+            setValue([{ name: event.target.value, raw: { fallback: true } }]);
+          }}
+        />
+        <pre style={{ marginTop: 12, fontSize: 12 }}>{JSON.stringify(value, null, 2)}</pre>
+      </div>
+    );
+  }
   return (
     <div style={{ padding: 16 }}>
       <EmployeeField
@@ -44,14 +76,11 @@ function YidaComp(props) {
         placeholder="请选择负责人"
         multiple={false}
         value={value}
-        onChange={(nextValue) => {
-          console.log('employee value', nextValue);
+        onChange={function (nextValue) {
           setValue(nextValue || []);
         }}
       />
-      <pre style={{ marginTop: 12, fontSize: 12 }}>
-        {JSON.stringify(value, null, 2)}
-      </pre>
+      <pre style={{ marginTop: 12, fontSize: 12 }}>{JSON.stringify(value, null, 2)}</pre>
     </div>
   );
 }
@@ -61,7 +90,7 @@ export default YidaComp;
 验收点：
-- 设计器属性中 `importedModules` 是否包含 `@ali/deep` 或等价字段组件库。
+- 组件探测结果能明确显示可用或缺失，不因缺失组件白屏。
 - 页面控制台没有 `EmployeeField is not defined`、样式缺失、弹层挂载错误。
 - 成员弹层能打开、搜索、选择、清空。
 - PC 和移动端都能完成选择。

package/yida-skills/skills/yida-canvas-custom-page/references/native-components-bridge.md CHANGED Viewed

@@ -4,7 +4,7 @@
 ## 核心策略
-Code Canvas 源码通过运行时桥接接入 `@ali/deep`、`@ali/vc-deep-yida` 或 `@ali/yida-ui` 已挂载到宿主 `window` 的组件。当前 Code Canvas 依赖白名单只负责加载通用前端包，这类宜搭运行态组件应保持在宿主桥接层，而不是进入 `importedModules`。本方案不要求修改 `vc-deep-yida`，以当前宿主已经存在的 `window.Deep` / `window.DeepYida` 探测为主。
+Code Canvas 里的宜搭运行态组件按“先探测、可用再增强、不可用就 fallback”的方式接入。字段、门户、数据管理视图等运行态组件统一从宿主 `window.Deep` / `window.DeepYida` / `window.YidaNativeComponents` 查找；页面源码只 `import` Code Canvas 白名单内的通用前端包。
 推荐方式是运行时桥接：
@@ -28,7 +28,7 @@ openyida sample yida-canvas-custom-page portal-native-components --output projec
 | --- | --- |
 | `window.Deep[name]` | `@ali/deep` 基础字段/组件全局 |
 | `window.DeepYida.default` 或 bundle 数组 | `vc-deep-yida` 运行包组件集合，按 `displayName` 匹配 |
-| `window.YidaNativeComponents[name]` | 可选兼容入口；存在时读取，不作为本方案前置条件 |
+| `window.YidaNativeComponents[name]` | 可选兼容入口；存在时读取，不作为前置条件 |
 业务代码统一走桥接函数读取宿主组件，便于隔离不同运行态差异。
@@ -47,17 +47,17 @@ openyida sample yida-canvas-custom-page portal-native-components --output projec
 - Banner 只传 `mainTitle`、`subTitle`、`bannerHeight`、`textPosition` 等稳定展示 props。
 - QuickEntry 只传静态 `content`、`titleConfig`、`themeConfig`。
-- 点击跳转由 Canvas 自己控制，避免依赖门户上下文隐式行为。
+- 点击跳转由 Canvas 自己控制，目标 URL 和打开方式写在页面代码里。
 ### QuickAccessCard / RecentlyUsedCard（可用，但 `theme` 必传）
-这两个是**容器型组件**：`componentDidMount` 时自己调用门户接口拉取应用列表（`QuickAccessCard` → 应用快捷入口，`RecentlyUsedCard` → 最近访问应用），再逐项渲染应用卡片。它们的 `renderItem` 内部执行 `this.props.theme.includes('column')` 决定卡片排布，而 **`theme` 在容器层没有默认值**——不传 `theme` 时，只要拉到的列表非空（真实登录态下几乎必然非空）就会抛 `Cannot read properties of undefined (reading 'includes')` 崩溃白屏。
+这两个是**容器型组件**，会在运行态自行拉取应用列表并渲染卡片。`theme` 是必传运行时契约；页面始终传入 `theme="row-white"` 或 `theme="column"`。
 必传 / 建议 props：
 | prop | 必要性 | 说明 |
 | --- | --- | --- |
-| `theme` | **必传** | 字符串。含 `column` → 纵向排布，否则横向。传 `'row-white'`（横排，与组件内层默认一致）或 `'column'`；**切勿留空** |
+| `theme` | **必传** | 字符串。含 `column` → 纵向排布，否则横向。推荐 `'row-white'`（横排）或 `'column'` |
 | `maxItems` | 建议 | 展示数量上限，缺省 8 |
 | `showAppDescription` | 可选 | 是否显示应用描述 |
 | `containerPrefix` | 可选 | 容器 className 前缀 |
@@ -66,21 +66,21 @@ openyida sample yida-canvas-custom-page portal-native-components --output projec
 使用要求：
-- **一定要传 `theme`**（如 `'row-white'`），这是这两个组件能否在 Canvas 里正常渲染的分水岭。
-- 列表数据由组件自取（依赖当前登录用户 + 门户接口），Canvas 既不需要、也无法通过 props 塞列表数据。
-- 组件缺失或无门户接口权限时，回退 Canvas 自绘应用入口卡片。
+- **始终传 `theme`**（如 `'row-white'`）。
+- 列表数据由组件自取（依赖当前登录用户 + 门户接口），Canvas 只负责容器 props、布局和 fallback。
+- 组件缺失或无门户接口权限时，渲染 Canvas 自绘应用入口卡片。
-> 崩溃根因核实自运行态 `@ali/vc-deep-yida` 异步 chunk（`QuickAccessCard` = chunk 53 / `RecentlyUsedCard` = chunk 52）：容器类 `renderItem` 里 `this.props.theme.includes('column')` 未做空值兜底，容器层 `theme` 亦无 `defaultProps`（仅内层展示组件默认 `'row-white'`，renderItem 绕过了它）。上游正确修复方向：容器补 `defaultProps.theme` 或改写为 `(theme||'').includes(...)`；页面侧无需改 `vc-deep-yida`，传 `theme` 即可。
+> 页面侧遵守必传 props 约束并做好局部降级：`theme` 有值，组件缺失或运行态不兼容时展示 Canvas fallback。
-### DataCard（暂不支持）
+### DataCard 使用边界
-`DataCard` 依赖数据卡片配置、图表上下文和门户变量，在 Code Canvas 无门户宿主上下文下无法有效工作：裸渲染只会显示「请选择要嵌入的数据卡片」空占位，无法真正承载数据。**当前暂不支持在 Canvas 页面复用 `DataCard`**。需要数据卡片时，用 Canvas 自绘卡片 + `fetch`/连接器/`yida-report` 取数据。
+数据卡片采用 Canvas 自绘卡片 + `fetch`/连接器/`yida-report` 取数。`DataCard` 需要完整门户数据卡片上下文，只有目标运行态确认该上下文可用时才接入。
-如果页面只是要「门户风格」，优先用 Canvas 自绘卡片并通过 fetch/连接器取数据；只有确实需要复用宜搭门户内置的快捷/最近应用卡片时，再按上面方式启用 `QuickAccessCard` / `RecentlyUsedCard`。
+页面只需要「门户风格」时，使用 Canvas 自绘卡片并通过 fetch/连接器取数据；需要复用宜搭门户内置的快捷/最近应用卡片时，按上面方式启用 `QuickAccessCard` / `RecentlyUsedCard`。
 ## 数据管理视图怎么用
-需要在自定义页面中嵌入门户里那块「数据管理视图」时，优先探测 `DataManageViews`。它来自 `@ali/vc-deep-yida` 的 `vc-data-manage-views`，门户中使用的就是这个组件；它只接收 `form` 配置，内部通过 `useFormInfo(form)` 请求 `getFormSchemaInfo.json`，再把 `multiViewInfos` 中非 `form` 类型的视图传给 `YidaFormManage` 渲染。`YidaFormManage` 是内部承载，不应作为门户数据管理视图的首选桥接入口。
+需要在自定义页面中嵌入门户里那块「数据管理视图」时，优先探测 `DataManageViews`，并把它当作黑盒组件使用。页面侧只传稳定的 `form` 配置，不自行构造底层数据管理 props。
 适用场景：
@@ -127,14 +127,14 @@ openyida sample yida-canvas-custom-page native-components-smoke --output project
 使用要求：
-- **不要在未指定 `form.value/formUuid` 时试渲染**，否则可能触发无效数据管理视图接口请求。
-- 组件依赖宿主运行态、登录态、权限、CSRF、`vc-deep-yida` 与 `yc-data-manage` 样式，找不到组件或权限不足时必须保留 Canvas fallback。
-- `DataManageViews` 会自动过滤 `viewType === 'form'` 的视图，并关闭导入、导出、批量操作等门户不需要的能力；页面侧不要绕过它直接拼内部 `YidaFormManage` props。
-- 如果只需要展示少量业务数据，用 Canvas 自绘表格 + `this.dataSourceMap`/连接器/`openyida data` 更稳；只有需要复用门户数据管理视图时使用 `DataManageViews`。
+- 先拿到 `form.value/formUuid`，再渲染 `DataManageViews`。
+- 组件依赖宿主运行态、登录态、权限、CSRF、`vc-deep-yida` 与 `yc-data-manage` 样式；组件缺失或权限不足时保留 Canvas fallback。
+- `DataManageViews` 会自动过滤 `viewType === 'form'` 的视图，并关闭导入、导出、批量操作等门户不需要的能力；页面侧统一使用它承载门户数据管理视图。
+- 只需要展示少量业务数据时，用 Canvas 自绘表格 + HTTP 数据桥 / 连接器 / `openyida data`；需要复用门户数据管理视图时使用 `DataManageViews`。
 ## 成员组件怎么用
-需要成员选择时，优先探测 `EmployeeField`。在 `vc-deep-yida` 中，`EmployeeField` 是对 `@ali/deep.EmployeeField` 的包装，并默认支持部门选择。
+需要成员选择时，优先探测 `EmployeeField`。它属于宿主运行态组件，先验证可用性，再接入业务页面。
 使用要求：
@@ -158,7 +158,7 @@ openyida sample yida-canvas-custom-page native-components-smoke --output project
 ## 部门组件怎么用
-需要部门选择时，优先探测 `DepartmentSelectField`。该组件依赖 `@ali/deep.SelectField`、`EmployeeSearch`、部门搜索接口和 CSRF 注入，因此要比成员组件更谨慎。
+需要部门选择时，优先探测 `DepartmentSelectField`。该组件依赖宿主通讯录能力、搜索接口和权限上下文，因此要比成员组件更谨慎。
 使用要求：
@@ -190,9 +190,9 @@ openyida sample yida-canvas-custom-page native-components-smoke --output project
 使用要求：
-- 原生上传只作为增强能力；找不到或失败时 fallback 到链接录入或业务连接器上传。
+- 原生上传作为增强能力；组件不可用或上传失败时，fallback 到链接录入或业务连接器上传。
 - Cookie、CSRF、OSS key 或内部上传密钥由平台、连接器或后端服务管理，Canvas 只消费安全返回结果。
-- 提交数据只使用归一化后的文件数组，`raw` 仅用于调试。
+- 提交数据只使用归一化后的文件数组，`raw` 仅用于检查。
 推荐归一化结构：
@@ -234,4 +234,4 @@ openyida sample yida-canvas-custom-page native-components-smoke --output project
 - 上传组件尚未完成 OSS 签名或上传权限校验。
 - 移动端组件形态与 PC 不一致且未适配。
-fallback 不是失败路径，而是 Canvas 页面的稳定基线；原生组件是增强体验。
+Canvas 自绘 fallback 是页面稳定基线；原生组件是增强体验。

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

@@ -4,24 +4,24 @@
 ## 首次生成模板路由
-用户通常不会直接说模板名，Agent 需要按自然语言选择模板。
+用户描述页面目标后，按下表把自然语言需求路由到确定模板。
-`generate-page` 的模板只用于选定运行时契约、数据桥、主题变量和首版 primitives；它不是最终视觉稿。生成真实页面时，必须结合 `yida-page-uiux` 的视觉方向决策块重写区块顺序、信息层级、局部构图、文案和样式节奏。可以保留模板的编译安全结构和必要 primitive class，但不要照搬默认 Hero、卡片网格、三段式卖点或库存文案。
+`generate-page` 的模板提供运行时契约、数据桥、主题变量和首版 primitives。生成真实页面时，结合 `yida-page-uiux` 的视觉方向决策块，产出业务化区块顺序、信息层级、局部构图、文案和样式节奏。保留模板的编译安全结构和必要 primitive class，替换为当前业务的 Hero、卡片、卖点和文案。
-页面生成路径必须二选一：走模板路径时，先写业务化 `page-spec.json` 并执行 `openyida generate-page ... --spec ... --compile`，之后只读取 CLI 摘要或 `.openyida-page.json`，再对生成源码做小范围 Edit/patch；不要立刻 Read 大段源码后全量 Write 覆盖同一路径。若已经明确最终页面结构、数据桥和视觉细节，走手写路径，跳过 `generate-page`，直接 Write 最终 `.canvas.jsx`。
+页面生成路径二选一：走模板路径时，先写业务化 `page-spec.json` 并执行 `openyida generate-page ... --spec ... --compile`，之后读取 CLI 摘要或 `.openyida-page.json`，再对生成源码做小范围 Edit/patch；已经明确最终页面结构、数据桥和视觉细节时，走手写路径，直接 Write 最终 `.canvas.jsx`。
 生成器会在 `.openyida-page.json` 中写入 `domainFidelity`，并在 CLI 输出中提示当前页面是否还依赖 sample fallback：
 - `domain-ready`：主要业务语义已覆盖，sample 只剩编译骨架。
 - `draft-needs-domain-spec`：用户已有业务要求，但 page spec 仍缺业务对象、指标、交互或视觉方向；继续补 spec 或改源码。
-- `sample-reference`：基本没有业务化输入，结果只能当 sample 参考，不能交付为真实应用页面。
+- `sample-reference`：业务化输入不足，结果定位为 sample 参考；继续补业务对象、字段、指标、视觉方向和数据绑定后再作为真实应用页面交付。
-真实业务页的 `page-spec.json` 不能只写 `template/title/output`。至少写清业务名称与定位、业务模块/对象、指标口径、用户动作或下钻方式、视觉方向；看板/列表/详情如果本轮已经创建或解析业务表单，必须写 `dataBinding.mode=form`、真实 `appType/formUuid` 和字段映射，官网/品牌页优先写 `assets` 或素材缺口。`sample` 是例子，不是框架；如果 `domainFidelity.sampleFallbacks` 里还出现 `features`、`metrics`、`roadmap`、`heroText` 等关键项，必须继续定制。
+真实业务页的 `page-spec.json` 至少写清业务名称与定位、业务模块/对象、指标口径、用户动作或下钻方式、视觉方向；看板/列表/详情如果本轮已经创建或解析业务表单，写入 `dataBinding.mode=form`、真实 `appType/formUuid` 和字段映射；官网/品牌页优先写 `assets` 或素材缺口。`domainFidelity.sampleFallbacks` 里出现 `features`、`metrics`、`roadmap`、`heroText` 等关键项时，继续补齐业务化规格。
 数据真实性边界：
 - `openyida sample` 或模板原样发布可以展示 sample/seed 数据，但页面必须标注 sample/seed。
-- 完整应用或真实交付页不能用前端 seedRows 冒充业务记录；需要演示数据时，先把 demo/mock records 写入真实宜搭表单，再由 Canvas 读取。
+- 完整应用或真实交付页使用真实业务记录；需要演示数据时，先把 demo/mock records 写入真实宜搭表单，再由 Canvas 读取。
 - 未写入 demo records 且没有真实数据时，页面应展示空态、表单入口、刷新/登记按钮和 dataBinding 接入提示。
 | 用户需求 | CLI 模板 | scene | 视觉要点 |
@@ -35,7 +35,7 @@
 | 主从分栏、工单处理台、左列表右详情 | `split-pane-detail` | `list` | 左侧队列、右侧详情、时间线、动作区 |
 | 页面内门户壳、多入口门户、隐藏导航门户 | `portal-shell-home` | `workbench` | 自绘门户导航、角色入口、常用应用、动态摘要 |
-如果用户要求“门户组件 / 成员 / 部门 / 上传组件”，继续使用 Code Canvas，但按 [native-components-bridge.md](native-components-bridge.md) 选择 `portal-native-components` 示例或桥接方案。
+如果用户要求“门户组件 / 成员 / 部门 / 上传组件”，继续使用 Code Canvas，但按 [native-components-bridge.md](native-components-bridge.md) 选择 `portal-native-components` 示例或桥接规则。
 当模板本身包含页面内应用导航（如 `workbench-home` 的侧边导航、`portal-shell-home` 的门户导航）时，生成的 `.openyida-page.json` 会默认写入 `appBlueprint.renderNav: false` / `navConfig.isRenderNav: false`。发布后必须用 `openyida update-form-config <appType> <formUuid> false "<页面标题>"` 隐藏宜搭原应用导航，避免双导航。
@@ -43,7 +43,7 @@
 命中 `official-homepage` 时，写代码前先形成轻量设计规格和素材清单。
-强视觉品牌先读 `yida-page-uiux/references/landing/realistic-brand-homepage.md`。不要把“有 heroImage”当作官网完成条件：至少规划场景 Hero、产品/服务、过程/空间三类素材，并给出从真实材质推导的页面级品牌 token、不同 section 的构图节奏和一个明确 CTA。
+强视觉品牌先读 `yida-page-uiux/references/landing/realistic-brand-homepage.md`。官网完成条件包括：场景 Hero、产品/服务、过程/空间三类素材，从真实材质推导的页面级品牌 token，不同 section 的构图节奏，以及一个明确 CTA。
 素材清单至少包含：
@@ -65,9 +65,9 @@
 2. AI 生成图片。先生成本地图片，再确认 CDN 配置，之后上传并回填 URL。
 3. 公开图库。只使用可公开访问且通过 HTTP 200 校验的图片 URL；生产交付优先转存到自有 CDN。
-若 `openyida cdn-config --show` 显示缺少 `accessKeyId/accessKeySecret/cdnDomain/ossBucket`，不要承诺已完成上传，可先用已验证公开 URL 测试，或提示用户补 CDN 配置。
+若 `openyida cdn-config --show` 显示缺少 `accessKeyId/accessKeySecret/cdnDomain/ossBucket`，交付状态标为“素材待上传”；可先用已验证公开 URL 测试，或提示用户补 CDN 配置。
-官方 Sample / 离线展示在无 CDN 时允许内嵌经过压缩的 JPEG/WebP data URI，保证源码原样发布也有真实图片；建议 3-5 张、单张不超过 250 KB、总量不超过 800 KB。生产页面不要沿用该兜底，应迁移到稳定 CDN。
+官方 Sample / 离线展示在无 CDN 时允许内嵌经过压缩的 JPEG/WebP data URI，保证源码原样发布也有真实图片；建议 3-5 张、单张不超过 250 KB、总量不超过 800 KB。生产页面使用稳定 CDN 素材 URL。
 ## 主题作用域