项目文件夹

文件

T

hangerye 8b7879d927 feat: [WIP]quick-panel

2025-12-31 17:56:15 +08:00

51 KiB

原始文件 永久链接 Blame 文件历史

Quick Panel - 产品需求文档 (PRD)

Chrome 快速启动面板 - 类 Raycast 的浏览器命令面板

一、产品概述

1.1 产品定位

Quick Panel 是一个 Chrome 扩展的快速启动面板，提供类似 Raycast/Alfred 的命令面板体验。用户可以通过全局快捷键唤起面板，快速搜索标签页、书签、历史记录，执行各种命令操作，实现浏览器能力的"命令化"，要有商业级产品的应用体验。

1.2 核心价值主张

一处入口：统一的入口覆盖导航、调试、自动化、内容分析
键盘优先：全程键盘可用，减少鼠标切换，提升效率
本地优先：数据本地处理，隐私安全可控
超越普通插件：深度集成 CDP/Native Host/MCP，实现 Raycast 做不到的能力

1.3 目标用户

用户类型	核心需求	功能侧重
通用效率用户	标签页管理、快速导航、常用操作	搜索、书签、历史、截图、复制链接
开发者/技术用户	调试工具、网络分析、脚本注入	DevTools、Cookie、LocalStorage、注入

1.4 入口形态

页面覆盖层 (Overlay) - 在任意网页上弹出悬浮面板，体验流畅。

通过 Content Script 注入到页面
使用 Shadow DOM 隔离样式和事件
全局快捷键唤起/关闭

二、功能规划

2.1 功能分类总览

┌─────────────────────────────────────────────────────────────────────┐
│                         Quick Panel 功能架构                         │
├─────────────────────────────────────────────────────────────────────┤
│  P0 核心功能 (MVP)           │  P1 增值功能              │  P2 差异化功能    │
│  ─────────────────          │  ───────────             │  ─────────────   │
│  • 全局快捷键唤起            │  • 标签页高级管理         │  • 语义搜索       │
│  • 标签页搜索切换            │  • 页面工具              │  • 工作流运行     │
│  • 书签搜索                 │  • 开发者工具            │  • AI 增强       │
│  • 历史记录搜索             │  • 小工具                │                  │
│  • 基础命令系统             │  • 扩展管理              │                  │
│  • 最近使用                 │                         │                  │
└─────────────────────────────────────────────────────────────────────┘

2.2 P0 核心功能 (MVP)

2.2.1 面板基础

功能	描述	快捷键
唤起/关闭面板	全局快捷键唤起面板	`Ctrl+Shift+K` / `Cmd+Shift+K`
关闭面板	ESC 关闭	`Esc`
列表导航	上下键导航列表	`↑` / `↓`
执行默认动作	执行选中项的默认动作	`Enter`
新标签页打开	在新标签页打开	`Cmd+Enter`
动作面板	打开选中项的动作列表	`Tab` / `→`
返回上级	返回上一级	`Backspace` / `←`

2.2.2 搜索 Providers

Provider	图标	描述	Scope 前缀
标签页	🗂️	搜索所有打开的标签页（跨窗口）	`t`
书签	⭐	搜索所有书签	`b`
历史记录	🕐	搜索浏览历史	`h`
内容搜索	📄	搜索标签页网页内容（正文）	`c`
命令	⌘	搜索可执行命令	`>`

2.2.3 标签页搜索

搜索字段：标题、URL、域名

默认动作：切换到该标签页

二级动作：

切换到标签页
关闭标签页
复制 URL
复制为 Markdown
固定/取消固定
静音/取消静音

2.2.4 书签搜索

搜索字段：标题、URL

默认动作：在当前标签页打开

二级动作：

在当前标签页打开
在新标签页打开
复制 URL
编辑书签
删除书签

2.2.5 历史记录搜索

搜索字段：标题、URL

默认动作：在当前标签页打开

二级动作：

在当前标签页打开
在新标签页打开
复制 URL
从历史中删除

2.2.6 内容搜索（标签页正文搜索）

功能描述：搜索所有已打开标签页的网页正文内容，快速定位包含特定关键词的页面。

搜索方式：关键词精确匹配（不依赖语义引擎）

搜索范围：所有窗口的所有标签页

技术实现：

┌──────────────┐      ┌──────────────┐      ┌───────────┐
│ 页面加载完成  │ ───▶ │ 抽取正文文本  │ ───▶ │ 存储到缓存 │
└──────────────┘      └──────────────┘      └───────────┘
       ↓ (复用现有 web-fetcher-helper.js + Readability)

┌──────────────┐      ┌──────────────┐      ┌───────────┐
│ 用户输入关键词│ ───▶ │ 遍历缓存匹配  │ ───▶ │ 返回结果  │
└──────────────┘      └──────────────┘      └───────────┘

存储结构：

interface ContentCache {
  [tabId: number]: {
    url: string;
    title: string;
    content: string; // 正文文本，截断到 50KB
    timestamp: number;
  };
}

索引更新时机：

tabs.onUpdated (status === 'complete')
webNavigation.onHistoryStateUpdated (SPA 路由变化)
tabs.onRemoved (清理缓存)

默认动作：切换到该标签页

二级动作：

切换到标签页
高亮显示匹配内容（可选，需要 Content Script 配合）
复制 URL
关闭标签页

限制说明：

