@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guanvis/references/selector-reference.md

@@ -0,0 +1,431 @@
+## 筛选器参考
+
+本文是 GuanVis 页面筛选器的语义事实源，覆盖筛选器类型、创建与编辑、默认值、展示配置、联动、级联和页面放置。通用 Builder 方法索引仍见 `builder-reference.md`；checkout 工程的整体编辑与覆盖发布红线见 `checkout-editing.md`。
+
+这里的“页面筛选器”指作为独立资源进入页面筛选栏或画布的 selector；新建资源使用 `createSelector()` / `registerSelector()`，已有资源由 checkout 生成 `attachCard()` 脚本，具体可编辑范围见下文能力矩阵。它不是普通 Card 的 filters zone；卡片级筛选条件仍见 `api-reference.md` 的“卡片级筛选器 (Filters Zone)”。
+
+### 能力边界
+
+前端存在某类筛选器，不代表 GuanVis 已提供对应的新建或语义化编辑 DSL；按下表选择当前支持的操作。
+
+| 类型 | BI 标识 | GuanVis 当前能力 | 说明 |
+|---|---|---|---|
+| 离散值 | `DS_ELEMENTS` | 支持新建和 `attachCard()` 配置编辑 | 单选、多选、默认值和多种展示样式 |
+| 连续范围 | `DS_INTERVAL` | 支持新建和 `attachCard()` 配置编辑 | 默认使用 `BT` 区间条件 |
+| 日期 | `CALENDAR` | 支持新建和 `attachCard()` 配置编辑 | 支持日期粒度和固定日期区间 |
+| 快捷日期区间 | `TIME_MACRO` | 支持新建和 `attachCard()` 配置编辑 | 不绑定字段或数据集 |
+| 全局参数 | `PARAMETER` | 支持新建；已有同类型 selector 可更新参数绑定和通用配置 | 使用 `bindParameter(param(dpId), options)`，不走卡片联动 |
+| 条件筛选器 | `TEXT_MATCH` | 支持新建和 `attachCard()` 配置编辑 | 绑定单个字段，支持 8 种文本匹配操作符 |
+| 树状筛选器 | `TREE` | 支持新建和 `attachCard()` 专属配置编辑 | 固定层级，至少绑定同一数据集的两个有序字段；路径默认值使用二维数组 |
+| 层级树状筛选器 | `LAYER_TREE` | 支持新建和 `attachCard()` 专属配置编辑 | 绑定单个带 `layerTreeId` 的字段；`cdType=TREE_SELECTOR` |
+| 组合条件 | `COMBINATION` | 支持新建和 `attachCard()` 专属配置编辑 | 同一数据集绑定多个候选字段；默认条件可为空或只覆盖其中一部分 |
+| 自定义筛选器 | `CUSTOM_SELECTOR` | checkout 后可保留已有配置，暂不支持通用专属内容创建/编辑 | 依赖目标环境插件和不透明 `customConfig` |
+
+`TREE_SELECTOR`、`MERGE_SELECTOR` 和 `CUSTOM_SELECTOR` 等已有资源在 checkout/publish 时会保留原 `cdType` 和未修改配置。树状筛选器使用专属 `.setTreeSetting()` 编辑，层级树状筛选器使用 `.setLayerTreeSetting()` 编辑，组合条件筛选器使用 `.setCombinationSetting()` 编辑；其他类型不能调用普通 `setSelectorSetting()` 修改专属内容。需要修改暂未支持的专属内容时应报告暂不支持，禁止修改 `.guanvis/base/**` 或 `.guanvis/raw/**` JSON。
+
+### 类型选择
+
+- 离散文本或分类值（区域、类别、客户名等）使用 `DS_ELEMENTS`。
+- 连续数值（利润率、金额区间等）使用 `DS_INTERVAL`，默认展示起止输入框。
+- 精确日期或日期范围使用 `CALENDAR`，需要绑定日期字段。
+- 本月、上月、近 7 天等预设区间使用 `TIME_MACRO`，不绑定字段或数据集。
+- 控制计算字段或卡片参数表达式时使用 `PARAMETER`，先创建/同步全局参数，再按稳定 `dpId` 绑定。
+- 单字段需要等于、不等于、包含、开头或结尾等匹配条件时使用 `TEXT_MATCH`；默认操作符为 `CONTAINS`。
+- 固定字段层级（如区域 → 城市）使用树状筛选器，必须按父到子的顺序绑定至少两个字段。
+- 数据集字段已配置层级树时使用层级树状筛选器，绑定该单个字段；`schema.js` 中该字段必须带 `layerTreeId`，否则构建明确报错。
+- 多个同一数据集字段允许用户自由组合条件时使用组合条件筛选器；用 `.bindCombinationFields(...)` 声明可选字段，用 `.setCombinationSetting(...)` 设置展示和初始条件。
+- 用户要求自定义筛选器时，先对照上面的能力边界；当前没有对应创建/编辑 DSL 时明确报告暂不支持，不用其他筛选器类型模拟。
+
+### 文件、注册与页面归属
+
+筛选器脚本建议命名为 `selector_NN_xxx.js`。目录模式按 `schema.js` → `metrics.js` → `dynamic-parameters.js` → `theme-colors.js` → `card_*.js` → `selector_*.js` → `page.js` 执行，因此 selector 可以按联动目标序列引用先注册的 Card。
+
+```javascript
+var sel = createSelector("区域筛选")
+    .setId("s184352b7a76776db5f534df")
+    .bindField(f("区域"))
+    .linkToAll()
+    .build();
+
+registerSelector(sel);
+```
+
+每个 selector 必须设置由 `guanvis genid` 生成的 ID，并调用 `registerSelector(selector.build())` 或先 `.build()` 后注册。包含 selector 的资源包必须同时包含引用它的 Page：
+
+- 未被页面布局引用的 selector 默认进入页面筛选栏；也可用 `page.addFilterSelector(selectorId)` 显式控制顺序。
+- 作为画布内容或隶属于 Tab、CardGroup、SelGroup 的 selector 必须跟随对应布局放置，不再进入筛选栏。
+- 画布中的局部 selector 用 `.linkTo(...)` 明确联动所属区域，不默认 `.linkToAll()`。
+- selector 进入画布、布局组件或 SelGroup 时使用字符串 ID；`registerSelector()` 不参与普通 card 数字 index 计数。
+
+### SelectorBuilder 方法
+
+| 方法 | 说明 |
+|---|---|
+| `createSelector(name)` | 创建筛选器 |
+| `.setId(cardId)` | 设置固定资源 ID；新建 ID 用 `guanvis genid` 生成 |
+| `.setDescription(desc)` | 设置筛选器描述 |
+| `.setSelectorSetting(config)` | 统一配置入口，支持新建和能力矩阵中标记可编辑的 `attachCard()` selector |
+| `.setTreeSetting(config)` | 树状筛选器专属配置；新建和已有树状筛选器均可用 |
+| `.setLayerTreeSetting(config)` | 层级树状筛选器专属配置；新建和已有层级树状筛选器均可用 |
+| `.setCombinationSetting(config)` | 组合条件筛选器专属配置；可修改清空、展示与默认条件 |
+| `.setSelectorType(type)` | 设置类型；可新建 `DS_ELEMENTS`、`TEXT_MATCH`、`DS_INTERVAL`、`CALENDAR`、`TIME_MACRO`、`TREE`、`LAYER_TREE`、`COMBINATION`，`PARAMETER` 由 `bindParameter()` 自动设置 |
+| `.setFilterType(type)` | 设置筛选条件；`DS_ELEMENTS` 默认 `IN`，`DS_INTERVAL`/`CALENDAR` 默认 `BT` |
+| `.setFilterLevel(level)` | 设置筛选级别；默认 `FilterLevel.DETAIL`，`PARAMETER` 不支持 |
+| `.bindDataset(dsId)` | 显式绑定数据集；单数据集工程通常由字段自动确定 |
+| `.bindField(field)` | 绑定筛选字段；`DS_ELEMENTS`、`DS_INTERVAL`、`CALENDAR` 必填 |
+| `.bindTreeFields(...fields)` | 按父到子顺序绑定树状筛选器的至少两个字段 |
+| `.bindLayerTreeField(field)` | 绑定层级树状筛选器的单个字段；字段必须带 `layerTreeId` |
+| `.bindCombinationFields(...fields)` | 绑定组合条件筛选器的候选字段；必须属于同一数据集且不能是聚合或窗口计算 |
+| `.bindParameter(paramRef, options?)` | 绑定全局参数；已有 `PARAMETER` selector 可原地更新绑定、继承方式和本地默认值 |
+| `.setGranularity(granularity)` | 设置 `CALENDAR` 的唯一日期粒度 |
+| `.setGranularityOptions(options, defaultGranularity?)` | 设置 `CALENDAR` 可选粒度和默认粒度 |
+| `.setTimeMacroOptions(options, defaultMacroName?)` | 兼容入口；设置快捷日期选项并自动切为 `TIME_MACRO` |
+| `.setMultiSelect(bool)` | 设置 `DS_ELEMENTS` 是否多选 |
+| `.setDefaultType(type)` | 设置 `FIRST_PICK`、`FIXED_VALUE` 或 `ALL` |
+| `.setDefaultAll()` | 设置默认全部，即不筛选 |
+| `.setDefaultValue(values, displayValues?)` | 设置固定默认值，并切换为 `FIXED_VALUE` |
+| `.setDefaultDateRange(start, end, displayValues?)` | 设置 `CALENDAR` 固定日期区间 |
+| `.setFirstPickLink(bool)` | `FIRST_PICK` 模式下是否联动刷新 |
+| `.setDisplayType(type)` | 设置 `DS_ELEMENTS` 展示样式 |
+| `.setShowSelectAll(bool)` | 设置 `DS_ELEMENTS` 是否显示全选 |
+| `.setCanClear(bool)` | 设置是否允许清空 |
+| `.linkTo(cardIndex, targetFieldNameOrMappings?)` | 联动指定图表；组合条件和带路径树状筛选器可传 `{源字段: 目标字段}` 完整映射 |
+| `.linkToSelector(selectorId, targetFieldName?)` | 联动指定 selector，构建时校验目标类型和级联环 |
+| `.linkToAll()` | 按同名字段联动所有可联动图表、MetricChart 和杜邦子卡片 |
+| `.build()` | 构建并触发验证 |
+
+推荐优先使用 `.setSelectorSetting()`。旧的 `.setSelectorType()`、`.setMultiSelect()`、`.setDefaultValue()` 等方法继续兼容。资源身份、字段/参数绑定和联动具有独立生命周期，仍分别使用 `.setId()`、`.bindField()` / `.bindParameter()` 和 `.linkTo*()`。
+
+### 统一配置 `setSelectorSetting()`
+
+所有字段都可选；`false`、`0` 和允许的空数组按显式值处理。新建 selector 未设置的字段采用 GuanVis 默认值；能力矩阵中标记可编辑的 `attachCard()` selector 只修改显式字段，未传字段保持线上原值。
+
+```javascript
+{
+    type: SelectorType.DS_ELEMENTS,
+    filterType: FilterType.IN,
+    filterLevel: FilterLevel.DETAIL,
+    selection: {
+        multiple: true,
+        showSelectAll: true,
+        canClear: false,
+        firstPickLink: false
+    },
+    display: {
+        type: SelectorDisplay.SEARCH_BOX,
+        showColumnName: true
+    },
+    defaultValue: {
+        type: SelectorDefaultType.FIXED_VALUE,
+        values: ["华东"],
+        displayValues: ["华东地区"]
+    },
+    calendar: {
+        granularities: [Granularity.MONTH, Granularity.QUARTER],
+        defaultGranularity: Granularity.MONTH
+    },
+    timeMacro: {
+        options: [{ name: "最近7天", expr: ["LAST_7_DAY"] }],
+        defaultName: "最近7天"
+    }
+}
+```
+
+适用规则：
+
+- `selection.multiple`、`selection.showSelectAll` 和 `display.type` 仅用于 `DS_ELEMENTS`。
+- `TEXT_MATCH` 的 `filterType` 仅支持 `EQ`、`NE`、`CONTAINS`、`NOT_CONTAINS`、`STARTSWITH`、`NOT_STARTSWITH`、`ENDSWITH` 和 `NOT_ENDSWITH`；其默认值仅使用字符串 `values`，不使用 `type` 或 `displayValues`。
+- `calendar` 仅用于 `CALENDAR`；`timeMacro` 仅用于 `TIME_MACRO`。
+- `defaultValue.values` 会切换为 `FIXED_VALUE`；`displayValues` 必须与 `values` 同次传入。
+- `TIME_MACRO` 和 `PARAMETER` 不接受通用 `filterType`、`defaultValue` 或 `firstPickLink` 配置。
+- 已有 selector 传入的 `type` 是类型断言，不能借此改变 selector 类型，也不会重新绑定字段。
+- `display.showColumnName` 对应 BI 内容中的 `display.showColName`；`selection.canClear` 对应 `props.canClear`。
+
+### 已支持类型示例
+
+#### 离散值 `DS_ELEMENTS`
+
+```javascript
+var sel = createSelector("区域筛选")
+    .setId("s184352b7a76776db5f534df")
+    .bindField(f("区域"))
+    .setSelectorSetting({
+        selection: { multiple: true, showSelectAll: true, canClear: false },
+        display: { type: SelectorDisplay.SEARCH_BOX, showColumnName: true },
+        defaultValue: {
+            type: SelectorDefaultType.FIXED_VALUE,
+            values: ["华东"]
+        }
+    })
+    .linkToAll()
+    .build();
+
+registerSelector(sel);
+```
+
+`SelectorDisplay` 可用值：`SEARCH_LIST`、`SEARCH_BOX`、`CHECKBOX`、`RADIO`、`BUTTON_GROUP`。不设置时根据 `multiple` 自动选择。
+
+#### 条件筛选器 `TEXT_MATCH`
+
+```javascript
+var sel = createSelector("客户关键字")
+    .setId("a184352b7a76776db5f534df")
+    .bindField(f("客户名称"))
+    .setSelectorSetting({
+        type: SelectorType.TEXT_MATCH,
+        filterType: FilterType.CONTAINS,
+        filterLevel: FilterLevel.DETAIL,
+        selection: { canClear: false },
+        display: { showColumnName: true },
+        defaultValue: { values: ["观远"] }
+    })
+    .linkToAll()
+    .build();
+
+registerSelector(sel);
+```
+
+`TEXT_MATCH` 默认操作符为 `CONTAINS`，默认值是字符串数组；传空数组表示页面打开时没有预填文本。它不支持多选、全选、展示样式、首项默认值或默认显示值。
+
+#### 组合条件 `COMBINATION`
+
+```javascript
+var condition = createSelector("经营条件")
+    .setId("d184352b7a76776db5f534df")
+    .setSelectorType(SelectorType.COMBINATION)
+    .bindCombinationFields(f("区域"), f("城市"), f("销售额"))
+    .setCombinationSetting({
+        selection: { canClear: false },
+        display: {
+            type: CombinationSelectorDisplay.STANDARD,
+            showColumnName: true
+        },
+        defaultValue: {
+            conditions: [
+                Combination.and(
+                    Combination.condition(f("区域"), FilterType.IN, ["华东"]),
+                    Combination.or(
+                        Combination.condition(f("城市"), FilterType.EQ, ["上海"]),
+                        Combination.condition(f("销售额"), FilterType.GE, [100000])
+                    )
+                )
+            ]
+        }
+    })
+    .linkTo(0, {
+        "区域": "销售区域",
+        "城市": "销售城市",
+        "销售额": "含税销售额"
+    })
+    .build();
+registerSelector(condition);
+```
+
+`bindCombinationFields(...)` 是页面上允许用户选择的候选字段集合，默认 `conditions` 可以是 `[]`，也可以只使用其中一部分；不会强制每个候选字段都出现在默认条件中。`Combination.condition(field, filterType, filterValue, { not: true }?)` 创建叶子条件，其中 `not` 省略时为 `false`，传入时必须为布尔值；`Combination.and(...)` / `Combination.or(...)` 创建嵌套分组，最多 5 层、共 200 个叶子条件。候选字段必须来自同一数据集，且不能是动态参数、聚合计算或窗口计算。
+
+筛选器联动则必须为每个候选字段提供可用映射，否则用户在运行时选到未映射字段会使目标卡片无法正确过滤。`.linkTo(index, mappings)` 中 `mappings` 的键可使用源字段名或 `fdId`，值可使用目标字段名或 `fdId`；显式映射必须覆盖全部候选字段。`.linkToAll()` 只连接能按同名字段完整映射的图表，自动跳过缺少任一候选字段的目标。组合条件筛选器不支持 `linkToSelector()` 级联。
+
+#### 树状筛选器
+
+```javascript
+var tree = createSelector("区域城市")
+    .setId("b184352b7a76776db5f534df")
+    .setSelectorType(SelectorType.TREE)
+    .bindTreeFields(f("区域"), f("城市"))
+    .setTreeSetting({
+        selection: { multiple: true, canClear: false },
+        display: { type: TreeSelectorDisplay.FLAT, showExclude: true, showConfirm: true },
+        defaultValue: {
+            paths: [["华东", "上海"]],
+            displayPaths: [["东区", "上海市"]]
+        },
+        path: { withPath: true, autoMergePath: true }
+    })
+    .build();
+
+registerSelector(tree);
+```
+
+树状筛选器会生成独立的 `cdType=TREE_SELECTOR`，不是普通 `SELECTOR`。`defaultValue.paths` / `displayPaths` 都是路径二维数组；默认值模式只支持 `FIXED_VALUE` 与 `FIRST_PICK`。`TreeSelectorDisplay` 可用 `SEARCH_BOX` 和 `FLAT`；`showConfirm`、`showExclude` 仅多选可用（平铺时可显式切换确认按钮）。路径配置为 `path.withPath`、`anyPathEnabled`、`excludeNullValue`、`autoMergePath`；其中任意层选择只适用于带路径单选，末级空值缩略只适用于不带路径，多选路径合并只适用于带路径多选。`filterLevel` 仅可用于不带路径模式。
+
+不带路径的树状筛选器可以使用 `.linkTo()` / `.linkToAll()` 按末级字段联动图表。带路径树状筛选器的选择值包含完整路径，需用 `.linkTo(cardIndex, { 源层级字段: 目标字段, ... })` 为每一级提供映射；映射的键和值均可写字段名或 `fdId`，且必须覆盖全部绑定层级。`.linkToAll()` 只会联动同时拥有全部同名层级字段的图表；不会降级成仅按末级字段联动。带路径树状筛选器暂不支持 `.linkToSelector()`。
+
+#### 层级树状筛选器
+
+```javascript
+var layerTree = createSelector("组织层级")
+    .setId("c184352b7a76776db5f534df")
+    .setSelectorType(SelectorType.LAYER_TREE)
+    .bindLayerTreeField(f("组织"))
+    .setLayerTreeSetting({
+        selection: { multiple: true, canClear: false },
+        defaultValue: {
+            paths: [["100", "200"]],
+            displayPaths: [["事业群", "运营部"]]
+        }
+    })
+    .linkToAll()
+    .build();
+registerSelector(layerTree);
+```
+
+层级树状筛选器同样生成 `cdType=TREE_SELECTOR`，但与树状筛选器不同：`source` 只有 `field`，没有 `fieldSeq`；绑定字段的 `layerTreeId` 由 `guanvis init` 写入可选字段元数据。数据集没有这个字段，或所绑字段没有 `layerTreeId` 时，构建会报错，不能用普通树状筛选器替代。`defaultValue.paths` 是节点 ID 的二维路径数组；GuanVis 自动补齐前端需要的层级标记，`displayPaths` 可选，未传时由节点 ID 生成显示值。它只支持多选、清空与默认路径配置，不支持树状筛选器的展示、路径模式或 `filterLevel` 配置。可按该字段使用 `.linkTo()` / `.linkToAll()` 联动图表。
+
+#### 连续范围 `DS_INTERVAL`
+
+```javascript
+var sel = createSelector("利润率筛选")
+    .setId("h61d8bf256952ef3fcf961c5")
+    .setSelectorType(SelectorType.DS_INTERVAL)
+    .bindField(f("利润率"))
+    .linkToAll()
+    .build();
+
+registerSelector(sel);
+```
+
+`DS_INTERVAL` 默认 `filterType="BT"`，展示起止输入框。需要单值或比较条件时可显式设置支持的 `FilterType`，不要用 `DS_ELEMENTS` 枚举连续数值。
+
+#### 日期 `CALENDAR`
+
+```javascript
+var sel = createSelector("日期筛选")
+    .setId("abc123def456abc123def456")
+    .setSelectorType(SelectorType.CALENDAR)
+    .bindField(f("订单日期"))
+    .setDefaultDateRange("2026-01-01", "2026-01-31")
+    .linkToAll()
+    .build();
+
+registerSelector(sel);
+```
+
+固定默认值必须有两个日期端点，支持 `2026-01-15`、`2026-01`、`2026-Q1`、`2026-W03`、`2026` 等格式。同一默认值数组必须使用相同粒度；未显式配置粒度时会从默认值或联动目标字段推断。
+
+#### 快捷日期区间 `TIME_MACRO`
+
+```javascript
+var sel = createSelector("快捷日期")
+    .setId("gf7a7ed51ec7c9477fcd1d81")
+    .setSelectorSetting({
+        type: SelectorType.TIME_MACRO,
+        timeMacro: {
+            options: [
+                { name: "今天", expr: ["TODAY"] },
+                { name: "昨天", expr: ["YESTERDAY"] },
+                { name: "最近7天", expr: ["LAST_7_DAY"] },
+                { name: "最近30天", expr: ["LAST_30_DAY"] },
+                { name: "本月", expr: ["MONTH_TO_DAY"] },
+                { name: "上月", expr: ["LAST_MONTH"] },
+                { name: "本年", expr: ["YEAR_TO_DAY"] }
+            ],
+            defaultName: "最近7天"
+        }
+    })
+    .linkToAll()
+    .build();
+
+registerSelector(sel);
+```
+
+`TIME_MACRO` 不绑定字段或数据集，通过目标卡片中的日期字段自动匹配。省略 `defaultName` 时默认选中第一项；显式传入 `defaultName: null` 时页面打开不选择默认项。内置宏还包括 `LAST_14_DAY`、`LAST_90_DAY`、`LAST_1_YEAR`、`LAST_WEEK`、`WEEK_TO_DAY`、`YEAR_TO_DAY`、`DAY_BEFORE_YESTERDAY`、`WEEK_TO_YESTERDAY`、`MONTH_TO_YESTERDAY`、`YEAR_TO_YESTERDAY`、`QUARTER_TO_DAY`、`QUARTER_TO_YESTERDAY`、`YEAR_TO_LAST_MONTH` 和 `YEAR_TO_LAST_QUARTER`。
+
+#### 全局参数 `PARAMETER`
+
+参数先通过 `guanvis parameter` 创建或更新，并生成/刷新 `dynamic-parameters.js`；脚本按稳定 `dpId` 引用，不按名称猜测。
+
+```javascript
+var sel = createSelector("区域参数")
+    .setId("bbbbbbbbbbbbbbbbbbbbbbbb")
+    .bindParameter(param("aaaaaaaaaaaaaaaaaaaaaaaa"), {
+        inheritParent: true
+    })
+    .setCanClear(false)
+    .build();
+
+registerSelector(sel);
+```
+
+参数筛选器不绑定数据集或字段，也不调用 `linkTo()` / `linkToAll()`；参数值通过 `dpId` 影响引用该全局参数的计算与卡片。需要覆盖参数本地默认值时显式关闭继承：
+
+```javascript
+.bindParameter(param("aaaaaaaaaaaaaaaaaaaaaaaa"), {
+    inheritParent: false,
+    defaultValue: ["华东", "华南"]
+})
+```
+
+### 联动与级联
+
+筛选器通过 `settings.asFilter` 联动图表：
+
+- `.linkTo(index, targetFieldName?)` 中 index 是过滤后的可联动目标序列：普通图表和 MetricChart 按注册/布局顺序进入，文本、图片和自定义图表等不可联动资源不占序号，杜邦子卡片追加在末尾。
+- `.linkToAll()` 按同名字段联动所有普通图表、MetricChart 和杜邦子卡片，不自动包含其他 selector。
+- 同一 selector 同时使用显式 `.linkTo(index, "目标字段")` 和 `.linkToAll()` 时，显式目标字段映射优先。
+- checkout 后的普通 `cdType=SELECTOR` 筛选器使用 `attachCard().addLink()`、`.removeLink()`、`.clearLinks()` 增量修改联动，不把有顺序的联动增删混进 `.setSelectorSetting()`；这些联动方法不支持 `TREE_SELECTOR`、`CUSTOM_SELECTOR` 等其他 selector 类型。
+
+筛选器级联使用 `.linkToSelector(selectorId, targetFieldName?)`：
+
+```javascript
+var city = createSelector("市")
+    .setId("bbbbbbbbbbbbbbbbbbbbbbbb")
+    .bindField(f("市"))
+    .build();
+registerSelector(city);
+
+var province = createSelector("省")
+    .setId("aaaaaaaaaaaaaaaaaaaaaaaa")
+    .bindField(f("省"))
+    .linkToSelector("bbbbbbbbbbbbbbbbbbbbbbbb")
+    .linkToAll()
+    .build();
+registerSelector(province);
+```
+
+当前级联目标只支持离散值筛选器和树状筛选器；构建时会校验目标存在、目标字段映射和 selector 级联成环。目标为 `ALL` 或空默认值时会自动启用 `FIRST_PICK + firstPickLink`，目标已有固定默认值时保留。上游字段与目标数据集字段不同名时，给 `.linkToSelector()` 传第二个参数。
+
+### Checkout 与 `attachCard()` 编辑
+
+能力矩阵中标记可编辑的已有 selector 使用 checkout 生成的 `attachCard(cardId, jsonPath)` 原地编辑：
+
+```javascript
+registerCard(
+    attachCard("bbbbbbbbbbbbbbbbbbbbbbbb", "selector.json")
+        .setSelectorSetting({
+            selection: { canClear: false },
+            display: { showColumnName: true }
+        })
+        .addLink("cccccccccccccccccccccccc")
+        .build()
+);
+```
+
+`attachCard().build()` 返回的是 attached-card 结果，因此使用 `registerCard()` 注册；只有 `createSelector().build()` 的结果使用 `registerSelector()`。
+
+编辑规则：
+
+- `.setSelectorSetting()` 只修改显式配置，保留未修改内容及未知扩展字段。
+- `selection.canClear` 和 `display.showColumnName` 是可编辑的 selector 配置；未知字段的保留是 checkout 往返兼容原则，不表示 GuanVis 声明支持其产品语义。
+- 已有 selector 的 `type` 只能用于断言，禁止原地改变类型或借配置入口重新绑定字段。
+- 已有 `PARAMETER` selector 是绑定规则的例外：可用 `.bindParameter()` 原地更新参数、`inheritParent` 和本地默认值；不能把其他类型转换成参数 selector。
+- `setSelectorSetting()` 仅用于新建 selector 和能力矩阵中标记可编辑的已有类型。`TEXT_MATCH` 可原地修改文本操作符、筛选级别、默认文本、`canClear` 和列名显示；树状筛选器使用 `.setTreeSetting()` 原地修改多选、清空、树展示、默认路径和路径选项；层级树状筛选器使用 `.setLayerTreeSetting()` 原地修改多选、清空与默认路径；组合条件筛选器使用 `.setCombinationSetting()` 原地修改 `canClear`、展示和默认条件，但保留 `source.fieldSeq`、`dsInfo` 及未知扩展字段，不重新绑定候选字段。自定义筛选器等其他类型仍只能保留原配置。
+- 任何已有 selector 都必须保留原 cdId 原地发布，禁止删除后重建同名资源。
+
+### 页面放置与筛选器组
+
+selector 可以作为字符串 ID 放入页面画布、Tab、CardGroup 或 SelectorGroup。SelectorGroup 本身是 Page 布局组件，不是 selector 资源；其创建、样式、画布/筛选栏归属、移动操作和完整示例统一见 `builder-reference.md` 的 `PageBuilder` 与 `SelectorGroupBuilder` 章节。
+
+### 验证与常见错误
+
+| 问题 | 处理 |
+|---|---|
+| selector 未设置 ID | 用 `guanvis genid` 生成并调用 `.setId()` |
+| selector 未联动任何图表 | 全局筛选器调用 `.linkToAll()`；局部筛选器调用 `.linkTo(index)` |
+| 连续数值生成了大量离散选项 | 改用 `DS_INTERVAL` |
+| `TIME_MACRO` 绑定了字段或数据集 | 删除字段/数据集绑定，只保留时间宏配置和联动 |
+| `PARAMETER` 调用了图表联动 | 删除 `linkTo*`，确认目标卡片通过同一 `dpId` 使用参数 |
+| `display.type` 用在非 `DS_ELEMENTS` | 删除该配置；其他类型使用自身展示规则 |
+| checkout 编辑试图改变 selector 类型或字段 | 保留原类型和绑定；确需改变时创建新资源并由用户明确处理替换关系 |
+| 条件 selector 使用 `IN`、`BT` 或默认显示值 | 改用 8 种文本匹配操作符；默认值仅传字符串 `values` |
+| 树状筛选器调用普通配置 API | 树状筛选器改用 `.setTreeSetting()`；层级树状筛选器改用 `.setLayerTreeSetting()`；组合条件筛选器改用 `.setCombinationSetting()`；自定义筛选器仍只能保留原配置 |
+| selector 没有进入 Page | 在筛选栏、画布或 SelGroup 中引用，并与 Page 同包发布 |

