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 模式实现：**
```typescript
// 位置：/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` 是全局状态的核心结构，包含以下主要部分：

```typescript
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：**
```typescript
// 状态变更时的处理逻辑
- 任务创建时自动展开任务列表
- 插件状态变更时触发热重载
- 团队上下文变更时更新 UI
```

## 2. 任务管理 (tasks/)

### 2.1 任务类型

**位置：** `/src/tasks/types.ts`

Claude Code 支持多种任务类型：

```typescript
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
```

**状态定义：**
```typescript
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`

```typescript
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`

```typescript
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 任务间依赖

**依赖管理：**
```typescript
// 阻止关系
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 中的任务管理

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

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

// 前台任务 ID
foregroundedTaskId?: string

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

### 3.2 任务状态变更与 UI 更新

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

## 4. 后台任务管理

### 4.1 背景任务识别

```typescript
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 任务清理：**
```typescript
// 位置：/src/tasks/LocalShellTask/killShellTasks.ts
export function killShellTasksForAgent(
  agentId: AgentId,
  getAppState: () => AppState,
  setAppState: (updater: (prev: AppState) => AppState) => void
): void
```

### 4.3 任务与 Hooks 的集成

```typescript
// 任务创建钩子
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

用于异步长时间运行的任务：
```typescript
// 位置：/src/tasks/DreamTask/DreamTask.ts
export type DreamTaskState = {
  // 异步任务状态
}
```

### 5.2 InProcessTeammateTask

用于进程中队友通信的任务类型：
```typescript
// 位置：/src/tasks/InProcessTeammateTask/types.ts
export type InProcessTeammateTaskState = {
  identity: TeammateIdentity
  abortController?: AbortController
  shutdownRequested?: boolean
  // ...
}
```

## 6. 任务列表管理

### 6.1 任务列表 ID

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

### 6.2 任务通知

```typescript
// 任务更新通知
notifyTasksUpdated()

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

## 7. 验证与提醒

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

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

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