Claude Code 从零复刻教程 - 完整大纲

本教程面向有 JavaScript 基础的开发者，通过 12 篇系列文章，从零构建一个类似 Claude Code 的 AI 编程助手 CLI 工具。

---

目录

• 教程简介
• 技术栈
• 系列大纲
• 每篇教程结构
• 学习路径

---

教程简介

什么是 Claude Code？

Claude Code 是 Anthropic 官方推出的命令行工具，可以让开发者通过终端与 Claude AI 进行自然语言交互，辅助完成编程任务。它具有以下核心能力：

能力	说明
CLI 交互	在终端中通过自然语言与 AI 对话
工具调用	AI 可以读写文件、执行命令、搜索代码
多智能体	多个 AI Agent 协同工作
长期记忆	跨会话记住项目上下文

教程目标

完成本系列教程后，你将：

• 理解 AI CLI 工具的核心架构
• 掌握 TypeScript + Node.js 构建 CLI 的最佳实践
• 实现一个功能完整的 AI 编程助手
• 为参与开源或开发自己的 AI 工具奠定基础

受众要求

要求	说明
JavaScript 基础	熟悉 ES6+ 语法
命令行基础	会使用终端
TypeScript	教程中会讲解，但有 JS 基础可快速上手
API Key	需要准备 Anthropic API Key（免费注册）

---

技术栈

类别	技术	版本	说明
语言	TypeScript	5.x	类型安全、易于调试
运行时	Node.js	20+	ESM + TS 原生支持
包管理	npm	10+	生态成熟
AI 能力	Anthropic SDK	最新	Claude API 封装
CLI 框架	Commander.js	12.x	参数解析
输出美化	picocolors	1.x	彩色终端输出
存储	文件系统	-	轻量无需 DB
测试	Vitest	2.x	快速轻量

---

系列大纲

---

阶段一：CLI 核心框架

第 1 篇：项目初始化与 CLI 骨架

核心内容：

• 项目目录结构设计
• TypeScript 配置（tsconfig.json）
• Commander.js 入门
• 入口文件架构
• 打印彩色输出

交付物： 最小可运行的 CLI 工具 my-claude

# 完成后可运行
my-claude --help
# 输出帮助信息

文件结构：

my-claude/
├── src/
│   ├── main.ts          # 入口
│   └── index.ts         # 导出
├── package.json
├── tsconfig.json
└── README.md

---

第 2 篇：REPL 循环实现

核心内容：

• 标准输入输出（readline 模块）
• 消息队列设计
• 用户输入处理
• 退出机制
• 彩色提示符

交付物： 可交互的命令行界面

my-claude
# 显示彩色提示符
# 等待用户输入
# 循环处理...
# 输入 /exit 退出

关键代码模式：

const rl = readline.createInterface({
  input: process.stdin,
  output: process.stdout,
  prompt: chalk.blue('claude> ')
});

rl.prompt();
rl.on('line', async (input) => {
  await processInput(input.trim());
  rl.prompt();
});

---

第 3 篇：参数解析与配置管理

核心内容：

• 命令行参数解析（–api-key, --model 等）
• 环境变量配置
• settings.json 配置文件
• API Key 安全管理
• 配置优先级

交付物： 完整的配置系统

my-claude --api-key sk-ant-xxx --model claude-sonnet
# 或通过环境变量
ANTHROPIC_API_KEY=sk-ant-xxx my-claude
# 或通过配置文件

配置文件结构：

// ~/.my-claude/settings.json
{
  "apiKey": "sk-ant-xxx",
  "model": "claude-sonnet-4-20250514",
  "maxTokens": 8192
}

---

阶段二：对话系统

第 4 篇：Anthropic API 集成

核心内容：

• Anthropic SDK 安装与配置
• API 调用流程
• 消息格式
• 流式响应
• 错误处理
• 重试机制

交付物： 能对话的 CLI

my-claude
# claud> 解释什么是闭包
# [AI 回复...]

核心代码：

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({ apiKey });

const message = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Hello!' }]
});

---

第 5 篇：七层 System Prompt 架构

核心内容：

• 七层设计理念
• 身份定义层
• 系统约束层
• 任务规范层
• 安全准则层
• 工具使用层
• 沟通规范层
• 静态/动态分层优化

交付物： 模块化的 Prompt 系统

Prompt 结构图：

┌─────────────────────────────────────────┐
│  Layer 7: 动态上下文（记忆/MCP/语言）       │ ← 每次请求重建
├─────────────────────────────────────────┤
│  Layer 6: 沟通规范                       │
├─────────────────────────────────────────┤
│  Layer 5: 工具使用指导                   │
├─────────────────────────────────────────┤
│  Layer 4: 安全准则                       │
├─────────────────────────────────────────┤
│  Layer 3: 任务规范                       │
├─────────────────────────────────────────┤
│  Layer 2: 系统约束                       │
├─────────────────────────────────────────┤
│  Layer 1: 身份定义                       │ ← 全局缓存
└─────────────────────────────────────────┘

---

第 6 篇：对话上下文管理

核心内容：

• 消息历史管理
• Token 计数
• 上下文窗口限制
• 消息截断策略
• 对话状态持久化
• 上下文压缩

交付物： 完整对话体验

interface ConversationContext {
  messages: Message[];
  totalTokens: number;
  maxTokens: number;
}

function manageContext(ctx: ConversationContext, newMsg: Message): void {
  ctx.messages.push(newMsg);
  ctx.totalTokens += countTokens(newMsg);
  while (ctx.totalTokens > ctx.maxTokens) {
    ctx.messages.shift();
    ctx.totalTokens = recalculate(ctx.messages);
  }
}