package/skills-bundle/guanvis/references/tableau-migration.md

@@ -0,0 +1,73 @@
+## Tableau 迁移 Checklist
+
+从 Tableau 迁移仪表板到观远BI时，必须按以下清单逐项检查：
+
+### 迁移前
+
+1. **解析 Tableau 仪表板结构**：用 `tableau-skill db <file> <dashboard_name> -f json` 获取完整结构
+2. **识别所有交互元素**：Dashboard JSON 中 `IsFilter=true` 的 zone 是筛选器，`IsParam=true` 的 zone 是参数控件
+3. **识别计算字段**：用 `tableau-skill calc <file> -f json` 获取所有计算字段，判断迁移策略
+
+### 筛选器翻译（必做）
+
+Tableau 仪表板上的 filter zone 必须翻译为观远的 `createSelector()`：
+
+| Tableau FilterMode | 观远 Selector 配置 |
+|---|---|
+| `typeinlist` / `typeinmulti` | `setMultiSelect(true)` + `setDisplayType(SelectorDisplay.SEARCH_BOX)` |
+| `typeinsingle` | `setMultiSelect(false)` + `setDisplayType(SelectorDisplay.SEARCH_LIST)` |
+| 日期范围筛选 | `.setSelectorType(SelectorType.CALENDAR)` 或 `.setSelectorType(SelectorType.DS_INTERVAL)` |
+| 相对日期筛选（Relative date） | `.setTimeMacroOptions([{ name: "最近7天", expr: ["LAST_7_DAY"] }, ...])` |
+| 数值范围筛选（利润率、金额等连续值） | `.setSelectorType(SelectorType.DS_INTERVAL)`（默认 BT 区间，起始值-结束值输入框） |
+| 数值精确筛选 | `.setSelectorType(SelectorType.DS_INTERVAL).setFilterType("EQ")` |
+
+**关键**：连续数值字段（如利润率、折扣率、金额等）**必须**使用 `DS_INTERVAL`，不要用 `DS_ELEMENTS`（列表选择会列出所有离散值，对连续数值没有意义）。
+
+所有 selector 必须调用 `.linkToAll()` 实现联动。
+
+### 计算字段迁移决策树
+
+| Tableau 计算类型 | 观远实现方式 | 说明 |
+|---|---|---|
+| 行级计算（如 `利润/销售额`） | **数据集计算字段**（`guands dataset calc-field add`） | 所有卡片和筛选器都能引用，推荐 |
+| 聚合计算（如 `SUM(利润)/SUM(销售额)`） | **卡片级 calcField** | 仅在单个卡片内有效 |
+| LOD 表达式（FIXED/INCLUDE/EXCLUDE） | **ETL** 或 **卡片级 window calcField** | 需要根据具体语义判断 |
+| 原生高级计算（Running Total、Rank） | **原生 advCalc builder** | 优先用 `runningTotal.*` / `rank.*`，不要手写 window calcField |
+| 其他表计算 | **卡片级 window calcField** | 当前无原生 builder 时再用 `calculationType: "window"` |
+| 多表 JOIN + 计算 | **ETL**（guanetl） | 需要先合表再计算 |
+
+**重要**：如果需要在筛选器中引用计算字段（如"利润率"筛选器），必须使用**数据集计算字段**而非卡片级 calcField，因为 selector 只能绑定数据集上的物理字段。
+
+### calcField 命名规则
+
+- calcField 的 name **不能与数据集已有字段同名**，否则观远BI会报 warning 并默认取数据集字段
+- 如果数据集已有"利润率"字段，卡片级 calcField 应命名为"利润率_agg"或"利润率_calc"等
+- `pack`/`publish` 时的验证会自动检查重名并输出 warning
+
+### 无法迁移内容的处理（必做）
+
+如果有无法 1:1 迁移的 Tableau 元素，**必须**在页面最底部添加一个全宽文本卡片说明：
+
+```javascript
+var note = createTextCard("迁移说明")
+    .setId("<genid>")
+    .addMarkdown(
+        "---\n" +
+        "### Tableau 迁移说明\n\n" +
+        "本页面从 Tableau 工作簿 `<workbook_name>` 的 `<dashboard_name>` 迁移而来。\n\n" +
+        "**未迁移的内容：**\n" +
+        "- <列出未迁移项及原因>\n\n" +
+        "**与原始 Tableau 的差异：**\n" +
+        "- <列出差异>\n"
+    );
+registerTextCard(note.build());
+
+// 在 page.js 中将说明卡片放在最底部
+page.addFullWidthCard(<noteCardIndex>, 3);
+```
+
+需要说明的典型内容：
+- Tableau 参数控件（观远用筛选器替代）
+- LOD 表达式的近似实现
+- 颜色/格式的差异
+- 交互行为的差异（如 Tableau 的 highlight action）

