mingdao-harness 0.6.41 → 0.6.43

package/docs/ARCHITECTURE.md

@@ -96,7 +96,7 @@ MingDao 是一个「模型循环 + 工具 + 权限」内核，纯 Node.js ≥ 18
 ### 2.4 会话 / 记忆 / 任务（11）
 
 - `session.js` —— 会话持久化：`<home>/sessions/<时间戳>-<随机>.jsonl` 每轮追加，`--continue` 载入最近一次，`--resume` 打开选择器 —— 会话文件是消息结构的唯一权威，检查点等旁挂状态另存侧车文件。
-- `session-events.js` —— 会话事件日志（v0.7.0 §1.1 切片 A）：`<session>.events.ndjson` 追加 12 类事件 `{seq,time,type,data}`（session/turn/step/tool/message/usage/compact/interrupt/checkpoint）—— **seq 是唯一关联键**：跨进程短临界区锁内「读尾行 last+1」、单次 append 后回读校验；读侧跳过 torn 行/未知 type 并返回 `skipped`；`replayToMessages()` 是纯函数（`message.append` 提供消息本体、`compact` 重置基线、`interrupt` 延迟补 tool 占位），由事件流重放的消息数组必须与原消息数组逐字节等价；事件文件是**旁路**：`loadSession`/`rewriteSession` 不读它，`cfg.eventLog=false` 或 `MINGDAO_EVENT_LOG=0` 可整体回滚；切片 B1 起新增两个纯函数供传输层使用——`readAfter(eventFile, afterSeq)` 只读游标读取（`seq > after`，返回 `{ok,events,lastSeq,skipped}`，文件不存在按空窗口）与 `continuityOf(seqs)` 连续性自检（`{ok,gaps:[{after,before}]}`，seq 必须从 1 起逐条 +1）——仅 `GET /api/events?file=&after=` 与 `GET /api/session` 的 `lastEventSeq` 读事件文件，SSE 帧/UI 仍不读。
+- `session-events.js` —— 会话事件日志（v0.7.0 §1.1 切片 A / B2-a）：`<session>.events.ndjson` 追加 13 类事件 `{seq,time,type,data}`（session/turn/step/tool/message/usage/compact/messages.replace/interrupt/checkpoint）—— **seq 是唯一关联键**：跨进程短临界区锁内「读尾行 last+1」、单次 append 后回读校验（单条事件超过尾窗时回退整文件校验最后一行）；读侧跳过 torn 行/未知 type 并返回 `skipped`（可忽略性：旧读者遇到新类型只当它不存在）；`replayToMessages()` 是纯函数（`message.append` 提供消息本体、`compact`/`messages.replace` 重置基线、`interrupt` 延迟补 tool 占位），由事件流重放的消息数组必须与原消息数组逐字节等价；事件文件是**旁路**：`loadSession` 不读它，`rewriteSession` 只在会话写盘成功后追加 `messages.replace`（写失败只 warn，不改变重写结果），`cfg.eventLog=false` 或 `MINGDAO_EVENT_LOG=0` 可整体回滚；切片 B1 起新增两个纯函数供传输层使用——`readAfter(eventFile, afterSeq)` 只读游标读取（`seq > after`，返回 `{ok,events,lastSeq,skipped}`，文件不存在按空窗口）与 `continuityOf(seqs)` 连续性自检（`{ok,gaps:[{after,before}]}`，seq 必须从 1 起逐条 +1）——仅 `GET /api/events?file=&after=` 与 `GET /api/session` 的 `lastEventSeq` 读事件文件，SSE 帧/UI 仍不读。
 - `session-index.js` —— 会话检索索引：词表倒排 + 按 mtime/size 的增量同步，分片存 `<home>/sessions-index/<2位sha1前缀>.json`（256 片）—— 未变化直接用缓存词表，>8MB 文件跳过并移除条目；中文按 bigram + 单字、查询串同口径分词后 AND 匹配。
 - `memory.js` —— 长记忆与自主进化：用户记忆 `~/.mingdao/AGENTS.md`（手动 + 会话结束自动提取用户偏好并去重追加）、会话日志 `journal.jsonl`（默认不注入系统提示，`--journal` / WebUI 勾选才取最近 3 条）—— 自动提取用 executor 模型（约几十 token），`autoMemory: false` 可关。
 - `tasks.js` —— 多会话后台任务面板：`mingdao run` 拉起独立 worker 子进程，状态落 `<home>/tasks/<id>.json`，命令族 `run` / `tasks` / `tasks watch` / `tasks kill` —— taskId 用不可枚举随机值；kill 前必须过 PID 归属校验（见 `proc.js`）。

