@guandata/guanvis 0.1.35 → 0.1.36

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## @guandata/guanvis 0.1.36 - 2026-08-04
+
+- 扩展仪表板标题、页面背景、筛选栏、卡片组、Tab 和分区的视觉配置，支持字体、颜色、图标、背景图、间距与分割线。
+- 表格可配置主题、斑马纹、边框、表头和数据区样式；柱形图和条形图可调整柱宽、间距和圆角。
+- 本地图片可随页面资源打包上传，检出已有页面后也能保留并继续编辑线上视觉配置。
+- 增强已有页面覆盖发布前的备份与兼容判断，降低不同 BI 版本下的误覆盖风险。
+
 ## @guandata/guanvis 0.1.35 - 2026-07-29
 
 - 补齐常用图表属性配置，支持背景、标题、图例、坐标轴、标签、辅助线、主题色和动态参数默认值等能力。

package/README.md

@@ -50,10 +50,17 @@ 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.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.36",
   "description": "观远 BI Card/Page 生成工具 - 通过 JS DSL 创建图表和仪表板",
   "bin": {
     "guanvis": "bin/run.js"

package/skills/guanvis/SKILL.md

@@ -26,7 +26,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 - Card/Page 描述也是 JS 源文件的一部分：新建看板或改版时，在 `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。
@@ -56,7 +56,7 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 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

@@ -5,7 +5,7 @@
 | 方法 | 说明 |
 |------|------|
 | `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,6 +23,7 @@
 | `.addLocation(field)` / `.addTarget(field)` / `.addCompare(field)` | 位置/目标/对比 |
 | `.setSplitSetting(config)` | 拆分图配置 |
 | `.setColorByColors(preset_or_config)` | 渐变色配置 |
+| `.setBarSetting(config)` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
 | `.setShapeColorType(type)` | 图形填充配置 |
 | `.setLineSetting(config)` | 折线显示配置 |
 | `.setCardSetting(config)` | 卡片背景、主题跟随、内边距和内容间距 |
@@ -31,7 +32,7 @@
 | `.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 +165,9 @@ attachCard(CARD_ID, BASE_PATH)
 | `.setDataLabel()` / `.setMetricAdditionalDataLabel()` | 数据标签配置 |
 | `.setAxis()` / `.setAuxiliaryLine()` / `.setTooltip()` | 坐标轴、辅助线和工具提示配置 |
 | `.setLineSetting()` | 折线显示配置 |
+| `.setBarSetting()` | 柱形图/条形图的柱体宽度、间距和圆角配置 |
 | `.setPieSetting()` / `.setPieCenterText()` | 饼图配置 |
-| `.setTableSetting()` / `.setTableCellMerge()` / `.setGrandTotal()` | 表格配置 |
+| `.setTableSetting()` / `.setTableCellMerge()` / `.setGrandTotal()` | 表格行为、视觉样式与汇总配置 |
 | `.setSplitSetting()` / `.setShapeColorType()` | 拆分图和图形填充配置 |
 | `.setRawSettings()` | 原始设置 |
 | `.setProps(obj)` | 设置指标卡片 `meta.chartMain.props` |
@@ -388,7 +390,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,12 +404,47 @@ 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`。多次调用深度合并 |
 | `.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
@@ -432,7 +469,66 @@ page.setWidthAdaptive(true, 1600);
 
 `setWidthAdaptive(true, width)` 的 `width` 会先静默四舍五入，再校验是否位于 `800 ~ 4096`；缺失或非法时使用 1280。宽度自适应不能与 `layoutType: "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 +536,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；非法值产生 warning 并丢弃 |
+| `labelFont` | 支持 `fontFamily`、`fontSize`、`color`、`bold`、`italic`、`underline`；字号为整数 9～20 |
+| `controlFont` | 支持 `fontFamily`、`fontSize`、`color`、`bold`、`italic` |
+| `buttonFont` | 支持 `fontFamily`、`fontSize`、`bold`、`italic`、`underline`；文字颜色由产品固定 |
+| `buttonColor` | 按钮强调色 |
 
-`padding` 支持 `top/right/bottom/left` 和`0 ~ 32`内的整数；非数字、`NaN`、`Infinity` 等非法值会产生 warning 并丢弃。
+`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 +582,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 +611,9 @@ page.setFilterPanelLayout({
 | `.setBackgroundColor(color)` | 背景色 |
 | `.setShowBgImage(boolean)` | 是否显示背景图 |
 | `.setShowIcon(boolean)` | 是否显示图标 |
+| `.setFontStyle(style)` | 稀疏设置字体、字形和对齐方式 |
+| `.setBackgroundImage(image)` | 设置背景图片；支持外链、已有 Store 地址或本地 `uploadPath` |
+| `.setIcon(image)` | 设置图标图片；图片规则同上 |
 | `.build()` | 构建 areaTitle result |
 
 ```javascript
@@ -503,12 +642,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 +775,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
@@ -1529,6 +1724,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,45 @@ attachCard(CARD_ID, BASE_PATH)
 
 堆积面积图和百分比堆积面积图使用 `skipNulls`、`opacity`、`showPoint`、`pointShape`、`pointSize`、`showAsSpline` 和 `lineStyle`。
 
+## 柱形图与条形图
+
+### `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

@@ -26,7 +26,7 @@ checkout 读到的是"当前账号视角"的卡片定义，publish 会把它整
 - **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()`；颜色、字体和背景继续由主题管理。
+- **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,10 +179,11 @@ 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` |
 | `.setShapeColorType(type)` | 设置图形填充 |
 | `.setLineSetting(obj)` | 设置折线显示 |
 | `.setAuxiliaryLine(obj)` | 设置辅助线 |

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 联网