@fieldwangai/agentflow 0.1.25

package/bin/pipeline/pre-process-node.mjs

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+/**
+ * 统一预处理入口：对当前节点做 ${} 替换并生成 prompt.md；读取 role / model 并计算 subagent。
+ * 用法：node pre-process-node.mjs <workspaceRoot> <flowName> <uuid> <instanceId>
+ * 输出（stdout JSON）：{ "ok": true, "promptPath": "...", "optionalPromptPath"?: "...", "directCommand"?: "...", "subagent": "...", "definitionId": "...", "role"?: "...", "model"?: "..." }
+ * definitionId 供 CLI 做 LOCAL_ONLY 判断；directCommand 供 CLI 直接执行并跳过 agent（与 optionalPromptPath 语义一致，仅 CLI 使用）。
+ *
+ * 当前 pre-process 流程与 cache 的关系：
+ *
+ * 1) 公共开头：从 memory 加载 execId（+1 作为本轮），得到 runDir、resultPathRel；读 flow.json 得 definitionId。
+ *
+ * 2) 分支 A（definitionId === "control_if"）：
+ *    - 用 getResolvedValues + 第一个 bool 槽取值 → parseBool → branch；
+ *    - writeResult(success, branch)；
+ *    - buildNodePrompt → writeCacheJsonForNode（统一写 .cache.json）→ 写 noop prompt，设 optionalPromptPath，return。
+ *
+ * 3) 分支 B（普通节点，含 control_toBool 走 tool_nodejs 同路径）：
+ *    - buildNodePrompt → writeResult("running") → writeCacheJsonForNode（统一写 .cache.json）；
+ *    - 若有 tool_load_key/tool_save_key/tool_get_env/control_anyOne 再设 optionalPromptPath，并视情况输出 directCommand 供 CLI 执行；
+ *    - 返回 promptPath、resultPath、execId、subagent 等。
+ *
+ * cache.json 流程已统一：control_if 与普通节点均通过 writeCacheJsonForNode 在「prompt 已存在」的前提下执行 computeCacheMd5 并写入 intermediate/<instanceId>/<instanceId>.cache.json，结构一致（含 cacheMd5、cacheInputInfo、execId、inputHandlerExecIds、payload）。
+ */
+
+import { spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+
+import { loadFlowDefinition } from "./parse-flow.mjs";
+import { buildNodePrompt } from "./build-node-prompt.mjs";
+import { snapshotPriorRoundIfNeeded } from "./snapshot-prior-round.mjs";
+import { computeCacheMd5 } from "./compute-cache-md5.mjs";
+import { getResolvedValues } from "./get-resolved-values.mjs";
+import { parseBool, getFirstBoolInputValue } from "./parse-bool.mjs";
+import { writeResult } from "./write-result.mjs";
+import { intermediateResultBasename, intermediateCacheBasename, intermediateDirForNode, outputNodeBasename, outputDirForNode } from "./get-exec-id.mjs";
+import { logToRunTag } from "./run-log.mjs";
+import { getRunDir } from "../lib/paths.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const ROLE_TO_SUBAGENT = {
+  requirement: "agentflow-node-executor-requirement",
+  planning: "agentflow-node-executor-planning",
+  code: "agentflow-node-executor-code",
+  test: "agentflow-node-executor-test",
+  normal: "agentflow-node-executor",
+  求拆解: "agentflow-node-executor-requirement",
+  技术规划: "agentflow-node-executor-planning",
+  代码执行: "agentflow-node-executor-code",
+  测试回归: "agentflow-node-executor-test",
+  普通: "agentflow-node-executor",
+};
+
+function readFlowJson(workspaceRoot, flowName, uuid) {
+  const flowJsonPath = path.join(getRunDir(workspaceRoot, flowName, uuid), "intermediate", "flow.json");
+  if (!fs.existsSync(flowJsonPath)) return null;
+  try {
+    const flow = JSON.parse(fs.readFileSync(flowJsonPath, "utf-8"));
+    return flow?.ok && Array.isArray(flow.nodes) ? flow : null;
+  } catch {
+    return null;
+  }
+}
+
+function getRoleAndModelFromFlowJson(workspaceRoot, flowName, uuid, instanceId) {
+  const flow = readFlowJson(workspaceRoot, flowName, uuid);
+  if (!flow || !Array.isArray(flow.nodes)) {
+    return { role: "普通", model: null };
+  }
+  const node = flow.nodes.find((n) => n.id === instanceId) || null;
+  const roleRaw = node && node.role != null ? String(node.role).trim() : "";
+  const modelRaw = node && node.model != null ? String(node.model).trim() : "";
+  const role = roleRaw || "普通";
+  const model = modelRaw || null;
+  return { role, model };
+}
+
+/** 从 flow.json 读取节点 definitionId，优先 node.definitionId，回退 nodeDefinitions[instanceId]（start/end 等可据此做本地跳过） */
+function getDefinitionIdFromFlowJson(workspaceRoot, flowName, uuid, instanceId) {
+  const flow = readFlowJson(workspaceRoot, flowName, uuid);
+  if (!flow) return null;
+  const node = flow.nodes.find((n) => n.id === instanceId);
+  return node?.definitionId ?? flow.nodeDefinitions?.[instanceId] ?? null;
+}
+
+/**
+ * 统一：根据当前 prompt 文件 + resolvedInputs + 上游 cache 算 MD5 并写 intermediate/<instanceId>/<instanceId>.cache.json。
+ * 调用前需保证 buildNodePrompt 已执行（prompt 文件已存在）。control_if 与普通节点共用此流程。
+ */
+function writeCacheJsonForNode(workspaceRoot, flowName, uuid, instanceId, execId) {
+  const runDir = getRunDir(workspaceRoot, flowName, uuid);
+  const cache = computeCacheMd5(workspaceRoot, flowName, uuid, instanceId, execId);
+  if (!cache.ok || (!cache.cacheMd5 && !cache.cacheInputInfo)) return;
+  const nodeIntermediateDir = path.join(runDir, intermediateDirForNode(instanceId));
+  fs.mkdirSync(nodeIntermediateDir, { recursive: true });
+  const cachePath = path.join(nodeIntermediateDir, intermediateCacheBasename(instanceId, execId));
+  const cacheObj = {
+    cacheMd5: cache.cacheMd5,
+    cacheInputInfo: cache.cacheInputInfo,
+    execId,
+  };
+  if (cache.inputHandlerExecIds != null && Object.keys(cache.inputHandlerExecIds).length > 0) {
+    cacheObj.inputHandlerExecIds = cache.inputHandlerExecIds;
+  }
+  if (cache.payload !== undefined) cacheObj.payload = cache.payload;
+  // 备份由 snapshotPriorRoundIfNeeded 统一在 pre-process 入口完成；此处只管写新 cache。
+  fs.writeFileSync(cachePath, JSON.stringify(cacheObj, null, 0), "utf-8");
+  logToRunTag(workspaceRoot, flowName, uuid, "pre-process", {
+    event: "cache-written",
+    instanceId,
+    cacheMd5: cache.cacheMd5,
+    cachePath: path.join(intermediateDirForNode(instanceId), intermediateCacheBasename(instanceId, execId)),
+  });
+}
+
+/**
+ * Bash 单引号包裹任意参数：单引号内无命令替换/变量展开，避免 save_key 的 value 含反引号、`$()`、换行时把整段当 shell 执行。
+ * 用法：'it'\''s' 表示 it's
+ */
+function bashSingleQuote(s) {
+  if (s == null) return "''";
+  return "'" + String(s).replace(/'/g, "'\\''") + "'";
+}
+
+/**
+ * 若为 tool_load_key / tool_save_key / tool_get_env，写入「直接执行 agentflow apply -ai run-tool-nodejs + 对应脚本」的 prompt，
+ * key/value 从 getResolvedValues 的 resolvedInputs 读取并拼入命令。
+ * 返回 { optionalPromptPath, directCommand }，供 AI 用 optionalPromptPath、CLI 用 directCommand 执行。
+ * @param {number} execId - 本轮 execId，传入 run-tool-nodejs 以写对 result 文件（第二轮起必须）
+ */
+function emitLoadSaveKeyOptionalPrompt(workspaceRoot, flowName, uuid, instanceId, definitionId, execId) {
+  if (definitionId !== "tool_load_key" && definitionId !== "tool_save_key" && definitionId !== "tool_get_env") return null;
+  const scriptName =
+    definitionId === "tool_load_key" ? "load-key.mjs"
+    : definitionId === "tool_save_key" ? "save-key.mjs"
+    : "get-env.mjs";
+  const runDir = getRunDir(workspaceRoot, flowName, uuid);
+  const nodeIntermediateDir = path.join(runDir, intermediateDirForNode(instanceId));
+  const promptFileName = `${instanceId}.run-key.prompt.md`;
+  const promptPath = path.join(nodeIntermediateDir, promptFileName);
+
+  let key = "";
+  let value = "";
+  const data = getResolvedValues(workspaceRoot, flowName, uuid, instanceId);
+  if (data.ok && data.resolvedInputs) {
+    const inputs = data.resolvedInputs;
+    key = inputs.key != null ? String(inputs.key).trim() : "";
+    value = inputs.value != null ? String(inputs.value).trim() : "";
+  }
+
+  const rootArg = workspaceRoot;
+  const q = bashSingleQuote;
+  const keyQ = q(key);
+  const directCommand =
+    definitionId === "tool_get_env"
+      ? `agentflow apply -ai get-env ${q(rootArg)} ${q(flowName)} ${q(uuid)} ${q(instanceId)} ${q(String(execId))} ${keyQ}`
+      : (() => {
+          const scriptArgs =
+            definitionId === "tool_load_key"
+              ? `${q(rootArg)} ${q(flowName)} ${q(uuid)} ${keyQ}`
+              : `${q(rootArg)} ${q(flowName)} ${q(uuid)} ${keyQ} ${q(value)}`;
+          const scriptPath = path.join(__dirname, definitionId === "tool_load_key" ? "load-key.mjs" : "save-key.mjs");
+          return `agentflow apply -ai run-tool-nodejs ${q(rootArg)} ${q(flowName)} ${q(uuid)} ${q(instanceId)} ${q(String(execId))} -- node ${q(scriptPath)} ${scriptArgs}`;
+        })();
+  const content = `此节点不调用 subagent，请主 agent 在工作区根目录直接执行以下命令完成该节点。
+
+\`\`\`bash
+${directCommand}
+\`\`\`
+`;
+
+  try {
+    fs.mkdirSync(nodeIntermediateDir, { recursive: true });
+    // 备份由 snapshotPriorRoundIfNeeded 统一处理
+    fs.writeFileSync(promptPath, content, "utf-8");
+  } catch (e) {
+    return null;
+  }
+  const relativePath = path.relative(workspaceRoot, promptPath);
+  return { optionalPromptPath: relativePath.replace(/\\/g, "/"), directCommand };
+}
+
+/**
+ * 若为 tool_nodejs 且 buildNodePrompt 返回了非空 script（来自 flow.yaml instance.script 字段），
+ * 生成 directCommand 直接通过 run-tool-nodejs 执行脚本，不调用 subagent。
+ * @param {string} resolvedScript - 已解析占位符且各参数已 shell-quote 的命令（run-tool-nodejs -- 之后的部分）
+ * @returns {{ optionalPromptPath: string, directCommand: string } | null}
+ */
+function emitToolNodejsDirectCommand(workspaceRoot, flowName, uuid, instanceId, resolvedScript, execId) {
+  const runDir = getRunDir(workspaceRoot, flowName, uuid);
+  const nodeIntermediateDir = path.join(runDir, intermediateDirForNode(instanceId));
+  const promptFileName = `${instanceId}.tool-nodejs-direct.prompt.md`;
+  const promptPath = path.join(nodeIntermediateDir, promptFileName);
+
+  const q = bashSingleQuote;
+  const directCommand = `agentflow apply -ai run-tool-nodejs ${q(workspaceRoot)} ${q(flowName)} ${q(uuid)} ${q(instanceId)} ${q(String(execId))} -- ${resolvedScript}`;
+  const content = `此节点为 tool_nodejs（直接执行模式），不调用 subagent，由流水线直接执行以下命令。
+
+\`\`\`bash
+${directCommand}
+\`\`\`
+`;
+
+  try {
+    fs.mkdirSync(nodeIntermediateDir, { recursive: true });
+    // 备份由 snapshotPriorRoundIfNeeded 统一处理
+    fs.writeFileSync(promptPath, content, "utf-8");
+  } catch (e) {
+    return null;
+  }
+  const relativePath = path.relative(workspaceRoot, promptPath);
+  return { optionalPromptPath: relativePath.replace(/\\/g, "/"), directCommand };
+}
+
+/**
+ * 若为 control_anyOne，写入「直接执行 write-result 将该节点标为 success」的 prompt，不调用 subagent。
+ * 返回 { optionalPromptPath, directCommand }，供 AI 用 optionalPromptPath、CLI 用 directCommand 执行。
+ */
+function emitAnyOneOptionalPrompt(workspaceRoot, flowName, uuid, instanceId, execId) {
+  const runDir = getRunDir(workspaceRoot, flowName, uuid);
+  const nodeIntermediateDir = path.join(runDir, intermediateDirForNode(instanceId));
+  const promptFileName = `${instanceId}.anyOne.prompt.md`;
+  const promptPath = path.join(nodeIntermediateDir, promptFileName);
+
+  const jsonPayload = JSON.stringify({
+    status: "success",
+    message: "任一前驱已就绪，直接通过",
+    execId,
+  });
+  const directCommand = `agentflow apply -ai write-result ${bashSingleQuote(workspaceRoot)} ${bashSingleQuote(flowName)} ${bashSingleQuote(uuid)} ${bashSingleQuote(instanceId)} --json ${bashSingleQuote(jsonPayload)}`;
+  const content = `此节点为 control_anyOne，不调用 subagent。请主 agent 在工作区根目录直接执行以下命令将该节点标记为 success。
+
+\`\`\`bash
+${directCommand}
+\`\`\`
+`;
+
+  try {
+    fs.mkdirSync(nodeIntermediateDir, { recursive: true });
+    // 备份由 snapshotPriorRoundIfNeeded 统一处理
+    fs.writeFileSync(promptPath, content, "utf-8");
+  } catch (e) {
+    return null;
+  }
+  const relativePath = path.relative(workspaceRoot, promptPath);
+  return { optionalPromptPath: relativePath.replace(/\\/g, "/"), directCommand };
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 4) {
+    console.error(
+      JSON.stringify({
+        ok: false,
+        error:
+          "Usage: node pre-process-node.mjs <workspaceRoot> <flowName> <uuid> <instanceId>",
+      }),
+    );
+    process.exit(1);
+  }
+
+  const [root, flowName, uuid, instanceId] = args;
+  const workspaceRoot = path.resolve(root);
+
+  let execId = 1;
+  let priorExecId = 0;
+  const loadKeyPath = path.join(path.dirname(fileURLToPath(import.meta.url)), "load-key.mjs");
+  const execIdKey = "execId_" + instanceId;
+  // load-key.mjs 参数约定：<workspaceRoot> <flowName> <uuid> <key>。
+  // 缺 flowName 会导致 getRunDir 拼成错误路径，memory 永远读不到 → execId 每轮都回到 1，
+  // snapshotPriorRoundIfNeeded 也永远 no-op，loop 跑多少轮 sidebar 都只有 #1/#2。
+  const loadResult = spawnSync(process.execPath, [loadKeyPath, workspaceRoot, flowName, uuid, execIdKey], {
+    cwd: workspaceRoot,
+    encoding: "utf-8",
+  });
+  if (loadResult.stdout) {
+    try {
+      const out = JSON.parse(loadResult.stdout.trim());
+      const result = out?.message?.result;
+      if (result !== undefined && result !== "") {
+        const current = parseInt(String(result), 10) || 0;
+        priorExecId = current;
+        execId = current + 1;
+      }
+    } catch (_) {}
+  }
+
+  const runDir = getRunDir(workspaceRoot, flowName, uuid);
+
+  // 唯一备份入口：把上一轮的 intermediate/output 文件统一 rename 为 _<priorExecId>。
+  // 之后任何 writer（write-result / build-node-prompt / run-tool-nodejs / get-env 等）
+  // 都不再负责备份，只管对 current 路径写入新内容。
+  snapshotPriorRoundIfNeeded(runDir, instanceId, priorExecId);
+
+  const resultPathRel = `${intermediateDirForNode(instanceId)}/${intermediateResultBasename(instanceId, execId)}`;
+
+  /** control_if：不执行 subagent，根据第一个 bool 类型输入直接写 result 并返回 optionalPromptPath */
+  const definitionId = getDefinitionIdFromFlowJson(workspaceRoot, flowName, uuid, instanceId);
+  if (definitionId === "control_if") {
+    const flow = readFlowJson(workspaceRoot, flowName, uuid);
+    const inputSlotTypes = (flow?.inputSlotTypes && flow.inputSlotTypes[instanceId]) || null;
+    const data = getResolvedValues(workspaceRoot, flowName, uuid, instanceId);
+    if (!data.ok || !data.resolvedInputs) {
+      console.error(JSON.stringify({ ok: false, error: "control_if: getResolvedValues failed or no resolvedInputs" }));
+      process.exit(1);
+    }
+    const rawVal = getFirstBoolInputValue(data.resolvedInputs, inputSlotTypes);
+    if (rawVal == null) {
+      console.error(JSON.stringify({ ok: false, error: "control_if: no bool-type input slot found" }));
+      process.exit(1);
+    }
+    let boolValue;
+    let filePath = null;
+    if (rawVal.startsWith("output/") || rawVal.startsWith("intermediate/")) {
+      filePath = path.join(runDir, rawVal);
+    } else if (path.isAbsolute(rawVal)) {
+      filePath = rawVal;
+    }
+    if (filePath) {
+      if (fs.existsSync(filePath)) {
+        boolValue = parseBool(fs.readFileSync(filePath, "utf-8").trim());
+      } else {
+        // 查找 snapshotPriorRoundIfNeeded 创建的 _N 备份文件
+        const dir = path.dirname(filePath);
+        const ext = path.extname(filePath);
+        const base = path.basename(filePath, ext);
+        let found = false;
+        try {
+          if (fs.existsSync(dir)) {
+            const candidates = fs.readdirSync(dir).filter(f =>
+              f.startsWith(base + "_") && f.endsWith(ext) &&
+              /^\d+$/.test(f.slice(base.length + 1, -ext.length))
+            );
+            if (candidates.length > 0) {
+              candidates.sort((a, b) => {
+                const na = parseInt(a.slice(base.length + 1, -ext.length), 10);
+                const nb = parseInt(b.slice(base.length + 1, -ext.length), 10);
+                return nb - na;
+              });
+              boolValue = parseBool(fs.readFileSync(path.join(dir, candidates[0]), "utf-8").trim());
+              found = true;
+            }
+          }
+        } catch (_) {}
+        if (!found) {
+          console.error(JSON.stringify({ ok: false, error: `control_if: bool input file not found: ${rawVal}` }));
+          process.exit(1);
+        }
+      }
+    } else {
+      boolValue = parseBool(rawVal);
+    }
+    const branch = boolValue ? "true" : "false";
+    writeResult(workspaceRoot, flowName, uuid, instanceId, { status: "success", message: `分支 ${branch}`, branch }, { execId });
+    const nodeIntermediateDir = path.join(runDir, intermediateDirForNode(instanceId));
+    fs.mkdirSync(nodeIntermediateDir, { recursive: true });
+    const build = buildNodePrompt(workspaceRoot, flowName, uuid, instanceId, execId);
+    if (build.ok) writeCacheJsonForNode(workspaceRoot, flowName, uuid, instanceId, execId);
+    const noopPromptPath = path.join(nodeIntermediateDir, `${instanceId}.control_if_noop.prompt.md`);
+    // 备份由 snapshotPriorRoundIfNeeded 统一处理
+    fs.writeFileSync(
+      noopPromptPath,
+      "此节点为 **control_if**，已由预处理根据 bool 输入直接写入 result，无需执行任何操作。",
+      "utf-8",
+    );
+    const optionalPromptPath = path.relative(workspaceRoot, noopPromptPath).replace(/\\/g, "/");
+    const output = {
+      ok: true,
+      promptPath: optionalPromptPath,
+      resultPath: resultPathRel,
+      execId,
+      subagent: "agentflow-node-executor",
+      optionalPromptPath,
+      definitionId,
+    };
+    logToRunTag(workspaceRoot, flowName, uuid, "pre-process", { event: "control_if-direct-write", instanceId, branch });
+    console.log(JSON.stringify(output));
+    return;
+  }
+
+  const data = buildNodePrompt(workspaceRoot, flowName, uuid, instanceId, execId);
+  if (!data.ok) {
+    console.error(JSON.stringify({ ok: false, error: data.error || "build-node-prompt failed" }));
+    process.exit(1);
+  }
+
+  const { role, model } = getRoleAndModelFromFlowJson(workspaceRoot, flowName, uuid, instanceId);
+  const subagent = ROLE_TO_SUBAGENT[role] ?? (role && String(role).trim() ? String(role).trim() : ROLE_TO_SUBAGENT.普通);
+
+  const intermediateDir = path.join(runDir, "intermediate");
+
+  writeResult(workspaceRoot, flowName, uuid, instanceId, { status: "running", message: "执行中" }, { preserveBody: false, execId });
+  logToRunTag(workspaceRoot, flowName, uuid, "pre-process", {
+    event: "result-running",
+    instanceId,
+    resultPath: resultPathRel,
+  });
+
+  writeCacheJsonForNode(workspaceRoot, flowName, uuid, instanceId, execId);
+
+  const output = {
+    ok: true,
+    promptPath: data.promptPath,
+    nodeContext: data.nodeContext ?? "",
+    taskBody: data.taskBody ?? "",
+    resultPath: resultPathRel,
+    execId,
+    subagent,
+    definitionId,
+    role,
+  };
+  if (model) output.model = model;
+  if (data.optionalPromptPath) {
+    output.optionalPromptPath = data.optionalPromptPath;
+  }
+  const runKeyResult = emitLoadSaveKeyOptionalPrompt(workspaceRoot, flowName, uuid, instanceId, definitionId, execId);
+  if (runKeyResult) {
+    output.optionalPromptPath = runKeyResult.optionalPromptPath;
+    output.directCommand = runKeyResult.directCommand;
+  } else if (definitionId === "control_anyOne") {
+    const anyOneResult = emitAnyOneOptionalPrompt(workspaceRoot, flowName, uuid, instanceId, execId);
+    if (anyOneResult) {
+      output.optionalPromptPath = anyOneResult.optionalPromptPath;
+      output.directCommand = anyOneResult.directCommand;
+    }
+  } else if ((definitionId === "tool_nodejs" || definitionId === "control_toBool") && data.script) {
+    const toolNodejsResult = emitToolNodejsDirectCommand(workspaceRoot, flowName, uuid, instanceId, data.script, execId);
+    if (toolNodejsResult) {
+      output.optionalPromptPath = toolNodejsResult.optionalPromptPath;
+      output.directCommand = toolNodejsResult.directCommand;
+      output.resolvedScript = data.script;
+    }
+  }
+  logToRunTag(workspaceRoot, flowName, uuid, "pre-process", {
+    event: "done",
+    instanceId,
+    promptPath: data.promptPath,
+    resultPath: resultPathRel,
+    subagent,
+    definitionId,
+    hasOptionalPrompt: !!output.optionalPromptPath,
+    hasDirectCommand: !!output.directCommand,
+  });
+  console.log(JSON.stringify(output));
+}
+
+main();

