claude-code/docs/types-utils-state.md

类型系统、工具函数与状态管理分析

类型系统

类型定义目录结构

graph TB
    subgraph types/
        CMD[command.ts<br/>命令类型]
        GEN[generated/<br/>生成类型]
        HOOKS[hooks.ts<br/>Hook 类型]
        IDS[ids.ts<br/>ID 类型]
        LOGS[logs.ts<br/>日志类型]
        PERM[permissions.ts<br/>权限类型]
        PLUGIN[plugin.ts<br/>插件类型]
        TEXT[textInputTypes.ts<br/>文本输入类型]
    end

    subgraph 核心类型定义
        TOOL_TYPE[Tool.ts<br/>工具类型]
        MSG[types/message.ts<br/>消息类型]
        TOOL_TYPES[types/tools.ts<br/>工具进度类型]
    end

    subgraph Schema 验证
        SCHEMAS[schemas/<br/>Zod Schema]
    end

关键类型定义

权限类型 (types/permissions.ts)

// 权限模式
type PermissionMode =
  | 'default'      // 默认：提示用户
  | 'plan'         // 计划：只读操作
  | 'bypassPermissions'  // 绕过所有权限
  | 'auto'         // 自动允许
  | 'dontAsk'      // 不询问

// 权限结果
type PermissionResult =
  | { allowed: true }
  | { allowed: false; reason: string }

工具进度类型 (types/tools.ts)

type ToolProgressData =
  | BashProgress
  | AgentToolProgress
  | MCPProgress
  | REPLToolProgress
  | SkillToolProgress
  | TaskOutputProgress
  | WebSearchProgress

消息类型 (types/message.ts)

type Message =
  | UserMessage
  | AssistantMessage
  | SystemMessage
  | ProgressMessage
  | AttachmentMessage
  | SystemLocalCommandMessage

状态管理

flowchart TD
    A[state/] --> B[AppState.tsx<br/>应用状态]
    A --> C[AppStateStore.ts<br/>状态存储]
    A --> D[store.ts<br/>Store 定义]
    A --> E[onChangeAppState.ts<br/>状态变更监听]
    A --> F[selectors.ts<br/>状态选择器]
    A --> G[teammateViewHelpers.ts<br/>队友视图辅助]

    B --> H[全局应用状态]
    H --> I[当前会话]
    H --> J[MCP 连接]
    H --> K[工具列表]
    H --> L[消息历史]
    H --> M[设置状态]
    H --> N[代理状态]
    H --> O[权限上下文]

AppState 核心状态

classDiagram
    class AppState {
        +Session currentSession
        +MCPState mcp
        +ToolsState tools
        +MessagesState messages
        +SettingsState settings
        +AgentState agents
        +PermissionContext permissions
        +BridgeState bridge
        +UIState ui
    }

    class Session {
        +string id
        +string model
        +Message[] messages
        +number totalCost
        +number totalTokens
    }

    class MCPState {
        +MCPServerConnection[] connections
        +Tool[] tools
    }

    class AgentState {
        +AgentInfo[] activeAgents
        +TeamInfo[] teams
        +TaskInfo[] tasks
    }

    AppState --> Session
    AppState --> MCPState
    AppState --> AgentState

工具函数 (utils/)

graph TB
    subgraph 核心工具
        PERM_UTILS[permissions/<br/>权限工具函数]
        FILE_CACHE[fileStateCache.ts<br/>文件状态缓存]
        ENV[envUtils.ts<br/>环境工具]
        SYSTEM[systemPromptType.ts<br/>系统提示类型]
    end

    subgraph 文件操作
        FILE_HISTORY[fileHistory.ts<br/>文件历史]
        FILE_STATE[fileStateCache.ts<br/>文件状态缓存]
    end

    subgraph 代理工具
        AGENT_SWARM[agentSwarmsEnabled.ts<br/>代理集群开关]
        WORKTREE[worktreeModeEnabled.ts<br/>Worktree 模式开关]
        TOOL_SEARCH[toolSearch.ts<br/>工具搜索]
        TASKS[tasks.ts<br/>任务工具]
    end

    subgraph Shell 工具
        SHELL[shell/<br/>Shell 相关工具]
    end

    subgraph 其他工具
        THEME[theme.ts<br/>主题管理]
        THINK[thinking.ts<br/>思考模式]
        TOKEN[tokenEstimation<br/>Token 估算]
        COMMIT[commitAttribution.ts<br/>提交归因]
        TOOL_RESULT[toolResultStorage.ts<br/>工具结果存储]
        DENIAL[denialTracking.ts<br/>拒绝追踪]
        EMBEDDED[embeddedTools.ts<br/>内嵌工具]
    end

Schema 验证体系

使用 Zod v4 进行配置验证。

flowchart TD
    A[schemas/<br/>Zod Schema 定义] --> B[配置验证]
    B --> C[settings.json<br/>设置文件]
    B --> D[CLAUDE.md<br/>项目指令]
    B --> E[plugins/<br/>插件配置]
    B --> F[keybindings<br/>快捷键配置]

