search-syntax-pro/README.zh-CN.md

# SearchSyntax Pro - 搜索语法大师

<div align="center">

[![CI](https://github.com/lhly/search-syntax-pro/actions/workflows/release.yml/badge.svg)](https://github.com/lhly/search-syntax-pro/actions/workflows/release.yml)
[![Version](https://img.shields.io/badge/version-1.7.0-blue.svg)](https://github.com/lhly/search-syntax-pro/releases)
[![Edge Add-ons](https://img.shields.io/badge/Edge-Install-blue?logo=microsoft-edge)](https://microsoftedge.microsoft.com/addons/detail/搜索语法大师/jhbaiiccckiclmgmoclidimjfcneeofh)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**简体中文** | [English](README.md)

</div>

**一个专业级的搜索语法可视化工具**，支持 10 个搜索引擎和 28 种高级搜索语法，让复杂搜索变得简单易用。

## 为什么选择 SearchSyntax Pro？

### 📊 功能对比

| 传统搜索方式 | SearchSyntax Pro |
|------------|------------------|
| ❌ 只能使用简单关键词 | ✅ **28种高级语法**，专业级搜索能力 |
| ❌ 需要记忆复杂的语法规则 | ✅ **可视化界面**，零学习成本 |
| ❌ 手动输入易出错 | ✅ **智能验证**，实时纠错 |
| ❌ 单一搜索引擎受限 | ✅ **10个引擎**随意切换 |
| ❌ 不同引擎语法不通用 | ✅ **自动适配**不同引擎特性 |

### 🌟 核心优势

**规模优势**：
- 🌐 **10个搜索引擎** - 通用搜索 6个 + 专业平台 4个
- 🔍 **28种高级语法** - 通用语法 14个 + 平台专属 14+个
- 📄 **13种文件格式** - Office文档、PDF、图片、压缩包全覆盖

**体验优势**：
- ⚡ **零学习成本** - 可视化表单替代复杂语法记忆
- 🎯 **智能适配** - 根据引擎自动调整语法支持
- 🔄 **一键切换** - 同一查询在不同引擎间无缝复用

---

## 功能特点

### 🌐 强大的搜索引擎支持

**10个主流搜索引擎**，满足不同场景需求：

| 类别 | 支持的引擎 |
|------|-----------|
| **通用搜索** | 百度、谷歌、必应、DuckDuckGo、Brave、Yandex |
| **专业平台** | Twitter/X、Reddit、GitHub、Stack Overflow |

### 🔍 28种专业搜索语法

让您像搜索专家一样精准找到所需信息：

#### **通用语法（14种）**

**✅ 已实现（4种）**
- **网站内搜索** (`site:`) - 限定特定网站或域名
- **文件类型** (`filetype:`) - 支持13种常见格式（PDF、DOCX、XLSX、PPT、图片、压缩包等）
- **精确匹配** (`"..."`) - 完整短语搜索，不拆分关键词
- **日期范围** - 按发布时间筛选结果

**🔜 计划实现（10种）**
- **标题搜索** (`intitle:`) - 在网页标题中查找关键词
- **URL搜索** (`inurl:`) - 在网址中查找关键词
- **排除关键词** (`-`) - 过滤不需要的搜索结果
- **逻辑或** (`OR` / `|`) - 匹配多个关键词之一
- **正文搜索** (`intext:`) - 在网页正文中查找
- **数字范围** (`..`) - 搜索指定数值区间
- **通配符** (`*`) - 模糊匹配未知部分
- **全标题匹配** (`allintitle:`) - 所有关键词都在标题中
- **相关网站** (`related:`) - 查找相似站点
- **网页缓存** (`cache:`) - 查看历史快照

#### **平台专属语法（14+种）**

**Twitter/X 专属（8种）**
- `from:@user` - 来自特定用户的推文
- `to:@user` - 发送给特定用户的推文
- `filter:images/videos/links/media` - 内容类型过滤
- `min_retweets:N` - 最少转发数筛选
- `min_faves:N` - 最少点赞数筛选
- `lang:xx` - 语言筛选
- 日期范围和排除关键词支持

**GitHub 专属**
- 代码仓库搜索、Issue 筛选、用户查找等

**Reddit 专属**
- 子版块筛选、作者筛选、分数筛选等

**Stack Overflow 专属**
- 标签筛选、投票数筛选、回答状态筛选等

### 💡 智能辅助系统

- **实时验证** - 自动检查语法正确性，避免搜索错误
- **智能建议** - 根据搜索引擎特性提供优化建议
- **错误预防** - 友好的错误和警告提示

### 📝 用户友好特性

- **搜索历史** - 自动保存，快速重用历史搜索
- **一键复制** - 生成的查询语句即复制即用
- **多语言界面** - 完整的中英文支持
- **响应式设计** - 适配各种屏幕尺寸
- **右键快速搜索** - 选中文本 → 右键菜单 → 自动填充到可视化搜索界面

### 🪟 窗口管理

- **独立窗口模式** - 不占用浏览器标签页，专注搜索
- **快捷键支持** - `Ctrl+Shift+F` (Win/Linux) 或 `Cmd+Shift+F` (Mac)
- **灵活切换** - 弹窗与独立窗口模式自由切换
- **状态保持** - 自动保存窗口位置和设置

### ⚙️ 个性化配置

- **搜索引擎管理** - 自定义显示顺序和可见性
- **拖拽排序** - 直观的拖放操作调整顺序
- **偏好保存** - 记住您的选择和配置
- **界面定制** - 隐藏不常用的引擎，简化界面

## 技术架构

### 核心技术栈
- **TypeScript 5.x**: 类型安全的开发体验
- **React 18.x**: 现代化UI组件开发
- **Vite 5.x**: 快速构建工具
- **Tailwind CSS**: 实用优先的CSS框架

### Chrome扩展技术
- **Manifest V3**: 最新Chrome扩展标准
- **Service Worker**: 后台服务处理
- **Content Scripts**: 页面内容注入
- **Chrome Storage API**: 本地数据存储
- **国际化支持**: 完整的 i18n 架构，支持多语言扩展

### 搜索引擎适配器
- **适配器模式**: 可扩展的搜索引擎架构
- **统一接口**: 一致的API设计
- **专用优化**: 针对不同搜索引擎的特性优化

## 安装方法

### 浏览器扩展商店（推荐）

#### Microsoft Edge
[![Edge Add-ons](https://img.shields.io/badge/Edge-Install-blue?logo=microsoft-edge)](https://microsoftedge.microsoft.com/addons/detail/搜索语法大师/jhbaiiccckiclmgmoclidimjfcneeofh)

访问 [Edge 扩展商店](https://microsoftedge.microsoft.com/addons/detail/搜索语法大师/jhbaiiccckiclmgmoclidimjfcneeofh) 点击"获取"按钮即可安装。

#### Chrome Web Store
🚧 Chrome Web Store 版本即将上线，敬请期待！

### 开发者模式安装

如果您是开发者或想要使用最新的开发版本：

1. 克隆本项目到本地
```bash
git clone https://github.com/lhly/search-syntax-pro.git
cd search-syntax-pro
```

2. 安装依赖
```bash
npm install
```

3. 构建项目
```bash
npm run build
```

4. 在浏览器中加载扩展

   **Chrome/Edge**:
   - 访问 `chrome://extensions/` 或 `edge://extensions/`
   - 开启"开发者模式"
   - 点击"加载已解压的扩展程序"
   - 选择项目的 `dist` 目录

## 使用方法

### 基础搜索
1. 点击扩展图标打开搜索面板
2. 输入搜索关键词
3. 选择搜索引擎
4. 点击"执行搜索"查看结果

### 高级搜索
1. 展开"高级搜索选项"
2. **网站内搜索**: 输入网站域名（如 wikipedia.org）
3. **文件类型**: 选择特定文件格式（如 PDF、DOCX）
4. **精确匹配**: 输入要精确匹配的短语
5. 查看实时生成的搜索查询
6. 点击"执行搜索"

### 搜索历史
1. 在主界面查看最近的搜索记录
2. 点击历史记录快速恢复搜索设置
3. 使用"清除历史"清理记录

## 开发指南

### 项目结构
```
src/
├── components/          # React组件
├── services/           # 业务逻辑服务
│   ├── adapters/       # 搜索引擎适配器
│   └── storage.ts      # 数据存储服务
├── hooks/              # 自定义React Hooks
├── types/              # TypeScript类型定义
├── popup/              # 弹窗界面
├── options/            # 设置页面
├── background/         # 后台脚本
└── content/            # 内容脚本
```

### 开发命令
```bash
# 开发模式（带热重载）
npm run dev

# 构建生产版本
npm run build

# 类型检查
npm run type-check

# 代码格式化
npm run format

# 运行测试
npm run test

# E2E测试
npm run test:e2e

# 代码检查
npm run lint
```

### 添加新搜索引擎
1. 在 `src/services/adapters/` 目录创建新的适配器文件
2. 实现 `SearchEngineAdapter` 接口
3. 在 `SearchAdapterFactory` 中注册新适配器
4. 更新类型定义中的搜索引擎类型

### 自定义UI主题
1. 修改 `tailwind.config.js` 中的主题配置
2. 在组件中使用主题变量
3. 测试深色/浅色模式切换

## 测试

### 单元测试
- 使用 Jest + React Testing Library
- 覆盖核心业务逻辑
- 测试组件渲染和交互

### E2E测试
- 使用 Playwright 进行端到端测试
- 模拟真实用户操作
- 测试Chrome扩展功能

### 运行测试
```bash
# 运行所有测试
npm test

# 运行特定测试文件
npm test -- SearchForm.test.tsx

# 运行E2E测试
npm run test:e2e

# 测试覆盖率
npm run test:coverage
```

## 📦 发布流程

### 自动化发布（推荐）

本项目使用 GitHub Actions 实现自动化构建和发布。

#### 快速发布新版本

```bash
# 1. 更新版本号（自动更新 package.json 和 manifest.json）
npm version patch   # 补丁版本：1.5.0 -> 1.5.1
npm version minor   # 次版本：1.5.0 -> 1.6.0
npm version major   # 主版本：1.5.0 -> 2.0.0

# 2. 推送代码和标签
git push origin main
git push origin --tags

# 3. 等待 GitHub Actions 完成（3-5分钟）
# 访问 https://github.com/lhly/search-syntax-pro/actions 查看进度

# 4. 在 Releases 页面审查并发布
# 访问 https://github.com/lhly/search-syntax-pro/releases

# 5. 下载 ZIP 文件上传到 Chrome Web Store
```

#### CI/CD 工作流说明

- **触发条件**：
  - Tag 推送 (v*.*.*)：触发完整的构建、测试、打包和发布流程
  - Main 分支推送：仅进行构建和测试（不发布）
  - Pull Request：代码审查时的质量检查

- **自动化步骤**：
  1. 🔨 构建和测试（类型检查、Lint、单元测试）
  2. ✅ 版本一致性验证
  3. 📦 生成 ZIP 安装包
  4. 🚀 创建 GitHub Release（草稿状态）

- **构建产物**：
  - `ssp-v{version}.zip`：Chrome 扩展安装包
  - 构建日志和测试报告

### 手动发布（传统方式）

如需手动发布，执行以下步骤：

```bash
# 1. 构建项目
npm run build

# 2. 打包扩展
npm run package

# 3. 在 releases/ 目录找到生成的 ZIP 文件
ls -lh releases/

# 4. 手动上传到 Chrome Web Store
```

## 贡献指南

### 提交代码
1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

### 代码规范
- 遵循 ESLint 和 Prettier 配置
- 添加适当的类型注释
- 编写单元测试
- 更新相关文档

### Issue 报告
- 使用 GitHub Issues 报告问题
- 提供详细的复现步骤
- 包含浏览器版本和系统信息

## 隐私政策

- 本扩展不收集任何用户个人信息
- 所有数据仅存储在用户本地设备
- 不会向第三方服务器传输任何数据
- 用户可以随时清除所有本地存储的数据

## 开源协议

本项目采用 MIT 协议开源。详见 [LICENSE](LICENSE) 文件。

## 更新日志

### v1.7.0 (2025-11-13)
- 🪟 **独立窗口功能**
  - 支持在独立窗口中使用搜索功能，不占用浏览器标签页
  - 快捷键快速打开（`Ctrl+Shift+F` / `Cmd+Shift+F`）
  - 窗口状态自动保存和恢复
  - 弹窗与独立窗口模式灵活切换
- 🌐 **完整国际化支持**
  - 新增英文语言包（`en`）
  - 优化多语言切换体验
  - 所有UI文本支持国际化
  - 基于浏览器语言自动选择界面语言
- 🏪 **商店发布**
  - 正式上架 Microsoft Edge 扩展商店
  - 完善商店资产和用户引导文档

### v1.6.0 (2025-11-12)
- ⚙️ **搜索引擎管理**
  - 可自定义搜索引擎显示顺序
  - 支持拖拽排序操作
  - 搜索引擎显示/隐藏配置
  - 用户偏好自动保存
- 📝 **文档完善**
  - 新增 Edge 商店提交完整指南
  - 添加商店资产制作指南
  - 完善隐私政策和商店发布内容
  - 添加搜索引擎文档

### v1.5.0 (2025-11-10)
- 🚀 **新增自动化 CI/CD 流程**
  - GitHub Actions 自动构建和发布
  - Tag 推送自动创建 Release
  - 构建产物自动打包为 ZIP
- ✅ **版本管理优化**
  - 新增版本一致性检查脚本
  - 自动验证 package.json 和 manifest.json 版本同步
- 📝 **文档完善**
  - 新增自动化发布流程说明
  - 添加 CI 状态徽章
  - 完善贡献指南

### v1.0.0 (2025-11-06)
- ✨ 初始版本发布
- 🔍 支持 10 个搜索引擎（百度、谷歌、必应、DuckDuckGo、Brave、Yandex、Twitter/X、Reddit、GitHub、Stack Overflow）
- 💡 智能搜索语法生成和验证
- 📝 搜索历史管理
- 🌐 中英文界面支持
- 🎨 现代化UI设计

## 联系我们

- **项目主页**: https://github.com/lhly/search-syntax-pro
- **问题反馈**: https://github.com/lhly/search-syntax-pro/issues
- **邮箱**: lhlyzh@qq.com

---

> **SearchSyntax Pro（搜索语法大师）** - 让高级搜索变得简单易用