@rexvane/piweb 0.3.1

package/src/lib/security-service.ts

@@ -0,0 +1,52 @@
+/**
+ * security-service：pi 真实安全能力的 Web 面。
+ * - 工具预设（只读/标准/全部）→ pi 的 tools 白名单（agent-manager 应用）
+ * - 项目信任（settings.json 的 defaultProjectTrust：ask/always/never）
+ * pi 没有 OS 级沙箱与审批系统——不做假开关。
+ */
+import fs from "node:fs/promises";
+import path from "node:path";
+import { getAgentDir, getSettingsManager, reloadAllLoaders, reloadSettingsManagers, syncProjectTrust } from "./pi";
+import { reloadSessionsForCwd } from "./agent-manager";
+import { flushSettingsOrThrow, withSettingsWriteLock } from "./settings-write-lock";
+
+export type ProjectTrust = "ask" | "always" | "never";
+
+export async function getSecurity(): Promise<{ defaultProjectTrust: ProjectTrust }> {
+	let raw: string;
+	try {
+		raw = await fs.readFile(path.join(getAgentDir(), "settings.json"), "utf8");
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code === "ENOENT") return { defaultProjectTrust: "ask" };
+		throw error;
+	}
+	const parsed: unknown = JSON.parse(raw.replace(/^\uFEFF/, ""));
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("settings.json must contain a JSON object");
+	const trust = (parsed as { defaultProjectTrust?: unknown }).defaultProjectTrust;
+	return { defaultProjectTrust: trust === "always" || trust === "never" ? trust : "ask" };
+}
+
+export async function setProjectTrust(value: ProjectTrust): Promise<void> {
+	if (value !== "ask" && value !== "always" && value !== "never") throw new Error("invalid defaultProjectTrust");
+	await withSettingsWriteLock(path.join(getAgentDir(), "settings.json"), async () => {
+		await getSecurity(); // ENOENT only; malformed or unreadable settings must fail closed.
+		const manager = getSettingsManager(process.cwd());
+		await flushSettingsOrThrow(manager);
+		await manager.reload();
+		await flushSettingsOrThrow(manager);
+		// SDK 自己持有跨进程锁，只落修改字段；flush 不抛写错，必须显式 drainErrors。
+		manager.setDefaultProjectTrust(value);
+		await flushSettingsOrThrow(manager);
+		if ((await getSecurity()).defaultProjectTrust !== value) {
+			throw new Error("defaultProjectTrust was not persisted");
+		}
+		// Only a confirmed persisted change may alter loaders and active sessions.
+		await reloadSettingsManagers();
+		await flushSettingsOrThrow(manager);
+		syncProjectTrust();
+		await flushSettingsOrThrow(manager);
+		await reloadAllLoaders();
+		await flushSettingsOrThrow(manager);
+		await reloadSessionsForCwd();
+	});
+}

package/src/lib/semver.ts