受限页面（chrome://、Web Store 等）无法抓取内容
跨域 iframe 内容不包含在搜索范围内
新打开的标签页需等待内容抓取完成才能被搜索到

2.2.7 基础命令

命令	描述	图标
复制当前链接	复制当前页面 URL	📋
复制为 Markdown	复制为 `[Title](URL)` 格式	📝
生成二维码	生成当前页面二维码	📱
截取屏幕	截取可视区域	📸
新建标签页	打开新标签页	➕
新建窗口	打开新窗口	🪟
新建隐身窗口	打开隐身窗口	🕶️

2.2.7 最近使用

记录用户使用的命令/搜索结果
按使用频次和时间排序
面板打开时优先显示最近使用

2.3 P1 增值功能

2.3.1 标签页高级管理

功能	描述
关闭右侧标签	关闭当前标签右侧所有标签
关闭其他标签	关闭除当前标签外的所有标签
按域名分组	自动按域名创建标签组
合并窗口	将所有窗口标签合并到当前窗口
保存会话	保存当前所有标签为可恢复会话
恢复会话	恢复之前保存的会话
标签休眠	释放不活跃标签内存 (`chrome.tabs.discard`)

2.3.2 页面工具

功能	描述	实现方式
截图-全页	截取整个页面	Content Script 滚动拼接
截图-选区	框选区域截图	Content Script
阅读模式	提取正文，沉浸式阅读	Content Script
网页大纲	提取 H1-H6 标签形成目录	Content Script
画中画	让视频进入画中画模式	Content Script
强制暗色	给网站加暗色滤镜	Content Script 注入 CSS
禅模式	隐藏非正文元素	Content Script 注入 CSS
RSS 嗅探	检测并复制 RSS 源	Content Script

2.3.3 开发者工具

功能	描述	实现方式
查看 Cookie	列出当前域名所有 Cookie	chrome.cookies API
查看 LocalStorage	查看/编辑本地存储	Content Script
清除站点数据	清除当前域名缓存和 Cookie	chrome.browsingData
Design Mode	开启 `document.designMode`	Content Script
注入 CSS	快速注入自定义 CSS	chrome.scripting
注入 JS	快速注入自定义脚本	chrome.scripting
Base64 编解码	对选中文本进行编解码	Content Script
JSON 格式化	美化 JSON 数据	Content Script

2.3.4 小工具

功能	描述
多引擎搜索	`g` Google / `gh` GitHub / `npm` NPM / `so` StackOverflow
计算器	输入算式直接计算，支持单位换算
快速笔记	临时记录想法，自动保存到本地
番茄钟	25分钟专注计时

2.3.5 扩展管理

功能	描述
搜索扩展	快速找到已安装扩展
启用/禁用	一键切换扩展状态
打开扩展选项	打开扩展的设置页面

2.3.6 Chrome 设置快捷入口

功能	目标 URL
设置	chrome://settings
扩展程序	chrome://extensions
下载内容	chrome://downloads
历史记录	chrome://history
书签管理器	chrome://bookmarks

2.4 P2 差异化功能（项目独特能力）

以下功能充分利用项目现有的 CDP、Native Host、MCP、Record & Replay 等能力，是 Raycast/Alfred 等桌面启动器无法实现的浏览器内独特功能。

2.4.1 Debug Bundle - 一键生成 Bug 报告

功能描述：一次命令自动采集截图、Console 日志、Network 请求（含 response body）、Performance trace，输出结构化报告包。

用户价值：把"复现+截图+抓包+性能+整理"从 10 分钟降到 30 秒，远程协作必备。

技术实现：

编排现有 Tools:
├── chrome_screenshot          → 截图
├── chrome_console             → Console 日志
├── chrome_network_debugger    → 网络请求 (含 body)
├── performance_trace          → 性能数据
└── trace-analyzer (native)    → AI 分析摘要

输出格式：

bug-report-2024xxxx/
├── screenshot.png
├── console.json
├── network.har
├── performance-summary.md
└── README.md (自动生成的报告)

复用现有能力：

network-capture-debugger.ts - CDP 抓包含 response body
performance.ts - Trace 采集
trace-analyzer.ts (native) - Trace 分析

2.4.2 API Detective - 抓包反推 API

功能描述：Quick Panel 开始抓包 → 用户执行一次操作 → 面板列出关键 XHR/Fetch → 选中后生成 curl/TypeScript fetch/请求重放。

用户价值：前后端联调、爬虫开发、逆向 Web API 都能快很多，不用 Charles/Postman。

技术实现：

// 流程
1. 用户触发 "API Detective" 命令
2. 调用 chrome_network_debugger_start 开始抓包
3. 用户在页面上执行操作
4. 用户按快捷键结束抓包
5. 过滤出 XHR/Fetch 请求，展示列表
6. 用户选择请求 → 生成代码/重放

生成代码示例：

# curl
curl 'https://api.example.com/data' \
  -H 'Authorization: Bearer xxx' \
  -H 'Content-Type: application/json' \
  --data-raw '{"page":1}'

// TypeScript fetch
const response = await fetch('https://api.example.com/data', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer xxx',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ page: 1 }),
});

复用现有能力：

network-capture-debugger.ts - CDP 抓包
chrome_network_request - 请求重放

2.4.3 Performance Assistant - 一键性能分析

功能描述：对当前页一键录制 Performance Trace（可选 reload），自动给出"摘要 + 指定 insight"。

用户价值：把性能分析从"会用 DevTools 的少数人"变成"所有开发者都能用"。