---

阶段三：工具系统

第 7 篇：工具注册与调用机制

核心内容：

• 工具接口定义
• 注册表模式
• 动态工具注册
• Tool Use 规范
• 工具参数验证
• 调用结果处理

交付物： 工具执行框架

工具接口：

interface Tool {
  name: string;
  description: string;
  input_schema: JSONSchema;
  execute: (params: unknown) => Promise<ToolResult>;
}

class ToolRegistry {
  private tools: Map<string, Tool>;
  register(tool: Tool): void;
  get(name: string): Tool | undefined;
  list(): Tool[];
}

---

第 8 篇：基础工具实现

核心内容：

• ReadFileTool：读取文件内容
• WriteFileTool：写入文件
• GlobTool：模式匹配文件
• BashTool：执行 shell 命令
• 工具权限控制
• 执行超时处理

交付物： 实际可用的文件操作工具

四个核心工具：

工具	命令	说明
Read	Read: filePath	读取文件
Write	Write: filePath, content	写入文件
Glob	Glob: pattern	搜索文件
Bash	Bash: command	执行命令

---

阶段四：Agent Teams

第 9 篇：多智能体协作框架

核心内容：

• Agent 概念与生命周期
• TeamCreateTool 实现
• SendMessageTool 实现
• 任务分发机制
• 进程内 vs 进程外 Agent
• 状态同步

交付物： 多 Agent 基础设施

架构图：

         用户
           │
           ▼
      ┌─────────┐
      │ TeamLead │ ← 主 Agent
      └────┬────┘
           │ 分配任务
     ┌─────┼─────┐
     ▼     ▼     ▼
  ┌─────┐ ┌─────┐ ┌─────┐
  │ Ag1 │ │ Ag2 │ │ Ag3 │ ← 队友 Agent
  └─────┘ └─────┘ └─────┘

---

第 10 篇：内置 Agent 实现

核心内容：

• ExploreAgent：代码探索专家
• PlanAgent：架构规划专家
• VerificationAgent：质量验证专家
• Agent 提示词设计
• Agent 间通信
• 结果汇总

交付物： 专业化的 Agent 角色

Agent 类型：

Agent	角色	特点
Explore	搜索专家	只读、并行、高效
Plan	规划专家	结构化输出、深度分析
Verification	验证专家	对抗测试、质量把控

---

阶段五：记忆系统

第 11 篇：长期记忆存储

核心内容：

• 四种记忆类型（user/feedback/project/reference）
• 记忆文件格式（YAML frontmatter）
• 存储路径设计
• 记忆索引（MEMORY.md）
• 记忆提取机制
• 安全存储

交付物： 记忆持久化系统

记忆类型：

类型	作用域	内容
user	私有	用户偏好、角色、职责
feedback	私有/团队	反馈规则、已知问题
project	私有/团队	项目约定、决策历史
reference	团队	共享文档、API 参考

存储结构：

~/.my-claude/
└── projects/
    └── <项目路径>/
        └── memory/
            ├── MEMORY.md      # 索引入口
            ├── user_role.md
            ├── feedback.md
            ├── project_arch.md
            └── reference_api.md

---

第 12 篇：Auto Dream 自动整合

核心内容：

• Fork Agent 模式
• 后台记忆整合
• 整合触发条件
• 四阶段整合流程（Orient/Gather/Consolidate/Prune）
• 定时任务调度
• 整合锁机制

交付物： 智能记忆管理

整合流程：

1. Orient:    了解当前记忆状态
2. Gather:    收集新会话数据
3. Consolidate: 合并新旧记忆
4. Prune:     清理过期内容

---

学习路径

推荐顺序

第1周：CLI 基础
├── 第 1 篇：项目初始化
├── 第 2 篇：REPL 循环
└── 第 3 篇：配置管理

第2周：对话核心
├── 第 4 篇：API 集成
├── 第 5 篇：Prompt 架构
└── 第 6 篇：上下文管理

第3周：工具系统
├── 第 7 篇：工具框架
└── 第 8 篇：基础工具

第4周：高级功能
├── 第 9 篇：Agent Teams
└── 第10篇：内置 Agent

第5周：记忆系统
├── 第11篇：记忆存储
└── 第12篇：自动整合

快速路径

如果你只想快速体验核心功能：

1. 第 1 篇：项目初始化
2. 第 4 篇：API 集成
3. 第 7 篇：工具框架
4. 第 8 篇：基础工具

完成这 4 篇后，你就拥有了一个最小可用的 AI 编程助手！

---

附录

A. Claude Code 源码参考

本教程部分设计参考 Claude Code 源码：

模块	源码位置	教程对应
CLI 入口	src/main.tsx	第 1-3 篇
对话系统	src/src/buddy/	第 4-6 篇
工具系统	src/src/tools/	第 7-8 篇
Agent Teams	src/src/tasks/	第 9-10 篇
记忆系统	src/src/memdir/	第 11-12 篇

B. 术语表

术语	解释
REPL	Read-Eval-Print Loop，交互式解释器
Tool Use	AI 调用外部工具的能力
System Prompt	系统提示词，定义 AI 行为
Token	文本处理单位，API 计费依据
Fork Agent	从当前会话分离的独立 Agent

C. 相关资源

• Anthropic API 文档
• TypeScript 官方文档
• Commander.js 文档
• Claude Code 源码