用途
Fractal 旨在用层级式、递归自组织的智能体循环来完成复杂任务。它把自主智能体循环组织成一棵 git worktree 树：每个节点在自己的工作树中朝一个目标迭代，并在遇到可分离的子任务时派生出子节点。这样任务树会根据问题实际需要生长，而不是执行一个预先固定的计划。
主要能力
- 树形智能体循环：无工作树、无自身循环的根（用户）节点是当前分支；顶层节点从它分支，子节点从父节点分支。
- 硬性边界：每个循环受迭代次数、深度、子节点数、后代总数、成本与时间等上限约束。
- 运行时元数据：所有状态（runs、iters、steps、costs、signals）记录在本地 SQLite 数据库，可通过终端 UI 实时查看与交互。
- 五种智能体后端：Claude Code（claude）、Codex（codex）、Grok Build（grok）、OpenCode（opencode）、Oh My Pi（omp），用 --agent 按节点选择，子节点继承。
- OpenRouter 路由：Claude 与 Codex 可通过 --provider=openrouter 走 OpenRouter，从启动 shell 的 OPENROUTER_API_KEY 认证；OpenCode 与 Oh My Pi 通过自身的 openrouter/<author>/<model> 模型 ID 原生接入。
- 无人值守循环：默认禁用审批门（Claude bypassPermissions、Codex danger-full-access、Grok --always-approve、opencode --auto、omp --yolo），节点可运行其智能体决定的任意命令。
- 操作者控制：可随时引导或停止循环。
使用方式
从 PyPI 安装：
- pipx install plasma-fractal 或 uv tool install plasma-fractal。使用这两种隔离安装方式时，还必须安装 plasma-wiki；一条命令等价写法为 uv tool install plasma-fractal --with-executables-from plasma-wiki。
- 普通 pip install 会拉取 plasma-wiki 并将 wiki 放入 PATH。
在项目根目录用 fractal open 打开仪表盘（需已初始化的 fractal），浅色终端加 --light。
为智能体安装 skill：可通过插件市场（Claude Code 和 Codex）；或从 CLI 安装，将 fractal 与 wiki skill 复制（或符号链接）到 ~/.claude/skills 与 ~/.agents/skills（加 --project 仅当前项目）。升级包后重新运行 fractal install 刷新已复制的 skill（--link 用于符号链接安装）。
使用 /fractal skill 生成和管理智能体节点；也可直接使用 CLI，运行 fractal --help 和 fractal <command> --help 探索。skill 以 /fractal [directive] 调用，接受自然语言指令，智能体会解释指令、打印可提炼出的 NODE.md 指令与完成要求，以及各参数表格（指令未提及处留空），再询问无法推断的内容，随后引导细化节点定义，批准后在 tmux 会话中启动节点。tmux 无法运行时加 --headless，节点输出追加到 headless.log；委托的子节点沿用父节点后端，未加标志的重启会复用节点上次启动的后端。
skill 可解释的参数包括：name（节点名，仅字母数字与下划线，必填）、path、title、scope、base、meta、inherit、agent、provider、model、effort、max-iters、max-depth、max-children、max-descendants、timeout、iter-timeout、step-timeout、interval、sleep、wait、max-cost、max-iter-cost、max-step-cost、reserve-budget、sync、detached、local。
本地开发安装：在包根目录运行 install.sh，无活动环境时创建并使用本地 .venv，有活动环境（如 pyenv）时在其中可编辑安装。./install.sh --help 可看全部选项；也可手动执行 uv sync --all-extras --group test --group lint --group type 与 uv run pre-commit install。可编辑安装下 fractal install --link 会符号链接内置 skill。安装后用 uv run --no-sync <command> 运行工具，或先 source .venv/bin/activate。
运行测试套件（启用 --doctest-modules，集成测试会创建真实 git 仓库与 worktree），以及运行 linter 与 formatter。贡献工作流、仓库约定与发布流程见 CONTRIBUTING.md、AGENTS.md、RELEASING.md；PR 应从 dev 分支拉出并针对 dev 提交，main 仅在发布时推进。
适用场景
适合将可分解的复杂任务交给多个自主智能体并行、分层推进，并需要成本、时间与深度等硬约束以及统一运行元数据追踪的场景。由于节点默认无审批提示运行且可执行任意命令，只应启动你信任其无人监督运行的任务节点，其他情况优先使用沙箱或可丢弃的主机。
限制
- 每个节点的 git worktree 只隔离其提交的分支，不隔离文件系统、网络或其他外部环境。
- 无人值守循环无法停下来询问，审批门默认禁用，节点拥有你的凭据与机器的可达范围。
- 成本上限按每次运行独立设置：预算结束的运行后，node start --continue 若无显式 --max-cost 会被拒绝。
- 部分参数（如 max-step-cost）在无法强制执行时仅为警告。
许可
Apache License 2.0，详见 LICENSE。Copyright © 2026 Plasma AI。
