dsh-log-contract 0.2.1 → 0.3.0

package/README.md

@@ -183,3 +183,20 @@ node scripts/check-local-fossils.mjs   # 扫描 ../ 下 backup-session-*.jsonl.z
 ## 许可
 
 MIT © OfferKuai Team
+
+
+## 🧭 会话考古（extract / audit-report）
+
+DSH 会话日志持久化了每次工具调用的完整输入输出——数据资产与审计资产。
+本工具提供只读考古能力：
+
+```sh
+# 按命令正则导出工具输出（保留原始文本）
+dsh-log-contract extract <session-log> --pattern "seed-scale" --min-size 50 --out ./found
+
+# 考古审计报告：调用数 / 配对率 / 孤儿数 / 命令分布
+dsh-log-contract audit-report <session-log>
+```
+
+契约规则 P3（tool/call↔tool/result 配对完整性）与 P4（输出结构可解析）
+守护"挖得动"：孤儿调用、text 字段异常在 check 中告警。

package/bin/dsh-log-contract.mjs

@@ -13,7 +13,7 @@
  *   contracts                     列出内置契约规则目录
  */
 import fs from 'node:fs';
-import { loadSessionLog, validateSessionLog, createPreWriter, repairSession, CONTRACT_RULES, ruleById } from '../lib/index.js';
+import { loadSessionLog, validateSessionLog, createPreWriter, repairSession, CONTRACT_RULES, ruleById, extractToolOutputs, auditToolCalls } from '../lib/index.js';
 
 const USAGE = `dsh-log-contract —— 日志契约守护（DSH session log contract guard）
 
@@ -39,6 +39,13 @@ const USAGE = `dsh-log-contract —— 日志契约守护（DSH session log cont
         { "edit": [ ...事件列表... ] }          帧级手术后的完整事件列表
       判定通过/拒绝并列出全部违规（三层契约：持久化/引擎/插件）。
 
+  dsh-log-contract extract <session-log> --pattern <regex> [--out DIR] [--min-size N] [--json]
+      考古提取：按命令正则导出工具输出（只读）。--out 写到目录（保留原始文本），
+      否则打印前 3 条摘要。--min-size 过滤小输出（默认 50，任务书口径）。
+
+  dsh-log-contract audit-report <session-log> [--json]
+      考古审计报告：调用数 / 配对率 / 孤儿数 / 命令分布。
+
   dsh-log-contract contracts
       列出内置契约规则目录（含官方源码出处）。
 
