@rexvane/piweb 0.3.1

package/src/lib/files-service.ts

@@ -0,0 +1,280 @@
+/**
+ * files-service：会话工作区的文件浏览（详情栏「文件」面板）。
+ * 安全边界：目标路径必须落在工作区根内（realpath 双重校验，防符号链接逃逸）。
+ */
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { BoundaryError, isPathInside, resolveWorkspacePath } from "./path-security";
+import { getAgentDir } from "./pi";
+
+export interface FileEntry {
+	name: string;
+	kind: "dir" | "file";
+	size?: number;
+}
+
+export interface DirListing {
+	/** 工作区根下的相对路径（"/" 分隔；根目录为 "."） */
+	dir: string;
+	entries: FileEntry[];
+	/** 单目录分页；客户端可继续拉取，直到 nextOffset 为 null。 */
+	nextOffset: number | null;
+	truncated: boolean;
+}
+
+/** 文本预览上限：256 KB——详情栏预览用，不是文件编辑器 */
+const MAX_READ_BYTES = 256 * 1024;
+/** 单次目录响应上限；后续条目通过 offset 分页获取。 */
+const MAX_ENTRIES = 2000;
+
+function toRel(root: string, target: string): string {
+	const rel = path.relative(root, target).replace(/\\/g, "/");
+	return rel === "" ? "." : rel;
+}
+
+export async function listWorkspaceDir(cwdValue: unknown, relPath: unknown, offsetValue: unknown = 0): Promise<DirListing> {
+	const root = await resolveWorkspacePath(cwdValue);
+	const offset = offsetValue === null || offsetValue === "" ? 0 : Number(offsetValue);
+	if (!Number.isSafeInteger(offset) || offset < 0) throw new BoundaryError("invalid directory offset");
+	const rel = typeof relPath === "string" && relPath.trim() ? relPath.trim().replace(/^[/\\]+/, "") : "";
+	const target = path.resolve(root, rel);
+	if (!isPathInside(root, target)) throw new BoundaryError("path escapes the workspace");
+	const real = await fs.realpath(target).catch(() => {
+		throw new BoundaryError("directory not found");
+	});
+	if (!isPathInside(root, real)) throw new BoundaryError("path escapes the workspace");
+	const stat = await fs.stat(real);
+	if (!stat.isDirectory()) throw new BoundaryError("not a directory");
+
+	const raw = await fs.readdir(real, { withFileTypes: true });
+	const entries: FileEntry[] = [];
+	const special: typeof raw = [];
+	for (const item of raw) {
+		if (item.isDirectory()) {
+			entries.push({ name: item.name, kind: "dir" });
+			continue;
+		}
+		if (item.isFile()) {
+			entries.push({ name: item.name, kind: "file" });
+			continue;
+		}
+		special.push(item);
+	}
+	// Symlinks/junctions need stat before sorting because they may be directories.
+	for (let i = 0; i < special.length; i += 64) {
+		const inspected = await Promise.all(special.slice(i, i + 64).map(async (item) => {
+			const info = await fs.stat(path.join(real, item.name)).catch(() => null);
+			if (!info) return null;
+			return { name: item.name, kind: info.isDirectory() ? "dir" : "file", size: info.isDirectory() ? undefined : info.size } as FileEntry;
+		}));
+		for (const entry of inspected) if (entry) entries.push(entry);
+	}
+	entries.sort((a, b) => {
+		if (a.kind !== b.kind) return a.kind === "dir" ? -1 : 1;
+		return a.name.localeCompare(b.name, undefined, { numeric: true, sensitivity: "base" });
+	});
+	const nextOffset = offset + MAX_ENTRIES < entries.length ? offset + MAX_ENTRIES : null;
+	const page = entries.slice(offset, offset + MAX_ENTRIES);
+	for (let i = 0; i < page.length; i += 64) {
+		await Promise.all(page.slice(i, i + 64).map(async (entry) => {
+			if (entry.kind !== "file" || entry.size !== undefined) return;
+			const info = await fs.stat(path.join(real, entry.name)).catch(() => null);
+			if (info?.isFile()) entry.size = info.size;
+		}));
+	}
+	return {
+		dir: toRel(root, real),
+		entries: page,
+		nextOffset,
+		truncated: nextOffset !== null,
+	};
+}
+
+export interface FilePreview {
+	path: string;
+	binary: boolean;
+	truncated: boolean;
+	content: string;
+}
+
+export async function readWorkspaceFile(cwdValue: unknown, relPath: unknown): Promise<FilePreview> {
+	if (typeof relPath !== "string" || !relPath.trim()) throw new BoundaryError("missing file path");
+	const root = await resolveWorkspacePath(cwdValue);
+	const target = path.resolve(root, relPath.trim().replace(/^[/\\]+/, ""));
+	if (!isPathInside(root, target)) throw new BoundaryError("path escapes the workspace");
+	const real = await fs.realpath(target).catch(() => {
+		throw new BoundaryError("file not found");
+	});
+	if (!isPathInside(root, real)) throw new BoundaryError("path escapes the workspace");
+	const stat = await fs.stat(real);
+	if (!stat.isFile()) throw new BoundaryError("not a file");
+
+	const handle = await fs.open(real, "r");
+	const buffer = Buffer.allocUnsafe(MAX_READ_BYTES + 1);
+	let bytesRead = 0;
+	try {
+		while (bytesRead < buffer.length) {
+			const result = await handle.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+			if (result.bytesRead === 0) break;
+			bytesRead += result.bytesRead;
+		}
+	} finally {
+		await handle.close();
+	}
+	const preview = buffer.subarray(0, Math.min(bytesRead, MAX_READ_BYTES));
+	// 只检查预览范围，绝不为识别二进制而加载整个大文件
+	if (preview.includes(0)) {
+		return { path: toRel(root, real), binary: true, truncated: false, content: "" };
+	}
+	const truncated = stat.size > MAX_READ_BYTES || bytesRead > MAX_READ_BYTES;
+	return {
+		path: toRel(root, real),
+		binary: false,
+		truncated,
+		content: preview.toString("utf8"),
+	}
+}
+
+// ---------- 拖拽上传（dsh attachment-local 语义：原样字节保存，模型经路径引用） ----------
+
+/** 单文件上传上限：100 MB（与 ChatInput 本地校验一致） */
+const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+const MAX_UPLOAD_BASE64_CHARS = Math.ceil(MAX_UPLOAD_BYTES / 3) * 4;
+
+async function openUniqueUpload(name: string) {
+	const safeName = sanitizeUploadName(name);
+	const dir = path.join(getAgentDir(), "web-uploads");
+	await fs.mkdir(dir, { recursive: true });
+	const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+	for (let i = 0; i < 32; i += 1) {
+		const target = path.join(dir, `${stamp}_${i ? `${i}_` : ""}${safeName}`);
+		try {
+			return { handle: await fs.open(target, "wx"), target, safeName };
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+		}
+	}
+	throw new BoundaryError("upload filename collision limit exceeded");
+}
+
+/** 文件名净化：剥目录成分与控制字符，限长；空名给占位 */
+function sanitizeUploadName(name: string): string {
+	const base = name.replace(/[\\/\u0000-\u001f\u007f]/g, "_").trim();
+	const trimmed = base.slice(0, 120);
+	return trimmed || "upload.bin";
+}
+
+/**
+ * 保存拖入的普通文件（非图片）：原样字节落盘到 ~/.pi/agent/web-uploads/，
+ * 返回绝对路径供消息引用（agent 用 read/bash 等工具访问）。
+ */
+export async function saveUpload(name: unknown, dataBase64: unknown): Promise<{ path: string; name: string; size: number }> {
+	if (typeof name !== "string" || typeof dataBase64 !== "string" || !dataBase64) throw new BoundaryError("missing upload payload");
+	if (dataBase64.length > MAX_UPLOAD_BASE64_CHARS) throw new BoundaryError("file too large (max 100 MB)");
+	const buffer = Buffer.from(dataBase64, "base64");
+	if (buffer.length === 0) throw new BoundaryError("empty upload");
+	if (buffer.length > MAX_UPLOAD_BYTES) throw new BoundaryError("file too large (max 100 MB)");
+
+	const { handle, target, safeName } = await openUniqueUpload(name);
+	try {
+		await handle.writeFile(buffer);
+	} catch (error) {
+		await handle.close();
+		await fs.unlink(target).catch(() => undefined);
+		throw error;
+	}
+	await handle.close();
+	return { path: target, name: safeName, size: buffer.length };
+}
+
+export function parseUploadLength(value: string | null): number {
+	if (value === null || !/^\d+$/.test(value)) throw new BoundaryError("missing or invalid upload size");
+	const size = Number(value);
+	if (!Number.isSafeInteger(size) || size <= 0) throw new BoundaryError("empty or invalid upload size");
+	if (size > MAX_UPLOAD_BYTES) throw new BoundaryError("file too large (max 100 MB)");
+	return size;
+}
+
+export async function saveUploadStream(name: unknown, stream: ReadableStream<Uint8Array> | null, expectedSize?: number): Promise<{ path: string; name: string; size: number }> {
+	if (typeof name !== "string" || !name.trim() || !stream) throw new BoundaryError("missing upload payload");
+	if (expectedSize !== undefined) parseUploadLength(String(expectedSize));
+	const { handle, target, safeName } = await openUniqueUpload(name);
+	const reader = stream.getReader();
+	let size = 0;
+	let complete = false;
+	try {
+		for (;;) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			size += value.byteLength;
+			if (size > MAX_UPLOAD_BYTES) throw new BoundaryError("file too large (max 100 MB)");
+			if (expectedSize !== undefined && size > expectedSize) throw new BoundaryError("upload size does not match the declared length");
+			let offset = 0;
+			while (offset < value.byteLength) {
+				const { bytesWritten } = await handle.write(value, offset, value.byteLength - offset, null);
+				if (bytesWritten === 0) throw new Error("upload write made no progress");
+				offset += bytesWritten;
+			}
+		}
+		if (size === 0) throw new BoundaryError("empty upload");
+		if (expectedSize !== undefined && size !== expectedSize) throw new BoundaryError("incomplete upload: size does not match the declared length");
+		complete = true;
+		return { path: target, name: safeName, size };
+	} finally {
+		await reader.cancel().catch(() => undefined);
+		reader.releaseLock();
+		await handle.close();
+		if (!complete) await fs.unlink(target).catch(() => undefined);
+	}
+}
+
+/**
+ * 在本机编辑器里打开工作区文件（服务本来就跑在本机）。
+ * 默认 `code`（VS Code），可用 PI_WEB_EDITOR 覆盖（cursor / windsurf / subl / notepad …）。
+ * VS Code 系列支持 `-g 路径:行号`，其他编辑器只传路径。
+ */
+export async function openInEditor(cwdValue: unknown, relOrAbs: unknown, line?: unknown): Promise<{ editor: string; target: string }> {
+	if (typeof relOrAbs !== "string" || !relOrAbs.trim()) throw new BoundaryError("missing file path");
+	const root = await resolveWorkspacePath(cwdValue);
+	const target = path.isAbsolute(relOrAbs) ? path.resolve(relOrAbs) : path.resolve(root, relOrAbs.trim().replace(/^[/\\]+/, ""));
+	if (!isPathInside(root, target)) throw new BoundaryError("path escapes the workspace");
+	const real = await fs.realpath(target).catch(() => {
+		throw new BoundaryError("file not found");
+	});
+	if (!isPathInside(root, real)) throw new BoundaryError("path escapes the workspace");
+
+	const editor = (process.env.PI_WEB_EDITOR || "code").trim();
+	const gotoCapable = /\b(code|codium|cursor|windsurf|trae)\b/i.test(editor);
+	const lineNo = typeof line === "number" && Number.isFinite(line) && line > 0 ? Math.floor(line) : undefined;
+	const args = gotoCapable ? ["-g", lineNo ? `${real}:${lineNo}` : real] : [real];
+	if (process.platform === "win32" && !isSafeWindowsEditorArgument(`${editor}${real}`)) {
+		throw new BoundaryError("file or editor path contains characters unsafe for cmd.exe");
+	}
+
+	await new Promise<void>((resolve, reject) => {
+		// Windows 下 code 是 code.cmd，必须经 cmd.exe 启动；Node 会给带空格的参数自动加引号
+		const child = process.platform === "win32"
+			? spawn(process.env.ComSpec || "cmd.exe", ["/d", "/c", editor, ...args], { stdio: "ignore", windowsHide: true })
+			: spawn(editor, args, { stdio: "ignore", detached: true });
+		const timer = setTimeout(() => {
+			// 编辑器进程长期不退出（首次启动 GUI）也视为成功
+			resolve();
+		}, 4000);
+		child.on("error", (error) => {
+			clearTimeout(timer);
+			reject(new Error(`无法启动编辑器 "${editor}"：${error.message}`));
+		});
+		child.on("exit", (code) => {
+			clearTimeout(timer);
+			if (code === 0 || code === null) resolve();
+			else reject(new Error(`编辑器 "${editor}" 退出码 ${code}；请确认它在 PATH 中，或用 PI_WEB_EDITOR 指定`));
+		});
+		if (process.platform !== "win32") child.unref();
+	});
+	return { editor, target: real };
+}
+
+export function isSafeWindowsEditorArgument(value: string): boolean {
+	return !/[&|^<>()%!"\x00-\x1f]/.test(value);
+}

package/src/lib/git-service.ts

@@ -0,0 +1,255 @@
+/**
+ * git-service：会话工作区的 Git 状态与差异（详情栏「Git」面板）。
+ * 只读：porcelain v2 状态、最近提交、单文件差异、单次提交内容；不做任何写操作。
+ * 所有 git 命令以仓库根为 cwd 运行，因为 porcelain 输出的路径都相对仓库根。
+ */
+import { execFile } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { BoundaryError, isPathInside, resolveWorkspacePath } from "./path-security";
+
+const exec = promisify(execFile);
+
+export interface GitFileEntry {
+	path: string;
+	/** 暂存区状态字母（" " 表示无） */
+	indexStatus: string;
+	/** 工作区状态字母（" " 表示无） */
+	workStatus: string;
+	kind: "modified" | "added" | "deleted" | "renamed" | "untracked" | "conflict";
+}
+
+export interface GitCommit {
+	hash: string;
+	subject: string;
+	author: string;
+	/** git 的相对时间（"2 hours ago"） */
+	relative: string;
+}
+
+export interface GitInfo {
+	/** 机器上找不到 git 命令 */
+	available: boolean;
+	isRepo: boolean;
+	/** 仓库根（用于把面板里的相对路径映射回文件面板） */
+	root: string | null;
+	branch: string | null;
+	upstream: string | null;
+	ahead: number;
+	behind: number;
+	detached: boolean;
+	files: GitFileEntry[];
+	/** 状态读取失败时文件变更未知；不能把空 files 解读为工作区干净。 */
+	statusError?: string;
+	commits: GitCommit[];
+}
+
+const EMPTY: GitInfo = {
+	available: true,
+	isRepo: false,
+	root: null,
+	branch: null,
+	upstream: null,
+	ahead: 0,
+	behind: 0,
+	detached: false,
+	files: [],
+	commits: [],
+};
+
+/** 单次差异输出上限：超过则截断并标记（详情栏不是完整的 diff 工具） */
+const MAX_DIFF_BYTES = 400 * 1024;
+
+function runGit(cwd: string, args: string[], maxBuffer = 4 * 1024 * 1024): Promise<string> {
+	return exec("git", args, { cwd, timeout: 15_000, maxBuffer, windowsHide: true, env: { ...process.env, GIT_OPTIONAL_LOCKS: "0", GIT_TERMINAL_PROMPT: "0" } }).then((r) => r.stdout);
+}
+
+function kindOf(x: string, y: string): GitFileEntry["kind"] {
+	if (x === "U" || y === "U" || (x === "A" && y === "A") || (x === "D" && y === "D")) return "conflict";
+	const letter = x !== "." ? x : y;
+	if (letter === "A") return "added";
+	if (letter === "D") return "deleted";
+	if (letter === "R" || letter === "C") return "renamed";
+	return "modified";
+}
+
+async function repoRoot(cwd: string): Promise<{ available: boolean; root: string | null }> {
+	try {
+		const out = (await runGit(cwd, ["rev-parse", "--show-toplevel"])).trim();
+		return { available: true, root: out ? path.resolve(out) : null };
+	} catch (error) {
+		const code = (error as NodeJS.ErrnoException).code;
+		if (code === "ENOENT") return { available: false, root: null };
+		// exit 128：不是仓库
+		return { available: true, root: null };
+	}
+}
+
+export async function gitInfo(cwdValue: unknown): Promise<GitInfo> {
+	const cwd = await resolveWorkspacePath(cwdValue);
+	const { available, root } = await repoRoot(cwd);
+	if (!available) return { ...EMPTY, available: false };
+	if (!root) return EMPTY;
+
+	let branch: string | null = null;
+	let upstream: string | null = null;
+	let ahead = 0;
+	let behind = 0;
+	let detached = false;
+	let statusError: string | undefined;
+	const files: GitFileEntry[] = [];
+	try {
+		// porcelain v2 是结构化输出，不依赖 "No branch" 这类措辞；-z 让含空格/非 ASCII 的路径也稳定
+		const status = await runGit(root, ["status", "--porcelain=v2", "--branch", "-z"]);
+		const records = status.split("\0");
+		for (let i = 0; i < records.length; i += 1) {
+			const line = records[i];
+			if (!line) continue;
+			if (line.startsWith("# branch.head ")) {
+				const head = line.slice("# branch.head ".length);
+				if (head === "(detached)") detached = true;
+				else branch = head;
+				continue;
+			}
+			if (line.startsWith("# branch.upstream ")) {
+				upstream = line.slice("# branch.upstream ".length);
+				continue;
+			}
+			if (line.startsWith("# branch.ab ")) {
+				const m = line.match(/\+(\d+) -(\d+)/);
+				if (m) {
+					ahead = Number(m[1]);
+					behind = Number(m[2]);
+				}
+				continue;
+			}
+			if (line.startsWith("# ")) continue;
+			const type = line[0];
+			if (type === "?") {
+				files.push({ path: line.slice(2), indexStatus: " ", workStatus: "?", kind: "untracked" });
+				continue;
+			}
+			if (type === "!") continue;
+			if (type === "1" || type === "2" || type === "u") {
+				const parts = line.split(" ");
+				const xy = parts[1] ?? "..";
+				const x = xy[0] ?? ".";
+				const y = xy[1] ?? ".";
+				// 1: <XY> <sub> <mH> <mI> <mW> <hH> <hI> <path>
+				// 2: <XY> <sub> <mH> <mI> <mW> <hH> <hI> <X><score> <path>  （NUL 后跟原路径，占下一条记录）
+				// u: <XY> <sub> <m1> <m2> <m3> <mW> <h1> <h2> <h3> <path>
+				const pathIndex = type === "1" ? 8 : type === "2" ? 9 : 10;
+				const filePath = parts.slice(pathIndex).join(" ");
+				if (type === "2") i += 1; // 跳过 rename 的原路径记录
+				if (!filePath) continue;
+				files.push({
+					path: filePath,
+					indexStatus: x === "." ? " " : x,
+					workStatus: y === "." ? " " : y,
+					kind: kindOf(x, y),
+				});
+			}
+		}
+	} catch (error) {
+		// 分支与提交可继续展示，但文件状态未知，绝不能回退为「工作区干净」。
+		const stderr = (error as { stderr?: unknown })?.stderr;
+		statusError = (typeof stderr === "string" ? stderr.trim() : error instanceof Error ? error.message : String(error)) || "git status failed";
+	}
+
+	let commits: GitCommit[] = [];
+	try {
+		const log = await runGit(root, ["log", "-10", "--pretty=%h%x1f%s%x1f%an%x1f%cr"]);
+		commits = log
+			.split("\n")
+			.filter(Boolean)
+			.map((line) => {
+				const [hash, subject, author, relative] = line.split("");
+				return { hash, subject: subject ?? "", author: author ?? "", relative: relative ?? "" };
+			});
+	} catch {
+		// 空仓库没有提交
+	}
+
+	if (branch === null && !detached) {
+		try {
+			branch = (await runGit(root, ["rev-parse", "--abbrev-ref", "HEAD"])).trim() || null;
+		} catch {
+			/* keep null */
+		}
+	}
+	return { available: true, isRepo: true, root, branch, upstream, ahead, behind, detached, files, commits, ...(statusError ? { statusError } : {}) };
+}
+
+export interface GitDiffResult {
+	patch: string;
+	truncated: boolean;
+	binary: boolean;
+}
+
+function truncate(patch: string): GitDiffResult {
+	if (Buffer.byteLength(patch) <= MAX_DIFF_BYTES) return { patch, truncated: false, binary: false };
+	return { patch: Buffer.from(patch).subarray(0, MAX_DIFF_BYTES).toString("utf8"), truncated: true, binary: false };
+}
+
+function assertRepoRelative(root: string, relPath: unknown): string {
+	if (typeof relPath !== "string" || !relPath.trim()) throw new BoundaryError("missing path");
+	const abs = path.resolve(root, relPath);
+	if (!isPathInside(root, abs)) throw new BoundaryError("path escapes the repository");
+	return abs;
+}
+
+/** 单文件差异：staged（索引 vs HEAD）、worktree（工作区 vs 索引）、untracked（整文件视为新增） */
+export async function gitDiff(cwdValue: unknown, relPath: unknown, mode: unknown): Promise<GitDiffResult> {
+	const cwd = await resolveWorkspacePath(cwdValue);
+	const { available, root } = await repoRoot(cwd);
+	if (!available || !root) throw new BoundaryError("not a git repository");
+	const abs = assertRepoRelative(root, relPath);
+	const rel = path.relative(root, abs).replace(/\\/g, "/");
+	if (mode === "untracked") {
+		// 未跟踪文件：合成一个全新增的 patch，让前端用同一套 diff 视图展示
+		const realRoot = await fs.realpath(root);
+		const realFile = await fs.realpath(abs).catch(() => { throw new BoundaryError("file not found"); });
+		if (!isPathInside(realRoot, realFile)) throw new BoundaryError("path escapes the repository");
+		const stat = await fs.stat(realFile).catch(() => null);
+		if (!stat?.isFile()) throw new BoundaryError("file not found");
+		const buffer = Buffer.alloc(Math.min(stat.size, MAX_DIFF_BYTES + 1));
+		const handle = await fs.open(realFile, "r");
+		let bytesRead = 0;
+		try {
+			while (bytesRead < buffer.length) {
+				const read = await handle.read(buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+				if (read.bytesRead === 0) break;
+				bytesRead += read.bytesRead;
+			}
+		} finally {
+			await handle.close();
+		}
+		const head = buffer.subarray(0, bytesRead);
+		if (head.includes(0)) return { patch: "", truncated: false, binary: true };
+		const text = head.subarray(0, MAX_DIFF_BYTES).toString("utf8").replace(/\r/g, "");
+		const lines = text.split("\n");
+		if (lines[lines.length - 1] === "") lines.pop();
+		const body = lines.map((l) => `+${l}`).join("\n");
+		return {
+			patch: `--- /dev/null\n+++ b/${rel}\n@@ -0,0 +1,${lines.length} @@\n${body}\n`,
+			truncated: stat.size > MAX_DIFF_BYTES,
+			binary: false,
+		};
+	}
+	const args = mode === "staged" ? ["diff", "--cached", "--no-color", "--", rel] : ["diff", "--no-color", "--", rel];
+	const out = await runGit(root, args, 8 * 1024 * 1024);
+	if (/^Binary files .* differ$/m.test(out)) return { patch: "", truncated: false, binary: true };
+	return truncate(out);
+}
+
+/** 单次提交的内容（含各文件 patch） */
+export async function gitShow(cwdValue: unknown, hash: unknown): Promise<GitDiffResult & { title: string }> {
+	const cwd = await resolveWorkspacePath(cwdValue);
+	const { available, root } = await repoRoot(cwd);
+	if (!available || !root) throw new BoundaryError("not a git repository");
+	if (typeof hash !== "string" || !/^[0-9a-f]{4,40}$/i.test(hash)) throw new BoundaryError("invalid commit hash");
+	const title = (await runGit(root, ["log", "-1", "--pretty=%h %s%n%an · %cr", hash])).trim();
+	const out = await runGit(root, ["show", "--no-color", "--format=", "--patch", hash], 8 * 1024 * 1024);
+	return { title, ...truncate(out) };
+}

package/src/lib/growth-rounds.ts

@@ -0,0 +1,84 @@
+import type { GrowthStep } from "./types";
+
+export interface GrowthRound {
+	/** 真实用户轮次；不会因没有文件改动而跳号。 */
+	id: number;
+	startedAt: number;
+	first: GrowthStep | null;
+	/** 此轮结束时可用的最后一张快照；无改动轮沿用前一张。 */
+	last: GrowthStep | null;
+	steps: GrowthStep[];
+	/** 相邻两轮终点的 tree；第一轮从 prompt 前的基线开始。 */
+	fromTree: string | null;
+	toTree: string | null;
+	/** 旧会话可能在启用生长账本前已发生，不能假装它是零改动。 */
+	recorded: boolean;
+}
+
+/** 兼容没有消息时间戳的调用者：按账本里的 turn 标记分组。 */
+function ledgerRounds(steps: GrowthStep[]): GrowthRound[] {
+	const rounds: GrowthRound[] = [];
+	let current: GrowthStep[] = [];
+	const flush = () => {
+		if (!current.length) return;
+		const first = current[0];
+		const last = current[current.length - 1];
+		rounds.push({ id: rounds.length + 1, startedAt: first.ts, first, last, steps: current, fromTree: first.parent, toTree: last.tree, recorded: true });
+		current = [];
+	};
+	for (const [index, step] of steps.entries()) {
+		if (index === 0 && step.initial) continue;
+		if (step.kind === "baseline") {
+			flush();
+			continue;
+		}
+		if (step.kind === "external" || step.kind === "manual") flush();
+		current.push(step);
+		if (step.kind === "turn" || step.kind === "external" || step.kind === "manual") flush();
+	}
+	flush();
+	return rounds;
+}
+
+/** 轮数以持久会话的用户消息为准；快照只负责证明这一轮的前后树与差异。 */
+export function buildGrowthRounds(steps: GrowthStep[], turnStarts?: number[]): GrowthRound[] {
+	if (turnStarts === undefined) return ledgerRounds(steps);
+	if (!turnStarts.length) return [];
+	const starts: number[] = [];
+	for (const value of turnStarts) {
+		const previous = starts[starts.length - 1];
+		starts.push(Number.isFinite(value) ? Math.max(value, previous === undefined ? value : previous + 0.001) : (previous ?? 0) + 0.001);
+	}
+	const ordered = [...steps].sort((a, b) => a.ts - b.ts || a.seq - b.seq);
+	const rounds: GrowthRound[] = [];
+	let cursor = 0;
+	let before: GrowthStep | null = null;
+	let previousEnd: GrowthStep | null = null;
+	for (let index = 0; index < starts.length; index += 1) {
+		const start = starts[index];
+		const end = starts[index + 1] ?? Infinity;
+		while (cursor < ordered.length && ordered[cursor].ts < start) before = ordered[cursor++];
+		const atStart = before;
+		const current: GrowthStep[] = [];
+		while (cursor < ordered.length && ordered[cursor].ts < end) {
+			const step = ordered[cursor++];
+			if (step.kind !== "baseline") current.push(step);
+			before = step;
+		}
+		const first = current[0] ?? null;
+		const last: GrowthStep | null = current[current.length - 1] ?? (atStart && (!previousEnd || atStart.ts > previousEnd.ts) ? atStart : previousEnd);
+		const fromTree = previousEnd?.tree ?? atStart?.tree ?? first?.parent ?? null;
+		rounds.push({
+			id: index + 1,
+			startedAt: start,
+			first,
+			last,
+			steps: current,
+			fromTree,
+			toTree: last?.tree ?? null,
+			recorded: current.length > 0 && fromTree !== null && !first?.initial,
+		});
+		previousEnd = last;
+	}
+	return rounds;
+}