技术实现：

1. performance_start_trace    → 开始录制
2. (可选) 刷新页面
3. performance_stop_trace     → 停止并保存 trace
4. analyze_insight (native)   → AI 分析给出建议

输出示例：

## 性能分析报告

### 关键指标

- LCP: 2.3s (需优化)
- FID: 50ms (良好)
- CLS: 0.05 (良好)

### 主要问题

1. 首屏有 800ms 的 JavaScript 执行阻塞
2. 图片资源未使用懒加载
3. 第三方脚本占用 30% 加载时间

### 优化建议

1. 考虑代码拆分，延迟非关键 JS
2. 对 below-the-fold 图片添加 loading="lazy"
   ...

复用现有能力：

performance.ts - Trace 采集
trace-analyzer.ts (native) - 分析引擎

2.4.4 Workflow Runner - 运行录制的浏览器技能

功能描述：在 Quick Panel 搜索并运行已录制的工作流，支持参数输入，显示运行状态和日志。

用户价值：把重复网页操作变成"命令"，适合运营/测试/BD/开发。

技术实现：

Quick Panel 搜索 "flow:"
    ↓
显示已保存的工作流列表
    ↓
选择工作流 → 如有变量则弹出输入框
    ↓
调用 runFlow 引擎执行
    ↓
实时显示执行状态/失败截图

复用现有能力：

record-replay/ - 完整的工作流引擎
scheduler.ts - 变量收集弹层
已有触发器、定时、日志能力

2.4.5 Flow → MCP Tool - 把工作流发布为 AI 工具

功能描述：一键发布工作流（slug），使其成为 MCP 客户端可调用的工具 flow.<slug>。

用户价值：团队沉淀"浏览器能力 API"；让 AI 代理复用你验证过的流程。

技术实现：

Quick Panel 执行 "发布工作流" 命令
    ↓
选择要发布的 flow
    ↓
设置 slug 和描述
    ↓
native-server 动态注册为 MCP tool
    ↓
任意 MCP 客户端可调用 flow.<slug>

复用现有能力：

register-tools.ts (native) - 动态工具注册
native-host.ts - 列出已发布 flows

2.4.6 Web-to-Code - 点击元素改本地代码

功能描述：在本地开发环境，Quick Panel 触发"修改这个元素"，选中页面元素后，Agent 自动修改本地代码。

用户价值：设计/产品提改、前端调样式从"截图描述"变"点一下就改代码"。

技术实现：

1. Quick Panel 触发 Web-to-Code 模式
2. 进入元素选择（复用 Web Editor 的选择器）
3. 用户点击目标元素
4. 弹出修改意图输入框（如"改成红色"）
5. 调用 WEB_EDITOR_APPLY → 本地 Agent
6. SSE 订阅状态，显示修改进度

复用现有能力：

web-editor/ - 元素选择、fingerprint
WEB_EDITOR_APPLY - Agent 调用
native-server Agent 路由

2.4.7 Response Override - 命令面板里的 Mock

功能描述：Quick Panel 维护一组"临时网络规则"：匹配 URL → 返回自定义响应，用于联调/灰度/验证修复。

用户价值：前端联调不再依赖后端；QA 可在浏览器内复现边界条件。

技术实现：

// 规则配置
interface MockRule {
  urlPattern: string; // 匹配规则
  response: {
    status?: number;
    headers?: Record<string, string>;
    body?: string | object;
  };
  enabled: boolean;
}

// 使用 CDP Fetch.enable + Fetch.requestPaused

复用现有能力：

cdpSessionManager - CDP 命令发送
已有 declarativeNetRequest 权限

2.4.8 Userscript Studio - 脚本即命令

功能描述：Quick Panel 管理用户脚本：创建/启用/禁用/导出，并支持对脚本下发命令（脚本可响应命令执行特定动作）。

用户价值：把"临时修样式/改交互/加快捷键"变成可沉淀能力，且可被 Quick Panel 调度。

技术实现：

Quick Panel 执行 "> userscript"
    ↓
显示已安装脚本列表
    ↓
选择脚本 → 二级动作：
  - 启用/禁用
  - 发送命令（如果脚本支持）
  - 编辑
  - 删除

复用现有能力：

userscript.ts - 完整的 userscript 管理
已支持 MAIN/ISOLATED world、命令下发

2.4.9 No-API Integrations - 用登录态集成外部服务

功能描述：无需 API Token，通过录制/回放把"当前页面摘要→发到 Notion/Slack/建 GitHub issue"变成一条命令。

用户价值：绕过 OAuth/权限申请成本；对企业内网/无 API 的系统尤其有价值。

技术示例：

命令: "保存到 Notion"
流程:
1. 抓取当前页面内容（标题、正文、URL）
2. 切换到 Notion 标签页（或新开）
3. 执行已录制的"新建页面"工作流
4. 填入抓取的内容
5. 返回原标签页

复用现有能力：

Record & Replay - UI 自动化
chrome_get_web_content - 内容抓取
同一浏览器态 = 已登录状态

2.4.10 语义搜索（可选）

基于项目现有的 @xenova/transformers 能力
跨标签页内容语义搜索
根据语义相关性排序搜索结果

注意：需要下载模型，首次使用有等待时间

2.4.11 AI 增强（需要 Native Server + LLM）

