first commit

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

@@ -0,0 +1,390 @@
+# 状态与任务管理
+
+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+ 个任务列表。