Guía de gestión de repositorios múltiples de MonoSpecs

Descripción general

MonoSpecs es el enfoque de gestión de repositorios múltiples de HagiCode. Realiza un seguimiento y gestiona subrepositorios a través de monospecs.yamly funciona para cualquier proyecto que necesite un lugar para coordinar múltiples repositorios independientes.

Conceptos básicos

Archivo de configuración

monospecs.yaml es el núcleo de toda la solución de gestión, definiendo:

• Lista y ubicación de subrepositorios
• URL de Git para cada repositorio
• Nombre para mostrar e icono
• Comportamiento de integración con OpenSpec

Diferencias con los repositorios habituales

Característica	Repositorio habitual	Proyecto Gestionado MonoSpecs
Ubicación de OpenSpec	directorio raíz openspec/	Directorio raíz del repositorio principal openspec/
Cambiar alcance	Limitado al repositorio actual	Puede involucrar múltiples subrepositorios
Pureza del subrepositorio	Especificaciones mezcladas con código	Especificaciones establecidas en el repositorio principal, los sub-repositorios están más limpios
Archivar confirmación automática	Necesita confirmaciones de especificaciones manuales	commit_when_archive: true envía automáticamente las especificaciones al repositorio principal

¿Por qué utilizar MonoSpecs?

• Administración unificada: administre todos los subrepositorios en un archivo de configuración
• Soporte de automatización: proporciona metadatos de repositorio para scripts y herramientas
• Compatibilidad con la IA: la configuración estructurada ayuda al agente de IA a comprender las relaciones del repositorio
• Integración OpenSpec: integración perfecta con el flujo de trabajo de gestión de cambios
• Subrepositorios más limpios: las especificaciones se guardan en el repositorio principal, los subrepositorios solo contienen código real

Escenarios aplicables

Utilice MonoSpecs primero en escenarios como estos:

1. Desarrollo colaborativo de múltiples repositorios Cuando un proyecto se divide en varios repositorios independientes:

• La aplicación frontend, el servicio backend y la aplicación de escritorio se desarrollan por separado
• Necesidad de coordinar versiones y dependencias entre repositorios.
• Proyectos de documentación y ayuda separados del código principal.

2. Gestión Auxiliar de Proyectos Utilice MonoSpecs para gestionar:

• Proyecto de documentacion
• Sitio web oficial
• Crear herramientas y scripts
• Cada repositorio mantiene su propio control de versiones.

3. Desarrollo de funciones entre repositorios Una característica que requiere cambios en múltiples repositorios:

• Necesidad de realizar un seguimiento de los cambios en qué repositorios
• Confirmar automáticamente las especificaciones para corregir el repositorio de destino
• Coordinar actualizaciones de versiones y dependencias.

Inicio rápido

Inicialización

Siga estos pasos para completar la inicialización de monospecs:

1. Crear un repositorio git vacío

crear un vacio git carpeta en su repositorio principal (nota: esta es git, no repos/ - esta es la convención monospecs):

mkdir git
cd git
git init
cd ..

2. Configurar el archivo monospecs

Crea el monospecs.yaml archivo de configuración en el directorio raíz de su repositorio principal:

version: "1.0"
commit_when_archive: true

repositories:
  - path: "repos/frontend"
    url: "https://github.com/your-org/frontend.git"
    displayName: "Frontend App"
    icon: "🌐"

  - path: "repos/backend"
    url: "https://github.com/your-org/backend.git"
    displayName: "Backend Service"
    icon: "⚙️"

Elementos de configuración:

Elemento de configuración	Tipo	Requerido	Descripción
version	cuerda	si	Versión del archivo de configuración
commit_when_archive	booleano	No	Si se deben confirmar automáticamente las especificaciones al archivar (no confirmar el código del subrepositorio)
repositories	matriz	si	Lista de configuración del repositorio
repositories[].path	cuerda	si	Ruta del repositorio (relativa a la raíz del proyecto)
repositories[].url	cuerda	si	URL del repositorio de Git
repositories[].displayName	cuerda	No	Nombre para mostrar del repositorio
repositories[].icon	cuerda	No	Ícono del repositorio (emoji)

Agregar subrepositorios al repositorio principal

Agregue todos los subrepositorios al repos/ directorio. Este directorio debe estar excluido del control de versiones de Git del repositorio principal para evitar el seguimiento del contenido del subrepositorio:

# Exclude all sub-repositories
repos/

3. Agregar repositorio principal a HagiCode

Si utiliza la aplicación de escritorio HagiCode, abra la aplicación y agregue su repositorio principal como proyecto. Haga clic en el botón “Agregar proyecto” o ”+” en la pantalla de inicio, seleccione la carpeta de su repositorio principal y verá todos los sub-repositorios y su información de estado.

4. Clonar subrepositorios

Utilice el monospecs.yaml configuración para clonar todos los subrepositorios configurados en el repos/ directorio:

Esto clonará todos los subrepositorios según las URL especificadas en el archivo de configuración.

Estructura del archivo de configuración

Configuración de nivel raíz

