# 自动任务执行脚本 - 使用说明 v2.0

## 🚀 快速开始

### 推荐方式：使用启动器

双击运行启动器脚本，根据菜单选择运行模式：

```cmd
scripts\start_task_scheduler.bat
```

### 最推荐的运行模式

**Agent 循环模式** - 全自动化，无需人工干预：

```cmd
python scripts\auto_execute_tasks.py --chat-loop --use-agent
```

**功能特点：**
- ✅ 自动检测 pending 任务
- ✅ 自动启动 Cursor Agent
- ✅ 自动执行任务
- ✅ 自动关闭 Agent
- ✅ 自动部署到生产服务器
- ✅ 自动同步数据库状态

---

## 📋 启动器菜单说明

### 【基础模式】

| 选项 | 模式 | 说明 | 适用场景 |
|------|------|------|----------|
| 1 | 前台运行 | 实时查看日志，Ctrl+C 停止 | 调试、监控 |
| 2 | 后台运行 | 日志写入文件，无窗口 | 生产环境 |
| 3 | 单次执行 | 执行一次后退出 | 手动触发 |

### 【Agent 自动化模式】(推荐)

| 选项 | 模式 | 说明 | 适用场景 |
|------|------|------|----------|
| 4 | Agent 循环模式 | 全自动：检测→启动→执行→部署→关闭 | **生产环境首选** |
| 5 | Agent 单次执行 | 执行一次任务后退出 | 测试、验证 |
| 6 | Agent 循环 + 禁用部署 | 只执行任务，不部署到生产 | 开发环境 |

### 【传统 Chat 模式】

| 选项 | 模式 | 说明 | 适用场景 |
|------|------|------|----------|
| 7 | Chat 循环模式 | 定期发送 Chat 消息提醒 | 需要人工确认 |
| 8 | 立即发送 Chat | 立即发送一次消息 | 手动触发 |

### 【部署功能】

| 选项 | 功能 | 说明 |
|------|------|------|
| 9 | 测试连接 | 测试到生产服务器的 SSH 连接 |
| 10 | 立即部署 | 部署指定任务 ID 的脚本 |

### 【管理功能】

| 选项 | 功能 | 说明 |
|------|------|------|
| 11 | 查看状态 | 查看进程、日志、任务状态 |
| 12 | 停止服务 | 停止后台运行的服务 |

---

## 💻 命令行方式

### 基础用法

```cmd
cd G:\code-lab\DataOps-platform-new
python scripts\auto_execute_tasks.py [选项]
```

### 完整参数列表

#### 基础参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--once` | 只执行一次检查，不循环 | - |
| `--interval N` | 设置检查间隔（秒） | 300 |

#### Chat 相关参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--enable-chat` | 启用自动 Cursor Chat | 禁用 |
| `--chat-input-pos "x,y"` | 指定 Chat 输入框位置 | - |
| `--chat-message "消息"` | 自定义 Chat 消息内容 | 默认消息 |
| `--chat-loop` | 启动 Chat 自动触发循环 | - |
| `--chat-interval N` | Chat 循环检查间隔（秒） | 60 |
| `--send-chat-now` | 立即发送一次 Chat 消息 | - |

#### Agent 模式参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--use-agent` | 使用 Agent 模式 | **启用** |
| `--no-agent` | 禁用 Agent，使用传统 Chat | - |
| `--agent-run` | 立即启动 Agent 执行任务 | - |
| `--agent-timeout N` | Agent 超时时间（秒） | 3600 |
| `--no-auto-close` | 任务完成后不自动关闭 Agent | - |

#### 自动部署参数

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--enable-deploy` | 启用自动部署 | **启用** |
| `--no-deploy` | 禁用自动部署 | - |
| `--deploy-now TASK_ID` | 立即部署指定任务 | - |
| `--test-connection` | 测试生产服务器连接 | - |

#### 其他参数

| 参数 | 说明 |
|------|------|
| `--refresh-trigger` | 仅刷新触发器文件 |

### 常用命令示例

#### 1. 生产环境推荐配置

```cmd
# Agent 循环模式 + 自动部署（推荐）
python scripts\auto_execute_tasks.py --chat-loop --use-agent

# 后台运行
start /B python scripts\auto_execute_tasks.py --chat-loop --use-agent > logs\auto_execute.log 2>&1
```

#### 2. 开发环境配置

```cmd
# Agent 循环模式，但不部署
python scripts\auto_execute_tasks.py --chat-loop --use-agent --no-deploy

# 单次执行测试
python scripts\auto_execute_tasks.py --agent-run --no-deploy
```

#### 3. 传统 Chat 模式

```cmd
# 启用 Chat 循环
python scripts\auto_execute_tasks.py --chat-loop --no-agent

