@finebi/finebi-cli 1.5.0 → 1.6.0

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

@@ -0,0 +1,456 @@
+# Dashboard DSL API：可构造值对象
+
+> Dashboard DSL API 总导航见 [dashboard-dsl-api.md](dashboard-dsl-api.md)。
+
+## 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({"backgroundColor":"#fffbe6"})` | 设置组件背景色；不设置正文字体样式。 |
+
+业务补充：
+
+- `name` 是文本组件业务名。
+- 纯文本正文使用 `TextItem.of(name, text)`；带样式的静态文本或动态字段使用 `TextItem.ofRichText(name, RichText.of()...build())`，见 §6.8。
+- `withStyle` 是组件级样式，前端只消费 `backgroundColor`。正文的字号、颜色、加粗和字体使用 `styled(...)`，不能放在 `withStyle` 中。
+
+静态标题也通过富文本设置字体样式：
+
+```js
+TextItem.ofRichText("看板标题", RichText.of()
+    .line(styled("经营目标达成分析看板", {
+        "font-size": "32px",
+        "color": "#76b7b2",
+        "font-weight": "bold",
+        "font-family": "STKaiti, Kai, KaiTi, 楷体"
+    }))
+    .build())
+```
+
+`styled` 使用 CSS 属性名（如 `font-size`，不能写 `fontSize`）；字体能否呈现取决于浏览器所在设备可用的字体。完整富文本 API 和样式规则见 §6.8。
+
+### 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 字段写法](dashboard-dsl-core.md#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()` 等于未设置会被编译期拒绝（用裸字段引用）；带参数的自动格式可用，参数与单位规则见 [数值格式工厂](widget-dsl-contexts.md#8-数值格式工厂)。 |
+| `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` 提示。
+
+### 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-contexts §6 过滤上下文](widget-dsl-contexts.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 配置（未配置时组件渲染占位提示）；仪表板的保存与读取不受该配置影响。
+

package/skills/finebi-cli-agent/references/mapping-rules.md

@@ -50,7 +50,7 @@
 | `funnel` | `.chart().funnel()`，阶段维度放 color 或 y，指标放 size；多指标连续 size，配 colorMetricName 或 granularityMetricName；标签可开 showConversionRate/showMeasureSum |
 
 瀑布图按已确认的分类顺序映射排序，y 的累计口径与 size 的原始变化量分别声明；完整示例见
