MoviePilot/tool_analysis_report.md

# 工具命名和功能混淆分析报告

## 一、潜在混淆点分析

### 1. 媒体相关工具（高风险混淆）

#### 1.1 `search_media` vs `recognize_media` vs `scrape_metadata`
**当前状态：**
- `search_media`: 在TMDB数据库中搜索媒体（按标题、年份等条件搜索）
- `recognize_media`: 从种子标题或文件路径识别媒体信息
- `scrape_metadata`: 为文件或目录刮削元数据（生成NFO文件等）

**混淆风险：** ⚠️ **中等**
- 三个工具都涉及"媒体"，但功能完全不同
- `search_media` 是数据库搜索，`recognize_media` 是信息识别，`scrape_metadata` 是文件操作
- 描述已区分，但命名可能让智能体混淆

**建议：**
- ✅ 描述已清晰区分，无需修改
- 可考虑在描述中更明确强调差异：
  - `search_media`: "Search for media in TMDB database by title/year/type"
  - `recognize_media`: "Extract/identify media info from torrent titles or file paths"
  - `scrape_metadata`: "Generate metadata files (NFO, posters) for existing media files"

### 2. 目录相关工具（高风险混淆）

#### 2.1 `query_directories` vs `list_directory`
**当前状态：**
- `query_directories`: 查询系统目录配置（配置信息，如下载目录、媒体库目录的设置）
- `list_directory`: 列出文件系统目录内容（实际文件和文件夹）

**混淆风险：** ⚠️⚠️ **高**
- 两个工具都涉及"目录"，但一个是配置查询，一个是文件列表
- 命名相似，容易混淆

**建议：**
- 考虑重命名 `query_directories` 为 `query_directory_config` 或 `query_directory_settings`
- 或者在描述中更明确：
  - `query_directories`: "Query directory **configuration settings** (download/library paths, storage types, etc.)"
  - `list_directory`: "List **actual files and folders** in a file system directory"

### 3. 媒体库查询工具（低风险）

#### 3.1 `query_media_library` vs `query_media_latest`
**当前状态：**
- `query_media_library`: 检查特定媒体是否存在于媒体库中
- `query_media_latest`: 查询媒体服务器最近入库的影片列表

**混淆风险：** ✅ **低**
- 命名清晰，功能区分明确
- 描述已明确说明差异

### 4. 订阅相关工具（低风险）

#### 4.1 `search_subscribe` vs `query_subscribes`
**当前状态：**
- `search_subscribe`: 搜索订阅的缺失剧集（执行搜索和下载操作）
- `query_subscribes`: 查询订阅状态和列表（只查询，不执行操作）

**混淆风险：** ✅ **低**
- `search` vs `query` 已明确区分操作类型
- 描述清晰

#### 4.2 多个订阅查询工具
- `query_subscribes`: 查询所有订阅
- `query_subscribe_history`: 查询订阅历史
- `query_subscribe_shares`: 查询共享订阅
- `query_popular_subscribes`: 查询热门订阅

**混淆风险：** ✅ **低**
- 命名清晰，通过后缀区分功能

### 5. 下载相关工具（低风险）

#### 5.1 `query_downloads` vs `query_downloaders`
**当前状态：**
- `query_downloads`: 查询下载任务状态
- `query_downloaders`: 查询下载器配置

**混淆风险：** ✅ **低**
- 命名清晰，单复数已区分

### 6. 调度器/工作流工具（低风险）

#### 6.1 `query_schedulers` vs `run_scheduler`
**当前状态：**
- `query_schedulers`: 查询调度器任务列表
- `run_scheduler`: 运行调度器任务

**混淆风险：** ✅ **低**
- `query` vs `run` 已明确区分

#### 6.2 `query_workflows` vs `run_workflow`
**当前状态：**
- `query_workflows`: 查询工作流列表
- `run_workflow`: 运行工作流

**混淆风险：** ✅ **低**
- `query` vs `run` 已明确区分

## 二、命名规范分析

### 命名模式总结：
1. **Search类** (`search_*`): 执行搜索操作
   - `search_media`, `search_person`, `search_torrents`, `search_subscribe`, `search_web`
   
2. **Query类** (`query_*`): 查询信息（只读）
   - `query_*`: 各种查询工具
   
3. **Add/Update/Delete类**: 执行操作
   - `add_*`, `update_*`, `delete_*`
   
4. **Run类**: 执行任务
   - `run_scheduler`, `run_workflow`

### 命名一致性：✅ 良好
- 命名模式统一，易于理解
- 动词选择恰当（search/query/add/update/delete/run）

## 三、建议优化

### 高优先级（建议修改）

1. **`query_directories` 重命名或增强描述**
   - 建议：在描述中明确强调是"配置查询"而非"文件列表"
   - 或考虑重命名为 `query_directory_config`

### 中优先级（可选优化）

1. **`search_media`、`recognize_media`、`scrape_metadata` 的描述增强**
   - 在描述开头明确说明数据源/操作类型
   - 例如：`search_media`: "Search TMDB database for media..."
   - 例如：`recognize_media`: "Extract media info from torrent titles or file paths..."
   - 例如：`scrape_metadata`: "Generate metadata files for existing media files..."

### 低优先级（当前已足够清晰）

- 其他工具命名和描述已足够清晰，无需修改

## 四、总结

**总体评价：** ✅ **良好**

大部分工具的命名和描述已经足够清晰，只有少数几个地方存在潜在的混淆风险：

1. **`query_directories` vs `list_directory`** - 需要更明确的区分
2. **媒体相关三个工具** - 描述可以更明确强调差异

建议优先处理 `query_directories` 的描述或命名，其他工具当前状态已足够清晰。