npm - @fieldwangai/agentflow - Versions diffs - 0.1.29 → 0.1.31 - Mend

@fieldwangai/agentflow 0.1.29 → 0.1.31

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (69) hide show

package/agents/agentflow-node-executor-code.md +3 -2
package/agents/agentflow-node-executor-planning.md +3 -2
package/agents/agentflow-node-executor-requirement.md +3 -2
package/agents/agentflow-node-executor-test.md +3 -2
package/agents/agentflow-node-executor-ui.md +3 -2
package/agents/agentflow-node-executor.md +3 -2
package/agents/en/agentflow-node-executor.md +3 -2
package/agents/zh/agentflow-node-executor.md +3 -2
package/bin/lib/agent-runners.mjs +63 -14
package/bin/lib/api-runner.mjs +30 -4
package/bin/lib/apply.mjs +6 -5
package/bin/lib/auth.mjs +240 -0
package/bin/lib/catalog-agents.mjs +2 -2
package/bin/lib/catalog-flows.mjs +196 -17
package/bin/lib/composer-agent.mjs +22 -1
package/bin/lib/composer-skill-router.mjs +10 -78
package/bin/lib/flow-import.mjs +2 -2
package/bin/lib/flow-write.mjs +20 -20
package/bin/lib/help.mjs +2 -2
package/bin/lib/locales/en.json +29 -1
package/bin/lib/locales/zh.json +31 -3
package/bin/lib/main.mjs +6 -1
package/bin/lib/node-exec-context.mjs +5 -5
package/bin/lib/node-execute.mjs +15 -10
package/bin/lib/paths.mjs +69 -13
package/bin/lib/recent-runs.mjs +2 -2
package/bin/lib/run-node-statuses-from-disk.mjs +3 -3
package/bin/lib/runtime-context.mjs +225 -0
package/bin/lib/scheduler.mjs +42 -38
package/bin/lib/skill-registry.mjs +145 -0
package/bin/lib/ui-server.mjs +1517 -57
package/bin/lib/user-env.mjs +83 -0
package/bin/lib/workspace-tree.mjs +4 -3
package/bin/lib/workspace.mjs +9 -11
package/bin/pipeline/build-node-prompt.mjs +29 -4
package/bin/pipeline/get-env.mjs +5 -29
package/bin/pipeline/get-exec-id.mjs +2 -2
package/bin/pipeline/get-resolved-values.mjs +1 -0
package/bin/pipeline/pre-process-node.mjs +328 -6
package/bin/pipeline/run-tool-nodejs.mjs +7 -0
package/bin/pipeline/validate-flow.mjs +2 -0
package/builtin/nodes/agent_subAgent.md +12 -3
package/builtin/nodes/control_cd_workspace.md +45 -0
package/builtin/nodes/control_load_skills.md +50 -0
package/builtin/nodes/control_user_workspace.md +20 -0
package/builtin/nodes/display_ascii.md +22 -0
package/builtin/nodes/display_markdown.md +22 -0
package/builtin/nodes/display_mermaid.md +22 -0
package/builtin/nodes/tool_git_checkout.md +57 -0
package/builtin/nodes/tool_nodejs.md +8 -1
package/builtin/nodes/tool_print.md +4 -1
package/builtin/web-ui/dist/assets/index-BVWwQpvg.css +1 -0
package/builtin/web-ui/dist/assets/index-CvNy1n3f.js +197 -0
package/builtin/web-ui/dist/index.html +2 -2
package/package.json +1 -1
package/skills/agentflow-flow-recipes/SKILL.md +24 -0
package/skills/agentflow-flow-recipes/references/recipes.md +63 -0
package/skills/agentflow-node-reference/SKILL.md +25 -0
package/skills/agentflow-node-reference/references/builtin-nodes.md +210 -0
package/skills/agentflow-placeholder-reference/SKILL.md +24 -0
package/skills/agentflow-placeholder-reference/references/placeholders.md +20 -0
package/skills/agentflow-runtime-reference/SKILL.md +25 -0
package/skills/agentflow-runtime-reference/references/runtime.md +64 -0
package/skills/agentflow-workspace-ascii/SKILL.md +42 -0
package/skills/agentflow-workspace-graph/SKILL.md +67 -0
package/skills/agentflow-workspace-markdown/SKILL.md +44 -0
package/skills/agentflow-workspace-mermaid/SKILL.md +43 -0
package/builtin/web-ui/dist/assets/index-0vJxkTJz.css +0 -1
package/builtin/web-ui/dist/assets/index-h69bpxLI.js +0 -190

