任务与调度
五种任务类型
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 任务依赖与状态工作流
任务之间可以通过 blocks 和 blockedBy 建立依赖关系。被阻塞的任务在其依赖完成之前无法开始执行。
状态工作流遵循严格的转换规则: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。它会在后台分析对话上下文,生成知识摘要,为后续交互提供更精准的上下文支持。
架构
模块关系与设计决策
任务与调度系统架构图
任务管理工具层
五种任务类型 (tasks/)
状态与依赖
Cron 调度 & AutoDream
源码
共 3 个关键代码示例
// 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"
});
}// 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)
);
}
}// 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 记忆文件