Claude Code 项目架构分析

项目概述

Claude Code 是 Anthropic 官方推出的 AI 编程助手命令行工具，采用 混合架构设计，既可作为客户端CLI工具使用，也可作为MCP服务器运行，还支持远程会话功能。

架构分析

🏗️ 混合架构设计

Claude Code 采用 Client-Server 混合架构，具有以下特点：

1. 主要作为客户端工具

定位：运行在用户本地的CLI工具
功能：提供AI编程辅助、代码理解、文件操作等
入口：src/entrypoints/cli.tsx
运行方式：claude 命令行工具

2. 内置服务器组件

MCP服务器模式：可作为Model Context Protocol服务器运行
入口：src/entrypoints/mcp.ts
运行方式：claude mcp serve
用途：为其他应用提供工具和资源接口

3. 远程客户端能力

远程会话支持：可连接到Claude Code远程服务器
功能：支持CCR（Claude Code Remote）环境
相关模块：src/remote/、src/bridge/
运行方式：通过环境变量或命令行参数启用

架构图

┌─────────────────────────────────────────────────────────────┐
│                   Claude Code 混合架构                  │
└─────────────────────────────────────────────────────────────┘

┌──────────────────┐         ┌──────────────────┐
│   本地客户端      │         │   MCP服务器       │
│   (CLI模式)     │         │   (服务模式)     │
├──────────────────┤         ├──────────────────┤
│ • 交互式会话    │         │ • 工具提供      │
│ • 文件操作      │         │ • 资源管理      │
│ • 命令执行      │         │ • 标准I/O通信   │
│ • AI编程辅助    │         │                │
└────────┬─────────┘         └────────┬─────────┘
         │                           │
         └───────────┬───────────────┘
                     │
         ┌───────────▼───────────────┐
         │      Claude API           │
         │   (anthropic-ai/sdk)     │
         └───────────┬───────────────┘
                     │
         ┌───────────▼───────────────┐
         │    远程服务器连接         │
         │  (可选CCR环境)          │
         └───────────────────────────┘

技术架构

核心技术栈

运行时环境:
  - Bun (JavaScript/TypeScript 运行时)
  - Node.js 兼容层

开发语言:
  - TypeScript (主要)
  - JavaScript (部分模块)

UI框架:
  - React (组件化UI)
  - Ink (React for CLI终端渲染)

API客户端:
  - @anthropic-ai/sdk (Claude官方SDK)
  - @modelcontextprotocol/sdk (MCP协议)

状态管理:
  - 自定义响应式状态管理系统
  - Context API (React上下文)

数据验证:
  - Zod (Schema验证)

工具库:
  - lodash-es (工具函数)
  - chalk (终端颜色)
  - ripgrep (高性能搜索)

项目结构详解

src/
├── entrypoints/              # 应用入口点
│   ├── cli.tsx              # CLI主入口 (客户端模式)
│   ├── init.ts               # 初始化模块
│   ├── mcp.ts                # MCP服务器入口 (服务模式)
│   └── sdk/                 # Agent SDK类型定义
│
├── components/              # React组件库
│   ├── App.tsx              # 主应用组件
│   ├── Messages.tsx          # 消息显示组件
│   ├── PromptInput/          # 输入组件
│   ├── permissions/          # 权限管理组件
│   └── design-system/        # 设计系统组件
│
├── tools/                  # 工具系统 (核心功能)
│   ├── BashTool/            # Bash/PowerShell执行
│   ├── AgentTool/           # 多代理系统
│   ├── FileReadTool/        # 文件读取
│   ├── FileWriteTool/       # 文件写入
│   ├── FileEditTool/        # 文件编辑
│   ├── GrepTool/            # 内容搜索
│   ├── GlobTool/            # 文件匹配
│   ├── MCPTool/             # MCP工具集成
│   └── SkillTool/           # 技能工具
│
├── services/                # 服务层
│   ├── api/                 # Claude API客户端
│   │   └── claude.ts        # API调用核心
│   ├── mcp/                 # MCP服务管理
│   │   ├── client.ts         # MCP客户端
│   │   └── config.ts        # MCP配置
│   ├── analytics/            # 分析和遥测
│   └── tools/               # 工具执行服务
│
├── state/                  # 状态管理
│   ├── AppState.tsx          # 应用状态定义
│   └── AppStateStore.ts      # 状态存储实现
│
├── commands/               # 命令系统
│   ├── install.tsx           # 安装命令
│   ├── plugin/              # 插件管理
│   ├── mcp/                 # MCP命令
│   └── [其他命令]           # 各种功能命令
│
├── utils/                  # 工具函数库
│   ├── nativeInstaller/      # 原生安装器
│   ├── config.ts            # 配置管理
│   ├── auth.ts             # 认证管理
│   └── [其他工具]           # 各类工具函数
│
├── bridge/                 # 桥接服务 (远程功能)
│   ├── bridgeMain.ts         # 桥接主逻辑
│   └── replBridge.ts        # REPL桥接
│
├── remote/                 # 远程会话管理
│   ├── RemoteSessionManager.ts # 远程会话管理器
│   └──── SessionsWebSocket.ts # WebSocket通信
│
├── plugins/                # 插件系统
│   └── bundled/             # 内置插件
│
├── skills/                 # 技能系统
│   └── bundled/             # 内置技能
│
├── ink/                    # Ink框架定制
├── hooks/                  # React Hooks
├── types/                  # TypeScript类型
├── constants/              # 常量定义
└── tasks/                  # 任务管理

