@leonhardthust/dsh-decision-engine 1.9.1 → 1.10.0

package/lib/decision-store.js

@@ -1,5 +1,6 @@
 /**
- * 决策明细存储（`decisions.jsonl`）——「决策历史」标签页的数据源。
+ * 决策明细存储（`logs/` 下的分片；`single` 模式沿用 `decisions.jsonl`）
+ * ——「决策历史」标签页的数据源。
  *
  * ## 为什么不写进 telemetry.jsonl
  *
@@ -15,7 +16,34 @@
  * 所以另立一个文件。两个文件各管一件事：
  *
  *   - `telemetry.jsonl`  对外口径的决策**结论**（谁、哪家、什么裁决、多少 token）
- *   - `decisions.jsonl`  本地的决策**明细**（问了什么、答了什么、给谁做的）
+ *   - `logs/*.log`       本地的决策**明细**（问了什么、答了什么、给谁做的）
+ *
+ * ## 分文件与保留（T3）
+ *
+ * 明细体量长起来之后，单个 `decisions.jsonl` 有两个硬问题：
+ *
+ *   1. **读一次要跨全文件**——按会话查历史得从头扫，越用越慢；
+ *   2. **轮转把不同会话混在一起**——文件按体积切，一个会话的记录会被切开，
+ *      清理时也无法只删「很久以前的某个会话」。
+ *
+ * 因此明细改写到 `logs/` 子目录，按配置分片：
+ *
+ *   - `date`（默认）`YYYY-MM-DD.log`：最常用、也最符合「今天的日志」这个问法；
+ *   - `session` `<会话名>__<id 前 8>.log`：按会话隔离，删一个会话的日志不影响别人；
+ *   - `workspace` `<工作区名>.log`：按项目归档；
+ *   - `single` `decisions.jsonl`：老行为，给不想让文件变多的用户留的退路。
+ *
+ * 保留策略（`cleanupOnce()`，启动时一次 + 每 6 小时一次）先按**文件名里的
+ * 日期**（解析不出来才用 mtime）删掉超过保留天数的分片，再按 mtime 从旧到新
+ * 删到总量上限。**永远跳过今天的分片、当前活跃分片与队列里待写的分片**——
+ * 清理删掉正在写的文件，比不清理坏得多。所有 I/O 失败只 warn：清理是旁路。
+ *
+ * ## 紧凑格式
+ *
+ * 明细里最占体积的是重复字段：授权点的 `modelEvaluation` 在一条记录里存了
+ * 三份，守卫的问题集定义每条都带一份。`lib/decision-log.js` 的
+ * `compactRecord()` 去掉逐字节相同的副本、把常量问题集折叠成引用、省略
+ * 默认空值；**所有读取路径先 `expandRecord()`** 还原，界面看到的形状不变。
  *
  * ## 记录体为什么带 sessionId
  *
@@ -52,15 +80,41 @@
  */
 
 import { randomUUID } from "node:crypto";
