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

2025-11-14 15:50:34 +08:00
parent 7b955de2f0
commit d86c4b21ae
46 changed files with 8477 additions and 5800 deletions
@@ -0,0 +1,207 @@
+# 搜索 API 使用说明
+
+## 概述
+
+该 API 允许 AI 在指定平台上搜索内容，目前支持小黑盒平台。
+
+## API 接口
+
+### 搜索平台内容
+
+**IPC Channel:** `search-platform`
+
+**参数:**
+```typescript
+{
+  platform: string,  // 平台名称，如 'xiaoheihe'
+  query: string      // 搜索关键词
+}
+```
+
+**返回值:**
+```typescript
+{
+  success: boolean,
+  results?: Array<{
+    title: string,           // 文章标题
+    url: string,             // 文章链接
+    author?: string,         // 作者名称
+    publishTime?: string,    // 发布时间
+    summary?: string,        // 摘要
+    commentCount?: number,   // 评论数
+    likeCount?: number       // 点赞数
+  }>,
+  error?: string
+}
+```
+
+## 使用示例
+
+### 在 Vue 组件中使用
+
+```typescript
+// 在 Chat.vue 或其他组件中
+
+const searchXiaoheihe = async (query: string) => {
+  try {
+    const result = await window.electron.ipcRenderer.invoke('search-platform', {
+      platform: 'xiaoheihe',
+      query: query
+    })
+
+    if (result.success && result.results) {
+      console.log(`找到 ${result.results.length} 条结果:`)
+      result.results.forEach((item, index) => {
+        console.log(`${index + 1}. ${item.title}`)
+        console.log(`   链接: ${item.url}`)
+        console.log(`   作者: ${item.author || '未知'}`)
+        console.log(`   时间: ${item.publishTime || '未知'}`)
+        console.log(`   摘要: ${item.summary || '无'}`)
+        console.log(`   评论: ${item.commentCount || 0}, 点赞: ${item.likeCount || 0}`)
+        console.log('---')
+      })
+
+      return result.results
+    } else {
+      console.error('搜索失败:', result.error)
+      return []
+    }
+  } catch (error) {
+    console.error('搜索异常:', error)
+    return []
+  }
+}
+
+// 使用示例
+const results = await searchXiaoheihe('三角洲行动更新日志')
+```
+
+### AI Tool 集成示例
+
+如果你要将此功能集成到 AI 的 tool calling 中，可以这样定义：
+
+```json
+{
+  "name": "search_platform",
+  "description": "在指定平台搜索内容，获取相关文章列表",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "platform": {
+        "type": "string",
+        "enum": ["xiaoheihe"],
+        "description": "要搜索的平台名称，目前支持: xiaoheihe（小黑盒）"
+      },
+      "query": {
+        "type": "string",
+        "description": "搜索关键词，例如：'三角洲行动最新版本更新日志'"
+      }
+    },
+    "required": ["platform", "query"]
+  }
+}
+```
+
+### 获取搜索结果中文章的详细内容
+
+搜索返回的 `url` 可以配合现有的 `fetch-article` API 来获取完整文章内容：
+
+```typescript
+// 1. 先搜索
+const searchResult = await window.electron.ipcRenderer.invoke('search-platform', {
+  platform: 'xiaoheihe',
+  query: '三角洲行动更新'
+})
+
+// 2. 获取第一条结果的详细内容
+if (searchResult.success && searchResult.results && searchResult.results.length > 0) {
+  const firstResult = searchResult.results[0]
+
+  const articleDetail = await window.electron.ipcRenderer.invoke('fetch-article', firstResult.url)
+
+  if (articleDetail.success) {
+    console.log('文章标题:', articleDetail.title)
+    console.log('文章内容:', articleDetail.content)
+    console.log('评论列表:', articleDetail.comments)
+    console.log('统计数据:', articleDetail.stats)
+  }
+}
+```
+
+## 完整工作流程示例
+
+用户说："去小黑盒查询三角洲的最新版本更新日志"
+
+AI 的处理流程：
+
+```typescript
+async function handleUserRequest(userQuery: string) {
+  // 1. 解析用户意图
+  // 用户想要：在小黑盒搜索"三角洲最新版本更新日志"
+
+  // 2. 调用搜索 API
+  const searchResult = await window.electron.ipcRenderer.invoke('search-platform', {
+    platform: 'xiaoheihe',
+    query: '三角洲 更新日志'
+  })
+
+  if (!searchResult.success) {
+    return `搜索失败: ${searchResult.error}`
+  }
+
+  if (!searchResult.results || searchResult.results.length === 0) {
+    return '没有找到相关内容'
+  }
+
+  // 3. 筛选最相关的结果（可以根据标题、时间等判断）
+  const mostRelevant = searchResult.results[0] // 简单取第一条
+
+  // 4. 获取文章详细内容
+  const articleDetail = await window.electron.ipcRenderer.invoke('fetch-article', mostRelevant.url)
+
+  if (!articleDetail.success) {
+    return `获取文章详情失败: ${articleDetail.error}`
+  }
+
+  // 5. 提取更新日志相关内容并返回给用户
+  return `
+找到最新的更新日志：
+
+**${articleDetail.title}**
+
+发布时间: ${articleDetail.publishTime || '未知'}
+作者: ${articleDetail.author || '官方'}
+
+内容摘要：
+${articleDetail.content.substring(0, 500)}...
+
+完整链接: ${mostRelevant.url}
+
+互动数据：
+- 点赞: ${articleDetail.stats?.likes || 0}
+- 评论: ${articleDetail.stats?.commentCount || 0}
+- 收藏: ${articleDetail.stats?.favorites || 0}
+  `
+}
+```
+
+## 支持的平台
+
+- ✅ `xiaoheihe` - 小黑盒游戏社区
+
+## 注意事项
+
+1. 搜索功能会打开浏览器页面进行搜索，可能需要几秒钟
+2. 搜索结果的准确性取决于平台的搜索算法
+3. 如果需要登录才能搜索，请确保用户已经登录对应平台
+4. 返回的搜索结果数量取决于平台的搜索结果页面结构
+
+## 错误处理
+
+常见错误：
+
+- `搜索关键词不能为空` - query 参数为空
+- `不支持的平台` - platform 参数不在支持列表中
+- `未找到平台服务` - 平台服务未正确注册
+- `搜索失败` - 网络错误或页面结构变化
+- `未找到相关结果` - 搜索成功但没有结果