@fieldwangai/agentflow 0.1.153 → 0.1.156

package/bin/lib/composer-skill-router.mjs

@@ -1,17 +1,9 @@
 /**
- * Composer Skill Router：基于用户输入意图动态加载 SKILL.md 和 reference 文档。
+ * Composer Skill Router：按用户在 Workspace Composer 中显式勾选的 skill key
+ * 加载 SKILL.md 及其引用的 reference 文档，并渲染成可注入 prompt 的文本块。
  *
- * 意图分类：
- *   query-explain  — 纯问答/解释（不修改文件）
- *   add-instances  — 新增节点/实例
- *   edit-fields    — 改已有节点内容
- *   optimize-flow  — 优化/重构整体流程
- *   optimize-nodes — 优化特定节点 prompt / body
- *   create-flow    — 从零创建新流程
- *
- * 每种意图映射到需要注入的 skills 和 reference 文档。
+ * 旧的「按 prompt 猜意图自动注入」随 Start/End Pipeline Composer 一并下线。
  */
-import fs from "fs";
 import path from "path";
 import {
   listSkills as registryListSkills,
@@ -19,116 +11,6 @@ import {
   readSkillDetail as registryReadSkillDetail,
 } from "./skill-registry.mjs";
 
-// ─── 意图模式定义 ─────────────────────────────────────────────────────────
-
-const INTENT_PATTERNS = [
-  {
-    id: "query-explain",
-    patterns: [
-      // 纯问答：问什么/怎么/为什么/是否/有没有
-      /^(?:这个|该|当前|选中)?.*(?:是什么|是啥|啥意思|怎么(?:工作|运行|执行|回事)|为什么|为啥|哪些|有没有|有多少|能不能|是否|如何|有什么)/i,
-      // 动词主导：解释/说明/介绍/查看/展示/分析
-      /(?:解释|说明|介绍|描述|分析|查看|看看|展示|显示|告诉|帮我看|帮我理解)/i,
-      // 名词主导：逻辑/作用/功能/原理
-      /(?:逻辑|作用|功能|用途|含义|意义|目的|原理|机制|区别|流程图|概览|概述).*(?:是|呢|吗|？|\?)/i,
-      // 英文
-      /(?:explain|describe|what\s+(?:does|is|are)|how\s+does|why\s+(?:does|is)|show\s+me|tell\s+me|walk.*through)/i,
-      // "X的逻辑/功能/作用"
-      /(?:脚本|script|body|prompt|代码|内容|节点|node).{0,15}(?:是什么|什么意思|做什么|干什么|逻辑|功能|作用|怎么样)/i,
-    ],
-  },
-  {
-    id: "create-flow",
-    patterns: [
-      /(?:新建|创建|新增|生成|搭建|设计).*(?:流程|流水线|pipeline|flow|agentflow)/i,
-      /(?:从零|从头|从无到有).*(?:搭|建|写|做)/i,
-      /create\s+(?:a\s+)?(?:new\s+)?(?:flow|pipeline)/i,
-    ],
-  },
-  {
-    id: "add-instances",
-    patterns: [
-      /(?:新增|添加|加入|插入|增加|加个|加一个|补充|补一个).*(?:节点|实例|node|instance|步骤|环节)/i,
-      /(?:加|添|增|补).*(?:分支|条件|判断|循环|环|if|toBool|agent_toBool|anyOne)/i,
-      /add\s+(?:a\s+)?(?:new\s+)?(?:node|instance|step)/i,
-    ],
-  },
-  {
-    id: "edit-fields",
-    patterns: [
-      /(?:改|修改|更新|调整|编辑|更换|换成|设为|设置|改为|替换|重写).*(?:节点|label|body|role|标签|名称|角色|内容|描述|文案|prompt|提示词|输入|输出|value|值)/i,
-      /(?:节点|label|body|role|标签|角色|内容|文案|prompt|提示词).*(?:改|修改|更新|调整|编辑|换|设|替换|重写)/i,
-      /edit\s+(?:node|label|body|role|content)/i,
-      /(?:把|将).{0,30}(?:改成|换成|设为|更新为|修改为|替换为)/i,
-    ],
-  },
-  {
-    id: "optimize-nodes",
-    patterns: [
-      /(?:优化|改善|提升|改进|完善|精炼|润色|增强).*(?:节点|node|body|prompt|提示词|描述|文案|内容)/i,
-      /(?:节点|node|body|prompt|提示词).*(?:优化|改善|提升|改进|完善|精炼|润色|增强)/i,
-      /(?:让|使).{0,20}(?:节点|node|prompt|body).{0,20}(?:更好|更准|更清晰|更高效)/i,
-      /optimize\s+(?:node|prompt|body)/i,
-    ],
-  },
-  {
-    id: "optimize-flow",
-    patterns: [
-      /(?:优化|改善|提升|改进|完善|重构|重新设计|简化|精简).*(?:流程|流水线|pipeline|flow|拓扑|结构|架构|整体)/i,
-      /(?:流程|流水线|pipeline|flow|拓扑|结构|架构|整体).*(?:优化|改善|提升|改进|完善|重构|重新设计|简化|精简)/i,
-      /(?:重新|重).*(?:规划|设计|组织|编排).*(?:流程|节点|步骤)/i,
-      /optimize\s+(?:flow|pipeline|topology)/i,
-      /refactor/i,
-    ],
-  },
-];
-
-// 意图 → 需要加载的 skills 和 references
-const INTENT_RESOURCES = {
-  "query-explain": {
-    skills: [],
-    references: [],
-  },
-  "create-flow": {
-    skills: ["agentflow-flow-add-instances"],
-    references: ["flow-control-capabilities.md", "flow-layout.md"],
-  },
-  "add-instances": {
-    skills: ["agentflow-flow-add-instances"],
-    references: ["flow-control-capabilities.md", "flow-layout.md"],
-  },
-  "edit-fields": {
-    skills: ["agentflow-flow-edit-node-fields"],
-    references: ["flow-prompt-handler-check.md"],
-  },
-  "optimize-nodes": {
-    skills: ["agentflow-flow-edit-node-fields", "agentflow-flow-add-instances"],
-    references: ["flow-prompt-handler-check.md", "flow-control-capabilities.md"],
-  },
-  "optimize-flow": {
-    skills: ["agentflow-flow-add-instances", "agentflow-flow-edit-node-fields"],
-    references: ["flow-control-capabilities.md", "flow-layout.md", "flow-prompt-handler-check.md"],
-  },
-};
-
-// ─── 文件缓存 ─────────────────────────────────────────────────────────────
-
-const _fileCache = new Map();
-const CACHE_TTL_MS = 60_000;
-
-function readFileCached(absPath) {
-  const now = Date.now();
-  const cached = _fileCache.get(absPath);
-  if (cached && now - cached.ts < CACHE_TTL_MS) return cached.content;
-  try {
-    const content = fs.readFileSync(absPath, "utf-8");
-    _fileCache.set(absPath, { content, ts: now });
-    return content;
-  } catch {
-    return null;
-  }
-}
-
 export function listComposerSkills(packageRoot, workspaceRoot) {
   return registryListUniqueSkills(packageRoot, workspaceRoot).map(({ body, content, ...skill }) => skill);
 }
@@ -187,84 +69,6 @@ export function loadResourcesForSkillKeys(skillKeys, packageRoot, workspaceRoot)
   };
 }
 
