# 任务执行器

<cite>
**本文引用的文件**
- [src/app/api/task-executions/route.ts](file://src/app/api/task-executions/route.ts)
- [src/lib/cron/executor.ts](file://src/lib/cron/executor.ts)
- [src/lib/cron/engine.ts](file://src/lib/cron/engine.ts)
- [src/lib/cron/cron-parser.ts](file://src/lib/cron/cron-parser.ts)
- [src/lib/db.ts](file://src/lib/db.ts)
- [src/hooks/use-task-executions.ts](file://src/hooks/use-task-executions.ts)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts)
- [src/components/views/schedule-view.tsx](file://src/components/views/schedule-view.tsx)
- [src/lib/types.ts](file://src/lib/types.ts)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件系统性阐述“任务执行器”的设计与实现，覆盖任务执行流程、会话管理、结果处理、执行上下文与权限控制、安全隔离策略、错误处理与重试机制、超时控制、资源管理与并发限制、性能监控、配置项、调试工具与监控指标等。目标是帮助开发者与运维人员全面理解并高效使用该执行器。

## 项目结构
围绕任务执行器的关键文件组织如下：
- 执行引擎：定时调度与并发控制
- 执行器：具体任务类型分发与执行
- 数据层：SQLite 持久化与索引
- API 层：查询执行记录、触发即时执行
- 前端 Hook 与视图：分页加载、过滤与展示
- 类型定义：统一的数据模型与状态枚举

```mermaid
graph TB
subgraph "前端"
Sched["ScheduleView 组件"]
Hook["useTaskExecutions Hook"]
end
subgraph "后端 API"
APIExe["/api/task-executions 路由"]
APIImmediate["/api/cron-tasks/[id]/execute 路由"]
end
subgraph "执行子系统"
Engine["CronEngine 引擎"]
Parser["Cron 解析器"]
Executor["executeTask 执行器"]
end
subgraph "数据层"
DB["SQLite 数据库"]
Tables["cron_tasks / task_executions / sessions / messages"]
end
Sched --> Hook
Hook --> APIExe
Sched --> APIImmediate
APIImmediate --> Executor
Engine --> Parser
Engine --> Executor
Executor --> DB
APIExe --> DB
APIImmediate --> DB
DB --> Tables
```

图表来源
- [src/lib/cron/engine.ts:16-106](file://src/lib/cron/engine.ts#L16-L106)
- [src/lib/cron/executor.ts:26-47](file://src/lib/cron/executor.ts#L26-L47)
- [src/lib/cron/cron-parser.ts:7-20](file://src/lib/cron/cron-parser.ts#L7-L20)
- [src/lib/db.ts:117-146](file://src/lib/db.ts#L117-L146)
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L11-L39)
- [src/hooks/use-task-executions.ts:30-97](file://src/hooks/use-task-executions.ts#L30-L97)
- [src/components/views/schedule-view.tsx:160-195](file://src/components/views/schedule-view.tsx#L160-L195)

章节来源
- [src/lib/cron/engine.ts:16-106](file://src/lib/cron/engine.ts#L16-L106)
- [src/lib/cron/executor.ts:26-47](file://src/lib/cron/executor.ts#L26-L47)
- [src/lib/cron/cron-parser.ts:7-20](file://src/lib/cron/cron-parser.ts#L7-L20)
- [src/lib/db.ts:117-146](file://src/lib/db.ts#L117-L146)
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L11-L39)
- [src/hooks/use-task-executions.ts:30-97](file://src/hooks/use-task-executions.ts#L30-L97)
- [src/components/views/schedule-view.tsx:160-195](file://src/components/views/schedule-view.tsx#L160-L195)

## 核心组件
- Cron 引擎（CronEngine）
  - 单例调度器，每分钟检查一次启用的任务，基于 cron 表达式匹配决定是否执行。
  - 内置并发控制：正在执行的任务 ID 集合，避免重复执行。
- 执行器（executeTask）
  - 根据任务类型分发到心跳、运行代理、运行技能或自定义提示。
  - 为每次执行创建持久会话，记录消息与结果，并可向 IM 通道通知。
- 数据层（SQLite）
  - 存储 cron 任务、执行记录、会话与消息。
  - 提供索引以优化按任务与时间的查询。
- API 层
  - 查询执行历史（支持按任务、工作区、类型、状态过滤）。
  - 触发即时执行并写入执行记录。
- 前端 Hook 与视图
  - 分页加载执行记录，支持类型与状态过滤。
  - 提供“立即执行”“启动/停止引擎”等交互。

章节来源
- [src/lib/cron/engine.ts:16-106](file://src/lib/cron/engine.ts#L16-L106)
- [src/lib/cron/executor.ts:26-47](file://src/lib/cron/executor.ts#L26-L47)
- [src/lib/db.ts:117-146](file://src/lib/db.ts#L117-L146)
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L11-L39)
- [src/hooks/use-task-executions.ts:30-97](file://src/hooks/use-task-executions.ts#L30-L97)
- [src/components/views/schedule-view.tsx:160-195](file://src/components/views/schedule-view.tsx#L160-L195)

## 架构总览
下图展示了从调度到执行、记录与通知的完整链路。

```mermaid
sequenceDiagram
participant Timer as "CronEngine 定时器"
participant Parser as "Cron 解析器"
participant Exec as "executeTask 执行器"
participant DB as "SQLite 数据库"
participant API as "任务执行 API"
participant UI as "ScheduleView/前端"
Timer->>Parser : "匹配当前时间"
Parser-->>Timer : "匹配结果"
Timer->>Exec : "执行任务"
Exec->>DB : "创建会话/插入消息"
Exec-->>Exec : "生成结果/会话ID"
Exec->>DB : "写入 task_executions"
Exec-->>Timer : "返回状态/结果"
UI->>API : "GET /api/task-executions"
API->>DB : "查询执行记录"
DB-->>API : "返回数据"
API-->>UI : "渲染分页列表"
```

图表来源
- [src/lib/cron/engine.ts:44-105](file://src/lib/cron/engine.ts#L44-L105)
- [src/lib/cron/cron-parser.ts:7-20](file://src/lib/cron/cron-parser.ts#L7-L20)
- [src/lib/cron/executor.ts:202-253](file://src/lib/cron/executor.ts#L202-L253)
- [src/lib/db.ts:135-144](file://src/lib/db.ts#L135-L144)
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
- [src/components/views/schedule-view.tsx:160-195](file://src/components/views/schedule-view.tsx#L160-L195)

## 详细组件分析

### 组件一：Cron 引擎（CronEngine）
- 启动/停止：单例模式，自动检测启用任务后启动；支持手动启停。
- 并发控制：维护“正在执行任务集合”，避免同一任务并发执行。
- 时间匹配：每分钟 tick，调用 cron 解析器判断是否到达执行点。
- 结果记录：无论成功或失败，均写入 task_executions，并更新 cron_tasks 的最近运行信息。
- 一次性任务：当 cron 表达式指定特定日期/月份时，执行后自动禁用。

```mermaid
classDiagram
class CronEngine {
-timer : Interval
-running : boolean
-executingTasks : Set~string~
+start() void
+stop() void
+isRunning() boolean
-tick() Promise~void~
-runTask(task) Promise~void~
}
class CronExecutor {
+executeTask(task) Promise~TaskResult~
}
class CronParser {
+matchesCron(expr, date) boolean
}
CronEngine --> CronExecutor : "调用执行"
CronEngine --> CronParser : "匹配表达式"
```

图表来源
- [src/lib/cron/engine.ts:16-106](file://src/lib/cron/engine.ts#L16-L106)
- [src/lib/cron/executor.ts:26-47](file://src/lib/cron/executor.ts#L26-L47)
- [src/lib/cron/cron-parser.ts:7-20](file://src/lib/cron/cron-parser.ts#L7-L20)

章节来源
- [src/lib/cron/engine.ts:16-106](file://src/lib/cron/engine.ts#L16-L106)

### 组件二：执行器（executeTask）
- 任务类型分发：心跳、运行代理、运行技能、自定义提示。
- 工作区解析：优先使用任务配置的工作区，心跳任务可回退到最近打开的工作区。
- 会话管理：为每次执行创建持久会话，插入用户消息与助手回复，触发会话变更事件。
- IM 通知：根据配置向绑定的 IM 频道发送通知。
- 结果封装：返回状态（ok/alert/error）、结果文本与会话 ID。

```mermaid
flowchart TD
Start(["开始"]) --> Type{"任务类型"}
Type --> |心跳| HB["读取清单并执行"]
Type --> |运行代理| RA["加载代理提示并执行"]
Type --> |运行技能| RS["加载技能提示并执行"]
Type --> |自定义提示| CP["构造系统提示并执行"]
HB --> WS["解析工作区ID"]
RA --> WS
RS --> WS
CP --> WS
WS --> |无| Err["返回错误结果"]
WS --> |有| Run["runAgentTask 创建会话/消息流式输出"]
Run --> IM{"需要通知?"}
IM --> |是| Notify["IM 通知"]
IM --> |否| Done["返回结果"]
Notify --> Done
```

图表来源
- [src/lib/cron/executor.ts:26-196](file://src/lib/cron/executor.ts#L26-L196)
- [src/lib/cron/executor.ts:202-253](file://src/lib/cron/executor.ts#L202-L253)
- [src/lib/cron/executor.ts:261-297](file://src/lib/cron/executor.ts#L261-L297)

章节来源
- [src/lib/cron/executor.ts:26-196](file://src/lib/cron/executor.ts#L26-L196)
- [src/lib/cron/executor.ts:202-253](file://src/lib/cron/executor.ts#L202-L253)
- [src/lib/cron/executor.ts:261-297](file://src/lib/cron/executor.ts#L261-L297)

### 组件三：数据库与表结构
- cron_tasks：存储任务元数据（名称、表达式、动作、类型、代理/技能名、工作区、配置、启用状态、最近运行等）。
- task_executions：存储每次执行的结果、状态、会话 ID、执行时间。
- sessions/messages：为每次执行创建会话与消息，便于在聊天界面查看。
- 索引：task_executions 上按任务与时间倒序索引，提升查询效率。

```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-146](file://src/lib/db.ts#L117-L146)

章节来源
- [src/lib/db.ts:117-146](file://src/lib/db.ts#L117-L146)

### 组件四：API 与前端集成
- 查询执行记录
  - 支持按任务、工作区、类型（心跳/定时）、状态（ok/alert/error）过滤。
  - 支持分页（limit/offset），默认 20，最大 500。
- 即时执行
  - 触发指定任务立即执行，写入执行记录并返回状态与会话 ID。
- 前端 Hook
  - 分页加载执行记录，支持类型与状态筛选，刷新与加载更多。
- 视图交互
  - 提供“启动/停止引擎”“立即执行心跳”等操作，刷新会话列表。

```mermaid
sequenceDiagram
participant UI as "ScheduleView"
participant Hook as "useTaskExecutions"
participant API as "/api/task-executions"
participant DB as "SQLite"
UI->>Hook : "初始化/刷新"
Hook->>API : "GET ?limit&offset&type=status"
API->>DB : "查询 task_executions"
DB-->>API : "返回分页数据"
API-->>Hook : "JSON 列表"
Hook-->>UI : "渲染执行记录"
UI->>API : "POST /api/cron-tasks/ : id/execute"
API->>DB : "写入 task_executions"
API-->>UI : "{status,result,sessionId}"
```

图表来源
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L11-L39)
- [src/hooks/use-task-executions.ts:30-97](file://src/hooks/use-task-executions.ts#L30-L97)
- [src/components/views/schedule-view.tsx:160-195](file://src/components/views/schedule-view.tsx#L160-L195)

章节来源
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L11-L39)
- [src/hooks/use-task-executions.ts:30-97](file://src/hooks/use-task-executions.ts#L30-L97)
- [src/components/views/schedule-view.tsx:160-195](file://src/components/views/schedule-view.tsx#L160-L195)

## 依赖关系分析
- CronEngine 依赖 CronParser 进行时间匹配，依赖 executeTask 执行任务，最终写入 SQLite。
- executeTask 依赖数据库创建会话与消息，依赖 IM 桥接层进行通知。
- API 层依赖数据库进行读写，前端通过 Hook 与 API 交互。
- 类型定义统一了任务、执行记录与状态枚举，保证前后端一致性。

```mermaid
graph LR
Engine["CronEngine"] --> Parser["CronParser"]
Engine --> Executor["executeTask"]
Executor --> DB["SQLite"]
APIExe["/api/task-executions"] --> DB
APIImmediate["/api/cron-tasks/:id/execute"] --> DB
Hook["useTaskExecutions"] --> APIExe
Types["types.ts"] --> Engine
Types --> Executor
Types --> APIExe
Types --> APIImmediate
```

图表来源
- [src/lib/cron/engine.ts:6-9](file://src/lib/cron/engine.ts#L6-L9)
- [src/lib/cron/executor.ts:6-12](file://src/lib/cron/executor.ts#L6-L12)
- [src/lib/cron/cron-parser.ts:7-20](file://src/lib/cron/cron-parser.ts#L7-L20)
- [src/lib/db.ts:117-146](file://src/lib/db.ts#L117-L146)
- [src/app/api/task-executions/route.ts:1-3](file://src/app/api/task-executions/route.ts#L1-L3)
- [src/app/api/cron-tasks/[id]/execute/route.ts](file://src/app/api/cron-tasks/[id]/execute/route.ts#L1-L5)
- [src/hooks/use-task-executions.ts:1-4](file://src/hooks/use-task-executions.ts#L1-L4)
- [src/lib/types.ts:162-211](file://src/lib/types.ts#L162-L211)

章节来源
- [src/lib/types.ts:162-211](file://src/lib/types.ts#L162-L211)

## 性能考量
- 并发控制
  - 引擎内部通过 Set 记录正在执行的任务 ID，避免重复执行，降低资源竞争。
- 查询优化
  - task_executions 对 (task_id, executed_at DESC) 建有索引，支持高效分页与过滤。
- 流式输出
  - 执行器通过流式消费消息块拼接结果，减少一次性内存占用。
- 数据库事务
  - 使用 WAL 模式与外键约束，保证数据一致性与并发安全性。
- 前端分页
  - 默认每页 20 条，最大 500，避免一次性传输过多数据。

章节来源
- [src/lib/cron/engine.ts:19-59](file://src/lib/cron/engine.ts#L19-L59)
- [src/lib/db.ts:22-23](file://src/lib/db.ts#L22-L23)
- [src/lib/db.ts:146-146](file://src/lib/db.ts#L146-L146)
- [src/lib/cron/executor.ts:231-239](file://src/lib/cron/executor.ts#L231-L239)
- [src/hooks/use-task-executions.ts:28-45](file://src/hooks/use-task-executions.ts#L28-L45)

## 故障排查指南
- 无法看到执行记录
  - 检查查询参数：确保 limit/offset/type/status/workspace_id 设置正确。
  - 确认任务存在且已执行，或尝试“立即执行”验证。
- 执行失败
  - 查看 task_executions 中 status 为 error 的记录，定位错误摘要。
  - 检查 cron_tasks 的 last_run_result 是否包含错误信息。
- IM 通知未送达
  - 确认通道已连接且存在绑定；检查 notify_channel 配置。
- 会话未显示
  - 确认执行器已创建会话并插入消息；前端会监听会话变更事件刷新列表。
- 引擎未运行
  - 通过视图提供的“启动/停止”按钮控制；检查是否存在启用的任务。

章节来源
- [src/app/api/task-executions/route.ts:5-49](file://src/app/api/task-executions/route.ts#L5-L49)
- [src/lib/cron/engine.ts:92-104](file://src/lib/cron/engine.ts#L92-L104)
- [src/lib/cron/executor.ts:261-297](file://src/lib/cron/executor.ts#L261-L297)
- [src/components/views/schedule-view.tsx:174-186](file://src/components/views/schedule-view.tsx#L174-L186)

## 结论
任务执行器以“调度-执行-记录-通知”为主线，结合 SQLite 持久化与前端分页展示，提供了稳定、可观测、可扩展的自动化任务能力。通过严格的并发控制、索引优化与清晰的错误处理，满足日常运维与开发场景下的高可用需求。

## 附录

### 执行上下文与权限控制
- 执行上下文
  - 每次执行创建独立会话，包含用户消息与助手回复，便于追溯。
  - 可选 IM 通知，将结果推送到指定频道。
- 权限控制
  - 执行器在创建查询时启用“绕过权限”模式，用于自动化执行场景。
  - 会话级权限模式可在 sessions 表中配置，作为会话级别的覆盖项。

章节来源
- [src/lib/cron/executor.ts:222-229](file://src/lib/cron/executor.ts#L222-L229)
- [src/lib/db.ts:26-34](file://src/lib/db.ts#L26-L34)
- [src/lib/db.ts:395-398](file://src/lib/db.ts#L395-L398)

### 错误处理、重试机制与超时控制
- 错误处理
  - 执行器捕获异常并返回 error 状态；引擎对异常进行记录并写入执行表。
- 重试机制
  - 当前实现未内置自动重试；可通过外部调度或手动再次触发。
- 超时控制
  - 代码未显式设置超时；如需超时保护，建议在上游接入层或执行器中增加超时逻辑。

章节来源
- [src/lib/cron/executor.ts:43-46](file://src/lib/cron/executor.ts#L43-L46)
- [src/lib/cron/engine.ts:92-104](file://src/lib/cron/engine.ts#L92-L104)

### 资源管理与并发限制
- 并发限制
  - 通过 executingTasks 集合避免同一任务并发执行。
- 资源清理
  - 会话与消息随执行结束保留，便于后续审计与复盘。
- 数据库健康
  - WAL 模式与外键约束保障并发与一致性。

章节来源
- [src/lib/cron/engine.ts:19-59](file://src/lib/cron/engine.ts#L19-L59)
- [src/lib/db.ts:22-23](file://src/lib/db.ts#L22-L23)

### 配置选项
- 任务配置（config 字段）
  - notify_channel：通知频道 ID。
  - checklist_path：心跳清单路径（默认 HEARTBEAT.md）。
  - check_interval：心跳检查间隔（字符串形式）。
- 任务类型
  - run-agent：运行指定代理。
  - run-skill：运行指定技能。
  - custom-prompt：自定义提示词。
- 一次性任务
  - 当 cron 表达式指定具体日期/月份时，执行后自动禁用。

章节来源
- [src/lib/cron/executor.ts:14-18](file://src/lib/cron/executor.ts#L14-L18)
- [src/lib/cron/executor.ts:68-78](file://src/lib/cron/executor.ts#L68-L78)
- [src/lib/cron/engine.ts:84-89](file://src/lib/cron/engine.ts#L84-L89)

### 调试工具与监控指标
- 调试工具
  - 前端“立即执行”按钮快速验证任务。
  - “启动/停止引擎”按钮控制调度器生命周期。
  - 执行记录页面按状态与类型过滤，辅助定位问题。
- 监控指标
  - 任务状态分布（ok/alert/error）。
  - 最近运行时间与结果摘要。
  - 会话数量与消息条数（通过 sessions/messages 表统计）。

章节来源
- [src/components/views/schedule-view.tsx:174-186](file://src/components/views/schedule-view.tsx#L174-L186)
- [src/app/api/task-executions/route.ts:34-37](file://src/app/api/task-executions/route.ts#L34-L37)
- [src/lib/db.ts:117-146](file://src/lib/db.ts#L117-L146)