minimal-workflow 0.2.1 → 0.2.2

package/package.json

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

package/src/App.tsx

@@ -20,6 +20,10 @@ export default function App() {
   const setCurrentFile = useWorkflowStore((s) => s.setCurrentFile);
   const toWorkflowDef = useWorkflowStore((s) => s.toWorkflowDef);
   const markDirty = useWorkflowStore((s) => s.markDirty);
+  const undo = useWorkflowStore((s) => s.undo);
+  const redo = useWorkflowStore((s) => s.redo);
+  const canUndo = useWorkflowStore((s) => s.past.length > 0);
+  const canRedo = useWorkflowStore((s) => s.future.length > 0);
 
   const saveFile = useFilesStore((s) => s.save);
   const refreshFiles = useFilesStore((s) => s.refresh);
@@ -31,6 +35,37 @@ export default function App() {
     loadManifest().catch(() => {});
   }, [loadManifest]);
 
+  // 全局 Ctrl/Cmd+Z / Ctrl/Cmd+Shift+Z / Ctrl/Cmd+Y 快捷键
+  useEffect(() => {
+    const isEditable = (el: EventTarget | null): boolean => {
+      if (!(el instanceof HTMLElement)) return false;
+      if (
+        el instanceof HTMLInputElement ||
+        el instanceof HTMLTextAreaElement ||
+        el instanceof HTMLSelectElement
+      ) {
+        return true;
+      }
+      return el.isContentEditable;
+    };
+
+    const onKeyDown = (e: KeyboardEvent) => {
+      if (!(e.ctrlKey || e.metaKey)) return;
+      if (isEditable(e.target)) return; // 让原生 input undo 优先
+      const key = e.key.toLowerCase();
+      if (key === 'z' && !e.shiftKey) {
+        e.preventDefault();
+        undo();
+      } else if ((key === 'z' && e.shiftKey) || key === 'y') {
+        e.preventDefault();
+        redo();
+      }
+    };
+
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [undo, redo]);
+
   const onNewWorkflow = () => {
     if (dirty && !confirm('当前修改未保存，确定要新建？')) return;
     loadWorkflow({
@@ -100,6 +135,20 @@ export default function App() {
         {saveStatus && (
           <span style={{ fontSize: 12, marginRight: 8 }}>{saveStatus}</span>
         )}
+        <button
+          onClick={undo}
+          disabled={!canUndo}
+          title="撤销 (Ctrl+Z)"
+        >
+          ↶ 撤销
+        </button>
+        <button
+          onClick={redo}
+          disabled={!canRedo}
+          title="重做 (Ctrl+Shift+Z / Ctrl+Y)"
+        >
+          ↷ 重做
+        </button>
         <button onClick={onNewWorkflow}>新建</button>
         <button onClick={() => setYamlOpen((v) => !v)}>
           {yamlOpen ? '关闭 YAML 视图' : 'YAML 视图'}

package/src/canvas/WorkflowCanvas.tsx

@@ -45,26 +45,44 @@ export function WorkflowCanvas() {
   const setEdges = useWorkflowStore((s) => s.setEdges);
   const selectNode = useWorkflowStore((s) => s.selectNode);
   const addStep = useWorkflowStore((s) => s.addStep);
+  const commitHistory = useWorkflowStore((s) => s.commitHistory);
 
+  /**
+   * change-aware history：拖拽过程中 (position && dragging===true) 高频 emit，
+   * 不打点；拖拽结束 (position && dragging===false) / remove / replace / dimensions(初始化)
+   * 之外的真正"离散提交"才入栈。
+   */
   const onNodesChange = useCallback(
     (changes: NodeChange[]) => {
+      const shouldCommit = changes.some((c) => {
+        if (c.type === 'remove') return true;
+        // position：仅在拖拽结束（dragging 字段缺省或为 false 时）打点
+        if (c.type === 'position' && c.dragging === false) return true;
+        return false;
+      });
+      if (shouldCommit) commitHistory();
       setNodes(applyNodeChanges(changes, nodes) as typeof nodes);
     },
-    [nodes, setNodes],
+    [nodes, setNodes, commitHistory],
   );
 
   const onEdgesChange = useCallback(
     (changes: EdgeChange[]) => {
+      const shouldCommit = changes.some(
+        (c) => c.type === 'remove' || c.type === 'add',
+      );
+      if (shouldCommit) commitHistory();
       setEdges(applyEdgeChanges(changes, edges));
     },
-    [edges, setEdges],
+    [edges, setEdges, commitHistory],
   );
 
   const onConnect = useCallback(
     (conn: Connection) => {
+      commitHistory();
       setEdges(addEdge({ ...conn, type: 'sequential' }, edges));
     },
-    [edges, setEdges],
+    [edges, setEdges, commitHistory],
   );
 
   const onNodeClick = useCallback(

package/src/canvas/nodes/LoopNode.tsx

@@ -14,7 +14,7 @@ export function LoopNode(props: NodeProps) {
       title="🔁 loop"
       body={summary}
       outputs={[
-        { id: 'iter', label: 'iter' },
+        { id: 'do', label: 'do' },
         { id: 'done', label: 'done' },
       ]}
     />

package/src/inspector/Inspector.tsx

@@ -192,7 +192,7 @@ function BranchForm({ step, onPatch }: FieldProps) {
         placeholder="${flag}"
       />
       <small style={{ color: '#6b7280', fontSize: 11 }}>
-        then / else 子步骤在 yaml 视图里编辑
+        从节点的 then / else 端口拉连线到子步骤节点
       </small>
     </div>
   );
@@ -217,7 +217,7 @@ function LoopForm({ step, onPatch }: FieldProps) {
         />
       </div>
       <small style={{ color: '#6b7280', fontSize: 11 }}>
-        do 子步骤在 yaml 视图里编辑
+        从节点的 do 端口拉连线到子步骤节点
       </small>
     </>
   );

package/src/inspector/ToolNodeForm.tsx

@@ -1,6 +1,12 @@
-import { useMemo } from 'react';
+import { useMemo, useState, useEffect } from 'react';
 import { useManifestStore } from '../store/manifestStore.ts';
-import type { StepDef, ToolMeta } from '../types.ts';
+import type { StepDef } from '../types.ts';
+import {
+  parseSchema,
+  coerceNumberInput,
+  tryParseJson,
+  type FieldDescriptor,
+} from './schemaForm.ts';
 
 interface Props {
   step: StepDef;
@@ -14,26 +20,25 @@ export function ToolNodeForm({ step, onPatch }: Props) {
     () => tools.find((t) => t.name === step.tool),
     [tools, step.tool],
   );
+  const fields = useMemo<FieldDescriptor[]>(
+    () => (currentTool ? parseSchema(currentTool.parameters) : []),
+    [currentTool],
+  );
 
-  const argsText = useMemo(() => {
-    try {
-      return JSON.stringify(step.args ?? {}, null, 2);
-    } catch {
-      return '{}';
-    }
-  }, [step.args]);
-
-  const onArgsChange = (text: string) => {
-    try {
-      const parsed = JSON.parse(text);
-      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-        onPatch({ args: parsed as Record<string, unknown> });
-      }
-    } catch {
-      /* 静默忽略中间态 */
-    }
+  const args = step.args ?? {};
+  const patchArg = (name: string, value: unknown) => {
+    const next = { ...args };
+    if (value === undefined) delete next[name];
+    else next[name] = value;
+    onPatch({ args: next });
   };
 
+  // 已声明字段的 name 集合，用于"高级 / 未知字段"展示
+  const knownNames = useMemo(() => new Set(fields.map((f) => f.name)), [fields]);
+  const unknownEntries = Object.entries(args).filter(
+    ([k]) => !knownNames.has(k),
+  );
+
   return (
     <>
       <div className="field">
@@ -56,65 +61,343 @@ export function ToolNodeForm({ step, onPatch }: Props) {
         )}
       </div>
 
-      {currentTool && <ParamHints tool={currentTool} />}
+      {currentTool && fields.length === 0 && (
+        <div className="field">
+          <small style={{ color: '#6b7280', fontSize: 11 }}>
+            （该工具未声明 parameters.properties，使用下方原始 JSON 编辑）
+          </small>
+          <RawArgsTextarea
+            value={args}
+            onChange={(next) => onPatch({ args: next })}
+          />
+        </div>
+      )}
 
-      <div className="field">
-        <label>args（JSON）</label>
-        <textarea
-          value={argsText}
-          rows={6}
-          spellCheck={false}
-          onChange={(e) => onArgsChange(e.target.value)}
-          style={{ fontFamily: 'ui-monospace, monospace', fontSize: 12 }}
+      {fields.map((f) => (
+        <FieldRenderer
+          key={f.name}
+          field={f}
+          value={args[f.name]}
+          onChange={(v) => patchArg(f.name, v)}
+        />
+      ))}
+
+      {unknownEntries.length > 0 && (
+        <AdvancedSection
+          entries={unknownEntries}
+          onPatchUnknown={(nextUnknown) => {
+            // 用已知字段的当前值 + 新的未知字段拼回 args
+            const known: Record<string, unknown> = {};
+            for (const f of fields) {
+              if (f.name in args) known[f.name] = args[f.name];
+            }
+            onPatch({ args: { ...known, ...nextUnknown } });
+          }}
         />
+      )}
+    </>
+  );
+}
+
+interface FieldRendererProps {
+  field: FieldDescriptor;
+  value: unknown;
+  onChange: (v: unknown) => void;
+}
+
+function FieldRenderer({ field, value, onChange }: FieldRendererProps) {
+  const isEmpty =
+    value === undefined ||
+    value === null ||
+    (typeof value === 'string' && value === '');
+  const invalidRequired = field.required && isEmpty;
+
+  return (
+    <div className="field">
+      <label>
+        {field.name}
+        {field.required && <span style={{ color: '#dc2626' }}> *</span>}
+        <span style={{ color: '#9ca3af', fontWeight: 'normal' }}>
+          {' '}
+          ({field.kind})
+        </span>
+      </label>
+      {renderControl(field, value, onChange, invalidRequired)}
+      {field.description && (
         <small style={{ color: '#6b7280', fontSize: 11 }}>
-          支持 ${'{var}'} 模板引用前序 capture 变量
+          {field.description}
         </small>
-      </div>
+      )}
+    </div>
+  );
+}
+
+function renderControl(
+  field: FieldDescriptor,
+  value: unknown,
+  onChange: (v: unknown) => void,
+  invalid: boolean,
+) {
+  const errStyle = invalid ? { borderColor: '#dc2626' } : undefined;
+
+  if (field.kind === 'enum') {
+    return (
+      <select
+        value={typeof value === 'string' ? value : ''}
+        onChange={(e) => onChange(e.target.value || undefined)}
+        style={errStyle}
+      >
+        <option value="">— 选择 —</option>
+        {field.enumValues?.map((v) => (
+          <option key={v} value={v}>
+            {v}
+          </option>
+        ))}
+      </select>
+    );
+  }
+
+  if (field.kind === 'boolean') {
+    return (
+      <input
+        type="checkbox"
+        checked={value === true}
+        onChange={(e) => onChange(e.target.checked)}
+      />
+    );
+  }
+
+  if (field.kind === 'number') {
+    // 受控字符串：number 表示为字符串以保留模板变量、半截输入
+    const text =
+      value === undefined || value === null
+        ? ''
+        : typeof value === 'string'
+          ? value
+          : String(value);
+    return (
+      <input
+        type="text"
+        inputMode="decimal"
+        value={text}
+        placeholder="数字 或 ${var}"
+        onChange={(e) => onChange(coerceNumberInput(e.target.value))}
+        style={{
+          fontFamily: 'ui-monospace, monospace',
+          fontSize: 12,
+          ...errStyle,
+        }}
+      />
+    );
+  }
+
+  if (field.kind === 'string') {
+    return (
+      <input
+        type="text"
+        value={typeof value === 'string' ? value : ''}
+        onChange={(e) => onChange(e.target.value === '' ? undefined : e.target.value)}
+        style={errStyle}
+      />
+    );
+  }
+
+  // kind === 'json' —— fallback 单字段 JSON textarea + onBlur 校验
+  return <JsonFieldTextarea value={value} onChange={onChange} invalid={invalid} />;
+}
+
+interface JsonFieldProps {
+  value: unknown;
+  onChange: (v: unknown) => void;
+  invalid?: boolean;
+}
+
+function JsonFieldTextarea({ value, onChange, invalid }: JsonFieldProps) {
+  const initial = useMemo(() => {
+    if (value === undefined) return '';
+    try {
+      return JSON.stringify(value, null, 2);
+    } catch {
+      return '';
+    }
+  }, [value]);
+  const [text, setText] = useState(initial);
+  const [error, setError] = useState<string | null>(null);
+
+  // 外部 value 变化（如切换 step）时同步 textarea
+  useEffect(() => {
+    setText(initial);
+    setError(null);
+  }, [initial]);
+
+  const onBlur = () => {
+    const r = tryParseJson(text);
+    if (r.ok) {
+      setError(null);
+      onChange(r.value);
+    } else {
+      setError(r.error);
+    }
+  };
+
+  const borderColor = error || invalid ? '#dc2626' : undefined;
+
+  return (
+    <>
+      <textarea
+        value={text}
+        rows={4}
+        spellCheck={false}
+        onChange={(e) => setText(e.target.value)}
+        onBlur={onBlur}
+        style={{
+          fontFamily: 'ui-monospace, monospace',
+          fontSize: 12,
+          borderColor,
+        }}
+      />
+      {error && (
+        <small style={{ color: '#dc2626', fontSize: 11 }}>
+          ⚠ JSON 格式错误: {error}
+        </small>
+      )}
     </>
   );
 }
 
-function ParamHints({ tool }: { tool: ToolMeta }) {
-  const params = tool.parameters;
-  const props =
-    params && typeof params === 'object'
-      ? ((params as Record<string, unknown>).properties as
-          | Record<string, unknown>
-          | undefined)
-      : undefined;
-  if (!props || typeof props !== 'object') return null;
-  const required =
-    (params as { required?: string[] }).required ?? [];
-  const entries = Object.entries(props);
-  if (entries.length === 0) return null;
+interface RawArgsProps {
+  value: Record<string, unknown>;
+  onChange: (next: Record<string, unknown>) => void;
+}
+
+/** tool 未声明 properties 时的完整 args JSON 编辑器 */
+function RawArgsTextarea({ value, onChange }: RawArgsProps) {
+  const initial = useMemo(() => {
+    try {
+      return JSON.stringify(value ?? {}, null, 2);
+    } catch {
+      return '{}';
+    }
+  }, [value]);
+  const [text, setText] = useState(initial);
+  const [error, setError] = useState<string | null>(null);
+  useEffect(() => {
+    setText(initial);
+    setError(null);
+  }, [initial]);
+
+  const onBlur = () => {
+    const r = tryParseJson(text);
+    if (!r.ok) {
+      setError(r.error);
+      return;
+    }
+    if (r.value === undefined) {
+      setError(null);
+      onChange({});
+      return;
+    }
+    if (typeof r.value !== 'object' || r.value === null || Array.isArray(r.value)) {
+      setError('args 必须是 object（{...}）');
+      return;
+    }
+    setError(null);
+    onChange(r.value as Record<string, unknown>);
+  };
+
   return (
-    <div
-      style={{
-        background: '#f9fafb',
-        border: '1px solid #e5e7eb',
-        borderRadius: 3,
-        padding: 6,
-        fontSize: 11,
-        marginBottom: 8,
-      }}
-    >
-      <div style={{ fontWeight: 600, marginBottom: 4 }}>参数提示</div>
-      {entries.map(([k, v]) => {
-        const desc = (v as { description?: string }).description ?? '';
-        const type = (v as { type?: string }).type ?? 'any';
-        const isReq = required.includes(k);
-        return (
-          <div key={k} style={{ marginBottom: 2 }}>
-            <code>{k}</code>
-            <span style={{ color: '#6b7280' }}>
-              {' '}
-              ({type}){isReq ? ' *' : ''}
-            </span>
-            {desc && <span style={{ color: '#6b7280' }}> — {desc}</span>}
-          </div>
-        );
-      })}
+    <>
+      <textarea
+        value={text}
+        rows={6}
+        spellCheck={false}
+        onChange={(e) => setText(e.target.value)}
+        onBlur={onBlur}
+        style={{
+          fontFamily: 'ui-monospace, monospace',
+          fontSize: 12,
+          borderColor: error ? '#dc2626' : undefined,
+        }}
+      />
+      {error && (
+        <small style={{ color: '#dc2626', fontSize: 11 }}>
+          ⚠ JSON 格式错误: {error}
+        </small>
+      )}
+    </>
+  );
+}
+
+interface AdvancedProps {
+  entries: [string, unknown][];
+  onPatchUnknown: (next: Record<string, unknown>) => void;
+}
+
+/** 折叠区域：展示 manifest 不声明、但用户已写在 yaml 里的字段，避免切 tool 时静默丢失 */
+function AdvancedSection({ entries, onPatchUnknown }: AdvancedProps) {
+  const [open, setOpen] = useState(false);
+  const raw = useMemo(() => {
+    try {
+      return JSON.stringify(Object.fromEntries(entries), null, 2);
+    } catch {
+      return '{}';
+    }
+  }, [entries]);
+  const [text, setText] = useState(raw);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setText(raw);
+    setError(null);
+  }, [raw]);
+
+  const onBlur = () => {
+    const r = tryParseJson(text);
+    if (!r.ok) {
+      setError(r.error);
+      return;
+    }
+    const val = r.value ?? {};
+    if (typeof val !== 'object' || val === null || Array.isArray(val)) {
+      setError('必须是 object（{...}）');
+      return;
+    }
+    setError(null);
+    onPatchUnknown(val as Record<string, unknown>);
+  };
+
+  return (
+    <div className="field">
+      <label
+        style={{ cursor: 'pointer', userSelect: 'none' }}
+        onClick={() => setOpen(!open)}
+      >
+        {open ? '▼' : '▶'} 高级 / 未声明字段（{entries.length}）
+      </label>
+      {open && (
+        <>
+          <textarea
+            value={text}
+            rows={4}
+            spellCheck={false}
+            onChange={(e) => setText(e.target.value)}
+            onBlur={onBlur}
+            style={{
+              fontFamily: 'ui-monospace, monospace',
+              fontSize: 12,
+              borderColor: error ? '#dc2626' : undefined,
+            }}
+          />
+          {error && (
+            <small style={{ color: '#dc2626', fontSize: 11 }}>
+              ⚠ JSON 格式错误: {error}
+            </small>
+          )}
+          <small style={{ color: '#6b7280', fontSize: 11 }}>
+            当前 tool 的 manifest 未声明的字段；onBlur 时校验并写回 args
+          </small>
+        </>
+      )}
     </div>
   );
 }

package/src/inspector/schemaForm.ts

@@ -0,0 +1,107 @@
+/**
+ * editor/src/inspector/schemaForm.ts —— JSON Schema → 表单字段描述符的纯函数转换。
+ *
+ * 抽离自 ToolNodeForm.tsx，便于纯函数测试（不依赖 React）。
+ * 输入：tool.parameters（JSON Schema 形如 { type: 'object', properties: {...}, required: [...] }）
+ * 输出：FieldDescriptor[] —— UI 层据此渲染 input / select / checkbox / textarea
+ */
+
+export type FieldKind =
+  | 'string'
+  | 'enum'
+  | 'number'
+  | 'boolean'
+  | 'json'; // fallback：array / object / 未知
+
+export interface FieldDescriptor {
+  /** properties 里的 key */
+  name: string;
+  /** 字段控件类型 */
+  kind: FieldKind;
+  /** required 列表是否包含此字段 */
+  required: boolean;
+  /** 字段描述，渲染到 small */
+  description: string;
+  /** kind === 'enum' 时的选项 */
+  enumValues?: string[];
+  /** 原始 schema 节点，留给高级用途（默认值等） */
+  raw: Record<string, unknown>;
+}
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function isStringArray(v: unknown): v is string[] {
+  return Array.isArray(v) && v.every((x) => typeof x === 'string');
+}
+
+/**
+ * 解析 JSON Schema 顶层 properties，返回字段描述数组。
+ * 不识别的 schema 形态返回空数组（caller 退回到原 JSON 编辑模式）。
+ */
+export function parseSchema(parameters: unknown): FieldDescriptor[] {
+  if (!isPlainObject(parameters)) return [];
+  const props = parameters.properties;
+  if (!isPlainObject(props)) return [];
+  const requiredRaw = parameters.required;
+  const required = isStringArray(requiredRaw) ? requiredRaw : [];
+
+  const fields: FieldDescriptor[] = [];
+  for (const [name, rawNode] of Object.entries(props)) {
+    if (!isPlainObject(rawNode)) continue;
+    const type = typeof rawNode.type === 'string' ? rawNode.type : 'any';
+    const description =
+      typeof rawNode.description === 'string' ? rawNode.description : '';
+    const enumValuesRaw = rawNode.enum;
+    const enumValues = isStringArray(enumValuesRaw) ? enumValuesRaw : undefined;
+
+    let kind: FieldKind;
+    if (type === 'string' && enumValues) kind = 'enum';
+    else if (type === 'string') kind = 'string';
+    else if (type === 'number' || type === 'integer') kind = 'number';
+    else if (type === 'boolean') kind = 'boolean';
+    else kind = 'json';
+
+    fields.push({
+      name,
+      kind,
+      required: required.includes(name),
+      description,
+      enumValues,
+      raw: rawNode,
+    });
+  }
+  return fields;
+}
+
+/**
+ * number 字段的智能值解析：
+ *  - 空串 → undefined（删除字段）
+ *  - 以 `$` 开头（模板变量 ${var}）→ 原样 string 透传，不 parseFloat
+ *  - 其他 → parseFloat；NaN 时回退为原始 string（用户半截输入）
+ */
+export function coerceNumberInput(raw: string): number | string | undefined {
+  if (raw === '') return undefined;
+  if (raw.startsWith('$')) return raw;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : raw;
+}
+
+/**
+ * 尝试把 JSON textarea 的文本解析为 JS 值。
+ * 失败返回 { ok: false, error }，成功返回 { ok: true, value }。
+ */
+export type JsonParseResult =
+  | { ok: true; value: unknown }
+  | { ok: false; error: string };
+
+export function tryParseJson(text: string): JsonParseResult {
+  const trimmed = text.trim();
+  if (trimmed === '') return { ok: true, value: undefined };
+  try {
+    return { ok: true, value: JSON.parse(trimmed) };
+  } catch (e) {
+    return { ok: false, error: (e as Error).message };
+  }
+}

package/src/store/workflowStore.ts

@@ -1,6 +1,21 @@
 import { create } from 'zustand';
 import type { Edge, Node } from '@xyflow/react';
-import type { CanvasNodeData, StepDef, WorkflowDef } from '../types.ts';
+import type {
+  CanvasNodeData,
+  StepDef,
+  WorkflowDef,
+  WorkflowEdgeMeta,
+} from '../types.ts';
+
+/** Undo/Redo history 快照：只存图模型，不含 UI 态。 */
+interface HistoryEntry {
+  nodes: Node<CanvasNodeData>[];
+  edges: Edge[];
+  meta: Pick<WorkflowDef, 'name' | 'description' | 'version' | 'inputs'>;
+}
+
+/** history 上限，防内存爆炸。 */
+const HISTORY_LIMIT = 100;
 
 interface WorkflowState {
   /** 当前打开的 workflow 文件名 */
@@ -15,17 +30,30 @@ interface WorkflowState {
   selectedNodeId: string | null;
   /** YAML 是否未保存 */
   dirty: boolean;
+  /** Undo 栈（最老的在前） */
+  past: HistoryEntry[];
+  /** Redo 栈（最近 undo 的在末尾） */
+  future: HistoryEntry[];
 
   setCurrentFile: (file: string | null) => void;
   loadWorkflow: (def: WorkflowDef) => void;
-  setNodes: (nodes: Node<CanvasNodeData>[]) => void;
-  setEdges: (edges: Edge[]) => void;
+  setNodes: (
+    nodes: Node<CanvasNodeData>[],
+    options?: { history?: boolean },
+  ) => void;
+  setEdges: (edges: Edge[], options?: { history?: boolean }) => void;
   selectNode: (id: string | null) => void;
   updateStep: (id: string, patch: Partial<StepDef>) => void;
   addStep: (step: StepDef, position: { x: number; y: number }) => void;
   removeStep: (id: string) => void;
   markDirty: (dirty: boolean) => void;
-  /** 生成当前 workflow 完整 def（含 __meta.layout） */
+  /** 显式把当前 nodes/edges/meta 快照入 history（拖拽结束等离散操作调用） */
+  commitHistory: () => void;
+  /** 撤销 */
+  undo: () => void;
+  /** 重做 */
+  redo: () => void;
+  /** 生成当前 workflow 完整 def（含 __meta.layout/edges/warnings） */
   toWorkflowDef: () => WorkflowDef;
 }
 
@@ -36,6 +64,31 @@ const initialMeta = {
   inputs: [],
 };
 
+/** branch/loop 用来挂载子步骤的 sourceHandle id。 */
+const CHILD_HANDLES = new Set(['then', 'else', 'do']);
+
+/**
+ * 在状态突变前把当前快照推入 past，并清空 future。
+ * 用 get()/set() 闭包封装，避免每个 action 复制粘贴。
+ * 不修改 nodes/edges/meta 本身——仅维护 past/future 栈。
+ */
+function pushHistorySnapshot(
+  get: () => WorkflowState,
+  set: (
+    partial:
+      | Partial<WorkflowState>
+      | ((s: WorkflowState) => Partial<WorkflowState>),
+  ) => void,
+): void {
+  const { nodes, edges, meta, past } = get();
+  const entry: HistoryEntry = { nodes, edges, meta };
+  const nextPast =
+    past.length >= HISTORY_LIMIT
+      ? [...past.slice(past.length - HISTORY_LIMIT + 1), entry]
+      : [...past, entry];
+  set({ past: nextPast, future: [] });
+}
+
 export const useWorkflowStore = create<WorkflowState>((set, get) => ({
   currentFile: null,
   meta: initialMeta,
@@ -43,27 +96,114 @@ export const useWorkflowStore = create<WorkflowState>((set, get) => ({
   edges: [],
   selectedNodeId: null,
   dirty: false,
+  past: [],
+  future: [],
 
   setCurrentFile: (file) => set({ currentFile: file }),
 
   loadWorkflow: (def) => {
-    const steps = def.steps ?? [];
     const layout = def.__meta?.layout ?? [];
-    const nodes: Node<CanvasNodeData>[] = steps.map((step, i) => {
-      const pos = layout.find((l) => l.id === step.id);
+    const metaEdges = def.__meta?.edges;
+
+    // 1) 展平所有 step（顶层 + branch.then/else + loop.do），保持父子关系
+    //    并清洗掉 data.step 上残留的 then/else/do 字段（子步骤改由 edges 表达）
+    interface FlatEntry {
+      step: StepDef;
+      childEdges: { handle: 'then' | 'else' | 'do'; targets: string[] }[];
+    }
+    const flat: FlatEntry[] = [];
+
+    const flatten = (steps: StepDef[]): void => {
+      for (const raw of steps) {
+        const { then: thenChildren, else: elseChildren, do: doChildren, ...rest } =
+          raw;
+        const cleaned: StepDef = { ...rest };
+        const childEdges: FlatEntry['childEdges'] = [];
+
+        if (Array.isArray(thenChildren) && thenChildren.length > 0) {
+          childEdges.push({
+            handle: 'then',
+            targets: thenChildren.map((c) => c.id),
+          });
+        }
+        if (Array.isArray(elseChildren) && elseChildren.length > 0) {
+          childEdges.push({
+            handle: 'else',
+            targets: elseChildren.map((c) => c.id),
+          });
+        }
+        if (Array.isArray(doChildren) && doChildren.length > 0) {
+          childEdges.push({
+            handle: 'do',
+            targets: doChildren.map((c) => c.id),
+          });
+        }
+        flat.push({ step: cleaned, childEdges });
+
+        if (thenChildren) flatten(thenChildren);
+        if (elseChildren) flatten(elseChildren);
+        if (doChildren) flatten(doChildren);
+      }
+    };
+    flatten(def.steps ?? []);
+
+    // 2) 生成 nodes
+    const nodes: Node<CanvasNodeData>[] = flat.map((entry, i) => {
+      const pos = layout.find((l) => l.id === entry.step.id);
+      const kind = detectKind(entry.step);
       return {
-        id: step.id,
-        type: detectKind(step),
+        id: entry.step.id,
+        type: kind,
         position: pos ? { x: pos.x, y: pos.y } : { x: 100, y: 80 + i * 120 },
-        data: { step, kind: detectKind(step) },
+        data: { step: entry.step, kind },
       };
     });
-    const edges: Edge[] = nodes.slice(0, -1).map((n, i) => ({
-      id: `seq-${n.id}-${nodes[i + 1].id}`,
-      source: n.id,
-      target: nodes[i + 1].id,
-      type: 'sequential',
-    }));
+
+    // 3) 还原 edges
+    let edges: Edge[];
+    if (Array.isArray(metaEdges) && metaEdges.length > 0) {
+      // 新格式：__meta.edges 是 single source of truth
+      edges = metaEdges.map((e) => buildEdge(e));
+    } else if (flat.some((f) => f.childEdges.length > 0)) {
+      // 旧 YAML 没有 __meta.edges，但有 nested children
+      //   → 重建：父→第一个子步骤（带 sourceHandle），剩余子步骤之间用顺序 edge
+      //   → 顶层 step 之间也按出现顺序串成线性 edge
+      edges = [];
+      for (const { step, childEdges } of flat) {
+        for (const { handle, targets } of childEdges) {
+          if (targets.length === 0) continue;
+          edges.push(
+            buildEdge({
+              source: step.id,
+              target: targets[0],
+              sourceHandle: handle,
+            }),
+          );
+          for (let i = 0; i < targets.length - 1; i++) {
+            edges.push(
+              buildEdge({ source: targets[i], target: targets[i + 1] }),
+            );
+          }
+        }
+      }
+      // 顶层 steps 之间按 def.steps 顺序串线性 edge
+      const topLevelIds = (def.steps ?? []).map((s) => s.id);
+      for (let i = 0; i < topLevelIds.length - 1; i++) {
+        edges.push(
+          buildEdge({ source: topLevelIds[i], target: topLevelIds[i + 1] }),
+        );
+      }
+    } else {
+      // 完全平铺的旧格式：按节点出现顺序串成线性 edge（向后兼容旧脑补逻辑）
+      edges = [];
+      for (let i = 0; i < nodes.length - 1; i++) {
+        edges.push(
+          buildEdge({ source: nodes[i].id, target: nodes[i + 1].id }),
+        );
+      }
+    }
+
+    // loadWorkflow 是 reset 而非 step：清空 history 两端
     set({
       meta: {
         name: def.name,
@@ -75,14 +215,27 @@ export const useWorkflowStore = create<WorkflowState>((set, get) => ({
       edges,
       selectedNodeId: null,
       dirty: false,
+      past: [],
+      future: [],
     });
   },
 
-  setNodes: (nodes) => set({ nodes, dirty: true }),
-  setEdges: (edges) => set({ edges, dirty: true }),
+  /**
+   * 默认 history=false：拖拽期间高频 setNodes 不打点，
+   * 由 WorkflowCanvas 在拖拽结束/节点增删时显式调 commitHistory()。
+   */
+  setNodes: (nodes, options) => {
+    if (options?.history) pushHistorySnapshot(get, set);
+    set({ nodes, dirty: true });
+  },
+  setEdges: (edges, options) => {
+    if (options?.history) pushHistorySnapshot(get, set);
+    set({ edges, dirty: true });
+  },
   selectNode: (id) => set({ selectedNodeId: id }),
 
   updateStep: (id, patch) => {
+    pushHistorySnapshot(get, set);
     const nodes = get().nodes.map((n) =>
       n.id === id
         ? { ...n, data: { ...n.data, step: { ...n.data.step, ...patch } } }
@@ -92,17 +245,25 @@ export const useWorkflowStore = create<WorkflowState>((set, get) => ({
   },
 
   addStep: (step, position) => {
+    pushHistorySnapshot(get, set);
+    // 子步骤归属由 edges 决定，store 内部的 step 不能再带 nested then/else/do
+    const { then: _t, else: _e, do: _d, ...clean } = step;
+    void _t;
+    void _e;
+    void _d;
+    const kind = detectKind(clean);
     const node: Node<CanvasNodeData> = {
-      id: step.id,
-      type: detectKind(step),
+      id: clean.id,
+      type: kind,
       position,
-      data: { step, kind: detectKind(step) },
+      data: { step: clean, kind },
     };
     const nodes = [...get().nodes, node];
     set({ nodes, dirty: true });
   },
 
   removeStep: (id) => {
+    pushHistorySnapshot(get, set);
     const nodes = get().nodes.filter((n) => n.id !== id);
     const edges = get()
       .edges.filter((e) => e.source !== id && e.target !== id);
@@ -111,23 +272,48 @@ export const useWorkflowStore = create<WorkflowState>((set, get) => ({
 
   markDirty: (dirty) => set({ dirty }),
 
+  commitHistory: () => {
+    pushHistorySnapshot(get, set);
+  },
+
+  undo: () => {
+    const { past, future, nodes, edges, meta } = get();
+    if (past.length === 0) return;
+    const previous = past[past.length - 1];
+    const nextPast = past.slice(0, past.length - 1);
+    const currentSnapshot: HistoryEntry = { nodes, edges, meta };
+    set({
+      past: nextPast,
+      future: [...future, currentSnapshot],
+      nodes: previous.nodes,
+      edges: previous.edges,
+      meta: previous.meta,
+      selectedNodeId: null,
+      dirty: true,
+    });
+  },
+
+  redo: () => {
+    const { past, future, nodes, edges, meta } = get();
+    if (future.length === 0) return;
+    const next = future[future.length - 1];
+    const nextFuture = future.slice(0, future.length - 1);
+    const currentSnapshot: HistoryEntry = { nodes, edges, meta };
+    set({
+      past: [...past, currentSnapshot],
+      future: nextFuture,
+      nodes: next.nodes,
+      edges: next.edges,
+      meta: next.meta,
+      selectedNodeId: null,
+      dirty: true,
+    });
+  },
+
   toWorkflowDef: () => {
-    const { meta, nodes } = get();
-    const ordered = [...nodes].sort(
-      (a, b) => a.position.y - b.position.y || a.position.x - b.position.x,
-    );
-    return {
-      ...meta,
-      name: meta.name || 'untitled',
-      steps: ordered.map((n) => n.data.step),
-      __meta: {
-        layout: ordered.map((n) => ({
-          id: n.id,
-          x: Math.round(n.position.x),
-          y: Math.round(n.position.y),
-        })),
-      },
-    };
+    const { meta, nodes, edges } = get();
+    const result = assembleWorkflow(meta, nodes, edges);
+    return result;
   },
 }));
 
@@ -138,3 +324,203 @@ function detectKind(step: StepDef): string {
   if (step.llm) return 'llm';
   return 'assert';
 }
+
+/** 把 store 内部 edge 形状压扁为 __meta.edges 形状。 */
+function edgeToMeta(e: Edge): WorkflowEdgeMeta {
+  const m: WorkflowEdgeMeta = { source: e.source, target: e.target };
+  if (e.sourceHandle) m.sourceHandle = e.sourceHandle;
+  return m;
+}
+
+/** 由 meta edge 构造 React Flow Edge。 */
+function buildEdge(m: WorkflowEdgeMeta): Edge {
+  const handleSuffix = m.sourceHandle ? `-${m.sourceHandle}` : '';
+  return {
+    id: `e-${m.source}${handleSuffix}-${m.target}`,
+    source: m.source,
+    target: m.target,
+    sourceHandle: m.sourceHandle,
+    type: 'sequential',
+  };
+}
+
+/**
+ * 拓扑组装：依据 edges 把 nodes 还原成 nested WorkflowDef。
+ *
+ * 算法：
+ *   1) 拆分 edges → childEdges（sourceHandle ∈ {then/else/do}）+ siblingEdges（其余）
+ *   2) 对每个 branch/loop 节点，沿 child handle 出发，再顺着 siblingEdges 链下去
+ *      构成 then[]/else[]/do[] 子步骤；子步骤集合从顶层候选里扣掉
+ *   3) 顶层 steps：roots（没被 siblingEdges 指向，也不是子步骤）出发拓扑 BFS
+ *   4) 成环：把剩余未访问节点按 Y 坐标 fallback，并写入 __meta.warnings
+ *   5) 孤儿（无入无出 + 未被分配）按 Y 坐标追加到顶层
+ */
+function assembleWorkflow(
+  meta: Pick<WorkflowDef, 'name' | 'description' | 'version' | 'inputs'>,
+  nodes: Node<CanvasNodeData>[],
+  edges: Edge[],
+): WorkflowDef {
+  const warnings: string[] = [];
+  const nodeById = new Map(nodes.map((n) => [n.id, n]));
+
+  // childAdj[nodeId][handle] = [targetId, ...] （来自 sourceHandle 是 then/else/do 的 edge）
+  const childAdj = new Map<string, Map<string, string[]>>();
+  // siblingAdj[nodeId] = [targetId, ...] （来自 sourceHandle 为空/done/其它的 edge）
+  const siblingAdj = new Map<string, string[]>();
+  // siblingInDeg：被 siblingEdges 指向的次数（用于找根）
+  const siblingInDeg = new Map<string, number>();
+  for (const n of nodes) siblingInDeg.set(n.id, 0);
+
+  for (const e of edges) {
+    if (!nodeById.has(e.source) || !nodeById.has(e.target)) continue;
+    if (e.sourceHandle && CHILD_HANDLES.has(e.sourceHandle)) {
+      let m = childAdj.get(e.source);
+      if (!m) {
+        m = new Map();
+        childAdj.set(e.source, m);
+      }
+      const arr = m.get(e.sourceHandle) ?? [];
+      if (!arr.includes(e.target)) arr.push(e.target);
+      m.set(e.sourceHandle, arr);
+    } else {
+      const arr = siblingAdj.get(e.source) ?? [];
+      if (!arr.includes(e.target)) arr.push(e.target);
+      siblingAdj.set(e.source, arr);
+      siblingInDeg.set(e.target, (siblingInDeg.get(e.target) ?? 0) + 1);
+    }
+  }
+
+  // 给同一节点的多条 sibling 出边按目标 Y 坐标稳定排序（提升拓扑确定性）
+  for (const [src, arr] of siblingAdj) {
+    arr.sort((a, b) => {
+      const ay = nodeById.get(a)?.position.y ?? 0;
+      const by = nodeById.get(b)?.position.y ?? 0;
+      return ay - by;
+    });
+    siblingAdj.set(src, arr);
+  }
+
+  // 沿 siblingAdj 从起点收集一条线性链（DFS，遇到已访问/无出边/分歧只走第一支）
+  // 返回的链是 visited（in-place 标记） + 链上节点 id 列表
+  const collectChain = (
+    startId: string,
+    claimed: Set<string>,
+    visiting: Set<string>,
+  ): string[] => {
+    const chain: string[] = [];
+    let cur: string | undefined = startId;
+    while (cur !== undefined && !claimed.has(cur) && !visiting.has(cur)) {
+      visiting.add(cur);
+      claimed.add(cur);
+      chain.push(cur);
+      const nexts = siblingAdj.get(cur) ?? [];
+      // 链只走第一个 sibling 后继（DAG 上的"线性"分支）
+      cur = nexts[0];
+    }
+    return chain;
+  };
+
+  // 第一遍：找到所有 branch/loop 节点的子步骤集合，登记到 claimed
+  const claimed = new Set<string>();
+  // childMap：每个 branch/loop 节点的 then/else/do 已抽出的子 step
+  const childMap = new Map<
+    string,
+    { then?: StepDef[]; else?: StepDef[]; do?: StepDef[] }
+  >();
+
+  for (const node of nodes) {
+    const kind = node.data.kind;
+    if (kind !== 'branch' && kind !== 'loop') continue;
+    const handles = childAdj.get(node.id);
+    if (!handles) continue;
+    const entry: { then?: StepDef[]; else?: StepDef[]; do?: StepDef[] } = {};
+    for (const [handle, targets] of handles) {
+      // 每个 target 拉一条链
+      const collected: StepDef[] = [];
+      const localVisiting = new Set<string>();
+      for (const t of targets) {
+        const chain = collectChain(t, claimed, localVisiting);
+        for (const id of chain) {
+          const n = nodeById.get(id);
+          if (n) collected.push(n.data.step);
+        }
+      }
+      if (collected.length > 0) {
+        if (handle === 'then') entry.then = collected;
+        else if (handle === 'else') entry.else = collected;
+        else if (handle === 'do') entry.do = collected;
+      }
+    }
+    childMap.set(node.id, entry);
+  }
+
+  // 第二遍：顶层 steps —— roots = 未 claimed 且 siblingInDeg === 0 的节点
+  const topLevel: StepDef[] = [];
+  const visited = new Set<string>(claimed);
+
+  const roots = nodes
+    .filter((n) => !claimed.has(n.id) && (siblingInDeg.get(n.id) ?? 0) === 0)
+    .sort((a, b) => a.position.y - b.position.y || a.position.x - b.position.x);
+
+  // Kahn BFS：从 roots 出发，按 siblingAdj 拓扑访问；遇到已访问跳过
+  const queue: string[] = roots.map((n) => n.id);
+  while (queue.length > 0) {
+    const id = queue.shift()!;
+    if (visited.has(id)) continue;
+    visited.add(id);
+    const node = nodeById.get(id);
+    if (!node) continue;
+    const stepWithChildren = withChildren(node.data.step, childMap.get(id));
+    topLevel.push(stepWithChildren);
+    for (const next of siblingAdj.get(id) ?? []) {
+      if (!visited.has(next)) queue.push(next);
+    }
+  }
+
+  // 剩余未访问的节点 —— 要么在环里，要么是被 sibling 指向但无人能到达（孤立环 + 孤儿）
+  const leftover = nodes
+    .filter((n) => !visited.has(n.id))
+    .sort((a, b) => a.position.y - b.position.y || a.position.x - b.position.x);
+
+  if (leftover.length > 0) {
+    // 区分：是否真在环里 —— 若节点 siblingInDeg > 0 且没被访问，可能是环
+    const inCycle = leftover.some((n) => (siblingInDeg.get(n.id) ?? 0) > 0);
+    if (inCycle) {
+      warnings.push(
+        `cycle detected: ${leftover.map((n) => n.id).join(' -> ')}`,
+      );
+    }
+    for (const n of leftover) {
+      visited.add(n.id);
+      topLevel.push(withChildren(n.data.step, childMap.get(n.id)));
+    }
+  }
+
+  const def: WorkflowDef = {
+    ...meta,
+    name: meta.name || 'untitled',
+    steps: topLevel,
+    __meta: {
+      layout: nodes.map((n) => ({
+        id: n.id,
+        x: Math.round(n.position.x),
+        y: Math.round(n.position.y),
+      })),
+      edges: edges.map(edgeToMeta),
+    },
+  };
+  if (warnings.length > 0) def.__meta!.warnings = warnings;
+  return def;
+}
+
+function withChildren(
+  step: StepDef,
+  children: { then?: StepDef[]; else?: StepDef[]; do?: StepDef[] } | undefined,
+): StepDef {
+  if (!children) return step;
+  const out: StepDef = { ...step };
+  if (children.then) out.then = children.then;
+  if (children.else) out.else = children.else;
+  if (children.do) out.do = children.do;
+  return out;
+}

package/src/types.ts

@@ -41,6 +41,12 @@ export interface StepDef {
   maxTurns?: number;
 }
 
+export interface WorkflowEdgeMeta {
+  source: string;
+  target: string;
+  sourceHandle?: string;
+}
+
 export interface WorkflowDef {
   name: string;
   description?: string;
@@ -49,6 +55,13 @@ export interface WorkflowDef {
   steps: StepDef[];
   __meta?: {
     layout?: { id: string; x: number; y: number }[];
+    /**
+     * 画布原始连线，保存时序列化、加载时还原。runner 严格忽略 __meta，
+     * 因此追加这两个字段不会破坏运行时。
+     */
+    edges?: WorkflowEdgeMeta[];
+    /** toWorkflowDef 期间检测到的结构问题（如成环）。 */
+    warnings?: string[];
   };
 }