package/docs/CONFIG.md

@@ -90,21 +90,28 @@ MingDao 先用 executor 模型（路由关闭时为当前模型）把被裁段
 
 每个会话在消息文件旁多一条 append-only 的事件流 `<session>.events.ndjson`（0600，与
 `<session>.jsonl` 同级）：每条 `{seq,time,type,data}`，seq 单调、是 turn/step/tool/message
-之间的唯一关联键。当前 12 类事件：`session.start` / `turn.start` / `turn.end` / `step.start` /
-`step.end` / `tool.start` / `tool.end` / `message.append` / `usage` / `compact` / `interrupt` /
-`checkpoint`。
-
-- **双写、旁路**：`appendMessages()` 在会话消息落盘**之后**追加 `message.append`；agent 在
+之间的唯一关联键。当前 13 类事件：`session.start` / `turn.start` / `turn.end` / `step.start` /
+`step.end` / `tool.start` / `tool.end` / `message.append` / `usage` / `compact` /
+`messages.replace` / `interrupt` / `checkpoint`。
+
+- **双写、旁路**：`appendMessages()` 在会话消息落盘**之后**追加 `message.append`；
+  `rewriteSession()`（压缩 / `--resume` / `/clear` / CLI 全量重写）在会话文件**写盘成功之后**
+  追加 `messages.replace`（`data={messages,reason}`，reason 为 `compact` / `resume` / `rewrite`）——
+  语义是「把当前派生窗口整体替换为 data.messages」，append-only、不删旧行。agent 在
   turn/step/工具/用量/压缩/中断边界追加结构事件。事件日志写失败只 warn，**不影响会话写入**，
   也不改变 `loadSession()` / `rewriteSession()` 的返回值。
-- **确定性重放**：`replayToMessages(events)` 由事件流派生消息数组（`compact` 重置基线、
-  `interrupt` 补 tool 占位），已对拍单轮 / 工具调用 / 压缩 / 中断四个场景与消息数组 deepEqual。
+- **确定性重放**：`replayToMessages(events)` 由事件流派生消息数组（`compact` 与
+  `messages.replace` 重置基线、`interrupt` 补 tool 占位），已对拍单轮 / 工具调用 / 压缩 /
+  resume / 空会话 / `tool_calls` 等场景与消息数组 deepEqual。
 - **回滚开关**：`"eventLog": false`（默认开）或环境变量 `MINGDAO_EVENT_LOG=0`。关闭后**完全**
-  停止事件写入（含 `message.append` 双写），会话文件照常写入。
-- **兼容**：旧会话没有 events 文件时读取返回空流；事件侧车不会出现在会话列表/最近会话中；
-  事件文件不参与云同步。SSE 帧与 UI 在本切片**未改**。
-- **已知边界**：手动 `/compact` 走 `rewriteSession` 时没有对应 `compact` 事件；自动标题重命名
-  会话文件不会搬迁事件侧车；这两类留待后续切片（事件日志目前是旁路，不参与既有读取）。
+  停止事件写入（含 `message.append` 与 `messages.replace` 双写），会话文件照常写入。
+- **兼容**：新增类型只追加、不改变既有事件形状；读侧对未知 type 一律跳过并计入 `skipped`，
+  因此旧版本读到 `messages.replace` 只会当它不存在，旧日志（没有该类型）在新版本照常可读。
+  旧会话没有 events 文件时读取返回空流；事件侧车不会出现在会话列表/最近会话中；事件文件不
+  参与云同步。SSE 帧与 UI 不受影响。
+- **已知边界**：自动标题重命名会话文件不会搬迁事件侧车；WebUI 的 `onCompact` 目前按默认
+  `rewrite` 记 reason（本轮不改 `src/web/**`）；本版之前写下的日志没有 `messages.replace`，
+  `scripts/event-parity.mjs` 将这类「不可回溯」会话判为 `incomplete`（不计失败）。
 
 ## 会话级工作空间（P3-4）
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mingdao-harness",
-  "version": "0.6.41",
+  "version": "0.6.43",
   "description": "MingDao Harness —— 开源智能体框架（Agent Harness）。零依赖、开箱即用，针对 DeepSeek-V4 系列优化，开放主流模型接入。",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -508,7 +508,7 @@ async function main() {
     sessionRef,
     // 自动压缩后重写会话文件 + 同步落盘游标（经 tuiState 共享槽与 REPL 会话联动）
     onCompact: (/** @type {any} */ msgs) => {
-      if (tuiState.session) rewriteSession(tuiState.session.file, msgs);
+      if (tuiState.session) rewriteSession(tuiState.session.file, msgs, 'compact');
       tuiState.persisted = msgs.length;
     },
   });
