@fieldwangai/agentflow 0.1.159 → 0.1.160

package/bin/lib/catalog-flows.mjs

@@ -29,6 +29,7 @@ import {
 } from "./marketplace.mjs";
 import { isWorkspacePreviewDir } from "./workspace-preview.mjs";
 import { RETIRED_NODE_IDS } from "./legacy-flow-execution.mjs";
+import { normalizeNodeUiForSlots } from "./node-ui-kit.mjs";
 
 /** 从指定目录收集含 flow.yaml 的子目录名。 */
 export function collectPipelineNamesFromDir(dirPath) {
@@ -219,6 +220,7 @@ export function parseNodeFrontmatter(raw) {
     displayName: undefined,
     description: undefined,
     guide: undefined,
+    ui: undefined,
     runtime: "native",
     type: "",
     paletteHidden: false,
@@ -242,6 +244,7 @@ export function parseNodeFrontmatter(raw) {
       data.paletteHidden = String(parsed.palette ?? "").trim().toLowerCase() === "hidden";
       data.input = normalizeFrontmatterSlots(parsed.input);
       data.output = normalizeFrontmatterSlots(parsed.output);
+      data.ui = normalizeNodeUiForSlots(parsed.ui, data.input, data.output);
       return data;
     }
   } catch {
@@ -320,7 +323,7 @@ export function listNodesJson(workspaceRoot, flowId, flowSource, opts = {}) {
         // frontmatter 的 type: 优先于按 id 前缀的推断（workspace_run 等不带前缀的节点靠它归类）
         if (data.type) type = data.type;
         // frontmatter 的 palette: hidden 与 RETIRED_NODE_IDS 等价，让节点自带可见性
-        if (data.paletteHidden) continue;
+        if (data.paletteHidden && !opts.includeHidden) continue;
         const strippedId =
           id.replace(/^agent_?/i, "").replace(/^control_?/i, "").replace(/^provide_?/i, "").replace(/^tool_?/i, "") || id;
         const label = data.displayName ?? strippedId;
@@ -343,6 +346,8 @@ export function listNodesJson(workspaceRoot, flowId, flowSource, opts = {}) {
           displayName: translatedDisplayName || data.displayName,
           description: translatedDescription || data.description,
           guide: translatedGuide || data.guide,
+          ui: data.ui,
+          paletteHidden: Boolean(data.paletteHidden),
           inputs: data.input,
           outputs: data.output,
           source: flowIdOpt ? "flow" : "project",
@@ -364,6 +369,7 @@ export function listNodesJson(workspaceRoot, flowId, flowSource, opts = {}) {
         label: manifest.displayName,
         displayName: manifest.displayName,
         description: manifest.description,
+        ui: manifest.ui,
         inputs: manifest.input,
         outputs: manifest.output,
         source: flowIdOpt ? "flow" : "project",
@@ -392,6 +398,7 @@ export function listNodesJson(workspaceRoot, flowId, flowSource, opts = {}) {
       label: manifest.displayName,
       displayName: manifest.displayName,
       description: manifest.description,
+      ui: manifest.ui,
       inputs: manifest.input,
       outputs: manifest.output,
       source: manifest.source || "marketplace",
@@ -664,6 +671,7 @@ export function readNodeJson(workspaceRoot, nodeId, flowId, flowSource, opts = {
       version: resolved.version,
       packageDir: resolved.packageDir,
       runtime: resolved.runtime,
+      ui: resolved.ui,
     };
   }
   const fileName = nodeId.endsWith(".md") ? nodeId : `${nodeId}.md`;
@@ -724,6 +732,7 @@ export function readNodeJson(workspaceRoot, nodeId, flowId, flowSource, opts = {
         executionLogic: content || undefined,
         description: data.description,
         guide: data.guide,
+        ui: data.ui,
       };
     } catch (_) {}
   }

package/bin/lib/control-while.mjs

@@ -0,0 +1,336 @@
+import crypto from "node:crypto";
+
+const DECISIONS = new Set(["continue", "wait", "done", "fail"]);
+const STEP_RESULT_KEYS = new Set(["decision", "state", "summary"]);
+
+export const DEFAULT_CONTROL_WHILE_MAX_ITERATIONS = 20;
+export const DEFAULT_CONTROL_WHILE_TIMEOUT_MS = 30 * 60 * 1000;
+export const MAX_CONTROL_WHILE_ITERATIONS = 1000;
+export const MAX_CONTROL_WHILE_TIMEOUT_MS = 7 * 24 * 60 * 60 * 1000;
+export const MAX_CONTROL_WHILE_STEP_STDOUT_BYTES = 1024 * 1024;
+export const MAX_CONTROL_WHILE_STEP_STDERR_BYTES = 256 * 1024;
+export const MAX_CONTROL_WHILE_SUMMARY_LENGTH = 4000;
+export const MAX_CONTROL_WHILE_STATE_BYTES = 1024 * 1024;
+
+export function parseControlWhileDurationMs(raw, fallback = DEFAULT_CONTROL_WHILE_TIMEOUT_MS) {
+  const text = String(raw ?? "").trim().toLowerCase();
+  if (!text) return fallback;
+  const match = text.match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/);
+  if (!match) throw new Error(`control.while invalid timeout: ${raw}`);
+  const value = Number(match[1]);
+  const unit = match[2] || "s";
+  const factor = unit === "ms" ? 1 : unit === "s" ? 1000 : unit === "m" ? 60_000 : unit === "h" ? 3_600_000 : 86_400_000;
+  const result = Math.round(value * factor);
+  if (!Number.isFinite(result) || result <= 0) throw new Error(`control.while timeout must be greater than zero: ${raw}`);
+  if (result > MAX_CONTROL_WHILE_TIMEOUT_MS) throw new Error("control.while timeout must not exceed 7d");
+  return result;
+}
+
+export function normalizeControlWhileConfig(inputs = {}) {
+  const rawMax = String(inputs.maxIterations ?? "").trim();
+  const maxIterations = rawMax ? Number(rawMax) : DEFAULT_CONTROL_WHILE_MAX_ITERATIONS;
+  if (!Number.isInteger(maxIterations) || maxIterations < 1 || maxIterations > MAX_CONTROL_WHILE_ITERATIONS) {
+    throw new Error(`control.while maxIterations must be an integer between 1 and ${MAX_CONTROL_WHILE_ITERATIONS}`);
+  }
+  return {
+    maxIterations,
+    timeoutMs: parseControlWhileDurationMs(inputs.timeout, DEFAULT_CONTROL_WHILE_TIMEOUT_MS),
+  };
+}
+
+export function normalizeControlWhileInitialState(raw) {
+  if (raw == null || String(raw).trim() === "") return null;
+  if (typeof raw === "object") {
+    assertControlWhileStateSize(raw);
+    return raw;
+  }
+  try {
+    const parsed = JSON.parse(String(raw));
+    assertControlWhileStateSize(parsed);
+    return parsed;
+  } catch (error) {
+    if (String(error?.message || "").startsWith("control.while state")) throw error;
+    throw new Error(`control.while state must be valid JSON: ${error.message}`);
+  }
+}
+
+export function serializeControlWhileState(value) {
+  const serialized = JSON.stringify(value ?? null);
+  if (serialized === undefined) throw new Error("control.while state must be JSON serializable");
+  if (Buffer.byteLength(serialized, "utf-8") > MAX_CONTROL_WHILE_STATE_BYTES) {
+    throw new Error(`control.while state must not exceed ${MAX_CONTROL_WHILE_STATE_BYTES} bytes`);
+  }
+  return serialized;
+}
+
+function assertControlWhileStateSize(value) {
+  serializeControlWhileState(value);
+}
+
+export function parseControlWhileStepResult(raw, currentState = null) {
+  const text = String(raw ?? "").trim();
+  if (!text) throw new Error("control.while step returned empty stdout; expected one JSON object");
+  if (Buffer.byteLength(text, "utf-8") > MAX_CONTROL_WHILE_STEP_STDOUT_BYTES) {
+    throw new Error(`control.while step stdout must not exceed ${MAX_CONTROL_WHILE_STEP_STDOUT_BYTES} bytes`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error) {
+    throw new Error(`control.while step stdout must be exactly one JSON object: ${error.message}`);
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("control.while step stdout must be a JSON object");
+  }
+  const unknownKeys = Object.keys(parsed).filter((key) => !STEP_RESULT_KEYS.has(key));
+  if (unknownKeys.length) {
+    throw new Error(`control.while step result contains unsupported fields: ${unknownKeys.join(", ")}`);
+  }
+  if (typeof parsed.decision !== "string") {
+    throw new Error("control.while decision must be a string");
+  }
+  const decision = parsed.decision;
+  if (!DECISIONS.has(decision)) {
+    throw new Error(`control.while decision must be continue, wait, done, or fail; received ${JSON.stringify(parsed.decision)}`);
+  }
+  if (parsed.summary != null && typeof parsed.summary !== "string") {
+    throw new Error("control.while summary must be a string");
+  }
+  const summary = parsed.summary || "";
+  if (summary.length > MAX_CONTROL_WHILE_SUMMARY_LENGTH) {
+    throw new Error(`control.while summary must not exceed ${MAX_CONTROL_WHILE_SUMMARY_LENGTH} characters`);
+  }
+  const state = Object.prototype.hasOwnProperty.call(parsed, "state") ? parsed.state : currentState;
+  assertControlWhileStateSize(state);
+  return {
+    decision,
+    state,
+    summary,
+  };
+}
+
+export function normalizeControlWhileHistory(raw) {
+  if (raw == null || String(raw).trim() === "") return [];
+  let parsed = raw;
+  if (!Array.isArray(raw)) {
+    try {
+      parsed = JSON.parse(String(raw));
+    } catch (error) {
+      throw new Error(`control.while checkpoint history must be valid JSON: ${error.message}`);
+    }
+  }
+  if (!Array.isArray(parsed)) throw new Error("control.while checkpoint history must be an array");
+  if (parsed.length > MAX_CONTROL_WHILE_ITERATIONS) {
+    throw new Error(`control.while checkpoint history must not exceed ${MAX_CONTROL_WHILE_ITERATIONS} entries`);
+  }
+  let previousIteration = 0;
+  return parsed.map((rawEntry, index) => {
+    if (!rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) {
+      throw new Error(`control.while checkpoint history entry ${index + 1} must be an object`);
+    }
+    const iteration = Number(rawEntry.iteration);
+    if (!Number.isInteger(iteration) || iteration < 1 || iteration <= previousIteration) {
+      throw new Error("control.while checkpoint iterations must be positive and strictly increasing");
+    }
+    const decision = rawEntry.decision;
+    if (typeof decision !== "string" || !DECISIONS.has(decision)) {
+      throw new Error(`control.while checkpoint entry ${iteration} has an invalid decision`);
+    }
+    if (rawEntry.summary != null && typeof rawEntry.summary !== "string") {
+      throw new Error(`control.while checkpoint entry ${iteration} has an invalid summary`);
+    }
+    const elapsedMs = Number(rawEntry.elapsedMs ?? 0);
+    if (!Number.isFinite(elapsedMs) || elapsedMs < 0) {
+      throw new Error(`control.while checkpoint entry ${iteration} has an invalid elapsedMs`);
+    }
+    const idempotencyKey = rawEntry.idempotencyKey == null ? "" : String(rawEntry.idempotencyKey);
+    if (idempotencyKey.length > 128) {
+      throw new Error(`control.while checkpoint entry ${iteration} has an invalid idempotencyKey`);
+    }
+    previousIteration = iteration;
+    return {
+      iteration,
+      decision,
+      summary: rawEntry.summary || "",
+      elapsedMs: Math.round(elapsedMs),
+      ...(idempotencyKey ? { idempotencyKey } : {}),
+    };
+  });
+}
+
+export function resolveControlWhileCheckpoint({
+  previousDecision = "",
+  state = "",
+  history = "",
+  iterations = "",
+  fingerprint = "",
+  expectedFingerprint = "",
+  allowResume = true,
+} = {}) {
+  if (String(previousDecision || "") !== "wait") return { resumable: false, reason: "not_waiting" };
+  if (!allowResume) return { resumable: false, reason: "resume_disabled" };
+  if (!fingerprint || fingerprint !== expectedFingerprint) return { resumable: false, reason: "fingerprint_mismatch" };
+
+  const parsedHistory = normalizeControlWhileHistory(history);
+  const last = parsedHistory[parsedHistory.length - 1];
+  const recordedIterations = Number(iterations);
+  if (!last || last.decision !== "wait") {
+    throw new Error("control.while waiting checkpoint is corrupt: history must end with wait");
+  }
+  if (!Number.isInteger(recordedIterations) || recordedIterations !== last.iteration) {
+    throw new Error("control.while waiting checkpoint is corrupt: iterations do not match history");
+  }
+  return {
+    resumable: true,
+    reason: "waiting_checkpoint",
+    state: normalizeControlWhileInitialState(state),
+    history: parsedHistory,
+    nextIteration: last.iteration + 1,
+    elapsedMs: parsedHistory.reduce((total, entry) => total + entry.elapsedMs, 0),
+  };
+}
+
+export function controlWhileCheckpointFingerprint({ inputFingerprint = "", initialState = null } = {}) {
+  return crypto.createHash("sha256")
+    .update(`${String(inputFingerprint || "")}\u0000${serializeControlWhileState(initialState)}`)
+    .digest("hex")
+    .slice(0, 24);
+}
+
+export function controlWhileIdempotencyKey({ checkpointFingerprint = "", nodeId = "", iteration = 1 } = {}) {
+  const absoluteIteration = Number(iteration);
+  if (!checkpointFingerprint || !nodeId || !Number.isInteger(absoluteIteration) || absoluteIteration < 1) {
+    throw new Error("control.while cannot create idempotency key without checkpoint fingerprint, nodeId, and iteration");
+  }
+  const digest = crypto.createHash("sha256")
+    .update(`${checkpointFingerprint}\u0000${nodeId}\u0000${absoluteIteration}`)
+    .digest("hex")
+    .slice(0, 32);
+  return `afw_${digest}`;
+}
+
+function controlWhileTimeoutError(timeoutMs) {
+  const error = new Error(`control.while timed out after ${timeoutMs}ms`);
+  error.code = "CONTROL_WHILE_TIMEOUT";
+  return error;
+}
+
+/**
+ * Execute one deterministic step repeatedly. The graph stays acyclic: iteration is entirely
+ * represented by this state machine and its per-iteration events.
+ */
+export async function runControlWhile({
+  initialState = null,
+  initialHistory = [],
+  initialElapsedMs = 0,
+  startIteration = null,
+  maxIterations = DEFAULT_CONTROL_WHILE_MAX_ITERATIONS,
+  timeoutMs = DEFAULT_CONTROL_WHILE_TIMEOUT_MS,
+  executeStep,
+  idempotencyKeyForIteration = null,
+  signal = null,
+  onIterationStart = null,
+  onIterationDone = null,
+  now = () => Date.now(),
+} = {}) {
+  if (typeof executeStep !== "function") throw new Error("control.while executeStep is required");
+  const history = normalizeControlWhileHistory(initialHistory);
+  const inferredStartIteration = history.length ? history[history.length - 1].iteration + 1 : 1;
+  const firstIteration = startIteration == null ? inferredStartIteration : Number(startIteration);
+  if (!Number.isInteger(firstIteration) || firstIteration < 1 || firstIteration !== inferredStartIteration) {
+    throw new Error("control.while startIteration must continue directly after checkpoint history");
+  }
+  const elapsedBeforeRun = Number(initialElapsedMs);
+  if (!Number.isFinite(elapsedBeforeRun) || elapsedBeforeRun < 0) {
+    throw new Error("control.while initialElapsedMs must be a non-negative number");
+  }
+  const startedAt = now();
+  let state = initialState;
+
+  for (let iteration = firstIteration; iteration <= maxIterations; iteration += 1) {
+    if (signal?.aborted) {
+      const error = new Error("Workspace run stopped");
+      error.code = "WORKSPACE_RUN_ABORTED";
+      throw error;
+    }
+    const elapsedBefore = elapsedBeforeRun + Math.max(0, now() - startedAt);
+    const remainingMs = timeoutMs - elapsedBefore;
+    if (remainingMs <= 0) return {
+      decision: "fail",
+      state,
+      summary: `Reached timeout after ${timeoutMs}ms`,
+      iterations: history.length ? history[history.length - 1].iteration : firstIteration - 1,
+      history,
+      reason: "timeout",
+    };
+
+    const idempotencyKey = typeof idempotencyKeyForIteration === "function"
+      ? String(idempotencyKeyForIteration({ iteration, state }) || "")
+      : "";
+    onIterationStart?.({ iteration, state, elapsedMs: elapsedBefore, remainingMs, idempotencyKey });
+    const iterationStartedAt = now();
+    const controller = new AbortController();
+    let timedOut = false;
+    const abortFromParent = () => controller.abort(signal?.reason);
+    signal?.addEventListener("abort", abortFromParent, { once: true });
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort(controlWhileTimeoutError(timeoutMs));
+    }, remainingMs);
+
+    let raw;
+    try {
+      raw = await executeStep({ iteration, state, remainingMs, signal: controller.signal, idempotencyKey });
+    } catch (error) {
+      if (signal?.aborted) {
+        const stopped = new Error("Workspace run stopped");
+        stopped.code = "WORKSPACE_RUN_ABORTED";
+        throw stopped;
+      }
+      if (timedOut) return {
+        decision: "fail",
+        state,
+        summary: `Reached timeout after ${timeoutMs}ms`,
+        iterations: history.length ? history[history.length - 1].iteration : firstIteration - 1,
+        history,
+        reason: "timeout",
+      };
+      throw error;
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abortFromParent);
+    }
+
+    const step = parseControlWhileStepResult(raw, state);
+    state = step.state;
+    const entry = {
+      iteration,
+      decision: step.decision,
+      summary: step.summary,
+      elapsedMs: Math.max(0, now() - iterationStartedAt),
+      ...(idempotencyKey ? { idempotencyKey } : {}),
+    };
+    history.push(entry);
+    onIterationDone?.({ ...entry, state });
+
+    if (step.decision !== "continue") {
+      return {
+        decision: step.decision,
+        state,
+        summary: step.summary,
+        iterations: iteration,
+        history,
+        reason: step.decision,
+      };
+    }
+  }
+
+  return {
+    decision: "fail",
+    state,
+    summary: `Reached maxIterations (${maxIterations}) without done or wait`,
+    iterations: maxIterations,
+    history,
+    reason: "max_iterations",
+  };
+}

package/bin/lib/flow-dsl/codegen.mjs

@@ -64,6 +64,8 @@ function displayFileExt(kind) {
  */
 export function generateFlowSource(ir, opts = {}) {
   const N = ir.nodes;
+  const subflows = ir?.subflows && typeof ir.subflows === "object" ? ir.subflows : {};
+  const subflowMemberIds = new Set(Object.values(subflows).flatMap((subflow) => subflow?.nodeIds || []));
   const files = [];
   const emitFile = (rel, text) => {
     files.push({ path: rel, text });
@@ -153,7 +155,9 @@ export function generateFlowSource(ir, opts = {}) {
   const callee = (id) => bindingOf.get(id)?.name || apiCall(apiName(N[id].definitionId));
 
   const bodyTextOf = (id) => String(
-    (N[id].definitionId === "tool_nodejs" && N[id].script) ? N[id].script : (N[id].body || ""),
+    ((N[id].definitionId === "tool_nodejs" || N[id].definitionId === "control_while") && N[id].script)
+      ? N[id].script
+      : (N[id].body || ""),
   );
 
   /**
@@ -246,13 +250,14 @@ export function generateFlowSource(ir, opts = {}) {
   }
 
   // 把控制链展开成嵌套序列；分叉处变成数组，由 printItem 打成 flow.fork(...)
-  function expandChain(id) {
+  function expandChain(id, allowed = null) {
     const kids = (controlNext.get(id) || [])
       .filter((x) => !RUN_DEFINITIONS.has(N[x.to].definitionId))
+      .filter((x) => !allowed || allowed.has(x.to))
       .map((x) => x.to);
     if (isIf(id) || !kids.length) return [id];
-    if (kids.length === 1) return [id, ...expandChain(kids[0])];
-    return [id, kids.map(expandChain)];
+    if (kids.length === 1) return [id, ...expandChain(kids[0], allowed)];
+    return [id, kids.map((kid) => expandChain(kid, allowed))];
   }
   const collectIds = (seq, acc = []) => {
     for (const item of seq) {
@@ -268,16 +273,39 @@ export function generateFlowSource(ir, opts = {}) {
   );
 
   const declared = new Set();
+  const declaredSubflows = new Set();
   const out = [];
 
-  function chainFrom(roots) {
+  function chainFrom(roots, allowed = null) {
     const seq = roots.length === 1
-      ? expandChain(roots[0])
-      : (roots.length ? [roots.map(expandChain)] : []);
+      ? expandChain(roots[0], allowed)
+      : (roots.length ? [roots.map((root) => expandChain(root, allowed))] : []);
     for (const id of collectIds(seq)) declare(id, false);
     return seq;
   }
 
+  const outputRef = (nodeId, slot) => outVar.get(`${nodeId}|${slot}`) || `${nodeId}.${slot}`;
+
+  function declareSubflow(subflowId) {
+    if (declaredSubflows.has(subflowId)) return;
+    const subflow = subflows[subflowId];
+    if (!subflow) return;
+    declaredSubflows.add(subflowId);
+    const allowed = new Set(subflow.nodeIds || []);
+    for (const binding of Object.values(subflow.inputs || {})) declare(binding.nodeId, false);
+    const seq = chainFrom((subflow.roots || []).filter((id) => allowed.has(id)), allowed).map(printItem);
+    for (const binding of Object.values(subflow.outputs || {})) declare(binding.nodeId, false);
+    const inputEntries = Object.entries(subflow.inputs || {}).map(([name, binding]) => (
+      `${isIdentifier(name) ? name : JSON.stringify(name)}: ${binding.nodeId}`
+    ));
+    const outputEntries = Object.entries(subflow.outputs || {}).map(([name, binding]) => (
+      `${isIdentifier(name) ? name : JSON.stringify(name)}: ${outputRef(binding.nodeId, binding.slot)}`
+    ));
+    const inputObject = inputEntries.length ? `{ ${inputEntries.join(", ")} }` : "{}";
+    const outputObject = outputEntries.length ? `{ ${outputEntries.join(", ")} }` : "{}";
+    out.push(`export const ${subflowId} = ${apiCall("flow.subflow")}(${literal(subflow.label || subflowId)}, ${inputObject}, ${apiCall("flow")}(${seq.join(", ")}), ${outputObject});\n`);
+  }
+
   function declare(id, exported) {
     if (declared.has(id)) return;
     declared.add(id);
@@ -285,18 +313,50 @@ export function generateFlowSource(ir, opts = {}) {
     for (const dep of dataIn.get(id) || []) if (!declared.has(dep.from)) declare(dep.from, true);
 
     const node = N[id];
+    if (node.definitionId === "workspace_subflow_input") {
+      const name = String(node.attrs?.subflowInputName || node.label || id);
+      const type = String(node.attrs?.subflowInputType || node.packageDef?.output?.[0]?.type || "text");
+      out.push(`const ${id} = ${apiCall("flow.input")}(${literal(name)}, ${literal(type)});\n`);
+      return;
+    }
+    if (node.definitionId === "control_subflow_call") {
+      const subflowId = String(node.attrs?.subflowId || "");
+      declareSubflow(subflowId);
+      const args = [];
+      if (node.label) args.push(literal(node.label));
+      args.push(subflowId);
+      args.push(pinsObject(id));
+      out.push(`${exported ? "export " : ""}const ${id} = ${apiCall("flow.call")}(${args.join(", ")});\n`);
+      const bindings = (destructured.get(id) || []).map((slot) => {
+        const variable = outVar.get(`${id}|${slot}`);
+        return variable === slot ? slot : `${isIdentifier(slot) ? slot : JSON.stringify(slot)}: ${variable}`;
+      });
+      if (bindings.length) out.push(`const { ${bindings.join(", ")} } = ${id};\n`);
+      return;
+    }
     const folds = isIf(id) ? new Map() : bodyFolds(id);
     const args = [];
     if (node.label) args.push(literal(node.label));
     args.push(pinsObject(id, folds));
 
-    if (isIf(id)) {
+    const conditionSubflowId = node.definitionId === "control_while"
+      ? String(node.attrs?.conditionSubflowId || "")
+      : "";
+    const bodySubflowId = node.definitionId === "control_while"
+      ? String(node.attrs?.bodySubflowId || "")
+      : "";
+    if (conditionSubflowId || bodySubflowId) {
+      declareSubflow(conditionSubflowId);
+      declareSubflow(bodySubflowId);
+      args.push(conditionSubflowId || "undefined");
+      args.push(bodySubflowId || "undefined");
+    } else if (isIf(id)) {
       const thenIds = (controlNext.get(id) || []).filter((x) => x.slot === "next1").map((x) => x.to);
       const elseIds = (controlNext.get(id) || []).filter((x) => x.slot === "next2").map((x) => x.to);
       args.push(`${apiCall("flow")}(${chainFrom(thenIds).map(printItem).join(", ")})`);
       args.push(`${apiCall("flow")}(${chainFrom(elseIds).map(printItem).join(", ")})`);
     } else {
-      const usesScript = node.definitionId === "tool_nodejs" && node.script;
+      const usesScript = (node.definitionId === "tool_nodejs" || node.definitionId === "control_while") && node.script;
       const body = usesScript ? node.script : node.body;
       if (body) {
         args.push(folds.size
@@ -319,6 +379,9 @@ export function generateFlowSource(ir, opts = {}) {
 
   const ids = Object.keys(N).sort();
 
+  // 子流程先于父流程调用声明；内部节点仍是普通 DSL 节点，只是拥有独立作用域。
+  for (const subflowId of Object.keys(subflows).sort()) declareSubflow(subflowId);
+
   for (const runId of ids) {
     const definitionId = N[runId].definitionId;
     if (!RUN_DEFINITIONS.has(definitionId)) continue;
@@ -344,12 +407,12 @@ export function generateFlowSource(ir, opts = {}) {
   // 没有 run 入口、但自成控制链的孤儿链条——语料里真的有，丢掉就等于删图
   const controlTargets = new Set(ir.edges.map((e) => e.split("|")).filter((p) => p[3] === "prev").map((p) => p[2]));
   for (const id of ids) {
-    if (declared.has(id) || RUN_DEFINITIONS.has(N[id].definitionId) || controlTargets.has(id)) continue;
+    if (declared.has(id) || subflowMemberIds.has(id) || RUN_DEFINITIONS.has(N[id].definitionId) || controlTargets.has(id)) continue;
     if (!(controlNext.get(id) || []).length) continue;
     out.push(`${apiCall("flow.detached")}(${chainFrom([id]).map(printItem).join(", ")});\n`);
   }
   for (const id of ids) {
-    if (!declared.has(id) && !RUN_DEFINITIONS.has(N[id].definitionId)) declare(id, true);
+    if (!declared.has(id) && !subflowMemberIds.has(id) && !RUN_DEFINITIONS.has(N[id].definitionId)) declare(id, true);
   }
 
   const flowImports = flowApiRoots.map((root) => {

package/bin/lib/flow-dsl/ir.mjs

@@ -46,6 +46,11 @@ export const NODE_META_KEYS = [
   "marketplacePackageId",
   "marketplaceVersion",
   "sourceContextRunNodeId",
+  "subflowId",
+  "subflowInputName",
+  "subflowInputType",
+  "conditionSubflowId",
+  "bodySubflowId",
 ];
 
 function handleIndex(handle) {
@@ -100,6 +105,21 @@ export function graphToIr(graph) {
     node.extraIn = [];
     node.extraOut = [];
 
+    if (definitionId === "control_subflow_call" || definitionId === "workspace_subflow_input") {
+      node.packageDef = {
+        input: (instance.input || []).map((slot) => ({
+          name: String(slot?.name || ""),
+          type: String(slot?.type || "text"),
+          ...(slot?.required ? { required: true } : {}),
+        })).filter((slot) => slot.name),
+        output: (instance.output || []).map((slot) => ({
+          name: String(slot?.name || ""),
+          type: String(slot?.type || "text"),
+          ...(slot?.required ? { required: true } : {}),
+        })).filter((slot) => slot.name),
+      };
+    }
+
     for (const slot of instance.input || []) {
       const name = String(slot?.name || "");
       if (!name) continue;
@@ -144,7 +164,12 @@ export function graphToIr(graph) {
     };
   }
 
-  return { nodes, edges: [...new Set(edges)].sort(), slotOrder };
+  return {
+    nodes,
+    edges: [...new Set(edges)].sort(),
+    slotOrder,
+    subflows: graph?.subflows && typeof graph.subflows === "object" ? graph.subflows : {},
+  };
 }
 
 /**
@@ -299,7 +324,13 @@ export function irToGraph(ir, layout = { nodes: {} }, nodeMeta = { nodes: {} })
   }
   if (layout.viewport) ui.viewport = layout.viewport;
 
-  return { version: 1, instances, edges, ui };
+  return {
+    version: 1,
+    instances,
+    edges,
+    ui,
+    subflows: ir?.subflows && typeof ir.subflows === "object" ? ir.subflows : {},
+  };
 }
 
 export { CTRL_SLOTS, STD_SLOTS };