功能	描述	依赖
总结页面	AI 总结当前页面要点	Native Agent
解释选中	解释选中的专业术语	Native Agent
翻译选中	智能翻译选中文字	Native Agent
智能命令	自然语言描述意图，AI 选择并执行命令	Native Agent

三、用户体验设计

3.1 交互流程

┌──────────────────────────────────────────────────────────────────┐
│                        Quick Panel 交互流程                       │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────┐    ┌──────────────┐    ┌─────────────┐             │
│  │ Cmd+K   │───▶│  显示面板     │───▶│  显示快捷入口  │             │
│  └─────────┘    └──────────────┘    │  + 最近使用   │             │
│                                     └───────┬─────┘             │
│                                             │                    │
│                    ┌────────────────────────┼────────────────┐   │
│                    ▼                        ▼                ▼   │
│            ┌─────────────┐         ┌─────────────┐   ┌──────────┐│
│            │ 点击快捷入口  │         │  输入搜索词   │   │ 输入命令 ││
│            │ (标签/书签/  │         └──────┬──────┘   │ (> xxx)  ││
│            │  历史/命令)  │                │          └────┬─────┘│
│            └──────┬──────┘                │               │      │
│                   │                        │               │      │
│                   ▼                        ▼               ▼      │
│            ┌─────────────┐         ┌─────────────┐   ┌──────────┐│
│            │ 进入 Scope   │         │  模糊搜索    │   │ 搜索命令 ││
│            │ 显示对应结果  │         │  显示结果    │   │ 显示结果 ││
│            └──────┬──────┘         └──────┬──────┘   └────┬─────┘│
│                   │                        │               │      │
│                   └────────────────────────┼───────────────┘      │
│                                            ▼                      │
│                                    ┌─────────────┐                │
│                                    │  选中结果    │                │
│                                    └──────┬──────┘                │
│                            ┌──────────────┼──────────────┐        │
│                            ▼              ▼              ▼        │
│                     ┌──────────┐   ┌──────────┐   ┌──────────┐   │
│                     │  Enter   │   │   Tab    │   │  Cmd+X   │   │
│                     │ 默认动作  │   │ 动作面板  │   │  关闭     │   │
│                     └──────────┘   └──────────┘   └──────────┘   │
│                                                                   │
└───────────────────────────────────────────────────────────────────┘

3.2 搜索策略

模糊匹配算法

精确匹配 > 前缀匹配 > 包含匹配 > 模糊匹配
多字段加权：标题权重 > URL 权重 > 域名权重
支持拼音首字母搜索（中文场景）

排序策略

匹配度分数
最近使用时间
使用频次
默认顺序

性能优化

书签/历史调用原生 chrome.bookmarks.search() / chrome.history.search() 获取候选集
前端做二次 fuzzy 匹配 + 排序
防抖处理，避免频繁搜索
虚拟列表渲染大量结果

3.3 快捷键设计

操作	快捷键	说明
唤起面板	`Cmd/Ctrl+Shift+K`	可配置，引导用户去 `chrome://extensions/shortcuts`
关闭面板	`Esc`
上移	`↑` / `Cmd+P`
下移	`↓` / `Cmd+N`
执行默认动作	`Enter`
新标签页打开	`Cmd+Enter`
后台打开	`Alt+Enter`
打开动作面板	`Tab` / `→` / `Cmd+K`
返回	`Backspace` / `←`	输入框为空时生效
切换到标签页搜索	`Cmd+T`
切换到书签搜索	`Cmd+B`
切换到历史搜索	`Cmd+H`

3.4 UI 设计

采用 液态玻璃风格 (Liquid Glass) 设计（参考 UI 设计稿 Version 6）

设计特点：

毛玻璃背景 + backdrop-filter
圆角卡片 (border-radius: 24px)
微妙的边框 (border: 1px solid rgba(255,255,255,0.4))
柔和的阴影
支持亮色/暗色主题

布局结构：

┌─────────────────────────────────────┐
│  🔍 搜索输入框              [⌘K]   │  ← 顶部搜索栏
├─────────────────────────────────────┤
│  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐  │
│  │标签页│ │书签 │ │历史 │ │命令 │  │  ← 快捷入口 (4宫格)
│  └─────┘ └─────┘ └─────┘ └─────┘  │
├─────────────────────────────────────┤
│  最近使用                           │
│  ┌─────────────────────────────┐   │
│  │ 📸 截取屏幕              ▶  │   │  ← 最近使用列表
│  │ 📋 复制链接              ▶  │   │
│  └─────────────────────────────┘   │
├─────────────────────────────────────┤
│  ↑↓ 导航  ↵ 选择  esc 关闭         │  ← 底部提示栏
└─────────────────────────────────────┘

四、技术实现架构

4.1 整体架构