package/builtin/web-ui/dist/index.html CHANGED Viewed

@@ -15,8 +15,8 @@
       href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0,0"
       rel="stylesheet"
     />
-    <script type="module" crossorigin src="/assets/index-h69bpxLI.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-0vJxkTJz.css">
+    <script type="module" crossorigin src="/assets/index-CvNy1n3f.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BVWwQpvg.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@fieldwangai/agentflow",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "description": "Orchestration system for long-running complex agent tasks using Cursor, OpenCode, or Claude Code as execution backends",
   "type": "module",
   "main": "bin/agentflow.mjs",

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

@@ -0,0 +1,24 @@
+---
+name: agentflow-flow-recipes
+description: >-
+  AgentFlow 常见流程模板。用于新建 Git 项目分析、加载项目 skills、打印结果、
+  以及组合 Git Checkout → CD Workspace → Load Skills → Agent → Print 的标准流水线。
+---
+# AgentFlow Flow Recipes
+使用本技能处理这些问题：
+- 用户要求“新建流水线拉仓库、cd 进去、让 agent 分析、print 结果”。
+- 需要把 Git 项目作为工作区分析，并可加载项目自身 skills。
+- 需要避免临场猜 slot/handle，按标准 recipe 搭图。
+## 必读规则
+- 读 [recipes.md](references/recipes.md)。
+- Git 项目分析的标准链路是：`Start → Git Checkout → CD Workspace → Load Skills → Agent → Print → End`。
+- `tool_print.content` 应接 agent 输出内容；没有接 content 时才 fallback 打印上游 result。
+## Reference
+- [Flow recipes](references/recipes.md)

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

@@ -0,0 +1,63 @@
+# AgentFlow Flow Recipes
+## Git Project Analysis
+Use when the user asks to clone/pull a repository, enter it, ask an agent what it does, and print the result.
+Recommended graph:
+```text
+control_start
+  -> tool_git_checkout
+  -> control_cd_workspace
+  -> control_load_skills
+  -> agent_subAgent
+  -> tool_print
+  -> control_end
+```
+Minimum required values:
+- `tool_git_checkout.repoUrl`: repository URL.
+- `tool_git_checkout.pullIfExists`: `true`.
+- `tool_git_checkout.includeSubmodules`: `true` only when the user asks to pull submodules.
+- `control_cd_workspace.target`: `.`.
+- `control_load_skills.source`: `all` or `current-workspace`.
+- `agent_subAgent.body`: ask the agent to inspect README, package/build files, source directories, and entry points.
+- `tool_print.content`: connect from the agent output content.
+Required context edges:
+- Git Checkout `next` -> CD Workspace `prev`
+- Git Checkout `workspaceContext` -> CD Workspace `workspaceContext`
+- CD Workspace `next` -> Load Skills `prev`
+- CD Workspace `workspaceContext` -> Load Skills `workspaceContext`
+- Load Skills `next` -> Agent `prev`
+- CD Workspace `workspaceContext` -> Agent `workspaceContext`
+- Load Skills `skillsContext` -> Agent `skillsContext`
+- Agent content output -> Print `content`
+- Print `next` -> End `prev`
+Notes:
+- Do not connect `repoPath:file` to CD `target:text`.
+- If the agent node has no custom file output slot, use its result body and let Print fallback, or add a text/file output slot intentionally.
+- For private/internal Git repositories, local credentials must already work.
+## Edit Current Flow
+Use existing flow editing skills:
+- New nodes/edges: `agentflow-flow-add-instances`
+- Existing node text/value edits only: `agentflow-flow-edit-node-fields`
+- After saving in UI Composer: `agentflow-flow-sync-ui`
+## Print Result
+Prefer explicit content:
+```text
+agent.output.summary -> tool_print.input.content
+```
+Fallback behavior exists, but explicit content keeps the graph self-documenting.

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

