任务系统

🗺️ 什么是任务？

当 Claude Code 运行 bash 命令、生成子代理、启动远程云会话或启动“梦想”内存整合代理时 - 每一个都被跟踪为 task。 任务是 Claude Code 的模型，用于与主要对话一起运行的并发、可观察的工作单元。

核心抽象位于 Task.ts。 系统中的每个任务共享一个共同的基本状态（TaskStateBase）、五种状态的生命周期和单一的kill接口：

// Task.ts — the minimal interface every task type implements
export type Task = {
  name: string
  type: TaskType
  kill(taskId: string, setAppState: SetAppState): Promise<void>
}

// Seven concrete types live in the codebase today
export type TaskType =
  | 'local_bash'        // LocalShellTask
  | 'local_agent'       // LocalAgentTask (+ LocalMainSessionTask)
  | 'remote_agent'      // RemoteAgentTask
  | 'in_process_teammate' // InProcessTeammateTask
  | 'local_workflow'    // LocalWorkflowTask
  | 'monitor_mcp'       // MonitorMcpTask
  | 'dream'             // DreamTask

// Shared fields every task state carries
export type TaskStateBase = {
  id: string          // e.g., "b3f7a2c1..." (prefix encodes type)
  type: TaskType
  status: TaskStatus   // pending | running | completed | failed | killed
  description: string
  toolUseId?: string   // links back to the tool_use that spawned this task
  startTime: number
  endTime?: number
  outputFile: string   // absolute path to the task output file on disk
  outputOffset: number // byte offset: how much output has been consumed
  notified: boolean    // prevents double-notification (atomically set)
}

🔄 生命周期

每个任务都会经历五个状态。 其中只有三个是终端（任务一旦到达这些就不会进一步转换）：

通知标志：防止重复投递

The notified 场上 TaskStateBase 是一个单向锁存器。 当任务完成时（任何终端状态），系统自动设置 notified: true 并将单个 XML 通知排队到模型中。 因为这是由比较和设置保护的状态机转换，所以即使两个异步路径（任务的结果处理程序和终止调用）竞相完成，也只会触发一个通知：

// Pattern used by every task type (e.g. LocalAgentTask.ts)
let shouldEnqueue = false
updateTaskState<LocalAgentTaskState>(taskId, setAppState, task => {
  if (task.notified) {
    return task           // already notified — no-op
  }
  shouldEnqueue = true
  return { ...task, notified: true }
})
if (!shouldEnqueue) return   // another path already sent the notification
// ... enqueue XML notification ...

逐出：通知后释放内存

一旦任务终止并得到通知，它就有资格从 AppState.tasks。 有两种机制可以处理这个问题：惰性 GC 传入 generateTaskAttachments() （在每个轮询标记上运行）和一个名为的急切路径 evictTerminalTask() 由任务自己的完成处理程序调用。 这 local_agent type 添加了第三个：可配置的宽限期（evictAfter）对于协调器任务面板中保留的任务，以便 UI 可以在任务完成后短暂显示它们。

📦 七种任务类型

🔬 深潜

// isBackgrounded = false → task exists in AppState but is "owned" by
// the foreground UI. isBackgrounded = true → task is truly background.
export function isBackgroundTask(task: TaskState): task is BackgroundTaskState {
  if (task.status !== 'running' && task.status !== 'pending') return false
  // Foreground tasks (isBackgrounded === false) excluded from pill
  if ('isBackgrounded' in task && task.isBackgrounded === false) return false
  return true
}

const PROMPT_PATTERNS = [
  /\(y\/n\)/i,          // (Y/n), (y/N)
  /\[y\/n\]/i,          // [Y/n], [y/N]
  /\(yes\/no\)/i,
  /\b(?:Do you|Would you|Shall I|Are you sure)\b.*\? *$/i,
  /Press (any key|Enter)/i,
  /Continue\?/i,
  /Overwrite\?/i
]

