Pular para o conteúdo principal

Como criar Quick Commands IDE

Criar um Quick Command

Siga os passos para criar:

Passo 1. Acesse o Portal da StackSpot AI

Passo 2. No menu principal, clique em ‘Contents > Quick Command’;

Passo 3. Clique no botão ‘Criar Quick Command’;

Captura de tela do Portal da StackSpot AI. A imagem destaca a seção Quick Commands e o botão Criar Quick Command

Passo 4. Selecione a opção: IDE;

Passo 5. Preencha os campos para adicionar informações sobre o seu Quick Command;

  • Nome do Quick Command: adicione um nome claro e descritivo para o seu comando.

Exemplo: Technical Debt

  • Comando: adicione um nome que será usado posteriormente. Ele deve seguir o padrão de slug. Para mais informações sobre Slugs, confira o padrão do slug.

Exemplo: technical_debt_1

  • Descrição: adicione uma descrição clara e objetiva sobre o que o seu comando faz.

Exemplo: Criar uma issue no GitHub destacando a dívida técnica no código selecionado e sugerir uma forma de correção.

Captura de tela do portal da StackSpot AI mostrando a seleção de IDE, campos para nome do Quick Command, comando e descrição, com o botão Salvar destacado na parte inferior.

Passo 6. Clique no botão 'Próximo'. Você pode escolher entre usar os templates disponíveis (pré-preenchidos) ou criar um template do zero, conforme sua necessidade.

Captura de tela do portal da StackSpot AI destacando o botão branco Criar para iniciar a criação de um Quick Command do zero.

Confira um exemplo de criação:

Animação mostrando o passo a passo para criar um Quick Command personalizado na Plataforma StackSpot AI. A animação guia o usuário desde o acesso ao portal, passando pela navegação no menu principal, até a criação do Quick Command.

Usar passo do tipo ‘Prompt’

Confira um exemplo de criação de um Quick Command de com passo do tipo ‘Prompt’:

1. Clique em 'Criar em branco'. Aperte e arraste a caixa de 'Prompt' para perto do 'Início'. É necessário conectar as caixas com a linha:

Captura de tela do portal da StackSpot AI mostrando a criação de um Quick Command, com o botão Prompt destacado e o botão Início visível na parte superior

2. Preencha os campos na caixa do prompt:

  • Insira o nome do seu prompt: adicione um identificador slug seguindo o padrão de slug.

Confira um exemplo: /titulo_da_issue

  • Insira seu prompt: escreva o que você quer que seu comando faça.

Se você quiser que o usuário selecione um trecho específico de código, insira o {{ input_data }} na caixa designada. Adicionar esta opção envia a informação para a StackSpot AI e facilita o entendimento;

Confira o exemplo: "Leia este {{ input_data }} e escreva um título de até 80 caracteres para uma issue no GitHub."

Informação Adicional

Você pode incorporar passos condicionais ao fluxo dos seus Quick Commands. Para mais detalhes, confira a página de Condicionais.

  • Use a Stack atual para gerar código: Esta opção depende do que você precisa.

    • Quando habilitada, considera o contexto da sua Stack e gera código baseado se você tem uma Stack de Java ou Python, por exemplo. Se você requer geração de código, então esta opção é recomendada.
    • No entanto, se você precisa gerar texto, como traduções, é melhor não habilitar esta opção, pois não deve produzir os melhores resultados.

  • Usar Projeto Indexado: ative o projeto indexado nesta etapa para utilizar os arquivos indexados e melhorar o contexto no Quick Command. Após um projeto ser indexado, o recurso de Quick Commands usa esses dados para criar comandos e fluxos de trabalho mais precisos e relevantes. Isso deve resultar em sugestões personalizadas para o ambiente específico do projeto indexado.

  • Use o Knowledge Source selecionado no chat: quando você habilita essa opção, a StackSpot AI incluirá todos os Knowledge Sources selecionados pelo usuário na IDE durante a execução de um Quick Command (incluindo aqueles dentro do Workspace selecionado) e aqueles já configurados no Quick Command. Isso melhorará os Quick Commands com informações essenciais e específicas do Workspace, aumentando sua utilidade e consciência de contexto.

  • Incluir os arquivos enviados: Para permitir que as pessoas usuárias enviem arquivos em uma etapa específica do Quick Command, ative a opção Incluir arquivos enviados em cada etapa desejada. Quando essa opção estiver ativada, as pessoas usuárias poderão fazer upload de arquivos durante a execução do comando.

