---
title: Referência do sistema de ferramentas
description: Referência completa do sistema de ferramentas do Verdent
---
### O que você vai aprender
Referência abrangente do sistema de ferramentas integrado do Verdent, incluindo operações com arquivos, recursos de busca, execução de comandos e ferramentas de integração.
---
## Visão geral das ferramentas disponíveis
O Verdent for VS Code oferece um conjunto abrangente de ferramentas para manipulação, navegação e interação externa de código.
| Ferramenta | Finalidade | Principais recursos |
|------|---------|------------------|
| `file_read` | Ler o conteúdo de arquivos | Suporta intervalos de linhas para arquivos grandes, funciona com todos os formatos de texto |
| `file_edit` | Modificações direcionadas | Substitui correspondências exatas de texto, múltiplas substituições, preserva a formatação |
| `file_write` | Criar ou sobrescrever arquivos | Criação/substituição completa de arquivos, lida com conteúdo de texto |
| Ferramenta | Finalidade | Principais recursos |
|------|---------|------------------|
| `glob` | Busca de arquivos baseada em padrões | Padrões glob (`**/*.ts`), padrões de exclusão, limitação de resultados |
| `grep_content` | Busca de conteúdo com contexto | Suporte a regex, linhas de contexto, opções sem distinção entre maiúsculas e minúsculas |
| `grep_file` | Listar arquivos com correspondências | Identifica rapidamente arquivos antes de ler o conteúdo |
| `list_dir` | Estrutura de diretórios | Mostra a hierarquia, padrões de exclusão, controle de profundidade |
| Ferramenta | Finalidade | Principais recursos |
|------|---------|------------------|
| `bash` | Execução de comandos de shell | Configuração de tempo limite, descrições resumidas, encadeamento de comandos |
| `spawn_subagent` | Delegar a especialistas | Inicia subagentes general, explorer, verifier ou code-reviewer |
| `todo_update` | Acompanhar o progresso das tarefas | Gerencia listas de tarefas, atualiza status, acompanha o progresso |
| Ferramenta | Finalidade | Principais recursos |
|------|---------|------------------|
| `web_search` | Busca na internet | Execução de consultas, controle do número de resultados, filtragem por atualidade |
| `web_fetch` | Buscar e analisar páginas | Recupera conteúdo, extrai informações com consultas |
---
## Recursos e casos de uso das ferramentas
### file_read
**Recursos:**
- Ler o conteúdo completo de arquivos ou intervalos de linhas específicos
- Essencial para entender o código antes de fazer modificações
- Manuseio eficiente de arquivos grandes por meio da especificação de intervalos
**Casos de uso:**
- Ler arquivos de configuração antes de editá-los
- Entender padrões de implementação existentes
- Revisar arquivos de teste para entender a cobertura
**Exemplo:**
```bash
# Read entire file
file_read("src/components/Button.tsx")
# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)
```
---
### file_edit
**Recursos:**
- Substituição precisa de texto usando correspondência exata de strings
- Múltiplas operações de substituição com a flag `multiple`
- Preserva a estrutura e a formatação do arquivo
**Casos de uso:**
- Atualizar implementações de funções
- Modificar valores de configuração
- Refatorar nomes de variáveis em vários arquivos
**Boa prática:** Use para alterações direcionadas. Para reescritas completas, use `file_write`.
---
### file_write
**Recursos:**
- Criar novos arquivos do zero
- Substituir completamente o conteúdo de arquivos existentes
- Lidar com qualquer formato baseado em texto
**Casos de uso:**
- Gerar novos componentes ou módulos
- Criar arquivos de configuração
- Escrever arquivos de teste
**Aviso:** Sobrescreve completamente os arquivos existentes. Use `file_edit` para modificações parciais.
### glob
**Recursos:**
- Encontrar arquivos que correspondam a padrões: `**/*.ts`, `src/**/*.js`
- Filtrar por caminho de diretório
- Padrões de exclusão para restringir os resultados
- Controlar o número de resultados
**Casos de uso:**
- Encontrar todos os componentes em um projeto
- Localizar arquivos de teste
- Identificar arquivos de configuração em diretórios
**Exemplos de padrões:**
```bash
**/*.tsx # All TypeScript React files
src/**/*.test.js # All test files in src
**/config.* # All config files anywhere
```
---
### grep_content
**Recursos:**
- Buscar o conteúdo de arquivos usando padrões regex
- Mostrar linhas de contexto antes/depois das correspondências (flags `-B`, `-A`)
- Busca sem distinção entre maiúsculas e minúsculas
- Filtrar por tipo de arquivo usando padrões glob
**Casos de uso:**
- Encontrar definições de funções
- Localizar implementações de endpoints de API
- Buscar mensagens de erro específicas
- Identificar padrões de segurança
**Exemplo:**
```bash
# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")
# Search with context
grep_content("TODO", glob="src/**", context_before=2, context_after=2)
```
---
### grep_file
**Recursos:**
- Listar arquivos que contenham correspondências de padrões
- Mais rápido que `grep_content` quando você só precisa das localizações dos arquivos
- Suporte a padrões regex
- Filtragem glob para tipos de arquivo
**Casos de uso:**
- Identificar quais arquivos precisam de refatoração
- Encontrar arquivos que importam módulos específicos
- Localizar arquivos com padrões obsoletos
**Boa prática:** Use `grep_file` primeiro para identificar os arquivos relevantes e, em seguida, `file_read` para um exame detalhado.
---
### list_dir
**Recursos:**
- Exibir a hierarquia de diretórios
- Controlar a profundidade com o parâmetro `max_depth`
- Padrões de exclusão para filtrar a saída
**Casos de uso:**
- Entender a estrutura do projeto
- Verificar a organização dos diretórios
- Encontrar subdiretórios específicos
### bash
**Recursos:**
- Executar comandos de shell
- Tempo limite máximo: 120 segundos (2 minutos, limite rígido)
- Encadear comandos com `&&` para dependências
- Fornecer resumos descritivos para maior clareza
**Casos de uso:**
- Executar testes
- Compilar projetos
- Instalar dependências
- Operações de Git
- Migrações de banco de dados
**Exemplo:**
```bash
# Run tests
bash("npm test", timeout=60000, summary="Run Jest test suite")
# Chain dependent commands
bash("npm install && npm run build", timeout=120000)
```
**Segurança:** Os comandos são executados com as permissões do usuário. Revise os comandos em Manual Accept Mode.
---
### spawn_subagent
**Recursos:**
- Iniciar subagentes especializados com contextos isolados
- Tipos: `explorer`, `verifier`, `code-reviewer`
- Delegar tarefas complexas sem poluir o contexto principal
- Execução paralela de subagentes para maior eficiência
**Casos de uso:**
- **explorer:** Buscar padrões em grandes bases de código
- **verifier:** Validar a lógica da implementação
- **code-reviewer:** Avaliação de segurança e qualidade
**Boa prática:** Delegue pesquisas exploratórias ao subagente Explorer para preservar o contexto da conversa principal.
---
### todo_update
**Recursos:**
- Criar e gerenciar listas de tarefas
- Atualizar o status das tarefas (pending, in_progress, completed)
- Acompanhar o progresso em implementações complexas
**Casos de uso:**
- Dividir recursos de várias etapas
- Acompanhar o progresso da refatoração
- Gerenciar tarefas de migração
### web_search
**Recursos:**
- Consultar mecanismos de busca na internet
- Controlar o número de resultados
- Filtrar por atualidade (dias recentes)
**Casos de uso:**
- Encontrar documentação de APIs desconhecidas
- Pesquisar mensagens de erro
- Verificar as melhores práticas atuais
---
### web_fetch
**Recursos:**
- Recuperar o conteúdo de páginas web
- Analisar conteúdo com consultas específicas
- Extrair informações estruturadas
**Casos de uso:**
- Ler páginas de documentação
- Analisar a documentação de API
- Extrair exemplos de tutoriais
---
## Suporte a formatos de arquivo
O Verdent funciona com todos os formatos de arquivo baseados em texto por meio de suas ferramentas de operação com arquivos.
| Categoria | Linguagens/Extensões |
|----------|---------------------|
| **Web** | JavaScript, TypeScript, HTML, CSS, SCSS, LESS |
| **Backend** | Python, Java, Go, Rust, C, C++, C#, Ruby, PHP, Perl |
| **Mobile** | Swift, Kotlin, Dart (Flutter), Objective-C |
| **Funcional** | Haskell, Scala, Elixir, Clojure, F# |
| **Scripting** | Bash, PowerShell, Zsh, Fish |
| **Dados** | SQL, R, Julia, MATLAB |
| Formato | Exemplos comuns |
|--------|----------------|
| **JSON** | package.json, tsconfig.json, settings.json |
| **YAML** | docker-compose.yml, GitHub Actions, configurações do Kubernetes |
| **TOML** | Cargo.toml, pyproject.toml |
| **XML** | pom.xml, web.xml, arquivos de configuração |
| **INI** | .gitconfig, .editorconfig |
| **ENV** | arquivos .env, configuração de ambiente |
| **HCL** | Configuração do Terraform |
| Formato | Casos de uso |
|--------|-----------|
| **Markdown** | README.md, arquivos de documentação |
| **HTML** | Templates, páginas web |
| **LaTeX** | Documentos científicos, artigos acadêmicos |
| **reStructuredText** | Documentação Python |
| **AsciiDoc** | Documentação técnica |
### Formatos de dados
| Formato | Descrição |
|--------|-------------|
| **CSV/TSV** | Arquivos de dados tabulares |
| **Dados baseados em texto** | Arquivos de log, dumps de dados |
| **JSON/YAML** | Intercâmbio de dados estruturados |
### Arquivos de build e pacotes
| Arquivo | Finalidade |
|------|---------|
| **Makefile** | Automação de build |
| **package.json** | Dependências do Node.js |
| **requirements.txt** | Pacotes Python |
| **Gemfile** | Gems Ruby |
| **Cargo.toml** | Pacotes Rust |
| **build.gradle** | Builds do Gradle |
| Tipo de formato | Exemplos | Editável |
|-------------|----------|-------------|
| **Imagens** | PNG, JPG, GIF, SVG (binário) | Não editável diretamente |
| **Vídeos** | MP4, AVI, MOV | Não editável diretamente |
| **Binários compilados** | EXE, DLL, SO | Não editável diretamente |
| **Arquivos compactados** | ZIP, TAR, GZ | Não editável diretamente |
| **Documentos do Office** | DOCX, XLSX, PPTX | Não editável diretamente |
| **PDFs** | Arquivos PDF | Não editável diretamente |
Arquivos binários podem ser referenciados no código, mas não podem ser modificados por meio das ferramentas de arquivo.
---
## Suporte a linguagens de programação
O Verdent oferece suporte abrangente a todas as linguagens de programação e frameworks baseados em texto.
| Linguagem/Framework | Nível de suporte | Casos de uso comuns |
|-------------------|---------------|------------------|
| JavaScript | Excelente | Lógica de frontend, backends Node.js, ferramentas |
| TypeScript | Excelente | Apps web type-safe, projetos de larga escala |
| React | Excelente | UIs baseadas em componentes, hooks, gerenciamento de estado |
| Vue | Excelente | Progressive web apps, componentes de arquivo único |
| Angular | Excelente | Apps empresariais, integração com TypeScript |
| Svelte | Muito bom | Componentes compilados, programação reativa |
| HTML/CSS | Excelente | Marcação, estilização, design responsivo |
| SCSS/LESS | Excelente | Estilização avançada, variáveis, mixins |
| Linguagem/Framework | Nível de suporte | Casos de uso comuns |
|-------------------|---------------|------------------|
| Python | Excelente | APIs, processamento de dados, automação |
| Django/Flask/FastAPI | Excelente | Frameworks web, APIs REST |
| Node.js/Express | Excelente | Backends JavaScript, microsserviços |
| Java/Spring | Excelente | Apps empresariais, Spring Boot |
| Go | Excelente | Serviços de alto desempenho, CLIs |
| Rust | Muito bom | Programação de sistemas, código de desempenho crítico |
| C/C++ | Muito bom | Sistemas, embarcados, engines de jogos |
| C# / .NET | Excelente | Apps Windows, serviços web, Unity |
| Ruby/Rails | Muito bom | Apps web, desenvolvimento rápido |
| PHP | Bom | WordPress, Laravel, apps legados |
| Linguagem/Framework | Nível de suporte | Casos de uso comuns |
|-------------------|---------------|------------------|
| Swift | Excelente | Apps nativos iOS/macOS |
| Kotlin | Excelente | Apps nativos Android |
| Dart/Flutter | Excelente | Apps mobile multiplataforma |
| React Native | Excelente | Apps mobile baseados em JavaScript |
| Objective-C | Bom | Apps iOS/macOS legados |
| Linguagem | Nível de suporte | Casos de uso comuns |
|----------|---------------|------------------|
| Python | Excelente | NumPy, Pandas, scikit-learn, TensorFlow |
| R | Muito bom | Análise estatística, visualização de dados |
| SQL | Excelente | Consultas a bancos de dados, design de esquemas |
| Julia | Bom | Computação científica, análise numérica |
| Linguagem | Nível de suporte | Casos de uso comuns |
|----------|---------------|------------------|
| C | Muito bom | Programação de sistemas, embarcados |
| C++ | Muito bom | Apps de desempenho crítico |
| Rust | Muito bom | Programação de sistemas com segurança de memória |
| Go | Excelente | Sistemas concorrentes, serviços de nuvem |
| Assembly | Bom | Otimização de baixo nível, depuração |
**Qualidade do suporte:** Linguagens comuns (JavaScript, Python, TypeScript) têm suporte mais forte devido aos dados de treinamento extensos. Linguagens menos comuns ou específicas de domínio podem ter qualidade de suporte reduzida, mas continuam funcionais.
---
## Limites de uso e melhores práticas
### Eficiência do file_read
**Melhores práticas:**
- Use intervalos de linhas para arquivos com mais de 500 linhas para evitar sobrecarga de contexto
- Leia apenas as seções relevantes necessárias para a tarefa
- Para arquivos grandes, use `grep_content` primeiro para identificar os números de linha relevantes
```bash
# Good: Read specific section
file_read("large-config.json", start_line=100, max_lines=50)
# Less efficient: Read entire large file
file_read("large-config.json") # May consume excessive context
```
---
### Precisão do file_edit
**Melhores práticas:**
- Garanta correspondências exatas de strings para evitar edições com falha
- Para várias alterações semelhantes, use a flag `multiple=true`
- Verifique os caminhos dos arquivos antes de editar
---
### Segurança do file_write
**Melhores práticas:**
- Confira novamente os caminhos para evitar sobrescritas acidentais
- Use apenas para novos arquivos ou reescritas completas
- Para modificações, prefira `file_edit` por segurança
### Especificidade dos padrões glob
**Melhores práticas:**
- Use padrões específicos para restringir o escopo: `src/**/*.ts` em vez de `**/*`
- Exclua diretórios com padrões de exclusão: `!**/node_modules/**`
- Limite os resultados para evitar saídas excessivas
```bash
# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)
# Less efficient: Too broad
glob("**/*") # Returns thousands of results
```
---
### Estratégia de grep
**Fluxo de trabalho recomendado:**
1. Use `grep_file` para identificar os arquivos relevantes
2. Leia arquivos específicos com `file_read`
3. Use `grep_content` quando precisar do contexto ao redor
**Dicas de desempenho:**
- Padrões regex podem levar mais tempo do que strings literais
- Buscas sem distinção entre maiúsculas e minúsculas são mais lentas
- Limite as linhas de contexto (`-A`, `-B`) ao necessário
### Melhores práticas do bash
**Execução segura de comandos:**
- Forneça resumos claros para as descrições dos comandos
- Defina tempos limite apropriados para operações de longa duração
- Encadeie comandos dependentes com `&&`
- Revise comandos destrutivos com cuidado (rm, drop, truncate)
```bash
# Good: Clear summary, reasonable timeout
bash("npm run build", timeout=120000, summary="Build production bundle")
# Good: Chained dependencies
bash("npm install && npm run test", timeout=180000)
```
---
### Considerações de segurança
**Regras de segurança críticas:**
- Os comandos são executados com as permissões do usuário
- Nunca execute comandos não confiáveis
- Use Manual Accept Mode para revisão em bases de código compartilhadas
- Evite comandos que exponham credenciais ou dados sensíveis
Sempre revise os comandos bash em Manual Accept Mode ao trabalhar em bases de código compartilhadas ou ambientes de produção.
### Eficiência na delegação de subagentes
**Quando usar subagentes:**
- **Explorer:** Buscas na base de código, questões de arquitetura (economiza o contexto principal)
- **Verifier:** Verificações rápidas de validação (verificação isolada)
- **Code-reviewer:** Revisões de segurança e qualidade (análise detalhada)
- **General:** Tarefas complexas de várias etapas (execução paralela)
**Boa prática:**
Delegue tarefas exploratórias e de pesquisa a subagentes para preservar o contexto da conversa principal para o trabalho de desenvolvimento ativo.
---
### Gerenciamento de contexto
**Uso estratégico de ferramentas:**
- Leia arquivos de forma estratégica — apenas o necessário
- Use subagentes para pesquisas em segundo plano
- Monitore o consumo de contexto durante sessões longas
- Divida operações complexas em etapas com todo_update
**Fluxos de trabalho eficientes:**
1. **Planejamento:** Use glob/grep para identificar o escopo
2. **Leitura:** Leia apenas os arquivos/seções relevantes
3. **Execução:** Delegue a subagentes quando apropriado
4. **Verificação:** Verificações rápidas com o subagente Verifier
### Limites de tamanho de arquivo
**Manuseio de arquivos grandes:**
Arquivos muito grandes (>10.000 linhas) devem ser lidos em seções para evitar:
- Esgotamento da janela de contexto
- Tempos de resposta lentos
- Problemas de memória
Para arquivos com mais de 500 linhas, sempre use intervalos de linhas com `file_read` para manter o desempenho ideal.
---
### Padrões de tempo limite das ferramentas
**Limites das ferramentas:**
- **Tempo limite do bash:** 120 segundos (2 minutos) no máximo
- **Operações com arquivos:** Sem limites de tamanho (arquivos grandes são lidos automaticamente em lotes)
- **Manuseio de arquivos grandes:** Arquivos >256KB retornam apenas os primeiros 256KB de conteúdo
- **Resultados de busca:** Sem limites para resultados de `glob` ou `grep_content`
- **Subagentes concorrentes:** Sem limites para execução paralela
**Configuração de tempo limite:**
- Defina tempos limite explícitos para operações de longa duração
- Monitore processos travados
- Comandos que excedam o tempo limite de 2 minutos serão encerrados
---
### Operações concorrentes
**Execução paralela:**
Vários subagentes podem ser executados em paralelo para operações complexas mais rápidas. O agente principal lida automaticamente com a coordenação.
**Benefícios de desempenho:**
- Redução do tempo total de execução para tarefas de várias etapas
- Utilização eficiente de recursos
- Orquestração automática de tarefas
- Sem limites no número de subagentes concorrentes
---
## Veja também
Saiba mais sobre agentes especializados
Controle a execução de ferramentas com modos