安装和部署

系统要求

操作系统:
  - Windows 10+
  - macOS 10.15+
  - Linux (主流发行版)

运行时:
  - Bun 1.0+ (推荐)
  - Node.js 18+ (兼容)

网络:
  - 需要访问Anthropic API
  - 可选：远程服务器连接

安装方式

方式1：官方安装器（推荐）

# 使用官方安装脚本
curl -fsSL https://claude.ai/install.sh | bash

# 或使用npm全局安装
npm install -g @anthropic-ai/claude-code

# 或使用Bun安装
bun install -g @anthropic-ai/claude-code

方式2：源码编译安装

# 克隆仓库
git clone https://github.com/anthropics/claude-code.git
cd claude-code

# 安装依赖
bun install

# 编译项目
bun run build

# 安装到系统
bun run install:global

方式3：开发模式安装

# 克隆仓库
git clone https://github.com/anthropics/claude-code.git
cd claude-code

# 安装依赖
bun install

# 创建符号链接
bun link

安装位置

# Linux/macOS
~/.local/bin/claude

# Windows
%USERPROFILE%\.local\bin\claude.exe

# 配置文件位置
~/.config/claude-code/

# 数据文件位置
~/.local/share/claude-code/

环境配置

# API密钥配置
export ANTHROPIC_API_KEY="your-api-key"

# 或使用配置文件
claude auth login

# 查看配置
claude settings edit

使用指南

基本使用

1. 启动交互式会话（客户端模式）

# 基本启动
claude

# 指定模型
claude --model claude-3-5-sonnet-20241022

# 指定工作目录
claude --path /path/to/project

# 继续上次会话
claude --continue

# 恢复特定会话
claude --resume <session-id>

2. 非交互式模式

# 直接执行命令
claude -p "解释这个函数的作用"

# 从文件读取输入
claude -p "$(cat prompt.txt)"

# 批处理模式
claude --batch < commands.txt

3. MCP服务器模式（服务模式）

# 启动MCP服务器
claude mcp serve

# 指定工作目录
claude mcp serve --cwd /path/to/project

# 调试模式
claude mcp serve --debug

# 详细输出
claude mcp serve --verbose

主要功能命令

文件操作

# 在Claude中执行
> 读取文件 src/main.ts
> 编辑文件 src/utils.ts
> 搜索函数 "calculateTotal"
> 列出所有 .tsx 文件

命令执行

# 在Claude中执行
> 运行 npm test
> 执行 git status
> 检查端口 3000 是否被占用

多代理协作

# 启动子代理
> 启动一个代理来分析代码性能

# 代理间通信
> 发送消息给代理A：检查测试覆盖率

插件和技能

# 插件管理
claude plugin list
claude plugin install <plugin-name>
claude plugin remove <plugin-name>