package/skills-bundle/guanvis/references/theme.md

@@ -0,0 +1,123 @@
+## 仪表板主题
+
+`preview` / `pack` / `publish` 会自动给新建页面与卡片注入主题，决策顺序如下：
+
+1. **`<dir>/themes/.preference.json`** — 用户/AI 主动写入的意图（`themeId` 优先，缺失再用 `keywords` 在 `.index.json` 上匹配；命中后 `themeId` 会被回写到 `.preference.json`）
+2. **`<dir>/themes/.applied.json`** — 上一次成功 `pack`/`publish` 明确选用的项目级线上主题（用于改版自动继承；本次回退到 skill 自带 `simple.json` 时**不写**该文件）
+3. **skill 自带 `simple.json`** — 兜底（embed 在二进制里，**不联网、不会失败**）
+
+`guanvis checkout` 是例外：线上 Page 的完整 `meta.theme` 只保存在
+`.guanvis/base/page.json`，不会写成项目级 `.applied.json`。未明确切换主题时，每个
+checkout Page 独立恢复自己的线上主题，新卡片继承所属 Page 的主题；旧页面没有
+`meta.theme`（缺失、`null` 或空对象）也是有效状态，新卡片不会被注入内置简约主题。
+项目里已有的 `.preference.json` 仍代表用户明确切换主题，优先级高于 checkout base。
+
+AI 选择主题时不要把租户主题列表里的默认“浅色”/“深色”当作候选：这两套主题没有特殊样式。若除了“浅色”/“深色”外没有合适主题，不写主题偏好或执行 `theme preference --clear`，让解析落到 skill 内置“简约”（`simple.json`），不要为了命中而从列表里随便挑一个。
+
+兜底覆盖的失败场景（任意一种发生都会平滑退到 simple.json，命令不会因主题问题中断）：
+- 新建工程目录下没有 `themes/`、或 `.preference.json` 缺失（checkout 工程会优先保留 base 页面原状）
+- `.preference.json` 里的 `themeId` 在租户线上 list 中不存在 / `Sync` 失败 / 当前命令本来就不联网
+- `keywords` 在 `.index.json` 上没有任何命中
+- `.applied.json` 引用的 `themeId` 本地快照已被删除（applied 步骤**只读本地、不再发起 sync**）
+
+执行命令时 stderr 会打印决策结果。命中线上主题时形如 `Theme: <name> [<id>] (source=preference|applied)`；落到自带兜底时形如 `Theme: 简约 (source=built-in simple.json)`（内置默认与 BI 默认主题对齐，属正常行为而非降级），特意不打印 themeId 是因为那只是 skill 与 BI 默认值对齐的实现细节，不是租户主题列表里能查到的 ID。built-in 横幅只在 `pack`/`publish` 打印；`preview`/`diff` 是高频只读命令，落到兜底时不再重复打印（命中真实主题时仍会打印）。
+
+普通数据集图表和指标平台 MetricChart 都会应用主题视觉配置。MetricChart 只注入 `settings` 与 `meta.chartMain.props`：透视表补表格/合计样式，柱线饼等补坐标轴、图例、数据标签和主题色；不会修改 `zoneData`、`dsInfo`、`defaultView` 等查询相关字段。
+
+### 何时主动操作
+
+> 所有 `theme *` 子命令的 **`[dir]` 可省**，缺省为当前工作目录；下面的示例假设你已经 `cd` 到 dashboard 工程目录。
+
+- **用户描述风格**（如"深色科技风" "蓝色简约"）：
+
+  ```bash
+  guanvis theme preference --keywords "深色 科技" --sync
+  ```
+
+  - `--keywords` 按 **空格 / 英文逗号 `,` / 中文逗号 `，`** 切分；命中分数最高者，平局取 `.index.json` 中**靠前**的条目（不区分 `themeType`）。AI 不应把默认“浅色”/“深色”作为关键词目标或手动指定的候选；命中后会把 `themeId` 写回 `.preference.json`，让 preview/pack/publish 后续都稳定指向同一主题。
+  - `--sync` 写入偏好后立刻拉一次 `/api/theme-setting/list` 落盘到 `themes/<id>.json` + `.index.json` + `.sync-meta.json`，让随后的 preview/pack 在离线状态也能看到真实主题。
+
+- **用户给出明确的 themeId**：
+
+  ```bash
+  guanvis theme preference --theme-id custom_blue
+  ```
+
+  themeId 需为单个「安全文件名」片段：`[A-Za-z0-9_-]`、长度 ≤32，且不能含 `/`、`\`、子串 `..`；否则 CLI 会拒绝，sync 也会跳过并打 stderr 警告。
+
+- **改版（不重提风格）**：普通工程由 `.applied.json` 沿用上次项目主题；checkout 工程按 Page base 保留各自线上主题。
+- **换风格**：再跑一次 `theme preference` 即可；下一次 `pack`/`publish` 实际使用新主题时 `.applied.json` 会自动覆盖。
+- **没有合适主题**：不要选择默认“浅色”/“深色”，也不要从列表里随便挑；保持无偏好或执行 `theme preference --clear`，使用内置“简约”兜底。
+- **回到默认状态**：`guanvis theme preference --clear` 会**同时**删除 `.preference.json` 和 `.applied.json`。新建工程下次运行会使用内置 `simple.json`；checkout 工程会优先恢复 `.guanvis/base/page.json` 记录的线上主题或“无主题”状态，避免清除偏好反而改坏已有页面。
+
+### 离线 vs 联网
+
+| 命令 | 是否联网 | 说明 |
+|---|---|---|
+| `preview` / `pack` | **不联网** | 只读 `themes/`，缺主题文件直接退到 skill 自带 `simple.json`（不会因弱网失败） |
+| `publish` | 按需 | 选定的 `themeId` 缺主题文件时调一次 list；list 失败则退到 `simple.json` + 警告，不阻塞发布 |
+| `theme preference --sync` / `theme sync` | 是 | 强制刷新；网络失败仅打 warning，不会损坏既有 `themes/` 内容 |
+
+> 想让 `preview` 看到与 `publish` 一致的主题，**先**跑 `theme preference --sync` 或 `theme sync`，再 `preview`。
+
+### `themes/` 目录文件说明
+
+| 文件 | 作用 | 是否入库 |
+|---|---|---|
+| `<themeId>.json` | 单主题快照（list 单条原文，含 `themeSettings`） | 推荐入库（diff 友好） |
+| `.preference.json` | 用户/AI 偏好 | 入库 |
+| `.applied.json` | 上次记录的线上主题 | 入库 |
+| `.index.json` | `themeId/themeName/themeType` 索引，供 keywords 匹配 | 入库 |
+| `.sync-meta.json` | `syncedAt`、条目数 | 可选 |
+
+不要直接手改 `<themeId>.json`——每次 `sync` 会原子覆盖；要改就改 `.preference.json`。
+
+### 排错
+
+- `theme show` 打印当前决策（`source` / `themeId` / `themeName` / `themeType`），只读。
+- `theme list` 列出 `.index.json` 中候选；`.index.json` 缺失时提示先 `sync`。
+- 看到 `Theme: 简约 (source=built-in simple.json)` 但用户期望非简约：检查 `.preference.json` 是否写好、对应 `themes/<id>.json` 是否存在；如果是 keywords 路径，跑 `theme list` 看候选名字是否真的包含关键词；联网命令还要看 stderr 是否打印了 `theme: sync failed: ...`。
+- 看到 `multi-subdir project under <root> contains per-subdir themes/ in [...]`：你在多子目录工程的**根目录**直接跑了 preview/pack/publish，但子目录里有自己的 `themes/`。按提示 `cd` 进每个子目录单独执行；或如果不想用各子目录的主题，删除子目录下的 `themes/` 后再回到根目录运行。
+
+## 设计规则
+
+`preview` / `pack` / `publish` 会自动应用内置设计规则。需要覆盖默认视觉规则时，在工程目录新建 `design-rule.json`，不要手改 `themes/<themeId>.json`。
+
+`design-rule.json` 只用于两类配置：
+
+- `componentDefaults`：卡片静态默认规则，用于统一项目内同类卡片的默认布局与样式，不属于主题覆盖。
+- `themePatch`：仅用于主题已开放的配置，例如页面背景、标题样式、主题色等；卡片自身的专属属性不放在这里。
+
+数据格式不放在 `design-rule.json` 里，数值/百分比格式由字段类型与图表区域规则自动处理。
+
+示例：
+
+```json
+{
+  "schemaVer": 1,
+  "componentDefaults": {
+    "SINGLE_VALUE": {
+      "singleValueSetting": {
+        "alignment": "left",
+        "fontStyle": {
+          "size": 28
+        }
+      }
+    },
+    "KPI_CARD": {
+      "secondKpiSetting": {
+        "valueAlign": "right"
+      }
+    }
+  },
+  "themePatch": {
+    "cardTitle": {
+      "style": {
+        "fontSize": 14
+      }
+    }
+  }
+}
+```
+
+非法字段会被忽略并打印 warning，不要依赖未支持的配置项。

package/skills-bundle/guanvis/references/troubleshooting.md

@@ -0,0 +1,25 @@
+## Troubleshooting（常见错误 → 修复方法）
+
+| 错误信息 | 原因 | 修复方法 |
+|---|---|---|
+| `zone metric: field count N exceeds max 1` | BASIC_COLUMN/BAR/LINE 只支持 1 个 metric | 改用 GROUPED_COLUMN/MULTI_LINE（支持多 metric），或拆成多个卡片 |
+| `zone row: field count N exceeds max 1` | 组合图（*_WITH_LINE）row maxCount=1 | 减少 row 字段到 1 个，或改用非组合图类型 |
+| `missing required zone: metric` | 卡片没有添加 metric 字段 | 调用 `.addMetric(f("字段名"))` |
+| `calcField name 'X' conflicts with dataset physical field` | calcField 与数据集字段同名 | 重命名 calcField，如加 `_calc` 后缀 |
+| `Calculated field missing name` | calcField 没有指定 name | 使用 `calcField("名称", "公式")` 格式 |
+| `Field 'X' not found in dataset` | 字段名拼写错误或数据集中不存在 | 检查 schema.js 中的字段名，确保完全匹配 |
+| `unknown chart type 'X'` | ChartType 枚举值错误 | 使用 `ChartType.XXX` 常量，不要手写字符串 |
+| `auth: ...` / `401` | Token 过期或 profile 错误 | 运行 `guancli auth status`，必要时重新 `auth login` |
+| `run scripts: ...ReferenceError` | JS 脚本中引用了未定义的变量 | 检查是否使用了 `new XxxBuilder()` 而非工厂函数 `createXxx()` |
+| `registerXxx() received a 'yyy' build result — use registerYyy(...) instead` | 注册函数与工厂函数错配（最常见：自定义图表误用 `registerCard`） | 按提示换成配对的注册函数，如 `createCustomChart` → `registerCustomChart(chart.build())` |
+| 自定义图表发布后渲染空白 | SDK 模式脚本没调 `new GDPlugin().init(renderChart)`；或 ECHARTS_LITE 脚本误用 `GDPlugin`/没给 `option` 赋值 | 对照 `evals/custom_chart_sdk/`（SDK）或 `evals/custom_chart_echarts/`（ECHARTS_LITE）模板检查渲染脚本入口 |
+| 自定义图表数值显示 `0.86%` 而非 `86%` | 没确认字段量纲就写格式化逻辑 | 先 `guancli ds preview <dsId>` 看真实数据，0~1 小数才需要 ×100 |
+| `placeCard index out of range` | placeCard 的 cardIndex 超出已注册卡片数量 | 检查 registerCard/registerTextCard 的调用顺序和总数 |
+| `page has no cards` | page.js 中没有 placeCard | 确保 page.js 中为每个已注册的卡片调用了 placeCard |
+| `selector not linked to any card` | selector 没有调用 linkTo/linkToAll | 添加 `.linkToAll()` 或 `.linkTo(cardIndex)` |
+| `Theme: 简约 (source=built-in simple.json)` 但用户要求别的风格 | 偏好缺失 / themeId 在环境中不存在 / sync 失败 / keywords 没命中 | `theme list` 看候选 → `theme preference --theme-id ...` 或 `--keywords ... --sync`；联网命令注意 stderr 是否有 `theme: sync failed: ...` |
+| publish 后 `.applied.json` 没更新 | 本次实际用的就是 skill 自带 `simple.json`（按设计 fallback 不写 applied） | 检查 stderr 的 `theme: ... falling back ...` 警告；确保对应 `themes/<id>.json` 存在或先 `theme sync` |
+| `invalid themeId "..." (...)` | themeId 不是合法的单段文件名（见 `publish-and-constraints.md` 中的约束） | 使用 `theme list` 里出现的 id；避免 `/`、`\`、`..`；或用 `theme preference --keywords` |
+| `theme: keywords "..." matched no theme` | 关键词与候选 themeName 没有公共子串 | `theme list` 核对候选名字；调整 keywords，或换成 `--theme-id` |
+| `Inherited from checkout base (线上资源原有问题，不阻断发布)` + ⚠ 列表 | checkout 的线上卡片本身带有不完整数据（缺 dsInfo、字段属性残缺等），未被本次 DSL 修改触碰 | 无需处理即可发布；如果要顺手修复线上数据质量，再针对 ⚠ 项做对应 DSL 修改 |
+| `payload validation failed with N error(s)` 且错误只出现在 ✗ 列表 | 本工程 DSL 操作引入的真实错误（继承自 base 的问题只会进 ⚠ 列表） | 按 ✗ 逐项修复 card_*.js / page.js |