@rexvane/piweb 0.3.12 → 0.3.14

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

@@ -0,0 +1,229 @@
+/**
+ * 导入会话的门面：扫描 → 选择 → 写入 pi 会话。
+ *
+ * 两条刻意的设计：
+ *  1. **不从客户端拿路径**。前端只回传 `{source, externalId}`，服务端在导入时按来源重新扫描一次
+ *     把 summary 解出来（扫描很便宜：SQLite 6~42ms，文件类只读文件头）。这样路径遍历之类的输入
+ *     完全进不来，也不会因为前端缓存了过期数据而写错文件。
+ *  2. **单来源失败不影响其他来源**。某个工具没装 / 库损坏时，那一组空着并带错误原因，其余照常。
+ */
+import path from "node:path";
+import fs from "node:fs/promises";
+import type { ExternalSessionSummary, ImportSource, ImportSourceModule } from "./types";
+import { IMPORT_SOURCES } from "./types";
+import { claudeSource } from "./claude";
+import { codexSource } from "./codex";
+import { grokSource } from "./grok";
+import { dshSource } from "./dsh";
+import { zcodeSource } from "./zcode";
+import { opencodeSource } from "./opencode";
+import { importedKey, listImportedKeys, findImported, writeImportedSession } from "./writer";
+
+export const IMPORT_SOURCE_MODULES: Record<ImportSource, ImportSourceModule> = {
+	claude: claudeSource,
+	codex: codexSource,
+	grok: grokSource,
+	zcode: zcodeSource,
+	dsh: dshSource,
+	opencode: opencodeSource,
+};
+
+/** 单来源扫描超时：库被别的进程锁死时不让整个面板卡住 */
+const SCAN_TIMEOUT_MS = 30_000;
+/**
+ * 面板每个来源只列最近这么多条：本机六个来源合计上千个会话，全读一遍纯属浪费，
+ * 而用户真正要导的基本都是最近用的那几个。想看更早的会话时把这里调大即可。
+ */
+export const SCAN_LIMIT_PER_SOURCE = 15;
+/** 单会话上限：超过就别导了，内存和解压都吃不消（dsh 解压后能膨胀到几百 MB） */
+const MAX_SOURCE_BYTES = 200 * 1024 * 1024;
+const MAX_ENTRIES = 50_000;
+
+export interface SourceScanError {
+	source: ImportSource;
+	message: string;
+}
+
+export interface ScanReport {
+	summaries: ExternalSessionSummary[];
+	errors: SourceScanError[];
+	/** 已导入过的 `source:externalId`，界面用来标"已导入"并禁止重复选 */
+	imported: string[];
+}
+
+function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+	return new Promise<T>((resolve, reject) => {
+		const timer = setTimeout(() => reject(new Error(message)), ms);
+		promise.then(
+			(value) => {
+				clearTimeout(timer);
+				resolve(value);
+			},
+			(error) => {
+				clearTimeout(timer);
+				reject(error);
+			},
+		);
+	});
+}
+
+/** 扫描全部来源；返回的 summary 带 imported 标记，且已按时间倒序 */
+export async function scanAllSources(agentDir: string, options: { sources?: ImportSource[]; limit?: number } = {}): Promise<ScanReport> {
+	const sources = options.sources ?? IMPORT_SOURCES;
+	const limit = options.limit ?? SCAN_LIMIT_PER_SOURCE;
+	const summaries: ExternalSessionSummary[] = [];
+	const errors: SourceScanError[] = [];
+	const imported = await listImportedKeys(agentDir);
+
+	await Promise.all(sources.map(async (source) => {
+		const module = IMPORT_SOURCE_MODULES[source];
+		if (!module) return;
+		try {
+			const found = await withTimeout(module.scan({ limit }), SCAN_TIMEOUT_MS, "扫描超时（30 秒）");
+			summaries.push(...found);
+		} catch (error) {
+			errors.push({ source, message: error instanceof Error ? error.message : String(error) });
+		}
+	}));
+
+	summaries.sort((left, right) => (right.updatedAt ?? right.createdAt ?? 0) - (left.updatedAt ?? left.createdAt ?? 0));
+	return { summaries, errors, imported: [...imported] };
+}
+
+export interface ImportSelection {
+	source: ImportSource;
+	externalId: string;
+}
+
+export interface ImportOutcome {
+	source: ImportSource;
+	externalId: string;
+	title?: string;
+	status: "imported" | "skipped" | "failed";
+	reason?: string;
+	messageCount?: number;
+	/** 导入到的 pi 会话文件（成功时） */
+	path?: string;
+	/** 落到的工具目录；源项目路径本机不存在时会与源项目不同 */
+	workspace?: string;
+	skipped?: string[];
+}
+
+export interface ImportReport {
+	imported: number;
+	skipped: number;
+	failed: number;
+	results: ImportOutcome[];
+	/** 本次涉及到的目录（调用方据此注册工作区） */
+	workspaces: string[];
+}
+
+export interface ImportOptions {
+	agentDir: string;
+	/** 源项目路径在本机不存在时的兜底工作区（必须已存在） */
+	fallbackCwd?: string;
+	now?: number;
+	onProgress?: (done: number, total: number) => void;
+}
+
+async function isDirectory(target: string | undefined): Promise<boolean> {
+	if (!target || !path.isAbsolute(target)) return false;
+	try {
+		return (await fs.stat(target)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** 源文件大小闸门：`file|id` 形式的 SQLite 位置没有单文件概念，直接放行（读的是库里的行） */
+async function oversize(location: string): Promise<boolean> {
+	if (location.includes("|")) return false;
+	try {
+		return (await fs.stat(location)).size > MAX_SOURCE_BYTES;
+	} catch {
+		return false;
+	}
+}
+
+export async function importSessions(items: ImportSelection[], options: ImportOptions): Promise<ImportReport> {
+	const results: ImportOutcome[] = [];
+	const workspaces = new Set<string>();
+	const fallback = (await isDirectory(options.fallbackCwd)) ? path.resolve(options.fallbackCwd as string) : undefined;
+	const scanned = new Map<ImportSource, Map<string, ExternalSessionSummary>>();
+	const seen = new Set<string>();
+
+	const resolveSummary = async (source: ImportSource, externalId: string): Promise<ExternalSessionSummary | undefined> => {
+		let cache = scanned.get(source);
+		if (!cache) {
+			const module = IMPORT_SOURCE_MODULES[source];
+			if (!module) return undefined;
+			cache = new Map();
+			// limit: 0 = 不限：这里要按 id 反查任意一条会话（面板只列最近的 15 条，
+			// 但选择来自面板、且可能已经过几分钟，所以解析一定要能看到全部，不能跟着截断）
+			for (const summary of await module.scan({ limit: 0 })) cache.set(summary.externalId, summary);
+			scanned.set(source, cache);
+		}
+		return cache.get(externalId);
+	};
+
+	let done = 0;
+	for (const item of items) {
+		const { source, externalId } = item;
+		const outcome: ImportOutcome = { source, externalId, status: "failed" };
+		try {
+			if (!IMPORT_SOURCE_MODULES[source]) {
+				outcome.reason = "不支持的来源";
+			} else if (seen.has(importedKey(source, externalId))) {
+				outcome.status = "skipped";
+				outcome.reason = "同一次导入里重复选择";
+			} else if (await findImported(options.agentDir, source, externalId)) {
+				outcome.status = "skipped";
+				outcome.reason = "已经导入过";
+			} else {
+				const summary = await resolveSummary(source, externalId);
+				if (!summary) {
+					outcome.reason = "源会话已不存在（可能被源工具删掉或移动）";
+				} else if (await oversize(summary.location)) {
+					outcome.reason = "源会话过大（超过 200MB），已跳过";
+				} else {
+					const session = await IMPORT_SOURCE_MODULES[source].read(summary);
+					if (!session) {
+						outcome.reason = "源会话读不出可导入的消息";
+					} else if (session.entries.length > MAX_ENTRIES) {
+						outcome.reason = `消息过多（${session.entries.length} 条），已跳过`;
+					} else {
+						// 源项目路径本机存在就导回原工作区，否则落到用户选的兜底工作区
+						const sourceProject = session.summary.projectPath;
+						const target = (await isDirectory(sourceProject)) ? path.resolve(sourceProject as string) : fallback;
+						if (!target) {
+							outcome.reason = sourceProject ? `源项目目录不存在：${sourceProject}` : "源会话没有项目目录，且未选择兜底工作区";
+						} else {
+							const written = await writeImportedSession(session, { cwd: target, agentDir: options.agentDir, now: options.now });
+							outcome.status = "imported";
+							outcome.path = written.path;
+							outcome.messageCount = written.messageCount;
+							outcome.workspace = target;
+							outcome.title = session.summary.title;
+							if (written.skipped.length) outcome.skipped = written.skipped;
+							workspaces.add(target);
+							seen.add(importedKey(source, externalId));
+						}
+					}
+				}
+			}
+		} catch (error) {
+			outcome.reason = error instanceof Error ? error.message : String(error);
+		}
+		results.push(outcome);
+		done += 1;
+		options.onProgress?.(done, items.length);
+	}
+
+	return {
+		imported: results.filter((result) => result.status === "imported").length,
+		skipped: results.filter((result) => result.status === "skipped").length,
+		failed: results.filter((result) => result.status === "failed").length,
+		results,
+		workspaces: [...workspaces],
+	};
+}

package/src/lib/session-import/oc-family.ts

@@ -0,0 +1,275 @@
+/**
+ * ZCode 与 opencode 的会话库是同一套血缘（session / message / part 三表，data 列存 JSON），
+ * 差别只在排序字段与少量列名，所以共用这一份适配器，各自只传自己的库路径与来源 id。
+ *
+ * 只读、只取顶层会话（parent_id 为空）：库里的 parent_id 指子代理/侧链会话，本机 ZCode 421 条里有
+ * 330 条是这种，导进来只会淹没侧栏；对应用户"只取主链"的要求。
+ */
+import type { ExternalSessionSummary, ImportedBlock, ImportedEntry, ImportedMessage, ImportedSession, ImportSource, ImportSourceModule, ImportedUsage, ScanOptions } from "./types";
+import { cleanTitle, compactBlocks, outputBlocks, textBlock, toEpochMs } from "./types";
+import { openReadOnly, parseJsonColumn, type ReadOnlyDb } from "./sqlite";
+import { zcodeDb, opencodeDb } from "./paths";
+
+interface FamilyOptions {
+	id: ImportSource;
+	/** 库文件绝对路径 */
+	dbPath(): string;
+}
+
+/** `data:` URL 形式的附件能还原成真正的图片块（opencode 用这种） */
+function imageFromUrl(url: unknown, mime: unknown): ImportedBlock | null {
+	if (typeof url !== "string" || !url.startsWith("data:")) return null;
+	const match = /^data:([^;,]+);base64,(.+)$/s.exec(url);
+	if (!match) return null;
+	return { type: "image", data: match[2], mimeType: typeof mime === "string" && mime ? mime : match[1] };
+}
+
+function orderClause(db: ReadOnlyDb, table: string, fallback: string): string {
+	return db.hasColumn(table, "sequence") ? `sequence, time_created, id` : fallback;
+}
+
+/** 消息里的 provider/model 列名两代不同：zcode 用 modelId/providerId，opencode 用 modelID/providerID */
+function modelOf(data: Record<string, unknown>): { provider?: string; model?: string } {
+	const pick = (camel: string) => {
+		const value = data[camel];
+		return typeof value === "string" && value ? value : undefined;
+	};
+	return { provider: pick("providerID") ?? pick("providerId"), model: pick("modelID") ?? pick("modelId") };
+}
+
+function usageOf(data: Record<string, unknown>): ImportedUsage {
+	const tokens = data.tokens as Record<string, unknown> | undefined;
+	if (!tokens) return {};
+	const cache = tokens.cache as Record<string, unknown> | undefined;
+	const num = (value: unknown) => (typeof value === "number" && Number.isFinite(value) ? value : undefined);
+	return {
+		input: num(tokens.input),
+		output: num(tokens.output),
+		reasoning: num(tokens.reasoning),
+		cacheRead: num(cache?.read),
+		cacheWrite: num(cache?.write),
+		totalTokens: num(tokens.total),
+	};
+}
+
+/** 消息内容块（user 消息也会带 file 附件） */
+function partBlocks(data: Record<string, unknown>): { blocks: ImportedBlock[]; ignored: number } {
+	const type = typeof data.type === "string" ? data.type : "";
+	if (type === "text") return { blocks: compactBlocks([textBlock(data.text)]), ignored: 0 };
+	if (type === "file") {
+		const image = imageFromUrl(data.url, data.mime);
+		if (image) return { blocks: [image], ignored: 0 };
+		// zcode 的附件是 zcode-artifact:// 协议，取不出字节：留一条文本注记而不是丢弃
+		const name = typeof data.filename === "string" ? data.filename : typeof data.mime === "string" ? data.mime : "附件";
+		return { blocks: compactBlocks([textBlock(`[附件: ${name}]`)]), ignored: 0 };
+	}
+	return { blocks: [], ignored: 1 };
+}
+
+/**
+ * 一条 message = 一次模型请求（opencode 血缘的表结构就是这样），所以按 pi 的原生形状合成：
+ * **一条 assistant 消息**（思考 + 正文 + 全部 toolCall，与 pi 自己写出来的完全一致），
+ * 后面紧跟每个调用的 toolResult。拆成多条反而会打散一次请求内的调用/结果配对，
+ * 用量也只能挂到最后一个碎片上。
+ */
+function assistantEntries(parts: Record<string, unknown>[], base: { timestamp: number; provider?: string; model?: string }): { entries: ImportedEntry[]; ignored: number } {
+	const entries: ImportedEntry[] = [];
+	let ignored = 0;
+	let blocks: ImportedBlock[] = [];
+	const results: Array<{ toolCallId: string; toolName: string; content: ImportedBlock[]; isError: boolean }> = [];
+
+	for (const data of parts) {
+		const type = typeof data.type === "string" ? data.type : "";
+		if (type === "text") {
+			const block = textBlock(data.text);
+			if (block) blocks.push(block);
+			continue;
+		}
+		if (type === "reasoning") {
+			// 加密推理只有密文（opencode 会存 reasoningEncryptedContent）：无正文可导，丢掉
+			if (typeof data.text === "string" && data.text.trim()) blocks.push({ type: "thinking", thinking: data.text });
+			continue;
+		}
+		if (type === "tool") {
+			const callId = typeof data.callID === "string" ? data.callID : "";
+			const name = typeof data.tool === "string" ? data.tool : "";
+			const state = data.state as Record<string, unknown> | undefined;
+			if (!callId || !name) continue;
+			blocks.push({ type: "toolCall", id: callId, name, arguments: state?.input ?? {} });
+			const failed = state?.status === "error";
+			const content = outputBlocks(state?.output ?? state?.error ?? "");
+			results.push({
+				toolCallId: callId,
+				toolName: name,
+				content: content.length ? content : compactBlocks([textBlock(failed ? "工具执行失败" : "(无输出)")]),
+				isError: failed,
+			});
+			continue;
+		}
+		// step-start / step-finish / timeline / compaction / patch 等：pi 侧没有对应概念或会重复
+		ignored += 1;
+	}
+
+	const hasCall = results.length > 0;
+	if (blocks.length) {
+		entries.push({
+			type: "message",
+			message: {
+				role: "assistant",
+				content: blocks,
+				timestamp: base.timestamp,
+				stopReason: hasCall ? "toolUse" : "stop",
+				...(base.provider ? { provider: base.provider } : {}),
+				...(base.model ? { model: base.model } : {}),
+			},
+		});
+	}
+	for (const result of results) {
+		entries.push({
+			type: "message",
+			message: {
+				role: "toolResult",
+				toolCallId: result.toolCallId,
+				toolName: result.toolName,
+				content: result.content,
+				...(result.isError ? { isError: true } : {}),
+				timestamp: base.timestamp,
+			},
+		});
+	}
+	return { entries, ignored };
+}
+
+function createSource(options: FamilyOptions): ImportSourceModule {
+	async function open(): Promise<ReadOnlyDb | null> {
+		return openReadOnly(options.dbPath());
+	}
+
+	return {
+		id: options.id,
+
+		async scan(scanOptions?: ScanOptions): Promise<ExternalSessionSummary[]> {
+			const db = await open();
+			if (!db) return [];
+			try {
+				if (!db.hasTable("session") || !db.hasTable("message")) return [];
+				// 空会话（只有标题没有消息）与子代理会话直接在 SQL 里排掉，这样 LIMIT 才是"最近 N 条有效会话"
+				const limit = scanOptions?.limit ?? 0;
+				const rows = db.all(
+					`SELECT s.id AS id, s.title AS title, s.directory AS directory, s.time_created AS created, s.time_updated AS updated,
+					        (SELECT COUNT(*) FROM message m WHERE m.session_id = s.id) AS msg_count
+					 FROM session s
+					 WHERE s.parent_id IS NULL AND (SELECT COUNT(*) FROM message m WHERE m.session_id = s.id) > 0
+					 ORDER BY COALESCE(s.time_updated, s.time_created) DESC${limit > 0 ? " LIMIT ?" : ""}`,
+					limit > 0 ? [limit] : [],
+				);
+				const file = options.dbPath();
+				const out: ExternalSessionSummary[] = [];
+				for (const row of rows) {
+					const id = typeof row.id === "string" ? row.id : "";
+					if (!id) continue;
+					const title = cleanTitle(/^New session - /.test(String(row.title)) ? undefined : row.title);
+					out.push({
+						source: options.id,
+						externalId: id,
+						title,
+						projectPath: typeof row.directory === "string" ? row.directory : undefined,
+						createdAt: toEpochMs(row.created),
+						updatedAt: toEpochMs(row.updated),
+						messageCount: typeof row.msg_count === "number" ? row.msg_count : undefined,
+						location: `${file}|${id}`,
+					});
+				}
+				return out;
+			} finally {
+				db.close();
+			}
+		},
+
+		async read(summary: ExternalSessionSummary): Promise<ImportedSession | null> {
+			const separator = summary.location.lastIndexOf("|");
+			if (separator < 0) return null;
+			const file = summary.location.slice(0, separator);
+			const sessionId = summary.location.slice(separator + 1);
+			const db = await openReadOnly(file);
+			if (!db) return null;
+			try {
+				const session = db.get("SELECT title, directory, time_created FROM session WHERE id = ?", [sessionId]);
+				const messages = db.all(`SELECT id, data FROM message WHERE session_id = ? ORDER BY ${orderClause(db, "message", "time_created, id")}`, [sessionId]);
+				const parts = db.all(`SELECT message_id, data FROM part WHERE session_id = ? ORDER BY ${orderClause(db, "part", "message_id, time_created, id")}`, [sessionId]);
+				const partsByMessage = new Map<string, Record<string, unknown>[]>();
+				for (const row of parts) {
+					const messageId = typeof row.message_id === "string" ? row.message_id : "";
+					const data = parseJsonColumn(row.data);
+					if (!messageId || !data) continue;
+					const list = partsByMessage.get(messageId);
+					if (list) list.push(data);
+					else partsByMessage.set(messageId, [data]);
+				}
+
+				const entries: ImportedEntry[] = [];
+				let ignored = 0;
+				let provider: string | undefined;
+				let model: string | undefined;
+				let lastAt = toEpochMs(session?.time_created) ?? summary.createdAt ?? Date.now();
+
+				for (const row of messages) {
+					const id = typeof row.id === "string" ? row.id : "";
+					const data = parseJsonColumn(row.data);
+					if (!data) continue;
+					const time = data.time as Record<string, unknown> | undefined;
+					const at = toEpochMs(time?.created) ?? toEpochMs(time?.completed) ?? lastAt;
+					lastAt = at;
+					const own = partsByMessage.get(id) ?? [];
+					const role = typeof data.role === "string" ? data.role : "";
+
+					if (role === "user") {
+						const blocks: ImportedBlock[] = [];
+						for (const part of own) {
+							const result = partBlocks(part);
+							blocks.push(...result.blocks);
+							ignored += result.ignored;
+						}
+						if (!blocks.length) continue;
+						entries.push({ type: "message", message: { role: "user", content: blocks, timestamp: at } });
+						continue;
+					}
+					if (role !== "assistant") continue;
+
+					const info = modelOf(data);
+					provider = info.provider ?? provider;
+					model = info.model ?? model;
+					const usage = usageOf(data);
+					const expanded = assistantEntries(own, { timestamp: at, provider: info.provider, model: info.model });
+					ignored += expanded.ignored;
+					// 一次请求的 token 记在这条消息**最后一个 assistant 条目**上（末尾常是工具结果，
+					// 所以不能简单取 entries 的最后一项目），否则同一笔用量会被数多次或整个丢掉
+					const usageIndex = expanded.entries.reduce((last, entry, index) => (entry.type === "message" && entry.message.role === "assistant" ? index : last), -1);
+					expanded.entries.forEach((entry, index) => {
+						if (index === usageIndex && entry.type === "message" && entry.message.role === "assistant" && Object.keys(usage).length) {
+							entries.push({ type: "message", message: { ...entry.message, usage } });
+							return;
+						}
+						entries.push(entry);
+					});
+				}
+
+				if (!entries.some((entry) => entry.type === "message")) return null;
+				const title = cleanTitle(/^New session - /.test(String(session?.title)) ? undefined : session?.title) ?? cleanTitle(summary.title);
+				const skipped: string[] = [];
+				if (ignored) skipped.push(`跳过 ${ignored} 个内部片段（步骤标记 / 压缩记录 / 补丁快照）`);
+				return {
+					summary: { ...summary, title, provider, model, projectPath: (typeof session?.directory === "string" ? session.directory : summary.projectPath) },
+					entries,
+					skipped,
+				};
+			} finally {
+				db.close();
+			}
+		},
+	};
+}
+
+export function createOcFamilySource(id: ImportSource, file: () => string): ImportSourceModule {
+	return createSource({ id, dbPath: file });
+}

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

@@ -0,0 +1,7 @@
+/**
+ * opencode：`~/.local/share/opencode/opencode.db`（与 ZCode 同源的表结构）。
+ */
+import { opencodeDb } from "./paths";
+import { createOcFamilySource } from "./oc-family";
+
+export const opencodeSource = createOcFamilySource("opencode", opencodeDb);

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

@@ -0,0 +1,37 @@
+/**
+ * 各来源在本机的固定位置（一处收口，方便核对与测试替身）。
+ *
+ * 全部基于用户主目录；这些目录**只读**——导入过程中不往源目录写任何东西。
+ */
+import os from "node:os";
+import path from "node:path";
+
+/** Claude Code：~/.claude/projects/<项目 slug>/<会话 uuid>.jsonl */
+export function claudeRoot(): string {
+	return path.join(os.homedir(), ".claude", "projects");
+}
+
+/** Codex CLI：~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl */
+export function codexRoot(): string {
+	return path.join(os.homedir(), ".codex", "sessions");
+}
+
+/** Grok CLI：~/.grok/sessions/<url 编码 cwd>/<id>/{summary.json,chat_history.jsonl} */
+export function grokRoot(): string {
+	return path.join(os.homedir(), ".grok", "sessions");
+}
+
+/** dsh：~/.dsh/sessions/<编码 cwd>/session-<uuid>/session.jsonl.zstd */
+export function dshRoot(): string {
+	return path.join(os.homedir(), ".dsh", "sessions");
+}
+
+/** ZCode：~/.zcode/cli/db/db.sqlite */
+export function zcodeDb(): string {
+	return path.join(os.homedir(), ".zcode", "cli", "db", "db.sqlite");
+}
+
+/** opencode：~/.local/share/opencode/opencode.db（Windows 上也是这个 XDG 风格路径） */
+export function opencodeDb(): string {
+	return path.join(os.homedir(), ".local", "share", "opencode", "opencode.db");
+}

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

@@ -0,0 +1,89 @@
+/**
+ * 只读 SQLite 封装（node:sqlite 的 DatabaseSync，Node 24 起无需 flag）。
+ *
+ * 导入过程中**绝不能写源库**：ZCode / opencode 可能正在跑，写一下就是数据损坏。
+ * 这里三重保险——`readOnly: true`、`PRAGMA query_only = 1`、只暴露查询方法（没有 exec/run 出口）。
+ *
+ * `node:sqlite` 是实验特性，所以**按需**动态载入：载不进来（Node 太老）时只有 ZCode/opencode
+ * 这两个来源报错，文件类的四个来源照常可用——scanAllSources 会把单来源失败隔离掉。
+ */
+import type { DatabaseSync } from "node:sqlite";
+
+export interface ReadOnlyDb {
+	all(sql: string, params?: Array<string | number | null>): Record<string, unknown>[];
+	get(sql: string, params?: Array<string | number | null>): Record<string, unknown> | undefined;
+	hasTable(name: string): boolean;
+	hasColumn(table: string, column: string): boolean;
+	close(): void;
+}
+
+export async function openReadOnly(file: string): Promise<ReadOnlyDb | null> {
+	const DatabaseSyncClass = await loadDriver();
+	if (!DatabaseSyncClass) return null;
+	let db: DatabaseSync;
+	try {
+		db = new DatabaseSyncClass(file, { readOnly: true });
+	} catch {
+		return null; // 文件不存在 / 不是 SQLite / 被占用到无法只读打开
+	}
+	try {
+		db.exec("PRAGMA query_only = 1");
+	} catch {
+		// 老版本不支持该 pragma：readOnly 仍然生效
+	}
+	const all = (sql: string, params: Array<string | number | null> = []) => {
+		try {
+			return db.prepare(sql).all(...params) as Record<string, unknown>[];
+		} catch {
+			return [];
+		}
+	};
+	return {
+		all,
+		get: (sql, params) => all(sql, params)[0],
+		hasTable: (name) => Boolean(all("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", [name]).length),
+		hasColumn: (table, column) => {
+			try {
+				return (db.prepare(`PRAGMA table_info(${table})`).all() as Array<{ name: string }>).some((row) => row.name === column);
+			} catch {
+				return false;
+			}
+		},
+		close: () => {
+			try {
+				db.close();
+			} catch {
+				// 已经关了：无事可做
+			}
+		},
+	};
+}
+
+type DatabaseSyncCtor = typeof DatabaseSync;
+
+let cachedDriver: Promise<DatabaseSyncCtor | null> | null = null;
+
+/** 动态载入 node:sqlite；失败只影响 ZCode/opencode 这两个来源 */
+function loadDriver(): Promise<DatabaseSyncCtor | null> {
+	if (!cachedDriver) {
+		cachedDriver = import("node:sqlite").then(
+			(module) => module.DatabaseSync,
+			(error) => {
+				if (process.env.PIWEB_DEBUG_PROMPT) console.warn("[piweb] node:sqlite 不可用:", error instanceof Error ? error.message : error);
+				return null;
+			},
+		);
+	}
+	return cachedDriver;
+}
+
+/** data 列里的 JSON：坏行返回 null 而不是抛错 */
+export function parseJsonColumn(value: unknown): Record<string, unknown> | null {
+	if (typeof value !== "string" || !value) return null;
+	try {
+		const parsed = JSON.parse(value);
+		return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : null;
+	} catch {
+		return null;
+	}
+}