套件組 API 參考

本頁定義宣告式套件組資訊清單、參照展開與已安裝紀錄的契約。套件組組合既有元件;它們不提供獨立的執行 API。

資訊清單

UTF-8 的 bundle.yml 檔案是一個 YAML 對應。套件組 ZIP 必須在封存檔根目錄包含它。開發指南提供完整的範例。

欄位 需求
schema_version 必填;"1.0" 或 "1.1"
bundle 必填的中繼資料對應
requires.speckit_version 必填的非空 Spec Kit 版本約束
requires.tools 選用的工具名稱清單;預設為空
requires.mcp 選用的 MCP 伺服器名稱清單;預設為空
integration 選用的對應,含有非空的 id
provides 選用的元件/參照對應
tags 選用的字串清單

缺少或為 null 的 requires/provides 對應會被視為空,但仍須提供必需的 Spec Kit 約束。存在的非對應值無效。字串清單欄位不能是裸字串,也不能含有非字串成員。

中繼資料

bundle 中的所有欄位皆為必填且非空:

欄位 含義
id 檔案系統安全的套件組識別碼
name 人類可讀的名稱
version 確切的語意版本
role 服務的角色、團隊或人物
description 設定的描述
author 作者或組織
license 授權識別碼

ID 須符合 ^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$:以小寫字母或數字開頭與結尾,中間為小寫字母、數字、點、底線與連字號。路徑分隔符與遍歷 ID 無效。

套件組與元件版本使用完整的 MAJOR.MINOR.PATCH SemVer,可選擇性帶有預發布/建置中繼資料與前導 v 或 V。不接受元件範圍與 latest。Spec Kit 需求改為約束,例如 ">=0.9.0,<2.0.0";它會在安裝/更新期間評估,而不是由 bundle validate 對照執行中的版本評估。

requires.tools 與 requires.mcp 會產生需求警告。它們不會安裝工具、佈建 MCP 伺服器,或驗證這些相依性是否存在。

整合

integration:
  id: copilot

省略 integration 或將其設為 null,會使套件組與整合無關。沒有非空 ID 的對應無效。

根套件組必須與專案的現用整合一致。它不會切換整合。被參照套件組的整合差異或無法確定的有效整合是警告,而不是額外的整合閘門。

元件參照

provides.extensions、provides.presets、provides.steps 與 provides.workflows 是對應的清單。省略或為 null 的清單為空。每個 (kind, id) 在一份資訊清單中最多只能出現一次,即使釘選相同。不同元件種類中的相同 ID 是不同的。

欄位 擴充功能 預設集 步驟 工作流程
id 必填 必填 必填 必填
version 必填 必填 選用 必填
source 選用的型錄名稱 選用的型錄名稱 選用的型錄名稱 選用的型錄名稱
priority 選用;預設為 10 必填的整數,至少為 1 不使用 不使用
strategy 不使用 必填 不使用 不使用

明確的擴充功能優先順序也必須至少為 1。預設集策略為 replace、prepend、append 與 wrap;其效果由預設集組合契約定義。

source 會斷言預期獲勝的元件型錄。它不會選取優先順序較低的型錄、繞過僅供探索的政策、接受直接成品 URL,或參照套件組本機承載內容。明確的來源即使對已安裝的元件也會檢查,需要網路存取,並拒絕含糊的型錄名稱。

沒有 source 時,隨附的擴充功能與預設集優先於其型錄。隨附的工作流程也可以使用。CLI 參考說明了穩定的隨附修補相容性與型錄釘選強制執行。

套件組參照

非空的 provides.bundles 清單需要綱要 "1.1"。空或 null 的清單沒有參照,在綱要 "1.0" 下也被接受。

provides:
  bundles:
    - id: qa-pack
      version: 2.0.0
      source: team-catalog
欄位 需求
id 必填的安全 slug;在這份資訊清單中唯一,且與父項 ID 不同
version 必填的確切 SemVer
source 選用的預期獲勝套件組型錄 ID,不是 URL

參照會在命令執行時,透過與父項相同的有效套件組型錄堆疊解析。明確的來源是斷言,不是優先順序覆寫。不符時會失敗,不會退回另一個型錄。

參照展開

結果是一份單一扁平的元件計畫,不是巢狀安裝。

