write_to_file

A ferramenta write_to_file cria novos arquivos ou substitui completamente o conteúdo de arquivos existentes com um processo de aprovação interativo. Ela fornece uma visualização de diferenças para revisar as alterações antes que sejam aplicadas.

Parâmetros

A ferramenta aceita estes parâmetros:

• path (obrigatório): O caminho do arquivo para escrever, relativo ao diretório de trabalho atual
• content (obrigatório): O conteúdo completo para escrever no arquivo
• line_count (obrigatório): O número de linhas no arquivo, incluindo linhas vazias

O Que Faz

Esta ferramenta escreve o conteúdo em um arquivo especificado, criando um novo arquivo se ele não existir ou sobrescrevendo completamente um arquivo existente. Todas as alterações exigem a aprovação explícita do usuário através de uma interface de visualização de diferenças, onde os usuários podem revisar e até mesmo editar as alterações propostas antes que sejam aplicadas.

Quando é usada?

• Quando o AI Cockpit Reasoning precisa criar um novo arquivo do zero
• Quando o AI Cockpit Reasoning precisa reescrever completamente um arquivo existente
• Ao criar vários arquivos para um novo projeto
• Ao gerar arquivos de configuração, documentação ou código-fonte
• Quando você precisa revisar as alterações antes que sejam aplicadas

Principais Características

• Aprovação Interativa: Mostra as alterações em uma visualização de diferenças que exige aprovação explícita antes de aplicar
• Suporte à Edição do Usuário: Permite editar o conteúdo proposto antes da aprovação final
• Medidas de Segurança: Detecta a omissão de código, valida caminhos e evita conteúdo truncado
• Integração com o Editor: Abre uma visualização de diferenças que rola automaticamente para a primeira diferença
• Pré-processamento de Conteúdo: Lida com artefatos de diferentes modelos de IA para garantir um conteúdo limpo
• Controle de Acesso: Valida em relação às restrições do .aicockpitcodeignore antes de fazer alterações
• Diretórios Pais: Pode lidar com a criação de diretórios através de dependências do sistema
• Substituição Completa: Fornece um arquivo totalmente transformado em uma única operação

Limitações

• Não é adequado para arquivos existentes: Muito mais lento e menos eficiente que o apply_diff para modificar arquivos existentes
• Desempenho com arquivos grandes: A operação se torna significativamente mais lenta com arquivos maiores
• Sobrescrita completa: Substitui todo o conteúdo do arquivo, não pode preservar o conteúdo original
• Contagem de linhas necessária: Precisa de uma contagem de linhas precisa para detectar um possível truncamento de conteúdo
• Sobrecarga de revisão: O processo de aprovação adiciona etapas extras em comparação com as edições diretas
• Apenas interativo: Não pode ser usado em fluxos de trabalho automatizados que exigem execução não interativa

Como Funciona

Quando a ferramenta write_to_file é invocada, ela segue este processo:

1. Validação de Parâmetros: Valida os parâmetros e permissões necessários

   • Verifica se path, content e line_count foram fornecidos
   • Valida se o arquivo é permitido (não restrito pelo .aicockpitcodeignore)
   • Garante que o caminho esteja dentro dos limites do espaço de trabalho
   • Rastreia a contagem de erros consecutivos para parâmetros ausentes
   • Mostra mensagens de erro específicas para cada falha de validação

2. Pré-processamento de Conteúdo:

   • Remove marcadores de bloco de código que podem ser adicionados por modelos de IA
   • Lida com entidades HTML escapadas (especificamente para modelos não-Claude)
   • Remove números de linha se incluídos acidentalmente no conteúdo
   • Realiza o processamento específico do modelo para diferentes provedores de IA

3. Geração da Visualização de Diferenças:

   • Abre uma visualização de diferenças no editor mostrando as alterações propostas
   • Adiciona um atraso de 300ms para garantir a capacidade de resposta da interface do usuário
   • Rola automaticamente para a primeira diferença
   • Destaca as alterações para facilitar a revisão

4. Processo de Aprovação do Usuário:

   • Aguarda a aprovação explícita do usuário para prosseguir
   • Permite que os usuários editem o conteúdo na visualização de diferenças
   • Captura quaisquer edições do usuário para o conteúdo final
   • Fornece a opção de rejeitar as alterações completamente
   • Detecta e incorpora as modificações do usuário no resultado final

5. Validação de Segurança:

   • Detecta um possível truncamento de conteúdo comparando com a contagem de linhas fornecida
   • Mostra avisos se o conteúdo parecer incompleto
   • Valida o caminho do arquivo e as permissões de acesso
   • Verifica especificamente se os arquivos estão fora do espaço de trabalho com a flag isOutsideWorkspace

6. Escrita do Arquivo:

   • Escreve o conteúdo aprovado (com quaisquer edições do usuário) no arquivo
   • Fornece a confirmação da escrita bem-sucedida
   • Zera o contador de erros consecutivos em caso de sucesso

Exemplos de Quando Usado

• Ao criar um novo projeto, o AI Cockpit Reasoning gera vários arquivos, mas permite que você revise cada um antes de confirmar as alterações.
• Ao configurar arquivos de configuração, o AI Cockpit Reasoning mostra a configuração proposta em uma visualização de diferenças para aprovação.
• Ao gerar documentação, o AI Cockpit Reasoning cria arquivos markdown, mas permite que você faça os ajustes finais na visualização de diferenças.
• Ao desenvolver um protótipo, o AI Cockpit Reasoning mostra arquivos de código-fonte completos em uma visualização de diferenças onde você pode ajustar antes de salvar.

Exemplos de Uso

Criando um novo arquivo de configuração JSON:

<write_to_file>
<path>config/settings.json</path>
<content>
{
  "apiEndpoint": "https://api.example.com",
  "theme": {
    "primaryColor": "#007bff",
    "secondaryColor": "#6c757d",
    "fontFamily": "Arial, sans-serif"
  },
  "features": {
    "darkMode": true,
    "notifications": true,
    "analytics": false
  },
  "version": "1.0.0"
}
</content>
<line_count>14</line_count>
</write_to_file>

Criando um arquivo HTML simples:

<write_to_file>
<path>src/index.html</path>
<content>
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Minha Aplicação</title>
  <link rel="stylesheet" href="styles.css">
</head>
<body>
  <div id="app"></div>
  <script src="app.js"></script>
</body>
</html>
</content>
<line_count>13</line_count>
</write_to_file>

Criando um módulo JavaScript:

<write_to_file>
<path>src/utils/helpers.js</path>
<content>
/**
 * Funções utilitárias para a aplicação
 */

export function formatDate(date) {
  return new Date(date).toLocaleDateString();
}

export function calculateTotal(items) {
  return items.reduce((sum, item) => sum + item.price, 0);
}

export function debounce(func, delay) {
  let timeout;
  return function(...args) {
    clearTimeout(timeout);
    timeout = setTimeout(() => func.apply(this, args), delay);
  };
}
</content>
<line_count>18</line_count>
</write_to_file>