套件組型錄
套件組型錄負責定位套件組資訊清單,並描述可供探索的設定。它們不提供這些資訊清單所需的擴充功能、預設集、工作流程或步驟型錄。請另外註冊並審查那些元件型錄。
信任與安裝政策
重要
安裝前,請同時審查套件組來源及其元件型錄。
專案可以在 .specify/ 下提供套件組與允許安裝的元件型錄;它們的存在並不表示有人審查過。
請檢查所有適用的來源,包括不是你自行加入的來源:
specify bundle catalog list
specify extension catalog list
specify preset catalog list
specify workflow catalog list
specify workflow step catalog list
請將不熟悉的來源視為未經審查,直到你審查過為止。對於工作流程元件,請檢查 shell 的 run 與 env 欄位及參照的程式碼,包括作用中的覆蓋層。即使是 strict: true 的步驟,也可能透過環境繫結改變執行檔查詢或執行階段載入;請參閱審查 shell 執行。
| 政策 | 效果 |
|---|---|
install-allowed |
允許從此來源安裝/更新 |
discovery-only |
允許搜尋與檢視,但拒絕安裝/更新 |
verified 旗標是型錄中繼資料,不是安裝政策或安全保證。社群項目未經驗證,維護者不會審查、稽核、背書或支援其程式碼。安裝套件組不會自動註冊或信任配套型錄。
內建來源
| 來源 ID | URL | 優先順序 | 政策 |
|---|---|---|---|
default |
builtin://default |
1 |
install-allowed |
community |
builtin://community |
20 |
discovery-only |
預設型錄是 bundles/catalog.json;社群提交出現在 bundles/catalog.community.json 中。兩者皆從儲存庫線上取得。離線探索使用隨附的 wheel 快照。短暫的內建型錄可用性失敗會發出警告並退回這些快照;格式錯誤的內容或安全驗證失敗不會無聲退回。
套件組資訊清單的 download_url 仍需透過網路存取。隨附的型錄快照不是本機承載內容儲存區。
設定來源
請在已初始化的專案中,於審查來源之後執行:
specify bundle catalog add https://example.com/bundles.json \
--id team --priority 10 --policy install-allowed
specify bundle catalog list
specify bundle catalog remove team
CLI 會寫入 .specify/bundle-catalogs.yml:
schema_version: "1.0"
catalogs:
- id: team
url: https://example.com/bundles.json
priority: 10
install_policy: install-allowed
使用者設定在 ~/.specify/bundle-catalogs.yml 中使用相同的形狀。CLI 的加入/移除操作只會寫入專案範圍。兩種讀取器為相容性接受缺少的綱要版本,並拒絕不支援的主版本。
來源 URL 可以是 HTTPS、file://、本機路徑,或已知的 builtin:// URL。純 HTTP 會在連網前被拒絕,包括 localhost。加入的本機路徑會儲存為絕對路徑。此彈性適用於型錄檔案,不適用於其套件組下載 URL。
優先順序
兩個步驟決定有效的堆疊:
- 依 ID 合併來源:專案範圍的來源會取代使用者範圍中相同的 ID,使用者範圍則取代內建範圍中相同的 ID。
- 將存活的來源依數字優先順序、再依來源 ID 排序。優先順序數字較小者獲勝。
對於不同的 ID,範圍不會勝過優先順序。加入的來源預設優先順序為 10,排在優先順序 20 的社群來源之前,但排在優先順序 1 的預設來源之後。請依其 ID 覆寫內建來源,或審慎選擇適當的優先順序。
第一個含有該套件組 ID 的來源獲勝。缺少歷史 release、來源不符,或僅供探索的政策,都不會導致退回優先順序較低的型錄。套件組參照中的 source 是斷言此獲勝者;它不會選取來源。
以相符的 ID/設定重新加入既有的 URL 不會有任何作用。衝突的 URL/ID 設定會失敗。內建來源無法移除,但可以移除內建 ID 的專案覆寫,以還原較低範圍的來源。
型錄承載內容
型錄檔案是 JSON 物件,含有以套件組 ID 為鍵的 bundles 對應:
{
"schema_version": "1.0",
"bundles": {
"team-setup": {
"id": "team-setup",
"name": "Team setup",
"version": "1.2.0",
"role": "developer",
"description": "A curated team setup",
"author": "Example team",
"license": "MIT",
"repository": "https://github.com/example/team-setup",
"download_url": "https://github.com/example/team-setup/releases/download/v1.2.0/team-setup-1.2.0.zip",
"requires": {"speckit_version": ">=0.9.0"},
"provides": {"extensions": 1, "presets": 0, "steps": 0, "workflows": 1},
"tags": ["developer", "bugfix"],
"verified": false
}
}
}
項目的 id 必須與其外層鍵相符。requires 與 provides 若存在且非空,必須是對應;tags 必須是字串清單;verified 必須是真正的布林值。provides 描述的是元件數量,不是資訊清單的元件清單。具有不支援主版本的型錄綱要版本與重複的 JSON 鍵會被拒絕。
請使用 sha256 摘要驗證成品位元組。社群提交自動化會記錄它從實際封存檔計算出的摘要;提交的檢查碼不符會使驗證失敗。一般的目前項目讀取器仍接受沒有摘要的項目。歷史 release 需要各自的摘要。
型錄套件組下載 URL 必須使用 HTTPS,或 localhost 上的 HTTP,並解析為套件組資訊清單,或含有根目錄層級 bundle.yml 的 ZIP。取回的資訊清單 ID 與版本必須與選取的型錄項目相符。本機路徑與 file:// 不被接受為套件組下載 URL;請將本機套件組來源直接傳給 bundle install。
社群提交的發布契約較窄:具版本、標籤釘選的 GitHub release ZIP 成品。請參閱發布指南。
Release 歷史
一個項目可以在目前 release 之外,加入核准的歷史 release:
{
"id": "team-setup",
"version": "1.2.0",
"download_url": "https://example.com/team-setup-1.2.0.zip",
"releases": {
"1.1.0": {
"download_url": "https://example.com/team-setup-1.1.0.zip",
"sha256": "<64-character SHA-256 digest>"
}
}
}
這是項目片段,不是完整的型錄。使用前請替換摘要預留位置。每筆歷史紀錄都需要各自的 HTTPS(或 localhost HTTP)download_url 與 64 字元十六進位 SHA-256 摘要。摘要可以帶有不區分大小寫的 sha256: 前綴與周圍空白;其他演算法前綴會被拒絕。
歷史鍵必須是嚴格的 SemVer 值,且可依 PEP 440 比較。它們不能與目前版本或彼此重複,包括等價寫法,例如 1.0.0-rc.1 與 1.0.0-rc1。歷史紀錄不能含有 id、version 或 releases。
名稱、描述與作者等共用中繼資料除非被覆寫,否則會被繼承。release 專屬的 requires、provides 與 verified 不會被繼承:請在每筆歷史紀錄上提供它們,否則該 release 沒有需求、沒有提供的數量,且信任為 community。
specify bundle info team-setup --versions
specify bundle install team-setup --version 1.1.0
等價的版本寫法,例如 v1.1.0 與 1.1.0,會選取同一個 release;型錄鍵的寫法僅供顯示。確切的套件組 release 選取絕不會改變取回的資訊清單中的元件釘選。bundle update 一律選取目前的 release。
歷史紀錄會在型錄來源載入時驗證。格式錯誤的歷史紀錄會使任何諮詢該來源的操作失敗。ID 查詢在找到獲勝者後,可能讓格式錯誤的較低優先順序來源不被觀察;搜尋會載入所有來源,因此即使是被遮蔽的格式錯誤項目也會使搜尋失敗。
既有的單一 release 型錄仍有效。第一方與社群套件組型錄目前每個套件組只刊登一個 release,不保留歷史紀錄。