testing-tool/docs/superpowers/specs/2026-03-20-storage-cleaner-design.md

存储清理功能设计文档

概述

为浏览器扩展添加一个存储清理功能，允许用户快速清理当前页面的各种存储数据，包括 localStorage、sessionStorage、IndexedDB、Cookies、Cache Storage 和 Service Workers。

目标

• 提供便捷的页面存储清理功能
• 支持多种存储类型清理
• 提供清理结果反馈
• 支持清理后自动刷新页面

架构设计

组件结构

entrypoints/popup/pages/
├── TimestampPage.tsx        (现有：时间戳转换页面)
└── StorageCleanerPage.tsx    (新增：存储清理页面)

页面布局

在弹窗中添加标签页切换功能，用户可以在时间戳转换和存储清理之间切换。

用户界面设计

页面组成

1. 头部区域

   • 标题："存储清理"
   • 当前域名显示（自动从活动标签页获取）

2. 存储类型选择区域

   • 勾选框：localStorage
   • 勾选框：sessionStorage
   • 勾选框：IndexedDB
   • 勾选框：Cookies
   • 勾选框：Cache Storage
   • 勾选框：Service Workers

3. 自动刷新选项

   • 复选框：清理完成后自动刷新页面（默认勾选）

4. 操作区域

   • 清理按钮

5. 结果显示区域

   • 清理成功/失败提示
   • 清理详情统计（如："清理了 5 个 localStorage, 3 个 cookies"）
   • 刷新页面按钮（当未勾选自动刷新时显示）

技术实现细节

获取当前标签页域名

使用 Chrome Tabs API 获取当前活动标签页：

const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
if (!tab?.url) {
  throw new Error('无法获取当前标签页 URL');
}
const domain = new URL(tab.url).hostname;

清理 Cookies（使用 chrome.cookies API）

在扩展环境中直接执行，不需要注入页面：

const cookies = await chrome.cookies.getAll({ url: tab.url });
let count = 0;
for (const cookie of cookies) {
  await chrome.cookies.remove({
    url: tab.url,
    name: cookie.name,
    storeId: cookie.storeId,
  });
  count++;
}

注入脚本清理其他存储

需要注入到页面执行的存储清理逻辑：

清理 localStorage

const count = localStorage.length;
localStorage.clear();
return count;

清理 sessionStorage

const count = sessionStorage.length;
sessionStorage.clear();
return count;

清理 IndexedDB

const databases = await indexedDB.databases();
let count = 0;
for (const db of databases) {
  const deleteReq = indexedDB.deleteDatabase(db.name);
  deleteReq.onblocked = () => {
    console.warn('IndexedDB delete blocked:', db.name);
  };
  await new Promise((resolve, reject) => {
    deleteReq.onsuccess = resolve;
    deleteReq.onerror = reject;
  });
  count++;
}
return count;

清理 Cache Storage

const cacheNames = await caches.keys();
for (const name of cacheNames) {
  await caches.delete(name);
}
return cacheNames.length;

注销 Service Workers

if ('serviceWorker' in navigator) {
  const registration = await navigator.serviceWorker.getRegistration();
  if (registration) {
    await registration.unregister();
    return true;
  }
}
return false;

数据流

1. 页面加载时获取当前标签页 URL 并显示域名
2. 用户勾选要清理的存储类型
3. 用户选择是否自动刷新页面
4. 用户点击清理按钮
5. 弹出确认对话框询问用户确认
6. 确认后执行清理：
   • 如果选择 Cookies：直接使用 chrome.cookies API 删除
   • 其他存储类型：向页面注入清理脚本
7. 收集所有清理结果并统计
8. 显示清理结果
9. 如果勾选"自动刷新"或用户点击"刷新页面"按钮，执行页面刷新

页面刷新

await chrome.tabs.reload(tab.id);

错误处理

错误场景	处理方式
无法获取当前标签页	显示错误提示："无法获取当前标签页"
无法访问页面 URL	显示错误提示："无法访问此页面"
IndexedDB onblocked	显示警告但继续执行其他清理
清理失败	显示具体错误信息
Cookies 删除失败	记录错误，显示清理失败提示
无权限	提示用户刷新扩展或检查权限

权限需求

需要在 manifest 中添加 cookies 权限：

permissions: [
  'storage',
  'unlimitedStorage',
  'clipboardWrite',
  'activeTab',
  'scripting',
  'tabs',
  'debugger',
  'cookies', // 新增
],

TypeScript 类型定义

在现有 types/storage.d.ts 中添加存储清理相关的类型：

export interface StorageCleanerOptions {
  localStorage: boolean;
  sessionStorage: boolean;
  indexedDB: boolean;
  cookies: boolean;
  cacheStorage: boolean;
  serviceWorkers: boolean;
}

export interface CleaningResult {
  localStorage?: number;
  sessionStorage?: number;
  indexedDB?: number;
  cookies?: number;
  cacheStorage?: number;
  serviceWorkers?: boolean;
}

测试计划

1. 测试各种存储类型的单独清理
2. 测试同时清理多种存储类型
3. 测试自动刷新功能
4. 测试手动刷新按钮
5. 测试无存储数据时的清理
6. 测试无法访问页面的错误处理
7. 测试 IndexedDB onblocked 场景
8. 测试 httponly 和 secure cookies 清理

后续优化

• 显示清理前的存储使用情况
• 支持批量清理多个标签页
• 支持自定义域名清理