# QuickFind-extenssion

**Repository Path**: tekintian/QuickFind-extenssion

## Basic Information

- **Project Name**: QuickFind-extenssion
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-11-03
- **Last Updated**: 2026-11-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">

# 🔍 QuickFind

### **一搜即达，极速定位您的数字足迹**

**最轻量、最智能、最尊重隐私的浏览器搜索增强工具**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![GitHub Repo](https://img.shields.io/badge/GitHub-QuickFind--extension-green)](https://github.com/tekintian/QuickFind-extenssion)

---

**QuickFind** 让您告别浏览器书签、历史记录和打开标签页的混乱。一键启动，智能搜索，毫秒响应——无论是模糊匹配还是精确查找，都能让您在瞬间找到所需内容。

> **Slogan**: 一搜即达 | Find anything, instantly

---

✨ **核心优势**

- ⚡ **极速响应** - 轻量级架构（< 150KB），毫秒级搜索体验
- 🎯 **智能匹配** - 双模式搜索（模糊/精确），支持 CJK 中日韩字符
- 🏷️ **标签系统** - 为书签打标签，让分类更清晰
- 🔐 **隐私优先** - 零数据收集，零外部请求，完全本地化运行
- 🌍 **双语支持** - 中英文无缝切换，自动检测浏览器语言
- ⚙️ **高度定制** - 丰富的配置选项，满足个性化需求
- 🌓 **自适应主题** - 自动跟随系统深色/浅色模式
- ⌨️ **快捷键导航** - 支持 Emacs/Vim 风格，提升效率

</div>

## Installation / 安装

本项目目前仅支持本地安装使用，安装步骤如下：

### 本地安装步骤

1. 克隆或下载本项目到本地
2. 执行构建命令：
   ```bash
   npm install
   npm run build

  npm run build:bundle && npm run build:create-dist
   ```
3. 浏览器扩展安装：
   - **Chrome/Edge**: 打开 `chrome://extensions/`，开启"开发者模式"，点击"加载已解压的扩展程序"，选择项目 `dist` 文件夹
   - **Firefox**: 打开 `about:debugging#/runtime/this-firefox`，点击"临时载入附加组件"，选择 `dist` 文件夹中的 `.xpi` 或 `manifest.json` 文件
   - **Opera**: 打开 `opera://extensions/`，开启"开发者模式"，点击"加载已解压的扩展程序"，选择项目 `dist` 文件夹

> 💡 更多本地开发信息请参考 [CONTRIBUTING.md#local-development](./docs/CONTRIBUTING.md#local-development)

## 功能特性

**本扩展不收集任何数据，也不进行任何外部请求**（参见[隐私保护](#隐私--数据保护)）。

### 🔎 智能搜索

- **双模式搜索**
  - 精确搜索：速度更快，精确匹配结果
  - 模糊搜索：近似匹配，找到更多相关内容
- **搜索结果排序**：基于多维度评分系统（标题、URL、标签、访问频率等）
- **高亮显示**：搜索关键词实时高亮，快速定位

### 🏷️ 标签管理

- 为书签添加标签，支持多标签管理
- 智能自动补全，提升标签输入效率
- 标签搜索模式（`#标签名`），精准筛选
- 支持标签组合搜索（AND 逻辑，如 `#github #pr`）

### 📁 文件夹导航

- 文件夹搜索模式（`~文件夹名`），快速定位特定目录
- 支持文件夹组合搜索，跨文件夹查找

### 🔍 高级搜索模式

| 模式 | 说明 | 示例 |
|------|------|------|
| `#标签` | 仅搜索包含指定标签的书签 | `#github #pr` |
| `~文件夹` | 仅搜索指定文件夹中的书签 | `~Sites ~Blogs` |
| `b 关键词` | 仅搜索书签 | `b quickfind` |
| `h 关键词` | 仅搜索历史记录和标签页 | `h tutorial` |
| `t 关键词` | 仅搜索打开的标签页 | `t docs` |
| `s 关键词` | 建议搜索引擎 | `s weather` |

### ⌨️ 快捷操作

- **快捷键启动**：默认 `Ctrl+Shift+.`（可自定义）
- **键盘导航**：
  - `Ctrl+J` / `Ctrl+N` - 向下选择
  - `Ctrl+K` / `Ctrl+P` - 向上选择
- **打开方式**：
  - 默认：在新标签页打开，或切换到已有标签页
  - `Shift` / `Alt`：在当前标签页打开
  - `Ctrl`：打开但不关闭搜索窗口
  - 右键：复制 URL 到剪贴板

### 🌍 多语言支持

- 支持**中文和英文**双语界面
- 系统自动根据浏览器语言选择默认语言
- 用户可以手动切换语言，设置会自动保存
- 完整的国际化（i18n）架构，易于扩展更多语言

> 💡 查看国际化文档：[I18N.md](./docs/I18N.md)

### ⚙️ 高度可定制

该扩展高度可定制（参见[用户配置](#用户配置)），并根据您的系统设置选择深色/浅色主题（参见 [prefers-color-scheme](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme)）。它非常轻量（包括依赖项在内的 JavaScript 代码少于 150kb）。

> 💡 查看使用技巧集合：[Tips & Tricks](./docs/Tips.md)


## 使用指南

### 基本操作

- **切换搜索模式**：点击搜索栏右上角的 **FUZZY**（模糊）或 **PRECISE**（精确）按钮
- **自定义快捷键**：默认 `Ctrl+Shift+.`，建议改为 `Ctrl+J` 更符合使用习惯
- **智能 URL 导航**：输入完整网址（如 `example.com`）可直接访问

### 高级技巧

**🎯 提升搜索结果的排名**
- 在书签标题中添加 ` +数字` 提升优先级
- 示例：`GitHub +20`、`QuickFind +10 #search #extension`

**🔧 自定义搜索引擎**
- 通过 `customSearchEngines` 配置选项添加自己的搜索别名
- 示例配置：
  ```yaml
  customSearchEngines:
    - alias: ['g', 'bing']
      name: Bing
      urlPrefix: https://cn.bing.com/search?q=$s
    - alias: npm
      name: NPM
      urlPrefix: https://www.npmjs.com/search?q=$s
  ```

**⚙️ 特殊页面支持**
- 可以将浏览器内部页面（如 `chrome://downloads`、`about:preferences`）添加到书签中快速访问

**🚫 最佳实践**
- 避免在非标签的书签标题中使用 `#`
- 避免在文件夹名称中使用 `~`
- 标签不能以数字开头（用于过滤 issue/ticket 号码）

---

## 架构概览

```
QuickFind 扩展架构
│
├── 📁 核心模块
│   ├── 搜索引擎 (Search Engine)
│   │   ├── 精确搜索 (Simple Search)
│   │   ├── 模糊搜索 (Fuzzy Search)
│   │   ├── 评分系统 (Scoring)
│   │   ├── 查询解析器 (Query Parser)
│   │   └── 搜索引擎集成 (Search Engines)
│   │
│   ├── 数据模型 (Data Model)
│   │   ├── 选项配置 (Options)
│   │   └── 搜索数据 (Search Data)
│   │
│   └── 视图层 (View Layer)
│       ├── 搜索视图 (Search View)
│       ├── 书签编辑 (Edit Bookmark)
│       ├── 标签管理 (Tags)
│       ├── 文件夹管理 (Folders)
│       └── 选项设置 (Options)
│
├── 🌐 浏览器接口 (Browser API)
│   ├── 书签 API (Bookmarks)
│   ├── 历史记录 API (History)
│   ├── 标签页 API (Tabs)
│   └── 存储 API (Storage)
│
└── 🛠️ 工具模块 (Helpers)
    ├── 浏览器 API 封装 (Browser API Wrapper)
    ├── 状态管理 (State Manager)
    ├── 国际化 (i18n)
    └── 工具函数 (Utils)
```

### 技术栈

- **搜索算法**: uFuzzy（模糊搜索）、自定义精确搜索
- **UI 框架**: 原生 JavaScript + CSS
- **构建工具**: esbuild、Biome
- **测试框架**: Jest（单元测试）、Playwright（E2E 测试）
- **依赖库**:
  - `@leeoniya/ufuzzy` - 模糊匹配算法
  - `@yaireo/tagify` - 标签输入组件
  - `mark.js` - 搜索结果高亮
  - `js-yaml` - 配置文件解析

---

## 性能优化

### 默认性能配置

QuickFind 已针对大多数使用场景进行优化，但您可以根据需求调整：

**提升搜索速度**（低性能设备）
```yaml
searchStrategy: precise           # 使用精确搜索
searchMinMatchCharLength: 2       # 输入 2 字符后才开始搜索
displaySearchMatchHighlight: false # 禁用高亮以提升渲染性能
searchMaxResults: 20              # 限制搜索结果数量
historyMaxItems: 512              # 减少加载的历史记录
maxRecentTabsToShow: 4            # 限制显示的标签页数量
detectDuplicateBookmarks: false    # 禁用重复检测
detectBookmarksWithOpenTabs: false # 禁用书签-标签匹配
```

**平衡性能与功能**
```yaml
searchStrategy: fuzzy             # 使用模糊搜索
historyMaxItems: 2048            # 增加历史记录数量
maxRecentTabsToShow: 32          # 显示更多标签页
```

**完整配置示例**
```yaml
searchStrategy: fuzzy
searchMinMatchCharLength: 1
historyMaxItems: 2048
maxRecentTabsToShow: 8
detectDuplicateBookmarks: true
detectBookmarksWithOpenTabs: true
```

## 用户配置

该扩展高度可定制。用户选项使用 [YAML](https://en.wikipedia.org/wiki/YAML) 或 [JSON](https://en.wikipedia.org/wiki/JSON) 表示法编写。

> 📘 **查看 [OPTIONS.md](./docs/OPTIONS.md) 了解所有可用选项的完整列表。**

> ⚠️ **注意**: 选项不会进行严格验证，请确保正确使用。如果出现问题，请考虑重置您的选项。

### 基础配置示例

```yaml
searchStrategy: fuzzy              # 搜索策略：fuzzy（模糊）或 precise（精确）
displayVisitCounter: true          # 显示访问次数
historyMaxItems: 2048              # 历史记录最大数量
maxRecentTabsToShow: 32            # 显示的标签页数量
```

### 高级配置示例

```yaml
# 搜索策略
searchStrategy: fuzzy
searchMinMatchCharLength: 1
searchMaxResults: 50

# 历史记录设置
historyDaysAgo: 30                 # 保留最近 30 天的历史
historyMaxItems: 2048
historyIgnoreList:                 # 忽略的 URL 模式
  - extension://
  - http://localhost
  - http://127.0.0.1

# 显示设置
displayVisitCounter: true
displaySearchMatchHighlight: true
colorStripeWidth: 4                # 颜色条纹宽度

# 评分系统
scoreBookmarkBase: 100             # 书签基础分数
scoreTabBase: 70                   # 标签页基础分数
scoreVisitedBonusScoreMaximum: 20   # 访问奖励最大值

# 检测功能
detectDuplicateBookmarks: true      # 检测重复书签
detectBookmarksWithOpenTabs: true   # 匹配已打开的标签页

# 搜索引擎
customSearchEngines:
  - alias: ['g', 'bing']
    name: Bing
    urlPrefix: https://cn.bing.com/search?q=$s
    blank: https://cn.bing.com
  - alias: [gh, github]
    name: GitHub
    urlPrefix: https://github.com/search?q=$s
    blank: https://github.com
```

### CJK 中日韩字符优化

```yaml
# 使 CJK 字符适用于模糊搜索
uFuzzyOptions:
  interSplit: (p{Unified_Ideograph=yes})+
```

---

## 评分系统详解

QuickFind 使用智能的**5 步评分算法**，确保最相关的结果排在前面：

### 评分流程

```
1️⃣ 基础分数 (Base Score)
   ↓ 每种结果类型有不同基础值
   - 书签: 100
   - 标签页: 70
   - 历史记录: 60
   - 搜索引擎: 50

2️⃣ 搜索质量乘数 (Search Quality Multiplier)
   ↓ 匹配质量（0-1）
   - 模糊/精确搜索算法返回

3️⃣ 字段特定奖励 (Field-Specific Bonus)
   ↓ 根据匹配位置和内容加分
   - 精确开头匹配: scoreExactStartsWithBonus
   - 精确完全匹配: scoreExactEqualsBonus
   - 标签匹配: scoreExactTagMatchBonus
   - 文件夹匹配: scoreExactFolderMatchBonus
   - 子字符串匹配: scoreExactIncludesBonus（按权重加权）
     * 标题权重: 1.0
     * 标签权重: 0.7
     * URL 权重: 0.6
     * 文件夹权重: 0.5

4️⃣ 行为奖励 (Behavioral Bonus)
   ↓ 根据使用习惯调整
   - 访问频率奖励: scoreVisitedBonusScore
   - 最近访问奖励: scoreRecentBonusScoreMaximum

5️⃣ 自定义奖励 (Custom Bonus)
   ↓ 用户手动调整
   - 书签标题中的 `+数字`（需启用 scoreCustomBonusScore）
```

### 评分配置选项

| 选项 | 默认值 | 说明 |
|------|--------|------|
| `scoreBookmarkBase` | 100 | 书签基础分数 |
| `scoreTabBase` | 70 | 标签页基础分数 |
| `scoreHistoryBase` | 60 | 历史记录基础分数 |
| `scoreSearchEngineBase` | 50 | 搜索引擎基础分数 |
| `scoreExactStartsWithBonus` | 15 | 精确开头匹配奖励 |
| `scoreExactEqualsBonus` | 25 | 精确完全匹配奖励 |
| `scoreExactTagMatchBonus` | 20 | 精确标签匹配奖励 |
| `scoreExactFolderMatchBonus` | 15 | 精确文件夹匹配奖励 |
| `scoreExactIncludesBonus` | 5 | 子字符串匹配奖励 |
| `scoreVisitedBonusScore` | 1 | 每次访问奖励 |
| `scoreVisitedBonusScoreMaximum` | 20 | 访问奖励最大值 |
| `scoreRecentBonusScoreMaximum` | 10 | 最近访问奖励最大值 |
| `scoreCustomBonusScore` | true | 启用自定义奖励 |

### 示例：如何提升搜索排名

**方法 1：添加自定义奖励**
```
GitHub +20               # 提升 20 分
QuickFind +10 #search    # 提升 10 分 + 标签奖励
```

**方法 2：使用精确匹配关键词**
```
搜索 "quickfind" 会优先显示：
✅ QuickFind (精确匹配)
✅ QuickFind Extension (开头匹配)
⭕ My QuickFind Tips (包含匹配)
```

**方法 3：使用标签和文件夹**
```
搜索 "#github #pr" 会优先显示：
✅ 同时包含 #github 和 #pr 标签的书签
```

> 📖 **详细实现**: 查看 [popup/js/search/scoring.js](popup/js/search/scoring.js)

## 隐私保护 🔒

QuickFind 的设计理念是**完全尊重用户隐私**：

| 隐私特性 | 说明 |
|---------|------|
| **零外部请求** | 没有任何网络通信，数据永不外传 |
| **临时内存** | 除用户配置外，所有数据在弹出窗口关闭时立即清除 |
| **无后台服务** | 只有在打开搜索窗口时才运行，无后台进程 |
| **开源透明** | 完全开源，代码可审计 |

### 权限说明

该扩展仅请求必要的浏览器权限：

| 权限 | 用途 | 可禁用 |
|------|------|--------|
| `bookmarks` | 读取和编辑书签 | ✅ 可通过配置禁用 |
| `history` | 读取浏览历史 | ✅ 可通过配置禁用或限制 |
| `tabs` | 查找和管理标签页 | ✅ 可通过配置禁用 |
| `storage` | 存储用户配置 | ❌ 必需 |

### 数据存储

- **用户配置**：存储在浏览器本地存储（Local Storage）
- **浏览器同步**：如果启用浏览器同步，配置会随之同步
- **零持久化**：书签、历史、标签页等数据实时读取，不持久化存储

---

## 开发指南 🛠️

### 环境要求

- **Node.js**: ^20.20.0
- **包管理器**: npm

### 快速开始

```bash
# 克隆仓库
git clone https://github.com/tekintian/QuickFind-extenssion.git
cd QuickFind-extension

# 安装依赖
npm install

# 构建项目
npm run build

# 运行测试
npm run test

# 启动开发服务器
npm start
```

### 可用命令

| 命令 | 说明 |
|------|------|
| `npm run build` | 构建项目（清理 + 打包 + 格式化） |
| `npm run test` | 运行单元测试 |
| `npm run test:watch` | 监听模式运行单元测试 |
| `npm run test:e2e` | 运行 E2E 测试（Playwright） |
| `npm run lint` | 代码检查 |
| `npm run lint:fix` | 自动修复代码问题 |
| `npm run format` | 格式化代码 |
| `npm run start` | 启动开发服务器 |
| `npm run size` | 查看构建产物大小 |

### 项目结构

```
QuickFind/
├── manifest.json          # 扩展配置清单
├── package.json           # 项目配置和依赖
├── popup/                 # 弹出窗口界面
│   ├── index.html        # 主搜索界面
│   ├── options.html      # 设置页面
│   ├── editBookmark.html # 书签编辑
│   ├── folders.html      # 文件夹管理
│   ├── tags.html         # 标签管理
│   ├── css/              # 样式文件
│   ├── js/               # JavaScript 模块
│   │   ├── init*.js      # 页面初始化脚本
│   │   ├── helper/       # 工具函数
│   │   ├── model/        # 数据模型
│   │   ├── search/       # 搜索引擎
│   │   └── view/         # 视图层
│   └── lib/              # 第三方库
├── bin/                  # 构建脚本
├── docs/                 # 项目文档
├── images/               # 图标和资源
├── playwright/           # E2E 测试
└── __tests__/           # 单元测试
```

### 核心模块说明

#### 搜索引擎 (`popup/js/search/`)
- `simpleSearch.js` - 精确搜索实现
- `fuzzySearch.js` - 模糊搜索实现（基于 uFuzzy）
- `scoring.js` - 评分系统
- `queryParser.js` - 查询解析器
- `taxonomySearch.js` - 标签和文件夹搜索
- `searchEngines.js` - 搜索引擎集成

#### 数据模型 (`popup/js/model/`)
- `options.js` - 用户配置管理
- `searchData.js` - 搜索数据加载和缓存

#### 视图层 (`popup/js/view/`)
- `searchView.js` - 搜索结果渲染
- `searchEvents.js` - 搜索事件处理
- `searchNavigation.js` - 键盘导航
- `editBookmarkView.js` - 书签编辑界面

#### 工具模块 (`popup/js/helper/`)
- `browserApi.js` - 浏览器 API 封装
- `i18n.js` - 国际化支持
- `stateManager.js` - 状态管理
- `utils.js` - 通用工具函数

> 📖 **详细开发文档**: [CONTRIBUTING.md](./docs/CONTRIBUTING.md)

---

## 测试 🧪

### 单元测试

```bash
# 运行所有单元测试
npm run test

# 监听模式
npm run test:watch

# 生成覆盖率报告
npm run test:unit:coverage
```

### E2E 测试

```bash
# 运行所有 E2E 测试
npm run test:e2e

# 指定浏览器
npm run test:e2e:chromium
npm run test:e2e:firefox
npm run test:e2e:edge

# 生成 HTML 报告
npm run test:e2e:html
```

---

## 常见问题 ❓

<details>
<summary><b>Q: 搜索速度变慢怎么办？</b></summary>

可以尝试以下优化：
1. 切换到精确搜索模式 (`searchStrategy: precise`)
2. 增加 `searchMinMatchCharLength` 到 2 或 3
3. 减少 `historyMaxItems` 的值
4. 减少 `maxRecentTabsToShow` 的值
5. 禁用搜索结果高亮 (`displaySearchMatchHighlight: false`)
</details>

<details>
<summary><b>Q: 如何备份我的配置？</b></summary>

配置存储在浏览器的本地存储中。可以通过以下方式备份：
1. 打开扩展的选项页面
2. 复制配置内容
3. 保存到本地文件

恢复时，将配置粘贴回选项页面即可。
</details>

<details>
<summary><b>Q: 中日韩字符搜索不正常？</b></summary>

需要在用户配置中添加：
```yaml
uFuzzyOptions:
  interSplit: (p{Unified_Ideograph=yes})+
```
</details>

<details>
<summary><b>Q: 如何添加自定义搜索引擎？</b></summary>

在用户配置中添加：
```yaml
customSearchEngines:
  - alias: ['keyword', 'kw']
    name: My Search
    urlPrefix: https://example.com/search?q=$s
    blank: https://example.com
```
</details>

---

## 更新日志 📅

查看 [CHANGELOG.md](./CHANGELOG.md) 了解版本更新历史。

---

## 贡献指南 🤝

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 贡献规范

- 遵循现有代码风格
- 添加必要的测试
- 更新相关文档
- 保持提交信息清晰

> 📖 **详细贡献指南**: [CONTRIBUTING.md](./docs/CONTRIBUTING.md)

---

## 致谢 🙏

本扩展使用了以下优秀的开源项目：

| 项目 | 用途 |
|------|------|
| [search-bookmarks-history-and-tabs](https://github.com/Fannon/search-bookmarks-history-and-tabs) | 项目灵感来源 |
| [uFuzzy](https://github.com/leeoniya/uFuzzy) | 模糊搜索算法 |
| [Tagify](https://github.com/yairEO/tagify) | 标签输入组件 |
| [Mark.js](https://markjs.io/) | 搜索结果高亮 |
| [js-yaml](https://www.npmjs.com/package/js-yaml) | 配置文件解析 |
| [Tabler Icons](https://github.com/tabler/tabler-icons) | 图标库 |
| [Custom CSS Reset](https://www.joshwcomeau.com/css/custom-css-reset/) | CSS 重置样式 |

特别感谢 [Fannon](https://github.com/Fannon) 创建的原始项目，为 QuickFind 提供了坚实的基础和灵感！

---

## 反馈与支持 💬

- **问题报告**: [GitHub Issues](https://github.com/tekintian/QuickFind-extenssion/issues)
- **功能建议**: [GitHub Discussions](https://github.com/tekintian/QuickFind-extenssion/discussions)
- **问题咨询**: 欢迎在 Issues 中提问

所有的想法、建议和 Bug 报告都欢迎！

---

## 许可证 📄

本项目基于 [MIT License](./LICENSE) 开源协议发布。

---

## 贡献者 👥

- **[tekintian](https://github.com/tekintian)** - 创建者、核心开发、文档维护
- **[Fannon](https://github.com/Fannon)** - 原始项目创建者、架构设计

---

<div align="center">

**如果 QuickFind 对你有帮助，请给一个 ⭐️ Star！**

Made with ❤️ by tekintian

</div>