De Assistente a Agente: Uma Mudanca de Paradigma
A maioria das ferramentas de IA para linha de comando funciona como assistentes: voce pergunta, elas respondem. O ChatCLI vai alem, transformando a IA em um agente autonomo que nao apenas responde, mas age. O sistema de Plugins e IA Agentiva materializa essa visao:- Voce: Define o objetivo e fornece as ferramentas (plugins)
- O Agente: Orquestra a execucao, conectando percepcao, raciocinio e acao para resolver problemas complexos
Esta nao e apenas uma funcionalidade — e a fundacao para um novo modo de interagir com seu ambiente de desenvolvimento.
Arquitetura do Sistema de Plugins
Descoberta e Carregamento Automatico
O ChatCLI utiliza um gerenciador de plugins inteligente que:Plugins Remotos (Server-Side)
Quando conectado a um servidor viachatcli connect, o client descobre automaticamente os plugins disponiveis no servidor. Esses plugins aparecem em /plugin list com a tag [remote] e sao executados no servidor via gRPC — sem necessidade de instalar nada localmente.
O agente pode usar plugins remotos da mesma forma que plugins locais — a execucao e transparente. Ao desconectar, plugins remotos sao removidos automaticamente da listagem.
Plugins Builtin
Alguns plugins essenciais ja vem embutidos no binario do ChatCLI e aparecem com a tag[builtin]. O principal e o @coder, que fornece a suite de engenharia para o modo /coder. Plugins builtin nao precisam de instalacao e nao podem ser desinstalados. Se voce instalar uma versao customizada em ~/.chatcli/plugins/ com o mesmo nome, ela prevalece sobre o builtin.
Busca Flexivel de Plugins
O sistema aceita ambas as formas de invocacao:- Com @ (forma canonica)
- Sem @ (atalho conveniente)
Configuracao do Agente
Variaveis de Ambiente
Configure o comportamento do agente atraves de variaveis de ambiente:| Variavel | Tipo | Padrao | Descricao |
|---|---|---|---|
CHATCLI_AGENT_PLUGIN_MAX_TURNS | inteiro | 50 | Numero maximo de iteracoes do ciclo ReAct. Evita loops infinitos (max: 200). |
CHATCLI_AGENT_PLUGIN_TIMEOUT | duracao | 15m | Tempo limite para execucao de cada plugin. Aceita formato Go (30s, 5m, 1h). |
CHATCLI_AGENT_CMD_TIMEOUT | duracao | 10m | Timeout para comandos shell executados via @command (max: 1h). |
CHATCLI_AGENT_DENYLIST | string | - | Expressoes regulares separadas por ; para bloquear comandos perigosos. |
CHATCLI_AGENT_ALLOW_SUDO | booleano | false | Permite comandos sudo sem bloqueio automatico (use com cautela). |
CHATCLI_AGENT_PARALLEL_MODE | booleano | false | Ativa orquestracao multi-agent com agents paralelos. |
CHATCLI_AGENT_MAX_WORKERS | inteiro | 4 | Maximo de workers (goroutines) executando agents em paralelo. |
CHATCLI_AGENT_WORKER_MAX_TURNS | inteiro | 10 | Maximo de turnos do mini ReAct loop de cada worker agent. |
CHATCLI_AGENT_WORKER_TIMEOUT | duracao | 5m | Timeout por worker agent individual. |
O Ciclo ReAct: Raciocinio e Acao
O AgentMode implementa o framework ReAct (Reasoning and Acting), um loop iterativo transparente:Gerenciamento de Plugins com /plugin
Comandos Disponiveis
| Comando | Descricao |
|---|---|
/plugin list | Lista todos os plugins instalados com metadados |
/plugin install <url> | Instala plugin de um repositorio Git (linguagens compilada) |
/plugin show <nome> | Exibe descricao e sintaxe de uso |
/plugin inspect <nome> | Mostra metadados brutos, caminho e permissoes |
/plugin uninstall <nome> | Remove plugin do sistema |
/plugin reload | Forca recarregamento manual (raramente necessario) |
Exemplo de Uso
- Listar plugins
- Ver detalhes
- Inspecionar metadados
Instalacao de Plugins
Criando Plugins: O Guia Completo
O Contrato do Plugin
Todo plugin deve seguir estas regras:Ser um Executavel
- Binario compilado (Go, Rust, C++) ou
- Script com shebang (
#!/usr/bin/env python3,#!/bin/bash) - Localizado em
~/.chatcli/plugins/ - Permissao de execucao obrigatoria (
chmod +x)
Responder ao Contrato --metadata (Obrigatorio)
Quando invocado com Todos os campos sao obrigatorios:
--metadata, o plugin DEVE imprimir um JSON valido para stdout:name: Deve comecar com@description: Usado pela IA para decidir quando usar a ferramentausage: Sintaxe de invocacaoversion: Versionamento semantico
Implementar --schema (Opcional, mas Recomendado)
O schema ajuda a IA a entender os parametros do plugin:
Comunicacao via I/O Padrao
| Canal | Uso | Descricao |
|---|---|---|
stdout | Resultado | Saida principal enviada para a IA |
stderr | Logs/Progresso | Mensagens de status, avisos e erros |
stdin | Entrada de dados | Blocos grandes de texto (ex: codigo gerado) |
args | Parametros | Argumentos de linha de comando |
stdout para apenas o resultado final, stderr para todo o resto (logs, progresso, erros).Exemplo Completo: Plugin @hello em Go
Este exemplo demonstra todas as melhores praticas:
Compilacao e Instalacao
Testando o Plugin
A IA responde com base no stdout do plugin. Exemplo: “O plugin retornou: Ola, Edilson! A hora agora e Mon, 02 Jan 2024 14:30:00 UTC.”
Debugging de Plugins
Verificar se o Plugin Foi Carregado
Verificar se o Plugin Foi Carregado
Execute
/plugin list. Se o plugin nao aparecer:- Verifique permissoes:
ls -l ~/.chatcli/plugins/— Deve mostrar-rwxr-xr-x(com ‘x’) - Teste o contrato
--metadata:~/.chatcli/plugins/seu-plugin --metadata— Deve retornar JSON valido - Ative logs de debug no
.env:
Testar Plugin Manualmente
Testar Plugin Manualmente
Antes de usar no agente, teste diretamente:
- Testar metadados:
~/.chatcli/plugins/seu-plugin --metadata - Testar schema:
~/.chatcli/plugins/seu-plugin --schema - Testar execucao:
~/.chatcli/plugins/seu-plugin arg1 arg2
Resolver Problemas de Timeout
Resolver Problemas de Timeout
Se o plugin esta sendo interrompido:
- Aumentar timeout globalmente:
export CHATCLI_AGENT_PLUGIN_TIMEOUT=30m - Ou no
.env:CHATCLI_AGENT_PLUGIN_TIMEOUT=30m
Exemplo Avancado: Plugin Docker Hub
Este exemplo demonstra integracao com API externa:Caso de Uso
- Usar
@dockerhub redispara listar tags - Filtrar tags com “alpine”
- Selecionar a versao mais recente
- Executar
docker run redis:<tag-alpine> - Validar que o container esta rodando
Linguagens Suportadas
Qualquer linguagem que possa criar um executavel, interagir com I/O padrao (stdin/stdout/stderr) e processar argumentos de linha de comando.Recomendacoes por Caso de Uso
| Linguagem | Melhor Para | Vantagens |
|---|---|---|
| Go | Plugins de producao | Binarios estaticos, rapidos, portateis |
| Rust | Performance critica | Seguranca de memoria, velocidade |
| Python | Prototipagem rapida | Ecossistema rico, facil debugging |
| Bash | Scripts de sistema | Integracao nativa com shell |
| Node.js | Integracao com APIs | NPM, async/await |
Seguranca e Melhores Praticas
Validacao de Entrada
Sempre valide argumentos antes de processar. Use
os.Exit(1) para sinalizar erros ao ChatCLI.Tratamento de Erros
Exit code diferente de 0 sinaliza erro para o ChatCLI. Envie mensagens de erro via
stderr.Timeouts Internos
Use
context.WithTimeout para evitar que operacoes externas travem o plugin indefinidamente.Logs Informativos
Envie progresso via
stderr para que o usuario acompanhe a execucao do plugin em tempo real.Plugins no Modo /coder
O modo /coder e especializado em engenharia de software e utiliza o plugin @coder para executar suas acoes. O@coder e um plugin builtin — ja vem embutido no ChatCLI e funciona sem instalacao.
No /coder, a IA emite chamadas de ferramenta em um formato estrito:
- Primeiro, escreve um bloco
reasoningcurto (2 a 6 linhas) - Em seguida, emite apenas um
tool_callcom args JSON
Proximos Passos
Exemplos de Plugins
Explore os plugins de exemplo no repositorio
Crie seu Primeiro Plugin
Siga o template
@hello nesta pagina para comecarCompartilhe com a Comunidade
Publique plugins no GitHub para o ecossistema ChatCLI
Contribua
Contribua com plugins para o ecossistema ChatCLI
O sistema de plugins e a sua porta de entrada para a verdadeira automacao. Comece a construir suas ferramentas e transforme seu terminal em um colega de equipe.