@rexvane/piweb 0.3.11 → 0.3.13

package/src/lib/session-import/codex.ts

@@ -0,0 +1,206 @@
+/**
+ * Codex CLI（~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl）
+ *
+ * 每行统一 `{timestamp, type, payload}`；payload.type = session_meta / response_item / event_msg …
+ * response_item.payload 里才有对话：message / reasoning / function_call / custom_tool_call(+output)。
+ * 注意首行可达十几 KB（含 base_instructions），必须读到换行再 parse。
+ */
+import path from "node:path";
+import fs from "node:fs/promises";
+import { eachJsonLine, listFiles, readHead, reachedLimit, sortByRecency } from "./files";
+import { codexRoot } from "./paths";
+import type { ExternalSessionSummary, ImportedBlock, ImportedEntry, ImportedSession, ImportSourceModule, ScanOptions } from "./types";
+import { cleanTitle, compactBlocks, outputBlocks, parseArguments, textBlock, toEpochMs } from "./types";
+
+const ROOT = codexRoot;
+
+/**
+ * 合成输入前缀（与参考实现同口径：精确前缀，不用 "#" 通配，避免误杀用户粘贴的 markdown）
+ */
+const SYNTHETIC_PREFIXES = [
+	"<",
+	"# AGENTS.md",
+	"# Context from my IDE setup",
+	"# In app browser:",
+	"# Browser comments:",
+	"# Files mentioned by the user:",
+	"# Diff comments:",
+	"# Selected text:",
+	"# Review findings:",
+	"You are Codex",
+];
+
+const isSynthetic = (text: string) => SYNTHETIC_PREFIXES.some((prefix) => text.startsWith(prefix));
+
+interface Meta {
+	cwd?: string;
+	createdAt?: number;
+	model?: string;
+	provider?: string;
+}
+
+function metaFrom(records: Record<string, unknown>[]): Meta {
+	const meta: Meta = {};
+	for (const record of records) {
+		if (record.type !== "session_meta") continue;
+		const payload = record.payload as Record<string, unknown> | undefined;
+		if (!payload) continue;
+		if (typeof payload.cwd === "string") meta.cwd = payload.cwd;
+		meta.createdAt = toEpochMs(payload.timestamp) ?? toEpochMs(record.timestamp);
+		if (typeof payload.model_provider === "string") meta.provider = payload.model_provider;
+		if (typeof payload.model === "string") meta.model = payload.model;
+	}
+	// 模型有时只在 turn_context 里出现
+	for (const record of records) {
+		if (record.type !== "turn_context") continue;
+		const payload = record.payload as Record<string, unknown> | undefined;
+		if (typeof payload?.model === "string") meta.model = payload.model;
+	}
+	return meta;
+}
+
+function messageBlocks(payload: Record<string, unknown>): ImportedBlock[] {
+	const content = payload.content;
+	if (!Array.isArray(content)) return compactBlocks([textBlock(typeof content === "string" ? content : undefined)]);
+	return compactBlocks(content.flatMap((raw): Array<ImportedBlock | null> => {
+		const block = raw as Record<string, unknown>;
+		if (typeof block?.text === "string") return [textBlock(block.text)];
+		return [];
+	}));
+}
+
+function reasoningText(payload: Record<string, unknown>): ImportedBlock | null {
+	const summary = payload.summary;
+	if (typeof summary === "string") return summary.trim() ? { type: "thinking", thinking: summary } : null;
+	if (Array.isArray(summary)) {
+		const text = summary.map((item) => (item as { text?: unknown })?.text).filter((value): value is string => typeof value === "string").join("\n");
+		return text.trim() ? { type: "thinking", thinking: text } : null;
+	}
+	return null;
+}
+
+/** 标题：Codex 不写标题字段，用首条真人用户消息（rollout 头几十行里就有） */
+function titleFrom(records: Record<string, unknown>[]): string | undefined {
+	for (const record of records) {
+		if (record.type !== "response_item") continue;
+		const payload = record.payload as Record<string, unknown> | undefined;
+		if (payload?.type !== "message" || payload.role !== "user") continue;
+		const blocks = messageBlocks(payload);
+		const plain = blocks.filter((block) => block.type === "text").map((block) => block.text).join("\n").replace(/\s+/g, " ").trim();
+		if (plain && !isSynthetic(plain)) return plain;
+	}
+	return undefined;
+}
+
+export const codexSource: ImportSourceModule = {
+	id: "codex",
+
+	async scan(options?: ScanOptions): Promise<ExternalSessionSummary[]> {
+		const limit = options?.limit ?? 0;
+		const candidates = await sortByRecency(await listFiles(ROOT(), { match: (name) => name.startsWith("rollout-") && name.endsWith(".jsonl") }));
+		const out: ExternalSessionSummary[] = [];
+		for (const { file, mtime } of candidates) {
+			if (reachedLimit(out.length, limit)) break; // 只读最近的若干条
+			let head: string;
+			try {
+				head = await readHead(file);
+			} catch {
+				continue;
+			}
+			const records = [...eachJsonLine(head)].slice(0, 300);
+			const meta = metaFrom(records);
+			const hasMessage = records.some((record) => record.type === "response_item");
+			if (!hasMessage) continue;
+			out.push({
+				source: "codex",
+				externalId: path.basename(file, ".jsonl"),
+				title: cleanTitle(titleFrom(records)),
+				projectPath: meta.cwd,
+				model: meta.model,
+				provider: meta.provider,
+				createdAt: meta.createdAt ?? mtime,
+				updatedAt: mtime,
+				location: file,
+			});
+		}
+		return out;
+	},
+
+	async read(summary: ExternalSessionSummary): Promise<ImportedSession | null> {
+		let text: string;
+		try {
+			text = await fs.readFile(summary.location, "utf8");
+		} catch {
+			return null;
+		}
+		const entries: ImportedEntry[] = [];
+		const skipped: string[] = [];
+		let synthetic = 0;
+		let reasoningSkipped = 0;
+		let meta: Meta = { cwd: summary.projectPath, createdAt: summary.createdAt, model: summary.model, provider: summary.provider };
+
+		for (const record of eachJsonLine(text)) {
+			if (record.type === "session_meta") {
+				meta = { ...meta, ...metaFrom([record]) };
+				continue;
+			}
+			if (record.type !== "response_item") continue;
+			const payload = record.payload as Record<string, unknown> | undefined;
+			if (!payload) continue;
+			const timestamp = toEpochMs(record.timestamp) ?? toEpochMs(payload.timestamp) ?? meta.createdAt ?? Date.now();
+
+			switch (payload.type) {
+				case "message": {
+					const role = payload.role;
+					if (role === "developer") continue; // 系统提示，不进对话
+					const blocks = messageBlocks(payload);
+					const plain = blocks.filter((block) => block.type === "text").map((block) => block.text).join("\n").trim();
+					if (role === "user") {
+						if (!plain || isSynthetic(plain)) {
+							synthetic += 1;
+							continue;
+						}
+						entries.push({ type: "message", message: { role: "user", content: blocks, timestamp } });
+					} else if (role === "assistant") {
+						if (!blocks.length) continue;
+						entries.push({ type: "message", message: { role: "assistant", content: blocks, timestamp, ...(meta.model ? { model: meta.model } : {}) } });
+					}
+					continue;
+				}
+				case "reasoning": {
+					// 有摘要就保留成 thinking；只有加密内容时跳过
+					const thinking = reasoningText(payload);
+					if (!thinking) {
+						reasoningSkipped += 1;
+						continue;
+					}
+					entries.push({ type: "message", message: { role: "assistant", content: [thinking], timestamp, ...(meta.model ? { model: meta.model } : {}) } });
+					continue;
+				}
+				case "function_call":
+				case "custom_tool_call": {
+					const callId = typeof payload.call_id === "string" ? payload.call_id : "";
+					const name = typeof payload.name === "string" ? payload.name : "";
+					if (!callId || !name) continue;
+					const args = parseArguments(payload.arguments ?? payload.input ?? {});
+					entries.push({ type: "message", message: { role: "assistant", content: [{ type: "toolCall", id: callId, name, arguments: args }], timestamp, stopReason: "toolUse", ...(meta.model ? { model: meta.model } : {}) } });
+					continue;
+				}
+				case "function_call_output":
+				case "custom_tool_call_output": {
+					const callId = typeof payload.call_id === "string" ? payload.call_id : "";
+					if (!callId) continue;
+					entries.push({ type: "message", message: { role: "toolResult", toolCallId: callId, content: outputBlocks(payload.output ?? payload.content), timestamp } });
+					continue;
+				}
+				default:
+					continue;
+			}
+		}
+
+		if (synthetic) skipped.push(`跳过 ${synthetic} 条合成输入`);
+		if (reasoningSkipped) skipped.push(`跳过 ${reasoningSkipped} 条仅含加密内容的推理记录`);
+		if (!entries.some((entry) => entry.type === "message")) return null;
+		return { summary: { ...summary, ...meta, projectPath: meta.cwd, model: meta.model, provider: meta.provider }, entries, skipped };
+	},
+};

