@rexvane/piweb 0.3.22 → 0.3.23

package/src/components/side-chat/SideChatPanel.tsx

@@ -0,0 +1,189 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
+import dynamic from "next/dynamic";
+import { IconChevronDown14, IconCloseOutline14, IconNewChatOutline16, IconSendArrowUp14, IconStopFill16 } from "@/components/icons";
+import { ContextMeter } from "@/components/ContextMeter";
+import { ModelSelector, type ModelChoice } from "@/components/ModelSelector";
+import { useI18n } from "@/i18n";
+import { EMPTY_SIDE_CHAT, sideChatStore, type SideChatStore } from "./store";
+import styles from "./SideChatPanel.module.css";
+
+const Markdown = dynamic(() => import("@/components/MarkdownBlock").then((module) => module.MarkdownBlock));
+const StreamingMarkdown = dynamic(() => import("@/components/MarkdownBlock").then((module) => module.StreamingMarkdownBlock));
+
+export function SideChatPanel({ sessionId, ready = true, mainModel, models = [], providerNames = {}, authByProvider = {}, onClose, store = sideChatStore }: {
+	sessionId: string | null;
+	ready?: boolean;
+	mainModel?: { provider: string; id: string; name: string };
+	models?: ModelChoice[];
+	providerNames?: Record<string, string>;
+	authByProvider?: Record<string, boolean>;
+	onClose: () => void;
+	store?: SideChatStore;
+}) {
+	const { t } = useI18n();
+	const subscribe = useCallback((listener: () => void) => store.subscribe(sessionId, listener), [sessionId, store]);
+	const getSnapshot = useCallback(() => store.get(sessionId), [sessionId, store]);
+	const state = useSyncExternalStore(subscribe, getSnapshot, () => EMPTY_SIDE_CHAT);
+	const thread = state.threads.find((item) => item.id === state.currentThreadId);
+	const scrollRef = useRef<HTMLDivElement>(null);
+	const textareaRef = useRef<HTMLTextAreaElement>(null);
+	const pinned = useRef(true);
+	const lastTop = useRef(0);
+	const busy = Boolean(thread?.request);
+	const threadId = thread?.id;
+	/** 历史记录菜单是否展开 */
+	const [historyOpen, setHistoryOpen] = useState(false);
+	const historyRef = useRef<HTMLDivElement>(null);
+	const selectedModel = thread?.model
+		? models.find((model) => model.provider === thread.model!.provider && model.id === thread.model!.id) ?? { ...thread.model, name: thread.model.id }
+		: mainModel;
+	const canSend = Boolean(sessionId && ready && selectedModel);
+
+	useEffect(() => {
+		pinned.current = true;
+		lastTop.current = 0;
+		if (scrollRef.current) scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
+	}, [sessionId, threadId]);
+	useEffect(() => {
+		const node = scrollRef.current;
+		if (!node) return;
+		const pin = () => { if (pinned.current) node.scrollTop = node.scrollHeight; };
+		const observer = new ResizeObserver(pin);
+		if (node.firstElementChild) observer.observe(node.firstElementChild);
+		pin();
+		return () => observer.disconnect();
+	}, [thread?.messages]);
+	useEffect(() => {
+		const textarea = textareaRef.current;
+		if (!textarea) return;
+		textarea.style.height = "auto";
+		textarea.style.height = `${Math.min(180, Math.max(64, textarea.scrollHeight))}px`;
+	}, [thread?.draft, threadId]);
+
+	// 历史记录菜单：点外部或 Esc 关掉（与圆环弹窗同一套做法）
+	useEffect(() => {
+		if (!historyOpen) return;
+		const onDown = (event: MouseEvent) => {
+			if (!historyRef.current?.contains(event.target as Node)) setHistoryOpen(false);
+		};
+		const onKey = (event: KeyboardEvent) => {
+			if (event.key === "Escape") setHistoryOpen(false);
+		};
+		document.addEventListener("mousedown", onDown);
+		document.addEventListener("keydown", onKey);
+		return () => {
+			document.removeEventListener("mousedown", onDown);
+			document.removeEventListener("keydown", onKey);
+		};
+	}, [historyOpen]);
+
+	// 上下文：这次问出去的真实 prompt（input + 缓存读写）对上该模型的窗口。
+	// 没有真实用量就一律 null —— 圆环显示「用量未知」，不编数字。
+	const usage = thread?.usage;
+	const contextTokens = usage ? usage.input + usage.cacheRead + usage.cacheWrite : null;
+	const contextWindow = thread?.contextWindow ?? null;
+	const contextPercent = contextTokens !== null && contextWindow ? (contextTokens / contextWindow) * 100 : null;
+
+	const send = () => {
+		if (!sessionId || !canSend || busy || !thread?.draft.trim()) return;
+		pinned.current = true;
+		store.send(sessionId);
+		textareaRef.current?.focus({ preventScroll: true });
+	};
+
+	return (
+		<section className={styles.panel} aria-label={t.sideChat} data-testid="side-chat-panel">
+			<header className={styles.header}>
+				<span className={styles.title}>{t.sideChat}</span>
+				<button type="button" className="icon-btn" aria-label={t.sideChatNew} title={t.sideChatNew} disabled={!sessionId} onClick={() => sessionId && store.createThread(sessionId)}>
+					<IconNewChatOutline16 size={16} />
+				</button>
+				<button type="button" className="icon-btn" aria-label={t.close} title={t.close} onClick={onClose}><IconCloseOutline14 size={14} /></button>
+			</header>
+			{state.threads.length > 1 && (
+				// 原生 select 在深色界面里是系统白底菜单（又丑又不跟主题），改用与模型选择器一致的浮层菜单
+				<div className={styles.history} ref={historyRef}>
+					<button type="button" className={styles.historyButton} aria-label={t.sideChatHistory} aria-haspopup="menu" aria-expanded={historyOpen} onClick={() => setHistoryOpen((open) => !open)}>
+						<span className="truncate">{thread ? `${thread.title || t.sideChatNew}${thread.request ? " · …" : ""}` : t.sideChatHistory}</span>
+						<IconChevronDown14 size={12} style={{ flex: "none", color: "var(--dsw-label-caption)" }} />
+					</button>
+					{historyOpen && (
+						<div className={styles.historyMenu} role="menu" aria-label={t.sideChatHistory}>
+							{[...state.threads].reverse().map((item) => (
+								<button key={item.id} type="button" role="menuitemradio" aria-checked={item.id === threadId} className={styles.historyItem}
+									onClick={() => { if (sessionId) store.selectThread(sessionId, item.id); setHistoryOpen(false); }}>
+									<span className="truncate">{item.title || t.sideChatNew}</span>
+									{item.request ? <span className={styles.historyMeta}>…</span> : null}
+								</button>
+							))}
+						</div>
+					)}
+				</div>
+			)}
+			<div className={styles.messages} ref={scrollRef} role="log" aria-label={t.sideChatMessages} aria-live="polite" aria-relevant="additions" onScroll={(event) => {
+				const node = event.currentTarget;
+				const distance = node.scrollHeight - node.scrollTop - node.clientHeight;
+				const movedUp = node.scrollTop < lastTop.current - 1 && distance > 2;
+				pinned.current = !movedUp && distance < 48;
+				lastTop.current = node.scrollTop;
+			}}>
+				<div className={styles.messageContent}>
+					{!thread?.messages.length ? (
+						<div className={styles.empty}>
+							<p>{sessionId ? t.sideChatEmpty : t.sideChatPickSession}</p>
+							{sessionId && <span>{t.sideChatHint}</span>}
+						</div>
+					) : thread.messages.map((message) => (
+						<div key={message.id} className={message.role === "user" ? styles.question : styles.answer} data-role={message.role}>
+							{message.role === "user" ? message.text : <>
+								{message.contextTruncated && <p className={styles.notice}>{t.sideChatContextTruncated}</p>}
+								{message.text && (message.status === "pending" ? <StreamingMarkdown text={message.text} /> : <Markdown text={message.text} />)}
+								{message.status === "pending" && !message.text && <span className={styles.waiting} role="status">{thread.connectionLost ? t.reconnecting : t.sideChatAnswering}</span>}
+								{message.error && <div className={styles.error} role="alert">{message.error}{message.status === "error" && message === thread.messages.at(-1) && <button type="button" disabled={busy} onClick={() => sessionId && store.send(sessionId, true)}>{t.retry}</button>}</div>}
+								{message.status === "aborted" && <p className={styles.notice}>{t.turnAborted}</p>}
+								{message.lengthLimited && <p className={styles.notice}>{t.sideChatLengthLimited}</p>}
+							</>}
+						</div>
+					))}
+				</div>
+			</div>
+			{state.storageFailed && <p className={styles.storageError} role="alert">{t.sideChatStorageFailed}</p>}
+			<form className={styles.composer} onSubmit={(event) => { event.preventDefault(); send(); }}>
+				<textarea ref={textareaRef} aria-label={t.sideChatQuestion} placeholder={sessionId ? t.sideChatPlaceholder : t.sideChatPickSession} value={thread?.draft ?? ""} disabled={!canSend}
+					onChange={(event) => sessionId && store.setDraft(sessionId, event.target.value)}
+					onKeyDown={(event) => {
+						if (event.key === "Enter" && !event.shiftKey && !event.nativeEvent.isComposing && event.nativeEvent.keyCode !== 229) { event.preventDefault(); send(); }
+					}} />
+				<div className={styles.actions}>
+					<div className={styles.model} role="group" aria-label={t.sideChatModel}>
+						<ModelSelector model={selectedModel} models={models} providerNames={providerNames} authByProvider={authByProvider}
+							modelOnly disabled={!sessionId} thinkingLevels={[]} onSelectLevel={() => {}}
+							defaultOption={{ label: t.sideChatFollowMain, selected: !thread?.model, onSelect: () => sessionId && store.setModel(sessionId) }}
+							onSelectModel={(provider, id) => sessionId && store.setModel(sessionId, { provider, id })} />
+					</div>
+					<div className={styles.meter}>
+						<ContextMeter
+							percent={contextPercent}
+							tokens={contextTokens}
+							contextWindow={contextWindow}
+							label={t.contextMeasured}
+							source={thread?.characters ? {
+								systemChars: 0,
+								messages: thread.messages.map((message) => ({ role: message.role, content: [{ type: "text", text: message.text }] })),
+								breakdown: {
+									characters: { systemPrompt: thread.characters.systemPrompt, background: thread.characters.background, systemTools: 0, customTools: 0, memory: 0, skills: 0, compacted: 0 },
+									systemPrompt: 0, systemTools: 0, customTools: 0, memory: 0, skills: 0, compacted: 0, autoCompactBuffer: 0,
+								},
+							} : undefined}
+							model={selectedModel ? { provider: selectedModel.provider, id: selectedModel.id } : null}
+						/>
+					</div>
+					{busy ? <button type="button" className={styles.send} title={t.stop} aria-label={t.stop} onClick={() => sessionId && store.stop(sessionId)}><IconStopFill16 size={15} /></button>
+						: <button type="submit" className={styles.send} title={t.send} aria-label={t.send} disabled={!canSend || !thread?.draft.trim()}><IconSendArrowUp14 size={16} /></button>}
+				</div>
+			</form>
+		</section>
+	);
+}

