@fieldwangai/agentflow 0.1.149 → 0.1.154

package/bin/lib/flow-import.mjs

@@ -1,12 +1,24 @@
 /**
- * 从 flow.yaml 文本或 zip 解压结果导入流水线目录（user / workspace）。
+ * 从上传的流程文件或 zip 解压结果导入流水线目录（user / workspace）。
+ *
+ * 「包的根在哪」这件事以前只认 `flow.yaml`——代码化的流程目录里没有它，于是从平台发布通道
+ * 传上来只会得到「压缩包内未找到 flow.yaml」。判据改成和磁盘上完全一致的那一套
+ * （`FLOW_MARKER_FILENAMES`：`workspace.flow.js` / `workspace.graph.json` / `flow.yaml`），
+ * 两种格式都收。
  */
 import fs from "fs";
 import path from "path";
 import yaml from "js-yaml";
 import { unzipSync } from "fflate";
+import { flowFilesToGraph } from "./flow-dsl/index.mjs";
+import { marketplaceDependenciesFromSource } from "./flow-dsl/packages.mjs";
 import { resolveFlowDirForWrite, validateUserPipelineId } from "./flow-write.mjs";
 import { normalizeFlowYamlText } from "./flow-normalize.mjs";
+import { FLOW_MARKER_FILENAMES } from "./paths.mjs";
+
+/** `flow.yml` 是 `flow.yaml` 的历史别名，落盘时统一改名。 */
+const YAML_ALIAS = "flow.yml";
+const MARKERS = new Set([...FLOW_MARKER_FILENAMES, YAML_ALIAS].map((n) => n.toLowerCase()));
 
 export const IMPORT_MAX_UNCOMPRESSED_BYTES = 8 * 1024 * 1024;
 export const IMPORT_MAX_FILE_ENTRIES = 500;
@@ -34,15 +46,19 @@ function shouldIgnoreZipPath(norm) {
   return parts.some((seg) => seg === "__MACOSX" || seg.startsWith("._"));
 }
 
-function flowYamlParentDir(normPath) {
+/**
+ * 这个文件是不是流程目录的标记文件；是的话返回它所在的目录（根目录为 `""`）。
+ *
+ * 只认根目录或一层子目录——再深的层级不是「单个流程的包」。
+ *
+ * @returns {string | null} 不是标记文件时返回 null
+ */
+function flowMarkerParentDir(normPath) {
   const lower = normPath.toLowerCase();
-  if (lower === "flow.yaml" || lower === "flow.yml") return "";
-  const suf = "/flow.yaml";
-  const sufYml = "/flow.yml";
-  let parent = null;
-  if (lower.endsWith(suf)) parent = normPath.slice(0, -suf.length);
-  else if (lower.endsWith(sufYml)) parent = normPath.slice(0, -sufYml.length);
-  else return null;
+  if (MARKERS.has(lower)) return "";
+  const slash = lower.lastIndexOf("/");
+  if (slash < 0 || !MARKERS.has(lower.slice(slash + 1))) return null;
+  const parent = normPath.slice(0, slash);
   if (parent.includes("/")) return null;
   return parent;
 }
@@ -85,6 +101,54 @@ export function validateImportedFlowYaml(content) {
   }
 }
 
