Spellcast Universe

寫下咒語，生成圖片，保留整次創作的可追溯紀錄。

English README

Spellcast Universe 是一個以 Codex 為核心、在本機執行的 CLI。它整合 Prompt Universe 與 image-gen-runner，將咒語、執行紀錄與圖片放回你的創作專案。

Inspiration

圖片創作很容易開始，卻很難重現：成功的描述散落在聊天紀錄，圖片則躺在 final-v7 類型的資料夾。Spellcast Universe 把咒語、設定、run 紀錄與圖片放在一起。

What it does

npm i -g @bobo-ai/spellcast-universe
mkdir my-spellbook && cd my-spellbook
spellcast prompt "一顆草莓"
spellcast 4

不需要先執行 init。第一次使用會自動建立：

prompts/       # 使用者可閱讀、編輯的 Prompt Universe Markdown 咒語
images/        # 每次產圖各自獨立的結果資料夾
.spellcast/    # 內部 runtime 快照、manifest 與可恢復狀態

prompt 會呼叫 Codex、編譯並驗證結構化咒語，完成後顯示 Markdown 路徑。 spellcast 4 使用目前咒語產生四張圖片，收集完成後顯示 images/ 路徑。

How we built it

Spellcast Universe 是 npm CLI，內含兩個 revision lock 的 runtime：

• Prompt Universe：結構化咒語、編譯、驗證與變體擴展。
• image-gen-runner：Codex 任務準備、圖片 session 隔離與安全收集／清理。

UPSTREAM-LOCK.json 記錄匯入 revision。每個專案會將 runtime 複製至 .spellcast/runtime/；Spellcast Universe 不會修改原始的 Prompt Universe 或 image-gen-runner 開發專案。

Challenges we ran into

兩個來源專案對驗證、審核、wave gate、圖片 session 與清理都有必要的安全邊界。 新的 CLI 縮短日常操作，但保留這些限制。

所有耗時工作都會顯示即時狀態：自動初始化、Codex 寫入咒語、Prompt Universe 編譯或擴展、runner 準備、圖片啟動與收集，以及最終輸出位置。

自動產圖目前需要 macOS Terminal.app、Node.js 20+、Python 3、SBCL 與已登入的 Codex CLI。第一次使用前請執行 spellcast doctor。

Accomplishments that we're proud of

• 兩個指令即可完成創作，並產出專案內真正可讀的 Markdown 與圖片檔。
• 每次 run 都保存來源、外部工具進度與可恢復狀態。
• 單向、revision lock 的上游整合，不影響兩個原始專案。
• 經驗證的變體批次可直接產圖，不需手動搬移檔案。

What we learned

簡短的命令不該隱藏創作決定或來源。讓咒語與圖片輸出位置清楚可見，能讓迭代與 中斷後恢復都更可靠。

What's next for ThreadCommander

下一步會改善結果檢視與跨平台手動圖片匯入，並逐步帶入 ThreadCommander 的更多工作流， 同時維持日常 Spellcast 操作的簡潔。

Built With

Node.js、Common Lisp/SBCL、Python 3、Codex CLI、macOS Terminal.app、Prompt Universe 與 image-gen-runner。

Try it out

先生成咒語，再生成圖片

npm i -g @bobo-ai/spellcast-universe
mkdir my-spellbook && cd my-spellbook

spellcast doctor
spellcast prompt "金色芒果果凍吉祥物，透明玻璃質感，童話插畫"
spellcast 4

咒語會顯示類似 prompts/golden-mango-jelly-....md 的路徑；圖片會顯示類似 images/images-golden-mango-.../ 的路徑。可先使用 spellcast 4 --dry-run 檢視產圖計畫，不呼叫 image runner。

一口氣完成咒語與產圖

spellcast "一顆草莓" 4

加上 --review 只會寫入並驗證咒語，不會開始產圖。

批次生成變體咒語

spellcast prompts/strawberry.md "更換各種水果和背景" --variant --count 100

這會呼叫 Codex 撰寫變體規則，再由 Prompt Universe 驗證並匯出 100 份 Markdown 到新的 prompts-...-variants-.../ 資料夾。預設不會產圖；只有明確加上 --run 才會接著產圖：

spellcast prompts/strawberry.md "更換各種水果和背景" --variant --count 100 --run

對整批咒語產圖

spellcast prompts-strawberry-variants-2026-07-18/ --all
spellcast prompts-strawberry-variants-2026-07-18/ 4

第一行會對資料夾內每份咒語各產一張圖；第二行只會依穩定檔名順序處理前四份。 使用 spellcast status 查看 run，使用 spellcast resume <run-id> 繼續 wave 並將 已收集圖片匯出到 images/。

spellcast status
spellcast status <run-id>

status <run-id> 會顯示目前階段（例如 authoring、compiling、image-launch 或 image-collection）、最新訊息，以及已知的咒語、圖片與 runner 路徑。

npx @bobo-ai/spellcast-universe … 仍可單次使用，但主要建議採用全域安裝。

維護者文件：上游更新 · 發佈清單。

License and attribution

Prompt Universe 依 Fan & Personal Non-Commercial License 內含於本專案。重新散布前請閱讀 隨附的 license 與 notices。