dsh-retrace 0.4.3 → 0.4.6

package/README.md

@@ -328,3 +328,26 @@ DeepSeek Harness community.
 ## 📄 License
 
 MIT
+
+
+## 🧭 会话日志考古（retrace CLI）
+
+DSH 会话日志持久化了每次工具调用的完整输入输出——数据资产与审计资产。
+`retrace` CLI 提供只读考古能力（复用 dsh-log-contract 0.3.0 的契约与提取）：
+
+```sh
+retrace index <session>                        # 工具调用索引（A1）
+retrace query <session> --cmd "seed-scale"     # 按命令正则查输出（A1）
+retrace extract <session> --pattern "seed-scale" --out ./found   # 导出输出（A2）
+retrace file-history <session> <path>          # 文件 write/edit 历史版本（A3）
+retrace file-diff <session> <path> 0 5         # 两版本行级 diff（A3）
+retrace lineage <session>                      # 会话 parent 链谱系（A4）
+```
+
+<session> 为完整日志路径或 sessionId（自动在 ~/.dsh/sessions 查找）。全部只读。
+
+**分叉图里的会话谱系（A4,UI）**：Fork map 视图头部展示当前会话的
+`parentSession` 接续链（当前会话 → 父 → 根,`←` 方向）。数据来自
+`GET /api/plugins/retrace/lineage?sessionId=`（只读 header 遍历,带环保护）,
+与 CLI `retrace lineage` 同一语义。这样"这个会话是从哪个会话接着干/分叉出来的"
+在界面上一眼可见——也是分叉图拓扑的元数据源。