package/src/components/side-chat/icons.tsx

@@ -0,0 +1,8 @@
+import type { SVGProps } from "react";
+
+export function SideChatIcon({ size = 16, ...props }: SVGProps<SVGSVGElement> & { size?: number }) {
+	return <svg width={size} height={size} viewBox="0 0 20 20" fill="none" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" {...props}>
+		<path d="M12.5 11.5H6l-3.5 2V4.5A2 2 0 0 1 4.5 2.5h8a2 2 0 0 1 2 2v5a2 2 0 0 1-2 2Z" />
+		<path d="M7.5 14.5h6.5l3.5 2V7.5a2 2 0 0 0-1-1.73" />
+	</svg>;
+}

package/src/components/side-chat/request-history.ts

@@ -0,0 +1,29 @@
+import { SIDE_CHAT_BODY_LIMIT, SIDE_CHAT_HISTORY_LIMIT, SIDE_CHAT_TEXT_LIMIT, type SideChatHistoryMessage } from "@/lib/side-chat/types";
+
+/** Bound only the transmitted context; the browser retains the original transcript. */
+export function requestHistory(messages: SideChatHistoryMessage[]): { history: SideChatHistoryMessage[]; truncated: boolean } {
+ const encoder = new TextEncoder();
+ const history: SideChatHistoryMessage[] = [];
+ // Reserve the other half for the question (including JSON escapes), model and envelope.
+ let remaining = Math.floor(SIDE_CHAT_BODY_LIMIT / 2) - 2;
+ let truncated = false;
+ for (let i = messages.length - 1; i >= 0; i--) {
+  if (history.length === SIDE_CHAT_HISTORY_LIMIT) { truncated = true; break; }
+  const message = messages[i];
+  let text = message.text;
+  if (text.length > SIDE_CHAT_TEXT_LIMIT) {
+   text = text.slice(-SIDE_CHAT_TEXT_LIMIT);
+   if (/^[\uDC00-\uDFFF]/.test(text)) text = text.slice(1);
+   truncated = true;
+  }
+  const entry = { role: message.role, text };
+  const size = encoder.encode(JSON.stringify(entry)).byteLength + 1;
+  if (size > remaining) { truncated = true; break; }
+  remaining -= size;
+  history.push(entry);
+ }
+ history.reverse();
+ // A retained transcript must begin with a question, not an orphaned answer.
+ while (history[0]?.role === "assistant") { history.shift(); truncated = true; }
+ return { history, truncated };
+}

