@fieldwangai/agentflow 0.1.153 → 0.1.154

package/skills/agentflow-cli/scripts/agentflow-runtime.mjs

@@ -0,0 +1,97 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const PACKAGE_NAME = "@fieldwangai/agentflow";
+const RUNTIME_ENTRY = path.join("bin", "lib", "skill-runtime.mjs");
+let explicitRoot = "";
+let resolvedRoot = "";
+let runtimePromise = null;
+
+function packageLooksUsable(root) {
+  if (!root) return false;
+  try {
+    const manifest = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf-8"));
+    return manifest?.name === PACKAGE_NAME && fs.statSync(path.join(root, RUNTIME_ENTRY)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function ancestors(start) {
+  const out = [];
+  let current = path.resolve(start);
+  while (true) {
+    out.push(current);
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return out;
+}
+
+function rootsNear(start) {
+  const out = [];
+  for (const ancestor of ancestors(start)) {
+    out.push(ancestor, path.join(ancestor, "node_modules", "@fieldwangai", "agentflow"));
+  }
+  return out;
+}
+
+function executableCandidates() {
+  const names = process.platform === "win32" ? ["agentflow.cmd", "agentflow.exe", "agentflow"] : ["agentflow"];
+  const dirs = String(process.env.PATH || "").split(path.delimiter).filter(Boolean);
+  return dirs.flatMap((dir) => names.map((name) => path.join(dir, name)));
+}
+
+function rootsFromExecutable(candidate) {
+  try {
+    if (!fs.statSync(candidate).isFile() && !fs.lstatSync(candidate).isSymbolicLink()) return [];
+    const real = fs.realpathSync(candidate);
+    return rootsNear(path.dirname(real));
+  } catch {
+    return [];
+  }
+}
+
+export function configureAgentFlowRuntime(options = {}) {
+  const requested = String(options.packageRoot || "").trim();
+  if (!requested || requested === explicitRoot) return;
+  explicitRoot = path.resolve(requested);
+  resolvedRoot = "";
+  runtimePromise = null;
+}
+
+export function resolveAgentFlowPackageRoot() {
+  if (resolvedRoot) return resolvedRoot;
+  const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    explicitRoot,
+    String(process.env.AGENTFLOW_PACKAGE_ROOT || "").trim(),
+    ...rootsNear(process.cwd()),
+    ...rootsNear(scriptDir),
+    ...executableCandidates().flatMap(rootsFromExecutable),
+  ].filter(Boolean);
+  const seen = new Set();
+  for (const candidate of candidates) {
+    const root = path.resolve(candidate);
+    if (seen.has(root)) continue;
+    seen.add(root);
+    if (packageLooksUsable(root)) {
+      resolvedRoot = root;
+      return root;
+    }
+  }
+  throw new Error(
+    "Cannot locate a compatible @fieldwangai/agentflow runtime. Install/update the agentflow CLI, "
+    + "put its executable on PATH, or set AGENTFLOW_PACKAGE_ROOT/--agentflow-package-root.",
+  );
+}
+
+export function loadAgentFlowRuntime() {
+  if (!runtimePromise) {
+    const entry = path.join(resolveAgentFlowPackageRoot(), RUNTIME_ENTRY);
+    runtimePromise = import(pathToFileURL(entry).href);
+  }
+  return runtimePromise;
+}

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

@@ -10,7 +10,7 @@ description: Legacy Pipeline node authoring is retired. Redirect requests to add
 用户要在画布中加节点时，请改用 `agentflow-workspace-graph`，编辑：
 
 ```text
-.workspace/agentflow/pipelines/<id>/workspace.graph.json
+.workspace/agentflow/pipelines/<id>/workspace.flow.js
 ```
 
 Workspace 图的入口使用 `workspace_run` 或 `workspace_scheduled_run`，不要创建 `control_start`、`control_end`，也不要修改旧 Pipeline 拓扑来实现新需求。

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

@@ -0,0 +1,206 @@
+---
+name: agentflow-flow-dsl
+description: >-
+  用 workspace.flow.js（受限 ESM）编写 AgentFlow Workspace 流程图。适用于新建流程、
+  修改流程结构、添加或删除节点、修改连线、控制顺序、分支和定时入口；自定义代码节点包
+  改用 agentflow-node-dsl。
+---
+
+# AgentFlow Flow DSL
+
+流程图就是代码：`flow()` 是 main，节点是 func，连线是传参。
+
+## 目录结构
+
+```
+<flowDir>/
+  workspace.flow.js        图结构。受限 JS，永不执行，只被静态解析
+  nodes/<name>/index.mjs   代码节点。普通 JS，会被真执行
+  prompts/*.md docs/*.html 超过 3000 字符的长文本
+  workspace.layout.json    画布坐标，由 layout 命令生成，不手写
+  workspace.nodes.json     图片和机器管理属性，别碰
+  workspace.state.json     运行产出，别碰
+```
+
+**两类文件规则完全不同**：本 skill 负责 `workspace.flow.js`，并在完成后调用排版命令；需要
+编写 `nodes/*/index.mjs` 时读取 `agentflow-node-dsl`。
+
+写完必须依次执行：
+
+```bash
+agentflow flow dsl lint <flowDir>
+agentflow flow dsl layout <flowDir>
+```
+
+lint 不通过先修结构，不要排版。`layout` 默认只给缺坐标的新节点补位置，保留用户手工布局。
+新建流程，或用户明确要求整理整张图时，使用 `agentflow flow dsl layout <flowDir> --all`。
+不要直接编辑 `workspace.layout.json` 里的 x/y。
+
+## 自动排版是交付步骤
+
+只生成正确连线还不算完成。AI 新建或改完流程后，必须保证节点在 UI 中可读：
+
+1. `lint` 校验节点、引脚和拓扑
+2. `layout` 生成或补齐坐标
+3. 如果本地 UI 已打开，再刷新或按 UI 同步 skill 通知画布加载磁盘结果
+
+自动排版按依赖从左到右放置，控制主链保持同一视觉轴，数据源放在上方，展示节点与同层主链
+错开，分支纵向展开。不要为了“看起来差不多”自行猜坐标。
+
+## 图结构：workspace.flow.js
+
+```js
+import { agent, control, display, file, flow, provide, tool } from "agentflow/flow";
+import collectMetrics from "./nodes/collect-metrics";      // 代码节点
+
+const dateStr = provide.str("查询日期", { value: "2026-08-06" });
+const collect = collectMetrics("统计语料", { date: dateStr.value });
+const analyse = agent.subAgent("解读", { metrics: collect.result }, `读 metrics 指出趋势与异常。`);
+const chart   = display.chart("规模分布", { content: analyse.result });
+
+export const run = flow("Run", collect, analyse, chart);
+```
+
+| 位置 | 含义 |
+|------|------|
+| 第 1 个参数（字符串） | 节点显示名。可省略 |
+| 第 2 个参数（对象） | **输入引脚**。每个键都是引脚名，没有例外 |
+| 第 3 个参数（字符串） | body：agent 是 prompt，`tool.nodejs` 是 shell 命令 |
+| `const 变量名` | **节点 id**。改名 = 重命名节点 |
+| `x.slotName` | 引用上游输出引脚 = 连一条数据线 |
+
+`provide.*` 只是数据源，没有 prev/next 槽，**不要放进 `flow(...)` 链**——被谁引用就跟谁跑。
+
+## 四条铁律
+
+1. 节点全部声明在**模块顶层**，不要写进函数
+2. `flow(...)` 里的顺序 = 控制流顺序；声明顺序不代表执行顺序
+3. **结构文件禁一切控制流**：`if` / `for` / `while` / `?:` / `.map()` / `await` /
+   箭头函数 / `new` / 动态属性。要写逻辑就建代码节点
+4. 一个输出可接多个输入（fan-out 允许）；**一个输入只能接一条边**（fan-in 禁止）；
+   不能成环，没有循环原语
+
+## 控制流
+
+```js
+export const run1 = flow("Run", a, b, c);                       // 顺序
+
+export const nightly = flow.schedule("每日",                     // 定时
+  `{"enabled":true,"cron":"0 8 * * *","timezone":"Asia/Shanghai","overlapPolicy":"skip"}`,
+  fetchData, sendReport,
+);
+
+const ok   = control.agentToBool("判断", { value: review.result }, `合格返回 true`);
+const gate = control.if("是否通过", { prediction: ok.prediction },  // 分支
+  flow(publish, notifySuccess),                                   // then
+  flow(rollback, notifyFail),                                     // else
+);
+export const run2 = flow("Run", review, ok, gate);
+
+export const run3 = flow("Run", build, flow.fork(flow(testA), flow(testB, report)));  // 控制边扇出
+
+flow.resume(showPlan, stage2);          // 闸门：跑到这停，人点第二个 run 才继续
+flow.detached(draftA, draftB);          // 有控制链但没 run 入口
+```
+
+**`flow.fork` 不是并行。** 它是「一个 `next` 接多个下游」的写法——`flow(a, b, c)` 是线性的，
+没法在链里写出扇出，所以有了它。编译出来就是两条边，图里不存在 fork 这个东西：
+
+```
+build.next → testA.prev
+build.next → testB.prev
+```
+
+运行时把两条分支的节点都收进计划，然后**按拓扑序串行执行**。两个各睡 3 秒的分支跑完要
+6 秒，不是 3 秒。分支之间也没有隔离：任何一个节点失败，整个 run 就结束，另一支不会跑。
+
+用它的理由是画布结构（两件事都挂在 build 后面、互不依赖），不是省时间。
+
+**分支不能汇合**——fan-in 禁止，`control.anyOne` 运行时没实现。两条分支各自收尾。
+
+**没有循环**。「改到通过为止」只能展开成固定轮次的嵌套 gate。
+
+`control.agentToBool` 是 `runtime: degraded`：它靠通用 agent 路径工作，没有任何东西
+约束模型输出，而 `parse-bool` 只认 `true` / `1` / `yes` / `on`。prompt 里必须写死
+「只回 true 或 false，多一个字都会被判成 false」。
+
+## 引脚值与正文插值
+
+引脚值可以写字符串、`file(...)`、上游引用，也可以写 `true` / `42`——非字符串会规范成
+字符串存图；只有定义表里声明为 `bool` 的槽（以及你自己用 `true`/`false` 建的槽）写回时
+还是裸的 `true`。
+
+正文（第 3 个参数）里的 `${...}` 有两种含义，按这个顺序判定：
+
+```js
+// 1) 本节点已有同名引脚 -> 运行时占位符，跑的时候换成该槽的值
+const a = agent.subAgent("解读", { metrics: collect.result }, `读 ${metrics} 指出趋势`);
+
+// 2) 引用上游 -> 自动建一个同名引脚并连线，等价于上面那种写法
+const b = agent.subAgent("解读", {}, `分析 ${dateStr.value} 的数据`);
+//   => 引脚 dateStr 接到 dateStr.value，正文存成 `分析 ${dateStr} 的数据`
+```
+
+第 2 种的槽名取**引用表达式的根标识符**（`dateStr.value` -> `dateStr`）。想让槽叫别的名字，
+就用第 1 种写法显式写引脚。插值只在正文里生效，引脚值里的 `${}` 运行时不会替换。
+
+## 自定义代码节点
+
+行为完全由输入决定、不需要 AI 推理时，创建代码节点。不要在本 skill 中推断节点包协议；
+读取 `agentflow-node-dsl`，由它负责 `nodes/<name>/index.mjs` 的声明、实现、测试和发布规则。
+
+## 自定义输出槽（agent 节点）
+
+`agent.subAgent` 想多吐一个值，两件事都要做：
+
+```js
+const breakdown = agent.subAgent("需求拆解", { tapdId: story.result },
+  `拆解需求……
+
+因为本节点有额外输出槽，回复必须只包含一个信封，不要有其它内容：
+---agentflow
+result: |
+  <完整结果，每行缩进两个空格>
+outParams:
+  storyId: <值>
+---end`,
+);
+const { storyId } = breakdown;              // 声明额外输出槽，下游直接用
+
+const notify = tool.wecomSendAppMarkdown("通知", { markdown: breakdown.result, toUser: storyId });
+```
+
+没有额外输出槽的 agent **不要**写信封，直接回正文。
+
+`agent.subAgent` 可以自由加自定义**输入**槽，当实参写就行。声明了但暂时不接线的
+写 `{ url: null }`，否则这个槽不会存在。
+
+## 超长文本外置
+
+body 或引脚值超过 3000 字符，抽成文件：
+
+```js
+const plan = agent.subAgent("规划", { skillsContext }, file("prompts/plan.md"));
+const doc  = display.html("使用说明", { content: file("docs/guide.html") });
+```
+
+## 节点选型
+
+| 场景 | 用 |
+|------|----|
+| 要 AI 理解 / 判断 / 生成 | `agent.subAgent` |
+| 行为由输入完全决定，逻辑复杂 | **建代码节点** `nodes/<name>/index.mjs` |
+| 一行 shell 就能搞定 | `tool.nodejs("名字", {}, \`node -e "..."\`)` |
+| 给用户看结果 | `display.markdown` / `.html` / `.chart` / `.table` |
+| 加载 skills 给下游 agent | `control.loadSkills` → `skillsContext` |
+| 加载知识库 / 代码仓 | `control.cdWorkspace` → `knowledgeContext` |
+| 固定文本 / 密钥 | `provide.str` / `provide.password` |
+| 文本转 bool 做分支 | `control.agentToBool` → `prediction` |
+
+`display.*` 的内容一般来自连线；写字面量则是手写文档节点（也合法，且不会被运行覆盖）。
+
+## 全部可用节点
+
+见 [node-calls.md](references/node-calls.md)。该表由
+`scripts/generate-agentflow-skill-references.mjs` 从 `builtin/nodes/*.md` 生成，
+只列运行时真正支持的类型——用了表外的类型 lint 会直接报错。

package/skills/agentflow-flow-dsl/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AgentFlow Flow DSL"
+  short_description: "Author AgentFlow workspace graphs and connections in DSL"
+  default_prompt: "Use $agentflow-flow-dsl to create or modify an AgentFlow workspace.flow.js graph."

package/skills/agentflow-flow-dsl/references/node-calls.md

@@ -0,0 +1,39 @@
+# AgentFlow Flow DSL — 内置节点调用表
+
+> Generated from `builtin/nodes/*.md` by `scripts/generate-agentflow-skill-references.mjs`.
+> 只列 `runtime: native` 的节点——其余类型 lint 会直接报错。
+
+`prev` / `next` / `next1` / `next2` 是控制引脚，由 `flow()` 自动接，**不要手写**。
+
+| 调用 | 输入引脚 | 输出引脚 |
+|------|----------|----------|
+| `agent.subAgent` | workspaceContext:text, skillsContext:text, mcpContext:text, knowledgeContext:text | result:text |
+| `control.cdWorkspace` | path:text, label:text, knowledgeContext:text, workspaceContext:text | knowledgeContext:text, workspaceContext:text, cwd:file |
+| `control.if` | prediction:bool | — |
+| `control.loadMcp` | serverNames:text | mcpContext:text |
+| `control.loadSkills` | skillKeys:text | skillsContext:text |
+| `control.userWorkspace` | — | workspaceContext:text, cwd:file |
+| `display.ascii` | content:text | content:text |
+| `display.chart` | content:text, filePath:file, workspaceContext:text | content:text |
+| `display.html` | content:text, filePath:file, workspaceContext:text | content:text |
+| `display.image` | src:text, filePath:file, alt:text, workspaceContext:text | src:text |
+| `display.markdown` | content:text | content:text |
+| `display.mermaid` | content:text | content:text |
+| `display.reactApp` | content:text, filePath:file, workspaceContext:text | content:text |
+| `display.table` | content:text, filePath:file, workspaceContext:text | content:text |
+| `provide.bool` | — | value:bool |
+| `provide.file` | — | value:file |
+| `provide.password` | — | value:text |
+| `provide.str` | — | value:text |
+| `tool.displayShareLink` | title:text, layout:text, nodeIds:text, baseUrl:text | url:text, shareId:text, expiresAt:text |
+| `tool.gitCheckout` | repoUrl:text, branch:text, targetDir:text, pullIfExists:bool, includeSubmodules:bool, remote:text, workspaceContext:text | repoPath:file, branch:text, commit:text, changed:bool, workspaceContext:text, gitContext:text |
+| `tool.gitlabCreateMr` | repoPath:file, gitContext:text, workspaceContext:text, sourceBranch:text, targetBranch:text, title:text, description:text, draft:bool, labels:text, push:bool, remote:text, tokenEnv:text, gitlabApiBase:text, removeSourceBranch:bool, squash:bool | mrUrl:text, created:bool, mrIid:text, projectId:text, sourceBranch:text, targetBranch:text, title:text, message:text |
+| `tool.gitWorktreeLoad` | repoPath:file, branch:text, worktreePath:file, pruneMissing:bool, force:bool, gitContext:text, workspaceContext:text | worktreePath:file, branch:text, commit:text, workspaceContext:text, gitContext:text |
+| `tool.gitWorktreeUnload` | repoPath:file, worktreePath:file, gitContext:text, workspaceContext:text, force:bool, prune:bool | removed:bool, workspaceContext:text, message:text |
+| `tool.nodejs` | workspaceContext:text, skillsContext:text, mcpContext:text | result:text |
+| `tool.setRunEnv` | key:text, value:text, variables:text | keys:text, count:text |
+| `tool.wecomSendAppMarkdown` | markdown:text, toUser:text, corpId:text, corpSecret:text, agentId:text, accessToken:text | sent:bool, message:text, response:text |
+| `tool.wecomSendGroupMarkdown` | markdown:text, webhookUrl:text, webhookKey:text | sent:bool, message:text, response:text |
+| `workspace.oneClickTask` | skillKeys:text, includeWorkspaceContext:bool, displayType:text, knowledgeContext:text, workspaceContext:text | content:text, displayType:text |
+| `workspace.run` | — | — |
+| `workspace.scheduledRun` | — | — |

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

@@ -5,6 +5,6 @@ description: Legacy Pipeline field editing is retired. Use the Workspace Graph s
 
 # Legacy Flow Node Field Editing（已下线）
 
-此 skill 原用于修改 `flow.yaml` 的实例字段。当前新建和操作统一发生在 Workspace 图中，节点字段应修改 `workspace.graph.json` 的 `instances`，并通过 Workspace 保存/预览链路同步。
+此 skill 原用于修改 `flow.yaml` 的实例字段。当前新建和操作统一发生在 Workspace 图中，节点字段应修改 `workspace.flow.js` 的节点调用（见 **agentflow-workspace-graph**），并通过 Workspace 保存/预览链路同步。
 
 不要修改 `flow.yaml`、`control_start/control_end` 或调用旧 Pipeline 执行接口来完成新需求。请改用 `agentflow-workspace-graph`。

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

@@ -1,10 +1,13 @@
 ---
 name: agentflow-flow-recipes
-description: Legacy Pipeline recipes are retired. Use Workspace Graph recipes for new AgentFlow canvas tasks.
+description: Workspace Graph recipes for AgentFlow canvas tasks (git analysis, display, branching).
 ---
 
-# Legacy Flow Recipes（已下线）
+# Workspace Graph Recipes
 
-旧的 `Start → … → End` 流水线 recipe 不再用于新任务。需要组合 Git Checkout、CD Workspace、Load Skills、Agent、Print 时，请在 `workspace.graph.json` 中以 `workspace_run` 为入口组织节点，并使用 `agentflow-workspace-graph` 校验槽位和连线。
+组合 Git Checkout、CD Workspace、Load Skills、Agent、Display 等节点时，先读
+[recipes.md](references/recipes.md)，在 `workspace.flow.js` 中以 `flow(...)` 为入口组织节点，
+再用 `agentflow-workspace-graph` 校验槽位和连线。
 
-历史 recipes 仅供迁移参考，不得生成 `control_start` 或 `control_end`。
+旧的 `Start → … → End` 流水线 recipe 已下线；不得生成 `control_start` / `control_end`
+或其它已退役的节点类型（recipes.md 末尾列出了完整清单）。

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

@@ -1,63 +1,117 @@
-# AgentFlow Flow Recipes
+# AgentFlow Workspace Graph Recipes
+
+These recipes are written in `workspace.flow.js` form — the authoritative representation of a
+Workspace graph. Syntax reference: **agentflow-flow-dsl**. The old
+`control_start → … → control_end` pipeline recipes are retired; see the note at the end.
+
+Every pin name below comes from `builtin/nodes/*.md`; the full call table is
+[node-calls.md](../../agentflow-flow-dsl/references/node-calls.md). Run
+`agentflow flow dsl lint <flowDir>` after editing — a wrong pin name is an error, not a warning.
 
 ## 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.
+Clone/pull a repository, enter it, ask an agent what it does, show the result.
+
+```js
+import { agent, control, display, flow, tool } from "agentflow/flow";
+
+const checkout = tool.gitCheckout("拉取仓库", {
+  repoUrl: "https://example.com/team/repo.git",
+  pullIfExists: "true",
+});
+
+const cd = control.cdWorkspace("进入仓库", {
+  path: ".",
+  workspaceContext: checkout.workspaceContext,
+});
 
-Recommended graph:
+const skills = control.loadSkills("加载 Skills", {
+  skillKeys: `["global-codex:code-reading"]`,
+});
 
-```text
-control_start
-  -> tool_git_checkout
-  -> control_cd_workspace
-  -> control_load_skills
-  -> agent_subAgent
-  -> tool_print
-  -> control_end
+const analyse = agent.subAgent("解读仓库", {
+  workspaceContext: cd.workspaceContext,
+  skillsContext: skills.skillsContext,
+}, `读 README、构建文件、源码目录和入口，说明这个仓库是做什么的、怎么跑起来。`);
+
+const report = display.markdown("分析结果", { content: analyse.result });
+
+export const run = flow("Run", checkout, cd, skills, analyse, report);
 ```
 
-Minimum required values:
+What the data edges do:
 
-- `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.
+- `checkout.workspaceContext → cd.workspaceContext` — hands the checked-out path to CD
+- `cd.workspaceContext → analyse.workspaceContext` — tells the agent which directory it is in
+- `skills.skillsContext → analyse.skillsContext` — injects the selected skills
 
-Required context edges:
+Watch out:
 
-- 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`
+- `control.cdWorkspace` takes `path`, not `target`; `control.loadSkills` takes `skillKeys`
+  (a JSON array of `collection:skill`), not `source`
+- `control.loadSkills` has no `workspaceContext` input — do not try to chain context through
+  it; feed the agent from `cd` directly
+- Do not wire `checkout.repoPath` (a `file`) into `cd.path` (a `text`)
+- Private repositories need working local credentials
 
-Notes:
+## Show A Result
 
-- 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.
+Feed the producing pin into a `display.*` node:
+
+```js
+const shown = display.markdown("结论", { content: analyse.result });
+```
 
-## Edit Current Flow
+Pick the type that matches the payload: `display.markdown`, `.html`, `.table`, `.chart`,
+`.mermaid`, `.ascii`, `.image`, `.reactApp`.
 
-Use existing flow editing skills:
+An agent with an extra output pin must be declared by destructuring, and its prompt must emit
+the output envelope:
 
-- 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`
+```js
+const { storyId } = breakdown;
+const notify = tool.wecomSendAppMarkdown("通知", { markdown: breakdown.result, toUser: storyId });
+```
 
-## Print Result
+## Branching
 
-Prefer explicit content:
+`control.if` is the branch primitive. Its `prediction` input is a `bool`:
 
-```text
-agent.output.summary -> tool_print.input.content
+```js
+const passed = provide.bool("是否发布", { value: "true" });
+const gate = control.if("是否发布", { prediction: passed.value },
+  flow(publish, notifySuccess),
+  flow(rollback, notifyFail),
+);
+export const run = flow("Run", passed, gate);
 ```
 
-Fallback behavior exists, but explicit content keeps the graph self-documenting.
+The taken branch runs and the other is skipped. **Branches cannot rejoin** — fan-in is
+forbidden and `control_anyOne` has no runtime implementation. Let each branch finish on its own.
+
+`control.agentToBool` also produces a `prediction`, but it is `runtime: degraded`: nothing
+constrains the model's answer and `parse-bool` accepts only exactly `true` / `1` / `yes` / `on`.
+If you use it, the prompt must say "只回 true 或 false，多一个字都会被判成 false".
+
+## No Loops
+
+The run planner rejects cyclic graphs (`Workspace run graph contains a cycle`). Express
+"check → fix → re-check" as forward steps, or put the retry loop **inside** one node — the
+agent's body, a `tool.nodejs` script, or a code node under `nodes/<name>/index.mjs`. Never
+draw an edge from a downstream node back to an upstream one.
+
+## Edit The Graph
+
+- Structure, nodes, edges: **agentflow-workspace-graph**
+- Full syntax and the node call table: **agentflow-flow-dsl**
+- Node implementations in code: `nodes/<name>/index.mjs`, see **agentflow-flow-dsl**
+
+Saving is handled by the Workspace API; there is no separate canvas-sync step.
+
+## Retired
+
+`control_start`, `control_end`, `control_anyOne`, `control_toBool`, `control_interval_loop`,
+`control_delay`, `control_wait_until`, `control_cancelled`, `tool_user_check`, `tool_user_ask`,
+`tool_print`, `tool_load_key`, `tool_save_key`, `tool_get_env` and `tool_jenkins_build` only
+ever ran under the retired Start/End runtime. They are not in the node palette and lint
+rejects them — do not generate them.

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

@@ -5,4 +5,4 @@ description: Legacy flow.yaml canvas sync is retired. Workspace Graph saves are
 
 # Legacy Flow Canvas Sync（已下线）
 
-旧的 `flow.yaml` + `/api/flow-editor-sync` 刷新链路不再用于新功能。Workspace 图请直接保存 `workspace.graph.json`，或使用 Workspace Graph 页面/API 的保存机制；需要所见即所得预览时使用 `agentflow-cli workspace-preview`。
+旧的 `flow.yaml` + `/api/flow-editor-sync` 刷新链路不再用于新功能。Workspace 图请直接编辑 `workspace.flow.js`（见 **agentflow-workspace-graph**），或使用 Workspace Graph 页面/API 的保存机制；需要所见即所得预览时使用 `agentflow-cli workspace-preview --file <flowDir>`。