TaskPulse — AI Agent Task Monitor

统一看板，监控 AI Agent 定时任务的运行状态、执行历史，并在任务超时未执行时发送告警通知。

线上地址: https://task.pags.cn

---

核心功能

• AI 原生接入 — AI Agent 通过 API 一次性注册自己 + 所有定时任务，无需手动填写表单
• 统一状态看板 — 所有定时任务的运行状态、最近运行时间、结果一目了然
• 执行汇报 — Agent 执行完任务后主动汇报结果，含详细日志
• 超时告警 — 任务未按时执行时自动告警
• 多渠道通知 — 支持飞书 Webhook、邮件、通用 Webhook
• Base URL 可配置 — 系统设置页面可配置公网访问地址，所有接入指令自动更新

技术栈

层	技术
后端	Python FastAPI (异步) + Gunicorn (生产)
前端	Vue3 + Element Plus (暗色主题)
数据库	MySQL 8.0
部署	单体应用（FastAPI serve Vue3 构建产物）

快速开始

本地开发

# 1. 克隆项目
git clone https://gitea.tatta.cn/Tatta/TaskPulse.git
cd TaskPulse

# 2. 后端 - 创建虚拟环境并安装依赖
cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux:   source .venv/bin/activate
pip install -r requirements.txt

# 3. 复制环境变量并修改数据库配置
cp .env.example .env
# 编辑 .env，配置 MySQL 连接信息

# 4. 启动后端开发服务器
uvicorn app.main:app --reload --port 8000

# 5. 前端（新开终端）
cd frontend
npm install
npm run dev   # 访问 http://localhost:3000

前端 dev server 自动代理 /api 请求到 localhost:8000

生产部署

# 1. 构建前端
cd frontend
npm install && npm run build

# 2. 部署到服务器
# 将整个项目复制到服务器（排除 .venv 和 node_modules）
rsync -avz --exclude='.venv' --exclude='node_modules' --exclude='.git' \
  ./ user@server:/home/openclaw/app/taskpulse/

# 3. 在服务器上创建虚拟环境并安装依赖
cd /home/openclaw/app/taskpulse/backend
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# 4. 使用 Gunicorn 启动
.venv/bin/gunicorn app.main:app \
  -k uvicorn.workers.UvicornWorker \
  -b 0.0.0.0:8000 \
  -w 2 \
  --access-logfile /var/log/taskpulse/access.log \
  --error-logfile /var/log/taskpulse/error.log \
  --daemon

环境变量

复制 backend/.env.example 为 backend/.env 并按需修改：

变量	默认值	说明
TASKPULSE_DB_HOST	localhost	MySQL 主机
TASKPULSE_DB_PORT	3306	MySQL 端口
TASKPULSE_DB_USER	dbuser	数据库用户
TASKPULSE_DB_PASSWORD	-	数据库密码
TASKPULSE_DB_NAME	taskpulse	数据库名
TASKPULSE_DEBUG	true	调试模式（生产环境设为 false）
TASKPULSE_FEISHU_WEBHOOK_URL	(空)	飞书 Webhook 地址
TASKPULSE_SMTP_HOST	(空)	SMTP 服务器
TASKPULSE_SMTP_PORT	587	SMTP 端口
TASKPULSE_SMTP_USER	(空)	SMTP 用户
TASKPULSE_SMTP_PASSWORD	(空)	SMTP 密码

Agent 接入

详细接入说明见 AGENT_GUIDE.md。

最小接入示例

import requests

BASE = "https://task.pags.cn"  # 替换为你的实际地址

# 1. AI Agent 注册自己 + 所有定时任务（一次性）
resp = requests.post(f"{BASE}/api/agents/register-with-tasks", json={
    "name": "my-agent",
    "description": "我的 AI Agent",
    "tasks": [
        {"name": "sync-data", "cron_expression": "*/5 * * * *"},
        {"name": "daily-report", "cron_expression": "0 9 * * *"}
    ]
})
agent = resp.json()
API_KEY = agent["api_key"]   # 保存此 Key
AGENT_ID = agent["agent"]["id"]

# 2. 每次执行后汇报结果
requests.post(f"{BASE}/api/tasks/{TASK_ID}/executions",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"status": "success", "duration_ms": 1200, "log": "done"})

API 概览

方法	路径	说明
POST	/api/agents	注册 Agent
POST	/api/agents/register-with-tasks	AI Agent 一次性注册自己 + 所有任务
GET	/api/agents	列出所有 Agent
POST	/api/tasks?agent_id=X	注册定时任务
GET	/api/tasks	列出所有任务
DELETE	/api/tasks/{id}	删除任务
POST	/api/tasks/{id}/executions	汇报执行结果
GET	/api/tasks/{id}/executions	查看执行历史
GET	/api/dashboard/summary	看板概览
GET	/api/dashboard/tasks	看板任务视图
GET	/api/system/config	读取系统配置（Base URL）
PUT	/api/system/config	更新系统配置
GET	/api/alerts	告警列表
POST	/api/alerts/{id}/acknowledge	确认告警
POST	/api/notification-channels	添加通知渠道
GET	/api/notification-channels	列出通知渠道

完整 API 文档见 /docs（Swagger UI）。

项目结构

taskpulse/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI 入口 + SPA 静态文件服务
│   │   ├── config.py            # 环境变量配置
│   │   ├── database.py          # 异步数据库连接
│   │   ├── models/              # SQLAlchemy 数据模型
│   │   │   ├── agent.py         # Agent（含 API Key 自动生成）
│   │   │   ├── task.py          # 定时任务（cron、宽容窗口）
│   │   │   ├── execution.py     # 执行记录（日志、结果、耗时）
│   │   │   ├── notification.py  # 通知渠道、告警规则、告警历史
│   │   │   └── system_config.py # 系统配置（key-value）
│   │   ├── schemas/             # Pydantic 数据校验
│   │   ├── api/                 # API 路由
│   │   │   ├── agents.py        # Agent CRUD + 批量注册
│   │   │   ├── tasks.py         # 任务 CRUD
│   │   │   ├── executions.py    # 执行汇报 + 历史查询
│   │   │   ├── notifications.py # 通知渠道 + 告警规则 + 告警确认
│   │   │   ├── dashboard.py     # 看板概览统计
│   │   │   └── system.py        # 系统配置
│   │   └── services/            # 业务逻辑
│   │       ├── agent.py / task.py / execution.py
│   │       ├── scheduler.py     # 后台扫描：检测超时任务→生成告警→通知
│   │       └── notification.py  # 飞书 / 邮件 / Webhook 通知发送
│   ├── alembic/                 # 数据库迁移
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── views/               # 页面组件（暗色主题）
│   │   ├── router/              # 路由
│   │   └── api/                 # Axios API 客户端
│   └── package.json
├── AGENT_GUIDE.md               # Agent 接入指南
└── README.md