5分钟从零跑通第一个Coding Agent：claude-code-from-scratch快速上手完整指南（免API key演示）-创锋一号

5分钟从零跑通第一个Coding Agent：claude-code-from-scratch快速上手完整指南（免API key演示）

【免费下载链接】claude-code-from-scratchBuild your own Claude Code from scratch. 🔍 Claude Code 开源了 50 万行代码，读不动？用 ~5000 行 TypeScript / Python 从零复现核心架构，11 章分步教程带你理解 coding agent 精髓项目地址: https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch

想搞懂Coding Agent（编程智能体）到底是怎么自己读文件、改代码、跑测试的，又不想啃 Claude Code 那五十多万行源码？claude-code-from-scratch用一个约 5000 行的 TypeScript / Python 极简实现，把 Coding Agent 的核心架构（Agent Loop、工具系统、上下文压缩、记忆、多 Agent、MCP 集成）一步步复现出来。最棒的是：每一章都能一条命令跑起来，而且完全免 API key（本地 mock 模型驱动、不联网），输出确定可复现。本指南带你 5 分钟克隆项目、装好依赖、跑通第一个能真正动手干活的 Coding Agent。

🎯适合谁看：刚接触 AI Agent / LLM 应用的新手、想用几百行代码看懂 Coding Agent 原理的开发者、想找一个能"边跑边读"的学习项目的同学。

一、这个项目到底做什么

一句话：用最小代码，把"会自己干活的编程 Agent"从循环搭建起来。

传统聊天机器人只能"给建议"——它给一段代码，但跑不了测试、看不到报错、没法根据结果再改一版。Coding Agent 迈过了这道坎：靠一个循环不断「调模型 → 执行工具 → 把结果喂回去 → 继续」，直到任务完成。

claude-code-from-scratch 正是把这个核心拎出来，用一块一块、可单独运行的方式重建：起点是十几行只会聊天的循环，每加一章就补一块能力，最后长成一个能读写文件、跑 Shell、自动压缩上下文、带记忆和子 Agent 的完整 Agent。

它不是一个玩具 demo，而是一份分步教程：13 章主线 + 2 章测试/自治，TypeScript 与 Python 双语言互为镜像，每章都对着真实 Claude Code 讲清"最小实现 vs 生产级"的差异。

二、环境准备（1 分钟）

两种方式，任选其一即可，依赖少到一眼能看完。

版本	需要	说明
TypeScript 版	Node.js 18+、npm	与 Claude Code 同语言，推荐
Python 版	Python 3.11+、pip	更简洁易读，功能一致

先确认一下版本：

node -v # TypeScript 版需要 Node 18+ python3 --version # Python 版需要 3.11+

三、克隆项目并安装依赖

git clone https://gitcode.com/gh_mirrors/cl/claude-code-from-scratch.git cd claude-code-from-scratch npm install # TypeScript 版安装依赖（首次约 1 分钟）

💡 想用 Python 版：安装完依赖后进入 python/ 目录执行pip install -e .即可。

四、5 分钟跑通：免 API key 的演示 🚀

这是全文最重要的部分——不用注册、不用填 key，直接看真实代码跑起来。

项目里每一章都配了一份"能单独跑的最小实现"，由本地 mock 模型回放一个脚本化场景，输出稳定、可复现。命令都在 steps/ 目录下，入口是 steps/run.mjs。

第 1 步：看看有哪些能跑的章节

node steps/run.mjs --list

第 2 步：跑一个章节演示（无需 key）

node steps/run.mjs 7 # 第 7 章：对话变长了，它把旧消息压成摘要

你会看到它真的在工作（终端会打印▶ step 7 demo (no API key — local mock model)这样的提示）。

第 3 步：看这一章比上一章多了哪几行代码

node steps/run.mjs 7 --diff

第 4 步：换成 Python 版

node steps/run.mjs 7 --py

常用参数	作用
`--list`	列出所有可运行的章节
`--diff`	对比本章相对上一章新增的代码
`--py`	运行 Python 版本
`--live`	连接真实模型（需要配置 API key）

📌原理：演示用的是"单一真源"生成出的自包含快照——文档里贴的代码块、跑出来的输出，全来自同一份源码，不会出现"文档说的和代码对不上"的情况。

五、配置 API Key，连接真实模型（可选）

看完演示想让它真的帮你干活？只需配置一个后端。支持两种格式，通过环境变量自动识别（也支持自定义 base url）：

方式一：Anthropic 格式（推荐）

export ANTHROPIC_API_KEY="sk-ant-xxx" # 可选：使用代理/中转 export ANTHROPIC_BASE_URL="https://your-relay.com"

方式二：OpenAI 兼容格式

export OPENAI_API_KEY="sk-xxx" export OPENAI_BASE_URL="https://api.openai.com/v1"

默认模型为claude-opus-4-6，可随时切换：

export MINI_CLAUDE_MODEL="claude-sonnet-4-6" # 环境变量方式 npm start -- --model gpt-4o # 命令行方式（优先级更高）

配置好后，任意章节都可以接上自己的 prompt 连真模型试：

node steps/run.mjs 2 --live -- "create hello.txt with the text hi"

六、启动 mini-claude 交互终端

TypeScript 版

npm start # 交互式 REPL 模式（推荐） npm start -- --resume # 恢复上次会话继续对话 npm start -- --plan # Plan 模式：只分析不修改

Python 版

