minimal-workflow 0.4.5 → 0.5.0

package/package.json

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

package/src/canvas/WorkflowCanvas.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useMemo } from 'react';
+import { useCallback, useEffect, useMemo } from 'react';
 import {
   ReactFlow,
   Background,
@@ -14,6 +14,7 @@ import {
 import '@xyflow/react/dist/style.css';
 
 import { useWorkflowStore } from '../store/workflowStore.ts';
+import { validateWorkflowByNode } from '../yaml-view/sync.ts';
 import { ToolNode } from './nodes/ToolNode.tsx';
 import { LlmNode } from './nodes/LlmNode.tsx';
 import { SkillNode } from './nodes/SkillNode.tsx';
@@ -50,6 +51,8 @@ export function WorkflowCanvas() {
   const selectNode = useWorkflowStore((s) => s.selectNode);
   const addStep = useWorkflowStore((s) => s.addStep);
   const commitHistory = useWorkflowStore((s) => s.commitHistory);
+  const toWorkflowDef = useWorkflowStore((s) => s.toWorkflowDef);
+  const setNodeErrors = useWorkflowStore((s) => s.setNodeErrors);
 
   /**
    * change-aware history：拖拽过程中 (position && dragging===true) 高频 emit，
@@ -128,6 +131,16 @@ export function WorkflowCanvas() {
     [nodes, addStep],
   );
 
+  /**
+   * 节点级错误接线：nodes/edges 变化 → 组装 def → 逐节点结构校验 →
+   * 把错误写回各 node.data.errors（BaseNode 渲染"N 错误"badge）。
+   * setNodeErrors 内部幂等（errors 无变化不 set），故不会死循环。
+   */
+  useEffect(() => {
+    const def = toWorkflowDef();
+    setNodeErrors(validateWorkflowByNode(def));
+  }, [nodes, edges, toWorkflowDef, setNodeErrors]);
+
   const defaultViewport = useMemo(() => ({ x: 0, y: 0, zoom: 1 }), []);
 
   return (

package/src/inspector/InputsPanel.tsx

@@ -0,0 +1,335 @@
+/**
+ * editor/src/inspector/InputsPanel.tsx —— workflow 级属性编辑面板。
+ *
+ * 在未选中任何节点时渲染（Inspector 空态），编辑 workflow 对外契约：
+ *   - 元信息：name / description / version
+ *   - inputs[]：每项 name / type(string|number|enum) / required / default / description；
+ *     type==='enum' 时额外编辑 values[]（候选值，必须非空，否则后端 loader 拒绝）。
+ *
+ * 所有改动统一走 store 的 updateMeta({...})（进 undo history + 置 dirty），
+ * 不直接 mutate meta。inputs 的增/删/改逻辑抽成纯函数（见下方 reducer 段），
+ * 既复用于组件、又可被 test/inputsPanel.test.ts 单测（editor 无 @testing-library/react）。
+ *
+ * D2 红线：本文件**禁止** import minimal-agent/src/* 或 plugins/*，只依赖 editor 自有类型与 store。
+ */
+
+import { useWorkflowStore } from '../store/workflowStore.ts';
+import type { WorkflowInput } from '../types.ts';
+
+/* ───────────────────────── 纯函数 reducer（可单测） ───────────────────────── */
+
+export type InputType = NonNullable<WorkflowInput['type']>;
+
+/** 追加一个新 input（默认 string、非必填）。 */
+export function addInput(inputs: WorkflowInput[]): WorkflowInput[] {
+  return [...inputs, { name: '', type: 'string' }];
+}
+
+/** 删除第 idx 个 input。 */
+export function removeInput(
+  inputs: WorkflowInput[],
+  idx: number,
+): WorkflowInput[] {
+  return inputs.filter((_, i) => i !== idx);
+}
+
+/**
+ * 局部 patch 第 idx 个 input。
+ * 当把 type 切到非 enum 时，顺手清掉残留的 values（避免 yaml 里留下无意义的候选值）；
+ * 切到 enum 时如果还没有 values 则补一个空数组（引导用户去填）。
+ */
+export function patchInput(
+  inputs: WorkflowInput[],
+  idx: number,
+  patch: Partial<WorkflowInput>,
+): WorkflowInput[] {
+  return inputs.map((inp, i) => {
+    if (i !== idx) return inp;
+    const next: WorkflowInput = { ...inp, ...patch };
+    if (patch.type !== undefined) {
+      if (patch.type === 'enum') {
+        if (!Array.isArray(next.values)) next.values = [];
+      } else if (next.values !== undefined) {
+        delete next.values;
+      }
+    }
+    return next;
+  });
+}
+
+/** 给第 idx 个 enum input 追加一个空候选值。 */
+export function addEnumValue(
+  inputs: WorkflowInput[],
+  idx: number,
+): WorkflowInput[] {
+  return inputs.map((inp, i) =>
+    i === idx ? { ...inp, values: [...(inp.values ?? []), ''] } : inp,
+  );
+}
+
+/** 修改第 idx 个 enum input 的第 vIdx 个候选值。 */
+export function setEnumValue(
+  inputs: WorkflowInput[],
+  idx: number,
+  vIdx: number,
+  value: string,
+): WorkflowInput[] {
+  return inputs.map((inp, i) => {
+    if (i !== idx) return inp;
+    const values = (inp.values ?? []).map((v, j) => (j === vIdx ? value : v));
+    return { ...inp, values };
+  });
+}
+
+/** 删除第 idx 个 enum input 的第 vIdx 个候选值。 */
+export function removeEnumValue(
+  inputs: WorkflowInput[],
+  idx: number,
+  vIdx: number,
+): WorkflowInput[] {
+  return inputs.map((inp, i) => {
+    if (i !== idx) return inp;
+    const values = (inp.values ?? []).filter((_, j) => j !== vIdx);
+    return { ...inp, values };
+  });
+}
+
+/* ───────────────────────────── React 组件 ───────────────────────────── */
+
+const SMALL: React.CSSProperties = { color: '#6b7280', fontSize: 11 };
+const WARN: React.CSSProperties = { color: '#dc2626', fontSize: 11 };
+
+export function InputsPanel() {
+  const meta = useWorkflowStore((s) => s.meta);
+  const updateMeta = useWorkflowStore((s) => s.updateMeta);
+
+  const inputs = meta.inputs ?? [];
+  const writeInputs = (next: WorkflowInput[]) => updateMeta({ inputs: next });
+
+  return (
+    <aside className="inspector">
+      <h2>workflow 属性</h2>
+
+      {/* ── 元信息 ── */}
+      <div className="field">
+        <label>name（workflow 名）</label>
+        <input
+          value={meta.name ?? ''}
+          placeholder="untitled"
+          onChange={(e) => updateMeta({ name: e.target.value })}
+        />
+      </div>
+      <div className="field">
+        <label>description（说明）</label>
+        <textarea
+          value={meta.description ?? ''}
+          rows={2}
+          onChange={(e) => updateMeta({ description: e.target.value })}
+        />
+      </div>
+      <div className="field">
+        <label>version</label>
+        <input
+          value={meta.version ?? ''}
+          placeholder="0.1"
+          onChange={(e) => updateMeta({ version: e.target.value })}
+        />
+      </div>
+
+      {/* ── inputs 列表 ── */}
+      <div className="field" style={{ marginTop: 16 }}>
+        <label>inputs（对外参数契约，{inputs.length} 个）</label>
+        <small style={SMALL}>
+          决定 <code>/workflow &lt;name&gt; [位置参数]</code> 的取值与顺序；
+          重排会破坏现有 CLI 位置参数调用。
+        </small>
+      </div>
+
+      {inputs.map((inp, i) => (
+        <InputRow
+          key={i}
+          input={inp}
+          onPatch={(patch) => writeInputs(patchInput(inputs, i, patch))}
+          onRemove={() => writeInputs(removeInput(inputs, i))}
+          onAddValue={() => writeInputs(addEnumValue(inputs, i))}
+          onSetValue={(vIdx, v) =>
+            writeInputs(setEnumValue(inputs, i, vIdx, v))
+          }
+          onRemoveValue={(vIdx) =>
+            writeInputs(removeEnumValue(inputs, i, vIdx))
+          }
+        />
+      ))}
+
+      <div className="field">
+        <button
+          onClick={() => writeInputs(addInput(inputs))}
+          style={{ fontSize: 11, padding: '2px 8px' }}
+        >
+          + 添加 input
+        </button>
+      </div>
+    </aside>
+  );
+}
+
+interface InputRowProps {
+  input: WorkflowInput;
+  onPatch: (patch: Partial<WorkflowInput>) => void;
+  onRemove: () => void;
+  onAddValue: () => void;
+  onSetValue: (vIdx: number, value: string) => void;
+  onRemoveValue: (vIdx: number) => void;
+}
+
+function InputRow({
+  input,
+  onPatch,
+  onRemove,
+  onAddValue,
+  onSetValue,
+  onRemoveValue,
+}: InputRowProps) {
+  const type: InputType = input.type ?? 'string';
+  const isEnum = type === 'enum';
+  const values = input.values ?? [];
+  const enumEmpty = isEnum && values.filter((v) => v.trim() !== '').length === 0;
+
+  return (
+    <div
+      className="field"
+      style={{
+        border: '1px solid #e5e7eb',
+        borderRadius: 4,
+        padding: 8,
+        marginBottom: 6,
+      }}
+    >
+      <div
+        style={{
+          display: 'flex',
+          gap: 6,
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          marginBottom: 6,
+        }}
+      >
+        <code style={{ fontSize: 12 }}>{input.name || '(未命名)'}</code>
+        <button
+          onClick={onRemove}
+          title="删除该 input"
+          style={{
+            fontSize: 11,
+            padding: '2px 6px',
+            background: '#fef2f2',
+            color: '#dc2626',
+            border: '1px solid #fca5a5',
+            borderRadius: 3,
+          }}
+        >
+          ×
+        </button>
+      </div>
+
+      <div className="field">
+        <label>name</label>
+        <input
+          value={input.name}
+          placeholder="param_name"
+          onChange={(e) => onPatch({ name: e.target.value })}
+        />
+      </div>
+
+      <div className="field">
+        <label>type</label>
+        <select
+          value={type}
+          onChange={(e) => onPatch({ type: e.target.value as InputType })}
+        >
+          <option value="string">string</option>
+          <option value="number">number</option>
+          <option value="enum">enum</option>
+        </select>
+      </div>
+
+      <div className="field">
+        <label style={{ display: 'flex', alignItems: 'center', gap: 6 }}>
+          <input
+            type="checkbox"
+            checked={input.required === true}
+            onChange={(e) => onPatch({ required: e.target.checked })}
+            style={{ width: 'auto' }}
+          />
+          required（必填）
+        </label>
+      </div>
+
+      <div className="field">
+        <label>default（默认值，可选）</label>
+        <input
+          value={defaultToText(input.default)}
+          placeholder={isEnum ? '需为某个候选值' : ''}
+          onChange={(e) =>
+            onPatch({
+              default: e.target.value === '' ? undefined : e.target.value,
+            })
+          }
+        />
+      </div>
+
+      <div className="field">
+        <label>description（说明，可选）</label>
+        <input
+          value={input.description ?? ''}
+          onChange={(e) =>
+            onPatch({
+              description: e.target.value === '' ? undefined : e.target.value,
+            })
+          }
+        />
+      </div>
+
+      {isEnum && (
+        <div className="field">
+          <label>values（候选值，必须非空）</label>
+          {values.map((v, vIdx) => (
+            <div
+              key={vIdx}
+              style={{ display: 'flex', gap: 4, marginBottom: 4 }}
+            >
+              <input
+                value={v}
+                placeholder="候选值"
+                onChange={(e) => onSetValue(vIdx, e.target.value)}
+              />
+              <button
+                onClick={() => onRemoveValue(vIdx)}
+                style={{ fontSize: 10 }}
+              >
+                ×
+              </button>
+            </div>
+          ))}
+          <button
+            onClick={onAddValue}
+            style={{ fontSize: 11, padding: '2px 8px' }}
+          >
+            + 候选值
+          </button>
+          {enumEmpty && (
+            <small style={WARN}>
+              ⚠ enum 至少需要一个非空候选值，否则后端 loader 会拒绝该 workflow
+            </small>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/** default 值渲染成输入框文本（非字符串值序列化展示，便于编辑后回填字符串）。 */
+function defaultToText(value: unknown): string {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'string') return value;
+  return String(value);
+}

package/src/inspector/Inspector.tsx

@@ -3,6 +3,7 @@ import { useWorkflowStore } from '../store/workflowStore.ts';
 import { ToolNodeForm } from './ToolNodeForm.tsx';
 import { LlmNodeForm } from './LlmNodeForm.tsx';
 import { SkillNodeForm } from './SkillNodeForm.tsx';
+import { InputsPanel } from './InputsPanel.tsx';
 import type { StepDef, StepKind } from '../types.ts';
 
 export function Inspector() {
@@ -12,13 +13,9 @@ export function Inspector() {
   const removeStep = useWorkflowStore((s) => s.removeStep);
 
   const node = nodes.find((n) => n.id === selectedId);
+  // 未选中节点时编辑 workflow 级属性（name/description/version/inputs），符合直觉
   if (!node) {
-    return (
-      <aside className="inspector">
-        <h2>属性</h2>
-        <div className="empty">选中一个节点以编辑参数</div>
-      </aside>
-    );
+    return <InputsPanel />;
   }
   const step = node.data.step;
   const kind = node.data.kind;

package/src/inspector/LlmNodeForm.tsx

@@ -1,30 +1,27 @@
+import { useEffect, useMemo, useState } from 'react';
 import type { StepDef } from '../types.ts';
+import { tryParseJson } from './schemaForm.ts';
 
 interface Props {
   step: StepDef;
   onPatch: (patch: Partial<StepDef>) => void;
 }
 
+type ContextFile = { path: string; hint?: string };
+
 /**
- * llm 字段两种形态：
- *   - string：直接是 prompt 文本
- *   - object：{ prompt, model?, temperature?, ... } 高级形态
+ * llm 节点表单。
+ *
+ * A2 收敛：后端 execLlmStep 第一行 `if (typeof step.llm !== 'string') throw`，
+ * 只接受 string —— object 形态（per-step model/temperature）后端零支持（provider
+ * 是全局的，runner 用 ctx.provider）。所以这里**只写回 string**。读取旧 object YAML
+ * 时由 extractPrompt 运行时降级提取 .prompt，向后兼容不丢数据。
  *
- * MVP 阶段只编辑 prompt 文本；其它高级字段在 yaml 视图里改。
+ * B1 暴露 ADR-05 三个 llm-only 字段（后端 loader 对 skill 节点会拒绝它们，故只在
+ * llm 节点出现）：output_schema / context_files / allowed_tools。
  */
 export function LlmNodeForm({ step, onPatch }: Props) {
   const prompt = extractPrompt(step.llm);
-  const isObjectForm = step.llm !== null && typeof step.llm === 'object';
-
-  const onPromptChange = (text: string) => {
-    if (isObjectForm) {
-      onPatch({
-        llm: { ...(step.llm as Record<string, unknown>), prompt: text },
-      });
-    } else {
-      onPatch({ llm: text });
-    }
-  };
 
   return (
     <>
@@ -35,21 +32,243 @@ export function LlmNodeForm({ step, onPatch }: Props) {
           rows={8}
           spellCheck={false}
           placeholder="请用一句话评价 ${book}"
-          onChange={(e) => onPromptChange(e.target.value)}
+          // A2：一律写回纯 string（删除了旧 isObjectForm 写 object 的分支）
+          onChange={(e) => onPatch({ llm: e.target.value })}
           style={{ fontFamily: 'ui-monospace, monospace', fontSize: 12 }}
         />
         <small style={{ color: '#6b7280', fontSize: 11 }}>
-          支持 ${'{var}'} 模板；
-          {isObjectForm
-            ? '对象形态 — model / temperature 等字段请在 YAML 视图编辑'
-            : '默认走主 provider'}
+          支持 ${'{var}'} 模板；默认走主 provider
         </small>
       </div>
+
+      <AdvancedAdr05Section step={step} onPatch={onPatch} />
     </>
   );
 }
 
-function extractPrompt(llm: StepDef['llm']): string {
+/**
+ * 折叠的「高级（ADR-05）」区，默认收起，保持表单清爽（折叠写法对齐
+ * ToolNodeForm.tsx 的 AdvancedSection）。聚合 output_schema / context_files /
+ * allowed_tools 三个 llm 专属字段。
+ */
+function AdvancedAdr05Section({ step, onPatch }: Props) {
+  const [open, setOpen] = useState(false);
+
+  // 已配置任一字段时，徽标提示数量，便于折叠态下也能看出"里面有料"
+  const activeCount =
+    (step.output_schema !== undefined ? 1 : 0) +
+    (step.context_files && step.context_files.length > 0 ? 1 : 0) +
+    (step.allowed_tools && step.allowed_tools.length > 0 ? 1 : 0);
+
+  return (
+    <div className="field">
+      <label
+        style={{ cursor: 'pointer', userSelect: 'none' }}
+        onClick={() => setOpen(!open)}
+      >
+        {open ? '▼' : '▶'} 高级（ADR-05）
+        {activeCount > 0 && (
+          <span style={{ color: '#9ca3af', fontWeight: 'normal' }}>
+            {' '}
+            （已配置 {activeCount}）
+          </span>
+        )}
+      </label>
+      {open && (
+        <>
+          <OutputSchemaField
+            value={step.output_schema}
+            onChange={(v) => onPatch({ output_schema: v })}
+          />
+          <ContextFilesField
+            value={step.context_files ?? []}
+            onChange={(arr) =>
+              onPatch({ context_files: arr.length > 0 ? arr : undefined })
+            }
+          />
+          <AllowedToolsField
+            value={step.allowed_tools ?? []}
+            onChange={(arr) =>
+              onPatch({ allowed_tools: arr.length > 0 ? arr : undefined })
+            }
+          />
+        </>
+      )}
+    </div>
+  );
+}
+
+interface OutputSchemaProps {
+  value: Record<string, unknown> | undefined;
+  onChange: (v: Record<string, unknown> | undefined) => void;
+}
+
+/** output_schema：JSON textarea，onBlur 校验（必须是 object）。 */
+function OutputSchemaField({ value, onChange }: OutputSchemaProps) {
+  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(r.error);
+      return;
+    }
+    // 清空 → undefined（关掉结构化输出）
+    if (r.value === undefined) {
+      setError(null);
+      onChange(undefined);
+      return;
+    }
+    if (typeof r.value !== 'object' || r.value === null || Array.isArray(r.value)) {
+      setError('output_schema 必须是 object（JSON Schema，{...}）');
+      return;
+    }
+    setError(null);
+    onChange(r.value as Record<string, unknown>);
+  };
+
+  return (
+    <div className="field">
+      <label>output_schema</label>
+      <textarea
+        value={text}
+        rows={6}
+        spellCheck={false}
+        placeholder={'{\n  "type": "object",\n  "properties": { ... }\n}'}
+        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 }}>
+          ⚠ {error}
+        </small>
+      )}
+      <small style={{ color: '#6b7280', fontSize: 11 }}>
+        provider-native 结构化输出；留空 = 普通文本输出
+      </small>
+    </div>
+  );
+}
+
+interface ContextFilesProps {
+  value: ContextFile[];
+  onChange: (arr: ContextFile[]) => void;
+}
+
+/** context_files：path（必填）+ hint（可选）的可增删行列表。 */
+function ContextFilesField({ value, onChange }: ContextFilesProps) {
+  return (
+    <div className="field">
+      <label>context_files</label>
+      {value.map((row, i) => (
+        // 行顺序稳定且无业务 key，用 index 作 key 可接受
+        // biome-ignore lint/suspicious/noArrayIndexKey: 行无稳定 id
+        <div
+          key={i}
+          style={{ display: 'flex', gap: 6, marginBottom: 4, alignItems: 'center' }}
+        >
+          <input
+            value={row.path}
+            placeholder="path（支持 ${var}）"
+            onChange={(e) =>
+              onChange(updateContextFileRow(value, i, { path: e.target.value }))
+            }
+            style={{ flex: 2, fontFamily: 'ui-monospace, monospace', fontSize: 12 }}
+          />
+          <input
+            value={row.hint ?? ''}
+            placeholder="hint（可选）"
+            onChange={(e) =>
+              onChange(updateContextFileRow(value, i, { hint: e.target.value }))
+            }
+            style={{ flex: 3, fontSize: 12 }}
+          />
+          <button
+            type="button"
+            title="删除此行"
+            onClick={() => onChange(removeContextFileRow(value, i))}
+            style={{ flex: '0 0 auto', cursor: 'pointer' }}
+          >
+            ✕
+          </button>
+        </div>
+      ))}
+      <button
+        type="button"
+        onClick={() => onChange(addContextFileRow(value))}
+        style={{ cursor: 'pointer', fontSize: 12 }}
+      >
+        + 添加文件
+      </button>
+      <small style={{ color: '#6b7280', fontSize: 11 }}>
+        runner 会用 Read 按需读取这些文件（RAG）；支持 ${'{var}'} 模板
+      </small>
+    </div>
+  );
+}
+
+interface AllowedToolsProps {
+  value: string[];
+  onChange: (arr: string[]) => void;
+}
+
+/** allowed_tools：逗号分隔单 input（取简单方案）。 */
+function AllowedToolsField({ value, onChange }: AllowedToolsProps) {
+  // 受控为字符串，保留用户半截输入（尾随逗号/空格），onChange 时即时解析写回
+  const [text, setText] = useState(value.join(', '));
+
+  useEffect(() => {
+    setText(value.join(', '));
+  }, [value]);
+
+  return (
+    <div className="field">
+      <label>allowed_tools</label>
+      <input
+        value={text}
+        placeholder="Read, Grep"
+        onChange={(e) => {
+          setText(e.target.value);
+          onChange(parseCsvList(e.target.value));
+        }}
+        style={{ fontFamily: 'ui-monospace, monospace', fontSize: 12 }}
+      />
+      <small style={{ color: '#6b7280', fontSize: 11 }}>
+        与 context_files 配对的工具白名单，缺省 ['Read']
+      </small>
+    </div>
+  );
+}
+
+// ===== 纯函数（可单测，不依赖 React）=====
+
+/**
+ * 从 step.llm 提取 prompt 文本（运行时防御，入参 unknown）：
+ *   - string → 直接用
+ *   - object → 取 .prompt（向后兼容旧 object 形态 YAML，不丢数据）
+ *   - 其它 → ''
+ */
+export function extractPrompt(llm: unknown): string {
   if (typeof llm === 'string') return llm;
   if (llm && typeof llm === 'object') {
     const p = (llm as Record<string, unknown>).prompt;
@@ -57,3 +276,41 @@ function extractPrompt(llm: StepDef['llm']): string {
   }
   return '';
 }
+
+/** 逗号分隔字符串 → 去空白、去空项的 string[]。 */
+export function parseCsvList(raw: string): string[] {
+  return raw
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+/** 末尾追加一个空 context_files 行（返回新数组，不原地改）。 */
+export function addContextFileRow(rows: ContextFile[]): ContextFile[] {
+  return [...rows, { path: '' }];
+}
+
+/**
+ * 更新第 i 行的 path / hint（返回新数组）。
+ * hint 被清空（''）时从对象删除该键，保持产出干净（与后端可选字段对齐）。
+ */
+export function updateContextFileRow(
+  rows: ContextFile[],
+  i: number,
+  patch: Partial<ContextFile>,
+): ContextFile[] {
+  return rows.map((row, idx) => {
+    if (idx !== i) return row;
+    const next: ContextFile = { ...row, ...patch };
+    if (next.hint === undefined || next.hint === '') delete next.hint;
+    return next;
+  });
+}
+
+/** 删除第 i 行（返回新数组）。 */
+export function removeContextFileRow(
+  rows: ContextFile[],
+  i: number,
+): ContextFile[] {
+  return rows.filter((_, idx) => idx !== i);
+}

package/src/store/workflowStore.ts

@@ -55,6 +55,17 @@ interface WorkflowState {
   redo: () => void;
   /** 生成当前 workflow 完整 def（含 __meta.layout/edges/warnings） */
   toWorkflowDef: () => WorkflowDef;
+  /** 编辑 workflow 级元信息（name/description/version/inputs）。进 history + 置 dirty。 */
+  updateMeta: (
+    patch: Partial<
+      Pick<WorkflowDef, 'name' | 'description' | 'version' | 'inputs'>
+    >,
+  ) => void;
+  /**
+   * 把校验错误按节点 id 写回各 node.data.errors（派生态）。
+   * 不进 history、不置 dirty；幂等：与当前 errors 相同则不触发渲染（防 validate→setNodeErrors→re-render 死循环）。
+   */
+  setNodeErrors: (errorsByNodeId: Map<string, string[]>) => void;
 }
 
 const initialMeta = {
@@ -322,8 +333,41 @@ export const useWorkflowStore = create<WorkflowState>((set, get) => ({
     const result = assembleWorkflow(meta, nodes, edges);
     return result;
   },
+
+  updateMeta: (patch) => {
+    pushHistorySnapshot(get, set);
+    set({ meta: { ...get().meta, ...patch }, dirty: true });
+  },
+
+  setNodeErrors: (errorsByNodeId) => {
+    const { nodes } = get();
+    let changed = false;
+    const next = nodes.map((n) => {
+      const incoming = errorsByNodeId.get(n.id);
+      const normalized = incoming && incoming.length > 0 ? incoming : undefined;
+      if (sameErrors(n.data.errors, normalized)) return n;
+      changed = true;
+      return { ...n, data: { ...n.data, errors: normalized } };
+    });
+    if (!changed) return; // 幂等：无变化不 set，避免 nodes 引用变动触发 effect 死循环
+    set({ nodes: next });
+  },
 }));
 
+/** errors 数组浅比较（都空视为相等），供 setNodeErrors 幂等判断。 */
+function sameErrors(
+  a: string[] | undefined,
+  b: string[] | undefined,
+): boolean {
+  const aa = a ?? [];
+  const bb = b ?? [];
+  if (aa.length !== bb.length) return false;
+  for (let i = 0; i < aa.length; i++) {
+    if (aa[i] !== bb[i]) return false;
+  }
+  return true;
+}
+
 function detectKind(step: StepDef): string {
   if (step.type) return step.type;
   if (step.tool) return 'tool';

package/src/types.ts

@@ -16,16 +16,21 @@ export type StepKind =
 
 export interface WorkflowInput {
   name: string;
-  type?: 'string' | 'number' | 'boolean';
+  type?: 'string' | 'number' | 'enum';
   required?: boolean;
   default?: unknown;
+  /** type=enum 时的候选值清单（与后端 InputDef.values 对齐；enum 必填非空） */
+  values?: string[];
+  /** 输入项说明，渲染到表单与变量提示 */
+  description?: string;
 }
 
 export interface StepDef {
   id: string;
   type?: StepKind;
   tool?: string;
-  llm?: string | Record<string, unknown>;
+  /** 后端 execLlmStep 只接受 string；object 形态（model/temperature per-step）后端零支持，故收敛到 string。读取旧 object YAML 时由 LlmNodeForm 运行时降级提取 prompt。 */
+  llm?: string;
   skill?: string;
   args?: Record<string, unknown>;
   input?: string;

package/src/yaml-view/sync.ts

@@ -111,90 +111,449 @@ export function stringifyWorkflowYaml(def: WorkflowDef): string {
 }
 
 /* ─────────────────────────────────────────────────────────────────────────
- * validateWorkflow
+ * validateWorkflow / validateWorkflowByNode
+ *
+ *  这两个导出共享同一套**递归**结构校验核心 collectStepErrors，精确镜像后端
+ *  plugins/workflow-runner/src/loader.ts 的 validate / validateSteps（D2 解耦
+ *  红线：不能 import 后端代码，规则靠手抄）。
+ *
+ *  - validateWorkflowByNode → Map<step.id, string[]>：供画布节点级 badge 接线。
+ *    branch/loop 的 then/else/do 子步骤在画布上**有独立节点** → 错误归各自 id；
+ *    parallel/vote 的 fork 子步骤**无独立画布节点** → 错误归并到父节点 id。
+ *  - validateWorkflow → 扁平 string[]：= 顶层 name/description/steps 错误 +
+ *    byNode 所有 value 拍平。签名（接收 def、返回 string[]）**保持不变**，
+ *    App.tsx::onSave 依赖它。
  * ──────────────────────────────────────────────────────────────────────── */
 
+// ADR-05：控制流 type 集合——这些节点的"动作"由 type 自身定义，
+// 不能附带 tool/skill/llm，也不能配 output_schema / context_files / allowed_tools。
+const CONTROL_FLOW_TYPES = new Set<string>([
+  'assert',
+  'branch',
+  'loop',
+  'pause',
+  'parallel',
+  'vote',
+]);
+
+// 合法的 step.type 枚举（与后端 VALID_STEP_TYPES 同集）。
+const VALID_STEP_TYPES = new Set<string>([
+  'assert',
+  'branch',
+  'loop',
+  'pause',
+  'parallel',
+  'vote',
+]);
+
 /**
- * 校验 WorkflowDef 结构；返回 errors 数组（空 = OK）。
+ * 校验 WorkflowDef 结构；返回扁平 errors 数组（空 = OK）。
  *
- * MVP 阶段检查：
- *   - step 缺 id
- *   - step 没有可执行字段（tool / llm / skill / type）
- *   - step id 重复
- *   - `${var}` 引用未在前序 step 的 capture values / inputs 里出现
+ * = 顶层字段错误（name / description / steps）+ 所有 step（含递归子步骤）的
+ *   结构错误 + 变量引用错误，全部拍平。
+ *
+ * 硬约束：签名不可变（App.tsx::onSave 依赖扁平 string[]）。
  */
 export function validateWorkflow(def: WorkflowDef): string[] {
-  const errors: string[] = [];
-
   if (!def || typeof def !== 'object') {
     return ['Workflow 不是对象'];
   }
+
+  const errors: string[] = [];
+  errors.push(...topLevelErrors(def));
+
+  if (!Array.isArray(def.steps)) {
+    // steps 缺失：顶层错误已记录，无法继续递归
+    return errors;
+  }
+
+  // 递归收集每个 step 的结构错误（已按 id 归类，这里只取 value 拍平）。
+  const byId = collectStepErrors(def.steps, makeInitialKnownVars(def), '');
+  for (const list of byId.values()) errors.push(...list);
+
+  return errors;
+}
+
+/**
+ * 校验 WorkflowDef 结构；返回 Map<step.id, string[]>，供画布节点级错误 badge。
+ *
+ * 仅含 step 维度的错误（不含顶层 name/description/steps —— 那些没有对应节点）。
+ * fork 子步骤错误归并到父 parallel/vote 节点的 id；then/else/do 子步骤归各自 id。
+ */
+export function validateWorkflowByNode(
+  def: WorkflowDef,
+): Map<string, string[]> {
+  if (!def || typeof def !== 'object' || !Array.isArray(def.steps)) {
+    return new Map();
+  }
+  return collectStepErrors(def.steps, makeInitialKnownVars(def), '');
+}
+
+/** 顶层字段（name / description / steps / inputs）结构校验，返回扁平错误。 */
+function topLevelErrors(def: WorkflowDef): string[] {
+  const errors: string[] = [];
+
   if (typeof def.name !== 'string' || !def.name.trim()) {
     errors.push('Workflow 缺少 name');
   }
+  if (typeof def.description !== 'string' || !def.description.trim()) {
+    errors.push('Workflow 缺少 description');
+  }
   if (!Array.isArray(def.steps)) {
     errors.push('Workflow 缺少 steps 数组');
-    return errors;
+  } else if (def.steps.length === 0) {
+    errors.push('Workflow 的 steps 不能为空');
   }
 
-  // 已知变量集合：先放 inputs.*
-  const knownVars = new Set<string>();
-  for (const inp of def.inputs ?? []) {
-    if (inp?.name) {
-      knownVars.add(`inputs.${inp.name}`);
+  // inputs 若存在：必须数组；每项 name 非空；type 枚举；enum 必须非空 values
+  if (def.inputs !== undefined) {
+    if (!Array.isArray(def.inputs)) {
+      errors.push('inputs 必须是数组');
+    } else {
+      def.inputs.forEach((item, i) => {
+        if (!item || typeof item !== 'object') {
+          errors.push(`inputs[${i}] 必须是对象`);
+          return;
+        }
+        const r = item as Record<string, unknown>;
+        if (typeof r.name !== 'string' || r.name.length === 0) {
+          errors.push(`inputs[${i}].name 必填（非空 string）`);
+        }
+        if (
+          r.type !== undefined &&
+          r.type !== 'string' &&
+          r.type !== 'number' &&
+          r.type !== 'enum'
+        ) {
+          errors.push(`inputs[${i}].type 必须是 string / number / enum`);
+        }
+        if (
+          r.type === 'enum' &&
+          (!Array.isArray(r.values) || r.values.length === 0)
+        ) {
+          errors.push(`inputs[${i}].values 必填（type=enum 时，非空数组）`);
+        }
+      });
     }
   }
 
-  const seenIds = new Set<string>();
+  return errors;
+}
+
+/** 已知变量初始集合：inputs.* 全名。 */
+function makeInitialKnownVars(def: WorkflowDef): Set<string> {
+  const known = new Set<string>();
+  for (const inp of def.inputs ?? []) {
+    if (inp?.name) known.add(`inputs.${inp.name}`);
+  }
+  return known;
+}
 
-  for (const step of def.steps) {
-    const sid = step?.id ?? '<no-id>';
+/**
+ * 递归校验 steps，返回 Map<归属节点 id, 错误列表>。
+ *
+ * 镜像后端 validateSteps：
+ *   - 同级 id 唯一（fork/then/else/do 各自子作用域内独立判重）
+ *   - type 枚举、动作字段恰好一个、各控制流必填字段、ADR-05 约束
+ *   - 递归进 then/else/do/fork
+ *
+ * 错误归属规则：
+ *   - then/else/do 子步骤 → 子步骤自己的 id（画布有独立节点）
+ *   - fork 子步骤 → 父 parallel/vote 节点的 id（画布无独立节点）
+ *
+ * 变量检查（editor 增值，与结构校验冲突时以不误报为先）：
+ *   knownVars 在**同级链**上顺序累积（前序 step 的 capture values 注入），
+ *   loop 的 `as` 在其 do 子作用域内视为已知。
+ *
+ * @param ownerId  当前 steps 数组的「归属节点」；非空表示这些 step 无独立画布
+ *                 节点（fork 场景），错误应归并到 ownerId。空串表示子步骤各归己 id。
+ */
+function collectStepErrors(
+  steps: StepDef[],
+  inheritedVars: Set<string>,
+  ownerId: string,
+): Map<string, string[]> {
+  const out = new Map<string, string[]>();
+  const push = (id: string, msg: string): void => {
+    const key = ownerId || id;
+    const list = out.get(key);
+    if (list) list.push(msg);
+    else out.set(key, [msg]);
+  };
+  const merge = (child: Map<string, string[]>): void => {
+    for (const [id, list] of child) {
+      // ownerId 非空时，子步骤错误一并归并到 ownerId
+      const key = ownerId || id;
+      const existing = out.get(key);
+      if (existing) existing.push(...list);
+      else out.set(key, [...list]);
+    }
+  };
+
+  // 同级 id 唯一（仅在当前 steps 数组内强制）
+  const seenIds = new Set<string>();
+  // 同级链上顺序累积的已知变量（capture 注入）
+  const knownVars = new Set<string>(inheritedVars);
 
-    if (!step?.id || typeof step.id !== 'string') {
-      errors.push(`Step "${sid}" 缺少 id`);
-      continue;
+  steps.forEach((item, i) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      push(ownerId || `<step-${i}>`, `steps[${i}] 必须是对象`);
+      return;
     }
-    if (seenIds.has(step.id)) {
-      errors.push(`Step id 重复: "${step.id}"`);
+    const s = item as StepDef & Record<string, unknown>;
+    const sid =
+      typeof s.id === 'string' && s.id.length > 0 ? s.id : `<step-${i}>`;
+
+    // id 非空
+    if (typeof s.id !== 'string' || s.id.length === 0) {
+      push(sid, `Step "${sid}" 缺少 id`);
     } else {
-      seenIds.add(step.id);
-    }
-
-    // 执行字段检测：tool / llm / skill / type 至少有一个
-    const hasExec =
-      !!step.tool ||
-      !!step.llm ||
-      !!step.skill ||
-      !!step.type;
-    if (!hasExec) {
-      errors.push(
-        `Step "${step.id}" 没有可执行字段（tool / llm / skill / 或 type）`,
+      if (seenIds.has(s.id)) {
+        push(sid, `Step id 重复: "${s.id}"`);
+      } else {
+        seenIds.add(s.id);
+      }
+    }
+
+    // type 枚举（提前于动作互斥，给更准确的错误）
+    if (
+      s.type !== undefined &&
+      (typeof s.type !== 'string' || !VALID_STEP_TYPES.has(s.type))
+    ) {
+      push(
+        sid,
+        `Step "${sid}" 的 type "${String(s.type)}" 非法；合法值: ${[
+          ...VALID_STEP_TYPES,
+        ].join(' / ')}`,
+      );
+    }
+
+    // 动作字段恰好一个：tool / skill / llm / type
+    const actionFields = ['tool', 'skill', 'llm', 'type'] as const;
+    const present = actionFields.filter((k) => s[k] !== undefined);
+    if (present.length === 0) {
+      push(
+        sid,
+        `Step "${sid}" 必须有以下字段之一: tool / skill / llm / type`,
       );
+    } else if (present.length > 1) {
+      push(
+        sid,
+        `Step "${sid}" 同时设置了 ${present.join(', ')}；只允许其中一个`,
+      );
+    }
+
+    // ── 控制流字段一致性 ──
+    if (s.type === 'branch' && s.condition === undefined) {
+      push(sid, `Step "${sid}" type=branch 必须带 condition`);
+    }
+    if (s.type === 'assert' && s.condition === undefined) {
+      push(sid, `Step "${sid}" type=assert 必须带 condition`);
+    }
+    if (s.type === 'branch') {
+      if (s.then !== undefined && !Array.isArray(s.then)) {
+        push(sid, `Step "${sid}" 的 then 必须是数组`);
+      }
+      if (s.else !== undefined && !Array.isArray(s.else)) {
+        push(sid, `Step "${sid}" 的 else 必须是数组`);
+      }
+      // then/else 子步骤：画布有独立节点 → 错误归各自 id（ownerId 传空串）
+      if (Array.isArray(s.then)) {
+        merge(collectStepErrors(s.then as StepDef[], knownVars, ''));
+      }
+      if (Array.isArray(s.else)) {
+        merge(collectStepErrors(s.else as StepDef[], knownVars, ''));
+      }
+    }
+    if (s.type === 'loop') {
+      if (s.over === undefined) {
+        push(sid, `Step "${sid}" type=loop 必须带 over`);
+      }
+      if (typeof s.as !== 'string' || s.as.length === 0) {
+        push(sid, `Step "${sid}" type=loop 必须带 as（非空 string）`);
+      }
+      if (!Array.isArray(s.do)) {
+        push(sid, `Step "${sid}" type=loop 必须带 do 数组`);
+      } else {
+        // loop 的 as 在 do 子作用域内视为已知变量
+        const doVars = new Set<string>(knownVars);
+        if (typeof s.as === 'string' && s.as.length > 0) doVars.add(s.as);
+        merge(collectStepErrors(s.do as StepDef[], doVars, ''));
+      }
     }
 
-    // 变量引用检查（只查 ${xxx}，inputs.* 和已知 capture）
-    const refs = collectVarRefs(step);
-    for (const ref of refs) {
-      // 把 inputs.book 这种 dotted 也接受为已知；变量名首段或全名匹配都行
+    // ── ADR-05：parallel ──
+    if (s.type === 'parallel') {
+      if (!Array.isArray(s.fork) || s.fork.length === 0) {
+        push(
+          sid,
+          `Step "${sid}" type=parallel 必须有 fork: [...]（至少 1 个子步骤）`,
+        );
+      } else {
+        // fork 子步骤：画布无独立节点 → 错误归并到父节点 id（ownerId 传 sid）
+        merge(collectStepErrors(s.fork as StepDef[], knownVars, sid));
+      }
+    } else if (s.fork !== undefined) {
+      push(sid, `Step "${sid}" 的 fork 只能用在 type=parallel 节点上`);
+    }
+
+    // ── ADR-05：vote ──
+    if (s.type === 'vote') {
+      const vc = s.voters_count;
+      const rules = s.rules;
+      const input = s.input;
+      const bad =
+        typeof vc !== 'number' ||
+        !Number.isInteger(vc) ||
+        vc < 2 ||
+        vc > 10 ||
+        typeof rules !== 'string' ||
+        rules.length === 0 ||
+        typeof input !== 'string' ||
+        input.length === 0;
+      if (bad) {
+        push(
+          sid,
+          `Step "${sid}" type=vote 要求 voters_count (2~10 整数), rules, input 三个字段`,
+        );
+      }
+      if (s.threshold !== undefined) {
+        const t = s.threshold;
+        if (
+          typeof t !== 'number' ||
+          !Number.isInteger(t) ||
+          t < 1 ||
+          (typeof vc === 'number' && t > vc)
+        ) {
+          push(
+            sid,
+            `Step "${sid}" threshold=${String(
+              t,
+            )} 超出范围；必须 1 <= threshold <= voters_count`,
+          );
+        }
+      }
+    } else {
+      // 非 vote 节点不应携带 vote-only 字段
+      for (const k of ['voters_count', 'rules', 'threshold'] as const) {
+        if (s[k] !== undefined) {
+          push(sid, `Step "${sid}" 的 ${k} 只能用在 type=vote 节点上`);
+        }
+      }
+    }
+
+    const isControlFlow =
+      typeof s.type === 'string' && CONTROL_FLOW_TYPES.has(s.type);
+
+    // ── ADR-05：output_schema ──
+    if (s.output_schema !== undefined) {
+      if (
+        typeof s.output_schema !== 'object' ||
+        s.output_schema === null ||
+        Array.isArray(s.output_schema)
+      ) {
+        push(sid, `Step "${sid}" 的 output_schema 必须是对象`);
+      }
+      if (isControlFlow) {
+        push(
+          sid,
+          `Step "${sid}" 的 output_schema 不能用在 type=${s.type} 控制流节点上`,
+        );
+      }
+      if (s.skill !== undefined) {
+        push(
+          sid,
+          `Step "${sid}" 的 output_schema 暂不支持 skill 节点（仅 llm 节点生效）`,
+        );
+      }
+    }
+
+    // ── ADR-05：context_files ──
+    if (s.context_files !== undefined) {
+      if (!Array.isArray(s.context_files)) {
+        push(sid, `Step "${sid}" 的 context_files 必须是数组`);
+      } else {
+        (s.context_files as unknown[]).forEach((cf, j) => {
+          if (!cf || typeof cf !== 'object' || Array.isArray(cf)) {
+            push(
+              sid,
+              `Step "${sid}" 的 context_files[${j}] 必须是 { path: string, hint?: string } 对象`,
+            );
+            return;
+          }
+          const r = cf as Record<string, unknown>;
+          if (typeof r.path !== 'string' || r.path.length === 0) {
+            push(
+              sid,
+              `Step "${sid}" 的 context_files[${j}].path 必填（非空 string）`,
+            );
+          }
+          if (r.hint !== undefined && typeof r.hint !== 'string') {
+            push(
+              sid,
+              `Step "${sid}" 的 context_files[${j}].hint 必须是 string`,
+            );
+          }
+        });
+      }
+      if (isControlFlow) {
+        push(
+          sid,
+          `Step "${sid}" 的 context_files 不能用在 type=${s.type} 控制流节点上`,
+        );
+      }
+      if (s.skill !== undefined) {
+        push(
+          sid,
+          `Step "${sid}" 的 context_files 暂不支持 skill 节点（仅 llm 节点生效）`,
+        );
+      }
+    }
+
+    // ── ADR-05：allowed_tools ──
+    if (s.allowed_tools !== undefined) {
+      if (
+        !Array.isArray(s.allowed_tools) ||
+        !(s.allowed_tools as unknown[]).every(
+          (x) => typeof x === 'string' && x.length > 0,
+        )
+      ) {
+        push(sid, `Step "${sid}" 的 allowed_tools 必须是非空 string 数组`);
+      }
+      if (isControlFlow) {
+        push(
+          sid,
+          `Step "${sid}" 的 allowed_tools 不能用在 type=${s.type} 控制流节点上`,
+        );
+      }
+      if (s.skill !== undefined) {
+        push(
+          sid,
+          `Step "${sid}" 的 allowed_tools 暂不支持 skill 节点（仅 llm 节点生效）`,
+        );
+      }
+    }
+
+    // ── 变量引用检查（editor 增值；冲突时以不误报为先）──
+    for (const ref of collectVarRefs(s)) {
       if (knownVars.has(ref)) continue;
       const head = ref.split('.')[0];
       if (knownVars.has(head)) continue;
-      errors.push(
-        `Step "${step.id}" 引用了未在 capture 里出现的变量: \${${ref}}`,
+      push(
+        sid,
+        `Step "${sid}" 引用了未在 capture 里出现的变量: \${${ref}}`,
       );
     }
 
-    // 把本 step 的 capture values 注入已知集合，供后续 step 引用
-    if (step.capture && typeof step.capture === 'object') {
-      for (const v of Object.values(step.capture)) {
-        if (typeof v === 'string' && v.trim()) {
-          knownVars.add(v);
-        }
+    // 把本 step 的 capture values 注入同级已知集合，供后续 step 引用
+    if (s.capture && typeof s.capture === 'object') {
+      for (const v of Object.values(s.capture)) {
+        if (typeof v === 'string' && v.trim()) knownVars.add(v);
       }
     }
-  }
+  });
 
-  return errors;
+  return out;
 }
 
 /** 递归遍历 step 所有字符串字段，收集 `${...}` 内的变量名。 */
@@ -216,9 +575,12 @@ function collectVarRefs(step: StepDef): string[] {
     }
   };
 
-  // 不扫 id 自己 / capture 的 values（capture value 是变量定义而非引用）
+  // 不扫：id（自己）/ capture（value 是变量定义而非引用）/
+  //       then/else/do/fork（子步骤有独立作用域，由 collectStepErrors 递归各自检查，
+  //       否则子作用域才有的变量——如 loop 的 as、子步骤前序 capture——会在父级误报）
+  const SKIP_KEYS = new Set(['id', 'capture', 'then', 'else', 'do', 'fork']);
   for (const [k, v] of Object.entries(step)) {
-    if (k === 'id' || k === 'capture') continue;
+    if (SKIP_KEYS.has(k)) continue;
     visit(v);
   }
   return refs;