GuanCLI 工具套件概述
概述
本章介绍观远 BI 的命令行工具套件，包括 GuanCLI、GuanVis 和 GuanETL。三者都面向 AI Agent 和命令行环境，但解决的问题不同。
- GuanCLI 是观远 BI 的通用命令行工具。它负责连接 BI 环境、管理登录认证、查询数据集/页面/卡片/ETL 等资源，并支持数据预览、任务排查、表单操作和 ChatBI 调用。
- GuanVis 是可视化资源生成工具。它基于 GuanCLI 的登录和查询能力，让 AI 根据自然语言需求读取数据集结构，自动生成并发布 BI 仪表板。
- GuanETL 是 ETL 开发调试工具。它基于 GuanCLI 的登录和查询能力，让 AI 打开、新建、修改、检查、预览、保存、运行和调度 ETL 流程。
简单来说，GuanCLI 负责“连接和查询 BI”，GuanVis 负责“生成看板”，GuanETL 负责“开发和调试 ETL”。
适合哪些人使用
| 使用者 | 典型任务 |
|---|---|
| 数据分析师 | 快速查找数据集、查看字段口径、预览数据、定位页面和卡片来源。 |
| IT / 运维人员 | 检查登录环境、排查任务失败、确认 ETL 运行状态、辅助定位权限问题。 |
| BI 开发人员 | 让 AI 读取数据集结构、生成看板初稿、修改 ETL 草稿、验证结果后再保存。 |
| 企业 AI Agent | 在受控环境中调用 BI 能力，完成查询、分析、排查和资源生成任务。 |
如果一线业务人员只是希望在企业 AI 助手中直接问数，通常不需要直接安装命令行工具，可以优先阅读 GuanMCP 使用指南。
三者的关系
GuanCLI 是底座，GuanVis 和 GuanETL 都依赖 GuanCLI。
┌─────────────────────────────────────────────────────────────┐
│ GuanCLI（底座） │
│ • 连接观远 BI 环境 │
│ • 管理登录、Token 和多环境配置 │
│ • 查询数据集、页面、卡片、ETL、任务等元信息 │
└───────────────────────┬─────────────────────────────────────┘
│ 依赖 GuanCLI 的认证与查询能力
┌───────────────┴───────────────┐
▼ ▼
┌───────────────┐ ┌───────────────────┐
│ GuanVis │ │ GuanETL │
│ 自动生成 │ │ ETL 开发调试 │
│ 仪表板初稿 │ │ 保存、运行、调度 │
└───────────────┘ └───────────────────┘
使用 GuanVis 或 GuanETL 前，必须先安装并登录 GuanCLI。GuanVis 和 GuanETL 本身不单独管理 BI 认证信息，而是复用 GuanCLI 的登录状态。
什么时候用哪个工具
| 需求 | 推荐工具 | 说明 |
|---|---|---|
| 安装登录、切换 BI 环境、查看当前账号 | GuanCLI | GuanCLI 负责认证和环境配置，是使用其他工具的前提 |
| 查询数据集、页面、卡片、ETL、任务等 BI 资源 | GuanCLI | 适合资源搜索、数据预览、问题排查和 ChatBI 调用 |
| 用自然语言生成 BI 仪表板初稿 | GuanVis | 适合基于数据集快速生成页面、图表和筛选器 |
| 新建、修改、检查或保存 ETL 流程 | GuanETL | 适合数据清洗、字段加工、流程调试和输出验证 |
| 运行 ETL 或配置 ETL 调度 | GuanETL | 适合保存后运行任务、等待结果或设置定时调度 |
使用前先确认
开始使用前，建议先完成以下确认：
- 当前电脑已安装 Node.js 和 npm。
- 已安装 GuanCLI，并完成
guancli auth login。 - 当前登录环境是预期的 BI 环境，账号权限足以访问目标资源。
- 如果要让 AI 自动调用工具，还需要独立安装 GuanVis、GuanETL 等工具，并执行对应工具的
install-skill命令。 - 涉及生成、保存、发布、调度或删除资源时，优先使用测试环境、测试目录或个人目录。
GuanVis 和 GuanETL 可以创建或修改 BI 资源。生产环境中使用前，请先让 AI 说明目标资源、影响范围和即将执行的操作，确认后再保存、发布或运行。
和 GuanMCP 的区别
本章介绍的是命令行工具套件，适合在本地电脑、交付环境或 AI Agent 可执行命令的环境中使用。
GuanMCP 面向企业 AI 助手或 AI 平台接入场景。它把观远 BI 的查询、指标、元信息和 ChatBI 能力封装为 MCP 工具，让业务人员可以在飞书 Aily、企业自研 AI 助手等入口中查询 BI 数据。
如果任务需要 AI 在本地或受控环境中查询、排查、生成看板或修改 ETL，优先使用 GuanCLI 工具套件。如果任务是让已有 AI 助手直接接入 BI 问数，优先了解 GuanMCP。
推荐阅读顺序
如果你是第一次使用，建议按以下顺序阅读：
- [[1-GuanCLI 使用指南|GuanCLI 使用指南]]：先安装、登录并熟悉 GuanCLI。
- [[2-GuanVis 使用指南|GuanVis 使用指南]]：在 GuanCLI 可用后，用自然语言生成仪表板。
- [[3-GuanETL 使用指南|GuanETL 使用指南]]：在 GuanCLI 可用后，用自然语言开发或调试 ETL。
如果你还不确定应该选 GuanCLI 还是 GuanMCP，可以先阅读 [[../0-GuanCLI 与 GuanMCP 对比|GuanCLI 与 GuanMCP 对比]]。