plasma-ai/fractal

# fractal [](https://github.com/plasma-ai/fractal/blob/main/LICENSE) [](https://github.com/plasma-ai/fractal/actions/workflows/build.yaml) [](https://github.com/plasma-ai/fractal/actions/workflows/docs.yaml) [](https://github.com/plasma-ai/fractal/actions/workflows/lint.yaml) [](https://github.com/plasma-ai/fractal/actions/workflows/tests.yaml) [](https://codecov.io/gh/plasma-ai/fractal) [](https://github.com/pre-commit/pre-commit) 具有递归自组织能力的分层 agent 循环。 在 fractal 中，自主的 agent 循环会自发组织成一棵树：一个节点会在其专属的 `git worktree` 中向着目标进行迭代，并为可分离的子任务生成子节点，因此这棵树会根据问题本身的结构动态生长，而不是依赖固定的计划。硬性上限（迭代次数、深度、子节点数、成本、时间）确保每个循环都是有界的，操作员可以随时对其进行引导或停止。运行元数据（包括成本）会存储在同一个本地 `SQLite` 数据库中，您可以通过终端 UI 与其进行实时交互。  **源码**: [https://github.com/plasma-ai/fractal](https://github.com/plasma-ai/fractal) **包**: [https://pypi.org/project/plasma-fractal/](https://pypi.org/project/plasma-fractal/) **文档**: [https://docs.plasma.ai/fractal](https://docs.plasma.ai/fractal) ## 安装 从 PyPI 安装 `fractal` 包： ``` pip install plasma-fractal ``` 或 ``` pip install fractal ``` 使用 `pipx install` 或 `uv tool install` 在隔离环境中安装该包。如果您使用了这两种方法之一，您还必须安装 `plasma-wiki`（直接使用 `pip` 安拉时会拉取 `plasma-wiki` 并将 `wiki` 放入您的 `PATH` 中，但在使用 `pipx install` 或 `uv tool install` 时则不会如此）。 `uv tool install plasma-fractal --with-executables-from plasma-wiki` 可以通过一条命令完成相同的操作。 在您的项目根目录下使用 `fractal open` 打开仪表盘（需要已初始化的 fractal）。如果您的终端使用浅色配色方案，请加上 `--light` 参数。 ### Skill 通过插件市场为您的 agent 安装 skill（适用于 Claude Code 和 Codex）： ``` # Claude Code /plugin marketplace add plasma-ai/plugins /plugin install fractal@plasma # Codex codex plugin marketplace add plasma-ai/plugins codex plugin add fractal@plasma ``` 另一种安装途径是通过 CLI，它将 fractal 和 wiki skill 复制（或符号链接）到 `~/.claude/skills` 和 `~/.agents/skills`（添加 `--project` 则仅限当前项目使用）： ``` fractal install [--link] ``` 升级包之后，请重新运行 `fractal install` 以刷新复制的 skill（如果是符号链接安装，请加上 `--link`）。 ## 使用说明 fractal 是一棵由 git worktrees 组成的树，每个 worktree 运行着一个自主的 agent 循环。根节点从您的工作树中分支出来，子节点从其父节点分支出来。Agents 在 tmux 会话中进行迭代，所有状态（运行、迭代、步骤、成本、信号）都会被记录在本地 SQLite 数据库中。 支持五种 agent 后端 —— Claude Code (`claude`)、Codex (`codex`)、Grok Build (`grok`)、OpenCode (`opencode`) 和 Oh My Pi (`omp`) —— 可以通过 `--agent` 为每个节点进行选择（子节点会继承此设置）。Claude 和 Codex 还可以通过 `--provider=openrouter` 经由 OpenRouter 路由，该方式使用从启动 shell 中获取的 `OPENROUTER_API_KEY` 进行身份验证；OpenCode 和 Oh My Pi 则通过它们各自的 `openrouter//` 模型 ID 原生访问 OpenRouter。 使用 `/fractal` skill 来生成和管理 agent 节点。`fractal` CLI 也可以直接使用 —— 运行 `fractal --help` 和 `fractal --help` 来探索更多功能。 该 skill 通过 `/fractal [指令]` 调用，并接受自然语言指令。Agent 会对指令进行解释，打印出从指令中提取出的任何建议的 `NODE.md` 指令和完成要求，以及包含所有参数的表格（如果指令中未提及相应参数则留空），然后询问任何它无法推断的内容。接下来，它会引导您完善节点的定义，并在您批准后，于 tmux 会话中启动该节点。 该 skill 从指令中解析出的参数： - **`name`**：节点名称（必填；仅限字母、数字和 `_` —— 不允许使用 `-`） - **`path`**：项目根目录、仓库根目录或 monorepo 子项目（默认值：`.`） - **`title`**：人类可读的显示名称（默认值：去除连接符的节点名称） - **`scope`**：将提交限制在 worktree 内的子目录中 （逗号分隔，例如 `parent/child,tests`） - **`base`**：起始分支（默认值：当前分支） - **`meta`**：用于元配置的目标节点分支 - **`inherit`**：从父节点而不是包默认种子中提取基础配置 （逗号分隔：`steps`、`scripts`、`skills`、`config` 或 `all`）；agent 配置始终会被继承。顶层生成节点的父节点是用户节点，它不携带任何 steps、scripts 或 skills —— 该参数专用于生成子节点的已配置节点 - **`agent`**：agent 命令；省略时继承用户节点的默认设置 - **`provider`**：agent 的提供商路由（例如 `openrouter`）；省略时继承用户节点的默认设置 - **`model`**：模型覆盖设置；省略时，agent 使用其自身的默认模型 - **`effort`**：推理强度覆盖设置；省略时，将应用每个 agent 种子自身锁定的级别，而不是供应商的默认值 - **`max-iters`**：每次运行的迭代上限 - **`max-depth`**：子节点最大嵌套深度 - **`max-children`**：最大直接子节点数 - **`max-descendants`**：最大后代节点总数 - **`timeout`**：每次运行的时间限制（例如 `30m`、`1.5h`） - **`iter-timeout`**：每次迭代的时间限制（例如 `30m`、`1.5h`） - **`step-timeout`**：每个步骤的时间限制（例如 `30s`、`10m`）；对每个步骤进行封顶限制 - **`interval`**：固定的迭代计划（例如 `1h`） - **`sleep`**：迭代之间的延迟（例如 `10s`） - **`wait`**：在等待批准的同步调用之间的休眠时间（默认值：`1m`） - **`max-cost`**：每次运行以美元为单位的成本上限 —— 运行之间是相互隔离的，因此每次启动都会重新启用该上限；如果运行因预算耗尽而结束，在没有明确指定 `--max-cost` 的情况下，`node start --continue` 将被拒绝执行 - **`max-iter-cost`**：每次迭代的成本上限（美元） - **`max-step-cost`**：每个步骤的成本上限（美元）（无法强制执行时仅发出警告） - **`reserve-budget`**：为清理预留的预算；可以是美元金额或 `max-cost` 的 N%（默认值：10%） - **`sync`**：在每个步骤之前启用（默认）或禁用无线电同步 - **`detached`**：将每个步骤作为独立的 agent 会话运行（默认值：一个连续的会话） - **`local`**：在每次提交后跳过推送到远程仓库 ## 开发 ### 安装 在包的根目录下运行 `install.sh`。如果没有激活任何环境，它会创建并使用一个本地的 `.venv`；如果已有激活的环境（例如 pyenv），它将以可编辑模式安装到该环境中，且不会重新创建环境： ``` ./install.sh --all-extras --groups=test,lint,type ``` 运行 `./install.sh --help` 查看所有选项。或者，您也可以运行 `uv sync --all-extras --group test --group lint --group type` 和 `uv run pre-commit install` 来手动设置环境。 以可编辑模式安装依赖项（例如同级包）留给调用方自行处理：`uv pip install --editable `。 在可编辑安装的情况下，`fractal install --link` 会将捆绑的 skill 符号链接到 agent 的 skill 目录中，而不是直接复制它，因此对 skill 的修改无需重新运行安装即可生效。 安装完成后，请使用 `uv run --no-sync ` 运行工具，或者先激活环境（`source .venv/bin/activate`）。 ### 测试 运行测试套件： ``` pytest . ``` 该套件在运行时启用了 `--doctest-modules`，并且集成测试会创建真实的 git 仓库和 worktrees。 ### 代码检查 运行 linter 和格式化工具： ``` pre-commit run --all-files ``` ## 许可证 基于 Apache License 2.0 授权 —— 详见 [LICENSE](https://github.com/plasma-ai/fractal/blob/main/LICENSE)。 版权所有 © 2026 Plasma AI

标签：Git, SQLite, 人工智能, 安全规则引擎, 用户模式Hook绕过, 终端UI, 自动化任务, 逆向工具, 递归架构