# 定时任务调度系统技术方案

> 文档版本：v1.0  
> 文档状态：待实施  
> 编写日期：2026-07-27  
> 适用项目：Mao Agent Workbench

## 1. 需求背景

当前 Agent 执行完全依赖用户通过 WebSocket 主动发送消息触发——系统没有任何自动或定时触发 Agent 执行的机制。当用户提出类似"每天早上帮我检查新股申购"、"每天下午5点给我生成日报"等需求时，Agent 无法实现。

核心限制：
- Agent 只能被动响应，不能主动发起执行
- 没有后台定时任务能力
- 没有消息注入机制

本方案构建一个通用的**定时任务调度系统**，让用户可以通过自然语言对话创建定时任务，系统按 cron 计划自动向固定 Session 注入消息触发 Agent 执行，复用现有 AgentLoop 引擎，执行结果通过现有 Webhook 通知系统推送。

## 2. 需求描述

### 2.1 功能范围

| 模块 | 功能点 | 结论 |
|------|--------|------|
| 任务创建 | 用户通过自然语言对话让 Agent 创建定时任务（Agent 内置工具） | 做 |
| 任务创建 | 通过 UI 表单手动创建定时任务 | 不做，仅对话式 |
| 任务管理 | 管理后台（admin/）定时任务管理页面：列表、启用/禁用、删除 | 做 |
| 任务管理 | 桌面端（desktop/）定时任务侧栏面板：列表、启用/禁用、删除 | 做 |
| 任务管理 | 对话中查看和管理任务（Agent 内置工具：列出、更新、删除） | 做 |
| 触发方式 | Cron 表达式定时触发 | 做 |
| 触发方式 | 固定间隔触发（如每30分钟） | 做 |
| 触发方式 | 外部 Webhook 回调触发 | 不做 |
| 触发方式 | 事件驱动触发（如文件变更、外部系统回调） | 不做 |
| 执行机制 | 向固定 Session 注入用户消息，复用现有 AgentLoop 执行 | 做 |
| 执行机制 | 独立后台执行（不依赖 Session） | 不做 |
| Session 策略 | 每个任务绑定固定 Session，历史上下文可累积 | 做 |
| Session 策略 | 每次触发新建 Session | 不做 |
| Agent 绑定 | 绑定创建任务时的当前 Agent | 做 |
| Agent 绑定 | 用户手动指定 Agent | 不做 |
| 并发控制 | 上次执行未完成时跳过本次触发 | 做 |
| 并发控制 | 取消上次执行，启动新的 | 不做 |
| 并发控制 | 排队等待上次完成 | 不做 |
| 执行超时 | 不限制执行时间，由用户取消、任务正常完成或真实错误终止 | 做 |
| 结果通知 | 复用现有 Webhook 通知系统（钉钉/飞书）+ Session 未读标记 | 做 |
| 结果通知 | 邮件通知 | 不做 |
| 结果通知 | 微信通知 | 不做 |
| Prompt 定义 | Agent 智能解析自然语言，转化为结构化 prompt 和 cron 表达式 | 做 |
| Prompt 定义 | 用户直接输入 cron 表达式和 prompt 文本 | 做（Agent 工具也接受结构化输入作为后备） |
| 权限 | 用户只能管理自己创建的任务 | 做 |
| 权限 | 管理员可管理所有用户的任务 | 做 |

### 2.2 业务规则

1. 定时任务绑定到创建时的 Session 对应的 Agent，执行时复用该 Agent 的 system_prompt、技能、模型配置。
2. 每个任务拥有一个专属 Session，所有执行历史在同一 Session 中累积。
3. 任务触发时，系统检查目标 Session 是否正在执行（phase 为 RUNNING/RESUMING/WAITING_APPROVAL），若是则跳过本次触发，记录跳过日志。
4. 任务触发时，系统向目标 Session 持久化一条 USER 角色消息（内容为任务的 prompt），然后调用 `HarnessService.executeFromEvent()` 启动 Agent 执行。
5. 任务进入 COMPLETED 或 FAILED 终态后，复用现有 Webhook 通知判定逻辑：先尝试 WS 推送，无在线客户端时通过 Webhook 发送。
6. 用户只能管理自己创建的定时任务；管理员可在管理后台查看和管理所有用户的任务。
7. 禁用任务后不再触发，启用后恢复。删除任务为逻辑删除。
8. cron 表达式解析失败时，任务不触发并在日志中记录错误。

### 2.3 用户流程

