dsh-tree-task-flow 0.3.5 → 0.3.7

package/README.md

@@ -27,24 +27,29 @@
 规则只有一条，**只看表层，与计划树无关**：
 
 ```
-从上一个边界调用之后  →  到下一个 tree_task_done 之前，这一段收走
+从「上一次 tree_task_done 之后的第一个 create / plan」之后
+    →  到本次 tree_task_done 之前，这一段收走
 ```
 
-边界调用是 `tree_task_create` / `tree_task_plan` / `tree_task_done` 这三个工具，
-它们的调用**与返回**都留在上下文里——模型靠它们看"计划是什么、下一步干什么"。
+起点是上一次 `tree_task_done` 之后的**第一个** `tree_task_create` / `tree_task_plan`；
+会话里还没有过 `tree_task_done` 时，就是表层第一个 `create` / `plan`。
+**中间的 `create` / `plan` 不再是切点**——它们连同过程一起收走。
+起点那次调用自己的调用**与返回**留在上下文里，本次 `tree_task_done` 的调用与返回
+同样留着（模型靠它们看"这一步做什么、下一步干什么"）。
 折叠只收它们**之间**的过程，换成一条计数通告：
 
 ```
-[tree_task_plan 调用] [返回：已添加 2 个子任务 + 整棵树]
+[tree_task_create 调用] [返回：计划已建立 + 整棵树]
 [tree_task消息：隐藏了 12 条过程上下文。读取：… 写入：…]
 [tree_task_done 调用] [返回：接下来需要进行步骤：「二」(s-4)。]
 ```
 
 两条硬约束：
 
-- 两次边界调用之间**夹着你的消息就不折**——往前折丢了需求，往后折丢了回应，
+- 折叠区间里**夹着你的消息就不折**——往前折丢了需求，往后折丢了回应，
   这一段整段跳过，一个节点都不动；
-- 两次调用**挨着**（中间没有过程）也什么都不注入，不追加、不留空消息。
+- 区间**为空**（起点那次调用与 `done` 紧挨着，中间没有过程）也什么都不注入，
+  不追加、不留空消息。
 
 每一次 `tree_task_done` 的调用与它的返回都**留在上下文里**，一轮轮累积；
 模型下一轮还看得到"我刚做完了什么、接下来干什么"。
@@ -83,7 +88,8 @@ tree_task消息：接下来需要进行步骤：「步骤二」(s-4)。
 | 整棵树都完了 | `tree_task消息：请汇报最终结果。` |
 
 两样都**不重复提交内容**（`result` 就在这次调用的参数里）。折叠时，**这次
-`tree_task_done` 的调用连同它的返回原样留在上下文里**，被收走的只是它**前面**那段过程。
+`tree_task_done` 的调用连同它的返回原样留在上下文里**，被收走的只是它**前面**那段过程
+——那一段里若夹着别的 `create` / `plan` 调用，它们也一并收走。
 
 **子任务全部结束，不会让父节点自动完成。** 那一刻树进入**检查点**，
 也就是上表第二种返回。
@@ -226,6 +232,12 @@ dsh --profile web --dump-config          # 输出里应出现 task-tree 这一
 继续（界面按钮或 `/task-tree resume`）就是从这个岔口放行：模型从它原本要请求的地方
 接着请求，同样**零新增消息**。任务树的进度停在哪儿，就从哪儿接着跑。
 
+**重启 `dsh web` 之后暂停依然有效。** "被按住"这件事写在状态目录的 `held/` 下，
+重启后条目仍显示「已暂停」，点「继续」即可接着跑。区别只有一处：进程重启过之后，
+没有挂在岔口上的那一口气可放，插件只能给会话排一条「恢复续行」的消息把它从 `idle`
+推起来——**只有跨过重启的这一次恢复会留下这条消息**。若那个会话还没被打开（DSH 还没把它
+加载成实时 agent），点继续会提示你先打开它，并且**保留暂停状态**，不会白丢。
+
 闸门开在 agent 的 `agent/pre-step` 上——一个 step 走完、工具结果都已落盘、模型还没
 发起下一次请求的那一刻。这是唯一同时满足"不打断工具"和"不留痕迹"的位置：再晚一点
 的 `agent/turn-stopping` 一旦放行，就得靠 `steer()` 推一条消息才能续上，那就留下痕迹了。
@@ -276,8 +288,10 @@ dsh --profile web --dump-config          # 输出里应出现 task-tree 这一
    空 `result` 会被拒绝。所以要写清"产出了什么"，写成能独立看懂的样子——
    过程会丢，别把过程写进去。
 
