預設集 API 參考
本參考定義預設集資訊清單、組合與交付規則,以及已安裝狀態。CLI 參考說明終端機命令;開發指南逐步介紹如何建立套件。
資訊清單
每個預設集都有一個 UTF-8 編碼的 preset.yml,其根節點為 YAML 對應。
| 欄位 | 必要 | 契約 |
|---|---|---|
schema_version |
是 | 字串 "1.0" |
preset |
是 | 中繼資料對應 |
preset.id |
是 | 符合 [a-z0-9-]+ 的字串 |
preset.name |
是 | 人類可讀的字串 |
preset.version |
是 | Python packaging.version.Version 接受的引號字串 |
preset.description |
是 | 說明字串 |
preset.author |
否 | 作者中繼資料 |
preset.repository |
否 | 儲存庫 URL 中繼資料 |
preset.license |
否 | 授權中繼資料 |
requires |
是 | 需求對應 |
requires.speckit_version |
是 | 非空字串;安裝期間以 PEP 440 規格字串檢查 |
requires.extensions |
否 | 擴充功能 ID 或相依性對應的清單 |
provides |
是 | 貢獻對應 |
provides.templates |
是 | 非空的貢獻對應清單,包含命令與指令碼 |
tags |
否 | 探索標籤;使用小寫字串清單 |
已發布的預設集請使用描述性、以字母開頭、小寫連字號形式的 ID,以及 X.Y.Z 版本。社群提交契約比執行階段資訊清單驗證器更嚴格:它要求 ID 符合 [a-z][a-z0-9-]*、數字形式的 X.Y.Z 版本,以及儲存庫、文件、授權與發行資訊。僅憑執行階段的中繼資料驗證,不足以證明預設集符合型錄提交需求。
版本與約束請加上引號:例如 version: 1.0 這類 YAML 值是數字,而非版本字串。不相容的 Spec Kit 版本或無效的 Spec Kit 規格字串會導致安裝失敗。
貢獻欄位
provides.templates 中的每個項目都使用以下結構:
provides:
templates:
- type: "template"
name: "spec-template"
file: "templates/spec-addendum.md"
description: "Adds team requirements"
strategy: "append"
| 欄位 | 必要 | 契約 |
|---|---|---|
type |
是 | template、command 或 script |
name |
是 | 邏輯產出物名稱,而非來源檔案名稱 |
file |
是 | 預設集內的相對路徑,不得含父層遍歷 |
description |
否 | 貢獻說明 |
strategy |
否 | 預設為 replace;接受的字串會正規化為小寫 |
selector |
僅適用 replace-section |
非空的小寫章節錨點;不含前導 # |
範本與指令碼名稱使用小寫字母、數字與連字號。命令名稱還可使用點號;例如 speckit.specify 或 speckit.myext.report。重複的 (name, type) 配對會被拒絕,但不同類型可以共用同一個名稱。
產出物一經宣告,資訊清單中的 file 即為權威依據。宣告的路徑若缺失或不是檔案,不會退回使用同一預設集內的其他慣用檔案。請確保所有宣告的檔案都存在:資訊清單的結構驗證並非完整的套件內容檢查。當資訊清單缺失或未宣告所要求的名稱時,舊版查閱可使用慣用路徑。
擴充功能相依性
requires:
speckit_version: ">=0.9.0"
extensions:
- "companion-extension"
- id: "other-extension"
version: ">=1.2.0,<2"
required: false
僅寫 ID 表示必要且無版本約束。對應形式的項目必須有符合 [a-z0-9-]+ 的 id;選填的 version 必須是有效的非空 PEP 440 規格字串,required 必須是布林值,預設為 true。精確釘選、排除條件與上限皆為有效寫法。
相依性僅供建議,不會自動安裝。安裝完成後,CLI 會針對必要的擴充功能發出警告,若其缺失、登錄項目損毀、檔案缺失、已停用,或可比較的版本不符合約束。缺失或已停用的功能仍無法使用。版本不符並不會停用擴充功能;它仍可執行,但行為可能與預期不同。
選填相依性一律不會發出警告。無法解析或缺失的已記錄版本屬於無法比較,不會回報為不符。解析器接納的擴充功能目錄即使沒有登錄項目,也視為可用,但沒有可供比較的已記錄版本。擴充功能登錄檔無法讀取時,便無法進行這項安裝後的相依性檢查;沒有警告並不代表相依性已通過驗證。
相依性請宣告在資訊清單中,而不只是型錄項目:--dev 與 --from 不會查閱型錄。即使是自成一體、具命名空間的取代命令,仍會在沒有同名擴充功能的情況下交付。
檔案解析
每個 (name, type) 皆獨立評估:
flowchart TD
A["Requested artifact"] --> B["Project-local override"]
B --> C["Enabled presets: priority, then ID"]
C --> D["Enabled extensions: priority, then ID"]
D --> E["Core defaults"]
在預設集與擴充功能層級中,優先順序數字越小越優先,其次以字母順序的 ID 打破平手。已停用的項目會被排除。安全的未登錄擴充功能目錄以隱含優先順序 10 參與;已停用、損毀或缺失的已登錄擴充功能,不會再以未登錄貢獻的形式重新納入。
| 類型 | 專案本機覆寫 | 慣用預設集子目錄 |
|---|---|---|
| 範本 | .specify/templates/overrides/<name>.md |
templates/,含舊版根目錄查閱 |
| 命令 | .specify/templates/overrides/<name>.md |
commands/ |
| 指令碼 | .specify/templates/overrides/scripts/<name>.<ext> |
scripts/ |
核心查閱包含專案預設值與封裝的核心資產;對於可編輯/原始碼安裝,則為儲存庫資產。命令查閱可將 speckit.<stem> 對應到核心的 <stem>.md 檔案名稱。如此一來,即使專案沒有 .specify/templates/commands/ 的副本,也能針對核心命令進行組合。
組合策略
| 類型 | replace |
prepend |
append |
wrap |
replace-section |
|---|---|---|---|---|---|
| 範本 | 預設 | 支援 | 支援 | {CORE_TEMPLATE} |
支援 |
| 命令 | 預設 | 支援 | 支援 | {CORE_TEMPLATE} |
支援 |
| 指令碼 | 預設 | 不支援 | 不支援 | $CORE_SCRIPT |
不支援 |
優先順序最高的 replace 層會完全勝出。否則,解析會找到最近的下層 replace 基準,再由下而上僅套用其上方的層級。前置與附加會以空白行分隔兩段內容。包裝佔位符會由實際的下層內容取代,而該內容可能已包含其他預設集的客製化。
位於勝出的 replace 基準下方的無效章節宣告,不會阻擋解析。貢獻堆疊中的章節宣告仍會受到嚴格驗證。
若無 replace 基準,組合便無法產出內容。命令註冊會發出警告並跳過無法組合的命令,而不是僅憑其命名空間就要求提供擴充功能。包裝缺少必要的佔位符時,會在組合期間引發預設集驗證錯誤。
組合後的命令主體不會內嵌每一層的 YAML frontmatter。解析會使用優先順序最高的可用 frontmatter,並在缺少時從基準繼承 scripts、agent_scripts 與 argument-hint。內部的 strategy 鍵會從組合輸出中移除。接著由使用中的整合以其支援的命令或技能格式算繪結果。
章節取代
使用 replace-section 可自訂某一個 Markdown 章節,而不必複製整份底層文件:
provides:
templates:
- type: template
name: spec-template
file: templates/team-requirements.md
strategy: replace-section
selector: requirements
檔案包含完整的取代內文,而不是所選的標題。空檔案會刪除該內文。內文從標題行之後開始,延伸至下一個同層級或更高層級的標題,或文件結尾。下層章節屬於該內文的一部分。原始標題與內文以外的所有文字維持不變,包括行結尾。請自行提供後續標題之前所需的空白行與結尾換行;此策略不會自動插入空白行分隔。若標題位於文件結尾(EOF)且沒有行結束符,非空的取代內容會取得一個分隔用的行結束符,除非片段本身已以行結束符開頭。這會採用文件的最後一種行結尾樣式,若無則預設為 LF。空的取代內容不會更動未以行結束符結尾的標題。
請在 preset.yml 中同時宣告 strategy 與 selector,而不是在命令 frontmatter 中。selector 用於其他策略時會被拒絕。此功能是在資訊清單結構描述 "1.0" 之下的附加功能;散布預設集時,請將 requires.speckit_version 設為支援此策略的版本。
選取器採用有界的 GitHub 風格錨點契約:
- ATX 標題有一至六個前導
#字元、最多三個前導空格,標題標記後方為空白字元或行尾。選用的結尾雜湊標記不計入標題文字。 - 行內強調/程式碼格式會被移除,但保留其文字;行內連結貢獻的是其標籤,而非目的地,包括含有平衡括號的目的地。程式碼片段內容在強調處理期間保持原樣,因此
`__init__`會保留其底線。完整的相符底線強調序列,包括___Target___,會被剝除;僅憑格式無法區分其他方面相同的重複標題錨點。 - 將文字轉為小寫,移除連字號與底線以外的標點/符號,保留 Unicode 字母/數字,並將每個空格換成一個連字號。重複的空格不會合併。
## Review & Approval!會變成review--approval;## API_v2 - Notes會變成api_v2---notes;## **Café** Guide會變成café-guide。- 選取器必須完全相符,不得含前導
#、模糊比對、父層路徑或重複編號。兩個標題即使層級不同,只要正規化後的錨點相同,就會被視為含糊。
反引號與波浪號圍欄程式碼在比對與章節邊界判定時都會被忽略。圍欄最多可有三個前導空格;結尾圍欄使用相同標記,且長度至少與開頭圍欄相同。反引號圍欄的資訊字串不得包含反引號。未閉合的圍欄會保護文件的其餘部分。開頭的 YAML 中繼資料不參與標題識別。不支援 Setext 標題、HTML 標題與明確的 HTML 錨點目標。
取代會套用至目前為止已組合的文件,並依既有的優先順序進行。稍後、優先順序較高的章節取代,可以取代先前對同一內文的取代。僅限章節的命令編輯會完整保留底層命令的 frontmatter;章節內文檔案不提供取代用的命令中繼資料。與其他命令策略混用時,仍維持其既定的中繼資料合併行為。
必須恰好有一個相符項目。零個相符項目會以 SECTION_NOT_FOUND 失敗;多個相符項目會以 SECTION_AMBIGUOUS 失敗。診斷資訊會指出預設集、貢獻檔案、目標產出物、選取器、相符數量與補救方式。含糊的診斷資訊包含候選標題文字,以及在當下已組合文件中的行號(從 1 起算)。這些欄位與錯誤識別碼是穩定的;散文措辭可能變更。遺漏相符項目時,請檢查選取器/目前的標題;含糊相符時,請讓正規化後的標題錨點保持唯一。不會回傳首次相符的備援結果或成功但未變更的結果。
可執行指令碼無法使用此策略。它不是通用的 Markdown 編輯器。執行階段範本輔助程式使用與 CLI 相同的章節語意;命令具體化仍由 CLI 負責。請讓受管理的配套 Python 輔助程式與每個指令碼變體一併安裝。以資訊清單為基礎的殼層組合本就要求 Python 3 與 PyYAML。
命令與技能生命週期
安裝會將預設集檔案複製到 .specify/presets/<id>/,並在組合其命令之前記錄該預設集。初始註冊與安裝後的協調會具體化實際的堆疊,因此安裝順序不會決定最終勝出的命令。
對於已初始化的專案,交付僅針對已記錄的使用中整合。技能模式會為命令式整合發出技能,而非第二種命令表示法;原生技能整合則使用其原生格式。通用整合不會註冊預設集覆寫。使用 specify integration use <key> 或 switch <key> 切換時,會為新啟用的整合重新搭建已啟用的預設集。
沒有 init-options.json 的舊版專案仍保留偵測式命令註冊。已存在但損毀或格式錯誤的選項檔案,不會觸發該全代理備援機制。
移除會清理已記錄的輸出,並協調存留的預設集、擴充功能、覆寫或核心貢獻。它也能還原受影響的命令或技能輸出,範圍包括被移除預設集所記錄的先前使用中整合目錄,以及目前的整合。啟用、停用與優先順序變更會更新解析狀態,但本身不會重新搭建已交付的命令或技能。
憲章生命週期與代理命令交付不同。預設情況下,憲章由憲章命令解析,而非在每次堆疊變更時重寫。啟用 constitution-sync 時,受保護的協調會利用產生內容的來源資訊,避免覆寫人工撰寫的憲章。
已安裝狀態
| 位置 | 角色 |
|---|---|
.specify/presets/<id>/preset.yml |
已安裝的資訊清單 |
.specify/presets/<id>/ |
已複製的套件檔案 |
.specify/presets/.registry |
含有 schema_version: "1.0" 與 presets 對應的 JSON 登錄檔 |
.specify/presets/.cache/ |
型錄快取與下載工作檔案 |
.specify/memory/.constitution-template.json |
具體化時產生的憲章來源資訊 |
登錄中繼資料記錄版本、資訊清單雜湊、啟用狀態、優先順序、安裝時間戳記、來源,以及已登錄的命令/技能輸出。新版輸出追蹤會將整合鍵對應到名稱清單;舊版技能追蹤可能是扁平清單。請將其視為 CLI 管理的狀態,而非套件資訊清單或穩定的 JSON 檢查 API。
型錄安裝會記錄 {"kind":"catalog","catalog":"<name>"} 來源資訊。本機目錄、直接 URL 與本機隨附安裝會記錄為本機,而非可重複使用的下載 URL。登錄更新會保留現有的 installed_at;先移除再新增的取代方式會建立新的時間戳記。
指令碼範本解析
各自 common 指令碼中的 Bash resolve_template/resolve_template_content 與 PowerShell Resolve-Template/Resolve-TemplateContent,可讓殼層取用者使用範本解析。代理命令與技能的具體化由 Spec Kit 處理,而非由各代理自行處理。