package/src/lib/session-import/dsh-zstd.ts

@@ -0,0 +1,69 @@
+/**
+ * dsh 的会话是 **多帧拼接的 zstd**（`session.jsonl.zstd`）：`zstdDecompressSync` 一次只解出第一帧，
+ * 必须按 zstd magic（28 B5 2F FD）切帧后逐帧解压再拼起来，否则只能拿到第一行。
+ */
+import fs from "node:fs/promises";
+import { zstdDecompressSync } from "node:zlib";
+
+const MAGIC = Buffer.from([0x28, 0xb5, 0x2f, 0xfd]);
+
+/** 解压多帧 zstd；帧边界只是"看起来像 magic"的位置，解压失败就把这片并入下一帧 */
+export function decodeZstdFrames(raw: Buffer): Buffer {
+	if (raw.length < MAGIC.length || !raw.subarray(0, MAGIC.length).equals(MAGIC)) {
+		// 不是多帧流（可能单帧或未压缩）：交给单帧解压，失败则原样当作文本
+		try {
+			return zstdDecompressSync(raw);
+		} catch {
+			return raw;
+		}
+	}
+	const cuts: number[] = [];
+	for (let i = 0; (i = raw.indexOf(MAGIC, i)) !== -1; i += MAGIC.length) cuts.push(i);
+	cuts.push(raw.length);
+	const parts: Buffer[] = [];
+	let start = 0;
+	for (let i = 1; i < cuts.length; i += 1) {
+		try {
+			parts.push(zstdDecompressSync(raw.subarray(cuts[start], cuts[i])));
+			start = i;
+		} catch {
+			// 误判的帧边界：与下一帧合并后重试
+		}
+	}
+	return Buffer.concat(parts);
+}
+
+export async function readZstdJsonl(file: string): Promise<string> {
+	return decodeZstdFrames(await fs.readFile(file)).toString("utf8");
+}
+
+/**
+ * 只解出前面的行即可判断会话是否值得导入（扫描用）：逐帧解压，凑够若干帧就停，
+ * 避免为了列个表把 39MB 全解出来。
+ *
+ * `complete` 表示"解出来的就是全部内容"——真实文件能到 7559 帧，前 40 帧只覆盖开头一小段，
+ * 所以只有 complete 为真时才能断言"这个会话里面没有消息"。
+ */
+export async function readZstdHead(file: string, maxFrames = 40): Promise<{ text: string; complete: boolean }> {
+	const raw = await fs.readFile(file);
+	const cuts: number[] = [];
+	for (let i = 0; (i = raw.indexOf(MAGIC, i)) !== -1; i += MAGIC.length) cuts.push(i);
+	if (!cuts.length) {
+		try {
+			return { text: zstdDecompressSync(raw).toString("utf8").slice(0, 64 * 1024), complete: true };
+		} catch {
+			return { text: "", complete: false };
+		}
+	}
+	cuts.push(raw.length);
+	const total = cuts.length - 1;
+	const out: string[] = [];
+	for (let i = 1; i < cuts.length && i <= maxFrames; i += 1) {
+		try {
+			out.push(zstdDecompressSync(raw.subarray(cuts[i - 1], cuts[i])).toString("utf8"));
+		} catch {
+			// 边界误判：跳过这片
+		}
+	}
+	return { text: out.join(""), complete: total <= maxFrames };
+}

