Steven d82e1c9946 docs: add English README (README.en.md) with language switcher

2026-06-19 16:06:46 +08:00

9.9 KiB

Raw Blame History

TaskPulse — AI Agent Scheduled Task Monitor

Let your AI agents self-report. You just glance at the dashboard.

TaskPulse is a tracking and monitoring platform designed for AI agents' scheduled tasks. Unlike traditional CRUD-heavy admin panels, TaskPulse is AI-native: give your agents an API spec, and they autonomously register themselves, report execution results, and update their status — no manual form-filling required.

Live Demo: https://task.pags.cn (login: admin / admin123)

📖 中文文档

Philosophy

                         ┌─────────────────────┐
                         │   TaskPulse Dashboard│
                         │   Unified Status View│
                         └──────┬──────────┬───┘
                                │          │
              ┌─────────────────┘          └─────────────────┐
              ▼                                               ▼
     ┌─────────────────┐                          ┌──────────────────────┐
     │  AI Agent A     │  register tasks → execute │   AI Agent B         │
     │  ├─ data sync   │  ← report result + log    │   ├─ order fetch     │
     │  └─ report gen  │                           │   └─ inventory sync  │
     └─────────────────┘                          └──────────────────────┘

AI-Native by Design

Traditional schedulers require humans to fill forms and manage cron expressions. But AI agents can read API docs and act autonomously:

Self-Register — One API call to register both the agent and all its tasks
Report Results — After each execution, POST back the result with logs and duration
Auto-Alert — If a task misses its window, the system alerts automatically

The only thing humans need to do: open the dashboard and see the big picture.

Features

🤖 AI-Native Onboarding

Batch Registration: POST /api/agents/register-with-tasks — agent + tasks in one shot
API Key Auth: Each agent gets its own key for reporting
Re-registration: Deleted agents can re-register anytime
Agent Avatars: First-letter + deterministic color avatars for quick visual identification

📊 Unified Dashboard

Summary Cards: agent count, task count, 24h executions, pending alerts
Global Task View: all tasks from all agents in one place
Task Tags: label tasks (e.g. "data-sync", "critical"), filter by tags
Human-Readable Cron: */5 * * * * → "Every 5 minutes"
Localized Time: all timestamps auto-converted from UTC to browser timezone

⏱ Execution Tracking

Live Reporting: agents POST results immediately after execution
Execution History: full timeline per task, paginated
Log Viewer: dark terminal-style viewer for debugging
Search & Filter: by task name, tags, and status

🚨 Timeout Alerts & Notifications

Auto-Scan: background scheduler checks overdue tasks every 60s
Grace Window: per-task tolerance to avoid false alerts
Multi-Channel: Feishu (Lark) webhook, email SMTP, generic webhook
Alert Acknowledgment: mark alerts as handled for closed-loop management

🎨 Modern UI

Dark Theme: gradient backgrounds + neon accents
Full-Width Layout: maximizes screen usage
Responsive: adapts to different screen sizes

Tech Stack

Layer	Technology
Backend	Python FastAPI (async)
Production Server	Gunicorn + Uvicorn Worker
Frontend	Vue 3 + Element Plus
Build Tool	Vite
Database	MySQL 8.0
Validation	Pydantic v2
ORM	SQLAlchemy 2.0 (async)
Auth	JWT (python-jose) + bcrypt
Scheduler	APScheduler (async loop)
Deployment	Monolithic (FastAPI serves SPA)

Quick Start

Local Development

# 1. Clone
git clone https://github.com/oventh/TaskPulse.git
cd TaskPulse

# 2. Backend
cd backend
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env                # edit .env with your DB config
uvicorn app.main:app --reload --port 8000

# 3. Frontend (new terminal)
cd frontend
npm install
npm run dev                         # http://localhost:3000

Frontend dev server proxies /api to localhost:8000.

Production Deployment

# 1. Build frontend
cd frontend && npm install && npm run build

# 2. Deploy to server
rsync -avz --exclude='.venv' --exclude='node_modules' --exclude='.git' \
  ./ user@server:/home/app/taskpulse/

# 3. Install deps + start with Gunicorn
cd /home/app/taskpulse/backend
python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
.venv/bin/gunicorn app.main:app \
  -k uvicorn.workers.UvicornWorker \
  -b 0.0.0.0:8000 -w 2 --preload --daemon

