/manage-biz-metric

name: manage-biz-metric
description: |-
  管理 Dataphin 业务指标（BIZ_INDEX）：查询 → 语义查重并强制阻塞确认 → 创建 → 关联技术指标。
  触发场景：查看业务指标 / 新建业务指标 / 指标查重 / 有没有类似的指标 / 业务指标关联技术指标。
  流程：get-biz-metric-by-name（草稿+已发布）与 list-catalog-assets(BIZ_INDEX) 三路召回 → 有相似项必须停下等用户确认 → create-biz-metric → list-catalog-assets(INDEX) → update-biz-metric 关联。
  关键限制：无业务指标 list 接口，列表靠资产目录且只覆盖已上架资产（存在漏判需告知）；--biz-metric-name 不接受中文，中文走 --display-name；技术指标全名 = 表资产 AssetFullName + 指标名，禁用 AssetFrom；一技术指标只能被一业务指标关联；写操作需 HITL。
  触发词：业务指标、BIZ_INDEX、create-biz-metric、指标查重、关联技术指标、指标口径。

业务指标治理 Skill（查重 · 新建 · 关联技术指标）

1. Scenario Description

在 Dataphin「资产治理管理 → 资产 → 业务指标」中，用业务语言登记指标口径，并把它映射到可计算的**技术指标**上。业务指标解决「这个指标是什么意思、谁负责」，技术指标解决「这个数怎么算出来」。

本 Skill 覆盖两段业务动作：

1. **查重后新建业务指标** — 先召回已有指标做语义查重；**发现相似项必须停下、列出相似原因、等用户明确确认**才允许创建，避免指标口径重复建设。 2. **关联技术指标** — 查业务指标当前关联情况；未关联则在资产目录中找可用技术指标（自定义指标 `CUSTOM_INDEX` 或规范建模派生指标 `INDEX`）并建立关联。

找不到任何可用技术指标时，转交子 skill [`develop-metric`](../develop-metric/SKILL.md) 做指标开发，开发完成后回到本 skill 的 Step 5 完成关联。

Architecture

用户描述指标需求
  → Step 1 三路召回已有业务指标（get-by-name×2 + 资产目录模糊搜索）
  → Step 2 语义查重 →【有相似项：阻塞，等用户确认】
  → Step 3 create-biz-metric 创建（HITL）
  → Step 4 查关联技术指标（get-biz-metric-by-name → list-catalog-assets INDEX）
  → Step 5 update-biz-metric 关联技术指标（HITL）
       └ 无可用技术指标 → 转 develop-metric skill → 回到 Step 5

涉及 Dataphin OpenAPI

• `ListCatalogAssets` — 查资产目录列表（`BIZ_INDEX` 业务指标 / `INDEX` 技术指标），上线版本 v6.1.0
• `GetBizMetricByName` — 按名称查业务指标详情，v5.5.0
• `CreateBizMetric` — 创建业务指标，v5.5.0
• `UpdateBizMetric` — 更新业务指标（含关联技术指标），v5.5.0
• `DeleteBizMetric` — 删除业务指标，v5.5.0

> **版本门槛**：资产目录相关命令需目标环境 ≥ v6.1.0；业务指标命令需 ≥ v5.5.0。低于门槛时相关命令不存在或报错，应告知用户升级而非换参数重试。

2. Installation

# 安装 aliyun CLI（>= 3.4.8）
# 各操作系统一键安装脚本见 ./references/cli-installation-guide.md

# 安装 dataphin-public 插件
aliyun plugin install --names aliyun-cli-dataphin-public

# 验证
aliyun dataphin-public --help

详见 [CLI 安装指南](./references/cli-installation-guide.md)。

3. Environment Variables

| 变量 | 说明 | 必须 | |------|------|------| | `ALIBABA_CLOUD_ACCESS_KEY_ID` | RAM AccessKey ID | 是 | | `ALIBABA_CLOUD_ACCESS_KEY_SECRET` | RAM AccessKey Secret | 是 |

或通过 `aliyun configure` 配置 profile。

4. Authentication

Pre-check: Credentials Required

