@guandata/guanvis 0.1.29 → 0.1.30

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## @guandata/guanvis 0.1.30 - 2026-07-08
+
+- 支持 checkout 线上页面到本地工程，并增强已有仪表板的编辑、差异查看和回写流程。
+- 支持动态维度、动态指标和拆分图表相关构建能力，提升复杂图表生成覆盖面。
+- 新增筛选器分组和开关类检查能力，页面交互配置更容易验证。
+- `pack` / `preview` / `lint` 诊断增强，可提前发现资源 ID、布局、联动和覆盖相关问题。
+
 ## @guandata/guanvis 0.1.29 - 2026-07-01
 
 - 支持筛选器级联联动，页面中的筛选器可以按上游筛选结果继续约束下游筛选项。

package/README.md

@@ -51,6 +51,13 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.30
+
+- 支持 checkout 线上页面到本地工程，并增强已有仪表板的编辑、差异查看和回写流程。
+- 支持动态维度、动态指标和拆分图表相关构建能力，提升复杂图表生成覆盖面。
+- 新增筛选器分组和开关类检查能力，页面交互配置更容易验证。
+- `pack` / `preview` / `lint` 诊断增强，可提前发现资源 ID、布局、联动和覆盖相关问题。
+
 ### @guandata/guanvis 0.1.29
 
 - 支持筛选器级联联动，页面中的筛选器可以按上游筛选结果继续约束下游筛选项。

package/package.json

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

package/skills/guanvis/SKILL.md

@@ -9,7 +9,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 这是一个执行型 skill，用于通过 AI 生成的 JS 脚本创建 BI Card 和 Page 资源。
 
 - AI 生成 `card_*.js` 定义各个 Card 图表；`page.js` 将多个 Card 组装成仪表板。
-- `schema.js` 由 `init` 命令自动生成，定义数据集字段信息（不允许 AI 修改）；指标卡片使用 `metric-init` 生成 `metrics.js`。
+- `schema.js` 由 `init` 或 `checkout` 命令生成，定义数据集字段信息（不允许 AI 修改）；checkout 生成 schema 是 best-effort，失败不会阻断 checkout。指标卡片使用 `metric-init` 生成 `metrics.js`。
 - 框架内置验证规则，在 pack/publish 时检查字段数量、zone 兼容性、必填字段等。
 - 认证通过 `guancli` 共享配置自动获取。
 
@@ -17,8 +17,10 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 
 把可视化生成当作源文件驱动的构建流程：本地 JS DSL 是可编辑事实源，payload、ZIP、线上 Card/Page 都是从源文件生成的派生产物。
 
-- `schema.js` 是由 `init` 生成的数据集事实快照，不手改；数据集字段变化时重新运行 `init`。`metrics.js` 是由 `metric-init` 生成的指标事实快照，不手改；指标口径、适用维度或格式变化时重新运行 `metric-init`。
+- `schema.js` 是由 `init` / `checkout` 生成的数据集事实快照，不手改；数据集字段变化时重新运行对应命令。`metrics.js` 是由 `metric-init` 生成的指标事实快照，不手改；指标口径、适用维度或格式变化时重新运行 `metric-init`。
 - `card_*.js`、`selector_*.js`、`page.js` 是可编辑源文件；`*_package.zip`、preview JSON、publish 后线上资源都是派生产物。
+- 已有线上仪表板用 `guanvis checkout <pgId> -d <dir>` 拉成可编辑工程：checkout 会尽量生成 `schema.js`，但数据集无权限/已删除/跨环境残留时只 warning 并继续生成可编辑工程；Card 用 `attachCard(cdId, ".guanvis/base/cards/<cdId>.json")` 接受线上 JSON 作为基线；Page 生成 `createPage(...).setBasePath(...).placeCard("cdId", ...)` 脚本，尽量反编译根布局里的 Tab/CardGroup/AreaTitle/SelGroup 和快捷筛选组，并保留 parentDirId。checkout 工程只用于修改指定 Page，不用于复制新 Page；遇到嵌套布局组件等当前 DSL 不能安全表达的结构，checkout 会直接失败，不生成会清结构的工程。
+- **Checkout JSON 红线**：`.guanvis/raw/**`、`.guanvis/base/**`、`.guanvis/manifest.json` 是 checkout 生成物和只读快照，不是可编辑源文件。Agent 不得修改这些 JSON，也不得复制一份 checkout JSON 后改副本来创建新资源；`attachCard(cardId, jsonPath)` 只能引用 manifest 记录的原始 base-card，且 `cardId` 必须与该 JSON 的资源 ID 一致。现有卡片修改必须通过 `attachCard(...).setName()/updateMetric()/addMetric()/removeMetric()/addLink()` 等 DSL 操作表达；字段整体重建才用 `setRows()` / `setMetrics()`，这些整 zone 替换会触发 warning，默认应优先用 `update*/patch*/add*/remove*/move*`。Page 快捷筛选区修改用 `createPage(...).setBasePath(...).setFilterLayout()/clearFilterLayout()/addFilterLayoutItem()/insertFilterSelector()/removeFilterSelector()/moveFilterSelector()` 表达；筛选器在快捷筛选区和画布之间移动时优先用 `moveFilterSelectorToCanvas()` / `moveCanvasSelectorToFilter()`，筛选器组用 `moveSelectorGroupToCanvas()` / `moveCanvasSelectorGroupToFilter()`。新增卡片必须使用 `createCard()` / `createSelector()` 等工厂函数。
 - Card/Page 描述也是 JS 源文件的一部分：新建看板或改版时，在 `card_*.js` / `page.js` 中写 `.setDescription(...)`，再通过 `preview`/`pack`/`publish` 从 JS 源文件生成并发布资源。
 - 写脚本前先形成 dashboard contract：目标用户、业务问题、使用的数据集、核心指标、维度拆解、筛选器、页面结构和验证方式。
 - 每次生成都针对明确目录或明确子目录；不要把 unrelated 示例、旧包或临时 ZIP 混入同一个发布目标。
@@ -29,7 +31,9 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 
 ## AI Quick Reference（速查，详细说明见按需参考资料）
 
-1. **工厂函数**：数据集图表用 `createCard()`；指标平台指标卡片用 `createMetricChart()`；筛选器/文本/图片/杜邦/Tab/页面用 `createSelector()` / `createTextCard()` / `createImageCard()` / `createDuPontChart()` / `createAreaTitle()` / `createCardGroup()` / `createTab()` / `createPage()`，不要 `new XxxBuilder()`
+**Checkout/attachCard 速记**：`attachCard(cardId, jsonPath)` 是“base JSON + 链式 DSL 操作 = 目标 JSON”。它不会修改 base JSON，重复执行同一组 JS 操作应产出相同 payload。已有卡片可继续串接常用 `createCard` 后续操作，包括标题/描述、`setRawSettings`、图例/标签/坐标轴/表格/拆分等视觉设置。Zone 操作按链式顺序真实执行：`addRow/addMetric/...` 追加字段，`insertMetric(index, field)` 插入字段，`removeMetric(selector)` 删除字段并保守清理其它 zone 中同字段引用，`moveMetric(selector, index)` 调整顺序，`updateMetric(selector, patch)` / `patchMetric(...)` 修改已有字段属性并保留未设置字段配置；`setRows/setMetrics/...` 和 `clearRows/clearMetrics/...` 是整 zone 重建，不会继承被替换字段的格式，并会在验证时提示 warning。已有 selector 额外用 `.addLink(cardIdOrIndex, targetFieldName?)` / `.removeLink(cardIdOrIndex)` / `.clearLinks()` 修改联动。Page 筛选区也按有序操作执行：`setFilterLayout` 整体设置，`clearFilterLayout` 清空，`addFilterLayoutItem` 追加去重，`insert/remove/moveFilterSelector` 局部调整；筛选器在快捷筛选区和画布间移动优先用动作级 API：`moveFilterSelectorToCanvas(selectorId, x, y, w, h)` / `moveCanvasSelectorToFilter(selectorId, index?)`，筛选器组用 `moveSelectorGroupToCanvas(group, x, y, w, h)` / `moveCanvasSelectorGroupToFilter(group, index?)`。checkout 生成的 page 布局默认用 card/selector ID 字符串；发布前可用 `guanvis diff <dir>` 或 `preview` 输出里的 `changeSummary` 查看 base JSON 到最终 payload 的路径级影响面；没有 DSL 操作覆盖的需求，先扩展 DSL，不要改 `.guanvis` JSON。
+
+1. **工厂函数**：数据集图表用 `createCard()`；已有线上卡片用 `attachCard(cardId, jsonPath)`；指标平台指标卡片用 `createMetricChart()`；筛选器/筛选器组/文本/图片/杜邦/Tab/页面用 `createSelector()` / `createSelectorGroup()` / `createTextCard()` / `createImageCard()` / `createDuPontChart()` / `createAreaTitle()` / `createCardGroup()` / `createTab()` / `createPage()`，不要 `new XxxBuilder()`；checkout JSON 不可复制改造，新卡片必须 create，老卡片才 attach
 2. **注册函数**：`registerCard(card.build())` / `registerMetricChart(card.build())` / `registerSelector(sel.build())` / `registerTextCard(text.build())` / `registerImageCard(image.build())` / `registerDuPontChart(dupont.build())` / `registerPage(page.build())`
 3. **字段引用**：单数据集用 `f("字段名")`，多数据集用 `field(DS, "字段名")`
 4. **zone maxCount**：`BASIC_COLUMN/BAR/LINE` metric=1；`GROUPED_*/STACKED_*` metric=∞；`KPI_CARD` metric=1；组合图 `*_WITH_LINE` row=1
