@guandata/guanvis

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

安装

npm install -g --foreground-scripts @guandata/guanvis

全局安装/升级时会通过 postinstall 自动执行一次 guanvis install-skill 刷新 AI skill。--foreground-scripts 用于显示明确的成功、失败或跳过结果；失败时按提示手动运行 guanvis install-skill。CI 等无需 skill 的环境可设 GUAN_SKIP_INSTALL_SKILL=1 跳过。

安装包会通过 npm optionalDependencies 自动选择当前系统的原生二进制。不要使用 --omit=optional 或 optional=false；企业 npm 镜像也需要同步对应的 @guandata/guanvis-<平台>-<架构> 包。若平台包缺失，CLI 会显示对应包名和重新安装方法。

安装后即可在终端使用：

# 生成资源 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/

# 预览生成结果（默认输出摘要，完整结果写入工程目录的 .preview.json）
guanvis preview ./my_dashboard/

# 兼容旧版：完整结果输出到终端
guanvis preview ./my_dashboard/ --full

# 打包为 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 创建资源迁移导出备份记录，并等待备份导出成功；备份任务以 /api/task/{taskId} 为权威终态，资源包列表仅用于在任务结果未返回 packageId 时补齐 packageId，不用列表状态推翻任务结论。目标 BI 不支持用该 taskId 查询任务或响应缺少任务状态时，会兼容回退到资源包列表判定。备份包含 Page 及其组成资源，但不会沿血缘额外导出数据集、数据账户等上游资源，避免普通用户因缺少上游资源所有者权限而无法备份。备份失败或超时会中止覆盖。Card/Selector ID 不做在线覆盖检查。CLI 不自动下载备份包，会在输出中打印 packageId。需要回滚时，到 BI 资源迁移导出记录中下载该资源包后手动导入覆盖回去。

版本更新

@guandata/guanvis 0.1.49

• 同步本次发布的内部依赖更新，无用户可见行为变化。

@guandata/guanvis 0.1.48

• 同步共享鉴权与环境识别更新，外部认证环境下的资源链接与服务域解析更准确。

@guandata/guanvis 0.1.47

• 交叉表新增跨视图 filterBy 逐格校验，违规形态在 pack/publish 阶段给出明确修正提示，文档同时说明与 JOIN 虚拟视图的取舍。
• setSheetDefaults({ showGridLines }) 可关闭 Pro 报表网格线，并可原样回读；表格字号下限放宽到 9。
• publish --allow-overwrite 覆盖发布会重置被替换页面的草稿，避免编辑器打开上一版本内容。

@guandata/guanvis 0.1.46

• 正式启用按系统和架构拆分的原生程序包，安装命令不变，下载量与磁盘占用显著降低。
• 新建页面要求指定目标目录并确认落位计划，页面支持卡片池配置。
• 改进批量预览错误提示，并修复 DATA_GRID 主题处理。

@guandata/guanvis 0.1.45

• 安装时自动选择当前系统和架构的原生程序，减少下载量与磁盘占用，原有安装命令不变。
• 支持 macOS arm64/x64、Linux arm64/x64 和 Windows x64；离线安装包也会自动选择匹配的平台。
• 页面支持卡片池配置，改进批量构建错误提示和页面发布目标目录检查。

@guandata/guanvis 0.1.44

• 新增条件匹配、树状、层级树状和组合条件筛选器，并完善全局参数筛选器支持。
• 支持统一配置默认值、日期粒度、展示样式、卡片联动和筛选器级联，构建时检查无效映射与级联环路。
• checkout/publish 可保留并安全编辑已支持筛选器配置，同时改善 Windows npm 安装兼容性。

@guandata/guanvis 0.1.43

• 同步底层运行时兼容性与稳定性更新。

@guandata/guanvis 0.1.42

• 主题偏好会校验真实主题，打包时不再携带隐藏文件。
• 修复计算字段去重与展示类型，页面布局新增 flow 支持。
• 上传后页面归位和父目录设置更可靠，preview、checkout 校验失败会正确非零退出。
• 精简 Skill 主文档并保留完整的页面目录与页面操作约束。

@guandata/guanvis 0.1.41