Agent Integration

Let your AI agent self-register in 3 steps:

import requests

BASE = "https://your-domain.com"

# 1. Register agent + all its tasks (one API call)
resp = requests.post(f"{BASE}/api/agents/register-with-tasks", json={
    "name": "my-agent",
    "description": "My AI Agent",
    "tasks": [
        {"name": "sync-data",     "cron_expression": "*/5 * * * *"},
        {"name": "daily-report",  "cron_expression": "0 9 * * *"}
    ]
})
data = resp.json()
API_KEY = data["agent"]["api_key"]   # ← save this
AGENT_ID = data["agent"]["id"]

# 2. Report execution result after each run
requests.post(f"{BASE}/api/tasks/{TASK_ID}/executions",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={"status": "success", "duration_ms": 1500, "log": "Task completed"})

For curl, batch registration, and more examples, see the Chinese doc AGENT_GUIDE.md.

Configuration

Variable	Default	Description
`TASKPULSE_DB_HOST`	localhost	MySQL host
`TASKPULSE_DB_PORT`	3306	MySQL port
`TASKPULSE_DB_USER`	dbuser	Database user
`TASKPULSE_DB_PASSWORD`	-	Database password
`TASKPULSE_DB_NAME`	taskpulse	Database name
`TASKPULSE_DEBUG`	true	Debug mode (false in production)
`TASKPULSE_SECRET_KEY`	-	JWT signing key
`TASKPULSE_SMTP_*`	-	Email notification config

See backend/.env.example for the full list.

API Overview

Agents

Method	Path	Description
POST	`/api/agents`	Register an agent (returns API Key)
POST	`/api/agents/register-with-tasks`	🌟 Batch register agent + tasks
GET	`/api/agents`	List all agents
PUT	`/api/agents/{id}`	Update agent name/description
DELETE	`/api/agents/{id}`	Delete agent (cascades to tasks)

Tasks

Method	Path	Description
POST	`/api/tasks?agent_id=X`	Create a scheduled task
GET	`/api/tasks`	List tasks (`?q=&tags=&status=` filters)
PUT	`/api/tasks/{id}`	Update task name/tags/description
DELETE	`/api/tasks/{id}`	Delete a task

Execution Reporting

Method	Path	Description
POST	`/api/tasks/{id}/executions`	Agent reports execution result
GET	`/api/tasks/{id}/executions`	View execution history (paginated)
GET	`/api/tasks/{id}/executions/{eid}`	View single execution detail

Dashboard & Config

Method	Path	Description
GET	`/api/dashboard/summary`	Dashboard summary stats
GET	`/api/dashboard/tasks`	Dashboard full task view
GET	`/api/system/config`	Get system config
PUT	`/api/system/config`	Update system config (Base URL)

Alerts & Notifications

Method	Path	Description
GET	`/api/alerts`	List alerts
POST	`/api/alerts/{id}/acknowledge`	Acknowledge an alert
POST	`/api/notification-channels`	Add notification channel

Full OpenAPI docs at /docs (Swagger UI).

Project Structure

taskpulse/
├── backend/
│   ├── app/
│   │   ├── main.py              # FastAPI entry + SPA static files + lifecycle
│   │   ├── config.py            # Environment variables (pydantic-settings)
│   │   ├── database.py          # Async MySQL connection
│   │   ├── models/              # SQLAlchemy models (6 tables)
│   │   ├── schemas/             # Pydantic request/response models
│   │   ├── api/                 # REST API routes (7 modules)
│   │   └── services/            # Business logic layer
│   │       ├── scheduler.py     # ⏰ Background scheduler (timeout detection)
│   │       └── notification.py  # 📢 Feishu/Email/Webhook sender
│   ├── alembic/                 # DB migrations
│   └── requirements.txt
├── frontend/
│   ├── src/
│   │   ├── views/               # 6 pages (dark theme)
│   │   ├── router/              # Route guards + login redirect
│   │   ├── api/                 # Axios client + 401 interceptor
│   │   └── assets/              # Global styles + Element Plus overrides
│   └── package.json
├── AGENT_GUIDE.md               # Agent API guide (Chinese)
├── README.md                    # Documentation (Chinese)
└── README.en.md                 # Documentation (English)

9.9 KiB Raw Blame History