dsh-tree-task-flow 0.1.1 → 0.3.0

package/cordis.patch.yml

@@ -13,7 +13,7 @@
 #   enabled            总开关                          默认 false（装上 ≠ 启用）
 #   autoContinue       是否允许自动续行                默认 false（开着会让人停不下来）
 #   maxAutoRounds      连续自动续行轮次上限            默认 5
-#   promptOrder        静态说明段顺序                  默认 2000
+#   promptOrder        工具说明段顺序                  默认 1800
 #   rootDir            插件状态目录                    默认 $DSH_HOME/dsh-task-tree
 - insert:
     - id: task-tree

package/lib/auto-continue.js

@@ -9,10 +9,8 @@
  *
  * 三条安全阀缺一不可（方案 §7.1）：
  *
- * 1. **有活跃的内置 goal 时完全不插手**——不只是"别抢方向盘"。
- *    `dsh-goal-round-driver` 每推进一轮都设 `startsRequestSeries: true`，
- *    那会让系统提示词走归一化分支；节点 0 一旦被判定需要重写，
- *    整个上下文从第一个 token 起失去缓存。
+ * 1. **有活跃的内置 goal 时完全不插手**——内置 goal 由 `dsh-goal-round-driver`
+ *    自己推进轮次，插件再续一次就成了两套机制同时推同一个会话。
  * 2. **队列里还有人在等的时候绝不抢**：`inbox.nextTurn` / `nextStep` 非空就退出。
  * 3. **连续续行轮次有上限**，达到就停，避免把 token 烧在一个卡住的任务上。
  *
@@ -64,7 +62,7 @@ export function registerAutoContinue(ctx, { store, cfg }) {
     );
     if (fromHuman) {
       rounds.set(sessionId, 0);
-      // 人回来了，解除中断闸门，允许新一轮的续行。
+      // 人回来了，解除中断标记，允许新一轮的续行。
       stopped.delete(sessionId);
     }
     return decision;

package/lib/commands.js

@@ -2,12 +2,9 @@
  * `/task-tree` 斜杠命令：给人用的入口。
  *
  * 命令**不经过模型**——`handler` 直接执行、直接返回文本。所以它是查看和管理
- * 任务树最直接的方式，也是"把自动执行停下来"的那个开关：
+ * 任务树最直接的方式，也是"暂停自动执行"的那个开关：
  * 任务自动执行必须是**受控**的，人得有一句话就能接管的手段。
  *
- * 命令同时是**检查点的旁路**：检查点闸门只拦模型（`tools/pre-execute`），
- * 拦不住人。人在检查点里照样能提交结果、丢弃节点、或者把自动续行停掉。
- *
  * @module dsh-tree-task-flow/commands
  */
 
@@ -18,8 +15,8 @@ const USAGE = [
   "/task-tree                     查看本会话的任务树与检查点状态",
   "/task-tree done <id> <结果>     提交某个节点的结果并完成它",
   "/task-tree drop <id>           丢弃某个节点",
-  "/task-tree stop                停止本会话的自动续行",
-  "/task-tree resume              重新允许自动续行（需 config 里 autoContinue 为 true）",
+  "/task-tree pause               暂停：当前工具跑完后停住，不再往下推进",
+  "/task-tree resume              继续：从停住的地方接着跑，不插消息",
   "/task-tree reset               清掉本会话的计划树",
 ].join("\n");
 