┌────────────────────────────────────────────────────────────────────────┐
│                              Quick Panel 架构                           │
├────────────────────────────────────────────────────────────────────────┤
│                                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │                     Content Script (Inject)                      │  │
│  │  ┌─────────────────────────────────────────────────────────────┐│  │
│  │  │                     Shadow DOM Host                         ││  │
│  │  │  ┌─────────────────────────────────────────────────────┐   ││  │
│  │  │  │                    UI Layer                          │   ││  │
│  │  │  │  • PanelController (主面板协调器)                     │   ││  │
│  │  │  │  • SearchInput (搜索输入框)                          │   ││  │
│  │  │  │  • ResultList (结果列表 - 虚拟滚动)                   │   ││  │
│  │  │  │  • ActionPanel (动作面板)                            │   ││  │
│  │  │  │  • QuickEntries (快捷入口)                           │   ││  │
│  │  │  └─────────────────────────────────────────────────────┘   ││  │
│  │  │  ┌─────────────────────────────────────────────────────┐   ││  │
│  │  │  │                   Core Layer                         │   ││  │
│  │  │  │  • CommandRegistry (命令注册表)                       │   ││  │
│  │  │  │  • SearchEngine (搜索引擎)                           │   ││  │
│  │  │  │  • HistoryTracker (使用历史追踪)                      │   ││  │
│  │  │  │  • KeyboardController (键盘事件)                      │   ││  │
│  │  │  │  • MessageBridge (消息桥接)                          │   ││  │
│  │  │  └─────────────────────────────────────────────────────┘   ││  │
│  │  └─────────────────────────────────────────────────────────────┘│  │
│  └─────────────────────────────────────────────────────────────────┘  │
│                                    │                                   │
│                         chrome.runtime.sendMessage                     │
│                                    │                                   │
│                                    ▼                                   │
│  ┌─────────────────────────────────────────────────────────────────┐  │
│  │                       Background Script                          │  │
│  │  ┌─────────────────────────────────────────────────────────────┐│  │
│  │  │                  Quick Panel Handler                        ││  │
│  │  │  • 标签页操作 (chrome.tabs.*)                               ││  │
│  │  │  • 书签操作 (chrome.bookmarks.*)                            ││  │
│  │  │  • 历史操作 (chrome.history.*)                              ││  │
│  │  │  • 扩展管理 (chrome.management.*)                           ││  │
│  │  │  • 截图 (chrome.tabs.captureVisibleTab)                     ││  │
│  │  │  • 数据存储 (chrome.storage.*)                              ││  │
│  │  └─────────────────────────────────────────────────────────────┘│  │
│  └─────────────────────────────────────────────────────────────────┘  │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

4.2 目录结构

app/chrome-extension/entrypoints/
├── quick-panel.ts                    # 入口文件 (Content Script)
├── quick-panel/
│   ├── index.ts                      # 模块导出
│   ├── constants.ts                  # 常量定义 (样式、配置)
│   │
│   ├── core/
│   │   ├── panel-controller.ts       # 主面板控制器
│   │   ├── command-registry.ts       # 命令注册表
│   │   ├── search-engine.ts          # 搜索引擎 (fuzzy match)
│   │   ├── history-tracker.ts        # 使用历史追踪
│   │   ├── keyboard-controller.ts    # 键盘事件处理
│   │   └── message-bridge.ts         # Background 消息通信
│   │
│   ├── providers/
│   │   ├── base-provider.ts          # Provider 基类
│   │   ├── tabs-provider.ts          # 标签页 Provider
│   │   ├── bookmarks-provider.ts     # 书签 Provider
│   │   ├── history-provider.ts       # 历史记录 Provider
│   │   ├── commands-provider.ts      # 命令 Provider
│   │   └── search-engine-provider.ts # 搜索引擎 Provider
│   │
│   ├── commands/
│   │   ├── page-commands.ts          # 页面操作命令
│   │   ├── tab-commands.ts           # 标签页命令
│   │   ├── dev-commands.ts           # 开发者命令
│   │   └── utility-commands.ts       # 工具命令
│   │
│   ├── ui/
│   │   ├── shadow-host.ts            # Shadow DOM 宿主
│   │   ├── panel.ts                  # 主面板 UI
│   │   ├── search-input.ts           # 搜索输入框
│   │   ├── result-list.ts            # 结果列表 (虚拟滚动)
│   │   ├── result-item.ts            # 结果项
│   │   ├── action-panel.ts           # 动作面板
│   │   ├── quick-entries.ts          # 快捷入口
│   │   └── footer.ts                 # 底部提示栏
│   │
│   └── utils/
│       ├── fuzzy-match.ts            # 模糊匹配算法
│       ├── pinyin.ts                 # 拼音搜索支持
│       └── disposables.ts            # 资源清理
│
├── background/
│   └── quick-panel/
│       ├── index.ts                  # 消息处理入口
│       ├── tabs-handler.ts           # 标签页操作处理
│       ├── bookmarks-handler.ts      # 书签操作处理
│       ├── history-handler.ts        # 历史记录处理
│       └── screenshot-handler.ts     # 截图处理

4.3 消息类型定义

// common/message-types.ts 新增

export const QUICK_PANEL_ACTIONS = {
  // 面板控制
  TOGGLE: 'quick_panel_toggle',
  PING: 'quick_panel_ping',

  // 数据查询
  SEARCH_TABS: 'quick_panel_search_tabs',
  SEARCH_BOOKMARKS: 'quick_panel_search_bookmarks',
  SEARCH_HISTORY: 'quick_panel_search_history',

  // 标签页操作
  SWITCH_TAB: 'quick_panel_switch_tab',
  CLOSE_TAB: 'quick_panel_close_tab',
  CLOSE_OTHER_TABS: 'quick_panel_close_other_tabs',
  GROUP_TABS_BY_DOMAIN: 'quick_panel_group_tabs',

  // 页面操作
  CAPTURE_SCREENSHOT: 'quick_panel_screenshot',
  COPY_URL: 'quick_panel_copy_url',

  // 扩展管理
  GET_EXTENSIONS: 'quick_panel_get_extensions',
  TOGGLE_EXTENSION: 'quick_panel_toggle_extension',

  // 历史记录
  GET_RECENT_COMMANDS: 'quick_panel_get_recent',
  SAVE_COMMAND_USAGE: 'quick_panel_save_usage',
} as const;