@@ -0,0 +1,25 @@
+---
+name: agentflow-node-reference
+description: >-
+  AgentFlow 内置节点参考。用于选择节点类型、确认 builtin node 的 input/output 槽位、
+  判断 local-only/script/agent 执行方式，以及避免 handle 类型和顺序接错。
+---
+# AgentFlow Node Reference
+使用本技能处理这些问题：
+- 选择 `agent_subAgent`、`tool_nodejs`、`tool_git_checkout`、`control_cd_workspace`、`tool_print` 等节点。
+- 创建或修改 flow 时需要确认 input/output 名称、类型、顺序和 handle 索引。
+- 判断节点是否 local-only，是否会调用 agent，是否需要 `script`。
+## 必读规则
+- 先读 [builtin-nodes.md](references/builtin-nodes.md)，再改 `flow.yaml` 的 `definitionId`、`input`、`output` 或 `edges`。
+- `input-N` / `output-N` 必须与节点定义中的槽位顺序一致。
+- `tool_nodejs` 只有写了完整 `script` 才会确定性执行；自然语言任务用 `agent_subAgent`。
+- local-only 节点由 AgentFlow runtime 执行，不会调用 agent。
+## Reference
+- [Builtin nodes reference](references/builtin-nodes.md)

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

@@ -0,0 +1,210 @@
+# AgentFlow Builtin Nodes Reference
+> Generated from `builtin/nodes/*.md` by `scripts/generate-agentflow-skill-references.mjs`.
+## Rules Of Thumb
+- `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.
+- Edge handles are positional: `input-0`, `output-0`, etc. Match slot order exactly.
+## agent
+### agent_subAgent
+- Display: SubAgent
+- Description: 利用 SubAgent 执行任务；可接收 workspaceContext 切换执行工作区，并接收 skillsContext 注入已加载 skills。
+- 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
+### control_anyOne
+- Display: AnyOne
+- Description: Continues to next when any upstream input is ready
+- Runtime: agent/runner
+- Inputs: 0. `prev1`:node; 1. `prev2`:node
+- Outputs: 0. `next`:node
+### 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_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
+- Runtime: local-only
+- Inputs: 0. `prev`:node
+- Outputs: 无
+### control_if
+- Display: If
+- Description: Has exactly one bool type input. Continues to next1 if true, next2 if false
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `prediction`:bool
+- Outputs: 0. `next1`:node; 1. `next2`:node
+### control_interval_loop
+- Display: IntervalLoop
+- Description: Wait by interval and branch to continue, done, timeout, or cancelled for watch-style flows.
+- 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
+### 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`
+- 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
+### control_start
+- Display: Start
+- Description: Entry point of AgentFlow, all flows should start from this node
+- Runtime: local-only
+- Inputs: 无
+- Outputs: 0. `next`:node
+### control_toBool
+- 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
+### control_wait_until
+- Display: WaitUntil
+- Description: Persistently wait until an absolute time, then continue when scheduler resumes this run.
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `until`:text; 2. `timezone`:text = Asia/Shanghai
+- Outputs: 0. `next`:node; 1. `wakeAt`:text
+## tool
+### tool_get_env
+- Display: GetEnv
+- Description: Get environment variable value
+- Runtime: agent/runner
+- Inputs: 0. `key`:text
+- Outputs: 0. `value`: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.
+- 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
+### tool_load_key
+- 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
+### 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...]
+- Runtime: direct script when script exists, otherwise agent
+- Inputs: 0. `prev`:node; 1. `workspaceContext`:text; 2. `skillsContext`:text
+- Outputs: 0. `next`:node; 1. `result`:text
+### tool_print
+- Display: Print
+- Description: Output content to user with special font style
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `content`:text
+- Outputs: 0. `next`:node
+### tool_save_key
+- 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
+### tool_user_ask
+- Display: UserAsk
+- Description: 等待用户从多个选项中选择一个，流程暂停；按用户选择沿对应出边分支继续。每个 output 槽位对应一条分支，槽位的 description 作为选项文案。
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `question`:file
+- Outputs: 0. `option_0`:node; 1. `option_1`:node
+### tool_user_check
+- Display: UserCheck
+- Description: 等待用户确认，流程暂停。展示确认内容给用户，用户可编辑/AI修改后保存，回复 "继续" 后重启流程。
+- Runtime: local-only
+- Inputs: 0. `prev`:node; 1. `content`:file
+- Outputs: 0. `next`:node; 1. `content`:file
+## provide
+### provide_file
+- Display: File
+- Description: Provide file path or content directly, value will be passed to downstream as-is
+- Runtime: local-only
+- Inputs: 无
+- Outputs: 0. `value`:file
+### provide_str
+- Display: String
+- Description: Provide a text value directly, value will be passed to downstream as-is
+- Runtime: local-only
+- Inputs: 无
+- Outputs: 0. `value`:text

