mirrors / hangwin--mcp-chrome

项目文件夹

hangwin--mcp-chrome
文件
feat/workflow
T
hangerye 8b7879d927 feat: [WIP]quick-panel
2025-12-31 17:56:15 +08:00

1352 行
51 KiB
Markdown
原始文件 永久链接 Blame 文件历史

此文件含有模棱两可的 Unicode 字符
此文件含有可能会与其他字符混淆的 Unicode 字符。 如果您是想特意这样的，可以安全地忽略该警告。 使用 Escape 按钮显示他们。
# 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)
┌──────────────┐ ┌──────────────┐ ┌───────────┐
│ 用户输入关键词│ ───▶ │ 遍历缓存匹配 │ ───▶ │ 返回结果 │
└──────────────┘ └──────────────┘ └───────────┘
```
**存储结构**：
```typescript
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。
**技术实现**：
```typescript
// 流程
1. 用户触发 "API Detective" 命令
2. 调用 chrome_network_debugger_start 开始抓包
3. 用户在页面上执行操作
4. 用户按快捷键结束抓包
5. 过滤出 XHR/Fetch 请求，展示列表
6. 用户选择请求 → 生成代码/重放
```
**生成代码示例**：
```bash
# curl
curl 'https://api.example.com/data' \
-H 'Authorization: Bearer xxx' \
-H 'Content-Type: application/json' \
--data-raw '{"page":1}'
```
```typescript
// 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 分析给出建议
```
**输出示例**：
```markdown
## 性能分析报告
### 关键指标
- 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 可在浏览器内复现边界条件。
**技术实现**：
```typescript
// 规则配置
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 搜索策略
#### 模糊匹配算法
1. **精确匹配** > **前缀匹配** > **包含匹配** > **模糊匹配**
2. 多字段加权：标题权重 > URL 权重 > 域名权重
3. 支持拼音首字母搜索（中文场景）
#### 排序策略
1. 匹配度分数
2. 最近使用时间
3. 使用频次
4. 默认顺序
#### 性能优化
- 书签/历史调用原生 `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 消息类型定义
```typescript
// 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 (主控制器)
```typescript
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 (搜索引擎)
```typescript
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 (命令注册表)
```typescript
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` - 脚本注入
在新工单中引用 查看 Git Blame 复制永久链接