@fieldwangai/agentflow 0.1.149 → 0.1.153
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.
- package/README.md +5 -0
- package/bin/lib/catalog-flows.mjs +4 -0
- package/bin/lib/help.mjs +2 -2
- package/bin/lib/legacy-flow-execution.mjs +6 -0
- package/bin/lib/main.mjs +4 -0
- package/bin/lib/ui-server.mjs +128 -0
- package/bin/lib/workspace-preview.mjs +74 -0
- package/builtin/web-ui/dist/assets/{WorkflowAssistantThread-DPbR2UaN.js → WorkflowAssistantThread-B9xslwI0.js} +1 -1
- package/builtin/web-ui/dist/assets/{index-BSCpd5la.js → index-DmUV7ZCL.js} +72 -73
- package/builtin/web-ui/dist/index.html +1 -1
- package/package.json +1 -1
- package/skills/agentflow-author-flow/SKILL.md +8 -47
- package/skills/agentflow-cli/SKILL.md +23 -5
- package/skills/agentflow-cli/scripts/agentflow-cli.mjs +16 -0
- package/skills/agentflow-flow-add-instances/SKILL.md +7 -248
- package/skills/agentflow-flow-edit-node-fields/SKILL.md +4 -73
- package/skills/agentflow-flow-recipes/SKILL.md +4 -18
- package/skills/agentflow-flow-sync-ui/SKILL.md +3 -54
- package/skills/agentflow-node-reference/SKILL.md +4 -3
- package/skills/agentflow-placeholder-reference/SKILL.md +2 -2
- package/skills/agentflow-runtime-reference/SKILL.md +2 -2
- package/skills/agentflow-workspace-graph/SKILL.md +3 -3
|
@@ -30,7 +30,7 @@
|
|
|
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-
|
|
33
|
+
<script type="module" crossorigin src="/assets/index-DmUV7ZCL.js"></script>
|
|
34
34
|
<link rel="stylesheet" crossorigin href="/assets/index-DZ328oSo.css">
|
|
35
35
|
</head>
|
|
36
36
|
<body>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fieldwangai/agentflow",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.153",
|
|
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",
|
|
@@ -1,55 +1,16 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agentflow-author-flow
|
|
3
|
-
description:
|
|
3
|
+
description: Legacy Pipeline authoring is retired. Redirect new AgentFlow creation and editing requests to the Workspace Graph skill and server-side Workspace preview.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
#
|
|
6
|
+
# Legacy Pipeline Authoring（已下线）
|
|
7
7
|
|
|
8
|
-
|
|
9
|
-
create, migrate, archive, or clean up product **Workflows**. A Workflow is the
|
|
10
|
-
TAPD-backed requirement entity addressed by `tapd:<id>` and is handled by
|
|
11
|
-
`agentflow-workflow-report`/`prd-flow` instead. A similar title or flow ID is
|
|
12
|
-
not evidence that the two resources are the same.
|
|
8
|
+
旧的 Flow/Pipeline (`flow.yaml` + `control_start/control_end`) 执行功能已经下线。此 skill 不再创建、发布或执行新的 Pipeline。
|
|
13
9
|
|
|
14
|
-
|
|
10
|
+
新任务统一使用：
|
|
15
11
|
|
|
16
|
-
|
|
12
|
+
- `agentflow-workspace-graph`：创建或修改 `workspace.graph.json`
|
|
13
|
+
- `agentflow-cli workspace-preview`：上传到服务器临时 Workspace，打开所见即所得画布
|
|
14
|
+
- Workspace 页面中的 `Run` / `Scheduled Run`：执行 Workspace 图
|
|
17
15
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
- [Builtin node schemas](../agentflow-node-reference/references/builtin-nodes.md)
|
|
21
|
-
- [Control capabilities](../../reference/flow-control-capabilities.md)
|
|
22
|
-
- [Flow layout](../../reference/flow-layout.md)
|
|
23
|
-
|
|
24
|
-
Read [prompt and handler checks](../../reference/flow-prompt-handler-check.md) when the Flow contains agent nodes. Read [standard recipes](../agentflow-flow-recipes/references/recipes.md) when a recipe matches the request.
|
|
25
|
-
|
|
26
|
-
## Workflow
|
|
27
|
-
|
|
28
|
-
1. Confirm that the user wants an executable Flow/Pipeline, rather than a TAPD Workflow status/record. Convert the request into a short node plan. Ask only for a business choice that materially changes behavior; do not ask for YAML details.
|
|
29
|
-
2. Choose a stable lowercase flow ID using letters, digits, hyphens, or underscores.
|
|
30
|
-
3. Create the draft at `.workspace/agentflow/pipelines/<flow-id>/flow.yaml`. Start from the packaged `builtin/pipelines/new/flow.yaml` when available. Preserve any unrelated workspace files.
|
|
31
|
-
4. Build nodes from authoritative definitions. Never invent `definitionId`, slot order, slot type, handle index, or control semantics. Give every instance a unique position and keep the main path left-to-right.
|
|
32
|
-
5. Validate the draft with `agentflow validate <flow-id> --json`. In this repository, use `node bin/agentflow.mjs validate <flow-id> --json`. Fix all errors before continuing; surface warnings that affect behavior.
|
|
33
|
-
6. Generate and open the static preview with `agentflow flow preview <path-to-flow.yaml>`. In this repository, use `node bin/agentflow.mjs flow preview <path-to-flow.yaml>`. This command must exit after opening the generated `file://` HTML; do not start `agentflow ui` or another server.
|
|
34
|
-
7. Report the draft path and a compact node/edge summary, then wait for the user's visual confirmation. Do not write to the AgentFlow platform before confirmation unless the user explicitly requested direct publish without review.
|
|
35
|
-
8. Ask for `personal`, `workspace`, or `team` only if the user has not already chosen the destination. `team` means a workspace Flow shared as editor with the current account's active team.
|
|
36
|
-
9. Publish through the sibling `agentflow-cli` skill. Publishing a Flow does not publish or update a Workflow:
|
|
37
|
-
|
|
38
|
-
```bash
|
|
39
|
-
node ../agentflow-cli/scripts/agentflow-cli.mjs publish-flow \
|
|
40
|
-
--flow-id <flow-id> \
|
|
41
|
-
--file <path-to-flow.yaml> \
|
|
42
|
-
--target-space <personal|workspace|team>
|
|
43
|
-
```
|
|
44
|
-
|
|
45
|
-
Resolve the script relative to this `SKILL.md`. Never expose the token.
|
|
46
|
-
10. If the server reports that the Flow already exists, stop and explain the conflict. Use `--replace` only after the user explicitly confirms updating that exact Flow and destination. The CLI reads the current revision before replacement.
|
|
47
|
-
11. Verify the published graph with `get-graph --flow-id <flow-id> --flow-source <user|workspace>` and report the platform Flow ID, scope, and result.
|
|
48
|
-
|
|
49
|
-
## Safety rules
|
|
50
|
-
|
|
51
|
-
- Treat local generation and preview as reversible; treat platform publish and replacement as external writes.
|
|
52
|
-
- Never silently convert a personal Flow into a shared Flow.
|
|
53
|
-
- Never create a temporary test Flow on the production platform merely to validate tooling. Use an isolated local AgentFlow server or mock API for integration tests.
|
|
54
|
-
- Do not run the Flow unless the user asks to execute it; publishing is not execution.
|
|
55
|
-
- Keep a failed draft on disk so it can be inspected and repaired.
|
|
16
|
+
历史 `flow.yaml` 仅用于读取、迁移和审计，不得作为新功能的实现目标。不要调用 `agentflow apply`、`/api/flow/run` 或创建 `control_start/control_end`。
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agentflow-cli
|
|
3
|
-
description: Direct AgentFlow
|
|
3
|
+
description: Direct AgentFlow Workspace operation through a bundled token-backed CLI, without MCP. Use when Codex needs to upload temporary Workspace previews, run or inspect Workspace graphs, read graphs and display outputs through AgentFlow HTTP APIs using AGENTFLOW_TOKEN from env or .env. Default AgentFlow base URL is http://ai.mengma.bigo.inner/.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# AgentFlow CLI
|
|
@@ -9,9 +9,11 @@ description: Direct AgentFlow platform operation through a bundled token-backed
|
|
|
9
9
|
|
|
10
10
|
AgentFlow has two different resource families:
|
|
11
11
|
|
|
12
|
-
- **Flow/Pipeline**:
|
|
13
|
-
|
|
14
|
-
|
|
12
|
+
- **Flow/Pipeline**: historical `flow.yaml` resources. Start/End execution and
|
|
13
|
+
new Pipeline authoring are retired; only read/migration operations remain.
|
|
14
|
+
- **Workspace**: the active node graph backed by `workspace.graph.json`.
|
|
15
|
+
`workspace-preview`, `get-graph`, `run`, and display-output commands target
|
|
16
|
+
this family.
|
|
15
17
|
- **Workflow**: a TAPD-derived product/requirement record addressed as
|
|
16
18
|
`tapd:<id>`. It is not a Flow/Pipeline and must be read or changed through
|
|
17
19
|
the `workflow-*` commands and the `agentflow-workflow-report` protocol.
|
|
@@ -119,12 +121,28 @@ Read one flow graph:
|
|
|
119
121
|
node skills/agentflow-cli/scripts/agentflow-cli.mjs get-graph --flow-id TestNodes --flow-source user
|
|
120
122
|
```
|
|
121
123
|
|
|
122
|
-
|
|
124
|
+
Upload a Workspace graph to a server-side temporary preview project (the
|
|
125
|
+
server returns a Workspace URL and cleans the project after its TTL):
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
node skills/agentflow-cli/scripts/agentflow-cli.mjs workspace-preview \
|
|
129
|
+
--file .workspace/agentflow/pipelines/<flow-id>/workspace.graph.json \
|
|
130
|
+
--ttl-seconds 7200
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
This is for visual review only. It does not publish a formal Flow/Pipeline or
|
|
134
|
+
create schedules. The returned temporary project is hidden from the normal
|
|
135
|
+
Flow list and must not be treated as a durable source of truth.
|
|
136
|
+
|
|
137
|
+
Run a Workspace graph:
|
|
123
138
|
|
|
124
139
|
```bash
|
|
125
140
|
node skills/agentflow-cli/scripts/agentflow-cli.mjs run --flow-id TestNodes --flow-source user
|
|
126
141
|
```
|
|
127
142
|
|
|
143
|
+
The legacy `agentflow apply`, `/api/flow/run`, and Start/End Pipeline execution
|
|
144
|
+
path are retired. Do not use them for new work.
|
|
145
|
+
|
|
128
146
|
Run a specific run node with inputs:
|
|
129
147
|
|
|
130
148
|
```bash
|
|
@@ -35,6 +35,7 @@ Commands:
|
|
|
35
35
|
list-flows
|
|
36
36
|
publish-flow --flow-id <id> --file <flow.yaml> [--target-space personal|workspace|team] [--replace]
|
|
37
37
|
get-graph --flow-id <id> [--flow-source user]
|
|
38
|
+
workspace-preview --file <workspace.graph.json> [--preview-id <id>] [--ttl-seconds <n>]
|
|
38
39
|
run --flow-id <id> [--flow-source user] [--run-node-id <id>] [--input k=v]
|
|
39
40
|
status --flow-id <id> [--flow-source user]
|
|
40
41
|
list-run-by-workspace | list-runs-by-workspace --workspace <flowId> [--limit 20]
|
|
@@ -438,6 +439,21 @@ async function main() {
|
|
|
438
439
|
return;
|
|
439
440
|
}
|
|
440
441
|
|
|
442
|
+
if (command === "workspace-preview" || command === "preview-workspace") {
|
|
443
|
+
const graph = readJsonFile(option(args, "file"));
|
|
444
|
+
const result = await httpJson(args, "/api/workspace/preview", {
|
|
445
|
+
method: "POST",
|
|
446
|
+
body: {
|
|
447
|
+
graph,
|
|
448
|
+
previewId: option(args, "preview-id") || "",
|
|
449
|
+
title: option(args, "title") || "Workspace Preview",
|
|
450
|
+
ttlSeconds: option(args, "ttl-seconds") ? Number(option(args, "ttl-seconds")) : undefined,
|
|
451
|
+
},
|
|
452
|
+
});
|
|
453
|
+
printJson(result);
|
|
454
|
+
return;
|
|
455
|
+
}
|
|
456
|
+
|
|
441
457
|
if (command === "run") {
|
|
442
458
|
const flowId = requireFlowId(args);
|
|
443
459
|
const flowSource = option(args, "flow-source") || "user";
|
|
@@ -1,257 +1,16 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agentflow-flow-add-instances
|
|
3
|
-
description:
|
|
4
|
-
向 AgentFlow 的 flow.yaml 新增实例：说明 instances/edges/ui 的 YAML 结构、
|
|
5
|
-
从内置定义拷贝 instance、设计连接点与内容；新增节点的 ui.nodePositions
|
|
6
|
-
默认放在画布视觉中心附近。不用于仅改已有节点文案或占位值。
|
|
3
|
+
description: Legacy Pipeline node authoring is retired. Redirect requests to add nodes to the Workspace Graph skill.
|
|
7
4
|
---
|
|
8
5
|
|
|
9
|
-
#
|
|
6
|
+
# Legacy Flow Node Authoring（已下线）
|
|
10
7
|
|
|
11
|
-
|
|
8
|
+
此 skill 原用于向 `flow.yaml` 添加实例，但旧 Pipeline 的 `Start/End` 执行模式已经下线，不再新增或编辑正式 `flow.yaml`。
|
|
12
9
|
|
|
13
|
-
|
|
10
|
+
用户要在画布中加节点时，请改用 `agentflow-workspace-graph`，编辑：
|
|
14
11
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
- `reference/flow-control-capabilities.md` — handle、边、控制节点语义
|
|
18
|
-
- `reference/flow-layout.md` — 整体布局原则（本技能对「新增」默认用**中心落点**，再按需微调）
|
|
19
|
-
- `reference/flow-prompt-handler-check.md` — 增边后 USER_PROMPT 与 handler 一致
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## flow.yaml 顶层结构
|
|
24
|
-
|
|
25
|
-
```yaml
|
|
26
|
-
instances:
|
|
27
|
-
<instanceId>:
|
|
28
|
-
definitionId: <内置或已存在定义 id>
|
|
29
|
-
label: ...
|
|
30
|
-
role: ...
|
|
31
|
-
input: [ { type, name, value }, ... ]
|
|
32
|
-
output: [ { type, name, value }, ... ]
|
|
33
|
-
script: <可选，tool_nodejs 直接执行的命令，支持 ${} 占位符>
|
|
34
|
-
body: | ...
|
|
35
|
-
edges:
|
|
36
|
-
- source: <instanceId>
|
|
37
|
-
target: <instanceId>
|
|
38
|
-
sourceHandle: output-0
|
|
39
|
-
targetHandle: input-0
|
|
40
|
-
ui:
|
|
41
|
-
nodePositions:
|
|
42
|
-
<instanceId>:
|
|
43
|
-
x: <number>
|
|
44
|
-
'y': <number>
|
|
45
|
-
description: 可选
|
|
46
|
-
```
|
|
47
|
-
|
|
48
|
-
- **`instances`**：键为 **instanceId**（全图唯一），值为该次运行的节点实例；**不要**写 **`description`**（系统说明由 `definitionId` 对应节点 `.md` 的 frontmatter 提供）。
|
|
49
|
-
- **`script`**（仅 `tool_nodejs`）：指定直接执行的命令，流水线将跳过 AI 直接运行 `run-tool-nodejs` 执行。支持 `${workspaceRoot}`、`${flowName}`、`${runDir}`、`${flowDir}` 及所有 input 槽位占位符，值自动 shell-quote。**引用 flow 自带脚本必须用 `${flowDir}/scripts/xxx.mjs`**（`${flowDir}` 指向 flow 当前所在目录，兼容 user/workspace/builtin 三种安装位置），**禁止**硬编码 `${workspaceRoot}/.workspace/agentflow/pipelines/${flowName}/scripts/...`（flow 安装到 `~/agentflow/pipelines/` 或 builtin 时会 Cannot find module）。脚本 stdout 须输出 `{"err_code":0,"message":{"result":"..."}}`。无 `script` 时回退到 AI 执行。
|
|
50
|
-
- **`edges`**：有向边；多输入/多输出必须写对 **`targetHandle` / `sourceHandle`**（见下表）。
|
|
51
|
-
- **`ui.nodePositions`**：编辑器坐标；**每个新 instanceId 必须新增一项**，否则画布会堆叠。
|
|
52
|
-
|
|
53
|
-
---
|
|
54
|
-
|
|
55
|
-
## 节点类型选择（必读）
|
|
56
|
-
|
|
57
|
-
新增实例时，**首先判断该步骤应使用哪种节点类型**。核心原则：**能用 tool 节点确定性执行的，不要用 agent_subAgent。**
|
|
58
|
-
|
|
59
|
-
| 判断条件 | 推荐 definitionId | 说明 |
|
|
60
|
-
|----------|-------------------|------|
|
|
61
|
-
| 行为完全由输入决定，不需要 AI 推理 | **tool_nodejs** + `script` 字段 | 打印文本、运行已有脚本、文件操作、数据转换等 |
|
|
62
|
-
| 向用户输出醒目信息 | **tool_print** | 专用输出节点 |
|
|
63
|
-
| 需要 AI 理解上下文、做判断、生成内容 | **agent_subAgent** | 撰写文档、分析代码、理解语义后做决策 |
|
|
64
|
-
|
|
65
|
-
**tool_nodejs + script 示例**（打印文本）：
|
|
66
|
-
|
|
67
|
-
```yaml
|
|
68
|
-
print_haha:
|
|
69
|
-
definitionId: tool_nodejs
|
|
70
|
-
label: 打印哈哈哈
|
|
71
|
-
script: node -e "console.log(${value})"
|
|
72
|
-
input:
|
|
73
|
-
- type: 节点
|
|
74
|
-
name: prev
|
|
75
|
-
value: ''
|
|
76
|
-
- type: 文本
|
|
77
|
-
name: value
|
|
78
|
-
value: ''
|
|
79
|
-
output:
|
|
80
|
-
- type: 节点
|
|
81
|
-
name: next
|
|
82
|
-
value: ''
|
|
83
|
-
- type: 文本
|
|
84
|
-
name: result
|
|
85
|
-
value: ''
|
|
86
|
-
```
|
|
87
|
-
|
|
88
|
-
- `script` 支持 `${}` 占位符引用 input 槽位，值自动 shell-quote。
|
|
89
|
-
- input/output 须与 `tool_nodejs` 节点定义一致（prev/next + result），可按需添加额外文本/文件槽位供 `script` 引用。
|
|
90
|
-
- **成败判定**：以脚本进程 **exit code** 为准（0 = success，非 0 = failed）。
|
|
91
|
-
- **stdout → result**：脚本 stdout 直接作为 result 槽位内容，纯文本即可（如 `console.log("hello")`）。无需输出 JSON。
|
|
92
|
-
- **JSON 兼容（可选）**：stdout 为 `{"err_code":0,"message":{"result":"..."}}` 时，err_code 覆盖 exit code；仅旧脚本或需要特殊成败语义时使用。
|
|
93
|
-
|
|
94
|
-
**常见误用**：用 `agent_subAgent` 做「打印一段文字」「执行一个已知命令」「跑一个已有脚本」—— 这些都应该用 `tool_nodejs` + `script`。
|
|
95
|
-
|
|
96
|
-
### tool_nodejs 的 `script` 与 `body` 区分（关键规则）
|
|
97
|
-
|
|
98
|
-
| 字段 | 作用 | 执行时行为 |
|
|
99
|
-
|------|------|-----------|
|
|
100
|
-
| `script` | **实际执行的 shell/node 命令** | 流水线直接 spawn 执行，stdout 作为 result |
|
|
101
|
-
| `body` | **纯文档说明**（可选） | 有 `script` 时完全忽略；无 `script` 时作为 AI 指令（兜底） |
|
|
102
|
-
|
|
103
|
-
**关键约束**：
|
|
104
|
-
1. **`tool_nodejs` 必须写 `script` 字段**，内容为完整可执行的命令或脚本，禁止用自然语言描述
|
|
105
|
-
2. `script` 中可通过 `${}` 引用 input 槽位和系统变量，值自动 shell-quote
|
|
106
|
-
3. **`script` 必须引用所有非 node 类型的 input 和 output 引脚**（硬性校验，validate-flow 会报错）：
|
|
107
|
-
- 所有 input 引脚（type ≠ node）必须在 script 中出现 `${slotName}`，用于接收上游数据
|
|
108
|
-
- 所有 output 引脚（type ≠ node）必须在 script 中出现 `${slotName}`，系统将解析为 output 文件路径，脚本应直接 `fs.writeFileSync(path, value)` 写入
|
|
109
|
-
- **禁止使用 JSON stdout 封装**（`{"err_code":0,"message":{...}}`），直接写文件、用 exit code 决定成败
|
|
110
|
-
4. `body` 仅用于给人类阅读的注释说明，**不会被执行**
|
|
111
|
-
5. 如果无法写出完整可执行的 `script`（如需要 AI 理解/判断），**必须改用 `agent_subAgent`**
|
|
112
|
-
6. **禁止**在 `script` 中写自然语言，**禁止**在 `body` 中写期望被执行的代码逻辑
|
|
113
|
-
|
|
114
|
-
### tool_nodejs 复杂脚本示例
|
|
115
|
-
|
|
116
|
-
**多行脚本（API 调用 + 数据处理）**：
|
|
117
|
-
```yaml
|
|
118
|
-
fetch_api_data:
|
|
119
|
-
definitionId: tool_nodejs
|
|
120
|
-
label: 调用API获取数据
|
|
121
|
-
script: |
|
|
122
|
-
curl -s -H "Authorization: Bearer ${token}" "https://api.example.com/data" | node -e "
|
|
123
|
-
let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>{
|
|
124
|
-
const res=JSON.parse(d);
|
|
125
|
-
const items=res.data.map(i=>({id:i.id,name:i.name}));
|
|
126
|
-
console.log(JSON.stringify(items,null,2));
|
|
127
|
-
});"
|
|
128
|
-
body: |
|
|
129
|
-
调用 Example API 获取数据列表并提取 id 和 name 字段
|
|
130
|
-
input:
|
|
131
|
-
- { type: 节点, name: prev, value: '' }
|
|
132
|
-
- { type: 文本, name: token, value: '' }
|
|
133
|
-
output:
|
|
134
|
-
- { type: 节点, name: next, value: '' }
|
|
135
|
-
- { type: 文本, name: result, value: '' }
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
**文件读写 + JSON 处理**：
|
|
139
|
-
```yaml
|
|
140
|
-
merge_json_files:
|
|
141
|
-
definitionId: tool_nodejs
|
|
142
|
-
label: 合并JSON
|
|
143
|
-
script: |
|
|
144
|
-
node -e "
|
|
145
|
-
const fs=require('fs');
|
|
146
|
-
const a=JSON.parse(fs.readFileSync(${fileA},'utf8'));
|
|
147
|
-
const b=JSON.parse(fs.readFileSync(${fileB},'utf8'));
|
|
148
|
-
console.log(JSON.stringify({...a,...b},null,2));
|
|
149
|
-
"
|
|
150
|
-
body: |
|
|
151
|
-
合并两个 JSON 文件的内容
|
|
152
|
-
input:
|
|
153
|
-
- { type: 节点, name: prev, value: '' }
|
|
154
|
-
- { type: 文件, name: fileA, value: '' }
|
|
155
|
-
- { type: 文件, name: fileB, value: '' }
|
|
156
|
-
output:
|
|
157
|
-
- { type: 节点, name: next, value: '' }
|
|
158
|
-
- { type: 文本, name: result, value: '' }
|
|
159
|
-
```
|
|
160
|
-
|
|
161
|
-
**错误示范**（禁止）：
|
|
162
|
-
```yaml
|
|
163
|
-
# ❌ 错误：tool_nodejs 却没有 script，body 是自然语言
|
|
164
|
-
bad_node:
|
|
165
|
-
definitionId: tool_nodejs
|
|
166
|
-
label: 获取截图
|
|
167
|
-
body: |
|
|
168
|
-
调用 Figma REST API 获取整体 UI 截图
|
|
169
|
-
- 解析 figmaUrl 提取 fileKey
|
|
170
|
-
- 调用 GET /v1/images/:fileKey 获取截图
|
|
171
|
-
- 将截图保存到 ${result}
|
|
172
|
-
```
|
|
173
|
-
上例应改为：写出完整可执行的 `script`，或改用 `agent_subAgent`（由 AI 执行复杂操作）。
|
|
174
|
-
|
|
175
|
-
**节点单一职责**：**每个节点只做一件事，工作内容保持专注和专一。** 不要把多个无关操作塞进同一个 `body`。如果任务包含多个可独立完成的步骤，应拆分为多个节点通过边串联。例如"分析代码并生成测试"应拆为两个节点：节点 A 分析代码 → 节点 B 生成测试。拆分后可调试、可复用、可并行，AI 生成质量也更高。
|
|
176
|
-
|
|
177
|
-
详见 `reference/flow-control-capabilities.md` 第 6 节。
|
|
178
|
-
|
|
179
|
-
---
|
|
180
|
-
|
|
181
|
-
## 新增 instance 的步骤
|
|
182
|
-
|
|
183
|
-
1. 从 **`builtin/pipelines/new/flow.yaml`** 或同仓库已有 flow 中，拷贝**同类** `definitionId` 的实例块作为模板，改 **`instanceId`**、`label`，按需改 `body` / `value`。
|
|
184
|
-
2. **不要**自造 `input`/`output` 的 **顺序、name、type**；须与节点类定义一致，否则 handle 索引会错。
|
|
185
|
-
3. **默认不连线**：仅新增 `instances` 和 `ui.nodePositions`，**不写 `edges`**，重点关注节点内容与连接点的正确性设计。
|
|
186
|
-
4. **仅当用户明确说「连线」「接到 X」「插入到 A 和 B 之间」等指令时**，才在 `edges` 中增加对应的边，并写 **`sourceHandle` / `targetHandle`**。
|
|
187
|
-
5. 在 **`ui.nodePositions`** 中为该 instanceId 写入坐标（见下一节「屏幕中间」）。
|
|
188
|
-
6. 每个 flow 仍只能有一个 **`control_start`**、一个 **`control_end`** 实例（勿重复新增入口/出口）。
|
|
189
|
-
|
|
190
|
-
**`control_toBool`**（本地确定性：parseBool 解析 true/1/yes/on → true，其余 → false，不调用 AI）和 **`control_agent_toBool`**（AI agent 语义判断，适用于不确定场景）的 prediction 输出文件内容必须仅为 **`true`** 或 **`false`**。
|
|
191
|
-
|
|
192
|
-
---
|
|
193
|
-
|
|
194
|
-
## Handle 速查（新增边时必填）
|
|
195
|
-
|
|
196
|
-
| definitionId | 常用 output | 常用 input |
|
|
197
|
-
|--------------|-------------|------------|
|
|
198
|
-
| control_start | next → output-0 | — |
|
|
199
|
-
| control_end | — | prev → input-0 |
|
|
200
|
-
| control_if | next1(**TRUE**) → output-0, next2(**FALSE**) → output-1 | prev → input-0, prediction → input-1 |
|
|
201
|
-
| control_toBool | next → output-0, prediction → output-1 | prev → input-0, value → input-1 |
|
|
202
|
-
| control_agent_toBool | next → output-0, prediction → output-1 | prev → input-0, value → input-1 |
|
|
203
|
-
| control_anyOne | next → output-0 | prev1 → input-0, prev2 → input-1 |
|
|
204
|
-
| tool_load_key | next → output-0, result → output-1 | prev → input-0, key → input-1 |
|
|
205
|
-
| tool_save_key | next → output-0 | prev → input-0, key → input-1, value → input-2 |
|
|
206
|
-
| tool_get_env | value → output-0 | key → input-0 |
|
|
207
|
-
|
|
208
|
-
**ToBool → If**：`output-1` → `input-1`（prediction）。**If**：`output-0` = 真分支，`output-1` = 假分支。
|
|
209
|
-
|
|
210
|
-
更多见 `reference/flow-control-capabilities.md` 第 8 节。
|
|
211
|
-
|
|
212
|
-
---
|
|
213
|
-
|
|
214
|
-
## 新增节点的 `ui.nodePositions`：放在屏幕中间
|
|
215
|
-
|
|
216
|
-
目标：新节点出现在画布**视区中心附近**，避免默认 (0,0) 挤在角落或与旧图重叠。
|
|
217
|
-
|
|
218
|
-
- **单个新节点**：使用中心基准，例如 **`x: 400`**、**`y: 300`**（可按项目里现有节点的 x/y 范围微调；若已有图，可取现有 `nodePositions` 的 **x、y 中位数** 作为中心再落点）。
|
|
219
|
-
- **多个新节点（主链/线性）**：主链节点从左到右排列，每个节点 **x 递增 280**，y 保持一致：
|
|
220
|
-
`x: 100 + i * 280`，`y: 300`。
|
|
221
|
-
- **分支节点**：分支的不同路径在 y 方向**错开 200**，例如 if 的两路分别 `y: 200` 和 `y: 400`。
|
|
222
|
-
- **并行节点**：并行的节点保持相同 x，y 方向每个错开 200。
|
|
223
|
-
- 后续若要融入主链/分支布局，再按 `reference/flow-layout.md` 做 x 递进、y 错开。
|
|
224
|
-
|
|
225
|
-
---
|
|
226
|
-
|
|
227
|
-
## 连线（仅用户明确要求时）
|
|
228
|
-
|
|
229
|
-
**Fan-out / Fan-in 规则**：
|
|
230
|
-
- **一个 output 可连多个 input**（fan-out 允许）。
|
|
231
|
-
- **一个 input 只能有一条入边**（fan-in 禁止）。同一个 `target + targetHandle` 不得出现在多条 edge 中；若需替换连线，先删旧边再加新边。违反此规则会导致运行时只有一条边生效，其余静默丢失。
|
|
232
|
-
|
|
233
|
-
**中间插入**：删 `A → B`，改为 `A → N`（N 的 `input-0`）、`N → B`（保持原 handle 语义）。
|
|
234
|
-
**追加到 End**：删 `X → control_end`，改为 `X → Y → control_end`（常见 `output-0` / `input-0`）。
|
|
235
|
-
**If 分支**：增加 `control_toBool`（确定性）或 `control_agent_toBool`（AI 判断）+ `control_if`，prediction 边与两条分支出边按上表连接。
|
|
236
|
-
|
|
237
|
-
完整图示例：`builtin/pipelines/new/flow.yaml`。
|
|
238
|
-
|
|
239
|
-
---
|
|
240
|
-
|
|
241
|
-
## 保存后同步 Web UI
|
|
242
|
-
|
|
243
|
-
将 `flow.yaml` 写入磁盘后，在 **Web UI + Composer** 场景下应通知浏览器刷新画布，见 `skills/agentflow-flow-sync-ui/SKILL.md`。
|
|
244
|
-
|
|
245
|
-
---
|
|
246
|
-
|
|
247
|
-
## 安装（vercel-labs [skills](https://github.com/vercel-labs/skills)）
|
|
248
|
-
|
|
249
|
-
在 AgentFlow 仓库根目录：
|
|
250
|
-
|
|
251
|
-
```bash
|
|
252
|
-
npx skills add ./skills --agent cursor --skill agentflow-flow-add-instances -y
|
|
253
|
-
# 或安装本包全部技能：
|
|
254
|
-
npx skills add ./skills --agent cursor -y
|
|
12
|
+
```text
|
|
13
|
+
.workspace/agentflow/pipelines/<id>/workspace.graph.json
|
|
255
14
|
```
|
|
256
15
|
|
|
257
|
-
|
|
16
|
+
Workspace 图的入口使用 `workspace_run` 或 `workspace_scheduled_run`，不要创建 `control_start`、`control_end`，也不要修改旧 Pipeline 拓扑来实现新需求。
|
|
@@ -1,79 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agentflow-flow-edit-node-fields
|
|
3
|
-
description:
|
|
4
|
-
仅修改 AgentFlow flow.yaml 中已有实例的允许字段（label、body、role、
|
|
5
|
-
input/output 的 value 等）；禁止改 definitionId、instanceId、IO 结构与顺序、
|
|
6
|
-
不增删边与实例。用于改文案、占位符、角色标签而不破坏图拓扑与 handle。
|
|
3
|
+
description: Legacy Pipeline field editing is retired. Use the Workspace Graph skill for node field changes.
|
|
7
4
|
---
|
|
8
5
|
|
|
9
|
-
#
|
|
6
|
+
# Legacy Flow Node Field Editing（已下线）
|
|
10
7
|
|
|
11
|
-
|
|
8
|
+
此 skill 原用于修改 `flow.yaml` 的实例字段。当前新建和操作统一发生在 Workspace 图中，节点字段应修改 `workspace.graph.json` 的 `instances`，并通过 Workspace 保存/预览链路同步。
|
|
12
9
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
**权威参考**：`reference/flow-control-capabilities.md`（内置 description 语义）、`reference/flow-prompt-handler-check.md`（改 `body` 后与图一致）。
|
|
16
|
-
|
|
17
|
-
---
|
|
18
|
-
|
|
19
|
-
## 允许修改的字段（白名单）
|
|
20
|
-
|
|
21
|
-
对每个已存在的 **`<instanceId>`** 块，**仅**可改下列内容：
|
|
22
|
-
|
|
23
|
-
| 字段 | 说明 |
|
|
24
|
-
|------|------|
|
|
25
|
-
| **`label`** | 画布显示名 |
|
|
26
|
-
| **`role`** | 角色分类字符串 |
|
|
27
|
-
| **`body`** | 节点用户区正文（agent 任务描述等）；改后核对与边的数据流是否仍一致 |
|
|
28
|
-
| **`script`** | **仅限 `definitionId: tool_nodejs`**——实际执行的 shell/node 命令（`body` 有 script 时不执行）。必须写完整可执行命令，禁止写自然语言 |
|
|
29
|
-
| **`input[].value`** | 各输入槽的默认值 / 占位路径 / 字面量（**不改** 该项的 `type`、`name`） |
|
|
30
|
-
| **`output[].value`** | 各输出槽默认值（**不改** `type`、`name`） |
|
|
31
|
-
|
|
32
|
-
### tool_nodejs 特殊规则（关键）
|
|
33
|
-
|
|
34
|
-
`definitionId: tool_nodejs` 的节点**核心是 `script` 字段**，不是 `body`：
|
|
35
|
-
- **`script`**：流水线直接执行的命令代码，stdout 作为 result，exit code 决定成败
|
|
36
|
-
- **`body`**：有 `script` 时仅作为人类可读的注释说明，**不会被执行**
|
|
37
|
-
- **禁止** `tool_nodejs` 只有 `body` 没有 `script`——自然语言描述不会被执行，节点必定失败
|
|
38
|
-
- 如果无法写出完整可执行的 `script`，必须把 `definitionId` 改为 `agent_subAgent`（此变更不在本技能范围，需用 `agentflow-flow-add-instances` 技能）
|
|
39
|
-
|
|
40
|
-
**`instances.*.description`** 已废弃：不要在 flow.yaml 中写入；agent 系统说明以 **`definitionId` 对应节点定义 `.md`** 的 frontmatter **`description`** 为准。需要补充说明性文字时用 **`body`** 或 **`label`**。
|
|
41
|
-
|
|
42
|
-
---
|
|
43
|
-
|
|
44
|
-
## 禁止修改（黑名单）
|
|
45
|
-
|
|
46
|
-
- **`definitionId`**：换类型会错 handle，须走「新增实例 + 删旧实例 + 改边」流程，**不在**本技能范围。
|
|
47
|
-
- **`instanceId` 键名**：改名必须同步改 **所有 `edges` 的 source/target** 与 **`ui.nodePositions` 键**，否则图断裂；**不在**本技能范围。
|
|
48
|
-
- **`input` / `output` 数组**：不得 **增删条目**、**改顺序**、**改 `name` / `type`**（会导致 `input-0` / `output-1` 与边不对应）。
|
|
49
|
-
- **`edges`**：不得增删改（含 `sourceHandle` / `targetHandle`）。
|
|
50
|
-
- **新增或删除整个 instance 块**：使用技能 **`agentflow-flow-add-instances`** 或其它流程。
|
|
51
|
-
- **`ui.nodePositions`**：本技能默认 **不** 改；仅当用户明确要求「只动坐标」时可单独改对应 instance 的 `x` / `y`，且 **不** 改其它字段。
|
|
52
|
-
|
|
53
|
-
---
|
|
54
|
-
|
|
55
|
-
## 操作建议
|
|
56
|
-
|
|
57
|
-
1. 用搜索定位目标 **`instanceId`**，只改上表白名单字段。
|
|
58
|
-
2. 修改 **`body`** 或 **`value`** 后，若涉及「读哪些文件 / 写哪些结果」，对照 **`reference/flow-prompt-handler-check.md`**，确保仍与当前 **edges** 上的 handler 一致（本技能不改边，但若文案宣称的读写与图不符，应提示用户需另改图）。
|
|
59
|
-
3. 批量改多个节点时，对每个实例重复上述约束，**不要**顺带重构 YAML 结构。
|
|
60
|
-
|
|
61
|
-
---
|
|
62
|
-
|
|
63
|
-
## 保存后同步 Web UI
|
|
64
|
-
|
|
65
|
-
将 `flow.yaml` 写入磁盘后，在 **Web UI + Composer** 场景下应通知浏览器刷新画布，见 `skills/agentflow-flow-sync-ui/SKILL.md`。
|
|
66
|
-
|
|
67
|
-
---
|
|
68
|
-
|
|
69
|
-
## 安装（vercel-labs [skills](https://github.com/vercel-labs/skills)）
|
|
70
|
-
|
|
71
|
-
在 AgentFlow 仓库根目录：
|
|
72
|
-
|
|
73
|
-
```bash
|
|
74
|
-
npx skills add ./skills --agent cursor --skill agentflow-flow-edit-node-fields -y
|
|
75
|
-
# 或安装本包全部技能：
|
|
76
|
-
npx skills add ./skills --agent cursor -y
|
|
77
|
-
```
|
|
78
|
-
|
|
79
|
-
项目内默认 **`.agents/skills/`**；全局加 **`-g`**。
|
|
10
|
+
不要修改 `flow.yaml`、`control_start/control_end` 或调用旧 Pipeline 执行接口来完成新需求。请改用 `agentflow-workspace-graph`。
|
|
@@ -1,24 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agentflow-flow-recipes
|
|
3
|
-
description:
|
|
4
|
-
AgentFlow 常见流程模板。用于新建 Git 项目分析、加载项目 skills、打印结果、
|
|
5
|
-
以及组合 Git Checkout → CD Workspace → Load Skills → Agent → Print 的标准流水线。
|
|
3
|
+
description: Legacy Pipeline recipes are retired. Use Workspace Graph recipes for new AgentFlow canvas tasks.
|
|
6
4
|
---
|
|
7
5
|
|
|
8
|
-
#
|
|
6
|
+
# Legacy Flow Recipes（已下线）
|
|
9
7
|
|
|
10
|
-
|
|
8
|
+
旧的 `Start → … → End` 流水线 recipe 不再用于新任务。需要组合 Git Checkout、CD Workspace、Load Skills、Agent、Print 时，请在 `workspace.graph.json` 中以 `workspace_run` 为入口组织节点，并使用 `agentflow-workspace-graph` 校验槽位和连线。
|
|
11
9
|
|
|
12
|
-
|
|
13
|
-
- 需要把 Git 项目作为工作区分析，并可加载项目自身 skills。
|
|
14
|
-
- 需要避免临场猜 slot/handle，按标准 recipe 搭图。
|
|
15
|
-
|
|
16
|
-
## 必读规则
|
|
17
|
-
|
|
18
|
-
- 读 [recipes.md](references/recipes.md)。
|
|
19
|
-
- Git 项目分析的标准链路是：`Start → Git Checkout → CD Workspace → Load Skills → Agent → Print → End`。
|
|
20
|
-
- `tool_print.content` 应接 agent 输出内容；没有接 content 时才 fallback 打印上游 result。
|
|
21
|
-
|
|
22
|
-
## Reference
|
|
23
|
-
|
|
24
|
-
- [Flow recipes](references/recipes.md)
|
|
10
|
+
历史 recipes 仅供迁移参考，不得生成 `control_start` 或 `control_end`。
|
|
@@ -1,59 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agentflow-flow-sync-ui
|
|
3
|
-
description:
|
|
4
|
-
在 AgentFlow Web UI + Composer 场景下，将 flow.yaml 保存到磁盘后通知本地 UI 刷新画布；
|
|
5
|
-
使用 POST /api/flow-editor-sync（端口以 Composer 系统提示中的 URL 为准）。
|
|
3
|
+
description: Legacy flow.yaml canvas sync is retired. Workspace Graph saves are synchronized through the Workspace API automatically.
|
|
6
4
|
---
|
|
7
5
|
|
|
8
|
-
#
|
|
6
|
+
# Legacy Flow Canvas Sync（已下线）
|
|
9
7
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
## 何时执行
|
|
13
|
-
|
|
14
|
-
每次对当前流水线的 **`flow.yaml` 做完增删改并已写入磁盘** 后执行 **一次**（含多次保存中的最后一次完成后）。
|
|
15
|
-
|
|
16
|
-
## 做什么
|
|
17
|
-
|
|
18
|
-
向本地 Web UI 发通知，让已打开该流水线的浏览器通过 SSE 重拉 `GET /api/flow`（与手动切换流水线效果一致，但保留 Composer 对话区）。
|
|
19
|
-
|
|
20
|
-
在终端执行（**必须与系统提示中的 `flowId`、`flowSource`、`端口` 一致**；以下占位符在 Composer 上下文中会给出**可复制的一行命令**）：
|
|
21
|
-
|
|
22
|
-
```bash
|
|
23
|
-
curl -sS -X POST http://127.0.0.1:<PORT>/api/flow-editor-sync \
|
|
24
|
-
-H 'Content-Type: application/json' \
|
|
25
|
-
-d '{"flowId":"<flowId>","flowSource":"user"}'
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
`flowSource` 取值：
|
|
29
|
-
|
|
30
|
-
- `user`：用户目录 `~/agentflow/pipelines`（或 `AGENTFLOW_HOME`）下的该流水线
|
|
31
|
-
- `workspace`：当前项目下 `.workspace/agentflow/pipelines` 下的该流水线（仍会读取旧路径 `.cursor/agentflow/pipelines`）。同项目内 **nodes** 以 `.workspace/agentflow/nodes` 为主（可读 `.cursor/agentflow/nodes`）；**models.json** 以 `.workspace/agentflow/models.json` 为主（可读 `.cursor` 下旧文件）。
|
|
32
|
-
- `builtin`：包内 `builtin/pipelines` 模板（只读；若实际写入的是工作区副本，须用 `workspace` 触发刷新）
|
|
33
|
-
|
|
34
|
-
## 等价的 Node one-liner（无 curl 时）
|
|
35
|
-
|
|
36
|
-
```bash
|
|
37
|
-
node -e "fetch('http://127.0.0.1:<PORT>/api/flow-editor-sync',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({flowId:'<flowId>',flowSource:'user'})}).then(r=>r.text()).then(console.log)"
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
（将 `<PORT>`、`<flowId>`、`flowSource` 换成实际值。）
|
|
41
|
-
|
|
42
|
-
## 注意
|
|
43
|
-
|
|
44
|
-
- 仅 **127.0.0.1** 本地 UI；未启动 UI 时请求会失败，可忽略（Composer 正常结束时前端仍会兜底重拉图一次）。
|
|
45
|
-
- 本操作**不**写入 YAML，只触发刷新；请勿用其代替保存文件。
|
|
46
|
-
|
|
47
|
-
---
|
|
48
|
-
|
|
49
|
-
## 安装（vercel-labs [skills](https://github.com/vercel-labs/skills)）
|
|
50
|
-
|
|
51
|
-
在 AgentFlow 仓库根目录：
|
|
52
|
-
|
|
53
|
-
```bash
|
|
54
|
-
npx skills add ./skills --agent cursor --skill agentflow-flow-sync-ui -y
|
|
55
|
-
# 或安装本包全部技能：
|
|
56
|
-
npx skills add ./skills --agent cursor -y
|
|
57
|
-
```
|
|
58
|
-
|
|
59
|
-
项目内默认 **`.agents/skills/`**；全局加 **`-g`** → **`~/.cursor/skills/`**。
|
|
8
|
+
旧的 `flow.yaml` + `/api/flow-editor-sync` 刷新链路不再用于新功能。Workspace 图请直接保存 `workspace.graph.json`，或使用 Workspace Graph 页面/API 的保存机制；需要所见即所得预览时使用 `agentflow-cli workspace-preview`。
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: agentflow-node-reference
|
|
3
3
|
description: >-
|
|
4
|
-
AgentFlow
|
|
4
|
+
AgentFlow Workspace 节点参考。用于选择节点类型、确认 builtin node 的 input/output 槽位、
|
|
5
5
|
判断 local-only/script/agent 执行方式，以及避免 handle 类型和顺序接错。
|
|
6
6
|
---
|
|
7
7
|
|
|
@@ -10,12 +10,13 @@ description: >-
|
|
|
10
10
|
使用本技能处理这些问题：
|
|
11
11
|
|
|
12
12
|
- 选择 `agent_subAgent`、`tool_nodejs`、`tool_git_checkout`、`control_cd_workspace`、`tool_print` 等节点。
|
|
13
|
-
- 创建或修改
|
|
13
|
+
- 创建或修改 Workspace Graph 时需要确认 input/output 名称、类型、顺序和 handle 索引。
|
|
14
14
|
- 判断节点是否 local-only，是否会调用 agent，是否需要 `script`。
|
|
15
15
|
|
|
16
16
|
## 必读规则
|
|
17
17
|
|
|
18
|
-
- 先读 [builtin-nodes.md](references/builtin-nodes.md)，再改 `
|
|
18
|
+
- 先读 [builtin-nodes.md](references/builtin-nodes.md)，再改 `workspace.graph.json` 的 `definitionId`、`input`、`output` 或 `edges`。
|
|
19
|
+
- 新图入口使用 `workspace_run` / `workspace_scheduled_run`，不要新增 `control_start` / `control_end`。
|
|
19
20
|
- `input-N` / `output-N` 必须与节点定义中的槽位顺序一致。
|
|
20
21
|
- `tool_nodejs` 只有写了完整 `script` 才会确定性执行；自然语言任务用 `agent_subAgent`。
|
|
21
22
|
- local-only 节点由 AgentFlow runtime 执行，不会调用 agent。
|