@guandata/guanmetric 0.1.18 → 0.1.20

package/skills/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/guanmetric/references/metric-atomic-mutation.md

@@ -2,6 +2,9 @@
 
 原子指标用于在单个数据集字段或数据集字段表达式上定义指标口径，例如“订购金额 = SUM(订单金额)”。
 
+创建/编辑请求、真实详情响应和读写映射见 `metric-api-contracts.md`；机器样例见
+`metric-api-contract-examples.json`。不要根据详情响应猜测写模型。
+
 ## 触发场景
 
 - 用户说“创建原子指标”“基于数据集建指标”“用某个字段求和/计数/平均”。
@@ -186,6 +189,14 @@ 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

package/skills/guanmetric/references/metric-business-dictionary-api-contract-examples.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": "1.0",
+  "source": {
+    "environment": "test153",
+    "capturedAt": "2026-09-21",
+    "authentication": "account-password",
+    "note": "由隔离临时业务字典真实 CRUD 请求采集后脱敏；PAT 未验证，示例 ID 不可用于调用。"
+  },
+  "createRequest": {"name": "销售额", "desc": "订单实付金额汇总", "dirId": "business_dir_root", "bizAttrs": []},
+  "createResponse": {"result": "ok", "response": "business_dictionary_example"},
+  "updateRequest": {"name": "含税销售额", "desc": "订单含税实付金额汇总", "dirId": "business_dir_root", "bizAttrs": []},
+  "updateResponse": {"result": "ok", "response": "business_dictionary_example"},
+  "detailResponse": {
+    "result": "ok",
+    "response": {
+      "id": "business_dictionary_example",
+      "domId": "example_domain",
+      "dirId": "business_dir_root",
+      "name": "含税销售额",
+      "desc": "订单含税实付金额汇总",
+      "bizAttrs": [],
+      "creator": "user_example",
+      "creatorName": "示例用户",
+      "ctime": "2026-09-21 14:04:11",
+      "utime": "2026-09-21 14:04:30",
+      "associatedMetrics": []
+    }
+  },
+  "listResponse": {
+    "result": "ok",
+    "response": {
+      "list": [{
+        "id": "business_dictionary_example",
+        "domId": "example_domain",
+        "dirId": "business_dir_root",
+        "name": "含税销售额",
+        "desc": "订单含税实付金额汇总",
+        "bizAttrs": [],
+        "creator": "user_example",
+        "creatorName": "示例用户",
+        "ctime": "2026-09-21 14:04:11",
+        "utime": "2026-09-21 14:04:30",
+        "associatedMetrics": []
+      }],
+      "total": 1
+    }
+  },
+  "treeResponse": {
+    "result": "ok",
+    "response": {"children": [{"dirId": "business_dir_root", "dirName": "根目录", "parentDirId": "", "children": []}]}
+  },
+  "deleteResponse": {"result": "ok", "response": true}
+}

package/skills/guanmetric/references/metric-business-dictionary-api-contract.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://guandata.example/schemas/metric-business-dictionary-api-contract.schema.json",
+  "title": "GuanData metric business dictionary API contracts",
+  "$defs": {
+    "nonEmptyString": {"type": "string", "minLength": 1},
+    "bizAttr": {"type": "object", "required": ["id", "values"], "properties": {"id": {"type": "string"}, "values": {"type": "array", "items": {"type": "string"}}}, "additionalProperties": true},
+    "writeRequest": {
+      "type": "object",
+      "required": ["name", "desc"],
+      "properties": {"name": {"$ref": "#/$defs/nonEmptyString"}, "desc": {"type": "string"}, "dirId": {"type": "string"}, "bizAttrs": {"type": "array", "items": {"$ref": "#/$defs/bizAttr"}}},
+      "additionalProperties": false
+    },
+    "mutationResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"$ref": "#/$defs/nonEmptyString"}}, "additionalProperties": true},
+    "dictionary": {
+      "type": "object",
+      "required": ["id", "domId", "name", "desc", "bizAttrs", "creator", "creatorName", "ctime", "utime", "associatedMetrics"],
+      "properties": {"id": {"type": "string"}, "domId": {"type": "string"}, "dirId": {"type": "string"}, "name": {"type": "string"}, "desc": {"type": "string"}, "bizAttrs": {"type": "array"}, "creator": {"type": "string"}, "creatorName": {"type": "string"}, "ctime": {"type": "string"}, "utime": {"type": "string"}, "associatedMetrics": {"type": "array"}},
+      "additionalProperties": true
+    },
+    "detailResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"$ref": "#/$defs/dictionary"}}, "additionalProperties": true},
+    "listResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["list", "total"], "properties": {"list": {"type": "array", "items": {"$ref": "#/$defs/dictionary"}}, "total": {"type": "number"}}, "additionalProperties": true}}, "additionalProperties": true},
+    "treeResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "object", "required": ["children"], "properties": {"children": {"type": "array"}}, "additionalProperties": true}}, "additionalProperties": true},
+    "deleteResponse": {"type": "object", "required": ["result", "response"], "properties": {"result": {"const": "ok"}, "response": {"type": "boolean"}}, "additionalProperties": true}
+  }
+}

package/skills/guanmetric/references/metric-business-dictionary.md

@@ -2,6 +2,10 @@
 
 业务字典在后端接口和代码中也称 `BusinessMetric`，CLI 使用面向产品语义的命令名 `business-dict`，并兼容 `business-metric`、`biz-dict` 别名。
 
