GuanMCP 使用指南
产品概述
GuanMCP 是连接企业 AI 助手和观远 BI 查询能力的服务。
接入后，员工可以在飞书 Aily、观远 DecideX、企业自研 AI 助手等入口中，用自然语言查询 BI 数据、查看指标口径、读取看板和卡片信息，或发起 ChatBI 问数类查询。
例如：
员工在飞书 Aily 中问：" 昨天华东区销售额是多少？"
AI 助手会通过 GuanMCP 调用观远 BI 的查询能力。观远 BI 按这个员工自己的权限返回结果，AI 助手再把答案展示给员工。
员工不需要知道数据集 ID、卡片 ID，也不需要会写 SQL。AI 助手会根据问题选择并调用 GuanMCP 工具，GuanMCP 再执行对应的 BI 查询。
本文适合谁阅读
| 角色 | 你可以重点看什么 |
|---|---|
| 业务分析师 / 业务用户 | 适用范围、典型业务问题、常见问题，了解能问什么和结果是否可信。 |
| BI 管理员 | 权限与安全边界、接入准备，确认哪些资源开放给 AI 助手查询。 |
| IT / 平台管理员 | 常见接入入口，再继续阅读 GuanMCP 部署指南。 |
| AI 平台负责人 | 产品能力、与 GuanCLI 工具套件的区别，判断如何接入企业 AI 助手。 |
适用范围
典型业务问题
| 业务问题 | GuanMCP 可以让 AI 助手做什么 |
|---|---|
| " 这个指标是什么意思？" | 搜索指标，查看指标口径、负责人、可用维度和更新时间。 |
| " 昨天销售额是多少？" | 调用 ChatBI 或指标查询能力，返回当前用户有权限看到的数据。 |
| " 销售经营看板里用了哪些数据？" | 搜索页面和卡片，读取卡片配置、数据集来源和页面结构。 |
| " 这个数为什么下降？" | 调用指标归因或 ChatBI 问数类能力，基于查询结果分析变化原因。 |
| " 这个数据集有哪些字段？" | 查看数据集字段、字段类型、维度、度量和计算字段。 |
| " 我找不到某张报表。" | 在 BI 中搜索页面、卡片、数据集、ETL 等资源。 |
适用场景
- 企业已经有 AI 助手，希望员工在原有入口直接问 BI 数据。
- 业务人员不熟悉 BI 操作，但需要查指标、找看板、看洞察。
- 企业希望统一权限，员工在 AI 助手里能看到什么数据仍由 BI 控制。
- 需要把观远 BI 的只读查询、指标查询、ChatBI 问数类能力接入企业 AI 平台。
不适用场景
- 需要 AI 创建、修改、发布 BI 资源。请参考 GuanVis 使用指南 或 GuanCLI 使用指南。
- 需要 AI 修改 ETL。请参考 GuanETL 使用指南。
- 只是个人电脑上试用 BI 查询能力，还没有企业 AI 助手。建议先参考 GuanCLI 使用指南。
- 希望绕过 BI 权限直接让 AI 查看全部数据。GuanMCP 会按当前真实用户权限返回结果，不作为越权查询入口。
业务查询示例
业务用户提问：
帮我看一下本周华东区销售额为什么比上周下降。
AI 助手可能会通过 GuanMCP 完成这些动作：
- 搜索和「销售额」相关的指标或 ChatBI 主题。
- 确认当前用户有权限查看该指标或主题。
- 查询本周和上周华东区销售额。
- 按城市、门店、渠道或商品类目拆解变化。
- 汇总下降最明显的因素，并给出可追溯的数据来源。
用户看到的是一段业务解释；背后由 GuanMCP 负责调用观远 BI。
客户能得到什么
原入口问数
员工可以继续在飞书 Aily、DecideX 或企业自研 AI 助手里提问，不需要切换到 BI 界面寻找页面、卡片或数据集。AI 助手负责把自然语言问题转成合适的 BI 工具调用。
复用 BI 可信资产
GuanMCP 使用的是企业已经在观远 BI 中沉淀好的数据集、指标、指标树、仪表板、卡片和 ChatBI 主题。原来在 BI 中已经治理好的指标口径、权限边界和分析经验，可以继续被 AI 助手复用。
保持权限一致
同一个问题由不同员工提出时，GuanMCP 会按各自在 BI 中的权限返回结果。用户原本不能在 BI 中查看的数据，也不应该通过 AI 助手看到。
产品能力
与 GuanCLI 工具套件的区别
| 对比项 | GuanMCP | GuanCLI 工具套件 |
|---|---|---|
| 面向对象 | 企业 AI 助手和业务用户 | 本地 Agent、数据分析师、实施和开发人员 |
| 使用入口 | 飞书 Aily、DecideX、自研 AI 助手等 | 命令行或本地 Agent |
| 主要能力 | 让 AI 助手安全查询 BI 数据和指标 | 查询、分析、创建或修改 BI 资源 |
| 典型场景 | 员工在 AI 助手里问数 | Agent 在本地排查数据集、改卡片、改 ETL |
| 权限方式 | 每次请求识别真实用户，由 BI 判断权限 | 通常使用当前登录用户或本地配置用户 |
简单理解：GuanMCP 是给企业 AI 助手接入 BI 查询能力的；GuanCLI 工具套件是给本地 Agent 直接操作 BI 能力的。
支持的 BI 能力
| 内容 | 用户能问什么 |
|---|---|
| BI 能力探测 | 当前 BI 版本、运行模式、可用能力有哪些。 |
| 全局搜索 | 搜索卡片、仪表板、数据集、ETL 等 BI 资源。 |
| 数据集 | 查看字段结构、字段类型、维度、度量和计算字段。 |
| 页面和卡片 | 查看页面里有哪些卡片、卡片来自哪些数据集、图表配置是什么。 |
| 卡片数据 | 读取已保存卡片的只读数据结果。 |
| 轻量 SQL 查询 | 面向数据集执行只读查询。 |
| 指标平台 | 搜索指标、查看口径、查询指标数据。 |
| 指标树归因 | 查看指标树，做单维拆解或全维扫描。 |
| ChatBI | 列主题、问数和查看问数类结果。 |
GuanMCP 默认聚焦只读查询。它不创建、编辑、保存或发布 BI 资源。
接入说明
权限与安全边界
GuanMCP 不绕过观远 BI 权限。
- AI 助手能看到 GuanMCP 工具，不代表用户能看到所有 BI 数据。
- 每次查询都需要识别当前真实用户。
- 观远 BI 会根据该用户在 BI 中的权限返回数据。
- 正式接入时，不建议用一个固定账号代替所有员工查询。
- 用户在 AI 助手中能看到的数据，与其在观远 BI 中有权限查看的数据保持一致。
如果同一个问题由不同用户发起，返回结果可能不同。
建议先做小范围试点
正式面向全员开放前，建议先选择一个部门或一个业务主题做试点：
- 选择 3 到 5 个高频业务问题，例如销售额查询、门店排行、指标口径解释、异常原因分析。
- 选择对应的指标、页面、卡片、ChatBI 主题和数据集。
- 准备不同权限的测试账号，覆盖管理员、部门负责人、普通员工等角色。
- 在 AI 助手中逐一提问，核对答案是否能追溯到正确 BI 资源。
- 对比不同权限用户的返回结果，确认没有越权。
- 记录 AI 助手容易误解的问题，并补充指标说明、页面描述或业务知识。
接入准备
接入前建议先确认：
- 希望在哪个 AI 助手中使用，例如飞书 Aily、DecideX 或企业自研助手。
- 员工主要会问哪些问题，例如查指标、找看板、看数据集字段或做洞察。
- 哪些 BI 资源要开放给 AI 助手查询。
- 低权限用户、高权限用户分别应该看到什么数据。
- 是否需要先选一个部门或一个主题做试点。
- 是否已指定负责接入的管理员或运维同学。
接入完成后，建议用不同权限的测试账号分别提问，确认返回结果符合 BI 权限预期。
常见接入入口
| 文档或入口 | 适合对象 | 说明 |
|---|---|---|
| 飞书 Aily 对接 | Aily 管理员 | 在飞书 Aily 中配置自定义 MCP，让员工用自然语言查询观远 BI 数据。 |
| GuanMCP 部署指南 | 运维和平台管理员 | 部署 GuanMCP 服务，配置入口鉴权、用户身份传递、环境变量和 HTTP 验证。 |
| 观远 DecideX | 观远 AI 助手场景 | 员工在 DecideX 中调用观远 BI 的查询和指标查询能力。 |
| 企业自研 AI 助手 | 企业统一 AI 入口 | 企业将 GuanMCP 接入自研助手，让员工在统一入口访问 BI 查询能力。 |
常见问题
AI 助手能看到工具，但查不到数据
工具可见不等于用户有资源权限。请先确认该用户在观远 BI 中能否直接查看对应页面、卡片、数据集或指标。如果 BI 中也无法访问，需要由 BI 管理员补充权限。
SQL 查询报错
- 确认当前 BI 版本支持高级 SQL 功能。
- 确认数据集显示名称与 SQL 中使用的表名一致。
- 如果业务用户无法判断原因，请联系管理员查看对应查询限制和错误信息。
不同用户看到的结果不一致
GuanMCP 会按当前用户在观远 BI 中的权限返回数据。不同用户的数据权限、组织范围或行列权限不同，返回结果也可能不同。
飞书 Aily 中无法正常查询
请先确认 Aily 端已完成自定义 MCP 配置，并且当前用户的身份信息可以传递给观远 BI。具体配置可参考 对接飞书 Aily 使用指南。