Detalhes do Projeto Serena

Visão Geral do Projeto

Serena é um poderoso kit de ferramentas de agente de programação inteligente, capaz de transformar grandes modelos de linguagem (LLMs) em agentes de programação totalmente funcionais, trabalhando diretamente em sua base de código. O projeto foi desenvolvido pela Oraios AI e contribuído como código aberto para a comunidade de desenvolvedores.

Principais Características

🚀 Capacidades Essenciais

• Recuperação e edição semântica de código: Fornece capacidades semelhantes a IDEs, extraindo entidades de código em nível de símbolo e utilizando estruturas relacionais.
• Totalmente gratuito e de código aberto: Aumenta as capacidades do seu LLM existente, sem custos adicionais.
• Múltiplas formas de integração: Suporta integração com o servidor MCP, framework Agno e frameworks de agentes personalizados.

🔧 Vantagens Técnicas

• Baseado no Protocolo de Servidor de Linguagem (LSP): Fornece uma variedade de funcionalidades de consulta e edição de código através do LSP, amplamente implementado.
• Compreensão em nível de símbolo: Realiza descoberta e edição baseadas na compreensão simbólica do código, como um desenvolvedor experiente usando um IDE.
• Eficiente e preciso: Encontra eficientemente o contexto correto e executa as ações corretas, mesmo em projetos grandes e complexos.

Linguagens de Programação Suportadas

Suporte Direto (Pronto para Uso)

• Python
• Java (Atenção: Inicialização lenta, especialmente na primeira vez)
• TypeScript

Essas linguagens são suportadas pela biblioteca de servidor de linguagem multilspy usada pelo Serena.

Formas de Integração

1. Protocolo de Contexto de Modelo (MCP)

Serena fornece um servidor MCP que pode ser integrado com os seguintes clientes:

• Claude Desktop
• IDEs (como VSCode, Cursor, IntelliJ)
• Extensões (como Cline, Roo Code)
• Goose (fornece uma boa experiência CLI)
• E muitos outros clientes, incluindo o aplicativo ChatGPT, que será suportado em breve.

2. Framework Agno

Através do Agno (um framework de agente independente de modelo), Serena pode transformar quase qualquer LLM em um agente de programação inteligente, suportando:

• Modelos de API pagos fornecidos por Google, OpenAI, Anthropic
• Modelos gratuitos fornecidos por Ollama, Together, Anyscale

3. Frameworks de Agentes Personalizados

A implementação das ferramentas do Serena é desacoplada do código específico do framework, facilitando a adaptação a qualquer framework de agente.

Casos de Uso

Serena pode ser usado para qualquer tarefa de programação, incluindo:

• Análise de código
• Planejamento de projetos
• Design de novos componentes
• Refatoração de código existente
• Tarefas de programação autônomas completas, desde a análise inicial até a implementação, teste e, finalmente, o commit no sistema de controle de versão.

Começo Rápido

Instalação Básica

