@rexvane/piweb 0.3.18 → 0.3.20

package/scripts/launcher.mjs

@@ -2,6 +2,7 @@ import net from "node:net";
 import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
+import { randomBytes } from "node:crypto";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { assertInstallation, selectProductionBuild } from "./build-output.mjs";
@@ -11,7 +12,7 @@ export { isMainModule } from "./entrypoint.mjs";
 const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 /** @typedef {Record<string, string | undefined>} Environment */
-/** @typedef {{port: number, hostname: string, noOpen: boolean, isDev: boolean, help: boolean}} ParsedOptions */
+/** @typedef {{port: number, hostname: string, publicUrl: string | null, noOpen: boolean, isDev: boolean, help: boolean}} ParsedOptions */
 /** @typedef {import('node:events').EventEmitter & {kill(signal?: NodeJS.Signals | number): boolean}} LauncherChild */
 /**
  * @typedef {Object} LauncherOptions
@@ -20,6 +21,7 @@ const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)),
  * @property {string} [root]
  * @property {{log?: (message: string) => void, probePort?: typeof probePort,
  * isPiWebRunning?: typeof isPiWebRunning, openBrowser?: (url: string) => Promise<void>,
+ * warmFirstPaint?: typeof warmFirstPaint, readLaunchToken?: typeof readLaunchToken,
  * spawn?: (command: string, args: string[], options: import('node:child_process').SpawnOptions) => LauncherChild}} [dependencies]
  */
 
@@ -40,10 +42,78 @@ function normalizeHostname(value) {
 	return host;
 }
 