Captura de tela do portal da StackSpot AI exibindo a criação de um Quick Command, com os campos Nome do Prompt, Inserir o seu Prompt e o botão Salvar na parte inferior.

  • Quando o comando for executado com essa opção ativada, a pessoa usuária deverá fazer o upload do arquivo no início do processo.

imagem mostrando a tela de quick command com o botão de fazer upload de arquivo

  • Continuar mesmo com erro: permite definir qual será o próximo passo de acordo com o sucesso ou erro de um step. Assim, você controla o fluxo do Quick Command conforme necessário.
    • Para configurar, clique na caixa do prompt e marque a opção 'Continuar mesmo com erro'. Clique em 'Sucesso'' e conecte a caixa desejada. Faça o mesmo para 'Erro'.
    • Você pode tratar erros exibindo o status, mensagem de erro ou outras informações usando variáveis Jinja no campo de Resultado Final. Para mais detalhes, confira a documentação.
Informações Adicionais
  • Se um step não tiver essa opção ativada, qualquer erro interrompe a execução do Quick Command.
  • Se a opção estiver ativada e ocorrer um erro, o fluxo segue o caminho definido para Erro. A StackSpot AI só continua a execução se houver um fluxo definido para erros.

Essa opção está disponível apenas para steps do tipo Prompt, não para Web Request.

3. Selecionar Knowledge Sources

Esse é um passo opcional. Ao criar um Quick Command, você pode escolher Knowledge Sources para selecionar um contexto específico. Isso é útil ao criar comandos que exigem conhecimento detalhado, como a busca por vulnerabilidades com base em políticas de segurança, por exemplo.

Captura de tela da seção do portal StackSpot AI onde é possível adicionar Knowledge Sources ao Quick Command, com opções para selecionar KS da conta ou pessoais.

4. Selecionar Agentes

Durante a criação do Quick Command, você pode selecionar Agentes. Eles serão consultados sempre que o usuário utilizar esse prompt.

Captura de tela da seção do portal StackSpot AI onde é possível adicionar Agentes ao Quick Command, com opções para selecionar agentes da conta, pessoais, compartilhados ou integrados (built-in)

5. Clique no botão ‘Salvar’ e depois conecte a linha da caixa do seu prompt até a caixa 'Finalizar'.

6. Clique em 'Finalizar' e, em seguida, na Tela de Resultado Final:

  • Escolha a forma como o usuário pode interagir com o seu Quick Command na IDE, confira:

  1. Interface: a pessoa usuária usa o comando, e o conteúdo é exibido na barra lateral da Extensão da StackSpot AI.

  2. Código: a pessoa usuária usa o comando, e o conteúdo será colado diretamente no código ou:

  • Substituir o código selecionado

  • Acima do código selecionado

  • Abaixo do código selecionado

  • Insira .answer após o nome do seu Quick Command (apenas se for uma opção de prompt): {{ title_issue.answer }}

7. Clique no botão 'Salvar';

Confira o resumo do seu comando

Captura de tela da seção de utilização do comando no portal StackSpot AI, mostrando as opções de interação do usuário com o comando na IDE e o resultado final. O botão Salvar está destacado

Dica!

O comando pode usar o formato Jinja

Confira o exemplo:

GIF tutorial da plataforma StackSpot AI mostrando, passo a passo, como criar um Quick Command do tipo Prompt. O GIF exibe o preenchimento da caixa de prompt com o texto: Leia este {input_data} e escreva o título até 80 caracteres para uma issue do GitHub. O cursor conecta visualmente as caixas de Início, Step01 e Finalizar. Por fim, a caixa Finalizar é configurada para que a resposta do Quick Command seja inserida abaixo do código selecionado.

Usar passo do tipo 'Web Request'

Esse exemplo adiciona o passo do tipo 'Web Request' em um Quick Command que já possui um passo do tipo Prompt para obter um título para uma issue do GitHub.

