Claude Code 源码文档 - 工具函数 (Utils)

版本: 2.1.88 | 文件数: 564 (329文件 + 子目录) | 源码路径: src/utils/

1. 模块概述

utils/ 是 Claude Code 最大的模块，包含 329 个顶层文件和多个子目录，提供所有共享工具函数。涵盖认证、配置、Git 操作、文件系统、消息处理、权限管理等基础能力。

2. 按功能域分类

🔐 认证与安全 (Auth & Security)

文件	职责
`auth.ts`	核心认证逻辑
`authFileDescriptor.ts`	文件描述符认证
`authPortable.ts`	便携式认证
`crypto.ts`	加密工具
`mtls.ts`	mTLS 支持
`secureStorage/`	安全存储
`aws.ts`	AWS 认证
`awsAuthStatusManager.ts`	AWS 认证状态
`caCerts.ts`	CA 证书配置

⚙️ 配置管理 (Config)

文件	职责
`config.ts`	全局配置加载
`configConstants.ts`	配置常量
`settings/`	设置管理子目录
`env.ts` / `envUtils.ts`	环境变量
`managedEnv.ts`	受管环境检测
`cliArgs.ts`	CLI 参数解析

📁 文件操作 (File Operations)

文件	职责
`file.ts`	文件工具函数
`fileRead.ts` / `fileReadCache.ts`	文件读取与缓存
`fileHistory.ts`	文件历史记录
`fileStateCache.ts`	文件状态缓存
`fsOperations.ts`	文件系统操作
`readFileInRange.ts`	按行范围读取
`tempfile.ts`	临时文件管理
`diff.ts`	文件差异计算
`glob.ts`	glob 模式匹配

🔀 Git 操作 (Git)

文件	职责
`git.ts`	Git 核心操作
`gitDiff.ts`	Git diff 操作
`gitSettings.ts`	Git 设置
`getWorktreePaths.ts`	Worktree 路径
`worktree.ts`	Worktree 操作
`ghPrStatus.ts`	GitHub PR 状态
`github/`	GitHub 相关工具
`commitAttribution.ts`	提交归属

💬 消息处理 (Messages)

文件	职责
`messages.ts`	消息创建/转换
`messages/`	消息处理子目录
`attachments.ts`	附件处理
`messageQueueManager.ts`	消息队列管理
`messagePredicates.ts`	消息过滤谓词
`toolResultStorage.ts`	工具结果存储
`controlMessageCompat.ts`	控制消息兼容

🛡️ 权限管理 (Permissions)

文件	职责
`permissions/`	权限工具子目录
`classifierApprovals.ts`	分类器审批
`autoModeDenials.ts`	自动模式拒绝

🧠 会话管理 (Session)

文件	职责
`sessionStorage.ts`	会话持久化
`sessionState.ts`	会话状态
`sessionStart.ts`	会话启动
`sessionRestore.ts`	会话恢复
`sessionTitle.ts`	会话标题
`sessionUrl.ts`	会话 URL
`sessionActivity.ts`	会话活跃度
`concurrentSessions.ts`	并发会话管理
`listSessionsImpl.ts`	列出会话
`crossProjectResume.ts`	跨项目恢复

🤖 模型与 API (Model & API)

文件	职责
`api.ts`	API 调用工具
`model/`	模型管理子目录
`modelCost.ts`	模型成本计算
`billing.ts`	计费工具
`tokens.ts` / `tokenBudget.ts`	Token 管理
`thinking.ts`	思考模式配置
`effort.ts`	努力等级
`fastMode.ts`	快速模式
`completionCache.ts`	补全缓存

🖥️ 终端与 UI (Terminal & UI)

文件	职责
`terminal.ts`	终端工具
`terminalPanel.ts`	终端面板
`format.ts`	文本格式化
`ansiToPng.ts` / `ansiToSvg.ts`	ANSI 转图片/SVG
`cliHighlight.ts`	CLI 高亮
`highlightMatch.tsx`	匹配高亮
`markdown.ts`	Markdown 渲染
`theme.ts`	主题管理
`systemTheme.ts`	系统主题
`hyperlink.ts`	超链接处理
`horizontalScroll.ts`	水平滚动

📦 工具系统支持 (Tool Support)