-[Widget DSL API 瀑布图编码](widget-dsl-api.md#421-瀑布图编码)。
+[Widget DSL API 瀑布图编码](widget-dsl-encodings.md#421-瀑布图编码)。
 
 说明：
 
@@ -188,7 +188,7 @@ GAUGE 的专属配置直接跟在 `.chart().gauge()`（或具体仪表盘类型
 先确定全部指标左右归属，再给每侧配置范围、标签、逆序、对数和标题；同侧配置不得互相冲突。
 金额/百分比等展示格式仍用 `.numberFormat()`，刻度边界使用原始值，不按百万等单位手工缩放。
 范围公式只生成 `AxisValue.fixed/min/max/average` 与四则运算，引用同轴完整指标身份；
-不要拼接内部 ID 或任意平台公式。完整 API 见 widget-dsl-api.md §4.7.2。
+不要拼接内部 ID 或任意平台公式。完整 API 见 widget-dsl-styles.md §4.7.2。
 
 `LINE` 与柱状图族只有在分析线目标能唯一对应一个实际绘制的 `VALUE` 时才生成：
 
@@ -239,7 +239,7 @@ GAUGE 的专属配置直接跟在 `.chart().gauge()`（或具体仪表盘类型
 
 ## 4. 过滤映射
 
-常用交接操作符映射如下；组件完整算子、值类型与组合条件见 [过滤 API](widget-dsl-api.md#6-过滤上下文)：
+常用交接操作符映射如下；组件完整算子、值类型与组合条件见 [过滤 API](widget-dsl-contexts.md#6-过滤上下文)：
 
 | 交接对象操作符    | 生成结果                                          |
 |------------|-----------------------------------------------|
@@ -253,7 +253,7 @@ GAUGE 的专属配置直接跟在 `.chart().gauge()`（或具体仪表盘类型
 规则：
 
 - 保持交接对象中的过滤顺序
-- 参数以 `parameter("参数名")` 引用，先核实主题参数目录与类型；各算子参数类型见 `widget-dsl-api.md` §6。
+- 参数以 `parameter("参数名")` 引用，先核实主题参数目录与类型；各算子参数类型见 `widget-dsl-contexts.md` §6。
 - 如果某个操作符需要的参数形态超出当前支持范围，直接阻塞
 - schema 不明确的 widget 或 dashboard 自由过滤保持阻塞
 
@@ -361,40 +361,40 @@ TextItem.ofRichText("kpi", RichText.of()
 Model → dimension 私有 settings.categoryAxis → Bean 反读 → DSL 输出使用同一 placement；
 不写 widgetMeasures holder 或 viewAttr.left/right。ALL 对应 ellipsis；interval(n) 为非负整数原值透传。
 纵向 labelAlign 非 AUTO 时必须配置自定义 labelFont；自动标题填当前维度名且 modified=false。
-本期不含钻取。完整 API 与默认值见 widget-dsl-api.md §4.7.3。
+本期不含钻取。完整 API 与默认值见 widget-dsl-styles.md §4.7.3。
 
 ## 表格指标属性
 
-明细表的原始数值列使用 DimRef 目标与 `TableColor/TableShape`，判断源同样使用原始数值 DimRef；用法见 [widget-dsl-api.md §4.7.4](widget-dsl-api.md#474-表格指标属性)。
+明细表的原始数值列使用 DimRef 目标与 `TableColor/TableShape`，判断源同样使用原始数值 DimRef；用法见 [widget-dsl-styles.md §4.7.4](widget-dsl-styles.md#474-表格指标属性)。
 
 分组表/交叉表用 `tableColor/tableShape`，目标是已绑定 MeasureRef 或 `TableTarget.ALL_MEASURES`；固定样式用 `fixed`，判断字段用 `by`，即使规则为空也保留绑定。排名、平均值差、不一致或极值标志使用现有计算能力，属性只按数值区间标记；排序单独声明。最后命中规则生效，逐指标覆盖全部指标。
 不生成属性专属过滤接口；组件 `.filter()` 可能影响结果行和共享字段分组。指标形状 `baseStyle` 不提供未匹配兜底。
-维度使用 DimRef 目标与 `TableDimensionColor/TableDimensionShape`，按 `TableCondition` 显示文本条件标记；`otherwise` 提供颜色/形状兜底。明细表文本/日期列支持此配置。分组表/交叉表的 `tableDrill` 引用主题共享目录，三参数颜色/形状接口设置各层样式。完整 API 与边界见 widget-dsl-api.md §4.7.4。
+维度使用 DimRef 目标与 `TableDimensionColor/TableDimensionShape`，按 `TableCondition` 显示文本条件标记；`otherwise` 提供颜色/形状兜底。明细表文本/日期列支持此配置。分组表/交叉表的 `tableDrill` 引用主题共享目录，三参数颜色/形状接口设置各层样式。完整 API 与边界见 widget-dsl-styles.md §4.7.4。
 
 ## 表格合计行列映射
 
-分组表合计行使用 totalRows(TableTotal.rows()...build())；交叉表还支持 totalColumns(TableTotal.columns()...build())。总合计与组内合计分别映射 grand/subtotal，小计维度用 fields([DimRef]) 明确选择。位置对两类合计共同生效，样式分别使用 grandStyle/subtotalStyle。指标合计方式使用 totalBy(measure, TotalCalculation.X)，不得把「合计平均」误写成修改指标聚合 avg()。完整 API 见 [widget-dsl-api.md](widget-dsl-api.md)「分组表、交叉表合计行列」。
+分组表合计行使用 totalRows(TableTotal.rows()...build())；交叉表还支持 totalColumns(TableTotal.columns()...build())。总合计与组内合计分别映射 grand/subtotal，小计维度用 fields([DimRef]) 明确选择。位置对两类合计共同生效，样式分别使用 grandStyle/subtotalStyle。指标合计方式使用 totalBy(measure, TotalCalculation.X)，不得把「合计平均」误写成修改指标聚合 avg()。完整 API 见 [widget-dsl-core.md「分组表、交叉表合计行列」](widget-dsl-core.md#分组表交叉表合计行列)。
 
 ## 组件内边距
 
 用户要求组件留白、四边内边距或指标卡无内边距时，使用 chart 链的 padding(Padding.of()...build())。
 四边分别用 top/right/bottom/left；上下联动用 vertical，左右联动用 horizontal，全部为非负整数像素。
 只设置用户要求的边；四边清零用 vertical(0).horizontal(0)，恢复默认用空 Builder。
-适用于全部图表与三种表格。完整语句见 [Widget API](widget-dsl-api.md)「组件内边距」。
+适用于全部图表与三种表格。完整语句见 [Widget API](widget-dsl-styles.md#49-组件内边距图表与表格通用)「组件内边距」。
 
 ## 表格字体
 
 用户要求组件的表头/表身字体时，在三种表格的 chart 链使用 `tableFont(WidgetTableFont.of()...build())`；
 自动模式用 `WidgetTableFont.auto()`。表头对齐用 `TableTextFont.align`，表身维度/指标分别用
 `dimensionAlign/measureAlign`；未要求的属性省略以继承主题。仪表板全局字体仍用 TemplateStyle 的 TableFont。
-字号须使用 [Widget API](widget-dsl-api.md)「表格字体（组件样式）」列出的 18 个离散值，未指定时省略以继承主题；完整语句见该节。
+字号须使用 [Widget API](widget-dsl-encodings.md#表格字体组件样式)「表格字体（组件样式）」列出的 18 个离散值，未指定时省略以继承主题；完整语句见该节。
 
 ## 表格行高
 
 用户要求调整表头/表身行高或自动换行时，在三种表格的 chart 链使用
 `tableRowHeight(TableRowHeight.of().headerHeight(48).headerWrap(true).bodyHeight(100).bodyWrap(true).build())`。
 仅配置用户要求的部分；高度 16–200，默认 32，换行默认关闭。开启后高度为最大适应高度。
-完整语句见 [Widget API](widget-dsl-api.md)「表格行高（组件样式）」。
+完整语句见 [Widget API](widget-dsl-encodings.md#表格行高组件样式)「表格行高（组件样式）」。
 
 ## 表格格式
 
@@ -402,7 +402,7 @@ Model → dimension 私有 settings.categoryAxis → Bean 反读 → DSL 输出
 禁止展开收起交互使用 TableExpansion.DISABLED；允许交互时以 COLLAPSED / EXPANDED 指定初始状态。
 明细表用 frozenColumns(0) 关闭冻结，用 1–10 冻结前 n 列；分组/交叉表用 freezeDimensions。
 “显示总行数/总页数”用 TableFormat.totalRows/totalPages，合计行列继续使用 chart.totalRows/totalColumns。
-完整适用范围、默认值和示例见 [Widget API](widget-dsl-api.md)「表格格式（组件样式）」。
+完整适用范围、默认值和示例见 [Widget API](widget-dsl-encodings.md#表格格式组件样式)「表格格式（组件样式）」。
 
 ## 表格风格
 
@@ -413,11 +413,11 @@ Model → dimension 私有 settings.categoryAxis → Bean 反读 → DSL 输出
 宽度适应（显示全部列）用 `adaptive(TableAdaptive.FIT_WIDTH)`；省略即标准适应，三种表格均支持。
 自动主题色用 `themeColor("")` 或省略，透明用 `themeColor("transparent")`，具体色直接传颜色字符串。
 仪表板全局主题继续用 TemplateStyle；组件未声明风格、主题色时继承主题。
-完整语句见 [Widget API](widget-dsl-api.md)「表格风格（组件样式）」。
+完整语句见 [Widget API](widget-dsl-encodings.md#表格风格组件样式)「表格风格（组件样式）」。
 
 ## 组件背景
 
 图表与表格的标题背景用 `titleBackground(WidgetBackground.of()...build())`，
 组件背景用 `widgetBackground(...)`。模式选择 `color` / `image` / `style`；自动颜色用空字符串，
 自定义图片先上传，再引用附件 ID。圆角/边框仅放在组件颜色背景；内置样式编号按标题和组件分别解释。
-完整方法、样式名称及示例见 [Widget API](widget-dsl-api.md)「组件背景（图表与表格通用）」。
+完整方法、样式名称及示例见 [Widget API](widget-dsl-styles.md#411-组件背景图表与表格通用)「组件背景（图表与表格通用）」。

package/skills/finebi-cli-agent/references/scenario-workflows.md

@@ -20,7 +20,7 @@
 6. 对最终选定或新建的分析表调用 `analysis-ds.info` 确认主题归属、引擎类型和字段元数据。DIRECT 不以 `dataStatus`、`updateStatus` 或摘要 `usable` 阻断，不执行数据集 `data-update`，使用只读 `preview` 验证查询能力；SPIDER 保留状态、可用性和 preview 校验。
 7. 用 `subject.info` 和必要的 `widget.info` 确认已有组件引用。
 8. 对 Dashboard 按名称引用的组件，证明每个已有引用全局唯一，并证明待创建组件名称在创建前不存在冲突。
-9. 模型指标集不走数据集搜索。先从 `subject.info` 返回的 `resources.models` 查看摘要，再用 `model.search --subject-id <subjectId>` 遍历主题内候选，并对选定模型调用 `model.info --subject-id <subjectId> --id <modelId>` 获取指标、数据集字段和模型计算字段。若用户要求使用的指标集尚未属于主题，单独用 `public-ds.search` 确认唯一的 `type=METRIC_SET` 来源和目标主题可编辑性；执行 `model.add --subject-id <subjectId> --id <sourceId>` 后，使用响应中的主题内模型 ID 执行 `model.info` 回查，才可构建交接对象。来源 ID 不得传给 `model.info/delete` 或写进 DSL。模型目录命令未出现在实时 capability 时，既有 `widget dsl` 输出中的 `model(...)` 可作为只读证据；否则进入 `BLOCKED`。不得查询同名分析表后改写成 `model(...)`。
+9. 模型指标集按来源探查与主题内模型分别解析。仅探查来源或尚无主题时，用 `public-ds.search` 发现 `type=METRIC_SET` 来源，再以来源 ID 调用 `model.source-info`，读取字段目录与来源展示提示；判读边界见 [Model 工作流](command-workflows.md#76-model-metric-set)。生成制品时，先从 `subject.info` 返回的 `resources.models` 查看摘要，再用 `model.search --subject-id <subjectId>` 遍历主题内候选，并对选定模型调用 `model.info --subject-id <subjectId> --id <modelId>` 获取指标、数据集字段和模型计算字段。若用户要求使用的指标集尚未属于主题，确认唯一来源和目标主题可编辑性；执行 `model.add --subject-id <subjectId> --id <sourceId>` 后，使用响应中的主题内模型 ID 执行 `model.info` 回查，才可构建交接对象。来源 ID 不得传给 `model.info/delete` 或写进 DSL。模型目录命令未出现在实时 capability 时，既有 `widget dsl` 输出中的 `model(...)` 可作为只读证据；否则进入 `BLOCKED`。不得查询同名分析表后改写成 `model(...)`。
 
 不得把公共数据集 ID 当作 Analysis DS ID。物理 DSL 字段语义使用 `analysis-ds.info.name` 返回的表名和字段原始 `name`；模型 DSL 字段语义使用已确认的模型展示名和字段展示名。数据集、模型和字段 ID 仅作为可选验证证据，不进入 DSL。
 

package/skills/finebi-cli-agent/references/web-app.md

@@ -0,0 +1,13 @@
+# 生成动态 HTML 数据应用
+
+用户要求生成动态页面、HTML看板或FineBI Web应用时，先选择同一CLI安装的本地 `app create`，再按生成项目AGENTS.md开发。创建模板不需要连接；读取/绑定FineBI资源才检查认证和实时命令help。
+
+1. `finebi-cli app create --name <name> --path <parent>` 创建工程，不安装/运行/发布。
+2. 用dashboard search/info/data确认唯一来源、板内entryId、结果字段dId、真实控件filterName；样本仅用于理解和测试。
+3. 在public/app-config.json填写非敏感绑定。图表库和UI组件库按页面需求选择，默认实现及替换约定见生成项目的docs/design.md。请求、认证、解析复用模板src/finebi；业务代码按项目指南开发。
+4. `finebi-cli app inspect --path <project>`只校验本地配置，不能证明字段/权限在远端存在。按项目README配置开发身份，再安装、启动、测试与构建。
+5. 浏览器验收实际请求、空/错误/权限状态、图表与刷新；生产部署必须用访问者Cookie，不携带开发身份。
+
+内置CLI同样通过 `node "<skill-dir>/scripts/finebi-cli/src/index.js" app ...` 调用，不走动态业务runner。生产页面不调用CLI。禁止将开发时查到的业务数据或token写入HTML/JS/config；无筛选控件不能伪造服务端过滤。pageLimit不是分页，hasNext和warnings必须呈现。v1不提供发布上传/目录来源/服务端续页，先说明缺口，不发明命令。
+
+模板内置文本、单选/多选、数值选择、日期及日期区间、年月季度、年月区间和已配置时间标签；草稿统一应用，恢复默认与筛选空值分开。配置、状态、请求编码和代理校验共用 src/finebi/filters.js。数值范围、滑块、树/级联和动态候选项暂不支持，不得换成其他类型绕过检查。绑定前核实源控件类型和作用范围，候选项不得冒充完整数据。通用约定、完整支持矩阵、值格式及扩展步骤见生成项目 docs/filters.md。