@fieldwangai/agentflow 0.1.25

package/bin/lib/schedule-config.mjs

@@ -0,0 +1,227 @@
+import fs from "fs";
+import path from "path";
+import { getFlowYamlAbs } from "./catalog-flows.mjs";
+
+export const SCHEDULE_CONFIG_FILENAME = "schedule.json";
+export const SCHEDULE_STATE_FILENAME = "schedule-state.json";
+
+const DEFAULT_SCHEDULE = {
+  enabled: false,
+  cron: "",
+  timezone: "Asia/Shanghai",
+  preset: "",
+  overlapPolicy: "skip",
+  misfirePolicy: "skip",
+};
+
+const CRON_FIELDS = [
+  { name: "minute", min: 0, max: 59 },
+  { name: "hour", min: 0, max: 23 },
+  { name: "dayOfMonth", min: 1, max: 31 },
+  { name: "month", min: 1, max: 12 },
+  { name: "dayOfWeek", min: 0, max: 7 },
+];
+
+const VALID_OVERLAP_POLICIES = new Set(["skip"]);
+const VALID_MISFIRE_POLICIES = new Set(["skip"]);
+
+function normalizeTimezone(tz) {
+  const value = typeof tz === "string" && tz.trim() ? tz.trim() : DEFAULT_SCHEDULE.timezone;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: value }).format(new Date());
+    return value;
+  } catch {
+    throw new Error(`Invalid timezone: ${value}`);
+  }
+}
+
+function parseCronNumber(raw, field) {
+  if (!/^\d+$/.test(raw)) throw new Error(`Invalid ${field.name} value: ${raw}`);
+  const n = Number(raw);
+  const normalized = field.name === "dayOfWeek" && n === 7 ? 0 : n;
+  if (n < field.min || n > field.max) throw new Error(`Invalid ${field.name} value: ${raw}`);
+  return normalized;
+}
+
+function addRange(values, field, start, end, step) {
+  if (step <= 0) throw new Error(`Invalid ${field.name} step`);
+  if (start > end) throw new Error(`Invalid ${field.name} range`);
+  for (let n = start; n <= end; n += step) {
+    values.add(field.name === "dayOfWeek" && n === 7 ? 0 : n);
+  }
+}
+
+function parseCronField(raw, field) {
+  const text = String(raw || "").trim();
+  if (!text) throw new Error(`Missing ${field.name}`);
+  const values = new Set();
+  values.cronWildcard = text === "*";
+  for (const partRaw of text.split(",")) {
+    const part = partRaw.trim();
+    if (!part) throw new Error(`Invalid ${field.name} field`);
+    const [rangeRaw, stepRaw] = part.split("/");
+    if (part.split("/").length > 2) throw new Error(`Invalid ${field.name} step`);
+    const step = stepRaw == null ? 1 : parseCronNumber(stepRaw, { ...field, min: 1 });
+    if (rangeRaw === "*") {
+      addRange(values, field, field.min, field.max, step);
+      continue;
+    }
+    const dashIdx = rangeRaw.indexOf("-");
+    if (dashIdx >= 0) {
+      const start = parseCronNumber(rangeRaw.slice(0, dashIdx), field);
+      const end = parseCronNumber(rangeRaw.slice(dashIdx + 1), field);
+      addRange(values, field, start, end, step);
+      continue;
+    }
+    if (stepRaw != null) throw new Error(`Invalid ${field.name} step target`);
+    values.add(parseCronNumber(rangeRaw, field));
+  }
+  return values;
+}
+
+export function parseCronExpression(cron) {
+  const parts = String(cron || "").trim().split(/\s+/).filter(Boolean);
+  if (parts.length !== 5) {
+    throw new Error("Cron must contain 5 fields: minute hour day month weekday");
+  }
+  return CRON_FIELDS.map((field, i) => parseCronField(parts[i], field));
+}
+
+function zonedParts(date, timeZone) {
+  const dtf = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false,
+  });
+  const out = {};
+  for (const p of dtf.formatToParts(date)) {
+    if (p.type !== "literal") out[p.type] = Number(p.value);
+  }
+  if (out.hour === 24) out.hour = 0;
+  return out;
+}
+
+function cronMatches(parsed, parts) {
+  const [minutes, hours, days, months, weekdays] = parsed;
+  const weekday = new Date(Date.UTC(parts.year, parts.month - 1, parts.day)).getUTCDay();
+  const dayMatches =
+    days.cronWildcard || weekdays.cronWildcard
+      ? days.has(parts.day) && weekdays.has(weekday)
+      : days.has(parts.day) || weekdays.has(weekday);
+  return (
+    minutes.has(parts.minute) &&
+    hours.has(parts.hour) &&
+    months.has(parts.month) &&
+    dayMatches
+  );
+}
+
+export function computeNextRunAt(cron, timezone, fromDate = new Date()) {
+  const parsed = parseCronExpression(cron);
+  const tz = normalizeTimezone(timezone);
+  const startMs = Math.floor(fromDate.getTime() / 60000) * 60000 + 60000;
+  const maxMinutes = 366 * 24 * 60;
+  for (let i = 0; i < maxMinutes; i++) {
+    const candidate = new Date(startMs + i * 60000);
+    if (cronMatches(parsed, zonedParts(candidate, tz))) return candidate.toISOString();
+  }
+  throw new Error("Could not find next run within one year");
+}
+
+export function computeNextRunAtFromSchedule(schedule, fromDate = new Date()) {
+  const normalized = normalizeSchedule(schedule);
+  if (!normalized.cron) return null;
+  return computeNextRunAt(normalized.cron, normalized.timezone, fromDate);
+}
+
+export function normalizeSchedule(raw) {
+  const src = raw && typeof raw === "object" ? raw : {};
+  const enabled = Boolean(src.enabled);
+  const cron = typeof src.cron === "string" ? src.cron.trim() : "";
+  const timezone = normalizeTimezone(src.timezone);
+  const preset = typeof src.preset === "string" ? src.preset.trim() : "";
+  const overlapPolicy = VALID_OVERLAP_POLICIES.has(src.overlapPolicy) ? src.overlapPolicy : DEFAULT_SCHEDULE.overlapPolicy;
+  const misfirePolicy = VALID_MISFIRE_POLICIES.has(src.misfirePolicy) ? src.misfirePolicy : DEFAULT_SCHEDULE.misfirePolicy;
+  let nextRunAt = null;
+  if (cron) {
+    parseCronExpression(cron);
+    nextRunAt = computeNextRunAt(cron, timezone);
+  } else if (enabled) {
+    throw new Error("Cron is required when schedule is enabled");
+  }
+  return { enabled, cron, timezone, preset, overlapPolicy, misfirePolicy, nextRunAt };
+}
+
+function readJsonIfExists(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+}
+
+export function readScheduleState(workspaceRoot, flowId, flowSource, opts = {}) {
+  const paths = getFlowSchedulePaths(workspaceRoot, flowId, flowSource, opts);
+  if (paths.error) return { success: false, error: paths.error };
+  try {
+    return { success: true, state: readJsonIfExists(paths.statePath) || {}, statePath: paths.statePath };
+  } catch (e) {
+    return { success: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+export function writeScheduleState(workspaceRoot, flowId, flowSource, state, opts = {}) {
+  const paths = getFlowSchedulePaths(workspaceRoot, flowId, flowSource, opts);
+  if (paths.error) return { success: false, error: paths.error };
+  try {
+    fs.writeFileSync(paths.statePath, JSON.stringify(state && typeof state === "object" ? state : {}, null, 2) + "\n", "utf-8");
+    return { success: true, statePath: paths.statePath };
+  } catch (e) {
+    return { success: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+export function getFlowSchedulePaths(workspaceRoot, flowId, flowSource, opts = {}) {
+  const yamlRes = getFlowYamlAbs(workspaceRoot, flowId, flowSource, opts);
+  if (yamlRes.error || !yamlRes.path) return { error: yamlRes.error || "Could not resolve flow.yaml" };
+  const flowDir = path.dirname(yamlRes.path);
+  return {
+    flowDir,
+    configPath: path.join(flowDir, SCHEDULE_CONFIG_FILENAME),
+    statePath: path.join(flowDir, SCHEDULE_STATE_FILENAME),
+  };
+}
+
+export function readFlowSchedule(workspaceRoot, flowId, flowSource, opts = {}) {
+  const paths = getFlowSchedulePaths(workspaceRoot, flowId, flowSource, opts);
+  if (paths.error) return { success: false, error: paths.error };
+  try {
+    const configRaw = readJsonIfExists(paths.configPath) || DEFAULT_SCHEDULE;
+    const state = readJsonIfExists(paths.statePath) || {};
+    return { success: true, schedule: normalizeSchedule(configRaw), state };
+  } catch (e) {
+    return { success: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+export function writeFlowSchedule(workspaceRoot, flowId, flowSource, schedule, opts = {}) {
+  const paths = getFlowSchedulePaths(workspaceRoot, flowId, flowSource, opts);
+  if (paths.error) return { success: false, error: paths.error };
+  try {
+    const normalized = normalizeSchedule(schedule);
+    const toWrite = {
+      enabled: normalized.enabled,
+      cron: normalized.cron,
+      timezone: normalized.timezone,
+      preset: normalized.preset,
+      overlapPolicy: normalized.overlapPolicy,
+      misfirePolicy: normalized.misfirePolicy,
+    };
+    fs.writeFileSync(paths.configPath, JSON.stringify(toWrite, null, 2) + "\n", "utf-8");
+    return { success: true, schedule: normalized };
+  } catch (e) {
+    return { success: false, error: e && e.message ? e.message : String(e) };
+  }
+}

package/bin/lib/scheduler.mjs

@@ -0,0 +1,312 @@
+import fs from "fs";
+import path from "path";
+import { spawn } from "child_process";
+import yaml from "js-yaml";
+import { listFlowsJson } from "./catalog-flows.mjs";
+import {
+  computeNextRunAtFromSchedule,
+  readFlowSchedule,
+  readScheduleState,
+  writeScheduleState,
+} from "./schedule-config.mjs";
+import { getRunDir, PACKAGE_ROOT } from "./paths.mjs";
+import { isApplyProcessAlive } from "./run-apply-active-lock.mjs";
+import { log } from "./log.mjs";
+
+const DEFAULT_POLL_MS = 30_000;
+const RUN_CONFIG_FILENAME = "run-config.json";
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function scheduleIdentity(schedule) {
+  return [
+    schedule.enabled ? "1" : "0",
+    schedule.cron || "",
+    schedule.timezone || "",
+    schedule.preset || "",
+    schedule.overlapPolicy || "skip",
+    schedule.misfirePolicy || "skip",
+  ].join("\t");
+}
+
+function readRunConfig(flowDir) {
+  const configPath = path.join(flowDir, RUN_CONFIG_FILENAME);
+  if (!fs.existsSync(configPath)) return { presets: {}, activePreset: null };
+  try {
+    const data = JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    return {
+      presets: data.presets && typeof data.presets === "object" ? data.presets : {},
+      activePreset: typeof data.activePreset === "string" ? data.activePreset : null,
+    };
+  } catch {
+    return { presets: {}, activePreset: null };
+  }
+}
+
+function buildCliInputArgs(flowDir, presetName) {
+  const cfg = readRunConfig(flowDir);
+  const name = presetName || cfg.activePreset || "";
+  const preset = name && cfg.presets && typeof cfg.presets[name] === "object" ? cfg.presets[name] : null;
+  if (!preset) return [];
+  let flow;
+  try {
+    flow = yaml.load(fs.readFileSync(path.join(flowDir, "flow.yaml"), "utf-8"));
+  } catch {
+    flow = null;
+  }
+  const instances = flow && typeof flow === "object" && flow.instances && typeof flow.instances === "object" ? flow.instances : {};
+  const edges = flow && typeof flow === "object" && Array.isArray(flow.edges) ? flow.edges : [];
+  const provideToInputName = {};
+  for (const e of edges) {
+    if (!e || !e.source || !e.target) continue;
+    const source = String(e.source);
+    const target = String(e.target);
+    if (!preset.hasOwnProperty(source)) continue;
+    const sourceInst = instances[source] || {};
+    const sourceDef = String(sourceInst.definitionId || "");
+    if (!sourceDef.startsWith("provide_")) continue;
+    const m = /^input-(\d+)$/.exec(String(e.targetHandle || ""));
+    if (!m) continue;
+    const targetInst = instances[target] || {};
+    const inputs = Array.isArray(targetInst.input) ? targetInst.input : [];
+    const slot = inputs[parseInt(m[1], 10)];
+    if (slot && typeof slot.name === "string" && slot.name.trim()) {
+      provideToInputName[source] = {
+        name: slot.name.trim(),
+        isFile: sourceDef.startsWith("provide_file"),
+      };
+    }
+  }
+  const args = [];
+  for (const [inputName, value] of Object.entries(preset)) {
+    if (!inputName || typeof inputName !== "string") continue;
+    const mapped = provideToInputName[inputName];
+    if (!mapped) continue;
+    args.push("--input", `${mapped.name}=${mapped.isFile ? "file:" : ""}${String(value ?? "")}`);
+  }
+  return args;
+}
+
+function hasHigherPriorityDuplicate(workspaceRoot, flow) {
+  if ((flow.source || "user") !== "workspace") return false;
+  return listFlowsJson(workspaceRoot).some((f) => f.id === flow.id && !f.archived && (f.source || "user") === "user");
+}
+
+function getLatestRunUuidForFlow(workspaceRoot, flowId) {
+  const runRoot = path.dirname(getRunDir(workspaceRoot, flowId, "00000000000000"));
+  if (!fs.existsSync(runRoot)) return null;
+  try {
+    const dirs = fs.readdirSync(runRoot, { withFileTypes: true })
+      .filter((e) => e.isDirectory() && /^\d{14}$/.test(e.name))
+      .map((e) => e.name)
+      .sort();
+    return dirs[dirs.length - 1] || null;
+  } catch {
+    return null;
+  }
+}
+
+function isFlowCurrentlyRunning(workspaceRoot, flowId, state) {
+  const candidates = [];
+  if (state && typeof state.lastRunUuid === "string") candidates.push(state.lastRunUuid);
+  const latest = getLatestRunUuidForFlow(workspaceRoot, flowId);
+  if (latest) candidates.push(latest);
+  for (const uuid of candidates) {
+    const runDir = getRunDir(workspaceRoot, flowId, uuid);
+    if (isApplyProcessAlive(runDir)) return true;
+  }
+  return false;
+}
+
+function baseState(flow, schedule, previousState) {
+  return {
+    ...(previousState && typeof previousState === "object" ? previousState : {}),
+    flowId: flow.id,
+    flowSource: flow.source || "user",
+    scheduleIdentity: scheduleIdentity(schedule),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function ensureNextRunAt(workspaceRoot, flow, schedule, state) {
+  const identity = scheduleIdentity(schedule);
+  if (state.scheduleIdentity === identity && state.nextRunAt) return state;
+  const nextRunAt = schedule.enabled && schedule.cron ? computeNextRunAtFromSchedule(schedule) : null;
+  const next = {
+    ...baseState(flow, schedule, state),
+    nextRunAt,
+    lastError: "",
+  };
+  writeScheduleState(workspaceRoot, flow.id, flow.source || "user", next);
+  return next;
+}
+
+function startScheduledRun(workspaceRoot, flow, schedule, state) {
+  const flowDir = flow.path || "";
+  const agentflowBin = path.join(PACKAGE_ROOT, "bin", "agentflow.mjs");
+  const args = [agentflowBin, "apply", flow.id, "--machine-readable", "--workspace-root", path.resolve(workspaceRoot), "--force"];
+  args.push(...buildCliInputArgs(flowDir, schedule.preset));
+  const child = spawn(process.execPath, args, {
+    cwd: path.resolve(workspaceRoot),
+    stdio: ["ignore", "pipe", "pipe"],
+    env: { ...process.env, FORCE_COLOR: "0" },
+    detached: true,
+  });
+
+  const startedAt = new Date().toISOString();
+  let lastRunUuid = null;
+  let stdoutBuf = "";
+  child.stdout.on("data", (chunk) => {
+    stdoutBuf += chunk.toString("utf8");
+    const lines = stdoutBuf.split("\n");
+    stdoutBuf = lines.pop() || "";
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const evt = JSON.parse(line);
+        if (evt && evt.event === "apply-start" && typeof evt.uuid === "string") {
+          lastRunUuid = evt.uuid;
+          writeScheduleState(workspaceRoot, flow.id, flow.source || "user", {
+            ...baseState(flow, schedule, state),
+            nextRunAt: computeNextRunAtFromSchedule(schedule),
+            lastTriggeredAt: startedAt,
+            lastRunUuid,
+            lastPid: child.pid || null,
+            lastError: "",
+          });
+        }
+      } catch {
+        /* ignore non-json lines */
+      }
+    }
+  });
+
+  child.stderr.on("data", (chunk) => {
+    const text = chunk.toString("utf8").trim();
+    if (text) log.debug(`[scheduler] ${flow.id}: ${text.slice(0, 1000)}`);
+  });
+
+  child.on("exit", (code, signal) => {
+    const prev = readScheduleState(workspaceRoot, flow.id, flow.source || "user").state || state;
+    writeScheduleState(workspaceRoot, flow.id, flow.source || "user", {
+      ...baseState(flow, schedule, prev),
+      nextRunAt: prev.nextRunAt || computeNextRunAtFromSchedule(schedule),
+      lastTriggeredAt: prev.lastTriggeredAt || startedAt,
+      lastRunUuid: lastRunUuid || prev.lastRunUuid || null,
+      lastExitCode: code,
+      lastExitSignal: signal || "",
+      lastFinishedAt: new Date().toISOString(),
+      lastError: code === 0 ? "" : `scheduled run exited with code ${code}${signal ? ` signal ${signal}` : ""}`,
+    });
+  });
+
+  child.unref();
+  return child;
+}
+
+export function listScheduleStatuses(workspaceRoot) {
+  const rows = [];
+  for (const flow of listFlowsJson(workspaceRoot)) {
+    if (flow.archived || flow.source === "builtin") continue;
+    const scheduleRes = readFlowSchedule(workspaceRoot, flow.id, flow.source || "user");
+    if (!scheduleRes.success) {
+      rows.push({ flowId: flow.id, flowSource: flow.source || "user", enabled: false, error: scheduleRes.error });
+      continue;
+    }
+    const schedule = scheduleRes.schedule;
+    const stateRes = readScheduleState(workspaceRoot, flow.id, flow.source || "user");
+    const state = stateRes.success ? stateRes.state : {};
+    rows.push({
+      flowId: flow.id,
+      flowSource: flow.source || "user",
+      enabled: Boolean(schedule.enabled),
+      cron: schedule.cron || "",
+      timezone: schedule.timezone || "",
+      preset: schedule.preset || "",
+      nextRunAt: state.nextRunAt || schedule.nextRunAt || null,
+      lastTriggeredAt: state.lastTriggeredAt || null,
+      lastRunUuid: state.lastRunUuid || null,
+      lastError: hasHigherPriorityDuplicate(workspaceRoot, flow)
+        ? "workspace flow is shadowed by a user flow with the same id"
+        : state.lastError || "",
+      running: isFlowCurrentlyRunning(workspaceRoot, flow.id, state),
+    });
+  }
+  rows.sort((a, b) => {
+    const ea = a.enabled ? 0 : 1;
+    const eb = b.enabled ? 0 : 1;
+    return ea - eb || String(a.nextRunAt || "").localeCompare(String(b.nextRunAt || "")) || a.flowId.localeCompare(b.flowId);
+  });
+  return rows;
+}
+
+export async function startScheduler(workspaceRoot, opts = {}) {
+  const pollMs = Math.max(1000, Number(opts.pollMs) || DEFAULT_POLL_MS);
+  const once = Boolean(opts.once);
+  log.info(`AgentFlow scheduler started. workspace=${path.resolve(workspaceRoot)} poll=${pollMs}ms`);
+  while (true) {
+    const now = Date.now();
+    for (const flow of listFlowsJson(workspaceRoot)) {
+      if (flow.archived || flow.source === "builtin") continue;
+      const flowSource = flow.source || "user";
+      const scheduleRes = readFlowSchedule(workspaceRoot, flow.id, flowSource);
+      if (!scheduleRes.success) {
+        log.debug(`[scheduler] ${flow.id}: ${scheduleRes.error}`);
+        continue;
+      }
+      const schedule = scheduleRes.schedule;
+      if (!schedule.enabled || !schedule.cron) continue;
+      if (hasHigherPriorityDuplicate(workspaceRoot, flow)) {
+        const stateRes = readScheduleState(workspaceRoot, flow.id, flowSource);
+        writeScheduleState(workspaceRoot, flow.id, flowSource, {
+          ...baseState(flow, schedule, stateRes.success ? stateRes.state : {}),
+          nextRunAt: null,
+          lastError: "workspace flow is shadowed by a user flow with the same id; scheduled run skipped",
+          lastErrorAt: new Date().toISOString(),
+        });
+        continue;
+      }
+      const stateRes = readScheduleState(workspaceRoot, flow.id, flowSource);
+      let state = ensureNextRunAt(workspaceRoot, flow, schedule, stateRes.success ? stateRes.state : {});
+      if (!state.nextRunAt || Date.parse(state.nextRunAt) > now) continue;
+
+      if (isFlowCurrentlyRunning(workspaceRoot, flow.id, state)) {
+        const nextRunAt = computeNextRunAtFromSchedule(schedule);
+        writeScheduleState(workspaceRoot, flow.id, flowSource, {
+          ...baseState(flow, schedule, state),
+          nextRunAt,
+          lastSkippedAt: new Date().toISOString(),
+          lastSkipReason: "running",
+        });
+        log.info(`[scheduler] skip ${flow.id}: already running; next=${nextRunAt}`);
+        continue;
+      }
+
+      try {
+        const child = startScheduledRun(workspaceRoot, flow, schedule, state);
+        const nextRunAt = computeNextRunAtFromSchedule(schedule);
+        writeScheduleState(workspaceRoot, flow.id, flowSource, {
+          ...baseState(flow, schedule, state),
+          nextRunAt,
+          lastTriggeredAt: new Date().toISOString(),
+          lastPid: child.pid || null,
+          lastError: "",
+        });
+        log.info(`[scheduler] triggered ${flow.id}; pid=${child.pid || "?"}; next=${nextRunAt}`);
+      } catch (e) {
+        const nextRunAt = computeNextRunAtFromSchedule(schedule);
+        writeScheduleState(workspaceRoot, flow.id, flowSource, {
+          ...baseState(flow, schedule, state),
+          nextRunAt,
+          lastError: e && e.message ? e.message : String(e),
+          lastErrorAt: new Date().toISOString(),
+        });
+        log.info(`[scheduler] failed ${flow.id}: ${e && e.message ? e.message : String(e)}`);
+      }
+    }
+    if (once) return;
+    await sleep(pollMs);
+  }
+}

package/bin/lib/table.mjs

@@ -0,0 +1,4 @@
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+export const Table = require("cli-table3");

package/bin/lib/terminal.mjs

@@ -0,0 +1,42 @@
+/** 当前时间 hh:MM:ss（24 小时） */
+export function formatTimeHHMMSS() {
+  const d = new Date();
+  const h = String(d.getHours()).padStart(2, "0");
+  const m = String(d.getMinutes()).padStart(2, "0");
+  const s = String(d.getSeconds()).padStart(2, "0");
+  return `${h}:${m}:${s}`;
+}
+
+/** 耗时展示：<1 分钟只展示秒，<1 小时展示分秒，>=1 小时展示时分秒 */
+export function formatDuration(ms) {
+  if (ms < 0 || !Number.isFinite(ms)) return "0s";
+  const sec = Math.floor(ms / 1000) % 60;
+  const min = Math.floor(ms / 60000) % 60;
+  const hour = Math.floor(ms / 3600000);
+  if (hour > 0) return `${hour}h ${min}m ${sec}s`;
+  if (min > 0) return `${min}m ${sec}s`;
+  return `${sec}s`;
+}
+
+const SAVE_CURSOR = "\x1b[s";
+const RESTORE_CURSOR = "\x1b[u";
+
+/** 在终端右下角写入一行文字（需 TTY）。pos 为从右往左的字符数，默认 8（hh:MM:ss） */
+export function writeBottomRight(stream, text, pos = 8) {
+  if (!stream.isTTY || stream.columns == null || stream.rows == null) return;
+  const cols = stream.columns || 80;
+  const rows = stream.rows || 24;
+  const col = Math.max(1, cols - pos);
+  stream.write(SAVE_CURSOR + `\x1b[${rows};${col}H` + text + RESTORE_CURSOR);
+}
+
+/** 对多行文本每行前加前缀后写入 stream */
+export function writeWithPrefix(stream, text, prefix, contentColor = null) {
+  if (!text || !prefix) {
+    if (text) stream.write(contentColor ? contentColor(text) : text);
+    return;
+  }
+  const lines = text.split("\n");
+  const out = lines.map((line) => prefix + (contentColor ? contentColor(line) : line)).join("\n");
+  stream.write(out + (text.endsWith("\n") ? "" : "\n"));
+}

package/bin/lib/ui-print.mjs

@@ -0,0 +1,94 @@
+import chalk from "chalk";
+import { log } from "./log.mjs";
+import { runNodeScript } from "./pipeline-scripts.mjs";
+import { Table } from "./table.mjs";
+
+/** 开始时：入口信息（仅流程名称与 uuid） */
+export function printEntryAndFlowFiles(workspaceRoot, flowName, uuid) {
+  const entryTable = new Table({
+    head: [chalk.cyan("项目"), chalk.cyan("值")],
+    colWidths: [18, 24],
+    style: { head: [], border: ["grey"] },
+  });
+  entryTable.push(["流程名称", flowName], ["本次运行 uuid", uuid]);
+  log.info("\n" + chalk.bold("入口信息"));
+  log.info(entryTable.toString());
+}
+
+export function styleStatus(s) {
+  if (s === "success") return chalk.green("success");
+  if (s === "pending") return chalk.yellow("pending");
+  if (s === "running") return chalk.cyan("running");
+  if (s === "condition_not_met") return chalk.dim("condition_not_met");
+  return chalk.dim(s || "-");
+}
+
+/** 仅打印全量节点状态表（应用进入时展示一次用）。输出到 stderr。 */
+export function printNodeStatusTable(instanceStatus, nodes, execIdMap = {}) {
+  const idToLabel = new Map();
+  const idToType = new Map();
+  if (Array.isArray(nodes)) {
+    for (const n of nodes) {
+      idToLabel.set(n.id, n.label || n.id);
+      idToType.set(n.id, n.type || "-");
+    }
+  }
+  const order = Array.isArray(nodes) ? nodes.map((n) => n.id) : Object.keys(instanceStatus || {});
+  if (order.length === 0) return;
+  const statusTable = new Table({
+    head: [chalk.cyan("标签"), chalk.cyan("类型"), chalk.cyan("状态"), chalk.cyan("execId")],
+    colWidths: [20, 10, 16, 8],
+    style: { head: [], border: ["grey"] },
+  });
+  for (const id of order) {
+    const label = idToLabel.get(id) || id;
+    const type = idToType.get(id) || "-";
+    const status = (instanceStatus && instanceStatus[id]) || "-";
+    const execId = execIdMap[id] != null ? String(execIdMap[id]) : "-";
+    statusTable.push([label, type, styleStatus(status), execId]);
+  }
+  process.stderr.write("\n" + chalk.bold("节点状态") + "\n");
+  process.stderr.write(statusTable.toString() + "\n");
+}
+
+/**
+ * apply 启动时执行 validate-flow（统一校验）；errors 则退出，仅 warnings 则提示后继续。
+ */
+export function runValidateFlowAndExitIfInvalid(workspaceRoot, flowName, flowDir) {
+  const result = runNodeScript(workspaceRoot, "validate-flow.mjs", [workspaceRoot, flowName, flowDir], {
+    captureStdout: true,
+  });
+  const stdout = (result.stdout || "").trim();
+  if (!stdout) return;
+  let data;
+  try {
+    data = JSON.parse(stdout);
+  } catch {
+    return;
+  }
+  const errors = Array.isArray(data.errors) ? data.errors : [];
+  const warnings = Array.isArray(data.warnings) ? data.warnings : [];
+
+  if (errors.length > 0) {
+    process.stderr.write("\n" + chalk.bold.red("流程校验未通过，请修正后再执行 apply：") + "\n\n");
+    for (const err of errors) {
+      process.stderr.write("  " + chalk.red("• ") + err + "\n");
+    }
+    if (warnings.length > 0) {
+      process.stderr.write("\n" + chalk.yellow("警告：") + "\n");
+      for (const w of warnings) {
+        process.stderr.write("  " + chalk.yellow("• ") + w + "\n");
+      }
+    }
+    process.stderr.write("\n" + chalk.dim("校验命令: agentflow validate " + flowName) + "\n");
+    process.exit(1);
+  }
+
+  if (warnings.length > 0) {
+    process.stderr.write("\n" + chalk.yellow("校验警告：") + "\n");
+    for (const w of warnings) {
+      process.stderr.write("  " + chalk.yellow("• ") + w + "\n");
+    }
+    process.stderr.write("\n");
+  }
+}