@fieldwangai/agentflow 0.1.25

package/bin/lib/flow-write.mjs

@@ -0,0 +1,395 @@
+/**
+ * 写入 flow.yaml（仅 user / workspace）。
+ * - user → ~/agentflow/pipelines/<flowId>/flow.yaml
+ * - workspace → <workspaceRoot>/.workspace/agentflow/pipelines/<flowId>/flow.yaml
+ * 包内 builtin/pipelines 不可直接覆盖写入。
+ */
+import fs from "fs";
+import path from "path";
+import yaml from "js-yaml";
+import {
+  ARCHIVED_PIPELINES_DIR_NAME,
+  getAgentflowDataRoot,
+  getUserPipelinesRoot,
+  LEGACY_PIPELINES_DIR,
+  PIPELINES_DIR,
+} from "./paths.mjs";
+import { getFlowYamlAbs } from "./catalog-flows.mjs";
+import { normalizeFlowYamlText } from "./flow-normalize.mjs";
+
+export const FLOW_YAML_FILENAME = "flow.yaml";
+
+/** @typedef {"user" | "workspace"} FlowWriteSource */
+
+/** 用户新建流水线 ID：英文字母开头，仅字母、数字、下划线、连字符 */
+export const USER_PIPELINE_ID_RE = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+
+const USER_PIPELINE_ID_MAX = 128;
+
+/**
+ * @param {string} flowId
+ * @returns {{ ok: true, flowId: string } | { ok: false, error: string }}
+ */
+export function validateUserPipelineId(flowId) {
+  if (flowId == null || typeof flowId !== "string") {
+    return { ok: false, error: "缺少流水线名称" };
+  }
+  const t = flowId.trim();
+  if (!t) {
+    return { ok: false, error: "流水线名称不能为空" };
+  }
+  if (t.length > USER_PIPELINE_ID_MAX) {
+    return { ok: false, error: `流水线名称过长（最多 ${USER_PIPELINE_ID_MAX} 字符）` };
+  }
+  if (!USER_PIPELINE_ID_RE.test(t)) {
+    return {
+      ok: false,
+      error: "名称须以英文字母开头，仅可使用字母、数字、下划线 _ 与连字符 -",
+    };
+  }
+  return { ok: true, flowId: t };
+}
+
+/**
+ * 空流水线 flow.yaml（instances / edges 为空；介绍写入 ui.description）
+ * @param {{ description?: string }} [options]
+ */
+export function buildEmptyUserFlowYaml(options = {}) {
+  /** @type {Record<string, unknown>} */
+  const ui = { nodePositions: {} };
+  const d = options.description;
+  if (d != null && String(d).trim() !== "") {
+    ui.description = String(d).trim();
+  }
+  return yaml.dump({ instances: {}, edges: [], ui }, { lineWidth: -1 });
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {FlowWriteSource} source
+ */
+function getPipelinesRootByWriteSource(workspaceRoot, source) {
+  if (source === "workspace") {
+    return path.join(path.resolve(workspaceRoot), PIPELINES_DIR);
+  }
+  return getUserPipelinesRoot();
+}
+
+/**
+ * 工作区内已存在的流水线目录（新路径优先，其次旧版 .cursor 路径）。
+ * @returns {string | null}
+ */
+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;
+  }
+  return null;
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {string} flowId
+ * @param {FlowWriteSource} flowSource
+ * @returns {{ flowDir: string, error?: string }}
+ */
+export function resolveFlowDirForWrite(workspaceRoot, flowId, flowSource) {
+  if (!workspaceRoot || !flowId) {
+    return { flowDir: "", error: "workspaceRoot and flowId are required" };
+  }
+  if (/[/\\.]/.test(flowId) || flowId === "..") {
+    return { flowDir: "", error: "invalid flowId" };
+  }
+  if (flowSource === "builtin") {
+    return { flowDir: "", error: "cannot write package builtin pipelines; use workspace or user" };
+  }
+  if (flowSource !== "user" && flowSource !== "workspace") {
+    return { flowDir: "", error: "flowSource must be user or workspace" };
+  }
+
+  let boundariesBase;
+  if (flowSource === "user") {
+    boundariesBase = path.resolve(getAgentflowDataRoot());
+    try {
+      if (fs.existsSync(boundariesBase)) boundariesBase = fs.realpathSync(boundariesBase);
+    } catch (_) {
+      /* keep boundariesBase */
+    }
+  } else {
+    const normalized = path.normalize(workspaceRoot);
+    try {
+      boundariesBase = fs.realpathSync(normalized);
+    } catch {
+      return { flowDir: "", error: "base path does not exist or is inaccessible" };
+    }
+  }
+
+  const pipelinesRoot = getPipelinesRootByWriteSource(workspaceRoot, flowSource);
+  const flowDir = path.join(pipelinesRoot, flowId);
+  const resolvedFlowDir = path.resolve(flowDir);
+  const baseWithSep = boundariesBase.endsWith(path.sep) ? boundariesBase : boundariesBase + path.sep;
+  if (resolvedFlowDir !== boundariesBase && !resolvedFlowDir.startsWith(baseWithSep)) {
+    return { flowDir: "", error: "flow path is outside base path" };
+  }
+  return { flowDir };
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {string} flowId
+ * @param {FlowWriteSource} flowSource
+ * @param {string} flowYaml
+ * @returns {{ success: true } | { success: false, error: string }}
+ */
+/**
+ * @param {string} workspaceRoot
+ * @param {string} flowId
+ * @param {FlowWriteSource} flowSource
+ * @returns {{ flowDir: string, error?: string }}
+ */
+export function resolveArchivedFlowDirForWrite(workspaceRoot, flowId, flowSource) {
+  if (!workspaceRoot || !flowId) {
+    return { flowDir: "", error: "workspaceRoot and flowId are required" };
+  }
+  if (/[/\\.]/.test(flowId) || flowId === "..") {
+    return { flowDir: "", error: "invalid flowId" };
+  }
+  if (flowSource !== "user" && flowSource !== "workspace") {
+    return { flowDir: "", error: "flowSource must be user or workspace" };
+  }
+
+  let boundariesBase;
+  if (flowSource === "user") {
+    boundariesBase = path.resolve(getAgentflowDataRoot());
+    try {
+      if (fs.existsSync(boundariesBase)) boundariesBase = fs.realpathSync(boundariesBase);
+    } catch (_) {
+      /* keep */
+    }
+  } else {
+    const normalized = path.normalize(workspaceRoot);
+    try {
+      boundariesBase = fs.realpathSync(normalized);
+    } catch {
+      return { flowDir: "", error: "base path does not exist or is inaccessible" };
+    }
+  }
+
+  const pipelinesRoot = getPipelinesRootByWriteSource(workspaceRoot, flowSource);
+  const flowDir = path.join(pipelinesRoot, ARCHIVED_PIPELINES_DIR_NAME, flowId);
+  const resolvedFlowDir = path.resolve(flowDir);
+  const baseWithSep = boundariesBase.endsWith(path.sep) ? boundariesBase : boundariesBase + path.sep;
+  if (resolvedFlowDir !== boundariesBase && !resolvedFlowDir.startsWith(baseWithSep)) {
+    return { flowDir: "", error: "flow path is outside base path" };
+  }
+  return { flowDir };
+}
+
+/**
+ * @param {string} workspaceRoot
+ * @param {string} flowId
+ * @param {FlowWriteSource} flowSource
+ * @param {string} flowYaml
+ * @param {{ archived?: boolean }} [opts]
+ * @returns {{ success: true } | { success: false, error: string }}
+ */
+export function writeFlowYaml(workspaceRoot, flowId, flowSource, flowYaml, opts = {}) {
+  const archived = Boolean(opts.archived);
+  const { flowDir, error } = archived
+    ? resolveArchivedFlowDirForWrite(workspaceRoot, flowId, flowSource)
+    : resolveFlowDirForWrite(workspaceRoot, flowId, flowSource);
+  if (error) return { success: false, error };
+  try {
+    fs.mkdirSync(flowDir, { recursive: true });
+    const normalized = normalizeFlowYamlText(flowYaml ?? "").text;
+    fs.writeFileSync(path.join(flowDir, FLOW_YAML_FILENAME), normalized, "utf-8");
+    return { success: true };
+  } catch (e) {
+    return { success: false, error: (e && e.message) || String(e) };
+  }
+}
+
+/**
+ * 将活跃流水线目录移入 `pipelines/_archived/<flowId>/`（仅 user / workspace）。
+ * @param {string} workspaceRoot
+ * @param {string} flowId
+ * @param {FlowWriteSource} flowSource
+ * @returns {{ success: true } | { success: false, error: string }}
+ */
+export function archiveFlowPipeline(workspaceRoot, flowId, flowSource) {
+  if (flowSource !== "user" && flowSource !== "workspace") {
+    return { success: false, error: "仅支持用户目录或工作区流水线归档" };
+  }
+  const yamlRes = getFlowYamlAbs(workspaceRoot, flowId, flowSource, { archived: false });
+  if (yamlRes.error || !yamlRes.path) {
+    return { success: false, error: yamlRes.error || "找不到流水线" };
+  }
+  const fromDir = path.dirname(yamlRes.path);
+  const sep = path.sep;
+  if (fromDir.split(sep).includes(ARCHIVED_PIPELINES_DIR_NAME)) {
+    return { success: false, error: "该流水线已在归档目录中" };
+  }
+  const toRes = resolveArchivedFlowDirForWrite(workspaceRoot, flowId, flowSource);
+  if (toRes.error || !toRes.flowDir) {
+    return { success: false, error: toRes.error || "无法解析归档路径" };
+  }
+  const toDir = toRes.flowDir;
+  if (fs.existsSync(toDir)) {
+    return { success: false, error: "归档位置已存在同名目录" };
+  }
+  try {
+    fs.mkdirSync(path.dirname(toDir), { recursive: true });
+    fs.renameSync(fromDir, toDir);
+  } catch (e) {
+    return { success: false, error: (e && e.message) || String(e) };
+  }
+  return { success: true };
+}
+
+/**
+ * 在用户目录与工作区之间移动整个流水线目录（含 nodes 等）。
+ * @param {string} workspaceRoot
+ * @param {string} flowId
+ * @param {"user" | "workspace"} fromSource
+ * @param {"user" | "workspace"} toSource
+ * @returns {{ success: true, flowSource: "user" | "workspace" } | { success: false, error: string }}
+ */
+export function moveFlowDirectory(workspaceRoot, flowId, fromSource, toSource) {
+  if (fromSource === toSource) {
+    return { success: false, error: "fromSource and toSource must differ" };
+  }
+  if (
+    (fromSource !== "user" && fromSource !== "workspace") ||
+    (toSource !== "user" && toSource !== "workspace")
+  ) {
+    return { success: false, error: "only user and workspace are allowed for move" };
+  }
+  let fromDir;
+  if (fromSource === "workspace") {
+    const w = resolveFlowDirForWrite(workspaceRoot, flowId, "workspace");
+    if (w.error || !w.flowDir) return { success: false, error: w.error || "invalid source path" };
+    fromDir = resolveExistingWorkspaceFlowDir(workspaceRoot, flowId);
+    if (!fromDir) return { success: false, error: "source flow not found" };
+  } else {
+    const fromRes = resolveFlowDirForWrite(workspaceRoot, flowId, fromSource);
+    if (fromRes.error || !fromRes.flowDir) return { success: false, error: fromRes.error || "invalid source path" };
+    fromDir = fromRes.flowDir;
+  }
+  const toRes = resolveFlowDirForWrite(workspaceRoot, flowId, toSource);
+  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))) {
+    return { success: false, error: "source flow not found" };
+  }
+  if (fs.existsSync(toDir)) {
+    return { success: false, error: "target location already exists" };
+  }
+  try {
+    fs.mkdirSync(path.dirname(toDir), { recursive: true });
+    fs.renameSync(fromDir, toDir);
+  } catch (e) {
+    return { success: false, error: (e && e.message) || String(e) };
+  }
+  return { success: true, flowSource: toSource };
+}
+
+/**
+ * @param {string} flowDir
+ * @param {string} workspaceRoot
+ * @param {FlowWriteSource} flowSource
+ * @param {string} flowId
+ * @returns {{ ok: true } | { ok: false, error: string }}
+ */
+function assertFlowDirIsSafeToDelete(flowDir, workspaceRoot, flowSource, flowId) {
+  let realDir;
+  try {
+    realDir = fs.realpathSync(flowDir);
+  } catch {
+    return { ok: false, error: "流水线目录不可访问" };
+  }
+  if (path.basename(realDir) !== flowId) {
+    return { ok: false, error: "目录与流水线 ID 不匹配" };
+  }
+  const root = path.resolve(workspaceRoot);
+  /** @type {string[]} */
+  const allowedRoots = [];
+  if (flowSource === "user") {
+    try {
+      allowedRoots.push(fs.realpathSync(getUserPipelinesRoot()));
+    } catch {
+      allowedRoots.push(path.resolve(getUserPipelinesRoot()));
+    }
+    for (const rel of [PIPELINES_DIR, LEGACY_PIPELINES_DIR]) {
+      const base = path.join(root, rel);
+      if (fs.existsSync(base)) {
+        try {
+          allowedRoots.push(fs.realpathSync(base));
+        } catch {
+          allowedRoots.push(path.resolve(base));
+        }
+      }
+    }
+  } else {
+    for (const rel of [PIPELINES_DIR, LEGACY_PIPELINES_DIR]) {
+      const base = path.join(root, rel);
+      if (fs.existsSync(base)) {
+        try {
+          allowedRoots.push(fs.realpathSync(base));
+        } catch {
+          allowedRoots.push(path.resolve(base));
+        }
+      }
+    }
+  }
+
+  for (const allowed of allowedRoots) {
+    const sep = allowed.endsWith(path.sep) ? allowed : allowed + path.sep;
+    if (realDir !== allowed && !realDir.startsWith(sep)) continue;
+    const rel = path.relative(allowed, realDir);
+    const parts = rel.split(path.sep).filter(Boolean);
+    if (parts.length === 1 && parts[0] === flowId) return { ok: true };
+    if (
+      parts.length === 2 &&
+      parts[0] === ARCHIVED_PIPELINES_DIR_NAME &&
+      parts[1] === flowId
+    ) {
+      return { ok: true };
+    }
+  }
+  return { ok: false, error: "拒绝删除：路径不在允许的 pipelines 目录内" };
+}
+
+/**
+ * 永久删除流水线目录（含 flow.yaml、scripts 等）。仅 user / workspace；内置只读不可删。
+ * @param {string} workspaceRoot
+ * @param {string} flowId
+ * @param {FlowWriteSource} flowSource
+ * @param {{ archived?: boolean }} [opts]
+ * @returns {{ success: true } | { success: false, error: string }}
+ */
+export function deleteFlowPipeline(workspaceRoot, flowId, flowSource, opts = {}) {
+  if (flowSource === "builtin") {
+    return { success: false, error: "内置流水线不可删除" };
+  }
+  if (flowSource !== "user" && flowSource !== "workspace") {
+    return { success: false, error: "仅支持删除用户目录或工作区流水线" };
+  }
+  if (!flowId || typeof flowId !== "string" || /[/\\.]/.test(flowId) || flowId === "..") {
+    return { success: false, error: "invalid flowId" };
+  }
+  const archived = Boolean(opts.archived);
+  const yamlRes = getFlowYamlAbs(workspaceRoot, flowId, flowSource, { archived });
+  if (yamlRes.error || !yamlRes.path) {
+    return { success: false, error: yamlRes.error || "找不到流水线" };
+  }
+  const flowDir = path.dirname(yamlRes.path);
+  const guard = assertFlowDirIsSafeToDelete(flowDir, workspaceRoot, flowSource, flowId);
+  if (!guard.ok) return { success: false, error: guard.error };
+  try {
+    fs.rmSync(flowDir, { recursive: true, force: true });
+    return { success: true };
+  } catch (e) {
+    return { success: false, error: (e && e.message) || String(e) };
+  }
+}

