Claude Code 源码研究（五）任务系统：7 种 Task 与多态生命周期

// 7 种任务类型
export type TaskType =
  | 'local_bash'            // 长跑 bash 子进程
  | 'local_agent'           // 本地子代理（AgentTool 后端）
  | 'remote_agent'          // 远程代理（云端）
  | 'in_process_teammate'   // 同进程队友
  | 'local_workflow'        // 工作流脚本（feature gate）
  | 'monitor_mcp'           // MCP 监控（feature gate）
  | 'dream'                 // 后台记忆整固

// 五态机
export type TaskStatus =
  | 'pending' | 'running'
  | 'completed' | 'failed' | 'killed'

export function isTerminalTaskStatus(status): boolean
// completed / failed / killed 不再转移
// 用于阻止向死队友注入消息、清理孤儿任务

// 多态接口（极薄）
export type Task = {
  name: string
  type: TaskType
  kill(taskId: string, setAppState: SetAppState): Promise<void>
}
// 注释: spawn/render 历史上是多态的，#22546 后被移除
//       6 种 kill 实现都只用 setAppState，
//       getAppState/abortController 是死代码

// 类型前缀 + 8 位字符
local_bash         → b...
local_agent        → a...
remote_agent       → r...
in_process_teammate → t...
local_workflow     → w...
monitor_mcp        → m...
dream              → d...

// 36⁸ ≈ 2.8 万亿组合
const TASK_ID_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'

// crypto.randomBytes(8) % 36 取字符
// 设计原因: 防止符号链接攻击爆破

export type TaskStateBase = {
  id: string
  type: TaskType
  status: TaskStatus
  description: string
  toolUseId?: string
  startTime: number
  endTime?: number
  totalPausedMs?: number
  outputFile: string      // 输出落盘路径
  outputOffset: number    // 已读偏移
  notified: boolean       // 是否已通知用户
}

const LocalWorkflowTask = feature('WORKFLOW_SCRIPTS')
  ? require('./tasks/LocalWorkflowTask/LocalWorkflowTask.js').LocalWorkflowTask
  : null
const MonitorMcpTask = feature('MONITOR_TOOL')
  ? require('./tasks/MonitorMcpTask/MonitorMcpTask.js').MonitorMcpTask
  : null

export function getAllTasks(): Task[] {
  const tasks = [LocalShellTask, LocalAgentTask, RemoteAgentTask, DreamTask]
  if (LocalWorkflowTask) tasks.push(LocalWorkflowTask)
  if (MonitorMcpTask) tasks.push(MonitorMcpTask)
  return tasks
}

export function getTaskByType(type: TaskType): Task | undefined

export type ToolActivity = {
  toolName: string
  input: Record<string, unknown>
  activityDescription?: string  // 来自 Tool.getActivityDescription()
  isSearch?: boolean
  isRead?: boolean
}

export type AgentProgress = {
  toolUseCount: number
  tokenCount: number
  lastActivity?: ToolActivity
  recentActivities?: ToolActivity[]  // 最多 5 个
  summary?: string
}

export type ProgressTracker = {
  toolUseCount: number
  latestInputTokens: number        // 累计 — 取最新（API 已含全部历史）
  cumulativeOutputTokens: number   // 累加 — 每 turn 输出
  recentActivities: ToolActivity[]
}

主代理 query 循环
  └─ tool_use: AgentTool({ subagent_type: 'Explore', prompt: '...' })
       └─ AgentTool.call(...)
            └─ runAgent({
                 agentType, prompt,
                 parentMessage,
                 onProgress,
                 thinkingConfig,
                 ...
               })
                  └─ 创建 LocalAgentTask（同进程）
                       ├─ registerTask(appState, taskState)
                       ├─ initTaskOutputAsSymlink(taskId)
                       └─ 内部跑独立 query 循环
                            ├─ 独立 messages
                            ├─ 独立 toolUseContext
                            ├─ 独立 token 预算
                            ├─ updateProgressFromMessage()  追踪进度
                            └─ 完成 → SyntheticOutputTool 汇总输出
                  └─ AgentTool 返回单条 summary 给主代理
                       └─ 节省主代理上下文（不暴露子代理工具痕迹）

spawn (各实现自身)
  ↓
registerTask(appState, taskState)
  ↓
status = 'pending' → 'running'
  ↓
periodic: updateTaskState(setAppState, taskId, patch)
  ↓
[panel grace: PANEL_GRACE_MS]    完成后保留显示
  ↓
emitTaskProgress(sdkChannel)     SDK 用户能看到
  ↓
notified=true 后 enqueuePendingNotification
  ↓
status = 'completed' | 'failed' | 'killed'
  ↓
evictTaskOutput(taskId)          落盘输出清理
registerCleanup(...)              注销资源