export function updateProgressFromMessage(
  tracker: ProgressTracker,
  message: Message,
): void {
  const usage = message.message.usage
  // input is cumulative: keep the latest, don't sum
  tracker.latestInputTokens = usage.input_tokens
    + (usage.cache_creation_input_tokens ?? 0)
    + (usage.cache_read_input_tokens ?? 0)
  // output is per-turn: sum across all turns
  tracker.cumulativeOutputTokens += usage.output_tokens
  // ... track tool uses and recent activities ...
}

// Register a completion checker for a specific remote task type
export function registerCompletionChecker(
  remoteTaskType: RemoteTaskType,
  checker: RemoteTaskCompletionChecker,
): void {
  completionCheckers.set(remoteTaskType, checker)
}

// Called on every poll tick
type RemoteTaskCompletionChecker = (
  metadata: RemoteTaskMetadata | undefined
) => Promise<string | null>
// Return non-null string → task complete, string is the notification text
// Return null → keep polling

export const TEAMMATE_MESSAGES_UI_CAP = 50

export function appendCappedMessage<T>(
  prev: readonly T[] | undefined,
  item: T,
): T[] {
  if (prev && prev.length >= TEAMMATE_MESSAGES_UI_CAP) {
    // Slice oldest, append new — always returns a new array
    const next = prev.slice(-(TEAMMATE_MESSAGES_UI_CAP - 1))
    next.push(item)
    return next
  }
  return [...(prev ?? []), item]
}

async kill(taskId, setAppState) {
  let priorMtime: number | undefined
  updateTaskState<DreamTaskState>(taskId, setAppState, task => {
    if (task.status !== 'running') return task
    task.abortController?.abort()
    priorMtime = task.priorMtime       // capture before state wipe
    return { ...task, status: 'killed', notified: true, ... }
  })
  if (priorMtime !== undefined) {
    await rollbackConsolidationLock(priorMtime)
  }
}

📣 通知系统

当任务完成时，它必须通知模型，以便它可以在下一轮处理结果。 通知是排队到的 XML 消息 messageQueueManager 具有特定的格式。 每个任务类型都会构建相同的 XML 信封：

// The canonical notification envelope
`<task_notification>
<task_id>${taskId}</task_id>
<tool_use_id>${toolUseId}</tool_use_id>   // links to spawning tool call
<output_file>${outputPath}</output_file>  // model reads this file for full output
<status>${status}</status>              // completed | failed | killed
<summary>${summary}</summary>          // human-readable 1-liner
</task_notification>`

优先级：下一个 vs 稍后

通知排队 priority field: 'next' 在下一回合开始时发送通知（立即可见），同时 'later' 将其排在任何挂起的正常消息之后。 Shell 任务使用 'later' 默认情况下; 监视任务（通过启用 MONITOR_TOOL 功能标志）使用 'next'。 这可以防止大量后台 shell 完成中断对话流。

停顿通知没有 <status> 标签——故意的

停顿看门狗通知（当命令似乎正在等待输入时发送）有意省略 <status> 标签。 原因很微妙： print.ts 治疗任何 <status> 值作为终端信号。 如果没有可识别的状态值，通知将被视为进度 ping - 任务保持打开状态。 与一个 <status> 标记设置为某个占位符值， print.ts 将落入“已完成”状态并错误地关闭 SDK 消费者的任务。

代理通知包括结果和使用情况

与 shell 任务通知不同，代理任务通知携带更丰富的负载：最终结果文本（通过 <result>）、令牌使用统计信息、持续时间以及可选的工作树路径/分支（如果代理在 git 工作树中运行）：

// LocalAgentTask enqueueAgentNotification — richer than shell
const resultSection   = finalMessage  ? `\n<result>${finalMessage}</result>` : ''
const usageSection    = usage ? `\n<usage><total_tokens>${total}</total_tokens>...` : ''
const worktreeSection = worktreePath  ? `\n<worktree><path>${worktreePath}</path>...` : ''