-2. **折叠只看表层。** 两次边界调用之间没有过程时，什么都不注入；中间夹着你的消息时
-   整段不折——那一段原样留着（往前折丢需求、往后折丢回应），代价是上下文不收缩。
+2. **折叠只看表层。** 起点是上一次 `done` 之后的第一个 `create` / `plan`，
+   中间的 `create` / `plan` 不再是切点，会连同过程一起收走；区间里没有过程时
+   什么都不注入，夹着你的消息时整段不折——那一段原样留着（往前折丢需求、
+   往后折丢回应），代价是上下文不收缩。
 
 3. **模型看到的工具说明不随计划变化，也不复述工具清单。** 那一段只讲什么时候用
    这组工具、完成时守什么规矩；每个工具的用法由它自己的 `description` 承担。
@@ -305,26 +319,6 @@ dsh --profile web --dump-config          # 输出里应出现 task-tree 这一
 | 并行推进多个目标 | 结构上支持一个会话有多个目标（目标层就是兄弟列表），但同一时刻只沿一条活动路径走 |
 | 把计划内容注入提示词 | 计划状态由 `tree_task_status` 现取，提示词里只放不随计划变化的说明 |
 
-## 自检
-
-六个自检脚本都不 import 任何 `@deepseek-ai/*` 运行时包——插件以 `link:` 方式安装时，
-从插件目录往上找不到宿主作用域的包，一旦 import 就根本跑不起来。
-`verify-client.mjs` 因此自带一套最小的 `window` / `document` / React 替身，
-真去物化 `client.js`、真调一次 `apply`、真渲染一遍条目。
-
-```powershell
-node verify-entry.mjs     # 入口装配：默认（安装即启用）/ 显式关闭两条路径各注册了什么
-node verify-tools.mjs     # 工具层：schema、result 必填、三级约束
-node verify-region.mjs    # 折叠行为：游标推进、降级追加、检查点提示
-node verify-plan.mjs      # 计划树纯逻辑：状态流转、自动完成、丢弃级联
-node verify-pause.mjs     # 暂停闸门：挂起、放行、取消信号、真人发言、会话隔离
-node verify-client.mjs    # 客户端条目：挂载点、样式注入、文案键集、四种渲染态
-```
-
-`verify-region.mjs` 用假 session 忠实复刻了 DSH surface 的三条硬规则
-（替换保持位置、`sourceEventSeqs` 必须覆盖全部遮蔽节点、节点 0 重写约束），
-否则测出来的东西不算数。
-
 ## 卸载
 
 ```powershell
@@ -333,11 +327,6 @@ dsh plugin --profile web remove dsh-tree-task-flow
 
 状态目录不会自动清理，需要的话手动删 `$DSH_HOME/dsh-task-tree`。
 
-## 设计文档
-
-- `docs/02-DSH插件开发方案.md` —— 完整设计：上下文组成、游标、折叠、检查点
-- `docs/01-AIDesktop联动设计整理.md` —— 本插件最初的设计来源
-
 ## 许可
 
 MIT

package/client.js

@@ -666,11 +666,24 @@ window.__ModuleLoader__.load({
 				return () => clearInterval(timer);
 			}, [sessionId, reload]);
 
+			// 这次操作的结果说明（已放行 / 已唤醒 / 为什么没动）：恢复失败时用户最需要
+			// 的就是这句话，不能只留在接口的返回里。
+			const [note, setNote] = useState(null);
+			useEffect(() => {
+				if (!note) return undefined;
+				const timer = setTimeout(() => setNote(null), 8000);
+				return () => clearTimeout(timer);
+			}, [note]);
+
 			const act = useCallback(
 				async (body) => {
 					setBusy(true);
+					setNote(null);
 					try {
-						await post(Object.assign({ sessionId }, body));
+						const result = await post(Object.assign({ sessionId }, body));
+						if (result && typeof result.message === "string" && result.message !== "") {
+							setNote(result.message);
+						}
 						await reload();
 					} finally {
 						setBusy(false);
@@ -747,6 +760,8 @@ window.__ModuleLoader__.load({
 							}),
 						),
 					),
+					// 这次操作的结果与原因（已放行 / 已唤醒 / 为什么没动）。
+					note ? h("div", { className: "dsh-ttf-note" }, note) : null,
 					open
 						? h(
 								"div",

package/lib/auto-continue.js

@@ -37,10 +37,19 @@ export function registerAutoContinue(ctx, { store, cfg }) {
    */
   const stopped = new Set();
 
+  /** 这个会话是不是被"停止"按住：内存说是，或磁盘说是。 */
+  function heldNow(sessionId) {
+    return stopped.has(sessionId) || store?.readHeld?.(sessionId)?.stopped === true;
+  }
+
   ctx.on("agent/turn-stopping", (payload) => {
     const sessionId = payload?.agent?.session?.id;
     if (sessionId === undefined) return;
-    if (payload?.signal?.aborted === true) stopped.add(sessionId);
+    if (payload?.signal?.aborted === true) {
+      stopped.add(sessionId);
+      // 落盘：重启后条目上仍看得到「继续」，也仍然压得住自动续行。
+      store?.patchHeld?.(sessionId, { stopped: true });
+    }
   });
 
   // 只有**真人**发的消息才重置配额。
@@ -62,6 +71,7 @@ export function registerAutoContinue(ctx, { store, cfg }) {
       rounds.set(sessionId, 0);
       // 人回来了，解除中断标记，允许新一轮的续行。
       stopped.delete(sessionId);
+      store?.patchHeld?.(sessionId, { stopped: false });
     }
     return decision;
   });
@@ -75,7 +85,7 @@ export function registerAutoContinue(ctx, { store, cfg }) {
     if (agent === undefined || sessionId === undefined) return;
 
     // ★ 安全阀 0：这一轮是被用户**中止**的 → 绝不能把它拉起来。
-    if (stopped.has(sessionId)) return;
+    if (heldNow(sessionId)) return;
 
     // 安全阀 1：已经有排队输入，别抢在用户前面。
     const inbox = agent.inbox;
@@ -116,9 +126,9 @@ export function registerAutoContinue(ctx, { store, cfg }) {
     resume(sessionId) {
       if (sessionId !== undefined) stopped.delete(sessionId);
     },
-    /** 这个会话当前是不是被停止状态。 */
+    /** 这个会话当前是不是处于被停止状态（跨重启）。 */
     isStopped(sessionId) {
-      return stopped.has(sessionId);
+      return heldNow(sessionId);
     },
   };
 }

package/lib/commands.js

@@ -90,18 +90,20 @@ export function registerCommands(ctx, { store, cfg, pause = null, enabled = fals
           kind: "success",
           text:
             "已暂停本会话：正在执行的那个工具会正常跑完，之后不再往下推进。" +
-            "任务树的进度没有变，点继续就从停住的地方接着跑。",
+            "任务树的进度没有变，点继续就从停住的地方接着跑。" +
+            "这个暂停会写进状态目录，重启 dsh web 之后依然有效。",
         };
       }
 
       if (verb === "resume") {
-        pause?.resume?.(sessionId);
+        const outcome = pause?.resume?.(sessionId) ?? null;
+        const tail =
+          cfg.autoContinue === true
+            ? "自动续行也重新允许了。"
+            : "配置里 autoContinue 是 false，所以模型自己停下后不会再被自动拉起。";
         return {
           kind: "success",
-          text:
-            cfg.autoContinue === true
-              ? "已继续：停在岔口上的那一步已经放行，自动续行也重新允许了。"
-              : "已继续：停在岔口上的那一步已经放行。配置里 autoContinue 是 false，所以模型自己停下后不会再被自动拉起。",
+          text: `已继续：${outcome?.text ?? "停在岔口上的那一步已经放行。"}${tail}`,
         };
       }
 

package/lib/http.js

@@ -150,11 +150,14 @@ export function registerHttp(ctx, { store, autoContinue, pause = null }) {
             // 暂停 / 继续。暂停会同时压住自动续行兜底，两个状态一起回传，
             // 免得条目还要再问一次。
             if (action === "pause" || action === "resume") {
-              pause?.[action]?.(sessionId);
+              const outcome = pause?.[action]?.(sessionId) ?? null;
               return sendJson(response, 200, {
                 ok: true,
                 paused: pause?.isPaused?.(sessionId) === true,
                 stopped: autoContinue?.isStopped?.(sessionId) === true,
+                // 跨重启的那次「继续」可能什么都没能唤醒，把话说给界面听。
+                message: typeof outcome?.text === "string" ? outcome.text : null,
+                woke: outcome?.woke === true,
               });
             }
 

package/lib/index.js

@@ -106,7 +106,7 @@ export function apply(ctx, config) {
 
   // 暂停闸门：挂在 `agent/pre-step` 上，人点暂停就停在"上一个工具跑完、
   // 下一次模型请求还没发出"那个岔口。它同时压住上面的自动续行兜底。
-  const pause = registerPause(ctx, { autoContinue });
+  const pause = registerPause(ctx, { store, autoContinue });
 
   // /task-tree 命令：查看与管理任务树，也是"暂停 / 继续"的开关。
   registerCommands(ctx, { store, cfg, pause, enabled: true });

package/lib/pause.js

@@ -15,29 +15,44 @@
  *   - 消息已被 claim 但尚未提交，轮次也还开着——放行后模型从原处接着请求，
  *     上下文里**零新增消息**。
  *
- * 所以本模块做的事只有一件：在这个岔口上挂住，等人点继续。
- *
- * 相比之下另外两个候选都不合适：
- *   - `agent/turn-stopping` 虽然也是被 await 的，但轮次紧接着就会关闭
- *     （`agent-loop` 里 `if (turnEnds && this.inbox.nextStep.length === 0) break;`），
- *     想让它继续跑就必须 `steer()` 一条消息进去——那就留下了痕迹。
- *   - 工具结果里的 `concludesTurn: true` 只是提前收尾，同样得靠新输入才能再启动。
- *
  * ★ **闸门只拦自动推进，不拦真人发言。** 暂停期间人自己发了消息，说明人要它跑，
  * 这时既不放闸也不该继续端着：直接放行，并顺手解除暂停。
  *
+ * ## 重启之后（本模块与"零痕迹"的唯一分歧点）
+ *
+ * 闸门挂住的是进程里的一个 Promise。**重启会把"挂住"这件事本身抹掉**：
+ * 没有 waiter 可放行，也没有标记可清，会话就停在 `idle` 上再也起不来。
+ *
+ * 所以"被按住"这件事**落盘**（`held/<sessionId>.json`，见 store）：
+ *
+ *   - 重启后 `isPaused` 依旧为真 → 条目上仍有「继续」按钮，人找得到入口；
+ *   - 闸门也按落盘的 `paused` 判定 → 重启后若还有别的力量（比如自动续行）把会话
+ *     推起来，它照样会在下一个岔口被按住；
+ *   - 点继续时本进程里没有 waiter，就退一步用 `agent.followup()` 把会话从 `idle`
+ *     唤醒。**这一次恢复会往会话里排一条续行消息**——常规暂停/继续仍然零新增消息，
+ *     只有跨过重启的那一次不同，因为那是唯一能真正把它跑起来的手段。
+ *
+ * 唤醒要求该会话已被 DSH 加载成实时 agent（Web 界面打开这个会话就会触发按需
+ * resume）。拿不到 agent 时不做任何事，只回一句"先打开它，或在其中发一条消息"。
+ *
  * @module dsh-tree-task-flow/pause
  */
 
+import { activePath, renderContinue } from "./plan.js";
+
+/** 本插件放下的消息都带这个身份。 */
+const PLUGIN = "dsh-tree-task-flow";
+
 /**
  * 注册暂停闸门。
  *
  * @param ctx - 挂载本行的 Cordis 上下文。
- * @param options - `{ autoContinue }`：自动续行兜底的控制接口，可为 null。
- *   暂停要同时压住它，否则模型刚停下、兜底就把会话又 followup 拉起来了。
+ * @param options - `{ store, autoContinue }`：`store` 是状态读写端口；
+ *   `autoContinue` 是自动续行兜底的控制接口，可为 null——暂停要同时压住它，
+ *   否则模型刚停下、兜底就把会话又 followup 拉起来了。
  */
-export function registerPause(ctx, { autoContinue = null } = {}) {
-  /** 处于暂停态的会话。 */
+export function registerPause(ctx, { store = null, autoContinue = null } = {}) {
+  /** 本进程内处于暂停态的会话。 */
   const paused = new Set();
   /**
    * 正挂在 pre-step 上的会话 → 唤醒它们的那些函数。
@@ -48,6 +63,27 @@ export function registerPause(ctx, { autoContinue = null } = {}) {
    */
   const waiters = new Map();
 
+  /** 这个会话是不是被按住：内存说是，或磁盘说是。 */
+  function heldNow(sessionId) {
+    return paused.has(sessionId) || store?.readHeld?.(sessionId)?.paused === true;
+  }
+
+  /** 只清"暂停"这一半；"停止"那一半归 auto-continue 管。 */
+  function clearPaused(sessionId) {
+    store?.patchHeld?.(sessionId, { paused: false });
+  }
+
+  /**
+   * 取这个会话的实时 agent。
+   *
+   * 用 `ctx.get()` 反射式取，不写进 `inject`：拿不到可选服务时 cordis 会直接抛错，
+   * 那会让整个插件加载失败。取不到就退回"提示用户自己发消息"。
+   */
+  function liveAgent(sessionId) {
+    const agents = ctx.get?.("agents");
+    return agents?.get?.(sessionId) ?? null;
+  }
+
   /**
    * 挂起当前会话，直到有人点继续、或这一轮被取消。
    *
@@ -81,11 +117,62 @@ export function registerPause(ctx, { autoContinue = null } = {}) {
     });
   }
 
+  /**
+   * 重启之后的那次"继续"：本进程里没有 waiter 可放行，只能把 idle 的会话推起来。
+   *
+   * 只有"会话已被加载 + 停在 idle + 计划里还有**未结束的节点**"三条同时成立才推——
+   * 正在跑的会话不需要推，整棵树已经收尾的会话不该被推。
+   *
+   * 注意别把"当前任务还没拆子任务"和"检查点"当成收尾：前者要模型去 `tree_task_plan`，
+   * 后者要模型拍板这一层到底完成没有，两者都还是活的。只有 `activePath()` 返回 null
+   * （整棵树都结束了）才真的没得跑。
+   *
+   * @param sessionId - 要唤醒的会话。
+   * @returns `{ woke, reason, text }`：`text` 是给命令与界面看的一句话。
+   */
+  function wakeIdle(sessionId) {
+    const agent = liveAgent(sessionId);
+    if (agent === null) {
+      return {
+        woke: false,
+        reason: "unloaded",
+        text: "这个会话还没被加载：先在界面上打开它，或在其中发一条消息。",
+      };
+    }
+    if (agent.status !== "idle") {
+      return { woke: false, reason: "busy", text: "这个会话正在跑，不需要唤醒。" };
+    }
+    const plan = store?.readPlan?.(sessionId) ?? null;
+    const active = activePath(plan);
+    if (active === null) {
+      return { woke: false, reason: "finished", text: "计划树上的节点都已结束，没有什么可以接着跑的。" };
+    }
+    try {
+      agent.followup({
+        id: `tt-resume-${sessionId}-${Date.now().toString(36)}`,
+        role: "user",
+        content: [{ type: "text", text: renderContinue(plan) }],
+        source: { kind: "plugin", plugin: PLUGIN, form: "notice", summary: "恢复续行" },
+      });
+    } catch (error) {
+      return {
+        woke: false,
+        reason: "error",
+        text: `唤醒失败：${String(error?.message ?? error)}`,
+      };
+    }
+    return {
+      woke: true,
+      reason: "woke",
+      text: "已把会话从停住的地方推起来（跨重启的这次恢复会往会话里排一条续行消息）。",
+    };
+  }
+
   // 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();
+    if (sessionId === undefined || !heldNow(sessionId)) return next();
 
     // 真人发言 = 人要它继续跑。放行，并且不再端着暂停态。
     const fromHuman = (payload?.messages ?? []).some(
@@ -93,6 +180,7 @@ export function registerPause(ctx, { autoContinue = null } = {}) {
     );
     if (fromHuman) {
       paused.delete(sessionId);
+      clearPaused(sessionId);
       return next();
     }
 
@@ -110,29 +198,60 @@ export function registerPause(ctx, { autoContinue = null } = {}) {
     pause(sessionId) {
       if (sessionId === undefined) return;
       paused.add(sessionId);
+      store?.patchHeld?.(sessionId, { paused: true });
       autoContinue?.stop?.(sessionId);
     },
     /**
-     * 继续某个会话：放行挂在 pre-step 上的那一步。
-     * 不推送任何消息——模型只是从它原本要请求的地方接着请求。
+     * 继续某个会话。
+     *
+     * 分两种情况：
+     *   - 本进程里真挂着（常规暂停）→ 放行那一步，**零新增消息**；
+     *   - 没有挂着的 waiter（进程重启过）→ 退一步唤醒 idle 的会话，
+     *     这一次会往会话里排一条续行消息。
      *
      * @param sessionId - 要放行的会话。
+     * @returns `{ released, woke, reason, text }`。
      */
     resume(sessionId) {
-      if (sessionId === undefined) return;
-      paused.delete(sessionId);
+      if (sessionId === undefined) {
+        return { released: false, woke: false, reason: "no-session", text: "拿不到当前会话。" };
+      }
+
+      /** 真解除"被按住"：暂停与停止两半一起清，连自动续行的压住也放开。 */
+      const clearHeld = () => {
+        paused.delete(sessionId);
+        store?.patchHeld?.(sessionId, { paused: false, stopped: false });
+        autoContinue?.resume?.(sessionId);
+      };
+
+      // 本进程里真挂着：放行那一步——这是常规路径，**零新增消息**。
       const pending = waiters.get(sessionId);
-      if (pending !== undefined) for (const release of [...pending]) release();
-      autoContinue?.resume?.(sessionId);
+      if (pending !== undefined && pending.size > 0) {
+        clearHeld();
+        for (const release of [...pending]) release();
+        return { released: true, woke: false, reason: "released", text: "停在岔口上的那一步已经放行。" };
+      }
+
+      // 没有挂着的 waiter（进程重启过）：退一步唤醒 idle 的会话。
+      //
+      // **只有真把它推起来、或计划确实已经收尾，才解除"被按住"。** 没成功时
+      // （会话没加载 / 正在跑 / 唤醒抛错）必须把状态留着：否则用户既没有「继续」
+      // 可再点一次，也看不到为什么没动，只剩一个停在原地的会话。
+      const outcome = wakeIdle(sessionId);
+      if (outcome.woke === true || outcome.reason === "finished") clearHeld();
+      return { released: false, ...outcome };
     },
     /**
-     * 这个会话当前是不是暂停着。
+     * 这个会话当前是不是被按住（暂停）。
+     *
+     * 读的是内存加磁盘的并集：重启后内存里的那份没了，磁盘上的还在，
+     * 否则界面上连「继续」按钮都不会画出来。
      *
      * @param sessionId - 要查询的会话。
-     * @returns 暂停中为 true。
+     * @returns 被按住为 true。
      */
     isPaused(sessionId) {
-      return paused.has(sessionId);
+      return heldNow(sessionId);
     },
   };
 }

package/lib/region.js

@@ -3,11 +3,16 @@
  *
  * 规则只有一条，**只看表层，与计划树无关**：
  *
- *     从上一个边界调用之后，到下一个 `tree_task_done` 之前，中间那一段过程收走。
+ *     从「上一次 `tree_task_done` 之后的第一个 `create` / `plan`」之后，
+ *     到本次 `tree_task_done` 之前，中间那一段过程收走。
  *
- * 边界调用是 `tree_task_create` / `tree_task_plan` / `tree_task_done` 这三个工具。
- * 它们的调用与返回都留在表层上——那是模型看"计划是什么、下一步干什么"的地方，
- * 折叠只收它们**之间**的过程。
+ * 更早没有 `tree_task_done` 时，起点取表层第一个 `create` / `plan`；区间里一次
+ * `create` / `plan` 都没有时，回退到上一次 `tree_task_done` 之后（更早没有 `done`
+ * 则是表层开头）。起点那次调用、以及本次 `done` 的调用与返回，都留在表层上——
+ * 那是模型看"计划是什么、下一步干什么"的地方；被跨过的其它 `create` / `plan`
+ * 连同过程一起收走。
+ *
+ * 判定表见 `docs/06-折叠范围规则.md`。
  *
  * 两条硬约束：
  *
@@ -18,11 +23,13 @@
  *
  *     [节点 0] 系统提示词
  *     [用户消息]
- *     [tree_task_create 调用] [返回：计划已建立 + 整棵树]
- *     [tree_task_plan 调用]   [返回：已添加 2 个子任务 + 整棵树]
+ *     [tree_task_create 调用]  [返回：计划已建立 + 整棵树]
  *     [tree_task消息：隐藏了 12 条过程上下文。读取：… 写入：…]
- *     [tree_task_done 调用]   [返回：接下来需要进行步骤：「二」(s-4)。]
- *     [当前这一段执行过程]    ← 下一次折叠的对象
+ *     [tree_task_done 调用]    [返回：接下来需要进行步骤：「二」(s-4)。]
+ *     [当前这一段执行过程]     ← 下一次折叠的对象
+ *
+ * 这一段过程里原本还有一次 `tree_task_plan` 的调用与返回——它夹在 create 与 done 之间，
+ * 不是起点，于是随这一条通告一起收走了。
  *
  * 时机是 `agent/pre-step`：上一轮已结束、下一个请求还没构造。工具执行中途不能折叠
  * ——那一刻 surface 还在增长，替换会把自己卷进去。
@@ -182,15 +189,22 @@ function summaryLine(count, files) {
   return touched === 0 ? base : `${base} · 涉及 ${touched} 个文件`;
 }
 
+/** 这条 assistant 消息里有没有 `tree_task_create` / `tree_task_plan`。 */
+function isPlanCall(event) {
+  const names = toolNamesOf(event);
+  return names.includes("tree_task_create") || names.includes("tree_task_plan");
+}
+
 /**
  * 找这一次要折叠的区间。
  *
- * 从末尾往前找两次边界调用：**最近的那次必须是 `tree_task_done`**（它就是这次完成的
- * 那一下），再往前那次（create / plan / done 都算）是起点。两次调用之间的过程才是要收的。
- * 起点那次调用自己的 `tool/result` 也算这次调用的一部分，一并跳过。
+ * 从末尾往前找最近的一次边界调用，**它必须是 `tree_task_done`**（它就是这次完成的
+ * 那一下）；再往前找上一次 `tree_task_done`，起点就是**它之后最早的那次
+ * `create` / `plan`**——更早没有 `done` 时，起点是表层第一个 `create` / `plan`。
+ * 中间的 `create` / `plan` 不是切点：它们连同过程一起被收走。
  *
- * 表层上找不到更早的边界调用时（比如它已经被压缩遮掉），起点退回表层第一个节点之后
- * ——那时区间多半会撞上真人消息，于是整段不折，这是安全的那一侧。
+ * 区间里一次 `create` / `plan` 都没有时，起点退回上一次 `done` 之后（更早没有 `done`
+ * 则是表层第一个节点之后）——那时区间多半会撞上真人消息，于是整段不折，这是安全的那一侧。
  *
  * @param session - 当前会话。
  * @returns `{ from, to, shadowed }`；这一轮不该折时返回 null。
@@ -199,26 +213,42 @@ export function foldRange(session) {
   const nodes = session.surface?.nodes ?? [];
   if (typeof session.eventAt !== "function" || nodes.length === 0) return null;
 
+  // 终点：最近的一次边界调用，必须是一次 done。
   let endIdx = -1;
-  let startIdx = -1;
   for (let index = nodes.length - 1; index >= 0; index -= 1) {
     if (!isBoundaryCall(session.eventAt(nodes[index]))) continue;
-    if (endIdx === -1) {
-      // 末尾最近的那次边界调用不是 done：说明还没走到"完成"这一步，这一轮不折。
-      if (!isDoneCall(session.eventAt(nodes[index]))) return null;
-      endIdx = index;
-      continue;
-    }
-    startIdx = index;
+    // 末尾最近的那次边界调用不是 done：说明还没走到"完成"这一步，这一轮不折。
+    if (!isDoneCall(session.eventAt(nodes[index]))) return null;
+    endIdx = index;
     break;
   }
   if (endIdx === -1) return null;
 
-  // 起点：上一次边界调用之后。找不到就退回表层第一个节点之后（节点 0 是系统提示词，
-  // 受 DSH 的重写保护，不能进替换区间）。
+  // 上一次 done 的位置；更早没有 done 时是 -1，起点就从头算。
+  let prevDoneIdx = -1;
+  for (let index = endIdx - 1; index >= 0; index -= 1) {
+    if (isDoneCall(session.eventAt(nodes[index]))) {
+      prevDoneIdx = index;
+      break;
+    }
+  }
+
+  // 起点：上一次 done 之后最早的那次 create / plan。
+  let startIdx = -1;
+  for (let index = prevDoneIdx + 1; index < endIdx; index += 1) {
+    if (isPlanCall(session.eventAt(nodes[index]))) {
+      startIdx = index;
+      break;
+    }
+  }
+  // 区间里没有 create / plan：退回上一次 done 之后（更早没有 done 就是表层开头）。
+  if (startIdx === -1) startIdx = prevDoneIdx;
+
+  // 区间从起点调用的 `tool/result` 之后开始；找不到起点（-1）就退回表层第一个节点之后
+  // （节点 0 是系统提示词，受 DSH 的重写保护，不能进替换区间）。
   //
   // 还要跳过紧邻的两样东西：那次调用自己的 `tool/result`，以及**上一次折叠落下的通告**
-  // ——后者虽然夹在两次边界调用之间，却已经是收过的结果，再收一次就会一轮轮空折下去。
+  // ——后者虽然夹在区间里，却已经是收过的结果，再收一次就会一轮轮空折下去。
   let from = startIdx === -1 ? 1 : startIdx + 1;
   while (from < endIdx) {
     const event = session.eventAt(nodes[from]);

package/lib/store.js

@@ -1,10 +1,11 @@
 /**
  * 插件自有状态的读写。
  *
- * 两类状态，都**以 `sessionId` 为键**：
+ * 三类状态，都**以 `sessionId` 为键**：
  *
  *   - `plans/<sessionId>.json`     计划树
- *   - `surfaces/<sessionId>.json`  三层的折叠游标
+ *   - `surfaces/<sessionId>.json`  三层的折叠游标（只给界面看，不参与折叠）
+ *   - `held/<sessionId>.json`      「被按住」：暂停 / 停止，**要跨重启保留**
  *
  * 计划属于建立它的那个会话。放到会话无关的位置，任何一个会话的计划都会被
  * 所有会话的 `agent/pre-step` 读到——那等于把不相干的节点指派塞进别人的上下文，
@@ -22,7 +23,7 @@
  * @module dsh-tree-task-flow/store
  */
 
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
 
@@ -81,6 +82,35 @@ function normalizePlan(plan) {
 export function createStore(root) {
   const file = (...parts) => join(root, ...parts);
 
+  /** 「被按住」状态的文件路径。 */
+  const heldFile = (sessionId) => file("held", `${sessionId}.json`);
+
+  /** 读「被按住」状态；读不到或文件坏了，一律按"没被按住"处理。 */
+  function readHeldState(sessionId) {
+    if (!sessionId) return { paused: false, stopped: false, at: null };
+    const value = readJson(heldFile(sessionId), null);
+    if (value === null || typeof value !== "object") {
+      return { paused: false, stopped: false, at: null };
+    }
+    return {
+      paused: value.paused === true,
+      stopped: value.stopped === true,
+      at: typeof value.at === "number" ? value.at : null,
+    };
+  }
+
+  /** 写「被按住」状态；两份都不是 true 就把文件删掉，不留空壳。 */
+  function writeHeldState(sessionId, value) {
+    if (!sessionId) return;
+    const paused = value?.paused === true;
+    const stopped = value?.stopped === true;
+    if (!paused && !stopped) {
+      rmSync(heldFile(sessionId), { force: true });
+      return;
+    }
+    writeJson(heldFile(sessionId), { sessionId, paused, stopped, at: Date.now() });
+  }
+
   return {
     /** 状态根目录。 */
     root,
@@ -136,5 +166,50 @@ export function createStore(root) {
     writeSurfaces(sessionId, value) {
       writeJson(file("surfaces", `${sessionId}.json`), value);
     },
+
+    // ---- 「被按住」：暂停 / 停止。**要跨重启保留**，所以落盘 ----
+
+    /**
+     * 读「被按住」状态。
+     *
+     * 暂停闸门挂住的是进程里的一个 Promise，重启就把"挂住"这件事本身抹掉了，
+     * 于是既没有 waiter 可放行、也没有标记可清。这份状态因此必须落盘——
+     * 否则重启后条目看不到「继续」按钮，人连恢复的入口都没有。
+     *
+     * @param sessionId - 会话 id。
+     * @returns `{ paused, stopped, at }`；`at` 是最后一次写入的时间，没有则为 null。
+     */
+    readHeld(sessionId) {
+      return readHeldState(sessionId);
+    },
+
+    /**
+     * 写「被按住」状态。
+     *
+     * @param sessionId - 会话 id。
+     * @param value - `{ paused?, stopped? }`。
+     */
+    writeHeld(sessionId, value) {
+      writeHeldState(sessionId, value);
+    },
+
+    /**
+     * 只改某几个字段，其余保持磁盘上的原样。
+     *
+     * 暂停与停止分属两个模块，各自只知道自己那一半：谁都用整份覆盖写，
+     * 就会把对方刚落下的那一半抹掉。所以两份状态一律走这里读改写。
+     *
+     * @param sessionId - 会话 id。
+     * @param patch - `{ paused?, stopped? }`；没给的字段不动。
+     * @returns 写入后的完整状态。
+     */
+    patchHeld(sessionId, patch) {
+      const current = readHeldState(sessionId);
+      writeHeldState(sessionId, {
+        paused: patch?.paused ?? current.paused,
+        stopped: patch?.stopped ?? current.stopped,
+      });
+      return readHeldState(sessionId);
+    },
   };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tree-task-flow",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "树形任务流：把多步任务组织成目标→任务→子任务三级树，节点完成时由 AI 提交结果，插件随即把该节点的执行过程从上下文里折叠掉，只留下结果。",
   "type": "module",
   "main": "lib/index.js",