GuanVis 使用指南
GuanVis 是什么
GuanVis 是观远 BI 可视化资源生成工具。配合 AI Agent 使用时，用户可以用自然语言描述想要的仪表板，例如“基于销售订单数据生成一个销售经营分析看板”，AI 会自动读取数据集结构、设计图表、生成筛选器和页面，并发布到指定 BI 目录。
GuanVis 适合用于快速生成经营分析看板、销售分析看板、客户分析看板、商品分析看板等 BI 页面，也适合在售前、实施、客户试用和内部验证阶段快速搭建看板初稿。
使用 GuanVis 时，建议先在测试环境、演示环境或个人测试目录中生成和验证结果。涉及正式客户环境、生产目录或重要线上看板时，请先确认指标口径、页面内容和发布目录，再发布到正式目录。
前提条件
安装 GuanVis 前，请确认电脑已安装 Node.js 和 npm：
node -v
npm -v
如果提示找不到命令，请先前往 Node.js 官网下载并安装 LTS 版本。安装完成后，重新打开终端再执行检查。
GuanVis 发布仪表板时会复用 GuanCLI 的 BI 登录状态。因此，如需查询数据集、查找页面目录或发布到 BI，还需要先安装并登录 GuanCLI。
安装 GuanVis
方式一：通过 npm 命令全局安装
-
安装 GuanVis
npm install -g @guandata/guanvis已安装过的用户，可以执行更新：
npm update -g @guandata/guanvis -
安装完成后验证
guanvis version终端显示版本号即表示安装成功。
说明如果安装成功但执行
guanvis version提示找不到命令，通常是 npm 全局命令目录未加入系统PATH。可执行以下命令查看全局目录，将对应目录加入PATH后重新打开终端。npm prefix -g -
安装 Skill
guanvis install-skill安装完成后，即可在 Codex、Cursor、Claude Code 等 AI 工具中用自然语言提出看板生成需求，例如：
请基于“销售订单明细”数据集生成一个销售经营分析看板，先发布到测试目录。
方式二：通过 Agent 辅助安装
直接把下面的需求发给 AI Agent，让 Agent 协助检查环境、安装工具并验证命令是否可用：
帮我安装 GuanVis，并确认 guanvis version 可以正常执行。
安装完成后，请帮我执行 guanvis install-skill。
登录 BI 环境
GuanVis 使用 GuanCLI 的认证配置。只要 guancli auth login 登录成功，GuanVis 后续查询数据集、发布页面时会自动复用当前认证信息。
在终端输入：
guancli auth login
按提示依次输入 BI 系统地址、登录方式和账号信息。
登录成功后，可以查看当前登录状态：
guancli auth status
如果你有多个 BI 环境，可以查看和切换环境：
guancli auth list
guancli auth use <profile>
生成或发布仪表板前，建议先确认当前环境是否正确。也可以直接让 AI 帮你检查：
请先检查当前 GuanCLI 登录环境，确认是否在 demo 环境。
使用 GuanVis 生成仪表板
用户通常不需要手动执行每一条 GuanVis 命令。更推荐的方式是在 AI Agent 中直接描述业务需求，让 AI 完成数据集查询、看板设计、生成、校验和发布。
第一步：让 AI 理解数据集
可以先让 AI 查看数据集结构，并判断适合做什么分析：
请查看“销售订单明细”这个数据集，说明它适合做哪些业务分析。
AI 通常会返回这个数据集包含哪些日期字段、金额字段、数量字段、区域字段、商品字段、客户字段，以及适合生成哪些指标和图表。
第二步：提出看板生成需求
确认数据集适合后，可以提出完整生成需求：
请基于“销售订单明细”数据集生成一个销售经营分析看板。
目标用户是销售负责人，重点查看本月销售额、订单数、区域贡献、商品排行和客户结构。
销售额口径是 quantity * unit_price。
需要日期、区域、品类、订单状态筛选。
整体风格清晰克制，适合业务人员日常查看。
请先发布到测试目录。
生成后告诉我页面名称、页面 ID、主要图表，以及需要人工确认的指标口径。
第三步：查看和反馈
生成完成后，请进入 BI 目标目录查看页面。重点检查：
- 指标口径是否正确。
- 字段选择是否符合业务含义。
- 图表类型是否合适。
- 筛选器是否覆盖常用分析维度。
- 页面是否发布到正确环境和目录。
- 页面布局和视觉风格是否适合使用场景。
如果结果不符合预期，可以直接告诉 AI 具体修改点：
区域销售贡献图改成按省份展示。
客户结构图改成按客户等级展示销售额占比。
订单明细表里增加订单状态和支付方式。
默认建议让 AI 发布为新版本，不直接覆盖原页面，便于对比和回滚。
使用建议
- 先说清楚业务目标，不要只说“做个看板”。
- 优先选择字段含义清楚的数据集，例如订单、销售、客户、商品、门店、库存等明细数据。
- 明确核心指标和计算口径，例如销售额、订单数、客户数、利润率等。
- 明确需要哪些筛选条件，例如日期、区域、品类、门店、客户等级、订单状态等。
- 首次试用建议发布到测试目录或个人目录。
- 生成后一定要人工检查，尤其是核心指标口径和页面内容。
- 对外交付前，请业务或项目负责人确认页面内容。
- 如果后续还要维护这张看板，建议保留本次需求描述和生成结果，便于继续迭代。
常见问题排查
问题一：安装后提示找不到 guanvis 命令
先确认安装成功：
npm list -g @guandata/guanvis
再检查 npm 全局命令目录是否在 PATH 中：
npm prefix -g
Windows 全局命令通常位于 %AppData%\npm，macOS/Linux 通常位于 $(npm prefix -g)/bin。加入 PATH 后，请重新打开终端。
问题二：AI 没有自动使用 GuanVis
可以在问题中明确写：
请使用 GuanVis 生成仪表板。
或：
请按 GuanVis 的方式，先读取数据集结构，再生成并发布看板。
如果仍然没有自动调用，请确认已经执行：
guanvis install-skill
问题三：提示未登录或认证失败
先查看 GuanCLI 登录状态：
guancli auth status
如果未登录或登录已失效，请重新登录：
guancli auth login
如果有多个环境，请确认当前 profile 是否正确：
guancli auth list
guancli auth use <profile>
问题四：AI 找不到数据集
可能原因包括：
- 当前 BI 环境不对。
- 数据集名称不完整。
- 数据集在另一个目录或另一个环境。
- 当前用户没有权限。
可以让 AI 先搜索候选数据集：
请先确认当前 GuanCLI 登录环境，并搜索包含“销售”的数据集。
如果仍然找不到，请确认数据集名称、目录位置和账号权限。
问题五：生成结果字段或指标不对
直接告诉 AI 正确字段或口径，例如：
销售额不是 unit_price，应该用 quantity * unit_price。
客户数应该按 customer_id 去重计数。
订单数应该按 order_id 去重计数。
涉及财务、利润、客户数、订单数等核心指标时，建议由业务或数据负责人确认口径。
问题六：调整看板会不会覆盖原来的页面
默认建议不要覆盖。
调整已发布或正在使用的仪表板时，建议让 AI 发布为新版本，保留旧版本用于对比和回滚。你可以这样表达：
请基于刚才生成的销售经营看板继续调整，并发布为新版本，不要覆盖原页面。
如果确实需要覆盖原仪表板，请明确说明：
我确认要覆盖原仪表板，请复用原页面和卡片 ID 发布。
覆盖会影响同 ID 的线上资源，建议只在测试目录或确认无风险时使用。