Este tópico descreve como usar o Alibaba Cloud Flink Agent Skills para gerenciar instâncias e workspaces do Realtime Compute for Apache Flink com linguagem natural em plataformas de AI Agent populares.
Visão geral dos Skills
O Realtime Compute for Apache Flink oferece três Agent Skills no Alibaba Cloud Skill Hub. Esses Skills abrangem três categorias de cenários frequentes: gerenciamento do ciclo de vida de instâncias, operações de workspace e conhecimento especializado em Flink. Após a integração, use linguagem natural para criar, consultar, implantar, operar e solucionar problemas de recursos do Flink em clientes compatíveis com o protocolo Agent Skills, como Claude Code, OpenClaw, Qoder, Cursor e Gemini CLI. Não é necessário fazer chamadas manuais à OpenAPI ou executar operações no console.
|
Nome do Skill |
Cenário |
Capacidades principais |
|
Gerenciamento do ciclo de vida de instâncias e namespaces |
Consulta de regiões e zonas disponíveis, criação de instâncias, consulta de status de instâncias, criação e consulta de namespaces, consulta de tags de recursos |
|
|
Operações diárias de workspace |
Criação e validação de rascunhos SQL, implantação e início ou parada de jobs, gerenciamento do ciclo de vida completo de Session Clusters, diagnóstico de jobs, consulta de tabelas de dados, gerenciamento de membros e variáveis |
|
|
Conhecimento especializado em Flink |
Consulta de parâmetros e versões do product, informações de faturamento, geração de Flink SQL (DDL, CDAS para sincronização completa de banco de dados, cenários de controle de risco), orientação para restauração de checkpoint e savepoint, solução de problemas de jobs |
Os três Skills chamam a OpenAPI do Flink diretamente por meio do SDK oficial Python da Alibaba Cloud. Por padrão, o sistema carrega as credenciais via default credentials provider chain. As credenciais nunca são passadas como argumentos de linha de comando.
O AI Intelligent Assistant no console também fornece skills integrados que cobrem cenários como desenvolvimento de rascunhos, gerenciamento de implantação e diagnóstico de jobs. Para mais informações, consulte Intelligent Assistant.
Pré-requisitos
Instale Node.js e Python
A instalação dos Skills ocorre por meio da CLI npx skills, que requer Node.js 18 ou posterior. Os scripts internos são implementados em Python e exigem Python 3.6 ou posterior.
node --version # Requires >= 18
python3 --version # Requires >= 3.6Se não estiverem instalados, escolha o método de instalação adequado ao seu sistema operacional:
# macOS
brew install node python@3.9
# Ubuntu/Debian
sudo apt-get install nodejs npm python3 python3-pip
# CentOS/RHEL
sudo yum install nodejs python3 python3-pipConfigure as credenciais da Alibaba Cloud
Os Skills obtêm credenciais de AccessKey da Alibaba Cloud por meio da cadeia de provedores de credenciais padrão. Recomendamos o uso de variáveis de ambiente para injetar as credenciais e evitar sua codificação direta em linhas de comando ou scripts.
export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret"
export ALIBABA_CLOUD_REGION_ID="cn-beijing"Para ambientes de produção, recomendamos o uso de funções RAM ou credenciais temporárias STS para evitar vazamentos de AccessKey de longo prazo.
Prepare as permissões RAM
Conceda as permissões mínimas necessárias ao usuário RAM utilizado pelos Skills. Não utilize diretamente o AccessKey da sua conta Alibaba Cloud.
Permissões necessárias para alibabacloud-flink-instance-manage
{
"Version": "1",
"Statement": [
{
"Effect": "Allow",
"Action": [
"stream:CreateVvpInstance",
"stream:DescribeVvpInstances",
"stream:CreateVvpNamespace",
"stream:DescribeVvpNamespaces",
"stream:QueryTagVvpResources"
],
"Resource": [
"acs:stream:*:*:vvpinstance/*",
"acs:stream:*:*:vvpinstance/*/vvpnamespace/*"
]
}
]
}Permissões necessárias para alibabacloud-flink-workspace-ops
Operações no nível de workspace, como implantação de jobs, gerenciamento de Session Cluster e validação de SQL, exigem a concessão de uma função de desenvolvedor ou administrador ao usuário RAM no workspace correspondente por meio do gerenciamento de membros no console. Para mais informações sobre permissões de funções, consulte Manage workspace members.
Instale e use Skills no Claude Code
Este tópico usa o Claude Code como exemplo. Para suporte a outras plataformas de Agent, consulte o guia de instalação na página do Skill correspondente no portal Alibaba Cloud Skills.
Instale os Skills
# Install to the current project (recommended for project-level sharing)
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-flink-instance-manage --agent claude-code -y --full-depth
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-flink-workspace-ops --agent claude-code -y --full-depth
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-flink-knowledge --agent claude-code -y --full-depth
# Or install globally (append -g for all projects)
npx skills add aliyun/alibabacloud-aiops-skills --skill alibabacloud-flink-instance-manage --agent claude-code -y --full-depth -gCaminho de instalação no nível do projeto: <project>/.claude/skills/. Caminho de instalação global: ~/.claude/skills/.
Se o comando npx skills add apresentar timeout devido a problemas de rede ao clonar o repositório, clone-o manualmente e instale a partir do caminho local:
git clone https://github.com/aliyun/alibabacloud-aiops-skills.git ~/.agents/alibabacloud-aiops-skills
npx skills add ~/.agents/alibabacloud-aiops-skills/skills/analyticscomputing/sc/alibabacloud-flink-instance-manage --agent claude-code -y
npx skills add ~/.agents/alibabacloud-aiops-skills/skills/analyticscomputing/sc/alibabacloud-flink-workspace-ops --agent claude-code -y
npx skills add ~/.agents/alibabacloud-aiops-skills/skills/analyticscomputing/sc/alibabacloud-flink-knowledge --agent claude-code -yInstale as dependências Python dos Skills
cd .claude/skills/alibabacloud-flink-instance-manage
pip3 install -r assets/requirements.txt
cd ../alibabacloud-flink-workspace-ops
pip3 install -r assets/requirements.txtO alibabacloud-flink-knowledge não requer dependências Python adicionais. Este Skill opera com base em uma base de conhecimento integrada.
Se o pip reportar um erro PEP 668 no macOS, utilize um ambiente virtual ou adicione o parâmetro --break-system-packages.
Verifique a instalação
Reinicie o Claude Code e visualize a lista de Skills disponíveis para confirmar o reconhecimento dos três Skills do Flink.
/skillsA saída deve incluir alibabacloud-flink-instance-manage, alibabacloud-flink-workspace-ops e alibabacloud-flink-knowledge.
Exemplos de uso
Descreva sua intenção em linguagem natural diretamente na conversa. O Claude Code identifica automaticamente o Skill correspondente e executa a operação.
Gerenciamento de instâncias (alibabacloud-flink-instance-manage)
# Query all Flink instances in the China (Beijing) region
Query my Flink instances in cn-beijing
# Create a Flink instance
Create a Flink instance named demo-vvp in cn-beijing
# Query available zones
Which zones are available in cn-hangzhou?Operações de workspace (alibabacloud-flink-workspace-ops)
# Create a SQL draft
Create a SQL draft named hello-flink in workspace my-workspace with the content SELECT 1
# Deploy and start a job
Deploy the draft I just created and start the job
# Diagnose a job
Diagnose the recently failed job in workspace my-workspace
# Manage Session Clusters
Create a Session Cluster named dev-cluster in workspace my-workspaceConsultas de conhecimento (alibabacloud-flink-knowledge)
# Query product parameters
What engine versions does Realtime Compute for Apache Flink support?
# Generate Flink SQL
Generate a CDAS SQL statement for full-database sync from MySQL CDC to Paimon
# Checkpoint restore guidance
How do I restore a job from a savepoint after an upgrade? What should I be aware of?
# Troubleshooting
What could cause a checkpoint timeout? How do I troubleshoot it?Para operações que modificam recursos, como criação, implantação, início, parada e exclusão, o Skill adiciona automaticamente o parâmetro de confirmação de segurança --confirm. Em operações irreversíveis, como exclusão, expresse explicitamente a intenção de excluir em linguagem natural antes que o Skill execute a operação.
Perguntas frequentes
P1: O Skill não entra em vigor após a instalação
Verifique se o diretório do Skill foi criado (se .claude/skills/alibabacloud-flink-instance-manage/SKILL.md existe) e se o cliente foi reiniciado para carregar os Skills.
P2: Erro ModuleNotFoundError ao executar um comando
As dependências Python não estão instaladas. Acesse o diretório do Skill e execute pip3 install -r assets/requirements.txt.
P3: Erro NoPermission ou Forbidden ao executar um comando
Verifique se o usuário RAM recebeu a política de permissão mínima listada nos pré-requisitos e se a cadeia de provedores de credenciais padrão está carregando o AccessKey correto para esse usuário RAM.
P4: O status da instância não muda para RUNNING após a criação
O Skill faz polling em um intervalo padrão de 30 segundos, com tempo máximo de espera de 10 minutos. Se o timeout for excedido, verifique manualmente o status da instância no console. Caso haja insuficiência de recursos, expanda-os no console antes de tentar novamente.
P5: As informações de parâmetros retornadas pelo Knowledge Skill são sempre precisas e atualizadas?
O Knowledge Skill busca as informações de parâmetros mais recentes na documentação online sempre que possível. Se a busca na documentação falhar, o Skill retorna um aviso de segurança e orienta você a verificar no console. Para parâmetros críticos, como faturamento e versões do mecanismo, a exibição real no console tem precedência.
P6: Quais tipos de Flink SQL o Knowledge Skill pode gerar?
Este Skill suporta a geração de instruções DDL, instruções de sincronização CDC de banco de dados completo (sintaxe CDAS) e SQL de monitoramento de controle de risco. O SQL gerado inclui anotações -- TODO: para indicar informações de conexão que devem ser substituídas pelos valores reais.