alibabacloud-dms-skill：盘点当前 Agent 在数据网关管控面可见的数据源、实例、数据库与表，完整翻页并输出状态、类型、引擎、环境分布及覆盖说明；全程只读，不执行 SQL。

阿里云 DMS 数据库读写

通过阿里云 DMS OpenAPI 搜索目标数据库并执行 SQL 查询与数据修改。

场景说明

本 Skill 实现以下工作流：

1. 搜索目标数据库 —— 按关键词搜索数据库以获取 Database ID
2. 执行 SQL 查询 —— 在目标数据库上执行 SQL 语句

架构

用户请求 → 搜索数据库 → 获取 Database ID → 执行 SQL → 返回结果

前置条件

AI-Mode 生命周期（必须按顺序遵循）

本 Skill 必须在 AI-Mode 会话中运行。将以下五个步骤视为严格的生命周期——不得跳过、重排，或将配置步骤与命令执行交错进行：

1. aliyun configure ai-mode enable                                              # 启用 AI-Mode
2. aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill   # 注册 Skill User-Agent
3. aliyun configure set --auto-plugin-install true && aliyun plugin update      # 更新插件
4. <通过 ./scripts/*.sh 执行 DMS 命令>                                          # 执行命令
5. aliyun configure ai-mode disable                                             # 禁用 AI-Mode（清理）

步骤 1–3 属于配置（本节）。步骤 4 由核心工作流覆盖。步骤 5 由清理覆盖。

前置检查

前置检查 0：需要 Aliyun CLI >= 3.3.3
运行 aliyun version 确认 >= 3.3.3。若未安装或版本过低，
运行 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash 安装 / 更新，
或参阅 references/cli-installation-guide.md 获取安装说明。

前置检查 1：启用 AI-Mode
[必须] 在任何其他配置或命令之前运行 aliyun configure ai-mode enable 启用 AI-Mode。
这将激活下游 OpenAPI 服务用于识别 agent 发起流量的 AI-Mode 会话。

前置检查 2：在 AI-Mode 下注册 Skill User-Agent
[必须] 运行 aliyun configure ai-mode set-user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill
将本 Skill 的标识符注册为当前会话的 AI-Mode User-Agent。
在 ai-mode enable 之后、任何插件更新或 DMS 命令之前立即运行。

前置检查 3：需要更新 Aliyun CLI 插件
[必须] 运行 aliyun configure set --auto-plugin-install true 启用插件自动安装。
[必须] 运行 aliyun plugin update 确保已有插件始终为最新版本。
插件更新必须在 AI-Mode 启用且 User-Agent 注册之后进行，以便插件管理器自身报告正确的标识符。

• Aliyun CLI >= 3.3.3
• jq（用于 JSON 解析）：brew install jq
• 已通过 aliyun configure 配置凭证

前置检查 4：需要阿里云凭证
安全规则：
- 绝不读取、回显或打印 AK/SK 值（例如 echo $ALIBABA_CLOUD_ACCESS_KEY_ID 是禁止的）
- 绝不要求用户在对话或命令行中直接输入 AK/SK
- 绝不使用字面凭证值运行 aliyun configure set
- 只使用 aliyun configure list 检查凭证状态
```bash
aliyun configure list
```
检查输出中是否有有效 profile（AK、STS 或 OAuth 身份）。
如果不存在有效 profile，就此停止。
1. 从阿里云控制台获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure 或 shell profile 中的环境变量）
3. 待 aliyun configure list 显示有效 profile 后再返回并重试

[必须] 逐命令 CLI User-Agent —— 除前置检查 2 中注册的 AI-Mode User-Agent 外，

步骤 4 中每次 aliyun CLI 命令调用还必须包含：

--user-agent AlibabaCloud-Agent-Skills/alibabacloud-dms-skill

逐命令标志与 AI-Mode 会话级设置互为补充——两者都必须存在，以便即使 AI-Mode 会话过期，标识符仍随每个请求发送。

RAM 权限

[必须] RAM 权限前置检查： 执行前验证当前用户具有以下 RAM 权限。
完整权限列表见 references/ram-policies.md。

参数确认

重要：参数确认 —— 执行任何命令或 API 调用前，
所有用户可自定义的参数（例如数据库关键词、SQL 语句、db-id 等）
都必须与用户确认。未经用户明确批准，不要假设或使用默认值。

核心工作流

任务 1：搜索目标数据库

按关键词搜索数据库以获取 Database ID：

./scripts/search_database.sh <keyword> --json

示例：

搜索包含 "mydb" 的数据库

./scripts/search_database.sh mydb --json

输出包含 `database_id`、`schema_name`、`db_type`、`host`、`port` 等。

### 任务 2：执行 SQL 查询

使用上一步获得的 Database ID 执行 SQL：

./scripts/execute_query.sh --db-id <database_id> --sql "<SQL_statement>"

#### 写操作保护

对写操作（INSERT/UPDATE/DELETE），脚本实现了保护性预检：

| 参数 | 说明 |
|-----------|-------------|
| `--force` | 确认并执行写操作所必需 |
| `--dry-run` | 预览写操作而不执行 |

**DDL 操作（DROP/TRUNCATE/ALTER/RENAME）被完全阻止** —— 这些必须通过 DMS 控制台执行。

示例：

读操作（无需确认）

./scripts/execute_query.sh --db-id 78059000 --sql "SHOW TABLES"

./scripts/execute_query.sh --db-id 78059000 --sql "SELECT * FROM users LIMIT 10" --json

写操作 —— 先预览（推荐）

./scripts/execute_query.sh --db-id 78059000 --sql "INSERT INTO users (name) VALUES ('test')" --dry-run

写操作 —— 确认后执行

./scripts/execute_query.sh --db-id 78059000 --sql "INSERT INTO users (name) VALUES ('test')" --force

./scripts/execute_query.sh --db-id 78059000 --sql "UPDATE users SET name='test' WHERE id=1" --force

./scripts/execute_query.sh --db-id 78059000 --sql "DELETE FROM users WHERE id=1" --force

逻辑库模式

./scripts/execute_query.sh --db-id 78059000 --sql "SELECT 1" --logic

### 完整示例

1. 搜索数据库（假设搜索 "order"）

./scripts/search_database.sh order --json

示例输出：

[{"DatabaseId": "78059000", "SchemaName": "order_db", ...}]

2. 执行查询

./scripts/execute_query.sh --db-id 78059000 --sql "SELECT COUNT(*) FROM orders"

成功验证

执行 SQL 后，检查返回结果：

1. 脚本返回码为 0
2. 输出包含查询结果（列名和行数据）
3. 无错误消息

验证查询成功

./scripts/execute_query.sh --db-id <db-id> --sql "SELECT 1" --json

预期输出：[{"Success": true, "RowCount": 1, ...}]

清理

本 Skill 执行读写操作但不创建持久资源，因此无需释放数据库资源。

然而，AI-Mode 生命周期要求显式的拆除步骤：

[必须] 所有任务完成后禁用 AI-Mode
本 Skill 会话中所有 DMS 命令（成功或失败）完成后，运行 aliyun configure ai-mode disable 一次。
这将终止 AI-Mode 会话，并防止已注册的
AlibabaCloud-Agent-Skills/alibabacloud-dms-skill User-Agent 泄漏到后续无关的 CLI 使用中。

aliyun configure ai-mode disable

写操作安全

可用脚本

注意： 脚本使用通过 aliyun configure 配置的 aliyun-cli 凭证。

最佳实践

1. 确认数据库 —— 执行 SQL 前验证目标数据库
2. 使用 --json 参数 —— 便于程序化处理输出
3. 预览写操作 —— INSERT/UPDATE/DELETE 始终先用 --dry-run
4. 明确确认 —— 仅在审查预览后才使用 --force
5. 避免 DDL 操作 —— DROP/TRUNCATE/ALTER/RENAME 被阻止；改用 DMS 控制台

参考链接