dsh-tree-task-flow 0.3.12 → 0.3.14

package/lib/plan.js

@@ -7,8 +7,10 @@
  * **谁是"当前节点"是推导出来的，不是存的**（`activePath`）——
  * 少一个需要同步的状态，就少一类 bug。
  *
- * 一个节点完成时必须提交 `result`（这个节点产出了什么）。插件据此把
- * 它的执行过程从上下文里折叠掉，换成一条携带该结果的汇总消息。
+ * 一个节点完成时必须提交 `result`（这个节点产出了什么）。它提交在这次
+ * `tree_task_done` 调用的参数里，而那次调用是折叠边界、不会被收走，所以
+ * 结果**留得住**；插件收走的是它前面那段执行过程。树渲染里也会把结果原样
+ * 列出来（**不截断**），让 `tree_task_status` 随时能把交付内容重新摆到眼前。
  *
  * **子节点全部结束时，父节点不自动完成。** 那一刻转入**检查点**：
  * 模型要么继续给父节点拆新的子节点，要么提交父节点的结果并完成它。
@@ -353,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 },
+  };
+}
+
 /**
  * 改一个节点的标题或说明。
  *
@@ -460,54 +510,118 @@ function checkpointNote(checkpoint) {
   );
 }
 
-/** 节点状态的中文短标记。 */
+/**
+ * 节点状态的短标记。
+ *
+ * 写成 `[ ]` / `[x]` 是**故意的**：整棵树用 Markdown 的嵌套任务清单渲染，
+ * 这两个标记在界面上会render成可以勾选的方框。`[-]` 不是标准任务清单标记，
+ * 会原样显示成 `[-]`——丢弃的节点本来就该看着"不是个正常的框"。
+ */
 function mark(node) {
   if (node.status === STATUS.DONE) return "[x]";
   if (node.status === STATUS.DROPPED) return "[-]";
   return "[ ]";
 }
 
