@fieldwangai/agentflow 0.1.153 → 0.1.156

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (193) hide show
  1. package/README.md +16 -34
  2. package/README.zh-CN.md +14 -34
  3. package/agents/agentflow-node-executor-code.md +13 -3
  4. package/agents/agentflow-node-executor-planning.md +13 -3
  5. package/agents/agentflow-node-executor-requirement.md +13 -3
  6. package/agents/agentflow-node-executor-test.md +13 -3
  7. package/agents/agentflow-node-executor-ui.md +13 -3
  8. package/agents/agentflow-node-executor.md +13 -3
  9. package/agents/en/agentflow-node-executor.md +13 -3
  10. package/agents/zh/agentflow-node-executor.md +13 -3
  11. package/bin/agentflow.mjs +3 -3
  12. package/bin/lib/admin-builtin-pipelines.mjs +3 -2
  13. package/bin/lib/agent-runners.mjs +0 -929
  14. package/bin/lib/auth.mjs +2 -1
  15. package/bin/lib/catalog-agents.mjs +2 -1
  16. package/bin/lib/catalog-flows.mjs +165 -90
  17. package/bin/lib/composer-agent.mjs +3 -793
  18. package/bin/lib/composer-skill-router.mjs +3 -323
  19. package/bin/lib/exec-buffered.mjs +32 -0
  20. package/bin/lib/flow-dsl/cli.mjs +277 -0
  21. package/bin/lib/flow-dsl/codegen.mjs +358 -0
  22. package/bin/lib/flow-dsl/defs.mjs +103 -0
  23. package/bin/lib/flow-dsl/index.mjs +77 -0
  24. package/bin/lib/flow-dsl/ir.mjs +305 -0
  25. package/bin/lib/flow-dsl/layout.mjs +115 -0
  26. package/bin/lib/flow-dsl/legacy-yaml.mjs +303 -0
  27. package/bin/lib/flow-dsl/lint.mjs +241 -0
  28. package/bin/lib/flow-dsl/packages.mjs +251 -0
  29. package/bin/lib/flow-dsl/parser.mjs +444 -0
  30. package/bin/lib/flow-import.mjs +96 -26
  31. package/bin/lib/flow-write.mjs +48 -12
  32. package/bin/lib/help.mjs +8 -28
  33. package/bin/lib/html-escape.mjs +19 -0
  34. package/bin/lib/http-util.mjs +49 -0
  35. package/bin/lib/legacy-flow-execution.mjs +37 -0
  36. package/bin/lib/locales/en.json +1 -1
  37. package/bin/lib/locales/zh.json +1 -1
  38. package/bin/lib/main.mjs +152 -286
  39. package/bin/lib/marketplace.mjs +206 -61
  40. package/bin/lib/model-config.mjs +10 -0
  41. package/bin/lib/node-package-archive.mjs +240 -0
  42. package/bin/lib/node-package-bootstrap.mjs +72 -0
  43. package/bin/lib/node-package-manifest.mjs +174 -0
  44. package/bin/lib/paths.mjs +42 -19
  45. package/bin/lib/prd-workflow-routes.mjs +2949 -0
  46. package/bin/lib/prd-workflow-server.mjs +4884 -0
  47. package/bin/lib/run-events.mjs +0 -66
  48. package/bin/lib/schedule-config.mjs +4 -4
  49. package/bin/lib/skill-runtime.mjs +35 -0
  50. package/bin/lib/startup-storage-migrations.mjs +274 -0
  51. package/bin/lib/ui-server.mjs +1092 -18123
  52. package/bin/lib/user-env.mjs +16 -0
  53. package/bin/lib/workspace-auto-layout.mjs +234 -0
  54. package/bin/lib/workspace-flow-store.mjs +478 -0
  55. package/bin/lib/workspace-graph-merge.mjs +41 -34
  56. package/bin/lib/workspace-preview.mjs +12 -2
  57. package/bin/lib/workspace-routes.mjs +3088 -0
  58. package/bin/lib/workspace-server.mjs +6199 -0
  59. package/bin/lib/workspace-state.mjs +331 -0
  60. package/bin/lib/workspace.mjs +2 -1
  61. package/builtin/nodes/agent_subAgent.md +1 -0
  62. package/builtin/nodes/control_agent_toBool.md +2 -0
  63. package/builtin/nodes/control_anyOne.md +2 -0
  64. package/builtin/nodes/control_cancelled.md +2 -0
  65. package/builtin/nodes/control_cd_workspace.md +5 -11
  66. package/builtin/nodes/control_delay.md +2 -0
  67. package/builtin/nodes/control_end.md +2 -0
  68. package/builtin/nodes/control_if.md +1 -0
  69. package/builtin/nodes/control_interval_loop.md +2 -0
  70. package/builtin/nodes/control_load_mcp.md +24 -0
  71. package/builtin/nodes/control_load_skills.md +8 -23
  72. package/builtin/nodes/control_start.md +2 -0
  73. package/builtin/nodes/control_toBool.md +2 -0
  74. package/builtin/nodes/control_user_workspace.md +2 -0
  75. package/builtin/nodes/control_wait_until.md +2 -0
  76. package/builtin/nodes/display_ascii.md +1 -0
  77. package/builtin/nodes/display_chart.md +1 -0
  78. package/builtin/nodes/display_html.md +1 -0
  79. package/builtin/nodes/display_image.md +1 -0
  80. package/builtin/nodes/display_markdown.md +1 -0
  81. package/builtin/nodes/display_mermaid.md +1 -0
  82. package/builtin/nodes/display_react_app.md +1 -0
  83. package/builtin/nodes/display_table.md +1 -0
  84. package/builtin/nodes/provide_bool.md +1 -0
  85. package/builtin/nodes/provide_file.md +1 -0
  86. package/builtin/nodes/provide_password.md +1 -0
  87. package/builtin/nodes/provide_str.md +1 -0
  88. package/builtin/nodes/tool_display_share_link.md +1 -0
  89. package/builtin/nodes/tool_get_env.md +2 -0
  90. package/builtin/nodes/tool_git_checkout.md +1 -0
  91. package/builtin/nodes/tool_git_worktree_load.md +1 -0
  92. package/builtin/nodes/tool_git_worktree_unload.md +1 -0
  93. package/builtin/nodes/tool_gitlab_create_mr.md +1 -0
  94. package/builtin/nodes/tool_jenkins_build.md +2 -0
  95. package/builtin/nodes/tool_load_key.md +2 -0
  96. package/builtin/nodes/tool_nodejs.md +17 -19
  97. package/builtin/nodes/tool_print.md +2 -0
  98. package/builtin/nodes/tool_save_key.md +2 -0
  99. package/builtin/nodes/tool_set_run_env.md +1 -0
  100. package/builtin/nodes/tool_user_ask.md +2 -0
  101. package/builtin/nodes/tool_user_check.md +2 -0
  102. package/builtin/nodes/tool_wecom_send_app_markdown.md +1 -0
  103. package/builtin/nodes/tool_wecom_send_group_markdown.md +1 -0
  104. package/builtin/nodes/workspace_one_click_task.md +44 -0
  105. package/builtin/nodes/workspace_run.md +16 -0
  106. package/builtin/nodes/workspace_scheduled_run.md +16 -0
  107. package/builtin/pipelines/module-migrate/scripts/gate.mjs +37 -0
  108. package/builtin/pipelines/module-migrate/scripts/static-check.mjs +82 -0
  109. package/builtin/pipelines/module-migrate/workspace.flow.js +172 -0
  110. package/builtin/pipelines/module-migrate/workspace.layout.json +134 -0
  111. package/builtin/pipelines/new/scripts/lint-flow.mjs +38 -0
  112. package/builtin/pipelines/new/workspace.flow.js +91 -0
  113. package/builtin/pipelines/new/workspace.layout.json +70 -0
  114. package/builtin/web-ui/dist/assets/{WorkflowAssistantThread-B9xslwI0.js → WorkflowAssistantThread-ClNxY2Wu.js} +1 -1
  115. package/builtin/web-ui/dist/assets/index-BJzMYRK3.js +870 -0
  116. package/builtin/web-ui/dist/assets/index-CEXmmwM2.css +1 -0
  117. package/builtin/web-ui/dist/index.html +2 -2
  118. package/package.json +3 -1
  119. package/reference/flow-control-capabilities.md +77 -158
  120. package/reference/flow-layout.md +1 -1
  121. package/reference/flow-prompt-handler-check.md +2 -2
  122. package/skills/agentflow-author-flow/SKILL.md +1 -1
  123. package/skills/agentflow-cli/SKILL.md +139 -24
  124. package/skills/agentflow-cli/agents/openai.yaml +2 -2
  125. package/skills/agentflow-cli/scripts/agentflow-cli.mjs +654 -20
  126. package/skills/agentflow-cli/scripts/agentflow-runtime.mjs +97 -0
  127. package/skills/agentflow-flow-add-instances/SKILL.md +1 -1
  128. package/skills/agentflow-flow-dsl/SKILL.md +206 -0
  129. package/skills/agentflow-flow-dsl/agents/openai.yaml +4 -0
  130. package/skills/agentflow-flow-dsl/references/node-calls.md +39 -0
  131. package/skills/agentflow-flow-edit-node-fields/SKILL.md +1 -1
  132. package/skills/agentflow-flow-recipes/SKILL.md +7 -4
  133. package/skills/agentflow-flow-recipes/references/recipes.md +97 -43
  134. package/skills/agentflow-flow-sync-ui/SKILL.md +1 -1
  135. package/skills/agentflow-node-dsl/SKILL.md +212 -0
  136. package/skills/agentflow-node-dsl/agents/openai.yaml +4 -0
  137. package/skills/agentflow-node-reference/SKILL.md +2 -2
  138. package/skills/agentflow-node-reference/references/builtin-nodes.md +166 -115
  139. package/skills/agentflow-runtime-reference/references/runtime.md +1 -1
  140. package/skills/agentflow-workspace-ascii/SKILL.md +9 -16
  141. package/skills/agentflow-workspace-graph/SKILL.md +62 -48
  142. package/skills/agentflow-workspace-html/SKILL.md +7 -2
  143. package/skills/agentflow-workspace-image/SKILL.md +6 -2
  144. package/skills/agentflow-workspace-markdown/SKILL.md +14 -21
  145. package/skills/agentflow-workspace-mermaid/SKILL.md +8 -16
  146. package/bin/lib/api-runner.mjs +0 -387
  147. package/bin/lib/apply.mjs +0 -903
  148. package/bin/lib/composer-flow-instances.mjs +0 -68
  149. package/bin/lib/composer-flow-skeleton.mjs +0 -334
  150. package/bin/lib/composer-flow-validate.mjs +0 -47
  151. package/bin/lib/composer-model-router.mjs +0 -185
  152. package/bin/lib/composer-node-schema.mjs +0 -303
  153. package/bin/lib/composer-planner.mjs +0 -751
  154. package/bin/lib/composer-script-ops.mjs +0 -233
  155. package/bin/lib/flow-static-preview.mjs +0 -104
  156. package/bin/lib/hub-login.mjs +0 -54
  157. package/bin/lib/hub-publish.mjs +0 -159
  158. package/bin/lib/hub-remote.mjs +0 -189
  159. package/bin/lib/hub.mjs +0 -299
  160. package/bin/lib/jenkins.mjs +0 -380
  161. package/bin/lib/node-execute.mjs +0 -539
  162. package/bin/lib/normalize-node-tool-command.mjs +0 -97
  163. package/bin/lib/runtime-context.mjs +0 -243
  164. package/bin/lib/scheduler.mjs +0 -601
  165. package/bin/lib/ui-print.mjs +0 -94
  166. package/bin/pipeline/build-node-prompt.mjs +0 -271
  167. package/bin/pipeline/check-cache.mjs +0 -191
  168. package/bin/pipeline/check-flow.mjs +0 -543
  169. package/bin/pipeline/collect-nodes.mjs +0 -212
  170. package/bin/pipeline/compute-cache-md5.mjs +0 -177
  171. package/bin/pipeline/ensure-run-dir.mjs +0 -71
  172. package/bin/pipeline/gc.mjs +0 -129
  173. package/bin/pipeline/get-env.mjs +0 -59
  174. package/bin/pipeline/get-resolved-values.mjs +0 -344
  175. package/bin/pipeline/load-key.mjs +0 -62
  176. package/bin/pipeline/parse-flow.mjs +0 -708
  177. package/bin/pipeline/post-process-control-if.mjs +0 -23
  178. package/bin/pipeline/post-process-node.mjs +0 -490
  179. package/bin/pipeline/pre-process-node.mjs +0 -1430
  180. package/bin/pipeline/resolve-inputs.mjs +0 -201
  181. package/bin/pipeline/run-tool-nodejs.mjs +0 -167
  182. package/bin/pipeline/save-key.mjs +0 -93
  183. package/bin/pipeline/snapshot-prior-round.mjs +0 -70
  184. package/bin/pipeline/validate-for-ui.mjs +0 -234
  185. package/bin/pipeline/validate-script-output.mjs +0 -130
  186. package/bin/pipeline/write-result.mjs +0 -182
  187. package/builtin/pipelines/module-migrate/flow.yaml +0 -819
  188. package/builtin/pipelines/new/flow.yaml +0 -545
  189. package/builtin/pipelines/new/scripts/check-flow.mjs +0 -9
  190. package/builtin/pipelines/new/scripts/collect-nodes.mjs +0 -211
  191. package/builtin/web-ui/dist/assets/index-DZ328oSo.css +0 -1
  192. package/builtin/web-ui/dist/assets/index-DmUV7ZCL.js +0 -888
  193. package/skills/agentflow-node-authoring/SKILL.md +0 -57
