Skip to content

skill_readme_cn.md

Latest commit

 

History

History
254 lines (176 loc) · 8.3 KB

skill_readme_cn.md

File metadata and controls

254 lines (176 loc) · 8.3 KB

RDS 相关 Skills 使用说明

本仓库提供两类 Skill，均可用于 Claude、OpenClaw、Claude Code 等以「技能」形式接入：

  1. alibabacloud-rds-copilot：调用阿里云 RDS AI 助手 API，完成智能问答、SQL 优化、故障排查等。
  2. rds-openapi-skill：通过命令行直接调用本项目的 RDS OpenAPI 工具 与 只读 SQL 工具，管理实例、查监控/慢日志/参数、执行只读 SQL 等。

一、RDS Copilot Claude Skill（RDS AI 助手）

阿里云 RDS AI助手 的 Claude Skill，用于在 Claude 对话中直接调用 RDS AI 助手能力，完成 SQL 优化、实例运维、故障排查等任务。

Claude Skill 使用示例

环境要求

开通 RDS AI助手专业版

Python 版本

  • Python 3.7+（推荐 Python 3.8 或更高版本）

验证 Python 版本：

python3 --version

快速开始

1. 克隆仓库

git clone https://github.com/aliyun/alibabacloud-rds-openapi-mcp-server
cd alibabacloud-rds-openapi-mcp-server/skill

2. 安装依赖

安装uv：

curl -LsSf https://astral.sh/uv/install.sh | sh

3. 配置环境变量

设置阿里云访问凭证（必需）：

macOS / Linux：

export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret"

Windows (PowerShell)：

$env:ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret"

永久配置（推荐）：

将上述命令添加到你的 shell 配置文件中：

  • Bash: ~/.bashrc 或 ~/.bash_profile
  • Zsh: ~/.zshrc
  • Windows: 系统环境变量设置

4. 部署 Skill 到 Claude

将 Skill 文件复制到 Claude 的 skills 目录：

方法一：直接使用本仓库结构

如果你使用的是 Claude Desktop 或支持自定义 skills 的环境，本仓库已经包含正确的目录结构 alibabacloud-rds-copilot/，可以直接使用。

方法二：复制到用户级 skills 目录

# macOS / Linux
mkdir -p ~/.claude/skills/
cp -r alibabacloud-rds-copilot ~/.claude/skills/

# Windows (PowerShell)
New-Item -ItemType Directory -Path "$env:USERPROFILE\.claude\skills\" -Force
Copy-Item -Recurse ".claude\skills\aliyun-rds-copilot" "$env:USERPROFILE\.claude\skills\"

方法三：创建符号链接（推荐开发环境）

# macOS / Linux
mkdir -p ~/.claude/skills/
ln -s "$(pwd)/alibabacloud-rds-copilot" ~/alibabacloud-rds-copilot

# Windows (需管理员权限)
New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.claude\skills\aliyun-rds-copilot" -Target "$(Get-Location)\.claude\skills\aliyun-rds-copilot"

5. 验证安装

运行claude，选择alibabacloud-rds-copilot skill：

claude
/alibabacloud-rds-copilot 我在杭州有多少实例？

预期输出：

[查询] 查询杭州地域的 RDS 实例列表
[地域] cn-hangzhou | [语言] zh-CN
============================================================
[RDS Copilot 回答]
<RDS Copilot 的实际回答内容>

[会话ID] conv-xxxx-xxxx-xxxx

使用说明

基础用法

在 Claude 对话中，直接提问 RDS 相关问题：

你：查询杭州地域有哪些 MySQL 实例？
Claude：[调用 RDS Copilot 并返回结果]

你：针对rm-xxx实例帮我分析和优化这条 SQL：SELECT * FROM users WHERE status=1 ORDER BY created_at
Claude：[调用 RDS Copilot 获取 SQL 优化建议]

常见问题

1. 提示找不到模块 alibabacloud_rdsai20250507

原因：未安装依赖包或使用了错误的 Python 环境。

解决方法：

# 使用 pip3 确保安装到 Python 3 环境
pip3 install -r alibabacloud-rds-copilot/requirements.txt

# 验证安装
pip3 list | grep alibabacloud

2. 提示环境变量未设置

错误信息：

未找到阿里云访问凭证。请设置环境变量:
  ALIBABA_CLOUD_ACCESS_KEY_ID
  ALIBABA_CLOUD_ACCESS_KEY_SECRET

解决方法： 按照"配置环境变量"章节设置 AccessKey 和 Secret。

3. Claude 未识别到 Skill

