@fieldwangai/agentflow 0.1.153 → 0.1.154

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

@@ -0,0 +1,212 @@
+---
+name: agentflow-node-dsl
+description: >-
+  使用 AgentFlow Node DSL 编写代码节点包（节点目录中的 index.mjs），在流程里用起来，并发布到
+  marketplace 供其它流程复用。用户要求「加一个自定义节点」「把这段逻辑做成可复用节点」
+  「把节点发布出去」时使用。跨端搜索、上传、安装和 Flow 拉取/发布需配合
+  agentflow-cli skill。
+---
+
+# AgentFlow Node DSL
+
+**一个目录 = 一个节点 = 一个可发布的包。** `index.mjs` 同时是声明和实现。
+
+```
+<flowDir>/nodes/<name>/index.mjs
+```
+
+行为完全由输入决定、不需要 AI 推理的，就该是代码节点。需要理解和判断的用
+`agent.subAgent`。
+
+## CLI 前置条件
+
+同时安装并读取 `agentflow-cli` skill。把其 `SKILL.md` 所在目录记为
+`<agentflow-cli-skill-dir>`；不要假设当前项目包含 `skills/agentflow-cli`。先执行：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs config
+```
+
+跨端节点操作要求 `localRuntime.available: true` 和有效 token；缺少 companion skill 或本地
+AgentFlow runtime 时先停止并按 `agentflow-cli` 的安装说明修复。
+
+写新包之前，先搜索服务端目录，避免重复造已有节点：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs node-package-search --query "需要的能力"
+```
+
+结果包含固定版本 `specifier` 和输入/输出槽。满足需求时先 `node-package-install`，然后直接
+import 返回的 `marketplace:<id>@<version>`；只有没有合适结果时才创建 `nodes/<name>/`。
+
+## 最小完整例子
+
+```js
+import fs from "node:fs/promises";
+
+export default {
+  id: "count_lines",              // 必填，构成 marketplace:count_lines@1.0.0
+  version: "1.0.0",               // 必填，完整 semver
+  name: "统计行数",
+  description: "读一个文本文件，统计行数",
+  inputs: {
+    filePath: { type: "text", description: "文件路径", required: true },
+  },
+  outputs: {
+    total: { type: "text" },
+  },
+};
+
+export async function run(inputs, outputs, dirs) {
+  const text = await fs.readFile(inputs.filePath, "utf-8");
+  const total = text.split("\n").length;
+  await fs.writeFile(outputs.total, String(total), "utf-8");
+  console.log(`共 ${total} 行`);   // 进度而已
+}
+```
+
+在图里就是一条 import：
+
+```js
+import countLines from "./nodes/count-lines";
+
+const count = countLines("统计行数", { filePath: pick.result });
+const show  = display.markdown("结果", { content: count.total });
+```
+
+## 三条硬约束
+
+**① 声明必须是纯字面量。** `export default` 由 acorn **静态解析**——列节点面板、渲染画布、
+校验槽位、算运行缓存指纹，全程不执行包里的代码。目录扫描期执行第三方代码既慢又不安全。
+
+```js
+const T = "text";
+export default { inputs: { day: { type: T } } };        // ✗ 变量引用
+export default { ...base, id: "x" };                     // ✗ 展开
+export default { version: pkg.version };                 // ✗ 成员访问
+```
+
+违反时带位置报错（`export default.id: 只允许字面量，不允许 Identifier`），不会静默变成空
+清单让节点从面板上消失。
+
+**② `outputs.<name>` 是要写入的绝对路径，不是值。** 最容易搞错的一点。
+
+```js
+await fs.writeFile(outputs.total, String(total));   // ✓
+outputs.total = String(total);                      // ✗ 什么都没发生
+```
+
+每个声明过的输出槽各自一个文件。**第一个非控制输出槽**承载节点的结果正文。stdout 只在你
+**没有**为结果槽写文件时才当结果——所以 `console.log` 打进度不会盖掉你写进去的值。
+
+`file` 类型的输出槽同理，把**文件内容本身**写到 `outputs.<name>` 上：
+
+```js
+await fs.writeFile(outputs.deduped, csvText, "utf-8");            // ✓
+const p = path.join(dirs.outputsDir, "deduped.csv");
+await fs.writeFile(p, csvText); await fs.writeFile(outputs.deduped, p);   // ✗
+```
+
+第二种在测试里看着能过（下游确实拿到一个存在的路径），但槽文件才是被当成产物管理的东西，
+你自选的那个路径在真实运行时位于会被清理的临时目录里。
+
+**③ 槽位顺序 = 画布 handle 顺序。** `inputs` / `outputs` 是有序映射，控制槽 `prev` / `next`
+自动前置。改声明顺序等于改已有流程的接线，加槽位请往后加。
+
+可用类型：`text` `file` `bool` `node` `image` `json`。未知类型直接报错。
+
+## `run(inputs, outputs, dirs)`
+
+| 参数 | 内容 |
+|------|------|
+| `inputs` | 槽位名 → 上游传来的值。`file` 槽拿到的是路径 |
+| `outputs` | 槽位名 → **要写入的绝对路径** |
+| `dirs` | `workspaceRoot` / `nodeRunDir` / `nodeTmpDir` / `outputsDir` |
+
+失败 = 抛异常或非零退出。不要用 JSON 包裹 stdout，也不要自己造结果文件。
+
+`index.mjs` 是**普通 Node 模块**，会被真执行：`for` / `if` / `await` 都可以写。复杂实现可拆到
+包内 `scripts/`，模板和资源可放 `templates/`、`assets/` 并用相对路径加载。不要提交
+`node_modules`；跨端包当前只应依赖 Node 内置模块或包内自带源码。
+和 `workspace.flow.js` 那种「禁一切控制流」的结构文件完全两套规则。
+
+## 验证
+
+```bash
+agentflow flow dsl lint <flowDir>     # 声明能不能静态解析、接线对不对
+```
+
+然后在画布上跑一次。节点会以 `marketplace:<id>@<version>` 出现在面板里。
+
+## 发布给别的流程用
+
+流程自带的 `nodes/<name>/` 只有那个流程能用。要复用就发布：
+
+```bash
+agentflow marketplace publish-node <flowDir>/nodes/<name>
+agentflow marketplace list
+```
+
+包会被复制到 `.workspace/agentflow/marketplace/packages/nodes/<id>/<version>`。
+
+要发给另一台机器或另一个 Agent workspace，上传和安装**整个包目录**：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs node-package-publish --file <flowDir>/nodes/<name>
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs node-package-install \
+  --node <id>@<version> --workspace-root <targetWorkspace>
+```
+
+流程和本地 `nodes/` 已经一起完成时，优先一键发布，避免漏传包或只传 `index.mjs`：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs publish-flow \
+  --flow-id <flow-id> --file <flowDir> --target-space personal --with-dependencies
+```
+
+命令上传所有包目录，并只在远端发布产物中把 `./nodes/<name>` 改为固定版本 import；本地
+`workspace.flow.js` 保持不变。同版本不同内容会整批在上传前拒绝，必须先提升版本号。
+
+如果已经有 `workspace.flow.js`，直接同步它声明的全部包：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs node-package-sync \
+  --flow <flowDir> --workspace-root <targetWorkspace>
+```
+
+如果流程本身还没落到本地，直接 pull；它会先同步包，再生成本地 DSL：
+
+```bash
+node <agentflow-cli-skill-dir>/scripts/agentflow-cli.mjs pull-flow \
+  --flow-id <flow-id> --flow-source user --workspace-root <targetWorkspace>
+```
+
+传输格式是 ZIP，`scripts/`、`templates/`、`assets/` 都会随包传输；同一个 `id@version` 内容
+不同会被拒绝，修改后必须提升版本号。
+
+解析 `marketplace:<id>@<version>` 的顺序是**流程本地 → 已发布 → 集合**：流程自己的实现永远
+不会被同名的已发布包顶掉。
+
+已安装的包直接在 `workspace.flow.js` 里写版本化 import：
+
+```js
+import myNode from "marketplace:<id>@<version>";
+```
+
+存储层会把它投影成「基础类型 + `marketplaceRef`」，保存后仍保留这条 import。
+
+## 别做的事
+
+- **不要写 `node.yaml`。** 它只是已发布老包的回退清单，新包一律用 `index.mjs`。
+- **不要写 `runtime.entry` / `scripts/run.mjs`。** 那是老 manifest 的字段，现在实现就在
+  `index.mjs` 的 `run` 里。
+- **不要找旧的 `agentflow marketplace install-node`。** 它写的是 `flow.yaml` 依赖钉。跨端安装
+  使用 token-backed CLI 的 `node-package-install`；DSL 用 `marketplace:<id>@<version>` import。
+- **不要用 `agentflow run` / `apply`。** Start/End Pipeline 执行栈已退休，运行走 Workspace。
+- **不要把本机绝对路径或密钥写进包。**
+
+## 相关
+
+- `agentflow-flow-dsl`：图怎么写，import 代码节点的语法
+- `agentflow-node-reference`：内置节点类型的槽位表
+- `docs/wiki/code-node-packages.zh-CN.md`：更完整的说明

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

@@ -0,0 +1,4 @@
+interface:
+  display_name: "AgentFlow Node DSL"
+  short_description: "Create, test, and distribute reusable AgentFlow nodes"
+  default_prompt: "Use $agentflow-node-dsl to create and validate a reusable AgentFlow code node package."

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

@@ -9,13 +9,13 @@ description: >-
 
 使用本技能处理这些问题：
 
-- 选择 `agent_subAgent`、`tool_nodejs`、`tool_git_checkout`、`control_cd_workspace`、`tool_print` 等节点。
+- 选择 `agent_subAgent`、`tool_nodejs`、`tool_git_checkout`、`control_cd_workspace`、`display_markdown` 等节点。
 - 创建或修改 Workspace Graph 时需要确认 input/output 名称、类型、顺序和 handle 索引。
 - 判断节点是否 local-only，是否会调用 agent，是否需要 `script`。
 
 ## 必读规则
 
-- 先读 [builtin-nodes.md](references/builtin-nodes.md)，再改 `workspace.graph.json` 的 `definitionId`、`input`、`output` 或 `edges`。
+- 先读 [builtin-nodes.md](references/builtin-nodes.md)，再改 `workspace.flow.js` 的节点调用、引脚和连线；DSL 里的调用名见 **agentflow-flow-dsl** 的 node-calls.md。
 - 新图入口使用 `workspace_run` / `workspace_scheduled_run`，不要新增 `control_start` / `control_end`。
 - `input-N` / `output-N` 必须与节点定义中的槽位顺序一致。
 - `tool_nodejs` 只有写了完整 `script` 才会确定性执行；自然语言任务用 `agent_subAgent`。

package/skills/agentflow-node-reference/references/builtin-nodes.md

@@ -7,75 +7,36 @@
 - `tool_nodejs` needs an executable `script`; `body` is documentation when `script` exists.
 - `agent_subAgent` is for semantic/code/text reasoning tasks.
 - Local-only nodes are executed by AgentFlow runtime and do not call an agent.
+- The Workspace runtime executes a DAG; cyclic graphs are rejected. Express check-then-fix as forward steps.
 - Edge handles are positional: `input-0`, `output-0`, etc. Match slot order exactly.
 
 ## agent
 
 ### agent_subAgent
 
-- Display: SubAgent
-- Description: 利用 SubAgent 执行任务；可接收 workspaceContext 切换执行工作区，并接收 skillsContext 注入已加载 skills。
+- Display: 子 Agent
+- Description: 利用子 Agent 执行任务；可接收 knowledgeContext 读取知识库，可接收 workspaceContext 切换执行工作区，并接收 skillsContext / mcpContext 注入已加载 skills 与 MCP 工具清单。
 - Runtime: agent/runner
-- Inputs: 0. `prev`:node; 1. `workspaceContext`:text; 2. `skillsContext`:text
-- Outputs: 0. `next`:node
-
-## control
-
-### control_agent_toBool
-
-- Display: Agent ToBool
-- Description: AI-powered boolean judgment: an agent evaluates the input value and writes true/false to prediction. Use for non-deterministic scenarios requiring semantic understanding.
-- Runtime: agent/runner
-- Inputs: 0. `prev`:node; 1. `value`:text
-- Outputs: 0. `next`:node; 1. `prediction`:bool
+- Inputs: 0. `prev`:node; 1. `workspaceContext`:text; 2. `skillsContext`:text; 3. `mcpContext`:text; 4. `knowledgeContext`:text
+- Outputs: 0. `next`:node; 1. `result`:text
 
-### control_anyOne
+### workspace_one_click_task
 
-- Display: AnyOne
-- Description: Continues to next when any upstream input is ready
+- Display: 一键任务
+- Description: 输入任务描述，选择 Skills、workspace 上下文和输出类型后直接运行；等价于「Load Skills + 子 Agent + Display」的合并节点。
 - Runtime: agent/runner
-- Inputs: 0. `prev1`:node; 1. `prev2`:node
-- Outputs: 0. `next`:node
+- Inputs: 0. `prev`:node; 1. `skillKeys`:text; 2. `includeWorkspaceContext`:bool = true; 3. `displayType`:text = markdown; 4. `knowledgeContext`:text; 5. `workspaceContext`:text
+- Outputs: 0. `next`:node; 1. `content`:text; 2. `displayType`:text = markdown
 
-### control_cancelled
-
-- Display: Cancelled
-- Description: Check whether the current run/watch has been cancelled. Use cancelled output with control_if.
-- Runtime: local-only
-- Inputs: 0. `prev`:node; 1. `watchId`:text
-- Outputs: 0. `next`:node; 1. `cancelled`:bool
+## control
 
 ### control_cd_workspace
 
-- Display: CD Workspace
-- Description: Switch the runtime workspace context for downstream nodes without changing the AgentFlow pipeline workspace. Modes: - `set`: switch to target, keep previous stack unchanged. - `push`: switch to target and save the incoming context as previous. - `pop`: restore the previous context. `target` supports `${workspaceRoot}`, `${pipelineWorkspace}`, `${flowDir}`, absolute paths, and paths relative to current workspace context.
-- Runtime: local-only
-- Inputs: 0. `prev`:node; 1. `target`:text = ${pipelineWorkspace}; 2. `mode`:text = set; 3. `label`:text; 4. `workspaceContext`:text
-- Outputs: 0. `next`:node; 1. `workspaceContext`:text; 2. `cwd`:file; 3. `previous`:text
-
-### control_deadline
-
-- Display: Deadline
-- Description: Compute whether a deadline has expired. Use expired output with control_if.
-- Runtime: local-only
-- Inputs: 0. `prev`:node; 1. `startAt`:text; 2. `duration`:text; 3. `deadlineAt`:text; 4. `timezone`:text = Asia/Shanghai
-- Outputs: 0. `next`:node; 1. `expired`:bool; 2. `deadlineAt`:text
-
-### control_delay
-
-- Display: Delay
-- Description: Persistently wait for a relative duration, then continue when scheduler resumes this run.
-- Runtime: local-only
-- Inputs: 0. `prev`:node; 1. `duration`:text = 10m
-- Outputs: 0. `next`:node; 1. `wakeAt`:text
-
-### control_end
-
-- Display: End
-- Description: End point of AgentFlow, flow terminates after this node
+- Display: 加载知识库
+- Description: Load one or more read-only knowledge sources for downstream Agent nodes. This node does not change the runtime cwd. It publishes `knowledgeContext` for reading/searching referenced repos or folders. `workspaceContext` and `cwd` are retained as legacy compatibility outputs for the first source.
 - Runtime: local-only
-- Inputs: 0. `prev`:node
-- Outputs: 无
+- Inputs: 0. `prev`:node; 1. `path`:text; 2. `label`:text; 3. `knowledgeContext`:text; 4. `workspaceContext`:text
+- Outputs: 0. `next`:node; 1. `knowledgeContext`:text; 2. `workspaceContext`:text; 3. `cwd`:file
 
 ### control_if
 
@@ -85,114 +46,196 @@
 - Inputs: 0. `prev`:node; 1. `prediction`:bool
 - Outputs: 0. `next1`:node; 1. `next2`:node
 
-### control_interval_loop
+### control_load_mcp
 
-- Display: IntervalLoop
-- Description: Wait by interval and branch to continue, done, timeout, or cancelled for watch-style flows.
+- Display: Load MCP
+- Description: 加载所选 Cursor MCP Server 的工具清单，通过 mcpContext 传给下游 agent 节点。
 - Runtime: local-only
-- Inputs: 0. `prev`:node; 1. `done`:bool; 2. `cancelled`:bool; 3. `interval`:text = 10m; 4. `startAt`:text; 5. `duration`:text; 6. `deadlineAt`:text; 7. `timezone`:text = Asia/Shanghai
-- Outputs: 0. `continue`:node; 1. `done`:node; 2. `timeout`:node; 3. `cancelled`:node; 4. `wakeAt`:text; 5. `expired`:bool; 6. `deadlineAt`:text
+- Inputs: 0. `prev`:node; 1. `serverNames`:text
+- Outputs: 0. `next`:node; 1. `mcpContext`:text
 
 ### control_load_skills
 
 - Display: Load Skills
-- Description: Load SKILL.md files from the current workspace context, pipeline workspace, explicit paths, or both. The output `skillsContext` can be connected to downstream agent nodes. Loaded skills are injected into the node prompt under "已加载 Skills". Sources: - `current-workspace` - `pipeline-workspace` - `explicit-paths` - `all` Merge modes: - `replace` - `append` - `prepend`
+- Description: Load the currently selected Workspace skill collection for downstream agent nodes. Set `skillKeys` to skill names or registry keys, then connect `skillsContext` to downstream agent/tool nodes. Loaded skills are injected into the node prompt under "已加载 Skills"。 Skill key examples: - `agentflow-flow-add-instances` - `workspace-agents:agentflow-flow-edit-node-fields` - `global-codex:some-skill`
 - Runtime: local-only
-- Inputs: 0. `prev`:node; 1. `source`:text = current-workspace; 2. `paths`:text; 3. `include`:text; 4. `exclude`:text; 5. `mergeMode`:text = replace; 6. `workspaceContext`:text; 7. `skillsContext`:text
-- Outputs: 0. `next`:node; 1. `skillsContext`:text; 2. `loadedCount`:text; 3. `summary`:text
+- Inputs: 0. `prev`:node; 1. `skillKeys`:text
+- Outputs: 0. `next`:node; 1. `skillsContext`:text
 
-### control_start
+### control_user_workspace
 
-- Display: Start
-- Description: Entry point of AgentFlow, all flows should start from this node
+- Display: User Workspace
+- Description: Output a workspace context pointing to the current user's home directory.
 - Runtime: local-only
-- Inputs: 无
-- Outputs: 0. `next`:node
+- Inputs: 0. `prev`:node
+- Outputs: 0. `next`:node; 1. `workspaceContext`:text; 2. `cwd`:file
 
-### control_toBool
+### workspace_run
 
-- Display: ToBool
-- Description: Script-based boolean conversion: executes script to produce true/false prediction. Like tool_nodejs but enforces bool output. Must have script field.
-- Runtime: agent/runner
-- Inputs: 0. `prev`:node; 1. `value`:text
-- Outputs: 0. `next`:node; 1. `prediction`:bool
+- Display: Run
+- Description: Workspace 图的运行入口。点击运行时，从本节点出发沿控制边选出子图并执行；本节点自身不产生输出。
+- Runtime: local-only
+- Inputs: 0. `prev`:node
+- Outputs: 0. `next`:node
 
-### control_wait_until
+### workspace_scheduled_run
 
-- Display: WaitUntil
-- Description: Persistently wait until an absolute time, then continue when scheduler resumes this run.
+- Display: Scheduled Run
+- Description: 定时运行入口。与 Run 相同的执行语义，区别是由调度器按节点 body 中的 JSON 排程配置触发。
 - Runtime: local-only
-- Inputs: 0. `prev`:node; 1. `until`:text; 2. `timezone`:text = Asia/Shanghai
-- Outputs: 0. `next`:node; 1. `wakeAt`:text
+- Inputs: 0. `prev`:node
+- Outputs: 0. `next`:node
 
 ## tool
 
-### tool_get_env
+### tool_display_share_link
 
-- Display: GetEnv
-- Description: Get environment variable value
-- Runtime: agent/runner
-- Inputs: 0. `key`:text
-- Outputs: 0. `value`:text
+- Display: Display Share Link
+- Description: Create a public share link for upstream Display nodes
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `title`:text; 2. `layout`:text = single; 3. `nodeIds`:text; 4. `baseUrl`:text
+- Outputs: 0. `next`:node; 1. `url`:text; 2. `shareId`:text; 3. `expiresAt`:text
 
 ### tool_git_checkout
 
 - Display: Git Checkout
-- Description: Clone or update a Git repository and expose it as a workspace context for downstream nodes. - `repoUrl` is required. - `targetDir` may be absolute or relative to the current workspace context. - If `targetDir` is empty, the repository is cloned into `${pipelineWorkspace}/.workspace/agentflow/git-repos/<repo-name>`. - Set `includeSubmodules` to `true` to clone/update Git submodules recursively. - The `workspaceContext` output can be connected to CD Workspace, Load Skills, agent, or tool nodes.
+- Description: Clone or update a Git repository and expose it as a workspace context for downstream nodes. - `repoUrl` is required. - `targetDir` may be absolute or relative to the current workspace context. - If `targetDir` is empty, the repository is cloned into `${pipelineWorkspace}/.workspace/agentflow/git-repos/<repo-name>`. For user pipelines, `${pipelineWorkspace}` follows the Admin Settings AgentFlow Data Root. - Set `includeSubmodules` to `true` to clone/update Git submodules recursively. - The `workspaceContext` output can be connected to CD Workspace, Load Skills, agent, or tool nodes. - The `gitContext` output can be connected to Worktree, GitLab MR, or other Git nodes.
 - Runtime: local-only
-- Inputs: 0. `prev`:node; 1. `repoUrl`:text; 2. `branch`:text; 3. `targetDir`:text; 4. `pullIfExists`:bool = true; 5. `includeSubmodules`:bool = false; 6. `workspaceContext`:text
-- Outputs: 0. `next`:node; 1. `repoPath`:file; 2. `branch`:text; 3. `commit`:text; 4. `changed`:bool; 5. `workspaceContext`:text
+- Inputs: 0. `prev`:node; 1. `repoUrl`:text; 2. `branch`:text; 3. `targetDir`:text; 4. `pullIfExists`:bool = true; 5. `includeSubmodules`:bool = false; 6. `remote`:text = origin; 7. `workspaceContext`:text
+- Outputs: 0. `next`:node; 1. `repoPath`:file; 2. `branch`:text; 3. `commit`:text; 4. `changed`:bool; 5. `workspaceContext`:text; 6. `gitContext`:text
 
-### tool_load_key
+### tool_git_worktree_load
 
-- Display: LoadKey
-- Description: Load key-value from global storage
-- Runtime: agent/runner
-- Inputs: 0. `prev`:node; 1. `key`:text
-- Outputs: 0. `next`:node; 1. `result`:text
+- Display: Load Worktree
+- Description: Create or reuse a Git worktree and expose it as the downstream workspace context. - `repoPath` is required unless `gitContext.repoPath` is connected. - `workspaceContext` is required so the node can preserve the previous execution context. - `branch` is optional. When empty, AgentFlow creates a detached worktree at the current HEAD. - `worktreePath` is optional. When empty, AgentFlow creates a temporary worktree under the current run temp directory. - A worktree created by this node during the current Workspace run is removed when the run finishes or is stopped, even when `worktreePath` is explicitly set. - Existing registered worktrees under the current flow workspace are also removed after the run, covering leftovers from previous interrupted runs. - Existing registered worktrees outside the current flow workspace are reused and not removed automatically unless this run created them. - Existing worktree paths are reused only when they are registered by `git worktree list` for the given repo. - `pruneMissing` defaults to true. When Git has a registered worktree whose directory is missing, AgentFlow runs `git worktree prune` before adding it again. - `force` defaults to false. When true, AgentFlow passes `--force` to `git worktree add`.
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `repoPath`:file; 2. `branch`:text; 3. `worktreePath`:file; 4. `pruneMissing`:bool = true; 5. `force`:bool = false; 6. `gitContext`:text; 7. `workspaceContext`:text
+- Outputs: 0. `next`:node; 1. `worktreePath`:file; 2. `branch`:text; 3. `commit`:text; 4. `workspaceContext`:text; 5. `gitContext`:text
+
+### tool_git_worktree_unload
+
+- Display: Unload Worktree
+- Description: Remove a Git worktree. - `workspaceContext` is required. Its `cwd` is used as the worktree to remove. - `repoPath`, `worktreePath` and `gitContext` are optional compatibility overrides. - By default `force` is false; dirty worktrees fail instead of being removed. - By default `prune` is true.
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `repoPath`:file; 2. `worktreePath`:file; 3. `gitContext`:text; 4. `workspaceContext`:text; 5. `force`:bool = false; 6. `prune`:bool = true
+- Outputs: 0. `next`:node; 1. `removed`:bool; 2. `workspaceContext`:text; 3. `message`:text
+
+### tool_gitlab_create_mr
+
+- Display: Create GitLab MR
+- Description: Create or reuse a GitLab merge request for the current branch. - `gitContext` and `workspaceContext` can be connected from Git Checkout / Load Worktree. - `repoPath` is optional. When empty, AgentFlow uses `gitContext.worktreePath`, `gitContext.repoPath`, or `workspaceContext.cwd`. - `sourceBranch`, `targetBranch`, `title`, `description`, `draft`, and `labels` are optional. When empty, AgentFlow derives sensible defaults from git. - `tokenEnv` is optional. Defaults to `GITLAB_TOKEN,GITLAB_PRIVATE_TOKEN`. - `gitlabApiBase` is optional. When empty, AgentFlow uses `https://${gitContext.host}/api/v4`.
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `repoPath`:file; 2. `gitContext`:text; 3. `workspaceContext`:text; 4. `sourceBranch`:text; 5. `targetBranch`:text; 6. `title`:text; 7. `description`:text; 8. `draft`:bool = false; 9. `labels`:text; 10. `push`:bool = true; 11. `remote`:text = origin; 12. `tokenEnv`:text; 13. `gitlabApiBase`:text; 14. `removeSourceBranch`:bool = false; 15. `squash`:bool = false
+- Outputs: 0. `next`:node; 1. `mrUrl`:text; 2. `created`:bool; 3. `mrIid`:text; 4. `projectId`:text; 5. `sourceBranch`:text; 6. `targetBranch`:text; 7. `title`:text; 8. `message`:text
 
 ### tool_nodejs
 
 - Display: NodeJs
