Todas as operações de edição iniciadas a partir da Apidog CLI são tratadas como iniciadas por IA / Agentes de IA por predefinição.AI Branch foi concebido para fornecer aos Agentes de IA um ramo de edição isolado em projetos Apidog. Com AI Branch, a IA pode criar e atualizar recursos do projeto sem alterar diretamente o ramo principal ou um sprint branch padrão. Depois de as alterações estarem concluídas, os utilizadores podem rever as diferenças no cliente ou na CLI e, em seguida, integrar os resultados no ramo de destino diretamente ou através de um pedido de integração.Porque é necessário o AI Branch#
As edições iniciadas por IA podem ser imprevisíveis, enquanto a Apidog CLI fornece uma vasta gama de capacidades de edição. AI Branch foi concebido para estas operações de edição iniciadas por IA de maior risco, permitindo que os Agentes de IA editem recursos do projeto dentro de um âmbito controlado.Também pode atualizar para o Apidog 2.8.31 ou posterior e ativar permissões de edição direta para o ramo principal, sprint branches padrão e ramos gerais conforme necessário em Definições do projeto -> Definições de funcionalidades -> Permissões de edição de IA externa. Depois de ativadas, estas permissões contornam as restrições de edição direta que normalmente exigem AI Branch.O que é o AI Branch?#
AI Branch é um sprint branch especial. Tal como um sprint branch padrão, armazena alterações aos recursos do projeto. No entanto, destina-se por predefinição a operações de IA externas, como edições baseadas na CLI, e mantém um passo de confirmação humana antes de as alterações serem integradas.As principais características do AI Branch incluem:1.
Edição isolada: As 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 ramo principal ou o ramo de origem.
2.
Origem clara: Os AI Branches não podem ser criados diretamente no cliente Apidog. Devem ser criados a partir de uma origem CLI ou MCP. Um AI Branch regista o seu ramo de origem e é normalmente integrado novamente nesse ramo de origem, facilitando a compreensão do contexto das alterações geradas por IA.
3.
Confirmação humana: As alterações num AI Branch devem ser confirmadas por um utilizador antes de serem integradas. Os utilizadores podem rever diferenças, selecionar o âmbito dos recursos e escolher se pretendem integrar diretamente ou criar um pedido de integração.
4.
Sem limite de quantidade: Atualmente, não existe qualquer limite ativo para o número de AI Branches que podem ser criados. Os Agentes de IA podem utilizá-los para processar dados por domínio de negócio, iteração ou funcionalidade.
5.
Arquivo automático: Para evitar o crescimento descontrolado de AI Branches durante a colaboração no projeto, cada AI Branch é comparado com o seu ramo de origem a cada 24 horas. Se não forem encontradas diferenças, é arquivado automaticamente. Pode restaurar AI Branches arquivados no Apidog a qualquer momento, ou recriar novos AI Branches a partir da Apidog CLI, sem qualquer limite.
AI Branch é utilizado para armazenar resultados de escrita de operações externas de IA ou CLI. A edição normal no cliente, a integração e a revisão pelos utilizadores continuam a seguir as permissões dos membros do projeto e as regras de proteção de ramos.
Casos de utilização#
AI Branch é adequado quando a IA precisa de participar na manutenção de recursos do projeto, preservando simultaneamente o isolamento de ramos e a confirmação humana.| Cenário | Descrição |
|---|
| Gerar rascunhos de API a partir de código | Depois de ler o código, a IA cria ou atualiza endpoints de API HTTP num AI Branch. Os utilizadores confirmam as alterações antes da integração. |
| 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 ramo de colaboração atual. |
| Gerar rascunhos de testes automatizados | A IA pode criar cenários de teste, casos de teste ou dados de teste num AI Branch para confirmação posterior por testadores. |
| Preencher lacunas na documentação da API | A IA pode complementar campos em falta com base em relatórios de erros, implementações de API ou ficheiros OpenAPI. |
| Escrita em lote em CI/CD | Fluxos de trabalho automatizados podem escrever resultados gerados num AI Branch e aguardar revisão do utilizador antes da integração. |
Fluxo de trabalho básico#
Um fluxo de trabalho típico de AI Branch é o seguinte:1
Crie um AI Branch e especifique o ramo de origem no qual se baseia.
2
Importe os recursos que precisam de ser editados para o AI Branch, ou crie novos recursos no AI Branch.
3
Um Agente de IA, CLI ou script de automatização modifica recursos no AI Branch.
4
O utilizador revê as diferenças entre o AI Branch e o ramo de origem e, em seguida, confirma o âmbito dos recursos a integrar.
5
Dependendo das regras de proteção do ramo de destino, integre diretamente ou crie um pedido de integração.
Criar um AI Branch#
Utilize branch create --type ai para criar um AI Branch. Os pontos de entrada legados sprint-branch e sb permanecem compatíveis, mas recomenda-se o ponto de entrada unificado branch.| Comando | Descrição | Exemplo |
|---|
branch create --type ai | Criar um AI Branch. | apidog branch create --project <projectId> --type ai --name "ai/20260312-from-main-userRegister" --from main |
branch list --type ai | Ver AI Branches num projeto. | apidog branch list --project <projectId> --type ai |
branch list --type all | Ver todos os tipos de ramos num projeto. | apidog branch list --project <projectId> --type all |
branch get --type ai | Ver detalhes de um AI Branch especificado, incluindo o seu tipo de ramo e informações de origem. | apidog branch get <branchName> --project <projectId> --type ai |
Exemplo: Criar um AI Branch para a API de registo de utilizadorRecomendamos nomear AI Branches no formato ai/YYYYMMDD-from-sourceBranch-featureOrModule, por exemplo, ai/20260312-from-main-userRegister. Um nome claro ajuda a equipa a compreender a origem do ramo, a finalidade e a hora de cria ção.
Editar recursos num AI Branch#
Quando a CLI escreve recursos do projeto, pode utilizar parâmetros de ramo para escrever esses recursos num AI Branch. Os parâmetros variam ligeiramente entre comandos de recursos. Antes de utilizar, consulte 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 |
| Suite 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 utilizar primeiro cli-schema para ver e validar a estrutura de dados.Importar recursos a partir do ramo de origem#
Se um AI Branch precisar de modificar recursos existentes, utilize primeiro branch pick-to para importar recursos do ramo de origem para o AI Branch. Após a importação, a IA pode continuar a editar esses recursos no AI Branch.| Comando | Descrição | Exemplo |
|---|
branch pick-to | Importar recursos de um ramo 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 forem necessários diretórios, modelos de dados, componentes de resposta ou outros recursos relacionados, confirme o âmbito dos recursos antes da importação.
Ver alterações do AI Branch#
Antes da integração, recomendamos pré-visualizar as alterações candidatas entre o AI Branch e o ramo de destino. A CLI pode utilizar merge-request preview para analisar os tipos de recursos atualmente suportados. Também pode ver diferenças de ramo mais completas no cliente.| Comando | Descrição | Exemplo |
|---|
merge-request preview | Analisar alterações candidatas para confirmar o âmbito dos recursos antes da integração. | apidog merge-request preview --project <projectId> --from <aiBranchName> --to <targetBranchName> |
branch get --type ai | Ver informações básicas do AI Branch. | apidog branch get <aiBranchName> --project <projectId> --type ai |
Exemplo: Pré-visualizar alterações candidatas antes da integraçãomerge-request preview analisa diferenças candidatas para tipos de recursos atualmente suportados pela CLI. Não é uma comparação completa de recursos. Antes da integração final, continuamos a recomendar a confirmação de conteúdo importante dos recursos no cliente.
Integrar um AI Branch#
Depois de as alterações do AI Branch estarem concluídas, pode integrá-las novamente no ramo de origem ou noutro ramo de destino. Para ramos de destino desprotegidos, utilize branch merge para integrar diretamente. Para ramos principais protegidos, utilize merge-request create para criar um pedido de integração e seguir o processo de revisão.| Comando | Descrição | Exemplo |
|---|
branch merge | Integrar diretamente recursos especificados de um AI Branch. | apidog branch merge --project <projectId> --from <aiBranchName> --to <targetBranchName> --endpoint-ids <ids> |
merge-request create | Criar um pedido de integração. | apidog merge-request create --project <projectId> --from <aiBranchName> --to <targetBranchName> --reviewer-ids <userIds> --endpoint-ids <ids> |
merge-request approve | Aprovar um pedido de integração. | apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json |
merge-request reject | Rejeitar um pedido de integração. | apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName> |
Exemplo: Integrar diretamente alterações de endpointsExemplo: Criar um pedido de integraçãoTanto a integração direta como os pedidos de integração integram apenas a lista de recursos fornecida explicitamente. Não incluem automaticamente recursos referenciados ou recursos de diretório. Ao definir o âmbito da integração, confirme as dependências entre endpoints, diretórios, modelos de dados, componentes de resposta e recursos de teste.
Arquivar e eliminar um AI Branch#
Depois de um AI Branch ser integrado ou deixar de ser necessário, pode arquivá-lo primeiro e depois eliminá-lo. Antes da eliminação, confirme que as alterações no ramo foram integradas ou já não são necessárias.| Comando | Descrição | Exemplo |
|---|
branch archive --type ai | Arquivar um AI Branch. | apidog branch archive <aiBranchName> --project <projectId> --type ai |
branch delete --type ai | Eliminar um AI Branch arquivado. | apidog branch delete <aiBranchName> --project <projectId> --type ai |
Permissões de edição de IA externa#
Por predefinição, a CLI recomenda escrever recursos do projeto através de AI Branch. Isto permite que alterações geradas por IA entrem primeiro num ramo isolado e sejam integradas apenas após confirmação do utilizador.Se pretender que operações externas de IA ou CLI editem diretamente o ramo principal, sprint branches padrão ou ramos gerais, ative 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 ramo principal | Permite que operações externas de IA ou CLI escrevam diretamente no ramo principal. |
| Permissão de edição direta de sprint branch padrão | Permite que operações externas de IA ou CLI escrevam diretamente em sprint branches padrão. |
| Permissão de edição direta de ramo geral | Permite que operações externas de IA ou CLI escrevam diretamente em ramos gerais. |
| Permissão de edição direta de AI Branch | Permite que operações externas de IA ou CLI escrevam em AI Branches criados e mantidos pela IA. Normalmente, esta permissão permanece ativada. |
Para proteger os recursos do projeto, recomendamos que operações externas de IA ou CLI escrevam primeiro num AI Branch e integrem apenas após confirmação do utilizador. Ative permissões de edição direta apenas quando um fluxo de trabalho de automatização precisar claramente de modificar diretamente o ramo de destino.
Boas práticas#
1.
Crie um AI Branch por tarefa: Cada AI Branch deve corresponder a uma tarefa clara, como concluir a API de registo de utilizador, organizar a documentação do módulo de encomendas ou gerar cenários de teste de pagamentos.
2.
Importe antes de editar: Ao modificar recursos existentes, utilize pick-to para os importar primeiro e, em seguida, atualize-os no AI Branch para evitar confusão sobre a origem.
3.
Pré-visualize diferenças antes da integração: Utilize merge-request preview ou a vista de diferenças do cliente para confirmar o conteúdo e as dependências dos recursos.
4.
Selecione explicitamente o âmbito da integração: Os comandos de integração 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 revistos por membros do projeto antes da integração.
6.
Arquive ramos prontamente: AI Branches que tenham sido integrados ou abandonados devem ser arquivados prontamente para manter a lista de ramos clara.
Perguntas frequentes#
AI Branch é um sprint branch especial utilizado principalmente para armazenar resultados de escrita de IA externa, operações da CLI ou scripts de automatização. Regista o ramo de origem e incentiva os utilizadores a confirmar diferenças antes da integração. Os sprint branches padrão são normalmente utilizados para a colaboração diária entre membros da equipa.
Não. As alterações num AI Branch são guardadas primeiro nesse AI Branch. Os recursos relacionados só entram no ramo de destino depois de um utilizador realizar uma integração direta ou criar e aprovar um pedido de integração.
Num projeto Apidog, aceda a Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions e, em seguida, ative permissões de edição direta para o ramo principal, sprint branches padrão ou ramos gerais conforme necessário. Depois de estas permissões serem ativadas, operações externas de IA ou CLI podem escrever diretamente dentro do âmbito do ramo correspondente.
Não. Tanto branch merge como 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 âmbito dos recursos correspondente antes da integração.
Não. A eliminação não é obrigatória. Recomendamos arquivar o ramo depois de confirmar que as suas alterações foram integradas ou já não são necessárias e, em seguida, decidir se o elimina de acordo com as convenções da sua equipa, para evitar a acumulação prolongada de ramos históricos.