原因：Skill 文件未正确部署到 Claude skills 目录。

解决方法：

  • 检查 alibabacloud-rds-copilot/SKILL.md 是否存在
  • 确认 Skill 目录结构完整
  • 重启 Claude 应用

5. 使用 python 命令报错

原因：系统中 python 命令指向 Python 2 或未配置。

解决方法： 统一使用 python3 命令：

python3 alibabacloud-rds-copilot/scripts/call_rds_ai.py "your query"

二、RDS OpenAPI Skill（OpenAPI + SQL 工具命令行）

rds-openapi-skill 将本项目的 MCP 工具以「脚本/命令行」形式暴露，便于接入 OpenClaw、Claude Code 等：大模型通过执行 rds-openapi-skill list / rds-openapi-skill run <工具名> '<JSON 参数>' 来调用 RDS OpenAPI 与只读 SQL 能力，从而管理 RDS 实例。

能力概览

  • OpenAPI 工具：查询实例列表/详情、可用区/规格、监控、慢日志、参数、账号、数据库、白名单；创建/修改实例与账号、改参数/规格、重启、公网连接等。
  • SQL 工具：只读执行 query_sql、explain_sql、show_create_table、show_engine_innodb_status、show_largest_table、show_largest_table_fragment 等。

安装与配置

  1. 安装本包（任选其一）

    • 在仓库根目录：uv pip install -e . 或 pip install -e .
    • 安装后可使用命令：rds-openapi-skill

  2. 环境变量（与 MCP 服务相同）

    • ALIBABA_CLOUD_ACCESS_KEY_ID、ALIBABA_CLOUD_ACCESS_KEY_SECRET（必填）
    • 可选：ALIBABA_CLOUD_SECURITY_TOKEN、MCP_TOOLSETS（默认 rds）

命令行用法

# 列出当前启用的工具（JSON）
rds-openapi-skill list

# 执行工具，参数为 JSON 字符串
rds-openapi-skill run describe_db_instances '{"region_id":"cn-hangzhou"}'
rds-openapi-skill run describe_db_instance_attribute '{"region_id":"cn-hangzhou","db_instance_id":"rm-xxxxx"}'
rds-openapi-skill run get_current_time '{}'

未安装到环境时，可从仓库根目录用模块方式执行：

uv run python -m alibabacloud_rds_openapi_mcp_server.run_tool list
uv run python -m alibabacloud_rds_openapi_mcp_server.run_tool run describe_db_instances '{"region_id":"cn-hangzhou"}'

接入 OpenClaw / Claude Code

  1. 部署 Skill 目录
    将 skill/rds-openapi-skill/ 复制或链接到对应平台的 skills 目录，例如：

    • OpenClaw：~/.openclaw/workspace/skills/rds-openapi-skill/
    • Claude Code：~/.claude/skills/rds-openapi-skill/ 或项目内 .claude/skills/rds-openapi-skill/

  2. 配置 entries 并写入 env（推荐）
    本 skill 需要环境变量 ALIBABA_CLOUD_ACCESS_KEY_ID 和 ALIBABA_CLOUD_ACCESS_KEY_SECRET。建议在平台的 entries 里为 rds-openapi-skill 配置 env，把这两个变量写进去，后续使用无需再单独配置。

    • OpenClaw：编辑 ~/.openclaw/openclaw.json，在 skills.entries 中增加： 
      "rds-openapi-skill": {
  "enabled": true,
  "env": {
    "ALIBABA_CLOUD_ACCESS_KEY_ID": "你的 AccessKey ID",
    "ALIBABA_CLOUD_ACCESS_KEY_SECRET": "你的 AccessKey Secret"
  }
}
    • 可选：同一 env 中可加 ALIBABA_CLOUD_SECURITY_TOKEN（STS）、MCP_TOOLSETS（如 "rds,rds_custom_read"）。
    • Claude Code 等：在对应技能的「entries」或「环境变量」配置中为 rds-openapi-skill 设置上述两个 env 即可。

  3. 确保环境中可执行
    安装本包后，保证在终端能直接运行 rds-openapi-skill。大模型会按 SKILL.md 中的说明调用 rds-openapi-skill list 与 rds-openapi-skill run <name> '<json>'。

  4. Skill 内容说明

    • skill/rds-openapi-skill/SKILL.md：技能名称、描述、何时使用、标准流程、配置 entries 与常用工具速查。
    • skill/rds-openapi-skill/tools_reference.md：工具名与参数参考。
    • skill/rds-openapi-skill/skill.yaml：供 OpenClaw/ClawHub 使用的元数据（可选）。