dsh-tree-task-flow 0.3.3 → 0.3.5

package/lib/region.js

@@ -1,32 +1,28 @@
 /**
- * 折叠：把一个节点的执行过程从上下文里收起来，换成一条携带它结果的汇总消息。
+ * 折叠：把一段执行过程从上下文里收起来，换成一条说明收走了什么的短消息。
  *
- * 上下文按固定三级排成这样：
+ * 规则只有一条，**只看表层，与计划树无关**：
  *
- *     [节点 0] 系统提示词
- *     [用户消息]
- *     [目标级汇总]                     ← goal.cursor
- *       [任务级汇总]                   ← task.cursor
- *         [子任务汇总] [子任务汇总] …  ← step.cursor 逐条往前推
- *       [任务级汇总]
- *         [子任务汇总] …
+ *     从上一个边界调用之后，到下一个 `tree_task_done` 之前，中间那一段过程收走。
  *
- * 每层一个游标，记着"这一层总结到哪儿了"。折叠时**从游标之后**替换到末尾：
+ * 边界调用是 `tree_task_create` / `tree_task_plan` / `tree_task_done` 这三个工具。
+ * 它们的调用与返回都留在表层上——那是模型看"计划是什么、下一步干什么"的地方，
+ * 折叠只收它们**之间**的过程。
  *
- *     子任务完成 → replace([上个游标之后, 末尾]) → 本子任务的汇总
- *     任务完成   → replace([进任务时的末尾之后, 末尾]) → 本任务的汇总
- *     目标完成   → replace([进目标时的末尾之后, 末尾]) → 目标的汇总
+ * 两条硬约束：
  *
- * 游标自己留在替换范围之外，所以**同级上一次的汇总消息不会被这一次折叠卷走**：
- * 新一层开始时游标正好停在它上面。
+ *   - 中间夹着真人消息就**整段不折**：往前折丢了需求，往后折丢了回应，两边都出事；
+ *   - 中间没有过程（两次调用挨着）就**什么都不注入**，不追加、不留空消息。
  *
- * 游标有两个来源：新开一层时是"进入那一刻 surface 的末尾节点"，折叠之后就变成
- * 刚落下的那条汇总消息。前者可能指向别的生产者留下的节点，所以判定游标是否可用
- * 只看"它还在不在 surface 上"，不要求它是本插件放的。
+ * 于是上下文长成这样：
  *
- * 游标一旦失效——被压缩遮掉了，或它之后本来就什么都没有——就没有可替换的区间。
- * 这一次折叠**降级为纯追加**：执行过程收不起来，但提交的结果照样进上下文。
- * 屏蔽是尽力而为，落下结果是必须做到的。
+ *     [节点 0] 系统提示词
+ *     [用户消息]
+ *     [tree_task_create 调用] [返回：计划已建立 + 整棵树]
+ *     [tree_task_plan 调用]   [返回：已添加 2 个子任务 + 整棵树]
+ *     [tree_task消息：隐藏了 12 条过程上下文。读取：… 写入：…]
+ *     [tree_task_done 调用]   [返回：接下来需要进行步骤：「二」(s-4)。]
+ *     [当前这一段执行过程]    ← 下一次折叠的对象
  *
  * 时机是 `agent/pre-step`：上一轮已结束、下一个请求还没构造。工具执行中途不能折叠
  * ——那一刻 surface 还在增长，替换会把自己卷进去。
@@ -34,16 +30,25 @@
  * @module dsh-tree-task-flow/region
  */
 
-import { activePath, checkpointOf, findNode, renderContinue } from "./plan.js";
+import { activePath } from "./plan.js";
 
 /** 本插件放下的消息都带这个身份。 */
 const PLUGIN = "dsh-tree-task-flow";
 
-/** 三层固定的名字，顺序就是折叠必须遵守的顺序：外层的折叠会吃掉内层的一切。 */
+/** 三层固定的名字。只给界面用的游标同步按这个顺序走。 */
 const LEVELS = ["goal", "task", "step"];
 