package/skills/agentflow-placeholder-reference/SKILL.md ADDED Viewed

@@ -0,0 +1,24 @@
+---
+name: agentflow-placeholder-reference
+description: >-
+  AgentFlow 占位符参考。用于编写 body/script 中的 ${workspaceRoot}、${pipelineWorkspace}、
+  ${flowDir}、${runDir}、${input.xxx}、${output.xxx} 等变量。
+---
+# AgentFlow Placeholder Reference
+使用本技能处理这些问题：
+- 编写或修复 `tool_nodejs.script`、agent body、节点默认值中的 `${...}`。
+- CD Workspace 后确认路径应该用 `workspaceRoot` 还是 `pipelineWorkspace`。
+- 解决脚本里路径多了一层引号、找不到 flow scripts、输出路径不对的问题。
+## 必读规则
+- 读 [placeholders.md](references/placeholders.md)。
+- 不要在 `script` 中给 `${workspaceRoot}` 这类占位符再包一层双引号；AgentFlow 会 shell-quote。
+- flow 自带脚本优先用 `${flowDir}/scripts/...`。
+## Reference
+- [Placeholder reference](references/placeholders.md)

package/skills/agentflow-placeholder-reference/references/placeholders.md ADDED Viewed

@@ -0,0 +1,20 @@
+# AgentFlow Placeholder Reference
+> Generated from `builtin/web-ui/src/bodyPlaceholders.js` by `scripts/generate-agentflow-skill-references.mjs`.
+## Runtime Placeholders
+- `${workspaceRoot}`: Current execution workspace. After CD Workspace, this is the target project workspace.
+- `${pipelineWorkspace}`: Original AgentFlow pipeline workspace. Use this to access pipeline-owned files after CD Workspace.
+- `${cwd}`: Alias-like current working directory for the runtime workspace context.
+- `${flowName}`: Current pipeline id/name.
+- `${runDir}`: Current run directory, relative to pipeline workspace.
+- `${flowDir}`: Absolute directory containing the current flow.yaml.
+## Slot Placeholders
+- `${input.<slotName>}`: input slot value by name.
+- `${output.<slotName>}`: output slot path by name.
+- `${<slotName>}`: shorthand for input or output slot when unambiguous.
+Do not wrap placeholders in extra quotes inside `script`; AgentFlow shell-quotes substituted values.

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