@@ -0,0 +1,39 @@
+/**
+ * 版本号比较（设置页「检查更新」用）：主.次.修 按数字比，预发布段按 semver 规则比。
+ * 正式版高于同号预发布（0.4.0 > 0.4.0-beta.1）；预发布标识符数字按数值、字母按字典序、数字低于字母。
+ */
+export interface ParsedVersion {
+	nums: [number, number, number];
+	pre: string[];
+}
+
+export function parseVersion(value: string): ParsedVersion | null {
+	const m = value.trim().replace(/^v/i, "").match(/^(\d+)\.(\d+)(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?/);
+	if (!m) return null;
+	return { nums: [Number(m[1]), Number(m[2]), Number(m[3] ?? 0)], pre: m[4] ? m[4].split(".") : [] };
+}
+
+/** a 比 b 新才返回 true；任一方解析失败按「不比它新」处理 */
+export function isNewer(a: string, b: string): boolean {
+	const pa = parseVersion(a);
+	const pb = parseVersion(b);
+	if (!pa || !pb) return false;
+	for (let i = 0; i < 3; i += 1) if (pa.nums[i] !== pb.nums[i]) return pa.nums[i] > pb.nums[i];
+	if (!pa.pre.length || !pb.pre.length) return pa.pre.length === 0 && pb.pre.length > 0;
+	const n = Math.max(pa.pre.length, pb.pre.length);
+	for (let i = 0; i < n; i += 1) {
+		const x = pa.pre[i];
+		const y = pb.pre[i];
+		if (x === undefined) return false;
+		if (y === undefined) return true;
+		const nx = /^\d+$/.test(x);
+		const ny = /^\d+$/.test(y);
+		if (nx && ny) {
+			if (Number(x) !== Number(y)) return Number(x) > Number(y);
+			continue;
+		}
+		if (nx !== ny) return ny;
+		if (x !== y) return x > y;
+	}
+	return false;
+}

package/src/lib/session-reader.ts

@@ -0,0 +1,204 @@
+/**
+ * session-reader：枚举 / 搜索 / 冷读取 ~/.pi/agent/sessions/**.jsonl（pi 零改动）。
+ */
+import { createReadStream } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { SessionSummary, WebMessage } from "./types";
+import { toWebMessage } from "./agent-manager";
+import { getAgentDir } from "./pi";
+import { BoundaryError, isPathInside } from "./path-security";
+
+function toSummary(info: {
+	path: string;
+	name?: string;
+	cwd: string;
+	created: Date;
+	modified: Date;
+	messageCount: number;
+	firstMessage: string;
+}): SessionSummary {
+	return {
+		path: info.path,
+		name: info.name,
+		cwd: info.cwd,
+		created: info.created.toISOString(),
+		modified: info.modified.toISOString(),
+		messageCount: info.messageCount,
+		firstMessage: info.firstMessage,
+	};
+}
+
+/**
+ * 单个 JSONL → 摘要，与 SDK `SessionManager.listAll()` 的口径一致：
+ * 首行必须是 session 头；名字取最后一条 session_info；messageCount 计全部 message 条目；
+ * firstMessage 取首条用户消息的文本块；modified 取用户 / 助手消息的最后活动时间（没有就回落头时间戳、再回落 mtime）。
+ */
+async function summarize(filePath: string, stat: { mtime: Date }): Promise<SessionSummary | null> {
+	try {
+		let header: { cwd?: unknown; timestamp?: unknown } | null = null;
+		let name: string | undefined;
+		let messageCount = 0;
+		let firstMessage = "";
+		let lastActivity: number | undefined;
+		const rl = createInterface({ input: createReadStream(filePath, { encoding: "utf8" }), crlfDelay: Infinity });
+		for await (const line of rl) {
+			if (!line.trim()) continue;
+			let entry: any;
+			try {
+				entry = JSON.parse(line);
+			} catch {
+				continue;
+			}
+			if (!header) {
+				if (entry?.type !== "session") return null;
+				header = entry;
+				continue;
+			}
+			if (entry?.type === "session_info") name = typeof entry.name === "string" && entry.name.trim() ? entry.name.trim() : undefined;
+			if (entry?.type !== "message") continue;
+			messageCount += 1;
+			const message = entry.message;
+			if (!message || typeof message.role !== "string" || !("content" in message)) continue;
+			if (message.role !== "user" && message.role !== "assistant") continue;
+			const at = typeof message.timestamp === "number" ? message.timestamp : new Date(entry.timestamp).getTime();
+			if (Number.isFinite(at)) lastActivity = Math.max(lastActivity ?? 0, at);
+			if (!firstMessage && message.role === "user") {
+				const content = message.content;
+				firstMessage = typeof content === "string"
+					? content
+					: Array.isArray(content) ? content.filter((b: any) => b?.type === "text").map((b: any) => b.text).join(" ") : "";
+			}
+		}
+		if (!header) return null;
+		const headerTime = typeof header.timestamp === "string" ? new Date(header.timestamp).getTime() : NaN;
+		const modified = lastActivity && lastActivity > 0 ? new Date(lastActivity) : !Number.isNaN(headerTime) ? new Date(headerTime) : stat.mtime;
+		return toSummary({
+			path: filePath,
+			name,
+			cwd: typeof header.cwd === "string" ? header.cwd : "",
+			created: new Date(String(header.timestamp)),
+			modified,
+			messageCount,
+			firstMessage: firstMessage || "(no messages)",
+		});
+	} catch {
+		return null;
+	}
+}
+
+/** 按文件缓存的摘要：mtime 与大小都没变就不重读（侧栏每 3 秒轮询一次，全盘重读几 MB JSONL 太浪费） */
+const summaryCache = new Map<string, { mtimeMs: number; size: number; summary: SessionSummary | null }>();
+/** 并发列表请求共用一次扫描 */
+let scanning: Promise<SessionSummary[]> | null = null;
+
+async function scanSessions(): Promise<SessionSummary[]> {
+	const root = path.join(getAgentDir(), "sessions");
+	const files: string[] = [];
+	let dirs: import("node:fs").Dirent[] = [];
+	try {
+		dirs = await fs.readdir(root, { withFileTypes: true });
+	} catch {
+		return [];
+	}
+	await Promise.all(dirs.filter((d) => d.isDirectory() || d.isSymbolicLink()).map(async (d) => {
+		try {
+			for (const f of await fs.readdir(path.join(root, d.name))) if (f.endsWith(".jsonl")) files.push(path.join(root, d.name, f));
+		} catch {
+			/* 目录读不了就跳过 */
+		}
+	}));
+	const seen = new Set<string>();
+	const out: SessionSummary[] = [];
+	const BATCH = 16;
+	for (let i = 0; i < files.length; i += BATCH) {
+		await Promise.all(files.slice(i, i + BATCH).map(async (file) => {
+			seen.add(file);
+			const stat = await fs.stat(file).catch(() => null);
+			if (!stat?.isFile()) return;
+			const cached = summaryCache.get(file);
+			if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) {
+				if (cached.summary) out.push(cached.summary);
+				return;
+			}
+			const summary = await summarize(file, stat);
+			summaryCache.set(file, { mtimeMs: stat.mtimeMs, size: stat.size, summary });
+			if (summary) out.push(summary);
+		}));
+	}
+	for (const key of summaryCache.keys()) if (!seen.has(key)) summaryCache.delete(key);
+	return out;
+}
+
+/** 列表短缓存：多标签每 3 秒各轮询一次，1.2 秒 TTL 吸收并发请求 */
+let listCache: { at: number; list: SessionSummary[] } | null = null;
+
+export async function listSessions(query?: string): Promise<SessionSummary[]> {
+	let list: SessionSummary[];
+	if (listCache && Date.now() - listCache.at < 1200) {
+		list = listCache.list;
+	} else {
+		scanning ??= scanSessions().finally(() => { scanning = null; });
+		list = await scanning;
+		listCache = { at: Date.now(), list };
+	}
+	if (query?.trim()) {
+		const q = query.trim().toLowerCase();
+		list = list.filter(
+			(s) =>
+				s.name?.toLowerCase().includes(q) ||
+				s.firstMessage.toLowerCase().includes(q) ||
+				s.cwd.toLowerCase().includes(q),
+		);
+	}
+	// 同一时间戳的会话按路径定序：扫描是并发的，顺序不固定会让 ETag 抖动、侧栏顺序跳动
+	list.sort((a, b) => b.modified.localeCompare(a.modified) || a.path.localeCompare(b.path));
+	return list;
+}
+
+export async function deleteSession(sessionPath: string): Promise<void> {
+	const root = path.join(getAgentDir(), "sessions");
+	const realRoot = await fs.realpath(root).catch(() => path.resolve(root));
+	const target = path.resolve(sessionPath);
+	if (path.extname(target).toLowerCase() !== ".jsonl" || !isPathInside(path.resolve(root), target)) {
+		throw new BoundaryError("session path is outside the Pi session store");
+	}
+	const realTarget = await fs.realpath(target).catch((error: NodeJS.ErrnoException) => {
+		if (error.code === "ENOENT") return target;
+		throw error;
+	});
+	if (realTarget !== target && !isPathInside(realRoot, realTarget)) throw new BoundaryError("session path escapes the Pi session store");
+	try {
+		await fs.unlink(target);
+	} catch (error) {
+		// 未落盘的惰性会话（还没发过消息）本来就没有文件，删除视为成功
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+}
+
+/** 冷读取：还原上下文消息 + 会话名（不启动 agent） */
+export async function readSession(sessionPath: string): Promise<{
+	cwd: string;
+	name: string;
+	messages: WebMessage[];
+}> {
+	const sm = SessionManager.open(sessionPath);
+	let messages: WebMessage[] = [];
+	try {
+		const entries = sm.buildContextEntries();
+		messages = entries
+			.filter((e: any) => e.type === "message" && e.message)
+			.map((e: any) => toWebMessage(e.message, e.id));
+	} catch {
+		messages = [];
+	}
+	let name = "";
+	try {
+		name = (sm as unknown as { getSessionName?: () => string }).getSessionName?.() ?? "";
+	} catch {
+		name = "";
+	}
+	return { cwd: sm.getCwd(), name, messages };
+}

package/src/lib/settings-write-lock.ts

@@ -0,0 +1,45 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import lockfile from "proper-lockfile";
+import type { SettingsManager } from "@earendil-works/pi-coding-agent";
+
+const pending = new Map<string, Promise<void>>();
+
+/** Serialize in-process read/modify/write operations on the same Pi settings file. */
+export function withSettingsWriteLock<T>(file: string, operation: () => Promise<T>): Promise<T> {
+	const resolved = path.resolve(file);
+	const key = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+	const previous = pending.get(key) ?? Promise.resolve();
+	const result = previous.then(operation, operation);
+	const settled = result.then(() => undefined, () => undefined);
+	pending.set(key, settled);
+	void settled.then(() => {
+		if (pending.get(key) === settled) pending.delete(key);
+	});
+	return result;
+}
+
+/** Match the SDK's settings.json.lock protocol for PiWeb's manual JSON writes. */
+export async function withExternalSettingsLock<T>(file: string, operation: () => Promise<T>): Promise<T> {
+	await fs.mkdir(path.dirname(file), { recursive: true });
+	const release = await lockfile.lock(file, {
+		realpath: false,
+		retries: { retries: 20, minTimeout: 20, maxTimeout: 100 },
+	});
+	try {
+		return await operation();
+	} finally {
+		await release();
+	}
+}
+
+/** SDK setters enqueue writes and record failures instead of rejecting flush(). */
+export async function flushSettingsOrThrow(manager: Pick<SettingsManager, "flush" | "drainErrors">): Promise<void> {
+	await manager.flush();
+	const errors = manager.drainErrors();
+	if (errors.length) {
+		throw new Error(`Pi settings failed: ${errors.map(({ scope, error }) => `${scope}: ${error.message}`).join("; ")}`, {
+			cause: errors[0].error,
+		});
+	}
+}

package/src/lib/skills-service.ts

@@ -0,0 +1,97 @@
+/**
+ * skills-service：技能发现（全局/项目/pi 包）+ SKILL.md frontmatter 开关。
+ * 开关实现：外科手术式改写 `disable-model-invocation`，其余 YAML 原样保留，然后 reload 加载器。
+ */
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { getAgentDir, getResourceLoader, reloadAllLoaders, resourceLoaderReady } from "./pi";
+import { reloadSessionsForCwd } from "./agent-manager";
+import { resolveDiscoveredPath } from "./path-security";
+
+export interface SkillView {
+	name: string;
+	description: string;
+	filePath: string;
+	disabled: boolean;
+	scope: "global" | "project" | "package";
+	baseDir: string;
+}
+
+function classifyScope(filePath: string, cwd?: string): SkillView["scope"] {
+	const norm = filePath.replace(/\\/g, "/").toLowerCase();
+	const agentDir = getAgentDir().replace(/\\/g, "/").toLowerCase();
+	const home = os.homedir().replace(/\\/g, "/").toLowerCase();
+	if (norm.startsWith(`${agentDir}/`) || norm.startsWith(`${home}/.agents/`) || norm.startsWith(`${home}/.pi/`))
+		return "global";
+	if (cwd && norm.startsWith(path.resolve(cwd).replace(/\\/g, "/").toLowerCase())) return "project";
+	if (norm.includes("/node_modules/")) return "package";
+	return "package";
+}
+
+export async function listSkills(cwd?: string): Promise<SkillView[]> {
+	const seen = new Set<string>();
+	const out: SkillView[] = [];
+	const targets: string[] = cwd ? [path.resolve(cwd)] : [process.cwd()];
+	for (const dir of targets) {
+		await resourceLoaderReady(dir);
+		const loader = getResourceLoader(dir);
+		const { skills } = loader.getSkills();
+		for (const s of skills) {
+			if (seen.has(s.filePath)) continue;
+			seen.add(s.filePath);
+			out.push({
+				name: s.name,
+				description: s.description,
+				filePath: s.filePath,
+				disabled: s.disableModelInvocation,
+				scope: classifyScope(s.filePath, dir),
+				baseDir: s.baseDir,
+			});
+		}
+	}
+	out.sort((a, b) => a.name.localeCompare(b.name));
+	return out;
+}
+
+/** 在 SKILL.md 的 YAML frontmatter 中精确改写一个布尔键，保留其余行 */
+function toggleFrontmatterKey(content: string, key: string, value: boolean): string {
+	const m = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+	if (!m) return content;
+	const lines = m[1].split(/\r?\n/);
+	const pattern = new RegExp(`^\\s*${key}\\s*:`);
+	let replaced = false;
+	const next = lines.map((line) => {
+		if (pattern.test(line)) {
+			replaced = true;
+			return value ? `${key}: true` : `${key}: false`;
+		}
+		return line;
+	});
+	if (!replaced) {
+		if (value) next.push(`${key}: true`);
+	}
+	if (!replaced && !value) return content; // 本来就没有且要关 → 无需改动
+	const body = content.slice(m[0].length);
+	return `---\n${next.join("\n")}\n---${body}`;
+}
+
+export async function setSkillDisabled(filePath: string, disabled: boolean, cwd?: string): Promise<{ changed: boolean }> {
+	const skills = await listSkills(cwd);
+	const authorized = await resolveDiscoveredPath(filePath, skills.map((skill) => skill.filePath));
+	const content = await fs.readFile(authorized, "utf8");
+	const next = toggleFrontmatterKey(content, "disable-model-invocation", disabled);
+	if (next === content) return { changed: false };
+	await fs.writeFile(authorized, next, "utf8");
+	// 就地重载加载器并让活跃会话重建系统提示（技能列表在系统提示里）；全局技能影响所有目录
+	await reloadAllLoaders();
+	const scope = classifyScope(authorized, cwd);
+	await reloadSessionsForCwd(scope === "project" ? cwd : undefined);
+	return { changed: true };
+}
+
+export async function readSkillFile(filePath: string, cwd?: string): Promise<string> {
+	const skills = await listSkills(cwd);
+	const authorized = await resolveDiscoveredPath(filePath, skills.map((skill) => skill.filePath));
+	return fs.readFile(authorized, "utf8");
+}

package/src/lib/text-sanitize.ts

@@ -0,0 +1,20 @@
+export interface SanitizedToolOutput {
+	text: string;
+	encodingLoss: boolean;
+}
+
+/**
+ * Legacy Windows PowerShell sessions may contain U+FFFD because output bytes
+ * were decoded before PowerShell switched to UTF-8. The original bytes are no
+ * longer recoverable, so retain readable lines and flag the loss for the UI.
+ */
+export function sanitizeToolOutput(value: string): SanitizedToolOutput {
+	if (!value.includes("\uFFFD")) return { text: value, encodingLoss: false };
+	const readableLines = value
+		.split(/\r?\n/)
+		.filter((line) => !line.includes("\uFFFD"));
+	return {
+		text: readableLines.join("\n").replace(/\n{3,}/g, "\n\n").trim(),
+		encodingLoss: true,
+	};
+}

package/src/lib/theme.ts

@@ -0,0 +1,137 @@
+/**
+ * 外观 = pebrel 配色主题对（https://github.com/Kuddev/pebrel）
+ *      + dsh 亮暗模式三选一（light / dark / system，见 dsh ui-theme 的 theme-settings.ts）。
+ * 两者独立持久化：配色 piweb.pebrelTheme，亮暗 piweb.theme。
+ */
+
+export type PebrelTheme =
+	| 'silver-steel'
+	| 'limestone-coal'
+	| 'linen-moss'
+	| 'nord-paper'
+	| 'pebrel'
+	| 'dsh';
+
+/** dsh 的 THEME_PREFERENCES：浅色/深色/跟随系统 */
+export type ThemeMode = 'light' | 'dark' | 'system';
+
+export const PEBREL_THEME_IDS: PebrelTheme[] = [
+	'dsh',
+	'silver-steel',
+	'limestone-coal',
+	'linen-moss',
+	'nord-paper',
+	'pebrel',
+];
+
+export const THEME_MODES: ThemeMode[] = ['light', 'dark', 'system'];
+
+export const DEFAULT_PEBREL_THEME: PebrelTheme = 'dsh';
+export const DEFAULT_THEME_MODE: ThemeMode = 'system';
+
+const THEME_KEY = 'piweb.pebrelTheme';
+const MODE_KEY = 'piweb.theme';
+
+export function isPebrelTheme(value: string | null): value is PebrelTheme {
+	return !!value && (PEBREL_THEME_IDS as string[]).includes(value);
+}
+
+export function isThemeMode(value: string | null): value is ThemeMode {
+	return !!value && (THEME_MODES as string[]).includes(value);
+}
+
+export function loadPebrelTheme(): PebrelTheme {
+	if (typeof window === 'undefined') return DEFAULT_PEBREL_THEME;
+	try {
+		const saved = localStorage.getItem(THEME_KEY);
+		if (isPebrelTheme(saved)) return saved;
+	} catch {
+		/* ignore */
+	}
+	return DEFAULT_PEBREL_THEME;
+}
+
+export function loadThemeMode(): ThemeMode {
+	if (typeof window === 'undefined') return DEFAULT_THEME_MODE;
+	try {
+		const saved = localStorage.getItem(MODE_KEY);
+		if (isThemeMode(saved)) return saved;
+	} catch {
+		/* ignore */
+	}
+	return DEFAULT_THEME_MODE;
+}
+
+/** 亮暗模式解析为实际值：system 跟随系统媒体查询（dsh getEffectiveTheme 语义） */
+export function getEffectiveMode(mode: ThemeMode): 'light' | 'dark' {
+	if (mode === 'system') {
+		if (typeof window === 'undefined' || !window.matchMedia) return 'dark';
+		return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+	}
+	return mode;
+}
+
+function applyLightDark(mode: ThemeMode): void {
+	if (typeof window === 'undefined') return;
+	const isDark = getEffectiveMode(mode) === 'dark';
+	const root = document.documentElement;
+	const body = document.body;
+	if (isDark) {
+		root.setAttribute('data-ds-dark-theme', '');
+		root.removeAttribute('data-ds-light-theme');
+		body?.setAttribute('data-ds-dark-theme', '');
+		body?.removeAttribute('data-ds-light-theme');
+	} else {
+		root.removeAttribute('data-ds-dark-theme');
+		root.setAttribute('data-ds-light-theme', '');
+		body?.removeAttribute('data-ds-dark-theme');
+		body?.setAttribute('data-ds-light-theme', '');
+	}
+	root.style.colorScheme = isDark ? 'dark' : 'light';
+}
+
+function applyFontSize(): void {
+	try {
+		// 界面字号：驱动 body/导航/标签等（--dsh-content-font-size + delta）
+		const fs = localStorage.getItem('piweb.fontSize');
+		if (fs) {
+			const n = Math.max(12, Math.min(18, parseInt(fs, 10) || 14));
+			document.documentElement.style.setProperty('--dsh-content-font-size', `${n}px`);
+			document.documentElement.style.setProperty('--dsh-content-font-delta', `${n - 14}px`);
+		}
+		// 对话字号：只作用于消息正文/用户气泡/输入框（.md 等），缺省回落界面字号
+		const chatFs = localStorage.getItem('piweb.chatFontSize');
+		if (chatFs) {
+			const n = Math.max(12, Math.min(20, parseInt(chatFs, 10) || 14));
+			document.documentElement.style.setProperty('--piweb-chat-font-size', `${n}px`);
+		}
+	} catch {
+		/* ignore */
+	}
+}
+
+export function applyPebrelTheme(theme: PebrelTheme, mode?: ThemeMode): void {
+	if (typeof window === 'undefined') return;
+	const effectiveMode = mode ?? loadThemeMode();
+	if (theme === 'dsh') {
+		// dsh 经典配色 = 项目基础变量，移除 pebrel 覆盖
+		document.documentElement.removeAttribute('data-pebrel-theme');
+		document.body?.removeAttribute('data-pebrel-theme');
+	} else {
+		document.documentElement.setAttribute('data-pebrel-theme', theme);
+		document.body?.setAttribute('data-pebrel-theme', theme);
+	}
+	applyLightDark(effectiveMode);
+	applyFontSize();
+	try {
+		localStorage.setItem(THEME_KEY, theme);
+		localStorage.setItem(MODE_KEY, effectiveMode);
+	} catch {
+		/* ignore */
+	}
+}
+
+/** 系统亮暗变化 / 跨标签同步时重放当前外观 */
+export function syncPebrelTheme(): void {
+	applyPebrelTheme(loadPebrelTheme(), loadThemeMode());
+}