@finebi/finebi-cli 1.4.0 → 1.6.0

package/skills/finebi-cli-agent/references/dashboard-dsl-api.md

@@ -23,8 +23,10 @@
 `remove-entry`（被控件圈定或联动的条目删除会被拒，按错误信息先改引用）。`add-entry`
 的 fragment 无切片可抄、需手写：单条目语句（上文各条目语句形态之一）+ 可选
 `position` 行，不包 `DashboardDsl.create` 整板脚本；缺省 position 落首个空位。
-并发编辑带 `--expected-update-time`（上次写响应的 `lastUpdateTime`），不匹配会报
-`VERSION_CONFLICT`，重读后重试。
+并发编辑（含用户在设计器手改后再让 Agent 续改）带 `--expected-update-time`——基准取
+读板响应（`info` / `dsl` 的 `lastUpdateTime`）或上次写响应的新值，不匹配会报
+`VERSION_CONFLICT`（附当前值），重读后重试。entryId 按条目名稳定：设计器保存与整板
+`update` 下同名条目沿用原值，新增条目的新值从 update 响应 `entries[]` 直接可得。
 
 **写新看板前先取场景样例**：`dashboard template`（默认场景）返回场景目录与通用设计要点，
 `dashboard template --scenario <id>` 取某一个场景的完整可抄脚本 + `guidance` 设计要点
@@ -32,1006 +34,11 @@
 `screen` 大屏驾驶舱 / `rich-text` 富文本与动态字段 / `linkage-jump` 联动与跳转 /
 `tree-time` 层级与时间筛选 / `blocks` 容器区块）。
 动态合法值（样式预设 id 与全局样式名）
