Claude Code 源码解析
返回目录
扩展与集成16

任务与调度

五种任务类型

核心洞察

DreamTask 在后台静默执行,实现了 "AI 做梦" 式的异步知识整理

学习

概念讲解与核心设计分析

16.1 五种任务类型

Claude Code 的 tasks/ 目录定义了五种核心任务类型,覆盖从主线程到后台处理的全部场景:

  • LocalMainSessionTask — 主线程任务,运行在用户当前的 REPL 会话中。这是最常见的任务类型,直接响应用户输入并产生可见输出
  • LocalAgentTask — 基于代理的任务,拥有独立的上下文窗口和工具集。通常由 AgentTool 创建,用于处理需要隔离执行环境的子任务
  • LocalShellTask — 后台 Shell 任务,在独立的终端进程中执行长时间运行的命令(如构建、测试),不阻塞主会话
  • InProcessTeammateTask — 进程内队友任务,与多代理 Swarm 系统配合使用。每个队友作为独立的异步任务在同一进程中运行
  • DreamTask — 后台"梦境"任务,用于 AI 异步知识整合。当用户空闲时,系统会启动 DreamTask 对对话历史进行反思和总结

16.2 任务管理工具

Claude Code 提供了一套完整的任务管理工具,通过 ScheduleCronTool/ 和任务 CRUD 工具实现任务的全生命周期管理:

  • TaskCreateTool — 创建新任务,接受 subject(简短标题)和 description(详细描述)参数。可选 activeForm 字段用于在进度条中显示
  • TaskUpdateTool — 更新任务状态和依赖关系。支持修改 status、subject、description、owner,以及通过 addBlocks/addBlockedBy 设置依赖
  • TaskGetTool — 按 ID 获取任务详情,包括完整描述、状态、依赖关系
  • TaskListTool — 列出所有任务的摘要视图,包含 id、subject、status、owner、blockedBy
  • TaskStopTool — 停止正在运行的任务,释放其占用的资源

16.3 任务依赖与状态工作流

任务之间可以通过 blocksblockedBy 建立依赖关系。被阻塞的任务在其依赖完成之前无法开始执行。

状态工作流遵循严格的转换规则:pending → in_progress → completed。任何阶段都可以转为 deleted 状态。只有当任务确实完成所有工作(测试通过、实现完整)时才应标记为 completed。

16.4 Cron 调度系统

ScheduleCronTool/ 提供基于 Cron 表达式的定时调度:

  • CronCreateTool — 创建定时任务,使用标准 5 字段 Cron 表达式(分 时 日 月 周),在用户本地时区执行
  • CronDeleteTool — 根据 Job ID 取消已创建的定时任务
  • CronListTool — 列出所有活跃的定时任务

Cron 任务支持两种模式:recurring(循环执行,7 天后自动过期)和 one-shot(单次执行后自动删除)。持久性方面分为 durable(写入 .claude/scheduled_tasks.json,跨会话保持)和 session-only(仅在当前会话存活)。

16.5 DreamTask 与自动梦境

services/autoDream/ 实现了 AI "做梦"机制:

  • consolidationPrompt — 梦境整合提示词,指导 AI 对对话历史进行反思、提取关键知识点和决策模式
  • consolidationLock — 梦境锁,防止多个梦境任务同时执行造成资源竞争

当用户空闲且会话达到一定长度时,系统自动启动 DreamTask。它会在后台分析对话上下文,生成知识摘要,为后续交互提供更精准的上下文支持。

架构

模块关系与设计决策

任务与调度系统架构图

任务管理工具层

TaskCreateTool
TaskUpdateTool
TaskGetTool
TaskListTool
TaskStopTool

五种任务类型 (tasks/)

LocalMainSession
主线程
LocalAgent
代理隔离
LocalShell
后台命令
InProcessTeammate
进程内队友
DreamTask
异步梦境

状态与依赖

pending
in_progress
completed
blocks / blockedBy 依赖关系控制执行顺序

