@guandata/guanvis

观远 BI Card/Page 生成工具，通过 JS DSL 创建图表、筛选器和仪表板。

安装

npm install -g @guandata/guanvis
guanvis install-skill

安装后即可在终端使用：

# 生成资源 ID
guanvis genid 5

# 生成布局组件 ID
guanvis gen-layout-id tab
guanvis gen-layout-id panel 3 --length 8
guanvis gen-layout-id areaTitle
guanvis gen-layout-id cardGroup

# 初始化：从 BI 获取数据集结构
guanvis init <dsId> -d ./my_dashboard/

# 预览生成结果（JSON 输出）
guanvis preview ./my_dashboard/

# 打包为 ZIP 资源包
guanvis pack ./my_dashboard/

# 一步到位：构建并上传到 BI
guanvis publish ./my_dashboard/

# 上传已有 ZIP；只上传 guanvis pack 原样生成的资源包
guanvis upload ./my_dashboard_package.zip

# 只检查将要覆盖哪些线上 Page，不上传
guanvis publish ./my_dashboard/ --dry-run

# 明确要覆盖同 ID 线上 Page 时才加；覆盖前会先导出备份记录，备份成功才继续
guanvis publish ./my_dashboard/ --allow-overwrite

说明：npm 包名为 @guandata/guanvis，用户侧 CLI 命令统一为 guanvis。

guanvis upload 只是上传器，不是自定义资源包制作入口。资源包应由 DSL 源文件通过 guanvis pack / guanvis publish 生成；不要手工生成、解包修改或重打包 ZIP。需要批量重绑资源或迁移已有页面时，先确认方案，不要直接改 ZIP 上传。

使用 --allow-overwrite 覆盖线上 Page 时，CLI 会先为冲突 Page 创建资源迁移导出备份记录，并等待备份导出成功；备份包含 Page 及其组成资源，但不会沿血缘额外导出数据集、数据账户等上游资源，避免普通用户因缺少上游资源所有者权限而无法备份。备份失败或超时会中止覆盖。Card/Selector ID 不做在线覆盖检查。CLI 不自动下载备份包，会在输出中打印 packageId。需要回滚时，到 BI 资源迁移导出记录中下载该资源包后手动导入覆盖回去。

版本更新

@guandata/guanvis 0.1.31

• 新增仪表板筛选栏布局配置，支持网格或流式排列、间距、内边距、标签位置和操作区位置。
• 增强已有仪表板 checkout 后的编辑能力，图表属性和页面布局修改会在保留线上未修改配置的基础上稳定回写。
• 覆盖页面前的备份不再额外包含上游数据集和数据账号，减少普通用户因上游资源权限不足而无法更新页面的情况。

@guandata/guanvis 0.1.30

• 支持 checkout 线上页面到本地工程，并增强已有仪表板的编辑、差异查看和回写流程。
• 支持动态维度、动态指标和拆分图表相关构建能力，提升复杂图表生成覆盖面。
• 新增筛选器分组和开关类检查能力，页面交互配置更容易验证。
• pack / preview / lint 诊断增强，可提前发现资源 ID、布局、联动和覆盖相关问题。

@guandata/guanvis 0.1.29

• 支持筛选器级联联动，页面中的筛选器可以按上游筛选结果继续约束下游筛选项。
• 画布布局支持放置筛选器，复杂仪表板可把筛选器和图表一起纳入布局管理。
• 自定义图表的数据视图可作为点击联动来源，并支持页面筛选器过滤自定义图表。
• 表格卡片支持只配置维度字段，init 支持多数据集页面中的数据集别名，降低多数据集页面配置成本。
• 比较卡支持本期/对比期输出，发布覆盖保护可识别并修复异常线上资源，必要时可跳过覆盖备份。

@guandata/guanvis 0.1.28

• 修复自定义图表重复生成数据视图卡片的问题，减少资源包中的冗余或冲突配置。
• install-skill 适配 WorkBuddy 配置目录，提升本机编码助手安装兼容性。

@guandata/guanvis 0.1.27

• publish / upload 避免发布前对 Card 做额外导入探测，减少无权限或跨环境场景下的误拦截。
• 覆盖保护说明同步调整，明确 Page 级覆盖检查和资源包上传边界。

@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 布局能力，支持在页面中组织分区标题和卡片分组。
• gen-layout-id 支持生成 area title 相关布局 ID，便于构建复杂页面布局。
• 增强布局 DSL、打包导出和页面布局校验，补充大量布局场景测试。

