01 - 根级文件源码分析

路径: src/*.ts / src/*.tsx 文件数: 18 个

这些文件是整个 Claude Code 应用的核心入口和基础抽象层，定义了应用的启动流程、核心类型和顶层模块导出。

1. main.tsx — 应用主入口

行数: 4683 行

功能概述

应用的最顶层入口文件，负责解析 CLI 参数、初始化环境、选择运行模式并启动对应的屏幕。

核心逻辑

CLI 参数解析 → 环境初始化 → 模式选择 → 渲染对应屏幕

解析命令行参数（--resume, --continue, --print 等）
调用 setup.ts 进行环境初始化
根据参数选择运行模式:
- 交互式 REPL 模式 → 渲染 REPL 屏幕
- 恢复会话模式 → 渲染 ResumeConversation 屏幕
- 诊断模式 → 渲染 Doctor 屏幕
- 非交互式打印模式 → 直接输出
使用 Ink 渲染 React 组件到终端

关键依赖

screens/REPL.tsx — 主交互屏幕
screens/ResumeConversation.tsx — 会话恢复屏幕
screens/Doctor.tsx — 诊断屏幕
setup.ts — 环境初始化
ink/ink.tsx — Ink 渲染器

2. Tool.ts — 工具抽象基类

行数: 792 行

功能概述

定义了 AI 工具的核心抽象。所有工具通过 buildTool(def) 工厂函数构建（不是链式 Builder），接收 ToolDef 对象，返回展开后的 BuiltTool。

导出

buildTool(def) — 工厂函数，将 ToolDef 转为 BuiltTool
ToolDef 类型 — 工具定义接口
BuiltTool 类型 — 构建后的工具对象
TOOL_DEFAULTS — 安全默认值

工厂模式

// 源码 src/Tool.ts:783-792
export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
  return {
    ...TOOL_DEFAULTS,
    userFacingName: () => def.name,
    ...def,
  } as BuiltTool<D>
}

设计亮点

工厂函数 + 对象展开: 不是类继承，而是 TOOL_DEFAULTS 与 def 展开合并
安全默认值: TOOL_DEFAULTS 提供默认权限检查、默认非并发安全等
MCP 集成: 支持 Model Context Protocol 工具协议
60+ 工具: 类型系统通过 0-error typecheck 验证所有工具定义

3. Task.ts — 任务类型定义

行数: 125 行

功能概述

定义后台任务的类型系统，支持 7 种任务类型和 5 种状态。任务 ID 使用 randomBytes(8) 生成，带单字符类型前缀。

导出

TaskType — 任务类型联合类型
TaskStatus — 任务状态联合类型
Task — 任务接口
generateTaskId() — 任务 ID 生成函数

任务类型

类型	说明
`local_bash`	本地 Shell 命令
`local_agent`	本地子 Agent
`remote_agent`	远程 Agent
`in_process_teammate`	进程内队友
`local_workflow`	本地工作流
`monitor_mcp`	MCP 监控
`dream`	后台推理任务

任务状态

pending → running → completed
                  → failed
                  → killed

ID 生成

使用 randomBytes(8) 生成（不是 crypto.randomUUID()）
36 字符字母表（a-z + 0-9）
单字符类型前缀：b=local_bash, a=local_agent, r=remote_agent, t=in_process_teammate, w=local_workflow, m=monitor_mcp, d=dream
36^8 ≈ 2.8 万亿种组合，足以抵抗暴力符号链接攻击

4. QueryEngine.ts — 查询引擎

行数: 1295 行

功能概述

查询引擎的顶层抽象，封装了与 Claude API 的交互逻辑。

核心职责

管理查询生命周期
协调模型调用和工具执行
处理流式响应
管理 token 预算

5. commands.ts — 命令注册中心

行数: 754 行

功能概述

中央命令注册表，聚合来自多个来源的斜杠命令（/help, /commit, /review 等）。

导出

getCommands() — 获取所有可用命令（带缓存）
REMOTE_SAFE_COMMANDS — 远程安全命令集合
BRIDGE_SAFE_COMMANDS — 桥接安全命令集合
INTERNAL_ONLY_COMMANDS — 仅内部使用的命令

命令来源

bundled skills (内置技能)
  + plugin skills (插件技能)
  + skill directories (.skills/ 目录)
  + workflows (工作流)
  + built-in commands (内置命令)
  = 完整命令列表

安全过滤

REMOTE_SAFE: 远程会话中允许执行的命令白名单
BRIDGE_SAFE_COMMANDS: 桥接模式中允许的命令白名单
INTERNAL_ONLY_COMMANDS: 对 AI 隐藏的内部命令

缓存机制

使用 memoization 确保命令只发现一次，后续调用直接返回缓存结果。

6. context.ts — 上下文收集

行数: 189 行

功能概述

收集对话所需的上下文信息，包括 git 仓库状态和系统/用户上下文。

导出

getGitStatus() — 收集 git 状态（memoized）
getSystemContext() — 收集系统上下文（memoized）
getUserContext() — 收集用户上下文（memoized）
setSystemPromptInjection() — 设置缓存破坏注入（调试用）

收集内容

Git 状态: 分支名、工作区状态（截断到 2000 字符）、最近提交、用户信息
CLAUDE.md 文件: 从项目目录树中发现并加载所有 CLAUDE.md 文件
缓存破坏注入: 用于调试的缓存破坏机制

特性

Memoized 缓存，避免重复收集
支持 bare mode（最小上下文）
支持显式添加额外目录
诊断日志带 PII 过滤

7. cost-tracker.ts — 费用追踪器

行数: 323 行

功能概述

全面的 API 使用费用监控系统，支持按模型粒度追踪。

追踪指标

指标	说明
输入 tokens	发送给模型的 token 数
输出 tokens	模型生成的 token 数
缓存读取 tokens	从缓存读取的 token 数
缓存创建 tokens	写入缓存的 token 数
Web 搜索请求	网页搜索调用次数
USD 费用	计算的美元费用

持久化

会话数据持久化到项目配置
支持通过 session ID 跨会话恢复
进程退出时自动保存

8. costHook.ts — 费用摘要 Hook

行数: 22 行

功能概述

React Hook，在进程退出时显示格式化的费用摘要。

导出

useCostSummary() — React Hook

逻辑

使用 useEffect 监听进程退出事件
格式化显示总费用、token 使用量
与计费访问控制系统集成

9. dialogLaunchers.tsx — 对话框启动器

行数: 132 行

功能概述

提供各种对话框的启动函数，用于在 REPL 中弹出模态对话框。

典型对话框

权限确认对话框
设置对话框
模型选择对话框
帮助对话框

10. history.ts — 历史记录管理

行数: ~150 行

功能概述

管理对话历史记录的加载、保存和查询。

核心功能

加载历史会话列表
按项目/仓库过滤会话
渐进式加载（分页）
会话元数据管理（标题、时间戳、消息数）

11. ink.ts — Ink 模块导出

行数: ~30 行

功能概述

Ink 终端 UI 框架的顶层导出文件，重新导出 ink/ 目录中的核心组件和 hooks。

导出内容

React 组件: Box, Text, Spacer 等
Hooks: useInput, useApp, useStdin 等
渲染函数: render

12. interactiveHelpers.tsx 行数**: ~80 行

功能概述

提供交互式 UI 的辅助组件和函数。

典型功能

确认提示
选择列表
进度指示器
错误显示

13. projectOnboardingState.ts — 项目引导状态

行数: ~50 行

功能概述

管理项目首次使用时的引导流程状态。

功能

检测是否为新项目
追踪引导步骤完成状态
持久化引导进度

14. query.ts — 查询入口

行数: 1729 行

功能概述

查询主循环的完整实现（不是简单导出），包含与 Claude API 交互、工具调用处理、流式响应、token 预算管理等核心逻辑。

核心流程

query(messages, tools, config)
  → 构建请求
  → 调用模型（流式）
  → 处理工具调用
  → 返回响应

15. replLauncher.tsx — REPL 启动器

行数: 22 行

16. setup.ts — 环境初始化

行数: ~200 行

功能概述

应用启动时的环境初始化，在 main.tsx 中最先调用。

初始化步骤

设置进程信号处理
初始化日志系统
加载用户配置
初始化 OpenTelemetry
设置错误处理
检查更新
运行配置迁移

17. tasks.ts — 任务模块导出

行数: ~30 行

功能概述

tasks/ 目录的顶层导出文件。

18. tools.ts — 工具模块导出

行数: ~100 行

功能概述

tools/ 目录的顶层导出，注册并导出所有可用的 AI 工具。

注册的工具

Bash — 执行 Shell 命令
Read — 读取文件
Write — 写入文件
Edit — 编辑文件
Glob — 文件模式匹配
Grep — 内容搜索
Agent — 子 Agent 启动
WebFetch — 网页获取
WebSearch — 网页搜索
Notebook — Jupyter Notebook 编辑
TodoWrite — 任务列表管理
更多 MCP 工具…

文件间依赖关系

main.tsx
  ├── setup.ts (初始化)
  ├── context.ts (上下文)
  ├── commands.ts (命令)
  ├── tools.ts (工具)
  │     └── Tool.ts (基类)
  ├── tasks.ts (任务)
  │     └── Task.ts (类型)
  ├── query.ts (查询)
  │     └── QueryEngine.ts (引擎)
  ├── cost-tracker.ts (费用)
  │     └── costHook.ts (Hook)
  └── replLauncher.tsx (启动器)
        └── screens/REPL.tsx (主屏幕)

Keyboard shortcuts

Claude Code 源码深度解析