+/**
+ * 单文件上传（不是 zip）时，判断这一份是什么、能不能收。
+ *
+ * 代码化的流程只上传 `workspace.flow.js` 时，布局和节点元数据都缺席——那不影响读图，
+ * 缺省会被补齐。但源码必须**当场解析得过**：写进去一个解析不出图的文件，用户下次打开画布
+ * 才发现，而那时已经离现场很远。
+ *
+ * @param {string} content
+ * @param {string} filename 上传时的文件名，用来决定按哪种格式解析
+ * @param {{ resolvePackage?: Function }} [opts]
+ * @returns {{ ok: true, entryName: string } | { ok: false, error: string }}
+ */
+export function validateImportedFlowSource(content, filename = "", opts = {}) {
+  const name = String(filename || "").toLowerCase();
+  if (!name.endsWith(".js") && !name.endsWith(".mjs")) {
+    const checked = validateImportedFlowYaml(content);
+    return checked.ok ? { ok: true, entryName: "flow.yaml" } : checked;
+  }
+  if (Buffer.byteLength(String(content || ""), "utf8") > IMPORT_MAX_UNCOMPRESSED_BYTES) {
+    return { ok: false, error: "workspace.flow.js 过大" };
+  }
+  const dependencies = marketplaceDependenciesFromSource(content);
+  if (dependencies.errors.length) {
+    return { ok: false, error: dependencies.errors.join("；") };
+  }
+  if (typeof opts.resolvePackage === "function") {
+    const missing = dependencies.dependencies.filter((dependency) => !opts.resolvePackage(dependency.specifier));
+    if (missing.length) {
+      return {
+        ok: false,
+        error: `服务端缺少节点包：${missing.map((dependency) => dependency.specifier).join(", ")}；请先上传这些精确版本`,
+      };
+    }
+  }
+  try {
+    flowFilesToGraph({
+      source: String(content || ""),
+      layout: {},
+      nodeMeta: {},
+      files: {},
+      resolvePackage: opts.resolvePackage,
+    });
+    return { ok: true, entryName: "workspace.flow.js" };
+  } catch (e) {
+    return { ok: false, error: `workspace.flow.js 解析失败：${(e && e.message) || e}` };
+  }
+}
+
 /**
  * @param {Record<string, Uint8Array>} unzipped
  * @returns {{ ok: true, files: Map<string, Buffer> } | { ok: false, error: string }}
@@ -118,15 +182,15 @@ export function normalizeZipToPipelineFiles(unzipped) {
   /** @type {Set<string>} */
   const parents = new Set();
   for (const k of raw.keys()) {
-    const p = flowYamlParentDir(k);
+    const p = flowMarkerParentDir(k);
     if (p !== null) parents.add(p);
   }
 
   if (parents.size === 0) {
-    return { ok: false, error: "压缩包内未找到 flow.yaml" };
+    return { ok: false, error: `压缩包内未找到流程文件（需要 ${FLOW_MARKER_FILENAMES.join(" / ")} 之一）` };
   }
   if (parents.size > 1) {
-    return { ok: false, error: "压缩包内存在多个 pipeline（多个 flow.yaml），请分别打包" };
+    return { ok: false, error: "压缩包内存在多个 pipeline，请分别打包" };
   }
 
   const [prefix] = [...parents];
@@ -136,7 +200,7 @@ export function normalizeZipToPipelineFiles(unzipped) {
     if (!need) {
       return {
         ok: false,
-        error: "ZIP 目录结构无效：存在不属于该流水线目录的文件（请使用单文件夹或根目录 flow.yaml）",
+        error: "ZIP 目录结构无效：存在不属于该流水线目录的文件（请使用单文件夹，或把流程文件放在根目录）",
       };
     }
   }
@@ -155,22 +219,23 @@ export function normalizeZipToPipelineFiles(unzipped) {
   }
 
   const yamlKeys = [...out.keys()].filter(
-    (k) => k.toLowerCase() === "flow.yaml" || k.toLowerCase() === "flow.yml",
+    (k) => k.toLowerCase() === "flow.yaml" || k.toLowerCase() === YAML_ALIAS,
   );
-  if (yamlKeys.length === 0) {
-    return { ok: false, error: "归一化后缺少 flow.yaml" };
-  }
   if (yamlKeys.length > 1) {
     return { ok: false, error: "流水线目录内不能同时存在多个 flow.yaml / flow.yml" };
   }
-
   const yamlKey = yamlKeys[0];
-  if (yamlKey !== "flow.yaml") {
+  if (yamlKey && yamlKey !== "flow.yaml") {
     const body = out.get(yamlKey);
     out.delete(yamlKey);
     out.set("flow.yaml", body);
   }
 
+  // 归一化会剥掉外层目录，标记文件可能因此换了位置——重新确认一次
+  if (![...out.keys()].some((k) => MARKERS.has(k.toLowerCase()))) {
+    return { ok: false, error: `归一化后缺少流程文件（需要 ${FLOW_MARKER_FILENAMES.join(" / ")} 之一）` };
+  }
+
   return { ok: true, files: out };
 }
 
