# AI Tool Calling 使用指南

## 概述

AI Desktop 现已支持完整的 Tool Calling（函数调用）功能！AI 可以自动调用工具来完成复杂任务，如搜索平台内容、获取文章详情等。

## 🎯 支持的工具

### 1. `search_platform` - 搜索平台内容

在指定平台搜索内容，获取相关文章列表。

**参数：**
- `platform` (string, 必需): 平台名称，目前支持 `xiaoheihe`（小黑盒）
- `query` (string, 必需): 搜索关键词

**返回：**
- `success` (boolean): 是否成功
- `count` (number): 结果数量
- `results` (array): 搜索结果列表
  - `title`: 文章标题
  - `url`: 文章链接
  - `author`: 作者名称
  - `publishTime`: 发布时间
  - `summary`: 摘要
  - `commentCount`: 评论数
  - `likeCount`: 点赞数

**示例：**
```
用户: 去小黑盒查询三角洲行动的最新更新日志

AI 会自动调用:
{
  "platform": "xiaoheihe",
  "query": "三角洲行动 更新日志"
}
```

### 2. `fetch_article` - 获取文章详情

获取指定 URL 的文章详细内容。

**参数：**
- `url` (string, 必需): 文章的完整 URL 地址

**返回：**
- `success` (boolean): 是否成功
- `article` (object): 文章详情
  - `title`: 标题
  - `author`: 作者
  - `publishTime`: 发布时间
  - `content`: 正文内容
  - `tags`: 标签列表
  - `stats`: 统计数据（点赞、收藏、评论数等）
  - `topComments`: 前5条评论

**示例：**
```
用户: 帮我看看这篇文章的详细内容

AI 会自动调用:
{
  "url": "https://www.xiaoheihe.cn/article/123456"
}
```

## 🚀 使用方式

### 方式一：自然语言对话（推荐）

直接用自然语言告诉 AI 你想做什么，AI 会自动判断是否需要调用工具。

**示例对话：**

```
👤 用户: 去小黑盒搜索一下黑神话悟空的最新攻略

🤖 AI: 🔧 正在调用工具: search_platform
      ⚙️ 正在执行工具...
      ✅ 工具执行完成

      我为您找到了 15 条关于黑神话悟空的最新攻略：

      1. 【黑神话悟空】全Boss打法攻略合集
         作者: 游戏大神
         发布时间: 2小时前
         点赞: 1234, 评论: 567

      2. 黑神话悟空隐藏关卡完全指南
         ...
```

```
👤 用户: 帮我看看第一篇文章的详细内容

🤖 AI: 🔧 正在调用工具: fetch_article
      ⚙️ 正在执行工具...
      ✅ 工具执行完成

      这篇文章详细介绍了黑神话悟空中所有Boss的打法策略：

      【文章标题】全Boss打法攻略合集
      【作者】游戏大神
      【发布时间】2小时前

      【正文内容】
      第一章：黑风山
      1. 黑熊精：
         - 阶段一：...
         - 阶段二：...
      ...
```

### 方式二：连续对话

AI 可以在一次对话中自动调用多个工具。

```
👤 用户: 去小黑盒查询三角洲行动的最新版本更新日志，然后告诉我主要更新了什么

🤖 AI:
      🔧 正在调用工具: search_platform
      ⚙️ 正在执行工具...
      🔧 正在调用工具: fetch_article
      ⚙️ 正在执行工具...
      ✅ 工具执行完成

      根据最新的更新日志，三角洲行动 v1.2.0 主要更新内容包括：

      1. 新增武器系统
         - 新增 5 把新武器
         - 优化武器平衡性

      2. 地图更新
         - 新地图「城市废墟」
         - 优化现有地图性能

      3. Bug修复
         - 修复了 23 个已知问题
         - 优化了网络延迟

      完整更新日志链接：https://...
```

## 💡 支持的使用场景

