本章总览
src/utils/ 是 Claude Code 的「基础设施层」：消息工厂、会话 JSONL 持久化、权限规则引擎、用户 Shell Hook 编排等横切能力都集中在此（数百个文件）。务必区分：utils/hooks.ts（用户配置的 Shell Hook）≠ src/hooks/（React UI Hooks 目录）。
总览图
渲染图表中…
学完本章你应该能
- 建立 utils 四大子主题的阅读顺序
- 能在源码树中从本页跳转到子章节
- 理解 messages / sessionStorage / permissions / hooks.ts 的协作边界
建议学习步骤
- 浏览下方子章节导航表，选择入口主题
- 点击模块源码树中的高亮文件跳转到对应讲解
- 建议顺序：messages → session-storage → permissions → shell-hooks
模块在架构中的位置
utils 是 src/ 下的一级目录，共 570 个文件、181,060 行。一句话概括：最大模块：消息格式化、会话持久化、配置、权限、Hooks、Token 计数、Bash 解析等通用能力。
模块 UML 图表
JSONL 转录写入流程
渲染图表中…
会话存储 ER 图
渲染图表中…
概览
| 指标 | 数值 |
|---|---|
| 行数 | 181,060 |
| 文件 | 570 |
子章节导航
| 子章节 | 主题 | 核心路径 |
|---|---|---|
| messages | 消息构造、规范化、配对修复 | utils/messages.ts |
| session-storage | JSONL 转录、parentUuid 链 | utils/sessionStorage.ts |
| permissions | 规则加载与 hasPermissionsToUseTool | utils/permissions/ |
| shell-hooks | 用户 Shell Hook 执行引擎 | utils/hooks.ts |
与其他模块的边界
messages.ts 产出 Message 联合类型实例，供 query 循环与 REPL 渲染；sessionStorage.ts 决定哪些消息写入 ~/.claude/projects/.../*.jsonl；permissions/ 在 tool_use 前返回 allow/deny/ask；hooks.ts 在 PreToolUse、PermissionRequest、Stop 等事件点执行用户脚本。
阅读 hooks 目录下的 useCanUseTool 时，请回到本模块的 permissions 与 shell-hooks 两章对照：前者做规则求值，后者可在 PermissionRequest 时改写决策。
本章小结与延伸
utils 模块按数据流拆分：先懂消息形态，再懂落盘，再懂权限决策，最后懂 Hook 扩展点。 继续学习：