dsh-browser-playwright-codex 0.7.1 → 0.7.4

package/CHANGELOG.md

@@ -1,3 +1,53 @@
+## 0.7.4 — 2026-10-23
+
+一句话摘要：**设置卡可以切换有头 / 无头** —— 运行时开关，不用改 YAML、不用重启 DSH；切换在**下一次操作**时生效（先导出登录态，再按新模式重开窗口）。默认仍是有头。
+
+### Added
+
+- **「浏览器窗口」开关**：设置卡新增单选「显示浏览器窗口（有头）」/「后台运行（无头）」，选择存进 `~/.dsh/dsh-browser-playwright.state.json`（与页面识别方式同一套 runtime-state），重启后仍记住。改完在**下一次浏览器操作**时重开窗口生效——不会打断正在进行的调用；代价是标签页和未提交的表单会丢，登录状态会先导出、不会丢。
+- **`POST /api/browser-playwright/window { headless }`**：校验布尔值，返回生效值与 `changed`；`GET /state` 同时返回 `headless` / `headlessUserChosen` / `headlessConfigured`，卡片据此显示「当前 / 你选的」。
+- **界面明确写清无头的代价**：无头模式下「看得见、能随时接手」的前提不成立——验证码/二次验证只剩提示，没人能在窗口里替你点；只在无人值守且接受这个代价时用。
+
+### Changed
+
+- **provider 按「期望模式 vs 实际启动模式」懒重开**：`desiredHeadless()` 读运行时选择（无选择时回退 `launch.headless`）；每次 acquire 前比较 `launchedHeadless`，不一致就先 `dispose()`（导出登录态、关窗）再按新模式启动。已经在用的 owner 切换模式也会被重建，而不是「下次重启才生效」。
+- **`launch.headless` 仍是配置默认**：配置里写什么就是没在卡片上选过时的默认值；两处启动路径（持久 context / legacy browser）都改为读解析后的值。
+
+### Fixed
+
+- **挑战页提示语随窗口模式变化**：无头模式下原提示仍说「浏览器窗口就在你桌面上，等人去点」——那个窗口不存在。现在无头时改为明确说「HEADLESS、没有窗口可完成验证；要么把窗口模式切回『显示浏览器窗口』让人处理，要么换一种方式」，并保留「不要盲目重试」的纪律。有头模式的措辞不变。
+
+### Tests
+
+- 运行时状态：窗口模式持久化、configured 默认只在没有用户选择时生效（2 条）。
+- provider：`desiredHeadless()` 用户选择优先于 `launch.headless`（1 条，无浏览器启动）。
+- 真机验收：有头启动 → 切无头（重开、会话句柄替换）→ 切回有头，状态文件落盘。
+
+## 0.7.3 — 2026-10-20
+
+一句话摘要：**设置卡新增「缓存与磁盘」** —— 把浏览器 profile 的纯缓存、%TEMP% 里的 dsh-* 残留、更新器残留、请求图缓存做成可预览、可逐项清理的面板；顺手修掉三处测试把临时目录泄进 %TEMP% 的根因。运行时代码零改动。
+
+### Added
+
+- **设置卡「缓存与磁盘」区块**：四类目标（浏览器缓存 / 临时残留 / 更新器残留 / 图片变体缓存）显示各自字节数与文件数，勾选后先「预演」看能释放多少，再「确认清理」；结果逐项报告释放量与跳过原因（占用中 / 权限 / 其它版本）。
+- **`src/cache-clean.ts`**：纯 `node:fs` 模块，两个入口 `scan()` / `clean()`。安全边界写在代码里而不是提示词里：目标是**枚举 id**（`browser-cache` / `temp-residue` / `updater-residue` / `attachment-cache`），路径一律由 DSH_HOME 与已知系统位置推导，请求体里的字符串永远不拼进路径；浏览器 profile 只删 Chromium 的纯缓存目录（Cache / Code Cache / GPUCache / ShaderCache / GrShaderCache / DawnCache / DawnGraphiteCache / ScriptCache / `*_crx_cache`），Cookies、Local Storage、Service Worker、IndexedDB、Network、Preferences 一律不碰。
+- **`GET /api/browser-playwright/disk/stat`** 与 **`POST /api/browser-playwright/disk/clean`**：沿用已有的 `x-dsh-plugin: browser-toggle` 防伪头（GET 与 POST 都验）、JSON 校验、枚举校验；失败逐条返回 `{ path, reason }`，不折成一个笼统错误。`~/.dsh/cache/attachments` 可清，`~/.dsh/attachments/v1/objects`（会话引用的原图）永不在清理范围内，只在统计里报大小。
+- **`tests/cache-clean.test.ts`**：9 条 fixture 用例——白名单内删干净、Cookies 与 Local Storage 一个不动、`dryRun` 不落盘、新临时目录预演时标 `in-use`、只清当前版本的更新器文件、附件缓存清空而会话原图保留、目标 id 拒绝任意路径、路径推导、字节格式化。
+
+### Fixed
+
+- **三处测试泄漏 %TEMP%**：`runtime-state.test.ts`、`provider.test.ts`、`login-state.test.ts` 用 `mkdtempSync` 创建的 `dsh-browser-state-*` / `dsh-provider-state-*` / `dsh-login-state-*` 目录从来没删，跑一次测试就在临时目录里留一堆空壳；现在各自登记并在 `after()` 里删掉。
+- **Windows 只读文件**：清理时先尝试普通删除，失败再 `chmod` 去掉只读位重试；**删成功之后才计入释放量**，不再出现"报了删除但一个没删"的假账。
+
+## 0.7.2 — 2026-10-19
+
+一句话摘要：**设置卡推倒重做** —— 用户要求按 DSH 设置页规范重新设计：首屏只留「主开关 + 三个分区摘要」，所有长说明收进折叠。0.7.1 因卡在 npm staged 状态作废（版本号让给这一版）。
+
+### Changed
+
+- **设置卡重做**：主开关一行；「页面读取方式」两个紧凑单选项 + 一个「两种模式到底差在哪」折叠；「工具权限」三个开关（任意 JS / 原始 CDP / 诊断工具）+ 一个「这些开关具体放行什么」折叠，标题行直接显示「N / 3 已开启」；「已登录的站点」默认收起，标题行只给「N 个域 · M 个 cookie」，展开后仍按公司分组折叠。名单每行只保留域名 + 说明 + cookie 数，逐个站点的四个 OWASP 信号不再塞在主视图里。
+- 卡片文案统一为"人话"，不再出现 evaluate / cdp / 引擎 / legacy / aria 这些词。
+
 # Changelog
 
 Bilingual by intent: the version headings and the summary of each release are given in both

