@wubaoqi/guancopilot 0.0.0-stage → 0.2.0

package/skills-bundle/guanmetric/references/metric-api-contracts.md

@@ -0,0 +1,436 @@
+# 指标创建、编辑、详情和列表 API 契约
+
+本文给 Agent 提供可直接参考的真实结构。完整脱敏样例见
+`metric-api-contract-examples.json`，机器可读约束见
+`metric-api-contract.schema.json`。
+
+## 证据与适用范围
+
+- 2026-09-21 在 test71 使用 `guancli`/`guanmetric` 做了只读查询和隔离测试资源实测。
+- 复合/衍生专用创建、编辑、影响校验和写后回读已使用账号密码认证实测；本轮未使用 PAT 做有权、无权和资源不存在对照，PAT 兼容性仍标记为未验证。
+- 复合指标和六种衍生配置均完成创建；复合、衍生完成原地编辑、详情回读和列表查询；创建/编辑响应均为 `{result:"ok",response:{id}}`。
+- 原子字段模式和表达式模式的详情结构来自真实指标回读；写请求字段同时对照当前 BI 写 DTO 和 Web 对应语义。
+- test71 当前原子创建接口对非空 `applicableDims` 仍返回 `5001 适用维度无效`，因此本文不把该次失败称为成功实测。请求结构仍是当前后端 DTO 与 CLI 的正式契约；在目标环境提交前必须先 dry-run，并以真实创建和回读为最终结论。
+- 所有样例均已脱敏。字段结构、空值形态和读写差异保留；样例 ID 不能直接拿去调用真实环境。
+- 响应允许后端新增字段。Schema 对响应使用 `additionalProperties: true`，Agent 不应因为出现新字段而拒绝解析。
+
+## 接口矩阵
+
+| 操作 | 方法与路径 | 请求 | 成功响应 |
+| --- | --- | --- | --- |
+| 创建原子 | `POST /api/metric-platform/metrics/atomic-metrics` | `CreateAtomicMetricRO` | mutation success |
+| 编辑原子 | `POST /api/metric-platform/metrics/atomic-metrics/{id}` | `UpdateAtomicMetricRO` | mutation success |
+| 创建复合 | `POST /api/metric-platform/metrics/composite-metrics` | `CreateCompositeMetricRO` | mutation success |
+| 编辑复合 | `POST /api/metric-platform/metrics/composite-metrics/{id}` | `UpdateCompositeMetricRO` | mutation success |
+| 创建衍生 | `POST /api/metric-platform/metrics/derived-metrics` | `CreateDerivedMetricRO` | mutation success |
+| 编辑衍生 | `POST /api/metric-platform/metrics/derived-metrics/{id}` | `UpdateDerivedMetricRO` | mutation success |
+| 指标详情 | `GET /api/metric-platform/metrics/{id}` | 无；草稿加 `?fromDraft=true` | detail response |
+| 指标列表 | `POST /api/metric-platform/metrics` | list request | list response |
+
+以上是客户端实际路径。BI 后端路由是去掉 `/api` 后的同路径。写接口分别需要
+`METRIC_PLATFORM` 的 `CREATE` 或 `UPDATE` 权限，详情和列表需要 `READ` 权限。
+
+## 原始响应与 CLI canonical 输出
+
+本文描述的是 `--raw` 或 `guanmetric fetch` 看到的后端原始 envelope：
+
+```json
+{
+  "result": "ok",
+  "response": {}
+}
+```
+
+`guancli metric get/search -f json` 是供普通机器发现使用的 canonical 输出，外层通常是
+`schemaVersion/command/resultMode/rowCount/data`。canonical 输出会主动省略部分写入字段，
+例如 `formula`、`formulaField`、`deriveSetting`，所以不能用它重建编辑请求。需要编辑时用
+`--raw` 读取完整详情，再按本文映射成写模型。
+
+`guanmetric create/edit` 的人类输出可能只展示解包后的 `{"id":"..."}`；这不改变底层 API
+响应契约。
+
+## 创建和编辑成功响应
+
+三种指标的创建和编辑共用同一响应：
+
+```json
+{
+  "result": "ok",
+  "response": {
+    "id": "metric_example_id"
+  }
+}
+```
+
+只收到 HTTP 2xx 但 `result` 不是 `ok`，或 `response.id` 缺失，不能认为创建/编辑成功。
+创建后必须详情回读；上线指标还必须按 `metric-flow.md` 验证状态、权限和查询可用性。
+
+## 创建与编辑的公共字段
+
+| 字段 | 创建 | 编辑 | 类型 | 说明 |
+| --- | --- | --- | --- | --- |
+| `projectId` | 必填 | 必填 | string | 指标主题 ID |
+| `subType` | 必填 | 必填 | enum | `ATOMIC/COMPOSITE/DERIVED` |
+| `name` | 必填 | 必填 | string | 指标名称 |
+| `engName` | 可选 | 可选 | string | 英文名 |
+| `desc` | 必填 | 必填 | string | 业务口径 |
+| `format` | 可选 | 可选 | object | 数字格式 |
+| `filter` | 可选 | 可选 | object/null | WebFilterData |
+| `bizAttrs` | 可选 | 可选 | array | 业务属性 `{id,values}` |
+| `dynamicParameters` | 可选 | 可选 | array | 动态参数默认值 |
+| `publish` | 必填 | 必填 | boolean | `false` 草稿，`true` 上线/进入审批 |
+| `bizMetricId` | 可选 | 可选 | string | 关联业务指标 |
+| `parentDirId` | 必填 | 不传 | string | 创建位置；编辑不会通过定义接口移动目录 |
+| `businessOwner` | 必填 | 不传 | string | 创建负责人；详情中变成用户对象 |
+
+编辑接口接收完整更新写模型，不是 JSON Merge Patch。`guanmetric edit` 可以让用户提供 patch，
+但 CLI 必须先把详情读模型规范化成完整写模型，再合并 patch。
+
+## 原子指标
+
+### 字段来源模式
+
+写模型必须同时提供 `fdId` 和 `aggrType`：
+
+```json
+{
+  "projectId": "project_demo",
+  "subType": "ATOMIC",
+  "dsId": "ds_orders",
+  "name": "销售额",
+  "fdId": "fd_amount",
+  "aggrType": "SUM",
+  "applicableDims": ["fd_order_date", "fd_region"],
+  "timeDim": "fd_order_date",
+  "desc": "订单销售额合计",
+  "parentDirId": "dir_demo",
+  "businessOwner": "user_owner",
+  "publish": false
+}
+```
+
+详情不返回顶层 `fdId`，而是返回：
+
+```json
+{
+  "result": "ok",
+  "response": {
+    "subType": "ATOMIC",
+    "dsInfo": {"dsId": "ds_orders", "name": "订单明细"},
+    "fdInfos": [
+      {"fdId": "fd_amount", "name": "订单金额", "fdType": "DOUBLE", "metaType": "METRIC"}
+    ],
+    "aggrType": "SUM",
+    "applicableDims": [
+      {"fdId": "fd_region", "name": "区域", "fdType": "STRING", "metaType": "DIM"}
+    ],
+    "timeDim": {"fdId": "fd_order_date", "name": "订单日期", "fdType": "DATE"}
+  }
+}
+```
+
+### 表达式模式
+
+表达式模式只传 `formulaField.fdFormula`，不能再传 `fdId/aggrType`：
+
+```json
+{
+  "projectId": "project_demo",
+  "subType": "ATOMIC",
+  "dsId": "ds_orders",
+  "name": "含税销售额",
+  "formulaField": {
+    "fdFormula": "SUM([fd_amount]) + SUM([fd_tax])"
+  },
+  "applicableDims": ["fd_order_date", "fd_region"],
+  "timeDim": "fd_order_date",
+  "desc": "订单金额与税额之和",
+  "parentDirId": "dir_demo",
+  "businessOwner": "user_owner",
+  "publish": false
+}
+```
+
+真实详情会同时返回表达式和表达式引用的 `fdInfos`：
+
+```json
+{
+  "formulaField": {
+    "fdFormula": "SUM([fd_amount]) + SUM([fd_tax])",
+    "fdType": "DOUBLE"
+  },
+  "fdInfos": [
+    {"fdId": "fd_amount", "name": "订单金额"},
+    {"fdId": "fd_tax", "name": "税额"}
+  ],
+  "aggrType": null
+}
+```
+
+这里的 `fdInfos` 只是读模型的解析结果，不能把 `fdInfos[0]` 错当成表达式指标的 `fdId`。
+判断顺序必须是：有非空 `formulaField.fdFormula` 就保留表达式模式；否则才从
+`fdInfos[0].fdId` 恢复字段来源模式。
+
+## 复合指标
+
+请求核心字段：
+
+```json
+{
+  "projectId": "project_demo",
+  "subType": "COMPOSITE",
+  "name": "客单价",
+  "formula": "[metric_sales] / [metric_order_count]",
+  "useExpressionMetricCommonDims": true,
+  "applicableDims": ["fd_order_date", "fd_region"],
+  "timeDim": "fd_order_date",
+  "desc": "销售额除以订单数",
+  "parentDirId": "dir_demo",
+  "businessOwner": "user_owner",
+  "publish": false
+}
+```
+
+详情保留 `formula`，并增加 `referencedMetrics`；`applicableDims` 和 `timeDim` 都变成字段对象：
+
+```json
+{
+  "formula": "[metric_sales] / [metric_order_count]",
+  "referencedMetrics": [
+    {
+      "id": "metric_sales",
+      "name": "销售额",
+      "subType": "ATOMIC",
+      "status": "PUBLISHED",
+      "timeDim": {"fdId": "fd_order_date"}
+    }
+  ],
+  "applicableDims": [
+    {"fdId": "fd_region", "name": "区域", "fdType": "STRING", "metaType": "DIM"}
+  ],
+  "timeDim": {"fdId": "fd_order_date", "name": "订单日期"}
+}
+```
+
+## 衍生指标
+
+普通衍生请求必须有 `baseMetricId`；组合衍生不传 `baseMetricId`，在
+`deriveSetting.formula` 中引用指标。详情把 `baseMetricId` 展开为 `baseMetric` 对象；组合衍生
+还返回 `referencedMetrics`。
+
+六种已实测配置如下，完整请求和详情见 examples JSON。
+
+### 对比 `COMPARATIVE`
+
+```json
+{
+  "deriveType": "ORDINARY",
+  "advType": "COMPARATIVE",
+  "advValue": {
+    "advType": "COMPARATIVE",
+    "dateFdId": "fd_order_date_month",
+    "valueType": "VALUE",
+    "offset": 1,
+    "offsetType": "MONTH",
+    "granularity": "MONTH",
+    "window": {"offset": 0}
+  }
+}
+```
+
+### 最近 N `RECENT_X`
+
+```json
+{
+  "deriveType": "ORDINARY",
+  "advType": "RECENT_X",
+  "advValue": {
+    "advType": "RECENT_X",
+    "granularity": "DAY",
+    "baselineOffset": [6, 0],
+    "baseline": "DATE_RANGE_PARAM_RIGHT",
+    "aggrType": "SUM",
+    "includeCurrentValue": true
+  }
+}
+```
+
+### 累计 `XTD`
+
+```json
+{
+  "deriveType": "ORDINARY",
+  "advType": "XTD",
+  "advValue": {
+    "advType": "XTD",
+    "granularity": "MONTH",
+    "baseline": "DATE_RANGE_PARAM_RIGHT",
+    "includeCurrentValue": true
+  }
+}
+```
+
+### 期末值 `LAST`
+
+```json
+{
+  "deriveType": "ORDINARY",
+  "advType": "LAST",
+  "advValue": {
+    "advType": "LAST",
+    "dateFdId": "fd_order_date",
+    "calculationMode": "LAST_NON_EMPTY"
+  }
+}
+```
+
+部分历史详情没有 `calculationMode`。编辑时应保留详情里的真实值；新建时按用户选择传
+`NATURAL_LAST_DAY` 或 `LAST_NON_EMPTY`，不要从字段名猜测。
+
+### 业务限定 `BIZ_CONDITION`
+
+```json
+{
+  "deriveSetting": {
+    "deriveType": "ORDINARY",
+    "advType": "BIZ_CONDITION",
+    "advValue": {"advType": "BIZ_CONDITION"}
+  },
+  "filter": {
+    "type": "condition",
+    "value": {
+      "dsId": "ds_orders",
+      "fdId": "fd_region",
+      "name": "区域",
+      "fdType": "STRING",
+      "metaType": "DIM",
+      "filterType": "IN",
+      "filterValue": ["华东"]
+    }
+  }
+}
+```
+
+真实回读会补 `filter.not=false`。筛选字段必须属于基础指标的 `applicableDims`。
+
+### 组合衍生 `deriveType=COMPOSITE`
+
+```json
+{
+  "deriveType": "COMPOSITE",
+  "formula": "[metric_sales_recent_7d] + [metric_sales_mtd]"
+}
+```
+
+## 详情公共结构
+
+三类详情至少包含下面的公共语义；字段是否出现受类型、状态、权限和版本影响：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | string | 指标 ID |
+| `projectId/projectName` | string | 主题 |
+| `parentDirId/dirPath` | string/array | 所属目录 |
+| `subType` | enum | 也可能读到只读类型 `SHORTCUT` |
+| `uniformResourceType` | string | `METRIC_ATOMIC/COMPOSITE/DERIVED` 等 |
+| `status` | string | 常见 `PUBLISHED/UNPUBLISHED` |
+| `name/engName/desc` | string | 基础属性 |
+| `businessOwner/creator` | object | 用户读模型，不是写请求中的用户 ID |
+| `applicableDims` | field[] | 字段对象数组，不是 ID 数组 |
+| `timeDim` | field/null | 字段对象，不是 ID |
+| `format/filter/bizAttrs` | object/array/null | 可选定义 |
+| `canManage/canUse` | boolean | 当前用户权限 |
+| `hasDraft` | boolean/null | 草稿标识，部分衍生详情可能缺失或为 null |
+| `statisticsData` | object | 引用、浏览统计，只读 |
+| `metricChartConfig` | object | 图表配置，只读 |
+| `ctime/utime` | string | 时间，只读 |
+
+`SHORTCUT` 可能出现在列表和详情，但当前 skill 没有它的创建/编辑契约；遇到时只能读取，
+不要伪造写请求。
+
+## 列表请求与响应
+
+列表接口是 POST，请求示例：
+
+```json
+{
+  "projectId": "project_demo",
+  "dirId": "dir_demo",
+  "status": "PUBLISHED",
+  "nameLike": "销售",
+  "subTypes": "ATOMIC,COMPOSITE,DERIVED",
+  "orderBy": "UTIME_DESC",
+  "offset": 0,
+  "limit": 20
+}
+```
+
+关键点：`subTypes` 是逗号分隔字符串，不是数组。`creator`、`businessOwner` 才是字符串数组。
+分页启用时 `limit` 最大 100。
+
+真实响应外形：
+
+```json
+{
+  "result": "ok",
+  "response": {
+    "contents": [
+      {
+        "id": "metric_atomic_sales",
+        "projectId": "project_demo",
+        "status": "PUBLISHED",
+        "subType": "ATOMIC",
+        "name": "销售额",
+        "desc": "订单销售额合计",
+        "dirId": "dir_demo",
+        "businessOwner": {"uId": "user_owner", "name": "指标负责人"},
+        "creator": {"uId": "user_creator", "name": "创建人"},
+        "canManage": true,
+        "canUse": true,
+        "timeDim": {"fdId": "fd_order_date"},
+        "hasDraft": false,
+        "favorite": false,
+        "approvalStatus": null
+      }
+    ],
+    "count": 1,
+    "dirPath": [{"dirId": "dir_demo", "dirName": "销售指标"}]
+  }
+}
+```
+
+不同查询路径/版本可能同时返回 `limit/returnedCount`，也可能返回 `dirPath`。解析器应要求
+`contents/count`，其余作为可选字段。
+
+## 读模型到更新写模型映射
+
+| 详情读模型 | 更新写模型 | 规则 |
+| --- | --- | --- |
+| `dsInfo.dsId` | `dsId` | 原子指标 |
+| `fdInfos[0].fdId` | `fdId` | 仅字段来源模式 |
+| `aggrType` | `aggrType` | 与 `fdId` 同时存在 |
+| `formulaField.fdFormula` | `formulaField.fdFormula` | 表达式模式优先，丢弃读模型 `fdType` |
+| `applicableDims[].fdId` | `applicableDims[]` | 对象数组压成 ID 数组 |
+| `timeDim.fdId` | `timeDim` | 对象压成 ID；null/缺失则不传 |
+| `businessOwner.uId` | 无 | 更新 DTO 不接收负责人 |
+| `baseMetric.id` | `baseMetricId` | 普通衍生；组合衍生不传 |
+| `formula` | `formula` | 复合指标原样保留 |
+| `deriveSetting` | `deriveSetting` | 深拷贝并保留变体字段 |
+| `filter/format/bizAttrs` | 同名字段 | 保留业务定义 |
+
+必须剔除只读键，包括但不限于：`id`、`domId`、`projectName`、`parentDirId`、`dirPath`、
+`businessOwner`、`creator`、`ctime`、`utime`、`canManage`、`canUse`、`statisticsData`、
+`hasDraft`、`metricChartConfig`、`uniformResourceType`、`sourceDsIds`、`publicDimensionMap`、
+`referencedMetrics`、`baseMetric`、`fdInfos`、`dsInfo`、`isLastSupported`。
+
+不要维护“详情减掉若干字段后直接提交”的黑名单算法；正确做法是按对应 Update DTO 白名单显式构造。
+
+## Agent 使用顺序
+
+1. 先判断 `subType` 和具体模式/衍生变体。
+2. 从 examples JSON 取同类型样例，只替换业务值和真实 ID。
+3. 用 schema 检查字段类型，并按类型文档做业务校验。
+4. 创建/编辑先 dry-run；编辑必须详情回读后显式构造更新写模型。
+5. 提交后要求 `result=ok` 且 `response.id` 非空。
+6. 用详情回读验证定义；列表只用于发现和汇总，不能替代详情。
+7. 要求“可用”时继续执行 `metric-flow.md` 的状态、权限和查询验收。

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