package/src/components/side-chat/store.ts

@@ -0,0 +1,248 @@
+"use client";
+
+import { isSideChatId, isSideChatModel, type SideChatModel, type SideChatHistoryMessage, type SideChatProgress, type SideChatRequest, type SideChatUsage } from "@/lib/side-chat/types";
+
+import { requestHistory } from "./request-history";
+
+export interface SideChatMessage {
+	id: string;
+	role: "user" | "assistant";
+	text: string;
+	status?: "pending" | "done" | "error" | "aborted";
+	error?: string;
+	contextTruncated?: boolean;
+	lengthLimited?: boolean;
+}
+export interface SideChatThread {
+	id: string;
+	title: string;
+	messages: SideChatMessage[];
+	draft: string;
+	model?: SideChatModel;
+	request?: { id: string; revision: number };
+	/** 最近一次回答的真实用量与窗口：面板右下角的上下文环用它 */
+	usage?: SideChatUsage;
+	contextWindow?: number;
+	/** 这次上下文的真实字符分项（系统提示词 / 引用的主会话背景） */
+	characters?: { systemPrompt: number; background: number };
+	connectionLost?: boolean;
+}
+export interface SideChatState {
+	currentThreadId: string;
+	threads: SideChatThread[];
+	storageFailed: boolean;
+}
+export const EMPTY_SIDE_CHAT: SideChatState = { currentThreadId: "", threads: [], storageFailed: false };
+const PREFIX = "piweb.sidechat.v1.";
+
+class ApiError extends Error {
+	constructor(message: string, readonly status: number) { super(message); }
+}
+
+function pause(ms: number, signal: AbortSignal): Promise<void> {
+	return new Promise((resolve) => {
+		const finish = () => { clearTimeout(timer); signal.removeEventListener("abort", finish); resolve(); };
+		const timer = setTimeout(finish, ms);
+		signal.addEventListener("abort", finish, { once: true });
+		if (signal.aborted) finish();
+	});
+}
+
+/** Browser-owned threads outlive panel unmounts. Only their own subscribers render on an answer update. */
+export class SideChatStore {
+	private states = new Map<string, SideChatState>();
+	private listeners = new Map<string, Set<() => void>>();
+	private requests = new Map<string, AbortController>();
+	private saves = new Map<string, ReturnType<typeof setTimeout>>();
+	constructor(private options: { fetch: typeof fetch; storage: () => Storage; id: () => string } = {
+		fetch: (...args) => fetch(...args), storage: () => localStorage, id: () => crypto.randomUUID(),
+	}) {}
+
+	get = (sessionId: string | null): SideChatState => {
+		if (!sessionId) return EMPTY_SIDE_CHAT;
+		let state = this.states.get(sessionId);
+		if (state) return state;
+		try {
+			const raw = this.options.storage().getItem(PREFIX + sessionId);
+			if (raw) {
+				const saved = JSON.parse(raw) as SideChatState;
+				if (isSideChatId(saved.currentThreadId) && Array.isArray(saved.threads) && saved.threads.length && saved.threads.every((thread) =>
+					isSideChatId(thread.id) && typeof thread.title === "string" && typeof thread.draft === "string" && Array.isArray(thread.messages) && thread.messages.every((message) =>
+						isSideChatId(message.id) && (message.role === "user" || message.role === "assistant") && typeof message.text === "string") &&
+					(!thread.request || (isSideChatId(thread.request.id) && Number.isSafeInteger(thread.request.revision)))) && saved.threads.some((thread) => thread.id === saved.currentThreadId)) {
+					state = { ...saved, storageFailed: false, threads: saved.threads.map((thread) => ({ ...thread, model: isSideChatModel(thread.model) ? thread.model : undefined })) };
+				}
+			}
+		} catch { /* A unavailable or full browser store must not disable questions. */ }
+		if (!state) {
+			const thread = this.newThread();
+			state = { currentThreadId: thread.id, threads: [thread], storageFailed: false };
+		}
+		this.states.set(sessionId, state);
+		return state;
+	};
+
+	flush = (): void => { for (const sessionId of this.states.keys()) this.save(sessionId); };
+
+	subscribe = (sessionId: string | null, listener: () => void): (() => void) => {
+		if (!sessionId) return () => {};
+		const listeners = this.listeners.get(sessionId) ?? new Set();
+		listeners.add(listener);
+		this.listeners.set(sessionId, listeners);
+		queueMicrotask(() => {
+			for (const thread of this.get(sessionId).threads) {
+				if (thread.request && !this.requests.has(thread.request.id)) void this.run(sessionId, thread.id, thread.request.id);
+			}
+		});
+		return () => { listeners.delete(listener); };
+	};
+
+	private newThread(model?: SideChatModel): SideChatThread { return { id: this.options.id(), title: "", messages: [], draft: "", ...(model ? { model: { ...model } } : {}) }; }
+	private notify(sessionId: string): void { for (const listener of this.listeners.get(sessionId) ?? []) listener(); }
+	private save(sessionId: string): void {
+		const timer = this.saves.get(sessionId);
+		if (timer) clearTimeout(timer);
+		this.saves.delete(sessionId);
+		const state = this.get(sessionId);
+		let failed = false;
+		try { this.options.storage().setItem(PREFIX + sessionId, JSON.stringify(state)); }
+		catch { failed = true; }
+		if (state.storageFailed !== failed) {
+			this.states.set(sessionId, { ...state, storageFailed: failed });
+			this.notify(sessionId);
+		}
+	}
+	private update(sessionId: string, state: SideChatState, immediately = false): void {
+		this.states.set(sessionId, state);
+		this.notify(sessionId);
+		if (immediately) this.save(sessionId);
+		else if (!this.saves.has(sessionId)) this.saves.set(sessionId, setTimeout(() => this.save(sessionId), 300));
+	}
+	private updateThread(sessionId: string, threadId: string, change: (thread: SideChatThread) => SideChatThread, immediately = false): void {
+		const state = this.get(sessionId);
+		this.update(sessionId, { ...state, threads: state.threads.map((thread) => thread.id === threadId ? change(thread) : thread) }, immediately);
+	}
+
+	setDraft(sessionId: string, text: string): void {
+		this.updateThread(sessionId, this.get(sessionId).currentThreadId, (thread) => ({ ...thread, draft: text }));
+	}
+	setModel(sessionId: string, model?: SideChatModel): void {
+		this.updateThread(sessionId, this.get(sessionId).currentThreadId, (thread) => ({ ...thread, model: model ? { ...model } : undefined }), true);
+	}
+	createThread(sessionId: string): void {
+		const state = this.get(sessionId);
+		const current = state.threads.find((thread) => thread.id === state.currentThreadId);
+		if (current && !current.messages.length && !current.draft) return;
+		const thread = this.newThread(current?.model);
+		this.update(sessionId, { ...state, currentThreadId: thread.id, threads: [...state.threads, thread] }, true);
+	}
+	selectThread(sessionId: string, threadId: string): void {
+		const state = this.get(sessionId);
+		if (state.threads.some((thread) => thread.id === threadId)) this.update(sessionId, { ...state, currentThreadId: threadId }, true);
+	}
+
+	send(sessionId: string, retry = false): void {
+		const state = this.get(sessionId);
+		const thread = state.threads.find((item) => item.id === state.currentThreadId);
+		if (!thread || thread.request) return;
+		const previous = thread.messages.at(-1);
+		const retrying = retry && previous?.role === "assistant" && previous.status === "error" && thread.messages.at(-2)?.role === "user";
+		const text = (retrying ? thread.messages.at(-2)!.text : thread.draft).trim();
+		if (!text) return;
+		const requestId = this.options.id();
+		const historyMessages = retrying ? thread.messages.slice(0, -2) : thread.messages;
+		const availableHistory: SideChatHistoryMessage[] = historyMessages.filter((message) => message.text && (message.role === "user" || message.status === "done" || message.status === "aborted"))
+			.map(({ role, text }) => ({ role, text }));
+		const { history, truncated } = requestHistory(availableHistory);
+		const messages: SideChatMessage[] = retrying
+			? [...thread.messages.slice(0, -1), { id: previous!.id, role: "assistant", text: "", status: "pending", contextTruncated: truncated }]
+			: [...thread.messages, { id: this.options.id(), role: "user", text }, { id: this.options.id(), role: "assistant", text: "", status: "pending", contextTruncated: truncated }];
+		this.updateThread(sessionId, thread.id, (item) => ({ ...item, title: item.title || text.slice(0, 80), messages, draft: retrying ? item.draft : "", request: { id: requestId, revision: -1 }, connectionLost: false }), true);
+		void this.run(sessionId, thread.id, requestId, { requestId, threadId: thread.id, text, history, ...(thread.model ? { model: { ...thread.model } } : {}) });
+	}
+
+	private apply(sessionId: string, threadId: string, requestId: string, progress: SideChatProgress): void {
+		this.updateThread(sessionId, threadId, (thread) => {
+			if (thread.request?.id !== requestId) return thread;
+			const previousText = thread.messages.at(-1)?.text ?? "";
+			if (progress.textOffset !== undefined && progress.textOffset > previousText.length) throw new Error("side-chat answer cursor is out of sync");
+			const text = progress.textOffset === undefined ? progress.text : previousText.slice(0, progress.textOffset) + progress.text;
+			const status = !progress.done ? "pending" : progress.error ? "error" : progress.aborted ? "aborted" : "done";
+			return {
+				...thread, connectionLost: false, request: progress.done ? undefined : { id: requestId, revision: progress.revision },
+				// 只在这次响应真的报了就更新；没报就保持上一次的值（不回落成 0）
+				...(progress.usage ? { usage: progress.usage } : {}),
+				...(progress.contextWindow ? { contextWindow: progress.contextWindow } : {}),
+				...(progress.characters ? { characters: progress.characters } : {}),
+				messages: thread.messages.map((message, index) => index === thread.messages.length - 1 ? {
+					...message, text, status, error: progress.error, contextTruncated: message.contextTruncated || progress.contextTruncated, lengthLimited: progress.lengthLimited,
+				} : message),
+			};
+		}, progress.done);
+	}
+	private fail(sessionId: string, threadId: string, requestId: string, error: string): void {
+		const thread = this.get(sessionId).threads.find((item) => item.id === threadId);
+		this.apply(sessionId, threadId, requestId, { requestId, revision: 0, text: thread?.messages.at(-1)?.text ?? "", done: true, aborted: false, error });
+	}
+	private async response(response: Response): Promise<SideChatProgress> {
+		const json = await response.json();
+		if (!response.ok || !json.success) throw new ApiError(json.error || `side-chat request failed (${response.status})`, response.status);
+		const data = json.data as SideChatProgress;
+		if (!data || !isSideChatId(data.requestId) || !Number.isSafeInteger(data.revision) || typeof data.text !== "string" || typeof data.done !== "boolean" || (data.textOffset !== undefined && (!Number.isSafeInteger(data.textOffset) || data.textOffset < 0))) throw new Error("invalid side-chat response");
+		return data;
+	}
+	private async run(sessionId: string, threadId: string, requestId: string, initial?: SideChatRequest): Promise<void> {
+		if (this.requests.has(requestId)) return;
+		const controller = new AbortController();
+		this.requests.set(requestId, controller);
+		const url = `/api/agent/${sessionId}/side-chat`;
+		let revision = this.get(sessionId).threads.find((thread) => thread.id === threadId)?.request?.revision ?? -1;
+		try {
+			if (initial) {
+				const progress = await this.response(await this.options.fetch(url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(initial), signal: controller.signal }));
+				if (progress.requestId !== requestId) throw new Error("side-chat response belongs to a different request");
+				if (controller.signal.aborted) return;
+				this.apply(sessionId, threadId, requestId, progress);
+				if (progress.done) return;
+				revision = progress.revision;
+			}
+			let failures = 0;
+			while (!controller.signal.aborted) {
+				let progress: SideChatProgress;
+				try {
+					progress = await this.response(await this.options.fetch(`${url}?requestId=${encodeURIComponent(requestId)}&after=${revision}`, { cache: "no-store", signal: controller.signal }));
+					if (progress.requestId !== requestId) throw new Error("side-chat response belongs to a different request");
+				} catch (error) {
+					if (controller.signal.aborted) return;
+					if (error instanceof ApiError || ++failures >= 6) throw error;
+					this.updateThread(sessionId, threadId, (thread) => ({ ...thread, connectionLost: true }));
+					await pause(Math.min(500 * 2 ** (failures - 1), 5000), controller.signal);
+					continue;
+				}
+				if (controller.signal.aborted) return;
+				failures = 0;
+				this.apply(sessionId, threadId, requestId, progress);
+				if (progress.done) return;
+				revision = progress.revision;
+			}
+		} catch (error) {
+			if (!controller.signal.aborted) this.fail(sessionId, threadId, requestId, error instanceof Error ? error.message : "side-chat request failed");
+		} finally {
+			if (this.requests.get(requestId) === controller) this.requests.delete(requestId);
+		}
+	}
+
+	stop(sessionId: string): void {
+		const thread = this.get(sessionId).threads.find((item) => item.id === this.get(sessionId).currentThreadId);
+		const requestId = thread?.request?.id;
+		if (!thread || !requestId) return;
+		this.requests.get(requestId)?.abort();
+		this.apply(sessionId, thread.id, requestId, { requestId, revision: 0, text: thread.messages.at(-1)?.text ?? "", done: true, aborted: true });
+		void this.options.fetch(`/api/agent/${sessionId}/side-chat?requestId=${encodeURIComponent(requestId)}`, { method: "DELETE" })
+			.then(async (response) => { if (!response.ok) throw new Error((await response.json()).error || "failed to stop side-chat answer"); })
+			.catch((error) => this.updateThread(sessionId, thread.id, (current) => ({ ...current, messages: current.messages.map((message) => message.id === thread.messages.at(-1)?.id ? { ...message, error: error instanceof Error ? error.message : "failed to stop side-chat answer" } : message) }), true));
+	}
+}
+
+export const sideChatStore = new SideChatStore();
+if (typeof window !== "undefined") window.addEventListener("pagehide", sideChatStore.flush);

