分析日期: 2026-03-31 项目: Claude Code CLI 技术栈: TypeScript/Node.js/Bun 文档版本: 1.0
Claude Code 是一个基于终端的交互式 AI 编程助手 CLI 工具，运行在 Bun/Node.js 运行时上，深度集成 Anthropic Claude API，提供代码编辑、文件操作、终端执行、多智能体协作等功能。
职责: 应用程序启动、配置加载、会话初始化
关键组件:
main.tsx(804KB) - 主入口文件，负责 CLI 命令解析、会话设置、REPL 启动setup.ts- 会话初始化逻辑，包括 UDS 通信、终端备份恢复、Git 工作区设置
启动流程:
CLI 参数解析 → 环境检查 (Node.js 版本) → 权限模式初始化 →
MDM/Keychain 预取 → 插件/技能加载 → UDS 通信服务器 →
终端备份恢复 → Git 工作区创建 → REPL 启动
核心代码位置:
src/main.tsx:1-200- 导入与初始化src/setup.ts:56-200- setup 函数
职责: 定义和管理所有可供 AI 调用的工具
工具类型:
| 工具类型 | 前缀 | 说明 |
|---|---|---|
local_bash |
b |
本地 Bash 命令执行 |
local_agent |
a |
本地子代理执行 |
remote_agent |
r |
远程代理执行 |
in_process_teammate |
t |
进程内协作者 |
local_workflow |
w |
本地工作流 |
monitor_mcp |
m |
MCP 监控 |
dream |
d |
Dream 模式 |
核心工具列表:
AgentTool- 子代理管理BashTool- Bash 命令执行FileReadTool/FileEditTool/FileWriteTool- 文件操作GlobTool/GrepTool- 文件搜索WebFetchTool/WebSearchTool- 网络请求TodoWriteTool/TaskCreateTool/TaskUpdateTool- 任务管理SkillTool- 技能系统ListMcpResourcesTool/ReadMcpResourceTool- MCP 资源LSPTool- 语言服务器协议
工具定义接口 (src/Tool.ts:362-695):
export type Tool<Input, Output, Progress> = {
name: string
call(args, context, canUseTool, parentMessage, onProgress): Promise<ToolResult>
description(input, options): Promise<string>
inputSchema: ZodType
outputSchema?: ZodType
isConcurrencySafe(input): boolean
isReadOnly(input): boolean
isDestructive?(input): boolean
checkPermissions(input, context): Promise<PermissionResult>
validateInput?(input, context): Promise<ValidationResult>
renderToolUseMessage(input, options): React.ReactNode
renderToolResultMessage(content, options): React.ReactNode
// ... 更多渲染和配置方法
}职责: 处理 AI API 请求、消息流、工具编排
核心功能:
- 消息规范化与 API 请求构建
- 流式响应处理
- 工具调用编排 (
src/services/tools/toolOrchestration.ts) - Token 预算管理 (
src/query/tokenBudget.ts) - 自动压缩 (
src/services/compact/autoCompact.ts) - 思考块处理
查询流程:
消息接收 → 上下文构建 → Token 检查 → API 请求 →
流式响应 → 工具调用 → 结果处理 → 消息更新
关键代码:
src/query.ts:181-QueryParams 和主查询循环src/services/tools/toolOrchestration.ts- runTools 函数
职责: 用户可执行的 slash 命令 (/help, /config, /skills 等)
命令类型:
prompt- 扩展为文本提示local- 本地执行产生文本输出local-jsx- 渲染 Ink UI 组件
命令注册流程 (src/commands.ts:256-520):
const COMMANDS = memoize((): Command[] => [
addDir, advisor, agents, branch, /* ... 80+ 内置命令 */
])
// 动态技能加载
async function getSkills(cwd): Promise<{
skillDirCommands: Command[]
pluginSkills: Command[]
bundledSkills: Command[]
builtinPluginSkills: Command[]
}>核心命令分类:
| 类别 | 命令示例 |
|---|---|
| 会话管理 | /session, /resume, /compact, /clear |
| 配置 | /config, /model, /theme, /permissions |
| 工具 | /mcp, /skills, /plugins, /hooks |
| 调试 | /debug-tool-call, /heapdump, /ant-trace |
| 协作 | /review, /pr_comments, /commit |
职责: 管理应用程序全局状态
AppState 核心字段:
interface AppState {
messages: Message[] // 对话消息历史
tools: Tools // 可用工具
mcp: { // MCP 配置
tools: Command[]
commands: Command[]
resources: Record<string, ServerResource[]>
}
permissionContext: ToolPermissionContext
tasks: Task[] // 任务列表
// ... 更多状态字段
}状态更新模式:
type SetAppState = (f: (prev: AppState) => AppState) => void采用不可变更新模式，通过函数式更新确保状态一致性。
职责: 工具调用权限控制
权限模式 (src/utils/permissions/PermissionMode.ts):
default- 默认模式auto- 自动模式bypass- 绕过模式
权限检查流程:
工具调用 → validateInput() → checkPermissions() →
deny rules 匹配 → 用户确认 (如需) → 执行
权限上下文 (src/Tool.ts:123-148):
export type ToolPermissionContext = {
mode: PermissionMode
additionalWorkingDirectories: Map<string, AdditionalWorkingDirectory>
alwaysAllowRules: ToolPermissionRulesBySource
alwaysDenyRules: ToolPermissionRulesBySource
alwaysAskRules: ToolPermissionRulesBySource
isBypassPermissionsModeAvailable: boolean
isAutoModeAvailable?: boolean
}职责: Model Context Protocol 服务器集成
核心功能:
- MCP 服务器连接管理 (
src/services/mcp/client.ts) - 资源配置 (
src/services/mcp/config.ts) - 工具桥接 (
src/services/mcp/types.ts)
MCP 工具类型:
interface MCPServerConnection {
serverName: string
status: 'connected' | 'disconnected' | 'error'
tools: Tool[]
resources: ServerResource[]
}职责: 可扩展的技能/插件机制
技能类型:
- Bundled Skills - 内置技能
- Directory Skills -
/skills/目录加载 - Plugin Skills - 插件提供
- MCP Skills - MCP 服务器提供
技能加载流程 (src/commands.ts:353-398):
async function getSkills(cwd) {
const skillDirCommands = await getSkillDirCommands(cwd)
const pluginSkills = await getPluginSkills()
const bundledSkills = getBundledSkills()
const builtinPluginSkills = getBuiltinPluginSkillCommands()
return { skillDirCommands, pluginSkills, bundledSkills, builtinPluginSkills }
}职责: 终端界面渲染 (基于 Ink/React)
核心组件:
src/ink/renderer.ts- 渲染引擎src/ink/layout/engine.ts- 布局引擎 (基于 Yoga)src/ink/events/- 事件处理 (键盘、鼠标、焦点)src/components/- UI 组件库
渲染流程:
React 组件 → Fiber 协调 → Yoga 布局 → 终端输出
职责: 遥测、API 通信、重试机制
核心服务:
src/services/analytics/- 事件日志、GrowthBook 功能开关src/services/api/- API 客户端、重试逻辑、错误处理src/services/compact/- 上下文压缩src/services/lsp/- 语言服务器管理src/services/plugins/- 插件管理src/services/policyLimits/- 策略限制
┌─────────────────────────────────────────────────────────────┐
│ main.tsx │
│ (入口：CLI 解析、初始化、REPL 启动) │
└─────────────────────────────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ setup.ts │ │ commands.ts │ │ tools.ts │
│ (会话初始化) │ │ (命令系统) │ │ (工具集合) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ query.ts │
│ (AI 请求处理、工具编排、流式响应) │
└─────────────────────────────────────────────────────────────┘
│
┌────────────────────┼────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ services/api/ │ │services/mcp/ │ │ services/compact│
│ (API 通信) │ │ (MCP 集成) │ │ (上下文压缩) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
位置: src/query.ts vs src/commands.ts
- 查询侧:
query.ts处理 AI 对话请求、工具调用 - 命令侧:
commands.ts处理用户 slash 命令
优点:
- 清晰的职责边界
- 独立演进能力
- 不同的权限和审计策略
位置: src/Tool.ts, src/tools/*
这是项目的核心架构模式，所有功能都通过 Tool 接口暴露：
export type Tool = {
call(args, context, canUseTool, parentMessage, onProgress): Promise<ToolResult>
// ... 配置和渲染方法
}实现分析:
- 符合策略模式 - 每个工具是一种策略实现
- 支持装饰器模式 -
buildTool()函数添加默认行为 - 统一的权限检查接口 -
checkPermissions()
代码示例 (src/Tool.ts:757-792):
const TOOL_DEFAULTS = {
isEnabled: () => true,
isConcurrencySafe: () => false,
isReadOnly: () => false,
checkPermissions: (input) => Promise.resolve({ behavior: 'allow', updatedInput: input }),
}
export function buildTool<D extends AnyToolDef>(def: D): BuiltTool<D> {
return { ...TOOL_DEFAULTS, ...def }
}位置: src/state/Store.ts, src/bootstrap/state.ts
模式:
type SetAppState = (f: (prev: AppState) => AppState) => void优点:
- 可预测的状态变更
- 支持时间旅行调试
- 安全的并发更新
位置: src/Tool.ts:158-300
export type ToolUseContext = {
options: { commands, tools, mcpClients, ... }
abortController: AbortController
getAppState(): AppState
setAppState(f: (prev) => prev): void
readFileState: FileStateCache
// ... 更多依赖
}所有工具通过上下文获取依赖，而非直接导入。
位置:
src/utils/hooks/fileChangedWatcher.tssrc/utils/settings/changeDetector.tssrc/utils/skills/skillChangeDetector.ts
实现:
initializeFileChangedWatcher(cwd) // 文件变更监听
settingsChangeDetector() // 设置变更监听
skillChangeDetector() // 技能变更监听位置: src/utils/permissions/PermissionMode.ts
不同权限模式决定工具调用的审批流程：
default- 标准审批auto- 自动审批 (有护栏)bypass- 完全绕过
| 模式 | 位置 | 说明 |
|---|---|---|
| Builder | src/Tool.ts:buildTool() |
构建完整工具对象 |
| Strategy | src/tools/* |
每个工具是一种策略 |
| Decorator | src/Tool.ts:TOOL_DEFAULTS |
为工具添加默认行为 |
| Singleton | src/state/Store.ts |
全局状态存储 |
| Observer | src/utils/hooks/ |
文件/设置变更监听 |
| Command | src/commands.ts |
用户命令封装 |
| Template Method | src/query.ts |
查询循环模板 |
| Factory | src/tools/AgentTool/ |
代理实例创建 |
| Adapter | src/services/mcp/ |
MCP 协议适配 |
| Facade | src/tools.ts |
工具池组装 |
┌─────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ src/main.tsx, src/ink/, src/components/ (终端 UI) │
├─────────────────────────────────────────────────────────┤
│ Application Layer │
│ src/commands.ts, src/tools/, src/query.ts (业务逻辑) │
├─────────────────────────────────────────────────────────┤
│ Domain Layer │
│ src/Tool.ts, src/Task.ts, src/types/ (领域模型) │
├─────────────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ src/services/, src/utils/ (外部服务、工具函数) │
└─────────────────────────────────────────────────────────┘
这是一个典型的 Clean Architecture 变体，依赖方向由外向内。
- 高度模块化 - 工具、命令、服务职责清晰
- 可扩展性强 - 通过工具/技能/插件机制
- 类型安全 - TypeScript 严格模式 + Zod 验证
- 测试友好 - 依赖注入 + 接口抽象
- 功能开关 - GrowthBook 集成支持渐进发布
- 循环依赖风险 - 多处使用
require()懒加载打破循环 - 条件编译复杂 -
feature()标志遍布代码库 - 大文件问题 -
main.tsx(804KB)、query.ts(69KB) - 隐式耦合 - 部分模块依赖全局状态 (
AppState)
graph TB
subgraph "终端用户界面层"
CLI[CLI 入口 main.tsx]
REPL[REPL 交互]
InkUI[Iink React 组件]
end
subgraph "应用服务层"
Commands[命令系统 commands.ts]
Tools[工具系统 tools.ts]
Query[查询引擎 query.ts]
State[状态管理 AppState]
end
subgraph "核心工具层"
AgentTool[AgentTool]
BashTool[BashTool]
FileTools[FileRead/Edit/Write]
SkillTool[SkillTool]
TaskTools[TaskCreate/Update/List]
end
subgraph "基础设施服务"
API[Anthropic API]
MCP[MCP Servers]
LSP[LSP Servers]
Hooks[Hooks 系统]
Analytics[Analytics]
end
subgraph "外部依赖"
Git[Git]
FS[文件系统]
Shell[Bash/Shell]
Network[网络]
end
CLI --> REPL
REPL --> InkUI
REPL --> Commands
REPL --> Query
Commands --> Tools
Query --> Tools
Tools --> AgentTool
Tools --> BashTool
Tools --> FileTools
Tools --> SkillTool
Tools --> TaskTools
AgentTool --> Query
BashTool --> Shell
FileTools --> FS
SkillTool --> Hooks
Query --> API
Tools --> MCP
Tools --> LSP
State -.-> Commands
State -.-> Query
State -.-> Tools
Hooks --> FS
Analytics --> API
sequenceDiagram
participant AI as Claude AI
participant Query as Query Engine
participant Tool as Tool System
participant Perm as Permission System
participant Exec as Tool Executor
participant State as AppState
AI->>Query: 流式响应含 tool_use
Query->>Tool: 解析 tool_use 块
Tool->>Tool: validateInput()
alt 验证失败
Tool-->>Query: 返回错误
Query-->>AI: 错误消息
else 验证通过
Tool->>Perm: checkPermissions()
Perm->>Perm: 匹配 deny rules
alt 被拒绝
Perm-->>Tool: 拒绝
Tool-->>Query: 权限错误
else 需要确认
Perm->>State: 触发权限对话框
State-->>AI: 等待用户确认
alt 用户确认
State-->>Perm: 确认
else 用户拒绝
State-->>Perm: 拒绝
end
else 自动允许
Perm-->>Tool: 允许
end
Tool->>Exec: 执行工具
Exec->>Exec: 调用实际实现
Exec-->>Tool: 工具结果
Tool->>State: 更新状态
State-->>Query: 新消息
Query->>AI: 发送 tool_result
end
flowchart TD
Start[开始查询] --> BuildConfig[构建查询配置]
BuildConfig --> CheckBudget[检查 Token 预算]
CheckBudget -->|超出预算 | BudgetError[预算错误]
CheckBudget -->|正常 | SendRequest[发送 API 请求]
SendRequest --> StreamLoop{流式循环}
StreamLoop -->|thinking 块 | HandleThinking[处理思考]
StreamLoop -->|tool_use | HandleTool[处理工具调用]
StreamLoop -->|text 内容 | HandleText[处理文本]
StreamLoop -->|error | HandleError[处理错误]
StreamLoop -->|done | EndLoop{循环结束}
HandleTool --> RunTools[执行 runTools]
RunTools --> CollectResults[收集结果]
CollectResults --> ContinueLoop[继续循环]
HandleThinking --> ContinueLoop
HandleText --> ContinueLoop
EndLoop -->|需要继续 | SendRequest
EndLoop -->|完成 | Finalize[完成查询]
HandleError -->|max_output_tokens | RetryWithRecovery[恢复重试]
HandleError -->|其他错误 | ReportError[报告错误]
RetryWithRecovery --> SendRequest
目标模块: src/main.tsx (804KB), src/query.ts (69KB)
当前问题:
- 单文件过大，难以理解和维护
- 隐式耦合多，测试困难
- 新人上手成本高
实施方案:
-
将
main.tsx拆分为多个子模块:main.cli.ts- CLI 参数解析main.session.ts- 会话管理main.repl.ts- REPL 启动main.dialogs.ts- 对话框启动器
-
将
query.ts拆分:query.loop.ts- 主循环query.budget.ts- Token 预算 (已有部分)query.compact.ts- 压缩逻辑query.hooks.ts- Hook 处理 (已有部分)
预期收益:
- 可维护性提升 50%+
- 代码审查效率提升
- 并行开发更容易
风险与成本:
- 需要仔细处理导入路径
- 可能需要 2-3 天重构时间
- 需要全面回归测试
目标区域: src/state/, src/tools/, src/query/
当前问题:
- 工具直接调用
setAppState()更新状态 - 状态变更逻辑分散在各处
- 难以追踪状态变更来源
实施方案:
引入领域事件总线:
// 新增 src/domain/events.ts
export type DomainEvent =
| { type: 'TOOL_CALLED'; toolName: string; input: unknown }
| { type: 'TOOL_COMPLETED'; toolName: string; result: unknown }
| { type: 'MESSAGE_ADDED'; message: Message }
| { type: 'TASK_CREATED'; taskId: string }
// ...
export type EventHandler = (event: DomainEvent) => void
export class EventBus {
private handlers: Map<string, EventHandler[]> = new Map()
subscribe(type: string, handler: EventHandler): () => void
publish(event: DomainEvent): void
}状态更新集中化:
// 新增 src/state/reducer.ts
export function appStateReducer(
state: AppState,
event: DomainEvent
): AppState {
switch (event.type) {
case 'MESSAGE_ADDED':
return { ...state, messages: [...state.messages, event.message] }
case 'TASK_CREATED':
return { ...state, tasks: [...state.tasks, event.task] }
// ...
}
}预期收益:
- 状态变更可追溯
- 支持事件回放调试
- 更容易添加副作用处理
风险与成本:
- 需要迁移现有
setAppState调用 - 约 1-2 周迁移时间
- 需要事件schema 版本管理
目标区域: src/services/tools/toolOrchestration.ts
当前问题:
- 工具调用链路不透明
- 性能瓶颈难以定位
- 调试复杂工具交互困难
实施方案:
添加结构化日志:
// 新增 src/utils/observability/toolTracing.ts
export function traceToolCall<T>(
toolName: string,
input: unknown,
fn: () => Promise<T>
): Promise<T> {
const span = startSpan({
name: `tool:${toolName}`,
attributes: { input: sanitize(input) }
})
try {
const result = await fn()
span.end({ status: 'ok', result: sanitize(result) })
return result
} catch (error) {
span.end({ status: 'error', error })
throw error
}
}添加性能指标:
// 新增 src/utils/observability/metrics.ts
export interface ToolMetrics {
toolName: string
callCount: number
avgDurationMs: number
p95DurationMs: number
errorRate: number
}
export function recordToolMetric(toolName: string, durationMs: number, success: boolean)
export function getToolMetrics(): Map<string, ToolMetrics>预期收益:
- 工具性能可视化
- 快速定位慢工具
- 支持容量规划
风险与成本:
- 额外性能开销 (<5%)
- 需要指标存储和展示
- 约 3-5 天实施
目标区域: 全局
当前问题:
- 错误处理不一致 (throw vs return vs log)
- 错误消息对用户不友好
- 错误恢复策略分散
实施方案:
定义统一错误类型:
// 新增 src/errors/AppError.ts
export abstract class AppError extends Error {
abstract readonly code: string
abstract readonly severity: 'low' | 'medium' | 'high' | 'critical'
abstract readonly userMessage: string
readonly context?: Record<string, unknown>
constructor(message: string, context?: Record<string, unknown>) {
super(message)
this.context = context
}
}
export class ToolExecutionError extends AppError {
readonly code = 'TOOL_EXECUTION_ERROR'
readonly severity = 'medium'
readonly userMessage = '工具执行失败，请检查输入或重试'
}
export class PermissionDeniedError extends AppError {
readonly code = 'PERMISSION_DENIED'
readonly severity = 'low'
readonly userMessage = '操作被拒绝：权限不足'
}统一错误边界:
// 新增 src/errors/ErrorBoundary.tsx
export function withErrorBoundary<T>(
fn: () => Promise<T>,
handler: (error: AppError) => T
): Promise<T>预期收益:
- 一致的用户体验
- 更容易添加错误恢复
- 支持错误分析和告警
claude-code/
├── src/ # 核心源代码
│ ├── main.tsx # 主入口 (804KB)
│ ├── setup.ts # 会话初始化
│ ├── query.ts # AI 查询引擎 (69KB)
│ ├── QueryEngine.ts # 查询引擎类 (47KB)
│ ├── commands.ts # 命令系统 (25KB)
│ ├── tools.ts # 工具集合 (17KB)
│ ├── Tool.ts # 工具类型定义 (29KB)
│ ├── Task.ts # 任务类型定义
│ ├── context.ts # 上下文获取 (Git, CLAUDE.md)
│ ├── history.ts # 会话历史
│ ├── replLauncher.tsx # REPL 启动器
│ │
│ ├── assistant/ # 助手模式
│ ├── bootstrap/ # 启动状态管理
│ ├── bridge/ # 桥接模式 (远程会话)
│ ├── buddy/ # Buddy 功能
│ ├── cli/ # CLI 子命令
│ │ ├── handlers/ # 命令处理器
│ │ └── transports/ # 传输层 (SSE, WebSocket)
│ │
│ ├── commands/ # Slash 命令实现
│ │ ├── add-dir/ # /add-dir
│ │ ├── agents/ # /agents
│ │ ├── config/ # /config
│ │ ├── mcp/ # /mcp
│ │ ├── permissions/ # /permissions
│ │ ├── skills/ # /skills
│ │ └── ... (80+ 命令目录)
│ │
│ ├── components/ # React 组件
│ │ ├── CustomSelect/ # 自定义选择器
│ │ └── design-system/ # 设计系统
│ │
│ ├── constants/ # 常量定义
│ │ ├── apiLimits.ts # API 限制
│ │ ├── tools.ts # 工具常量
│ │ └── ...
│ │
│ ├── coordinator/ # 协调器模式
│ ├── entrypoints/ # 入口点类型
│ ├── hooks/ # React Hooks
│ │ ├── toolPermission/ # 权限 Hooks
│ │ └── ...
│ │
│ ├── ink/ # 终端 UI 引擎
│ │ ├── components/ # Ink 组件
│ │ ├── events/ # 事件系统
│ │ ├── hooks/ # Ink Hooks
│ │ ├── layout/ # 布局引擎 (Yoga)
│ │ └── ...
│ │
│ ├── keybindings/ # 键盘绑定
│ ├── memdir/ # 记忆目录
│ ├── migrations/ # 数据迁移
│ ├── moreright/ # (内部模块)
│ ├── native-ts/ # 原生 TypeScript 绑定
│ ├── outputStyles/ # 输出样式
│ ├── plugins/ # 插件系统
│ ├── query/ # 查询子模块
│ │ ├── config.ts # 查询配置
│ │ ├── deps.ts # 查询依赖
│ │ ├── stopHooks.ts # 停止 Hooks
│ │ ├── tokenBudget.ts # Token 预算
│ │ └── transitions.ts # 状态转换
│ │
│ ├── remote/ # 远程会话
│ ├── screens/ # 屏幕管理
│ ├── schemas/ # Zod schemas
│ ├── server/ # 服务器功能
│ ├── services/ # 基础设施服务
│ │ ├── analytics/ # 分析服务
│ │ ├── api/ # API 客户端
│ │ ├── compact/ # 上下文压缩
│ │ ├── lsp/ # LSP 管理
│ │ ├── mcp/ # MCP 集成
│ │ ├── plugins/ # 插件管理
│ │ ├── policyLimits/ # 策略限制
│ │ ├── remoteManagedSettings/ # 远程设置
│ │ ├── SessionMemory/ # 会话记忆
│ │ ├── tips/ # 提示系统
│ │ └── tools/ # 工具服务
│ │ ├── StreamingToolExecutor.ts
│ │ └── toolOrchestration.ts
│ │
│ ├── skills/ # 技能系统
│ │ ├── bundled/ # 内置技能
│ │ └── loadSkillsDir.ts # 技能加载
│ │
│ ├── state/ # 状态管理
│ │ ├── AppState.tsx # 状态定义
│ │ ├── AppStateStore.ts # 状态存储
│ │ ├── onChangeAppState.ts # 状态变更监听
│ │ └── Store.ts # Store 实现
│ │
│ ├── tasks/ # 任务功能
│ ├── tools/ # 工具实现
│ │ ├── AgentTool/ # 代理工具
│ │ ├── BashTool/ # Bash 工具
│ │ ├── FileEditTool/ # 文件编辑
│ │ ├── FileReadTool/ # 文件读取
│ │ ├── FileWriteTool/ # 文件写入
│ │ ├── SkillTool/ # 技能工具
│ │ ├── TaskCreateTool/ # 任务创建
│ │ ├── TodoWriteTool/ # TODO 工具
│ │ ├── WebFetchTool/ # 网页抓取
│ │ ├── WebSearchTool/ # 网络搜索
│ │ └── ... (40+ 工具目录)
│ │
│ ├── types/ # TypeScript 类型
│ │ ├── command.ts # 命令类型
│ │ ├── message.ts # 消息类型
│ │ ├── permissions.ts # 权限类型
│ │ ├── tools.ts # 工具类型
│ │ └── ...
│ │
│ ├── upstreamproxy/ # 上游代理
│ ├── utils/ # 工具函数库
│ │ ├── permissions/ # 权限工具
│ │ ├── settings/ # 设置工具
│ │ ├── model/ # 模型工具
│ │ ├── plugins/ # 插件工具
│ │ ├── hooks/ # Hooks 工具
│ │ ├── swarm/ # 集群工具
│ │ └── ... (100+ 工具文件)
│ │
│ ├── vim/ # Vim 模式
│ └── voice/ # 语音功能
│
└── src.zip # 源码压缩包
| 目录 | 职责 | 核心文件 |
|---|---|---|
src/ |
核心业务代码 | main.tsx, query.ts, commands.ts |
src/tools/ |
工具实现 | 40+ 工具目录 |
src/commands/ |
Slash 命令 | 80+ 命令目录 |
src/services/ |
基础设施 | API, MCP, LSP, Analytics |
src/state/ |
状态管理 | AppState, Store |
src/ink/ |
终端 UI | 渲染引擎、布局、事件 |
src/utils/ |
工具函数 | 100+ 工具文件 |
| 软件 | 最低版本 | 推荐版本 |
|---|---|---|
| Node.js | 18.x | 20.x LTS |
| Bun | 1.0.x | 最新稳定版 |
| Git | 2.x | 最新 |
# 克隆仓库
git clone <repository-url>
cd claude-code
# 安装依赖 (使用 Bun)
bun install
# 或者使用 npm
npm install创建 .env 文件或设置环境变量:
# API 密钥
export ANTHROPIC_API_KEY="your-api-key"
# 可选：调试模式
export NODE_ENV=development
export DEBUG=true
# 可选：功能开关
export CLAUDE_CODE_SIMPLE=true # 简单模式git clone <repository-url>
cd claude-codebun install开发模式:
bun run dev生产模式:
bun run start带参数运行:
bun run start --help
bun run start --verbose
bun run start --model claude-sonnet-4-6目标: 添加 /hello 命令，输出 "Hello, World!"
步骤 1: 创建命令文件
mkdir -p src/commands/hello
touch src/commands/hello/index.ts步骤 2: 编写命令实现
// src/commands/hello/index.ts
import type { Command } from '../../types/command.js'
const helloCommand: Command = {
type: 'prompt',
name: 'hello',
description: '输出 Hello, World!',
source: 'builtin',
contentLength: 0,
async getPromptForCommand() {
return 'Hello, World! 这是一个测试命令。'
}
}
export default helloCommand步骤 3: 注册命令
编辑 src/commands.ts, 在导入区域添加:
import hello from './commands/hello/index.js'在 COMMANDS() 数组中添加:
const COMMANDS = memoize((): Command[] => [
addDir,
advisor,
// ... 其他命令
hello, // 新增
])步骤 4: 运行验证
bun run start
# 在 REPL 中输入 /hello目标: 添加 HelloTool, 返回问候语
步骤 1: 创建工具文件
mkdir -p src/tools/HelloTool
touch src/tools/HelloTool/HelloTool.ts步骤 2: 编写工具实现
// src/tools/HelloTool/HelloTool.ts
import { z } from 'zod/v4'
import { buildTool } from '../Tool.js'
const inputSchema = z.object({
name: z.string().describe('要问候的名字')
})
export const HelloTool = buildTool({
name: 'HelloTool',
description: '向某人问好',
inputSchema,
call: async (args) => {
return {
data: `Hello, ${args.name}!`
}
},
isConcurrencySafe: () => true,
isReadOnly: () => true,
})步骤 3: 注册工具
编辑 src/tools.ts, 在导入区域添加:
import { HelloTool } from './tools/HelloTool/HelloTool.js'在 getAllBaseTools() 数组中添加:
export function getAllBaseTools(): Tools {
return [
AgentTool,
// ... 其他工具
HelloTool, // 新增
]
}步骤 4: 运行验证
bun run start
# 让 AI 调用 HelloToolexport DEBUG=true
export NODE_ENV=development
bun run start日志文件位于:
- macOS:
~/Library/Logs/Claude Code/ - Windows:
%APPDATA%\Claude Code\logs\ - Linux:
~/.config/Claude Code/logs/
# 进入 REPL
bun run start
# 使用内部命令
/debug-tool-call # 调试工具调用
/ant-trace # 查看追踪
/heapdump # 内存快照# 使用 Biome 格式化
bun run format
# 使用 ESLint 检查
bun run lintbun run typecheck# 运行所有测试
bun test
# 运行特定测试
bun test src/tools/BashTool| 文件 | 说明 |
|---|---|
package.json |
项目配置、依赖、脚本 |
tsconfig.json |
TypeScript 配置 |
bunfig.toml |
Bun 配置 |
.claude/settings.json |
Claude Code 用户设置 |
| 命令 | 说明 |
|---|---|
/help |
显示帮助 |
/config |
查看配置 |
/skills |
列出技能 |
/model |
切换模型 |
/compact |
压缩上下文 |
/clear |
清空屏幕 |
文档结束