@@ -0,0 +1,25 @@
+---
+name: agentflow-runtime-reference
+description: >-
+  AgentFlow 运行时参考。用于理解 pipeline/workspace 目录、runBuild、
+  intermediate/output/result 文件、workspaceContext/skillsContext 传递和 CD Workspace 行为。
+---
+# AgentFlow Runtime Reference
+使用本技能处理这些问题：
+- 解释或调试 AgentFlow 运行目录和产物。
+- 设计 Git Checkout、CD Workspace、Load Skills、Agent、Print 的工作区切换链路。
+- 判断 `${workspaceRoot}` 与 `${pipelineWorkspace}` 在 CD Workspace 前后的差异。
+- 排查上游 output 文件、result.md、cache.json、skillsContext 没传到下游的问题。
+## 必读规则
+- 读 [runtime.md](references/runtime.md) 了解目录与上下文。
+- 下游 agent/tool 的当前执行目录由 `workspaceContext` 决定。
+- pipeline 自己的文件永远通过 `pipelineWorkspace` / `flowDir` 找，不要在 CD 后误用 `workspaceRoot`。
+## Reference
+- [Runtime reference](references/runtime.md)

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

@@ -0,0 +1,64 @@
+# AgentFlow Runtime Reference
+## Workspaces
+- `pipelineWorkspace`: the original workspace that owns the AgentFlow pipeline run.
+- `workspaceRoot`: current execution workspace. Before CD Workspace it is usually the pipeline workspace; after CD Workspace it becomes the selected project directory.
+- `cwd`: current runtime working directory, normally same as `workspaceRoot`.
+- `flowDir`: absolute directory containing the current `flow.yaml`.
+## Pipeline Locations
+- Builtin pipelines: `builtin/pipelines/<flowId>/flow.yaml`
+- Workspace pipelines: `.workspace/agentflow/pipelines/<flowId>/flow.yaml`
+- User pipelines: `~/agentflow/pipelines/<flowId>/flow.yaml`
+- Pipeline scripts: `<flowDir>/scripts/*`
+- Flow-local nodes: `<flowDir>/nodes/*.md`
+## Run Directory
+Each run writes under:
+```text
+<pipelineWorkspace>/.workspace/agentflow/runBuild/<flowName>/<uuid>/
+```
+Important files:
+- `intermediate/flow.json`: parsed graph snapshot.
+- `intermediate/<instanceId>/<instanceId>.prompt.md`: prompt used by a node.
+- `intermediate/<instanceId>/<instanceId>.result.md`: node status and result body.
+- `intermediate/<instanceId>/<instanceId>.cache.json`: cache metadata.
+- `output/<instanceId>/node_<instanceId>_<slot>.md`: output slot files.
+- `logs/log.txt`: run events and CLI logs.
+## Context Objects
+`workspaceContext` is a JSON text value passed between nodes:
+```json
+{
+  "version": 1,
+  "label": "workspace",
+  "cwd": "/abs/current/workspace",
+  "workspaceRoot": "/abs/current/workspace",
+  "pipelineWorkspace": "/abs/pipeline/workspace",
+  "flowDir": "/abs/flow/dir",
+  "previous": null
+}
+```
+`skillsContext` is a JSON text value generated by Load Skills and consumed by downstream agent/tool nodes. It contains selected skill metadata and loaded SKILL.md bodies.
+## Git / CD Behavior
+- `tool_git_checkout` outputs `workspaceContext` whose `workspaceRoot` is the checked-out repository path.
+- `control_cd_workspace` changes downstream execution workspace.
+- If Git Checkout is immediately followed by CD Workspace, connect `workspaceContext` and set CD `target` to `.`.
+- Do not connect `repoPath:file` to `target:text`; use `workspaceContext` instead.
+## Output Resolution
+- 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.

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