上下文管理

flowchart TD
    A[context.ts] --> B[系统上下文收集]
    A --> C[用户上下文收集]

    B --> D[操作系统信息]
    B --> E[Shell 环境]
    B --> F[工作目录信息]
    B --> G[Git 状态]

    C --> H[CLAUDE.md 指令]
    C --> I[项目文件结构]
    C --> J[对话历史]
    C --> K[工具结果]

    subgraph context/ 子模块
        L[notifications.ts<br/>通知]
        M[其他上下文模块]
    end

任务管理

flowchart TD
    A[tasks.ts] --> B[Task.ts<br/>任务类型定义]
    A --> C[tasks/<br/>任务实现]

    D[TaskCreateTool] --> E[创建任务]
    F[TaskUpdateTool] --> G[更新任务状态]
    H[TaskGetTool] --> I[获取任务详情]
    J[TaskListTool] --> K[列出所有任务]
    L[TaskOutputTool] --> M[获取后台任务输出]
    N[TaskStopTool] --> O[停止任务]

    E --> P[状态: pending]
    P --> Q[状态: in_progress]
    Q --> R[状态: completed]
    Q --> S[状态: deleted]

    subgraph 任务依赖
        T[addBlocks<br/>设置阻塞关系]
        U[addBlockedBy<br/>设置被阻塞关系]
    end

成本追踪

flowchart TD
    A[cost-tracker.ts] --> B[Token 计数]
    A --> C[成本估算]
    A --> D[阈值监控]

    B --> E[输入 Token]
    B --> F[输出 Token]
    B --> G[缓存读取 Token]
    B --> H[缓存写入 Token]

    D --> I[成本阈值提醒]
    D --> J[用量限制检查]

    K[costHook.ts] --> L[成本 Hook<br/>每次查询后更新]

历史记录管理

flowchart TD
    A[history.ts] --> B[会话历史存储]
    A --> C[消息历史]
    A --> D[命令历史]

    B --> E[会话恢复<br/>/resume]
    C --> F[上下文压缩<br/>/compact]
    D --> G[命令补全<br/>useArrowKeyHistory]

配置迁移

flowchart LR
    A[migrations/] --> B[配置版本检测]
    B --> C{版本匹配?}
    C -->|需要迁移| D[执行迁移脚本]
    C -->|已是最新| E[跳过]
    D --> F[更新配置格式]

Bash 解析器 (utils/bash/)

Claude Code 实现了一个完整的 Bash 语法解析器，用于分析和理解 Shell 命令：

flowchart TD
    A[utils/bash/<br/>Bash 解析系统] --> B[parser.ts<br/>语法解析器]
    A --> C[ast.ts<br/>抽象语法树]
    A --> D[commands.ts<br/>命令解析]
    A --> E[shellQuoting.ts<br/>Shell 引用处理]

    B --> F[管道链解析<br/>识别管道操作]
    B --> G[重定向解析<br/>识别重定向操作]
    B --> H[变量展开<br/>识别环境变量]
    B --> I[子 Shell 解析<br/>识别嵌套命令]

    subgraph 用途
        J[BashTool 命令语义分析<br/>commandSemantics.ts]
        K[破坏性命令检测<br/>destructiveCommandWarning.ts]
        L[只读验证<br/>readOnlyValidation.ts]
        L2[sed 命令验证<br/>sedValidation.ts]
    end

内存目录系统 (memdir/)

flowchart TD
    A[memdir/<br/>持久化内存目录] --> B[memdir.ts<br/>内存目录管理]
    A --> C[memoryTypes.ts<br/>记忆类型定义]
    A --> D[memoryScan.ts<br/>记忆扫描]
    A --> E[paths.ts<br/>路径管理]

    B --> F[自动记忆<br/>auto memory]
    B --> G[团队记忆<br/>team memory]

    subgraph 记忆存储结构
        H[MEMORY.md<br/>索引文件<br/>~150字/行]
        I[*.md<br/>记忆文件<br/>frontmatter 格式]
    end

    F --> H
    G --> H
    H --> I

任务类型体系

classDiagram
    class TaskBase {
        +string id
        +string subject
        +string description
        +TaskStatus status
    }

    class LocalShellTask {
        +后台 Shell 执行
    }

    class LocalAgentTask {
        +本地代理任务
    }

    class RemoteAgentTask {
        +远程代理任务
    }

    class DreamTask {
        +AI 规划任务
    }

    class LocalWorkflowTask {
        +工作流脚本任务
    }

    class MonitorMcpTask {
        +MCP 监控任务
    }

    TaskBase <|-- LocalShellTask
    TaskBase <|-- LocalAgentTask
    TaskBase <|-- RemoteAgentTask
    TaskBase <|-- DreamTask
    TaskBase <|-- LocalWorkflowTask
    TaskBase <|-- MonitorMcpTask