plasma-ai/fractal
Hierarchical agent loops with recursive self-organization.
fractal – 層級式自主代理循環
是什麼
- 一個 Python 庫與 CLI，可讓你以 Git worktree 的樹狀結構運行 遞迴 自主代理。樹中的每個節點都是獨立的代理循環，可為子任務生成子節點，形成一種隨問題規模成長的 分形 結構。
- 所有執行記錄均儲存在本地 SQLite 資料庫中，可透過基於終端的 UI（TUI）進行檢視或控制。
如何運作
- 根節點 – 目前的 Git 分支扮演頂層「使用者」節點（不擁有自己的 worktree）。
- 生成 – 透過
/fractal技能（或fractalCLI）發出自然語言指令。代理解析指令，詢問遺漏的參數，然後為子節點建立新的 Git worktree。 - 迭代 – 每個節點在 tmux 會話中運行自主循環，呼叫支援的 LLM 後端之一（Claude、Codex、Grok、OpenCode、Oh My Pi）。循環可迭代、提交程式碼、執行命令，並生成更多子節點。
- 限制 – 對迭代次數、深度、子節點數量、時間及成本設置上限，確保每個循環都受控。預算按執行和步驟強制執行，支援可選的清理預留。
- 追蹤 – 每次迭代、步驟、成本和訊號均儲存在單一 SQLite 檔案中。TUI 電腦板可視化樹狀結構，顯示即時指標，並支援暫停/停止節點。
主要特性
- 遞迴自我組織 – 節點可建立更多節點，使系統能根據問題自適應調整結構。
- 多 LLM 後端支援 – 支援 Claude、Codex、Grok、OpenCode、Oh My Pi，可選透過 OpenRouter 路由。
- 細粒度控制 – 每個節點可設定最大迭代次數、最大深度、逾時、成本上限、作用域等參數。
- 以 Git 為中心的工作流程 – 每個節點在獨立的 Git worktree 中工作，提交隔離於特定分支，可推送或本地保留。
- 終端 UI – 實時儀表板（
fractal open）展示樹狀結構、成本和進度。 - 技能整合 – 可將
/fractal技能安裝至 Claude Code 或 Codex 代理中，實現自然語言啟動節點。 - 安全警告 – 節點預設無權限提示運行；README 強調僅在可信或沙箱主機上運行受信任任務。
安裝
# 從 PyPI（套件名為 "plasma-fractal"，但提供 "fractal" 入口點）
pip install plasma-fractal # 或：pip install fractal
# 隔離安裝（pipx、uv）時，還需安裝配套的 "plasma-wiki" 套件
pipx install plasma-fractal && pipx install plasma-wiki
# 或使用 uv：
uv tool install plasma-fractal --with-executables-from plasma-wiki
安裝後，從已透過 fractal init 初始化的專案根目錄執行 fractal open（README 假設專案已初始化 fractal）。
典型工作流程
# 開啟儀表板（可選淺色主題）
fractal open --light
# 透過 TUI 或技能發出指令，例如：
/fractal spawn name=docgen path=./docs title="產生 API 文件" agent=claude max-iters=5
# 系統將：
# • 解析指令，詢問遺漏欄位
# • 在 ./docs 下建立新的 Git worktree
# • 啟動執行 Claude 代理循環的 tmux 會話
# • 將每次迭代記錄到 SQLite 資料庫
# • 在儀表板中顯示進度
可透過 fractal node stop <name> 命令或與 UI 互動來停止、暫停或調整節點。
安全與限制
- 節點 無權限提示運行，意味著 LLM 可以以啟動使用者的憑證在主機上執行任意命令。README 警告：僅在可信或可丟棄的主機上運行不可信任務。
- 成本上限已強制執行，但僅按每次執行的美元計；必須設定適當的
max-cost值以避免 API 費用失控。 - 系統依賴外部 LLM 提供商；需要網路存取和 API 金鑰（例如
OPENROUTER_API_KEY）。
文件與社群
- 官方文件：https://docs.plasma.ai/fractal
- PyPI 頁面：https://pypi.org/project/plasma-fractal/
- 原始碼：https://github.com/plasma-ai/fractal (Apache‑2.0 許可證)
誰可能使用它
- 希望為大型程式碼庫重構、文件產生或多步驟 AI 驅動任務實現自動化、自我組織工作流程的開發者。
- 探索分層 AI 代理架構的研究人員。
- 已使用 Claude、Codex 或其他支援 LLM 並希望與 Git 緊密整合的團隊。
以上所有細節均直接取自倉儲的 README；未推斷任何額外功能。
相關
- 專案
- 專案
- 專案
- 專案
- 專案