@guandata/guancli 1.0.30 → 1.0.32

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

@@ -0,0 +1,384 @@
+# 衍生指标创建与编辑
+
+衍生指标用于在基础指标之上配置同比/环比、最近 N、累计、期末值、业务限定，或通过组合衍生公式引用多个指标。
+
+## 触发场景
+
+- 用户说“创建衍生指标”“做同比/环比”“最近 N 天/周/月”“本月累计/年累计”“期末值”“业务限定”。
+- 用户要编辑一个 `subType=DERIVED` 的指标。
+
+## 创建必填信息
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `projectId` | 主题 ID | 指标所属主题 |
+| `subType` | 指标类型 | 固定 `DERIVED` |
+| `name` | 指标名称 | 最长 50 |
+| `deriveSetting` | 衍生配置 | 见下方细节 |
+| `desc` | 业务口径 | 最长 1000 |
+| `parentDirId` | 保存至/所属文件夹 | 创建时需要 |
+| `businessOwner` | 责任人 | 创建时需要 |
+| `publish` | 保存方式 | `true` 上线，`false` 草稿 |
+
+普通衍生还需要：
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `baseMetricId` | 衍生自/基础指标 ID | 不能是快捷引用指标；先用 `metric search/get` 确认 |
+
+组合衍生不选择单个 `baseMetricId`，核心配置在 `deriveSetting.formula`。
+
+通用可选字段见 `metric-common-fields.md`。`BIZ_CONDITION` 类型必须提供顶层 `filter`。
+
+## 衍生类型
+
+| `advType` / `deriveType` | 中文 | 说明 |
+| --- | --- | --- |
+| `COMPARATIVE` | 同比/环比 | 需要基础指标有时间维度；配置本期、对比期和输出值类型 |
+| `RECENT_X` | 最近 N | 只能衍生自原子指标；如最近 7 天、最近 3 月 |
+| `XTD` | 累计计算 | 周/月/季/年至今累计，或近 N 个粒度累计 |
+| `LAST` | 期末值 | 按基础指标时间维度取期末值 |
+| `BIZ_CONDITION` | 业务限定 | 在基础指标上附加业务筛选，顶层 `filter` 必填 |
+| `deriveType=COMPOSITE` | 组合衍生 | 通过 `deriveSetting.formula` 引用多个指标 |
+
+## `deriveSetting` 通用结构
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `deriveType` | 衍生大类 | 普通衍生为 `ORDINARY`；组合衍生为 `COMPOSITE` |
+| `advType` | 衍生方式 | 普通衍生必填；组合衍生提交前可删除 |
+| `advValue` | 衍生方式配置 | 普通衍生必填；组合衍生可为 `null` 或不传 |
+| `formula` | 组合衍生公式 | 组合衍生必填，使用 `[metric_id]` 引用指标 |
+
+时间粒度 `granularity` 常用值：
+
+| 值 | 中文 |
+| --- | --- |
+| `DAY` | 日 |
+| `WEEK` | 周 |
+| `MONTH` | 月 |
+| `QUARTER` | 季度 |
+| `YEAR` | 年 |
+| `NONE` | 历史数据 |
+| `YEARBYWEEK` | 年同比按周 |
+| `ENDOFMONTH` | 上月末 |
+| `ENDOFQUARTER` | 上季度末 |
+| `ENDOFYEAR` | 上年末 |
+
+基准日期 `baseline` 常用值：
+
+| 值 | 中文 |
+| --- | --- |
+| `DATE_RANGE_PARAM_LEFT` | 基于日期筛选：开始日期 |
+| `DATE_RANGE_PARAM_RIGHT` | 基于日期筛选：结束日期 |
+
+## 同比/环比 `COMPARATIVE`
+
+用于描述本期时间范围、上期/对比期时间范围、输出值类型。
+
+字段明细：
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `advValue.advType` | 高级计算类型 | 固定 `COMPARATIVE` |
+| `dateFdId` | 日期字段 ID | 来自基础指标时间维度；必填 |
+| `dateFdName` | 日期字段名称 | 建议带上 |
+| `granularity` | 时间粒度 | `DAY/WEEK/MONTH/QUARTER/YEAR` |
+| `window` | 本期时间范围 | Web 默认常见为 `{ "offset": 0 }` |
+| `offsetType` | 对比方式粒度 | 如 `MONTH` 月环比、`YEAR` 年同比、`ENDOFMONTH` 上月末 |
+| `offset` | 偏移量 | 同环比默认 `1`；自定义偏移可大于 1 |
+| `fixedBase` | 固定对比期 | 自定义时间范围时使用 |
+| `valueType` | 数值设置 | `VALUE`、`RATE`、`RAWDATA`、`CUSTOM` |
+| `growthRateType` | 增长率算法 | `RATE` 时必填：`NORMAL` 或 `ABS` |
+| `formulaSetting` | 自定义公式 | `CUSTOM` 时必填，由公式编辑器生成 |
+
+`window` 写法：
+
+| 形态 | JSON | 说明 |
+| --- | --- | --- |
+| 当前粒度本期 | `{ "offset": 0 }` | 当前日/周/月/季/年 |
+| 上一个粒度区间 | `{ "offset": 1 }` | 上日/上周/上月等 |
+| 相对日期 | `{ "offset": 3 }` | 相对本期前 3 个粒度 |
+| 固定区间 | `{ "withMacro": false, "period": ["2026-05-01", "2026-05-31"] }` | 固定日期范围 |
+| 时间宏 | `{ "withMacro": true, "period": ["{{{}}}", "{{{}}}"] }` | 使用时间宏表达式 |
+
+数值设置：
+
+| `valueType` | 中文 | 额外字段 |
+| --- | --- | --- |
+| `VALUE` | 增长值 | 无，含义为本期数据 - 上期数据 |
+| `RATE` | 增长率 | `growthRateType` 必填 |
+| `RAWDATA` | 对比值 | 无，直接输出上期/对比期数据 |
+| `CUSTOM` | 自定义公式 | `formulaSetting` 必填 |
+
+示例：月环比增长率：
+
+```json
+"deriveSetting": {
+  "deriveType": "ORDINARY",
+  "advType": "COMPARATIVE",
+  "advValue": {
+    "advType": "COMPARATIVE",
+    "dateFdId": "<time_fd_id>",
+    "dateFdName": "订单日期",
+    "granularity": "MONTH",
+    "window": { "offset": 0 },
+    "offsetType": "MONTH",
+    "offset": 1,
+    "valueType": "RATE",
+    "growthRateType": "NORMAL"
+  }
+}
+```
+
+## 最近 N `RECENT_X`
+
+只能衍生自原子指标。
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `advValue.advType` | 高级计算类型 | 固定 `RECENT_X` |
+| `granularity` | 时间粒度 | `DAY/WEEK/MONTH/QUARTER/YEAR` |
+| `baseline` | 基准日期 | `DATE_RANGE_PARAM_LEFT` 或 `DATE_RANGE_PARAM_RIGHT` |
+| `baselineOffset` | 起止偏移 | 二元数组 `[startOffset, endOffset]` |
+| `baselineOffsetDynamicParameters` | 动态参数偏移 | 如 `[DYNAMIC_PARAMS.N]`，非空时优先于 `baselineOffset` |
+| `aggrType` | 计算方式 | 通常 `SUM/MIN/MAX/AVG/CNT/CNT_DISTINCT/NUL` |
+
+偏移示例：
+
+- `[6,0]` + `DAY`：以基准日期为结束，最近 7 天。
+- `[29,0]` + `DAY`：最近 30 天。
+- `[3,1]` + `MONTH`：基准日期前第 3 个月到前第 1 个月。
+- 动态参数：把对应位置的 `baselineOffset` 置为 `-1`，在 `baselineOffsetDynamicParameters` 写 `[DYNAMIC_PARAMS.xxx]`，同时在顶层 `dynamicParameters` 填默认值。
+
+示例：
+
+```json
+"deriveSetting": {
+  "deriveType": "ORDINARY",
+  "advType": "RECENT_X",
+  "advValue": {
+    "advType": "RECENT_X",
+    "granularity": "DAY",
+    "baseline": "DATE_RANGE_PARAM_RIGHT",
+    "baselineOffset": [6, 0],
+    "aggrType": "SUM"
+  }
+}
+```
+
+## 累计计算 `XTD`
+
+用于“周/月/季/年至今累计”或“近 N 个粒度累计”。
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `advValue.advType` | 高级计算类型 | 固定 `XTD` |
+| `granularity` | 累计范围 | `WEEK/MONTH/QUARTER/YEAR/NONE` |
+| `baseline` | 基准日期 | `DATE_RANGE_PARAM_LEFT` 或 `DATE_RANGE_PARAM_RIGHT` |
+| `baselineOffset` | 自定义累计偏移 | 可选数字；例如 `1` 表示近 2 个粒度累计 |
+| `includeCurrentValue` | 是否包含基准日期当前值 | `true/false` |
+
+示例：月累计：
+
+```json
+"deriveSetting": {
+  "deriveType": "ORDINARY",
+  "advType": "XTD",
+  "advValue": {
+    "advType": "XTD",
+    "granularity": "MONTH",
+    "baseline": "DATE_RANGE_PARAM_RIGHT",
+    "includeCurrentValue": true
+  }
+}
+```
+
+限制：基础指标是复合指标时，不支持部分自定义累计方式；特别是“当年累计”这类年累计自定义配置需谨慎，Web 会拦截不支持组合。
+
+## 期末值 `LAST`
+
+```json
+"deriveSetting": {
+  "deriveType": "ORDINARY",
+  "advType": "LAST",
+  "advValue": {
+    "advType": "LAST",
+    "dateFdId": "<time_fd_id>"
+  }
+}
+```
+
+`dateFdId` 必须来自基础指标时间维度。
+
+## 业务限定 `BIZ_CONDITION`
+
+业务限定必须提供顶层 `filter`。
+
+```json
+"deriveSetting": {
+  "deriveType": "ORDINARY",
+  "advType": "BIZ_CONDITION",
+  "advValue": {
+    "advType": "BIZ_CONDITION"
+  }
+},
+"filter": {
+  "combineType": "AND",
+  "conditions": []
+}
+```
+
+`filter` 结构复杂时，优先参考同环境已有指标详情或由 Web 配置后复制 payload，不凭空拼复杂筛选。
+
+## 组合衍生 `COMPOSITE`
+
+组合衍生通过公式引用多个指标，不选择单个 `baseMetricId`：
+
+```json
+"deriveSetting": {
+  "deriveType": "COMPOSITE",
+  "formula": "[<metric_id_1>] / [<metric_id_2>]"
+}
+```
+
+引用规则：
+
+- 涉及组合衍生 `deriveSetting.formula` 时，先读取 `metric-expression-rules.md`。
+- 公式支持 `+`、`-`、`*`、`/`、括号、数字和 `[指标ID]`；不要主动生成函数、窗口函数或 SQL 片段。
+- 可引用原子指标。
+- 可引用普通衍生里的 `RECENT_X`、`XTD`、`LAST`。
+- 不要引用复合指标、组合衍生、快捷引用指标或当前正在编辑的指标。
+- 组合衍生需要公式引用指标存在共有时间维度；没有共有时间维度时 Web 会提示不可配置衍生指标。
+
+## 基础指标选择规则
+
+- 普通衍生可衍生自原子指标或复合指标；不能衍生自快捷引用指标。
+- `RECENT_X` 只能衍生自原子指标。
+- `COMPARATIVE` 和 `LAST` 需要基础指标有时间维度。
+- `COMPARATIVE` 可基于最近 N、累计、期末值、组合衍生继续衍生。
+- `BIZ_CONDITION` 可基于非业务限定的任意其它衍生指标。
+
+## 信息收集
+
+如果用户只说“帮我创建一个衍生指标”，先收集：
+
+1. 指标主题和保存目录。
+2. 衍生类型：同比/环比、最近 N、累计、期末值、业务限定、组合衍生。
+3. 普通衍生的基础指标，或组合衍生要引用的指标与公式。
+4. 时间粒度、时间偏移、是否包含当天、数值设置等衍生配置。
+5. 业务限定的筛选条件 `filter`。
+6. 数据格式：默认沿用/复制基础指标格式，或指定为数值、货币、百分比；如需指定，确认小数位、千分位、货币符号/前后缀、数量级单位、百分比是否除以 100。
+7. 指标名称、业务口径、是否保存并上线。
+8. 责任人和必填 `bizAttrs`。
+
+衍生指标常见做法：
+
+- 用户说“跟基础指标格式一样”时，先 `guancli metric get <baseMetricId> -f json` 读取基础指标 `format` 并复制。
+- 同比/环比增长率、转化率、占比类指标通常使用 `PERCENTAGE`。
+- 最近 N、累计、期末值通常复制基础指标 `format`；如果用户没有明确要求，也可以省略 `format` 使用默认。
+
+## JSON 模板：最近 7 天
+
+```json
+{
+  "projectId": "<metric_project_id>",
+  "subType": "DERIVED",
+  "name": "最近7天销售额",
+  "engName": "sales_amount_recent_7d",
+  "baseMetricId": "<atomic_metric_id>",
+  "deriveSetting": {
+    "deriveType": "ORDINARY",
+    "advType": "RECENT_X",
+    "advValue": {
+      "advType": "RECENT_X",
+      "granularity": "DAY",
+      "baseline": "DATE_RANGE_PARAM_RIGHT",
+      "baselineOffset": [6, 0],
+      "aggrType": "SUM"
+    }
+  },
+  "format": {
+    "formatType": "CURRENCY",
+    "decimalPlaces": 2,
+    "useThousandsSeparator": true,
+    "prefix": "￥",
+    "prefixUnit": null,
+    "showPrefixUnit": true,
+    "suffix": ""
+  },
+  "desc": "统计筛选日期结束日前最近7天的销售额。",
+  "parentDirId": "<metric_dir_id>",
+  "businessOwner": "<user_id>",
+  "publish": false
+}
+```
+
+## JSON 模板：组合衍生
+
+```json
+{
+  "projectId": "<metric_project_id>",
+  "subType": "DERIVED",
+  "name": "组合衍生客单价",
+  "deriveSetting": {
+    "deriveType": "COMPOSITE",
+    "formula": "[<recent_sales_metric_id>] / [<recent_order_metric_id>]"
+  },
+  "format": {
+    "formatType": "NUMBER",
+    "decimalPlaces": 2,
+    "useThousandsSeparator": true,
+    "prefixUnit": null,
+    "showPrefixUnit": true,
+    "prefix": "",
+    "suffix": ""
+  },
+  "desc": "使用多个衍生指标组合计算客单价。",
+  "parentDirId": "<metric_dir_id>",
+  "businessOwner": "<user_id>",
+  "publish": false
+}
+```
+
+## 创建步骤
+
+`guancli metric create` 当前是原子指标专用 endpoint；衍生指标创建使用 `guancli fetch`。
+
+1. 生成 `/tmp/derived_metric.json`。
+2. 本地/人工检查 JSON、基础指标或公式引用指标、时间维度、衍生配置、必填业务属性。
+3. 按 `metric-common-fields.md` 向用户摘要并确认。
+4. 用户确认后，不调用原子指标 `save-precheck`；衍生指标 Web 创建没有 save-precheck。
+5. 提交真实创建：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/derived-metrics --stdin < /tmp/derived_metric.json
+```
+
+6. 响应返回指标 ID 后回读确认。
+
+## 编辑步骤
+
+衍生指标没有原子指标的 save-precheck；主要校验基础指标、衍生配置或筛选变化是否影响下游指标/卡片。
+
+1. 读取当前详情：
+
+```bash
+guancli metric get <metric_id> -f json
+```
+
+2. 基于当前详情生成完整编辑 payload，例如 `/tmp/derived_metric_update.json`。至少包含 `projectId`、`subType`、`name`、`baseMetricId`（普通衍生）、`deriveSetting`、`desc`、`publish`。
+3. 如果修改了 `baseMetricId`、`deriveSetting` 或 `filter`，先调用影响校验：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/derived-metrics/<metric_id>/validate-update-impact --stdin < /tmp/derived_metric_update.json
+```
+
+4. 如果返回 `hasChanged=true` 且 `affectedMetrics` 或 `affectedCards` 非空，展示受影响指标和卡片，等待用户二次确认。
+5. 提交真实编辑：
+
+```bash
+guancli fetch POST /api/metric-platform/metrics/derived-metrics/<metric_id> --stdin < /tmp/derived_metric_update.json
+```
+
+6. 保存后回读确认。

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