package/README.md

@@ -281,6 +281,16 @@ Both are honest trades, not free wins: a diff is smaller but requires the model
 tree, and an interactive-only snapshot hides the prose the model may want to read. Measure before
 turning them on in a deployment that shares prompts across many users.
 
+### Window mode (headful / headless)
+
+The Settings card has a **浏览器窗口** choice: show the window (headful, the default) or run it in the background (headless). The pick is stored in `~/.dsh/dsh-browser-playwright.state.json` and survives restarts; `launch.headless` stays the configured default for anyone who never picks.
+
+Switching takes effect on the **next browser operation**: the provider compares the mode it launched with against the desired one and relaunches (login state is exported first, so the login survives; tabs and unsaved page state do not). Headless is honest about its cost — with no visible window, the “watch it and take over” guarantee for sign-ins and CAPTCHAs no longer holds, so use it only for unattended work where you accept that.
+
+### Cache and disk
+
+The Settings card also carries a **缓存与磁盘** section: Chromium's pure caches inside the plugin's profile, `dsh-*` residue in `%TEMP%`, updater installers of the installed version, and the request-image cache are listed with their sizes; you preview first (“先预演”) and only then confirm. Cookies, Local Storage, Service Worker, IndexedDB, Network, Preferences and `~/.dsh/attachments` are never in scope — the target list is a closed enum in `src/cache-clean.ts`, and no path is ever taken from the request.
+
 ### Prefer a switch to editing config?
 
 The Settings card ships **inside this package** (it moved out of the companion package `dsh-browser-toggle`, which is retired) and puts
@@ -496,3 +506,5 @@ MIT
 - **新增两只诊断工具**：`browser_console_messages`（控制台报错）与 `browser_network_requests`（网络请求），用于"点了没反应"时快速定位原因。
 - **接口与实现同步**：`BrowserSession` 补齐 9 个实现里已有的方法；`errors.ts` 补齐 12 个实际在用的错误码；`BrowserSnapshot` 补 `dialogNote` / `landingNote`；`TabInfo` 补 `active`；`runtime-state` / `cdp-policy` 新增类型声明。
 - **依赖范围修正**：`devDependencies` 与 `peerDependencies` 对齐，可在当前 DSH 版本下安装。
