@guandata/guanmetric 0.1.12 → 0.1.14

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## @guandata/guanmetric 0.1.14 - 2026-09-09
+
+- 统一指标 JSON 输入契约、标准模板和消费示例，指标定义可更稳定地在工具间传递。
+- 指标创建与编辑的类型、字段校验对齐服务端契约，非法组合会在提交前明确失败。
+
+## @guandata/guanmetric 0.1.13 - 2026-09-03
+
+- 复合指标创建和编辑会校验公式上游类型，只允许原子指标或复合指标，阻止衍生指标、快捷引用指标和自身引用进入公式。
+- 标准模板会按引用对象的真实类型补充原子或复合指标，不再把缺失引用一律补成原子指标；涉及衍生语义时提示改模并要求确认。
+- 改进 Windows npm 全局安装环境下的 CLI 执行器定位。
+
 ## @guandata/guanmetric 0.1.12 - 2026-09-01
 
 - 新增业务字典目录树、查询、新建、原地编辑和删除能力，支持业务属性筛选、dry-run 和关联指标影响确认。

package/README.md

@@ -38,6 +38,17 @@ guanmetric metric-tree update-config <metric_tree_id> --file metric_tree_config.
 
 ## 版本更新
 
+### @guandata/guanmetric 0.1.14
+
+- 统一指标 JSON 输入契约、模板和消费示例，便于跨工具稳定传递指标定义。
+- 创建与编辑校验对齐服务端字段规则，非法组合会在提交前明确失败。
+
+### @guandata/guanmetric 0.1.13
+
+- 复合指标公式会校验上游类型，阻止衍生指标、快捷引用指标和自身引用。
+- 标准模板按真实类型补充原子或复合指标；涉及衍生结果时会提示改模并要求确认。
+- 改善 Windows npm 全局安装场景下的 CLI 执行器定位。
+
 ### @guandata/guanmetric 0.1.12
 
 - 新增业务字典目录树及增删改查，支持业务属性筛选、dry-run 和删除影响确认。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guandata/guanmetric",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "description": "观远 BI 指标写操作工具 - 指标创建编辑删除、指标目录、公共维度、Excel 标准化",
   "bin": {
     "guanmetric": "bin/run.js"
@@ -37,6 +37,7 @@
     "node": ">=14"
   },
   "publishConfig": {
-    "registry": "https://registry.npmjs.org/"
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
   }
 }

package/skills/guanmetric/SKILL.md

@@ -57,7 +57,7 @@ guanmetric fetch POST /api/metric-platform/metrics/composite-metrics --file comp
 
 标准 Excel 第一张固定为 `汇总` sheet，用于给用户总览本次待创建指标总数、按类型计数、指标名称、指标类型、所在模板、关键来源、行状态和问题说明；创建 payload 仍以各指标类型模板 sheet 为事实源，不从 `汇总` sheet 创建。
 
-生成复合指标模板时，如果 `计算公式` 引用的 `[指标名]` 不在原子指标模板中，agent 必须补充同名原子指标行，保证创建时先有基础原子指标，再创建复合指标。
+生成复合指标模板时，`计算公式` 的每个引用都必须解析为已上线或本批先创建的原子指标/复合指标。复合指标不能引用衍生指标或快捷引用指标；如果引用对象不在模板中，先判断它应建为原子指标还是复合指标并补充对应行，不要一律补成原子指标。若业务公式确实要组合最近 N、累计、期末值等衍生结果，按 `metric-derived-mutation.md` 评估组合衍生，并向用户说明改模后的业务语义。
 
 生成衍生指标模板时，如果 `衍生自` 指标不是已明确存在的线上指标，而是本批也要创建的指标，必须在标准模板中补充对应的原子指标或复合指标行；信息不足时先补行并在该基础指标行的 `问题说明` 中列出缺失的数据集、来源字段、聚合方式、计算公式、适用维度等。不要等到创建计划阶段才临时新增基础指标。
 

package/skills/guanmetric/references/metric-atomic-mutation.md

@@ -189,7 +189,7 @@ guancli metric get <metric_id> --brief
 1. 读取当前详情：
 
 ```bash
-guancli metric get <metric_id> -f json
+guancli metric get <metric_id> --raw
 ```
 
 2. 生成 patch 或完整 payload，先 dry-run：