Passo 1. Clique em ‘Web Request’, em seguida clique no Card Step adicionado e preencha os campos:

  • Nome da requisição web: github-issue
  • Método HTTP: POST
  • URL Endpoint: Esta é uma API do GitHub que usa seu repositório, substitua os valores {ONWER_REPO}/{REPO_NAME} pelo seu nome de usuário ou organização e o nome do repositório que você deseja abrir a issue: https://api.github.com/repos/{ONWER_REPO}/{REPO_NAME}/issues
  • Headers:
Dica!

Para esse tipo de requisição, você precisa gerar um Personal Access Token (PAT) fine-grained nas configurações do seu perfil do GitHub. Vá até a seção ‘Developer settings‘, e conceda as permissões necessárias para interagir com repositórios. E em seguida, crie uma Secret na StackSpot ou selecione uma Secret existente na sua conta para usar nos campos 'Key' e 'Value'.

Considere que foi cadastrada uma Secret com o nome github com a Key MY_TOKEN e Value com o valor do PAT. Ao selecionar a Secret ela será adicionada como:

  • Key: MY_TOKEN
  • Value: {{secrets.user.github.MY_TOKEN}} (Formato de Secret para armazanamento Pessoal)

Dessa forma, o header da sua requisição deve conter em Authorization como 'Value' a variável {{secrets.user.github.MY_TOKEN}}.

Preencha os 'Headers' da requisição preenchendo os campos 'KEY' e 'VALUE' de acordo com o exemplo a seguir:

Não utilize aspas no preenchimento dos Headers.

{
   "Accept": "application/vnd.github+json",
   "Authorization": "Bearer <ADD_YOUR_TOKEN>",
   "X-GitHub-Api-Version": "2022-11-28"
}

Exemplo de preenchimento dos Headers da requisição pelo preenchimento dos campos Key e Value disponíveis no menu de Secrets

  • Body da requisição: O body recebe a resposta do prompt de revisão de código que você adicionou antes e substitui JSON usando Jinja para realizar ações:
{{ codereview.answer | replace("json","") | replace("```","")}}

Clique em 'Ok' para finalizar;

Passo 2. Clique no card 'Finalizar' para abrir as opções de 'Utilização do Quick Command'. Selecione a opção 'Interface';

  • No campo 'Resultado Final', apague qualquer texto que houver e adicione o texto a seguir:
Este código adiciona na resposta a URL da issue do GitHub
Issue created on github! 
{{github-issue.json.html_url}}

Passo 3. Clique em ‘Ok’ e ligue todos os cards do fluxo na sequência: Início > codereview > github-issue > Finalizar;

Passo 4. Preencha a Utilização do Quick Command. Escolha a forma como o usuário pode interagir com o seu Quick Command na IDE, confira:

  1. Interface: a pessoa usuária usa o comando, e o conteúdo é exibido na barra lateral da Extensão da StackSpot AI.

  2. Código: a pessoa usuária usa o comando, e o conteúdo será colado diretamente no código ou:

  • Substituir o código selecionado

  • Acima do código selecionado

  • Abaixo do código selecionado

  • Resultado final: Esta opção mostra a mensagem de sucesso que o usuário verá usando o seu Quick Command. Você pode editar a mensagem e escolher o modo de utilização também. Confira o exemplo mostrando a URL para criar uma issue no GitHub:

