# 异步任务使用说明

## 问题背景

`separate_series_by_patient` 函数执行时间很长（处理大量DICOM文件），导致MCP工具调用超时。

## 解决方案

采用**后台任务模式**：
1. 调用工具时立即返回任务ID，不等待任务完成
2. 任务在后台线程池中执行
3. 提供单独的工具查询任务状态和结果

## 使用方法

### 1. 启动文件拆分任务（异步模式）

调用 `fileforsep` 工具，默认 `async_mode=true`：

```json
{
  "fileforsep": "C:/path/to/dicom/directory",
  "async_mode": true
}
```

**返回结果：**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "message": "任务已在后台启动，请使用 get_separate_task_status 工具查询进度",
  "directory_path": "C:/path/to/dicom/directory",
  "async_mode": true
}
```

### 2. 查询任务状态

使用返回的 `task_id` 和 `directory_path` 调用 `get_separate_task_status` 工具：

```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "directory_path": "C:/path/to/dicom/directory"
}
```

**返回结果（任务进行中）：**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress": 0.0,
  "message": "任务已启动...",
  "updated_at": 1234567890.123
}
```

**返回结果（任务完成）：**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "progress": 1.0,
  "message": "任务完成",
  "updated_at": 1234567890.123,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{...拆分结果JSON...}"
      }
    ]
  }
}
```

**返回结果（任务失败）：**
```json
{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "failed",
  "progress": 0.0,
  "message": "任务失败",
  "error": "错误详细信息...",
  "updated_at": 1234567890.123
}
```

### 3. 同步模式（不推荐）

如果需要同步执行（可能超时），可以设置 `async_mode=false`：

```json
{
  "fileforsep": "C:/path/to/dicom/directory",
  "async_mode": false
}
```

## 技术实现

### 文件结构

1. **`src/function/task_manager.py`** - 任务管理器
   - 管理后台任务执行
   - 任务状态存储（`~/.dicom_tasks/`）
   - 线程池执行长时间任务

2. **`setup.py`** - 工具函数包装
   - `separate_series_by_patient_tool` - 支持异步/同步模式
   - `get_separate_task_status_tool` - 查询任务状态

3. **`main.py`** - MCP服务器
   - 注册两个工具：`fileforsep` 和 `get_separate_task_status`
   - 处理工具调用请求

### 任务状态存储

任务状态文件保存在：`{directory_path}/task_{task_id}.json`

例如，如果 `directory_path` 是 `C:/path/to/dicom/directory`，任务ID是 `550e8400-e29b-41d4-a716-446655440000`，则状态文件路径为：
`C:/path/to/dicom/directory/task_550e8400-e29b-41d4-a716-446655440000.json`

每个任务文件包含：
- `task_id`: 任务ID
- `status`: 状态（"running", "completed", "failed"）
- `progress`: 进度（0.0 - 1.0）
- `message`: 状态消息
- `updated_at`: 更新时间戳
- `result`: 任务结果（完成时）
- `error`: 错误信息（失败时）

## 优势

1. **避免超时**：立即返回任务ID，不等待任务完成
2. **可查询进度**：随时查询任务状态
3. **后台执行**：不阻塞MCP服务器
4. **状态持久化**：任务状态保存在文件中，服务器重启后仍可查询
5. **向后兼容**：支持同步模式（`async_mode=false`）

## 注意事项

1. 任务状态文件会保存在 `fileforsep` 参数指定的目录中，与处理的文件在同一位置
2. 建议定期清理已完成的任务文件（`task_*.json`）
3. 线程池最大工作线程数为2，避免资源过度占用
4. 如果任务执行失败，错误信息会保存在状态文件中
5. 查询任务状态时，必须提供与启动任务时相同的 `directory_path`