💾 输出管理

每个任务在磁盘上都有一个输出文件 ~/.claude/projects/<project>/tmp/<sessionId>/tasks/<taskId>.output。 系统采用两层架构：

文件模式与管道模式

Bash 命令使用 文件模式：stdout 和 stderr 通过操作系统级文件描述符重定向到输出文件。 JS 在执行过程中不会看到这些数据。 通过使用与 React 组件挂载/卸载生命周期相关的共享静态轮询器每 1 秒轮询一次文件尾部来提取进度。

挂钩执行和基于管道的输出使用 管道模式：数据流经 writeStdout()/writeStderr() 到内存缓冲区中。 当缓冲区超过8MB时，它通过以下方式溢出到磁盘 DiskTaskOutput。 在溢出状态下， getStdout() 仅返回最近 5 行并带有截断通知。

安全性：O_NOFOLLOW 防止符号链接攻击

所有输出文件打开都使用 O_NOFOLLOW 标志（如果可用 - 仅限 Unix）。 如果没有这个，沙盒环境中的攻击者可以在任务目录中创建指向任意文件的符号链接（例如， /etc/passwd），导致主机上的 Claude Code 在那里写入任务输出。 该标志导致打开失败 ELOOP 如果路径是符号链接，则完全防止攻击。

代理转录本使用符号链接

For local_agent 任务时，输出文件被初始化为代理脚本 JSONL 文件的符号链接，通过 initTaskOutputAsSymlink()。 这意味着读取任务输出文件相当于读取代理的转录本 - 没有数据重复。 增量读取系统（getTaskOutputDelta()）使用字节偏移量，因此它可以有效地仅读取自上次轮询以来的新内容。

API 消耗的截断

在任务输出包含在模型通知中之前，它会被格式化并截断 formatTaskOutput()。 默认限制为 32,000 个字符（可通过配置 TASK_MAX_OUTPUT_LENGTH，上限为 160,000）。 截断的输出包括指向完整文件路径的标头，因此模型可以在需要时请求完整输出：

// outputFormatting.ts
export function formatTaskOutput(
  output: string,
  taskId: string,
): { content: string; wasTruncated: boolean } {
  const maxLen = getMaxTaskOutputLength()  // default 32_000
  if (output.length <= maxLen) return { content: output, wasTruncated: false }
  const filePath = getTaskOutputPath(taskId)
  const header = `[Truncated. Full output: ${filePath}]\n\n`
  const truncated = output.slice(-(maxLen - header.length))
  return { content: header + truncated, wasTruncated: true }
}

🧰 任务创建工具和任务更新工具

这两个工具使模型能够管理结构化的 任务清单 — 与上面的后台任务系统不同的概念。 任务列表是一个轻量级的项目管理系统：主题、描述、状态、所有权和依赖链（块/blockedBy）。 当 isTodoV2Enabled() 返回真。

TaskCreateTool

在活动任务列表中创建任务。 除了基本的创造之外，它还激发了 TaskCreated 钩子管道（可插入验证 - 如果任何钩子返回阻塞错误，则任务将被删除并引发错误）。 创建时，它会自动展开任务列表 UI 面板。

// The input schema — minimal by design
z.strictObject({
  subject:     z.string(),            // "Fix authentication bug in login flow"
  description: z.string(),            // what needs to be done
  activeForm:  z.string().optional(), // "Fixing authentication bug" (spinner text)
  metadata:    z.record(...).optional(), // arbitrary key-value
})

TaskUpdateTool：状态工作流程和自动所有权

更新现有任务的任何字段。 状态工作流程： pending → in_progress → completed， 和 deleted 作为完全删除任务文件的特殊操作。 关键行为：