排序與衝突規則

參照會依宣告順序以深度優先走訪,接著是宣告套件組自身的元件。最終計畫保留元件分組:擴充功能、預設集、步驟,接著是工作流程。

每個元件在每個 (kind, id) 下最多安裝一次。重複的宣告在版本與來源相符時一致;省略與明確的來源視為不同。擴充功能與預設集也必須在優先順序上一致,預設集則在策略上一致。省略的擴充功能優先順序等於其預設值 10。

衝突的同層參照會失敗,除非宣告套件組以自身的元件宣告解決它們。在每一層,套件組自身的宣告勝過其參照,佔據自身的宣告位置,並發出帶有被取代宣告來源鏈的覆寫警告。

一個套件組 ID 在一次展開中只能有一個版本。第二個版本是錯誤,不是另一次安裝。請選擇相容的參照 release 來解決該衝突。

限制與閘門

  • 循環會連同其參照鏈一併被拒絕。
  • 最多允許 10 層參照巢狀。
  • 最多允許 50 個不同的被參照套件組 ID,不含根。
  • 安裝與更新會對圖中每個套件組強制執行 Spec Kit 版本需求。
  • 根是唯一的整合閘門。被參照的整合差異會產生警告。
  • 工具與 MCP 需求會在整個圖中聯集,以供警告。

info 可以展開僅供探索的參照以供檢視。安裝、更新與線上驗證會將它們拒絕為不可安裝。validate --offline 不會展開參照,且每個宣告的參照只警告一次。build 只做結構檢查;它既不解析也不內嵌被參照的套件組。

被參照的資訊清單需要有網路支援的型錄下載。本機/離線參照解析與本機 bundle info 預覽不受支援。第一方套件組型錄不保留 release 歷史,因此當型錄推進時,第一方參照可能變得無法取得。較廣泛的綱要相容性協商未實作。

已安裝紀錄與擁有權

專案會在 .specify/bundle-records.json 中儲存來源資訊:

{
  "schema_version": "1.0",
  "updated_at": "2026-01-01T00:00:00Z",
  "bundles": [
    {
      "bundle_id": "team-setup",
      "version": "1.0.0",
      "installed_at": "2026-01-01T00:00:00Z",
      "required_components": [
        {"kind": "extensions", "id": "bug", "version": "1.0.0"}
      ],
      "contributed_components": [
        {"kind": "extensions", "id": "bug", "version": "1.0.0"}
      ],
      "installed_versions": {
        "extensions:bug": "1.0.1"
      }
    }
  ]
}
紀錄欄位 含義
bundle_id、version 已安裝的根套件組身分
installed_at 原始安裝時間,在重新整理/更新後保留
required_components 展開計畫中的每個必需元件,包括獨立提供的元件
contributed_components 歸屬於該套件組的元件;一律為其需求的子集
installed_versions 選用的已知實際版本,以複數 kind:id 為鍵,與要求的釘選不同
bundle_references 選用的直接/遞移套件組參照清單,各含 id、version 與解析後的型錄 source

紀錄元件項目使用複數的 kind 名稱,並含有 id、version,以及任何宣告的 source、priority 與 strategy。對於帶有參照的套件組,只有父項有已安裝紀錄;子參照只記錄一次,不會作為獨立的套件組紀錄安裝。

必需的釘選即使在元件已獨立安裝時,也會參與跨套件組衝突檢查。相容的獨立安裝元件不會被套件組採用、重新整理或解除安裝。其他套件組已擁有的元件可以共用。

共用需求必須在版本與來源、擴充功能/預設集優先順序,以及預設集策略上一致。套件組更新無法取代另一個套件組需要的釘選。移除套件組或在重新整理期間捨棄元件時,另一個套件組仍需要的元件會被保留;必要時擁有權會轉移給其餘需要該元件的套件組。

沒有 required_components 的舊紀錄會保留其已知的貢獻釘選。成功的重新安裝/重新整理會記錄完整的需求。缺少的紀錄會被視為沒有套件組,但格式錯誤的紀錄與不相容的綱要主版本是錯誤,不是空安裝。

紀錄寫入發生在成功的元件操作之後。它們不會讓安裝、更新、重新整理或移除成為全域交易;失敗與復原邊界請參閱 CLI 參考。

另請參閱