@@ -164,13 +171,15 @@ function cmdFix(args) {
   const dropFailedTurns = args.includes('--drop-failed-turns');
   const trimIdx = args.indexOf('--trim-last');
   const trimLast = trimIdx >= 0 && args[trimIdx + 1] ? Number(args[trimIdx + 1]) : undefined;
+  const compactIdx = args.indexOf('--compact-last');
+  const compactLast = compactIdx >= 0 && args[compactIdx + 1] ? Number(args[compactIdx + 1]) : undefined;
   const apply = args.includes('--apply');
   const backupDirIdx = args.indexOf('--backup-dir');
   const backupDir = backupDirIdx >= 0 && args[backupDirIdx + 1] ? args[backupDirIdx + 1] : undefined;
   const file = args.find((a) => !a.startsWith('-'));
   if (!file) fail(USAGE);
 
-  const result = repairSession(file, { removeMarkers, dropFailedTurns, trimLast, apply, backupDir });
+  const result = repairSession(file, { removeMarkers, dropFailedTurns, trimLast, compactLast, apply, backupDir });
   if (json) {
     process.stdout.write(JSON.stringify(result, null, 2) + '\n');
     process.exit(result.ok ? 0 : 1);
@@ -193,6 +202,66 @@ function cmdFix(args) {
   process.exit(result.ok ? 0 : 1);
 }
 
+function cmdExtract(args) {
+  const json = args.includes('--json');
+  const outIdx = args.indexOf('--out');
+  const outDir = outIdx >= 0 && args[outIdx + 1] ? args[outIdx + 1] : undefined;
+  const minIdx = args.indexOf('--min-size');
+  const minSize = minIdx >= 0 && args[minIdx + 1] ? Number(args[minIdx + 1]) : 50;
+  const patternIdx = args.indexOf('--pattern');
+  const pattern = patternIdx >= 0 && args[patternIdx + 1] ? args[patternIdx + 1] : '';
+  const file = args.find((a) => !a.startsWith('-'));
+  if (!file || pattern === '') fail('extract 需要 <session-log> 与 --pattern <regex>');
+
+  const log = loadSessionLog(file);
+  const { pairs, total } = extractToolOutputs(log.events.map((e) => e.event), pattern, { minSize });
+  if (json) {
+    process.stdout.write(JSON.stringify({ file, pattern, matched: pairs.length, total, pairs: pairs.map((p) => ({ callId: p.callId, command: p.command, size: p.size })) }, null, 2) + '\n');
+    process.exit(0);
+  }
+  process.stdout.write(`\n🔍 dsh-log-contract extract —— ${file}\n`);
+  process.stdout.write(`   命令正则：/${pattern}/ ｜ 匹配 ${pairs.length} 个输出（共 ${total} 个工具调用，min-size ${minSize}）\n`);
+  if (outDir) {
+    fs.mkdirSync(outDir, { recursive: true });
+    let written = 0;
+    for (const p of pairs) {
+      const safe = p.callId.replace(/[^a-zA-Z0-9_-]/g, '_');
+      fs.writeFileSync(`${outDir}/${safe}.txt`, p.text);
+      written += 1;
+    }
+    process.stdout.write(`   已导出 ${written} 个输出到 ${outDir}\n`);
+  } else {
+    for (const p of pairs.slice(0, 3)) {
+      process.stdout.write(`   - [${p.size}B] ${p.command.slice(0, 60)}… ${p.text.slice(0, 80).replace(/\n/g, ' ')}…\n`);
+    }
+    if (pairs.length > 3) process.stdout.write(`   … 其余 ${pairs.length - 3} 个（加 --out DIR 全部导出）\n`);
+  }
+  process.stdout.write('\n');
+  process.exit(0);
+}
+
+function cmdAuditReport(args) {
+  const json = args.includes('--json');
+  const file = args.find((a) => !a.startsWith('-'));
+  if (!file) fail(USAGE);
+  const log = loadSessionLog(file);
+  const report = auditToolCalls(log.events.map((e) => e.event));
+  if (json) {
+    process.stdout.write(JSON.stringify({ file, ...report }, null, 2) + '\n');
+    process.exit(0);
+  }
+  process.stdout.write(`\n📊 dsh-log-contract audit-report —— ${file}\n`);
+  process.stdout.write(`   工具调用 ${report.calls} ｜ 结果 ${report.results} ｜ 孤儿 ${report.orphans} ｜ 配对率 ${(report.pairingRate * 100).toFixed(1)}%\n`);
+  process.stdout.write(`   输出总字节 ${report.outputBytes}`);
+  if (report.largest) process.stdout.write(` ｜ 最大 ${report.largest.size}B（${(report.largest.command || '?').slice(0, 40)}）`);
+  process.stdout.write(`\n   命令分布（前 ${report.commands.top.length} 个去重）：\n`);
+  for (const { command, count } of report.commands.top.slice(0, 8)) {
+    process.stdout.write(`     ${String(count).padStart(4)}  ${(command || '(no-command)').slice(0, 70)}\n`);
+  }
+  process.stdout.write('\n');
+  process.exit(0);
+}
+
 const args = process.argv.slice(2);
 const cmd = args[0];
 if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
@@ -205,6 +274,8 @@ if (cmd === '--version' || cmd === '-v') {
   process.exit(0);
 }
 if (cmd === 'check') cmdCheck(args.slice(1));
+else if (cmd === 'extract') cmdExtract(args.slice(1));
+else if (cmd === 'audit-report') cmdAuditReport(args.slice(1));
 else if (cmd === 'prewrite') cmdPrewrite(args.slice(1));
 else if (cmd === 'fix') cmdFix(args.slice(1));
 else if (cmd === 'contracts') cmdContracts();

package/lib/archaeology.js

@@ -0,0 +1,159 @@
+/**
+ * dsh-log-contract · lib/archaeology.js
+ *
+ * 会话日志考古（任务书 dsh-会话日志考古-插件任务与方法.md）——两插件共享：
+ * retrace 的考古界面/导出（A1-A4）与 log-contract 的 extract/audit-report
+ * （B3/B4）都消费这里的纯函数。**只读不写**（纪律 §8.1）。
+ *
+ * 核心事实（§2）：
+ * - tool/call 的 `data.callId` ↔ tool/result 的 `data.message.source.callId`
+ *   配对（不可用"上一个 call"推断）；
+ * - tool/call 的 `data.arguments`（JSON 串）含 `command`（命令考古）；
+ * - tool/result 的 `data.message.content` 是嵌套 text 结构（输出考古）。
+ */
+/** 元数据字段：不参与考古文本提取。 */
+const META_KEYS = new Set([
+  'type', 'toolCallId', 'isError', 'id', 'role', 'source', 'name', 'status',
+  'usage', 'provider', 'model', 'callId', 'kind', 'version', 'error',
+  'title', 'timestamp', 'threadId', 'messageId', 'sessionId', 'plugin',
+]);
+
+/**
+ * 递归提取 content 中的全部 text（保留顺序，换行连接）。
+ * 只收集 `{type:'text', text}` 块与裸字符串；`tool-result` 之类的类型标签、
+ * toolCallId/isError 等元数据字段一律跳过——避免提取到类型名而非内容。
+ */
+export function extractText(content) {
+  const parts = [];
+  const walk = (node) => {
+    if (typeof node === 'string') {
+      parts.push(node);
+      return;
+    }
+    if (Array.isArray(node)) {
+      for (const item of node) walk(item);
+      return;
+    }
+    if (node !== null && typeof node === 'object') {
+      if (node.type === 'text' && typeof node.text === 'string') {
+        parts.push(node.text);
+        return;
+      }
+      for (const key of Object.keys(node)) {
+        if (META_KEYS.has(key)) continue;
+        if (key === 'text' && typeof node[key] === 'string') {
+          parts.push(node[key]);
+          continue;
+        }
+        walk(node[key]);
+      }
+    }
+  };
+  walk(content);
+  return parts.join('\n');
+}
+
+/** 解析 tool/call 的 arguments（JSON 串容错）。 */
+export function toolCommandOf(event) {
+  if (event?.type !== 'tool/call') return '';
+  try {
+    const args = typeof event.data?.arguments === 'string' ? JSON.parse(event.data.arguments) : event.data?.arguments;
+    return typeof args?.command === 'string' ? args.command : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 提取会话内工具调用 → 输出 的配对表（考古 A1/A2/B3 的基础）。
+ *
+ * @param events - 会话事件数组（按日志顺序）。
+ * @returns {{
+ *   calls: Map<callId, { command: string, callSeq: number }>,
+ *   outputs: Map<callId, { text: string, size: number, resultSeq: number }>,
+ *   orphans: string[],          // 无 result 的 callId（P3 同源）
+ * }}
+ */
+export function indexToolCalls(events) {
+  const calls = new Map();
+  const outputs = new Map();
+  for (const event of events) {
+    if (event.type === 'tool/call') {
+      const callId = event.data?.callId;
+      if (typeof callId === 'string' && callId !== '') {
+        calls.set(callId, { command: toolCommandOf(event), callSeq: event.seq });
+      }
+    } else if (event.type === 'tool/result') {
+      const callId = event.data?.message?.source?.callId;
+      if (typeof callId === 'string' && callId !== '') {
+        const text = extractText(event.data?.message?.content);
+        outputs.set(callId, { text, size: text.length, resultSeq: event.seq });
+      }
+    }
+  }
+  const orphans = [...calls.keys()].filter((callId) => !outputs.has(callId));
+  return { calls, outputs, orphans };
+}
+
+/**
+ * 按命令正则导出工具输出（考古 A2/B3）。
+ *
+ * @param events - 会话事件数组。
+ * @param pattern - 命令正则（字符串或 RegExp；字符串按子串匹配，空则全量）。
+ * @param opts.minSize - 输出最小字节数过滤（默认 0；任务书用 50 过滤噪声）。
+ * @returns {{ pairs: Array<{ callId, command, text, size }>, matched: number, total: number }}
+ */
+export function extractToolOutputs(events, pattern = '', { minSize = 0 } = {}) {
+  const { calls, outputs } = indexToolCalls(events);
+  const re = pattern instanceof RegExp ? pattern : (pattern ? new RegExp(pattern) : null);
+  const pairs = [];
+  for (const [callId, call] of calls) {
+    const matched = re === null || re.test(call.command);
+    if (!matched) continue;
+    const output = outputs.get(callId);
+    if (!output || output.size < minSize) continue;
+    pairs.push({ callId, command: call.command, text: output.text, size: output.size });
+  }
+  return { pairs, matched: pairs.length, total: calls.size };
+}
+
+/**
+ * 会话考古审计报告（B4）：调用数 / 配对率 / 孤儿数 / 命令分布。
+ *
+ * @param events - 会话事件数组。
+ * @returns {{
+ *   calls, results, paired, orphans, pairingRate,
+ *   commands: { top: Array<{ command, count }>, distinct },
+ *   outputBytes, largest: { callId, command, size } | null,
+ * }}
+ */
+export function auditToolCalls(events) {
+  const { calls, outputs, orphans } = indexToolCalls(events);
+  const commandCounts = new Map();
+  for (const call of calls.values()) {
+    const key = call.command || '(no-command)';
+    commandCounts.set(key, (commandCounts.get(key) ?? 0) + 1);
+  }
+  const top = [...commandCounts.entries()]
+    .map(([command, count]) => ({ command, count }))
+    .sort((a, b) => b.count - a.count);
+  let outputBytes = 0;
+  let largest = null;
+  for (const [callId, output] of outputs) {
+    outputBytes += output.size;
+    if (!largest || output.size > largest.size) {
+      largest = { callId, command: calls.get(callId)?.command ?? '', size: output.size };
+    }
+  }
+  const paired = outputs.size;
+  return {
+    calls: calls.size,
+    results: outputs.size,
+    paired,
+    orphans: orphans.length,
+    pairingRate: calls.size > 0 ? paired / calls.size : 0,
+    commands: { top: top.slice(0, 15), distinct: top.length },
+    outputBytes,
+    largest,
+  };
+}

package/lib/checks.js

@@ -265,6 +265,136 @@ export function finalFold(events) {
   }
 }
 
+/**
+ * P3 —— tool/call ↔ tool/result 配对完整性（考古任务书 B1）。
+ * 每个 tool/call 的 `data.callId` 必须能在 tool/result 的
+ * `data.message.source.callId` 中找到配对；孤儿 call（无 result）告警——
+ * 中断/失败轮次可能产生孤儿（合法但要审计）。warning 级：不破坏日志。
+ */
+export function toolPairingViolations(events) {
+  const out = [];
+  const calls = new Map(); // callId → { command, loc }
+  const results = new Set();
+  for (const { event, lineNo } of events) {
+    if (event.type === 'tool/call') {
+      const callId = event.data?.callId;
+      if (typeof callId === 'string' && callId !== '') {
+        let command = '';
+        try {
+          const args = typeof event.data?.arguments === 'string' ? JSON.parse(event.data.arguments) : event.data?.arguments;
+          command = typeof args?.command === 'string' ? args.command.slice(0, 120) : '';
+        } catch { /* 参数解析失败不阻断配对检查 */ }
+        calls.set(callId, { command, loc: { seq: event.seq, lineNo, eventType: event.type } });
+      }
+    } else if (event.type === 'tool/result') {
+      const callId = event.data?.message?.source?.callId;
+      if (typeof callId === 'string' && callId !== '') results.add(callId);
+    }
+  }
+  for (const [callId, { command, loc }] of calls) {
+    if (!results.has(callId)) {
+      out.push(violation('P3', loc, `tool/call ${callId}（命令 ${command || '(未知)'}）没有配对的 tool/result——孤儿调用（中断/失败未落结果），考古提取将缺该输出`));
+    }
+  }
+  return out;
+}
+
+/**
+ * 递归检查 content 的可提取性：任意标量（string/number/boolean/null）都是合法
+ * 元数据（如 isError、toolCallId）——只有 "text 字段存在但值非 string" 才是
+ * 考古提取会漏数据的结构异常（extractText 依赖 text 为 string）。
+ */
+function findUnparsableContent(node, path) {
+  if (typeof node === 'string' || typeof node === 'number' || typeof node === 'boolean' || node === null) return null;
+  if (Array.isArray(node)) {
+    for (let i = 0; i < node.length; i++) {
+      const r = findUnparsableContent(node[i], `${path}[${i}]`);
+      if (r !== null) return r;
+    }
+    return null;
+  }
+  if (typeof node === 'object') {
+    if (Object.prototype.hasOwnProperty.call(node, 'text') && typeof node.text !== 'string') {
+      return `${path}.text（${String(node.text)}，非 string）`;
+    }
+    for (const key of Object.keys(node)) {
+      if (key === 'text') continue;
+      const r = findUnparsableContent(node[key], `${path}.${key}`);
+      if (r !== null) return r;
+    }
+    return null;
+  }
+  return `${path}（${String(node)}）`;
+}
+
+/**
+ * P4 —— tool/result 输出结构契约（考古任务书 B2）。
+ * `data.message.content` 必须可递归解析（list[dict{type:text,text}] 或等价）；
+ * 不可解析片段 = 考古提取将漏数据。空 content（失败/无输出）合法。warning 级。
+ */
+export function toolResultStructureViolations(events) {
+  const out = [];
+  for (const { event, lineNo } of events) {
+    if (event.type !== 'tool/result') continue;
+    const content = event.data?.message?.content;
+    if (!Array.isArray(content) || content.length === 0) continue;
+    const callId = event.data?.message?.source?.callId;
+    const loc = { seq: event.seq, lineNo, eventType: event.type };
+    const bad = findUnparsableContent(content, 'content');
+    if (bad !== null) {
+      out.push(violation('P4', loc, `tool/result ${callId ?? '?'} 的 content 含不可解析片段（${bad}）——考古提取将漏数据`));
+    }
+  }
+  return out;
+}
+
+/**
+ * T1 —— token-meter 配对（复刻 @deepseek-ai/dsh-token-meter 的 _foldEvent 状态机，
+ * 2026-08-28 事故根因 3 固化）：
+ * - `step/start` 打开一个 step（记录 turn/step）；
+ * - `step/end` 必须匹配当前打开的 step/start，否则抛错；
+ * - `assistant/message` 必须匹配当前打开的 step/start（turn/step 完全一致），否则抛错；
+ * - `user/message` / `tool/result` 不检查（token meter 不配对）。
+ *
+ * 违反 = token meter 折叠抛错 → 该会话 `/compact` 与压力测量永久失败。
+ * 已知命中：retrace 的 turn/step=null 编辑/撤回 marker（空 assistant/message replace）——
+ * foldSurface 认可其合法性（M1 只约束 append 形态），但 token meter 崩溃。这是
+ * M1 规则的盲区：M1 没约束"replace 也必须过 token meter"。
+ *
+ * @param events - 行序事件流（`{event, lineNo}`）。
+ * @returns T1 违规列表。
+ */
+export function tokenMeterViolations(events) {
+  const out = [];
+  // 无任何 step/start 的日志：现代 DSH 每个 assistant 回合必有 step/start，
+  // 完全没有说明是极早期格式或简化日志——token-meter 的 step 配对兼容性未
+  // 定义，不做配对检查（避免对旧结构误报；真实事故会话都是现代结构）。
+  if (!events.some(({ event }) => event.type === 'step/start')) return out;
+  let stepStart = undefined;
+  for (const { event, lineNo } of events) {
+    const loc = { seq: event.seq, lineNo, eventType: event.type };
+    if (event.type === 'step/start') {
+      if (stepStart !== undefined) {
+        out.push(violation('T1', loc, `step/start at seq ${event.seq} arrived before turn ${stepStart.turn}/step ${stepStart.step} ended——token meter 折叠会抛错`));
+      }
+      stepStart = { turn: event.data?.turn, step: event.data?.step };
+    } else if (event.type === 'step/end') {
+      if (stepStart === undefined || stepStart.turn !== event.data?.turn || stepStart.step !== event.data?.step) {
+        out.push(violation('T1', loc, `step/end at seq ${event.seq} has no matching step/start event（turn=${String(event.data?.turn)}, step=${String(event.data?.step)}）——token meter 折叠会抛错`));
+      }
+      stepStart = undefined;
+    } else if (event.type === 'assistant/message') {
+      const turn = event.data?.turn;
+      const step = event.data?.step;
+      if (stepStart === undefined || stepStart.turn !== turn || stepStart.step !== step) {
+        const open = stepStart === undefined ? '无打开的 step' : `打开的 step 为 turn ${stepStart.turn}/step ${stepStart.step}`;
+        out.push(violation('T1', loc, `assistant/message at seq ${event.seq} has no matching step/start event（turn=${String(turn)}, step=${String(step)}；${open}）——token meter 折叠会抛错，/compact 与压力测量永久失败（retrace 的 turn-null 编辑/撤回 marker 即命中此条）`));
+      }
+    }
+  }
+  return out;
+}
+
 /** 从事件推导 wire 消息（与 dsh-session deriveEventMessage 同语义）。 */
 export function deriveWireMessage(event) {
   if (event.type === 'user/message') {

package/lib/contracts.js

@@ -197,6 +197,30 @@ export const CONTRACT_RULES = [
     description: '终验：把全部事件按序喂给官方 foldSurface，不抛 = 持久化层通过。S1–S7 任何一条违反都会在此暴露。',
   },
 
+  {
+    id: 'T1',
+    title: 'token-meter 配对：assistant/message 与 step/end 必须匹配当前打开的 step/start',
+    layer: LAYER.ENGINE,
+    severity: SEVERITY.ERROR,
+    source: '@deepseek-ai/dsh-token-meter lib/index.js:566-625 (_foldEvent)',
+    description: 'token meter 折叠要求 assistant/message 与 step/end 与打开的 step/start（turn/step 完全一致）匹配；违反即 /compact 与压力测量永久失败。retrace 的 turn-null 编辑/撤回 marker（空 assistant/message replace）命中此条——foldSurface 认可其合法性但 token meter 崩溃（M1 只约束 append 形态的盲区），压缩前需清理。',
+  },
+  {
+    id: 'P3',
+    title: 'tool/call ↔ tool/result 配对完整性（考古 B1）',
+    layer: LAYER.PLUGIN,
+    severity: SEVERITY.WARNING,
+    source: 'dsh-会话日志考古-插件任务与方法.md §2/§4.2（callId 配对，不可用"上一个 call"推断）',
+    description: '每个 tool/call 的 data.callId 必须能在 tool/result 的 data.message.source.callId 中找到配对；孤儿 call（无 result）告警——中断/失败轮次可能产生孤儿（合法但要审计），考古提取将缺该输出。',
+  },
+  {
+    id: 'P4',
+    title: 'tool/result 输出结构可解析（考古 B2）',
+    layer: LAYER.PLUGIN,
+    severity: SEVERITY.WARNING,
+    source: 'dsh-会话日志考古-插件任务与方法.md §2/§4.2（content 递归 text 结构）',
+    description: 'tool/result 的 data.message.content 必须可递归解析（list[dict{type:text,text}] 或等价）；不可解析片段 = 考古提取将漏数据。空 content（失败/无输出）合法。',
+  },
   // ── M · 客户端引擎层 ────────────────────────────────────────────────────
   {
     id: 'M1',

package/lib/index.js

@@ -7,5 +7,7 @@
 export { loadSessionLog } from './log-reader.js';
 export { validateSessionLog } from './validate.js';
 export { createPreWriter, preWriterFromLog } from './prewrite.js';
-export { repairSession, strictScanText, removeMarkersText, dropFailedTurnsText, trimLastMessagesText, rebuildZstdText } from './repair.js';
+export { repairSession, strictScanText, removeMarkersText, dropFailedTurnsText, trimLastMessagesText, compactLastMessagesText, rebuildZstdText } from './repair.js';
 export { CONTRACT_RULES, LAYER, SEVERITY, ruleById } from './contracts.js';
+export { tokenMeterViolations } from './checks.js';
+export { auditToolCalls, extractText, extractToolOutputs, indexToolCalls, toolCommandOf } from './archaeology.js';

package/lib/prewrite.js

@@ -17,7 +17,12 @@
  * 所有判定复用 `lib/checks.js`（与离线体检同一套逻辑），
  * 保证"体检看到的问题 = 写入前拦下的问题"。
  */
-import { envelopeViolations, engineViolations, finalFold, isSafeInt, pluginViolations, replaySurface, violation } from './checks.js';
+import { envelopeViolations, engineViolations, finalFold, isSafeInt, pluginViolations, replaySurface, tokenMeterViolations, violation } from './checks.js';
+
+/** retrace 类 marker：data.editor 存在（assistant/message replace，turn/step=null）。 */
+function isKnownMarkerCandidate(event) {
+  return Boolean(event) && event.type === 'assistant/message' && event.surfaceOp && event.surfaceOp !== 'append' && event.data?.editor !== undefined;
+}
 
 /** 把一个"拟写事件"规整为带 seq 的事件；seq 未携带时按追加位置赋值。 */
 function normalizeCandidate(candidate, nextSeq) {
@@ -78,6 +83,21 @@ export function createPreWriter(input = {}) {
     if (folded.error) {
       violations.push(violation('S8', { lineNo: null }, `官方 foldSurface 重放失败：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
     }
+    // T1 —— token-meter 配对（事故根因 3 固化）。写前校验只判定**拟写事件自身**
+    // 的 step 配对：retrace 的 turn-null 编辑/撤回 marker 必然命中（空
+    // assistant/message replace 无 step 可配对），但编辑功能必须可用——白名单
+    // 降级为 warning（已知设计债，压缩前需 doctor 清理）；非 marker 的
+    // assistant/message 配对失败保持 error。历史已有事件的 T1 归属离线体检
+    // （check），不在这里重复拦截（否则历史 marker 会让后续编辑全部被拒）。
+    const lastCandidate = candidateEvents[candidateEvents.length - 1];
+    for (const t1 of tokenMeterViolations(candidateEvents.map((event) => ({ event })))) {
+      if (t1.id !== 'T1' || t1.seq !== lastCandidate?.seq) continue;
+      if (isKnownMarkerCandidate(lastCandidate)) {
+        violations.push({ ...t1, severity: 'warning', message: `${t1.message}（已知 retrace marker 设计债：压缩前需 doctor 清理）` });
+      } else {
+        violations.push(t1);
+      }
+    }
     const bySeverity = { error: 0, warning: 0, info: 0 };
     for (const v of violations) bySeverity[v.severity] = (bySeverity[v.severity] ?? 0) + 1;
     return {

package/lib/repair.js

@@ -31,7 +31,7 @@ import path from 'node:path';
 import { constants, zstdCompressSync, zstdDecompressSync } from 'node:zlib';
 import { decompressZstd, loadSessionLog } from './log-reader.js';
 import { validateSessionLog } from './validate.js';
-import { CHUNK_ROW_TYPES, MARKER_PREFIXES } from './checks.js';
+import { CHUNK_ROW_TYPES, MARKER_PREFIXES, SURFACE_TYPES } from './checks.js';
 
 /** 复刻 dsh-session expandRow：chunk 行展开为完整事件（含 data/turn/step）。 */
 function expandChunkRow(row) {
@@ -370,6 +370,165 @@ export function trimLastMessagesText(text, keepMessages) {
   return { ...r, kept: keepMessages, cutoff };
 }
 
+/** 从被遮蔽的 user/assistant 消息做提取式摘要（跨范围均匀采样，不依赖模型）。 */
+function extractiveSummary(msgEvents) {
+  const lines = [];
+  const step = Math.max(1, Math.ceil(msgEvents.length / 18));
+  const sampled = [];
+  for (let i = 0; i < msgEvents.length; i += step) sampled.push(msgEvents[i]);
+  const last = msgEvents[msgEvents.length - 1];
+  if (sampled[sampled.length - 1] !== last) sampled.push(last);
+  for (const ev of sampled) {
+    let text = '';
+    if (ev.type === 'user/message') {
+      text = (ev.data?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join(' ');
+    } else if (ev.type === 'assistant/message') {
+      text = (ev.data?.message?.content ?? []).filter((b) => b.type === 'text').map((b) => b.text).join(' ');
+    }
+    text = text.replace(/\s+/g, ' ').trim();
+    if (!text) continue;
+    const chunk = text.length > 120 ? `${text.slice(0, 120)}…` : text;
+    lines.push(`${ev.type === 'user/message' ? '问' : '答'} ${chunk}`);
+    if (lines.join('\n').length > 1800) break;
+  }
+  if (lines.length === 0) return '（早期对话无文本内容）';
+  return `【早期对话提取式摘要 · 完整原文保留在会话日志与备份中】\n${lines.join('\n')}`;
+}
+
+/**
+ * DSH 官方压缩（compaction）：不删除任何事件——在日志尾部追加
+ * compaction/start → compaction/summary → checkpoint(user/message, replace
+ * [start..end]) → compaction/end，把 [start..end] 从模型表面遮蔽，替换为
+ * 提取式摘要。旧事件全部保留（append-only 审计），日志一行不删。
+ * @param {string} text - JSONL 全文（严格连续）。
+ * @param {number} keepMessages - 保留的最近 append 消息数。
+ * @returns {{ text: string, compacted: boolean, kept: number, shadowed: number, summary: string }}
+ */
+export function compactLastMessagesText(text, keepMessages) {
+  const parts = text.split('\n');
+  const bySeq = new Map();
+  const surfaceNodes = [];
+  for (let i = 1; i < parts.length; i++) {
+    const raw = parts[i].trim();
+    if (!raw) continue;
+    const decoded = decodeLine(raw);
+    if (decoded === null) continue;
+    for (const ev of decoded) {
+      bySeq.set(ev.seq, ev);
+      if (SURFACE_TYPES.has(ev.type)) {
+        const op = ev.surfaceOp;
+        if (op === 'append') surfaceNodes.push(ev.seq);
+        else if (op && op.op === 'replace') {
+          const s = surfaceNodes.indexOf(op.start);
+          const e = surfaceNodes.indexOf(op.end);
+          if (s !== -1 && e !== -1 && s <= e) surfaceNodes.splice(s, e - s + 1);
+          surfaceNodes.push(ev.seq);
+        }
+      }
+    }
+  }
+  const appendMsgs = surfaceNodes.filter((seq) => {
+    const ev = bySeq.get(seq);
+    return ev && (ev.type === 'user/message' || (ev.type === 'assistant/message' && ev.surfaceOp === 'append'));
+  });
+  const total = appendMsgs.length;
+  if (total <= keepMessages) return { text, compacted: false, kept: total, shadowed: 0, summary: '' };
+  const target = appendMsgs[total - keepMessages];
+  let boundary = target;
+  for (const seq of appendMsgs) {
+    const ev = bySeq.get(seq);
+    if (ev.type === 'user/message' && seq <= target) boundary = seq;
+  }
+  const shadowedSeqs = surfaceNodes.filter((seq) => seq < boundary);
+  const start = shadowedSeqs[0];
+  const end = shadowedSeqs[shadowedSeqs.length - 1];
+  const summary = extractiveSummary(shadowedSeqs.map((seq) => bySeq.get(seq)).filter(Boolean));
+  // 压缩事件插入到"第一个保留事件"之前（seq = boundary..boundary+3），
+  // 之后的事件整体 +4 重编号——保证表面顺序为 [checkpoint, 近期轮次…]。
+  const boundarySeq = boundary;
+  const compactionId = `dsh-fix-${Date.now().toString(36)}${Math.floor(Math.random() * 1e6).toString(36)}`;
+  const startSeq = boundarySeq;
+  const summarySeq = boundarySeq + 1;
+  const checkpointSeq = boundarySeq + 2;
+  const endSeq = boundarySeq + 3;
+  const now = Date.now();
+  const appended = [
+    { type: 'compaction/start', seq: startSeq, time: now, data: { compactionId, turn: null } },
+    {
+      type: 'compaction/summary',
+      seq: summarySeq,
+      time: now,
+      data: {
+        compactionId,
+        summary,
+        shadowedRange: { start, end },
+        shadowedSeqs,
+        shadowedTokenCount: Math.round(summary.length / 4),
+        provider: 'dsh-log-contract',
+        model: 'extractive',
+      },
+    },
+    {
+      type: 'user/message',
+      seq: checkpointSeq,
+      time: now,
+      surfaceOp: { op: 'replace', start, end },
+      sourceEventSeqs: [startSeq, summarySeq, ...shadowedSeqs],
+      data: {
+        id: `checkpoint-${compactionId}`,
+        role: 'user',
+        source: { kind: 'user' },
+        content: [{ type: 'text', text: summary }],
+      },
+    },
+    { type: 'compaction/end', seq: endSeq, time: now, data: { compactionId, turn: null } },
+  ];
+  // 找到第一个事件 seq >= boundary 的行（保留区起点），在其前插入压缩事件
+  let insertIdx = parts.length - 1;
+  for (let i = 1; i < parts.length; i++) {
+    const raw = parts[i].trim();
+    if (!raw) continue;
+    const decoded = decodeLine(raw);
+    if (decoded === null || decoded.length === 0) continue;
+    if (decoded[0].seq >= boundarySeq) {
+      insertIdx = i;
+      break;
+    }
+  }
+  const shiftFields = (v) => {
+    if (typeof v.seq === 'number') v.seq += 4;
+    if (CHUNK_ROW_TYPES.has(v.type) && typeof v.seq0 === 'number') v.seq0 += 4;
+    if (Array.isArray(v.sourceEventSeqs)) v.sourceEventSeqs = v.sourceEventSeqs.map((x) => x + 4);
+    if (v.surfaceOp && v.surfaceOp.op === 'replace') {
+      v.surfaceOp.start += 4;
+      v.surfaceOp.end += 4;
+    }
+    return v;
+  };
+  const out = [];
+  for (let i = 0; i < parts.length; i++) {
+    if (i === insertIdx) for (const e of appended) out.push(JSON.stringify(e));
+    const raw = parts[i];
+    if (i > 0 && i >= insertIdx && raw.trim()) {
+      let v;
+      try {
+        v = JSON.parse(raw);
+      } catch {
+        out.push(raw);
+        continue;
+      }
+      if (typeof v.seq === 'number') {
+        out.push(JSON.stringify(shiftFields(v)));
+        continue;
+      }
+    }
+    out.push(raw);
+  }
+  const newText = out.join('\n');
+  if (!newText.endsWith('\n')) return { text: newText + '\n', compacted: true, kept: keepMessages, shadowed: shadowedSeqs.length, summary };
+  return { text: newText, compacted: true, kept: keepMessages, shadowed: shadowedSeqs.length, summary };
+}
+
 /**
  * 按官方 writer 帧格式重建 .jsonl.zstd（帧1=header，帧2=其余，均带 checksum）。
  * @param {string} text - JSONL 全文（以 "\n" 结尾）。
@@ -395,7 +554,7 @@ export function rebuildZstdText(text) {
  * 对单个会话日志执行诊断 +（可选）修复。
  * @param {string} file - .jsonl 或 .jsonl.zstd 路径。
  * @param {{
- *   removeMarkers?: boolean, dropFailedTurns?: boolean, trimLast?: number,
+ *   removeMarkers?: boolean, dropFailedTurns?: boolean, trimLast?: number, compactLast?: number,
  *   apply?: boolean, backupDir?: string
  * }} opts
  * @returns {{
@@ -455,6 +614,13 @@ export function repairSession(file, opts = {}) {
     const r = trimLastMessagesText(plain, opts.trimLast);
     applyFix('trim', r, `裁剪到最近 ${r.kept} 条消息（丢弃 ${r.removed} 行，重编号 ${r.renumbered} 行）`);
   }
+  if (typeof opts.compactLast === 'number') {
+    const r = compactLastMessagesText(plain, opts.compactLast);
+    if (r.compacted) {
+      issues.push({ kind: 'compact', detail: `官方压缩：遮蔽 ${r.shadowed} 个 surface 节点，保留最近 ${r.kept} 条消息；旧事件全部保留（日志零删除）` });
+      plain = r.text;
+    }
+  }
   // 全部修复完成后做一次终检（中间态的临时违规不阻塞——后续修复可能已消除）
   const scanFinal = strictScanText(plain);
   const checkFinal = validateSessionLog(loadSessionLogFromText(plain));

package/lib/validate.js

@@ -17,6 +17,9 @@ import {
   pluginViolations,
   replaySurface,
   violation,
+  tokenMeterViolations,
+  toolPairingViolations,
+  toolResultStructureViolations,
   wireViolations,
 } from './checks.js';
 
@@ -101,6 +104,13 @@ export function validateSessionLog(log, opts = {}) {
   violations.push(...replay.violations);
 
   const folded = finalFold(events.map((e) => e.event));
+
+  // ── T · token meter 配对（事故根因 3）──
+  violations.push(...tokenMeterViolations(events));
+
+  // ── P3/P4 · 考古契约（工具配对 + 输出结构）──
+  violations.push(...toolPairingViolations(events));
+  violations.push(...toolResultStructureViolations(events));
   if (folded.error) {
     violations.push(violation('S8', { lineNo: null }, `官方 foldSurface 重放失败：${folded.error.message} —— 会话加载会被拒（SessionPersistenceCorruptionError）`));
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-log-contract",
   "description": "日志契约守护 — DSH session log contract guard: offline health check (CLI) + pre-write validation for DeepSeek Harness session logs",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",