openyida 2026.7.18 → 2026.7.21

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

@@ -1,16 +1,29 @@
 ---
 name: yida-process-rule
-description: 为已有流程表单配置审批规则（审批/办理/抄送、条件/并行分支、字段权限、跳转规则、官方组件节点透传）。适用于流程表单已创建、需要调整审批流程时。
+description: 配置已有流程表单审批规则；schema-managed 流程由根技能或明确 context 路由到 schema workflow。
 ---
 
 # 宜搭流程规则配置技能
 
+> 资源边界：本技能只处理普通 OpenYida 资源；若根技能、上下文或 CLI guard 显示目标是 schema-managed，停止本技能并走 schema workflow；目标不明时回到根技能确认。
+> direct/standalone 路径才可执行本技能；schema-managed 路径必须回到 schema validate → plan → apply，不在本技能内降级写入。
+
+## Resource-First 使用门槛
+
+本技能是已有流程/表单上下文的默认流程修改入口：
+
+- 已有流程表单、`processCode`、流程 URL、bound process 或可确认的 workflow form 时，审批节点、条件分支、字段权限、抄送、跳转规则等诉求默认使用本技能。
+- 已有普通表单 `formUuid` 且用户要“配置审批 / 转为审批流程”，先确认是否对该表单启用流程；如果只是转流程且尚无流程，可由 `yida-create-process --formUuid` 复用该表单，不要新建同名表单。
+- 没有目标表单/流程，且用户明确从零创建审批系统时，才改用 `yida-create-process`。
+- 多个流程候选按根技能来源优先级选择；同级冲突或无法判断目标流程时才问用户。
+
 ## 严格禁止 (NEVER DO)
 
 - 不要在流程定义中使用猜测的 fieldId，必须先用 `yida-get-schema` 获取
 - 不要在未加载本技能内容的情况下编写流程定义 JSON，格式复杂且易出错
 - 不要用此技能创建流程表单，应使用 `yida-create-process`
 - 不要用 shell heredoc、`cat`/`echo`/`printf`/`tee` 或重定向生成流程定义 JSON
+- 已有 process/form context 时不要新建同类流程表单；在原流程上配置/更新。
 
 ## 严格要求 (MUST DO)
 
@@ -25,6 +38,7 @@ description: 为已有流程表单配置审批规则（审批/办理/抄送、
 | 用户意图 | 触发条件 |
 |---------|---------|
 | 配置/修改审批流程 | "配置审批"、"审批节点"、"条件分支"、"字段权限" |
+| 从零创建流程表单 | 仅无既有 form/process context 时 → 改用 `yida-create-process` |
 
 ## 触发条件
 
@@ -51,6 +65,14 @@ description: 为已有流程表单配置审批规则（审批/办理/抄送、
 
 ## 前提
 
+| 场景 | 使用技能 |
+|------|---------|
+| **已有流程表单**：只需修改/配置已有表单的审批流程规则 | **本技能（yida-process-rule）** |
+| **已有普通表单**：要启用/转换审批流程 | 先确认目标表单，再用 `yida-create-process --formUuid` 复用表单或回到本技能配置 |
+| **从零创建**：没有目标表单/流程，需要新建表单 + 配置审批流程 | **yida-create-process** |
+
+> 简单判断：有没有现成的流程表单？有 → 本技能；没有 → `yida-create-process`。
+
 执行本技能前需要已经有目标流程表单、`appType`、`formUuid`、字段 ID 和必要的审批人 / 条件信息。
 
 ## 使用方式
