Claude Code 使用技术调研报告

一、项目概述

Claude Code 是一个运行在本地终端中的 agentic coding system，由 Anthropic 开发。它不是给建议的聊天机器人——它直接在你的项目目录中读代码、改文件、跑命令、调试程序，拥有完整的 shell 能力。

1.1 技术定位关键词

定位关键词 含义
Terminal-native 原生 CLI 应用，不是 IDE 插件、不是 Web 界面、不是 API wrapper
Agentic AI 自主决策工具调用链，不是”一问一答”的聊天模式
Coding system 面向软件工程全流程，不是通用问答工具

1.2 与同类工具的架构差异

工具 架构模式 运行位置 工具执行
Claude Code Terminal-native agentic loop 本地进程 直接 shell 执行
Cursor / Copilot IDE-integrated autocomplete + chat IDE 进程内 LSP / IDE API
Aider CLI chat → git patch 本地进程 文件操作为主
ChatGPT / Claude.ai Cloud chat + artifacts 浏览器/云端 沙箱容器

二、五层架构设计

Claude Code 采用清晰的分层架构，从上到下共 5 层：

层次 核心职责 入口源码 关键技术关键词
交互层 终端UI渲染、用户输入接收、消息展示 src/screens/REPL.tsx React/Ink、PromptInput
编排层 多轮对话管理、会话持久化、成本追踪 src/QueryEngine.ts QueryEngine、transcript
核心循环层 单轮对话全流程处理：发请求→接收响应→执行工具→循环判定 src/query.ts Agentic Loop、State
工具层 提供AI可调用的能力集合 src/tools.ts → src/Tool.ts Tool接口、MCP
通信层 与Claude API的流式通信适配 src/services/api/claude.ts Streaming、Provider

2.1 交互层技术细节

2.2 编排层技术细节

核心管理 4 类状态与能力：

2.3 通信层技术细节

支持 7 种 API Provider 适配：

三、Agentic Loop 核心机制

Agentic Loop 是 Claude Code 实现 AI 自主多轮执行的核心机制，源码级实现位于 src/query.ts 的 queryLoop() 异步生成器函数中。

3.1 循环完整执行流程

每次迭代包含 4 个标准阶段：


阶段1: 上下文预处理
  原始 messagesForQuery
    ↓ applyToolResultBudget()    — 工具结果预算截断
    ↓ snipCompactIfNeeded()      — 历史Snip压缩
    ↓ microcompact()             — 微压缩
    ↓ applyCollapsesIfNeeded()   — 上下文折叠
    ↓ autocompact()             — 自动压缩
  → 处理后的 messagesForQuery → 发往API

阶段2: 流式API调用
  通过 deps.callModel() 发起流式请求
  收集 assistantMessages[]、toolUseBlocks[]

阶段3: 工具执行
  StreamingToolExecutor（并行执行）或 runTools（串行执行）
  生成 toolResults[]

阶段4: 终止/继续判定
  通过 needsFollowUp 判定是否需要继续循环

3.2 循环终止条件（9种）

终止原因 触发机制
blocking_limit Token计数超过硬限制
image_error ImageSizeError/ImageResizeError 异常
model_error callModel() 抛出不可恢复异常
aborted_streaming 流式阶段检测到 abort
prompt_too_long 触发413错误且reactive compact无法恢复
completed（正常完成） AI未发出 tool_use
completed（API错误） 限流、认证失败等不可恢复错误
aborted_tools 工具执行阶段检测到 abort
max_turns 轮次计数超过限制

3.3 错误恢复路径（5类）

  1. 正常工具循环：基础继续逻辑
  2. max_output_tokens 两阶段恢复：提升阶段 → 恢复阶段
  3. Prompt-Too-Long 两级恢复：Context Collapse Drain → Reactive Compact
  4. Stop Hook 阻塞重试：注入阻塞错误让 AI 重新思考
  5. Token Budget 继续提示：注入 nudge 消息让 AI 加速收尾

3.4 模型降级（Fallback）机制

主模型不可用时触发：

  1. 清空已收集的 assistantMessages
  2. 移除思维签名块
  3. 切换到 fallbackModel
  4. 生成系统消息后重新发起流式请求

四、上下文压缩系统

采用 三层递进式策略，对应不同触发场景与严重程度：