### 1. 搜索游戏资讯
```
- "去小黑盒搜索原神最新活动"
- "查询王者荣耀新赛季更新"
- "搜索黑神话悟空的评测"
```

### 2. 获取详细攻略
```
- "帮我看看这篇攻略的详细内容"
- "获取这个链接的文章内容"
- "这篇文章都说了什么？"
```

### 3. 综合查询
```
- "去小黑盒搜索三角洲行动的更新，然后总结主要内容"
- "查询最新的游戏新闻，帮我挑出最重要的3条"
- "搜索某某游戏的评价，告诉我玩家都在说什么"
```

## 🔧 技术实现

### 架构说明

1. **工具定义** (`tools.ts`)
   - 定义所有可用工具的接口和参数
   - 实现工具执行器 `ToolExecutor`

2. **AI 服务** (`aiService.ts`)
   - `chatWithTools`: 支持 tool calling 的聊天函数
   - `executeToolCalls`: 执行工具调用并返回结果
   - 支持流式响应和工具调用通知

3. **界面集成** (`Chat.vue`)
   - 自动检测 AI 的工具调用
   - 执行工具并显示进度提示
   - 将工具结果返回给 AI 生成最终回复

### 工作流程

```
用户输入
   ↓
发送给 AI (携带工具定义)
   ↓
AI 分析是否需要调用工具
   ↓
如果需要: 返回 tool_calls
   ↓
执行工具调用 (search_platform / fetch_article)
   ↓
将工具结果添加到对话历史
   ↓
再次发送给 AI
   ↓
AI 基于工具结果生成最终回复
   ↓
显示给用户
```

## 📝 添加新工具

如果你想添加新的工具，按照以下步骤：

### 1. 在 `tools.ts` 中定义工具

```typescript
export const availableTools: ToolDefinition[] = [
  // ... 现有工具
  {
    type: 'function',
    function: {
      name: 'your_tool_name',
      description: '工具的详细描述，AI 会根据这个描述判断何时使用',
      parameters: {
        type: 'object',
        properties: {
          param1: {
            type: 'string',
            description: '参数1的描述'
          },
          param2: {
            type: 'number',
            description: '参数2的描述'
          }
        },
        required: ['param1']
      }
    }
  }
]
```

### 2. 在 `ToolExecutor` 中实现工具

```typescript
async execute(toolCall: ToolCall): Promise<ToolResult> {
  // ... 现有代码
  switch (name) {
    case 'your_tool_name':
      result = await this.yourToolFunction(args.param1, args.param2)
      break
    // ...
  }
}

private async yourToolFunction(param1: string, param2: number): Promise<any> {
  // 实现工具逻辑
  // 可以调用 IPC、API 或执行其他操作
  return { success: true, data: ... }
}
```

### 3. 如果需要新的 IPC 接口

在主进程 (`main/index.ts`) 中添加：

```typescript
ipcMain.handle('your-ipc-channel', async (_, args) => {
  // 实现功能
  return { success: true, ... }
})
```

## ⚠️ 注意事项

1. **API 兼容性**
   - 确保使用的 AI 模型支持 Function Calling
   - OpenAI GPT-4, GPT-3.5-turbo 1106+ 支持
   - DeepSeek Chat 支持

2. **工具执行时间**
   - 搜索和抓取可能需要几秒钟
   - 界面会显示进度提示

3. **错误处理**
   - 工具执行失败时会显示错误提示
   - AI 会尝试基于错误信息给出建议

4. **对话历史**
   - 工具调用和结果不会显示在对话界面
   - 只显示用户消息和 AI 的最终回复

## 🎉 开始使用

1. 确保已在设置中配置 AI 模型（推荐使用支持 Function Calling 的模型）
2. 打开对话窗口
3. 用自然语言告诉 AI 你想做什么
4. AI 会自动判断并调用相应的工具
5. 查看执行进度提示和最终结果

就这么简单！🚀