@@ -420,3 +442,15 @@ OpenYida 会自动兼容常见别名：
 yida-process-rule/
 └── SKILL.md                    # 本文档
 ```
+
+## 与其他技能配合
+
+| 步骤 | 技能 | 说明 |
+| --- | --- | --- |
+| 1 | 已有 app 或 `yida-create-app` | 复用已解析 `appType`；仅无 app 且允许创建时新建 |
+| 2 | 已有表单或 `yida-create-form-page` | 复用已解析 `formUuid`；仅缺表单且允许创建时新建，并获取字段 ID |
+| 3 | **本技能** | 配置表单的流程规则 |
+| 4 | `yida-custom-page` | 编写自定义页面代码 |
+| 5 | `yida-publish-page` | 发布自定义页面 |
+
+> **快捷方式**：使用 `yida-create-process` 技能可一键完成步骤 2-3（创建表单 + 配置流程）。

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

@@ -1,16 +1,30 @@
 ---
 name: yida-publish-page
-description: 将 JSX 源码编译发布到宜搭自定义页面。Babel 转 ES5 + UglifyJS 压缩 + Schema 构建 + saveFormSchema 接口部署。适用于自定义页面代码编写完成后的编译和发布。
+description: 自定义页面 JSX 编译发布技能；schema-managed 页面由根技能或明确 context 路由到 schema workflow。
 ---
 
 # 发布自定义页面
 
+> 资源边界：本技能只处理普通 OpenYida 资源；若根技能、上下文或 CLI guard 显示目标是 schema-managed，停止本技能并走 schema workflow；目标不明时回到根技能确认。
+> direct/standalone 路径才可执行本技能；schema-managed 路径必须回到 schema validate → plan → apply，不在本技能内降级写入。
+
+## Resource-First 发布目标
+
+发布前必须先解析目标页面 context；本技能优先服务已有页面：
+
+- 用户说“优化这个页面 URL / 修改这个页面 / 重新发布 / 覆盖现有页面”并提供页面 URL、`formUuid`、bound page 或 workspace 中可确认的 display page 时，直接把该页面作为发布目标，不创建 app/page。
+- bound page 是默认发布候选，不是强制目标；如果当前会话绑定页面 A，而用户本轮明确指定页面 B，必须先解析 B。B 有唯一 URL / display `formUuid` 时发布到 B；B 只有名称或描述且无法唯一匹配时先问用户；不要静默发布到 A。
+- 只有无法解析目标页面，且用户明确要新增一个页面容器时，才回到 `yida-create-page` 创建缺失 display page；已有 appType 不代表需要新建 app。
+- 发布目标必须是 `formType=display` 的自定义页面；普通表单、流程表单、数据底表的 `formUuid` 不能作为 `openyida publish` 第三个参数。
+- 多个页面候选按根技能来源优先级选择；同级冲突或无法判断页面类型时才问用户或执行只读 `list-forms` 确认。
+
 ## 严格禁止 (NEVER DO)
 
 - 不要在未加载对应页面子技能的情况下编写页面源码：普通自定义页面 JSX/Jsx 组件链路加载 `yida-custom-page`，Code Canvas 链路加载 `yida-canvas-custom-page`
 - 不要把 AI 生成的普通 React 项目代码直接发布；源码应使用 OpenYida 页面源码格式：普通自定义页面 JSX/Jsx 组件链路用 `.oyd.jsx` / `.jsx` 并通过 `check-page` / `compile` 预检，Code Canvas 用 `.canvas.jsx` 并通过 `publish` 的 Canvas 编译阶段校验
 - 不要在宜搭原生 `export function renderJsx()` 页面里手写 Hooks；如确需 `useState/useEffect`，必须使用 `.oyd.jsx` 的 `export default function Page()` authoring 模式，让 OpenYida 兼容编译器降级
 - 不要编造 appType 和 formUuid，必须从已有记录或命令返回中获取
+- 用户已给页面 URL / `formUuid` / bound page 时，不要先创建新 app 或新 page；直接确认目标并发布到已有页面。
 
 ## 严格要求 (MUST DO)
 
@@ -22,17 +36,19 @@ description: 将 JSX 源码编译发布到宜搭自定义页面。Babel 转 ES5
 - corpId 不匹配时，必须询问用户是否切换组织，不得强行发布
 - 重新发布已有自定义页面时，`openyida publish` 会自动读取目标页面现有 Schema 并合并页面级 `dataSource`；不要靠 Agent 口头承诺“保留数据源”，必须使用新版 CLI 的默认保护能力
 - 如果源码包含 `this.dataSourceMap.`，而发布输出包含 `No custom page data sources to preserve`，本次发布不能视为完成；说明源码依赖设计器数据源但目标页没有可保留数据源。必须改为 `this.utils.yida.*` / 入口型页面后重新 check、compile、publish，或先通过 `yida-data-source-connectors` 创建并绑定数据源后重新发布
+- **发布证据闭环**：本轮只要 Write/Edit/Create 了 `project/pages/src/*.{canvas.jsx,canvas.tsx,oyd.jsx,jsx,tsx}`，final 证据只认真实执行成功的 `openyida publish <source> <appType> <displayPageFormUuid>` 命令结果；本地文件编辑、diff、`check-page`、`compile`、`compileCanvasLocal` 或口头声明都不能证明远端页面已更新
 - **本技能不读写 memory**：发布操作通过 CLI 命令写入宜搭平台，不依赖跨会话的 memory 状态
 
 ## 适用场景
 
-编写完自定义页面 JSX 代码后，执行此技能将代码编译发布到宜搭平台。
+编写完自定义页面 JSX 代码后，执行此技能将代码编译发布到宜搭平台。已有页面 URL / `formUuid` / bound page 时，默认发布到该已有页面。
 通常在 `yida-custom-page`（普通自定义页面 JSX/Jsx 组件链路）或 `yida-canvas-custom-page`（Code Canvas 链路）之后执行。
 
 ## 触发条件
 
 **正向触发**：
 - "发布页面"、"上线页面"、"部署页面"
+- "优化这个页面 URL"、"修改现有页面后重新发布"
 - `yida-custom-page` 或 `yida-canvas-custom-page` 代码编写完成后的下一步
 - "编译发布"、"把代码发布到宜搭"
 
@@ -70,6 +86,13 @@ openyida list-forms <appType> --keyword <页面名>
 
 只选择 `formType=display` 的 `formUuid` 作为发布目标。源码里用于 `this.utils.yida` 读写数据的普通表单常量（如 `FORM_SKILL`、`FORM_DATA`、`FORM_TABLE`）通常是数据底表，不能作为 `openyida publish` 的第三个参数。
 
+## Final 证据契约
+
+- final 中“页面已更新 / 已重新发布 / 已上线”的依据只能是成功的 `openyida publish <source> <appType> <displayPageFormUuid>` 命令结果，最好同时带发布输出中的 URL、`formUuid`、`success:true` 或 health-check 摘要。
+- `<source>` 必须是本轮实际 Write/Edit/Create 过的页面源码；`<displayPageFormUuid>` 必须是已解析的 display 自定义页面。发布了其他文件或其他目标页面，不满足本轮源码修改的 doneWhen。
+- 若 publish 没执行、执行失败、目标不明、登录态/组织不一致或用户要求先暂停，final 只能说“源码已修改，尚未发布”，并给出下一步需要执行的 publish 命令或阻塞原因。
+- 普通自定义页面的 `check-page` / `compile`、Code Canvas 的 `compileCanvasLocal` 或 `generate-page --compile` 都是发布前 guard，不是远端完成证据。
+
 ## 数据源保留
 
 `openyida publish` 默认是非破坏式发布：保存新 JSX Schema 前会调用 `getFormSchema` 读取目标自定义页面已有 Schema，提取 Page 组件上的 `dataSource`，再与发布脚本内置的 `urlParams`、`timestamp` 数据源合并。用户在宜搭设计器里手工创建的 HTTP / VALUE / URI 等页面级数据源会随新源码一起保留。
@@ -116,8 +139,8 @@ body { background-color: #f2f3f5; }
 
 ## 注意事项
 
-- 发布目标地址由当前环境配置和 token session 中的 `base_url` 决定
-- 碰到组织 corpId 不匹配时，询问用户是否创建新应用发布
+- 发布目标地址由当前环境配置和 auth context（默认 token session；`YIDA_AUTH_ENABLED=true` 时为宿主注入 token）中的 `base_url` 决定
+- 碰到组织 corpId 不匹配时，询问用户是重新登录到目标组织，还是确认在当前组织继续发布到已解析页面；不要通过新建应用规避不匹配
 - **编写源码前必须先加载对应页面子技能**：普通自定义页面 JSX/Jsx 组件链路调用 `use_skill("yida-custom-page", "编写宜搭普通自定义页面 JSX")`；Code Canvas 链路调用 `use_skill("yida-canvas-custom-page", "编写 Code Canvas 自定义页面")`。旧式 `renderJsx` 写法不要使用 Hooks，现代普通自定义页面 authoring 写法必须走 `.oyd.jsx` 兼容编译；Canvas 源码写成 `.canvas.jsx`
 
 ## 异常处理
@@ -147,3 +170,22 @@ body { background-color: #f2f3f5; }
 | corpId 不匹配 | 停止执行，询问用户是否切换组织或创建新应用 |
 | 网络超时 | 重试 1 次，仍失败则停止并提示用户检查网络 |
 | 未知错误 | 停止执行，完整展示错误信息，建议用户反馈问题 |
+
+## 与其他技能配合
+
+本技能在完整开发流程中的位置：
+
+```
+resolve existing page or create missing page → yida-custom-page / yida-canvas-custom-page → [本技能] yida-publish-page
+                                                                                 ↑
+                                                                            编写 JSX 代码
+```
+
+| 相关技能 | 关系说明 |
+|---------|----------|
+| `yida-create-page` | 可选前置技能，仅在目标 display page 缺失且允许新增时创建页面容器，获取 formUuid |
+| `yida-custom-page` | native 前置技能，编写 `.oyd.jsx` / `.jsx` 源码 |
+| `yida-canvas-custom-page` | Code Canvas 前置技能，编写 `.canvas.jsx` 源码 |
+| `yida-create-form-page` | 无关，用于创建表单页面，不需要本技能发布 |
+| `yida-page-config` | 后续技能，发布后可配置页面公开访问/分享 |
+| `yida-ppt-slider` | 特殊场景，PPT 幻灯片页面也使用本技能发布 |

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

@@ -1,10 +1,16 @@
 ---
 name: yida-report
-description: "宜搭原生报表创建，支持 16 种图表/表格/筛选器组件。普通「报表」「统计」需求默认使用本技能。触发词：「报表」「统计」「图表」「数据汇总」。"
+description: "Standalone 创建宜搭原生报表；如果请求来自 Schema-as-Code manifest/state，停止，不降级直写。"
 ---
 
 # 宜搭原生报表技能
 
+## 适用范围：standalone 资源
+
+- SAC Phase 1 下，本技能只处理明确 standalone 的原生报表。用户提供 Schema-as-Code manifest、要求 schema validate/plan/apply，或报表身份来自 Schema-as-Code state 时，不执行创建、追加或发布，稳定停止为 unsupported。
+- 不得把 SAC unsupported/conflict/uncertain 降级为 `create-report` 等 legacy 写入，不得按标题、组件类型或数组位置 adopt、猜 report/chart/filter ID。
+- 只有报表明确 standalone/unmanaged，或用户明确要求 standalone legacy 报表命令时，以下示例、stdout/stderr 和返回行为才按原契约使用；所有权不明确时零远端写。
+
 ## 严格禁止 (NEVER DO)
 
 - 不要在前端直接聚合表单数据，必须通过宜搭原生报表的 `getDataAsync.json` 或 `getCacheData.json` 接口获取聚合数据
@@ -151,241 +157,9 @@ POST /alibaba/web/{appType}/visual/visualizationDataRpc/getDataAsync.json
 | `YoushuTimeFilter` | 时间筛选器 | `buildSchema.timeFilter()` | 筛选 |
 | `YoushuInputFilter` | 区间筛选器 | `buildSchema.inputFilter()` | 筛选 |
 
-### 核心工具函数
-
-Schema 构建脚本提供以下核心函数，使用前需先引入：
-
-```javascript
-const {
-  buildSchema,           // 各组件 Schema 构建器
-  buildDataSetEntry,     // 构建数据集配置
-  buildFieldDefinition,  // 构建字段定义
-  buildFilterItem,       // 构建过滤条件
-  buildOrderByItem,      // 构建排序项
-  generateComponentId,   // 生成唯一组件 ID
-} = require('./build-yida-report-schema');
-```
-
-### 数据集配置（dataSetModelMap）
-
-所有报表组件通过 `dataSetModelMap` 配置数据源，每个数据集由 `buildDataSetEntry` 构建：
-
-```javascript
-buildDataSetEntry({
-  cubeCode: 'your_cube_code',        // 数据集 cubeCode（必填）
-  fieldDefinitionList: [              // 字段定义列表
-    buildFieldDefinition({
-      alias: 'date',                  // 字段别名（fieldKey）
-      aliasName: '日期',              // 字段显示名称
-      isDim: true,                    // true=维度，false=度量
-      dataType: 'DATE',              // STRING | NUMBER | DATE | BOOLEAN | ARRAY
-      aggregateType: 'NONE',         // NONE | SUM | AVG | COUNT | MAX | MIN | COUNT_DISTINCT
-      timeGranularityType: 'DAY',    // YEAR | QUARTER | MONTH | WEEK | DAY | HOUR | MINUTE | null
-    }),
-    buildFieldDefinition({
-      alias: 'sales',
-      aliasName: '销售额',
-      isDim: false,
-      dataType: 'NUMBER',
-      aggregateType: 'SUM',
-    }),
-  ],
-  fieldList: ['date', 'sales'],       // 查询字段别名列表
-  filterList: [],                     // 过滤条件列表
-  orderByList: [                      // 排序列表
-    buildOrderByItem('date', 'ASC'),  // ASC | DESC
-  ],
-  limit: 1000,                        // 数据条数限制
-  // 以下为筛选器专用参数
-  cubeCodes: ['your_cube_code'],      // cubeCode 数组（筛选器使用）
-  valueField: ['field_alias'],        // 值字段数组（筛选器使用）
-  labelField: ['field_alias'],        // 显示字段数组（筛选器使用）
-})
-```
-
-### 常用组件 Schema 构建示例
-
-#### 指标卡
-
-```javascript
-buildSchema.simpleIndicatorCard({
-  dataSetModelMap: {
-    kpi_dataset: buildDataSetEntry({
-      cubeCode: 'your_cube_code',
-      fieldDefinitionList: [
-        buildFieldDefinition({ alias: 'total_sales', aliasName: '总销售额', isDim: false, dataType: 'NUMBER', aggregateType: 'SUM' }),
-        buildFieldDefinition({ alias: 'order_count', aliasName: '订单数', isDim: false, dataType: 'NUMBER', aggregateType: 'COUNT' }),
-      ],
-      fieldList: ['total_sales', 'order_count'],
-    })
-  },
-  settings: { columnCount: 4, columnCountForH5: 2 }
-})
-```
-
-#### 折线图
-
-```javascript
-buildSchema.lineChart({
-  dataSetModelMap: {
-    line_dataset: buildDataSetEntry({
-      cubeCode: 'your_cube_code',
-      fieldDefinitionList: [
-        buildFieldDefinition({ alias: 'date', aliasName: '日期', isDim: true, dataType: 'DATE', timeGranularityType: 'DAY' }),
-        buildFieldDefinition({ alias: 'sales', aliasName: '销售额', isDim: false, dataType: 'NUMBER', aggregateType: 'SUM' }),
-      ],
-      fieldList: ['date', 'sales'],
-      orderByList: [buildOrderByItem('date', 'ASC')],
-    })
-  },
-  settings: {
-    titleConfig: { label: '销售趋势' },
-    height: 400,
-    smooth: true,
-    drillDown: false,
-  }
-})
-```
-
-#### 饼图（环形图）
-
-```javascript
-buildSchema.pieChart({
-  dataSetModelMap: {
-    pie_dataset: buildDataSetEntry({
-      cubeCode: 'your_cube_code',
-      fieldDefinitionList: [
-        buildFieldDefinition({ alias: 'category', aliasName: '类别', isDim: true, dataType: 'STRING' }),
-        buildFieldDefinition({ alias: 'amount', aliasName: '金额', isDim: false, dataType: 'NUMBER', aggregateType: 'SUM' }),
-      ],
-      fieldList: ['category', 'amount'],
-    })
-  },
-  settings: {
-    titleConfig: { label: '销售占比' },
-    innerRadius: 0.6,  // >0 为环形图
-  }
-})
-```
-
-#### 基础表格（明细表）
-
-```javascript
-buildSchema.table({
-  dataSetModelMap: {
-    table: buildDataSetEntry({
-      cubeCode: 'your_cube_code',
-      fieldDefinitionList: [
-        buildFieldDefinition({ alias: 'name', aliasName: '姓名', isDim: true, dataType: 'STRING' }),
-        buildFieldDefinition({ alias: 'dept', aliasName: '部门', isDim: true, dataType: 'STRING' }),
-        buildFieldDefinition({ alias: 'sales', aliasName: '销售额', isDim: false, dataType: 'NUMBER', aggregateType: 'SUM' }),
-      ],
-      fieldList: ['name', 'dept', 'sales'],
-      orderByList: [buildOrderByItem('sales', 'DESC')],
-    })
-  },
-  settings: {
-    fixedHeader: true,
-    theme: 'border',
-    maxBodyHeight: 500,
-    pagination: {
-      pageSize: 20,
-      showPageSelect: true,
-      pageSizeList: [10, 20, 50, 100],
-    }
-  }
-})
-```
-
-#### 筛选器（下拉 + 时间 + 区间）
-
-```javascript
-// 下拉筛选器
-buildSchema.selectFilter({
-  dataSetModelMap: {
-    selectFilter: buildDataSetEntry({
-      cubeCode: 'your_cube_code',
-      cubeCodes: ['your_cube_code'],
-      fieldDefinitionList: [
-        buildFieldDefinition({ alias: 'dept_id', aliasName: '部门ID', isDim: true, dataType: 'STRING' }),
-        buildFieldDefinition({ alias: 'dept_name', aliasName: '部门名称', isDim: true, dataType: 'STRING' }),
-      ],
-      fieldList: ['dept_id', 'dept_name'],
-      valueField: ['dept_id'],
-      labelField: ['dept_name'],
-    })
-  },
-  settings: { labelConfig: { label: '部门' }, mode: 'multiple', showLabel: true }
-})
-
-// 时间筛选器
-buildSchema.timeFilter({
-  dataSetModelMap: {
-    filterData: buildDataSetEntry({
-      cubeCode: 'your_cube_code',
-      cubeCodes: ['your_cube_code'],
-      fieldDefinitionList: [
-        buildFieldDefinition({ alias: 'create_date', aliasName: '创建日期', isDim: true, dataType: 'DATE', timeGranularityType: 'DAY' }),
-      ],
-      fieldList: ['create_date'],
-      valueField: ['create_date'],
-    })
-  },
-  settings: { labelConfig: { label: '日期范围' }, mode: 'range', dataConfig: { queryType: 'Between' } }
-})
-```
-
-### 完整报表页面 Schema 构建示例
-
-以下示例展示如何组合多个组件构建一个完整的报表页面：
-
-```javascript
-const {
-  buildSchema, buildDataSetEntry, buildFieldDefinition, buildOrderByItem,
-} = require('./build-yida-report-schema');
-
-const CUBE_CODE = 'your_cube_code_here';
-
-const reportPageSchema = buildSchema.pageHeader({
-  titleContent: '销售数据看板',
-  titleTip: '数据每日 08:00 更新',
-  children: [
-    buildSchema.topFilterContainer({
-      showTag: true,
-      children: [
-        buildSchema.timeFilter({ /* 时间筛选器配置 */ }),
-        buildSchema.selectFilter({ /* 下拉筛选器配置 */ }),
-      ],
-    }),
-    buildSchema.simpleIndicatorCard({ /* 指标卡配置 */ }),
-    buildSchema.lineChart({ /* 折线图配置 */ }),
-    buildSchema.table({ /* 明细表格配置 */ }),
-  ],
-});
-
-console.log(JSON.stringify(reportPageSchema, null, 2));
-```
+### Schema 构建细节参考
 
-### 通用 settings 配置参考
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `titleConfig.label` | `string` | 组件标题 |
-| `height` | `number` | 组件高度（默认 300） |
-| `colorType` | `string` | 颜色类型，`default` 或 `CUSTOM_COLOR` |
-| `customColor` | `string` | 自定义颜色，逗号分隔 |
-| `drillDown` | `boolean` | 是否开启下钻（默认 false） |
-| `limit` | `number` | 数据条数限制（默认 1000） |
-
-### 各图表组件特有配置
-
-| 组件 | 特有配置 | 说明 |
-|------|---------|------|
-| **折线图** | `smooth`, `isStack`, `isPercent` | 平滑曲线、堆叠、百分比堆叠 |
-| **饼图** | `innerRadius` | 内半径（>0 为环形图） |
-| **条形图** | `isStack`, `isPercent` | 堆叠、百分比堆叠 |
-| **仪表盘** | `min`, `max`, `range` | 最小值、最大值、区间配置 |
-| **基础表格** | `fixedHeader`, `theme`, `pagination` | 固定表头、风格、分页 |
+普通报表创建优先使用 `openyida create-report <appType> "<报表名称>" <配置JSON文件路径>`，由 CLI 内部构建并发布 Schema。需要查看构建函数、组件示例、settings 字段或完整页面组合示例时，再读取 [references/schema-builder-details.md](references/schema-builder-details.md)。
 
 ---
 

package/yida-skills/skills/yida-report/references/schema-builder-details.md

@@ -0,0 +1,239 @@
+# 报表 Schema 构建细节
+
+> 从 yida-report 主技能迁出。只有需要理解底层 schema 结构、组件示例或 settings 字段时读取；普通创建报表优先使用 `openyida create-report` 的结构化配置。
+
+### 核心工具函数
+
+Schema 构建脚本提供以下核心函数，使用前需先引入：
+
+```javascript
+const {
+  buildSchema,           // 各组件 Schema 构建器
+  buildDataSetEntry,     // 构建数据集配置
+  buildFieldDefinition,  // 构建字段定义
+  buildFilterItem,       // 构建过滤条件
+  buildOrderByItem,      // 构建排序项
+  generateComponentId,   // 生成唯一组件 ID
+} = require('./build-yida-report-schema');
+```
+
+### 数据集配置（dataSetModelMap）
+
+所有报表组件通过 `dataSetModelMap` 配置数据源，每个数据集由 `buildDataSetEntry` 构建：
+
+```javascript
+buildDataSetEntry({
+  cubeCode: 'your_cube_code',        // 数据集 cubeCode（必填）
+  fieldDefinitionList: [              // 字段定义列表
+    buildFieldDefinition({
+      alias: 'date',                  // 字段别名（fieldKey）
+      aliasName: '日期',              // 字段显示名称
+      isDim: true,                    // true=维度，false=度量
+      dataType: 'DATE',              // STRING | NUMBER | DATE | BOOLEAN | ARRAY
+      aggregateType: 'NONE',         // NONE | SUM | AVG | COUNT | MAX | MIN | COUNT_DISTINCT
+      timeGranularityType: 'DAY',    // YEAR | QUARTER | MONTH | WEEK | DAY | HOUR | MINUTE | null
+    }),
+    buildFieldDefinition({
+      alias: 'sales',
+      aliasName: '销售额',
+      isDim: false,
+      dataType: 'NUMBER',
+      aggregateType: 'SUM',
+    }),
+  ],
+  fieldList: ['date', 'sales'],       // 查询字段别名列表
+  filterList: [],                     // 过滤条件列表
+  orderByList: [                      // 排序列表
+    buildOrderByItem('date', 'ASC'),  // ASC | DESC
+  ],
+  limit: 1000,                        // 数据条数限制
+  // 以下为筛选器专用参数
+  cubeCodes: ['your_cube_code'],      // cubeCode 数组（筛选器使用）
+  valueField: ['field_alias'],        // 值字段数组（筛选器使用）
+  labelField: ['field_alias'],        // 显示字段数组（筛选器使用）
+})
+```
+
+### 常用组件 Schema 构建示例
+
+#### 指标卡
+
+```javascript
+buildSchema.simpleIndicatorCard({
+  dataSetModelMap: {
+    kpi_dataset: buildDataSetEntry({
+      cubeCode: 'your_cube_code',
+      fieldDefinitionList: [
+        buildFieldDefinition({ alias: 'total_sales', aliasName: '总销售额', isDim: false, dataType: 'NUMBER', aggregateType: 'SUM' }),
+        buildFieldDefinition({ alias: 'order_count', aliasName: '订单数', isDim: false, dataType: 'NUMBER', aggregateType: 'COUNT' }),
+      ],
+      fieldList: ['total_sales', 'order_count'],
+    })
+  },
+  settings: { columnCount: 4, columnCountForH5: 2 }
+})
+```
+
+#### 折线图
+
+```javascript
+buildSchema.lineChart({
+  dataSetModelMap: {
+    line_dataset: buildDataSetEntry({
+      cubeCode: 'your_cube_code',
+      fieldDefinitionList: [
+        buildFieldDefinition({ alias: 'date', aliasName: '日期', isDim: true, dataType: 'DATE', timeGranularityType: 'DAY' }),
+        buildFieldDefinition({ alias: 'sales', aliasName: '销售额', isDim: false, dataType: 'NUMBER', aggregateType: 'SUM' }),
+      ],
+      fieldList: ['date', 'sales'],
+      orderByList: [buildOrderByItem('date', 'ASC')],
+    })
+  },
+  settings: {
+    titleConfig: { label: '销售趋势' },
+    height: 400,
+    smooth: true,
+    drillDown: false,
+  }
+})
+```
+
+#### 饼图（环形图）
+
+```javascript
+buildSchema.pieChart({
+  dataSetModelMap: {
+    pie_dataset: buildDataSetEntry({
+      cubeCode: 'your_cube_code',
+      fieldDefinitionList: [
+        buildFieldDefinition({ alias: 'category', aliasName: '类别', isDim: true, dataType: 'STRING' }),
+        buildFieldDefinition({ alias: 'amount', aliasName: '金额', isDim: false, dataType: 'NUMBER', aggregateType: 'SUM' }),
+      ],
+      fieldList: ['category', 'amount'],
+    })
+  },
+  settings: {
+    titleConfig: { label: '销售占比' },
+    innerRadius: 0.6,  // >0 为环形图
+  }
+})
+```
+
+#### 基础表格（明细表）
+
+```javascript
+buildSchema.table({
+  dataSetModelMap: {
+    table: buildDataSetEntry({
+      cubeCode: 'your_cube_code',
+      fieldDefinitionList: [
+        buildFieldDefinition({ alias: 'name', aliasName: '姓名', isDim: true, dataType: 'STRING' }),
+        buildFieldDefinition({ alias: 'dept', aliasName: '部门', isDim: true, dataType: 'STRING' }),
+        buildFieldDefinition({ alias: 'sales', aliasName: '销售额', isDim: false, dataType: 'NUMBER', aggregateType: 'SUM' }),
+      ],
+      fieldList: ['name', 'dept', 'sales'],
+      orderByList: [buildOrderByItem('sales', 'DESC')],
+    })
+  },
+  settings: {
+    fixedHeader: true,
+    theme: 'border',
+    maxBodyHeight: 500,
+    pagination: {
+      pageSize: 20,
+      showPageSelect: true,
+      pageSizeList: [10, 20, 50, 100],
+    }
+  }
+})
+```
+
+#### 筛选器（下拉 + 时间 + 区间）
+
+```javascript
+// 下拉筛选器
+buildSchema.selectFilter({
+  dataSetModelMap: {
+    selectFilter: buildDataSetEntry({
+      cubeCode: 'your_cube_code',
+      cubeCodes: ['your_cube_code'],
+      fieldDefinitionList: [
+        buildFieldDefinition({ alias: 'dept_id', aliasName: '部门ID', isDim: true, dataType: 'STRING' }),
+        buildFieldDefinition({ alias: 'dept_name', aliasName: '部门名称', isDim: true, dataType: 'STRING' }),
+      ],
+      fieldList: ['dept_id', 'dept_name'],
+      valueField: ['dept_id'],
+      labelField: ['dept_name'],
+    })
+  },
+  settings: { labelConfig: { label: '部门' }, mode: 'multiple', showLabel: true }
+})
+
+// 时间筛选器
+buildSchema.timeFilter({
+  dataSetModelMap: {
+    filterData: buildDataSetEntry({
+      cubeCode: 'your_cube_code',
+      cubeCodes: ['your_cube_code'],
+      fieldDefinitionList: [
+        buildFieldDefinition({ alias: 'create_date', aliasName: '创建日期', isDim: true, dataType: 'DATE', timeGranularityType: 'DAY' }),
+      ],
+      fieldList: ['create_date'],
+      valueField: ['create_date'],
+    })
+  },
+  settings: { labelConfig: { label: '日期范围' }, mode: 'range', dataConfig: { queryType: 'Between' } }
+})
+```
+
+### 完整报表页面 Schema 构建示例
+
+以下示例展示如何组合多个组件构建一个完整的报表页面：
+
+```javascript
+const {
+  buildSchema, buildDataSetEntry, buildFieldDefinition, buildOrderByItem,
+} = require('./build-yida-report-schema');
+
+const CUBE_CODE = 'your_cube_code_here';
+
+const reportPageSchema = buildSchema.pageHeader({
+  titleContent: '销售数据看板',
+  titleTip: '数据每日 08:00 更新',
+  children: [
+    buildSchema.topFilterContainer({
+      showTag: true,
+      children: [
+        buildSchema.timeFilter({ /* 时间筛选器配置 */ }),
+        buildSchema.selectFilter({ /* 下拉筛选器配置 */ }),
+      ],
+    }),
+    buildSchema.simpleIndicatorCard({ /* 指标卡配置 */ }),
+    buildSchema.lineChart({ /* 折线图配置 */ }),
+    buildSchema.table({ /* 明细表格配置 */ }),
+  ],
+});
+
+console.log(JSON.stringify(reportPageSchema, null, 2));
+```
+
+### 通用 settings 配置参考
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `titleConfig.label` | `string` | 组件标题 |
+| `height` | `number` | 组件高度（默认 300） |
+| `colorType` | `string` | 颜色类型，`default` 或 `CUSTOM_COLOR` |
+| `customColor` | `string` | 自定义颜色，逗号分隔 |
+| `drillDown` | `boolean` | 是否开启下钻（默认 false） |
+| `limit` | `number` | 数据条数限制（默认 1000） |
+
+### 各图表组件特有配置
+
+| 组件 | 特有配置 | 说明 |
+|------|---------|------|
+| **折线图** | `smooth`, `isStack`, `isPercent` | 平滑曲线、堆叠、百分比堆叠 |
+| **饼图** | `innerRadius` | 内半径（>0 为环形图） |
+| **条形图** | `isStack`, `isPercent` | 堆叠、百分比堆叠 |
+| **仪表盘** | `min`, `max`, `range` | 最小值、最大值、区间配置 |
+| **基础表格** | `fixedHeader`, `theme`, `pagination` | 固定表头、风格、分页 |