package/src/lib/session-import/dsh.ts

@@ -0,0 +1,248 @@
+/**
+ * dsh（DeepSeek Harness）：`~/.dsh/sessions/<编码 cwd>/session-<uuid>/session.jsonl.zstd`
+ *
+ * 多帧 zstd 压缩的 JSONL，行形状 `{type, seq, time, data}`。实测要点（照抄真实文件）：
+ *  - assistant/message 的 content 里 **已经带 tool-call 块**，与独立的 tool/call 行是同一批调用
+ *    （本机 241 : 241 完全对应），所以只取前者，否则工具调用会翻倍。
+ *  - tool/result 是 `message.content[0] = {type:"tool-result", toolCallId, content:[...], isError}`，
+ *    比别的来源深一层。
+ *  - plugin / agent-instructions 来源的 user/message 是运行时注入（沙箱策略、AGENTS.md 快照、
+ *    压缩摘要），pi 端会注入自己的那一套，导入时跳过并计数。
+ */
+import path from "node:path";
+import fs from "node:fs/promises";
+import { listFiles, reachedLimit, sortByRecency } from "./files";
+import { dshRoot } from "./paths";
+import { readZstdHead, readZstdJsonl } from "./dsh-zstd";
+import type { ExternalSessionSummary, ImportedBlock, ImportedEntry, ImportedSession, ImportSourceModule, ScanOptions } from "./types";
+import { cleanTitle, compactBlocks, outputBlocks, parseArguments, textBlock, toEpochMs } from "./types";
+
+const ROOT = dshRoot;
+
+/**
+ * 目录名是编码后的 cwd（`--D-AIApp-PiWeb--`）；非 ASCII 用 `~XXXX` 表示码位
+ * （`--D-AIApp-Ordo-~524D~7AEF~9875~9762--` = `D:\AIApp\Ordo-前端页面`）。
+ * 还原不出来就返回 undefined，交给 header.cwd。
+ */
+export function decodeCwdDir(name: string): string | undefined {
+	const match = /^--(.+)--$/.exec(name);
+	if (!match) return undefined;
+	const body = match[1].replace(/~([0-9A-Fa-f]{4})/g, (_, hex: string) => String.fromCharCode(parseInt(hex, 16)));
+	if (!/^[A-Za-z]-/.test(body)) return undefined; // 只有盘符风格能可靠还原（POSIX 路径无法与 - 区分）
+	return `${body[0]}:\\${body.slice(2).split("-").filter(Boolean).join("\\")}`;
+}
+
+interface DshHeader {
+	id?: string;
+	cwd?: string;
+	createdAt?: number;
+}
+
+function parseRecords(text: string): { header: DshHeader; records: Record<string, unknown>[] } {
+	const records: Record<string, unknown>[] = [];
+	let header: DshHeader = {};
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		let parsed: Record<string, unknown>;
+		try {
+			parsed = JSON.parse(trimmed) as Record<string, unknown>;
+		} catch {
+			continue;
+		}
+		if (parsed.type === "session") {
+			header = { id: typeof parsed.id === "string" ? parsed.id : undefined, cwd: typeof parsed.cwd === "string" ? parsed.cwd : undefined, createdAt: toEpochMs(parsed.createdAt) };
+			continue;
+		}
+		records.push(parsed);
+	}
+	return { header, records };
+}
+
+/** request/header 里带 provider+model；取最后一次生效的作为会话的模型 */
+function configOf(data: Record<string, unknown> | undefined): { provider?: string; model?: string } {
+	const config = (data?.header as Record<string, unknown> | undefined)?.config as Record<string, unknown> | undefined;
+	return {
+		provider: typeof config?.provider === "string" ? config.provider : undefined,
+		model: typeof config?.model === "string" ? config.model : undefined,
+	};
+}
+
+/** assistant/message 的 content 块：reasoning→thinking、text→text、tool-call→toolCall */
+function assistantBlocks(content: unknown): ImportedBlock[] {
+	if (!Array.isArray(content)) return [];
+	return compactBlocks(content.flatMap((raw): Array<ImportedBlock | null> => {
+		const block = raw as Record<string, unknown>;
+		if (block?.type === "reasoning" || block?.type === "thinking") {
+			return typeof block.text === "string" && block.text.trim() ? [{ type: "thinking", thinking: block.text }] : [];
+		}
+		if (block?.type === "text") return [textBlock(block.text)];
+		if (block?.type === "tool-call") {
+			const id = typeof block.id === "string" ? block.id : "";
+			const name = typeof block.name === "string" ? block.name : "";
+			return id && name ? [{ type: "toolCall", id, name, arguments: parseArguments(block.arguments) }] : [];
+		}
+		return [];
+	}));
+}
+
+/** 用户消息块：只认 text */
+function userBlocks(content: unknown): ImportedBlock[] {
+	if (!Array.isArray(content)) return [];
+	return compactBlocks(content.flatMap((raw): Array<ImportedBlock | null> => {
+		const block = raw as Record<string, unknown>;
+		return block?.type === "text" ? [textBlock(block.text)] : [];
+	}));
+}
+
+/**
+ * 一个会话目录里可能同时存在 `session.jsonl.zstd` 与 `session.v3.jsonl.zstd`（迁移产物，
+ * 本机有 6 个这样的目录）。两者是同一个会话、externalId 相同，都列出来就会重复，
+ * 导入时还会被判成"重复选择"。选 v3：它是迁移后的规范格式，去掉了流式分片，
+ * 实测消息条数反而更多（44/171/241/256 → 46/179/247/262），也确认了 v3 才是最新的完整历史。
+ */
+function pickPerSession(files: string[]): string[] {
+	const best = new Map<string, string>();
+	for (const file of files) {
+		const dir = path.dirname(file);
+		const previous = best.get(dir);
+		if (!previous || (file.includes(".v3.") && !previous.includes(".v3."))) best.set(dir, file);
+	}
+	return [...best.values()];
+}
+
+/** tool/result 的输出深一层：{type:"tool-result", toolCallId, content:[{type:"text"}], isError} */
+function toolResultOf(message: Record<string, unknown> | undefined): { callId: string; content: ImportedBlock[]; isError: boolean } {
+	const blocks = Array.isArray(message?.content) ? (message?.content as Record<string, unknown>[]) : [];
+	const node = (blocks.find((block) => block?.type === "tool-result") ?? blocks[0]) as Record<string, unknown> | undefined;
+	const source = message?.source as Record<string, unknown> | undefined;
+	const callId = typeof node?.toolCallId === "string" ? node.toolCallId : typeof source?.callId === "string" ? source.callId : "";
+	return { callId, content: outputBlocks(node?.content ?? node), isError: node?.isError === true };
+}
+
+export const dshSource: ImportSourceModule = {
+	id: "dsh",
+
+	async scan(options?: ScanOptions): Promise<ExternalSessionSummary[]> {
+		const limit = options?.limit ?? 0;
+		const files = await listFiles(ROOT(), { match: (name) => name.endsWith(".jsonl.zstd") });
+		const candidates = await sortByRecency(pickPerSession(files));
+		const out: ExternalSessionSummary[] = [];
+		for (const { file, mtime } of candidates) {
+			if (reachedLimit(out.length, limit)) break; // 只解压最近的若干条：其余的连 zstd 都不碰
+			let head: { text: string; complete: boolean };
+			try {
+				head = await readZstdHead(file);
+			} catch {
+				continue;
+			}
+			const { header, records } = parseRecords(head.text);
+			if (!header.id) continue;
+			// 建了却从没用过的会话（只有 header 与几条配置）：整个文件都解出来却没有消息，不该列进列表
+			if (head.complete && !records.some((record) => record.type === "user/message" || record.type === "assistant/message")) continue;
+			let title: string | undefined;
+			let provider: string | undefined;
+			let model: string | undefined;
+			for (const record of records) {
+				const data = record.data as Record<string, unknown> | undefined;
+				if (record.type === "session/title") {
+					title = cleanTitle(data?.title ?? data?.name) ?? title;
+				}
+				if (record.type === "request/header") {
+					const config = configOf(data);
+					provider = config.provider ?? provider;
+					model = config.model ?? model;
+				}
+			}
+			const sessionDir = path.basename(path.dirname(file));
+			out.push({
+				source: "dsh",
+				externalId: sessionDir || header.id,
+				title,
+				projectPath: header.cwd ?? decodeCwdDir(path.basename(path.dirname(path.dirname(file)))),
+				provider,
+				model,
+				createdAt: header.createdAt ?? mtime,
+				updatedAt: mtime,
+				// 扫描只解前若干帧，统计整会话条数不可靠：留空由界面显示 —
+				location: file,
+			});
+		}
+		return out;
+	},
+
+	async read(summary: ExternalSessionSummary): Promise<ImportedSession | null> {
+		let text: string;
+		try {
+			text = await readZstdJsonl(summary.location);
+		} catch {
+			return null;
+		}
+		const { header, records } = parseRecords(text);
+		const entries: ImportedEntry[] = [];
+		let title = summary.title;
+		let injected = 0;
+		let provider = summary.provider;
+		let model = summary.model;
+		let lastAt = header.createdAt ?? summary.createdAt ?? Date.now();
+
+		for (const record of records) {
+			const type = typeof record.type === "string" ? record.type : "";
+			const at = toEpochMs(record.time) ?? lastAt;
+			lastAt = at;
+			const data = record.data as Record<string, unknown> | undefined;
+
+			if (type === "user/message") {
+				const source = data?.source as Record<string, unknown> | undefined;
+				if (source?.kind !== "user") {
+					injected += 1; // 插件注入 / AGENTS.md 快照 / 压缩摘要：pi 端会注入自己的版本
+					continue;
+				}
+				const content = userBlocks(data?.content);
+				if (!content.length) continue;
+				entries.push({ type: "message", message: { role: "user", content, timestamp: at } });
+				continue;
+			}
+
+			if (type === "assistant/message") {
+				const message = data?.message as Record<string, unknown> | undefined;
+				const content = assistantBlocks(message?.content);
+				if (!content.length) continue;
+				const hasCall = content.some((block) => block.type === "toolCall");
+				entries.push({ type: "message", message: { role: "assistant", content, timestamp: at, stopReason: hasCall ? "toolUse" : "stop" } });
+				continue;
+			}
+
+			// tool/call 行与 assistant/message 里的 tool-call 块是同一批调用，重复导入会让调用翻倍
+			if (type === "tool/call") continue;
+
+			if (type === "tool/result") {
+				const message = data?.message as Record<string, unknown> | undefined;
+				const result = toolResultOf(message);
+				if (!result.callId || !result.content.length) continue;
+				entries.push({ type: "message", message: { role: "toolResult", toolCallId: result.callId, content: result.content, isError: result.isError, timestamp: at } });
+				continue;
+			}
+
+			if (type === "session/title") {
+				title = cleanTitle(data?.title ?? data?.name) ?? title;
+				continue;
+			}
+
+			if (type === "request/header") {
+				const config = configOf(data);
+				provider = config.provider ?? provider;
+				model = config.model ?? model;
+			}
+		}
+
+		if (!entries.some((entry) => entry.type === "message")) return null;
+		const skipped: string[] = [];
+		if (injected) skipped.push(`跳过 ${injected} 条运行时注入消息（沙箱策略 / AGENTS.md 快照 / 压缩摘要）`);
+		return {
+			summary: { ...summary, title, provider, model, projectPath: header.cwd ?? summary.projectPath },
+			entries,
+			skipped,
+		};
+	},
+};

