@fieldwangai/agentflow 0.1.138 → 0.1.142

package/bin/lib/workflow-report.mjs

@@ -11,6 +11,8 @@ const WORKFLOW_ACTION_STATUSES = new Set([
   "cancelled",
   "observed",
 ]);
+const WORKFLOW_CHECKLIST_COMPLETION_POLICIES = new Set(["all_required", "any_required", "manual"]);
+const WORKFLOW_CHECKLIST_ITEM_STATUSES = new Set(["pending", "passed", "failed", "blocked", "skipped"]);
 const UNSAFE_OBJECT_KEYS = new Set(["__proto__", "prototype", "constructor"]);
 
 function plainObject(value) {
@@ -109,6 +111,98 @@ function normalizeStringList(value, maxItems = 100) {
   return uniqueValues(list.map((item) => cleanString(item, 240)).filter(Boolean)).slice(0, maxItems);
 }
 
+function normalizeChecklistSection(value, index = 0) {
+  const raw = plainObject(value);
+  const rawContent = raw.content ?? raw.value ?? raw.text ?? "";
+  const content = Array.isArray(rawContent)
+    ? rawContent.map((item) => cleanString(item, 4000)).filter(Boolean).slice(0, 100)
+    : cleanString(rawContent, 12000);
+  return {
+    key: cleanString(raw.key || raw.id || `section-${index + 1}`, 120),
+    title: cleanString(raw.title || raw.label || `Section ${index + 1}`, 500),
+    content,
+  };
+}
+
+function normalizeWorkflowChecklist(value) {
+  const raw = plainObject(value);
+  const rawDocument = plainObject(raw.document);
+  const items = (Array.isArray(raw.items) ? raw.items : []).map((value, index) => {
+    const item = plainObject(value);
+    const rawDetail = item.detail;
+    const detailObject = plainObject(rawDetail);
+    const sections = Array.isArray(detailObject.sections)
+      ? detailObject.sections.map((section, sectionIndex) => normalizeChecklistSection(section, sectionIndex))
+      : [];
+    const summary = typeof rawDetail === "string"
+      ? cleanString(rawDetail, 4000)
+      : cleanString(detailObject.summary || detailObject.description, 4000);
+    return {
+      key: cleanString(item.key || item.id, 240),
+      title: cleanString(item.title || item.label || item.key || item.id || `Item ${index + 1}`, 500),
+      required: item.required !== false,
+      ...(summary || sections.length ? { detail: { ...(summary ? { summary } : {}), ...(sections.length ? { sections } : {}) } } : {}),
+      ...(item.evidenceRequired === true || item.evidence_required === true ? { evidenceRequired: true } : {}),
+    };
+  });
+  const completionPolicy = cleanString(raw.completionPolicy || raw.completion_policy || "all_required", 40).toLowerCase();
+  const documentUrl = cleanString(rawDocument.url || rawDocument.href, 4000);
+  return {
+    schemaVersion: 1,
+    completionPolicy,
+    document: {
+      title: cleanString(rawDocument.title || rawDocument.label || "Checklist 详情", 500),
+      ...(rawDocument.artifactKey || rawDocument.artifact_key ? { artifactKey: cleanString(rawDocument.artifactKey || rawDocument.artifact_key, 500) } : {}),
+      ...(documentUrl ? { url: documentUrl } : {}),
+    },
+    items,
+  };
+}
+
+function validateWorkflowChecklist(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return "action.checklist must be an object";
+  const raw = plainObject(value);
+  const schemaVersion = Number(raw.schemaVersion ?? raw.schema_version ?? 1);
+  if (schemaVersion !== 1) return `Unsupported action.checklist schemaVersion: ${schemaVersion}`;
+  const completionPolicy = rawString(raw.completionPolicy || raw.completion_policy || "all_required").toLowerCase();
+  if (!WORKFLOW_CHECKLIST_COMPLETION_POLICIES.has(completionPolicy)) {
+    return `Invalid action.checklist completionPolicy: ${completionPolicy}`;
+  }
+  if (!Array.isArray(raw.items) || raw.items.length === 0) return "action.checklist requires at least one item";
+  if (raw.items.length > 100) return "action.checklist supports at most 100 items";
+  const seen = new Set();
+  for (let index = 0; index < raw.items.length; index += 1) {
+    const item = raw.items[index];
+    if (!item || typeof item !== "object" || Array.isArray(item)) return `action.checklist.items[${index}] must be an object`;
+    const key = rawString(item.key || item.id);
+    if (!key || key.length > 240 || /[\0\r\n]/.test(key)) return `action.checklist.items[${index}].key is invalid`;
+    if (seen.has(key)) return `action.checklist.items[${index}].key must be unique`;
+    seen.add(key);
+    if (stringExceeds(item.title || item.label || key, 500)) return `action.checklist.items[${index}].title exceeds 500 characters`;
+    if (item.detail != null && typeof item.detail !== "string" && (!item.detail || typeof item.detail !== "object" || Array.isArray(item.detail))) {
+      return `action.checklist.items[${index}].detail must be a string or object`;
+    }
+    const detail = plainObject(item.detail);
+    if (typeof item.detail === "string" && stringExceeds(item.detail, 4000)) return `action.checklist.items[${index}].detail exceeds 4000 characters`;
+    if (stringExceeds(detail.summary || detail.description, 4000)) return `action.checklist.items[${index}].detail.summary exceeds 4000 characters`;
+    if (detail.sections != null && !Array.isArray(detail.sections)) return `action.checklist.items[${index}].detail.sections must be an array`;
+    if (Array.isArray(detail.sections) && detail.sections.length > 50) return `action.checklist.items[${index}].detail.sections supports at most 50 entries`;
+  }
+  const document = plainObject(raw.document);
+  if (stringExceeds(document.title || document.label, 500)) return "action.checklist.document.title exceeds 500 characters";
+  if (stringExceeds(document.artifactKey || document.artifact_key, 500)) return "action.checklist.document.artifactKey exceeds 500 characters";
+  const documentUrl = rawString(document.url || document.href);
+  if (documentUrl && !isSafeWorkflowUrl(documentUrl)) return "action.checklist.document.url must use http, https, or an absolute application path";
+  return "";
+}
+
+export function normalizeWorkflowChecklistItemStatus(value) {
+  const raw = cleanString(value, 40).toLowerCase();
+  const aliases = { done: "passed", complete: "passed", completed: "passed", success: "passed", error: "failed", cancelled: "skipped", canceled: "skipped" };
+  const normalized = aliases[raw] || raw || "pending";
+  return WORKFLOW_CHECKLIST_ITEM_STATUSES.has(normalized) ? normalized : "pending";
+}
+
 function normalizeWorkflowArtifact(value, index = 0, defaultScope = "action") {
   const raw = plainObject(value);
   const url = cleanString(raw.url || raw.href, 4000);
@@ -347,6 +441,11 @@ export function normalizeWorkflowReport(payload = {}) {
   if (stringExceeds(rawAction.issueKey || rawAction.issue_key, 240)) return { error: "Workflow action issueKey exceeds 240 characters" };
   const rawTags = Array.isArray(rawAction.tags) ? rawAction.tags : rawAction.tags == null ? [] : [rawAction.tags];
   if (rawTags.length > 100 || rawTags.some((tag) => stringExceeds(tag, 240))) return { error: "Workflow action tags exceed supported limits" };
+  const hasChecklist = hasOwn(rawAction, "checklist");
+  if (hasChecklist) {
+    const checklistError = validateWorkflowChecklist(rawAction.checklist);
+    if (checklistError) return { error: checklistError };
+  }
   if (hasAction && !isKnownActionStatus(rawAction.status)) return { error: `Invalid workflow action status: ${rawAction.status}` };
   const rawOccurredAt = rawString(rawAction.occurredAt || rawAction.occurred_at || rawAction.completedAt || rawAction.startedAt);
   if (rawOccurredAt && !Number.isFinite(Date.parse(rawOccurredAt))) return { error: "action.occurredAt must be an ISO-compatible date" };
@@ -361,6 +460,7 @@ export function normalizeWorkflowReport(payload = {}) {
     ...(rawAction.platform ? { platform: cleanString(rawAction.platform, 80) } : {}),
     ...(rawAction.issueKey || rawAction.issue_key ? { issueKey: cleanString(rawAction.issueKey || rawAction.issue_key, 240) } : {}),
     ...(rawAction.tags != null ? { tags: normalizeStringList(rawAction.tags) } : {}),
+    ...(hasChecklist ? { checklist: normalizeWorkflowChecklist(rawAction.checklist) } : {}),
     occurredAt: cleanString(
       rawAction.occurredAt ||
       rawAction.occurred_at ||
@@ -539,6 +639,7 @@ export function normalizeWorkflowReport(payload = {}) {
       ...(action.platform ? { platform: action.platform } : {}),
       ...(action.issueKey ? { issueKey: action.issueKey } : {}),
       ...(action.tags ? { tags: action.tags } : {}),
+      ...(action.checklist ? { checklist: action.checklist } : {}),
       ...(action.occurredAt ? { occurredAt: action.occurredAt } : {}),
     } : {
       title: cleanString(payload.title || "Workflow 全局状态更新", 500),
@@ -600,6 +701,24 @@ function resourceVersion(value) {
   return `rv:${semanticHash(value)}`;
 }
 
+function actionDefinitionForVersion(event = {}) {
+  const action = plainObject(event.actionModel);
+  if (!Object.keys(action).length) return event;
+  const checklist = plainObject(action.checklist);
+  if (!Object.keys(checklist).length) return action;
+  const items = Array.isArray(checklist.items)
+    ? checklist.items.map((item) => {
+        const clean = { ...plainObject(item) };
+        delete clean.state;
+        return clean;
+      })
+    : [];
+  const cleanChecklist = { ...checklist, items };
+  delete cleanChecklist.progress;
+  delete cleanChecklist.source;
+  return { ...action, checklist: cleanChecklist };
+}
+
 function addObjectResourceVersions(out, prefix, value, path = []) {
   if (value === undefined) return;
   if (path.length) out[`${prefix}:${path.join(".")}`] = resourceVersion(value);
@@ -617,8 +736,15 @@ export function workflowSnapshotResourceVersions(snapshot = {}) {
     : [];
   for (const event of runtimeEvents) {
     const source = cleanString(event?.source || event?.producer || "agentflow", 120).toLowerCase() || "agentflow";
+    const checklistState = plainObject(event?.checklistState || event?.checklist_state);
+    const checklistSource = cleanString(checklistState.producer || checklistState.source, 120).toLowerCase();
+    const checklistActionKey = cleanString(checklistState.actionKey || checklistState.action_key, 240);
+    const checklistItemKey = cleanString(checklistState.itemKey || checklistState.item_key, 240);
+    if (checklistSource && checklistActionKey && checklistItemKey) {
+      out[`checklist:${checklistSource}:${checklistActionKey}:${checklistItemKey}`] = resourceVersion(checklistState);
+    }
     const actionKey = cleanString(event?.actionModel?.key || event?.action || event?.actionId || event?.stageKey, 240);
-    if (actionKey && event?.auxiliary !== true) out[`action:${source}:${actionKey}`] = resourceVersion(event);
+    if (actionKey && event?.auxiliary !== true) out[`action:${source}:${actionKey}`] = resourceVersion(actionDefinitionForVersion(event));
     for (const artifact of Array.isArray(event?.artifacts) ? event.artifacts : []) {
       const producer = cleanString(artifact?.producer || source, 120).toLowerCase() || source;
       const key = cleanString(artifact?.key || artifact?.artifactKey || artifact?.artifact_key, 500);

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

@@ -51,6 +51,13 @@ import {
 import { buildGitContext, inferGitRepoRootFromWorktree, loadGitWorktree, normalizeGitContext, unloadGitWorktree } from "../lib/git-worktree.mjs";
 import { createGitLabMergeRequest } from "../lib/gitlab-mr.mjs";
 import { sendWecomAppMarkdown, sendWecomGroupMarkdown } from "../lib/wecom.mjs";
+import {
+  advanceJenkinsBuild,
+  createJenkinsSkillInvoker,
+  normalizeJenkinsBuildConfig,
+  readJenkinsBuildState,
+  writeJenkinsBuildState,
+} from "../lib/jenkins.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -500,6 +507,106 @@ async function emitWecomMarkdownNode(workspaceRoot, flowName, uuid, instanceId,
   return emitLocalNoopPrompt(workspaceRoot, runDir, instanceId, "wecom-markdown", `${result.message}\n`);
 }
 
+function emitJenkinsBuildNode(workspaceRoot, flowName, uuid, instanceId, execId) {
+  const runDir = getRunDir(workspaceRoot, flowName, uuid);
+  const data = getResolvedValues(workspaceRoot, flowName, uuid, instanceId);
+  if (!data.ok) throw new Error("getResolvedValues failed");
+  const inputs = data.resolvedInputs || {};
+  const config = normalizeJenkinsBuildConfig(inputs);
+  const statePath = path.join(runDir, "state", `${instanceId}.jenkins.json`);
+  const priorState = readJenkinsBuildState(statePath);
+  if (priorState?.job && priorState.job !== config.job) {
+    throw new Error(`checkpoint job mismatch: ${priorState.job} != ${config.job}`);
+  }
+  let invoker = null;
+  const invoke = (operation, args) => {
+    if (!invoker) {
+      invoker = createJenkinsSkillInvoker({
+        workspaceRoot,
+        credentialRef: config.credentialRef,
+        env: process.env,
+      });
+    }
+    return invoker(operation, args);
+  };
+  const result = advanceJenkinsBuild({
+    state: priorState,
+    config,
+    invoke,
+    persistState: (state) => writeJenkinsBuildState(statePath, state),
+    nowMs: Date.now(),
+    cancelled: readCancelFlag(runDir),
+  });
+  writeJenkinsBuildState(statePath, result.state);
+  writeOutputSlot(runDir, instanceId, execId, "status", result.outputs?.status || result.state?.status || "");
+  writeOutputSlot(runDir, instanceId, execId, "url", result.outputs?.url || result.state?.url || result.state?.buildUrl || "");
+  writeOutputSlot(runDir, instanceId, execId, "qrUrl", result.outputs?.qrUrl || result.state?.qrUrl || "");
+
+  const message = result.message || result.state?.message || "Jenkins Build";
+  if (result.kind === "failed") {
+    writeResult(
+      workspaceRoot,
+      flowName,
+      uuid,
+      instanceId,
+      { status: "failed", message },
+      { execId, preserveBody: false, body: JSON.stringify({ status: "ERROR", message }, null, 2) },
+    );
+    throw new Error(message);
+  }
+
+  const promptPath = emitLocalNoopPrompt(
+    workspaceRoot,
+    runDir,
+    instanceId,
+    result.kind === "waiting" ? "jenkins-waiting" : "jenkins-complete",
+    `${message}\n`,
+  );
+  if (result.kind === "waiting") {
+    const waitId = `${uuid}:${instanceId}:jenkins-build`;
+    writeWaitState(runDir, {
+      waitId,
+      status: "waiting",
+      reason: "tool_jenkins_build",
+      resumeMode: "rerun",
+      flowName,
+      uuid,
+      instanceId,
+      execId,
+      phase: result.state?.phase || "queued",
+      buildNumber: result.state?.buildNumber || "",
+      wakeAt: result.wakeAt,
+      createdAt: priorState?.createdAt || new Date().toISOString(),
+    });
+    writeResult(
+      workspaceRoot,
+      flowName,
+      uuid,
+      instanceId,
+      { status: "pending", message },
+      { execId, preserveBody: false, body: JSON.stringify({ phase: result.state?.phase, wakeAt: result.wakeAt }, null, 2) },
+    );
+  } else {
+    writeResult(
+      workspaceRoot,
+      flowName,
+      uuid,
+      instanceId,
+      { status: "success", message },
+      {
+        execId,
+        preserveBody: false,
+        body: JSON.stringify({
+          status: result.outputs?.status || result.state?.status || "",
+          url: result.outputs?.url || result.state?.url || "",
+          qrUrl: result.outputs?.qrUrl || result.state?.qrUrl || "",
+        }, null, 2),
+      },
+    );
+  }
+  return { promptPath, lifecycle: result.kind };
+}
+
 function emitCdWorkspaceNode(workspaceRoot, flowName, uuid, instanceId, execId) {
   const runDir = getRunDir(workspaceRoot, flowName, uuid);
   const { inputs, workspaceContext } = resolveNodeRuntimeContexts(workspaceRoot, flowName, uuid, instanceId);
@@ -1203,26 +1310,29 @@ async function main() {
     return;
   }
 
-  if (definitionId === "tool_git_checkout" || definitionId === "tool_git_worktree_load" || definitionId === "tool_git_worktree_unload" || definitionId === "tool_gitlab_create_mr" || definitionId === "tool_wecom_send_group_markdown" || definitionId === "tool_wecom_send_app_markdown" || definitionId === "control_cd_workspace" || definitionId === "control_user_workspace" || definitionId === "control_load_skills" || definitionId === "tool_print") {
+  if (definitionId === "tool_git_checkout" || definitionId === "tool_git_worktree_load" || definitionId === "tool_git_worktree_unload" || definitionId === "tool_gitlab_create_mr" || definitionId === "tool_jenkins_build" || definitionId === "tool_wecom_send_group_markdown" || definitionId === "tool_wecom_send_app_markdown" || definitionId === "control_cd_workspace" || definitionId === "control_user_workspace" || definitionId === "control_load_skills" || definitionId === "tool_print") {
     try {
-      const promptPath =
+      const localResult =
         definitionId === "tool_git_checkout"
-          ? emitGitCheckoutNode(workspaceRoot, flowName, uuid, instanceId, execId, resultPathRel)
+          ? { promptPath: emitGitCheckoutNode(workspaceRoot, flowName, uuid, instanceId, execId, resultPathRel) }
           : definitionId === "tool_git_worktree_load"
-            ? emitGitWorktreeLoadNode(workspaceRoot, flowName, uuid, instanceId, execId)
+            ? { promptPath: emitGitWorktreeLoadNode(workspaceRoot, flowName, uuid, instanceId, execId) }
             : definitionId === "tool_git_worktree_unload"
-              ? emitGitWorktreeUnloadNode(workspaceRoot, flowName, uuid, instanceId, execId)
+              ? { promptPath: emitGitWorktreeUnloadNode(workspaceRoot, flowName, uuid, instanceId, execId) }
               : definitionId === "tool_gitlab_create_mr"
-                ? await emitGitLabCreateMrNode(workspaceRoot, flowName, uuid, instanceId, execId)
+                ? { promptPath: await emitGitLabCreateMrNode(workspaceRoot, flowName, uuid, instanceId, execId) }
+                : definitionId === "tool_jenkins_build"
+                  ? emitJenkinsBuildNode(workspaceRoot, flowName, uuid, instanceId, execId)
                 : definitionId === "tool_wecom_send_group_markdown" || definitionId === "tool_wecom_send_app_markdown"
-                  ? await emitWecomMarkdownNode(workspaceRoot, flowName, uuid, instanceId, execId, definitionId)
+                  ? { promptPath: await emitWecomMarkdownNode(workspaceRoot, flowName, uuid, instanceId, execId, definitionId) }
                   : definitionId === "control_cd_workspace"
-                    ? emitCdWorkspaceNode(workspaceRoot, flowName, uuid, instanceId, execId)
+                    ? { promptPath: emitCdWorkspaceNode(workspaceRoot, flowName, uuid, instanceId, execId) }
                     : definitionId === "control_user_workspace"
-                      ? emitUserWorkspaceNode(workspaceRoot, flowName, uuid, instanceId, execId)
+                      ? { promptPath: emitUserWorkspaceNode(workspaceRoot, flowName, uuid, instanceId, execId) }
                       : definitionId === "control_load_skills"
-                        ? emitLoadSkillsNode(workspaceRoot, flowName, uuid, instanceId, execId)
-                        : emitToolPrintNode(workspaceRoot, flowName, uuid, instanceId, execId);
+                        ? { promptPath: emitLoadSkillsNode(workspaceRoot, flowName, uuid, instanceId, execId) }
+                        : { promptPath: emitToolPrintNode(workspaceRoot, flowName, uuid, instanceId, execId) };
+      const promptPath = localResult.promptPath;
       writeCacheJsonForNode(workspaceRoot, flowName, uuid, instanceId, execId);
       logToRunTag(workspaceRoot, flowName, uuid, "pre-process", { event: "runtime-context-node", instanceId, definitionId });
       console.log(JSON.stringify({
@@ -1233,6 +1343,7 @@ async function main() {
         subagent: "agentflow-node-executor",
         optionalPromptPath: promptPath,
         definitionId,
+        ...(localResult.lifecycle ? { nodeLifecycle: localResult.lifecycle } : {}),
       }));
       return;
     } catch (e) {

package/bin/pipeline/run-log.mjs

@@ -21,11 +21,11 @@ const LOG_FILE = "logs/log.txt";
  * @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) {
+export function logToRunTag(workspaceRoot, flowName, uuid, tag, message, opts = {}) {
   if (!workspaceRoot || !flowName || !uuid) return;
   const text = typeof message === "string" ? message : JSON.stringify(message);
   try {
-    const runDir = getRunDir(workspaceRoot, flowName, uuid);
+    const runDir = opts.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`;

package/bin/pipeline/write-result.mjs

@@ -12,7 +12,7 @@
  *   import { writeResult } from "./write-result.mjs";
  *   writeResult(workspaceRoot, flowName, uuid, instanceId, fields, options?)
  * fields: { status, message, finishedAt?, outputPath?, branch?, cacheNotMetReason?, elapsedMs? }
- * options: { preserveBody?: boolean, body?: string, execId?: number }
+ * options: { preserveBody?: boolean, body?: string, execId?: number, runDir?: string }
  */
 
 import fs from "fs";
@@ -53,10 +53,10 @@ function getExistingBody(resultPath) {
  * @param {string} uuid - 本次 run 的 uuid
  * @param {string} instanceId - 节点 instance id
  * @param {{ status: string, message: string, finishedAt?: string, outputPath?: string, branch?: string, cacheNotMetReason?: string, elapsedMs?: number }} fields - 必填 status、message；可选其余（elapsedMs 为节点执行耗时毫秒，供 UI 展示）
- * @param {{ preserveBody?: boolean, body?: string, execId?: number }} [options] - preserveBody：保留已有正文；body：指定正文内容；execId：本轮 execId，缺省则从 memory 读取
+ * @param {{ preserveBody?: boolean, body?: string, execId?: number, runDir?: string }} [options] - preserveBody：保留已有正文；body：指定正文内容；execId：本轮 execId，缺省则从 memory 读取；runDir：多用户调度时使用已解析的精确运行目录
  */
 export function writeResult(workspaceRoot, flowName, uuid, instanceId, fields, options = {}) {
-  const runDir = getRunDir(workspaceRoot, flowName, uuid);
+  const runDir = options.runDir || getRunDir(workspaceRoot, flowName, uuid);
   const execId = options.execId ?? loadExecId(workspaceRoot, flowName, uuid, instanceId);
   const resultBasename = intermediateResultBasename(instanceId, execId);
   const resultPath = path.join(runDir, intermediateDirForNode(instanceId), resultBasename);
@@ -114,7 +114,7 @@ export function writeResult(workspaceRoot, flowName, uuid, instanceId, fields, o
     branch: branch ?? undefined,
     cacheNotMetReason: cacheNotMetReason ?? undefined,
     resultPathRel: path.relative(runDir, resultPath),
-  });
+  }, { runDir });
 }
 
 function main() {

package/builtin/nodes/tool_jenkins_build.md

@@ -0,0 +1,64 @@
+---
+# Built-in node: durable Jenkins build
+description: |
+  Trigger one Jenkins job and durably monitor it until completion.
+
+  The node persists queue/build checkpoints and never keeps a process blocked while waiting.
+  Scheduler re-enters the same node at `pollInterval`; an existing queueId/buildNumber is reused,
+  so a resumed run does not trigger the job again. Jenkins FAILURE/ABORTED/TIMEOUT are business
+  outcomes and continue to downstream notification nodes. Authentication, configuration, and
+  repeated platform request errors fail the AgentFlow node.
+
+  Credentials are read from environment configuration. `credentialRef: team-ci` selects
+  `JENKINS_TEAM_CI_BASE_URL`, `JENKINS_TEAM_CI_USERNAME`, and `JENKINS_TEAM_CI_TOKEN`, falling
+  back to the standard `JENKINS_BASE_URL`, `JENKINS_USERNAME`, and `JENKINS_TOKEN` variables.
+displayName: Jenkins Build
+input:
+  - type: node
+    name: prev
+    default: ""
+  - type: text
+    name: job
+    default: ""
+    required: true
+    showOnNode: true
+  - type: text
+    name: parameters
+    default: "{}"
+    description: "Jenkins Job 参数 JSON object。"
+    showOnNode: true
+  - type: text
+    name: credentialRef
+    default: ""
+    description: "Project Deployment 中配置的 Jenkins 凭证引用；不在 flow.yaml 中填写 token。"
+    showOnNode: false
+  - type: text
+    name: pollInterval
+    default: "30s"
+    showOnNode: false
+  - type: text
+    name: timeout
+    default: "2h"
+    showOnNode: false
+output:
+  - type: node
+    name: next
+    default: ""
+  - type: text
+    name: status
+    default: ""
+    required: true
+    showOnNode: true
+  - type: text
+    name: url
+    default: ""
+    required: true
+    description: "优先返回安装包 URL；没有安装包时返回 Jenkins Build URL。"
+    showOnNode: true
+  - type: text
+    name: qrUrl
+    default: ""
+    description: "解析到二维码时返回，否则为空。"
+    showOnNode: true
+---
+Trigger Jenkins job `${job}` with `${parameters}`, wait durably, then output `${status}`, `${url}`, and optional `${qrUrl}`.