fusion/README.zh-CN.md

Fusion

从粗糙想法到生产代码——全程自动化。

多节点智能体编排器 — 任务、智能体、任务群、Git、文件与工作树，支持任意模型，本地与云端皆可。

runfusion.ai → · 文档 · GitHub · npm · Discord

English · 简体中文 · 繁體中文 · Français · Español · 한국어

本文档为社区机器翻译版本，英文 README 为权威原版。

---

你的整个开发环境。尽在一块面板之上。

用自然语言描述一个任务。规划智能体会读取你的项目、理解上下文，并撰写完整的 PROMPT.md 计划——包括步骤、文件范围和验收标准。随后 Fusion 在隔离的 Git 工作树中完成规划、审核、执行与再审核，你可以在任意环节设置人工审批门控。

一块看板。随处操控。笔记本、Mac mini、Linux 服务器、云虚拟机、手机——全部互联。

就像 Trello，只不过你的任务由 AI 来定义、执行和交付。基于 dustinbyrne/kb 的出色工作构建。

---

工作流程

  ①  描述              ②  规划                  ③  看板                  ④  隔离工作树
  ─────────────        ─────────────         ─────────────          ─────────────────────
  "在设置面板    →   智能体撰写    →   规划 → 审核 →      →   fusion/FN-123 分支
   添加深色模式        PROMPT.md           执行 → 审核              并行运行，零
   切换按钮"          （步骤、范围、        （逐步进行，直到          文件冲突
                       验收标准）           完成）

合并前看清每一步

每个任务都会实时展示其计划、审核记录、差异对比和文件变更。你可以随时介入活跃任务，调整方向、收紧约束、暂停执行或重新提示。

---

与众不同之处

🧠 AI 规划	用自然语言描述任务。规划智能体将其转化为包含步骤、文件范围和验收标准的 PROMPT.md 计划。
🔁 工作流门控	每个步骤均经历：规划 → 审核 → 执行 → 审核。合并前门控阻止劣质代码，合并后门控执行信息性检查。
🌳 工作树隔离	每个任务在独立分支和工作树（fusion/{task-id}）中运行，支持并行任务，零冲突。可通过 worktrunk.enabled 选择性启用 worktrunk 委托（参见 WorktreeBackend 抽象）。
⚡ 智能合并	通过所有门控后，Fusion 自动压缩合并并继续推进。你也可以在任意环节开启手动审批。
🛰️ 多节点网格	笔记本、Mac mini、Linux 服务器、云虚拟机、手机——全部同步。桌面端、移动端、Web 端均支持。
🧩 任意模型	支持 Anthropic、OpenAI、Ollama 等，本地与云端并存。
🏢 智能体公司	导入预构建团队——16 家公司共 440+ 个智能体——自主运行数周。
📬 智能体间消息	内置智能体间邮箱，支持委派、澄清与协调。
🗨️ 多智能体聊天室	项目范围内的群组会话，多位成员可以回复：被提及成员为直接响应者，其他旁听成员在上限内也可参与回复。当前为实验性功能——在设置 → 实验性功能 → 聊天室中启用 chatRooms。（聊天室文档）
🗺️ 任务群	层级式规划（任务群 → 里程碑 → 切片 → 功能 → 任务），支持自动驾驶和验证契约。
🔬 调研	有边界的调研运行，集成网络搜索、GitHub、本地文档和 LLM 综合分析（规划与综合流程中还支持运行时内置 WebSearch/WebFetch）。将调研发现直接转化为任务。（文档）
🧪 自我改进	智能体反思自身输出，并在熟悉你的代码库后持续更新其提示词。
🔓 开源，MIT 协议。	无供应商锁定。可在自有硬件上运行。每周持续更新。

---

工作原理

