@oversk7/pi-web-dsh-style 1.0.0 → 1.1.0

package/server.ts

@@ -3,7 +3,7 @@ import { createServer } from "node:http";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, readFile, readdir, stat, unlink } from "node:fs/promises";
+import { chmod, mkdir, mkdtemp, readFile, readdir, rm, stat, unlink } from "node:fs/promises";
 import { homedir, platform, tmpdir } from "node:os";
 import { basename, dirname, extname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -16,17 +16,25 @@ import {
   type RpcQueueKind,
   type RpcQueueSnapshot,
 } from "./abort-session.ts";
-import { ImageAttachmentStore } from "./attachment-store.ts";
+import { AttachmentStore, detectImageMimeType } from "./attachment-store.ts";
+import { builtinCommandError, parseSlashCommand } from "./web/slash-commands.js";
+import { extensionSettings } from "./extension-settings.ts";
+import { isLocalRequest, WebAccess } from "./network-access.ts";
+import { FrpProcess } from "./frp-process.ts";
+import { loadTerminalProxy, saveTerminalProxy, validateTerminalProxy, type TerminalProxySettings } from "./terminal-proxy.ts";
+import { frpcConfig, loadNetworkSettings, proxyForNetwork, publicNetworkSettings, relayServerFiles, resolveFrpc, saveNetworkSettings, updateNetworkSettings, type NetworkMode, type NetworkSettings } from "./network-settings.ts";
 import { closeSseClient, createSseClient, sendSseEvent, type SseClient } from "./sse-channel.ts";
 import { closeAllPiRpcs, spawnPiRpc, type Json, type PiRpc } from "./pi-rpc.ts";
 import { loadLocalSession } from "./local-session.ts";
-import { loadJsonWithLegacyMigration, writeJsonAtomically } from "./state-store.ts";
+import { loadJsonWithLegacyMigration, writeJsonAtomically, writeTextAtomically } from "./state-store.ts";
 import { buildFilePreview } from "./file-preview.ts";
+import { collectBackgroundJobs, readBackgroundJobLog } from "./background-jobs.ts";
 import { readClipboardImage, readClipboardText } from "./windows-clipboard.ts";
 import {
   applyAssistantDelta,
   applyToolExecution,
   attachToolResults,
+  browserMessages,
   findLast,
   renderAssistantMessage,
   renderCompaction,
@@ -44,6 +52,9 @@ const DEFAULT_PORT = 18789;
 const STATE_DIR = process.env.PI_WEB_STATE_DIR || join(getAgentDir(), "pi-web");
 const STATE_FILE = resolve(process.env.PI_WEB_STATE_FILE || join(STATE_DIR, "state.json"));
 const LEGACY_STATE_FILE = resolve(process.env.PI_WEB_LEGACY_STATE_FILE || join(here, "state.json"));
+const AUTH_FILE = join(dirname(STATE_FILE), "auth.json");
+const NETWORK_FILE = join(dirname(STATE_FILE), "network.json");
+const TERMINAL_PROXY_FILE = join(dirname(STATE_FILE), "terminal-proxy.json");
 
 interface Workspace {
   id: string;
@@ -181,6 +192,7 @@ interface RuntimeSession {
   operationChain?: Promise<void>;
   pendingTreeNavigation?: PendingTreeNavigation;
   compactionNotice?: RenderedMessage;
+  compactionNoticeIndex?: number;
   pendingQueue?: RpcQueueSnapshot;
 }
 
@@ -205,8 +217,19 @@ interface MaintenanceCommandResult {
 let server: ReturnType<typeof createServer> | undefined;
 let serverUrl: string | undefined;
 let serverInstanceId: string | undefined;
+let webAccess = new WebAccess(false);
+let networkSettings: NetworkSettings = { mode: "local" };
+let terminalProxy: TerminalProxySettings = { mode: "inherit", url: "http://127.0.0.1:7987" };
+let terminalProxySaving = false;
+let networkApplying = false;
+let networkChange: Promise<void> = Promise.resolve();
+let networkError: string | undefined;
+let frpRuntimeDir: string | undefined;
+const frpProcess = new FrpProcess(() => broadcastEvent({ type: "network_changed" }));
 let updateExtensions: (() => Promise<MaintenanceCommandResult>) | undefined;
 let reloadRuntime: (() => Promise<void>) | undefined;
+let extensionSettingsCwd = process.cwd();
+let extensionSettingsSaving = false;
 let maintenanceRunning = false;
 let sessions = new Map<string, RuntimeSession>();
 let sseClients = new Set<SseClient>();
@@ -221,7 +244,7 @@ const modelInfoCache = new Map<string, ModelInfo>();
 const modelCatalogRefreshes = new Map<string, Promise<ModelCatalog>>();
 const commandCache = new Map<string, SlashCommandInfo[]>();
 const exportDownloads = new Map<string, ExportDownload>();
-const imageAttachments = new ImageAttachmentStore();
+const attachments = new AttachmentStore();
 const ABORT_RPC_TIMEOUT_MS = 3_000;
 const INTERNAL_TREE_COMMAND = "pi-web-navigate-tree";
 const INTERNAL_RELOAD_COMMAND = "pi-web-reload-runtime";
@@ -240,8 +263,10 @@ const MIME: Record<string, string> = {
   ".woff2": "font/woff2",
   ".ttf": "font/ttf",
   ".png": "image/png",
+  ".webp": "image/webp",
 };
 const MAX_FILE_VIEW_BYTES = 2 * 1024 * 1024;
+const MAX_IMAGE_VIEW_BYTES = 10 * 1024 * 1024;
 
 function nowIso(): string {
   return new Date().toISOString();
@@ -397,7 +422,7 @@ function historyEditorText(record: RuntimeSession, entryId: string): string | un
 async function pasteSystemClipboard(): Promise<Json> {
   const image = await readClipboardImage();
   if (image) {
-    const attachment = await imageAttachments.create(image.bytes);
+    const attachment = await attachments.create(image.bytes);
     return {
       kind: "image",
       attachment: { ...attachment, url: `/api/attachments/${attachment.id}` },
@@ -618,7 +643,9 @@ function snapshotMessages(record: RuntimeSession): RenderedMessage[] {
       return merged;
     }
   }
-  return [...record.messages, notice];
+  const messages = [...record.messages];
+  messages.splice(Math.min(record.compactionNoticeIndex ?? messages.length, messages.length), 0, notice);
+  return messages;
 }
 
 function pendingQueueSnapshot(record: RuntimeSession): RpcQueueSnapshot {
@@ -651,7 +678,7 @@ function broadcastSessionSnapshot(record: RuntimeSession): void {
     thinkingLevelsByModel: thinkingLevelsByModel(record.models),
     commands: record.commands,
     extensionStatuses: record.extensionStatuses,
-    messages: snapshotMessages(record),
+    messages: browserMessages(snapshotMessages(record)),
     pendingQueue: pendingQueueSnapshot(record),
     dialogs: record.dialogs,
   });
@@ -864,7 +891,7 @@ async function discoverFreshModelCatalog(cwd: string): Promise<ModelCatalog> {
   const existing = modelCatalogRefreshes.get(key);
   if (existing) return existing;
   const task = (async () => {
-    const probe = spawnPiRpc({ cwd: key, noSession: true });
+    const probe = spawnPiRpc({ cwd: key, noSession: true, proxy: terminalProxy });
     try {
       const [modelsResponse, stateResponse] = await Promise.all([
         probe.send<Json>({ type: "get_available_models" }),
@@ -902,7 +929,7 @@ function applyModelInfo(record: RuntimeSession, info: ModelInfo): void {
 
 async function refreshModelsFresh(record: RuntimeSession): Promise<void> {
   if (record.starting) await record.starting;
-  if (record.streaming) {
+  if (record.streaming || hasRunningBackgroundJobs(record)) {
     await refreshModels(record);
     return;
   }
@@ -913,10 +940,15 @@ async function refreshModelsFresh(record: RuntimeSession): Promise<void> {
       const runtimeModels = (runtimeResponse.data?.models ?? []) as unknown[];
       if (!sameModelCatalog(runtimeModels, catalog.models)) {
         await Promise.allSettled([refreshState(record), refreshMessages(record)]);
+        if (record.streaming || hasRunningBackgroundJobs(record)) {
+          await refreshModels(record);
+          return;
+        }
         await stopSessionProcess(record);
       }
     } catch (error) {
       console.error("[pi-web] runtime model refresh failed:", error);
+      if (record.streaming || hasRunningBackgroundJobs(record)) return;
       await stopSessionProcess(record);
     }
   }
@@ -1220,6 +1252,7 @@ function bindSessionEvents(record: RuntimeSession, proc: PiRpc): void {
     } else if (event.type === "compaction_start") {
       const reason = typeof event.reason === "string" ? event.reason : undefined;
       record.state = { ...(record.state ?? {}), isCompacting: true };
+      record.compactionNoticeIndex = record.messages.length;
       record.compactionNotice = {
         kind: "compaction",
         id: `compaction-running:${Date.now()}`,
@@ -1251,6 +1284,7 @@ function bindSessionEvents(record: RuntimeSession, proc: PiRpc): void {
             timestamp: Date.now(),
           };
       record.compactionNotice = notice;
+      record.compactionNoticeIndex = record.messages.length;
       broadcastSessionSnapshot(record);
       if (result) {
         Promise.allSettled([refreshMessages(record), refreshStats(record)]).then(() => {
@@ -1296,10 +1330,15 @@ function bindSessionEvents(record: RuntimeSession, proc: PiRpc): void {
 // session lifecycle
 // ---------------------------------------------------------------------------
 
+function hasRunningBackgroundJobs(record: RuntimeSession): boolean {
+  // pi-pwsh-notify clears this live status only after its last background job exits.
+  return Boolean(record.extensionStatuses["pwsh-bg"]);
+}
+
 function evictIdleProcesses(): void {
   const idle: RuntimeSession[] = [];
   for (const record of sessions.values()) {
-    if (record.proc && !record.streaming && record.status !== "running" && record.status !== "starting" && record.dialogs.length === 0 && record.id !== state.currentSessionId) {
+    if (record.proc && !record.streaming && !hasRunningBackgroundJobs(record) && record.status !== "running" && record.status !== "starting" && record.dialogs.length === 0 && record.id !== state.currentSessionId) {
       idle.push(record);
     }
   }
@@ -1361,6 +1400,7 @@ async function ensureProcess(record: RuntimeSession): Promise<void> {
   const task = (async () => {
     const proc = spawnPiRpc({
       cwd: record.cwd,
+      proxy: terminalProxy,
       sessionId: record.sessionFile ? undefined : record.id,
       sessionFile: record.sessionFile,
       name: record.title === "新会话" ? undefined : record.title,
@@ -1707,28 +1747,6 @@ function readJsonBody(req: import("node:http").IncomingMessage, limit = 12 * 102
   });
 }
 
-function isTrustedLocalMutation(req: import("node:http").IncomingMessage): boolean {
-  const host = req.headers.host ?? "";
-  let hostname = "";
-  try {
-    hostname = new URL(`http://${host}`).hostname.toLowerCase();
-  } catch {
-    return false;
-  }
-  if (hostname !== "127.0.0.1" && hostname !== "localhost" && hostname !== "[::1]") return false;
-  const fetchSite = req.headers["sec-fetch-site"];
-  if (fetchSite === "cross-site") return false;
-  const origin = req.headers.origin;
-  if (origin) {
-    try {
-      if (new URL(origin).host.toLowerCase() !== host.toLowerCase()) return false;
-    } catch {
-      return false;
-    }
-  }
-  return true;
-}
-
 function findRecord(id: string): RuntimeSession | undefined {
   return sessions.get(id);
 }
@@ -2083,8 +2101,116 @@ function scheduleRuntimeReload(): void {
 async function handleApi(req: import("node:http").IncomingMessage, res: ServerResponse, url: URL): Promise<boolean> {
   const path = url.pathname;
   const method = req.method ?? "GET";
-  if (method !== "GET" && method !== "HEAD" && !isTrustedLocalMutation(req)) {
-    return sendJson(res, 403, { error: "forbidden origin" });
+  if (!webAccess.trusted(req)) return sendJson(res, 403, { error: "forbidden origin" });
+  res.setHeader("cache-control", "no-store");
+  if (method === "GET" && path === "/api/auth") {
+    return sendJson(res, 200, { passwordConfigured: webAccess.passwordConfigured });
+  }
+  if (method === "POST" && path === "/api/auth") {
+    const body = await readJsonBody(req, 2048);
+    if (!webAccess.passwordConfigured) {
+      return sendJson(res, 503, { error: "请先在电脑网页的设置中设置访问密码" });
+    }
+    if (!webAccess.remoteEnabled || !await webAccess.acceptsPassword(body.password)) {
+      return sendJson(res, 401, { error: "密码不正确" });
+    }
+    res.setHeader("set-cookie", webAccess.cookie(req));
+    return sendJson(res, 200, { ok: true });
+  }
+  if (!webAccess.authorized(req)) {
+    return sendJson(res, 401, { error: "请输入访问密码" });
+  }
+  if (method === "POST" && path === "/api/auth/password") {
+    if (!isLocalRequest(req)) return sendJson(res, 403, { error: "请在电脑本机网页设置密码" });
+    if (networkApplying) return sendJson(res, 409, { error: "网络设置正在应用，请稍后保存密码" });
+    networkApplying = true;
+    try {
+      const body = await readJsonBody(req, 2048);
+      await webAccess.setPassword(body.password, AUTH_FILE);
+    } catch (error) {
+      return sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+    } finally {
+      networkApplying = false;
+    }
+    for (const client of [...sseClients]) {
+      closeSseClient(client);
+      (client.res as ServerResponse).end();
+    }
+    sseClients.clear();
+    return sendJson(res, 200, { ok: true });
+  }
+
+  if (path === "/api/extensions" && (method === "GET" || method === "POST")) {
+    if (!isLocalRequest(req)) return sendJson(res, 403, { error: "请在电脑本机网页管理扩展" });
+    if (extensionSettingsSaving || maintenanceRunning) return sendJson(res, 409, { error: "扩展配置或维护操作正在执行，请稍后重试" });
+    extensionSettingsSaving = true;
+    try {
+      let change: { scope: "global" | "project"; source: string; enabled: boolean } | undefined;
+      if (method === "POST") {
+        const body = await readJsonBody(req, 16 * 1024);
+        if ((body.scope !== "global" && body.scope !== "project") || typeof body.source !== "string" || !body.source || typeof body.enabled !== "boolean") {
+          return sendJson(res, 400, { error: "扩展配置参数无效" });
+        }
+        change = { scope: body.scope, source: body.source, enabled: body.enabled };
+      }
+      return sendJson(res, 200, await extensionSettings(extensionSettingsCwd, change));
+    } catch (error) {
+      return sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+    } finally {
+      extensionSettingsSaving = false;
+    }
+  }
+
+  if (path === "/api/terminal-proxy") {
+    if (!isLocalRequest(req)) return sendJson(res, 403, { error: "请在电脑本机网页配置终端代理" });
+    if (method === "GET") return sendJson(res, 200, { settings: terminalProxy });
+    if (method === "POST") {
+      if (terminalProxySaving) return sendJson(res, 409, { error: "终端代理正在保存，请稍后重试" });
+      terminalProxySaving = true;
+      try {
+        const next = validateTerminalProxy(await readJsonBody(req, 4096));
+        await saveTerminalProxy(TERMINAL_PROXY_FILE, next);
+        terminalProxy = next;
+        return sendJson(res, 200, { settings: terminalProxy });
+      } catch (error) {
+        return sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+      } finally {
+        terminalProxySaving = false;
+      }
+    }
+  }
+
+  if (path === "/api/network" || path === "/api/network/server-files") {
+    if (!isLocalRequest(req)) return sendJson(res, 403, { error: "请在电脑本机网页配置网络访问" });
+    if (method === "GET" && path === "/api/network/server-files") {
+      if (!networkSettings.relay) return sendJson(res, 400, { error: "请先保存服务器中转配置" });
+      return sendJson(res, 200, { files: relayServerFiles(networkSettings.relay) });
+    }
+    if (method === "GET" && path === "/api/network") return sendJson(res, 200, networkView());
+    if (method === "POST" && path === "/api/network") {
+      if (networkApplying) return sendJson(res, 409, { error: "网络设置正在应用" });
+      networkApplying = true;
+      try {
+        const next = updateNetworkSettings(await readJsonBody(req, 16 * 1024), networkSettings);
+        if (next.mode === "relay") await resolveFrpc(next.relay!.frpcPath, dirname(NETWORK_FILE));
+        await saveNetworkSettings(NETWORK_FILE, next);
+        networkSettings = next;
+        networkError = undefined;
+        sendJson(res, 200, networkView());
+        networkChange = new Promise<void>((resolveChange) => setImmediate(resolveChange)).then(async () => {
+          if (!shuttingDown) await applyNetworkSettings();
+        }).catch((error) => {
+          networkError = error instanceof Error ? error.message : String(error);
+        }).finally(() => {
+          networkApplying = false;
+          broadcastEvent({ type: "network_changed" });
+        });
+        return true;
+      } catch (error) {
+        networkApplying = false;
+        return sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+      }
+    }
   }
 
   if (method === "GET" && path === "/api/bootstrap") {
@@ -2096,11 +2222,15 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
       commands: bootstrapCommands(),
       url: serverUrl,
       instanceId: serverInstanceId,
+      localClient: isLocalRequest(req),
+      lanEnabled: webAccess.remoteEnabled,
+      passwordConfigured: webAccess.passwordConfigured,
+      lanUrls: isLocalRequest(req) ? getWebLanUrls() : [],
     });
   }
 
   if (method === "POST" && (path === "/api/maintenance/update-and-reload" || path === "/api/maintenance/reload")) {
-    if (maintenanceRunning) return sendJson(res, 409, { error: "维护操作正在执行" });
+    if (maintenanceRunning || extensionSettingsSaving) return sendJson(res, 409, { error: "维护操作或扩展配置正在执行" });
     if (!reloadRuntime || (path.endsWith("update-and-reload") && !updateExtensions)) {
       return sendJson(res, 503, { error: "当前 Pi 运行时不支持 Web 维护操作，请先执行一次 /reload" });
     }
@@ -2137,12 +2267,26 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
     }
   }
 
+  if (method === "POST" && path === "/api/attachments") {
+    const body = await readJsonBody(req, 21 * 1024 * 1024);
+    if (typeof body.data !== "string" || !/^[A-Za-z0-9+/]+={0,2}$/.test(body.data)) {
+      return sendJson(res, 400, { error: "文件数据无效" });
+    }
+    try {
+      const attachment = await attachments.create(Buffer.from(body.data, "base64"), typeof body.name === "string" ? body.name : undefined);
+      return sendJson(res, 200, { attachment: { ...attachment, url: `/api/attachments/${attachment.id}` } });
+    } catch (error) {
+      return sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
+    }
+  }
+
   const attachmentMatch = /^\/api\/attachments\/([a-f0-9-]+)$/.exec(path);
   if (attachmentMatch && (method === "GET" || method === "HEAD")) {
     try {
-      const { meta, bytes } = await imageAttachments.read(attachmentMatch[1]);
+      const { meta, bytes } = await attachments.read(attachmentMatch[1]);
       res.writeHead(200, {
         "content-type": meta.mimeType,
+        ...(meta.kind === "document" ? { "content-disposition": `attachment; filename*=UTF-8''${encodeURIComponent(meta.name)}` } : {}),
         "content-length": bytes.byteLength,
         "cache-control": "private, no-store",
         "x-content-type-options": "nosniff",
@@ -2155,7 +2299,7 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
   }
 
   if (attachmentMatch && method === "DELETE") {
-    const removed = await imageAttachments.remove(attachmentMatch[1]);
+    const removed = await attachments.remove(attachmentMatch[1]);
     return sendJson(res, removed ? 200 : 404, removed ? { ok: true } : { error: "attachment not found" });
   }
 
@@ -2191,8 +2335,20 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
       const target = normalizePath(input);
       const info = await stat(target);
       if (!info.isFile()) return sendJson(res, 400, { error: "path is not a file" });
-      if (info.size > MAX_FILE_VIEW_BYTES) return sendJson(res, 413, { error: "file is too large to preview" });
+      const image = url.searchParams.get("format") === "image";
+      if (info.size > (image ? MAX_IMAGE_VIEW_BYTES : MAX_FILE_VIEW_BYTES)) return sendJson(res, 413, { error: "file is too large to preview" });
       const data = await readFile(target);
+      if (image) {
+        const mimeType = await detectImageMimeType(target, data);
+        if (!mimeType) return sendJson(res, 415, { error: "file is not a supported image" });
+        res.writeHead(200, {
+          "content-type": mimeType,
+          "cache-control": "private, no-store",
+          "x-content-type-options": "nosniff",
+        });
+        res.end(data);
+        return true;
+      }
       if (data.includes(0)) return sendJson(res, 415, { error: "binary files cannot be previewed" });
       if (url.searchParams.get("format") === "json") {
         return sendJson(res, 200, buildFilePreview(target, data));
@@ -2380,7 +2536,7 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
     return sendJson(res, 200, {
       session: sessionSummary(record),
       state: record.state,
-      messages: record.messages,
+      messages: browserMessages(record.messages),
       pendingQueue: pendingQueueSnapshot(record),
       models: record.models,
       thinkingLevels: record.thinkingLevels,
@@ -2405,6 +2561,21 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
     const match = /^\/api\/sessions\/([^/]+)(?:\/([^/]+))?$/.exec(path);
     const action = match?.[2] ?? "";
 
+    if (method === "GET" && action === "background-jobs") {
+      const jobs = collectBackgroundJobs(session.messages);
+      const requested = url.searchParams.get("job");
+      const job = requested ? jobs.find((item) => item.id === requested) : jobs[0];
+      if (requested && !job) return sendJson(res, 404, { error: "当前会话中找不到此后台任务" });
+      const visible = ({ logPath: _logPath, ...item }: typeof jobs[number]) => item;
+      const data = { jobs: jobs.map(visible), job: job ? visible(job) : null };
+      if (!job) return sendJson(res, 200, { ...data, output: "", truncated: false });
+      try {
+        return sendJson(res, 200, { ...data, ...await readBackgroundJobLog(job.logPath) });
+      } catch (error) {
+        return sendJson(res, 200, { ...data, output: "", truncated: false, error: (error as NodeJS.ErrnoException).code === "ENOENT" ? "日志文件已被清理或尚未创建" : "无法读取任务日志" });
+      }
+    }
+
     if (method === "POST" && action === "models") {
       try {
         await refreshModelsFresh(session);
@@ -2425,7 +2596,7 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
       return sendJson(res, 200, {
         session: sessionSummary(session),
         state: session.state,
-        messages: snapshotMessages(session),
+        messages: browserMessages(snapshotMessages(session)),
         pendingQueue: pendingQueueSnapshot(session),
         models: session.models,
         thinkingLevels: session.thinkingLevels,
@@ -2505,7 +2676,7 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
             history: nextHistory,
             session: sessionSummary(session),
             state: session.state,
-            messages: snapshotMessages(session),
+            messages: browserMessages(snapshotMessages(session)),
             pendingQueue: pendingQueueSnapshot(session),
             stats: session.stats,
           });
@@ -2515,6 +2686,40 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
       }
     }
 
+    if (method === "POST" && action === "reload") {
+      try {
+        return await withSessionOperation(session, async () => {
+          await ensureProcess(session);
+          if (session.streaming || session.state?.isCompacting || session.dialogs.length > 0) {
+            return sendJson(res, 409, { error: "请等待当前会话运行结束并处理完交互后再重载" });
+          }
+          const proc = session.proc!;
+          const commandsResponse = await proc.send<Json>({ type: "get_commands" });
+          const commands = commandsResponse.data?.commands;
+          if (!Array.isArray(commands) || !commands.some((command) => command?.name === INTERNAL_RELOAD_COMMAND)) {
+            return sendJson(res, 409, { error: "当前会话未加载 Web 重载命令，请重启 Pi Web 后重试" });
+          }
+          let commandError: string | undefined;
+          const unsubscribe = proc.onEvent((event) => {
+            if (event.type === "extension_error" && event.extensionPath === `command:${INTERNAL_RELOAD_COMMAND}`) {
+              commandError = String(event.error || "会话重载失败");
+            }
+          });
+          try {
+            await proc.send({ type: "prompt", message: `/${INTERNAL_RELOAD_COMMAND}` });
+            if (commandError) throw new Error(commandError);
+          } finally {
+            unsubscribe();
+          }
+          await Promise.all([refreshState(session), refreshCommands(session), refreshModels(session)]);
+          broadcastSessionSnapshot(session);
+          return sendJson(res, 200, { ok: true, reloaded: true });
+        });
+      } catch (error) {
+        return sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+
     if (method === "POST" && action === "prompt") {
       const body = await readJsonBody(req);
       const message = typeof body.message === "string" ? body.message : "";
@@ -2522,35 +2727,47 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
         ? body.attachmentIds.filter((id): id is string => typeof id === "string")
         : [];
       if (!message.trim() && attachmentIds.length === 0) {
-        return sendJson(res, 400, { error: "message or image attachment is required" });
+        return sendJson(res, 400, { error: "请输入消息或添加文件附件" });
       }
+      const parsedCommand = parseSlashCommand(message);
+      const builtinError = parsedCommand ? builtinCommandError(parsedCommand.name) : null;
+      if (builtinError) return sendJson(res, 400, { error: builtinError });
       try {
         return await withSessionOperation(session, async () => {
           await ensureProcess(session);
           const wasStreaming = session.streaming;
           if (attachmentIds.length > 0 && wasStreaming) {
-            return sendJson(res, 409, { error: "生成过程中暂不支持排队图片，请停止当前生成后再发送" });
+            return sendJson(res, 409, { error: "生成过程中暂不支持排队附件，请停止当前生成后再发送" });
           }
           if (attachmentIds.length > 0 && message.trimStart().startsWith("/")) {
-            return sendJson(res, 400, { error: "斜杠命令不能附带图片" });
+            return sendJson(res, 400, { error: "斜杠命令不能附带附件" });
           }
           const model = session.state?.model;
           const modelInput = model && typeof model === "object" && Array.isArray((model as Json).input)
             ? (model as Json).input as unknown[]
             : [];
-          if (attachmentIds.length > 0 && !modelInput.includes("image")) {
-            return sendJson(res, 400, { error: "当前模型不支持图片输入，请切换视觉模型" });
-          }
-          let images: Array<{ type: "image"; data: string; mimeType: string }> = [];
+          let prepared: Awaited<ReturnType<AttachmentStore["promptForRpc"]>>;
           try {
-            images = await imageAttachments.imagesForRpc(attachmentIds);
+            prepared = await attachments.promptForRpc(attachmentIds, message);
           } catch (error) {
             return sendJson(res, 400, { error: error instanceof Error ? error.message : String(error) });
           }
-          const promptMessage = message.trim() || "请分析附加图片。";
-          if (promptMessage.trimStart().startsWith("/")) await refreshCommands(session);
-          const optimisticStreaming = !wasStreaming && !isImmediateExtensionCommand(session, promptMessage);
-          const command: Json = { type: "prompt", message: promptMessage };
+          const { images, message: promptMessage } = prepared;
+          if (images.length > 0 && !modelInput.includes("image")) {
+            return sendJson(res, 400, { error: "当前模型不支持图片输入，请切换视觉模型" });
+          }
+          const slash = /^\/([^\s]+)(?:\s|$)/.exec(promptMessage.trim());
+          if (promptMessage.trimStart().startsWith("/")) {
+            const response = await session.proc!.send<Json>({ type: "get_commands" });
+            session.commands = normalizeCommands(response.data?.commands);
+            commandCache.set(session.cwd, session.commands);
+            if (!slash || !session.commands.some((command) => command.name === slash[1])) {
+              return sendJson(res, 400, { error: `未知或不可用的命令：${slash ? `/${slash[1]}` : "/"}。请输入 / 查看可用命令；普通消息请勿以 / 开头。` });
+            }
+          }
+          const immediateCommand = isImmediateExtensionCommand(session, promptMessage);
+          const optimisticStreaming = !wasStreaming && !immediateCommand;
+          const command: Json = { type: "prompt", message: slash ? promptMessage.trim() : promptMessage };
           if (images.length > 0) command.images = images;
           if (wasStreaming) command.streamingBehavior = "steer";
           if (optimisticStreaming) {
@@ -2560,15 +2777,15 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
           }
           try {
             const response = await session.proc!.send(command);
-            await Promise.all(attachmentIds.map((id) => imageAttachments.remove(id)));
-            if (!session.title || session.title === "新会话") {
-              const nextTitle = message.trim().replace(/\s+/g, " ").slice(0, 60) || "图片会话";
+            await Promise.all(attachmentIds.map((id) => attachments.remove(id)));
+            if (!immediateCommand && (!session.title || session.title === "新会话")) {
+              const nextTitle = message.trim().replace(/\s+/g, " ").slice(0, 60) || "文件会话";
               session.title = nextTitle;
               updateStoredSession(session);
               session.proc?.send({ type: "set_session_name", name: nextTitle }).catch(() => {});
               broadcastWorkspaces();
             }
-            return sendJson(res, 200, { ok: true, response, queued: wasStreaming });
+            return sendJson(res, 200, { ok: true, response, queued: wasStreaming && !immediateCommand });
           } catch (error) {
             if (optimisticStreaming) {
               session.streaming = false;
@@ -2809,24 +3026,37 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
       const body = await readJsonBody(req);
       const name = typeof body.name === "string" ? body.name.trim().replace(/\s+/g, " ").slice(0, 60) : "";
       if (!name) return sendJson(res, 400, { error: "name is required" });
-      session.title = name;
-      updateStoredSession(session);
-      if (session.proc) {
-        session.proc.send({ type: "set_session_name", name }).catch(() => {});
-      } else {
-        session.pendingName = name;
-        scheduleSave();
+      try {
+        if (session.proc) {
+          await session.proc.send({ type: "set_session_name", name });
+          session.pendingName = undefined;
+        } else {
+          session.pendingName = name;
+        }
+        session.title = name;
+        updateStoredSession(session);
+        broadcastWorkspaces();
+        broadcastSessionSnapshot(session);
+        return sendJson(res, 200, { ok: true });
+      } catch (error) {
+        return sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
       }
-      broadcastWorkspaces();
-      broadcastSessionSnapshot(session);
-      return sendJson(res, 200, { ok: true });
     }
 
     if (method === "POST" && action === "compact") {
-      await ensureProcess(session);
+      const body = await readJsonBody(req);
+      const customInstructions = typeof body.customInstructions === "string" ? body.customInstructions.trim() : "";
       try {
-        const response = await session.proc!.send({ type: "compact" });
-        return sendJson(res, 200, { ok: true, response });
+        return await withSessionOperation(session, async () => {
+          await ensureProcess(session);
+          if (session.streaming || session.state?.isCompacting || session.dialogs.length > 0) {
+            return sendJson(res, 409, { error: "请等待当前会话运行结束并处理完交互后再压缩" });
+          }
+          const response = await session.proc!.send({ type: "compact", ...(customInstructions ? { customInstructions } : {}) });
+          await Promise.all([refreshState(session), refreshMessages(session), refreshStats(session)]);
+          broadcastSessionSnapshot(session);
+          return sendJson(res, 200, { ok: true, response });
+        });
       } catch (error) {
         return sendJson(res, 500, { error: error instanceof Error ? error.message : String(error) });
       }
@@ -2895,7 +3125,7 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
       return sendJson(res, 200, {
         session: sessionSummary(session),
         state: session.state,
-        messages: snapshotMessages(session),
+        messages: browserMessages(snapshotMessages(session)),
         pendingQueue: pendingQueueSnapshot(session),
         models: session.models,
         thinkingLevels: session.thinkingLevels,
@@ -2922,19 +3152,77 @@ async function handleApi(req: import("node:http").IncomingMessage, res: ServerRe
 // server lifecycle
 // ---------------------------------------------------------------------------
 
-function listenOn(app: ReturnType<typeof createServer>, preferredPort: number): Promise<number> {
+function networkView() {
+  const status = networkError ? { state: "error", message: networkError }
+    : networkSettings.mode === "relay" ? frpProcess.status
+    : { state: networkSettings.mode === "lan" ? "connected" : "stopped", message: networkSettings.mode === "lan" ? "局域网访问已开启" : "仅本机访问" };
+  return { settings: publicNetworkSettings(networkSettings), status, urls: getWebLanUrls(), applying: networkApplying };
+}
+
+function disconnectWebClients(): void {
+  for (const client of [...sseClients]) {
+    closeSseClient(client);
+    (client.res as ServerResponse).end();
+  }
+  sseClients.clear();
+}
+
+async function stopRelay(): Promise<void> {
+  await frpProcess.stop();
+  if (frpRuntimeDir) await rm(frpRuntimeDir, { recursive: true, force: true });
+  frpRuntimeDir = undefined;
+}
+
+async function startRelay(): Promise<void> {
+  if (networkSettings.mode !== "relay" || !networkSettings.relay || !serverUrl) return;
+  const relay = networkSettings.relay;
+  const executable = await resolveFrpc(relay.frpcPath, dirname(NETWORK_FILE));
+  const runtimeRoot = join(dirname(NETWORK_FILE), "runtime");
+  await mkdir(runtimeRoot, { recursive: true });
+  frpRuntimeDir = await mkdtemp(join(runtimeRoot, "frpc-"));
+  const configPath = join(frpRuntimeDir, "frpc.toml");
+  await writeTextAtomically(configPath, frpcConfig(relay, Number(new URL(serverUrl).port)));
+  await chmod(configPath, 0o600);
+  await frpProcess.start({ executable, args: ["-c", configPath], cwd: dirname(NETWORK_FILE) });
+}
+
+async function applyNetworkSettings(): Promise<void> {
+  if (!server || !serverUrl) return;
+  await stopRelay();
+  const next = await WebAccess.load(networkSettings.mode === "lan", AUTH_FILE, proxyForNetwork(networkSettings));
+  disconnectWebClients();
+  if (next.lan !== webAccess.lan) {
+    const port = Number(new URL(serverUrl).port);
+    const previousHost = webAccess.lan ? "0.0.0.0" : HOST;
+    const app = server;
+    await new Promise<void>((resolveClose) => {
+      app.close(() => resolveClose());
+      app.closeAllConnections();
+    });
+    try {
+      await listenOn(app, port, next.lan ? "0.0.0.0" : HOST, false);
+    } catch (error) {
+      await listenOn(app, port, previousHost, false);
+      throw error;
+    }
+  }
+  webAccess = next;
+  await startRelay();
+}
+
+function listenOn(app: ReturnType<typeof createServer>, preferredPort: number, host = HOST, allowFallback = true): Promise<number> {
   return new Promise((resolvePort, reject) => {
     const onError = (error: NodeJS.ErrnoException) => {
-      if (error.code === "EADDRINUSE" && preferredPort !== 0) {
+      if (allowFallback && error.code === "EADDRINUSE" && preferredPort !== 0) {
         app.removeListener("error", onError);
-        listenOn(app, 0).then(resolvePort, reject);
+        listenOn(app, 0, host).then(resolvePort, reject);
         return;
       }
       app.removeListener("error", onError);
       reject(error);
     };
     app.once("error", onError);
-    app.listen(preferredPort, HOST, () => {
+    app.listen(preferredPort, host, () => {
       app.removeListener("error", onError);
       const address = app.address();
       resolvePort(address && typeof address === "object" ? address.port : preferredPort);
@@ -2950,6 +3238,7 @@ function openBrowser(url: string): void {
 }
 
 function exitHook(): void {
+  frpProcess.kill();
   for (const record of sessions.values()) {
     try {
       record.proc?.close();
@@ -2957,7 +3246,7 @@ function exitHook(): void {
       // ignore
     }
   }
-  void imageAttachments.close();
+  void attachments.close();
 }
 
 function sigintHook(): void {
@@ -2972,6 +3261,8 @@ function shutdown(): Promise<void> {
 }
 
 async function shutdownServer(): Promise<void> {
+  await networkChange;
+  await stopRelay();
   for (const client of [...sseClients]) {
     closeSseClient(client);
     try {
@@ -2985,7 +3276,7 @@ async function shutdownServer(): Promise<void> {
   await closeAllPiRpcs();
   for (const download of exportDownloads.values()) unlink(download.path).catch(() => {});
   exportDownloads.clear();
-  await imageAttachments.close();
+  await attachments.close();
   if (heartbeat) clearInterval(heartbeat);
   heartbeat = undefined;
   await saveStateNow().catch(() => {});
@@ -3010,6 +3301,8 @@ export async function startWebServer(options: {
   defaultCwd?: string;
   port?: number;
   open?: boolean;
+  lan?: boolean;
+  mode?: NetworkMode;
   initialModelInfo?: ModelInfo;
   initialCommands?: unknown[];
   updateExtensions?: () => Promise<MaintenanceCommandResult>;
@@ -3017,9 +3310,19 @@ export async function startWebServer(options: {
 } = {}): Promise<string> {
   if (shutdownPromise) await shutdownPromise;
   const initialCwd = normalizePath(options.defaultCwd ?? process.cwd());
+  extensionSettingsCwd = initialCwd;
   updateExtensions = options.updateExtensions;
   reloadRuntime = options.reloadRuntime;
+  const mode = options.mode ?? (options.lan === undefined ? undefined : options.lan ? "lan" : "local");
   if (serverUrl && server) {
+    await networkChange;
+    if (mode !== undefined) {
+      networkSettings = updateNetworkSettings({ mode }, networkSettings);
+      await saveNetworkSettings(NETWORK_FILE, networkSettings);
+      networkError = undefined;
+      await applyNetworkSettings();
+      broadcastEvent({ type: "network_changed" });
+    }
     if (options.initialCommands?.length) commandCache.set(initialCwd, normalizeCommands(options.initialCommands));
     if (options.open !== false) openBrowser(serverUrl);
     return serverUrl;
@@ -3037,9 +3340,24 @@ export async function startWebServer(options: {
   }
   if (options.initialCommands?.length) commandCache.set(initialCwd, normalizeCommands(options.initialCommands));
   if (state.workspaces.length === 0 && options.defaultCwd) await addWorkspace(options.defaultCwd);
-  const requestedPort = options.port && Number.isFinite(options.port) ? options.port : DEFAULT_PORT;
+  const requestedPort = options.port ?? DEFAULT_PORT;
+  if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
+    throw new Error("端口必须是 0–65535 之间的整数");
+  }
+  terminalProxy = await loadTerminalProxy(TERMINAL_PROXY_FILE);
+  networkSettings = await loadNetworkSettings(NETWORK_FILE);
+  if (mode !== undefined) {
+    networkSettings = updateNetworkSettings({ mode }, networkSettings);
+    await saveNetworkSettings(NETWORK_FILE, networkSettings);
+  }
+  networkApplying = false;
+  networkError = undefined;
+  webAccess = await WebAccess.load(networkSettings.mode === "lan", AUTH_FILE, proxyForNetwork(networkSettings));
   const app = createServer(async (req, res) => {
     try {
+      res.setHeader("referrer-policy", "no-referrer");
+      res.setHeader("x-content-type-options", "nosniff");
+      res.setHeader("x-frame-options", "DENY");
       if (shuttingDown) return sendJson(res, 503, { error: "pi-web 正在关闭" });
       const url = new URL(req.url ?? "/", `http://${req.headers.host ?? `${HOST}:${requestedPort}`}`);
       if (url.pathname.startsWith("/api/")) {
@@ -3053,7 +3371,7 @@ export async function startWebServer(options: {
       else res.end();
     }
   });
-  const port = await listenOn(app, requestedPort);
+  const port = await listenOn(app, requestedPort, webAccess.lan ? "0.0.0.0" : HOST);
   server = app;
   serverUrl = `http://${HOST}:${port}`;
   serverInstanceId = randomUUID();
@@ -3061,6 +3379,9 @@ export async function startWebServer(options: {
   process.on("exit", exitHook);
   process.on("SIGINT", sigintHook);
   process.on("SIGTERM", sigintHook);
+  try { await startRelay(); } catch (error) {
+    networkError = error instanceof Error ? error.message : String(error);
+  }
   if (options.open !== false) openBrowser(serverUrl);
   return serverUrl;
 }
@@ -3072,3 +3393,11 @@ export async function stopWebServer(): Promise<void> {
 export function getWebUrl(): string | undefined {
   return serverUrl;
 }
+
+export function getWebLanUrls(): string[] {
+  return serverUrl ? webAccess.urls(Number(new URL(serverUrl).port)) : [];
+}
+
+export function getWebConnectionOptions(): { port: number; lan: boolean; mode: NetworkMode } | undefined {
+  return serverUrl ? { port: Number(new URL(serverUrl).port), lan: webAccess.lan, mode: networkSettings.mode } : undefined;
+}