4.4 核心类设计

PanelController (主控制器)

interface PanelController {
  // 生命周期
  show(): void;
  hide(): void;
  toggle(): boolean;
  dispose(): void;

  // 状态
  isVisible(): boolean;
  getCurrentScope(): Scope | null;

  // 搜索
  setQuery(query: string): void;
  setScope(scope: Scope): void;

  // 导航
  selectNext(): void;
  selectPrev(): void;
  executeSelected(): void;
  showActions(): void;
}

SearchEngine (搜索引擎)

interface SearchEngine {
  // 注册 Provider
  registerProvider(provider: SearchProvider): void;

  // 搜索
  search(query: string, scope?: Scope): Promise<SearchResult[]>;

  // 配置
  setMaxResults(count: number): void;
}

interface SearchProvider {
  id: string;
  name: string;
  icon: string;
  scope: Scope;

  search(query: string): Promise<SearchResult[]>;
  getActions(item: SearchResult): Action[];
}

interface SearchResult {
  id: string;
  provider: string;
  title: string;
  subtitle?: string;
  icon?: string | HTMLElement;
  data: unknown;
  score: number;
}

CommandRegistry (命令注册表)

interface Command {
  id: string;
  title: string;
  subtitle?: string;
  icon: string;
  keywords?: string[]; // 用于搜索的关键词
  category: CommandCategory;

  execute(): void | Promise<void>;
  isAvailable?(): boolean; // 动态判断命令是否可用
}

interface CommandRegistry {
  register(command: Command): void;
  unregister(id: string): void;
  getAll(): Command[];
  search(query: string): Command[];
  execute(id: string): Promise<void>;
}

五、详细任务拆解

Phase 1: 基础框架搭建 (P0)

1.1 Content Script 入口与 Shadow DOM

创建 quick-panel.ts 入口文件
实现 shadow-host.ts - Shadow DOM 宿主
- 创建 Shadow DOM 容器
- 注入样式
- 事件隔离（阻止冒泡到页面）
定义 constants.ts - 样式常量、配置常量
实现 disposables.ts - 资源清理工具类

1.2 主面板 UI

实现 panel.ts - 主面板容器
- 液态玻璃风格样式
- 显示/隐藏动画 (fade + scale)
- 点击外部区域关闭
实现 search-input.ts - 搜索输入框组件
- 输入框 + scope 标签显示
- 清空按钮
- 防抖输入处理
实现 quick-entries.ts - 四宫格快捷入口
- 标签页/书签/历史/命令四个入口
- hover 效果
- 点击进入对应 scope

1.3 结果列表

实现 result-list.ts - 结果列表容器
- 虚拟滚动（处理大量结果）
- 分组标题显示
- 空状态提示
实现 result-item.ts - 结果项组件
- 图标/标题/副标题/右侧操作
- 选中态样式
- hover 效果
实现 footer.ts - 底部提示栏
- 快捷键提示
- 状态指示器

1.4 核心控制器

实现 panel-controller.ts - 主控制器
- 协调各组件
- 管理面板状态
- 处理显示/隐藏逻辑
实现 keyboard-controller.ts - 键盘事件处理
- 全局快捷键监听
- 面板内导航快捷键
- 快捷键冲突处理

1.5 消息通信

扩展 message-types.ts - 新增 Quick Panel 消息类型
实现 message-bridge.ts - Content Script 侧消息发送
实现 background/quick-panel/index.ts - Background 消息处理入口

Phase 2: 搜索 Provider 实现 (P0)

2.1 搜索引擎核心

实现 search-engine.ts - 搜索引擎
- Provider 注册机制
- 并行搜索多个 Provider
- 结果合并与排序
实现 fuzzy-match.ts - 模糊匹配算法
- 字符串模糊匹配
- 匹配高亮
- 分数计算
实现 pinyin.ts - 拼音搜索支持（可选，使用成熟库）

2.2 标签页 Provider

实现 tabs-provider.ts
- 获取所有标签页（跨窗口）
- 标签页搜索（标题、URL、域名）
- 标签页图标获取
实现 background/quick-panel/tabs-handler.ts
- chrome.tabs.query 获取标签页
- chrome.tabs.update 切换标签页
- chrome.tabs.remove 关闭标签页

2.3 书签 Provider

实现 bookmarks-provider.ts
- 书签搜索
- 书签树遍历
实现 background/quick-panel/bookmarks-handler.ts
- chrome.bookmarks.search 搜索书签
- chrome.bookmarks.create/update/remove 书签操作

2.4 历史记录 Provider

实现 history-provider.ts
- 历史记录搜索
- 时间范围过滤
实现 background/quick-panel/history-handler.ts
- chrome.history.search 搜索历史
- chrome.history.deleteUrl 删除历史

2.5 命令 Provider

实现 commands-provider.ts
- 命令搜索
- 命令分类展示
实现 command-registry.ts - 命令注册表
- 命令注册/注销
- 命令执行

Phase 3: 基础命令实现 (P0)

3.1 页面操作命令

实现 page-commands.ts
- 复制当前链接 (URL)
- 复制为 Markdown
- 生成二维码
- 截取屏幕（可视区域）

