dsh-browser-playwright-codex 0.7.2 → 0.7.5

package/lib/cache-clean.js

@@ -0,0 +1,386 @@
+/**
+ * Cache-residue scanning and cleaning for the Settings card.
+ *
+ * Design rules (these are the safety boundary, not implementation details):
+ * - **Targets are enum ids, never paths.** The caller can only ask for
+ *   `browser-cache` / `temp-residue` / `updater-residue` / `attachment-cache`;
+ *   every path below is derived here from DSH_HOME and known OS locations, so a
+ *   request can never point deletion at an arbitrary directory.
+ * - **Whitelist only.** Inside the browser profile only Chromium's pure caches
+ *   are touched; Cookies, Local Storage, Service Worker, IndexedDB, Network,
+ *   Preferences and Login Data are never opened.
+ * - **Rename before delete.** A directory that is in use fails the rename on
+ *   Windows; that is treated as "in use" and reported instead of retried.
+ * - **Count after success.** Bytes are measured before removal but only added to
+ *   `freedBytes` once the entry is confirmed gone — the earlier disk-cleanup rule
+ *   "count += size before deleting and swallow errors" produced fake accounting.
+ * - Pure `node:fs` — no dependencies, so it is testable without a DSH host.
+ *
+ * @module dsh-browser-playwright-codex/cache-clean
+ */
+import { chmod, lstat, readdir, rename, rm } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+/** Display order and labels for every target. */
+export const TARGETS = [
+    { id: 'browser-cache', label: '浏览器缓存' },
+    { id: 'temp-residue', label: '临时残留' },
+    { id: 'updater-residue', label: '更新器残留' },
+    { id: 'attachment-cache', label: '图片变体缓存' },
+];
+/** Is this value one of the enum ids? Unknown strings are rejected, never joined into a path. */
+export function isTargetId(value) {
+    return typeof value === 'string' && TARGETS.some((target) => target.id === value);
+}
+/** Resolve the default paths from the environment (no path ever comes from the request). */
+export function resolvePaths(env = process.env, version, platform = process.platform) {
+    const home = env.DSH_HOME !== undefined && env.DSH_HOME !== '' ? env.DSH_HOME : join(homedir(), '.dsh');
+    const profileOverride = env.DSH_BROWSER_PROFILE_DIR;
+    const localAppData = env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local');
+    return {
+        dshHome: home,
+        browserProfileDir: profileOverride !== undefined && profileOverride !== ''
+            ? profileOverride
+            : join(home, 'browser-profiles', 'playwright'),
+        tmpDir: tmpdir(),
+        updaterDir: join(localAppData, '@deepseek-aidsh-desktop-updater'),
+        installedVersion: version,
+    };
+}
+/** Chromium's pure caches. Everything else in the profile is off limits. */
+const BROWSER_CACHE_DIRS = [
+    'Cache',
+    'Code Cache',
+    'GPUCache',
+    'ShaderCache',
+    'GrShaderCache',
+    'DawnCache',
+    'DawnGraphiteCache',
+    'ScriptCache',
+];
+/** Temp entries this plugin and the harness leave behind. */
+const TEMP_PREFIXES = [
+    'dsh-browser-state-',
+    'dsh-provider-state-',
+    'dsh-subprocess-',
+    'dsh-spill-',
+    'dsh-acl-skill-',
+    'dsh-login-state-',
+];
+/** A temp entry younger than this is assumed to belong to a running task. */
+const TEMP_MIN_AGE_MS = 30 * 60 * 1000;
+/** Measure a file or directory tree. Missing paths measure as zero. */
+async function measure(path) {
+    const st = await lstat(path).catch(() => undefined);
+    if (st === undefined)
+        return { bytes: 0, files: 0 };
+    if (!st.isDirectory())
+        return { bytes: st.size, files: 1 };
+    let bytes = 0;
+    let files = 0;
+    const stack = [path];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        if (dir === undefined)
+            break;
+        const entries = await readdir(dir, { withFileTypes: true }).catch(() => undefined);
+        if (entries === undefined)
+            continue;
+        for (const entry of entries) {
+            const child = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                stack.push(child);
+                continue;
+            }
+            const size = await lstat(child).catch(() => undefined);
+            if (size !== undefined) {
+                bytes += size.size;
+                files += 1;
+            }
+        }
+    }
+    return { bytes, files };
+}
+/** Windows refuses to delete read-only files even with `force`; clear the attribute first. */
+async function makeWritable(path) {
+    const st = await lstat(path).catch(() => undefined);
+    if (st === undefined)
+        return;
+    if (st.isDirectory()) {
+        const entries = await readdir(path).catch(() => []);
+        for (const name of entries)
+            await makeWritable(join(path, name));
+        await chmod(path, 0o777).catch(() => undefined);
+        return;
+    }
+    await chmod(path, 0o666).catch(() => undefined);
+}
+/** Remove an entry, retrying once after clearing read-only attributes. */
+async function removeEntry(path) {
+    try {
+        await rm(path, { recursive: true, force: true, maxRetries: 2 });
+    }
+    catch {
+        await makeWritable(path);
+        await rm(path, { recursive: true, force: true, maxRetries: 2 }).catch(() => undefined);
+    }
+    return (await lstat(path).catch(() => undefined)) === undefined;
+}
+/**
+ * Detach an entry by renaming it first, then delete the renamed copy.
+ * A rename failure means something holds it open (Windows locks the directory),
+ * which is exactly the "in use" signal we want instead of guessing.
+ */
+async function detachAndRemove(path) {
+    const detached = `${path}.dsh-delete-${process.pid}-${Date.now()}`;
+    try {
+        await rename(path, detached);
+    }
+    catch {
+        return { ok: false, reason: 'in-use' };
+    }
+    const removed = await removeEntry(detached);
+    return removed ? { ok: true } : { ok: false, reason: 'permission' };
+}
+/** Browser-profile cache directories that currently exist. */
+async function browserCacheDirs(profileDir) {
+    const defaultDir = join(profileDir, 'Default');
+    const entries = await readdir(defaultDir, { withFileTypes: true }).catch(() => undefined);
+    if (entries === undefined)
+        return [];
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((name) => BROWSER_CACHE_DIRS.includes(name) || /_crx_cache$/.test(name))
+        .map((name) => join(defaultDir, name));
+}
+/** Temp entries matching the known residue prefixes. */
+async function tempResidueDirs(tmpDir) {
+    const entries = await readdir(tmpDir, { withFileTypes: true }).catch(() => undefined);
+    if (entries === undefined)
+        return [];
+    return entries
+        .filter((entry) => entry.isDirectory())
+        .filter((entry) => TEMP_PREFIXES.some((prefix) => entry.name.startsWith(prefix)))
+        .map((entry) => join(tmpDir, entry.name));
+}
+/** Updater files that belong to the currently installed version. */
+async function updaterResidue(updaterDir, installedVersion) {
+    const files = [];
+    const skipped = [];
+    const entries = await readdir(updaterDir, { withFileTypes: true }).catch(() => undefined);
+    if (entries === undefined)
+        return { files, skipped };
+    const versionFrom = (name) => {
+        const match = /(\d+\.\d+\.\d+(?:-[0-9A-Za-z.]+)?)/.exec(name);
+        return match?.[1];
+    };
+    for (const entry of entries) {
+        const path = join(updaterDir, entry.name);
+        if (entry.isDirectory()) {
+            // Only `pending/` is updater residue; the directory itself stays.
+            if (entry.name !== 'pending')
+                continue;
+            const pending = await readdir(path, { withFileTypes: true }).catch(() => []);
+            for (const child of pending) {
+                if (!child.isFile())
+                    continue;
+                const childPath = join(path, child.name);
+                const version = versionFrom(child.name);
+                if (version === undefined)
+                    skipped.push({ path: childPath, reason: 'unknown-version' });
+                else if (version !== installedVersion)
+                    skipped.push({ path: childPath, reason: 'other-version' });
+                else
+                    files.push(childPath);
+            }
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const isUpdaterFile = /^installer.*\.exe$/i.test(entry.name) || /\.blockmap$/i.test(entry.name);
+        if (!isUpdaterFile)
+            continue;
+        const version = versionFrom(entry.name);
+        if (version === undefined) {
+            skipped.push({ path, reason: 'unknown-version' });
+            continue;
+        }
+        if (version !== installedVersion) {
+            skipped.push({ path, reason: 'other-version' });
+            continue;
+        }
+        files.push(path);
+    }
+    return { files, skipped };
+}
+/** Everything under the request-image cache (kept apart from session attachments). */
+async function attachmentCacheFiles(dshHome) {
+    const root = join(dshHome, 'cache', 'attachments');
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => undefined);
+    if (entries === undefined)
+        return [];
+    return entries.map((entry) => join(root, entry.name));
+}
+/**
+ * Inspect every bucket without touching anything.
+ * @param paths - resolved locations
+ * @returns per-target sizes plus the attachment totals kept apart from the cache
+ */
+export async function scan(paths) {
+    const items = [];
+    const skipped = [];
+    const browserDirs = await browserCacheDirs(paths.browserProfileDir);
+    const browser = { bytes: 0, files: 0 };
+    for (const dir of browserDirs) {
+        const own = await measure(dir);
+        browser.bytes += own.bytes;
+        browser.files += own.files;
+    }
+    items.push({ id: 'browser-cache', label: '浏览器缓存', ...browser });
+    const temp = { bytes: 0, files: 0 };
+    for (const dir of await tempResidueDirs(paths.tmpDir)) {
+        const own = await measure(dir);
+        temp.bytes += own.bytes;
+        temp.files += own.files;
+    }
+    items.push({ id: 'temp-residue', label: '临时残留', ...temp });
+    const updater = await updaterResidue(paths.updaterDir, paths.installedVersion);
+    const updaterSize = { bytes: 0, files: 0 };
+    for (const file of updater.files) {
+        const own = await measure(file);
+        updaterSize.bytes += own.bytes;
+        updaterSize.files += own.files;
+    }
+    items.push({
+        id: 'updater-residue',
+        label: '更新器残留',
+        ...updaterSize,
+        ...(updater.skipped.length > 0 ? { note: `${String(updater.skipped.length)} 项属于其它版本，跳过` } : {}),
+    });
+    const attachments = await measure(join(paths.dshHome, 'cache', 'attachments'));
+    items.push({
+        id: 'attachment-cache',
+        label: '图片变体缓存',
+        ...attachments,
+        note: '发给模型前的缩放副本，可重建',
+    });
+    const objects = await measure(join(paths.dshHome, 'attachments', 'v1', 'objects'));
+    const requestImages = attachments;
+    return {
+        items,
+        totalBytes: items.reduce((sum, item) => sum + item.bytes, 0),
+        attachments: { objectsBytes: objects.bytes, requestImagesBytes: requestImages.bytes },
+        skipped,
+    };
+}
+/**
+ * Clean the requested buckets. With `dryRun` the same walk happens but nothing
+ * is renamed or removed, so the preview shows real numbers.
+ *
+ * @param options - resolved paths, enum targets and dry-run flag
+ * @returns per-target freed bytes and every skipped entry with a reason
+ */
+export async function clean(options) {
+    const now = options.now ?? Date.now();
+    const perTarget = [];
+    let freedBytes = 0;
+    for (const id of options.targets) {
+        const report = { id, freedBytes: 0, skipped: [] };
+        if (id === 'browser-cache') {
+            for (const dir of await browserCacheDirs(options.browserProfileDir)) {
+                const size = await measure(dir);
+                if (options.dryRun) {
+                    report.freedBytes += size.bytes;
+                    continue;
+                }
+                const outcome = await detachAndRemove(dir);
+                if (outcome.ok)
+                    report.freedBytes += size.bytes;
+                else
+                    report.skipped.push({ path: dir, reason: outcome.reason ?? 'permission' });
+            }
+        }
+        if (id === 'temp-residue') {
+            for (const dir of await tempResidueDirs(options.tmpDir)) {
+                const stat = await lstat(dir).catch(() => undefined);
+                const age = stat === undefined ? 0 : now - stat.mtimeMs;
+                const size = await measure(dir);
+                if (stat !== undefined && age < TEMP_MIN_AGE_MS) {
+                    // Too fresh to tell "left behind" from "this run is using it": prove it by
+                    // renaming first; only a successful rename means the owner let go.
+                    if (options.dryRun) {
+                        report.skipped.push({ path: dir, reason: 'in-use' });
+                        continue;
+                    }
+                    const outcome = await detachAndRemove(dir);
+                    if (outcome.ok)
+                        report.freedBytes += size.bytes;
+                    else
+                        report.skipped.push({ path: dir, reason: outcome.reason ?? 'in-use' });
+                    continue;
+                }
+                if (options.dryRun) {
+                    report.freedBytes += size.bytes;
+                    continue;
+                }
+                const outcome = await detachAndRemove(dir);
+                if (outcome.ok)
+                    report.freedBytes += size.bytes;
+                else
+                    report.skipped.push({ path: dir, reason: outcome.reason ?? 'permission' });
+            }
+        }
+        if (id === 'updater-residue') {
+            const residue = await updaterResidue(options.updaterDir, options.installedVersion);
+            for (const skipped of residue.skipped)
+                report.skipped.push(skipped);
+            for (const file of residue.files) {
+                const size = await measure(file);
+                if (options.dryRun) {
+                    report.freedBytes += size.bytes;
+                    continue;
+                }
+                const removed = await removeEntry(file);
+                if (removed)
+                    report.freedBytes += size.bytes;
+                else
+                    report.skipped.push({ path: file, reason: 'permission' });
+            }
+        }
+        if (id === 'attachment-cache') {
+            for (const path of await attachmentCacheFiles(options.dshHome)) {
+                const size = await measure(path);
+                if (options.dryRun) {
+                    report.freedBytes += size.bytes;
+                    continue;
+                }
+                const removed = await removeEntry(path);
+                if (removed)
+                    report.freedBytes += size.bytes;
+                else
+                    report.skipped.push({ path, reason: 'permission' });
+            }
+        }
+        freedBytes += report.freedBytes;
+        perTarget.push(report);
+    }
+    return { dryRun: options.dryRun, freedBytes, perTarget };
+}
+/** Human-readable size for the card and the CLI. */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return String(bytes) + ' B';
+    const units = ['KB', 'MB', 'GB', 'TB'];
+    let value = bytes / 1024;
+    let unit = 0;
+    while (value >= 1024 && unit < units.length - 1) {
+        value /= 1024;
+        unit += 1;
+    }
+    return value.toFixed(value >= 100 ? 0 : 1) + ' ' + (units[unit] ?? 'TB');
+}
+/** Basename helper re-exported for the route's skipped-entry display. */
+export function displayName(path) {
+    return basename(path);
+}

