claude-code-mirror/claude-code-中文Wiki/09-状态与任务管理.md

状态与任务管理

Claude Code 提供了强大的状态管理和任务管理系统来协调复杂的操作流程。

1. 状态管理 (state/)

1.1 状态存储机制

核心文件：

• /src/state/store.ts - 状态存储基础实现
• /src/state/AppStateStore.ts - 应用状态存储
• /src/state/onChangeAppState.ts - 状态变更处理
• /src/state/selectors.ts - 状态选择器

Store 模式实现：

// 位置：/src/state/store.ts
export type Store<T> = {
  getState: () => T           // 获取当前状态
  setState: (updater: (prev: T) => T) => void  // 更新状态
  subscribe: (listener: Listener) => () => void  // 订阅变更
}

export function createStore<T>(
  initialState: T,
  onChange?: OnChange<T>
): Store<T>

特性：

• 不可变性（Immutability）：状态更新采用函数式风格
• 订阅机制：支持多个监听器，变更时自动通知
• 变更回调：onChange 回调在状态变更后执行

1.2 AppState 结构

位置： /src/state/AppStateStore.ts

AppState 是全局状态的核心结构，包含以下主要部分：

export type AppState = {
  // 设置与配置
  settings: SettingsJson
  verbose: boolean
  mainLoopModel: ModelSetting

  // 任务管理
  tasks: { [taskId: string]: TaskState }
  agentNameRegistry: Map<string, AgentId>
  foregroundedTaskId?: string
  viewingAgentTaskId?: string

  // MCP 状态
  mcp: {
    clients: MCPServerConnection[]
    tools: Tool[]
    commands: Command[]
    resources: Record<string, ServerResource[]>
    pluginReconnectKey: number
  }

  // 插件状态
  plugins: {
    enabled: LoadedPlugin[]
    disabled: LoadedPlugin[]
    commands: Command[]
    errors: PluginError[]
    installationStatus: {...}
    needsRefresh: boolean
  }

  // Agent 定义
  agentDefinitions: AgentDefinitionsResult

  // 团队上下文
  teamContext?: {
    teamName: string
    teamFilePath: string
    leadAgentId: string
    selfAgentId?: string
    selfAgentName?: string
    isLeader?: boolean
    selfAgentColor?: string
    teammates: {...}
  }

  // 推理状态
  speculation: SpeculationState
  thinkingEnabled: boolean | undefined
}

1.3 状态持久化

持久化策略：

• 设置存储在 ~/.claude/settings.json
• 任务状态存储在 ~/.claude/tasks/{taskListId}/
• 团队配置存储在 ~/.claude/teams/{team-name}/

状态恢复：

• 应用启动时从磁盘加载设置
• 团队成员重新连接时恢复上下文
• 任务队列在会话间持久化

1.4 状态变更处理

onChangeAppState.ts：

// 状态变更时的处理逻辑
- 任务创建时自动展开任务列表
- 插件状态变更时触发热重载
- 团队上下文变更时更新 UI

2. 任务管理 (tasks/)

2.1 任务类型

位置： /src/tasks/types.ts

Claude Code 支持多种任务类型：

export type TaskState =
  | LocalShellTaskState      // 本地 Shell 任务
  | LocalAgentTaskState     // 本地 Agent 任务
  | RemoteAgentTaskState    // 远程 Agent 任务
  | InProcessTeammateTaskState  // 进程中队友任务
  | LocalWorkflowTaskState  // 本地工作流任务
  | MonitorMcpTaskState     // MCP 监控任务
  | DreamTaskState          // 异步任务

2.2 任务状态机

任务状态流转：

pending → in_progress → completed
    ↓           ↓           ↓
  blocked    blocked     blocked
    ↓           ↓
  cancelled  cancelled

状态定义：

type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'cancelled' | 'blocked'

interface TaskState {
  id: string
  status: TaskStatus
  subject: string
  description?: string
  activeForm?: string       // 进行中的操作描述
  owner?: string           // 任务负责人
  blocks: string[]          // 此任务阻止的任务
  blockedBy: string[]       // 阻止此任务的任务
  metadata?: Record<string, unknown>
}

2.3 任务工具

Claude Code 提供四个主要任务工具：

TaskCreateTool

位置： /src/tools/TaskCreateTool/TaskCreateTool.ts

input: {
  subject: string                    // 任务标题
  description: string                // 任务描述
  activeForm?: string                // 进行中显示文本
  metadata?: Record<string, unknown> // 元数据
}

