# Cursor自动任务执行触发器 - 使用指南

## 📋 概述

`trigger_cursor_execution.py` 已优化为支持**定期自动执行**模式，可以自动检测并触发Cursor执行任务。

## 🚀 主要功能

### 1. 定期自动检查
- 每5分钟（可配置）自动检查一次processing任务
- 自动生成任务执行指令文件（`.cursor/task_execute_instructions.md`）
- Cursor会自动检测文件变化并执行任务

### 2. 任务指令文件
- 自动生成Markdown格式的任务执行指令
- 包含完整的任务描述和执行步骤
- Cursor可以直接读取并自动执行

### 3. 多种执行模式
- **单次执行**：手动触发，执行一次检查
- **定期执行**：持续监控，自动触发Cursor执行

---

## 📖 使用方法

### 方式1：单次执行（推荐调试）

```bash
python scripts/trigger_cursor_execution.py --once
```

**效果**：
- 立即检查一次processing任务
- 生成或更新 `task_execute_instructions.md` 文件
- 输出任务信息到控制台

---

### 方式2：定期执行（推荐生产环境）

#### 前台运行（可以看到实时输出）
```bash
python scripts/trigger_cursor_execution.py --interval 300
```

#### 后台运行（无窗口）
```bash
# Windows
scripts\start_cursor_task_trigger_background.bat

# Linux/Mac
nohup python scripts/trigger_cursor_execution.py --interval 300 > logs/cursor_task_trigger.log 2>&1 &
```

#### 自定义检查间隔
```bash
# 每10分钟检查一次
python scripts/trigger_cursor_execution.py --interval 600

# 每1分钟检查一次（测试用）
python scripts/trigger_cursor_execution.py --interval 60
```

---

### 方式3：在Cursor中直接触发

在Cursor Chat中输入：
```
请检查并执行所有待处理任务
```

Cursor会：
1. 自动读取 `task_execute_instructions.md` 文件
2. 根据指令执行任务
3. 完成后更新任务状态

---

## 🔄 工作流程

```
1. 脚本定期检查 .cursor/pending_tasks.json
   ↓
2. 发现processing状态的任务
   ↓
3. 生成/更新 .cursor/task_execute_instructions.md
   ↓
4. 输出任务信息到控制台
   ↓
5. Cursor检测到文件变化（或用户触发）
   ↓
6. Cursor读取任务指令文件
   ↓
7. Cursor自动执行任务：
   - 打开任务文件
   - 实现功能
   - 更新任务状态为completed
   ↓
8. 任务完成！✅
```

---

## 📁 相关文件

### 任务指令文件
- **位置**：`.cursor/task_execute_instructions.md`
- **格式**：Markdown
- **内容**：任务描述、执行步骤、MCP工具调用示例
- **更新**：脚本会自动更新此文件

### 任务通知文件
- **位置**：`.cursor/pending_tasks.json`
- **格式**：JSON
- **内容**：待处理任务的详细信息

### Cursor规则文件
- **位置**：`.cursor/rules/auto_task_execution.mdc`
- **内容**：Cursor自动执行规则和说明

---

## ⚙️ 配置说明

### 检查间隔

默认：300秒（5分钟）

修改方式：
```bash
# 命令行参数
python scripts/trigger_cursor_execution.py --interval 600

# 或编辑批处理文件中的参数
```

### 日志文件

**后台运行模式**：
- 位置：`logs/cursor_task_trigger.log`
- 格式：标准日志格式
- 包含：任务检查、文件生成、错误信息

---

## 💡 使用场景

### 场景1：开发调试
```bash
# 手动触发，查看任务
python scripts/trigger_cursor_execution.py --once
```

### 场景2：生产环境
```bash
# 后台持续运行
scripts\start_cursor_task_trigger_background.bat
```

### 场景3：快速测试
```bash
# 1分钟检查一次（快速响应）
python scripts/trigger_cursor_execution.py --interval 60
```

---

## 🎯 Cursor自动执行机制

### 自动检测
Cursor会：
1. **文件监控**：监控 `.cursor/task_execute_instructions.md` 文件变化
2. **定期检查**：根据 `.cursor/rules/auto_task_execution.mdc` 规则定期检查
3. **触发执行**：发现新任务时自动执行

### 手动触发
在Cursor Chat中说：
```
请检查并执行所有待处理任务
```

### 执行步骤
Cursor会自动：
1. 读取任务指令文件
2. 打开任务文件
3. 分析任务需求
4. 实现功能代码
5. 调用MCP工具更新状态

---

## 📊 执行效果

### 脚本输出示例

```
================================================================================
🤖 [CURSOR-AUTO-EXECUTE] 发现 1 个待执行任务
================================================================================

🤖 [CURSOR-EXECUTE-TASK]
任务ID: 9
任务名称: 导入科室对照表
任务文件: app/core/data_flow/导入科室对照表.py

任务描述:
# Task: 导入科室对照表
...

执行指令:
1. 打开任务文件: app/core/data_flow/导入科室对照表.py
2. 根据任务描述实现功能
3. 调用MCP工具更新状态:
   工具: update_task_status
   参数: {
     "task_id": 9,
     "code_name": "导入科室对照表.py",
     "code_path": "app/core/data_flow",
     "status": "completed"
   }

🔚 [END-CURSOR-EXECUTE-TASK]

💡 提示：任务执行指令已保存到 .cursor/task_execute_instructions.md
💡 Cursor可以自动读取此文件并执行任务
```

---

## 🔍 故障排查

### 问题1：Cursor没有自动执行任务

**检查**：
1. 任务指令文件是否存在：`.cursor/task_execute_instructions.md`
2. 文件是否最近更新（5分钟内）
3. 任务状态是否为 `processing`

**解决**：
```bash
# 手动触发
python scripts/trigger_cursor_execution.py --once

# 在Cursor中手动执行
请检查并执行所有待处理任务
```

### 问题2：任务指令文件未生成

**检查**：
1. `pending_tasks.json` 文件是否存在
2. 是否有processing状态的任务
3. 脚本是否有权限写入 `.cursor` 目录

**解决**：
```bash
# 检查任务文件
cat .cursor/pending_tasks.json

# 手动运行脚本查看错误
python scripts/trigger_cursor_execution.py --once
```

### 问题3：定期执行脚本停止工作

**检查**：
1. 进程是否还在运行
2. 日志文件中是否有错误信息
3. 数据库连接是否正常

**解决**：
```bash
# 查看进程
Get-Process python | Where-Object {$_.CommandLine -like "*trigger_cursor*"}

# 查看日志
tail -f logs/cursor_task_trigger.log

# 重启服务
scripts\start_cursor_task_trigger_background.bat
```

---

## 📚 相关文档

- **自动执行脚本**：`docs/CURSOR_AUTO_TASK_EXECUTION.md`
- **快速开始**：`docs/TASK_EXECUTION_QUICK_START.md`
- **修复总结**：`docs/AUTO_TASK_EXECUTION_FIX.md`

---

## ✅ 优化总结

### 新增功能

1. ✅ **定期执行模式**：支持持续监控和自动触发
2. ✅ **任务指令文件**：自动生成Markdown格式的执行指令
3. ✅ **Cursor规则**：创建自动执行规则文件
4. ✅ **启动脚本**：Windows批处理文件，方便启动服务
5. ✅ **日志记录**：完整的日志输出和文件记录

### 工作流程优化

- **之前**：需要手动运行脚本，Cursor才能看到任务
- **现在**：脚本自动定期检查，自动生成指令文件，Cursor自动检测并执行

---

**最后更新**：2025-11-29