成品

成品是 Spec Kit 在專案中公開的任何命令、範本、指令碼或 hook,無論由哪一層貢獻,包括內建資產、已安裝的預設集、已安裝的擴充功能,或 .specify/templates/overrides/ 中的專案本機覆寫。

specify artifact 命令群組是該清單的唯讀檢視介面。specify preset resolve <name> 回答「對於這個由預設集管理的名稱,哪個檔案勝出?」;specify artifact 回答「到底存在什麼,其背後的完整組成堆疊為何?」,包括沒有預設集觸及的內建成品。

目前所有子命令都需要 --json。省略它會以代碼 2 結束,並在 stderr 列印使用訊息;不會產生 stdout。文字呈現被刻意延後,因此下方的 JSON 形狀是唯一的合約,日後新增預設文字呈現器仍是非破壞性、附加性的變更。

列出成品

specify artifact list --json
選項 說明
--json 必要。以 JSON 陣列形式將清單輸出到 stdout。

列印每個可見成品的完整清單,每個 (kind, name) 配對一列,包含其組成 stack。具名成品依種類(command,然後 template,然後 script)與名稱排序。Hook 列在其後,依事件排序,然後依第一個宣告的優先順序排序。

[
  {
    "id": "command:speckit.specify",
    "name": "speckit.specify",
    "kind": "command",
    "description": "Create or update the feature specification.",
    "stack": [
      {
        "id": "command:speckit.specify",
        "layer": null,
        "sourceId": null,
        "presetId": null,
        "presetName": null,
        "strategy": "replace",
        "active": true,
        "hidden": false,
        "manifestPath": null,
        "lookupId": null,
        "sourcePath": null
      }
    ]
  },
  {
    "id": "script:setup-plan",
    "name": "setup-plan",
    "kind": "script",
    "description": "Setup implementation plan for a feature.",
    "stack": [
      {
        "id": "script:setup-plan",
        "layer": null,
        "sourceId": null,
        "presetId": null,
        "presetName": null,
        "strategy": "replace",
        "active": true,
        "hidden": false,
        "manifestPath": null,
        "lookupId": null,
        "sourcePath": null
      }
    ]
  }
]
欄位 說明
id {kind}:{name},即 artifact info 接受作為參數的簡寫
name 邏輯成品名稱(命令使用 speckit.<stem> 命名空間)
kind command、template、script、hook 其中之一
description 來自宣告它的最高優先層的說明,否則為 ""
stack 此成品的組成堆疊,使用與 artifact info 相同的列形狀

內建成品永遠會出現,即使沒有任何東西覆寫它們。說明來自具有說明的最高優先層,隱藏內建命令的預設集或專案覆寫會回報自己的說明,而非被隱藏的內建文字。Skills(.github/skills/**/SKILL.md)被排除:它們是整合專屬輸出,不是隨附的資產家族。

成品資訊

specify artifact info <name> --json
選項 說明
--json 必要。以 JSON 物件形式將組成堆疊輸出到 stdout。
--kind <kind> 將查詢限縮為 command、template、script 或 hook

<name> 接受裸名稱(speckit.specify)或 kind:name 簡寫(command:speckit.specify)。當簡寫與 --kind 同時提供時,兩者必須一致。

{
  "id": "command:speckit.specify",
  "name": "speckit.specify",
  "kind": "command",
  "description": "Create or update the feature specification.",
  "stack": [
    {
      "id": "command:speckit.specify",
      "layer": "preset",
      "sourceId": "compliance",
      "presetId": "compliance",
      "presetName": "Compliance Preset",
      "strategy": "replace",
      "active": true,
      "hidden": false,
      "manifestPath": ".specify/presets/compliance/preset.yml",
      "lookupId": "preset:compliance:command:speckit.specify",
      "sourcePath": ".github/skills/speckit-specify/SKILL.md"
    },
    {
      "id": "command:speckit.specify",
      "layer": null,
      "sourceId": null,
      "presetId": null,
      "presetName": null,
      "strategy": "replace",
      "active": false,
      "hidden": true,
      "manifestPath": null,
      "lookupId": null,
      "sourcePath": null
    }
  ]
}