+构造或解析请求和响应前先读取 `metric-business-dictionary-api-contract-examples.json` 与 `metric-business-dictionary-api-contract.schema.json`。样例于 2026-09-21 在 test153 使用隔离临时业务字典和账号密码认证完成 create、detail/list、edit、delete 后脱敏；PAT 尚未验证。仓库测试会按 Schema 校验真实快照的必需字段和类型，同时允许后端新增可选字段。
+
+真实响应外层统一为 `{ "result": "ok", "response": ... }`：创建和编辑成功时 `response` 是业务字典 ID 字符串；详情包含 `id/domId/dirId/name/desc/bizAttrs/creator/creatorName/ctime/utime/associatedMetrics`；搜索返回 `response.list/total`；删除成功返回布尔值。详情是读模型，编辑只白名单提交 `name/desc/dirId/bizAttrs`。
+
 ## 查询
 
 ```bash

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

@@ -2,6 +2,9 @@
 
 复合指标用于通过公式组合已有指标，例如“客单价 = 销售额 / 订单数”。
 
+创建/编辑请求、真实详情响应和读写映射见 `metric-api-contracts.md`；机器样例见
+`metric-api-contract-examples.json`。
+
 ## 触发场景
 
 - 用户说“创建复合指标”“基于多个指标算一个指标”。
@@ -119,17 +122,18 @@
 
 ## 创建步骤
 
-`guanmetric create` 当前是原子指标专用 endpoint；复合指标创建使用 `guanmetric fetch`。
+单个复合指标使用 `guanmetric composite create`；对话式批量创建或公式引用本批指标时，优先按 `metric-flow.md` 使用 `guanmetric flow`。
 
 1. 先输出指标创建计划，按 `metric-mutation.md` 的“指标创建计划”要求展示环境、主题、目录、将复用或新建的基础指标、复合公式、共有适用维度/时间维度、格式、业务属性和保存方式。
 2. 用户确认计划后，生成 `/tmp/composite_metric.json`。
-3. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性；逐个读取引用指标详情，确认 `subType` 仅为 `ATOMIC` 或 `COMPOSITE`。`guanmetric fetch` 也会在提交前执行同一类型检查。
+3. 本地/人工检查 JSON、公式引用指标、共有适用维度、必填业务属性；逐个读取引用指标详情，确认 `subType` 仅为 `ATOMIC` 或 `COMPOSITE`。`guanmetric composite create` 也会在提交前执行同一类型检查。
 4. 按 `metric-common-fields.md` 向用户摘要并确认。
 5. 用户确认后，不调用原子指标 `save-precheck`；复合指标 Web 创建没有 save-precheck。
 6. 提交真实创建：
 
 ```bash
-guanmetric fetch POST /api/metric-platform/metrics/composite-metrics --stdin < /tmp/composite_metric.json
+guanmetric composite create --file /tmp/composite_metric.json --dry-run
+guanmetric composite create --file /tmp/composite_metric.json
 ```
 
 7. 响应返回指标 ID 后回读：
@@ -142,26 +146,20 @@ guancli metric get <metric_id> --brief
 
 复合指标没有原子指标的 save-precheck；主要校验公式或筛选变化是否影响下游指标/卡片。
 
-1. 读取当前详情：
-
-```bash
-guancli metric get <metric_id> --raw
-```
-
-2. 基于当前详情生成完整编辑 payload，例如 `/tmp/composite_metric_update.json`。至少包含 `projectId`、`subType`、`name`、`formula`、`useExpressionMetricCommonDims`、`applicableDims`、`desc`、`publish`。
-3. 如果修改了 `formula` 或 `filter`，先调用影响校验：
+1. 准备只包含本次变更字段的 patch，例如 `/tmp/composite_metric_patch.json`；不要复制或回写详情读模型。
+2. 先 dry-run。命令会读取当前详情，按复合指标 Update DTO 白名单构造完整写模型并输出影响校验和更新步骤：
 
 ```bash
-guanmetric fetch POST /api/metric-platform/metrics/composite-metrics/<metric_id>/validate-update-impact --stdin < /tmp/composite_metric_update.json
+guanmetric composite edit <metric_id> --file /tmp/composite_metric_patch.json --dry-run
 ```
 
-4. 如果返回 `hasChanged=true` 且 `affectedMetrics` 或 `affectedCards` 非空，展示受影响指标和卡片，等待用户二次确认。
-5. 提交真实编辑：
+3. 提交真实编辑。命令自动调用 `validate-update-impact`；存在下游影响时会阻断并返回影响清单，用户确认后才追加 `--confirm`：
 
 ```bash
-guanmetric fetch POST /api/metric-platform/metrics/composite-metrics/<metric_id> --stdin < /tmp/composite_metric_update.json
+guanmetric composite edit <metric_id> --file /tmp/composite_metric_patch.json
+guanmetric composite edit <metric_id> --file /tmp/composite_metric_patch.json --confirm
 ```
 
-6. 保存后回读确认。
+4. 命令保存后自动回读，校验名称、口径、公式及维度等已提交字段；`useExpressionMetricCommonDims=true` 时适用维度由后端按引用指标共有维度重算，不做输入数组逐项相等判断。
 
-编辑载荷和公式/格式复制使用 `--raw` 的后端详情，成功后从后端 `response` 读取字段；不能把后端响应当成 canonical envelope。普通机器发现使用 `-f json` 并从 `data` 取值，canonical 详情不承诺完整编辑字段。
+编辑命令内部读取后端详情，但只通过白名单生成写模型；`referencedMetrics`、`creator`、`statisticsData`、对象数组 `applicableDims`、对象 `timeDim` 等读模型字段绝不能原样提交。