version: "1.0"
commit_when_archive: true

repositories:
  # ... repository configurations

Configuración a nivel de repositorio

Cada subrepositorio puede tener:

• Carpeta de cambio OpenSpec (openspec/)
• independiente .git/ directorio
• Opcional AGENTS.md para la configuración del agente AI

Operaciones de gestión de repositorios

Agregar nuevo repositorio

Al agregar un nuevo subrepositorio al monospecs.yaml repositories matriz:

repositories:
  - path: "repos/new-service"
    url: "https://github.com/HagiCode-org/new-service.git"
    displayName: "New Service"
    icon: "🆕"

Actualizar la configuración del repositorio

Cuando las URL del repositorio o los metadatos cambian:

1. Editar monospecs.yaml para actualizar las entradas correspondientes
2. Verifique que la sintaxis de YAML sea correcta
3. Si la sincronización cambia, actualice manualmente la configuración del repositorio local

Soporte de configuración del agente AI

AGENTES.md

el AGENTS.md El archivo proporciona orientación específica del repositorio para el Agente AI:

Información técnica de la pila

• Marco y herramientas de construcción.
• Convenciones de código y prácticas de nomenclatura
• Configuración de implementación y gestión de versiones

Comportamientos específicos del proyecto

• Extensiones de configuración y requisitos especiales.
• Patrones de integración OpenSpec
• Necesidades de coordinación entre repositorios

Beneficios de la IA

Usando AGENTS.md permite al agente de IA:

• Comprender las relaciones y dependencias del repositorio
• Genere código y refactorice en múltiples repositorios
• Mantener la coherencia en el control de versiones y las configuraciones.

Integración OpenSpec

Cómo funciona MonoSpecs con OpenSpec

Ya sea que administre un proyecto administrado por monospecs o un repositorio normal, puede usar el flujo de trabajo OpenSpec de HagiCode:

Repositorio habitual:

• OpenSpec en la raíz openspec/ directorio
• Los cambios sólo afectan al repositorio actual

Proyecto gestionado por MonoSpecs:

• Lecturas OpenSpec monospecs.yaml configuración
• Cambios rastreados por subrepositorio
• Especificaciones comprometidas automáticamente con los objetivos correctos

Comportamiento del archivo

cuando commit_when_archive: true:

• Las especificaciones se envían automáticamente al repositorio principal.
• El código de los subrepositorios no está confirmado (permanece separado)
• Simplifica la gestión de especificaciones: no se necesitan confirmaciones manuales de especificaciones para los subrepositorios

Confirmaciones manuales del subrepositorio

Los subrepositorios mantienen un control de versiones independiente:

• Confirmar cambios de código reales en sus propios repositorios.
• Las especificaciones se confirman por separado (desde el repositorio principal al archivar)

Mejores prácticas

Convenciones de nomenclatura de repositorios

• Utilice kebab-case (letras minúsculas y guiones) para las rutas del repositorio
• Utilice nombres para mostrar simples y descriptivos en chino
• Utilice emojis relevantes como íconos

Pautas para mostrar nombres

• Mantenlo conciso y descriptivo.
• Utilice nombres consistentes en repositorios similares
• Seleccione iconos que representen el propósito del repositorio

Mantenimiento de configuración

Sincronizar configuración con estado real

• verificar periódicamente monospecs.yaml refleja la estructura real del repositorio
• Actualizar o eliminar entradas cuando se agregan o eliminan repositorios
• Probar cambios para garantizar la validez de la configuración.

Control de versiones para configuración

• Seguimiento de cambios en el archivo de configuración con git
• Documentar los motivos de los cambios de configuración importantes
• Versiones del archivo de configuración de etiquetas para una fácil reversión

Solución de problemas

Archivo de configuración no encontrado

si el monospecs.yaml El archivo no se encuentra en la raíz del proyecto:

1. Compruebe si el archivo existe en la ubicación correcta
2. Verifique que esté en el directorio de trabajo correcto
3. Compruebe si hay errores tipográficos en el nombre del archivo de configuración.

Errores de sintaxis de YAML

Problemas comunes de sintaxis de YAML:

• Sangría incorrecta (use espacios, no tabulaciones)
• Comillas faltantes o adicionales alrededor de las cadenas
• Tipos de datos no válidos (las cadenas necesitan comillas, los números no)
• Faltan campos obligatorios (como path o url)

Repositorio no detectado

Si no aparece un repositorio recién agregado:

1. Compruebe el path es correcto en monospecs.yaml
2. Verifique que el repositorio se haya clonado correctamente
3. Compruebe si el repositorio existe en la ubicación esperada

Fallos de clonación

Si falla la clonación del repositorio:

1. Comprobar conexión de red
2. Verifique que la URL del repositorio de Git sea correcta
3. Verificar problemas de autenticación
4. Revisar el estado del contenedor Docker
5. Verificar la disponibilidad de espacio en disco

---

Para obtener información más detallada, consulte la documentación de monospecs y consulte el repositorio de HagiCode para ver ejemplos de configuración.