@xrn1997/dsh-session-delete 0.0.1 → 0.1.0

package/lib/index.d.ts

@@ -43,7 +43,7 @@ export declare const name = "@xrn1997/dsh-session-delete";
  *   它取不到时 `titleOf` 返回空串，正是契约允许的降级。
  *
  * `webServer` 是**浏览器半取数通道的承载者**（那条薄线）：插件用它注册 `/dsh-session-delete-api`
- * 前缀路由，浏览器半同源 fetch 那四个端点。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
+ * 前缀路由，浏览器半同源 fetch 那五个端点。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
  * `super(ctx, "webServer")`），服务名与 `register({kind:'prefix', path, handler})` 的形状按
  * `dsh-host-webserver/lib/index.js` 与 `README.md` 原文读实，不是猜的。
  */

package/lib/index.js

@@ -1,10 +1,11 @@
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
+import zlib from "node:zlib";
 import { existsSync } from "node:fs";
-import { mkdir, readdir, rename, rm, stat } from "node:fs/promises";
+import { mkdir, readFile, readdir, rename, rm, stat } from "node:fs/promises";
 //#region src/shared/wire.ts
 /**
-* 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、四个端点段、请求字段名**——
+* 跨半 wire 契约：`/dsh-session-delete-api` 的**前缀、五个端点段、请求字段名**——
 * Node 半（`src/api/dispatch.ts` 注册并分发）与浏览器半（`src/client/remote.ts` 同源 fetch）
 * 之间唯一的那份真相。两侧都 import 它，不各写一份字面量。
 *
@@ -27,12 +28,14 @@ import { mkdir, readdir, rename, rm, stat } from "node:fs/promises";
 * 撞了就是整棵插件树 boot 失败——所以这条路径是与生态的硬边界，不是显示好不好看的问题。
 */
 const SESSION_DELETE_API_PREFIX = "/dsh-session-delete-api";