@@ -214,7 +279,7 @@ export function suggestFlowIdFromZip(zipBuffer) {
     /** @type {Set<string>} */
     const parents = new Set();
     for (const k of raw.keys()) {
-      const p = flowYamlParentDir(k);
+      const p = flowMarkerParentDir(k);
       if (p !== null) parents.add(p);
     }
 
@@ -270,12 +335,17 @@ export function writePipelineTree(workspaceRoot, flowId, flowSource, filesRelati
     return { success: false, error: "目标目录已存在" };
   }
 
+  // 有 yaml 就照旧校验并规范化；代码化的包没有 yaml，认标记文件即可
   const yamlBuf = filesRelative.get("flow.yaml");
-  if (!yamlBuf) return { success: false, error: "缺少 flow.yaml" };
-  const text = yamlBuf.toString("utf8");
-  const v = validateImportedFlowYaml(text);
-  if (!v.ok) return { success: false, error: v.error };
-  const normalizedYaml = normalizeFlowYamlText(text).text;
+  let normalizedYaml = "";
+  if (yamlBuf) {
+    const text = yamlBuf.toString("utf8");
+    const v = validateImportedFlowYaml(text);
+    if (!v.ok) return { success: false, error: v.error };
+    normalizedYaml = normalizeFlowYamlText(text).text;
+  } else if (![...filesRelative.keys()].some((k) => MARKERS.has(k.toLowerCase()))) {
+    return { success: false, error: `缺少流程文件（需要 ${FLOW_MARKER_FILENAMES.join(" / ")} 之一）` };
+  }
 
   try {
     fs.mkdirSync(flowDir, { recursive: true });
@@ -290,7 +360,7 @@ export function writePipelineTree(workspaceRoot, flowId, flowSource, filesRelati
       }
       const parent = path.dirname(abs);
       fs.mkdirSync(parent, { recursive: true });
-      const payload = safe === "flow.yaml" ? Buffer.from(normalizedYaml, "utf8") : buf;
+      const payload = safe === "flow.yaml" && normalizedYaml ? Buffer.from(normalizedYaml, "utf8") : buf;
       fs.writeFileSync(abs, payload);
     }
     return { success: true };

package/bin/lib/flow-write.mjs

@@ -13,9 +13,11 @@ import {
   getUserPipelinesRoot,
   LEGACY_PIPELINES_DIR,
   PIPELINES_DIR,
+  isFlowDir,
 } from "./paths.mjs";
-import { getFlowYamlAbs } from "./catalog-flows.mjs";
+import { resolveFlowDirAbs } from "./catalog-flows.mjs";
 import { normalizeFlowYamlText } from "./flow-normalize.mjs";
+import { writeWorkspaceGraphFiles } from "./workspace-flow-store.mjs";
 
 export const FLOW_YAML_FILENAME = "flow.yaml";
 
@@ -83,7 +85,7 @@ function resolveExistingWorkspaceFlowDir(workspaceRoot, flowId) {
   const root = path.resolve(workspaceRoot);
   for (const rel of [PIPELINES_DIR, LEGACY_PIPELINES_DIR]) {
     const d = path.join(root, rel, flowId);
-    if (fs.existsSync(path.join(d, FLOW_YAML_FILENAME))) return d;
+    if (isFlowDir(d)) return d;
   }
   return null;
 }
@@ -186,6 +188,40 @@ export function resolveArchivedFlowDirForWrite(workspaceRoot, flowId, flowSource
   return { flowDir };
 }
 
+/**
+ * 新建一个空流程：目录 + 空的 `workspace.flow.js` + 承载说明的 `workspace.layout.json`。
+ *
+ * 以前新建流程写的是一个空 `flow.yaml`——那个格式的执行栈早就退休了，写它纯粹是因为
+ * 目录识别和列表说明当时只认它。两件事现在都不依赖 yaml 了（见 paths.mjs 的 `isFlowDir`
+ * 和 catalog-flows 的 `readPipelineListDescription`），所以新流程生下来就是代码。
+ *
+ * @param {string} workspaceRoot
+ * @param {string} flowId
+ * @param {FlowWriteSource} flowSource
+ * @param {{ description?: string, userId?: string }} [opts]
+ * @returns {{ success: true, flowDir: string } | { success: false, error: string }}
+ */
+export function createEmptyFlow(workspaceRoot, flowId, flowSource, opts = {}) {
+  const { flowDir, error } = resolveFlowDirForWrite(workspaceRoot, flowId, flowSource, opts);
+  if (error) return { success: false, error };
+  const description = String(opts.description || "").trim();
+  try {
+    fs.mkdirSync(flowDir, { recursive: true });
+    const result = writeWorkspaceGraphFiles(flowDir, {
+      version: 1,
+      instances: {},
+      edges: [],
+      ui: { nodePositions: {}, ...(description ? { description } : {}) },
+    });
+    if (result.format !== "dsl") {
+      return { success: false, error: `新建流程没能写成代码：${result.degradedReason || "未知原因"}` };
+    }
+    return { success: true, flowDir };
+  } catch (e) {
+    return { success: false, error: (e && e.message) || String(e) };
+  }
+}
+
 /**
  * @param {string} workspaceRoot
  * @param {string} flowId
@@ -221,11 +257,11 @@ export function archiveFlowPipeline(workspaceRoot, flowId, flowSource, opts = {}
   if (flowSource !== "user" && flowSource !== "workspace") {
     return { success: false, error: "仅支持用户目录或工作区流水线归档" };
   }
-  const yamlRes = getFlowYamlAbs(workspaceRoot, flowId, flowSource, { archived: false, userId: opts.userId });
-  if (yamlRes.error || !yamlRes.path) {
-    return { success: false, error: yamlRes.error || "找不到流水线" };
+  const dirRes = resolveFlowDirAbs(workspaceRoot, flowId, flowSource, { archived: false, userId: opts.userId });
+  if (dirRes.error || !dirRes.dir) {
+    return { success: false, error: dirRes.error || "找不到流水线" };
   }
-  const fromDir = path.dirname(yamlRes.path);
+  const fromDir = dirRes.dir;
   const sep = path.sep;
   if (fromDir.split(sep).includes(ARCHIVED_PIPELINES_DIR_NAME)) {
     return { success: false, error: "该流水线已在归档目录中" };
@@ -266,7 +302,7 @@ export function restoreArchivedFlowPipeline(workspaceRoot, flowId, flowSource, o
     return { success: false, error: archivedRes.error || "无法解析归档路径" };
   }
   const fromDir = archivedRes.flowDir;
-  if (!fs.existsSync(path.join(fromDir, FLOW_YAML_FILENAME))) {
+  if (!isFlowDir(fromDir)) {
     return { success: false, error: "找不到归档流水线" };
   }
   const activeRes = resolveFlowDirForWrite(workspaceRoot, flowId, flowSource, opts);
@@ -317,7 +353,7 @@ export function moveFlowDirectory(workspaceRoot, flowId, fromSource, toSource, o
   const toRes = resolveFlowDirForWrite(workspaceRoot, flowId, toSource, opts);
   if (toRes.error || !toRes.flowDir) return { success: false, error: toRes.error || "invalid target path" };
   const toDir = toRes.flowDir;
-  if (!fs.existsSync(path.join(fromDir, FLOW_YAML_FILENAME))) {
+  if (!isFlowDir(fromDir)) {
     return { success: false, error: "source flow not found" };
   }
   if (fs.existsSync(toDir)) {
@@ -417,11 +453,11 @@ export function deleteFlowPipeline(workspaceRoot, flowId, flowSource, opts = {})
     return { success: false, error: "invalid flowId" };
   }
   const archived = Boolean(opts.archived);
-  const yamlRes = getFlowYamlAbs(workspaceRoot, flowId, flowSource, { archived, userId: opts.userId });
-  if (yamlRes.error || !yamlRes.path) {
-    return { success: false, error: yamlRes.error || "找不到流水线" };
+  const dirRes = resolveFlowDirAbs(workspaceRoot, flowId, flowSource, { archived, userId: opts.userId });
+  if (dirRes.error || !dirRes.dir) {
+    return { success: false, error: dirRes.error || "找不到流水线" };
   }
-  const flowDir = path.dirname(yamlRes.path);
+  const flowDir = dirRes.dir;
   const guard = assertFlowDirIsSafeToDelete(flowDir, workspaceRoot, flowSource, flowId, opts);
   if (!guard.ok) return { success: false, error: guard.error };
   try {

package/bin/lib/help.mjs

@@ -11,30 +11,20 @@ export function printHelp() {
 AgentFlow CLI — 使用 Cursor / OpenCode / Claude Code / Codex CLI 流式输出驱动 apply/replay。
 
 用法：
-  agentflow login [--provider github|google]   登录 AgentFlow Hub（默认 GitHub）
-  agentflow logout                             退出 Hub 登录
-  agentflow publish <FlowName> [--title <t>] [--description <d>] [--tags <t1,t2>]  发布流程到 Hub
-  agentflow list-remote [--search <q>] [--sort popular|trending] [--json]  浏览 Hub 上的流程
-  agentflow download <slug|title> [--user|--workspace] [--as <id>] [--raw [--output <dir>]]  从 Hub 下载流程（默认 --user 安装到 ~/agentflow/pipelines/<id>；--workspace 安装到当前工程 .workspace/agentflow/pipelines/<id>；--raw 仅保留压缩包）
   agentflow list                              列出所有流水线
-  agentflow ui [--host <addr>] [--port <n>] [--scheduler] [--no-open] [--hide-community-links]  本地 HTTP：流水线列表 + React Flow 节点流程图编辑保存（默认 127.0.0.1:8765；可用 AGENTFLOW_UI_HOST）
-  agentflow flow preview <FlowName|flow.yaml> [--output <preview.html>] [--no-open]  生成平台同款画布的单文件静态 Flow 预览
+  agentflow ui [--host <addr>] [--port <n>] [--no-open] [--hide-community-links]  本地 HTTP：流水线列表 + React Flow 节点流程图编辑保存（默认 127.0.0.1:8765；可用 AGENTFLOW_UI_HOST）
+  agentflow flow dsl <export|import|lint|migrate> <FlowName|dir> [--out <dir>]  流程图与 workspace.flow.js 代码互转 / 静态校验 / 就地迁移
   agentflow mcp                              启动 AgentFlow MCP stdio server，供 Cursor/Codex 运行流程并读取 display 输出
-  agentflow scheduler start [--poll-ms <ms>]  启动定时执行调度器（读取各流水线 schedule.json）
-  agentflow scheduler status [--json]         查看定时执行配置与状态
-  agentflow scheduler cancel <FlowName> <uuid>  取消某次等待中的 watch/run
   agentflow marketplace list [--json]         查看 workspace 本地节点市场
   agentflow marketplace publish-node <dir>    发布本地节点包到 workspace market
-  agentflow marketplace install-node <FlowName> <nodeSpec>  将 market 节点依赖写入 flow
-  agentflow apply <FlowName> [uuid]            或 agentflow apply <uuid>（由 uuid 反查 pipeline）
+  agentflow apply <FlowName> [uuid]            已下线；请改用 Workspace Run
   agentflow validate <FlowName> [uuid]        校验流程；终端下输出易读结果，--json 或管道时输出 JSON；传 uuid 时写入 runDir/intermediate/validation.json
-  agentflow resume <FlowName> <uuid> [instanceId]  将 pending 与 failed 节点标为已确认并继续 apply
-  agentflow replay [flowName] <uuid> <instanceId>
+  agentflow resume <FlowName> <uuid> [instanceId]  已下线；请改用 Workspace Run
+  agentflow replay [flowName] <uuid> <instanceId>   已下线；请改用 Workspace Run
   agentflow run-status <flowName> <uuid>  输出该次运行的节点状态 JSON（供 UI 展示 success/pending 等角标）
   agentflow extract-thinking <flowName> <uuid>  从该次 run 的 logs/log.txt 提取 thinking，写入 logs/thinking_by_session_and_nodes.md
   agentflow extract-thinking -list             列出所有存在 logs/log.txt 的 run（可接 --json）
   agentflow update-model-lists            拉取 Cursor / OpenCode / Claude Code / Codex 模型列表并写入 ~/agentflow/model-lists.json
-  agentflow write-flow <flowId> --json --flow-source <user|workspace>   从 stdin 读入 YAML 写入用户目录或工作区（builtin 已弃用，将视为 workspace）
   agentflow --help
 
 选项：
@@ -82,30 +72,20 @@ Apply/replay 脚本已打包在 agentflow 包中（bin/pipeline/）。
 AgentFlow CLI — drive apply/replay with Cursor / OpenCode / Claude Code / Codex CLI streaming.
 
 Usage:
-  agentflow login [--provider github|google]   Login to AgentFlow Hub (default: GitHub)
-  agentflow logout                             Sign out of Hub
-  agentflow publish <FlowName> [--title <t>] [--description <d>] [--tags <t1,t2>]  Publish flow to Hub
-  agentflow list-remote [--search <q>] [--sort popular|trending] [--json]  Browse flows on Hub
-  agentflow download <slug|title> [--user|--workspace] [--as <id>] [--raw [--output <dir>]]  Download flow (default --user → ~/agentflow/pipelines/<id>; --workspace → current project's .workspace/agentflow/pipelines/<id>; --raw keeps the archive)
   agentflow list                              List all pipelines
-  agentflow ui [--host <addr>] [--port <n>] [--scheduler] [--no-open] [--hide-community-links]  Local HTTP: pipeline list + React Flow node diagram editor (default 127.0.0.1:8765; AGENTFLOW_UI_HOST supported)
-  agentflow flow preview <FlowName|flow.yaml> [--output <preview.html>] [--no-open]  Generate a single-file static Flow preview using the platform canvas
+  agentflow ui [--host <addr>] [--port <n>] [--no-open] [--hide-community-links]  Local HTTP: pipeline list + React Flow node diagram editor (default 127.0.0.1:8765; AGENTFLOW_UI_HOST supported)
+  agentflow flow dsl <export|import|lint|migrate> <FlowName|dir> [--out <dir>]  Convert a graph to/from workspace.flow.js, lint it, or migrate in place
   agentflow mcp                              Start the AgentFlow MCP stdio server for Cursor/Codex to run flows and read display outputs
-  agentflow scheduler start [--poll-ms <ms>]  Start the scheduled-run scheduler (reads each pipeline schedule.json)
-  agentflow scheduler status [--json]         Show scheduled-run configuration and state
-  agentflow scheduler cancel <FlowName> <uuid>  Cancel a waiting watch/run
   agentflow marketplace list [--json]         Show workspace local marketplace packages
   agentflow marketplace publish-node <dir>    Publish a local node package to the workspace market
-  agentflow marketplace install-node <FlowName> <nodeSpec>  Add a marketplace node dependency to a flow
-  agentflow apply <FlowName> [uuid]            Or agentflow apply <uuid> (resolve pipeline from uuid)
+  agentflow apply <FlowName> [uuid]            Retired; use Workspace Run instead
   agentflow validate <FlowName> [uuid]        Validate flow; readable output in terminal, JSON with --json or pipe; writes to runDir/intermediate/validation.json when uuid provided
-  agentflow resume <FlowName> <uuid> [instanceId]  Mark pending and failed nodes as acknowledged and continue apply
-  agentflow replay [flowName] <uuid> <instanceId>
+  agentflow resume <FlowName> <uuid> [instanceId]  Retired; use Workspace Run instead
+  agentflow replay [flowName] <uuid> <instanceId>   Retired; use Workspace Run instead
   agentflow run-status <flowName> <uuid>  Output node status JSON for this run (for UI success/pending badges)
   agentflow extract-thinking <flowName> <uuid>  Extract thinking from run logs/log.txt, write to logs/thinking_by_session_and_nodes.md
   agentflow extract-thinking -list             List all runs with logs/log.txt (use --json)
   agentflow update-model-lists            Fetch Cursor / OpenCode / Claude Code / Codex model lists to ~/agentflow/model-lists.json
-  agentflow write-flow <flowId> --json --flow-source <user|workspace>   Read YAML from stdin and write to user dir or workspace (builtin deprecated, treated as workspace)
   agentflow --help
 
 Options:

package/bin/lib/html-escape.mjs

@@ -0,0 +1,19 @@
+/**
+ * HTML 转义。
+ *
+ * 单独成模块是为了让 PRD workflow 那套服务端渲染不必反向依赖 ui-server——它和
+ * `injectHtmlBaseHref` 是仅有的两个使用者，各自 import 一份比互相牵扯干净。
+ */
+
+/**
+ * 转义成可以放进属性值的文本。
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function htmlEscapeAttribute(value) {
+  return String(value || "")
+    .replace(/&/g, "&")
+    .replace(/"/g, """)
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;");
+}

package/bin/lib/http-util.mjs

@@ -0,0 +1,49 @@
+/**
+ * 两个最基础的 HTTP 工具。
+ *
+ * 独立成模块只有一个原因：路由拆分出去之后，`json(res, ...)` / `readBody(req)` 在两个文件
+ * 里都要以**同名标识符**出现——搬走的路由体一行都不改，靠的就是这个。
+ */
+
+/**
+ * @param {import('http').ServerResponse} res
+ * @param {number} status
+ * @param {unknown} obj
+ */
+export function json(res, status, obj) {
+  const body = JSON.stringify(obj);
+  res.writeHead(status, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Content-Length": Buffer.byteLength(body),
+  });
+  res.end(body);
+}
+
+export function readBody(req, maxBytes = 5 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    let exceeded = false;
+    req.on("data", (chunk) => {
+      if (exceeded) return;
+      const value = Buffer.from(chunk);
+      total += value.length;
+      if (total > maxBytes) {
+        exceeded = true;
+        chunks.length = 0;
+        return;
+      }
+      chunks.push(value);
+    });
+    req.on("end", () => {
+      if (exceeded) {
+        const error = new Error(`Request body exceeds ${maxBytes} bytes`);
+        error.status = 413;
+        reject(error);
+        return;
+      }
+      resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    req.on("error", reject);
+  });
+}