@@ -223,3 +223,5 @@ guanmetric fetch POST /api/metric-platform/metrics/atomic-metrics/<metric_id>/va
 ```bash
 guanmetric edit <metric_id> --file /tmp/atomic_metric_update.json -f json
 ```
+
+编辑载荷和公式/格式复制使用 `--raw` 的后端详情，成功后从后端 `response` 读取字段；不能把后端响应当成 canonical envelope。普通机器发现使用 `-f json` 并从 `data` 取值，canonical 详情不承诺完整编辑字段。

package/skills/guanmetric/references/metric-common-fields.md

@@ -32,6 +32,8 @@
 | `filter` | 业务限定/筛选 | 可选或条件必填 | 业务限定衍生指标必填 |
 | `dynamicParameters` | 动态参数默认值 | 可选 | 表达式或最近 N 配置引用动态参数时使用 |
 
+`guanmetric create/edit` 和指标定义类 `fetch POST` 会在提交前统一校验 `name`、`engName`、`desc`；标准 Excel 的原子、复合、衍生指标行使用相同规则。长度按 Web 表单的 JavaScript UTF-16 计数语义计算，因此 emoji 等非 BMP 字符计为 2，避免 CLI 校验通过但 Web 编辑页报超长。
+
 ## 筛选条件 `filter`（WebFilterData）
 
 原子指标筛选、复合指标筛选、衍生指标业务限定和查询加速筛选共用同一套 `WebFilterData` 协议。合法节点只有：
@@ -215,6 +217,8 @@ guanmetric fetch GET /api/metric-attr-config
 - `TEXT_AREA`：写入 `values[0]`，Web 单项最大 200 个字符。
 - 如果关联了业务字典 `bizMetricId`，业务口径和业务属性通常由业务字典同步；仍需确认最终 payload 中 `desc` 和 `bizAttrs` 已有值。
 
+当 JSON 创建/编辑 payload 包含非空 `bizAttrs` 时，CLI 会先读取当前环境的 `GET /api/metric-attr-config`，再按属性 ID 对 `TEXT` / `TEXT_AREA` 执行上述 50/200 长度校验。因此，这类请求（包括 `--dry-run`）需要有效登录态；不包含业务属性时，原子指标 `create --dry-run` 仍可只做本地字段校验。
+
 示例：
 
 ```json

package/skills/guanmetric/references/metric-composite-mutation.md

@@ -46,7 +46,7 @@
 - 先用 `guancli metric search <关键词> -d <projectId> -f json` 查询公式中的指标，再用 `guancli metric get <metric_id> --brief` 核对名称、类型、状态和适用维度。
 - 如果用户只提供数据集字段级公式，先询问是否要创建复合指标。用户确认后，再识别公式里的基础度量，创建或复用基础原子指标，并把公式改写为 `[metricId]`。
 - 如果输入来自标准 Excel，字段级公式需要读取 `公式来源数据集ID` / `公式来源数据集名称` 和 `公式字段映射`。没有这些映射时，不要根据 `repr / total_buyer` 这类裸 token 猜测字段或指标；应要求用户补齐或确认。
-- 公式只能引用数值型指标；不要引用当前正在编辑的指标本身。
+- 公式只能引用数值型原子指标或复合指标；不要引用衍生指标、快捷引用指标或当前正在编辑的指标本身。创建计划和提交前都要读取引用指标详情并核对 `subType`。
 - 公式支持 `+`、`-`、`*`、`/`、括号、数字和 `[指标ID]`；不要主动生成函数、窗口函数或 SQL 片段。
 - 公式中的 `[xxx]` 会被后端解析为上游指标 ID，并参与循环引用校验。
 - 如果用户用中文名描述公式，先转换成 ID 公式，再把“中文公式”和“ID 公式”都展示给用户确认。
@@ -58,7 +58,13 @@
 | `SUM([销售额字段]) / COUNT([订单ID字段])` | 先建“销售额”“订单数”原子指标，再建复合指标 `[metric_sales] / [metric_order_count]` |
 | `SUM([归因销售额字段]) / SUM([广告花费字段])` | 先建“归因销售额”“广告花费”原子指标，再建复合指标 ROAS |
 | `SUM([点击量字段]) / SUM([曝光量字段])` | 先建“点击量”“曝光量”原子指标，再建复合指标 CTR |
-| `COUNT(CASE WHEN ... THEN 1 ELSE NULL END) / COUNT([ID字段])` | 先判断分子是否应建为条件计数原子指标或业务限定衍生指标，再创建复合比率指标 |
+| `COUNT(CASE WHEN ... THEN 1 ELSE NULL END) / COUNT([ID字段])` | 优先把分子建为条件计数原子指标，再创建复合比率指标；业务限定衍生指标不能作为复合指标上游 |
+
+如果用户给出的公式依赖衍生指标，不要把它直接提交为复合指标：
+
+- 组合“最近 N、累计、期末值”等受支持衍生结果时，评估改建为组合衍生指标。
+- 表达“某个复合口径的同比/环比”时，通常先创建原子/复合基础口径，再基于该复合指标创建普通衍生指标。
+- 两种改写可能改变业务语义，例如“比率的同比”不等于“两个同比增长率相除”；创建计划必须展示改模方案并让用户确认。
 
 ## 适用维度
 
@@ -117,7 +123,7 @@
 
 1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、将复用或新建的基础指标、复合公式、共有适用维度/时间维度、格式、业务属性和保存方式。
 2. 用户确认计划后，生成 `/tmp/composite_metric.json`。
-3. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性。
+3. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性；逐个读取引用指标详情，确认 `subType` 仅为 `ATOMIC` 或 `COMPOSITE`。`guanmetric fetch` 也会在提交前执行同一类型检查。
 4. 按 `metric-common-fields.md` 向用户摘要并确认。
 5. 用户确认后，不调用原子指标 `save-precheck`；复合指标 Web 创建没有 save-precheck。
 6. 提交真实创建：
@@ -139,7 +145,7 @@ guancli metric get <metric_id> --brief
 1. 读取当前详情：
 
 ```bash