@@ -38,19 +42,20 @@ 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" }`，且不要写任何 SQL 聚合函数或窗口函数。汇总需求改用非明细图表 `aggrType` / aggregation calcField，或 ETL 预计算
-10. **联动/下钻**：筛选器联动图表必须调用 `.linkToAll()` 或 `.linkTo(cardIndex)`；筛选器级联筛选器用 `.linkToSelector(selectorId, targetFieldName?)`，目标为 ALL/空默认值时会自动启用 FIRST_PICK + firstPickLink，固定默认值会保留；普通图表卡片联动普通图表用 `card.linkTo(layoutCardIndex, { fields: [{ source, target }] })`；固定路径下钻用 `registerDrillPath(parentCardIndex, [child.build()], { position: DrillPathPosition.BOTTOM })`；详细规则见 `references/builder-reference.md`
+10. **联动/下钻**：新建筛选器联动图表必须调用 `.linkToAll()` 或 `.linkTo(cardIndex)`；checkout attach 回来的已有筛选器用 `attachCard(selectorId, jsonPath).addLink(cardIdOrIndex, targetFieldName?)` / `.removeLink(cardIdOrIndex)` / `.clearLinks()` 叠加修改现有 `settings.asFilter`，不要反向改 JSON；筛选器级联筛选器用 `.linkToSelector(selectorId, targetFieldName?)`，目标为 ALL/空默认值时会自动启用 FIRST_PICK + firstPickLink，固定默认值会保留；普通图表卡片联动普通图表用 `card.linkTo(layoutCardIndex, { fields: [{ source, target }] })`；固定路径下钻用 `registerDrillPath(parentCardIndex, [child.build()], { position: DrillPathPosition.BOTTOM })`；详细规则见 `references/builder-reference.md`
 11. **selector 类型选择**：离散值（区域/类别）→ `DS_ELEMENTS`（默认）；连续数值（利润率/金额）→ `.setSelectorType(SelectorType.DS_INTERVAL)`；日期 → `CALENDAR`；快捷日期区间（本月/近7天等）→ `.setTimeMacroOptions(options)`
 12. **同环比默认**：用户说同比/环比/同环比/年同比/月环比且未指定输出值时，默认用增长率；未指定模式时默认按日期筛选模式（`ComparativeMode.FILTER_BASED`），普通模式需显式指定 `ComparativeMode.NORMAL`。如果日期字段已经是预聚合周期字段（如 `周开始日期` / `月开始日期`），必须把日期字段声明为 `f("周开始日期", { granularity: Granularity.NONE })`，builder 会生成不带筛选窗口和 `mode` 的同环比，避免按 DAY 筛选窗口计算为空
-13. **placeCard 入参**：数字 index 按 `registerCard` / `registerMetricChart` / `registerTextCard` / `registerImageCard` / `registerCustomChart` / `registerDuPontChart` 等可布局资源的注册顺序累加，文件按文件名排序加载。**registerSelector 不参与 card index 计数**；要把 selector 放进画布或者布局组件时，使用 selector 字符串 ID，如 `placeCard("selectorId", x, y, w, h)` 或 `addFullWidthCard("selectorId", h)`。
+13. **placeCard 入参**：优先使用 card/selector ID 字符串，尤其是 checkout 工程和子目录工程，如 `placeCard("cardId", x, y, w, h)`。数字 index 仍可用于新建工程，按 `registerCard` / `registerMetricChart` / `registerTextCard` / `registerImageCard` / `registerCustomChart` / `registerDuPontChart` 等可布局资源的注册顺序累加，文件按文件名排序加载；**registerSelector 不参与 card index 计数**。要把 selector 放进画布或者布局组件时，使用 selector 字符串 ID，如 `placeCard("selectorId", x, y, w, h)` 或 `addFullWidthCard("selectorId", h)`。
 14. **publish 环境**：认证由底层 CLI 负责——guancli 需先 `guancli auth use <profile>`，guancli-lite 需设置环境变量
-15. **更新线上仪表板**：已发布过或线上正在使用的仪表板，若调整图表、布局、筛选器、字段等看板内容，默认创建新版本仪表板，不覆盖原仪表板；新版本使用新的 Page/Card/Selector ID，名称追加版本号（如 `销售仪表板 v2` / `销售仪表板 20260430`），保留多个版本。只有用户明确要求覆盖时，才复用原 ID；遇到覆盖提示时，Agent 必须先向用户说明将覆盖哪些线上资源并取得明确确认，确认前不得自行加 `--allow-overwrite`
+15. **更新线上仪表板**：checkout 工程默认表示“修改指定线上 Page”，保留原 Page/Card/Selector ID；发布时如 CLI 检测到同 ID Page，必须先向用户说明将覆盖哪些线上资源并取得明确确认，确认后才可加 `--allow-overwrite`，由现有覆盖备份机制兜底。不要把 checkout JSON 复制后改 ID 来做“新版本”。若用户明确要保留原页面并生成新版本，应优先调用 BI 自身 Page Save/复制能力让 BI 处理 ID 映射，再基于新页面 checkout/edit；不要在 guanvis CLI 里手写复杂 ID map。
 16. **描述维护**：仅修复已发布 Card/Page 的描述时，保留原资源 ID，使用 `guanvis card/page set-description` 更新线上描述；如果本地有对应 JS 工程，也同步更新 `.setDescription(...)`，让源文件与线上描述一致
 17. **主题切换**：用户描述风格（深色科技风/科技蓝/蓝色简约等）→ 在工程目录里 `guanvis theme preference --keywords "..." --sync`（`[dir]` 可省，默认当前目录）；不要选择租户默认的“浅色”/“深色”主题，找不到合适主题时保持/清空偏好，让 preview/pack/publish 自动使用内置“简约”兜底。普通数据集图表与指标平台 MetricChart 都会自动应用主题视觉配置；改版未提风格时 `.applied.json` 会自动继承上次主题，preview/pack/publish 不需要重复指定。**多子目录工程**：每个子目录是独立工程，主题要在子目录里配置 + preview/pack/publish 也必须 `cd` 进对应子目录运行（在根目录直接跑会被命令显式拒绝并给出 cd 提示）；详见 `references/theme.md`
 18. **设计规则**：`preview`/`pack`/`publish` 会自动应用内置设计规则；需要自定义静态卡片默认规则或主题已开放配置时，在工程目录新建 `design-rule.json`，不要手改 `themes/<themeId>.json`；详见 `references/theme.md`
 19. **图表选型**：用户说“指标卡片”时先区分语义：如果是数据集字段做单值/KPI，用 `SINGLE_VALUE` / `KPI_CARD`；如果是“用指标平台已有指标创建卡片”，必须先 `guanvis metric-init <metricId>`，再用 `createMetricChart()` + `metric()` / `metricDim()`，生成后端 `CARD_TYPE.METRIC_CHART`。复杂指标卡片参数先读 `references/metric-chart-reference.md`
 20. **杜邦分析图**：杜邦不是普通 `ChartType`，用 `createDuPontChart()` 创建 `LAYOUT` 卡片；节点通常放 `KPI_CARD` 子卡片，并通过 `.setRoot()` / `.addChild()` 组织树。页面布局只放杜邦父卡片，不单独放子卡片；筛选器 `linkToAll()` 会覆盖杜邦子卡片。
-21. **布局组件**：支持 `小标题(AreaTitle)` / `卡片组(CardGroup)` / `标签页(Tab)`。布局组件本身只支持放在画布根布局，不支持嵌套组合使用；内部布局能力详见 `references/builder-reference.md`。
-22. **资源包禁止手改**：只改 DSL，不改 ZIP 内部文件；`upload` 只用于上传 `guanvis pack` 原样生成的包。批量重绑、迁移页面等需求先讨论方案。
+21. **布局组件**：支持 `小标题(AreaTitle)` / `卡片组(CardGroup)` / `筛选器组(SelGroup)` / `标签页(Tab)`。布局组件本身只支持放在画布根布局，不支持嵌套组合使用；SelGroup 内只能放 selector；checkout 会反编译根布局组件，无法安全表达的嵌套结构会失败；内部布局能力详见 `references/builder-reference.md`。
+22. **资源包/checkout JSON 禁止手改**：只改 DSL，不改 ZIP 内部文件，也不改 `.guanvis/raw` / `.guanvis/base` / `.guanvis/manifest.json`；`upload` 只用于上传 `guanvis pack` 原样生成的包。批量重绑、迁移页面、补缺失操作符等需求先讨论方案，必要时扩展 DSL 操作，不手工改生成物。
+23. **动态字段**：普通卡支持动态维度/动态数值，指标平台卡支持动态维度/动态指标；用户明确需要字段切换时使用 `.addDynamicRow()` / `.addDynamicMetric()` 等 API，细节见 `references/builder-reference.md`。
 
 ## 何时使用
 