最上層的 id、name、kind、description 與 stack 欄位,與 artifact list --json 上對應的列相符。

堆疊語意

對於 command、template 與 script 成品,stack 依解析優先順序排列:索引 0 是勝出層。Hook 堆疊是附加性的,而非以勝出者為基礎:多個項目可以同時啟用,其宣告順序在 Hook 成品 中說明。每一列描述一個貢獻層:

欄位 說明
id {kind}:{name},與來源無關的來回鍵,在同一個成品堆疊的每一列上都相同
layer project、preset 或 extension;內建層為 null
sourceId 解析器使用的已安裝預設集或擴充功能 ID,當該層沒有來源時為 null
presetId 預設集套件目錄 id;在內建、project 與 extension 列上為 null
presetName 當其資訊清單宣告了顯示名稱時為該名稱,否則為套件 id;當 presetId 為 null 時為 null
strategy replace、wrap、prepend、append 或 additive
active 該層是否啟用;對於具名成品,只有在索引 0 時為 true
hidden 當較低索引的 replace 層將此層從組成中切除時為 true
manifestPath 宣告資訊清單的專案相對路徑,當不適用時為 null
lookupId 確定性的 {layer}:{sourceId}:{kind}:{name} 識別碼,內建層為 null
sourcePath 支援該層的具體檔案的專案相對 POSIX 路徑,內建/合成層為 null

active 與 hidden 是獨立標籤,不是相反。對於 command、template 與 script 成品,active 標識由既有 Spec Kit 層解析順序選出的最高優先層;它不驗證該層內容是否可讀取或組成。這保留了 specify preset resolve 的診斷行為,該命令即使內容組成之後產生警告,也會回報已發現的層鏈。組成策略(wrap、prepend、append)會將較低層保留在組成的輸出中,因此未啟用的層不一定被隱藏:只有第一個 replace 層以下的層會被標為 hidden。內建列沒有來源:layer、sourceId 與 lookupId 為 null,但 id 永遠有值,即使在內建列上也是如此。id 是來回鍵:specify artifact info 接受它作為輸入(例如 specify artifact info command:speckit.specify --json),且無論呼叫者傳入裸名稱還是 id,它都解析到同一個成品。

此處的來源是指單一成品層的起源:提供它的已安裝預設集或擴充功能、宣告它的資訊清單,以及支援它的具體檔案。查詢 ID 使用已安裝的預設集或擴充功能 ID,與既有解析器使用的身分與順序相符。已安裝 ID 是登錄/目錄名稱,可能與資訊清單內宣告的邏輯 id 不同。使用已安裝 ID 可讓獨立的已安裝目錄保持區分,即使其資訊清單宣告了相同的邏輯 ID。

專案本機覆寫帶有合成的 project:_:{kind}:{name} ID,而內建層沒有 lookupId。這些值標識成品堆疊的來源;它們不是成品來回鍵,來回請使用 id 搭配 artifact info。manifestPath 標識宣告資訊清單,sourcePath 在存在時標識支援該層的具體檔案。核心、專案覆寫與其他合成列可能回報 sourcePath: null。

貢獻查詢

specify artifact lookup <lookupId> --json

將資訊清單支援的堆疊 lookupId 解析為 Spec Kit 使用的已驗證預設集或擴充功能宣告。回傳的宣告反映正常的資訊清單處理,包括標準的擴充功能命令名稱、注入的預設值(例如空的別名清單)與小寫的預設集策略。它不是撰寫的 YAML 的逐字呈現。

這讓跨參照行為保留在 artifact 命令內:預設集與擴充功能命令、資訊清單與解析器回傳形狀都不變。