@@ -0,0 +1,42 @@
+---
+name: agentflow-workspace-ascii
+description: >-
+  AgentFlow Workspace ASCII 图展示技能。用于生成目录树、文本框图、流程草图等
+  等宽 ASCII 内容，并写入 display_ascii 节点的 workspace.graph.json。
+---
+# AgentFlow Workspace ASCII
+在 Workspace 视图中需要展示目录树、简洁结构图、文本框图或不适合 Mermaid 的草图时使用本技能。
+## 生成节点
+新增或更新 `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" }
+  ]
+}
+```
+`body`、`input.content.value`、`output.content.value` 使用同一份 ASCII 文本。
+## ASCII 规则
+- 只写纯文本 ASCII，避免 Unicode 线框字符，保证跨终端显示稳定。
+- 目录树使用 `|--`、`` `-- ``、`|   ` 缩进。
+- 框图尽量短行，避免超宽节点。
+## 布局建议
+- 默认宽度 640，高度 420。
+- 适合作为 Markdown 分析节点旁边的辅助图。

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

@@ -0,0 +1,67 @@
+---
+name: agentflow-workspace-graph
+description: >-
+  AgentFlow Workspace 画布编辑技能。用于在 Workspace 视图中创建或修改
+  workspace.graph.json，新增展示节点、上下文节点和连线；不修改正式 flow.yaml。
+---
+# AgentFlow Workspace Graph
+在 Workspace 视图中需要创建临时工作画布、保存分析结果、组织上下文节点或连接展示节点时使用本技能。
+## 目标文件
+优先修改当前 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 } }
+  }
+}
+```
+## 节点使用规则
+- 用 `display_markdown` 展示 Markdown 正文、分析报告、会议纪要、代码结构说明。
+- 用 `display_mermaid` 展示 Mermaid 图源码。
+- 用 `display_ascii` 展示 ASCII 图。
+- 用普通 pipeline 节点作为上下文节点时，保持 `instances` 结构与 flow.yaml instance 一致，但它只属于 workspace graph。
+- 每个新增 instance 必须有 `ui.nodePositions`。
+- 展示节点建议写 `ui.nodeSizes`，避免内容区域过小。
+## 连接语义
+展示节点的输入：
+- `input[0]` / `targetHandle: "input-0"`：node prev，用于连接上游上下文。
+- `input[1]`：text content，展示内容。
+展示节点的输出：
+- `output[0]` / `sourceHandle: "output-0"`：text content，可作为后续 agent 的上下文输入。
+## 输出要求
+当用户要求“生成/展示/放到 workspace 画布”时，直接编辑 `workspace.graph.json`。完成后简要说明新增或修改了哪些 workspace 节点。

package/skills/agentflow-workspace-markdown/SKILL.md ADDED Viewed

@@ -0,0 +1,44 @@
+---
+name: agentflow-workspace-markdown
+description: >-
+  AgentFlow Workspace Markdown 展示技能。用于把分析、总结、文档、代码结构说明
+  生成 display_markdown 节点并写入 workspace.graph.json，作为后续 agent 上下文。
+---
+# AgentFlow Workspace Markdown
+在 Workspace 视图中需要生成 Markdown 报告、说明文档、分析结果或总结卡片时使用本技能。
+## 生成节点
+新增或更新 `workspace.graph.json` 中的 `display_markdown` instance：
+```json
+{
+  "definitionId": "display_markdown",
+  "label": "项目结构分析",
+  "body": "# 项目结构分析\n\n...",
+  "input": [
+    { "type": "node", "name": "prev", "value": "" },
+    { "type": "text", "name": "content", "value": "# 项目结构分析\n\n..." }
+  ],
+  "output": [
+    { "type": "text", "name": "content", "value": "# 项目结构分析\n\n..." }
+  ]
+}
+```
+`body`、`input.content.value`、`output.content.value` 使用同一份 Markdown 内容。
+## 内容规范
+- 生成真正可展示的 Markdown，不要包在代码块里，除非用户要求展示原始 Markdown。
+- 表格必须使用标准 Markdown 表格：表头、分隔行、数据行各自独立成行。
+- Mermaid 内容不要放进 Markdown 节点；用 `display_mermaid`。
+- ASCII 图不要放进 Markdown 节点；用 `display_ascii`。
+## 布局建议
+- 默认宽度 760，高度 520。
+- 多个 Markdown 节点按从左到右、从上到下排布。
+- label 放短标题，正文放 body/content。