graph TD
    H((你)) -->|粗糙想法| T["规划中<br/><i>自动规划</i>"]
    T --> TD["待办<br/><i>已安排执行</i>"]
    TD --> IP["进行中<br/><i>每步骤：<br/>规划、审核、执行、审核</i>"]

    subgraph IP["进行中"]
        direction TD
        NS([开始步骤]) --> P[规划]
        P --> R1{审核}
        R1 -->|修改| P
        R1 -->|批准| E[执行]
        E --> R2{审核}
        R2 -->|修改| E
        R2 -->|下一步| NS
        R2 -->|重新规划| P
    end

    R2 -->|完成| IR["审核中<br/><i>待合并，<br/>或自动完成</i>"]
    IR -->|直接压缩合并<br/>或 PR 合并| D["已完成"]

    style H fill:#161b22,stroke:#8b949e,color:#e6edf3
    style T fill:#2d2006,stroke:#d29922,color:#d29922
    style TD fill:#0d2044,stroke:#58a6ff,color:#58a6ff
    style IP fill:#1a0d2e,stroke:#bc8cff,color:#bc8cff
    style P fill:#1a0d2e,stroke:#bc8cff,color:#e6edf3
    style R1 fill:#1a0d2e,stroke:#bc8cff,color:#e6edf3
    style E fill:#1a0d2e,stroke:#bc8cff,color:#e6edf3
    style R2 fill:#1a0d2e,stroke:#bc8cff,color:#e6edf3
    style NS fill:#1a0d2e,stroke:#bc8cff,color:#bc8cff
    style IR fill:#0d2d16,stroke:#3fb950,color:#3fb950
    style D fill:#1a1a1a,stroke:#8b949e,color:#8b949e

有依赖关系的任务按顺序处理，相互独立的任务并行运行。可选择在任务从规划移至待办前要求手动审批（requirePlanApproval 设置）。

---

多节点。一块看板。全平台覆盖。

笔记本、Mac mini、Linux 服务器、云虚拟机、手机——每个节点都是对等方。你的任务状态、智能体、日志和差异对比在整个网格中保持同步。同一个 Fusion 提供以下形态：

• 🖥️ 桌面应用 — 基于 Electron，支持 macOS（Intel + Apple Silicon）、Windows 10/11 和 Linux
• 📱 移动应用 — 基于 Capacitor，支持 iOS/iPadOS 和 Android（MOBILE.md）
• 🌐 Web 仪表板 — 任意现代浏览器，由 fn dashboard 守护进程提供服务
• 🔌 CLI — fn 二进制文件 + 扩展，面向终端优先的工作流

在任意节点启动守护进程，连接其他设备，看板随你所在。

---

运行一个智能体公司

导入一个团队，自主运行数周。16 家公司共 440+ 个智能体，预置了任务群、邮箱和智能体间委派机制。

npx companies.sh add paperclipai/companies/gstack

---

与你已在使用的工具兼容。

Fusion 与你喜爱的工具深度集成。Hermes、Paperclip 和 OpenClaw 均作为一等公民插件发布——将任意工作区路由到最适合该任务的运行时。任何 Paperclip 智能体公司均可通过单条命令导入。

Hermes _experimental

_{Nous Research}

Nous Research 出品的开源自主智能体。安装 Hermes 插件后，可通过 Hermes 运行智能体以处理长期运行、上下文持续增长的工作——将任意 Fusion 工作区路由至其上。

OpenClaw _experimental

OpenClaw 运行时支持以实验性插件（fusion-plugin-openclaw-runtime）的形式提供，用于运行时发现与配置对等。安装插件后，使用 runtimeConfig.runtimeHint: "openclaw" 配置智能体。

Paperclip _experimental

_{paperclip.ing}

AI 劳动力的人工控制平面。安装 Paperclip 插件后，可在 Fusion 内部通过 Paperclip 运行智能体。

Fusion 还原生支持 companies.sh 智能体公司标准：导入预构建团队——16 家公司共 440+ 个智能体——让它们通过 Fusion 的邮箱、任务群和工作流门控协作，自主运行数周。与 Paperclip 共用相同的公司格式、相同的智能体和相同的技能。

