Todas as operações de edição iniciadas pelo Apidog CLI são tratadas como iniciadas por IA / Agentes de IA por padrão.AI Branch foi projetado para fornecer aos Agentes de IA um branch de edição isolado em projetos do Apidog. Com AI Branch, a IA pode criar e atualizar recursos do projeto sem alterar diretamente o branch principal ou um sprint branch padrão. Depois que as alterações forem concluídas, os usuários poderão revisar as diferenças no cliente ou na CLI e, em seguida, mesclar os resultados no branch de destino diretamente ou por meio de uma solicitação de mesclagem.Por Que AI Branch É Necessário#
Edições iniciadas por IA podem ser imprevisíveis, enquanto o Apidog CLI fornece uma ampla variedade de recursos de edição. AI Branch foi projetado para essas operações de edição iniciadas por IA de maior risco, permitindo que Agentes de IA editem recursos do projeto dentro de um escopo controlado.Você também pode atualizar para o Apidog 2.8.31 ou posterior e habilitar permissões de edição direta para o branch principal, sprint branches padrão e branches gerais conforme necessário em Configurações do Projeto -> Configurações de Recursos -> Permissões de Edição por IA Externa. Uma vez habilitadas, essas permissões contornam as restrições de edição direta que normalmente exigem AI Branch.O Que É AI Branch?#
AI Branch é um sprint branch especial. Como um sprint branch padrão, ele armazena alterações em recursos do projeto. No entanto, por padrão, ele é destinado a operações externas de IA, como edições baseadas na CLI, e mantém uma etapa de confirmação humana antes que as alterações sejam mescladas.As principais características de AI Branch incluem:1.
Edição isolada: Alterações feitas a partir da CLI em recursos como APIs, documentação, modelos de dados e cenários de teste são armazenadas no AI Branch e não afetam diretamente o branch principal ou o branch de origem.
2.
Origem clara: AI Branches não podem ser criados diretamente no cliente Apidog. Eles devem ser criados a partir de uma origem CLI ou MCP. Um AI Branch registra seu branch de origem e geralmente é mesclado de volta a esse branch de origem, facilitando a compreensão do contexto das alterações geradas por IA.
3.
Confirmação humana: Alterações em um AI Branch devem ser confirmadas por um usuário antes de serem mescladas. Os usuários podem revisar diferenças, selecionar o escopo dos recursos e escolher se desejam mesclar diretamente ou criar uma solicitação de mesclagem.
4.
Sem limite de quantidade: Atualmente não há limite ativo para o número de AI Branches que podem ser criados. Agentes de IA podem usá-los para processar dados por domínio de negócio, iteração ou recurso.
5.
Arquivamento automático: Para evitar o crescimento descontrolado de AI Branches durante a colaboração no projeto, cada AI Branch é comparado com seu branch de origem a cada 24 horas. Se nenhuma diferença for encontrada, ele será arquivado automaticamente. Você pode restaurar AI Branches arquivados no Apidog a qualquer momento ou recriar novos AI Branches a partir do Apidog CLI, sem qualquer limite.
AI Branch é usado para armazenar resultados de gravação de operações externas de IA ou CLI. A edição normal no cliente, a mesclagem e a revisão por usuários ainda seguem as permissões de membros do projeto e as regras de proteção de branch.
Casos de Uso#
AI Branch é adequado quando a IA precisa participar da manutenção de recursos do projeto, enquanto o isolamento de branch e a confirmação humana ainda devem ser preservados.| Cenário | Descrição |
|---|
| Gerar rascunhos de API a partir do código | Depois de ler o código, a IA cria ou atualiza endpoints de API HTTP em um AI Branch. Os usuários confirmam as alterações antes da mesclagem. |
| Organizar recursos de API em massa | A IA pode ajustar diretórios de API, adicionar descrições e atualizar modelos de dados ou componentes de resposta sem afetar diretamente o branch de colaboração atual. |
| Gerar rascunhos de testes automatizados | A IA pode criar cenários de teste, casos de teste ou dados de teste em um AI Branch para confirmação posterior por testadores. |
| Preencher lacunas na documentação da API | A IA pode complementar campos ausentes com base em relatórios de bug, implementações de API ou arquivos OpenAPI. |
| Gravação em lote em CI/CD | Fluxos de trabalho automatizados podem gravar resultados gerados em um AI Branch e aguardar a revisão do usuário antes da mesclagem. |
Fluxo de Trabalho Básico#
Um fluxo de trabalho típico de AI Branch é o seguinte:1
Crie um AI Branch e especifique o branch de origem no qual ele se baseia.
2
Importe os recursos que precisam ser editados para o AI Branch ou crie novos recursos no AI Branch.
3
Um Agente de IA, a CLI ou um script de automação modifica recursos no AI Branch.
4
O usuário revisa as diferenças entre o AI Branch e o branch de origem e, em seguida, confirma o escopo dos recursos a serem mesclados.
5
Dependendo das regras de proteção do branch de destino, faça a mesclagem diretamente ou crie uma solicitação de mesclagem.
Criar um AI Branch#
Use branch create --type ai para criar um AI Branch. Os pontos de entrada legados sprint-branch e sb permanecem compatíveis, mas o ponto de entrada unificado branch é recomendado.| Comando | Descrição | Exemplo |
|---|
branch create --type ai | Crie um AI Branch. | apidog branch create --project <projectId> --type ai --name "ai/20260312-from-main-userRegister" --from main |
branch list --type ai | Visualize AI Branches em um projeto. | apidog branch list --project <projectId> --type ai |
branch list --type all | Visualize todos os tipos de branch em um projeto. | apidog branch list --project <projectId> --type all |
branch get --type ai | Visualize os detalhes de um AI Branch especificado, incluindo seu tipo de branch e informações de origem. | apidog branch get <branchName> --project <projectId> --type ai |
Exemplo: Criar um AI Branch para a API de registro de usuárioRecomendamos nomear AI Branches no formato ai/YYYYMMDD-from-sourceBranch-featureOrModule, por exemplo, ai/20260312-from-main-userRegister. Um nome claro ajuda a equipe a entender a origem, a finalidade e o horário de criação do branch.
Editar Recursos em um AI Branch#
Quando a CLI grava recursos do projeto, você pode usar parâmetros de branch para gravar esses recursos em um AI Branch. Os parâmetros variam ligeiramente entre comandos de recursos. Antes do uso, verifique a ajuda do comando correspondente e o JSON Schema.| Tipo de Recurso | Comandos Comuns | Exemplo |
|---|
| endpoint de API HTTP | endpoint create, endpoint update | apidog endpoint create --project <projectId> --branch <aiBranchName> --file ./endpoint.json |
| Modelo de dados | schema create, schema update | apidog schema update <schemaId> --project <projectId> --branch <aiBranchName> --file ./schema.json |
| Documento Markdown | doc create, doc update | apidog doc create --project <projectId> --branch <aiBranchName> --file ./doc.json |
| Cenário de teste | test-scenario create, test-scenario update | apidog test-scenario update <scenarioId> --project <projectId> --branch <aiBranchName> --file ./scenario.json |
| Suíte de testes | test-suite create, test-suite update | apidog test-suite create --project <projectId> --branch <aiBranchName> --file ./suite.json |
| Dados de teste | test-data create, test-data update | apidog test-data create --project <projectId> --branch <aiBranchName> --file ./test-data.json |
Ao criar ou atualizar recursos complexos, recomendamos usar cli-schema primeiro para visualizar e validar a estrutura de dados.Importar Recursos do Branch de Origem#
Se um AI Branch precisar modificar recursos existentes, use branch pick-to primeiro para importar recursos do branch de origem para o AI Branch. Após a importação, a IA pode continuar editando esses recursos no AI Branch.| Comando | Descrição | Exemplo |
|---|
branch pick-to | Importe recursos de um branch de origem para um AI Branch de destino. | apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <aiBranchName> --endpoint-ids <ids> |
Exemplo: Importar endpoints e permitir que a IA os modifiquepick-to importa apenas os recursos explicitamente especificados no comando. Se diretórios, modelos de dados, componentes de resposta ou outros recursos relacionados forem necessários, confirme o escopo dos recursos antes da importação.
Visualizar Alterações do AI Branch#
Antes da mesclagem, recomendamos pré-visualizar as alterações candidatas entre o AI Branch e o branch de destino. A CLI pode usar merge-request preview para verificar os tipos de recursos atualmente suportados. Você também pode visualizar diferenças de branch mais completas no cliente.| Comando | Descrição | Exemplo |
|---|
merge-request preview | Verifique alterações candidatas para confirmar o escopo dos recursos antes da mesclagem. | apidog merge-request preview --project <projectId> --from <aiBranchName> --to <targetBranchName> |
branch get --type ai | Visualize informações básicas do AI Branch. | apidog branch get <aiBranchName> --project <projectId> --type ai |
Exemplo: Pré-visualizar alterações candidatas antes da mesclagemmerge-request preview verifica diferenças candidatas para tipos de recursos atualmente suportados pela CLI. Ele não é um diff completo de recursos. Antes da mesclagem final, ainda recomendamos confirmar conteúdo importante dos recursos no cliente.
Mesclar um AI Branch#
Depois que as alterações do AI Branch forem concluídas, você poderá mesclá-las de volta ao branch de origem ou a outro branch de destino. Para branches de destino desprotegidos, use branch merge para mesclar diretamente. Para branches principais protegidos, use merge-request create para criar uma solicitação de mesclagem e passar pelo processo de revisão.| Comando | Descrição | Exemplo |
|---|
branch merge | Mescle diretamente recursos especificados de um AI Branch. | apidog branch merge --project <projectId> --from <aiBranchName> --to <targetBranchName> --endpoint-ids <ids> |
merge-request create | Crie uma solicitação de mesclagem. | apidog merge-request create --project <projectId> --from <aiBranchName> --to <targetBranchName> --reviewer-ids <userIds> --endpoint-ids <ids> |
merge-request approve | Aprove uma solicitação de mesclagem. | apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json |
merge-request reject | Rejeite uma solicitação de mesclagem. | apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName> |
Exemplo: Mesclar diretamente alterações de endpointExemplo: Criar uma solicitação de mesclagemTanto a mesclagem direta quanto as solicitações de mesclagem mesclam apenas a lista de recursos fornecida explicitamente. Elas não incluem automaticamente recursos referenciados ou recursos de diretório. Ao definir o escopo da mesclagem, confirme as dependências entre endpoints, diretórios, modelos de dados, componentes de resposta e recursos de teste.
Arquivar e Excluir um AI Branch#
Depois que um AI Branch for mesclado ou não for mais necessário, você poderá arquivá-lo primeiro e depois excluí-lo. Antes da exclusão, confirme que as alterações no branch foram mescladas ou não são mais necessárias.| Comando | Descrição | Exemplo |
|---|
branch archive --type ai | Arquive um AI Branch. | apidog branch archive <aiBranchName> --project <projectId> --type ai |
branch delete --type ai | Exclua um AI Branch arquivado. | apidog branch delete <aiBranchName> --project <projectId> --type ai |
Permissões de Edição por IA Externa#
Por padrão, a CLI recomenda gravar recursos do projeto por meio de AI Branch. Isso permite que alterações geradas por IA entrem primeiro em um branch isolado e sejam mescladas somente após a confirmação do usuário.Se você quiser que operações externas de IA ou CLI editem diretamente o branch principal, sprint branches padrão ou branches gerais, habilite as permissões correspondentes no cliente:Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions
| Permissão | Descrição |
|---|
| Permissão de edição direta do branch principal | Permite que operações externas de IA ou CLI gravem diretamente no branch principal. |
| Permissão de edição direta de sprint branch padrão | Permite que operações externas de IA ou CLI gravem diretamente em sprint branches padrão. |
| Permissão de edição direta de branch geral | Permite que operações externas de IA ou CLI gravem diretamente em branches gerais. |
| Permissão de edição direta de AI Branch | Permite que operações externas de IA ou CLI gravem em AI Branches criados e mantidos por IA. Isso geralmente permanece habilitado. |
Para proteger os recursos do projeto, recomendamos que operações externas de IA ou CLI gravem primeiro em um AI Branch e mesclem somente após a confirmação do usuário. Habilite permissões de edição direta somente quando um fluxo de trabalho de automação precisar claramente modificar o branch de destino diretamente.
Práticas Recomendadas#
1.
Crie um AI Branch por tarefa: Cada AI Branch deve corresponder a uma tarefa clara, como concluir a API de registro de usuário, organizar a documentação do módulo de pedidos ou gerar cenários de teste de pagamento.
2.
Importe antes de editar: Ao modificar recursos existentes, use pick-to para importá-los primeiro e, em seguida, atualize-os no AI Branch para evitar confusão sobre a origem.
3.
Pré-visualize diferenças antes da mesclagem: Use merge-request preview ou a visualização de diff do cliente para confirmar o conteúdo e as dependências dos recursos.
4.
Selecione explicitamente o escopo da mesclagem: Comandos de mesclagem processam apenas a lista de recursos fornecida. Para recursos relacionados, como diretórios de API, modelos de dados, componentes de resposta e casos de teste, confirme-os em conjunto.
5.
Mantenha a revisão humana: Definições de API, scripts de teste e modelos de dados gerados por IA devem ser revisados por membros do projeto antes da mesclagem.
6.
Arquive branches prontamente: AI Branches que foram mesclados ou abandonados devem ser arquivados prontamente para manter a lista de branches clara.
FAQ#
AI Branch é um sprint branch especial usado principalmente para armazenar resultados de gravação de IA externa, operações da CLI ou scripts de automação. Ele registra o branch de origem e incentiva os usuários a confirmar diferenças antes da mesclagem. Sprint branches padrão geralmente são usados para colaboração diária entre membros da equipe.
Não. Alterações em um AI Branch são salvas primeiro nesse AI Branch. Recursos relacionados entram no branch de destino somente depois que um usuário realiza uma mesclagem direta ou cria e aprova uma solicitação de mesclagem.
Em um projeto do Apidog, acesse Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions e habilite as permissões de edição direta para o branch principal, sprint branches padrão ou branches gerais conforme necessário. Depois que essas permissões forem habilitadas, operações externas de IA ou CLI poderão gravar diretamente dentro do escopo do branch correspondente.
Não. Tanto branch merge quanto merge-request create são executados de acordo com a lista de recursos fornecida explicitamente. Se endpoints referenciarem modelos de dados, componentes de resposta, diretórios ou recursos de teste, confirme e adicione o escopo de recursos correspondente antes da mesclagem.
Não. A exclusão não é obrigatória. Recomendamos arquivar o branch após confirmar que suas alterações foram mescladas ou não são mais necessárias e, em seguida, decidir se deve excluí-lo de acordo com as convenções da sua equipe para evitar o acúmulo de longo prazo de branches históricos.
