@guandata/guanmetric 0.1.18 → 0.1.20

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

@@ -0,0 +1,171 @@
+{
+  "schemaVersion": "1.0",
+  "source": {
+    "environment": "test71",
+    "capturedAt": "2026-09-21",
+    "note": "由 test71 隔离临时资源真实请求采集后脱敏；ID 和名称不可直接用于调用"
+  },
+  "project": {
+    "createRequest": {
+      "name": "经营指标",
+      "icon": "finance_subject",
+      "iconColor": "#1A827F"
+    },
+    "createResponse": {
+      "result": "ok",
+      "response": {
+        "id": "project_example"
+      }
+    },
+    "updateRequest": {
+      "name": "经营分析指标",
+      "icon": "binoculars_subject",
+      "iconColor": "#799BFF"
+    },
+    "updateResponse": {
+      "result": "ok",
+      "response": {
+        "id": "project_example"
+      }
+    },
+    "detailResponse": {
+      "result": "ok",
+      "response": {
+        "id": "project_example",
+        "domId": "example_domain",
+        "name": "经营分析指标",
+        "icon": "binoculars_subject",
+        "iconColor": "#799BFF",
+        "dirId": "dir_project_root",
+        "canManage": true,
+        "canUse": true
+      }
+    },
+    "listResponse": {
+      "result": "ok",
+      "response": [
+        {
+          "id": "project_example",
+          "domId": "example_domain",
+          "name": "经营分析指标",
+          "icon": "binoculars_subject",
+          "iconColor": "#799BFF",
+          "dirId": "dir_project_root",
+          "canManage": true,
+          "canUse": true
+        }
+      ]
+    },
+    "deleteResponse": {
+      "result": "ok",
+      "response": "delete success."
+    }
+  },
+  "directory": {
+    "createRequest": {
+      "name": "销售分析",
+      "parentDirId": "dir_project_root",
+      "dirType": "METRIC_PLATFORM"
+    },
+    "createResponse": {
+      "result": "ok",
+      "response": {
+        "dirId": "dir_sales",
+        "dirName": "销售分析",
+        "dirType": "METRIC_PLATFORM",
+        "parentDirId": "dir_project_root",
+        "parentDirName": "经营分析指标",
+        "dirPath": [
+          {
+            "dirId": "dir_global_root",
+            "dirName": "根目录"
+          },
+          {
+            "dirId": "dir_project_root",
+            "dirName": "经营分析指标"
+          },
+          {
+            "dirId": "dir_sales",
+            "dirName": "销售分析"
+          }
+        ]
+      }
+    },
+    "updateRequest": {
+      "name": "销售经营分析",
+      "parentDirId": "dir_project_root",
+      "dirType": "METRIC_PLATFORM"
+    },
+    "updateResponse": {
+      "result": "ok",
+      "response": {
+        "dirId": "dir_sales",
+        "dirName": "销售经营分析",
+        "dirType": "METRIC_PLATFORM",
+        "parentDirId": "dir_project_root",
+        "parentDirName": "经营分析指标",
+        "dirPath": [
+          {
+            "dirId": "dir_global_root",
+            "dirName": "根目录"
+          },
+          {
+            "dirId": "dir_project_root",
+            "dirName": "经营分析指标"
+          },
+          {
+            "dirId": "dir_sales",
+            "dirName": "销售经营分析"
+          }
+        ]
+      }
+    },
+    "detailResponse": {
+      "id": "dir_sales",
+      "parentDirId": "dir_project_root",
+      "name": "销售经营分析",
+      "type": "DIRECTORY",
+      "contents": [],
+      "canManage": true,
+      "canUse": true,
+      "ctime": "2026-09-21T10:15:32.00Z",
+      "utime": "2026-09-21T10:15:48.00Z",
+      "metricCnt": 0,
+      "allMetricCnt": 0
+    },
+    "treeResponse": {
+      "result": "ok",
+      "response": {
+        "id": "dir_project_root",
+        "parentDirId": "dir_global_root",
+        "name": "根目录",
+        "type": "DIRECTORY",
+        "contents": [
+          {
+            "id": "dir_sales",
+            "parentDirId": "dir_project_root",
+            "name": "销售经营分析",
+            "type": "DIRECTORY",
+            "contents": [],
+            "canManage": true,
+            "canUse": true,
+            "ctime": "2026-09-21T10:15:32.00Z",
+            "utime": "2026-09-21T10:15:48.00Z",
+            "metricCnt": 0,
+            "allMetricCnt": 0
+          }
+        ],
+        "canManage": true,
+        "canUse": true,
+        "ctime": "2026-09-21T10:15:19.00Z",
+        "utime": "2026-09-21T10:15:49.00Z",
+        "metricCnt": 0,
+        "allMetricCnt": 0
+      }
+    },
+    "deleteResponse": {
+      "result": "ok",
+      "response": "Directory deleted"
+    }
+  }
+}

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

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://guandata.dev/schemas/guanmetric/metric-hierarchy-api-contract-1.0.json",
+  "title": "GuanData metric project and directory API contract",
+  "description": "用于 Agent 构造指标主题/目录请求并解析真实后端响应。响应允许后端新增字段。",
+  "oneOf": [
+    { "$ref": "#/$defs/projectWriteRequest" },
+    { "$ref": "#/$defs/projectMutationResponse" },
+    { "$ref": "#/$defs/projectDetailResponse" },
+    { "$ref": "#/$defs/projectListResponse" },
+    { "$ref": "#/$defs/projectDeleteResponse" },
+    { "$ref": "#/$defs/directoryWriteRequest" },
+    { "$ref": "#/$defs/directoryMutationResponse" },
+    { "$ref": "#/$defs/directoryNode" },
+    { "$ref": "#/$defs/directoryTreeResponse" },
+    { "$ref": "#/$defs/directoryDeleteResponse" }
+  ],
+  "$defs": {
+    "nonEmptyString": {
+      "type": "string",
+      "minLength": 1
+    },
+    "projectWriteRequest": {
+      "type": "object",
+      "required": ["name", "icon", "iconColor"],
+      "properties": {
+        "name": { "$ref": "#/$defs/nonEmptyString" },
+        "icon": { "$ref": "#/$defs/nonEmptyString" },
+        "iconColor": { "$ref": "#/$defs/nonEmptyString" }
+      },
+      "additionalProperties": false
+    },
+    "project": {
+      "type": "object",
+      "required": ["id", "domId", "name", "icon", "iconColor", "dirId", "canManage", "canUse"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nonEmptyString" },
+        "domId": { "$ref": "#/$defs/nonEmptyString" },
+        "name": { "$ref": "#/$defs/nonEmptyString" },
+        "icon": { "$ref": "#/$defs/nonEmptyString" },
+        "iconColor": { "$ref": "#/$defs/nonEmptyString" },
+        "dirId": { "$ref": "#/$defs/nonEmptyString" },
+        "canManage": { "type": "boolean" },
+        "canUse": { "type": "boolean" }
+      },
+      "additionalProperties": true
+    },
+    "projectMutationResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {
+        "result": { "const": "ok" },
+        "response": {
+          "type": "object",
+          "required": ["id"],
+          "properties": { "id": { "$ref": "#/$defs/nonEmptyString" } },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "projectDetailResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {
+        "result": { "const": "ok" },
+        "response": { "$ref": "#/$defs/project" }
+      },
+      "additionalProperties": true
+    },
+    "projectListResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {
+        "result": { "const": "ok" },
+        "response": { "type": "array", "items": { "$ref": "#/$defs/project" } }
+      },
+      "additionalProperties": true
+    },
+    "projectDeleteResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {
+        "result": { "const": "ok" },
+        "response": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "directoryWriteRequest": {
+      "type": "object",
+      "required": ["name", "parentDirId", "dirType"],
+      "properties": {
+        "name": { "$ref": "#/$defs/nonEmptyString" },
+        "parentDirId": { "$ref": "#/$defs/nonEmptyString" },
+        "dirType": { "const": "METRIC_PLATFORM" }
+      },
+      "additionalProperties": false
+    },
+    "directoryPathItem": {
+      "type": "object",
+      "required": ["dirId", "dirName"],
+      "properties": {
+        "dirId": { "$ref": "#/$defs/nonEmptyString" },
+        "dirName": { "type": "string" }
+      },
+      "additionalProperties": true
+    },
+    "directoryMutationPayload": {
+      "type": "object",
+      "required": ["dirId", "dirName", "dirType", "parentDirId", "parentDirName", "dirPath"],
+      "properties": {
+        "dirId": { "$ref": "#/$defs/nonEmptyString" },
+        "dirName": { "$ref": "#/$defs/nonEmptyString" },
+        "dirType": { "const": "METRIC_PLATFORM" },
+        "parentDirId": { "$ref": "#/$defs/nonEmptyString" },
+        "parentDirName": { "type": "string" },
+        "dirPath": { "type": "array", "items": { "$ref": "#/$defs/directoryPathItem" } }
+      },
+      "additionalProperties": true
+    },
+    "directoryMutationResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {
+        "result": { "const": "ok" },
+        "response": { "$ref": "#/$defs/directoryMutationPayload" }
+      },
+      "additionalProperties": true
+    },
+    "directoryNode": {
+      "type": "object",
+      "required": ["id", "parentDirId", "name", "type", "contents", "canManage", "canUse", "metricCnt", "allMetricCnt"],
+      "properties": {
+        "id": { "$ref": "#/$defs/nonEmptyString" },
+        "parentDirId": { "type": "string" },
+        "name": { "type": "string" },
+        "type": { "const": "DIRECTORY" },
+        "contents": { "type": "array", "items": { "$ref": "#/$defs/directoryNode" } },
+        "canManage": { "type": "boolean" },
+        "canUse": { "type": "boolean" },
+        "ctime": { "type": "string" },
+        "utime": { "type": "string" },
+        "metricCnt": { "type": "integer", "minimum": 0 },
+        "allMetricCnt": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": true
+    },
+    "directoryTreeResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {
+        "result": { "const": "ok" },
+        "response": { "$ref": "#/$defs/directoryNode" }
+      },
+      "additionalProperties": true
+    },
+    "directoryDeleteResponse": {
+      "type": "object",
+      "required": ["result", "response"],
+      "properties": {
+        "result": { "const": "ok" },
+        "response": { "type": "string" }
+      },
+      "additionalProperties": true
+    }
+  }
+}

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

