@guandata/guanvis 0.1.32 → 0.1.34

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## @guandata/guanvis 0.1.34 - 2026-07-25
+
+- 预览默认返回精简摘要，并把完整结果保存到工程目录，复杂仪表板的校验结论更容易查看；依赖旧版完整输出的脚本可使用 `--full`。
+- 发布成功后可直接返回页面访问地址，并增强临时目录缺失场景的兼容性。
+- 必填筛选器会保留不可清空设置，避免发布后出现无效的清空操作。
+- 优化 Agent 发布流程和内置主题提示，减少重复操作与无效排查。
+
+## @guandata/guanvis 0.1.33 - 2026-07-23
+
+- 指标图表支持主次指标组和数字分组，可构建层次更清晰的指标展示。
+- 增强页面发布前检查，可提前发现无效资源 ID、未挂载到页面的卡片和资源生成错误。
+- 优化页面检出、指标初始化和全局参数读取效率，复杂页面编辑等待更少。
+- 大型资源导入支持更灵活的等待时间，并能更快返回明确失败原因。
+
 ## @guandata/guanvis 0.1.32 - 2026-07-20
 
 - 新增复杂报表 Pro 的创建、编辑、检视、反编译与发布完整链路。

package/README.md

@@ -24,9 +24,12 @@ guanvis gen-layout-id cardGroup
 # 初始化：从 BI 获取数据集结构
 guanvis init <dsId> -d ./my_dashboard/
 
-# 预览生成结果（JSON 输出）
+# 预览生成结果（默认输出摘要，完整结果写入工程目录的 .preview.json）
 guanvis preview ./my_dashboard/
 
+# 兼容旧版：完整结果输出到终端
+guanvis preview ./my_dashboard/ --full
+
 # 打包为 ZIP 资源包
 guanvis pack ./my_dashboard/
 
@@ -51,6 +54,20 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.34
+
+- 预览默认返回精简摘要，并把完整结果保存到工程目录，复杂仪表板的校验结论更容易查看；依赖旧版完整输出的脚本可使用 `--full`。
+- 发布成功后可直接返回页面访问地址，并增强临时目录缺失场景的兼容性。
+- 必填筛选器会保留不可清空设置，避免发布后出现无效的清空操作。
+- 优化 Agent 发布流程和内置主题提示，减少重复操作与无效排查。
+
+### @guandata/guanvis 0.1.33
+
+- 指标图表支持主次指标组和数字分组，可构建层次更清晰的指标展示。
+- 增强页面发布前检查，可提前发现无效资源 ID、未挂载到页面的卡片和资源生成错误。
+- 优化页面检出、指标初始化和全局参数读取效率，复杂页面编辑等待更少。
+- 大型资源导入支持更灵活的等待时间，并能更快返回明确失败原因。
+
 ### @guandata/guanvis 0.1.32
 
 - 新增复杂报表 Pro 的创建、编辑、检视、反编译与发布完整链路。

package/package.json

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

package/skills/guanvis/SKILL.md

@@ -19,15 +19,17 @@ compatibility: "Requires Node.js 14+. Install via npm link (local) or npm instal
 
 - `schema.js` 是由 `init` / `checkout` 生成的数据集事实快照，不手改；数据集字段变化时重新运行对应命令。`metrics.js` 是由 `metric-init` 生成的指标事实快照，不手改；指标口径、适用维度或格式变化时重新运行 `metric-init`。
 - 全局参数先用 `guanvis parameter` 创建或复用，再通过 `dynamic-parameters.js` 按 `dpId` 引用；`pack`/`publish` 不会隐式写入参数。创建前必须按名称查询；若系统已有同名有效参数，立即停止并让用户明确选择“更新已有参数”或“换名创建”，不得自动复用或修改。只有用户明确选择更新后，才可按该参数的 `dpId` 执行 `update`。