+/**
+ * 对外地址（反代/隧道给用户看的那个 URL）。只用于拼登录链接和补 Host 白名单。
+ * 去掉查询串与结尾斜杠，拼接时统一补。
+ * @param {string | null | undefined} value
+ * @returns {string | null}
+ */
+export function normalizePublicUrl(value) {
+	if (value === null || value === undefined) return null;
+	const trimmed = String(value).trim();
+	if (!trimmed) return null;
+	let url;
+	try {
+		url = new URL(trimmed);
+	} catch {
+		throw new Error(`无效的对外地址：${value}`);
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") throw new Error(`对外地址必须是 http/https：${value}`);
+	if (url.username || url.password) throw new Error(`对外地址不能带凭据：${value}`);
+	url.search = "";
+	url.hash = "";
+	return url.href.replace(/\/+$/, "");
+}
+
+/** 把令牌拼成可直接打开的登录链接 */
+export function tokenLoginUrl(base, token) {
+	return `${String(base).replace(/\/+$/, "")}/?token=${encodeURIComponent(token)}`;
+}
+
+/**
+ * 读某个端口上正在运行的实例留下的启动令牌（服务端 publishLaunchToken 写的，
+ * 位置是 `<agentDir>/web-launch/<端口>.token`，agentDir 规则与 src/lib/web-secret.ts 一致）。
+ * 没有、读不了、内容不像令牌都返回 null —— 调用方退回打开裸地址。
+ * @param {number} port
+ * @param {Environment} [env]
+ * @returns {string | null}
+ */
+export function readLaunchToken(port, env = process.env) {
+	const raw = env.PI_CODING_AGENT_DIR;
+	const home = os.homedir();
+	const dir = !raw ? path.join(home, ".pi", "agent")
+		: raw === "~" ? home
+		: raw.startsWith("~/") || raw.startsWith("~\\") ? path.join(home, raw.slice(2))
+		: raw;
+	try {
+		const token = fs.readFileSync(path.join(dir, "web-launch", `${port}.token`), "utf8").trim();
+		return /^[A-Za-z0-9_-]{16,}$/.test(token) ? token : null;
+	} catch {
+		return null;
+	}
+}
+
+function mergeHostnames(current, hostname) {
+	const list = (current ?? "").split(",").map((part) => part.trim().toLowerCase()).filter(Boolean);
+	if (hostname && !list.includes(hostname)) list.push(hostname);
+	return list.join(",");
+}
+
+function isTruthyFlag(value) {
+	const flag = (value ?? "").trim().toLowerCase();
+	return flag === "1" || flag === "true" || flag === "on" || flag === "yes";
+}
+
+function isOffFlag(value) {
+	const flag = (value ?? "").trim().toLowerCase();
+	return flag === "0" || flag === "false" || flag === "off" || flag === "no";
+}
+
 /** @param {string[]} [args] @param {Environment} [env] @returns {ParsedOptions} */
 export function parseLauncherArgs(args = [], env = process.env) {
 	let port = Number(env.PORT || 30141);
 	let hostname = env.PI_WEB_HOSTNAME || "127.0.0.1";
+	let publicUrl = env.PI_WEB_PUBLIC_URL ?? null;
 	let noOpen = env.PI_WEB_NO_OPEN === "1";
 	let isDev = env.PI_WEB_DEV === "1";
 	let help = false;
@@ -53,13 +123,15 @@ export function parseLauncherArgs(args = [], env = process.env) {
 		else if (arg.startsWith("--port=")) port = Number(arg.slice(7));
 		else if (arg === "-H" || arg === "--hostname") hostname = args[++i];
 		else if (arg.startsWith("--hostname=")) hostname = arg.slice(11);
+		else if (arg === "--public-url") publicUrl = args[++i];
+		else if (arg.startsWith("--public-url=")) publicUrl = arg.slice(13);
 		else if (arg === "--no-open") noOpen = true;
 		else if (arg === "--dev") isDev = true;
 		else if (arg === "-h" || arg === "--help") help = true;
 		else throw new Error(`未知参数：${arg}`);
 	}
 	if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`无效端口：${port}`);
-	return { port, hostname: normalizeHostname(hostname), noOpen, isDev, help };
+	return { port, hostname: normalizeHostname(hostname), publicUrl: normalizePublicUrl(publicUrl), noOpen, isDev, help };
 }
 
 /**
@@ -69,23 +141,40 @@ export function parseLauncherArgs(args = [], env = process.env) {
  * @returns {{root: string, command: 'dev' | 'start', env: Environment}}
  */
 export function createLaunchPlan(root, options, env = process.env) {
+	// 拒绝启动而不是静默忽略：设了 PI_WEB_PASSWORD 的部署本来是有认证的，
+	// 悄悄放过就会让它在没有任何登录要求的情况下继续对外服务。
+	if (env.PI_WEB_PASSWORD) {
+		throw new Error("PI_WEB_PASSWORD 已被移除：密码登录不再存在，认证现在只用启动令牌（PI_WEB_AUTH=1，启动器默认已开）。请删掉这个环境变量再重试。");
+	}
 	const loopback = isLoopback(options.hostname);
 	if (!loopback && options.isDev) {
-		throw new Error("拒绝非本机开发模式：PI_WEB_PASSWORD 不能保护 Next 开发工具端点。请绑定 127.0.0.1，或先运行 npm run build:release 后用生产模式启动。");
+		throw new Error("拒绝非本机开发模式：启动令牌认证保护不了 Next 开发工具端点。请绑定 127.0.0.1，或先运行 npm run build:release 后用生产模式启动。");
 	}
-	if (!loopback && !env.PI_WEB_PASSWORD) throw new Error("拒绝无密码的非本机监听。请设置 PI_WEB_PASSWORD，或绑定 127.0.0.1。");
+	const publicUrl = options.publicUrl ?? null;
 	const installation = assertInstallation(root);
 	const build = options.isDev ? null : selectProductionBuild(installation, env.PIWEB_BUILD_DIR);
 	if (!build && !loopback) {
 		throw new Error("找不到可用生产构建，拒绝对外自动回退到开发模式。请先运行 npm run build:release，再以相同启动参数重试。");
 	}
 	const command = options.isDev || !build ? "dev" : "start";
+	// 局域网入口（「远程连接」内置插件）默认开着，等于这台机器同网段可达；
+	// 非本机监听、配了对外地址同样算暴露面。三种情况都必须有认证。
+	// 开发模式下局域网入口根本不会起（instrumentation 会跳过），不算暴露面。
+	const lanEntry = command !== "dev" && !isOffFlag(env.PIWEB_REMOTE_LAN);
+	const exposed = !loopback || Boolean(publicUrl) || lanEntry;
 	const childEnv = {
 		...env,
 		PI_WEB_ROOT: installation,
 		PYTHONUTF8: env.PYTHONUTF8 ?? "1",
 		PYTHONIOENCODING: env.PYTHONIOENCODING ?? "utf-8",
 	};
+	// 每次启动换一个启动令牌；调用方已经给出就沿用（便于测试与外部编排）。
+	if (!childEnv.PI_WEB_LAUNCH_TOKEN) childEnv.PI_WEB_LAUNCH_TOKEN = randomBytes(32).toString("base64url");
+	// 有暴露面 + 用户没表态 → 自动打开启动令牌认证，而不是拒绝启动。
+	// 只在用户没表态时才替它打开：显式 PI_WEB_AUTH=0 会被尊重（此时局域网入口也会自行跳过）。
+	if (exposed && !String(childEnv.PI_WEB_AUTH ?? "").trim()) childEnv.PI_WEB_AUTH = "1";
+	// 反代会把外部主机名原样转给后端，不进白名单会被判 untrusted host。
+	if (publicUrl) childEnv.PI_WEB_TRUSTED_HOSTS = mergeHostnames(childEnv.PI_WEB_TRUSTED_HOSTS, new URL(publicUrl).hostname.toLowerCase());
 	if (command === "start") childEnv.PIWEB_BUILD_DIR = build.buildDir;
 	else {
 		delete childEnv.PIWEB_BUILD_DIR;
@@ -142,6 +231,70 @@ export async function isPiWebRunning(base, { fetchImpl = fetch, timeoutMs = 1500
 	}
 }
 
+/** 预热要打的四个首屏路由（会话列表 / 工作区 / 模型目录 / pi 设置） */
+export const FIRST_PAINT_ROUTES = ["/api/sessions", "/api/workspaces", "/api/models", "/api/pi-settings"];
+
+/** @param {number} ms @param {AbortSignal} [signal] */
+function delay(ms, signal) {
+	return new Promise((resolve) => {
+		const timer = setTimeout(resolve, ms);
+		timer.unref?.();
+		signal?.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+	});
+}
+
+/**
+ * 首屏预热：生产模式下，Next 服务器对**第一个动态 API 请求**要一次性付出 2.4~3.3 秒的
+ * 模块加载成本（本机实测：`/api/version` 首次 2559~3566ms、第二次 4~10ms；页面路由与
+ * `/api/health` 不吃这笔账）。浏览器首屏正好撞在这笔成本上，于是"页面出来了、列表还在转圈"。
+ *
+ * 这里在子进程刚起来时就后台打一次最便宜的路由吃掉它，再预热首屏真正要用的四个路由。
+ * 只等端口起来 + 身份确认，绝不阻塞启动；失败一律静默（预热属于优化，不是启动的前置条件）。
+ *
+ * @param {string} base
+ * @param {{fetchImpl?: typeof fetch, token?: string, timeoutMs?: number, waitMs?: number,
+ * pollMs?: number, check?: typeof isPiWebRunning, signal?: AbortSignal}} [options]
+ * @returns {Promise<boolean>} 是否完成了管线预热
+ */
+export async function warmFirstPaint(base, { fetchImpl = fetch, token, timeoutMs = 20_000, waitMs = 60_000, pollMs = 100, check = isPiWebRunning, signal } = {}) {
+	const timeoutFor = () => (signal ? AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]) : AbortSignal.timeout(timeoutMs));
+	// 身份确认不带凭据（与 isPiWebRunning 的既有约定一致）：端口可能被别的进程抢走。
+	const deadline = Date.now() + waitMs;
+	for (;;) {
+		if (signal?.aborted) return false;
+		if (await check(base, { fetchImpl, timeoutMs: Math.min(1500, timeoutMs), signal })) break;
+		if (Date.now() >= deadline) return false;
+		await delay(pollMs, signal);
+	}
+	// 令牌只认根路径的 GET：先换到 Cookie，后面几条路由才有资格预热。
+	let cookie;
+	if (token) {
+		try {
+			const response = await fetchImpl(new URL(tokenLoginUrl("/", token), base), { credentials: "omit", redirect: "manual", signal: timeoutFor() });
+			const match = /^([^;]+)/.exec(response.headers.get("set-cookie") ?? "");
+			if (match) cookie = match[1];
+			await response.arrayBuffer().catch(() => undefined);
+		} catch {
+			/* 换不到就退化成只预热公开路由 */
+		}
+	}
+	const headers = {};
+	if (cookie) headers.cookie = cookie;
+	const headerInit = Object.keys(headers).length > 0 ? headers : undefined;
+	const get = async (route) => {
+		try {
+			const response = await fetchImpl(new URL(route, base), { credentials: "omit", redirect: "error", headers: headerInit, signal: timeoutFor() });
+			// 只需让服务端把这条路由跑完；响应体要么丢弃，要么读干净以释放连接。
+			await response.arrayBuffer().catch(() => undefined);
+		} catch {
+			/* 预热失败不影响启动 */
+		}
+	};
+	await get("/api/version");
+	for (const route of FIRST_PAINT_ROUTES) void get(route);
+	return true;
+}
+
 /** @param {number} port @param {string} hostname @returns {Promise<'busy' | 'free' | NodeJS.ErrnoException>} */
 export function probePort(port, hostname) {
 	return new Promise((resolve) => {
@@ -169,9 +322,10 @@ export async function runLauncher({ args = process.argv.slice(2), env = process.
 	const options = parseLauncherArgs(args, env);
 	const log = dependencies.log ?? console.log;
 	if (options.help) {
-		log("Usage: pi web [-p, --port <port>] [-H, --hostname <host>] [--dev] [--no-open]");
+		log("Usage: pi web [-p, --port <port>] [-H, --hostname <host>] [--public-url <url>] [--dev] [--no-open]");
 		log("默认绑定 127.0.0.1:30141；端口被占自动 +1。开发模式仅允许本机监听。");
-		log("对外监听必须使用生产构建与 PI_WEB_PASSWORD。构建/恢复发布：npm run build:release。");
+		log("非本机监听、或配了 --public-url，都会自动启用启动令牌认证（PI_WEB_AUTH=1）。");
+		log("对外监听必须使用生产构建。构建/恢复发布：npm run build:release。");
 		return 0;
 	}
 	// Validate before probing/reusing: an existing server must not hide an unsafe request.
@@ -183,7 +337,7 @@ export async function runLauncher({ args = process.argv.slice(2), env = process.
 			// 常见根因：包目录属主不是当前用户（sudo 安装残留），构建产物写不进去
 			let owner = "";
 			try {
-				const stat = await fs.stat(root);
+				const stat = fs.statSync(root);
 				if (typeof stat.uid === "number" && stat.uid !== process.getuid?.()) {
 					owner = `\n此安装目录属主不是当前用户（uid ${stat.uid}）——之前可能用 sudo 安装过。修复：sudo chown -R $(whoami) "${root}"，然后重试 piweb。`;
 				}
@@ -204,7 +358,12 @@ export async function runLauncher({ args = process.argv.slice(2), env = process.
 		const url = localUrl(options.hostname, port);
 		if (await checkHealth(url)) {
 			log(`[piweb] 检测到已有 PiWeb：${url}（未发送凭据）`);
-			if (!options.noOpen) await browse(url);
+			if (!options.noOpen) {
+				// 那个实例开了认证的话，裸地址只会落到登录页，而这里手里没有它的令牌；
+				// 它启动时留下过令牌就直接开登录链接（浏览器里已有 Cookie 时令牌也无害）
+				const token = (dependencies.readLaunchToken ?? readLaunchToken)(port, env);
+				await browse(token ? tokenLoginUrl(url, token) : url);
+			}
 			return 0;
 		}
 		if (attempts >= 50 || port >= 65535) throw new Error(`连续 ${attempts + 1} 个端口都被占用，请用 -p 指定端口`);
@@ -212,31 +371,53 @@ export async function runLauncher({ args = process.argv.slice(2), env = process.
 		port += 1;
 	}
 	const url = localUrl(options.hostname, port);
+	// 内置插件要转发回 PiWeb 自己的端口；端口可能被占而 +1，所以在这里给最终值。
+	plan.env.PIWEB_PORT = String(port);
 	log(`[piweb] 启动 ${url} (${plan.command} 模式)`);
-	if (env.PI_WEB_PASSWORD) log(plan.command === "dev" ? "[piweb] 开发模式仅限本机；密码不保护 Next 开发工具端点。" : "[piweb] 已启用密码认证（浏览器登录页，API 兼容 Basic 用户名 pi）");
+	const authOn = isTruthyFlag(plan.env.PI_WEB_AUTH);
+	if (authOn) log("[piweb] 已启用启动令牌认证");
 	if (!isLoopback(options.hostname)) {
 		for (const addresses of Object.values(os.networkInterfaces())) {
 			for (const address of addresses ?? []) {
 				if (address.family === "IPv4" && !address.internal && !address.address.startsWith("169.254.")) {
-					log(`[piweb] 局域网/手机访问地址（需同一网络；已启用密码认证）：http://${address.address}:${port}`);
+					log(`[piweb] 局域网/手机访问地址（需同一网络）：http://${address.address}:${port}`);
 				}
 			}
 		}
 	}
+	// 令牌即凭据：只往终端打印，不写日志文件，也不要贴到聊天或截图里。
+	const loginBase = options.publicUrl ?? url;
+	const loginUrl = tokenLoginUrl(loginBase, plan.env.PI_WEB_LAUNCH_TOKEN);
+	if (authOn) {
+		if (options.publicUrl) log(`[piweb] 对外地址：${options.publicUrl}`);
+		log(`[piweb] 登录链接（令牌即凭据，别外传；它会进浏览器历史）：${loginUrl}`);
+	}
 	const next = path.join(plan.root, "node_modules", "next", "dist", "bin", "next");
 	const child = start(process.execPath, [next, plan.command, ...(plan.command === "dev" ? ["--webpack"] : []), "-p", String(port), "-H", options.hostname], {
 		cwd: plan.root, stdio: "inherit", env: plan.env,
 	});
 	const controller = new AbortController();
 	let timer;
+	// 首屏预热：开发模式每次请求都要现场编译，预热只会白占 CPU，因此只在生产模式下做。
+	let warmPromise = null;
+	if (plan.command !== "dev" && env.PIWEB_SKIP_WARMUP !== "1") {
+		const warm = dependencies.warmFirstPaint ?? warmFirstPaint;
+		warmPromise = Promise.resolve(warm(url, { token: authOn ? plan.env.PI_WEB_LAUNCH_TOKEN : undefined, signal: controller.signal })).then(() => true, () => false);
+	}
 	const ready = async (attempt = 0) => {
-		if (controller.signal.aborted || attempt > 120) return;
+		if (controller.signal.aborted || attempt > 240) return;
 		if (await checkHealth(url, { signal: controller.signal })) {
 			if (controller.signal.aborted) return;
+			if (warmPromise) {
+				log("[piweb] 预热首屏…");
+				await warmPromise;
+				if (controller.signal.aborted) return;
+			}
 			log(`[piweb] 就绪：${url}`);
-			if (!options.noOpen) await browse(url);
+			// 开了认证就直接开登录链接：否则用户打开的是登录页，而他手里还没有会话 Cookie。
+			if (!options.noOpen) await browse(authOn ? loginUrl : url);
 		} else if (!controller.signal.aborted) {
-			timer = setTimeout(() => void ready(attempt + 1), 500);
+			timer = setTimeout(() => void ready(attempt + 1), 250);
 			timer.unref();
 		}
 	};

package/scripts/release.mjs

@@ -141,8 +141,6 @@ export async function prepareRelease({ root = ROOT, env = process.env, run = run
 			...env, PI_WEB_ROOT: installation, PIWEB_BUILD_DIR: buildDir,
 			PYTHONUTF8: env.PYTHONUTF8 ?? "1", PYTHONIOENCODING: env.PYTHONIOENCODING ?? "utf-8",
 		};
-		// Do not pass the live web password to Git/npm/package build scripts.
-		delete childEnv.PI_WEB_PASSWORD;
 		delete childEnv.PI_WEB_DEV;
 		delete childEnv.NODE_ENV;
 		const context = { root: installation, buildDir, env: childEnv, run, signal };

package/src/app/api/agent/[id]/events/route.ts

@@ -1,4 +1,4 @@
-import { buildSnapshot, getManaged, subscribe, unsubscribe } from "@/lib/agent-manager";
+import { buildSnapshot, getManaged, parseLastEventId, sseEventId, subscribe, unsubscribe } from "@/lib/agent-manager";
 import { BoundaryError, resolveSessionPath } from "@/lib/path-security";
 
 export const dynamic = "force-dynamic";
@@ -14,10 +14,15 @@ export async function GET(req: Request, { params }: { params: Promise<{ id: stri
 	} catch (error) {
 		return new Response(error instanceof BoundaryError ? error.message : "invalid session", { status: 400 });
 	}
-	const m = getManaged(sessionPath);
-	const rawLastEventId = req.headers.get("last-event-id");
-	const parsedLastEventId = rawLastEventId === null ? undefined : Number.parseInt(rawLastEventId, 10);
-	const lastEventId = Number.isSafeInteger(parsedLastEventId) && (parsedLastEventId ?? -1) >= 0 ? parsedLastEventId : undefined;
+	let m: ReturnType<typeof getManaged>;
+	try {
+		m = getManaged(sessionPath);
+	} catch (error) {
+		// 待落盘的会话在服务重启后就不存在了：给明确的 404，而不是未捕获异常的 500
+		return new Response(error instanceof BoundaryError ? error.message : "session unavailable", { status: error instanceof BoundaryError ? 404 : 500 });
+	}
+	// id 带着这份会话的 epoch：服务重启或会话被回收重开后，旧的 Last-Event-ID 不会被误续到新一轮事件上
+	const lastEventId = parseLastEventId(m, req.headers.get("last-event-id"));
 
 	const encoder = new TextEncoder();
 	let closed = false;
@@ -41,7 +46,7 @@ export async function GET(req: Request, { params }: { params: Promise<{ id: stri
 				}
 			};
 			subscriber = (seq: number, json: string) => {
-				write(`id: ${seq}\ndata: ${json}\n\n`);
+				write(`id: ${sseEventId(m, seq)}\ndata: ${json}\n\n`);
 				if (json.includes('"state":"disposed"')) close();
 			};
 			const send = subscriber;

package/src/app/api/fs/route.ts

@@ -0,0 +1,119 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { NextResponse } from "next/server";
+import { BoundaryError } from "@/lib/path-security";
+
+export const dynamic = "force-dynamic";
+
+/**
+ * 只读的目录枚举，供应用内的工作区选择器用（手机等远程设备）。
+ *
+ * 只列目录、不读内容：选择器的产出是一个路径，随后仍由 resolveWorkspacePath 校验
+ * （必须绝对路径、必须存在、必须是目录）才写进工作区注册表。
+ */
+
+/** 单个目录最多返回多少条，避免在手机上拉一个几万项的目录 */
+const MAX_ENTRIES = 2000;
+
+interface FsEntry {
+	name: string;
+	path: string;
+}
+
+async function isDirectory(target: string): Promise<boolean> {
+	try {
+		return (await fs.stat(target)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+
+/** 设备的起点：Windows 逐个探测盘符，macOS 列 /Volumes，其余从主目录与根开始 */
+async function listRoots(): Promise<FsEntry[]> {
+	const roots: FsEntry[] = [];
+	if (process.platform === "win32") {
+		// 26 个盘符一起探：断开的网络盘、没插卡的读卡器一个就能卡上几秒，逐个探会把等待叠加起来
+		const drives = Array.from({ length: 26 }, (_, i) => `${String.fromCharCode(65 + i)}:\\`);
+		const present = await Promise.all(drives.map(isDirectory));
+		return drives.filter((_, i) => present[i]).map((drive) => ({ name: drive, path: drive }));
+	}
+	if (process.platform === "darwin") {
+		const volumes = await fs.readdir("/Volumes", { withFileTypes: true }).catch(() => []);
+		for (const entry of volumes) {
+			if (entry.isDirectory() || entry.isSymbolicLink()) roots.push({ name: entry.name, path: path.join("/Volumes", entry.name) });
+		}
+	}
+	const home = os.homedir();
+	if (await isDirectory(home)) roots.push({ name: home, path: home });
+	if (await isDirectory("/")) roots.push({ name: "/", path: "/" });
+	return roots;
+}
+
+function directoryError(error: unknown): BoundaryError {
+	const code = (error as NodeJS.ErrnoException | undefined)?.code;
+	if (code === "ENOENT") return new BoundaryError("目录不存在");
+	if (code === "EACCES" || code === "EPERM") return new BoundaryError("没有权限读取此目录");
+	if (code === "ENOTDIR") return new BoundaryError("这不是一个目录");
+	return new BoundaryError(error instanceof Error ? error.message : String(error));
+}
+
+async function listDirectory(target: unknown) {
+	if (target !== undefined && (typeof target !== "string" || target.length === 0 || target.length > 4096)) {
+		throw new BoundaryError("invalid path");
+	}
+	const requested = typeof target === "string" ? target : os.homedir();
+	if (!path.isAbsolute(requested)) throw new BoundaryError("path must be absolute");
+	// realpath 同时做两件事：解析链接，以及确认目录真的存在
+	const resolved = await fs.realpath(requested).catch((error: unknown) => {
+		throw directoryError(error);
+	});
+	let stat;
+	try {
+		stat = await fs.stat(resolved);
+	} catch (error) {
+		throw directoryError(error);
+	}
+	if (!stat.isDirectory()) throw new BoundaryError("这不是一个目录");
+
+	const dirents = await fs.readdir(resolved, { withFileTypes: true }).catch((error: unknown) => {
+		throw directoryError(error);
+	});
+	const entries: FsEntry[] = [];
+	for (const entry of dirents) {
+		// 符号链接也列出来（macOS 的 /Volumes 全是链接）；能否进入由下一次 list 决定
+		if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+		entries.push({ name: entry.name, path: path.join(resolved, entry.name) });
+	}
+	entries.sort((left, right) => left.name.localeCompare(right.name, undefined, { numeric: true, sensitivity: "base" }));
+	const parent = path.dirname(resolved);
+	return {
+		path: resolved,
+		parent: parent === resolved ? null : parent,
+		entries: entries.slice(0, MAX_ENTRIES),
+		truncated: entries.length > MAX_ENTRIES,
+	};
+}
+
+export async function POST(req: Request) {
+	let body: unknown;
+	try {
+		body = await req.json();
+	} catch {
+		return NextResponse.json({ success: false, error: "invalid JSON body" }, { status: 400 });
+	}
+	if (!body || typeof body !== "object" || Array.isArray(body)) {
+		return NextResponse.json({ success: false, error: "expected an object body" }, { status: 400 });
+	}
+	const { action, path: target } = body as { action?: unknown; path?: unknown };
+	try {
+		if (action === "roots") return NextResponse.json({ success: true, data: { roots: await listRoots() } });
+		if (action === "list") return NextResponse.json({ success: true, data: await listDirectory(target) });
+		return NextResponse.json({ success: false, error: "unknown action" }, { status: 400 });
+	} catch (error) {
+		return NextResponse.json(
+			{ success: false, error: error instanceof Error ? error.message : String(error) },
+			{ status: error instanceof BoundaryError ? 400 : 500 },
+		);
+	}
+}

package/src/app/api/growth/route.ts

@@ -1,5 +1,5 @@
 import { NextResponse } from "next/server";
-import { getManaged, growthRecord } from "@/lib/agent-manager";
+import { getManaged, growthConsent, growthRecord } from "@/lib/agent-manager";
 import { GrowthError, changesBetween, fileContent, filePatch, isAvailable, listTree, readRounds } from "@/lib/growth-service";
 import { BoundaryError, resolveSessionPath, resolveWorkspacePath } from "@/lib/path-security";
 
@@ -7,7 +7,7 @@ export const dynamic = "force-dynamic";
 
 function status(err: unknown): number {
 	if (err instanceof BoundaryError) return 400;
-	if (err instanceof GrowthError) return err.code === "not-found" ? 404 : err.code === "unavailable" ? 503 : err.code === "too-large" ? 413 : 500;
+	if (err instanceof GrowthError) return err.code === "not-found" ? 404 : err.code === "unavailable" ? 503 : err.code === "too-large" ? 413 : err.code === "needs-consent" ? 409 : 500;
 	return 500;
 }
 
@@ -36,13 +36,18 @@ export async function GET(req: Request) {
 	}
 }
 
-/** POST { action: "record", session: <会话 id> }：立即记录，把当前改动提交为「你的修改」（并广播给会话订阅者） */
+/**
+ * POST { action: "record", session: <会话 id> }：立即记录，把当前改动提交为「你的修改」（并广播给会话订阅者）
+ * POST { action: "consent", session, allow: boolean }：回答「要不要在工作区建 git 仓库」；同意时立即拍基线
+ */
 export async function POST(req: Request) {
 	try {
-		const body = (await req.json()) as { action?: string; session?: unknown };
-		if (body.action !== "record") return NextResponse.json({ success: false, error: "unknown action" }, { status: 400 });
+		const body = (await req.json()) as { action?: string; session?: unknown; allow?: unknown };
+		if (body.action !== "record" && body.action !== "consent") return NextResponse.json({ success: false, error: "unknown action" }, { status: 400 });
+		if (body.action === "consent" && typeof body.allow !== "boolean") return NextResponse.json({ success: false, error: "allow must be a boolean" }, { status: 400 });
 		const sessionPath = await resolveSessionPath(String(body.session ?? ""), { allowPending: true });
-		const round = await growthRecord(getManaged(sessionPath));
+		const m = getManaged(sessionPath);
+		const round = body.action === "consent" ? await growthConsent(m, body.allow as boolean) : await growthRecord(m);
 		return NextResponse.json({ success: true, data: { round } });
 	} catch (err: any) {
 		return NextResponse.json({ success: false, error: String(err?.message ?? err) }, { status: err instanceof SyntaxError ? 400 : status(err) });

package/src/app/api/models/route.ts

@@ -9,6 +9,7 @@ import {
 	listModels,
 	listModelsForPiWeb,
 	loginState,
+	modelListStamp,
 	providerUsage,
 	readCustomProviders,
 	removeApiKey,
@@ -19,17 +20,28 @@ import {
 
 export const dynamic = "force-dynamic";
 
-/** 1300+ 个模型的目录有 240KB～420KB；Next 的压缩层实测没有压这条响应，这里自己 gzip（浏览器透明解压） */
-function jsonMaybeGzip(req: Request, payload: unknown): Response {
+/**
+ * 完整目录 482KB、精简目录 271KB，未压缩发送太浪费；这里自己 gzip。
+ * gzip 是主线程同步操作，设置面板开关一次会连着请求好几次，所以按目录版本戳复用压好的字节：
+ * 目录没变（5 秒 TTL 内、且没人改配置）就不再重新压一遍。
+ */
+const gzipCache = new Map<string, { at: number; body: Uint8Array }>();
+const GZIP_CACHE_TTL_MS = 5_000;
+
+function jsonMaybeGzip(req: Request, payload: unknown, stamp: string): Response {
 	const body = JSON.stringify(payload);
 	const accept = req.headers.get("accept-encoding") ?? "";
-	if (!/\bgzip\b/.test(accept) || body.length < 2048) {
-		return new Response(body, { headers: { "Content-Type": "application/json; charset=utf-8" } });
+	const headers = { "Content-Type": "application/json; charset=utf-8", Vary: "Accept-Encoding", "Cache-Control": "no-store" };
+	if (!/\bgzip\b/.test(accept) || body.length < 2048) return new Response(body, { headers });
+	const key = `${stamp}:${body.length}`;
+	const cached = gzipCache.get(key);
+	if (cached && Date.now() - cached.at < GZIP_CACHE_TTL_MS) {
+		return new Response(cached.body.slice(), { headers: { ...headers, "Content-Encoding": "gzip" } });
 	}
-	const gz = gzipSync(Buffer.from(body, "utf8"));
-	return new Response(new Uint8Array(gz), {
-		headers: { "Content-Type": "application/json; charset=utf-8", "Content-Encoding": "gzip", Vary: "Accept-Encoding", "Cache-Control": "no-store" },
-	});
+	const gz = new Uint8Array(gzipSync(Buffer.from(body, "utf8")));
+	if (gzipCache.size > 8) gzipCache.clear();
+	gzipCache.set(key, { at: Date.now(), body: gz });
+	return new Response(gz.slice(), { headers: { ...headers, "Content-Encoding": "gzip" } });
 }
 
 export async function GET(req: Request) {
@@ -46,7 +58,7 @@ export async function GET(req: Request) {
 		const providers = full
 			? data.providers
 			: data.providers.map((p) => ({ id: p.id, name: p.name, authReady: p.authReady, builtIn: p.builtIn, modelCount: p.modelCount }));
-		return jsonMaybeGzip(req, { success: true, data: { providers, models, customProviders } });
+		return jsonMaybeGzip(req, { success: true, data: { providers, models, customProviders } }, `${modelListStamp()}:${full ? "full" : "piweb"}`);
 	} catch (err: any) {
 		return NextResponse.json({ success: false, error: String(err?.message ?? err) }, { status: 500 });
 	}

package/src/app/api/remote/route.ts

@@ -0,0 +1,77 @@
+/**
+ * 「远程连接」内置插件的控制接口。
+ *
+ * GET    当前状态（局域网入口 + 公网入口 + 拼登录链接用的启动令牌）
+ * POST   { action: "start" | "stop" | "start-lan" | "stop-lan" }
+ * DELETE 全停
+ *
+ * 「谁能调这个接口」由 proxy.ts 把关；但「现在能不能开入口」必须在这里再看一次：
+ * 认证没开时 proxy 一律放行，这时开出去的局域网 / 公网入口就是一个免密 shell。
+ */
+import { NextResponse } from "next/server";
+import { remoteBlocked, remoteStatus, startLan, startPublic, stopAll, stopPublic } from "@/lib/remote/supervisor";
+import { authEnabled } from "@/lib/web-auth";
+
+export const dynamic = "force-dynamic";
+
+const NO_STORE = { "Cache-Control": "no-store" };
+
+/**
+ * 本次启动的令牌：设置页拿它拼带令牌的入口链接，手机打开就直接登录，不用再去终端里抄。
+ * 能调到这个接口的已经是登录过的设备（proxy.ts 把关），它们本来就有完整权限，拿到令牌不多出任何能力；
+ * 认证没开时没有令牌这回事。
+ */
+function loginToken(): string | null {
+	return authEnabled() ? process.env.PI_WEB_LAUNCH_TOKEN || null : null;
+}
+
+function respond() {
+	return NextResponse.json({ success: true, data: { ...remoteStatus(), loginToken: loginToken() } }, { headers: NO_STORE });
+}
+
+function bad(error: string, status = 400) {
+	return NextResponse.json({ success: false, error }, { status, headers: NO_STORE });
+}
+
+export async function GET() {
+	return respond();
+}
+
+export async function POST(request: Request) {
+	let body: unknown;
+	try {
+		body = await request.json();
+	} catch {
+		return bad("invalid JSON body");
+	}
+	const action = typeof body === "object" && body !== null && !Array.isArray(body)
+		? (body as { action?: unknown }).action
+		: undefined;
+	if (action === "start" || action === "start-lan") {
+		const blocked = remoteBlocked();
+		if (blocked === "auth") return bad("remote access requires authentication (PI_WEB_AUTH=1)", 409);
+		if (blocked === "dev") return bad("remote access is disabled in development mode", 409);
+	}
+	switch (action) {
+		case "start":
+			await startLan();
+			await startPublic();
+			return respond();
+		case "stop":
+			await stopPublic();
+			return respond();
+		case "start-lan":
+			await startLan();
+			return respond();
+		case "stop-lan":
+			await stopAll();
+			return respond();
+		default:
+			return bad("unknown action");
+	}
+}
+
+export async function DELETE() {
+	await stopAll();
+	return respond();
+}