output: {
  task: {
    id: string
    subject: string
  }
}

特性：

• 创建任务后自动展开任务列表
• 支持任务创建钩子 (TaskCreated hooks)
• 阻止错误的钩子可取消创建

TaskUpdateTool

位置： /src/tools/TaskUpdateTool/TaskUpdateTool.ts

input: {
  taskId: string
  subject?: string
  description?: string
  activeForm?: string
  status?: TaskStatus | 'deleted'
  addBlocks?: string[]       // 此任务阻止的任务
  addBlockedBy?: string[]     // 阻止此任务的任务
  owner?: string
  metadata?: Record<string, unknown>
}

output: {
  success: boolean
  taskId: string
  updatedFields: string[]
  statusChange?: { from: string; to: string }
  verificationNudgeNeeded?: boolean
}

特性：

• 支持原子字段更新
• 任务完成时触发 TaskCompleted 钩子
• 所有权变更时通知新负责人
• 阻止依赖任务处理

TaskListTool

列出所有任务，支持过滤和排序。

TaskStopTool

停止正在运行的任务。

2.4 任务间依赖

依赖管理：

// 阻止关系
task.blocks = ['task-id-1', 'task-id-2']      // 此任务阻止这些任务
task.blockedBy = ['task-id-3']                // 此任务被这些任务阻止

// 依赖检查
function canStartTask(task: TaskState): boolean {
  return task.blockedBy.every(id => isTaskCompleted(id))
}

2.5 任务输出 (TaskOutputTool)

位置： /src/tools/TaskOutputTool/

用于检索任务的执行输出和结果。

3. 任务与状态的集成

3.1 AppState 中的任务管理

// 任务存储在 AppState.tasks 中
tasks: { [taskId: string]: TaskState }

// 任务 ID 注册表（用于按名称查找）
agentNameRegistry: Map<string, AgentId>

// 前台任务 ID
foregroundedTaskId?: string

// 查看中的 Agent 任务 ID
viewingAgentTaskId?: string

3.2 任务状态变更与 UI 更新

// TaskCreateTool 和 TaskUpdateTool 自动更新 expandedView
context.setAppState(prev => {
  if (prev.expandedView === 'tasks') return prev
  return { ...prev, expandedView: 'tasks' as const }
})

4. 后台任务管理

4.1 背景任务识别

export function isBackgroundTask(task: TaskState): boolean {
  if (task.status !== 'running' && task.status !== 'pending') {
    return false
  }
  // 前台任务（isBackgrounded === false）不是后台任务
  if ('isBackgrounded' in task && task.isBackgrounded === false) {
    return false
  }
  return true
}

4.2 任务清理

Shell 任务清理：

// 位置：/src/tasks/LocalShellTask/killShellTasks.ts
export function killShellTasksForAgent(
  agentId: AgentId,
  getAppState: () => AppState,
  setAppState: (updater: (prev: AppState) => AppState) => void
): void

4.3 任务与 Hooks 的集成

// 任务创建钩子
executeTaskCreatedHooks(
  taskId: string,
  subject: string,
  description: string,
  agentName: string | undefined,
  teamName: string | undefined,
  // ...
)

// 任务完成钩子
executeTaskCompletedHooks(
  taskId: string,
  subject: string,
  description: string,
  agentName: string | undefined,
  teamName: string | undefined,
  // ...
)

5. 工作流集成

5.1 DreamTask

用于异步长时间运行的任务：

// 位置：/src/tasks/DreamTask/DreamTask.ts
export type DreamTaskState = {
  // 异步任务状态
}

5.2 InProcessTeammateTask

用于进程中队友通信的任务类型：

// 位置：/src/tasks/InProcessTeammateTask/types.ts
export type InProcessTeammateTaskState = {
  identity: TeammateIdentity
  abortController?: AbortController
  shutdownRequested?: boolean
  // ...
}

6. 任务列表管理

6.1 任务列表 ID

function getTaskListId(): string {
  // 基于团队名称或会话 ID
}

6.2 任务通知

// 任务更新通知
notifyTasksUpdated()

// 任务目录
getTasksDir(taskListId: string): string

7. 验证与提醒

当完成任务列表时，系统会检查是否需要进行验证：

// 在 TaskUpdateTool 中
if (allTasks.length >= 3 && !allTasks.some(t => /verif/i.test(t.subject))) {
  verificationNudgeNeeded = true
}

这提醒主线程 Agent 在没有验证步骤的情况下关闭了 3+ 个任务列表。