层级 触发条件 实现位置 是否需要 API 调用
MicroCompact 单个工具输出过长 microCompact.ts 否
Session Memory Compact 自动压缩（需 feature flag） sessionMemoryCompact.ts 否
传统 API 摘要 手动 /compact 或 SM 不可用时回退 compact.ts 是

4.1 MicroCompact 局部压缩

4.2 Session Memory（SM）压缩

4.3 传统 API 摘要压缩

4.4 边界标记机制

五、工具系统设计

5.1 Tool 统一接口定义

所有工具均实现 Tool<Input, Output, Progress> 泛型结构性类型，共 35+ 个字段：

核心四要素（必选基础字段）

字段 类型 说明
name string 工具唯一标识
description() (input) => Promise<string> 动态描述方法
inputSchema z.ZodType Zod schema，定义参数类型与校验
call() (args, context, ...) => Promise<ToolResult> 核心执行函数

安全与权限相关字段

字段 说明
validateInput() 输入校验方法
checkPermissions() 权限检查方法
isReadOnly() 标记是否只读操作
isDestructive() 标记是否不可逆操作
isConcurrencySafe() 标记是否可并行执行

5.2 工具注册机制

基础工具分为 4 类：

  1. 固定工具（17个）：Agent、Bash、FileRead、FileEdit、FileWrite、NotebookEdit、WebFetch、WebSearch、TodoWrite、AskUserQuestion、Skill、EnterPlanMode、ExitPlanMode、TaskOutput、Brief 等
  2. 条件工具：运行时检查后添加
  3. Feature-flag工具：按功能开关添加
  4. Ant-only工具：仅内部环境可用

5.3 工具调用完整链路（10步）


1. 大模型API返回 tool_use block
2. StreamingToolExecutor.addTool() / runTools() 接收请求
3. findToolByName() 查找工具实例
4. validateInput() 做输入校验
5. canUseTool() 触发权限UI（如Ask模式确认弹窗）
6. checkPermissions() 做权限规则匹配
7. 执行工具 call() 方法
8. 返回 ToolResult<Output>
9. mapToolResultToToolResultBlockParam() 转换格式
10. 消息追加到上下文，进入下一轮

5.4 50+ 内置工具分类

分类 包含工具
文件操作 Read、Write、Edit、Glob、Grep、NotebookEdit
命令执行 Bash、PowerShell
对话管理 Agent、SendMessage、AskUserQuestion
任务追踪 TaskCreate、TaskUpdate、TaskList、TaskGet、TaskOutput、TaskStop
Web能力 WebFetch、WebSearch、WebBrowser
规划与版本 EnterPlanMode、ExitPlanMode、Worktree、TodoWrite、ToolSearch

六、权限与安全模型

6.1 三级权限行为

权限行为 含义 典型场景
Allow 自动放行 Read工具读取项目内文件
Ask 弹出确认对话框 Bash工具执行未知命令
Deny 直接拒绝 尝试执行被禁止的命令

6.2 八层规则来源（优先级从低到高）

  1. userSettings：~/.claude/settings.json
  2. projectSettings：.claude/settings.json
  3. localSettings：.claude/settings.local.json
  4. flagSettings：--settings 命令行参数
  5. policySettings：企业管理员下发的强制策略
  6. cliArg：命令行 --allow/--deny 参数
  7. command：Skill工具的 allowedTools 白名单
  8. session：用户在当前对话中手动授权

6.3 六种权限模式

模式 适用场景 行为规则
Default 日常使用 敏感操作逐一确认
Plan Mode 探索阶段 仅允许读操作
Accept Edits 快速迭代 文件编辑自动放行
Don’t Ask 减少打断 尽量自动决策
Auto 信任AI场景 通过 classifier 自动决策
Bypass 完全信任场景 所有操作自动放行

6.4 死循环防护


const DENIAL_LIMITS = {
  maxConsecutive: 3,   // 同一工具连续拒绝上限
  maxTotal: 20,        // 总拒绝次数上限
}

七、扩展性系统

7.1 Hook 生命周期钩子（27种事件）

阶段 事件
会话阶段 SessionStart、SessionEnd、Setup
用户交互 UserPromptSubmit、Stop、StopFailure
工具执行 PreToolUse、PostToolUse、PostToolUseFailure
权限 PermissionRequest、PermissionDenied
子Agent SubagentStart、SubagentStop
压缩 PreCompact、PostCompact
协作 TeammateIdle、TaskCreated、TaskCompleted
MCP/通知 Elicitation、ElicitationResult、Notification

