用 MineAgent 画布搭多智能体并编译成独立 Python 项目：33 种推理模式、supervisor 委派与 mock LLM 零密钥跑通

想试多智能体协作，通常卡在两件事：框架代码写不动，模型 Key 还没申请下来。MineAgent 把这两步都绕开了——它是一个本地跑的浏览器画布，拖节点、连线、选推理模式，点「保存」就把整张画布编译成一个可独立运行的 Python Agent 项目；再配一个内置的假模型服务，没有 API Key 也能把「画布 → 代码 → 运行 → 事件流」整条链路跑完。本教程按官方 README 六步操作，Windows 上照抄命令即可。

🧩 适合谁：想理解多智能体分工但不想先啃 LangGraph / AutoGen 代码的产品、运营、学生；以及需要快速给团队演示 supervisor 加 worker 协作的开发者。前置准备：Windows / macOS / Linux 一台机器、Python 与 Node.js 运行环境（启动脚本会自动建虚拟环境与装依赖）、一个浏览器、约几百 MB 磁盘。本教程主线用内置 mock 模型，全程不需要任何 API Key。

先弄清：画布不是重点，编译出来的项目才是

官方把 MineAgent 定义成前后端分离的本地项目：前端 React 18 加 React Flow 负责画布，后端 Python FastAPI 加 SQLite 存画布与配置，生成的代码放在 projects/<画布名>/。它和其它可视化编排工具的差别在于「保存即产出」：

你做的动作	系统实际产出	本教程落在哪步
选框架与推理模式	生成对应架构图的节点链，33 种模式各有最小可用模板	Step 2
给 agent 勾上下级	关系注入运行时上下文，supervisor 默认模板遍历下级逐个委派	Step 3
点保存	生成 `agent.py` 等一整套可独立部署的项目文件	Step 4
点运行	拉起 `runner.py` 子进程，逐 token 与逐节点事件回传浏览器	Step 5

项目很新，请以仓库 README 为准：官方仓库在 2026-11-05 前后创建，社区模板、流式运行与 33 个推理模式标注为「最近新增」，功能面与星标数会持续变化。本教程按本次核对的 README 撰写；许可为 Apache-2.0，商用与闭源分发允许，但需保留版权声明与 NOTICE。启动脚本面向 Windows 提供 start.bat / start.ps1，其它平台请先确认脚本可用性。

Step 1：一键启动，打开本地画布

1 双击或一条 PowerShell 命令

启动脚本会自动完成 Python 虚拟环境、后端依赖、前端依赖、前端构建、启动服务与打开浏览器。默认地址是回环地址，刚启动时若没有画布，会自动创建一张 LangChain 架构图。

# 方式一：Windows 双击 start.bat

# 方式二：命令行（PowerShell）
.\start.ps1

# 指定端口 / 开发模式（前端 5173 热更新 + 后端 8000）
.\start.ps1 -Port 8080
.\start.ps1 -Dev

# 前端改了代码没生效时重建
.\start.ps1 -Rebuild
# 不想自动开浏览器
.\start.ps1 -NoBrowser

# 默认访问地址
# http://127.0.0.1:8000

💡 官方说明同一局域网内其它设备可用 http://<你的内网IP>:8000 访问。只在需要手机 / 同事预览时开，别在不受信任的网络里暴露这个端口。

启动脚本会装依赖：它会自动建虚拟环境并安装前后端依赖，等于在本机执行第三方包安装。公司机器请先确认网络与合规要求；中文提示若显示乱码，官方说明 start.ps1 已存为 UTF-8 with BOM，可用 PowerShell 7 运行或用 -NoBrowser 检查提示信息，不要随手改存成别的编码。

Step 2：选框架与推理模式，先拿一张能跑的画布

2 33 种模式直接生成节点链

右上角选 Agent 框架（LangChain / LangGraph、AutoGen、CrewAI 等），切换后会重建架构图；框架左边的「选择模式」下拉列出该框架支持的推理模式，选中后作为画布默认，新建 agent 节点会用它。每个 agent 还能在属性面板里单独选推理策略，保存后写进 agent.json 的 params.mode：

# 节点属性「推理模式」的六个取值（写进 agent.json 的 params.mode）
react           # 思考 → 调工具 → 观察，循环直到能给出答案
plan_execute    # 先列执行计划，再逐步执行，最后汇总
goal            # 围绕目标反复推进，每轮自评达成度
reflexion       # 先出一版，自我批判后重写
tool_call       # 只做一轮工具调用，快且便宜
simple          # 单次推理，不循环不用工具

# 模式模板示例（选模式即生成节点链）
# ReAct:              input → agent(react) → tool → 观察 → 回到 agent → output
# 主管调度:            input → 主管 → worker → 汇总 → output
# 并行处理:            input → 拆分支 → 分支 A/B → 合并 → output
# 护栏校验:            input → 输入校验 → Agent → 输出校验 → output