Resultado final Insira { para visualizar as opções de entrada pré-definidas ou clique nas tags: select_mode, titulo_da_issue, summarize, propose_improvement;

  • Usar contexto de chat: Esta opção usa respostas e interações de Quick Command anteriores como contexto para interações subsequentes em uma sessão de chat específica. Você pode usar esta opção para ter uma experiência mais coerente e enriquecida contextualmente em suas interações dentro da plataforma. A StackSpot AI usa entradas e respostas anteriores para informar e aprimorar seus comandos e respostas futuras.

  • Usar Projeto Indexado: ative o projeto indexado nesta etapa para utilizar os arquivos indexados e melhorar o contexto no Quick Command. Após um projeto ser indexado, o recurso de Quick Commands usa esses dados para criar comandos e fluxos de trabalho mais precisos e relevantes. Isso deve resultar em sugestões personalizadas para o ambiente específico do projeto indexado.

Sua issue foi criada com sucesso no seguinte URL: {{create_issue.json[0].url}}

Captura de tela do portal StackSpot AI na página de criação de um Quick Command do tipo Web Request. A imagem destaca a seleção do tipo Web Request e exibe os campos de configuração preenchidos como exemplo, incluindo: nome do comando, método HTTP, URL do endpoint, cabeçalhos (headers) e corpo da requisição. Os campos estão organizados em um formulário centralizado na tela.

Passo 5. Clique nos botão 'OK’

Você pode fazer alterações no seu Quick Command, é só clicar em qualquer parte do 'Command Flow'.

Informação Adicional

Se o seu Quick Command encontrar algum erro com o provedor do LLM, como limite de uso, tempo de resposta esgotado (timeout) ou falha de conexão, a StackSpot AI tentará executar a chamada novamente de forma automática. São feitas até três novas tentativas além da chamada original, totalizando quatro tentativas para cada step de LLM.

Você não pode alterar ou configurar a quantidade de tentativas.

Atenção!

Ao adicionar uma URL de serviço externa, pode ser que a API não permita o recebimento de requisições devido a restrições de CORS (Cross-Origin Resource Sharing).

Para resolver esse problema, você tem duas opções:

Para realizar qualquer uma das opções, é necessário ter conhecimento sobre APIs. O processo pode variar dependendo da linguagem, framework ou infraestrutura utilizada.

Opção 1. Adicionar a URL do Front da StackSpot na API

Se você for o responsável pela API, basta configurar a API para aceitar requisições provenientes da URL do front da StackSpot. Isso permitirá que as requisições sejam realizadas sem problemas.

Opção 2. Criar uma API de Middleware

Caso não seja possível alterar a configuração da API, você pode criar uma API de middleware. Nesse caso, o Quick Command (QC) chamará a sua API de middleware, que será responsável por liberar o CORS. Em seguida, o middleware fará a chamada interna ao serviço externo desejado.

O middleware ou proxy mencionado aqui é uma API comum que permite você configurar e habilitar as definições de CORS. Sua principal função é atuar como um intermediário, repassando as chamadas para a API de destino. As chamadas de API para API não enfrentam problemas relacionados a CORS.

O fluxo típico funciona da seguinte forma:

  • O Front-end realiza chamadas para a API de middleware ou proxy. Nesta etapa, é necessário que as configurações de CORS estejam devidamente habilitadas no middleware ou proxy.
  • A API de middleware ou proxy repassa as chamadas para a API de destino, sem a necessidade de configurações adicionais de CORS, já que chamadas entre APIs não enfrentam restrições de origem cruzada

Para mais detalhes, confira o guia.

Informação Adicional

Como posso navegar por cada etapa desse fluxo de criação?

Quando a resposta é um JSON, você pode navegar por partes específicas das etapas anteriores que você fez no fluxo de criação. Você pode trabalhar com os atributos, os valores, etc. Esse passo é essencial porque você pode extrair o que o usuário precisa. Por exemplo, um campo daquele serviço que você criou, um cabeçalho, qual foi o status, etc.

Se você precisar saber qualquer valor das etapas anteriores, adicione as informações:

1. Web Request Confira um servidor que pode retornar o seguinte formato de objeto:

Headers: {"headers_name": "value", ...}
data: text
status: [200-599]
json: json - dictionary of the "data"

Exemplo: {{create_issue.json[0].url}}

  • Se os dados que você recebe estão em formato JSON, você pode facilmente navegar pelos valores e atributos dos seus dados.
  • O campo json estará vazio se não for um JSON.

2. Prompt Por padrão, você pode navegar pelos seguintes campos:

prompt_tokens: string
completion_tokens: string

Exemplo: {{my_prompt.answer}}

O que você pode fazer a seguir?

1. Adicionar Inputs

2. Compartilhar o seu Quick Command

Você pode compartilhar um Quick Command que criou com outras pessoas usuárias. Isso permitirá o uso direto dentro das IDEs da Conta.

  • Na tela de 'Quick Commands' clique no botão de compartilhar no lado esquerdo para compartilhar.

Excluir um Quick Command IDE conectado a um Workspace

Cuidado!

Esta ação é irreversível.

Excluir um Quick Command IDE em um Workspace pode afetar outras pessoas usuárias. Siga os passos:

  1. No o menu principal vá para ‘Quick Command’;
  2. Selecione o Quick Command que deseja excluir e clique em ‘Configurações’;
  3. Clique no botão ‘Excluir’

Vídeo: Como criar um Quick Command

Próximos Passos