7.2 六种 Hook 类型

类型 执行方式 适用场景
command Shell命令 通用脚本、CI检查
prompt 注入到AI上下文 代码规范提醒
agent 启动子Agent执行 复杂分析任务
http HTTP请求 远程服务、Webhook
callback 内部JS函数 系统内置Hook
function 运行时注册的函数 Agent/Skill内部使用

7.3 Skills 技能系统

核心理念：”复杂任务的关键不在代码逻辑，而在 Prompt 质量”

维度 Tool Skill
粒度 单个原子操作 一套完整工作流
触发方式 AI自主选择 用户 /skill-name 或AI匹配
本质 TypeScript执行逻辑 Prompt + 权限配置的声明式封装

Skill 的五个来源：

  1. 内置命令（70+条）
  2. Bundled Skills（编译时打包）
  3. 磁盘 Skills（主要来源）
  4. MCP Skills（动态发现）
  5. Legacy Commands（向后兼容）

7.4 MCP 协议支持

八、子 Agent 协作系统

8.1 四大子 Agent 类型

类型 触发方式 Tool协议 结果返回
命名子Agent 主模型调用 Agent({ subagent_type }) ✅ 当前 turn 的 tool_result
AgentTool fork 省略 subagent_type + fork gate 开启 ✅ async_launched → 任务通知
Slash command fork 用户执行 context: fork 的 slash command ❌ 同步返回或隐藏 prompt 回注
runForkedAgent() 运行时内部服务直接调用 ❌ 调用方内部消费

8.2 Agent Definition 字段


name: code-reviewer
description: 系统性代码审查
tools: [Read, Grep, Glob]
disallowedTools: [Write, Bash]
prompt: You are a focused reviewer...
model: sonnet
effort: medium
permissionMode: acceptEdits
background: true
isolation: worktree
maxTurns: 8
memory: project

8.3 Worktree 隔离

使用 git worktree 实现文件级隔离：

九、System Prompt 动态组装

9.1 三阶段处理管道


getSystemPrompt()              →  string[]
  ↓
buildEffectiveSystemPrompt()   →  SystemPrompt
  ↓
buildSystemPromptBlocks()      →  TextBlockParam[]

9.2 静态区与动态区分界


[静态内容]                    → cacheScope: 'global'（全局缓存）
__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__
[动态内容]                    → cacheScope: 'org' 或不缓存

9.3 五级优先级选择

优先级 名称 触发条件
0 Override overrideSystemPrompt 非空
1 Coordinator COORDINATOR_MODE feature + 环境变量
2 Agent mainThreadAgentDefinition 存在
3 Custom –system-prompt 参数指定
4 Default 无特殊条件

9.4 CLAUDE.md 多级合并


~/.claude/CLAUDE.md          ← 用户全局
  └── /project/CLAUDE.md     ← 项目根目录
        └── /project/src/CLAUDE.md  ← 子目录

十、核心技术指标

指标 数值
内置工具数量 50+
Hook 事件类型 27种
Hook 执行类型 6种
权限规则来源 8层
权限模式 6种
API Provider 支持 7种
默认上下文窗口 200K tokens
压缩保留窗口 min: 10K / max: 40K tokens

十一、关键技术设计原则

1. 流式优先 (Streaming-first)

2. 工具即能力 (Tool as Capability)

3. 权限即边界 (Permission as Boundary)

4. 上下文即记忆 (Context as Memory)

十二、技术启示与应用建议

12.1 对 AI Agent 开发的启示

  1. Agentic Loop 是核心：区别于传统聊天机器人的关键
  2. 流式架构优先：提升用户体验和执行效率
  3. 上下文管理是瓶颈：需要多层压缩策略
  4. 安全与体验平衡：Allow/Ask/Deny 三级体系

12.2 架构设计参考

设计模式 Claude Code 实现
分层架构 五层架构，边界清晰
状态机 State 对象不可变传递
工厂模式 buildTool() 工厂函数
策略模式 多种压缩策略可选
观察者模式 Hook 生命周期系统

12.3 可借鉴的技术点

  1. Tool 接口标准化：泛型 + Zod schema
  2. 权限系统：来源优先级 + 匹配规则
  3. 压缩策略：三层递进 + 边界标记
  4. Skill 封装：Prompt 即能力
  5. 子 Agent 协作：命名/Fork/Teammate 分层

十三、参考资源

报告生成时间：2026-05-17