@@ -547,7 +547,7 @@ async function main() {
       mcp: mcpFacade,
       sessionRef: oneShotRef,
       onCompact: (/** @type {any} */ msgs) => {
-        rewriteSession(session.file, msgs);
+        rewriteSession(session.file, msgs, 'compact');
         oneShotPersisted = msgs.length;
       },
     });

package/src/commands/repl.js

@@ -238,7 +238,7 @@ export async function runRepl(ctx) {
         mcp: mcpFacade,
         sessionRef,
         onCompact: (/** @type {any} */ msgs) => {
-          rewriteSession(session.file, msgs);
+          rewriteSession(session.file, msgs, 'compact');
           tuiState.persisted = msgs.length;
         },
       });
@@ -327,7 +327,7 @@ export async function runRepl(ctx) {
           provider, permission: permissionNow, io, modelName, workingDir, cfg: agentCfg,
           undoStore: sessionUndoStore, mcp: mcpFacade, sessionRef,
           onCompact: (/** @type {any} */ msgs) => {
-            rewriteSession(session.file, msgs);
+            rewriteSession(session.file, msgs, 'compact');
             tuiState.persisted = msgs.length;
           },
         });
@@ -363,7 +363,7 @@ export async function runRepl(ctx) {
           provider, permission: permissionNow, io, modelName, workingDir, cfg: agentCfg,
           undoStore: sessionUndoStore, mcp: mcpFacade, sessionRef,
           onCompact: (/** @type {any} */ msgs) => {
-            rewriteSession(session.file, msgs);
+            rewriteSession(session.file, msgs, 'compact');
             tuiState.persisted = msgs.length;
           },
         });