-/** 结果取首行，超长截断——树上只报"产出了什么"，全文在上下文里的汇总消息里。 */
-function firstLine(text, limit = 120) {
-  const line = String(text ?? "").split("\n")[0].trim();
-  return line.length > limit ? `${line.slice(0, limit)}…` : line;
+/** 每一层的缩进宽度：两个空格，Markdown 嵌套列表的常规写法。 */
+const INDENT = "  ";
+
+/**
+ * 一个节点的「说明 / 结果」字段，作为该列表项的下一层条目挂进去。
+ *
+ * **全文输出，一个字都不截。** `result` 是这个节点交付的全部文字，截掉半句
+ * 就等于没交付。多行文本逐行输出；空行也要带上缩进，否则 Markdown 会认为
+ * 列表项到此为止，后面的内容会被甩出列表。
+ *
+ * @param lines - 输出行数组，就地追加。
+ * @param ownerIndent - 所属节点那一行的缩进层数。
+ * @param label - 「说明」或「结果」。
+ * @param text - 正文；空值不输出。
+ */
+function pushField(lines, ownerIndent, label, text) {
+  const rows = String(text ?? "")
+    .replace(/\r\n?/gu, "\n")
+    .split("\n");
+  while (rows.length > 0 && rows[rows.length - 1].trim() === "") rows.pop();
+  if (rows.length === 0) return;
+
+  const pad = INDENT.repeat(ownerIndent + 1);
+  lines.push(`${pad}- **${label}**：${rows[0]}`);
+  for (const row of rows.slice(1)) {
+    lines.push(row === "" ? pad : `${pad}${INDENT}${row}`);
+  }
 }
 
 /**
- * 把整棵树渲染成给模型看的文本。
+ * 渲染一个目标。
  *
- * @param plan - 计划树；null 表示还没有计划。
- * @returns 多行文本。
+ * 输出是**规范的 Markdown 嵌套任务清单**（`- [ ]` 一层两个空格），复制出去
+ * 就能正常预览——之前的写法靠纯空格缩进，四空格起就被 Markdown 当成代码块。
+ *
+ * @param goal - 目标节点。
+ * @param plan - 整棵计划树，用来标出"当前"落在哪。
+ * @param expand - `false` 时只渲染目标自己这一级（不含它下面的任务与子任务）。
+ * @returns 多行 Markdown 文本。
  */
-export function renderTree(plan) {
-  const goals = goalsOf(plan);
-  if (goals.length === 0) return "（还没有计划。先用 tree_task_create 建立目标与任务。）";
+export function renderGoal(goal, plan, expand = true) {
   const active = activePath(plan);
   const checkpoint = checkpointOf(plan);
   const lines = [];
 
-  for (const goal of goals) {
-    lines.push(`${mark(goal)} 目标  ${goal.id}  ${goal.title}`);
-    if (goal.detail) lines.push(`       ${goal.detail}`);
-    if (goal.result) lines.push(`       结果: ${firstLine(goal.result.text)}`);
-
-    for (const task of goal.tasks ?? []) {
-      const taskHere = active?.task?.id === task.id || checkpoint?.node?.id === task.id;
-      lines.push(`  ${mark(task)} 任务  ${task.id}  ${task.title}${taskHere ? " ← 当前" : ""}`);
-      if (task.result) lines.push(`        结果: ${firstLine(task.result.text)}`);
-      const steps = task.steps ?? [];
-      if (steps.length === 0 && isOpen(task)) {
-        lines.push("        （还没有子节点 → 调用 tree_task_plan）");
-      }
-      for (const step of steps) {
-        lines.push(`    ${mark(step)} 子任务  ${step.id}  ${step.title}${active?.step?.id === step.id ? " ← 当前" : ""}`);
-        if (step.result) lines.push(`          结果: ${firstLine(step.result.text)}`);
-      }
+  const goalHere = active?.goal?.id === goal.id;
+  lines.push(`- ${mark(goal)} **目标** \`${goal.id}\` ${goal.title}${goalHere ? " ← 当前" : ""}`);
+  pushField(lines, 0, "说明", goal.detail);
+  pushField(lines, 0, "结果", goal.result?.text);
+  if (expand !== true) return lines.join("\n");
+
+  for (const task of goal.tasks ?? []) {
+    const taskHere = active?.task?.id === task.id || checkpoint?.node?.id === task.id;
+    lines.push(
+      `${INDENT}- ${mark(task)} **任务** \`${task.id}\` ${task.title}${taskHere ? " ← 当前" : ""}`,
+    );
+    pushField(lines, 1, "结果", task.result?.text);
+
+    const steps = task.steps ?? [];
+    if (steps.length === 0 && isOpen(task)) {
+      lines.push(`${INDENT.repeat(2)}- 还没有子节点，用 tree_task_plan 补上`);
+    }
+    for (const step of steps) {
+      const stepHere = active?.step?.id === step.id;
+      lines.push(
+        `${INDENT.repeat(2)}- ${mark(step)} **子任务** \`${step.id}\` ${step.title}${stepHere ? " ← 当前" : ""}`,
+      );
+      pushField(lines, 2, "结果", step.result?.text);
     }
   }
   return lines.join("\n");
 }
 
+/**
+ * 渲染计划树。
+ *
+ * 默认把**已经结束的目标**收成目标那一级：一个会话跑久了会有好几个做完的目标，
+ * 每个都摊开会把树变成一大坨没人看的文字。要某个目标的完整树就指名它。
+ *
+ * @param plan - 计划树；null 表示还没有计划。
+ * @param only - 只渲染这个 id 所在的目标，并展开到底；不传就是全部目标。
+ * @returns 多行 Markdown 文本。
+ */
+export function renderTree(plan, only = null) {
+  const goals = goalsOf(plan);
+  if (goals.length === 0) return "（还没有计划。用 tree_task_create 建立目标与任务。）";
+
+  const wanted = typeof only === "string" && only.trim() !== "" ? only.trim() : null;
+  if (wanted !== null) {
+    const found = findNode(plan, wanted);
+    if (found === null) {
+      return `找不到节点 ${wanted}。不带 id 调用可以看到本会话的全部目标。`;
+    }
+    return renderGoal(found.goal, plan, true);
+  }
+
+  return goals.map((goal) => renderGoal(goal, plan, isOpen(goal))).join("\n");
+}
+
 /**
  * 注入消息里的收尾提示。它接在完成通告后面，所以自带前置标点（`lead`）。
  *

package/lib/region.js

@@ -3,16 +3,21 @@
  *
  * 规则只有一条，**只看表层，与计划树无关**：
  *
- *     从「上一次 `tree_task_done` 之后的第一个 `tree_task_create`」之后，
+ *     从「上一次 `tree_task_done` 之后的第一条 `tree_task_create` 调用」之后，
  *     到本次 `tree_task_done` 之前，中间那一段过程收走。
  *
- * 更早没有 `tree_task_done` 时，起点取表层第一个 `tree_task_create`；区间里一次
+ * 更早没有 `tree_task_done` 时，起点取表层第一条 `tree_task_create`；区间里一次
  * `create` 都没有时，回退到上一次 `tree_task_done` 之后（更早没有 `done` 则是
  * 表层开头）。起点那次调用、以及本次 `done` 的调用与返回，都留在表层上——
  * 那是模型看"计划是什么、下一步干什么"的地方。
  *
- * 边界只有 `create` 与 `done` 两个：**`tree_task_plan` 不是边界**，它的调用与返回
- * 跟普通过程一样，落在区间里就被收走。
+ * 边界只有 `create` 与 `done` 两个：写树的 `tree_task_plan` **不是边界**，
+ * 它跟普通过程一样落在区间里就被收走。
+ *
+ * **为什么不能把 `create` 并进 `plan`**：起点取的是"上一次 done 之后最早的
+ * 那一次开工调用"，而 `plan` 每补一次步骤就调一次；并成一个工具之后，
+ * 每一次补步骤都会把起点往后推，`done` 与它之间那段过程就永远收不走。
+ * 靠"实参里有没有 `parentId`"去区分，也只是把认错起点的机会交给模型。
  *
  * 判定表见 `docs/06-折叠范围规则.md`。
  *
@@ -25,7 +30,7 @@
  *
  *     [节点 0] 系统提示词
  *     [用户消息]
- *     [tree_task_create 调用]  [返回：计划已建立 + 整棵树]
+ *     [tree_task_create 调用]  [返回：计划已建立 + 这个目标的树]
  *     [tree_task消息：隐藏了 12 条过程上下文。读取：… 写入：…]
  *     [tree_task_done 调用]    [返回：接下来需要进行步骤：「二」(s-4)。]
  *     [当前这一段执行过程]     ← 下一次折叠的对象
@@ -62,17 +67,52 @@ export const PLUGIN = "dsh-tree-task-flow";
  */
 export const PLUGIN_SOURCE_KIND = `plugin:${PLUGIN}`;
 
+/**
+ * 界面上那一行摘要的统一前缀。
+ *
+ * 折叠、压缩、恢复续行、计划续行、中断拉起、中断重试——本插件往会话里放的通知不止一种，
+ * 界面上都是一行摘要。**前缀只在这里加一次**：调用点写自己的裸标签
+ * （「恢复续行」「中断拉起」），谁都别再手写它，否则迟早有一条漏掉或者写成两遍。
+ */
+export const SUMMARY_PREFIX = "树形任务流 · ";
+
+/**
+ * 给一个裸标签配上统一前缀，得到界面上真正显示的那一行。
+ *
+ * @param label - 裸标签，例如「恢复续行」。
+ * @returns 带前缀的摘要文本。
+ */
+export function noticeSummary(label) {
+  return `${SUMMARY_PREFIX}${label}`;
+}
+
+/**
+ * 这条 source 的摘要是不是某个标签。
+ *
+ * **带不带前缀都认**：升级之前落在会话里的那几条摘要没有前缀，
+ * 而按摘要做匹配的地方（收走失败尝试时找那条拉起消息）得能认出它们。
+ *
+ * @param source - 消息的 source。
+ * @param label - 裸标签。
+ * @returns 命中为 true。
+ */
+export function hasSummary(source, label) {
+  if (typeof source?.summary !== "string") return false;
+  return source.summary === label || source.summary === noticeSummary(label);
+}
+
 /**
  * 本插件一条 notice 消息的 source。
  *
  * 字段与老写法保持一致：`form: "notice"` 让界面渲染成可展开的一行说明，
- * `summary` 是那一行的文字。
+ * `summary` 是那一行的文字。**摘要一律走 {@link noticeSummary} 加前缀**——
+ * 界面上那一行必须自己说清是哪个插件发的，不能只写「恢复续行」。
  *
- * @param summary - 界面上显示的一行摘要。
+ * @param label - 界面上显示的那一行（不含前缀）。
  * @returns 消息 source。
  */
-export function pluginSource(summary) {
-  return { kind: PLUGIN_SOURCE_KIND, form: "notice", summary };
+export function pluginSource(label) {
+  return { kind: PLUGIN_SOURCE_KIND, form: "notice", summary: noticeSummary(label) };
 }
 
 /**
@@ -96,7 +136,7 @@ export function isPluginSource(source) {
 const LEVELS = ["goal", "task", "step"];
 
 /**
- * 边界调用：只有 `tree_task_create` 与 `tree_task_done`。它们的调用与返回不进替换区间，
+ * 边界调用：`tree_task_create` 与 `tree_task_done`。它们的调用与返回不进替换区间，
  * 是折叠的起止点。**`tree_task_plan` 不在其中**——它跟别的过程一样，落在区间里就被收走。
  */
 const BOUNDARY_TOOLS = new Set(["tree_task_create", "tree_task_done"]);
@@ -228,7 +268,7 @@ function renderSummary(count, files) {
 }
 
 /**
- * 汇总消息的一行摘要，给界面折叠标题用。
+ * 汇总消息的一行摘要（**不含统一前缀**——前缀由 `pluginSource` 加）。
  *
  * @param count - 被这次替换收走的节点条数。
  * @param files - `touchedFiles()` 的结果。
@@ -236,11 +276,22 @@ function renderSummary(count, files) {
  */
 function summaryLine(count, files) {
   const touched = files.read.length + files.write.length;
-  const base = `树形任务流 · 隐藏了${count}条过程上下文`;
+  const base = `隐藏了${count}条过程上下文`;
   return touched === 0 ? base : `${base} · 涉及 ${touched} 个文件`;
 }
 
-/** 这条 assistant 消息里有没有 `tree_task_create`。 */
+/**
+ * 这条 assistant 消息里有没有**新建目标**的那次 `tree_task_create`。
+ *
+ * 折叠起点只认这一种调用。**不能拿 `tree_task_plan` 顶替**：`plan` 在任务中途
+ * 反复调用（每补一次步骤就调一次），而起点取的是"上一次 done 之后最早的那次"，
+ * 于是每一次补步骤都会把起点往后推，`done` 与它之间那段过程永远收不走。
+ * 靠实参里有没有 `parentId` 去区分也只是把"认错起点"的机会交给了模型——
+ * 专门一个工具、按名字认，才是可靠的。
+ *
+ * @param event - 表层上的事件。
+ * @returns 是否新建了目标。
+ */
 function isCreateCall(event) {
   return toolNamesOf(event).includes("tree_task_create");
 }
@@ -250,8 +301,7 @@ function isCreateCall(event) {
  *
  * 从末尾往前找最近的一次边界调用，**它必须是 `tree_task_done`**（它就是这次完成的
  * 那一下）；再往前找上一次 `tree_task_done`，起点就是**它之后最早的那次
- * `tree_task_create`**——更早没有 `done` 时，起点是表层第一个 `tree_task_create`。
- * `tree_task_plan` 不是边界：它跟过程、工具结果一样落在区间里被收走。
+ * `tree_task_create`**——更早没有 `done` 时，起点是表层第一条 `tree_task_create`。
  *
  * 区间里一次 `create` 都没有时，起点退回上一次 `done` 之后（更早没有 `done`
  * 则是表层第一个节点之后）——那时区间多半会撞上真人消息，于是整段不折，这是安全的那一侧。

package/lib/settings.js

@@ -0,0 +1,53 @@
+/**
+ * 界面上的开关：**哪些键可以改**，以及怎么把它们并进配置。
+ *
+ * 单独成文件是为了让"可改的键"只有一份定义：`lib/index.js` 开机时用它把落盘的
+ * 选择并进配置，`lib/http.js` 收到面板的请求时用它校验键名。两处各写一份，
+ * 迟早会出现"界面能点、开机不认"或者反过来的错位。
+ *
+ * 优先级：**界面改过的（落盘）> profile 里的 config > DEFAULT_CONFIG**。
+ * 界面上改完还被 profile 顶回去，人会以为开关坏了。
+ *
+ * @module dsh-tree-task-flow/settings
+ */
+
+/**
+ * 面板可以改的键。
+ *
+ * 只收布尔开关：它们都是"要不要让插件自己动起来"这类事，改了立刻能看出效果，
+ * 也不需要额外解释。`maxAutoRounds` / `interruptDelaysMs` 这类带数值的旋钮
+ * 留在 profile 里——界面上给一个数字要配输入框与校验，不值当。
+ */
+export const SETTING_KEYS = ["autoContinue", "interruptRecovery"];
+
+/**
+ * 从一个对象里挑出认识的开关，且值必须是布尔。
+ *
+ * 落盘的 `settings.json` 可能被人手改坏、也可能是旧版本留下的键，
+ * 所以这里**只认名单上的键**，其余一概忽略；值不是布尔的也忽略，
+ * 免得一个 `"false"` 字符串把 `cfg.autoContinue !== true` 那种判断带偏。
+ *
+ * @param value - 待挑选的对象，通常是落盘的设置。
+ * @returns 只含合法键值的新对象；没有合法的就是 `{}`。
+ */
+export function pickSettings(value) {
+  const picked = {};
+  if (value === null || typeof value !== "object") return picked;
+  for (const key of SETTING_KEYS) {
+    if (typeof value[key] === "boolean") picked[key] = value[key];
+  }
+  return picked;
+}
+
+/**
+ * 把当前生效的开关压成面板要的形状。
+ *
+ * @param cfg - 合并后的配置。
+ * @returns `{ autoContinue, interruptRecovery }`，缺的按 false 报。
+ */
+export function settingsSnapshot(cfg) {
+  return {
+    autoContinue: cfg?.autoContinue === true,
+    interruptRecovery: cfg?.interruptRecovery === true,
+  };
+}

package/lib/store.js

@@ -6,6 +6,8 @@
  *   - `plans/<sessionId>.json`     计划树
  *   - `surfaces/<sessionId>.json`  三层的折叠游标（只给界面看，不参与折叠）
  *   - `held/<sessionId>.json`      「被按住」：暂停 / 停止，**要跨重启保留**
+ *   - `revive/<sessionId>.json`    意外中断的拉起重试链，**要跨重启保留**
+ *   - `settings.json`              界面上的开关，**跟会话无关**，整个状态根一份
  *
  * 计划属于建立它的那个会话。放到会话无关的位置，任何一个会话的计划都会被
  * 所有会话的 `agent/pre-step` 读到——那等于把不相干的节点指派塞进别人的上下文，
@@ -85,6 +87,12 @@ export function createStore(root) {
   /** 「被按住」状态的文件路径。 */
   const heldFile = (sessionId) => file("held", `${sessionId}.json`);
 
+  /** 意外中断重试链的文件路径。 */
+  const reviveFile = (sessionId) => file("revive", `${sessionId}.json`);
+
+  /** 设置文件的路径（与会话无关，整个状态根一份）。 */
+  const settingsFile = () => file("settings.json");
+
   /** 读「被按住」状态；读不到或文件坏了，一律按"没被按住"处理。 */
   function readHeldState(sessionId) {
     if (!sessionId) return { paused: false, stopped: false, at: null };
@@ -172,6 +180,43 @@ export function createStore(root) {
       writeJson(file("surfaces", `${sessionId}.json`), value);
     },
 
+    // ---- 设置：**与会话无关**，整个状态根一份 ----
+
+    /**
+     * 读界面上的开关。
+     *
+     * 为什么落盘：开关是"这台机器上的偏好"，重启一次就忘掉等于没有这个开关。
+     * 它在 `apply()` 里盖在 profile 的 config 之上——**人在界面上的选择优先**，
+     * 否则界面改完、profile 一改又被顶回去，人会以为开关坏了。
+     *
+     * 只认自己认识的键：文件里多出别的字段一律忽略，坏文件当空。
+     *
+     * @returns `{ autoContinue?, interruptRecovery?, at? }`；没改过就是 `{}`。
+     */
+    readSettings() {
+      const value = readJson(settingsFile(), null);
+      if (value === null || typeof value !== "object") return {};
+      return value;
+    },
+
+    /**
+     * 改几个开关，其余保持磁盘上的原样（读改写，与 `patchHeld` 同一个道理：
+     * 两个开关分属两条路径，谁都不能整份覆盖）。
+     *
+     * @param patch - `{ autoContinue?, interruptRecovery? }`；没给的键不动。
+     * @returns 写入后的完整设置对象。
+     */
+    patchSettings(patch) {
+      const current = readJson(settingsFile(), null);
+      const next = current !== null && typeof current === "object" ? { ...current } : {};
+      for (const [key, value] of Object.entries(patch ?? {})) {
+        if (typeof value === "boolean") next[key] = value;
+      }
+      next.at = Date.now();
+      writeJson(settingsFile(), next);
+      return next;
+    },
+
     // ---- 「被按住」：暂停 / 停止。**要跨重启保留**，所以落盘 ----
 
     /**
@@ -216,5 +261,49 @@ export function createStore(root) {
       });
       return readHeldState(sessionId);
     },
+
+    // ---- 意外中断的拉起重试链：**要跨重启保留** ----
+
+    /**
+     * 读这个会话的重试链状态。
+     *
+     * 为什么不放内存：网络类中断的时刻表横跨 30 分钟，而这台机器上重启 dsh 是常事。
+     * 只留内存的话，重启一次这条链就断了，正好落在最需要它的场景上。
+     *
+     * @param sessionId - 会话 id。
+     * @returns `{ sessionId, turn, class, code, pending, attempts, hidden, updatedAt }`，
+     *   没有链时为 null。`class` 是 `network` / `tool` / `malformed` 之一。
+     */
+    readRevive(sessionId) {
+      if (!sessionId) return null;
+      const value = readJson(reviveFile(sessionId), null);
+      if (value === null || typeof value !== "object") return null;
+      return value;
+    },
+
+    /**
+     * 写重试链状态。
+     *
+     * @param sessionId - 会话 id。
+     * @param value - 完整状态；`null` 等同于 {@link clearRevive}。
+     */
+    writeRevive(sessionId, value) {
+      if (!sessionId) return;
+      if (value === null || typeof value !== "object") {
+        rmSync(reviveFile(sessionId), { force: true });
+        return;
+      }
+      writeJson(reviveFile(sessionId), { sessionId, ...value, updatedAt: Date.now() });
+    },
+
+    /**
+     * 丢掉这个会话的重试链。链正常结束（这一轮跑完了）或该停手时调用。
+     *
+     * @param sessionId - 会话 id。
+     */
+    clearRevive(sessionId) {
+      if (!sessionId) return;
+      rmSync(reviveFile(sessionId), { force: true });
+    },
   };
 }