@guandata/guancli 1.0.38 → 1.0.40

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

@@ -1,225 +0,0 @@
-# 原子指标创建与编辑
-
-原子指标用于在单个数据集字段或数据集字段表达式上定义指标口径，例如“订购金额 = SUM(订单金额)”。
-
-## 触发场景
-
-- 用户说“创建原子指标”“基于数据集建指标”“用某个字段求和/计数/平均”。
-- 用户给出数据集、字段、聚合方式。
-- 用户要编辑一个 `subType=ATOMIC` 的指标。
-
-## 创建必填信息
-
-| 字段 | 中文 | 说明 |
-| --- | --- | --- |
-| `projectId` | 主题 ID | 指标所属主题 |
-| `subType` | 指标类型 | 固定 `ATOMIC` |
-| `dsId` | 数据集 ID | 指标来源数据集 |
-| `name` | 指标名称 | 最长 50 |
-| `desc` | 业务口径 | 最长 1000 |
-| `applicableDims` | 适用维度 | 数据集字段 ID 数组，不能为空 |
-| `parentDirId` | 保存至/所属文件夹 | 指标目录 ID |
-| `businessOwner` | 责任人 | 用户 ID |
-| `publish` | 保存方式 | `true` 上线，`false` 草稿 |
-
-计算方式二选一：
-
-| 模式 | 必填字段 | 说明 |
-| --- | --- | --- |
-| 来源字段 + 聚合方式 | `fdId` + `aggrType` | 最常见；来源字段是数据集字段 ID |
-| 表达式 | `formulaField.fdFormula` | 例如 `SUM([fd_amount]) + SUM([fd_tax])`；不要同时传 `fdId/aggrType`；支持范围见 `metric-expression-rules.md` |
-
-## 原子专属可选字段
-
-| 字段 | 中文 | 说明 |
-| --- | --- | --- |
-| `timeDim` | 时间维度 | 如果适用维度中包含时间字段，优先让用户指定一个时间维度字段 ID |
-| `sourceMetricId` | 来源指标 ID | 复制/快捷等高级场景才传 |
-
-通用可选字段见 `metric-common-fields.md`。
-
-## 聚合方式
-
-| `aggrType` | 中文 |
-| --- | --- |
-| `SUM` | 求和 |
-| `MIN` | 最小值 |
-| `MAX` | 最大值 |
-| `AVG` | 平均值 |
-| `CNT` | 计数 |
-| `CNT_DISTINCT` | 去重计数 |
-| `NUL` | 无处理 |
-
-字段判断：
-
-- 用户只给字段中文名时，先用 `guancli ds get <dsId> --brief` 查字段和 `fdId`。
-- 来源字段是维度字段时，常用计数、去重计数、最大值、最小值、无处理。
-- 来源字段是指标/数值字段时，常用求和、平均值、最大值、最小值、计数、去重计数。
-
-## 表达式限制
-
-当用户选择“使用表达式”时，先读取 `metric-expression-rules.md`。默认只生成当前前后端明确支持的聚合表达式形态：
-
-- `SUM([fd_id])`、`COUNT([fd_id])`
-- 多个聚合项加减：`SUM([fd_a]) - SUM([fd_b])`
-- 条件聚合：`SUM(CASE WHEN ... THEN ... ELSE ... END)`
-
-不要把 `AVG/MAX/MIN/FIRST/LAST/ANY_VALUE` 主动写进 `formulaField.fdFormula`；如果用户要平均值、最大值、最小值，优先走“来源字段 + `aggrType`”。表达式中字段必须写 `[fdId]`，不要提交字段中文名。
-
-### 计算表达式确认
-
-遇到计算表达式时，不要直接替用户决定创建原子表达式还是复合指标。先说明两种方案并询问：
-
-- 原子表达式：直接在当前数据集字段上生成 `formulaField.fdFormula`。
-- 复合指标：先创建或复用表达式中的基础原子指标，再用 `[metricId]` 公式创建复合指标。
-
-用户选择复合指标后，再拆解基础度量。例如 `SUM([attributed_sales_fd]) / SUM([spend_amount_fd])` 可先创建或复用“归因销售额”“广告花费”两个原子指标，再创建复合指标：
-
-```text
-[metric_attributed_sales] / [metric_ad_spend]
-```
-
-用户选择原子表达式，或明确要求“数据集字段表达式原子指标”时，才使用 `formulaField.fdFormula`。
-
-## 信息收集
-
-如果用户只说“帮我创建一个原子指标”，先收集：
-
-1. 指标主题和保存目录。
-2. 来源数据集和来源字段。
-3. 计算方式：来源字段 + 聚合方式，还是表达式；如果是表达式，先询问用户是否改用复合指标。用户选择原子表达式时，再按 `metric-expression-rules.md` 校验支持形态。
-4. 指标名称、业务口径、适用维度、时间维度、是否保存并上线。
-5. 数据格式：默认、数值、货币、百分比；如需指定，确认小数位、千分位、货币符号/前后缀、数量级单位、百分比是否除以 100。
-6. 责任人是否用当前登录用户。
-7. 指标业务属性中启用且必填的 `bizAttrs`。
-
-## JSON 模板：字段聚合
-
-```json
-{
-  "projectId": "<metric_project_id>",
-  "subType": "ATOMIC",
-  "dsId": "<ds_id>",
-  "name": "订购金额",
-  "engName": "order_amount",
-  "fdId": "<source_fd_id>",
-  "aggrType": "SUM",
-  "applicableDims": ["<dim_fd_id_1>", "<dim_fd_id_2>"],
-  "timeDim": "<time_dim_fd_id>",
-  "format": {
-    "formatType": "CURRENCY",
-    "decimalPlaces": 2,
-    "useThousandsSeparator": true,
-    "prefix": "￥",
-    "prefixUnit": null,
-    "showPrefixUnit": true,
-    "suffix": ""
-  },
-  "desc": "统计订单明细中的订购金额总和，用于分析销售规模。",
-  "parentDirId": "<metric_dir_id>",
-  "businessOwner": "<user_id>",
-  "publish": false
-}
-```
-
-没有时间维度时删除 `timeDim`；没有英文名称时删除 `engName`；未指定数据格式时删除 `format` 或传 `{}`。
-
-## JSON 模板：表达式
-
-```json
-{
-  "projectId": "<metric_project_id>",
-  "subType": "ATOMIC",
-  "dsId": "<ds_id>",
-  "name": "含税销售额",
-  "formulaField": {
-    "fdFormula": "SUM([fd_amount]) + SUM([fd_tax])"
-  },
-  "applicableDims": ["<dim_fd_id_1>", "<dim_fd_id_2>"],
-  "format": {
-    "formatType": "NUMBER",
-    "decimalPlaces": 2,
-    "useThousandsSeparator": true,
-    "prefixUnit": null,
-    "showPrefixUnit": true,
-    "prefix": "",
-    "suffix": ""
-  },
-  "desc": "销售金额与税额之和。",
-  "parentDirId": "<metric_dir_id>",
-  "businessOwner": "<user_id>",
-  "publish": false
-}
-```
-
-## 创建步骤
-
-1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、来源数据集/字段、聚合方式或表达式、适用维度/时间维度、格式、业务属性和保存方式。
-2. 用户确认计划后，生成 `/tmp/atomic_metric.json`。
-3. 先 dry-run：
-
-```bash
-guancli metric create --file /tmp/atomic_metric.json --dry-run
-```
-
-4. 按 `metric-common-fields.md` 向用户摘要并确认。
-5. 如果 `publish=true`，先跑 save-precheck：
-
-```bash
-guancli fetch POST /api/metric-platform/metrics/atomic-metrics/save-precheck --stdin < /tmp/atomic_metric.json
-```
-
-6. 如果返回 `conflicts` 且非空，展示冲突指标、冲突口径、适用维度差异，等待用户二次确认。
-7. 校验通过或二次确认后提交：
-
-```bash
-guancli metric create --file /tmp/atomic_metric.json -f json
-```
-
-8. 响应返回指标 ID 后回读：
-
-```bash
-guancli metric get <metric_id> --brief
-```
-
-## 编辑步骤
-
-编辑原子指标时复用 Web 顺序：必要时先口径冲突校验，再影响校验，最后提交。
-
-1. 读取当前详情：
-
-```bash
-guancli metric get <metric_id> -f json
-```
-
-2. 生成 patch 或完整 payload，先 dry-run：
-
-```bash
-guancli metric edit <metric_id> --file /tmp/atomic_metric_update.json --dry-run
-```
-
-3. 如果 `publish=true`，调用 save-precheck。编辑态请求体需要带 `metricId`：
-
-```bash
-guancli fetch POST /api/metric-platform/metrics/atomic-metrics/save-precheck --stdin < /tmp/atomic_metric_update_precheck.json
-```
-
-其中 precheck JSON 等于编辑 payload 加：
-
-```json
-{ "metricId": "<metric_id>" }
-```
-
-4. 如果存在 `conflicts`，展示后等待二次确认。
-5. 调用编辑影响校验：
-
-```bash
-guancli fetch POST /api/metric-platform/metrics/atomic-metrics/<metric_id>/validate-update-impact --stdin < /tmp/atomic_metric_update.json
-```
-
-6. 如果返回 `hasChanged=true` 且 `affectedMetrics` 或 `affectedCards` 非空，展示影响并等待二次确认。
-7. 提交真实编辑：
-
-```bash
-guancli metric edit <metric_id> --file /tmp/atomic_metric_update.json -f json
-```

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