package/bin/lib/legacy-flow-execution.mjs

@@ -0,0 +1,43 @@
+export const LEGACY_FLOW_EXECUTION_DISABLED = true;
+
+export const LEGACY_FLOW_EXECUTION_MESSAGE =
+  "Legacy Start/End Pipeline execution has been retired. Use the Workspace graph with Run or Scheduled Run.";
+
+export const LEGACY_FLOW_NODE_IDS = new Set(["control_start", "control_end"]);
+
+/**
+ * 只有旧 Start/End 运行时实现、Workspace 运行时没有对应 handler 的节点类型。
+ *
+ * 这些定义留在 `builtin/nodes/` 只为让历史 flow.yaml / workspace.graph.json 仍能解析出
+ * 节点元数据；节点面板不再提供它们，避免用户新建出跑不了的图（拖出来只会落到通用
+ * agent 路径，拿不到文档承诺的语义）。
+ *
+ * 想恢复某个类型，就在 ui-server 的 workspace 运行循环里补上 handler，再从这里删掉。
+ */
+export const WORKSPACE_UNSUPPORTED_NODE_IDS = new Set([
+  // 循环 / 汇合：Workspace 运行计划是 DAG，有环会被直接拒绝
+  "control_anyOne",
+  "control_toBool",
+  "control_agent_toBool",
+  "control_interval_loop",
+  // 时序与取消
+  "control_delay",
+  "control_wait_until",
+  "control_cancelled",
+  // 人工卡点
+  "tool_user_check",
+  "tool_user_ask",
+  // 运行期键值 / 环境变量
+  "tool_load_key",
+  "tool_save_key",
+  "tool_get_env",
+  // 其它
+  "tool_print",
+  "tool_jenkins_build",
+]);
+
+/** 节点面板与目录需要隐藏的全部 definitionId */
+export const RETIRED_NODE_IDS = new Set([
+  ...LEGACY_FLOW_NODE_IDS,
+  ...WORKSPACE_UNSUPPORTED_NODE_IDS,
+]);

package/bin/lib/locales/en.json

@@ -106,7 +106,7 @@
     "type_text": "Text",
     "pipeline_header": "Pipeline",
     "source_header": "Source",
-    "apply_example_header": "Apply Example"
+    "open_example_header": "Validate Command"
   },
   "composer": {
     "edit_context": "## AgentFlow Edit Context",

package/bin/lib/locales/zh.json

@@ -106,7 +106,7 @@
     "type_text": "文本",
     "pipeline_header": "流水线",
     "source_header": "来源",
-    "apply_example_header": "Apply 示例"
+    "open_example_header": "校验命令"
   },
   "composer": {
     "edit_context": "## AgentFlow 编辑上下文",