@@ -270,9 +275,18 @@ guanvis gen-layout-id tab                 # 生成 1 个 tab_ + 默认 6 位字
 guanvis gen-layout-id panel 3 --length 8  # 生成 3 个 panel_ + 8 位字母；length 只计算下划线后的随机字母，超出 6~10 时自动收敛
 guanvis gen-layout-id areaTitle           # 生成 1 个 areaTitle_ + 默认 6 位字母
 guanvis gen-layout-id cardGroup           # 生成 1 个 cardGroup_ + 默认 6 位字母
+guanvis gen-layout-id selGroup            # 生成 1 个 selGroup_ + 默认 6 位字母
+
+# 拉取已有线上仪表板为可编辑工程（只读 BI，不发布；尽量生成 schema.js）
+guanvis checkout <pageId> -d ./existing_dashboard
+# checkout 后只编辑 schema 外的 card_*.js / selector_*.js / page.js；不要修改或复制 .guanvis/raw、.guanvis/base、.guanvis/manifest.json
+# 若 schema.js 未生成或缺字段，后续可手动 guanvis init <dsId> -d ./existing_dashboard --force 补齐
+# checkout --overwrite 会清理输出目录下所有根级 .js 和旧 .guanvis，避免 schema/selector/metrics/other.js 残留混入运行
 
 # 预览生成结果（JSON 输出到 stdout，含 payload 验证，用于调试）
 guanvis preview ./my_dashboard/
+# checkout/attach 工程的路径级变更摘要（也会出现在 preview JSON 的 changeSummary 中）
+guanvis diff ./existing_dashboard/
 
 # 打包为 ZIP 资源包
 guanvis pack ./my_dashboard/
@@ -298,6 +312,12 @@ guanvis screenshot <pageId>                                     # 截图页面 P
 guanvis screenshot <pageId> -o /tmp/dashboard.png               # 指定输出路径
 guanvis screenshot <pageId> --orientation horizontal            # 横向截图
 
+# 数据集/指标切换后的检查（仅梳理）
+guanvis check-dataset-usage . --ds <dsId>         # 盘点某个 dsId 在工程中的引用
+guanvis check-dataset-switch . --from <oldDs> --to <newDs> --mode full # 整页/整包数据集切换后检查
+guanvis check-dataset-switch . --from <oldDs> --to <newDs> --mode linked --changed-cards <cdId> # 局部切数据集后检查一跳关联资源
+guanvis check-metric-switch . --from <oldMetric> --to <newMetric> --mode linked --changed-cards <cdId> # 局部切指标后检查一跳关联资源
+
 # 仪表板主题（详见 `references/theme.md`，[dir] 缺省为当前目录）
 guanvis theme preference --keywords "深色 科技" --sync          # 在当前目录写入偏好并同步主题列表
 guanvis theme preference ./my_dashboard --theme-id custom_blue  # 显式指定工程目录
@@ -331,12 +351,12 @@ guanvis pack ./project
 
 **资源包安全约束**：`upload` 只是上传器，不是制作自定义资源包的入口。除非用户明确批准，否则不得上传手工生成、解包修改、重打包或批量替换内部内容后的 ZIP。需要批量重绑数据集、字段、卡片或页面 ID 时，先讨论方案，不要直接改 ZIP。
 
-**线上仪表板更新策略**：为了保护已经发布过的仪表板和线上仪表板，默认不要复用原 Page/Card/Selector ID 做覆盖更新。需要调整线上看板时，应先生成一组新的 ID，复制并修改 DSL/JS，给 Page 名称追加版本号（例如 `v2`、`v20260430` 或业务约定版本），再 `publish` 到目标目录。旧版本保留用于回滚和对比。仅当用户明确要求“覆盖原仪表板/复用原 ID”时，才允许同 ID 发布，并且命令必须显式加 `--allow-overwrite` 允许同 ID Page 覆盖；发布前可用 `--dry-run` 查看会覆盖哪些线上 Page。Card/Selector ID 不做在线覆盖检查。**Agent 禁止在未确认的情况下自行加 `--allow-overwrite`**：当 CLI 提示将覆盖线上 Page 时，必须先停止发布，向用户说明将覆盖的 Page ID、名称和覆盖后可能替换原页面布局，等用户明确确认“覆盖”后才可以重跑并加 `--allow-overwrite`。使用 `--allow-overwrite` 时，CLI 会先为冲突 Page 发起资源包导出备份并等待导出成功；备份未成功则中止覆盖。CLI 只记录备份导出记录和 packageId，不自动下载资源包；需要回滚时，到 BI 资源迁移导出记录中手动下载该资源包后再导入覆盖回去。
+**线上仪表板更新策略**：新建工程发布的是新 Page；checkout 工程发布的是对 checkout 指定 Page 的覆盖式修改，不承担“复制新版本”职责。需要保留原页面并生成新版本时，不要在 guanvis CLI 内手工复制 JSON 或改 ID map；应先使用 BI 自身 Page Save/复制能力生成新 Page，让 BI 处理 ID 映射，再 checkout 新 Page 继续编辑。对 checkout 工程同 ID 发布时，命令必须显式加 `--allow-overwrite` 允许同 ID Page 覆盖；发布前可用 `--dry-run` 查看会覆盖哪些线上 Page。Card/Selector ID 不做在线覆盖检查。**Agent 禁止在未确认的情况下自行加 `--allow-overwrite`**：当 CLI 提示将覆盖线上 Page 时，必须先停止发布，向用户说明将覆盖的 Page ID、名称和覆盖后可能替换原页面布局，等用户明确确认“覆盖”后才可以重跑并加 `--allow-overwrite`。使用 `--allow-overwrite` 时，CLI 会先为冲突 Page 发起资源包导出备份并等待导出成功；备份未成功则中止覆盖。CLI 只记录备份导出记录和 packageId，不自动下载资源包；需要回滚时，到 BI 资源迁移导出记录中手动下载该资源包后再导入覆盖回去。
 
 ## 文件结构约定
 
 目录模式下文件加载顺序：
-1. `schema.js` — 数据集定义（自动生成，不可修改）
+1. `schema.js` — 数据集定义（init 生成；checkout 尽量生成，不可修改）
 2. `metrics.js` — 指标定义（仅指标卡片需要，自动生成，不可修改）
 3. `card_01_xxx.js` ~ `card_NN_xxx.js` — Card 定义（按文件名排序）
 4. `selector_01_xxx.js` ~ `selector_NN_xxx.js` — 筛选器定义（在 card 之后执行，因为联动需要引用 card 索引）
@@ -351,6 +371,7 @@ guanvis pack ./project
 | 示例 | 路径 | 说明 |
 |------|------|------|
 | 基础仪表板 | `evals/sales_dashboard/` | 普通卡片（柱状图、折线图、KPI、饼图）+ 筛选器 + 页面布局 |
+| 拆分图 | `evals/split_charts/` | 柱形等图表按字段拆分 |
 | 自定义图表 | `evals/custom_chart_echarts/` | ECharts Lite 自定义图表：柱状图 + 饼图，使用 `loadContent()` 文件模式 |
 | Tab 布局 | `evals/tab_layout/` | 单页面 tab 示例，含根布局指标卡、图表卡片、文本卡片、筛选器和 panel 内卡片布局 |
 

package/skills/guanvis/evals/dynamic_fields/card_01_dynamic_dataset.js

@@ -0,0 +1,20 @@
+var region = f("区域");
+var city = f("城市");
+var sales = f("销售额", { aggrType: AggrType.SUM });
+var profit = f("利润", { aggrType: AggrType.SUM });
+
+var card = createCard(ChartType.GROUPED_COLUMN, "动态维度与动态数值")
+    .setId("dfcarddataset00000000000")
+    .bindDataset(DS)
+    .addDynamicRow("分析维度", [region, city], {
+        defaultValue: [region],
+        multiSelect: false
+    })
+    .addDynamicMetric("分析数值", [sales, profit], {
+        defaultValue: [sales],
+        multiSelect: true,
+        orderType: DynamicFieldOrder.CLICK
+    })
+    .setShowLegend(true, "bottom");
+
+registerCard(card.build());

package/skills/guanvis/evals/dynamic_fields/card_02_dynamic_metric_chart.js

