GuanMetric 使用指南
产品概述
GuanMetric 是什么
GuanMetric 是观远 BI 指标平台的写操作工具，用于创建和维护指标主题、指标目录、原子指标、复合指标、衍生指标、公共维度和指标树。它与 GuanCLI 共用认证配置。
- GuanCLI 负责指标搜索、详情查询、数据查询和归因查询；
- GuanMetric 负责指标平台资源的创建和修改。
配合 AI Agent 使用时，先让 Agent 查询资源、生成创建或修改计划，再进行 dry-run、校验、提交和回读。
例如，可以这样描述需求：
请在“经营指标”主题下创建“销售额”和“订单数”两个原子指标，再创建“客单价 = 销售额 / 订单数”。
先查询数据集、字段和已有指标，生成计划和 dry-run 结果；未经确认不要创建或发布。
指标会被复合指标、衍生指标、卡片和指标树引用。编辑时应原地修改，避免删除重建导致 ID 变化和下游引用断裂。
目前产品处于公测阶段，可以免费使用所有功能，公测后需要获得商业授权才能继续使用，如仍需体验请联系观远数据商务人员或客户成功经理（通常是贵公司当前的服务交流负责人）。
适用场景
优先使用 GuanMetric 处理以下任务：
- 标准化指标模板：将客户指标 Excel/CSV 整理为观远指标平台可识别的标准模板。
- 整理指标需求：根据文字、半结构化表格或截图转写内容整理指标需求，并生成标准模板供用户确认。
- 创建指标主题和目录：创建指标主题和普通指标目录。
- 创建和编辑原子指标：基于数据集字段求和、计数、去重计数、平均、最大、最小或表达式聚合。
- 创建和编辑复合指标：例如销售额 / 订单数、A + B - C 等已有指标间公式。
- 创建和编辑衍生指标：例如同比/环比、最近 N、累计、期末值、业务限定和组合衍生。
- 删除指标：删除前执行 Web 同款影响校验，并在无下游依赖时按确认流程删除。
- 管理公共维度：查询、详情、字段占用映射、新建、编辑、转移责任人和删除。
- 创建和配置指标树：配置维度拆解、指标拆解、时间对比、贡献计算，并支持原地改名、移动和更新配置。
- 受控透传调用：对尚未封装为专用命令的复合指标、衍生指标接口使用受控
fetch。
常见指标管理任务
| 业务需求 | 使用 GuanMetric |
|---|---|
| 我要把业务指标 Excel 导入指标中心 | 指标模板标准化 |
| 我要创建销售额指标 | 创建原子指标 |
| 我要创建客单价 | 创建复合指标 |
| 我要创建销售额同比 | 创建衍生指标 |
| 我要调整指标口径 | 编辑指标 |
| 我要搭建经营分析指标体系 | 指标树 |
| 我要统一日期、组织等维度 | 公共维度 |
使用边界
GuanMetric 不适合承担以下工作：
| 需求 | 推荐工具 | 说明 |
|---|---|---|
| 搜索指标、读取指标详情、查询指标数据、查询指标归因结果 | guancli | 偏指标只读分析 |
| 读取数据集详情、字段 ID 和数据集预览 | guancli ds | 偏数据集只读 |
| 创建或修改数据集 | guands | 偏数据源和数据集管理 |
| 创建 ETL | guanetl | 偏数据加工流程 |
| 创建指标卡片或仪表板 | guanvis | 偏可视化产物 |
| 修改已有指标主题或普通指标目录名称 | BI 网页端 | 当前 CLI 只支持创建；不支持时不要通过新建同名主题/目录模拟改名 |
| 用删除重建方式替代指标、公共维度或指标树的编辑 | - | 会导致 ID 变化和下游引用断裂 |
高风险操作
以下操作会影响线上指标体系或下游引用，执行前必须确认目标环境、资源 ID、影响范围和用户授权：
- 创建并上线指标，即
publish=true。 - 编辑已有指标的公式、来源字段、适用维度、时间维度、业务限定或发布状态。
guanmetric delete <metricId>：删除指标。guanmetric public-dim delete <publicDimId>：删除公共维度。- 修改公共维度关联字段。
- 更新指标树配置、移动指标树或重命名指标树。
- 通过
fetch调用指标平台写接口。
dry-run、保存前校验、影响校验或依赖检查通过，不等于线上已经写入成功。只有真实提交成功并回读确认后，才能报告“已创建”“已编辑”或“已删除”。
前提条件
安装 GuanMetric 前，请确认电脑已安装 Node.js、npm 和 GuanCLI，并已完成 guancli auth login。安装和登录方式请参考 GuanCLI 使用指南。
安装 GuanMetric
方式一：通过 npm 命令全局安装
# 首次安装
npm install -g @guandata/guanmetric
# 验证安装
guanmetric version
# 让 AI Agent 识别 GuanMetric
guanmetric install-skill
升级时执行：
npm install -g @guandata/guanmetric@latest
guanmetric install-skill
guanmetric install-skill 会安装 GuanMetric 的工具说明，不替代 GuanCLI 登录。若已成功安装但找不到命令，检查 npm 全局目录：
npm prefix -g
方式二：通过 Agent 辅助安装
将以下内容发送给 AI Agent：
请检查当前电脑是否已安装 Node.js、GuanCLI 和 GuanMetric。
如果 GuanMetric 未安装，请执行 npm install -g @guandata/guanmetric，确认 guanmetric version 可以正常执行，
再执行 guanmetric install-skill。不要修改 BI 中的任何指标。
登录 BI 环境
GuanMetric 使用 GuanCLI 的认证配置。详细配置可参考 登录 GuanCLI。
写操作前先确认当前环境和账号：
guancli auth status
guancli auth list
主题、目录、数据集、字段、指标、公共维度和指标树的 ID 必须来自当前环境。名称可能重复，不能直接猜测 ID。
使用 GuanMetric 管理指标
建议按“查询 → 计划 → 预览与校验 → 确认 → 写入 → 回读”的顺序工作。首次试用请选择测试主题或目录。
下面每个步骤提供两种操作方式：
- AI Agent 调用示例：适合希望通过自然语言完成操作的用户；
- CLI 命令参考：适合技术用户直接调用 GuanMetric。
第一步：查询主题、指标和数据集
给 Agent 的指令：
请确认当前环境，并搜索“销售额”相关的指标、指标主题和数据集。
列出候选资源的名称、ID、数据集和字段；只查询，不要创建或修改。
对应的常用查询命令：
guancli auth status
guancli metric project 经营 -f json
guancli metric tree -f json
guancli metric search 销售额 -f json
guancli metric get <metricId> --brief
guancli ds get <dsId> --brief
第二步：确认指标类型和创建计划
给 Agent 的指令：
我已经确认环境。请根据以下需求判断每个指标应该建模为原子指标、复合指标还是衍生指标，并输出创建计划：
1. 销售额：对订单表.amount 字段求和。
2. 订单数：对订单表.order_id 去重计数。
3. 客单价：销售额 / 订单数。
计划需包含：主题、目录、指标名称与类型、数据集与字段、聚合方式或公式、适用维度、时间维度、责任人、保存方式（草稿/上线），以及创建顺序。未确认计划前不要生成最终提交文件。
先确认指标的建模方式：
| 需求 | 推荐类型 |
|---|---|
| 基于一个字段求和、计数、去重计数、平均、最大或最小 | 原子指标 |
| 已有指标之间做四则运算 | 复合指标 |
| 同比、环比、最近 N、累计、期末值或业务限定 | 衍生指标 |
| 多个衍生指标再组合计算 | 组合衍生 |
计划至少应包含目标环境、主题和目录、指标名称与类型、核心口径、数据集与字段、适用维度和时间维度、责任人、草稿或发布状态，以及依赖顺序。未确认计划前，不应提交真实写操作。
业务示例表：
| 业务指标 | 类型 | 说明 |
|---|---|---|
| 销售额 | 原子指标 | 订单金额 SUM |
| 订单数 | 原子指标 | 订单 ID 去重计数 |
| 客单价 | 复合指标 | 销售额 / 订单数 |
| 销售额同比增长率 | 衍生指标 | 基于销售额计算同比 |
| 近 30 天销售额 | 衍生指标 | 时间窗口计算 |
第三步：创建或编辑原子指标
给 Agent 的指令：
计划已确认。请在“经营指标/核心指标”目录下创建原子指标“销售额”。
基于数据集 <dsId> 的字段 <fdId>，聚合方式为 SUM。
先执行 dry-run 并展示请求体，我确认后再创建。创建后回读指标详情验收。
如果需要编辑，请使用 guanmetric edit <metricId> 原地修改，不要删除重建。
原子指标基于单个数据集字段或字段表达式定义。常见聚合方式包括 SUM、CNT、CNT_DISTINCT、AVG、MAX 和 MIN。
对应的常用命令：
# 预览创建请求
guanmetric create --file atomic_metric.json --dry-run
# 确认后创建
guanmetric create --file atomic_metric.json -f json
# 回读验收
guancli metric get <metricId> --brief
# 原地编辑已有指标
guanmetric edit <metricId> --set name=销售额 --set desc=核心口径 --dry-run
guanmetric edit <metricId> --file atomic_metric_update.json -f json
发布指标时，命令会执行保存前校验。编辑已有指标还会根据变化执行影响校验；发现口径冲突或下游影响时，应先展示结果并取得确认。
第四步：创建复合和衍生指标
给 Agent 的指令：
原子指标已创建完成。请基于以下信息创建复合指标“客单价 = 销售额 / 订单数”：
- 销售额 metricId：<metric_sales_amount>
- 订单数 metricId：<metric_order_count>
公式中必须使用 [metricId] 而不是中文名称。先展示中文公式和 ID 公式供我确认，再执行 dry-run/校验，最后创建并回读。
复合指标由已有指标组成，例如“客单价 = 销售额 / 订单数”。提交公式必须使用指标 ID，而不是中文名称：
人读公式：销售额 / 订单数
提交公式：[metric_sales_amount] / [metric_order_count]
对应的常用命令：
# 复合指标创建
guanmetric fetch POST /api/metric-platform/metrics/composite-metrics --file composite_metric.json
# 衍生指标创建
guanmetric fetch POST /api/metric-platform/metrics/derived-metrics --file derived_metric.json
# 创建后回读
guancli metric get <newMetricId> --brief
同比、环比和期末值要求基础指标具有时间维度；最近 N 只能衍生自原子指标；业务限定必须带 filter。复合指标的适用维度只能从引用指标的共有维度中选择。
第五步：批量标准化指标模板
给 Agent 的指令：
我上传了一份客户指标清单“客户指标.xlsx”，请先用 guanmetric template normalize 标准化为固定模板。
输出标准 Excel 和报告后，展示“汇总”Sheet 中的行状态统计：可创建、待确认、错误分别有多少行。
对于“待确认”和“错误”行，列出问题说明和需要我补充的信息。所有行都变为“可创建”且我确认模板后，再进入创建计划。
不要直接创建任何指标。
当用户提供 Excel、CSV、表格或文字需求并希望批量创建指标时，先标准化模板，而不是直接创建：
guanmetric template normalize 客户指标.xlsx \
--out standard_metrics.xlsx \
--report standard_metrics_report.json
标准文件会按原子、复合和不同衍生类型拆分 Sheet，并在“汇总”中标记行状态：
| 行状态 | 下一步 |
|---|---|
| 可创建 | 用户确认后进入创建计划 |
| 待确认 | 补充或确认候选信息 |
| 错误 | 修正必填项、ID 或公式映射后重新标准化 |
只有真实指标行均为“可创建”且用户确认模板后，才能执行创建。Agent 应先把中文字段名和指标名映射为 ID，再生成最终 payload。
第六步：管理公共维度和指标树
指标树与指标目录区别
- 指标目录：用于管理指标存放位置。
- 指标树：用于描述指标之间的分析关系。
例如：
销售额
├── 区域拆解
├── 品类拆解
└── 渠道拆解
给 Agent 的指令：
请帮我创建/编辑以下资源，所有写操作前先执行 dry-run：
1. 公共维度“日期”，基于数据集 <dsId> 的日期字段 <fdId>。
2. 指标树“销售额指标树”，根指标为 <metricId>，挂在指标树目录 <metricTreeDirId> 下。
请确认根指标有时间维度，指标树目录 ID 来自 guancli metric_attribution tree，而不是普通指标目录。
对应的常用命令：
# 公共维度
guanmetric public-dim list 日期
guanmetric public-dim fd-map <dsId>
guanmetric public-dim create --file public_dim.json --dry-run
guanmetric public-dim edit <publicDimId> --file public_dim_patch.json --dry-run
# 指标树
guancli metric_attribution tree -f json
guanmetric metric-tree create 销售额指标树 --metric-id <metricId> --parent-dir-id <metricTreeDirId> --dry-run
guanmetric metric-tree update-config <metricTreeId> --file metric_tree_config.json --dry-run
guanmetric metric-tree get <metricTreeId>
公共维度删除前需检查依赖。指标树必须使用 guancli metric_attribution tree 返回的指标树目录 ID，不能使用普通指标目录 ID；根指标必须具备时间维度。
第七步：删除前检查和回读
给 Agent 的指令：
请检查指标 <metricId> 是否可以删除。执行影响校验后，展示下游引用情况。
如果存在下游指标或卡片，先列出清单并让我决定如何处理。只有当 deletable=true 且我明确确认后，才追加 --confirm 执行删除。
删除后，通过搜索或 get 命令回读确认。
删除指标默认先检查影响：
guanmetric delete <metricId>
仅当结果显示可删除、下游引用已处理且用户明确确认后，才执行：
guanmetric delete <metricId> --confirm
写操作完成后必须回读。除指标详情外，公共维度使用 guanmetric public-dim get <publicDimId>，指标树使用 guanmetric metric-tree get <metricTreeId> 验收。
使用建议
- 先查询再写入；主题、目录、数据集、字段和指标都可能重名。
- 所有创建和编辑先生成计划并执行
--dry-run、保存前校验或影响校验。 - 原子指标使用数据集字段引用
[fdId]；复合和组合衍生使用指标引用[metricId]。 - 不要用删除重建模拟编辑。指标 ID 变化会导致卡片、指标树和下游指标引用断裂。
- 公共维度删除、指标删除、指标树配置更新和通过
fetch调用未封装写接口属于高风险操作，须先确认影响范围。 - 常规原子指标、主题、目录、公共维度和指标树优先使用专用命令；
fetch仅用于未封装的复合、衍生或校验接口。
常见问题排查
问题一：找不到主题、目录、指标或数据集
确认环境后按资源类型搜索：
guancli auth status
guancli metric project <关键词> -f json
guancli metric tree -f json
guancli metric search <关键词> -f json
guancli ds search <关键词>
存在多个候选时，请指定 ID。
问题二：标准模板出现“待确认”或“错误”
不要直接创建。检查“汇总”中的问题说明，补齐主题、目录、数据集、字段、基础指标或公式映射后重新执行 template normalize。
问题三：复合公式无法解析
确认公式中的每个 token 均能映射到已有指标、数据集字段或本批已定义的基础指标。不要猜测中文名称或裸 token 对应的资源。
问题四：编辑或删除被下游影响阻断
先展示受影响的指标或卡片并处理引用关系。未获得确认前，不要追加 --confirm；有下游引用时不要强行删除。
问题五：AI 没有自动使用 GuanMetric
在需求中明确说明：
请使用 GuanMetric 管理这些指标。先查询资源并生成计划，执行 dry-run 和影响校验；没有我的确认不要创建、发布、编辑或删除。
并确认已执行：
guanmetric install-skill
问题六：我不知道指标类型怎么办？
可以让 Agent 根据业务需求判断原子、复合或衍生指标，但需要确认业务口径。