Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Specula:安裝、使用與相關工具

查核日期:2026-10-28。本文以 Specula 官方專案 的 README、Usage Guide 和本地 1.2.0 原始碼為依據。指令與支援範圍可能隨版本改變,實際操作前可再執行 specula --help、specula run --help。

Specula 是什麼?

Specula 是針對並行與分散式系統程式碼找深層錯誤的工具。它讓程式代理閱讀目標程式碼,建立描述系統行為與正確性條件的 TLA+ 模型,再用模型檢查器搜尋違反條件的執行路徑;找到候選問題後,還會嘗試用實際程式碼與測試環境重現。它適合檢查共識協定、狀態同步、併發控制、故障恢復等容易出現交錯執行錯誤的程式。來源:Specula README

流程可簡化為:

目標程式碼 → 分析與建模 → TLA+ 規格 → 產生執行 trace 的 harness
           → trace 驗證與 TLC 模型檢查 → 程式碼層確認 → 嚴重度報告

這個流程結合抽象模型與程式碼驗證。模型檢查通過不等於整份程式碼已被證明正確:結果仍取決於建模範圍、抽象方式、檢查設定,以及 harness 能否呈現真實行為。候選錯誤也應閱讀重現證據,而非只看模型反例。來源:Specula 論文

安裝前準備

必要項目用途
Python 3.10+,含 pip、venvCLI 與 MCP 工具環境
uv安裝 specula 命令
JDK 21+、MavenTLA+ 檢查工具與 CFA 工具建置
Git、Bash、curl 或 wget原始碼操作與初次下載
GitHub CLI (gh)儲存庫及 issue 研究
一種受支援的代理 CLI執行分析流程,例如 Claude Code、Codex、Copilot CLI、OpenCode 或 Pi
目標專案自己的建置與測試依賴產生 harness 和重現錯誤

specula setup 不會安裝上表的系統依賴或代理 CLI。初次設定需能連到 GitHub、PyPI、Maven Central;代理執行時還需模型供應商的帳號或憑證。官方建議至少 32 GB RAM 與 100 GB 可用磁碟空間;模型檢查可能需要大量時間與記憶體。來源:Specula Usage Guide

支援 Linux、macOS,以及在 WSL2 內執行的 Windows。macOS 還需 GNU coreutils,並將 gnubin 放進 PATH;Windows 原生終端目前不是官方支援的執行環境。來源:平台需求

安裝 Specula

先自行安裝上述依賴與一種代理 CLI,接著執行:

git clone https://github.com/specula-org/Specula.git
cd Specula
uv tool install -e .
specula setup
specula --help

這裡的 -e 很重要:specula 命令會呼叫儲存庫內的腳本,所以安裝後要保留該 checkout。specula setup 會下載 TLA+ JAR、建置 CFA 工具、建立 MCP 工具環境,並詢問是否整合偵測到的代理。它不會執行完整的目標專案分析。來源:安裝說明

若使用 Codex,設定畫面可選 y(分別安裝 skills 與 MCP)或 plugin(安裝 specula-codex@specula)。Plugin 會作用於目前 Codex profile,可供該 profile 下各專案使用;這是設定時要留意的範圍。來源:Codex 設定

第一次執行

在 Specula checkout 根目錄執行,將 /absolute/path/to/source 換成已能正常建置的目標儲存庫絕對路徑:

specula run \
  --agent=codex \
  --artifact=/absolute/path/to/source \
  --keep-original \
  "mysys|owner/repository|Go|系統設計或參考演算法"

--agent=codex 可改為 claude-code、copilot-cli、opencode 或 pi;若省略,預設使用 claude-code。最後的引號內依序是輸出名稱、GitHub 儲存庫、主要語言、參考設計,必須加引號,否則 | 會被 shell 當作管線。--artifact 指向要分析的原始碼。來源:First run

--keep-original 會在私有副本中分析,保留原 checkout,並輸出可審閱的 changes.patch。若不加這個選項,harness 或重現工作可能直接修改 --artifact 指向的原始碼。首次探索建議使用私有副本。來源:Output Structure

需要把分析集中在特定模組或情境時,可先參考建模指引範本,再加上 --guidance=/absolute/path/to/guidance.md。這個檔案是建議項,不是安裝必要條件。來源:First run

結果在哪裡?

預設隔離模式把產物放在 Specula checkout 的 runs/<run-id>/;runs/latest 指向最新執行。先看:

  1. runs/latest/pipeline-summary.md:整體狀態。
  2. runs/latest/index.md:選擇目標並進入個別報告。
  3. 目標的 .specula-output/index.md:摘要、確認結果、嚴重度及技術細節。
  4. pipeline.log:流程出錯時的日誌;使用 --keep-original 時再查看 changes.patch。

候選問題應逐一確認其重現結果與環境限制,不能把所有模型反例直接視為已證實的程式錯誤。來源:輸出結構

進階用法

情境命令或入口說明
已有 TLA+ 模型`specula run --byom=/absolute/path/to/model-or-assets --artifact=/absolute/path/to/source "mysysowner/repository
建立持續驗證基線`specula run --ci-init --ci-dir=/work/mysys-ci --artifact=/absolute/path/to/source "mysysowner/repository
檢查後續程式碼變更specula run --incremental --ci-dir=/work/mysys-ci使用上述基線檢查新版本
手動控制每個階段code-analysis → spec-generation → harness-generation → validation-workflow → bug-confirmation在代理中依序呼叫 skills;參閱 Interactive Mode

相關工具怎麼選?

工具主要用途與 Specula 的關係
TLA+ / TLC手寫 TLA+ 模型,用 TLC 檢查狀態空間Specula 以 TLA+ 與 TLC 為核心,額外串接代理、trace 與程式碼重現
TLA+ Toolbox / PlusCal編輯規格、把 PlusCal 演算法翻譯成 TLA+、查看 TLC 反例適合手動建模、學習及審查 Specula 產生的模型
Apalache使用 SMT 求解器對 TLA+ 模型做符號式、有限步數等檢查可補充 TLC 的檢查視角;有限步數未找到反例不代表所有長度都安全
SPIN以 Promela 描述並行系統並進行模型檢查同類形式驗證工具,但模型語言與工具鏈不同
Alloy以 Alloy 語言建模並搜尋符合或違反約束的實例適合研究結構關係與小範圍行為;需另寫 Alloy 模型
Jepsen對真實分散式系統施加故障並檢查操作歷史偏向黑箱整合測試,可補足抽象模型與真實部署之間的落差

這些工具不保證可直接讀取彼此的模型。若重點是快速分析既有程式碼並追蹤模型反例到實作,可先試 Specula;若要完全控制規格與檢查設定,可先從 TLA+ / TLC 或其他模型檢查器開始。Jepsen 適合驗證真實叢集在故障條件下的外部行為。來源:Specula、TLA+、Jepsen

常見問題

找不到 specula 命令? 確認 uv tool install -e . 已在 Specula checkout 執行,且 uv 的工具命令目錄位於 PATH。可先查 uv tool list 與 specula --help。uv 官方文件

specula setup 後仍不能跑? 先確認 Python、Java、Maven、gh、代理 CLI 與目標專案工具鏈都能執行;setup 不負責安裝這些依賴。需求清單

模型檢查很慢或記憶體不足? 先縮小建模範圍,檢查磁碟及 JVM 記憶體設定;進階參數見 specula run --help 與資源說明。

可以只用其中一段流程嗎? 可以。CLI 提供 analyze、specgen、harness、validate、confirm、classify 等分段命令;詳細輸入輸出見 Individual Steps。

參考資料