-import { chmod, mkdir, open, rename, stat, unlink } from "node:fs/promises";
+import { appendFile, chmod, mkdir, open, readFile, readdir, rename, stat, unlink, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
-/** 明细文件名（与 `telemetry.jsonl` / `stats.jsonl` 同目录）。 */
+import {
+  DEFAULT_DATE_SEPARATOR,
+  DEFAULT_RETENTION_DAYS,
+  DEFAULT_SPLIT_MODE,
+  DEFAULT_TOTAL_MAX_BYTES,
+  SESSION_ID_SEGMENT_LENGTH,
+  compactRecord,
+  dateKeyOf,
+  expandRecord,
+  normalizeDateSeparator,
+  normalizeSplitMode,
+  parseShardDate,
+  rotatedNameOf,
+  sanitizeSegment,
+  shardFileName,
+} from "./decision-log.js";
+
+/**
+ * `single` 模式的文件名，也是旧版本唯一使用的文件名（迁移来源）。
+ * 分片模式下明细写在 `logs/` 里，不再是这个名字。
+ */
 export const DECISIONS_FILE_NAME = "decisions.jsonl";
 
 /** 轮转后的旧文件（覆盖式，只留一代）。 */
 export const DECISIONS_ROTATED_NAME = "decisions.jsonl.1";
 
+/** 所有分片所在的子目录名：与 config.yml / 标记文件分开，清理时不会误伤它们。 */
+export const DECISIONS_LOGS_DIR_NAME = "logs";
+
+/** 旧 `decisions.jsonl` 一次性迁移的标记文件名。 */
+export const MIGRATION_MARKER_NAME = "decisions-log-migrated";
+
 /** 记录体版本。加字段不升版本（读端按缺省值兜），改语义才升。 */
 export const DECISION_RECORD_VERSION = 1;
 
@@ -402,22 +456,27 @@ export function recordIdOf(entry) {
  *
  * 用法：
  *
- *   const store = new DecisionStore({ dir, getEnabled, getMaxBytes });
- *   store.record(buildDecisionRecord({ … }));       // 不 await，异步落盘
+ *   const store = new DecisionStore({ dir, getEnabled, getMaxBytes, getSplitMode });
+ *   store.record(buildDecisionRecord({ … }), { sessionName, workspaceName }); // 不 await
  *   const page = await store.readForSession(sessionId, { limit: 200 });
  */
 export class DecisionStore {
   /**
    * @param options.dir - 插件数据目录（`~/.dsh/dsh-decision-engine/`）。
-   * @param options.fileName - 文件名，默认 `decisions.jsonl`。
+   * @param options.fileName - `single` 模式的文件名，默认 `decisions.jsonl`。
    * @param options.logger - 宿主 logger；写盘失败时用它警告。
    * @param options.getEnabled - 返回「决策历史」开关。**关闭时不写任何东西**：
-   *   不建文件、不占磁盘、也不采集内容。用取值函数而不是定值，配置改了
-   *   立刻生效（与插件其余配置的处理方式一致）。**这是唯一的开关**：开启时
-   *   记录一定带内容，内容只在超过长度上限时才由 `truncateContent()` 退回
-   *   `capture: 'meta'`。
-   * @param options.getMaxBytes - 返回文件体积上限。
+   *   不建目录、不建文件、不占磁盘、也不采集内容。用取值函数而不是定值，
+   *   配置改了立刻生效（与插件其余配置的处理方式一致）。**这是唯一的开关**：
+   *   开启时记录一定带内容，内容只在超过长度上限时才由 `truncateContent()`
+   *   退回 `capture: 'meta'`。
+   * @param options.getMaxBytes - 返回**单个分片**的体积上限（到顶轮转）。
    * @param options.getMaxContentChars - 返回单条内容长度上限。
+   * @param options.getSplitMode - 返回分文件模式（single/date/session/workspace）。
+   * @param options.getDateSeparator - 返回日期分隔符（- / _ / .）。
+   * @param options.getRetentionDays - 返回保留天数；0 = 不按天删。
+   * @param options.getTotalMaxBytes - 返回 `logs/` 的总量上限（清理用）。
+   * @param options.getTimeZone - 返回 IANA 时区；留空用系统时区。
    * @param options.maxQueue - 待写队列上限；超过丢最旧的，防止磁盘挂起时吃内存。
    */
   constructor(options = {}) {
@@ -431,8 +490,23 @@ export class DecisionStore {
       typeof options.getMaxContentChars === "function"
         ? options.getMaxContentChars
         : () => DEFAULT_MAX_CONTENT_CHARS;
+    this.getSplitMode =
+      typeof options.getSplitMode === "function" ? options.getSplitMode : () => DEFAULT_SPLIT_MODE;
+    this.getDateSeparator =
+      typeof options.getDateSeparator === "function"
+        ? options.getDateSeparator
+        : () => DEFAULT_DATE_SEPARATOR;
+    this.getRetentionDays =
+      typeof options.getRetentionDays === "function"
+        ? options.getRetentionDays
+        : () => DEFAULT_RETENTION_DAYS;
+    this.getTotalMaxBytes =
+      typeof options.getTotalMaxBytes === "function"
+        ? options.getTotalMaxBytes
+        : () => DEFAULT_TOTAL_MAX_BYTES;
+    this.getTimeZone = typeof options.getTimeZone === "function" ? options.getTimeZone : () => undefined;
     this.maxQueue = Number.isFinite(options.maxQueue) ? Math.max(16, options.maxQueue) : 4096;
-    /** 待写队列（已脱敏的整行文本）。 */
+    /** 待写队列：元素是 `{ target, line }`，目标分片在入队时就定了。 */
     this.queue = [];
     /** 正在进行的写盘任务。 */
     this.pending = null;
@@ -454,20 +528,52 @@ export class DecisionStore {
     this.dropped = 0;
     /** 轮转次数（诊断用）。 */
     this.rotated = 0;
-    /** 自上次轮转以来已追加的字节数。 */
-    this.appendedBytes = 0;
+    /** 每个分片自上次校准 / 轮转以来已追加的字节数：`target → bytes`。 */
+    this.appendedBytesMap = new Map();
+    /** 已经用真实文件大小校准过 baseline 的分片（避免每条记录一次 stat）。 */
+    this.baselined = new Set();
+    /**
+     * 最近一次实际写入的分片名。
+     *
+     * `path` getter 与清理的「活跃分片」都认它：清理绝不能删掉正在写的文件。
+     */
+    this.activeTarget = "";
     /** 是否已经确认过文件权限（避免每条记录一次 chmod）。 */
     this.permissionSettled = false;
+    /** 最近一次清理的结果（`storageReport()` 的数据源）。 */
+    this.storageState = {
+      dir: this.logsDir,
+      splitMode: this.splitMode(),
+      files: 0,
+      bytes: 0,
+      removed: 0,
+      removedBytes: 0,
+      lastCleanup: "",
+      retentionDays: this.retentionDays(),
+      totalMaxBytes: this.totalMaxBytes(),
+      enabled: this.enabled(),
+      error: "",
+    };
+  }
+
+  /** 所有分片所在的目录。 */
+  get logsDir() {
+    return join(this.dir, DECISIONS_LOGS_DIR_NAME);
   }
 
-  /** 明细文件的绝对路径。 */
+  /**
+   * 当前主分片的绝对路径。
+   *
+   * 还没写过任何记录时按**此刻**算一个（日期模式 → 今天的分片），这样设置页
+   * 与排查脚本能直接拿到「接下来会写哪个文件」，而不是一个空串。
+   */
   get path() {
-    return join(this.dir, this.fileName);
+    return join(this.logsDir, this.activeTarget || this.mainShardName());
   }
 
-  /** 轮转后旧文件的绝对路径。 */
+  /** 当前主分片轮转后的绝对路径。 */
   get rotatePath() {
-    return join(this.dir, DECISIONS_ROTATED_NAME);
+    return join(this.logsDir, rotatedNameOf(this.activeTarget || this.mainShardName()));
   }
 
   /** 开关是否开启。 */
@@ -479,16 +585,101 @@ export class DecisionStore {
     }
   }
 
+  /** 当前分文件模式（现读配置）。 */
+  splitMode() {
+    try {
+      return normalizeSplitMode(this.getSplitMode());
+    } catch {
+      return DEFAULT_SPLIT_MODE;
+    }
+  }
+
+  /** 当前日期分隔符（现读配置）。 */
+  dateSeparator() {
+    try {
+      return normalizeDateSeparator(this.getDateSeparator());
+    } catch {
+      return DEFAULT_DATE_SEPARATOR;
+    }
+  }
+
+  /** 当前保留天数：夹在 0..3650；坏值退回默认 30。 */
+  retentionDays() {
+    try {
+      const value = Number(this.getRetentionDays());
+      if (!Number.isFinite(value)) return DEFAULT_RETENTION_DAYS;
+      return Math.min(3650, Math.max(0, Math.floor(value)));
+    } catch {
+      return DEFAULT_RETENTION_DAYS;
+    }
+  }
+
+  /** 当前总量上限（字节）。 */
+  totalMaxBytes() {
+    try {
+      const value = Number(this.getTotalMaxBytes());
+      return Number.isFinite(value) && value > 0 ? value : DEFAULT_TOTAL_MAX_BYTES;
+    } catch {
+      return DEFAULT_TOTAL_MAX_BYTES;
+    }
+  }
+
+  /** 当前时区；留空 = 系统时区（由 decision-log.js 里的 Intl 兜底）。 */
+  timeZone() {
+    try {
+      const value = this.getTimeZone();
+      return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** 按配置与此刻算出主分片名（没写过记录时的 `path`）。 */
+  mainShardName() {
+    return shardFileName({
+      splitMode: this.splitMode(),
+      fileName: this.fileName,
+      separator: this.dateSeparator(),
+      timeZone: this.timeZone(),
+      ts: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * 按**记录自己的 ts** 决定它该落到哪个分片。
+   *
+   * 用记录 ts 而不是「写盘时刻」：夜里的记录可能因为队列滞后到第二天才落盘，
+   * 按写盘时刻定位会让它出现在错误的日期文件里（对账时最难解释的一种错）。
+   *
+   * @param ts - 记录时间。
+   * @param meta - `{ sessionId, sessionName, workspaceName }`。
+   * @returns 分片文件名。
+   */
+  targetFor(ts, meta = {}) {
+    return shardFileName({
+      splitMode: this.splitMode(),
+      fileName: this.fileName,
+      separator: this.dateSeparator(),
+      timeZone: this.timeZone(),
+      ts,
+      sessionId: meta.sessionId,
+      sessionName: meta.sessionName,
+      workspaceName: meta.workspaceName,
+    });
+  }
+
   /**
    * 记一条决策明细。
    *
    * **不返回 Promise**：调用方不该 await 它。写盘在后台串行进行，决策路径
-   * 上的额外开销只有一次 `JSON.stringify` 与一次 `push`。
+   * 上的额外开销只有一次紧凑化 + `JSON.stringify` 与一次 `push`。
    *
    * @param record - `buildDecisionRecord()` 造出的记录。
+   * @param meta - `{ sessionName, workspaceName }`（session 模式的命名依据；
+   *   会话 id 始终取自记录本身，meta 里只放展示名）。
    * @returns 是否入队（开关关闭、内容为空、序列化失败都返回 false）。
    */
-  record(record) {
+  record(record, meta = {}) {
     if (!this.enabled()) return false;
     if (record === null || typeof record !== "object") return false;
     const seq = this.seq + 1;
@@ -516,18 +707,32 @@ export class DecisionStore {
     try {
       // 脱敏放在**序列化之后**：模式表针对的是 JSON 文本形态（`"apiKey": "…"`），
       // 对结构化对象做替换既难写又容易漏。
-      line = maskSecrets(JSON.stringify(finalRecord));
+      //
+      // 紧凑化放在序列化**之前**：它删的是结构化重复字段（见 decision-log.js），
+      // 读端 `expandRecord()` 会原样还原，网络与界面都看不到差别。
+      line = maskSecrets(JSON.stringify(compactRecord(finalRecord)));
     } catch {
       // 循环引用之类的问题不该把调用方带崩——明细是旁路。
       this.failed += 1;
       return false;
     }
     this.seq += 1;
+    let target;
+    try {
+      target = this.targetFor(finalRecord.ts, {
+        sessionId: finalRecord.sessionId,
+        sessionName: meta?.sessionName,
+        workspaceName: meta?.workspaceName,
+      });
+    } catch {
+      // 分片名算不出来（不该发生）时退回主分片：宁可写错文件，不要丢记录。
+      target = this.mainShardName();
+    }
     if (this.queue.length >= this.maxQueue) {
       this.queue.shift();
       this.dropped += 1;
     }
-    this.queue.push(`${line}\n`);
+    this.queue.push({ target, line: `${line}\n` });
     this.schedule();
     return true;
   }
@@ -549,56 +754,84 @@ export class DecisionStore {
     this.pending.catch(() => {});
   }
 
-  /** 把队列里的条目写进文件；到体积上限时先轮转。 */
+  /** 把队列里的条目按目标分片写进文件；到体积上限时先轮转。 */
   async drain() {
     await Promise.resolve();
     while (this.queue.length > 0) {
       const batch = this.queue.splice(0, this.queue.length);
-      const payload = batch.join("");
-      try {
-        await mkdir(dirname(this.path), { recursive: true });
-        await this.ensureSizeBaseline();
-        const limit = this.maxBytes();
-        /**
-         * 一批可能很大（调用方连续记了 200 条 → 一批 60 KB），**整批写会
-         * 直接冲过上限**：轮转判断发生在写之前，而写之前文件还是空的，
-         * 于是「追加字节数 + 这一批 > 上限」永远不成立，上限形同虚设。
-         *
-         * 因此把这一批按上限切成若干片，逐片写。片与片之间才可能触发
-         * 轮转，于是「文件有多大」真正受上限约束。
-         */
-        for (const chunk of splitByBytes(batch, limit)) {
-          // 写之前：文件已接近上限就先轮转，让新内容从一个空文件开始。
-          // `appendedBytes > 0` 是「文件还空着就不轮转」——对着一个不存在的
-          // 文件 rename 会失败，那只是噪音。
-          if (this.appendedBytes > 0 && this.appendedBytes + chunk.length > limit) {
-            await this.rotate();
-          }
-          const handle = await open(this.path, "a");
-          try {
-            await handle.write(chunk);
-          } finally {
-            await handle.close().catch(() => {});
-          }
-          this.appendedBytes += chunk.length;
-        }
-        this.written += batch.length;
-        if (!this.permissionSettled) {
-          this.permissionSettled = true;
-          // 明细里可能有会话正文与命令片段，权限与 config.yml 一致保持 600。
-          await chmod(this.path, 0o600).catch(() => {});
+      /**
+       * 按目标分组再写，而不是整批写一个文件：一批记录可能跨天（或跨会话），
+       * 整批写会让它们全落到「这批第一条」的那个分片里——日志里就会出现
+       * 「今天的文件里有昨天的记录」这种最难自查的错位。
+       */
+      const groups = new Map();
+      for (const item of batch) {
+        const lines = groups.get(item.target);
+        if (lines === undefined) groups.set(item.target, [item.line]);
+        else lines.push(item.line);
+      }
+      for (const [target, lines] of groups) {
+        try {
+          await this.appendTarget(target, lines);
+        } catch (error) {
+          // 写盘失败：丢这一组，记一次警告。**不重试**——重试会堆积，
+          // 而明细失败绝不该拖住决策。
+          this.failed += lines.length;
+          this.logger?.warn?.(
+            `dsh-decision-engine: 写入决策明细失败（${error instanceof Error ? error.message : String(error)}）`,
+          );
         }
-      } catch (error) {
-        // 写盘失败：丢这批，记一次警告。**不重试**——重试会堆积，
-        // 而明细失败绝不该拖住决策。
-        this.failed += batch.length;
-        this.logger?.warn?.(
-          `dsh-decision-engine: 写入决策明细失败（${error instanceof Error ? error.message : String(error)}）`,
-        );
       }
     }
   }
 
+  /**
+   * 把一个目标的若干行追加进文件；必要时按单文件上限轮转。
+   *
+   * 一批可能很大（调用方连续记了 200 条 → 一批 60 KB），**整批写会直接
+   * 冲过上限**：轮转判断发生在写之前，而写之前文件还是空的，于是
+   * 「追加字节数 + 这一批 > 上限」永远不成立，上限形同虚设。因此按上限
+   * 切成若干片逐片写，片与片之间才可能触发轮转。
+   *
+   * @param target - 分片文件名。
+   * @param lines - 已脱敏的整行文本（每行自带 `\n`）。
+   */
+  async appendTarget(target, lines) {
+    await mkdir(this.logsDir, { recursive: true });
+    await this.ensureSizeBaseline(target);
+    const limit = this.maxBytes();
+    for (const chunk of splitByBytes(lines, limit)) {
+      const bytes = Buffer.byteLength(chunk, "utf8");
+      // `appendedBytes > 0` 是「文件还空着就不轮转」——对着一个不存在的
+      // 文件 rename 会失败，那只是噪音。
+      if (this.appendedBytesOf(target) > 0 && this.appendedBytesOf(target) + bytes > limit) {
+        await this.rotateTarget(target);
+      }
+      const handle = await open(join(this.logsDir, target), "a");
+      try {
+        await handle.write(chunk);
+      } finally {
+        await handle.close().catch(() => {});
+      }
+      this.appendedBytesMap.set(target, this.appendedBytesOf(target) + bytes);
+      this.activeTarget = target;
+    }
+    this.written += lines.length;
+    if (!this.permissionSettled) {
+      this.permissionSettled = true;
+      // 明细里可能有会话正文与命令片段，权限与 config.yml 一致保持 600。
+      // 只对**本批最后写的那个文件**设一次：这是「首次落盘」的粗粒度保险，
+      // 而不是逐条 chmod 的精确权限管理。
+      await chmod(join(this.logsDir, this.activeTarget || target), 0o600).catch(() => {});
+    }
+  }
+
+  /** 某分片已追加的字节数（0 = 还没写过/刚轮转过）。 */
+  appendedBytesOf(target) {
+    const value = this.appendedBytesMap.get(target);
+    return Number.isFinite(value) ? value : 0;
+  }
+
   /** 体积上限（现读配置）。 */
   maxBytes() {
     try {
@@ -610,31 +843,36 @@ export class DecisionStore {
   }
 
   /**
-   * 首次写盘前用真实文件大小初始化「已追加字节」。
+   * 首次写某个分片前用真实文件大小初始化「已追加字节」。
    *
-   * 为什么需要：进程刚启动时 `appendedBytes` 是 0，而磁盘上的文件可能已经
-   * 有几十 MB（升级前累积的）。不校准的话要再写满一整个上限才轮转。
+   * 为什么需要：进程刚启动时计数是 0，而磁盘上的分片可能已经有几十 MB
+   * （升级前 / 上次运行累积的）。不校准的话要再写满一整个上限才轮转。
    */
-  async ensureSizeBaseline() {
-    if (this.permissionSettled) return;
+  async ensureSizeBaseline(target) {
+    if (this.baselined.has(target)) return;
+    this.baselined.add(target);
     try {
-      const info = await stat(this.path);
-      this.appendedBytes = info.size;
+      const info = await stat(join(this.logsDir, target));
+      this.appendedBytesMap.set(target, info.size);
     } catch {
-      this.appendedBytes = 0;
+      this.appendedBytesMap.set(target, 0);
     }
   }
 
   /**
-   * 把当前文件挪成 `.1`，覆盖上一代。
+   * 把某个分片挪成 `.1`，覆盖上一代。
    *
    * 只留一代而不是多代：这个页面的用途是「看会话里刚才发生了什么」，
    * 不是归档。多代备份会让磁盘占用变成上限的整数倍，而收益近似为零。
+   * 轮转名跟着模式走：`2026-11-15.log` → `2026-11-15.1.log`，
+   * `decisions.jsonl` → `decisions.jsonl.1`。
    */
-  async rotate() {
+  async rotateTarget(target) {
+    const path = join(this.logsDir, target);
+    const rotated = join(this.logsDir, rotatedNameOf(target));
     try {
-      await unlink(this.rotatePath).catch(() => {});
-      await rename(this.path, this.rotatePath);
+      await unlink(rotated).catch(() => {});
+      await rename(path, rotated);
       this.rotated += 1;
     } catch (error) {
       this.logger?.warn?.(
@@ -642,21 +880,180 @@ export class DecisionStore {
       );
     } finally {
       // 无论成功与否都把计数清零：失败时继续往老文件写也不会无限跑偏。
-      this.appendedBytes = 0;
+      this.appendedBytesMap.set(target, 0);
+    }
+  }
+
+  /** 路径是否存在（只判断存在性，不区分文件/目录）。 */
+  async pathExists(path) {
+    try {
+      await stat(path);
+      return true;
+    } catch {
+      return false;
     }
   }
 
+  /**
+   * 列出 `logs/` 下的所有分片（只认 `.log`）。
+   *
+   * 为什么只认 `.log`：这个目录里还可能有迁移标记、`.migrated` 备份与
+   * 临时文件；清理与读取都不该碰它们。`decisions.jsonl` 是「迁移前」的
+   * 旧文件，由读取路径单独兜底，不参与日志目录的枚举。
+   *
+   * @returns `{ name, path, size, mtimeMs, date }[]`；目录不存在时返回空数组。
+   */
+  async shardFiles() {
+    let names;
+    try {
+      names = await readdir(this.logsDir);
+    } catch {
+      return [];
+    }
+    const files = [];
+    for (const name of names) {
+      if (!name.endsWith(".log")) continue;
+      const path = join(this.logsDir, name);
+      let info;
+      try {
+        info = await stat(path);
+      } catch {
+        continue;
+      }
+      if (!info.isFile()) continue;
+      files.push({
+        name,
+        path,
+        size: info.size,
+        mtimeMs: Number.isFinite(info.mtimeMs) ? info.mtimeMs : 0,
+        date: parseShardDate(name),
+      });
+    }
+    return files;
+  }
+
+  /**
+   * 按模式收集「该读哪些分片」，并读出它们的尾部行。
+   *
+   * 读取顺序与配额：
+   *
+   *   - `date`：按文件名日期**从新到旧**，同一天先读主文件再读 `.1`（`.1`
+   *     是轮转出去的、更旧），边读边扣 `scanLines` 配额；
+   *   - `session`：按 mtime 从新到旧匹配 `__<id8>` 后缀；
+   *   - `workspace`：读该目录全部分片（按 mtime 从新到旧）；
+   *   - `single`：主文件 + `.1`。
+   *
+   * **不丢历史的兜底链**（模式特定分片一个都没有时逐级退让）：
+   *
+   *   1. 本模式下没有匹配 → 读 `logs/` 里单一文件模式的 `decisions.jsonl`；
+   *   2. 还没有 → 读**旧格式**根目录的 `decisions.jsonl` / `.1`（用户可能
+   *      刚升级、迁移还没跑或失败）；
+   *   3. 仍没有 → 读 `logs/` 全部分片（用户切换过模式：例如从 session 切到
+   *      date，旧记录在别的命名里；最终仍按 sessionId 严格过滤，不会串会话）。
+   *
+   * @param sessionId - 目标会话 id。
+   * @param scanLines - 最多倒着扫多少行。
+   * @returns `{ files, lines, scanned, hitCap }`：`lines` 已按时间从旧到新。
+   */
+  async collectLines(sessionId, scanLines) {
+    const mode = this.splitMode();
+    const todayKey = dateKeyOf(new Date().toISOString(), this.timeZone());
+    const all = await this.shardFiles();
+    /** @type {{ name: string, path: string }[]} */
+    let files = [];
+    if (mode === "single") {
+      files = await this.existingFiles([
+        join(this.logsDir, rotatedNameOf(this.fileName)),
+        join(this.logsDir, this.fileName),
+      ]);
+    } else if (mode === "date") {
+      // 只认「今天及更早」的日期分片：未来日期的文件（改过系统时钟、手工拷贝）
+      // 若混进来，会排在最前面并吃掉全部扫描配额，让真正的今天记录读不到。
+      files = all
+        .filter((file) => file.date !== null && file.date.key <= todayKey)
+        .sort((left, right) => {
+          if (left.date.key !== right.date.key) return left.date.key < right.date.key ? 1 : -1;
+          // 同一天：主文件比 `.1` 新（轮转把旧内容挪到了 `.1`）。
+          return left.date.rotation - right.date.rotation;
+        })
+        .map((file) => ({ name: file.name, path: file.path }));
+    } else if (mode === "session") {
+      const suffix = sessionIdSuffix(sessionId);
+      const pattern = new RegExp(`__${escapeRegExp(suffix)}(?:\\.\\d+)?\\.log$`);
+      files = all
+        .filter((file) => pattern.test(file.name))
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .map((file) => ({ name: file.name, path: file.path }));
+    } else {
+      files = all
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .map((file) => ({ name: file.name, path: file.path }));
+    }
+    if (files.length === 0 && mode !== "single") {
+      files = await this.existingFiles([
+        join(this.logsDir, rotatedNameOf(this.fileName)),
+        join(this.logsDir, this.fileName),
+      ]);
+    }
+    if (files.length === 0) {
+      // 旧格式：不迁移也能看历史（迁移把旧文件改名成 `.migrated` 之后
+      // 这里自然读不到，不会重复计数）。
+      files = await this.existingFiles([
+        join(this.dir, DECISIONS_ROTATED_NAME),
+        join(this.dir, this.fileName),
+      ]);
+    }
+    if (files.length === 0) {
+      // 切换过模式：旧记录可能在别的命名的分片里。仍按 sessionId 严格过滤，
+      // 因此读到别的会话的记录是不可能的，最多多扫几行。
+      files = all
+        .sort((left, right) => right.mtimeMs - left.mtimeMs)
+        .map((file) => ({ name: file.name, path: file.path }));
+    }
+    const lines = [];
+    /** 真正读过的分片（配额用完后就不再读更旧的那些）。 */
+    const readFiles = [];
+    let scanned = 0;
+    let hitCap = false;
+    for (const file of files) {
+      const remaining = scanLines - scanned;
+      if (remaining <= 0) {
+        hitCap = true;
+        break;
+      }
+      const part = await readTailLines(file.path, remaining);
+      readFiles.push(file.path);
+      scanned += part.length;
+      if (part.length >= remaining) hitCap = true;
+      // 后读的文件更新：放到已读内容后面，最终仍是时间升序。
+      lines.unshift(...part);
+    }
+    return { files: readFiles, lines, scanned, hitCap };
+  }
+
+  /** 过滤出真实存在的文件（顺序与入参一致）。 */
+  async existingFiles(paths) {
+    const files = [];
+    for (const path of paths) {
+      if (await this.pathExists(path)) {
+        files.push({ name: path.split(/[\\/]/).pop() ?? path, path });
+      }
+    }
+    return files;
+  }
+
   /**
    * 读某个会话的决策明细（时间升序）。
    *
-   * 先读当前文件尾部；不够再读轮转过的 `.1`（更早的那些）。**永远整读**：
-   * 扫描行数有上限 `DEFAULT_SCAN_LINES`，返回条数有上限 `MAX_ENTRIES_PER_QUERY`。
+   * 跨分片读：按当前模式收集最近的分片，倒着扫到 `scanLines` 配额为止。
+   * 返回条数有上限 `MAX_ENTRIES_PER_QUERY`。
    *
    * @param sessionId - 会话 id；空串直接返回空页（不可归属的记录不属于任何人）。
    * @param options.limit - 返回多少条（默认 200，上限 500）。
    * @param options.scanLines - 最多倒着扫多少行（默认 4000）。
-   * @returns `{ entries, total, scanned, truncated, file }`。
-   *   `total` 是扫描窗口内**该会话**的记录数，可能大于 `entries.length`。
+   * @returns `{ entries, total, scanned, truncated, file, files, enabled }`。
+   *   `total` 是扫描窗口内**该会话**的记录数，可能大于 `entries.length`；
+   *   `files` 是本次实际读取的分片（从新到旧），供界面显示「记录在哪」。
    */
   async readForSession(sessionId, options = {}) {
     const id = typeof sessionId === "string" ? sessionId.trim() : "";
@@ -673,17 +1070,13 @@ export class DecisionStore {
       scanned: 0,
       truncated: false,
       file: this.path,
+      files: [],
       enabled: this.enabled(),
     };
     if (id.length === 0) return empty;
 
-    const current = await readTailLines(this.path, scanLines);
-    let lines = current;
-    let scannedHitCap = current.length >= scanLines;
-    if (current.length < scanLines) {
-      const older = await readTailLines(this.rotatePath, scanLines - current.length);
-      lines = [...older, ...current];
-    }
+    const collected = await this.collectLines(id, scanLines);
+    const lines = collected.lines;
 
     /**
      * 预筛：先用子串判断这行**有没有可能**属于目标会话，命中了才 `JSON.parse`。
@@ -692,10 +1085,9 @@ export class DecisionStore {
      * 完整 JSON.parse 再丢掉，白花 90% 以上的解析开销。
      *
      * 为什么这是安全的（不是启发式）：`JSON.stringify` 只会把会话 id 里的
-     * 引号、反斜杠与控制字符转义，其余字符原样保留。因此只要 id 本身不含
-     * 这些需要转义的字符，磁盘上那一行的 `"sessionId":"<id>"` 片段必然
-     * **逐字**包含 id；反过来，包含 id 子串的行仍要经过下面的严格比较，
-     * 预筛只可能漏掉不可能匹配的行，不会放过不匹配的行。
+     * 引号、反斜杠与控制字符转义，其余字符原样保留；紧凑格式**不省略**
+     * `sessionId`，所以磁盘上那一行的 `"sessionId":"<id>"` 片段必然逐字包含
+     * id。反过来，包含 id 子串的行仍要经过下面的严格比较。
      *
      * id 含转义字符时（极罕见）直接退化成「全部解析」，与旧行为一致。
      */
@@ -712,8 +1104,10 @@ export class DecisionStore {
         continue;
       }
       if (entry === null || typeof entry !== "object") continue;
-      if (typeof entry.sessionId !== "string" || entry.sessionId !== id) continue;
-      matched.push(entry);
+      // 所有读取路径都必须先展开：紧凑格式不是「另一种记录」，只是磁盘形态。
+      const expanded = expandRecord(entry);
+      if (typeof expanded.sessionId !== "string" || expanded.sessionId !== id) continue;
+      matched.push(expanded);
     }
     // 按**时间**排序，不按 `seq`。
     //
@@ -751,13 +1145,265 @@ export class DecisionStore {
     return {
       entries,
       total: matched.length,
-      scanned: lines.length,
-      truncated: matched.length > limit || scannedHitCap,
-      file: this.path,
+      scanned: collected.scanned,
+      truncated: matched.length > limit || collected.hitCap,
+      file: collected.files[0] ?? this.path,
+      files: collected.files,
+      enabled: this.enabled(),
+    };
+  }
+
+  /**
+   * 清理过期分片（启动时一次 + 每 6 小时一次）。
+   *
+   * 两轮，顺序不能反：
+   *
+   *   1. **按保留天数**：日期从文件名解析（分片名里的日期就是记录日期，
+   *      比 mtime 可信——拷贝/恢复会把 mtime 改掉）；解析不出日期才退回
+   *      mtime。早于「今天 − 保留天数」的删掉；`0` = 这一轮不删。
+   *   2. **按总量上限**：仍超上限就按 mtime 从旧到新删，直到不超。
+   *
+   * 两道保险：**绝不删今天的分片**（用户正在看的很可能就是它）与
+   * **绝不删活跃分片**（当前主分片 / 本进程写过 / 队列里待写）。清理删掉
+   * 正在写的文件比不清理坏得多——轻则丢记录，重则在 Windows 上写失败。
+   *
+   * 任何 I/O 异常只 warn：清理是旁路，失败不该影响插件启动。开关关闭时
+   * 直接返回（不建目录、不动磁盘）。
+   *
+   * @returns 本次清理的报告（同时存进 `storageReport()`）。
+   */
+  async cleanupOnce() {
+    const report = {
+      dir: this.logsDir,
+      splitMode: this.splitMode(),
+      files: 0,
+      bytes: 0,
+      removed: 0,
+      removedBytes: 0,
+      lastCleanup: new Date().toISOString(),
+      retentionDays: this.retentionDays(),
+      totalMaxBytes: this.totalMaxBytes(),
+      enabled: this.enabled(),
+      error: "",
+    };
+    if (!report.enabled) {
+      this.storageState = report;
+      return report;
+    }
+    try {
+      const entries = await this.shardFiles();
+      const todayKey = dateKeyOf(new Date().toISOString(), this.timeZone());
+      const active = this.activeTargetNames();
+      const retention = report.retentionDays;
+      const cutoffKey =
+        retention > 0
+          ? dateKeyOf(Date.now() - retention * 24 * 60 * 60 * 1000, this.timeZone())
+          : "";
+      const kept = [];
+      for (const entry of entries) {
+        const key = entry.date === null ? dateKeyOf(entry.mtimeMs, this.timeZone()) : entry.date.key;
+        const isToday = key === todayKey;
+        const isActive = active.has(entry.name);
+        if (retention > 0 && key.length > 0 && cutoffKey.length > 0 && key < cutoffKey && !isToday && !isActive) {
+          try {
+            await unlink(entry.path);
+            report.removed += 1;
+            report.removedBytes += entry.size;
+            continue;
+          } catch (error) {
+            // 删不掉（权限 / 被别的进程占用）不影响其它文件。
+            this.logger?.warn?.(
+              `dsh-decision-engine: 清理过期决策日志失败（${entry.name}：${error instanceof Error ? error.message : String(error)}）`,
+            );
+          }
+        }
+        kept.push({ ...entry, key });
+      }
+      let total = kept.reduce((sum, item) => sum + item.size, 0);
+      const maxTotal = report.totalMaxBytes;
+      if (total > maxTotal) {
+        const candidates = kept
+          .filter((item) => item.key !== todayKey && !active.has(item.name))
+          .sort((left, right) => left.mtimeMs - right.mtimeMs);
+        for (const item of candidates) {
+          if (total <= maxTotal) break;
+          try {
+            await unlink(item.path);
+            total -= item.size;
+            report.removed += 1;
+            report.removedBytes += item.size;
+            const index = kept.findIndex((keptItem) => keptItem.name === item.name);
+            if (index >= 0) kept.splice(index, 1);
+          } catch (error) {
+            this.logger?.warn?.(
+              `dsh-decision-engine: 按总量清理决策日志失败（${item.name}：${error instanceof Error ? error.message : String(error)}）`,
+            );
+          }
+        }
+      }
+      report.files = kept.length;
+      report.bytes = total;
+    } catch (error) {
+      report.error = error instanceof Error ? error.message : String(error);
+      this.logger?.warn?.(`dsh-decision-engine: 清理决策日志失败（${report.error}）`);
+    }
+    this.storageState = report;
+    return report;
+  }
+
+  /** 活跃分片名集合：当前主分片 + 本进程写过的 + 队列里待写的。 */
+  activeTargetNames() {
+    const active = new Set();
+    const current = this.activeTarget || this.mainShardName();
+    if (typeof current === "string" && current.length > 0) active.add(current);
+    for (const target of this.appendedBytesMap.keys()) active.add(target);
+    for (const item of this.queue) if (typeof item.target === "string") active.add(item.target);
+    return active;
+  }
+
+  /** 最近一次清理的报告（同步，供 `/status` 回显；未清理过时是零值）。 */
+  storageReport() {
+    return {
+      ...this.storageState,
+      dir: this.logsDir,
+      splitMode: this.splitMode(),
+      retentionDays: this.retentionDays(),
+      totalMaxBytes: this.totalMaxBytes(),
       enabled: this.enabled(),
     };
   }
 
+  /**
+   * 把旧的 `decisions.jsonl` / `.1` **一次性**迁移到 `logs/` 的日期分片。
+   *
+   * 触发条件很窄：`logs/` 里**还没有任何分片**且旧文件存在。满足这两条说明
+   * 用户是从旧版本升上来的第一次启动——迁移后旧文件改名成 `.migrated`
+   * （**保留不删**，用户仍能直接打开核对），并写标记文件记住「做过」。
+   *
+   * 为什么条件是「没有分片」而不是「目录不存在」：上一次迁移可能在 `mkdir`
+   * 之后、写分片之前失败（磁盘满、权限），留下一个**空目录**。按「目录不存在」
+   * 判断的话，那次失败就永久关死了迁移——旧文件还在，却再也不会被搬。空目录
+   * 说明新布局并没有真的开始过，继续迁移才是对的。
+   *
+   * 幂等性靠三条，任何一条成立都不再产生副作用：
+   *
+   *   1. 标记文件存在 → 直接返回 0；
+   *   2. `logs/` 里已有分片（说明新布局已经启用过）→ 写标记、返回 0；
+   *   3. 旧文件不存在 → 写标记、返回 0（下次启动不再重扫）。
+   *
+   * 失败时**不写标记**且旧文件不动：下次启动会重试，读取路径也仍能读到旧
+   * 文件（`collectLines()` 的兜底）。代价是失败前已写入的分片可能重复——
+   * 但迁移失败是极端情况，而「丢历史」比「可能重复」严重得多。
+   *
+   * @returns 迁移的记录条数；0 表示没有可迁移的（已迁移过 / 失败 / 文件不存在）。
+   */
+  async migrateLegacyOnce() {
+    const markerPath = join(this.dir, MIGRATION_MARKER_NAME);
+    if (await this.pathExists(markerPath)) return 0;
+    // 开关关闭时不迁移，也不写标记：用户重新打开后仍会触发一次迁移。
+    if (!this.enabled()) return 0;
+    if (await this.pathExists(this.logsDir)) {
+      const existing = await this.shardFiles();
+      if (existing.length > 0) {
+        await this.writeMarker(markerPath);
+        return 0;
+      }
+    }
+    const legacyPath = join(this.dir, DECISIONS_FILE_NAME);
+    const rotatedPath = join(this.dir, DECISIONS_ROTATED_NAME);
+    const hasLegacy = await this.pathExists(legacyPath);
+    const hasRotated = await this.pathExists(rotatedPath);
+    if (!hasLegacy && !hasRotated) {
+      await this.writeMarker(markerPath);
+      return 0;
+    }
+    /** 旧数据：`.1` 是更早的一代，先读它，保证分片内顺序仍是时间顺序。 */
+    const records = [];
+    for (const path of [hasRotated ? rotatedPath : "", hasLegacy ? legacyPath : ""]) {
+      if (path.length === 0) continue;
+      let raw;
+      try {
+        raw = await readFile(path, "utf8");
+      } catch (error) {
+        this.logger?.warn?.(
+          `dsh-decision-engine: 读取旧决策明细失败（${path}：${error instanceof Error ? error.message : String(error)}）`,
+        );
+        continue;
+      }
+      for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0) continue;
+        try {
+          const parsed = JSON.parse(trimmed);
+          if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) records.push(parsed);
+        } catch {
+          // 坏行跳过：迁移不能因为一行半行就整体失败。
+        }
+      }
+    }
+    if (records.length > 0) {
+      const groups = new Map();
+      for (const record of records) {
+        const compacted = compactRecord(record);
+        let target;
+        try {
+          target = shardFileName({
+            splitMode: "date",
+            separator: this.dateSeparator(),
+            timeZone: this.timeZone(),
+            ts: compacted.ts,
+          });
+        } catch {
+          target = this.mainShardName();
+        }
+        const lines = groups.get(target);
+        if (lines === undefined) groups.set(target, [`${JSON.stringify(compacted)}\n`]);
+        else lines.push(`${JSON.stringify(compacted)}\n`);
+      }
+      try {
+        await mkdir(this.logsDir, { recursive: true });
+        for (const [target, lines] of groups) {
+          await appendFile(join(this.logsDir, target), lines.join(""), "utf8");
+        }
+      } catch (error) {
+        // 不写标记、不改名：下次启动重试，旧文件仍可读。
+        this.logger?.warn?.(
+          `dsh-decision-engine: 迁移旧决策明细失败（${error instanceof Error ? error.message : String(error)}）`,
+        );
+        return 0;
+      }
+    }
+    // 改名保留而不是删除：用户仍可打开 `.migrated` 核对迁移前的原始内容。
+    await this.renameLegacyFile(legacyPath);
+    await this.renameLegacyFile(rotatedPath);
+    await this.writeMarker(markerPath);
+    return records.length;
+  }
+
+  /** 把旧明细改名成 `.migrated`（目标已存在时先删旧的）；失败只 warn。 */
+  async renameLegacyFile(path) {
+    if (!(await this.pathExists(path))) return;
+    const target = `${path}.migrated`;
+    try {
+      await unlink(target).catch(() => {});
+      await rename(path, target);
+    } catch (error) {
+      this.logger?.warn?.(
+        `dsh-decision-engine: 旧决策明细改名失败（${path}：${error instanceof Error ? error.message : String(error)}）`,
+      );
+    }
+  }
+
+  /** 写一次性迁移标记；写失败不算失败（下次会重扫，幂等）。 */
+  async writeMarker(markerPath) {
+    try {
+      await mkdir(this.dir, { recursive: true });
+      await writeFile(markerPath, new Date().toISOString(), "utf8");
+    } catch {
+      /* 标记写不了就下次再来 */
+    }
+  }
+
   /**
    * 等待队列里的内容全部落盘。
    *
@@ -772,3 +1418,16 @@ export class DecisionStore {
     return this.written;
   }
 }
+
+/** 会话 id 在文件名里的那一段（与 `shardFileName()` 完全同一套规则）。 */
+function sessionIdSuffix(sessionId) {
+  const id = typeof sessionId === "string" ? sessionId.trim() : "";
+  return sanitizeSegment(id.length > 0 ? id.slice(0, SESSION_ID_SEGMENT_LENGTH) : "unknown", {
+    maxLength: SESSION_ID_SEGMENT_LENGTH,
+  });
+}
+
+/** 正则转义（会话 id 段拼进正则前必须转义：`~` 之外的字符都可能出现）。 */
+function escapeRegExp(text) {
+  return String(text).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}