-guancli metric get <metric_id> -f json
+guancli metric get <metric_id> --raw
 ```
 
 2. 基于当前详情生成完整编辑 payload，例如 `/tmp/composite_metric_update.json`。至少包含 `projectId`、`subType`、`name`、`formula`、`useExpressionMetricCommonDims`、`applicableDims`、`desc`、`publish`。
@@ -157,3 +163,5 @@ guanmetric fetch POST /api/metric-platform/metrics/composite-metrics/<metric_id>
 ```
 
 6. 保存后回读确认。
+
+编辑载荷和公式/格式复制使用 `--raw` 的后端详情，成功后从后端 `response` 读取字段；不能把后端响应当成 canonical envelope。普通机器发现使用 `-f json` 并从 `data` 取值，canonical 详情不承诺完整编辑字段。

package/skills/guanmetric/references/metric-derived-mutation.md

@@ -342,7 +342,7 @@
 
 衍生指标常见做法：
 
-- 用户说“跟基础指标格式一样”时，先 `guancli metric get <baseMetricId> -f json` 读取基础指标 `format` 并复制。
+- 用户说“跟基础指标格式一样”时，先 `guancli metric get <baseMetricId> --raw` 读取基础指标 `format` 并复制。
 - 同比/环比增长率、转化率、占比类指标通常使用 `PERCENTAGE`。
 - 最近 N、累计、期末值通常复制基础指标 `format`；如果用户没有明确要求，也可以省略 `format` 使用默认。
 
@@ -433,7 +433,7 @@ guanmetric fetch POST /api/metric-platform/metrics/derived-metrics --stdin < /tm
 1. 读取当前详情：
 
 ```bash
-guancli metric get <metric_id> -f json
+guancli metric get <metric_id> --raw
 ```
 
 2. 基于当前详情生成完整编辑 payload，例如 `/tmp/derived_metric_update.json`。至少包含 `projectId`、`subType`、`name`、`baseMetricId`（普通衍生）、`deriveSetting`、`desc`、`publish`。