回應包含穩定的查詢 ID、提供者座標、資訊清單與來源路徑,以及 contribution 下的有效宣告。僅依慣例的貢獻與專案覆寫沒有起源資訊清單宣告,因此查詢會回傳 {"error": "unknown contribution <lookupId>"},結束代碼為 1。內建列永遠沒有 lookupId。

Hook 成品

Hook 列從標準預設集與擴充功能解析器包含的擴充功能中,投影 hook 宣告。來回簡寫為:

hook:{encodedEventName}:{encodedTargetCommand}

例如,以下兩者選取同一個 hook 成品:

specify artifact info hook:before_specify:speckit.compliance.pre-check --json
specify artifact info before_specify:speckit.compliance.pre-check --kind hook --json

Hook 事件與目標命令元件使用 URL 引用的 UTF-8 百分比編碼:ASCII 字母、數字、-、.、_ 與 ~ 保持字面,其餘所有位元組都會編碼。此編碼僅限於成品 id、name 與 lookupId 中的 hook 元件;hook 資訊清單、執行時期繫結、eventName 與 targetCommand 不變。例如,名為 custom:after、目標為 /skill:speckit-test-ext-hello 的事件,其成品 ID 為:

hook:custom%3Aafter:%2Fskill%3Aspeckit-test-ext-hello

Hook 列新增三個最上層欄位:

欄位 說明
eventName 觸發宣告的 hook 事件
targetCommand hook 宣告呼叫的命令
registered 當至少一個宣告堆疊項目具有已啟用的執行時期繫結時為 true

每個 hook 堆疊項目還包含宣告正規化後的 priority 與 optional 值。Hook 項目永遠使用 strategy: "additive" 與 hidden: false:多個擴充功能可以宣告並註冊相同的事件—命令配對,且每個已啟用的宣告都保持啟用。堆疊項目依 hook 優先順序排序,並以解析器的確定性宣告順序作為同分時的決斷依據。此順序描述宣告清單;它不保證同優先順序的 hook 在執行時期以相同順序執行。

對於 hook,active 回報的是來自 .specify/extensions.yml 的註冊狀態,不是條件評估。宣告只有在執行時期設定包含具有相同擴充功能 id、事件與命令的已啟用繫結時才啟用。條件在 hook 執行時稍後才評估。因此,遺失、格式錯誤或無法讀取的執行時期設定,會讓宣告以 registered: false 與 active: false 保持可見。

已宣告但未註冊的 hook,在其擴充功能被正常解析器包含時仍保持可見。在登錄中停用的擴充功能會被完全排除,與其其他貢獻一致。無效的個別擴充功能資訊清單同樣會被既有解析器省略,並可透過擴充功能檢查與驗證命令診斷。

Hook 查詢 ID 使用成品私有的 {layer}:{sourceId}:hook:{encodedEventName}:{encodedTargetCommand} 文法,其中 sourceId 是已安裝的提供者 ID。Hook 來源限於 preset 與 extension 層;hook 永遠不會收到內建/核心層。目前的資訊清單 API 公開擴充功能 hook 宣告,因此目前的列使用 extension 層。preset 層在 hook 識別碼文法中保留給預設集提供的 hook,無需將成品 ID 新增到預設集或擴充功能資訊清單 API。

JSON 錯誤

失敗時,不會寫入任何內容到 stdout。單鍵 JSON 信封會寫入 stderr,行程以代碼 1 結束:

{ "error": "unknown artifact command:nope" }
訊息 原因
not a Spec Kit project: no .specify/ directory found 在已初始化專案外執行
unknown artifact <name> 沒有成品符合所請求的名稱(以及給定時的 kind)
ambiguous artifact <name>: matches kinds [...] 裸名稱符合多於一種 kind,請以 --kind 重新執行
artifact resolution failed 無法讀取擴充功能登錄,或有錯誤阻止成品層堆疊被蒐集

結束代碼 2 保留給使用錯誤,也就是遺失 --json 旗標或無效的 --kind 值,並在 stderr 發出純文字訊息,而非 JSON 信封。