• Auto-ownership：当队友（启用代理群）标记任务时 in_progress 如果不指定所有者，该工具会自动将所有者设置为呼叫代理的姓名。 这使任务列表与实际执行保持同步。
• 任务完成挂钩：标记任务 completed 激发 TaskCompleted 挂钩管道。 如果任何钩子返回阻塞错误（例如，测试失败），状态更新将被拒绝——当门失败时，模型无法将任务标记为完成。
• 邮箱通知：当所有权发生变化并启用代理群时， task_assignment 邮箱消息写入新所有者的邮箱，使团队成员无需轮询即可发现分配的工作。
• 验证推动：如果启用了功能标志，并且模型刚刚完成了 3 个以上任务中的最后一个，且列表中没有“verif*”任务，则工具结果将包含一个轻推以生成验证代理。

// The verification nudge — instructs the model to spawn a verifier
if (verificationNudgeNeeded) {
  resultContent += `\n\nNOTE: You just closed out 3+ tasks and none of them `
    + `was a verification step. Before writing your final summary, spawn `
    + `the verification agent (subagent_type="${VERIFICATION_AGENT_TYPE}"). `
    + `You cannot self-assign PARTIAL by listing caveats in your summary `
    + `— only the verifier issues a verdict.`
}

任务列表与后台任务：两个不同的系统

🖥️ UI：页脚药丸

页脚药丸（在 TUI 中可见，例如， ◇ 2 cloud sessions or 3 shells · Shift+Down) 是由生成的 getPillLabel() in tasks/pillLabel.ts。 它汇总了所有 background 任务（那些通过 isBackgroundTask()）并给出一个紧凑的摘要：

The pillNeedsCta() 函数控制是否 · ↓ to view 附加号召性用语 — 它仅针对处于注意力状态的单个 ultraplan 任务触发（needs_input or plan_ready），不适用于普通运行的任务。

当旋转器树处于活动状态时，进程中的队友将在旋转器树中渲染（每个队友一行），而不是页脚药丸中。 shouldHideTasksFooter() 检查每个后台任务是否都是正在进行的队友，并在这种情况下隐藏页脚药丸以避免重复。

🏗️ 框架内部：registerTask 和 updateTaskState

中的两个实用函数 utils/task/framework.ts 处理所有任务状态突变。 了解它们是理解所有七种任务类型如何保持一致的关键：

registerTask

registerTask(task, setAppState) 将任务插入到 AppState.tasks。 如果具有相同 ID 的任务已经存在（“恢复”路径），它将继承 UI 状态 — retain, startTime, messages, diskLoaded, pendingMessages。 这允许后台代理在会话中恢复，而不会丢失用户的记录视图或滚动位置。 注册后，会出现一个 task_started 发出 SDK 事件（跳过替换以避免重复发出）。

updateTaskState

updateTaskState<T>(taskId, setAppState, updater) 将更新程序功能应用于特定任务。 如果更新程序返回相同的引用（提前退出无操作），则 setAppState 调用被跳过 - React 订阅者不会在未更改的状态下重新渲染。 这种引用相等性检查对于频繁更新的任务（例如带有活动看门狗的 shell 命令）来说是一项重大优化。

export function updateTaskState<T extends TaskState>(
  taskId: string,
  setAppState: SetAppState,
  updater: (task: T) => T,
): void {
  setAppState(prev => {
    const task = prev.tasks?.[taskId] as T | undefined
    if (!task) return prev
    const updated = updater(task)
    if (updated === task) return prev // reference-equal → no-op, no re-render
    return { ...prev, tasks: { ...prev.tasks, [taskId]: updated } }
  })
}

轮询循环

pollTasks() 以 1 秒的间隔运行。 它调用 generateTaskAttachments()，它读取正在运行的任务的输出增量（基于字节偏移，从不加载整个文件），然后逐出终端+通知的任务。 偏移补丁应用于 fresh 状态（不是预等待快照），以防止在异步磁盘读取期间可能发生的并发转换。

📊 类型比较参考

🧠 Quiz