@@ -1,168 +0,0 @@
-# 指标通用配置
-
-本文记录原子指标、复合指标、衍生指标共享的写操作规则、通用字段和业务属性处理方式。处理任一指标创建/编辑任务时，都应先读取本文，再读取对应类型文档。
-
-## 环境与查询
-
-- 默认使用用户当前已登录环境，不询问“创建到哪个 profile”。可先执行 `guancli auth status` 确认登录态。
-- 只有用户明确指定其它环境时，才统一追加 `--profile <profile>`。
-- 用户只给中文名称时，先查询并展示候选；查不到或有多个候选再向用户确认。
-- 常用查询：
-  - 指标主题：`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`
-
-## 通用字段
-
-| 字段 | 中文 | 适用范围 | 说明 |
-| --- | --- | --- | --- |
-| `projectId` | 主题 ID | 创建/编辑 | 指标所属主题 |
-| `subType` | 指标类型 | 创建/编辑 | `ATOMIC`、`COMPOSITE`、`DERIVED` |
-| `name` | 指标名称 | 创建/编辑 | 最长 50；仅中文、字母、数字、下划线 |
-| `engName` | 英文名称 | 可选 | 最长 50；仅字母、数字、下划线 |
-| `desc` | 业务口径 | 创建/编辑 | 最长 1000；必须能解释业务含义 |
-| `format` | 数据格式 | 可选 | 指标数值展示格式；省略或传 `{}` 表示默认格式 |
-| `parentDirId` | 保存至/所属文件夹 | 创建必填 | 指标目录 ID |
-| `businessOwner` | 责任人 | 创建必填 | 用户 ID，默认可用当前登录用户 |
-| `publish` | 保存方式 | 创建/编辑 | `true` 保存并上线；`false` 保存为草稿 |
-| `bizMetricId` | 关联业务字典 ID | 可选 | 关联后业务口径/业务属性通常会同步 |
-| `bizAttrs` | 业务属性 | 条件必填 | 由环境中的指标属性配置决定 |
-| `filter` | 业务限定/筛选 | 可选或条件必填 | 业务限定衍生指标必填 |
-| `dynamicParameters` | 动态参数默认值 | 可选 | 表达式或最近 N 配置引用动态参数时使用 |
-
-## 数据格式 `format`
-
-`format` 是指标数值的展示格式，创建和编辑原子指标、复合指标、衍生指标时都可设置。保存指标时写入 Web 表单使用的 UI 配置，不要写转换后的 d3 `specifier`、Excel format 或预览接口返回值。
-
-省略 `format` 或传 `{}` 表示使用默认格式。用户没有明确要求时，不要为了补全字段强行设置格式；用户提到“保留两位小数”“显示百分比”“人民币”“万元”“不要千分位”“加后缀”等，再按下面字段生成。
-
-| 字段 | 中文 | 说明 |
-| --- | --- | --- |
-| `formatType` | 格式类型 | `NUMBER` 数值、`CURRENCY` 货币、`PERCENTAGE` 百分比、`ADVANCED` 高级自定义 |
-| `decimalPlaces` | 小数位数 | `null` 表示 0 位；也可传 `1` 到 `15` |
-| `useThousandsSeparator` | 是否使用千分位 | `true/false` |
-| `prefix` | 前缀/货币符号 | 货币常用 `￥`、`$`、`€`、`£`；后端兼容旧字段 `currencySymbol`，新建优先写 `prefix` |
-| `suffix` | 后缀 | 如 `元`、`人`、`单`、`次`；没有则省略或传空字符串 |
-| `prefixUnit` | 数量级单位 | `null` 无，`K`、`M`、`万`、`亿` 或 `auto` 自动 |
-| `showPrefixUnit` | 是否展示数量级单位 | 数值/货币格式可用；`prefixUnit=auto` 时应为 `true` |
-| `divideDataBy` | 百分比是否除以 100 | 百分比格式可用；`1` 适合底层值是比例小数如 `0.85`，`100` 适合底层值已是百分数如 `85` |
-| `customFormat` | 高级自定义格式 | `formatType=ADVANCED` 时使用；除非用户给出现成格式串，否则不要主动生成 |
-| `suffixSizePercent` | 后缀字号比例 | 部分卡片展示场景使用，指标创建/编辑通常不需要 |
-
-常用模板：
-
-```jsonc
-// 默认格式：省略 format 或传 {}
-"format": {}
-
-// 数值：千分位，保留 2 位小数
-"format": {
-  "formatType": "NUMBER",
-  "decimalPlaces": 2,
-  "useThousandsSeparator": true,
-  "prefixUnit": null,
-  "showPrefixUnit": true,
-  "prefix": "",
-  "suffix": ""
-}
-
-// 货币：人民币，千分位，保留 2 位小数
-"format": {
-  "formatType": "CURRENCY",
-  "decimalPlaces": 2,
-  "useThousandsSeparator": true,
-  "prefix": "￥",
-  "prefixUnit": null,
-  "showPrefixUnit": true,
-  "suffix": ""
-}
-
-// 百分比：底层值为 0.85 时展示为 85.00%
-"format": {
-  "formatType": "PERCENTAGE",
-  "decimalPlaces": 2,
-  "divideDataBy": 1,
-  "useThousandsSeparator": false,
-  "prefix": "",
-  "suffix": ""
-}
-
-// 百分比：底层值为 85 时展示为 85.00%
-"format": {
-  "formatType": "PERCENTAGE",
-  "decimalPlaces": 2,
-  "divideDataBy": 100,
-  "useThousandsSeparator": false,
-  "prefix": "",
-  "suffix": ""
-}
-
-// 数值：按万元展示
-"format": {
-  "formatType": "NUMBER",
-  "decimalPlaces": 2,
-  "useThousandsSeparator": true,
-  "prefixUnit": "万",
-  "showPrefixUnit": true,
-  "prefix": "",
-  "suffix": "元"
-}
-```
-
-## 业务属性 `bizAttrs`
-
-`bizAttrs` 是管理员配置的指标自定义业务属性，不是固定字段。创建或编辑指标前读取当前环境配置：
-
-```bash
-guancli fetch GET /api/metric-attr-config
-```
-
-响应关键字段：
-
-| 字段 | 中文 | 说明 |
-| --- | --- | --- |
-| `id` | 属性 ID | 写入 `bizAttrs[].id` |
-| `name` | 属性名称 | 用于向用户提问 |
-| `description` | 属性描述 | 可作为输入提示 |
-| `valueType` | 属性值类型 | `ENUM_SINGLE`、`ENUM_MULTIPLE`、`TEXT`、`TEXT_AREA` |
-| `defaultValue` | 默认值 | 用户未指定且允许默认时可采用 |
-| `optionValue` | 枚举选项 | 枚举单选/多选必须从这里选择 |
-| `required` | 是否必填 | `true` 且 `enabled=true` 时必须收集 |
-| `enabled` | 是否启用 | 只处理启用的属性 |
-
-处理规则：
-
-- 只展示和写入 `enabled=true` 的属性；其中 `required=true` 是必填项。
-- `ENUM_SINGLE`：`values` 只能有一个值，且必须来自 `optionValue`。
-- `ENUM_MULTIPLE`：`values` 可以有多个值，且都必须来自 `optionValue`。
-- `TEXT`：写入 `values[0]`，Web 单项最大 50 个字符。
-- `TEXT_AREA`：写入 `values[0]`，Web 单项最大 200 个字符。
-- 如果关联了业务字典 `bizMetricId`，业务口径和业务属性通常由业务字典同步；仍需确认最终 payload 中 `desc` 和 `bizAttrs` 已有值。
-
-示例：
-
-```json
-"bizAttrs": [
-  { "id": "attr_region", "values": ["华东"] },
-  { "id": "attr_tags", "values": ["销售", "核心"] },
-  { "id": "attr_owner_note", "values": ["用于经营分析月报"] }
-]
-```
-
-## 保存与确认
-
-- 先输出“指标创建计划”让用户 review；计划确认前不生成最终提交 JSON，不执行真实创建。
-- 用户确认计划后，再生成 JSON 文件并做 dry-run 或人工摘要，不直接提交。
-- 计划/摘要至少包含：当前环境、主题、目录、指标类型、名称、核心计算方式、依赖顺序、复用/新建指标、适用维度/时间维度、数据格式、业务属性、保存方式。
-- 如果适用维度中存在时间字段但时间维度为空，计划必须标记为待确认，不能继续提交。
-- 用户确认后按类型执行 save-precheck 或 validate-update-impact。
-- 如果校验返回冲突或影响下游资源，展示冲突指标、受影响指标、受影响卡片，并等待二次确认。
-- 写入成功后回读 `guancli metric get <metric_id> --brief`。
-
-## 发布状态判断
-
-- 用户说“先别上线”“保存草稿”：`publish=false`。
-- 用户说“直接上线”“发布”：`publish=true`，提交前提醒会创建或更新在线指标。
-- 不要把 `publish=true` 自动当成用户已经确认所有冲突；冲突/影响校验仍需要单独二次确认。

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