• 新增页面目录创建、改名、移动和删除，以及页面删除、改名和移动能力。
• 发布时可指定页面目标目录，并拦截仍含生成器占位符的项目。
• 修复自有计算字段误判，自动关联卡片可正确接收筛选条件。
• 支持企业 OIDC 认证上下文，并升级底层请求兼容能力。

@guandata/guanvis 0.1.40

• 完善自定义图表布局与视觉验收指引，减少依赖手工数值微调造成的反复发布验证。

@guandata/guanvis 0.1.39

• 修复 attachCard 计算字段序列化问题，减少附加卡片配置异常。
• profile 模式发布后会直接输出页面 URL，便于继续验收。
• 完善自定义图表速查入口、最小 SDK 模板和注册函数类型校验。
• 改进 Skill 自动安装反馈、删除确认和 Windows CLI 兼容性。

@guandata/guanvis 0.1.38

• 新增 live 系列命令和完整实时项目工作流，可受控地创建与维护线上仪表板。
• 扩展指标图、进度图、迷你图、地图、气泡图、雷达图、箱线图、热力图等专项图表属性。
• 支持查询和引用 BI 环境中的系统图标，并增强输入校验、覆盖保护和任务诊断。

@guandata/guanvis 0.1.37

• 完善筛选器、页面布局和组合图配置，仪表板搭建更灵活。
• 增强字段绑定校验，减少图表配置错误。
• 优化图表属性和页面导出配置，提升生成结果的稳定性。

@guandata/guanvis 0.1.36

• 扩展仪表板标题、页面背景、筛选栏、卡片组、Tab 和分区的视觉配置，支持字体、颜色、图标、背景图、间距与分割线。
• 表格可配置主题、斑马纹、边框、表头和数据区样式；柱形图和条形图可调整柱宽、间距和圆角。
• 本地图片可随页面资源打包上传，检出已有页面后也能保留并继续编辑线上视觉配置。
• 增强已有页面覆盖发布前的备份与兼容判断，降低不同 BI 版本下的误覆盖风险。

@guandata/guanvis 0.1.35

• 补齐常用图表属性配置，支持背景、标题、图例、坐标轴、标签、辅助线、主题色和动态参数默认值等能力。
• 图表背景图支持引用本地图片，打包或发布时自动上传并转换为线上资源。
• 初始化或检出页面后会直接回显数据集字段清单，Agent 编写图表时更容易选对字段。
• 发布前会识别同名但 ID 不同的线上页面并阻止误建重复页面，已有页面更新更安全。
• 优化可视化构建文档结构，复杂图表和已有页面编辑说明更容易按需读取。

@guandata/guanvis 0.1.34

• 预览默认返回精简摘要，并把完整结果保存到工程目录，复杂仪表板的校验结论更容易查看；依赖旧版完整输出的脚本可使用 --full。
• 发布成功后可直接返回页面访问地址，并增强临时目录缺失场景的兼容性。
• 必填筛选器会保留不可清空设置，避免发布后出现无效的清空操作。
• 优化 Agent 发布流程和内置主题提示，减少重复操作与无效排查。

@guandata/guanvis 0.1.33

• 指标图表支持主次指标组和数字分组，可构建层次更清晰的指标展示。
• 增强页面发布前检查，可提前发现无效资源 ID、未挂载到页面的卡片和资源生成错误。
• 优化页面检出、指标初始化和全局参数读取效率，复杂页面编辑等待更少。
• 大型资源导入支持更灵活的等待时间，并能更快返回明确失败原因。

@guandata/guanvis 0.1.32

• 新增复杂报表 Pro 的创建、编辑、检视、反编译与发布完整链路。
• 支持页面另存为，并可将自定义图表脚本、样式和资源还原为可编辑工程。
• 支持全局参数和导出配置，增强线上页面 checkout、修改和无损回写的稳定性。
• 补全图表类型校验，提前阻止无法正常展示的卡片配置。
• 全局安装或升级后自动刷新 AI Skill，并随包提供完整使用说明和参考资料。

@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 install -g / npm link 全局安装时会通过 postinstall 自动执行一次 skill 安装/刷新；上述命令用于手动重装或排查。CI 等无需 skill 的环境可设 GUAN_SKIP_INSTALL_SKILL=1 跳过。

卸载

npm unlink -g @guandata/guanvis

支持平台

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

开发

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