@guandata/guanvis 0.1.36 → 0.1.38

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## @guandata/guanvis 0.1.38 - 2026-08-13
+
+- 新增 `live` 系列命令和完整实时项目工作流，可对线上仪表板执行受控、可回溯的创建与维护操作。
+- 大幅扩展指标图、进度图、迷你图、地图、气泡图、雷达图、箱线图、热力图等专项图表属性，复杂看板的表达能力更完整。
+- 新增系统图标查询与引用能力，指标图等场景可直接使用 BI 环境中的图标资源。
+- 增强实时项目输入校验、已有仪表板附着、初始化、覆盖保护和任务诊断，减少误操作并提升问题定位效率。
+
+## @guandata/guanvis 0.1.37 - 2026-08-07
+
+- 发布前新增字段 `fdId` 线上活性校验，提前发现无效字段绑定，降低发布失败风险。
+- 完善筛选器配置，支持更完整的筛选设置与组合使用场景。
+- 优化页面布局及组合图配置，提升图表构建与导出结果的稳定性。
+- 补充构建器、图表属性、指标图表和编辑流程文档，改善使用体验。
 ## @guandata/guanvis 0.1.36 - 2026-08-04
 
 - 扩展仪表板标题、页面背景、筛选栏、卡片组、Tab 和分区的视觉配置，支持字体、颜色、图标、背景图、间距与分割线。

package/README.md

@@ -54,6 +54,18 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.38
+
+- 新增 `live` 系列命令和完整实时项目工作流，可受控地创建与维护线上仪表板。
+- 扩展指标图、进度图、迷你图、地图、气泡图、雷达图、箱线图、热力图等专项图表属性。
+- 支持查询和引用 BI 环境中的系统图标，并增强输入校验、覆盖保护和任务诊断。
+
+### @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.38",
   "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 不受限）。
@@ -32,9 +32,31 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 - **资源包安全红线**：Agent 只编辑 DSL 源文件；资源包 ZIP 是 `guanvis pack/publish` 的派生产物，不手工生成、解包修改或重打包。`guanvis upload` 只允许上传 `guanvis pack` 原样生成的 ZIP。若用户要求批量重绑资源、迁移已有页面或复用线上页面结构，先停下来说明风险并确认方案，不要直接改 ZIP。
 - 发布后优先用 `guancli page get/card get` 回读结构与配置；`guanvis screenshot` 仅在明确需要视觉质量判断且模型支持图像理解时使用（额外消耗 token），不作默认闭环步骤。
 
+### 桌面端对话式实时构建
+
+桌面安全 Runtime 同时提供 `connected.guancli`、`connected.guanvis` 与右侧可见的 `browser` 时，使用 `guanvis live` 做无需持久化本地工程的对话式构建：
+
+1. 用 `connected.guancli` 查询数据集、页面与卡片，真实取数走 `card preview`；不要向用户索取 Token。
+2. 正式交付或需要任一完整能力时，把与普通工程完全相同的 `schema.js`、`card_*.js`、`selector_*.js`、`page.js`、主题/设计规则及二进制资产组成 version=1 JSON 内存工程，先调 `live project validate`，再把同一份 stdin 交给 `live project publish`。文本文件用 `content`；直接调用 CLI 时二进制用 `base64`，桌面安全 Runtime 中上传的图片或 xlsx 必须通过 `reference.list` 取得 ID，再用 `asset_refs:[{"reference_id":<id>,"path":"<工程内路径>"}]` 交给 Host 注入，模型不要读取或生成大段 base64。路径必须在工程内且大小写不能冲突。
+3. 只有需求严格落在 KPI、基础/分组/堆叠柱、基础折线、明细表且强调最低延迟时，才用 `live page/card` 批量建卡并一次 apply；不得用 P0 命令降级模拟筛选器、文本、图片、地图、自定义图表或复杂报表。
+4. publish/page create 返回页面 URL 后用 `browser.open` 在右侧打开；每次 publish/apply/patch/remove/delete 后 `browser.navigate(reload)`，再用 snapshot/screenshot 回读，并以 `guancli page get/card preview` 验证结构和真实数据。
+5. `live project` 复用普通 GuanVis 的完整 DSL、主题、设计规则、校验和 transfer 发布引擎；不允许宿主文件参数、绝对路径、`..` 或文件 URI。新建资源必须显式 setId，覆盖同 ID Page 仍需用户明确确认后使用 `--allow-overwrite`。
+6. `live card delete` 与 `live page remove-card` 仅在用户明确要求删除/移除时调用；前者删除实体，后者只移出布局。
+
+完整内存工程最小契约：
+
+```json
+{"version":1,"files":[
+  {"path":"schema.js","content":"defineDataset(...)"},
+  {"path":"card_01.js","content":"var card = createCard(...); registerCard(card.build());"},
+  {"path":"page.js","content":"var page = createPage(...); registerPage(page.build());"},
+  {"path":"assets/logo.png","base64":"..."}
+]}
+```
+
 ## 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 +71,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 用环境变量
