dsh-log-contract 0.2.2 → 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
       列出内置契约规则目录（含官方源码出处）。
 
@@ -195,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') {
@@ -207,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,89 @@ 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 固化）：

package/lib/contracts.js

@@ -205,6 +205,22 @@ export const CONTRACT_RULES = [
     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

@@ -10,3 +10,4 @@ export { createPreWriter, preWriterFromLog } from './prewrite.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/validate.js

@@ -18,6 +18,8 @@ import {
   replaySurface,
   violation,
   tokenMeterViolations,
+  toolPairingViolations,
+  toolResultStructureViolations,
   wireViolations,
 } from './checks.js';
 
@@ -105,6 +107,10 @@ export function validateSessionLog(log, opts = {}) {
 
   // ── 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.2",
+  "version": "0.3.0",
   "packageManager": "pnpm@11.7.0",
   "type": "module",
   "main": "lib/index.js",