从0到1构建 Claude Code 风格的 AI Coding Agent
这是一个渐进式学习项目，用 TypeScript 从零开始构建一个完整的 AI 编程代理。我们将逐步实现 Claude Code 的所有核心机制：
本项目灵感来自 learn-claude-code（59.7k ⭐），原项目 Agent 核心由 Python 实现，本项目使用 TypeScript 重写 Agent 逻辑本身，目前已完成 s01–s09，持续更新中。适合希望在 Node.js / TypeScript 生态中深入理解 Harness 工程的开发者。
- 核心循环
- 工具系统
- 任务规划
- 上下文压缩
- 多代理协作
- 工作树隔离
核心理念：智能来自模型训练，Harness（套件）只是让智能得以表达的载体。我们构建的是载体，不是智能本身。
| 阶段 | Session | 主题 | 核心概念 |
|---|---|---|---|
| 1 | s01 | Agent Loop | 一个循环 + Bash = Agent |
| 1 | s02 | Tool Use | 添加工具 = 添加一个 handler |
| 2 | s03 | TodoWrite | 没有计划的代理会迷失方向 |
| 2 | s04 | Subagent | 大任务拆分，子任务获得干净的上下文 |
| 2 | s05 | Skills | 按需加载知识，不要 upfront |
| 3 | s06 | Context Compact | 三层压缩策略实现无限会话 |
| 3 | s07 | Permission System | 工具执行前的安全检查管道 |
| 3 | s08 | Hook System | 不改主循环也能在固定时机插入行为 |
| 4 | s09 | Memory System | 跨会话保存有价值的信息 |
| 4 | s10 | System Prompt | 动态组装系统提示词 |
| 4 | s11 | Error Recovery | 错误分类 + 恢复路径 |
| 5 | s12 | Task System | 文件持久化任务板 + 依赖图 |
| 5 | s13 | Background Tasks | 后台执行 + 通知队列 |
| 5 | s14 | Cron Scheduler | 定时任务调度 |
| 6 | s15 | Agent Teams | JSONL 邮箱通信的多代理 |
| 6 | s16 | Team Protocols | 关闭/审批协议 |
| 6 | s17 | Autonomous Agents | 代理自动发现任务 |
| 6 | s18 | Worktree Isolation | 目录级隔离执行 |
| 7 | s19 | MCP Plugin | 模型上下文协议插件 |
| 8 | s_full | Full Agent | 所有机制整合 |
- Node.js >= 20
- pnpm >= 10
pnpm install复制 .env.example 为 .env，填入你的 API 配置：
ANTHROPIC_API_KEY=your-api-key-here
MODEL_ID=claude-sonnet-4-20250514# 运行 s01 - 基础 Agent Loop
pnpm s01
# 运行其他 session
pnpm s02
pnpm s03
# ...
# 运行完整代理
pnpm full整个项目的核心就是一个简单的循环：
async function agentLoop(messages: Message[]): Promise<void> {
while (true) {
const response = await client.messages.create({
model: MODEL,
system: SYSTEM,
messages: messages,
tools: TOOLS,
})
messages.push({ role: 'assistant', content: response.content })
if (response.stop_reason !== 'tool_use') {
return // 模型决定停止
}
const results = await executeTools(response.content)
messages.push({ role: 'user', content: results })
// 循环继续...
}
}模型决定何时调用工具、何时停止。代码只执行模型的请求。
build-claude-code/
├── src/
│ ├── index.ts # 入口文件
│ ├── core/ # 核心模块 (s01-s02)
│ │ ├── agent-loop.ts # 核心循环
│ │ ├── tools.ts # 工具系统
│ │ └── types.ts # 类型定义
│ ├── planning/ # 计划模块 (s03-s05)
│ ├── persistence/ # 持久化模块 (s06-s14)
│ │ ├── compact.ts # s06: 上下文压缩
│ │ ├── permission.ts # s07: 权限系统
│ │ ├── hook.ts # s08: Hook 系统
│ │ ├── memory.ts # s09: 记忆系统
│ │ ├── prompt.ts # s10: 系统提示词
│ │ ├── recovery.ts # s11: 错误恢复
│ │ ├── task-manager.ts # s12: 任务系统
│ │ ├── background.ts # s13: 后台任务
│ │ └── cron.ts # s14: 定时调度
│ ├── team/ # 团队模块 (s15-s18)
│ ├── plugin/ # 插件模块 (s19)
│ ├── full/ # 综合实现
│ └── sessions/ # 各 session 入口
├── learn/
│ ├── 00-project-setup.md # 项目初始化笔记
│ ├── 01-agent-loop.md # s01 学习笔记
│ ├── ... # 每个 session 的学习笔记
│ └── output/ # 公众号文章输出
├── skills/ # 技能文件目录
├── package.json
├── tsconfig.json
├── eslint.config.mjs
├── .prettierrc
└── .env.example
| 工具 | 版本 | 说明 |
|---|---|---|
| TypeScript | 6.0 | 主要语言 |
| tsdown | 0.21 | 现代化构建工具 |
| tsx | 4.21 | 开发时直接运行 TS |
| pnpm | 10 | 包管理 |
| @anthropic-ai/sdk | 0.90 | Anthropic 官方 SDK |
| ESLint | 10 | 代码检查 |
| Prettier | 3.8 | 代码格式化 |
pnpm dev # 开发模式
pnpm build # 构建
pnpm typecheck # 类型检查
pnpm lint # ESLint 检查
pnpm lint:fix # ESLint 自动修复
pnpm format # Prettier 格式化
pnpm format:check # Prettier 检查- learn-claude-code - Python 参考实现
- Claude Code 官方文档
- Kode CLI - 开源实现
- 无分号
- 单引号
- 尾逗号
MIT