package/bin/pipeline/resolve-inputs.mjs

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/**
+ * 按 flow 结构 + 中间文件为单个 instance 计算 resolvedInputs（不注入常量；上游 output 路径已带对应 input handler 的 execId）。
+ * 供 get-resolved-values 等用时现算，不依赖 flow.json 中的 resolvedInputs。
+ * 约定：上游节点的 output 槽路径使用该前驱的 latestResultExecId，即 output/<predId>/node_<predId>_<execId>_<slot>.md。
+ * 用法（模块）：import { computeResolvedInputsForInstance } from "./resolve-inputs.mjs";
+ * @returns {{ ok: true, resolvedInputs: object }} 或 {{ ok: false, error: string }}
+ */
+
+import fs from "fs";
+import path from "path";
+
+import { getRunDir, PIPELINES_DIR } from "../lib/paths.mjs";
+import { getFlowDir } from "../lib/workspace.mjs";
+import {
+  loadAllExecIds,
+  latestResultExecId,
+  intermediateResultBasename,
+  outputDirForNode,
+  outputNodeBasename,
+} from "./get-exec-id.mjs";
+import {
+  loadFlowDefinition,
+  parseResultOutputPath,
+  instanceEntryToSlots,
+  parseInstanceSlots,
+  readInstanceContent,
+  extractPlaceholders,
+} from "./parse-flow.mjs";
+
+/**
+ * 为指定 instanceId 计算 resolvedInputs（与 parse-flow resolvePlaceholders 单实例逻辑一致）。
+ */
+export function computeResolvedInputsForInstance(workspaceRoot, flowName, uuid, instanceId) {
+  const root = path.resolve(workspaceRoot);
+  const runDir = getRunDir(workspaceRoot, flowName, uuid);
+  const flowJsonPath = path.join(runDir, "intermediate", "flow.json");
+  const intermediateDir = path.join(runDir, "intermediate");
+
+  if (!fs.existsSync(flowJsonPath)) {
+    return { ok: false, error: `flow.json not found: ${flowJsonPath}. Run parse-flow.mjs first.` };
+  }
+
+  let flow;
+  try {
+    flow = JSON.parse(fs.readFileSync(flowJsonPath, "utf-8"));
+  } catch (e) {
+    return { ok: false, error: e.message || "Invalid flow.json" };
+  }
+  if (!flow.ok) {
+    return { ok: false, error: flow.error || "flow.json indicates error" };
+  }
+
+  let flowDir = getFlowDir(root, flowName) || path.join(root, PIPELINES_DIR, flowName);
+  if (flow.flowDir && typeof flow.flowDir === "string" && flow.flowDir.trim()) {
+    flowDir = path.isAbsolute(flow.flowDir) ? flow.flowDir : path.join(root, flow.flowDir);
+  }
+  const instanceDir = path.join(flowDir, "instance");
+
+  const order = flow.order || [];
+  const edges = flow.edges || [];
+  if (!order.length) {
+    return { ok: false, error: "flow.json missing order" };
+  }
+
+  if (!order.includes(instanceId)) {
+    return { ok: false, error: `instanceId ${instanceId} not in flow order` };
+  }
+
+  const flowData = loadFlowDefinition(flowDir);
+  const instances = flowData?.instances && typeof flowData.instances === "object" ? flowData.instances : {};
+  const useYaml = Object.keys(instances).length > 0;
+
+  let execIds = {};
+  if (fs.existsSync(intermediateDir)) {
+    try {
+      execIds = loadAllExecIds(workspaceRoot, flowName, uuid, order);
+    } catch (_) {}
+  }
+
+  /** 入边：target -> [{ source, sourceHandle, targetHandle }] */
+  const predecessors = new Map();
+  for (const e of edges) {
+    if (!e.target) continue;
+    if (!predecessors.has(e.target)) predecessors.set(e.target, []);
+    predecessors.get(e.target).push({
+      source: e.source,
+      sourceHandle: e.sourceHandle || "output-0",
+      targetHandle: e.targetHandle,
+    });
+  }
+
+  const getSlotsFor = (id) => {
+    if (useYaml && instances[id]) return instanceEntryToSlots(instances[id]);
+    const instPath = path.join(instanceDir, `${id}.md`);
+    return fs.existsSync(instPath) ? parseInstanceSlots(instPath) : instanceEntryToSlots(null);
+  };
+
+  const getContentFor = (id) => {
+    if (useYaml && instances[id] && instances[id].body != null) return String(instances[id].body || "").trim();
+    return readInstanceContent(path.join(instanceDir, `${id}.md`));
+  };
+
+  const getNodeOutput = (id, sourceHandle) => {
+    const slots = getSlotsFor(id);
+    const outValues = Object.values(slots.output || {});
+    if (sourceHandle && /^output-(\d+)$/.test(sourceHandle)) {
+      const idx = parseInt(sourceHandle.replace("output-", ""), 10);
+      if (idx >= 0 && idx < outValues.length) return outValues[idx] ?? null;
+    }
+    return outValues[0] ?? null;
+  };
+
+  const getNodeOutputFromResult = (id) => {
+    const latestE = latestResultExecId(execIds[id] ?? 1);
+    if (!latestE) return null;
+    const resultPath = path.join(intermediateDir, id, intermediateResultBasename(id, latestE));
+    return parseResultOutputPath(resultPath);
+  };
+
+  const resolvedInputs = {};
+  const slots = getSlotsFor(instanceId);
+  const { inputs: inputRefs } = extractPlaceholders(getContentFor(instanceId));
+  const preds = predecessors.get(instanceId) || [];
+  const inputSlotNames = Object.keys(slots.input || {});
+
+  for (let i = 0; i < inputSlotNames.length; i++) {
+    const slotName = inputSlotNames[i];
+    const targetHandle = `input-${i}`;
+    const pred = preds.find((p) => p.targetHandle === targetHandle);
+    if (!pred) continue;
+
+    const fromResult = getNodeOutputFromResult(pred.source);
+    const fromInstance = getNodeOutput(pred.source, pred.sourceHandle);
+    let value = fromResult ?? fromInstance;
+
+    if (pred.sourceHandle && /^output-(\d+)$/.test(pred.sourceHandle)) {
+      const sourceSlots = getSlotsFor(pred.source);
+      const outSlotNames = Object.keys(sourceSlots.output || {});
+      if (outSlotNames.length > 0) {
+        const idx = parseInt(pred.sourceHandle.replace("output-", ""), 10);
+        if (idx >= 0 && idx < outSlotNames.length) {
+          const predExecId = latestResultExecId(execIds[pred.source] ?? 1);
+          const slotPath = `${outputDirForNode(pred.source)}/${outputNodeBasename(pred.source, predExecId, outSlotNames[idx])}`;
+          if (!value || value === "" || outSlotNames.length > 1) {
+            value = slotPath;
+          }
+        }
+      }
+    }
+
+    if (value != null) {
+      const slotType = (slots.inputTypes && slots.inputTypes[slotName]) || null;
+      if (slotType === "节点" || slotType === "node") {
+        value = pred.source;
+      }
+      resolvedInputs[slotName] = value;
+    }
+  }
+
+  for (const slotName of inputSlotNames) {
+    if (resolvedInputs[slotName] != null) continue;
+    const defaultVal = slots.input && slots.input[slotName];
+    if (defaultVal !== undefined && defaultVal !== "") {
+      resolvedInputs[slotName] = defaultVal;
+    }
+  }
+
+  // --input 覆盖：仅当对应上游是 provide_ 节点，且用户传了该 slotName 的值时生效。
+  // parse-flow 初始阶段也会写入 flow.json 的 cliInputsApplied，但此处在运行时重算 resolvedInputs，
+  // 必须在同一处再打一次 patch，否则 override 会丢失（provide 节点原 default 值会覆盖用户输入）。
+  if (flow.cliInputsApplied && typeof flow.cliInputsApplied === "object") {
+    for (let i = 0; i < inputSlotNames.length; i++) {
+      const slotName = inputSlotNames[i];
+      const cliVal = flow.cliInputsApplied[slotName];
+      if (!cliVal || typeof cliVal !== "object") continue;
+      const pred = preds.find((p) => p.targetHandle === `input-${i}`);
+      if (!pred?.source) continue;
+      const sourceInst = instances[pred.source];
+      if (!sourceInst?.definitionId?.startsWith?.("provide_")) continue;
+      const overrideValue = cliVal.type === "file" ? cliVal.path : cliVal.value;
+      if (overrideValue == null) continue;
+      resolvedInputs[slotName] = overrideValue;
+    }
+  }
+
+  if (inputRefs.length > 0 && preds.length > 0 && !Object.keys(resolvedInputs).length) {
+    const pred = preds[0];
+    const fromResult = getNodeOutputFromResult(pred.source);
+    const fromInstance = getNodeOutput(pred.source, pred.sourceHandle);
+    let v = fromResult ?? fromInstance;
+    if (v != null) {
+      const firstSlotName = inputSlotNames[0];
+      const firstType = (slots.inputTypes && slots.inputTypes[firstSlotName]) || null;
+      if (firstType === "节点" || firstType === "node") v = pred.source;
+      return { ok: true, resolvedInputs: { _: v } };
+    }
+  }
+
+  return { ok: true, resolvedInputs };
+}