@@ -0,0 +1,193 @@
+# 指标主题与指标目录 CRUD API 契约
+
+本文供 Agent 创建和维护指标体系的组织骨架。真实脱敏样例见
+`metric-hierarchy-api-contract-examples.json`，机器可读约束见
+`metric-hierarchy-api-contract.schema.json`。
+
+## 证据与边界
+
+- 2026-09-21 在 test71 使用隔离临时主题和目录完成 create、edit、detail/list/tree、delete 全链路实测。
+- test71 实测使用 `robot@guandata.com` 的账号密码登录态。按本次范围不再创建 PAT；PAT 对照尚未验证，发布或 MR 的 `Domain and Contract` 不能将 PAT 兼容性标记为已通过。
+- 临时目录和主题均在采集完成后删除，没有保留测试资源。
+- 样例保留真实字段、空值和响应形态，ID、Domain 和名称已脱敏，不能直接用于真实调用。
+- 后端响应可能增加字段，Schema 的响应对象允许 `additionalProperties: true`。
+- 本契约只覆盖 `METRIC_PLATFORM` 指标目录，不可拿去修改 `METRIC_TREE`、`BUSINESS_METRIC` 等其他目录类型。
+- 不包含指标 move 和指标 owner 转移；这是本轮明确排除的范围。
+
+## 命令速查
+
+```bash
+# 主题
+guanmetric project list
+guanmetric project get <project_id>
+guanmetric project create 经营指标 --dry-run
+guanmetric project create 经营指标
+guanmetric project edit <project_id> --name 经营分析指标 --dry-run
+guanmetric project edit <project_id> --name 经营分析指标
+guanmetric project delete <project_id>
+guanmetric project delete <project_id> --confirm
+
+# 指标目录
+guanmetric directory tree <project_id>
+guanmetric directory get <project_id> <dir_id>
+guanmetric directory create 销售分析 --project-id <project_id> --dry-run
+guanmetric directory create 销售分析 --project-id <project_id>
+guanmetric directory edit <project_id> <dir_id> --name 销售经营分析 --dry-run
+guanmetric directory edit <project_id> <dir_id> --name 销售经营分析
+guanmetric directory delete <project_id> <dir_id>
+guanmetric directory delete <project_id> <dir_id> --confirm
+```
+
+旧命令 `project-create` 和 `dir-create` 为兼容保留。新流程优先使用分组命令，便于发现完整 CRUD。
+
+## 接口矩阵
+
+| 资源 | 操作 | 客户端方法与路径 | 权限 |
+| --- | --- | --- | --- |
+| Project | create | `POST /api/metric-platform/projects` | `METRIC_PLATFORM.CREATE` |
+| Project | update | `POST /api/metric-platform/projects/{id}` | `METRIC_PLATFORM.UPDATE` |
+| Project | detail | `GET /api/metric-platform/projects/{id}` | `METRIC_PLATFORM.READ` |
+| Project | list | `GET /api/metric-platform/projects` | `METRIC_PLATFORM.READ` |
+| Project | delete | `POST /api/metric-platform/projects/delete/{id}` | `METRIC_PLATFORM.DELETE` |
+| Directory | create | `POST /api/metric-platform/directory/create` | `METRIC_PLATFORM.CREATE` |
+| Directory | update | `POST /api/metric-platform/directory/{id}/update` | `METRIC_PLATFORM.UPDATE` |
+| Directory | tree/read | `GET /api/directory/METRIC_PLATFORM/unauthorized-tree?projectId={id}` | `BASE.READ` |
+| Directory | delete | `POST /api/metric-platform/directory/{id}/delete` | `METRIC_PLATFORM.DELETE` |
+
+以上是客户端真实路径；后端 Spring 路由是去掉 `/api` 后的同路径。新增写调用需要在正式交付前完成同一用户、同一 Domain 下账号密码与 PAT 对照验证。本次按用户选择只使用账号密码，因此 PAT 仍是明确的待验证门禁，不能由单元测试或账密实测替代。
+
+## Project 写模型
+
+创建和更新使用同一完整写模型：
+
+```json
+{
+  "name": "经营分析指标",
+  "icon": "binoculars_subject",
+  "iconColor": "#799BFF"
+}
+```
+
+更新不是自由 patch。`guanmetric project edit` 先读取详情，只从详情白名单提取
+`name/icon/iconColor`，再合并命令行修改；`id/domId/dirId/canManage/canUse` 是读模型字段，不能原样提交。
+
+创建和更新成功响应相同：
+
+```json
+{"result":"ok","response":{"id":"project_example"}}
+```
+
+只收到 HTTP 2xx 但 `result` 不为 `ok`，或 `response.id` 为空，不能认为成功。CLI 会在创建/编辑后回读详情，校验 `name/icon/iconColor` 与请求一致。
+
+## Project 详情与列表
+
+详情的真实结构：
+
+```json
+{
+  "result": "ok",
+  "response": {
+    "id": "project_example",
+    "domId": "example_domain",
+    "name": "经营分析指标",
+    "icon": "binoculars_subject",
+    "iconColor": "#799BFF",
+    "dirId": "dir_project_root",
+    "canManage": true,
+    "canUse": true
+  }
+}
+```
+
+列表的 `response` 是上述对象数组。`dirId` 是该主题对应的根目录 ID，创建一级指标目录时应把它作为 `parentDirId`。不要把主题 `id` 当目录 ID。
+
+删除成功响应是字符串：
+
+```json
+{"result":"ok","response":"delete success."}
+```
+
+主题删除没有独立影响预检接口。CLI 默认只回读并展示目标；只有 `--confirm` 才提交，资源依赖和最终可删性由后端裁决。
+
+## Directory 写模型
+
+创建和更新都使用完整 `DirectoryAPI` 子集：
+
+```json
+{
+  "name": "销售经营分析",
+  "parentDirId": "dir_project_root",
+  "dirType": "METRIC_PLATFORM"
+}
+```
+
+三个字段均不可省略。更新目录时，即使只改名称，也必须保留当前 `parentDirId` 和固定的
+`dirType=METRIC_PLATFORM`。`guanmetric directory edit` 会先读取目录树并显式构造写模型，禁止把树节点详情直接提交。
+
+创建/更新响应不是只有 ID，而是目录路径对象：
+
+```json
+{
+  "result": "ok",
+  "response": {
+    "dirId": "dir_sales",
+    "dirName": "销售经营分析",
+    "dirType": "METRIC_PLATFORM",
+    "parentDirId": "dir_project_root",
+    "parentDirName": "经营分析指标",
+    "dirPath": [
+      {"dirId":"dir_global_root","dirName":"根目录"},
+      {"dirId":"dir_project_root","dirName":"经营分析指标"},
+      {"dirId":"dir_sales","dirName":"销售经营分析"}
+    ]
+  }
+}
+```
+
+CLI 在创建/编辑前校验父目录属于指定 Project 的 `METRIC_PLATFORM` 树，并在写后重新读取目录树，确认名称和父目录均与请求一致。不能把目录移动到自身或自己的子目录。
+
+## Directory 的“详情”来自目录树
+
+后端没有指标目录单条详情接口。权威读取接口返回整个 Project 的目录树：
+
+```http
+GET /api/directory/METRIC_PLATFORM/unauthorized-tree?projectId={projectId}
+```
+
+树节点结构如下：
+
+```json
+{
+  "id": "dir_sales",
+  "parentDirId": "dir_project_root",
+  "name": "销售经营分析",
+  "type": "DIRECTORY",
+  "contents": [],
+  "canManage": true,
+  "canUse": true,
+  "ctime": "2026-09-21T10:15:32.00Z",
+  "utime": "2026-09-21T10:15:48.00Z",
+  "metricCnt": 0,
+  "allMetricCnt": 0
+}
+```
+
+`guanmetric directory get <project_id> <dir_id>` 是客户端从这棵树按 ID 提取节点，不对应新的后端 API。`contents` 递归包含子目录；`metricCnt` 是当前目录指标数，`allMetricCnt` 是包含后代的指标总数。
+
+删除成功响应：
+
+```json
+{"result":"ok","response":"Directory deleted"}
+```
+
+CLI 禁止通过 directory 命令删除 Project 根目录；删除整个主题必须用 `project delete`。普通目录删除默认只展示节点及其子树/指标计数，追加 `--confirm` 才提交；依赖由后端最终校验。
+
+## Agent 使用约束
+
+1. 先创建 Project，再从 Project 详情/列表取得真实根目录 `dirId`。
+2. 创建目录时固定 `dirType=METRIC_PLATFORM`，并校验 `parentDirId` 在该 Project 目录树内。
+3. 编辑只能原地更新，不能删除重建。
+4. Project 更新只提交 `name/icon/iconColor`；Directory 更新只提交 `name/parentDirId/dirType`。
+5. 所有创建和编辑都必须写后回读；HTTP 成功不等于最终状态正确。
+6. 删除必须先展示精确目标，并要求 `--confirm`；不能自行扩展为批量删除。
+7. 本契约不授权指标 move、指标 owner 转移或其他目录类型管理。

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

