@fieldwangai/agentflow 0.1.149 → 0.1.154

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

@@ -0,0 +1,358 @@
+/**
+ * IR -> `workspace.flow.js`。
+ *
+ * 生成的是**受限 ESM**：只有 import、const 声明和调用表达式，没有控制流。这不是风格
+ * 选择——画布必须能靠静态解析渲染出来，绝不能为了画一张图去执行用户的代码。
+ *
+ * 图结构如何映射成代码：
+ *
+ * - 一个节点 = 一次 `const <nodeId> = <api>(label?, pins, body?)`
+ * - 控制边（连到 `prev` 的边）= `flow(a, b, c)` 里的参数顺序
+ * - 数据边 = 引脚对象里引用上游变量：`{ content: agent1.result }`
+ * - `control_if` 的两个分支 = 第 3、4 个参数 `flow(...)` / `flow(...)`
+ * - 控制流分叉 = `flow.fork(flow(...), flow(...))`
+ * - 运行入口 = `export const run = flow("Run", ...)`
+ *
+ * 超过 EXTERNALIZE_MIN 的长文本外置成独立文件，代码里写 `file("prompts/x.md")`：
+ * 一段 8 KB 的提示词塞进模板字符串会把流程结构淹没。
+ */
+import { CTRL_SLOTS, RUN_DEFINITIONS, apiName, definitionOf, isDisplayDefinition, isProvideDefinition } from "./defs.mjs";
+
+/** 长文本外置阈值（字节）。低于这个长度的直接内联，免得目录里全是碎文件。 */
+export const EXTERNALIZE_MIN = 3000;
+
+const isIdentifier = (s) => /^[A-Za-z_$][\w$]*$/.test(s);
+
+/**
+ * 短的普通文本用双引号；带引号、换行或过长的用模板字符串。
+ * 含 `"` 的内容（排程 JSON、带引号的提示词）走双引号会被转义成一片 `\"`，读不动。
+ */
+function literal(value) {
+  const text = String(value ?? "");
+  const inlineable = !text.includes("\n")
+    && text.length < 90
+    && !text.includes('"')
+    && !text.includes("`")
+    && !text.includes("${");
+  if (inlineable) return JSON.stringify(text);
+  return "`" + text.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${") + "`";
+}
+
+/**
+ * 把正文写成模板字符串，`folds` 里的占位符还原成 JS 插值。
+ *
+ * 没被折叠的 `${...}` 一律转义成 `\${...}`——那是运行时自己要解析的占位符，不是 JS 表达式。
+ */
+function interpolatedLiteral(text, folds) {
+  const escape = (s) => s.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$\{/g, "\\${");
+  const parts = String(text ?? "").split(/(\$\{[A-Za-z_][A-Za-z0-9_-]*\})/);
+  return `\`${parts.map((part) => {
+    const m = /^\$\{([A-Za-z_][A-Za-z0-9_-]*)\}$/.exec(part);
+    return m && folds.has(m[1]) ? `\${${folds.get(m[1])}}` : escape(part);
+  }).join("")}\``;
+}
+
+function displayFileExt(kind) {
+  return { html: "html", chart: "json", table: "json", mermaid: "mmd", ascii: "txt", react: "json" }[kind] || "md";
+}
+
+/**
+ * @param {object} ir
+ * @param {{ packages?: Record<string, {binding?: string, specifier: string}> }} [opts]
+ *        packages：nodeId -> 代码节点包，生成 `import x from "./nodes/x"` 并用绑定名做调用
+ * @returns {{ source: string, files: Array<{path: string, text: string}> }}
+ */
+export function generateFlowSource(ir, opts = {}) {
+  const N = ir.nodes;
+  const files = [];
+  const emitFile = (rel, text) => {
+    files.push({ path: rel, text });
+    return rel;
+  };
+
+  // 同一个节点的 body 和某个引脚值可能都超阈值，文件名必须带槽名区分：都叫
+  // `prompts/<id>.md` 的话两段不同的文本会写进同一个文件，往返时后写的覆盖先写的。
+  const externalize = (id, slot, text) => {
+    if (text.length < EXTERNALIZE_MIN) return null;
+    const definitionId = N[id].definitionId;
+    const suffix = slot === "$body" || slot === "$script" ? "" : `.${slot.replace(/[^\w.-]/g, "_")}`;
+    if (isDisplayDefinition(definitionId)) {
+      return emitFile(`docs/${id}${suffix}.${displayFileExt(definitionId.slice("display_".length))}`, text);
+    }
+    return emitFile(slot === "$script" ? `scripts/${id}.sh` : `prompts/${id}${suffix}.md`, text);
+  };
+  const textArg = (id, slot, text) => {
+    const rel = externalize(id, slot, text);
+    return rel ? `file(${JSON.stringify(rel)})` : literal(text);
+  };
+
+  const controlNext = new Map();
+  const dataIn = new Map();
+  for (const key of ir.edges) {
+    const [src, fromSlot, dst, toSlot] = key.split("|");
+    if (toSlot === "prev") {
+      if (!controlNext.has(src)) controlNext.set(src, []);
+      controlNext.get(src).push({ to: dst, slot: fromSlot });
+    } else {
+      if (!dataIn.has(dst)) dataIn.set(dst, []);
+      dataIn.get(dst).push({ slot: toSlot, from: src, fromSlot });
+    }
+  }
+
+  const isIf = (id) => N[id]?.definitionId === "control_if";
+
+  // 代码节点包自己声明了输出槽，import 已经把它们带进来，不必解构；引用时直接写
+  // `pkgNode.total`。这个集合必须先算，`outVar` 只收真的会被解构出来的槽——否则会生成
+  // 一个引用了不存在变量的文件。
+  const packageOutputs = (id) => new Set(
+    (opts.packages?.[id]?.output || []).map((slot) => String(slot?.name || "")),
+  );
+  const destructured = new Map(
+    Object.entries(N).map(([id, node]) => {
+      const declared = packageOutputs(id);
+      return [id, node.extraOut.filter((slot) => !declared.has(slot))];
+    }),
+  );
+
+  // 文件里所有顶层标识符共用一个命名空间：节点 id、解构出来的输出变量、import 绑定名。
+  // 分开发号就会撞——两个节点各有一个叫 ok 的自定义输出槽，是完全正常的图，但会生成两条
+  // `const { ok } = ...`，文件根本解析不回来。
+  const taken = new Set(Object.keys(N));
+  const uniqueName = (base, fallback) => {
+    let name = isIdentifier(base) ? base : fallback;
+    if (taken.has(name)) name = fallback;
+    while (taken.has(name)) name += "_";
+    taken.add(name);
+    return name;
+  };
+
+  // 自定义输出槽通过解构暴露成变量：`const { storyId } = node;`
+  const outVar = new Map();
+  for (const [id, slots] of destructured) {
+    for (const slot of slots) {
+      outVar.set(`${id}|${slot}`, uniqueName(slot, `${id}_${slot}`.replace(/[^\w$]/g, "_")));
+    }
+  }
+
+  // 代码节点包的 import 绑定名
+  const bindingOf = new Map();
+  for (const [id, pkg] of Object.entries(opts.packages || {})) {
+    const base = pkg.binding
+      || pkg.specifier.split("/").pop().replace(/[-.](\w)/g, (_, c) => c.toUpperCase());
+    // 同一个包在多个节点上共用一个绑定名，别重复发号
+    const shared = [...bindingOf.values()].find((v) => v.spec === pkg.specifier);
+    bindingOf.set(id, shared || { name: uniqueName(base, `${base}Node`), spec: pkg.specifier });
+  }
+  const callee = (id) => bindingOf.get(id)?.name || apiName(N[id].definitionId);
+
+  const bodyTextOf = (id) => String(
+    (N[id].definitionId === "tool_nodejs" && N[id].script) ? N[id].script : (N[id].body || ""),
+  );
+
+  /**
+   * 正文里的 `${slot}` 占位符能写回成 JS 插值的那些槽。
+   *
+   * 条件很紧：引用表达式的**根标识符**必须和槽名一致。`{ date: date.value }` + 正文
+   * `${date}` 可以折叠成 `` `${date.value}` ``；而 `{ d: date.value }` 不行——解析器只能
+   * 从 `${date.value}` 推出槽名 `date`，折叠了就往返不回来。
+   */
+  function bodyFolds(id) {
+    const text = bodyTextOf(id);
+    // 正文超阈值会被外置成文件，文件里没有 JS 插值这回事
+    if (!text || text.length >= EXTERNALIZE_MIN) return new Map();
+    const candidates = new Map();
+    for (const x of dataIn.get(id) || []) {
+      if (!text.includes(`\${${x.slot}}`)) continue;
+      const ref = outVar.get(`${x.from}|${x.fromSlot}`) || `${x.from}.${x.fromSlot}`;
+      if (ref.split(".")[0] !== x.slot) continue;
+      candidates.set(x.slot, ref);
+    }
+    if (!candidates.size) return candidates;
+
+    // 定义表里的槽永远按定义顺序重建，折不折都在原位；自定义槽不一样——折进正文之后，
+    // 解析回来是「按正文里出现的先后追加到末尾」。所以自定义槽只能折**末尾那一段**，
+    // 而且那段的正文顺序要和槽序一致。否则往返一次槽序就变了，闸门会把整张图退回 JSON。
+    const extras = N[id].extraIn;
+    const folds = new Map([...candidates].filter(([slot]) => !extras.includes(slot)));
+    const atBody = (slot) => text.indexOf(`\${${slot}}`);
+    for (let k = extras.length; k > 0; k -= 1) {
+      const tail = extras.slice(-k);
+      if (!tail.every((slot) => candidates.has(slot))) continue;
+      const byBody = [...tail].sort((a, b) => atBody(a) - atBody(b));
+      if (JSON.stringify(byBody) !== JSON.stringify(tail)) continue;
+      for (const slot of tail) folds.set(slot, candidates.get(slot));
+      break;
+    }
+    return folds;
+  }
+
+  const pkgSlots = (id, kind) => (opts.packages?.[id]?.[kind] || []);
+  const slotTypeOf = (id, name) => {
+    const node = N[id];
+    const fromPkg = pkgSlots(id, "input").find((s) => s?.name === name);
+    if (fromPkg?.type) return String(fromPkg.type);
+    const fromDef = definitionOf(node.definitionId).input.find((s) => s.name === name);
+    if (fromDef?.type) return String(fromDef.type);
+    return String(node.inputTypes?.[name] || "text");
+  };
+  /** bool 槽写回成裸 `true` / `false`；其余一律是文本。 */
+  const pinValue = (id, name, value) => {
+    const text = String(value);
+    if (slotTypeOf(id, name) === "bool" && (text === "true" || text === "false")) return text;
+    return textArg(id, name, text);
+  };
+
+  function pinsObject(id, folds = new Map()) {
+    const node = N[id];
+    const def = definitionOf(node.definitionId);
+    const lines = [];
+    const wired = new Map((dataIn.get(id) || []).filter((x) => !folds.has(x.slot)).map((x) => [x.slot, x]));
+    const order = [...def.input.map((s) => s.name).filter((n) => !CTRL_SLOTS.has(n)), ...node.extraIn];
+    const seen = new Set();
+    for (const name of order) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      // 已经折进正文插值里的槽不再出现在引脚对象里；写两遍等于同一条边写两次
+      if (folds.has(name)) continue;
+      const key = isIdentifier(name) ? name : JSON.stringify(name);
+      if (wired.has(name)) {
+        const x = wired.get(name);
+        lines.push(`${key}: ${outVar.get(`${x.from}|${x.fromSlot}`) || `${x.from}.${x.fromSlot}`}`);
+        continue;
+      }
+      if (node.inputs[name] !== undefined) {
+        lines.push(`${key}: ${pinValue(id, name, node.inputs[name])}`);
+        continue;
+      }
+      // 声明了但没接线也没默认值的自定义槽写成 null，否则解析回来会丢掉这个槽
+      if (node.extraIn.includes(name)) lines.push(`${key}: null`);
+    }
+    for (const [name, value] of Object.entries(node.inputs)) {
+      if (!seen.has(name) && !folds.has(name)) lines.push(`${name}: ${pinValue(id, name, value)}`);
+    }
+    if (isProvideDefinition(node.definitionId)) {
+      for (const [name, value] of Object.entries(node.outputs)) {
+        lines.push(`${name}: ${textArg(id, name, String(value))}`);
+      }
+    }
+    return lines.length ? `{\n${lines.map((l) => `  ${l}`).join(",\n")},\n}` : "{}";
+  }
+
+  // 把控制链展开成嵌套序列；分叉处变成数组，由 printItem 打成 flow.fork(...)
+  function expandChain(id) {
+    const kids = (controlNext.get(id) || [])
+      .filter((x) => !RUN_DEFINITIONS.has(N[x.to].definitionId))
+      .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)];
+  }
+  const collectIds = (seq, acc = []) => {
+    for (const item of seq) {
+      if (Array.isArray(item)) item.forEach((s) => collectIds(s, acc));
+      else acc.push(item);
+    }
+    return acc;
+  };
+  const printItem = (item) => (
+    Array.isArray(item)
+      ? `flow.fork(${item.map((s) => `flow(${s.map(printItem).join(", ")})`).join(", ")})`
+      : item
+  );
+
+  const declared = new Set();
+  const out = [];
+
+  function chainFrom(roots) {
+    const seq = roots.length === 1
+      ? expandChain(roots[0])
+      : (roots.length ? [roots.map(expandChain)] : []);
+    for (const id of collectIds(seq)) declare(id, false);
+    return seq;
+  }
+
+  function declare(id, exported) {
+    if (declared.has(id)) return;
+    declared.add(id);
+    // 上游数据依赖必须先声明，否则引用的变量还不存在
+    for (const dep of dataIn.get(id) || []) if (!declared.has(dep.from)) declare(dep.from, true);
+
+    const node = N[id];
+    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 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(`flow(${chainFrom(thenIds).map(printItem).join(", ")})`);
+      args.push(`flow(${chainFrom(elseIds).map(printItem).join(", ")})`);
+    } else {
+      const usesScript = node.definitionId === "tool_nodejs" && node.script;
+      const body = usesScript ? node.script : node.body;
+      if (body) {
+        args.push(folds.size
+          ? interpolatedLiteral(body, folds)
+          : textArg(id, usesScript ? "$script" : "$body", String(body)));
+      }
+    }
+
+    out.push(`${exported ? "export " : ""}const ${id} = ${callee(id)}(${args.join(", ")});\n`);
+    const needsBinding = destructured.get(id) || [];
+    if (needsBinding.length) {
+      const bindings = needsBinding.map((slot) => {
+        const v = outVar.get(`${id}|${slot}`);
+        if (v === slot) return slot;
+        return `${isIdentifier(slot) ? slot : JSON.stringify(slot)}: ${v}`;
+      });
+      out.push(`const { ${bindings.join(", ")} } = ${id};\n`);
+    }
+  }
+
+  const ids = Object.keys(N).sort();
+
+  for (const runId of ids) {
+    const definitionId = N[runId].definitionId;
+    if (!RUN_DEFINITIONS.has(definitionId)) continue;
+    const roots = (controlNext.get(runId) || [])
+      .filter((x) => !RUN_DEFINITIONS.has(N[x.to].definitionId))
+      .map((x) => x.to);
+    const seq = chainFrom(roots).map(printItem);
+    const head = [];
+    if (N[runId].label) head.push(literal(N[runId].label));
+    // 排程配置存在 run 节点的 body 里，是 JSON 字符串
+    if (definitionId === "workspace_scheduled_run") head.push(N[runId].body ? literal(N[runId].body) : "null");
+    const fn = definitionId === "workspace_scheduled_run" ? "flow.schedule" : "flow";
+    out.push(`export const ${runId} = ${fn}(${[...head, ...seq].join(", ")});\n`);
+  }
+
+  // 一个 run 直接连到另一个 run：接力，不是子图
+  for (const [src, list] of [...controlNext].sort()) {
+    for (const x of list) {
+      if (RUN_DEFINITIONS.has(N[x.to].definitionId)) out.push(`flow.resume(${src}, ${x.to});\n`);
+    }
+  }
+
+  // 没有 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 (!(controlNext.get(id) || []).length) continue;
+    out.push(`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);
+  }
+
+  const imports = [`import { agent, control, display, file, flow, provide, tool, workspace } from "agentflow/flow";`];
+  const seenBinding = new Set();
+  for (const id of ids) {
+    const binding = bindingOf.get(id);
+    if (!binding || seenBinding.has(binding.name)) continue;
+    seenBinding.add(binding.name);
+    imports.push(`import ${binding.name} from ${JSON.stringify(binding.spec)};`);
+  }
+
+  return { source: `${imports.join("\n")}\n\n${out.join("\n")}`, files };
+}

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

@@ -0,0 +1,103 @@
+/**
+ * DSL 用的节点定义表与 API 名映射。
+ *
+ * 定义表来自 `builtin/nodes/*.md`——与节点面板同一个来源（见
+ * docs/wiki/node-definitions.zh-CN.md），因此 DSL 认识的节点集合与用户能拖出来的
+ * 节点集合天然一致，不存在第二份清单。
+ */
+import fs from "fs";
+import path from "path";
+
+import { PACKAGE_BUILTIN_NODES_DIR } from "../paths.mjs";
+import { parseNodeFrontmatter } from "../catalog-flows.mjs";
+
+/** 控制槽：连这些槽的边表示执行顺序，不是数据流。 */
+export const CTRL_SLOTS = new Set(["prev", "next", "next1", "next2"]);
+
+/**
+ * 标准槽：控制槽 + 运行时统一注入的上下文槽。
+ * 这些名字不算「自定义槽」，代码里不必声明。
+ */
+export const STD_SLOTS = new Set([
+  ...CTRL_SLOTS,
+  "workspaceContext",
+  "skillsContext",
+  "mcpContext",
+  "knowledgeContext",
+  "gitContext",
+]);
+
+/** 运行入口节点——DSL 里对应 `flow()` / `flow.schedule()`，不是普通节点调用。 */
+export const RUN_DEFINITIONS = new Set(["workspace_run", "workspace_scheduled_run"]);
+
+export const isDisplayDefinition = (id) => String(id || "").startsWith("display_");
+export const isProvideDefinition = (id) => String(id || "").startsWith("provide_");
+
+/** 槽是否是控制槽（按类型或按名字，两者都要认——语料里两种写法都有）。 */
+export const isControlSlot = (slot) =>
+  String(slot?.type) === "node" || CTRL_SLOTS.has(String(slot?.name));
+
+function loadDefinitions(dir) {
+  const out = {};
+  if (!fs.existsSync(dir)) return out;
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith(".md")) continue;
+    const meta = parseNodeFrontmatter(fs.readFileSync(path.join(dir, file), "utf-8"));
+    out[file.slice(0, -3)] = { input: meta.input, output: meta.output, runtime: meta.runtime };
+  }
+  return out;
+}
+
+export const DEFINITIONS = loadDefinitions(PACKAGE_BUILTIN_NODES_DIR);
+
+/**
+ * definitionId -> DSL 调用名。多数是 `前缀_驼峰` 的机械转换，少数缩写要显式列出，
+ * 否则 `control_cd_workspace` 会变成 `control.cdWorkspace` 的错拼。
+ */
+const API_OVERRIDES = {
+  control_agent_toBool: "control.agentToBool",
+  control_cd_workspace: "control.cdWorkspace",
+  control_user_workspace: "control.userWorkspace",
+  control_load_skills: "control.loadSkills",
+  control_load_mcp: "control.loadMcp",
+  control_toBool: "control.toBool",
+  control_anyOne: "control.anyOne",
+  tool_nodejs: "tool.nodejs",
+  workspace_one_click_task: "workspace.oneClickTask",
+};
+
+function deriveApiName(definitionId) {
+  if (API_OVERRIDES[definitionId]) return API_OVERRIDES[definitionId];
+  const at = definitionId.indexOf("_");
+  if (at < 0) return definitionId;
+  const tail = definitionId.slice(at + 1).replace(/_([a-zA-Z])/g, (_, c) => c.toUpperCase());
+  return `${definitionId.slice(0, at)}.${tail}`;
+}
+
+const API_BY_DEFINITION = {};
+const DEFINITION_BY_API = {};
+const collisions = [];
+for (const definitionId of Object.keys(DEFINITIONS)) {
+  const name = deriveApiName(definitionId);
+  if (DEFINITION_BY_API[name] && DEFINITION_BY_API[name] !== definitionId) {
+    collisions.push(`${name}: ${DEFINITION_BY_API[name]} vs ${definitionId}`);
+  }
+  API_BY_DEFINITION[definitionId] = name;
+  DEFINITION_BY_API[name] = definitionId;
+}
+
+/**
+ * definitionId <-> DSL 名必须是双射，否则解析回来会指向错误的节点类型。
+ * 新增节点定义撞名时在这里直接炸掉，而不是等到某张图被静默解析错。
+ */
+export const API_NAME_COLLISIONS = collisions;
+if (collisions.length) {
+  throw new Error(`DSL 节点调用名冲突：${collisions.join("; ")}`);
+}
+
+export const apiName = (definitionId) => API_BY_DEFINITION[definitionId] || deriveApiName(definitionId);
+export const definitionIdFromApi = (name) => DEFINITION_BY_API[name] || String(name).replace(".", "_");
+
+export function definitionOf(definitionId) {
+  return DEFINITIONS[definitionId] || { input: [], output: [], runtime: "native" };
+}

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