-/** 层级的显示名。 */
-const LEVEL_LABEL = { goal: "目标", task: "任务", step: "子任务" };
+/** 边界调用：这三个工具的调用与返回都不进替换区间，它们是折叠的起止点。 */
+const BOUNDARY_TOOLS = new Set(["tree_task_create", "tree_task_plan", "tree_task_done"]);
+
+/** 注入消息的抬头。 */
+const NOTICE_PREFIX = "tree_task消息：";
+
+/** 会改动文件的工具：它们的调用参数里带路径，算进"写入"列表。 */
+const WRITE_TOOLS = new Set(["write", "edit", "str_replace_editor"]);
+
+/** 只读取文件的工具：算进"读取"列表。 */
+const READ_TOOLS = new Set(["read", "read_image"]);
 
 /** 折叠消息的编号，保证同一毫秒内连折两次也不会撞 id。 */
 let foldSeq = 0;
@@ -53,99 +58,81 @@ function foldId() {
   return `tt-fold-${Date.now().toString(36)}-${foldSeq.toString(36)}`;
 }
 
-/** 一个节点是否已经结束（完成或丢弃）。两种都值得把执行过程收起来。 */
-function isClosed(node) {
-  return node.status === "done" || node.status === "dropped";
-}
-
 /** 取当前 surface 的最后一个节点 seq；surface 为空时返回 null。 */
 export function tailSeq(session) {
   const nodes = session.surface?.nodes;
   return nodes !== undefined && nodes.length > 0 ? nodes[nodes.length - 1] : null;
 }
 