@@ -415,7 +415,7 @@ export async function runRepl(ctx) {
         // v0.6.3（H-4）：手动 /compact 此前用**追加**落盘（再补一条"压缩点"标记），而压缩前的历史
         // 早已在文件里 → 每次 /compact 文件近乎翻倍，`-c/--continue` 恢复后历史重复并立刻再次触发压缩。
         // 自动压缩走的是 rewriteSession（原子重写）——两处写盘口径不一致，这里统一到重写。
-        rewriteSession(session.file, messages);
+        rewriteSession(session.file, messages, 'compact');
         tuiState.persisted = messages.length;
         // v0.6.3（M-1）：压缩把早期消息（含文件正文）换成了摘要，但读取去重缓存仍记着"这个文件你看过"
         // → 模型再读同一文件只会拿到「内容与上次读取一致」的占位串，而正文已不在上下文里。

package/src/session-events.js

@@ -26,7 +26,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { appendFilePrivateSync } from './atomic-write.js';
 
-/** 本切片先定这 12 类事件；新增类型必须同时更新这里与 `test/session-events.js` 的清单。 */
+/**
+ * 公开事件类型（v0.7.0 B2-a：12 → 13，新增 `messages.replace`）。
+ *
+ * **可忽略性是新增类型的前提**：读侧对未知 type 一律跳过并计入 `skipped`（见 `readEvents`），
+ * 因此旧版读者遇到 `messages.replace` 只会当它不存在，不会把整份日志读坏；反过来，旧日志
+ * （没有该类型）在本版照常可读——语义退化为「只有 compact/message.append」，不改变任何
+ * 既有事件形状。新增类型必须同时更新这里与 `test/session-events.js` 的清单。
+ */
 export const EVENT_TYPES = Object.freeze([
   'session.start',
   'turn.start',
@@ -38,6 +45,7 @@ export const EVENT_TYPES = Object.freeze([
   'message.append',
   'usage',
   'compact',
+  'messages.replace',
   'interrupt',
   'checkpoint',
 ]);
@@ -45,14 +53,14 @@ export const EVENT_TYPES = Object.freeze([
 /**
  * 审批事件（v0.6.40 悬空闭合切片）：`approval.asked` / `approval.decided` 由审批轨道写入。
  *
- * 为什么不并进 `EVENT_TYPES`：那份清单是**对外公开**的 12 类事件，条数被既有回归套件
- * （`test/session-events.js` ①）逐字钉死；本切片不允许改那套断言。但读取与追加又必须认它们——
- * 否则修补器看不见「永远在等审批」的悬空 ask，也没法把合成的 decided 追加进日志。
- * 因此：`EVENT_TYPES` 仍是 12 类；内部可读写集合 = 12 类 + 审批 2 类。
+ * 为什么不并进 `EVENT_TYPES`：那份清单是**对外公开**的事件类型（v0.7.0 B2-a 起 13 类），
+ * 条数被回归套件（`test/session-events.js` ①）逐字钉死；本切片不允许改那套断言。但读取与
+ * 追加又必须认它们——否则修补器看不见「永远在等审批」的悬空 ask，也没法把合成的 decided
+ * 追加进日志。因此：`EVENT_TYPES` 仍是 13 类；内部可读写集合 = 13 类 + 审批 2 类。
  */
 export const APPROVAL_EVENT_TYPES = Object.freeze(['approval.asked', 'approval.decided']);
 
-/** 内部接受的事件类型：公共 12 类 + 审批 2 类（变量名保持 `EVENT_TYPE_SET`，既有变异锚点不变）。 */
+/** 内部接受的事件类型：公共 13 类 + 审批 2 类（变量名保持 `EVENT_TYPE_SET`，既有变异锚点不变）。 */
 const EVENT_TYPE_SET = new Set([...EVENT_TYPES, ...APPROVAL_EVENT_TYPES]);
 
 /** 审批/工具的关联键字段（按优先级；没有键时按「最近一条」兜底配对）。 */
@@ -67,6 +75,18 @@ export const SYNTHETIC_REASON = '进程中断（启动时合成闭合事件）';
 /** 回滚开关：`MINGDAO_EVENT_LOG=0`（或 false/off/no）时全局关闭双写。 */
 export const EVENT_LOG_ENV = 'MINGDAO_EVENT_LOG';
 
+/**
+ * 事件日志**格式版本**（写在 `session.start` 的 `data.format` 里）。
+ *
+ * 为什么需要：0.6.42 之前 `rewriteSession()` 完全不写事件，旧日志**无法**从事件流恢复历史。
+ * 对拍工具需要一个可靠依据来区分"旧日志不可回溯（历史噪声）"与"新日志重放回归（真 bug）"——
+ * 靠"条数/前缀"猜是不行的（实测会把内容不一致误判成历史噪声）。这就是 DSH `session-format-v*` 的同一思路。
+ *
+ *   1 = 0.6.35–0.6.41：只有 appendMessages 双写，rewrite 无事件
+ *   2 = 0.6.42 起：rewriteSession 也写 `messages.replace`
+ */
+export const EVENT_LOG_FORMAT = 2;
+
 /** 中断时补的 tool 占位文案——与 `agent.js#finishTurn` 的既有文案保持逐字一致。 */
 export const INTERRUPTED_TOOL_CONTENT = '（已中断，未执行）';
 
@@ -327,13 +347,24 @@ export function appendEvent(eventFile, { type = '', data = {}, at = null } = {})
         const newSize = tail.size + Buffer.byteLength(prefix + json + '\n', 'utf8');
         // 末尾校验：确认最后一行就是刚写下的事件（锁内不会有第二个写方）。
         const verify = readTail(file);
-        const lines = verify.text.split('\n').filter((l) => l.trim());
-        const last = lines.length ? lines[lines.length - 1] : '';
+        const lastLineOf = (/** @type {string} */ text) => {
+          const lines = text.split('\n').filter((l) => l.trim());
+          return lines.length ? lines[lines.length - 1] : '';
+        };
         let ok = false;
         try {
-          const parsed = JSON.parse(last.replace(/\r$/, ''));
+          const parsed = JSON.parse(lastLineOf(verify.text).replace(/\r$/, ''));
           ok = parsed?.seq === seq && parsed?.type === type;
         } catch {}
+        // v0.7.0 B2-a：单条事件可能 > TAIL_BYTES（压缩摘要/工具结果/整份 messages.replace）。
+        // 尾窗会把最后一行截断，JSON.parse 必然失败——这不是写失败。只在「尾窗确实没覆盖
+        // 整个文件」时回退整文件重验最后一行（大事件才走这条路，代价与事件大小同阶）。
+        if (!ok && verify.size > TAIL_BYTES) {
+          try {
+            const parsed = JSON.parse(lastLineOf(fs.readFileSync(file, 'utf8')).replace(/\r$/, ''));
+            ok = parsed?.seq === seq && parsed?.type === type;
+          } catch {}
+        }
         if (!ok) return { ok: false, error: `事件写入后校验失败（seq=${seq}）` };
         seqCache.set(file, { seq, size: newSize });
         return { ok: true, error: null, seq };
@@ -692,7 +723,9 @@ export function missingToolCallIds(messages) {
  *
  * 语义（与双写顺序一致）：
  *   · `message.append`：`data.message` 追加到末尾；
- *   · `compact`：`data.messages` 是压缩后的**新基线**，整体替换（后续 append 接在它后面）；
+ *   · `compact` / `messages.replace`：`data.messages` 是**新基线**，整体替换当前窗口
+ *     （后续 message.append 按 seq 顺序接在它后面）。两者语义相同：`compact` 是切片 A 的旧
+ *     类型，`messages.replace`（v0.7.0 B2-a）覆盖压缩 / rewrite / resume 等所有整份重写。
  *   · `interrupt`：`data.toolCallIds` 里的 id 若在最终消息里仍没有 tool 回填，则在对应
  *     assistant 之后补一条 `（已中断，未执行）` 占位——**延迟到所有事件处理完再补**，这样
  *     随后到达的 message.append 若已含占位就不会重复，也不会插错位置。
@@ -708,7 +741,7 @@ export function replayToMessages(events) {
     if (ev.type === 'message.append') {
       const m = ev.data?.message;
       if (m && typeof m === 'object' && !Array.isArray(m)) messages.push(cloneJson(m));
-    } else if (ev.type === 'compact') {
+    } else if (ev.type === 'compact' || ev.type === 'messages.replace') {
       const base = ev.data?.messages;
       if (Array.isArray(base)) {
         messages = base.filter((m) => m && typeof m === 'object' && !Array.isArray(m)).map(cloneJson);

package/src/session.js

@@ -3,7 +3,7 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-import { appendEvent, eventFileFor, eventLogEnabled, isEventLogName, repairEventLog, warnEventFailure } from './session-events.js';
+import { appendEvent, eventFileFor, eventLogEnabled, isEventLogName, repairEventLog, warnEventFailure, EVENT_LOG_FORMAT } from './session-events.js';
 
 // —— 冲突备份名（单一事实来源，v0.4.6）——
 // 同步冲突时写入的备份：<会话名>.server-<时间戳>[-<随机后缀>].jsonl（远端版本）与 .remote-（远端拉取版本）。
@@ -134,7 +134,7 @@ function doubleWriteSessionEvents(file, messages) {
   try {
     // 事件流的第一条：只在文件尚不存在时写一次（并发下最多重复一条 session.start，无害）。
     if (!fs.existsSync(eventFile)) {
-      const start = appendEvent(eventFile, { type: 'session.start', data: { session: path.basename(String(file)) } });
+      const start = appendEvent(eventFile, { type: 'session.start', data: { session: path.basename(String(file)), format: EVENT_LOG_FORMAT } });
       if (!start.ok) {
         warnEventFailure(eventFile, start.error ?? null);
         return;
@@ -161,11 +161,65 @@ export function appendMessages(file, messages) {
   doubleWriteSessionEvents(file, messages); // 旁路：失败只 warn，不影响上面的会话写入
 }
 
+/** 允许的整份重写原因；认不出的一律按 `rewrite`（事件里的 reason 永远是有限集合）。 */
+const REWRITE_REASONS = new Set(['compact', 'resume', 'rewrite']);
+
+/**
+ * 归一化 `rewriteSession` 的 reason：`compact` / `resume` / `rewrite`，其余（含缺省）→ `rewrite`。
+ * @param {any} value
+ * @returns {string}
+ */
+function normalizeRewriteReason(value) {
+  const s = String(value ?? '').trim();
+  return REWRITE_REASONS.has(s) ? s : 'rewrite';
+}
+
+/**
+ * v0.7.0 B2-a：整份重写（压缩 / --resume / /clear / CLI 全量重写）的双写。
+ *
+ * 必须在会话文件**写盘成功之后**调用：`messages.replace` 的语义是「把当前派生窗口整体替换为
+ * data.messages」，不是增量。先写事件后写会话，一旦会话写失败就会留下「事件侧车已前进、消息
+ * 文件没动」的分叉。事件写入失败只 warn（与 appendMessages 同口径），绝不回滚也不抛出——
+ * 会话文件已经落盘，事件的完整性不能反过来决定会话是否成功。
+ * @param {any} file
+ * @param {any[]} messages
+ * @param {any} reason
+ */
+function doubleWriteReplaceEvents(file, messages, reason) {
+  if (!eventLogEnabled()) return;
+  const eventFile = eventFileFor(file);
+  if (!eventFile) return;
+  try {
+    // 与 appendMessages 一致：事件流的第一条 session.start 只在文件尚不存在时写一次。
+    if (!fs.existsSync(eventFile)) {
+      const start = appendEvent(eventFile, { type: 'session.start', data: { session: path.basename(String(file)), format: EVENT_LOG_FORMAT } });
+      if (!start.ok) {
+        warnEventFailure(eventFile, start.error ?? null);
+        return;
+      }
+    }
+    const r = appendEvent(eventFile, {
+      type: 'messages.replace',
+      data: { messages, reason: normalizeRewriteReason(reason) },
+    });
+    if (!r.ok) warnEventFailure(eventFile, r.error ?? null);
+  } catch (err) {
+    warnEventFailure(eventFile, String(/** @type {any} */ (err)?.message ?? err));
+  }
+}
+
 // 整文件原子重写：自动压缩后把会话文件同步为压缩形态（否则每次加载历史都会重新触发压缩）
-/** @param {any} file @param {any} messages */
-export function rewriteSession(file, messages) {
+/**
+ * @param {any} file
+ * @param {any} messages
+ * @param {string} [reason] `compact` / `resume` / `rewrite`（缺省或非法 = `rewrite`）
+ */
+export function rewriteSession(file, messages, reason = 'rewrite') {
   const lines = messages.map((/** @type {any} */ m) => JSON.stringify(m)).join('\n');
   atomicWriteFileSync(file, lines + (lines ? '\n' : ''), { mode: 0o600 }); // 质检 H4：会话文件原子写
+  // v0.7.0 B2-a：重写是「整体替换窗口」，必须以 messages.replace 落事件（append-only，不删旧行）。
+  // 只有会话文件写成功之后才写；失败只 warn（见 doubleWriteReplaceEvents）。
+  doubleWriteReplaceEvents(file, messages, reason);
 }
 
 /** 每个会话文件每进程只尝试修补一次；失败也不重试（避免每次读取都整份读事件日志）。 */

package/src/tasks/worker.js

@@ -107,7 +107,7 @@ export async function runWorkerTask(id, question, { permission, model, offpeak }
       mcp: mcpFacade || undefined,
       sessionRef,
       onCompact: (/** @type {any} */ msgs) => {
-        rewriteSession(session.file, msgs);
+        rewriteSession(session.file, msgs, 'compact');
         persistedCount = msgs.length;
       },
     });