@@ -2,6 +2,9 @@
 
 本文是指标写操作的入口索引，用于指导 AI 选择应加载的细分文档，避免一次性读取所有指标类型的长配置。当前覆盖原子指标、复合指标、衍生指标的创建/编辑预检查；删除的完整交互流程后续补充。
 
+创建、编辑、详情和列表接口的真实脱敏响应、JSON Schema 及读写模型映射见
+`metric-api-contracts.md`。Agent 构造写请求前应先按该契约选择指标类型和具体变体。
+
 ## 读取顺序
 
 处理指标写操作时按需读取：
@@ -64,8 +67,8 @@ guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <repor
 3. 信息不全时先查 ID，不凭空猜：
    - 指标主题：`guancli metric project [keyword] -f json`
    - 指标目录：`guancli metric tree -f json`
-   - 新建指标主题：`guanmetric project-create <name> --dry-run`，确认后去掉 `--dry-run`
-   - 新建指标目录：`guanmetric dir-create <name> --project-id <metric_topic_id> --dry-run`，也可用 `--project-name <metric_topic_name>`；确认后去掉 `--dry-run`。创建子目录可传 `--parent-dir-id`，也可传 `--parent-dir-name`。若主题名称重复必须让用户指定主题 ID；若父目录名称重复必须让用户指定目录 ID
+   - 新建指标主题：`guanmetric project create <name> --dry-run`，确认后去掉 `--dry-run`
+   - 新建指标目录：`guanmetric directory create <name> --project-id <metric_topic_id> --dry-run`，确认后去掉 `--dry-run`。创建子目录可传 `--parent-dir-id`
    - 指标详情：`guancli metric search <keyword> -f json`、`guancli metric get <metric_id> --brief`
    - 数据集字段：`guancli ds search <keyword>`、`guancli ds get <dsId> --brief`
 4. 如果输入来自标准模板，按 `metric-excel-template.md` 的“创建阶段读取规则”生成 payload：
