如何在本機開發 Spec Kit
在每個 checkout 或 worktree 中使用各自獨立的 .venv,以可編輯模式安裝該 checkout,並透過明確的環境路徑執行其 CLI 與測試。如此可讓本機變更與全域安裝的發行版本及其他 Spec Kit checkout 隔離開來。不需要啟用環境。
1. 準備 Checkout
安裝 Python 3.11+、uv 與 Git。複製你的 fork,並依照分支命名指引在功能分支上工作。從該 checkout 的儲存庫根目錄執行以下設定。
在 macOS 或 Linux 上:
uv sync --extra test
uv pip install --python .venv/bin/python -e .
.venv/bin/specify --help
在 Windows PowerShell 上:
uv sync --extra test
uv pip install --python .venv\Scripts\python.exe -e .
.\.venv\Scripts\specify.exe --help
uv sync --extra test 會建立專案環境並安裝其測試相依性。明確的可編輯安裝會以同一個環境為目標。編輯 Python 原始碼後不需要重新安裝;相依性中繼資料變更時再重新執行設定。
2. 執行聚焦的自動化檢查
先從涵蓋你變更的測試開始,並以實際的測試路徑取代以下範例。
在 macOS 或 Linux 上:
.venv/bin/python -m pytest tests/test_agent_config_consistency.py -q
在 Windows PowerShell 上:
.\.venv\Scripts\python.exe -m pytest tests/test_agent_config_consistency.py -q
要執行完整測試套件,請將測試檔案換成 tests。在 macOS 上,請為測試設定 LC_ALL=en_US.UTF-8,讓 Bash 的 Unicode 處理使用 UTF-8 locale:
LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests -q
執行與 CI 相同的 Ruff 版本:
uvx ruff@0.15.0 check src tests
Ruff 是獨立執行的 lint 工具;Spec Kit CLI 與 pytest 只能透過該 checkout 的 .venv 執行。正面與負面覆蓋率、迴歸證據、Windows PowerShell 5.1 相容性及其他檢查,請參閱貢獻者測試指引。
3. 在獨立專案中測試 CLI
在 Spec Kit checkout 之外初始化一個用完即棄的專案,並使用該 checkout 的 CLI。選擇你的代理的整合金鑰。
在 macOS 或 Linux 上,從 Spec Kit 儲存庫根目錄執行:
.venv/bin/specify init /tmp/spec-kit-test --integration <key> --script sh
在 Windows PowerShell 上,從 Spec Kit 儲存庫根目錄執行:
.\.venv\Scripts\specify.exe init "$env:TEMP\spec-kit-test" --integration <key> --script ps
每個獨立測試請使用未使用過的專案目錄。測試 Python 指令稿變體時請使用 --script py。在你的程式代理中開啟產生的專案,並在 slash 命令行為變更時遵循手動測試流程。
如果要從產生的專案中執行更多 CLI 命令,請使用 Spec Kit checkout 執行檔的絕對路徑;不要切換到全域安裝的 specify。請將以下範例 checkout 路徑換成你實際的 checkout 路徑。例如,要在產生的專案中檢查 CLI 並加入 git 擴充功能:
在 macOS 或 Linux 上:
"/path/to/spec-kit/.venv/bin/specify" --help
"/path/to/spec-kit/.venv/bin/specify" extension add git
在 Windows PowerShell 上:
& "C:\path\to\spec-kit\.venv\Scripts\specify.exe" --help
& "C:\path\to\spec-kit\.venv\Scripts\specify.exe" extension add git
PowerShell 呼叫運算子(&)會執行引用的路徑,包括含有空格的路徑。
產生的指令稿位於 .specify/scripts/ 之下。在 macOS 或 Linux 上測試 Bash 指令稿權限時,請從產生的專案中檢查它們:
ls -l .specify/scripts/bash/*.sh
指令稿應該具有擁有者執行位元。Windows 上的 PowerShell 指令稿不需要 chmod。
4. 在相關時檢查封裝
若有封裝變更,請從 Spec Kit 儲存庫根目錄建置 wheel:
uv build
檢查 dist/ 中的產出物。封裝驗證是可編輯安裝開發循環的補充,不能取代測試環境。
常見問題
| 症狀 | 處理方式 |
|---|---|
| 缺少 Python 相依性 | 從這個 checkout 的根目錄重新執行設定命令。 |
| 測試或 CLI 使用了另一個 checkout | 使用這個 checkout 明確的 .venv 執行檔路徑。 |
| 產生的專案中無法使用 Git 命令 | 從產生的專案中,使用其絕對 .venv 路徑執行該 checkout 的 CLI,並執行 extension add git。 |
| 產生了錯誤的指令稿變體 | 明確傳入 --script sh、--script ps 或 --script py。 |
| 公司網路發生 TLS 錯誤 | 設定憑證儲存區或 proxy,例如使用 SSL_CERT_FILE、HTTPS_PROXY 或 HTTP_PROXY。已棄用的 --skip-tls 旗標沒有作用。 |