# 技能使用
> 使用verify技能检查代码
> 使用loop技能重复执行

技能系统详解

Claude Code 的技能系统是一个强大的工作流自动化和代码复用机制，允许用户将重复性的工作过程封装为可重用的技能。

技能架构

技能系统层次
├── 内置技能
│   ├── verify          # 代码验证技能
│   ├── simplify         # 代码简化技能
│   ├── remember         # 记忆管理归档技能
│   ├── skillify        # 会话捕获技能
│   ├── batch           # 批量处理技能
│   ├── loop            # 循环调度技能
│   ├── stuck           # 诊断技能
│   ├── debug           # 调试技能
│   ├── keybindings     # 键盘绑定技能
│   ├── loremIpsum      # 测试数据生成
│   └── updateConfig    # 配置更新技能
│
├── 用户技能
│   ├── 项目级技能
│   │   └── .claude/skills/
│   ├── 用户级技能
│   │   └── ~/.claude/skills/
│   └── 管理策略技能
│       └── 策略配置
│
└── MCP技能
    └── 动从MCP服务器加载

技能定义格式

每个技能都是一个 Markdown 文件，包含前端元数据和后执行逻辑：

---
name: skill-name
description: 一行描述
aliases: [alias1, alias2]
when_to_use: 何时自动调用此技能的详细描述
argument_hint: 参数提示信息
allowed_tools: [Read, Write, Bash(git:*)]
model: claude-3-5-sonnet-20241022
context: inline | fork
agent: agent-type
hooks:
  before: []
  after: []
---

# 技能标题

技能的详细描述...

## 输入
- `$arg_name`: 参数描述

## 目标
明确的目标和成功标准

。

## 步骤

### 1. 步骤名称
具体的操作步骤...

**成功标准**: 完成此步骤的明确标准

...

内置技能详解

1. verify 技能

文件位置: src/skills/bundled/verify.ts

功能: 验证代码更改是否按预期工作，通过运行应用程序进行测试。

使用场景:

> 使用verify技能

工作流程:

运行应用程序测试验证更改
检查应用程序行为是否符合预期
报告测试结果和问题

2. simplify 技能

文件位置: src/skills/bundled/simplify.ts

功能: 审查更改的代码以进行复用、质量和效率审查，然后修复发现的任何问题。

使用场景:

> 使用simplify技能

工作流程:

代码复用审查: 搜索可以替换新代码的现有工具和辅助函数
代码质量审查: 检查冗余状态、参数扩展、复制粘贴等模式
效率审查: 检查不必要的工作、错过的并发、热路径膨胀等
修复问题: 聚合发现并直接修复每个问题

3. remember 技能

文件位置: src/skills/bundled/remember.ts

功能: 审查自动记忆条目并提出将其提升到 CLAUDE.md、CLAUDE.local.md 或共享记忆的建议。

使用场景:

> 使用remember技能

工作流程:

收集所有记忆层（CLAUDE.md、CLAUDE.local.md、团队记忆、自动记忆）
对每个自动记忆条目进行分类
识别清理机会（重复、过时、冲突）
呈现结构化报告供用户批准

4. skillify 技能

文件位置: src/skills/bundled/skillify.ts

功能: 将此会话的可重复过程捕获为可重用的技能。

使用场景:

> 使用skillify技能
> 使用skillify技能捕获这个部署流程

工作流程:

分析会话: 识别可重复的过程、输入/参数、步骤、成功标准
访谈用户: 通过多轮对话了解用户想要自动化什么
编写 SKILL.md: 创建技能文件和目录
确认并保存: 在用户批准后保存技能

5. batch 技能

文件位置: src/skills/bundled/batch.ts

功能: 研究和规划大规模更改，然后通过 5-30 个隔离的工作树代理并行执行。

使用场景:

> 使用batch技能迁移从react到vue
> 使用batch技能替换所有lodash的使用

工作流程:

研究和规划: 进入计划模式，研究更改范围并分解为独立单元
生成工作器: 为每个工作单元启动后台代理
跟踪进度: 监控代理完成状态并更新状态表
汇总结果: 汇总成功率和 PR 链接

6. loop 技能

文件位置: src/skills/bundled/loop.ts