✅ 官方说明 33 个模式模板全部通过编排约束检查（0 error / 0 warn）。新手建议先选「主管调度」或「并行处理」，节点少、关系直观；想排查画布问题可点顶部「⚠ 约束」，违规节点会在画布上标红。右键空白画布能搜出 110 种节点，含 MCP、护栏、人工审批与 RAG 全链路节点。

保存前的硬约束：每个智能体强制要求一个 input 和一个 output 方块，缺少时保存会被拦下并提示。别把「组织关系」当成数据连线——它只表达调度关系，画布上的数据仍靠节点右侧圆点拖出来的边传递。

Step 3：搭 supervisor 加 worker，用 ctx.delegate 派活

3 勾上下级，分层协作就成型了

在 agent 节点属性面板里指定「上级」「下级」「平级」，改一边另一端会自动同步。运行时这些关系会注入节点上下文，代码里可以直接用官方给出的这组能力：

# 运行时注入到节点上下文的能力（官方 README 原生写法）
ctx.superior                    # 我的上级 agent 名字
ctx.subordinates                # 我的下级 agent 名字列表
ctx.peers                       # 我的平级 agent 名字列表
ctx.delegate("名字", 任务)       # 把活派给某个 agent，等它返回结果

# supervisor 节点的默认模板就是：
# 遍历 ctx.subordinates 逐个 delegate，再汇总结果
# 画一张 supervisor + 若干 worker、勾好上下级即可跑出分层协作

节点右下角还有一个红色小端口，拖出来是红色虚线「错误」边：节点失败时接了错误边就走错误分支继续跑，没接才中断整条流程；失败策略选「走 error 连线」后，原生模式会生成 conditional_edges 做分流。节点属性里另有可靠性开关——超时、失败重试次数、重试退避、每分钟调用上限、失败策略、执行沙箱、工具调用幂等，生成代码由统一的 _track 包装执行。

🔎 官方说明可靠性开关不是画布节点，而是节点属性：重试、超时、限流属于「怎么跑」的执行约束，做成节点会诱导把控制流当业务流。生成代码只对网络、限流、超时类错误重试，超过每分钟上限会等待。

循环要设上限：官方运行原理写明，走回边按循环处理，每个节点最多访问 8 次（agent.json 里 max_visits 可调）。用 reflexion、goal 这类会自我迭代的模式时，先保持默认值跑通，再决定要不要调高，否则容易在 mock 模型下无限打转。

Step 4：点保存，拿到一个可独立运行的 Python 项目

4 projects 目录里就是完整后端

顶部「保存」（或 Ctrl/Cmd + S）会把画布落库，并实时生成 projects/<画布>/ 下的全部代码。官方强调：整个文件夹拷走就能跑，不依赖 MineAgent 平台，也不依赖数据库。

# 生成项目的主要文件（官方 README 目录说明）
agent.py            # 核心：这一整张画布的框架原生代码
server.py           # FastAPI 入口：/chat、/chat/stream、/health、/ready、/metrics
settings.py         # 服务配置，环境变量驱动
telemetry.py        # 结构化日志 + 轻量 metrics
checkpoint.py       # 会话持久化
Dockerfile          # 容器镜像
docker-compose.yml  # 一条命令起服务
.github/workflows/ci.yml
tests/              # pytest 冒烟测试，不需要真实模型
agent.json          # 画布图定义：节点、连线、参数、节点代码
runner.py           # 零依赖预览执行器
runtime_sdk.py      # runner 用的运行时（只用标准库）
run.ps1 / run.sh    # 一键运行
config.json         # 模型配置（不含 key）
.env.example        # 脱离网页独立运行时复制成 .env 填 key
requirements.txt    # 该框架需要的依赖

# 装框架依赖（Windows，路径换成你的画布名）
.\.venv\Scripts\python.exe -m pip install -r "projects\你的画布\requirements.txt"

💡 打开 agent.py 能看到每个节点是带 ═══ 标记的原生代码块，网页上「代码逻辑」显示的就是同一段，改那里保存后 agent.py 跟着改。官方还说明：本机没装对应框架时，agent.py 会自动提示并回退到内置 runner.py，保证流程任何时候都能跑。

别在项目目录里手改代码：官方 FAQ 写明「以画布为准」，点保存会覆盖生成文件；如果要改，始终在网页里编辑节点代码，或者改完就别再回网页点保存。另外配置密钥不写进项目文件，独立运行时才在 .env 里填 MINEAGENT_API_KEY。

Step 5：零密钥跑通全流程，看逐节点事件流

5 另开一个窗口起 mock 模型服务

官方专门给了免 Key 路线：另开终端起本地假模型服务，再到「用户中心 → 模型配置」把 Base URL 指过去，整条链路就能完整跑起来。

# 另开一个窗口，在项目根目录执行
.\.venv\Scripts\python.exe tools\mock_llm.py --port 8012

