@fieldwangai/agentflow 0.1.149 → 0.1.154

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-placeholder-reference/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: agentflow-placeholder-reference
 description: >-
-  AgentFlow 占位符参考。用于编写 body/script 中的 ${workspaceRoot}、${pipelineWorkspace}、
+  AgentFlow Workspace 节点占位符参考。用于编写 body/script 中的 ${workspaceRoot}、${pipelineWorkspace}、
   ${flowDir}、${runDir}、${input.xxx}、${output.xxx} 等变量。
 ---
 
@@ -17,7 +17,7 @@ description: >-
 
 - 读 [placeholders.md](references/placeholders.md)。
 - 不要在 `script` 中给 `${workspaceRoot}` 这类占位符再包一层双引号；AgentFlow 会 shell-quote。
-- flow 自带脚本优先用 `${flowDir}/scripts/...`。
+- Workspace 节点脚本优先使用 `${workspaceRoot}`；`${flowDir}` / `${pipelineWorkspace}` 仅兼容历史 Pipeline 资源。
 
 ## Reference
 

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

@@ -1,7 +1,7 @@
 ---
 name: agentflow-runtime-reference
 description: >-
-  AgentFlow 运行时参考。用于理解 pipeline/workspace 目录、runBuild、
+  AgentFlow Workspace 运行时参考。用于理解 workspace 图、runBuild、
   intermediate/output/result 文件、workspaceContext/skillsContext 传递和 CD Workspace 行为。
 ---
 
@@ -18,7 +18,7 @@ description: >-
 
 - 读 [runtime.md](references/runtime.md) 了解目录与上下文。
 - 下游 agent/tool 的当前执行目录由 `workspaceContext` 决定。
-- pipeline 自己的文件永远通过 `pipelineWorkspace` / `flowDir` 找，不要在 CD 后误用 `workspaceRoot`。
+- 新任务优先使用 Workspace 图和 `workspaceRoot`；历史 Pipeline 的 `pipelineWorkspace` / `flowDir` 仅用于迁移和审计。
 
 ## Reference
 

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`, …).

package/skills/agentflow-workspace-ascii/SKILL.md

@@ -2,7 +2,7 @@
 name: agentflow-workspace-ascii
 description: >-
   AgentFlow Workspace ASCII 图展示技能。用于生成目录树、文本框图、流程草图等
-  等宽 ASCII 内容，并写入 display_ascii 节点的 workspace.graph.json。
+  等宽 ASCII 内容，并写入 workspace.flow.js 的 display.ascii 节点。
 ---
 
 # AgentFlow Workspace ASCII
@@ -11,21 +11,14 @@ description: >-
 
 ## 生成节点
 
-新增或更新 `workspace.graph.json` 中的 `display_ascii` instance：
-
-```json
-{
-  "definitionId": "display_ascii",
-  "label": "目录树",
-  "body": "app/\n|-- src/\n|-- package.json",
-  "input": [
-    { "type": "node", "name": "prev", "value": "" },
-    { "type": "text", "name": "content", "value": "app/\n|-- src/\n|-- package.json" }
-  ],
-  "output": [
-    { "type": "text", "name": "content", "value": "app/\n|-- src/\n|-- package.json" }
-  ]
-}
+在 `workspace.flow.js` 里新增或更新一个 `display.ascii` 节点：
+
+```js
+const tree = display.ascii("目录树", {
+  content: `app/
+|-- src/
+|-- package.json`,
+});
 ```
 
 `body`、`input.content.value`、`output.content.value` 使用同一份 ASCII 文本。

package/skills/agentflow-workspace-graph/SKILL.md

@@ -2,7 +2,7 @@
 name: agentflow-workspace-graph
 description: >-
   AgentFlow Workspace 画布编辑技能。用于在 Workspace 视图中创建或修改
-  workspace.graph.json，新增展示节点、上下文节点和连线；不修改正式 flow.yaml。
+  workspace.flow.js，新增展示节点、上下文节点和连线；不修改正式 flow.yaml。
 ---
 
 # AgentFlow Workspace Graph
@@ -11,61 +11,75 @@ description: >-
 
 ## 目标文件
 
