dsh-tree-task-flow 0.3.13 → 0.3.15

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

@@ -3,10 +3,12 @@
  *
  * 三类状态，都**以 `sessionId` 为键**：
  *
- *   - `plans/<sessionId>.json`     计划树
+ *   - `plans/<sessionId>.json`     计划树（需求都在里面的 `goals` 里）
+ *   - `notes/<sessionId>.json`     笔记，按会话一份
  *   - `surfaces/<sessionId>.json`  三层的折叠游标（只给界面看，不参与折叠）
  *   - `held/<sessionId>.json`      「被按住」：暂停 / 停止，**要跨重启保留**
  *   - `revive/<sessionId>.json`    意外中断的拉起重试链，**要跨重启保留**
+ *   - `settings.json`              界面上的开关，**跟会话无关**，整个状态根一份
  *
  * 计划属于建立它的那个会话。放到会话无关的位置，任何一个会话的计划都会被
  * 所有会话的 `agent/pre-step` 读到——那等于把不相干的节点指派塞进别人的上下文，
@@ -27,6 +29,8 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { normalizeNotes } from "./notes.js";
+import { normalizeRequirement } from "./requirement.js";
 
 /**
  * 没有显式配置时的状态根目录。
@@ -59,19 +63,29 @@ function writeJson(file, value) {
 }
 
 /**
- * 老结构（整棵树只有一个 `goal` 字段）读进来时升级成 `goals` 数组。
+ * 老结构（整棵树只有一个 `goal` 字段）读进来时升级成 `goals` 数组，
+ * 再给每条记录补上需求那一层缺的字段。
  *
- * 计划文件是插件自己的持久状态，换个版本不该让既有的树失联。
+ * 计划文件是插件自己的持久状态，换个版本不该让既有的树失联——所以**读的时候补，
+ * 不迁移磁盘上的老文件**：老会话的计划文件保持原样，缺什么字段就在内存里补什么，
+ * 下一次写入自然带上（见 `requirement.normalizeRequirement`）。
  *
  * @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] };
+  let upgraded = plan;
+  if (!Array.isArray(plan.goals)) {
+    if (plan.goal === undefined || plan.goal === null) {
+      upgraded = { ...plan, goals: [] };
+    } else {
+      const { goal, ...rest } = plan;
+      upgraded = { ...rest, version: 2, goals: [goal] };
+    }
+  }
+  for (const goal of upgraded.goals) normalizeRequirement(goal);
+  return upgraded;
 }
 
 /**
@@ -89,6 +103,12 @@ export function createStore(root) {
   /** 意外中断重试链的文件路径。 */
   const reviveFile = (sessionId) => file("revive", `${sessionId}.json`);
 
+  /** 设置文件的路径（与会话无关，整个状态根一份）。 */
+  const settingsFile = () => file("settings.json");
+
+  /** 笔记文件的路径（按会话一份）。 */
+  const notesFile = (sessionId) => file("notes", `${sessionId}.json`);
+
   /** 读「被按住」状态；读不到或文件坏了，一律按"没被按住"处理。 */
   function readHeldState(sessionId) {
     if (!sessionId) return { paused: false, stopped: false, at: null };
@@ -176,6 +196,70 @@ 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;
+    },
+
+    // ---- 笔记：**按会话**，一个会话一份 ----
+
+    /**
+     * 读这个会话的笔记。
+     *
+     * 笔记跟着会话走：它记的是"这次工作的上下文里必须一直记着的几句话"，
+     * 换一个会话就等于换了一份工作，旧笔记跟过去只会变成噪声。
+     *
+     * @param sessionId - 会话 id。
+     * @returns `{ version, items, updatedAt }`；没有笔记时 `items` 是空数组。
+     */
+    readNotes(sessionId) {
+      if (!sessionId) return normalizeNotes(null);
+      return normalizeNotes(readJson(notesFile(sessionId), null));
+    },
+
+    /**
+     * 整份写回笔记表。调用方（`lib/notes.js` 的 `upsertNote`）已经改好了内容。
+     *
+     * @param sessionId - 会话 id。
+     * @param state - 完整笔记表。
+     */
+    writeNotes(sessionId, state) {
+      if (!sessionId) return;
+      writeJson(notesFile(sessionId), state);
+    },
+
     // ---- 「被按住」：暂停 / 停止。**要跨重启保留**，所以落盘 ----
 
     /**