@@ -0,0 +1,77 @@
+/**
+ * Workspace 图的代码化表示。
+ *
+ * 一张图落成四个文件：
+ *
+ * ```
+ * workspace.flow.js       图结构——节点、连线、作者写的内容（受限 ESM）
+ * workspace.layout.json   画布状态——坐标、尺寸、引脚显隐与顺序
+ * workspace.nodes.json    代码里说不清的节点级数据——粘贴的图片、机器管理属性
+ * workspace.state.json    运行态——由 workspace-state.mjs 负责，这里只是路过
+ * prompts/ docs/ scripts/ 超过 3 KB 的长文本
+ * ```
+ *
+ * 为什么是代码而不是 JSON：流程编排本质上就是「main 调用一串 func、连线传数据」。
+ * 写成代码，AI 的编码能力可以直接用上，lint 能做语法校验，diff 能看懂。而 JSON 里
+ * 一条 `output-1 -> input-2` 的边，人和模型都读不出它连的是什么。
+ *
+ * 全流程**不执行**流程文件：acorn 静态解析。
+ */
+import { splitWorkspaceGraph } from "../workspace-state.mjs";
+import { generateFlowSource } from "./codegen.mjs";
+import { extractLayout } from "./layout.mjs";
+import { graphToIr, irToGraph } from "./ir.mjs";
+import { parseFlowSource } from "./parser.mjs";
+
+export const FLOW_SOURCE_FILENAME = "workspace.flow.js";
+export const FLOW_LAYOUT_FILENAME = "workspace.layout.json";
+export const FLOW_NODES_FILENAME = "workspace.nodes.json";
+
+export { EXTERNALIZE_MIN } from "./codegen.mjs";
+export { DEFINITIONS, apiName, definitionIdFromApi } from "./defs.mjs";
+export { graphToIr, irToGraph } from "./ir.mjs";
+export { generateFlowSource } from "./codegen.mjs";
+export { parseFlowSource } from "./parser.mjs";
+
+/**
+ * 完整图 -> 代码化的一组文件。
+ *
+ * 运行态先由 `splitWorkspaceGraph` 摘出去，DSL 只面对设计态；这样代码里不会混进
+ * 上次运行的产出。
+ *
+ * @param {object} graph 完整图（design + state 合并后的形态）
+ * @param {{ packages?: Record<string, {binding?: string, specifier: string}> }} [opts]
+ * @returns {{ source: string, layout: object, nodeMeta: object, state: object, files: Array<{path: string, text: string}> }}
+ */
+export function graphToFlowFiles(graph, opts = {}) {
+  const { design, state } = splitWorkspaceGraph(graph);
+  const ir = graphToIr(design);
+  const { source, files } = generateFlowSource(ir, opts);
+  const { layout, nodeMeta } = extractLayout(design, ir);
+  return { source, layout, nodeMeta, state, files };
+}
+
+/**
+ * 代码化的一组文件 -> 设计态图。
+ *
+ * 返回的是设计态；要拿到完整图，再用 `mergeWorkspaceState(design, state)` 合上运行态。
+ *
+ * 默认是**严格模式**：解析器认不出的语句会抛错，而不是当它不存在。这是作为存储格式的
+ * 底线——静默丢一条语句，等于用户下一次保存时那部分图就没了。只想「尽力读出能读的部分」
+ * 时（lint 要把问题一次列全）传 `strict: false`。
+ *
+ * @param {{ source: string, layout?: object, nodeMeta?: object, files?: Array<{path:string,text:string}>|Record<string,string>, resolvePackage?: Function, strict?: boolean }} input
+ * @returns {object} 设计态图
+ */
+export function flowFilesToGraph(input) {
+  const files = Array.isArray(input.files)
+    ? Object.fromEntries(input.files.map((f) => [f.path, f.text]))
+    : (input.files || {});
+  const ir = parseFlowSource(input.source, { files, resolvePackage: input.resolvePackage });
+  if (input.strict !== false && ir.unresolved.length) {
+    const shown = ir.unresolved.slice(0, 5).map((u) => `第 ${u.line} 行：${u.message}`);
+    const more = ir.unresolved.length > shown.length ? `（还有 ${ir.unresolved.length - shown.length} 处）` : "";
+    throw new Error(`有 ${ir.unresolved.length} 处内容解析不出图结构${more}\n  ${shown.join("\n  ")}`);
+  }
+  return irToGraph(ir, input.layout || { nodes: {} }, input.nodeMeta || { nodes: {} });
+}