Руководство по управлению несколькими репозиториями MonoSpecs

Обзор

MonoSpecs — это подход HagiCode к управлению несколькими репозиториями. Он отслеживает и управляет субрепозиториями через monospecs.yaml, и он работает для любого проекта, которому требуется одно место для координации нескольких независимых репозиториев.

Основные понятия

Файл конфигурации

monospecs.yaml является основой всего управленческого решения и определяет:

• Список и расположение субрепозиториев
• URL-адрес Git для каждого репозитория
• Отображаемое имя и значок
• Поведение интеграции с OpenSpec

Отличия от обычных репозиториев

Особенность	Обычный репозиторий	Управляемый проект MonoSpecs
Расположение OpenSpec	Корневой каталог openspec/	Корневой каталог основного репозитория openspec/
Изменить область	Ограничено текущим репозиторием	Может включать несколько субрепозиториев
Чистота субрепозитория	Спецификации смешаны с кодом	Спецификации установлены в основном репозитории, субрепозитории более чистые.
Автоматическая фиксация архива	Требуется ручная фиксация спецификации	commit_when_archive: true автоматически фиксирует спецификации в основной репозиторий

Зачем использовать моноспеки?

• Единое управление: управляйте всеми субрепозиториями в одном файле конфигурации.
• Поддержка автоматизации: предоставляет метаданные репозитория для сценариев и инструментов.
• Удобство для искусственного интеллекта: структурированная конфигурация помогает агенту искусственного интеллекта понимать взаимоотношения с репозиториями.
• Интеграция OpenSpec: бесшовная интеграция с рабочим процессом управления изменениями.
• Чистые субрепозитории: спецификации хранятся в основном репозитории, субрепозитории содержат только реальный код.

Применимые сценарии

Сначала используйте MonoSpecs в таких сценариях:

1. Совместная разработка нескольких репозиториев Когда проект разделен на несколько независимых репозиториев:

• Интерфейсное приложение, серверная служба и настольное приложение разрабатываются отдельно.
• Необходимость координации версий и зависимостей между репозиториями.
• Документация и вспомогательные проекты отделены от основного кода.

2. Вспомогательное управление проектами Используйте MonoSpecs для управления:

• Проект документации
• Официальный сайт
• Инструменты и скрипты для создания
• Каждый репозиторий поддерживает собственный контроль версий.

3. Межрепозиторийная разработка Функция, требующая внесения изменений в несколько репозиториев:

• Нужно отслеживать изменения в каких репозиториях
• Автоматически фиксировать спецификации для исправления целевого репозитория
• Координация обновлений версий и зависимостей

Быстрый старт

Инициализация

Выполните следующие шаги для завершения инициализации monospecs:

1. Создайте пустой репозиторий git.

Создайте пустой git папка в вашем основном репозитории (примечание: это git, не repos/ - это соглашение моноспеков):

mkdir git
cd git
git init
cd ..

2. Настройте файл monospecs.

Создайте monospecs.yaml файл конфигурации в корневом каталоге вашего основного репозитория:

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: "⚙️"

Элементы конфигурации:

Элемент конфигурации	Тип	Требуется	Описание
version	строка	Да	Версия файла конфигурации
commit_when_archive	логическое значение	Нет	Следует ли автоматически фиксировать спецификации при архивировании (не фиксировать код субрепозитория)
repositories	массив	Да	Список конфигурации репозитория
repositories[].path	строка	Да	Путь к репозиторию (относительно корня проекта)
repositories[].url	строка	Да	URL-адрес репозитория Git
repositories[].displayName	строка	Нет	Отображаемое имя репозитория
repositories[].icon	строка	Нет	Значок репозитория (эмодзи)

Добавить субрепозитории в основной репозиторий

Добавьте все подрепозитории в repos/ каталог. Этот каталог должен быть исключен из системы контроля версий Git основного репозитория, чтобы избежать отслеживания содержимого подрепозитория:

# Exclude all sub-repositories
repos/

3. Добавьте родительский репозиторий в HagiCode.

Если вы используете настольное приложение HagiCode, откройте его и добавьте основной репозиторий в качестве проекта. Нажмите кнопку «Добавить проект» или «+» на главном экране, выберите папку основного репозитория, и вы увидите все подрепозитории и информацию об их статусе.

4. Клонирование субрепозиториев

Используйте monospecs.yaml конфигурация для клонирования всех настроенных субрепозиториев в repos/ каталог:

Это клонирует все подрепозитории на основе URL-адресов, указанных в файле конфигурации.

Структура файла конфигурации

Конфигурация корневого уровня

version: "1.0"
commit_when_archive: true

repositories:
  # ... repository configurations

Конфигурация уровня репозитория