-// ─── 意图检测 ─────────────────────────────────────────────────────────────
-
-/**
- * 分析用户输入，返回匹配的意图 ID 列表（按优先级排序，去重）。
- * 可能返回多个意图（如"优化节点并新增一个分支"同时匹配 optimize-nodes 和 add-instances）。
- * @param {string} userPrompt
- * @returns {string[]}
- */
-export function detectIntents(userPrompt) {
-  if (!userPrompt || typeof userPrompt !== "string") return [];
-  const text = userPrompt.trim();
-  if (!text) return [];
-
-  const matched = [];
-  for (const { id, patterns } of INTENT_PATTERNS) {
-    for (const re of patterns) {
-      if (re.test(text)) {
-        matched.push(id);
-        break;
-      }
-    }
-  }
-  return [...new Set(matched)];
-}
-
-// ─── 加载 skill 和 reference 内容 ─────────────────────────────────────────
-
-/**
- * 根据意图列表加载对应的 SKILL.md 和 reference 文档内容。
- *
- * @param {string[]} intents - detectIntents 返回的意图 ID 列表
- * @param {string} packageRoot - AgentFlow 包根目录
- * @returns {{ skills: Array<{id: string, content: string}>, references: Array<{name: string, content: string}>, skillsHint: string, hasContext: boolean }}
- */
-export function loadResourcesForIntents(intents, packageRoot) {
-  if (!intents || intents.length === 0) {
-    return { skills: [], references: [], skillsHint: "", hasContext: false };
-  }
-
-  const skillIds = new Set();
-  const refNames = new Set();
-
-  for (const intent of intents) {
-    const res = INTENT_RESOURCES[intent];
-    if (!res) continue;
-    for (const s of res.skills) skillIds.add(s);
-    for (const r of res.references) refNames.add(r);
-  }
-
-  const skills = [];
-  for (const id of skillIds) {
-    const absPath = path.join(packageRoot, "skills", id, "SKILL.md");
-    const content = readFileCached(absPath);
-    if (content) {
-      const body = stripFrontmatter(content);
-      skills.push({ id, content: body, absPath });
-    }
-  }
-
-  const references = [];
-  for (const name of refNames) {
-    const absPath = path.join(packageRoot, "reference", name);
-    const content = readFileCached(absPath);
-    if (content) {
-      references.push({ name, content, absPath });
-    }
-  }
-
-  const skillsHint = buildSkillsHint(intents, skills, references);
-
-  return {
-    skills,
-    references,
-    skillsHint,
-    hasContext: skills.length > 0 || references.length > 0,
-  };
-}
-
 // ─── 构建注入到 prompt 的文本块 ───────────────────────────────────────────
 
 // 已知 reference / skill 的一行摘要（compact 模式注入）
