minimal-workflow 0.5.1 → 0.5.3

package/README.md

@@ -0,0 +1,86 @@
+# minimal-workflow
+
+> minimal-agent **workflow YAML 的可视化编辑器** —— 拖拽节点、连线、属性表单、实时校验，
+> 双向同步到 `workflows/*.yaml`。基于 Bun + Vite + React + [@xyflow/react](https://reactflow.dev)。
+
+`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/` 子目录）作为编辑对象。
+
+```bash
+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 个端点
+```
+
+## 命令
+
+```bash
+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`，绝不暴露外网。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-workflow",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Visual editor for minimal-agent workflow YAML files",
   "type": "module",
   "bin": {

package/src/canvas/WorkflowCanvas.tsx

@@ -10,6 +10,8 @@ import {
   type EdgeChange,
   type Connection,
   addEdge,
+  ReactFlowProvider,
+  useReactFlow,
 } from '@xyflow/react';
 import '@xyflow/react/dist/style.css';
 
@@ -43,7 +45,8 @@ const edgeTypes = {
   sequential: SequentialEdge,
 };
 
-export function WorkflowCanvas() {
+function WorkflowCanvasInner() {
+  const { screenToFlowPosition } = useReactFlow();
   const nodes = useWorkflowStore((s) => s.nodes);
   const edges = useWorkflowStore((s) => s.edges);
   const setNodes = useWorkflowStore((s) => s.setNodes);
@@ -117,18 +120,15 @@ export function WorkflowCanvas() {
       } catch {
         return;
       }
-      const bounds = (e.target as HTMLElement)
-        .closest('.canvas')!
-        .getBoundingClientRect();
-      const position = {
-        x: e.clientX - bounds.left - 90,
-        y: e.clientY - bounds.top - 30,
-      };
+      // 用 ReactFlow 的 screenToFlowPosition 把屏幕像素换算成画布(flow)坐标，
+      // 自动吃掉当前缩放 / 平移 —— 缩放或平移后拖入的节点也能精确落在光标处
+      // （旧实现用 getBoundingClientRect + 硬编码偏移，viewport 一变就落偏）。
+      const position = screenToFlowPosition({ x: e.clientX, y: e.clientY });
       const id = nextId(payload.kind, nodes.map((n) => n.id));
       const step = makeStepTemplate(payload.kind, id, payload.name);
       addStep(step, position);
     },
-    [nodes, addStep],
+    [nodes, addStep, screenToFlowPosition],
   );
 
   /**
@@ -166,6 +166,16 @@ export function WorkflowCanvas() {
   );
 }
 
+export function WorkflowCanvas() {
+  // ReactFlowProvider 提供 useReactFlow() 的 context（screenToFlowPosition 等）。
+  // 必须包在渲染 <ReactFlow> 的组件之外，Inner 才能在 onDrop 里拿到正确的坐标换算。
+  return (
+    <ReactFlowProvider>
+      <WorkflowCanvasInner />
+    </ReactFlowProvider>
+  );
+}
+
 function nextId(kind: StepKind, existing: string[]): string {
   let i = 1;
   while (existing.includes(`${kind}_${i}`)) i++;

package/src/canvas/nodes/BaseNode.tsx

@@ -4,8 +4,7 @@ import type { CanvasNodeData } from '../../types.ts';
 
 interface BaseNodeProps extends NodeProps {
   data: CanvasNodeData;
-  selected?: boolean;
-  /** 节点种类 css class（决定边框色） */
+  /** 节点种类 css class（决定边框色）；selected 继承自 NodeProps（ReactFlow 注入） */
   variant: string;
   /** 节点标题（如 "🔧 tool: bash"） */
   title: string;
@@ -34,7 +33,9 @@ export function BaseNode({
       {body && <div className="node-body">{body}</div>}
       {errors && errors.length > 0 && (
         <div style={{ marginTop: 4 }}>
-          <span className="badge err">{errors.length} 错误</span>
+          <span className="badge err" title={errors.join('\n')}>
+            {errors.length} 错误
+          </span>
         </div>
       )}
       {!outputs || outputs.length === 0 ? (

package/src/inspector/Inspector.tsx

@@ -27,6 +27,27 @@ export function Inspector() {
         {kind} · {step.id}
       </h2>
 
+      {node.data.errors && node.data.errors.length > 0 && (
+        <div
+          style={{
+            background: '#fef2f2',
+            border: '1px solid #fca5a5',
+            borderRadius: 4,
+            padding: '6px 8px',
+            marginBottom: 8,
+            fontSize: 12,
+            color: '#b91c1c',
+          }}
+        >
+          <strong>{node.data.errors.length} 个问题</strong>
+          <ul style={{ margin: '4px 0 0', paddingLeft: 16 }}>
+            {node.data.errors.map((err, i) => (
+              <li key={i}>{err}</li>
+            ))}
+          </ul>
+        </div>
+      )}
+
       <CommonStepFields step={step} onPatch={onPatch} />
 
       {kind === 'tool' && <ToolNodeForm step={step} onPatch={onPatch} />}

package/src/store/workflowStore.ts

@@ -3,6 +3,7 @@ import type { Edge, Node } from '@xyflow/react';
 import type {
   CanvasNodeData,
   StepDef,
+  StepKind,
   WorkflowDef,
   WorkflowEdgeMeta,
 } from '../types.ts';
@@ -368,7 +369,7 @@ function sameErrors(
   return true;
 }
 
-function detectKind(step: StepDef): string {
+function detectKind(step: StepDef): StepKind {
   if (step.type) return step.type;
   if (step.tool) return 'tool';
   if (step.skill) return 'skill';
@@ -464,7 +465,7 @@ function assembleWorkflow(
       visiting.add(cur);
       claimed.add(cur);
       chain.push(cur);
-      const nexts = siblingAdj.get(cur) ?? [];
+      const nexts: string[] = siblingAdj.get(cur) ?? [];
       // 链只走第一个 sibling 后继（DAG 上的"线性"分支）
       cur = nexts[0];
     }

package/src/types.ts

@@ -104,9 +104,13 @@ export interface Manifest {
   skills: SkillMeta[];
 }
 
-/** 图模型节点 data 字段 */
-export interface CanvasNodeData {
+/**
+ * 图模型节点 data 字段。
+ * 交叉 `Record<string, unknown>` 以满足 @xyflow/react `Node<T>` 对 data 的约束
+ * （T extends Record<string, unknown>）；已知字段仍各自保留类型，访问 step/kind/errors 不受影响。
+ */
+export type CanvasNodeData = {
   step: StepDef;
   kind: StepKind;
   errors?: string[];
-}
+} & Record<string, unknown>;

package/src/yaml-view/sync.ts

@@ -127,7 +127,9 @@ export function stringifyWorkflowYaml(def: WorkflowDef): string {
 
 // ADR-05：控制流 type 集合——这些节点的"动作"由 type 自身定义，
 // 不能附带 tool/skill/llm，也不能配 output_schema / context_files / allowed_tools。
-const CONTROL_FLOW_TYPES = new Set<string>([
+// 导出供主项目的 schema 一致性测试比对（test/editorSchemaSync.test.ts）——
+// 这两份是手抄后端 loader.ts 的（D2 红线禁止运行时 import 后端），导出后由测试守护不漂移。
+export const CONTROL_FLOW_TYPES = new Set<string>([
   'assert',
   'branch',
   'loop',
@@ -137,7 +139,7 @@ const CONTROL_FLOW_TYPES = new Set<string>([
 ]);
 
 // 合法的 step.type 枚举（与后端 VALID_STEP_TYPES 同集）。
-const VALID_STEP_TYPES = new Set<string>([
+export const VALID_STEP_TYPES = new Set<string>([
   'assert',
   'branch',
   'loop',
@@ -215,7 +217,7 @@ function topLevelErrors(def: WorkflowDef): string[] {
           errors.push(`inputs[${i}] 必须是对象`);
           return;
         }
-        const r = item as Record<string, unknown>;
+        const r = item as unknown as Record<string, unknown>;
         if (typeof r.name !== 'string' || r.name.length === 0) {
           errors.push(`inputs[${i}].name 必填（非空 string）`);
         }