minimal-workflow

minimal-agent workflow YAML 的可视化编辑器 —— 拖拽节点、连线、属性表单、实时校验， 双向同步到 workflows/*.yaml。基于 Bun + Vite + React + @xyflow/react。

v0.4.1 · 独立子项目（不属于 minimal-agent npm 包发布物），单独 package.json / 依赖 / Bun ≥ 1.1。

这是什么

minimal-agent 的 workflow-runner 插件用 YAML DAG 描述工作流（9 种 step：tool / llm / skill / assert / branch / loop / pause / parallel / vote）。手写 YAML 容易出错，这个编辑器让你画图：

• 左侧 Palette 拖出节点；中间 画布 连线表达顺序与 then/else/do 子步骤；右侧 Inspector 编辑属性
• 实时校验：每个节点显示错误数（hover / Inspector 看详情），规则镜像后端 loader.ts
• YAML 视图双向：图 → YAML 预览，编辑 YAML → 校验通过后回写图
• 撤销/重做（Ctrl+Z / Ctrl+Shift+Z）、画布布局与连线持久化到 __meta（runner 严格忽略，不影响执行）

工具 / skill 的元数据（名称、参数 schema）由编辑器在启动时从目标项目的 src/tools + skills 自动导出成 <project>/.editor-cache/manifest.json，过期自动重建。

运行

需要一个 minimal-agent 项目目录（含 workflows/ 子目录）作为编辑对象。

cd editor
bun install

# 一键启动（推荐）：起 IO 服务 + Vite + 自动开浏览器
bun start ..                      # 用上级目录（minimal-agent 本体）作为项目
bun start /path/to/your-project   # 或指定任意含 workflows/ 的项目

CLI 选项（bun start --help）：

| 选项 | 说明 | |---|---| | --port <n> | 编辑器（Vite）端口，默认 5173 | | --server-port <n> | 文件 IO 服务端口，默认 5174 | | --refresh-manifest | 强制重新生成 manifest | | --no-manifest-refresh | 跳过 manifest 新鲜度检查 | | --no-open | 不自动打开浏览器 |

纯前端调试用 bun run dev，但那样不会起 IO 服务（读写 / manifest 接口会 404）—— 日常用 bun start <project> 即可。

架构

editor/
├─ scripts/
│  ├─ cli.ts          # 入口：manifest 新鲜度检查 → spawn server + vite → 开浏览器
│  └─ server.ts       # 本地 IO 服务（Bun.serve，127.0.0.1，仅本地）：/api/{list,read,write,manifest}
└─ src/
   ├─ App.tsx         # 三栏布局 + 工具栏（新建 / 保存 / YAML 视图 / 撤销重做）
   ├─ types.ts        # 与 workflow-runner 同形的模型（D2 红线：手抄、禁 import 后端）
   ├─ canvas/         # ReactFlow 画布 + 9 种节点组件 + 连线
   ├─ inspector/      # 属性面板（按 kind 分发到各表单）+ inputs 面板
   ├─ palette/        # 左侧节点 / 工具 / skill 拖拽源
   ├─ store/          # zustand：workflow（含 undo/redo + 图↔def 拓扑组装）/ manifest / files
   ├─ yaml-view/      # 图 ↔ YAML 纯函数互转（parse / stringify / validate）
   └─ api/            # 调 server 的 4 个端点

命令

bun start [project-dir]   # = bun scripts/cli.ts，一键启动
bun run dev               # 仅 Vite 前端（不含 IO 服务）
bun run server            # 仅 IO 服务（需 WORKFLOW_UI_PROJECT_DIR 环境变量）
bun run build             # Vite 生产构建
bun run typecheck         # tsc --noEmit
bun test                  # 单元测试（sync / store / undo / 表单 等）

与 minimal-agent 的关系（解耦红线）

• D2 解耦：编辑器运行时不 import minimal-agent / workflow-runner 的任何代码（要能在浏览器跑）。 step 模型与校验规则是手抄后端的（src/types.ts、src/yaml-view/sync.ts）。
• 防漂移：手抄会随后端演进而过时，故主项目用 test/editorSchemaSync.test.ts 守护 —— 后端 loader.ts 的 VALID_STEP_TYPES / CONTROL_FLOW_TYPES 一变该测试就红，提示同步本编辑器。
• __meta：保存的 YAML 里 __meta（节点坐标、连线）仅供编辑器还原布局，runner 严格忽略， 不影响执行语义。
• 本地 only：IO 服务仅监听 127.0.0.1，绝不暴露外网。