@fieldwangai/agentflow 0.1.159 → 0.1.160

package/bin/pipeline/validate-flow.mjs

@@ -501,10 +501,10 @@ function checkFlowCore(nodes, edges, flowDir, nodeIdToSlots, getNodeBody, instan
         }
       }
 
-      // provide_str / provide_file / provide_bool output 类型校验
-      if (defId === "provide_str" || defId === "provide_file" || defId === "provide_bool") {
+      // provide_str / provide_json / provide_file / provide_bool output 类型校验
+      if (defId === "provide_str" || defId === "provide_json" || defId === "provide_file" || defId === "provide_bool") {
         const out = Array.isArray(inst.output) ? inst.output : [];
-        const expectedType = defId === "provide_file" ? "file" : defId === "provide_bool" ? "bool" : "text";
+        const expectedType = defId === "provide_file" ? "file" : defId === "provide_bool" ? "bool" : defId === "provide_json" ? "json" : "text";
         if (out.length !== 1) {
           errors.push(`节点 "${n.id}"（${defId}）output 必须仅有 1 个槽位（value:${expectedType}），当前 ${out.length} 个`);
         } else {

package/builtin/nodes/control_parse_json.md

@@ -0,0 +1,25 @@
+---
+# 内置节点：解析 JSON
+runtime: native
+type: control
+description: 显式解析并校验文本 JSON，成功后输出 json 类型；解析失败会终止本次运行。
+displayName: Parse JSON
+input:
+  - type: node
+    name: prev
+    default: ""
+  - type: text
+    name: value
+    default: ""
+    required: true
+    showOnNode: true
+output:
+  - type: node
+    name: next
+    default: ""
+  - type: json
+    name: result
+    default: "null"
+    showOnNode: true
+---
+Parse a text value as JSON and expose the validated result through a typed output.

package/builtin/nodes/control_subflow_call.md

@@ -0,0 +1,27 @@
+---
+# 内置节点：调用子流程
+runtime: native
+type: control
+palette: hidden
+description: |
+  调用 workspace.flow.js 中由 flow.subflow 声明的同 Workspace 子流程。
+  输入和输出槽来自子流程契约；每次调用使用独立调用帧，内部节点仍按标准 AgentFlow DSL 和运行时执行。
+displayName: Call Subflow
+ui:
+  card:
+    template: details
+    icon: account_tree
+    tone: purple
+    sections:
+      - type: subflow
+        label: Called subflow
+input:
+  - type: node
+    name: prev
+    default: ""
+output:
+  - type: node
+    name: next
+    default: ""
+---
+Execute the referenced inline subflow using its declared input and output contract.

package/builtin/nodes/control_while.md

@@ -0,0 +1,124 @@
+---
+# 内置节点：While 单步推进
+runtime: native
+description: |
+  Repeatedly execute either an explicit Condition/Body subflow pair or one legacy deterministic
+  step command (`script` or `scriptRef`) without adding a cycle to the Workspace graph. A Run
+  restarted after `wait` resumes from the saved output state.
+
+  Preferred DSL form:
+  `control.while("Advance", { state, maxIterations, timeout }, conditionFlow, bodyFlow)`.
+  Condition must accept `state` and `iteration`, and return `decision` plus optional `summary`.
+  Only `continue` invokes Body. Body must accept `state`, `iteration`, and `idempotencyKey`, and
+  return the next `state` plus optional `summary`. `wait`, `done`, and `fail` skip Body.
+
+  In legacy script mode, the command runs once per iteration and stdout must be exactly one JSON object:
+  `{"decision":"continue|wait|done|fail","state":{},"summary":"..."}`.
+  `continue` starts another iteration, `wait` pauses this Run before downstream nodes, `done`
+  continues downstream, and `fail` fails the node. A missing `state` keeps the previous state.
+
+  Each step receives `AGENTFLOW_WHILE_STATE` (JSON), the absolute
+  `AGENTFLOW_WHILE_ITERATION`, `AGENTFLOW_WHILE_MAX_ITERATIONS`,
+  `AGENTFLOW_WHILE_TIMEOUT_MS`, and a stable per-iteration
+  `AGENTFLOW_WHILE_IDEMPOTENCY_KEY`. Pass the idempotency key to external write APIs when they
+  support one. Write progress logs to stderr because stdout is reserved for the decision object.
+  The command also supports the same runtime placeholders as `tool.nodejs`, including
+  `${flowDir}` and `${workspaceRoot}`.
+
+  A waiting checkpoint retains state, history, elapsed active time, and the next absolute
+  iteration. `maxIterations` and `timeout` are cumulative across resumes. A changed input resets
+  the checkpoint; a matching but malformed checkpoint fails closed. Step output is schema-strict
+  and bounded: unknown fields are rejected, state/stdout are limited to 1 MiB, stderr to 256 KiB,
+  and summary to 4000 characters.
+displayName: While
+ui:
+  card:
+    template: state-machine
+    icon: repeat
+    tone: purple
+    sections:
+      - type: binding
+        label: State input
+        input: state
+      - type: loop
+        label: Loop execution
+        field: script
+      - type: decision
+        label: Decision from step
+        output: decision
+        source: step.stdout.decision
+        options:
+          - value: continue
+            label: continue ↻
+            tone: purple
+            description: 保存 state 并立即进入下一轮
+          - value: wait
+            label: wait ⏸
+            tone: amber
+            description: 保存 checkpoint，暂停当前 Run
+          - value: done
+            label: done →
+            tone: green
+            description: 结束循环并继续下游
+          - value: fail
+            label: fail ×
+            tone: red
+            description: 终止并标记节点失败
+      - type: metrics
+        label: Limits and progress
+        items:
+          - label: Iteration
+            output: iterations
+            maxInput: maxIterations
+          - label: Timeout
+            input: timeout
+      - type: summary
+        label: Latest outcome
+        output: summary
+      - type: history
+        label: Iteration history
+        output: history
+        limit: 3
+input:
+  - type: node
+    name: prev
+    default: ""
+  - type: json
+    name: state
+    default: "null"
+  - type: text
+    name: maxIterations
+    default: "20"
+  - type: text
+    name: timeout
+    default: "30m"
+output:
+  - type: node
+    name: next
+    default: ""
+  - type: json
+    name: result
+    default: ""
+  - type: json
+    name: state
+    default: "null"
+  - type: text
+    name: decision
+    default: ""
+    showOnNode: true
+  - type: text
+    name: iterations
+    default: "0"
+    showOnNode: true
+  - type: text
+    name: summary
+    default: ""
+    showOnNode: true
+  - type: json
+    name: history
+    default: "[]"
+  - type: text
+    name: checkpointFingerprint
+    default: ""
+---
+${USER_PROMPT}

package/builtin/nodes/provide_json.md

@@ -0,0 +1,14 @@
+---
+# 内置节点：直接提供 JSON
+runtime: native
+type: provide
+description: 提供经过校验的 JSON 值，输出可以直接连接 json 类型输入。
+displayName: JSON
+output:
+  - type: json
+    name: value
+    default: "null"
+    required: true
+    showOnNode: true
+---
+${USER_PROMPT}

package/builtin/nodes/workspace_subflow_input.md

@@ -0,0 +1,14 @@
+---
+# 内置节点：子流程输入
+runtime: native
+type: control
+palette: hidden
+description: 子流程调用帧的输入代理。只允许通过 flow.input 创建，不在节点面板中展示。
+displayName: Subflow Input
+input: []
+output:
+  - type: text
+    name: value
+    default: ""
+---
+Expose one value injected by a flow.call invocation.

package/builtin/pipelines/subflow-preview/workspace.flow.js

@@ -0,0 +1,29 @@
+import { agent, control, display, file, flow, provide, tool, workspace } from "agentflow/flow";
+
+const issueIn = flow.input("issue", "text");
+
+const inspect = agent.subAgent("分析单个 Issue", {
+  issue: issueIn.value,
+}, "只分析本次输入的一个 Issue，给出目标、风险和下一步。不要处理其它 Issue。");
+
+const normalize = tool.nodejs("规范化交付摘要", {
+  analysis: inspect.result,
+}, `node -e 'process.stdout.write(process.argv[1])' \${analysis}`);
+
+export const inspectIssue = flow.subflow("Issue 单项分析", { issue: issueIn }, flow(inspect, normalize), { summary: normalize.result, raw: inspect.result });
+
+export const request = provide.str("待分析 Issue", {
+  value: "LIKEE-1842 · Android 评论气泡样式需要统一",
+});
+
+const callInspect = flow.call("调用 Issue 分析子流程", inspectIssue, {
+  issue: request.value,
+});
+
+const { summary, raw } = callInspect;
+
+const preview = display.markdown("父流程收到的结果", {
+  content: summary,
+});
+
+export const run = flow("运行案例", callInspect, preview);

package/builtin/pipelines/subflow-preview/workspace.layout.json

@@ -0,0 +1,38 @@
+{
+  "version": 1,
+  "nodes": {
+    "callInspect": {
+      "x": 460,
+      "y": 80,
+      "w": 410,
+      "h": 330
+    },
+    "inspect": {
+      "x": 500,
+      "y": 700
+    },
+    "issueIn": {
+      "x": 100,
+      "y": 700
+    },
+    "normalize": {
+      "x": 900,
+      "y": 700
+    },
+    "preview": {
+      "x": 940,
+      "y": 80,
+      "w": 560,
+      "h": 420
+    },
+    "request": {
+      "x": 80,
+      "y": 80
+    },
+    "run": {
+      "x": 80,
+      "y": 300
+    }
+  },
+  "description": "子流程案例：父流程通过 flow.call 调用带输入/输出契约的标准节点子图"
+}

package/builtin/pipelines/subflow-preview/workspace.nodes.json

@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "nodes": {
+    "callInspect": {
+      "subflowId": "inspectIssue"
+    },
+    "inspect": {
+      "subflowId": "inspectIssue"
+    },
+    "issueIn": {
+      "subflowId": "inspectIssue",
+      "subflowInputName": "issue",
+      "subflowInputType": "text"
+    },
+    "normalize": {
+      "subflowId": "inspectIssue"
+    }
+  }
+}

package/builtin/pipelines/subflow-preview/workspace.state.json

@@ -0,0 +1,93 @@
+{
+  "version": 1,
+  "inputs": {
+    "inspect": {
+      "workspaceContext": {
+        "value": ""
+      },
+      "skillsContext": {
+        "value": ""
+      },
+      "mcpContext": {
+        "value": ""
+      },
+      "knowledgeContext": {
+        "value": ""
+      },
+      "issue": {
+        "value": ""
+      }
+    },
+    "normalize": {
+      "workspaceContext": {
+        "value": ""
+      },
+      "skillsContext": {
+        "value": ""
+      },
+      "mcpContext": {
+        "value": ""
+      },
+      "analysis": {
+        "value": ""
+      }
+    },
+    "callInspect": {
+      "issue": {
+        "value": ""
+      }
+    },
+    "preview": {
+      "content": {
+        "value": ""
+      }
+    }
+  },
+  "outputs": {
+    "issueIn": {
+      "value": {
+        "value": ""
+      }
+    },
+    "inspect": {
+      "next": {
+        "value": ""
+      },
+      "result": {
+        "value": ""
+      }
+    },
+    "normalize": {
+      "next": {
+        "value": ""
+      },
+      "result": {
+        "value": ""
+      }
+    },
+    "callInspect": {
+      "next": {
+        "value": ""
+      },
+      "summary": {
+        "value": ""
+      },
+      "raw": {
+        "value": ""
+      }
+    },
+    "preview": {
+      "content": {
+        "value": ""
+      },
+      "next": {
+        "value": ""
+      }
+    },
+    "run": {
+      "next": {
+        "value": ""
+      }
+    }
+  }
+}

package/builtin/pipelines/while-subflow-preview/workspace.flow.js

@@ -0,0 +1,55 @@
+import { agent, control, display, file, flow, provide, tool, workspace } from "agentflow/flow";
+
+const bodyState = flow.input("state", "json");
+
+const bodyIteration = flow.input("iteration", "text");
+
+const bodyIdempotencyKey = flow.input("idempotencyKey", "text");
+
+const selectIssue = tool.nodejs("选择本轮 Issue", {
+  state: bodyState.value,
+  iteration: bodyIteration.value,
+}, `node -e 'const i=JSON.parse(process.env.AGENTFLOW_INPUTS_JSON||"{}");const s=JSON.parse(i.state||"{}");const issues=["LIKEE-1842 · Android 评论气泡样式","LIKEE-1843 · iOS 评论气泡样式"];process.stdout.write(issues[s.cursor]||"无待处理 Issue")'`);
+
+const advanceIssue = tool.nodejs("推进一个研发动作", {
+  issue: selectIssue.result,
+  idempotencyKey: bodyIdempotencyKey.value,
+}, `node -e 'const i=JSON.parse(process.env.AGENTFLOW_INPUTS_JSON||"{}");process.stdout.write("已模拟推进："+i.issue+"（幂等键 "+String(i.idempotencyKey||"").slice(0,12)+"…）")'`);
+
+const saveState = tool.nodejs("归并下一轮状态", {
+  previousState: bodyState.value,
+  action: advanceIssue.result,
+}, `node -e 'const i=JSON.parse(process.env.AGENTFLOW_INPUTS_JSON||"{}");const s=JSON.parse(i.previousState||"{}");s.cursor=Number(s.cursor||0)+1;s.status="advanced";s.lastAction=i.action;process.stdout.write(JSON.stringify(s))'`);
+
+const validateNextState = control.parseJson("验证下一轮状态", {
+  value: saveState.result,
+});
+
+export const bodyFlow = flow.subflow("执行一轮推进", { state: bodyState, iteration: bodyIteration, idempotencyKey: bodyIdempotencyKey }, flow(selectIssue, advanceIssue, saveState, validateNextState), { state: validateNextState.result, summary: advanceIssue.result });
+
+const conditionState = flow.input("state", "json");
+
+const conditionIteration = flow.input("iteration", "text");
+
+const checkBoundary = tool.nodejs("检查人工边界", {
+  state: conditionState.value,
+  iteration: conditionIteration.value,
+}, `node -e 'const i=JSON.parse(process.env.AGENTFLOW_INPUTS_JSON||"{}");const s=JSON.parse(i.state||"{}");process.stdout.write(Number(s.cursor||0)>=2?"done":"continue")'`);
+
+export const conditionFlow = flow.subflow("是否继续推进", { state: conditionState, iteration: conditionIteration }, flow(checkBoundary), { decision: checkBoundary.result, summary: checkBoundary.result });
+
+export const initialState = provide.json("初始 PRD 状态", {
+  value: `{"prdId":"TAPD-1010475","cursor":0,"status":"ready"}`,
+});
+
+const advanceUntilBoundary = control.while("推进到下一个人工边界 · 设计预览", {
+  state: initialState.value,
+  maxIterations: "20",
+  timeout: "30m",
+}, conditionFlow, bodyFlow);
+
+const result = display.markdown("While 最终结果", {
+  content: advanceUntilBoundary.result,
+});
+
+export const run = flow("运行设计预览", advanceUntilBoundary, result);

package/builtin/pipelines/while-subflow-preview/workspace.layout.json

@@ -0,0 +1,66 @@
+{
+  "version": 1,
+  "nodes": {
+    "advanceIssue": {
+      "x": 1590,
+      "y": 820
+    },
+    "advanceUntilBoundary": {
+      "x": 520,
+      "y": 70,
+      "w": 560,
+      "h": 520
+    },
+    "bodyIdempotencyKey": {
+      "x": 950,
+      "y": 1060
+    },
+    "bodyIteration": {
+      "x": 950,
+      "y": 940
+    },
+    "bodyState": {
+      "x": 950,
+      "y": 820
+    },
+    "checkBoundary": {
+      "x": 430,
+      "y": 820
+    },
+    "conditionIteration": {
+      "x": 60,
+      "y": 940
+    },
+    "conditionState": {
+      "x": 60,
+      "y": 820
+    },
+    "initialState": {
+      "x": 80,
+      "y": 80
+    },
+    "result": {
+      "x": 1180,
+      "y": 80,
+      "w": 520,
+      "h": 360
+    },
+    "run": {
+      "x": 80,
+      "y": 300
+    },
+    "saveState": {
+      "x": 1920,
+      "y": 820
+    },
+    "selectIssue": {
+      "x": 1260,
+      "y": 820
+    },
+    "validateNextState": {
+      "x": 2360,
+      "y": 1372
+    }
+  },
+  "description": "While 双子流程设计预览：Condition 负责决策，Body 负责单轮推进，图本身保持 DAG"
+}

package/builtin/pipelines/while-subflow-preview/workspace.nodes.json

@@ -0,0 +1,49 @@
+{
+  "version": 1,
+  "nodes": {
+    "advanceIssue": {
+      "subflowId": "bodyFlow"
+    },
+    "advanceUntilBoundary": {
+      "conditionSubflowId": "conditionFlow",
+      "bodySubflowId": "bodyFlow"
+    },
+    "bodyIdempotencyKey": {
+      "subflowId": "bodyFlow",
+      "subflowInputName": "idempotencyKey",
+      "subflowInputType": "text"
+    },
+    "bodyIteration": {
+      "subflowId": "bodyFlow",
+      "subflowInputName": "iteration",
+      "subflowInputType": "text"
+    },
+    "bodyState": {
+      "subflowId": "bodyFlow",
+      "subflowInputName": "state",
+      "subflowInputType": "json"
+    },
+    "checkBoundary": {
+      "subflowId": "conditionFlow"
+    },
+    "conditionIteration": {
+      "subflowId": "conditionFlow",
+      "subflowInputName": "iteration",
+      "subflowInputType": "text"
+    },
+    "conditionState": {
+      "subflowId": "conditionFlow",
+      "subflowInputName": "state",
+      "subflowInputType": "json"
+    },
+    "saveState": {
+      "subflowId": "bodyFlow"
+    },
+    "selectIssue": {
+      "subflowId": "bodyFlow"
+    },
+    "validateNextState": {
+      "subflowId": "bodyFlow"
+    }
+  }
+}