-- Description: Execute Node.js script via agentflow apply -ai run-tool-nodejs. **Success/Failure:** Determined by script process **exit code**—0 = success, non-0 = failed. **Result Output:** Script stdout directly becomes result slot content (plain text, e.g., `console.log("hello")`). When stdout is empty and exit code is non-0, stderr info will be written to failure message. **JSON Compatible (Optional):** If stdout is `{"err_code":0,"message":{"result":"..."}}` format, err_code will override exit code semantics, message.result writes to result slot. Only use when needing different success/failure semantics than exit code. **Direct Execution Mode (Recommended):** Set `script` field in flow.yaml instance, pipeline will skip AI and execute directly. `script` supports ${} placeholders (workspaceRoot, pipelineWorkspace, flowName, runDir, flowDir and all input/output slots), values are auto shell-quoted. When a CD Workspace node is connected, `workspaceRoot` is the current execution workspace; `pipelineWorkspace` is the original pipeline workspace. flowDir is absolute path of current pipeline flow.yaml directory, can be used to reference scripts in same directory. Example: `script: node ${flowDir}/scripts/my-check.mjs --root ${workspaceRoot} --input ${todo}` **Pin Path Constraint (Important):** File paths read/written by script **must be passed via pins**, forbidden to construct output paths inside script. - All input slots with type 'file' (e.g., `figma_tree`, `semantic_outline`) are parsed from upstream connections by pipeline, script receives via CLI args. - All output slots with type 'file' (e.g., `restore_todolist`, `screenshot_map`) are generated by pipeline as absolute paths following `output/<instanceId>/node_<instanceId>_<slot>.md` convention, script receives via CLI args and writes directly. - Use `${slotName}` in `script` field to get correct path, e.g., `--figma-tree ${figma_tree} --output ${restore_todolist}`. - **Forbidden** to use `outDirForNode`, manually write `node_<instance>_xxx.json` etc. in script—this causes script output path mismatch with pipeline parser convention, downstream nodes cannot find files. **AI Execution Mode (Legacy):** Without `script` field, AI agent reads body and manually executes commands. **Underlying Usage:** agentflow apply -ai run-tool-nodejs <workspaceRoot> <flowName> <uuid> <instanceId> [execId] -- <scriptCmd> [args...]
+- Description: Execute a Node.js script. The Workspace runtime spawns the command directly — no agent involved. **Success/Failure:** Determined by the script process **exit code** — 0 = success, non-0 = failed. **Result Output:** Script stdout becomes the `result` slot content (plain text, e.g. `console.log("hello")`). When stdout is empty and the exit code is non-0, stderr is written to the failure message. Do **not** wrap stdout in a JSON envelope. **Script placeholders:** `script` (inline) or `scriptRef` (file) support `${}` placeholders — `workspaceRoot` / `pipelineWorkspace` / `flowDir` (all three resolve to the scoped workspace root), `cwd`, `nodeRunDir`, `nodeTmpDir`, `outputsDir`, `scriptRef`, plus every input and output slot name. Values are auto shell-quoted, so do not add your own quotes. Example: `script: node ${flowDir}/scripts/my-check.mjs --root ${workspaceRoot} --input ${todo}` **Pin Path Constraint (Important):** File paths read/written by the script **must be passed via pins**; never construct output paths inside the script. - Input slots of type `file` are resolved from upstream connections; the script receives them as CLI args. - Output slots of type `file` are resolved to absolute paths by the runtime; the script writes to them directly. - Reference them with `${slotName}` in `script`, e.g. `--figma-tree ${figma_tree} --output ${restore_todolist}`. - **Forbidden** to invent output paths inside the script — downstream nodes will not find the files. **Scripts under `scripts/` must be referenced as `${flowDir}/scripts/xxx.mjs`.**
 - Runtime: direct script when script exists, otherwise agent
