经过前面28章的深度解析，你应该对Claude Code的架构有了全面了解。但如果你想去源码里亲自看看某个功能的实现，该去哪找？
这份索引手册按功能模块整理了Claude Code的核心源码文件，帮你快速定位想看的内容。
核心架构模块#
Agent Loop核心#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/core/agent.ts | Agent类 | Agent Loop主循环，查询-响应-处理流程 |
src/core/loop.ts | runLoop() | 消息循环执行器，处理用户输入和工具结果 |
src/core/query.ts | processQuery() | 单次查询处理，工具调用与响应生成 |
工具系统#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/tools/base.ts | BaseTool抽象类 | 所有工具的基类，定义通用接口 |
src/tools/registry.ts | ToolRegistry | 工具注册表，管理可用工具列表 |
src/tools/loader.ts | loadTools() | 动态加载工具模块 |
具体工具实现#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/tools/FileReadTool.ts | FileReadTool | 文件读取，支持offset/limit分页 |
src/tools/FileEditTool.ts | FileEditTool | 文件编辑，强制先读取再编辑 |
src/tools/BashTool.ts | BashTool | Bash命令执行，含Git安全协议 |
src/tools/GrepTool.ts | GrepTool | 代码搜索，基于ripgrep |
src/tools/AgentTool.ts | AgentTool | 派生子Agent，支持fork模式 |
src/tools/SkillTool.ts | SkillTool | 技能系统，预算约束管理 |
上下文管理#
自动压缩#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/services/compact/compact.ts | compact() | 手动压缩，摘要生成 |
src/services/compact/autoCompact.ts | autoCompact() | 自动压缩，阈值触发 |
src/services/compact/prompt.ts | 压缩提示词模板 | 定义压缩行为和摘要格式 |
微压缩#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/services/compact/microcompact.ts | microcompact() | 微压缩实现，三机制协同 |
src/services/compact/timeCleaner.ts | timeCleaner() | 时间戳清理器 |
src/services/compact/cacheCleaner.ts | cacheCleaner() | 缓存感知清理器 |
Token预算#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/constants/toolLimits.ts | DEFAULT_MAX_RESULT_SIZE_CHARS | 工具结果大小限制(50K) |
src/constants/toolLimits.ts | MAX_TOOL_RESULTS_PER_MESSAGE_CHARS | 单消息工具结果限制(200K) |
src/utils/tokenEstimator.ts | estimateTokens() | Token估算器，保守策略 |
提示词工程#
系统提示词#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/constants/prompts.ts | getSystemPrompt() | 系统提示词组装 |
src/constants/prompts.ts | getSimpleDoingTasksSection() | 极简主义指令组 |
src/constants/prompts.ts | getGitSafetyProtocol() | Git安全协议 |
动态边界#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/services/prompt/dynamicBoundary.ts | SYSTEM_PROMPT_DYNAMIC_BOUNDARY | 动态边界标记 |
src/services/prompt/promptBuilder.ts | buildPrompt() | 提示词组装器 |
缓存系统#
缓存中断检测#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/services/api/promptCacheBreakDetection.ts | recordPromptState() | 记录提示词状态 |
src/services/api/promptCacheBreakDetection.ts | checkResponseForCacheBreak() | 检测缓存中断 |
src/services/api/promptCacheBreakDetection.ts | perToolHashes | 每个工具的独立哈希 |
缓存优化#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/services/cache/dateMemoization.ts | getMemoizedDate() | 日期记忆化，避免午夜缓存中断 |
src/services/cache/schemaCache.ts | schemaCache | 工具Schema缓存 |
src/services/cache/betaHeaderLatch.ts | afkModeHeaderLatched | Beta Header锁存 |
权限与安全#
权限系统#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/utils/permissions/types.ts | PermissionMode枚举 | 权限模式类型定义 |
src/utils/permissions/modeResolver.ts | resolvePermissionMode() | 权限模式解析 |
src/utils/permissions/denialTracking.ts | DENIAL_LIMITS | 拒绝追踪阈值(3/20) |
src/utils/permissions/denialTracking.ts | shouldFallbackToPrompting() | 回退判定 |
YOLO分类器#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/services/classifier/yoloClassifier.ts | YOLOClassifier类 | YOLO分类器主类 |
src/services/classifier/stage1Fast.ts | stage1Fast() | Stage 1快速过滤 |
src/services/classifier/stage2Deep.ts | stage2Deep() | Stage 2深度推理 |
src/services/classifier/whitelist.ts | isWhitelisted() | 白名单检查 |
Agent系统#
子Agent#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/agents/base.ts | BaseAgent类 | Agent基类 |
src/agents/subAgent.ts | SubAgent类 | 标准子Agent实现 |
src/agents/fork.ts | forkAgent() | Fork模式，继承上下文 |
协调者模式#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/agents/coordinator.ts | CoordinatorAgent类 | 协调者Agent |
src/agents/coordinatorPrompt.ts | 协调者提示词 | “永远不要委托理解” |
src/agents/worker.ts | WorkerAgent类 | Worker Agent |
Agent生命周期#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/agents/lifecycle.ts | registerAsyncAgent() | 注册后台Agent |
src/agents/lifecycle.ts | completeAsyncAgent() | 标记Agent完成 |
src/agents/lifecycle.ts | enqueueAgentNotification() | 结果通知注入 |
记忆系统#
Memdir核心#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/memory/memdir.ts | Memdir类 | 记忆目录管理 |
src/memory/memdir.ts | MEMORY_FILENAME | MEMORY.md索引文件 |
自动提取#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/memory/extractMemories.ts | extractMemories() | 自动记忆提取 |
src/memory/extractAgent.ts | ExtractAgent | 提取专用Agent |
Auto-Dream#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/memory/autoDream.ts | autoDream() | 自动夜间整合 |
src/memory/consolidator.ts | ConsolidatorAgent | 整合Agent |
src/memory/lock.ts | acquireConsolidateLock() | PID锁机制 |
Session Memory#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/memory/sessionMemory.ts | SessionMemory类 | 会话摘要管理 |
src/memory/sessionMemory.ts | summarizeSession() | 会话摘要生成 |
Hooks系统#
Hooks核心#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/hooks/registry.ts | HookRegistry | Hook注册表 |
src/hooks/dispatcher.ts | dispatchHook() | Hook分发器 |
src/hooks/types.ts | HookType枚举 | Hook类型定义 |
具体Hook实现#
| 文件路径 | 事件名 | 触发时机 |
|---|
src/hooks/commandHooks.ts | before:command | 命令执行前 |
src/hooks/commandHooks.ts | after:command | 命令执行后 |
src/hooks/agentHooks.ts | before:agent | Agent调用前 |
src/hooks/agentHooks.ts | after:agent | Agent调用后 |
src/hooks/httpHooks.ts | before:http | HTTP请求前 |
src/hooks/httpHooks.ts | after:http | HTTP响应后 |
技能系统#
技能核心#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/skills/registry.ts | SkillRegistry | 技能注册表 |
src/skills/loader.ts | loadSkill() | 技能加载器 |
src/skills/types.ts | Skill接口 | 技能类型定义 |
技能存储#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/skills/storage.ts | getSkillStoragePath() | 获取技能存储路径 |
src/skills/storage.ts | loadSkillManifest() | 加载技能清单 |
Feature Flags#
Flag定义#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/featureFlags/flags.ts | feature()函数 | 构建时Flag检查 |
src/featureFlags/flags.ts | KAIROS | KAIROS模式Flag |
src/featureFlags/flags.ts | TRANSCRIPT_CLASSIFIER | 分类器Flag |
远程配置#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/featureFlags/remote.ts | getRemoteFlag() | 获取远程Flag值 |
src/featureFlags/growthbook.ts | GrowthBookClient | GrowthBook客户端 |
配置与设置#
配置文件#
| 文件路径 | 用途 | 说明 |
|---|
CLAUDE.md | 项目级配置 | 编码规范、架构约束 |
.claude/settings.json | 用户设置 | 个人偏好、功能开关 |
.claude/settings.local.json | 本地设置 | 机器特定配置 |
设置管理#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/settings/loader.ts | loadSettings() | 设置加载器 |
src/settings/validator.ts | validateSettings() | 设置验证器 |
src/settings/types.ts | Settings接口 | 设置类型定义 |
实用工具#
Git操作#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/utils/git/status.ts | getGitStatus() | 获取Git状态 |
src/utils/git/diff.ts | getGitDiff() | 获取Git差异 |
src/utils/git/worktree.ts | createWorktree() | 创建git worktree |
文件操作#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/utils/file/reader.ts | readFile() | 文件读取，分页支持 |
src/utils/file/writer.ts | writeFile() | 文件写入 |
src/utils/file/watcher.ts | FileWatcher | 文件变更监听 |
网络请求#
| 文件路径 | 核心类/函数 | 功能说明 |
|---|
src/utils/http/client.ts | HttpClient | HTTP客户端 |
src/utils/http/retry.ts | retryRequest() | 请求重试逻辑 |
快速查找索引#
按功能查找#
| 你想了解… | 先看这里 |
|---|
| Agent Loop怎么工作 | src/core/agent.ts, src/core/loop.ts |
| 工具怎么定义 | src/tools/base.ts, 各工具文件 |
| 上下文怎么压缩 | src/services/compact/目录 |
| Token预算怎么算 | src/constants/toolLimits.ts |
| 系统提示词怎么组装 | src/constants/prompts.ts |
| 缓存怎么优化 | src/services/cache/目录 |
| 权限怎么判断 | src/utils/permissions/目录 |
| YOLO分类器怎么工作 | src/services/classifier/目录 |
| 子Agent怎么派生 | src/agents/subAgent.ts |
| Fork模式怎么实现 | src/agents/fork.ts |
| 记忆怎么存储 | src/memory/memdir.ts |
| 自动提取怎么工作 | src/memory/extractMemories.ts |
| Auto-Dream怎么触发 | src/memory/autoDream.ts |
| Hooks怎么用 | src/hooks/目录 |
| 技能怎么加载 | src/skills/目录 |
| Feature Flag怎么定义 | src/featureFlags/flags.ts |
| 设置怎么读取 | src/settings/loader.ts |
按问题查找#
| 你有这个问题… | 查这些文件 |
|---|
| 为什么编辑前要读取 | src/tools/FileEditTool.ts |
| 为什么Git操作有安全限制 | src/tools/BashTool.ts提示词 |
| 压缩后怎么恢复文件 | src/services/compact/compact.ts |
| Token估算为什么保守 | src/utils/tokenEstimator.ts |
| 缓存为什么中断 | src/services/api/promptCacheBreakDetection.ts |
| 分类器为什么拒绝 | src/services/classifier/yoloClassifier.ts |
| 协调者为什么不编码 | src/agents/coordinatorPrompt.ts |
| 记忆为什么不生效 | src/memory/memdir.ts, src/memory/extractMemories.ts |
| Hooks为什么不触发 | src/hooks/dispatcher.ts |
使用建议#
阅读源码的顺序#
- 先看接口定义：
types.ts文件了解数据结构和契约 - 再看主流程：核心类的入口方法，把握整体逻辑
- 最后看细节：具体实现、边界条件、错误处理
调试技巧#
- 环境变量：
CLAUDE_CODE_DEBUG=1开启调试日志 - 日志位置：
~/.claude/logs/查看详细日志 - API日志：
CLAUDE_CODE_DUMP_AUTO_MODE=1导出分类器输入输出
贡献代码#
- 编码规范：参考
CLAUDE.md中的项目规范 - 测试要求：修改核心模块需要配套测试
- 文档同步：代码变更同步更新相关文档
这份索引手册涵盖了Claude Code的主要源码文件。随着版本迭代，文件路径可能会有变化，但核心架构和设计理念保持稳定。建议收藏，需要时快速查阅。