package/bin/pipeline/run-log.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * 向 run 目录下的 logs/log.txt 追加日志（单文件、追加模式），便于定位 get-ready-nodes、cache、result 等问题。
+ * 用法（模块）：import { logToRunTag } from "./run-log.mjs";
+ *   logToRunTag(workspaceRoot, flowName, uuid, tag, message)
+ * 日志写入：<workspaceRoot>/.workspace/agentflow/runBuild/<flowName>/<uuid>/logs/log.txt，每行 [ISO8601] [tag] message
+ */
+
+import fs from "fs";
+import path from "path";
+
+import { getRunDir } from "../lib/paths.mjs";
+
+const LOG_FILE = "logs/log.txt";
+
+/**
+ * 向 run 目录下的 logs/log.txt 追加一行日志（单文件、追加模式）。
+ * @param {string} workspaceRoot - 工作区根目录
+ * @param {string} flowName - 流程名
+ * @param {string} uuid - 本次 run 的 uuid
+ * @param {string} tag - 来源标识：get-ready-nodes | check-cache | pre-process | post-process | result
+ * @param {string|object} message - 文本或对象（对象会 JSON.stringify）
+ */
+export function logToRunTag(workspaceRoot, flowName, uuid, tag, message) {
+  if (!workspaceRoot || !flowName || !uuid) return;
+  const text = typeof message === "string" ? message : JSON.stringify(message);
+  try {
+    const runDir = getRunDir(workspaceRoot, flowName, uuid);
+    const logPath = path.join(runDir, LOG_FILE);
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const line = `[${new Date().toISOString()}] [${tag}] ${text}\n`;
+    fs.appendFileSync(logPath, line, "utf-8");
+  } catch (_) {}
+}