@@ -1,158 +0,0 @@
-# 复合指标创建与编辑
-
-复合指标用于通过公式组合已有指标，例如“客单价 = 销售额 / 订单数”。
-
-## 触发场景
-
-- 用户说“创建复合指标”“基于多个指标算一个指标”。
-- 用户描述的口径是已有指标之间的四则运算。
-- 用户给出数据集字段计算表达式后，确认希望先创建/复用基础原子指标，再创建复合指标。
-- 用户要编辑一个 `subType=COMPOSITE` 的指标。
-
-## 创建必填信息
-
-| 字段 | 中文 | 说明 |
-| --- | --- | --- |
-| `projectId` | 主题 ID | 指标所属主题 |
-| `subType` | 指标类型 | 固定 `COMPOSITE` |
-| `name` | 指标名称 | 最长 50 |
-| `formula` | 计算公式 | 使用已有指标 ID，形如 `[metric_sales] / [metric_orders]` |
-| `useExpressionMetricCommonDims` | 是否沿用公式指标共有维度 | Web 默认 `true` |
-| `applicableDims` | 适用维度 | 引用指标的共有维度字段 ID 数组；手动选择时不能为空 |
-| `desc` | 业务口径 | 最长 1000 |
-| `parentDirId` | 保存至/所属文件夹 | 创建时需要 |
-| `businessOwner` | 责任人 | 创建时需要 |
-| `publish` | 保存方式 | `true` 上线，`false` 草稿 |
-
-专属可选字段：
-
-| 字段 | 中文 | 说明 |
-| --- | --- | --- |
-| `timeDim` | 时间维度 | 最终适用维度中存在时间字段时选择一个 |
-
-通用可选字段见 `metric-common-fields.md`。
-
-## 公式与引用指标
-
-复合指标公式在最终 payload 中使用指标 ID，而不是指标中文名：
-
-```text
-[metric_sales_amount] / [metric_order_count]
-```
-
-处理规则：
-
-- 涉及复合指标 `formula` 时，先读取 `metric-expression-rules.md`。
-- 先用 `guancli metric search <关键词> -d <projectId> -f json` 查询公式中的指标，再用 `guancli metric get <metric_id> --brief` 核对名称、类型、状态和适用维度。
-- 如果用户只提供数据集字段级公式，先询问是否要创建复合指标。用户确认后，再识别公式里的基础度量，创建或复用基础原子指标，并把公式改写为 `[metricId]`。
-- 公式只能引用数值型指标；不要引用当前正在编辑的指标本身。
-- 公式支持 `+`、`-`、`*`、`/`、括号、数字和 `[指标ID]`；不要主动生成函数、窗口函数或 SQL 片段。
-- 公式中的 `[xxx]` 会被后端解析为上游指标 ID，并参与循环引用校验。
-- 如果用户用中文名描述公式，先转换成 ID 公式，再把“中文公式”和“ID 公式”都展示给用户确认。
-
-用户确认创建复合指标后的字段公式改写示例：
-
-| 用户口径 | 建模方式 |
-| --- | --- |
-| `SUM([销售额字段]) / COUNT([订单ID字段])` | 先建“销售额”“订单数”原子指标，再建复合指标 `[metric_sales] / [metric_order_count]` |
-| `SUM([归因销售额字段]) / SUM([广告花费字段])` | 先建“归因销售额”“广告花费”原子指标，再建复合指标 ROAS |
-| `SUM([点击量字段]) / SUM([曝光量字段])` | 先建“点击量”“曝光量”原子指标，再建复合指标 CTR |
-| `COUNT(CASE WHEN ... THEN 1 ELSE NULL END) / COUNT([ID字段])` | 先判断分子是否应建为条件计数原子指标或业务限定衍生指标，再创建复合比率指标 |
-
-## 适用维度
-
-复合指标的适用维度来自公式中引用指标的共有维度：
-
-- `useExpressionMetricCommonDims=true`：沿用表达式中指标的共用维度。需要根据引用指标详情整理共有维度；如果没有共有维度，Web 会报“计算公式来源指标无共有适用维度，请检查”。
-- `useExpressionMetricCommonDims=false`：从共有维度中手动选择 `applicableDims`，至少选择一个。
-- 如果最终适用维度中有时间类型字段，需要选择一个 `timeDim`。
-- 不要把某个上游指标独有的维度写进 `applicableDims`。
-
-## 信息收集
-
-如果用户只说“帮我创建一个复合指标”，先收集：
-
-1. 指标主题和保存目录。
-2. 公式中要引用哪些已有指标；中文名先搜索确认唯一指标。
-3. 计算公式，转换成 `[metric_id]` 形式。
-4. 是否沿用共有维度；如果手动选择，确认具体维度和时间维度。
-5. 数据格式：默认、数值、货币、百分比；如需指定，确认小数位、千分位、货币符号/前后缀、数量级单位、百分比是否除以 100。
-6. 指标名称、业务口径、是否保存并上线。
-7. 责任人和必填 `bizAttrs`。
-
-## JSON 模板
-
-```json
-{
-  "projectId": "<metric_project_id>",
-  "subType": "COMPOSITE",
-  "name": "客单价",
-  "engName": "avg_order_value",
-  "formula": "[<sales_amount_metric_id>] / [<order_count_metric_id>]",
-  "useExpressionMetricCommonDims": true,
-  "applicableDims": ["<common_dim_fd_id_1>", "<common_dim_fd_id_2>"],
-  "timeDim": "<time_dim_fd_id>",
-  "format": {
-    "formatType": "NUMBER",
-    "decimalPlaces": 2,
-    "useThousandsSeparator": true,
-    "prefixUnit": null,
-    "showPrefixUnit": true,
-    "prefix": "",
-    "suffix": ""
-  },
-  "desc": "销售金额除以订单数，用于衡量平均每笔订单贡献的销售额。",
-  "parentDirId": "<metric_dir_id>",
-  "businessOwner": "<user_id>",
-  "publish": false
-}
-```
-
-没有时间维度时删除 `timeDim`；没有英文名称时删除 `engName`；未指定数据格式时删除 `format` 或传 `{}`。如需业务属性，按 `metric-common-fields.md` 补充 `bizAttrs`。
-
-## 创建步骤
-
-`guancli metric create` 当前是原子指标专用 endpoint；复合指标创建使用 `guancli fetch`。
-
-1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、将复用或新建的基础指标、复合公式、共有适用维度/时间维度、格式、业务属性和保存方式。
-2. 用户确认计划后，生成 `/tmp/composite_metric.json`。
-3. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性。
-4. 按 `metric-common-fields.md` 向用户摘要并确认。
-5. 用户确认后，不调用原子指标 `save-precheck`；复合指标 Web 创建没有 save-precheck。
-6. 提交真实创建：
-
-```bash
-guancli fetch POST /api/metric-platform/metrics/composite-metrics --stdin < /tmp/composite_metric.json
-```
-
-7. 响应返回指标 ID 后回读：
-
-```bash
-guancli metric get <metric_id> --brief
-```
-
-## 编辑步骤
-
-复合指标没有原子指标的 save-precheck；主要校验公式或筛选变化是否影响下游指标/卡片。
-
-1. 读取当前详情：
-
-```bash
-guancli metric get <metric_id> -f json
-```
-
-2. 基于当前详情生成完整编辑 payload，例如 `/tmp/composite_metric_update.json`。至少包含 `projectId`、`subType`、`name`、`formula`、`useExpressionMetricCommonDims`、`applicableDims`、`desc`、`publish`。
-3. 如果修改了 `formula` 或 `filter`，先调用影响校验：
-
-```bash
-guancli fetch POST /api/metric-platform/metrics/composite-metrics/<metric_id>/validate-update-impact --stdin < /tmp/composite_metric_update.json
-```
-
-4. 如果返回 `hasChanged=true` 且 `affectedMetrics` 或 `affectedCards` 非空，展示受影响指标和卡片，等待用户二次确认。
-5. 提交真实编辑：
-
-```bash
-guancli fetch POST /api/metric-platform/metrics/composite-metrics/<metric_id> --stdin < /tmp/composite_metric_update.json
-```
-
-6. 保存后回读确认。

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