npx companies.sh add paperclipai/companies/gstack

Hermes、Paperclip 和 OpenClaw 均为实验性运行时插件——API 和通信格式可能在次要版本间发生变更。

---

快速上手

无需安装，直接通过 npm 运行：

npx runfusion.ai

这将启动仪表板。子命令可透传：npx runfusion.ai task create "fix X"、npx runfusion.ai --help 等（或完整写法：npx @runfusion/fusion dashboard）。

一键安装脚本（macOS 和 Linux——自动选用 Homebrew，失败则回退到 npm）：

curl -fsSL https://runfusion.ai/install.sh | sh
fusion dashboard

Homebrew（macOS 和 Linux）：

brew tap runfusion/fusion
brew install fusion
fusion dashboard            # 或：fn dashboard

或使用一行命令（自动添加 tap）：brew install runfusion/fusion/fusion。

npm 全局安装：

npm install -g @runfusion/fusion
fn dashboard                # 或：fusion dashboard

从克隆仓库启动（用于开发）：

pnpm dev dashboard

然后点击终端输出的 Open: URL。该 URL 内嵌了一个持有者令牌 （http://localhost:4040/?token=fn_...），浏览器首次访问时会将其捕获并存入 localStorage，此后自动复用。在服务端，Fusion 会在首次经过身份验证的运行时将 仪表板/守护进程令牌持久化至 ~/.fusion/settings.json，并在后续启动时复用， 除非你通过 --token、FUSION_DASHBOARD_TOKEN、FUSION_DAEMON_TOKEN 覆盖， 或使用 --no-auth 禁用鉴权。完整的优先级规则及重置/吊销选项，请参见 CLI 参考 → fn dashboard → 身份验证。

首次运行向导

首次启动时，Fusion 会打开引导向导，分三步引导：

1. AI 配置 — 使用简化的快速启动提供商列表（推荐提供商加上已连接的提供商），如需添加更多提供商或查看详细设置，展开高级提供商设置即可。入门只需一个提供商。已弃用的 Google Gemini CLI / Antigravity 提供商条目已被有意隐藏；Google/Gemini API 密钥、Google Generative AI、Vertex 和 Cloud Code 路径仍受支持。
2. GitHub（可选） — 连接 GitHub 以导入 Issue 和管理 PR
3. 第一个任务 — 创建你的第一个任务，或从 GitHub 导入（若当前无活跃项目，引导向导会先提示你注册/选择项目目录）

向导可关闭且不阻塞——点击暂时跳过即可立即使用仪表板。稍后可从设置 → 身份验证 → 重新打开引导向导再次触发。

移动端

Capacitor + PWA 工作流，请参见 MOBILE.md。

---

文档

指南	内容
入门指南	安装与引导
仪表板指南	看板/列表视图、终端、Git 管理器
任务管理	任务生命周期与 CLI 命令
CLI 参考	完整命令与守护进程参考
设置参考	配置选项
架构	系统内部机制
智能体	智能体管理、生成与心跳
工作流步骤	质量门控、模板与阶段
任务群	任务群层级、规划与自动驾驶
多项目	中央注册表与隔离模式
Docker	容器部署

---

核心功能

• AI 规划 — 规划智能体生成包含步骤、文件范围和验收标准的详细 PROMPT.md
• 逐步执行 — 每个任务步骤均经历规划 → 审核 → 执行 → 审核循环
• Git 工作树隔离 — 每个任务在独立工作树（fusion/{task-id} 分支）中运行
• 工作流步骤 — 可配置的质量门控（合并前：阻止合并；合并后：信息性检查）
• GitHub 集成 — 导入 Issue、创建 PR、实时 PR/Issue 徽章
• 仪表板 — 实时看板、智能体管理、终端、Git 管理器、任务群规划器
• 任务群 — 层级式规划（任务群 → 里程碑 → 切片 → 功能 → 任务），支持自动驾驶、验证契约、修复功能重试和阻塞移交语义
• 多项目 — 从单一安装管理多个项目，项目间相互隔离
• 智能体间消息 — 内置消息机制，用于智能体与用户之间的协调
• 聊天室（实验性） — 项目范围内的群组聊天，被提及成员作为直接响应者路由，其他旁听成员在上限内可回复（通过设置 → 实验性功能 → 聊天室启用；详情见仪表板指南 → 聊天室）