@@ -76,11 +79,11 @@ guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <repor
    - 复合指标的每个引用必须解析并核对为 `ATOMIC`/`COMPOSITE`；发现 `DERIVED`/快捷引用指标时停止计划，按业务语义改建为组合衍生或“先复合、后衍生”。
    - `适用维度`、`时间维度`、业务属性列都需要解析成接口字段，不要把中文名原样提交给后端。
 5. 读取启用的指标业务属性配置，补齐必填 `bizAttrs`。
-6. 生成“指标创建计划”，让用户 review；用户确认计划前，不生成最终提交 JSON，不执行 dry-run/precheck/真实创建。
-7. 用户确认计划后，生成 JSON 文件，先做 dry-run 或人工摘要，向用户确认当前环境、目标目录、指标口径、计算配置、业务属性和保存方式。
-8. 用户确认后，仍需按 Web 同款交互执行保存前校验或影响校验。
-9. 校验通过、无对应校验，或用户对冲突/影响完成二次确认后，才提交真实创建或编辑。
-10. 写入成功后用 `guancli metric get <metric_id> --brief` 回读确认。
+6. 基于标准模板输出“指标创建计划”摘要，让用户 review；用户确认计划前，不生成最终提交 JSON，不执行真实创建。
+7. 用户确认标准 Excel 后，执行 `guanmetric flow generate --file <standard.xlsx> --out <metric_flow.json>` 自动生成 `schemaVersion=1.0` 计划并完成只读 plan 校验；不要由 Agent 手写 Flow JSON。单个、不经过标准模板的原子指标仍可使用 `create --dry-run`。
+8. 用户确认环境、目录、口径、计算配置、业务属性、保存方式和 Flow 执行顺序后，使用 `flow apply --state ... --confirm`；旧的单指标命令继续按各类型文档执行。
+9. Flow 会执行前端有而后端缺失的字段规则、原子 save-precheck、逐项创建和逐项验收；后端已有的引用状态、权限和指标定义规则由创建接口裁决，不在 Flow 重复查询。口径冲突、审批中或上游不可用时停止下游创建并保存状态。
+10. `acceptance.mode=usable` 只有在 `PUBLISHED`、`canUse=true` 且 `metric query` 冒烟成功后才算完成；`draft` 模式只验证草稿定义回读。旧命令写入成功后仍至少用 `metric get` 回读，不能把它描述为已完成 Flow 的可用性验收。
 
 不要把“dry-run 成功”“precheck 通过”或“影响校验无阻塞”描述成指标已经创建/编辑成功。
 