@@ -0,0 +1,238 @@
+# 原子指标创建与编辑
+
+原子指标用于在单个数据集字段或数据集字段表达式上定义指标口径，例如“订购金额 = SUM(订单金额)”。
+
+创建/编辑请求、真实详情响应和读写映射见 `metric-api-contracts.md`；机器样例见
+`metric-api-contract-examples.json`。不要根据详情响应猜测写模型。
+
+## 触发场景
+
+- 用户说“创建原子指标”“基于数据集建指标”“用某个字段求和/计数/平均”。
+- 用户给出数据集、字段、聚合方式。
+- 用户要编辑一个 `subType=ATOMIC` 的指标。
+
+## 创建必填信息
+
+| 字段 | 中文 | 说明 |
+| --- | --- | --- |
+| `projectId` | 主题 ID | 指标所属主题 |
+| `subType` | 指标类型 | 固定 `ATOMIC` |
+| `dsId` | 数据集 ID | 指标来源数据集 |
+| `name` | 指标名称 | 最长 50 |
+| `desc` | 业务口径 | 最长 1000 |
+| `applicableDims` | 适用维度 | 数据集字段 ID 数组，不能为空 |
+| `parentDirId` | 保存至/所属文件夹 | 指标目录 ID |
+| `businessOwner` | 责任人 | 用户 ID |
+| `publish` | 保存方式 | `true` 上线，`false` 草稿 |
+
+计算方式二选一：
+
+| 模式 | 必填字段 | 说明 |
+| --- | --- | --- |
+| 来源字段 + 聚合方式 | `fdId` + `aggrType` | 最常见；标准 Excel 填 `来源字段` 和 `聚合方式`；来源字段是数据集字段 ID |
+| 表达式 | `formulaField.fdFormula` | 标准 Excel 填 `字段表达式`；例如 `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
+guanmetric create --file /tmp/atomic_metric.json --dry-run
+```
+
+4. 按 `metric-common-fields.md` 向用户摘要并确认。
+5. 如果 `publish=true`，先跑 save-precheck：
+
+```bash
+guanmetric fetch POST /api/metric-platform/metrics/atomic-metrics/save-precheck --stdin < /tmp/atomic_metric.json
+```
+
+6. 如果返回 `conflicts` 且非空，展示冲突指标、冲突口径、适用维度差异，等待用户二次确认。
+7. 校验通过或二次确认后提交：
+
+```bash
+guanmetric create --file /tmp/atomic_metric.json -f json
+```
+
+8. 响应返回指标 ID 后回读：
+
+```bash
+guancli metric get <metric_id> --brief
+```
+
+## 编辑步骤
+
+编辑原子指标时复用 Web 顺序：必要时先口径冲突校验，再影响校验，最后提交。
+
+默认编辑模式接收 patch。CLI 会先读取指标详情，将详情读模型规范化为更新写模型（例如
+`fdInfos[0].fdId -> fdId`、维度对象数组 -> 字段 ID 数组），剔除只读字段，再合并 patch。
+提交前必须仍保留一种完整取数方式：`fdId + aggrType` 或
+`formulaField.fdFormula`。无法安全恢复取数字段时直接拒绝提交，不能用缺少取数方式的请求继续保存。
+
+原子指标 `edit --replace` 已停用。编辑必须提交 patch，由命令优先读取草稿详情；仅当详情接口以结构化业务状态明确表示草稿不存在时才回退正式详情，再按 Update DTO 白名单构造完整请求。不得把 `guancli metric get --raw` 的详情响应直接回写。
+patch 本身也受同一 Update DTO 白名单约束：`id/status/fdInfos/canUse` 等读模型字段会在读取详情和发请求前被拒绝，`subType` 不能改成非 `ATOMIC`。当 filter 只给出 `fdId` 时，规范化必须使用本次实际选中的草稿或正式详情中的 `applicableDims` 元数据，不能重新读取正式版本覆盖草稿上下文。
+
+1. 读取当前详情：
+
+```bash
+guancli metric get <metric_id> --raw
+```
+
+2. 生成 patch 或完整 payload，先 dry-run：
+
+```bash
+guanmetric edit <metric_id> --file /tmp/atomic_metric_update.json --dry-run
+```
+
+3. 如果 `publish=true`，调用 save-precheck。编辑态请求体需要带 `metricId`：
+
+```bash
+guanmetric 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
+guanmetric 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
+guanmetric edit <metric_id> --file /tmp/atomic_metric_update.json -f json
+```
+
+编辑载荷和公式/格式复制使用 `--raw` 的后端详情，成功后从后端 `response` 读取字段；不能把后端响应当成 canonical envelope。普通机器发现使用 `-f json` 并从 `data` 取值，canonical 详情不承诺完整编辑字段。