@guandata/guanvis 0.1.35 → 0.1.37

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## @guandata/guanvis 0.1.37 - 2026-08-07
+
+- 发布前新增字段 `fdId` 线上活性校验，提前发现无效字段绑定，降低发布失败风险。
+- 完善筛选器配置，支持更完整的筛选设置与组合使用场景。
+- 优化页面布局及组合图配置，提升图表构建与导出结果的稳定性。
+- 补充构建器、图表属性、指标图表和编辑流程文档，改善使用体验。
+## @guandata/guanvis 0.1.36 - 2026-08-04
+
+- 扩展仪表板标题、页面背景、筛选栏、卡片组、Tab 和分区的视觉配置，支持字体、颜色、图标、背景图、间距与分割线。
+- 表格可配置主题、斑马纹、边框、表头和数据区样式；柱形图和条形图可调整柱宽、间距和圆角。
+- 本地图片可随页面资源打包上传，检出已有页面后也能保留并继续编辑线上视觉配置。
+- 增强已有页面覆盖发布前的备份与兼容判断，降低不同 BI 版本下的误覆盖风险。
+
 ## @guandata/guanvis 0.1.35 - 2026-07-29
 
 - 补齐常用图表属性配置，支持背景、标题、图例、坐标轴、标签、辅助线、主题色和动态参数默认值等能力。

package/README.md

@@ -50,10 +50,23 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 `guanvis upload` 只是上传器，不是自定义资源包制作入口。资源包应由 DSL 源文件通过 `guanvis pack` / `guanvis publish` 生成；不要手工生成、解包修改或重打包 ZIP。需要批量重绑资源或迁移已有页面时，先确认方案，不要直接改 ZIP 上传。
 
-使用 `--allow-overwrite` 覆盖线上 Page 时，CLI 会先为冲突 Page 创建资源迁移导出备份记录，并等待备份导出成功；备份包含 Page 及其组成资源，但不会沿血缘额外导出数据集、数据账户等上游资源，避免普通用户因缺少上游资源所有者权限而无法备份。备份失败或超时会中止覆盖。Card/Selector ID 不做在线覆盖检查。CLI 不自动下载备份包，会在输出中打印 packageId。需要回滚时，到 BI 资源迁移导出记录中下载该资源包后手动导入覆盖回去。
+使用 `--allow-overwrite` 覆盖线上 Page 时，CLI 会先为冲突 Page 创建资源迁移导出备份记录，并等待备份导出成功；备份任务以 `/api/task/{taskId}` 为权威终态，资源包列表仅用于在任务结果未返回 packageId 时补齐 packageId，不用列表状态推翻任务结论。目标 BI 不支持用该 taskId 查询任务或响应缺少任务状态时，会兼容回退到资源包列表判定。备份包含 Page 及其组成资源，但不会沿血缘额外导出数据集、数据账户等上游资源，避免普通用户因缺少上游资源所有者权限而无法备份。备份失败或超时会中止覆盖。Card/Selector ID 不做在线覆盖检查。CLI 不自动下载备份包，会在输出中打印 packageId。需要回滚时，到 BI 资源迁移导出记录中下载该资源包后手动导入覆盖回去。
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.37
+
+- 完善筛选器、页面布局和组合图配置，仪表板搭建更灵活。
+- 增强字段绑定校验，减少图表配置错误。
+- 优化图表属性和页面导出配置，提升生成结果的稳定性。
+
+### @guandata/guanvis 0.1.36
+
+- 扩展仪表板标题、页面背景、筛选栏、卡片组、Tab 和分区的视觉配置，支持字体、颜色、图标、背景图、间距与分割线。
+- 表格可配置主题、斑马纹、边框、表头和数据区样式；柱形图和条形图可调整柱宽、间距和圆角。
+- 本地图片可随页面资源打包上传，检出已有页面后也能保留并继续编辑线上视觉配置。
+- 增强已有页面覆盖发布前的备份与兼容判断，降低不同 BI 版本下的误覆盖风险。
+
 ### @guandata/guanvis 0.1.35
 
 - 补齐常用图表属性配置，支持背景、标题、图例、坐标轴、标签、辅助线、主题色和动态参数默认值等能力。

package/package.json

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

package/skills/guanvis/SKILL.md

@@ -23,10 +23,10 @@ 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 不受限）。
+- Card/Page/Selector 的 `.setId(...)` 必须用 `guanvis genid` 生成（保证字母开头）；数字开头 ID 会触发 BI 前端 CSS selector 语法错误，新建资源校验直接报 error 拦截（checkout/attach 的已有资源保留原 ID 不受限）。
 - 先 `preview` 做本地结构验证，再 `publish`（publish 自带构建打包上传，**发布前不需要单独 `pack`**；`pack` 只用于生成离线 ZIP 走 `upload`）。仅修复描述用 `card/page set-description` 并同步 JS 中的 `.setDescription(...)`；改看板内容按「线上仪表板更新红线」处理。
 - **编辑红线（编辑 ≠ 删除重建）**：修改/改名已发布 Page 或 Card 必须保留原 pgId/cdId 原地覆盖发布。本地源工程还在且线上未被网页端改动 → 直接改本地 JS 同 ID 重新 publish；否则 → `checkout` 后编辑，且**不得**把 `attachCard` 改写成 `createCard()`（绕过 base JSON 会丢线上配置）。**禁止**用"新建 + 删除旧的"模拟编辑——资源 ID 变化会让收藏、分享、订阅、门户引用和页面权限全部失效且无法迁移；"保留旧页面出新版本"用 `guanvis page save-as`。全局参数同理只能 `parameter update <dpId>` 原地更新，禁止 delete 后重建同名参数（dpId 断链）。分流决策见 `references/checkout-editing.md` §4。
 - **资源包安全红线**：Agent 只编辑 DSL 源文件；资源包 ZIP 是 `guanvis pack/publish` 的派生产物，不手工生成、解包修改或重打包。`guanvis upload` 只允许上传 `guanvis pack` 原样生成的 ZIP。若用户要求批量重绑资源、迁移已有页面或复用线上页面结构，先停下来说明风险并确认方案，不要直接改 ZIP。
@@ -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,14 +49,14 @@ 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 用环境变量
 15. **更新线上仪表板**：checkout 工程 = 修改指定线上 Page，保留原资源 ID；CLI 检测到同 ID Page 时必须先向用户说明覆盖影响并取得明确确认，才可加 `--allow-overwrite`（自带覆盖备份兜底）。要"保留原页面出新版本"用 `guanvis page save-as <pgId> --suffix _guanvis`（BI 原生整页另存为，服务端重映射全部卡片间引用），不要复制 checkout JSON 改 ID；细节见 `references/checkout-editing.md` §5
 16. **描述维护**：仅修复已发布资源描述时保留原 ID，用 `guanvis card/page set-description`；本地有 JS 工程时同步更新 `.setDescription(...)`
