# learn-claude-code

**Repository Path**: creaks_admin/learn-claude-code

## Basic Information

- **Project Name**: learn-claude-code
- **Description**: 用 java 来帮你理解 Claude Code
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-07
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 手写 AI Coding Agent —— 从零构建 Claude Code 核心机制

> 配套视频课程源码。12 个章节，每个章节一个独立 tag，逐步叠加，最终实现完整的 AI 编程代理。

## 项目定位

Claude Code 是目前最强的 AI 编码工具之一。本课程**不教你"怎么用" Claude Code**，而是带你**手写一个 Claude Code**——把它的核心机制逐个拆解，用 Java 重新实现。

每章先理解 Python 参考实现，再手写 Java 版，最后跑测试验证。

## 章节导航

| Tag | 章节 | 核心机制 | 一句话 |
|-----|------|---------|--------|
| `v01-agent-loop` | s01 | Agent Loop | 模型接收输入 → 决定调哪个工具 → 执行 → 送回结果 → 循环 |
| `v02-tool-use` | s02 | Tool Use | 分发表模式：多工具共存，模型自行选择，代码只负责路由 |
| `v03-todo-write` | s03 | TodoWrite | 用 TodoManager 让模型跟踪自己的进度，遗忘时自动提醒 |
| `v04-subagent` | s04 | Subagent | 模型可以孵化子代理去独立探索或执行任务 |
| `v05-skill-loading` | s05 | Skill Loading | 动态加载 SKILL.md，注入系统提示词扩展模型能力 |
| `v06-context-compact` | s06 | Context Compaction | 对话太长时自动压缩，保持上下文窗口不溢出 |
| `v07-task-system` | s07 | Task System | 文件持久化的任务管理，支持依赖关系和状态流转 |
| `v08-background-tasks` | s08 | Background Tasks | 后台线程执行耗时命令，完成后异步通知 |
| `v09-agent-teams` | s09 | Agent Teams | 多个 Agent 通过消息总线协作，各自独立运行 |
| `v10-team-protocols` | s10 | Team Protocols | 关闭协议 + 计划审批，保证团队有序协作 |
| `v11-autonomous-agents` | s11 | Autonomous Agents | 空闲时自动认领任务，实现自主工作循环 |
| `v12-worktree-isolation` | s12 | Worktree Isolation | 任务级文件系统隔离，多个 Agent 互不干扰 |

## 技术栈

| 组件 | 选型 | 原因 |
|------|------|------|
| 语言 | Java 17 | 纯手写，不用 Lombok |
| HTTP 客户端 | OkHttp 4 | 轻量、支持 SSE |
| JSON | Jackson 2 | 标准选择 |
| 测试 | JUnit 5 | |
| LLM | DeepSeek v4（Anthropic 兼容 API） | 国内可用，格式与 Claude API 一致 |
| 构建 | Maven | |

## 快速开始

```bash
# 1. 克隆项目
git clone https://gitee.com/creaks_admin/learn-claude-code.git
cd learn-claude-code

# 2. 查看所有章节 tag
git tag -l

# 3. 切换到你想学的章节（示例：第 2 章）
git checkout v02-tool-use

# 4. 配置 API Key
cp .env.example .env
# 编辑 .env，填入你的 ANTHROPIC_API_KEY

# 5. 编译运行
mvn compile
mvn exec:java -Dexec.mainClass="com.tianji.s01.AgentLoop"

# 6. 运行测试
mvn test
```

### Tag 使用说明

每个章节对应一个 Git tag（如 `v01-agent-loop`）。Tag 和分支的区别：

| | Git Tag | Git Branch |
|------|------|------|
| 能 `git checkout` 吗 | 能 | 能 |
| 能运行代码吗 | 能 | 能 |
| 能提交修改吗 | **不能**（只读快照） | 能 |

**只读查看+运行：**

```bash
git checkout v02-tool-use       # 切到第 2 章的只读快照
mvn test                         # 跑测试，代码可正常运行
```

**想在上面改代码实验：**

```bash
git checkout -b my-s02 v02-tool-use  # 基于 tag 创建自己的分支
# 自由修改代码...
git commit -m "我的实验"
```

**想看最新代码（包含所有章节）：**

```bash
git checkout master
```

## 项目结构

```
src/
├── main/java/com/tianji/
│   ├── client/              # 可复用的 API 客户端（跨章节共享）
│   │   ├── ClaudeClient.java    # Anthropic Messages API HTTP 客户端
│   │   ├── ClaudeConfig.java    # .env → 配置对象
│   │   ├── EnvLoader.java       # 零依赖 .env 解析器
│   │   └── model/               # 请求/响应数据模型
│   ├── s01/AgentLoop.java       # 第 1 章
│   ├── s02/ToolUse.java         # 第 2 章
│   └── ...                      # 后续章节
│
└── test/java/com/tianji/
    ├── client/ClaudeClientTest.java
    ├── s01/AgentLoopTest.java
    └── s02/ToolUseTest.java
```

## 核心设计

每个章节**自包含**：一个 main class 即可运行。底层共享 `ClaudeClient`（HTTP 通信 + JSON 解析），上层各自定义工具和分发表。

```
main()
  └─ agentLoop()              ← 核心循环（每章都一样）
       ├─ client.chat()       ← HTTP 通信（共享）
       ├─ HANDLERS.get(name)  ← 分发表路由（每章扩展）
       └─ 工具执行             ← 真正的代码（每章不同）
```

## 环境变量

`.env` 文件（不提交到 Git）：

```
ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
ANTHROPIC_API_KEY=sk-your-api-key-here
ANTHROPIC_MODEL=deepseek-v4-pro[1m]
CLAUDE_DEBUG=true    # 可选：开启后打印完整的请求/响应 JSON
```

## 学习建议

1. 从 `v01-agent-loop` 开始，按 tag 顺序递进
2. 每个 tag 的代码是那个章节的**最终状态**，可以直接运行
3. 如果某个章节有 Python 参考实现，在 `learn-claude-code/agents/` 目录下
4. 开启 `CLAUDE_DEBUG=true` 可以看到每次 API 调用的完整 JSON

## 许可

MIT