@guandata/guanvis 0.1.24 → 0.1.26

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## @guandata/guanvis 0.1.26 - 2026-06-15
+
+- 修复自定义排序 payload 归一化问题，提升图表排序配置发布兼容性。
+- 资源包打包增加配置一致性校验，提前发现重复或冲突资源，降低上传失败和覆盖风险。
+
+## @guandata/guanvis 0.1.25 - 2026-06-11
+
+- 补充资源 ID 命名指引，建议 Card/Page/布局等资源 ID 使用字母开头，降低平台 ID 解析兼容风险。
+
 ## @guandata/guanvis 0.1.24 - 2026-06-09
 
 - 新增 area title 和 card group 布局能力，支持在页面中组织分区标题和卡片分组。

package/README.md

@@ -51,6 +51,15 @@ guanvis publish ./my_dashboard/ --allow-overwrite
 
 ## 版本更新
 
+### @guandata/guanvis 0.1.26
+
+- 修复自定义排序 payload 归一化问题，提升图表排序配置发布兼容性。
+- 资源包打包增加配置一致性校验，提前发现重复或冲突资源，降低上传失败和覆盖风险。
+
+### @guandata/guanvis 0.1.25
+
+- 补充资源 ID 命名指引，建议 Card/Page/布局等资源 ID 使用字母开头，降低平台 ID 解析兼容风险。
+
 ### @guandata/guanvis 0.1.24
 
 - 新增 area title 和 card group 布局能力，支持在页面中组织分区标题和卡片分组。

package/package.json

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

package/skills/guanvis/SKILL.md

@@ -22,6 +22,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` 生成；如果生成或填写的 24 位 ID 以数字开头，重新生成一组，避免 BI 前端把 ID 拼成 CSS selector（如 `#5bef...`）时触发 `querySelector` 语法错误。
 - 先 `preview/pack` 做本地结构验证，再 `publish/upload`；修改已发布资源前先判断变更类型：仅修复 Card/Page 描述时应保留原资源 ID，使用 `card/page set-description` 并同步维护 JS 中的 `.setDescription(...)`；调整图表、布局、筛选器、字段等看板内容时，按线上仪表板更新策略处理。
 - **资源包安全红线**：Agent 只编辑 DSL 源文件；资源包 ZIP 是 `guanvis pack/publish` 的派生产物，不手工生成、解包修改或重打包。`guanvis upload` 只允许上传 `guanvis pack` 原样生成的 ZIP。若用户要求批量重绑资源、迁移已有页面或复用线上页面结构，先停下来说明风险并确认方案，不要直接改 ZIP。
 - 发布后优先用 `guancli page get/card get` 回读结构与配置。只有在明确需要视觉质量判断、且当前大模型支持图像理解时，才使用 `guanvis screenshot <pageId>` 生成 PNG 并交给模型分析；不要把截图作为默认闭环步骤，因为图像理解会额外消耗 token/费用。
@@ -262,6 +263,7 @@ registerPage(p.build());
 # 生成资源 ID（用于 .setId() 调用）
 guanvis genid       # 生成 1 个
 guanvis genid 5     # 生成 5 个
+# 如果生成或填写的 ID 以数字开头，重新生成一组，避免 BI 前端 querySelector("#<id>") 报非法 selector
 
 # 生成布局组件 ID
 guanvis gen-layout-id tab                 # 生成 1 个 tab_ + 默认 6 位字母

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

@@ -414,7 +414,10 @@ createCard(ChartType.PIVOT_TABLE, "品牌同比分析")
     .addMetric(yoyRate)
     .addSort(f("品牌", {
         ordering: "ASC",
-        customSort: ["华东", "华南", "华北"]
+        customSort: {
+            turnedOn: true,
+            sortOrder: ["华东", "华南", "华北"]
+        }
     }));
 ```
 

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` 生成 |
+| `.setId(cardId)` | **必填**。设置资源 ID（严格 24 位字母数字，格式与后端 RandUtil.uuid 一致），支持多次上传覆盖更新。通过 `guanvis genid` 生成；如果生成或填写的 ID 以数字开头，建议重新生成一组，避免 BI 前端 `querySelector("#<id>")` 报错 |
 | `.bindDataset(dsId)` | 绑定数据集（必填，dsId 必须在 defineDataset 中注册） |
 | `.addRow(field)` | 添加行维度（X 轴） |
 | `.addColumn(field)` | 添加列维度（按维度分组着色，如按地区/类别分色）。仅 `STACKED_COLUMN`、`GROUPED_COLUMN`、`GROUPED_BAR` 等多指标图表支持 |

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

@@ -46,7 +46,7 @@
 
 所有 Card、Selector 和 Page **必须**调用 `.setId(id)` 设置显式 ID。未设置 ID 会在 JS 校验和 Go 校验两层报错，阻止生成。
 
-- `.setId(id)` 的 ID **必须**为严格 24 位字母数字字符串（正则：`^[a-zA-Z0-9]{24}$`），与后端 `RandUtil.uuid` 格式一致。
+- `.setId(id)` 的 ID **必须**为严格 24 位字母数字字符串（正则：`^[a-zA-Z0-9]{24}$`），与后端 `RandUtil.uuid` 格式一致。若生成或手填的 ID 以数字开头，建议重新生成一组，避免 BI 前端某些路径把 ID 拼成 CSS selector（如 `#5bef...`）时触发 `querySelector` 语法错误。
 - **生成 ID**：先运行 `guanvis genid <数量>` 生成足够的 ID，在编写脚本时直接填入每个 card/selector/page 的 `.setId()` 调用中。
 - **线上更新默认策略**：已发布过或线上正在使用的仪表板，后续修改默认生成新的 Page/Card/Selector ID，并给 Page 名称追加版本号后发布，保留旧版本不覆盖。
 - **覆盖前检查**：发布前可先运行 `guanvis publish <dir> --dry-run` 或 `guanvis upload <zip> --dry-run`，只构建/解析资源并列出将被覆盖的线上 Card/Page，不提交 transfer 任务。