-优先修改当前 pipeline 目录下的 `workspace.graph.json`。不要修改正式 `flow.yaml`，除非用户明确要求并且 UI 勾选允许修改 flow.yaml。
-
-`workspace.graph.json` 结构：
-
-```json
-{
-  "version": 1,
-  "instances": {
-    "node_id": {
-      "definitionId": "display_markdown",
-      "label": "标题",
-      "body": "展示内容",
-      "input": [
-        { "type": "node", "name": "prev", "value": "" },
-        { "type": "text", "name": "content", "value": "展示内容" }
-      ],
-      "output": [
-        { "type": "text", "name": "content", "value": "展示内容" }
-      ]
-    }
-  },
-  "edges": [
-    { "source": "a", "target": "b", "sourceHandle": "output-0", "targetHandle": "input-0" }
-  ],
-  "ui": {
-    "nodePositions": { "node_id": { "x": 320, "y": 180 } },
-    "nodeSizes": { "node_id": { "width": 760, "height": 520 } }
-  }
-}
+画布就是代码：改当前 Workspace 项目目录下的 **`workspace.flow.js`**。不要修改历史
+`flow.yaml`，也不要写 `workspace.graph.json`——那是已经退役的格式，写了不会被读。
+
+```
+workspace.flow.js      ← 改这个
+workspace.layout.json    坐标，平台维护，别碰
+workspace.nodes.json     图片等机器属性，平台维护，别碰
+workspace.state.json     运行产出，平台维护，别碰
+```
+
+坐标不用管：新节点平台会自动排布，写死坐标反而会覆盖用户调过的位置。
+
+## 写法
+
+```js
+import { agent, control, display, flow } from "agentflow/flow";
+
+const notes = display.markdown("项目结构分析", {
+  content: `# 项目结构分析
+
+- src/ 业务代码
+- bin/ CLI 入口`,
+});
+```
+
+| 位置 | 含义 |
+|------|------|
+| 第 1 个参数（字符串） | 节点显示名 |
+| 第 2 个参数（对象） | 输入引脚，每个键都是引脚名 |
+| 第 3 个参数（字符串） | body：agent 的 prompt、`tool.nodejs` 的命令 |
+| `const 变量名` | 节点 id |
+| `x.slotName` | 引用上游输出引脚 = 连一条数据线 |
+
+连线和控制流：
+
+```js
+const summary = agent.subAgent("总结", { source: notes.content }, `把上面的结构讲清楚`);
+const show    = display.markdown("总结", { content: summary.result });
+export const run = flow("Run", summary, show);
 ```
 
-## 节点使用规则
+只放一个展示节点、不需要跑的，不用写 `flow(...)`，声明出来就行。
 
-- 用 `display_markdown` 展示 Markdown 正文、分析报告、会议纪要、代码结构说明。
-- 用 `display_mermaid` 展示 Mermaid 图源码。
-- 用 `display_ascii` 展示 ASCII 图。
-- 用 `display_html` 展示可交互 HTML 原型或富 UI 片段。
-- 用 `display_image` 展示图片 URL、data URL 或图片路径。
-- 用 `display_chart` 展示 ChartSpec JSON 图表。
-- 用 `display_table` 展示结构化表格数据。
-- 用普通 pipeline 节点作为上下文节点时，保持 `instances` 结构与 flow.yaml instance 一致，但它只属于 workspace graph。
-- 每个新增 instance 必须有 `ui.nodePositions`。
-- 展示节点建议写 `ui.nodeSizes`，避免内容区域过小。
+## 铁律
 
-## 连接语义
+1. 节点全部声明在**模块顶层**
+2. **禁一切控制流**：`if` / `for` / `while` / `?:` / `.map()` / `await` / 箭头函数 /
+   动态属性。这个文件永不执行、只被静态解析，出现这些就还原不出图。要写逻辑就建代码
+   节点 `nodes/<name>/index.mjs`
+3. 一个输出可接多个输入；**一个输入只能接一条边**；不能成环
+4. 改完跑 `agentflow flow dsl lint <flowDir>` 自查
 
-展示节点的输入：
+完整语法和全部可用节点见 **agentflow-flow-dsl** skill。
 
-- `input[0]` / `targetHandle: "input-0"`：node prev，用于连接上游上下文。
-- `input[1]`：text content，展示内容。
+## 展示节点选型
 
-展示节点的输出：
+- `display.markdown` — Markdown 正文、分析报告、会议纪要、代码结构说明
+- `display.mermaid` — Mermaid 图源码
+- `display.ascii` — ASCII 图
+- `display.html` — 可交互 HTML 原型或富 UI 片段
+- `display.image` — 图片 URL、data URL 或图片路径
+- `display.chart` — ChartSpec JSON 图表
+- `display.table` — 结构化表格数据
 
-- `output[0]` / `sourceHandle: "output-0"`：text content，可作为后续 agent 的上下文输入。
+内容写在 `content` 引脚上；平台会同时把它当作节点正文。展示节点的 `content` 输出可以
+接给后续 agent 当上下文。
 
 ## 输出要求
 
-当用户要求“生成/展示/放到 workspace 画布”时，直接编辑 `workspace.graph.json`。完成后简要说明新增或修改了哪些 workspace 节点。
+用户要求「生成/展示/放到 workspace 画布」时，直接编辑 `workspace.flow.js`。需要所见即所得
+的线上画布，再用 `agentflow-cli workspace-preview --file <flowDir>` 上传到服务器临时
+Workspace；不要把临时项目当作正式源版本。完成后简要说明新增或修改了哪些节点。

package/skills/agentflow-workspace-html/SKILL.md

@@ -60,6 +60,11 @@ HTML 展示节点接收完整 HTML 文档或 HTML fragment：
 
 ## 节点写入
 
-新增或更新 `workspace.graph.json` 中的 `display_html` instance 时，`body`、`input.content.value`、`output.content.value` 使用同一份 HTML。
+在 `workspace.flow.js` 里写一个 `display.html` 节点，HTML 放 `content` 引脚：
 
-建议默认尺寸：宽 430-760，高 640-860，按原型复杂度调整。
+```js
+const proto = display.html("原型", { content: file("docs/proto.html") });
+```
+
+超过 3000 字符就像上面这样抽成 `docs/*.html`——整页 HTML 内联会把流程结构淹没。
+尺寸由平台维护，不要手写。

package/skills/agentflow-workspace-image/SKILL.md

@@ -47,6 +47,10 @@ description: >-
 
 ## 节点写入
 
-新增或更新 `workspace.graph.json` 中的 `display_image` instance 时，`body`、`input.src.value`、`output.src.value` 使用同一份图片 src。
+在 `workspace.flow.js` 里写一个 `display.image` 节点，图片地址放 `src` 引脚：
 
-建议默认尺寸：宽 520-760，高 420-680。
+```js
+const shot = display.image("截图", { src: "outputs/image.png" });
+```
+
+尺寸由平台维护，不要手写。