文件	职责
`toolPool.ts`	工具池管理
`toolErrors.ts`	工具错误处理
`toolSchemaCache.ts`	工具 Schema 缓存
`toolSearch.ts`	工具搜索
`toolResultStorage.ts`	工具结果存储
`mcpOutputStorage.ts`	MCP 输出存储

🔄 Cron 与调度 (Cron)

文件	职责
`cron.ts`	Cron 核心
`cronScheduler.ts`	Cron 调度器
`cronTasks.ts`	Cron 任务
`cronTasksLock.ts`	Cron 任务锁
`cronJitterConfig.ts`	Cron 抖动配置

📊 分析与遥测 (Analytics)

文件	职责
`telemetry/`	遥测子目录
`stats.ts` / `statsCache.ts`	统计信息
`profilerBase.ts`	性能分析基础
`headlessProfiler.ts`	Headless 性能分析
`startupProfiler.ts`	启动性能分析
`queryProfiler.ts`	查询性能分析
`fpsTracker.ts`	FPS 追踪
`heatmap.ts`	热力图

🔧 进程与执行 (Process)

文件	职责
`process.ts`	进程管理
`subprocessEnv.ts`	子进程环境
`shell/`	Shell 操作子目录
`Shell.ts`	Shell 工具
`ShellCommand.ts`	Shell 命令
`shellConfig.ts`	Shell 配置
`bash/`	Bash 相关子目录
`powershell/`	PowerShell 子目录
`execFileNoThrow.ts`	安全执行文件
`background/`	后台任务子目录

🧪 沙盒 (Sandbox)

文件	职责
`sandbox/`	沙盒工具子目录
`embeddedTools.ts`	嵌入式工具检测

📋 提示词 (Prompts)

文件	职责
`systemPrompt.ts`	系统提示词
`systemPromptType.ts`	系统提示词类型
`queryContext.ts`	查询上下文
`promptCategory.ts`	提示词分类
`promptEditor.ts`	提示词编辑器
`claudemd.ts`	CLAUDE.md 处理
`contextAnalysis.ts`	上下文分析

🧩 插件与技能 (Plugins & Skills)

文件	职责
`plugins/`	插件加载子目录
`skills/`	技能工具子目录
`mcp/`	MCP 工具子目录

🕐 时间与日期 (Time)

文件	职责
`sleep.ts`	延迟/睡眠
`timeouts.ts`	超时管理
`idleTimeout.ts`	空闲超时
`formatBriefTimestamp.ts`	时间格式化

🗂️ 其他工具

文件	职责
`array.ts`	数组工具
`hash.ts`	哈希计算
`json.ts` / `jsonRead.ts`	JSON 工具
`yaml.ts`	YAML 解析
`xml.ts`	XML 工具
`uuid.ts`	UUID 生成
`memoize.ts`	记忆化
`set.ts`	Set 工具
`generators.ts`	生成器工具
`semver.ts`	语义版本
`truncate.ts`	文本截断
`words.ts`	单词工具
`stringUtils.ts`	字符串工具
`treeify.ts`	树形显示
`markdownConfigLoader.ts`	Markdown 配置
`frontmatterParser.ts`	Frontmatter 解析
`zodToJsonSchema.ts`	Zod→JSON Schema 转换

3. 关键子目录

目录	内容
`utils/git/`	Git 高级操作
`utils/messages/`	消息处理细节
`utils/hooks/`	Hook 辅助函数
`utils/permissions/`	权限检查逻辑
`utils/memory/`	内存/记忆管理
`utils/model/`	模型选择与配置
`utils/settings/`	设置同步
`utils/shell/`	Shell 操作封装
`utils/telemetry/`	遥测收集
`utils/swarm/`	Agent 集群
`utils/task/`	任务管理
`utils/todo/`	TODO 管理
`utils/suggestions/`	自动补全建议
`utils/sandbox/`	沙盒实现
`utils/computerUse/`	计算机使用
`utils/processUserInput/`	用户输入处理

4. 导出接口总结

utils/ 的设计原则是按需导入，没有统一的 index.ts，每个文件独立导出。关键的入口函数：

getGlobalConfig() → 获取全局配置
getCwd() / setCwd() → 工作目录管理
loadAllPluginsCacheOnly() → 插件加载
getMainLoopModel() → 获取主循环模型
processUserInput() → 处理用户输入
fetchSystemPromptParts() → 获取系统提示词