Checkpoints

Checkpoints versionam automaticamente os arquivos do seu workspace durante as tarefas de reasoning do AI Cockpit, permitindo a exploração não destrutiva de sugestões de IA e a fácil recuperação de alterações indesejadas.

Os checkpoints permitem que você:

• Experimente com segurança as alterações sugeridas pela IA
• Recupere-se facilmente de modificações indesejadas
• Compare diferentes abordagens de implementação
• Reverta para estados anteriores do projeto sem perder o trabalho

Notas Importantes

• Checkpoints estão ativados por padrão.
• O Git deve estar instalado para que os checkpoints funcionem - veja as instruções de instalação
• Nenhuma conta ou repositório do GitHub é necessário
• Nenhuma configuração de informações pessoais do Git é necessária
• O repositório Git sombra opera independentemente da configuração Git existente do seu projeto

Opções de Configuração

Acesse as configurações de checkpoint nas configurações de reasoning do AI Cockpit na seção "Checkpoints":

1. Abra as Configurações clicando no ícone de engrenagem → Checkpoints

2. Marque ou desmarque a caixa de seleção "Ativar checkpoints automáticos"

   

Como os Checkpoints Funcionam

O reasoning do AI Cockpit captura snapshots do estado do seu projeto usando um repositório Git sombra, separado do seu sistema de controle de versão principal. Esses snapshots, chamados de checkpoints, registram automaticamente as alterações ao longo do seu fluxo de trabalho assistido por IA - sempre que as tarefas começam, os arquivos mudam ou os comandos são executados.

Os checkpoints são armazenados como commits Git no repositório sombra, capturando:

• Alterações no conteúdo do arquivo
• Novos arquivos adicionados
• Arquivos excluídos
• Arquivos renomeados
• Alterações em arquivos binários

Trabalhando com Checkpoints

Os checkpoints são integrados diretamente ao seu fluxo de trabalho através da interface de chat.

Os checkpoints aparecem diretamente no seu histórico de chat de duas formas:

• Checkpoint inicial marca o estado inicial do seu projeto

  

• Checkpoints regulares aparecem após modificações de arquivos ou execução de comandos

  

Cada checkpoint oferece duas funções principais:

Visualizando Diferenças

Para comparar seu workspace atual com um checkpoint anterior:

1. Localize o checkpoint no seu histórico de chat

2. Clique no botão View Differences do checkpoint

   

3. Revise as diferenças na visão de comparação:

   • Linhas adicionadas são destacadas em verde
   • Linhas removidas são destacadas em vermelho
   • Arquivos modificados são listados com alterações detalhadas
   • Arquivos renomeados e movidos são rastreados com suas alterações de caminho
   • Arquivos novos ou excluídos são claramente marcados

Restaurando Checkpoints

Para restaurar um projeto para um estado de checkpoint anterior:

1. Localize o checkpoint no seu histórico de chat

2. Clique no botão Restore Checkpoint do checkpoint

   

3. Escolha uma destas opções de restauração:

   

   • Restaurar Apenas Arquivos - Reverte apenas os arquivos do workspace para o estado do checkpoint sem modificar o histórico da conversa. Ideal para comparar implementações alternativas enquanto mantém o contexto do chat, permitindo que você alterne sem problemas entre diferentes estados do projeto. Esta opção não requer confirmação e permite alternar rapidamente entre diferentes implementações.

   • Restaurar Arquivos e Tarefa - Reverte tanto os arquivos do workspace QUANTO remove todas as mensagens de conversa subsequentes. Use quando quiser redefinir completamente tanto seu código quanto sua conversa para o ponto no tempo do checkpoint. Esta opção requer confirmação em um diálogo, pois não pode ser desfeita.

     

Limitações e Considerações

• Escopo: Checkpoints capturam apenas as alterações feitas durante as tarefas ativas de reasoning do AI Cockpit
• Alterações externas: Modificações feitas fora das tarefas (edições manuais, outras ferramentas) não são incluídas
• Arquivos grandes: Arquivos binários muito grandes podem impactar o desempenho
• Trabalho não salvo: A restauração substituirá quaisquer alterações não salvas no seu workspace

Implementação Técnica

Arquitetura de Checkpoint

O sistema de checkpoint consiste em:

1. Repositório Git Sombra: Um repositório Git separado criado especificamente para o rastreamento de checkpoints que funciona como o mecanismo de armazenamento persistente para o estado do checkpoint.

2. Serviço de Checkpoint: Lida com operações Git e gerenciamento de estado através de:

   • Inicialização do repositório
   • Criação e armazenamento de checkpoint
   • Computação de diferenças
   • Restauração de estado

3. Componentes de UI: Elementos de interface exibidos no chat que permitem a interação com os checkpoints.

