Visão Geral da Arquitetura do Qwen Code

Este documento fornece uma visão geral de alto nível da arquitetura do Qwen Code.

Componentes Principais

O Qwen Code é composto principalmente por dois pacotes principais, juntamente com um conjunto de ferramentas que podem ser utilizadas pelo sistema durante o processamento de entrada da linha de comando:

1. Pacote CLI (`packages/cli`)

Objetivo: Contém a parte do Qwen Code voltada para o usuário, como o tratamento da entrada inicial do usuário, a apresentação da saída final e o gerenciamento da experiência geral do usuário.

Funções Principais:

Processamento de Entrada: Lida com a entrada do usuário através de vários métodos, incluindo entrada de texto direta, comandos de barra (ex.: /help, /clear, /model), comandos arroba (@file para incluir conteúdo de arquivo) e comandos de exclamação (!command para execução no shell).
Gerenciamento de Histórico: Mantém o histórico da conversa e permite recursos como retomada de sessão.
Renderização de Exibição: Formata e apresenta as respostas ao usuário no terminal com destaque de sintaxe e formatação adequada.
Personalização de Tema e Interface: Suporta temas personalizáveis e elementos de interface para uma experiência personalizada.
Configurações: Gerencia várias opções de configuração através de arquivos de configuração JSON, variáveis de ambiente e argumentos de linha de comando.

2. Pacote Core (`packages/core`)

Objetivo: Atua como o backend do Qwen Code. Ele recebe requisições enviadas pelo packages/cli, orquestra interações com a API do modelo configurado e gerencia a execução das ferramentas disponíveis.

Funções Principais:

Cliente API: Comunica-se com a API do modelo Qwen para enviar prompts e receber respostas.
Construção de Prompt: Constrói prompts adequados para o modelo, incorporando histórico da conversa e definições de ferramentas disponíveis.
Registro e Execução de Ferramentas: Gerencia o registro das ferramentas disponíveis e as executa com base nas solicitações do modelo.
Gerenciamento de Estado: Mantém informações de estado da conversa e da sessão.
Configuração do Lado do Servidor: Lida com a configuração e ajustes do lado do servidor.

3. Ferramentas (`packages/core/src/tools/`)

Objetivo: São módulos individuais que estendem as capacidades do modelo Qwen, permitindo que ele interaja com o ambiente local (ex.: sistema de arquivos, comandos shell, busca na web).

Interação: O packages/core invoca essas ferramentas com base em solicitações do modelo Qwen.

Ferramentas Comuns Incluem:

Operações de Arquivo: Leitura, escrita e edição de arquivos
Comandos Shell: Execução de comandos do sistema com aprovação do usuário para operações potencialmente perigosas
Ferramentas de Busca: Localização de arquivos e pesquisa de conteúdo dentro do projeto
Ferramentas Web: Obtenção de conteúdo da web
Integração MCP: Conexão a servidores Model Context Protocol para capacidades estendidas

Fluxo de Interação

Uma interação típica com o Qwen Code segue este fluxo:

Entrada do Usuário: O usuário digita um prompt ou comando no terminal, que é gerenciado pelo packages/cli.
Requisição ao Core: O packages/cli envia a entrada do usuário para o packages/core.
Processamento da Requisição: O pacote core:
- Constrói um prompt apropriado para a API do modelo configurado, possivelmente incluindo histórico da conversa e definições de ferramentas disponíveis.
- Envia o prompt para a API do modelo.
Resposta da API do Modelo: A API do modelo processa o prompt e retorna uma resposta. Essa resposta pode ser uma resposta direta ou uma solicitação para usar uma das ferramentas disponíveis.
Execução da Ferramenta (se aplicável):
- Quando a API do modelo solicita uma ferramenta, o pacote core se prepara para executá-la.
- Se a ferramenta solicitada puder modificar o sistema de arquivos ou executar comandos shell, o usuário recebe primeiro os detalhes da ferramenta e seus argumentos, e deve aprovar a execução.
- Operações somente leitura, como leitura de arquivos, podem não exigir confirmação explícita do usuário para prosseguir.
- Uma vez confirmado, ou se a confirmação não for necessária, o pacote core executa a ação relevante dentro da ferramenta relevante, e o resultado é enviado de volta para a API do modelo pelo pacote core.
- A API do modelo processa o resultado da ferramenta e gera uma resposta final.
Resposta para o CLI: O pacote core envia a resposta final de volta para o pacote CLI.
Exibição para o Usuário: O pacote CLI formata e exibe a resposta para o usuário no terminal.

Opções de Configuração

O Qwen Code oferece várias maneiras de configurar seu comportamento:

Camadas de Configuração (em ordem de precedência)

Argumentos de linha de comando
Variáveis de ambiente
Arquivo de configuração do projeto (.qwen/settings.json)
Arquivo de configuração do usuário (~/.qwen/settings.json)
Arquivos de configuração do sistema
Valores padrão

Principais Categorias de Configuração

Configurações Gerais: modo vim, editor preferido, preferências de atualização automática
Configurações de Interface: Personalização de tema, visibilidade do banner, exibição do rodapé
Configurações de Modelo: Seleção de modelo, limites de turnos de sessão, configurações de compactação
Configurações de Contexto: Nomes de arquivos de contexto, inclusão de diretórios, filtragem de arquivos
Configurações de Ferramentas: Modos de aprovação, sandboxing, restrições de ferramentas
Configurações de Privacidade: Coleta de estatísticas de uso
Configurações Avançadas: Opções de depuração, comandos personalizados de relatório de bugs

Principais Princípios de Design

Modularidade: Separar o CLI (frontend) do Core (backend) permite o desenvolvimento independente e possíveis extensões futuras (ex.: diferentes frontends para o mesmo backend).
Extensibilidade: O sistema de ferramentas foi projetado para ser extensível, permitindo que novas capacidades sejam adicionadas através de ferramentas personalizadas ou integração com servidores MCP.
Experiência do Usuário: O CLI foca em fornecer uma experiência de terminal rica e interativa com recursos como destaque de sintaxe, temas personalizáveis e estruturas de comando intuitivas.
Segurança: Implementa mecanismos de aprovação para operações potencialmente perigosas e opções de sandboxing para proteger o sistema do usuário.
Flexibilidade: Suporta múltiplos métodos de configuração e pode se adaptar a diferentes fluxos de trabalho e ambientes.