search-syntax-pro/docs/archived-specs/search-engine-adapters-expansion/requirements-confirm.md
Zain 4c52de98ad feat(search): 支持Yandex和DuckDuckGo搜索引擎
- 新增Yandex和DuckDuckGo搜索引擎适配器配置
- 更新manifest.json添加新搜索引擎权限
- 优化URL工具类支持更多搜索引擎参数解析
- 移除调试日志输出
- 修复百度搜索输入框选择器兼容性问题
- 添加文档归档和历史需求规范

版本升级至1.8.6
2025-12-02 16:28:56 +08:00

634 行
18 KiB
Markdown

# Requirements Confirmation - Search Engine Adapters Expansion
## ✅ Final Requirements (Quality Score: 92/100)
### 项目概述
为 SearchSyntax Pro Chrome 扩展添加 7 个新搜索引擎的适配器支持,确保所有高级语法与官方搜索引擎支持保持一致,并提供完整的国际化支持(中文+英文)。
---
## 1. 功能范围与优先级
### 实施范围 (基于用户回答 Q1.1=C, Q1.2=C)
#### ✅ 包含的搜索引擎(7个,分三阶段实施)
**Phase 1: 兼容性引擎** (基于现有语法模式)
1. **Yahoo Search** - 全球市场份额2-3%, Bing语法兼容
2. **Startpage** - 隐私友好, Google语法兼容
3. **Ecosia** - 环保搜索, Google/Bing混合语法
**Phase 2: 区域市场引擎** (需要独立适配)
4. **Naver** (네이버) - 韩国最大搜索引擎,市场份额60%+
5. **Sogou** (搜狗) - 中国第二大搜索引擎,市场份额约15%
6. **360搜索** (Haosou/好搜) - 中国市场份额10-15%
**Phase 3: 欧洲市场引擎**
7. **Qwant** - 法国隐私搜索引擎,基础语法支持
#### ❌ 排除的搜索引擎(2个)
- **Perplexity AI** - AI搜索引擎,暂不实施
- **You.com** - AI搜索引擎,暂不实施
### 实施策略说明
- 采用分批实施策略,降低风险并便于增量验证
- Phase 1 可复用现有适配器逻辑,快速实现
- Phase 2/3 需要独立研究和适配,预留充足时间
---
## 2. 搜索引擎语法支持矩阵 (基于官方文档研究)
### 研究方法 (基于用户回答 Q2.1=联网查询官方支持)
已通过网络搜索验证各搜索引擎的官方语法支持情况,确保实现与官方能力一致。
### 语法支持详情
| 搜索引擎 | 基础语法 | 多关键词支持 | 特殊语法 | 官方文档来源 |
|---------|---------|------------|---------|-----------|
| **Yahoo** | site:, filetype:, intitle:, inurl:, inbody: | ✅ 支持OR组合 | 与Bing相同 | Bing-compatible |
| **Startpage** | site:, filetype:, intitle:, "", before:, after: | ✅ 支持OR组合 | 与Google相似 | 官方Help Center |
| **Ecosia** | site:, filetype:, intitle:, inurl:, "" | ✅ 支持OR组合 | Google/Bing混合 | 官方FAQ |
| **Qwant** | site:, filetype:, "", 基础操作符 | ⚠️ 有限支持 | Qwick快捷方式 | 官方帮助页面 |
| **Naver** | site:, filetype:, "" | ⚠️ 有限支持 | 韩语优化搜索 | Naver API文档 |
| **Sogou** | site:, filetype:, intitle:, inurl: | ⚠️ 部分支持 | 中文分词优化 | 搜狗帮助中心 |
| **360搜索** | site:, filetype:, intitle: | ⚠️ 有限支持 | 中文优化 | 360帮助页面 |
### 具体语法支持细节
#### Yahoo Search (Bing-compatible)
```typescript
支持的语法:
- site: (单个和多个OR组合)
- filetype: (单个和多个OR组合)
- intitle:, allintitle:
- inurl:, inbody:
- "" (精确匹配)
- - (排除)
- OR (逻辑或)
不支持的语法:
- cache: (需要降级处理)
- related: (需要降级处理)
URL格式: https://search.yahoo.com/search?p={query}
```
#### Startpage (Google-compatible)
```typescript
支持的语法:
- site: (单个和多个OR组合)
- filetype: (单个和多个OR组合)
- intitle:
- "" (精确匹配)
- before:, after: (日期范围)
- OR (逻辑或)
- - (排除)
URL格式: https://www.startpage.com/sp/search?query={query}
```
#### Ecosia (Google/Bing hybrid)
```typescript
支持的语法:
- site: (官方文档确认支持)
- filetype: (官方文档确认支持)
- "" (精确匹配)
- OR (逻辑或)
- - (排除)
说明: 官方声明支持Google和Bing的搜索操作符
URL格式: https://www.ecosia.org/search?q={query}
```
#### Qwant (基础操作符)
```typescript
支持的语法:
- site: (基础支持)
- filetype: (基础支持)
- "" (精确匹配)
- Qwick快捷方式 (!w Wikipedia等)
说明: 语法支持相对有限,文档不够详细
URL格式: https://www.qwant.com/?q={query}
```
#### Naver (韩国市场)
```typescript
支持的语法:
- site: (有限支持)
- filetype: (支持pdf, doc, xls等)
- "" (精确匹配)
- 韩语分词和形态分析
特点: 针对韩语内容优化,语法文档以韩语为主
URL格式: https://search.naver.com/search.naver?query={query}
```
#### Sogou (中国市场)
```typescript
支持的语法:
- site: (官方帮助确认支持)
- filetype: (官方帮助确认支持,包括pdf, doc, xls, ppt等)
- intitle:, inurl: (基于官方帮助推断)
- "" (精确匹配)
特点: 中文分词优化,拼音搜索支持
URL格式: https://www.sogou.com/web?query={query}
```
#### 360搜索 (中国市场)
```typescript
支持的语法:
- site: (基础支持)
- filetype: (基础支持)
- intitle: (基础支持)
- "" (精确匹配)
特点: 中文优化,文档有限
URL格式: https://www.so.com/s?q={query}
```
---
## 3. 技术规格要求
### 3.1 语法降级策略 (基于用户回答 Q2.2=A)
**策略选择**: 选项A - 直接忽略并发出警告
```typescript
// 降级处理示例
degradeSyntax(params: SearchParams): SearchParams {
const degradedParams = { ...params }
const warnings: string[] = []
// 如果引擎不支持某语法,设为undefined并记录警告
if (!this.getSupportedSyntax().includes('cache') && params.cacheSite) {
degradedParams.cacheSite = undefined
warnings.push(
translate(language, 'adapter.validation.unsupported_syntax', {
syntax: 'cache:',
engine: this.getName()
})
)
}
if (warnings.length > 0) {
console.warn(`[${this.getName()}] 语法降级:`, warnings.join('; '))
}
return degradedParams
}
```
### 3.2 多关键词支持 (基于用户回答 Q2.3=联网确认官方支持)
**要求**: 确保所有多关键词功能与官方搜索引擎的支持程度保持一致
```typescript
// 仅当官方支持OR操作符时才实现多关键词组合
buildSearchQuery(params: SearchParams): string {
let query = params.keywords || ''
// 多域名支持 (仅当引擎支持OR时)
if (this.supportsOR()) {
const sites = params.sites?.filter(s => s.trim()) || []
if (sites.length > 0) {
const siteQuery = sites
.map(s => `site:${this.cleanSiteDomain(s.trim())}`)
.join(' OR ')
query += sites.length > 1 ? ` (${siteQuery})` : ` ${siteQuery}`
}
}
// 多文件类型支持 (仅当引擎支持OR时)
if (this.supportsOR()) {
const fileTypes = params.fileTypes?.filter(ft => ft.trim()) || []
if (fileTypes.length > 0) {
const ftQuery = fileTypes
.map(ft => `filetype:${ft.trim().toLowerCase()}`)
.join(' OR ')
query += fileTypes.length > 1 ? ` (${ftQuery})` : ` ${ftQuery}`
}
}
return query
}
```
### 3.3 适配器接口实现
所有新适配器必须实现 `SearchEngineAdapter` 接口:
```typescript
interface SearchEngineAdapter {
getName(): string // 引擎名称(中文)
getBaseUrl(): string // 基础URL
buildQuery(params: SearchParams): string // 构建搜索URL
getSupportedSyntax(): SyntaxType[] // 支持的语法列表
validateParams(params: SearchParams): Promise<ValidationResult>
degradeSyntax(params: SearchParams): SearchParams
getSearchSuggestions?(): string[] // 可选: 搜索建议
}
```
---
## 4. 国际化要求 (基于用户回答 Q3.1/Q3.2/Q3.3)
### 4.1 语言支持范围 (用户回答 Q3.2=仅中文与英文)
**明确要求**: 所有文本必须且仅支持项目本身存在的国际化语言配置:
- ✅ zh-CN (简体中文)
- ✅ en-US (英语)
- ❌ 不添加 ko-KR (韩语) - 即使是Naver引擎
- ❌ 不添加其他语言
### 4.2 翻译键命名规范
#### 引擎名称
```typescript
// src/i18n/translations.ts
export const translations = {
'zh-CN': {
common: {
searchEngines: {
yahoo: 'Yahoo搜索',
startpage: 'Startpage',
ecosia: 'Ecosia',
qwant: 'Qwant',
naver: 'Naver',
sogou: '搜狗',
so360: '360搜索'
}
}
},
'en-US': {
common: {
searchEngines: {
yahoo: 'Yahoo Search',
startpage: 'Startpage',
ecosia: 'Ecosia',
qwant: 'Qwant',
naver: 'Naver',
sogou: 'Sogou',
so360: '360 Search'
}
}
}
}
```
#### 验证消息
```typescript
// 新增验证消息翻译键
adapter: {
validation: {
unsupported_syntax: '{engine}不支持{syntax}语法,该参数将被忽略',
unsupported_multi_keyword: '{engine}不支持多关键词OR组合',
query_too_long: '查询长度超过{engine}的限制({max}字符)',
// ... 其他验证消息
}
}
```
#### 搜索建议国际化 (基于用户回答 Q3.3)
```typescript
// getSearchSuggestions() 返回的提示需要国际化
async getSearchSuggestions(): Promise<string[]> {
const language = await getCurrentLanguage()
return [
translate(language, 'adapter.suggestions.site_search'),
translate(language, 'adapter.suggestions.filetype_search'),
translate(language, 'adapter.suggestions.exact_match')
]
}
```
### 4.3 国际化实施清单
- [ ] 添加7个新引擎的名称翻译 (zh-CN + en-US)
- [ ] 添加引擎特定的验证错误消息
- [ ] 添加语法降级警告消息
- [ ] 添加搜索建议提示文本
- [ ] 更新 `common.searchEngines` 类别
- [ ] 确保所有用户可见文本都通过 `translate()` 函数
---
## 5. 测试要求 (基于用户回答 Q4.1=B, Q4.2=B)
### 5.1 参数验证策略 (选项B: 宽松验证)
```typescript
// 仅警告,允许搜索继续
async validateParams(params: SearchParams): Promise<ValidationResult> {
const warnings: string[] = []
const language = await getCurrentLanguage()
// 检查不支持的语法,但仅警告不阻止
if (params.cacheSite && !this.getSupportedSyntax().includes('cache')) {
warnings.push(
translate(language, 'adapter.validation.unsupported_syntax', {
syntax: 'cache:',
engine: this.getName()
})
)
}
return {
isValid: true, // 始终返回true,不阻止搜索
warnings: warnings.length > 0 ? warnings : undefined
}
}
```
### 5.2 测试覆盖范围 (选项B: 仅核心逻辑需要测试)
**必须测试的核心逻辑**:
```typescript
describe('YahooAdapter', () => {
// ✅ 必须: URL构建测试
it('should build correct search URL', () => {
const adapter = new YahooAdapter()
const url = adapter.buildQuery({ keywords: 'test' })
expect(url).toContain('search.yahoo.com')
})
// ✅ 必须: 多关键词组合测试 (如果支持)
it('should combine multiple sites with OR', () => {
const url = adapter.buildQuery({
keywords: 'test',
sites: ['example.com', 'test.com']
})
expect(url).toContain('site:example.com OR site:test.com')
})
// ✅ 必须: 语法降级测试
it('should degrade unsupported syntax', () => {
const degraded = adapter.degradeSyntax({
keywords: 'test',
cacheSite: 'example.com' // Yahoo不支持cache:
})
expect(degraded.cacheSite).toBeUndefined()
})
// ❌ 不需要: UI集成测试
// ❌ 不需要: E2E测试
// ❌ 不需要: 性能测试
})
```
**测试文件结构**:
```
src/services/adapters/
├── yahoo.test.ts ✅ 核心逻辑测试
├── startpage.test.ts ✅ 核心逻辑测试
├── ecosia.test.ts ✅ 核心逻辑测试
├── qwant.test.ts ✅ 核心逻辑测试
├── naver.test.ts ✅ 核心逻辑测试
├── sogou.test.ts ✅ 核心逻辑测试
└── so360.test.ts ✅ 核心逻辑测试
```
---
## 6. UI/UX决策
### 6.1 引擎显示顺序 (保持现有实现)
基于现有代码分析,引擎顺序由 `factory.ts` 中的注册顺序决定,无需特殊处理。
### 6.2 引擎选择器UI (保持现有实现)
使用现有下拉选择器,无需修改UI组件。
---
## 7. 边界情况处理
### 7.1 引擎不可用处理 (保守策略)
```typescript
// 如果URL格式变化,记录错误但允许继续
buildQuery(params: SearchParams): string {
try {
const baseUrl = this.getBaseUrl()
const query = this.buildSearchQuery(params)
return `${baseUrl}?q=${encodeURIComponent(query)}`
} catch (error) {
console.error(`[${this.getName()}] URL构建失败:`, error)
// 返回基础URL,允许用户尝试
return `${this.getBaseUrl()}?q=${encodeURIComponent(params.keywords || '')}`
}
}
```
### 7.2 查询长度限制 (统一保守策略)
```typescript
// 所有引擎统一使用180字符限制(最保守)
const MAX_QUERY_LENGTH = 180
async validateParams(params: SearchParams): Promise<ValidationResult> {
const warnings: string[] = []
const language = await getCurrentLanguage()
const fullQuery = this.buildSearchQuery(params)
if (fullQuery.length > MAX_QUERY_LENGTH) {
warnings.push(
translate(language, 'adapter.validation.query_too_long', {
engine: this.getName(),
max: MAX_QUERY_LENGTH.toString()
})
)
}
return { isValid: true, warnings: warnings.length > 0 ? warnings : undefined }
}
```
---
## 8. 实施计划
### Phase 1: 兼容性引擎 (预计2-3小时)
```yaml
Yahoo:
- 复用 BingAdapter 逻辑
- 修改 baseUrl 和引擎名称
- 添加翻译键
- 编写核心测试
Startpage:
- 复用 GoogleAdapter 逻辑
- 修改 baseUrl
- 验证语法兼容性
- 添加翻译和测试
Ecosia:
- 混合 Google/Bing 语法
- 实现基础操作符
- 添加翻译和测试
```
### Phase 2: 区域市场引擎 (预计3-4小时)
```yaml
Naver:
- 独立实现韩国市场特性
- 仅提供中英文翻译
- 实现基础语法支持
- 测试韩语查询处理
Sogou:
- 参考 Baidu 实现
- 实现中文分词优化
- 支持官方确认的语法
- 添加翻译和测试
360搜索:
- 参考 Sogou/Baidu
- 实现基础语法
- 中文优化
- 添加翻译和测试
```
### Phase 3: 欧洲市场引擎 (预计1-2小时)
```yaml
Qwant:
- 实现基础操作符
- 支持 Qwick 快捷方式(可选)
- 添加翻译和测试
```
### 集成和验收 (预计1小时)
```yaml
- 在 factory.ts 注册所有新适配器
- 手动测试每个引擎的搜索功能
- 验证国际化完整性
- 测试语法降级警告
- 更新 README.md
```
**总预计时间**: 7-10小时
---
## 9. 验收标准
### 功能验收
- [ ] 7个新搜索引擎全部实现并注册
- [ ] 所有引擎的语法支持与官方能力一致
- [ ] 多关键词OR组合仅在官方支持时启用
- [ ] 语法降级正确处理,发出适当警告
- [ ] 所有核心逻辑都有单元测试
### 国际化验收
- [ ] 所有引擎名称有中英文翻译
- [ ] 所有验证消息有中英文翻译
- [ ] 所有搜索建议有中英文翻译
- [ ] 切换语言时所有文本正确显示
- [ ] 不包含中英文以外的语言
### 代码质量验收
- [ ] 遵循现有适配器模式
- [ ] TypeScript类型安全
- [ ] 无ESLint错误
- [ ] 代码风格与现有代码一致
- [ ] 充分的代码注释(中文)
### 用户体验验收
- [ ] 手动测试每个引擎可正常搜索
- [ ] 不支持的语法显示警告但不阻止搜索
- [ ] 查询过长时显示警告
- [ ] 引擎选择器包含所有新引擎
---
## 10. 风险与缓解
### 风险识别
1. **官方语法文档不完整**: 中文搜索引擎(Sogou, 360)的英文文档有限
- **缓解**: 基于中文官方帮助页面和实际测试验证
2. **URL格式可能变化**: 搜索引擎可能更新URL结构
- **缓解**: 使用保守的错误处理,允许搜索继续
3. **多关键词支持不确定**: 部分引擎的OR支持未明确文档
- **缓解**: 通过实际测试验证,不确定时禁用
### 假设和依赖
- 假设: 搜索引擎URL格式在可预见的未来保持稳定
- 假设: 官方文档和帮助页面的信息准确
- 依赖: 现有 `SearchEngineAdapter` 接口和工厂模式不变
---
## 11. 质量评分明细 (92/100)
### 功能清晰度 (28/30) ⬆️+13
- ✅ 明确了7个待添加的搜索引擎
- ✅ 明确了排除2个AI引擎
- ✅ 提供了每个引擎的语法支持矩阵
- ✅ 确认了多关键词支持策略(基于官方支持)
- ⚠️ 部分中文引擎的语法文档仍需实际测试验证
### 技术具体性 (23/25) ⬆️+13
- ✅ 完整的语法降级策略(选项A)
- ✅ 详细的URL格式和参数定义
- ✅ 多关键词实现模式(基于OR支持)
- ✅ 代码示例覆盖所有关键场景
- ⚠️ 部分引擎的特殊处理细节需要实施时确认
### 实现完整性 (22/25) ⬆️+12
- ✅ 完整的国际化方案(zh-CN + en-US)
- ✅ 明确的测试策略(核心逻辑测试)
- ✅ 边界情况处理(查询长度,URL失败)
- ✅ 分阶段实施计划
- ⚠️ 实际实施时可能发现额外边界情况
### 业务上下文 (19/20) ⬆️+9
- ✅ 清晰的验收标准
- ✅ 风险识别和缓解措施
- ✅ 预估工作量和时间
- ✅ 用户价值明确(扩展引擎支持)
- ✅ 优先级和阶段划分合理
---
## 12. 后续步骤
1. ✅ **需求确认完成** - 质量评分92/100
2. ⏸️ **等待用户批准** - 需要用户明确同意后才进入实施阶段
3. ⏳ **Phase 1 实施** - Yahoo, Startpage, Ecosia
4. ⏳ **Phase 2 实施** - Naver, Sogou, 360搜索
5. ⏳ **Phase 3 实施** - Qwant
6. ⏳ **集成测试和验收**
---
## 附录: 研究来源
### 官方文档和帮助页面
- Yahoo: Bing语法兼容性参考
- Startpage: 官方Help Center确认Google/Bing操作符支持
- Ecosia: 官方FAQ确认Google和Bing搜索操作符支持
- Qwant: 官方帮助页面提及基础操作符和Qwick快捷方式
- Naver: Naver Search API文档和帮助中心
- Sogou: 搜狗帮助中心确认filetype等语法支持
- 360搜索: 360帮助页面基础语法说明
### 技术参考
- 现有适配器实现: Google, Bing, Baidu等10个引擎
- SearchEngineAdapter接口定义
- 多关键词OR组合模式(已在Google/Bing中验证)
- i18n翻译系统和translate()函数
---
**文档版本**: 2.0 (最终版)
**最后更新**: 2025-11-26
**状态**: ✅ 需求确认完成,等待用户批准