@@ -0,0 +1,16 @@
+var region = metricDim("销售额", "区域");
+var city = metricDim("销售额", "城市");
+var sales = metric("销售额");
+var profit = metric("利润");
+
+var card = createMetricChart(ChartType.PIVOT_TABLE, "指标平台动态维度与动态指标")
+    .setId("dfmetriccard000000000000")
+    .addDynamicRow("分析维度", [region, city], {
+        defaultValue: [region]
+    })
+    .addDynamicMetric("分析指标", [sales, profit], {
+        defaultValue: [sales],
+        multiSelect: true
+    });
+
+registerMetricChart(card.build());

package/skills/guanvis/evals/dynamic_fields/metrics.js

@@ -0,0 +1,19 @@
+defineMetric({
+    id: "metric_sales_eval_000001",
+    name: "销售额",
+    subType: "ATOMIC",
+    applicableDims: [
+        { fdId: "region_fd", dsId: "ds_dynamic_fields_eval", name: "区域", fdType: "STRING", metaType: "DIM" },
+        { fdId: "city_fd", dsId: "ds_dynamic_fields_eval", name: "城市", fdType: "STRING", metaType: "DIM" }
+    ]
+});
+
+defineMetric({
+    id: "metric_profit_eval_00001",
+    name: "利润",
+    subType: "ATOMIC",
+    applicableDims: [
+        { fdId: "region_fd", dsId: "ds_dynamic_fields_eval", name: "区域", fdType: "STRING", metaType: "DIM" },
+        { fdId: "city_fd", dsId: "ds_dynamic_fields_eval", name: "城市", fdType: "STRING", metaType: "DIM" }
+    ]
+});

package/skills/guanvis/evals/dynamic_fields/page.js

@@ -0,0 +1,9 @@
+var page = createPage("动态字段示例")
+    .setId("dfpage000000000000000000")
+    .setDescription("验证动态维度、动态数值和指标平台动态指标的资源包结构。")
+    .setBackgroundColor("#f5f5f5")
+    .setCardMargin(8)
+    .addFullWidthCard(0, 7)
+    .addFullWidthCard(1, 7);
+
+registerPage(page.build());

package/skills/guanvis/evals/dynamic_fields/schema.js

@@ -0,0 +1,7 @@
+defineDataset("ds_dynamic_fields_eval", [
+    { fdId: "region_fd", name: "区域", fdType: "STRING", metaType: "DIM" },
+    { fdId: "city_fd", name: "城市", fdType: "STRING", metaType: "DIM" },
+    { fdId: "month_fd", name: "月份", fdType: "DATE", metaType: "DIM" },
+    { fdId: "sales_fd", name: "销售额", fdType: "DOUBLE", metaType: "METRIC" },
+    { fdId: "profit_fd", name: "利润", fdType: "DOUBLE", metaType: "METRIC" }
+], { displayType: "CSV" });

package/skills/guanvis/evals/dynamic_fields/verify_default_roundtrip.sh

@@ -0,0 +1,137 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
+EVAL_DIR="$ROOT_DIR/evals/dynamic_fields"
+OUT_DIR="$EVAL_DIR/.roundtrip"
+
+mkdir -p "$OUT_DIR"
+
+cd "$ROOT_DIR"
+
+go run ./cmd/guanvis preview "$EVAL_DIR" > "$OUT_DIR/preview_payload.json"
+go run ./cmd/guanvis pack "$EVAL_DIR" -o "$OUT_DIR/dynamic_fields_package.zip" > "$OUT_DIR/pack.log"
+
+if [[ "${PUBLISH:-0}" == "1" ]]; then
+    go run ./cmd/guanvis publish "$EVAL_DIR" > "$OUT_DIR/publish.log"
+    guancli card get dfcarddataset00000000000 --raw > "$OUT_DIR/raw_dataset_card.json"
+    guancli card get dfmetriccard000000000000 --raw > "$OUT_DIR/raw_metric_card.json"
+fi
+
+python3 - "$OUT_DIR" <<'PY'
+import json
+import sys
+from pathlib import Path
+
+out = Path(sys.argv[1])
+
+expected = {
+    "dfcarddataset00000000000": {
+        "name": "动态维度与动态数值",
+        "mappings": {
+            "分析维度": {"zoneId": "row", "metaType": "DIM", "multiSelect": False},
+            "分析数值": {"zoneId": "metric", "metaType": "METRIC", "multiSelect": True},
+        },
+    },
+    "dfmetriccard000000000000": {
+        "name": "指标平台动态维度与动态指标",
+        "mappings": {
+            "分析维度": {"zoneId": "row", "metaType": "DIM", "multiSelect": False},
+            "分析指标": {"zoneId": "metric", "metaType": "METRIC", "multiSelect": True},
+        },
+    },
+}
+
+def load_json(path):
+    text = path.read_text(encoding="utf-8")
+    start = text.find("{")
+    if start > 0:
+        text = text[start:]
+    return json.loads(text)
+
+def normalize_card(raw):
+    obj = raw.get("response") or raw.get("data") or raw
+    if "card" in obj:
+        card = obj["card"]
+        meta = json.loads(card["meta"]) if isinstance(card.get("meta"), str) else card.get("meta")
+        return {"id": card.get("cdId"), "name": card.get("name"), "meta": meta}
+    content = obj.get("content") or obj
+    return {"id": obj.get("cdId") or obj.get("id"), "name": obj.get("name"), "meta": content.get("meta")}
+
+def preview_cards():
+    payload = load_json(out / "preview_payload.json")
+    cards = []
+    for item in payload.get("cards", []):
+        card = item.get("card", {})
+        meta = json.loads(card["meta"]) if isinstance(card.get("meta"), str) else card.get("meta")
+        cards.append({"id": card.get("cdId"), "name": card.get("name"), "meta": meta})
+    return cards
+
+def assert_dynamic_card(card):
+    card_id = card["id"]
+    if card_id not in expected:
+        return None
+    spec = expected[card_id]
+    chart_main = (card.get("meta") or {}).get("chartMain") or {}
+    zone_data = chart_main.get("zoneData") or {}
+    dz_info = chart_main.get("dynamicZoneInfo") or {}
+    if dz_info.get("hidden") is not False:
+        raise SystemExit(f"{card_id}: dynamicZoneInfo.hidden={dz_info.get('hidden')!r}, want false")
+    mappings = dz_info.get("dzMappings") or []
+    by_name = {m.get("name"): m for m in mappings}
+    if set(by_name) != set(spec["mappings"]):
+        raise SystemExit(f"{card_id}: dzMappings names={sorted(by_name)}, want {sorted(spec['mappings'])}")
+
+    summary = {"cardId": card_id, "name": card.get("name"), "mappings": {}}
+    for name, want in spec["mappings"].items():
+        mapping = by_name[name]
+        for key, want_value in want.items():
+            got = mapping.get(key)
+            if got != want_value:
+                raise SystemExit(f"{card_id}: mapping {name} {key}={got!r}, want {want_value!r}")
+        if mapping.get("selectType") != "SEARCHBOX":
+            raise SystemExit(f"{card_id}: mapping {name} selectType={mapping.get('selectType')!r}, want SEARCHBOX")
+        if mapping.get("orderType") not in ("PRESET", "CLICK"):
+            raise SystemExit(f"{card_id}: mapping {name} invalid orderType={mapping.get('orderType')!r}")
+        dz_id = mapping.get("dzId")
+        defaults = mapping.get("defaultValue") or []
+        if not dz_id:
+            raise SystemExit(f"{card_id}: mapping {name} missing dzId")
+        if not defaults:
+            raise SystemExit(f"{card_id}: mapping {name} defaultValue is empty")
+        zone_fields = zone_data.get(mapping["zoneId"]) or []
+        candidate_keys = {f.get("key") for f in zone_fields if f.get("dzId") == dz_id}
+        if not candidate_keys:
+            raise SystemExit(f"{card_id}: mapping {name} has no zoneData candidates for dzId={dz_id}")
+        missing = [key for key in defaults if key not in candidate_keys]
+        if missing:
+            raise SystemExit(f"{card_id}: mapping {name} defaultValue keys {missing} not found in zoneData.{mapping['zoneId']}")
+        summary["mappings"][name] = {
+            "dzId": dz_id,
+            "zoneId": mapping["zoneId"],
+            "metaType": mapping["metaType"],
+            "multiSelect": mapping["multiSelect"],
+            "defaultValue": defaults,
+            "candidateCount": len(candidate_keys),
+        }
+    return summary
+
+summaries = []
+for card in preview_cards():
+    result = assert_dynamic_card(card)
+    if result:
+        summaries.append(result)
+
+if len(summaries) != len(expected):
+    got = sorted(item["cardId"] for item in summaries)
+    raise SystemExit(f"preview dynamic card count={len(summaries)}, got {got}, want {sorted(expected)}")
+
+if (out / "raw_dataset_card.json").exists() and (out / "raw_metric_card.json").exists():
+    for raw_name in ("raw_dataset_card.json", "raw_metric_card.json"):
+        raw_summary = assert_dynamic_card(normalize_card(load_json(out / raw_name)))
+        summaries.append({**raw_summary, "source": raw_name})
+
+summary = {"cards": summaries}
+(out / "summary.json").write_text(json.dumps(summary, ensure_ascii=False, indent=2), encoding="utf-8")
+print(json.dumps(summary, ensure_ascii=False, indent=2))
+PY