-/** 四个端点的段名（相对前缀；`GET list` 读、其余三个 `POST` 写）。 */
+/** 五个端点的段名（相对前缀；`GET list` 读清单，其余四个 `POST` 按 id 取数或写）。 */
 const ROUTES = {
 	list: "/list",
 	delete: "/delete",
 	restore: "/restore",
-	purge: "/purge"
+	purge: "/purge",
+	/** 单条详情（读回收站目录里那条会话自己的日志）。用 POST 表达一个读：见设计稿 2026-10-15 §3。 */
+	detail: "/detail"
 };
 /** 请求体字段名：浏览器半发、Node 半读，同名同义（`purge` 的 `entryId` 缺席 = 清空）。 */
 const PARAMS = {
@@ -156,6 +159,299 @@ function trashDirOf(entryId, home) {
 	return `${home}/session-trash/${entryId}`;
 }
 //#endregion
+//#region src/log/zstd-frames.ts
+const MAGIC = [
+	40,
+	181,
+	47,
+	253
+];
+/** magic(4) + Frame_Header_Descriptor(1) 之后第一个字节的偏移。 */
+const AFTER_DESCRIPTOR = 5;
+const BLOCK_HEADER_BYTES = 3;
+const BLOCK_LAST = 1;
+const BLOCK_TYPE_SHIFT = 1;
+const BLOCK_SIZE_SHIFT = 3;
+const BLOCK_SIZE_MASK = 2097151;
+const BLOCK_RAW = 0;
+const BLOCK_RLE = 1;
+const BLOCK_COMRESSED = 2;
+/** 规范（RFC 8878 表 4）里 3 是 **Reserved**，不是"未压缩块"：见到就抛，别照 Raw 吞块体。 */
+const BLOCK_RESERVED = 3;
+/** descriptor 各字段的取值 → 字段字节数（zstd 帧头的两张尺寸表）。 */
+const DID_SIZES = [
+	0,
+	1,
+	2,
+	4
+];
+const FCS_SIZES_SINGLE = [
+	1,
+	2,
+	4,
+	8
+];
+const FCS_SIZES_MULTI = [
+	0,
+	2,
+	4,
+	8
+];
+/** 实测的帧尾长度（校验和位置；bit5 没置位也照样带，见文件头注）。 */
+const FRAME_TAIL_BYTES = 4;
+function isMagicAt(raw, at) {
+	return MAGIC.every((byte, i) => raw[at + i] === byte);
+}
+function readUint24LE(raw, at) {
+	return raw[at] | raw[at + 1] << 8 | raw[at + 2] << 16;
+}
+/** 块体之后有没有那 4 字节尾巴：只有"跳过它之后仍是帧头或到 EOF"才认。 */
+function withFrameTail(raw, at) {
+	const afterTail = at + FRAME_TAIL_BYTES;
+	if (afterTail <= raw.length && (afterTail === raw.length || isMagicAt(raw, afterTail))) return afterTail;
+	return at;
+}
+/**
+* 把 `raw` 切成帧区间。
+* @throws 起始处不是 magic、或某帧算到的末位既不是下一帧帧头也不是 EOF——**一律抛**，
+*   绝不"尽力往下解"：切错帧的后果是把半截压缩体当解压输入，那时解出来的东西不可信。
+*/
+function frameRanges(raw) {
+	const ranges = [];
+	let at = 0;
+	while (at < raw.length) {
+		if (!isMagicAt(raw, at)) throw new Error(`zstd 帧头缺席：偏移 ${at} 处不是 magic（前面第 ${ranges.length} 帧的边界算歪了？）`);
+		const descriptor = raw[at + 4];
+		if (descriptor === void 0) throw new Error(`zstd 帧头不完整：偏移 ${at} 之后不足 ${AFTER_DESCRIPTOR} 字节`);
+		const fcsFlag = descriptor & 3;
+		const singleSegment = descriptor >> 2 & 1;
+		const didFlag = descriptor >> 6 & 3;
+		let cursor = at + AFTER_DESCRIPTOR;
+		if (!singleSegment) cursor += 1;
+		cursor += DID_SIZES[didFlag];
+		cursor += (singleSegment ? FCS_SIZES_SINGLE : FCS_SIZES_MULTI)[fcsFlag];
+		for (;;) {
+			const blockHeader = readUint24LE(raw, cursor);
+			cursor += BLOCK_HEADER_BYTES;
+			if (cursor > raw.length) throw new Error(`zstd 块头越界：帧起于 ${at}，读到偏移 ${cursor}（文件长 ${raw.length}）`);
+			const blockType = blockHeader >> BLOCK_TYPE_SHIFT & 3;
+			const blockSize = blockHeader >> BLOCK_SIZE_SHIFT & BLOCK_SIZE_MASK;
+			if (blockType === BLOCK_RESERVED) throw new Error(`zstd 保留块类型：帧起于 ${at}，偏移 ${cursor - BLOCK_HEADER_BYTES} 的块头 type=3（规范 Reserved，对面解不开）`);
+			if (blockType === BLOCK_RAW || blockType === BLOCK_COMRESSED) cursor += blockSize;
+			else if (blockType === BLOCK_RLE) cursor += 1;
+			if (blockHeader & BLOCK_LAST) break;
+		}
+		cursor = withFrameTail(raw, cursor);
+		if (cursor !== raw.length && !isMagicAt(raw, cursor)) throw new Error(`zstd 帧边界算歪了：帧起于 ${at}，算到 ${cursor}，那里既不是下一帧帧头也不是 EOF`);
+		ranges.push({
+			start: at,
+			end: cursor
+		});
+		at = cursor;
+	}
+	return ranges;
+}
+//#endregion
+//#region src/log/session-log.ts
+/**
+* 会话日志（`session.vN.jsonl.zstd`）的**逐帧读法**：帧边界交给 `zstd-frames.ts`，这一层只做
+* 「帧 → 明文 → 一行一条 JSON」的解码，并把每条记录原样交给回调。
+*
+* **策略不在这里**（哪些 `type` 算正文、截断到多少字、算不算失败）——那是 `src/trash/detail.ts` 的事。
+* 这一层只懂编解码，所以它能被单独验穿。
+*
+* 两条实测决定的口径：
+* ① **必须逐帧**：Node 的 `zstdDecompressSync` 与 `createZstdDecompress()` 都只给第一帧（见
+*    `zstd-frames.ts` 头注）；明文留在手里会一次装下整条日志（本机 125 条合计 280.7 MB），
+*    所以**一帧一帧解、解完就撒手**，内存口径是"最大那一帧的明文"（实测 8.99 MB）而不是整条。
+* ② **一行的余量跨帧带走**（2026-10-16 改，原来靠"跳过解不开的行"兜）：写作侧是一条条 append，
+*    实测本机 686 个 `.jsonl.zstd` / 92 421 帧**没有一帧切在行中间**（连最后一帧都整行收尾），
+*    所以旧口径当时并不丢东西；但"逐帧 `split('\n')`"一旦遇上切行就是**静默少一条记录**（半个头
+*    加半个身，两半都解不开 JSON），而少掉的那条正是页面上要跟账的正文。带上余量之后这条不变量
+*    不必再成立，顺带把**跨帧的多字节字符**也解对了——拼接在字节层做，`toString('utf8')` 只看整行。
+*    真被切断的尾巴（写一半）仍然**跳过并计数**：绝不因为一行就抛整个读数，前面几百条是真的。
+*/
+const NEWLINE = 10;
+function walkSessionLog(raw, onRecord) {
+	const stats = {
+		frames: 0,
+		records: 0,
+		unparsedLines: 0,
+		truncatedTailBytes: 0
+	};
+	const feed = (line) => {
+		if (line === "") return;
+		let parsed;
+		try {
+			parsed = JSON.parse(line);
+		} catch {
+			stats.unparsedLines += 1;
+			return;
+		}
+		stats.records += 1;
+		onRecord(parsed !== null && typeof parsed === "object" ? parsed : {});
+	};
+	/** 上一帧没闭合的那一行。**存字节不存字符**：切在多字节字符中间的帧要拼回完整才解得对。 */
+	let carry = Buffer.alloc(0);
+	for (const { start, end } of frameRanges(raw)) {
+		stats.frames += 1;
+		let plain;
+		try {
+			plain = zlib.zstdDecompressSync(raw.subarray(start, end));
+		} catch (error) {
+			throw new Error(`回收站日志第 ${stats.frames} 帧解压失败：${String(error)}`);
+		}
+		const merged = carry.length === 0 ? plain : Buffer.concat([carry, plain]);
+		const cut = merged.lastIndexOf(NEWLINE);
+		if (cut === -1) {
+			carry = merged;
+			continue;
+		}
+		carry = merged.subarray(cut + 1);
+		for (const line of merged.subarray(0, cut).toString("utf8").split("\n")) feed(line);
+	}
+	stats.truncatedTailBytes = carry.length;
+	if (carry.length > 0) feed(carry.toString("utf8"));
+	return stats;
+}
+//#endregion
+//#region src/trash/detail.ts
+/**
+* 回收站**单条详情**：从回收站目录里那条会话自己的日志读出元信息与正文（设计稿 2026-10-15 §3）。
+*
+* 三层里的策略层——编解码在 `src/log/*`，这里只回答"给谁看、给多少、算不算失败"。
+*
+* 三条硬口径，都不是口味：
+* ① **寻址只认清册**：`entryId` 先在清单里查，目录一律由 `trashDirOf(record.id, home)` 推 ⇒ 外部
+*    输入进不了文件系统寻址（不给"传个路径就读任意目录"留缝）。
+* ② **正文只认 `source.kind === "user"`**：`user/message` 里绝大多数是宿主注入的上下文
+*    （本机实测一条会话：真实提问 21 条、注入 241 条），不过滤就被淹掉；注入条数照样上线
+*    （`injectedCount`），让"为什么少了这么多条"能与页面上的数字对账。
+* ③ **两个闸是载荷闸，不是读盘闸**：每条 3 000 字符、累计 50 万字符（CJK 最坏 ≈ 1.5 MB UTF-8）。
+*    按 §1 的读数本机一条都触发不了（最大那条正文 806 KB ≈ 27 万字符、442 条消息）⇒ 它们是防异常
+*    膨胀的；**不设"文件太大就拒绝"**，那种阈值只会把真读得出来的正文挡在外面。
+*
+* 计数与正文**同源同判据**：`userMessageCount` 就是进了正文的提问条数、`assistantMessageCount` 就是
+* 有文字的回复条数——不是一套判据算两遍，否则页面上会出现"计数 421、正文 200"这种对不上账的话。
+*/
+/** 每条文字的上限（字符）。超出即截断并置 `truncated`。 */
+const PER_MESSAGE_CHAR_CAP = 3e3;
+/** 一次回信的正文总量上限（字符）。 */
+const TOTAL_CHAR_CAP = 5e5;
+const LOG_SUFFIX = ".jsonl.zstd";
+const DEFAULT_LIMITS = {
+	perMessageChars: PER_MESSAGE_CHAR_CAP,
+	totalChars: TOTAL_CHAR_CAP
+};
+/** 一条记录里那些 `content[]` 段的文字拼起来（`\n` 分隔；非 text 段一律不参与）。 */
+function textOf(content) {
+	if (!Array.isArray(content)) return "";
+	return content.filter((part) => part?.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n").trim();
+}
+function readTrashDetail(deps, limits = DEFAULT_LIMITS) {
+	return async function readTrashDetail(entryId) {
+		const record = (await deps.manifest.list()).find((e) => e.id === entryId);
+		if (record === void 0) throw verbError("trash-empty", `回收站里没有这一条：${entryId}`);
+		const dir = trashDirOf(record.id, deps.home);
+		if (!await deps.fs.exists(dir)) throw verbError("io", `回收站目录不在：${dir}`);
+		const names = (await deps.fs.listFiles(dir)).sort();
+		const logName = names.find((n) => n.endsWith(LOG_SUFFIX));
+		if (logName === void 0) throw verbError("io", `回收站目录里没有会话日志：${dir}（里面有：${names.join(", ") || "空目录"}）`);
+		let raw;
+		try {
+			raw = await deps.fs.readFile(`${dir}/${logName}`);
+		} catch (error) {
+			throw verbError("io", `读会话日志失败：${String(error)}`, error);
+		}
+		const detail = {
+			entryId: record.id,
+			cwd: "",
+			createdAt: 0,
+			lastActivity: 0,
+			logTitle: "",
+			models: [],
+			turnCount: 0,
+			userMessageCount: 0,
+			assistantMessageCount: 0,
+			toolCallCount: 0,
+			injectedCount: 0,
+			messages: [],
+			omittedByPayloadCap: 0
+		};
+		const models = /* @__PURE__ */ new Set();
+		let usedChars = 0;
+		let capped = false;
+		/** 收进正文，顺带管两个闸：截到单条上限，累计到总量就停。 */
+		function push(role, time, text) {
+			if (capped) {
+				detail.omittedByPayloadCap += 1;
+				return;
+			}
+			const truncated = text.length > limits.perMessageChars;
+			const kept = truncated ? text.slice(0, limits.perMessageChars) : text;
+			if (usedChars + kept.length > limits.totalChars) {
+				capped = true;
+				detail.omittedByPayloadCap += 1;
+				return;
+			}
+			usedChars += kept.length;
+			detail.messages.push({
+				role,
+				time,
+				text: kept,
+				truncated
+			});
+		}
+		try {
+			walkSessionLog(raw, (r) => {
+				if (typeof r.time === "number" && r.time > detail.lastActivity) detail.lastActivity = r.time;
+				const data = r.data ?? {};
+				switch (r.type) {
+					case "session":
+						if (typeof r.cwd === "string") detail.cwd = r.cwd;
+						if (typeof r.createdAt === "number") detail.createdAt = r.createdAt;
+						return;
+					case "session/title":
+						if (typeof data.title === "string") detail.logTitle = data.title;
+						return;
+					case "turn/start":
+						detail.turnCount += 1;
+						return;
+					case "tool/call":
+						detail.toolCallCount += 1;
+						return;
+					case "user/message": {
+						if ((data.source ?? {}).kind !== "user") {
+							detail.injectedCount += 1;
+							return;
+						}
+						const text = textOf(data.content);
+						if (text === "") return;
+						detail.userMessageCount += 1;
+						push("user", r.time ?? 0, text);
+						return;
+					}
+					case "assistant/message": {
+						const message = data.message ?? {};
+						const source = message.source ?? {};
+						if (typeof source.model === "string") models.add(source.model);
+						const text = textOf(message.content);
+						if (text === "") return;
+						detail.assistantMessageCount += 1;
+						push("assistant", r.time ?? 0, text);
+						return;
+					}
+					default: return;
+				}
+			});
+		} catch (error) {
+			throw verbError("io", error instanceof Error ? `读回收站日志失败：${error.message}` : `读回收站日志失败：${String(error)}`, error);
+		}
+		detail.models = [...models];
+		return detail;
+	};
+}
+//#endregion
 //#region src/verbs/delete-session.ts
 function deleteSession(deps) {
 	return async function deleteSession(sessionId) {
@@ -423,6 +719,10 @@ async function dispatch(method, rest, req, deps) {
 		requireMethod(method, "POST", ROUTES.purge);
 		return await purgeTrash(deps)(optionalString(await readJsonBody(req), PARAMS.entryId));
 	}
+	if (rest === ROUTES.detail) {
+		requireMethod(method, "POST", ROUTES.detail);
+		return await readTrashDetail(deps)(requireString(await readJsonBody(req), PARAMS.entryId));
+	}
 	throw new Error(`未知路由：${method} ${rest === "" ? SESSION_DELETE_API_PREFIX : rest}`);
 }
 /** 宿主 `webServer.register({kind:'prefix', path: SESSION_DELETE_API_PREFIX, handler})` 的那个 handler。 */
@@ -470,7 +770,13 @@ function createFsPort() {
 				force: true
 			});
 		},
-		sizeOfDir: (p) => sizeOfDir(p)
+		sizeOfDir: (p) => sizeOfDir(p),
+		async listFiles(p) {
+			return readdir(p);
+		},
+		async readFile(p) {
+			return readFile(p);
+		}
 	};
 }
 //#endregion