Каждый субрепозиторий может иметь:

• Папка изменений OpenSpec (openspec/)
• Независимый .git/ каталог
• Необязательно AGENTS.md для настройки AI-агента

Операции по управлению репозиторием

Добавить новый репозиторий

При добавлении нового субрепозитория в monospecs.yaml repositories массив:

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

Обновить конфигурацию репозитория

При изменении URL-адресов репозитория или метаданных:

1. Редактировать monospecs.yaml обновить соответствующие записи
2. Убедитесь, что синтаксис YAML верен.
3. При синхронизации изменений вручную обновите конфигурацию локального репозитория.

Поддержка настройки агента AI

AGENTS.md

AGENTS.md файл содержит рекомендации для AI-агента, специфичные для репозитория:

Техническая информация по стеку

• Фреймворк и инструменты сборки
• Соглашения о коде и практика именования
• Управление версиями и настройка развертывания

Поведение, зависящее от проекта

• Расширения конфигурации и особые требования
• Шаблоны интеграции OpenSpec
• Потребности в координации между репозиториями

Преимущества ИИ

Использование AGENTS.md позволяет ИИ-агенту:

• Понимание отношений и зависимостей репозитория
• Генерация кода и рефакторинг в нескольких репозиториях
• Поддерживать согласованность в управлении версиями и конфигурациях.

Интеграция OpenSpec

Как MonoSpecs работает с OpenSpec

Независимо от того, управляете ли вы управляемым проектом monospecs или обычным репозиторием, вы можете использовать рабочий процесс OpenSpec HagiCode:

Обычный репозиторий:

• OpenSpec в корне openspec/ каталог
• Изменения касаются только текущего репозитория.

Проект, управляемый MonoSpecs:

• OpenSpec читает monospecs.yaml конфигурация
• Изменения отслеживаются субрепозиторием
• Спецификации автоматически фиксируются для достижения правильных целей

Поведение архива

Когда commit_when_archive: true:

• Спецификации автоматически фиксируются в основном репозитории.
• Код субрепозиториев не зафиксирован (остается отдельным)
• Упрощает управление спецификациями — для субрепозиториев не требуется фиксация спецификаций вручную.

Ручная фиксация субрепозитория

Субрепозитории поддерживают независимый контроль версий:

• Вносить фактические изменения кода в свои собственные репозитории.
• Спецификации фиксируются отдельно (из основного репозитория при архивировании)

Лучшие практики

Соглашения об именах репозиториев

• Используйте kebab-case (строчные буквы и дефисы) для путей к хранилищу.
• Используйте простые, описательные отображаемые имена на китайском языке.
• Используйте соответствующие смайлы в качестве значков

Рекомендации по отображаемым именам

• Держите его кратким и описательным
• Используйте единообразные имена для похожих репозиториев.
• Выберите значки, обозначающие назначение репозитория.

Обслуживание конфигурации

Синхронизировать конфигурацию с фактическим статусом

• Регулярно проверяйте monospecs.yaml отражает фактическую структуру репозитория
• Обновлять или удалять записи при добавлении или удалении репозиториев.
• Тестируйте изменения, чтобы убедиться в правильности конфигурации.

Контроль версий для конфигурации

• Отслеживать изменения файла конфигурации с помощью git
• Документируйте причины серьезных изменений конфигурации.
• Тегируйте версии файла конфигурации для простого отката

Устранение неполадок

Файл конфигурации не найден

Если monospecs.yaml файл не найден в корне проекта:

1. Проверьте, существует ли файл в правильном месте
2. Убедитесь, что вы находитесь в правильном рабочем каталоге
3. Проверьте наличие опечаток в имени файла конфигурации.

Синтаксические ошибки YAML

Распространенные проблемы с синтаксисом YAML:

• Неправильный отступ (используйте пробелы, а не табуляции)
• Отсутствующие или лишние кавычки вокруг строк
• Недопустимые типы данных (строки нуждаются в кавычках, числа — нет)
• Отсутствуют обязательные поля (например, path или url)

Репозиторий не обнаружен

Если вновь добавленный репозиторий не отображается:

1. Проверьте path правильно в monospecs.yaml
2. Убедитесь, что репозиторий успешно клонирован.
3. Проверьте, существует ли репозиторий в ожидаемом месте.

Неудачи клонирования

Если клонирование репозитория не удалось:

1. Проверьте сетевое соединение
2. Убедитесь, что URL-адрес репозитория Git верен.
3. Проверьте наличие проблем с аутентификацией
4. Просмотр состояния контейнера Docker
5. Проверьте наличие места на диске

---

Для получения более подробной информации обратитесь к документации monospecs и проверьте репозиторий HagiCode, чтобы найти примеры конфигурации.