391 lines
8.6 KiB
Markdown
391 lines
8.6 KiB
Markdown
# 状态与任务管理
|
||
|
||
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+ 个任务列表。
|