@@ -29,7 +26,7 @@ const DISABLED_NOTE =
   "也不会折叠任何上下文。要启用请在 profile 的 cordis.patch.yml 里把 enabled 设为 true。";
 
 /**
- * 把检查点那句话拼出来。措辞与 `plan.js` 的检查点提示、`tools.js` 的闸门拒绝文案一致。
+ * 把检查点那句话拼出来。措辞与 `plan.js` 的检查点提示一致。
  *
  * @param checkpoint - `checkpointOf(plan)` 的结果。
  * @returns 两行文本。
@@ -38,8 +35,8 @@ function checkpointLines(checkpoint) {
   const label = levelLabel(checkpoint.level);
   return [
     `检查点：${label}「${checkpoint.node.title}」(${checkpoint.node.id}) 的子节点已全部结束。`,
-    `此刻只有两条路：tree_task_plan 继续给 ${checkpoint.node.id} 拆子节点，` +
-      `或者 tree_task_done(id="${checkpoint.node.id}", result="…") 提交这个${label}的结果并完成它。`,
+    `此刻轮到你的判断：用 tree_task_plan 继续给 ${checkpoint.node.id} 拆子节点，` +
+      `或者用 tree_task_done(id="${checkpoint.node.id}", result="…") 提交这个${label}的结果并完成它。`,
   ];
 }
 
@@ -47,10 +44,10 @@ function checkpointLines(checkpoint) {
  * 注册命令。
  *
  * @param ctx - 挂载本行的 Cordis 上下文。
- * @param options - `{ store, cfg, autoContinue, enabled }`；`autoContinue` 是
- *   `registerAutoContinue` 返回的控制接口，未启用时为 null。
+ * @param options - `{ store, cfg, pause, enabled }`；`pause` 是 `registerPause`
+ *   返回的控制接口，未启用时是 null。
  */
