dsh-tree-task-flow 0.3.13 → 0.3.15

package/lib/index.js

@@ -1,5 +1,5 @@
 /**
- * dsh-tree-task-flow —— 三级任务树：完成时提交结果，同时把执行过程折叠掉。
+ * dsh-tree-task-flow —— 三级任务树：完成[步骤/任务/需求]并折叠过程。
  *
  * 与 DSH 内置任务系统的差别在于**上下文的收放方式**：
  *
@@ -25,6 +25,7 @@ import { registerInterruptRecovery } from "./interrupt.js";
 import { registerPause } from "./pause.js";
 import { DEFAULT_ORDER, registerPromptSection } from "./prompt.js";
 import { registerRegion } from "./region.js";
+import { pickSettings } from "./settings.js";
 import { createStore, defaultRoot } from "./store.js";
 import { registerTools } from "./tools.js";
 
@@ -55,17 +56,16 @@ export const DEFAULT_CONFIG = {
   /**
    * 是否允许在模型停下时自动续行。
    *
-   * ★ **默认开启**。一条总规矩：**插件还没有配置界面，功能就不能默认关**——
-   * 默认关等于这个功能不存在，没人会去翻 YAML 把它打开。等哪天真做了配置界面，
-   * 再交给用户去配。
+   * ★ **默认关闭。** 它会趁你没说话的时候**往会话里推一条消息**、把模型再叫起来跑一轮，
+   * 是最需要人知情的一项。
    *
-   * 曾经担心"开着就停不下来"（用户按下停止、agent 回到 idle，插件立刻又把它拉起来）。
-   * **那个担心已经有闸门挡住了**：按停止会写 `held/<sessionId>.json` 的
-   * `stopped: true`（见 `auto-continue.js` 的 `agent/turn-stopping`），
-   * `agent/status` 一回 idle 就先看这个标记，是就一步都不动；真人再发一条消息才解除。
-   * 再加上 `maxAutoRounds` 的轮次上限，兜底不会变成脱缰。
+   * 这里曾经写死过一条规矩："插件还没有配置界面，功能就不能默认关"——默认关等于这个
+   * 功能不存在，没人会去翻 YAML 把它打开。**那条规矩随着设置界面一起作废**：现在面板上
+   * 就能点开，默认值该按"会不会打扰人"来定，而不是按"能不能被发现"。
+   *
+   * 想打开：面板上的设置里点一下，或在 profile 里写 `autoContinue: true`。
    */