+
+**有问题直接去[讨论区](https://github.com/miqian-nomad/dsh-browser-playwright-codex/discussions)开个帖说，用得顺手也可以来吭一声——就我一个人维护，回得慢，但每条都看。**

package/SECURITY.md

@@ -11,6 +11,10 @@ this package ships switched off** — it is not registered at all until a deploy
 
 ---
 
+## 0. Window mode
+
+Headful is the default and the safety story depends on it: the window is visible, you can watch it and take over for sign-ins and CAPTCHAs. **Headless removes that**: the agent still parks native dialogs and reports challenge pages as notes, but nobody can act in a window that does not exist. Treat headless as an unattended mode, not as a quieter headful one.
+
 ## 1. What it can and cannot do
 
 **It drives your browser, as you.** The provider opens a visible, profile-backed Chromium-family

package/lib/browser-lifecycle.js

@@ -28,7 +28,8 @@ export async function ensureContext(provider) {
         provider.context = undefined;
     }
     fs.mkdirSync(provider.profileDir, { recursive: true });
-    const { executablePath, channel, headless } = provider.config.launch;
+    const { executablePath, channel } = provider.config.launch;
+    const headless = provider.desiredHeadless();
     const headful = !headless;
     const attempts = [];
     const baseOptions = {
@@ -56,6 +57,7 @@ export async function ensureContext(provider) {
     const start = async (extra) => {
         try {
             provider.context = await chromium.launchPersistentContext(provider.profileDir, { ...baseOptions, ...extra });
+            provider.launchedHeadless = headless;
         }
         catch (error) {
             // A stale Chrome singleton lock from a dirty shutdown breaks a
@@ -64,6 +66,8 @@ export async function ensureContext(provider) {
             if (error instanceof Error && /user data directory|SingletonLock|ProcessSingleton/i.test(error.message)) {
                 await provider.clearChromeLocks();
                 provider.context = await chromium.launchPersistentContext(provider.profileDir, { ...baseOptions, ...extra });
+                provider.launchedHeadless = headless;
+                provider.launchedHeadless = headless;
             }
             else {
                 throw error;
@@ -147,11 +151,13 @@ export async function clearChromeLocks(provider) {
 export async function ensureBrowser(provider) {
     if (provider.browser !== undefined)
         return provider.browser;
-    const { executablePath, channel, headless } = provider.config.launch;
+    const { executablePath, channel } = provider.config.launch;
+    const headless = provider.desiredHeadless();
     const attempts = [];
     if (executablePath !== undefined) {
         try {
             provider.browser = await chromium.launch({ executablePath, headless, ...HUMANIZED_LAUNCH });
+            provider.launchedHeadless = headless;
             return provider.browser;
         }
         catch (error) {
@@ -164,6 +170,7 @@ export async function ensureBrowser(provider) {
         for (const candidate of channels) {
             try {
                 provider.browser = await chromium.launch({ channel: candidate, headless, ...HUMANIZED_LAUNCH });
+                provider.launchedHeadless = headless;
                 return provider.browser;
             }
             catch (error) {

package/lib/cache-clean.d.ts

@@ -0,0 +1,90 @@
+/** The four buckets the card can report and clean. */
+export type TargetId = 'browser-cache' | 'temp-residue' | 'updater-residue' | 'attachment-cache';
+/** Display order and labels for every target. */
+export declare const TARGETS: readonly {
+    id: TargetId;
+    label: string;
+}[];
+/** Is this value one of the enum ids? Unknown strings are rejected, never joined into a path. */
+export declare function isTargetId(value: unknown): value is TargetId;
+/** Absolute locations this module may inspect. */
+export interface CachePaths {
+    /** DSH home (`~/.dsh` unless DSH_HOME overrides it). */
+    dshHome: string;
+    /** Persistent Chromium profile directory of the browser capability. */
+    browserProfileDir: string;
+    /** OS temp directory. */
+    tmpDir: string;
+    /** Electron updater residue directory for the DSH desktop app. */
+    updaterDir: string;
+    /** Version currently installed — used to refuse other versions' installers. */
+    installedVersion: string;
+}
+/** Resolve the default paths from the environment (no path ever comes from the request). */
+export declare function resolvePaths(env: NodeJS.ProcessEnv | undefined, version: string, platform?: NodeJS.Platform): CachePaths;
+/** One row of the disk panel. */
+export interface DiskItem {
+    id: TargetId;
+    label: string;
+    bytes: number;
+    files: number;
+    /** Optional human note (e.g. "浏览器正在运行，整段跳过"). */
+    note?: string;
+}
+/** What `scan()` reports. */
+export interface ScanReport {
+    items: DiskItem[];
+    totalBytes: number;
+    attachments: {
+        objectsBytes: number;
+        requestImagesBytes: number;
+    };
+    skipped: {
+        id: TargetId;
+        reason: string;
+    }[];
+}
+/** One skipped entry inside a target. */
+export interface SkippedEntry {
+    path: string;
+    reason: 'in-use' | 'permission' | 'other-version' | 'unknown-version' | 'missing';
+}
+/** Per-target outcome of a clean pass. */
+export interface CleanTargetReport {
+    id: TargetId;
+    freedBytes: number;
+    skipped: SkippedEntry[];
+}
+/** What `clean()` reports. */
+export interface CleanReport {
+    dryRun: boolean;
+    freedBytes: number;
+    perTarget: CleanTargetReport[];
+}
+/** Options for one clean pass. */
+export interface CleanOptions extends CachePaths {
+    targets: readonly TargetId[];
+    dryRun: boolean;
+    /** True when the capability is enabled — reported, not used to skip silently. */
+    browserActive?: boolean;
+    /** Clock override for tests. */
+    now?: number;
+}
+/**
+ * Inspect every bucket without touching anything.
+ * @param paths - resolved locations
+ * @returns per-target sizes plus the attachment totals kept apart from the cache
+ */
+export declare function scan(paths: CachePaths): Promise<ScanReport>;
+/**
+ * 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 declare function clean(options: CleanOptions): Promise<CleanReport>;
+/** Human-readable size for the card and the CLI. */
+export declare function formatBytes(bytes: number): string;
+/** Basename helper re-exported for the route's skipped-entry display. */
+export declare function displayName(path: string): string;

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