> **Security Rules:** > - **NEVER** 读取、回显或打印凭证环境变量（禁止对 AccessKey ID / Secret 做任何输出或日志） > - **NEVER** 要求用户在本会话或命令行直接输入 AK/SK > - **NEVER** 使用 `aliyun configure set` 写入字面量凭证 > - **ONLY** 使用 `aliyun configure list` 检查凭证状态 > > ```bash > aliyun configure list > ``` > 检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。 > > **如果没有有效 profile，请在此停止。** > 1. 从 [Alibaba Cloud Console](https://ram.console.aliyun.com/manage/ak) 获取凭证 > 2. 在会话外配置（终端执行 `aliyun configure`，或在 shell profile 中设置环境变量） > 3. 重新运行 `aliyun configure list` 确认有效后再继续

Pre-check: Aliyun CLI >= 3.4.8 required

> 执行 `aliyun version` 确认版本 >= 3.4.8；不达标见 [references/cli-installation-guide.md](./references/cli-installation-guide.md)。

Pre-check: Aliyun CLI plugin update required

> [MUST] run `aliyun configure set --auto-plugin-install true` to enable automatic plugin installation. > [MUST] run `aliyun plugin update` to ensure that any existing plugins are always up-to-date.

5. RAM Policy

> **[MUST] Permission Failure Handling:** When any command or API call fails due to permission errors at any point during execution, follow this process: > 1. Read `../../ram-policies.md` to get the full list of permissions required by this SKILL > 2. Use `ram-permission-diagnose` skill to guide the user through requesting the necessary permissions > 3. Pause and wait until the user confirms that the required permissions have been granted

本 skill 最小权限见 [../../ram-policies.md](../../ram-policies.md)。

> **除 RAM Action 外还需 Dataphin 平台内角色**（已实测）：读写业务指标都需要**资产维护人员**或拥有**「上架管理-管理」权限**的角色。权限不足时的报错**都不是标准 403**：写操作返回顶层 `Code: OK` 但 `Data.Success=false`（见 §9），读详情返回 `DPN.Mdc.Shelve.ShelveObjectNoViewAuth`（见 §8 Step 1）。**实测赋权后同一指标同一命令即返回 `OK`**，所以遇到这两种报错应先怀疑权限，不要改参数重试。

6. IMPORTANT: Parameter Confirmation

> **IMPORTANT: Parameter Confirmation** — Before executing any command or API call, > ALL user-customizable parameters MUST be confirmed with the user. Do NOT assume or > use default values without explicit user approval.

创建 / 更新前必须逐项确认，禁止静默填默认值：

| 参数 | 必填 | 说明 | |------|------|------| | `--tenant-id` | 是 | 租户 ID（19 位大整数，字符串传参） | | `--biz-metric-name` | 是 | 指标名称，**租户内唯一**；仅接受英文字母、数字与 `-_/\·#$^&*()%+=`，≤256 字符。**中文名会被拒绝** | | `--display-name` | 建议必填 | 展示名称，**中文指标名放这里** | | `--metric-definition` | 建议必填 | 指标口径；引用其他业务指标时用半角中括号 `[指标名]` 包裹 | | `--biz-owner-name` | 否 | 业务负责人**账号用户名**（不是显示名） | | `--description` | 否 | 描述 | | `--catalog-ids` | 否 | 归属目录 ID 列表（list 型，取值见 §8 Step 3 说明） | | `--labels` | 否 | 资产标签（list 型） | | `--associated-tech-metric-full-names` | 否 | 关联技术指标全名列表（list 型，格式见 §类型分支） | | `--related-biz-metrics` | 否 | 相关业务指标列表（list 型） | | `--view-scope` | 否 | 可见范围（object 型） | | `--new-name` | 否（update） | 改名时才传 |

7. Observability

版本 `{version}`（Shell 变量 `SKILL_VERSION`）来自套件 `references/manifest.json` 的 `version` 字段，与 session-id 一同继承[父技能 §7](../../../SKILL.md#7-observability)。直接加载本子技能时先完成父层初始化；所有 CLI / SDK 调用使用父技能名称与同一版本，跨 Shell 调用须重新注入这些值。

本 Skill 属于 `alibabacloud-dataphin-skills` 套件，**继承父 Skill `alibabacloud-dataphin-skills` 的 session-id**，子 Skill 不再重新生成。

所有调用 Alibaba Cloud API 的 `aliyun` 命令必须携带：

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}"

其中 `{session-id}` 替换为父 Skill 生成的 32 位小写十六进制字符串。本地工具命令（`configure` / `plugin` / `version`）不支持该 flag，不需携带。

8. Core Workflow

TENANT_ID="<19 位租户 ID，字符串>"
SESSION_ID="<继承自 alibabacloud-dataphin-skills>"
USER_AGENT="AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/$SESSION_ID skill-version/$SKILL_VERSION"

Step 1 · 三路召回已有业务指标（只读）

**以 1a/1b 精确查为权威判定，1c 用于找近义指标**（顺序与理由见下方错误码表）：

# 1a) 精确名 · 草稿/未上架态 ★ 判定「同名是否已存在」的权威路径
aliyun dataphin-public get-biz-metric-by-name --tenant-id "$TENANT_ID" \
  --biz-metric-na