package/src/hooks/useFileViewer.ts

@@ -8,11 +8,13 @@ import { useCallback, useState } from "react";
 
 export interface ViewerTab {
 	path: string;
-	/** 重命名前的路径（取 diff 用） */
+	/** 重命名前的路径(取 diff 用) */
 	from?: string;
-	/** 快照之外的文件（node_modules 等）：只能看磁盘上的当前内容 */
+	/** 快照之外的文件(node_modules 等):只能看磁盘上的当前内容 */
 	lazy?: boolean;
-	/** 内容由调用方直接提供（如技能文档）：不取 diff、不读磁盘 */
+	/** dir = 打开的是文件夹:正文区列目录(可逐层进入),不是文件内容 */
+	kind?: "dir" | "file";
+	/** 内容由调用方直接提供(如技能文档):不取 diff、不读磁盘 */
 	staticContent?: string;
 }
 
@@ -25,7 +27,7 @@ export interface ViewerState {
 
 export function useFileViewer() {
 	const [state, setState] = useState<ViewerState>({ open: false, tabs: [], active: null });
-	const open = useCallback((path: string, opts: { from?: string; lazy?: boolean } = {}) => {
+	const open = useCallback((path: string, opts: { from?: string; lazy?: boolean; kind?: "dir" | "file" } = {}) => {
 		setState((s) => {
 			const exists = s.tabs.some((tab) => tab.path === path);
 			const tabs = exists ? s.tabs.map((tab) => (tab.path === path ? { ...tab, ...opts } : tab)) : [...s.tabs, { path, ...opts }];

package/src/i18n.tsx

@@ -43,10 +43,15 @@ const zh = {
 	visionLabel: "视觉",
 	visionHint: "该模型能否接收图片。未声明时 pi 按纯文本处理：你贴的截图会被换成一行占位文字（提示语还会说成「模型不支持图像」）",
 	visionUnset: "未声明",
+	visionInputText: "文本",
+	visionInputTextHint: "pi 总是接受文本输入；贴图能不能发由「图片」决定",
+	visionInputImage: "图片",
+	visionInputImageHint: "勾上表示该模型能收图（写进 models.json 的 input）；不勾则按纯文本处理",
 	visionOn: "有视觉",
 	visionOff: "纯文本",
 	imagePreview: "点击放大预览",
 	imageViewer: "图片预览",
+	imageClearAll: "清空图片",
 	imagePrev: "上一张",
 	imageNext: "下一张",
 	chipExpandMore: "展开 {n}",
@@ -314,9 +319,9 @@ const zh = {
 	contextUsed: "上下文已用",
 	contextUnknown: "上下文用量未知",
 	contextEstimated: "上下文估算",
+	contextMeasured: "上下文用量",
+	contextBackground: "Main Conversation",
 	contextApiInput: "最近请求输入（API）",
-	contextCharacterBreakdown: "内容分类（字符数）",
-	contextCharacterHint: "按当前文本统计，图片不计。API 未提供分类 token 用量。",
 	contextChars: "字符",
 	contextSystem: "系统提示词",
 	contextMessages: "对话消息",
@@ -381,8 +386,6 @@ const zh = {
 	cacheHits: "缓存命中",
 	statsCounts: "{turns} 轮 · {steps} 步",
 	ttftAverage: "首 token 平均",
-	statsMeasuredSteps: "实时测量 {n} 步",
-	statsTimedCoverage: "{n}/{total} 条有计时",
 	inputTokens: "输入",
 	outputTokens: "输出",
 	// 视图
@@ -465,6 +468,21 @@ const zh = {
 	drawerPanel: "右侧抽屉",
 	drawerSections: "抽屉入口",
 	drawerPrompts: "提示词",
+	sideChat: "旁聊",
+	sideChatModel: "旁聊模型",
+	sideChatFollowMain: "跟随主会话",
+	sideChatNew: "新旁聊",
+	sideChatHistory: "旁聊记录",
+	sideChatMessages: "旁聊消息",
+	sideChatQuestion: "旁聊提问",
+	sideChatPlaceholder: "读到哪里有疑问，就在这里问…",
+	sideChatEmpty: "边读边问，主会话停在原处",
+	sideChatHint: "参考主会话，问答独立。记录仅保存在此浏览器。",
+	sideChatPickSession: "打开一个主会话后，就可以旁聊",
+	sideChatAnswering: "正在回答…",
+	sideChatContextTruncated: "背景较长，本次仅参考了部分主会话或旁聊记录。",
+	sideChatLengthLimited: "已达到本次输出上限，可以继续追问。",
+	sideChatStorageFailed: "浏览器未能保存旁聊记录，请先保留需要的内容。",
 	setPlugins: "插件",
 	setRemote: "远程连接",
 	remoteBuiltin: "内置插件",
@@ -721,6 +739,9 @@ const zh = {
 	viewerNotInSnapshot: "此文件不在快照里（超过 1MB 或被排除），显示磁盘上的当前内容",
 	viewerLoadFailed: "加载失败",
 	viewerEmpty: "从左侧树里选择一个文件",
+	viewerOpenFolder: "打开文件夹预览",
+	viewerDirHint: "文件夹：共 {n} 项（已按 .gitignore 过滤）",
+	viewerDirMore: "加载更多",
 	// 流式输出
 	streamStyleTitle: "流式输出样式",
 	streamStyleDesc: "回答逐字出现的方式；改完立刻生效，正在流出的回答也一并换",
@@ -781,10 +802,15 @@ const en: Dict = {
 	visionLabel: "Vision",
 	visionHint: "Whether this model accepts images. Left unset, pi treats it as text-only and replaces pasted screenshots with a placeholder line.",
 	visionUnset: "Not declared",
+	visionInputText: "Text",
+	visionInputTextHint: "pi always accepts text; whether images can be sent is decided by the Image box",
+	visionInputImage: "Image",
+	visionInputImageHint: "Checked means this model accepts images (written into models.json input); unchecked is treated as text-only",
 	visionOn: "Vision",
 	visionOff: "Text only",
 	imagePreview: "Click to preview",
 	imageViewer: "Image preview",
+	imageClearAll: "Clear images",
 	imagePrev: "Previous image",
 	imageNext: "Next image",
 	chipExpandMore: "Show {n} more",
@@ -1050,9 +1076,9 @@ const en: Dict = {
 	contextUsed: "context used",
 	contextUnknown: "Context usage unknown",
 	contextEstimated: "estimated context usage",
+	contextMeasured: "context usage",
+	contextBackground: "Main Conversation",
 	contextApiInput: "Last request input (API)",
-	contextCharacterBreakdown: "Content breakdown (characters)",
-	contextCharacterHint: "Counts current text; excludes images. The API does not report tokens by category.",
 	contextChars: "chars",
 	contextSystem: "System prompt",
 	contextMessages: "Messages",
@@ -1116,8 +1142,6 @@ const en: Dict = {
 	cacheHits: "cache hits",
 	statsCounts: "{turns} turns · {steps} steps",
 	ttftAverage: "TTFT avg",
-	statsMeasuredSteps: "{n} steps measured live",
-	statsTimedCoverage: "{n}/{total} entries timed",
 	inputTokens: "Input",
 	outputTokens: "Output",
 	tabChat: "Chat",
@@ -1196,6 +1220,21 @@ const en: Dict = {
 	drawerPanel: "Drawer",
 	drawerSections: "Drawer sections",
 	drawerPrompts: "Prompts",
+	sideChat: "Side chat",
+	sideChatModel: "Side-chat model",
+	sideChatFollowMain: "Follow main chat",
+	sideChatNew: "New side chat",
+	sideChatHistory: "Side-chat history",
+	sideChatMessages: "Side-chat messages",
+	sideChatQuestion: "Side-chat question",
+	sideChatPlaceholder: "Ask about anything you're reading…",
+	sideChatEmpty: "Ask as you read. Keep your place.",
+	sideChatHint: "Uses the main chat as background. Separate answers, saved only in this browser.",
+	sideChatPickSession: "Open a main conversation to start a side chat",
+	sideChatAnswering: "Answering…",
+	sideChatContextTruncated: "The background is long; this answer uses part of the main or side-chat history.",
+	sideChatLengthLimited: "This answer reached its output limit. You can ask it to continue.",
+	sideChatStorageFailed: "Your browser could not save the side chat. Keep a copy of anything you need.",
 	setPlugins: "Plugins",
 	setRemote: "Remote access",
 	remoteBuiltin: "Built-in plugin",
@@ -1451,6 +1490,9 @@ const en: Dict = {
 	viewerNotInSnapshot: "Not in the snapshot (over 1MB or excluded); showing the current content from disk",
 	viewerLoadFailed: "Failed to load",
 	viewerEmpty: "Pick a file from the tree on the left",
+	viewerOpenFolder: "Preview folder",
+	viewerDirHint: "Folder: {n} items (ignored files hidden)",
+	viewerDirMore: "Load more",
 	// Streaming text
 	streamStyleTitle: "Streaming text",
 	streamStyleDesc: "How the answer appears while it arrives; applies to the stream already running",