@@ -203,9 +225,13 @@ guanvis check-dataset-switch . --from <oldDs> --to <newDs> --mode full   # 详
 # 仪表板主题（详见 references/theme.md）
 guanvis theme preference --keywords "..." --sync   # 另有 --theme-id / --clear；theme list/show/sync
 
-# 单张图表主题色
+# 获取当前环境中可用的图表主题色
 guanvis theme-color list
 guanvis theme-color sync -d ./my_dashboard
+
+# 获取当前 BI 环境可用的图标
+guanvis icon list
+guanvis icon list --group default_line -f json
 ```
 
 **多子目录工程**：每个子目录是独立工程，preview/pack/publish/`theme *` 必须 `cd` 进各子目录分别执行、各出各的资源包；根目录直接运行时若任一子目录有 `themes/` 会拒绝执行并打印 cd 提示。

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

@@ -4,7 +4,7 @@
 
 | 函数 | 说明 |
 |------|------|
-| `defineDataset(dsId, columns, options?)` | 定义数据集 schema（由 init 命令生成）。第一个数据集自动暴露为 `global.DS`（dsId 字符串）。`options.displayType` 指定数据集类型（如 `"EXCEL"`, `"DATAFLOW"`），确保看板页面正确显示数据集图标 |
+| `defineDataset(dsId, columns, options?)` | 定义数据集 schema（由 init 命令生成）。第一个数据集自动暴露为 `global.DS`（dsId 字符串）。`options.displayType` 指定数据集类型（如 `"EXCEL"`, `"DATAFLOW"`）；`options.sourceType` 保存数据源运行方式，用于直连能力限制等校验 |
 | `field(dsId, fieldName, overrides?)` | 从 schema 构造字段引用，`dsId` 是字符串。可叠加 aggrType/alias/numberFormat/sortType/granularity 等 |
 | `f(fieldName, overrides?)` | `field(DS, fieldName, overrides)` 的简写，仅适用于**单数据集**场景 |
 | `chartField(zone, index)` | 按最终数据区和位置引用图表字段，用于 `setAuxiliaryLine()` 的计算辅助线 |

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

@@ -1,5 +1,7 @@
 ## Builder API 参考
 
+新建 Card/Page 未设置非空业务描述时，payload 描述使用 `[guanvis:created]` 标记创建来源；设置非空业务描述后只保存业务描述，不追加标记。attach/checkout 已有资源不补标记，Page 只有创建标记时不会打开描述展示。
+
 ### CardBuilder
 
 | 方法 | 说明 |
@@ -23,16 +25,30 @@
 | `.addLocation(field)` / `.addTarget(field)` / `.addCompare(field)` | 位置/目标/对比 |
 | `.setSplitSetting(config)` | 拆分图配置 |
 | `.setColorByColors(preset_or_config)` | 渐变色配置 |
-| `.setBarSetting(config)` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
+| `.setBarSetting(config)` | 柱形图/条形图的柱体宽度、间距和圆角配置；帕累托图还支持数据点显隐 |
+| `.setStackSplitSetting(config)` | 分组堆积柱形图/条形图的堆积分组模式 |
+| `.setWaterfallSetting(config)` | 瀑布图的正负值颜色和累计值配置 |
+| `.setParetoSetting(config)` | 帕累托图的累计曲线名称和百分比精度配置 |
+| `.setMapSetting(config)` | 地图专属属性配置 |
+| `.setBubbleSetting(config)` | 气泡半径配置 |
+| `.setRadarSetting(config)` | 雷达图显示配置 |
+| `.setBoxPlotSetting(config)` | 箱线图配置 |
+| `.setHeatMapSetting(config)` | 热力图配置 |
+| `.setSingleValueSetting(config)` / `.setKPISetting(config)` | 指标卡、对比指标卡配置 |
+| `.setProgressBarSetting(config)` / `.setProgressPieSetting(config)` | 进度条、进度环配置 |
+| `.setActivityGaugeSetting(config)` / `.setLiquidGaugeSetting(config)` / `.setSolidGaugeSetting(config)` | 活动仪表盘、水波图、实心仪表盘配置 |
 | `.setShapeColorType(type)` | 图形填充配置 |
 | `.setLineSetting(config)` | 折线显示配置 |
+| `.setComboSetting(config)` | 组合图的显示方式、折线或符号样式配置 |
 | `.setCardSetting(config)` | 卡片背景、主题跟随、内边距和内容间距 |
 | `.setShowTitle(show)` / `.setCardTitleStyle(config)` | 卡片标题显隐和样式配置 |
 | `.setShowLegend(show, position?)` / `.setChartLegend(config)` | 图例配置 |
 | `.setDataLabel(config)` / `.setMetricAdditionalDataLabel(config)` | 数据标签配置 |
+| `.setTreemapDataLabel(config)` / `.setFunnelDataLabel(config)` | 矩形树图分层数据标签、漏斗图各类数据标签配置 |
 | `.setAxis(config)` | 坐标轴配置 |
 | `.setTooltip(config)` | 工具提示配置 |
 | `.setTableSetting(config)` / `.setTableCellMerge(config)` | 表格行为、视觉样式与单元格配置 |
+| `.setMiniChart(selector, config)` / `.setMiniChartSetting(selector, config)` | 设置透视表数值字段的迷你图类型、维度及字段 key 对应样式 |
 | `.setPieSetting(config)` / `.setPieCenterText(config)` | 饼图配置 |
 | `.setGrandTotal(config)` | 表格总计与小计配置 |
 | `.setSummary(field, options?)` / `.setSummaryStyle(config)` | 汇总指标及样式配置 |
@@ -163,11 +179,25 @@ attachCard(CARD_ID, BASE_PATH)
 | `.setShowTitle()` / `.setCardTitleStyle()` | 卡片标题显隐和样式配置 |
 | `.setShowLegend()` / `.setChartLegend()` | 图例配置 |
 | `.setDataLabel()` / `.setMetricAdditionalDataLabel()` | 数据标签配置 |
+| `.setTreemapDataLabel()` / `.setFunnelDataLabel()` | 矩形树图分层数据标签、漏斗图各类数据标签配置 |
 | `.setAxis()` / `.setAuxiliaryLine()` / `.setTooltip()` | 坐标轴、辅助线和工具提示配置 |
 | `.setLineSetting()` | 折线显示配置 |
-| `.setBarSetting()` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
+| `.setComboSetting()` | 组合图的显示方式、折线或符号样式配置 |
+| `.setBarSetting()` | 柱形图/条形图的柱体宽度、间距和圆角配置；帕累托图还支持数据点显隐 |
+| `.setStackSplitSetting()` | 分组堆积柱形图/条形图的堆积分组模式 |
+| `.setWaterfallSetting()` | 瀑布图的正负值颜色和累计值配置 |
+| `.setParetoSetting()` | 帕累托图的累计曲线名称和百分比精度配置 |
+| `.setMapSetting()` | 地图专属属性配置 |
+| `.setBubbleSetting()` | 气泡半径配置 |
+| `.setRadarSetting()` | 雷达图显示配置 |
+| `.setBoxPlotSetting()` | 箱线图配置 |
+| `.setHeatMapSetting()` | 热力图配置 |
+| `.setSingleValueSetting()` / `.setKPISetting()` | 指标卡、对比指标卡配置 |
+| `.setProgressBarSetting()` / `.setProgressPieSetting()` | 进度条、进度环配置 |
+| `.setActivityGaugeSetting()` / `.setLiquidGaugeSetting()` / `.setSolidGaugeSetting()` | 活动仪表盘、水波图、实心仪表盘配置 |
 | `.setPieSetting()` / `.setPieCenterText()` | 饼图配置 |
 | `.setTableSetting()` / `.setTableCellMerge()` / `.setGrandTotal()` | 表格行为、视觉样式与汇总配置 |
+| `.setMiniChart()` / `.setMiniChartSetting()` | 设置透视表数值字段的迷你图和样式；支持已有 MetricChart 增量编辑 |
 | `.setSplitSetting()` / `.setShapeColorType()` | 拆分图和图形填充配置 |
 | `.setRawSettings()` | 原始设置 |
 | `.setProps(obj)` | 设置指标卡片 `meta.chartMain.props` |
@@ -407,7 +437,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 +475,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 +504,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 +887,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 +910,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 +953,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 +994,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 +1046,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` 的目标字段映射优先。
 