功能: 在重复间隔上运行提示或斜杠命令（例如：/loop 5m /babysit-prs）。

使用场景:

> 使用loop技能每5分钟检查部署状态
> /loop 30m /standup 1

工作流程:

解析间隔和提示（支持 5m、2h、1d 格式）
转换为 cron 表达式
使用 cron 工具调度重复任务
立即执行一次，然后按计划重复

7. stuck 技能

文件位置: src/skills/bundled/stuck.ts

功能: [ANT-ONLY] 调查此机器上冻结/卡顿/缓慢的 Claude Code 会话，并将诊断报告发布到 #claude-code-feedback。

使用场景:

> 使用stuck技能

工作流程:

列出所有 Claude Code 进程
检查卡顿会话的迹象（高 CPU、D 状态、高 RSS）
收集更多上下文（子进程、调试日志）
发布诊断报告到反馈频道

8. debug 技能

文件位置: src/skills/bundled/debug.ts

功能: 通过读取会话调试日志来调试当前的 Claude Code 会话。

使用场景:

> 使用debug技能
> 使用debug技能修复登录问题

工作流程:

启用调试日志记录
读取调试日志的最后 20 行
呈现日志内容和问题摘要
提供具体的修复建议

9. keybindings 技能

文件位置: src/skills/bundled/keybindings.ts

功能: 用于自定义键盘快捷键、重新绑定键、添加和弦绑定或修改 ~/.claude/keybindings.json。

使用场景:

> 使用keybindings技能
> 重新绑定ctrl+s
> 添加和弦快捷键
> 自定义快捷键

工作流程:

显示可用上下文和操作表
提供文件格式示例
解释按键语法和行为规则
显示验证和故障排除信息

创建自定义技能

项目级技能

# 创建技能目录
mkdir -p .claude/skills/my-skill

# 创建技能文件
cat > .claude/skills/my-skill/SKILL.md << 'EOF'
---
name: deploy
description: 部署应用到生产环境
when_to_use: 当用户想要部署应用时使用
argument_hint: "<环境>"
allowed_tools:
  - Read
  - Write
  - Bash(git:*, npm:*)
---

# 部署技能

## 目标
将应用部署到指定的生产环境。

## 输入
- `$env`: 目标环境（staging、production）

## 步骤

### 1. 运行测试
执行测试套件确保代码质量。

**成功标准**: 所有测试通过

### 2. 构建应用
构建生产版本的应用程序。

**成功标准**: 构建成功，无错误

### 3. 部署到环境
将构建的应用部署到 `$env` 环境。

**成功标准**: 部署成功，应用可访问
EOF

用户级技能

# 创建用户级技能
mkdir -p ~/.claude/skills/global-deploy

# 创建技能文件
cat > ~/.claude/skills/global-deploy/SKILL.md << 'EOF'
---
name: global-deploy
description: 全局部署工作流
when_to_use: 跨项目使用的通用部署流程
---

# 全局部署技能
...
EOF

技能调用方式

1. 斜杠命令调用

# 在Claude Code中直接调用
> /deploy production
> /simplify
> /verify

2. 自然语言调用

# 通过自然语言描述触发
> 部署应用到生产环境
> 使用验证技能检查代码
> 简化这个函数

3. 自动调用

Claude 会根据 when_to_use 字段自动识别何时调用技能：

when_to_use: |
  当用户想要部署应用时使用
  触发短语包括："部署"、"发布"、"上线"
  示例：'部署到staging', '发布新版本', '上线生产环境'

技能高级特性

1. 权限控制

---
allowed_tools:
  - Read
  - Write
  - Bash(git:*, npm:*)
  - Edit
---

2. 执行上下文

---
context: inline    # 在当前对话中执行
context: fork      # 作为子代理执行（隔离上下文）
---

3. 模型指定

---
model: claude-3-5-sonnet-20241022
---

4. 代理指定

---
agent: general-purpose    # 使用通用代理
agent: plan             # 使用计划代理
---

5. 钩子系统

---
hooks:
  before:
    - skill:before-deploy
  after:
    - skill:after-deploy
---

技能开发最佳实践

1. 命名规范

