From d2dc0057b30731559da21ce778e73a295cfec3fc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=9B=A8=E9=9C=96=E9=93=83?= Date: Fri, 20 Mar 2026 00:18:02 +0800 Subject: [PATCH] docs: add storage cleaner feature design document - Design for browser extension storage cleaning feature - Supports localStorage, sessionStorage, IndexedDB, Cookies, Cache Storage, Service Workers - Uses chrome.cookies API for cookie cleaning - Implements IndexedDB onblocked event handling Co-Authored-By: Claude Opus 4.6 --- .../2026-03-20-storage-cleaner-design.md | 235 ++++++++++++++++++ 1 file changed, 235 insertions(+) create mode 100644 docs/superpowers/specs/2026-03-20-storage-cleaner-design.md diff --git a/docs/superpowers/specs/2026-03-20-storage-cleaner-design.md b/docs/superpowers/specs/2026-03-20-storage-cleaner-design.md new file mode 100644 index 0000000..c45deda --- /dev/null +++ b/docs/superpowers/specs/2026-03-20-storage-cleaner-design.md @@ -0,0 +1,235 @@ +# 存储清理功能设计文档 + +## 概述 + +为浏览器扩展添加一个存储清理功能，允许用户快速清理当前页面的各种存储数据，包括 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 获取当前活动标签页： + +```typescript +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） + +在扩展环境中直接执行，不需要注入页面： + +```typescript +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 + +```javascript +const count = localStorage.length; +localStorage.clear(); +return count; +``` + +#### 清理 sessionStorage + +```javascript +const count = sessionStorage.length; +sessionStorage.clear(); +return count; +``` + +#### 清理 IndexedDB + +```javascript +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 + +```javascript +const cacheNames = await caches.keys(); +for (const name of cacheNames) { + await caches.delete(name); +} +return cacheNames.length; +``` + +#### 注销 Service Workers + +```javascript +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. 如果勾选"自动刷新"或用户点击"刷新页面"按钮，执行页面刷新 + +### 页面刷新 + +```typescript +await chrome.tabs.reload(tab.id); +``` + +## 错误处理 + +| 错误场景 | 处理方式 | +| ------------------- | ---------------------------------- | +| 无法获取当前标签页 | 显示错误提示："无法获取当前标签页" | +| 无法访问页面 URL | 显示错误提示："无法访问此页面" | +| IndexedDB onblocked | 显示警告但继续执行其他清理 | +| 清理失败 | 显示具体错误信息 | +| Cookies 删除失败 | 记录错误，显示清理失败提示 | +| 无权限 | 提示用户刷新扩展或检查权限 | + +## 权限需求 + +需要在 manifest 中添加 `cookies` 权限： + +```typescript +permissions: [ + 'storage', + 'unlimitedStorage', + 'clipboardWrite', + 'activeTab', + 'scripting', + 'tabs', + 'debugger', + 'cookies', // 新增 +], +``` + +## TypeScript 类型定义 + +在现有 `types/storage.d.ts` 中添加存储清理相关的类型： + +```typescript +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 清理 + +## 后续优化 + +- 显示清理前的存储使用情况 +- 支持批量清理多个标签页 +- 支持自定义域名清理