-/**
- * 定位「游标之后到末尾」这一段，也就是这一步要折叠掉的东西。
- *
- * surface 是**位置顺序**、不是 seq 顺序：`replace` 会把新节点放回被替换的位置
- * （`nodes.splice(startIdx, count, seq)`），所以节点的 seq 并不递增——系统提示词
- * 被重写过之后，它的 seq 可能比它后面的用户消息大得多。
- *
- * 因此起止都必须按**位置索引**取，与 DSH 自己算 `nodes.slice(startIdx, endIdx + 1)`
- * 的方式一致。按 seq 区间筛选会在这种乱序下漏掉节点，而 `sourceEventSeqs`
- * 少列一个就会被 `session.append` 直接拒绝。
- *
- * 起点落在游标之后（`cursorIdx + 1`），游标本身因此永远留在 surface 上。
- *
- * @param session - 当前会话。
- * @param cursorSeq - 该层的游标 seq。
- * @returns `{ startIdx, endIdx, startSeq, endSeq, shadowed }`；
- *   游标不在 surface 上、或它已经是末尾（这一层还没产生任何可折叠的东西）时返回 null，
- *   调用方据此降级为追加。
- */
-export function foldRange(session, cursorSeq) {
-  const nodes = session.surface?.nodes ?? [];
-  if (!Number.isInteger(cursorSeq)) return null;
-  const cursorIdx = nodes.indexOf(cursorSeq);
-  if (cursorIdx === -1) return null;
-  const startIdx = cursorIdx + 1;
-  if (startIdx >= nodes.length) return null;
-  const endIdx = nodes.length - 1;
-  return {
-    startIdx,
-    endIdx,
-    startSeq: nodes[startIdx],
-    endSeq: nodes[endIdx],
-    shadowed: nodes.slice(startIdx),
-  };
+/** 这条 assistant 消息里调用了哪些工具。 */
+function toolNamesOf(event) {
+  const content = event?.data?.message?.content;
+  if (!Array.isArray(content)) return [];
+  return content.filter((part) => part?.type === "tool-call").map((part) => part.name);
+}
+
+/** 这条 assistant 消息里有没有边界调用。 */
+function isBoundaryCall(event) {
+  return toolNamesOf(event).some((name) => BOUNDARY_TOOLS.has(name));
+}
+
+/** 这条 assistant 消息里有没有 `tree_task_done`。 */
+function isDoneCall(event) {
+  return toolNamesOf(event).includes("tree_task_done");
+}
+
+/** 这条消息是不是真人发的——插件注入的消息 source 是 plugin，不算。 */
+function isHumanMessage(event) {
+  return event?.type === "user/message" && event.data?.source?.kind === "user";
+}
+
+/** 这条消息是不是本插件自己落下的折叠通告。 */
+function isPluginNotice(event) {
+  return event?.type === "user/message" && event.data?.source?.plugin === PLUGIN;
+}
+
+/** 从一次工具调用的参数里取它指向的文件路径；不是文件类调用就返回 null。 */
+function filePathOf(call) {
+  if (typeof call?.arguments !== "string") return null;
+  let args;
+  try {
+    args = JSON.parse(call.arguments);
+  } catch {
+    return null;
+  }
+  const value = args?.file_path ?? args?.path;
+  return typeof value === "string" && value.trim() !== "" ? value : null;
 }
 
 /**
- * 把三层游标对齐到当前的节点路径。
+ * 被这次替换收走的那一段里，读过和写过哪些文件。
  *
- * 一层的 key 变了（换节点了）就重建这个槽，游标落在**进入这一层那一刻的末尾节点**上；
- * 那一刻的末尾后面就是这个节点将要产生的全部内容，正是下一次折叠要收走的东西。
- *
- * 上层重建会顺带清空下层：上层一折叠，下层的一切就已经不在上下文里了，
- * 留着它的游标只会指向一个不存在的边界。
+ * 路径取自工具调用的 `file_path` / `path` 参数——界面列出文件变更用的是同一个来源。
+ * 只认读写文件的工具：`pwsh` / `bash` 这类命令里碰过什么文件看不出来，不计入。
  *
  * @param session - 当前会话。
- * @param cursors - `store.readSurfaces()` 读出来的游标对象，**就地修改**。
- * @param active - `activePath(plan)` 的结果；`null` 表示整棵树已结束。
- * @returns 是否有改动（调用方据此决定要不要写盘）。
+ * @param shadowed - 被收走的节点 seq，按位置顺序。
+ * @returns `{ read, write }`，各是去重后的路径数组，按出现顺序。
  */
-export function syncCursors(session, cursors, active) {
-  const tail = tailSeq(session);
-  let changed = false;
-  let outerRebuilt = false;
-
-  for (const level of LEVELS) {
-    const key = active?.[level]?.id ?? null;
-    const slot = cursors[level] ?? null;
-    // `Object.hasOwn` 同时挡住旧格式留下的槽：那种槽没有 cursor 字段，
-    // 直接当成没对齐、重建一次就好，不必迁移磁盘上的文件。
-    const aligned =
-      slot !== null && key !== null && slot.key === key && Object.hasOwn(slot, "cursor");
-    if (aligned && !outerRebuilt) continue;
-
-    // 外层一旦重建（或清空），内层的边界就已经并进外层了，无论 key 是否相同都要重来。
-    outerRebuilt = true;
-    if (key === null) {
-      if (slot !== null) {
-        cursors[level] = null;
-        changed = true;
-      }
-      continue;
+export function touchedFiles(session, shadowed) {
+  const read = new Set();
+  const write = new Set();
+  for (const seq of shadowed) {
+    const event = session.eventAt(seq);
+    if (event?.type !== "assistant/message") continue;
+    for (const part of event.data?.message?.content ?? []) {
+      if (part?.type !== "tool-call") continue;
+      const path = filePathOf(part);
+      if (path === null) continue;
+      if (WRITE_TOOLS.has(part.name)) write.add(path);
+      else if (READ_TOOLS.has(part.name)) read.add(path);
     }
-    cursors[level] = { key, cursor: tail };
-    changed = true;
   }
-
-  return changed;
+  return { read: [...read], write: [...write] };
 }
 
 /**
- * 造一条汇总消息：它取代的是一段执行过程，携带的是那段过程提交的结果。
+ * 造一条汇总消息：它取代的是一段执行过程，携带的是"收走了什么"。
  *
  * 形态是 `notice` + `summary`：界面把它渲染成一行可读的说明，展开才是正文。
  * 刻意**不用** `snapshot`——那个形态是"运行时上下文快照"的专属标签，
@@ -166,143 +153,165 @@ export function summaryMessage(id, text, summary) {
 }
 
 /**
- * 这一层从 `fromKey` 起、连续已结束的节点。
+ * 汇总消息的正文：这一次收走了多少条过程上下文，以及那一段里读写过哪些文件。
  *
- * 一个 key 和下一个 key 之间可能挤着好几个节点——模型一轮里连着完成两个子任务，
- * 或者中间那个被丢弃了。它们同属一段执行过程，收成一条汇总就够。
+ * 文件列表是给后面用的——过程收走了，但"这活碰过哪些文件"得留下，
+ * 否则模型要从头再找一遍。
  *
- * 只在**同一父节点下按树里的顺序**往后数，遇到第一个还没结束的节点就停：
- * 那正是这一层现在的活跃节点。
+ * @param count - 被这次替换收走的节点条数。
+ * @param files - `touchedFiles()` 的结果。
+ * @returns 正文文本，可能多行。
+ */
+function renderSummary(count, files) {
+  const lines = [`${NOTICE_PREFIX}隐藏了${count}条过程上下文。`];
+  if (files.read.length > 0) lines.push(`读取：${files.read.join("、")}`);
+  if (files.write.length > 0) lines.push(`写入：${files.write.join("、")}`);
+  return lines.join("\n");
+}
+
+/**
+ * 汇总消息的一行摘要，给界面折叠标题用。
  *
- * @param plan - 计划树。
- * @param level - `goal` / `task` / `step`。
- * @param fromKey - 这一层上一次的活跃节点 id。
- * @returns 已结束的节点，按树里的顺序；没有就返回空数组。
+ * @param count - 被这次替换收走的节点条数。
+ * @param files - `touchedFiles()` 的结果。
+ * @returns 一行摘要。
  */
-export function closedFrom(plan, level, fromKey) {
-  const goal = plan?.goal;
-  if (goal === undefined || goal === null) return [];
+function summaryLine(count, files) {
+  const touched = files.read.length + files.write.length;
+  const base = `树形任务流 · 隐藏了${count}条过程上下文`;
+  return touched === 0 ? base : `${base} · 涉及 ${touched} 个文件`;
+}
 
-  if (level === "goal") {
-    return goal.id === fromKey && isClosed(goal) ? [goal] : [];
+/**
+ * 找这一次要折叠的区间。
+ *
+ * 从末尾往前找两次边界调用：**最近的那次必须是 `tree_task_done`**（它就是这次完成的
+ * 那一下），再往前那次（create / plan / done 都算）是起点。两次调用之间的过程才是要收的。
+ * 起点那次调用自己的 `tool/result` 也算这次调用的一部分，一并跳过。
+ *
+ * 表层上找不到更早的边界调用时（比如它已经被压缩遮掉），起点退回表层第一个节点之后
+ * ——那时区间多半会撞上真人消息，于是整段不折，这是安全的那一侧。
+ *
+ * @param session - 当前会话。
+ * @returns `{ from, to, shadowed }`；这一轮不该折时返回 null。
+ */
+export function foldRange(session) {
+  const nodes = session.surface?.nodes ?? [];
+  if (typeof session.eventAt !== "function" || nodes.length === 0) return null;
+
+  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;
+    break;
   }
-
-  const list =
-    level === "task" ? (goal.tasks ?? []) : (findNode(plan, fromKey)?.task?.steps ?? []);
-  const start = list.findIndex((node) => node.id === fromKey);
-  if (start === -1) return [];
-
-  const out = [];
-  for (let index = start; index < list.length; index += 1) {
-    if (!isClosed(list[index])) break;
-    out.push(list[index]);
+  if (endIdx === -1) return null;
+
+  // 起点：上一次边界调用之后。找不到就退回表层第一个节点之后（节点 0 是系统提示词，
+  // 受 DSH 的重写保护，不能进替换区间）。
+  //
+  // 还要跳过紧邻的两样东西：那次调用自己的 `tool/result`，以及**上一次折叠落下的通告**
+  // ——后者虽然夹在两次边界调用之间，却已经是收过的结果，再收一次就会一轮轮空折下去。
+  let from = startIdx === -1 ? 1 : startIdx + 1;
+  while (from < endIdx) {
+    const event = session.eventAt(nodes[from]);
+    if (event?.type === "tool/result" || isPluginNotice(event)) {
+      from += 1;
+      continue;
+    }
+    break;
   }
-  return out;
+  const to = endIdx - 1;
+  if (from > to) return null;
+
+  return { from, to, shadowed: nodes.slice(from, to + 1) };
 }
 
 /**
- * 汇总消息的正文：这些节点各自提交了什么。
+ * 折一次：把边界调用之间那一段过程收走，换成一条说明收走了什么的短消息。
  *
- * 正处在检查点上时，把检查点提示一并附上——那一刻模型正需要知道"这一层只剩
- * 拆子节点和提交结果两条路"，而这条消息就是它接下来唯一会读到的说明。
+ * 一轮最多折一次——折完这一段就已经不在上下文里了。
+ *
+ * @param ctx - 挂载本行的 Cordis 上下文，只用来记日志。
+ * @param session - 当前会话。
+ * @returns 是否真的替换了内容。
  */
-function renderSummary(level, nodes, plan) {
-  const label = LEVEL_LABEL[level];
-  const parts = [];
-
-  for (const node of nodes) {
-    parts.push(
-      node.status === "done"
-        ? `${label}「${node.title}」(${node.id}) 已完成，它的执行过程已从上下文里收起。`
-        : `${label}「${node.title}」(${node.id}) 已丢弃。`,
+export function foldOnce(ctx, session) {
+  const range = foldRange(session);
+  if (range === null) return false;
+
+  // 中间夹着真人消息：整段不折。往前折丢了需求，往后折丢了回应。
+  if (range.shadowed.some((seq) => isHumanMessage(session.eventAt(seq)))) return false;
+
+  const nodes = session.surface.nodes;
+  const files = touchedFiles(session, range.shadowed);
+  try {
+    session.append(
+      "user/message",
+      summaryMessage(
+        foldId(),
+        renderSummary(range.shadowed.length, files),
+        summaryLine(range.shadowed.length, files),
+      ),
+      {
+        surfaceOp: { op: "replace", startSeq: nodes[range.from], endSeq: nodes[range.to] },
+        sourceEventSeqs: range.shadowed,
+      },
     );
-    const result = node.result?.text;
-    if (typeof result === "string" && result !== "") parts.push(`结果：\n${result}`);
+    return true;
+  } catch (error) {
+    // 注入失败不能拖垮会话，原区间原样留着，下一轮还有机会。
+    ctx.logger?.warn?.(`dsh-tree-task-flow: 折叠失败，保留原区间：${String(error?.message ?? error)}`);
+    return false;
   }
-
-  if (checkpointOf(plan) !== null) parts.push(renderContinue(plan));
-  return parts.join("\n\n");
-}
-
-/** 汇总消息的一行摘要，给界面折叠标题用。 */
-function summaryLine(level, nodes) {
-  const label = LEVEL_LABEL[level];
-  if (nodes.length === 1) return `树形任务流 · ${label}「${nodes[0].title}」已完成`;
-  return `树形任务流 · ${nodes.length} 个${label}已完成`;
 }
 
 /**
- * 把刚结束那一层折起来。
- *
- * 判定只有一条：某一层的 key 和 `activePath` 对不上，就说明这一层换节点了，
- * 刚过去的那个节点（连同它后面连续结束的兄弟）已经做完。
- *
- * 从外往里走，**碰到第一层换了就停**：外层的折叠范围一直覆盖到末尾，
- * 内层的一切本来就在里面，再折一次只会把外层刚落下的汇总又卷走。
- * 剩下的交给 `syncCursors` 重建游标。
+ * 把三层游标对齐到当前的节点路径。
  *
- * 折叠失败或无从折叠时降级为追加，见 `foldRange` 的说明。
+ * 游标**不参与折叠区间的计算**（那由 `foldRange` 在表层上现算），它只记"这一层走到
+ * 哪儿了"，给界面和排查用。一层的 key 变了（换节点了）就重建这个槽，游标落在
+ * **进入这一层那一刻的末尾节点**上。
  *
- * 折叠必须用**换节点之前**的游标，所以这一步要跑在 `syncCursors` 前面。
+ * 上层重建会顺带重建下层：上层一换，下层的边界就已经并进上层了。
  *
- * @param ctx - 挂载本行的 Cordis 上下文，只用来记日志。
  * @param session - 当前会话。
- * @param cursors - 游标状态，**就地修改**。
- * @param plan - 计划树。
- * @param active - `activePath(plan)`；`null` 表示整棵树已结束。
- * @returns 是否有改动。
+ * @param cursors - `store.readSurfaces()` 读出来的游标对象，**就地修改**。
+ * @param active - `activePath(plan)` 的结果；`null` 表示整棵树已结束。
+ * @returns 是否有改动（调用方据此决定要不要写盘）。
  */
-export function foldFinishedLevels(ctx, session, cursors, plan, active) {
+export function syncCursors(session, cursors, active) {
+  const tail = tailSeq(session);
   let changed = false;
+  let outerRebuilt = false;
 
   for (const level of LEVELS) {
     const key = active?.[level]?.id ?? null;
     const slot = cursors[level] ?? null;
+    // `Object.hasOwn` 同时挡住旧格式留下的槽：那种槽没有 cursor 字段，
+    // 直接当成没对齐、重建一次就好，不必迁移磁盘上的文件。
+    const aligned =
+      slot !== null && key !== null && slot.key === key && Object.hasOwn(slot, "cursor");
+    if (aligned && !outerRebuilt) continue;
 
-    // 还没有游标的层没有历史可折：第一次进入这一层由 syncCursors 立游标。
-    if (slot === null || !Object.hasOwn(slot, "cursor")) continue;
-    if (slot.key === key) continue;
-
-    const finished = closedFrom(plan, level, slot.key);
-    if (finished.length > 0) {
-      const range = foldRange(session, slot.cursor);
-
-      // 折得动就替换：执行过程从上下文里消失，换成一条携带结果的汇总。
-      // 折不动（游标已被压缩遮掉，或游标之后本就没有节点）就**只追加**：
-      // 那时没有可替换的区间，但提交的结果必须进上下文——否则模型再也看不到
-      // 这个节点产出了什么。收不起来可以，丢掉结果不行。
-      const intent =
-        range === null
-          ? { surfaceOp: "append" }
-          : {
-              surfaceOp: { op: "replace", startSeq: range.startSeq, endSeq: range.endSeq },
-              sourceEventSeqs: range.shadowed,
-            };
-
-      try {
-        const node = session.append(
-          "user/message",
-          summaryMessage(
-            foldId(),
-            renderSummary(level, finished, plan),
-            summaryLine(level, finished),
-          ),
-          intent,
-        );
-        // 游标停在刚落下的汇总上：下一次同级折叠从它**之后**开始，
-        // 所以这一条汇总不会被那一次卷走。
-        cursors[level] = key === null ? null : { key, cursor: node.seq };
+    // 外层一旦重建（或清空），内层的边界就已经并进外层了，无论 key 是否相同都要重来。
+    outerRebuilt = true;
+    if (key === null) {
+      if (slot !== null) {
+        cursors[level] = null;
         changed = true;
-      } catch (error) {
-        // 注入失败不能拖垮会话，也不能把游标推走——推走了这段过程就再也折不掉。
-        ctx.logger?.warn?.(
-          `dsh-tree-task-flow: 折叠 ${level} 失败，保留原区间：${String(error?.message ?? error)}`,
-        );
       }
+      continue;
     }
-
-    // 外层换了，内层的边界已经并进这一层，剩下的交给 syncCursors。
-    break;
+    cursors[level] = { key, cursor: tail };
+    changed = true;
   }
 
   return changed;
@@ -327,13 +336,12 @@ export function registerRegion(ctx, { store }) {
     const plan = store.readPlan(sessionId);
     if (plan === null) return decision;
 
-    const cursors = store.readSurfaces(sessionId);
-    const active = activePath(plan);
+    // 折叠只看表层：边界调用之间那一段过程。
+    let changed = foldOnce(ctx, session);
 
-    // 顺序不能颠倒：折叠要读**换节点之前**的游标，而 syncCursors 一跑就把游标
-    // 推到当前末尾，那时再也没有折叠的起点了。
-    let changed = foldFinishedLevels(ctx, session, cursors, plan, active);
-    if (syncCursors(session, cursors, active)) changed = true;
+    // 三层游标照旧维护，它是给界面看的，不参与上面那次判断。
+    const cursors = store.readSurfaces(sessionId);
+    if (syncCursors(session, cursors, activePath(plan))) changed = true;
 
     if (changed) {
       cursors.sessionId = sessionId;

package/lib/store.js

@@ -56,6 +56,22 @@ function writeJson(file, value) {
   renameSync(tmp, file);
 }
 
+/**
+ * 老结构（整棵树只有一个 `goal` 字段）读进来时升级成 `goals` 数组。
+ *
+ * 计划文件是插件自己的持久状态，换个版本不该让既有的树失联。
+ *
+ * @param plan - 磁盘上读到的对象，可能是 null。
+ * @returns 归一化后的计划树。
+ */
+function normalizePlan(plan) {
+  if (plan === null || typeof plan !== "object") return plan;
+  if (Array.isArray(plan.goals)) return plan;
+  if (plan.goal === undefined || plan.goal === null) return { ...plan, goals: [] };
+  const { goal, ...rest } = plan;
+  return { ...rest, version: 2, goals: [goal] };
+}
+
 /**
  * 建一个 store。一个插件实例一个，所有路径都在 root 下。
  *
@@ -78,7 +94,7 @@ export function createStore(root) {
      */
     readPlan(sessionId) {
       if (!sessionId) return null;
-      return readJson(file("plans", `${sessionId}.json`), null);
+      return normalizePlan(readJson(file("plans", `${sessionId}.json`), null));
     },
 
     /**
@@ -96,15 +112,13 @@ export function createStore(root) {
      * 层级固定为 目标 → 任务 → 子任务，每层一个槽。槽的形状是 `{ key, cursor }`：
      *
      *   - `key`    该层当前节点的 id。与上一轮不同就说明这一层换了节点。
-     *   - `cursor` 该层折叠的起点：折叠时从它**之后**替换到末尾，它自己留在 surface 上。
-     *              初值是**进入这一层那一刻 surface 的末尾节点**，之后每折叠一次就
-     *              更新为刚落下的那条汇总消息。所以它指向的**不一定是本插件放下的
-     *              汇总消息**——第一次折叠之前，它可能指向别的生产者留下的节点。
-     *              也正因为它停在边界上，同级上一次的汇总消息才不会被这一次折叠卷走。
-     *              为 null 表示进入这一层时 surface 还是空的，没有可保留的边界。
+     *   - `cursor` 进入这一层那一刻 surface 的末尾节点。
      *
      * 槽本身为 null 表示这一层还没开始，或整棵树已经结束。
      *
+     * 它**不参与折叠**：折叠区间由 `region.foldRange()` 在表层上现算（边界调用之间那
+     * 一段过程）。这里记的只是"这一层走到哪儿了"，给界面和排查用。
+     *
      * @param sessionId - 会话 id。
      * @returns `{ sessionId, goal, task, step, updatedAt }`。
      */