@240xu/dsh-message-ops 0.2.2

package/src/ops-core.js

@@ -0,0 +1,269 @@
+/**
+ * dsh-message-ops — 可复用操作核心（纯逻辑，无 HTTP、无 dsh-tools 依赖）。
+ *
+ * HTTP 路由（src/index.js）与 Agent 工具 message_ops 共用这里的函数，
+ * 保证两条入口的行为（规划 / 校验 / 错误语义）完全一致。
+ *
+ * 引擎能力查证（来自安装的运行时 @deepseek-ai/dsh-session/lib/types/surface.js）：
+ *   - SurfaceOp 只有 'append' 与 'replace' 两个变体，不存在「解除遮蔽」
+ *     操作；surface replace 是 append-only 的永久遮蔽。
+ *   - 运行时引擎的 replace 形状是 { op:'replace', startSeq, endSeq }
+ *     （dsh-src 仓库较新副本已改名为 start/end；本插件面向安装的运行时，
+ *     写入用 startSeq/endSeq，读取端两种拼写都兼容以便前向迁移）。
+ *   - 因此「回滚恢复」只能实现为「重放」（replay）：把被遮蔽区间的
+ *     user/assistant 消息文本重新 append 为新事件（文本加 [恢复] 前缀），
+ *     而不是取消遮蔽。语义差异见 README。
+ * @module dsh-message-ops/ops-core
+ */
+
+import { readReplaceOp } from "./session-file.js";
+
+/** 带语义状态码的操作错误（HTTP 直接映射，工具端转为失败文本）。 */
+export class OpsError extends Error {
+  constructor(message, status = 400) {
+    super(message);
+    this.status = status;
+  }
+}
+
+/** 从 message 事件提取首个非空 text 块（与 listMessages 同一规则）。 */
+export function messageText(e) {
+  const msg = e && e.data && e.data.message;
+  const content = msg && Array.isArray(msg.content) ? msg.content : (e && e.data && e.data.content);
+  if (!Array.isArray(content)) return "";
+  for (const c of content) {
+    if (c && c.type === "text" && typeof c.text === "string" && c.text.trim()) return c.text;
+  }
+  return "";
+}
+
+/** planRevert：回撤语义 = 遮蔽 targetSeq 及其之后全部可见节点（连续到末尾）。 */
+export function planRevert(surface, targetSeq) {
+  const nodes = surface && Array.isArray(surface.nodes) ? surface.nodes : [];
+  const startIdx = nodes.indexOf(targetSeq);
+  if (startIdx === -1) throw new OpsError(`surface replace: start seq ${targetSeq} not found in surface`, 409);
+  const shadowedSeqs = nodes.slice(startIdx);
+  if (shadowedSeqs.length === 0) throw new OpsError("nothing to revert", 409);
+  return {
+    startSeq: targetSeq,
+    endSeq: shadowedSeqs[shadowedSeqs.length - 1],
+    shadowedSeqs,
+  };
+}
+
+/** planDelete：单条遮蔽，要求 seq 仍在当前 surface 上可见。 */
+export function planDelete(surface, seq) {
+  const nodes = surface && Array.isArray(surface.nodes) ? surface.nodes : [];
+  if (!nodes.includes(seq)) throw new OpsError(`seq ${seq} not visible on current surface`, 409);
+  return { startSeq: seq, endSeq: seq, shadowedSeqs: [seq] };
+}
+
+// 写端 replace 拼写（前向兼容雷，评审 P1）：当前运行时引擎
+// （@deepseek-ai/dsh-session/lib/types/surface.js 的 isReplaceOp）要求
+// {op:'replace', startSeq, endSeq} 且恰好 3 个键；dsh-src 较新副本已改名
+// {op:'replace', start, end}（同样恰好 3 个键）。写端做一次运行时探测：
+// 先按当前 cohort 的 startSeq/endSeq 形状写，若引擎报
+// "invalid replace surfaceOp"（validateNext 在事件入 log 前抛出，失败不落
+// 状态、无半写风险），降级用 {start,end} 重试一次并记住结果。读端
+// （readReplaceOp/computeShadowed/planRestore）两种拼写始终兼容。
+let replaceShape = null; // null=未探测 | "legacy"=startSeq/endSeq | "new"=start/end
+
+function replaceOpFor(shape, startSeq, endSeq) {
+  return shape === "new"
+    ? { op: "replace", start: startSeq, end: endSeq }
+    : { op: "replace", startSeq, endSeq };
+}
+
+/** 测试专用：重置写端拼写探测缓存。 */
+export function _resetReplaceShape() { replaceShape = null; }
+
+/**
+ * surface replace 落定：append 一条承载 replace 的 system/message。
+ * sourceEventSeqs 必须覆盖被遮蔽的全部 surface 节点（引擎
+ * assertProvenance 强校验，缺失即抛错）。
+ */
+export function applySurfaceReplace(session, startSeq, endSeq, sourceEventSeqs, noticeText) {
+  const data = { message: { role: "system", content: [{ type: "text", text: noticeText }] } };
+  if (replaceShape) {
+    return session.append("system/message", data, { surfaceOp: replaceOpFor(replaceShape, startSeq, endSeq), sourceEventSeqs });
+  }
+  try {
+    const event = session.append("system/message", data, { surfaceOp: replaceOpFor("legacy", startSeq, endSeq), sourceEventSeqs });
+    replaceShape = "legacy";
+    return event;
+  } catch (err) {
+    if (!/invalid replace surfaceOp/.test(String(err && err.message))) throw err;
+    const event = session.append("system/message", data, { surfaceOp: replaceOpFor("new", startSeq, endSeq), sourceEventSeqs });
+    replaceShape = "new";
+    return event;
+  }
+}
+
+/**
+ * planRestore：从磁盘事件流规划「回滚恢复」。
+ *
+ * @param {Array} events 磁盘全量事件（readSessionFile 的返回）
+ * @param {number} restoreSeq 一次 revert/delete 落定的 system/message 事件的
+ *   seq（其 surfaceOp 为 replace、sourceEventSeqs 记录了被遮蔽节点）
+ */
+export function planRestore(events, restoreSeq) {
+  if (!Array.isArray(events)) throw new OpsError("restore: events must be an array", 500);
+  if (!Number.isSafeInteger(restoreSeq) || restoreSeq < 0) throw new OpsError("invalid seq", 400);
+  const ev = events.find((e) => e && e.seq === restoreSeq);
+  if (!ev) throw new OpsError(`restore: event seq ${restoreSeq} not found in log`, 404);
+  // 读取端拼写统一走 session-file 的 readReplaceOp（双拼写兼容的单点）。
+  const range = readReplaceOp(ev);
+  if (!range) {
+    throw new OpsError(`restore: seq ${restoreSeq} is not a revert/delete marker event (no well-formed replace surfaceOp)`, 409);
+  }
+  const { startSeq, endSeq } = range;
+  const replayable = [];
+  let skipped = 0;
+  for (const e of events) {
+    if (!e || typeof e.seq !== "number" || e.seq < startSeq || e.seq > endSeq) continue;
+    if (e.type === "user/message" || e.type === "assistant/message") {
+      const text = messageText(e);
+      if (!text.trim()) { skipped++; continue; }
+      replayable.push({
+        seq: e.seq,
+        type: e.type,
+        role: e.type === "user/message" ? "user" : "assistant",
+        text,
+      });
+    } else {
+      skipped++; // tool/call 等不可安全重放的事件：跳过并在结果里计数
+    }
+  }
+  if (replayable.length === 0) {
+    throw new OpsError(`restore: no replayable user/assistant messages in shadowed range ${startSeq}..${endSeq}`, 409);
+  }
+  return { restoreSeq, startSeq, endSeq, replayable, skipped };
+}
+
+/**
+ * applyRestore：把 planRestore 的重放计划落定到 live session。
+ * 引擎不支持取消遮蔽（SurfaceOp 无该变体），故实现为重放：
+ * 每条消息以原类型 append、文本加 [恢复] 前缀；先 append 一条 system 说明。
+ */
+export function applyRestore(session, plan, { flush } = {}) {
+  const eventSeqs = [];
+  const notice = `[消息恢复] 重放 seq ${plan.startSeq}..${plan.endSeq} 的 ${plan.replayable.length} 条消息` +
+    (plan.skipped > 0 ? `（另有 ${plan.skipped} 条不可重放事件已跳过）` : "") +
+    `；原区间仍处于遮蔽状态，恢复为重放而非解除遮蔽`;
+  const noticeEvent = session.append(
+    "system/message",
+    { message: { role: "system", content: [{ type: "text", text: notice }] } },
+    { surfaceOp: "append" },
+  );
+  if (noticeEvent && noticeEvent.seq != null) eventSeqs.push(noticeEvent.seq);
+  for (const item of plan.replayable) {
+    const event = session.append(
+      item.type,
+      { message: { role: item.role, content: [{ type: "text", text: `[恢复] ${item.text}` }] } },
+      { surfaceOp: "append" },
+    );
+    if (event && event.seq != null) eventSeqs.push(event.seq);
+  }
+  if (flush) {
+    try { flush(); } catch { /* flush 失败不回滚已接受的事件 */ }
+  }
+  return { restoredCount: plan.replayable.length, skipped: plan.skipped, eventSeqs };
+}
+
+/**
+ * exportMarkdown：把到 upToSeq（含）为止的事件流渲染为 Markdown。
+ * user/assistant/system 消息按角色小节展开，工具调用折叠为单行引用。
+ * @param {object} header 会话 header（readSessionFile）
+ * @param {Array} events 全量事件
+ * @param {number=} upToSeq 可选上界（含）；缺省导出全部
+ */
+export function exportMarkdown(header, events, upToSeq) {
+  if (upToSeq !== undefined && (!Number.isSafeInteger(upToSeq) || upToSeq < 0)) {
+    throw new OpsError("invalid seq", 400);
+  }
+  const sessionId = header && header.id ? header.id : "unknown";
+  const scoped = upToSeq === undefined ? events : events.filter((e) => e && typeof e.seq === "number" && e.seq <= upToSeq);
+  const lines = [];
+  lines.push(`# DSH 会话导出：${sessionId}`);
+  lines.push("");
+  lines.push(`- 会话 id：${sessionId}`);
+  if (header && header.parentSession) lines.push(`- 来源分支：${header.parentSession}`);
+  lines.push(`- 导出范围：${upToSeq === undefined ? "全部" : `seq ≤ ${upToSeq}`}`);
+  lines.push(`- 生成时间：${new Date().toISOString()}`);
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  for (const e of scoped) {
+    if (!e || typeof e.seq !== "number") continue;
+    if (e.type === "user/message" || e.type === "assistant/message" || e.type === "system/message") {
+      const role = (e.data && e.data.message && e.data.message.role) ||
+        (e.type === "user/message" ? "user" : e.type === "assistant/message" ? "assistant" : "system");
+      const text = messageText(e);
+      lines.push(`## [seq ${e.seq}] ${role}`);
+      lines.push("");
+      lines.push(text || "（无文本内容）");
+      lines.push("");
+    } else if (e.type === "tool/call") {
+      const d = e.data || {};
+      const name = d.name || (d.call && d.call.name) || "tool";
+      const argsHint = d.call && d.call.arguments !== undefined
+        ? JSON.stringify(d.call.arguments).slice(0, 80)
+        : "";
+      lines.push(`> [seq ${e.seq}] 🔧 工具调用：${name}${argsHint ? ` — ${argsHint}` : ""}`);
+      lines.push("");
+    }
+  }
+  return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// HTTP 信任围栏（评审 P0）：插件经 webServer.register 挂载的路由不经过宿主
+// connection RPC 面的 isTrustedApiRequest 围栏（dsh-src
+// packages/client/connection/src/api-request-trust.ts），必须自建。三层：
+//   1. Host 必须是回环地址 → 挡 DNS rebinding（伪造 Host 的攻击页直接 403）；
+//   2. sec-fetch-site: cross-site 拒绝 → 挡跨站浏览器请求；
+//   3. Origin 存在时必须与 Host 同源 → 挡其余跨站 POST/GET。
+// 非浏览器客户端（curl / Agent 工具 / 宿主自身）不带 sec-fetch-site 与
+// Origin，且 Host 均为回环 → 天然放行，无需 token。
+// ---------------------------------------------------------------------------
+
+function headerOf(headers, name) {
+  const value = headers && headers[name];
+  return typeof value === "string" ? value : undefined;
+}
+
+function parseAuthority(authority) {
+  try { return new URL(`http://${authority}`); } catch { return undefined; }
+}
+
+function isLoopbackHostname(hostname) {
+  if (hostname === "localhost" || hostname === "[::1]") return true;
+  const parts = hostname.split(".");
+  return parts.length === 4 && parts[0] === "127" && parts.every((p) => /^\d{1,3}$/.test(p) && Number(p) <= 255);
+}
+
+/** 与 slv-check 同款的信任判定（回环 Host + 非 cross-site + Origin 同源）。 */
+export function isTrustedApiRequest(req) {
+  const host = headerOf(req && req.headers, "host");
+  if (host === undefined) return false;
+  const hostUrl = parseAuthority(host);
+  if (hostUrl === undefined) return false;
+  if (!isLoopbackHostname(hostUrl.hostname)) return false;
+  if (headerOf(req.headers, "sec-fetch-site") === "cross-site") return false;
+  const origin = headerOf(req.headers, "origin");
+  if (origin === undefined) return true;
+  try { return new URL(origin).host === hostUrl.host; } catch { return false; }
+}
+
+/**
+ * 写操作 CSRF 防护：Content-Type 必须 application/json（允许 ;charset=… 后缀）。
+ * 为何不需要一次性 token：浏览器对**所有** POST（含 text/plain 绕预检的
+ * 那条路）都会附带 Origin 头，第 3 层 Origin 同源校验已覆盖跨站 POST；
+ * Content-Type 约束是纵深防御（阻止非 JSON 客户端误写），而自定义头
+ * （如 X-Requested-With）天然触发 CORS 预检，与 Origin 校验等价，故
+ * 引入 token 只增加握手复杂度而不增加安全性——围栏已足够（论证记录于此）。
+ */
+export function isJsonContentType(req) {
+  const ct = headerOf(req && req.headers, "content-type") || "";
+  return ct.split(";")[0].trim().toLowerCase() === "application/json";
+}

package/src/session-file.js

@@ -0,0 +1,230 @@
+/**
+ * dsh-message-ops — 会话文件机制（纯 Node，零 npm 依赖）。
+ *
+ * DSH 的 JSONL 持久化格式：一份会话日志 = 多个独立 zstd 帧的串联，
+ *   帧 0 = 恰好一行 session header JSON（以 \n 结尾，帧带 checksum）
+ *   之后每帧 = 一批以 \n 分隔的事件行（NDJSON）
+ * 回写 = 重排帧：header 帧 + 事件帧。node:zlib 自 Node 23.5 起暴露
+ * zstdCompressSync / zstdDecompressSync，零依赖即可压缩/解压，
+ * Windows / Termux / Linux 行为一致。旧格式 session.jsonl.zstd（单帧
+ * 整文件）读取走同一帧扫描路径，单帧等效于解压整份。
+ * @module dsh-message-ops/session-file
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { constants, zstdCompressSync, zstdDecompressSync } from "node:zlib";
+
+const ZSTD_MAGIC = 0xfd2fb528;
+
+/** 与 DSH 宿主一致：帧带 checksum（ZSTD_c_checksumFlag=1）。 */
+function compressFrame(input) {
+  return zstdCompressSync(Buffer.from(input, "utf8"), {
+    params: { [constants.ZSTD_c_checksumFlag]: 1 },
+  });
+}
+
+/**
+ * 扫描串联 zstd 流的完整帧边界（不解压块）。
+ * @returns {{frames: {start:number,end:number}[], tornStart?: number}}
+ */
+export function scanZstdFrames(buf) {
+  const frames = [];
+  let offset = 0;
+  while (offset < buf.length) {
+    const start = offset;
+    if (buf.length - offset < 4) return { frames, tornStart: start };
+    if (buf.readUInt32LE(offset) !== ZSTD_MAGIC) {
+      throw new Error(`corrupt zstd session log: invalid frame magic at byte ${offset}`);
+    }
+    let end = buf.length;
+    for (let p = offset + 4; p <= buf.length - 4; p++) {
+      if (buf.readUInt32LE(p) === ZSTD_MAGIC) { end = p; break; }
+    }
+    frames.push({ start, end });
+    offset = end;
+  }
+  return { frames };
+}
+
+/**
+ * 读取会话日志 → { header, events }。撕裂的最终帧按宿主同款
+ * 「完整前缀」语义忽略（完整帧全部恢复）。
+ */
+export function readSessionFile(file) {
+  const buf = fs.readFileSync(file);
+  const { frames } = scanZstdFrames(buf);
+  if (frames.length === 0) throw new Error("empty or header-less session log");
+  const headerText = zstdDecompressSync(buf.subarray(frames[0].start, frames[0].end)).toString("utf8");
+  const header = JSON.parse(headerText.trim());
+  if (header.type !== "session") throw new Error("first frame is not a session header");
+  const events = [];
+  for (const f of frames.slice(1)) {
+    const text = zstdDecompressSync(buf.subarray(f.start, f.end)).toString("utf8");
+    for (const line of text.split("\n")) {
+      const t = line.trim();
+      if (!t) continue;
+      try { events.push(JSON.parse(t)); } catch { /* torn record: skip */ }
+    }
+  }
+  return { header, events };
+}
+
+/** 物化整份日志：header 帧（恰一行）+ 单一事件帧（全部事件行）。 */
+export function encodeSessionFile(header, events) {
+  const headerText = JSON.stringify(header) + "\n";
+  const bodyText = events.map((e) => JSON.stringify(e)).join("\n") + "\n";
+  return Buffer.concat([compressFrame(headerText), compressFrame(bodyText)]);
+}
+
+/** 会话根目录（尊重 DSH_HOME；Windows/Termux 通吃）。 */
+export function sessionsRoot() {
+  const home = process.env.DSH_HOME || path.join(os.homedir(), ".dsh");
+  return path.join(home, "sessions");
+}
+
+const SESSION_ID_RE = /^(session-)?[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+export function isSessionId(v) {
+  return typeof v === "string" && SESSION_ID_RE.test(v);
+}
+
+/** 会话 id 的两种拼写（带/不带 session- 前缀）。 */
+export function sessionIdVariants(sessionId) {
+  const variants = new Set([sessionId]);
+  if (sessionId.startsWith("session-")) variants.add(sessionId.slice("session-".length));
+  else variants.add(`session-${sessionId}`);
+  return [...variants];
+}
+
+/**
+ * 在 sessions 根下定位会话目录：扫每个 project-slug 目录找 <slug>/<id>/，
+ * 避免在插件里重推 workspace 路径编码。
+ * @returns {{dir: string, logPath: string}[]}
+ */
+export function findSessionDirs(sessionId) {
+  const root = sessionsRoot();
+  let slugs = [];
+  try { slugs = fs.readdirSync(root, { withFileTypes: true }); } catch { return []; }
+  const variants = sessionIdVariants(sessionId);
+  const found = [];
+  for (const slug of slugs) {
+    if (!slug.isDirectory()) continue;
+    for (const variant of variants) {
+      const dir = path.join(root, slug.name, variant);
+      try {
+        if (!fs.statSync(dir).isDirectory()) continue;
+      } catch { continue; }
+      const logPath = path.join(dir, "session.v3.jsonl.zstd");
+      try { fs.statSync(logPath); } catch { continue; }
+      if (!found.some((f) => f.dir === dir)) found.push({ dir, logPath });
+    }
+  }
+  return found;
+}
+
+/** 新建会话 id（与宿主同款 session-<uuid> 拼写）。 */
+export function newSessionId() {
+  return `session-${crypto.randomUUID()}`;
+}
+
+/** 从事件流提取消息级列表（user/assistant/system message + tool/call 摘要）。 */
+export function listMessages(events) {
+  const messages = [];
+  for (const e of events) {
+    if (!e || typeof e.seq !== "number") continue;
+    if (e.type === "user/message" || e.type === "assistant/message" || e.type === "system/message") {
+      const msg = e.data && e.data.message;
+      const content = msg && Array.isArray(msg.content) ? msg.content : (e.data && e.data.content);
+      let text = "";
+      if (Array.isArray(content)) {
+        for (const c of content) {
+          if (c && c.type === "text" && typeof c.text === "string" && c.text.trim()) {
+            text = c.text; break;
+          }
+        }
+      }
+      messages.push({
+        seq: e.seq,
+        type: e.type,
+        role: (msg && msg.role) || (e.type === "user/message" ? "user" : e.type === "assistant/message" ? "assistant" : "system"),
+        snippet: text.replace(/\s+/g, " ").trim().slice(0, 160),
+        time: e.time ?? null,
+        turn: (e.data && e.data.turn) ?? null,
+      });
+    } else if (e.type === "tool/call") {
+      const d = e.data || {};
+      const name = d.name || (d.call && d.call.name) || "tool";
+      messages.push({
+        seq: e.seq, type: "tool/call", role: "tool", snippet: `[tool] ${name}`,
+        time: e.time ?? null, turn: d.turn ?? null,
+      });
+    }
+  }
+  return messages;
+}
+
+/**
+ * 读取一条 replace surfaceOp 的区间（共用单点，读写端拼写必须一致）。
+ * 兼容两种拼写：当前运行时 {op:'replace', startSeq, endSeq} 与
+ * dsh-src 较新副本的 {op:'replace', start, end}；其余视为非法返回 null。
+ */
+export function readReplaceOp(e) {
+  const op = e && e.surfaceOp;
+  if (!op || typeof op !== "object" || op.op !== "replace") return null;
+  const startSeq = Number.isSafeInteger(op.startSeq) ? op.startSeq : op.start;
+  const endSeq = Number.isSafeInteger(op.endSeq) ? op.endSeq : op.end;
+  if (!Number.isSafeInteger(startSeq) || !Number.isSafeInteger(endSeq)) return null;
+  return { startSeq, endSeq };
+}
+
+/**
+ * 从磁盘事件流推导「被遮蔽」seq 集合：后来发生的 surface replace 事件
+ * 遮蔽 [startSeq..endSeq]（append-only：遮蔽仍在日志但不再可见）。
+ */
+export function computeShadowed(events) {
+  const shadowed = new Set();
+  for (const e of events) {
+    const range = readReplaceOp(e);
+    if (!range) continue;
+    for (let s = range.startSeq; s <= range.endSeq; s++) shadowed.add(s);
+  }
+  return shadowed;
+}
+
+const yieldToLoop = () => new Promise((resolve) => setImmediate(resolve));
+
+/**
+ * readSessionFile 的异步变体：逐帧解压循环每 framesPerYield 帧向事件循环
+ * 让出一次（setImmediate），避免大日志把 GUI 的 tick 卡死数秒。
+ * 文件读取与帧边界扫描仍是同步单次系统调用/字节扫描（成本低）；真正昂贵
+ * 的 zstdDecompressSync + JSON.parse 在让出点之间执行。
+ * @returns {{header, events, frameCount, partial}}
+ *   partial：帧数超过 frameBudget（默认 500）时为 true，调用方应向
+ *   用户提示「仅完整读取，无截断，但本次请求耗时可能较长」。
+ */
+export async function readSessionFileAsync(file, { framesPerYield = 8, frameBudget = 500 } = {}) {
+  const buf = fs.readFileSync(file);
+  const { frames } = scanZstdFrames(buf);
+  if (frames.length === 0) throw new Error("empty or header-less session log");
+  const headerText = zstdDecompressSync(buf.subarray(frames[0].start, frames[0].end)).toString("utf8");
+  const header = JSON.parse(headerText.trim());
+  if (header.type !== "session") throw new Error("first frame is not a session header");
+  const events = [];
+  const bodyFrames = frames.slice(1);
+  let framesSinceYield = 0;
+  for (const f of bodyFrames) {
+    const text = zstdDecompressSync(buf.subarray(f.start, f.end)).toString("utf8");
+    for (const line of text.split("\n")) {
+      const t = line.trim();
+      if (!t) continue;
+      try { events.push(JSON.parse(t)); } catch { /* torn record: skip */ }
+    }
+    if (++framesSinceYield >= framesPerYield) {
+      framesSinceYield = 0;
+      await yieldToLoop();
+    }
+  }
+  return { header, events, frameCount: bodyFrames.length, partial: bodyFrames.length > frameBudget };
+}