-- `card_*.js`、`selector_*.js`、`page.js` 是可编辑源文件；`*_package.zip`、preview JSON、publish 后线上资源都是派生产物。
+- `card_*.js`、`selector_*.js`、`page.js` 是可编辑源文件；`*_package.zip`、`.preview.json`（preview 落盘的全量 payload）、publish 后线上资源都是派生产物，不要手工编辑。
+- **Page 归属红线**：任何包含 Card 或 Selector 的资源包都必须同时包含 Page，且包内每个 Card/Selector 都必须被至少一个 Page 引用。禁止发布只有 Card/Selector、没有 Page 的资源包，也禁止留下未放入任何 Page 的 Card/Selector；否则后端会产生 `pg_id` 为空、无法访问且可能阻塞后续页面发布的孤儿卡片。校验失败时在 `page.js` 中放置对应资源，再将 Page 与 Card/Selector 同包 `pack`/`publish`。
 - 已有线上仪表板用 `guanvis checkout <pgId> -d <dir>` 拉成可编辑工程：checkout 会尽量生成 `schema.js`，但数据集无权限/已删除/跨环境残留时只 warning 并继续生成可编辑工程；普通 Card 用 `attachCard(cdId, ".guanvis/base/cards/<cdId>.json")` 接受线上 JSON 作为基线；自定义图表（SDK/ECHARTS_LITE）会把脚本/HTML/CSS 反编译到 `charts/<cdId>.js|.html|.css`，超长内联资源（GeoJSON、base64 图片）抽取回 `charts/<cdId>_assets/` + `__asset_text/__asset_base64` 占位符（逐字节往返验证，未编辑时 diff 恒为空），card JS 用 `attachCard(...).loadContent("charts/<cdId>")` 引用，直接编辑内容文件即可改图表；复杂报表 Pro 会额外下载可编辑 xlsx 到 `templates/`，生成 `createComplexReportPro()` 父卡和嵌套的 attached data view，并使用下一模板版本，旧版复杂报表 checkout 直接拒绝；Page 生成 `createPage(...).setBasePath(...).placeCard("cdId", ...)` 脚本，尽量反编译根布局里的 Tab/CardGroup/AreaTitle/SelGroup 和快捷筛选组，并保留 parentDirId。checkout 工程只用于修改指定 Page，不用于复制新 Page；遇到嵌套布局组件等当前 DSL 不能安全表达的结构，checkout 会直接失败，不生成会清结构的工程。只支持普通仪表板（pgType=PAGE），自助取数/数据大屏/清单页等特殊页面会在 checkout 入口直接报错。
 - **Checkout 账号要求**：checkout 读到的是"当前账号视角"的卡片定义，publish 会把它整体回写。必须用对页面涉及数据集拥有**完整列权限、无脱敏限制**的账号（推荐资源 owner 或管理员）执行 checkout/publish，否则读接口会按该账号权限裁剪 zone 字段/脱敏字段，回写后这些字段会从线上卡片中永久丢失。租户启用多语言时，操作账号语言应与卡片原始语言一致，避免把翻译后的字段显示名固化回卡片。
 - **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 混入同一个发布目标。
