@fieldwangai/agentflow 0.1.28 → 0.1.30

package/skills/agentflow-flow-add-instances/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: agentflow-flow-add-instances
+description: >-
+  向 AgentFlow 的 flow.yaml 新增实例：说明 instances/edges/ui 的 YAML 结构、
+  从内置定义拷贝 instance、设计连接点与内容；新增节点的 ui.nodePositions
+  默认放在画布视觉中心附近。不用于仅改已有节点文案或占位值。
+---
+
+# AgentFlow：新增 instances
+
+在 **向现有 flow 增加新节点（一个或多个）** 时使用本技能。
+
+**路径说明**：`npx skills add` 后本文件不在 AgentFlow 仓库内；文中 `reference/`、`builtin/` 均相对 **AgentFlow 仓库根目录**，请在以该仓库为工作区时打开文件。
+
+**权威参考**（仓库根）：
+
+- `reference/flow-control-capabilities.md` — handle、边、控制节点语义  
+- `reference/flow-layout.md` — 整体布局原则（本技能对「新增」默认用**中心落点**，再按需微调）  
+- `reference/flow-prompt-handler-check.md` — 增边后 USER_PROMPT 与 handler 一致  
+
+---
+
+## flow.yaml 顶层结构
+
+```yaml
+instances:
+  <instanceId>:
+    definitionId: <内置或已存在定义 id>
+    label: ...
+    role: ...
+    input: [ { type, name, value }, ... ]
+    output: [ { type, name, value }, ... ]
+    script: <可选，tool_nodejs 直接执行的命令，支持 ${} 占位符>
+    body: | ...
+edges:
+  - source: <instanceId>
+    target: <instanceId>
+    sourceHandle: output-0
+    targetHandle: input-0
+ui:
+  nodePositions:
+    <instanceId>:
+      x: <number>
+      'y': <number>
+  description: 可选
+```
+
+- **`instances`**：键为 **instanceId**（全图唯一），值为该次运行的节点实例；**不要**写 **`description`**（系统说明由 `definitionId` 对应节点 `.md` 的 frontmatter 提供）。  
+- **`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 执行。  
+- **`edges`**：有向边；多输入/多输出必须写对 **`targetHandle` / `sourceHandle`**（见下表）。  
+- **`ui.nodePositions`**：编辑器坐标；**每个新 instanceId 必须新增一项**，否则画布会堆叠。
+
+---
+
+## 节点类型选择（必读）
+
+新增实例时，**首先判断该步骤应使用哪种节点类型**。核心原则：**能用 tool 节点确定性执行的，不要用 agent_subAgent。**
+
+| 判断条件 | 推荐 definitionId | 说明 |
+|----------|-------------------|------|
+| 行为完全由输入决定，不需要 AI 推理 | **tool_nodejs** + `script` 字段 | 打印文本、运行已有脚本、文件操作、数据转换等 |
+| 向用户输出醒目信息 | **tool_print** | 专用输出节点 |
+| 需要 AI 理解上下文、做判断、生成内容 | **agent_subAgent** | 撰写文档、分析代码、理解语义后做决策 |
+
+**tool_nodejs + script 示例**（打印文本）：
+
+```yaml
+print_haha:
+  definitionId: tool_nodejs
+  label: 打印哈哈哈
+  script: node -e "console.log(${value})"
+  input:
+    - type: 节点
+      name: prev
+      value: ''
+    - type: 文本
+      name: value
+      value: ''
+  output:
+    - type: 节点
+      name: next
+      value: ''
+    - type: 文本
+      name: result
+      value: ''
+```
+
+- `script` 支持 `${}` 占位符引用 input 槽位，值自动 shell-quote。
+- input/output 须与 `tool_nodejs` 节点定义一致（prev/next + result），可按需添加额外文本/文件槽位供 `script` 引用。
+- **成败判定**：以脚本进程 **exit code** 为准（0 = success，非 0 = failed）。
+- **stdout → result**：脚本 stdout 直接作为 result 槽位内容，纯文本即可（如 `console.log("hello")`）。无需输出 JSON。
+- **JSON 兼容（可选）**：stdout 为 `{"err_code":0,"message":{"result":"..."}}` 时，err_code 覆盖 exit code；仅旧脚本或需要特殊成败语义时使用。
+
+**常见误用**：用 `agent_subAgent` 做「打印一段文字」「执行一个已知命令」「跑一个已有脚本」—— 这些都应该用 `tool_nodejs` + `script`。
+
+### tool_nodejs 的 `script` 与 `body` 区分（关键规则）
+
+| 字段 | 作用 | 执行时行为 |
+|------|------|-----------|
+| `script` | **实际执行的 shell/node 命令** | 流水线直接 spawn 执行，stdout 作为 result |
+| `body` | **纯文档说明**（可选） | 有 `script` 时完全忽略；无 `script` 时作为 AI 指令（兜底） |
+
+**关键约束**：
+1. **`tool_nodejs` 必须写 `script` 字段**，内容为完整可执行的命令或脚本，禁止用自然语言描述
+2. `script` 中可通过 `${}` 引用 input 槽位和系统变量，值自动 shell-quote
+3. **`script` 必须引用所有非 node 类型的 input 和 output 引脚**（硬性校验，validate-flow 会报错）：
+   - 所有 input 引脚（type ≠ node）必须在 script 中出现 `${slotName}`，用于接收上游数据
+   - 所有 output 引脚（type ≠ node）必须在 script 中出现 `${slotName}`，系统将解析为 output 文件路径，脚本应直接 `fs.writeFileSync(path, value)` 写入
+   - **禁止使用 JSON stdout 封装**（`{"err_code":0,"message":{...}}`），直接写文件、用 exit code 决定成败
+4. `body` 仅用于给人类阅读的注释说明，**不会被执行**
+5. 如果无法写出完整可执行的 `script`（如需要 AI 理解/判断），**必须改用 `agent_subAgent`**
+6. **禁止**在 `script` 中写自然语言，**禁止**在 `body` 中写期望被执行的代码逻辑
+
+### tool_nodejs 复杂脚本示例
+
+**多行脚本（API 调用 + 数据处理）**：
+```yaml
+fetch_api_data:
+  definitionId: tool_nodejs
+  label: 调用API获取数据
+  script: |
+    curl -s -H "Authorization: Bearer ${token}" "https://api.example.com/data" | node -e "
+      let d=''; process.stdin.on('data',c=>d+=c); process.stdin.on('end',()=>{
+        const res=JSON.parse(d);
+        const items=res.data.map(i=>({id:i.id,name:i.name}));
+        console.log(JSON.stringify(items,null,2));
+      });"
+  body: |
+    调用 Example API 获取数据列表并提取 id 和 name 字段
+  input:
+    - { type: 节点, name: prev, value: '' }
+    - { type: 文本, name: token, value: '' }
+  output:
+    - { type: 节点, name: next, value: '' }
+    - { type: 文本, name: result, value: '' }
+```
+
+**文件读写 + JSON 处理**：
+```yaml
+merge_json_files:
+  definitionId: tool_nodejs
+  label: 合并JSON
+  script: |
+    node -e "
+      const fs=require('fs');
+      const a=JSON.parse(fs.readFileSync(${fileA},'utf8'));
+      const b=JSON.parse(fs.readFileSync(${fileB},'utf8'));
+      console.log(JSON.stringify({...a,...b},null,2));
+    "
+  body: |
+    合并两个 JSON 文件的内容
+  input:
+    - { type: 节点, name: prev, value: '' }
+    - { type: 文件, name: fileA, value: '' }
+    - { type: 文件, name: fileB, value: '' }
+  output:
+    - { type: 节点, name: next, value: '' }
+    - { type: 文本, name: result, value: '' }
+```
+
+**错误示范**（禁止）：
+```yaml
+# ❌ 错误：tool_nodejs 却没有 script，body 是自然语言
+bad_node:
+  definitionId: tool_nodejs
+  label: 获取截图
+  body: |
+    调用 Figma REST API 获取整体 UI 截图
+    - 解析 figmaUrl 提取 fileKey
+    - 调用 GET /v1/images/:fileKey 获取截图
+    - 将截图保存到 ${result}
+```
+上例应改为：写出完整可执行的 `script`，或改用 `agent_subAgent`（由 AI 执行复杂操作）。
+
+**节点单一职责**：**每个节点只做一件事，工作内容保持专注和专一。** 不要把多个无关操作塞进同一个 `body`。如果任务包含多个可独立完成的步骤，应拆分为多个节点通过边串联。例如"分析代码并生成测试"应拆为两个节点：节点 A 分析代码 → 节点 B 生成测试。拆分后可调试、可复用、可并行，AI 生成质量也更高。
+
+详见 `reference/flow-control-capabilities.md` 第 6 节。
+
+---
+
+## 新增 instance 的步骤
+
+1. 从 **`builtin/pipelines/new/flow.yaml`** 或同仓库已有 flow 中，拷贝**同类** `definitionId` 的实例块作为模板，改 **`instanceId`**、`label`，按需改 `body` / `value`。  
+2. **不要**自造 `input`/`output` 的 **顺序、name、type**；须与节点类定义一致，否则 handle 索引会错。  
+3. **默认不连线**：仅新增 `instances` 和 `ui.nodePositions`，**不写 `edges`**，重点关注节点内容与连接点的正确性设计。  
+4. **仅当用户明确说「连线」「接到 X」「插入到 A 和 B 之间」等指令时**，才在 `edges` 中增加对应的边，并写 **`sourceHandle` / `targetHandle`**。  
+5. 在 **`ui.nodePositions`** 中为该 instanceId 写入坐标（见下一节「屏幕中间」）。  
+6. 每个 flow 仍只能有一个 **`control_start`**、一个 **`control_end`** 实例（勿重复新增入口/出口）。
+
+**`control_toBool`**（本地确定性：parseBool 解析 true/1/yes/on → true，其余 → false，不调用 AI）和 **`control_agent_toBool`**（AI agent 语义判断，适用于不确定场景）的 prediction 输出文件内容必须仅为 **`true`** 或 **`false`**。
+
+---
+
+## Handle 速查（新增边时必填）
+
+| definitionId | 常用 output | 常用 input |
+|--------------|-------------|------------|
+| control_start | next → output-0 | — |
+| control_end | — | prev → input-0 |
+| control_if | next1(**TRUE**) → output-0, next2(**FALSE**) → output-1 | prev → input-0, prediction → input-1 |
+| control_toBool | next → output-0, prediction → output-1 | prev → input-0, value → input-1 |
+| control_agent_toBool | next → output-0, prediction → output-1 | prev → input-0, value → input-1 |
+| control_anyOne | next → output-0 | prev1 → input-0, prev2 → input-1 |
+| tool_load_key | next → output-0, result → output-1 | prev → input-0, key → input-1 |
+| tool_save_key | next → output-0 | prev → input-0, key → input-1, value → input-2 |
+| tool_get_env | value → output-0 | key → input-0 |
+
+**ToBool → If**：`output-1` → `input-1`（prediction）。**If**：`output-0` = 真分支，`output-1` = 假分支。
+
+更多见 `reference/flow-control-capabilities.md` 第 8 节。
+
+---
+
+## 新增节点的 `ui.nodePositions`：放在屏幕中间
+
+目标：新节点出现在画布**视区中心附近**，避免默认 (0,0) 挤在角落或与旧图重叠。
+
+- **单个新节点**：使用中心基准，例如 **`x: 400`**、**`y: 300`**（可按项目里现有节点的 x/y 范围微调；若已有图，可取现有 `nodePositions` 的 **x、y 中位数** 作为中心再落点）。  
+- **多个新节点（主链/线性）**：主链节点从左到右排列，每个节点 **x 递增 280**，y 保持一致：  
+  `x: 100 + i * 280`，`y: 300`。  
+- **分支节点**：分支的不同路径在 y 方向**错开 200**，例如 if 的两路分别 `y: 200` 和 `y: 400`。  
+- **并行节点**：并行的节点保持相同 x，y 方向每个错开 200。  
+- 后续若要融入主链/分支布局，再按 `reference/flow-layout.md` 做 x 递进、y 错开。
+
+---
+
+## 连线（仅用户明确要求时）
+
+**Fan-out / Fan-in 规则**：  
+- **一个 output 可连多个 input**（fan-out 允许）。  
+- **一个 input 只能有一条入边**（fan-in 禁止）。同一个 `target + targetHandle` 不得出现在多条 edge 中；若需替换连线，先删旧边再加新边。违反此规则会导致运行时只有一条边生效，其余静默丢失。
+
+**中间插入**：删 `A → B`，改为 `A → N`（N 的 `input-0`）、`N → B`（保持原 handle 语义）。  
+**追加到 End**：删 `X → control_end`，改为 `X → Y → control_end`（常见 `output-0` / `input-0`）。  
+**If 分支**：增加 `control_toBool`（确定性）或 `control_agent_toBool`（AI 判断）+ `control_if`，prediction 边与两条分支出边按上表连接。
+
+完整图示例：`builtin/pipelines/new/flow.yaml`。
+
+---
+
+## 保存后同步 Web UI
+
+将 `flow.yaml` 写入磁盘后，在 **Web UI + Composer** 场景下应通知浏览器刷新画布，见 `skills/agentflow-flow-sync-ui/SKILL.md`。
+
+---
+
+## 安装（vercel-labs [skills](https://github.com/vercel-labs/skills)）
+
+在 AgentFlow 仓库根目录：
+
+```bash
+npx skills add ./skills --agent cursor --skill agentflow-flow-add-instances -y
+# 或安装本包全部技能：
+npx skills add ./skills --agent cursor -y
+```
+
+项目内默认 **`.agents/skills/`**；全局加 **`-g`** → **`~/.cursor/skills/`**。

package/skills/agentflow-flow-edit-node-fields/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: agentflow-flow-edit-node-fields
+description: >-
+  仅修改 AgentFlow flow.yaml 中已有实例的允许字段（label、body、role、
+  input/output 的 value 等）；禁止改 definitionId、instanceId、IO 结构与顺序、
+  不增删边与实例。用于改文案、占位符、角色标签而不破坏图拓扑与 handle。
+---
+
+# AgentFlow：仅修改已有节点（白名单字段）
+
+在 **不增加/删除节点与边、不改编译拓扑** 的前提下，修改一个或多个 **已有** `instances` 条目时使用本技能。
+
+**路径说明**：`npx skills add` 后本文件不在 AgentFlow 仓库内；`reference/` 相对 **AgentFlow 仓库根目录**。
+
+**权威参考**：`reference/flow-control-capabilities.md`（内置 description 语义）、`reference/flow-prompt-handler-check.md`（改 `body` 后与图一致）。
+
+---
+
+## 允许修改的字段（白名单）
+
+对每个已存在的 **`<instanceId>`** 块，**仅**可改下列内容：
+
+| 字段 | 说明 |
+|------|------|
+| **`label`** | 画布显示名 |
+| **`role`** | 角色分类字符串 |
+| **`body`** | 节点用户区正文（agent 任务描述等）；改后核对与边的数据流是否仍一致 |
+| **`script`** | **仅限 `definitionId: tool_nodejs`**——实际执行的 shell/node 命令（`body` 有 script 时不执行）。必须写完整可执行命令，禁止写自然语言 |
+| **`input[].value`** | 各输入槽的默认值 / 占位路径 / 字面量（**不改** 该项的 `type`、`name`） |
+| **`output[].value`** | 各输出槽默认值（**不改** `type`、`name`） |
+
+### tool_nodejs 特殊规则（关键）
+
+`definitionId: tool_nodejs` 的节点**核心是 `script` 字段**，不是 `body`：
+- **`script`**：流水线直接执行的命令代码，stdout 作为 result，exit code 决定成败
+- **`body`**：有 `script` 时仅作为人类可读的注释说明，**不会被执行**
+- **禁止** `tool_nodejs` 只有 `body` 没有 `script`——自然语言描述不会被执行，节点必定失败
+- 如果无法写出完整可执行的 `script`，必须把 `definitionId` 改为 `agent_subAgent`（此变更不在本技能范围，需用 `agentflow-flow-add-instances` 技能）
+
+**`instances.*.description`** 已废弃：不要在 flow.yaml 中写入；agent 系统说明以 **`definitionId` 对应节点定义 `.md`** 的 frontmatter **`description`** 为准。需要补充说明性文字时用 **`body`** 或 **`label`**。
+
+---
+
+## 禁止修改（黑名单）
+
+- **`definitionId`**：换类型会错 handle，须走「新增实例 + 删旧实例 + 改边」流程，**不在**本技能范围。  
+- **`instanceId` 键名**：改名必须同步改 **所有 `edges` 的 source/target** 与 **`ui.nodePositions` 键**，否则图断裂；**不在**本技能范围。  
+- **`input` / `output` 数组**：不得 **增删条目**、**改顺序**、**改 `name` / `type`**（会导致 `input-0` / `output-1` 与边不对应）。  
+- **`edges`**：不得增删改（含 `sourceHandle` / `targetHandle`）。  
+- **新增或删除整个 instance 块**：使用技能 **`agentflow-flow-add-instances`** 或其它流程。  
+- **`ui.nodePositions`**：本技能默认 **不** 改；仅当用户明确要求「只动坐标」时可单独改对应 instance 的 `x` / `y`，且 **不** 改其它字段。
+
+---
+
+## 操作建议
+
+1. 用搜索定位目标 **`instanceId`**，只改上表白名单字段。  
+2. 修改 **`body`** 或 **`value`** 后，若涉及「读哪些文件 / 写哪些结果」，对照 **`reference/flow-prompt-handler-check.md`**，确保仍与当前 **edges** 上的 handler 一致（本技能不改边，但若文案宣称的读写与图不符，应提示用户需另改图）。  
+3. 批量改多个节点时，对每个实例重复上述约束，**不要**顺带重构 YAML 结构。
+
+---
+
+## 保存后同步 Web UI
+
+将 `flow.yaml` 写入磁盘后，在 **Web UI + Composer** 场景下应通知浏览器刷新画布，见 `skills/agentflow-flow-sync-ui/SKILL.md`。
+
+---
+
+## 安装（vercel-labs [skills](https://github.com/vercel-labs/skills)）
+
+在 AgentFlow 仓库根目录：
+
+```bash
+npx skills add ./skills --agent cursor --skill agentflow-flow-edit-node-fields -y
+# 或安装本包全部技能：
+npx skills add ./skills --agent cursor -y
+```
+
+项目内默认 **`.agents/skills/`**；全局加 **`-g`**。

package/skills/agentflow-flow-recipes/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: agentflow-flow-recipes
+description: >-
+  AgentFlow 常见流程模板。用于新建 Git 项目分析、加载项目 skills、打印结果、
+  以及组合 Git Checkout → CD Workspace → Load Skills → Agent → Print 的标准流水线。
+---
+
+# AgentFlow Flow Recipes
+
+使用本技能处理这些问题：
+
+- 用户要求“新建流水线拉仓库、cd 进去、让 agent 分析、print 结果”。
+- 需要把 Git 项目作为工作区分析，并可加载项目自身 skills。
+- 需要避免临场猜 slot/handle，按标准 recipe 搭图。
+
+## 必读规则
+
+- 读 [recipes.md](references/recipes.md)。
+- Git 项目分析的标准链路是：`Start → Git Checkout → CD Workspace → Load Skills → Agent → Print → End`。
+- `tool_print.content` 应接 agent 输出内容；没有接 content 时才 fallback 打印上游 result。
+
+## Reference
+
+- [Flow recipes](references/recipes.md)

package/skills/agentflow-flow-recipes/references/recipes.md

@@ -0,0 +1,63 @@
+# AgentFlow Flow Recipes
+
+## Git Project Analysis
+
+Use when the user asks to clone/pull a repository, enter it, ask an agent what it does, and print the result.
+
+Recommended graph:
+
+```text
+control_start
+  -> tool_git_checkout
+  -> control_cd_workspace
+  -> control_load_skills
+  -> agent_subAgent
+  -> tool_print
+  -> control_end
+```
+
+Minimum required values:
+
+- `tool_git_checkout.repoUrl`: repository URL.
+- `tool_git_checkout.pullIfExists`: `true`.
+- `tool_git_checkout.includeSubmodules`: `true` only when the user asks to pull submodules.
+- `control_cd_workspace.target`: `.`.
+- `control_load_skills.source`: `all` or `current-workspace`.
+- `agent_subAgent.body`: ask the agent to inspect README, package/build files, source directories, and entry points.
+- `tool_print.content`: connect from the agent output content.
+
+Required context edges:
+
+- Git Checkout `next` -> CD Workspace `prev`
+- Git Checkout `workspaceContext` -> CD Workspace `workspaceContext`
+- CD Workspace `next` -> Load Skills `prev`
+- CD Workspace `workspaceContext` -> Load Skills `workspaceContext`
+- Load Skills `next` -> Agent `prev`
+- CD Workspace `workspaceContext` -> Agent `workspaceContext`
+- Load Skills `skillsContext` -> Agent `skillsContext`
+- Agent content output -> Print `content`
+- Print `next` -> End `prev`
+
+Notes:
+
+- Do not connect `repoPath:file` to CD `target:text`.
+- If the agent node has no custom file output slot, use its result body and let Print fallback, or add a text/file output slot intentionally.
+- For private/internal Git repositories, local credentials must already work.
+
+## Edit Current Flow
+
+Use existing flow editing skills:
+
+- New nodes/edges: `agentflow-flow-add-instances`
+- Existing node text/value edits only: `agentflow-flow-edit-node-fields`
+- After saving in UI Composer: `agentflow-flow-sync-ui`
+
+## Print Result
+
+Prefer explicit content:
+
+```text
+agent.output.summary -> tool_print.input.content
+```
+
+Fallback behavior exists, but explicit content keeps the graph self-documenting.

package/skills/agentflow-flow-sync-ui/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: agentflow-flow-sync-ui
+description: >-
+  在 AgentFlow Web UI + Composer 场景下，将 flow.yaml 保存到磁盘后通知本地 UI 刷新画布；
+  使用 POST /api/flow-editor-sync（端口以 Composer 系统提示中的 URL 为准）。
+---
+
+# AgentFlow：保存 flow.yaml 后同步 Web 画布
+
+在 **已通过 Composer 编辑当前流水线**（系统提示里已注入 `flowId`、`flowSource`、UI 端口）且 **本机正在运行 `agentflow ui`** 时使用。
+
+## 何时执行
+
+每次对当前流水线的 **`flow.yaml` 做完增删改并已写入磁盘** 后执行 **一次**（含多次保存中的最后一次完成后）。
+
+## 做什么
+
+向本地 Web UI 发通知，让已打开该流水线的浏览器通过 SSE 重拉 `GET /api/flow`（与手动切换流水线效果一致，但保留 Composer 对话区）。
+
+在终端执行（**必须与系统提示中的 `flowId`、`flowSource`、`端口` 一致**；以下占位符在 Composer 上下文中会给出**可复制的一行命令**）：
+
+```bash
+curl -sS -X POST http://127.0.0.1:<PORT>/api/flow-editor-sync \
+  -H 'Content-Type: application/json' \
+  -d '{"flowId":"<flowId>","flowSource":"user"}'
+```
+
+`flowSource` 取值：
+
+- `user`：用户目录 `~/agentflow/pipelines`（或 `AGENTFLOW_HOME`）下的该流水线
+- `workspace`：当前项目下 `.workspace/agentflow/pipelines` 下的该流水线（仍会读取旧路径 `.cursor/agentflow/pipelines`）。同项目内 **nodes** 以 `.workspace/agentflow/nodes` 为主（可读 `.cursor/agentflow/nodes`）；**models.json** 以 `.workspace/agentflow/models.json` 为主（可读 `.cursor` 下旧文件）。
+- `builtin`：包内 `builtin/pipelines` 模板（只读；若实际写入的是工作区副本，须用 `workspace` 触发刷新）
+
+## 等价的 Node one-liner（无 curl 时）
+
+```bash
+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)"
+```
+
+（将 `<PORT>`、`<flowId>`、`flowSource` 换成实际值。）
+
+## 注意
+
+- 仅 **127.0.0.1** 本地 UI；未启动 UI 时请求会失败，可忽略（Composer 正常结束时前端仍会兜底重拉图一次）。
+- 本操作**不**写入 YAML，只触发刷新；请勿用其代替保存文件。
+
+---
+
+## 安装（vercel-labs [skills](https://github.com/vercel-labs/skills)）
+
+在 AgentFlow 仓库根目录：
+
+```bash
+npx skills add ./skills --agent cursor --skill agentflow-flow-sync-ui -y
+# 或安装本包全部技能：
+npx skills add ./skills --agent cursor -y
+```
+
+项目内默认 **`.agents/skills/`**；全局加 **`-g`** → **`~/.cursor/skills/`**。

package/skills/agentflow-node-reference/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: agentflow-node-reference
+description: >-
+  AgentFlow 内置节点参考。用于选择节点类型、确认 builtin node 的 input/output 槽位、
+  判断 local-only/script/agent 执行方式，以及避免 handle 类型和顺序接错。
+---
+
+# AgentFlow Node Reference
+
+使用本技能处理这些问题：
+
+- 选择 `agent_subAgent`、`tool_nodejs`、`tool_git_checkout`、`control_cd_workspace`、`tool_print` 等节点。
+- 创建或修改 flow 时需要确认 input/output 名称、类型、顺序和 handle 索引。
+- 判断节点是否 local-only，是否会调用 agent，是否需要 `script`。
+
+## 必读规则
+
+- 先读 [builtin-nodes.md](references/builtin-nodes.md)，再改 `flow.yaml` 的 `definitionId`、`input`、`output` 或 `edges`。
+- `input-N` / `output-N` 必须与节点定义中的槽位顺序一致。
+- `tool_nodejs` 只有写了完整 `script` 才会确定性执行；自然语言任务用 `agent_subAgent`。
+- local-only 节点由 AgentFlow runtime 执行，不会调用 agent。
+
+## Reference
+
+- [Builtin nodes reference](references/builtin-nodes.md)