@@ -1,70 +0,0 @@
-# 指标删除
-
-指标删除适用于原子指标、复合指标、衍生指标和快捷引用指标。删除流程是通用的，不需要按指标类型走不同 endpoint。
-
-## Web 同款行为
-
-Web 的单指标删除弹窗会先做删除影响校验：
-
-```bash
-guancli fetch GET /api/metric-platform/metrics/<metric_id>/validate-delete-impact
-```
-
-响应结构与编辑影响校验一致：
-
-| 字段 | 中文 | 说明 |
-| --- | --- | --- |
-| `hasChanged` | 是否存在变更影响 | 删除校验通常为 `true` |
-| `affectedMetrics` | 下游指标 | 仍引用该指标的指标列表 |
-| `affectedCards` | 下游指标卡片 | 仍引用该指标的卡片列表 |
-
-如果 `affectedMetrics` 或 `affectedCards` 非空，Web 会提示“指标已被以下资源使用，暂无法删除”，只允许用户查看影响并关闭弹窗，不会提交删除。
-
-只有影响列表为空时，Web 才展示“删除后无法恢复”的确认弹窗；用户确认后调用：
-
-```bash
-guancli fetch POST /api/metric-platform/metrics/<metric_id>/delete
-```
-
-## CLI 推荐流程
-
-优先使用封装命令：
-
-```bash
-guancli metric delete <metric_id>
-```
-
-该命令默认只执行删除影响校验并输出结果，不会真实删除。输出 `deletable=true` 时，再向用户确认“删除后无法恢复”。
-
-用户明确确认后执行：
-
-```bash
-guancli metric delete <metric_id> --confirm
-```
-
-`--confirm` 也会先重新执行删除影响校验；如果此时发现下游指标或卡片，仍然阻断删除，不会调用 delete 接口。
-
-## 信息收集
-
-如果用户只说“帮我删除一个指标”，先收集或查询：
-
-1. 指标 ID；如果只给名称，先用 `guancli metric search <关键词> -f json` 查候选。
-2. 用 `guancli metric get <metric_id> --brief` 核对指标名称、类型、主题、目录和状态。
-3. 运行 `guancli metric delete <metric_id>` 查看删除影响。
-4. 如果可删除，向用户确认删除对象和“删除后无法恢复”。
-5. 用户明确确认后执行 `guancli metric delete <metric_id> --confirm`。
-
-## 影响展示
-
-影响校验返回下游资源时，需要向用户展示：
-
-- 下游指标：`id`、`name`、`subType`；若有 `linkMetricId`，说明是快捷引用关联的原始指标。
-- 下游卡片：`id`、`name`。
-
-存在下游资源时不要提供 `--confirm` 继续删除的建议；应提示用户先调整或删除引用关系。
-
-## 常见判断
-
-- 删除是不可恢复操作，即使 `publish=false` 的草稿也要明确确认。
-- 不要把“删除影响校验通过”说成已经删除成功。
-- 删除成功后可尝试 `guancli metric get <metric_id> --brief` 或重新搜索确认资源已不可见；如果后端返回已删除/不存在，视为删除完成。