提供商身份验证

Fusion 支持通过设置 → 身份验证为 AI 提供商配置基于 OAuth 的身份验证。对于大多数 OAuth 提供商，当仪表板通过非 localhost 主机访问（远程节点、局域网主机/IP 或反向代理）时，提供商登录 URL 会被重写，通过桥接端点（/api/auth/oauth-callback）路由 OAuth 回调，以确保重定向能到达活跃的浏览器会话。

• Anthropic (Claude) — 在设置/引导向导中使用粘贴授权码流程：登录后，将最终重定向 URL（或授权码）粘贴回 Fusion 以完成登录
• OpenAI Codex — 使用相同的粘贴授权码流程，附带安全状态验证
• Factory AI — 通过 Droid CLI （可选） — 需要本地安装 Droid CLI 并执行 droid auth login；检测遵循有效运行时二进制路径（默认为 droid，或配置了插件 droidBinaryPath 时使用该路径），然后在设置 → 身份验证中启用并重启 Fusion
• llama.cpp — 通过 HTTP 服务器 （可选） — 配置你的 llama.cpp 服务器 URL（默认 http://127.0.0.1:8080）和可选 API 密钥，然后在设置 → 身份验证中启用
• 其他提供商 — 在设置中通过 API 密钥条目进行身份验证（包括 Google/Gemini API 密钥、Google Generative AI、Vertex 和 Cloud Code 别名）

模型系统

Fusion 使用双作用域模型层级，包含五条独立通道。全局设置定义基准默认值，项目设置提供每个项目的覆盖配置。

通道	用途	全局基准键	项目覆盖键
执行器	任务执行智能体	executionGlobalProvider + executionGlobalModelId	executionProvider + executionModelId
规划器	任务规划智能体	planningGlobalProvider + planningGlobalModelId	planningProvider + planningModelId
验证器	计划/代码审核	validatorGlobalProvider + validatorGlobalModelId	validatorProvider + validatorModelId
标题摘要	自动标题生成	titleSummarizerGlobalProvider + titleSummarizerGlobalModelId	titleSummarizerProvider + titleSummarizerModelId
工作流步骤优化	AI 提示词优化	（使用 defaultProvider/defaultModelId）	（使用 WorkflowStep 上的 modelProvider/modelId）

任务级覆盖： 任务可通过任务级模型字段（modelProvider/modelId、validatorModelProvider/validatorModelId、planningModelProvider/planningModelId）覆盖执行器、验证器和规划器通道。

优先级： 任务级 → 项目覆盖 → 全局通道 → defaultProvider/defaultModelId → 自动解析。

完整设置文档，请参见设置参考。

计划任务 / 自动化

Fusion 通过 /api/automations 端点支持计划任务自动化。自动化任务可按可配置的计划运行 Shell 命令或多步骤工作流。

调度范围

自动化任务和例程可在两种范围内运行：

• 全局 — 跨所有项目运行。适用于跨项目维护、备份或统一报告。
• 项目 — 仅在特定项目内运行。适用于项目特定的 CI、测试或部署任务。

创建计划时若未选择范围，Fusion 默认使用 project 范围并以 default 项目 ID，以保持向后兼容。

显式指定范围的方式：

• 在仪表板的计划任务模态框中，使用全局 / 项目切换开关。
• 通过 API，在自动化/例程端点上传递 ?scope=global 或 ?scope=project&projectId=<id>。

范围解析规则：

