plasma-ai/fractal

fractal – 层级式自主代理循环

是什么

一个 Python 库和 CLI，允许你以 Git worktree 的树形结构运行递归自主代理。树中的每个节点都是一个独立的代理循环，可以为子任务生成子节点，形成一种随问题规模增长的分形结构。
所有运行记录均存储在本地 SQLite 数据库中，可通过基于终端的 UI（TUI）进行检查或控制。

如何工作

根节点 – 当前 Git 分支充当顶层“用户”节点（不拥有自己的 worktree）。
生成 – 通过 /fractal 技能（或 fractal CLI）发出自然语言指令。代理解析指令，询问缺失参数，然后为子节点创建新的 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；未推断任何额外功能。

plasma-ai/fractal

fractal – 层级式自主代理循环

相关