3.2 标签页命令

实现 tab-commands.ts
- 新建标签页
- 新建窗口
- 新建隐身窗口

3.3 截图功能

实现 background/quick-panel/screenshot-handler.ts
- chrome.tabs.captureVisibleTab 截取可视区域
- 图片处理与下载

Phase 4: 动作面板与使用历史 (P0)

4.1 动作面板

实现 action-panel.ts
- 动作列表展示
- 键盘导航
- 执行动作后关闭
为每个 Provider 定义二级动作
- 标签页：切换、关闭、复制、固定、静音
- 书签：打开、新标签打开、复制、编辑、删除
- 历史：打开、新标签打开、复制、删除

4.2 使用历史追踪

实现 history-tracker.ts
- 记录命令使用
- 使用频次统计
- 最近使用排序
存储方案
- 使用 chrome.storage.local 存储
- 定期清理旧数据

Phase 5: 增值功能 - 标签页管理 (P1)

5.1 高级标签页操作

关闭右侧标签页
关闭其他标签页
按域名自动分组
合并所有窗口
标签休眠 (chrome.tabs.discard)

5.2 会话管理

保存当前会话
恢复历史会话
会话列表管理

Phase 6: 增值功能 - 页面工具 (P1)

6.1 截图增强

全页截图（滚动拼接）
选区截图

6.2 阅读模式

正文提取
沉浸式阅读 UI
字体/背景设置

6.3 其他页面工具

网页大纲（提取 H1-H6）
画中画
强制暗色模式
禅模式

Phase 7: 增值功能 - 开发者工具 (P1)

7.1 数据查看

Cookie 查看器
LocalStorage 查看器

7.2 注入工具

Design Mode 切换
CSS 注入
JS 注入

7.3 编解码工具

Base64 编解码
JSON 格式化

Phase 8: 增值功能 - 小工具 (P1)

8.1 多引擎搜索

Google / Bing / GitHub / NPM / StackOverflow
自定义搜索引擎

8.2 计算器

基础算术
单位换算

8.3 其他

快速笔记
番茄钟

Phase 9: 增值功能 - 扩展管理 (P1)

扩展列表展示
启用/禁用扩展
打开扩展选项页

Phase 10: 内容搜索 Provider (P1)

10.1 内容索引系统

实现 content-indexer.ts - 内容索引管理器
- 监听 tabs.onUpdated 触发索引
- 监听 webNavigation.onHistoryStateUpdated 处理 SPA
- 监听 tabs.onRemoved 清理缓存
复用 web-fetcher-helper.js 抽取正文
- 调用 Readability 提取正文
- 内容截断到 50KB
内容存储方案
- 使用 chrome.storage.session 或 Background 内存 Map
- 定期清理过期数据

10.2 内容搜索 Provider

实现 content-provider.ts
- 关键词精确匹配搜索
- 提取匹配上下文作为 snippet
- 高亮匹配关键词
实现 background/quick-panel/content-handler.ts
- 内容索引 CRUD
- 搜索接口

Phase 11: 差异化功能 - 开发者诊断 (P2)

11.1 Debug Bundle - 一键 Bug 报告

实现 debug-bundle-command.ts
- 编排多个 Tools 采集数据
- 生成结构化报告
- 支持导出/分享
集成现有能力
- chrome_screenshot 截图
- chrome_console 日志
- network-capture-debugger 抓包
- performance Trace

11.2 API Detective - 抓包反推 API

实现 api-detective-command.ts
- 开始/结束抓包流程
- 过滤 XHR/Fetch 请求
- 生成 curl/fetch 代码
请求重放功能
- 复用 chrome_network_request

11.3 Performance Assistant - 性能分析

实现 performance-assistant-command.ts
- 一键 Trace 录制
- 调用 native trace-analyzer 分析
- 展示分析报告

Phase 12: 差异化功能 - 工作流集成 (P2)

12.1 Workflow Runner

实现 workflow-provider.ts
- 搜索已保存的工作流
- 显示工作流列表
实现 workflow-runner-command.ts
- 变量输入弹窗
- 调用 runFlow 引擎
- 实时状态展示

12.2 Flow → MCP Tool

实现 publish-flow-command.ts
- 发布工作流为 MCP tool
- 设置 slug 和描述
与 native-server 通信
- 调用 register-tools 注册

Phase 13: 差异化功能 - 高级开发工具 (P2)

13.1 Web-to-Code

实现 web-to-code-command.ts
- 进入元素选择模式（复用 Web Editor）
- 意图输入弹窗
- 调用 WEB_EDITOR_APPLY
- SSE 状态订阅

13.2 Response Override

实现 mock-rules-command.ts
- Mock 规则管理 UI
- 规则 CRUD
实现 CDP 拦截
- 使用 Fetch.enable + Fetch.requestPaused

13.3 Userscript Studio

实现 userscript-provider.ts
- 脚本列表搜索
- 启用/禁用操作
- 命令下发

Phase 14: 差异化功能 - AI 增强 (P2/P3)

14.1 语义搜索（可选）

集成 @xenova/transformers
跨标签页内容向量索引
语义相关性排序

14.2 AI 命令（需要 Native Server）

页面总结
选中文本解释/翻译
智能命令匹配

六、技术风险与应对

6.1 技术限制

