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 会显示对应包名和重新安装方法。

dsl preview、dsl document 和 dsl diff 等纯本地命令由安装包内置的 DSL 引擎执行，不需要源码仓库。dsl init、dsl checkout、dsl plan、dsl apply 以及其他访问 BI 的命令会通过 guancli 或 guancli-lite 调用 BI API；客户环境必须将其中一个加入 PATH，或用 GUANCLI_PATH 指向其原生程序，并按对应 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 project edit <project_id> --name 经营分析指标 --dry-run
guanmetric directory create 广告分析 --project-id <project_id> --dry-run
guanmetric directory edit <project_id> <dir_id> --name 广告经营分析 --dry-run
guanmetric create --file atomic_metric.json --dry-run
guanmetric composite create --file composite_metric.json --dry-run
guanmetric derived create --file derived_metric.json --dry-run
guanmetric flow generate --file standard.xlsx --out metric_flow.json
guanmetric flow plan --file metric_flow.json
guanmetric flow apply --file metric_flow.json --state metric_flow.state.json --confirm
guanmetric flow verify --state metric_flow.state.json
guanmetric flow reconcile --file metric_flow.json --state metric_flow.state.json --key <flow_key> --metric-id <metric_id> --confirm
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、行、列、期望值和修正示例定位。

guanmetric flow generate 把用户确认后的标准 Excel 转换为版本化 Flow 计划，自动解析字段、责任人、业务属性、已有指标和批内依赖，并立即执行只读 plan 校验。flow apply 按 ${metric:key} 依赖稳定排序，创建后逐项回读；usable 模式还要求指标已发布、当前用户可用且数据查询冒烟成功。状态文件保存真实指标 ID，审批或故障后可继续执行，并避免重复创建。创建结果未知时，flow apply 不会重发创建；先用 flow reconcile 预览候选与原计划是否一致，确认后只把真实 ID 安全绑定回本地 state。

版本更新

@guandata/guanmetric 0.1.23

• 适配 BI 8.4 指标及公共维度协议。

@guandata/guanmetric 0.1.22

• 新增指标 DSL 创建与编辑流程，支持预览、文档生成、计划核对和应用。
• 支持检出已有指标、对比本地变更及按计划原地编辑。

@guandata/guanmetric 0.1.21

• 共享配置写入增加并发保护，避免覆盖并发更新的认证配置。
• 平台包发布校验兼容 npm 12。

@guandata/guanmetric 0.1.20

• 从源码目录运行但尚未构建时，启动器会提示先执行 npm run build。

@guandata/guanmetric 0.1.19

• 新增指标创建 Flow：从标准模板生成可审阅计划，按依赖创建、回读和验证；创建结果不确定时可核对已有资源并恢复进度。
• 创建和编辑原子、复合、衍生指标时使用明确的写入模型，保护已有取数字段；补齐指标主题、目录和指标树等资源的管理能力。

@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 输入契约、模板和消费示例，便于跨工具稳定传递指标定义。
• 对话式 Flow 只补 Web 创建页已有而后端缺失的校验，避免与服务端重复维护同一业务规则。

@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 处理。