第2章：核心概念

本章介绍 Claude Code 中的核心概念和术语，包括 Agent、Tool、Skill、MCP 协议、权限系统和会话管理。

2.1 Agent 模型定义

Agent 的角色和职责

在 Claude Code 中，Agent 是执行任务的智能实体。它接收用户输入，通过 LLM 进行推理，选择合适的工具执行操作，最终返回结果。

graph TD
    subgraph AgentCore["Agent 核心"]
        A[LLM 推理引擎]
        B[上下文管理]
        C[工具选择器]
    end
    
    subgraph Inputs["输入"]
        I1[用户消息]
        I2[系统提示]
        I3[历史上下文]
    end
    
    subgraph Outputs["输出"]
        O1[文本响应]
        O2[工具调用]
        O3[状态更新]
    end
    
    I1 --> A
    I2 --> A
    I3 --> B
    B --> A
    A --> C
    C --> O2
    A --> O1
    B --> O3

Agent 的核心职责：

Agent 与 Tool 的关系

sequenceDiagram
    participant U as User
    participant A as Agent
    participant T as Tool
    participant S as System
    
    U->>A: 输入请求
    A->>A: 推理分析
    A->>T: 选择并调用工具
    T->>S: 执行操作
    S->>T: 返回结果
    T->>A: 工具结果
    A->>A: 处理结果
    A->>U: 输出响应
    
    note over A,T: Agent 决策使用哪个 Tool
    note over T,S: Tool 执行具体操作

Agent 是决策层，Tool 是执行层：

• Agent 负责「做什么」—— 根据用户意图选择工具
• Tool 负责「怎么做」—— 执行具体的系统操作

2.2 Tool 工具概念

工具的定义

Tool 是 Claude Code 与外部系统交互的标准化接口。每个工具定义了：

• 名称（name）
• 描述（description）
• 输入 Schema（JSON Schema）
• 执行逻辑（execute 函数）

// Tool.ts 中的核心类型定义
export type Tool<TTools extends Tools = Tools> = {
  name: string                  // 工具名称
  description: string           // 工具描述
  inputSchema: ToolInputJSONSchema  // 输入参数 Schema
  execute: (                    // 执行函数
    args: unknown,
    context: ToolUseContext
  ) => Promise<ToolResult>
  progress?: ToolProgress       // 进度回调
  validate?: (args: unknown) => ValidationResult  // 参数验证
}

工具的类型分类

Claude Code 提供约 46 种工具，按功能分类：

graph TD
    subgraph FileOps["文件操作"]
        F1[FileReadTool]
        F2[FileEditTool]
        F3[FileWriteTool]
        F4[GlobTool]
        F5[GrepTool]
    end
    
    subgraph System["系统操作"]
        S1[BashTool]
        S2[PowerShellTool]
        S3[NotebookEditTool]
    end
    
    subgraph Network["网络操作"]
        N1[WebFetchTool]
        N2[WebSearchTool]
    end
    
    subgraph AgentOps["Agent 操作"]
        A1[AgentTool]
        A2[SkillTool]
        A3[TaskCreateTool]
        A4[TaskStopTool]
    end
    
    subgraph MCP["MCP 操作"]
        M1[MCPTool]
        M2[ListMcpResourcesTool]
        M3[ReadMcpResourceTool]
    end
    
    subgraph UI["UI 操作"]
        U1[AskUserQuestionTool]
        U2[TodoWriteTool]
    end
    
    subgraph Misc["其他"]
        X1[EnterWorktreeTool]
        X2[ExitWorktreeTool]
        X3[ConfigTool]
        X4[LSPTool]
    end

工具类型详细说明

工具调用流程

sequenceDiagram
    participant LLM as Claude LLM
    participant QE as QueryEngine
    participant TR as Tool Registry
    participant T as Tool Instance
    participant PM as Permission Manager
    participant SYS as System
    
    LLM->>QE: Tool Use Block
    QE->>TR: lookup(tool_name)
    TR->>QE: Tool Instance
    QE->>PM: check_permission(tool, args)
    PM->>QE: Permission Result
    
    alt Permission Granted
        QE->>T: execute(args, context)
        T->>SYS: Perform Operation
        SYS->>T: Result
        T->>QE: Tool Result Block
        QE->>LLM: Return Result
    else Permission Denied
        PM->>QE: Deny Message
        QE->>LLM: Permission Error
    end

2.3 Skill 技能概念

Skill 与 Tool 的区别

Skill 是一种特殊的「宏工具」，它不是执行单一操作，而是注入一组预定义的提示词和行为模板。

graph TD
    subgraph Tool["Tool 模型"]
        T1[单一操作]
        T2[明确参数]
        T3[原子执行]
    end
    
    subgraph Skill["Skill 模型"]
        S1[提示词注入]
        S2[行为模板]
        S3[上下文扩展]
        S4[允许工具列表]
    end
    
    Tool --> |"底层执行"| Skill

Skill 的加载机制

flowchart TD
    A[启动] --> B{Skill 来源}
    B --> |"bundled"| C[内置 Skills]
    B --> |"disk"| D[磁盘 Skills]
    B --> |"plugin"| E[插件 Skills]
    
    C --> F[registerBundledSkill]
    D --> G[loadSkillsDir]
    E --> H[loadPluginSkills]
    
    F --> I[Skill Registry]
    G --> I
    H --> I
    
    I --> J[Command Registry]

Skill 的三种来源：

1. Bundled Skills：编译内置的 Skills，随 CLI 二进制分发
2. Disk Skills：用户目录 ~/.claude/commands/ 下的 .md 文件
3. Plugin Skills：通过插件系统加载的外部 Skills