package/lib/challenge.d.ts

@@ -21,6 +21,14 @@ export declare function detectChallenge(snapshot: ChallengeSnapshot): ChallengeM
  * challenge. The browser window is visible on the user's desktop: the agent
  * should pause and ask the user to complete it by hand, then re-snapshot.
  */
+/**
+ * The hint appended when a challenge page is recognised. It has to know the
+ * window mode: headless has no window to complete a slider in, so telling the
+ * user to "finish it in the open window" would be false.
+ *
+ * @param headless - the mode the provider is running in
+ */
+export declare function challengeNote(headless: boolean): string;
 export declare const CHALLENGE_NOTE = "[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. The browser window is open on the user's desktop \u2014 tell the user a verification appeared, wait for them to finish it (a few seconds), then call browser_snapshot again. The clearance cookie is saved to the profile automatically and keeps working for the session.";
 /**
  * Appended after an action that left the page byte-for-byte unchanged on a page

package/lib/challenge.js

@@ -213,6 +213,22 @@ export function detectChallenge(snapshot) {
  * challenge. The browser window is visible on the user's desktop: the agent
  * should pause and ask the user to complete it by hand, then re-snapshot.
  */
+/**
+ * The hint appended when a challenge page is recognised. It has to know the
+ * window mode: headless has no window to complete a slider in, so telling the
+ * user to "finish it in the open window" would be false.
+ *
+ * @param headless - the mode the provider is running in
+ */
+export function challengeNote(headless) {
+    if (headless) {
+        return ('[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. ' +
+            'The browser is running HEADLESS, so there is no window to finish it in — do not wait for a human to click anything here. ' +
+            'Stop and tell the user: either switch the window mode to 显示浏览器窗口 in Settings → 浏览器 and let them complete the verification, ' +
+            'or handle this site another way. Once a clearance cookie is obtained (in a headful window) it is saved to the profile and keeps working for the session.');
+    }
+    return CHALLENGE_NOTE;
+}
 export const CHALLENGE_NOTE = "[human verification] The page triggered an anti-bot challenge; it is NOT solvable by automation and must NOT be retried blindly. The browser window is open on the user's desktop — tell the user a verification appeared, wait for them to finish it (a few seconds), then call browser_snapshot again. The clearance cookie is saved to the profile automatically and keeps working for the session.";
 /**
  * Appended after an action that left the page byte-for-byte unchanged on a page

package/lib/client.js

@@ -233,10 +233,16 @@ window.__ModuleLoader__.load({
             const [busy, setBusy] = useState(false);
             const [msg, setMsg] = useState('');
             const [logins, setLogins] = useState(null);
+            const [headless, setHeadless] = useState(null);
+            const [headlessUserChosen, setHeadlessUserChosen] = useState(false);
             const [showAll, setShowAll] = useState(false);
             const [openGroups, setOpenGroups] = useState([]);
             const [hiddenDomains, setHiddenDomains] = useState(readHiddenDomains());
             const [loginsOpen, setLoginsOpen] = useState(false);
+            const [disk, setDisk] = useState(null);
+            const [diskPicked, setDiskPicked] = useState({ 'browser-cache': true, 'temp-residue': true, 'updater-residue': true, 'attachment-cache': false });
+            const [diskPreview, setDiskPreview] = useState(null);
+            const [diskResult, setDiskResult] = useState(null);
             const mountedRef = useRef(true);
 
             const refresh = async () => {
@@ -248,6 +254,8 @@ window.__ModuleLoader__.load({
                     if (typeof s.engine === 'string')
                         setEngine(s.engine);
                     setEngineUserChosen(s.engineUserChosen === true);
+                    if (typeof s.headless === 'boolean') setHeadless(s.headless);
+                    setHeadlessUserChosen(s.headlessUserChosen === true);
                     setGates({
                         allowEvaluate: typeof s.allowEvaluate === 'boolean' ? s.allowEvaluate : null,
                         allowCdp: typeof s.allowCdp === 'boolean' ? s.allowCdp : null,
@@ -276,6 +284,7 @@ window.__ModuleLoader__.load({
                 mountedRef.current = true;
                 refresh();
                 refreshLogins();
+                refreshDisk();
                 const timer = setInterval(refresh, 5000);
                 // Cookies change far more slowly than switches; polling this less often keeps the
                 // settings page from doing pointless work.
@@ -331,6 +340,27 @@ window.__ModuleLoader__.load({
                 }
             };
 
+            const chooseWindow = async (nextHeadless) => {
+                if (headless === null || busy || nextHeadless === headless) return;
+                setBusy(true);
+                setMsg('');
+                try {
+                    const r = await api('/window', 'POST', { headless: nextHeadless });
+                    if (r && r.error) throw new Error(r.error.message || r.error.code || 'unknown');
+                    if (typeof r.headless === 'boolean') setHeadless(r.headless);
+                    setHeadlessUserChosen(true);
+                    setMsg(r.changed
+                        ? (nextHeadless
+                            ? '已切到后台运行（无头）。下次操作时重开浏览器；标签页会关闭，登录状态保留。'
+                            : '已切到显示窗口。下次操作时重开浏览器；标签页会关闭，登录状态保留。')
+                        : '状态未变化');
+                } catch (error) {
+                    setMsg('切换失败：' + (error?.message ?? String(error)));
+                } finally {
+                    setBusy(false);
+                }
+            };
+
             const applyGates = async (key, next) => {
                 if (gates[key] === null || busy || next === gates[key])
                     return;
@@ -366,6 +396,58 @@ window.__ModuleLoader__.load({
                 }
             };
 
+            const fmt = (bytes) => {
+                if (typeof bytes !== 'number') return '—';
+                if (bytes < 1024) return bytes + ' B';
+                const units = ['KB', 'MB', 'GB'];
+                let value = bytes / 1024;
+                let unit = 0;
+                while (value >= 1024 && unit < units.length - 1) { value /= 1024; unit += 1; }
+                return value.toFixed(value >= 100 ? 0 : 1) + ' ' + units[unit];
+            };
+
+            const refreshDisk = async () => {
+                try {
+                    const d = await api('/disk/stat', 'GET');
+                    if (mountedRef.current && d && !d.error) setDisk(d);
+                } catch (error) {
+                    if (mountedRef.current) setMsg('磁盘统计失败：' + (error?.message ?? String(error)));
+                }
+            };
+
+            const runDisk = async (dryRun) => {
+                if (busy) return;
+                const targets = Object.keys(diskPicked).filter((id) => diskPicked[id]);
+                if (targets.length === 0) { setMsg('先勾选要清理的项目'); return; }
+                setBusy(true);
+                setMsg('');
+                try {
+                    const r = await api('/disk/clean', 'POST', { targets, dryRun });
+                    if (r && r.error) throw new Error(r.error.message || r.error.code || 'unknown');
+                    if (dryRun) {
+                        setDiskPreview(r);
+                        setDiskResult(null);
+                    } else {
+                        setDiskPreview(null);
+                        setDiskResult(r);
+                        setMsg('已释放 ' + fmt(r.freedBytes) + '（跳过 ' + (r.perTarget || []).reduce((n, t) => n + ((t.skipped && t.skipped.length) || 0), 0) + ' 项）');
+                        refreshDisk();
+                    }
+                } catch (error) {
+                    setMsg('清理失败：' + (error?.message ?? String(error)));
+                } finally {
+                    setBusy(false);
+                }
+            };
+
+            const skipSummary = (report) => {
+                if (!report || !Array.isArray(report.perTarget)) return '';
+                const reasons = {};
+                for (const t of report.perTarget) for (const s of (t.skipped || [])) reasons[s.reason] = (reasons[s.reason] || 0) + 1;
+                const parts = Object.keys(reasons).map((k) => k + ' ' + reasons[k]);
+                return parts.length > 0 ? '　跳过：' + parts.join('、') : '';
+            };
+
             const state = enabled === null ? 'ongoing' : (enabled ? 'done' : 'idle');
             const gateState = (key) => (gates[key] === null ? 'ongoing' : (gates[key] ? 'done' : 'idle'));
             const gatesOn = GATE_ROWS.filter((row) => gates[row.key] === true).length;
@@ -423,6 +505,40 @@ window.__ModuleLoader__.load({
                         o.label + '：' + o.hint))),
                 }),
 
+                // ---- 浏览器窗口（有头 / 无头） ----
+                h('div', { key: 'windowGroup', style: S.group }, [
+                    '浏览器窗口',
+                    h('span', { key: 'cur', style: S.groupCount },
+                        headless === null ? '　读取中…' : (headless ? '　当前：后台运行（无头）' : '　当前：显示窗口（有头）')
+                        + (headlessUserChosen ? '（你选的）' : '')),
+                ]),
+                h('div', { key: 'windows', style: { ...S.list, marginTop: 8 } }, [
+                    h(RadioRow, {
+                        key: 'headful',
+                        p: { id: 'headful', label: '显示浏览器窗口', hint: '能看见、能随时接手；登录和验证码可以自己处理' },
+                        selected: headless === false,
+                        disabled: headless === null || busy,
+                        onPick: () => chooseWindow(false),
+                    }),
+                    h(RadioRow, {
+                        key: 'headless',
+                        p: { id: 'headless', label: '后台运行（无头）', hint: '更快、不弹窗；但你看不见它，登录/验证码只能远程处理' },
+                        selected: headless === true,
+                        disabled: headless === null || busy,
+                        onPick: () => chooseWindow(true),
+                    }),
+                ]),
+                h(Notes, {
+                    key: 'windowNotes',
+                    title: '切换窗口模式会发生什么',
+                    children: h('div', null, [
+                        h('p', { key: 'reopen', style: S.note },
+                            '有头/无头是启动参数，不能原地切换：下次操作时会关掉旧窗口、按新模式重开。标签页和未提交的表单会丢，登录状态会先导出、不会丢。'),
+                        h('p', { key: 'risk', style: S.note },
+                            '无头模式下插件"看得见、能接管"的前提不成立——验证码/二次验证只有提示，没人能在窗口里替你点。只在无人值守、且你接受这个代价时用。'),
+                    ]),
+                }),
+
                 // ---- 工具权限 ----
                 h('div', { key: 'gateGroup', style: S.group }, [
                     '工具权限',
@@ -459,6 +575,55 @@ window.__ModuleLoader__.load({
                     ]),
                 }),
 
+                h('div', { key: 'diskGroup', style: S.group }, [
+                    '缓存与磁盘',
+                    h('span', { key: 'sum', style: S.groupCount },
+                        disk === null ? '　统计中…' : '　可清理 ' + fmt(disk.totalBytes)),
+                ]),
+                h('div', { key: 'diskList', style: { ...S.list, marginTop: 8 } },
+                    (disk === null ? [] : disk.items).map((item) => h('div', { key: item.id, style: S.row }, [
+                        h('div', {
+                            key: 'check',
+                            role: 'checkbox',
+                            'aria-checked': diskPicked[item.id] === true,
+                            'aria-label': item.label,
+                            tabIndex: 0,
+                            onClick: () => setDiskPicked({ ...diskPicked, [item.id]: !diskPicked[item.id] }),
+                            onKeyDown: (e) => {
+                                if (e.key === 'Enter' || e.key === ' ') {
+                                    e.preventDefault();
+                                    setDiskPicked({ ...diskPicked, [item.id]: !diskPicked[item.id] });
+                                }
+                            },
+                            style: {
+                                width: 16, height: 16, flex: 'none', borderRadius: 4, cursor: 'pointer',
+                                border: '1.5px solid ' + (diskPicked[item.id] ? T.primary : T.borderL3),
+                                display: 'flex', alignItems: 'center', justifyContent: 'center',
+                            },
+                        }, diskPicked[item.id] ? h('span', { style: { width: 8, height: 8, borderRadius: 2, background: T.primary } }) : null),
+                        h('div', { key: 'text', style: { flex: 1, minWidth: 0 } }, [
+                            h('div', { key: 'label', style: S.rowTitle }, item.label),
+                            h('div', { key: 'desc', style: S.rowDesc },
+                                fmt(item.bytes) + '　' + item.files + ' 个文件'
+                                + (item.note ? '　' + item.note : '')),
+                        ]),
+                    ]))),
+                h('div', { key: 'diskActions', style: S.footer }, [
+                    h(Btn, { key: 'rescan', onClick: refreshDisk, disabled: busy }, '重新统计'),
+                    h(Btn, { key: 'preview', onClick: () => runDisk(true), disabled: busy || disk === null }, '先预演'),
+                    diskPreview
+                        ? h(Btn, { key: 'clean', onClick: () => runDisk(false), disabled: busy }, '确认清理 ' + fmt(diskPreview.freedBytes))
+                        : null,
+                ]),
+                diskPreview
+                    ? h('div', { key: 'diskPreview', style: S.tip },
+                        '预演：将释放 ' + fmt(diskPreview.freedBytes) + skipSummary(diskPreview) + '（点了确认才会真删）')
+                    : null,
+                diskResult
+                    ? h('div', { key: 'diskResult', style: S.tip },
+                        '已释放 ' + fmt(diskResult.freedBytes) + skipSummary(diskResult))
+                    : null,
+
                 // ---- 已登录站点（默认收起） ----
                 h('div', {
                     key: 'loginsGroup',

package/lib/errors.d.ts

@@ -23,3 +23,15 @@ export declare class BrowserError extends Error {
 }
 /** Wrap an unknown cause into a launch failure with the code preserved. */
 export declare function launchFailed(cause: unknown): BrowserError;
+/**
+ * "browser_evaluate is switched off". One wording, thrown by both layers that
+ * enforce it: the tool layer (before a browser is even launched) and the
+ * session itself (so a programmatic caller cannot go around the switch).
+ * @returns the denial, ready to throw.
+ */
+export declare function evaluateDisabled(): BrowserError;
+/**
+ * "browser_cdp is switched off". Same two-layer rule as {@link evaluateDisabled}.
+ * @returns the denial, ready to throw.
+ */
+export declare function cdpDisabled(): BrowserError;