Cron 调度 & AutoDream

ScheduleCronTool
Create / Delete / List
recurring | one-shot
durable | session-only
services/autoDream
consolidationPrompt
consolidationLock
后台知识整合

源码

3 个关键代码示例

01
任务创建与依赖管理
TypeScript
// TaskCreateTool: 创建任务并设置依赖
interface TaskCreateInput {
  subject: string;       // 简短标题(祈使句式)
  description: string;   // 详细描述
  activeForm?: string;   // 进行中时的显示文本
  metadata?: Record<string, unknown>;
}

interface Task {
  id: string;
  subject: string;
  description: string;
  status: "pending" | "in_progress" | "completed" | "deleted";
  owner?: string;
  blocks: string[];      // 此任务完成后才能开始的任务
  blockedBy: string[];   // 此任务依赖的前置任务
  activeForm?: string;
}

// 创建一组有依赖关系的任务
async function createTaskPipeline(
  store: TaskStore
): Promise<void> {
  // 任务 1: 基础设施
  const t1 = store.create({
    subject: "搭建数据库 Schema",
    description: "创建用户表、权限表和会话表",
    activeForm: "搭建数据库 Schema 中"
  });

  // 任务 2: 依赖任务 1
  const t2 = store.create({
    subject: "实现 API 端点",
    description: "基于 Schema 实现 CRUD API"
  });
  store.update(t2.id, {
    addBlockedBy: [t1.id]
  });

  // 任务 3: 依赖任务 2
  const t3 = store.create({
    subject: "编写集成测试",
    description: "测试所有 API 端点"
  });
  store.update(t3.id, {
    addBlockedBy: [t2.id]
  });

  // 开始执行任务 1
  store.update(t1.id, {
    status: "in_progress"
  });
}
02
Cron 调度系统
TypeScript
// CronCreateTool: 标准 5 字段 Cron 调度
interface CronCreateInput {
  cron: string;          // "M H DoM Mon DoW"
  prompt: string;        // 触发时执行的提示词
  recurring?: boolean;   // 默认 true,false 为单次
  durable?: boolean;     // 默认 false,true 持久化到磁盘
}

interface CronJob {
  id: string;
  cron: string;
  prompt: string;
  recurring: boolean;
  durable: boolean;
  nextFireTime: Date;
  createdAt: Date;
  expiresAt: Date;       // 循环任务 7 天后过期
}

// 调度器核心逻辑
class CronScheduler {
  private jobs: Map<string, CronJob> = new Map();
  private readonly STORAGE_PATH =
    ".claude/scheduled_tasks.json";

  create(input: CronCreateInput): CronJob {
    const job: CronJob = {
      id: generateId(),
      cron: input.cron,
      prompt: input.prompt,
      recurring: input.recurring !== false,
      durable: input.durable || false,
      nextFireTime: computeNextFire(input.cron),
      createdAt: new Date(),
      expiresAt: new Date(
        Date.now() + 7 * 24 * 60 * 60 * 1000
      )
    };

    this.jobs.set(job.id, job);

    // 持久化到磁盘
    if (job.durable) {
      this.persistToDisk();
    }
    return job;
  }

  // REPL 空闲时检查并触发到期任务
  async tick(): Promise<void> {
    const now = new Date();
    for (const [id, job] of this.jobs) {
      // 过期检查
      if (now > job.expiresAt) {
        this.jobs.delete(id);
        continue;
      }
      // 触发检查
      if (now >= job.nextFireTime) {
        await this.fire(job);
        if (job.recurring) {
          job.nextFireTime = computeNextFire(job.cron);
        } else {
          this.jobs.delete(id);
        }
      }
    }
  }

  private async fire(job: CronJob): Promise<void> {
    // 将 prompt 加入 REPL 消息队列
    enqueuePrompt(job.prompt);
  }