package/builtin/web-ui/dist/index.html CHANGED
@@ -30,8 +30,8 @@
30
30
  @keyframes af-app-loading-slide { from { transform: translateX(-115%); } to { transform: translateX(250%); } }
31
31
  @media (prefers-reduced-motion: reduce) { .af-app-loading__track span { width: 100%; animation: none; } }
32
32
  </style>
33
- <script type="module" crossorigin src="/assets/index-DmUV7ZCL.js"></script>
34
- <link rel="stylesheet" crossorigin href="/assets/index-DZ328oSo.css">
33
+ <script type="module" crossorigin src="/assets/index-BJzMYRK3.js"></script>
34
+ <link rel="stylesheet" crossorigin href="/assets/index-CEXmmwM2.css">
35
35
  </head>
36
36
  <body>
37
37
  <div id="root">
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fieldwangai/agentflow",
3
- "version": "0.1.153",
3
+ "version": "0.1.156",
4
4
  "description": "Orchestration system for long-running complex agent tasks using Cursor, OpenCode, Claude Code, or Codex as execution backends",
5
5
  "type": "module",
6
6
  "main": "bin/agentflow.mjs",
@@ -54,9 +54,11 @@
54
54
  "dev:web": "cd builtin/web-ui && npm run dev",
55
55
  "dev:website": "cd website && npm run dev",
