/develop-metric

name: develop-metric
description: |-
  指标开发：为没有技术实现的业务指标找来源表 → 定口径 SQL → 建计算任务产出结果表 → 登记自定义指标 → 回流关联。
  触发场景：指标开发 / 找不到可用的技术指标 / 给业务指标做技术落地 / 找来源表算指标 / 新建自定义指标。
  流程：list-catalog-assets 先找现成结果表 → list-tables 找来源表 → get-table-columns 校验字段 → 产出任务草案交 update-batch-task / submit-batch-task → 【控制台人工登记自定义指标】→ 核验注册 → 交回 manage-biz-metric 关联。
  关键限制：创建自定义指标（CUSTOM_INDEX）与资产上架无 OpenAPI，必须输出控制台指引并暂停等人工；get-table-columns 走 --catalog 项目英文名，不认 --project-id；list-tables 必带 --cli-query 收窄输出。
  触发词：指标开发、自定义指标、CUSTOM_INDEX、找来源表、汇总表、指标计算任务、develop metric。

指标开发 Skill（找来源表 · 建计算任务 · 登记技术指标）

1. Scenario Description

当业务指标已经定义好口径，但**没有任何现成技术指标能满足它**时，进入本 Skill 做技术落地。典型上游是子 skill [`manage-biz-metric`](../manage-biz-metric/SKILL.md) 的 Step 4 判定「无可用技术指标」后转来。

本 Skill 的产出目标是**一个可被业务指标关联的技术指标**。路径分两种，按结果表是否已存在分流：

| 情况 | 处理 | |---|---| | **已有结果表/汇总表**能算出该指标 | 跳过任务开发，直接进 Step 4 登记自定义指标 | | **没有结果表** | 走完整开发：找来源表 → 定口径 SQL → 建计算任务产出结果表 → 再进 Step 4 |

> **本 Skill 有一处硬断点**：创建自定义指标（`CUSTOM_INDEX`）与资产上架到目录**实测无任何 OpenAPI 命令**（插件 0.7.1 已穷举确认）。Step 4 必须输出控制台操作指引并**暂停等用户人工完成**，不得伪造命令或跳过。

Architecture

上游：业务指标已定义，无可用技术指标
  → Step 1 找来源表（list-tables → get-table-columns 校验字段）
  → Step 2 定口径 SQL（可选：即席查询试算验证）
  → Step 3 建离线计算任务产出结果表（委托 update-batch-task / submit-batch-task）
  → Step 4 【人工】控制台登记自定义指标 + 上架到资产目录  ← 无 OpenAPI，暂停等人工
  → Step 5 list-catalog-assets --asset-type INDEX 确认已注册，取 AssetFullName
  → 回流：交回 manage-biz-metric Step 5 完成关联

涉及 Dataphin OpenAPI

• `ListTables` — 分页查资产表元数据（v5.4.2）
• `GetTableColumns` — 查表字段（v5.4.2）
• `ExecuteAdHocTask` / `GetAdHocTaskResult` — 即席查询试算口径（可选）
• `CreateBatchTask` / `UpdateBatchTask` / `SubmitBatchTask` — 离线计算任务（委托给已有 skill）
• `ListCatalogAssets` — 确认自定义指标已注册（v6.1.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)。

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 位大整数，字符串传参） | | 目标业务指标名 | 是 | 本次开发是为哪个业务指标做技术落地 | | 指标口径 | 是 | 统计对象 + 聚合方式 + 统计周期 + 业务限定 | | `--project-id` / 项目英文名 | 是 | 来源表与计算任务所在项目 | | 来源表清单 | 是 | 由 Step 1 检索后**经用户确认**，不得 Agent 自行拍定 | | 结果表名 | 是（需开发时） | 计算任务的输出表 | | 调度周期 | 是（需开发时） | 与指标统计周期一致 |

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 0 · 先判断是否已有结果表可用

先在资产目录里搜一遍汇总表/结果表，命中就**跳过 Step 1~3 直接进 Step 4**，避免重复建任务：

aliyun dataphin-public list-catalog-assets --tenant-id "$TENANT_ID" \
  --asset-type TABLE --query-mode ASSET_SEARCH \
  --keyword "<业务关键词，如 客户 汇总>" --page-size 20 \
  --user-agent "$USER_AGENT" --format json

关注返回项的 `AssetFullName`（后续拼技术指标全名要用）、`AssetDescription`、`SubType`。

Step 1 · 找来源表（只读）

# 1a) 先只取总数，判断检索范围大小（避免一次拉回巨量元数据）
aliyun dataphin-public list-tables --tenant-id "$TENANT_ID" \
  --project-id "<项目ID>" --page-size 1 \
  --cli-query 'PageResult.TotalCount' \
  --user-agent "$USER_AGENT"

# 1b) 只取表名清单（必须收窄投影，否则单次响应可达十万级字符）
aliyun dataphin-public list-tables --tenant-id "$TENANT_ID" \
  --project-id "<项目ID>" --page-num 1 --page-size 50 \
  --cli-query 'PageResult.TableList[].Name' \
  --u