@@ -0,0 +1,143 @@
+# 指标表达式 / 计算公式支持范围
+
+本文件用于创建或编辑指标时约束 AI 生成公式的形态，覆盖：
+
+- 原子指标 `formulaField.fdFormula`
+- 复合指标 `formula`
+- 衍生指标选择“组合衍生”时的 `deriveSetting.formula`
+
+## 总体原则
+
+- 用户给出中文字段名或指标名时，最终 payload 必须替换成 ID 引用：数据集字段写 `[fdId]`，指标写 `[metricId]`。
+- 优先生成 Web 编辑器明确支持的简单表达式；复杂函数、嵌套函数、窗口函数、自定义 SQL 函数不要主动生成。
+- 公式中使用英文半角符号：`+ - * / ( ) [ ]`。
+- 不要把指标中文名直接提交到后端；中文名只用于向用户展示“可读公式”。
+- 条件表达式优先使用 `CASE WHEN ... THEN ... ELSE ... END`。虽然底层数据集公式解析能识别部分 `IF(condition, trueValue, falseValue)` 写法，但 AI 生成指标表达式时默认转成 `CASE WHEN`，兼容性更稳定。
+- 如果用户坚持使用本文件未列出的公式形态，先提示可能被前端/后端校验拦截，建议用户在 Web 公式编辑器中校验或先保存草稿验证。
+
+## 原子指标表达式 `formulaField.fdFormula`
+
+原子指标选择“使用表达式”时，表达式走数据集公式编辑器和后端数据集派生字段校验。后端会把公式当成数据集计算字段检查，并要求最终字段是聚合表达式；没有聚合函数会报“原子指标表达式必须包含聚合函数”。
+
+### 推荐支持形态
+
+| 形态 | 示例 | 说明 |
+| --- | --- | --- |
+| 单聚合 | `SUM([fd_amount])` | 最常用 |
+| 计数 | `COUNT([fd_order_id])` | 计数类表达式 |
+| 聚合项加减 | `SUM([fd_amount]) - SUM([fd_refund])` | 多个聚合结果加减 |
+| 聚合内部加减 | `SUM([fd_price] + [fd_tax] - [fd_discount])` | 字段先加减再聚合 |
+| 条件聚合 | `SUM(CASE WHEN [fd_status] = 'paid' THEN [fd_amount] ELSE 0 END)` | 支持 `CASE WHEN`、比较、`AND/OR/NOT` |
+| 条件计数 | `COUNT(CASE WHEN [fd_status] = 'paid' THEN 1 ELSE 0 END)` | 条件计数 |
+| 顶层比值 | `SUM([fd_amount]) / COUNT([fd_order_id])` | 只建议一个顶层 `/` |
+| 分子/分母加减后相除 | `(SUM([fd_a]) + SUM([fd_b])) / (SUM([fd_c]) + COUNT([fd_d]))` | 分子、分母内部仅用加减和推荐聚合 |
+| 动态参数 | `SUM(CASE WHEN [fd_amount] > [DYNAMIC_PARAMS.N] THEN [fd_amount] ELSE 0 END)` | 同时在顶层 `dynamicParameters` 写默认值 |
+
+### 避免生成
+
+- 无聚合表达式：`[fd_amount] + [fd_tax]`。
+- 乘法：`SUM([fd_price] * [fd_qty])`、`SUM([fd_a]) * SUM([fd_b])`。
+- 非顶层除法：`SUM([fd_a]) + SUM([fd_b]) / SUM([fd_c])`。
+- 多重除法：`SUM([fd_a]) / SUM([fd_b]) / SUM([fd_c])`。
+- `AVG/MAX/MIN/FIRST/LAST/ANY_VALUE` 等聚合函数表达式；如果用户要平均值、最大值、最小值，优先走“来源字段 + `aggrType=AVG/MAX/MIN`”。
+- 窗口函数、子查询、跨数据集字段、字段中文名直接入参。
+
+## `IF` 语法转 `CASE WHEN`
+
+当用户用自然语言或公式写出 `if` / `IF` 条件语法时，不要照抄 `IF(...)` 到指标 payload，默认转换为 `CASE WHEN`：
+
+| 用户写法 | 生成写法 |
+| --- | --- |
+| `IF(condition, trueValue, falseValue)` | `CASE WHEN condition THEN trueValue ELSE falseValue END` |
+| `SUM(IF([fd_status] = 'paid', [fd_amount], 0))` | `SUM(CASE WHEN [fd_status] = 'paid' THEN [fd_amount] ELSE 0 END)` |
+| `COUNT(IF([fd_status] = 'paid', 1, NULL))` | `COUNT(CASE WHEN [fd_status] = 'paid' THEN 1 ELSE NULL END)` |
+| `IF(SUM([fd_a]) > 0, SUM([fd_b]), 0)` | `CASE WHEN SUM([fd_a]) > 0 THEN SUM([fd_b]) ELSE 0 END` |
+
+嵌套 `IF` 转多分支 `CASE WHEN`：
+
+```text
+IF(c1, v1, IF(c2, v2, v3))
+```
+
+转换为：
+
+```text
+CASE
+  WHEN c1 THEN v1
+  WHEN c2 THEN v2
+  ELSE v3
+END
+```
+
+转换注意事项：
+
+- 必须保留原条件里的比较、`AND/OR/NOT`、字符串字面量和动态参数。
+- 三个参数分别是条件、命中值、未命中值；遇到逗号嵌套在括号或字符串中时，不要错误拆分。
+- 原子指标表达式仍必须满足聚合要求：最终表达式要包含 `SUM` 或 `COUNT` 等聚合上下文。
+- 如果用户给出的 `IF` 结构无法可靠拆分，先向用户确认条件、命中值和未命中值，再生成 `CASE WHEN`。
+
+## 复合指标公式 `formula`
+
+复合指标公式组合已有指标。Web 公式编辑器会把 `[指标名称]` 转成 `[metricId]`；CLI 生成 payload 时必须直接使用 `[metricId]`。
+
+### 推荐支持形态
+
+| 形态 | 示例 |
+| --- | --- |
+| 单指标引用 | `[metric_sales]` |
+| 加减乘除 | `[metric_sales] / [metric_orders]` |
+| 数字常量 | `[metric_sales] * 2 + 100` |
+| 括号分组 | `([metric_sales] - [metric_refund]) / [metric_orders]` |
+
+### 引用限制
+
+- 可引用已上线且当前用户可使用的原子指标、复合指标。
+- 不要引用当前正在编辑的指标本身。
+- 不要引用快捷引用指标（有 `linkMetricId` 的指标）。
+- 公式中的 `[xxx]` 会被后端识别为上游指标 ID，并参与循环引用校验。
+- 复合指标适用维度必须来自公式中引用指标的共有维度；没有共有维度时会报错。
+
+### 避免生成
+
+- 指标中文名入参：`[销售额] / [订单数]` 只能用于展示，payload 必须替换成 `[metricId] / [metricId]`。
+- 数据集字段引用：`[fd_amount]`。
+- 复杂函数、窗口函数、SQL 片段、字符串拼接。
+
+## 衍生指标：组合衍生 `deriveSetting.formula`
+
+组合衍生公式也是指标公式，但引用范围比复合指标更窄。
+
+### 推荐支持形态
+
+同复合指标：`+ - * / ( )`、数字常量、`[metricId]`。
+
+示例：
+
+```text
+[metric_recent_sales] / [metric_recent_orders]
+([metric_xtd_sales] - [metric_xtd_refund]) / [metric_last_inventory]
+```
+
+### 引用限制
+
+- 可引用原子指标。
+- 可引用普通衍生指标中 `RECENT_X`（最近 N）、`XTD`（累计计算）、`LAST`（期末值）。
+- 不要引用组合衍生指标。
+- 不要引用复合指标、快捷引用指标或当前正在编辑的指标。
+- 公式引用的指标必须存在共有时间维度；没有共有时间维度时 Web 会提示“源指标没有共有时间维度，不可配置衍生指标”。
+
+### 避免生成
+
+- 任意数据集字段引用。
+- 函数、窗口函数、SQL 片段。
+- 引用同比/环比、业务限定、组合衍生等不在允许范围内的衍生指标。
+
+## 后端公式合法性校验的安全子集
+
+部分场景（例如指标树归因的贡献分析）会使用更严格的后端公式合法性校验。为了让新建指标后尽量兼容这些场景，AI 默认按以下安全子集生成：
+
+- 原子表达式：`SUM`、`COUNT`、加减、条件表达式；如果有除法，整个表达式必须是一个顶层 `分子 / 分母`，且分子分母分别满足前述规则。
+- 复合指标：最终展开到原子指标后，也应能落到上述安全子集。
+- 衍生组合：优先只做指标间的四则运算；需要参与归因时，优先避免乘法和非顶层除法。
+
+如果用户明确不需要归因/贡献分析，可以按 Web 创建表单的基础限制放宽，但仍应先保存草稿或 dry-run/校验。

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