@@ -451,3 +451,5 @@ guanmetric fetch POST /api/metric-platform/metrics/derived-metrics/<metric_id> -
 ```
 
 6. 保存后回读确认。
+
+编辑载荷和公式/格式复制使用 `--raw` 的后端详情，成功后从后端 `response` 读取字段；不能把后端响应当成 canonical envelope。普通机器发现使用 `-f json` 并从 `data` 取值，canonical 详情不承诺完整编辑字段。

package/skills/guanmetric/references/metric-excel-template.md

@@ -280,7 +280,7 @@ agent 根据标准模板生成创建 payload 时，必须识别这些成组字
 - `原子指标模板` 行必须明确 `指标类型=原子指标`，并尽量填写数据集、计算方式、适用维度等原子指标字段。计算方式可以是 `来源字段` + `聚合方式`，也可以是 `字段表达式`，但不能同时填写两种。
 - 各衍生指标模板行必须明确 `指标类型=衍生指标`，并根据用户语义放入对应衍生 sheet；例如同比/环比放入 `同比环比衍生模板`，最近 N 天/周/月放入 `最近N衍生模板`，累计放入 `累计衍生模板`，期末值放入 `期末值衍生模板`，业务筛选限定放入 `业务限定衍生模板`，组合衍生放入 `组合衍生模板`。
 - `复合指标模板` 行必须明确 `指标类型=复合指标`，并尽量填写计算公式、引用指标、公式来源数据集和公式字段映射等复合指标字段。
-- 复合指标计算公式中的 `[指标名]` 必须能对应到已有指标或本次将创建的基础指标。若公式引用的指标名不在 `原子指标模板` 中，agent 应在 `原子指标模板` 中补充同名原子指标行，保证后续创建顺序为先创建基础原子指标，再创建复合指标。无法确定数据集、来源字段、聚合方式时先留空或写入最保守默认值，并让 CLI 在 `问题说明` 中暴露需要用户补齐的字段。
+- 复合指标计算公式中的 `[指标名]` 必须能对应到已有或本批先创建的原子指标/复合指标，不能对应衍生指标或快捷引用指标。同批模板发现复合公式引用衍生指标时会把该行标为 `错误`；线上已有指标则在创建计划和 `guanmetric fetch` 提交前读取详情核对 `subType`。缺失依赖应按真实语义补到原子指标模板或复合指标模板，不要一律补成原子指标；无法确定建模方式或必要字段时，在 `问题说明` 中列出待确认项。
 - 衍生指标的 `衍生自` 也必须能对应到已有指标或本次将创建的指标。如果 `衍生自` 是本批也要创建的指标，必须在标准模板阶段就把它列入 `原子指标模板` 或 `复合指标模板`；创建计划阶段只核对和排序，不临时新增模板外基础指标。若该基础指标线上不存在且模板中也没有对应行，agent 必须回到模板补充基础指标行；补充所需信息不足时，在基础指标行或衍生指标行的 `问题说明` 中列出缺失的数据集、来源字段、聚合方式、复合公式、引用指标映射、适用维度或时间维度。
 - 客户表中的“表达式”“统计口径”“分子/分母”“达成率”“同比/环比”“最近 N”“累计”“期末值”“业务限定”“维度勾选”等语义，不应靠 CLI 写死列名猜测；agent 应结合整张表和上下文理解后写入标准字段。
 - 标准模板生成后必须检查 `汇总` sheet 的指标总数和衍生指标数，并结合 report.notes 检查是否存在衍生类型缺类。如果业务口径或用户输入中出现明显衍生语义，而对应衍生 sheet 为空，需要回到 `ai_mapped.xlsx` 重做或在交付摘要中明确说明这些语义为什么不创建衍生指标。

package/skills/guanmetric/references/metric-expression-rules.md

@@ -93,10 +93,12 @@ END
 ### 引用限制
 
 - 可引用已上线且当前用户可使用的原子指标、复合指标。
+- 不要引用任何衍生指标；这类依赖需要按业务语义改建为组合衍生，或先创建复合基础口径再做普通衍生。
 - 不要引用当前正在编辑的指标本身。
 - 不要引用快捷引用指标（有 `linkMetricId` 的指标）。
 - 公式中的 `[xxx]` 会被后端识别为上游指标 ID，并参与循环引用校验。
 - 复合指标适用维度必须来自公式中引用指标的共有维度；没有共有维度时会报错。
+- `guanmetric fetch` 会在创建/编辑复合指标前读取每个引用指标详情，只放行 `ATOMIC`/`COMPOSITE`；无法确认类型时停止提交。
 
 ### 避免生成
 

package/skills/guanmetric/references/metric-mutation.md

@@ -73,6 +73,7 @@ guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <repor
    - 原子指标如果填写 `字段表达式`，生成 `formulaField.fdFormula`，且不要同时传 `fdId/aggrType`。
    - 原子指标如果填写 `来源字段` + `聚合方式`，解析为 `fdId` + `aggrType`。
    - 复合指标必须把 `复合公式` 结合 `公式引用指标` 或前置创建结果改写成 `[metricId]` 形式。
+   - 复合指标的每个引用必须解析并核对为 `ATOMIC`/`COMPOSITE`；发现 `DERIVED`/快捷引用指标时停止计划，按业务语义改建为组合衍生或“先复合、后衍生”。
    - `适用维度`、`时间维度`、业务属性列都需要解析成接口字段，不要把中文名原样提交给后端。
 5. 读取启用的指标业务属性配置，补齐必填 `bizAttrs`。
 6. 生成“指标创建计划”，让用户 review；用户确认计划前，不生成最终提交 JSON，不执行 dry-run/precheck/真实创建。
@@ -93,6 +94,7 @@ guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <repor
 - 目标目录路径和目录 ID。
 - 将创建的指标清单，按依赖顺序排序；每个指标标明临时序号、名称、类型、保存方式。
 - 每个指标的核心口径：原子指标写数据集、字段、聚合方式或表达式；复合指标写中文公式和 `[metricId]` 公式草案；衍生指标写基础指标和衍生配置。
+- 复合指标依赖核对结果：逐个列出引用指标的 ID、名称和 `subType`，只允许原子/复合指标。若原口径依赖衍生指标，必须展示替代建模及语义差异，确认前不生成提交 payload。
 - 衍生指标的 `衍生自` 解析结果：必须先检查标准模板中是否已有同名原子/复合指标行，再查询现有指标。若该 `衍生自` 是本批也要创建的指标，标准模板阶段就必须已经列出对应基础指标行；创建计划阶段只负责核对、排序和暴露缺失信息，不临时新增模板外指标。
 - 适用维度和时间维度；如果存在时间字段但时间维度为空，计划必须标记为待确认，不能进入提交步骤。
 - 数据格式、业务负责人、必填业务属性。

package/skills/guanmetric/references/metric-tree-mutation.md

@@ -114,7 +114,7 @@ guancli auth status
 
 - 有 ID：用 `guancli metric get <metric_id> --brief` 或 `-f json` 回读确认。
 - 只有名称：用 `guancli metric search <keyword> -f json` 搜索；多候选必须让用户指定 ID。
-- 需要配置维度、时间对比或复合指标展开时，必须用 `guancli metric get <metric_id> -f json` 读取完整详情。
+- 需要配置维度、时间对比或复合指标展开时，必须用 `guancli metric get <metric_id> --raw` 读取完整详情。
 
 指标树父目录来自 `METRIC_TREE` 目录体系：
 
@@ -265,7 +265,7 @@ guancli metric_attribution tree -f json
 
 处理规则：
 
-1. 对每个参与指标执行 `guancli metric get <metric_id> -f json`。
+1. 对每个参与指标执行 `guancli metric get <metric_id> --raw`。
 2. 如果 `subType=COMPOSITE`，读取其 `formula` 字段。
 3. 从 `formula` 中提取 `[metricId]` 引用和 `+ - * /` 运算符。
 4. 把复合指标作为节点保留，再把公式引用指标作为它的子节点。
@@ -468,3 +468,5 @@ guancli metric_attribution query <metric_tree_id> --target index
 - `metric-tree init-config <root_metric_id>`：按前端初始化逻辑生成默认 config。
 - `metric-tree validate-config`：离线校验维度、交叉维度、指标关系树和时间对比开关。
 - `metric-tree plan`：从简化 DSL 或用户公式生成 create/config JSON。
+
+编辑载荷和公式/格式复制使用 `--raw` 的后端详情，成功后从后端 `response` 读取字段；不能把后端响应当成 canonical envelope。普通机器发现使用 `-f json` 并从 `data` 取值，canonical 详情不承诺完整编辑字段。