package/bin/retrace.mjs

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+/**
+ * dsh-retrace · bin/retrace.mjs
+ *
+ * 会话日志考古 CLI（任务书 A1-A4）——只读，不写任何日志。
+ *
+ *   retrace index <session> [--json]
+ *       工具调用索引：调用数 / 配对率 / 孤儿数 / 命令分布（A1）
+ *   retrace query <session> --cmd <regex> [--json]
+ *       按命令正则查工具输出（A1）
+ *   retrace extract <session> --pattern <regex> --out <dir> [--min-size N]
+ *       导出匹配命令的工具输出到目录（A2）
+ *   retrace file-history <session> <path> [--json]
+ *       某文件的所有 write/edit 历史版本（A3）
+ *   retrace file-diff <session> <path> <v1> <v2>
+ *       两个历史版本的行级 diff（A3）
+ *   retrace lineage <session> [--json]
+ *       会话 parent 链谱系（A4，分叉图数据源）
+ *
+ * <session> 为完整文件路径或 sessionId（自动在 ~/.dsh/sessions 查找）。
+ */
+import fs from 'node:fs';
+import { loadSessionLog, extractToolOutputs, auditToolCalls } from 'dsh-log-contract';
+import { replayFileHistory, diffLines, resolveSessionFile, lineageOf } from '../lib/archaeology-cli.js';
+
+const USAGE = `dsh-retrace 考古 CLI —— 会话日志数据/审计资产挖掘（只读）
+
+用法：
+  retrace index <session> [--json]
+  retrace query <session> --cmd <regex> [--json]
+  retrace extract <session> --pattern <regex> --out <dir> [--min-size N]
+  retrace file-history <session> <path> [--json]
+  retrace file-diff <session> <path> <v1> <v2>
+  retrace lineage <session> [--json]`;
+
+function fail(msg) {
+  process.stderr.write(`❌ ${msg}\n\n${USAGE}\n`);
+  process.exit(1);
+}
+
+const args = process.argv.slice(2);
+const cmd = args[0];
+const rest = args.slice(1);
+const json = rest.includes('--json');
+const positional = rest.filter((a) => !a.startsWith('-'));
+const opt = (name, def) => {
+  const i = rest.indexOf(name);
+  return i >= 0 && rest[i + 1] ? rest[i + 1] : def;
+};
+
+function main() {
+  if (cmd === 'index') {
+    const file = resolveSessionFile(positional[0] ?? fail('index 需要 <session>'));
+    const log = loadSessionLog(file);
+    const report = auditToolCalls(log.events.map((e) => e.event));
+    if (json) return process.stdout.write(JSON.stringify({ file, ...report }, null, 2) + '\n');
+    process.stdout.write(`📇 retrace index —— ${file}\n`);
+    process.stdout.write(`   工具调用 ${report.calls} ｜ 结果 ${report.results} ｜ 孤儿 ${report.orphans} ｜ 配对率 ${(report.pairingRate * 100).toFixed(1)}%\n`);
+    process.stdout.write(`   输出总字节 ${report.outputBytes}${report.largest ? ` ｜ 最大 ${report.largest.size}B（${(report.largest.command || '?').slice(0, 40)}）` : ''}\n`);
+    process.stdout.write(`   命令分布（前 8）：\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`);
+    }
+  } else if (cmd === 'query' || cmd === 'extract') {
+    const pattern = opt('--cmd', opt('--pattern', ''));
+    if (!pattern) fail(`${cmd} 需要 --cmd/--pattern <regex>`);
+    const file = resolveSessionFile(positional[0] ?? fail(`${cmd} 需要 <session>`));
+    const log = loadSessionLog(file);
+    const minSize = cmd === 'extract' ? Number(opt('--min-size', '50')) : 0;
+    const { pairs, total } = extractToolOutputs(log.events.map((e) => e.event), pattern, { minSize });
+    if (cmd === 'query') {
+      if (json) return process.stdout.write(JSON.stringify({ file, pattern, matched: pairs.length, total, pairs: pairs.map((p) => ({ callId: p.callId, command: p.command, size: p.size, text: p.text.slice(0, 500) })) }, null, 2) + '\n');
+      process.stdout.write(`🔎 retrace query —— ${file} ｜ /${pattern}/\n`);
+      process.stdout.write(`   匹配 ${pairs.length} 个输出（共 ${total} 个调用）\n`);
+      for (const p of pairs.slice(0, 5)) process.stdout.write(`   - [${p.size}B] ${p.command.slice(0, 50)}… ${p.text.slice(0, 70).replace(/\n/g, ' ')}…\n`);
+      if (pairs.length > 5) process.stdout.write(`   … 其余 ${pairs.length - 5} 个（extract --out 导出全部）\n`);
+    } else {
+      const outDir = opt('--out', '');
+      if (!outDir) fail('extract 需要 --out <dir>');
+      fs.mkdirSync(outDir, { recursive: true });
+      let written = 0;
+      for (const p of pairs) {
+        fs.writeFileSync(`${outDir}/${p.callId.replace(/[^a-zA-Z0-9_-]/g, '_')}.txt`, p.text);
+        written += 1;
+      }
+      process.stdout.write(`📤 retrace extract —— ${file} ｜ /${pattern}/ ｜ ${written}/${pairs.length} 输出 → ${outDir}\n`);
+    }
+  } else if (cmd === 'file-history') {
+    const file = resolveSessionFile(positional[0] ?? fail('file-history 需要 <session>'));
+    const path = positional[1] ?? fail('file-history 需要 <path>');
+    const log = loadSessionLog(file);
+    const { files } = replayFileHistory(log.events.map((e) => e.event));
+    const history = files.get(path) ?? [];
+    if (json) return process.stdout.write(JSON.stringify({ file, path, versions: history.map((v) => ({ seq: v.seq, time: v.time, kind: v.kind, tool: v.tool, hash: v.hash, size: v.size })) }, null, 2) + '\n');
+    process.stdout.write(`📜 retrace file-history —— ${path}（${file}）\n`);
+    if (history.length === 0) {
+      process.stdout.write('   （该文件无 write/edit 记录）\n');
+    } else {
+      history.forEach((v, i) => {
+        process.stdout.write(`   v${i} [${v.kind}/${v.tool}] seq ${v.seq} ${v.size}B ${v.hash} ${(v.time ? new Date(v.time).toISOString().slice(5, 16) : '')}\n`);
+      });
+    }
+  } else if (cmd === 'file-diff') {
+    const file = resolveSessionFile(positional[0] ?? fail('file-diff 需要 <session>'));
+    const path = positional[1] ?? fail('file-diff 需要 <path>');
+    const v1 = Number(positional[2]);
+    const v2 = Number(positional[3]);
+    if (!Number.isInteger(v1) || !Number.isInteger(v2)) fail('file-diff 需要 <v1> <v2>（版本索引）');
+    const log = loadSessionLog(file);
+    const { files } = replayFileHistory(log.events.map((e) => e.event));
+    const history = files.get(path) ?? [];
+    if (v1 < 0 || v2 < 0 || v1 >= history.length || v2 >= history.length) fail(`版本索引越界（共 ${history.length} 个版本）`);
+    const lines = diffLines(history[v1].content, history[v2].content);
+    process.stdout.write(`🔀 retrace file-diff —— ${path} v${v1}(${history[v1].hash}) → v${v2}(${history[v2].hash})\n`);
+    let added = 0;
+    let removed = 0;
+    for (const line of lines) {
+      if (line.op === 'add') added += 1;
+      if (line.op === 'del') removed += 1;
+    }
+    process.stdout.write(`   +${added} / -${removed}\n`);
+    for (const line of lines.slice(0, 40)) {
+      process.stdout.write(`   ${line.op === 'add' ? '+' : line.op === 'del' ? '-' : ' '} ${line.text}\n`);
+    }
+    if (lines.length > 40) process.stdout.write(`   … 其余 ${lines.length - 40} 行\n`);
+  } else if (cmd === 'lineage') {
+    const file = resolveSessionFile(positional[0] ?? fail('lineage 需要 <session>'));
+    const log = loadSessionLog(file);
+    const lineage = lineageOf(log);
+    if (json) return process.stdout.write(JSON.stringify(lineage, null, 2) + '\n');
+    process.stdout.write(`🌿 retrace lineage —— ${lineage.id}\n`);
+    process.stdout.write(`   parent: ${lineage.parentId ?? '(无，根会话)'}\n`);
+  } else {
+    fail(cmd ? `未知命令 "${cmd}"` : '缺少命令');
+  }
+}
+main();