```
【创建任务】
用户在对话中：  "每天早上9点帮我检查新股申购，有新股就提醒我"
  → Agent 调用 tool_create_scheduled_task({ prompt: "检查今日是否有新股申购...", cron: "0 0 9 * * ?" })
  → 后端创建定时任务 + 专属 Session
  → Agent 回复："已创建定时任务'新股申购检查'，每天早上9点执行"

【任务执行】
Spring Scheduler 扫描到期任务
  → 检查目标 Session 是否空闲
  → 空闲：持久化 USER 消息 → 调用 HarnessService.executeFromEvent()
  → 忙碌：跳过本次，记录日志
  → Agent 执行完毕 → 通知推送（WS 或 Webhook）

【管理任务】
用户在桌面端侧栏：查看任务列表、启用/禁用、删除
用户在管理后台：管理员查看所有任务、管理
用户在对话中："列出我的定时任务" / "取消新股提醒任务"
```

## 3. 当前代码分析

### 3.1 可复用能力

| 能力 | 当前实现 | 复用方式 |
|------|----------|----------|
| Agent 执行引擎 | `HarnessService.executeFromEvent()` → `AgentLoop.execute()` | 直接复用，注入 USER 消息后调用 |
| 定时调度基础设施 | `@EnableScheduling` 已启用，已有 5 个 `@Scheduled` 任务 | 新增 `ScheduledTaskScheduler` 扫描到期任务 |
| Webhook 通知系统 | `TaskCompletionNotificationService` + Outbox 模式 | 任务终态复用相同通知逻辑 |
| Session 管理 | `SessionService` 完整的 CRUD + 状态管理 | 为每个定时任务创建专属 Session |
| Message 持久化 | `SessionService.saveMessage()` | 直接调用持久化 USER 消息 |
| WebSocket 事件推送 | `StreamingWsRegistry` 多设备推送 | 任务执行过程的实时事件自动推送 |
| 内置工具注册 | `@Component` 实现 `Tool` 接口自动注册 | 新增 4 个内置工具 |
| 管理后台路由 | `admin/src/router/index.ts` Vue Router | 新增定时任务管理路由 |
| 桌面端侧栏 | 左侧面板组件体系 | 新增定时任务面板 |

### 3.2 关键代码路径

| 组件 | 文件路径 |
|------|----------|
| Agent 执行入口 | `backend/.../harness/core/HarnessService.java` |
| Agent 循环 | `backend/.../harness/core/AgentLoop.java` |
| WS 消息处理 | `backend/.../session/ws/StreamingWsHandler.java` |
| WS 连接注册 | `backend/.../session/ws/StreamingWsRegistry.java` |
| 工具接口 | `backend/.../harness/tool/Tool.java` |
| 工具实现目录 | `backend/.../harness/tool/impl/` |
| 现有 Scheduler 示例 | `backend/.../session/service/StaleSessionSweepScheduler.java` |
| Webhook 通知 | `backend/.../notification/task/` |
| Flyway 迁移 | `backend/src/main/resources/db/migration/` (当前最新 V060) |
| 管理后台路由 | `admin/src/router/index.ts` |
| 管理后台视图 | `admin/src/views/` |
| 桌面端 composables | `desktop/src/composables/` |
| 桌面端组件 | `desktop/src/components/` |

## 4. 整体设计

### 4.1 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                        用户层                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐   │
│  │ 桌面端侧栏    │  │ 管理后台页面   │  │ 对话式交互        │   │
│  │ (定时任务面板) │  │ (任务管理)    │  │ (Agent 内置工具)  │   │
│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘   │
│         │                 │                    │             │
│         ▼                 ▼                    ▼             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │              REST API / WebSocket                     │   │
│  └──────────────────────────┬───────────────────────────┘   │
└─────────────────────────────┼───────────────────────────────┘
                              │