package/bin/lib/help.mjs

@@ -0,0 +1,139 @@
+import { log } from "./log.mjs";
+import { t } from "./i18n.mjs";
+
+export function printHelp() {
+  const lang = process.env.AGENTFLOW_LANG || "zh";
+  const isZh = lang === "zh";
+
+  // 根据语言输出不同的帮助文本
+  if (isZh) {
+    log.info(`
+AgentFlow CLI — 使用 Cursor / OpenCode / Claude Code 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]  本地 HTTP：流水线列表 + React Flow 节点流程图编辑保存（默认 127.0.0.1:8765；可用 AGENTFLOW_UI_HOST）
+  agentflow scheduler start [--poll-ms <ms>]  启动定时执行调度器（读取各流水线 schedule.json）
+  agentflow scheduler status [--json]         查看定时执行配置与状态
+  agentflow apply <FlowName> [uuid]            或 agentflow apply <uuid>（由 uuid 反查 pipeline）
+  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 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 模型列表并写入 ~/agentflow/model-lists.json；--json 时输出 { cursor, opencode }
+  agentflow write-flow <flowId> --json --flow-source <user|workspace>   从 stdin 读入 YAML 写入用户目录或工作区（builtin 已弃用，将视为 workspace）
+  agentflow --help
+
+选项：
+  --workspace-root <path>  工作区根目录（默认：当前目录）
+  --dry-run                （仅 apply）打印就绪节点后退出，不执行 Cursor agent
+  --model <name>           后端模型。默认走 Cursor；前缀 opencode:<model>、claude-code:<model>、api:<provider>/<model> 可切换后端。覆盖 CURSOR_AGENT_MODEL。
+  --input <name>=<value>   （仅 apply）覆盖 flow 中 provide 节点的值。value 前缀 file: 表示文件路径。可多次使用。
+  --debug                  显示调试日志（灰色，低优先级）
+  --force                  传递 --force/--trust 给 Cursor；设置 OPENCODE_PERMISSION 允许 OpenCode 的 external_directory（默认开启）。使用 --no-force 禁用。
+  --parallel               并行运行同轮就绪节点（默认关闭）。多个 Cursor CLI 进程可能竞争 ~/.cursor/cli-config.json。
+  --machine-readable       向 stdout 每行输出一个 JSON 事件（apply-start/node-start/node-done/node-failed/apply-done/apply-paused）。供 UI 运行按钮使用：解析 stdout 显示当前节点；Cursor agent 输出转到 stderr。
+  --lang <code>            设置语言：en、zh（默认：zh，或从 LANG 环境变量检测）
+
+路径说明：
+  runBuild 目录：<flowRuntimeRoot>/runBuild（每个 flow 与其 pipeline 源同 root）
+    user-scope：~/agentflow/pipelines/<flow>/runBuild
+    workspace-scope：<workspaceRoot>/.workspace/agentflow/pipelines/<flow>/runBuild
+  旧位置（仅历史兼容读取）：
+    <workspaceRoot>/.workspace/agentflow/runBuild
+    ~/agentflow/runBuild
+
+Apply：构建运行目录，解析流程，循环运行就绪节点。
+  使用 -ai / --ai：运行单步供外部（AI）多轮控制：
+    agentflow apply -ai ensure-run-dir <workspaceRoot> [uuid] <flowName>
+    agentflow apply -ai parse-flow <workspaceRoot> <flowName> <uuid> [flowDir]
+    agentflow apply -ai get-ready-nodes <workspaceRoot> <flowName> <uuid>
+    agentflow apply -ai pre-process-node <workspaceRoot> <flowName> <uuid> <instanceId>
+    agentflow apply -ai post-process-node <workspaceRoot> <flowName> <uuid> <instanceId> [execId]
+    agentflow apply -ai write-result <workspaceRoot> <flowName> <uuid> <instanceId> --json '<JSON>'
+    agentflow apply -ai run-tool-nodejs <workspaceRoot> <flowName> <uuid> <instanceId> [execId] -- <scriptCmd> [args...]
+    agentflow apply -ai get-env <workspaceRoot> <flowName> <uuid> <instanceId> <execId> <key>
+    agentflow apply -ai validate-flow <workspaceRoot> <flowName> <flowDir> [uuid]
+    agentflow apply -ai collect-nodes <workspaceRoot> <flowName> [runDir]
+    agentflow apply -ai gc <workspaceRoot> [--list] [--dry-run] [--delete] [--keep N] [--older-than N]
+    agentflow apply -ai extract-thinking <workspaceRoot> <flowName> <uuid>
+Resume：将 pending 和 failed 节点标记为成功（例如 UserCheck 确认后或重试失败后），然后继续 apply。
+Replay：运行单个节点（pre-process → execute → post-process）。
+
+需要：Node >=18，以下任一 CLI 在 PATH 中用于节点执行：Cursor CLI（'agent'，默认）、OpenCode CLI（'opencode'，env 覆盖 OPENCODE_CMD）、Claude Code CLI（'claude'，env 覆盖 CLAUDE_CODE_CMD，需先 'claude /login'）。
+Apply/replay 脚本已打包在 agentflow 包中（bin/pipeline/）。
+`);
+  } else {
+    // 英文版本
+    log.info(`
+AgentFlow CLI — drive apply/replay with Cursor / OpenCode / Claude Code 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]  Local HTTP: pipeline list + React Flow node diagram editor (default 127.0.0.1:8765; AGENTFLOW_UI_HOST supported)
+  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 apply <FlowName> [uuid]            Or agentflow apply <uuid> (resolve pipeline from uuid)
+  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 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 model lists to ~/agentflow/model-lists.json; --json outputs { cursor, opencode }
+  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:
+  --workspace-root <path>  Workspace root (default: cwd)
+  --dry-run                (apply only) Print ready nodes and exit without running Cursor agent
+  --model <name>           Backend model. Default routes to Cursor; prefixes opencode:<model>, claude-code:<model>, api:<provider>/<model> switch backend. Overrides CURSOR_AGENT_MODEL.
+  --input <name>=<value>   (apply only) Override provide node values in flow. Prefix value with file: for file paths. Can be used multiple times.
+  --debug                  Show debug logs (gray, low priority)
+  --force                  Pass --force/--trust to Cursor; set OPENCODE_PERMISSION to allow external_directory for OpenCode (default: on). Use --no-force to disable.
+  --parallel               Run same-round ready nodes in parallel (default: off). Multiple Cursor CLI processes may race on ~/.cursor/cli-config.json.
+  --machine-readable       Emit one JSON event per line to stdout (apply-start/node-start/node-done/node-failed/apply-done/apply-paused). For UI run button: parse stdout to show current node; Cursor agent output goes to stderr.
+  --lang <code>            Set language: en, zh (default: en, or auto-detect from LANG env)
+
+Path notes:
+  runBuild dir: <flowRuntimeRoot>/runBuild (per-flow, co-located with pipeline source)
+    user-scope: ~/agentflow/pipelines/<flow>/runBuild
+    workspace-scope: <workspaceRoot>/.workspace/agentflow/pipelines/<flow>/runBuild
+  Legacy dirs (read-only compatibility):
+    <workspaceRoot>/.workspace/agentflow/runBuild
+    ~/agentflow/runBuild
+
+Apply: builds run dir, parses flow, runs ready nodes in a loop.
+  With -ai / --ai: run a single step for external (AI) multi-round control:
+    agentflow apply -ai ensure-run-dir <workspaceRoot> [uuid] <flowName>
+    agentflow apply -ai parse-flow <workspaceRoot> <flowName> <uuid> [flowDir]
+    agentflow apply -ai get-ready-nodes <workspaceRoot> <flowName> <uuid>
+    agentflow apply -ai pre-process-node <workspaceRoot> <flowName> <uuid> <instanceId>
+    agentflow apply -ai post-process-node <workspaceRoot> <flowName> <uuid> <instanceId> [execId]
+    agentflow apply -ai write-result <workspaceRoot> <flowName> <uuid> <instanceId> --json '<JSON>'
+    agentflow apply -ai run-tool-nodejs <workspaceRoot> <flowName> <uuid> <instanceId> [execId] -- <scriptCmd> [args...]
+    agentflow apply -ai get-env <workspaceRoot> <flowName> <uuid> <instanceId> <execId> <key>
+    agentflow apply -ai validate-flow <workspaceRoot> <flowName> <flowDir> [uuid]
+    agentflow apply -ai collect-nodes <workspaceRoot> <flowName> [runDir]
+    agentflow apply -ai gc <workspaceRoot> [--list] [--dry-run] [--delete] [--keep N] [--older-than N]
+    agentflow apply -ai extract-thinking <workspaceRoot> <flowName> <uuid>
+Resume: marks pending and failed node(s) as success (e.g. after UserCheck confirm or retry failed), then continues apply.
+Replay: runs a single node (pre-process → execute → post-process).
+
+Requires: Node >=18, any of Cursor CLI ('agent', default), OpenCode CLI ('opencode', env OPENCODE_CMD), or Claude Code CLI ('claude', env CLAUDE_CODE_CMD, run 'claude /login' first) in PATH for node execution.
+Apply/replay scripts are bundled in the agentflow package (bin/pipeline/).
+`);
+  }
+}

