guanmetric

观远 BI 指标写操作 CLI。

安装

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

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

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

常用命令

guanmetric template schema --type atomic
guanmetric template init --type atomic --out atomic_metrics.xlsx
guanmetric template normalize 客户指标.xlsx --check-only --output json-v1
guanmetric template normalize 客户指标.xlsx --out standard.xlsx --report report.json
guanmetric template explain-error report.json --json
guanmetric project-create 经营指标 --dry-run
guanmetric dir-create 广告分析 --project-id <project_id> --dry-run
guanmetric create --file atomic_metric.json --dry-run
guanmetric edit <metric_id> --file patch.json --dry-run
guanmetric delete <metric_id>
guanmetric public-dim create --file public_dim.json --dry-run
guanmetric business-dict list 销售 -f table
guanmetric business-dict get <business_dict_id>
guanmetric business-dict create --file business_dict.json --dry-run
guanmetric business-dict edit <business_dict_id> --set desc=新口径 --dry-run
guanmetric business-dict delete <business_dict_id>
guanmetric accelerate create <metric_id> --ds-id <dsId> --fd-id <fdId> --aggr-type SUM --filter-file filter.json --dry-run
guanmetric metric-tree create 销售额指标树 --metric-id <metric_id> --parent-dir-id <metric_tree_dir_id> --dry-run
guanmetric metric-tree update-config <metric_tree_id> --file metric_tree_config.json --dry-run

指标模板命令提供机器可读 schema、原子/复合指标最小模板和无副作用预检。--check-only 不写 Excel/report，也不创建或修改指标；失败结果通过稳定的 TEMPLATE_* 错误码以及 Sheet、行、列、期望值和修正示例定位。

版本更新

@guandata/guanmetric 0.1.18

• 安装时自动选择当前系统和架构的原生程序，减少下载量与磁盘占用，原有安装命令不变；离线安装也支持自动选包。

@guandata/guanmetric 0.1.17

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

@guandata/guanmetric 0.1.16

• 同步共享鉴权与环境识别更新，支持识别内部 OAuth2 应用认证环境。

@guandata/guanmetric 0.1.15

• 新增 batch online|offline 指标批量上下线，支持 --id 或 --file 输入并先 --dry-run 规划。
• 批量上线逐项读取草稿、原子指标执行 save-precheck、全部类型执行影响校验；冲突或下游影响默认标记 blocked，需 --confirm 才提交。
• 批量输出 schemaVersion: 1.0 机器契约，存在失败或阻断时非零退出；单项失败不回滚已成功项。

@guandata/guanmetric 0.1.14

• 统一指标 JSON 输入契约、模板和消费示例，便于跨工具稳定传递指标定义。
• 创建与编辑校验对齐服务端字段规则，非法组合会在提交前明确失败。

@guandata/guanmetric 0.1.13

• 复合指标公式会校验上游类型，阻止衍生指标、快捷引用指标和自身引用。
• 标准模板按真实类型补充原子或复合指标；涉及衍生结果时会提示改模并要求确认。
• 改善 Windows npm 全局安装场景下的 CLI 执行器定位。

@guandata/guanmetric 0.1.12

• 新增业务字典目录树及增删改查，支持业务属性筛选、dry-run 和删除影响确认。
• 指标模板新增机器 schema、最小模板、--check-only 预检和稳定单元格诊断。
• 规范指标与查询加速筛选条件，修复业务限定保存后无法回显并强化提交前校验。

@guandata/guanmetric 0.1.11

• 拼错二级子命令会明确报错并非零退出。
• 结构化错误可更准确地区分请求、认证和后端业务失败。

@guandata/guanmetric 0.1.10

• 支持企业 OIDC 认证上下文，并升级底层请求兼容能力，改善受控环境中的指标管理稳定性。

@guandata/guanmetric 0.1.9

• 改进 Skill 自动安装反馈和删除确认流程。
• 优化 Windows 环境下的 CLI 启动兼容性。

@guandata/guanmetric 0.1.8

• 查询加速创建和编辑支持配置筛选条件，可通过完整请求体、--filter-json 或 --filter-file 传入。

@guandata/guanmetric 0.1.7

• 新增指标查询加速管理能力。
• 增强指标、目录、公共维度和指标树变更后的校验与回读。
• 写操作会提前检查目标目录和配置，减少无效变更。

@guandata/guanmetric 0.1.6

• 更新底层依赖，提升指标管理和模板处理的安全性与运行稳定性。

@guandata/guanmetric 0.1.5

• 新增指标树创建、查看、改名、移动和配置更新能力，支持维度拆解、指标公式拆解及复合指标展开。
• 指标树写入支持预览计划和原地更新，减少配置错误及删除重建造成的引用失效。

@guandata/guanmetric 0.1.4

• 适配受控 Agent 运行环境，指标创建、编辑和模板处理可在嵌入式执行场景复用，现有 CLI 用法保持不变。

@guandata/guanmetric 0.1.3

• 完善已有指标资源的原地编辑指引，避免更新时误建新资源并影响既有引用。
• 优化多资源读取效率，Agent 批量准备和校验指标配置时等待更少。

@guandata/guanmetric 0.1.2

• 全局安装或升级后自动刷新 AI Skill，减少 CLI 与 Agent 使用说明版本不一致的情况。
• 随包提供完整的指标管理说明和参考资料。

@guandata/guanmetric 0.1.1

• 增强指标 Excel 标准化能力，支持按原子、复合和多类衍生指标拆分标准模板。
• 新增汇总 sheet，便于用户总览待创建指标、行状态和问题说明。
• 优化批量创建前的校验和下一步提示，帮助 Agent 引导用户补齐缺失信息后再创建指标。

@guandata/guanmetric 0.1.0

• 新增指标写操作 CLI，承接指标创建、编辑、删除、指标主题、指标目录和公共维度管理能力。
• 新增指标 Excel 标准化能力，可把客户指标清单整理为标准模板并输出校验报告。
• 指标写操作独立为 guanmetric 组件，指标查询和数据读取仍由 guancli 处理。