# 浏览器里：用户中心 → 模型配置
# Base URL : http://127.0.0.1:8012/v1
# 模型名   : mock-model
# API Key  : 随便填一个占位值即可

# 回到画布点顶部「运行」，观察运行面板：
# 执行到哪个节点哪个节点高亮（脉冲边框 + 运行中角标）
# 逐条打印节点、耗时、输出；模型输出逐 token 流式回显

🎉 预期效果：运行面板依次出现 node_start 与 node_end 事件（含耗时、输出、重试次数），模型输出按 token 回显，最终结果单独展示。官方运行原理说明后端拉起 runner.py 子进程，通过 stdout 的 @@EVENT@@{json} 行回传事件，再以 SSE 推给浏览器——所以你能逐节点盯着它跑。

mock 只验链路，不验质量：假模型不会给出有意义的推理结果，它证明的是编译、执行、事件流与多智能体委派都通了。接真实服务商时按官方说明检查 Base URL 是否带 /v1（例如 DeepSeek 预设是 https://api.deepseek.com/v1）与模型名是否一致，报 401 / 404 多半是这两处写错。

Step 6：跑测试、配真实模型、把项目搬走

6 五组测试与四级模型配置

官方仓库自带覆盖后端、代码生成、约束、多 agent 委派与浏览器交互的测试脚本。配真实模型时有四级优先级，从高到低依次是节点级、画布级、全局、项目 .env：

# 官方 README 列出的测试脚本（Windows 虚拟环境路径）
.\.venv\Scripts\python.exe tools\smoke_test.py        # 后端 + 代码生成 + 真实执行
.\.venv\Scripts\python.exe tools\api_test.py          # 框架切换 / 改名 / 删除
.\.venv\Scripts\python.exe tools\constraint_test.py   # 编排约束与运行拦截
.\.venv\Scripts\python.exe tools\feature_test.py      # Agent 模式 / 多 agent 委派
.\.venv\Scripts\python.exe tools\granularity_test.py  # 110 节点与检索链路
cd frontend
node test/ui-smoke.mjs                                   # 浏览器端交互

# 模型配置四级优先级（高 → 低）
# 1 节点级：右键 agent → 配置模型 / API Key
# 2 画布级：右上角「模型」
# 3 全局：用户中心 → 模型配置
# 4 项目文件：projects/<画布>/.env 写 MINEAGENT_API_KEY=sk-xxx

✅ 填完 Base URL 与 Key 可点「测试连接」立即验证；模型名不用手敲，点输入框右边「⟳ 获取列表」会调服务商 /v1/models 拉候选，服务商不提供该接口时再手填。Key 加密存本机 backend/data/mineagent.db，接口只回显掩码；节点级 Key 运行时以 MINEAGENT_KEY_<节点ID> 环境变量注入子进程。

密钥安全与实际费用：加密入库并不等于密钥不会外泄，backend/data/ 下有 mineagent.db 与 master.key，别提交、别外发；官方 FAQ 说明想从头重来可删掉 backend/data/ 与 projects/ 内容重启，但会生成新主密钥、已存 Key 需重填。接真实模型会产生费用，先在服务商控制台设低额度上限；上传社区模板官方说明会自动剔除密钥，仍建议提交前自查一遍。

常见问题 FAQ

现象	原因与处理
8000 端口被占用	用 `.\start.ps1 -Port 8080` 换端口
前端改了没生效	`.\start.ps1 -Rebuild`，或进 frontend 目录跑 `npm run build`
保存被拦下	每个智能体缺 `input` 或 `output` 方块，补齐再保存
提示缺少模型 API Key	按 Step 5 配 mock 服务，或在四级配置里任选一处填真实凭据
真实模型报 401 / 404	检查 Base URL 是否带 `/v1`、模型名与服务商是否一致
运行一直打转	循环节点默认最多访问 8 次，检查 reflexion / goal 回边与 `max_visits`
生成项目跑不起来	装 `projects\你的画布\requirements.txt`；未装框架时会自动回退 `runner.py`

做到哪一步算成功

四条验收线：① .\start.ps1 起服务后能打开本地画布并看到自动生成的架构图；② 选「主管调度」模式、勾好 supervisor 与 worker 的上下级，保存不报约束错误；③ projects/<画布>/ 下生成了 agent.py、server.py、agent.json 等一整套文件；④ 起 mock_llm.py 后点运行，运行面板能看到逐节点事件与逐 token 输出，且 smoke_test.py 通过。做到这些，再把真实模型 Key 填进画布级配置做一次对比。

交付前自查：本教程命令全部来自官方仓库 README 与其 FAQ；项目迭代较快，节点数量、模式数量与脚本参数请以你克隆当天的 README 为准。生成的 Python 项目自带 Dockerfile 与 CI，部署到生产前仍要做代码审查与权限收敛，画布能跑通不等于可以上线。

← 返回教程中心