-用 `dashboard style-presets` 查，语句面速查用 `dashboard schema`。本文件是逐条 API 参考。
-
-## 1. 根入口
-
-嵌入的数据图表沿用 [Widget DSL API §4.7.2](widget-dsl-api.md#472-值轴与双-y-轴) 的
-`.valueAxis(measureRef, ValueAxis.builder()...build())`，无需 Dashboard 专属双轴开关。
-`dashboard dsl` 可回读支持的值轴设置；替换更新应保留导出的完整组件 DSL，
-遇到不能表达的有效轴公式或样式时先处理明确报错，不删除设置后强行更新。
-
-```js
-DashboardDsl.create("仪表板名")
-```
-
-业务含义：
-
-- 新建一个仪表板 Builder。
-- 仪表板负责组织组件、控件、文本、布局、样式和移动端配置。
-
-## 2. 顶层 Builder
-
-| DSL API           | 业务含义                        |
-|-------------------|-----------------------------|
-| `.content()`      | 进入内容域，定义仪表板上有哪些条目。          |
-| `.presentation()` | 进入布局与样式域，定义条目如何摆放、整板采用什么风格。 |
-| `.mobile()`       | 进入移动端域，定义移动端展示顺序。           |
-| `.build()`        | 结束编排，生成 `ReportModel`。      |
-
-## 3. 内容域
-
-### 3.1 条目挂载
-
-| DSL API                   | 业务含义                  |
-|---------------------------|-----------------------|
-| `.reference("已有组件名")`     | 引用已有数据组件，不在当前脚本内重新定义。 |
-| `.control(controlItem)`   | 挂载一个筛选控件。             |
-| `.text(textItem)`         | 挂载一个文本组件。             |
-| `.image(imageItem)`       | 挂载一个图片组件。             |
-| `.web(webItem)`           | 挂载一个 Web 组件（内嵌 iframe 打开外部地址）。 |
-| `.generalQuery(generalQueryItem)` | 挂载一个复合过滤组件：用 `.where(...)` / `.orGroup(...)` 声明初始过滤条件（省略 = 空骨架，查看者在查看态自行增删条件、且或组合并触发查询）（见 §6.13）。 |
-| `.aiDiagnosis(aiDiagnosisItem)` | 挂载一个 AI 诊断组件：对选中组件做 AI 诊断/产出分析（见 §6.14）。 |
-| `.combine(combineItem)`   | 挂载一个组件组合（区块容器）：成员为已声明的非容器条目名（至少 2 个），成员布局移入组合内容区（见 §6.10）。 |
-| `.tab(tabItem)`           | 挂载一个 Tab 组件：多页签切换展示，每页持成员（见 §6.11）。 |
-| `.freeze(freezeItem)`     | 挂载一个过滤组件冻结栏：成员为控件与复合过滤组件，查看态钉在页面上方（见 §6.12）。 |
-| `.title("组件名", "标题")`     | 给已声明的数据组件设置显示标题；第二参数也可传 `RichText.of()...build()`（富文本标题，含动态字段值，见 §8.3）。 |
-| `.showTitle("组件名", true)` | 设置已声明的数据组件是否显示标题。     |
-
-容器公共口径（三件套同构）：
-
-- 成员是**同板已声明的条目名**，可在容器声明之后才声明；一个条目至多加入一个容器；成员不得再 `position` 到顶层（其布局在容器内局部 72×36 网格）。
-- 容器自身占一个画布位：不 `position` 时默认尺寸 组合 72×24 / Tab 72×16 / 冻结栏 72×8，与其他条目一起自动排；组合与 Tab 可悬浮（`float` 作用于容器名），**冻结栏自身不可悬浮**（设计器工具栏无该入口）。
-- **组合容器浮 = 成员全浮**：`float(组合名)` 时**全部成员都须 `float`**（否则 fail-loud）。设计器按「成员全悬浮 → 容器悬浮」派生（帮助文档 §4），因此容器不浮而部分成员悬浮是合法的（对应设计器的「部分悬浮组合」形态）。
-- 组合/Tab 页成员可悬浮（`float(成员名)`，须显式 `place`）；冻结栏成员不可悬浮。组合不可嵌任何容器；Tab 页可含组合与冻结栏（冻结栏每页至多 1 个）；Tab 不可嵌 Tab。
-
-### 3.2 联动与跳转
-
-| DSL API                                     | 业务含义                       |
-|---------------------------------------------|----------------------------|
-| `.linkage("源组件名", linkage1, linkage2, ...)` | 给已声明的数据组件追加主动联动配置（显式字段对，查看态按声明字段过滤；被联动组件上的反向条目自动派生）。 |
-| `.linkageEffect("源组件名", click, "目标1", "目标2", ...)` | 声明一条持久化联动效果（设计器里点击组件联动后的自动保存产物，打开仪表板即生效）。 |
-| `.jump("源组件名", jump1, jump2, ...)`          | 给已声明的数据组件追加跳转配置。           |
-| `.cancelDefaultLinkage()`                   | 关闭仪表板默认联动，只保留显式声明的联动规则。    |
-
-业务补充：
-
-- `linkage` 和 `jump` 都按组件业务名工作；多次调用是累加关系。
-- 联动目标必须是同板已声明的数据组件或文本组件（控件、图片不可被联动）；不声明联动 = 平台天然联动（同表/关联表/同指标集自动配对）。
-- `LinkageModel.of(源字段, "目标组件名", 目标字段)` 声明显式字段对；`LinkageModel.disable("目标组件名")` 对单个目标显式关闭联动（含天然联动）。
-- `linkageEffect` 与 `linkage` 正交：`linkage` 描述「怎么联动」（配置），`linkageEffect` 描述「当前联动已发生」（持久化点击态）。点击坐标 `LinkageEffect.click(点击轴字段)` + `.cell(维度字段, "显示值")` 维度坐标 / `.summaryCell("合计")` 合计行坐标 / `.metricNameCell("指标名")` 指标名称坐标（源组件须声明指标名称维度）。同一源至多一条；目标集可为空（点击时源无可联动目标）；每条效果独立一跳、**不传递**（A 联动 B、B 联动 C 时点击 A 不会传导到 C——前端运行态限制）；明细表不可发起（同 `linkage`）。
-- 跳转名称（`.name(...)`）同一组件内不可重复；未命名的跳转用平台默认名（分析模板/网页链接），可多条。
-- 跳转目标仪表板可跨主题：目标板按名称解析（同主题同名板优先，未命中查全局）；目标字段的 fieldId 属于目标板用到的表，跨主题前先 `dashboard tables --id <目标板id>` 查候选字段名。
-- `title` 和 `showTitle` 只作用于数据组件，不作用于控件、文本和图片组件。
-
-## 4. 布局与样式域
-
-### 4.1 布局与自适应
-
-```js
-AdaptiveModel.flowLayout()
-AdaptiveModel.origin(width, height)
-```
-
-| DSL API                                   | 业务含义                  |
-|-------------------------------------------|-----------------------|
-| `.adaptive(AdaptiveModel.flowLayout())`   | 自动适应：仅重排布局，不整体缩放（省略语句 = 自动适应 + 整体缩放，即设计器默认）。 |
-| `.adaptive(AdaptiveModel.origin(w, h))`   | 固定基准尺寸：保持原始尺寸不缩放。 |
-| `.adaptive(AdaptiveModel.fitWidth(w, h))` | 固定基准尺寸：按宽度铺满等比缩放。 |
-| `.adaptive(AdaptiveModel.fitHeight(w, h))`| 固定基准尺寸：按高度铺满等比缩放。 |
-| `.adaptive(AdaptiveModel.fitAuto(w, h))`  | 固定基准尺寸：按屏幕自适应铺满（宽高取小）。 |
-| `.position(name, col, row, wCols, hRows)` | 按 72 列网格给条目设置位置和占位大小。 |
-
-参数语义（adaptive）：
-
-- `w` / `h`：基准尺寸，取值 100~10000（整数，超界 fail-loud）
-
-参数语义（position）：
-
-- `name`：已声明条目的业务名
-- `col`：起始列
-- `row`：起始行
-- `wCols`：占用列数
-- `hRows`：占用行数
-
-业务规则：
-
-- 仪表板宽度固定为 72 列。
-- `col + wCols` 不能超过 72。
-- `row` 与 `hRows` 不做画布行上限硬校验（支持纵向延展，超出一屏时可滚动查看）。
-- 没有显式 `position(...)` 的条目会按默认尺寸自动排版；显式和 auto 条目统一经全量压实（对齐前端查看态）；**悬浮条目例外**（原样落位不压实）。
-
-### 4.2 悬浮与图层
-
-```js
-.float(name)
-```
-
-| DSL API | 业务含义 |
-|-------------------------------------------|-----------------------|
-| `.float(name)` | 声明条目悬浮：允许重叠、不参与压实，悬浮恒压网格条目。 |
-
-参数语义：
-
-- `name`：已声明条目的业务名；多次调用累加
-- **声明序即图层顺序**：后 `.float(...)` 声明的条目在上（置顶 = 调整声明序）
-- 悬浮条目必须同时有显式 `.position(...)`（自由层无自动排布，缺省 fail-loud）
-- 同名重复悬浮 fail-loud
-
-### 4.3 模板样式
-
-| DSL API                        | 业务含义                      |
-|--------------------------------|---------------------------|
-| `.stylePreset("DEFAULT_DARK")` | 使用平台内置的整板样式预设，按预设 id 选择。  |
-| `.customStyle("我的样式")`         | 使用管理员保存的全局自定义样式，按样式显示名选择。 |
-| `.templateStyle(TemplateStyle.of()....build())` | 在基底上分区微调样式（可与上面任一组合：基底 + 逐项覆盖）。 |
-
-业务补充：
-
-- `stylePreset` 适合快速套用平台标准主题。
-- `customStyle` 适合复用团队已有的大屏或看板风格。
-- `templateStyle` 全部可选、省略 = 基底值/平台默认；只声明要改的项。
-
-微调方法速查（按面板 6 分区）：
-
-| 分区 | 方法 | 值域 |
-|---|---|---|
-| 仪表板 | `widgetGap(gap)` / `background(color)` / `background(TemplateBackground)` | gap 偶数 0~20；颜色 `#RGB`/`#RRGGBB`/`transparent` |
-| 组件 | `widgetBackground(color)` 或 `widgetBackground(color, radius, borderSize, borderColor)` 或 `widgetBackground(TemplateBackground)` / `hoverShadow(bool)` / `titleBackground(color\|TemplateBackground)` / `titleFont(font)` | 圆角 0~6、边框 0~5 |
-| 图表 | `chartColor([colors])` / `clearChartColor()` / `chartFont(font)` | 色板非空；`clearChartColor()` = 面板「自动」回退平台配色；图表字体无对齐 |
-| 表格 | `tableStyle(TemplateStyle.PLAIN\|BLUE_HEADER\|INTERVAL)` / `tableThemeColor(color)` / `tableFont(font)` / `scrollbar(TemplateStyle.STATIC\|DYNAMIC)` | |
-| 过滤组件 | `controlTheme(color)` / `controlTitleFont(font)` / `controlTitleBackground(color\|TemplateBackground)` / `controlBackground(color[...]\|TemplateBackground)` | 此分区背景无样式皮肤入口 |
-| 图片组件 | `imageBackground(color[...]\|TemplateBackground)` | |
-
-背景值对象（6 个背景槽位通用，镜像设计器背景面板的颜色/图片/组件样式三选一）：
-
-```js
-TemplateBackground.color("#13141f")                          // 纯色（等价于 background("#13141f") 便捷形态）
-TemplateBackground.color("#1a1a2e", 4, 1, "#5a80ff")        // 纯色 + 圆角 0~6 / 边框 0~5 / 边框色
-TemplateBackground.image("image1788431093821_aft0uG6q_png")  // 上传图片（attach id，先跑 dashboard upload-image）
-TemplateBackground.style(TemplateBackground.STYLE2)          // 预置装饰皮肤 STYLE1..STYLE6
-```
-
-- 图片 `attachId` 必须来自 `dashboard upload-image`（或 `data:image...`、`resources?path=`）；绝对 URL 渲染不出，构造期报错。
-- 样式皮肤仅组件背景（`STYLE1/2/3/5/6`）、标题背景（`STYLE1..STYLE6`）、图片组件背景（`STYLE1/2/3/5/6`）可用；模板背景与过滤组件分区无此入口。
-- 边框三件只在组件 / 过滤组件 / 图片组件背景三个分区设置；图片与皮肤形态不消费颜色与边框。
-
-字体值（`FontModel.of().family(...).size(...).bold(bool).italic(bool).underline(bool).color(...).align(FontModel.LEFT|CENTER|RIGHT).build()`；`FontModel.auto()` 把槽位重置回自动）：
-
-- `size` 必须是设计器字号选项之一：12~40（步进见面板）、64、128。
-- 表格字体 `TableFont.of().header(FontModel).body(TableBodyFont.of()....dimAlign(...).tarAlign(...).build()).build()`（表头单对齐、表身维度/指标双对齐）；`TableFont.auto()` 整体重置（表头/表身共用一个开关）。
-
-## 5. 移动端域
-
-| DSL API                                               | 业务含义         |
-|-------------------------------------------------------|--------------|
-| `.mobileConfig(MobileConfigModel.defaults())`         | 使用默认移动端配置。   |
-| `.mobileConfig(MobileConfigModel.of(["组件A", "组件B"]))` | 显式指定移动端组件顺序。 |
-
-默认配置语义：
-
-- `controlShowType = 1`
-- `fitGap = 10`
-- `autoSequence = true`
-
-## 6. 可构造值对象
-
-### 6.1 ControlItem
-
-入口：
-
-```js
-ControlItem.builder("区域筛选", ControlItem.TEXT)
-```
-
-可用方法：
-
-| DSL API                               | 业务含义                      |
-|---------------------------------------|---------------------------|
-| `.bindField(fieldRef)`                | 绑定一个筛选字段。fieldRef 三种形态：物理字段 `from("表").dim("字段")`、主题内已保存计算字段 `measureID("配置 ID").dim()`、业务模型字段 `model("模型").dataset("数据集").dim("字段")`。**字段类型须与控件族匹配**（与设计器字段面板一致）：文本/树类控件只收字符串字段、数值类只收数值字段、日期类（含时间按钮组）只收日期字段——数值字段拖不进文本或树控件，写错了保存前即报错。 |
-| `.bindFields([fieldRef1, fieldRef2])` | 一次绑定多个筛选字段（形态同上）。树族三型下**声明序即层级顺序**（第一个字段为根层级）。 |
-| `.defaultValue(["默认值1", "默认值2"])`     | 设置默认选中值。树族三型下只支持**单层级**树（多层级树保存报错——平台每层存一份选中值）。 |
-| 值列表书写约定（`defaultValue` / `customValues` / `allowInterval` / `controlRange`） | 元素一律写**字符串字面量**——数值/日期也带引号（如 `["0", "1000000"]`）。控件值的持久化契约就是字符串（真机 JSON 里数值下拉的 value/customValue 均为字符串）；写裸数值字面量会在构造期报错（`must contain strings only`）。 |
-| `.closeRange(true, false)`             | 默认值区间边界含否（先声明 `defaultValue`）。**省略 = 前端编辑器默认骨架：左闭右开**（min ≤ 值 < max），只声明偏离默认的组合：`(true, true)` 全闭 [min, max]、`(false, false)` 双开、`(false, true)` 左开右闭。仅 NUMBER_RANGE/NUMBER_RANGE_SLIDER 可用；查看态回显闭边界为 ≤、开边界为 <。 |
-| `.controlRange(["组件A", "组件B"])`       | 指定控件影响的组件范围（正选）；空范围（默认）为反选全范围——声明作用于全部组件，实际过滤仅对存在数据关联的组件生效（同表/关联表或使用控件字段，含其他控件）。只能圈定数据组件/文本/选项类控件（TEXT/TEXT_LIST/TEXT_BUTTON_GROUP/NUMBER）与树族三型；**图片、Web、容器（组合/Tab/冻结栏）、按钮、日期时间与数值区间/滑块类控件不可被圈定**（保存时直接报错——容器要逐个圈定其成员）。 |
-| `.title("标题")`                        | 设置控件标题。                   |
-| `.showTitle(true)`                    | 设置是否显示控件标题。               |
-| `.multiSelect(true/false)`            | 多选开关。仅 TEXT/TEXT_LIST/TEXT_BUTTON_GROUP/NUMBER 可用（其余类型声明 `true` 报错）。**省略 = 平台骨架：多选**（真机 JSON `singleSelect:1`），单选写 `.multiSelect(false)`。 |
-| `.sort("asc")`                        | 候选按绑定字段自身升序（省略默认即此形态）。仅 TEXT/TEXT_LIST/TEXT_BUTTON_GROUP 与树族三型（TREE/TREE_LIST/TREE_LABEL）可用；与 `customValues` 互斥。 |
-| `.sort("desc")`                       | 候选按绑定字段自身降序。同上类型门禁与互斥。      |
-| `.sortByField(fieldRef, "desc")`      | 候选按另一字段排序（可跨关联表，如按"薪资"排"爱好"候选）。方向 `"asc"/"desc"` 必填；覆盖 `sort`；同上类型门禁与互斥；fieldRef 形态与 `bindField` 相同（物理/计算字段/模型字段）。 |
-| `.where(fieldRef, "in", ["值1", "值2"])` | **绑定字段过滤**：过滤本控件的**候选取数**（如只让"地区"下拉列出华东/华南），不是过滤数据组件的出数——那是控件值生效后的天然结果。fieldRef 必须是本控件已 `bindField` 的字段之一（否则构造期报错）；可多次声明（AND 叠加）。算子 `"eq"/"in"/"between"/"not_null"`（按被过滤字段类型：数值 eq/between/not_null、文本 eq/in/not_null、日期 eq/between/not_null）。仅 TEXT/TEXT_LIST/TEXT_BUTTON_GROUP 与树族三型可用（日期与数值区间类控件无此入口）。 |
-| `.defaultValueOrigin(ControlItem.X)`  | 初始默认值：`CURRENT` 当前值（默认）/ `FIRST_OR_MIN` 第一项文本·最小项数值·最早时间 / `LAST_OR_MAX` 最后一项·最大项·最晚时间。仅 TEXT/TEXT_LIST/TEXT_BUTTON_GROUP/NUMBER 与 DATE/DATE_PANE/YEAR/MONTH/QUARTER 可用，区间类控件报错。 |
-| `.allowPassDefault(true)`             | 登录名传递默认值（用当前登录用户的用户名作默认选中值）。仅 TEXT/TEXT_LIST/TEXT_BUTTON_GROUP 与树族三型可用；与选中值互斥——`defaultValue` / `selectedPaths` / `selectedLevels` 不可与登录名传递同时声明（查看态传递会覆盖选中值）。 |
-| `.showTime(true)`                     | 日期控件显示时间（默认不显示）。仅 DATE/DATE_PANE/DATE_INTERVAL 可用。 |
-| `.monoWidthDisplay(false)`            | 关闭按钮组等宽显示（默认 true 等宽）。仅 TEXT_BUTTON_GROUP 与 TIME_GROUP 可用。 |
-| `.timeTags(timeTag...)`               | 时间按钮组的标签集（声明序即按钮展示顺序）。仅 TIME_GROUP 可用。**省略 = 平台 6 档预置标签全展示**（当天/本周/本月/本季度/最近7天/最近30天）；声明后只展示声明的标签。标签来自 `TimeTag` 工厂（见下），最多一个可标 `.selected()` 作默认选中项。 |
-| `.required(true)`                     | 设为必填项（默认非必填）。数值区间/区间滑块与按钮类不可用。 |
-| `.filterLevel(ControlItem.FIRST/SECOND)` | **控件过滤层级**：本控件自身的过滤条件落在过滤顺序的哪一档——`FIRST` 前置过滤（原始数据表层，在所有组件计算之前）/ `SECOND` 明细过滤（明细行层）；越靠前影响的下游计算越多。过滤层级共四档，**控件只占前两档**（后两档「聚合计算过滤/快速计算过滤」属组件过滤条件，走 widget DSL 的 `level(FilterLevel.THIRD/FOURTH)`）。**仅标准分析主题可用**（自助主题声明直接报错，前端该菜单也只对标准主题开放）；按钮类不可用。**省略 = 平台默认**：标准主题落「明细过滤」（设计器新控件的骨架），自助主题由平台按维度自动算层级。仅在需要把控件改成「前置过滤」时才写（标准主题下 `SECOND` 与省略等价）。 |
-| `.customValues(["值1", "值2"])`        | 使用自定义值：候选不走绑定字段而用显式清单（非空）。仅 TEXT/TEXT_LIST/TEXT_BUTTON_GROUP/NUMBER 可用；与 `defaultValueOrigin` 互斥。 |
-| `.allowInterval(["2024-01-01", "2024-12-31"])` | 日期可选范围 [start, end]（限制用户可选的起止）。值格式随控件粒度：DATE/DATE_PANE/DATE_INTERVAL 用 `yyyy-MM-dd`、YEAR 用 `yyyy`、MONTH/YEAR_MONTH_RANGE 用 `yyyy-M`、QUARTER 用 `yyyy-Qn`。仅日期族七型可用；与 `defaultValue` 互斥。注意：前端打开日历/年月时仍定位当前时间，区间外的视野全部禁用，需翻到区间内才能选——这是正常行为不是缺陷。 |
-| `.dynamicDefault(DynamicDate.X)`     | 动态日期默认值（相对"现在"的表达式，如"近 30 天""上季度初"，查看态按打开时刻求值）。仅 DATE/DATE_PANE/YEAR/MONTH/QUARTER 五型可用；与 `defaultValue`、`allowInterval` 互斥。值来自 `DynamicDate` 工厂（见下）。 |
-| `.selectedPaths([["购买合同", "一次性付款"], ["服务协议"]])` | 下拉树/列表树的**多层级**选中路径：内层 = 一条路径（按层级顺序，可短于层数 = 该层以下不限）。仅 TREE/TREE_LIST；与 `defaultValue` 互斥；须先 `bindField`（绑定字段即层级）；路径不得互为祖先-后代（父路径已含其下全部，声明父路径即可）。 |
-| `.selectedLevels([[], ["一次性付款"]])` | 树标签的**按层**选中值：外层下标 = 层级，空层/缺层 = 该层不限。仅 TREE_LABEL；与 `defaultValue` 互斥；须先 `bindField`（绑定字段即层级）。 |
-| `.bindSqlParameter("参数名", ...)`       | **绑定 SQL 参数**：控件把选中值送进数据集 SQL 的 `${参数名}` 占位符。参数名取自该仪表板所属主题的数据集参数——先用 `finebi-cli dashboard sql-params --id <dashboardId>` 查候选；同名参数出现在两张表时直接报错（DSL 不猜表），需在数据集侧改名。单槽控件（TEXT/TEXT_LIST/TEXT_BUTTON_GROUP/NUMBER/YEAR/DATE/DATE_PANE）用它，可一次列多个或多次声明。**参数类型不限**（字符串/数值/日期参数都能绑，与设计器候选列表一致）；一个参数在整个仪表板内只能被一个控件绑定。 |
-| `.bindSqlParameter(SqlSlot.X, "参数名")` | 多槽控件的 SQL 参数绑定，槽位必填：`SqlSlot.YEAR`/`SqlSlot.MONTH`（MONTH、QUARTER——年与月/季两个页签）、`SqlSlot.START`/`SqlSlot.END`（DATE_INTERVAL、TIME_GROUP）、`SqlSlot.START_YEAR`/`SqlSlot.START_MONTH`/`SqlSlot.END_YEAR`/`SqlSlot.END_MONTH`（YEAR_MONTH_RANGE）。上述五型若用不带槽位的写法会报错；未绑的槽留空（设计器形态）。同一参数不能在一个控件里占两个槽/两个端。 |
-| `.bindWidgetParameter("组件参数名")`      | **绑定组件参数**（主题级参数，`finebi-cli widget-parameter info --subject-id <subjectId>` 查候选）：控件把该参数的值送进取数，整体绑定。参数类型须与控件家族匹配（文本类控件绑字符串参数、数值下拉绑数值参数、日期类控件绑日期参数），否则报错并列出主题可用候选；一个参数在整个仪表板内只能被一个控件绑定。 |
-| `.bindWidgetParameter("组件参数名", BindEnd.START/END)` | 区间控件分端绑定：`BindEnd.START` 绑开始端、`BindEnd.END` 绑结束端。仅 DATE_INTERVAL/YEAR_MONTH_RANGE/TIME_GROUP 可用（这些类型也可整体绑定）；同一参数只能占一个端。 |
-| `.actualField(fieldRef)`              | **实际值字段**：显示值与送进查询的值不同时用——选中候选按此字段的取值替换 `${参数}`（如下拉显示"华东"、查询用"HD"）。fieldRef 须与绑定字段**同表**；仅 TEXT/TEXT_LIST/TEXT_BUTTON_GROUP 且已声明 `bindSqlParameter` 后可用。 |
-| `.build()`                            | 生成 `ControlItem`。         |
-
-> **计算字段聚合约束**：`measureID(...)` 引用已保存计算字段作控件筛选字段时，只可绑**行级**
-> （`calculated-field` 命令输出 `aggregate=false`，公式不含 `SUM_AGG` 等聚合函数）。**聚合型**
-> （`aggregate=true`）按组产单值、没有逐行候选值，保存时直接报错（前端同规则：聚合候选不出现在
-> 控件字段面板）——聚合型计算字段只能作图表指标、富文本动态字段（`measureID(...).sum()`）或
-> `.sortByField` 排序目标（按指标排候选，合法）。
-
-`DynamicDate` 动态日期工厂（值对象传给 `.dynamicDefault(...)`；偏移在查看态相对"现在"求值，叠加顺序 年→季→月→周(×7天)→天）：
-
-| 调用 | 语义 |
-|---|---|
-| `DynamicDate.today()` | 今天 |
-| `DynamicDate.yesterday()` | 昨天 |
-| `DynamicDate.daysAgo(n)` | n 天前（n ≥ 0） |
-| `DynamicDate.beginOf(unit, n)` | 第 n 个（0=本周期，-1=上一周期）unit 的**初**：`DynamicDate.QUARTER` / `MONTH` / `YEAR` / `WEEK` 单位常量。如 `beginOf(DynamicDate.QUARTER, -1)` = 上季度初 |
-| `DynamicDate.endOf(unit, n)` | 同上但取**末**：`endOf(DynamicDate.MONTH, -1)` = 上月末 |
-| `DynamicDate.offset()...build()` | 组合偏移链：`.years(n).quarters(n).months(n).weeks(n).days(n)`，可加 `.atBegin()`/`.atEnd()` 吸附到最细声明单位的初/末（**天级偏移不可吸附**，前端参数卡无此形态）。如"去年今日"= `offset().years(-1).days(0).build()` |
-
-可用控件类型：
-
-- `ControlItem.TEXT`
-- `ControlItem.TEXT_LIST`
-- `ControlItem.TEXT_BUTTON_GROUP`
-- `ControlItem.NUMBER`
-- `ControlItem.NUMBER_RANGE`
-- `ControlItem.NUMBER_RANGE_SLIDER`
-- `ControlItem.DATE`
-- `ControlItem.DATE_INTERVAL`
-- `ControlItem.YEAR`
-- `ControlItem.MONTH`
-- `ControlItem.QUARTER`
-- `ControlItem.DATE_PANE`
-- `ControlItem.YEAR_MONTH_RANGE`
-- `ControlItem.TIME_GROUP`
-- `ControlItem.TREE`（下拉树）/ `ControlItem.TREE_LIST`（列表树）/ `ControlItem.TREE_LABEL`（树标签）
-- `ControlItem.QUERY`
-- `ControlItem.RESET`
-- `ControlItem.CLEAR`
-
-`TimeTag` 时间标签工厂（值对象传给 `.timeTags(...)`；标签显示名即按钮文案）：
-
-| 调用 | 语义 |
-|---|---|
-| `TimeTag.preset(TimeTag.CURRENT_DAY)` | 平台预置档位：`CURRENT_DAY`（当天）/ `CURRENT_WEEK`（本周）/ `CURRENT_MONTH`（本月）/ `CURRENT_QUARTER`（本季度）/ `LAST_SEVEN_DAYS`（最近7天）/ `LAST_THIRTY_DAYS`（最近30天）。区间与显示名由平台给定，查看态按打开时刻求值。 |
-| `TimeTag.of("上半年", "2024-01-01", "2024-06-30")` | 自定义标签：显示名 + 静态日期区间（`yyyy-MM-dd`）。同一控件内标签名不可重复。 |
-| `.selected()` | 标记该标签为默认选中项（同一控件至多一个）；不标记则查看态初始不过滤，点击标签才过滤——若要板子一打开就按某个区间过滤，必须写 `.selected()`。 |
-
-业务补充：
-
-- `ControlItem.TEXT`、`ControlItem.TEXT_LIST`、`ControlItem.TEXT_BUTTON_GROUP` 适合文本类筛选。
-- `ControlItem.NUMBER`、`ControlItem.NUMBER_RANGE`、`ControlItem.NUMBER_RANGE_SLIDER` 适合数值类筛选。
-- `ControlItem.DATE`、`ControlItem.DATE_INTERVAL`、`ControlItem.YEAR`、`ControlItem.MONTH`、`ControlItem.QUARTER`、
-  `ControlItem.DATE_PANE`、`ControlItem.YEAR_MONTH_RANGE` 适合时间类筛选。
-- 树族三型（`TREE`/`TREE_LIST`/`TREE_LABEL`）用于层级筛选：**绑定多个字段时，字段按声明序构成父子层级**
-  （第一个字段是根层级），如 `.bindField(from("地区表").dim("省份")).bindField(from("地区表").dim("城市"))`。
-  层级字段可以来自多张表，但表之间必须已建立关联（无关联时保存报错，与设计器一致）；
-  层级只有一层时用 `.defaultValue(["默认展开/选中值"])`，**多层级选中值另有两个语句**：
-  - 下拉树 / 列表树用 `.selectedPaths([["购买合同", "一次性付款"], ["服务协议"]])`——内层 = 一条选中路径、元素按层级顺序，
-    可短于层数（该层以下不限）；同一父节点的多条路径自动收束。
-  - 树标签用 `.selectedLevels([[], ["一次性付款"]])`——外层下标 = 层级，内层 = 该层选中值，空层或缺失层 = 该层不限
-    （树标签各层独立过滤，不是路径语义）。
-  两者都与 `defaultValue` 互斥，层数/路径长度不得超过绑定层级数。
-- `ControlItem.TIME_GROUP` 是时间按钮组：绑定一个日期字段，用一排标签（预置档位或自定义区间）快速切换
-  筛选区间。例：`.timeTags(TimeTag.preset(TimeTag.CURRENT_MONTH), TimeTag.of("上半年", "2024-01-01", "2024-06-30").selected())`。
-  该类型不支持 `defaultValue`/`customValues`/`allowInterval`/`sort`/`multiSelect`/`allowPassDefault`/`showTime`。
-- `ControlItem.QUERY`/`ControlItem.RESET`/`ControlItem.CLEAR` 是查询/重置/清空按钮：占位形态
-  （不绑定字段、无默认值/controlRange），全板各至多 1 个；`ControlItem.builder("查询", ControlItem.QUERY).autoQuery(false).build()`
-  关闭自动查询（默认 true=控件值变更即查询，false=点击按钮才查询，仅 QUERY 可用）。
-
-### 6.2 TextItem
-
-入口：
-
-```js
-TextItem.of("标题", "销售概览")
-```
-
-可用方法：
-
-| DSL API                                              | 业务含义          |
-|------------------------------------------------------|---------------|
-| `.withTitle("标题")`                                   | 设置文本组件标题。     |
-| `.withShowTitle(true)`                               | 设置是否显示文本组件标题。 |
-| `.withStyle({"fontSize":"20px", "color":"#333333"})` | 设置文本样式。       |
-
-业务补充：
-
-- `name` 是文本组件业务名。
-- `content` 是文本正文内容（纯文本），或 `RichText.of()...build()` 富文本（动态字段值，见 §6.8）。
-- `style` 是样式键值对，可用于字体大小、颜色、字重、背景色等。
-
-### 6.3 ImageItem
-
-入口：
-
-```js
-ImageItem.of("封面图", "data:image/png;base64,...")
-```
-
-可用方法：
-
-| DSL API                          | 业务含义                          |
-|----------------------------------|-------------------------------|
-| `.withHref("https://.../页面")`    | 设置点击跳转链接。                    |
-| `.withSize(ImageItem.WIDGET_SIZE)` | 设置填充方式（ORIGINAL/EQUAL/WIDGET_SIZE）。 |
-| `.withTitle("标题")`                | 设置图片组件标题。                     |
-| `.withShowTitle(true)`             | 设置是否显示图片组件标题。                 |
-
-业务补充：
-
-- `src` 是平台图片资源标识：上传图片的 attach id、`data:image...` 内联 URI 或 `resources?path=...` 资源路径；**不支持绝对 http(s) URL**（前端会经附件端点解析导致 404，构造期直接报错）。
-- attach id 用 CLI 命令产出：`finebi-cli dashboard upload-image --file <本地图片>`（jpg/jpeg/png/gif/bmp，20MB 内），返回的 `attachId` 即合法 src。
-- `size` 不写 = 平台默认 `ORIGINAL`（原始尺寸）。
-- 未 `position` 时默认网格 24×16 自动排版。
-
-### 6.4 LinkageModel
-
-入口：
-
-```js
-LinkageModel.of(
-    from("销售表").dim("地区"),
-    "订单明细",
-    from("销售表").dim("地区")
-)
-```
-
-业务含义：
-
-- 当源组件中的某个字段发生选择变化时，用该字段去过滤目标组件的目标字段。
-- 适合做钻取式分析，例如“点区域图，右侧明细表跟着变”。
-
-### 6.5 JumpModel
-
-入口：
-
-```js
-JumpModel.toReport(from("销售表").dim("地区"), "目标仪表板", from("销售表").dim("地区"))
-JumpModel.toUrl("https://example.com/s?wd=${地区}&t={currentTarget}", from("销售表").dim("地区"))
-```
-
-| DSL API                                       | 业务含义           |
-|-----------------------------------------------|----------------|
-| `JumpModel.toReport(fieldRef, "目标仪表板", targetFieldRef)` | 跳到另一张仪表板（分析模板型；targetField 传 `null` 表示只打开不定位字段）。 |
-| `JumpModel.toUrl(urlTemplate, fieldRef, ...)`  | 跳到网页链接（`${字段名}` 占位符按名匹配声明的字段引用并替换为字段 id；`{currentTarget}` 传当前点击值）。 |
-
-可选链（追加在工厂调用之后）：
-
-| DSL API | 业务含义 |
-|---------|--------|
-| `.fieldPair(srcField, tgtField)` | 追加一组字段映射（分析模板型可配多组）。 |
-| `.passValue(true/false)` | 覆盖派生的传值开关（有映射即传值；`false` 不能与字段映射并存）。 |
-| `.openPosition(JumpModel.FULL_SCREEN / DIALOG)` | 打开方式，省略 = 新窗口。 |
-| `.name("菜单名")` | 跳转菜单名，省略 = 平台默认名（分析模板/网页链接），同组件内不可重复。 |
-
-业务补充：
-
-- 第三个参数传 `null` 表示只打开目标，不额外定位字段。
-- 目标仪表板可跨主题（按名称解析：同主题同名板优先，未命中查全局）；目标字段解析到目标板用到的表（跨主题前先 `dashboard tables --id` 查字段名）。
-- 适合“从总览跳明细”或“从当前看板跳专题看板”。
-
-### 6.6 AdaptiveModel
-
-| DSL API | 业务含义      |
-|----------------------|-----------|
-| `AdaptiveModel.flowLayout()` | 自动适应：仅重排布局，不整体缩放。 |
-| `AdaptiveModel.origin(w, h)` | 固定基准尺寸：保持原始尺寸不缩放。 |
-| `AdaptiveModel.fitWidth(w, h)` | 固定基准尺寸：按宽度铺满等比缩放。 |
-| `AdaptiveModel.fitHeight(w, h)` | 固定基准尺寸：按高度铺满等比缩放。 |
-| `AdaptiveModel.fitAuto(w, h)` | 固定基准尺寸：按屏幕自适应铺满（宽高取小）。 |
-
-w/h 取值 100~10000（整数）；省略 `.adaptive(...)` 语句 = 自动适应 + 整体缩放（设计器默认）。
-
-### 6.7 MobileConfigModel
-
-| DSL API                                | 业务含义            |
-|----------------------------------------|-----------------|
-| `MobileConfigModel.defaults()`         | 使用默认移动端配置。      |
-| `MobileConfigModel.of(["组件A", "组件B"])` | 按给定顺序生成移动端组件序列。 |
-
-### 6.8 RichText（文本组件动态字段值）
-
-入口：`TextItem.ofRichText("名称", RichText.of()...build())`（独立工厂；`TextItem.of` 仅收纯文本）。
-
-| DSL API | 业务含义 |
-|---|---|
-| `RichText.of()` | 创建富文本构建器。 |
-| `.line("文本", fieldRef, styled(...))` | 追加一行：静态文本 / 字段引用 / 行内样式文本段混排（字段引用见 §7 字段写法，dim/sum/avg/count 均可；也支持已保存计算字段 `measureID("配置 ID").dim()` 与业务模型字段 `model("模型").dataset("数据集").dim("字段")`）。 |
-| `styled(fieldRef, {"font-weight": "bold"})` | 行内样式**字段值**段：给动态字段值加行内样式（对齐编辑器里选中已插入的字段再点加粗/改色）。样式规则与下面的 `styled("文本", ...)` 完全一致。 |
-| `styled("文本", {"font-size": "20px"})` | 行内样式文本段：key 必须是 CSS 属性名（小写字母+连字符，如 font-size / color / font-weight），写入内联 `<span style="...">`；camelCase（如 fontSize）前端会静默丢弃，编译期直接报错。 |
-| `formatted(fieldRef, NumberFormatModel.number(...))` | 数值格式字段值：`formatted(from("销售表").sum("销售额"), NumberFormatModel.number(2))`。格式工厂：`NumberFormatModel.number(小数位[, NumberFormatModelScale.THOUSAND, "单位", 千分位])` / `NumberFormatModel.percentage(小数位, 千分位)`。**只作用于指标/数值值（sum/count 等聚合），dim 引用按维度文本处理格式不生效**；`auto()` 等于未设置会被编译期拒绝（用裸字段引用）。 |
-| `fieldValue(fieldRef)` | 带字段级配置的动态字段值（可选链，全部可省 = 平台默认）：`.sort(SortOrder.ASC/DESC)` / `.sortByField(fieldRef, SortOrder.*)`（跨字段排序）/ `.dateFormat(FieldValue.SPLIT/CHINESE/SLASH)`（日期显示格式）/ `.numberFormat(NumberFormatModel...)` / `.where(fieldRef, "eq"\|"in"\|"between"\|"not_null", [值...])`（指标条件，可多次 AND 叠加；数值 between 前可用 `.closeRange(includeMin, includeMax)` 声明端点开闭，省略 = 全闭）/ `.showDefaultData()`，末尾 `.build()`。例：`fieldValue(from("销售表").dim("签约时间")).dateFormat(FieldValue.CHINESE).sort(SortOrder.DESC).build()`。**分组/汇总语义不在这里写**——由字段引用本身承载（`dim(名, DimensionGrouping.dateGranularity("YEAR_MONTH"))` / `sum(...)` / `avg(...)`）。字段类型门禁与前端字段面板一致：排序/显示默认数据限文本/日期字段，时间格式限日期字段，数值格式与指标条件限数值字段。指标条件的算子族按**被过滤字段**类型分派（数值：eq/between/not_null；文本：eq/in/not_null；日期：eq/between/not_null），过滤值必须是静态值（公式过滤平台不支持）。 |
-| `link("文本", "https://...")` | 超链接文本段：`line("详见 ", link("官网", "https://www.finebi.com"))`。查看态渲染为可点击链接；`javascript:` 协议编译期拒绝。只包静态文本——字段值/行内样式不能带链接（反读遇该形态丢弃链接保内容并给 `RICH_TEXT_LINK_DROPPED` 提示）。 |
-| `widgetName()` | 组件自身名称：查看态解析为组件在主题里的名字（组件改名后自动跟随）。**只有组件标题可用**——文本组件没有「组件名」插入项（写进文本组件会编译期报错，前端查看态也只会渲染成「元素被删除」）。 |
-| `componentField("组件名", fieldRef)` | 引用**同一仪表板上另一个组件**的字段/指标（对齐前端「插入组件字段」）：`componentField("月度趋势", from("销售表").sum("销售额"))`。组件必须在本脚本中已声明（reference/addWidget）；字段引用要与目标组件对该字段的分组/汇总方式一致（组件字段的分组键由字段引用派生，不一致则查看态取不到值）；**记录数用 `count(from(表).dim(字段))`，字段依赖必须是物理字段；去重计数用 `from(表).countDistinct(字段)` 或 `measureID("配置 ID").countDistinct()`**（字段须已在主题内转成指标形态，见 measure 命令；富文本里去重计数只有组件字段这一种表达——直接字段引用带 `countDistinct` 会编译期报错）。不支持 sort/dateFormat/numberFormat/where 等字段级配置（前端组件字段面板没有这些入口）。 |
-| `.listItem(RichText.ORDERED\|UNORDERED, 片段...)` | 追加列表项（有序 / 无序）：片段形态与 `line(...)` 相同，`align(...)` 同样作用于刚追加的项；**相邻同类型项自动归并为一个列表块**。例：`.listItem(RichText.UNORDERED, "华东：", from("销售表").sum("销售额"))`。 |
-| `.verticalAlign(RichText.TOP/MIDDLE/BOTTOM)` | 整块垂直对齐（对齐前端文本组件的「垂直对齐」按钮）。不写 = TOP（前端默认）；重复声明报错；**只有文本组件有该入口**（组件标题声明会报错）。 |
-| `.align(RichText.LEFT/CENTER/RIGHT)` | 对齐刚追加的行（可选；不写 = 默认左对齐，与 position 不写走自动排同款语义）：`.line(...).align(RichText.CENTER)`。仅修饰最后追加的行，先 line 再 align。 |
-| `.build()` | 冻结富文本，作为 TextItem 第二参数。 |
-
-```js
-TextItem.ofRichText("概览", RichText.of()
-        .line("总销售额：", formatted(from("销售表").sum("销售额"),
-            NumberFormatModel.number(2)))
-        .line("订单数：", formatted(count(from("销售表").dim("订单号")),
-            NumberFormatModel.number(0)))
-        .line("签约时间：", fieldValue(from("销售表").dim("签约时间"))
-            .dateFormat(FieldValue.CHINESE).sort(SortOrder.DESC).build())
-        .line("重点地区：", from("销售表").dim("地区"),
-            styled("重点关注", {"font-size": "20px", "color": "#ff0000"}))
-        .listItem(RichText.UNORDERED, "看板口径见 ", link("帮助文档", "https://help.fanruan.com/finebi/"))
-        .listItem(RichText.UNORDERED, "数据由 ", from("销售表").sum("销售额"), " 支撑")
-        .verticalAlign(RichText.MIDDLE)
-        .build())
-```
-
-业务补充：
-
-- 每行按顺序渲染；字段值在查看态显示真实数据。
-- 字段来源两类：主题字段直引 `from(表名)`；引用**同一仪表板其他组件的字段**用 `componentField("组件名", fieldRef)`（§6.8）。
-**约束（2026-08-26 真机实证 + 2026-09-08/2026-09-11 补）**：富文本记录数两种写法——带依赖 `count(from(表).dim(字段))`（占位符 appId = `{物理表 id}_count-field-id` + fieldsConfig 条目 counterDep = 物理字段 id）与无依赖 `from(表).count()`（前端插入的默认形态，appId 表前缀取来源表、条目无 counterDep）；两者反读都能还原。带依赖时**依赖只能是物理字段**——`count(measureID(...).dim())` 等计算/模型字段依赖保存时直接报错（表前缀来自物理复合 id 首段，拼不出合法占位符）。
-- 平台占位符与字段配置由后端自动生成，DSL 不写。
-- 行内样式（字体大小/颜色/加粗 `{"font-weight": "bold"}` / 斜体 `{"font-style": "italic"}` 等）用 `styled(...)` 文本段表达；`withStyle` 是组件级样式，前端只消费 backgroundColor，不要用它设置字体/颜色。
-- 反读（`dashboard dsl`）时前端 `<strong>`/`<em>` 自动翻译为 font-weight/font-style。
-- 给**动态字段值**加行内样式用 `styled(fieldRef, {...})`（同一工厂名按参数类型分派：String = 静态文本段，FieldRef = 字段值段，如 `styled(from("销售表").sum("销售额"), {"font-weight": "bold"})`）——对应编辑器里选中字段再点加粗/改色。字段级配置（`fieldValue(...)`）与组件名/组件字段不接受行内样式，并存时样式被丢弃并给 `RICH_TEXT_STYLE_DROPPED` 提示。
-
-## 7. 字段写法
-
-Dashboard DSL 中涉及字段的地方，包括控件、联动和跳转，都统一使用 source-scoped 写法：
-
-```js
-from("销售表").dim("地区")
-from("销售表").sum("销售额")
-from("销售表").measure("销售额")
-```
-
-### 6.9 WebItem
-
-入口：
-
-```js
-WebItem.of("官网", "https://example.com/page")
-```
-
-可用方法：
-
-| DSL API                | 业务含义          |
-|------------------------|---------------|
-| `.withTitle("标题")`      | 设置 Web 组件标题。   |
-| `.withShowTitle(true)` | 设置是否显示 Web 组件标题。 |
-
-业务补充：
-
-- `url` 是 iframe 打开的地址，原样存储；`javascript:` 协议在构造期报错（平台反序列化器与前端输入框同款校验）。
-- 地址里可以带 `{控件名}` 形式的查询参数，前端查看态会按控件筛选值回填；DSL 不做解析。
-- Web 组件不参与取数，也不能被控件的 `controlRange` 圈定。
-- 未 `position` 时默认网格 24×16 自动排版。
-
-### 6.10 CombineItem（组件组合）
-
-入口：
-
-```js
-CombineItem.of("趋势组", "月度趋势", "区域分布")   // 至少 2 个成员名
-```
-
-可用方法：
-
-| DSL API                | 业务含义          |
-|------------------------|---------------|
-| `.place("成员名", col, row, wCols, hRows)` | 成员在组合内容区 72×36 网格内的局部格位（省略 = 填充式自动分：1 个铺满、2 个对半、4 个四象限）。 |
-| `.gap(n)`              | 组件间隙（0-20 偶数，默认 6 省略）。 |
-| `.withTitle("标题")`      | 组合标题。 |
-| `.withShowTitle(true)`  | 显示标题栏（默认 false；显示时内容区下移 25px）。 |
-
-业务补充：
-
-- 组合是把相关组件整理成区块（批量移动、区块背景与间隙由设计器样式面板承载，DSL 未建模，反读偏离留痕）。
-- 成员不能是 Tab / 组合 / 冻结栏（设计器遮罩同口径）；组合未 `position` 时默认 72×24 自动排。
-
-### 6.11 TabItem（Tab 组件）
-
-入口：
-
-```js
-TabItem.of("分析页签")
-    .page("华东", "月度趋势")
-    .page("华南", "区域分布", "华南说明文本")
-```
-
-可用方法：
-
-| DSL API                | 业务含义          |
-|------------------------|---------------|
-| `.page("页名", 成员...)` | 追加一页（成员可空——空页合法）；页名组件内唯一。 |
-| `.place("成员名", col, row, wCols, hRows)` | 成员在**最近声明页**内容区的局部格位（省略 = 页内填充式自动分）。 |
-| `.selected("页名")`      | 选中页（省略 = 首页）。 |
-| `.style(tabStyle)`      | 页签标签样式（`TabStyle.of()...`，见下）。 |
-| `.withTitle("标题")` / `.withShowTitle(false)` | 标题与显示（默认显示标题栏）。 |
-
-`TabStyle.of()` 可链槽位（全部省略 = 平台骨架：风格 1 下划线 / 左对齐 / 默认字体 12 号 / 空态色）：
-
-| DSL API | 业务含义 |
-|---|---|
-| `.style(TabStyle.STYLE1\|STYLE2\|STYLE3)` | 标签风格：1 下方线条 / 2 选中色块 / 3 全色块。 |
-| `.align(TabStyle.LEFT\|CENTER\|RIGHT)` | 标签条位置。 |
-| `.fontFamily("...")` / `.fontSize(n)` / `.fontBold(b)` / `.fontItalic(b)` / `.fontUnderline(b)` | 标签字体（字号取字体面板值集）。 |
-| `.defaultState("#色", "#背景")` / `.selectedState("#色", "#背景")` | 未选中 / 选中标签配色（空串 = 跟随模板样式）。 |
-
-业务补充：
-
-- 页成员不能是 Tab；可含组合与冻结栏（冻结栏每页至多 1 个）；Tab 未 `position` 时默认 72×16。
-- 未重命名页在反读时按前端展示链回落首成员名。
-
-### 6.12 FreezeItem（过滤组件冻结栏）
-
-入口：
-
-```js
-FreezeItem.of("顶部筛选栏", "类型筛选", "交货筛选")   // 成员为控件与复合过滤组件，可为空
-```
-
-可用方法：
-
-| DSL API                | 业务含义          |
-|------------------------|---------------|
-| `.place("控件名", col, row, wCols, hRows)` | 控件局部格位（省略 = 流式自动排：自左向右放不下换行，按冻结栏专用控件尺寸表——按钮 12×12、树标签/滑块/按钮组高 36、其余 24×18）。 |
-| `.gap(n)`              | 控件间隙（0-20 偶数，默认 6 省略）。 |
-| `.showExpand(true)`    | 显示展开按钮（默认 false；控件多时查看态可向下展开冻结栏）。 |
-
-业务补充：
-
-- 查看态冻结栏钉在页面上方、滚动跟随（帮助文档「过滤组件冻结栏」）；成员不可悬浮、不可入组合，可入 Tab 页。
-- 冻结栏未 `position` 时默认 72×8 自动排。
-
-### 6.13 GeneralQueryItem（复合过滤组件）
-
-入口：
-
-```js
-GeneralQueryItem.of("复合过滤")                      // 全板至多 1 个
-GeneralQueryItem.of("复合过滤")
-    .where(from("合同订单原表").dim("地区"), "in", ["华东"])            // 顶层条件，多条 AND
-    .where(from("合同订单原表").dim("合同签约时间"), "between", ["2024-01-01", "2024-06-30"])
-    .where(QueryCondition.between(from("合同订单原表").dim("购买金额"), 1, 100, true, true))  // 显式开闭
-    .orGroup(                                                          // 或组：组内 OR，与前几条 AND
-        QueryCondition.of(from("合同订单原表").dim("购买金额"), "between", [1, null]),
-        QueryConditionGroup.allOf([                                    // 或组内嵌且组（多层树）
-            QueryCondition.of(from("合同订单原表").dim("地区"), "not_in", []),
-            QueryCondition.of(from("合同订单原表").dim("购买金额"), "ge", [100])]),
-        QueryCondition.of(from("合同订单原表").dim("合同签约时间"), "after",
-            [DynamicDate.beginOf(DynamicDate.YEAR, -1)]))
-    .filterLevel(ControlItem.FIRST)
-```
-
-可用方法：
-
-| DSL API                | 业务含义          |
-|------------------------|---------------|
-| `.where(fieldRef, "算子", [值...])` | 追加一条**顶层过滤条件**（多条之间 AND，声明序即持久化序）。 |
-| `.where(QueryCondition.between(...))` | 追加**带端点开闭的区间条件**（值对象入口）：`QueryCondition.between(fieldRef, min, max, includeMin, includeMax)` / `QueryCondition.notBetween(...)`；开闭省略（`of` 形态）= 平台骨架**左闭右开**。 |
-| `.orGroup(成员, 成员...)` | 追加一个**或组**（组内 OR，组与顶层其他条件 AND）；成员为 `QueryCondition.of(fieldRef, "算子", [值...])` 或嵌套 `QueryConditionGroup.allOf([...])` / `anyOf([...])` 且/或组（设计器条件树任意深度），至少 2 条。 |
-| `.filterLevel(ControlItem.FIRST \| ControlItem.SECOND)` | 过滤层级（前置过滤 / 明细过滤）——**每个条件叶子**按该档落值；仅标准分析主题可声明，省略 = 平台默认。 |
-| `.withTitle("标题")` / `.withShowTitle(false)` | 标题与显示开关（默认显示标题）。 |
-
-算子按字段族取值（族外算子保存时直接报错）：
-
-| 字段族 | 算子 |
-|---|---|
-| 文本 | `in`（属于）/ `not_in` / `contain` / `not_contain` / `begin_with` / `not_begin_with` / `end_with` / `not_end_with` / `null` / `not_null` |
-| 数值 | `between`（区间）/ `not_between` / `eq` / `ne` / `gt` / `ge` / `lt` / `le` / `null` / `not_null` |
-| 日期 | `between`（期间）/ `not_between` / `before`（早于）/ `after`（晚于）/ `eq` / `ne` / `null` / `not_null` |
-
-业务补充：
-
-- 值列表：`between` 给 `[min, max]`，**任一端写 `null` 表示该侧无界**（如 `[1, null]` = 金额 ≥ 1）；`null` / `not_null` 不给值；`in` / `not_in` 可以给空列表（= 清空选择）。
-- **数值区间端点开闭**：`between` / `not_between` 省略 = 左闭右开（设计器默认骨架）；双闭 / 双开 / 左开右闭用 `QueryCondition.between/notBetween(fieldRef, min, max, includeMin, includeMax)` 显式声明。仅数值区间适用——日期期间恒含端点，开闭声明用在日期字段上保存时报错。
-- 日期条件给静态字符串（格式随字段粒度，默认天粒度 `yyyy-MM-dd`）或**动态时间值**：`DynamicDate.beginOf/endOf(单位, 偏移)`、`DynamicDate.today()`；工作日偏移、明确粒度、时钟用 `FilterDate`（与组件过滤同模型，见 [widget-dsl-api §6 过滤上下文](widget-dsl-api.md#6-过滤上下文)的 FilterDate 段）。
-- **空值条件（清空态）**：条件值元素写 `null` 表示该条件被「清空」（设计器清空按钮的空值骨架：区间 `[null, null]`、单边比较 `[null]`、文本匹配 `[null]`、日期 `[null]`）。平台查询语义：正向算子（属于/包含/介于等）放行全部，取反算子（不属于/不包含/不介于）结果为空——**两种都影响查询结果**，反读会保真还原，不要手写丢弃。
-- 条件字段的引用方式与控件绑定字段一致：物理字段 `from("表").dim("字段")` / 已保存计算字段 `measureID(id).dim()` / 模型字段 `model("模型").dataset("数据集").dim("字段")`。
-- **跨来源字段（不推荐）**：`fieldOf("表id", "字段名")` 可引用不在当前主题内的表（公共数据、其他分析主题的数据集）。**新看板不要用**——BI 分析以主题为单位，应引用主题内的表/模型，或先把字段并入主题/业务模型；跨来源条件绕过主题的关联、权限与血缘语义。该形态主要作为**读改写保真兜底**：设计器可以绑定这类字段，回写时不能丢条件。
-  （真要用时：表 id 取自 `finebi-cli public-ds search`（公共数据）或 `finebi-cli analysis-ds search`（分析数据集），字段名用该表的字段名。）
-- **不声明任何条件 = 空骨架**：查看者在查看态自行增删条件、且或组合，条件变更即触发其他组件刷新查询；声明的初始条件查看态可直接改。
-- 设计器里同一条件下只能选同族算子；`where` 的字段若已删除，反读时该条会被丢弃并留痕（参数值 / TopN / 平均值比较 / 非天粒度静态日期等编辑器配不出的形态同样留痕丢弃）。
-- 未 `position` 时默认 24×8 自动排；可悬浮、可入组合 / Tab 页 / 冻结栏。
-- 控件作用范围（controlRange）不可圈定复合过滤组件。
-
-### 6.14 AiDiagnosisItem（AI 诊断组件）
-
-入口：
-
-```js
-AiDiagnosisItem.of("AI诊断", "月度趋势", "区域销售额")   // 诊断对象为同板数据组件名，至少 1 个
-```
-
-业务补充：
-
-- 诊断对象必须是同板已声明的**数据组件**（表格 / 明细表 / 图表——设计器的诊断对象选择器只列这三类；交叉表等数据组件也放行，属有意超集），可在 `aiDiagnosis` 声明之后才声明。
-- 诊断知识默认平台默认档；自定义时用 `.analysisDocId("<分析文档id>")`（id 来自设计器「诊断知识」面板配置的分析文档，裸 id 透传——分析文档域暂无 CLI 查询命令，后续落地后升级按名引用）。读改写会原样保留该配置。
-- 未 `position` 时默认 24×16 自动排；可悬浮、可入组合 / Tab 页，不可入冻结栏、不可被 controlRange 圈定。
-- 查看态的对话与诊断依赖平台 AI 配置（未配置时组件渲染占位提示）；仪表板的保存与读取不受该配置影响。
-
-## 8. 推荐写法示例
-
-### 8.1 引用已有组件
-
-```js
-DashboardDsl.create("经营总览")
-    .content()
-    .reference("区域销售额")
-    .reference("月度趋势")
-    .presentation()
-    .position("区域销售额", 0, 0, 24, 16)
-    .position("月度趋势", 24, 0, 24, 16)
-    .build()
-```
-
-适用场景：已有组件已经保存到平台，只负责组织它们在仪表板上的摆放。
-
-### 8.2 筛选控件
-
-```js
-DashboardDsl.create("带筛选控件")
-    .content()
-    .reference("月度趋势")
-    .control(
-        ControlItem.builder("区域筛选", ControlItem.TEXT)
-            .bindField(from("销售表").dim("地区"))
-            .controlRange(["月度趋势"])
-            .title("区域")
-            .showTitle(true)
-            .build()
-    )
-    .presentation()
-    .position("月度趋势", 0, 0, 24, 16)
-    .position("区域筛选", 0, 16, 24, 4)
-    .build()
-```
-
-适用场景：给指定组件加一个局部生效的文本筛选控件。
-
-### 8.3 数据组件标题
-
-```js
-DashboardDsl.create("经营总览")
-    .content()
-    .reference("区域销售额")
-    .title("区域销售额", "各区域销售额")
-    .showTitle("区域销售额", true)
-    .presentation()
-    .position("区域销售额", 0, 0, 24, 16)
-    .build()
-```
-
-标题也可以带动态字段值（富文本标题，形态与文本组件富文本一致）：
-
-```js
-DashboardDsl.create("经营总览")
-    .content()
-    .reference("区域销售额")
-    .title("区域销售额", RichText.of()
-        .line("各区域销售额（", widgetName(), "）")   // 组件名只有标题可用
-        .line("更新至：", from("销售表").dim("统计日期"))
-        .build())
-    .presentation()
-    .position("区域销售额", 0, 0, 24, 16)
-    .build()
-```
-
-标题富文本的片段类型与文本组件一致（`line` / `listItem` / `styled` / `link` / 字段引用 / `widgetName()` / `componentField(...)`），但**标题没有整块垂直对齐**（前端标题面板无该入口，声明 `verticalAlign(...)` 会报错）。
-
-适用场景：复用已有组件，但在当前仪表板中使用新的业务标题。
-
-### 8.4 时间控件
-
-```js
-DashboardDsl.create("按月分析")
-    .content()
-    .reference("月度趋势")
-    .control(
-        ControlItem.builder("月份控件", ControlItem.MONTH)
-            .bindField(from("销售表").dim("月份"))
-            .title("月份")
-            .showTitle(true)
-            .build()
-    )
-    .presentation()
-    .position("月份控件", 0, 0, 24, 4)
-    .position("月度趋势", 0, 4, 24, 16)
-    .build()
-```
-
-适用场景：用月份控件驱动时间分析。
-
-### 8.5 文本 + 数据组件
-
-```js
-DashboardDsl.create("销售总览")
-    .content()
-    .text(
-        TextItem.ofRichText("标题", RichText.of()
-            .line(styled("销售总览", {"font-size": "24px", "font-weight": "600", "color": "#333333"}))
-            .build())
-    )
-    .reference("区域销售额")
-    .presentation()
-    .position("标题", 0, 0, 24, 4)
-    .position("区域销售额", 0, 4, 24, 16)
-    .build()
-```
-
-适用场景：用标题文本、说明文本给数据组件做语义包装。
-
-### 8.6 富文本动态指标（KPI 风格）
-
-```js
-DashboardDsl.create("经营速览")
-    .content()
-    .text(TextItem.of("核心指标", RichText.of()
-            .line("总销售额：", from("销售表").sum("销售额"), " 元")
-            .line("订单数：", count(from("销售表").dim("订单号")))
-            .build()))
-    .presentation()
-    .position("核心指标", 0, 0, 24, 8)
-    .build()
-```
-
-适用场景：在文本组件里展示字段真实数据（维度值、聚合指标、记录数），做 KPI 概览或说明行；字段写法同 §7。
-
-### 8.7 主动联动
-
-```js
-DashboardDsl.create("区域销售分析")
-    .content()
-    .reference("区域销售图")
-    .reference("订单明细")
-    .linkage(
-        "区域销售图",
-        LinkageModel.of(
-            from("销售表").dim("地区"),
-            "订单明细",
-            from("销售表").dim("地区")
-        )
-    )
-    .presentation()
-    .position("区域销售图", 0, 0, 24, 16)
-    .position("订单明细", 24, 0, 24, 16)
-    .build()
-```
-
-适用场景：点击左侧汇总图，右侧明细表跟随过滤。
-
-### 8.8 组件跳转
-
-```js
-DashboardDsl.create("销售驾驶舱")
-    .content()
-    .reference("区域销售图")
-    .jump(
-        "区域销售图",
-        JumpModel.toReport(
-            from("销售表").dim("地区"),
-            "区域专题看板",
-            from("销售表").dim("地区")
-        )
-        .openPosition(JumpModel.DIALOG)
-        .name("查看区域专题")
-    )
-    .presentation()
-    .position("区域销售图", 0, 0, 24, 16)
-    .build()
-```
-
-适用场景：从总览看板跳到专题看板（也可用 `JumpModel.toUrl` 跳网页链接）。
-
-### 8.9 关闭默认联动与单目标禁用
-
-```js
-DashboardDsl.create("显式联动看板")
-    .content()
-    .reference("chartA")
-    .reference("chartB")
-    .reference("chartC")
-    .linkage("chartA", LinkageModel.of(
-        from("销售表").dim("地区"),
-        "chartB",
-        from("销售表").dim("地区")
-    ))
-    .linkage("chartA", LinkageModel.disable("chartC"))
-    .cancelDefaultLinkage()
-    .presentation()
-    .position("chartA", 0, 0, 24, 16)
-    .position("chartB", 24, 0, 24, 16)
-    .position("chartC", 48, 0, 24, 16)
-    .build()
-```
-
-适用场景：只保留显式编排的联动关系（天然联动整板关闭；`LinkageModel.disable` 对单个目标关闭）。
-
-### 8.10 持久化联动效果
-
-```js
-DashboardDsl.create("留存联动看板")
-    .content()
-    .reference("区域销售图")
-    .reference("订单明细")
-    .text(TextItem.of("区域说明", "当前聚焦区域"))
-    .linkageEffect(
-        "区域销售图",
-        LinkageEffect.click(from("销售表").dim("销售额"))
-            .cell(from("销售表").dim("地区"), "华东")
-            .summaryCell("合计"),
-        "订单明细", "区域说明"
-    )
-    .presentation()
-    .position("区域销售图", 0, 0, 24, 16)
-    .position("订单明细", 24, 0, 24, 16)
-    .position("区域说明", 0, 16, 24, 4)
-    .build()
-```
-
-适用场景：看板打开即呈现「区域销售图点击华东后」的联动状态（数据/文本目标跟随过滤）。与 `linkage` 配置正交；一条效果一跳生效、不传递。
-
-### 8.11 使用平台预设样式
-
-```js
-DashboardDsl.create("大屏主题示例")
-    .content()
-    .reference("经营概览")
-    .presentation()
-    .stylePreset("DEFAULT_DARK")
-    .position("经营概览", 0, 0, 24, 16)
-    .build()
-```
-
-适用场景：快速套用平台内置深色或浅色风格。
-
-### 8.12 使用全局自定义样式
-
-```js
-DashboardDsl.create("品牌看板")
-    .content()
-    .reference("区域销售额")
-    .presentation()
-    .customStyle("销售总览样式")
-    .position("区域销售额", 0, 0, 24, 16)
-    .build()
-```
-
-适用场景：复用团队统一维护的品牌样式。
-
-### 8.13 移动端顺序
-
-```js
-DashboardDsl.create("移动端示例")
-    .content()
-    .reference("w1")
-    .reference("w2")
-    .reference("w3")
-    .mobile()
-    .mobileConfig(MobileConfigModel.of(["w2", "w1", "w3"]))
-    .build()
-```
-
-适用场景：移动端展示顺序与桌面端布局顺序不同，需要单独编排。
-
-### 8.14 多字段控件
-
-```js
-DashboardDsl.create("多字段筛选")
-    .content()
-    .reference("区域销售额")
-    .reference("订单明细")
-    .control(
-        ControlItem.builder("地区与大区筛选", ControlItem.TEXT_LIST)
-            .bindFields([
-                from("销售表").dim("地区"),
-                from("销售表").dim("大区")
-            ])
-            .controlRange(["区域销售额", "订单明细"])
-            .title("区域范围")
-            .showTitle(true)
-            .build()
-    )
-    .presentation()
-    .position("地区与大区筛选", 0, 0, 24, 8)
-    .position("区域销售额", 0, 8, 24, 16)
-    .position("订单明细", 24, 8, 24, 16)
-    .build()
-```
-
-适用场景：同一个控件要同时绑定多个业务字段，用一组筛选驱动多个组件。
-
-### 8.15 控件默认值与排序
-
-```js
-DashboardDsl.create("带默认值的筛选")
-    .content()
-    .reference("月度趋势")
-    .control(
-        ControlItem.builder("地区筛选", ControlItem.TEXT_BUTTON_GROUP)
-            .bindField(from("销售表").dim("地区"))
-            .defaultValue(["华东"])
-            .sort("asc")
-            .multiSelect(false)
-            .build()
-    )
-    .presentation()
-    .position("地区筛选", 0, 0, 24, 8)
-    .position("月度趋势", 0, 8, 24, 16)
-    .build()
-```
-
-适用场景：控件需要预选某个业务值，并按升序稳定展示候选项。
-
-### 8.16 带目标字段的跳转
-
-```js
-DashboardDsl.create("区域驾驶舱")
-    .content()
-    .reference("区域销售图")
-    .jump(
-        "区域销售图",
-        JumpModel.toReport(
-            from("销售表").dim("地区"),
-            "区域专题看板",
-            from("销售表").dim("地区")
-        )
-    )
-    .presentation()
-    .position("区域销售图", 0, 0, 24, 16)
-    .build()
-```
-
-适用场景：从当前看板跳转到目标看板时，把当前选中的业务字段一并带过去做定位。
-
-### 8.17 默认移动端配置
-
-```js
-DashboardDsl.create("移动端默认配置")
-    .content()
-    .reference("经营概览")
-    .reference("订单明细")
-    .mobile()
-    .mobileConfig(MobileConfigModel.defaults())
-    .build()
-```
-
-适用场景：明确声明“移动端沿用平台默认配置”，避免由调用方再补默认值。
-
-## 9. 场景模板与设计要点
-
-`dashboard template` 的每个场景都给出可抄脚本 + 变量契约 + `guidance`（设计要点，共享要点在前、
-场景专属在后）。设计要点只讲**决策**（怎么摆、怎么取舍），语法与取值约束以本文档与
-`dashboard schema` 为准。
-
-| 场景 id | 形态 | 覆盖能力 |
-|---|---|---|
-| `basic` | 经营看板：筛选条 + KPI 富文本行 + 封面图 + 双图表联动 | 引用/标题/富文本（列表、链接、行内样式）/图片/控件 + controlRange/联动/网格 position/stylePreset/移动端 |
-| `kpi` | KPI 概览：富文本指标行 + 一张图 | 富文本动态字段；注释给出 KPI 指标卡组件的替代路径（`widget template --chart-type KPI_CARD`） |
-| `filter` | 筛选控件：多选列表 + 数值区间 + 日期区间 + 查询/重置/清空 | 控件属性族（title/required/sortByField/closeRange）与按钮族；日期过滤不写死默认区间 |
-| `style` | 样式面：预设基底 + 六分区微调 | stylePreset/customStyle + templateStyle（背景/卡片/图表配色/表格/过滤/图片）+ FontModel/TableFont |
-| `screen` | 大屏驾驶舱：固定基准 + 悬浮装饰 + 深色预设 | adaptive(AdaptiveModel.fitAuto/origin) + float + dynamicDefault 日期控件 |
-| `rich-text` | 富文本与动态字段：富标题 + 组件字段 + 行内样式 + 列表链接 | title(name, RichText)/widgetName()/componentField/styled/formatted/fieldValue 子链/图片 withHref |
-| `linkage-jump` | 联动与跳转：跨表自定义依赖字段联动 + 两型跳转（分析模板传值 / 网页链接占位符）+ 持久化联动效果 | linkage(LinkageModel.of)/linkageEffect(LinkageEffect.click + cell)/jump(JumpModel.toReport/toUrl + openPosition/name)；目标板字段先 `dashboard tables --id` 查候选；clickedValue 须取源组件数据里的真实显示值（空组合联动结果为空） |
-| `tree-time` | 层级与时间筛选：二级树（省→市）+ 时间按钮组驱动一张图 | TREE 的 bindField 声明序=层级（跨表层级须同关联分量）/多层级树无 defaultValue；TIME_GROUP + timeTags(TimeTag.preset(...).selected())，未标 selected 则首屏不过滤 |
-| `blocks` | 容器区块：冻结筛选栏 + Tab 页签（页内组合区块 + 明细页）+ 页脚长板 | combine(CombineItem.of/gap/withTitle)/tab(TabItem.of/page/selected/style)/freeze(FreezeItem.of/gap/showExpand)；成员单容器归属、成员不得顶层 position、组合悬浮须成员全悬浮 |
-
-通用设计要点（每个场景响应都会带回，节选）：
-
-- 结构：标题 → 筛选区 → 关键指标行 → 主分析区（1–2 行图表）→ 明细表（可选）。
-- 节奏：一屏 2–3 行组件；同类组件等宽（36+36 或 24+24+24）；`widgetGap` 8–16 留白。
-- 自适应：日常分析用省略态；汇报/大屏改固定基准尺寸（`origin`/`fitWidth`/`fitAuto`）。
-- 样式：整板一个基底 + `templateStyle` 局部微调；图表配色统一；字号不超过三档。
-- 交互：筛选组件置顶并用 `controlRange` 圈定；查询按钮保持默认自动查询（写 `autoQuery(false)`
-  且无默认值时首屏可能空板）。
+用 `dashboard style-presets` 查，语句面速查用 `dashboard schema`。API 面拆分为下表文件，
+按需读取当前操作涉及的文件，不一次加载全部；章节编号沿用拆分前原编号。
+
+| 文件 | 章节 | 何时读取 |
+| --- | --- | --- |
+| [dashboard-dsl-core.md](dashboard-dsl-core.md) | §1-§5 根入口、顶层 Builder、内容域（条目挂载、联动与跳转）、布局与样式域、移动端域；§7 字段写法 | 写任何仪表板前必读 |
+| [dashboard-dsl-items.md](dashboard-dsl-items.md) | §6 可构造值对象（6.1-6.14：控件、文本、图片、联动/跳转模型、自适应、移动端配置、富文本、Web、组合、Tab、冻结栏、复合过滤、AI 诊断） | 挂载或配置具体条目类型时 |
+| [dashboard-dsl-examples.md](dashboard-dsl-examples.md) | §8 推荐写法示例、§9 场景模板与设计要点 | 需要可抄写法或场景模板时 |