-17. **主题切换**：用户描述风格 → 工程目录里 `guanvis theme preference --keywords "..." --sync`；不要选租户默认"浅色"/"深色"，没有合适主题就保持/清空偏好用内置"简约"兜底；改版未提风格时 `.applied.json` 自动继承上次主题。多子目录工程主题按子目录独立配置和执行；详见 `references/theme.md`
+17. **主题切换**：用户描述风格 → 工程目录里 `guanvis theme preference --keywords "..." --sync`；不要选租户默认"浅色"/"深色"，没有合适主题就保持/清空偏好用内置"简约"兜底；改版未提风格时普通工程由 `.applied.json` 继承上次主题，checkout 工程按 Page base 保留线上主题。多子目录工程主题按子目录独立配置和执行；详见 `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()`；复杂指标卡片参数先读 `references/metric-chart-reference.md`
 20. **杜邦分析图**：用 `createDuPontChart()` 创建 `LAYOUT` 卡片（非普通 ChartType），节点放 `KPI_CARD` 子卡并用 `.setRoot()`/`.addChild()` 组织树；页面只放杜邦父卡片，筛选器 `linkToAll()` 会覆盖杜邦子卡片
@@ -158,7 +158,7 @@ var page = createPage("销售仪表板")
 registerPage(page.build());
 ```
 
-**仪表板主题**：没配 `themes/` 时 `preview`/`pack`/`publish` 自动使用内置简约主题（不依赖租户线上主题列表）；普通图表与指标平台 MetricChart 都会自动应用主题视觉配置（只写 `settings` 与 `meta.chartMain.props`，不改 `zoneData` 等查询字段）。**JS DSL 不提供主题接口**——`setDashboardTheme(...)` / `page.setTheme(...)` 会因函数未定义而报错，主题一律走 `guanvis theme preference`（见 `references/theme.md`）。
+**仪表板主题**：新建工程没配 `themes/` 时 `preview`/`pack`/`publish` 自动使用内置简约主题（不依赖租户线上主题列表）；`checkout` 工程未明确切换主题时保留线上主题或“无主题”状态。普通图表与指标平台 MetricChart 都会自动应用主题视觉配置（只写 `settings` 与 `meta.chartMain.props`，不改 `zoneData` 等查询字段）。**JS DSL 不提供主题接口**——`setDashboardTheme(...)` / `page.setTheme(...)` 会因函数未定义而报错，主题一律走 `guanvis theme preference`（见 `references/theme.md`）。
 
 **单张图表主题色**：用 `.setThemeColor(tcId, colors?, options?)` 切换主题色、修改颜色覆盖或选择分类/顺序色板，`options.useSequentialPalette` 用于显式选择色板模式。只修改当前主题时 `tcId` 传 `null`；编写配置前必须检查项目根目录的 `theme-colors.js`，不存在时先运行 `guanvis theme-color sync -d <project>`，非空 `tcId` 必须取自快照。多页面和多子目录共用这一份快照，构建阶段的自动生成只作兜底。完整语义见 `references/chart-properties.md`。
 

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

@@ -1,11 +1,13 @@
 ## Builder API 参考
 
+新建 Card/Page 未设置非空业务描述时，payload 描述使用 `[guanvis:created]` 标记创建来源；设置非空业务描述后只保存业务描述，不追加标记。attach/checkout 已有资源不补标记，Page 只有创建标记时不会打开描述展示。
+
 ### CardBuilder
 
 | 方法 | 说明 |
 |------|------|
 | `createCard(chartType, name)` | 创建 Card（chartType 必须使用 `ChartType.XXX` 枚举） |
-| `.setId(cardId)` | **必填**。设置资源 ID（严格 24 位字母数字，格式与后端 RandUtil.uuid 一致），支持多次上传覆盖更新。通过 `guanvis genid` 生成；如果生成或填写的 ID 以数字开头，建议重新生成一组，避免 BI 前端 `querySelector("#<id>")` 报错 |
+| `.setId(cardId)` | **必填**。新建资源 ID 应通过 `guanvis genid` 生成；新建校验格式为 `^[a-z][a-z0-9]{23}$`。支持同 ID 重复上传覆盖更新；checkout/attach 的已有资源 ID 原样保留，不校验格式 |
 | `.bindDataset(dsId)` | 绑定数据集（必填，dsId 必须在 defineDataset 中注册） |
 | `.addRow(field)` | 添加行维度（X 轴） |
 | `.addColumn(field)` | 添加列维度（按维度分组着色，如按地区/类别分色）。仅 `STACKED_COLUMN`、`GROUPED_COLUMN`、`GROUPED_BAR` 等多指标图表支持 |
@@ -23,15 +25,18 @@
 | `.addLocation(field)` / `.addTarget(field)` / `.addCompare(field)` | 位置/目标/对比 |
 | `.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)` | 图例配置 |
 | `.setDataLabel(config)` / `.setMetricAdditionalDataLabel(config)` | 数据标签配置 |
 | `.setAxis(config)` | 坐标轴配置 |
 | `.setTooltip(config)` | 工具提示配置 |
-| `.setTableSetting(config)` / `.setTableCellMerge(config)` | 表格配置 |
+| `.setTableSetting(config)` / `.setTableCellMerge(config)` | 表格行为、视觉样式与单元格配置 |
 | `.setPieSetting(config)` / `.setPieCenterText(config)` | 饼图配置 |
 | `.setGrandTotal(config)` | 表格总计与小计配置 |
 | `.setSummary(field, options?)` / `.setSummaryStyle(config)` | 汇总指标及样式配置 |
@@ -164,8 +169,11 @@ attachCard(CARD_ID, BASE_PATH)
 | `.setDataLabel()` / `.setMetricAdditionalDataLabel()` | 数据标签配置 |
 | `.setAxis()` / `.setAuxiliaryLine()` / `.setTooltip()` | 坐标轴、辅助线和工具提示配置 |
 | `.setLineSetting()` | 折线显示配置 |
+| `.setComboSetting()` | 组合图的显示方式、折线或符号样式配置 |
+| `.setBarSetting()` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
+| `.setWaterfallSetting()` | 瀑布图的正负值颜色和累计值配置 |
 | `.setPieSetting()` / `.setPieCenterText()` | 饼图配置 |
-| `.setTableSetting()` / `.setTableCellMerge()` / `.setGrandTotal()` | 表格配置 |
+| `.setTableSetting()` / `.setTableCellMerge()` / `.setGrandTotal()` | 表格行为、视觉样式与汇总配置 |
 | `.setSplitSetting()` / `.setShapeColorType()` | 拆分图和图形填充配置 |
 | `.setRawSettings()` | 原始设置 |
 | `.setProps(obj)` | 设置指标卡片 `meta.chartMain.props` |
@@ -388,7 +396,7 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.removeLayoutItem(cardRef)` | 从当前 Page 根布局移除已放置的 card/selector/layout component；主要给动作级移动 API 使用 |
 | `.addFilterSelectorGroup(group)` | 添加一个筛选栏筛选器组 |
 | `.addFilterSelector(selectorId)` | 显式添加一个未分组的筛选栏 selector，并控制其与筛选器组的顺序 |