package/bin/lib/hub-login.mjs

@@ -0,0 +1,54 @@
+/**
+ * agentflow login [--provider github|google]
+ * agentflow logout
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import chalk from "chalk";
+import { log } from "./log.mjs";
+import { getStoredSession, getUserProfile, loginWithBrowser } from "./hub.mjs";
+
+export async function hubLogin(argv) {
+  // Check if already logged in
+  const existing = await getStoredSession();
+  if (existing?.access_token) {
+    const user = await getUserProfile(existing.access_token);
+    if (user?.id) {
+      log.info(chalk.green("✓") + " Already logged in as " + chalk.bold(user.email || user.id));
+      log.info("  Use " + chalk.dim("agentflow logout") + " to sign out.");
+      return;
+    }
+  }
+
+  // Parse --provider flag
+  let provider = "github";
+  const providerIdx = argv.indexOf("--provider");
+  if (providerIdx >= 0 && argv[providerIdx + 1]) {
+    provider = argv[providerIdx + 1];
+  }
+  if (!["github", "google"].includes(provider)) {
+    throw new Error("Invalid provider: " + provider + ". Use github or google.");
+  }
+
+  log.info("Logging in to AgentFlow Hub via " + chalk.bold(provider) + "...");
+  const session = await loginWithBrowser(provider);
+
+  // Fetch user info
+  const user = await getUserProfile(session.access_token);
+  if (user?.id) {
+    log.info(chalk.green("✓") + " Logged in as " + chalk.bold(user.email || user.id));
+  } else {
+    log.info(chalk.green("✓") + " Login successful. Token stored.");
+  }
+}
+
+export function hubLogout() {
+  const configPath = path.join(os.homedir(), ".agentflow", "hub.json");
+  try {
+    fs.unlinkSync(configPath);
+    log.info(chalk.green("✓") + " Logged out. Token removed.");
+  } catch {
+    log.info("Not logged in.");
+  }
+}