-- Card/Page/Selector 的 `.setId(...)` 建议使用 `guanvis genid` 生成；如果生成或填写的 24 位 ID 以数字开头，重新生成一组，避免 BI 前端把 ID 拼成 CSS selector（如 `#5bef...`）时触发 `querySelector` 语法错误。
-- 先 `preview/pack` 做本地结构验证，再 `publish/upload`；修改已发布资源前先判断变更类型：仅修复 Card/Page 描述时应保留原资源 ID，使用 `card/page set-description` 并同步维护 JS 中的 `.setDescription(...)`；调整图表、布局、筛选器、字段等看板内容时，按线上仪表板更新策略处理。
+- Card/Page/Selector 的 `.setId(...)` 建议使用 `guanvis genid` 生成（保证字母开头）。数字开头的 24 位 ID 会让 BI 前端把 ID 拼成 CSS selector（如 `#5bef...`）时触发 `querySelector` 语法错误，`preview`/`pack`/`publish` 会对**新建资源**直接报 error 拦截；checkout/attach 的已有线上资源不受此限制（保留原 ID 原地更新）。
+- 先 `preview` 做本地结构验证，再 `publish`（publish 自带构建打包上传，**发布前不需要单独 `pack`**；`pack` 只用于生成离线 ZIP 交付物走 `upload`）；修改已发布资源前先判断变更类型：仅修复 Card/Page 描述时应保留原资源 ID，使用 `card/page set-description` 并同步维护 JS 中的 `.setDescription(...)`；调整图表、布局、筛选器、字段等看板内容时，按线上仪表板更新策略处理。
+- **编辑红线（编辑 ≠ 删除重建）**：用户要求修改/改名已发布 Page 或 Card 时，必须保留原 pgId/cdId 原地覆盖发布，先按工程来源分流。**本地有源工程**（该 Page 就是当前 guanvis 工程创建并发布的，`card_*.js` / `page.js` 还在，且线上没有在发布后被网页端改动过）：直接修改本地 JS 源文件（改名即改 `createCard(...)` / `createPage(...)` 标题）重新 publish 同 ID 覆盖。**线上在发布后被网页端修改过、本地没有原始 JS 工程、或不确定线上是否已被改动**：用 `checkout` 拉取线上版本编辑——Page 改 checkout 生成的 `createPage(...)` 标题，已 checkout 的 Card 用 `attachCard(...).setName(...)`，**不得**把 `attachCard` 改写成 `createCard()`（那会绕过 base JSON，未被 DSL 表达的线上配置会在覆盖发布时丢失，`createCard()` 只用于新增卡片）。**禁止**用"新建一个新 Page/Card + 删除或废弃旧的"来模拟编辑——资源 ID 变化会让收藏、分享链接、订阅推送、门户菜单引用和页面权限配置全部失效，这些状态 guanvis 无法迁移。需要"保留旧页面、出一个新版本"时用 `guanvis page save-as`。全局参数编辑同理：只能 `parameter update <dpId>` 原地更新，禁止 delete 后重建同名参数（dpId 变化会让所有引用它的卡片/筛选器断链）；`parameter delete` 只用于用户明确要求删除参数本身。
 - **资源包安全红线**：Agent 只编辑 DSL 源文件；资源包 ZIP 是 `guanvis pack/publish` 的派生产物，不手工生成、解包修改或重打包。`guanvis upload` 只允许上传 `guanvis pack` 原样生成的 ZIP。若用户要求批量重绑资源、迁移已有页面或复用线上页面结构，先停下来说明风险并确认方案，不要直接改 ZIP。
 - 发布后优先用 `guancli page get/card get` 回读结构与配置。只有在明确需要视觉质量判断、且当前大模型支持图像理解时，才使用 `guanvis screenshot <pageId>` 生成 PNG 并交给模型分析；不要把截图作为默认闭环步骤，因为图像理解会额外消耗 token/费用。
 
@@ -223,7 +225,7 @@ var card = createCard(ChartType.PIVOT_TABLE, "区域产品交叉分析")
 registerCard(card.build());
 ```
 
-### 5. 编写 page.js（可选）
+### 5. 编写 page.js（发布 Card/Selector 时必需）
 
 ```javascript
 var page = createPage("销售仪表板")
@@ -287,7 +289,7 @@ registerPage(p.build());
 # 生成资源 ID（用于 .setId() 调用）
 guanvis genid       # 生成 1 个
 guanvis genid 5     # 生成 5 个
-# 如果生成或填写的 ID 以数字开头，重新生成一组，避免 BI 前端 querySelector("#<id>") 报非法 selector
+# genid 保证字母开头；手写数字开头 ID 会被 preview/pack/publish 对新建资源直接报错拦截
 
 # 生成布局组件 ID
 guanvis gen-layout-id tab                 # 生成 1 个 tab_ + 默认 6 位字母
@@ -303,7 +305,8 @@ guanvis checkout <pageId> -d ./existing_dashboard
 # 若 schema.js 未生成或缺字段，后续可手动 guanvis init <dsId> -d ./existing_dashboard --force 补齐
 # checkout --overwrite 会清理输出目录下所有根级 .js 和旧 .guanvis，避免 schema/selector/metrics/other.js 残留混入运行
 
-# 预览生成结果（JSON 输出到 stdout，含 payload 验证，用于调试）
+# 预览生成结果（默认输出摘要 JSON：卡片/页面清单 + changeSummary + 验证状态；
+# 全量 payload 写入工程目录 .preview.json，需要时用 read_file 按需查看，或加 --full 全量输出）
 guanvis preview ./my_dashboard/
 # checkout/attach 工程的路径级变更摘要（也会出现在 preview JSON 的 changeSummary 中）
 guanvis diff ./existing_dashboard/
@@ -364,7 +367,8 @@ guanvis pack ./project
 
 `publish` 和 `upload` 使用 BI 的 **transfer API**（`/api/manual/template/transfer`），特点：
 - `needIdMapping=false`：保持资源 ID 不变，重复导入会覆盖同 ID 资源