-export function registerCommands(ctx, { store, cfg, autoContinue, enabled = false }) {
+export function registerCommands(ctx, { store, cfg, pause = null, enabled = false }) {
   // 和 tools 一样，命令服务不是每个部署都有；用 get 探测而不是写进 inject。
   const commands = ctx.get?.("commands");
   if (commands === undefined || commands === null) {
@@ -60,8 +57,8 @@ export function registerCommands(ctx, { store, cfg, autoContinue, enabled = fals
 
   commands.register({
     name: "task-tree",
-    description: "查看与管理任务树：status / done <id> <结果> / drop <id> / stop / resume / reset",
-    input: { hint: "status | done <id> <结果> | drop <id> | stop | resume | reset" },
+    description: "查看与管理任务树：status / done <id> <结果> / drop <id> / pause / resume / reset",
+    input: { hint: "status | done <id> <结果> | drop <id> | pause | resume | reset" },
     handler: (invocation) => {
       const sessionId = invocation?.agent?.session?.id;
       if (sessionId === undefined) {
@@ -84,22 +81,25 @@ export function registerCommands(ctx, { store, cfg, autoContinue, enabled = fals
         };
       }
 
-      if (verb === "stop") {
-        autoContinue?.stop?.(sessionId);
+      // `stop` 是旧写法，含义与 `pause` 完全一样，留着免得习惯改不过来。
+      if (verb === "pause" || verb === "stop") {
+        pause?.pause?.(sessionId);
         return {
           kind: "success",
-          text: "已停止本会话的自动续行。任务树的进度没有变，随时可以继续。",
+          text:
+            "已暂停本会话：正在执行的那个工具会正常跑完，之后不再往下推进。" +
+            "任务树的进度没有变，点继续就从停住的地方接着跑。",
         };
       }
 
       if (verb === "resume") {
-        autoContinue?.resume?.(sessionId);
+        pause?.resume?.(sessionId);
         return {
           kind: "success",
           text:
             cfg.autoContinue === true
-              ? "已重新允许本会话自动续行。"
-              : "已解除中断标记，但配置里 autoContinue 是 false，所以仍然不会自动续行。",
+              ? "已继续：停在岔口上的那一步已经放行，自动续行也重新允许了。"
+              : "已继续：停在岔口上的那一步已经放行。配置里 autoContinue 是 false，所以模型自己停下后不会再被自动拉起。",
         };
       }
 

package/lib/http.js

@@ -1,26 +1,26 @@
 /**
- * 设置面板用的 HTTP 接口。
+ * 任务树条目用的 HTTP 接口。
  *
- * 面板跑在浏览器里，拿不到宿主内存中的 store，所以数据要经由这里出去。
+ * 条目跑在浏览器里，拿不到宿主内存中的 store，所以数据要经由这里出去。
  * 全部挂在 `/dsh-tree-task-flow/` 前缀下；只读写插件**自己的**状态目录，
  * 不碰会话日志（那是后端内部格式）。
  *
- * 面板要显示两样东西，都在这里算好给它：
+ * 条目要显示三样东西，都在这里算好给它：
  *
- *   - **每层的结果**：节点完成时提交的文本。面板不自己去挖计划树的深层结构，
+ *   - **每层的结果**：节点完成时提交的文本。条目不自己去挖计划树的深层结构，
  *     接口直接把三层各自的结果摆出来。
  *   - **检查点状态**：一个节点自己的子节点全部结束、而它自己还开着的那一刻。
  *     此刻只有两条路——继续拆子节点，或者提交结果并完成它。
+ *   - **暂停状态**：条目上的暂停/继续按钮写的就是这个。暂停挂的是
+ *     `agent/pre-step`（见 `pause.js`），不插消息、不改计划，所以它不属于计划树，
+ *     单独回传。
  *
- * 面板上的按钮都写计划树，所以写完要把**新的**活动路径、结果与检查点一并回传，
- * 免得面板还要再发一次请求才知道自己按出了什么效果。
+ * 条目上的按钮都写计划树，所以写完要把**新的**活动路径、结果与检查点一并回传，
+ * 免得条目还要再发一次请求才知道自己按出了什么效果。
  *
  * @module dsh-tree-task-flow/http
  */
 
-import { readdirSync } from "node:fs";
-import { join } from "node:path";
-
 import { activePath, checkpointOf, complete, dropNode, levelLabel } from "./plan.js";
 
 /** 统一的 JSON 响应。 */
@@ -97,63 +97,15 @@ function afterWrite(plan) {
   };
 }
 
-/** 列出状态目录里所有**有计划的会话**。 */
-function listSessions(store) {
-  let names = [];
-  try {
-    names = readdirSync(join(store.root, "plans"));
-  } catch {
-    return [];
-  }
-
-  const out = [];
-  for (const name of names) {
-    if (!name.endsWith(".json")) continue;
-    const sessionId = name.slice(0, -".json".length);
-    const plan = store.readPlan(sessionId);
-    if (plan === null) continue;
-    const steps = (plan.goal?.tasks ?? []).flatMap((task) => task.steps ?? []);
-    out.push({
-      sessionId,
-      goal: plan.goal?.title ?? "(未命名目标)",
-      status: plan.goal?.status ?? "pending",
-      updatedAt: plan.updatedAt ?? 0,
-      steps: steps.length,
-      done: steps.filter((step) => step.status === "done").length,
-      result: plan.goal?.result?.text ?? null,
-      checkpoint: checkpointInfo(plan),
-    });
-  }
-  out.sort((a, b) => b.updatedAt - a.updatedAt);
-  return out;
-}
-
 /**
  * 注册全部面板接口。
  *
  * @param ctx - 挂载本行的 Cordis 上下文。
- * @param options - `{ store, cfg, autoContinue }`。
+ * @param options - `{ store, autoContinue, pause }`；未启用时后两者是 null。
  */
-export function registerHttp(ctx, { store, cfg, autoContinue }) {
+export function registerHttp(ctx, { store, autoContinue, pause = null }) {
   ctx.inject(["webServer"], (host) => {
     host.effect(() => {
-      // 会话列表：面板顶部的下拉框。
-      host.webServer.register(
-        {
-          kind: "exact",
-          path: "/dsh-tree-task-flow/sessions",
-          handler: async (request, response) => {
-            if (request.method !== "GET") return sendJson(response, 405, { ok: false, error: "只支持 GET" });
-            sendJson(response, 200, {
-              ok: true,
-              enabled: cfg.enabled === true,
-              sessions: listSessions(store),
-            });
-          },
-        },
-        "dsh-tree-task-flow: sessions",
-      );
-
       // 一棵树的全部信息：结构 + 每层结果 + 检查点 + 当前路径 + 三层折叠游标。
       host.webServer.register(
         {
@@ -177,6 +129,7 @@ export function registerHttp(ctx, { store, cfg, autoContinue }) {
                 step: cursors.step ?? null,
               },
               stopped: autoContinue?.isStopped?.(sessionId) === true,
+              paused: pause?.isPaused?.(sessionId) === true,
             });
           },
         },
@@ -194,10 +147,13 @@ export function registerHttp(ctx, { store, cfg, autoContinue }) {
             const sessionId = String(body.sessionId ?? "");
             const action = String(body.action ?? "");
 
-            if (action === "stop" || action === "resume") {
-              autoContinue?.[action]?.(sessionId);
+            // 暂停 / 继续。暂停会同时压住自动续行兜底，两个状态一起回传，
+            // 免得条目还要再问一次。
+            if (action === "pause" || action === "resume") {
+              pause?.[action]?.(sessionId);
               return sendJson(response, 200, {
                 ok: true,
+                paused: pause?.isPaused?.(sessionId) === true,
                 stopped: autoContinue?.isStopped?.(sessionId) === true,
               });
             }

package/lib/index.js

@@ -5,7 +5,7 @@
  *
  * ```
  * 一个节点的上下文 =
- *     ① 节点 0：会话级稳定前缀（身份 / 工具 / 静态说明）   ← 永不变化
+ *     ① 节点 0：会话级稳定前缀（身份 / 工具 / 工具说明）   ← 不随计划变化
  *   + ② 这一层已有的汇总消息                                ← 同级逐条累积，不被卷走
  *   + ③ 当前节点的执行过程                                  ← 完成时整段折叠成一条汇总
  * ```
@@ -20,6 +20,7 @@
 import { registerAutoContinue } from "./auto-continue.js";
 import { registerCommands } from "./commands.js";
 import { registerHttp } from "./http.js";
+import { registerPause } from "./pause.js";
 import { DEFAULT_ORDER, registerPromptSection } from "./prompt.js";
 import { registerRegion } from "./region.js";
 import { createStore, defaultRoot } from "./store.js";
@@ -57,7 +58,7 @@ export const DEFAULT_CONFIG = {
   autoContinue: false,
   /** 连续自动续行的轮次上限，达到就停。 */
   maxAutoRounds: 5,
-  /** 静态说明段落的排序。 */
+  /** 工具说明段落的排序。 */
   promptOrder: DEFAULT_ORDER,
   /** 状态目录；null 表示 $DSH_HOME/dsh-task-tree。 */
   rootDir: null,
@@ -77,20 +78,21 @@ export function apply(ctx, config) {
   // 总开关默认**关**。未启用时一个字节都不碰会话：不注册工具、不加提示词段落、
   // 不折叠上下文、不续行——只留一条命令，让人能确认"装了但没开"以及怎么开。
   if (cfg.enabled !== true) {
-    registerCommands(ctx, { store, cfg, autoContinue: null, enabled: false });
-    // 面板接口照挂：设置页要能显示"装了但没启用"以及启用后的影响。
-    // 只读自己的状态目录，不碰任何会话。
-    registerHttp(ctx, { store, cfg, autoContinue: null });
+    registerCommands(ctx, { store, cfg, pause: null, enabled: false });
+    // 条目接口照挂：客户端条目与 enabled 无关，照样会来读。读不到计划它就返回
+    // null，一个像素都不占；而既有的计划文件仍然能看到。
+    // 只读插件自己的状态目录，不碰任何会话。
+    registerHttp(ctx, { store, autoContinue: null, pause: null });
     ctx.logger?.warn?.(
       "dsh-tree-task-flow: 已装载但**未启用**（enabled=false）。要启用请在 profile 的 cordis.patch.yml 里设为 true。",
     );
     return;
   }
 
-  // 静态说明段。必须包在 effect 里，否则热更新后会重复注册而抛错。
+  // 工具说明段。必须包在 effect 里，否则热更新后会重复注册而抛错。
   ctx.effect(registerPromptSection(ctx, cfg.promptOrder), "dsh-tree-task-flow.section");
 
-  // 六个工具，以及检查点上的工具闸门。tools 已在 inject 里声明，这里必定就绪。
+  // 六个工具。tools 已在 inject 里声明，这里必定就绪。
   registerTools(ctx, { store, cfg });
 
   // 节点完成时把它的执行过程折叠成一条携带结果的汇总消息。
@@ -100,11 +102,15 @@ export function apply(ctx, config) {
   // 让人随时能一句话停下来。
   const autoContinue = registerAutoContinue(ctx, { store, cfg });
 
-  // /task-tree 命令：查看与管理任务树，也是"停止自动执行"的开关。
-  registerCommands(ctx, { store, cfg, autoContinue, enabled: true });
+  // 暂停闸门：挂在 `agent/pre-step` 上，人点暂停就停在"上一个工具跑完、
+  // 下一次模型请求还没发出"那个岔口。它同时压住上面的自动续行兜底。
+  const pause = registerPause(ctx, { autoContinue });
 
-  // 任务树条目与设置页要用的 HTTP 接口。
-  registerHttp(ctx, { store, cfg, autoContinue });
+  // /task-tree 命令：查看与管理任务树，也是"暂停 / 继续"的开关。
+  registerCommands(ctx, { store, cfg, pause, enabled: true });
+
+  // 任务树条目要用的 HTTP 接口。
+  registerHttp(ctx, { store, autoContinue, pause });
 
   ctx.logger?.info?.(`dsh-tree-task-flow: 已启用（状态目录 ${root}）`);
 }

package/lib/pause.js

@@ -0,0 +1,138 @@
+/**
+ * 暂停 / 继续。
+ *
+ * 人按下暂停时想要的是"**现在就停，别再往下跑**"，而且**不要留下痕迹**：
+ * 不要插一条消息进对话，也不要凭空多出一轮模型请求。
+ *
+ * 能同时满足这两点的位置只有一个：**`agent/pre-step`**。
+ *
+ * 一个 step 走完、工具结果都已落盘之后，驱动循环会回到起点，向 `agent/pre-step`
+ * 询问"下一步进不进、带哪些消息进去"（`agent-loop` 的 `turn()` 里那次
+ * `await this.preStep(target, …)`）。此刻的状态恰好是：
+ *
+ *   - 正在执行的工具**已经正常跑完**，结果也在会话里了——不打断它；
+ *   - 模型**还没**发起下一次请求——拦在这里就真的什么都不会发生；
+ *   - 消息已被 claim 但尚未提交，轮次也还开着——放行后模型从原处接着请求，
+ *     上下文里**零新增消息**。
+ *
+ * 所以本模块做的事只有一件：在这个岔口上挂住，等人点继续。
+ *
+ * 相比之下另外两个候选都不合适：
+ *   - `agent/turn-stopping` 虽然也是被 await 的，但轮次紧接着就会关闭
+ *     （`agent-loop` 里 `if (turnEnds && this.inbox.nextStep.length === 0) break;`），
+ *     想让它继续跑就必须 `steer()` 一条消息进去——那就留下了痕迹。
+ *   - 工具结果里的 `concludesTurn: true` 只是提前收尾，同样得靠新输入才能再启动。
+ *
+ * ★ **闸门只拦自动推进，不拦真人发言。** 暂停期间人自己发了消息，说明人要它跑，
+ * 这时既不放闸也不该继续端着：直接放行，并顺手解除暂停。
+ *
+ * @module dsh-tree-task-flow/pause
+ */
+
+/**
+ * 注册暂停闸门。
+ *
+ * @param ctx - 挂载本行的 Cordis 上下文。
+ * @param options - `{ autoContinue }`：自动续行兜底的控制接口，可为 null。
+ *   暂停要同时压住它，否则模型刚停下、兜底就把会话又 followup 拉起来了。
+ */
+export function registerPause(ctx, { autoContinue = null } = {}) {
+  /** 处于暂停态的会话。 */
+  const paused = new Set();
+  /**
+   * 正挂在 pre-step 上的会话 → 唤醒它们的那些函数。
+   *
+   * 存成集合而不是单个函数：驱动循环虽然串行，一个会话同一时刻只会有一个
+   * pre-step 在等，但"继续"必须是幂等且彻底的——万一有第二个挂上来，
+   * 后一个把前一个的唤醒函数盖掉，先挂住的那次就永远醒不过来了。
+   */
+  const waiters = new Map();
+
+  /**
+   * 挂起当前会话，直到有人点继续、或这一轮被取消。
+   *
+   * @param sessionId - 要挂起的会话。
+   * @param signal - 本轮的取消信号。人在界面上按停止时它会 abort，
+   *   必须跟着醒来——否则轮次会被永远挂住，连停都停不下来。
+   * @returns 可以放行时兑现的 promise（不传递任何值）。
+   */
+  function waitForResume(sessionId, signal) {
+    return new Promise((resolve) => {
+      let settled = false;
+      const release = () => {
+        if (settled) return;
+        settled = true;
+        const pending = waiters.get(sessionId);
+        if (pending !== undefined) {
+          pending.delete(release);
+          if (pending.size === 0) waiters.delete(sessionId);
+        }
+        signal?.removeEventListener?.("abort", release);
+        resolve();
+      };
+      const pending = waiters.get(sessionId) ?? new Set();
+      pending.add(release);
+      waiters.set(sessionId, pending);
+      if (signal?.aborted === true) {
+        release();
+        return;
+      }
+      signal?.addEventListener?.("abort", release, { once: true });
+    });
+  }
+
+  // waterfall：必须 await next() 并把它返回，否则会截断监听器链。
+  // auto-continue.js 也注册了同一个事件（重置续行配额），两条互不干扰。
+  ctx.on("agent/pre-step", async (payload, next) => {
+    const sessionId = payload?.agent?.session?.id;
+    if (sessionId === undefined || !paused.has(sessionId)) return next();
+
+    // 真人发言 = 人要它继续跑。放行，并且不再端着暂停态。
+    const fromHuman = (payload?.messages ?? []).some(
+      (message) => message?.source?.kind === "user",
+    );
+    if (fromHuman) {
+      paused.delete(sessionId);
+      return next();
+    }
+
+    await waitForResume(sessionId, payload?.signal);
+    return next();
+  });
+
+  return {
+    /**
+     * 暂停某个会话：之后的每一次自动推进都停在 pre-step。
+     * 正在执行的工具不受影响，它跑完才会走到这里。
+     *
+     * @param sessionId - 要暂停的会话。
+     */
+    pause(sessionId) {
+      if (sessionId === undefined) return;
+      paused.add(sessionId);
+      autoContinue?.stop?.(sessionId);
+    },
+    /**
+     * 继续某个会话：放行挂在 pre-step 上的那一步。
+     * 不推送任何消息——模型只是从它原本要请求的地方接着请求。
+     *
+     * @param sessionId - 要放行的会话。
+     */
+    resume(sessionId) {
+      if (sessionId === undefined) return;
+      paused.delete(sessionId);
+      const pending = waiters.get(sessionId);
+      if (pending !== undefined) for (const release of [...pending]) release();
+      autoContinue?.resume?.(sessionId);
+    },
+    /**
+     * 这个会话当前是不是暂停着。
+     *
+     * @param sessionId - 要查询的会话。
+     * @returns 暂停中为 true。
+     */
+    isPaused(sessionId) {
+      return paused.has(sessionId);
+    },
+  };
+}

package/lib/plan.js

@@ -323,7 +323,7 @@ export function updateNode(plan, id, patch, now = Date.now()) {
 }
 
 /**
- * 层级的显示名。树渲染、检查点提示、闸门拒绝文案都用它，保证三处称呼一致。
+ * 层级的显示名。树渲染、检查点提示、命令回执都用它，保证几处称呼一致。
  *
  * @param level - `goal` / `task` / `step`。
  * @returns 中文称呼。
@@ -334,12 +334,12 @@ export function levelLabel(level) {
   return "子任务";
 }
 
-/** 检查点那句话：只放行拆子节点与提交结果两条路。 */
+/** 检查点那句话：把判断权交还给模型，不假装替它规定了出路。 */
 function checkpointNote(checkpoint) {
   const label = levelLabel(checkpoint.level);
   return (
     `${label}「${checkpoint.node.title}」的子节点已全部结束，转入检查点。` +
-    `此刻只有两条路：用 tree_task_plan 继续给 ${checkpoint.node.id} 拆子节点，` +
+    `此刻轮到你的判断：用 tree_task_plan 继续给 ${checkpoint.node.id} 拆子节点，` +
     `或者用 tree_task_done(id="${checkpoint.node.id}", result="…") 提交这个${label}的结果并完成它。`
   );
 }
@@ -402,9 +402,8 @@ export function renderContinue(plan) {
     const label = levelLabel(checkpoint.level);
     return [
       `检查点：${label}「${checkpoint.node.title}」(${checkpoint.node.id}) 的子节点已全部结束。`,
-      `此刻只放行两个工具：tree_task_plan（继续给 ${checkpoint.node.id} 拆子节点）与 ` +
-        `tree_task_done（提交这个${label}的结果并完成它）。`,
-      `不要再调用别的工具。`,
+      `此刻轮到你的判断：用 tree_task_plan 继续给 ${checkpoint.node.id} 拆子节点，` +
+        `或者用 tree_task_done(id="${checkpoint.node.id}", result="…") 提交这个${label}的结果并完成它。`,
     ].join("\n");
   }
 

package/lib/prompt.js

@@ -1,13 +1,11 @@
 /**
- * 系统提示词段落：**只有一段，静态，会话内逐字节不变**。
+ * 系统提示词段落：**只有一段**，讲的是"什么时候用这组工具、完成时守什么规矩"。
  *
- * 这里只说明"这组工具是什么、怎么配合用"。计划的当前状态由 `tree_task_status`
- * 现取；已完成节点的产出一部分在树上（首行），全文在完成时注入的那条汇总消息里
- * ——都不放进这里。
+ * 工具清单**不在这里**——每个工具的用法由它自己的 `description` 承担。同一句话
+ * 写在两处，只会让它在每一次请求里占两份位置，而模型真要调用时读的始终是
+ * `description`。计划当前的状态同样不在这里，由 `tree_task_status` 现取。
  *
- * 之所以坚持静态：提示词一变，DSH 就会往 surface 上追加一整份新副本
- * （默认 in-history 路由）；万一撞上归一化，还会重写节点 0，
- * 让整个上下文从第一个 token 起失去缓存。所以这里一个字都不动。
+ * 写法与内置工具段落一致：`text` 是个函数，工具不在当前作用域里就输出空串。
  *
  * @module dsh-tree-task-flow/prompt
  */
@@ -15,34 +13,28 @@
 /** 段落名。注册表要求全局唯一。 */
 export const SECTION_NAME = "dsh-tree-task-flow";
 
-/** 默认排序。放在部署人设（0）、计划策略（500）之后，所有内置工具指引之前。 */
-export const DEFAULT_ORDER = 2000;
+/**
+ * 默认排序。
+ *
+ * 落在 TOOL_PTY（1700）与 TOOL_WEB_SEARCH（2000）之间的空档：与内置工具指引同区，
+ * 又不与任何已占用的号相撞。内置贡献方靠 `getSectionOrder` 取中央分配的位置，
+ * 外部插件没有这个待遇，只能自己挑一个不冲突的有限值。
+ */
+export const DEFAULT_ORDER = 1800;
 
 /** 段落正文。 */
 export const SECTION_TEXT = `## 树形任务流（tree_task_* 工具组）
 
-一件事需要多步才能做完时，用 tree_task_* 这组工具把它组织成一棵树，
-而不是把计划写在回复正文里。层级固定三级：**目标 → 任务 → 子任务**；
+一件事需要多步才能做完时，用这组工具把它组织成**目标 → 任务 → 子任务**三级树，
+而不是把计划写在回复正文里，也不要再用 todo_write 另记一份。层级固定三级，
 子任务是最低一级，不能再往下拆。
 
-- **tree_task_create** —— 建立一个计划：一个目标 + 若干任务。会替换掉现有计划，只在开始新目标时用。
-- **tree_task_plan** —— 给一个节点追加子节点：给目标追加任务，给任务追加子任务。
-- **tree_task_status** —— 查看整棵树、各节点状态与已提交的结果，以及现在该推进哪个节点。
-- **tree_task_done** —— 完成一个节点并提交它的结果。**result 必填。**
-- **tree_task_update** —— 修改一个节点的标题或说明。
-- **tree_task_drop** —— 丢弃一个节点；丢弃任务会连同它的子任务一起丢弃。改需求用它，不要重建整棵树。
-
-三条规则：
-
-1. **完成必须写 result。** 一个节点完成时，插件会把它从开始到现在的执行过程
-   从上下文里折叠掉，换成一条只携带这段结果的汇总消息。所以 result 要写清它
-   究竟产出了什么，写成能独立看懂的样子——过程会被丢掉，别写在里面。
-2. **子任务全部结束，不会让父节点自动完成**，而是转入**检查点**。那一刻只剩两条路：
-   用 tree_task_plan 继续给这个节点拆子节点，或者用 tree_task_done 提交它的结果。
-   检查点期间其它工具一律被拒绝——"这一层到底做完没有"要由你判断，不能被计数规则替你定死。
-3. 折叠只发生在完成的那一刻：已完成节点的执行过程不再可见，只留下它提交的结果，
-   而同级节点各自的结果都会保留下来。需要看全貌——哪些做完了、各自产出了什么——
-   调用 tree_task_status，不要凭印象猜。`;
+- **完成必须提交能独立看懂的 result。** 这个节点从开始到现在的执行过程会被整段
+  折叠掉，只留下这条结果；同级已完成的汇总不会被后来的折叠卷走。要看全貌就调
+  tree_task_status，不要凭印象猜。
+- **子任务全部结束后，父节点不会自动完成。** 那一刻轮到你的判断：继续用
+  tree_task_plan 拆子节点，还是用 tree_task_done 提交结果收尾。插件不会替你决定
+  这一层做完没有。`;
 
 /**
  * 注册段落。调用方必须包在 `ctx.effect()` 里，否则热更新后会重复注册而抛错。
@@ -52,5 +44,11 @@ export const SECTION_TEXT = `## 树形任务流（tree_task_* 工具组）
  * @returns 注册返回的 disposer（由 ctx.effect 持有）。
  */
 export function registerPromptSection(ctx, order) {
-  return () => ctx.systemPrompt.section({ name: SECTION_NAME, order, text: SECTION_TEXT });
+  return () =>
+    ctx.systemPrompt.section({
+      name: SECTION_NAME,
+      order,
+      text: ({ scope }) =>
+        ctx.tools.get("tree_task_status", scope) === undefined ? "" : SECTION_TEXT,
+    });
 }