@@ -1714,6 +1797,10 @@ project/
 | `AggrType` | `SUM`, `AVG`, `COUNT`(=CNT), `COUNT_DISTINCT`(=CNT_DISTINCT), `MIN`, `MAX` | 聚合类型 |
 | `FieldType` | `STRING`, `INT`, `LONG`, `DOUBLE`, `FLOAT`, `DATE`, `BOOL`, `DECIMAL` | 字段数据类型 |
 | `SortOrder` | `ASC`, `DESC` | 排序方向 |
+| `MiniChartType` | `LINE`, `COLUMN`, `PIE`, `PROGRESS` | 透视表字段迷你图类型 |
+| `MiniChartSort` | `ASC`, `DESC` | 迷你图维度排序方向 |
+| `MapRegion` | `COUNTRY`, `PROVINCE`, `CITY`, `AUTO` | 中国行政类地图的显示范围 |
+| `MapSymbol` | `CIRCLE`, `DIAMOND`, `SQUARE`, `TRIANGLE`, `TRIANGLE_DOWN` | 符号行政地图的内置符号 |
 | `Granularity` | `NONE`, `YEAR`, `QUARTER`, `MONTH`, `WEEK`, `DAYOFWEEK`, `DAY`, `HOUR`, `MINUTE`, `SECOND` | 日期粒度 |
 | `GrandTotalPosition` | `LEFT`, `RIGHT`, `TOP`, `BOTTOM` | 表格总计位置；行总计用左右，列总计用上下 |
 | `ContentSpaceSize` | `SMALL`, `MIDDLE`, `LARGE` | 卡片内容间距 |