Spec Kit 整合型錄
整合型錄讓 Spec Kit 的 AI 代理整合可以被探索、版本化與散佈。
型錄檔案
內建型錄(integrations/catalog.json)
包含隨 Spec Kit 一起提供的整合。這些由核心團隊維護,且永遠可以安裝。
社群型錄(integrations/catalog.community.json)
由社群貢獻的整合。預設的社群來源僅供探索:在型錄中列出某個轉接器,既不是安裝許可,也不是程式碼稽核。使用允許安裝的型錄之前,請先審查外部程式碼。
型錄設定
第一個設定的層級會取代較低的層級。在該層級內,數字較小的優先順序勝出:
- 環境變數——
SPECKIT_INTEGRATION_CATALOG_URL以單一 URL 覆寫所有型錄 - 專案設定——專案根目錄中的
.specify/integration-catalogs.yml - 使用者設定——使用者主目錄中的
~/.specify/integration-catalogs.yml - 內建預設值——
catalog.json+catalog.community.json
加入第一個專案型錄會取代預設來源,除非你也在專案檔案中列出它們。共用的探索、信任與私人來源指引,請參閱型錄。
integration-catalogs.yml 範例:
catalogs:
- url: "https://example.com/my-catalog.json"
name: "my-catalog"
priority: 1
install_allowed: true
CLI 命令
使用 specify integration list --catalog、search 與 info 瀏覽。請參閱 CLI 參考中的型錄管理與外部轉接器安裝。
整合描述檔(integration.yml)
每個外部整合套件都包含一個僅供轉接器使用的 integration.yml 描述檔,以及一個匯出 IntegrationBase 子類別的根目錄 __init__.py。不需要命令清單,也不需要複製核心範本:
schema_version: "1.0"
integration:
id: "sample-agent"
name: "Sample Agent"
version: "1.0.0"
description: "Adapter for Sample Agent"
license: "MIT"
requires:
speckit_version: ">=1.1.2.dev0"
tools:
- name: "sample-agent"
required: true
必要的描述檔欄位:
| 欄位 | 驗證 |
|---|---|
schema_version |
必須是字串 "1.0" |
integration.id |
外部 ID 必須符合 ^[a-z0-9][a-z0-9-]*$。名稱 con、prn、aux、nul、com1 到 com9,以及 lpt1 到 lpt9 為保留字 |
integration.name、integration.description |
必須是字串 |
integration.version |
必須是 PEP 440 版本字串 |
requires.speckit_version |
必填,且為非空的 PEP 440 版本指定字串 |
requires.tools 為選用;沒有必需執行檔的轉接器請省略。選用的舊版 provides 中繼資料仍有效,但不提供主機命令。類別中繼資料、執行階段方法、工具與儲存需求,請參閱整合 API 參考。
型錄綱要
兩個型錄檔案都遵循相同的 JSON 綱要:
{
"schema_version": "1.0",
"updated_at": "2026-04-08T00:00:00Z",
"catalog_url": "https://...",
"integrations": {
"sample-agent": {
"id": "sample-agent",
"name": "Sample Agent",
"version": "1.0.0",
"description": "Adapter for Sample Agent",
"download_url": "https://example.com/sample-agent/1.0.0/sample-agent.zip",
"tags": ["cli"]
}
}
}
最上層欄位
| 欄位 | 類型 | 說明 |
|---|---|---|
schema_version |
string | 必須是 "1.0" |
updated_at |
string | 選用的 ISO 8601 時間戳記 |
integrations |
object | 整合 ID → 中繼資料的對應 |
整合項目欄位
| 欄位 | 類型 | 必填 | 說明 |
|---|---|---|---|
id |
string | 否 | 選用的明確 ID;必須與對應鍵相符 |
name |
string | 是 | 方便閱讀的顯示名稱 |
version |
string | 是 | PEP 440 版本(例如 1.0.0、1.0.0a1) |
description |
string | 是 | 單行說明 |
author |
string | 否 | 作者名稱或組織 |
repository |
string | 否 | 原始碼儲存庫 URL |
license |
string | 否 | 與描述檔相符的授權識別字 |
tags |
array | 否 | 可搜尋的標籤(例如 ["cli", "ide"]) |
download_url |
string | 外部安裝 | 釘選的 ZIP、tar.gz 或 tgz 封存檔 URL;HTTPS 或 loopback HTTP |
sha256 |
string | 否 | 封存檔的 64 字元十六進位 SHA-256 |
requires |
object | 否 | 提供時必須與描述檔要求相符 |
releases |
object | 否 | 歷來版本中繼資料;不是可安裝的版本 |
對應鍵與任何宣告的 id 都必須與 integration.id 相符。名稱、版本、說明,以及選用的作者/儲存庫/授權中繼資料,都必須與描述檔相符。內建項目不需要下載欄位,因為它們的實作隨 CLI 一起提供。
安裝政策與儲存
以 integration catalog add 註冊型錄會建立一個允許安裝的專案來源。在其設定中將 install_allowed: false 設為僅允許探索。此政策無法以 --trust-integration 或 --force 覆寫。每次外部安裝/更新在下載/匯入 Python 之前都會先提示,除非以 --trust-integration 明確預先授權。需要驗證的 GitHub 成品會使用既有的 Spec Kit 驗證提供者。
已安裝的程式碼儲存在 .specify/integrations/packages/<id>/,出處與雜湊則在 packages.json 中;兩者都會被受管理的 .specify/.gitignore 排除。執行同意會另外儲存在 ~/.specify/integration-trust.json,並與專案、整合 ID 以及經驗證的套件摘要綁定。產生的檔案有各自以雜湊追蹤的 <id>.manifest.json。
不要就地編輯已安裝的套件程式碼:請發佈新的封存檔/版本並改以升級方式處理。請參閱 CLI 參考中的信任與重新授權與升級與復原。
貢獻
加入內建整合或提交外部整合型錄項目,請參閱貢獻指南。代理專屬的設定請從整合目錄開始。共用的使用者命令記載於整合管理參考中。