package/lib/archaeology-cli.js

@@ -0,0 +1,150 @@
+/**
+ * dsh-retrace · lib/archaeology-cli.js
+ *
+ * 会话日志考古 CLI 的核心逻辑（任务书 dsh-会话日志考古-插件任务与方法.md A1-A4）。
+ * 与 dsh-log-contract 的 archaeology.js 分工：B 侧提供 extract/audit 纯函数，
+ * 本模块提供 A 侧的文件版本考古（write/edit 重放）与谱系（parent 链）。
+ * **只读不写**（纪律 §8.1）。
+ */
+import { loadSessionLog, extractToolOutputs, auditToolCalls } from 'dsh-log-contract';
+import { accessSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+/** 文件写工具名（与 host-core WRITE_TOOLS 同族；DSH 真实工具名为裸 write/edit）。 */
+const WRITE_NAMES = /^(?:fs\.)?(?:write|edit|create|append|patch|apply-patch)$/i;
+
+/** 从 tool/call 提取文件操作 { path, kind: 'write'|'edit', content? }。 */
+export function fileOpFromCall(event) {
+  if (event?.type !== 'tool/call') return null;
+  const name = typeof event.data?.name === 'string' ? event.data.name : '';
+  if (!WRITE_NAMES.test(name)) return null;
+  let args = {};
+  try {
+    args = typeof event.data?.arguments === 'string' ? JSON.parse(event.data.arguments) : event.data?.arguments ?? {};
+  } catch {
+    return null;
+  }
+  const path = args.file_path ?? args.path ?? args.filePath ?? args.file ?? args.target;
+  if (typeof path !== 'string' || path === '') return null;
+  const isEdit = /edit|patch/i.test(name);
+  if (isEdit) {
+    if (typeof args.old_string !== 'string' || typeof args.new_string !== 'string') return null;
+    return { path, kind: 'edit', oldString: args.old_string, newString: args.new_string, seq: event.seq, time: event.time, name };
+  }
+  if (typeof args.content !== 'string') return null;
+  return { path, kind: 'write', content: args.content, seq: event.seq, time: event.time, name };
+}
+
+/**
+ * 重放会话内全部文件写操作 → 每文件的版本序列（A3）。
+ * write 记全量；edit 基于上一版本做 old→new 替换（重放得到全量）。
+ *
+ * @param events - 会话事件数组。
+ * @returns {{
+ *   files: Map<path, Array<{ seq, time, kind, tool, hash, size, content }>>,
+ * }}
+ */
+export function replayFileHistory(events) {
+  const files = new Map();
+  for (const event of events) {
+    const op = fileOpFromCall(event);
+    if (!op) continue;
+    const history = files.get(op.path) ?? [];
+    let content;
+    if (op.kind === 'write') {
+      content = op.content;
+    } else {
+      const prev = history[history.length - 1]?.content ?? '';
+      content = prev.includes(op.oldString) ? prev.replace(op.oldString, op.newString) : prev;
+    }
+    history.push({
+      seq: op.seq,
+      time: op.time,
+      kind: op.kind,
+      tool: op.name,
+      hash: simpleHash(content),
+      size: content.length,
+      content,
+    });
+    files.set(op.path, history);
+  }
+  return { files };
+}
+
+/** 轻量内容哈希（考古版本标识用，非加密）。 */
+export function simpleHash(text) {
+  let h = 2166136261;
+  for (let i = 0; i < text.length; i++) {
+    h ^= text.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, '0');
+}
+
+/** 行级 diff：返回 { added, removed, lines: [{op:'same'|'add'|'del', text}] }。 */
+export function diffLines(a, b) {
+  const al = a.split('\n');
+  const bl = b.split('\n');
+  const lines = [];
+  let i = 0;
+  let j = 0;
+  // 简单前缀/后缀对齐（考古 diff 够用；完整 LCS 不必要）
+  while (i < al.length && j < bl.length && al[i] === bl[j]) {
+    lines.push({ op: 'same', text: al[i] });
+    i++;
+    j++;
+  }
+  const at = al.length - 1;
+  const bt = bl.length - 1;
+  let ae = al.length;
+  let be = bl.length;
+  while (ae > i && be > j && al[ae - 1] === bl[be - 1]) {
+    ae--;
+    be--;
+  }
+  for (let k = i; k < ae; k++) lines.push({ op: 'del', text: al[k] });
+  for (let k = j; k < be; k++) lines.push({ op: 'add', text: bl[k] });
+  while (ae < al.length) {
+    lines.push({ op: 'same', text: al[ae] });
+    ae++;
+  }
+  return lines;
+}
+
+/** 解析会话参数：完整文件路径，或 sessionId（在 ~/.dsh/sessions 下查找）。 */
+export function resolveSessionFile(ref) {
+  if (typeof ref !== 'string' || ref === '') throw new Error('session 参数不能为空');
+  if (ref.includes('/') || ref.endsWith('.zstd') || ref.endsWith('.jsonl')) return ref;
+  // 按 id 在所有工作区查找
+  const root = join(homedir(), '.dsh', 'sessions');
+  for (const workspace of readdirSync(root)) {
+    const candidate = join(root, workspace, ref, 'session.jsonl.zstd');
+    try {
+      accessSync(candidate);
+      return candidate;
+    } catch { /* keep looking */ }
+  }
+  throw new Error(`session "${ref}" 未在 ~/.dsh/sessions 下找到`);
+}
+
+/**
+ * 谱系（A4）：从当前会话沿 header.parentSession 追溯父链。
+ * @param log - loadSessionLog 结果。
+ * @returns {{ id, parentId, ancestors: Array<{id, parentId}> }}
+ */
+export function lineageOf(log) {
+  const header = log?.header ?? {};
+  const ancestors = [];
+  let parentId = header.parentSession ?? null;
+  const seen = new Set([header.id]);
+  while (parentId && !seen.has(parentId)) {
+    seen.add(parentId);
+    ancestors.push({ id: parentId, parentId: null });
+    // 父会话文件在同一工作区；不递归读文件（只列 id 链，内容读取留给调用方）
+    parentId = null; // 需要父文件才能继续；单次给出直接父
+  }
+  return { id: header.id, parentId: header.parentSession ?? null, ancestors };
+}
+
+export { extractToolOutputs, auditToolCalls, loadSessionLog };