  private persistToDisk(): void {
    const durableJobs = [...this.jobs.values()]
      .filter(j => j.durable);
    writeFileSync(
      this.STORAGE_PATH,
      JSON.stringify(durableJobs, null, 2)
    );
  }
}
03
DreamTask 与自动梦境整合
TypeScript
// services/autoDream: AI 梦境知识整合
const consolidationPrompt = [
  "回顾本次对话的完整历史。",
  "提取关键技术决策和发现。",
  "识别用户的编码偏好和风格。",
  "总结项目结构和架构特征。",
  "生成简洁的知识摘要用于后续参考。"
].join("\n");

// 梦境锁:防止并发执行
class ConsolidationLock {
  private locked = false;
  private lockHolder: string | null = null;

  acquire(taskId: string): boolean {
    if (this.locked) return false;
    this.locked = true;
    this.lockHolder = taskId;
    return true;
  }

  release(taskId: string): void {
    if (this.lockHolder === taskId) {
      this.locked = false;
      this.lockHolder = null;
    }
  }
}

// DreamTask: 后台知识整合任务
class DreamTask {
  private lock = new ConsolidationLock();

  async execute(
    conversationHistory: Message[]
  ): Promise<DreamResult | null> {
    const taskId = "dream-" + Date.now();

    // 尝试获取锁
    if (!this.lock.acquire(taskId)) {
      return null; // 已有梦境任务在执行
    }

    try {
      // 构建整合上下文
      const context = conversationHistory
        .filter(m => m.role !== "system")
        .map(m => m.role + ": " + summarize(m.content))
        .join("\n");

      // 执行 AI 反思
      const result = await callModel({
        system: consolidationPrompt,
        messages: [
          { role: "user", content: context }
        ]
      });

      // 保存知识摘要
      return {
        summary: result.content,
        timestamp: Date.now(),
        messageCount: conversationHistory.length
      };
    } finally {
      this.lock.release(taskId);
    }
  }
}

// 自动触发条件
function shouldStartDream(
  state: AppState
): boolean {
  const idleTime = Date.now() - state.lastUserInput;
  const messageCount = state.conversationLength;
  // 空闲 2 分钟且对话超过 20 条消息
  return idleTime > 120_000 && messageCount > 20;
}

互动

步进式流程演示

互动演示

任务调度交互式演练

Step 1: 创建任务流水线

用户要求实现一个完整功能。Claude Code 自动创建三个有序任务:数据库 Schema → API 实现 → 集成测试。通过 blockedBy 建立依赖,确保执行顺序。

Task #1 [pending] "搭建数据库 Schema"
Task #2 [pending] "实现 API 端点" (blockedBy: #1)
Task #3 [pending] "编写集成测试" (blockedBy: #2)

Step 2: 逐步执行与状态流转

Task #1 开始执行,状态变为 in_progress。完成后标记为 completed,Task #2 自动解除阻塞变为可执行状态。

Task #1 [completed] ✔
Task #2 [in_progress] → 阻塞解除,开始执行
Task #3 [pending] (blockedBy: #2) 等待中...

Step 3: 设置 Cron 定时任务

用户请求"每天早上 9 点检查部署状态"。CronCreateTool 创建一个 durable 循环任务,写入磁盘持久化,跨会话保持运行。

CronJob {
  id: "cj_abc123",
  cron: "3 9 * * *",      // 每天 9:03(避开整点)
  prompt: "检查所有服务的部署状态并汇报",
  recurring: true,
  durable: true,           // 持久化到磁盘
  expiresAt: "7天后"       // 自动过期
}

Step 4: 后台梦境整合

用户空闲 2 分钟后,DreamTask 自动启动。在后台分析对话历史,提取知识要点,生成知识摘要。下次用户提问时,这些摘要提供更精准的上下文。

DreamTask 启动:
  - 分析 35 条对话消息
  - 提取 8 个关键技术决策
  - 识别用户偏好: TypeScript, React, 函数式风格
  - 生成知识摘要 (512 tokens)
  - 写入 CLAUDE.md 记忆文件

相关源文件

tasks/tools/ScheduleCronTool/services/autoDream/