@fieldwangai/agentflow 0.1.149 → 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

@@ -1,257 +1,16 @@
 ---
 name: agentflow-flow-add-instances
-description: >-
-  向 AgentFlow 的 flow.yaml 新增实例：说明 instances/edges/ui 的 YAML 结构、
-  从内置定义拷贝 instance、设计连接点与内容；新增节点的 ui.nodePositions
-  默认放在画布视觉中心附近。不用于仅改已有节点文案或占位值。
+description: Legacy Pipeline node authoring is retired. Redirect requests to add nodes to the Workspace Graph skill.
 ---
 
-# AgentFlow：新增 instances
+# Legacy Flow Node Authoring（已下线）
 
-在 **向现有 flow 增加新节点（一个或多个）** 时使用本技能。
+此 skill 原用于向 `flow.yaml` 添加实例，但旧 Pipeline 的 `Start/End` 执行模式已经下线，不再新增或编辑正式 `flow.yaml`。
 
-**路径说明**：`npx skills add` 后本文件不在 AgentFlow 仓库内；文中 `reference/`、`builtin/` 均相对 **AgentFlow 仓库根目录**，请在以该仓库为工作区时打开文件。
+用户要在画布中加节点时，请改用 `agentflow-workspace-graph`，编辑：
 
-**权威参考**（仓库根）：
-
-- `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
+```text
+.workspace/agentflow/pipelines/<id>/workspace.flow.js
 ```
 
-项目内默认 **`.agents/skills/`**；全局加 **`-g`** → **`~/.cursor/skills/`**。
+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` | — | — |