-- 发布前在线覆盖检查只探测 Page ID，不探测 Card/Selector ID；如果资源包不包含 Page，则不会执行在线覆盖检查，避免部分 BI 版本在导入前缓存"找不到相关卡片"
+- 发布前强制校验 Page 归属：资源包包含 Card/Selector 时必须同时包含 Page，且每个 Card/Selector 都必须被至少一个 Page 引用；Card-only 和孤儿 Card/Selector 包会在上传前被拒绝，并提示在 `page.js` 中放置资源后同包发布
+- 在线覆盖检查只探测 Page ID，不探测 Card/Selector ID，避免部分 BI 版本在导入前缓存"找不到相关卡片"
 - 认证方式：随底层 `guancli fetch` 使用 `Cookie: uIdToken=...`
 - 需要 `raw-backend-response: TRUE` header 绕过前端代理层
 - 不需要目标系统开启"一键迁移"开关，所有环境通用
@@ -419,7 +423,7 @@ registerComplexReportPro(createComplexReportPro("销售月报")
     .build());
 ```
 
-`page.js` 正常 `registerPage`（Pro 卡按注册顺序参与 card index，或用 ID 字符串）；**Pro 必须与 Page 同包发布**，单独发 Pro 卡片会导入成功但线上查询不可用。之后与普通流程一致：`pack` → 确认 → `publish`。
+`page.js` 正常 `registerPage`（Pro 卡按注册顺序参与 card index，或用 ID 字符串）；**所有 Card/Selector 都必须与引用它们的 Page 同包发布**，Pro 也不例外。之后与普通流程一致：`pack` → 确认 → `publish`。
 
 ### Pro-2. 编辑已有 Pro（checkout → inspect/decompile → 改 → diff → publish）
 

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

@@ -10,6 +10,8 @@
 | `.addRow(field)` | 添加行维度（X 轴） |
 | `.addColumn(field)` | 添加列维度（按维度分组着色，如按地区/类别分色）。仅 `STACKED_COLUMN`、`GROUPED_COLUMN`、`GROUPED_BAR` 等多指标图表支持 |
 | `.addMetric(field)` | 添加度量（Y 轴，主轴） |
+| `.addMetricGroup(group)` | 添加数值组或嵌套数值组；仅支持 `PIVOT_TABLE` / `GROUPED_TABLE` / `LAYER_TREE_TABLE` |
+| `.addMainViceGroup(group)` | 添加主副指标组；仅支持 `PIVOT_TABLE` |
 | `.addMetricAdditional(field)` | 添加副轴度量（仅组合图 `*_WITH_LINE`/`*_WITH_SYMBOL`），默认绑定副 Y 轴（`plotOn: secondary`） |
 | `.addDynamicRow(name, fields, options?)` | 添加动态维度组，候选字段写入 row |
 | `.addDynamicColumn(name, fields, options?)` | 添加动态维度组，候选字段写入 column |
@@ -30,6 +32,7 @@
 | `.setThemeColor(tcId, colors)` | 主题颜色 |
 | `.setLimit(count)` | 数据行数限制 |
 | `.setConditionalFormat(config)` / `.setAuxiliaryLine(config)` | 条件格式/辅助线 |
+| `.setMainViceStyle(config)` | 设置主副指标内容样式，配置见“数值组与主副指标组” |
 | `.linkTo(target, config)` | 图表卡片点击联动；`target` 可传布局 index 或 cardId，详细规则见本节 Card Linkage |
 | `registerDrillPath(parentCardIndex, drillCards, config?)` | 全局函数，声明固定路径下钻，详细规则见本节 Card Drill |
 | `.setRawSettings(key, value)` | 原始设置 |
@@ -48,6 +51,83 @@
 
 `hidden` 和 `selectType` 不开放配置；资源包固定写 `hidden: false`、`selectType: "SEARCHBOX"`。动态字段不写 `stateValue.dzFieldValues`，前端加载卡片时会根据 `dynamicZoneInfo.dzMappings.defaultValue` 初始化默认选中值。
 
+#### 数值组与主副指标组
+
+数值组使用 `createMetricGroup(title)`，主副指标组使用 `createMainViceGroup(title)`。组 ID 是 5 位大小写字母，通过 `guanvis gen-alpha-id --length 5` 生成；不要使用 Card ID 或布局组件 ID。
+
+同一套 group builder 同时适用于普通 `createCard()` 和指标平台 `createMetricChart()`。普通卡组内使用 `f()` / `field()`，指标平台卡组内使用 `metric()`；不要在同一张卡中混用两种字段引用。
+
+```javascript
+var revenue = createMetricGroup("收入")
+    .setId("AbCdE")
+    .setHeaderStyle({
+        backgroundColor: "#EAF2FF",
+        color: "#245BDB",
+        fontSize: 14,
+        bold: true
+    }, { syncToFields: true })
+    .addMetric(f("销售额", { aggrType: AggrType.SUM }))
+    .addMetric(f("利润", { aggrType: AggrType.SUM }));
+
+var operation = createMetricGroup("经营指标")
+    .setId("FgHiJ")
+    .addGroup(revenue);
+
+var performance = createMainViceGroup("销售表现")
+    .setId("PqRsT")
+    .setMainMetric(f("销售额", { aggrType: AggrType.SUM }))
+    .addViceMetric(f("销售额同比", { aggrType: AggrType.SUM }));
+
+var card = createCard(ChartType.PIVOT_TABLE, "经营分析")
+    .setId("aaaaaaaaaaaaaaaaaaaaaaaa")
+    .bindDataset(DS)
+    .addRow(f("区域"))
+    .addMetricGroup(operation)
+    .addMainViceGroup(performance)
+    .setMainViceStyle({
+        main: { fontSize: 16, color: "#1F2329", bold: true },
+        vice: { fontSize: 12, color: "#646A73", bold: false },
+        viceIconStyle: "positiveGreen"
+    });
+```
+
+`MetricGroupBuilder`：
+
+| 方法 | 说明 |
+|---|---|
+| `.setId(id)` | 必填，严格 5 位大小写字母，整棵组树内唯一 |
+| `.addMetric(field)` | 添加组内度量 |
+| `.addGroup(metricGroup)` | 添加嵌套数值组；主副指标组不能嵌套 |
+| `.setHeaderStyle(style, options?)` | 设置分组表头；`style` 支持 `backgroundColor`、`color`、`fontSize`（12～20）、`bold`；`options.syncToFields` 默认 `true` |
+
+`MainViceGroupBuilder`：
+
+| 方法 | 说明 |
+|---|---|
+| `.setId(id)` | 必填，严格 5 位大小写字母 |
+| `.setMainMetric(field)` | 设置唯一的主指标，必填 |
+| `.addViceMetric(field)` | 添加副指标，至少一个 |
+| `.setHeaderStyle(style, options?)` | 与数值组表头配置相同 |
+
+`setMainViceStyle()` 中 `main` 和 `vice` 分别支持 `fontSize`（1～72）、`color`、`bold`；`viceIconStyle` 支持 `positiveRed`、`positiveGreen`、`displayNull`。这些配置彼此独立，不共享公共样式对象。
+
+组内字段只在 group builder 中声明，不要再对同一个字段调用 `card.addMetric()`。构建时字段按 DSL 声明顺序写入 metric zone，并写入叶子组或当前组的 `subZoneId`。`PIVOT_TABLE` / `GROUPED_TABLE` 有度量时自动保证 row/column 中只有一个 MPH；已有合法位置会保留，否则补到 column。`LAYER_TREE_TABLE` 不添加 MPH。
+
+attach 已有卡片时，普通 `updateMetric()`、`moveMetric()` 不会删除 `subZoneId`；`removeMetric()` 删除最后一个组内字段后会清理空组。可使用：
+
+```javascript
+attachCard(CARD_ID, BASE_PATH)
+    .renameMetricGroup("AbCdE", "收入与利润")
+    .setMetricGroupHeaderStyle(
+        "AbCdE",
+        { backgroundColor: "#DCE8FF", bold: true },
+        { syncToFields: true }
+    )
+    .setMainViceStyle({ main: { bold: true } });
+```
+
+当线上 metric zone 已有 `subZones` 时，`setMetrics()` / `clearMetrics()` 会直接报错，避免静默冲平分组。确实需要取消分组时，必须显式调用 `.clearMetricGroups()`；它只解除组关系并保留 metric 字段，之后才能整体替换 metric zone。attach 中未被上述 API 修改的表头高级字段、主副指标字体字段和其它线上 meta 会原样保留。
+
 ### MetricChartBuilder（指标平台指标卡片）
 
 用于“用指标平台已有指标创建卡片”，生成后端 `CARD_TYPE.METRIC_CHART`（`cdType=13`）。不要用普通 `createCard()` 伪造，也不要把指标 ID 当作数据集字段。
@@ -64,6 +144,9 @@
 | `.setId(cardId)` | 设置 24 位资源 ID，用于重复导入覆盖 |
 | `.addRow(field)` / `.addColumn(field)` | 添加指标适用维度 |
 | `.addMetric(metric)` | 添加指标平台指标；至少一个 |
+| `.addMetricGroup(group)` | 添加数值组或嵌套数值组；支持 `PIVOT_TABLE` / `GROUPED_TABLE` / `LAYER_TREE_TABLE` |
+| `.addMainViceGroup(group)` | 添加主副指标组；仅支持 `PIVOT_TABLE` |
+| `.setMainViceStyle(config)` | 设置主副指标内容样式，与普通 CardBuilder 一致 |
 | `.addDynamicRow(name, fields, options?)` / `.addDynamicColumn(name, fields, options?)` | 添加指标平台动态维度组 |
 | `.addDynamicMetric(name, fields, options?)` / `.addDynamicMetricAdditional(name, fields, options?)` | 添加指标平台动态指标组 |
 | `.addFilter(field, filterType, filterValue)` / `.addSort(field)` | 添加筛选/排序；排序字段的排序方向用 `sortType: SortOrder.ASC/DESC` |

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

@@ -157,6 +157,8 @@ registerMetricChart(card.build());
 |---|---|
 | `createMetricChart(chartType, name)` | 创建指标卡片 |
 | `.addMetric(metric(...))` | 添加主指标 |
+| `.addMetricGroup(createMetricGroup(...))` | 添加数值组或嵌套数值组 |
+| `.addMainViceGroup(createMainViceGroup(...))` | 添加主副指标组，仅透视表 |
 | `.addMetricAdditional(metric(...))` | 添加副轴指标 |
 | `.addRow(metricDim(...))` | 添加行/类目维度 |
 | `.addColumn(metricDim(...))` | 添加列/对比维度 |

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

@@ -5,7 +5,8 @@
 - **接口**：`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，则不会执行在线覆盖检查。checkout 工程表示修改指定 Page，不在 CLI 内复制新版本或手写 ID 映射。
