mingdao-harness 0.6.42 → 0.6.44

package/docs/CONFIG.md

@@ -28,7 +28,9 @@
 可选字段：`temperature`、`maxOutputTokens`、`includeUsage`（流式请求 usage 统计，个别网关不支持
 `stream_options` 时设 `false`）、`autoTitle`（自动生成会话标题，默认开）、`notify`（任务桌面通知，默认开）、
 `autoCompact`（上下文自动压缩，默认开，见下）、`audit`（工具调用审计，默认开，见下）、
-`eventLog`（会话事件日志双写，默认开，见下）。
+`eventLog`（会话事件日志双写，默认开，见下）、`eventSource`（会话读取真源，`messages`（默认）/
+`events`，见下——**灰度开关，风险提示**：`events` 会用事件日志派生消息，一旦与消息文件对拍不一致
+就 warn 并回退到消息数组；只在验证「事件流能否当唯一真源」时临时开启，**不要长期依赖**）。
 
 ### WebUI 设置项的「默认值」列（只读，不落盘）
 
@@ -105,6 +107,12 @@ MingDao 先用 executor 模型（路由关闭时为当前模型）把被裁段
   resume / 空会话 / `tool_calls` 等场景与消息数组 deepEqual。
 - **回滚开关**：`"eventLog": false`（默认开）或环境变量 `MINGDAO_EVENT_LOG=0`。关闭后**完全**
   停止事件写入（含 `message.append` 与 `messages.replace` 双写），会话文件照常写入。
+- **读取真源（灰度开关，默认 `messages`）**：`"eventSource": "events"` 时 `loadSession()` 尝试用事件日志
+  重放派生消息；只有 `session.start.data.format >= 2` **且**与 `.jsonl` 消息数组逐条对拍一致才
+  采用。日志缺失 / 格式戳缺失或过旧 / 读失败 → **静默**回退消息数组（灰度期常态，不刷 warn）；
+  对拍不一致 → warn 一行（含文件与首个差异位置：`第 N 条`）并回退。返回值形状不变。默认
+  `"messages"` 保持只读消息数组、与 0.6.x 逐字节一致；**翻默认要等 `scripts/event-parity.mjs`
+  的真实会话证据（不再有 incomplete）**，不要仅凭配置开启就认为事件已是唯一真源。
 - **兼容**：新增类型只追加、不改变既有事件形状；读侧对未知 type 一律跳过并计入 `skipped`，
   因此旧版本读到 `messages.replace` 只会当它不存在，旧日志（没有该类型）在新版本照常可读。
   旧会话没有 events 文件时读取返回空流；事件侧车不会出现在会话列表/最近会话中；事件文件不

package/package.json

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

package/src/commands/repl.js

@@ -164,7 +164,7 @@ export async function runRepl(ctx) {
         '选择要恢复的会话：',
         list.map((s) => ({ value: s.file, label: `${relativeTime(s.mtime)} · ${sessionPreview(s.file)}` }))
       );