-| `.setFilterPanelLayout(config)` | 配置筛选栏的布局相关属性；见下方“筛选栏布局” |
+| `.setFilterPanelLayout(config)` | 配置筛选栏布局和视觉样式；见下方“筛选栏布局与视觉” |
 | `.setFilterLayout(items)` | 整体设置快捷筛选区的 selector / filter selectorGroup ID 列表；checkout 场景会覆盖 base `filterLayout` |
 | `.clearFilterLayout()` | 清空快捷筛选区；常用于把已有快捷筛选器改成画布内普通筛选器卡片 |
 | `.addFilterLayoutItem(items)` | 向快捷筛选区追加 selector / filter selectorGroup ID，已存在则跳过 |
@@ -402,13 +410,55 @@ overview.linkTo("bbbbbbbbbbbbbbbbbbbbbbbb", {
 | `.setBackgroundColor(color)` | 页面背景色 |
 | `.setCardMargin(margin)` | 卡片间距 |
 | `.setFineMode(enabled)` | 开启/关闭精细模式 |
-| `.setDashboardTitle(enabled, options?: { title?: string })` | 开启/关闭仪表板标题；未传 `title` 时默认使用 Page 名称 |
+| `.setDashboardTitle(enabled, options?)` | 开启/关闭仪表板标题，并设置标题文字、字体、背景、图标、高度和下边距；未传 `title` 时默认使用 Page 名称 |
 | `.setExportView(enabled, config?)` | 开启/关闭导出视图；`config.mode` 决定使用分页方向还是单页宽度 |
 | `.setWidthAdaptive(enabled, width?)` | 开启/关闭宽度自适应；默认宽度 1280 |
-| `.setLayoutSetting(config)` | 原始 layout 配置 |
+| `.setLayoutSetting(config)` | 设置 `page.meta.layoutSetting`；布局类型使用 `PageLayoutType` |
 | `.build()` | 构建 |
 
-#### 导出视图与宽度自适应
+`setDashboardTitle()` 的 `options`：
+
+| 字段 | 说明 |
+|------|------|
+| `title` | 标题文字；省略时使用 Page 名称 |
+| `font` | 字体、字形和对齐设置，见下表 |
+| `backgroundColor` | 背景色 |
+| `backgroundImage` | 背景图片，使用通用图片对象 |
+| `icon` | 标题图标，使用通用图片对象 |
+| `contentHeight` | 背景高度，整数 120～400 |
+| `paddingBottom` | 背景下边距，整数 0～100 |
+
+`font` 字段：
+
+| 字段 | 规则 |
+|------|------|
+| `fontFamily` | 非空字符串 |
+| `fontSize` | 整数 1～72 |
+| `color` | 颜色字符串 |
+| `bold` | 布尔值 |
+| `italic` | 布尔值 |
+| `underline` | 布尔值 |
+| `strikeThrough` | 布尔值 |
+| `textAlign` | `left` / `center` / `right` |
+
+通用图片对象：
+
+| 字段 | 说明 |
+|------|------|
+| `enabled` | 是否显示图片 |
+| `url` | `http(s)` 外链或已有 `/guandata-store/...` 地址 |
+| `uploadPath` | 本地图片路径；pack/publish 时作为 Page 附件上传 |
+| `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
@@ -430,9 +480,68 @@ 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` 同时开启，但可以与导出视图同时开启。
+
+#### 页面布局与卡片视觉
+
+页面全局视觉配置直接写入 `layoutSetting`，不使用单独的 `setGlobalStyle()`：
 
-#### 筛选栏布局
+```javascript
+page.setLayoutSetting({
+    compact: true,
+    card: {
+        border: {
+            enabled: true,
+            width: 1,
+            color: "#D9D9D9",
+            radius: 6
+        },
+        boxShadow: {
+            enabled: true
+        }
+    },
+    page: {
+        background: {
+            image: {
+                enabled: true,
+                uploadPath: "./assets/page-background.png",
+                renderType: ImageRenderType.STRETCH
+            }
+        }
+    },
+    toolbarSettings: {
+        displayState: CardToolbarDisplayState.HIDDEN,
+        hiddenState: CardToolbarHiddenState.PARTIAL,
+        hiddenMenus: [
+            CardToolbarMenu.DATA_EXPLAIN,
+            CardToolbarMenu.INTRO
+        ]
+    }
+});
+```
+
+`setLayoutSetting()` 按自有属性递归稀疏合并，多次调用只覆盖相同叶子字段。例如先设置 `card.border.enabled`、再单独设置 `card.border.color`，两个值都会保留。未传字段不会被写成默认值：checkout Page 保留 base 中的同级配置，新建 Page 继续由主题和前端运行时补齐。
+
+只设置 `card.border.color` 是合法的，但不会自动开启边框；`enabled` 未设置时仍使用现有值或产品默认值 `false`。边框宽度范围为 `1 ~ 10`，圆角范围为 `0 ~ 20`，均接受范围内的有限数字。`card.boxShadow.enabled` 和 `compact` 必须为布尔值。
+
+页面背景图片位于 `page.background.image`：
+
+- `enabled`：是否显示背景图片；设为 `false` 只关闭显示，不清除已选择的图片。
+- `url`：外链或 BI 已上传图片地址。`http://...` / `https://...` 推断为 `ImageSourceType.OUTSIDE_LINK`；`/guandata-store/...` 是当前 BI 环境中已有的上传资源，推断为 `ImageSourceType.LOCAL_IMAGE`，直接引用而不会再次上传。跨环境迁移时优先使用 `uploadPath`，让图片随 Page 附件一起打包。
+- `uploadPath`：相对项目目录或绝对本地路径。`preview` 会校验文件，`pack` / `publish` 会作为 Page 附件上传并改写为稳定的 `/guandata-store/images/...` 地址。支持 jpg、jpeg、png、gif，并校验扩展名与真实文件类型一致。
+- `renderType`：`ImageRenderType.RATIO`、`STRETCH`、`FIT_TO_CONTENT`；选择新图片而未传时与当前产品一致，默认 `FIT_TO_CONTENT`。
+
+`url` 和 `uploadPath` 同时传入时优先使用 `url` 并产生 warning。新建 Page 只公开 `ImageSourceType.OUTSIDE_LINK`(1) 和 `LOCAL_IMAGE`(2)；checkout 未修改的历史来源值会原样保留。背景色仍可使用 `.setBackgroundColor()` 或设置 `layoutSetting.pageBackgroundColor`。
+
+工具栏配置与产品页面的“卡片工具栏”设置一致：
+
+- `displayState`：`CardToolbarDisplayState.DEFAULT` / `HIDDEN`。
+- `hiddenState`：隐藏工具栏时使用 `CardToolbarHiddenState.ALL` / `PARTIAL`；默认展示的新页面可以省略，checkout 从隐藏切回默认时必须显式传 `null`。
+- `hiddenMenus`：使用 `CardToolbarMenu` 中的公开菜单枚举；`ALL` 模式必须传空数组或省略。
+
+新建 Page 设置 `hiddenState` 或 `hiddenMenus` 时必须同时设置 `displayState`，设置 `displayState: HIDDEN` 时必须给出 `hiddenState`，避免产生前端无法生效的半完整组合。checkout 改变工具栏状态时按产品的整组更新语义填写关联字段：切回默认使用 `{ displayState: DEFAULT, hiddenState: null, hiddenMenus: [] }`，切换为全部隐藏时同时传 `hiddenMenus: []`。构建会在 base 深度合并后校验最终组合；未修改的历史配置和仅调整菜单的历史值仍可无损回写。
+
+#### 筛选栏布局与视觉
 
 ```javascript
 page.setFilterPanelLayout({
@@ -440,13 +549,45 @@ page.setFilterPanelLayout({
     spacing: FilterPanelSpacing.MIDDLE,
     padding: { top: 8, right: 12, bottom: 8, left: 12 },
     labelPosition: "top",
-    actionOrder: "right"
+    labelFont: { fontSize: 12, color: "#333333", bold: true },
+    controlStyle: FilterPanelControlStyle.OUTLINED,
+    controlFont: { fontSize: 12, color: "#222222", bold: false },
+    actionOrder: "right",
+    buttonColor: "#2E88FF",
+    buttonFont: { fontSize: 12, bold: true },
+    backgroundColor: "rgba(255, 255, 255, 0.9)",
+    backgroundImageEnabled: true,
+    backgroundImage: {
+        url: "https://example.com/filter-panel.png",
+        sourceType: ImageSourceType.OUTSIDE_LINK,
+        renderType: ImageRenderType.FIT_TO_CONTENT
+    }
 });
 ```
 
-所有字段均可选，多次调用按字段增量合并。
+所有字段均可选，多次调用按字段增量合并；`labelFont`、`controlFont` 和 `buttonFont` 也只覆盖显式传入的字体子字段。省略字段表示保留现值，显式传 `null` 表示删除该覆盖值并恢复产品/主题默认；字体对象的单个子字段也可传 `null`。例如 `{ backgroundColor: null, controlFont: { color: null } }` 会清除背景色和控件文字颜色覆盖。
+
+补充规则：
 
-`padding` 支持 `top/right/bottom/left` 和`0 ~ 32`内的整数；非数字、`NaN`、`Infinity` 等非法值会产生 warning 并丢弃。
+| 对象/字段 | 规则 |
+|-----------|------|
+| `padding` | 支持 `top`、`right`、`bottom`、`left`，值为整数 0～32；非法值产生 warning 并丢弃 |
+| `labelFont` | 支持 `fontFamily`、`fontSize`、`color`、`bold`、`italic`、`underline`；字号为整数 9～20 |
+| `controlFont` | 支持 `fontFamily`、`fontSize`、`color`、`bold`、`italic` |
+| `buttonFont` | 支持 `fontFamily`、`fontSize`、`bold`、`italic`、`underline`；文字颜色由产品固定 |
+| `buttonColor` | 按钮强调色 |
+
+`backgroundImage`：
+
+| 项目 | 规则 |
+|------|------|
+| 完整对象 | 新建 Page 最终必须包含 `url`、`sourceType`、`renderType` |
+| 稀疏更新 | 完整设置后可只修改单个字段；checkout 与 base 合并后的对象必须完整 |
+| `url` | 非空字符串；本地图片使用已有 BI 资源路径 |
+| `sourceType` | `ImageSourceType.OUTSIDE_LINK` / `LOCAL_IMAGE` |
+| `renderType` | `ImageRenderType.RATIO` / `STRETCH` / `FIT_TO_CONTENT` |
+| 关闭显示 | 设置 `backgroundImageEnabled: false` |
+| 恢复默认 | 同时将 `backgroundImageEnabled`、`backgroundImage` 设为 `null` |
 
 | 字段 | 可选值 | 写入 `page.meta.filterLayoutSettings` |
 |------|--------|----------------------------------------|
@@ -454,9 +595,17 @@ page.setFilterPanelLayout({
 | `spacing` | `FilterPanelSpacing.SMALL` / `MIDDLE` / `LARGE` | `selPadding` |
 | `padding` | `{ top?, right?, bottom?, left? }` | `paddingValue` |
 | `labelPosition` | `"top"` / `"left"` | `selName.position` |
+| `labelFont` | 字体对象 | `selName.font` |
+| `controlStyle` | `FilterPanelControlStyle.BORDERLESS` / `OUTLINED` / `FILLED` | `selStyle.variant` |
+| `controlFont` | 字体对象 | `selStyle.font` |
 | `actionOrder` | `"left"` / `"right"` | `opStyle.order` |
+| `buttonColor` | 非空颜色字符串 | `button` |
+| `buttonFont` | 字体对象 | `opStyle.font` |
+| `backgroundColor` | 非空颜色字符串 | `background` |
+| `backgroundImageEnabled` | `true` / `false` | `backgroundImageEnabled` |
+| `backgroundImage` | `{ url, sourceType, renderType }` | `backgroundImage` |
 
-该方法只覆盖上述布局字段。checkout 会在 `.guanvis/base/page.json` 保留完整线上配置，pack/publish 时在此基础上合并布局补丁，因此颜色、字体和背景不会丢失；新页面的视觉字段由主题补齐。
+该方法只覆盖表中字段。checkout 会把这些布局和视觉字段重新生成到 `page.js`，同时在 `.guanvis/base/page.json` 保留完整线上配置；pack/publish 在基线上稀疏合并显式补丁，未知历史字段不会丢失。新页面未显式设置的视觉字段仍由主题补齐。
 
 ### AreaTitleBuilder
 
@@ -475,6 +624,9 @@ page.setFilterPanelLayout({
 | `.setBackgroundColor(color)` | 背景色 |
 | `.setShowBgImage(boolean)` | 是否显示背景图 |
 | `.setShowIcon(boolean)` | 是否显示图标 |
+| `.setFontStyle(style)` | 稀疏设置字体、字形和对齐方式 |
+| `.setBackgroundImage(image)` | 设置背景图片；支持外链、已有 Store 地址或本地 `uploadPath` |
+| `.setIcon(image)` | 设置图标图片；图片规则同上 |
 | `.build()` | 构建 areaTitle result |
 
 ```javascript
@@ -503,12 +655,42 @@ registerPage(page.build());
 | `.setId(cardGroupId)` | **必填**。设置卡片组 ID，必须以 `cardGroup_` 开头 |
 | `.setRawStyle(style)` | checkout 保留线上 style 用；新建工程优先用 `.setShowTitle()` 等语义化方法 |
 | `.setShowTitle(boolean)` | 是否显示标题，默认 `true` |
+| `.setTitleStyle(config)` | 设置标题字体、背景/图标及上下边框 |
+| `.setBackgroundStyle({ color?, image? })` | 设置卡片组自身背景色和背景图 |
+| `.setCardSpacing(type, value?)` | 设置组内卡片间距；type 使用 `LayoutMarginType.NONE/SPACE/DIVIDE` |
+| `.setDividingLineStyle({ color? })` | 设置分割线颜色；分割线模式由 `.setCardSpacing(LayoutMarginType.DIVIDE)` 开启 |
 | `.addRow(specs, height?)` | 在组内按行放置卡片，写法同 `PageBuilder.addRow()` |
 | `.addFullWidthCard(cardRef, height?)` | 在组内放一张满宽卡片 |
 | `.placeCard(cardRef, x, y, w, h)` | 在组内精确放置卡片 |
 
 卡片组内布局方法同 `PageBuilder`，使用 `cardRef`。
 
+`setTitleStyle()`：
+
+| 字段 | 说明 |
+|------|------|
+| `enabled` | 是否显示标题 |
+| `font` | 标题字体、字形和对齐 |
+| `backgroundColor` | 标题背景色 |
+| `backgroundImage` | 标题背景图 |
+| `icon` | 标题图标 |
+| `topStrip` | 顶部边框设置 |
+| `bottomStrip` | 底部边框设置 |
+
+`topStrip`、`bottomStrip`：
+
+| 字段 | 说明 |
+|------|------|
+| `enabled` | 是否显示边框 |
+| `width` | 2 / 4 / 6 / 8 |
+| `backgroundColor` | 边框颜色 |
+
+`setDividingLineStyle()`：
+
+| 字段 | 说明 |
+|------|------|
+| `color` | 分割线颜色 |
+
 ```javascript
 var salesGroup = createCardGroup("销售概览")
     .setId("cardGroup_AbCdEf")
@@ -606,11 +788,37 @@ tab 用于把页面中的卡片分到多个 panel。适合同一主题下多组
 | `.setLabelStyle(style)` | 设置标签样式：`TabLabelStyle.UNDERLINE`（默认）、`CARD`、`CAPSULE`、`TRAPEZOID` |
 | `.setAlignment(alignment)` | 设置标签对齐：`TabAlignment.LEFT`（默认）、`CENTER`、`RIGHT` |
 | `.setTabSize(size)` | 设置标签宽度：`TabSizeType.MAX_CONTENT`（默认）或 `FLEX` |
+| `.setTitleStyle(config)` | 设置 Tab 总标题及其字体、位置、背景和图标 |
+| `.setSelectedTextStyle(style)` / `.setUnselectedTextStyle(style)` | 设置选中/未选中页签文字样式 |
+| `.setTabColor(color)` | 设置非下划线页签的主体颜色 |
+| `.setBackgroundStyle({ color?, image? })` | 设置页签栏背景色和背景图 |
 | `panel.setId(panelId)` | **必填**。设置 panel ID，必须以 `panel_` 开头且同一页面内唯一。建议用 `guanvis gen-layout-id panel` 生成 |
+| `panel.setPanelStyle(config)` | 设置当前 panel 的背景、卡片间距和分割线颜色 |
 | `panel.addRow(specs, height?)` | 在 panel 内按行放置卡片，写法同 `PageBuilder.addRow()` |
 | `panel.addFullWidthCard(cardRef, height?)` | 在 panel 内放一张满宽卡片 |
 | `panel.placeCard(cardRef, x, y, w, h)` | 在 panel 内精确放置卡片 |
 
+Tab 的 `setTitleStyle()`：
+
+| 字段 | 说明 |
+|------|------|
+| `enabled` | 是否显示总标题 |
+| `title` | 总标题文字 |
+| `position` | `TabTitlePosition.TOP` / `TabTitlePosition.LEFT` |
+| `font` | 标题字体、字形和对齐 |
+| `backgroundColor` | 标题背景色 |
+| `backgroundImage` | 标题背景图 |
+| `icon` | 标题图标 |
+
+`panel.setPanelStyle()`：
+
+| 字段 | 说明 |
+|------|------|
+| `backgroundColor` | panel 背景色 |
+| `backgroundImage` | panel 背景图 |
+| `margin` | `{ type, value }`；`type: LayoutMarginType.DIVIDE` 开启分割线模式，`SPACE` 的 value 为整数 1～20 |
+| `dividingLineColor` | 分割线颜色 |
+
 **使用示例**：
 
 ```javascript
@@ -655,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)` | 绑定数据集（可选，单数据集场景自动绑定） |
@@ -677,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
@@ -684,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);
@@ -722,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);
@@ -768,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` 的目标字段映射优先。
 
@@ -1529,6 +1783,8 @@ project/
 | `SelectorType` | `DS_ELEMENTS`（默认）, `DS_INTERVAL`, `CALENDAR`, `TIME_MACRO` | 筛选器类型 |
 | `SelectorDisplay` | `SEARCH_LIST`（单选下拉）, `SEARCH_BOX`（多选下拉）, `CHECKBOX`（复选框）, `RADIO`（单选框）, `BUTTON_GROUP`（按钮组） | 筛选器展示类型，不设置时根据 multiSelect 自动推断 |
 | `SelectorDefaultType` | `FIRST_PICK`, `FIXED_VALUE`, `ALL`（默认，全部/不筛选） | 筛选器默认值类型 |
+| `TabTitlePosition` | `TOP`, `LEFT` | Tab 总标题位置 |
+| `LayoutMarginType` | `NONE`, `SPACE`, `DIVIDE` | Tab panel 与卡片组的卡片间距模式 |
 | `CardType` | `CHART`(0), `TEXT`(1), `IFRAME`(2), `PICTURE`(4), `SELECTOR`(6), `LAYOUT`(9) | 卡片类型（内部使用，通常不需要直接引用） |
 | `ImageSourceType` | `OUTSIDE_LINK`(1), `LOCAL_IMAGE`(2) | 图片来源类型 |
 | `ImageRenderType` | `RATIO`(1，原比例), `STRETCH`(2，拉伸填满), `FIT_TO_CONTENT`(3，自适应内容) | 图片渲染模式 |

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

@@ -640,23 +640,108 @@ Tooltip 展示哪些数据字段由 `.addTooltip(field)` 控制；`setTooltip()`
 
 ### `setTableSetting(config)`
 
-设置表格的分页、对齐、换行、序号和分组展示。
+设置透视表、分组表、明细表、树状表和滚动表的行为与视觉样式。行为字段继续写入 `props.miscPivotTableSetting`；视觉样式按分组写入真实前端属性：
 
+- `appearance` → `props.pivot_appearance`
+- `headers` → `props.pivot_headers`
+- `data` → `props.pivot_data`
 
-| 字段                              | 类型                   | 说明                                                                                        |
-| ------------------------------- | -------------------- | ----------------------------------------------------------------------------------------- |
-| `pagination`                    | boolean              | 是否分页                                                                                      |
-| `pageSize`                      | number               | 每页行数；可选 `10` / `20` / `50` / `100` / `200`                                                |
-| `autoAlignment`                 | boolean              | 横向自动对齐                                                                                    |
-| `vAlign`                        | `"MIDDLE"` / `"TOP"` | 垂直居中或向上对齐                                                                                 |
-| `textWrap`                      | boolean              | `true` 自动换行，`false` 截断                                                                    |
-| `showHeaderSortingIcon`         | boolean              | 是否显示表头排序图标                                                                                |
-| `fixedHeaderInfo`               | object               | 固定表头；可包含 `{ X: boolean, Y: boolean }`                                                     |
-| `showLineNumber`                | boolean              | 是否显示行序号                                                                                   |
-| `accumulatedLineNumber`         | boolean              | 分页时连续累加编号                                                                                 |
-| `skipTotalRow`                  | boolean              | 行序号排除总计/小计；与连续累加编号互斥                                                                      |
+视觉分组使用嵌套字段合并。只设置视觉样式时不会清空已有行为配置；编辑已有卡片时也只深合并显式传入的视觉字段。
 
-透视表还支持：
+| 图表类型 | 视觉能力 | 行为限制 |
+|---|---|---|
+| `PIVOT_TABLE` | 支持下表全部视觉字段 | 支持透视表序号配置 |
+| `GROUPED_TABLE` | 支持下表全部视觉字段 | 支持分组展示与展开配置 |
+| `DETAIL_TABLE` | 支持下表全部视觉字段 | `vAlign` 仅支持 `"MIDDLE"` |
+| `LAYER_TREE_TABLE` | 支持下表全部视觉字段 | 不支持分页、累计行号和跳过总计行；支持展开配置 |
+| `SCROLL_TABLE` | 使用下文所列的滚动表视觉字段 | 支持数字/字母换行及行号样式；不支持分页、累计行号、跳过总计行和 `textWrap`；`vAlign` 仅支持 `"MIDDLE"` |
+
+#### 主题及样式：`appearance`
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `theme` | `"classic"` / `"compact"` | 经典或极简主题 |
+| `colorType` | `"grey"` / `"ocean"` / `"laker"` / `"spring"` / `"autumn"` | 表格色系 |
+| `banding` | `{ enabled: boolean, colors: string[] }` | 斑马纹开关与非空颜色数组 |
+| `border` | `{ enabled: boolean, colors: string[] }` | 外边框开关与非空颜色数组 |
+| `divider` | `{ colors: string[] }` | 行列分隔线非空颜色数组 |
+| `backgroundColor` | string | 表格背景色 |
+| `selectedColor` | string | 选中高亮色，可使用带透明度的 `rgba(...)` |
+| `colWidth` | integer，15–1000 | 表格列宽 |
+| `fontFamily` | 非空 string | 全表字体 |
+| `fontSize` | number，12–72 | 全表字号 |
+| `cellPadding` | `"SMALL"` / `"MIDDLE"` / `"LARGE"` | 单元格内间距 |
+
+滚动表的 `appearance` 仅支持 `colorType`、`banding`、`divider`、`backgroundColor`、`colWidth` 和 `cellPadding`。其中 `colorType` 可选 `"grey"` / `"light-blue"` / `"purple"` / `"lake-blue"` / `"green"` / `"yellow"`，`divider` 使用 `{ row: boolean, column: boolean, color: string }`。
+
+#### 表头设置：`headers`
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `columnEnabled` | boolean | 是否显示列表头；仅滚动表支持配置 |
+| `colHeaderHeight` | integer，18–500 | 列表头行高 |
+| `columnStyle` | object | 列表头背景与文字样式 |
+| `colHeaderAlignment` | `"center"` / `"left"` / `"right"` / `"followField"` | 列表头对齐方式 |
+| `rowSize` | integer，0–100 | 行表头列数；滚动表不支持配置 |
+| `rowStyle` | object | 行表头背景与文字样式；额外支持 `showFillColor`；滚动表不支持配置 |
+
+#### 数据行样式：`data`
+
+| 字段 | 类型/取值 | 说明 |
+|---|---|---|
+| `rowHeight` | integer，18–500 | 数据行行高 |
+| `hoverColor` | string | 鼠标悬停背景色 |
+| `style` | object | 数据区文字样式 |
+
+`columnStyle`、`rowStyle` 和 `data.style` 可包含 `fontFamily`、`fontSize`（12–72）、`color`、`bold`、`italic`、`underline`、`strikeThrough`。`columnStyle` / `rowStyle` 还支持 `fillColor`，`rowStyle` 额外支持 `showFillColor: boolean`。
+
+```javascript
+.setTableSetting({
+    appearance: {
+        theme: "compact",
+        colorType: "ocean",
+        banding: { enabled: true, colors: ["#F5F7FA"] },
+        border: { enabled: true, colors: ["#D9DEE8"] },
+        divider: { colors: ["#E4E7F0"] },
+        backgroundColor: "#FFFFFF",
+        selectedColor: "rgba(22, 93, 255, 0.1)",
+        colWidth: 120,
+        fontFamily: "Arial",
+        fontSize: 12,
+        cellPadding: "MIDDLE"
+    },
+    headers: {
+        colHeaderHeight: 36,
+        columnStyle: { fillColor: "#EDF2FA", color: "#21272A", bold: true },
+        colHeaderAlignment: "followField",
+        rowSize: 1,
+        rowStyle: { showFillColor: true, fillColor: "#F1F6FB", color: "#343D50" }
+    },
+    data: {
+        rowHeight: 32,
+        hoverColor: "#F5F5F5",
+        style: { color: "#21272A", fontSize: 12 }
+    }
+})
+```
+
+#### 行为配置
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `pagination` | boolean | 是否分页 |
+| `pageSize` | number | 每页行数；可选 `10` / `20` / `50` / `100` / `200` |
+| `autoAlignment` | boolean | 横向自动对齐 |
+| `vAlign` | `"MIDDLE"` / `"TOP"` | 垂直居中或向上对齐；明细表、滚动表不支持 `"TOP"` |
+| `textWrap` | boolean | `true` 自动换行，`false` 截断；滚动表不支持 |
+| `wordBreak` | boolean | 数字/字母是否自动换行；仅滚动表支持 |
+| `showHeaderSortingIcon` | boolean | 是否显示表头排序图标 |
+| `fixedHeaderInfo` | object | 固定表头；通常可包含 `{ X: boolean, Y: boolean }`；滚动表仅支持 `{ X: false }` |
+| `showLineNumber` | boolean | 是否显示行序号 |
+| `accumulatedLineNumber` | boolean | 分页时连续累加编号；树状表、滚动表不支持 |
+| `skipTotalRow` | boolean | 行序号排除总计/小计；与连续累加编号互斥；树状表、滚动表不支持 |
+
+透视表和滚动表还支持：
 
 | 字段 | 类型 | 说明 |
 |---|---|---|
@@ -674,11 +759,13 @@ Tooltip 展示哪些数据字段由 `.addTooltip(field)` 控制；`setTooltip()`
 | `isDefaultExpandedGroupedTable` | boolean | 是否默认全部展开 |
 | `defaultExpandCols` | number | 默认展开列数 |
 
+树状表支持其中的 `isDefaultExpandedGroupedTable` 和 `defaultExpandCols`。
+
 
 表格属性会按以下规则同步关联字段：
 
-- `pagination: false` 会同时设置 `accumulatedLineNumber: false`。
-- `showLineNumber: false` 会同时设置 `skipTotalRow: false`。
+- 对支持累计行号的表格，`pagination: false` 会同时设置 `accumulatedLineNumber: false`。
+- 对支持跳过总计行的表格，`showLineNumber: false` 会同时设置 `skipTotalRow: false`。
 - `skipTotalRow: true` 与 `accumulatedLineNumber: true` 互斥，开启其中一项会关闭另一项。
 - `isDefaultExpandedGroupedTable: true` 会同时设置 `defaultExpandCols: 0`；设置大于 `0` 的 `defaultExpandCols` 会关闭默认全部展开。
 - `treeDisplay: true` 会把列总计位置设置为 `TOP`。
@@ -861,6 +948,130 @@ 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)`
+
+设置柱形图和条形图的柱体宽度、分组间距、组内间距和圆角：
+
+```javascript
+.setBarSetting({
+    barWidth: 35,
+    barBorderRadius: 4
+})
+```
+
+也可以使用间距模式：
+
+```javascript
+.setBarSetting({
+    gapBetweenGroup: 40,
+    gapInGroup: 20,
+    barBorderRadius: 2
+})
+```
+
+| 字段 | 类型/范围 | 说明 |
+|---|---|---|
+| `barWidth` | 1–100 的整数 | 柱体宽度百分比 |
+| `gapBetweenGroup` | 0–100 的整数 | 分组间距百分比 |
+| `gapInGroup` | 0–100 的整数 | 分组内柱体间距百分比 |
+| `barBorderRadius` | 0–40 的整数 | 柱体圆角，单位 px |
+
+`barWidth` 与 `gapBetweenGroup` / `gapInGroup` 是两种互斥的配置方式，不能在同一次调用中同时设置。调用 `barWidth` 时自动使用宽度模式；调用任一间距字段时自动切换到间距模式并清除已有 `barWidth`。`barBorderRadius` 可以与任一模式组合，也可以单独修改；新建图表仅在该图表的前端默认矩阵本来使用宽度模式时补充 `useBarWidth: true`，不会把其它柱图强制切换模式。
+
+该方法支持以下柱形图和条形图：
+
+- 柱形图：`BASIC_COLUMN`、`GROUPED_COLUMN`、`STACKED_COLUMN`、`STACKED_SPLIT_COLUMN`、`PERCENT_STACKED_COLUMN`、`GROUPED_COLUMN_WITH_LINE`、`STACKED_COLUMN_WITH_LINE`、`GROUPED_COLUMN_WITH_SYMBOL`、`STACKED_COLUMN_WITH_SYMBOL`、`BULLET_COLUMN`、`WATERFALL_COLUMN`、`PARETO`
+- 条形图：`BASIC_BAR`、`GROUPED_BAR`、`STACKED_BAR`、`STACKED_SPLIT_BAR`、`PERCENT_STACKED_BAR`、`BULLET_BAR`、`BUTTERFLY`
+
+蝴蝶图没有组内柱体间距配置，因此不支持 `gapInGroup`。`attachCard()` 使用相同的图表类型和字段校验，并只合并显式传入的配置；切换到间距模式时保留未修改的颜色、圆角和未知历史字段。
+
 ## 图形填充
 
 ### `setShapeColorType(type)`

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

@@ -25,8 +25,9 @@ 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。
-- **Page 快捷筛选区**：按有序操作执行——`setFilterLayout` 整体设置，`clearFilterLayout` 清空，`addFilterLayoutItem` 追加去重，`insert/remove/moveFilterSelector` 局部调整；筛选栏布局用 `setFilterPanelLayout()`；颜色、字体和背景继续由主题管理。
+- **已有 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` 生成）。
 - **影响面检查**：发布前用 `guanvis diff <dir>` 或 `preview` 输出里的 `changeSummary` 查看 base JSON 到最终 payload 的路径级影响面。

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

@@ -179,12 +179,15 @@ registerMetricChart(card.build());
 | `.setSpecialValue(config)` | 设置特殊值显示；仅支持前端开放该属性的图表类型 |
 | `.setShowTitle(show)` / `.setCardTitleStyle(config)` | 设置卡片标题显隐与样式 |
 | `.setColumns(columns)` | 设置 `content.columns` 与 dsInfo.columns |
-| `.setTableSetting(obj)` | 设置 `props.miscPivotTableSetting` |
+| `.setTableSetting(obj)` | 设置表格行为与视觉样式；详细字段见 `chart-properties.md` |
 | `.setTableCellMerge(obj)` | 设置透视表单元格合并 |
 | `.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` |

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

@@ -5,7 +5,7 @@
 - **接口**：`POST /api/manual/template/transfer`（标准 multipart/form-data，表单字段名 `new-file`）
 - **认证**：随底层 BI 请求通道使用 `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 不做在线探测。checkout 工程表示修改指定 Page，不在 CLI 内复制新版本或手写 ID 映射。
+- **ID 策略**：`needIdMapping=false`，保持资源 ID 不变。同 ID 资源会被覆盖更新。为避免部分 BI 版本在导入前探测 Card 时缓存"找不到相关卡片"，`guanvis publish/upload` 的在线覆盖检查只探测目标环境已有 Page ID；检测到同 ID Page 时默认拒绝上传，只有明确加 `--allow-overwrite` 才允许覆盖。加 `--allow-overwrite` 后，CLI 会先调用资源包导出为冲突 Page 生成备份记录，并等待导出成功；`/api/task/{taskId}` 是备份成功或失败的权威终态，资源包列表只在任务成功但结果未直接返回 packageId 时用于补齐 packageId，不用列表状态覆盖任务结论。目标 BI 不支持通过该 taskId 查询任务或响应缺少任务状态时，兼容回退到资源包列表判定。备份失败或超时则中止上传。Card/Selector ID 不做在线探测。checkout 工程表示修改指定 Page，不在 CLI 内复制新版本或手写 ID 映射。
 - **Page 归属校验**：资源包只要包含 Card/Selector，就必须同时包含 Page，且每个 Card/Selector 的 ID 必须出现在至少一个 Page 的 `cdIds` 中。只有 Card/Selector、没有 Page，或包内存在未被任何 Page 引用的 Card/Selector 时，`preview/pack/publish/upload` 会提示在 `page.js` 中放置对应资源并将 Page 与 Card/Selector 同包发布。该约束用于避免导入端生成 `pg_id` 为空、无法访问且会与页面草稿 `origin_cd_id` 冲突的孤儿卡片。
 - **通用性**：不需要目标系统开启"一键迁移"开关，所有客户环境可用
 - **异步执行**：上传成功后返回 `taskId`，后端异步完成导入
@@ -50,7 +50,9 @@ checkout 工程表示“基于线上快照修改指定 Page”，不会新建 Pa
 
 所有 Card、Selector 和 Page **必须**调用 `.setId(id)` 设置显式 ID。未设置 ID 会在 JS 校验和 Go 校验两层报错，阻止生成。
 
-- `.setId(id)` 的 ID **必须**为严格 24 位字母数字字符串（正则：`^[a-zA-Z0-9]{24}$`），与后端 `RandUtil.uuid` 格式一致。若生成或手填的 ID 以数字开头，建议重新生成一组，避免 BI 前端某些路径把 ID 拼成 CSS selector（如 `#5bef...`）时触发 `querySelector` 语法错误。
+- **新建资源 ID** 应使用 `guanvis genid` 生成；`genid` 输出格式为 `^[a-z][0-9a-f]{23}$`。新建校验接受字母开头的 24 位小写字母数字 ID（`^[a-z][a-z0-9]{23}$`），因此已有的固定小写测试 ID 仍可使用，但混合大小写和数字开头 ID 会被拦截。
+- **已有资源兼容**：checkout/attach 把线上 ID 视为不透明标识并原样保留，不校验格式；只检查非空、唯一和引用关系，避免已有资源因历史或未来 ID 形态变化而无法原地编辑。
+- 存量本地源码工程若包含已发布的非规范 ID，不要按新建校验提示替换 ID；应 checkout/attach 后继续使用线上原 ID，避免收藏、订阅、权限和外部引用断链。
 - **生成 ID**：先运行 `guanvis genid <数量>` 生成足够的 ID，在编写脚本时直接填入每个 card/selector/page 的 `.setId()` 调用中。
 - **布局组件 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，不负责复制新版本。

package/skills/guanvis/references/theme.md

@@ -1,15 +1,21 @@
 ## 仪表板主题
 
-`preview` / `pack` / `publish` 会自动给页面与卡片注入主题，决策顺序如下：
+`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` 时**不写**该文件）
+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` 缺失
+- 新建工程目录下没有 `themes/`、或 `.preference.json` 缺失（checkout 工程会优先保留 base 页面原状）
 - `.preference.json` 里的 `themeId` 在租户线上 list 中不存在 / `Sync` 失败 / 当前命令本来就不联网
 - `keywords` 在 `.index.json` 上没有任何命中
 - `.applied.json` 引用的 `themeId` 本地快照已被删除（applied 步骤**只读本地、不再发起 sync**）
@@ -39,10 +45,10 @@ AI 选择主题时不要把租户主题列表里的默认“浅色”/“深色
 
   themeId 需为单个「安全文件名」片段：`[A-Za-z0-9_-]`、长度 ≤32，且不能含 `/`、`\`、子串 `..`；否则 CLI 会拒绝，sync 也会跳过并打 stderr 警告。
 
-- **改版（不重提风格）**：什么都不用做，`.applied.json` 会让本次 `pack`/`publish` 沿用上次主题。
+- **改版（不重提风格）**：普通工程由 `.applied.json` 沿用上次项目主题；checkout 工程按 Page base 保留各自线上主题。
 - **换风格**：再跑一次 `theme preference` 即可；下一次 `pack`/`publish` 实际使用新主题时 `.applied.json` 会自动覆盖。
 - **没有合适主题**：不要选择默认“浅色”/“深色”，也不要从列表里随便挑；保持无偏好或执行 `theme preference --clear`，使用内置“简约”兜底。
-- **回到 skill 自带兜底**：`guanvis theme preference --clear` 会**同时**删除 `.preference.json` 和 `.applied.json`，下次 `preview`/`pack`/`publish` 必然落到内置 `simple.json`（只删 `.preference.json` 而保留 `.applied.json` 的话，解析仍会通过 applied 继承上次主题，所以 `--clear` 一并清掉）。
+- **回到默认状态**：`guanvis theme preference --clear` 会**同时**删除 `.preference.json` 和 `.applied.json`。新建工程下次运行会使用内置 `simple.json`；checkout 工程会优先恢复 `.guanvis/base/page.json` 记录的线上主题或“无主题”状态，避免清除偏好反而改坏已有页面。
 
 ### 离线 vs 联网