本章总览
src/types/ 是 Claude Code 的「纯类型与契约层」：19 个文件、约 3636 行，几乎不含运行时逻辑（permissions.ts 除外有常量数组）。类型按域拆分——message、command、permissions、hooks、plugin、tools 等——目的是 打破 import 循环、让 utils/services/components 共享同一套 TS 契约，而不互相拉入 React 或 Tool 实现。
学完本章你应该能
- 理解 types/ 在架构中的「零依赖枢纽」角色
- 区分 message 联合类型与 transcript 渲染类型
- 知道 permissions.ts 为何从 utils/permissions 抽离
- 能定位 command 三种形态（prompt / local / local-jsx）的类型定义
- 了解 hooks.ts 与 entrypoints/agentSdkTypes 的类型复用关系
- 会从子章节跳转到 generated/ protobuf 事件类型
建议学习步骤
- 浏览下方子章节导航表，按域选择入口
- 点击 SourceTree module=types 查看完整目录树
- 建议顺序：message-types → tool-permission-types → api-sdk-types → misc-types
模块在架构中的位置
types 是 src/ 下的一级目录，共 19 个文件、3,636 行。建议结合「系统架构」章节理解它与其他层的调用关系。
概览
| 指标 | 数值 |
|---|---|
| 行数 | 3,636 |
| 文件 | 19 |
子章节导航
| 子章节 | 主题 | 核心路径 |
|---|---|---|
| message-types | Message 联合、content blocks | types/message.ts |
| tool-permission-types | Tool、Permission、Command | types/tools.ts, permissions.ts, command.ts |
| api-sdk-types | Hooks、SDK 协议类型 | types/hooks.ts, entrypoints/agentSdkTypes |
| misc-types | ids、plugin、logs、generated | ids.ts, plugin.ts, generated/ |
为何单独建 types/ 目录
Claude Code 单体仓库 import 图极深：Tool → utils/permissions → hooks → state → components。若在 utils 内定义 PermissionRule，hooks 与 types/message 会形成环。
types/ 的设计原则：
| 原则 | 体现 |
|---|---|
| 纯类型优先 | message.ts、tools.ts 只有 type/export，无函数 |
| 常量与类型同文件 | permissions.ts 导出 EXTERNAL_PERMISSION_MODES 供 runtime 校验 |
| 重类型轻实现 | command.ts 引用 ToolUseContext 但不 import Tool 实现 |
| generated 隔离 | protobuf 生成物放在 types/generated/，手改类型与其并列 |
改 transcript 形状时，通常先改 types/message.ts，再让 utils/messages、components 跟随编译错误修复。
文件域划分（19 文件）
| 簇 | 文件 | 行量级 | 消费方 |
|---|---|---|---|
| 消息 | message.ts, messageQueueTypes.ts | ~200 | REPL、compact、bridge |
| 命令 | command.ts | ~220 | commands/、skills |
| 权限 | permissions.ts | ~440 | useCanUseTool、Permission UI |
| 工具进度 | tools.ts | ~20 | BashTool、AgentTool streaming |
| Hooks 协议 | hooks.ts | ~290 | Shell hooks、SDK |
| 插件 | plugin.ts | ~360 | /plugin、marketplace |
| 输入/UI | textInputTypes.ts, statusLine.ts, fileSuggestion.ts | 小 | PromptInput、statusline |
| 标识 | ids.ts | ~45 | session、agent、teammate |
| 生成 | generated/events_mono/* | ~2500 | analytics、GrowthBook |
utils.ts 提供 DeepImmutable 等类型工具；connectorText.ts、notebook.ts 服务特定 UI 或导出格式。
目录树展示 src/types/ 全部 19 个文件（含 generated/ 子树）。highlightFiles 与子章节 sources 锚点可在页面内跳转到具体行号。
与其他模块的边界
| 协作方 | 关系 |
|---|---|
| utils/messages.ts | 构造 Message 实例；类型来自 message.ts |
| entrypoints/agentSdkTypes.ts | HookEvent、PermissionUpdate 被 hooks.ts re-export/扩展 |
| state/AppStateStore.ts | 不 import types/ 全集，按需引用 PermissionMode 等 |
| services/compact | CompactMetadata、Message 子类型 |
| bridge/* | NormalizedMessage、RenderableMessage |
勿混淆：src/types/hooks.ts（Hook JSON 协议）≠ src/hooks/（React Hooks 目录）。前者在 api-sdk-types 子章节详解。
本章小结与延伸
types 模块 = 全栈共享的类型词汇表。先读 message 与 permission 子集（与 REPL 渲染、权限 UI 直接相关），再读 hooks/API 类型与剩余辅助类型。 继续学习：