From ad51078975ef9c86f129f99a910a160126c85c35 Mon Sep 17 00:00:00 2001 From: Steven Date: Wed, 17 Jun 2026 20:36:03 +0800 Subject: [PATCH] docs: rewrite README with comprehensive project introduction and feature overview --- README.md | 301 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 189 insertions(+), 112 deletions(-) diff --git a/README.md b/README.md index f4ae4b6..ecb253e 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,94 @@ -# TaskPulse — AI Agent Task Monitor + -统一看板，监控 AI Agent 定时任务的运行状态、执行历史，并在任务超时未执行时发送告警通知。 +# TaskPulse — AI Agent 定时任务监控系统 -**线上地址**: https://task.pags.cn +> **让 AI Agent 自己汇报工作，你只需要打开看板看一眼。** + +TaskPulse 是一个面向 AI Agent 的定时任务跟踪与监控平台。它不是传统的"你去填表创建任务"的后台管理系统，而是**给 AI Agent 一份 API 说明书，让 Agent 自主注册、自动汇报**——你只需要在统一的 Dashboard 上看全局状态。 + +**线上 Demo**: https://task.pags.cn （账号: `admin` / `admin123`） + +--- + +## 设计理念 + +``` + ┌─────────────────────┐ + │ TaskPulse Dashboard│ + │ 统一状态看板 │ + └──────┬──────────┬───┘ + │ │ + ┌─────────────────┘ └─────────────────┐ + ▼ ▼ + ┌─────────────────┐ ┌──────────────────────┐ + │ AI Agent A │ 注册任务 → 定时执行 │ AI Agent B │ + │ └─ 数据同步 │ ← 汇报结果 + 日志 │ └─ 订单采集 │ + │ └─ 报表生成 │ │ └─ 库存同步 │ + └─────────────────┘ └──────────────────────┘ +``` + +**核心理念：AI 原生接入** + +传统定时任务管理需要用户手动填写 cron 表达式、配置参数。但 AI Agent 本身就具备理解和执行能力——只需给 Agent 一份 API 文档，它就能： + +1. **自主注册** — 通过一条 API 把自己和所有定时任务登记到系统 +2. **按时汇报** — 每次任务执行完毕，主动 POST 结果（含日志、耗时、状态） +3. **自动纠错** — 如果某个任务到点没执行，系统自动告警 + +人类要做的只有一件事：**打开看板，看一眼全局状态。** --- ## 核心功能 -- **AI 原生接入** — AI Agent 通过 API 一次性注册自己 + 所有定时任务，无需手动填写表单 -- **统一状态看板** — 所有定时任务的运行状态、最近运行时间、结果一目了然 -- **执行汇报** — Agent 执行完任务后主动汇报结果，含详细日志 -- **超时告警** — 任务未按时执行时自动告警 -- **多渠道通知** — 支持飞书 Webhook、邮件、通用 Webhook -- **Base URL 可配置** — 系统设置页面可配置公网访问地址，所有接入指令自动更新 +### 🤖 AI 原生接入 +- **一次性批量注册**：`POST /api/agents/register-with-tasks` — Agent 在一分钟内完成注册 + 所有任务登记 +- **API Key 鉴权**：每个 Agent 独立密钥，汇报时自动校验 +- **无缝重注册**：删除后可重新注册，获取新 Key 继续工作 +- **Agent 头像**：名称首字 + 确定性色彩头像，多 Agent 一目了然 + +### 📊 统一状态看板 +- **概览卡片**：Agent 数量、任务总数、24h 执行量、待处理告警 +- **全任务视图**：所有 Agent 的任务集中展示，状态、最近运行、结果一目了然 +- **任务标签**：可对任务打标签（如"数据同步"、"重要"），按标签筛选 +- **Cron 人类可读**：`*/5 * * * *` 自动显示为 "每5分钟" +- **时间本地化**：所有时间自动从 UTC 转为浏览器本地时区 + +### ⏱ 执行汇报与追踪 +- **实时汇报**：Agent 执行完任务后 POST 结果，系统记录执行日志 +- **执行历史**：每个任务都有完整的时间线，支持分页查看 +- **日志查看器**：暗色终端风格，方便排查问题 +- **搜索过滤**：按任务名称、标签、状态快速筛选 + +### 🚨 超时告警与通知 +- **自动检测**：后台调度器每 60 秒扫描未按时执行的任务 +- **宽容窗口**：每个任务可单独配置容忍时间，避免误报 +- **多渠道通知**：飞书 Webhook、邮件 SMTP、通用 Webhook +- **告警确认**：已处理的告警可标记确认，闭环管理 + +### 🎨 现代化界面 +- **暗色主题**：深色渐变背景 + 霓虹色点缀，降低视觉疲劳 +- **全宽布局**：充分利用屏幕空间 +- **响应式**：适配不同分辨率 + +--- ## 技术栈 | 层 | 技术 | |---|---| -| 后端 | Python FastAPI (异步) + Gunicorn (生产) | -| 前端 | Vue3 + Element Plus (暗色主题) | +| 后端框架 | Python FastAPI (异步) | +| 生产服务 | Gunicorn + Uvicorn Worker | +| 前端框架 | Vue 3 + Element Plus | +| 构建工具 | Vite | | 数据库 | MySQL 8.0 | -| 部署 | 单体应用（FastAPI serve Vue3 构建产物） | +| 数据校验 | Pydantic v2 | +| ORM | SQLAlchemy 2.0 (异步) | +| 认证 | JWT (python-jose) + bcrypt | +| 定时检测 | APScheduler (异步) | +| 部署形态 | 单体应用 (FastAPI serve 前端静态文件) | + +--- ## 快速开始 @@ -30,128 +96,138 @@ ```bash # 1. 克隆项目 -git clone https://gitea.tatta.cn/Tatta/TaskPulse.git +git clone https://github.com/oventh/TaskPulse.git cd TaskPulse -# 2. 后端 - 创建虚拟环境并安装依赖 +# 2. 后端 cd backend python -m venv .venv -# Windows: .venv\Scripts\activate -# Linux: source .venv/bin/activate +source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt - -# 3. 复制环境变量并修改数据库配置 -cp .env.example .env -# 编辑 .env，配置 MySQL 连接信息 - -# 4. 启动后端开发服务器 +cp .env.example .env # 编辑 .env 配置数据库 uvicorn app.main:app --reload --port 8000 -# 5. 前端（新开终端） +# 3. 前端（新终端） cd frontend npm install -npm run dev # 访问 http://localhost:3000 +npm run dev # http://localhost:3000 ``` -> 前端 dev server 自动代理 `/api` 请求到 `localhost:8000` +> 前端 `npm run dev` 会代理 `/api` 到 `localhost:8000` ### 生产部署 ```bash # 1. 构建前端 -cd frontend -npm install && npm run build +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/ + ./ user@server:/home/app/taskpulse/ -# 3. 在服务器上创建虚拟环境并安装依赖 -cd /home/openclaw/app/taskpulse/backend -python3 -m venv .venv -.venv/bin/pip install -r requirements.txt - -# 4. 使用 Gunicorn 启动 +# 3. 安装依赖 + 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 \ - --access-logfile /var/log/taskpulse/access.log \ - --error-logfile /var/log/taskpulse/error.log \ - --daemon + -b 0.0.0.0:8000 -w 2 --preload --daemon ``` -## 环境变量 +--- -复制 `backend/.env.example` 为 `backend/.env` 并按需修改： +## Agent 接入指南 -| 变量 | 默认值 | 说明 | -|------|--------|------| -| 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](./AGENT_GUIDE.md)。 - -### 最小接入示例 +让 AI Agent 自动接入只需 3 步： ```python import requests -BASE = "https://task.pags.cn" # 替换为你的实际地址 +BASE = "https://your-domain.com" # 替换为你的实际地址 -# 1. AI Agent 注册自己 + 所有定时任务（一次性） +# 1. 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 * * *"} + {"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"] +data = resp.json() +API_KEY = data["agent"]["api_key"] # ← 保存此 Key +AGENT_ID = data["agent"]["id"] -# 2. 每次执行后汇报结果 +# 2. 每次执行完任务后，汇报结果 requests.post(f"{BASE}/api/tasks/{TASK_ID}/executions", headers={"Authorization": f"Bearer {API_KEY}"}, - json={"status": "success", "duration_ms": 1200, "log": "done"}) + json={"status": "success", "duration_ms": 1500, "log": "执行完毕"}) ``` +> 完整接入说明见 [AGENT_GUIDE.md](./AGENT_GUIDE.md)，含 curl / Python / 批量注册示例。 + +--- + +## 系统配置 + +| 变量 | 默认值 | 说明 | +|------|--------|------| +| `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_SECRET_KEY` | - | JWT 签名密钥 | +| `TASKPULSE_SMTP_*` | - | 邮件通知配置 | + +完整变量列表见 `backend/.env.example`。 + +--- + ## API 概览 +### Agent 管理 | 方法 | 路径 | 说明 | |------|------|------| -| 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 | 列出通知渠道 | +| POST | `/api/agents` | 注册 Agent（返回 API Key） | +| **POST** | **`/api/agents/register-with-tasks`** | **🌟 Agent + 任务一次性批量注册** | +| GET | `/api/agents` | 列出所有 Agent | +| PUT | `/api/agents/{id}` | 修改 Agent 名称/描述 | +| DELETE | `/api/agents/{id}` | 删除 Agent（关联任务一并删除） | -完整 API 文档见 `/docs`（Swagger UI）。 +### 定时任务 +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | `/api/tasks?agent_id=X` | 注册定时任务 | +| GET | `/api/tasks` | 任务列表（支持 `?q=&tags=&status=` 搜索） | +| PUT | `/api/tasks/{id}` | 修改任务名称/标签/描述 | +| DELETE | `/api/tasks/{id}` | 删除任务 | + +### 执行汇报 +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | `/api/tasks/{id}/executions` | Agent 汇报执行结果 | +| GET | `/api/tasks/{id}/executions` | 查看执行历史（分页） | +| GET | `/api/tasks/{id}/executions/{eid}` | 查看单次执行详情 | + +### 看板与配置 +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/dashboard/summary` | 看板概览统计数据 | +| GET | `/api/dashboard/tasks` | 看板全任务视图 | +| GET | `/api/system/config` | 获取系统配置 | +| PUT | `/api/system/config` | 更新系统配置（Base URL） | + +### 告警与通知 +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/api/alerts` | 告警列表 | +| POST | `/api/alerts/{id}/acknowledge` | 确认告警 | +| POST | `/api/notification-channels` | 添加通知渠道（飞书/邮件/Webhook） | + +完整 OpenAPI 文档在 `/docs`（Swagger UI）查看。 + +--- ## 项目结构 @@ -159,35 +235,36 @@ requests.post(f"{BASE}/api/tasks/{TASK_ID}/executions", 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 通知发送 +│ │ ├── main.py # FastAPI 入口 + SPA 静态文件 + 生命周期 +│ │ ├── config.py # 环境变量配置 (pydantic-settings) +│ │ ├── database.py # 异步 MySQL 连接 +│ │ ├── models/ # SQLAlchemy 数据模型（6 张表） +│ │ │ ├── agent.py # Agent + API Key +│ │ │ ├── task.py # 定时任务 + cron + tags +│ │ │ ├── execution.py # 执行记录 + 日志 +│ │ │ ├── notification.py # 通知渠道 + 告警规则 + 告警 +│ │ │ ├── system_config.py # 系统配置 (key-value) +│ │ │ └── user.py # 看板登录用户 +│ │ ├── schemas/ # Pydantic 请求/响应模型 +│ │ ├── api/ # REST API 路由（7 个模块） +│ │ └── services/ # 业务逻辑层 +│ │ ├── scheduler.py # ⏰ 后台调度器（超时检测） +│ │ └── notification.py # 📢 飞书/邮件/Webhook 发送 │ ├── alembic/ # 数据库迁移 │ └── requirements.txt ├── frontend/ │ ├── src/ -│ │ ├── views/ # 页面组件（暗色主题） -│ │ ├── router/ # 路由 -│ │ └── api/ # Axios API 客户端 +│ │ ├── views/ # 6 个页面（暗色主题） +│ │ ├── router/ # 路由守卫 + 登录跳转 +│ │ ├── api/ # Axios 客户端 + 401 拦截 +│ │ └── assets/ # 全局样式 + Element Plus 覆盖 │ └── package.json -├── AGENT_GUIDE.md # Agent 接入指南 +├── AGENT_GUIDE.md # Agent API 接入说明 └── README.md ``` + +--- + +## 许可证 + +MIT License © 2026