package/skills/guanvis/evals/split_charts/card_01_column_split.js

@@ -0,0 +1,10 @@
+var card = createCard(ChartType.BASIC_COLUMN, "按产品拆分区域营收")
+    .setId("spcolsplitdemoaabbccddee")
+    .bindDataset(DS)
+    .addRow(f("区域"))
+    .addMetric(f("营收", { aggrType: AggrType.SUM, numberFormat: NumberFormat.currency("¥", 0) }))
+    .addSplit(f("产品"))
+    .setSplitSetting({ rows: 2, columns: 3 })
+    .setDataLabel({ show: true, showNumber: true });
+
+registerCard(card.build());

package/skills/guanvis/evals/split_charts/card_02_line_split.js

@@ -0,0 +1,10 @@
+var card = createCard(ChartType.BASIC_LINE, "按产品拆分月营收趋势")
+    .setId("splinesplitdemoaabbccdde")
+    .bindDataset(DS)
+    .addRow(f("月份", { granularity: "MONTH" }))
+    .addMetric(f("营收", { aggrType: AggrType.SUM, numberFormat: NumberFormat.currency("¥", 0) }))
+    .addSplit(f("产品"))
+    .setSplitSetting({ rows: 2, columns: 3 })
+    .setShowLegend(false);
+
+registerCard(card.build());

package/skills/guanvis/evals/split_charts/card_03_combo_split.js

@@ -0,0 +1,11 @@
+var card = createCard(ChartType.GROUPED_COLUMN_WITH_LINE, "按产品拆分营收成本趋势")
+    .setId("spcombosplitdemoaabbccdd")
+    .bindDataset(DS)
+    .addRow(f("月份", { granularity: "MONTH" }))
+    .addMetric(f("营收", { aggrType: AggrType.SUM, numberFormat: NumberFormat.currency("¥", 0) }))
+    .addMetricAdditional(f("成本", { aggrType: AggrType.SUM, numberFormat: NumberFormat.currency("¥", 0) }))
+    .addSplit(f("产品"))
+    .setSplitSetting({ rows: 2, columns: 2 })
+    .setShowLegend(true, "bottom");
+
+registerCard(card.build());

package/skills/guanvis/evals/split_charts/page.js

@@ -0,0 +1,10 @@
+var page = createPage("拆分图示例")
+    .setId("sppagesplitdemoaabbccdde")
+    .setDescription("展示柱形、折线和柱线组合图的 addSplit 用法。")
+    .setBackgroundColor("#f5f5f5")
+    .setCardMargin(8)
+    .addFullWidthCard(0, 6)
+    .addFullWidthCard(1, 6)
+    .addFullWidthCard(2, 6);
+
+registerPage(page.build());

package/skills/guanvis/evals/split_charts/schema.js

@@ -0,0 +1,14 @@
+// Auto-generated by guanvis schema command
+// DO NOT EDIT — regenerate with: guanvis schema s9ded2338f43807b095fbb4f
+// This file defines dataset schemas for field() references in card scripts.
+
+// Dataset: 销售数据 (example, 7 fields)
+defineDataset("s9ded2338f43807b095fbb4f", [
+    { fdId: "jb16f22f6c1c21c3f6e8e293", name: "区域", fdType: "STRING", metaType: "DIM" },
+    { fdId: "o7093aaf2b2f32c9e964c41a", name: "产品", fdType: "STRING", metaType: "DIM" },
+    { fdId: "p2670dd6b74fc78c3e9c57ad", name: "月份", fdType: "DATE", metaType: "DIM" },
+    { fdId: "lb1c31b4dc86511a27049a98", name: "营收", fdType: "DOUBLE", metaType: "METRIC" },
+    { fdId: "aece10cd6806966be56f52ff", name: "成本", fdType: "DOUBLE", metaType: "METRIC" },
+    { fdId: "g1b16b52a16eb10c5e26d4bb", name: "数量", fdType: "INT", metaType: "METRIC" },
+    { fdId: "eae7cae6fbdcde68acdf5d1f", name: "利润率", fdType: "DOUBLE", metaType: "METRIC" }
+], { displayType: "EXCEL" });

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

@@ -11,12 +11,18 @@
 | `.addColumn(field)` | 添加列维度（按维度分组着色，如按地区/类别分色）。仅 `STACKED_COLUMN`、`GROUPED_COLUMN`、`GROUPED_BAR` 等多指标图表支持 |
 | `.addMetric(field)` | 添加度量（Y 轴，主轴） |
 | `.addMetricAdditional(field)` | 添加副轴度量（仅组合图 `*_WITH_LINE`/`*_WITH_SYMBOL`），默认绑定副 Y 轴（`plotOn: secondary`） |
+| `.addDynamicRow(name, fields, options?)` | 添加动态维度组，候选字段写入 row |
+| `.addDynamicColumn(name, fields, options?)` | 添加动态维度组，候选字段写入 column |
+| `.addDynamicMetric(name, fields, options?)` | 添加动态数值组，候选字段写入 metric |
+| `.addDynamicMetricAdditional(name, fields, options?)` | 添加动态数值组，候选字段写入副轴 |
 | `.addColorBy(field)` | 按指标值渐变着色（接受度量字段，不是维度）|
 | `.addTooltip(field)` / `.addFilter(field)` | 提示/筛选 |
 | `.addSort(field)` / `.addSplit(field)` / `.addSize(field)` | 排序/拆分/大小 |
 | `.addLocation(field)` / `.addTarget(field)` / `.addCompare(field)` | 位置/目标/对比 |
 | `.setSplitSetting({ rows, columns })` | 拆分行列数（默认各 3），需配合 `.addSplit(field)` |
 | `.setColorByColors(preset_or_config)` | colorBy 渐变色。传 `ColorByPreset.RedGreen` 等预设名称，或 `{ startColor, endColor, middleColor?, steps? }` 自定义 hex 颜色 |
+| `.setShapeColorType(type)` | 图形填充方式。默认不调用为纯色；支持 `ShapeColorType.TransparentGradient`，仅用于前端已支持的柱/条类图表 |
+| `.setShowTitle(show)` | 是否显示卡片标题；隐藏标题用 `.setShowTitle(false)` |
 | `.setShowLegend(show, position)` | 图例 |
 | `.setDataLabel(config)` | 数据标签 |
 | `.setAxis(config)` | 轴配置（见下方 Axis Config 详解） |
@@ -29,6 +35,19 @@
 | `.setRawSettings(key, value)` | 原始设置 |
 | `.build()` | 构建（触发验证） |
 
+动态字段是显式能力，不会根据同一区域多个字段自动推断。只有调用 `.addDynamicRow()` / `.addDynamicColumn()` / `.addDynamicMetric()` / `.addDynamicMetricAdditional()` 时，才会生成 `zoneData.*[].dzId` 和 `meta.chartMain.dynamicZoneInfo`。
+
+动态字段 `options`：
+
+| 字段 | 默认值 | 说明 |
+|---|---|---|
+| `defaultValue` | 第一个候选字段 | 推荐传候选数组里的字段对象；字符串只在唯一命中 `name` / `alias` / `fdId` / `id` 时可用 |
+| `multiSelect` | 根据 zone `maxCount` 推断 | `maxCount=1` 时强制单选；维度切换常建议显式写 `false` |
+| `orderType` | `DynamicFieldOrder.PRESET` | `PRESET` 按预置顺序，`CLICK` 按用户点击顺序 |
+| `id` | 自动生成 | 可选，显式指定 `dzId`，用于稳定 diff |
+
+`hidden` 和 `selectType` 不开放配置；资源包固定写 `hidden: false`、`selectType: "SEARCHBOX"`。动态字段不写 `stateValue.dzFieldValues`，前端加载卡片时会根据 `dynamicZoneInfo.dzMappings.defaultValue` 初始化默认选中值。
+
 ### MetricChartBuilder（指标平台指标卡片）
 
 用于“用指标平台已有指标创建卡片”，生成后端 `CARD_TYPE.METRIC_CHART`（`cdType=13`）。不要用普通 `createCard()` 伪造，也不要把指标 ID 当作数据集字段。
@@ -45,8 +64,10 @@
 | `.setId(cardId)` | 设置 24 位资源 ID，用于重复导入覆盖 |
 | `.addRow(field)` / `.addColumn(field)` | 添加指标适用维度 |
 | `.addMetric(metric)` | 添加指标平台指标；至少一个 |
