MonoSpecs 多存儲庫管理指南

概述

MonoSpecs 是 HagiCode 的多儲存庫管理方法。它透過以下方式追蹤和管理子儲存庫 monospecs.yaml，它適用於任何需要一個地方協調多個獨立儲存庫的專案。

核心概念

設定檔

monospecs.yaml 是整個管理解決方案的核心，定義：

• 子存儲庫的清單和位置
• 每個儲存庫的 Git URL
• 顯示名稱和圖標
• 與 OpenSpec 的整合行為

與常規存儲庫的差異

特點	常規儲存庫	MonoSpecs 託管項目
OpenSpec 位置	根目錄的 openspec/	主儲存庫根目錄 openspec/
更改範圍	僅限於目前儲存庫	可以涉及多個子存儲庫
子存儲庫純度	規格與程式碼混合	主存儲庫中建立的規範，子存儲庫更清晰
存檔自動提交	需要手動規範提交	commit_when_archive: true 自動將規格提交至主儲存庫

為什麼要使用 Monospec？

• 統一管理：在一個設定檔中管理所有子倉庫
• 自動化支援：為腳本和工具提供儲存庫元數據
• AI 友善性：結構化配置有助於 AI 代理程式理解儲存庫關係
• OpenSpec 整合：與變更管理工作流程無縫集成
• 更乾淨的子儲存庫：規格保留在主儲存庫中，子儲存庫僅包含實際程式碼

適用場景

在以下場景中首先使用 Monospec：

1.多儲存庫協作開發 當一個項目被拆分成多個獨立的倉庫時：

• 前端應用、後端服務、桌面應用分別開發
• 需要跨儲存庫協調版本和依賴關係
• 文件和輔助項目與主程式碼分開

2.輔助專案管理 使用 MonoSpecs 來管理：

• 文件項目
• 官方網站
• 建置工具和腳本
• 每個儲存庫維護自己的版本控制

3.跨儲存庫功能開發 需要跨多個儲存庫進行更改的功能：

• 需要追蹤哪些儲存庫中的更改
• 自動將規格提交到正確的目標儲存庫
• 協調版本更新和依賴項

快速入門

初始化

請依照以下步驟完成單一規格初始化：

1.建立空的git儲存庫

創建一個空的 git 主存儲庫中的資料夾（注意：這是 git, 不 repos/ - 這是 monospecs 約定）：

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	字串	是的	Git 儲存庫 URL
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代理配置支援

代理.md

的 AGENTS.md 文件為 AI 代理提供特定於存儲庫的指導：

技術堆疊資訊

• 框架和建構工具
• 程式碼約定與命名實踐
• 版本管理和部署配置

特定於項目的行為

• 配置擴充和特殊要求
• OpenSpec 整合模式
• 跨儲存庫協調需求

人工智慧的好處

使用 AGENTS.md 使 AI 代理程式能夠：

• 了解儲存庫關係和依賴關係
• 跨多個儲存庫產生程式碼並重構
• 保持版本控制和配置的一致性

開放規範集成

MonoSpecs 如何與 OpenSpec 搭配使用

無論是管理 monospecs 託管專案還是常規儲存庫，您都可以使用 HagiCode 的 OpenSpec 工作流程：

常規存儲庫：

• 根目錄中的 OpenSpec openspec/ 目錄
• 變更僅影響目前儲存庫

單一規格管理項目：

• 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. 驗證 Git 儲存庫 URL 是否正確
3. 檢查身份驗證問題
4. 查看 Docker 容器狀態
5. 檢查磁碟空間可用性

---

有關更多詳細資訊，請參閱 monospecs 文件並檢查 HagiCode 儲存庫以取得設定範例。