• scope=global 始终解析到全局自动化/例程通道，与活跃项目无关。
• scope=project 需要 projectId。若省略，则回退到 "default"。
• 增删改查、运行、切换和 Webhook 操作严格按范围隔离：全局计划不能通过项目范围请求修改，反之亦然。

多项目环境操作建议：

• 共享基础设施（如夜间备份、记忆洞察提取）优先使用全局计划。
• 仓库级自动化（如每项目测试运行器、部署钩子）优先使用项目计划。
• 全局通道和项目通道由引擎独立轮询，一个通道中到期的运行不会阻塞另一个。

自动化任务

端点	方法	说明
/api/automations	GET	列出所有自动化任务（若指定范围则按范围过滤）
/api/automations	POST	创建自动化任务（范围默认为 project）
/api/automations/:id	GET	按 ID 获取自动化任务
/api/automations/:id	PATCH	更新自动化任务
/api/automations/:id	DELETE	删除自动化任务
/api/automations/:id/run	POST	触发手动运行
/api/automations/:id/toggle	POST	切换启用/禁用
/api/automations/:id/steps/reorder	POST	重排自动化步骤顺序

例程

例程是由 Cron 计划、Webhook 或手动执行触发的 AI 智能体任务。例程与自动化任务共用相同的全局/项目范围模型。

端点	方法	说明
/api/routines	GET	列出所有例程（若指定范围则按范围过滤）
/api/routines	POST	创建例程（范围默认为 project）
/api/routines/:id	GET	按 ID 获取例程
/api/routines/:id	PATCH	更新例程
/api/routines/:id	DELETE	删除例程
/api/routines/:id/run	POST	手动触发
/api/routines/:id/trigger	POST	规范化手动触发
/api/routines/:id/runs	GET	获取执行历史
/api/routines/:id/webhook	POST	Webhook 触发（支持签名验证）

---

CLI 快速示例

fn task create "Fix the login bug"                    # 快速录入 → 规划
fn task plan "Build auth system"                      # AI 辅助规划
fn task import owner/repo --labels bug                # 导入 GitHub Issue
fn task show FN-001                                   # 查看任务详情
fn task logs FN-001 --follow                          # 流式查看执行日志
fn task steer FN-001 "Use TypeScript"                 # 在执行中途引导智能体

fn project add my-app /path/to/app                    # 注册项目
fn project list                                       # 列出所有项目

fn settings set maxConcurrent 4                       # 配置设置
fn settings export                                    # 导出配置

fn mission create "Auth System" "Build auth"          # 创建任务群
fn mission activate-slice <slice-id>                  # 激活切片

fn skills search react                                # 搜索 skills.sh
fn skills install firebase/agent-skills               # 安装智能体技能

---

包结构

包	说明
@fusion/core	领域模型——任务、看板列、SQLite 存储
@fusion/dashboard	Web UI——Express 服务器 + 带 SSE 的看板
@fusion/engine	AI 引擎——规划、执行、调度、工作流步骤
@runfusion/fusion	CLI + 扩展——发布至 npm

---

开发

pnpm install                  # 安装依赖
pnpm local                    # 在非 4040 端口启动本地仪表板/API
pnpm local -- --engine        # 启动带 AI 引擎的本地仪表板
pnpm build                    # 构建默认工作区包（不含桌面端/移动端）
pnpm build:all                # 构建所有包（含桌面端/移动端）
pnpm dev dashboard            # 运行仪表板 + AI 引擎
pnpm dev:ui                   # 仅仪表板（无 AI 引擎）
pnpm lint                     # 对所有包执行代码检查
pnpm typecheck                # 对所有包执行类型检查
pnpm test                     # 运行所有测试

构建独立可执行文件

使用 Bun 构建单个自包含的 fn 二进制文件：

pnpm build:exe                # 为当前平台构建
pnpm build:exe:all            # 跨平台编译所有目标

---

许可证

MIT — 开源，无供应商锁定。详见 LICENSE。

runfusion.ai →