+| `.addDynamicRow(name, fields, options?)` / `.addDynamicColumn(name, fields, options?)` | 添加指标平台动态维度组 |
+| `.addDynamicMetric(name, fields, options?)` / `.addDynamicMetricAdditional(name, fields, options?)` | 添加指标平台动态指标组 |
 | `.addFilter(field, filterType, filterValue)` / `.addSort(field)` | 添加筛选/排序 |
-| `.setShowLegend()` / `.setDataLabel()` / `.setAxis()` / `.setTableSetting()` / `.setRawSettings()` | 常用图表设置，和普通 CardBuilder 一致 |
+| `.setShowTitle()` / `.setShowLegend()` / `.setDataLabel()` / `.setAxis()` / `.setTableSetting()` / `.setRawSettings()` | 常用图表设置，和普通 CardBuilder 一致 |
 | `.setProps(obj)` / `.setRawProps(key, value)` | 设置指标卡片 `meta.chartMain.props` |
 | `.setConfig(obj)` / `.setRawConfig(key, value)` | 设置指标卡片 `meta.chartMain.config` |
 | `.setSummary(obj)` | 设置指标卡片 `meta.summary` |
@@ -66,6 +87,21 @@ var card = createMetricChart(ChartType.PIVOT_TABLE, "销售指标分析")
 registerMetricChart(card.build());
 ```
 
+#### Shape Color Type（图形填充方式）
+
+`setShapeColorType()` 控制柱子/条形等图形本身的填充方式，和 `.addColorBy()` / `.setColorByColors()` 的“按度量值渐变着色”不同。默认不调用时保持 BI 默认纯色。
+
+```javascript
+var card = createCard(ChartType.BASIC_COLUMN, "区域销售额")
+    .setId("card12345678901234567890")
+    .bindDataset(DS)
+    .addRow(f("区域"))
+    .addMetric(f("销售额", { aggrType: AggrType.SUM }))
+    .setShapeColorType(ShapeColorType.TransparentGradient);
+```
+
+支持的图表：`BASIC_COLUMN`、`BASIC_BAR`、`GROUPED_COLUMN`、`GROUPED_BAR`、`GROUPED_COLUMN_WITH_LINE`、`GROUPED_COLUMN_WITH_SYMBOL`、`BULLET_BAR`。
+
 多指标示例：
 
 ```javascript
@@ -289,11 +325,13 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 
 **布局单位**：
 1. 默认横向使用 12 列栅格；开启精细模式后使用 60 列栅格。
-2. 推荐通过 `.setFineMode(true)` 设置为精细模式，且必须在任何 `addRow()` / `placeCard()` / `addTab()` / `addAreaTitle()` / `addCardGroup()` 等布局方法之前调用。
+2. 推荐通过 `.setFineMode(true)` 设置为精细模式，且必须在任何 `addRow()` / `placeCard()` / `addTab()` / `addAreaTitle()` / `addCardGroup()` / `addSelectorGroup()` 等布局方法之前调用。
 3. `addRow()` 及其快捷方法的 `height` 省略或为 0 时使用默认行高（普通 6，精细 18）。
 4. 区域小标题用 `createAreaTitle(...).setId(...).build()` 定义，并通过 `page.addAreaTitle(title)` 放在 Page 根布局；不要放进 tab panel。
 5. 卡片组用 `createCardGroup(...).setId(...)` 定义，并通过 `page.addCardGroup(group)` 放在 Page 根布局。
-6. 下文布局 API 中的 `cardRef` 表示：非 selector 卡片的数字 index，或已注册 selector 的字符串 ID。`registerSelector()` 不参与数字 index 计数；被布局引用的 selector 不再进入同页筛选器栏。
+6. 筛选器组用 `createSelectorGroup(...).setId(...)` 定义；画布组通过 `page.addSelectorGroup(group)` 放在 Page 根布局，筛选栏组通过 `page.addFilterSelectorGroup(group)` 加入筛选栏，未分组 selector 可通过 `page.addFilterSelector(selectorId)` 显式控制顺序；组内只能放 selector。checkout 后修改已有快捷筛选区时，优先用 `setFilterLayout()` / `clearFilterLayout()` / `addFilterLayoutItem()` / `insertFilterSelector()` / `removeFilterSelector()` / `moveFilterSelector()` 表达增量操作；筛选器或筛选器组需要在快捷筛选区和画布之间移动时，优先用动作级 `moveFilterSelectorToCanvas()` / `moveCanvasSelectorToFilter()` / `moveSelectorGroupToCanvas()` / `moveCanvasSelectorGroupToFilter()`，不要手改 base JSON。
+7. checkout 生成的根布局组件会使用 `page.placeTab()` / `placeAreaTitle()` / `placeCardGroup()` / `placeSelectorGroup()` 保留线上 x/y/w/h；新建工程通常继续用 `addTab()` / `addAreaTitle()` / `addCardGroup()` / `addSelectorGroup()` 自动满宽布局。
+8. 下文布局 API 中的 `cardRef` 表示：推荐使用已注册卡片或 selector 的字符串 ID；数字 index 仍可用于非 selector 卡片，按可布局资源注册顺序计数。`registerSelector()` 不参与数字 index 计数；被布局引用的 selector 不再进入同页筛选器栏。
 
 | 方法 | 说明 |
 |------|------|
@@ -309,6 +347,24 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.addTab(tab, height?)` | 添加一个满宽 tab 容器；不传 height 时按第一个 panel 内容自动推导 |
 | `.addAreaTitle(areaTitle, height?)` | 添加一个满宽区域小标题|
 | `.addCardGroup(group, height?)` | 添加一个满宽卡片组；不传 height 时按标题和组内布局自动推导 |
+| `.addSelectorGroup(group, height?)` | 添加一个满宽画布筛选器组；不传 height 时按展示模式、标题和组内布局自动推导 |
+| `.placeTab(tab, x, y, w, h)` | checkout/精确布局用：注册 tab 并按显式坐标放入 Page 根布局 |
+| `.placeAreaTitle(areaTitle, x, y, w, h)` | checkout/精确布局用：注册区域小标题并按显式坐标放入 Page 根布局 |
+| `.placeCardGroup(group, x, y, w, h)` | checkout/精确布局用：注册卡片组并按显式坐标放入 Page 根布局 |
+| `.placeSelectorGroup(group, x, y, w, h)` | checkout/精确布局用：注册画布筛选器组并按显式坐标放入 Page 根布局 |
+| `.removeLayoutItem(cardRef)` | 从当前 Page 根布局移除已放置的 card/selector/layout component；主要给动作级移动 API 使用 |
+| `.addFilterSelectorGroup(group)` | 添加一个筛选栏筛选器组 |
+| `.addFilterSelector(selectorId)` | 显式添加一个未分组的筛选栏 selector，并控制其与筛选器组的顺序 |
+| `.setFilterLayout(items)` | 整体设置快捷筛选区的 selector / filter selectorGroup ID 列表；checkout 场景会覆盖 base `filterLayout` |
+| `.clearFilterLayout()` | 清空快捷筛选区；常用于把已有快捷筛选器改成画布内普通筛选器卡片 |
+| `.addFilterLayoutItem(items)` | 向快捷筛选区追加 selector / filter selectorGroup ID，已存在则跳过 |
+| `.insertFilterLayoutItem(index, items)` / `.insertFilterSelector(index, selectorId)` | 在快捷筛选区指定位置插入 |
+| `.removeFilterLayoutItem(id)` / `.removeFilterSelector(selectorId)` | 从快捷筛选区移除已有 selector / filter selectorGroup ID |
+| `.moveFilterLayoutItem(id, index)` / `.moveFilterSelector(selectorId, index)` | 调整快捷筛选区已有项顺序 |
+| `.moveFilterSelectorToCanvas(selectorId, x, y, w, h)` | 动作级：从快捷筛选区移除 selector，并按坐标放到 Page 画布，联动配置保留在 selector 卡片本身 |
+| `.moveCanvasSelectorToFilter(selectorId, index?)` | 动作级：从 Page 根布局移除 selector，并加入快捷筛选区；传 `index` 时插入指定位置，否则追加 |
+| `.moveSelectorGroupToCanvas(group, x, y, w, h)` / `.moveFilterSelectorGroupToCanvas(group, x, y, w, h)` | 动作级：把筛选栏 SelGroup 转换成画布 SelGroup，并从快捷筛选区移除 |
+| `.moveCanvasSelectorGroupToFilter(group, index?)` | 动作级：把画布 SelGroup 转换成筛选栏 SelGroup，并从 Page 根布局移除；组内布局必须引用 selector ID 字符串 |
 | `.setBackgroundColor(color)` | 页面背景色 |
 | `.setCardMargin(margin)` | 卡片间距 |
 | `.setFineMode(enabled)` | 开启/关闭精细模式 |
@@ -324,6 +380,7 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 |------|------|
 | `createAreaTitle(name)` | 创建区域小标题，`name` 即为标题的内容，会被写入该组件的 style 中，必须要传 name |
 | `.setId(areaTitleId)` | **必填**。设置区域小标题 ID，必须以 `areaTitle_` 开头 |
+| `.setRawStyle(style)` | checkout 保留线上 style 用；新建工程优先用下列语义化方法 |
 | `.setShowTitle(boolean)` | 是否显示标题 |
 | `.setFontSize(number)` | 字号 |
 | `.setColor(color)` | 字体颜色 |
@@ -358,6 +415,7 @@ registerPage(page.build());
 |------|------|
 | `createCardGroup(name)` | 创建卡片组，`name` 写入分组标题 |
 | `.setId(cardGroupId)` | **必填**。设置卡片组 ID，必须以 `cardGroup_` 开头 |
+| `.setRawStyle(style)` | checkout 保留线上 style 用；新建工程优先用 `.setShowTitle()` 等语义化方法 |
 | `.setShowTitle(boolean)` | 是否显示标题，默认 `true` |
 | `.addRow(specs, height?)` | 在组内按行放置卡片，写法同 `PageBuilder.addRow()` |
 | `.addFullWidthCard(cardRef, height?)` | 在组内放一张满宽卡片 |
@@ -378,6 +436,57 @@ var page = createPage("销售仪表板")
 registerPage(page.build());
 ```
 