Processo de Restauração

Quando a restauração é executada, o reasoning do AI Cockpit:

• Realiza um reset forçado para o commit do checkpoint especificado
• Copia todos os arquivos do repositório sombra para o seu workspace
• Atualiza o estado de rastreamento interno do checkpoint

Tipo de Armazenamento

Os checkpoints têm escopo de tarefa, o que significa que são específicos para uma única tarefa.

Computação de Diferenças

A comparação de checkpoints usa as capacidades de diferenciação subjacentes do Git para produzir diferenças de arquivos estruturadas:

• Arquivos modificados mostram alterações linha por linha
• Arquivos binários são detectados e tratados adequadamente
• Arquivos renomeados e movidos são rastreados corretamente
• A criação e exclusão de arquivos são claramente identificadas

Exclusão de Arquivos e Padrões de Ignorar

O sistema de checkpoint usa exclusão inteligente de arquivos para rastrear apenas os arquivos relevantes:

Exclusões Embutidas

O sistema possui padrões de exclusão embutidos abrangentes que ignoram automaticamente:

• Artefatos de compilação e diretórios de dependência (node_modules/, dist/, build/)
• Arquivos de mídia e ativos binários (imagens, vídeos, áudio)
• Arquivos de cache e temporários (.cache/, .tmp/, .bak)
• Arquivos de configuração com informações sensíveis (.env)
• Arquivos de dados grandes (arquivos compactados, executáveis, binários)
• Arquivos de banco de dados e logs

Esses padrões são escritos no arquivo .git/info/exclude do repositório sombra durante a inicialização.

Suporte ao .gitignore

O sistema de checkpoint respeita os padrões do .gitignore no seu workspace:

• Arquivos excluídos pelo .gitignore não acionarão a criação de checkpoint
• Arquivos excluídos não aparecerão nas diferenças de checkpoint
• Regras de ignorar padrão do Git se aplicam ao preparar as alterações de arquivos

Comportamento do .aicockpitcodeignore

O arquivo .aicockpitcodeignore (que controla o acesso da IA aos arquivos) é separado do rastreamento de checkpoint:

• Arquivos excluídos pelo .aicockpitcodeignore mas não pelo .gitignore ainda serão checkpointed
• Alterações em arquivos inacessíveis à IA ainda podem ser restauradas através de checkpoints

Essa separação é intencional, pois o .aicockpitcodeignore limita quais arquivos a IA pode acessar, não quais arquivos devem ser rastreados para o histórico de versões.

Repositórios Git Aninhados

O sistema de checkpoint inclui tratamento especial para repositórios Git aninhados:

• Renomeia temporariamente os diretórios .git aninhados para .git_disabled durante as operações
• Restaura-os após a conclusão das operações
• Permite o rastreamento adequado de arquivos em repositórios aninhados
• Garante que os repositórios aninhados permaneçam funcionais e não afetados

Controle de Concorrência

As operações são enfileiradas para evitar operações Git concorrentes que possam corromper o estado do repositório. Isso garante que as operações rápidas de checkpoint sejam concluídas com segurança, mesmo quando solicitadas em rápida sucessão.

Instalação do Git

Os checkpoints exigem que o Git esteja instalado no seu sistema. A implementação usa a biblioteca simple-git, que depende das ferramentas de linha de comando do Git para criar e gerenciar repositórios sombra.

macOS

1. Instale com o Homebrew (recomendado):

   brew install git

2. Alternativa: Instale com as Ferramentas de Linha de Comando do Xcode:

   xcode-select --install

3. Verifique a instalação:

   • Abra o Terminal
   • Digite git --version
   • Você deve ver um número de versão como git version 2.40.0

Windows

1. Baixe o Git para Windows:

   • Visite https://git-scm.com/download/win
   • O download deve começar automaticamente

2. Execute o instalador:

   • Aceite o contrato de licença
   • Escolha o local de instalação (o padrão é recomendado)
   • Selecione os componentes (as opções padrão geralmente são suficientes)
   • Escolha o editor padrão
   • Escolha como usar o Git a partir da linha de comando (recomendado: Git a partir da linha de comando e também de software de terceiros)
   • Configure as conversões de final de linha (recomendado: Checkout no estilo Windows, commit no estilo Unix)
   • Conclua a instalação

3. Verifique a instalação:

   • Abra o Prompt de Comando ou o PowerShell
   • Digite git --version
   • Você deve ver um número de versão como git version 2.40.0.windows.1

Linux

Debian/Ubuntu:

sudo apt update
sudo apt install git

Fedora:

sudo dnf install git

Arch Linux:

sudo pacman -S git

Verifique a instalação:

• Abra o Terminal
• Digite git --version
• Você deve ver um número de versão