-      const loaded = loadSession(choice);
+      const loaded = loadSession(choice, cfg);
       if (loaded.messages.length) {
         session = loaded;
         io.print(style(`✓ 已载入会话 ${path.basename(choice)}（${loaded.messages.length} 条消息）`, C.green));
@@ -174,7 +174,7 @@ export async function runRepl(ctx) {
   if (!session && opts.continueSession) {
     const latest = latestSession(home);
     if (latest) {
-      const loaded = loadSession(latest.file);
+      const loaded = loadSession(latest.file, cfg);
       if (loaded.messages.length) {
         session = loaded;
         io.print(style(`已载入会话 ${latest.name}（${loaded.messages.length} 条消息）`, C.dim));

package/src/config.js

@@ -227,6 +227,43 @@ function applyModelLabels(/** @type {any} */ cfg) {
   return cfg;
 }
 
+/**
+ * 会话读取真源（v0.7.0 B2-b 灰度开关）。
+ *
+ * `messages`（默认）：继续只读 `.jsonl` 消息数组——与 0.6.x 完全一致，事件侧车坏掉也不影响。
+ * `events`：用事件日志重放派生消息，但**必须与消息文件对拍一致**才采用；不一致就 warn 并
+ * 回退到消息数组。这只用于灰度验证「事件流能否当唯一真源」，**不是**新的默认值：
+ * 翻默认要等真实会话的 `scripts/event-parity.mjs` 证据（pass 覆盖足够广、incomplete 清零）。
+ *
+ * 校验口径与 `config.eventLog` 一致：只认字面量 `'events'`，其余（缺省 / 大小写不符 /
+ * 任意非法值）一律按 `'messages'` 处理，绝不因为一个拼错的值把读取路径切到实验分支。
+ */
+export const EVENT_SOURCE_MESSAGES = 'messages';
+export const EVENT_SOURCE_EVENTS = 'events';
+/** 默认真源：`messages`。改这里等于改所有 ENOENT/未配置用户的读取路径，必须等灰度证据。 */
+export const DEFAULT_EVENT_SOURCE = EVENT_SOURCE_MESSAGES;
+const EVENT_SOURCE_SET = new Set([EVENT_SOURCE_MESSAGES, EVENT_SOURCE_EVENTS]);
+
+/**
+ * 归一化 `config.eventSource`：合法枚举原样返回，其余一律回落默认值 `messages`。
+ * 纯函数，读配置/写配置/直接调用 `loadSession(file, cfg)` 三条路径共用同一判据。
+ * @param {any} value
+ * @returns {'messages'|'events'}
+ */
+export function normalizeEventSource(value) {
+  return EVENT_SOURCE_SET.has(value) ? value : DEFAULT_EVENT_SOURCE;
+}
+
+/**
+ * 就地归一化配置对象里的 `eventSource`（字段不存在时**不新增**，保持旧配置文件字节不变）。
+ * @param {any} cfg
+ */
+function applyEventSource(/** @type {any} */ cfg) {
+  if (!isConfigObject(cfg) || cfg.eventSource === undefined) return cfg;
+  cfg.eventSource = normalizeEventSource(cfg.eventSource);
+  return cfg;
+}
+
 // ---------------------------------------------------------------------------
 // v0.7.0 §1.3：配置写入的「基线 + 增量」。
 //
@@ -350,12 +387,12 @@ function prepareConfigForWrite(cfg) {
     quarantineCorruptConfig(`保存配置时读不出来：${strict.error}`);
     base = {};
   }
-  if (!sameHome) return cfg; // 无基线（新配置/字面量）或换了 home → 保持原语义：整份写入
+  if (!sameHome) return applyEventSource(cfg); // 无基线（新配置/字面量）或换了 home → 保持原语义：整份写入
   /** @type {{set: [string[], any][], del: string[][]}} */
   const patch = { set: [], del: [] };
   collectConfigPatch(snapshot.data, cfg, [], patch);
   applyConfigPatch(base, patch);
-  return base;
+  return applyEventSource(base);
 }
 
 /**
@@ -379,7 +416,7 @@ function applyEventLogGate(cfg) {
 export function loadConfig() {
   const r = readConfigStrict();
   if (!r.ok) return null;
-  const cfg = applyModelLabels(applyCachedModelDefaults(r.data));
+  const cfg = applyEventSource(applyModelLabels(applyCachedModelDefaults(r.data)));
   rememberConfig(cfg); // v0.7.0 §1.3：记下基线，saveConfig 只合并增量
   applyEventLogGate(cfg); // v0.7.0 §1.1：config.eventLog=false 在「先落盘、后建 agent」路径也生效
   return cfg;
@@ -401,7 +438,7 @@ export function loadConfig() {
 export function loadConfigForWrite(why = '某个写配置的命令') {
   const r = readConfigStrict();
   if (r.ok) {
-    const cfg = r.data || {};
+    const cfg = applyEventSource(r.data || {});
     rememberConfig(cfg);
     applyEventLogGate(cfg);
     return cfg;
@@ -418,7 +455,7 @@ export function loadConfigForWrite(why = '某个写配置的命令') {
 export function ensureMinimalConfig() {
   const strict = readConfigStrict();
   if (strict.ok && strict.data) {
-    const cfg = applyModelLabels(strict.data);
+    const cfg = applyEventSource(applyModelLabels(strict.data));
     rememberConfig(cfg);
     return cfg;
   }
@@ -457,6 +494,7 @@ export function ensureMinimalConfig() {
 export function saveConfig(cfg) {
   try {
     ensureHome();
+    applyEventSource(cfg); // B2-b：写回前也归一化，保证内存基线与落盘值一致
     withStateFileLockSync(configLockFile(), () => {
       writeConfigUnlocked(prepareConfigForWrite(cfg));
       rememberConfig(cfg); // 成功后把这版对象当作下次增量比较的基线
@@ -479,6 +517,7 @@ export function saveConfig(cfg) {
 export async function saveConfigAsync(cfg) {
   try {
     ensureHome();
+    applyEventSource(cfg); // B2-b：写回前也归一化，保证内存基线与落盘值一致
     await withFileLock(configLockFile(), () => {
       writeConfigUnlocked(prepareConfigForWrite(cfg));
       rememberConfig(cfg);
@@ -513,7 +552,7 @@ export function updateConfigSync(/** @type {(cfg: any) => any} */ mutate) {
         cfg = {};
       }
       const next = typeof mutate === 'function' ? mutate(cfg) : cfg;
-      const out = isConfigObject(next) ? next : cfg;
+      const out = applyEventSource(isConfigObject(next) ? next : cfg);
       writeConfigUnlocked(out);
       rememberConfig(out);
       return { ok: true, error: null, config: out };
@@ -543,7 +582,7 @@ export async function updateConfig(/** @type {(cfg: any) => any} */ mutate) {
         cfg = {};
       }
       const next = typeof mutate === 'function' ? mutate(cfg) : cfg;
-      const out = isConfigObject(next) ? next : cfg;
+      const out = applyEventSource(isConfigObject(next) ? next : cfg);
       writeConfigUnlocked(out);
       rememberConfig(out);
       return { ok: true, error: null, config: out };

package/src/session-events.js

@@ -75,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 = '（已中断，未执行）';
 
@@ -765,6 +777,39 @@ export function replayToMessages(events) {
   return messages;
 }
 
+/**
+ * 比较两个消息数组（v0.7.0 B2-b 从 `scripts/event-parity.mjs` 抽出的共享判据）。
+ *
+ * 逐条按 `role + content + tool_calls`（tool_calls 只比 id，排序后）比较；`_` 开头的运行时注记
+ * 不落盘、不参与比较。**必须与 scripts/event-parity.mjs 的 `diffMessages` 保持同一语义**：
+ * 对拍工具说「等价」的会话，`loadSession({eventSource:'events'})` 才能采用派生结果；两边判据
+ * 一旦漂移，对拍结论与灰度读取就会互相打脸。
+ *
+ * 为什么不直接 import 脚本：`scripts/` 不在 `package.json#files`（npm 安装形态没有它），
+ * 且 tsconfig 会把脚本拉进类型检查；因此判据放在 src 侧，脚本侧保留同名实现（硬约束：本切片
+ * 不改 `scripts/event-parity.mjs`）。
+ *
+ * @param {any[]} a
+ * @param {any[]} b
+ * @returns {{ok:boolean, index:number, reason:string}}
+ */
+export function diffMessages(a, b) {
+  const A = Array.isArray(a) ? a : [];
+  const B = Array.isArray(b) ? b : [];
+  if (A.length !== B.length) return { ok: false, index: Math.min(A.length, B.length), reason: `条数不同：消息 ${A.length} vs 重放 ${B.length}` };
+  const norm = (/** @type {any} */ m) => {
+    /** @type {{role:string, content:any, tool_calls?:string[], tool_call_id?:string}} */
+    const out = { role: String(m?.role ?? ''), content: m?.content ?? '' };
+    if (Array.isArray(m?.tool_calls)) out.tool_calls = m.tool_calls.map((/** @type {any} */ t) => String(t?.id ?? '')).sort();
+    if (m?.tool_call_id != null) out.tool_call_id = String(m.tool_call_id);
+    return JSON.stringify(out);
+  };
+  for (let i = 0; i < A.length; i += 1) {
+    if (norm(A[i]) !== norm(B[i])) return { ok: false, index: i, reason: `第 ${i + 1} 条不同` };
+  }
+  return { ok: true, index: -1, reason: '' };
+}
+
 /**
  * 供后续 UI/诊断用的 turn 摘要（可选；纯函数）。只从事件自己推导，不读消息正文。
  * @param {any[]} events

package/src/session.js

@@ -3,7 +3,10 @@
 
 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, diffMessages, isEventLogName, readEvents, replayToMessages, repairEventLog, warnEventFailure, EVENT_LOG_FORMAT } from './session-events.js';
+// v0.7.0 B2-b：读取真源开关。归一化放在 config.js（配置读取/写回/直接传 cfg 三条路径共用），
+// 对拍比较函数抽在 session-events.js 的 `diffMessages`（与 scripts/event-parity.mjs 同一判据）。
+import { normalizeEventSource, EVENT_SOURCE_EVENTS } from './config.js';
 
 // —— 冲突备份名（单一事实来源，v0.4.6）——
 // 同步冲突时写入的备份：<会话名>.server-<时间戳>[-<随机后缀>].jsonl（远端版本）与 .remote-（远端拉取版本）。
@@ -134,7 +137,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;
@@ -192,7 +195,7 @@ function doubleWriteReplaceEvents(file, messages, reason) {
   try {
     // 与 appendMessages 一致：事件流的第一条 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;
@@ -262,7 +265,44 @@ export function repairSessionEvents(file, cfg = null) {
   }
 }
 
-/** @param {any} file @param {any} [cfg] */
+/**
+ * v0.7.0 B2-b：从事件侧车派生消息（灰度读取真源）。
+ *
+ * 返回 `null` 表示**不采用事件源**——无侧车 / 格式戳缺失或早于本版 / 事件日志读失败。
+ * 这三种都是灰度期常态（旧会话本来就没有 `messages.replace`），调用方必须**静默**回退到
+ * 消息数组，不刷 warn；只有「格式够新、派生出来了、但与消息文件对拍不一致」才是需要可见的异常。
+ * @param {any} file 会话文件（.jsonl）
+ * @returns {any[]|null}
+ */
+function messagesFromEvents(file) {
+  const eventFile = eventFileFor(file);
+  if (!eventFile) return null;
+  try {
+    if (!fs.existsSync(eventFile)) return null;
+    const read = readEvents(eventFile);
+    if (!read.ok) return null;
+    // 与 scripts/event-parity.mjs 同一判据：format >= EVENT_LOG_FORMAT 才认为日志可完整回溯
+    // （旧日志没有 rewrite 记录，派生出来必然缺窗口，不能拿它当读取真源）。
+    const newFormat = read.events.some((ev) => ev.type === 'session.start' && Number(ev.data?.format) >= EVENT_LOG_FORMAT);
+    if (!newFormat) return null;
+    return replayToMessages(read.events);
+  } catch {
+    // 事件侧车是旁路：任何异常都只意味着「这次不用事件源」，绝不能让会话读不出来。
+    return null;
+  }
+}
+
+/**
+ * 读取会话。默认（`eventSource` 缺省或 `messages`）只读 `.jsonl` 消息数组，行为与 0.6.x 一致。
+ *
+ * `cfg.eventSource === 'events'`（v0.7.0 B2-b 灰度开关）时额外尝试事件日志派生，但必须通过
+ * **对拍兜底**：派生结果与消息文件逐条等价才采用；不一致就 warn（带文件与首个差异位置）并
+ * 回退到消息数组。事件源缺失 / 格式旧 / 读失败一律静默回退。
+ *
+ * @param {any} file
+ * @param {any} [cfg] 传入时尊重 `cfg.eventSource` 与 `cfg.eventLog === false`（后者只影响修补器）
+ * @returns {{file:any, messages:any[]}} 形状与旧版完全一致
+ */
 export function loadSession(file, cfg = null) {
   const raw = fs.readFileSync(file, 'utf8');
   const messages = [];
@@ -275,10 +315,30 @@ export function loadSession(file, cfg = null) {
       }
     } catch {}
   }
+  let result = messages;
+  if (normalizeEventSource(cfg?.eventSource) === EVENT_SOURCE_EVENTS) {
+    const derived = messagesFromEvents(file);
+    if (derived) {
+      const d = diffMessages(messages, derived);
+      if (d.ok) result = derived;
+      else {
+        // 对拍失败是**真异常**（新格式日志理应可完整重放）：必须可见，并带首个差异位置。
+        // 但读取结果仍回退到消息数组——灰度期不能让实验分支改变用户看到的历史。
+        const at = d.index >= 0 ? `第 ${d.index + 1} 条` : '未知';
+        try {
+          console.warn(
+            `[MingDao] ⚠ 会话事件源对拍不一致（${file}）：${d.reason}；差异位置：${at}——已回退到消息数组` +
+              `（config.eventSource=events 仅灰度验证用，默认仍是 messages）。`
+          );
+        } catch {}
+      }
+    }
+  }
   // v0.6.40：消息读完后顺带闭合悬空事件。失败只 warn（repairSessionEvents 内部吞掉），
   // 返回值与消息数组一字不动——事件侧车坏了/修不了，会话照样可读。
+  // v0.7.0 B2-b：放在事件派生之后，派生读到的是修补前的日志（与 scripts/event-parity.mjs 同口径）。
   repairSessionEvents(file, cfg);
-  return { file, messages };
+  return { file, messages: result };
 }
 
 // 会话预览：第一条用户消息（用于会话选择器）

package/src/web/routes/domains/sessions.js

@@ -89,7 +89,7 @@ export async function handle({ req, res, method, p, url }, deps, shared) {
     const file = url.searchParams.get('file');
     if (!file) return json(res, 400, { error: '缺少 file 参数' });
     try {
-      const loaded = loadSession(path.join(home, 'sessions', path.basename(file)));
+      const loaded = loadSession(path.join(home, 'sessions', path.basename(file)), deps.cfg);
       // 载入会话时聚焦其工作空间（P3-4）：全局默认切到该会话的目录，前端下拉同步显示
       const wsDir = getSessionWorkspace(path.basename(file));
       const ws = workspaceForDir(wsDir);
@@ -189,7 +189,7 @@ export async function handle({ req, res, method, p, url }, deps, shared) {
       return json(res, 404, { error: `会话不存在：${file}` });
     }
     try {
-      const loaded = loadSession(path.join(home, 'sessions', file));
+      const loaded = loadSession(path.join(home, 'sessions', file), deps.cfg);
       if (loaded.messages.length) {
         const wsDir = getSessionWorkspace(file) || state.workingDir;
         const { finalizeSession } = await import('../../../memory.js');

package/src/web/server.js

@@ -819,7 +819,7 @@ export async function runWebServer({ host = '127.0.0.1', port = 3820, authToken,
     const isNew = !body.file;
     if (body.file) {
       try {
-        const loaded = loadSession(path.join(home, 'sessions', path.basename(body.file)));
+        const loaded = loadSession(path.join(home, 'sessions', path.basename(body.file)), cfg);
         if (loaded.messages.length) session = loaded;
       } catch {}
     }