@guandata/guanvis 0.1.36 → 0.1.37

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## @guandata/guanvis 0.1.37 - 2026-08-07
+
+- 发布前新增字段 `fdId` 线上活性校验，提前发现无效字段绑定，降低发布失败风险。
+- 完善筛选器配置，支持更完整的筛选设置与组合使用场景。
+- 优化页面布局及组合图配置，提升图表构建与导出结果的稳定性。
+- 补充构建器、图表属性、指标图表和编辑流程文档，改善使用体验。
 ## @guandata/guanvis 0.1.36 - 2026-08-04
 
 - 扩展仪表板标题、页面背景、筛选栏、卡片组、Tab 和分区的视觉配置，支持字体、颜色、图标、背景图、间距与分割线。

package/README.md

@@ -54,6 +54,12 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.37
+
+- 完善筛选器、页面布局和组合图配置，仪表板搭建更灵活。
+- 增强字段绑定校验，减少图表配置错误。
+- 优化图表属性和页面导出配置，提升生成结果的稳定性。
+
 ### @guandata/guanvis 0.1.36
 
 - 扩展仪表板标题、页面背景、筛选栏、卡片组、Tab 和分区的视觉配置，支持字体、颜色、图标、背景图、间距与分割线。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanvis",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "description": "观远 BI Card/Page 生成工具 - 通过 JS DSL 创建图表和仪表板",
   "bin": {
     "guanvis": "bin/run.js"

package/skills/guanvis/SKILL.md

@@ -23,7 +23,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 - 已有线上仪表板用 `guanvis checkout <pgId> -d <dir>` 拉成可编辑工程（attachCard 基线、自定义图表 `charts/` 反编译、Pro 模板 `templates/`、Page 布局脚本）。checkout 工程只用于修改指定 Page，不用于复制新 Page；只支持普通仪表板（pgType=PAGE），DSL 不能安全表达的结构会直接失败而不是清结构。**checkout 工程动手前先读 `references/checkout-editing.md`**。
 - **Checkout 账号红线**：checkout 读到的是"当前账号视角"，publish 整体回写。必须用对涉及数据集有**完整列权限、无脱敏限制**的账号（推荐 owner 或管理员）执行 checkout/publish，否则被裁剪的字段会在回写后从线上卡片永久丢失；多语言租户操作账号语言须与卡片原始语言一致。
 - **Checkout JSON 红线**：`.guanvis/raw/**`、`.guanvis/base/**`、`.guanvis/manifest.json` 是只读快照。Agent 不得修改这些 JSON，也不得复制 checkout JSON 改副本创建新资源；现有卡片修改必须通过 `attachCard(...)` 的 DSL 操作表达（优先 `update*/patch*/add*/remove*/move*`，整 zone 重建的 `set*/clear*` 会触发 warning），新增卡片必须用 `createCard()` / `createSelector()` 工厂函数；操作清单见 `references/checkout-editing.md` §3。
-- Card/Page 描述也是 JS 源文件的一部分：新建看板或改版时，在 `card_*.js` / `page.js` 中写 `.setDescription(...)`，再通过 `preview`/`pack`/`publish` 从 JS 源文件生成并发布资源。
+- Card/Page 描述也是 JS 源文件的一部分：新建资源未设置非空业务描述时，payload 描述使用 `[guanvis:created]` 标记创建来源，Page 不会因此打开描述展示；调用 `.setDescription(...)` 设置非空业务描述后只保留业务描述，不追加标记。attach/checkout 已有资源不补标记。新建看板或改版时，在 `card_*.js` / `page.js` 中写 `.setDescription(...)`，再通过 `preview`/`pack`/`publish` 从 JS 源文件生成并发布资源。
 - 写脚本前先形成 dashboard contract：目标用户、业务问题、使用的数据集、核心指标、维度拆解、筛选器、页面结构和验证方式。
 - 每次生成都针对明确目录或明确子目录；不要把 unrelated 示例、旧包或临时 ZIP 混入同一个发布目标。
 - Card/Page/Selector 的 `.setId(...)` 必须用 `guanvis genid` 生成（保证字母开头）；数字开头 ID 会触发 BI 前端 CSS selector 语法错误，新建资源校验直接报 error 拦截（checkout/attach 的已有资源保留原 ID 不受限）。
@@ -34,7 +34,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 
 ## AI Quick Reference（速查，详细说明见按需参考资料）
 
-**Checkout/attachCard 速记**：`attachCard(cardId, jsonPath)` 是"base JSON + 链式 DSL 操作 = 目标 JSON"，不修改 base JSON，重复执行产出相同 payload。zone 修改优先 `update*/patch*/add*/remove*/move*`（整 zone 重建的 `set*/clear*` 会触发 warning）；已有 selector 用 `.addLink()/.removeLink()/.clearLinks()` 改联动；自定义图表内容编辑仅限 SDK/ECHARTS_LITE（编辑 `charts/` 下反编译源文件），COMPLEX_REPORT/PLUGIN/PLUGIN_LITE/REPORT_FORM 调内容编辑 API 直接报错。发布前用 `guanvis diff <dir>` 或 preview 的 `changeSummary` 查看影响面；没有 DSL 操作覆盖的需求先扩展 DSL，不改 `.guanvis` JSON。完整操作语义（zone/筛选区/筛选栏画布互移等）见 `references/checkout-editing.md` §3。
+**Checkout/attachCard 速记**：`attachCard(cardId, jsonPath)` 是"base JSON + 链式 DSL 操作 = 目标 JSON"，不修改 base JSON，重复执行产出相同 payload。zone 修改优先 `update*/patch*/add*/remove*/move*`（整 zone 重建的 `set*/clear*` 会触发 warning）；已有 selector 用 `.setSelectorSetting()` 修改筛选器配置，用 `.addLink()/.removeLink()/.clearLinks()` 修改联动，禁止借配置入口改变 selector 类型或重新绑定字段；自定义图表内容编辑仅限 SDK/ECHARTS_LITE（编辑 `charts/` 下反编译源文件），COMPLEX_REPORT/PLUGIN/PLUGIN_LITE/REPORT_FORM 调内容编辑 API 直接报错。发布前用 `guanvis diff <dir>` 或 preview 的 `changeSummary` 查看影响面；没有 DSL 操作覆盖的需求先扩展 DSL，不改 `.guanvis` JSON。完整操作语义（zone/筛选区/筛选栏画布互移等）见 `references/checkout-editing.md` §3。
 
 **字段显示名与 Card 标题**：`createCard()` 第二参数是 Card 标题，与字段显示名独立。图例/轴标题/表头/Tooltip/指标标签都用字段显示名，需要与物理字段名或 calcField 内部名分开时设置 `alias`（如 `f("营收", { alias: "本月营收" })`）；`SINGLE_VALUE`/`KPI_CARD`/`KPI_TREND` 和仪表盘/进度类尤其明显。
 
@@ -49,8 +49,8 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 7. **calcField 命名**：不能与数据集物理字段同名，否则 BI 默认取数据集字段
 8. **calcField 类型**：`aggregation`（默认）公式必须含聚合函数；纯算术用 `{ calculationType: "normal" }`；窗口函数用 `{ calculationType: "window" }`
 9. **明细/滚动表 calcField**：`DETAIL_TABLE`/`SCROLL_TABLE` 只逐行展示，行级计算必须 `{ calculationType: "normal" }` 且禁用聚合/窗口函数；汇总需求改用非明细图表或 ETL 预计算
-10. **联动/下钻**：新建筛选器联动图表必须 `.linkToAll()` 或 `.linkTo(cardIndex)`；已有筛选器用 `attachCard(...).addLink()/.removeLink()/.clearLinks()`；筛选器级联用 `.linkToSelector(selectorId, targetFieldName?)`；卡片联动卡片用 `card.linkTo(layoutCardIndex, { fields: [{ source, target }] })`；固定路径下钻用 `registerDrillPath(parentCardIndex, [child.build()], { position: DrillPathPosition.BOTTOM })`；详细规则见 `references/builder-reference.md`
-11. **selector 类型**：离散值 → `DS_ELEMENTS`（默认）；连续数值 → `SelectorType.DS_INTERVAL`；日期 → `CALENDAR`；快捷日期区间（本月/近7天等）→ `.setTimeMacroOptions(options)`
+10. **筛选器/联动/下钻**：新建和已有筛选器配置优先用 `.setSelectorSetting()`；新建筛选器联动图表必须 `.linkToAll()` 或 `.linkTo(cardIndex)`，已有筛选器用 `attachCard(...).addLink()/.removeLink()/.clearLinks()`；筛选器级联用 `.linkToSelector(selectorId, targetFieldName?)`；卡片联动卡片用 `card.linkTo(layoutCardIndex, { fields: [{ source, target }] })`；固定路径下钻用 `registerDrillPath(parentCardIndex, [child.build()], { position: DrillPathPosition.BOTTOM })`；详细规则见 `references/builder-reference.md`
+11. **selector 类型**：离散值 → `DS_ELEMENTS`（默认）；连续数值 → `SelectorType.DS_INTERVAL`；日期 → `CALENDAR`；快捷日期区间（本月/近7天等）→ `.setSelectorSetting({ type: SelectorType.TIME_MACRO, timeMacro: { options, defaultName } })`（旧 `.setTimeMacroOptions()` 仅保留兼容）
 12. **同环比默认**：未指定输出值时默认增长率；未指定模式时默认 `ComparativeMode.FILTER_BASED`（普通模式需显式 `NORMAL`）。日期字段已是预聚合周期字段（如 `月开始日期`）时必须声明 `{ granularity: Granularity.NONE }`，避免按 DAY 筛选窗口计算为空
 13. **placeCard 入参**：优先用 card/selector ID 字符串（checkout 工程与子目录工程必须用），如 `placeCard("cardId", x, y, w, h)`。数字 index 仅限新建工程，按可布局资源（registerCard/MetricChart/TextCard/ImageCard/CustomChart/DuPontChart）的注册顺序累加，文件按文件名排序加载；**registerSelector 不参与 card index 计数**——selector 进画布/布局组件一律用其 ID 字符串。
 14. **publish 认证**：由底层 CLI 负责——guancli 先 `guancli auth use <profile>`，guancli-lite 用环境变量

package/skills/guanvis/references/builder-reference.md

@@ -1,5 +1,7 @@
 ## Builder API 参考
 
+新建 Card/Page 未设置非空业务描述时，payload 描述使用 `[guanvis:created]` 标记创建来源；设置非空业务描述后只保存业务描述，不追加标记。attach/checkout 已有资源不补标记，Page 只有创建标记时不会打开描述展示。
+
 ### CardBuilder
 
 | 方法 | 说明 |
@@ -24,8 +26,10 @@
 | `.setSplitSetting(config)` | 拆分图配置 |
 | `.setColorByColors(preset_or_config)` | 渐变色配置 |
 | `.setBarSetting(config)` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
+| `.setWaterfallSetting(config)` | 瀑布图的正负值颜色和累计值配置 |
 | `.setShapeColorType(type)` | 图形填充配置 |
 | `.setLineSetting(config)` | 折线显示配置 |
+| `.setComboSetting(config)` | 组合图的显示方式、折线或符号样式配置 |
 | `.setCardSetting(config)` | 卡片背景、主题跟随、内边距和内容间距 |
 | `.setShowTitle(show)` / `.setCardTitleStyle(config)` | 卡片标题显隐和样式配置 |
 | `.setShowLegend(show, position?)` / `.setChartLegend(config)` | 图例配置 |
@@ -165,7 +169,9 @@ attachCard(CARD_ID, BASE_PATH)
 | `.setDataLabel()` / `.setMetricAdditionalDataLabel()` | 数据标签配置 |
 | `.setAxis()` / `.setAuxiliaryLine()` / `.setTooltip()` | 坐标轴、辅助线和工具提示配置 |
 | `.setLineSetting()` | 折线显示配置 |
+| `.setComboSetting()` | 组合图的显示方式、折线或符号样式配置 |
 | `.setBarSetting()` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
+| `.setWaterfallSetting()` | 瀑布图的正负值颜色和累计值配置 |
 | `.setPieSetting()` / `.setPieCenterText()` | 饼图配置 |
 | `.setTableSetting()` / `.setTableCellMerge()` / `.setGrandTotal()` | 表格行为、视觉样式与汇总配置 |
 | `.setSplitSetting()` / `.setShapeColorType()` | 拆分图和图形填充配置 |
@@ -407,7 +413,7 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.setDashboardTitle(enabled, options?)` | 开启/关闭仪表板标题，并设置标题文字、字体、背景、图标、高度和下边距；未传 `title` 时默认使用 Page 名称 |
 | `.setExportView(enabled, config?)` | 开启/关闭导出视图；`config.mode` 决定使用分页方向还是单页宽度 |
 | `.setWidthAdaptive(enabled, width?)` | 开启/关闭宽度自适应；默认宽度 1280 |
-| `.setLayoutSetting(config)` | 设置 `page.meta.layoutSetting`。多次调用深度合并 |
+| `.setLayoutSetting(config)` | 设置 `page.meta.layoutSetting`；布局类型使用 `PageLayoutType` |
 | `.build()` | 构建 |
 
 `setDashboardTitle()` 的 `options`：
@@ -445,7 +451,14 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `sourceType` | `ImageSourceType.OUTSIDE_LINK` / `LOCAL_IMAGE` |
 | `renderType` | `ImageRenderType.RATIO` / `STRETCH` / `FIT_TO_CONTENT` |
 
-#### 导出视图与宽度自适应
+#### 页面布局类型、导出视图与宽度自适应
+
+```javascript
+page.setLayoutSetting({ layoutType: PageLayoutType.WATERFALL });
+page.setLayoutSetting({ layoutType: PageLayoutType.RESPONSIVE });
+```
+
+`PageLayoutType` 支持 `WATERFALL`（瀑布流）和 `RESPONSIVE`（自适应）；也可以传 `null` 恢复默认布局。
 
 ```javascript
 // 多页导出：orientation 默认 ExportOrientation.VERTICAL
@@ -467,7 +480,7 @@ page.setWidthAdaptive(true, 1600);
 
 `setExportView()` 以 `mode` 为唯一判断依据。未传 `mode` 时默认 `ExportViewMode.MULTI_PAGE`；多页模式只读取 `orientation`，缺失或非法时使用 `ExportOrientation.VERTICAL`；单页模式只读取 `width`，缺失或非法时使用 827。传入与当前模式不匹配的 `width` / `orientation` 会被忽略并产生 warning。
 
-`setWidthAdaptive(true, width)` 的 `width` 会先静默四舍五入，再校验是否位于 `800 ~ 4096`；缺失或非法时使用 1280。宽度自适应不能与 `layoutType: "responsive"` 同时开启，但可以与导出视图同时开启。
+`setWidthAdaptive(true, width)` 的 `width` 会先静默四舍五入，再校验是否位于 `800 ~ 4096`；缺失或非法时使用 1280。宽度自适应不能与 `PageLayoutType.RESPONSIVE` 同时开启，但可以与导出视图同时开启。
 
 #### 页面布局与卡片视觉
 
@@ -850,6 +863,7 @@ registerPage(page.build());
 |------|------|
 | `createSelector(name)` | 创建筛选器 |
 | `.setId(cardId)` | 设置固定资源 ID（同 CardBuilder） |
+| `.setSelectorSetting(config)` | 修改筛选器配置，支持新建和 `attachCard()`；完整结构见下方示例 |
 | `.setSelectorType(type)` | 筛选器类型：`SelectorType.DS_ELEMENTS`（列表选择，默认）、`DS_INTERVAL`（数值范围）、`CALENDAR`（日期）、`TIME_MACRO`（快捷日期区间）、`PARAMETER`（全局参数，由 `bindParameter` 自动设置） |
 | `.setFilterType(type)` | 筛选条件：`DS_INTERVAL` 默认 `"BT"`（区间），`DS_ELEMENTS` 默认 `"IN"`。可用值参见 `FilterType` 枚举 |
 | `.bindDataset(dsId)` | 绑定数据集（可选，单数据集场景自动绑定） |
@@ -872,6 +886,42 @@ registerPage(page.build());
 | `.linkToAll()` | 自动联动所有普通图表卡片、MetricChart 和杜邦子卡片（按同名字段匹配） |
 | `.build()` | 构建（触发验证） |
 
+推荐优先使用统一配置入口，旧的 `.setSelectorType()`、`.setMultiSelect()`、`.setDefaultValue()` 等方法继续兼容。资源身份、数据绑定和联动具有独立生命周期，仍分别使用 `.setId()`、`.bindField()` / `.bindParameter()` 和 `.linkTo*()`；已有筛选器联动使用 `attachCard().addLink()/removeLink()/clearLinks()`。
+
+`setSelectorSetting(config)` 的结构如下。所有字段都可选；`false`、`0` 和允许的空数组都会按显式值处理，未传字段在 `attachCard()` 模式下保持线上原值：
+
+```javascript
+{
+    type: SelectorType.DS_ELEMENTS,
+    filterType: FilterType.IN,
+    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/showSelectAll` 和 `display.type` 仅用于 `DS_ELEMENTS`；`calendar` 仅用于 `CALENDAR`；`timeMacro` 仅用于 `TIME_MACRO`。`defaultValue.values` 会切换为 `FIXED_VALUE`。已有筛选器传入的 `type` 是类型断言，不能借此把筛选器改成另一种类型，也不会重新绑定字段或参数。
+
 **使用示例**：
 
 ```javascript
@@ -879,7 +929,10 @@ registerPage(page.build());
 var sel = createSelector("区域筛选")
     .setId("s184352b7a76776db5f534df")
     .bindField(f("区域"))
-    .setMultiSelect(true)
+    .setSelectorSetting({
+        selection: { multiple: true, showSelectAll: true, canClear: false },
+        display: { type: SelectorDisplay.SEARCH_BOX }
+    })
     .linkToAll()
     .build();
 registerSelector(sel);
@@ -917,15 +970,21 @@ registerSelector(sel);
 // selector_03_timemacro.js — 快捷日期（TIME_MACRO）
 var sel = createSelector("快捷日期")
     .setId("gf7a7ed51ec7c9477fcd1d81")
-    .setTimeMacroOptions([
-        { 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"] }
-    ], "最近7天")
+    .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);
@@ -963,7 +1022,7 @@ registerSelector(province);
 - **离散值**（区域、类别、客户名等文本字段）→ `DS_ELEMENTS`（默认），配合 `setDisplayType` 选择展示样式
 - **连续数值范围**（利润率、金额区间等）→ `SelectorType.DS_INTERVAL`，默认区间输入（起始值-结束值）
 - **日期选择**（精确日期范围）→ `SelectorType.CALENDAR`，需要 `bindField` 绑定日期字段。默认会从联动目标卡片推断日期粒度；如需固定月/季度等粒度，可用 `.setGranularity(Granularity.MONTH)` 或 `.setGranularityOptions([...], default)`
-- **快捷日期区间**（本月/上月/近7天等预设区间）→ `.setTimeMacroOptions(options, default)`，不需要 `bindField`，自动匹配目标卡片日期字段联动。`default` 传 `null` 表示无默认值
+- **快捷日期区间**（本月/上月/近7天等预设区间）→ `.setSelectorSetting({ type: SelectorType.TIME_MACRO, timeMacro: { options, defaultName } })`，不需要 `bindField`，自动匹配目标卡片日期字段联动。`defaultName` 传 `null` 表示无默认值；旧 `.setTimeMacroOptions()` 仅保留兼容
 
 **联动机制**：筛选器通过 `settings.asFilter` 配置联动关系。`linkTo(cardIndex)` 会自动构建 `columnMappings`，将筛选器字段映射到目标卡片的同名字段；cardIndex 只统计普通图表、MetricChart 和杜邦子卡片，文本/图片等不可联动资源不占序号。`linkToSelector(selectorId, targetFieldName?)` 用于筛选器联动筛选器，目标必须是已注册的 DS_ELEMENTS/TREE 筛选器，构建时会检查 selector 级联成环；目标为 ALL/空默认值时会自动改为 `FIRST_PICK + firstPickLink`，目标已有固定默认值时保留用户设置。`linkToAll()` 会自动匹配所有普通图表卡片、MetricChart 和杜邦子卡片中的同名字段，不自动包含筛选器。若同一个筛选器同时写了 `linkTo(index, "自定义字段")` 和 `linkToAll()`，显式 `linkTo` 的目标字段映射优先。
 

package/skills/guanvis/references/chart-properties.md

@@ -948,6 +948,91 @@ attachCard(CARD_ID, BASE_PATH)
 
 堆积面积图和百分比堆积面积图使用 `skipNulls`、`opacity`、`showPoint`、`pointShape`、`pointSize`、`showAsSpline` 和 `lineStyle`。
 
+## 组合图
+
+### `setComboSetting(config)`
+
+设置组合图的显示方式、折线或符号样式。
+
+通用属性：
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `swapYShape` | boolean | 是否交换主图形和叠加图形 |
+
+折线组合图支持 `GROUPED_COLUMN_WITH_LINE` 和 `STACKED_COLUMN_WITH_LINE`：
+
+```javascript
+.setComboSetting({
+    swapYShape: true,
+    line: {
+        skipNulls: true,
+        showPoint: true,
+        pointShape: "ring",
+        pointSize: 6,
+        showAsSpline: true,
+        lineStyle: "Solid_2"
+    }
+})
+```
+
+`line` 支持的属性：
+
+| 属性 | 类型/取值 | 说明 |
+|---|---|---|
+| `skipNulls` | boolean | 是否在空值处断开 |
+| `showPoint` | boolean | 是否显示数据点 |
+| `pointShape` | `"default"` / `"dot"` / `"ring"` | 混合图形、实心圆或空心圆 |
+| `pointSize` | `5` / `6` / `8` | 数据点大小 |
+| `showAsSpline` | boolean | 是否显示为曲线 |
+| `lineStyle` | `"Solid_1"` / `"Solid_2"` / `"Solid_3"` / `"Dash_2"` | 细实线、中实线、粗实线或虚线 |
+
+符号组合图支持 `GROUPED_COLUMN_WITH_SYMBOL` 和 `STACKED_COLUMN_WITH_SYMBOL`：
+
+```javascript
+.setComboSetting({
+    symbol: {
+        symbols: ["circle", "diamond", "square", "triangle", "triangle-down"],
+        symbolSize: 8
+    }
+})
+```
+
+`symbol` 支持的属性：
+
+| 属性 | 类型/取值 | 说明 |
+|---|---|---|
+| `symbols` | 1～20 个 string | 可使用 `circle`、`diamond`、`square`、`triangle`、`triangle-down` 或有效的 `http(s)` 图片地址 |
+| `symbolSize` | 4～20 的整数 | 符号大小 |
+
+`swapYShape` 可以单独设置，也可以与 `line` 或 `symbol` 一起设置；`line` 与 `symbol` 不能同时配置。`attachCard()` 只修改显式传入的字段。
+
+## 瀑布图
+
+### `setWaterfallSetting(config)`
+
+设置 `WATERFALL_COLUMN` 的正负值颜色和累计值：
+
+```javascript
+.setWaterfallSetting({
+    upColor: "#FD7F76",
+    downColor: "#69BFA8",
+    showSum: true,
+    sumName: "累计值",
+    sumColor: "#4379CE"
+})
+```
+
+| 属性 | 类型 | 说明 |
+|---|---|---|
+| `upColor` | 非空 string / `null` | 正值颜色；`null` 使用默认颜色 |
+| `downColor` | 非空 string / `null` | 负值颜色；`null` 使用默认颜色 |
+| `showSum` | boolean | 是否显示累计值 |
+| `sumName` | 非空 string / `null` | 累计值名称；`null` 使用“累计值” |
+| `sumColor` | 非空 string / `null` | 累计值颜色；`null` 使用默认颜色 |
+
+该方法支持普通卡片、指标卡片和 `attachCard()`；多次调用或 attach 更新都只合并显式传入的属性。配置颜色指标时，正负值颜色由颜色指标决定；累计值配置仍然生效。
+
 ## 柱形图与条形图
 
 ### `setBarSetting(config)`

package/skills/guanvis/references/checkout-editing.md

@@ -25,7 +25,8 @@ checkout 读到的是"当前账号视角"的卡片定义，publish 会把它整
 - **通用操作**：已有卡片可继续串接常用 `createCard` 后续操作，包括标题/描述（`setName`/`setDescription`）、`setRawSettings`、图例/标签/坐标轴/表格/拆分等视觉设置。
 - **Zone 操作按链式顺序真实执行**：`addRow/addMetric/...` 追加字段；`insertMetric(index, field)` 插入；`removeMetric(selector)` 删除字段并保守清理其它 zone 中同字段引用；`moveMetric(selector, index)` 调整顺序；`updateMetric(selector, patch)` / `patchMetric(...)` 修改已有字段属性并保留未设置字段配置。`setRows/setMetrics/...` 和 `clearRows/clearMetrics/...` 是整 zone 重建，不会继承被替换字段的格式，并会在验证时提示 warning——默认优先用 `update*/patch*/add*/remove*/move*`。
 - **自定义图表内容编辑**：仅限 subType 为 **SDK / ECHARTS_LITE**。checkout 自动反编译出 `charts/<cdId>.js`（含内嵌资源抽取），card JS 里 `attachCard(...).loadContent("charts/<cdId>")`；也可用 `.setScript()/.setHtml()/.setCss()/.setLibs()/.addLib()` 内联修改。COMPLEX_REPORT（走 Pro 流程）、PLUGIN/PLUGIN_LITE（事实源是插件市场资源）、REPORT_FORM（填报模板配置）调用这些内容编辑 API 会直接报错，不要对它们生成此类修改；详见 `builder-reference.md` 自定义图表章节。
-- **已有 selector 联动**：用 `.addLink(cardIdOrIndex, targetFieldName?)` / `.removeLink(cardIdOrIndex)` / `.clearLinks()` 叠加修改现有 `settings.asFilter`，不要反向改 JSON。
+- **已有 selector 配置**：用 `.setSelectorSetting()` 修改筛选器配置；禁止原地改变 selector 类型或重新绑定字段/参数。完整配置结构和适用规则见 `builder-reference.md` 的 SelectorBuilder 章节。
+- **已有 selector 联动**：用 `.addLink(cardIdOrIndex, targetFieldName?)` / `.removeLink(cardIdOrIndex)` / `.clearLinks()` 叠加修改现有 `settings.asFilter`，不要把有顺序的联动增删混进 `.setSelectorSetting()`，也不要反向改 JSON。
 - **Page 快捷筛选区**：按有序操作执行——`setFilterLayout` 整体设置，`clearFilterLayout` 清空，`addFilterLayoutItem` 追加去重，`insert/remove/moveFilterSelector` 局部调整；筛选栏布局、名称/控件/按钮字体、控件风格、按钮色、背景色和背景图用 `setFilterPanelLayout()`。省略字段保留 base，显式 `null` 删除对应覆盖并恢复产品/主题默认。
 - **筛选器在筛选栏和画布间移动**：优先用动作级 API：`moveFilterSelectorToCanvas(selectorId, x, y, w, h)` / `moveCanvasSelectorToFilter(selectorId, index?)`；筛选器组用 `moveSelectorGroupToCanvas(group, x, y, w, h)` / `moveCanvasSelectorGroupToFilter(group, index?)`。
 - **新增卡片**必须使用 `createCard()` / `createSelector()` 等工厂函数（新建资源 ID 用 `guanvis genid` 生成）。

package/skills/guanvis/references/metric-chart-reference.md

@@ -184,8 +184,10 @@ registerMetricChart(card.build());
 | `.setPieSetting(obj)` / `.setPieCenterText(obj)` | 设置饼图属性 |
 | `.setSplitSetting(obj)` | 设置拆分图属性 |
 | `.setBarSetting(obj)` | 设置柱形图/条形图的柱体宽度、间距和圆角；详细字段见 `chart-properties.md` |
+| `.setWaterfallSetting(obj)` | 设置瀑布图的正负值颜色和累计值；详细字段见 `chart-properties.md` |
 | `.setShapeColorType(type)` | 设置图形填充 |
 | `.setLineSetting(obj)` | 设置折线显示 |
+| `.setComboSetting(obj)` | 设置组合图的显示方式、折线或符号样式；详细字段见 `chart-properties.md` |
 | `.setAuxiliaryLine(obj)` | 设置辅助线 |
 | `.setGrandTotal(obj)` | 设置透视表/分组表行列总计及样式；字段小计通过 `metricDim()` / `metric()` overrides 配置 |
 | `.setFreeDrill(enabled, position)` | 设置 `config.freeDrillConfig` |