@@ -304,75 +108,6 @@ export function buildSkillCompactInjectionBlock(skills, references) {
   return parts.join("\n");
 }
 
-/**
- * 为单步 prompt 构建完整的 skill + reference 注入块。
- * @param {Array<{id: string, content: string}>} skills
- * @param {Array<{name: string, content: string}>} references
- * @returns {string}
- */
-export function buildSkillInjectionBlock(skills, references) {
-  const parts = [];
-  if ((skills?.length || 0) + (references?.length || 0) > 8) {
-    return buildSkillCompactInjectionBlock(skills || [], references || []);
-  }
-
-  if (skills.length > 0) {
-    parts.push("### 相关编辑技能（请严格遵循）");
-    parts.push("");
-    for (const s of skills) {
-      parts.push(`<skill name="${s.id}">`);
-      parts.push(s.content.trim());
-      parts.push("</skill>");
-      parts.push("");
-    }
-  }
-
-  if (references.length > 0) {
-    parts.push("### 参考文档");
-    parts.push("");
-    for (const r of references) {
-      parts.push(`<reference name="${r.name}">`);
-      parts.push(r.content.trim());
-      parts.push("</reference>");
-      parts.push("");
-    }
-  }
-
-  return parts.join("\n");
-}
-
-/**
- * 为多步模式的 flowContext.skillsHint 构建精简版。
- */
-function buildSkillsHint(intents, skills, references) {
-  const lines = [];
-
-  if (intents.includes("add-instances") || intents.includes("create-flow")) {
-    lines.push("- 新增实例与边：遵循 skill `skills/agentflow-flow-add-instances/SKILL.md`（内容已注入上下文）");
-  }
-  if (intents.includes("edit-fields") || intents.includes("optimize-nodes")) {
-    lines.push("- 仅改已有实例文案/占位等：遵循 `skills/agentflow-flow-edit-node-fields/SKILL.md`（内容已注入上下文）");
-  }
-  if (intents.includes("optimize-flow")) {
-    lines.push("- 流程结构优化：参考 `reference/flow-control-capabilities.md` 和 `reference/flow-layout.md`（内容已注入上下文）");
-  }
-
-  lines.push(
-    "- **节点类型选择（必须遵守）**：**确定性任务 → tool_nodejs；非确定性任务 → agent_subAgent**。" +
-    "确定性 = 相同输入必出相同输出、可用普通代码完整描述（CLI/npm、读写文件、转换格式、调 API）。" +
-    "非确定性 = 需语义理解或创造（代码翻译/生成、源码/文本理解、多步决策、创意写作）。" +
-    "醒目输出 → tool_print。" +
-    "反例：『Android 转 RN』『代码 review』必须 agent。"
-  );
-  lines.push(
-    "- **tool_nodejs 必须写 script 字段**：script 是实际执行的命令代码，body 仅为文档注释（有 script 时不执行）。" +
-    "禁止 tool_nodejs 只有 body 没有 script（body 中的自然语言不会被执行）。" +
-    "如果无法写出完整可执行的 script，必须改用 agent_subAgent。"
-  );
-
-  return lines.join("\n");
-}
-
 function buildSelectedSkillsHint(skills) {
   if (!Array.isArray(skills) || skills.length === 0) return "";
   const lines = ["## 用户选择的 skills"];
@@ -385,58 +120,3 @@ function buildSelectedSkillsHint(skills) {
 
 // ─── 辅助 ─────────────────────────────────────────────────────────────────
 
-function stripFrontmatter(content) {
-  const match = content.match(/^---\n[\s\S]*?\n---\n?/);
-  return match ? content.slice(match[0].length) : content;
-}
-
-/**
- * 为规划器提供精简的 skill 上下文摘要（不含完整文档内容，仅规则要点）。
- * @param {string[]} intents
- * @returns {string}
- */
-export function buildPlannerSkillContext(intents) {
-  if (!intents || intents.length === 0) return "";
-
-  const parts = ["## 编辑技能约束（规划时须遵守）"];
-
-  if (intents.includes("add-instances") || intents.includes("create-flow")) {
-    parts.push(
-      "- 新增节点：须从 builtin/pipelines/new/flow.yaml 拷贝同类 definitionId 的实例模板；" +
-      "不要自造 input/output 顺序和 name；每个新 instanceId 须在 ui.nodePositions 写入坐标（主链从左到右 x 递增 280，起始 x:100 y:300；分支 y 错开 200）；" +
-      "默认不连线，仅当用户明确要求时才在 edges 中增加边。"
-    );
-    parts.push(
-      "- 节点类型选择：**确定性任务 → tool_nodejs；非确定性任务 → agent_subAgent**。" +
-      "确定性 = 相同输入永远相同输出（CLI/npm/读写文件/转换/调 API）；" +
-      "非确定性 = 需语义理解或创造（代码翻译/生成、理解源码、多步决策、创意写作）；" +
-      "醒目输出 → tool_print。反例：『Android 转 RN』『代码 review』必须 agent。"
-    );
-    parts.push(
-      "- tool_nodejs 的 script 与 body 区分：script 是实际执行的命令（必填），body 仅为文档注释（有 script 时不执行）；" +
-      "禁止 tool_nodejs 只写 body 不写 script（自然语言不会被执行）；如果无法写出完整可执行的 script，必须改用 agent_subAgent。"
-    );
-    parts.push("- 每个节点单一职责，不要把多个操作塞进同一个 body。");
-  }
-
-  if (intents.includes("edit-fields") || intents.includes("optimize-nodes")) {
-    parts.push(
-      "- 修改已有节点：可改白名单字段（label、body、role、script、input[].value、output[].value）；" +
-      "禁改 definitionId、instanceId 键名、input/output 数组结构与顺序、edges。"
-    );
-    parts.push(
-      "- **tool_nodejs 的 script 必须写**：`definitionId: tool_nodejs` 的节点核心是 `script`（实际执行的 shell/node 命令），" +
-      "`body` 有 script 时不执行。优化 tool_nodejs 节点时务必检查并完善 `script` 字段，禁止只在 `body` 里写自然语言描述。" +
-      "如果无法写出可执行 script，应建议改用 `agent_subAgent`。"
-    );
-  }
-
-  if (intents.includes("optimize-flow")) {
-    parts.push(
-      "- 流程优化可能涉及：调整拓扑（改边）、增删节点、改 body 内容、调整布局坐标。" +
-      "如果需要多种操作，拆成多个步骤（先改内容再连线，先加节点再连线）。"
-    );
-  }
-
-  return parts.join("\n");
-}

package/bin/lib/exec-buffered.mjs

@@ -0,0 +1,32 @@
+/**
+ * 带超时和缓冲上限的 execFile。
+ *
+ * 失败时把 stdout / stderr 挂在 error 上再抛——调用方通常要靠子进程的输出判断出了什么事，
+ * 只拿到一个 exit code 没法处理。
+ */
+import { execFile } from "child_process";
+
+/**
+ * @param {string} command
+ * @param {string[]} args
+ * @param {{ timeout?: number, maxBuffer?: number, cwd?: string, env?: object }} [options]
+ * @returns {Promise<{ stdout: string, stderr: string }>}
+ */
+export function execFileBuffered(command, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, {
+      timeout: Number(options.timeout || 30000),
+      maxBuffer: Number(options.maxBuffer || 2 * 1024 * 1024),
+      cwd: options.cwd || process.cwd(),
+      env: options.env || process.env,
+    }, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}

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

@@ -0,0 +1,277 @@
+/**
+ * `agentflow flow dsl <export|import|lint>` 的实现。
+ *
+ * export / import 是互逆的，用同一套 IR，所以往返可证；lint 只读，不改任何文件。
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+import { WORKSPACE_STATE_FILENAME, mergeWorkspaceState } from "../workspace-state.mjs";
+import {
+  FLOW_LAYOUT_FILENAME,
+  FLOW_NODES_FILENAME,
+  FLOW_SOURCE_FILENAME,
+  flowFilesToGraph,
+  graphToFlowFiles,
+} from "./index.mjs";
+import { legacyYamlToDesignGraph } from "./legacy-yaml.mjs";
+import { lintFlowDir } from "./lint.mjs";
+import { readWorkspaceGraphFiles, writeWorkspaceGraphFiles } from "../workspace-flow-store.mjs";
+import { applyWorkspaceAutoLayout } from "../workspace-auto-layout.mjs";
+
+const GRAPH_FILENAME = "workspace.graph.json";
+const LEGACY_YAML_FILENAME = "flow.yaml";
+
+function readJson(file, fallback) {
+  if (!fs.existsSync(file)) return fallback;
+  try {
+    const raw = fs.readFileSync(file, "utf-8");
+    if (!raw.trim()) return fallback;
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeFileEnsuringDir(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, text, "utf-8");
+}
+
+/** 读一个流程目录里的完整图（设计态 + 运行态）。 */
+function readFullGraph(flowDir) {
+  const graphPath = path.join(flowDir, GRAPH_FILENAME);
+  if (!fs.existsSync(graphPath)) throw new Error(`找不到 ${graphPath}`);
+  const design = JSON.parse(fs.readFileSync(graphPath, "utf-8"));
+  return mergeWorkspaceState(design, readJson(path.join(flowDir, WORKSPACE_STATE_FILENAME), null));
+}
+
+/**
+ * workspace.graph.json -> workspace.flow.js + layout/nodes + 外置长文本。
+ * @returns {{ outDir: string, written: string[] }}
+ */
+export function exportFlowDsl(flowDir, outDir) {
+  const graph = readFullGraph(flowDir);
+  const out = graphToFlowFiles(graph);
+  const target = path.resolve(outDir || flowDir);
+  fs.mkdirSync(target, { recursive: true });
+
+  const written = [];
+  const put = (rel, text) => {
+    writeFileEnsuringDir(path.join(target, rel), text);
+    written.push(rel);
+  };
+
+  put(FLOW_SOURCE_FILENAME, out.source);
+  put(FLOW_LAYOUT_FILENAME, `${JSON.stringify(out.layout, null, 2)}\n`);
+  if (Object.keys(out.nodeMeta.nodes).length) {
+    put(FLOW_NODES_FILENAME, `${JSON.stringify(out.nodeMeta, null, 2)}\n`);
+  }
+  for (const file of out.files) put(file.path, file.text);
+
+  return { outDir: target, written };
+}
+
+/**
+ * workspace.flow.js + layout/nodes -> workspace.graph.json（设计态）。
+ * 运行态原样保留在 workspace.state.json 里，不受导入影响。
+ */
+export function importFlowDsl(srcDir, outFlowDir) {
+  const dir = path.resolve(srcDir);
+  const sourcePath = path.join(dir, FLOW_SOURCE_FILENAME);
+  if (!fs.existsSync(sourcePath)) throw new Error(`找不到 ${sourcePath}`);
+
+  const lint = lintFlowDir(dir);
+  if (lint.errors.length) {
+    throw new Error(`lint 未通过，拒绝导入：\n  ${lint.errors.join("\n  ")}`);
+  }
+
+  // file() 引用的外置文本：把目录下所有非结构文件都喂进去，解析时按引用取用
+  const files = {};
+  const collect = (rel) => {
+    const abs = path.join(dir, rel);
+    if (!fs.existsSync(abs)) return;
+    for (const entry of fs.readdirSync(abs, { withFileTypes: true })) {
+      if (entry.isDirectory()) continue;
+      files[`${rel}/${entry.name}`] = fs.readFileSync(path.join(abs, entry.name), "utf-8");
+    }
+  };
+  for (const sub of ["prompts", "docs", "scripts"]) collect(sub);
+
+  const design = flowFilesToGraph({
+    source: fs.readFileSync(sourcePath, "utf-8"),
+    layout: readJson(path.join(dir, FLOW_LAYOUT_FILENAME), { nodes: {} }),
+    nodeMeta: readJson(path.join(dir, FLOW_NODES_FILENAME), { nodes: {} }),
+    files,
+  });
+
+  const target = path.resolve(outFlowDir || dir);
+  fs.mkdirSync(target, { recursive: true });
+  writeFileEnsuringDir(path.join(target, GRAPH_FILENAME), `${JSON.stringify(design, null, 2)}\n`);
+  return {
+    graphPath: path.join(target, GRAPH_FILENAME),
+    nodeCount: Object.keys(design.instances).length,
+    edgeCount: design.edges.length,
+    warnings: lint.warnings,
+  };
+}
+
+/**
+ * 为 Workspace 图生成确定性坐标。默认只补缺失坐标，保护用户已经拖过的节点；`all` 用于
+ * AI 新建流程或用户明确要求整理整张图时的全量重排。
+ */
+export function layoutWorkspaceFlowDir(flowDir, { all = false, workspaceRoot = "" } = {}) {
+  const dir = path.resolve(flowDir);
+  const lint = lintWorkspaceFlowDir(dir, { workspaceRoot });
+  if (lint.errors.length) {
+    throw new Error(`lint 未通过，拒绝排版：\n  ${lint.errors.join("\n  ")}`);
+  }
+  const current = readWorkspaceGraphFiles(dir, { marketplaceRoot: workspaceRoot });
+  if (current.format === "empty") throw new Error("这个流程还没有 Workspace 图");
+
+  const before = current.graph?.ui?.nodePositions || {};
+  const next = applyWorkspaceAutoLayout(current.graph, { preserveExisting: !all });
+  const after = next.ui.nodePositions;
+  let positioned = 0;
+  for (const id of Object.keys(next.instances || {})) {
+    if (before[id]?.x !== after[id]?.x || before[id]?.y !== after[id]?.y) positioned += 1;
+  }
+  const written = writeWorkspaceGraphFiles(dir, next, { marketplaceRoot: workspaceRoot });
+  return {
+    flowDir: dir,
+    format: written.format,
+    mode: all ? "all" : "missing",
+    nodeCount: Object.keys(next.instances || {}).length,
+    positioned,
+    layoutPath: path.join(dir, FLOW_LAYOUT_FILENAME),
+  };
+}
+
+/** 没有节点丢失时的空损耗清单，让返回值形状始终一致。 */
+const NO_LOSS = { remapped: [], dropped: [], droppedEdges: [], renamedIds: [], warnings: [] };
+
+/**
+ * 把一个流程目录就地迁移成代码形态。两个来源：
+ *
+ * - `workspace.graph.json` —— 同一套词汇表，纯换存储格式，无损
+ * - `flow.yaml` —— 老执行栈的词汇表，要换词，**可能有损**
+ *
+ * 都走 Web UI 保存时的同一条路径（`writeWorkspaceDesign`），因此同样带往返比对闸门：
+ * 生成的代码解析不回原图就不迁移，原文件原样留着。
+ *
+ * yaml 那条路默认**拒绝有损迁移**：只要有节点或边接不过去就停下来把清单报出去，磁盘不动。
+ * `allowLoss` 才落盘。理由和存储层那条闸门一样——宁可不迁移，也不能悄悄弄丢。
+ *
+ * yaml 原文不删。迁移完 `workspace.flow.js` 成为权威（读图先看它），`flow.yaml` 退到
+ * 一边当原始材料，出了问题还能对着看。
+ *
+ * @param {string} flowDir
+ * @param {{ force?: boolean, marketplaceRoot?: string }} [opts]
+ * @returns {{ flowDir: string, format: "dsl"|"json"|"yaml"|"empty", migrated: boolean,
+ *   degradedReason: string|null, externals: string[], source?: "graph.json"|"flow.yaml",
+ *   remapped: Array, dropped: Array, droppedEdges: Array, warnings: string[] }}
+ */
+export function migrateFlowDirToDsl(flowDir, opts = {}) {
+  const dir = path.resolve(flowDir);
+  const storeOpts = { marketplaceRoot: opts.marketplaceRoot || "" };
+  const current = readWorkspaceGraphFiles(dir, storeOpts);
+  if (current.format === "dsl") {
+    return { flowDir: dir, format: "dsl", migrated: false, degradedReason: null, externals: [], ...NO_LOSS };
+  }
+  if (current.format === "empty") return migrateLegacyYamlDir(dir, opts);
+
+  // 走完整图这条路：历史 graph.json 里运行产出还是内联的，得先拆出去，否则那些每跑一次
+  // 就变一次的值会被当成设计态参与往返比对
+  const result = writeWorkspaceGraphFiles(dir, current.graph, storeOpts);
+  return {
+    flowDir: dir,
+    format: result.format,
+    migrated: result.format === "dsl",
+    degradedReason: result.degradedReason,
+    externals: result.externals,
+    source: "graph.json",
+    ...NO_LOSS,
+  };
+}
+
+/** `flow.yaml` -> 代码。没有 yaml 就是真的没图。 */
+function migrateLegacyYamlDir(dir, { force = false, marketplaceRoot = "" } = {}) {
+  const yamlPath = path.join(dir, LEGACY_YAML_FILENAME);
+  if (!fs.existsSync(yamlPath)) {
+    return { flowDir: dir, format: "empty", migrated: false, degradedReason: null, externals: [], ...NO_LOSS };
+  }
+  const converted = legacyYamlToDesignGraph(fs.readFileSync(yamlPath, "utf-8"));
+  const loss = {
+    remapped: converted.remapped,
+    dropped: converted.dropped,
+    droppedEdges: converted.droppedEdges,
+    renamedIds: converted.renamedIds,
+    warnings: converted.warnings,
+  };
+  // `control_end` 和指向它的边标了 benign——丢了等于没丢，不该拦住迁移。
+  const lossy = [...converted.dropped, ...converted.droppedEdges].some((x) => !x.benign);
+  if (lossy && !force) {
+    return {
+      flowDir: dir,
+      format: "yaml",
+      migrated: false,
+      degradedReason: "有节点或边接不过去（--allow-loss 忽略并继续）",
+      externals: [],
+      source: "flow.yaml",
+      ...loss,
+    };
+  }
+  const result = writeWorkspaceGraphFiles(dir, converted.graph, { marketplaceRoot });
+  return {
+    flowDir: dir,
+    format: result.format,
+    migrated: result.format === "dsl",
+    // 从 yaml 出发时，退回 JSON 也是**成功**：`workspace.graph.json` 读得出、画得出、
+    // 跑得动，而 yaml 三样都不行。够不着代码形态只是差最后一步，不是这次迁移失败。
+    leftYaml: true,
+    degradedReason: result.degradedReason,
+    externals: result.externals,
+    source: "flow.yaml",
+    ...loss,
+  };
+}
+
+/**
+ * 校验一个流程目录里的 Workspace 图，不管它是代码形态还是历史 JSON。
+ *
+ * 历史 JSON 的做法是先在临时目录里渲染成代码再 lint——校验的正是它迁移之后会变成的
+ * 样子，比「这份 JSON 能不能 parse」有用得多：引脚名、未知节点类型、环、fan-in 这些
+ * 问题在两种形态下都一样存在，只有代码形态能查出来。
+ *
+ * @returns {{ format: "dsl"|"json"|"empty", errors: string[], warnings: string[] }}
+ */
+export function lintWorkspaceFlowDir(flowDir, opts = {}) {
+  const dir = path.resolve(flowDir);
+  if (fs.existsSync(path.join(dir, FLOW_SOURCE_FILENAME))) {
+    return { format: "dsl", ...lintFlowDir(dir, opts) };
+  }
+
+  const current = readWorkspaceGraphFiles(dir);
+  if (current.format === "empty") {
+    return { format: "empty", errors: [], warnings: ["这个流程还没有 Workspace 图"] };
+  }
+
+  const staging = fs.mkdtempSync(path.join(os.tmpdir(), "agentflow-lint-"));
+  try {
+    const out = graphToFlowFiles(current.graph);
+    writeFileEnsuringDir(path.join(staging, FLOW_SOURCE_FILENAME), out.source);
+    writeFileEnsuringDir(path.join(staging, FLOW_LAYOUT_FILENAME), `${JSON.stringify(out.layout, null, 2)}\n`);
+    writeFileEnsuringDir(path.join(staging, FLOW_NODES_FILENAME), `${JSON.stringify(out.nodeMeta, null, 2)}\n`);
+    for (const file of out.files) writeFileEnsuringDir(path.join(staging, file.path), file.text);
+    // 代码节点包在原目录里，不复制过去的话每个 import 都会报「节点包不存在」
+    const localNodes = path.join(dir, "nodes");
+    if (fs.existsSync(localNodes)) fs.cpSync(localNodes, path.join(staging, "nodes"), { recursive: true });
+    return { format: "json", ...lintFlowDir(staging, opts) };
+  } finally {
+    fs.rmSync(staging, { recursive: true, force: true });
+  }
+}
+
+export { lintFlowDir };