限制	影响	应对方案
特殊页面无法注入	`chrome://`、Chrome Web Store 等页面无法使用	提供 Popup 作为 fallback
唤起快捷键冲突	`Cmd+K` 可能被 Chrome 或网站占用	提供可配置快捷键，引导用户设置
剪贴板权限	读取剪贴板需要用户授权	仅在用户操作时请求

6.2 性能考虑

场景	风险	优化方案
大量标签页	搜索响应慢	虚拟列表 + 防抖 + 分页加载
大量书签/历史	内存占用高	原生 API 搜索 + 按需加载
频繁唤起面板	性能开销	组件复用，不销毁重建

七、里程碑计划

里程碑	范围	交付物
M1	Phase 1-4	MVP 版本：基础面板 + 五大 Provider（含内容搜索）+ 基础命令 + 动作面板
M2	Phase 5-6, 10	增值版本：高级标签页管理 + 页面工具 + 内容搜索
M3	Phase 7-9	完整版本：开发者工具 + 小工具 + 扩展管理
M4	Phase 11-12	差异化版本 I：Debug Bundle + API Detective + Performance Assistant + Workflow Runner
M5	Phase 13-14	差异化版本 II：Web-to-Code + Response Override + Userscript Studio + AI 增强

功能依赖说明

┌─────────────────────────────────────────────────────────────────────────┐
│                           功能依赖关系图                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  纯扩展能力（无额外依赖）        需要 Native Server           需要 CDP    │
│  ─────────────────────        ────────────────           ─────────    │
│  • 标签页/书签/历史搜索         • Performance 分析          • Debug Bundle │
│  • 基础命令                    • Web-to-Code              • API Detective│
│  • 标签页管理                  • Flow → MCP Tool          • Response Mock│
│  • 页面工具                    • AI 增强功能               • 网络抓包     │
│  • 扩展管理                                                             │
│  • 内容搜索                                                             │
│  • Workflow Runner                                                      │
│  • Userscript Studio                                                    │
│                                                                         │
│  ⚠️ CDP 相关功能注意事项：                                               │
│  - 如果 DevTools 已打开，debugger 会冲突                                 │
│  - 需要做降级提示                                                        │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

附录

A. 参考资源

UI 设计稿：quick-panel-ui.html (Version 6 液态玻璃风格)
现有架构参考：web-editor-v2/ (Shadow DOM、事件隔离、消息通信)
消息类型定义：common/message-types.ts

B. 相关 Chrome API

chrome.tabs - 标签页管理
chrome.bookmarks - 书签管理
chrome.history - 历史记录
chrome.management - 扩展管理
chrome.commands - 快捷键
chrome.storage - 数据存储
chrome.scripting - 脚本注入

51 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape

Quick Panel - 产品需求文档 (PRD)

一、产品概述

1.1 产品定位

1.2 核心价值主张

1.3 目标用户

1.4 入口形态

二、功能规划

2.1 功能分类总览

2.2 P0 核心功能 (MVP)

2.2.1 面板基础

2.2.2 搜索 Providers

2.2.3 标签页搜索

2.2.4 书签搜索

2.2.5 历史记录搜索

2.2.6 内容搜索（标签页正文搜索）

2.2.7 基础命令

2.2.7 最近使用

2.3 P1 增值功能

2.3.1 标签页高级管理

2.3.2 页面工具

2.3.3 开发者工具

2.3.4 小工具

2.3.5 扩展管理

2.3.6 Chrome 设置快捷入口

2.4 P2 差异化功能（项目独特能力）

2.4.1 Debug Bundle - 一键生成 Bug 报告

2.4.2 API Detective - 抓包反推 API

2.4.3 Performance Assistant - 一键性能分析

2.4.4 Workflow Runner - 运行录制的浏览器技能

2.4.5 Flow → MCP Tool - 把工作流发布为 AI 工具

2.4.6 Web-to-Code - 点击元素改本地代码

2.4.7 Response Override - 命令面板里的 Mock

2.4.8 Userscript Studio - 脚本即命令

2.4.9 No-API Integrations - 用登录态集成外部服务

2.4.10 语义搜索（可选）

2.4.11 AI 增强（需要 Native Server + LLM）

三、用户体验设计

3.1 交互流程

3.2 搜索策略

模糊匹配算法

排序策略

性能优化

3.3 快捷键设计

3.4 UI 设计

四、技术实现架构

4.1 整体架构

4.2 目录结构

4.3 消息类型定义

4.4 核心类设计

PanelController (主控制器)

SearchEngine (搜索引擎)

CommandRegistry (命令注册表)

五、详细任务拆解

Phase 1: 基础框架搭建 (P0)

1.1 Content Script 入口与 Shadow DOM

1.2 主面板 UI

1.3 结果列表

1.4 核心控制器

1.5 消息通信

Phase 2: 搜索 Provider 实现 (P0)

2.1 搜索引擎核心

2.2 标签页 Provider

2.3 书签 Provider

2.4 历史记录 Provider

2.5 命令 Provider

Phase 3: 基础命令实现 (P0)

3.1 页面操作命令

3.2 标签页命令

3.3 截图功能

Phase 4: 动作面板与使用历史 (P0)

4.1 动作面板

4.2 使用历史追踪

Phase 5: 增值功能 - 标签页管理 (P1)

5.1 高级标签页操作

5.2 会话管理

Phase 6: 增值功能 - 页面工具 (P1)

6.1 截图增强

6.2 阅读模式

6.3 其他页面工具

51 KiB

原始文件永久链接 Blame 文件历史