-- Inputs: 0. `prev`:node; 1. `workspaceContext`:text; 2. `skillsContext`:text
+- Inputs: 0. `prev`:node; 1. `workspaceContext`:text; 2. `skillsContext`:text; 3. `mcpContext`:text
 - Outputs: 0. `next`:node; 1. `result`:text
 
-### tool_print
+### tool_set_run_env
+
+- Display: Set Run Env
+- Description: Set environment variables for downstream nodes in the current workspace run
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `key`:text; 2. `value`:text; 3. `variables`:text
+- Outputs: 0. `next`:node; 1. `keys`:text; 2. `count`:text
+
+### tool_wecom_send_app_markdown
+
+- Display: WeCom Direct Markdown
+- Description: Send Markdown message to WeCom users through an enterprise application
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `markdown`:text; 2. `toUser`:text; 3. `corpId`:text; 4. `corpSecret`:text; 5. `agentId`:text; 6. `accessToken`:text
+- Outputs: 0. `next`:node; 1. `sent`:bool; 2. `message`:text; 3. `response`:text
+
+### tool_wecom_send_group_markdown
+
+- Display: WeCom Group Chat Markdown
+- Description: Send Markdown message to a WeCom group robot webhook
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `markdown`:text; 2. `webhookUrl`:text; 3. `webhookKey`:text
+- Outputs: 0. `next`:node; 1. `sent`:bool; 2. `message`:text; 3. `response`:text
+
+## display
+
+### display_ascii
 
