模块: tasks | Claude Code 源码分析

本章总览

src/tasks/（14 个文件，约 3310 行）是 Claude Code 的「后台任务层」：把 Bash 子进程、本地子 Agent、远程 CCR 会话、in-process teammate、Dream 记忆整理等长运行工作统一注册到 AppState.tasks，并通过 footer pill、Shift+Down 对话框、XML task-notification 与 SDK 事件对外暴露状态。根目录 Task.ts 定义 Task 接口与 createTaskStateBase；tasks.ts 维护 type→Task 实现映射；utils/task/framework.ts 提供 registerTask / updateTaskState。

总览图

渲染图表中…

学完本章你应该能

建立 Task 接口 → 具体 Task 实现 → AppState.tasks → UI pill 的阅读顺序
区分 local_agent / local_bash / remote_agent / in_process_teammate / dream 等 type 字段
理解 isBackgroundTask 与 isBackgrounded 如何决定 footer pill 可见性
能在源码树中从本页跳转到子章节与高亮文件

建议学习步骤

浏览下方子章节导航表，选择入口主题
点击 SourceTree 中的 tasks/LocalAgentTask/ 跳转到对应讲解
建议顺序：local-agent-task → remote-agent-task → shell-workflow-tasks → dream-monitor-tasks

模块在架构中的位置

tasks 是 src/ 下的一级目录，共 14 个文件、3,310 行。建议结合「系统架构」章节理解它与其他层的调用关系。

模块 UML 图表

后台 Task 生命周期

渲染图表中…

概览

指标	数值
行数	3,310
文件	14

子章节导航

子章节	主题	核心路径
local-agent-task	本地子 Agent、主会话后台化	`LocalAgentTask/`、`LocalMainSessionTask.ts`
remote-agent-task	远程 CCR 会话、Ultraplan、Ultrareview	`RemoteAgentTask/`、`InProcessTeammateTask/`
shell-workflow-tasks	后台 Bash、Monitor、stopTask	`LocalShellTask/`、`LocalWorkflowTask/`、`stopTask.ts`
dream-monitor-tasks	Dream 记忆整理、Monitor MCP、pill 文案	`DreamTask/`、`MonitorMcpTask/`、`pillLabel.ts`

架构分层

Claude Code 任务系统可概括为四层：

Task.ts           — Task 接口、TaskStateBase、createTaskStateBase
tasks.ts          — getTaskByType、ALL_TASKS 注册表
tasks/*Task/      — 各任务类型实现（kill、spawn、complete）
utils/task/       — registerTask、updateTaskState、diskOutput
AppState.tasks    — Record<taskId, TaskState> 运行时状态
pillLabel.ts      — footer pill 文案与 CTA 判定
stopTask.ts       — TaskStopTool 与 SDK stop_task 共享逻辑

关键边界：

types.ts 定义 TaskState 联合类型与 isBackgroundTask 谓词，不 import React
LocalShellTask/guards.ts 与 killShellTasks.ts 从 TSX 拆出，避免 runAgent 拉入 Ink
LocalMainSessionTask.ts 复用 LocalAgentTaskState，agentType='main-session' 区分主会话后台化
RemoteAgentTask 通过 pollRemoteSessionEvents 增量拉取 CCR 事件，sidecar 持久化 --resume 恢复

SourceTree 扫描 src/tasks/ 目录；根目录 Task.ts、tasks.ts 在 highlightFiles 中以相对 src/ 的路径引用。

任务类型一览

type 字段	实现目录	典型触发场景
`local_agent`	LocalAgentTask/	AgentTool async、Ctrl+B 后台主会话
`local_bash`	LocalShellTask/	BashTool run_in_background、Monitor 脚本
`remote_agent`	RemoteAgentTask/	/ultraplan、/ultrareview、background PR
`in_process_teammate`	InProcessTeammateTask/	AgentTool teammate spawn（同进程）
`local_workflow`	LocalWorkflowTask/	占位 stub（isLocalWorkflowTask 恒 false）
`monitor_mcp`	MonitorMcpTask/	占位 stub（isMonitorMcpTask 恒 false）
`dream`	DreamTask/	autoDream 记忆整理 fork agent

BackgroundTaskState 是 footer pill 与 Shift+Down 对话框的数据源。isBackgroundTask 要求 status 为 running/pending 且 isBackgrounded !== false（foreground 任务在 pill 中隐藏，直到用户 Ctrl+B 或 auto-background 超时）。

notified 标志防止重复 XML notification；evictAfter + retain 控制 CoordinatorTaskPanel 的 GC 宽限期。

目录树展示 src/tasks/ 下全部子目录（LocalAgentTask、RemoteAgentTask、LocalShellTask 等）。根目录 types.ts、stopTask.ts、pillLabel.ts、LocalMainSessionTask.ts 在树中可见。点击子目录进入对应深度讲解。

与其他模块的协作

协作方	关系
tools/AgentTool/	registerAsyncAgent、completeAgentTask、enqueueAgentNotification
tools/BashTool/	spawnShellTask、registerForeground、backgroundTask
query.ts	LocalMainSessionTask.startBackgroundSession 递归 query
utils/task/diskOutput	initTaskOutputAsSymlink、appendTaskOutput、evictTaskOutput
utils/messageQueueManager	enqueuePendingNotification（task-notification 模式）
utils/sdkEventQueue	emitTaskTerminatedSdk、emitTaskProgress
components/BackgroundTasksIndicator	消费 getPillLabel、pillNeedsCta
utils/teleport	pollRemoteSessionEvents、archiveRemoteSession

调试「任务 pill 不显示」时：先查 isBackgroundTask 谓词，再查 task.isBackgrounded，最后查 foregroundedTaskId 是否占用主视图。调试「stop 无效」时：查 getTaskByType(task.type).kill 与 StopTaskError.code。

本章小结与延伸

tasks 模块 = 长运行工作的统一注册表与生命周期管理。先懂 LocalAgentTask 与 LocalMainSessionTask，再读 RemoteAgentTask 轮询，最后理解 stopTask 与 pillLabel 的 UI 契约。 继续学习：

local-agent-task