-  autoContinue: true,
+  autoContinue: false,
   /** 连续自动续行的轮次上限，达到就停。 */
   maxAutoRounds: 5,
   /**
@@ -102,6 +102,13 @@ export function apply(ctx, config) {
   const root = cfg.rootDir ?? defaultRoot();
   const store = createStore(root);
 
+  // 面板上改过的开关盖在 profile 的 config 之上：**人在界面上的选择优先**。
+  // 不这么做的话，界面改完、profile 一改又被顶回去，人会以为开关坏了。
+  //
+  // `cfg` 是**活的对象**：面板改开关时就地改它，各模块拿的是同一个引用，
+  // 所以立刻生效，不用重启。这也是为什么各模块要按事件现读 `cfg`，不是开机读一次。
+  Object.assign(cfg, pickSettings(store.readSettings()));
+
   // 被显式关掉时，一个字节都不碰会话：不注册工具、不加提示词段落、不折叠上下文、
   // 不续行——只留一条命令，让人能确认"装了但被关掉了"以及怎么打开。
   if (cfg.enabled !== true) {
@@ -109,7 +116,7 @@ export function apply(ctx, config) {
     // 条目接口照挂：客户端条目与 enabled 无关，照样会来读。读不到计划它就返回
     // null，一个像素都不占；而既有的计划文件仍然能看到。
     // 只读插件自己的状态目录，不碰任何会话。
-    registerHttp(ctx, { store, autoContinue: null, pause: null });
+    registerHttp(ctx, { store, autoContinue: null, pause: null, cfg });
     ctx.logger?.warn?.(
       "dsh-tree-task-flow: 已按配置关闭（enabled=false）。要打开请在 profile 的 cordis.patch.yml 里把它设为 true。",
     );
@@ -142,15 +149,16 @@ export function apply(ctx, config) {
   // 意外中断的拉起：网络类按 1/5/10/30 分钟各一次，工具类（结果未知的合成错误）
   // 立刻一次，再失败就收走那一次尝试再来一次。它与 autoContinue 并存：
   // 那边管"模型正常收尾但计划没做完"，这边管"模型没机会说完就断了"。
-  if (cfg.interruptRecovery === true) {
-    registerInterruptRecovery(ctx, { store, cfg, pause });
-  }
+  //
+  // ★ **无条件注册**：开关（`interruptRecovery`）在面板上随时可改，注册与否取决于
+  // 它就没法在运行中打开。真正的闸门放在模块内部——事件来了先问一句 `cfg`。
+  registerInterruptRecovery(ctx, { store, cfg, pause });
 
   // /task-tree 命令：查看与管理任务树，也是"暂停 / 继续"的开关。
   registerCommands(ctx, { store, cfg, pause, enabled: true });
 
-  // 任务树条目要用的 HTTP 接口。
-  registerHttp(ctx, { store, autoContinue, pause });
+  // 任务树条目要用的 HTTP 接口。`cfg` 传进去是为了让面板能读到并改掉那几个开关。
+  registerHttp(ctx, { store, autoContinue, pause, cfg });
 
   ctx.logger?.info?.(`dsh-tree-task-flow: 已启用（状态目录 ${root}）`);
 }

package/lib/interrupt.js

@@ -198,6 +198,20 @@ export function registerInterruptRecovery(ctx, { store, cfg, pause = null }) {
     return active !== null && active.step !== null;
   }
 
+  /**
+   * 开关关着时整个模块都不动。
+   *
+   * 它是**面板上随时可改**的，所以每次事件现读 `cfg`，不能开机读一次就定死；
+   * 注册与否也不该取决于它（见 `lib/index.js` 里那句"无条件注册"）。
+   *
+   * 判据写成"**显式 false 才算关**"：这一项的默认值是开，缺字段的意思是"没配，
+   * 按默认走"，不该被当成关掉——直接构造这个模块的调用方（自检、以后别的入口）
+   * 往往只给一个 `{}`。
+   */
+  function off() {
+    return cfg?.interruptRecovery === false;
+  }
+
   /** 现在能不能拉：暂停 / 停止 / 没计划 / 没加载 / 不空闲，一条不满足就不拉。 */
   function blockedBy(sessionId) {
     if (pause?.isPaused?.(sessionId) === true) return "paused";
@@ -220,6 +234,7 @@ export function registerInterruptRecovery(ctx, { store, cfg, pause = null }) {
    * @returns `{ ok, reason?, text? }`。
    */
   function revive(sessionId, kind, code) {
+    if (off()) return { ok: false, reason: "disabled" };
     const blocked = blockedBy(sessionId);
     if (blocked !== null) return { ok: false, reason: blocked };
 
@@ -253,6 +268,7 @@ export function registerInterruptRecovery(ctx, { store, cfg, pause = null }) {
    * 一个不剩就把这条链标成用完。
    */
   function scheduleNext(sessionId) {
+    if (off()) return;
     clearTimer(sessionId);
     const state = store.readRevive(sessionId);
     if (state === null || state.class !== "network") return;
@@ -447,6 +463,7 @@ export function registerInterruptRecovery(ctx, { store, cfg, pause = null }) {
   // ---------------------------------------------------------------- 会话事件
 
   ctx.on("session/event", (session, event) => {
+    if (off()) return;
     const sessionId = session?.id;
     if (sessionId === undefined || event === undefined) return;
 
@@ -495,6 +512,7 @@ export function registerInterruptRecovery(ctx, { store, cfg, pause = null }) {
   // ---------------------------------------------------------------- agent 状态
 
   ctx.on("agent/status", (payload) => {
+    if (off()) return;
     const sessionId = payload?.agent?.session?.id;
     if (sessionId === undefined || payload?.status !== "idle") return;
 

package/lib/notes.js

@@ -0,0 +1,173 @@
+/**
+ * 笔记：跟工作有关、但不属于任何一条需求的事实与偏好。
+ *
+ * **跟着会话走**，不设全局层、不跨会话带——用户开新会话就不管旧会话了，这是设计不是缺陷。
+ * 偏好是"对产出的要求"，不是"关于用户的知识"，所以写进这里就够，不必另立体系。
+ *
+ * 纯逻辑模块：不碰 DSH、不碰磁盘。
+ *
+ * ## 为什么笔记要有 `key` 和 `rev`
+ *
+ * 折叠会把一段过程收成一条通告，通告里要带上"这段里动过的笔记"。于是同一条笔记可能：
+ * 先在较早的通告里出现（rev 1），后来又被改过（rev 2），两份通告都还在上下文里。
+ * 给每条笔记一个**短名字**和一个**修订号**，再在静态提示词里写死一句"同一名字以修订号大的
+ * 为准"，模型就不会拿旧值当新值。
+ *
+ * `seq` 记的是写这条笔记那一刻会话表层的末尾节点，折叠时靠它判断"这条笔记是不是落在
+ * 这个区间里"。
+ *
+ * @module dsh-tree-task-flow/notes
+ */
+
+/** 一条笔记的形状。 */
+export function makeNote(input, now = Date.now()) {
+  return {
+    key: String(input?.key ?? "").trim(),
+    text: String(input?.text ?? "").trim(),
+    rev: 1,
+    at: now,
+    seq: typeof input?.seq === "number" ? input.seq : null,
+  };
+}
+
+/**
+ * 读出来的笔记表补齐成当前形状。坏文件、缺字段一律当空，不让它拖垮会话。
+ *
+ * @param state - 磁盘上读到的对象，可能是 null。
+ * @returns `{ version, items, updatedAt }`。
+ */
+export function normalizeNotes(state) {
+  if (state === null || typeof state !== "object") {
+    return { version: 1, items: [], updatedAt: null };
+  }
+  const items = Array.isArray(state.items)
+    ? state.items
+        .filter((item) => item !== null && typeof item === "object")
+        .map((item) => ({
+          key: String(item.key ?? "").trim(),
+          text: String(item.text ?? ""),
+          rev: Number.isFinite(item.rev) ? item.rev : 1,
+          at: Number.isFinite(item.at) ? item.at : null,
+          seq: Number.isFinite(item.seq) ? item.seq : null,
+        }))
+        .filter((item) => item.key !== "")
+    : [];
+  return {
+    version: 1,
+    items,
+    updatedAt: Number.isFinite(state.updatedAt) ? state.updatedAt : null,
+  };
+}
+
+/**
+ * 写一条笔记：**同名就覆盖、修订号 +1**，不同名就新增。
+ *
+ * 当场返回结果——`tree_task_note` 的返回直接用它，不用等折叠。
+ *
+ * @param state - 笔记表（会被就地修改）。
+ * @param input - `{ key, text, seq? }`。
+ * @param now - 时间戳。
+ * @returns `{ ok, reason?, note?, created? }`。
+ */
+export function upsertNote(state, input, now = Date.now()) {
+  const key = String(input?.key ?? "").trim();
+  const text = String(input?.text ?? "").trim();
+  if (key === "") return { ok: false, reason: "笔记要有一个短名字（key），以后按它找" };
+  if (text === "") return { ok: false, reason: "笔记正文不能为空" };
+
+  const existing = state.items.find((item) => item.key === key);
+  if (existing === undefined) {
+    const note = makeNote({ key, text, seq: input?.seq }, now);
+    state.items.push(note);
+    state.updatedAt = now;
+    return { ok: true, note, created: true };
+  }
+
+  existing.text = text;
+  existing.rev += 1;
+  existing.at = now;
+  if (typeof input?.seq === "number") existing.seq = input.seq;
+  state.updatedAt = now;
+  return { ok: true, note: existing, created: false };
+}
+
+/**
+ * 查笔记：不给条件就是全部，给了就在名字与正文里找。
+ *
+ * @param state - 笔记表。
+ * @param query - 关键词（不分大小写）。
+ * @returns 笔记数组，按最后修改时间倒序。
+ */
+export function findNotes(state, query) {
+  const word = String(query ?? "").trim().toLowerCase();
+  const items = word === ""
+    ? [...state.items]
+    : state.items.filter(
+        (item) =>
+          item.key.toLowerCase().includes(word) || item.text.toLowerCase().includes(word),
+      );
+  return items.sort((a, b) => Number(b.at ?? 0) - Number(a.at ?? 0));
+}
+
+/**
+ * 某个表层区间里的笔记：`seq` 落在 `(from, to]` 里的那几条。
+ *
+ * 折叠时用它决定"这段通告要带哪些笔记"。没有 `seq` 的老笔记（迁移前写的）一律算进来——
+ * 宁可多带一条，也不能让笔记跟着被收走的过程一起消失。
+ *
+ * @param state - 笔记表。
+ * @param from - 区间起点 seq（不含）。
+ * @param to - 区间终点 seq（含）。
+ * @returns 笔记数组，按写入顺序。
+ */
+export function notesInRange(state, from, to) {
+  return state.items
+    .filter((item) => item.seq === null || (item.seq > from && item.seq <= to))
+    .sort((a, b) => Number(a.seq ?? 0) - Number(b.seq ?? 0));
+}
+
+/**
+ * 把笔记渲染成通告里那一段。
+ *
+ * 形状是**固定且可再解析的**：一行 `· 名字 (r修订号)：正文`。二次折叠时靠它把上一层通告里的
+ * 笔记捡回来，所以别随手改格式（`parseNoteLines` 认的就是它）。
+ *
+ * @param items - 笔记数组。
+ * @returns 多行文本；没有笔记时是空串。
+ */
+export function renderNoteLines(items) {
+  if (!Array.isArray(items) || items.length === 0) return "";
+  return items.map((item) => `· ${item.key} (r${item.rev})：${oneLine(item.text)}`).join("\n");
+}
+
+/**
+ * 从一段通告正文里把笔记捡回来。
+ *
+ * @param text - 通告正文。
+ * @returns 笔记数组 `{ key, rev, text }`。
+ */
+export function parseNoteLines(text) {
+  const rows = [];
+  const pattern = /^· (.+?) \(r(\d+)\)：(.*)$/u;
+  for (const line of String(text ?? "").split("\n")) {
+    const match = pattern.exec(line.trim());
+    if (match === null) continue;
+    rows.push({ key: match[1], rev: Number(match[2]), text: match[3] });
+  }
+  return rows;
+}
+
+/**
+ * 正文压成一行：通告里每条笔记只占一行，换行会把它拆成两条，再解析就错位了。
+ *
+ * @param text - 原文。
+ * @returns 单行文本。
+ */
+function oneLine(text) {
+  return String(text ?? "")
+    .replace(/\r\n?/gu, "\n")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line !== "")
+    .join(" / ");
+}

package/lib/pause.js

@@ -35,6 +35,20 @@
  * 唤醒要求该会话已被 DSH 加载成实时 agent（Web 界面打开这个会话就会触发按需
  * resume）。拿不到 agent 时不做任何事，只回一句"先打开它，或在其中发一条消息"。
  *
+ * ★ **点「继续」是无条件的。** "接着跑"是人的意思表示，不是"此刻有没有闸门挂着"
+ * 的一次查询。所以 `resume()` 的第一件事永远是**解除「被按住」**，然后才谈要不要
+ * 主动唤醒。
+ *
+ * 旧实现把这层意思押在了"此刻 `waiters` 里正好挂着一个"上：没有 waiter 就退到
+ * `wakeIdle()`，而它要求 agent 恰好 `idle`——会话正忙（工具还在跑、这一轮还没走到
+ * 岔口）时直接拒绝，并且**一个标记都不清**。于是那一次点击被静默吞掉：闸门在下一个
+ * 岔口照旧挂上，会话停住，人却以为自己已经点过了。实机就卡在这儿：
+ * session-c516e2cc 23:05:59 点了暂停，那个工具 23:07:03 才跑完，中间点的那次
+ * 「继续」白点了——等到闸门真挂上时，已经没人在等那一下点击。
+ *
+ * 唤醒失败也不再反过来把状态留下：留着只会让"我点过了它却还按着我"再来一次。
+ * 推不起来的原因照样如实回报（没加载 / 唤醒抛错 / 计划已收尾），人能据它决定下一步。
+ *
  * @module dsh-tree-task-flow/pause
  */
 
@@ -71,6 +85,18 @@ export function registerPause(ctx, { store = null, autoContinue = null } = {}) {
     store?.patchHeld?.(sessionId, { paused: false });
   }
 
+  /**
+   * 真解除"被按住"：暂停与停止两半一起清，内存、磁盘、自动续行压住的那一份都放开。
+   * 「继续」走的就是这一条，而且**无条件**（见模块头的 ★）。
+   *
+   * @param sessionId - 要放开的会话。
+   */
+  function clearHeld(sessionId) {
+    paused.delete(sessionId);
+    store?.patchHeld?.(sessionId, { paused: false, stopped: false });
+    autoContinue?.resume?.(sessionId);
+  }
+
   /**
    * 取这个会话的实时 agent。
    *
@@ -138,7 +164,13 @@ export function registerPause(ctx, { store = null, autoContinue = null } = {}) {
       };
     }
     if (agent.status !== "idle") {
-      return { woke: false, reason: "busy", text: "这个会话正在跑，不需要唤醒。" };
+      // 正忙不是失败：它自己会在下一个岔口接着跑，本来就不需要谁推它一把。
+      // 「被按住」已经由 `resume()` 无条件解除，所以这里什么都不用做。
+      return {
+        woke: false,
+        reason: "busy",
+        text: "这个会话正在跑，不用唤醒：被按住的状态已经解除，它会在下一个岔口接着往下跑。",
+      };
     }
     const plan = store?.readPlan?.(sessionId) ?? null;
     const active = activePath(plan);
@@ -215,28 +247,21 @@ export function registerPause(ctx, { store = null, autoContinue = null } = {}) {
         return { released: false, woke: false, reason: "no-session", text: "拿不到当前会话。" };
       }
 
-      /** 真解除"被按住"：暂停与停止两半一起清，连自动续行的压住也放开。 */
-      const clearHeld = () => {
-        paused.delete(sessionId);
-        store?.patchHeld?.(sessionId, { paused: false, stopped: false });
-        autoContinue?.resume?.(sessionId);
-      };
+      // ★ 先无条件解除"被按住"，再谈唤醒。理由见模块头那段 ★：点「继续」是一个
+      // 意思表示，不该有条件；有条件就会制造"点过了却还按着"的静默卡死。
+      clearHeld(sessionId);
 
-      // 本进程里真挂着：放行那一步——这是常规路径，**零新增消息**。
+      // 本进程里真挂着闸门：放行那一步——常规路径，**零新增消息**。
       const pending = waiters.get(sessionId);
       if (pending !== undefined && pending.size > 0) {
-        clearHeld();
         for (const release of [...pending]) release();
         return { released: true, woke: false, reason: "released", text: "停在岔口上的那一步已经放行。" };
       }
 
-      // 没有挂着的 waiter（进程重启过）：退一步唤醒 idle 的会话。
-      //
-      // **只有真把它推起来、或计划确实已经收尾，才解除"被按住"。** 没成功时
-      // （会话没加载 / 正在跑 / 唤醒抛错）必须把状态留着：否则用户既没有「继续」
-      // 可再点一次，也看不到为什么没动，只剩一个停在原地的会话。
+      // 没有挂着的 waiter：本进程里没有东西可放行（进程重启过，或者这次暂停赶在
+      // 闸门挂上之前——那时候点的那一下，旧实现会被吞掉）。退一步，尽最大努力把
+      // idle 的会话推起来；推不起来也不改变"已经解除被按住"这个事实。
       const outcome = wakeIdle(sessionId);
-      if (outcome.woke === true || outcome.reason === "finished") clearHeld();
       return { released: false, ...outcome };
     },
     /**
@@ -251,5 +276,49 @@ export function registerPause(ctx, { store = null, autoContinue = null } = {}) {
     isPaused(sessionId) {
       return heldNow(sessionId);
     },
+
+    /**
+     * 往会话里排一句话，把它推起来。**面板上的「开始」按钮走这里。**
+     *
+     * 与 `resume()` 的区别：`resume` 是"把按住的东西放开"，这里的语义是"从这条需求
+     * 开工"。会话正忙时不排——它自己会在下一个岔口继续；没被加载时也不排，回一句
+     * "先在界面上打开它"。
+     *
+     * @param sessionId - 目标会话。
+     * @param text - 要排进去的那句话。
+     * @param label - 界面上那行摘要的裸标签。
+     * @returns `{ woke, reason, text }`。
+     */
+    nudge(sessionId, text, label = "开始需求") {
+      if (sessionId === undefined) {
+        return { woke: false, reason: "no-session", text: "拿不到当前会话。" };
+      }
+      const agent = liveAgent(sessionId);
+      if (agent === null) {
+        return {
+          woke: false,
+          reason: "unloaded",
+          text: "这个会话还没被加载：先在界面上打开它，或在其中发一条消息。",
+        };
+      }
+      if (agent.status !== "idle") {
+        return {
+          woke: false,
+          reason: "busy",
+          text: "这个会话正在跑，不用再推它；它做完手上这一步就会接着往下走。",
+        };
+      }
+      try {
+        agent.followup({
+          id: `tt-nudge-${sessionId}-${Date.now().toString(36)}`,
+          role: "user",
+          content: [{ type: "text", text: String(text ?? "") }],
+          source: pluginSource(label),
+        });
+      } catch (error) {
+        return { woke: false, reason: "error", text: `唤醒失败：${String(error?.message ?? error)}` };
+      }
+      return { woke: true, reason: "woke", text: "已让它开始。" };
+    },
   };
 }

package/lib/plan.js

@@ -355,6 +355,54 @@ export function dropNode(plan, id, now = Date.now()) {
   };
 }
 
+/**
+ * 删掉一个节点。**删除和丢弃是两件事，别混着用：**
+ *
+ * - **丢弃**回答"这件事还要不要做"：节点留在树里划掉，将来还查得到"曾经有这么一件事，
+ *   后来决定不做了"。它不改写历史。
+ * - **删除**是**清理**：内容本身就是错的（建重了、写歪了、结果记在了错的地方），
+ *   留着只会误导后面的人。所以它把这个节点连同它的全部子孙从树里凭空摘掉，
+ *   **不看状态**——已完成的照样删得掉，那正是"这条记录不该留在这儿"的情形。
+ *
+ * 摘完树可能是空的（最后一个目标被删掉）：那时 `plan.goals` 是**空数组**，而不是
+ * 没有计划——计划文件照旧在盘上，渲染会给出"还没有计划"的样子。
+ *
+ * 活动路径与检查点在删完**重新算**，调用方不要拿删除前的那一份去用。
+ *
+ * @param plan - 计划树。
+ * @param id - 节点 id。
+ * @param now - 时间戳。
+ * @returns `{ ok, reason?, removed?, active?, checkpoint? }`。
+ */
+export function deleteNode(plan, id, now = Date.now()) {
+  const found = findNode(plan, id);
+  if (!found) return { ok: false, reason: `找不到节点 ${id}` };
+
+  // 先把要摘掉的那几个记下来——摘掉之后就找不着了。
+  const removed = [`${levelLabel(found.level)}「${found.node.title}」`];
+  if (found.level === "goal") {
+    for (const task of found.node.tasks ?? []) {
+      removed.push(`任务「${task.title}」`);
+      for (const step of task.steps ?? []) removed.push(`子任务「${step.title}」`);
+    }
+    plan.goals = goalsOf(plan).filter((goal) => goal.id !== id);
+  } else if (found.level === "task") {
+    for (const step of found.node.steps ?? []) removed.push(`子任务「${step.title}」`);
+    found.goal.tasks = (found.goal.tasks ?? []).filter((task) => task.id !== id);
+  } else {
+    found.task.steps = (found.task.steps ?? []).filter((step) => step.id !== id);
+  }
+  plan.updatedAt = now;
+
+  const checkpoint = checkpointOf(plan);
+  return {
+    ok: true,
+    removed,
+    active: activePath(plan),
+    checkpoint: checkpoint === null ? null : { id: checkpoint.node.id, level: checkpoint.level },
+  };
+}
+
 /**
  * 改一个节点的标题或说明。
  *

package/lib/prompt.js

@@ -1,7 +1,7 @@
 /**
- * 系统提示词段落：**只有一段**，讲的是"什么时候用这组工具、完成时守什么规矩"。
+ * 系统提示词段落：**只有一段**，讲的是"这组工具是什么、一次工作怎么开头、完成时守什么时机"。
  *
- * 工具清单**不在这里**——每个工具的用法由它自己的 `description` 承担。同一句话
+ * 工具清单与填法**不在这里**——每个工具怎么用由它自己的 `description` 承担。同一句话
  * 写在两处，只会让它在每一次请求里占两份位置，而模型真要调用时读的始终是
  * `description`。计划当前的状态同样不在这里，由 `tree_task_status` 现取。
  *
@@ -22,8 +22,24 @@ export const SECTION_NAME = "dsh-tree-task-flow";
  */
 export const DEFAULT_ORDER = 1800;
 
-/** 段落正文。 */
-export const SECTION_TEXT = "`tree_task_*` 工具适用长线任务，当目标和资料分析完成后，如果用户要求或判断任务较为复杂，可以将任务执行计划分为目标、任务、任务执行步骤三级写入任务树，借助工具来推进项目；将目标按照可独立交付的节点分为多个任务，任务节点需要准确表述清楚需求；将任务按照“需一次性处理并交付产物”分为多个步骤；完成步骤或任务时提交后续步骤需要的 result，提交内容可以是：产物/结论/问题/有哪些需要注意的坑；执行过程上下文将会在完成时被隐藏。";
+/**
+ * 段落正文。
+ *
+ * 只讲这次工作按什么顺序走、什么时候该动哪个工具，不讲工具怎么填——填法归各自的
+ * `description`。三个入口工具（状态、建草稿、改需求）在这里点名，其余仍交给描述：
+ * 光说"用工具"换不到指代明确，十来个字不值得省。
+ *
+ * 流水线：需求草稿 → update 多次修改（仍是草稿）→ confirm 生成版本 → 读资料 → start。
+ * 任务与步骤的拆分口径归 `plan`，result 写法归 `done`，笔记覆盖归 `note`。
+ */
+export const SECTION_TEXT =
+  "`tree_task_*` 工具记录这个会话的工作结构。需求记录用户提出的要求；任务与步骤记录实现路径；" +
+  "笔记记录不属于任何单条需求的工作事实与偏好。\n\n" +
+  "开工前先调用 tree_task_status 取回需求列表。用户提出要求后，先用 tree_task_create 记录需求草稿；" +
+  "草稿阶段用 tree_task_requirement 的 update 动作逐次修改正文，每次只给出要改的字段，修改后仍是草稿；" +
+  "标题与简介确定后，用同一工具的 confirm 动作确认并生成版本。确认之后，调用 tree_task_start 开始工作，" +
+  "调用前先读取所需的文件与文档。\n\n" +
+  "每完成一个步骤、任务或需求，调用一次 tree_task_done。";
 
 /**
  * 注册段落。调用方必须包在 `ctx.effect()` 里，否则热更新后会重复注册而抛错。