@@ -145,7 +148,8 @@ guanmetric template normalize <input.xlsx> --out <standard.xlsx> --report <repor
 
 ## 命令能力边界
 
-- `guanmetric create` 和 `guanmetric edit` 当前是原子指标专用命令。
-- 复合指标和衍生指标创建/编辑使用 `guanmetric fetch POST ... --stdin < payload.json`。
+- `guanmetric create` 和 `guanmetric edit` 是原子指标专用命令。
+- 复合指标使用 `guanmetric composite create|edit`，衍生指标使用 `guanmetric derived create|edit`。专用编辑命令负责详情读模型到 Update DTO 白名单的转换、影响校验和写后回读；不要再用裸 `fetch` 回写指标详情。
+- 对话式批量创建或包含依赖的原子/复合/衍生指标统一使用 `guanmetric flow generate|plan|apply|verify`；Flow 是新增入口，不改变上述旧命令。
 - 指标删除使用 `guanmetric delete <metric_id>`；默认只做影响校验，追加 `--confirm` 才会在无下游依赖时提交删除。
 - 指标批量上下线使用 `guanmetric batch online|offline`；详细输入、输出和失败语义见 `metric-batch-status.md`。

package/skills/guanmetric/references/metric-public-dimension-api-contract-examples.json

@@ -0,0 +1,62 @@
+{
+  "schemaVersion": "1.0",
+  "source": {
+    "environment": "test153",
+    "capturedAt": "2026-09-21",
+    "authentication": "account-password",
+    "note": "由隔离临时公共维度真实 CRUD 请求采集后脱敏；PAT 未验证，示例 ID 不可用于调用。"
+  },
+  "createRequest": {
+    "name": "区域",
+    "businessOwner": "user_example",
+    "relatedFields": [{"dsId": "dataset_example", "fdId": "field_region"}]
+  },
+  "createResponse": {"result": "ok", "response": {"id": "public_dim_example"}},
+  "updateRequest": {
+    "name": "经营区域",
+    "businessOwner": "user_example",
+    "relatedFields": [{"dsId": "dataset_example", "fdId": "field_region"}]
+  },
+  "updateResponse": {"result": "ok", "response": {"id": "public_dim_example"}},
+  "detailResponse": {
+    "result": "ok",
+    "response": {
+      "id": "public_dim_example",
+      "domId": "example_domain",
+      "name": "经营区域",
+      "businessOwner": {"uId": "user_example", "name": "示例用户", "email": "user@example.com", "avatar": "", "isDel": false},
+      "relatedFields": [{
+        "dsInfo": {"dsId": "dataset_example", "name": "销售明细"},
+        "fdInfo": {"dsId": "dataset_example", "fdId": "field_region", "name": "省份", "metaType": "DIM", "fdType": "STRING"}
+      }],
+      "creator": {"uId": "user_example", "name": "示例用户", "email": "user@example.com", "avatar": "", "isDel": false},
+      "ctime": "2026-09-21 14:05:05",
+      "utime": "2026-09-21 14:05:15"
+    }
+  },
+  "listResponse": {
+    "result": "ok",
+    "response": {
+      "contents": [{
+        "id": "public_dim_example",
+        "domId": "example_domain",
+        "name": "经营区域",
+        "businessOwner": {"uId": "user_example", "name": "示例用户", "email": "user@example.com", "avatar": "", "isDel": false},
+        "relatedFieldsDisplay": "省份(销售明细)",
+        "fdType": "STRING",
+        "creator": {"uId": "user_example", "name": "示例用户", "email": "user@example.com", "avatar": "", "isDel": false},
+        "ctime": "2026-09-21 14:05:05",
+        "utime": "2026-09-21 14:05:15"
+      }],
+      "count": 1,
+      "limit": 20,
+      "offset": 0
+    }
+  },
+  "fieldMapResponse": {
+    "result": "ok",
+    "response": {"field_region": {"id": "public_dim_example", "name": "经营区域"}}
+  },
+  "dependCheckResponse": {"result": "ok", "response": {"isDepended": false}},
+  "deleteResponse": {"result": "ok", "response": "delete success."}
+}