Todas las operaciones de edición iniciadas desde Apidog CLI se tratan como iniciadas por IA / agentes de IA de forma predeterminada.AI Branch está diseñado para proporcionar a los agentes de IA una rama de edición aislada en los proyectos de Apidog. Con AI Branch, la IA puede crear y actualizar recursos del proyecto sin cambiar directamente la rama principal ni una rama de sprint estándar. Una vez completados los cambios, los usuarios pueden revisar las diferencias en el cliente o en la CLI y, a continuación, fusionar los resultados en la rama de destino directamente o mediante una solicitud de fusión.Por qué se necesita AI Branch#
Las ediciones iniciadas por IA pueden ser impredecibles, mientras que Apidog CLI proporciona una amplia variedad de capacidades de edición. AI Branch está diseñado para estas operaciones de edición iniciadas por IA de mayor riesgo, lo que permite a los agentes de IA editar recursos del proyecto dentro de un alcance controlado.También puede actualizar a Apidog 2.8.31 o posterior y habilitar permisos de edición directa para la rama principal, las ramas de sprint estándar y las ramas generales según sea necesario en Configuración del proyecto -> Configuración de funciones -> Permisos de edición de IA externa. Una vez habilitados, estos permisos omiten las restricciones de edición directa que normalmente requieren AI Branch.Qué es AI Branch#
AI Branch es una rama de sprint especial. Al igual que una rama de sprint estándar, almacena cambios en los recursos del proyecto. Sin embargo, está pensada de forma predeterminada para operaciones de IA externa, como ediciones basadas en CLI, y mantiene un paso de confirmación humana antes de fusionar los cambios.Las características clave de AI Branch incluyen:1.
Edición aislada: Los cambios realizados desde la CLI en recursos como API, documentación, modelos de datos y escenarios de prueba se almacenan en AI Branch y no afectan directamente a la rama principal ni a la rama de origen.
2.
Origen claro: Las AI Branches no se pueden crear directamente en el cliente de Apidog. Deben crearse desde una fuente CLI o MCP. Una AI Branch registra su rama de origen y normalmente se fusiona de nuevo en esa rama de origen, lo que facilita comprender el contexto de los cambios generados por IA.
3.
Confirmación humana: Los cambios en una AI Branch deben ser confirmados por un usuario antes de fusionarse. Los usuarios pueden revisar diferencias, seleccionar el alcance de los recursos y elegir si desean fusionar directamente o crear una solicitud de fusión.
4.
Sin límite de cantidad: Actualmente no hay ningún límite activo en el número de AI Branches que se pueden crear. Los agentes de IA pueden utilizarlas para procesar datos por dominio de negocio, iteración o función.
5.
Archivado automático: Para evitar un crecimiento descontrolado de AI Branches durante la colaboración del proyecto, cada AI Branch se compara con su rama de origen cada 24 horas. Si no se encuentran diferencias, se archiva automáticamente. Puede restaurar AI Branches archivadas en Apidog en cualquier momento, o recrear nuevas AI Branches desde Apidog CLI, sin ningún límite.
AI Branch se utiliza para almacenar resultados de escritura de operaciones externas de IA o CLI. La edición normal dentro del cliente, la fusión y la revisión por parte de los usuarios siguen estando sujetas a los permisos de los miembros del proyecto y a las reglas de protección de ramas.
Casos de uso#
AI Branch es adecuado cuando la IA necesita participar en el mantenimiento de recursos del proyecto, mientras se conservan el aislamiento de ramas y la confirmación humana.| Escenario | Descripción |
|---|
| Generar borradores de API a partir de código | Después de leer el código, la IA crea o actualiza endpoints de API HTTP en una AI Branch. Los usuarios confirman los cambios antes de fusionarlos. |
| Organizar recursos de API en bloque | La IA puede ajustar directorios de API, añadir descripciones y actualizar modelos de datos o componentes de respuesta sin afectar directamente a la rama de colaboración actual. |
| Generar borradores de pruebas automatizadas | La IA puede crear escenarios de prueba, casos de prueba o datos de prueba en una AI Branch para su posterior confirmación por parte de los testers. |
| Completar vacíos en la documentación de API | La IA puede complementar campos faltantes basándose en informes de errores, implementaciones de API o archivos OpenAPI. |
| Escritura por lotes en CI/CD | Los flujos de trabajo automatizados pueden escribir resultados generados en una AI Branch y esperar la revisión del usuario antes de fusionar. |
Flujo de trabajo básico#
Un flujo de trabajo típico de AI Branch es el siguiente:1
Cree una AI Branch y especifique la rama de origen en la que se basa.
2
Importe los recursos que deben editarse en la AI Branch, o cree nuevos recursos en la AI Branch.
3
Un agente de IA, CLI o script de automatización modifica recursos en la AI Branch.
4
El usuario revisa las diferencias entre la AI Branch y la rama de origen y, a continuación, confirma el alcance de los recursos que se fusionarán.
5
Según las reglas de protección de la rama de destino, fusione directamente o cree una solicitud de fusión.
Crear una AI Branch#
Utilice branch create --type ai para crear una AI Branch. Los puntos de entrada heredados sprint-branch y sb siguen siendo compatibles, pero se recomienda el punto de entrada unificado branch.| Comando | Descripción | Ejemplo |
|---|
branch create --type ai | Crear una AI Branch. | apidog branch create --project <projectId> --type ai --name "ai/20260312-from-main-userRegister" --from main |
branch list --type ai | Ver AI Branches en un proyecto. | apidog branch list --project <projectId> --type ai |
branch list --type all | Ver todos los tipos de ramas en un proyecto. | apidog branch list --project <projectId> --type all |
branch get --type ai | Ver los detalles de una AI Branch especificada, incluido su tipo de rama y la información de origen. | apidog branch get <branchName> --project <projectId> --type ai |
Ejemplo: Crear una AI Branch para la API de registro de usuarioRecomendamos nombrar las AI Branches con el formato ai/YYYYMMDD-from-sourceBranch-featureOrModule, por ejemplo, ai/20260312-from-main-userRegister. Un nombre claro ayuda al equipo a comprender el origen, el propósito y la fecha de creación de la rama.
Editar recursos en una AI Branch#
Cuando la CLI escribe recursos del proyecto, puede utilizar parámetros de rama para escribir esos recursos en una AI Branch. Los parámetros varían ligeramente entre comandos de recursos. Antes de usarlos, consulte la ayuda del comando correspondiente y el JSON Schema.| Tipo de recurso | Comandos comunes | Ejemplo |
|---|
| Endpoint de API HTTP | endpoint create, endpoint update | apidog endpoint create --project <projectId> --branch <aiBranchName> --file ./endpoint.json |
| Modelo de datos | 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 |
| Escenario de prueba | test-scenario create, test-scenario update | apidog test-scenario update <scenarioId> --project <projectId> --branch <aiBranchName> --file ./scenario.json |
| Suite de pruebas | test-suite create, test-suite update | apidog test-suite create --project <projectId> --branch <aiBranchName> --file ./suite.json |
| Datos de prueba | test-data create, test-data update | apidog test-data create --project <projectId> --branch <aiBranchName> --file ./test-data.json |
Al crear o actualizar recursos complejos, recomendamos utilizar primero cli-schema para ver y validar la estructura de datos.Importar recursos desde la rama de origen#
Si una AI Branch necesita modificar recursos existentes, utilice primero branch pick-to para importar recursos desde la rama de origen a la AI Branch. Después de la importación, la IA puede seguir editando esos recursos en la AI Branch.| Comando | Descripción | Ejemplo |
|---|
branch pick-to | Importar recursos desde una rama de origen a una AI Branch de destino. | apidog branch pick-to --project <projectId> --from <sourceBranchName> --to <aiBranchName> --endpoint-ids <ids> |
Ejemplo: Importar endpoints y permitir que la IA los modifiquepick-to importa únicamente los recursos especificados explícitamente en el comando. Si se requieren directorios, modelos de datos, componentes de respuesta u otros recursos relacionados, confirme el alcance de los recursos antes de importar.
Ver cambios de AI Branch#
Antes de fusionar, recomendamos previsualizar los cambios candidatos entre la AI Branch y la rama de destino. La CLI puede utilizar merge-request preview para escanear los tipos de recursos actualmente compatibles. También puede ver diferencias de rama más completas en el cliente.| Comando | Descripción | Ejemplo |
|---|
merge-request preview | Escanear cambios candidatos para confirmar el alcance de los recursos antes de fusionar. | apidog merge-request preview --project <projectId> --from <aiBranchName> --to <targetBranchName> |
branch get --type ai | Ver información básica de AI Branch. | apidog branch get <aiBranchName> --project <projectId> --type ai |
Ejemplo: Previsualizar cambios candidatos antes de fusionarmerge-request preview escanea diferencias candidatas para los tipos de recursos actualmente compatibles con la CLI. No es una diferencia completa de recursos. Antes de la fusión final, seguimos recomendando confirmar el contenido importante de los recursos en el cliente.
Fusionar una AI Branch#
Una vez completados los cambios de la AI Branch, puede fusionarlos de nuevo en la rama de origen o en otra rama de destino. Para ramas de destino no protegidas, utilice branch merge para fusionar directamente. Para ramas principales protegidas, utilice merge-request create para crear una solicitud de fusión y pasar por el proceso de revisión.| Comando | Descripción | Ejemplo |
|---|
branch merge | Fusionar directamente recursos especificados desde una AI Branch. | apidog branch merge --project <projectId> --from <aiBranchName> --to <targetBranchName> --endpoint-ids <ids> |
merge-request create | Crear una solicitud de fusión. | apidog merge-request create --project <projectId> --from <aiBranchName> --to <targetBranchName> --reviewer-ids <userIds> --endpoint-ids <ids> |
merge-request approve | Aprobar una solicitud de fusión. | apidog merge-request approve <mergeRequestId> --project <projectId> --to <targetBranchName> --file ./approve.json |
merge-request reject | Rechazar una solicitud de fusión. | apidog merge-request reject <mergeRequestId> --project <projectId> --to <targetBranchName> |
Ejemplo: Fusionar directamente cambios de endpointsEjemplo: Crear una solicitud de fusiónTanto la fusión directa como las solicitudes de fusión fusionan únicamente la lista de recursos proporcionada explícitamente. No incluyen automáticamente recursos referenciados ni recursos de directorio. Al definir el alcance de la fusión, confirme las dependencias entre endpoints, directorios, modelos de datos, componentes de respuesta y recursos de prueba.
Archivar y eliminar una AI Branch#
Después de fusionar una AI Branch o cuando ya no se necesite, puede archivarla primero y luego eliminarla. Antes de eliminarla, confirme que los cambios en la rama se hayan fusionado o ya no sean necesarios.| Comando | Descripción | Ejemplo |
|---|
branch archive --type ai | Archivar una AI Branch. | apidog branch archive <aiBranchName> --project <projectId> --type ai |
branch delete --type ai | Eliminar una AI Branch archivada. | apidog branch delete <aiBranchName> --project <projectId> --type ai |
Permisos de edición de IA externa#
De forma predeterminada, la CLI recomienda escribir recursos del proyecto mediante AI Branch. Esto permite que los cambios generados por IA entren primero en una rama aislada y se fusionen únicamente después de la confirmación del usuario.Si desea que las operaciones de IA externa o CLI editen directamente la rama principal, las ramas de sprint estándar o las ramas generales, habilite los permisos correspondientes en el cliente:Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions
| Permiso | Descripción |
|---|
| Permiso de edición directa de la rama principal | Permite que las operaciones de IA externa o CLI escriban directamente en la rama principal. |
| Permiso de edición directa de ramas de sprint estándar | Permite que las operaciones de IA externa o CLI escriban directamente en ramas de sprint estándar. |
| Permiso de edición directa de ramas generales | Permite que las operaciones de IA externa o CLI escriban directamente en ramas generales. |
| Permiso de edición directa de AI Branch | Permite que las operaciones de IA externa o CLI escriban en AI Branches creadas y mantenidas por IA. Normalmente se mantiene habilitado. |
Para proteger los recursos del proyecto, recomendamos que las operaciones de IA externa o CLI escriban primero en una AI Branch y se fusionen solo después de la confirmación del usuario. Habilite permisos de edición directa únicamente cuando un flujo de trabajo de automatización necesite claramente modificar la rama de destino directamente.
Prácticas recomendadas#
1.
Cree una AI Branch por tarea: Cada AI Branch debe corresponder a una tarea clara, como completar la API de registro de usuario, organizar la documentación del módulo de pedidos o generar escenarios de prueba de pagos.
2.
Importe antes de editar: Al modificar recursos existentes, utilice pick-to para importarlos primero y luego actualícelos en la AI Branch para evitar confusiones sobre el origen.
3.
Previsualice las diferencias antes de fusionar: Utilice merge-request preview o la vista de diferencias del cliente para confirmar el contenido de los recursos y las dependencias.
4.
Seleccione explícitamente el alcance de la fusión: Los comandos de fusión procesan únicamente la lista de recursos proporcionada. Para recursos relacionados, como directorios de API, modelos de datos, componentes de respuesta y casos de prueba, confírmelos conjuntamente.
5.
Mantenga la revisión humana: Las definiciones de API, los scripts de prueba y los modelos de datos generados por IA deben ser revisados por miembros del proyecto antes de fusionarse.
6.
Archive las ramas oportunamente: Las AI Branches que se hayan fusionado o abandonado deben archivarse oportunamente para mantener clara la lista de ramas.
Preguntas frecuentes#
AI Branch es una rama de sprint especial utilizada principalmente para almacenar resultados de escritura de IA externa, operaciones de CLI o scripts de automatización. Registra la rama de origen y anima a los usuarios a confirmar las diferencias antes de fusionar. Las ramas de sprint estándar suelen utilizarse para la colaboración diaria entre miembros del equipo.
No. Los cambios en una AI Branch se guardan primero en esa AI Branch. Los recursos relacionados entran en la rama de destino solo después de que un usuario realice una fusión directa o cree y apruebe una solicitud de fusión.
En un proyecto de Apidog, vaya a Project Settings - Feature Settings - AI Feature Settings - External AI Edit Permissions y, a continuación, habilite los permisos de edición directa para la rama principal, las ramas de sprint estándar o las ramas generales según sea necesario. Después de habilitar estos permisos, las operaciones de IA externa o CLI pueden escribir directamente dentro del alcance de la rama correspondiente.
No. Tanto branch merge como merge-request create se ejecutan según la lista de recursos proporcionada explícitamente. Si los endpoints hacen referencia a modelos de datos, componentes de respuesta, directorios o recursos de prueba, confirme y añada el alcance de recursos correspondiente antes de fusionar.
No. La eliminación no es obligatoria. Recomendamos archivar la rama después de confirmar que sus cambios se han fusionado o ya no son necesarios y, a continuación, decidir si eliminarla según las convenciones de su equipo para evitar la acumulación a largo plazo de ramas históricas.