# 指定 Chat 输入框位置
python scripts\auto_execute_tasks.py --chat-loop --no-agent --chat-input-pos "1180,965"
```

#### 4. 部署相关

```cmd
# 测试生产服务器连接
python scripts\auto_execute_tasks.py --test-connection

# 立即部署任务 ID 123
python scripts\auto_execute_tasks.py --deploy-now 123
```

#### 5. 调试和监控

```cmd
# 执行一次
python scripts\auto_execute_tasks.py --once

# 自定义检查间隔（10分钟）
python scripts\auto_execute_tasks.py --interval 600

# 立即发送 Chat 消息
python scripts\auto_execute_tasks.py --send-chat-now
```

---

## 📊 工作流程详解

### Agent 自动化模式流程

```
┌─────────────────────────────────────────────────────────────┐
│                    auto_execute_tasks.py                    │
│                      (Agent 循环模式)                        │
└─────────────────────────────┬───────────────────────────────┘
                              │
      ┌───────────────────────┼───────────────────────┐
      │                       │                       │
      ▼                       ▼                       ▼
┌─────────────┐      ┌─────────────────┐      ┌──────────────┐
│ 1. 同步完成 │      │ 2. 获取pending  │      │ 3. 生成文件  │
│    任务     │      │    任务         │      │              │
│  (completed)│      │  (从数据库)     │      │              │
└─────────────┘      └─────────────────┘      └──────────────┘
      │                       │                       │
      │                       ▼                       │
      │              ┌─────────────────┐              │
      │              │ 4. 创建任务文件 │              │
      │              │    更新状态为   │              │
      │              │    processing   │              │
      │              └─────────────────┘              │
      │                       │                       │
      │                       ▼                       │
      │        ┌──────────────────────────────┐       │
      │        │ 5. 生成执行指令文件          │       │
      │        │    - pending_tasks.json      │       │
      │        │    - instructions.md         │       │
      │        │    - task_trigger.txt        │       │
      │        └──────────────────────────────┘       │
      │                       │                       │
      │                       ▼                       │
      │        ┌──────────────────────────────┐       │
      │        │ 6. 启动 Cursor Agent         │       │
      │        │    (自动打开新 Agent 会话)   │       │
      │        └──────────────────────────────┘       │
      │                       │                       │
      │                       ▼                       │
      │        ┌──────────────────────────────┐       │
      │        │ 7. 等待 Agent 执行完成       │       │
      │        │    (监控 pending_tasks.json) │       │
      │        └──────────────────────────────┘       │
      │                       │                       │
      │                       ▼                       │
      │        ┌──────────────────────────────┐       │
      │        │ 8. 检测到任务完成            │       │
      │        │    (status = completed)      │       │
      │        └──────────────────────────────┘       │
      │                       │                       │
      │                       ▼                       │
      │        ┌──────────────────────────────┐       │
      │        │ 9. 自动部署到生产服务器      │       │
      │        │    - 上传脚本文件            │       │
      │        │    - 上传工作流文件          │       │
      │        │    - 设置执行权限            │       │
      │        └──────────────────────────────┘       │
      │                       │                       │
      │                       ▼                       │
      │        ┌──────────────────────────────┐       │
      │        │ 10. 自动关闭 Agent           │       │
      │        │     (如果启用 auto-close)    │       │
      │        └──────────────────────────────┘       │
      │                       │                       │
      └───────────────────────┼───────────────────────┘
                              ▼
                    ┌─────────────────┐
                    │  等待下一次检查  │
                    │   (60秒间隔)    │
                    └─────────────────┘
```

### 传统 Chat 模式流程

```
┌─────────────────────────────────────────────────────────────┐
│                    auto_execute_tasks.py                    │
│                      (Chat 循环模式)                         │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ 1. 生成执行指令 │
                    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ 2. 发送 Chat 消息│
                    │    (需要 GUI)    │
                    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ 3. 等待人工响应 │
                    │    (手动执行)   │
                    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ 4. 检测任务完成 │
                    └─────────────────┘
                              │
                              ▼
                    ┌─────────────────┐
                    │ 5. 同步数据库   │
                    └─────────────────┘
