跳轉到

SpecStory CLI

Terminology rule (zh-TW pages)

技術名詞首次出現以「中文 (English original)」格式呈現，例：依賴注入 (dependency injection)。不自創翻譯——若無公認譯名直接保留英文 （如 embedding、tokenizer）。代碼、API 名、CLI flag、套件名、檔名一律不翻。

SpecStory 記錄終端機的編碼代理 (coding agent) 工作階段 (session)，並能透過 specstory run 包裝受支援的代理。

在本 dotfiles repo 中的安裝

specstory 由 coding_agents ansible role 自動安裝。

  • macOS：優先使用 Homebrew，並以 GitHub release 退回安裝至 ~/.local/bin
  • Linux：從 GitHub release tarball 安裝至 ~/.local/bin

全域與專案設定

本 dotfiles repo 管理使用者層級的 SpecStory 設定 ~/.specstory/cli/config.toml。

SpecStory 依以下順序讀取設定：

  1. 使用者層級設定：~/.specstory/cli/config.toml
  2. 專案層級設定：./.specstory/cli/config.toml
  3. 傳給 specstory 的 CLI flag

後者覆蓋前者。也就是說 dotfile 提供全域預設值，而 repo 專屬的 .specstory/cli/config.toml 可在專案需要不同行為時覆寫之。

只種一次 (seed once)，不持續管理

使用者層級設定是 chezmoi 的 create_ 檔（private_dot_specstory/private_cli/create_config.toml）：chezmoi 只在第一次 apply 時寫入，之後不再更動它。這是刻意設計的 —— SpecStory CLI 會把執行期的 UI 狀態寫回這個檔（例如 specstory resume 之後產生的 [resume] 區塊，含 view_mode / last_agent），若持續管理就會變成永久的 chezmoi drift。要修改內建預設值，請改 source 檔再重新種一次：cp ~/.specstory/cli/config.toml "$(chezmoi source-path ~/.specstory/cli/config.toml)"。

受管理的預設值

受管理的設定保留上游範例區塊作為註解文件，但只啟用 [providers] 預設值。

已設定的 provider：

  • antigravity_cmd = "agy --dangerously-skip-permissions"
  • claude_cmd = "claude --dangerously-skip-permissions"
  • codex_cmd = 'codex -c model_reasoning_effort="high" --ask-for-approval never --sandbox danger-full-access -c model_reasoning_summary="detailed"'
  • cursor_cmd = "cursor-agent --force"
  • droid_cmd = "droid --yolo"
  • gemini_cmd = "gemini --sandbox=none"

這些是 specstory run claude、specstory run codex 與類似 provider 捷徑預設會執行的命令，除非在專案內或命令列上另行覆寫。

Codex 0.156.0 不接受舊的 model_supports_reasoning_summaries 覆寫值，啟動時會將它列為被忽略的 session-flags 設定。保留 model_reasoning_summary="detailed" 即可要求詳細摘要。既有主機需從 ~/.specstory/cli/config.toml 的 codex_cmd（及任何專案覆寫）中移除 -c model_supports_reasoning_summaries=true；chezmoi apply 不會更新這個只種一次的檔案。重新啟動 Codex 工作階段後才會使用修正後的命令。

一律明寫 provider —— 無參數的預設值並不穩定

<id>_cmd 只控制某個 provider 怎麼啟動，從來不決定裸的 specstory run 挑哪一個。設定裡沒有 default_provider 這個 key：沒有參數時，specstory 會解析成其 provider registry 中字母序第一個項目。因此 2.9.0 只是「加入」antigravity，就在所有既有安裝上悄悄把 claude 從預設位置擠掉，而 specstory run --help 也跟著重新生成成 By default, launches Antigravity CLI.。由於 agy 已安裝，錯的 agent 會成功啟動、完全不報錯。

請一律寫 specstory run claude。本 repo 的包裝層已經這麼做 —— 見 dot_config/shell/22_sesh.sh 的 _sesh_wrap_agent()（由 scode / svibe / hcode / hvibe 共用）與 pitfalls/specstory-run-default-agent-drift.md。

安全取捨

設定的 provider 命令刻意傾向低摩擦的代理執行：

  • Claude 使用 --dangerously-skip-permissions
  • Codex 使用 --ask-for-approval never 與 --sandbox danger-full-access
  • Antigravity 使用 --dangerously-skip-permissions；Cursor 使用 --force、Droid 使用 --yolo
  • Gemini 使用 --sandbox=none

這移除了大部分互動式權限提示，對快速本機工作流程很有用，但同時也讓被包裝的代理擁有更廣的檔案系統或命令存取權。只有在您信任該環境並重視便利勝於更嚴格的護欄時，才保留這些預設值。若否，請在全域檔、專案本機設定或 specstory run -c ... flag 中覆寫相關的 provider 命令。

驗證

specstory --version
specstory run codex --help
chezmoi diff

另見

參考資料