56
56
  "preview:website": "cd website && npm run preview",
57
+ "version": "npm --prefix builtin/web-ui run build && git add builtin/web-ui/dist",
57
58
  "prepack": "npm run build:web-ui"
58
59
  },
59
60
  "dependencies": {
61
+ "acorn": "^8.18.0",
60
62
  "busboy": "^1.6.0",
61
63
  "chalk": "^5.6.2",
62
64
  "cli-table3": "^0.6.5",
package/reference/flow-control-capabilities.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # AgentFlow 常见流程控制能力
2
2
 
3
- 本文档供 AI 参考：流程中常用的控制节点及其用法、连线方式与典型模式。
3
+ 本文档供 AI 参考：Workspace 图中常用的控制节点及其用法、连线方式与典型模式。
4
4
 
5
5
  **说明**：下文中的 handle（如 input-0、output-1）是**可变的**，由节点类或 instance 的 input/output 列表顺序决定；若槽位顺序有变动，须以实际 definition/instance 的 frontmatter 为准。
6
6
 
@@ -8,14 +8,16 @@
8
8
 
9
9
  ---
10
10
 
11
- ## 1. 入口与出口
11
+ ## 1. 入口
12
12
 
13
- | 节点 | definitionId | 作用 |
14
- |------|----------------|------|
15
- | **Start** | control_start | 流程唯一入口，无 input，只有 output `next`（output-0）。所有边从 start 连出到第一个执行节点。 |
16
- | **End** | control_end | 流程唯一出口，只有 input `prev`（input-0），无 output。所有最终节点连到 end。 |
13
+ | 节点 | definitionId | 作用 |
14
+ |------|--------------|------|
15
+ | **Run** | workspace_run | 手动运行的入口。点 Run 时从它沿控制边向下游展开。 |
16
+ | **Scheduled Run** | workspace_scheduled_run | 定时运行的入口，按 cron 配置触发。 |
17
17
 
18
- **约定**：每个 flow 必须包含且仅包含一个 control_start、一个 control_end。
18
+ 图不需要出口节点——控制链走到尽头即结束。
19
+
20
+ **旧版 `control_start` / `control_end` 已下线**，不要新增。
19
21
 
20
22
  ---
21
23
 
@@ -23,179 +25,111 @@
23
25
 
24
26
  - **control_if**：单节点双分支。根据 **prediction**（bool）：为 true 时沿 **next1**（output-0）继续，为 false 时沿 **next2**（output-1）继续。适用于「二选一」分支。
25
27
 
26
- **典型用法**：上游接一个能输出布尔值的节点（如 **control_toBool**（确定性）或 **control_agent_toBool**（AI 判断）），把布尔槽位连到 If 的 **input-1**（prediction），再根据需要连到不同分支。
28
+ **典型用法**：上游接 **provide_bool**，把它的 bool 输出连到 If 的 **input-1**（prediction），再把两个分支分别连到 output-0 / output-1。
27
29
 
28
30
  **control_if Handle**：
29
- - input: prev → input-0, prediction → input-1
31
+ - input: prev → input-0, prediction → input-1
30
32
  - output: next1 → output-0（条件为真时）, next2 → output-1（条件为假时）
31
33
 
32
34
  ---
33
35
 
34
- ## 3. 转布尔（ToBool）
35
-
36
- ### 3a. control_toBool（本地确定性执行）
37
-
38
- - **definitionId**: control_toBool
39
- - **作用**：**本地代码**将上游 **value** 文本用 parseBool 解析为布尔（true/1/yes/on → true，其余 → false），写入 **prediction**。**不调用 AI agent**。
40
- - **适用场景**：上游输出已是明确的 "true"/"false"、"1"/"0"、"yes"/"no" 等确定性文本。
41
-
42
- **Handle**：
43
- - input: prev → input-0, value → input-1
44
- - output: next → output-0, prediction → output-1
45
-
46
- ### 3b. control_agent_toBool（AI agent 执行）
47
-
48
- - **definitionId**: control_agent_toBool
49
- - **作用**：由 **AI agent** 理解上游 **value** 内容的语义，判断布尔含义后写入 **prediction**。
50
- - **适用场景**：上游输出是自然语言描述、代码分析结果、复杂报告等需要语义理解才能判定真假的内容。
51
-
52
- **Handle**：
53
- - input: prev → input-0, value → input-1
54
- - output: next → output-0, prediction → output-1
36
+ ## 3. 图必须是 DAG（无环）
55
37
 
56
- **共同约定**：写入 **prediction**（output-1）的**文件内容必须仅为 true 或 false**，供下游 control_if 等解析；不得写入长文本或 markdown 报告。
38
+ Workspace 运行计划做拓扑排序，**遇到环直接抛 `Workspace run graph contains a cycle`**，整次运行失败。
57
39
 
58
- ---
59
-
60
- ## 4. 多路汇合（AnyOne）
40
+ 因此：
61
41
 
62
- - **definitionId**: control_anyOne
63
- - **作用**：多个上游分支中**任意一个**就绪（success）时，即从 **next** 继续，常用于「多路并行、任一路完成即进入下一步」的场景。
42
+ - **禁止**从下游节点连边回到上游节点。
43
+ - 「检查 → 修复 → 复检」要**向前展开**成多个节点，而不是回流成环。
44
+ - 需要「反复重试直到达标」时，把循环放进**单个节点内部**——`agent_subAgent` 的 body 里让 agent 自己迭代，或 `tool_nodejs` 的脚本里自己 while 循环。
64
45
 
65
- **Handle**：
66
- - input: prev1 → input-0, prev2 → input-1（可扩展更多输入槽位时按 input-2, input-3… 约定）
67
- - output: next → output-0
46
+ 旧版用于成环的 `control_anyOne` / `control_toBool` / `control_agent_toBool` / `control_interval_loop` 均已下线。
68
47
 
69
48
  ---
70
49
 
71
- ## 5. 全局存储与环境（LoadKey / SaveKey / GetEnv）
72
-
73
- 用于**当前 flow 在一次 run 内的全局信息保存与读取**：按 key 在 run 目录下的 memory 存储中写入或读取文本，供多节点共享状态、跨分支传递结果。**GetEnv** 从系统环境变量与用户目录 `~/.cursor/config.json` 按 key 读取，用于注入 API Key、工作区配置等。
74
-
75
- | 节点 | definitionId | 作用 |
76
- |------|----------------|------|
77
- | **LoadKey** | tool_load_key | 按 **key** 从当前 run 的存储中读取一个值，结果输出到 **result** 槽位，可连到下游节点的 input。 |
78
- | **SaveKey** | tool_save_key | 按 **key** 将 **value** 写入当前 run 的存储；value 可为字面文本，或 run 内相对路径（如 `output/node_xxx_result.md`），脚本会读文件内容后写入。 |
79
- | **GetEnv** | tool_get_env | 按 **key** 从系统环境变量与 `~/.cursor/config.json` 读取一个值（优先环境变量）；key 支持点号路径如 `openai.apiKey` 读取 config 嵌套字段；结果输出到 **value** 槽位。 |
50
+ ## 4. 展示结果（Display）
80
51
 
81
- **Handle**：
52
+ 把产出槽连到 `display_*` 节点的 `content` 输入即可在画布上渲染：
82
53
 
83
- - **LoadKey**
84
- - input: prev → input-0, key → input-1
85
- - output: next → output-0, result → output-1
86
- - **SaveKey**
87
- - input: prev → input-0, key → input-1, value → input-2
88
- - output: next → output-0
89
- - **GetEnv**
90
- - input: key → input-0
91
- - output: value → output-0
54
+ | definitionId | 内容形态 |
55
+ |--------------|----------|
56
+ | display_markdown | Markdown 正文 |
57
+ | display_html | 可直接放进 iframe 的 HTML |
58
+ | display_react_app | React 工程 JSON（title / entry / files） |
59
+ | display_table | `{"columns":[...],"rows":[...]}` |
60
+ | display_chart | ChartSpec JSON |
61
+ | display_mermaid | Mermaid 图表代码 |
62
+ | display_ascii | 纯文本 / ASCII 图 |
63
+ | display_image | 图片地址、data URL 或 base64 |
92
64
 
93
- **典型用法**：
94
-
95
- 1. **保存后再读**：某节点产出结果 → SaveKey（key 固定如 `flowName`，value 接上游 output）→ 下游分支中 LoadKey（同一 key）→ result 连到后续 agent/tool。
96
- 2. **跨分支共享**：并行分支中一路用 SaveKey 写入（如「选中的方案名」），汇合后或另一分支用 LoadKey 读取，保证全 flow 看到同一份全局信息。
97
- 3. **占位符**：instance 中 key/value 可写占位符（如 `${output/node_plan_result.md}`），由 apply 在 resolvedInputs 中解析后传入脚本。
98
- 4. **环境/配置注入**：GetEnv（key 如 `OPENAI_API_KEY` 或 `openai.apiKey`）→ value 连到下游 agent 的 input，用于从环境或 `~/.cursor/config.json` 读取密钥或配置，避免写死在 flow 中。
99
-
100
- 存储由 apply 通过 `agentflow apply -ai run-tool-nodejs` 调用 load-key/save-key 实现；GetEnv 由 `agentflow apply -ai get-env <workspaceRoot> <flowName> <uuid> <instanceId> <execId> <key>` 直接执行，run 上下文通过命令行参数传入，不再经 run-tool-nodejs。LoadKey/SaveKey 数据仅在**当前 run**（同一 uuid 的 `~/agentflow/runBuild/<FlowName>/<uuid>/`）内有效；GetEnv 读取的是系统环境与用户级 `~/.cursor/config.json`，不随 run 隔离。
65
+ **旧版 `tool_print` 已下线**，改用 `display_markdown`。
101
66
 
102
67
  ---
103
68
 
104
- ## 6. 工具节点与 Agent 节点选型
69
+ ## 5. 工具节点与 Agent 节点选型
105
70
 
106
71
  **核心原则：能用工具节点确定性执行的，不要用 agent_subAgent。**
107
72
 
108
73
  | 场景 | 推荐节点 | 原因 |
109
74
  |------|----------|------|
110
- | 执行已知命令/脚本（打印、文件操作、数据处理等） | **tool_nodejs** + `script` 字段 | 直接执行，零 LLM 调用，毫秒级完成 |
111
- | 向用户输出醒目信息 | **tool_print** | 专用输出节点 |
75
+ | 执行已知命令/脚本（文件操作、数据处理等） | **tool_nodejs** + `script` 字段 | 直接执行，零 LLM 调用，毫秒级完成 |
76
+ | 向用户展示结果 | **display_\*** | 专用展示节点 |
112
77
  | 需要 AI 理解上下文、做判断、生成内容 | **agent_subAgent** | 需要 LLM 推理能力 |
113
78
 
114
- ### 6.1 tool_nodejs 直接执行模式（推荐）
79
+ ### 5.1 tool_nodejs 直接执行模式（推荐）
115
80
 
116
- 在 instance 中设置 `script` 字段，流水线**跳过 AI 直接执行命令**：
81
+ 在 instance 中设置 `script` 字段，运行时**跳过 AI 直接 spawn 命令**：
117
82
 
118
83
  ```yaml
119
- print_hello:
84
+ write_summary:
120
85
  definitionId: tool_nodejs
121
- label: 打印Hello
122
- script: node -e "console.log(${value})"
86
+ label: 写摘要
87
+ script: node ${flowDir}/scripts/write-summary.mjs --input ${value} --output ${summary}
123
88
  input:
124
- - type: 节点
125
- name: prev
126
- value: ''
127
- - type: 文本
128
- name: value
129
- value: ''
89
+ - { type: node, name: prev, value: '' }
90
+ - { type: text, name: value, value: '' }
130
91
  output:
131
- - type: 节点
132
- name: next
133
- value: ''
134
- - type: 文本
135
- name: result
136
- value: ''
92
+ - { type: node, name: next, value: '' }
93
+ - { type: text, name: result, value: '' }
94
+ - { type: file, name: summary, value: '' }
137
95
  ```
138
96
 
139
- - `script` 支持 `${}` 占位符（workspaceRoot、flowName、runDir 及所有 input 槽位），值自动 shell-quote。
140
- - 适用于：打印文本、运行已有脚本、文件复制/移动、数据格式转换等**确定性操作**。
141
- - input 可按需添加额外的文本/文件槽位（如上例的 `value`），供 `script` 中 `${value}` 引用。
97
+ - `script` / `scriptRef` 支持 `${}` 占位符：`workspaceRoot` / `pipelineWorkspace` / `flowDir`（三者都解析为当前 scoped workspace 根）、`cwd`、`nodeRunDir`、`nodeTmpDir`、`outputsDir`、`scriptRef`，以及**所有 input / output 槽位名**。值自动 shell-quote，不要自己加引号。
98
+ - 适用于：运行已有脚本、文件复制/移动、数据格式转换等**确定性操作**。
142
99
  - **成败判定**：以脚本进程 **exit code** 为准（0 = success，非 0 = failed）。
143
- - **stdout → result**：脚本 stdout 直接作为 result 槽位内容，纯文本即可（如 `console.log("hello")`）。
144
- - **JSON 兼容（可选）**：stdout 为 `{"err_code":0,"message":{"result":"..."}}` 时，err_code 覆盖 exit code 语义——仅在需要与 exit code 不同的成败语义时使用。
100
+ - **stdout → result**：脚本 stdout 直接作为 result 槽位内容，纯文本即可。**不要用 JSON 封装 stdout。**
145
101
 
146
- ### 6.2 判断标准
102
+ ### 5.2 判断标准
147
103
 
148
104
  问自己：**"这个步骤的行为是否完全由输入决定，不需要 AI 推理？"**
149
105
 
150
- - **是** → 用 `tool_nodejs` + `script`，或 `tool_print`
151
- - 例：打印一段文字、执行 `agentflow apply -ai validate-flow`、跑一个已有的 `.mjs` 脚本
106
+ - **是** → 用 `tool_nodejs` + `script`
107
+ - 例：跑一个已有的 `.mjs` 脚本、格式化 JSON、复制产物
152
108
  - **否** → 用 `agent_subAgent`
153
109
  - 例：根据需求撰写文档、分析代码并提出修改方案、理解上下文后做决策
154
110
 
155
- ### 6.3 `script` 与 `body` 的职责（必须遵守）
111
+ ### 5.3 `script` 与 `body` 的职责（必须遵守）
156
112
 
157
113
  | 字段 | 职责 | 有 `script` 时 | 无 `script` 时 |
158
114
  |------|------|---------------|---------------|
159
- | `script` | 实际执行的 shell/node 命令 | 流水线直接 spawn 执行 | — |
160
- | `body` | 纯文档说明（供人类阅读） | **完全忽略**，不参与执行 | 作为 AI 指令兜底（AI 执行模式） |
115
+ | `script` | 实际执行的 shell/node 命令 | 运行时直接 spawn 执行 | — |
116
+ | `body` | 纯文档说明（供人类阅读） | **完全忽略**，不参与执行 | 节点无法执行，必须改用 agent_subAgent |
161
117
 
162
118
  **约束规则**：
163
- 1. `tool_nodejs` **必须写 `script` 字段**，内容为完整可执行的命令
164
- 2. `script` 中的 `${}` 占位符自动 shell-quote，引用 input/output 槽位或系统变量
119
+ 1. `tool_nodejs` **必须写 `script` 或 `scriptRef`**，内容为完整可执行的命令
120
+ 2. `script` 中的 `${}` 占位符自动 shell-quote，引用 input/output 槽位或运行时常量
165
121
  3. **`script` 必须引用所有非 node 类型的 input 和 output 引脚**（validate-flow 硬性校验）：
166
122
  - input 引脚 `${slotName}` → 解析为上游数据值或文件路径
167
123
  - output 引脚 `${slotName}` → 解析为 output 文件的绝对路径，脚本应 `fs.writeFileSync(path, value)` 直接写入
168
- - **禁止使用 JSON stdout 封装**（`{"err_code":0,"message":{...}}`），用 exit code 0/非 0 决定成败
124
+ - **禁止使用 JSON stdout 封装**，用 exit code 0/非 0 决定成败
169
125
  4. `body` 可选，仅用于文档说明，**禁止写期望被执行的逻辑**
170
126
  5. 如果无法写出完整可执行的 `script`（需要 AI 理解/判断），**必须改用 `agent_subAgent`**
171
127
  6. `script` 支持多行（YAML `|` 语法）和管道组合
128
+ 7. **`scripts/` 下的脚本必须写成 `${flowDir}/scripts/xxx.mjs`**，不要硬编码 workspace 路径
172
129
 
173
- **复杂脚本示例（API 调用 + JSON 处理）**：
174
-
130
+ **错误示范**（校验将报错）：
175
131
  ```yaml
176
- fetch_user_list:
177
- definitionId: tool_nodejs
178
- label: 获取用户列表
179
- script: |
180
- curl -s -H "Authorization: Bearer ${token}" "${apiUrl}/users" | node -e "
181
- let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>{
182
- const res=JSON.parse(d);
183
- console.log(JSON.stringify(res.data.map(u=>({id:u.id,name:u.name}))));
184
- });"
185
- body: |
186
- 调用 API 获取用户列表并提取 id 和 name
187
- input:
188
- - { type: 节点, name: prev, value: '' }
189
- - { type: 文本, name: apiUrl, value: '' }
190
- - { type: 文本, name: token, value: '' }
191
- output:
192
- - { type: 节点, name: next, value: '' }
193
- - { type: 文本, name: result, value: '' }
194
- ```
195
-
196
- **错误示范**（校验将报 warning）：
197
- ```yaml
198
- # ❌ tool_nodejs 无 script，body 写自然语言 → 节点无法正确执行
132
+ # ❌ tool_nodejs 无 script，body 写自然语言 → 节点无法执行
199
133
  bad_example:
200
134
  definitionId: tool_nodejs
201
135
  label: 获取数据
@@ -203,16 +137,16 @@ bad_example:
203
137
  调用 API 获取数据，解析 JSON，提取关键字段保存到文件
204
138
  ```
205
139
 
206
- ### 6.4 常见误用
140
+ ### 5.4 常见误用
207
141
 
208
142
  | 用户需求 | 错误做法 | 正确做法 |
209
143
  |----------|----------|----------|
210
- | 打印一段文字 | agent_subAgent + body 描述打印任务 | tool_nodejs + `script: node -e "console.log(${value})"` |
211
- | 执行已有脚本 | agent_subAgent + body 要求运行脚本 | tool_nodejs + `script: node scripts/xxx.mjs` |
212
- | 读取环境变量 | agent_subAgent + body 要求读环境变量 | tool_get_env（专用节点） |
144
+ | 展示一段结果 | agent_subAgent + body 描述展示任务 | 产出槽连到 `display_markdown.content` |
145
+ | 执行已有脚本 | agent_subAgent + body 要求运行脚本 | tool_nodejs + `script: node ${flowDir}/scripts/xxx.mjs` |
146
+ | 注入密钥 | 写死在 flow 里 | `tool_set_run_env` 或运行时环境变量 |
213
147
  | 复杂 AI 推理/生成 | tool_nodejs + body 写自然语言 | agent_subAgent（需 LLM 能力时必须用 agent） |
214
148
 
215
- ### 6.5 节点单一职责（必须遵守）
149
+ ### 5.5 节点单一职责（必须遵守）
216
150
 
217
151
  **每个节点只做一件事，工作内容保持专注和专一。**
218
152
 
@@ -233,42 +167,27 @@ bad_example:
233
167
 
234
168
  ---
235
169
 
236
- ## 7. 常见流程模式简述
237
-
238
- 1. **线性链**：Start → A → B → … → End
239
- 2. **条件分支**：
240
- - **单节点 If**：… → ToBool → **control_if** → next1 连分支A、next2 连分支B（true 走 output-0，false 走 output-1）。
241
- 3. **多路任一**：分支1、分支2 均连到 AnyOne（prev1/prev2），AnyOne 的 next 再连到后续或 End。
242
- 4. **用户确认**：在需要暂停处插入 **tool_user_check**，用户确认后再继续。
243
- 5. **全局存储**：用 **SaveKey** 写入、**LoadKey** 读取当前 flow 的全局信息（见上节）。
244
- 6. **检查 → 修改 → 检查 → 修改**：见下节。
245
-
246
- ---
247
-
248
- ### 8 入环 → 检查 → 修复 → 检查 → 修复 → 检查 → 出环
249
-
250
- 该流程可概括为：**入环 → 检查 → 修复 → 检查 → 修复 → … → 检查通过 → 出环**。参考 **builtin/pipelines/module-migrate** 的连线方式。
251
-
252
- - **入环**：用 **control_anyOne** 汇合两条路——「首次进入」与「上一轮修复完成后再检查」。prev1 / prev2 任一路就绪即从 next 继续，进入**检查**。
253
- - **检查**：执行检查节点（可并行、可汇总），结果经 **control_toBool**（确定性）或 **control_agent_toBool**（AI 判断）转为布尔，再接到 **control_if**。
254
- - **分支**：**control_if** 的 next1（true，通过）→ 出环到后续或 End；next2（false，未通过）→ 进入**修复**。
255
- - **修复**：修复节点消费检查结果，修改后通过边回到「检查」上游或回到 **AnyOne** 的 prev2，形成环；可再套一层 ToBool + If 判断「是否修完」，未修完再修复、修完再回检查。
256
- - **出环**：当 **control_if** 为 true 时，从 next1 连到环外节点，不再回到 AnyOne。
170
+ ## 6. 常见流程模式
257
171
 
258
- 要点：**AnyOne** 做入环/复入环汇合；**ToBool + If** 做通过/未通过二选一；未通过 → 修复 → 回到检查或 AnyOne（成环）；通过 → 连到环外即出环。
172
+ 1. **线性链**：Run → A → B → … → display
173
+ 2. **条件分支**：… → provide_bool → **control_if** → next1 连分支A、next2 连分支B（true 走 output-0，false 走 output-1）
174
+ 3. **并行**：同一个 output 扇出到多个下游节点，无依赖的分支会并行执行，各自往下走
175
+ 4. **检查 → 修复 → 复检**：向前排成 检查节点 → 修复节点 → 复检节点 → control_if（通过走后续，不通过走汇报节点）。**不要连回上游**
176
+ 5. **批量任务**：拆解节点产出 `- [ ]` 清单 → 执行节点在内部逐项推进 → control_if 按完成情况分支
259
177
 
260
178
  ---
261
179
 
262
- ## 9. Edge 与 Handle 注意点
180
+ ## 7. Edge 与 Handle 注意点
263
181
 
264
- - **Fan-out 允许，Fan-in 禁止**：一个 output handle 可连多个 input（扇出），但**一个 input handle 只允许一条入边**（禁止扇入）。同一 `target + targetHandle` 不得出现在多条 edge 中——运行时 `resolve-inputs` 仅取 `find()` 首条匹配，其余静默丢失。若需替换连线，先删旧边再加新边。
265
- - 条件/分支节点有多输入时，必须在 edge 上写清 **targetHandle**（如 prediction 用 input-1）。
266
- - 从 ToBool 的 prediction 连到 If（control_if）时：sourceHandle 用 **output-1**，targetHandle 用 **input-1**。
182
+ - **Fan-out 允许，Fan-in 禁止**：一个 output handle 可连多个 input（扇出），但**一个 input handle 只允许一条入边**（禁止扇入）。同一 `target + targetHandle` 不得出现在多条 edge 中——运行时仅取首条匹配，其余静默丢失。若需替换连线，先删旧边再加新边。
183
+ - **禁止回流边**：任何从下游连回上游的边都会让运行计划判定成环，整次运行失败。
184
+ - 条件/分支节点有多输入时，必须在 edge 上写清 **targetHandle**（如 prediction 用 input-1）。
185
+ - 从 `provide_bool` 的 bool 输出连到 `control_if` 时：targetHandle 用 **input-1**。
267
186
  - 多输出节点连到不同下游时，用不同 **sourceHandle**（output-0, output-1, …）区分槽位。
268
- - **control_if** 必须写清：从 output-0 连到「条件为真」的后继、从 output-1 连到「条件为假」的后继，否则 get-ready-nodes 无法正确解锁分支。
187
+ - **control_if** 必须写清：从 output-0 连到「条件为真」的后继、从 output-1 连到「条件为假」的后继。
269
188
 
270
189
  ---
271
190
 
272
- ## 10. 图与 USER_PROMPT 的读写一致性
191
+ ## 8. 图与 USER_PROMPT 的读写一致性
273
192
 
274
193
  ${USER_PROMPT} 中描述的「读取」「写入」应与图中的 **handler 节点**（input/output 通过 edge 连接的节点）对应：描述的每项「读」应有节点的 input 入边，每项「写」应有节点的 output 出边。详见 [flow-prompt-handler-check.md](./flow-prompt-handler-check.md)。
package/reference/flow-layout.md CHANGED
@@ -78,7 +78,7 @@ ui:
78
78
 
79
79
  ## 5. 参考示例
80
80
 
81
- - **builtin/pipelines/new/flow.yaml**：主链从左到右（start 负 x → control_end 大 x），provide/collect 等偏左，检查/修复分支在 y 上有区分。
81
+ - 主链从左到右（入口 `workspace_run` 在最左，x 依次递增），provide/collect 等数据源偏左，分支路径在 y 上错开。
82
82
  - **builtin/pipelines/module-migrate/flow.yaml**：主链沿 x 递增；provide/SaveKey 在左侧（x≈50～240）；静态环与编译环在 y 上分层（如 agent_fix_todo、control_if_fixed 等 y≈460～470，与主链 y≈100～280 分开），回流不压在主链一条线上。
83
83
 
84
84
  生成或手改 `ui.nodePositions` 时，可先按「主链 x 递增 + 分支/环 y 错开」排一版，再微调间距与对齐。
package/reference/flow-prompt-handler-check.md CHANGED
@@ -6,7 +6,7 @@
6
6
 
7
7
  ## 约定
8
8
 
9
- - **USER_PROMPT**：用户或上游在流程中注入的「需求描述」或「本节点说明」，常出现在 provide_str / provide_file、control_start 等节点的正文中，或作为流程级需求。
10
- - **Handler 节点**：在 flow 中通过 **input/output 槽位** 与其它节点用 **edge** 连接、参与数据流的节点。不含 provide_*、control_start、control_end 等「仅作为源/汇」的节点时，通常指会「读入」或「写出」数据的 agent/tool/control 节点。
9
+ - **USER_PROMPT**：用户或上游在流程中注入的「需求描述」或「本节点说明」，常出现在 provide_str / provide_file 等节点的正文中，或作为流程级需求。
10
+ - **Handler 节点**：在图中通过 **input/output 槽位** 与其它节点用 **edge** 连接、参与数据流的节点。不含 provide_*、workspace_run 等「仅作为源」的节点时，通常指会「读入」或「写出」数据的 agent/tool/control 节点。
11
11
  - **读取**：某节点**消费**某数据 → 对应其 **input** 槽位上有 **入边**（target 为该节点，targetHandle 为该 input）。
12
12
  - **写入**：某节点**产出**某数据 → 对应其 **output** 槽位上有 **出边**（source 为该节点，sourceHandle 为该 output）。
package/skills/agentflow-author-flow/SKILL.md CHANGED
@@ -9,7 +9,7 @@ description: Legacy Pipeline authoring is retired. Redirect new AgentFlow creati
9
9
 
10
10
  新任务统一使用：
11
11
 
12
- - `agentflow-workspace-graph`：创建或修改 `workspace.graph.json`
12
+ - `agentflow-workspace-graph`：创建或修改 `workspace.flow.js`
13
13
  - `agentflow-cli workspace-preview`：上传到服务器临时 Workspace，打开所见即所得画布
14
14
  - Workspace 页面中的 `Run` / `Scheduled Run`：执行 Workspace 图
15
15