@@ -0,0 +1,67 @@
+# 指标新建 / 编辑 / 删除指引
+
+本文是指标写操作的入口索引，用于指导 AI 选择应加载的细分文档，避免一次性读取所有指标类型的长配置。当前覆盖原子指标、复合指标、衍生指标的创建/编辑预检查；删除的完整交互流程后续补充。
+
+## 读取顺序
+
+处理指标写操作时按需读取：
+
+1. 先读本文，判断指标类型和整体保存流程。
+2. 始终读取 `metric-common-fields.md`，获取当前环境、通用字段、业务属性 `bizAttrs`、发布/校验规则。
+3. 只读取目标类型文档：
+   - 原子指标：`metric-atomic-mutation.md`
+   - 复合指标：`metric-composite-mutation.md`
+   - 衍生指标：`metric-derived-mutation.md`
+   - 删除指标：`metric-delete-mutation.md`
+4. 如果用户意图不明确，先按“类型判断”问清楚，再加载对应类型文档。
+
+## 类型判断
+
+| 用户意图 | 指标类型 | 读取文档 |
+| --- | --- | --- |
+| 基于一个数据集字段求和、计数、平均、最大、最小、去重计数，或用数据集字段公式生成指标 | 原子指标 `ATOMIC` | `metric-atomic-mutation.md` |
+| 用已有指标做公式，例如销售额 / 订单数、A + B、多个指标组合计算 | 复合指标 `COMPOSITE` | `metric-composite-mutation.md` |
+| 同比、环比、最近 N 天/周/月、累计、期末值、业务限定、组合衍生 | 衍生指标 `DERIVED` | `metric-derived-mutation.md` |
+| 删除、移除某个指标 | 通用删除流程 | `metric-delete-mutation.md` |
+
+常见含混说法：
+
+- “新建一个指标，基于某数据集/某字段”：通常是原子指标。
+- “客单价 = 销售额 / 订单数”：通常是复合指标。
+- “给销售额做月环比/最近 7 天/本月累计/华东限定”：通常是衍生指标。
+
+## 总体流程
+
+1. 使用当前已登录环境，不主动询问 profile；写操作前可执行 `guancli auth status`。
+2. 信息不全时先查 ID，不凭空猜：
+   - 指标主题：`guancli metric project [keyword] -f json`
+   - 指标目录：`guancli metric tree -f json`
+   - 指标详情：`guancli metric search <keyword> -f json`、`guancli metric get <metric_id> --brief`
+   - 数据集字段：`guancli ds search <keyword>`、`guancli ds get <dsId> --brief`
+3. 读取启用的指标业务属性配置，补齐必填 `bizAttrs`。
+4. 生成 JSON 文件，先做 dry-run 或人工摘要，向用户确认当前环境、目标目录、指标口径、计算配置、业务属性和保存方式。
+5. 用户确认后，仍需按 Web 同款交互执行保存前校验或影响校验。
+6. 校验通过、无对应校验，或用户对冲突/影响完成二次确认后，才提交真实创建或编辑。
+7. 写入成功后用 `guancli metric get <metric_id> --brief` 回读确认。
+
+不要把“dry-run 成功”“precheck 通过”或“影响校验无阻塞”描述成指标已经创建/编辑成功。
+
+## 校验入口速查
+
+| 操作 | 校验规则 |
+| --- | --- |
+| 原子创建，`publish=true` | 先 `POST /api/metric-platform/metrics/atomic-metrics/save-precheck` |
+| 原子创建，`publish=false` | Web 跳过 save-precheck，可在用户确认后创建草稿 |
+| 原子编辑，`publish=true` | 先 atomic `save-precheck`，请求体带 `metricId`；再跑 `validate-update-impact` |
+| 原子编辑，`publish=false` | 跑 `validate-update-impact` |
+| 复合创建 | Web 创建无 save-precheck；提交前做人工摘要和本地 JSON/引用检查 |
+| 复合编辑 | 修改 `formula` 或 `filter` 时跑 `validate-update-impact` |
+| 衍生创建 | Web 创建无 save-precheck；提交前做人工摘要和本地 JSON/引用检查 |
+| 衍生编辑 | 修改 `baseMetricId`、`deriveSetting` 或 `filter` 时跑 `validate-update-impact` |
+| 删除指标 | 先 `GET /api/metric-platform/metrics/{id}/validate-delete-impact`；有下游资源时阻断删除 |
+
+## 命令能力边界
+
+- `guancli metric create` 和 `guancli metric edit` 当前是原子指标专用命令。
+- 复合指标和衍生指标创建/编辑使用 `guancli fetch POST ... --stdin < payload.json`。
+- 指标删除使用 `guancli metric delete <metric_id>`；默认只做影响校验，追加 `--confirm` 才会在无下游依赖时提交删除。