package/src/lib/session-import/files.ts

@@ -0,0 +1,84 @@
+/** 文件类来源的公共读取：扫描时只读文件头（避免为了列表把几百 MB 全读进来），导入时才整读 */
+import fs from "node:fs/promises";
+
+/** 读文件开头若干字节（不切 UTF-8 字符：按行切分后只取完整行） */
+export async function readHead(file: string, bytes = 64 * 1024): Promise<string> {
+	const handle = await fs.open(file, "r");
+	try {
+		const buffer = Buffer.alloc(bytes);
+		const { bytesRead } = await handle.read(buffer, 0, bytes, 0);
+		return buffer.subarray(0, bytesRead).toString("utf8");
+	} finally {
+		await handle.close();
+	}
+}
+
+/** 逐行解析 JSONL；单行坏掉只跳过该行，不放弃整个文件 */
+export function* eachJsonLine(text: string): Generator<Record<string, unknown>> {
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+		try {
+			const parsed = JSON.parse(trimmed);
+			if (parsed && typeof parsed === "object") yield parsed as Record<string, unknown>;
+		} catch {
+			// 单行损坏（写入中断等）：跳过
+		}
+	}
+}
+
+/** 从文件头里取第一批记录（扫描用） */
+export function headRecords(text: string, limit = 400): Record<string, unknown>[] {
+	const out: Record<string, unknown>[] = [];
+	for (const record of eachJsonLine(text)) {
+		out.push(record);
+		if (out.length >= limit) break;
+	}
+	return out;
+}
+
+/** 递归列文件，带深度上限与名字过滤 */
+export async function listFiles(root: string, options: { match: (name: string) => boolean; maxDepth?: number }): Promise<string[]> {
+	const out: string[] = [];
+	const maxDepth = options.maxDepth ?? 4;
+	async function walk(dir: string, depth: number) {
+		let entries;
+		try {
+			entries = await fs.readdir(dir, { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const entry of entries) {
+			const full = `${dir}${dir.endsWith("/") || dir.endsWith("\\") ? "" : "/"}${entry.name}`;
+			if (entry.isDirectory()) {
+				if (depth < maxDepth) await walk(full, depth + 1);
+			} else if (entry.isFile() && options.match(entry.name)) {
+				out.push(full);
+			}
+		}
+	}
+	await walk(root, 1);
+	return out;
+}
+
+export async function statMtime(file: string): Promise<number | undefined> {
+	try {
+		return (await fs.stat(file)).mtimeMs;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * 按最近活动倒序：扫描只列最近若干条，所以先按 mtime 排序（只 stat、不读内容），
+ * 再从头读——读到够了就停，剩下的文件根本不打开。
+ */
+export async function sortByRecency(files: string[]): Promise<Array<{ file: string; mtime?: number }>> {
+	const rows = await Promise.all(files.map(async (file) => ({ file, mtime: await statMtime(file) })));
+	return rows.sort((left, right) => (right.mtime ?? 0) - (left.mtime ?? 0));
+}
+
+/** 到达上限就别再往下读了（limit <= 0 表示不限） */
+export function reachedLimit(count: number, limit: number): boolean {
+	return limit > 0 && count >= limit;
+}