dsh-plugin-agentflow 0.3.1 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # AgentFlow · DSH 插件
 
-> 在 DeepSeek Harness 里用**画布**编排 agent 工作流，一键生成 DSH 预设 —— 每一步由你定义，而不是塞进一个黑盒循环。
+> 在 DeepSeek Harness 里用**画布**编排 agent 工作流，一键生成 `/命令` —— 每一步由你定义，而不是塞进一个黑盒循环。
 
 [![npm](https://img.shields.io/npm/v/dsh-plugin-agentflow?color=24543F&label=npm)](https://www.npmjs.com/package/dsh-plugin-agentflow)
 [![license](https://img.shields.io/badge/license-MIT-24543F)](./LICENSE)
@@ -12,12 +12,12 @@
 
 DSH 自带的 agent 是「一个模型 + 一堆工具」的循环，中间怎么想、调什么，你看不见也改不了。
 
-AgentFlow 把它掰开：**画布上的每张卡片就是一个 agent 步骤**。你决定有几步、谁先谁后、谁并行、每步用哪个模型、能不能调 MCP 工具、做完怎么验收。编排好之后导出成一个 DSH 预设，在对话里直接选中它。
+AgentFlow 把它掰开：**画布上的每张卡片就是一个 agent 步骤**。你决定有几步、谁先谁后、谁并行、每步用哪个模型、能不能调 MCP 工具、做完怎么验收。编排好之后把整张画布生成成一个 DSH 命令，在对话里输入 `/命令名` 就能用。
 
 - **节点**：LLM（调模型）/ MCP（直接调工具，不经过模型）/ 调度（根，对话入口）
 - **执行**：纯 DAG，无上游先跑、同层并行、失败不阻塞其它分支
 - **模型**：全部走 DSH 自己的模型通道（`ctx.llm`），推理强度和兜底模型可逐节点配
-- **预设**：根节点承载人格，导出时自动附上子节点清单，写进 DSH profile
+- **命令**：整张画布生成成 `/命令名`，插件热注册、即时生效，不写 DSH profile
 
 ## 安装
 
@@ -45,36 +45,92 @@ CC19990113/dsh-plugin-agentflow
 
 ![画布列表](docs/images/boards-list.png)
 
-每张画布对应一个 DSH 预设。卡片上会标出「对话入口」（哪张卡是和用户对话的根节点），改过画布但没更新预设时显示 **预设未更新**。
+每张画布可以生成一个 DSH 命令。卡片上会标出「对话入口」（哪张卡是和用户对话的根节点）。
 
 ### 2. 编排
 
 - 拖卡片改位置，从卡片边缘拖线连上下游
 - 点卡片改模型、推理强度、兜底模型、技能、MCP 工具
 - 「加下游 / 加上游」快速派生新卡
-- 编辑**自动保存**，点「保存」才会把你的编排**生成/覆盖成 DSH 预设**
+- 编辑**自动保存**，点「保存」把编排落库；点「生成命令」把画布变成 `/命令`
 
 ### 3. 验证
 
 顶栏「验证 AgentFlow」会真实跑一遍整张图（会消耗 token），用来看流程通不通。卡片上只显示配置摘要，不堆运行产出。
 
-### 4. 导出成预设
+### 4. 生成命令
 
-点「保存」（或 ⌘S）→ 画布落库 + 预设写入 `~/.dsh/profiles/<profile>/cordis.patch.yml`。重启 DSH 后，新会话的预设列表里就能选到它。
+点画布上的「生成命令」（或插件页 → 添加插件 →「从 AgentFlow 画布生成命令」，或设置页 AgentFlow 分区），得到 `/agentflow-<slug>`：
 
-预设长这样：
+- **生成即生效**：命令由插件热注册，无需重启 DSH，也不写 `~/.dsh/profiles/<profile>/cordis.patch.yml`
+- **命令名**：默认 `agentflow-<画布 slug>`；同名会覆盖
+- **落盘**：`<数据目录>/commands/<name>.json`，只存画布 id
+- **跟当前画布**：画布内联打开哪张，设置页/菜单就生成哪张（画布会通过 `agentflow-board-active` 事件回传当前 id）；没有回传时才退回索引第一张
 
+在对话输入框里：
+
+| 输入 | 行为 |
+|---|---|
+| `/agentflow-<slug>` | 只看画布：返回画布名、节点列表（label / 任务 / 上游）与用法，不消耗 token |
+| `/agentflow-<slug> 要做的事` | 进入该画布的工作流：你的话作为**入口节点（调度卡）的输入**，之后对话被画布 DAG 推着走 |
+| `/agentflow-<slug> off` | 退出该画布的工作流 |
+
+### 5. 输入命令之后，对话怎么走
+
+不是「把画布说明塞给模型让它自觉」，而是插件按 DAG 推进：
+
+1. 你的话进**根节点**（调度卡；优先认引擎的 `type: 'orchestrator'`），模型只做这个节点，做完必须调 `agentflow_node_done(node_id, output)`
+2. 插件校验（非空、≥10 字、前置已完成、只有发起这次工作流的 agent 能标记），通过后算下一层
+3. 这一层有几个节点，就**强制**为每个节点建一个 teammate：
+   - teammate 名由插件分配：`<节点id清洗>-<本次 run 的随机后缀>`。Agent Teams 的 roster 名字**永不复用**（实测连 DSH 重启后都还记着），所以每次 run 都换后缀；同一 run 内清洗撞名再加 `-2`
+   - `tools/pre-execute` 只放行这一套名字（报错里列出当前能派谁）
+   - 派发指令里带每个节点的任务、验收标准、上游产出摘要
+4. **非根节点必须先真的 spawn 过才能标完成**（`tools/post-execute` 观察到成功的 `spawn_teammate` 才算），所以模型没法自己把下游做完
+5. 每个 teammate 回报后，用它的实际产出去调 `agentflow_node_done`；一层全部完成才进下一层
+6. 全部完成 → 收束并给产出清单；连线成环 → 判定卡住并提示
+
+画布上给节点配的**模型 / 推理档 / 技能 / 工具**会写进派发指令（`spawn_teammate` 没法指定模型，所以是「按这套配置干活」的提示，不是强制）；`type: mcp` 的节点在命令模式暂不执行，指令末尾会明确列出「本次不执行：…」，不会静默吞掉。
+
+每一步都会注入一行进行态（已完成 / 已派发待回报 / 待派发）。模型想收工但还没派发时，`turn-stopping` 会在同一回合先催一次（同一个 turn 不重复刷），超过 120s 再补提醒。
+
+同一张画布**已有进行中的工作流**时，再输入 `/命令 文本` 会被拒绝（提示先 `off` 或等结束），不会静默覆盖。
+
+工作流状态会落到 `<数据目录>/runs/<会话>.json`：DSH 重启后能接着跑（恢复时会换新的 teammate 名重新派发，因为旧 teammate 已经不在）。`/命令 off` 除了退出，还会**中断已经派出去的 teammate**（需要装 Agent Teams；服务不在时只退出不中断）。
+
+teammate 名撞车（概率极低）会自动换名重试一次，并提示模型用新名字重新 spawn。
+
+指令有预算：规则永远先占位，用户输入/节点详情按剩余额度截断并提示「已截断」。没有任务（或只有空白）的占位节点自动跳过；整张画布没有可执行节点时直接判结束，不会留一个永远不动的 run。
+
+> 前提：Agent Teams（`spawn_teammate` 等工具）要在 profile 里；没装时命令仍可用，只是派发那一层会停在对话里，由你手动推进。
+
+### 6. 想跑多层 / 多节点：先调 teammate 名额
+
+画布上**每个节点都会建一个 teammate**，所以节点多、层数深的画布会很快撞上限。默认上限不是代码里的 16，而是被 profile bundle 压到 **8**：
+
+| 层 | 值 | 位置 |
+|---|---|---|
+| 主包默认 | `DEFAULT_MAX_MEMBERS = 16` | `@deepseek-ai/dsh-experimental-agent-team/lib/index.js` |
+| bundle 覆写 | `maxMembers: 8` | `@deepseek-ai/dsh-experimental-agent-team-profile/cordis.patch.yml` |
+| desktop profile | bundles 里挂了这个 bundle | `~/.dsh/profiles/desktop/package.json` |
+
+要开大，在**自己的 profile** `cordis.patch.yml` 末尾追加同 id 覆写（`<profile>` 换成你的，桌面版是 `desktop`）：
+
+```yaml
+- id: agent-team
+  config:
+    maxMembers: 32
+    maxTasks: 256
+    maxMessageBytes: 65536
+    disposalTimeoutMs: 5000
 ```
-你是「AgentFlow」的对话入口。
-你只负责和用户对话：问清需求、确认关键信息。
-需求明确后，严格按照后续节点的 AgentFlow 流去执行，不要自己直接产出结果。
-
-【完成标准】…
-【子节点】共 4 个
-- 大纲：根据给定的题材，写一个三幕剧的简要大纲
-- 对白版：为关键场景写几句有张力的对白
-…
-```
+
+三个坑：
+
+1. **config 是整体替换、不深合并**（`dsh-app-boot` 原文 "config is replaced wholesale, not deep-merged"）。只写 `maxMembers` 会把其余键打回 schema 默认，所以四个键必须写全（后三个与 bundle 原值一致）。
+2. **必须重启 DSH**：`TeamService` 在构造时读 config，热改不生效。
+3. **注意内存**：每个 teammate 都是独立 agent（自己的会话与上下文），十几个同时活着时内存和 token 都明显上涨；32 已接近 24 GB 机器的实际承受力。另外名额**用完不回收**——Agent Teams 的成员名永不复用，所以一次 App 会话里能建的 teammate 总数是有上限的，宽画布建议拆小或分层跑。
+
+画布删掉时对应命令文件会被一起清掉（不再注册也不会留死文件）；配置 `commands: false` 可关掉注册（只生成不挂命令）。历史遗留的预设不再生成，插件设置页只留「旧预设清理」用于删除 profile 里的旧行。
 
 ## 深色模式
 
@@ -107,16 +163,34 @@ DSH 桌面
 |---|---|---|
 | 数据目录 | `~/.dsh/agent-flow-data` | 首次启动会自动从 `~/.dsh/agent-flow/data` 迁移 |
 | 后端端口 | `8791` | 可用 `agentflowPort` 插件配置改 |
-| 预设 profile | `desktop` | 用环境变量 `AGENTFLOW_PROFILE` 指定别的 profile |
+| 旧预设 profile | `desktop` | 读/删历史预设（`/api/presets`）用；可用环境变量 `AGENTFLOW_PROFILE` 指定别的 profile |
+| `commands` | `true` | 是否把 `<数据目录>/commands/*.json` 注册成对话命令；关闭则只生成不注册 |
 | `agentflowRenderMode` | `native` | 画布渲染方式：`native` 把画布编进客户端 bundle 直接渲染；`iframe` 回滚到嵌入独立画布页面 |
 | `agentflowUrl` | `http://127.0.0.1:8791` | `native` 下作为 API 基地址；`iframe` 下作为画布页面地址 |
+| `observe` | `true` | 观察器：只记每一步的消息形状与每次工具调用，不拦不改 |
+| `observeDir` | `<数据目录>/observe` | 观察日志落盘目录 |
+
+## 观察器
+
+`observe` 打开时，插件挂在 `agent/pre-step`、`tools/post-execute`、`agent/turn-stopping` 三个钩子上，
+把每个 agent 的一次对话记成 `<observeDir>/<session>.jsonl`，一行一个事件（工具耗时取自 `tools/execute` 的真实执行时间）：
+
+| `t` | 字段 | 说明 |
+|---|---|---|
+| `step` | `turn` `step` `msgs[]` `decision{}` | 这一步进了哪些消息（只记 `source.kind` / `form` / 字符数，不存正文）、最终决策是 `enter` 还是 `reject` |
+| `tool` | `turn` `step` `name` `args` `ms` `isError` `text` | 每一次工具调用；被 `pre-execute` deny 的也会出现，`isError` 为真 |
+| `stop` | `turn` | 模型认为自己干完了（`turn-stopping`）的地方 |
+
+用途：在做「强制工作流」之前，先看清模型实际怎么调工具、在哪收工、被拒之后怎么反应。
+纪律：写盘 fire-and-forget，任何异常只 `warn`——观察器坏了不能连累对话。
 
 ## 限制
 
 - **只在 macOS 上验证过**，Windows 的路径与命令未测
+- teammate 名额默认 8（bundle 覆写），宽画布先按 §6 调大；名额用完不回收，重启 DSH 才重置
 - 运行态是全局的：跑图时切换画布，事件会被丢弃；「停止」不分画布
 - 验证跑图会真实调用模型，注意 token 消耗
-- 预设依赖 DSH profile 的 patch 机制，profile 结构变了要跟着调整
+- 命令只注册已存在的画布：画布删了，对应命令下次扫描时自动消失
 - 宿主客户端运行时是 **React 18**；画布源码来自 React 19，但只使用两者共有的 API（不用 19-only API）
 - 画布样式靠 `.af-canvas` 作用域隔离（Tailwind 的 `:root` 变量收进容器内），不污染宿主页面
 - **`npm run sync` 会清空重建 `src/canvas/`**：为内联渲染做的适配改动会被引擎源码覆盖，改完需要重做
@@ -127,10 +201,11 @@ DSH 桌面
 npm run build   # 构建客户端 bundle（lib/client.js，含画布）
 npm run sync    # 从 ~/.dsh/agent-flow 同步引擎到 runtime/，并把画布源码同步到 src/canvas/
 npm run check   # 语法检查 + tsc --noEmit
-npm test        # 插件自测（152 项：bridge 83 + client bundle 69）
+npm test        # 插件自测（479 项：bridge 91 + client 86 + observe 28 + commands 150 + flow 124）
+npm run observe # 把观察日志读成时间线（默认 ~/.dsh/agent-flow-data/observe）
 ```
 
-引擎侧测试在 `~/.dsh/agent-flow/test`（85 项）。
+引擎侧测试在 `~/.dsh/agent-flow/test`（72 项）。
 
 ## 发布
 

package/cordis.patch.yml

@@ -6,190 +6,3 @@
 - insert:
     - id: agentflow
       name: 'dsh-plugin-agentflow'
-
-# >>> AgentFlow 预设（自动生成，重新导出会整体替换这段）
-# 本文件由 AgentFlow 自动生成，请勿手改 —— 重新生成会整体覆盖。
-# 来源画布：《AgentFlow》（id: demo）
-# 生成器：~/.dsh/agent-flow/preset-gen.mjs
-# 注意：delegation 组里的 tool-subagent 是分层下发子 agent 的唯一途径，不要删。
-
-- insert:
-  - id: preset-flow-agentflow
-    name: '@deepseek-ai/dsh-agent-preset'
-    config:
-      id: flow-agentflow
-      name: 'AgentFlow'
-      description: '由 AgentFlow 画布《AgentFlow》生成：6 个节点 / 5 层'
-      order: 50
-      plugins:
-        - id: persona
-          name: '@deepseek-ai/dsh-persona'
-          config:
-            prefix: |-
-              你是一个按固定流程组织子 agent 的调度者。
-
-              【你是谁】
-              你是「AgentFlow」。
-              这个流程共 6 个节点、5 层：大纲 → 对白版 / 下游卡片 → 人物版 → 合并 → 下游卡片。
-
-              【第一步：对齐需求】
-              动手前必须先把需求问清楚，最多问 3 个问题、一次问完：
-              - 这次的题材（主题）是什么？
-              - 期望的篇幅大概多少？
-              - 主要人物有哪些已有设定？
-              信息够了就说「开始执行」，不要边问边跑。
-
-              【流程】
-              第 1 层（串行）
-                ▸ 大纲 —— 根据给定的题材，写一个三幕剧的简要大纲，每幕两三句话用修仙类的。11
-                  完成标准：三幕结构清晰，每幕有一个明确转折.
-                  用模型：deepseek-flash
-                  参考技能：caveman、grill-me
-
-              第 2 层（并行，两个同时下发）
-                ▸ 对白版 —— 基于大纲，为关键场景写几句有张力的对白。
-                  完成标准：对白有潜台词，不要直白解释情绪
-                  用模型：deepseek-flash
-
-                ▸ 下游卡片
-                  完成标准：（未填写）
-                  用模型：deepseek-flash
-
-              第 3 层（等第 2 层全部完成）
-                ▸ 人物版 —— 基于大纲，塑造主要人物的动机与成长弧线。
-                  完成标准：主角有明确欲望、阻碍与转变
-                  用模型：deepseek-flash
-
-              第 4 层（等第 3 层全部完成）
-                ▸ 合并 —— 把两份材料合并成一份完整的三幕剧梗概，约 300 字。
-                  完成标准：读起来是一个连贯故事，不是拼接
-                  用模型：deepseek-flash
-
-              第 5 层（独立节点，可单独下发）
-                ▸ 下游卡片
-                  完成标准：（未填写）
-                  用模型：deepseek-flash
-
-              【怎么下发】
-              - 每个节点用一次 `subagent` 工具；prompt 里给全：任务 + 完成标准 + 上游产出
-              - 同一层的多个节点同时下发，不要一个个等
-              - 上游产出原样传给下游，不要自己改写或概括
-              - 子 agent 如果还有自己的子任务，把它的子任务一并写进它的 prompt，让它继续嵌套
-
-              【收尾】
-              全部跑完，把最终产出交给用户。中间有节点失败要说清楚是哪个、为什么，不要假装成功。
-        - id: agent-instructions
-          name: '@deepseek-ai/dsh-agent-instructions'
-          config:
-            maxBytes: 65536
-        - id: time-context
-          name: '@deepseek-ai/dsh-time-context'
-        - id: tool-bash
-          name: '@deepseek-ai/dsh-tool-bash'
-          disabled: !!js process.platform === 'win32'
-        - id: tool-pwsh
-          name: '@deepseek-ai/dsh-tool-pwsh'
-          disabled: !!js process.platform !== 'win32'
-        - id: tool-fs
-          name: '@deepseek-ai/dsh-tool-fs'
-        - id: tool-fs-search
-          name: '@deepseek-ai/dsh-tool-fs-search'
-          config:
-            sampleOverCapGlobResults: false
-        - id: tool-jobs
-          name: '@deepseek-ai/dsh-tool-jobs'
-        - id: tool-schedule
-          name: '@deepseek-ai/dsh-tool-schedule'
-        - id: skill-filesystem
-          name: '@deepseek-ai/dsh-skill-filesystem'
-        - id: tool-skill
-          name: '@deepseek-ai/dsh-tool-skill'
-        - id: command-goal
-          name: '@deepseek-ai/dsh-command-goal'
-        - id: tool-goal
-          name: '@deepseek-ai/dsh-tool-goal'
-        - id: planning
-          name: cordis:group
-          group: true
-          isolate:
-            planMode: true
-          config:
-            - id: plan-mode
-              name: '@deepseek-ai/dsh-plan-mode'
-              config:
-                section: |
-                  You are in plan mode. Stay in plan mode until the user approves your plan through exit_plan_mode or switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
-
-                  Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
-
-                  The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
-
-                  Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
-
-                  Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
-
-                  When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
-        - id: compaction
-          name: cordis:group
-          group: true
-          isolate:
-            compaction: true
-            toolResultPruner: true
-          config:
-            - id: compaction-basic
-              name: '@deepseek-ai/dsh-compaction-basic'
-            - id: command-compact
-              name: '@deepseek-ai/dsh-command-compact'
-            - id: tool-result-pruner
-              name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
-              config:
-                thresholdChars: 8192
-                headChars: 4096
-                tailChars: 1024
-        - id: delegation
-          name: cordis:group
-          group: true
-          isolate:
-            workflowEngine: true
-          config:
-            - id: tool-subagent-control
-              name: '@deepseek-ai/dsh-tool-subagent-control'
-            - id: tool-subagent-list-agents
-              name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
-            - id: tool-subagent
-              name: '@deepseek-ai/dsh-tool-subagent'
-              config:
-                provider: spawn
-                toolName: subagent
-                modelSelectionSettings: true
-            - id: tool-subagent-fork
-              name: '@deepseek-ai/dsh-tool-subagent'
-              config:
-                provider: fork
-                toolName: subagent_fork
-            - id: workflow-ptc
-              name: '@deepseek-ai/dsh-workflow-ptc'
-              config:
-                provider: spawn
-            - id: tool-workflow
-              name: '@deepseek-ai/dsh-tool-workflow'
-        - id: tool-ask-user
-          name: '@deepseek-ai/dsh-tool-ask-user'
-        - id: tool-todo
-          name: '@deepseek-ai/dsh-tool-todo'
-          config:
-            allowParallelInProgress: true
-        - id: tool-web
-          name: '@deepseek-ai/dsh-tool-web'
-          config:
-            fetch: false
-            searchTimeoutMs: 60000
-        - id: present
-          name: '@deepseek-ai/dsh-tool-present'
-        - id: tool-plugin-manager
-          name: '@deepseek-ai/dsh-plugin-manager/tools'
-          disabled: true
-        - id: tool-plugin-market
-          name: '@deepseek-ai/dsh-plugin-market/tools'
-          disabled: true
-# <<< AgentFlow 预设结束

package/index.js

@@ -23,6 +23,8 @@ import { spawn } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { startBridge } from './lib/bridge.js';
+import { startObserver } from './lib/observe.js';
+import { startCommands, createNodeDoneTool } from './lib/commands.js';
 
 export const name = 'tool-agentflow';
 
@@ -300,6 +302,47 @@ export function apply(ctx, config = {}) {
   // 再用 ctx.llm 调模型；启动失败只 warn，模型通道不可用不影响两个工具加载。
   ctx.effect(() => startBridge(ctx, { dir: bridgeDir }), 'agentflow: bridge');
 
+  // 观察器（阶段 1）：只记每步消息与每次工具调用，不拦不改。
+  // 用来在真正做「强制工作流」之前，看清模型实际怎么调工具、在哪收工。
+  // `observe: false` 关掉；`observeDir` 换落盘目录。
+  if (config.observe !== false) {
+    const observeRoot =
+      typeof config.observeDir === 'string' && config.observeDir
+        ? path.resolve(config.observeDir)
+        : path.join(dataDir, 'observe');
+    ctx.effect(() => startObserver(ctx, { root: observeRoot }).dispose, 'agentflow: observe');
+  }
+
+  // 命令（阶段 2）：引擎侧在 <dataDir>/commands/ 下写命令文件，这里热注册成
+  // DSH 的 /agentflow-xxx。宿主没有 commands 服务时 startCommands 内部只 warn，
+  // 插件照常加载；`commands: false` 关掉。
+  let commandsApi = null;
+  if (config.commands !== false) {
+    ctx.effect(() => {
+      const api = startCommands(ctx, { dir, dataDir });
+      commandsApi = api;
+      return () => {
+        try {
+          api.dispose();
+        } finally {
+          if (commandsApi === api) commandsApi = null;
+        }
+      };
+    }, 'agentflow: commands');
+  }
+
+  // ---------- agentflow_node_done ----------
+  // 画布工作流的显式完成信号：工具全局注册，只有发起这次 run 的 agent 能调。
+  // 没有进行中的 run 时只回一句「当前没有工作流」，不报错。
+  ctx.tools.register(
+    createNodeDoneTool(
+      (agentId) => (commandsApi ? commandsApi.getRun(agentId) : null),
+      (agentId, run) => {
+        if (commandsApi && typeof commandsApi.persistRun === 'function') commandsApi.persistRun(agentId, run);
+      },
+    ),
+  );
+
   // ---------- agentflow_list ----------
   ctx.tools.register(
     defineTool({