擴充功能 API 參考
Spec Kit 擴充功能系統 API 與資訊清單結構描述的技術參考。
目錄
擴充功能資訊清單
結構描述版本 1.0
檔案:extension.yml
schema_version: "1.0" # Required
extension:
id: string # Required, pattern: ^[a-z0-9-]+$
name: string # Required, human-readable name
version: string # Required, PEP 440 version; SemVer recommended
description: string # Required, brief description
author: string # Optional
repository: string # Optional, source URL
license: string # Optional (e.g., "MIT", "Apache-2.0")
homepage: string # Optional, homepage URL
requires:
speckit_version: string # Required, version specifier (>=X.Y.Z)
tools: # Optional, array of tool requirements
- name: string # Tool name
version: string # Optional, version specifier
required: boolean # Optional, default: false
provides:
commands: # At least one of commands/templates/scripts/hooks/events required
- name: string # Required, pattern: ^speckit\.[a-z0-9-]+\.[a-z0-9-]+$
file: string # Required, relative path to command file
description: string # Optional
templates: # Optional, array of declared templates. Always resolve
# as "replace" -- 'strategy' is not an authorable field here.
- name: string # Required, pattern: ^[a-z0-9-]+$
file: string # Required, relative path to template file
description: string # Optional
scripts: # Optional, array of declared scripts. Always resolve
# as "replace" -- 'strategy' is not an authorable field here.
- name: string # Required, pattern: ^[a-z0-9-]+$
file: string # Required, relative path to script file
description: string # Optional
runtimes: [string] # Optional, subset of: bash, powershell, python
config: # Optional, array of config files
- name: string # Config file name
template: string # Template file path
description: string
required: boolean # Default: false
hooks: # Optional, event hooks. Each event accepts either form below.
event_name: # e.g., "after_specify", "after_plan", "after_tasks", "after_implement"
command: string # Command to execute
priority: integer # Optional, >= 1, default 10 (HookExecutor sort metadata)
optional: boolean # Default: true
prompt: string # Prompt text for optional hooks
description: string # Hook description
condition: string # Optional, condition expression
another_event: # Any event may instead use a list of mappings (multiple commands)
- command: string # Same fields as the single mapping, per entry
priority: integer
- command: string
priority: integer
events: # Optional, coding-agent lifecycle events
session_start:
command: string # Command template with a runnable scripts entry
tags: # Optional, array of tags (2-10 recommended)
- string
defaults: # Optional, default configuration values
key: value # Any YAML structure
config: # Optional, separate from provides.config
defaults: # Merged over top-level defaults
key: value
欄位規格
extension.id
- 類型:string
- 模式:
^[a-z0-9-]+$ - 說明:唯一的擴充功能識別碼
- 範例:
jira、linear、azure-devops - 無效:
Jira、my_extension、extension.id
extension.version
- 類型:string
- 格式:PEP 440;發行版本建議使用
MAJOR.MINOR.PATCH - 說明:擴充功能版本
- 範例:
1.0.0、0.9.5、2.1.3 - 亦接受:
v1.0、1.0、1.0.0-beta - 無效:
latest、not-a-version
requires.speckit_version
- 類型:string
- 格式:版本指定子
- 說明:所需的 spec-kit 版本範圍
- 範例:
>=0.1.0——0.1.0 或更高版本>=0.1.0,<2.0.0——0.1.x 或 1.x 版本==0.1.0——恰好 0.1.0
- 亦接受:
>= 0.1.0(運算子後有空白) - 無效:
0.1.0、latest
資訊清單載入時,此處必須是非空字串;相容性檢查會將它解析為 packaging.specifiers.SpecifierSet,並檢查已安裝的 Spec Kit 版本。
provides.commands[].name
- 類型:string
- 模式:
^speckit\.[a-z0-9-]+\.[a-z0-9-]+$ - 說明:具命名空間的命令名稱
- 格式:
speckit.{extension-id}.{command-name} - 範例:
speckit.jira.specstoissues、speckit.linear.sync - Invalid:
another-extension.command,speckit.jira.CreateIssues
舊版的雙段名稱 speckit.command 與 <extension-id>.command 會正規化為 speckit.<extension-id>.command,並發出警告。作者應使用正式名稱,而非依賴此相容性行為。安裝時也會檢查主要名稱屬於擴充功能的命名空間,並拒絕與已安裝擴充功能完全相同的命令名稱或別名衝突,以及與核心命令正規化輸出名稱的衝突。
provides.templates[].name / provides.scripts[].name
- 類型:string
- 模式:
^[a-z0-9-]+$ - 說明:與命令不同,範本與指令碼不是依名稱呼叫,因此它們使用與
extension.id相同的純 slug 模式,而非具命名空間的命令模式。 - 範例:
myext-template、myext-collect
provides.templates[].strategy / provides.scripts[].strategy
- 不是可撰寫的欄位。擴充功能提供的範本與指令碼一律解析為
replace;若資訊清單在其中一個條目上包含strategy鍵,將以ValidationError拒絕。可組合策略(wrap/prepend/append)僅供預設集使用。
provides.scripts[].runtimes
- 類型:字串陣列
- 值:
bash、powershell、python - 說明:宣告指令碼支援的執行環境。純粹是資訊性後設資料——不用於選擇或呼叫指令碼。
hooks
- 類型:object
- 鍵:事件名稱(例如
after_specify、after_plan、after_tasks、after_implement、before_analyze) - 值:單一 hook 對應,或 hook 對應清單(在一個事件上註冊多個命令)
- 說明:在生命週期事件執行的 hook
- 事件:由核心 spec-kit 命令定義
- 排序:目前的命令範本會依設定的 YAML 順序呈現 hook。
HookExecutor.get_hooks_for_event()則改為依priority遞增回傳(整數 ≥ 1,預設為 10),相同時以穩定的撰寫順序排列。執行限制請參閱掛鉤設定。
events
- 類型:object
- 鍵:正式的程式代理事件名稱
- 值:參照可執行命令的事件對應
- 說明:與整合無關的宣告,會翻譯為 已安裝程式代理的原生事件設定;請參閱擴充功能執行時期事件。
Python API
ExtensionManifest
模組:specify_cli.extensions
from specify_cli.extensions import ExtensionManifest
manifest = ExtensionManifest(Path("extension.yml"))
屬性:
manifest.id # str: Extension ID
manifest.name # str: Extension name
manifest.version # str: Version
manifest.description # str: Description
manifest.requires_speckit_version # str: Required spec-kit version
manifest.commands # List[Dict]: Command definitions
manifest.templates # List[Dict]: Declared template definitions
manifest.scripts # List[Dict]: Declared script definitions
manifest.hooks # Dict: Hook definitions
方法:
manifest.get_hash() # str: SHA256 hash of manifest file
例外:
ValidationError # Invalid manifest structure
CompatibilityError # Incompatible with current spec-kit version
ExtensionRegistry
模組:specify_cli.extensions
from specify_cli.extensions import ExtensionRegistry
registry = ExtensionRegistry(extensions_dir)
方法:
# Add extension to registry
registry.add(extension_id: str, metadata: dict)
# Remove extension from registry
registry.remove(extension_id: str)
# Get extension metadata
metadata = registry.get(extension_id: str) # Optional[dict]
# List all extensions
extensions = registry.list() # Dict[str, dict]
# Check if installed
is_installed = registry.is_installed(extension_id: str) # bool
登錄格式:
{
"schema_version": "1.0",
"extensions": {
"jira": {
"version": "1.0.0",
"source": {"kind": "catalog", "catalog": "my-org"},
"manifest_hash": "sha256...",
"enabled": true,
"priority": 10,
"registered_commands": {
"claude": ["speckit.jira.specstoissues"]
},
"registered_skills": [],
"installed_at": "2026-01-28T00:00:00"
}
}
}
registered_commands 將整合鍵對應至已註冊的命令名稱;registered_skills 記錄補充的技能名稱。安裝程式將 "local" 儲存為原始的本機來源,或如上所示的型錄物件。CLI 正規化的 --json 輸出使用另一種公開來源格式。
ExtensionManager
模組:specify_cli.extensions
from specify_cli.extensions import ExtensionManager
manager = ExtensionManager(project_root)
方法:
# Install from directory
manifest = manager.install_from_directory(
source_dir: Path,
speckit_version: str,
register_commands: bool = True
) # Returns: ExtensionManifest
# Install from ZIP
manifest = manager.install_from_zip(
zip_path: Path,
speckit_version: str
) # Returns: ExtensionManifest
# Remove extension
success = manager.remove(
extension_id: str,
keep_config: bool = False
) # Returns: bool
# List installed extensions
extensions = manager.list_installed() # List[Dict]
# Get extension manifest
manifest = manager.get_extension(extension_id: str) # Optional[ExtensionManifest]
# Check compatibility
manager.check_compatibility(
manifest: ExtensionManifest,
speckit_version: str
) # Raises: CompatibilityError if incompatible
CatalogEntry
模組:specify_cli.extensions
表示使用中型錄堆疊中的單一型錄。
from specify_cli.extensions import CatalogEntry
entry = CatalogEntry(
url="https://example.com/catalog.json",
name="default",
priority=1,
install_allowed=True,
description="Built-in catalog of installable extensions",
)
欄位:
| 欄位 | 類型 | 說明 |
|---|---|---|
url |
str |
型錄 URL(必須使用 HTTPS,包含 localhost) |
name |
str |
方便閱讀的型錄名稱 |
priority |
int |
排序順序(數字越小優先順序越高,衝突時勝出) |
install_allowed |
bool |
是否可安裝此型錄的擴充功能 |
description |
str |
型錄的選用說明(預設:空) |
ExtensionCatalog
模組:specify_cli.extensions
from specify_cli.extensions import ExtensionCatalog
catalog = ExtensionCatalog(project_root)
類別屬性:
ExtensionCatalog.DEFAULT_CATALOG_URL # default catalog URL
ExtensionCatalog.COMMUNITY_CATALOG_URL # community catalog URL
方法:
# Get the ordered list of active catalogs
entries = catalog.get_active_catalogs() # List[CatalogEntry]
# Fetch catalog (primary catalog, backward compat)
catalog_data = catalog.fetch_catalog(force_refresh: bool = False) # Dict
# Search extensions across all active catalogs
# Each result includes _catalog_name and _install_allowed
results = catalog.search(
query: Optional[str] = None,
tag: Optional[str] = None,
author: Optional[str] = None,
verified_only: bool = False
) # Returns: List[Dict] — each dict includes _catalog_name, _install_allowed
# Get extension info (searches all active catalogs)
# Returns None if not found; includes _catalog_name and _install_allowed
ext_info = catalog.get_extension_info(extension_id: str) # Optional[Dict]
# Check cache validity (primary catalog)
is_valid = catalog.is_cache_valid() # bool
# Clear all catalog caches
catalog.clear_cache()
結果註記欄位:
search() 與 get_extension_info() 回傳的每個擴充功能 dict 都包含:
| 欄位 | 類型 | 說明 |
|---|---|---|
_catalog_name |
str |
來源型錄的名稱 |
_install_allowed |
bool |
是否允許從此型錄安裝 |
型錄設定檔(.specify/extension-catalogs.yml):
catalogs:
- name: "default"
url: "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json"
priority: 1
install_allowed: true
description: "Built-in catalog of installable extensions"
- name: "community"
url: "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.community.json"
priority: 2
install_allowed: false
description: "Community-contributed extensions (discovery only)"
HookExecutor
模組:specify_cli.extensions
from specify_cli.extensions import HookExecutor
hook_executor = HookExecutor(project_root)
方法:
# Get project config
config = hook_executor.get_project_config() # Dict
# Save project config
hook_executor.save_project_config(config: Dict)
# Register hooks
hook_executor.register_hooks(manifest: ExtensionManifest)
# Unregister hooks
hook_executor.unregister_hooks(extension_id: str)
# Get hooks for event
hooks = hook_executor.get_hooks_for_event(event_name: str) # List[Dict]
# Check if hook should execute
should_run = hook_executor.should_execute_hook(hook: Dict) # bool
# Format hook message
message = hook_executor.format_hook_message(
event_name: str,
hooks: List[Dict]
) # str
CommandRegistrar
模組:specify_cli.extensions
from specify_cli.extensions import CommandRegistrar
registrar = CommandRegistrar()
方法:
# Register commands for Claude Code
registered = registrar.register_commands_for_claude(
manifest: ExtensionManifest,
extension_dir: Path,
project_root: Path
) # Returns: List[str] (command names)
# Parse frontmatter
frontmatter, body = registrar.parse_frontmatter(content: str)
# Render frontmatter
yaml_text = registrar.render_frontmatter(frontmatter: Dict) # str
命令檔案格式
通用命令格式
檔案:commands/{command-name}.md
---
description: "Command description"
tools:
- 'mcp-server/tool_name'
- 'other-mcp-server/other_tool'
---
# Command Title
Command documentation in Markdown.
## Prerequisites
1. Requirement 1
2. Requirement 2
## User Input
$ARGUMENTS
## Steps
### Step 1: Description
Instruction text...
\`\`\`bash
# Shell commands
\`\`\`
### Step 2: Another Step
More instructions...
## Configuration Reference
Information about configuration options.
## Notes
Additional notes and tips.
Frontmatter 欄位
description: string # Recommended, brief command description
tools: [string] # Optional, MCP tools required
特殊變數
$ARGUMENTS——使用者提供參數的佔位符Markdown 命令輸出包含擴充功能上下文註解:
<!-- Extension: {extension-id} --> <!-- Config: .specify/extensions/{extension-id}/ -->
產生的技能則在 frontmatter 的 metadata.source 中帶有來源資訊,且不會自動包含這些 HTML 註解。其他輸出格式使用各自整合專屬的渲染器。
設定結構描述
擴充功能設定檔
檔案:.specify/extensions/{extension-id}/{extension-id}-config.yml
擴充功能自行定義設定結構描述。常見模式:
# Connection settings
connection:
url: string
api_key: string
# Project settings
project:
key: string
workspace: string
# Feature flags
features:
enabled: boolean
auto_sync: boolean
# Defaults
defaults:
labels: [string]
assignee: string
# Custom fields
field_mappings:
internal_name: "external_field_id"
設定層級
- 擴充功能預設值(頂層
defaults與config.defaults合併, 衝突時以config.defaults為準) - 專案設定(
{extension-id}-config.yml) - 本機覆寫(
local-config.yml,gitignored) - 環境變數(
SPECKIT_{EXTENSION}_*)
ConfigManager 在呼叫時執行此合併;擴充功能命令與指令稿必須使用它或自行實作載入。它不會內插 YAML 中的 ${...} 字串,也不會驗證 config_schema 欄位。設定驗證屬於擴充功能命令或指令稿的責任。
環境變數模式
格式:SPECKIT_{EXTENSION}_{KEY}
擴充功能 ID 會轉為大寫,連字號改為底線。該前綴之後每個以底線分隔的組成部分會成為巢狀小寫鍵:SPECKIT_JIRA_PROJECT_KEY 設定的是 project.key,而非 project_key。環境變數值維持字串。當已安裝擴充功能 ID 的正規化前綴重疊時,較長的相符擴充功能 ID 擁有該變數。
範例:
SPECKIT_JIRA_PROJECT_KEYSPECKIT_LINEAR_API_KEYSPECKIT_GITHUB_TOKEN
Hook 系統
Hook 定義
每個事件可接受單一 hook 對應或對應清單。清單可在同一事件上註冊多個命令。
單一對應(在 extension.yml 中):
hooks:
after_tasks:
command: "speckit.jira.specstoissues"
optional: true
prompt: "Create Jira issues from tasks?"
description: "Automatically create Jira hierarchy"
condition: null
附優先順序的對應清單:
hooks:
after_plan:
- command: "speckit.my-ext.verify"
priority: 5
optional: false
description: "Verify the plan"
- command: "speckit.my-ext.report"
priority: 10
optional: true
prompt: "Generate the report?"
description: "Generate a report from the plan"
在單一資訊清單的清單中,重複的 command 會以「最後者勝出」去重並移到末尾,因此它也會在撰寫順序上打破優先順序相同的平手。
Hook 事件
標準事件(由核心定義):
before_specify——規格產生之前after_specify——規格產生之後before_plan——實作規劃之前after_plan——實作規劃之後before_tasks——任務產生之前after_tasks——任務產生之後before_implement——實作之前after_implement——實作之後before_analyze——跨成品分析之前after_analyze——跨成品分析之後before_checklist——檢核清單產生之前after_checklist——檢核清單產生之後before_clarify——規格釐清之前after_clarify——規格釐清之後before_constitution——憲章更新之前after_constitution——憲章更新之後before_converge——收斂評估之前after_converge——收斂評估之後
內建 bug 擴充功能事件(安裝該擴充功能時可用)
Hook 是在同一工作階段中執行的提示詞;它們重用從對話中解析的 BUG_SLUG 與 BUG_DIR(post-hook 則重用已寫入的報告),不會注入任何變數。Pre-hook 在 slug 解析與必要條件之後執行;post-hook 在報告寫入後、回報完成之前執行。
before_bug_assess——bug 目錄存在之後、擷取報告之前after_bug_assess——寫入assessment.md之後;報告難以理解導致提早停止時不會到達before_bug_fix——套用修復之前after_bug_fix——寫入fix.md之後before_bug_test——執行驗證之前after_bug_test——寫入test.md之後
Hook 設定
Spec Kit 將專案層級的擴充功能註冊與掛鉤設定儲存在 .specify/extensions.yml。installed 清單記錄已安裝的擴充功能 ID,settings 儲存專案範圍的擴充功能設定,hooks 依事件分組已註冊的掛鉤。
installed:
- git
- my-extension
settings:
auto_execute_hooks: true
hooks:
before_implement:
- extension: git
command: speckit.git.commit
enabled: true
optional: true
priority: 10
prompt: "Commit outstanding changes before implementation?"
description: "Auto-commit before implementation"
condition: null
after_implement:
- extension: my-extension
command: speckit.my-extension.verify
enabled: true
optional: false
priority: 5
description: "Run verification after implementation"
auto_execute_hooks 預設為 true,但屬於保留設定,在呈現或呼叫掛鉤時不會被參考。
| 欄位 | 說明 |
|---|---|
extension |
註冊 hook 的擴充功能 ID。 |
command |
與 hook 關聯的擴充功能命令。 |
enabled |
Hook 是否啟用。enabled: false 的 hook 會被略過。 |
optional |
若為 true,掛鉤會連同其 prompt 一起呈現,且可以跳過。若為 false,則會以帶有 EXECUTE_COMMAND 標記的自動掛鉤形式發出。 |
priority |
整數中繼資料 ≥ 1,預設為 10。目前的命令範本使用設定的 YAML 順序,而非依優先順序排序。 |
prompt |
詢問是否執行選用 hook 時顯示的訊息。 |
description |
掛鉤的人類可讀說明。 |
condition |
由 HookExecutor 求值的選用運算式:config.<path> 或 env.<VAR>,搭配 is set、== 或 !=。目前的命令範本不會求值條件,並會跳過條件非空的掛鉤。 |
掛鉤事件名稱用來識別掛鉤被呼叫的時機,一般使用 before_<command> 或 after_<command>,例如 before_implement、after_implement、before_tasks 與 after_tasks。
擴充功能資訊清單會在安裝期間拒絕無效的掛鉤優先順序。對於既有的註冊,HookExecutor.get_hooks_for_event() 會使用 normalize_priority() 排序:缺少的值、布林值、int() 拒絕的值(包含非有限浮點數)以及小於 1 的值會退回 10。數值字串與有限浮點數會以 int() 強制轉型。較小的值會先回傳,相同時以穩定的撰寫順序排列。目前的命令範本會直接讀取掛鉤清單,而非使用該 Python API,因此會依設定的 YAML 順序呈現掛鉤。
Hook 訊息格式
## Extension Hooks
**Optional Hook**: {extension}
Command: `/{command}`
Description: {description}
Prompt: {prompt}
To execute: `/{command}`
或強制 hook:
**Automatic Hook**: {extension}
Executing: `/{command}`
EXECUTE_COMMAND: {command}
擴充功能執行時期事件
擴充功能可以透過在 extension.yml 中宣告最上層的 events 對應,來回應程式代理的生命週期事件:
events:
session_start:
command: speckit.my-extension.initialize
pre_tool_use:
command: speckit.my-extension.validate
事件宣告與整合無關。Spec Kit 會重新整理每一個已安裝且支援事件的整合,各整合會將正式事件名稱翻譯為其程式代理的原生事件設定。支援的正式事件為 session_start、pre_tool_use、post_tool_use、user_prompt_submit、stop 與 session_end;整合可能只支援其中一部分。
執行時期事件與擴充功能 hook 不同。事件回應程式代理的生命週期,並直接執行被參照命令範本的 scripts 項目。因此,被參照的命令必須提供可執行的指令碼;其 Markdown 指示不會傳送給程式代理。Hook 則是在 Spec Kit 命令(例如 plan、tasks 與 implement)之前或之後呈現擴充功能命令。
例外
ValidationError
當擴充功能資訊清單驗證失敗時擲出。
from specify_cli.extensions import ValidationError
try:
manifest = ExtensionManifest(path)
except ValidationError as e:
print(f"Invalid manifest: {e}")
CompatibilityError
當擴充功能與目前的 spec-kit 版本不相容時擲出。
from specify_cli.extensions import CompatibilityError
try:
manager.check_compatibility(manifest, "0.1.0")
except CompatibilityError as e:
print(f"Incompatible: {e}")
ExtensionError
所有擴充功能相關錯誤的基底例外。
from specify_cli.extensions import ExtensionError
try:
manager.install_from_directory(path, "0.1.0")
except ExtensionError as e:
print(f"Extension error: {e}")
版本函式
version_satisfies
檢查版本是否符合指定子。
from specify_cli.extensions import version_satisfies
# True if 1.2.3 satisfies >=1.0.0,<2.0.0
satisfied = version_satisfies("1.2.3", ">=1.0.0,<2.0.0") # bool
檔案系統配置
.specify/
├── extensions/
│ ├── .registry # Extension registry (JSON)
│ ├── .cache/ # Catalog cache
│ │ ├── catalog.json
│ │ └── catalog-metadata.json
│ ├── .backup/ # Config backups
│ │ └── {ext}-{config}.yml
│ ├── {extension-id}/ # Extension directory
│ │ ├── extension.yml # Manifest
│ │ ├── {ext}-config.yml # User config
│ │ ├── local-config.yml # Local overrides (gitignored)
│ │ ├── {ext}-config.template.yml # Template
│ │ ├── commands/ # Command files
│ │ │ └── *.md
│ │ ├── scripts/ # Helper scripts
│ │ │ └── *.sh
│ │ ├── docs/ # Documentation
│ │ └── README.md
├── extensions.yml # Project extension config
└── scripts/ # (existing spec-kit)
.claude/
└── commands/
└── speckit.{ext}.{cmd}.md # Registered commands
最後更新:2026-01-28 API 版本:1.0 Spec Kit 版本:0.1.0