完善小黑盒搜索功能，将小黑盒操作作为工具给大模型

2025-11-14 15:50:34 +08:00
parent 7b955de2f0
commit d86c4b21ae
46 changed files with 8477 additions and 5800 deletions
@@ -0,0 +1,273 @@
+# 搜索功能登录策略设计
+
+## 问题背景
+
+小黑盒平台的搜索功能需要用户登录才能使用。我们需要设计一个用户体验友好的策略来处理这个限制。
+
+## 产品设计方案
+
+### 核心原则
+
+1. **用户体验优先** - 不让用户感到困惑或受阻
+2. **信息透明** - 清晰告知用户为什么需要登录
+3. **操作便捷** - 提供简单快速的登录路径
+4. **智能判断** - 避免不必要的提示和检查
+
+### 方案：渐进式提示 + 自动引导
+
+#### 1. 静默检查（不打扰用户）
+
+在执行搜索前，使用 `checkLoginStatusFast()` 快速检查登录状态：
+
+```typescript
+// 优点：
+// - 基于 cookie 检查，不需要加载页面
+// - 速度快（< 100ms）
+// - 用户无感知
+
+const loginStatus = await this.checkLoginStatusFast(context)
+```
+
+#### 2. 智能响应（根据登录状态）
+
+**场景 A: 已登录用户**
+- ✅ 直接执行搜索
+- ✅ 无任何提示
+- ✅ 正常返回搜索结果
+
+**场景 B: 未登录用户**
+- ⚠️ 返回特殊错误码 `NOT_LOGGED_IN`
+- 📝 AI 收到友好的错误信息
+- 🔑 提供登录引导
+
+#### 3. AI 友好的错误响应
+
+```json
+{
+  "success": false,
+  "error": "NOT_LOGGED_IN",
+  "message": "搜索小黑盒需要登录。请先登录小黑盒账号。",
+  "needLogin": true,
+  "platform": "xiaoheihe",
+  "loginGuide": "你可以通过以下方式登录：\n1. 点击设置按钮\n2. 扫描二维码登录小黑盒账号\n3. 登录成功后即可使用搜索功能"
+}
+```
+
+AI 会自动将这些信息转化成用户友好的回复。
+
+## 用户交互流程
+
+### 流程图
+
+```
+用户: "去小黑盒搜索三角洲行动"
+        ↓
+   检查登录状态
+        ↓
+   ┌────┴────┐
+   │         │
+已登录     未登录
+   │         │
+   ↓         ↓
+执行搜索   返回登录提示
+   │         │
+   ↓         ↓
+返回结果   AI 引导登录
+```
+
+### 实际对话示例
+
+#### 示例 1: 已登录用户
+
+```
+👤 用户: 去小黑盒搜索三角洲行动的更新日志
+
+🤖 AI: 🔧 正在调用工具: search_platform
+      ⚙️ 正在执行工具...
+      ✅ 工具执行完成
+
+      我为您找到了 12 条关于三角洲行动的更新日志：
+
+      1. 【官方】三角洲行动 v1.2.0 更新公告
+         发布时间: 2小时前
+         点赞: 2456, 评论: 891
+         ...
+```
+
+#### 示例 2: 未登录用户
+
+```
+👤 用户: 去小黑盒搜索三角洲行动的更新日志
+
+🤖 AI: 抱歉，搜索小黑盒需要先登录账号。
+
+      📱 登录方式：
+      1. 点击右上角的设置按钮 ⚙️
+      2. 扫描二维码登录小黑盒账号
+      3. 登录成功后，重新发送您的搜索请求即可
+
+      登录后我就可以帮您搜索相关内容了！
+```
+
+#### 示例 3: 用户登录后再次尝试
+
+```
+👤 用户: 好的，我已经登录了，再搜索一次
+
+🤖 AI: 🔧 正在调用工具: search_platform
+      ⚙️ 正在执行工具...
+      ✅ 工具执行完成
+
+      太好了！现在我为您找到了相关内容：
+      [搜索结果...]
+```
+
+## 技术实现
+
+### 1. 后端检查（xiaoheihe.ts）
+
+```typescript
+async search(context: BrowserContext, query: string) {
+  // 快速检查登录状态
+  const loginStatus = await this.checkLoginStatusFast(context)
+
+  if (!loginStatus.isLoggedIn) {
+    return {
+      success: false,
+      error: 'NOT_LOGGED_IN',
+      results: []
+    }
+  }
+
+  // 执行搜索...
+}
+```
+
+### 2. 工具执行器处理（tools.ts）
+
+```typescript
+private async searchPlatform(platform: string, query: string) {
+  const result = await window.electron.ipcRenderer.invoke('search-platform', {
+    platform,
+    query
+  })
+
+  if (result.error === 'NOT_LOGGED_IN') {
+    return {
+      success: false,
+      error: 'NOT_LOGGED_IN',
+      message: `搜索 ${platform} 需要登录。请先登录小黑盒账号。`,
+      needLogin: true,
+      loginGuide: '登录步骤...'
+    }
+  }
+
+  // 返回搜索结果...
+}
+```
+
+### 3. AI 自动处理
+
+AI 收到工具返回的错误信息后，会自然地向用户解释并引导登录。
+
+## 优势
+
+### ✅ 用户体验优势
+
+1. **无感知检查** - 登录状态检查速度快，用户无感知
+2. **清晰提示** - 未登录时，清楚告知原因和解决方法
+3. **简化流程** - 提供一键式的登录引导
+4. **智能对话** - AI 自然地引导用户完成登录
+
+### ✅ 技术优势
+
+1. **性能优化** - 使用 `checkLoginStatusFast()` 避免加载页面
+2. **错误分级** - 通过错误码区分不同类型的失败
+3. **可扩展性** - 可以轻松添加其他平台的登录检查
+4. **容错性强** - 即使检查失败，也能优雅降级
+
+### ✅ 产品优势
+
+1. **降低摩擦** - 用户第一次使用就能得到清晰的指引
+2. **提升转化** - 明确的登录引导提高登录率
+3. **用户留存** - 良好的体验提升用户满意度
+4. **减少困惑** - 避免用户不知道为什么功能无法使用
+
+## 未来优化方向
+
+### 1. 自动唤起登录（优先级：高）
+
+当检测到未登录时，可以自动弹出登录窗口：
+
+```typescript
+if (!loginStatus.isLoggedIn) {
+  // 自动打开登录窗口
+  window.electron.ipcRenderer.send('open-login-window', {
+    platform: 'xiaoheihe',
+    returnTo: 'search',
+    query: query
+  })
+}
+```
+
+### 2. 登录状态缓存（优先级：中）
+
+缓存登录状态 5 分钟，避免频繁检查：
+
+```typescript
+private loginStatusCache = new Map<string, {
+  status: boolean,
+  timestamp: number
+}>()
+
+async checkLoginWithCache(platform: string) {
+  const cached = this.loginStatusCache.get(platform)
+  if (cached && Date.now() - cached.timestamp < 5 * 60 * 1000) {
+    return cached.status
+  }
+  // 重新检查...
+}
+```
+
+### 3. 访客模式支持（优先级：低）
+
+如果平台支持，提供有限的访客搜索功能：
+
+```typescript
+if (!loginStatus.isLoggedIn) {
+  // 尝试访客模式搜索
+  const guestResult = await this.searchAsGuest(query)
+  if (guestResult.success) {
+    return {
+      ...guestResult,
+      isGuestMode: true,
+      message: '当前为访客模式，搜索结果可能有限'
+    }
+  }
+}
+```
+
+### 4. 多账号支持（优先级：低）
+
+支持用户同时登录多个账号：
+
+```typescript
+const accounts = await this.getLoggedInAccounts(platform)
+if (accounts.length > 1) {
+  // 让用户选择使用哪个账号搜索
+}
+```
+
+## 总结
+
+这个方案在**用户体验**、**技术实现**和**产品目标**之间取得了良好的平衡：
+
+- ✅ 不会让用户感到困惑
+- ✅ 不会阻断用户的操作流程
+- ✅ 提供了清晰的问题解决路径
+- ✅ 为未来的优化留下了空间
+
+用户会感受到：
+1. AI 很智能，知道需要登录
+2. 提示很清楚，知道如何登录
+3. 流程很顺畅，登录后立即可用