+- **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 映射。
+- **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`，后端异步完成导入
 
@@ -36,6 +37,7 @@ checkout 工程表示“基于线上快照修改指定 Page”，不会新建 Pa
 - card 文件名建议 `card_NN_xxx.js` 控制执行顺序。
 - selector 文件名建议 `selector_NN_xxx.js`，在 card 之后执行。
 - page 文件必须命名为 `page.js`。
+- 包含 Card/Selector 时必须提供 `page.js`，并把包内每个 Card/Selector 放入至少一个 Page；禁止 Card-only 或孤儿 Card/Selector 资源包。
 - 筛选器的 `linkTo(cardIndex)` 中 cardIndex 基于过滤后的可联动目标序列（0-based）：普通图表和 MetricChart 按注册/布局顺序，文本/图片等不可联动资源不占序号，杜邦子图追加在末尾。
 - 资源包 ZIP 是派生产物，不是可编辑源文件；不要手工编辑或重打包 ZIP。
 - **文件访问边界**：只允许访问以下路径，不要主动探索或读取用户未明确授权的其他目录：

package/skills/guanvis/references/theme.md

@@ -14,7 +14,7 @@ AI 选择主题时不要把租户主题列表里的默认“浅色”/“深色
 - `keywords` 在 `.index.json` 上没有任何命中
 - `.applied.json` 引用的 `themeId` 本地快照已被删除（applied 步骤**只读本地、不再发起 sync**）
 
-执行命令时 stderr 会打印决策结果。命中线上主题时形如 `Theme: <name> [<id>] (source=preference|applied)`；落到自带兜底时形如 `Theme: 简约 (source=fallback, built-in simple.json)`，特意不打印 themeId 是因为那只是 skill 与 BI 默认值对齐的实现细节，不是租户主题列表里能查到的 ID。fallback 横幅只在 `pack`/`publish` 打印；`preview`/`diff` 是高频只读命令，落到兜底时不再重复打印（命中真实主题时仍会打印）。
+执行命令时 stderr 会打印决策结果。命中线上主题时形如 `Theme: <name> [<id>] (source=preference|applied)`；落到自带兜底时形如 `Theme: 简约 (source=built-in simple.json)`（内置默认与 BI 默认主题对齐，属正常行为而非降级），特意不打印 themeId 是因为那只是 skill 与 BI 默认值对齐的实现细节，不是租户主题列表里能查到的 ID。built-in 横幅只在 `pack`/`publish` 打印；`preview`/`diff` 是高频只读命令，落到兜底时不再重复打印（命中真实主题时仍会打印）。
 
 普通数据集图表和指标平台 MetricChart 都会应用主题视觉配置。MetricChart 只注入 `settings` 与 `meta.chartMain.props`：透视表补表格/合计样式，柱线饼等补坐标轴、图例、数据标签和主题色；不会修改 `zoneData`、`dsInfo`、`defaultView` 等查询相关字段。
 
@@ -70,7 +70,7 @@ AI 选择主题时不要把租户主题列表里的默认“浅色”/“深色
 
 - `theme show` 打印当前决策（`source` / `themeId` / `themeName` / `themeType`），只读。
 - `theme list` 列出 `.index.json` 中候选；`.index.json` 缺失时提示先 `sync`。
-- 看到 `Theme: 简约 (source=fallback, built-in simple.json)` 但用户期望非简约：检查 `.preference.json` 是否写好、对应 `themes/<id>.json` 是否存在；如果是 keywords 路径，跑 `theme list` 看候选名字是否真的包含关键词；联网命令还要看 stderr 是否打印了 `theme: sync failed: ...`。
+- 看到 `Theme: 简约 (source=built-in simple.json)` 但用户期望非简约：检查 `.preference.json` 是否写好、对应 `themes/<id>.json` 是否存在；如果是 keywords 路径，跑 `theme list` 看候选名字是否真的包含关键词；联网命令还要看 stderr 是否打印了 `theme: sync failed: ...`。
 - 看到 `multi-subdir project under <root> contains per-subdir themes/ in [...]`：你在多子目录工程的**根目录**直接跑了 preview/pack/publish，但子目录里有自己的 `themes/`。按提示 `cd` 进每个子目录单独执行；或如果不想用各子目录的主题，删除子目录下的 `themes/` 后再回到根目录运行。
 
 ## 设计规则

package/skills/guanvis/references/troubleshooting.md

@@ -14,7 +14,7 @@
 | `placeCard index out of range` | placeCard 的 cardIndex 超出已注册卡片数量 | 检查 registerCard/registerTextCard 的调用顺序和总数 |
 | `page has no cards` | page.js 中没有 placeCard | 确保 page.js 中为每个已注册的卡片调用了 placeCard |
 | `selector not linked to any card` | selector 没有调用 linkTo/linkToAll | 添加 `.linkToAll()` 或 `.linkTo(cardIndex)` |
-| `Theme: 简约 (source=fallback, built-in simple.json)` 但用户要求别的风格 | 偏好缺失 / themeId 在环境中不存在 / sync 失败 / keywords 没命中 | `theme list` 看候选 → `theme preference --theme-id ...` 或 `--keywords ... --sync`；联网命令注意 stderr 是否有 `theme: sync failed: ...` |
+| `Theme: 简约 (source=built-in simple.json)` 但用户要求别的风格 | 偏好缺失 / themeId 在环境中不存在 / sync 失败 / keywords 没命中 | `theme list` 看候选 → `theme preference --theme-id ...` 或 `--keywords ... --sync`；联网命令注意 stderr 是否有 `theme: sync failed: ...` |
 | publish 后 `.applied.json` 没更新 | 本次实际用的就是 skill 自带 `simple.json`（按设计 fallback 不写 applied） | 检查 stderr 的 `theme: ... falling back ...` 警告；确保对应 `themes/<id>.json` 存在或先 `theme sync` |
 | `invalid themeId "..." (...)` | themeId 不是合法的单段文件名（见 `publish-and-constraints.md` 中的约束） | 使用 `theme list` 里出现的 id；避免 `/`、`\`、`..`；或用 `theme preference --keywords` |
 | `theme: keywords "..." matched no theme` | 关键词与候选 themeName 没有公共子串 | `theme list` 核对候选名字；调整 keywords，或换成 `--theme-id` |