// bundledSkills.ts 中的 Skill 定义
export type BundledSkillDefinition = {
  name: string                  // Skill 名称
  description: string           // 描述
  aliases?: string[]            // 别名
  whenToUse?: string            // 使用时机说明
  argumentHint?: string         // 参数提示
  allowedTools?: string[]       // 允许使用的工具列表
  model?: string                // 指定模型
  hooks?: HooksSettings         // 钩子配置
  getPromptForCommand: (args, context) => Promise<ContentBlockParam[]>
}

内置 Skills 示例

2.4 MCP 协议概念

MCP (Model Context Protocol) 简介

MCP 是 Anthropic 推出的开放协议，用于连接 LLM 应用与外部数据源和工具。

graph TD
    subgraph ClaudeCode["Claude Code"]
        A[MCP Client]
    end
    
    subgraph MCPServer["MCP Server"]
        B1[GitHub MCP]
        B2[Postgres MCP]
        B3[Filesystem MCP]
        B4[Custom MCP]
    end
    
    subgraph Resources["资源"]
        R1[GitHub API]
        R2[数据库]
        R3[文件系统]
        R4[自定义服务]
    end
    
    A --> |"MCP Protocol"| B1
    A --> |"MCP Protocol"| B2
    A --> |"MCP Protocol"| B3
    A --> |"MCP Protocol"| B4
    
    B1 --> R1
    B2 --> R2
    B3 --> R3
    B4 --> R4

MCP 协议的核心概念：

MCP Server 与 Claude Code 的交互

sequenceDiagram
    participant CC as Claude Code
    participant MCP as MCP Client
    participant Server as MCP Server
    
    CC->>MCP: 启动时连接 Server
    MCP->>Server: initialize
    Server->>MCP: capabilities
    
    MCP->>Server: listTools
    Server->>MCP: tools list
    MCP->>CC: 注册工具
    
    MCP->>Server: listResources
    Server->>MCP: resources list
    MCP->>CC: 注册资源
    
    note over CC,Server: 用户交互中
    
    CC->>MCP: Tool Use (MCP Tool)
    MCP->>Server: callTool
    Server->>MCP: result
    MCP->>CC: Tool Result

2.5 Permission 权限系统

权限检查流程

Claude Code 实现了细粒度的权限控制，确保工具执行的安全性。

flowchart TD
    A[Tool Use Request] --> B{检查规则}
    
    B --> C[alwaysAllowRules]
    B --> D[alwaysDenyRules]
    B --> E[alwaysAskRules]
    
    C --> F{匹配?}
    D --> G{匹配?}
    E --> H{匹配?}
    
    F --> |"Yes"| I[自动允许]
    F --> |"No"| J[继续检查]
    
    G --> |"Yes"| K[自动拒绝]
    G --> |"No"| J
    
    H --> |"Yes"| L[弹出确认]
    H --> |"No"| M[默认模式]
    
    J --> M
    M --> N{Permission Mode}
    
    N --> |"accept"| I
    N --> |"default"| L
    N --> |"bypass"| I
    
    L --> O{用户决策}
    O --> |"Allow"| I
    O --> |"Deny"| K
    O --> |"Allow Always"| P[添加到 alwaysAllow]

权限类型

// 权限类型定义
export type PermissionMode = 
  | 'default'    // 每次询问
  | 'accept'     // 自动接受（但检查规则）
  | 'bypass'     // 绕过所有检查（危险模式）

export type PermissionResult = 
  | 'allow'      // 允许执行
  | 'deny'       // 拒绝执行
  | 'ask'        // 需要用户确认

权限规则配置示例：

{
  "alwaysAllow": [
    "Bash(npm install)",
    "Read(**/*.ts)",
    "Grep(**/*)"
  ],
  "alwaysDeny": [
    "Bash(rm -rf /)",
    "Write(/etc/*)"
  ],
  "alwaysAsk": [
    "Bash(git push)"
  ]
}

2.6 Session 会话概念

会话生命周期

Session 代表一次完整的用户交互周期，从启动到退出。

stateDiagram-v2
    [*] --> Init: 启动 CLI
    Init --> Ready: 初始化完成
    Ready --> Active: 用户输入
    Active --> Processing: 处理请求
    Processing --> ToolCall: 工具调用
    ToolCall --> Processing: 工具结果
    Processing --> Active: 响应完成
    Active --> Compact: 上下文压缩
    Compact --> Active: 压缩完成
    Active --> Exit: 用户退出
    Exit --> [*]

Session 的关键阶段：

上下文管理

graph TD
    subgraph Context["上下文组成"]
        C1[System Prompt]
        C2[Tool Definitions]
        C3[Conversation History]
        C4[File State Cache]
    end
    
    subgraph TokenLimit["Token 管理"]
        T1[输入 Token]
        T2[输出 Token]
        T3[总预算]
    end
    
    C1 --> T1
    C2 --> T1
    C3 --> T1
    
    T1 --> L{超出预算?}
    L --> |"Yes"| M[上下文压缩]
    L --> |"No"| N[正常处理]
    
    M --> P[保留关键信息]
    P --> C3

上下文压缩策略：

1. 消息截断：保留最近 N 条消息
2. 内容摘要：将长内容替换为摘要
3. 工具结果压缩：大型工具结果转为引用
4. 文件状态清理：清理不再相关的文件缓存

下一章将深入分析 Claude Code 的架构设计，包括整体架构图和请求生命周期。