alibabacloud-adb-smart-analyst

ADB MySQL 智能分析师 Skill

使用时机

• 用户提出数据分析问题（如 "帮我看看销售数据"、"查一下北京的订单"、"最近一周的发货量"）
• 用户想创建、修改或删除语义视图
• 用户想探索数据库表结构或元数据
• 用户提到 ADB MySQL、AnalyticDB 或语义视图

前置条件

ADB 连接（所有方式必须）

• Python 3.6+，并已安装 pymysql 包
• 安装依赖：uv pip install pymysql
• 可选依赖：cryptography（仅在以下场景需要，按需安装 uv pip install cryptography）：
  • 服务端使用 caching_sha2_password（MySQL 8.0 默认）或 sha256_password 鉴权插件
  • 连接走 TLS/SSL
  • 默认的 ADB MySQL 多采用 mysql_native_password，通常无需安装；若连接时报 RuntimeError: 'cryptography' package is required ...，再补装即可
• 必须设置以下环境变量（无论使用哪种方式都需要，因为最终 SQL 执行均通过 SQL 连接）：
  • ADB_MYSQL_HOST - ADB MySQL 集群地址
  • ADB_MYSQL_PORT - ADB MySQL 端口（默认：3306）
  • ADB_MYSQL_DATABASE - 默认数据库名
  • ADB_MYSQL_USER - 数据库用户名
  • ADB_MYSQL_PASSWORD - 数据库密码

OpenAPI 方式附加条件（当语义层 SQL 方式不可用时）

当 SQL 方式的语义功能不可用（如缺少 semantic_views 元数据表、SQL hint 语义操作失败）时，语义操作切换到 OpenAPI 方式。数据查询执行仍通过上述 SQL 连接完成。

• aliyun CLI 已安装
• adb CLI 插件已安装
• aliyun CLI 凭证已由用户配置完成。可通过 aliyun configure 配置 AK/SK，但不建议 Agent 主动执行配置命令或代用户录入密钥；Agent 只做检测和使用。
• 必须设置：
  • ADB_CLUSTER_ID - ADB 集群 ID（必须，如 am-bp1xxxxxxxx）
  • ADB_REGION - 地域（可选，CLI profile 已含时可省略，如 cn-hangzhou）
• 凭证检测优先使用 aliyun configure list 或轻量级 OpenAPI 探测；不要仅依赖 ALIBABA_CLOUD_* 环境变量，因为默认 profile 也可提供有效凭证。
• RAM 权限要求（需为当前 AK/SK 对应的 RAM 用户或角色授权以下 Action）：
  • adb:CreateSemanticView
  • adb:DeleteSemanticView
  • adb:ReplaceSemanticView
  • adb:GenerateSqlBySemanticSql
  • adb:RenameSemanticView
  • adb:SearchSemanticViews
  • adb:GetSemanticView

架构

方式 A（主方式 - 全 SQL）：
  用户 → Agent → Skill → PyMySQL → ADB Engine

方式 B（OpenAPI 语义 + SQL 执行）：
  语义操作：用户 → Agent → Skill → aliyun CLI → OpenAPI Gateway → ADB Engine
  数据执行：用户 → Agent → Skill → PyMySQL → ADB Engine

两种方式均通过 SQL 连接执行最终查询，区别仅在于语义操作的实现方式（SQL hint vs aliyun CLI）。Skill 优先 SQL 方式，SQL 语义功能不可用时自动切换 OpenAPI（详见下方「方式选择策略」）。

OpenAPI 方式下 alter_semantic_view --operation set_comment 不可用（计划补齐）。Skill 脚本自动添加 SQL hint，Agent 生成 SQL 时无需加 hint。

方式选择策略