@fieldwangai/agentflow 0.1.153 → 0.1.156

package/bin/lib/marketplace.mjs

@@ -8,7 +8,16 @@ import {
   MARKETPLACE_PACKAGES_DIR,
   PIPELINES_DIR,
   getUserPipelinesRoot,
+  isFlowDir,
 } from "./paths.mjs";
+import { NODE_PACKAGE_ENTRY, isNodePackageDir, readNodePackageManifest } from "./node-package-manifest.mjs";
+import {
+  NODE_PACKAGE_METADATA_FILENAME,
+  createNodePackageArchive,
+  inspectNodePackageArchive,
+  inspectNodePackageDirectory,
+  writeNodePackageFiles,
+} from "./node-package-archive.mjs";
 
 const NODE_MANIFEST = "node.yaml";
 const COLLECTION_MANIFEST = "collection.yaml";
@@ -80,6 +89,21 @@ function normalizeSlotList(value) {
   });
 }
 
+/**
+ * 读取节点包清单：`index.mjs` 的静态声明优先，回退 `node.yaml`。
+ * 声明写得不合法时不静默吞掉——按目录名报错，否则节点会莫名从面板消失。
+ */
+function readNodeManifestRaw(dir) {
+  try {
+    const manifest = readNodePackageManifest(dir, readYamlObject);
+    const metadata = readJsonObject(path.join(dir, NODE_PACKAGE_METADATA_FILENAME));
+    return manifest && metadata ? { ...manifest, ...metadata } : manifest;
+  } catch (e) {
+    console.warn(`[agentflow] 节点包 ${path.basename(dir)} 清单无效：${(e && e.message) || e}`);
+    return null;
+  }
+}
+
 function normalizeManifest(raw, packageDir, source = "workspace") {
   if (!raw || typeof raw !== "object") return null;
   const id = raw.id != null ? String(raw.id).trim() : path.basename(packageDir);
@@ -187,7 +211,7 @@ function collectFlowDirs(rootDir, source, archived = false) {
   for (const entry of entries) {
     if (!entry.isDirectory() || entry.name === ARCHIVED_PIPELINES_DIR_NAME) continue;
     const dir = path.join(rootDir, entry.name);
-    if (!fs.existsSync(path.join(dir, "flow.yaml"))) continue;
+    if (!isFlowDir(dir)) continue;
     out.push({ flowId: entry.name, flowSource: source, archived, flowDir: dir });
   }
   return out;
@@ -263,11 +287,11 @@ function findNodePackageDir(workspaceRoot, id, version) {
   const nodeBase = path.join(root, "nodes", id);
   if (version) {
     const direct = path.join(nodeBase, version);
-    if (fs.existsSync(path.join(direct, NODE_MANIFEST))) return direct;
+    if (isNodePackageDir(direct)) return direct;
   } else {
     for (const v of sortVersionsDesc(listVersionDirs(nodeBase))) {
       const direct = path.join(nodeBase, v);
-      if (fs.existsSync(path.join(direct, NODE_MANIFEST))) return direct;
+      if (isNodePackageDir(direct)) return direct;
     }
   }
   return null;
@@ -289,13 +313,13 @@ function iterCollectionNodeDirs(workspaceRoot, collectionDeps = []) {
       for (const entry of fs.readdirSync(nodesRoot, { withFileTypes: true })) {
         if (!entry.isDirectory()) continue;
         const direct = path.join(nodesRoot, entry.name);
-        if (fs.existsSync(path.join(direct, NODE_MANIFEST))) {
+        if (isNodePackageDir(direct)) {
           out.push(direct);
           continue;
         }
         for (const nodeVersion of sortVersionsDesc(listVersionDirs(direct))) {
           const versioned = path.join(direct, nodeVersion);
-          if (fs.existsSync(path.join(versioned, NODE_MANIFEST))) out.push(versioned);
+          if (isNodePackageDir(versioned)) out.push(versioned);
         }
       }
     }
@@ -317,6 +341,13 @@ function dependencyVersion(flowData, id) {
   return null;
 }
 
+/**
+ * 只读，没有写入方——写 `agentflow.lock.json` 的是已删除的 `install-node`。
+ *
+ * 留着是因为磁盘上仍可能有它当年写下的锁文件，那些流程的版本钉应该继续生效。代码化流程
+ * 不依赖它：版本钉在实例的 `marketplaceRef`（`marketplace:<id>@<version>`）上，解析时
+ * `parsed.version` 先命中，这条兜底根本走不到。
+ */
 function lockVersion(flowDir, id) {
   const lock = readJsonObject(path.join(flowDir, LOCK_FILENAME));
   const entry = lock && lock.nodes && lock.nodes[id];
@@ -330,18 +361,58 @@ function collectionDeps(flowData) {
   return deps && Array.isArray(deps.collections) ? deps.collections : [];
 }
 
+/**
+ * flow 自带的代码节点包：`<flowDir>/nodes/<dirName>/`，不带版本子目录。
+ *
+ * 这类包跟着 flow 走——AI 生成流程时可以顺手把节点实现写在流程目录里，不必先发布到
+ * marketplace。id 以包声明为准（目录名只是回退），所以目录名和 id 可以不一致。
+ */
+function findFlowLocalNodePackageDir(flowDir, id, requestedVersion) {
+  const nodesRoot = flowDir ? path.join(path.resolve(flowDir), "nodes") : "";
+  if (!nodesRoot || !fs.existsSync(nodesRoot) || !fs.statSync(nodesRoot).isDirectory()) return null;
+  for (const entry of fs.readdirSync(nodesRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const dir = path.join(nodesRoot, entry.name);
+    if (!isNodePackageDir(dir)) continue;
+    const manifest = normalizeManifest(readNodeManifestRaw(dir), dir, "flow");
+    if (!manifest || manifest.id !== id) continue;
+    if (requestedVersion && manifest.version !== requestedVersion) continue;
+    return dir;
+  }
+  return null;
+}
+
+/**
+ * 列出一个 `nodes/` 目录下的所有代码节点包（子目录形式，不带版本层）。
+ * 供节点目录把 flow 自带的节点一起摆进面板。
+ */
+export function listNodePackagesInDir(nodesRoot) {
+  const out = [];
+  const root = String(nodesRoot || "");
+  if (!root || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) return out;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const dir = path.join(root, entry.name);
+    if (!isNodePackageDir(dir)) continue;
+    const manifest = normalizeManifest(readNodeManifestRaw(dir), dir, "flow");
+    if (manifest) out.push(manifest);
+  }
+  return out.sort((a, b) => a.id.localeCompare(b.id));
+}
+
 export function resolveMarketplaceNodePackage(workspaceRoot, flowDir, definitionId, flowData = null, opts = {}) {
   const parsed = parseMarketplaceDefinitionId(definitionId);
   if (!parsed) return null;
   const id = parsed.id;
   const requestedVersion = parsed.version || dependencyVersion(flowData, id) || lockVersion(flowDir, id);
-  let packageDir = findNodePackageDir(workspaceRoot, id, requestedVersion);
-  let packageSource = "marketplace";
+  // flow 自带的包优先：流程目录里的实现就是这个流程要用的那份，不该被同名的已发布包顶掉
+  let packageDir = findFlowLocalNodePackageDir(flowDir, id, requestedVersion);
+  let packageSource = packageDir ? "flow" : "marketplace";
+  if (!packageDir) packageDir = findNodePackageDir(workspaceRoot, id, requestedVersion);
 
   if (!packageDir) {
     for (const dir of iterCollectionNodeDirs(workspaceRoot, collectionDeps(flowData))) {
-      const raw = readYamlObject(path.join(dir, NODE_MANIFEST));
-      const manifest = normalizeManifest(raw, dir, "collection");
+      const manifest = normalizeManifest(readNodeManifestRaw(dir), dir, "collection");
       if (!manifest || manifest.id !== id) continue;
       if (requestedVersion && manifest.version !== requestedVersion) continue;
       packageDir = dir;
@@ -351,7 +422,7 @@ export function resolveMarketplaceNodePackage(workspaceRoot, flowDir, definition
   }
 
   if (!packageDir) return null;
-  const manifest = normalizeManifest(readYamlObject(path.join(packageDir, NODE_MANIFEST)), packageDir, packageSource);
+  const manifest = normalizeManifest(readNodeManifestRaw(packageDir), packageDir, packageSource);
   if (!manifest) return null;
   if (!canAccessMarketplaceNode(manifest, opts)) return null;
   return {
@@ -366,7 +437,7 @@ export function listMarketplaceNodes(workspaceRoot, flowData = null, opts = {})
   const out = [];
   const seen = new Set();
   const addManifest = (dir, source = "marketplace") => {
-    const manifest = normalizeManifest(readYamlObject(path.join(dir, NODE_MANIFEST)), dir, source);
+    const manifest = normalizeManifest(readNodeManifestRaw(dir), dir, source);
     if (!manifest) return;
     if (!canAccessMarketplaceNode(manifest, opts)) return;
     const key = `${manifest.id}@${manifest.version}`;
@@ -404,6 +475,15 @@ export function listMarketplacePackages(workspaceRoot, opts = {}) {
     inputs: n.input,
     outputs: n.output,
     packagedFiles: Array.isArray(n.packagedFiles) ? n.packagedFiles : [],
+    fileList: Array.isArray(n.fileList) ? n.fileList : [],
+    fileCount: Number(n.fileCount) || 0,
+    totalBytes: Number(n.totalBytes) || 0,
+    contentSha256: String(n.contentSha256 || ""),
+    archiveSha256: String(n.archiveSha256 || ""),
+    installedFrom: String(n.installedFrom || ""),
+    installedAt: String(n.installedAt || ""),
+    ownerUserId: n.ownerUserId || n.createdBy || "",
+    createdBy: n.createdBy || n.ownerUserId || "",
     packageDir: n.packageDir,
     usage: listMarketplaceNodeUsages(workspaceRoot, n.id, n.version, opts),
   }));
@@ -519,42 +599,126 @@ export function deleteMarketplaceFlowSnippetPackage(workspaceRoot, id, version,
   return { ok: true, id, version, packageDir };
 }
 
-export function writeFlowMarketplaceLock(workspaceRoot, flowDir, flowData, opts = {}) {
-  if (!flowData || !flowData.instances || typeof flowData.instances !== "object") return null;
-  const nodes = {};
-  for (const inst of Object.values(flowData.instances)) {
-    const defId = inst && (inst.marketplaceRef || inst.definitionId);
-    const resolved = resolveMarketplaceNodePackage(workspaceRoot, flowDir, defId, flowData, opts);
-    if (!resolved) continue;
-    nodes[resolved.id] = {
-      version: resolved.version,
-      resolved: path.relative(flowDir, resolved.packageDir).replace(/\\/g, "/"),
-      definitionId: resolved.resolvedDefinitionId,
-    };
-  }
-  const lockPath = path.join(flowDir, LOCK_FILENAME);
-  if (Object.keys(nodes).length === 0) return null;
-  const lock = readJsonObject(lockPath) || {};
-  const next = {
-    ...lock,
-    version: 1,
-    updatedAt: new Date().toISOString(),
-    nodes: { ...(lock.nodes && typeof lock.nodes === "object" ? lock.nodes : {}), ...nodes },
-  };
-  fs.writeFileSync(lockPath, JSON.stringify(next, null, 2) + "\n", "utf-8");
-  return next;
-}
 
-export function publishNodePackage(workspaceRoot, sourceDir) {
+export function publishNodePackage(workspaceRoot, sourceDir, opts = {}) {
   const src = path.resolve(sourceDir);
-  const manifestPath = path.join(src, NODE_MANIFEST);
-  const manifest = normalizeManifest(readYamlObject(manifestPath), src);
-  if (!manifest) return { ok: false, error: `Invalid node package manifest: ${manifestPath}` };
-  const dest = path.join(workspacePackageRoot(workspaceRoot), "nodes", manifest.id, manifest.version);
+  // 走和读取同一条路径：`index.mjs` 的静态声明优先，回落 `node.yaml`。只认后者的话，
+  // 一个目录扫描、面板、运行时都跑得通的 index.mjs 包偏偏发布不出去。
+  const inspected = inspectNodePackageDirectory(src, { allowLegacyManifest: true });
+  if (!inspected.ok) return inspected;
+  const manifest = normalizeManifest(inspected.manifest, src);
+  if (!manifest) return { ok: false, error: `Invalid node package manifest: ${src}` };
+  const dest = resolveWorkspaceNodePackageDir(workspaceRoot, manifest.id, manifest.version);
+  if (!dest) return { ok: false, error: "Invalid marketplace node id or version" };
+  const existing = fs.existsSync(dest) ? inspectNodePackageDirectory(dest, { allowLegacyManifest: true }) : null;
+  if (existing?.ok && existing.contentSha256 === inspected.contentSha256) {
+    return {
+      ok: true,
+      alreadyExists: true,
+      id: manifest.id,
+      version: manifest.version,
+      packageDir: dest,
+      definitionId: manifest.definitionId,
+      contentSha256: inspected.contentSha256,
+      fileList: inspected.fileList,
+    };
+  }
+  if (existing?.ok && opts.immutable === true) {
+    return { ok: false, conflict: true, error: `${manifest.id}@${manifest.version} 已存在且内容不同，请提升版本号` };
+  }
   fs.mkdirSync(path.dirname(dest), { recursive: true });
   fs.rmSync(dest, { recursive: true, force: true });
   fs.cpSync(src, dest, { recursive: true });
-  return { ok: true, id: manifest.id, version: manifest.version, packageDir: dest, definitionId: manifest.definitionId };
+  const ownerUserId = String(opts.ownerUserId || opts.userId || manifest.ownerUserId || manifest.createdBy || "").trim();
+  fs.writeFileSync(path.join(dest, NODE_PACKAGE_METADATA_FILENAME), `${JSON.stringify({
+    ...(ownerUserId ? { ownerUserId, createdBy: ownerUserId } : {}),
+    contentSha256: inspected.contentSha256,
+    fileList: inspected.fileList,
+    fileCount: inspected.fileCount,
+    totalBytes: inspected.totalBytes,
+    publishedAt: new Date().toISOString(),
+  }, null, 2)}\n`, "utf-8");
+  return {
+    ok: true,
+    id: manifest.id,
+    version: manifest.version,
+    packageDir: dest,
+    definitionId: manifest.definitionId,
+    contentSha256: inspected.contentSha256,
+    fileList: inspected.fileList,
+  };
+}
+
+export function publishNodePackageArchive(workspaceRoot, archiveInput, opts = {}) {
+  const inspected = inspectNodePackageArchive(archiveInput);
+  if (!inspected.ok) return inspected;
+  const manifest = normalizeManifest(inspected.manifest, "");
+  if (!manifest) return { ok: false, error: "Invalid node package manifest" };
+  const dest = resolveWorkspaceNodePackageDir(workspaceRoot, manifest.id, manifest.version);
+  if (!dest) return { ok: false, error: "Invalid marketplace node id or version" };
+  const existing = fs.existsSync(dest) ? inspectNodePackageDirectory(dest) : null;
+  if (existing?.ok) {
+    if (existing.contentSha256 !== inspected.contentSha256) {
+      return { ok: false, conflict: true, error: `${manifest.id}@${manifest.version} 已存在且内容不同，请提升版本号` };
+    }
+    return {
+      ok: true,
+      alreadyExists: true,
+      id: manifest.id,
+      version: manifest.version,
+      definitionId: manifest.definitionId,
+      packageDir: dest,
+      contentSha256: inspected.contentSha256,
+      archiveSha256: inspected.archiveSha256,
+      fileList: inspected.fileList,
+    };
+  }
+  const parent = path.dirname(dest);
+  fs.mkdirSync(parent, { recursive: true });
+  // 先在同一父目录完整写好再 rename。这样进程中断或磁盘异常时不会留下一个被目录扫描到、
+  // 但脚本只写了一半的版本。
+  const staging = fs.mkdtempSync(path.join(parent, `.${manifest.version}.installing-`));
+  const ownerUserId = String(opts.ownerUserId || opts.userId || "").trim();
+  const installedFrom = String(opts.installedFrom || "").trim();
+  const installedAt = String(opts.installedAt || "").trim();
+  try {
+    const written = writeNodePackageFiles(staging, inspected.files);
+    if (!written.ok) return written;
+    fs.writeFileSync(path.join(staging, NODE_PACKAGE_METADATA_FILENAME), `${JSON.stringify({
+      ...(ownerUserId ? { ownerUserId, createdBy: ownerUserId } : {}),
+      contentSha256: inspected.contentSha256,
+      archiveSha256: inspected.archiveSha256,
+      fileList: inspected.fileList,
+      fileCount: inspected.fileCount,
+      totalBytes: inspected.totalBytes,
+      publishedAt: new Date().toISOString(),
+      ...(installedFrom ? { installedFrom } : {}),
+      ...(installedAt ? { installedAt } : {}),
+    }, null, 2)}\n`, "utf-8");
+    fs.renameSync(staging, dest);
+  } catch (error) {
+    return { ok: false, error: error?.message || String(error) };
+  } finally {
+    if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
+  }
+  return {
+    ok: true,
+    id: manifest.id,
+    version: manifest.version,
+    definitionId: manifest.definitionId,
+    packageDir: dest,
+    contentSha256: inspected.contentSha256,
+    archiveSha256: inspected.archiveSha256,
+    fileList: inspected.fileList,
+  };
+}
+
+export function nodePackageArchive(workspaceRoot, id, version, opts = {}) {
+  const packageDir = resolveWorkspaceNodePackageDir(workspaceRoot, id, version);
+  if (!packageDir || !fs.existsSync(packageDir)) return { ok: false, error: `Node package not found: ${id}@${version}` };
+  const manifest = normalizeManifest(readNodeManifestRaw(packageDir), packageDir, "marketplace");
+  if (!manifest || !canAccessMarketplaceNode(manifest, opts)) return { ok: false, error: "Node package permission denied" };
+  return createNodePackageArchive(packageDir);
 }
 
 function safePackageId(raw) {
@@ -907,22 +1071,3 @@ export function publishFlowSnippet(workspaceRoot, payload = {}, opts = {}) {
   );
   return { ok: true, id, version, packageDir: dest, snippet: manifest.snippet };
 }
-
-export function installFlowDependency(workspaceRoot, flowDir, spec, opts = {}) {
-  const parsed = parseMarketplaceDefinitionId(spec.startsWith("marketplace:") ? spec : `marketplace:${spec}`);
-  if (!parsed) return { ok: false, error: `Invalid marketplace node spec: ${spec}` };
-  const resolved = resolveMarketplaceNodePackage(workspaceRoot, flowDir, `marketplace:${parsed.id}${parsed.version ? `@${parsed.version}` : ""}`, { dependencies: {} }, opts);
-  if (!resolved) return { ok: false, error: `Marketplace node not found: ${spec}` };
-
-  const flowYamlPath = path.join(flowDir, "flow.yaml");
-  const data = readYamlObject(flowYamlPath);
-  if (!data) return { ok: false, error: `Invalid flow.yaml: ${flowYamlPath}` };
-  const deps = data.dependencies && typeof data.dependencies === "object" ? data.dependencies : {};
-  const nodes = Array.isArray(deps.nodes) ? deps.nodes : [];
-  const exists = nodes.some((item) => (typeof item === "string" ? item === resolved.id : item && item.id === resolved.id));
-  if (!exists) nodes.push({ id: resolved.id, version: resolved.version });
-  data.dependencies = { ...deps, nodes };
-  fs.writeFileSync(flowYamlPath, yaml.dump(data, { lineWidth: -1 }), "utf-8");
-  writeFlowMarketplaceLock(workspaceRoot, flowDir, data, opts);
-  return { ok: true, id: resolved.id, version: resolved.version, definitionId: `marketplace:${resolved.id}@${resolved.version}` };
-}

package/bin/lib/model-config.mjs

@@ -150,3 +150,13 @@ export function resolveCliAndModel(workspaceRoot, nodeModel, agentModelOverride)
     label: model === "Auto" ? "cursor: Auto" : `cursor: ${model}`,
   };
 }
+
+/** 解析 `api:<provider>/<model>` 形式的模型串；无 provider 时默认 openai。 */
+export function parseApiModel(str) {
+  const s = String(str ?? "").replace(/^api:/, "");
+  const slash = s.indexOf("/");
+  if (slash < 0) return { provider: "openai", model: s };
+  const provider = s.slice(0, slash).toLowerCase();
+  const model = s.slice(slash + 1);
+  return { provider, model };
+}

package/bin/lib/node-package-archive.mjs

@@ -0,0 +1,240 @@
+/**
+ * Portable node-package archives.
+ *
+ * On disk a node package is a directory. ZIP is only the transport form. The
+ * archive always has `index.mjs` at its root and may contain relative scripts,
+ * templates, and assets. We validate paths and size limits before either
+ * packing or installing so an uploaded package cannot escape its destination.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { unzipSync, zipSync } from "fflate";
+import yaml from "js-yaml";
+
+import {
+  NODE_PACKAGE_ENTRY,
+  nodePackageExportsRun,
+  readNodePackageManifest,
+} from "./node-package-manifest.mjs";
+
+export const NODE_PACKAGE_MAX_UNCOMPRESSED_BYTES = 8 * 1024 * 1024;
+export const NODE_PACKAGE_MAX_FILE_ENTRIES = 500;
+export const NODE_PACKAGE_MAX_ARCHIVE_BYTES = 10 * 1024 * 1024;
+export const NODE_PACKAGE_METADATA_FILENAME = ".agentflow-package.json";
+
+const FORBIDDEN_SEGMENTS = new Set([
+  ".git",
+  ".ssh",
+  "__MACOSX",
+  "node_modules",
+]);
+const FORBIDDEN_FILES = new Set([
+  ".env",
+  ".env.local",
+  ".npmrc",
+  ".DS_Store",
+  NODE_PACKAGE_METADATA_FILENAME,
+  "id_rsa",
+  "id_ed25519",
+]);
+
+export function sanitizeNodePackageEntryPath(raw) {
+  if (typeof raw !== "string") return null;
+  // ZIP 规范只使用 `/`。不能把绝对路径或反斜杠悄悄“修正”为相对路径，否则两个不同的
+  // archive entry 可能在安装时落到同一个文件，路径穿越也会从拒绝变成接受。
+  const value = raw.replace(/^\uFEFF/, "");
+  if (!value || value.includes("\0") || value.includes("\\") || value.startsWith("/") || /^[A-Za-z]:/.test(value)) return null;
+  const parts = value.split("/").filter(Boolean);
+  if (!parts.length || parts.some((part) => part === "." || part === "..")) return null;
+  if (parts.some((part) => FORBIDDEN_SEGMENTS.has(part))) return null;
+  const base = parts.at(-1);
+  if (FORBIDDEN_FILES.has(base) || /^\.env\./.test(base) || /\.(?:pem|key|p12|pfx)$/i.test(base)) return null;
+  if (parts.some((part) => part.startsWith("._"))) return null;
+  return parts.join("/");
+}
+
+function stableContentHash(files) {
+  const hash = crypto.createHash("sha256");
+  for (const [rel, content] of [...files.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    hash.update(rel);
+    hash.update("\0");
+    hash.update(content);
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+function validateFilesMap(files, opts = {}) {
+  if (!(files instanceof Map) || files.size === 0) {
+    return { ok: false, error: "节点包内没有文件" };
+  }
+  if (files.size > NODE_PACKAGE_MAX_FILE_ENTRIES) {
+    return { ok: false, error: `节点包文件数量超过限制（最多 ${NODE_PACKAGE_MAX_FILE_ENTRIES} 个）` };
+  }
+  let totalBytes = 0;
+  for (const [rel, content] of files) {
+    const safe = sanitizeNodePackageEntryPath(rel);
+    if (!safe || safe !== rel) return { ok: false, error: `节点包包含非法或敏感路径：${rel}` };
+    totalBytes += content.length;
+    if (totalBytes > NODE_PACKAGE_MAX_UNCOMPRESSED_BYTES) {
+      return { ok: false, error: "节点包解压后总大小超过限制（8MB）" };
+    }
+  }
+  if (!files.has(NODE_PACKAGE_ENTRY) && !(opts.allowLegacyManifest && files.has("node.yaml"))) {
+    return { ok: false, error: `节点包根目录缺少 ${NODE_PACKAGE_ENTRY}（旧包可使用 node.yaml）` };
+  }
+  return { ok: true, totalBytes };
+}
+
+function collectDirectoryFiles(packageDir) {
+  const root = path.resolve(packageDir);
+  const files = new Map();
+  const walk = (dir) => {
+    const entries = fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      if (entry.name === NODE_PACKAGE_METADATA_FILENAME) continue;
+      const abs = path.join(dir, entry.name);
+      const stat = fs.lstatSync(abs);
+      if (stat.isSymbolicLink()) throw new Error(`节点包不允许符号链接：${path.relative(root, abs)}`);
+      const rel = path.relative(root, abs).replace(/\\/g, "/");
+      const safe = sanitizeNodePackageEntryPath(rel);
+      if (!safe || safe !== rel) throw new Error(`节点包包含非法或敏感路径：${rel}`);
+      if (stat.isDirectory()) {
+        walk(abs);
+      } else if (stat.isFile()) {
+        files.set(rel, fs.readFileSync(abs));
+      }
+    }
+  };
+  walk(root);
+  return files;
+}
+
+function manifestFromTemporaryFiles(files, opts = {}) {
+  const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "agentflow-node-package-"));
+  try {
+    for (const [rel, content] of files) {
+      const abs = path.join(tempRoot, ...rel.split("/"));
+      fs.mkdirSync(path.dirname(abs), { recursive: true });
+      fs.writeFileSync(abs, content);
+    }
+    const manifest = readNodePackageManifest(tempRoot, (yamlPath) => {
+      if (!opts.allowLegacyManifest || !fs.existsSync(yamlPath)) return null;
+      const parsed = yaml.load(fs.readFileSync(yamlPath, "utf-8"));
+      return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
+    });
+    if (!manifest) return { ok: false, error: `${NODE_PACKAGE_ENTRY} 缺少有效的 export default 声明，node.yaml 也无有效清单` };
+    if (files.has(NODE_PACKAGE_ENTRY) && !nodePackageExportsRun(path.join(tempRoot, NODE_PACKAGE_ENTRY))) {
+      return { ok: false, error: `${NODE_PACKAGE_ENTRY} 缺少 export function run` };
+    }
+    return { ok: true, manifest };
+  } catch (error) {
+    return { ok: false, error: error?.message || String(error) };
+  } finally {
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+  }
+}
+
+export function inspectNodePackageDirectory(packageDir, opts = {}) {
+  try {
+    const root = path.resolve(packageDir);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+      return { ok: false, error: `节点包目录不存在：${root}` };
+    }
+    const files = collectDirectoryFiles(root);
+    const checked = validateFilesMap(files, opts);
+    if (!checked.ok) return checked;
+    const parsed = manifestFromTemporaryFiles(files, opts);
+    if (!parsed.ok) return parsed;
+    return {
+      ok: true,
+      packageDir: root,
+      manifest: parsed.manifest,
+      files,
+      fileList: [...files.keys()].sort(),
+      fileCount: files.size,
+      totalBytes: checked.totalBytes,
+      contentSha256: stableContentHash(files),
+    };
+  } catch (error) {
+    return { ok: false, error: error?.message || String(error) };
+  }
+}
+
+export function createNodePackageArchive(packageDir) {
+  const inspected = inspectNodePackageDirectory(packageDir);
+  if (!inspected.ok) return inspected;
+  const entries = Object.fromEntries([...inspected.files].map(([rel, content]) => [rel, new Uint8Array(content)]));
+  const archive = Buffer.from(zipSync(entries, { level: 6 }));
+  if (archive.length > NODE_PACKAGE_MAX_ARCHIVE_BYTES) {
+    return { ok: false, error: "节点包 ZIP 超过限制（10MB）" };
+  }
+  return {
+    ...inspected,
+    archive,
+    archiveSha256: crypto.createHash("sha256").update(archive).digest("hex"),
+  };
+}
+
+function stripOptionalRoot(files) {
+  const roots = new Set([...files.keys()].map((rel) => rel.split("/")[0]));
+  if (roots.size !== 1 || files.has(NODE_PACKAGE_ENTRY)) return files;
+  const [root] = [...roots];
+  const prefix = `${root}/`;
+  if (!files.has(`${prefix}${NODE_PACKAGE_ENTRY}`)) return files;
+  return new Map([...files].map(([rel, content]) => [rel.slice(prefix.length), content]));
+}
+
+export function inspectNodePackageArchive(input) {
+  try {
+    const archive = Buffer.from(input || []);
+    if (!archive.length) return { ok: false, error: "节点包 ZIP 为空" };
+    if (archive.length > NODE_PACKAGE_MAX_ARCHIVE_BYTES) return { ok: false, error: "节点包 ZIP 超过限制（10MB）" };
+    const raw = unzipSync(new Uint8Array(archive));
+    let files = new Map();
+    for (const [rawRel, value] of Object.entries(raw)) {
+      if (rawRel.endsWith("/")) continue;
+      const rel = sanitizeNodePackageEntryPath(rawRel);
+      if (!rel) return { ok: false, error: `节点包包含非法或敏感路径：${rawRel}` };
+      if (files.has(rel)) return { ok: false, error: `节点包包含重复路径：${rawRel}` };
+      files.set(rel, Buffer.from(value));
+    }
+    files = stripOptionalRoot(files);
+    const checked = validateFilesMap(files);
+    if (!checked.ok) return checked;
+    const parsed = manifestFromTemporaryFiles(files);
+    if (!parsed.ok) return parsed;
+    return {
+      ok: true,
+      manifest: parsed.manifest,
+      files,
+      fileList: [...files.keys()].sort(),
+      fileCount: files.size,
+      totalBytes: checked.totalBytes,
+      contentSha256: stableContentHash(files),
+      archiveSha256: crypto.createHash("sha256").update(archive).digest("hex"),
+      archive,
+    };
+  } catch (error) {
+    return { ok: false, error: `节点包 ZIP 解析失败：${error?.message || String(error)}` };
+  }
+}
+
+export function writeNodePackageFiles(targetDir, files) {
+  const target = path.resolve(targetDir);
+  const checked = validateFilesMap(files);
+  if (!checked.ok) return checked;
+  fs.mkdirSync(target, { recursive: true });
+  for (const [rel, content] of files) {
+    const abs = path.resolve(target, ...rel.split("/"));
+    if (abs !== target && !abs.startsWith(`${target}${path.sep}`)) {
+      return { ok: false, error: `节点包路径越界：${rel}` };
+    }
+    fs.mkdirSync(path.dirname(abs), { recursive: true });
+    fs.writeFileSync(abs, content);
+  }
+  return { ok: true, totalBytes: checked.totalBytes };
+}