1. Instale o uv (consulte a documentação oficial para instruções de instalação: https://docs.astral.sh/uv/getting-started/installation/)
2. Clone o repositório para /path/to/serena
3. Copie serena_config.template.yml para serena_config.yml e ajuste as configurações
4. Copie myproject.template.yml para myproject.yml e ajuste as configurações específicas do projeto
5. Para alternar dinamicamente entre projetos, adicione todos os arquivos de projeto à lista projects em serena_config.yml

Integração com Claude Desktop

1. Crie um arquivo de configuração de projeto myproject.yml
2. Configure o servidor MCP no Claude Desktop:
   • Abra File / Settings / Developer / MCP Servers / Edit Config
   • Adicione o seguinte em claude_desktop_config.json:

   {
     "mcpServers": {
       "serena": {
         "command": "/abs/path/to/uv",
         "args": ["run", "--directory", "/abs/path/to/serena", "serena-mcp-server", "--project-file", "/abs/path/to/myproject.yml"]
       }
     }
   }
   

3. Salve a configuração e reinicie o Claude Desktop

Usando o Goose CLI

1. Instale o goose
2. Use goose configure para adicionar uma extensão
3. Selecione "Command-line Extension" e nomeie-a como "Serena"
4. Adicione o comando: /abs/path/to/uv run --directory /abs/path/to/serena serena-mcp-server /optional/abs/path/to/project.yml
5. Desative a extensão developer padrão

Usando o Agno GUI

1. Baixe o código do agent-ui: npx create-agent-ui@latest
2. Instale o Serena: uv pip install --all-extras -r pyproject.toml -e .
3. Copie .env.example para .env e preencha as chaves da API
4. Inicie o agente Agno: uv run python scripts/agno_agent.py
5. Inicie a UI: cd agent-ui && pnpm dev

Ferramentas e Configuração

Principais Categorias de Ferramentas

• Ferramentas de recuperação semântica de código: Encontre símbolos, referências, trechos de código
• Ferramentas de edição de código: Insira, substitua, exclua código
• Operações do sistema de arquivos: Leia, crie, liste arquivos e diretórios
• Execução de shell: Execute comandos shell
• Gerenciamento de projetos: Ative projetos, orientação inicial, gerenciamento de memória

Considerações de Segurança

• O uso de todas as ferramentas é geralmente recomendado para fornecer o máximo de valor
• A ferramenta execute_shell_command permite a execução de código arbitrário e deve ser usada com cautela
• Comandos específicos podem ser desativados no arquivo de configuração do projeto
• Suporte para modo somente leitura (read_only: true), permitindo apenas análise e sugestões, sem modificar a base de código

Comparação com Outros Agentes de Programação

Comparado com Agentes Baseados em Assinatura (Windsurf, Cursor, VSCode)

Vantagens:

• Sem taxas de assinatura
• Não vinculado a um IDE específico
• Não vinculado a um modelo de linguagem grande ou API específico
• Usa servidores de linguagem para compreensão de código em nível de símbolo
• Código aberto e base de código pequena, fácil de estender e modificar

Desvantagens:

• Não integrado diretamente ao IDE, a inspeção de novo código não é tão perfeita quanto as ferramentas integradas ao IDE

Comparado com Agentes Baseados em API (Claude Code, Cline, Aider)

Vantagens:

• Pode ser usado como um servidor MCP, sem chaves de API, evitando custos de API
• Esta é uma característica única do Serena

Semelhanças:

• Ambos podem ser usados como agentes básicos de API
• Ambos são poderosos, a principal desvantagem são os custos de API potencialmente altos

Comparado com Outros Servidores MCP

• Entende-se que outros servidores MCP relacionados à programação (como DesktopCommander, codemcp) não fornecem ferramentas de recuperação e edição semântica de código
• Eles dependem de análise puramente baseada em texto
• A integração do Serena de servidores de linguagem e MCP o torna único e poderoso ao lidar com tarefas de programação desafiadoras em grandes bases de código

Orientação Inicial e Sistema de Memória

Orientação Inicial

• Por padrão, o Serena executa um processo de orientação inicial quando é iniciado pela primeira vez para um projeto
• O objetivo é familiarizar o Serena com o projeto e armazenar memórias para uso em interações futuras

Sistema de Memória

• Os arquivos de memória são armazenados em .serena/memories/ no diretório do projeto
• Os agentes podem optar por ler esses arquivos
• Os usuários podem ler e ajustar os arquivos de memória conforme necessário ou adicionar manualmente novos arquivos de memória
• O sistema de memória melhora significativamente a experiência do usuário com o Serena

Recomendações de Uso

Seleção de Modelo

• A versão não pensante do Claude 3.7 parece funcionar melhor do que a versão pensante
• O Gemini teve um bom desempenho em experimentos preliminares, mas ainda não suporta MCP
• O Gemini é relativamente barato e pode lidar com enormes comprimentos de contexto

Melhores Práticas

1. Controle de versão: É melhor começar as tarefas de geração de código a partir de um estado git limpo
2. Configuração do Windows: Configure git config --global core.autocrlf true no Windows
3. Estrutura do código: Use código bem estruturado, modular e com anotações de tipo
4. Teste e registro: Inclua informações de registro detalhadas e testes significativos
5. Planejamento primeiro: Para tarefas complexas, conceitue e planeje primeiro
6. Gerenciamento de contexto: Para tarefas longas, você pode criar resumos e continuar em novas conversas

Lista Completa de Ferramentas

A seguir está a lista completa de todas as ferramentas do Serena:

• activate_project: Ativa o projeto por nome
• check_onboarding_performed: Verifica se a orientação inicial foi realizada
• create_text_file: Cria/sobrescreve um arquivo no diretório do projeto
• delete_lines: Exclui um intervalo de linhas em um arquivo
• delete_memory: Exclui uma memória do armazenamento de memória específico do projeto do Serena
• execute_shell_command: Executa um comando shell
• find_referencing_code_snippets: Encontra trechos de código que referenciam um símbolo em um determinado local
• find_referencing_symbols: Encontra símbolos que referenciam um símbolo em um determinado local
• find_symbol: Executa uma pesquisa de símbolo global (ou local)
• get_active_project: Obtém o nome do projeto ativo atual
• get_symbols_overview: Obtém uma visão geral dos símbolos de nível superior em um arquivo ou diretório
• insert_after_symbol: Insere conteúdo após o final da definição de um símbolo
• insert_at_line: Insere conteúdo em uma determinada linha de um arquivo
• insert_before_symbol: Insere conteúdo antes do início da definição de um símbolo
• list_dir: Lista arquivos e diretórios em um diretório
• list_memories: Lista memórias no armazenamento de memória
• onboarding: Executa a orientação inicial
• prepare_for_new_conversation: Prepara para uma nova conversa
• read_file: Lê um arquivo no diretório do projeto
• read_memory: Lê uma memória com o nome especificado
• replace_lines: Substitui um intervalo de linhas em um arquivo por novo conteúdo
• replace_symbol_body: Substitui a definição completa de um símbolo
• restart_language_server: Reinicia o servidor de linguagem
• search_for_pattern: Procura um padrão no projeto
• summarize_changes: Fornece um resumo das alterações na base de código
• think_about_collected_information: Ferramenta de pensamento para considerar a integridade das informações coletadas
• think_about_task_adherence: Ferramenta de pensamento para determinar se o agente ainda está no caminho certo para a tarefa atual
• think_about_whether_you_are_done: Ferramenta de pensamento para determinar se a tarefa está realmente concluída
• write_memory: Grava uma memória nomeada no armazenamento de memória para referência futura

Resumo

Serena é um poderoso kit de ferramentas de agente de programação inteligente, totalmente de código aberto, que oferece aos desenvolvedores uma solução de assistente de programação de IA gratuita e poderosa, por meio da compreensão semântica do código e de múltiplas formas de integração. Seja através da integração com o Claude Desktop via servidor MCP, ou através do uso de vários LLMs via framework Agno, Serena pode melhorar significativamente a eficiência da programação e a qualidade do código.