使用简短、描述性的名称（kebab-case）
避免与内置技能冲突
使用有意义的别名

2. 描述编写

提供清晰的一行描述
详细说明 when_to_use 条件
包含具体的触发短语和示例

3. 步骤设计

每个步骤都有明确的目标
定义可验证的成功标准
使用编号子步骤（1a、1b）表示并行操作
包含具体的命令和操作

4. 权限管理

只请求必要的工具权限
使用模式匹配（Bash(git:*)）而非通配符
考虑使用 context: fork 进行隔离

5. 错误处理

提供失败时的回滚步骤
包含诊断命令
建议具体的修复措施

技能文件位置

# 项目级技能
.claude/skills/<skill-name>/SKILL.md

# 用户级技能
~/.claude/skills/<skill-name>/SKILL.md

# 管理策略技能
# 由组织策略定义

技能管理命令

# 列出所有可用技能
claude skills list

# 查看特定技能详情
claude skills show <skill-name>

# 重新加载技能（开发时）
claude skills reload

# 验证技能语法
claude skills validate

技能与插件的对比

特性	技能	插件
定位	工作流封装	功能扩展
存储	Markdown 文件	独立包
权限	声明式权限	完全访问
调用	斜杠命令/自然语言	工具集成
上下文	可选隔离	共享上下文
分发	内置/用户/MCP	独立安装
更新	文件编辑	版本管理

MCP 技能集成

技能系统支持从 MCP 服务器动态加载技能：

// MCP 服务器可以提供技能
{
  "name": "mcp-server",
  "skills": [
    {
      "name": "custom-skill",
      "description": "来自MCP的技能",
      "prompt": "技能提示内容..."
    }
  ]
}

这使得技能可以：

跨组织共享
动态更新
集中管理
版本控制

高级功能

1. 远程会话

# 连接到远程服务器
export CLAUDE_CODE_REMOTE=true
claude --remote-url https://your-server.com

# 远程环境变量
export CLAUDE_CODE_SESSION_ID="session-123"

2. 工作树模式

# 创建工作树会话
claude --worktree

# 与tmux集成
claude --worktree --tmux

# 指定分支
claude --worktree --branch feature/new-feature

3. 权限管理

# 查看权限设置
claude permissions

# 配置权限规则
claude permissions add-rule --allow "npm *"
claude permissions add-rule --deny "rm -rf *"

# 绕过权限模式
claude --bypass-permissions

4. 计划模式

# 进入计划模式
claude --plan

# 批准计划
> 计划：执行3个步骤
> 批准

配置管理

# 编辑配置
claude settings edit

# 重置配置
claude settings reset

# 查看当前配置
claude settings show

# 设置特定选项
claude settings set model claude-3-5-sonnet-20241022
claude settings set theme dark

开发指南

开发环境设置

# 克隆仓库
git clone https://github.com/anthropics/claude-code.git
cd claude-code

# 安装依赖
bun install

# 设置开发环境
bun run dev

# 运行测试
bun run test

# 类型检查
bun run typecheck

# 代码检查
bun run lint

项目构建

# 开发构建
bun run build:dev

# 生产构建
bun run build

# 原生构建
bun run build:native

# 打包发布
bun run package

调试

# 启用调试日志
export DEBUG=claude-code:*

# 启用性能分析
claude --profile

# 转储系统提示词
claude --dump-system-prompt

扩展开发

创建自定义工具

// src/tools/MyTool/MyTool.tsx
import { buildTool } from '../../Tool.js';
import { z } from 'zod/v4';

export function MyTool() {
  return buildTool({
    name: 'my_tool',
    description: '我的自定义工具',
    inputSchema: z.object({
      param: z.string()
    }),
    execute: async (input, context) => {
      // 工具逻辑
      return { result: 'success' };
    }
  });
}

创建自定义技能

// src/skills/bundled/mySkill.ts
export const mySkill = {
  name: 'mySkill',
  description: '我的自定义技能',
  execute: async (context) => {
    // 技能逻辑
  }
};

创建自定义插件

// 插件配置
{
  "name": "my-plugin",
  "version": "1.0.0",
  "tools": ["./tools"],
  "skills": ["./skills"],
  "commands": ["./commands"]
}