@guandata/guanvis 0.1.23

• 新增指标卡片构建能力，支持基于指标配置生成图表卡片，并补充 metric init 和指标图表参考文档。
• 增强指标卡片 payload、联动、导出打包与发布前校验，提升指标图表构建稳定性。
• publish --allow-overwrite 覆盖线上 Card/Page 前会先创建资源迁移导出备份，备份失败或超时会中止覆盖。
• 补充资源包安全约束，强调只上传 guanvis pack 原样生成的资源包。

@guandata/guanvis 0.1.22

• install-skill 增加 WorkBuddy skill 安装路径支持。
• 补充发布与资源约束说明，强调发布前检查资源 ID、命名和覆盖风险。

0.1.21

• 新增卡片固定钻取路径能力，可在构建时配置图表点击后的固定下钻路径。
• 新增杜邦分析图表支持，扩展财务分析类图表构建能力。
• 发布与上传阶段增加线上资源覆盖保护；当前版本默认阻止误覆盖同 ID 线上 Page，并可通过 dry-run 检查影响范围。
• 优化卡片诊断信息和联动/点击动作解析，提升复杂页面发布前的可检查性。

0.1.20

• 新增普通图表卡片点击联动能力，支持通过 card.linkTo(...) 配置卡片之间的字段映射联动。
• 构建阶段会校验同页联动、字段映射、日期粒度和联动环，提前发现无法发布的联动配置。
• 补充图表卡片联动文档和测试覆盖，提升联动页面生成稳定性。

0.1.19

• 增强日历筛选器默认值校验，固定默认值会校验日期格式、区间端点数量、起止顺序和粒度一致性。
• 日历筛选器会校验绑定字段类型，避免非日期字段误配日期默认值。
• 新增 setDefaultDateRange(start, end) 辅助方法，配置日期区间默认值更直接。

0.1.18

• 新增 Tab 布局能力，支持通过 createTab() / addPanel() 组织同页多组可切换内容。
• 新增 gen-layout-id 命令，用于生成布局组件 ID。
• 增加 Tab 布局示例工程和文档说明，便于快速复用。
• 增强筛选器默认值校验，提前发现不匹配的筛选值配置。

0.1.17

• 构建流程会将 npm 包版本注入到 guanvis 二进制，确保运行时版本信息与发布包一致。
• prepublishOnly 增加构建脚本测试，提升 npm 发布产物稳定性。

0.1.16

• 包名和命令入口统一移除 -skill 后缀，改为使用 @guandata/guanvis / guanvis。
• 新增 guanvis 可视化构建、打包、预览、发布、截图、主题等完整 CLI 与使用文档。
• 比较卡默认改为基于筛选条件计算占比，改善默认生成结果的业务可用性。
• init 生成的 schema.js 现在会包含数据集虚拟字段，便于后续卡片配置直接使用。
• 改进 npm 包运行与发布兼容性，包括 Windows 控制台 UTF-8 启动和 skill YAML 字段引用兼容。

Card/Page 的名称、描述和布局都应维护在 JS DSL 源文件中。新建或改版时，通过 preview/pack/publish 从 JS 源文件生成并发布资源；若只是修复已发布 Card/Page 的描述，应保留原资源 ID，使用 set-description 直接更新线上描述，并同步更新 JS 中的 .setDescription(...)：

guanvis card set-description <cdId> --description "卡片业务故事..."
guanvis page set-description <pgId> --file ./page_story.md --visible=false

var card = createCard(ChartType.KPI_CARD, "总销售额")
    .setId("abcdefghijklmnopqrstuvwx")
    .bindDataset(DS)
    .setDescription("业务故事：用于跟踪当前总销售额，口径为销售额 SUM。")
    .addMetric(f("销售额", { aggrType: AggrType.SUM }));

registerCard(card.build());

var page = createPage("销售看板")
    .setId("abcdefghijklmnopqrstuvw1")
    .setDescription("页面故事：面向经营管理层的销售总览。")
    .addFullWidthCard(0, 4);

registerPage(page.build());

也可以为 AI Coding Assistant 安装 Skill：

guanvis install-skill

卸载

npm unlink -g @guandata/guanvis

支持平台

• macOS (Apple Silicon / Intel)
• Linux (x64 / arm64)
• Windows (x64)

开发

# 编译所有平台 binary（需要 Go 工具链）
npm run build

# 发布到内部 Nexus npm 仓库
npm publish