mini-claude-py # 交互式 REPL（避免与 TS 版命令冲突） mini-claude-py --resume # 恢复上次会话 python -m mini_claude # 或用模块方式运行

启动后进入命令行交互：

Mini Claude Code — A minimal coding agent Commands: /clear /cost /compact /memory /skills /plan >

常用命令行开关（对应的实现在后面章节逐个拆解）：

开关	作用
`--yolo`	跳过安全确认（危险命令自动执行）
`--plan`	Plan 模式：只读分析，不修改文件
`--accept-edits`	自动批准文件编辑
`--dont-ask`	CI 模式：需确认的操作自动拒绝
`--max-cost 0.50 --max-turns 20`	费用 + 轮次双重预算限制

REPL 内命令：

命令	功能
`/clear`	清空对话历史
`/cost`	显示累计 token 用量与费用估算
`/compact`	手动触发对话压缩
`/memory`	列出所有已保存的记忆
`/skills`	列出可用技能

试一句read src/agent.ts and explain the main loop，看它自己读文件、自己讲给你听。

七、核心能力一览

跑起来后你会发现，这个"最小实现"其实五脏俱全：

Agent 循环：自动调工具 → 处理结果 → 持续迭代，直到任务完成
13 个工具：读写编辑文件（带 mtime 防护）、搜索、Shell、WebFetch、技能、子 Agent、Plan Mode
4 层上下文压缩：对话再长也不撑爆窗口，>30KB 的大结果自动落盘
权限系统：5 种模式 + 声明式规则 + 16 个危险命令正则拦截
记忆系统：4 类型记忆 + 语义召回 + 异步预取
多 Agent：子 Agent fork-return，任务太大就分出去啃
MCP 集成：JSON-RPC over stdio 连接外部工具服务器
错误恢复：限流/过载时指数退避 + 随机抖动重试，Ctrl+C 优雅中断

八、去哪读代码：项目结构

代码精简到"每个文件各管一摊"，TS 版约 5500 行，Python 版约 5000 行，互为镜像：

模块	路径	管什么
Agent 主循环	src/agent.ts	消息构造、API 调用、工具编排、流式、压缩、预算
工具系统	src/tools.ts	13 工具 + mtime 防护 + 延迟加载
自治三件套	src/autonomy.ts	`/goal`评估器、`/loop`、Auto Mode 分类器
CLI 入口	src/cli.ts	参数解析、REPL 交互
记忆系统	src/memory.ts	4 类型 + 语义召回 + 异步预取
每章可运行实现	steps/	单一真源 → 生成可跑快照
Python 镜像	python/mini_claude/	与 TS 版功能一致

想深挖原理，从这份导读入手：docs/00-introduction.md。

九、继续学习：13 章路线图 📚

每一章 = 一个新能力，跟着动手写几千行代码，从零理解 Coding Agent 的工作原理：

阶段	章节	这一章之后 Agent 能……
Phase 1	1. Agent Loop	调用工具、把结果喂回自己，不再只是聊天
Phase 1	2. 工具系统	读写文件、跑 Shell、搜代码——真正动手
Phase 1	3. System Prompt	知道自己在什么系统、目录、Git 状态下干活
Phase 1	4. CLI 与会话	有交互式命令行，对话可存盘、`--resume`续聊
Phase 1	5. 流式输出	边生成边显示，支持 OpenAI 兼容后端
Phase 1	6. 权限与安全	危险操作先问一句，deny 规则拦得住越界
Phase 1	7. 上下文管理	对话太长自动压缩，跑几十轮不撑爆窗口
Phase 2	8. 记忆系统	跨会话记住偏好与项目事实
Phase 2	9. 技能系统	常用操作打包成技能，随用随调
Phase 2	10. Plan Mode	先只读出方案，批准了再动手
Phase 2	11. 多 Agent	任务太大就 fork 子 Agent 去啃
Phase 2	12. MCP 集成	接外部工具服务器，工具集向外扩展
收尾	13. 架构对比	逐项对照真实 Claude Code，看清差异在哪

十、常见问题（FAQ）

❓ 没有 API key 能跑吗？能。node steps/run.mjs <N>默认走本地 mock 模型，不联网、免 key，专门用来"看它真的转起来"。

❓ 支持哪些模型？Anthropic 格式与 OpenAI 兼容格式两种后端，默认claude-opus-4-6，可通过MINI_CLAUDE_MODEL或--model随意切换（含 gpt-4o 等）。

❓ TypeScript 和 Python 版怎么选？想贴近 Claude Code 同语言就选 TS 版（npm start）；偏好简洁易读就选 Python 版（mini-claude-py），两者功能完全一致。

❓ 演示和真实运行有什么区别？演示（默认）是回放脚本化场景、输出确定；加--live就换成你的 prompt 连真模型实时跑。

十一、加入社区交流 💬

学习路上遇到问题、想交流 Agent 设计思路？扫下方二维码加入AI Agent 工坊交流群（群号：1090526244）：

小结

claude-code-from-scratch给你一条"读得动、跑得起来"的路径理解 Coding Agent：

git clone+npm install装好依赖；
node steps/run.mjs 7免 API key 跑通演示；
想真干活就配个 key，npm start进入交互终端；
跟着 13 章教程从零把 Agent 一块块搭起来。

5000 行代码，一个循环起步，一路长到能自己干活——这就是 Coding Agent 的精髓。现在，去跑你的第一个吧 🚀

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析