架构特点

1. 模块化设计

清晰的模块边界
低耦合高内聚
易于扩展和维护

2. 类型安全

全面的TypeScript类型定义
编译时错误检查
智能代码补全

3. 响应式状态管理

统一的状态管理
响应式UI更新
状态持久化

4. 插件化架构

工具系统插件化
技能系统插件化
命令系统插件化

5. 安全性设计

多层权限控制
沙箱执行环境
命令安全验证

6. 性能优化

懒加载机制
缓存策略
流式处理

常见问题

安装问题

Q: 安装后找不到claude命令？

# 检查PATH环境变量
echo $PATH

# 手动添加到PATH
export PATH="$HOME/.local/bin:$PATH"

# 或重启终端

Q: 权限被拒绝？

# macOS
sudo chown -R $(whoami) ~/.local/bin/claude

# Linux
sudo chmod +x ~/.local/bin/claude

使用问题

Q: API调用失败？

# 检查API密钥
claude auth status

# 重新登录
claude auth login

# 检查网络连接
curl -I https://api.anthropic.com

Q: 性能问题？

# 使用快速模式
claude --fast

# 减少上下文
claude --max-tokens 4096

# 禁用某些功能
claude --no-compact

更新和维护

自动更新

# 检查更新
claude --update

# 自动更新（如果启用）
# 会在启动时自动检查并提示更新

手动更新

# 使用安装器更新
curl -fsSL https://claude.ai/install.sh | bash

# 或重新安装
npm install -g @anthropic-ai/claude-code@latest

卸载

# 使用npm卸载
npm uninstall -g @anthropic-ai/claude-code

# 手动清理
rm -rf ~/.config/claude-code
rm -rf ~/.local/share/claude-code
rm ~/.local/bin/claude

社区和资源

官方文档: https://docs.anthropic.com
GitHub仓库: https://github.com/anthropics/claude-code
问题反馈: https://github.com/anthropics/claude-code/issues
Discord社区: https://discord.gg/anthropic

许可证

本项目采用商业许可证，具体请查看项目根目录的LICENSE文件。

贡献指南

欢迎贡献代码！请遵循以下步骤：

Fork本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启Pull Request

代码规范

使用TypeScript编写代码
遵循项目的ESLint规则
编写单元测试
更新相关文档

注意: 本文档基于代码分析生成，具体功能请以官方文档为准。

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
src		src
README.md		README.md
SKILL_ARCHITECTURE_ANALYSIS.md		SKILL_ARCHITECTURE_ANALYSIS.md

Folders and files

Latest commit

History

Repository files navigation

Claude Code 项目架构分析

项目概述

架构分析

🏗️ 混合架构设计

1. 主要作为客户端工具

2. 内置服务器组件

3. 远程客户端能力

架构图

技术架构

核心技术栈

项目结构详解

安装和部署

系统要求

安装方式

方式1：官方安装器（推荐）

方式2：源码编译安装

方式3：开发模式安装

安装位置

环境配置

使用指南

基本使用

1. 启动交互式会话（客户端模式）

2. 非交互式模式

3. MCP服务器模式（服务模式）

主要功能命令

文件操作

命令执行

多代理协作

插件和技能

技能系统详解

技能架构

技能定义格式

内置技能详解

1. verify 技能

2. simplify 技能

3. remember 技能

4. skillify 技能

5. batch 技能

6. loop 技能

7. stuck 技能

8. debug 技能

9. keybindings 技能

创建自定义技能

项目级技能

用户级技能

技能调用方式

1. 斜杠命令调用

2. 自然语言调用

3. 自动调用

技能高级特性

1. 权限控制

2. 执行上下文

3. 模型指定

4. 代理指定

5. 钩子系统

技能开发最佳实践

1. 命名规范

2. 描述编写

3. 步骤设计

4. 权限管理

5. 错误处理

技能文件位置

技能管理命令

技能与插件的对比

MCP 技能集成

高级功能

1. 远程会话

2. 工作树模式

3. 权限管理

4. 计划模式

配置管理

开发指南

开发环境设置

项目构建

调试

扩展开发

Packages