# 任务监控
**本文引用的文件**
- [src/app/api/task-executions/route.ts](file://src/app/api/task-executions/route.ts)
- [src/hooks/use-task-executions.ts](file://src/hooks/use-task-executions.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/app/api/cron-tasks/route.ts](file://src/app/api/cron-tasks/route.ts)
- [src/app/api/cron-engine/route.ts](file://src/app/api/cron-engine/route.ts)
- [src/lib/cron/engine.ts](file://src/lib/cron/engine.ts)
- [src/lib/cron/executor.ts](file://src/lib/cron/executor.ts)
- [src/lib/cron/cron-parser.ts](file://src/lib/cron/cron-parser.ts)
- [src/lib/types.ts](file://src/lib/types.ts)
- [src/app/api/data/export/route.ts](file://src/app/api/data/export/route.ts)
- [src/app/api/data/clear/route.ts](file://src/app/api/data/clear/route.ts)
- [src/app/api/im-channels/route.ts](file://src/app/api/im-channels/route.ts)
- [src/app/api/im-channels/[id]/connect/route.ts](file://src/app/api/im-channels/[id]/connect/route.ts)
- [src/lib/im/bridge-manager.ts](file://src/lib/im/bridge-manager.ts)
- [src/app/api/im-events/route.ts](file://src/app/api/im-events/route.ts)
- [templates/init/HEARTBEAT.md](file://templates/init/HEARTBEAT.md)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件为“任务监控系统”的完整技术文档，聚焦于任务执行历史记录、状态跟踪与性能统计能力，解释监控数据的采集、存储与查询机制，并阐述实时监控界面、历史数据分析与趋势预测思路。同时覆盖告警机制、通知系统（IM桥接）、故障诊断工具，以及监控API接口、数据导出与报表生成建议。
系统围绕“定时任务引擎”展开：通过数据库中的定时任务配置，引擎按分钟粒度扫描匹配的任务并触发执行；每次执行结果写入执行历史表，并可选地通过IM渠道进行告警通知。前端通过React Hook拉取执行历史并提供筛选与分页展示；后端提供REST API用于任务管理、执行记录查询、引擎启停控制等。
## 项目结构
- 后端API层：Next.js App Router路由，集中于src/app/api下，负责任务、执行记录、引擎状态、IM通道与事件等接口。
- 数据访问层：SQLite数据库封装与迁移逻辑，位于src/lib/db.ts，包含任务、执行记录、会话、消息等核心表。
- 定时任务引擎：src/lib/cron/engine.ts负责调度与执行，executor.ts实现不同类型任务的具体执行逻辑，cron-parser.ts提供表达式匹配。
- 前端监控界面：src/hooks/use-task-executions.ts提供执行历史的拉取、筛选与分页；Schedule视图中提供类型与状态过滤。
- IM通知与桥接：src/lib/im/bridge-manager.ts负责多IM渠道适配、连接管理与消息投递；IM事件通过SSE推送到桌面端。
- 数据导出与清理：提供导出会话与消息、清理用户数据的API。
```mermaid
graph TB
subgraph "前端"
FE_UI["Schedule 视图
use-task-executions 钩子"]
end
subgraph "后端API"
API_TASK["/api/cron-tasks"]
API_EXEC["/api/task-executions"]
API_ENGINE["/api/cron-engine"]
API_IM["/api/im-channels
/api/im-events"]
end
subgraph "业务逻辑"
CRON_ENGINE["CronEngine 引擎"]
EXECUTOR["任务执行器 executor"]
PARSER["cron 表达式解析"]
end
subgraph "数据层"
DB["SQLite 数据库
cron_tasks / task_executions / sessions / messages"]
end
FE_UI --> API_EXEC
FE_UI --> API_TASK
FE_UI --> API_ENGINE
FE_UI --> API_IM
API_TASK --> CRON_ENGINE
API_EXEC --> CRON_ENGINE
API_ENGINE --> CRON_ENGINE
CRON_ENGINE --> EXECUTOR
CRON_ENGINE --> PARSER
CRON_ENGINE --> DB
EXECUTOR --> DB
EXECUTOR --> API_IM
API_IM --> DB
```
图表来源
- [src/app/api/task-executions/route.ts:1-76](file://src/app/api/task-executions/route.ts#L1-L76)
- [src/app/api/cron-tasks/route.ts:1-53](file://src/app/api/cron-tasks/route.ts#L1-L53)
- [src/app/api/cron-engine/route.ts:1-30](file://src/app/api/cron-engine/route.ts#L1-L30)
- [src/lib/cron/engine.ts:1-121](file://src/lib/cron/engine.ts#L1-L121)
- [src/lib/cron/executor.ts:1-306](file://src/lib/cron/executor.ts#L1-L306)
- [src/lib/db.ts:1-499](file://src/lib/db.ts#L1-L499)
- [src/app/api/im-channels/route.ts:1-12](file://src/app/api/im-channels/route.ts#L1-L12)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
章节来源
- [src/app/api/task-executions/route.ts:1-76](file://src/app/api/task-executions/route.ts#L1-L76)
- [src/app/api/cron-tasks/route.ts:1-53](file://src/app/api/cron-tasks/route.ts#L1-L53)
- [src/app/api/cron-engine/route.ts:1-30](file://src/app/api/cron-engine/route.ts#L1-L30)
- [src/lib/cron/engine.ts:1-121](file://src/lib/cron/engine.ts#L1-L121)
- [src/lib/cron/executor.ts:1-306](file://src/lib/cron/executor.ts#L1-L306)
- [src/lib/db.ts:135-147](file://src/lib/db.ts#L135-L147)
## 核心组件
- 任务执行历史表：task_executions，记录每次执行的task_id、task_name、result、status、session_id、executed_at。
- 定时任务表：cron_tasks，记录任务配置（schedule、action、action_type、agent_name、skill_name、workspace_id、is_heartbeat、config、last_run_at、last_run_result）。
- 会话与消息：sessions/messages，用于承载每次任务执行产生的对话上下文，便于回溯与导出。
- 执行器：根据任务类型（心跳、运行代理、运行技能、自定义提示）调用SDK执行，并可选通知IM。
- 引擎：每分钟扫描一次启用的任务，匹配cron表达式后异步执行，写入执行历史并更新任务元信息。
- 前端Hook：use-task-executions，负责分页、筛选（类型/状态）、加载更多与刷新。
章节来源
- [src/lib/db.ts:135-147](file://src/lib/db.ts#L135-L147)
- [src/lib/types.ts:166-211](file://src/lib/types.ts#L166-L211)
- [src/hooks/use-task-executions.ts:1-98](file://src/hooks/use-task-executions.ts#L1-L98)
## 架构总览
系统采用“数据库驱动 + 调度引擎 + 事件推送”的架构：
- 数据库作为事实来源，保存任务配置与执行历史。
- CronEngine以单例模式运行，定时扫描并执行任务，执行结果落库。
- 执行器支持多种任务类型，统一产出文本结果与会话ID，便于后续分析与通知。
- 前端通过API拉取执行历史，结合筛选条件进行可视化展示。
- IM桥接层负责将异常或告警结果投递到指定渠道，SSE向桌面端推送事件。
```mermaid
sequenceDiagram
participant Client as "浏览器/桌面客户端"
participant API as "后端API"
participant Engine as "CronEngine"
participant Executor as "任务执行器"
participant DB as "SQLite数据库"
participant IM as "IM桥接"
Client->>API : GET /api/task-executions?workspace_id=...
API->>DB : 查询执行历史(带筛选/分页)
DB-->>API : 返回执行记录
API-->>Client : JSON执行历史
Client->>API : POST /api/cron-engine {action : "start"}
API->>Engine : 启动引擎
Engine->>DB : 每分钟读取启用任务
Engine->>Executor : 匹配后执行任务
Executor->>DB : 写入会话与消息
Executor->>DB : 写入执行历史
Executor->>IM : 发送告警/通知(可选)
IM-->>Client : SSE事件推送
```
图表来源
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
- [src/app/api/cron-engine/route.ts:4-29](file://src/app/api/cron-engine/route.ts#L4-L29)
- [src/lib/cron/engine.ts:44-105](file://src/lib/cron/engine.ts#L44-L105)
- [src/lib/cron/executor.ts:26-47](file://src/lib/cron/executor.ts#L26-L47)
- [src/app/api/im-events/route.ts:13-65](file://src/app/api/im-events/route.ts#L13-L65)
## 详细组件分析
### 组件A：任务执行历史与查询
- 功能要点
- 支持按任务ID、工作区、类型（心跳/普通）、状态（ok/alert/error）筛选。
- 支持limit/offset分页，限制范围1~500。
- 返回字段包含执行时间、状态、结果摘要、关联会话ID等。
- 关键实现
- 路由参数解析与SQL拼接，动态构建WHERE条件。
- 与cron_tasks表JOIN，支持按工作区与心跳类型过滤。
- 插入执行记录时同步更新任务的last_run_at与last_run_result。
```mermaid
flowchart TD
Start(["请求进入 /api/task-executions"]) --> Parse["解析查询参数
task_id/workspace_id/type/status/limit/offset"]
Parse --> HasTaskId{"是否指定task_id?"}
HasTaskId --> |是| QueryByTask["按task_id查询执行历史"]
HasTaskId --> |否| BuildWhere["构建WHERE条件
工作区/类型/状态"]
BuildWhere --> Join["与cron_tasks内连接"]
Join --> Order["按执行时间倒序分页返回"]
QueryByTask --> Return["返回JSON"]
Order --> Return
```
图表来源
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
章节来源
- [src/app/api/task-executions/route.ts:1-76](file://src/app/api/task-executions/route.ts#L1-L76)
- [src/hooks/use-task-executions.ts:30-98](file://src/hooks/use-task-executions.ts#L30-L98)
### 组件B：定时任务引擎与执行流程
- 功能要点
- 单例引擎，每60秒扫描一次启用任务。
- 使用cron表达式匹配当前时间点，避免并发重复执行。
- 执行完成后写入执行历史与任务元信息，必要时自动禁用一次性任务。
- 关键实现
- CronEngine.tick遍历启用任务，matchesCron判断是否应执行。
- executeTask根据action_type分派到不同执行分支。
- 执行器创建会话与消息，产出文本结果并可通知IM。
```mermaid
sequenceDiagram
participant Timer as "定时器(每60秒)"
participant Engine as "CronEngine"
participant DB as "数据库"
participant Executor as "executeTask"
participant IM as "IM通知"
Timer->>Engine : tick()
Engine->>DB : 读取启用任务
Engine->>Engine : 遍历任务并匹配cron
Engine->>Executor : 执行任务(生成会话/消息)
Executor->>DB : 写入执行历史
Executor->>DB : 更新任务last_run_at/result
alt 非OK状态且配置了通知
Executor->>IM : 发送告警消息
end
```
图表来源
- [src/lib/cron/engine.ts:44-105](file://src/lib/cron/engine.ts#L44-L105)
- [src/lib/cron/executor.ts:26-47](file://src/lib/cron/executor.ts#L26-L47)
章节来源
- [src/lib/cron/engine.ts:16-121](file://src/lib/cron/engine.ts#L16-L121)
- [src/lib/cron/executor.ts:1-306](file://src/lib/cron/executor.ts#L1-L306)
- [src/lib/cron/cron-parser.ts:7-20](file://src/lib/cron/cron-parser.ts#L7-L20)
### 组件C：IM通知与告警机制
- 功能要点
- 心跳任务在非正常状态下可通过IM通道发送告警。
- 通知目标优先DM绑定，其次群组绑定。
- BridgeManager负责适配器生命周期、重连策略与并发控制。
- 关键实现
- executeHeartbeat根据检查清单结果判定状态并发送通知。
- notifyIm解析绑定并调用DeliveryLayer投递消息。
- IM事件通过SSE推送到桌面端，便于实时监控。
```mermaid
sequenceDiagram
participant Engine as "CronEngine"
participant Executor as "executeHeartbeat"
participant DB as "数据库"
participant Bridge as "BridgeManager"
participant IM as "IM通道"
Engine->>Executor : 执行心跳任务
Executor->>DB : 读取HEARTBEAT.md检查项
Executor->>Executor : 判定状态(ok/alert)
alt 非正常且配置通知
Executor->>DB : 查询绑定(chat_id)
Executor->>Bridge : 获取适配器并投递
Bridge->>IM : 发送告警消息
end
```
图表来源
- [src/lib/cron/executor.ts:67-104](file://src/lib/cron/executor.ts#L67-L104)
- [src/lib/im/bridge-manager.ts:78-144](file://src/lib/im/bridge-manager.ts#L78-L144)
- [src/app/api/im-channels/[id]/connect/route.ts](file://src/app/api/im-channels/[id]/connect/route.ts#L24-L37)
- [src/app/api/im-events/route.ts:13-65](file://src/app/api/im-events/route.ts#L13-L65)
章节来源
- [src/lib/cron/executor.ts:67-104](file://src/lib/cron/executor.ts#L67-L104)
- [src/lib/im/bridge-manager.ts:78-144](file://src/lib/im/bridge-manager.ts#L78-L144)
- [src/app/api/im-channels/[id]/connect/route.ts:1-L46](file://src/app/api/im-channels/[id]/connect/route.ts#L1-L46)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
### 组件D：数据模型与索引
- 关键表
- cron_tasks：任务配置与元信息。
- task_executions：执行历史，含状态与结果摘要。
- sessions/messages：执行产生的会话与消息，便于回溯与导出。
- 索引
- task_executions(task_id, executed_at DESC)：加速按任务与时间排序查询。
```mermaid
erDiagram
CRON_TASKS {
text id PK
text name
text schedule
text action
text action_type
text agent_name
text skill_name
text workspace_id
int enabled
int is_heartbeat
text config
text last_run_at
text last_run_result
text created_at
text updated_at
}
TASK_EXECUTIONS {
text id PK
text task_id FK
text task_name
text result
text status
text session_id
text executed_at
}
SESSIONS {
text id PK
text title
text workspace
text model
text status
text created_at
text updated_at
}
MESSAGES {
text id PK
text session_id FK
text role
text content
text created_at
}
CRON_TASKS ||--o{ TASK_EXECUTIONS : "产生"
SESSIONS ||--o{ MESSAGES : "包含"
```
图表来源
- [src/lib/db.ts:117-147](file://src/lib/db.ts#L117-L147)
章节来源
- [src/lib/db.ts:117-147](file://src/lib/db.ts#L117-L147)
### 组件E：前端监控界面与交互
- 功能要点
- 提供类型（全部/心跳/普通）与状态（全部/OK/告警/错误）筛选。
- 分页加载与“加载更多”，支持刷新。
- 显示最近一次执行时间与结果摘要。
- 关键实现
- use-task-executions构建查询参数，调用API获取执行历史并映射为前端类型。
```mermaid
flowchart TD
UI_Start["打开Schedule视图"] --> Init["初始化筛选与分页参数"]
Init --> Fetch["首次拉取执行历史"]
Fetch --> Render["渲染列表(类型/状态/时间/结果)"]
Render --> Scroll{"滚动至底部?"}
Scroll --> |是| LoadMore["追加一页"]
Scroll --> |否| Wait["等待操作"]
LoadMore --> Fetch
```
图表来源
- [src/hooks/use-task-executions.ts:30-98](file://src/hooks/use-task-executions.ts#L30-98)
章节来源
- [src/hooks/use-task-executions.ts:1-98](file://src/hooks/use-task-executions.ts#L1-L98)
### 组件F：数据导出与清理
- 导出
- /api/data/export：按工作区导出会话与消息，支持版本化输出。
- 清理
- /api/data/clear：清空用户数据（需确认），保留基础表结构与设置。
章节来源
- [src/app/api/data/export/route.ts:1-38](file://src/app/api/data/export/route.ts#L1-L38)
- [src/app/api/data/clear/route.ts:1-31](file://src/app/api/data/clear/route.ts#L1-L31)
## 依赖关系分析
- 组件耦合
- CronEngine依赖数据库读取任务配置，依赖executeTask执行具体动作，最终写回执行历史。
- executeTask依赖工作区文件系统读取模板、SDK客户端执行、IM桥接投递。
- 前端Hook依赖API层提供执行历史与任务管理。
- 外部依赖
- SQLite(better-sqlite3)：本地持久化。
- IM适配器：Telegram/Feishu/Discord等，通过BridgeManager统一管理。
- 可能的循环依赖
- 未见直接循环依赖；模块间通过API与数据库解耦。
```mermaid
graph LR
Engine["CronEngine"] --> DB["db.ts"]
Engine --> Executor["executor.ts"]
Executor --> DB
Executor --> IM["bridge-manager.ts"]
UI["use-task-executions.ts"] --> APIExec["/api/task-executions"]
APIExec --> DB
APIEngine["/api/cron-engine"] --> Engine
APIIM["/api/im-channels"] --> IM
IM --> SSE["/api/im-events"]
```
图表来源
- [src/lib/cron/engine.ts:1-121](file://src/lib/cron/engine.ts#L1-L121)
- [src/lib/cron/executor.ts:1-306](file://src/lib/cron/executor.ts#L1-L306)
- [src/lib/db.ts:1-499](file://src/lib/db.ts#L1-L499)
- [src/hooks/use-task-executions.ts:1-98](file://src/hooks/use-task-executions.ts#L1-L98)
- [src/app/api/task-executions/route.ts:1-76](file://src/app/api/task-executions/route.ts#L1-L76)
- [src/app/api/cron-engine/route.ts:1-30](file://src/app/api/cron-engine/route.ts#L1-L30)
- [src/app/api/im-channels/route.ts:1-12](file://src/app/api/im-channels/route.ts#L1-L12)
- [src/lib/im/bridge-manager.ts:1-635](file://src/lib/im/bridge-manager.ts#L1-L635)
- [src/app/api/im-events/route.ts:1-66](file://src/app/api/im-events/route.ts#L1-L66)
## 性能考量
- 查询性能
- 对task_executions按(task_id, executed_at DESC)建立索引，满足高频按任务与时间排序场景。
- 分页限制最大500条，避免大结果集导致内存压力。
- 执行性能
- 引擎每60秒扫描一次，避免频繁I/O；使用Set去重避免并发重复执行。
- 执行器创建会话与消息，便于后续分析但需注意消息量增长带来的存储成本。
- IM投递
- BridgeManager实现并发控制与重连策略，防止抖动放大。
- 建议
- 对高频查询增加缓存（如最近N条执行摘要）。
- 对历史数据定期归档或清理，控制表规模。
章节来源
- [src/lib/db.ts:146](file://src/lib/db.ts#L146)
- [src/app/api/task-executions/route.ts:10-11](file://src/app/api/task-executions/route.ts#L10-L11)
- [src/lib/cron/engine.ts:17-28](file://src/lib/cron/engine.ts#L17-L28)
- [src/lib/im/bridge-manager.ts:63-70](file://src/lib/im/bridge-manager.ts#L63-L70)
## 故障排查指南
- 引擎未启动
- 检查是否创建过启用的任务；若无启用任务，引擎不会自动启动。
- 通过POST /api/cron-engine手动启动。
- 任务不执行
- 检查cron表达式格式与当前时间是否匹配。
- 查看task_executions中是否有重复执行记录（并发去重）。
- IM通知失败
- 检查IM通道是否已连接（GET /api/im-channels/[id]/connect）。
- 查看BridgeManager状态与错误日志。
- 执行历史为空
- 确认筛选条件（workspace_id/type/status/limit/offset）。
- 检查任务是否为心跳类型且工作区配置正确。
章节来源
- [src/app/api/cron-engine/route.ts:4-29](file://src/app/api/cron-engine/route.ts#L4-L29)
- [src/lib/cron/engine.ts:108-120](file://src/lib/cron/engine.ts#L108-L120)
- [src/lib/cron/cron-parser.ts:7-20](file://src/lib/cron/cron-parser.ts#L7-L20)
- [src/app/api/im-channels/[id]/connect/route.ts:24-L37](file://src/app/api/im-channels/[id]/connect/route.ts#L24-L37)
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
## 结论
该任务监控系统以数据库为核心，结合定时任务引擎与IM通知，实现了从执行到告警的闭环。前端提供灵活的筛选与分页能力，后端API覆盖任务管理、执行历史查询与引擎控制。通过会话与消息表，系统具备良好的可追溯性与导出能力。建议在生产环境中配合缓存、归档与容量规划，持续优化查询与执行性能。
## 附录
### 监控API接口一览
- 任务管理
- GET /api/cron-tasks?workspace_id=...：列出任务（含全局心跳）
- POST /api/cron-tasks：创建任务
- 执行历史
- GET /api/task-executions?workspace_id=...&type=...&status=...&limit=...&offset=...：查询执行历史
- POST /api/task-executions：上报执行结果（内部使用）
- 引擎控制
- GET /api/cron-engine：查询引擎状态
- POST /api/cron-engine：启动/停止引擎
- IM通道与事件
- GET /api/im-channels：列出IM通道
- POST /api/im-channels/[id]/connect：连接/断开通道
- GET /api/im-events：SSE事件流
- 数据导出与清理
- GET /api/data/export?workspace=...：导出会话与消息
- POST /api/data/clear：清理用户数据（需确认）
章节来源
- [src/app/api/cron-tasks/route.ts:6-21](file://src/app/api/cron-tasks/route.ts#L6-L21)
- [src/app/api/cron-tasks/route.ts:23-52](file://src/app/api/cron-tasks/route.ts#L23-L52)
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
- [src/app/api/task-executions/route.ts:51-75](file://src/app/api/task-executions/route.ts#L51-L75)
- [src/app/api/cron-engine/route.ts:4-29](file://src/app/api/cron-engine/route.ts#L4-L29)
- [src/app/api/im-channels/route.ts:5-11](file://src/app/api/im-channels/route.ts#L5-L11)
- [src/app/api/im-channels/[id]/connect/route.ts:5-L37](file://src/app/api/im-channels/[id]/connect/route.ts#L5-L37)
- [src/app/api/im-events/route.ts:13-65](file://src/app/api/im-events/route.ts#L13-L65)
- [src/app/api/data/export/route.ts:6-37](file://src/app/api/data/export/route.ts#L6-L37)
- [src/app/api/data/clear/route.ts:5-30](file://src/app/api/data/clear/route.ts#L5-L30)
### 告警与通知配置要点
- 心跳任务
- 检查清单文件：HEARTBEAT.md（模板位于templates/init/HEARTBEAT.md）
- 配置项：check_interval、notify_channel
- 通知渠道
- Telegram/Feishu/Discord，优先DM绑定，其次群组绑定
- 实时监控
- SSE推送IM事件，桌面端可实时感知
章节来源
- [src/lib/cron/executor.ts:67-104](file://src/lib/cron/executor.ts#L67-L104)
- [templates/init/HEARTBEAT.md:1-8](file://templates/init/HEARTBEAT.md#L1-L8)
- [src/app/api/im-channels/[id]/connect/route.ts:24-L37](file://src/app/api/im-channels/[id]/connect/route.ts#L24-L37)
- [src/app/api/im-events/route.ts:13-65](file://src/app/api/im-events/route.ts#L13-L65)