┌─────────────────────────────┼───────────────────────────────┐
│                        后端核心                              │
│                              │                               │
│  ┌───────────────────────────▼───────────────────────────┐  │
│  │           ScheduledTaskScheduler (每分钟扫描)           │  │
│  │     ┌─────────────────────────────────────────┐       │  │
│  │     │ 1. 查询 enabled=true 且 next_fire_time  │       │  │
│  │     │    <= now 的任务                         │       │  │
│  │     │ 2. 检查目标 Session 是否空闲             │       │  │
│  │     │ 3. 空闲 → 持久化 USER 消息 + 触发执行    │       │  │
│  │     │ 4. 忙碌 → 跳过，计算下次触发时间          │       │  │
│  │     │ 5. 更新 next_fire_time                  │       │  │
│  │     └─────────────────────────────────────────┘       │  │
│  └───────────────────────┬───────────────────────────────┘  │
│                          │                                   │
│                          ▼                                   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │         HarnessService.executeFromEvent()             │   │
│  │              (现有 AgentLoop 引擎)                     │   │
│  └───────────────────────┬──────────────────────────────┘   │
│                          │                                   │
│                          ▼                                   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │     TaskCompletionNotificationService (现有)          │   │
│  │     WS 推送 / Webhook (钉钉/飞书) / 未读标记           │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                    数据层                              │   │
│  │     scheduled_task 表 + session 表 + message 表       │   │
│  └──────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────┘
```

### 4.2 核心数据模型

**scheduled_task 表：**

| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT AUTO_INCREMENT PK | 主键 |
| user_id | BIGINT NOT NULL | 创建者用户 ID |
| agent_id | BIGINT NOT NULL | 绑定的 Agent ID |
| session_id | BIGINT NOT NULL | 专属 Session ID |
| name | VARCHAR(200) NOT NULL | 任务名称 |
| prompt | TEXT NOT NULL | 触发时注入的 prompt 内容 |
| cron_expression | VARCHAR(100) NOT NULL | Cron 表达式（Spring cron 格式：秒 分 时 日 月 周） |
| status | VARCHAR(20) NOT NULL DEFAULT 'ACTIVE' | 状态：ACTIVE / PAUSED / DELETED |
| last_fire_time | DATETIME | 上次触发时间 |
| last_execution_status | VARCHAR(20) | 上次执行状态：COMPLETED / FAILED / SKIPPED |
| next_fire_time | DATETIME | 下次触发时间（预计算，用于快速查询） |
| fire_count | INT DEFAULT 0 | 累计触发次数 |
| created_at | DATETIME NOT NULL | 创建时间 |
| updated_at | DATETIME NOT NULL | 更新时间 |
| deleted | TINYINT DEFAULT 0 | 逻辑删除标记 |

### 4.3 Cron 表达式格式

使用 Spring `CronExpression`（6 位：秒 分 时 日 月 周），支持：

| 用户意图 | Cron 表达式 | 说明 |
|----------|-------------|------|
| 每天早上 9 点 | `0 0 9 * * ?` | 标准 cron |
| 每个工作日早上 9 点 | `0 0 9 * * MON-FRI` | 周一到周五 |
| 每 30 分钟 | `0 */30 * * * ?` | 固定间隔 |
| 每周一上午 10 点 | `0 0 10 * * MON` | 指定星期 |
| 每月 1 号上午 9 点 | `0 0 9 1 * ?` | 指定日期 |

## 5. 实现步骤

### 5.1 数据库迁移

**文件**：`backend/src/main/resources/db/migration/V061__scheduled_task.sql`

```sql
CREATE TABLE scheduled_task (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    user_id         BIGINT       NOT NULL,
    agent_id        BIGINT       NOT NULL,
    session_id      BIGINT       NOT NULL,
    name            VARCHAR(200) NOT NULL,
    prompt          TEXT         NOT NULL,
    cron_expression VARCHAR(100) NOT NULL,
    status          VARCHAR(20)  NOT NULL DEFAULT 'ACTIVE',
    last_fire_time  DATETIME              DEFAULT NULL,
    last_execution_status VARCHAR(20)     DEFAULT NULL,
    next_fire_time  DATETIME              DEFAULT NULL,
    fire_count      INT          NOT NULL DEFAULT 0,
    created_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted         TINYINT      NOT NULL DEFAULT 0,
    INDEX idx_user_id (user_id),
    INDEX idx_status_next_fire (status, next_fire_time, deleted)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
```

### 5.2 后端 — 实体与 Mapper

**新增文件：**

| 文件 | 说明 |
|------|------|
| `backend/.../schedule/entity/ScheduledTask.java` | 实体类，`@TableName("scheduled_task")` |
| `backend/.../schedule/mapper/ScheduledTaskMapper.java` | MyBatis-Plus Mapper 接口 |

**ScheduledTask 关键字段映射：**

```java
@Data
@TableName("scheduled_task")
public class ScheduledTask {
    @TableId(type = IdType.AUTO)
    private Long id;
    private Long userId;
    private Long agentId;
    private Long sessionId;
    private String name;
    private String prompt;
    private String cronExpression;
    private String status;       // ACTIVE / PAUSED
    private LocalDateTime lastFireTime;
    private String lastExecutionStatus;  // COMPLETED / FAILED / SKIPPED
    private LocalDateTime nextFireTime;
    private Integer fireCount;
    private LocalDateTime createdAt;
    private LocalDateTime updatedAt;
    @TableLogic
    private Integer deleted;
}
```

### 5.3 后端 — Service 层

**新增文件：**

| 文件 | 说明 |
|------|------|
| `backend/.../schedule/service/ScheduledTaskService.java` | 核心业务逻辑 |

**ScheduledTaskService 职责：**

```java
@Service
@RequiredArgsConstructor
public class ScheduledTaskService {

    // 创建定时任务
    // 1. 创建专属 Session（title=任务名, agent_id=绑定Agent, session_type=NORMAL）
    // 2. 计算 next_fire_time
    // 3. 持久化 scheduled_task 记录
    public ScheduledTask createTask(Long userId, Long agentId, String name,
                                     String prompt, String cronExpression);

    // 更新任务（名称、prompt、cron、启用/禁用）
    // 若 cron 变更，重新计算 next_fire_time
    public ScheduledTask updateTask(Long taskId, Long userId, ...);

    // 删除任务（逻辑删除）
    public void deleteTask(Long taskId, Long userId);

    // 查询用户的任务列表
    public List<ScheduledTask> listByUser(Long userId);

    // 查询所有任务（管理员用）
    public Page<ScheduledTask> listAll(PageParams params);

    // 执行定时任务（由 Scheduler 调用）
    // 1. 检查 Session 是否空闲
    // 2. 空闲 → 持久化 USER 消息 → 调用 HarnessService.executeFromEvent()
    // 3. 更新 last_fire_time、fire_count、next_fire_time
    public void executeTask(ScheduledTask task);

    // 计算下次触发时间
    public LocalDateTime calculateNextFireTime(String cronExpression);
}
```

### 5.4 后端 — Scheduler

**新增文件：**

| 文件 | 说明 |
|------|------|
| `backend/.../schedule/scheduler/ScheduledTaskScheduler.java` | 定时扫描与触发 |

**核心逻辑：**

```java
@Component
@RequiredArgsConstructor
@Slf4j
public class ScheduledTaskScheduler {

    private final ScheduledTaskService scheduledTaskService;
    private final ScheduledTaskMapper scheduledTaskMapper;

    // 每分钟扫描一次
    @Scheduled(fixedDelay = 60_000)
    public void scanAndExecute() {
        LocalDateTime now = LocalDateTime.now();

        // 查询：status=ACTIVE AND next_fire_time <= now AND deleted=0
        List<ScheduledTask> dueTasks = scheduledTaskMapper.selectList(
            new LambdaQueryWrapper<ScheduledTask>()
                .eq(ScheduledTask::getStatus, "ACTIVE")
                .le(ScheduledTask::getNextFireTime, now)
                .eq(ScheduledTask::getDeleted, 0)
        );

        for (ScheduledTask task : dueTasks) {
            try {
                scheduledTaskService.executeTask(task);
            } catch (Exception e) {
                log.error("定时任务执行失败: taskId={}", task.getId(), e);
                // 更新状态为 FAILED，计算下次触发时间
            }
        }
    }
}
```

### 5.5 后端 — Agent 内置工具

**新增 4 个工具，放置在 `backend/.../harness/tool/impl/` 目录：**

| 工具文件 | 工具名 | 说明 |
|----------|--------|------|
| `CreateScheduledTaskTool.java` | `create_scheduled_task` | 创建定时任务 |
| `ListScheduledTasksTool.java` | `list_scheduled_tasks` | 列出用户的定时任务 |
| `UpdateScheduledTaskTool.java` | `update_scheduled_task` | 更新任务（名称、prompt、cron、启用/禁用） |
| `DeleteScheduledTaskTool.java` | `delete_scheduled_task` | 删除定时任务 |

**CreateScheduledTaskTool 示例结构：**

```java
@Component
@RequiredArgsConstructor
public class CreateScheduledTaskTool implements Tool {

    private final ScheduledTaskService scheduledTaskService;

    @Override
    public String getName() { return "create_scheduled_task"; }

    @Override
    public String getDescription() {
        return "创建定时任务。任务将按照指定的 cron 计划自动执行。" +
               "例如：每天早上9点检查新股申购、每小时检查服务器状态等。";
    }

    @Override
    public Map<String, Object> getInputSchema() {
        // 参数：name(任务名), prompt(执行内容), cron_expression(Spring cron 6位)
        return Map.of(
            "type", "object",
            "properties", Map.of(
                "name", Map.of("type", "string", "description", "任务名称"),
                "prompt", Map.of("type", "string", "description", "任务触发时执行的 prompt 内容"),
                "cron_expression", Map.of("type", "string",
                    "description", "Spring cron 表达式（6位：秒 分 时 日 月 周），如 '0 0 9 * * ?' 表示每天9点")
            ),
            "required", List.of("name", "prompt", "cron_expression")
        );
    }

    @Override
    public String execute(String arguments, Long sessionId, Long userId, String workspace) {
        // 1. 解析参数
        // 2. 从 sessionId 获取 agent_id
        // 3. 调用 scheduledTaskService.createTask()
        // 4. 返回任务创建结果 JSON
    }
}
```

**工具行为指南（toolPrompt）关键内容：**

```markdown
## create_scheduled_task 使用指南

当用户希望创建定时自动执行的任务时使用此工具。

### cron 表达式规则
- 格式：秒 分 时 日 月 周（Spring 6位 cron）
- "每天早上9点" → "0 0 9 * * ?"
- "每30分钟" → "0 */30 * * * ?"
- "工作日早上9点" → "0 0 9 * * MON-FRI"

### prompt 编写要求
- prompt 应该是完整的、自包含的指令
- 应包含足够的上下文，因为 Agent 执行时只有任务历史，没有用户实时对话
- 示例："检查今日是否有新股可申购。如果有，列出新股代码、名称、申购价格和上限；如果没有，简要说明即可。"
```

### 5.6 后端 — REST API

**新增文件：**

| 文件 | 说明 |
|------|------|
| `backend/.../schedule/controller/ScheduledTaskController.java` | REST 接口 |

**接口定义：**

| 方法 | 路径 | 说明 | 权限 |
|------|------|------|------|
| GET | `/api/v1/scheduled-tasks` | 查询当前用户的任务列表 | 登录用户 |
| GET | `/api/v1/scheduled-tasks/all` | 查询所有任务（分页） | 管理员 |
| PUT | `/api/v1/scheduled-tasks/{id}` | 更新任务（名称、prompt、cron、状态） | 任务创建者 |
| DELETE | `/api/v1/scheduled-tasks/{id}` | 删除任务 | 任务创建者 |

> 注：创建任务通过 Agent 工具（`create_scheduled_task`）完成，不提供 REST 创建接口。
> 注：管理员接口需添加 `@RequirePermission` 注解。

### 5.7 管理后台 — 定时任务管理页面

**新增文件：**

| 文件 | 说明 |
|------|------|
| `admin/src/views/scheduled-tasks/index.vue` | 定时任务管理页面 |

**页面功能：**

- 任务列表表格：名称、创建者、Agent、Cron 表达式、状态、上次执行状态、上次触发时间、下次触发时间、触发次数
- 操作列：启用/禁用开关、删除按钮
- 支持分页

**路由配置：**

在 `admin/src/router/index.ts` 中新增：

```typescript
{
  path: 'scheduled-tasks',
  name: 'ScheduledTasks',
  component: () => import('@/views/scheduled-tasks/index.vue'),
  meta: { title: '定时任务', icon: 'Clock' }
}
```

### 5.8 桌面端 — 定时任务侧栏面板

**新增文件：**

| 文件 | 说明 |
|------|------|
| `desktop/src/components/ScheduledTaskPanel.vue` | 定时任务面板组件 |
| `desktop/src/composables/useScheduledTasks.ts` | 定时任务数据管理 composable |

**面板功能：**

- 任务列表：名称、状态（Active/Paused）、下次触发时间
- 操作：启用/禁用切换、删除
- 空状态提示："还没有定时任务，试试对 Agent 说'每天早上9点帮我检查新股'"

**集成位置：**

在桌面端左侧面板或设置区域添加入口，点击后展开定时任务面板。

### 5.9 消息注入与执行流程

**核心执行流程（ScheduledTaskService.executeTask）：**

```
executeTask(task)
  │
  ├─ 1. 查询 Session 当前 phase
  │     └─ 若 phase 为 RUNNING/RESUMING/WAITING_APPROVAL
  │          → 标记 last_execution_status = 'SKIPPED'
  │          → 计算 next_fire_time
  │          → return
  │
  ├─ 2. 持久化 USER 消息
  │     └─ sessionService.saveMessage(sessionId, "USER", task.prompt, ...)
  │
  ├─ 3. 更新 Session 状态
  │     └─ sessionService.updatePhase(sessionId, "RUNNING")
  │
  ├─ 4. 创建 WsStreamingEventListener（用于推送执行事件）
  │
  ├─ 5. 提交到 agentExecutor 线程池
  │     └─ agentExecutor.submit(() -> {
  │          harnessService.executeFromEvent(sessionId, eventId, listener, cancelFlag)
  │        })
  │
  ├─ 6. 更新任务状态
  │     ├─ last_fire_time = now
  │     ├─ fire_count++
  │     ├─ next_fire_time = calculateNextFireTime(cron)
  │     └─ last_execution_status = 根据执行结果设置
  │
  └─ 7. 通知判定
        └─ 复用现有 TaskCompletionNotificationService 逻辑
```

## 6. 落地清单

### 6.1 后端

| 序号 | 任务 | 文件 | 依赖 |
|------|------|------|------|
| B1 | 创建数据库迁移脚本 | `V061__scheduled_task.sql` | 无 |
| B2 | 创建实体类 | `schedule/entity/ScheduledTask.java` | B1 |
| B3 | 创建 Mapper | `schedule/mapper/ScheduledTaskMapper.java` | B2 |
| B4 | 创建 Service | `schedule/service/ScheduledTaskService.java` | B2, B3 |
| B5 | 创建 Scheduler | `schedule/scheduler/ScheduledTaskScheduler.java` | B4 |
| B6 | 创建内置工具 `create_scheduled_task` | `harness/tool/impl/CreateScheduledTaskTool.java` | B4 |
| B7 | 创建内置工具 `list_scheduled_tasks` | `harness/tool/impl/ListScheduledTasksTool.java` | B4 |
| B8 | 创建内置工具 `update_scheduled_task` | `harness/tool/impl/UpdateScheduledTaskTool.java` | B4 |
| B9 | 创建内置工具 `delete_scheduled_task` | `harness/tool/impl/DeleteScheduledTaskTool.java` | B4 |
| B10 | 创建 REST Controller | `schedule/controller/ScheduledTaskController.java` | B4 |
| B11 | 编写单元测试 | `schedule/service/ScheduledTaskServiceTest.java` 等 | B4-B10 |

### 6.2 管理后台

| 序号 | 任务 | 文件 | 依赖 |
|------|------|------|------|
| A1 | 创建定时任务管理页面 | `admin/src/views/scheduled-tasks/index.vue` | B10 |
| A2 | 注册路由 | `admin/src/router/index.ts` 修改 | A1 |

### 6.3 桌面端

| 序号 | 任务 | 文件 | 依赖 |
|------|------|------|------|
| D1 | 创建定时任务 composable | `desktop/src/composables/useScheduledTasks.ts` | B10 |
| D2 | 创建定时任务面板组件 | `desktop/src/components/ScheduledTaskPanel.vue` | D1 |
| D3 | 集成到桌面端布局 | 相关布局组件修改 | D2 |
| D4 | 更新 package.json version | `desktop/package.json` | 全部 |

### 6.4 执行顺序

```
Phase 1 — 后端基础（B1 → B2 → B3 → B4）
Phase 2 — 后端核心（B5, B6, B7, B8, B9, B10 并行，均依赖 B4）
Phase 3 — 后端测试（B11）
Phase 4 — 管理后台（A1 → A2，依赖 B10）
Phase 5 — 桌面端（D1 → D2 → D3 → D4，依赖 B10）
```

## 7. 风险与注意事项

| 风险 | 说明 | 应对 |
|------|------|------|
| Session 消息膨胀 | 定时任务长期运行后 Session 消息量过大 | 现有 CompactionService 自动压缩机制兜底 |
| Scheduler 扫描性能 | 任务量大时每分钟全表扫描 | `idx_status_next_fire` 索引保证查询效率，仅查询 `next_fire_time <= now` 的记录 |
| 线程池饱和 | 大量定时任务同时触发 | 复用现有 `agentExecutor` 线程池，已有队列机制；跳过策略也避免并发堆积 |
| 时区问题 | Cron 触发时间与用户期望不一致 | 使用系统默认时区（Asia/Shanghai），后续可扩展用户级时区设置 |
| LLM 费用 | 定时任务频繁调用 LLM 产生费用 | 用户自行控制任务频率；管理员可在管理后台监控触发次数 |