@fieldwangai/agentflow 0.1.159 → 0.1.162

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

@@ -4,6 +4,7 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 const PACKAGE_NAME = "@fieldwangai/agentflow";
 const RUNTIME_ENTRY = path.join("bin", "lib", "skill-runtime.mjs");
+const BUNDLED_RUNTIME_ENTRY = path.join("bin", "lib", "skill-runtime.mjs");
 let explicitRoot = "";
 let resolvedRoot = "";
 let runtimePromise = null;
@@ -12,7 +13,9 @@ 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();
+    const supportedManifest = manifest?.name === PACKAGE_NAME || manifest?.agentflowSkillRuntime === 1;
+    const entry = manifest?.agentflowSkillRuntime === 1 ? BUNDLED_RUNTIME_ENTRY : RUNTIME_ENTRY;
+    return supportedManifest && fs.statSync(path.join(root, entry)).isFile();
   } catch {
     return false;
   }
@@ -65,9 +68,11 @@ export function configureAgentFlowRuntime(options = {}) {
 export function resolveAgentFlowPackageRoot() {
   if (resolvedRoot) return resolvedRoot;
   const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+  const bundledRoot = path.resolve(scriptDir, "..", "runtime");
   const candidates = [
     explicitRoot,
     String(process.env.AGENTFLOW_PACKAGE_ROOT || "").trim(),
+    bundledRoot,
     ...rootsNear(process.cwd()),
     ...rootsNear(scriptDir),
     ...executableCandidates().flatMap(rootsFromExecutable),
@@ -83,14 +88,16 @@ export function resolveAgentFlowPackageRoot() {
     }
   }
   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.",
+    "Cannot locate the AgentFlow Skill runtime. Reinstall/update agentflow-cli from SkillHub, "
+    + "or set AGENTFLOW_PACKAGE_ROOT/--agentflow-package-root for an explicit development override.",
   );
 }
 
 export function loadAgentFlowRuntime() {
   if (!runtimePromise) {
-    const entry = path.join(resolveAgentFlowPackageRoot(), RUNTIME_ENTRY);
+    const root = resolveAgentFlowPackageRoot();
+    const manifest = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf-8"));
+    const entry = path.join(root, manifest?.agentflowSkillRuntime === 1 ? BUNDLED_RUNTIME_ENTRY : RUNTIME_ENTRY);
     runtimePromise = import(pathToFileURL(entry).href);
   }
   return runtimePromise;

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

@@ -1,13 +1,13 @@
 ---
 name: agentflow-flow-add-instances
-description: Legacy Pipeline node authoring is retired. Redirect requests to add nodes to the Workspace Graph skill.
+description: Legacy Pipeline node authoring is retired. Redirect requests to add nodes to agentflow-flow-dsl.
 ---
 
 # Legacy Flow Node Authoring（已下线）
 
 此 skill 原用于向 `flow.yaml` 添加实例，但旧 Pipeline 的 `Start/End` 执行模式已经下线，不再新增或编辑正式 `flow.yaml`。
 
-用户要在画布中加节点时，请改用 `agentflow-workspace-graph`，编辑：
+用户要在画布中加节点时，请改用 `agentflow-flow-dsl`，编辑：
 
 ```text
 .workspace/agentflow/pipelines/<id>/workspace.flow.js

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

@@ -2,8 +2,8 @@
 name: agentflow-flow-dsl
 description: >-
   用 workspace.flow.js（受限 ESM）编写 AgentFlow Workspace 流程图。适用于新建流程、
-  修改流程结构、添加或删除节点、修改连线、控制顺序、分支和定时入口；自定义代码节点包
-  改用 agentflow-node-dsl。
+  在现有 Workspace 画布中添加或删除节点、修改字段和连线，以及编排控制顺序、分支、
+  子流程、受控循环和定时入口；自定义代码节点包改用 agentflow-node-dsl。
 ---
 
 # AgentFlow Flow DSL
@@ -28,12 +28,14 @@ description: >-
 写完必须依次执行：
 
 ```bash
-agentflow flow dsl lint <flowDir>
-agentflow flow dsl layout <flowDir>
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs dsl-lint --file <flowDir>
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs dsl-layout --file <flowDir>
 ```
 
+先安装并读取 `agentflow-cli` Skill，把它的 `SKILL.md` 所在目录记为
+`<agentflow-cli-skill-dir>`。CLI/DSL Runtime 已随该 Skill 分发，不要安装 npm 包。
 lint 不通过先修结构，不要排版。`layout` 默认只给缺坐标的新节点补位置，保留用户手工布局。
-新建流程，或用户明确要求整理整张图时，使用 `agentflow flow dsl layout <flowDir> --all`。
+新建流程，或用户明确要求整理整张图时，在 `dsl-layout` 命令末尾加 `--all`。
 不要直接编辑 `workspace.layout.json` 里的 x/y。
 
 ## 自动排版是交付步骤
@@ -42,11 +44,25 @@ lint 不通过先修结构，不要排版。`layout` 默认只给缺坐标的新
 
 1. `lint` 校验节点、引脚和拓扑
 2. `layout` 生成或补齐坐标
-3. 如果本地 UI 已打开，再刷新或按 UI 同步 skill 通知画布加载磁盘结果
+3. 如果本地 UI 已打开，刷新画布加载磁盘结果；需要远端审图和试运行时交给
+   `agentflow-author-flow` 创建可运行 Draft
 
 自动排版按依赖从左到右放置，控制主链保持同一视觉轴，数据源放在上方，展示节点与同层主链
 错开，分支纵向展开。不要为了“看起来差不多”自行猜坐标。
 
+## 直接修改现有 Workspace
+
+用户明确要求在现有画布中加节点、改字段或连线时，先读当前 `workspace.flow.js`，只修改目标
+节点和相关引用，不要重建整张图。保留未涉及的节点 id、控制顺序、数据边、子流程契约和用户
+已有布局；新增节点再由 `layout` 补坐标。
+
+- 只放展示内容且不需要执行的 `display.*` 节点可以不写进 `flow(...)`。
+- `display.*` 的字面量写在 `content` 输入；连接上游时引用 `source.slot`。它的 `content`
+  输出仍可接给后续 agent 作为上下文。
+- 不直接编辑 `workspace.layout.json`、`workspace.nodes.json` 或 `workspace.state.json`。
+- 本地改完仍必须执行 `lint` 和 `layout`。需要可保存、可试运行的远端画布时，交给
+  `agentflow-author-flow` 创建 Draft；只读分享才使用 `workspace-preview`。
+
 ## 交付状态与用户验收
 
 `lint`、`layout`、自动化测试和 Mock 外部服务都属于 **Agent 测试环境**。完成这些只能说
@@ -60,6 +76,9 @@ GitLab 等外部系统时，必须验证真实请求、账号权限、网络、
 用户明确确认实际流程跑通后，才能将状态更新为“生产同构验收通过，可发布/可上线”。如果流程里有
 自定义代码节点，同时遵守 `agentflow-node-dsl` 里更严格的两级验证闸门。
 
+面向用户的新流程不要直接正式发布。完成 lint/layout 后使用 `agentflow-author-flow` 的
+Draft → 试运行 → 动态修改 → 明确确认 → 发布/定时流程；只读 `workspace-preview` 不能代替试运行。
+
 ## 图结构：workspace.flow.js
 
 ```js
@@ -78,7 +97,8 @@ export const run = flow("Run", collect, analyse, chart);
 |------|------|
 | 第 1 个参数（字符串） | 节点显示名。可省略 |
 | 第 2 个参数（对象） | **输入引脚**。每个键都是引脚名，没有例外 |
-| 第 3 个参数（字符串） | body：agent 是 prompt，`tool.nodejs` 是 shell 命令 |
+| 第 3 个参数 | 一般是 body；`control.while` 优先传 Condition 子流程，旧模式才传 step 脚本 |
+| 第 4 个参数 | 仅双子流程 `control.while` 使用：Body 子流程 |
 | `const 变量名` | **节点 id**。改名 = 重命名节点 |
 | `x.slotName` | 引用上游输出引脚 = 连一条数据线 |
 
@@ -91,7 +111,7 @@ export const run = flow("Run", collect, analyse, chart);
 3. **结构文件禁一切控制流**：`if` / `for` / `while` / `?:` / `.map()` / `await` /
    箭头函数 / `new` / 动态属性。要写逻辑就建代码节点
 4. 一个输出可接多个输入（fan-out 允许）；**一个输入只能接一条边**（fan-in 禁止）；
-   不能成环，没有循环原语
+   图不能成环；重复执行用 `control.while`，不要画回边
 
 ## 控制流
 
@@ -116,6 +136,38 @@ flow.resume(showPlan, stage2);          // 闸门：跑到这停，人点第二
 flow.detached(draftA, draftB);          // 有控制链但没 run 入口
 ```
 
+### 同 Workspace 子流程
+
+需要把一段标准节点拓扑复用为可调用单元时，用 `flow.input` + `flow.subflow` 声明契约，
+再由父流程用 `flow.call` 调用。子流程内部仍然是 AgentFlow 节点和连线，不要包装成一个脚本：
+
+创建、修改或验收普通子流程、`control.while` 或其画布投影时，必须读取
+[子流程与 While 编写规范](references/subflow-authoring.md)。该规范同时约束 DSL 契约、状态流、
+Start / Return 边界投影和父子流程引脚映射；不要手工创建边界节点或输入代理连线。
+
+```js
+const stateIn = flow.input("state", "json");
+const inspect = agent.subAgent("检查下一项", { state: stateIn.value }, `只处理一项并返回 JSON`);
+const save = tool.nodejs("规范化状态", { value: inspect.result }, `node ${flowDir}/scripts/normalize.mjs`);
+
+export const advanceOne = flow.subflow(
+  "推进一项",
+  { state: stateIn },
+  flow(inspect, save),
+  { state: save.result },
+);
+
+const advance = flow.call("调用推进子流程", advanceOne, { state: read.result });
+const { state } = advance;
+export const run = flow("Run", read, advance, show);
+```
+
+- `flow.input(name, type)` 只能作为某个子流程的输入代理。
+- `flow.subflow(label, inputs, flow(...), outputs)` 的输入值引用 `flow.input`，输出值引用内部节点输出。
+- `flow.call(label, subflow, pins)` 是父流程里的真实控制节点，动态引脚由契约生成。
+- 禁止父流程和内部节点直接跨边界连线；所有值必须经过 `flow.call`。
+- 禁止递归调用。当前第一版也不允许子流程内部 `wait/deferred`；调用帧恢复能力补齐前会明确失败。
+
 **`flow.fork` 不是并行。** 它是「一个 `next` 接多个下游」的写法——`flow(a, b, c)` 是线性的，
 没法在链里写出扇出，所以有了它。编译出来就是两条边，图里不存在 fork 这个东西：
 
@@ -131,7 +183,25 @@ build.next → testB.prev
 
 **分支不能汇合**——fan-in 禁止，`control.anyOne` 运行时没实现。两条分支各自收尾。
 
-**没有循环**。「改到通过为止」只能展开成固定轮次的嵌套 gate。
+### 受控循环
+
+**图仍然不能成环。** 重复执行时用 `control.while` 把循环收进一个有上限、超时和 checkpoint 的
+状态机节点；不要画回边，也不要用 DSL 的 JavaScript `while`。优先传入显式 Condition/Body 子流程：
+
+```js
+const advance = control.while("推进到人工边界", {
+  state: initial.value,
+  maxIterations: "20",
+  timeout: "30m",
+}, shouldContinue, advanceOne);
+export const run4 = flow("Run", advance, report); // done 才继续；wait 会暂停
+```
+
+- Condition 固定输出 `decision`，Body 固定输出下一版 `state`；两者都可选输出 `summary`。
+- `state` 是用户可见的业务状态载体。`iteration`、`idempotencyKey` 由运行时注入，保留在 DSL
+  契约中，但不要要求普通用户在画布上配置或连接。
+- `maxIterations` 和 `timeout` 必须显式设置。新流程不要使用旧的脚本式 While，除非用户要求兼容。
+- Condition/Body 的完整声明、状态迁移、固定输出和手动画布编辑方式都在专项规范中；不要凭记忆简写。
 
 `control.agentToBool` 是 `runtime: degraded`：它靠通用 agent 路径工作，没有任何东西
 约束模型输出，而 `parse-bool` 只认 `true` / `1` / `yes` / `on`。prompt 里必须写死
@@ -207,8 +277,11 @@ const doc  = display.html("使用说明", { content: file("docs/guide.html") });
 | 给用户看结果 | `display.markdown` / `.code` / `.html` / `.chart` / `.table` |
 | 加载 skills 给下游 agent | `control.loadSkills` → `skillsContext` |
 | 加载知识库 / 代码仓 | `control.cdWorkspace` → `knowledgeContext` |
-| 固定文本 / 密钥 | `provide.str` / `provide.password` |
+| 固定文本 / JSON / 密钥 | `provide.str` / `provide.json` / `provide.password` |
+| 文本显式解析为 JSON | `control.parseJson` |
 | 文本转 bool 做分支 | `control.agentToBool` → `prediction` |
+| 复用一段标准节点拓扑 | `flow.subflow` + `flow.call` |
+| 重复执行显式条件与单轮拓扑 | `control.while(..., conditionFlow, bodyFlow)` |
 
 `display.*` 的内容一般来自连线；写字面量则是手写文档节点（也合法，且不会被运行覆盖）。
 

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

@@ -1,4 +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."
+  short_description: "Author AgentFlow graphs, subflows, and controlled loops in DSL"
+  default_prompt: "Use $agentflow-flow-dsl to create or modify an AgentFlow workspace.flow.js graph, including subflows and controlled loops."

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

@@ -12,7 +12,9 @@
 | `control.if` | prediction:bool | — |
 | `control.loadMcp` | serverNames:text | mcpContext:text |
 | `control.loadSkills` | skillKeys:text | skillsContext:text |
+| `control.parseJson` | value:text | result:json |
 | `control.userWorkspace` | — | workspaceContext:text, cwd:file |
+| `control.while` | state:json, maxIterations:text, timeout:text | result:json, state:json, decision:text, iterations:text, summary:text, history:json, checkpointFingerprint:text |
 | `display.ascii` | content:text | content:text |
 | `display.chart` | content:text, filePath:file, workspaceContext:text | content:text |
 | `display.code` | content:text, language:text, fileName:text, wrap:bool | content:text |
@@ -24,6 +26,7 @@
 | `display.table` | content:text, filePath:file, workspaceContext:text | content:text |
 | `provide.bool` | — | value:bool |
 | `provide.file` | — | value:file |
+| `provide.json` | — | value:json |
 | `provide.password` | — | value:text |
 | `provide.str` | — | value:text |
 | `tool.displayShareLink` | title:text, layout:text, nodeIds:text, baseUrl:text | url:text, shareId:text, expiresAt:text |

package/skills/agentflow-flow-dsl/references/subflow-authoring.md

@@ -0,0 +1,230 @@
+# 子流程与 `control.while` 编写规范
+
+## 目录
+
+1. 选型
+2. 普通子流程 DSL
+3. While 的状态模型
+4. While DSL 契约
+5. 用户可见画布语义
+6. 手动编辑方式
+7. 运行与 Preview 验收
+
+## 1. 选型
+
+按以下边界选型：
+
+- 复用一段标准 AgentFlow 节点拓扑时，用 `flow.subflow` + `flow.call`。
+- 按状态重复执行同一套 Condition/Body 拓扑时，用 `control.while`。
+- 封装一个确定性计算或外部工具调用时，用代码节点，不要伪装成子流程。
+- 多个角色、阶段或业务分支只执行一次时，继续使用父图中的普通节点和控制流，不要全部塞进 While。
+
+子流程内部仍是普通 AgentFlow 节点。父流程通过显式输入/输出契约调用它，不得直接连接内部节点。
+
+## 2. 普通子流程 DSL
+
+按 `flow.input`、`flow.subflow`、`flow.call` 三层声明：
+
+```js
+const issueIn = flow.input("issue", "text");
+const inspect = agent.subAgent(
+  "分析单个 Issue",
+  { issue: issueIn.value },
+  `只分析本次输入的一个 Issue，给出目标、风险和下一步。`,
+);
+const normalize = agent.subAgent(
+  "规范化交付摘要",
+  { analysis: inspect.result },
+  `输出父流程可直接展示的摘要。`,
+);
+
+export const inspectIssue = flow.subflow(
+  "Issue 单项分析",
+  { issue: issueIn },
+  flow(inspect, normalize),
+  { summary: normalize.result, raw: inspect.result },
+);
+
+const callInspect = flow.call(
+  "调用 Issue 分析子流程",
+  inspectIssue,
+  { issue: pendingIssue.value },
+);
+const { summary, raw } = callInspect;
+export const run = flow("Run", callInspect, showSummary);
+```
+
+遵守以下约束：
+
+- 每个契约输入绑定一个 `flow.input(name, type)`，内部消费者读取它的 `.value`。
+- `flow.subflow(label, inputs, flow(...), outputs)` 的第三个参数是非空内部控制链。
+- 每个契约输出绑定内部成员节点的输出槽。
+- `flow.call(label, subflow, pins)` 是父流程里的真实执行节点；动态数据引脚来自子流程契约。
+- 一个内部节点只能属于一个子流程。禁止直接跨边界连线、跨子流程连线和递归调用。
+- 当前子流程内部不接受 `wait/deferred`。需要暂停 While 时，由 Condition 返回 `wait`。
+
+普通子流程的输出契约可以变化。画布编辑器中把某个内部数据输出拖到 Return 的 `add output`，再命名
+输出；重命名或删除后，所有父图 `SUBFLOW CALL` 的同名输出及相关连线必须同步迁移或移除。
+
+## 3. While 的状态模型
+
+把 While 理解为以下状态迁移，而不是一条隐藏的回边：
+
+```text
+初始 state₀
+  → Condition(stateₙ)
+      ├─ continue → Body(stateₙ) → stateₙ₊₁ → 下一轮 Condition
+      ├─ wait     → 保存 checkpoint，暂停 Run
+      ├─ done     → 结束 While，继续父流程下游
+      └─ fail     → While 失败
+```
+
+只把业务上需要跨轮保留的数据放入 `state`，例如：
+
+```json
+{
+  "cursor": 2,
+  "records": [{ "id": "U-001" }, { "id": "U-002" }],
+  "valid": [{ "id": "U-001" }],
+  "invalid": []
+}
+```
+
+每轮 Body 必须返回完整的下一版 `state`。业务变量不要增加成 While 顶层输出，也不要依赖隐藏的
+局部变量；把它们作为 `state` 的 JSON 字段显式更新。
+
+`iteration` 是运行时绝对轮次，`idempotencyKey` 是逐轮稳定幂等键。它们属于执行上下文，不是业务
+状态：DSL 契约必须声明，产品画布默认隐藏，普通用户不需要连接或配置。只有高级 DSL/代码节点确实
+需要轮次或外部写幂等时，才在内部消费它们。
+
+## 4. While DSL 契约
+
+优先使用显式 Condition/Body 子流程：
+
+```js
+const conditionState = flow.input("state", "json");
+const conditionIteration = flow.input("iteration", "text");
+const check = agent.subAgent(
+  "判断是否继续",
+  { state: conditionState.value },
+  `检查 state。只返回 continue、wait、done 或 fail 之一。`,
+);
+
+export const shouldContinue = flow.subflow(
+  "是否继续",
+  { state: conditionState, iteration: conditionIteration },
+  flow(check),
+  { decision: check.result },
+);
+
+const bodyState = flow.input("state", "json");
+const bodyIteration = flow.input("iteration", "text");
+const bodyKey = flow.input("idempotencyKey", "text");
+const step = tool.nodejs(
+  "推进一轮",
+  { state: bodyState.value, idempotencyKey: bodyKey.value },
+  `node ${flowDir}/scripts/advance-one.mjs`,
+);
+const nextState = control.parseJson("校验下一版状态", { value: step.result });
+
+export const advanceOne = flow.subflow(
+  "执行一轮",
+  { state: bodyState, iteration: bodyIteration, idempotencyKey: bodyKey },
+  flow(step, nextState),
+  { state: nextState.result },
+);
+
+const initial = provide.json("初始状态", {
+  value: "{\"cursor\":0,\"records\":[],\"valid\":[],\"invalid\":[]}",
+});
+const loop = control.while("逐条处理", {
+  state: initial.value,
+  maxIterations: "20",
+  timeout: "30m",
+}, shouldContinue, advanceOne);
+
+const summarize = agent.subAgent("生成最终摘要", { state: loop.state }, `把最终 state 整理成 Markdown。`);
+const report = display.markdown("最终结果", { content: summarize.result });
+export const run = flow("Run", loop, summarize, report);
+```
+
+固定契约如下：
+
+| 子流程 | DSL 输入 | DSL 输出 | 产品画布中用户需要理解的部分 |
+|--------|----------|----------|--------------------------------|
+| Condition | `state:json`, `iteration:text` | 必需 `decision:text`；可选 `summary:text` | `state → decision` |
+| Body | `state:json`, `iteration:text`, `idempotencyKey:text` | 必需 `state:json`；可选 `summary:text` | `stateₙ → stateₙ₊₁` |
+
+While Return 是固定契约：Condition 只能返回 `decision/summary`，Body 只能返回 `state/summary`。
+不要在 While Return 添加任意顶层变量。普通 Subflow Return 才支持动态输出。
+
+只在兼容旧流程时使用脚本式 While：
+
+```js
+const loop = control.while("推进", {
+  state: initial.value,
+  maxIterations: "20",
+  timeout: "30m",
+}, `node ${flowDir}/scripts/advance-one.mjs`);
+```
+
+旧脚本 stdout 只能是 `{"decision":"continue|wait|done|fail","state":{},"summary":"..."}`；日志写
+stderr。新流程不要用脚本替代 Condition/Body 子流程。
+
+## 5. 用户可见画布语义
+
+保持“运行时完整、产品上不暴露噪音”：
+
+- 父图把普通调用显示为独立的 **SUBFLOW CALL** 节点，动态输入/输出与声明契约同名。
+- 父图把 While 显示为状态机卡片：左侧 `state` 是初始业务状态输入，右侧 `state` 是最终业务状态。
+- While 卡片中的 Condition/Body 是可进入的子流程入口；`maxIterations` 和 `timeout` 可直接配置。
+- While 卡片明确展示 `stateₙ → check → run → stateₙ₊₁`，运行后展示当前 state、最新结果和历史。
+- `CHECKS`、`RUNS`、`CALLS` 虚线只表示调用关系，由系统生成，不是数据线或控制线，也不能手拉。
+- 点击 Condition、Body 或普通 Subflow 卡片进入独立子流程编辑模式；不要删除父图的调用关系视图。
+- 子图显示可拖动的 **SUBFLOW START** 和 **SUBFLOW RETURN**，复用普通节点的 Port Rail、Handle、
+  选中和拖动规则。
+- While 的 Start 只展示业务 `state`；隐藏 `iteration/idempotencyKey`。它们仍留在 DSL/IR 中由运行时注入。
+- While Return 显示固定锁定契约。Body Return 有可用值时展示 state 字段、类型和预览，并可定位来源节点。
+- 普通 Subflow Return 显示 `add output`，允许新增、重命名和删除契约输出。
+- `workspace_subflow_input` 是 IR 输入代理，画布不重复显示；Start 的同名输出线代表它的真实绑定。
+
+React 组件名、CSS 类名和像素尺寸属于实现细节，不写入 DSL。
+
+## 6. 手动编辑方式
+
+创建 While 后按以下方式操作：
+
+1. 从普通 JSON 数据节点的输出引脚连接到 While 左侧 `state`。
+2. 在 While 卡片中设置最大轮次和超时。
+3. 点击 Condition 卡片进入编辑器，添加判断节点；连接 Start `next` 到首节点 `prev`，连接 Start
+   `state` 到判断节点数据输入，连接末节点 `next` 到 Return `prev`，再把结果连到 Return `decision`。
+4. 点击 Body 卡片进入编辑器，连接 Start `state` 到单轮处理节点，最后把完整下一版 JSON 状态连到
+   Return `state`；文本结果先经过 `control.parseJson`。
+5. 需要摘要时连接可选 `summary`。不要寻找或手工连接 `iteration/idempotencyKey` 产品引脚。
+6. 返回父图，确认 Condition/Body 卡片、状态流说明和两条调用虚线仍存在。
+
+创建普通子流程时，Start/Return 的控制线和数据线方式相同；区别是 Return 输出可以通过 `add output`
+扩展，父图 SUBFLOW CALL 会同步出现同名输出。
+
+## 7. 运行与 Preview 验收
+
+完成 DSL 后执行：
+
+```bash
+agentflow flow dsl lint <flowDir>
+agentflow flow dsl layout <flowDir>
+```
+
+涉及子流程或 While 时，不能只凭 lint、单元测试或 DSL 文本宣称完成。打开真实 Workspace Preview：
+
+1. 确认父流程只通过 SUBFLOW CALL 或 While 调用子流程，没有直接跨边界线。
+2. 确认调用虚线稳定落到对应 Start，且不会被误读成 `next` 控制线。
+3. 确认 Start/Return 可拖动，保存刷新后位置和契约不丢失。
+4. 确认普通子流程多输出在 Return 与 Call 两侧逐项对应。
+5. 确认 While 只暴露业务 state，Condition/Body 固定输出正确，运行时字段没有泄露到普通 UI。
+6. 确认节点高度随内容收敛，没有大面积空白、越界历史或重叠引脚。
+7. 实际运行至少两轮，验证 `state` 确实变化；`continue` 才启动 Body，`done` 继续下游，`wait` 保存
+   checkpoint 且不触发下游。
+8. 重新运行等待中的 While，确认轮次、累计超时、历史和幂等键不重置。
+
+任何一项失败，都先修正 DSL、投影或运行时，再重新 lint、测试和预览。

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

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

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

@@ -7,7 +7,7 @@ description: Workspace Graph recipes for AgentFlow canvas tasks (git analysis, d
 
 组合 Git Checkout、CD Workspace、Load Skills、Agent、Display 等节点时，先读
 [recipes.md](references/recipes.md)，在 `workspace.flow.js` 中以 `flow(...)` 为入口组织节点，
-再用 `agentflow-workspace-graph` 校验槽位和连线。
+再用 `agentflow-flow-dsl` 校验槽位和连线。
 
 旧的 `Start → … → End` 流水线 recipe 已下线；不得生成 `control_start` / `control_end`
 或其它已退役的节点类型（recipes.md 末尾列出了完整清单）。

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

@@ -102,8 +102,7 @@ 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**
+- Structure, nodes, edges, full syntax and node calls: **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.

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.flow.js`（见 **agentflow-workspace-graph**），或使用 Workspace Graph 页面/API 的保存机制；需要所见即所得预览时使用 `agentflow-cli workspace-preview --file <flowDir>`。
+旧的 `flow.yaml` + `/api/flow-editor-sync` 刷新链路不再用于新功能。Workspace 图请按 **agentflow-flow-dsl** 编辑 `workspace.flow.js`，或使用 Workspace 页面/API 的保存机制；需要可编辑、可试运行的远端画布时使用 **agentflow-author-flow** 的 Draft，纯只读分享才使用 `agentflow-cli workspace-preview --file <flowDir>`。

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

@@ -27,8 +27,8 @@ description: >-
 node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs config
 ```
 
-跨端节点操作要求 `localRuntime.available: true` 和有效 token；缺少 companion skill 或本地
-AgentFlow runtime 时先停止并按 `agentflow-cli` 的安装说明修复。
+跨端节点操作要求 `localRuntime.available: true` 和有效 token。Runtime 已包含在 companion
+Skill 中；缺失时重新安装或更新 `agentflow-cli`，不要另装 npm CLI。
 
 写新包之前，先搜索服务端目录，避免重复造已有节点：
 
@@ -115,6 +115,45 @@ await fs.writeFile(p, csvText); await fs.writeFile(outputs.deduped, p);   // ✗
 
 可用类型：`text` `file` `bool` `node` `image` `json`。未知类型直接报错。
 
+## Node UI Kit（可选）
+
+节点需要在画布上解释输入绑定、执行步骤或运行状态时，在 `export default` 中声明 `ui.card`。
+UI 与清单一起静态解析和发布；节点包不能注入 React、HTML 或事件处理器，只能组合平台白名单
+组件：`binding`、`code`、`decision`、`metrics`、`summary`、`history`。
+
+```js
+export default {
+  id: "advance_state",
+  version: "1.0.0",
+  name: "推进状态",
+  inputs: { state: { type: "json" }, max: { type: "text", default: "20" } },
+  outputs: { decision: { type: "text" }, iterations: { type: "text" }, history: { type: "json" } },
+  ui: {
+    card: {
+      template: "state-machine", // details | state-machine
+      icon: "repeat",            // Material Symbols 名称
+      tone: "purple",            // neutral | blue | purple | green | amber | red
+      sections: [
+        { type: "binding", label: "State", input: "state" },
+        { type: "code", label: "Step", field: "script" },
+        { type: "decision", label: "Decision", output: "decision", source: "step.result.decision",
+          options: [
+            { value: "continue", label: "continue", tone: "purple" },
+            { value: "done", label: "done", tone: "green" },
+          ] },
+        { type: "metrics", label: "Progress", items: [
+          { label: "Iteration", output: "iterations", maxInput: "max" },
+        ] },
+        { type: "history", label: "History", output: "history", limit: 3 },
+      ],
+    },
+  },
+};
+```
+
+字段里的 `input` / `output` 必须引用本节点已声明的槽位；`code.field` 只能是 `script`、
+`scriptRef`、`body`、`implementationRef`。未知组件或字段会在清单规范化时被丢弃，不会进入 UI。
+
 ## `run(inputs, outputs, dirs)`
 
 | 参数 | 内容 |
@@ -144,7 +183,7 @@ Agent 自行完成且保留可重现证据：
 - 节点包含 `scripts/` / `templates/` / `assets/` 时，用完整 ZIP 安装后再跑一次，不得只测 `index.mjs`
 
 ```bash
-agentflow flow dsl lint <flowDir>
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs dsl-lint --file <flowDir>
 ```
 
 这一级通过后只能汇报：**开发验证通过，待生产同构验收**。
@@ -164,16 +203,8 @@ agentflow flow dsl lint <flowDir>
 
 ## 发布给别的流程用
 
-流程自带的 `nodes/<name>/` 只有那个流程能用。要复用就发布：
-
-```bash
-agentflow marketplace publish-node <flowDir>/nodes/<name>
-agentflow marketplace list
-```
-
-包会被复制到 `.workspace/agentflow/marketplace/packages/nodes/<id>/<version>`。
-
-要发给另一台机器或另一个 Agent workspace，上传和安装**整个包目录**：
+流程自带的 `nodes/<name>/` 只有那个流程能用。要让其它流程或其它 Agent workspace 复用，
+通过 token-backed CLI 上传和安装**整个包目录**：
 
 ```bash
 node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs node-package-publish --file <flowDir>/nodes/<name>