```

---

## 📁 生成的文件

| 文件路径 | 说明 | 格式 |
|---------|------|------|
| `tasks/pending_tasks.json` | 待处理任务列表 | JSON |
| `tasks/task_execute_instructions.md` | Cursor 执行指令 | Markdown |
| `tasks/task_trigger.txt` | 触发器标记文件 | 文本 |
| `logs/auto_execute.log` | 后台运行日志 | 文本 |
| `app/core/data_flow/*.py` | 任务占位文件 | Python |

### pending_tasks.json 结构

```json
[
  {
    "task_id": 123,
    "task_name": "创建数据流",
    "task_description": "从 A 到 B 的数据同步",
    "status": "processing",
    "created_at": "2025-01-07T10:00:00",
    "file_path": "app/core/data_flow/task_123.py"
  }
]
```

### task_execute_instructions.md 结构

```markdown
# 任务执行指令

## 任务信息
- 任务ID: 123
- 任务名称: 创建数据流
- 状态: processing

## 执行要求
1. 阅读任务描述
2. 创建或修改文件
3. 完成后更新状态为 completed

## 完成标记
完成后请更新 tasks/pending_tasks.json 中的状态为 "completed"
```

---

## ⚙️ 配置说明

### 1. 数据库配置

编辑文件：`app/config/config.py`

```python
# PostgreSQL 数据库配置
DATABASE_CONFIG = {
    'host': 'localhost',
    'port': 5432,
    'database': 'dataops',
    'user': 'postgres',
    'password': 'your_password'
}
```

### 2. 生产服务器配置

编辑文件：`scripts/auto_execute_tasks.py`

```python
PRODUCTION_SERVER = {
    "host": "your-server.com",
    "port": 22,
    "username": "deploy_user",
    "password": "your_password",
    "script_path": "/opt/dataops/scripts",
    "workflow_path": "/opt/dataops/workflows",
}
```

### 3. 自动 Chat 配置

**安装依赖：**

```cmd
pip install pywin32 pyautogui pyperclip
```

**获取 Chat 输入框位置：**

1. 打开 Cursor 并显示 Chat 面板
2. 将鼠标移动到 Chat 输入框
3. 使用屏幕坐标工具记录坐标（如 PowerToys）
4. 使用 `--chat-input-pos "x,y"` 参数指定

**示例：**

```cmd
python scripts\auto_execute_tasks.py --chat-loop --no-agent --chat-input-pos "1180,965"
```

---

## 🔧 依赖安装

### 核心依赖

```cmd
pip install psycopg2-binary
```

### GUI 自动化依赖（可选）

```cmd
pip install pywin32 pyautogui pyperclip
```

### SSH 部署依赖（可选）

```cmd
pip install paramiko
```

### 一键安装所有依赖

```cmd
pip install psycopg2-binary pywin32 pyautogui pyperclip paramiko
```

---

## 🔍 故障排查

### 问题 1：脚本无法启动

**症状：** 运行脚本时报错 `ModuleNotFoundError`

**检查：**
```cmd
# 检查 Python 版本
python --version

# 检查依赖
pip show psycopg2-binary
```

**解决：**
```cmd
pip install psycopg2-binary
```

---

### 问题 2：无法连接数据库

**症状：** 日志显示 `数据库连接失败`

**检查：**
1. PostgreSQL 服务是否运行
2. `app/config/config.py` 配置是否正确
3. 网络连接是否正常
4. 防火墙是否阻止连接

**解决：**
```cmd
# 测试数据库连接
python -c "import psycopg2; conn = psycopg2.connect('postgresql://user:pass@host:5432/db'); print('连接成功')"
```

---

### 问题 3：Agent 无法启动

**症状：** 日志显示 `无法启动 Cursor Agent`

**检查：**
1. Cursor 是否已打开
2. 是否有其他 Agent 正在运行
3. Windows GUI 自动化依赖是否安装

**解决：**
```cmd
# 安装 GUI 依赖
pip install pywin32 pyautogui

# 手动测试
python scripts\auto_execute_tasks.py --agent-run
```

---

### 问题 4：自动部署失败

**症状：** 日志显示 `SSH 连接失败` 或 `部署失败`

**检查：**
1. paramiko 是否安装
2. 生产服务器配置是否正确
3. SSH 连接是否正常

**解决：**
```cmd
# 安装 paramiko
pip install paramiko

# 测试连接
python scripts\auto_execute_tasks.py --test-connection
```

---

### 问题 5：进程无法停止

**症状：** 后台进程无法通过启动器停止

**解决方法 1：** 使用启动器
```
运行 start_task_scheduler.bat → 选择 12
```

**解决方法 2：** 使用 PowerShell
```powershell
Get-WmiObject Win32_Process | Where-Object { $_.CommandLine -like '*auto_execute_tasks.py*' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }
```

**解决方法 3：** 使用任务管理器
1. 打开任务管理器 (Ctrl+Shift+Esc)
2. 找到 `python.exe` 进程
3. 查看命令行包含 `auto_execute_tasks.py`
4. 结束进程

---

### 问题 6：Chat 消息发送失败

**症状：** 启用 Chat 后无反应

**检查：**
1. GUI 依赖是否安装
2. Cursor 窗口是否打开
3. Chat 面板是否可见
4. 输入框位置是否正确

**解决：**
```cmd
# 安装依赖
pip install pywin32 pyautogui pyperclip

# 重新获取输入框位置
# 使用 PowerToys 或其他工具获取准确坐标
```

---

## 📝 日志说明

### 日志级别

- `INFO` - 正常信息
- `WARNING` - 警告信息
- `ERROR` - 错误信息

### 日志位置

**前台运行：** 直接输出到控制台

**后台运行：** `logs\auto_execute.log`

### 查看日志

```cmd
# 查看全部日志
type logs\auto_execute.log

# 查看最后 50 行
powershell "Get-Content logs\auto_execute.log -Tail 50"

# 实时监控日志
powershell "Get-Content logs\auto_execute.log -Wait -Tail 20"
```

### 日志示例

```
2025-01-07 10:00:00 - INFO - ========================================
2025-01-07 10:00:00 - INFO - 🚀 启动自动任务执行脚本 (Agent 模式)
2025-01-07 10:00:00 - INFO - ========================================
2025-01-07 10:00:05 - INFO - ✅ 数据库连接成功
2025-01-07 10:00:06 - INFO - 📋 发现 1 个 pending 任务
2025-01-07 10:00:06 - INFO - 📝 生成任务执行指令文件
2025-01-07 10:00:07 - INFO - 🚀 启动 Cursor Agent...
2025-01-07 10:05:30 - INFO - ✅ 任务 123 已完成
2025-01-07 10:05:31 - INFO - 🚀 开始部署到生产服务器...
2025-01-07 10:05:35 - INFO - ✅ 部署成功
2025-01-07 10:05:36 - INFO - 🔒 关闭 Cursor Agent
```

---

## 🎯 最佳实践

### 1. 生产环境部署

**推荐配置：**
- 使用 Agent 循环模式
- 启用自动部署
- 后台运行
- 定期检查日志

**启动命令：**
```cmd
start /B python scripts\auto_execute_tasks.py --chat-loop --use-agent > logs\auto_execute.log 2>&1
```

**监控命令：**
```cmd
# 查看状态
scripts\start_task_scheduler.bat → 选择 11

# 查看日志
powershell "Get-Content logs\auto_execute.log -Wait -Tail 20"
```

---

### 2. 开发环境测试

**推荐配置：**
- 使用 Agent 单次执行
- 禁用自动部署
- 前台运行

**启动命令：**
```cmd
python scripts\auto_execute_tasks.py --agent-run --no-deploy
```

---

### 3. 调试和排错

**推荐配置：**
- 单次执行模式
- 前台运行
- 查看详细日志

**启动命令：**
```cmd
python scripts\auto_execute_tasks.py --once
```

---

### 4. 定时任务配置

**Windows 任务计划程序：**

1. 打开任务计划程序
2. 创建基本任务
3. 触发器：每天 00:00
4. 操作：启动程序
   - 程序：`python.exe`
   - 参数：`scripts\auto_execute_tasks.py --agent-run`
   - 起始于：`G:\code-lab\DataOps-platform-new`

---

## 📞 相关文件

| 文件路径 | 说明 |
|---------|------|
| `scripts/auto_execute_tasks.py` | 核心调度脚本 |
| `scripts/start_task_scheduler.bat` | 启动器脚本 |
| `scripts/AUTO_TASKS_使用说明.md` | 本文档 |
| `app/config/config.py` | 数据库配置 |
| `tasks/pending_tasks.json` | 任务状态文件 |
| `tasks/task_execute_instructions.md` | 执行指令文件 |
| `logs/auto_execute.log` | 日志文件 |

---

## 🆕 更新日志

### v2.0 (2025-01-07)

**新增功能：**
- ✨ Agent 自动化模式（自动启动/关闭 Agent）
- ✨ 自动部署到生产服务器（SSH + SFTP）
- ✨ 完整的启动器菜单（12 个选项）
- ✨ 服务状态检查功能
- ✨ 立即部署指定任务功能
- ✨ SSH 连接测试功能

**改进：**
- 🔧 优化日志输出格式
- 🔧 改进错误处理机制
- 🔧 增强任务状态同步
- 🔧 完善文档说明

**修复：**
- 🐛 修复未使用变量警告
- 🐛 修复 paramiko 导入问题
- 🐛 修复类型检查错误

---

## 📚 参考资料

- [Python psycopg2 文档](https://www.psycopg.org/docs/)
- [PyAutoGUI 文档](https://pyautogui.readthedocs.io/)
- [Paramiko 文档](https://www.paramiko.org/)
- [Cursor 官方文档](https://cursor.sh/docs)

---

**祝您使用愉快！🚀**

如有问题，请查看日志文件或联系技术支持。