+### SelectorGroupBuilder
+
+`SelGroup` 是原生筛选器组，不是 Card，不绑定数据集，也不会生成独立 page-card relation。ID 必须以 `selGroup_` 开头，使用 `guanvis gen-layout-id selGroup` 生成。画布 SelGroup 只能放入 Page 根布局；筛选栏 SelGroup 只能放入 `filterLayout`；组内只能包含已注册 selector。
+
+默认值：`displayMode = "tiled"`、`showTitle = false`、`titleStyle.fontSize = 14`、`titleStyle.bold = true`。筛选栏组名始终来自 `name`，不受 `showTitle` 控制。
+
+| 方法 | 说明 |
+|------|------|
+| `createSelectorGroup(name)` | 创建筛选器组，`name` 必填 |
+| `.setId(selGroupId)` | **必填**。设置筛选器组 ID，必须以 `selGroup_` 开头 |
+| `.setRawStyle(style)` | checkout 保留线上 style 用；新建工程优先用 `.setDisplayMode()` / `.setShowTitle()` / `.setFpWidth()` |
+| `.setDisplayMode(mode)` | 展示模式：`SelectorGroupDisplayMode.TILED`（默认）或 `SelectorGroupDisplayMode.DROPDOWN` |
+| `.setShowTitle(boolean)` | 是否显示画布组标题；默认 `false` |
+| `.setFpWidth(width)` | 筛选栏非栅格模式宽度，仅筛选栏组有效 |
+| `.setFpGrid(span)` | 筛选栏栅格模式宽度，仅筛选栏组有效 |
+| `.addSelector(selectorId)` / `.addSelectors(selectorIds)` | 添加筛选栏组内 selector；使用后只能传给 `page.addFilterSelectorGroup()` |
+| `.addRow(specs, height?)` | 添加画布组内 selector 布局，写法同 `PageBuilder.addRow()`；height 省略或为 0 时 selector 高度默认普通 1、精细 3；使用后只能传给 `page.addSelectorGroup()` |
+| `.addFullWidthCard(cardRef, height?)` | 在画布组内放一个满宽 selector |
+| `.placeCard(cardRef, x, y, w, h)` | 在画布组内精确放置 selector |
+
+画布下拉筛选器组：
+
+```javascript
+var advanced = createSelectorGroup("高级筛选")
+    .setId("selGroup_AbCdEf")
+    .setDisplayMode(SelectorGroupDisplayMode.DROPDOWN)
+    .setShowTitle(true)
+    .addRow([
+        { card: "ssssssssssssssssssssssss", w: 6 },
+        { card: "tttttttttttttttttttttttt", w: 6 }
+    ]);
+
+var page = createPage("销售仪表板")
+    .setId("p184352b7a76776db5f534df")
+    .addSelectorGroup(advanced);
+```
+
+筛选栏筛选器组与未分组筛选器混排：
+
+```javascript
+var globalFilters = createSelectorGroup("全局筛选")
+    .setId("selGroup_GhIjKl")
+    .addSelector("ssssssssssssssssssssssss")
+    .addSelector("tttttttttttttttttttttttt");
+
+var page = createPage("销售仪表板")
+    .setId("p184352b7a76776db5f534df")
+    .addFilterSelectorGroup(globalFilters)
+    .addFilterSelector("uuuuuuuuuuuuuuuuuuuuuuuu");
+```
+
 #### 页面密度尺寸建议
 
 以下尺寸建议以非精细模式的 12 列布局单位为基准，用于生成页面时选择页面卡片间距和常见卡片高度。精细模式目前只定义横向 60 列栅格与显式 `x/y/w/h` 放置规则，暂不提供独立的密度尺寸换算规则。
@@ -404,6 +513,9 @@ tab 用于把页面中的卡片分到多个 panel。适合同一主题下多组
 |------|------|
 | `createTab(name)` | 创建 tab 容器；`name` 用于脚本可读性，页面上显示的是各 panel 的 name |
 | `.setId(tabId)` | **必填**。设置 tab ID，必须以 `tab_` 开头且同一页面内唯一。建议用 `guanvis gen-layout-id tab` 生成 |
+| `.setRawStyle(style)` | checkout 保留线上 tab style 用；新建工程优先用下列语义化方法 |
+| `.setRawPanelStyle(panelStyle)` | checkout 保留线上 panelStyle 用 |
+| `.setRawLayoutItemMap(layoutItemMap)` | checkout 保留线上 tab 内 layoutItemMap 用 |
 | `.addPanel(name, callback)` | 添加 panel；callback 接收 `panel` 配置对象，必须在其中放入至少一张卡片 |
 | `.setLabelStyle(style)` | 设置标签样式：`TabLabelStyle.UNDERLINE`（默认）、`CARD`、`CAPSULE`、`TRAPEZOID` |
 | `.setAlignment(alignment)` | 设置标签对齐：`TabAlignment.LEFT`（默认）、`CENTER`、`RIGHT` |
