套件組 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 參考。