-- Display: Print
-- Description: Output content to user with special font style
+- Display: ASCII Display
+- Description: Display ASCII diagram content in workspace canvas; passes diagram text downstream as text
 - Runtime: local-only
 - Inputs: 0. `prev`:node; 1. `content`:text
-- Outputs: 0. `next`:node
+- Outputs: 0. `content`:text; 1. `next`:node
 
-### tool_save_key
+### display_chart
 
-- Display: SaveKey
-- Description: Save key-value pair to global storage
-- Runtime: agent/runner
-- Inputs: 0. `prev`:node; 1. `key`:text; 2. `value`:text
-- Outputs: 0. `next`:node
+- Display: Chart Display
+- Description: Display a JSON ChartSpec with ECharts in workspace canvas; passes the JSON downstream as text
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `content`:text; 2. `filePath`:file; 3. `workspaceContext`:text
+- Outputs: 0. `content`:text; 1. `next`:node
 
-### tool_user_ask
+### display_html
 
-- Display: UserAsk
-- Description: 等待用户从多个选项中选择一个，流程暂停；按用户选择沿对应出边分支继续。每个 output 槽位对应一条分支，槽位的 description 作为选项文案。
+- Display: HTML Display
+- Description: Display HTML content in workspace canvas; passes HTML downstream as text
 - Runtime: local-only