@@ -1080,6 +1192,7 @@ option = {
 | `FieldType` | `STRING`, `INT`, `LONG`, `DOUBLE`, `FLOAT`, `DATE`, `BOOL`, `DECIMAL` | 字段数据类型 |
 | `SortOrder` | `ASC`, `DESC` | 排序方向 |
 | `Granularity` | `NONE`, `YEAR`, `QUARTER`, `MONTH`, `WEEK`, `DAYOFWEEK`, `DAY`, `HOUR`, `MINUTE`, `SECOND` | 日期粒度 |
+| `DynamicFieldOrder` | `PRESET`, `CLICK` | 动态字段默认顺序；`PRESET` 按候选顺序，`CLICK` 按用户选择顺序 |
 | `FilterType` | `IN`, `NOT_IN`, `GT`, `GE`, `LT`, `LE`, `EQ`, `NE`, `BT`（区间）, `CONTAINS`, `NOT_CONTAINS`, `STARTSWITH`, `ENDSWITH`, `IS_NULL`, `NOT_NULL` | 筛选条件类型 |
 | `FilterLevel` | `DETAIL`（明细）, `AGGREGATION`（聚合）, `RESULT`（结果） | 筛选级别 |
 | `NumberFormat` | `.number()`, `.currency()`, `.percentage()`, `.auto()`, `.custom()` | 数值格式化工厂 |

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

@@ -160,6 +160,10 @@ registerMetricChart(card.build());
 | `.addMetricAdditional(metric(...))` | 添加副轴指标 |
 | `.addRow(metricDim(...))` | 添加行/类目维度 |
 | `.addColumn(metricDim(...))` | 添加列/对比维度 |
+| `.addDynamicRow(name, fields, options?)` | 添加动态维度组，候选字段写入 row |
+| `.addDynamicColumn(name, fields, options?)` | 添加动态维度组，候选字段写入 column |
+| `.addDynamicMetric(name, fields, options?)` | 添加动态指标组，候选指标写入 metric |
+| `.addDynamicMetricAdditional(name, fields, options?)` | 添加动态指标组，候选指标写入副轴 |
 | `.addFilter(field, type, values)` | 添加筛选 |
 | `.addSort(field)` | 添加排序 |
 | `.addColorBy(metric(...))` | 添加颜色指标 |
@@ -174,6 +178,42 @@ registerMetricChart(card.build());
 | `.setFreeDrill(enabled, position)` | 设置 `config.freeDrillConfig` |
 | `.setRowThreshold(thresholds)` | 设置 `config.rowThreshold` |
 
+## 动态维度 / 动态指标
+
+动态字段是显式能力。只有调用 `.addDynamicRow()` / `.addDynamicColumn()` / `.addDynamicMetric()` / `.addDynamicMetricAdditional()` 时，guanvis 才会生成候选字段的 `dzId` 和 `meta.chartMain.dynamicZoneInfo`；普通 `.addRow()` / `.addMetric()` 仍生成静态字段。
+
+```javascript
+var region = metricDim("销售额", "区域");
+var city = metricDim("销售额", "城市");
+var sales = metric("销售额");
+var profit = metric("利润");
+
+var card = createMetricChart(ChartType.PIVOT_TABLE, "指标动态分析")
+    .setId("metriccard12345678901234")
+    .addDynamicRow("分析维度", [region, city], {
+        defaultValue: [region],
+        multiSelect: false
+    })
+    .addDynamicMetric("分析指标", [sales, profit], {
+        defaultValue: [sales],
+        multiSelect: true,
+        orderType: DynamicFieldOrder.CLICK
+    });
+
+registerMetricChart(card.build());
+```
+
+`options`：
+
+| 字段 | 默认值 | 说明 |
+|---|---|---|
+| `defaultValue` | 第一个候选字段 | 推荐传候选数组里的字段对象；字符串只在唯一命中 `name` / `alias` / `fdId` / `id` 时可用 |
+| `multiSelect` | 根据 zone `maxCount` 推断 | `maxCount=1` 时强制单选；指标卡 row 默认单选 |
+| `orderType` | `DynamicFieldOrder.PRESET` | `PRESET` 按候选顺序，`CLICK` 按用户点击顺序 |
+| `id` | 自动生成 | 可选，显式指定 `dzId`，用于稳定 diff |
+
+`hidden` 和 `selectType` 不开放配置；资源包固定写 `hidden: false`、`selectType: "SEARCHBOX"`。动态字段不写 `stateValue.dzFieldValues`，前端加载卡片时会根据 `dynamicZoneInfo.dzMappings.defaultValue` 初始化默认选中值。
+
 复杂配置可直接放到 `metric()` / `metricDim()` 的 overrides 中：
 
 ```javascript

package/skills/guanvis/references/publish-and-constraints.md

@@ -5,7 +5,7 @@
 - **接口**：`POST /api/manual/template/transfer`（标准 multipart/form-data，表单字段名 `new-file`）
 - **认证**：随底层 `guancli fetch` 使用 `Cookie: uIdToken=...`
 - **关键 header**：`raw-backend-response: TRUE`（绕过前端代理层，直达后端）
-- **ID 策略**：`needIdMapping=false`，保持资源 ID 不变。同 ID 资源会被覆盖更新。为避免部分 BI 版本在导入前探测 Card 时缓存"找不到相关卡片"，`guanvis publish/upload` 的在线覆盖检查只探测目标环境已有 Page ID；检测到同 ID Page 时默认拒绝上传，只有明确加 `--allow-overwrite` 才允许覆盖。加 `--allow-overwrite` 后，CLI 会先调用资源包导出为冲突 Page 生成备份记录，并等待导出成功；备份失败或超时则中止上传。Card/Selector ID 不做在线探测；如果资源包不包含 Page，则不会执行在线覆盖检查。更新已有仪表板时应按新版本策略生成新的 Page/Card/Selector ID。
+- **ID 策略**：`needIdMapping=false`，保持资源 ID 不变。同 ID 资源会被覆盖更新。为避免部分 BI 版本在导入前探测 Card 时缓存"找不到相关卡片"，`guanvis publish/upload` 的在线覆盖检查只探测目标环境已有 Page ID；检测到同 ID Page 时默认拒绝上传，只有明确加 `--allow-overwrite` 才允许覆盖。加 `--allow-overwrite` 后，CLI 会先调用资源包导出为冲突 Page 生成备份记录，并等待导出成功；备份失败或超时则中止上传。Card/Selector ID 不做在线探测；如果资源包不包含 Page，则不会执行在线覆盖检查。checkout 工程表示修改指定 Page，不在 CLI 内复制新版本或手写 ID 映射。
 - **通用性**：不需要目标系统开启"一键迁移"开关，所有客户环境可用
 - **异步执行**：上传成功后返回 `taskId`，后端异步完成导入
 
@@ -13,7 +13,7 @@
 
 若用户要求批量重绑资源、迁移已有页面或复用线上页面结构，先说明风险并确认方案；不要直接修改 ZIP 内部文件后上传。
 
-修改或重新发布已存在的仪表板资源时，默认按“新版本仪表板”处理：先从目标 BI 线上环境同步最新资源状态，再基于同步后的内容生成新的 Page/Card/Selector ID，并给仪表板名称追加版本号后发布。用户可能已经在 BI 上手工改过页面布局、卡片配置、筛选器或说明文本；如果只按本地旧文件 `publish`，同 ID 资源会被覆盖，导致线上改动丢失。只有用户明确要求覆盖原资源时，才允许保留原 ID 并同 ID 发布。
+checkout 工程表示“基于线上快照修改指定 Page”，不会新建 Page，也不要通过复制 checkout JSON、改 ID 或自建 ID map 来生成新版本。若用户要求保留原页面并另存新版本，应先调用 BI 自身 Page Save/复制能力，由 BI 处理资源 ID 映射，再对新 Page 执行 checkout/edit。用户可能已经在 BI 上手工改过页面布局、卡片配置、筛选器或说明文本；如果按旧 checkout 工程同 ID `publish`，线上改动会被覆盖。发布前应使用 `--dry-run` 检查覆盖对象，只有用户明确要求覆盖原资源时，才允许加 `--allow-overwrite` 同 ID 发布。
 
 ## 认证与 CLI 集成
 
@@ -23,7 +23,7 @@
 
 ## 硬约束
 
-- `schema.js` 由 `init` 命令自动生成，不允许 AI 或人工修改。
+- `schema.js` 由 `init` 命令生成；`checkout` 会尽量生成 schema，但数据集无权限、已删除或跨环境残留时只提示 warning 并继续生成可编辑工程。不允许 AI 或人工修改 `schema.js`，缺失时后续用 `guanvis init <dsId> -d <dir> --force` 补齐。
 - card 脚本必须调用 `registerCard(card.build())`（目录模式）或返回 `card.build()`（单文件模式）。
 - metric chart 脚本必须调用 `registerMetricChart(card.build())`。
 - text card 脚本必须调用 `registerTextCard(textCard.build())`。
@@ -48,6 +48,7 @@
 
 - `.setId(id)` 的 ID **必须**为严格 24 位字母数字字符串（正则：`^[a-zA-Z0-9]{24}$`），与后端 `RandUtil.uuid` 格式一致。若生成或手填的 ID 以数字开头，建议重新生成一组，避免 BI 前端某些路径把 ID 拼成 CSS selector（如 `#5bef...`）时触发 `querySelector` 语法错误。
 - **生成 ID**：先运行 `guanvis genid <数量>` 生成足够的 ID，在编写脚本时直接填入每个 card/selector/page 的 `.setId()` 调用中。
-- **线上更新默认策略**：已发布过或线上正在使用的仪表板，后续修改默认生成新的 Page/Card/Selector ID，并给 Page 名称追加版本号后发布，保留旧版本不覆盖。
+- **布局组件 ID 例外**：Tab、Panel、AreaTitle、CardGroup、SelGroup 使用 `guanvis gen-layout-id <prefix>` 生成，形如 `tab_AbCdEf`、`panel_AbCdEf`、`areaTitle_AbCdEf`、`cardGroup_AbCdEf`、`selGroup_AbCdEf`，不适用 24 位 `genid` 规则。
+- **线上更新默认策略**：新建工程发布新 Page；checkout 工程只修改 checkout 指定的 Page，不负责复制新版本。
 - **覆盖前检查**：发布前可先运行 `guanvis publish <dir> --dry-run` 或 `guanvis upload <zip> --dry-run`，只构建/解析资源并列出将被覆盖的线上 Page，不提交 transfer 任务。
-- **显式覆盖场景**：只有用户明确要求覆盖原仪表板时，才保持 `.setId()` 不变，并在 `publish/upload` 时加 `--allow-overwrite` 允许同 ID Page 覆盖；多次同 ID 发布会覆盖资源（因为 transfer API 的 `needIdMapping=false`），其中 Card/Selector ID 不做在线覆盖检查。覆盖前备份只创建资源迁移导出记录并打印 packageId，不自动下载资源包；需要回滚时，用户应到 BI 资源迁移导出记录中下载该资源包，再手动导入覆盖回去。
+- **显式覆盖场景**：checkout 工程发布时保持 `.setId()` 不变，并在用户确认覆盖后加 `--allow-overwrite` 允许同 ID Page 覆盖；多次同 ID 发布会覆盖资源（因为 transfer API 的 `needIdMapping=false`），其中 Card/Selector ID 不做在线覆盖检查。覆盖前备份只创建资源迁移导出记录并打印 packageId，不自动下载资源包；需要回滚时，用户应到 BI 资源迁移导出记录中下载该资源包，再手动导入覆盖回去。