@@ -732,7 +1038,7 @@ const name = "@xrn1997/dsh-session-delete";
 *   它取不到时 `titleOf` 返回空串，正是契约允许的降级。
 *
 * `webServer` 是**浏览器半取数通道的承载者**（那条薄线）：插件用它注册 `/dsh-session-delete-api`
-* 前缀路由，浏览器半同源 fetch 那四个端点。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
+* 前缀路由，浏览器半同源 fetch 那五个端点。它是宿主 web 组成里的硬依赖（`dsh-host-webserver` 的
 * `super(ctx, "webServer")`），服务名与 `register({kind:'prefix', path, handler})` 的形状按
 * `dsh-host-webserver/lib/index.js` 与 `README.md` 原文读实，不是猜的。
 */

package/locale/en.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "Session Delete",
-    "description": "Delete sessions: delete moves them to a recoverable trash, with an explicit permanent delete."
-  }
-}
+{
+  "meta": {
+    "title": "Session Delete",
+    "description": "Delete sessions: delete moves them to a recoverable trash, with an explicit permanent delete."
+  }
+}

package/locale/zh.json

@@ -1,6 +1,6 @@
-{
-  "meta": {
-    "title": "会话删除",
-    "description": "删除会话：删除 = 移入回收站（可恢复），另设显式的彻底删除。"
-  }
-}
+{
+  "meta": {
+    "title": "会话删除",
+    "description": "删除会话：删除 = 移入回收站（可恢复），另设显式的彻底删除。"
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xrn1997/dsh-session-delete",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "在 DeepSeek Harness 里删除会话：删除=移入回收站（可恢复），另设显式彻底删除",
   "type": "module",
   "main": "lib/index.js",
@@ -87,5 +87,9 @@
     "delete"
   ],
   "author": "xrn1997",
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "dependencies": {
+    "react-markdown": "^10.1.0",
+    "remark-gfm": "^4.0.1"
+  }
 }