-- Inputs: 0. `prev`:node; 1. `question`:file
-- Outputs: 0. `option_0`:node; 1. `option_1`:node
+- Inputs: 0. `prev`:node; 1. `content`:text; 2. `filePath`:file; 3. `workspaceContext`:text
+- Outputs: 0. `content`:text; 1. `next`:node
 
-### tool_user_check
+### display_image
 
-- Display: UserCheck
-- Description: 等待用户确认，流程暂停。展示确认内容给用户，用户可编辑/AI修改后保存，回复 "继续" 后重启流程。
+- Display: Image Display
+- Description: Display an image URL, data URL, or image path in workspace canvas; passes source downstream as text
 - Runtime: local-only
-- Inputs: 0. `prev`:node; 1. `content`:file
-- Outputs: 0. `next`:node; 1. `content`:file
+- Inputs: 0. `prev`:node; 1. `src`:text; 2. `filePath`:file; 3. `alt`:text; 4. `workspaceContext`:text
+- Outputs: 0. `src`:text; 1. `next`:node
+
+### display_markdown
+
+- Display: Markdown Display
+- Description: Display Markdown content in workspace canvas; passes content downstream as text
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `content`:text
+- Outputs: 0. `content`:text; 1. `next`:node
+
+### display_mermaid
+
+- Display: Mermaid Display
+- Description: Display Mermaid diagram source in workspace canvas; passes diagram source downstream as text
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `content`:text
+- Outputs: 0. `content`:text; 1. `next`:node
+
+### display_react_app
+
+- Display: React App
+- Description: Display a small React project in a sandboxed workspace iframe and pass the project JSON downstream
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `content`:text; 2. `filePath`:file; 3. `workspaceContext`:text
+- Outputs: 0. `content`:text; 1. `next`:node
+
+### display_table
+
+- Display: Table Display
+- Description: Display table data in workspace canvas; accepts JSON, Markdown table, CSV, or TSV and passes the text downstream
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `content`:text; 2. `filePath`:file; 3. `workspaceContext`:text
+- Outputs: 0. `content`:text; 1. `next`:node
 
 ## provide
 
+### provide_bool
+
+- Display: Boolean
+- Description: Provide a boolean value directly, value will be passed to downstream as true or false
+- Runtime: local-only
+- Inputs: 无
+- Outputs: 0. `value`:bool = false
+
 ### provide_file
 
 - Display: File
@@ -201,6 +244,14 @@
 - Inputs: 无
 - Outputs: 0. `value`:file
 
+### provide_password
+
+- Display: Password
+- Description: Provide a secret text value without showing it on the node card
+- Runtime: local-only
+- Inputs: 无
+- Outputs: 0. `value`:text
+
 ### provide_str
 
 - Display: String

package/skills/agentflow-runtime-reference/references/runtime.md

@@ -61,4 +61,4 @@ Important files:
 
 - Edge values are resolved by handle index.
 - File slots usually pass paths; text slots may read upstream output file content.
-- `tool_print.content` should receive the display text. If missing, `tool_print` may fallback to upstream result body.
+- `display_*.content` should receive the text to render. Pick the display type that matches the payload (`display_markdown`, `display_html`, `display_table`, `display_chart`, …).